@dfosco/storyboard 0.5.0-alpha.0

package/src/core/cli/flags.js

@@ -0,0 +1,174 @@
+/**
+ * Shared CLI flag parser — converts argv into a validated flags object.
+ *
+ * Supports:
+ *   --key value       string/number value
+ *   --key=value       equals-separated
+ *   --bool            boolean true
+ *   --no-bool         boolean false (negation prefix)
+ *   --key a --key b   repeated flags → array
+ *
+ * Usage:
+ *   const { flags, missing, errors } = parseFlags(process.argv.slice(3), schema)
+ */
+
+/**
+ * @typedef {Object} FlagDef
+ * @property {'string'|'boolean'|'number'|'array'} type
+ * @property {boolean} [required]
+ * @property {*} [default]
+ * @property {string} [description]
+ * @property {string[]} [aliases] - short or alternate names (without --)
+ */
+
+/**
+ * @typedef {Object<string, FlagDef>} FlagSchema
+ */
+
+/**
+ * Parse argv tokens against a schema.
+ *
+ * @param {string[]} argv - process.argv tokens (after command words are stripped)
+ * @param {FlagSchema} schema
+ * @returns {{ flags: Object, positional: string[], missing: string[], errors: string[] }}
+ */
+export function parseFlags(argv, schema) {
+  const flags = {}
+  const positional = []
+  const errors = []
+
+  // Build alias → canonical name map
+  const aliasMap = {}
+  for (const [name, def] of Object.entries(schema)) {
+    aliasMap[name] = name
+    if (def.aliases) {
+      for (const alias of def.aliases) {
+        aliasMap[alias] = name
+      }
+    }
+  }
+
+  // Seed defaults
+  for (const [name, def] of Object.entries(schema)) {
+    if (def.default !== undefined) {
+      flags[name] = def.default
+    }
+  }
+
+  let i = 0
+  while (i < argv.length) {
+    const token = argv[i]
+
+    if (!token.startsWith('-')) {
+      positional.push(token)
+      i++
+      continue
+    }
+
+    // Strip leading dashes
+    let raw = token.replace(/^--?/, '')
+    let value
+
+    // Handle --key=value
+    const eqIdx = raw.indexOf('=')
+    if (eqIdx !== -1) {
+      value = raw.slice(eqIdx + 1)
+      raw = raw.slice(0, eqIdx)
+    }
+
+    // Handle --no-<key> negation
+    let negated = false
+    if (raw.startsWith('no-') && !aliasMap[raw]) {
+      const candidate = raw.slice(3)
+      if (aliasMap[candidate]) {
+        raw = candidate
+        negated = true
+      }
+    }
+
+    const canonical = aliasMap[raw]
+    if (!canonical) {
+      errors.push(`Unknown flag: --${raw}`)
+      i++
+      continue
+    }
+
+    const def = schema[canonical]
+
+    if (def.type === 'boolean') {
+      if (value !== undefined) {
+        // Handle --flag=true / --flag=false
+        const lower = value.toLowerCase()
+        if (lower === 'true' || lower === '1') flags[canonical] = !negated
+        else if (lower === 'false' || lower === '0') flags[canonical] = negated
+        else errors.push(`Flag --${raw} is boolean; use --${raw}, --no-${raw}, or --${raw}=true|false`)
+      } else {
+        flags[canonical] = !negated
+      }
+      i++
+      continue
+    }
+
+    // Consume next token as value if we didn't get one from `=`
+    if (value === undefined) {
+      i++
+      if (i >= argv.length) {
+        errors.push(`Flag --${raw} requires a value`)
+        continue
+      }
+      value = argv[i]
+    }
+
+    if (def.type === 'number') {
+      const num = Number(value)
+      if (Number.isNaN(num)) {
+        errors.push(`Flag --${raw} must be a number, got "${value}"`)
+      } else {
+        flags[canonical] = num
+      }
+    } else if (def.type === 'array') {
+      if (!Array.isArray(flags[canonical])) flags[canonical] = []
+      flags[canonical].push(value)
+    } else {
+      // string (or JSON for object-typed flags)
+      flags[canonical] = value
+    }
+
+    i++
+  }
+
+  // Check required
+  const missing = []
+  for (const [name, def] of Object.entries(schema)) {
+    if (def.required && (flags[name] === undefined || flags[name] === '')) {
+      missing.push(name)
+    }
+  }
+
+  return { flags, positional, missing, errors }
+}
+
+/**
+ * Check if any flags were provided (beyond defaults).
+ * Useful to decide interactive vs non-interactive mode.
+ */
+export function hasFlags(argv) {
+  return argv.some((t) => t.startsWith('-'))
+}
+
+/**
+ * Format a schema into help text lines.
+ *
+ * @param {FlagSchema} schema
+ * @returns {string}
+ */
+export function formatFlagHelp(schema) {
+  const lines = []
+  for (const [name, def] of Object.entries(schema)) {
+    const aliases = def.aliases ? def.aliases.map((a) => `-${a}`).join(', ') + ', ' : ''
+    const req = def.required ? ' (required)' : ''
+    const defVal = def.default !== undefined ? ` [default: ${def.default}]` : ''
+    lines.push(`  ${aliases}--${name.padEnd(16)} ${def.description || ''}${req}${defVal}`)
+  }
+  return lines.join('\n')
+}

