shipwright-preview git:20261024.1caabdcA

Immutable. This exact content never changes and is served at /api/v1/blob/0b6878e00be850d2.

---
name: shipwright-preview
description: "Start local dev server and show browser preview URL. Available after first build split.\nTRIGGER when: user wants to see the app, preview changes, check the UI, open the browser, show me the app, start the dev server, or view the running application.\nDO NOT TRIGGER when: user asks to write code, run tests, deploy, or any other SDLC phase."
license: MIT
compatibility: Requires Node.js and project dependencies installed (npm install).
---

# SHIPWRIGHT-PREVIEW — Local Browser Preview

Start the development server and show the preview URL so the user can open the app in their browser.

## CRITICAL: First Actions

### A. Print Intro Banner

```
╔══════════════════════════════════════════════╗
║           SHIPWRIGHT-PREVIEW                 ║
║                                              ║
║  Usage:                                      ║
║    /shipwright-preview                       ║
║    "show me the app"                         ║
║    "preview"                                 ║
╚══════════════════════════════════════════════╝
```

### B. Run Checks and Start Preview

Execute these checks in order. Stop at the first failure and help the user fix it.

#### Step 1: Build Check

Check if `shipwright_build_config.json` exists in the project root and has at least one section with `"status": "complete"`.

- **If no build config or no complete sections:** Tell the user:
  > "Preview is not available yet. Complete at least one build split first (`/shipwright-build`)."
  
  Stop here.

#### Step 2: Environment Check

Run the shared environment validator:

```bash
uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/validate_env.py" \
  --project-root ${SHIPWRIGHT_PROJECT_ROOT} \
  --phase build
```

- **If validation fails (missing env vars; but `error` / `kind` / exit 2-3 is a profile problem: stop and show the message, do not ask for env vars or edit `.env.local`):** Do NOT just tell the user to "check logs". Instead, actively help them create or fix `.env.local`. Read the error output, identify which variables are missing, and guide them through setting the values.

#### Step 3: Dev Server Status

Check if the dev server is already running:

```bash
uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/dev_server.py" \
  status --cwd ${SHIPWRIGHT_PROJECT_ROOT}
```

Parse the JSON output. If `"running": true`, skip to Step 5.

#### Step 4: Start Dev Server

Start the dev server using the project's own stack profile. Read `profile` from
`${SHIPWRIGHT_PROJECT_ROOT}/shipwright_run_config.json` (do not assume a stack). The name
must match `^[a-z0-9][a-z0-9-]*$` and exist as `shared/profiles/{profile}.json`; otherwise stop:

```bash
uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/dev_server.py" \
  start --profile "{profile}" --cwd ${SHIPWRIGHT_PROJECT_ROOT}
```

Parse the JSON output:
- `"no_dev_server": true` → the profile declares no web dev server (a library,
  CLI or plugin project). Tell the user there is nothing to preview and stop.
- `"ready": true` → proceed to Step 5
- `"ready": false` or error → investigate. Read the server logs, check for port conflicts, missing dependencies, or build errors. Fix the issue and retry. Do not just report the error — help resolve it.

#### Step 5: Show Preview URL

Display the preview URL prominently:

```
┌────────────────────────────────────────────┐
│  Preview running at:                       │
│  http://localhost:{port}                   │
│                                            │
│  Open this URL in your browser.            │
│  The server stays running until you stop   │
│  it or end the session.                    │
└────────────────────────────────────────────┘
```

The port comes from the dev server status output (it is whatever the profile's dev server declares; do not assume 3000).

## Stopping the Preview

The user can ask to stop the preview at any time in chat (e.g., "stop preview", "kill the server"). When asked:

```bash
uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/dev_server.py" \
  stop --cwd ${SHIPWRIGHT_PROJECT_ROOT}
```

The dev server also stops automatically when the Claude Code session ends (state file cleanup).

## Profile Extensibility

Preview uses the `dev_server` configuration from the stack profile JSON (`shared/profiles/{profile}.json`). When adding a new stack profile (e.g., SQLite + Flask, or Postgres + Django), define the `dev_server` section:

```json
{
  "dev_server": {
    "command": "npm run dev",
    "port": 3000,
    "ready_timeout_seconds": 60,
    "ready_path": "/"
  }
}
```

The `dev_server.py` shared script reads this configuration automatically. No changes to the preview plugin are needed for new stacks — only the profile JSON.