@dfosco/storyboard 0.6.0-beta.2 → 0.6.0-beta.21

package/src/core/cli/setup.js

@@ -12,18 +12,25 @@
 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 { execSync, spawn } from 'child_process'
 import { gettingStartedLines, dim, magenta, bold, yellow, green } from './intro.js'
 import { parseFlags } from './flags.js'
+import { readUserState, writeUserState, getInstalledStoryboardVersion } from './userState.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)' },
+  'no-buddy': { type: 'boolean', default: false, description: 'Omit the storyboard mascot from setup output' },
   'nuke': { type: 'boolean', default: false }, // undocumented: output uninstall command
 }
 
 const { flags } = parseFlags(process.argv.slice(3), flagSchema)
 
+// Suppress the mascot when piped into another storyboard command that
+// renders its own mascot (e.g. `storyboard dev` auto-runs setup first).
+// Respects either the --no-buddy flag or the STORYBOARD_NO_BUDDY env var.
+const showMascot = !flags['no-buddy'] && process.env.STORYBOARD_NO_BUDDY !== '1'
+
 // Hidden: output uninstall command for testing fresh setups
 if (flags.nuke) {
   const nukeCmd = [
@@ -42,23 +49,53 @@ if (flags.nuke) {
 }
 
 /**
- * Run a potentially slow task with a spinner that only appears after 500ms.
- * If the task completes quickly, shows the done message immediately.
+ * Async command runner — does NOT block the event loop, so spinners animate.
+ */
+function runAsync(cmd, args = [], opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: 'ignore', ...opts })
+    child.on('error', reject)
+    child.on('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${cmd} exited with code ${code}`))
+    })
+  })
+}
+
+/**
+ * Install a brew package with an animated spinner.
  */
