@dfosco/storyboard 0.6.11 → 0.6.13

package/src/core/scaffold/fragments.test.js

@@ -0,0 +1,401 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parseFragments,
+  extractFragment,
+  applyFragments,
+  stripLibraryMarkers,
+} from './fragments.js'
+
+// Helpers -------------------------------------------------------------------
+
+function mkLookup(entries) {
+  return (src, id) => {
+    const key = `${src}:${id}`
+    return Object.prototype.hasOwnProperty.call(entries, key) ? entries[key] : null
+  }
+}
+
+const RUNTIME_BODY = '.storyboard/\nsrc/canvas/**/drafts/\n'
+
+const CLIENT_GITIGNORE = `# top of file
+/node_modules
+.DS_Store
+
+# <!-- storyboard:scaffold/gitignore:runtime-state --start-->
+old-content
+that-will-be-replaced
+# <!-- storyboard:scaffold/gitignore:runtime-state --end-->
+
+# bottom of file
+`
+
+const LIBRARY_GITIGNORE = `# packages/storyboard/scaffold/gitignore
+/some/library/comment
+
+# <!-- runtime-state --start-->
+.storyboard/
+src/canvas/**/drafts/
+# <!-- runtime-state --end-->
+
+# trailing library comment
+`
+
+// parseFragments ------------------------------------------------------------
+
+describe('parseFragments', () => {
+  it('returns [] on a file with no markers', () => {
+    expect(parseFragments('hello\nworld\n')).toEqual([])
+  })
+
+  it('returns [] on an empty string', () => {
+    expect(parseFragments('')).toEqual([])
+  })
+
+  it('parses a single fragment with start/end on their own lines', () => {
+    const out = parseFragments(CLIENT_GITIGNORE)
+    expect(out).toHaveLength(1)
+    expect(out[0]).toMatchObject({
+      sourcePath: 'scaffold/gitignore',
+      id: 'runtime-state',
+    })
+    expect(out[0].body).toBe('old-content\nthat-will-be-replaced\n')
+  })
+
+  it('parses multiple fragments in the same file', () => {
+    const text = [
+      '# <!-- storyboard:scaffold/a:one --start-->',
+      'A1',
+      '# <!-- storyboard:scaffold/a:one --end-->',
+      'middle',
+      '# <!-- storyboard:scaffold/b:two --start-->',
+      'B1',
+      'B2',
+      '# <!-- storyboard:scaffold/b:two --end-->',
+      '',
+    ].join('\n')
+    const out = parseFragments(text)
+    expect(out).toHaveLength(2)
+    expect(out[0].id).toBe('one')
+    expect(out[1].id).toBe('two')
+    expect(out[1].body).toBe('B1\nB2\n')
+  })
+
+  it('handles an empty fragment body', () => {
+    const text = [
+      '# <!-- storyboard:src:id --start-->',
+      '# <!-- storyboard:src:id --end-->',
+      '',
+    ].join('\n')
+    const out = parseFragments(text)
+    expect(out[0].body).toBe('')
+  })
+
+  it('rejects duplicate start without intervening end', () => {
+    const text = [
+      '# <!-- storyboard:src:id --start-->',
+      'x',
+      '# <!-- storyboard:src:id --start-->',
+      '',
+    ].join('\n')
+    expect(() => parseFragments(text)).toThrow(/Duplicate or nested/)
+  })
+
+  it('rejects stray end with no matching start', () => {
+    const text = [
+      'a',
+      '# <!-- storyboard:src:id --end-->',
+      '',
+    ].join('\n')
+    expect(() => parseFragments(text)).toThrow(/Stray storyboard:src:id --end--/)
+  })
+
+  it('rejects unclosed start', () => {
+    const text = [
+      '# <!-- storyboard:src:id --start-->',
+      'body',
+      '',
+    ].join('\n')
+    expect(() => parseFragments(text)).toThrow(/Unclosed storyboard:src:id/)
+  })
+
+  it('ignores comment prefix style (works for #, //, <!--, etc.)', () => {
+    const text = [
+      '// <!-- storyboard:a:one --start-->',
+      'x',
+      '// <!-- storyboard:a:one --end-->',
+      '<!-- storyboard:b:two --start-->',
+      'y',
+      '<!-- storyboard:b:two --end-->',
+      '',
+    ].join('\n')
+    const out = parseFragments(text)
+    expect(out).toHaveLength(2)
+    expect(out.map(f => f.id)).toEqual(['one', 'two'])
+  })
+
+  it('handles CRLF line endings', () => {
+    const text =
+      '# <!-- storyboard:src:id --start-->\r\n' +
+      'body\r\n' +
+      '# <!-- storyboard:src:id --end-->\r\n'
+    const out = parseFragments(text)
+    expect(out).toHaveLength(1)
+    expect(out[0].body).toBe('body\r\n')
+  })
+})
+
+// extractFragment -----------------------------------------------------------
+
+describe('extractFragment', () => {
+  it('returns the body for a matching bare marker', () => {
+    expect(extractFragment(LIBRARY_GITIGNORE, 'runtime-state')).toBe(RUNTIME_BODY)
+  })
+
+  it('returns null when the fragment id is not present', () => {
+    expect(extractFragment(LIBRARY_GITIGNORE, 'nope')).toBeNull()
+  })
+
+  it('returns null on an empty source file', () => {
+    expect(extractFragment('', 'whatever')).toBeNull()
+  })
+
+  it('handles an empty body', () => {
+    const src = '<!-- empty --start-->\n<!-- empty --end-->\n'
+    expect(extractFragment(src, 'empty')).toBe('')
+  })
+
+  it('rejects duplicate --start-- for the same id', () => {
+    const src = [
+      '<!-- dup --start-->',
+      '<!-- dup --start-->',
+      '<!-- dup --end-->',
+      '',
+    ].join('\n')
+    expect(() => extractFragment(src, 'dup')).toThrow(/Duplicate --start--/)
+  })
+
+  it('rejects stray --end-- for the same id', () => {
+    const src = '<!-- ghost --end-->\n'
+    expect(() => extractFragment(src, 'ghost')).toThrow(/Stray --end--/)
+  })
+
+  it('rejects unclosed --start--', () => {
+    const src = '<!-- open --start-->\nstuff\n'
+    expect(() => extractFragment(src, 'open')).toThrow(/Unclosed --start--/)
+  })
+
+  it('ignores markers for other ids', () => {
+    const src = [
+      '<!-- other --start-->',
+      'OTHER',
+      '<!-- other --end-->',
+      '<!-- target --start-->',
+      'TARGET',
+      '<!-- target --end-->',
+      '',
+    ].join('\n')
+    expect(extractFragment(src, 'target')).toBe('TARGET\n')
+  })
+})
+
+// applyFragments ------------------------------------------------------------
+
+describe('applyFragments', () => {
+  it('rewrites a single fragment body and reports replaced count', () => {
+    const lookup = mkLookup({ 'scaffold/gitignore:runtime-state': RUNTIME_BODY })
+    const out = applyFragments(CLIENT_GITIGNORE, lookup)
+    expect(out.replaced).toBe(1)
+    expect(out.unchanged).toBe(0)
+    expect(out.text).toContain(RUNTIME_BODY)
+    expect(out.text).not.toContain('old-content')
+    // Outside-marker content preserved exactly
+    expect(out.text).toContain('# top of file')
+    expect(out.text).toContain('# bottom of file')
+    expect(out.text.split('\n')[0]).toBe('# top of file')
+  })
+
+  it('is idempotent: applying twice produces the same text', () => {
+    const lookup = mkLookup({ 'scaffold/gitignore:runtime-state': RUNTIME_BODY })
+    const once = applyFragments(CLIENT_GITIGNORE, lookup).text
+    const twice = applyFragments(once, lookup)
+    expect(twice.text).toBe(once)
+    expect(twice.replaced).toBe(0)
+    expect(twice.unchanged).toBe(1)
+  })
+
+  it('returns text unchanged when there are no fragments', () => {
+    const out = applyFragments('just some text\n', mkLookup({}))
+    expect(out.text).toBe('just some text\n')
+    expect(out.replaced).toBe(0)
+  })
+
+  it('throws when a fragment references an unknown source/id', () => {
+    expect(() => applyFragments(CLIENT_GITIGNORE, mkLookup({}))).toThrow(
+      /No fragment "runtime-state" found in scaffold\/gitignore/
+    )
+  })
+
+  it('rewrites multiple fragments without index drift', () => {
+    const text = [
+      'header',
+      '# <!-- storyboard:src:one --start-->',
+      'OLD-ONE',
+      '# <!-- storyboard:src:one --end-->',
+      'middle',
+      '# <!-- storyboard:src:two --start-->',
+      'OLD-TWO-A',
+      'OLD-TWO-B',
+      '# <!-- storyboard:src:two --end-->',
+      'footer',
+      '',
+    ].join('\n')
+    const lookup = mkLookup({
+      'src:one': 'NEW-ONE-A\nNEW-ONE-B\nNEW-ONE-C\n',
+      'src:two': 'NEW-TWO\n',
+    })
+    const out = applyFragments(text, lookup)
+    expect(out.replaced).toBe(2)
+    expect(out.text).toContain('NEW-ONE-A\nNEW-ONE-B\nNEW-ONE-C\n')
+    expect(out.text).toContain('NEW-TWO\n')
+    expect(out.text).not.toContain('OLD-')
+    expect(out.text.split('\n')[0]).toBe('header')
+    expect(out.text).toMatch(/footer\n$/)
+  })
+
+  it('preserves CRLF line endings around the fragment', () => {
+    const text =
+      'header\r\n' +
+      '# <!-- storyboard:src:id --start-->\r\n' +
+      'OLD\r\n' +
+      '# <!-- storyboard:src:id --end-->\r\n' +
+      'footer\r\n'
+    const out = applyFragments(text, mkLookup({ 'src:id': 'NEW\r\n' }))
+    expect(out.text).toBe(
+      'header\r\n' +
+      '# <!-- storyboard:src:id --start-->\r\n' +
+      'NEW\r\n' +
+      '# <!-- storyboard:src:id --end-->\r\n' +
+      'footer\r\n'
+    )
+  })
+
+  it('counts unchanged fragments separately from replaced', () => {
+    const text = [
+      '# <!-- storyboard:src:one --start-->',
+      'KEEP-ME',
+      '# <!-- storyboard:src:one --end-->',
+      '# <!-- storyboard:src:two --start-->',
+      'OLD',
+      '# <!-- storyboard:src:two --end-->',
+      '',
+    ].join('\n')
+    const lookup = mkLookup({
+      'src:one': 'KEEP-ME\n',
+      'src:two': 'NEW\n',
+    })
+    const out = applyFragments(text, lookup)
+    expect(out.replaced).toBe(1)
+    expect(out.unchanged).toBe(1)
+  })
+})
+
+// stripLibraryMarkers -------------------------------------------------------
+
+describe('stripLibraryMarkers', () => {
+  it('removes bare --start-- and --end-- marker lines', () => {
+    const out = stripLibraryMarkers(LIBRARY_GITIGNORE)
+    expect(out.stripped).toBe(2)
+    expect(out.text).not.toMatch(/--start--/)
+    expect(out.text).not.toMatch(/--end--/)
+    expect(out.text).toContain('.storyboard/')
+    expect(out.text).toContain('src/canvas/**/drafts/')
+    expect(out.text).toContain('# trailing library comment')
+  })
+
+  it('leaves non-marker content untouched', () => {
+    const text = 'a\nb\nc\n'
+    const out = stripLibraryMarkers(text)
+    expect(out.stripped).toBe(0)
+    expect(out.text).toBe('a\nb\nc\n')
+  })
+
+  it('leaves storyboard:-namespaced markers intact (defensive)', () => {
+    const text = [
+      '# <!-- storyboard:scaffold/x:foo --start-->',
+      'body',
+      '# <!-- storyboard:scaffold/x:foo --end-->',
+      '',
+    ].join('\n')
+    const out = stripLibraryMarkers(text)
+    expect(out.stripped).toBe(0)
+    expect(out.text).toBe(text)
+  })
+
+  it('collapses runs of blank lines left behind', () => {
+    const text = [
+      'first',
+      '',
+      '<!-- a --start-->',
+      'body',
+      '<!-- a --end-->',
+      '',
+      'last',
+      '',
+    ].join('\n')
+    const out = stripLibraryMarkers(text)
+    expect(out.stripped).toBe(2)
+    // The two blank lines that bracketed the markers should collapse to one.
+    expect(out.text.split('\n\n').length).toBeLessThanOrEqual(3)
+    expect(out.text).toContain('first')
+    expect(out.text).toContain('body')
+    expect(out.text).toContain('last')
+  })
+
+  it('handles multiple bare fragments in one file', () => {
+    const text = [
+      '<!-- one --start-->',
+      'A',
+      '<!-- one --end-->',
+      '<!-- two --start-->',
+      'B',
+      '<!-- two --end-->',
+      '',
+    ].join('\n')
+    const out = stripLibraryMarkers(text)
+    expect(out.stripped).toBe(4)
+    expect(out.text).toContain('A')
+    expect(out.text).toContain('B')
+  })
+
+  it('is idempotent', () => {
+    const once = stripLibraryMarkers(LIBRARY_GITIGNORE).text
+    const twice = stripLibraryMarkers(once)
+    expect(twice.text).toBe(once)
+    expect(twice.stripped).toBe(0)
+  })
+})
+
+// Cross-function integration -----------------------------------------------
+
+describe('integration: client.apply ↔ library.extract', () => {
+  it('round-trips through apply + extract', () => {
+    const lookup = (src, id) => {
+      if (src === 'scaffold/gitignore') return extractFragment(LIBRARY_GITIGNORE, id)
+      return null
+    }
+    const applied = applyFragments(CLIENT_GITIGNORE, lookup)
+    const fragments = parseFragments(applied.text)
+    expect(fragments).toHaveLength(1)
+    expect(fragments[0].body).toBe(RUNTIME_BODY)
+  })
+
+  it('whole-file strip yields content equivalent to the fragment body for a single-fragment file', () => {
+    // A trivial library file containing nothing but the fragment.
+    const src = '<!-- only --start-->\nA\nB\n<!-- only --end-->\n'
+    const stripped = stripLibraryMarkers(src).text
+    const body = extractFragment(src, 'only')
+    // Stripping leaves the body intact (plus the trailing newline that was
+    // after the closing marker on its own line).
+    expect(stripped).toContain(body)
+  })
+})

