cc-pipeline 0.4.0

package/src/commands/update.js

@@ -0,0 +1,42 @@
+import { existsSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates');
+
+export function update(projectDir) {
+  const pipelineDir = join(projectDir, '.pipeline');
+
+  if (!existsSync(pipelineDir)) {
+    console.error('  ❌ No .pipeline/ directory found. Run `cc-pipeline init` first.');
+    process.exit(1);
+  }
+
+  console.log('🔄 Updating pipeline templates...\n');
+
+  // Update prompts
+  const promptsDir = join(pipelineDir, 'prompts');
+  cpSync(join(TEMPLATES_DIR, 'pipeline', 'prompts'), promptsDir, { recursive: true, force: true });
+  console.log('  ✅ Updated .pipeline/prompts/');
+
+  // Update .pipeline/CLAUDE.md
+  const pipelineClaudeMd = join(pipelineDir, 'CLAUDE.md');
+  cpSync(join(TEMPLATES_DIR, 'pipeline', 'CLAUDE.md'), pipelineClaudeMd);
+  console.log('  ✅ Updated .pipeline/CLAUDE.md');
+
+  // Update root CLAUDE.md (pipeline section)
+  const rootClaudeMd = join(projectDir, 'CLAUDE.md');
+  if (!existsSync(rootClaudeMd)) {
+    cpSync(join(TEMPLATES_DIR, 'CLAUDE.md'), rootClaudeMd);
+    console.log('  ✅ Created CLAUDE.md');
+  } else {
+    console.log('  ⏭️  CLAUDE.md exists — skipped (edit manually if needed)');
+  }
+
+  console.log(`
+  ⚠️  workflow.yaml was NOT changed (your customizations are preserved).
+  If you need the latest default workflow, delete .pipeline/workflow.yaml
+  and run \`cc-pipeline init\` again.
+`);
+}

package/src/config.js

@@ -0,0 +1,101 @@
+import YAML from 'yaml';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Load and parse the workflow configuration from .pipeline/workflow.yaml
+ * Normalizes snake_case YAML keys to camelCase JS properties
+ * @param {string} projectDir - The project directory path
+ * @returns {object} Normalized config object
+ */
+export function loadConfig(projectDir) {
+  const workflowPath = join(projectDir, '.pipeline', 'workflow.yaml');
+
+  if (!existsSync(workflowPath)) {
+    throw new Error(`Workflow file not found: ${workflowPath}`);
+  }
+
+  const rawContent = readFileSync(workflowPath, 'utf-8');
+  const raw = YAML.parse(rawContent);
+
+  // Normalize top-level config
+  const config = {
+    name: raw.name || 'Unnamed Pipeline',
+    version: raw.version || 1,
+    phasesDir: raw.phases_dir || 'docs/phases',
+    steps: [],
+    usageCheck: raw.usage_check || { when: 'phase_boundary' }
+  };
+
+  // Normalize steps array
+  if (raw.steps && Array.isArray(raw.steps)) {
+    config.steps = raw.steps.map(step => ({
+      name: step.name,
+      description: step.description || '',
+      agent: step.agent,
+      prompt: step.prompt,
+      model: step.model,
+      skipUnless: step.skip_unless,
+      output: step.output,
+      testGate: step.test_gate,
+      command: step.command
+    }));
+  }
+
+  return config;
+}
+
+/**
+ * Find a step by name
+ * @param {object} config - The workflow configuration
+ * @param {string} name - The step name to find
+ * @returns {object|null} The step object or null if not found
+ */
+export function getStepByName(config, name) {
+  return config.steps.find(step => step.name === name) || null;
+}
+
+/**
+ * Find the index of a step by name
+ * @param {object} config - The workflow configuration
+ * @param {string} name - The step name to find
+ * @returns {number} The step index or -1 if not found
+ */
+export function getStepIndex(config, name) {
+  return config.steps.findIndex(step => step.name === name);
+}
+
+/**
+ * Get the next step name after the current step
+ * @param {object} config - The workflow configuration
+ * @param {string} currentStepName - The current step name
+ * @returns {string} The next step name or 'done' if at the end
+ */
+export function getNextStep(config, currentStepName) {
+  const currentIndex = getStepIndex(config, currentStepName);
+
+  if (currentIndex === -1) {
+    throw new Error(`Step not found: ${currentStepName}`);
+  }
+
+  const nextIndex = currentIndex + 1;
+
+  if (nextIndex >= config.steps.length) {
+    return 'done';
+  }
+
+  return config.steps[nextIndex].name;
+}
+
+/**
+ * Get the first step name
+ * @param {object} config - The workflow configuration
+ * @returns {string} The first step name
+ */
+export function getFirstStep(config) {
+  if (!config.steps || config.steps.length === 0) {
+    throw new Error('No steps defined in workflow');
+  }
+
+  return config.steps[0].name;
+}

package/src/engine.js

@@ -0,0 +1,326 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { getCurrentState, appendEvent, deriveResumePoint } from './state.js';
+import { loadConfig } from './config.js';
+import { printBanner } from './logger.js';
+import { agentState } from './agents/base.js';
+import { BashAgent } from './agents/bash.js';
+import { ClaudePipedAgent } from './agents/claude-piped.js';
+import { ClaudeInteractiveAgent } from './agents/claude-interactive.js';
+
+const MAX_PHASES = 20;
+
+/**
+ * Main pipeline engine loop.
+ *
+ * Logic from run.sh lines 549-636:
+ * - Load config from workflow.yaml
+ * - Derive current state from JSONL
+ * - Print banner
+ * - Loop through phases, executing steps
+ * - Check for PROJECT COMPLETE in reflections
+ * - Handle phase limits and MAX_PHASES
+ * - Signal handling for clean shutdown
+ *
+ * @param {string} projectDir - Absolute path to project root
+ * @param {object} options - { phases?: number, model?: string }
+ */
+export async function runEngine(projectDir, options = {}) {
+  const pipelineDir = join(projectDir, '.pipeline');
+  const logFile = join(pipelineDir, 'pipeline.jsonl');
+  const workflowFile = join(pipelineDir, 'workflow.yaml');
+
+  // Validate pipeline exists
+  if (!existsSync(workflowFile)) {
+    throw new Error('No .pipeline/workflow.yaml found. Run `cc-pipeline init` first.');
+  }
+
+  // Load config
+  const config = loadConfig(projectDir);
+
+  // Derive current state
+  const state = getCurrentState(logFile);
+  const resumePoint = deriveResumePoint(logFile, config.steps);
+
+  // Print banner
+  printBanner(config, projectDir, state);
+  console.log(`\nResumed state: phase=${resumePoint.phase} step=${resumePoint.stepName} status=${state.status}`);
+
+  // Signal handling — track interrupted state, kill child processes, and allow cancelling sleep
+  let interrupted = false;
+  let cancelSleep = null;
+  let phase = resumePoint.phase;
+  let currentStepName = resumePoint.stepName;
+
+  const handleSignal = (signal) => {
+    if (interrupted) return; // Already handling a signal, ignore duplicates
+    console.log(`\nReceived ${signal}, shutting down gracefully...`);
+    interrupted = true;
+    agentState.setInterrupted(true);
+    if (cancelSleep) cancelSleep();
+
+    // Write interrupted event
+    appendEvent(logFile, { event: 'interrupted', phase, step: currentStepName });
+
+    // Kill current child process if any
+    const child = agentState.getChild();
+    if (child && child.pid) {
+      console.log(`Terminating child process ${child.pid}...`);
+
+      // Send SIGTERM first
+      try {
+        process.kill(child.pid, 'SIGTERM');
+      } catch (err) {
+        // Process may have already exited
+      }
+
+      // Send SIGKILL after 2 seconds if still running
+      setTimeout(() => {
+        try {
+          process.kill(child.pid, 'SIGKILL');
+        } catch (err) {
+          // Process already exited, ignore
+        }
+      }, 2000);
+    }
+
+    // Exit after cleanup — use correct exit code per signal
+    const exitCode = signal === 'SIGTERM' ? 143 : 130;
+    setTimeout(() => {
+      process.exit(exitCode);
+    }, 3000);
+  };
+  process.on('SIGINT', handleSignal);
+  process.on('SIGTERM', handleSignal);
+
+  const cleanup = () => {
+    process.removeListener('SIGINT', handleSignal);
+    process.removeListener('SIGTERM', handleSignal);
+  };
+
+  try {
+    // Main loop (phase and currentStepName already declared above for signal handler)
+    let phasesRun = 0;
+
+    const phaseLimit = options.phases || 0;
+
+    while (phase <= MAX_PHASES) {
+      // Check for PROJECT COMPLETE
+      if (phase > 1) {
+        const prevPhaseDir = join(projectDir, config.phasesDir, `phase-${phase - 1}`);
+        const reflectFile = join(prevPhaseDir, 'REFLECTIONS.md');
+        if (existsSync(reflectFile)) {
+          const firstLine = readFileSync(reflectFile, 'utf8').split('\n')[0];
+          if (firstLine && /PROJECT COMPLETE/i.test(firstLine)) {
+            appendEvent(logFile, { event: 'project_complete', phase: phase - 1 });
+            console.log(`PROJECT COMPLETE detected in phase ${phase - 1} reflections.`);
+            return;
+          }
+        }
+      }
+
+      // Execute all steps in phase
+      let stepIndex = config.steps.findIndex(s => s.name === currentStepName);
+      if (stepIndex === -1) stepIndex = 0;
+
+      for (let i = stepIndex; i < config.steps.length; i++) {
+        if (interrupted) {
+          // Signal handler already wrote the interrupted event
+          throw new Error('Pipeline interrupted by signal');
+        }
+
+        const stepDef = config.steps[i];
+        currentStepName = stepDef.name;
+
+        // Retry logic: 3 attempts with backoff (0s, 30s, 60s)
+        const retryDelays = [0, 30000, 60000];
+        let lastResult = null;
+
+        for (let attempt = 0; attempt < retryDelays.length; attempt++) {
+          if (attempt > 0) {
+            const delaySec = retryDelays[attempt] / 1000;
+            console.log(`\n  ⏳ Retry ${attempt}/2 for step "${stepDef.name}" in ${delaySec}s...`);
+            await new Promise(resolve => {
+              const timer = setTimeout(resolve, retryDelays[attempt]);
+              cancelSleep = () => { clearTimeout(timer); resolve(); };
+            });
+            cancelSleep = null;
+            if (interrupted) throw new Error('Pipeline interrupted by signal');
+          }
+
+          lastResult = await runStep(phase, stepDef, projectDir, config, logFile, options);
+
+          // If interrupted during step execution, bail immediately
+          if (interrupted) throw new Error('Pipeline interrupted by signal');
+
+          if (lastResult === 'ok' || lastResult === 'skipped') break;
+
+          // Log retry
+          if (attempt < retryDelays.length - 1) {
+            appendEvent(logFile, {
+              event: 'step_retry',
+              phase,
+              step: stepDef.name,
+              attempt: attempt + 1,
+            });
+          }
+        }
+
+        // If still failed after all retries, stop the pipeline
+        if (lastResult === 'error') {
+          console.error(`\n  ❌ Step "${stepDef.name}" failed after 3 attempts. Pipeline stopped.`);
+          console.error(`  Run \`cc-pipeline run\` to retry from this step.`);
+          appendEvent(logFile, {
+            event: 'pipeline_stopped',
+            phase,
+            step: stepDef.name,
+            reason: 'max_retries_exceeded',
+          });
+          process.exit(1);
+        }
+      }
+
+      // Phase complete
+      appendEvent(logFile, { event: 'phase_complete', phase });
+
+      phasesRun++;
+
+      // Check phase limit
+      if (phaseLimit > 0 && phasesRun >= phaseLimit) {
+        console.log(`Completed ${phasesRun} phase(s) as requested. Stopping.`);
+        return;
+      }
+
+      // Advance to next phase
+      phase++;
+      currentStepName = config.steps[0].name;
+
+      // Brief pause between phases (interruptible)
+      await new Promise(resolve => {
+        const timer = setTimeout(resolve, 5000);
+        cancelSleep = () => { clearTimeout(timer); resolve(); };
+      });
+      cancelSleep = null;
+      if (interrupted) {
+        // Signal handler already wrote the interrupted event
+        throw new Error('Pipeline interrupted by signal');
+      }
+    }
+
+    console.log(`Hit MAX_PHASES (${MAX_PHASES}). Stopping.`);
+  } finally {
+    cleanup();
+  }
+}
+
+/**
+ * Execute a single pipeline step.
+ *
+ * @param {number} phase - Current phase number
+ * @param {object} stepDef - Step definition from workflow.yaml
+ * @param {string} projectDir - Project root directory
+ * @param {object} config - Full config object
+ * @param {string} logFile - Path to JSONL log
+ */
+async function runStep(phase, stepDef, projectDir, config, logFile, options = {}) {
+  const { name: stepName, agent, skipUnless, output, testGate } = stepDef;
+
+  // Check skipUnless condition
+  if (skipUnless) {
+    const checkFile = join(projectDir, config.phasesDir, `phase-${phase}`, skipUnless);
+    if (!existsSync(checkFile)) {
+      appendEvent(logFile, {
+        event: 'step_skip',
+        phase,
+        step: stepName,
+        reason: `${skipUnless} not found`,
+      });
+      console.log(`Skipping ${stepName} (${skipUnless} not found)`);
+      return 'skipped';
+    }
+  }
+
+  // CLI --model overrides workflow.yaml per-step model
+  const model = options.model || stepDef.model || 'default';
+  appendEvent(logFile, {
+    event: 'step_start',
+    phase,
+    step: stepName,
+    agent,
+    model,
+  });
+
+  console.log(`\nRunning step: ${stepName} (phase ${phase}, agent: ${agent})`);
+
+  // Route to agent and execute
+  let result;
+  const context = { projectDir, config, logFile };
+  const promptPath = stepDef.prompt || null;
+
+  try {
+    switch (agent) {
+      case 'bash': {
+        const bashAgent = new BashAgent();
+        result = await bashAgent.run(phase, stepDef, promptPath, model, context);
+        break;
+      }
+      case 'claude-piped': {
+        const pipedAgent = new ClaudePipedAgent();
+        result = await pipedAgent.run(phase, stepDef, promptPath, model, context);
+        break;
+      }
+      case 'claude-interactive':
+      case 'codex-interactive': {
+        const interactiveAgent = new ClaudeInteractiveAgent();
+        result = await interactiveAgent.run(phase, stepDef, promptPath, model, context);
+        break;
+      }
+      default:
+        throw new Error(`Unknown agent: ${agent}`);
+    }
+  } catch (err) {
+    console.error(`Error executing agent ${agent}: ${err.message}`);
+    result = { exitCode: 1, outputPath: null, error: err.message };
+  }
+
+  // Log step done
+  const status = result.exitCode === 0 ? 'ok' : 'error';
+  appendEvent(logFile, {
+    event: 'step_done',
+    phase,
+    step: stepName,
+    agent,
+    status,
+    exitCode: result.exitCode,
+    ...(result.error && { error: result.error }),
+  });
+
+  // Validate output if specified
+  if (output) {
+    const outputFile = join(projectDir, config.phasesDir, `phase-${phase}`, output);
+    if (existsSync(outputFile)) {
+      appendEvent(logFile, {
+        event: 'output_verified',
+        phase,
+        step: stepName,
+        file: output,
+      });
+    } else {
+      appendEvent(logFile, {
+        event: 'output_missing',
+        phase,
+        step: stepName,
+        file: output,
+      });
+      console.log(`WARNING: Expected output ${output} not found after ${stepName}`);
+    }
+  }
+
+  // Test gate (placeholder)
+  if (testGate === true) {
+    console.log(`  [STUB] Would run test gate for ${stepName}`);
+  }
+
+  return status;
+}
+

package/src/logger.js

@@ -0,0 +1,57 @@
+// ANSI color codes
+const COLORS = {
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+};
+
+/**
+ * Print startup banner with box-drawing characters.
+ * @param {object} config - Workflow config from yaml
+ * @param {string} projectDir - Project directory path
+ * @param {object} currentState - Current state { phase, step, status }
+ */
+export function printBanner(config, projectDir, currentState) {
+  const workflowName = config.name || 'Pipeline';
+  const projectName = projectDir.split('/').pop();
+  const BOX_WIDTH = 60;
+
+  // Helper to pad line with spaces and add right border.
+  // All ANSI codes must be included in `text`; this function only handles padding.
+  const boxLine = (text) => {
+    const stripped = text.replace(/\x1b\[[0-9;]*m/g, ''); // Remove ANSI codes for length calc
+    const padding = ' '.repeat(Math.max(0, BOX_WIDTH - 2 - stripped.length));
+    return `║ ${text}${padding}${COLORS.reset} ║`;
+  };
+
+  const lines = [
+    '╔' + '═'.repeat(BOX_WIDTH) + '╗',
+    boxLine(`${COLORS.cyan}${workflowName}${COLORS.reset}`),
+    boxLine(`Project: ${projectName}`),
+    boxLine(''),
+  ];
+
+  // Show steps with current step highlighted
+  lines.push(boxLine(`${COLORS.yellow}Pipeline Steps:${COLORS.reset}`));
+  config.steps.forEach((step, idx) => {
+    const isCurrent = currentState && step.name === currentState.step;
+    const marker = isCurrent ? `${COLORS.cyan}▶` : ' ';
+    const stepText = isCurrent
+      ? `${COLORS.cyan}${marker} ${idx + 1}. ${step.name}${COLORS.reset}`
+      : `${marker} ${idx + 1}. ${step.name}`;
+    lines.push(boxLine(stepText));
+  });
+
+  // Show phase and status
+  if (currentState && currentState.phase) {
+    lines.push(boxLine(''));
+    const phaseText = `${COLORS.dim}Phase: ${currentState.phase} | Status: ${currentState.status}${COLORS.reset}`;
+    lines.push(boxLine(phaseText));
+  }
+
+  lines.push('╚' + '═'.repeat(BOX_WIDTH) + '╝');
+
+  lines.forEach(line => console.log(line));
+}

package/src/prompts.js

@@ -0,0 +1,49 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Generate a prompt by reading the template and substituting placeholders
+ * @param {string} projectDir - The project directory path
+ * @param {object} config - The workflow configuration
+ * @param {number} phase - The current phase number
+ * @param {string} promptPath - The relative path to the prompt template (e.g., "prompts/spec.md")
+ * @returns {string} The generated prompt with substitutions
+ */
+export function generatePrompt(projectDir, config, phase, promptPath) {
+  const promptFile = join(projectDir, '.pipeline', promptPath);
+
+  if (!existsSync(promptFile)) {
+    throw new Error(`Prompt file not found: ${promptFile}`);
+  }
+
+  // Read the template
+  let prompt = readFileSync(promptFile, 'utf-8');
+
+  // Substitute {{PHASE}}
+  prompt = prompt.replace(/\{\{PHASE\}\}/g, phase.toString());
+
+  // Substitute {{PREV_REFLECTIONS}}
+  let prevReflections = '';
+  if (phase > 1) {
+    const prevPhase = phase - 1;
+    const prevReflectPath = join(projectDir, config.phasesDir, `phase-${prevPhase}`, 'REFLECTIONS.md');
+    if (existsSync(prevReflectPath)) {
+      prevReflections = `Previous phase reflections (read this file): ${prevReflectPath}`;
+    }
+  }
+  prompt = prompt.replace(/\{\{PREV_REFLECTIONS\}\}/g, prevReflections);
+
+  // Substitute {{BRIEF}}
+  let briefContent = '';
+  const briefPath = join(projectDir, 'BRIEF.md');
+  if (existsSync(briefPath)) {
+    briefContent = readFileSync(briefPath, 'utf-8');
+  }
+  prompt = prompt.replace(/\{\{BRIEF\}\}/g, briefContent);
+
+  // Substitute {{FILE_TREE}} - placeholder for now
+  const fileTree = '(file tree generation not yet implemented)';
+  prompt = prompt.replace(/\{\{FILE_TREE\}\}/g, fileTree);
+
+  return prompt;
+}