-async function withSpin(label, doneMsg, fn) {
+async function brewInstall(pkg, label) {
   const spin = p.spinner()
-  const timer = setTimeout(() => spin.start(label), 500)
+  spin.start(`Installing ${label}`)
   try {
-    await fn()
-    clearTimeout(timer)
-    spin.stop(doneMsg)
-  } catch (err) {
-    clearTimeout(timer)
-    spin.stop(`Failed: ${label}`)
-    throw err
+    await runAsync('brew', ['install', pkg])
+    spin.stop(`${label} installed`)
+    return true
+  } catch {
+    spin.stop(`Failed to install ${label}`)
+    p.log.warning(`Install manually: brew install ${pkg}`)
+    return false
   }
 }
 
+/**
+ * Quick network probe — alerts the user if GitHub looks unreachable.
+ * We don't block on failure; downstream installers will surface their own errors.
+ */
+async function checkNetwork() {
+  const http = await import('node:https')
+  return new Promise((resolve) => {
+    const req = http.request('https://api.github.com', { method: 'HEAD', timeout: 4000 }, (res) => {
+      resolve(res.statusCode != null && res.statusCode < 500)
+      res.resume()
+    })
+    req.on('error', () => resolve(false))
+    req.on('timeout', () => { req.destroy(); resolve(false) })
+    req.end()
+  })
+}
+
 function mascot() {
   const d = dim('·')
   const f = magenta
@@ -87,13 +124,20 @@ function isInstalled(cmd) {
 
 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')
+// 0. Network probe — alert if GitHub is unreachable; don't block.
+{
+  const online = await checkNetwork()
+  if (!online) {
+    p.log.warning('Network looks offline — installers/downloads may fail')
+    p.log.info(dim('  Tried HEAD https://api.github.com; check VPN/proxy/DNS'))
+  } else {
+    p.log.success('Network reachable')
+  }
 }
 
+// Node is assumed to be present (you already ran `npx storyboard setup`).
+// node_modules will be installed at the end if missing.
+
 // 2. Homebrew
 let hasBrew = isInstalled('brew')
 if (!hasBrew) {
@@ -121,35 +165,43 @@ if (hasBrew) {
   if (isInstalled('git')) {
     p.log.success('Git installed')
   } else {
-    const gitSpin = p.spinner()
-    gitSpin.start('Installing Git')
-    try {
-      run('brew install git')
-      gitSpin.stop('Git installed')
-    } catch {
-      gitSpin.stop('Failed to install Git')
-      p.log.warning('Install manually: brew install git')
-    }
+    await brewInstall('git', 'Git')
   }
 }
 
 // 4. Caddy is no longer used. Worktrees run their own Vite directly on
-//    `http://localhost:<port>/storyboard/`. The block below intentionally
-//    skips the previous Caddy install + start steps.
+//    `http://localhost:<port>/storyboard/`.
 
 if (hasBrew) {
-  // 5. GitHub CLI
+  // 5. GitHub CLI — required for `gh auth`, `gh pr`, `gh issue` in agents.
+  let ghNewlyInstalled = false
   if (isInstalled('gh')) {
     p.log.success('GitHub CLI installed')
   } else {
-    const ghSpin = p.spinner()
-    ghSpin.start('Installing GitHub CLI')
+    ghNewlyInstalled = await brewInstall('gh', 'GitHub CLI')
+  }
+
+  // 5a. tmux (required for headless agent sessions)
+  if (isInstalled('tmux')) {
+    p.log.success('tmux installed')
+  } else {
+    await brewInstall('tmux', 'tmux')
+  }
+
+  // 5b. Surface gh auth status. Even if gh was already installed, we should
+  //     prompt the user to log in — agents that shell out to `gh` will fail
+  //     silently otherwise.
+  if (isInstalled('gh')) {
+    let authed = false
     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')
+      execSync('gh auth status', { stdio: 'ignore' })
+      authed = true
+    } catch { /* not authed */ }
+    if (authed) {
+      p.log.success('GitHub CLI authenticated')
+    } else {
+      p.log.warning(ghNewlyInstalled ? 'GitHub CLI installed but not logged in' : 'GitHub CLI is not logged in')
+      p.log.info(`  Run ${yellow('gh auth login')} to authenticate`)
     }
   }
 }
@@ -195,25 +247,102 @@ if (isInstalled('code')) {
   }
 }
 
-// 6a. Copilot CLI
-if (isInstalled('copilot')) {
-  p.log.success('Copilot CLI installed')
-} else {
-  const copilotSpin = p.spinner()
-  copilotSpin.start('Installing Copilot CLI')
-  try {
-    run('curl -fsSL https://gh.io/copilot-install | bash')
-    // Add ~/.local/bin to PATH if not already there
+// 6a. Coding agents (Copilot CLI / Claude Code / Codex CLI).
+//     On first-time setup, ask the user which agents they want installed.
+//     On subsequent runs, only install the previously-opted-in agents that
+//     went missing — never re-prompt to avoid being annoying after upgrades.
+{
+  const priorState = readUserState()
+  const priorAgents = priorState.agents || null
+  const firstRun = !priorState.setupVersion
+
+  const ensureLocalBinOnPath = () => {
     const localBin = `${process.env.HOME}/.local/bin`
     if (!process.env.PATH.includes(localBin)) {
       process.env.PATH = `${localBin}:${process.env.PATH}`
     }
-    copilotSpin.stop('Copilot CLI installed')
-    p.log.info(dim('  Note: You may need to restart your terminal or add ~/.local/bin to PATH'))
-  } catch {
-    copilotSpin.stop('Failed to install Copilot CLI')
-    p.log.warning('Install manually: curl -fsSL https://gh.io/copilot-install | bash')
   }
+
+  const installers = {
+    copilot: {
+      label: 'Copilot CLI',
+      bin: 'copilot',
+      install: async () => {
+        await runAsync('bash', ['-c', 'curl -fsSL https://gh.io/copilot-install | bash'])
+        ensureLocalBinOnPath()
+      },
+      manualHint: 'curl -fsSL https://gh.io/copilot-install | bash',
+      authHint: `Auth is separate from gh — run ${yellow('copilot')} then ${yellow('/login')}`,
+    },
+    claude: {
+      label: 'Claude Code',
+      bin: 'claude',
+      install: async () => {
+        await runAsync('bash', ['-c', 'curl -fsSL https://claude.ai/install.sh | bash'])
+        ensureLocalBinOnPath()
+      },
+      manualHint: 'curl -fsSL https://claude.ai/install.sh | bash',
+      authHint: `Run ${yellow('claude')} once to authenticate`,
+    },
+    codex: {
+      label: 'Codex CLI',
+      bin: 'codex',
+      install: async () => {
+        await runAsync('npm', ['install', '-g', '@openai/codex'])
+      },
+      manualHint: 'npm i -g @openai/codex',
+      authHint: `Run ${yellow('codex login')} to authenticate`,
+    },
+  }
+
+  let chosen
+  if (firstRun) {
+    const selection = await p.multiselect({
+      message: 'Which coding agents do you want installed?',
+      options: [
+        { value: 'copilot', label: 'Copilot CLI', hint: 'recommended' },
+        { value: 'claude', label: 'Claude Code' },
+        { value: 'codex', label: 'Codex CLI' },
+      ],
+      initialValues: ['copilot'],
+      required: false,
+    })
+    if (p.isCancel(selection)) {
+      chosen = { copilot: true, claude: false, codex: false }
+    } else {
+      chosen = Object.fromEntries(Object.keys(installers).map((k) => [k, selection.includes(k)]))
+    }
+  } else {
+    // Returning user — install only what they previously opted into and is
+    // currently missing. If we have no record (older setup), default to
+    // re-installing copilot only when missing.
+    chosen = priorAgents || { copilot: true, claude: false, codex: false }
+  }
+
+  for (const [key, agent] of Object.entries(installers)) {
+    if (!chosen[key]) continue
+    if (isInstalled(agent.bin)) {
+      p.log.success(`${agent.label} installed`)
+      p.log.info(`  ${agent.authHint}`)
+      continue
+    }
+    const spin = p.spinner()
+    spin.start(`Installing ${agent.label}`)
+    try {
+      await agent.install()
+      spin.stop(`${agent.label} installed`)
+      if (!isInstalled(agent.bin)) {
+        p.log.warning(`${agent.bin} not on PATH — add ${yellow('export PATH="$HOME/.local/bin:$PATH"')} to your shell rc`)
+      }
+      p.log.info(`  ${agent.authHint}`)
+    } catch {
+      spin.stop(`Failed to install ${agent.label}`)
+      p.log.warning(`Install manually: ${agent.manualHint}`)
+    }
+  }
+
+  // Persist the choice so future setups know what to keep installed.
+  writeUserState({ agents: chosen })
 }
 
 // 8. Git hooks
@@ -283,6 +412,8 @@ if (isInstalled('copilot')) {
     'src/canvas/~*/',
     'src/prototypes/~*/',
     'src/prototypes/**/~*.{flow,object,record,prototype,folder}.json',
+    // Per-user local state (setup version marker, agent prefs, future onboarding state)
+    '.storyboard/.user.json',
   ]
   if (existsSync(gitignorePath)) {
     try {
@@ -352,18 +483,26 @@ if (isInstalled('copilot')) {
 
 // 10. Install / sync dependencies
 {
+  const installSpin = p.spinner()
+  installSpin.start('Installing dependencies')
   try {
-    await withSpin(
-      'Installing dependencies...',
-      'Dependencies installed',
-      () => { run('npm install', { stdio: 'ignore' }) }
-    )
+    await runAsync('npm', ['install'])
+    installSpin.stop('Dependencies installed')
   } catch {
-    p.log.warning('npm install failed — run it manually to see details')
+    installSpin.stop('npm install failed')
+    p.log.warning('Run it manually to see details:')
     p.log.info(`  ${dim('npm install')}`)
   }
 }
 
+// 11. Stamp the user-state marker so `npm run dev` knows setup is fresh
+//     and won't re-run it until the storyboard package version changes.
+{
+  const version = getInstalledStoryboardVersion() || 'unknown'
+  writeUserState({ setupVersion: version, setupRanAt: new Date().toISOString() })
+  p.log.success(`Setup marker written (.storyboard/.user.json @ ${version})`)
+}
+
 p.note(
   [
     ...gettingStartedLines(),
@@ -380,8 +519,10 @@ p.note(
     const { runBranchGuide } = await import('./branch.js')
     await runBranchGuide(flags.branch)
   } else if (flags['skip-branch']) {
-    console.log()
-    console.log(mascot())
+    if (showMascot) {
+      console.log()
+      console.log(mascot())
+    }
     p.outro('')
   } else {
     // Interactive: ask the user
@@ -403,8 +544,10 @@ p.note(
       const { runBranchGuide } = await import('./branch.js')
       await runBranchGuide()
     } else {
-      console.log()
-      console.log(mascot())
+      if (showMascot) {
+        console.log()
+        console.log(mascot())
+      }
       p.log.info(`${dim('Non-interactive:')} ${green('npx sb setup --skip-branch')}`)
       p.outro('')
     }

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

@@ -17,11 +17,12 @@
 
 import * as p from '@clack/prompts'
 import { execSync, spawn } from 'node:child_process'
-import { readFileSync, existsSync } from 'node:fs'
-import { resolve, join } from 'node:path'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { parseFlags } from './flags.js'
 import { dim, bold } from './intro.js'
 import { takePendingMessages } from '../canvas/terminal-config.js'
+import { readAgentsConfig } from '../canvas/configReader.js'
 
 const blue = (s) => `\x1b[34m${s}\x1b[0m`
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`
@@ -76,14 +77,12 @@ function agentEnv() {
 }
 
 /**
- * Read agents config from storyboard.config.json.
+ * Read agents config (lib defaults + storyboard.config.json + terminal.config.json merged).
  * Returns an array of { id, label, startupCommand, resumeCommand } entries.
  */
 function loadAgents() {
   try {
-    const raw = readFileSync(resolve(process.cwd(), 'storyboard.config.json'), 'utf8')
-    const config = JSON.parse(raw)
-    const agents = config?.canvas?.agents
+    const agents = readAgentsConfig()
     if (!agents || typeof agents !== 'object') return []
     return Object.entries(agents).map(([id, cfg]) => ({
       id,

package/src/core/cli/userState.js

@@ -0,0 +1,63 @@
+/**
+ * userState — Per-user local state for the current repo, stored in
+ * `.storyboard/.user.json` (gitignored).
+ *
+ * This is a free-form key/value bag for things that should persist across
+ * runs but never be committed:
+ *   - setupVersion   (string) — @dfosco/storyboard version setup was last
+ *     run against. Compared against the installed version on `npm run dev`
+ *     to decide whether scaffolding needs to re-run.
+ *   - setupRanAt     (ISO date) — last setup timestamp.
+ *   - agents         (object) — per-agent opt-in flags from the
+ *     first-run install prompt (copilot/claude/codex booleans).
+ *   - … future:        onboarded, username, lastSeenChangelog, etc.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+
+const FILE = '.storyboard/.user.json'
+
+export function userStatePath(cwd = process.cwd()) {
+  return resolve(cwd, FILE)
+}
+
+export function readUserState(cwd = process.cwd()) {
+  const file = userStatePath(cwd)
+  if (!existsSync(file)) return {}
+  try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return {} }
+}
+
+export function writeUserState(patch, cwd = process.cwd()) {
+  const file = userStatePath(cwd)
+  const dir = dirname(file)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const next = { ...readUserState(cwd), ...patch }
+  writeFileSync(file, JSON.stringify(next, null, 2) + '\n', 'utf8')
+  return next
+}
+
+/**
+ * Read the installed @dfosco/storyboard package version, or null if not
+ * resolvable (e.g. running from a worktree without node_modules).
+ */
+export function getInstalledStoryboardVersion(cwd = process.cwd()) {
+  try {
+    const pkgPath = resolve(cwd, 'node_modules', '@dfosco', 'storyboard', 'package.json')
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || null
+  } catch { return null }
+}
+
+/**
+ * Decide whether `storyboard setup` should run before `dev`.
+ * Returns null when up-to-date, or { reason, ... } otherwise.
+ */
+export function setupNeeded(cwd = process.cwd()) {
+  const state = readUserState(cwd)
+  const current = getInstalledStoryboardVersion(cwd)
+  if (!state.setupVersion) return { reason: 'first-run', current }
+  if (current && state.setupVersion !== current) {
+    return { reason: 'version-changed', from: state.setupVersion, to: current }
+  }
+  return null
+}

package/src/core/stores/configSchema.js

@@ -65,6 +65,7 @@
  * @property {string}  [sessionIdEnv]   — env var exposed in the agent's SessionStart hook payload that holds its session id (e.g. "COPILOT_AGENT_SESSION_ID"). When set, the server captures the id per-widget so cold restarts can auto-resume.
  * @property {string}  [sessionStateDir] — directory where the agent stores per-session state, used to pre-flight `--resume` (e.g. "~/.copilot/session-state"). Pass `null` to skip the fs check (UUID-only validation).
  * @property {string}  [sessionStateGlob] — alternative to sessionStateDir for agents that store sessions under a per-project subdir, with `{id}` placeholder (e.g. "~/.claude/projects/*‍/{id}.jsonl").
+ * @property {boolean} [resumeFallback]  — when true (default), the resume command is shell-chained with `|| <startupCommand>` so a runtime resume failure falls through to a fresh session instead of leaving the widget with a dead terminal. Set false to opt out.
  * @property {boolean} [resizable]     — override terminal resizability for this agent
  * @property {number}  [defaultWidth]  — override default width
  * @property {number}  [defaultHeight] — override default height

package/src/core/stores/themeStore.ts

@@ -218,6 +218,30 @@ if (typeof window !== 'undefined') {
       _applyToDOM('system', state.resolved)
       _dispatchEvent('system', state.resolved)
     })
+
+  // Cross-frame sync: the native `storage` event fires in OTHER windows
+  // when localStorage is mutated. Prototype iframes embed the same app on
+  // the same origin, so when the parent toolbar flips the theme we must
+  // pick that up here and re-apply the DOM attributes / dispatch the
+  // theme-changed event. Without this, Tailwind utilities (and Primer
+  // CSS vars) inside the iframe stay stuck on the load-time theme.
+  window.addEventListener('storage', (e) => {
+    if (e.storageArea !== localStorage) return
+    if (e.key === STORAGE_KEY || e.key === null) {
+      const next = readStoredTheme()
+      _current = next
+      const state = snapshot(next)
+      _store.set(state)
+      _applyToDOM(next, state.resolved)
+      _dispatchEvent(next, state.resolved)
+    } else if (e.key === SYNC_STORAGE_KEY) {
+      _syncTargets = readStoredSync()
+      _syncStore.set(_syncTargets)
+      const state = snapshot(_current)
+      _applyToDOM(_current, state.resolved)
+      _dispatchEvent(_current, state.resolved)
+    }
+  })
 }
 
 // ---------------------------------------------------------------------------

package/src/core/tools/handlers/devtools.test.js

@@ -76,7 +76,7 @@ describe('devtools prototype auto-reload toggle', () => {
     window.history.replaceState({}, '', '/')
   })
 
-  it('shows the toggle as inactive by default (guard ON)', async () => {
+  it('shows the toggle as inactive by default (guard ON, auto-reload OFF)', async () => {
     const devtools = await createDevtoolsHandler({})
     const item = getPrototypeAutoReloadItem(devtools.getChildren())