@dfosco/storyboard 0.5.0-alpha.0

package/src/core/cli/canvasAdd.js

@@ -0,0 +1,241 @@
+/**
+ * storyboard canvas add <widget-type> — Add a widget to an existing canvas.
+ *
+ * Widgets are auto-positioned by default near (in priority order):
+ * 1. The active agent/terminal running the command ($STORYBOARD_WIDGET_ID)
+ * 2. The user's currently selected widget
+ * 3. The center of the user's viewport
+ * 4. The last widget on the canvas
+ *
+ * Use --x/--y for explicit coordinates, or --near <widget-id> to place
+ * relative to a specific widget. Use --near false to opt out entirely.
+ *
+ * Usage:
+ *   storyboard canvas add sticky-note --canvas my-canvas
+ *   storyboard canvas add markdown --canvas my-canvas --near widget-abc
+ *   storyboard canvas add prototype --canvas my-canvas --x 100 --y 200
+ *   storyboard canvas add sticky-note --canvas my-canvas --near false --x 0 --y 0
+ *
+ * Known widget types: sticky-note, markdown, prototype
+ * The server accepts any type string — new widget types work automatically.
+ */
+
+import fs from 'node:fs'
+import * as p from '@clack/prompts'
+import { parseFlags, hasFlags, formatFlagHelp } from './flags.js'
+import { widgetSchema } from './schemas.js'
+import { ensureDevServer, serverPost, getServerUrl } from './create.js'
+
+const KNOWN_TYPES = ['sticky-note', 'markdown', 'prototype', 'story']
+
+async function canvasAdd() {
+  // argv: storyboard canvas add [type] [--flags]
+  // process.argv: [node, script, 'canvas', 'add', ...rest]
+  const rest = process.argv.slice(4)
+
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(`\n  canvas add flags:\n`)
+    console.log(`  Positional: <widget-type>  Widget type (${KNOWN_TYPES.join(', ')})\n`)
+    console.log(formatFlagHelp(widgetSchema))
+    console.log('')
+    process.exit(0)
+  }
+
+  // Extract positional widget type (first non-flag arg)
+  let widgetType = ''
+  const flagTokens = []
+  for (const token of rest) {
+    if (!widgetType && !token.startsWith('-')) {
+      widgetType = token
+    } else {
+      flagTokens.push(token)
+    }
+  }
+
+  const flagMode = hasFlags(rest) || Boolean(widgetType)
+  const { flags, errors } = flagMode ? parseFlags(flagTokens, widgetSchema) : { flags: {}, errors: [] }
+  const jsonOutput = flags.json || false
+
+  if (errors.length) {
+    for (const e of errors) p.log.error(e)
+    process.exit(1)
+  }
+
+  if (!jsonOutput) p.intro('storyboard canvas add')
+  await ensureDevServer({ quiet: jsonOutput })
+
+  // Widget type
+  if (!widgetType) {
+    widgetType = await p.select({
+      message: 'Widget type',
+      options: KNOWN_TYPES.map((t) => ({ value: t, label: t })),
+    })
+    if (p.isCancel(widgetType)) return process.exit(0)
+  }
+
+  // Canvas name
+  const canvasName = flags.canvas || await (async () => {
+    // Try to fetch available canvases
+    let canvases = []
+    try {
+      const base = getServerUrl()
+      const res = await fetch(`${base}/_storyboard/canvas/list`)
+      if (res.ok) {
+        const data = await res.json()
+        canvases = data.canvases || data || []
+      }
+    } catch { /* empty */ }
+
+    if (canvases.length > 0) {
+      const choice = await p.select({
+        message: 'Canvas',
+        options: canvases.map((c) => ({ value: c.name || c, label: c.name || c })),
+      })
+      if (p.isCancel(choice)) process.exit(0)
+      return choice
+    }
+
+    const v = await p.text({
+      message: 'Canvas name',
+      placeholder: 'my-canvas',
+      validate: (v) => { if (!v) return 'Canvas name is required' },
+    })
+    if (p.isCancel(v)) process.exit(0)
+    return v
+  })()
+
+  // Position flags: only send explicit position if user provided --x/--y.
+  // --near=false explicitly opts out of auto-positioning.
+  const hasExplicitX = flags.x !== undefined && flags.x !== null
+  const hasExplicitY = flags.y !== undefined && flags.y !== null
+  const hasExplicitPosition = hasExplicitX || hasExplicitY
+  const x = flags.x ?? 0
+  const y = flags.y ?? 0
+
+  // --near: string widget ID, or literal "false" to opt out
+  const nearRaw = flags.near
+  const nearOptOut = nearRaw === 'false' || nearRaw === false
+  const near = (nearRaw && !nearOptOut) ? nearRaw : null
+  const direction = flags.direction || 'right'
+  const resolve = flags.resolve || !!near
+
+  // Pass the calling agent/terminal's widget ID so the server can auto-position near it
+  const source = process.env.STORYBOARD_WIDGET_ID || null
+
+  let props = {}
+  if (flags['props-file']) {
+    try {
+      const raw = fs.readFileSync(flags['props-file'], 'utf8')
+      props = JSON.parse(raw)
+    } catch (err) {
+      p.log.error(`--props-file: ${err.message}`)
+      process.exit(1)
+    }
+  } else if (flags.props) {
+    try {
+      props = JSON.parse(flags.props)
+    } catch {
+      p.log.error('--props must be valid JSON')
+      process.exit(1)
+    }
+  }
+
+  // Story-specific: prompt for storyId and exportName if not in --props
+  if (widgetType === 'story' && !props.storyId) {
+    // Try to fetch available stories from the dev server
+    let stories = []
+    try {
+      const base = getServerUrl()
+      const res = await fetch(`${base}/_storyboard/stories/list`)
+      if (res.ok) {
+        const data = await res.json()
+        stories = data.stories || []
+      }
+    } catch { /* empty */ }
+
+    if (stories.length > 0) {
+      const storyId = await (async () => {
+        const choice = await p.select({
+          message: 'Story',
+          options: stories.map((s) => ({ value: s.name, label: s.name, hint: s.route || '' })),
+        })
+        if (p.isCancel(choice)) process.exit(0)
+        return choice
+      })()
+      props.storyId = storyId
+    } else {
+      const storyId = await (async () => {
+        const v = await p.text({
+          message: 'Story ID',
+          placeholder: 'button-patterns',
+          validate: (v) => { if (!v) return 'Story ID is required' },
+        })
+        if (p.isCancel(v)) process.exit(0)
+        return v
+      })()
+      props.storyId = storyId
+    }
+
+    if (!props.exportName) {
+      const exportName = await (async () => {
+        const v = await p.text({
+          message: 'Export name (leave empty for all)',
+          placeholder: 'Default',
+        })
+        if (p.isCancel(v)) process.exit(0)
+        return v
+      })()
+      if (exportName) props.exportName = exportName
+    }
+
+    if (!props.width) props.width = 600
+    if (!props.height) props.height = 400
+  }
+
+  // Submit
+  if (jsonOutput) {
+    // JSON mode: no spinners/clack UI, just raw JSON output for scripting
+    try {
+      const body = { name: canvasName, type: widgetType, props }
+      if (hasExplicitPosition) body.position = { x, y }
+      if (nearOptOut) body.near = false
+      if (near) { body.near = near; body.direction = direction }
+      if (resolve) body.resolve = true
+      if (source) body.source = source
+      const result = await serverPost('/_storyboard/canvas/widget', body)
+      const widget = result.widget || result
+      console.log(JSON.stringify(widget))
+    } catch (err) {
+      console.error(JSON.stringify({ error: err.message }))
+      process.exit(1)
+    }
+    return
+  }
+
+  const s = p.spinner()
+  s.start(`Adding ${widgetType} widget...`)
+
+  try {
+    const body = { name: canvasName, type: widgetType, props }
+    if (hasExplicitPosition) body.position = { x, y }
+    if (nearOptOut) body.near = false
+    if (near) { body.near = near; body.direction = direction }
+    if (resolve) body.resolve = true
+    if (source) body.source = source
+    const result = await serverPost('/_storyboard/canvas/widget', body)
+    s.stop(`Widget added!`)
+    const widgetId = result.widget?.id || result.id
+    if (widgetId) {
+      p.log.success(`  ${widgetType} → ${canvasName} (id: ${widgetId})`)
+    } else {
+      p.log.success(`  ${widgetType} → ${canvasName}`)
+    }
+    p.outro('')
+  } catch (err) {
+    s.stop('Failed to add widget')
+    p.log.error(err.message)
+    p.outro('')
+  }
+}
+
+canvasAdd()