package/src/core/cli/flags.test.js

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { parseFlags, hasFlags, formatFlagHelp } from './flags.js'
+
+const testSchema = {
+  name: { type: 'string', required: true, description: 'Name', aliases: ['n'] },
+  title: { type: 'string', description: 'Title', aliases: ['t'] },
+  count: { type: 'number', description: 'Count', default: 0 },
+  verbose: { type: 'boolean', description: 'Verbose', default: false },
+  tags: { type: 'array', description: 'Tags', aliases: ['g'] },
+}
+
+describe('parseFlags', () => {
+  it('parses --key value pairs', () => {
+    const { flags } = parseFlags(['--name', 'hello', '--title', 'world'], testSchema)
+    expect(flags.name).toBe('hello')
+    expect(flags.title).toBe('world')
+  })
+
+  it('parses --key=value syntax', () => {
+    const { flags } = parseFlags(['--name=hello'], testSchema)
+    expect(flags.name).toBe('hello')
+  })
+
+  it('parses short aliases', () => {
+    const { flags } = parseFlags(['-n', 'hello', '-t', 'world'], testSchema)
+    expect(flags.name).toBe('hello')
+    expect(flags.title).toBe('world')
+  })
+
+  it('parses boolean flags', () => {
+    const { flags } = parseFlags(['--verbose', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('parses --no- negation for booleans', () => {
+    const { flags } = parseFlags(['--no-verbose', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('parses --flag=false for booleans', () => {
+    const { flags } = parseFlags(['--verbose=false', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('parses --flag=true for booleans', () => {
+    const { flags } = parseFlags(['--verbose=true', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('parses --no-flag=false as double negation (true)', () => {
+    const { flags } = parseFlags(['--no-verbose=false', '--name', 'x'], testSchema)
+    expect(flags.verbose).toBe(true)
+  })
+
+  it('reports error for invalid boolean value', () => {
+    const { errors } = parseFlags(['--verbose=maybe', '--name', 'x'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('boolean')
+  })
+
+  it('parses number flags', () => {
+    const { flags } = parseFlags(['--name', 'x', '--count', '42'], testSchema)
+    expect(flags.count).toBe(42)
+  })
+
+  it('reports error for non-numeric number flag', () => {
+    const { errors } = parseFlags(['--name', 'x', '--count', 'abc'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('must be a number')
+  })
+
+  it('collects repeated flags into arrays', () => {
+    const { flags } = parseFlags(['--name', 'x', '-g', 'a', '-g', 'b'], testSchema)
+    expect(flags.tags).toEqual(['a', 'b'])
+  })
+
+  it('collects positional arguments', () => {
+    const { positional } = parseFlags(['sticky-note', '--name', 'x'], testSchema)
+    expect(positional).toEqual(['sticky-note'])
+  })
+
+  it('reports missing required flags', () => {
+    const { missing } = parseFlags(['--title', 'hello'], testSchema)
+    expect(missing).toContain('name')
+  })
+
+  it('does not report missing when required flag is provided', () => {
+    const { missing } = parseFlags(['--name', 'hello'], testSchema)
+    expect(missing).not.toContain('name')
+  })
+
+  it('reports unknown flags', () => {
+    const { errors } = parseFlags(['--name', 'x', '--unknown', 'y'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('Unknown flag')
+  })
+
+  it('applies defaults', () => {
+    const { flags } = parseFlags(['--name', 'x'], testSchema)
+    expect(flags.count).toBe(0)
+    expect(flags.verbose).toBe(false)
+  })
+
+  it('reports error when value flag has no value', () => {
+    const { errors } = parseFlags(['--name'], testSchema)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain('requires a value')
+  })
+
+  it('returns empty results for empty argv', () => {
+    const { flags, positional, missing, errors } = parseFlags([], testSchema)
+    expect(positional).toEqual([])
+    expect(errors).toEqual([])
+    expect(missing).toContain('name')
+    expect(flags.count).toBe(0)
+  })
+})
+
+describe('hasFlags', () => {
+  it('returns true when argv has flags', () => {
+    expect(hasFlags(['--name', 'x'])).toBe(true)
+  })
+
+  it('returns true for short flags', () => {
+    expect(hasFlags(['-n', 'x'])).toBe(true)
+  })
+
+  it('returns false when no flags', () => {
+    expect(hasFlags(['positional'])).toBe(false)
+  })
+
+  it('returns false for empty argv', () => {
+    expect(hasFlags([])).toBe(false)
+  })
+})
+
+describe('formatFlagHelp', () => {
+  it('includes flag names and descriptions', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('--name')
+    expect(output).toContain('Name')
+    expect(output).toContain('(required)')
+  })
+
+  it('includes aliases', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('-n')
+  })
+
+  it('includes defaults', () => {
+    const output = formatFlagHelp(testSchema)
+    expect(output).toContain('[default: 0]')
+    expect(output).toContain('[default: false]')
+  })
+})

package/src/core/cli/index.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * storyboard CLI — unified dev tooling for Storyboard projects.
+ *
+ * Commands:
+ *   storyboard dev              Start Vite dev server + update proxy
+ *   storyboard setup            Install deps, Caddy, start proxy
+ *   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
+ *
+ * Aliases: `sb` is equivalent to `storyboard`.
+ */
+
+import * as p from '@clack/prompts'
+import { readFileSync } from 'fs'
+import { resolve } from 'path'
+import { gettingStartedLines, dim, magenta, cyan, green, bold, yellow } from './intro.js'
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(import.meta.dirname, '..', '..', 'package.json'), 'utf8'))
+    return pkg.version || '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+function helpScreen(version) {
+  const d = dim('·')
+  const b = dim
+  const f = magenta
+
+  const mascot = [
+    `  ${b('╭─────────────────╮')}`,
+    `  ${b('│')}  ${d}  ${f('◠')}  ${f('◡')}  ${f('◠')}  ${d}  ${b('│')}  ${bold('storyboard')} ${dim(`v${version}`)}`,
+    `  ${b('│')}  ${d}  ${d}  ${d}  ${d}  ${d}  ${b('│')}  ${dim('A design tool for prototyping')}`,
+    `  ${b('╰─────────────────╯')}`,
+  ].join('\n')
+
+  const cmd = (name, desc) => `    ${green(name.padEnd(22))}${desc}`
+
+  const gettingStarted = [
+    '',
+    ...gettingStartedLines(),
+  ].join('\n')
+
+  const commands = [
+    '',
+    `  ${bold('All commands:')}`,
+    '',
+    `  ${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'),
+    '',
+    `  ${bold(cyan('Create'))}`,
+    cmd('create', 'Interactive creation picker'),
+    cmd('create prototype', 'Create a prototype'),
+    cmd('create canvas', 'Create a canvas'),
+    cmd('create flow', 'Create a flow for a prototype'),
+    cmd('create page', 'Create a page in a prototype'),
+    '',
+    `  ${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'),
+    '',
+    `  ${bold(cyan('Terminal'))}`,
+    cmd('terminal', 'Browse and manage terminal sessions'),
+    cmd('terminal start', 'Launch the terminal welcome prompt'),
+    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('setup --skip-branch', 'Non-interactive setup (skip branch prompt)'),
+    cmd('setup --branch=<name>', 'Setup + switch to a branch'),
+    cmd('branch', 'Switch to a branch (interactive worktree guide)'),
+    cmd('branch <name>', 'Switch to a specific branch directly'),
+    cmd('branch --worktree=<name>', 'Non-interactive branch switch'),
+    cmd('proxy start', 'Start or reload Caddy proxy'),
+    cmd('proxy close', 'Stop Caddy proxy'),
+    '',
+    `  ${bold(cyan('Updates'))}`,
+    cmd('update', 'Update storyboard packages to latest'),
+    cmd('update:<tag>', 'Update to a specific tag ' + dim('(beta, alpha, ...)')),
+    '',
+    `  ${dim('All create commands accept --flags for non-interactive use.')}`,
+    `  ${dim('Run')} ${yellow('npx storyboard create <type> --help')} ${dim('for flag details.')}`,
+    '',
+    `  ${dim('Usage:')} ${yellow('npx storyboard')} ${dim('<command>')}`,
+    `  ${dim('Alias:')} ${yellow('npx sb')} ${dim('<command>')}`,
+  ].join('\n')
+
+  return `\n${mascot}\n${gettingStarted}\n${commands}\n`
+}
+
+const command = process.argv[2]
+
+switch (command) {
+  case 'dev':
+    import('./dev.js')
+    break
+  case 'setup':
+    import('./setup.js')
+    break
+  case 'branch':
+    import('./branch.js')
+    break
+  case 'proxy':
+    import('./proxy.js')
+    break
+  case 'create':
+    import('./create.js')
+    break
+  case 'compact':
+    import('./compact.js')
+    break
+  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))
+      p.log.error(`Unknown canvas subcommand: ${bold(process.argv[3] || '(none)')}`)
+      process.exit(1)
+    }
+    break
+  case 'exit':
+    import('./exit.js')
+    break
+  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')
+    }
+    break
+  case 'sessions':
+    // Backwards compat alias
+    import('./sessions.js')
+    break
+  case 'terminal-welcome':
+    // Internal alias used by terminal-server
+    import('./terminal-welcome.js')
+    break
+  case 'server':
+    import('./server.js')
+    break
+  case 'agent':
+    import('./agent.js')
+    break
+  case 'code':
+    import('./code.js')
+    break
+  default: {
+    if (command === 'update' || (command && command.startsWith('update:'))) {
+      import('./updateVersion.js')
+      break
+    }
+    const version = getVersion()
+
+    if (command) {
+      console.log(helpScreen(version))
+      p.log.error(`Unknown command: ${bold(command)}`)
+      process.exit(1)
+    }
+
+    console.log(helpScreen(version))
+  }
+}

package/src/core/cli/intro.js

@@ -0,0 +1,37 @@
+/**
+ * Single source of truth for CLI getting-started content.
+ * Used by both `storyboard setup` and the help screen (`storyboard`).
+ */
+
+// ANSI helpers — shared across CLI modules
+export const dim = (s) => `\x1b[2m${s}\x1b[0m`
+export const magenta = (s) => `\x1b[35m${s}\x1b[0m`
+export const cyan = (s) => `\x1b[36m${s}\x1b[0m`
+export const green = (s) => `\x1b[32m${s}\x1b[0m`
+export const bold = (s) => `\x1b[1m${s}\x1b[0m`
+export const white = (s) => `\x1b[97m${s}\x1b[0m`
+export const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+
+/**
+ * Returns the getting-started intro lines as an array of strings.
+ * @param {object} [opts]
+ * @param {string} [opts.indent='  '] Prefix for each non-empty line
+ */
+export function gettingStartedLines({ indent = '  ' } = {}) {
+  const i = indent
+  return [
+    `${i}Welcome! Storyboard is a design tool to build and`,
+    `${i}collaborate on prototypes. Here's how to get started:`,
+    '',
+    `${i}  ${green('npx storyboard dev')}                Start developing locally`,
+    `${i}  ${green('npx storyboard create prototype')}   Create a prototype`,
+    `${i}  ${green('npx storyboard create canvas')}      Create a canvas`,
+    `${i}  ${green('npx storyboard create component')}   Create a component (.story.jsx)`,
+    `${i}  ${green('npx storyboard canvas add sticky-note')}  Add a widget to a canvas`,
+    '',
+    `${i}  ${dim('Using an AI assistant? You can also ask it to')}`,
+    `${i}  ${dim('"create a prototype", "create a canvas" or "create a component" for you!')}`,
+    '',
+    `${i}  ${dim('Docs:')} ${cyan('https://github.com/dfosco/storyboard/blob/main/README.md')}`,
+  ]
+}