@dfosco/storyboard 0.5.0-alpha.0

package/src/core/workshop/features/registry.js

@@ -0,0 +1,28 @@
+/**
+ * Workshop feature registry.
+ *
+ * Maps feature names (matching keys in storyboard.config.json → workshop.features)
+ * to their module paths. The server plugin and client mount use this registry
+ * to dynamically load only the enabled features.
+ *
+ * To add a new feature:
+ * 1. Create a directory under features/ with index.js exporting the standard interface
+ * 2. Add its import here
+ */
+
+import * as createPrototype from './createPrototype/index.js'
+import * as createFlow from './createFlow/index.js'
+import * as createPage from './createPage/index.js'
+import * as createCanvas from './createCanvas/index.js'
+import * as createStory from './createStory/index.js'
+
+/**
+ * All available workshop features, keyed by config name.
+ */
+export const features = {
+  createPrototype,
+  createFlow,
+  createPage,
+  createCanvas,
+  createStory,
+}

package/src/core/workshop/features/templateIndex.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { parse as parseJsonc } from 'jsonc-parser'
+
+const TEMPLATE_DIR_NAMES = new Set(['template', 'templates'])
+const RECIPE_DIR_NAMES = new Set(['recipe', 'recipes'])
+const PARTIAL_DIR_NAMES = new Set([...TEMPLATE_DIR_NAMES, ...RECIPE_DIR_NAMES])
+
+function normalizeSlashes(value) {
+  return value.replaceAll('\\', '/')
+}
+
+function isExternalPrototype(prototypePath) {
+  try {
+    const raw = fs.readFileSync(prototypePath, 'utf-8')
+    const parsed = parseJsonc(raw)
+    return typeof parsed?.url === 'string' && parsed.url.trim().length > 0
+  } catch {
+    return false
+  }
+}
+
+function isPartialDirName(directory) {
+  return PARTIAL_DIR_NAMES.has(directory)
+}
+
+function toPartialKind(directory) {
+  if (TEMPLATE_DIR_NAMES.has(directory)) return 'template'
+  if (RECIPE_DIR_NAMES.has(directory)) return 'recipe'
+  return null
+}
+
+function listPrototypeDirs(root) {
+  const prototypesDir = path.join(root, 'src', 'prototypes')
+  if (!fs.existsSync(prototypesDir)) return []
+
+  const results = []
+
+  function scanDir(dir, folder) {
+    if (!fs.existsSync(dir)) return
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (entry.name.endsWith('.folder')) {
+        scanDir(path.join(dir, entry.name), entry.name.replace(/\.folder$/, ''))
+        continue
+      }
+
+      const protoDir = path.join(dir, entry.name)
+      const prototypeFile = fs.readdirSync(protoDir).find((f) => f.endsWith('.prototype.json'))
+      if (!prototypeFile) continue
+      if (isExternalPrototype(path.join(protoDir, prototypeFile))) continue
+
+      results.push({
+        name: entry.name,
+        folder,
+        dir: protoDir,
+      })
+    }
+  }
+
+  scanDir(prototypesDir)
+  return results
+}
+
+function makeId(prefix, directory, name, prototype, folder) {
+  if (prefix === 'global') {
+    return `global:${directory}/${name}`
+  }
+  const folderPart = folder ? `${folder}/` : ''
+  return `prototype:${folderPart}${prototype}:${directory}/${name}`
+}
+
+export function buildTemplateRecipeIndex(root, configPartials = []) {
+  const srcRoot = path.join(root, 'src')
+  const results = []
+  const seenIds = new Set()
+
+  for (const partial of configPartials) {
+    if (!partial || !isPartialDirName(partial.directory) || !partial.name) continue
+    const kind = toPartialKind(partial.directory)
+    if (!kind) continue
+    const id = makeId('global', partial.directory, partial.name)
+    if (seenIds.has(id)) continue
+    seenIds.add(id)
+    results.push({
+      id,
+      name: partial.name,
+      directory: partial.directory,
+      kind,
+      scope: 'global',
+      baseDir: partial.directory,
+      globals: Array.isArray(partial.globals) ? partial.globals : undefined,
+    })
+  }
+
+  const prototypes = listPrototypeDirs(root)
+  for (const proto of prototypes) {
+    for (const directory of PARTIAL_DIR_NAMES) {
+      const localPartialsDir = path.join(proto.dir, directory)
+      if (!fs.existsSync(localPartialsDir)) continue
+
+      for (const entry of fs.readdirSync(localPartialsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue
+        const kind = toPartialKind(directory)
+        if (!kind) continue
+
+        const baseDir = normalizeSlashes(path.relative(srcRoot, localPartialsDir))
+        const id = makeId('prototype', directory, entry.name, proto.name, proto.folder)
+        if (seenIds.has(id)) continue
+        seenIds.add(id)
+        results.push({
+          id,
+          name: entry.name,
+          directory,
+          kind,
+          scope: 'prototype',
+          prototype: proto.name,
+          ...(proto.folder ? { folder: proto.folder } : {}),
+          baseDir,
+        })
+      }
+    }
+  }
+
+  return results.sort((a, b) => {
+    if (a.scope !== b.scope) return a.scope.localeCompare(b.scope)
+    if ((a.prototype || '') !== (b.prototype || '')) return (a.prototype || '').localeCompare(b.prototype || '')
+    if ((a.folder || '') !== (b.folder || '')) return (a.folder || '').localeCompare(b.folder || '')
+    if (a.kind !== b.kind) return a.kind.localeCompare(b.kind)
+    return a.name.localeCompare(b.name)
+  })
+}
+
+export function resolveTemplateRecipeEntry(entries, templateValue, { prototype, folder } = {}) {
+  if (!templateValue || typeof templateValue !== 'string') return null
+
+  const trimmed = templateValue.trim()
+  if (!trimmed) return null
+
+  const byId = entries.find((entry) => entry.id === trimmed)
+  if (byId) return byId
+
+  const exactScoped = entries.find((entry) =>
+    entry.scope === 'prototype' &&
+    entry.name === trimmed &&
+    entry.prototype === prototype &&
+    (entry.folder || '') === (folder || '')
+  )
+  if (exactScoped) return exactScoped
+
+  const globalMatch = entries.find((entry) => entry.scope === 'global' && entry.name === trimmed)
+  if (globalMatch) return globalMatch
+
+  return entries.find((entry) => entry.name === trimmed) || null
+}

package/src/core/workshop/ui/WorkshopPanel.jsx

@@ -0,0 +1,98 @@
+import { useState, useMemo, useEffect, useCallback } from 'react'
+
+export default function WorkshopPanel({ features = [] }) {
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [activeOverlay, setActiveOverlay] = useState(null)
+  const [visible, setVisible] = useState(true)
+
+  const activeFeature = useMemo(
+    () => (activeOverlay ? features.find((f) => f.overlayId === activeOverlay) ?? null : null),
+    [activeOverlay, features]
+  )
+
+  const showOverlay = useCallback((id) => {
+    setActiveOverlay(id)
+    setMenuOpen(false)
+  }, [])
+
+  const closeOverlay = useCallback(() => setActiveOverlay(null), [])
+
+  const handleKeydown = useCallback(
+    (e) => {
+      if (e.key === '.' && (e.metaKey || e.ctrlKey)) {
+        setVisible((v) => !v)
+        return
+      }
+      if (e.key === 'Escape') {
+        setActiveOverlay((cur) => {
+          if (cur) return null
+          setMenuOpen(false)
+          return cur
+        })
+      }
+    },
+    []
+  )
+
+  const handleClickOutside = useCallback((e) => {
+    if (!e.target.closest('[data-workshop-panel]')) {
+      setMenuOpen(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    window.addEventListener('keydown', handleKeydown)
+    document.addEventListener('click', handleClickOutside)
+    return () => {
+      window.removeEventListener('keydown', handleKeydown)
+      document.removeEventListener('click', handleClickOutside)
+    }
+  }, [handleKeydown, handleClickOutside])
+
+  if (!visible) return null
+
+  const ActiveOverlay = activeFeature?.overlay
+
+  return (
+    <div data-workshop-panel className="fixed bottom-6 right-[76px] z-[9999] font-sans">
+      <button
+        className="flex items-center p-3 bg-popover text-muted-foreground border border-border rounded-full cursor-pointer shadow-lg hover:scale-105 active:scale-95 transition-transform select-none"
+        aria-label="Workshop"
+        onClick={() => setMenuOpen((o) => !o)}
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" fill="currentColor">
+          <path d="M5.433 2.304A4.494 4.494 0 0 0 3.5 6c0 1.598.832 3.002 2.09 3.802.518.328.929.923.902 1.64v.008l-.164 3.337a.75.75 0 1 1-1.498-.073l.163-3.34c.007-.14-.1-.313-.36-.465A5.986 5.986 0 0 1 2 6a5.994 5.994 0 0 1 2.567-4.92 1.482 1.482 0 0 1 1.673-.04c.462.296.76.827.76 1.423v2.076c0 .332.214.572.491.572.268 0 .492-.24.492-.572V2.463c0-.596.298-1.127.76-1.423a1.482 1.482 0 0 1 1.673.04A5.994 5.994 0 0 1 13 6a5.986 5.986 0 0 1-2.633 4.909c-.26.152-.367.325-.36.465l.164 3.34a.75.75 0 1 1-1.498.073l-.164-3.337v-.008c-.027-.717.384-1.312.902-1.64A4.494 4.494 0 0 0 11.5 6a4.494 4.494 0 0 0-1.933-3.696c-.024.017-.067.067-.067.159v2.076c0 1.074-.84 2.072-1.991 2.072-1.161 0-2.009-.998-2.009-2.072V2.463c0-.092-.043-.142-.067-.16Z" />
+        </svg>
+      </button>
+
+      {menuOpen && (
+        <div className="absolute bottom-14 right-0 min-w-[200px] bg-popover text-popover-foreground border border-border rounded-xl shadow-lg overflow-hidden">
+          <div className="px-4 pt-2 pb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">Workshop</div>
+          <div className="h-px bg-border" />
+          {features.map((f) => (
+            <button
+              key={f.overlayId}
+              className="flex items-center gap-2 w-full px-4 py-2 text-sm bg-transparent border-none cursor-pointer text-left hover:bg-accent transition-colors"
+              onClick={() => showOverlay(f.overlayId)}
+            >
+              <span className="text-sm">{f.icon || ''}</span> {f.label}
+            </button>
+          ))}
+          <div className="h-px bg-border" />
+          <div className="px-4 py-1.5 text-[11px] text-muted-foreground">Dev-only tools</div>
+        </div>
+      )}
+
+      {ActiveOverlay && (
+        <div
+          className="fixed inset-0 z-[10000] flex items-center justify-center bg-black/50"
+          onClick={(e) => { if (e.target === e.currentTarget) closeOverlay() }}
+        >
+          <div className="w-full max-w-[480px]">
+            <ActiveOverlay onClose={closeOverlay} />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/core/workshop/ui/mount.ts

@@ -0,0 +1,6 @@
+/**
+ * Workshop panel mount — stub (Svelte UI removed).
+ */
+
+export function mountWorkshopPanel() {}
+export function unmountWorkshopPanel() {}

package/src/core/worktree/port.js

@@ -0,0 +1,268 @@
+/**
+ * Worktree Port Registry
+ *
+ * Manages a JSON registry (worktrees/ports.json) that maps worktree names
+ * to unique dev-server ports. Main always gets 1234; worktrees get 1235+.
+ *
+ * This module is published as part of @dfosco/storyboard-core so client
+ * repos can use port detection without duplicating the logic.
+ *
+ * Programmatic API:
+ *   import { getPort, detectWorktreeName, resolvePort } from '@dfosco/storyboard/worktree/port'
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, realpathSync } from 'fs'
+import { join, dirname, basename } from 'path'
+import { execSync } from 'child_process'
+import { findByWorktree } from './serverRegistry.js'
+
+const BASE_PORT = 1234
+
+/**
+ * Resolve the path to worktrees/ports.json.
+ *
+ * Derives the repo root from directory structure so it works whether
+ * running from the repo root or from inside worktrees/<name>/ — even
+ * when ports.json does not exist yet.
+ *
+ * @param {string} [cwd] — override working directory
+ * @returns {string} absolute path to ports.json
+ */
+export function portsFilePath(cwd = process.cwd()) {
+  const realCwd = realpathSync(cwd)
+
+  // Check if we're inside worktrees/<name>/
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
+  if (worktreeMatch) {
+    return join(worktreeMatch[1], 'worktrees', 'ports.json')
+  }
+
+  // We're at the repo root (or somewhere else) — default location
+  return join(realCwd, 'worktrees', 'ports.json')
+}
+
+/**
+ * Detect the worktree name from the current git context.
+ *
+ * Returns 'main' when not inside a worktrees/<name>/ directory.
+ */
+export function detectWorktreeName() {
+  try {
+    const topLevel = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim()
+    const realTop = realpathSync(topLevel)
+
+    // Check if we're inside a worktrees/<name> directory
+    if (realTop.includes('worktrees/') || realTop.includes('worktrees\\')) {
+      return basename(realTop)
+    }
+
+    // Also check the cwd pattern
+    const realCwd = realpathSync(process.cwd())
+    const worktreeMatch = realCwd.match(/worktrees[/\\]([^/\\]+)/)
+    if (worktreeMatch) return worktreeMatch[1]
+
+    // Not a worktree — check the current branch name
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim()
+    if (branch && branch !== 'main' && branch !== 'master') return branch
+
+    return 'main'
+  } catch {
+    return 'main'
+  }
+}
+
+/**
+ * Check if a port is in use by another process (synchronous, best-effort via lsof).
+ * Skipped when NODE_ENV=test to avoid test flakiness from real port state.
+ * @param {number} port
+ * @returns {boolean}
+ */
+function isPortInUse(port) {
+  if (process.env.NODE_ENV === 'test') return false
+  try {
+    execSync(`lsof -i :${port} -sTCP:LISTEN`, { stdio: 'ignore', timeout: 2000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Get or assign a port for the given worktree name.
+ *
+ * Creates worktrees/ports.json if it doesn't exist. Assigns ports
+ * starting at BASE_PORT+1 (1235) for non-main worktrees.
+ * If the previously assigned port was stolen by another process,
+ * reassigns to the next available port.
+ *
+ * @param {string} worktreeName
+ * @returns {number}
+ */
+export function getPort(worktreeName) {
+  const portsFile = portsFilePath()
+  const dir = dirname(portsFile)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  let ports = { main: BASE_PORT }
+  if (existsSync(portsFile)) {
+    try {
+      ports = JSON.parse(readFileSync(portsFile, 'utf8'))
+    } catch {
+      // Corrupted file — start fresh
+    }
+  }
+
+  if (worktreeName === 'main') return ports.main || BASE_PORT
+
+  // If port already assigned, verify it's not stolen by another process
+  if (ports[worktreeName]) {
+    if (!isPortInUse(ports[worktreeName])) {
+      return ports[worktreeName]
+    }
+    // Port is occupied — fall through to reassign
+  }
+
+  const usedPorts = Object.values(ports)
+  let nextPort = BASE_PORT + 1
+  while (usedPorts.includes(nextPort)) nextPort++
+  ports[worktreeName] = nextPort
+  writeFileSync(portsFile, JSON.stringify(ports, null, 2) + '\n')
+
+  return ports[worktreeName]
+}
+
+/**
+ * Release a port assignment for a worktree.
+ *
+ * Removes the entry from ports.json so the port can be reused.
+ * Never removes 'main'.
+ *
+ * @param {string} worktreeName
+ */
+export function releasePort(worktreeName) {
+  if (worktreeName === 'main') return
+
+  const portsFile = portsFilePath()
+  if (!existsSync(portsFile)) return
+
+  try {
+    const ports = JSON.parse(readFileSync(portsFile, 'utf8'))
+    if (!(worktreeName in ports)) return
+    delete ports[worktreeName]
+    writeFileSync(portsFile, JSON.stringify(ports, null, 2) + '\n')
+  } catch { /* ignore corrupt file */ }
+}
+
+/**
+ * Resolve the port for a running dev server.
+ *
+ * Checks the server registry (servers.json) first for a live process,
+ * then falls back to ports.json assignment. Use this when connecting
+ * to an already-running server — it returns the real bound port even
+ * when Vite rebinds to a different port than originally assigned.
+ *
+ * @param {string} worktreeName
+ * @returns {number}
+ */
+export function resolveRunningPort(worktreeName) {
+  try {
+    const servers = findByWorktree(worktreeName)
+    if (servers.length > 0) {
+      const latest = servers.reduce((a, b) =>
+        (a.startedAt || '') >= (b.startedAt || '') ? a : b
+      )
+      return latest.port
+    }
+  } catch { /* registry unavailable */ }
+
+  return resolvePort(worktreeName)
+}
+
+/**
+ * Resolve the port for a worktree from worktrees/ports.json
+ * without assigning a new one if missing.
+ *
+ * @param {string} worktreeName
+ * @returns {number}
+ */
+export function resolvePort(worktreeName) {
+  const portsFile = portsFilePath()
+  if (!existsSync(portsFile)) return BASE_PORT
+
+  try {
+    const ports = JSON.parse(readFileSync(portsFile, 'utf8'))
+    return ports[worktreeName] ?? BASE_PORT
+  } catch {
+    return BASE_PORT
+  }
+}
+
+/**
+ * Slugify a branch name for filesystem and subdomain safety.
+ *
+ * - lowercase
+ * - dots, spaces, underscores, non-alphanumeric (except - and /) → hyphens
+ * - collapse consecutive hyphens
+ * - trim leading/trailing hyphens per segment
+ */
+export function slugify(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9/-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .split('/')
+    .map((s) => s.replace(/^-+|-+$/g, ''))
+    .join('/')
+}
+
+/**
+ * Resolve the repo root — the directory that contains `worktrees/`.
+ *
+ * Works whether cwd is the repo root itself or inside `worktrees/<name>/`.
+ *
+ * @param {string} [cwd]
+ * @returns {string} absolute path to repo root
+ */
+export function repoRoot(cwd = process.cwd()) {
+  const realCwd = realpathSync(cwd)
+
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
+  if (worktreeMatch) return worktreeMatch[1]
+
+  return realCwd
+}
+
+/**
+ * Resolve the full path to a worktree directory.
+ *
+ * Returns repo root for 'main', `worktrees/<name>` otherwise.
+ *
+ * @param {string} name — worktree name
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function worktreeDir(name, cwd) {
+  const root = repoRoot(cwd)
+  if (name === 'main') return root
+  return join(root, 'worktrees', name)
+}
+
+/**
+ * List existing worktree directory names from `worktrees/`.
+ *
+ * Only returns directories that look like real worktrees (contain a `.git` file).
+ * Does not include 'main'.
+ *
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+export function listWorktrees(cwd) {
+  const root = repoRoot(cwd)
+  const worktreesDir = join(root, 'worktrees')
+
+  if (!existsSync(worktreesDir)) return []
+
+  return readdirSync(worktreesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(worktreesDir, d.name, '.git')))
+    .map((d) => d.name)
+}