@abarcenas/ai-workflow-template 1.29.0 → 1.33.0

package/scripts/setup/sync-phase.js

@@ -0,0 +1,179 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// sync-phase.js — Phase 5: spawn sync.js and normalize-memory.js as child
+//                 processes (avoids process.exit() killing the parent setup)
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { spawn } from 'child_process'
+import { join } from 'path'
+
+import { resolvePackageRoot, logInfo, logWarn, logError } from './utils.js'
+import { verbose } from './ui.js'
+
+// ── Main export ─────────────────────────────────────────────────────────────
+
+/**
+ * Runs the sync phase of the setup pipeline.
+ *
+ * Spawns `scripts/sync.js` and `scripts/normalize-memory.js` as child processes
+ * rather than importing them directly. This is required because `sync.js` calls
+ * `process.exit()` internally (line 83), which would terminate the entire setup
+ * process if it were imported as a module.
+ *
+ * **Early exits:**
+ * - `skipSync` is `true` → returns `{ action: 'skipped' }` without spawning
+ * - `dryRun`   is `true` → returns `{ action: 'dry-run' }` after logging intent
+ *
+ * **Normal execution:**
+ * Both scripts are spawned sequentially (sync.js first, normalize-memory.js
+ * second) with `INIT_CWD` set to `consumerRoot` so they resolve consumer
+ * paths correctly. If `flags.force` is set, the `--force` argument is
+ * forwarded to both child scripts.
+ *
+ * Non-zero exit codes from either script are treated as warnings, not
+ * failures — the overall action becomes `'partial'` but the pipeline
+ * continues (graceful degradation per REQ-04).
+ *
+ * @param {object} context - Setup context object.
+ * @param {string} context.consumerRoot - Absolute path to the consumer project root.
+ * @param {boolean} [context.dryRun=false] - If `true`, only simulate without spawning.
+ * @param {boolean} [context.skipSync=false] - If `true`, skip the entire sync phase.
+ * @param {object} [context.flags={}] - Parsed CLI flags (may include `force`).
+ * @returns {Promise<{
+ *   action: 'completed'|'partial'|'skipped'|'dry-run',
+ *   message: string,
+ *   results: Array<{
+ *     script: string,
+ *     success: boolean,
+ *     exitCode: number,
+ *     output: string
+ *   }>
+ * }>}
+ */
+export async function runSyncPhase(context) {
+  const { consumerRoot, dryRun = false, skipSync = false, flags = {} } = context
+
+  // ── Skip path ──────────────────────────────────────────────────────────
+  if (skipSync) {
+    const message = 'Sync phase skipped (--skip-sync)'
+    logInfo(`[setup] ${message}`)
+    return { action: 'skipped', message, results: [] }
+  }
+
+  // ── Dry-run path ───────────────────────────────────────────────────────
+  if (dryRun) {
+    const message =
+      `Would run sync.js and normalize-memory.js ` +
+      `with INIT_CWD="${consumerRoot}"`
+    logInfo(`[setup] dry-run: ${message}`)
+    return { action: 'dry-run', message, results: [] }
+  }
+
+  const packageRoot = resolvePackageRoot()
+  const extraArgs = flags.force ? ['--force'] : []
+
+  // ── Spawn sync.js ──────────────────────────────────────────────────────
+  const syncPath = join(packageRoot, 'scripts', 'sync.js')
+  verbose(context.verbose, 'Spawning sync.js\u2026')
+  const syncResult = await spawnScript(
+    'sync.js',
+    syncPath,
+    consumerRoot,
+    extraArgs,
+    context.verbose,
+  )
+
+  // ── Spawn normalize-memory.js ──────────────────────────────────────────
+  const normPath = join(packageRoot, 'scripts', 'normalize-memory.js')
+  verbose(context.verbose, 'Spawning normalize-memory.js\u2026')
+  const normResult = await spawnScript(
+    'normalize-memory.js',
+    normPath,
+    consumerRoot,
+    extraArgs,
+    context.verbose,
+  )
+
+  const results = [syncResult, normResult]
+  const allSucceeded = results.every((r) => r.success)
+  const action = allSucceeded ? 'completed' : 'partial'
+  const failureCount = results.filter((r) => !r.success).length
+
+  const message =
+    action === 'completed'
+      ? 'Sync phase completed'
+      : `Sync phase completed with ${failureCount} script failure(s)`
+
+  if (!allSucceeded) {
+    logWarn(`[setup] ${message}`)
+    for (const r of results) {
+      if (!r.success) {
+        logWarn(`[setup]   ${r.script} exited with code ${r.exitCode}`)
+      }
+    }
+  }
+
+  return { action, message, results }
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+/**
+ * Spawns a Node.js script as a child process and waits for it to complete.
+ *
+ * Both stdout and stderr are captured into a single `output` string
+ * (interleaved in the order data events arrive). The returned promise
+ * resolves when the child process exits or fails to spawn.
+ *
+ * Uses `process.execPath` so the child always runs the same Node.js
+ * binary as the parent setup process.
+ *
+ * @param {string} name - Display name for the script (e.g. `'sync.js'`).
+ * @param {string} scriptPath - Absolute path to the script to execute.
+ * @param {string} cwd - Working directory for the child process.
+ * @param {string[]} extraArgs - Extra CLI arguments forwarded to the script.
+ * @returns {Promise<{
+ *   script: string,
+ *   success: boolean,
+ *   exitCode: number,
+ *   output: string
+ * }>}
+ */
+function spawnScript(name, scriptPath, cwd, extraArgs, verbose = false) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [scriptPath, ...extraArgs], {
+      cwd,
+      env: { ...process.env, INIT_CWD: cwd, AI_WORKFLOW_VERBOSE: verbose ? '1' : '0' },
+      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}`,
+      })
+    })
+  })
+}

package/scripts/setup/sync-phase.test.js

@@ -0,0 +1,195 @@
+// ═════════════════════════════════════════════════════════════════════════════
+// sync-phase.test.js — Unit tests for the sync phase module
+// ═════════════════════════════════════════════════════════════════════════════
+//
+// Tests the spawnScript() function's verbose vs non-verbose spawn behavior
+// by mocking `child_process.spawn` and inspecting the options passed.
+//
+// Covered scenarios (5 tests per T10 requirements):
+//   1. Uses stdio: 'pipe' when verbose is false (default behavior)
+//   2. Uses stdio: 'inherit' when verbose is true
+//   3. Sets AI_WORKFLOW_VERBOSE=1 in child env when verbose is true
+//   4. Sets AI_WORKFLOW_VERBOSE=0 in child env when verbose is false
+//   5. Captures stdout/stderr output correctly in non-verbose mode
+// ═════════════════════════════════════════════════════════════════════════════
+
+import { vi, describe, it, expect, beforeEach } 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 { runSyncPhase } from './sync-phase.js'
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Creates a mock child process that mimics a spawned Node.js script.
+ *
+ * The mock registers event handlers for stdout/stderr 'data' events and
+ * the 'close' event, then fires them asynchronously on a microtask.
+ * This allows the Promise-based flow in spawnScript() to resolve naturally.
+ *
+ * @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'
+ * @returns {object} Mock child process with .stdout.on, .stderr.on, .on
+ */
+function createMockChild({ exitCode = 0, stdoutData = '', stderrData = '' } = {}) {
+  const stdoutHandlers = []
+  const stderrHandlers = []
+  let closeHandler = 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
+    },
+  }
+
+  // Fire events on a microtask so handlers are registered first
+  Promise.resolve().then(() => {
+    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 runSyncPhase().
+ *
+ * @param {object} [overrides] - Properties to override on the default context.
+ * @returns {object} Context object.
+ */
+function makeContext(overrides = {}) {
+  return {
+    consumerRoot: '/fake/consumer',
+    verbose: false,
+    dryRun: false,
+    skipSync: false,
+    flags: {},
+    ...overrides,
+  }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────
+
+describe('sync-phase verbose spawn behavior', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // ── 1. Pipe mode (non-verbose, default) ───────────────────────────────
+
+  it('uses stdio: "pipe" when verbose is false', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: false }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].stdio).toBe('pipe')
+    }
+  })
+
+  // ── 2. Inherit mode (verbose) ─────────────────────────────────────────
+
+  it('uses stdio: "inherit" when verbose is true', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: true }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].stdio).toBe('inherit')
+    }
+  })
+
+  // ── 3. Verbose env var = '1' ──────────────────────────────────────────
+
+  it('sets AI_WORKFLOW_VERBOSE=1 in child env when verbose is true', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: true }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].env).toBeDefined()
+      expect(call[2].env.AI_WORKFLOW_VERBOSE).toBe('1')
+    }
+  })
+
+  // ── 4. Non-verbose env var = '0' ──────────────────────────────────────
+
+  it('sets AI_WORKFLOW_VERBOSE=0 in child env when verbose is false', async () => {
+    vi.mocked(spawn).mockImplementation(() => createMockChild({ exitCode: 0 }))
+
+    await runSyncPhase(makeContext({ verbose: false }))
+
+    const calls = vi.mocked(spawn).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(2)
+    for (const call of calls) {
+      expect(call[2]).toBeDefined()
+      expect(call[2].env).toBeDefined()
+      expect(call[2].env.AI_WORKFLOW_VERBOSE).toBe('0')
+    }
+  })
+
+  // ── 5. Output capture in non-verbose mode ─────────────────────────────
+
+  it('captures stdout/stderr output in non-verbose mode', async () => {
+    vi.mocked(spawn).mockImplementation(() =>
+      createMockChild({
+        exitCode: 0,
+        stdoutData: 'copying files...\n',
+        stderrData: '',
+      }),
+    )
+
+    const result = await runSyncPhase(makeContext({ verbose: false }))
+
+    expect(result.action).toBe('completed')
+    expect(result.results).toHaveLength(2)
+    for (const r of result.results) {
+      expect(r.output).toBe('copying files...')
+      expect(r.success).toBe(true)
+      expect(r.exitCode).toBe(0)
+    }
+  })
+})