@abarcenas/ai-workflow-template 1.33.0 → 1.38.0

package/scripts/setup/knowledgebase.test.js

@@ -0,0 +1,248 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// knowledgebase.test.js — Unit tests for the knowledgebase registration module
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Tests registerKnowledgebase() from knowledgebase.js — the Phase 6 setup
+// module that registers the consumer project in the centralized knowledgebase.
+//
+// Covered scenarios (6 tests per T17 requirements):
+//   1. skipKnowledgebase flag   → early return with action='skipped'
+//   2. No DATABASE_URL          → graceful skip with warning message
+//   3. Missing project name     → graceful skip
+//   4. Successful index         → spawn exits 0, parses chunk counts
+//   5. CLI failure             → non-zero exit, action='failed'
+//   6. Spawn error event       → ENOENT, graceful handling
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+
+// ── Mocks (vitest hoists these to the top of the module) ──────────────────
+
+vi.mock('child_process', () => ({
+  spawn: vi.fn(),
+}))
+
+vi.mock('./ui.js', () => ({
+  verbose: vi.fn(),
+}))
+
+vi.mock('./utils.js', () => ({
+  resolvePackageRoot: vi.fn(() => '/fake/package/root'),
+  logInfo: vi.fn(),
+  logWarn: vi.fn(),
+  logError: vi.fn(),
+}))
+
+import { spawn } from 'child_process'
+import { registerKnowledgebase } from './knowledgebase.js'
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Creates a mock child process that mimics a spawned Node.js script.
+ *
+ * Supports two modes controlled by `emitError`:
+ *   - false (default): registers stdout/stderr 'data' handlers and a 'close'
+ *     handler, then fires them asynchronously on a microtask so the calling
+ *     code's event listeners are registered before the events fire.
+ *   - true: registers and fires an 'error' handler instead (for ENOENT etc.)
+ *
+ * @param {object}   opts
+ * @param {number}   [opts.exitCode=0]     - Exit code for the 'close' event
+ * @param {string}   [opts.stdoutData='']   - Data emitted via stdout 'data'
+ * @param {string}   [opts.stderrData='']   - Data emitted via stderr 'data'
+ * @param {boolean}  [opts.emitError=false] - If true, emit 'error' instead
+ * @returns {object} Mock child process with .stdout.on, .stderr.on, .on
+ */
+function createMockChild({
+  exitCode = 0,
+  stdoutData = '',
+  stderrData = '',
+  emitError = false,
+} = {}) {
+  const stdoutHandlers = []
+  const stderrHandlers = []
+  let closeHandler = null
+  let errorHandler = null
+
+  const child = {
+    stdout: {
+      on: (event, handler) => {
+        if (event === 'data') stdoutHandlers.push(handler)
+      },
+    },
+    stderr: {
+      on: (event, handler) => {
+        if (event === 'data') stderrHandlers.push(handler)
+      },
+    },
+    on: (event, handler) => {
+      if (event === 'close') closeHandler = handler
+      if (event === 'error') errorHandler = handler
+    },
+  }
+
+  // Fire events on a microtask so handlers are registered first
+  Promise.resolve().then(() => {
+    if (emitError) {
+      if (errorHandler) {
+        errorHandler(new Error('ENOENT: no such file or directory'))
+      }
+    } else {
+      if (stdoutData) {
+        stdoutHandlers.forEach((h) => h(Buffer.from(stdoutData)))
+      }
+      if (stderrData) {
+        stderrHandlers.forEach((h) => h(Buffer.from(stderrData)))
+      }
+      if (closeHandler) closeHandler(exitCode)
+    }
+  })
+
+  return child
+}
+
+/**
+ * Builds a minimal context object accepted by registerKnowledgebase().
+ *
+ * Defaults provide a valid DATABASE_URL and consumerPackageJson.name so that
+ * tests can focus on one axis of variation at a time without repeating
+ * setup code.
+ *
+ * @param {object} [overrides] - Properties to override on the default context.
+ * @returns {object} Context object.
+ */
+function makeContext(overrides = {}) {
+  return {
+    flags: {},
+    verbose: false,
+    consumerRoot: '/fake/consumer',
+    consumerPackageJson: { name: 'test-consumer' },
+    ...overrides,
+  }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe('registerKnowledgebase', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Provide a valid DATABASE_URL by default so only tests that explicitly
+    // delete it exercise the missing-URL path.
+    process.env.DATABASE_URL = 'postgres://localhost:5432/knowledgebase'
+  })
+
+  afterEach(() => {
+    delete process.env.DATABASE_URL
+  })
+
+  // ── 1. Skip flag ───────────────────────────────────────────────────────
+
+  it('returns action="skipped" when flags.skipKnowledgebase is true', async () => {
+    const ctx = makeContext({ flags: { skipKnowledgebase: true } })
+
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result).toEqual({
+      action: 'skipped',
+      message: expect.stringContaining('skip-knowledgebase'),
+    })
+    // No child process should be spawned when the flag short-circuits
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
+  // ── 2. Missing DATABASE_URL ───────────────────────────────────────────
+
+  it('returns action="skipped" with warning when DATABASE_URL is not set', async () => {
+    delete process.env.DATABASE_URL
+    const ctx = makeContext()
+
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result).toEqual({
+      action: 'skipped',
+      message: expect.stringContaining('DATABASE_URL'),
+    })
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
+  // ── 3. Missing project name ───────────────────────────────────────────
+
+  it('returns action="skipped" when consumerPackageJson has no name field', async () => {
+    const ctx = makeContext({ consumerPackageJson: {} })
+
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result).toEqual({
+      action: 'skipped',
+      message: expect.stringContaining('project name'),
+    })
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
+  // ── 4. Successful index ───────────────────────────────────────────────
+
+  it('returns action="indexed" with parsed chunk counts on successful spawn', async () => {
+    vi.mocked(spawn).mockImplementation(() =>
+      createMockChild({
+        exitCode: 0,
+        stdoutData: [
+          '[knowledgebase]',
+          'Indexed 5 new, updated 3, skipped 2 chunks',
+          'from project "test-consumer"',
+        ].join(' '),
+      }),
+    )
+
+    const ctx = makeContext()
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result).toEqual({
+      action: 'indexed',
+      message: expect.stringContaining('8 chunks indexed'),
+      chunks_indexed: 8,   // 5 new + 3 updated
+      chunks_skipped: 2,
+    })
+    expect(spawn).toHaveBeenCalledTimes(1)
+  })
+
+  // ── 5. CLI failure (non-zero exit) ────────────────────────────────────
+
+  it('returns action="failed" when the CLI exits with a non-zero code', async () => {
+    vi.mocked(spawn).mockImplementation(() =>
+      createMockChild({
+        exitCode: 1,
+        stderrData: 'Error: connection refused',
+      }),
+    )
+
+    const ctx = makeContext()
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result).toEqual({
+      action: 'failed',
+      message: expect.stringContaining('exit code 1'),
+    })
+    expect(spawn).toHaveBeenCalledTimes(1)
+  })
+
+  // ── 6. Spawn error event (ENOENT) ─────────────────────────────────────
+
+  it('gracefully handles spawn error (ENOENT) returning action="failed"', async () => {
+    vi.mocked(spawn).mockImplementation(() =>
+      createMockChild({ emitError: true }),
+    )
+
+    const ctx = makeContext()
+
+    // The function must not throw — the spawn 'error' event resolves the
+    // internal promise with success=false, and registerKnowledgebase
+    // converts that into a graceful 'failed' result.
+    const result = await registerKnowledgebase(ctx)
+
+    expect(result.action).toBe('failed')
+    expect(result.message).toContain('exit code -1')
+    expect(result.message).toContain('ENOENT')
+    expect(spawn).toHaveBeenCalledTimes(1)
+  })
+})

