@dfosco/storyboard 0.6.11 → 0.6.13

package/src/core/scaffold/migrateLegacyGitignore.js

@@ -0,0 +1,157 @@
+/**
+ * Migrate legacy ad-hoc `.gitignore` blocks (written by setup.js lines 401–431
+ * pre-0.6.10, or copied from the pre-fragment `scaffold/gitignore`) into the
+ * new fragment-marker form so subsequent scaffolds keep them in sync via the
+ * fragments system.
+ *
+ * Two legacy forms are handled:
+ *
+ *   1. The setup.js banner (single trailing block):
+ *
+ *        # Storyboard: runtime state (gitignored) + private tilde-prefixed files
+ *        .storyboard/
+ *        src/canvas/images/~*
+ *        ... etc.
+ *
+ *   2. The old scaffold/gitignore split form (two separate blocks):
+ *
+ *        # Runtime/transient state (per-machine, per-session)
+ *        .storyboard/agent-sessions/
+ *        ... etc.
+ *
+ *        # Private canvas images (tilde prefix = not committed)
+ *        src/canvas/images/~*
+ *        ... etc.
+ *
+ * After migration both end up as:
+ *
+ *        # <!-- storyboard:scaffold/gitignore:runtime-state --start-->
+ *        ... (library-managed body)
+ *        # <!-- storyboard:scaffold/gitignore:runtime-state --end-->
+ *
+ * Idempotent — if the file already contains the marker, leave it alone.
+ */
+
+import fs from 'node:fs'
+
+const SETUP_BANNER =
+  '# Storyboard: runtime state (gitignored) + private tilde-prefixed files'
+
+// Legacy split form headers from the pre-fragment scaffold/gitignore. We only
+// migrate when BOTH are present to avoid false positives on unrelated content.
+const SPLIT_RUNTIME_HEADER = '# Runtime/transient state (per-machine, per-session)'
+const SPLIT_PRIVATE_HEADER = '# Private canvas images (tilde prefix = not committed)'
+
+// Other related comments that the pre-fragment scaffold/gitignore wrote — we
+// strip them too when migrating the split form so we don't leave orphan
+// section headers in the file.
+const RELATED_HEADERS = [
+  '# Real-time canvas selection bridge for Copilot',
+  '# Auto-generated scaffold dir (copies of library config defaults — overwritten on every dev-server boot)',
+]
+
+const MARKER_START =
+  '# <!-- storyboard:scaffold/gitignore:runtime-state --start-->'
+const MARKER_END =
+  '# <!-- storyboard:scaffold/gitignore:runtime-state --end-->'
+
+const MARKER_PRESENT_SUBSTRING =
+  'storyboard:scaffold/gitignore:runtime-state --start'
+
+/**
+ * Detect + rewrite legacy block(s) in a `.gitignore` text.
+ *
+ * @param {string} text
+ * @returns {{ text: string, migrated: boolean }}
+ */
+export function migrateLegacyGitignore(text) {
+  if (text.includes(MARKER_PRESENT_SUBSTRING)) {
+    return { text, migrated: false }
+  }
+
+  // --- Form 1: single trailing banner from setup.js ---
+  const setupIdx = text.indexOf(SETUP_BANNER)
+  if (setupIdx !== -1) {
+    const before = text.slice(0, setupIdx).trimEnd()
+    const afterBanner = text.slice(setupIdx)
+    const bannerEnd = afterBanner.indexOf('\n')
+    const body = bannerEnd === -1 ? '' : afterBanner.slice(bannerEnd + 1).trimEnd()
+    const rewritten =
+      before +
+      '\n\n' +
+      MARKER_START + '\n' +
+      (body ? body + '\n' : '') +
+      MARKER_END + '\n'
+    return { text: rewritten, migrated: true }
+  }
+
+  // --- Form 2: split runtime + private sections from old scaffold/gitignore ---
+  if (text.includes(SPLIT_RUNTIME_HEADER) && text.includes(SPLIT_PRIVATE_HEADER)) {
+    return { text: migrateSplitForm(text), migrated: true }
+  }
+
+  return { text, migrated: false }
+}
+
+/**
+ * Apply the migration to an on-disk `.gitignore`. Returns true if the file
+ * was rewritten. Safe to call when the file doesn't exist (returns false).
+ *
+ * @param {string} gitignorePath
+ * @returns {boolean}
+ */
+export function migrateLegacyGitignoreFile(gitignorePath) {
+  if (!fs.existsSync(gitignorePath)) return false
+  const text = fs.readFileSync(gitignorePath, 'utf-8')
+  const { text: next, migrated } = migrateLegacyGitignore(text)
+  if (!migrated) return false
+  fs.writeFileSync(gitignorePath, next, 'utf-8')
+  return true
+}
+
+/**
+ * Rewrite Form 2 (split runtime + private sections) into marker form.
+ *
+ * Walk lines top-to-bottom; when we hit one of the known legacy section
+ * headers, consume all following lines until we see a blank line OR a line
+ * that doesn't look like part of that section (= doesn't start with `#`,
+ * `.storyboard/`, `src/canvas/`, `assets/`, or `.sync-target`).
+ *
+ * All consumed sections are dropped from the output, and a single marker
+ * block is appended at the end. The fragment-replace pass then populates
+ * the body from the library source.
+ */
+function migrateSplitForm(text) {
+  const lines = text.split(/\r?\n/)
+  const out = []
+  const droppedSections = new Set([
+    SPLIT_RUNTIME_HEADER,
+    SPLIT_PRIVATE_HEADER,
+    ...RELATED_HEADERS,
+  ])
+
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    if (droppedSections.has(line.trim())) {
+      // Consume until the next blank line (exclusive of that blank).
+      i++
+      while (i < lines.length && lines[i].trim() !== '') i++
+      // Also consume the blank line itself if present, to avoid double blanks.
+      if (i < lines.length && lines[i].trim() === '') i++
+      continue
+    }
+    out.push(line)
+    i++
+  }
+
+  // Trim trailing blank lines, then append the marker block.
+  while (out.length > 0 && out[out.length - 1].trim() === '') out.pop()
+
+  out.push('')
+  out.push(MARKER_START)
+  out.push(MARKER_END)
+  out.push('')
+
+  return out.join('\n')
+}

