@dfosco/storyboard 0.7.1 → 0.9.0

package/src/core/rename-watcher/watcher.test.js

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { execFileSync } from 'node:child_process'
+import { __test } from './watcher.js'
+
+const { detectDraftsFlips, processChange, scanDirectory } = __test
+
+const TEST_CONFIG = {
+  watch: [
+    { path: 'src/prototypes', extensions: ['.jsx', '.tsx', '.mdx'], type: 'prototype' },
+    { path: 'src/canvas', extensions: ['.canvas.jsonl'], type: 'canvas' },
+  ],
+  exclude: {
+    filePrefixes: ['_'],
+    directories: ['node_modules', '.git', 'dist', 'images', '.worktrees'],
+  },
+  debounceMs: 0,
+  autocommit: { enabled: false, prefix: '[test-autofix]' },
+}
+
+/**
+ * Initialise a tmp dir as a git repo so the watcher's `git add`/`git rm`
+ * autocommit path doesn't blow up. We disable autocommit by default in
+ * tests via the config override; this is just defensive.
+ */
+function makeRepoRoot() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'sb-watcher-test-'))
+  fs.mkdirSync(path.join(root, 'src', 'canvas'), { recursive: true })
+  fs.mkdirSync(path.join(root, 'src', 'prototypes'), { recursive: true })
+  fs.mkdirSync(path.join(root, 'assets', 'canvas', 'images'), { recursive: true })
+  // Init git so autocommit can run if needed
+  try {
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: root, stdio: 'pipe' })
+    execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: root })
+    execFileSync('git', ['config', 'user.name', 'Test'], { cwd: root })
+    execFileSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: root })
+  } catch { /* git may be missing in CI sandbox — flips work without */ }
+  return root
+}
+
+function writeCanvasFile(absPath, widgets) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true })
+  const events = [
+    { event: 'canvas_created', timestamp: '2026-01-01T00:00:00Z', title: 'X', widgets: [] },
+  ]
+  if (widgets && widgets.length > 0) {
+    events.push({ event: 'widgets_replaced', timestamp: '2026-01-01T00:00:01Z', widgets })
+  }
+  fs.writeFileSync(absPath, events.map((e) => JSON.stringify(e)).join('\n') + '\n')
+}
+
+function imageWidget(id, src) {
+  return { id, type: 'image', props: { src, width: 100, height: 100 }, position: { x: 0, y: 0 } }
+}
+
+describe('rename-watcher: detectDraftsFlips', () => {
+  it('detects a top-level canvas moving into drafts/', () => {
+    const oldSet = new Set(['foo.canvas.jsonl'])
+    const newSet = new Set(['drafts/foo.canvas.jsonl'])
+    const flips = detectDraftsFlips(oldSet, newSet)
+    expect(flips).toHaveLength(1)
+    expect(flips[0]).toMatchObject({
+      oldPath: 'foo.canvas.jsonl',
+      newPath: 'drafts/foo.canvas.jsonl',
+      oldDraft: false,
+      newDraft: true,
+    })
+  })
+
+  it('detects a drafts canvas moving back out to top-level', () => {
+    const oldSet = new Set(['drafts/foo.canvas.jsonl'])
+    const newSet = new Set(['foo.canvas.jsonl'])
+    const flips = detectDraftsFlips(oldSet, newSet)
+    expect(flips).toHaveLength(1)
+    expect(flips[0].oldDraft).toBe(true)
+    expect(flips[0].newDraft).toBe(false)
+  })
+
+  it('detects flips inside a subdirectory (widget/drafts/v6 ↔ widget/v6)', () => {
+    const oldSet = new Set(['widget/v6.canvas.jsonl'])
+    const newSet = new Set(['widget/drafts/v6.canvas.jsonl'])
+    const flips = detectDraftsFlips(oldSet, newSet)
+    expect(flips).toHaveLength(1)
+    expect(flips[0].newDraft).toBe(true)
+  })
+
+  it('returns nothing when the move is purely a rename (no draft change)', () => {
+    const oldSet = new Set(['foo.canvas.jsonl'])
+    const newSet = new Set(['bar.canvas.jsonl'])
+    expect(detectDraftsFlips(oldSet, newSet)).toEqual([])
+  })
+
+  it('returns nothing when both sides are inside drafts/', () => {
+    const oldSet = new Set(['drafts/foo.canvas.jsonl'])
+    const newSet = new Set(['drafts/bar.canvas.jsonl'])
+    expect(detectDraftsFlips(oldSet, newSet)).toEqual([])
+  })
+
+  it('skips ambiguous flips (multiple files with the same stripped path)', () => {
+    const oldSet = new Set(['foo.canvas.jsonl', 'drafts/foo.canvas.jsonl'])
+    const newSet = new Set(['drafts/foo.canvas.jsonl', 'foo.canvas.jsonl'])
+    // No actual changes here, but even if there were, multi-match would skip.
+    expect(detectDraftsFlips(oldSet, newSet)).toEqual([])
+  })
+
+  it('ignores non-canvas files', () => {
+    const oldSet = new Set(['foo.jsx', 'bar.md'])
+    const newSet = new Set(['drafts/foo.jsx', 'drafts/bar.md'])
+    expect(detectDraftsFlips(oldSet, newSet)).toEqual([])
+  })
+})
+
+describe('rename-watcher: drafts-flip image movement (end-to-end via processChange)', () => {
+  let root
+  let config
+
+  beforeEach(() => {
+    root = makeRepoRoot()
+    config = TEST_CONFIG
+  })
+
+  afterEach(() => {
+    try { fs.rmSync(root, { recursive: true, force: true }) } catch { /* */ }
+  })
+
+  it('moves a public image into images/drafts/ when its canvas moves into drafts', () => {
+    const canvasAbs = path.join(root, 'src', 'canvas', 'foo.canvas.jsonl')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.writeFileSync(path.join(imagesDir, 'pic.png'), Buffer.from([1, 2, 3]))
+    writeCanvasFile(canvasAbs, [imageWidget('img-1', 'pic.png')])
+
+    // Seed snapshots, then move the canvas into drafts.
+    const snapshots = new Map()
+    for (const entry of config.watch) snapshots.set(entry.path, scanDirectory(root, entry, config))
+
+    const draftAbs = path.join(root, 'src', 'canvas', 'drafts', 'foo.canvas.jsonl')
+    fs.mkdirSync(path.dirname(draftAbs), { recursive: true })
+    fs.renameSync(canvasAbs, draftAbs)
+
+    processChange(root, snapshots, config)
+
+    expect(fs.existsSync(path.join(imagesDir, 'pic.png'))).toBe(false)
+    expect(fs.existsSync(path.join(imagesDir, 'drafts', 'pic.png'))).toBe(true)
+
+    // Canvas file should have a widgets_replaced event with the new src
+    const text = fs.readFileSync(draftAbs, 'utf-8')
+    expect(text).toContain('"src":"drafts/pic.png"')
+  })
+
+  it('moves a drafts image back to images/ when its canvas moves out of drafts', () => {
+    const draftAbs = path.join(root, 'src', 'canvas', 'drafts', 'foo.canvas.jsonl')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.mkdirSync(path.join(imagesDir, 'drafts'), { recursive: true })
+    fs.writeFileSync(path.join(imagesDir, 'drafts', 'pic.png'), Buffer.from([1, 2, 3]))
+    writeCanvasFile(draftAbs, [imageWidget('img-1', 'drafts/pic.png')])
+
+    const snapshots = new Map()
+    for (const entry of config.watch) snapshots.set(entry.path, scanDirectory(root, entry, config))
+
+    const canvasAbs = path.join(root, 'src', 'canvas', 'foo.canvas.jsonl')
+    fs.renameSync(draftAbs, canvasAbs)
+
+    processChange(root, snapshots, config)
+
+    expect(fs.existsSync(path.join(imagesDir, 'drafts', 'pic.png'))).toBe(false)
+    expect(fs.existsSync(path.join(imagesDir, 'pic.png'))).toBe(true)
+
+    const text = fs.readFileSync(canvasAbs, 'utf-8')
+    // The new src is the bare basename (no drafts/ prefix)
+    expect(text).toMatch(/"src":"pic\.png"/)
+  })
+
+  it('copies (not renames) a shared image when another canvas still references it', () => {
+    const movedCanvas = path.join(root, 'src', 'canvas', 'foo.canvas.jsonl')
+    const otherCanvas = path.join(root, 'src', 'canvas', 'other.canvas.jsonl')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.writeFileSync(path.join(imagesDir, 'shared.png'), Buffer.from([9]))
+    writeCanvasFile(movedCanvas, [imageWidget('a', 'shared.png')])
+    writeCanvasFile(otherCanvas, [imageWidget('b', 'shared.png')])
+
+    const snapshots = new Map()
+    for (const entry of config.watch) snapshots.set(entry.path, scanDirectory(root, entry, config))
+
+    const draftAbs = path.join(root, 'src', 'canvas', 'drafts', 'foo.canvas.jsonl')
+    fs.mkdirSync(path.dirname(draftAbs), { recursive: true })
+    fs.renameSync(movedCanvas, draftAbs)
+
+    processChange(root, snapshots, config)
+
+    // Source preserved (other canvas still owns it)
+    expect(fs.existsSync(path.join(imagesDir, 'shared.png'))).toBe(true)
+    // Copied into drafts dir for the flipping canvas
+    expect(fs.existsSync(path.join(imagesDir, 'drafts', 'shared.png'))).toBe(true)
+    // Only the flipping canvas's widget src updated
+    const flippedText = fs.readFileSync(draftAbs, 'utf-8')
+    expect(flippedText).toContain('"src":"drafts/shared.png"')
+    const otherText = fs.readFileSync(otherCanvas, 'utf-8')
+    expect(otherText).toContain('"src":"shared.png"')
+    expect(otherText).not.toContain('"src":"drafts/shared.png"')
+  })
+
+  it('picks a unique basename when the target directory already has the same name', () => {
+    const movedCanvas = path.join(root, 'src', 'canvas', 'foo.canvas.jsonl')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.writeFileSync(path.join(imagesDir, 'pic.png'), Buffer.from([1]))
+    // Pre-existing collision in target dir
+    fs.mkdirSync(path.join(imagesDir, 'drafts'), { recursive: true })
+    fs.writeFileSync(path.join(imagesDir, 'drafts', 'pic.png'), Buffer.from([2]))
+    writeCanvasFile(movedCanvas, [imageWidget('a', 'pic.png')])
+
+    const snapshots = new Map()
+    for (const entry of config.watch) snapshots.set(entry.path, scanDirectory(root, entry, config))
+
+    const draftAbs = path.join(root, 'src', 'canvas', 'drafts', 'foo.canvas.jsonl')
+    fs.mkdirSync(path.dirname(draftAbs), { recursive: true })
+    fs.renameSync(movedCanvas, draftAbs)
+
+    processChange(root, snapshots, config)
+
+    expect(fs.existsSync(path.join(imagesDir, 'drafts', 'pic-2.png'))).toBe(true)
+    // Original pic.png in drafts/ untouched (different content from pre-existing file)
+    expect(fs.readFileSync(path.join(imagesDir, 'drafts', 'pic.png'))).toEqual(Buffer.from([2]))
+
+    const flippedText = fs.readFileSync(draftAbs, 'utf-8')
+    expect(flippedText).toContain('"src":"drafts/pic-2.png"')
+  })
+
+  it('is a no-op for widgets whose images are already in the correct directory', () => {
+    const canvasAbs = path.join(root, 'src', 'canvas', 'foo.canvas.jsonl')
+    const imagesDir = path.join(root, 'assets', 'canvas', 'images')
+    fs.mkdirSync(path.join(imagesDir, 'drafts'), { recursive: true })
+    // Image lives in drafts/ even though the (about-to-move-in) canvas is public
+    fs.writeFileSync(path.join(imagesDir, 'drafts', 'already.png'), Buffer.from([1]))
+    writeCanvasFile(canvasAbs, [imageWidget('a', 'drafts/already.png')])
+
+    const snapshots = new Map()
+    for (const entry of config.watch) snapshots.set(entry.path, scanDirectory(root, entry, config))
+
+    const draftAbs = path.join(root, 'src', 'canvas', 'drafts', 'foo.canvas.jsonl')
+    fs.mkdirSync(path.dirname(draftAbs), { recursive: true })
+    fs.renameSync(canvasAbs, draftAbs)
+
+    processChange(root, snapshots, config)
+
+    // File didn't move, no new widgets_replaced event with a different src
+    expect(fs.existsSync(path.join(imagesDir, 'drafts', 'already.png'))).toBe(true)
+    const text = fs.readFileSync(draftAbs, 'utf-8')
+    // Original src is preserved
+    expect(text).toContain('"src":"drafts/already.png"')
+  })
+})