package/scripts/sync.js

@@ -9,7 +9,9 @@ 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 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')
@@ -77,7 +79,7 @@ function syncFile(sourceFile, targetFile) {
   copyFileSync(sourceFile, targetFile)
 }
 
-const rootFiles = ['AGENTS.md', 'opencode.mcp.example.json', 'skills-lock.json']
+const rootFiles = ['AGENTS.md', 'opencode.json', 'skills-lock.json']
 
 if (!existsSync(sourceAgentsDir)) {
   console.warn('[ai-workflow-template] No .agents directory found to sync.')
@@ -171,6 +173,66 @@ if (existsSync(sourceOpenCodeDir)) {
   }
 }
 
+/* ──  Sync scripts/ directory ──────────────────────────────── */
+
+const scriptsToSync = [
+  'memory-cli.js',
+  'memory-index.js',
+  'bump-version.js',
+  'validate-memory-schema.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
+  }
+
+  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
+  }
+
+  const isUntouched = recordedHash !== null && existingHash === recordedHash
+
+  if (forceOverwrite || isUntouched) {
+    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    scriptsCopied += 1
+    copied += 1
+    continue
+  }
+
+  scriptsSkipped += 1
+  skipped += 1
+  console.warn(`[ai-workflow-template] Skipped locally modified script file: scripts/${scriptRelPath}`)
+}
+
 for (const rootFile of rootFiles) {
   const sourceFile = resolve(packageRoot, rootFile)
   if (!existsSync(sourceFile)) {
@@ -278,14 +340,41 @@ for (const [fileName, fileContent] of Object.entries(memoryBankStubs)) {
   scaffolded += 1
 }
 
-/* ──  Auto-copy opencode.mcp.json from example ────────────────── */
+/* ──  Scaffold .agents/instructions/ directory ───────────────── */
+
+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.
+
+---
+
+`,
+}
+
+for (const [fileName, fileContent] of Object.entries(agentInstructionsStubs)) {
+  const targetFile = resolve(targetAgentsDir, 'instructions', fileName)
+  const trackedKey = `__agents-instructions__/${fileName}`
+
+  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
+}
+
+/* ──  Auto-copy opencode.mcp.example.json → opencode.json ────── */
 
 const exampleMcpFile = resolve(packageRoot, 'opencode.mcp.example.json')
-const targetMcpFile = resolve(consumerRoot, 'opencode.mcp.json')
-const mcpTrackedKey = '__root__/opencode.mcp.json'
+const targetMcpFile = resolve(consumerRoot, 'opencode.json')
+const mcpTrackedKey = '__root__/opencode.json'
 
 if (existsSync(exampleMcpFile) && !existsSync(targetMcpFile)) {
-  if (isVerbose) console.error('  … scaffolding: opencode.mcp.json from example')
+  if (isVerbose) console.error('  … scaffolding: opencode.json from example')
   copyFileSync(exampleMcpFile, targetMcpFile)
   manifest.files[mcpTrackedKey] = hashFile(targetMcpFile)
   scaffolded += 1

package/scripts/sync.test.js

@@ -1,4 +1,40 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, afterAll } from 'vitest'
+import { spawnSync } from 'child_process'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  mkdtempSync,
+  statSync,
+} from 'fs'
+import { join, dirname } from 'path'
+import { tmpdir } from 'os'
+
+const projectRoot = process.cwd()
+const tempDirs = []
+
+function createTempDir() {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sync-test-'))
+  tempDirs.push(tmpDir)
+  return tmpDir
+}
+
+function runSync(tempDir, args = []) {
+  return spawnSync('node', ['scripts/sync.js', ...args], {
+    cwd: projectRoot,
+    env: { ...process.env, INIT_CWD: tempDir },
+    encoding: 'utf8',
+  })
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
 
 describe('sync utility functions', () => {
   it('should validate basic assertions work', () => {
@@ -10,3 +46,143 @@ describe('sync utility functions', () => {
     expect(result).toBe('ai workflow template')
   })
 })
+
+describe('__scripts__ sync behavior', () => {
+  const scriptsToSync = [
+    'memory-cli.js',
+    'memory-index.js',
+    'bump-version.js',
+    'validate-memory-schema.js',
+    'mcp-memory-server.js',
+    'mcp/playwright-mcp-launcher.js',
+  ]
+
+  it('should copy scripts when they do not exist in consumer project', () => {
+    const tempDir = createTempDir()
+
+    // Create a manifest with __scripts__ entries (initial tracking)
+    const manifest = {
+      version: 1,
+      files: Object.fromEntries(
+        scriptsToSync.map((s) => [`__scripts__/${s}`, null]),
+      ),
+    }
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify(manifest, null, 2),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify all 6 script files were created in the consumer's scripts/ dir
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      expect(
+        existsSync(targetFile),
+        `Expected scripts/${script} to exist`,
+      ).toBe(true)
+    }
+  })
+
+  it('should skip scripts that exist in target without manifest tracking', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with files matching source content (same hash)
+    // but create a manifest that has NO __scripts__ entries
+    for (const script of scriptsToSync) {
+      const sourceFile = join(sourceScriptsDir, script)
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      copyFileSync(sourceFile, targetFile)
+    }
+
+    // Empty manifest — no __scripts__ keys → isUntouched = false for all
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    // Record mtimes before sync
+    const mtimesBefore = {}
+    for (const script of scriptsToSync) {
+      mtimesBefore[script] = statSync(
+        join(tempDir, 'scripts', script),
+      ).mtimeMs
+    }
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify mtimes are unchanged (files were NOT overwritten)
+    for (const script of scriptsToSync) {
+      expect(statSync(join(tempDir, 'scripts', script)).mtimeMs).toBe(
+        mtimesBefore[script],
+      )
+    }
+  })
+
+  it('should force overwrite all scripts with --force', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with dummy content (different from source)
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      writeFileSync(targetFile, `// modified ${script}`)
+    }
+
+    const result = runSync(tempDir, ['--force'])
+    expect(result.status).toBe(0)
+
+    // Verify all 6 files were overwritten with source content
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      const sourceFile = join(sourceScriptsDir, script)
+      expect(existsSync(targetFile)).toBe(true)
+      expect(readFileSync(targetFile, 'utf8')).toBe(
+        readFileSync(sourceFile, 'utf8'),
+      )
+    }
+  })
+
+  it('should show scripts in --dry-run output but not write files', () => {
+    const tempDir = createTempDir()
+
+    const result = runSync(tempDir, ['--dry-run'])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('dry-run')
+
+    // Verify no script files were written to disk
+    for (const script of scriptsToSync) {
+      expect(existsSync(join(tempDir, 'scripts', script))).toBe(false)
+    }
+  })
+
+  it('should track new manifest entries after sync', () => {
+    const tempDir = createTempDir()
+
+    // Create empty manifest
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Read back the updated manifest
+    const updatedManifest = JSON.parse(
+      readFileSync(join(tempDir, '.agents-sync-manifest.json'), 'utf8'),
+    )
+
+    // Verify all 6 __scripts__ entries are tracked with valid SHA-256 hashes
+    for (const script of scriptsToSync) {
+      const key = `__scripts__/${script}`
+      expect(updatedManifest.files[key]).toBeDefined()
+      expect(updatedManifest.files[key]).toMatch(/^[a-f0-9]{64}$/)
+    }
+  })
+})