@dfosco/storyboard 0.5.0-alpha.0

package/src/core/server/index.js

@@ -0,0 +1,391 @@
+/**
+ * Storyboard Server — persistent Node.js process that manages dev sessions.
+ *
+ * Runs independently of Vite. Manages:
+ * - Vite child processes (one per active branch)
+ * - /_storyboard/ API (workshop, canvas, comments, worktrees, branch switching)
+ * - Caddy proxy route registration
+ *
+ * Architecture:
+ *   Browser → Caddy → Vite (serves app + static)
+ *   Browser → Caddy → Storyboard Server (serves /_storyboard/ API)
+ *   Storyboard Server → spawns/manages Vite processes
+ */
+
+import http from 'node:http'
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { getPort, releasePort, repoRoot } from '../worktree/port.js'
+import { generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, reloadCaddy, readDevDomain } from '../cli/proxy.js'
+import { compactAll } from '../canvas/compact.js'
+import { register, unregister, generateId, list, findByWorktree } from '../worktree/serverRegistry.js'
+import { createDevLogger } from '../logger/devLogger.js'
+
+const SERVER_PORT_BASE = 4100
+
+/**
+ * Derive a deterministic server port from the devDomain.
+ * Each repo (identified by its devDomain) gets its own port.
+ */
+function deriveServerPort(domain) {
+  let h = 0
+  for (let i = 0; i < domain.length; i++) {
+    h = ((h << 5) - h + domain.charCodeAt(i)) | 0
+  }
+  // Map to port range 4100-4199
+  return SERVER_PORT_BASE + (Math.abs(h) % 100)
+}
+
+const DEV_DOMAIN = readDevDomain()
+export const SERVER_PORT = deriveServerPort(DEV_DOMAIN)
+const HEALTH_TIMEOUT = 30_000
+const HEALTH_INTERVAL = 300
+
+/** Active Vite processes: branch name → { child, port, status, cwd } */
+const processes = new Map()
+
+/** Route handlers: prefix → handler function */
+const routeHandlers = new Map()
+
+// ─── Dev Logger ───
+
+let _currentBranch = null
+try { _currentBranch = (await import('node:child_process')).execSync('git branch --show-current', { encoding: 'utf8', cwd: repoRoot() }).trim() } catch { /* empty */ }
+const devLogger = createDevLogger({ root: repoRoot(), devDomain: DEV_DOMAIN.replace('.localhost', ''), branch: _currentBranch })
+
+// ─── JSON helpers ───
+
+function sendJson(res, status, data) {
+  const body = JSON.stringify(data)
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' })
+  res.end(body)
+}
+
+function sendJsonLogged(res, status, data) {
+  sendJson(res, status, data)
+  if (status >= 400) {
+    const ctx = res.__sbLogCtx || {}
+    devLogger.logResponse({
+      status,
+      method: ctx.method || 'UNKNOWN',
+      url: ctx.url || '',
+      route: ctx.route || null,
+      subRoute: ctx.subRoute || null,
+      error: data?.error || null,
+    })
+  }
+}
+
+async function parseBody(req) {
+  const chunks = []
+  for await (const chunk of req) chunks.push(chunk)
+  try { return JSON.parse(Buffer.concat(chunks).toString()) }
+  catch { return {} }
+}
+
+// ─── Vite Process Management ───
+
+function resolveWorktreeCwd(branch) {
+  const root = repoRoot()
+  if (branch === 'main') return root
+  const wtDir = join(root, 'worktrees', branch)
+  if (existsSync(wtDir)) return wtDir
+  return null
+}
+
+function isPortReady(port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}`, () => resolve(true))
+    req.on('error', () => resolve(false))
+    req.setTimeout(1000, () => { req.destroy(); resolve(false) })
+  })
+}
+
+async function waitForPort(port, timeout = HEALTH_TIMEOUT) {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (await isPortReady(port)) return true
+    await new Promise(r => setTimeout(r, HEALTH_INTERVAL))
+  }
+  return false
+}
+
+function buildBasePath(branch) {
+  return branch === 'main' ? '/' : `/branch--${branch}/`
+}
+
+function spawnVite(branch) {
+  const cwd = resolveWorktreeCwd(branch)
+  if (!cwd) throw new Error(`Worktree not found for branch: ${branch}`)
+
+  const port = getPort(branch)
+  const basePath = buildBasePath(branch)
+  const localVite = resolve(cwd, 'node_modules', '.bin', 'vite')
+  const useLocalVite = existsSync(localVite)
+
+  // Compact canvas files before starting
+  try { compactAll(cwd) } catch { /* non-critical */ }
+
+  const viteArgs = ['--port', String(port)]
+  const child = useLocalVite
+    ? spawn(localVite, viteArgs, {
+        cwd,
+        env: { ...process.env, VITE_BASE_PATH: basePath },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    : spawn('npx', ['vite', ...viteArgs], {
+        cwd,
+        env: { ...process.env, VITE_BASE_PATH: basePath },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+
+  const entry = { child, port, status: 'starting', cwd, branch, serverId: generateId() }
+  processes.set(branch, entry)
+
+  // Register in persistent server registry
+  register({ id: entry.serverId, worktree: branch, pid: child.pid, port, background: true })
+
+  // Detect ready state from stdout
+  child.stdout.on('data', (data) => {
+    const text = data.toString()
+    const portMatch = text.match(/localhost:(\d+)/)
+    if (portMatch) {
+      const actualPort = Number(portMatch[1])
+      if (actualPort !== entry.port) {
+        entry.port = actualPort
+        // Re-register with the actual port Vite bound to
+        register({ id: entry.serverId, worktree: branch, pid: child.pid, port: actualPort, background: true })
+      }
+    }
+    if (text.includes('ready in')) {
+      entry.status = 'ready'
+      registerCaddyRoute(branch, entry.port)
+    }
+  })
+
+  child.stderr.on('data', () => { /* suppress */ })
+
+  child.on('exit', (_code) => {
+    void _code
+    entry.status = 'stopped'
+    processes.delete(branch)
+    unregister(entry.serverId)
+    releasePort(branch)
+  })
+
+  return entry
+}
+
+function stopVite(branch) {
+  const entry = processes.get(branch)
+  if (!entry) return
+  try { entry.child.kill('SIGTERM') } catch { /* */ }
+  processes.delete(branch)
+}
+
+function registerCaddyRoute(branch, port) {
+  try {
+    const routeConfig = generateRouteConfig({ [branch]: port })
+    if (isCaddyRunning() && upsertCaddyRoute(routeConfig)) {
+      generateCaddyfile({ [branch]: port })
+    } else {
+      const caddyfilePath = generateCaddyfile({ [branch]: port })
+      if (isCaddyRunning()) reloadCaddy(caddyfilePath)
+    }
+  } catch { /* Caddy not available */ }
+}
+
+// ─── API Routes ───
+
+// POST /_storyboard/switch-branch
+routeHandlers.set('switch-branch', async (req, res, ctx) => {
+  if (ctx.method !== 'POST') {
+    sendJsonLogged(res, 405, { error: 'POST required' })
+    return
+  }
+
+  const { branch } = ctx.body
+  if (!branch) {
+    sendJsonLogged(res, 400, { error: 'branch is required' })
+    return
+  }
+
+  const devDomain = readDevDomain()
+  const targetUrl = branch === 'main'
+    ? `http://${devDomain}/`
+    : `http://${devDomain}/branch--${branch}/`
+
+  try {
+    // Check if already running
+    const existing = processes.get(branch)
+    if (existing && existing.status === 'ready') {
+      const alive = await isPortReady(existing.port)
+      if (alive) {
+        sendJsonLogged(res, 200, { url: targetUrl, status: 'already_running' })
+        return
+      }
+      // Stale entry — remove it
+      processes.delete(branch)
+    }
+
+    // Check if Vite is already running in this server's process map
+    const _port = getPort(branch)
+    void _port
+    const existingInRegistry = findByWorktree(branch)
+    if (existingInRegistry.length > 0) {
+      const latest = existingInRegistry.reduce((a, b) =>
+        (a.startedAt || '') >= (b.startedAt || '') ? a : b
+      )
+      if (await isPortReady(latest.port)) {
+        registerCaddyRoute(branch, latest.port)
+        sendJsonLogged(res, 200, { url: targetUrl, status: 'already_running' })
+        return
+      }
+    }
+
+    // Check worktree exists
+    const cwd = resolveWorktreeCwd(branch)
+    if (!cwd) {
+      sendJsonLogged(res, 404, { error: `Worktree not found: ${branch}. Create it with: npx storyboard dev ${branch}` })
+      return
+    }
+
+    // Spawn Vite
+    const entry = spawnVite(branch)
+
+    // Wait for Vite to report ready via stdout (not TCP polling, which
+    // can false-positive on occupied ports from other processes)
+    const ready = await (async () => {
+      const start = Date.now()
+      while (Date.now() - start < HEALTH_TIMEOUT) {
+        if (entry.status === 'ready') return true
+        await new Promise(r => setTimeout(r, 300))
+      }
+      return false
+    })()
+    if (!ready) {
+      stopVite(branch)
+      sendJsonLogged(res, 504, { error: `Vite server for ${branch} did not become ready in time` })
+      return
+    }
+
+    sendJsonLogged(res, 200, { url: targetUrl, status: 'started' })
+  } catch (err) {
+    sendJsonLogged(res, 500, { error: err.message })
+  }
+})
+
+// GET /_storyboard/worktrees
+routeHandlers.set('worktrees', async (req, res) => {
+  try {
+    // Use the server registry (live processes) instead of stale ports.json
+    const servers = list()
+    const branches = servers.map(srv => ({
+      branch: srv.worktree,
+      folder: srv.worktree === 'main' ? '' : `branch--${srv.worktree}/`,
+      port: srv.port,
+      running: processes.has(srv.worktree) ? processes.get(srv.worktree).status : 'background',
+    }))
+    // Always include main even if no server is registered for it
+    if (!branches.some(b => b.branch === 'main')) {
+      branches.unshift({ branch: 'main', folder: '', port: 1234, running: null })
+    }
+    sendJsonLogged(res, 200, branches)
+  } catch { sendJsonLogged(res, 200, []) }
+})
+
+// GET /_storyboard/server/status
+routeHandlers.set('server', async (req, res, ctx) => {
+  if (ctx.path === '/status' || ctx.path === '/') {
+    const active = []
+    for (const [branch, entry] of processes) {
+      active.push({ branch, port: entry.port, status: entry.status })
+    }
+    sendJsonLogged(res, 200, { active, serverPort: SERVER_PORT })
+    return
+  }
+  sendJsonLogged(res, 404, { error: 'Unknown server route' })
+})
+
+// ─── HTTP Server ───
+
+const server = http.createServer(async (req, res) => {
+  // CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+    })
+    res.end()
+    return
+  }
+
+  const url = new URL(req.url, `http://localhost:${SERVER_PORT}`)
+  const pathname = url.pathname
+
+  // Route /_storyboard/{prefix}/{rest}
+  if (pathname.startsWith('/_storyboard/')) {
+    const after = pathname.slice('/_storyboard/'.length)
+    const slashIdx = after.indexOf('/')
+    const prefix = slashIdx === -1 ? after : after.slice(0, slashIdx)
+    const restPath = slashIdx === -1 ? '/' : after.slice(slashIdx)
+
+    // Attach route context for the logging sendJson wrapper
+    res.__sbLogCtx = { method: req.method, url: req.url, route: prefix, subRoute: restPath }
+
+    const handler = routeHandlers.get(prefix)
+    if (handler) {
+      let body = {}
+      if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+        body = await parseBody(req)
+      }
+      try {
+        await handler(req, res, { body, path: restPath, method: req.method })
+      } catch (err) {
+        sendJsonLogged(res, 500, { error: err.message })
+      }
+      return
+    }
+  }
+
+  // Health check
+  if (pathname === '/health') {
+    sendJsonLogged(res, 200, { ok: true, devDomain: DEV_DOMAIN })
+    return
+  }
+
+  // Set context for catch-all 404
+  res.__sbLogCtx = { method: req.method, url: req.url, route: null, subRoute: null }
+  sendJsonLogged(res, 404, { error: 'Not found' })
+})
+
+export function startServer(port = SERVER_PORT) {
+  return new Promise((resolve, reject) => {
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        reject(Object.assign(new Error(`Port ${port} already in use`), { code: 'EADDRINUSE' }))
+        return
+      }
+      reject(err)
+    })
+    server.listen(port, () => {
+      resolve(server)
+    })
+  })
+}
+
+/** Public API for spawning Vite from CLI (with stdout piping) */
+export function spawnViteForBranch(branch, { pipeOutput = false } = {}) {
+  const entry = spawnVite(branch)
+
+  if (pipeOutput) {
+    entry.child.stdout.pipe(process.stdout)
+    entry.child.stderr.pipe(process.stderr)
+  }
+
+  return entry
+}
+
+export { processes, routeHandlers, waitForPort, isPortReady }

