@abarcenas/ai-workflow-template 1.45.0 → 1.46.0

package/scripts/sync.js

@@ -1,28 +1,197 @@
 import { createHash } from 'crypto'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs'
-import { dirname, join, relative, resolve } from 'path'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'path'
 import { fileURLToPath } from 'url'
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const packageRoot = resolve(__dirname, '..')
-const sourceAgentsDir = resolve(packageRoot, '.agents')
-const consumerRoot = process.env.INIT_CWD ? resolve(process.env.INIT_CWD) : process.cwd()
-const targetAgentsDir = resolve(consumerRoot, '.agents')
-const manifestPath = resolve(consumerRoot, '.agents-sync-manifest.json')
-const excludedRelativePaths = new Set([
+const defaultPackageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+export const excludedRelativePaths = new Set([
   'instructions/learned-knowledge.instructions.md',
 ])
-const args = new Set(process.argv.slice(2))
-const forceOverwrite = args.has('--force')
-const dryRun = args.has('--dry-run')
-const isVerbose = process.env.AI_WORKFLOW_VERBOSE === '1'
 
-function hashFile(filePath) {
+export const openCodeExcluded = new Set([
+  'node_modules',
+  'package.json',
+  'package-lock.json',
+  'bun.lock',
+  '.gitignore',
+])
+
+export const rootFiles = ['AGENTS.md', 'opencode.json', 'skills-lock.json']
+
+export const scriptsToSync = [
+  'memory-cli.js',
+  'memory-index.js',
+  'bump-version.js',
+  'validate-memory-schema.js',
+  'vocab-sync.js',
+  'mcp-memory-server.js',
+  'mcp/playwright-mcp-launcher.js',
+  // Knowledgebase scripts
+  'knowledgebase-cli.js',
+  'knowledgebase-index.js',
+  'mcp-knowledgebase-server.js',
+  'knowledgebase-init.sql',
+]
+
+export const memoryBankStubs = {
+  'projectbrief.md': `# projectbrief
+
+> Foundation document — defines core requirements and goals.
+
+- **Purpose**: {{describe project purpose}}
+- **Goals**: {{list project goals}}
+- **Scope**: {{define scope}}
+`,
+  'productContext.md': `# productContext
+
+> Why this project exists and what problems it solves.
+
+- **Problem**: {{describe the problem}}
+- **Solution**: {{describe the solution}}
+- **User Experience**: {{describe UX goals}}
+`,
+  'activeContext.md': `# activeContext
+
+> Current work focus, recent changes, next steps.
+
+- **Current Focus**: {{current task or goal}}
+- **Recent Changes**: {{list of recent changes}}
+- **Next Steps**: {{next actions}}
+`,
+  'systemPatterns.md': `# systemPatterns
+
+> Architecture, key decisions, design patterns.
+
+- **Architecture**: {{describe architecture}}
+- **Key Decisions**: {{list key technical decisions}}
+- **Patterns**: {{list design patterns in use}}
+`,
+  'techContext.md': `# techContext
+
+> Technologies, setup, constraints, dependencies.
+
+- **Stack**: {{list technologies}}
+- **Setup**: {{describe dev setup}}
+- **Constraints**: {{list technical constraints}}
+`,
+  'progress.md': `# progress
+
+> What works, what's left, current status.
+
+- **Working**: {{what's implemented and working}}
+- **To Build**: {{what remains}}
+- **Status**: {{overall project status}}
+- **Known Issues**: {{list known issues}}
+`,
+}
+
+export const agentInstructionsStubs = {
+  'learned-knowledge.instructions.md': `# Learned Knowledge
+
+Cross-session knowledge accumulated by agent pipelines. Each session records discoveries, patterns, gotchas, and agent tuning notes for future reference.
+
+---
+
+`,
+}
+
+// Parses the flags supported by the sync entry point. Unknown flags are ignored
+// so that consumer tooling can pass extra arguments without breaking a sync.
+export function parseArgs(argv = [], env = process.env) {
+  const args = new Set(argv)
+
+  return {
+    forceOverwrite: args.has('--force'),
+    dryRun: args.has('--dry-run'),
+    // Pruning is opt-in and off by default: syncing never deletes anything unless
+    // the caller explicitly passes --prune. Even then, only manifest-tracked files
+    // whose package source has disappeared AND whose content is unmodified are removed.
+    prune: args.has('--prune'),
+    isVerbose: env.AI_WORKFLOW_VERBOSE === '1',
+  }
+}
+
+// Resolves every directory and flag the sync pass works with. Tests pass an
+// explicit packageRoot/consumerRoot; production derives the package root from
+// this module's location and the consumer root from INIT_CWD (npm) or cwd.
+export function createSyncContext(options = {}) {
+  const {
+    packageRoot,
+    consumerRoot,
+    manifestPath,
+    argv = process.argv.slice(2),
+    env = process.env,
+  } = options
+
+  const resolvedPackageRoot = packageRoot
+    ? resolve(packageRoot)
+    : defaultPackageRoot
+  const resolvedConsumerRoot = consumerRoot
+    ? resolve(consumerRoot)
+    : env.INIT_CWD
+      ? resolve(env.INIT_CWD)
+      : process.cwd()
+
+  const sourceAgentsDir = resolve(resolvedPackageRoot, '.agents')
+  const targetAgentsDir = resolve(resolvedConsumerRoot, '.agents')
+  const sourceOpenCodeDir = resolve(resolvedPackageRoot, '.opencode')
+  const sourceScriptsDir = resolve(resolvedPackageRoot, 'scripts')
+  const targetScriptsDir = resolve(resolvedConsumerRoot, 'scripts')
+
+  return {
+    packageRoot: resolvedPackageRoot,
+    consumerRoot: resolvedConsumerRoot,
+    sourceAgentsDir,
+    targetAgentsDir,
+    sourceOpenCodeDir,
+    sourceScriptsDir,
+    targetScriptsDir,
+    manifestPath: manifestPath
+      ? resolve(manifestPath)
+      : resolve(resolvedConsumerRoot, '.agents-sync-manifest.json'),
+    ...parseArgs(argv, env),
+    pruneChannels: {
+      agents: {
+        prefix: '',
+        packageDir: sourceAgentsDir,
+        consumerDir: targetAgentsDir,
+      },
+      opencode: {
+        prefix: '__opencode__/',
+        packageDir: sourceOpenCodeDir,
+        consumerDir: resolve(resolvedConsumerRoot, '.opencode'),
+      },
+      scripts: {
+        prefix: '__scripts__/',
+        packageDir: sourceScriptsDir,
+        consumerDir: targetScriptsDir,
+      },
+      root: {
+        prefix: '__root__/',
+        packageDir: resolvedPackageRoot,
+        consumerDir: resolvedConsumerRoot,
+      },
+    },
+  }
+}
+
+export function hashFile(filePath) {
   const contents = readFileSync(filePath)
   return createHash('sha256').update(contents).digest('hex')
 }
 
-function collectFiles(directory) {
+export function collectFiles(directory) {
   const entries = readdirSync(directory, { withFileTypes: true })
   const files = []
 
@@ -41,7 +210,7 @@ function collectFiles(directory) {
   return files
 }
 
-function readManifest() {
+export function readManifest(manifestPath) {
   if (!existsSync(manifestPath)) {
     return { version: 1, files: {} }
   }
@@ -62,7 +231,7 @@ function readManifest() {
   }
 }
 
-function writeManifest(manifest) {
+export function writeManifest(manifestPath, manifest) {
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
 }
 
@@ -70,7 +239,7 @@ function ensureParentDirectory(filePath) {
   mkdirSync(dirname(filePath), { recursive: true })
 }
 
-function syncFile(sourceFile, targetFile) {
+function syncFile(sourceFile, targetFile, dryRun) {
   if (dryRun) {
     return
   }
@@ -79,311 +248,436 @@ function syncFile(sourceFile, targetFile) {
   copyFileSync(sourceFile, targetFile)
 }
 
-const rootFiles = ['AGENTS.md', 'opencode.json', 'skills-lock.json']
+// A file is safe to overwrite when the manifest recorded a hash for it and the
+// consumer copy still matches that hash. Missing recorded hashes mean the file
+// is not tracked, so local edits are assumed and the copy is skipped.
+export function isUntouched(recordedHash, existingHash) {
+  return recordedHash !== null && existingHash === recordedHash
+}
 
-if (!existsSync(sourceAgentsDir)) {
-  console.warn('[ai-workflow-template] No .agents directory found to sync.')
-  process.exit(0)
+export function isPathInside(baseDir, candidatePath) {
+  const rel = relative(baseDir, candidatePath)
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)
 }
 
-const manifest = readManifest()
-const sourceFiles = collectFiles(sourceAgentsDir)
-let copied = 0
-let skipped = 0
-let added = 0
+// Resolves a manifest key to its package path (for the "still shipped?" check)
+// and its consumer path (the prune candidate). Returns null for keys that the
+// sync layer does not own, and for paths that escape their channel root.
+export function resolvePruneEntry(manifestKey, { pruneChannels, packageRoot }) {
+  let channel
+  let relativePath
+
+  if (manifestKey.startsWith('__opencode__/')) {
+    channel = pruneChannels.opencode
+    relativePath = manifestKey.slice(channel.prefix.length)
+    // Never touch paths the .opencode copy pass deliberately ignores (e.g. node_modules).
+    if (
+      openCodeExcluded.has(relativePath) ||
+      openCodeExcluded.has(relativePath.split('/')[0])
+    ) {
+      return null
+    }
+  } else if (manifestKey.startsWith('__scripts__/')) {
+    channel = pruneChannels.scripts
+    relativePath = manifestKey.slice(channel.prefix.length)
+  } else if (manifestKey.startsWith('__root__/')) {
+    channel = pruneChannels.root
+    relativePath = manifestKey.slice(channel.prefix.length)
+  } else if (manifestKey.startsWith('__')) {
+    // Unknown internal namespace — never prune (scaffold-only or future keys).
+    return null
+  } else {
+    channel = pruneChannels.agents
+    relativePath = manifestKey
+    if (excludedRelativePaths.has(relativePath)) {
+      return null
+    }
+  }
 
-/* ──  Sync .agents/ directory ────────────────────────────────── */
+  if (!relativePath) {
+    return null
+  }
 
-for (const sourceFile of sourceFiles) {
-  const relativePath = relative(sourceAgentsDir, sourceFile)
-  if (excludedRelativePaths.has(relativePath)) {
-    continue
+  const packagePaths = [resolve(channel.packageDir, relativePath)]
+  if (channel === pruneChannels.root && relativePath === 'opencode.json') {
+    // opencode.json is scaffolded from the example when the package does not ship
+    // it directly (auto-copy pass above). Either source keeps the file alive.
+    packagePaths.push(resolve(packageRoot, 'opencode.mcp.example.json'))
   }
 
-  const targetFile = resolve(targetAgentsDir, relativePath)
-  const sourceHash = hashFile(sourceFile)
-  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
-  const trackedKey = relativePath
-  const recordedHash = manifest.files[trackedKey] ?? null
-
-  if (!existsSync(targetFile)) {
-    if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    copied += 1
-    added += 1
-    continue
+  const consumerPath = resolve(channel.consumerDir, relativePath)
+  if (!isPathInside(channel.packageDir, packagePaths[0])) {
+    return null
+  }
+  if (!isPathInside(channel.consumerDir, consumerPath)) {
+    return null
   }
 
-  const isUntouched = recordedHash !== null && existingHash === recordedHash
+  return { packagePaths, consumerPath }
+}
 
-  if (forceOverwrite || isUntouched) {
-    if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    copied += 1
-    continue
+export function isRegularFile(filePath) {
+  try {
+    return statSync(filePath).isFile()
+  } catch {
+    return false
   }
-
-  skipped += 1
-  console.warn(`[ai-workflow-template] Skipped locally modified file: ${relativePath}`)
 }
 
-/* ──  Sync .opencode/ directory ────────────────────────────── */
+export function syncProject(context) {
+  const {
+    packageRoot,
+    consumerRoot,
+    sourceAgentsDir,
+    targetAgentsDir,
+    sourceOpenCodeDir,
+    sourceScriptsDir,
+    targetScriptsDir,
+    manifestPath,
+    forceOverwrite,
+    dryRun,
+    prune,
+    isVerbose,
+  } = context
+
+  if (!existsSync(sourceAgentsDir)) {
+    console.warn('[ai-workflow-template] No .agents directory found to sync.')
+    return { exitCode: 0, copied: 0, added: 0, scaffolded: 0, skipped: 0 }
+  }
 
-const sourceOpenCodeDir = resolve(packageRoot, '.opencode')
-const openCodeExcluded = new Set(['node_modules', 'package.json', 'package-lock.json', 'bun.lock', '.gitignore'])
+  const manifest = readManifest(manifestPath)
+  // Snapshot before syncing: prune only considers entries that existed at the start
+  // of this run, so files scaffolded/copied now are never candidates in the same run.
+  const preexistingManifestKeys = Object.keys(manifest.files)
+  const sourceFiles = collectFiles(sourceAgentsDir)
+  let copied = 0
+  let skipped = 0
+  let added = 0
 
-if (existsSync(sourceOpenCodeDir)) {
-  const openCodeFiles = collectFiles(sourceOpenCodeDir)
+  /* ──  Sync .agents/ directory ────────────────────────────────── */
 
-  for (const sourceFile of openCodeFiles) {
-    const relativePath = relative(sourceOpenCodeDir, sourceFile)
-    if (openCodeExcluded.has(relativePath) || openCodeExcluded.has(relativePath.split('/')[0])) {
+  for (const sourceFile of sourceFiles) {
+    const relativePath = relative(sourceAgentsDir, sourceFile)
+    if (excludedRelativePaths.has(relativePath)) {
       continue
     }
 
-    const targetFile = resolve(consumerRoot, '.opencode', relativePath)
+    const targetFile = resolve(targetAgentsDir, relativePath)
     const sourceHash = hashFile(sourceFile)
     const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
-    const trackedKey = `__opencode__/${relativePath}`
+    const trackedKey = relativePath
     const recordedHash = manifest.files[trackedKey] ?? null
 
     if (!existsSync(targetFile)) {
-      if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
-      syncFile(sourceFile, targetFile)
+      if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
+      syncFile(sourceFile, targetFile, dryRun)
       manifest.files[trackedKey] = sourceHash
       copied += 1
       added += 1
       continue
     }
 
-    const isUntouched = recordedHash !== null && existingHash === recordedHash
-
-    if (forceOverwrite || isUntouched) {
-      if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
-      syncFile(sourceFile, targetFile)
+    if (forceOverwrite || isUntouched(recordedHash, existingHash)) {
+      if (isVerbose) console.error(`  … syncing: .agents/${relativePath}`)
+      syncFile(sourceFile, targetFile, dryRun)
       manifest.files[trackedKey] = sourceHash
       copied += 1
       continue
     }
 
     skipped += 1
-    console.warn(`[ai-workflow-template] Skipped locally modified opencode file: ${relativePath}`)
+    console.warn(`[ai-workflow-template] Skipped locally modified file: ${relativePath}`)
   }
-}
-
-/* ──  Sync scripts/ directory ──────────────────────────────── */
-
-const scriptsToSync = [
-  'memory-cli.js',
-  'memory-index.js',
-  'bump-version.js',
-  'validate-memory-schema.js',
-  'vocab-sync.js',
-  'mcp-memory-server.js',
-  'mcp/playwright-mcp-launcher.js',
-  // Knowledgebase scripts
-  'knowledgebase-cli.js',
-  'knowledgebase-index.js',
-  'mcp-knowledgebase-server.js',
-  'knowledgebase-init.sql',
-]
-
-const sourceScriptsDir = resolve(packageRoot, 'scripts')
-const targetScriptsDir = resolve(consumerRoot, 'scripts')
-let scriptsCopied = 0
-let scriptsSkipped = 0
-
-for (const scriptRelPath of scriptsToSync) {
-  const sourceFile = resolve(sourceScriptsDir, scriptRelPath)
-  const targetFile = resolve(targetScriptsDir, scriptRelPath)
 
-  if (!existsSync(sourceFile)) {
-    continue
+  /* ──  Sync .opencode/ directory ────────────────────────────── */
+
+  if (existsSync(sourceOpenCodeDir)) {
+    const openCodeFiles = collectFiles(sourceOpenCodeDir)
+
+    for (const sourceFile of openCodeFiles) {
+      const relativePath = relative(sourceOpenCodeDir, sourceFile)
+      if (openCodeExcluded.has(relativePath) || openCodeExcluded.has(relativePath.split('/')[0])) {
+        continue
+      }
+
+      const targetFile = resolve(consumerRoot, '.opencode', relativePath)
+      const sourceHash = hashFile(sourceFile)
+      const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+      const trackedKey = `__opencode__/${relativePath}`
+      const recordedHash = manifest.files[trackedKey] ?? null
+
+      if (!existsSync(targetFile)) {
+        if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
+        syncFile(sourceFile, targetFile, dryRun)
+        manifest.files[trackedKey] = sourceHash
+        copied += 1
+        added += 1
+        continue
+      }
+
+      if (forceOverwrite || isUntouched(recordedHash, existingHash)) {
+        if (isVerbose) console.error(`  … syncing: .opencode/${relativePath}`)
+        syncFile(sourceFile, targetFile, dryRun)
+        manifest.files[trackedKey] = sourceHash
+        copied += 1
+        continue
+      }
+
+      skipped += 1
+      console.warn(`[ai-workflow-template] Skipped locally modified opencode file: ${relativePath}`)
+    }
   }
 
-  const sourceHash = hashFile(sourceFile)
-  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
-  const trackedKey = `__scripts__/${scriptRelPath}`
-  const recordedHash = manifest.files[trackedKey] ?? null
-
-  if (!existsSync(targetFile)) {
-    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    scriptsCopied += 1
-    copied += 1
-    added += 1
-    continue
-  }
+  /* ──  Sync scripts/ directory ──────────────────────────────── */
 
-  const isUntouched = recordedHash !== null && existingHash === recordedHash
+  let scriptsCopied = 0
+  let scriptsSkipped = 0
 
-  if (forceOverwrite || isUntouched) {
-    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    scriptsCopied += 1
-    copied += 1
-    continue
-  }
+  for (const scriptRelPath of scriptsToSync) {
+    const sourceFile = resolve(sourceScriptsDir, scriptRelPath)
+    const targetFile = resolve(targetScriptsDir, scriptRelPath)
 
-  scriptsSkipped += 1
-  skipped += 1
-  console.warn(`[ai-workflow-template] Skipped locally modified script file: scripts/${scriptRelPath}`)
-}
+    if (!existsSync(sourceFile)) {
+      continue
+    }
 
-for (const rootFile of rootFiles) {
-  const sourceFile = resolve(packageRoot, rootFile)
-  if (!existsSync(sourceFile)) {
-    continue
-  }
+    const sourceHash = hashFile(sourceFile)
+    const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+    const trackedKey = `__scripts__/${scriptRelPath}`
+    const recordedHash = manifest.files[trackedKey] ?? null
 
-  const targetFile = resolve(consumerRoot, rootFile)
-  const sourceHash = hashFile(sourceFile)
-  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
-  const trackedKey = `__root__/${rootFile}`
-  const recordedHash = manifest.files[trackedKey] ?? null
-
-  if (!existsSync(targetFile)) {
-    if (isVerbose) console.error(`  … syncing: ${rootFile}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    copied += 1
-    added += 1
-    continue
-  }
+    if (!existsSync(targetFile)) {
+      if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+      syncFile(sourceFile, targetFile, dryRun)
+      manifest.files[trackedKey] = sourceHash
+      scriptsCopied += 1
+      copied += 1
+      added += 1
+      continue
+    }
 
-  const isUntouched = recordedHash !== null && existingHash === recordedHash
+    if (forceOverwrite || isUntouched(recordedHash, existingHash)) {
+      if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+      syncFile(sourceFile, targetFile, dryRun)
+      manifest.files[trackedKey] = sourceHash
+      scriptsCopied += 1
+      copied += 1
+      continue
+    }
 
-  if (forceOverwrite || isUntouched) {
-    if (isVerbose) console.error(`  … syncing: ${rootFile}`)
-    syncFile(sourceFile, targetFile)
-    manifest.files[trackedKey] = sourceHash
-    copied += 1
-    continue
+    scriptsSkipped += 1
+    skipped += 1
+    console.warn(`[ai-workflow-template] Skipped locally modified script file: scripts/${scriptRelPath}`)
   }
 
-  skipped += 1
-  console.warn(`[ai-workflow-template] Skipped locally modified root file: ${rootFile}`)
-}
-
-/* ──  Scaffold memory-bank/ directory ──────────────────────────── */
+  /* ──  Sync root files ────────────────────────────────────────── */
 
-const memoryBankStubs = {
-  'projectbrief.md': `# projectbrief
-
-> Foundation document — defines core requirements and goals.
-
-- **Purpose**: {{describe project purpose}}
-- **Goals**: {{list project goals}}
-- **Scope**: {{define scope}}
-`,
-  'productContext.md': `# productContext
+  for (const rootFile of rootFiles) {
+    const sourceFile = resolve(packageRoot, rootFile)
+    if (!existsSync(sourceFile)) {
+      continue
+    }
 
-> Why this project exists and what problems it solves.
+    const targetFile = resolve(consumerRoot, rootFile)
+    const sourceHash = hashFile(sourceFile)
+    const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+    const trackedKey = `__root__/${rootFile}`
+    const recordedHash = manifest.files[trackedKey] ?? null
 
-- **Problem**: {{describe the problem}}
-- **Solution**: {{describe the solution}}
-- **User Experience**: {{describe UX goals}}
-`,
-  'activeContext.md': `# activeContext
+    if (!existsSync(targetFile)) {
+      if (isVerbose) console.error(`  … syncing: ${rootFile}`)
+      syncFile(sourceFile, targetFile, dryRun)
+      manifest.files[trackedKey] = sourceHash
+      copied += 1
+      added += 1
+      continue
+    }
 
-> Current work focus, recent changes, next steps.
+    if (forceOverwrite || isUntouched(recordedHash, existingHash)) {
+      if (isVerbose) console.error(`  … syncing: ${rootFile}`)
+      syncFile(sourceFile, targetFile, dryRun)
+      manifest.files[trackedKey] = sourceHash
+      copied += 1
+      continue
+    }
 
-- **Current Focus**: {{current task or goal}}
-- **Recent Changes**: {{list of recent changes}}
-- **Next Steps**: {{next actions}}
-`,
-  'systemPatterns.md': `# systemPatterns
+    skipped += 1
+    console.warn(`[ai-workflow-template] Skipped locally modified root file: ${rootFile}`)
+  }
 
-> Architecture, key decisions, design patterns.
+  /* ──  Scaffold memory-bank/ directory ──────────────────────────── */
 
-- **Architecture**: {{describe architecture}}
-- **Key Decisions**: {{list key technical decisions}}
-- **Patterns**: {{list design patterns in use}}
-`,
-  'techContext.md': `# techContext
+  const memoryBankDir = resolve(consumerRoot, 'memory-bank')
+  let scaffolded = 0
 
-> Technologies, setup, constraints, dependencies.
+  for (const [fileName, fileContent] of Object.entries(memoryBankStubs)) {
+    const targetFile = resolve(memoryBankDir, fileName)
+    const trackedKey = `__memory-bank__/${fileName}`
 
-- **Stack**: {{list technologies}}
-- **Setup**: {{describe dev setup}}
-- **Constraints**: {{list technical constraints}}
-`,
-  'progress.md': `# progress
+    if (existsSync(targetFile)) {
+      continue
+    }
 
-> What works, what's left, current status.
+    ensureParentDirectory(targetFile)
+    if (isVerbose) console.error(`  … scaffolding: memory-bank/${fileName}`)
+    writeFileSync(targetFile, fileContent, 'utf8')
+    manifest.files[trackedKey] = hashFile(targetFile)
+    scaffolded += 1
+  }
 
-- **Working**: {{what's implemented and working}}
-- **To Build**: {{what remains}}
-- **Status**: {{overall project status}}
-- **Known Issues**: {{list known issues}}
-`,
-}
+  /* ──  Scaffold .agents/instructions/ directory ───────────────── */
 
-const memoryBankDir = resolve(consumerRoot, 'memory-bank')
-let scaffolded = 0
+  for (const [fileName, fileContent] of Object.entries(agentInstructionsStubs)) {
+    const targetFile = resolve(targetAgentsDir, 'instructions', fileName)
+    const trackedKey = `__agents-instructions__/${fileName}`
 
-for (const [fileName, fileContent] of Object.entries(memoryBankStubs)) {
-  const targetFile = resolve(memoryBankDir, fileName)
-  const trackedKey = `__memory-bank__/${fileName}`
+    if (existsSync(targetFile)) {
+      continue
+    }
 
-  if (existsSync(targetFile)) {
-    continue
+    ensureParentDirectory(targetFile)
+    if (isVerbose) console.error(`  … scaffolding: .agents/instructions/${fileName}`)
+    writeFileSync(targetFile, fileContent, 'utf8')
+    manifest.files[trackedKey] = hashFile(targetFile)
+    scaffolded += 1
   }
 
-  ensureParentDirectory(targetFile)
-  if (isVerbose) console.error(`  … scaffolding: memory-bank/${fileName}`)
-  writeFileSync(targetFile, fileContent, 'utf8')
-  manifest.files[trackedKey] = hashFile(targetFile)
-  scaffolded += 1
-}
+  /* ──  Auto-copy opencode.mcp.example.json → opencode.json ────── */
 
-/* ──  Scaffold .agents/instructions/ directory ───────────────── */
-
-const agentInstructionsStubs = {
-  'learned-knowledge.instructions.md': `# Learned Knowledge
+  const exampleMcpFile = resolve(packageRoot, 'opencode.mcp.example.json')
+  const targetMcpFile = resolve(consumerRoot, 'opencode.json')
+  const mcpTrackedKey = '__root__/opencode.json'
 
-Cross-session knowledge accumulated by agent pipelines. Each session records discoveries, patterns, gotchas, and agent tuning notes for future reference.
+  if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
+    if (isVerbose) console.error('  … scaffolding: opencode.json from example')
+    copyFileSync(exampleMcpFile, targetMcpFile)
+    manifest.files[mcpTrackedKey] = hashFile(targetMcpFile)
+    scaffolded += 1
+  }
 
----
+  /* ──  Prune stale files (opt-in via --prune) ─────────────────── */
+
+  // Every prunable manifest namespace maps onto the same package/consumer roots
+  // used by the copy passes above. Scaffold-only namespaces (__memory-bank__,
+  // __agents-instructions__) have no package source and are therefore never
+  // prunable — their keys fall through to the "unknown namespace" guard below.
+  let pruned = 0
+  let pruneSkipped = 0
+
+  if (prune) {
+    for (const manifestKey of preexistingManifestKeys) {
+      const entry = resolvePruneEntry(manifestKey, context)
+      if (!entry) {
+        continue
+      }
+
+      // Still shipped by the package? Package-owned — never prunable (CON-05, D-10).
+      if (entry.packagePaths.some((packagePath) => existsSync(packagePath))) {
+        continue
+      }
+
+      const displayPath = relative(consumerRoot, entry.consumerPath)
+
+      // Consumer file is already gone: drop the stale bookkeeping entry, delete nothing.
+      if (!existsSync(entry.consumerPath)) {
+        if (!dryRun) {
+          delete manifest.files[manifestKey]
+        }
+        continue
+      }
+
+      // Files only — never delete a directory, symlink target, or unreadable path.
+      if (!isRegularFile(entry.consumerPath)) {
+        continue
+      }
+
+      const recordedHash = manifest.files[manifestKey]
+      if (typeof recordedHash !== 'string' || recordedHash.length === 0) {
+        pruneSkipped += 1
+        console.warn(`[ai-workflow-template] Skipped pruning untracked file: ${displayPath}`)
+        continue
+      }
+
+      // Locally modified (or unverifiable): keep the file AND its manifest entry so
+      // a later run can still see it. Deleting here would destroy user work.
+      if (hashFile(entry.consumerPath) !== recordedHash) {
+        pruneSkipped += 1
+        console.warn(`[ai-workflow-template] Skipped pruning locally modified file: ${displayPath}`)
+        continue
+      }
+
+      pruned += 1
+      if (dryRun) {
+        console.log(`[ai-workflow-template] Would prune: ${displayPath}`)
+        continue
+      }
+
+      rmSync(entry.consumerPath, { force: true })
+      delete manifest.files[manifestKey]
+
+      // Directories are never deleted. Report an emptied one and leave it in place.
+      const parentDir = dirname(entry.consumerPath)
+      if (existsSync(parentDir) && readdirSync(parentDir).length === 0) {
+        console.log(
+          `[ai-workflow-template] Left empty directory in place: ${relative(consumerRoot, parentDir)}`,
+        )
+      }
+    }
 
-`,
-}
+    const summaryVerb = dryRun ? 'Would prune' : 'Pruned'
+    console.log(
+      `[ai-workflow-template] ${summaryVerb} ${pruned} stale file(s); skipped ${pruneSkipped} locally modified.`,
+    )
+  }
 
-for (const [fileName, fileContent] of Object.entries(agentInstructionsStubs)) {
-  const targetFile = resolve(targetAgentsDir, 'instructions', fileName)
-  const trackedKey = `__agents-instructions__/${fileName}`
+  if (!dryRun) {
+    writeManifest(manifestPath, manifest)
+  }
 
-  if (existsSync(targetFile)) {
-    continue
+  const modeLabel = forceOverwrite ? 'force' : dryRun ? 'dry-run' : 'safe'
+  console.log(`[ai-workflow-template] Synced ${copied} files (${added} new), scaffolded ${scaffolded} files, skipped ${skipped} modified files. Mode: ${modeLabel}.`)
+
+  return {
+    exitCode: 0,
+    copied,
+    added,
+    skipped,
+    scaffolded,
+    pruned,
+    pruneSkipped,
+    scriptsCopied,
+    scriptsSkipped,
   }
+}
 
-  ensureParentDirectory(targetFile)
-  if (isVerbose) console.error(`  … scaffolding: .agents/instructions/${fileName}`)
-  writeFileSync(targetFile, fileContent, 'utf8')
-  manifest.files[trackedKey] = hashFile(targetFile)
-  scaffolded += 1
+// Runs a complete sync pass. Accepts explicit roots/argv/env so the module can
+// be exercised in-process by tests without touching the real repository.
+export function runSync(options = {}) {
+  return syncProject(createSyncContext(options))
 }
 
-/* ──  Auto-copy opencode.mcp.example.json → opencode.json ────── */
+// True only when this module is the script Node was asked to execute. This keeps
+// `node scripts/sync.js` working while making the module safe to import in tests.
+// Compares symlink-resolved paths because macOS reports /var scripts as
+// /private/var through import.meta.url.
+export function isEntryPoint(moduleUrl = import.meta.url, argv1 = process.argv[1]) {
+  if (!argv1) {
+    return false
+  }
 
-const exampleMcpFile = resolve(packageRoot, 'opencode.mcp.example.json')
-const targetMcpFile = resolve(consumerRoot, 'opencode.json')
-const mcpTrackedKey = '__root__/opencode.json'
+  const modulePath = fileURLToPath(moduleUrl)
+  const argvPath = resolve(argv1)
+  if (modulePath === argvPath) {
+    return true
+  }
 
-if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
-  if (isVerbose) console.error('  … scaffolding: opencode.json from example')
-  copyFileSync(exampleMcpFile, targetMcpFile)
-  manifest.files[mcpTrackedKey] = hashFile(targetMcpFile)
-  scaffolded += 1
+  try {
+    return realpathSync(modulePath) === realpathSync(argvPath)
+  } catch {
+    return false
+  }
 }
 
-if (!dryRun) {
-  writeManifest(manifest)
+if (isEntryPoint()) {
+  runSync()
 }
-
-const modeLabel = forceOverwrite ? 'force' : dryRun ? 'dry-run' : 'safe'
-console.log(`[ai-workflow-template] Synced ${copied} files (${added} new), scaffolded ${scaffolded} files, skipped ${skipped} modified files. Mode: ${modeLabel}.`)