package/src/core/scaffold/index.js

@@ -0,0 +1,291 @@
+/**
+ * storyboard-scaffold — sync scaffold files from @dfosco/storyboard.
+ *
+ * Two passes per run, driven by `packages/storyboard/scaffold/scaffold.config.json`:
+ *
+ *   1. Whole-file pass (`files[]`):
+ *      - `mode: "scaffold"`   — copy library file to client only if target is missing
+ *      - `mode: "updateable"` — always overwrite client file with library version
+ *      Both call `stripLibraryMarkers()` on the source content first so library
+ *      bare markers (`<!-- <id> --start-->`) never leak into client output.
+ *
+ *   2. Fragment-replace pass (`fragmentSources[]`):
+ *      - For every client file that contains `<!-- storyboard:<src>:<id> --start-->`
+ *        markers, rewrite each fragment body from the corresponding library
+ *        source. Content outside markers is preserved exactly.
+ *      - Scans `files[]` targets plus a curated set of well-known config files
+ *        (`.gitignore`, `AGENTS.md`, `README.md`) so clients can opt in to
+ *        fragment-only updates without listing the file in `files[]`.
+ *
+ * A one-shot legacy migration runs before pass 2: any `.gitignore` containing
+ * the pre-0.6.10 ad-hoc storyboard banner is rewritten into marker form so
+ * subsequent scaffolds keep it in sync.
+ *
+ * Backwards-compat: if `scaffold.config.json` is missing but the old
+ * `manifest.json` exists, we read it and emit a deprecation warning.
+ *
+ * Usage:
+ *   npx storyboard-scaffold                  # both passes
+ *   npx storyboard-scaffold --fragments-only # skip pass 1, only rewrite fragments
+ *   npx storyboard-scaffold --files-only     # skip pass 2, only copy whole files
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { applyFragments, extractFragment, stripLibraryMarkers } from './fragments.js'
+import { migrateLegacyGitignoreFile } from './migrateLegacyGitignore.js'
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
+
+// We're at packages/storyboard/src/core/scaffold/index.js — the library
+// scaffold tree lives at packages/storyboard/scaffold/
+const scaffoldRoot = path.resolve(__dirname, '..', '..', '..', 'scaffold')
+const consumerRoot = process.cwd()
+
+// Targets that clients commonly mark up with fragment markers but might not
+// have in `files[]`. Always scanned during the fragment pass.
+const WELL_KNOWN_FRAGMENT_TARGETS = ['.gitignore', 'AGENTS.md', 'README.md']
+
+const args = new Set(process.argv.slice(2))
+const filesOnly = args.has('--files-only')
+const fragmentsOnly = args.has('--fragments-only')
+
+function loadConfig() {
+  const cfgPath = path.join(scaffoldRoot, 'scaffold.config.json')
+  if (fs.existsSync(cfgPath)) {
+    return JSON.parse(fs.readFileSync(cfgPath, 'utf-8'))
+  }
+  // Backcompat fallback for one release — manifest.json was the old name.
+  const legacyPath = path.join(scaffoldRoot, 'manifest.json')
+  if (fs.existsSync(legacyPath)) {
+    console.warn(
+      '  ⚠ Reading legacy scaffold/manifest.json — rename to scaffold.config.json (this fallback is removed in the next release)'
+    )
+    return JSON.parse(fs.readFileSync(legacyPath, 'utf-8'))
+  }
+  console.error('❌ Could not find scaffold/scaffold.config.json in @dfosco/storyboard')
+  process.exit(1)
+}
+
+const config = loadConfig()
+
+// ---------------------------------------------------------------------------
+// FS helpers
+// ---------------------------------------------------------------------------
+
+function ensureDir(dest) {
+  const dir = path.dirname(dest)
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+}
+
+function writeStripped(srcPath, destPath) {
+  ensureDir(destPath)
+  const text = fs.readFileSync(srcPath, 'utf-8')
+  const { text: stripped, stripped: count } = stripLibraryMarkers(text)
+  fs.writeFileSync(destPath, stripped)
+  if (destPath.endsWith('.sh')) fs.chmodSync(destPath, 0o755)
+  return count
+}
+
+function copyFileStripped(srcPath, destPath) {
+  // Binary files: just copy bytes.
+  if (isLikelyBinary(srcPath)) {
+    ensureDir(destPath)
+    fs.copyFileSync(srcPath, destPath)
+    if (destPath.endsWith('.sh')) fs.chmodSync(destPath, 0o755)
+    return 0
+  }
+  return writeStripped(srcPath, destPath)
+}
+
+function copyDirStripped(srcDir, destDir) {
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true })
+  let stripped = 0
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const s = path.join(srcDir, entry.name)
+    const d = path.join(destDir, entry.name)
+    if (entry.isDirectory()) {
+      stripped += copyDirStripped(s, d)
+    } else {
+      stripped += copyFileStripped(s, d)
+    }
+  }
+  return stripped
+}
+
+function isLikelyBinary(filePath) {
+  const ext = path.extname(filePath).toLowerCase()
+  return [
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.icns',
+    '.woff', '.woff2', '.ttf', '.otf',
+    '.zip', '.gz', '.tgz', '.tar',
+    '.mp4', '.mov', '.webm',
+  ].includes(ext)
+}
+
+// ---------------------------------------------------------------------------
+// Pass 1: whole-file copies
+// ---------------------------------------------------------------------------
+
+function runFilesPass() {
+  let created = 0
+  let updated = 0
+  let skipped = 0
+  let strippedTotal = 0
+
+  for (const file of config.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') {
+        strippedTotal += copyDirStripped(srcPath, destPath)
+        updated++
+        console.log(`  ✔ Updated ${file.target} (sync)`)
+      } else if (!fs.existsSync(destPath)) {
+        strippedTotal += copyDirStripped(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 {
+        strippedTotal += copyFileStripped(srcPath, destPath)
+        created++
+        console.log(`  ✔ Created ${file.target} (scaffold)`)
+      }
+    } else if (file.mode === 'updateable') {
+      strippedTotal += copyFileStripped(srcPath, destPath)
+      updated++
+      console.log(`  ✔ Updated ${file.target} (sync)`)
+    }
+  }
+
+  return { created, updated, skipped, strippedTotal }
+}
+
+// ---------------------------------------------------------------------------
+// Pass 2: fragment-replace on client files
+// ---------------------------------------------------------------------------
+
+// Cache parsed fragment bodies per (srcRelPath, fragmentId).
+const fragmentCache = new Map()
+
+function lookupFragment(srcRelPath, fragmentId) {
+  const key = `${srcRelPath}::${fragmentId}`
+  if (fragmentCache.has(key)) return fragmentCache.get(key)
+
+  // srcRelPath looks like "scaffold/gitignore". Resolve against the library
+  // scaffold root which already starts with .../packages/storyboard/scaffold,
+  // so we strip the leading "scaffold/" before joining.
+  const rel = srcRelPath.replace(/^scaffold\//, '')
+  const absPath = path.join(scaffoldRoot, rel)
+  if (!fs.existsSync(absPath)) {
+    fragmentCache.set(key, null)
+    return null
+  }
+  const srcText = fs.readFileSync(absPath, 'utf-8')
+  const body = extractFragment(srcText, fragmentId)
+  fragmentCache.set(key, body)
+  return body
+}
+
+function gatherFragmentTargets() {
+  const set = new Set(WELL_KNOWN_FRAGMENT_TARGETS)
+  for (const file of config.files) {
+    if (file.directory) continue
+    set.add(file.target)
+  }
+  return [...set]
+}
+
+function runFragmentsPass() {
+  let synced = 0
+  let unchanged = 0
+  const errors = []
+
+  for (const rel of gatherFragmentTargets()) {
+    const destPath = path.join(consumerRoot, rel)
+    if (!fs.existsSync(destPath)) continue
+    if (isLikelyBinary(destPath)) continue
+
+    let clientText
+    try {
+      clientText = fs.readFileSync(destPath, 'utf-8')
+    } catch {
+      continue
+    }
+    if (!clientText.includes('storyboard:')) continue
+
+    try {
+      const result = applyFragments(clientText, lookupFragment)
+      if (result.replaced > 0) {
+        fs.writeFileSync(destPath, result.text)
+        synced += result.replaced
+        console.log(`  ✔ Synced ${result.replaced} fragment(s) in ${rel}`)
+      }
+      unchanged += result.unchanged
+    } catch (err) {
+      errors.push({ path: rel, message: err.message })
+    }
+  }
+
+  return { synced, unchanged, errors }
+}
+
+// ---------------------------------------------------------------------------
+// Entry
+// ---------------------------------------------------------------------------
+
+let filesStats = { created: 0, updated: 0, skipped: 0, strippedTotal: 0 }
+let fragmentStats = { synced: 0, unchanged: 0, errors: [] }
+let migratedLegacy = false
+
+if (!fragmentsOnly) {
+  filesStats = runFilesPass()
+}
+
+if (!filesOnly) {
+  // One-shot migration of pre-0.6.10 ad-hoc gitignore banner.
+  try {
+    migratedLegacy = migrateLegacyGitignoreFile(path.join(consumerRoot, '.gitignore'))
+    if (migratedLegacy) {
+      console.log('  ✔ Migrated legacy .gitignore block to fragment markers')
+    }
+  } catch (err) {
+    console.warn(`  ⚠ Failed to migrate legacy .gitignore: ${err.message}`)
+  }
+
+  fragmentStats = runFragmentsPass()
+}
+
+console.log('')
+const parts = []
+if (!fragmentsOnly) {
+  parts.push(`${filesStats.created} created`)
+  parts.push(`${filesStats.updated} updated`)
+  parts.push(`${filesStats.skipped} skipped`)
+  if (filesStats.strippedTotal > 0) parts.push(`${filesStats.strippedTotal} markers stripped`)
+}
+if (!filesOnly) {
+  parts.push(`${fragmentStats.synced} fragment(s) synced`)
+  if (fragmentStats.unchanged > 0) parts.push(`${fragmentStats.unchanged} unchanged`)
+}
+console.log(`✔ Scaffold complete: ${parts.join(', ')}.`)
+
+if (fragmentStats.errors.length > 0) {
+  console.error('')
+  console.error(`❌ ${fragmentStats.errors.length} fragment error(s):`)
+  for (const e of fragmentStats.errors) {
+    console.error(`   ${e.path}: ${e.message}`)
+  }
+  process.exit(1)
+}