@dfosco/storyboard-core 4.2.0-beta.3 → 4.2.0

package/src/canvas/server.test.js

@@ -138,3 +138,242 @@ describe('POST /create with convertFrom', () => {
     expect(lastResponse.body.error).toContain('collides')
   })
 })
+
+// ──────────────────────────────────────────────────
+// POST /batch
+// ──────────────────────────────────────────────────
+
+describe('POST /batch', () => {
+  let root, canvasDir, invoke, lastResponse
+
+  beforeEach(() => {
+    ({ invoke, root, canvasDir, lastResponse } = setup())
+    writeCanvas(canvasDir, 'test-canvas')
+  })
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true })
+  })
+
+  it('creates multiple widgets in one batch', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'A' } },
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'B' } },
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'C' } },
+      ],
+    })
+
+    expect(lastResponse.status).toBe(200)
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results).toHaveLength(3)
+    expect(lastResponse.body.results[0].widget.props.text).toBe('A')
+    expect(lastResponse.body.results[1].widget.props.text).toBe('B')
+    expect(lastResponse.body.results[2].widget.props.text).toBe('C')
+  })
+
+  it('auto-assigns index refs ($0, $1, ...)', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'first' } },
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'second' } },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    const { refs } = lastResponse.body
+    expect(refs['0']).toBe(lastResponse.body.results[0].widgetId)
+    expect(refs['1']).toBe(lastResponse.body.results[1].widgetId)
+  })
+
+  it('supports named refs alongside index refs', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', ref: 'header', props: { text: 'H' } },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    const { refs } = lastResponse.body
+    const widgetId = lastResponse.body.results[0].widgetId
+    expect(refs['0']).toBe(widgetId)
+    expect(refs['header']).toBe(widgetId)
+  })
+
+  it('resolves $index refs in create-connector', async () => {
+    // First create a widget to act as the "existing" terminal widget
+    await invoke('/widget', 'POST', { name: 'test-canvas', type: 'terminal', props: {} })
+    const terminalId = lastResponse.body.widget.id
+
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'target' } },
+        { op: 'create-connector', startWidgetId: terminalId, endWidgetId: '$0', startAnchor: 'right', endAnchor: 'left' },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results).toHaveLength(2)
+    expect(lastResponse.body.results[1].op).toBe('create-connector')
+    expect(lastResponse.body.results[1].connectorId).toBeTruthy()
+  })
+
+  it('resolves $named refs in update-widget', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', ref: 'note', props: { text: 'before' } },
+        { op: 'update-widget', widgetId: '$note', props: { text: 'after' } },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results[1].op).toBe('update-widget')
+    expect(lastResponse.body.results[1].success).toBe(true)
+  })
+
+  it('supports move-widget with ref resolution', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', position: { x: 0, y: 0 }, props: { text: 'X' } },
+        { op: 'move-widget', widgetId: '$0', position: { x: 500, y: 300 } },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results[1].op).toBe('move-widget')
+    expect(lastResponse.body.results[1].success).toBe(true)
+  })
+
+  it('supports delete-widget with ref resolution', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'temp' } },
+        { op: 'delete-widget', widgetId: '$0' },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results[1].op).toBe('delete-widget')
+    expect(lastResponse.body.results[1].success).toBe(true)
+  })
+
+  it('fails fast on unknown ref', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'ok' } },
+        { op: 'update-widget', widgetId: '$nonexistent', props: { text: 'fail' } },
+      ],
+    })
+
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.success).toBe(false)
+    expect(lastResponse.body.failedAt).toBe(1)
+    expect(lastResponse.body.error).toContain('Unknown ref')
+    // First operation's result should still be returned
+    expect(lastResponse.body.results).toHaveLength(1)
+    expect(lastResponse.body.results[0].op).toBe('create-widget')
+  })
+
+  it('fails fast on unknown operation type', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'explode-widget' },
+      ],
+    })
+
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.success).toBe(false)
+    expect(lastResponse.body.failedAt).toBe(0)
+    expect(lastResponse.body.error).toContain('Unknown operation')
+  })
+
+  it('rejects empty operations array', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [],
+    })
+
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.error).toContain('non-empty')
+  })
+
+  it('rejects missing canvas name', async () => {
+    await invoke('/batch', 'POST', {
+      operations: [{ op: 'create-widget', type: 'sticky-note' }],
+    })
+
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.error).toContain('Canvas name')
+  })
+
+  it('rejects batch exceeding 200 operations', async () => {
+    const ops = Array.from({ length: 201 }, (_, i) => ({
+      op: 'create-widget', type: 'sticky-note', props: { text: `#${i}` },
+    }))
+
+    await invoke('/batch', 'POST', { name: 'test-canvas', operations: ops })
+
+    expect(lastResponse.status).toBe(400)
+    expect(lastResponse.body.error).toContain('200')
+  })
+
+  it('returns 404 for unknown canvas', async () => {
+    await invoke('/batch', 'POST', {
+      name: 'nonexistent',
+      operations: [{ op: 'create-widget', type: 'sticky-note' }],
+    })
+
+    expect(lastResponse.status).toBe(404)
+  })
+
+  it('supports full create-update-move-connect workflow', async () => {
+    // Create a pre-existing terminal widget for connectors
+    await invoke('/widget', 'POST', { name: 'test-canvas', type: 'terminal', props: {} })
+    const termId = lastResponse.body.widget.id
+
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', position: { x: 100, y: 100 }, props: { text: 'Draft' } },
+        { op: 'update-widget', widgetId: '$0', props: { text: 'Final', color: 'blue' } },
+        { op: 'move-widget', widgetId: '$0', position: { x: 500, y: 300 } },
+        { op: 'create-connector', startWidgetId: termId, endWidgetId: '$0', startAnchor: 'right', endAnchor: 'left' },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    expect(lastResponse.body.results).toHaveLength(4)
+    expect(lastResponse.body.results[0].op).toBe('create-widget')
+    expect(lastResponse.body.results[1].op).toBe('update-widget')
+    expect(lastResponse.body.results[2].op).toBe('move-widget')
+    expect(lastResponse.body.results[3].op).toBe('create-connector')
+  })
+
+  it('connector refs also get index refs', async () => {
+    await invoke('/widget', 'POST', { name: 'test-canvas', type: 'terminal', props: {} })
+    const termId = lastResponse.body.widget.id
+
+    await invoke('/batch', 'POST', {
+      name: 'test-canvas',
+      operations: [
+        { op: 'create-widget', type: 'sticky-note', props: { text: 'A' } },
+        { op: 'create-connector', startWidgetId: termId, endWidgetId: '$0', startAnchor: 'right', endAnchor: 'left' },
+      ],
+    })
+
+    expect(lastResponse.body.success).toBe(true)
+    const { refs } = lastResponse.body
+    // Op 0 = widget, Op 1 = connector — both get index refs
+    expect(refs['0']).toMatch(/^sticky-note-/)
+    expect(refs['1']).toMatch(/^connector-/)
+  })
+})

