@abarcenas/ai-workflow-template 1.34.0 → 1.39.0

package/scripts/setup/index.js

@@ -11,8 +11,9 @@
 //   6. Phase 3 — Prepare (configure consumer package.json prepare script)
 //   7. Phase 4 — Husky Init (generate .husky/_/ shims, unless --skip-hooks)
 //   8. Phase 5 — Sync (spawn sync.js + normalize-memory.js, unless --skip-sync)
-//   9. Render summary table via ui.summary()
-//  10. Determine exit code and return it
+//   9. Phase 6 — Knowledgebase (register with centralized knowledgebase, unless --skip-knowledgebase)
+//  10. Render summary table via ui.summary()
+//  11. Determine exit code and return it
 //
 // Each phase is wrapped in try/catch. Only discovery failure is fatal.
 // All other phase errors are logged and the pipeline continues (REQ-04).
@@ -38,6 +39,7 @@ import { installHooks } from './hooks.js'
 import { handlePrepare } from './prepare.js'
 import { initHusky } from './husky-init.js'
 import { runSyncPhase } from './sync-phase.js'
+import { registerKnowledgebase } from './knowledgebase.js'
 
 // ── Package version (lazy, cached) ───────────────────────────────────────────
 
@@ -85,6 +87,7 @@ function actionStatus(action) {
     case 'dry-run':
     case 'overwritten':
     case 'merged':
+    case 'indexed':
       return 'success'
     // These actions indicate the phase was intentionally skipped or
     // only partially completed — not an error but worth noting
@@ -331,6 +334,30 @@ export async function main(argv) {
     }
   }
 
+  // ═════════════════════════════════════════════════════════════════════════
+  // Phase 6 — Knowledgebase (unless --skip-knowledgebase)
+  // ═════════════════════════════════════════════════════════════════════════
+  if (!flags.skipKnowledgebase) {
+    section('Phase 6: Knowledgebase')
+
+    try {
+      const kbResult = await registerKnowledgebase(context)
+      context.kbResult = kbResult
+      phases.push({
+        phase: 'knowledgebase',
+        status: actionStatus(kbResult.action),
+        message: kbResult.message,
+      })
+    } catch (err) {
+      stepWarn(`Knowledgebase registration skipped: ${err.message}`)
+      phases.push({
+        phase: 'knowledgebase',
+        status: 'warn',
+        message: `Skipped \u2014 ${err.message}`,
+      })
+    }
+  }
+
   // ═════════════════════════════════════════════════════════════════════════
   // Summary
   // ═════════════════════════════════════════════════════════════════════════

package/scripts/setup/index.test.js

@@ -72,6 +72,10 @@ vi.mock('./sync-phase.js', () => ({
   runSyncPhase: vi.fn(),
 }))
 
+vi.mock('./knowledgebase.js', () => ({
+  registerKnowledgebase: vi.fn(),
+}))
+
 // ═════════════════════════════════════════════════════════════════════════════
 // Imports — these resolve to the mocked modules above
 // ═════════════════════════════════════════════════════════════════════════════
@@ -93,6 +97,7 @@ import { installHooks } from './hooks.js'
 import { handlePrepare } from './prepare.js'
 import { initHusky } from './husky-init.js'
 import { runSyncPhase } from './sync-phase.js'
+import { registerKnowledgebase } from './knowledgebase.js'
 import { EXIT_CODES } from './constants.js'
 
 // ═════════════════════════════════════════════════════════════════════════════