package/src/core/cli/canvasBatch.js

@@ -0,0 +1,98 @@
+/**
+ * storyboard canvas batch — Execute multiple canvas operations in one call.
+ *
+ * Usage:
+ *   storyboard canvas batch --canvas my-canvas --ops '[{"op":"create-widget","type":"sticky-note","props":{"text":"Hi"}}]'
+ *   storyboard canvas batch --canvas my-canvas --ops-file ops.json
+ *   cat ops.json | storyboard canvas batch --canvas my-canvas --ops-file -
+ *
+ * Always outputs JSON. Designed for scripting and agent use.
+ */
+
+import fs from 'node:fs'
+import { parseFlags, formatFlagHelp } from './flags.js'
+import { ensureDevServer, serverPost } from './create.js'
+
+const batchSchema = {
+  canvas: {
+    type: 'string',
+    required: true,
+    description: 'Target canvas name',
+    aliases: ['c'],
+  },
+  ops: {
+    type: 'string',
+    description: 'Operations as a JSON string (array)',
+  },
+  'ops-file': {
+    type: 'string',
+    description: 'Path to JSON file with operations (use - for stdin)',
+    aliases: ['f'],
+  },
+}
+
+async function canvasBatch() {
+  const rest = process.argv.slice(4)
+
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(`\n  canvas batch flags:\n`)
+    console.log(formatFlagHelp(batchSchema))
+    console.log(`\n  Operations: create-widget, update-widget, move-widget, delete-widget, create-connector, delete-connector`)
+    console.log(`  Refs: use $0, $1 etc. to reference IDs from earlier create ops. Named refs via "ref" field.\n`)
+    process.exit(0)
+  }
+
+  const { flags, errors } = parseFlags(rest, batchSchema)
+
+  if (errors.length) {
+    for (const e of errors) console.error(e)
+    process.exit(1)
+  }
+
+  if (!flags.ops && !flags['ops-file']) {
+    console.error(JSON.stringify({ error: 'Provide --ops (JSON string) or --ops-file (path or - for stdin)' }))
+    process.exit(1)
+  }
+
+  await ensureDevServer({ quiet: true })
+
+  let operations
+  try {
+    if (flags['ops-file']) {
+      let raw
+      if (flags['ops-file'] === '-') {
+        // Read from stdin
+        const chunks = []
+        for await (const chunk of process.stdin) chunks.push(chunk)
+        raw = Buffer.concat(chunks).toString('utf8')
+      } else {
+        raw = fs.readFileSync(flags['ops-file'], 'utf8')
+      }
+      operations = JSON.parse(raw)
+    } else {
+      operations = JSON.parse(flags.ops)
+    }
+  } catch (err) {
+    console.error(JSON.stringify({ error: `Failed to parse operations: ${err.message}` }))
+    process.exit(1)
+  }
+
+  if (!Array.isArray(operations)) {
+    console.error(JSON.stringify({ error: 'Operations must be a JSON array' }))
+    process.exit(1)
+  }
+
+  try {
+    const result = await serverPost('/_storyboard/canvas/batch', {
+      name: flags.canvas,
+      operations,
+    })
+    console.log(JSON.stringify(result))
+    if (!result.success) process.exit(1)
+  } catch (err) {
+    console.error(JSON.stringify({ error: err.message }))
+    process.exit(1)
+  }
+}
+
+canvasBatch()

