@dfosco/storyboard 0.5.0-alpha.0

package/src/core/cli/canvasRead.js

@@ -0,0 +1,236 @@
+/**
+ * storyboard canvas read — Read canvas state and list widgets with their IDs, URLs, and content.
+ *
+ * Usage:
+ *   storyboard canvas read my-canvas             List all widgets
+ *   storyboard canvas read my-canvas --json      Output as JSON
+ *   storyboard canvas read my-canvas --id abc    Get a specific widget by ID
+ *
+ * Output includes:
+ *   - Widget ID
+ *   - Widget type
+ *   - Position (x, y)
+ *   - Content (text, url, src depending on type)
+ *   - File path (for images)
+ */
+
+import * as p from '@clack/prompts'
+import { getServerUrl } from './serverUrl.js'
+import { getWidgetBounds } from '../canvas/collision.js'
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`
+
+async function checkServer() {
+  try {
+    await fetch(`${getServerUrl()}/_storyboard/canvas/list`, { signal: AbortSignal.timeout(2000) })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Compute positional bounds for a widget.
+ */
+function computeBounds(widget) {
+  const { x, y, width, height } = getWidgetBounds(widget)
+  return {
+    width,
+    height,
+    startX: x,
+    startY: y,
+    endX: x + width,
+    endY: y + height,
+  }
+}
+
+/**
+ * Get bounds for a widget — uses persisted bounds if available, computes otherwise.
+ */
+function getBounds(widget) {
+  if (widget.bounds && typeof widget.bounds.startX === 'number') {
+    return widget.bounds
+  }
+  return computeBounds(widget)
+}
+
+/**
+ * Extract the primary content from a widget based on its type.
+ */
+function getWidgetContent(widget) {
+  const { type, props = {} } = widget
+  switch (type) {
+    case 'sticky-note':
+      return { content: props.text || '', contentType: 'text' }
+    case 'markdown':
+      return { content: props.content || '', contentType: 'markdown' }
+    case 'prototype':
+      return { content: props.src || '', contentType: 'url', url: props.src }
+    case 'figma-embed':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'link-preview':
+      return { content: props.url || '', contentType: 'url', url: props.url }
+    case 'image':
+      return {
+        content: props.src || '',
+        contentType: 'image',
+        url: props.src ? `/_storyboard/canvas/images/${props.src}` : '',
+        filePath: props.src ? `assets/canvas/images/${props.src}` : '',
+      }
+    default:
+      return { content: JSON.stringify(props), contentType: 'props' }
+  }
+}
+
+/**
+ * Format a widget for human-readable output.
+ */
+function formatWidget(widget) {
+  const { id, type, position = {} } = widget
+  const { content, contentType, url, filePath } = getWidgetContent(widget)
+  const bounds = getBounds(widget)
+
+  const lines = []
+  lines.push(`${bold(id)} ${dim(`(${type})`)}`)
+  lines.push(`  Position: ${position.x ?? 0}, ${position.y ?? 0}`)
+  lines.push(`  Bounds: ${bounds.startX},${bounds.startY} → ${bounds.endX},${bounds.endY} ${dim(`(${bounds.width}×${bounds.height})`)}`)
+
+  if (contentType === 'image') {
+    lines.push(`  File: ${cyan(filePath)}`)
+    if (content) lines.push(`  Filename: ${content}`)
+  } else if (contentType === 'url') {
+    lines.push(`  URL: ${cyan(url || content)}`)
+  } else if (content) {
+    const preview = content.length > 80 ? content.slice(0, 77) + '...' : content
+    lines.push(`  Content: ${preview}`)
+  }
+
+  return lines.join('\n')
+}
+
+async function canvasRead() {
+  const args = process.argv.slice(4)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  canvas read — Read canvas state and list widgets
+
+  Usage:
+    storyboard canvas read <canvas-name>          List all widgets
+    storyboard canvas read <canvas-name> --json   Output as JSON
+    storyboard canvas read <canvas-name> --id <widget-id>  Get specific widget
+
+  Output includes widget ID, type, position, content, URLs, and file paths.
+`)
+    process.exit(0)
+  }
+
+  // Parse args
+  let canvasName = ''
+  let outputJson = false
+  let widgetId = ''
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--json') {
+      outputJson = true
+    } else if (arg === '--id' && args[i + 1]) {
+      widgetId = args[++i]
+    } else if (!arg.startsWith('-') && !canvasName) {
+      canvasName = arg
+    }
+  }
+
+  // Check server
+  const serverUp = await checkServer()
+  if (!serverUp) {
+    p.log.error('Dev server is not running. Start it with: storyboard dev')
+    process.exit(1)
+  }
+
+  const base = getServerUrl()
+
+  // If no canvas name, list available canvases
+  if (!canvasName) {
+    try {
+      const res = await fetch(`${base}/_storyboard/canvas/list`)
+      if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
+      const data = await res.json()
+      const canvases = data.canvases || []
+
+      if (outputJson) {
+        console.log(JSON.stringify(canvases, null, 2))
+      } else {
+        if (canvases.length === 0) {
+          p.log.info('No canvases found')
+        } else {
+          console.log('\nAvailable canvases:\n')
+          for (const c of canvases) {
+            console.log(`  ${bold(c.name)} ${dim(`(${c.widgetCount} widgets)`)}`)
+          }
+          console.log('')
+        }
+      }
+    } catch (err) {
+      p.log.error(`Failed to list canvases: ${err.message}`)
+      process.exit(1)
+    }
+    return
+  }
+
+  // Read canvas state
+  try {
+    let url = `${base}/_storyboard/canvas/read?name=${encodeURIComponent(canvasName)}`
+    if (widgetId) url += `&widget=${encodeURIComponent(widgetId)}`
+    const res = await fetch(url)
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`${res.status} ${res.statusText}${text ? ': ' + text : ''}`)
+    }
+    const data = await res.json()
+    const widgets = data.widgets || []
+
+    // If filtering by widget ID
+    if (widgetId) {
+      const widget = widgets[0]
+      if (!widget) {
+        p.log.error(`Widget "${widgetId}" not found in canvas "${canvasName}"`)
+        process.exit(1)
+      }
+
+      if (outputJson) {
+        const enriched = { ...widget, ...getWidgetContent(widget), bounds: getBounds(widget) }
+        console.log(JSON.stringify(enriched, null, 2))
+      } else {
+        console.log('')
+        console.log(formatWidget(widget))
+        console.log('')
+      }
+      return
+    }
+
+    // List all widgets
+    if (outputJson) {
+      const enriched = widgets.map((w) => ({ ...w, ...getWidgetContent(w), bounds: getBounds(w) }))
+      console.log(JSON.stringify({ ...data, widgets: enriched }, null, 2))
+    } else {
+      console.log(`\n${bold(data.title || canvasName)} ${dim(`(${widgets.length} widgets)`)}\n`)
+
+      if (widgets.length === 0) {
+        console.log('  No widgets on this canvas.\n')
+      } else {
+        for (const widget of widgets) {
+          console.log(formatWidget(widget))
+          console.log('')
+        }
+      }
+    }
+  } catch (err) {
+    p.log.error(`Failed to read canvas: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+canvasRead()

package/src/core/cli/canvasUpdate.js

@@ -0,0 +1,179 @@
+/**
+ * storyboard canvas update <widget-id> — Update a widget's props or position.
+ *
+ * Usage:
+ *   storyboard canvas update <widget-id> --canvas my-canvas --text "New text"
+ *   storyboard canvas update <widget-id> --canvas my-canvas --content "# Markdown"
+ *   storyboard canvas update <widget-id> --canvas my-canvas --props '{"key":"value"}'
+ *   storyboard canvas update <widget-id> --canvas my-canvas --x 100 --y 200
+ *
+ * Shorthand flags (merged into props):
+ *   --text <string>       Set props.text (sticky notes)
+ *   --content <string>    Set props.content (markdown blocks)
+ *   --src <string>        Set props.src (images, prototypes)
+ *   --url <string>        Set props.url (link previews, embeds)
+ *   --color <string>      Set props.color (sticky notes)
+ *
+ * Position flags:
+ *   --x <number>          Move widget to x position
+ *   --y <number>          Move widget to y position
+ */
+
+import * as p from '@clack/prompts'
+import { getServerUrl } from './serverUrl.js'
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+
+async function checkServer() {
+  try {
+    await fetch(`${getServerUrl()}/_storyboard/canvas/list`, { signal: AbortSignal.timeout(2000) })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function serverPatch(path, body) {
+  const base = getServerUrl()
+  const res = await fetch(`${base}${path}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    throw new Error(`${res.status} ${res.statusText}${text ? ': ' + text : ''}`)
+  }
+  return res.json()
+}
+
+async function canvasUpdate() {
+  const args = process.argv.slice(4)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  canvas update — Update a widget's props or position
+
+  Usage:
+    storyboard canvas update <widget-id> --canvas <name> [flags]
+
+  Shorthand flags (merged into props):
+    --text <string>       Set props.text (sticky notes)
+    --content <string>    Set props.content (markdown blocks)
+    --src <string>        Set props.src (images, prototypes)
+    --url <string>        Set props.url (link previews, embeds)
+    --color <string>      Set props.color (sticky notes)
+    --props <json>        Set arbitrary props as JSON
+
+  Position flags:
+    --x <number>          Move widget to x position
+    --y <number>          Move widget to y position
+
+  Options:
+    --canvas <name>       Canvas name ${dim('(required)')}
+    --json                Output result as JSON
+`)
+    process.exit(0)
+  }
+
+  // Parse args
+  let widgetId = ''
+  let canvasName = ''
+  let outputJson = false
+  let rawProps = ''
+  const shorthandProps = {}
+  let posX = undefined
+  let posY = undefined
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--canvas' && args[i + 1]) {
+      canvasName = args[++i]
+    } else if (arg === '--json') {
+      outputJson = true
+    } else if (arg === '--props' && args[i + 1]) {
+      rawProps = args[++i]
+    } else if (arg === '--text' && args[i + 1]) {
+      shorthandProps.text = args[++i]
+    } else if (arg === '--content' && args[i + 1]) {
+      shorthandProps.content = args[++i]
+    } else if (arg === '--src' && args[i + 1]) {
+      shorthandProps.src = args[++i]
+    } else if (arg === '--url' && args[i + 1]) {
+      shorthandProps.url = args[++i]
+    } else if (arg === '--color' && args[i + 1]) {
+      shorthandProps.color = args[++i]
+    } else if (arg === '--x' && args[i + 1]) {
+      posX = Number(args[++i])
+    } else if (arg === '--y' && args[i + 1]) {
+      posY = Number(args[++i])
+    } else if (!arg.startsWith('-') && !widgetId) {
+      widgetId = arg
+    }
+  }
+
+  if (!widgetId) {
+    p.log.error('Widget ID is required. Usage: storyboard canvas update <widget-id> --canvas <name>')
+    process.exit(1)
+  }
+
+  if (!canvasName) {
+    p.log.error('Canvas name is required. Use --canvas <name>')
+    process.exit(1)
+  }
+
+  // Build props
+  let props = {}
+  if (rawProps) {
+    try {
+      props = JSON.parse(rawProps)
+    } catch {
+      p.log.error('--props must be valid JSON')
+      process.exit(1)
+    }
+  }
+  Object.assign(props, shorthandProps)
+
+  // Build position
+  let position = undefined
+  if (posX !== undefined || posY !== undefined) {
+    position = {}
+    if (posX !== undefined) position.x = posX
+    if (posY !== undefined) position.y = posY
+  }
+
+  if (Object.keys(props).length === 0 && !position) {
+    p.log.error('Nothing to update. Provide --props, --text, --content, --x, --y, or other flags.')
+    process.exit(1)
+  }
+
+  // Check server
+  const serverUp = await checkServer()
+  if (!serverUp) {
+    p.log.error('Dev server is not running. Start it with: storyboard dev')
+    process.exit(1)
+  }
+
+  try {
+    const body = { name: canvasName, widgetId }
+    if (Object.keys(props).length > 0) body.props = props
+    if (position) body.position = position
+
+    const result = await serverPatch('/_storyboard/canvas/widget', body)
+
+    if (outputJson) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      const updates = []
+      if (Object.keys(props).length > 0) updates.push(`props: ${Object.keys(props).join(', ')}`)
+      if (position) updates.push(`position: ${posX ?? '·'}, ${posY ?? '·'}`)
+      p.log.success(`Updated ${bold(widgetId)} in ${bold(canvasName)} (${updates.join('; ')})`)
+    }
+  } catch (err) {
+    p.log.error(`Failed to update widget: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+canvasUpdate()

package/src/core/cli/code.js

@@ -0,0 +1,67 @@
+/**
+ * storyboard code [branch] — Open a worktree in VS Code.
+ *
+ * Usage:
+ *   storyboard code              # open current worktree or repo root
+ *   storyboard code main         # open repo root
+ *   storyboard code <branch>     # open worktrees/<branch>/
+ */
+
+import * as p from '@clack/prompts'
+import { execFileSync } from 'child_process'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+import { detectWorktreeName, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
+
+const branch = process.argv[3] || undefined
+
+p.intro('storyboard code')
+
+function openInCode(dir) {
+  try {
+    execFileSync('code', [dir], { stdio: 'inherit' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const root = repoRoot()
+
+if (!branch) {
+  // No argument — open current directory
+  const name = detectWorktreeName()
+  const dir = name === 'main' ? root : worktreeDir(name)
+  if (openInCode(dir)) {
+    p.outro(`Opened ${name === 'main' ? 'repo root' : `worktrees/${name}/`}`)
+  } else {
+    p.log.error('Could not open VS Code. Is the `code` CLI installed?')
+    p.log.info('Run `npx storyboard setup` to install it, or open VS Code and run:')
+    p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    process.exit(1)
+  }
+} else if (branch === 'main') {
+  if (openInCode(root)) {
+    p.outro('Opened repo root')
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+} else {
+  const dir = worktreeDir(branch)
+  if (!existsSync(resolve(dir, '.git'))) {
+    // List available worktrees as a hint
+    const available = listWorktrees()
+    p.log.error(`Worktree "${branch}" does not exist.`)
+    if (available.length > 0) {
+      p.log.info(`Available worktrees: ${available.join(', ')}`)
+    }
+    process.exit(1)
+  }
+  if (openInCode(dir)) {
+    p.outro(`Opened worktrees/${branch}/`)
+  } else {
+    p.log.error('Could not open VS Code.')
+    process.exit(1)
+  }
+}

package/src/core/cli/compact.js

@@ -0,0 +1,62 @@
+/**
+ * storyboard compact — Compact canvas JSONL files to reduce bloat.
+ *
+ * Usage:
+ *   storyboard compact                 Compact all canvases over 500KB
+ *   storyboard compact --all           Compact all canvases (force)
+ *   storyboard compact folder/page     Compact a specific canvas
+ */
+
+import * as p from '@clack/prompts'
+import { compactAll, compactCanvas, findCanvasFiles } from '../canvas/compact.js'
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const green = (s) => `\x1b[32m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+
+function formatKB(bytes) {
+  return `${(bytes / 1024).toFixed(0)}KB`
+}
+
+const root = process.cwd()
+const args = process.argv.slice(3)
+const forceAll = args.includes('--all')
+const target = args.find(a => !a.startsWith('--'))
+
+if (target) {
+  // Compact a specific canvas
+  const files = findCanvasFiles(root)
+  const match = files.find(f => f.name === target)
+  if (!match) {
+    p.log.error(`Canvas "${target}" not found.`)
+    const available = files.map(f => `  ${f.name}`).join('\n')
+    if (available) p.log.info(`Available canvases:\n${available}`)
+    process.exit(1)
+  }
+
+  const result = compactCanvas(match.filePath, { force: true })
+  if (result.compacted) {
+    p.log.success(`${bold(target)}: ${formatKB(result.before)} → ${formatKB(result.after)} ${dim(`(${((1 - result.after / result.before) * 100).toFixed(0)}% reduced)`)}`)
+  } else {
+    p.log.info(`${target}: already compact (${formatKB(result.before)})`)
+  }
+} else {
+  // Compact all
+  const files = findCanvasFiles(root)
+  if (files.length === 0) {
+    p.log.info('No canvas files found.')
+    process.exit(0)
+  }
+
+  const results = compactAll(root, { force: forceAll })
+  if (results.length === 0) {
+    const total = files.length
+    const sizes = files.map(f => formatKB(f.size)).join(', ')
+    p.log.info(`All ${total} canvases are under threshold. ${dim(`(${sizes})`)}`)
+  } else {
+    for (const r of results) {
+      p.log.success(`${bold(r.name)}: ${formatKB(r.before)} → ${formatKB(r.after)} ${dim(`(${((1 - r.after / r.before) * 100).toFixed(0)}% reduced)`)}`)
+    }
+    p.log.info(green(`Compacted ${results.length} canvas${results.length === 1 ? '' : 'es'}.`))
+  }
+}