@@ -110,6 +115,7 @@ const defaultFlags = {
   skipHooks: false,
   skipPrepare: false,
   skipSync: false,
+  skipKnowledgebase: false,
   help: false,
   version: false,
   quiet: false,
@@ -190,6 +196,12 @@ describe('main() — setup orchestrator', () => {
     handlePrepare.mockResolvedValue(defaultPrepareResult)
     initHusky.mockResolvedValue(defaultHuskyResult)
     runSyncPhase.mockResolvedValue(defaultSyncResult)
+    registerKnowledgebase.mockResolvedValue({
+      action: 'indexed',
+      message: 'Registered "test-consumer" — 5 chunks indexed, 0 skipped',
+      chunks_indexed: 5,
+      chunks_skipped: 0,
+    })
 
     // Spy on console.log for --version tests
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
@@ -214,6 +226,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).not.toHaveBeenCalled()
     expect(initHusky).not.toHaveBeenCalled()
     expect(runSyncPhase).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
     // No header or summary for early-exit flags
     expect(header).not.toHaveBeenCalled()
     expect(summary).not.toHaveBeenCalled()
@@ -231,6 +244,7 @@ describe('main() — setup orchestrator', () => {
     expect(discover).not.toHaveBeenCalled()
     expect(installHooks).not.toHaveBeenCalled()
     expect(header).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
   })
 
   // ── 3. --version flag ────────────────────────────────────────────────────
@@ -246,6 +260,7 @@ describe('main() — setup orchestrator', () => {
     // Early exit means no pipeline phases run
     expect(discover).not.toHaveBeenCalled()
     expect(help).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
   })
 
   // ── 4. -v short flag ─────────────────────────────────────────────────────
@@ -259,6 +274,7 @@ describe('main() — setup orchestrator', () => {
     expect(logSpy).toHaveBeenCalled()
     expect(logSpy.mock.calls[0][0]).toEqual(expect.any(String))
     expect(discover).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
   })
 
   // ── 5. --dry-run flag ────────────────────────────────────────────────────
@@ -287,6 +303,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
     // Header and summary shown (not quiet)
     expect(header).toHaveBeenCalledTimes(1)
     expect(summary).toHaveBeenCalledTimes(1)
@@ -307,6 +324,7 @@ describe('main() — setup orchestrator', () => {
     expect(discover).toHaveBeenCalledTimes(1)
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 7. --skip-sync flag ──────────────────────────────────────────────────
@@ -323,6 +341,7 @@ describe('main() — setup orchestrator', () => {
     expect(installHooks).toHaveBeenCalledTimes(1)
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 8. --skip-prepare flag ───────────────────────────────────────────────
@@ -339,6 +358,7 @@ describe('main() — setup orchestrator', () => {
     expect(installHooks).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 9. Unknown flag ──────────────────────────────────────────────────────
@@ -362,7 +382,7 @@ describe('main() — setup orchestrator', () => {
 
   // ── 10. Full pipeline (default flags) ────────────────────────────────────
 
-  it('full pipeline: all 5 phases called in order, exits 0', async () => {
+  it('full pipeline: all 6 phases called in order, exits 0', async () => {
     const code = await main([])
 
     expect(code).toBe(EXIT_CODES.SUCCESS)
@@ -372,6 +392,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
     // Header displayed
     expect(header).toHaveBeenCalledTimes(1)
     // Summary displayed
@@ -398,6 +419,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).not.toHaveBeenCalled()
     expect(initHusky).not.toHaveBeenCalled()
     expect(runSyncPhase).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
     // Summary is shown even on fatal (not quiet mode)
     expect(summary).toHaveBeenCalledTimes(1)
   })
@@ -419,6 +441,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
     // Summary is shown
     expect(summary).toHaveBeenCalledTimes(1)
   })
@@ -445,6 +468,7 @@ describe('main() — setup orchestrator', () => {
     expect(discover).toHaveBeenCalledTimes(1)
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
     // Summary shown
     expect(summary).toHaveBeenCalledTimes(1)
   })
@@ -463,6 +487,7 @@ describe('main() — setup orchestrator', () => {
     expect(ciModeBanner).toHaveBeenCalledTimes(1)
     // CI mode doesn't skip phases (that's done by --skip-hooks)
     expect(discover).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   it('CI mode: ciModeBanner NOT shown in quiet mode even when isCI is true', async () => {
@@ -496,6 +521,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 16. Multiple skips combined ─────────────────────────────────────────
@@ -520,6 +546,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).not.toHaveBeenCalled()
     expect(initHusky).not.toHaveBeenCalled()
     expect(runSyncPhase).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 17. Verify parseCliArgs receives the argv ───────────────────────────
@@ -536,6 +563,7 @@ describe('main() — setup orchestrator', () => {
     await main(argv)
 
     expect(parseCliArgs).toHaveBeenCalledWith(argv)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 18. Discovery context is passed to each phase ───────────────────────
@@ -556,6 +584,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledWith(ctx)
     expect(initHusky).toHaveBeenCalledWith(ctx)
     expect(runSyncPhase).toHaveBeenCalledWith(ctx)
+    expect(registerKnowledgebase).toHaveBeenCalledWith(ctx)
   })
 
   // ── 19a. --verbose flag passthrough to Context ──────────────────────────
@@ -577,6 +606,7 @@ describe('main() — setup orchestrator', () => {
     expect(handlePrepare).toHaveBeenCalledWith(ctx)
     expect(initHusky).toHaveBeenCalledWith(ctx)
     expect(runSyncPhase).toHaveBeenCalledWith(ctx)
+    expect(registerKnowledgebase).toHaveBeenCalledWith(ctx)
     // Normal pipeline — header and summary shown
     expect(header).toHaveBeenCalledTimes(1)
     expect(summary).toHaveBeenCalledTimes(1)
@@ -591,6 +621,7 @@ describe('main() — setup orchestrator', () => {
     await main(['--dry-run'])
 
     expect(discover).toHaveBeenCalledWith(flags)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 20. Verify --help takes priority over --version ─────────────────────
@@ -608,6 +639,7 @@ describe('main() — setup orchestrator', () => {
     expect(help).toHaveBeenCalledTimes(1)
     expect(logSpy).not.toHaveBeenCalled() // console.log NOT called for version
     expect(discover).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).not.toHaveBeenCalled()
   })
 
   // ── 21. Error in prepare phase → continues ──────────────────────────────
@@ -626,6 +658,7 @@ describe('main() — setup orchestrator', () => {
     expect(installHooks).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 22. Error in husky-init → continues ────────────────────────────────
@@ -644,6 +677,7 @@ describe('main() — setup orchestrator', () => {
     expect(installHooks).toHaveBeenCalledTimes(1)
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(runSyncPhase).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
   // ── 23. Error in sync phase → continues ────────────────────────────────
@@ -660,5 +694,6 @@ describe('main() — setup orchestrator', () => {
     expect(installHooks).toHaveBeenCalledTimes(1)
     expect(handlePrepare).toHaveBeenCalledTimes(1)
     expect(initHusky).toHaveBeenCalledTimes(1)
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 })

package/scripts/setup/knowledgebase.js

@@ -0,0 +1,204 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// knowledgebase.js — Setup Phase 6: register consumer project in the
+//                    centralized knowledgebase (PostgreSQL + pgvector)
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Spawns `knowledgebase-cli.js sync --project <id>` as a child process to
+// register the consumer project and index its learned-knowledge chunks.
+//
+// Gracefully degrades when DATABASE_URL is not configured or when the CLI
+// script is unavailable — never blocks the setup pipeline.
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { spawn } from 'child_process'
+import { join } from 'path'
+
+import { UNICODE_CHARS } from './constants.js'
+import { verbose } from './ui.js'
+import { logInfo, logWarn, resolvePackageRoot } from './utils.js'
+
+// ── Main export ─────────────────────────────────────────────────────────────
+
+/**
+ * Registers the consumer project in the centralized knowledgebase.
+ *
+ * Spawns `scripts/knowledgebase-cli.js sync --project <projectId>` as a child
+ * process so the CLI's own graceful degradation (DATABASE_URL check, optional
+ * dependency loading) is reused rather than duplicated.
+ *
+ * **Early exits (all return `{ action: 'skipped' }`):**
+ * - `flags.skipKnowledgebase` is `true` — user opted out via flag
+ * - `process.env.DATABASE_URL` is not set — not configured yet
+ * - `consumerPackageJson` has no `name` field — can't identify the project
+ *
+ * **Normal execution:**
+ * The CLI is spawned with `INIT_CWD` set to `consumerRoot`. If the child
+ * process exits with a non-zero code, the action becomes `'failed'` but the
+ * pipeline continues (graceful degradation per REQ-08).
+ *
+ * @param {object} context - Setup context object.
+ * @param {object} [context.flags={}] - Parsed CLI flags.
+ * @param {boolean} [context.flags.skipKnowledgebase=false] - If `true`, skip.
+ * @param {boolean} [context.verbose=false] - Enable verbose child output.
+ * @param {string} [context.consumerRoot] - Absolute consumer project root.
+ * @param {object} [context.consumerPackageJson] - Consumer's package.json.
+ * @returns {Promise<{
+ *   action: 'indexed'|'skipped'|'failed',
+ *   message: string,
+ *   chunks_indexed?: number,
+ *   chunks_skipped?: number
+ * }>}
+ */
+export async function registerKnowledgebase(context) {
+  const { flags = {}, verbose: verboseFlag = false } = context
+
+  // ── Skip flag check ──────────────────────────────────────────────────
+  if (flags.skipKnowledgebase) {
+    const message =
+      '[knowledgebase] Skipping Phase 6 \u2014 --skip-knowledgebase flag set'
+    logInfo(message)
+    return { action: 'skipped', message }
+  }
+
+  // ── DATABASE_URL check ───────────────────────────────────────────────
+  if (!process.env.DATABASE_URL) {
+    const message =
+      'DATABASE_URL not configured. Set up later with: ' +
+      'npx ai-workflow-template setup --knowledgebase'
+    logWarn(
+      `[knowledgebase] Skipping Phase 6 \u2014 ${message}`,
+    )
+    return { action: 'skipped', message }
+  }
+
+  // ── Resolve project ID from consumer package.json ────────────────────
+  const projectId = context.consumerPackageJson?.name
+  if (!projectId) {
+    const message = 'No project name in consumer package.json'
+    logWarn(
+      `[knowledgebase] Skipping Phase 6 \u2014 ${message}`,
+    )
+    return { action: 'skipped', message }
+  }
+
+  // ── Spawn knowledgebase-cli.js sync ──────────────────────────────────
+  const packageRoot = resolvePackageRoot()
+  const cliPath = join(packageRoot, 'scripts', 'knowledgebase-cli.js')
+  const cwd = context.consumerRoot || process.cwd()
+
+  verbose(verboseFlag, `Spawning knowledgebase-cli.js sync for project "${projectId}"\u2026`)
+
+  try {
+    const result = await spawnScript(
+      'knowledgebase-cli.js',
+      cliPath,
+      cwd,
+      ['sync', '--project', projectId],
+      verboseFlag,
+    )
+
+    // Non-zero exit from the CLI is a warning, not a blocker
+    if (!result.success) {
+      const trimmedOutput = result.output
+      const message =
+        `Knowledgebase sync failed (exit code ${result.exitCode}): ${trimmedOutput}`
+      logWarn(`[knowledgebase] ${message}`)
+      return { action: 'failed', message }
+    }
+
+    // Parse the human-readable output for chunk counts.
+    // The CLI outputs: "[knowledgebase] Indexed X new, updated Y, skipped Z chunks from project <name>"
+    let chunksIndexed = 0
+    let chunksSkipped = 0
+    const outputLine = result.output
+    const match = outputLine.match(
+      /Indexed (\d+) new, updated (\d+), skipped (\d+) chunks/,
+    )
+    if (match) {
+      // "indexed" = new chunks + updated chunks (both were processed)
+      chunksIndexed = parseInt(match[1], 10) + parseInt(match[2], 10)
+      chunksSkipped = parseInt(match[3], 10)
+    }
+
+    const message =
+      `Registered "${projectId}" \u2014 ${chunksIndexed} chunks indexed, ` +
+      `${chunksSkipped} skipped`
+    logInfo(`[knowledgebase] ${UNICODE_CHARS.CHECK} ${message}`)
+
+    return {
+      action: 'indexed',
+      message,
+      chunks_indexed: chunksIndexed,
+      chunks_skipped: chunksSkipped,
+    }
+  } catch (err) {
+    // Catch spawn-level errors (ENOENT when script doesn't exist, etc.)
+    const message = `knowledgebase-cli.js not available: ${err.message}`
+    logWarn(
+      `[knowledgebase] Skipping Phase 6 \u2014 ${message}`,
+    )
+    return { action: 'skipped', message }
+  }
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+/**
+ * Spawns a Node.js script as a child process and waits for completion.
+ *
+ * Matches the `spawnScript` pattern from `sync-phase.js`: uses
+ * `process.execPath` so the child runs the same Node binary as the parent,
+ * streams output in real-time when `verbose` is `true`, and captures
+ * interleaved stdout + stderr when not.
+ *
+ * @param {string} name - Display name for the script.
+ * @param {string} scriptPath - Absolute path to the script to execute.
+ * @param {string} cwd - Working directory for the child process.
+ * @param {string[]} args - CLI arguments forwarded to the script.
+ * @param {boolean} [verbose=false] - Stream output in real-time when `true`.
+ * @returns {Promise<{
+ *   script: string,
+ *   success: boolean,
+ *   exitCode: number,
+ *   output: string
+ * }>}
+ */
+function spawnScript(name, scriptPath, cwd, args, verbose = false) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [scriptPath, ...args], {
+      cwd,
+      env: { ...process.env, INIT_CWD: cwd },
+      stdio: verbose ? 'inherit' : 'pipe',
+    })
+
+    let output = ''
+
+    if (!verbose) {
+      child.stdout.on('data', (data) => {
+        output += data.toString()
+      })
+
+      child.stderr.on('data', (data) => {
+        output += data.toString()
+      })
+    }
+
+    child.on('close', (exitCode) => {
+      resolve({
+        script: name,
+        success: exitCode === 0,
+        exitCode: exitCode ?? -1,
+        output: verbose ? '(streamed to terminal)' : output.trim(),
+      })
+    })
+
+    child.on('error', (err) => {
+      resolve({
+        script: name,
+        success: false,
+        exitCode: -1,
+        output: `Failed to spawn child process: ${err.message}`,
+      })
+    })
+  })
+}