package/src/core/cli/canvasBounds.js

@@ -0,0 +1,160 @@
+/**
+ * storyboard canvas bounds — Get size and positional bounds for a widget.
+ *
+ * Usage:
+ *   storyboard canvas bounds <canvas-name> --id <widget-id>   Get bounds for a specific widget
+ *   storyboard canvas bounds <canvas-name>                    Get bounds for all widgets
+ *   storyboard canvas bounds <canvas-name> --json             Output as JSON
+ *
+ * Output includes:
+ *   - Widget ID and type
+ *   - width, height
+ *   - startX, startY (top-left)
+ *   - endX, endY (bottom-right)
+ */
+
+import * as p from '@clack/prompts'
+import { getServerUrl } from './serverUrl.js'
+import { getWidgetBounds, getDefaultSize } from '../canvas/collision.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
+  }
+}
+
+/**
+ * Compute 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
+  }
+  const { x, y, width, height } = getWidgetBounds(widget)
+  return { width, height, startX: x, startY: y, endX: x + width, endY: y + height }
+}
+
+function formatBounds(widget) {
+  const { id, type } = widget
+  const b = getBounds(widget)
+  const lines = []
+  lines.push(`${bold(id)} ${dim(`(${type})`)}`)
+  lines.push(`  Size: ${b.width} × ${b.height}`)
+  lines.push(`  Start: ${b.startX}, ${b.startY}`)
+  lines.push(`  End:   ${b.endX}, ${b.endY}`)
+  return lines.join('\n')
+}
+
+async function canvasBounds() {
+  const args = process.argv.slice(4)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  canvas bounds — Get size and positional bounds for canvas widgets
+
+  Usage:
+    storyboard canvas bounds <canvas-name>                    All widgets
+    storyboard canvas bounds <canvas-name> --id <widget-id>   Specific widget
+    storyboard canvas bounds <canvas-name> --json             JSON output
+    storyboard canvas bounds --type <widget-type>             Show default size for a type
+`)
+    process.exit(0)
+  }
+
+  // --type mode: just show default size, no server needed
+  const typeIdx = args.indexOf('--type')
+  if (typeIdx !== -1 && args[typeIdx + 1]) {
+    const type = args[typeIdx + 1]
+    const size = getDefaultSize(type)
+    const outputJson = args.includes('--json')
+    if (outputJson) {
+      console.log(JSON.stringify({ type, ...size }))
+    } else {
+      console.log(`\n${bold(type)} default size: ${size.width} × ${size.height}\n`)
+    }
+    return
+  }
+
+  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
+    }
+  }
+
+  if (!canvasName) {
+    p.log.error('Canvas name is required. Usage: storyboard canvas bounds <canvas-name> [--id <widget-id>]')
+    process.exit(1)
+  }
+
+  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()
+
+  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 (widgetId) {
+      const widget = widgets[0]
+      if (!widget) {
+        p.log.error(`Widget "${widgetId}" not found in canvas "${canvasName}"`)
+        process.exit(1)
+      }
+      if (outputJson) {
+        console.log(JSON.stringify({ id: widget.id, type: widget.type, ...getBounds(widget) }))
+      } else {
+        console.log('')
+        console.log(formatBounds(widget))
+        console.log('')
+      }
+      return
+    }
+
+    // All widgets
+    if (outputJson) {
+      const result = widgets.map((w) => ({ id: w.id, type: w.type, ...getBounds(w) }))
+      console.log(JSON.stringify(result, 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(formatBounds(widget))
+          console.log('')
+        }
+      }
+    }
+  } catch (err) {
+    p.log.error(`Failed to read canvas bounds: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+canvasBounds()