package/src/core/session/bodyClasses.js

@@ -0,0 +1,128 @@
+/**
+ * Body class sync for overrides and scenes.
+ *
+ * Mirrors active overrides as `sb-{key}--{value}` classes on <body>
+ * and the active scene as `sb-scene--{name}`.
+ *
+ * Works in both normal mode (URL hash) and hide mode (localStorage shadows).
+ */
+
+import { getAllParams } from './session.js'
+import { isHideMode, getAllShadows } from './hideMode.js'
+import { subscribeToHash } from './hashSubscribe.js'
+import { subscribeToStorage } from './localStorage.js'
+import { syncFlagBodyClasses } from '../stores/featureFlags.js'
+
+const PREFIX = 'sb-'
+const FLOW_PREFIX = 'sb-scene--'
+
+/**
+ * Sanitize a string for use in a CSS class name.
+ * Dots and spaces become dashes, lowercased, non-alphanumeric stripped.
+ * @param {string} str
+ * @returns {string}
+ */
+function sanitize(str) {
+  return String(str)
+    .toLowerCase()
+    .replace(/[.\s]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+/**
+ * Build the class name for an override key/value pair.
+ * @param {string} key
+ * @param {string} value
+ * @returns {string}
+ */
+function overrideClass(key, value) {
+  return `${PREFIX}${sanitize(key)}--${sanitize(value)}`
+}
+
+/**
+ * Get all current sb- override classes on body.
+ * Override classes follow the pattern `sb-{key}--{value}` (double-dash separator).
+ * Other sb-* classes (comment mode, feature flags, etc.) are excluded
+ * because they don't contain the `--` separator.
+ * Flow/scene classes (`sb-scene--*`) are also excluded since they use
+ * the same `--` separator but have their own lifecycle.
+ * @returns {Set<string>}
+ */
+function getCurrentOverrideClasses() {
+  const classes = new Set()
+  for (const cls of document.body.classList) {
+    if (cls.startsWith(PREFIX) && cls.includes('--') && !cls.startsWith(FLOW_PREFIX)) {
+      classes.add(cls)
+    }
+  }
+  return classes
+}
+
+/**
+ * Sync override classes on <body> with current hash/shadow state.
+ * Diffs against existing classes to minimize DOM mutations.
+ */
+export function syncOverrideClasses() {
+  const overrides = isHideMode() ? getAllShadows() : getAllParams()
+  const desired = new Set()
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key && value != null && value !== '') {
+      desired.add(overrideClass(key, value))
+    }
+  }
+
+  const current = getCurrentOverrideClasses()
+
+  // Remove stale classes
+  for (const cls of current) {
+    if (!desired.has(cls)) {
+      document.body.classList.remove(cls)
+    }
+  }
+  // Add missing classes
+  for (const cls of desired) {
+    if (!current.has(cls)) {
+      document.body.classList.add(cls)
+    }
+  }
+}
+
+/**
+ * Set the flow class on <body>. Removes any previous flow class.
+ * @param {string} name - Flow name (e.g. "Dashboard")
+ */
+export function setFlowClass(name) {
+  // Remove any existing flow classes
+  for (const cls of [...document.body.classList]) {
+    if (cls.startsWith(FLOW_PREFIX)) {
+      document.body.classList.remove(cls)
+    }
+  }
+  if (name) {
+    document.body.classList.add(`${FLOW_PREFIX}${sanitize(name)}`)
+  }
+}
+
+/** @deprecated Use setFlowClass() */
+export const setSceneClass = setFlowClass
+
+/**
+ * Install listeners that keep body classes in sync with overrides.
+ * Subscribes to both hashchange (normal mode) and storage (hide mode).
+ * Runs an initial sync immediately.
+ *
+ * @returns {function} unsubscribe — removes all listeners
+ */
+export function installBodyClassSync() {
+  syncOverrideClasses()
+  syncFlagBodyClasses()
+  const sync = () => { syncOverrideClasses(); syncFlagBodyClasses() }
+  const unsubHash = subscribeToHash(sync)
+  const unsubStorage = subscribeToStorage(sync)
+  return () => {
+    unsubHash()
+    unsubStorage()
+  }
+}