package/src/core/scaffold/scaffold-integration.test.js

@@ -0,0 +1,244 @@
+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'
+
+/**
+ * End-to-end scaffold tests: spawn the real `storyboard-scaffold` binary
+ * against a tmp client directory and assert the file outcomes match the
+ * design rules from `.agents/plans/scaffold-fragment-templating.md`.
+ *
+ * This validates the full pipeline (config → file pass → fragments pass +
+ * migration helper + library-marker stripping), not just the individual
+ * pure functions covered by `fragments.test.js`.
+ */
+
+const SCAFFOLD_BIN = path.resolve(
+  // From packages/storyboard/src/core/scaffold/scaffold-integration.test.js
+  path.dirname(new URL(import.meta.url).pathname),
+  '..', 'scaffold.js'
+)
+
+function runScaffolder(cwd, args = []) {
+  return execFileSync(process.execPath, [SCAFFOLD_BIN, ...args], {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+}
+
+let tmp
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sb-scaffold-'))
+})
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true })
+})
+
+describe('storyboard-scaffold integration', () => {
+  it('fresh client: copies whole files and strips library markers from the output', () => {
+    runScaffolder(tmp)
+
+    const gitignore = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+
+    // Library-side bare markers must NOT leak into the client output.
+    expect(gitignore).not.toMatch(/<!--\s+runtime-state\s+--start-->/)
+    expect(gitignore).not.toMatch(/<!--\s+runtime-state\s+--end-->/)
+
+    // The fragment body content should be present.
+    expect(gitignore).toContain('.storyboard/')
+    expect(gitignore).toContain('src/canvas/**/drafts/')
+    expect(gitignore).toContain('src/prototypes/**/drafts/')
+  })
+
+  it('re-run on a fresh client is a no-op (idempotent)', () => {
+    runScaffolder(tmp)
+    const before = snapshot(tmp)
+    runScaffolder(tmp)
+    const after = snapshot(tmp)
+    expect(after).toEqual(before)
+  })
+
+  it('client with explicit fragment markers: rewrites only the fragment body', () => {
+    // Hand-craft a client .gitignore that has its own header + a marker block
+    // pointing at the library fragment with stale content inside.
+    const clientGitignore = [
+      '# my custom header',
+      '/node_modules',
+      '',
+      '# <!-- storyboard:scaffold/gitignore:runtime-state --start-->',
+      'STALE-CONTENT-THAT-MUST-BE-REPLACED',
+      '# <!-- storyboard:scaffold/gitignore:runtime-state --end-->',
+      '',
+      '# my custom footer',
+      '',
+    ].join('\n')
+    fs.writeFileSync(path.join(tmp, '.gitignore'), clientGitignore, 'utf-8')
+
+    runScaffolder(tmp, ['--fragments-only'])
+
+    const updated = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+
+    // Outside-marker content preserved exactly.
+    expect(updated).toContain('# my custom header')
+    expect(updated).toContain('# my custom footer')
+    expect(updated).toContain('/node_modules')
+
+    // Fragment body rewritten.
+    expect(updated).not.toContain('STALE-CONTENT-THAT-MUST-BE-REPLACED')
+    expect(updated).toContain('.storyboard/')
+
+    // Client markers stay so the next scaffold can keep things in sync.
+    expect(updated).toContain('storyboard:scaffold/gitignore:runtime-state --start')
+    expect(updated).toContain('storyboard:scaffold/gitignore:runtime-state --end')
+  })
+
+  it('client with unknown fragment id: exits non-zero with a clear error', () => {
+    const clientGitignore = [
+      '# <!-- storyboard:scaffold/gitignore:does-not-exist --start-->',
+      'x',
+      '# <!-- storyboard:scaffold/gitignore:does-not-exist --end-->',
+      '',
+    ].join('\n')
+    fs.writeFileSync(path.join(tmp, '.gitignore'), clientGitignore, 'utf-8')
+
+    let threw = false
+    let errOutput = ''
+    try {
+      runScaffolder(tmp, ['--fragments-only'])
+    } catch (err) {
+      threw = true
+      errOutput = String(err.stderr || '') + String(err.stdout || '')
+    }
+
+    expect(threw).toBe(true)
+    expect(errOutput).toMatch(/No fragment "does-not-exist"/)
+  })
+
+  it('legacy ad-hoc gitignore banner is migrated into marker form', () => {
+    // Mimic what setup.js used to append in pre-0.6.10 clients.
+    const legacy = [
+      '# my header',
+      '/node_modules',
+      '',
+      '# Storyboard: runtime state (gitignored) + private tilde-prefixed files',
+      '.storyboard/',
+      'src/canvas/images/~*',
+      'assets/canvas/images/~*',
+      '',
+    ].join('\n')
+    fs.writeFileSync(path.join(tmp, '.gitignore'), legacy, 'utf-8')
+
+    runScaffolder(tmp, ['--fragments-only'])
+
+    const updated = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+
+    // Header preserved.
+    expect(updated).toContain('# my header')
+    expect(updated).toContain('/node_modules')
+
+    // Markers now present.
+    expect(updated).toContain('storyboard:scaffold/gitignore:runtime-state --start')
+    expect(updated).toContain('storyboard:scaffold/gitignore:runtime-state --end')
+
+    // Legacy banner gone.
+    expect(updated).not.toContain('# Storyboard: runtime state (gitignored) + private tilde-prefixed files')
+
+    // Fragment body matches the library.
+    expect(updated).toContain('src/canvas/**/drafts/')
+
+    // Second run is a no-op.
+    const before = updated
+    runScaffolder(tmp, ['--fragments-only'])
+    const after = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+    expect(after).toBe(before)
+  })
+
+  it('legacy split-form gitignore (Runtime + Private headers) is migrated into marker form', () => {
+    // Mimic a client that received the pre-fragment scaffold/gitignore where
+    // runtime state and private images lived in two separate sections.
+    const legacy = [
+      '# my header',
+      '/node_modules',
+      '',
+      '# Runtime/transient state (per-machine, per-session)',
+      '.storyboard/agent-sessions/',
+      '.storyboard/hot-pool/',
+      '.storyboard/logs/',
+      '',
+      '# Private canvas images (tilde prefix = not committed)',
+      'src/canvas/images/~*',
+      'assets/canvas/images/~*',
+      '.sync-target',
+      '',
+      '# Integration test results (ephemeral local artifacts)',
+      'test-results/',
+      '',
+    ].join('\n')
+    fs.writeFileSync(path.join(tmp, '.gitignore'), legacy, 'utf-8')
+
+    runScaffolder(tmp, ['--fragments-only'])
+
+    const updated = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+
+    // Header preserved.
+    expect(updated).toContain('# my header')
+    // Unrelated section (test-results) preserved.
+    expect(updated).toContain('# Integration test results (ephemeral local artifacts)')
+    expect(updated).toContain('test-results/')
+
+    // Both legacy section headers gone.
+    expect(updated).not.toContain('# Runtime/transient state (per-machine, per-session)')
+    expect(updated).not.toContain('# Private canvas images (tilde prefix = not committed)')
+
+    // Marker block present with library body.
+    expect(updated).toContain('storyboard:scaffold/gitignore:runtime-state --start')
+    expect(updated).toContain('src/canvas/**/drafts/')
+
+    // Second run is a no-op.
+    const before = updated
+    runScaffolder(tmp, ['--fragments-only'])
+    const after = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+    expect(after).toBe(before)
+  })
+
+  it('--files-only skips the fragment pass entirely', () => {
+    // Seed a gitignore with a stale fragment body. --files-only should NOT
+    // touch it because the fragment-replace pass is suppressed.
+    const stale = [
+      '# <!-- storyboard:scaffold/gitignore:runtime-state --start-->',
+      'STALE',
+      '# <!-- storyboard:scaffold/gitignore:runtime-state --end-->',
+      '',
+    ].join('\n')
+    fs.writeFileSync(path.join(tmp, '.gitignore'), stale, 'utf-8')
+
+    runScaffolder(tmp, ['--files-only'])
+
+    const after = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
+    expect(after).toContain('STALE')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function snapshot(dir) {
+  const out = {}
+  function walk(d) {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, entry.name)
+      if (entry.isDirectory()) {
+        walk(full)
+      } else {
+        out[path.relative(dir, full)] = fs.readFileSync(full, 'utf-8')
+      }
+    }
+  }
+  walk(dir)
+  return out
+}

package/src/core/scaffold.js

@@ -1,100 +1,7 @@
 #!/usr/bin/env node
 /**
- * storyboard-scaffold — sync scaffold files from @dfosco/storyboard.
- *
- * Reads scaffold/manifest.json and copies files to the consumer repo:
- * - "scaffold" mode: only if target doesn't exist (never overwrites config)
- * - "updateable" mode: always overwrites with latest (skills, scripts)
- *
- * Usage:
- *   npx storyboard-scaffold
+ * storyboard-scaffold — thin shim that re-exports the implementation from
+ * ./scaffold/index.js. Keeps `bin.storyboard-scaffold` resolving to a stable
+ * path while the actual logic lives in a dedicated directory.
  */
-
-import fs from 'node:fs'
-import path from 'node:path'
-
-const __dirname = path.dirname(new URL(import.meta.url).pathname)
-const scaffoldRoot = path.resolve(__dirname, '..', '..', 'scaffold')
-const consumerRoot = process.cwd()
-
-const manifestPath = path.join(scaffoldRoot, 'manifest.json')
-if (!fs.existsSync(manifestPath)) {
-  console.error('❌ Could not find scaffold/manifest.json in @dfosco/storyboard-core')
-  process.exit(1)
-}
-
-const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'))
-
-function copyFileSync(src, dest) {
-  const dir = path.dirname(dest)
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true })
-  }
-  fs.copyFileSync(src, dest)
-}
-
-function copyDirSync(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true })
-  }
-  const entries = fs.readdirSync(src, { withFileTypes: true })
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name)
-    const destPath = path.join(dest, entry.name)
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, destPath)
-    } else {
-      copyFileSync(srcPath, destPath)
-    }
-  }
-}
-
-let created = 0
-let updated = 0
-let skipped = 0
-
-for (const file of manifest.files) {
-  const srcPath = path.join(scaffoldRoot, path.relative('scaffold', file.source))
-  const destPath = path.join(consumerRoot, file.target)
-
-  if (file.directory) {
-    if (file.mode === 'updateable') {
-      copyDirSync(srcPath, destPath)
-      updated++
-      console.log(`  ✔ Updated ${file.target} (sync)`)
-    } else {
-      if (!fs.existsSync(destPath)) {
-        copyDirSync(srcPath, destPath)
-        created++
-        console.log(`  ✔ Created ${file.target} (scaffold)`)
-      } else {
-        skipped++
-        console.log(`  ⏭ Skipped ${file.target} (already exists)`)
-      }
-    }
-    continue
-  }
-
-  if (file.mode === 'scaffold') {
-    if (fs.existsSync(destPath)) {
-      skipped++
-      console.log(`  ⏭ Skipped ${file.target} (already exists)`)
-    } else {
-      copyFileSync(srcPath, destPath)
-      created++
-      console.log(`  ✔ Created ${file.target} (scaffold)`)
-    }
-  } else if (file.mode === 'updateable') {
-    copyFileSync(srcPath, destPath)
-    updated++
-    console.log(`  ✔ Updated ${file.target} (sync)`)
-  }
-
-  // Make shell scripts executable
-  if (file.target.endsWith('.sh')) {
-    fs.chmodSync(destPath, 0o755)
-  }
-}
-
-console.log('')
-console.log(`✔ Scaffold complete: ${created} created, ${updated} updated, ${skipped} skipped.`)
+import './scaffold/index.js'