@dfosco/storyboard-core 4.0.0-beta.5 → 4.0.0-beta.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.0.0-beta.5",
+  "version": "4.0.0-beta.7",
   "type": "module",
   "license": "MIT",
   "bin": {

package/src/cli/canvasRead.js

@@ -0,0 +1,212 @@
+/**
+ * storyboard canvas read — Read canvas state and list widgets with their IDs, URLs, and content.
+ *
+ * Usage:
+ *   storyboard canvas read my-canvas             List all widgets
+ *   storyboard canvas read my-canvas --json      Output as JSON
+ *   storyboard canvas read my-canvas --id abc    Get a specific widget by ID
+ *
+ * Output includes:
+ *   - Widget ID
+ *   - Widget type
+ *   - Position (x, y)
+ *   - Content (text, url, src depending on type)
+ *   - File path (for images)
+ */
+
+import * as p from '@clack/prompts'
+import { detectWorktreeName, getPort } from '../worktree/port.js'
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`
+
+function getServerUrl() {
+  const name = detectWorktreeName()
+  const port = getPort(name)
+  return `http://localhost:${port}`
+}
+
+async function checkServer() {
+  try {
+    await fetch(getServerUrl(), { signal: AbortSignal.timeout(2000) })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Extract the primary content from a widget based on its type.
+ */
+function getWidgetContent(widget) {
+  const { type, props = {} } = widget
+  switch (type) {
+    case 'sticky-note':
+      return { content: props.text || '', contentType: 'text' }
+    case 'markdown':
+      return { content: props.content || '', contentType: 'markdown' }
+    case 'prototype':
+      return { content: props.src || '', contentType: 'url', url: props.src }
+    case 'figma-embed':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'link-preview':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'image':
+      return {
+        content: props.src || '',
+        contentType: 'image',
+        url: props.src ? `/_storyboard/canvas/images/${props.src}` : '',
+        filePath: props.src ? `src/canvas/images/${props.src}` : '',
+      }
+    default:
+      return { content: JSON.stringify(props), contentType: 'props' }
+  }
+}
+
+/**
+ * Format a widget for human-readable output.
+ */
+function formatWidget(widget) {
+  const { id, type, position = {} } = widget
+  const { content, contentType, url, filePath } = getWidgetContent(widget)
+
+  const lines = []
+  lines.push(`${bold(id)} ${dim(`(${type})`)}`)
+  lines.push(`  Position: ${position.x ?? 0}, ${position.y ?? 0}`)
+
+  if (contentType === 'image') {
+    lines.push(`  File: ${cyan(filePath)}`)
+    if (content) lines.push(`  Filename: ${content}`)
+  } else if (contentType === 'url') {
+    lines.push(`  URL: ${cyan(url || content)}`)
+  } else if (content) {
+    const preview = content.length > 80 ? content.slice(0, 77) + '...' : content
+    lines.push(`  Content: ${preview}`)
+  }
+
+  return lines.join('\n')
+}
+
+async function canvasRead() {
+  const args = process.argv.slice(4)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  canvas read — Read canvas state and list widgets
+
+  Usage:
+    storyboard canvas read <canvas-name>          List all widgets
+    storyboard canvas read <canvas-name> --json   Output as JSON
+    storyboard canvas read <canvas-name> --id <widget-id>  Get specific widget
+
+  Output includes widget ID, type, position, content, URLs, and file paths.
+`)
+    process.exit(0)
+  }
+
+  // Parse args
+  let canvasName = ''
+  let outputJson = false
+  let widgetId = ''
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--json') {
+      outputJson = true
+    } else if (arg === '--id' && args[i + 1]) {
+      widgetId = args[++i]
+    } else if (!arg.startsWith('-') && !canvasName) {
+      canvasName = arg
+    }
+  }
+
+  // Check server
+  const serverUp = await checkServer()
+  if (!serverUp) {
+    p.log.error('Dev server is not running. Start it with: storyboard dev')
+    process.exit(1)
+  }
+
+  const base = getServerUrl()
+
+  // If no canvas name, list available canvases
+  if (!canvasName) {
+    try {
+      const res = await fetch(`${base}/_storyboard/canvas/list`)
+      if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
+      const data = await res.json()
+      const canvases = data.canvases || []
+
+      if (outputJson) {
+        console.log(JSON.stringify(canvases, null, 2))
+      } else {
+        if (canvases.length === 0) {
+          p.log.info('No canvases found')
+        } else {
+          console.log('\nAvailable canvases:\n')
+          for (const c of canvases) {
+            console.log(`  ${bold(c.name)} ${dim(`(${c.widgetCount} widgets)`)}`)
+          }
+          console.log('')
+        }
+      }
+    } catch (err) {
+      p.log.error(`Failed to list canvases: ${err.message}`)
+      process.exit(1)
+    }
+    return
+  }
+
+  // Read canvas state
+  try {
+    const res = await fetch(`${base}/_storyboard/canvas/read?name=${encodeURIComponent(canvasName)}`)
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`${res.status} ${res.statusText}${text ? ': ' + text : ''}`)
+    }
+    const data = await res.json()
+    const widgets = data.widgets || []
+
+    // If filtering by widget ID
+    if (widgetId) {
+      const widget = widgets.find((w) => w.id === widgetId)
+      if (!widget) {
+        p.log.error(`Widget "${widgetId}" not found in canvas "${canvasName}"`)
+        process.exit(1)
+      }
+
+      if (outputJson) {
+        const enriched = { ...widget, ...getWidgetContent(widget) }
+        console.log(JSON.stringify(enriched, null, 2))
+      } else {
+        console.log('')
+        console.log(formatWidget(widget))
+        console.log('')
+      }
+      return
+    }
+
+    // List all widgets
+    if (outputJson) {
+      const enriched = widgets.map((w) => ({ ...w, ...getWidgetContent(w) }))
+      console.log(JSON.stringify({ ...data, widgets: enriched }, null, 2))
+    } else {
+      console.log(`\n${bold(data.title || canvasName)} ${dim(`(${widgets.length} widgets)`)}\n`)
+
+      if (widgets.length === 0) {
+        console.log('  No widgets on this canvas.\n')
+      } else {
+        for (const widget of widgets) {
+          console.log(formatWidget(widget))
+          console.log('')
+        }
+      }
+    }
+  } catch (err) {
+    p.log.error(`Failed to read canvas: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+canvasRead()

package/src/cli/code.js

@@ -0,0 +1,67 @@
+/**
+ * storyboard code [branch] — Open a worktree in VS Code.
+ *
+ * Usage:
+ *   storyboard code              # open current worktree or repo root
+ *   storyboard code main         # open repo root
+ *   storyboard code <branch>     # open .worktrees/<branch>/
+ */
+
+import * as p from '@clack/prompts'
+import { execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { detectWorktreeName, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
+
+const branch = process.argv[3] || undefined
+
+p.intro('storyboard code')
+
+function openInCode(dir) {
+  try {
+    execFileSync('code', [dir], { stdio: 'inherit' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const root = repoRoot()
+
+if (!branch) {
+  // No argument — open current directory
+  const name = detectWorktreeName()
+  const dir = name === 'main' ? root : worktreeDir(name)
+  if (openInCode(dir)) {
+    p.outro(`Opened ${name === 'main' ? 'repo root' : `.worktrees/${name}/`}`)
+  } else {
+    p.log.error('Could not open VS Code. Is the `code` CLI installed?')
+    p.log.info('Run `npx storyboard setup` to install it, or open VS Code and run:')
+    p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    process.exit(1)
+  }
+} else if (branch === 'main') {
+  if (openInCode(root)) {
+    p.outro('Opened repo root')
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+} else {
+  const dir = worktreeDir(branch)
+  if (!existsSync(resolve(dir, '.git'))) {
+    // List available worktrees as a hint
+    const available = listWorktrees()
+    p.log.error(`Worktree "${branch}" does not exist.`)
+    if (available.length > 0) {
+      p.log.info(`Available worktrees: ${available.join(', ')}`)
+    }
+    process.exit(1)
+  }
+  if (openInCode(dir)) {
+    p.outro(`Opened .worktrees/${branch}/`)
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+}

package/src/cli/dev-helpers.js

@@ -0,0 +1,47 @@
+/**
+ * Git helpers for storyboard dev CLI.
+ * Extracted for testability — no side effects on import.
+ */
+
+import { execFileSync } from 'child_process'
+
+/**
+ * Check if the working tree has uncommitted changes (staged or unstaged).
+ */
+export function hasUncommittedChanges(cwd) {
+  try {
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8' }).trim()
+    return status.length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a local branch exists.
+ */
+export function localBranchExists(name, cwd) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', `refs/heads/${name}`], { cwd, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve the default branch for the repo root (main, master, or origin/HEAD target).
+ * Returns null if none can be determined.
+ */
+export function resolveDefaultBranch(cwd) {
+  for (const candidate of ['main', 'master']) {
+    if (localBranchExists(candidate, cwd)) return candidate
+  }
+  // Try origin/HEAD
+  try {
+    const ref = execFileSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD'], { cwd, encoding: 'utf8' }).trim()
+    const name = ref.replace('refs/remotes/origin/', '')
+    if (name && localBranchExists(name, cwd)) return name
+  } catch { /* no origin/HEAD */ }
+  return null
+}

package/src/cli/dev-helpers.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+import { hasUncommittedChanges, localBranchExists, resolveDefaultBranch } from './dev-helpers.js'
+import { execSync } from 'child_process'
+
+// These tests run against the real git repo — they verify the helpers
+// work correctly with actual git state.
+
+const repoRoot = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim()
+
+describe('hasUncommittedChanges', () => {
+  it('returns a boolean', () => {
+    const result = hasUncommittedChanges(repoRoot)
+    expect(typeof result).toBe('boolean')
+  })
+
+  it('returns false for non-existent directory', () => {
+    expect(hasUncommittedChanges('/tmp/nonexistent-repo-12345')).toBe(false)
+  })
+})
+
+describe('localBranchExists', () => {
+  it('returns true for a branch that exists', () => {
+    // The current branch must exist
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: repoRoot, encoding: 'utf8' }).trim()
+    expect(localBranchExists(branch, repoRoot)).toBe(true)
+  })
+
+  it('returns false for a branch that does not exist', () => {
+    expect(localBranchExists('__nonexistent-branch-xyz-99999__', repoRoot)).toBe(false)
+  })
+
+  it('returns false for invalid cwd', () => {
+    expect(localBranchExists('main', '/tmp/nonexistent-repo-12345')).toBe(false)
+  })
+})
+
+describe('resolveDefaultBranch', () => {
+  it('returns a string or null', () => {
+    const result = resolveDefaultBranch(repoRoot)
+    expect(result === null || typeof result === 'string').toBe(true)
+  })
+
+  it('prefers main over master when main exists', () => {
+    // If main exists in this repo, it should be the default
+    if (localBranchExists('main', repoRoot)) {
+      expect(resolveDefaultBranch(repoRoot)).toBe('main')
+    }
+  })
+
+  it('returns null for non-git directory', () => {
+    expect(resolveDefaultBranch('/tmp')).toBe(null)
+  })
+})

package/src/cli/dev.js

@@ -19,27 +19,13 @@ import { detectWorktreeName, getPort, repoRoot, worktreeDir, listWorktrees } fro
 import { generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, reloadCaddy, readDevDomain } from './proxy.js'
 import { startRenameWatcher } from '../rename-watcher/watcher.js'
 import { parseFlags } from './flags.js'
+import { hasUncommittedChanges, localBranchExists, resolveDefaultBranch } from './dev-helpers.js'
 
 const flagSchema = {
   port: { type: 'number', description: 'Override dev server port' },
   create: { type: 'boolean', default: true, description: 'Allow creating worktrees/branches (disable with --no-create)' },
 }
 
-/**
- * Check if a local branch exists.
- * @param {string} name
- * @param {string} cwd
- * @returns {boolean}
- */
-function localBranchExists(name, cwd) {
-  try {
-    execFileSync('git', ['show-ref', '--verify', `refs/heads/${name}`], { cwd, stdio: 'ignore' })
-    return true
-  } catch {
-    return false
-  }
-}
-
 /**
  * Check if a remote branch exists on origin.
  * @param {string} name
@@ -84,15 +70,84 @@ function createWorktree(name, root, { newBranch = false } = {}) {
 /**
  * Resolve the target worktree for `storyboard dev [branch]`.
  *
+ * When no argument is given and the repo root is on a non-main branch,
+ * prompts the user to convert it to a proper worktree.
+ *
  * @param {string|undefined} branchArg — positional branch argument
  * @param {object} opts
  * @param {boolean} opts.allowCreate — whether creation is allowed
  * @returns {Promise<{ worktreeName: string, targetCwd: string, created: boolean }>}
  */
 async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
-  // No argument — detect from cwd (current behavior)
+  // No argument — detect from cwd
   if (!branchArg) {
-    return { worktreeName: detectWorktreeName(), targetCwd: process.cwd(), created: false }
+    const detectedName = detectWorktreeName()
+
+    // Already in a worktree or on main — use cwd as-is
+    const root = repoRoot()
+    const realCwd = resolve(process.cwd())
+    const isAtRoot = realCwd === resolve(root)
+    if (detectedName === 'main' || !isAtRoot) {
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // Root is on a non-main branch — check for existing worktree first
+    const branch = detectedName
+    const existingDir = worktreeDir(branch)
+    if (existsSync(resolve(existingDir, '.git'))) {
+      p.log.info(`Root is on branch "${branch}" — using existing worktree`)
+      return { worktreeName: branch, targetCwd: existingDir, created: false }
+    }
+
+    // No worktree exists — prompt the user to convert
+    p.log.warning(`Root is on branch "${branch}" instead of main.`)
+    const shouldConvert = await p.confirm({
+      message: `Convert "${branch}" to a worktree? (moves branch to .worktrees/${branch}/)`,
+      initialValue: true,
+    })
+
+    if (p.isCancel(shouldConvert) || !shouldConvert) {
+      // User declined — proceed with root as-is (legacy behavior)
+      return { worktreeName: detectedName, targetCwd: process.cwd(), created: false }
+    }
+
+    // User accepted — validate and convert
+    if (!allowCreate) {
+      p.log.error('Cannot convert — --no-create flag is set.')
+      process.exit(1)
+    }
+
+    if (hasUncommittedChanges(root)) {
+      p.log.error('Cannot convert — uncommitted changes in working tree.')
+      p.log.info('Commit or stash your changes first, then run `sb dev` again.')
+      process.exit(1)
+    }
+
+    const defaultBranch = resolveDefaultBranch(root)
+    if (!defaultBranch) {
+      p.log.error('Cannot determine default branch (main/master). Switch root manually.')
+      process.exit(1)
+    }
+
+    p.log.step(`Switching root to "${defaultBranch}"`)
+    execFileSync('git', ['checkout', defaultBranch], { cwd: root, stdio: 'inherit' })
+
+    const targetDir = createWorktree(branch, root, { newBranch: false })
+
+    // Offer to open the new worktree in VS Code
+    const shouldOpen = await p.confirm({
+      message: 'Open this worktree in VS Code?',
+      initialValue: true,
+    })
+    if (shouldOpen && !p.isCancel(shouldOpen)) {
+      try {
+        execFileSync('code', [targetDir], { stdio: 'inherit' })
+      } catch {
+        p.log.warning(`Could not open VS Code. Run: code ${targetDir}`)
+      }
+    }
+
+    return { worktreeName: branch, targetCwd: targetDir, created: true }
   }
 
   const root = repoRoot()

package/src/cli/index.js

@@ -71,6 +71,7 @@ function helpScreen(version) {
     `  ${bold(cyan('Development'))}`,
     cmd('dev', 'Start Vite dev server + update proxy'),
     cmd('dev [branch]', 'Start dev for a specific worktree/branch'),
+    cmd('code [branch]', 'Open a worktree in VS Code'),
     cmd('exit', 'Stop all dev servers and proxy'),
     '',
     `  ${bold(cyan('Create'))}`,
@@ -83,6 +84,7 @@ function helpScreen(version) {
     `  ${bold(cyan('Canvas'))}`,
     cmd('canvas add <type>', 'Add widget to a canvas'),
     `                              ${dim('types: sticky-note, markdown, prototype')}`,
+    cmd('canvas read [name]', 'Read canvas state and list widgets'),
     '',
     `  ${bold(cyan('Setup'))}`,
     cmd('setup', 'Install deps, Caddy proxy, start proxy'),
@@ -120,6 +122,8 @@ switch (command) {
   case 'canvas':
     if (process.argv[3] === 'add') {
       import('./canvasAdd.js')
+    } else if (process.argv[3] === 'read' || !process.argv[3]) {
+      import('./canvasRead.js')
     } else {
       const version = getVersion()
       console.log(helpScreen(version))
@@ -130,6 +134,9 @@ switch (command) {
   case 'exit':
     import('./exit.js')
     break
+  case 'code':
+    import('./code.js')
+    break
   default: {
     if (command === 'update' || (command && command.startsWith('update:'))) {
       import('./updateVersion.js')

package/src/cli/proxy.js

@@ -130,21 +130,73 @@ export function generateRouteConfig(portOverrides = {}) {
   }
 }
 
+/**
+ * Find indices of stale routes that match the same host but lack an @id.
+ * Returns indices sorted descending (highest first) for safe deletion.
+ * Exported for testing.
+ */
+export function findStaleRouteIndices(routes, keepId, host) {
+  const indices = []
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i]
+    if (route['@id'] === keepId) continue
+    if (route['@id']) continue // different intentional route — leave it
+    const routeHosts = route.match?.[0]?.host || []
+    if (routeHosts.includes(host)) {
+      indices.push(i)
+    }
+  }
+  return indices.reverse()
+}
+
+/**
+ * Remove stale routes that match the same host but lack an @id.
+ * These are leftovers from Caddyfile reloads that shadow admin-API routes.
+ * Deletes from highest index to lowest to preserve indices during removal.
+ * Best-effort — warns on failure but does not throw.
+ */
+function cleanupDuplicateRoutes(keepId, host) {
+  try {
+    const config = execSync(
+      `curl -sf '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes'`,
+      { encoding: 'utf-8', timeout: 5000 },
+    )
+    const routes = JSON.parse(config)
+    const staleIndices = findStaleRouteIndices(routes, keepId, host)
+    for (const idx of staleIndices) {
+      try {
+        execSync(
+          `curl -sf -X DELETE '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes/${idx}'`,
+          { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
+        )
+      } catch {
+        console.warn(`[storyboard] failed to remove stale proxy route at index ${idx}`)
+      }
+    }
+  } catch {
+    console.warn('[storyboard] failed to clean up stale proxy routes — branch URLs may not work via proxy')
+  }
+}
+
 /**
  * Upsert this repo's route in the running Caddy instance via admin API.
  * Uses PATCH if the @id exists, POST if it doesn't.
+ * After a successful upsert, removes any stale non-@id routes for the
+ * same host (leftovers from prior Caddyfile reloads).
  * Returns true on success, false on failure.
  */
 export function upsertCaddyRoute(routeConfig) {
   const id = routeConfig['@id']
+  const host = routeConfig.match?.[0]?.host?.[0]
   const payload = JSON.stringify(routeConfig)
 
   // Try PATCH first (update existing route by @id)
   try {
-    const patchResult = execSync(
+    execSync(
       `curl -sf -X PATCH '${CADDY_ADMIN}/id/${id}' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
       { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
     )
+    if (host) cleanupDuplicateRoutes(id, host)
     return true
   } catch {
     // @id doesn't exist yet — POST a new route
@@ -153,6 +205,7 @@ export function upsertCaddyRoute(routeConfig) {
         `curl -sf -X POST '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
         { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
       )
+      if (host) cleanupDuplicateRoutes(id, host)
       return true
     } catch {
       return false

package/src/cli/proxy.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { findStaleRouteIndices } from './proxy.js'
+
+describe('findStaleRouteIndices', () => {
+  it('identifies stale non-@id routes matching the same host', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }], terminal: true }, // index 0: stale
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 1: ours
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([0])
+  })
+
+  it('preserves routes with a different @id for the same host', () => {
+    const routes = [
+      { '@id': 'other-app', match: [{ host: ['storyboard.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns multiple stale indices in descending order', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 0: stale
+      { '@id': 'storyboard-core', match: [{ host: ['storyboard-core.localhost'] }] }, // index 1: different host
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 2: ours
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 3: stale
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([3, 0]) // descending for safe deletion
+  })
+
+  it('ignores routes for a different host', () => {
+    const routes = [
+      { match: [{ host: ['other.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles routes with no match field', () => {
+    const routes = [
+      { handle: [{ handler: 'reverse_proxy' }] }, // no match
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns empty array when no stale routes exist', () => {
+    const routes = [
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles empty routes array', () => {
+    expect(findStaleRouteIndices([], 'storyboard', 'storyboard.localhost')).toEqual([])
+  })
+})

package/src/cli/setup.js

@@ -114,7 +114,47 @@ if (hasBrew) {
   }
 }
 
-// 5. Proxy
+// 5. VS Code CLI
+if (isInstalled('code')) {
+  p.log.success('VS Code CLI installed')
+} else {
+  // Try to install the `code` CLI from VS Code's known locations
+  const codePaths = [
+    '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+    '/usr/local/bin/code',
+  ]
+  let installed = false
+  for (const codePath of codePaths) {
+    if (existsSync(codePath)) {
+      p.log.success('VS Code CLI available (symlink exists)')
+      installed = true
+      break
+    }
+  }
+  if (!installed) {
+    // Try the VS Code shell command installer
+    const vsCodeApp = '/Applications/Visual Studio Code.app'
+    if (existsSync(vsCodeApp)) {
+      const shellScript = `${vsCodeApp}/Contents/Resources/app/bin/code`
+      if (existsSync(shellScript)) {
+        try {
+          // Create symlink in /usr/local/bin
+          run(`ln -sf "${shellScript}" /usr/local/bin/code`)
+          p.log.success('VS Code CLI installed (symlinked to /usr/local/bin/code)')
+          installed = true
+        } catch {
+          // Fall through to manual instructions
+        }
+      }
+    }
+    if (!installed) {
+      p.log.warning('VS Code CLI not found. Open VS Code and run:')
+      p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    }
+  }
+}
+
+// 6. Proxy
 if (isCaddyInstalled()) {
   const proxySpin = p.spinner()
   const caddyfilePath = generateCaddyfile()