@dfosco/storyboard 0.5.0-alpha.0

package/src/core/cli/proxy.js

@@ -0,0 +1,319 @@
+/**
+ * storyboard proxy — Manage the Caddy reverse proxy.
+ *
+ * Usage:
+ *   storyboard proxy start       Start or reload Caddy proxy
+ *   storyboard proxy close       Stop Caddy proxy
+ *
+ * Caddy listens on port 80 for storyboard.localhost, routing:
+ *   /storyboard/*              → main (port 1234)
+ *   /<branchname>/storyboard/* → worktree (assigned port)
+ *
+ * Requires Caddy to be installed (brew install caddy).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs'
+import { execSync } from 'child_process'
+import { dirname, resolve } from 'path'
+import { portsFilePath } from '../worktree/port.js'
+import { list as listRunningServers } from '../worktree/serverRegistry.js'
+
+export function readDevDomain(cwd) {
+  try {
+    const configPath = resolve(cwd || process.cwd(), 'storyboard.config.json')
+    const config = JSON.parse(readFileSync(configPath, 'utf8'))
+    return `${config.devDomain || 'storyboard'}.localhost`
+  } catch {
+    return 'storyboard.localhost'
+  }
+}
+
+const DOMAIN = readDevDomain()
+
+/**
+ * Build branch→port map from running servers (servers.json) + explicit overrides.
+ * Only includes branches with live processes — prevents stale routes from
+ * creating redirect loops when ports get reused by different Vite instances.
+ * When multiple servers run for the same worktree, latest startedAt wins.
+ */
+function livePortMap(portOverrides = {}) {
+  const map = {}
+  try {
+    for (const srv of listRunningServers()) {
+      if (srv.worktree === 'main') continue
+      const existing = map[srv.worktree]
+      if (!existing || srv.startedAt > existing.startedAt) {
+        map[srv.worktree] = { port: srv.port, startedAt: srv.startedAt }
+      }
+    }
+  } catch { /* registry unavailable — rely on overrides only */ }
+
+  // Build final branch→port, overrides always win
+  const result = {}
+  for (const [name, info] of Object.entries(map)) result[name] = info.port
+  Object.assign(result, portOverrides)
+  // Remove 'main' if accidentally passed — handled separately
+  delete result.main
+  return result
+}
+
+export function generateCaddyfile(portOverrides = {}) {
+  const portsFile = portsFilePath()
+  const dir = dirname(portsFile)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  // Main port from ports.json (always 1234 unless overridden)
+  let mainPort = 1234
+  if (existsSync(portsFile)) {
+    try {
+      const ports = JSON.parse(readFileSync(portsFile, 'utf8'))
+      mainPort = ports.main || 1234
+    } catch { /* use default */ }
+  }
+
+  const branches = Object.entries(livePortMap(portOverrides))
+
+  // Build Caddy route blocks — branches first (more specific), main last (fallback)
+  const branchBlocks = branches
+    .map(([name, port]) => `\t# Worktree: ${name}\n\thandle /branch--${name}/* {\n\t\treverse_proxy localhost:${port}\n\t}`)
+    .join('\n\n')
+
+  const caddyfile = `# Auto-generated by storyboard CLI — do not edit manually.
+# Regenerated on every \`storyboard dev\` or \`storyboard proxy\`.
+
+http://${DOMAIN} {
+${branchBlocks ? branchBlocks + '\n\n' : ''}\t# Main
+\thandle {
+\t\treverse_proxy localhost:${mainPort}
+\t}
+}
+`
+
+  const caddyfilePath = portsFile.replace('ports.json', 'Caddyfile')
+  writeFileSync(caddyfilePath, caddyfile)
+  return caddyfilePath
+}
+
+export function isCaddyInstalled() {
+  try {
+    execSync('caddy version', { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function isCaddyRunning() {
+  try {
+    // Caddy admin API on localhost:2019
+    execSync('curl -sf http://localhost:2019/config/ >/dev/null 2>&1', { timeout: 2000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function reloadCaddy(caddyfilePath) {
+  try {
+    execSync(`caddy reload --config "${caddyfilePath}" 2>/dev/null`, { stdio: 'ignore', timeout: 5000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ── 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 = {}) {
+  // Main port from ports.json
+  const portsFile = portsFilePath()
+  let mainPort = 1234
+  if (existsSync(portsFile)) {
+    try {
+      const ports = JSON.parse(readFileSync(portsFile, 'utf8'))
+      mainPort = ports.main || 1234
+    } catch { /* use default */ }
+  }
+
+  const branches = Object.entries(livePortMap(portOverrides))
+
+  // 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(`caddy start --config "${caddyfilePath}" >/dev/null 2>&1`, { stdio: ['inherit', 'pipe', 'pipe'] })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function stopCaddy() {
+  try {
+    execSync('curl -sf -X POST http://localhost:2019/stop', { timeout: 5000, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+// When run directly as `storyboard proxy` (not imported by setup.js)
+const isDirectRun = process.argv[2] === 'proxy'
+if (isDirectRun) {
+  const { intro, outro, log, spinner } = await import('@clack/prompts')
+  const subcommand = process.argv[3]
+
+  if (!isCaddyInstalled()) {
+    intro('storyboard proxy')
+    log.error('Caddy is not installed. Run: brew install caddy')
+    process.exit(1)
+  }
+
+  if (subcommand === 'close' || subcommand === 'stop') {
+    intro('storyboard proxy close')
+    if (!isCaddyRunning()) {
+      log.info('Proxy is not running.')
+      outro('')
+    } else if (stopCaddy()) {
+      log.success('Proxy stopped.')
+      outro('')
+    } else {
+      log.error('Failed to stop proxy.')
+      process.exit(1)
+    }
+  } else if (subcommand === 'start' || !subcommand) {
+    intro('storyboard proxy start')
+    const caddyfilePath = generateCaddyfile()
+
+    const s = spinner()
+    if (isCaddyRunning()) {
+      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 update proxy')
+        process.exit(1)
+      }
+    } else {
+      s.start('Starting proxy...')
+      if (startCaddy(caddyfilePath)) {
+        s.stop('Proxy started')
+      } else {
+        s.stop('Failed to start proxy')
+        process.exit(1)
+      }
+    }
+    outro(`Proxy ready at http://${DOMAIN}/`)
+  } else {
+    intro('storyboard proxy')
+    log.error(`Unknown subcommand: "${subcommand}"`)
+    log.info('Available: start, close')
+    process.exit(1)
+  }
+}

package/src/core/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/core/cli/schemas.js

@@ -0,0 +1,223 @@
+/**
+ * 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',
+    description: 'X position (omit for auto-positioning)',
+  },
+  y: {
+    type: 'number',
+    description: 'Y position (omit for auto-positioning)',
+  },
+  near: {
+    type: 'string',
+    description: 'Place near this widget ID (default: auto-selects last widget). Use --near false to disable',
+  },
+  direction: {
+    type: 'string',
+    default: 'right',
+    description: 'Direction from reference widget: right, left, above, below',
+    aliases: ['dir'],
+  },
+  resolve: {
+    type: 'boolean',
+    default: false,
+    description: 'Run server-side collision detection on the target position',
+  },
+  props: {
+    type: 'string',
+    description: 'Widget props as JSON string',
+  },
+  'props-file': {
+    type: 'string',
+    description: 'Path to a JSON file containing widget props (avoids shell escaping)',
+    aliases: ['pf'],
+  },
+  json: {
+    type: 'boolean',
+    default: false,
+    description: 'Output result as JSON (includes widget id)',
+  },
+}
+
+/** @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'],
+  },
+}