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

package/src/cli/setup.js

@@ -6,16 +6,28 @@
 
 import * as p from '@clack/prompts'
 import { existsSync } from 'fs'
+import path from 'path'
 import { execSync } from 'child_process'
 import { generateCaddyfile, isCaddyInstalled, isCaddyRunning, startCaddy, reloadCaddy } from './proxy.js'
+import { gettingStartedLines, dim, magenta, bold, green, yellow } from './intro.js'
 
-// ANSI colors
-const dim = (s) => `\x1b[2m${s}\x1b[0m`
-const magenta = (s) => `\x1b[35m${s}\x1b[0m`
-const cyan = (s) => `\x1b[36m${s}\x1b[0m`
-const green = (s) => `\x1b[32m${s}\x1b[0m`
-const bold = (s) => `\x1b[1m${s}\x1b[0m`
-const white = (s) => `\x1b[97m${s}\x1b[0m`
+/**
+ * Run a potentially slow task with a spinner that only appears after 500ms.
+ * If the task completes quickly, shows the done message immediately.
+ */
+async function withSpin(label, doneMsg, fn) {
+  const spin = p.spinner()
+  const timer = setTimeout(() => spin.start(label), 500)
+  try {
+    await fn()
+    clearTimeout(timer)
+    spin.stop(doneMsg)
+  } catch (err) {
+    clearTimeout(timer)
+    spin.stop(`Failed: ${label}`)
+    throw err
+  }
+}
 
 function mascot() {
   const d = dim('·')
@@ -114,7 +126,115 @@ if (hasBrew) {
   }
 }
 
