@dfosco/storyboard 0.5.0-alpha.0

package/src/core/cli/setup.js

@@ -0,0 +1,404 @@
+/**
+ * storyboard setup — One-time setup for the Storyboard dev environment.
+ *
+ * Idempotent: safe to run multiple times, only does what's needed.
+ *
+ * Usage:
+ *   npx storyboard setup                          # interactive
+ *   npx storyboard setup --skip-branch             # non-interactive, skip branch prompt
+ *   npx storyboard setup --branch=<name>           # non-interactive, switch to branch after setup
+ */
+
+import * as p from '@clack/prompts'
+import { existsSync, writeFileSync, readFileSync, mkdirSync, readdirSync, symlinkSync } from 'fs'
+import path from 'path'
+import { execSync } from 'child_process'
+import { generateCaddyfile, isCaddyInstalled, isCaddyRunning, startCaddy, reloadCaddy } from './proxy.js'
+import { gettingStartedLines, dim, magenta, bold, yellow, green } from './intro.js'
+import { parseFlags } from './flags.js'
+
+const flagSchema = {
+  'skip-branch': { type: 'boolean', default: false, description: 'Skip the branch prompt at the end' },
+  branch: { type: 'string', description: 'Switch to a branch after setup (non-interactive)' },
+}
+
+const { flags } = parseFlags(process.argv.slice(3), flagSchema)
+
+/**
+ * Run a potentially slow task with a spinner that only appears after 500ms.
+ * If the task completes quickly, shows the done message immediately.
+ */
+async function withSpin(label, doneMsg, fn) {
+  const spin = p.spinner()
+  const timer = setTimeout(() => spin.start(label), 500)
+  try {
+    await fn()
+    clearTimeout(timer)
+    spin.stop(doneMsg)
+  } catch (err) {
+    clearTimeout(timer)
+    spin.stop(`Failed: ${label}`)
+    throw err
+  }
+}
+
+function mascot() {
+  const d = dim('·')
+  const f = magenta
+  const b = dim
+  const msg = `  ${bold('Happy prototyping!')} 🎨`
+  return [
+    `        ${b('╭─────────────────╮')}`,
+    `        ${b('│')}  ${d}  ${f('◠')}  ${f('◡')}  ${f('◠')}  ${d}  ${b('│')}${msg}`,
+    `        ${b('│')}  ${d}  ${d}  ${d}  ${d}  ${d}  ${b('│')}`,
+    `        ${b('╰─────────────────╯')}`,
+  ].join('\n')
+}
+
+function run(cmd, opts = {}) {
+  execSync(cmd, { stdio: 'pipe', ...opts })
+}
+
+function isInstalled(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+p.intro('storyboard setup')
+
+// 1. Check for node_modules (quick sanity check — full install runs at the end)
+if (!existsSync('node_modules')) {
+  p.log.info('node_modules not found — will install at end of setup')
+} else {
+  p.log.success('Dependencies present')
+}
+
+// 2. Homebrew
+let hasBrew = isInstalled('brew')
+if (!hasBrew) {
+  const brewSpin = p.spinner()
+  brewSpin.start('Installing Homebrew...')
+  try {
+    run('/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"')
+    const brewPaths = ['/opt/homebrew/bin/brew', '/usr/local/bin/brew', '/home/linuxbrew/.linuxbrew/bin/brew']
+    for (const bp of brewPaths) {
+      if (existsSync(bp)) {
+        process.env.PATH = `${bp.replace(/\/brew$/, '')}:${process.env.PATH}`
+        break
+      }
+    }
+    hasBrew = true
+    brewSpin.stop('Homebrew installed')
+  } catch {
+    brewSpin.stop('Failed to install Homebrew')
+    p.log.warning('Install manually: https://brew.sh')
+  }
+}
+
+// 3. Caddy
+if (hasBrew) {
+  if (isCaddyInstalled()) {
+    p.log.success('Caddy proxy installed')
+  } else {
+    const caddySpin = p.spinner()
+    caddySpin.start('Installing Caddy...')
+    try {
+      run('brew install caddy')
+      caddySpin.stop('Caddy proxy installed')
+    } catch {
+      caddySpin.stop('Failed to install Caddy')
+      p.log.warning('Install manually: brew install caddy')
+    }
+  }
+
+  // 4. GitHub CLI
+  if (isInstalled('gh')) {
+    p.log.success('GitHub CLI installed')
+  } else {
+    const ghSpin = p.spinner()
+    ghSpin.start('Installing GitHub CLI...')
+    try {
+      run('brew install gh')
+      ghSpin.stop('GitHub CLI installed')
+    } catch {
+      ghSpin.stop('Failed to install GitHub CLI')
+      p.log.warning('Install manually: brew install gh')
+    }
+  }
+}
+
+// 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. Git hooks
+{
+  // Create .githooks/ if it doesn't exist — copy from scaffold template
+  if (!existsSync('.githooks')) {
+    const scaffoldHooks = path.resolve(import.meta.dirname, '..', '..', 'scaffold', 'githooks')
+    if (existsSync(scaffoldHooks)) {
+      try {
+        run(`cp -r "${scaffoldHooks}" .githooks`)
+        run('chmod +x .githooks/*')
+      } catch { /* fall through */ }
+    }
+  }
+
+  if (existsSync('.githooks')) {
+    try {
+      run('git config core.hooksPath .githooks')
+      if (existsSync('.githooks/pre-push')) {
+        run('chmod +x .githooks/pre-push')
+      }
+      p.log.success('Git hooks activated (.githooks/)')
+    } catch {
+      p.log.warning('Failed to set git hooks path')
+    }
+  } else {
+    p.log.info(dim('No .githooks/ directory — run storyboard-scaffold first'))
+  }
+}
+
+// 7. Asset directories
+{
+  const dirs = ['assets/canvas/images', 'assets/.storyboard-public/terminal-snapshots', '.storyboard', '.storyboard/terminals', '.storyboard/terminal-buffers', '.storyboard/logs']
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      try { mkdirSync(dir, { recursive: true }) } catch { /* ignore */ }
+    }
+  }
+
+  // Scaffold initial .selectedwidgets.json if missing
+  const selectedWidgetsPath = '.storyboard/.selectedwidgets.json'
+  if (!existsSync(selectedWidgetsPath)) {
+    try {
+      writeFileSync(selectedWidgetsPath, JSON.stringify({
+        canvasId: null,
+        canvasFile: null,
+        selectedWidgetIds: [],
+        widgets: [],
+      }, null, 2) + '\n', 'utf-8')
+    } catch { /* ignore */ }
+  }
+
+  p.log.success('Canvas asset directories ready')
+}
+
+// 7a. Scaffold .gitignore entries for private canvas images
+{
+  const gitignorePath = '.gitignore'
+  const privatePatterns = [
+    'src/canvas/images/~*',
+    'assets/canvas/images/~*',
+    'assets/canvas/snapshots/~*',
+    'assets/.storyboard-public/terminal-snapshots/~*',
+  ]
+  if (existsSync(gitignorePath)) {
+    try {
+      let content = readFileSync(gitignorePath, 'utf-8')
+      const missing = privatePatterns.filter(p => !content.includes(p))
+      if (missing.length > 0) {
+        const block = '\n# Private canvas images (tilde prefix = not committed)\n' + missing.join('\n') + '\n'
+        content = content.trimEnd() + '\n' + block
+        writeFileSync(gitignorePath, content, 'utf-8')
+        p.log.success('Added private image patterns to .gitignore')
+      }
+    } catch { /* ignore */ }
+  }
+}
+
+// 7b. Copilot agents
+{
+  const agentsDir = '.agents'
+  if (!existsSync(agentsDir)) {
+    try { mkdirSync(agentsDir, { recursive: true }) } catch { /* ignore */ }
+  }
+
+  const scaffoldAgents = path.resolve(import.meta.dirname, '..', '..', 'scaffold', 'agents')
+  if (existsSync(scaffoldAgents)) {
+    try {
+      const agentFiles = execSync(`ls "${scaffoldAgents}"`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+      for (const file of agentFiles) {
+        const dest = path.join(agentsDir, file)
+        if (!existsSync(dest)) {
+          run(`cp "${path.join(scaffoldAgents, file)}" "${dest}"`)
+        }
+      }
+      if (agentFiles.length > 0) {
+        p.log.success('Copilot agents scaffolded (.agents/)')
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Create symlinks in each CLI's expected agent directory.
+  // Source of truth: .agents/*.agent.md
+  // Copilot CLI reads .github/agents/*.md
+  // Claude Code reads .claude/agents/*.md
+  // Codex CLI uses .codex/config.toml (no agent files needed)
+  try {
+    const agentFiles = readdirSync(agentsDir).filter(f => f.endsWith('.agent.md'))
+    const targets = [
+      { dir: path.join('.github', 'agents'), label: 'Copilot CLI' },
+      { dir: path.join('.claude', 'agents'), label: 'Claude Code' },
+    ]
+    for (const { dir, label } of targets) {
+      try { mkdirSync(dir, { recursive: true }) } catch { /* ignore */ }
+      let linked = 0
+      for (const file of agentFiles) {
+        const linkName = file.replace('.agent.md', '.md')
+        const linkPath = path.join(dir, linkName)
+        const target = path.relative(dir, path.join(agentsDir, file))
+        if (!existsSync(linkPath)) {
+          try { symlinkSync(target, linkPath); linked++ } catch { /* ignore */ }
+        }
+      }
+      if (linked > 0) {
+        p.log.success(`${label} agent symlinks created (${dir}/)`)
+      }
+    }
+  } catch { /* ignore */ }
+}
+
+// 8. Proxy
+if (isCaddyInstalled()) {
+  const proxySpin = p.spinner()
+  const caddyfilePath = generateCaddyfile()
+  if (isCaddyRunning()) {
+    proxySpin.start('Reloading proxy...')
+    reloadCaddy(caddyfilePath)
+    proxySpin.stop('Proxy reloaded')
+  } else {
+    proxySpin.start('Starting proxy...')
+    startCaddy(caddyfilePath)
+    proxySpin.stop('Proxy started')
+  }
+}
+
+// 9. Install / sync dependencies
+// Skip npm install if a dev server is running — it would trigger Vite's
+// file watcher and restart the server on a different port.
+{
+  const { SERVER_PORT } = await import('../server/index.js')
+  const { readDevDomain: readDomain } = await import('./proxy.js')
+  const http = await import('node:http')
+
+  const devRunning = await new Promise((resolve) => {
+    const req = http.get(`http://localhost:${SERVER_PORT}/health`, (res) => {
+      if (res.statusCode !== 200) { resolve(false); return }
+      let data = ''
+      res.on('data', (chunk) => { data += chunk })
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data)
+          const ourDomain = readDomain()
+          resolve(json.ok === true && json.devDomain === ourDomain)
+        } catch { resolve(false) }
+      })
+    })
+    req.on('error', () => resolve(false))
+    req.setTimeout(1000, () => { req.destroy(); resolve(false) })
+  })
+
+  if (devRunning) {
+    p.log.info(dim('Skipping npm install — dev server is running (would cause restart)'))
+    p.log.info(dim('Run `npm install` manually after stopping the dev server if needed'))
+  } else {
+    try {
+      await withSpin(
+        'Installing dependencies...',
+        'Dependencies installed',
+        () => { run('npm install', { stdio: 'ignore' }) }
+      )
+    } catch {
+      p.log.warning('npm install failed — run it manually to see details')
+      p.log.info(`  ${dim('npm install')}`)
+    }
+  }
+}
+
+p.note(
+  [
+    ...gettingStartedLines(),
+    '',
+    `  ${dim('Run')} ${yellow('npx storyboard')} ${dim('to see all commands')}`,
+  ].join('\n'),
+  'Getting started'
+)
+
+// Offer branch guide
+{
+  // Non-interactive: --branch=<name> or --skip-branch
+  if (flags.branch) {
+    const { runBranchGuide } = await import('./branch.js')
+    await runBranchGuide(flags.branch)
+  } else if (flags['skip-branch']) {
+    console.log()
+    console.log(mascot())
+    p.outro('')
+  } else {
+    // Interactive: ask the user
+    let currentBranchName = 'main'
+    try {
+      currentBranchName = execSync('git branch --show-current', { encoding: 'utf8' }).trim() || 'main'
+    } catch { /* empty */ }
+
+    const wantBranch = await p.select({
+      message: 'Want to work from a different branch?',
+      options: [
+        { value: true, label: 'Yes (help me create it)' },
+        { value: false, label: `No (stay on current branch ${bold(currentBranchName)})` },
+      ],
+      initialValue: false,
+    })
+
+    if (!p.isCancel(wantBranch) && wantBranch) {
+      const { runBranchGuide } = await import('./branch.js')
+      await runBranchGuide()
+    } else {
+      console.log()
+      console.log(mascot())
+      p.log.info(`${dim('Non-interactive:')} ${green('npx sb setup --skip-branch')}`)
+      p.outro('')
+    }
+  }
+}

