---
name: run-ui
description: Start the project's Vite UI dev server on port 4300 in the background, surfacing the URL once it's ready. Detects port conflicts and asks before killing the holder.
---

# Run UI

Start `ui/` dev server (`pnpm -C ui dev`) in the background on port 4300 and surface the URL when Vite reports ready.

**Usage:** `/run-ui`

The Vite config in `ui/vite.config.ts` pins port 4300 with `strictPort: true`, so a conflict is a hard fail — the skill resolves the conflict before launching.

## Process

### Step 1: Probe port 4300

Run via PowerShell tool (Windows-native, cleanest):

```powershell
$conn = Get-NetTCPConnection -LocalPort 4300 -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1
if ($conn) {
  $proc = Get-Process -Id $conn.OwningProcess -ErrorAction SilentlyContinue
  $cmd = (Get-CimInstance Win32_Process -Filter "ProcessId = $($conn.OwningProcess)" -ErrorAction SilentlyContinue).CommandLine
  "PID=$($conn.OwningProcess) NAME=$($proc.ProcessName) CMD=$cmd"
} else {
  "FREE"
}
```

### Step 2: Branch on probe result

- **`FREE`** → go to Step 3.
- **Holder is our Vite** (CMD contains `vite` or `node` running from this project's `ui/`) → port is already serving the app. Skip launch and surface `http://localhost:4300/` directly. Done.
- **Holder is something else** → ask the user:

  > "Port 4300 is held by `<NAME>` (PID `<PID>`). Kill it and start the dev server? (y/n)"

  On `n`, abort with no further action. On `y`, run `Stop-Process -Id <PID> -Force` then continue to Step 3.

### Step 3: Launch dev server in background

Use Bash tool with `run_in_background: true`:

```bash
pnpm -C ui dev
```

Capture the returned shell ID.

### Step 4: Wait for ready signal

Poll the background shell output (read every ~2s) for Vite's ready line — typically:

```
  ➜  Local:   http://localhost:4300/
```

or `ready in <N>ms`.

Stop polling on the first match. Hard cap: ~15 seconds (≈7 reads). If no ready signal arrives, surface the last 20 lines of background output so the user can debug, and leave the background process running.

### Step 5: Report

On success:

```
UI dev server running
  Local:  http://localhost:4300/
  Shell:  <bg-shell-id>
```

On timeout, prepend a one-line note ("Vite did not report ready within 15s — last output:") before the captured tail.