-// 5. Proxy
+// 5. VS Code CLI
+if (isInstalled('code')) {
+  p.log.success('VS Code CLI installed')
+} else {
+  // Try to install the `code` CLI from VS Code's known locations
+  const codePaths = [
+    '/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code',
+    '/usr/local/bin/code',
+  ]
+  let installed = false
+  for (const codePath of codePaths) {
+    if (existsSync(codePath)) {
+      p.log.success('VS Code CLI available (symlink exists)')
+      installed = true
+      break
+    }
+  }
+  if (!installed) {
+    // Try the VS Code shell command installer
+    const vsCodeApp = '/Applications/Visual Studio Code.app'
+    if (existsSync(vsCodeApp)) {
+      const shellScript = `${vsCodeApp}/Contents/Resources/app/bin/code`
+      if (existsSync(shellScript)) {
+        try {
+          // Create symlink in /usr/local/bin
+          run(`ln -sf "${shellScript}" /usr/local/bin/code`)
+          p.log.success('VS Code CLI installed (symlinked to /usr/local/bin/code)')
+          installed = true
+        } catch {
+          // Fall through to manual instructions
+        }
+      }
+    }
+    if (!installed) {
+      p.log.warning('VS Code CLI not found. Open VS Code and run:')
+      p.log.info('  Cmd+Shift+P → "Shell Command: Install \'code\' command in PATH"')
+    }
+  }
+}
+
+// 6. Git hooks
+{
+  // Create .githooks/ if it doesn't exist — copy from scaffold template
+  if (!existsSync('.githooks')) {
+    const scaffoldHooks = path.resolve(import.meta.dirname, '..', '..', 'scaffold', 'githooks')
+    if (existsSync(scaffoldHooks)) {
+      try {
+        run(`cp -r "${scaffoldHooks}" .githooks`)
+        run('chmod +x .githooks/*')
+      } catch { /* fall through */ }
+    }
+  }
+
+  if (existsSync('.githooks')) {
+    try {
+      run('git config core.hooksPath .githooks')
+      if (existsSync('.githooks/pre-push')) {
+        run('chmod +x .githooks/pre-push')
+      }
+      p.log.success('Git hooks activated (.githooks/)')
+    } catch {
+      p.log.warning('Failed to set git hooks path')
+    }
+  } else {
+    p.log.info(dim('No .githooks/ directory — run storyboard-scaffold first'))
+  }
+}
+
+// 7. Asset directories
+{
+  const dirs = ['assets/canvas/images', 'assets/canvas/snapshots']
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      try {
+        execSync(`mkdir -p ${dir}`, { stdio: 'pipe' })
+      } catch { /* ignore */ }
+    }
+  }
+  p.log.success('Canvas asset directories ready')
+}
+
+// 8. Playwright (for canvas snapshots)
+{
+  let hasPlaywright = false
+  try {
+    run('node -e "require(\'playwright\')"')
+    hasPlaywright = true
+  } catch { /* not installed */ }
+
+  if (hasPlaywright) {
+    p.log.success('Playwright installed')
+  } else {
+    try {
+      await withSpin(
+        'Installing Playwright + Chromium...',
+        'Playwright installed',
+        () => {
+          run('npm install --save-dev playwright')
+          run('npx playwright install chromium')
+        }
+      )
+    } catch {
+      p.log.warning('Install manually: npm install --save-dev playwright && npx playwright install chromium')
+      p.log.info(dim('Playwright is needed for `storyboard snapshots`'))
+    }
+  }
+}
+
+// 9. Proxy
 if (isCaddyInstalled()) {
   const proxySpin = p.spinner()
   const caddyfilePath = generateCaddyfile()
@@ -131,19 +251,9 @@ if (isCaddyInstalled()) {
 
 p.note(
   [
-    white(`Welcome! Storyboard is a design tool to build and`),
-    white(`collaborate on prototypes. Here's how to get started:`),
-    '',
-    `  ${green('npx storyboard dev')}                Start developing locally`,
-    `  ${green('npx storyboard create prototype')}   Create a prototype`,
-    `  ${green('npx storyboard create canvas')}      Create a canvas`,
-    '',
-    `  ${dim('Using an AI assistant? You can also ask it to')}`,
-    `  ${dim('"create a prototype" or "create a canvas" for you!')}`,
-    '',
-    `  ${dim('Docs:')} ${cyan('https://github.com/dfosco/storyboard/blob/main/README.md')}`,
+    ...gettingStartedLines(),
     '',
-    `  ${dim('PS: You can also use')} ${green('npx sb ...')} ${dim('for shorter commands')}`,
+    `  ${dim('Run')} ${yellow('npx storyboard')} ${dim('to see all commands')}`,
   ].join('\n'),
   'Getting started'
 )

package/src/cli/snapshots.js

@@ -0,0 +1,335 @@
+/**
+ * storyboard snapshots — batch-generate preview snapshots for canvas widgets.
+ *
+ * Fully standalone: reads JSONL from disk, spins up a temporary Vite server
+ * on an ephemeral port, uses Playwright to capture each embed at the widget's
+ * dimensions (both light and dark themes), writes images to src/canvas/images/,
+ * and appends a widgets_replaced event to the JSONL.
+ *
+ * Does NOT touch the user's running dev server or browser.
+ *
+ * Requires: playwright installed (globally or locally).
+ *
+ * Usage:
+ *   storyboard snapshots              # all canvases
+ *   storyboard snapshots <name>       # specific canvas
+ *   storyboard snapshots --force      # regenerate even if snapshots exist
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { materializeFromText, serializeEvent } from '../canvas/materializer.js'
+import * as p from '@clack/prompts'
+import { bold, dim, green, yellow, cyan } from './intro.js'
+
+const THEMES = ['light', 'dark']
+const SNAPSHOT_PORT = 19876
+
+// ── Disk I/O helpers ──
+
+function findCanvasFiles(root) {
+  const results = []
+  const ignore = new Set(['node_modules', 'dist', '.git', '.worktrees'])
+  function walk(dir, rel = '') {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (ignore.has(entry.name)) continue
+      const fullPath = path.join(dir, entry.name)
+      const relPath = rel ? `${rel}/${entry.name}` : entry.name
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath)
+      } else if (entry.name.endsWith('.canvas.jsonl')) {
+        results.push({ relPath, absPath: fullPath })
+      }
+    }
+  }
+  walk(root)
+  return results
+}
+
+function toCanvasId(relPath) {
+  return relPath
+    .replace(/\.canvas\.jsonl$/, '')
+    .replace(/\\/g, '/')
+}
+
+function readCanvasState(absPath) {
+  const raw = fs.readFileSync(absPath, 'utf-8')
+  return materializeFromText(raw)
+}
+
+function writeImage(imagesDir, widgetId, theme, buffer) {
+  fs.mkdirSync(imagesDir, { recursive: true })
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+  const dateStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
+  const filename = `snapshot-${widgetId}--${theme}--${dateStr}.png`
+  fs.writeFileSync(path.join(imagesDir, filename), buffer)
+  return filename
+}
+
+function appendWidgetsReplaced(jsonlPath, widgets) {
+  const event = {
+    event: 'widgets_replaced',
+    timestamp: new Date().toISOString(),
+    widgets,
+  }
+  fs.appendFileSync(jsonlPath, serializeEvent(event) + '\n', 'utf-8')
+}
+
+// ── Main ──
+
+async function run() {
+  const args = process.argv.slice(3)
+  const force = args.includes('--force')
+  const canvasFilter = args.find(a => !a.startsWith('--')) || null
+
+  p.intro(bold('storyboard snapshots'))
+
+  const root = process.cwd()
+  const imagesDir = path.join(root, 'assets', 'canvas', 'snapshots')
+
+  // Discover canvases from disk
+  const allFiles = findCanvasFiles(root)
+  const targets = canvasFilter
+    ? allFiles.filter(f => {
+        const id = toCanvasId(f.relPath)
+        return id === canvasFilter || id.includes(canvasFilter)
+      })
+    : allFiles
+
+  if (targets.length === 0) {
+    p.log.warn(canvasFilter
+      ? `No canvases matching "${canvasFilter}"`
+      : 'No canvases found')
+    process.exit(0)
+  }
+
+  p.log.info(`Found ${bold(targets.length)} canvas${targets.length > 1 ? 'es' : ''}`)
+
+  // Import playwright
+  let chromium
+  try {
+    const pw = await import('playwright')
+    chromium = pw.chromium
+  } catch {
+    p.log.error('Playwright is required for snapshot generation.')
+    p.log.info('Install: ' + yellow('npx storyboard setup'))
+    p.log.info('Or manually: ' + yellow('npm install --save-dev playwright && npx playwright install chromium'))
+    process.exit(1)
+  }
+
+  // Start a temporary Vite server on an ephemeral port
+  const serverSpin = p.spinner()
+  serverSpin.start('Starting temporary Vite server')
+  let server
+  try {
+    const { createServer } = await import('vite')
+    server = await createServer({
+      root,
+      server: { port: SNAPSHOT_PORT, strictPort: false },
+      logLevel: 'silent',
+    })
+    await server.listen()
+    const address = server.httpServer.address()
+    const serverUrl = `http://localhost:${address.port}`
+    serverSpin.stop(`Vite server ready at ${dim(serverUrl)}`)
+
+    const browser = await chromium.launch({ headless: true })
+
+    let totalWidgets = 0
+    let totalSnapshots = 0
+    let totalSkipped = 0
+
+    for (const { relPath, absPath } of targets) {
+      const canvasId = toCanvasId(relPath)
+      const spin = p.spinner()
+      spin.start(`Reading ${cyan(canvasId)}`)
+
+      let state
+      try {
+        state = readCanvasState(absPath)
+      } catch (err) {
+        spin.stop(`${canvasId}: failed to read — ${err.message}`)
+        continue
+      }
+
+      // Collect embeddable widgets (prototype + story + figma-embed)
+      const widgets = (state.widgets || []).filter(w =>
+        w.type === 'prototype' || w.type === 'story' || w.type === 'figma-embed'
+      )
+
+      if (widgets.length === 0) {
+        spin.stop(`${canvasId}: no embeddable widgets`)
+        continue
+      }
+
+      spin.stop(`${canvasId}: ${widgets.length} widget${widgets.length > 1 ? 's' : ''}`)
+      totalWidgets += widgets.length
+      let canvasDirty = false
+
+      for (const widget of widgets) {
+        const widgetLabel = widget.props?.label || widget.props?.exportName || widget.id
+        const rawW = widget.props?.width || 800
+        const rawH = widget.props?.height || 600
+        const isFigma = widget.type === 'figma-embed'
+
+        // Compute capture dimensions:
+        // - Story widgets have a 31px header above iframe content
+        // - Prototype widgets may have a zoom factor
+        // - Figma embeds use raw dimensions
+        const isStory = widget.type === 'story'
+        const zoom = widget.props?.zoom || 100
+        const scale = zoom / 100
+        const captureW = isStory ? rawW : isFigma ? rawW : Math.round(rawW / scale)
+        const captureH = isStory ? Math.max(rawH - 31, 100) : isFigma ? rawH : Math.round(rawH / scale)
+
+        // Figma embeds only need a single snapshot (no theme variants)
+        const themesNeeded = isFigma ? ['light'] : THEMES
+
+        // Check existing snapshots
+        const hasLight = !!widget.props?.snapshotLight
+        const hasDark = !!widget.props?.snapshotDark
+        const allExist = isFigma ? hasLight : (hasLight && hasDark)
+        if (allExist && !force) {
+          totalSkipped++
+          p.log.step(dim(`  ${widgetLabel} — snapshots exist, skipping`))
+          continue
+        }
+
+        const themesToCapture = force
+          ? themesNeeded
+          : themesNeeded.filter(t => t === 'light' ? !hasLight : !hasDark)
+
+        const embedUrl = resolveEmbedUrl(serverUrl, widget)
+        if (!embedUrl) {
+          p.log.warn(`  ${widgetLabel} — could not resolve embed URL, skipping`)
+          continue
+        }
+
+        const updates = {}
+
+        for (const theme of themesToCapture) {
+          const themeUrl = isFigma ? embedUrl : appendThemeParam(embedUrl, theme)
+          const wspin = p.spinner()
+          wspin.start(`  ${widgetLabel}${isFigma ? '' : ` (${theme})`} ${dim(`${captureW}×${captureH}`)}`)
+
+          try {
+            const context = await browser.newContext({
+              viewport: { width: captureW, height: captureH },
+              deviceScaleFactor: 2,
+              colorScheme: theme === 'dark' ? 'dark' : 'light',
+            })
+            const page = await context.newPage()
+
+            await page.goto(themeUrl, { waitUntil: 'networkidle', timeout: 30000 })
+            await page.waitForTimeout(isFigma ? 4000 : 2000)
+
+            const buffer = await page.screenshot({ type: 'png' })
+            await context.close()
+
+            const filename = writeImage(imagesDir, widget.id, theme, buffer)
+            const imageUrl = `/_storyboard/canvas/images/${filename}`
+            const themeKey = theme === 'dark' ? 'snapshotDark' : 'snapshotLight'
+            updates[themeKey] = imageUrl
+            totalSnapshots++
+            wspin.stop(green(`  ${widgetLabel} (${theme}) ✓`))
+          } catch (err) {
+            wspin.stop(`  ${widgetLabel} (${theme}) — ${err.message}`)
+          }
+        }
+
+        if (Object.keys(updates).length > 0) {
+          widget.props = { ...widget.props, ...updates }
+          canvasDirty = true
+        }
+      }
+
+      // Persist all snapshot updates in a single widgets_replaced event
+      if (canvasDirty) {
+        try {
+          appendWidgetsReplaced(absPath, state.widgets)
+        } catch (err) {
+          p.log.warn(`  ${canvasId}: failed to write JSONL — ${err.message}`)
+        }
+      }
+    }
+
+    await browser.close()
+
+    // Auto-commit snapshot files so they don't clutter git status
+    if (totalSnapshots > 0) {
+      try {
+        const { execSync } = await import(/* @vite-ignore */ 'node:child_process')
+        execSync('git add assets/canvas/snapshots/ src/canvas/', { cwd: root, stdio: 'pipe' })
+        execSync(
+          `git commit -m "chore: update canvas snapshots" --no-verify --allow-empty`,
+          { cwd: root, stdio: 'pipe' }
+        )
+        p.log.step(dim('Snapshots committed'))
+      } catch {
+        // Not in a git repo or nothing to commit — that's fine
+      }
+    }
+
+    p.outro([
+      green('Done!'),
+      `${bold(totalSnapshots)} snapshot${totalSnapshots !== 1 ? 's' : ''} generated`,
+      totalSkipped > 0 ? dim(`${totalSkipped} skipped (already exist)`) : '',
+      `across ${bold(totalWidgets)} widget${totalWidgets !== 1 ? 's' : ''}`,
+    ].filter(Boolean).join('  ·  '))
+  } finally {
+    if (server) await server.close()
+  }
+}
+
+// ── URL helpers ──
+
+function resolveEmbedUrl(serverUrl, widget) {
+  const { type, props } = widget
+  if (type === 'prototype') {
+    const src = props?.src
+    if (!src) return null
+    if (/^https?:\/\//.test(src)) return null
+    const cleaned = src.replace(/^\/branch--[^/]+/, '')
+    const hashIdx = cleaned.indexOf('#')
+    const base = hashIdx >= 0 ? cleaned.slice(0, hashIdx) : cleaned
+    const hash = hashIdx >= 0 ? cleaned.slice(hashIdx) : ''
+    const sep = base.includes('?') ? '&' : '?'
+    return `${serverUrl}${base}${sep}_sb_embed${hash}`
+  }
+  if (type === 'story') {
+    const storyId = props?.storyId
+    const exportName = props?.exportName || ''
+    if (!storyId) return null
+    const params = new URLSearchParams({ _sb_embed: '1' })
+    if (exportName) params.set('export', exportName)
+    return `${serverUrl}/components/${storyId}?${params}`
+  }
+  if (type === 'figma-embed') {
+    const url = props?.url
+    if (!url) return null
+    // Convert figma.com URL to embed.figma.com URL
+    try {
+      const parsed = new URL(url)
+      if (!/^(www\.)?figma\.com$/.test(parsed.hostname)) return null
+      parsed.hostname = 'embed.figma.com'
+      parsed.searchParams.delete('t')
+      parsed.searchParams.set('embed-host', 'share')
+      return parsed.toString()
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function appendThemeParam(url, theme) {
+  const sep = url.includes('?') ? '&' : '?'
+  return `${url}${sep}_sb_theme_target=prototype&_sb_canvas_theme=${theme}`
+}
+
+run().catch((err) => {
+  p.log.error(err.message)
+  process.exit(1)
+})

package/src/cli/updateVersion.js

@@ -56,18 +56,69 @@ const tag = channel || (targetVersion ? undefined : 'latest')
 const suffix = targetVersion ? `@${targetVersion}` : `@${tag}`
 const packages = [...storyboardPkgs].map(name => `${name}${suffix}`).join(' ')
 
-const label = channel ? `to ${channel}` : targetVersion ? `to ${targetVersion}` : ''
+// Resolve actual version from the registry when using a tag (channel or latest)
+let resolvedVersion
+if (tag) {
+  try {
+    const probe = [...storyboardPkgs][0]
+    resolvedVersion = execSync(`npm view ${probe}@${tag} version`, { encoding: 'utf8' }).trim()
+  } catch { /* fall back to showing the tag */ }
+}
+
+const displayVersion = resolvedVersion || targetVersion || tag
+const label = resolvedVersion && channel ? `to ${resolvedVersion} (${channel})` : resolvedVersion ? `to ${resolvedVersion}` : channel ? `to ${channel}` : targetVersion ? `to ${targetVersion}` : ''
 p.intro(`storyboard ${command}`)
 p.log.info(`Updating ${storyboardPkgs.size} package(s)${label ? ` ${label}` : ''}…`)
 for (const name of storyboardPkgs) {
-  p.log.message(`  ${name}${suffix}`)
+  p.log.message(`  ${name}@${displayVersion}`)
 }
 
 try {
   execSync(`npm install ${packages}`, { stdio: 'inherit', cwd: process.cwd() })
   p.log.success('All storyboard packages updated')
-  p.outro('Done')
 } catch {
   p.log.error('Failed to update packages — see npm output above')
   process.exit(1)
 }
+
+// Sync scaffold files (skills, scripts) from the updated package
+p.log.info('Syncing scaffold files…')
+try {
+  execSync('npx storyboard-scaffold', { stdio: 'inherit', cwd: process.cwd() })
+} catch {
+  p.log.warn('Scaffold sync failed — run `npx storyboard-scaffold` manually')
+}
+
+// Auto-commit the version update (only if package.json or lock file changed)
+try {
+  // Read the installed version from the core package
+  const corePkg = JSON.parse(readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard-core', 'package.json'), 'utf8'))
+  const installedVersion = corePkg.version || suffix.slice(1)
+  const commitMsg = `[storyboard-update] Update storyboard to ${installedVersion}`
+
+  // Only stage update-related files (package.json, lock files, scaffold outputs)
+  const filesToStage = [
+    'package.json',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    '.github/skills',
+    'scripts',
+  ]
+  for (const f of filesToStage) {
+    try { execSync(`git add ${f}`, { cwd: process.cwd(), stdio: 'pipe' }) } catch {}
+  }
+
+  // Only commit if there are staged changes
+  try {
+    execSync('git diff --cached --quiet', { cwd: process.cwd(), stdio: 'pipe' })
+    p.log.message('No changes to commit — already up to date')
+  } catch {
+    execSync(`git commit -m "${commitMsg}"`, { cwd: process.cwd(), stdio: 'pipe' })
+    p.log.success(`Committed: ${commitMsg}`)
+  }
+} catch (err) {
+  p.log.warn(`Auto-commit failed: ${err.message}`)
+}
+
+p.outro('Done')