package/src/canvas/terminal-config.js

@@ -0,0 +1,330 @@
+/**
+ * Terminal Config — per-terminal context files for agent awareness.
+ *
+ * Each terminal widget gets a config at `.storyboard/terminals/{hash}.json`
+ * that agents read on startup to understand their canvas context.
+ *
+ * Files are keyed by a stable hash (same as tmuxName) so renames don't break them.
+ * The canvasId/widgetId are stored inside the JSON payload.
+ *
+ * Connected widgets are stored as IDs only — full widget data is resolved
+ * from the materialized canvas state at read time to stay fresh.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, symlinkSync, unlinkSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { createHash } from 'node:crypto'
+import { findByWorktree } from '../worktree/serverRegistry.js'
+import { detectWorktreeName } from '../worktree/port.js'
+import { readCurrentViewport } from './selectedWidgets.js'
+
+const TERMINALS_DIR = '.storyboard/terminals'
+
+let rootDir = process.cwd()
+
+/** Initialize with the project root directory */
+export function initTerminalConfig(root) {
+  rootDir = root
+  const dir = join(rootDir, TERMINALS_DIR)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+/** Read storyboard.config.json for devDomain */
+function readDevDomain() {
+  try {
+    const raw = readFileSync(join(rootDir, 'storyboard.config.json'), 'utf8')
+    return JSON.parse(raw).devDomain || 'storyboard'
+  } catch { return 'storyboard' }
+}
+
+/** Detect worktree name */
+function getWorktreeName() {
+  try {
+    // Check if we're in a .worktrees/ directory
+    const cwd = rootDir
+    const match = cwd.match(/\.worktrees\/([^/]+)/)
+    return match ? match[1] : 'main'
+  } catch { return 'main' }
+}
+
+/** Generate a stable filename from branch + canvasId + widgetId */
+function configKey(branch, canvasId, widgetId) {
+  const input = `${branch}::${canvasId}::${widgetId}`
+  return createHash('sha256').update(input).digest('hex').slice(0, 16)
+}
+
+/** Get the config file path */
+function configPath(branch, canvasId, widgetId) {
+  return join(rootDir, TERMINALS_DIR, `${configKey(branch, canvasId, widgetId)}.json`)
+}
+
+/** Atomic write — write to temp then rename */
+function atomicWrite(filePath, data) {
+  const tmp = filePath + '.tmp'
+  writeFileSync(tmp, JSON.stringify(data, null, 2))
+  renameSync(tmp, filePath)
+}
+
+/**
+ * Pre-reserve terminal identity at widget creation time.
+ * Called from POST /widget when a terminal/agent widget is added to the canvas,
+ * BEFORE the widget renders or the WebSocket connects.
+ *
+ * Writes a minimal config file at `.storyboard/terminals/{widgetId}.json` so
+ * agents (especially hot-pool sessions) can find their identity immediately.
+ * The `reserved` flag marks this as a pre-reserve — writeTerminalConfig() will
+ * later overwrite it with the full config.
+ */
+export function preReserveTerminalIdentity({ widgetId, preDisplayName, canvasId, branch, serverUrl }) {
+  const dir = join(rootDir, TERMINALS_DIR)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  const fp = join(dir, `${widgetId}.json`)
+  const data = {
+    widgetId,
+    preDisplayName,
+    displayName: preDisplayName,
+    canvasId,
+    branch,
+    serverUrl: serverUrl || null,
+    reserved: true,
+    connectedWidgets: [],
+    messaging: null,
+    agentStatus: null,
+    viewport: readCurrentViewport(rootDir) || null,
+    updatedAt: new Date().toISOString(),
+  }
+  atomicWrite(fp, data)
+}
+
+/**
+ * Write or update a terminal config file.
+ * Called when a terminal widget is created or reconnected.
+ */
+export function writeTerminalConfig({ branch, canvasId, widgetId, canvasFile = null, serverUrl = null, tmuxName = null, widgetProps = null, displayName = null }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  const dir = dirname(fp)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  let existing = {}
+  try {
+    existing = JSON.parse(readFileSync(fp, 'utf8'))
+  } catch { /* new file */ }
+
+  const worktree = getWorktreeName()
+  const devDomain = readDevDomain()
+
+  // Resolve server URL: use passed value, or query server registry, or default
+  if (!serverUrl) {
+    try {
+      const name = detectWorktreeName()
+      const servers = findByWorktree(name)
+      if (servers.length > 0) serverUrl = `http://localhost:${servers[0].port}`
+    } catch { /* empty */ }
+  }
+  if (!serverUrl) serverUrl = 'http://localhost:1234'
+
+  const config = {
+    ...existing,
+    widgetId,
+    displayName: displayName || existing.displayName || widgetProps?.prettyName || existing.widgetProps?.prettyName || null,
+    canvasId,
+    canvasFile: canvasFile || existing.canvasFile || null,
+    branch,
+    worktree,
+    devDomain,
+    serverUrl,
+    workingDirectory: rootDir,
+    deleted: false,
+    widgetProps: widgetProps || existing.widgetProps || null,
+    connectedWidgets: existing.connectedWidgets || [],
+    agentStatus: existing.agentStatus || null,
+    viewport: readCurrentViewport(rootDir) || existing.viewport || null,
+    updatedAt: new Date().toISOString(),
+  }
+
+  atomicWrite(fp, config)
+
+  // Create a widgetId-named symlink so agents can find their config directly
+  const hashName = `${configKey(branch, canvasId, widgetId)}.json`
+  const symPath = join(dir, `${widgetId}.json`)
+  try {
+    if (existsSync(symPath)) unlinkSync(symPath)
+    symlinkSync(hashName, symPath)
+  } catch { /* symlink creation is best-effort */ }
+
+  // Create a tmuxName-named symlink so agents can resolve identity via tmux session name
+  // (tmux session name is always available and never goes stale)
+  if (tmuxName) {
+    const tmuxSymPath = join(dir, `${tmuxName}.json`)
+    try {
+      if (existsSync(tmuxSymPath)) unlinkSync(tmuxSymPath)
+      symlinkSync(hashName, tmuxSymPath)
+    } catch { /* best-effort */ }
+  }
+
+  return config
+}
+
+/**
+ * Update connected widgets for a terminal.
+ * Called when connectors are added/removed.
+ * Stores full widget objects (id, type, props, position) so agents
+ * can read context directly without additional API calls.
+ */
+export function updateTerminalConnections({ branch, canvasId, widgetId, connectedWidgets, widgetProps = null, messaging = null }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  let config = {}
+  try {
+    config = JSON.parse(readFileSync(fp, 'utf8'))
+  } catch { /* file may not exist yet */ }
+
+  if (widgetProps) {
+    config.widgetProps = widgetProps
+    // Promote displayName from prettyName
+    if (widgetProps.prettyName) config.displayName = widgetProps.prettyName
+  }
+  config.connectedWidgets = connectedWidgets || []
+  config.messaging = messaging || null
+  config.viewport = readCurrentViewport(rootDir) || config.viewport || null
+  config.updatedAt = new Date().toISOString()
+
+  atomicWrite(fp, config)
+  return config
+}
+
+/**
+ * Mark a terminal config as deleted (tombstone).
+ * Called when a terminal widget is deleted.
+ */
+export function markTerminalDeleted({ branch, canvasId, widgetId }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  try {
+    const config = JSON.parse(readFileSync(fp, 'utf8'))
+    config.deleted = true
+    config.updatedAt = new Date().toISOString()
+    atomicWrite(fp, config)
+  } catch { /* file may not exist */ }
+}
+
+/**
+ * Unmark a terminal config as deleted (undo).
+ * Called when a deleted terminal widget is restored.
+ */
+export function unmarkTerminalDeleted({ branch, canvasId, widgetId }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  try {
+    const config = JSON.parse(readFileSync(fp, 'utf8'))
+    config.deleted = false
+    config.updatedAt = new Date().toISOString()
+    atomicWrite(fp, config)
+  } catch { /* file may not exist */ }
+}
+
+/**
+ * Read a terminal config. Connected widgets are already inline —
+ * no additional resolution needed.
+ */
+export function readTerminalConfig({ branch, canvasId, widgetId }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  try {
+    return JSON.parse(readFileSync(fp, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Update agent status in the terminal config.
+ * Called by the signal endpoint.
+ */
+export function updateAgentStatus({ branch, canvasId, widgetId, status, message = null, data = null }) {
+  const fp = configPath(branch, canvasId, widgetId)
+  let config = {}
+  try {
+    config = JSON.parse(readFileSync(fp, 'utf8'))
+  } catch { /* may not exist */ }
+
+  config.agentStatus = {
+    status,
+    message,
+    data,
+    updatedAt: new Date().toISOString(),
+  }
+  config.updatedAt = new Date().toISOString()
+
+  atomicWrite(fp, config)
+  return config
+}
+
+/**
+ * Read a terminal config by widget ID (searches by symlink).
+ * @param {string} widgetId
+ * @returns {Object|null}
+ */
+export function readTerminalConfigById(widgetId) {
+  const dir = join(rootDir, TERMINALS_DIR)
+  const symPath = join(dir, `${widgetId}.json`)
+  try {
+    return JSON.parse(readFileSync(symPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Append a pending message to a terminal's config.
+ * Messages are delivered when the agent starts or reconnects.
+ * @param {string} widgetId
+ * @param {{ from: string|null, fromName: string, message: string, createdAt: string }} msg
+ */
+export function updatePendingMessages(widgetId, msg) {
+  const config = readTerminalConfigById(widgetId)
+  if (!config) return
+
+  if (!Array.isArray(config.pendingMessages)) config.pendingMessages = []
+  config.pendingMessages.push(msg)
+  config.updatedAt = new Date().toISOString()
+
+  // Write back using the config's known path
+  const fp = configPath(config.branch || 'unknown', config.canvasId || 'unknown', widgetId)
+  atomicWrite(fp, config)
+}
+
+/**
+ * Atomically read and clear pending messages from a terminal config.
+ * Returns the messages array (empty if none). Safe to call from any process.
+ * @param {string} widgetId
+ * @returns {Array<{ from: string|null, fromName: string, message: string, createdAt: string }>}
+ */
+export function takePendingMessages(widgetId) {
+  const config = readTerminalConfigById(widgetId)
+  if (!config?.pendingMessages?.length) return []
+
+  const messages = config.pendingMessages
+  config.pendingMessages = []
+  config.updatedAt = new Date().toISOString()
+
+  // Write back via hash path (not symlink) to preserve symlink integrity
+  const fp = configPath(config.branch || 'unknown', config.canvasId || 'unknown', widgetId)
+  atomicWrite(fp, config)
+  return messages
+}
+
+/**
+ * Save the latest output from an agent for peers to read.
+ * @param {string} widgetId
+ * @param {{ content: string, summary: string, updatedAt: string }} output
+ */
+export function updateLatestOutput(widgetId, output) {
+  const config = readTerminalConfigById(widgetId)
+  if (!config) return
+
+  config.latestOutput = output
+  config.updatedAt = new Date().toISOString()
+
+  const fp = configPath(config.branch || 'unknown', config.canvasId || 'unknown', widgetId)
+  atomicWrite(fp, config)
+}

package/src/canvas/terminal-registry.js

@@ -112,7 +112,7 @@ export function initRegistry(root, options = {}) {
   registryPath = join(dir, REGISTRY_FILE)
 
   // Ensure .storyboard/ exists
-  try { mkdirSync(dir, { recursive: true }) } catch {}
+  try { mkdirSync(dir, { recursive: true }) } catch { /* empty */ }
 
   // Load persisted state
   try {
@@ -305,6 +305,44 @@ export function killSession(tmuxName) {
   persist()
 }
 
+/**
+ * Bulk cleanup — kill all sessions matching the given statuses.
+ * Returns { removed, remaining: { live, background, archived, total } }.
+ */
+export function bulkCleanup({ statuses }) {
+  const statusSet = new Set(statuses)
+  const toKill = []
+
+  for (const [name, entry] of sessions) {
+    if (statusSet.has(entry.status)) {
+      toKill.push(name)
+    }
+  }
+
+  for (const name of toKill) {
+    cancelOrphanTimer(name)
+    killTmuxSession(name)
+    sessions.delete(name)
+  }
+
+  if (toKill.length > 0) persist()
+
+  return { removed: toKill.length, remaining: getSessionStats() }
+}
+
+/**
+ * Get session counts by status.
+ */
+export function getSessionStats() {
+  let live = 0, background = 0, archived = 0
+  for (const entry of sessions.values()) {
+    if (entry.status === 'live') live++
+    else if (entry.status === 'background') background++
+    else if (entry.status === 'archived') archived++
+  }
+  return { live, background, archived, total: live + background + archived }
+}
+
 /**
  * Get a session entry by tmux name.
  */
@@ -353,7 +391,7 @@ function persist() {
   try {
     const entries = Array.from(sessions.values())
     writeFileSync(registryPath, JSON.stringify(entries, null, 2))
-  } catch {}
+  } catch { /* empty */ }
 }
 
 function listTmuxSessions() {
@@ -375,7 +413,7 @@ function listTmuxSessions() {
 function killTmuxSession(name) {
   try {
     execSync(`tmux kill-session -t "${name}" 2>/dev/null`, { stdio: 'ignore' })
-  } catch {}
+  } catch { /* empty */ }
 }
 
 function armOrphanTimer(tmuxName, delayMs) {