package/src/core/cli/terminal-commands.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * storyboard terminal {close|open|remove} --id <name-or-id>
+ *
+ * Subcommands for managing terminal sessions by friendly name, tmux name, or widget ID.
+ */
+
+import * as p from '@clack/prompts'
+import { execSync } from 'node:child_process'
+import { detectWorktreeName, resolveRunningPort } from '../worktree/port.js'
+import { readDevDomain } from './proxy.js'
+import { parseFlags } from './flags.js'
+import { dim, cyan, bold, yellow } from './intro.js'
+
+const flagSchema = {
+  id: { type: 'string', required: true, description: 'Session name, tmux name, or widget ID' },
+}
+
+const subcommand = process.argv[3]
+const { flags, missing, errors } = parseFlags(process.argv.slice(4), flagSchema)
+
+/** Resolve the dev server base URL (proxy or direct) */
+function getBaseUrl(worktreeName, port) {
+  const domain = readDevDomain()
+  const isMain = worktreeName === 'main'
+  const proxyBase = isMain ? `http://${domain}/` : `http://${domain}/branch--${worktreeName}/`
+  const directBase = isMain ? `http://localhost:${port}/` : `http://localhost:${port}/branch--${worktreeName}/`
+  return { proxyBase, directBase }
+}
+
+/** Fetch all sessions from the dev server */
+async function fetchSessions(worktreeName, port) {
+  const { proxyBase, directBase } = getBaseUrl(worktreeName, port)
+  for (const base of [proxyBase, directBase]) {
+    try {
+      const res = await fetch(`${base}_storyboard/terminal/sessions`, { signal: AbortSignal.timeout(3000) })
+      if (!res.ok) continue
+      const data = await res.json()
+      return { sessions: data.sessions || [], base }
+    } catch { continue }
+  }
+  return null
+}
+
+/** POST/DELETE helper that tries proxy then direct */
+async function apiRequest(worktreeName, port, path, method = 'POST', body = null) {
+  const { proxyBase, directBase } = getBaseUrl(worktreeName, port)
+  for (const base of [proxyBase, directBase]) {
+    try {
+      const opts = { method, signal: AbortSignal.timeout(5000) }
+      if (body) {
+        opts.headers = { 'Content-Type': 'application/json' }
+        opts.body = JSON.stringify(body)
+      }
+      const res = await fetch(`${base}${path}`, opts)
+      if (res.ok) return { ok: true, data: await res.json().catch(() => ({})) }
+    } catch { continue }
+  }
+  return { ok: false }
+}
+
+/**
+ * Resolve --id to a session entry. Tries:
+ * 1. Friendly name match (e.g. "red-robin")
+ * 2. Exact tmux name match (e.g. "sb-abc123def456")
+ * 3. Widget ID match (e.g. "terminal-abc123")
+ */
+function resolveSession(sessions, id) {
+  // Friendly name
+  const byName = sessions.find(s => s.name === id)
+  if (byName) return byName
+  // Tmux name
+  const byTmux = sessions.find(s => s.tmuxName === id)
+  if (byTmux) return byTmux
+  // Widget ID
+  const byWidget = sessions.find(s => s.widgetId === id)
+  if (byWidget) return byWidget
+  return null
+}
+
+/** Detect the current tmux session name (only if it's a storyboard session) */
+function getCurrentTmuxSession() {
+  try {
+    const name = execSync('tmux display-message -p "#{session_name}" 2>/dev/null', {
+      encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim()
+    // Only return if this is a storyboard terminal session
+    return name.startsWith('sb-') ? name : null
+  } catch {
+    return null
+  }
+}
+
+/** Check if we're inside ANY tmux (storyboard or user's own) */
+function _isInsideTmux() {
+  return Boolean(process.env.TMUX)
+}
+void _isInsideTmux
+
+// ── Close (archive) ──
+
+async function closeSession(session, worktreeName, port) {
+  p.intro(bold('Close session'))
+
+  const label = session.name || session.tmuxName
+
+  if (session.status === 'live') {
+    p.log.info(`Session ${cyan(label)} is live — detaching first...`)
+    const detachResult = await apiRequest(
+      worktreeName, port,
+      `_storyboard/terminal/sessions/${encodeURIComponent(session.tmuxName)}/detach`,
+    )
+    if (!detachResult.ok) {
+      p.log.warn('Could not detach via API, continuing with archive...')
+    }
+  }
+
+  // Orphan the session (archive with grace timer)
+  const orphanResult = await apiRequest(
+    worktreeName, port,
+    `_storyboard/terminal/sessions/${encodeURIComponent(session.tmuxName)}/orphan`,
+  )
+
+  if (orphanResult.ok) {
+    p.log.success(`Session ${cyan(label)} archived. Tmux session kept alive with grace timer.`)
+  } else {
+    p.log.error(`Failed to archive session ${cyan(label)}`)
+    process.exit(1)
+  }
+
+  p.outro('')
+}
+
+// ── Open (attach) ──
+
+async function openSession(session, _worktreeName, _port) {
+  void _worktreeName
+  void _port
+  p.intro(bold('Open session'))
+
+  const label = session.name || session.tmuxName
+  const currentSb = getCurrentTmuxSession()
+
+  if (session.status === 'live' && session.tmuxName !== currentSb) {
+    p.log.warn(
+      `Session ${cyan(label)} is currently live on widget ${dim(session.widgetId)} ` +
+      `in canvas ${cyan(session.canvasId)}.`
+    )
+    const confirm = await p.confirm({
+      message: 'Attach anyway? This may cause conflicts with the live widget.',
+    })
+    if (p.isCancel(confirm) || !confirm) {
+      p.outro(dim('Cancelled'))
+      process.exit(0)
+    }
+  }
+
+  // If we're inside a storyboard tmux session, use switch-client.
+  // Otherwise always use attach-session (even if user has their own tmux).
+  if (currentSb) {
+    p.outro(`Switching to ${bold(label)}...`)
+    try {
+      execSync(`tmux switch-client -t "${session.tmuxName}"`, { stdio: 'inherit' })
+    } catch {
+      p.log.error('Failed to switch tmux client')
+      process.exit(1)
+    }
+  } else {
+    p.outro(`Attaching to ${bold(label)}...`)
+    try {
+      execSync(`tmux attach-session -t "${session.tmuxName}"`, { stdio: 'inherit' })
+    } catch {
+      p.log.error('Failed to attach to tmux session')
+      process.exit(1)
+    }
+  }
+}
+
+// ── Remove (destroy) ──
+
+async function removeSession(session, worktreeName, port) {
+  p.intro(bold('Remove session'))
+
+  const label = session.name || session.tmuxName
+
+  const widgetNote = session.widgetId && session.widgetId !== 'unknown'
+    ? `\n  This will also ${yellow('remove the terminal widget')} from canvas ${cyan(session.canvasId)}.`
+    : ''
+
+  const confirm = await p.confirm({
+    message: `Permanently destroy session ${bold(label)}?${widgetNote}\n  The tmux session and all running processes inside it will be lost.`,
+  })
+
+  if (p.isCancel(confirm) || !confirm) {
+    p.outro(dim('Cancelled'))
+    process.exit(0)
+  }
+
+  // Kill via API
+  const killResult = await apiRequest(
+    worktreeName, port,
+    `_storyboard/terminal/sessions/${encodeURIComponent(session.tmuxName)}`,
+    'DELETE',
+  )
+
+  if (killResult.ok) {
+    p.log.success(`Session ${cyan(label)} destroyed`)
+  } else {
+    p.log.warn('API call failed, killing tmux session directly...')
+    try {
+      execSync(`tmux kill-session -t "${session.tmuxName}" 2>/dev/null`, { stdio: 'ignore' })
+      p.log.success(`Session ${cyan(label)} killed via tmux`)
+    } catch {
+      p.log.error('Failed to kill session')
+      process.exit(1)
+    }
+  }
+
+  // Remove widget from canvas
+  if (session.widgetId && session.widgetId !== 'unknown' && session.canvasId && session.canvasId !== 'unknown') {
+    const removeResult = await apiRequest(
+      worktreeName, port,
+      '_storyboard/canvas/widget',
+      'DELETE',
+      { name: session.canvasId, widgetId: session.widgetId },
+    )
+    if (removeResult.ok) {
+      p.log.success(`Widget ${dim(session.widgetId)} removed from canvas ${cyan(session.canvasId)}`)
+    }
+  }
+
+  p.outro('')
+}
+
+// ── Main ──
+
+async function main() {
+  if (missing.length > 0 || errors.length > 0) {
+    p.intro(bold('Terminal'))
+    if (errors.length) errors.forEach(e => p.log.error(e))
+    if (missing.length) p.log.error(`Missing required flag: ${bold('--id')}`)
+    p.log.info(`Usage: ${cyan(`storyboard terminal ${subcommand} --id <name-or-id>`)}`)
+    p.outro('')
+    process.exit(1)
+  }
+
+  const worktreeName = detectWorktreeName()
+  const port = resolveRunningPort(worktreeName)
+  const result = await fetchSessions(worktreeName, port)
+
+  if (!result) {
+    p.intro(bold('Terminal'))
+    p.log.error('Could not connect to dev server. Is it running?')
+    p.outro('')
+    process.exit(1)
+  }
+
+  const session = resolveSession(result.sessions, flags.id)
+  if (!session) {
+    p.intro(bold('Terminal'))
+    p.log.error(`No session found matching ${bold(flags.id)}`)
+    p.log.info(`Try ${cyan('storyboard terminal')} to browse sessions.`)
+    p.outro('')
+    process.exit(1)
+  }
+
+  switch (subcommand) {
+    case 'close':
+    case 'archive':
+      await closeSession(session, worktreeName, port)
+      break
+    case 'open':
+      await openSession(session, worktreeName, port)
+      break
+    case 'remove':
+      await removeSession(session, worktreeName, port)
+      break
+    default:
+      p.log.error(`Unknown subcommand: ${subcommand}`)
+      process.exit(1)
+  }
+}
+
+main().catch((err) => {
+  p.log.error(err.message)
+  process.exit(1)
+})