@dfosco/storyboard-core 4.2.0-beta.2 → 4.2.0-beta.21

package/src/cli/dev.js

@@ -1,8 +1,13 @@
 /**
  * storyboard dev [branch] — Start Vite with correct base path.
  *
- * If the storyboard server is running, delegates to it via the
- * switch-branch API instead of spawning Vite directly.
+ * If a storyboard server is already running (from another `sb dev`),
+ * operates in "client mode": asks the existing server to spawn Vite
+ * for this branch, prints the URL, and exits. This allows multiple
+ * branches to run simultaneously through the same server + Caddy proxy.
+ *
+ * Otherwise, starts the server in the foreground as the "owner".
+ * Ctrl+C kills Vite, releases the port, and exits cleanly.
  *
  * Usage:
  *   storyboard dev                 # detect worktree from cwd
@@ -16,16 +21,15 @@
 
 import * as p from '@clack/prompts'
 import http from 'node:http'
-import { spawn, execFileSync } from 'child_process'
+import { execFileSync } from 'child_process'
 import { existsSync } from 'fs'
 import { resolve } from 'path'
-import { detectWorktreeName, getPort, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
+import { detectWorktreeName, getPort, releasePort, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
 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'
 import { compactAll } from '../canvas/compact.js'
-import { SERVER_PORT } from '../server/index.js'
 
 const flagSchema = {
   port: { type: 'number', description: 'Override dev server port' },
@@ -203,102 +207,115 @@ async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
   return { worktreeName: branchArg, targetCwd: targetDir, created: true }
 }
 
-/** Check if the storyboard server is already running */
-function isServerRunning() {
+// ─── Server Detection ───
+
+/**
+ * Check if a storyboard server is already running on the expected port.
+ * Returns the server's health response if running, or null.
+ */
+function checkExistingServer(port) {
   return new Promise((resolve) => {
-    const req = http.get(`http://localhost:${SERVER_PORT}/health`, (res) => {
-      if (res.statusCode !== 200) { resolve(false); return }
+    const req = http.get(`http://localhost:${port}/health`, (res) => {
       let data = ''
-      res.on('data', (chunk) => { data += chunk })
+      res.on('data', (c) => (data += c))
       res.on('end', () => {
-        try {
-          const json = JSON.parse(data)
-          // Verify the server belongs to this repo's devDomain
-          const ourDomain = readDevDomain(process.cwd())
-          resolve(json.ok === true && json.devDomain === ourDomain)
-        } catch { resolve(false) }
+        try { resolve(JSON.parse(data)) }
+        catch { resolve(null) }
       })
     })
-    req.on('error', () => resolve(false))
-    req.setTimeout(1000, () => { req.destroy(); resolve(false) })
+    req.on('error', () => resolve(null))
+    req.setTimeout(2000, () => { req.destroy(); resolve(null) })
   })
 }
 
-/** Ask the running server to start a branch */
-function requestBranchFromServer(branch) {
+/**
+ * Ask an existing server to spawn Vite for a branch via the switch-branch API.
+ * Returns the parsed JSON response.
+ */
+function requestSwitchBranch(port, branch) {
   return new Promise((resolve, reject) => {
     const body = JSON.stringify({ branch })
-    const req = http.request(`http://localhost:${SERVER_PORT}/_storyboard/switch-branch`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
-    }, (res) => {
-      let data = ''
-      res.on('data', (chunk) => { data += chunk })
-      res.on('end', () => {
-        try { resolve(JSON.parse(data)) }
-        catch { reject(new Error('Invalid server response')) }
-      })
-    })
+    const req = http.request(
+      { hostname: 'localhost', port, path: '/_storyboard/switch-branch', method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } },
+      (res) => {
+        let data = ''
+        res.on('data', (c) => (data += c))
+        res.on('end', () => {
+          try {
+            const json = JSON.parse(data)
+            if (res.statusCode >= 400) reject(new Error(json.error || `HTTP ${res.statusCode}`))
+            else resolve(json)
+          } catch { reject(new Error(`Bad response: ${data}`)) }
+        })
+      }
+    )
     req.on('error', reject)
-    req.write(body)
-    req.end()
+    req.setTimeout(90_000, () => { req.destroy(); reject(new Error('Timeout waiting for Vite to start')) })
+    req.end(body)
   })
 }
 
-async function main() {
-  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+// ─── Client Mode ───
 
-  const branchArg = positional[0] || undefined
-  const overridePort = flags.port || null
-  const allowCreate = flags.create
+/**
+ * Run in client mode: an existing server handles Vite lifecycle.
+ * We just ask it to start the branch, print URLs, and exit.
+ */
+async function runClientMode(serverPort, worktreeName, domain) {
+  const isMain = worktreeName === 'main'
+  const basePath = isMain ? '/' : `/branch--${worktreeName}/`
+  const proxyUrl = `http://${domain}${basePath}`
 
-  p.intro('storyboard dev')
+  p.log.info(`Server already running on :${serverPort} — requesting dev session for "${worktreeName}"...`)
 
-  const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
+  try {
+    const result = await requestSwitchBranch(serverPort, worktreeName)
 
-  if (created) {
-    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
-  } else if (branchArg) {
-    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
-  }
+    if (result.status === 'already_running') {
+      p.log.success(`Already running: ${proxyUrl}`)
+    } else {
+      p.log.success(`Started: ${proxyUrl}`)
+    }
 
-  const port = getPort(worktreeName)
-  const isMain = worktreeName === 'main'
+    p.log.info(`Stop with: npx storyboard server stop ${worktreeName}`)
+    p.outro('Ready')
+  } catch (err) {
+    p.log.error(`Failed to start dev for "${worktreeName}": ${err.message}`)
+    process.exit(1)
+  }
+}
 
-  const basePath = isMain
-    ? '/'
-    : `/branch--${worktreeName}/`
+// ─── Owner Mode ───
 
-  const domain = readDevDomain(targetCwd)
+/**
+ * Run in owner mode: start the server + Vite in the foreground.
+ * This is the original behavior — the process owns the server lifecycle.
+ */
+async function runOwnerMode(worktreeName, targetCwd, domain, serverPort) {
+  getPort(worktreeName) // allocate port for this worktree
+  const isMain = worktreeName === 'main'
+  const basePath = isMain ? '/' : `/branch--${worktreeName}/`
   const proxyUrl = `http://${domain}${basePath}`
-  const directUrl = `http://localhost:${port}${basePath}`
 
-  // ── Check if storyboard server is already running ──
-  const serverRunning = await isServerRunning()
+  p.log.info('Starting storyboard server...')
+
+  const { startServer, spawnViteForBranch } = await import('../server/index.js')
 
-  if (serverRunning) {
-    // Delegate to the running server — just ask it to start this branch
-    p.log.info('Storyboard server detected — delegating...')
-    try {
-      const result = await requestBranchFromServer(worktreeName)
-      if (result.url) {
-        p.log.success(result.url)
-        p.outro(result.status === 'already_running' ? 'Already running' : 'Started')
-      } else {
-        p.log.error(result.error || 'Failed to start branch')
-      }
-    } catch (err) {
-      p.log.error(`Server communication failed: ${err.message}`)
+  let serverInstance
+  try {
+    serverInstance = await startServer()
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      // Race condition: server started between our health check and bind attempt.
+      // Fall back to client mode.
+      p.log.info('Server started by another process — switching to client mode...')
+      await runClientMode(serverPort, worktreeName, domain)
+      return
     }
-    return
+    throw err
   }
 
-  // ── No server running — start server + Vite together ──
-  p.log.info('Starting storyboard server...')
-
-  const { startServer, spawnViteForBranch, waitForPort: waitPort } = await import('../server/index.js')
-  startServer()
-
   // Compact bloated canvas JSONL files before starting Vite
   const compacted = compactAll(targetCwd)
   if (compacted.length > 0) {
@@ -307,13 +324,9 @@ async function main() {
     }
   }
 
-  // Spawn Vite through the server (manages the child process)
   const entry = spawnViteForBranch(worktreeName)
-
-  // Start rename watcher in target directory
   const renameWatcher = startRenameWatcher(targetCwd)
 
-  // Auto-compact every 15 minutes
   const compactInterval = setInterval(() => {
     try {
       const results = compactAll(targetCwd)
@@ -323,19 +336,42 @@ async function main() {
     } catch { /* non-critical */ }
   }, 15 * 60 * 1000)
 
-  // Wait for Vite to be ready
-  const ready = await waitPort(entry.port, 60_000)
+  function cleanup() {
+    renameWatcher.close()
+    clearInterval(compactInterval)
+    try { entry.child.kill('SIGTERM') } catch { /* already dead */ }
+    try { serverInstance.close() } catch { /* best effort */ }
+    releasePort(worktreeName)
+    process.exit(0)
+  }
+  process.on('SIGINT', cleanup)
+  process.on('SIGTERM', cleanup)
+
+  const ready = await (async () => {
+    const start = Date.now()
+    while (Date.now() - start < 60_000) {
+      if (entry.status === 'ready') return true
+      await new Promise(r => setTimeout(r, 300))
+    }
+    return false
+  })()
 
   if (ready) {
+    const actualDirectUrl = `http://localhost:${entry.port}${basePath}`
+
     if (isCaddyRunning()) {
-      p.log.success(proxyUrl)
+      const routeConfig = generateRouteConfig({ [worktreeName]: entry.port })
+      if (upsertCaddyRoute(routeConfig)) {
+        generateCaddyfile({ [worktreeName]: entry.port })
+      }
+      p.log.success(`${proxyUrl}`)
+      p.log.info(`direct: ${actualDirectUrl}`)
     } else {
-      p.log.success(directUrl)
+      p.log.success(actualDirectUrl)
       p.log.warning('Proxy not running — run `npx storyboard setup` for clean URLs')
     }
     p.outro('Ready')
 
-    // Pipe Vite output for interactive use
     entry.child.stdout.pipe(process.stdout)
     entry.child.stderr.pipe(process.stderr)
   } else {
@@ -346,6 +382,7 @@ async function main() {
   entry.child.on('exit', (code) => {
     renameWatcher.close()
     clearInterval(compactInterval)
+    try { serverInstance.close() } catch { /* best effort */ }
     if (code && code !== 0) {
       p.log.error(`Vite exited with code ${code}`)
     }
@@ -353,4 +390,41 @@ async function main() {
   })
 }
 
+// ─── Main ───
+
+async function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+
+  const branchArg = positional[0] || undefined
+  const allowCreate = flags.create
+
+  p.intro('storyboard dev')
+
+  const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
+
+  if (created) {
+    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
+  } else if (branchArg) {
+    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
+  }
+
+  const domain = readDevDomain(targetCwd)
+
+  // Check if a storyboard server is already running for this repo
+  const { SERVER_PORT } = await import('../server/index.js')
+  const existingServer = await checkExistingServer(SERVER_PORT)
+
+  if (existingServer?.ok) {
+    // Validate the running server belongs to the same repo (devDomain match)
+    if (existingServer.devDomain && existingServer.devDomain !== domain) {
+      p.log.error(`Port ${SERVER_PORT} is in use by a different project (domain: ${existingServer.devDomain}).`)
+      p.log.info('Stop it with `npx storyboard exit`, or use a different devDomain in storyboard.config.json.')
+      process.exit(1)
+    }
+    await runClientMode(SERVER_PORT, worktreeName, domain)
+  } else {
+    await runOwnerMode(worktreeName, targetCwd, domain, SERVER_PORT)
+  }
+}
+
 main()

package/src/cli/exit.js

@@ -1,38 +1,37 @@
 /**
- * storyboard exit — Stop the Caddy proxy and all running dev servers.
+ * storyboard exit — Stop all running dev servers and the Caddy proxy.
  */
 
 import * as p from '@clack/prompts'
-import { execSync } from 'child_process'
+import { list, unregister } from '../worktree/serverRegistry.js'
+import { isCaddyRunning, stopCaddy } from './proxy.js'
 
 p.intro('storyboard exit')
 
-// 1. Stop all Vite dev servers started by storyboard
-try {
-  const psOutput = execSync('ps aux', { encoding: 'utf8' })
-  const vitePids = psOutput
-    .split('\n')
-    .filter((line) => line.includes('vite') && line.includes('VITE_BASE_PATH'))
-    .map((line) => line.trim().split(/\s+/)[1])
-    .filter(Boolean)
-
-  if (vitePids.length > 0) {
-    for (const pid of vitePids) {
-      try { process.kill(Number(pid), 'SIGTERM') } catch { /* already dead */ }
-    }
-    p.log.success(`Stopped ${vitePids.length} dev server${vitePids.length > 1 ? 's' : ''}`)
-  } else {
-    p.log.info('No dev servers running')
+// 1. Stop all registered dev servers
+const servers = list()
+if (servers.length > 0) {
+  let stopped = 0
+  for (const s of servers) {
+    try {
+      process.kill(s.pid, 'SIGTERM')
+      stopped++
+    } catch { /* already dead */ }
+    unregister(s.id)
   }
-} catch {
+  p.log.success(`Stopped ${stopped} dev server${stopped !== 1 ? 's' : ''}`)
+} else {
   p.log.info('No dev servers running')
 }
 
-// 2. Stop Caddy proxy
-try {
-  execSync('sudo caddy stop >/dev/null 2>&1', { stdio: ['inherit', 'pipe', 'pipe'] })
-  p.log.success('Proxy stopped')
-} catch {
+// 2. Stop Caddy proxy via admin API (no sudo needed)
+if (isCaddyRunning()) {
+  if (stopCaddy()) {
+    p.log.success('Proxy stopped')
+  } else {
+    p.log.warning('Failed to stop proxy via admin API')
+  }
+} else {
   p.log.info('Proxy was not running')
 }
 

package/src/cli/index.js

@@ -5,7 +5,8 @@
  * Commands:
  *   storyboard dev              Start Vite dev server + update proxy
  *   storyboard setup            Install deps, Caddy, start proxy
- *   storyboard proxy            Generate Caddyfile + start/reload Caddy
+ *   storyboard proxy start      Start or reload Caddy proxy
+ *   storyboard proxy close      Stop Caddy proxy
  *   storyboard update:version   Update @dfosco/storyboard-* packages to latest
  *   storyboard update:beta      Update to latest beta
  *   storyboard update:alpha     Update to latest alpha
@@ -53,6 +54,9 @@ 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('server list', 'List running dev servers'),
+    cmd('server start [wt]', 'Start dev server for a worktree'),
+    cmd('server stop <wt|ID>', 'Stop a dev server'),
     cmd('code [branch]', 'Open a worktree in VS Code'),
     cmd('exit', 'Stop all dev servers and proxy'),
     '',
@@ -66,7 +70,9 @@ function helpScreen(version) {
     `  ${bold(cyan('Canvas'))}`,
     cmd('canvas add <type>', 'Add widget to a canvas'),
     `                              ${dim('types: sticky-note, markdown, prototype')}`,
+    cmd('canvas update <id>', 'Update a widget\'s props or position'),
     cmd('canvas read [name]', 'Read canvas state and list widgets'),
+    cmd('canvas batch', 'Execute multiple canvas operations in one call'),
     cmd('compact [name]', 'Compact canvas JSONL files (removes bloat)'),
     cmd('compact --all', 'Force compact all canvases'),
     '',
@@ -76,11 +82,21 @@ function helpScreen(version) {
     cmd('terminal close --id <name>', 'Archive a session ' + dim('(alias: archive)')),
     cmd('terminal open --id <name>', 'Attach to a session'),
     cmd('terminal remove --id <name>', 'Permanently destroy a session'),
+    cmd('terminal read <id>', 'Read terminal buffer ' + dim('(+ --length N)')),
     cmd('terminal --all', 'Show sessions across all branches'),
+    cmd('terminal reset', 'Kill tmux server, clear registry & snapshots'),
+    '',
+    `  ${dim('Inside a storyboard terminal, shortcuts are available:')}`,
+    cmd('start', 'Open the welcome screen'),
+    cmd('start <agent>', 'Launch an agent ' + dim('(copilot, claude, codex)')),
+    cmd('<agent>', 'Shorthand for start <agent> ' + dim('(accepts extra flags)')),
     '',
     `  ${bold(cyan('Setup'))}`,
     cmd('setup', 'Install deps, Caddy proxy, start proxy'),
-    cmd('proxy', 'Generate Caddyfile + start/reload Caddy'),
+    cmd('branch', 'Switch to a branch (interactive worktree guide)'),
+    cmd('branch <name>', 'Switch to a specific branch directly'),
+    cmd('proxy start', 'Start or reload Caddy proxy'),
+    cmd('proxy close', 'Stop Caddy proxy'),
     '',
     `  ${bold(cyan('Updates'))}`,
     cmd('update', 'Update storyboard packages to latest'),
@@ -105,6 +121,9 @@ switch (command) {
   case 'setup':
     import('./setup.js')
     break
+  case 'branch':
+    import('./branch.js')
+    break
   case 'proxy':
     import('./proxy.js')
     break
@@ -117,10 +136,14 @@ switch (command) {
   case 'canvas':
     if (process.argv[3] === 'add') {
       import('./canvasAdd.js')
+    } else if (process.argv[3] === 'update') {
+      import('./canvasUpdate.js')
     } else if (process.argv[3] === 'read' || !process.argv[3]) {
       import('./canvasRead.js')
     } else if (process.argv[3] === 'bounds') {
       import('./canvasBounds.js')
+    } else if (process.argv[3] === 'batch') {
+      import('./canvasBatch.js')
     } else {
       const version = getVersion()
       console.log(helpScreen(version))
@@ -134,12 +157,39 @@ switch (command) {
   case 'terminal':
     if (process.argv[3] === 'start') {
       import('./terminal-welcome.js')
+    } else if (process.argv[3] === '--help' || process.argv[3] === 'help') {
+      const cmd = (name, desc) => `    ${green(name.padEnd(36))}${desc}`
+      const cmds = [
+        `  ${bold(cyan('Terminal commands'))}`,
+        cmd('terminal', 'Browse and manage terminal sessions (interactive)'),
+        cmd('terminal start', 'Launch the terminal welcome prompt'),
+        cmd('terminal close --id <name>', 'Archive a session'),
+        cmd('terminal open --id <name>', 'Attach to a session'),
+        cmd('terminal remove --id <name>', 'Permanently destroy a session'),
+        cmd('terminal reset', 'Kill tmux server, clear registry & snapshots'),
+        '',
+        `  ${bold(cyan('Messaging'))}`,
+        cmd('terminal send <id> "msg"', 'Send a message to a terminal'),
+        cmd('terminal send --connected "msg"', 'Send to connected peer'),
+        cmd('terminal output --summary "..."', 'Save latest output (+ --content)'),
+        cmd('terminal status <widgetId>', 'Check terminal status'),
+        cmd('terminal read <widgetId>', 'Read terminal buffer (+ --length N)'),
+      ].join('\n')
+      console.log(`\n${cmds}\n`)
     } else if (process.argv[3] === 'close' || process.argv[3] === 'archive') {
       import('./terminal-commands.js')
     } else if (process.argv[3] === 'open') {
       import('./terminal-commands.js')
     } else if (process.argv[3] === 'remove') {
       import('./terminal-commands.js')
+    } else if (process.argv[3] === 'send') {
+      import('./terminal-messaging.js').then(m => m.handleSend())
+    } else if (process.argv[3] === 'output') {
+      import('./terminal-messaging.js').then(m => m.handleOutput())
+    } else if (process.argv[3] === 'status') {
+      import('./terminal-messaging.js').then(m => m.handleStatus())
+    } else if (process.argv[3] === 'read') {
+      import('./terminal-messaging.js').then(m => m.handleRead())
     } else {
       // Default: session browser (formerly `storyboard sessions`)
       import('./sessions.js')
@@ -156,6 +206,9 @@ switch (command) {
   case 'server':
     import('./server.js')
     break
+  case 'agent':
+    import('./agent.js')
+    break
   case 'code':
     import('./code.js')
     break