package/src/core/session/bodyClasses.test.js

@@ -0,0 +1,192 @@
+import {
+  syncOverrideClasses,
+  setFlowClass,
+  setSceneClass,
+  installBodyClassSync,
+} from './bodyClasses.js'
+import { activateHideMode, deactivateHideMode, setShadow } from './hideMode.js'
+
+/**
+ * Collect all sb- prefixed classes currently on document.body.
+ * @returns {string[]}
+ */
+function getSbClasses() {
+  return [...document.body.classList].filter((c) => c.startsWith('sb-'))
+}
+
+beforeEach(() => {
+  // Clear all sb- classes and hash between tests
+  for (const cls of getSbClasses()) {
+    document.body.classList.remove(cls)
+  }
+  window.location.hash = ''
+  // Ensure hide mode is off
+  try {
+    deactivateHideMode()
+  } catch {
+    // ignore if not active
+  }
+})
+
+// ── Override Classes ──
+
+describe('Override body classes', () => {
+  it('adds sb- classes for hash overrides', () => {
+    window.location.hash = '#theme=dark&sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-sidebar--collapsed')
+  })
+
+  it('removes stale classes when overrides are cleared', () => {
+    window.location.hash = '#theme=dark&sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+
+    window.location.hash = '#sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).not.toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-sidebar--collapsed')
+  })
+
+  it('removes all override classes when hash is empty', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+
+    window.location.hash = ''
+    syncOverrideClasses()
+    const overrideClasses = getSbClasses().filter((c) => !c.startsWith('sb-scene--'))
+    expect(overrideClasses).toEqual([])
+  })
+
+  it('sanitizes dot-notation keys (dots become dashes)', () => {
+    window.location.hash = '#settings.theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-settings-theme--dark')
+  })
+
+  it('sanitizes values with special characters', () => {
+    window.location.hash = '#mode=dark.dimmed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-mode--dark-dimmed')
+  })
+
+  it('skips overrides with empty values', () => {
+    window.location.hash = '#theme='
+    syncOverrideClasses()
+    const overrideClasses = getSbClasses().filter((c) => !c.startsWith('sb-scene--'))
+    expect(overrideClasses).toEqual([])
+  })
+
+  it('updates classes when override value changes', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+
+    window.location.hash = '#theme=light'
+    syncOverrideClasses()
+    expect(getSbClasses()).not.toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-theme--light')
+  })
+})
+
+// ── Non-override sb-* classes preserved ──
+
+describe('Non-override sb-* classes', () => {
+  it('does not strip sb-comment-mode during sync', () => {
+    document.body.classList.add('sb-comment-mode')
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    expect(document.body.classList.contains('sb-comment-mode')).toBe(true)
+    expect(getSbClasses()).toContain('sb-theme--dark')
+  })
+
+  it('does not strip sb-ff-* feature flag classes during sync', () => {
+    document.body.classList.add('sb-ff-dark-mode')
+    syncOverrideClasses()
+    expect(document.body.classList.contains('sb-ff-dark-mode')).toBe(true)
+  })
+
+  it('still removes stale override classes', () => {
+    document.body.classList.add('sb-comment-mode')
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    window.location.hash = ''
+    syncOverrideClasses()
+    expect(document.body.classList.contains('sb-comment-mode')).toBe(true)
+    expect(getSbClasses()).not.toContain('sb-theme--dark')
+  })
+})
+
+// ── Flow Classes ──
+
+describe('Flow body classes', () => {
+  it('sets sb-scene-- class', () => {
+    setFlowClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+
+  it('replaces previous flow class', () => {
+    setFlowClass('Dashboard')
+    setFlowClass('Settings')
+    expect(getSbClasses()).not.toContain('sb-scene--dashboard')
+    expect(getSbClasses()).toContain('sb-scene--settings')
+  })
+
+  it('removes flow class when called with empty string', () => {
+    setFlowClass('Dashboard')
+    setFlowClass('')
+    const flowClasses = getSbClasses().filter((c) => c.startsWith('sb-scene--'))
+    expect(flowClasses).toEqual([])
+  })
+
+  it('does not interfere with override classes', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    setFlowClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+})
+
+// ── setSceneClass (deprecated alias) ──
+
+describe('setSceneClass (deprecated alias)', () => {
+  it('is the same function as setFlowClass', () => {
+    expect(setSceneClass).toBe(setFlowClass)
+  })
+
+  it('sets sb-scene-- class', () => {
+    setSceneClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+})
+
+// ── Hide Mode ──
+
+describe('Hide mode body classes', () => {
+  it('reflects shadow overrides as body classes', () => {
+    activateHideMode()
+    setShadow('theme', 'dark')
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+  })
+})
+
+// ── installBodyClassSync ──
+
+describe('installBodyClassSync', () => {
+  it('runs initial sync on install', () => {
+    window.location.hash = '#layout=compact'
+    const unsub = installBodyClassSync()
+    expect(getSbClasses()).toContain('sb-layout--compact')
+    unsub()
+  })
+
+  it('returns an unsubscribe function', () => {
+    const unsub = installBodyClassSync()
+    expect(typeof unsub).toBe('function')
+    unsub()
+  })
+})