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

package/src/cli/index.js

@@ -16,6 +16,7 @@
 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 {
@@ -26,6 +27,67 @@ function getVersion() {
   }
 }
 
+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('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 read [name]', 'Read canvas state and list widgets'),
+    cmd('snapshots [name]', 'Generate preview snapshots for canvas widgets'),
+    `                              ${dim('--force to regenerate existing snapshots')}`,
+    '',
+    `  ${bold(cyan('Setup'))}`,
+    cmd('setup', 'Install deps, Caddy proxy, start proxy'),
+    cmd('proxy', 'Generate Caddyfile + start/reload Caddy'),
+    '',
+    `  ${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) {
@@ -41,31 +103,40 @@ switch (command) {
   case 'create':
     import('./create.js')
     break
+  case 'canvas':
+    if (process.argv[3] === 'add') {
+      import('./canvasAdd.js')
+    } else if (process.argv[3] === 'read' || !process.argv[3]) {
+      import('./canvasRead.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 'snapshots':
+    import('./snapshots.js')
+    break
   case 'exit':
     import('./exit.js')
     break
+  case 'code':
+    import('./code.js')
+    break
   default: {
     if (command === 'update' || (command && command.startsWith('update:'))) {
       import('./updateVersion.js')
       break
     }
     const version = getVersion()
-    p.intro(`storyboard v${version}`)
-    p.log.message(`Commands:
-  dev              Start Vite dev server + update proxy
-  create           Create a prototype or canvas
-  setup            Install deps, Caddy proxy, start proxy
-  proxy            Generate Caddyfile + start/reload Caddy
-  exit             Stop all dev servers and proxy
-  update               Update storyboard packages to latest
-  update:<version>     Update to specific version
-  update:beta          Update to latest beta
-  update:alpha         Update to latest alpha`)
 
     if (command) {
-      p.log.error(`Unknown command: ${command}`)
+      console.log(helpScreen(version))
+      p.log.error(`Unknown command: ${bold(command)}`)
       process.exit(1)
     }
-    p.outro('Run: npx storyboard <command>')
+
+    console.log(helpScreen(version))
   }
 }

package/src/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')}`,
+  ]
+}

package/src/cli/proxy.js

@@ -14,9 +14,9 @@ import { execSync } from 'child_process'
 import { dirname, resolve } from 'path'
 import { portsFilePath } from '../worktree/port.js'
 