package/src/core/scaffold/fragments.js

@@ -0,0 +1,287 @@
+/**
+ * Scaffold fragment templating — comment-style-agnostic block markers used by
+ * `storyboard-scaffold` to keep slices of client-owned files in sync with the
+ * library.
+ *
+ * Two marker schemes:
+ *
+ *   Client-side ("namespaced"):
+ *     # <!-- storyboard:<source-path>:<fragment-id> --start-->
+ *     ...content the scaffolder rewrites...
+ *     # <!-- storyboard:<source-path>:<fragment-id> --end-->
+ *
+ *     The leading `#` (or `//`, or whatever comment prefix the host file uses)
+ *     is ignored by the parser — we match on the `storyboard:` namespace
+ *     substring only, so the same scheme works in .gitignore, .yml, .json,
+ *     .js, .md, etc.
+ *
+ *   Library-side ("bare"):
+ *     # <!-- <fragment-id> --start-->
+ *     ...fragment body...
+ *     # <!-- <fragment-id> --end-->
+ *
+ *     Bare markers live in `packages/storyboard/scaffold/<source-path>`. The
+ *     scaffolder reads them via `extractFragment()`. When a library file is
+ *     copied wholesale into a client (no client-side markers present), the
+ *     scaffolder strips the bare markers first via `stripLibraryMarkers()`
+ *     so the client gets clean content.
+ *
+ * Whitespace rules:
+ *   - Fragment body = the bytes BETWEEN the start-marker line and the
+ *     end-marker line, exclusive of both. Leading/trailing newlines on the
+ *     body are preserved exactly so round-trips are stable.
+ *   - The comment prefix on the start line is repeated on the end line by
+ *     convention but not enforced — the parser only requires that both
+ *     markers appear on their own line.
+ *
+ * Failure modes (all throw):
+ *   - Nested markers with the same id.
+ *   - Unbalanced markers (start without end, or vice versa).
+ *   - Unknown source path or fragment id during apply.
+ */
+
+const NAMESPACE = 'storyboard'
+
+// Captures `storyboard:<src>:<id> --start` or `--end` inside an HTML comment.
+// The wrapping comment chars (`#`, `//`, etc.) AROUND the `<!--` are matched
+// loosely — we only require the `<!--` HTML-comment open/close brackets and
+// the `storyboard:` namespace substring.
+const NAMESPACED_MARKER_RE = new RegExp(
+  `<!--\\s*${NAMESPACE}:([^\\s:]+):([A-Za-z0-9][A-Za-z0-9-]*)\\s+--(start|end)\\s*-->`
+)
+
+// Library-side bare markers: `<!-- <id> --start-->` or `<!-- <id> --end-->`.
+// `<!--` and `-->` are required so we don't accidentally match prose comments.
+const BARE_MARKER_RE = /<!--\s*([A-Za-z0-9][A-Za-z0-9-]*)\s+--(start|end)\s*-->/
+
+/**
+ * @typedef {object} NamespacedFragment
+ * @property {string} sourcePath  - e.g. "scaffold/gitignore"
+ * @property {string} id          - e.g. "runtime-state"
+ * @property {number} startLine   - 0-indexed line number of the start marker
+ * @property {number} endLine     - 0-indexed line number of the end marker
+ * @property {string} body        - content between markers (exclusive)
+ */
+
+/**
+ * Parse a client-side file for `storyboard:<src>:<id>` fragment markers.
+ *
+ * @param {string} text
+ * @returns {NamespacedFragment[]}
+ * @throws if markers are nested, unbalanced, or duplicated.
+ */
+export function parseFragments(text) {
+  const lines = splitLinesKeepingEol(text)
+  const fragments = []
+  const open = new Map() // key=`${src}:${id}` → { sourcePath, id, startLine }
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(NAMESPACED_MARKER_RE)
+    if (!m) continue
+    const [, sourcePath, id, side] = m
+    const key = `${sourcePath}:${id}`
+
+    if (side === 'start') {
+      if (open.has(key)) {
+        throw new Error(
+          `Duplicate or nested storyboard:${key} --start-- marker at line ${i + 1}`
+        )
+      }
+      open.set(key, { sourcePath, id, startLine: i })
+    } else {
+      const opened = open.get(key)
+      if (!opened) {
+        throw new Error(
+          `Stray storyboard:${key} --end-- marker at line ${i + 1} with no matching --start--`
+        )
+      }
+      const bodyLines = lines.slice(opened.startLine + 1, i)
+      fragments.push({
+        sourcePath: opened.sourcePath,
+        id: opened.id,
+        startLine: opened.startLine,
+        endLine: i,
+        body: bodyLines.join(''),
+      })
+      open.delete(key)
+    }
+  }
+
+  if (open.size > 0) {
+    const first = [...open.values()][0]
+    throw new Error(
+      `Unclosed storyboard:${first.sourcePath}:${first.id} fragment (start at line ${first.startLine + 1})`
+    )
+  }
+
+  return fragments
+}
+
+/**
+ * Extract a bare-marker fragment body from a library source file.
+ *
+ * @param {string} srcText
+ * @param {string} id
+ * @returns {string|null} the fragment body (between markers, exclusive), or
+ *   null if no matching fragment exists.
+ * @throws if markers are nested, unbalanced, or duplicated for the same id.
+ */
+export function extractFragment(srcText, id) {
+  const lines = splitLinesKeepingEol(srcText)
+  let startLine = -1
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(BARE_MARKER_RE)
+    if (!m || m[1] !== id) continue
+    const side = m[2]
+    if (side === 'start') {
+      if (startLine !== -1) {
+        throw new Error(`Duplicate --start-- marker for fragment "${id}" at line ${i + 1}`)
+      }
+      startLine = i
+    } else {
+      if (startLine === -1) {
+        throw new Error(`Stray --end-- marker for fragment "${id}" at line ${i + 1}`)
+      }
+      const bodyLines = lines.slice(startLine + 1, i)
+      return bodyLines.join('')
+    }
+  }
+
+  if (startLine !== -1) {
+    throw new Error(`Unclosed --start-- marker for fragment "${id}" at line ${startLine + 1}`)
+  }
+  return null
+}
+
+/**
+ * Rewrite the bodies of every `storyboard:<src>:<id>` fragment in a client
+ * file by looking up the matching library fragment via `lookup(src, id)`.
+ *
+ * The lookup callback is responsible for resolving the source file and
+ * extracting the fragment body — typically:
+ *
+ *   (src, id) => extractFragment(fs.readFileSync(src, 'utf-8'), id)
+ *
+ * Returns `{ text, replaced, unchanged }` so the caller can report counts and
+ * skip writes when nothing changed.
+ *
+ * @param {string} clientText
+ * @param {(sourcePath: string, fragmentId: string) => string|null} lookup
+ * @returns {{ text: string, replaced: number, unchanged: number }}
+ * @throws if a fragment marker references a source/id the lookup can't resolve.
+ */
+export function applyFragments(clientText, lookup) {
+  const fragments = parseFragments(clientText)
+  if (fragments.length === 0) {
+    return { text: clientText, replaced: 0, unchanged: 0 }
+  }
+
+  const lines = splitLinesKeepingEol(clientText)
+  let replaced = 0
+  let unchanged = 0
+
+  // Walk fragments in reverse so earlier indices don't shift after splicing.
+  for (let i = fragments.length - 1; i >= 0; i--) {
+    const frag = fragments[i]
+    const newBody = lookup(frag.sourcePath, frag.id)
+    if (newBody == null) {
+      throw new Error(
+        `No fragment "${frag.id}" found in ${frag.sourcePath} (referenced from client line ${frag.startLine + 1})`
+      )
+    }
+
+    const newBodyLines = splitLinesKeepingEol(newBody)
+    const oldBody = lines.slice(frag.startLine + 1, frag.endLine).join('')
+    if (oldBody === newBody) {
+      unchanged++
+      continue
+    }
+
+    lines.splice(frag.startLine + 1, frag.endLine - frag.startLine - 1, ...newBodyLines)
+    replaced++
+  }
+
+  return { text: lines.join(''), replaced, unchanged }
+}
+
+/**
+ * Strip library-side bare markers from a text. Used by the whole-file copy
+ * pass so that when a library file is copied into a client, the markers
+ * don't leak through.
+ *
+ * Defensive behaviour:
+ *   - Removes ONLY bare-marker lines (`<!-- <id> --start-->` / `--end-->`).
+ *   - Leaves `storyboard:<src>:<id>` namespaced markers in place — those
+ *     don't belong in library sources, but if a contributor adds one we
+ *     shouldn't silently delete it.
+ *   - Collapses any blank lines left behind so the output stays clean.
+ *
+ * @param {string} text
+ * @returns {{ text: string, stripped: number }} number of marker LINES removed.
+ */
+export function stripLibraryMarkers(text) {
+  const lines = splitLinesKeepingEol(text)
+  let stripped = 0
+
+  const filtered = lines.filter((line) => {
+    if (NAMESPACED_MARKER_RE.test(line)) return true
+
+    const m = line.match(BARE_MARKER_RE)
+    if (!m) return true
+
+    stripped++
+    return false
+  })
+
+  // Collapse runs of >2 consecutive blank lines that may now exist where
+  // a marker used to live.
+  const collapsed = []
+  let blankRun = 0
+  for (const line of filtered) {
+    const isBlank = /^\s*$/.test(stripEol(line))
+    if (isBlank) {
+      blankRun++
+      if (blankRun > 1) continue
+    } else {
+      blankRun = 0
+    }
+    collapsed.push(line)
+  }
+
+  return { text: collapsed.join(''), stripped }
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/**
+ * Split text into an array of lines that, when joined, reproduce the input
+ * byte-for-byte. Each element retains its trailing `\n` / `\r\n` (or no EOL
+ * for a trailing non-terminated line).
+ *
+ * This is the only safe way to splice line ranges back together without
+ * mangling line endings — a naive `split('\n').join('\n')` corrupts CRLF
+ * files and drops the trailing newline.
+ */
+function splitLinesKeepingEol(text) {
+  if (text === '') return []
+  const out = []
+  let start = 0
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (ch === '\n') {
+      out.push(text.slice(start, i + 1))
+      start = i + 1
+    }
+  }
+  if (start < text.length) {
+    out.push(text.slice(start))
+  }
+  return out
+}
+
+function stripEol(line) {
+  return line.replace(/\r?\n$/, '')
+}