@dfosco/storyboard 0.6.0-beta.6 → 0.6.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.0-beta.6",
+  "version": "0.6.0-beta.8",
   "type": "module",
   "license": "MIT",
   "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/src/core/canvas/server.js

@@ -3103,7 +3103,10 @@ export function Default() {
         // Write env file for this terminal session — sourced before copilot launch
         // This avoids race conditions with tmux send-keys export
         const envFile = path.join(root, '.storyboard', 'terminals', `${tmuxName}.env`)
-        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\n'
+        // Trailing echo is the readiness signal the post-startup poller
+        // matches against. Don't drop it — without it /allow-all and the
+        // identity/role/broadcast bind wait the full 30s timeout fallback.
+        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\necho "Environment loaded:"\n'
         fsModule.writeFileSync(envFile, envContent)
 
         // Resolve agent config from storyboard.config.json

package/src/core/canvas/terminal-server.js

@@ -1245,11 +1245,17 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
         try { mkdirSync(envScriptDir, { recursive: true }) } catch { /* empty */ }
         const envScriptPath = join(envScriptDir, `${widgetId}.env.sh`)
         try {
-          writeFileSync(envScriptPath, envParts.join('\n') + '\n')
+          // Trailing echo is the readiness signal the post-startup poller
+          // looks for. Without it, the 30s timeout fallback fires before
+          // /allow-all, identity, role/broadcast bind are sent — making
+          // the agent feel "stuck" for the first half-minute after launch.
+          writeFileSync(envScriptPath, envParts.join('\n') + '\necho "Environment loaded:"\n')
         } catch { /* empty */ }
-        const envSourceCmd = startupCommand
-          ? `clear && source ${JSON.stringify(envScriptPath)} && clear`
-          : `source ${JSON.stringify(envScriptPath)}`
+        // Source env script; the trailing readiness echo MUST remain on
+        // the pane so the post-startup poller can match it. Don't append
+        // a `clear` here — the welcomeCmd that runs next clears the pane
+        // itself before launching the agent.
+        const envSourceCmd = `source ${JSON.stringify(envScriptPath)}`
 
         setTimeout(() => {
           try {

package/src/core/cli/dev.js

@@ -21,6 +21,21 @@ import { detectWorktreeName, getPort, releasePort } from '../worktree/port.js'
 import { startRenameWatcher } from '../rename-watcher/watcher.js'
 import { compactAll } from '../canvas/compact.js'
 import { parseFlags } from './flags.js'
+import { setupNeeded, writeUserState, getInstalledStoryboardVersion } from './userState.js'
+import { dim, magenta, bold } from './intro.js'
+
+/** Render the storyboard mascot with two info lines beside it. */
+function mascotBanner(line1, line2) {
+  const d = dim('·')
+  const f = magenta
+  const b = dim
+  return [
+    `        ${b('╭─────────────────╮')}`,
+    `        ${b('│')}  ${d}  ${f('◠')}  ${f('◡')}  ${f('◠')}  ${d}  ${b('│')}  ${line1}`,
+    `        ${b('│')}  ${d}  ${d}  ${d}  ${d}  ${d}  ${b('│')}  ${line2}`,
+    `        ${b('╰─────────────────╯')}`,
+  ].join('\n')
+}
 
 const flagSchema = {
   port: { type: 'number', description: 'Override dev server port' },
@@ -55,6 +70,34 @@ async function main() {
   p.intro('storyboard dev')
   p.log.info(`worktree: ${worktreeName}`)
 
+  // Re-run setup automatically if it has never run here, or if the installed
+  // @dfosco/storyboard version no longer matches the one setup was last run
+  // against. This lets `npm install` upgrades trigger fresh scaffolding
+  // without requiring `npx storyboard update`.
+  {
+    const need = setupNeeded(targetCwd)
+    if (need) {
+      const why = need.reason === 'first-run'
+        ? 'first run in this repo'
+        : `version changed ${need.from} → ${need.to}`
+      p.log.info(`Running setup (${why})…`)
+      await new Promise((resolveSetup) => {
+        const setupChild = spawn(
+          process.platform === 'win32' ? 'npx.cmd' : 'npx',
+          ['storyboard', 'setup', '--skip-branch'],
+          { cwd: targetCwd, stdio: 'inherit' }
+        )
+        setupChild.on('exit', () => resolveSetup())
+        setupChild.on('error', () => resolveSetup())
+      })
+      // Belt-and-suspenders: even if setup failed to write the marker,
+      // stamp the current version so dev doesn't loop forever asking to run
+      // setup on every boot.
+      const version = getInstalledStoryboardVersion(targetCwd)
+      if (version) writeUserState({ setupVersion: version, setupRanAt: new Date().toISOString() }, targetCwd)
+    }
+  }
+
   // Compact bloated canvas JSONL files before booting Vite.
   const compacted = compactAll(targetCwd)
   for (const r of compacted) {
@@ -78,15 +121,23 @@ async function main() {
   const viteArgs = ['vite', '--port', String(port)]
   if (strictPort) viteArgs.push('--strictPort')
   if (strictPort) p.log.info(`port ${port} (strict — from storyboard.config.json)`)
+
+  // Render the storyboard mascot just before Vite takes over stdio. The
+  // mascot acts as a visual anchor between our setup output and Vite's
+  // own "ready in Xms" banner.
+  console.log()
+  console.log(mascotBanner(
+    bold(`http://localhost:${port}/storyboard/`),
+    dim('Stop with Ctrl+C'),
+  ))
+  console.log()
+
   const child = spawn(npmBin, viteArgs, {
     cwd: targetCwd,
     stdio: 'inherit',
     env: { ...process.env, STORYBOARD_WORKTREE: worktreeName },
   })
 
-  p.log.success(`http://localhost:${port}/storyboard/`)
-  p.log.info('Stop with Ctrl+C')
-
   function shutdown() {
     clearInterval(compactInterval)
     renameWatcher.close()

package/src/core/cli/setup.js

@@ -15,6 +15,7 @@ import path from 'path'
 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' },
@@ -259,38 +260,102 @@ if (isInstalled('code')) {
   }
 }
 
-// 6a. Copilot CLI — install via the official script (no homebrew dependency).
-//     curl ships with macOS and all major Linux distros.
-//     Auth is separate from `gh`: copilot has its own credential store.
+// 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.
 {
-  let copilotNewlyInstalled = false
-  if (isInstalled('copilot')) {
-    p.log.success('Copilot CLI installed')
+  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}`
+    }
+  }
+
+  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 Copilot CLI')
+    spin.start(`Installing ${agent.label}`)
     try {
-      await runAsync('bash', ['-c', 'curl -fsSL https://gh.io/copilot-install | bash'])
-      // Install script drops the binary in ~/.local/bin when run as
-      // non-root. Make sure the current process can find it for the
-      // remainder of setup, and warn the user to add it to their shell rc.
-      const localBin = `${process.env.HOME}/.local/bin`
-      if (!process.env.PATH.includes(localBin)) {
-        process.env.PATH = `${localBin}:${process.env.PATH}`
-      }
-      spin.stop('Copilot CLI installed')
-      copilotNewlyInstalled = true
-      if (!isInstalled('copilot')) {
-        p.log.warning(`copilot not on PATH — add ${yellow('export PATH="$HOME/.local/bin:$PATH"')} to your shell rc`)
+      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 Copilot CLI')
-      p.log.warning('Install manually: curl -fsSL https://gh.io/copilot-install | bash')
+      spin.stop(`Failed to install ${agent.label}`)
+      p.log.warning(`Install manually: ${agent.manualHint}`)
     }
   }
-  if (copilotNewlyInstalled || isInstalled('copilot')) {
-    p.log.info(`  Auth is separate from gh — run ${yellow('copilot')} then ${yellow('/login')}`)
-  }
+
+  // Persist the choice so future setups know what to keep installed.
+  writeUserState({ agents: chosen })
 }
 
 // 8. Git hooks
@@ -360,6 +425,8 @@ if (isInstalled('code')) {
     '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 {
@@ -441,6 +508,14 @@ if (isInstalled('code')) {
   }
 }
 
+// 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(),

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
+}