-export function readDevDomain() {
+export function readDevDomain(cwd) {
   try {
-    const configPath = resolve(process.cwd(), 'storyboard.config.json')
+    const configPath = resolve(cwd || process.cwd(), 'storyboard.config.json')
     const config = JSON.parse(readFileSync(configPath, 'utf8'))
     return `${config.devDomain || 'storyboard'}.localhost`
   } catch {
@@ -95,6 +95,124 @@ export function reloadCaddy(caddyfilePath) {
   }
 }
 
+// ── Caddy admin API (additive route upsert) ──
+
+const CADDY_ADMIN = 'http://localhost:2019'
+
+/**
+ * Build a Caddy JSON route object for this repo's devDomain.
+ * Tagged with @id so it can be upserted independently of other repos.
+ */
+export function generateRouteConfig(portOverrides = {}) {
+  const portsFile = portsFilePath()
+  let ports = { main: 1234 }
+  if (existsSync(portsFile)) {
+    try { ports = JSON.parse(readFileSync(portsFile, 'utf8')) } catch { /* use defaults */ }
+  }
+  Object.assign(ports, portOverrides)
+
+  const mainPort = ports.main || 1234
+  const branches = Object.entries(ports).filter(([name]) => name !== 'main')
+
+  // Branch subroutes first (more specific), then main fallback
+  const subroutes = branches.map(([name, port]) => ({
+    match: [{ path: [`/branch--${name}/*`] }],
+    handle: [{ handler: 'reverse_proxy', upstreams: [{ dial: `localhost:${port}` }] }],
+  }))
+  subroutes.push({
+    handle: [{ handler: 'reverse_proxy', upstreams: [{ dial: `localhost:${mainPort}` }] }],
+  })
+
+  return {
+    '@id': DOMAIN.replace('.localhost', ''),
+    match: [{ host: [DOMAIN] }],
+    handle: [{ handler: 'subroute', routes: subroutes }],
+  }
+}
+
+/**
+ * Find indices of stale routes that match the same host but lack an @id.
+ * Returns indices sorted descending (highest first) for safe deletion.
+ * Exported for testing.
+ */
+export function findStaleRouteIndices(routes, keepId, host) {
+  const indices = []
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i]
+    if (route['@id'] === keepId) continue
+    if (route['@id']) continue // different intentional route — leave it
+    const routeHosts = route.match?.[0]?.host || []
+    if (routeHosts.includes(host)) {
+      indices.push(i)
+    }
+  }
+  return indices.reverse()
+}
+
+/**
+ * Remove stale routes that match the same host but lack an @id.
+ * These are leftovers from Caddyfile reloads that shadow admin-API routes.
+ * Deletes from highest index to lowest to preserve indices during removal.
+ * Best-effort — warns on failure but does not throw.
+ */
+function cleanupDuplicateRoutes(keepId, host) {
+  try {
+    const config = execSync(
+      `curl -sf '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes'`,
+      { encoding: 'utf-8', timeout: 5000 },
+    )
+    const routes = JSON.parse(config)
+    const staleIndices = findStaleRouteIndices(routes, keepId, host)
+    for (const idx of staleIndices) {
+      try {
+        execSync(
+          `curl -sf -X DELETE '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes/${idx}'`,
+          { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
+        )
+      } catch {
+        console.warn(`[storyboard] failed to remove stale proxy route at index ${idx}`)
+      }
+    }
+  } catch {
+    console.warn('[storyboard] failed to clean up stale proxy routes — branch URLs may not work via proxy')
+  }
+}
+
+/**
+ * Upsert this repo's route in the running Caddy instance via admin API.
+ * Uses PATCH if the @id exists, POST if it doesn't.
+ * After a successful upsert, removes any stale non-@id routes for the
+ * same host (leftovers from prior Caddyfile reloads).
+ * Returns true on success, false on failure.
+ */
+export function upsertCaddyRoute(routeConfig) {
+  const id = routeConfig['@id']
+  const host = routeConfig.match?.[0]?.host?.[0]
+  const payload = JSON.stringify(routeConfig)
+
+  // Try PATCH first (update existing route by @id)
+  try {
+    execSync(
+      `curl -sf -X PATCH '${CADDY_ADMIN}/id/${id}' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
+      { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+    if (host) cleanupDuplicateRoutes(id, host)
+    return true
+  } catch {
+    // @id doesn't exist yet — POST a new route
+    try {
+      execSync(
+        `curl -sf -X POST '${CADDY_ADMIN}/config/apps/http/servers/srv0/routes' -H 'Content-Type: application/json' -d '${payload.replace(/'/g, "'\\''")}'`,
+        { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] },
+      )
+      if (host) cleanupDuplicateRoutes(id, host)
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
 export function startCaddy(caddyfilePath) {
   try {
     execSync(`sudo caddy start --config "${caddyfilePath}" >/dev/null 2>&1`, { stdio: ['inherit', 'pipe', 'pipe'] })
@@ -119,11 +237,14 @@ if (isDirectRun) {
 
   const s = spinner()
   if (isCaddyRunning()) {
-    s.start('Reloading proxy...')
-    if (reloadCaddy(caddyfilePath)) {
-      s.stop('Proxy reloaded')
+    s.start('Updating proxy routes...')
+    const routeConfig = generateRouteConfig()
+    if (upsertCaddyRoute(routeConfig)) {
+      s.stop('Proxy routes updated (admin API)')
+    } else if (reloadCaddy(caddyfilePath)) {
+      s.stop('Proxy reloaded (Caddyfile fallback)')
     } else {
-      s.stop('Failed to reload')
+      s.stop('Failed to update proxy')
       process.exit(1)
     }
   } else {

package/src/cli/proxy.test.js

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import { findStaleRouteIndices } from './proxy.js'
+
+describe('findStaleRouteIndices', () => {
+  it('identifies stale non-@id routes matching the same host', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }], terminal: true }, // index 0: stale
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 1: ours
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([0])
+  })
+
+  it('preserves routes with a different @id for the same host', () => {
+    const routes = [
+      { '@id': 'other-app', match: [{ host: ['storyboard.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns multiple stale indices in descending order', () => {
+    const routes = [
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 0: stale
+      { '@id': 'storyboard-core', match: [{ host: ['storyboard-core.localhost'] }] }, // index 1: different host
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] }, // index 2: ours
+      { match: [{ host: ['storyboard.localhost'] }] }, // index 3: stale
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([3, 0]) // descending for safe deletion
+  })
+
+  it('ignores routes for a different host', () => {
+    const routes = [
+      { match: [{ host: ['other.localhost'] }] },
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles routes with no match field', () => {
+    const routes = [
+      { handle: [{ handler: 'reverse_proxy' }] }, // no match
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('returns empty array when no stale routes exist', () => {
+    const routes = [
+      { '@id': 'storyboard', match: [{ host: ['storyboard.localhost'] }] },
+    ]
+    const indices = findStaleRouteIndices(routes, 'storyboard', 'storyboard.localhost')
+    expect(indices).toEqual([])
+  })
+
+  it('handles empty routes array', () => {
+    expect(findStaleRouteIndices([], 'storyboard', 'storyboard.localhost')).toEqual([])
+  })
+})

package/src/cli/schemas.js

@@ -0,0 +1,200 @@
+/**
+ * Creation schemas — define flags for each `storyboard create` subcommand.
+ *
+ * Each schema is a plain object mapping flag names to definitions.
+ * Schemas serve as validation, documentation, and help-text source.
+ *
+ * @typedef {import('./flags.js').FlagSchema} FlagSchema
+ */
+
+/** @type {FlagSchema} */
+export const prototypeSchema = {
+  name: {
+    type: 'string',
+    required: true,
+    description: 'Prototype name (kebab-case)',
+    aliases: ['n'],
+  },
+  title: {
+    type: 'string',
+    description: 'Display title',
+    aliases: ['t'],
+  },
+  folder: {
+    type: 'string',
+    description: 'Parent .folder directory',
+    aliases: ['f'],
+  },
+  partial: {
+    type: 'string',
+    description: 'Template/recipe name',
+    aliases: ['p'],
+  },
+  author: {
+    type: 'string',
+    description: 'Author name(s)',
+    aliases: ['a'],
+  },
+  description: {
+    type: 'string',
+    description: 'Prototype description',
+    aliases: ['d'],
+  },
+  url: {
+    type: 'string',
+    description: 'External URL (makes it an external prototype)',
+  },
+  flow: {
+    type: 'boolean',
+    default: false,
+    description: 'Create a default flow file',
+  },
+}
+
+/** @type {FlagSchema} */
+export const canvasSchema = {
+  name: {
+    type: 'string',
+    required: true,
+    description: 'Canvas name (kebab-case)',
+    aliases: ['n'],
+  },
+  title: {
+    type: 'string',
+    description: 'Display title',
+    aliases: ['t'],
+  },
+  folder: {
+    type: 'string',
+    description: 'Parent .folder directory',
+    aliases: ['f'],
+  },
+  grid: {
+    type: 'boolean',
+    default: true,
+    description: 'Show dot grid',
+  },
+  jsx: {
+    type: 'boolean',
+    default: false,
+    description: 'Include JSX companion file',
+  },
+  description: {
+    type: 'string',
+    description: 'Optional description',
+    aliases: ['d'],
+  },
+}
+
+/** @type {FlagSchema} */
+export const flowSchema = {
+  name: {
+    type: 'string',
+    required: true,
+    description: 'Flow name (kebab-case)',
+    aliases: ['n'],
+  },
+  prototype: {
+    type: 'string',
+    required: true,
+    description: 'Target prototype name',
+    aliases: ['p'],
+  },
+  title: {
+    type: 'string',
+    description: 'Display title',
+    aliases: ['t'],
+  },
+  folder: {
+    type: 'string',
+    description: 'Parent .folder directory',
+    aliases: ['f'],
+  },
+  globals: {
+    type: 'array',
+    description: '$global object names',
+    aliases: ['g'],
+  },
+  'copy-from': {
+    type: 'string',
+    description: 'Existing flow to copy from',
+  },
+  author: {
+    type: 'string',
+    description: 'Author name(s)',
+    aliases: ['a'],
+  },
+  description: {
+    type: 'string',
+    description: 'Flow description',
+    aliases: ['d'],
+  },
+  'starting-page': {
+    type: 'string',
+    description: 'Starting page path',
+  },
+}
+
+/** @type {FlagSchema} */
+export const pageSchema = {
+  prototype: {
+    type: 'string',
+    required: true,
+    description: 'Target prototype name',
+    aliases: ['p'],
+  },
+  path: {
+    type: 'string',
+    required: true,
+    description: 'Page path (e.g. settings/general)',
+  },
+  folder: {
+    type: 'string',
+    description: 'Parent .folder directory',
+    aliases: ['f'],
+  },
+  template: {
+    type: 'string',
+    description: 'Page template name',
+    aliases: ['t'],
+  },
+}
+
+/** @type {FlagSchema} */
+export const widgetSchema = {
+  canvas: {
+    type: 'string',
+    required: true,
+    description: 'Target canvas name',
+    aliases: ['c'],
+  },
+  x: {
+    type: 'number',
+    default: 0,
+    description: 'X position',
+  },
+  y: {
+    type: 'number',
+    default: 0,
+    description: 'Y position',
+  },
+  props: {
+    type: 'string',
+    description: 'Widget props as JSON string',
+  },
+}
+
+/** @type {FlagSchema} */
+export const componentSchema = {
+  name: {
+    type: 'string',
+    required: true,
+    description: 'Component name (kebab-case)',
+    aliases: ['n'],
+  },
+  directory: {
+    type: 'string',
+    description: 'Subdirectory inside src/components/',
+    aliases: ['d'],
+  },
+}

package/src/cli/serverUrl.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve the dev server URL for the current worktree.
+ *
+ * Checks the Caddy admin API first to find the actual port mapped to
+ * this branch's route, since ports.json can drift from the running
+ * dev server. Falls back to ports.json if Caddy isn't reachable.
+ */
+
+import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { readDevDomain } from './proxy.js'
+import { execSync } from 'child_process'
+
+export function getServerUrl() {
+  const name = detectWorktreeName()
+
+  // Try Caddy admin API for the real port
+  try {
+    const raw = execSync(
+      'curl -sf http://localhost:2019/config/apps/http/servers/srv0/routes',
+      { encoding: 'utf8', timeout: 2000, stdio: ['pipe', 'pipe', 'pipe'] }
+    )
+    const routes = JSON.parse(raw)
+    const domain = readDevDomain()
+
+    for (const route of routes) {
+      const hosts = route.match?.[0]?.host || []
+      if (!hosts.includes(domain)) continue
+      const subroutes = route.handle?.[0]?.routes || []
+
+      if (name === 'main') {
+        // Main is the fallback route (no match path)
+        const fallback = subroutes.find(r => !r.match)
+        if (fallback) {
+          const dial = fallback.handle?.[0]?.upstreams?.[0]?.dial
+          if (dial) return `http://${dial}`
+        }
+      } else {
+        // Branch route matches /branch--<name>/*
+        const branchRoute = subroutes.find(r => {
+          const paths = r.match?.[0]?.path || []
+          return paths.some(p => p === `/branch--${name}/*`)
+        })
+        if (branchRoute) {
+          const dial = branchRoute.handle?.[0]?.upstreams?.[0]?.dial
+          if (dial) return `http://${dial}`
+        }
+      }
+    }
+  } catch {
+    // Caddy not running or not reachable — fall through
+  }
+
+  // Fallback to ports.json
+  const port = getPort(name)
+  return `http://localhost:${port}`
+}