ctx-cc 3.5.0 → 4.1.0

package/src/lifecycle.js

@@ -0,0 +1,194 @@
+import fs from 'fs';
+import path from 'path';
+import { readState, writeState, transitionPhase, initState, logAgentInvocation } from './state.js';
+import { discoverAgents } from './agents.js';
+import { buildContext } from './context.js';
+import { runAgent } from './runner.js';
+import { loadConfig } from './config.js';
+
+/**
+ * Phase-to-agent mapping.
+ * When `ctx next` advances to a phase, this agent is spawned.
+ */
+const PHASE_AGENTS = {
+  plan:     'ctx-planner.md',
+  execute:  'ctx-executor.md',
+  verify:   'ctx-verifier.md',
+};
+
+/**
+ * Determine the next phase from the current state.
+ * Returns { nextPhase, agent, message } or { error }.
+ */
+export function determineNext(state) {
+  if (!state) {
+    return { error: 'No STATE.json found. Run /ctx:init first.' };
+  }
+
+  const phaseMap = {
+    init:     'plan',
+    plan:     'execute',
+    execute:  'verify',
+    verify:   null, // depends on verification result
+    complete: null, // needs next story
+  };
+
+  // Verify phase: check if criteria passed
+  if (state.phase === 'verify') {
+    // If there are failed criteria, go back to execute
+    if (state.verificationResult === 'fail') {
+      return {
+        nextPhase: 'execute',
+        agent: PHASE_AGENTS.execute,
+        message: `Fix verification failures and re-implement. Previous failures: ${JSON.stringify(state.verificationFailures || [])}`,
+      };
+    }
+    // If passed, complete
+    return {
+      nextPhase: 'complete',
+      agent: null,
+      message: 'All acceptance criteria passed. Story complete.',
+    };
+  }
+
+  // Complete phase: need to pick next story
+  if (state.phase === 'complete') {
+    return {
+      nextPhase: 'init',
+      agent: null,
+      message: 'Story complete. Select next story from PRD.',
+      needsStorySelection: true,
+    };
+  }
+
+  const nextPhase = phaseMap[state.phase];
+  if (!nextPhase) {
+    return { error: `Cannot determine next phase from "${state.phase}".` };
+  }
+
+  return {
+    nextPhase,
+    agent: PHASE_AGENTS[nextPhase] || null,
+    message: `Advancing to ${nextPhase} phase.`,
+  };
+}
+
+/**
+ * Execute the `ctx next` command.
+ * Determines next phase, transitions state, spawns appropriate agent.
+ *
+ * Options:
+ *   ctxDir     - .ctx directory path
+ *   projectDir - project root
+ *   agentsDir  - agents directory path
+ *   streaming  - stream agent output (default true)
+ *   config     - loaded config object
+ */
+export async function executeNext({ ctxDir, projectDir, agentsDir, streaming = true, config = {} }) {
+  const state = readState(ctxDir);
+  const next = determineNext(state);
+
+  if (next.error) {
+    throw new Error(next.error);
+  }
+
+  if (next.needsStorySelection) {
+    return { action: 'select_story', message: next.message };
+  }
+
+  // Complete phase — no agent needed
+  if (!next.agent) {
+    if (next.nextPhase === 'complete') {
+      transitionPhase(ctxDir, 'complete');
+      return { action: 'completed', message: next.message };
+    }
+    transitionPhase(ctxDir, next.nextPhase);
+    return { action: 'transitioned', phase: next.nextPhase, message: next.message };
+  }
+
+  // Transition state
+  transitionPhase(ctxDir, next.nextPhase);
+
+  // Build agent-specific context
+  const agentCommand = agentFileToCommand(next.agent);
+  const { context, estimatedTokens, warnings } = buildContext(agentCommand, projectDir, ctxDir);
+
+  for (const w of warnings) {
+    process.stderr.write(`\x1b[33m  Warning: ${w}\x1b[0m\n`);
+  }
+
+  // Log invocation
+  logAgentInvocation(ctxDir, next.agent, `Phase: ${next.nextPhase}`);
+
+  // Run agent
+  const agentPath = path.join(agentsDir, next.agent);
+  const timeout = (config.agentTimeout || 300) * 1000;
+
+  const result = await runAgent({
+    agentPath,
+    message: next.message,
+    streaming,
+    timeout,
+    context,
+  });
+
+  return {
+    action: 'agent_completed',
+    phase: next.nextPhase,
+    agent: next.agent,
+    exitCode: result.exitCode,
+  };
+}
+
+/**
+ * Select a story from PRD.json and set it as active.
+ * Returns the story object or null.
+ */
+export function selectStory(ctxDir, storyId) {
+  const prdPath = path.join(ctxDir, 'PRD.json');
+  let prd;
+  try {
+    prd = JSON.parse(fs.readFileSync(prdPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+
+  const story = (prd.stories || []).find(s => s.id === storyId);
+  if (!story) return null;
+
+  // Update PRD metadata
+  prd.metadata = prd.metadata || {};
+  prd.metadata.currentStory = storyId;
+  fs.writeFileSync(prdPath, JSON.stringify(prd, null, 2) + '\n');
+
+  // Update state
+  const state = readState(ctxDir) || {};
+  state.phase = 'init';
+  state.activeStory = storyId;
+  state.storyTitle = story.title;
+  state.completedTasks = [];
+  state.verificationResult = null;
+  state.verificationFailures = null;
+  writeState(ctxDir, state);
+
+  return story;
+}
+
+/**
+ * List unfinished stories from PRD.json.
+ */
+export function listPendingStories(ctxDir) {
+  const prdPath = path.join(ctxDir, 'PRD.json');
+  try {
+    const prd = JSON.parse(fs.readFileSync(prdPath, 'utf-8'));
+    return (prd.stories || []).filter(s => !s.passes);
+  } catch {
+    return [];
+  }
+}
+
+// --- internal ---
+
+function agentFileToCommand(agentFile) {
+  return agentFile.replace(/^ctx-/, '').replace(/\.md$/, '').replace(/er$/, '').replace(/or$/, '');
+}

package/src/metrics.js

@@ -0,0 +1,198 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { readState } from './state.js';
+
+/**
+ * Collect metrics from STATE.json history and git log.
+ * Returns a metrics object with all computed stats.
+ */
+export function collectMetrics(ctxDir, projectDir) {
+  const state = readState(ctxDir);
+  const prd = loadPrd(ctxDir);
+  const gitStats = collectGitStats(projectDir);
+
+  const agentHistory = state?.agentHistory || [];
+  const completedTasks = state?.completedTasks || [];
+  const reviewHistory = state?.reviewGate?.history || [];
+
+  // Stories
+  const stories = prd?.stories || [];
+  const totalStories = stories.length;
+  const passedStories = stories.filter(s => s.passes).length;
+
+  // Agent metrics
+  const agentCounts = {};
+  let totalAgentDuration = 0;
+  for (const entry of agentHistory) {
+    const name = entry.agent?.replace('ctx-', '').replace('.md', '') || 'unknown';
+    agentCounts[name] = (agentCounts[name] || 0) + 1;
+    if (entry.invokedAt && entry.completedAt) {
+      totalAgentDuration += new Date(entry.completedAt) - new Date(entry.invokedAt);
+    }
+  }
+
+  // Review metrics
+  const totalReviews = reviewHistory.length;
+  const passedFirstTry = reviewHistory.filter(r => r.cycle === 1 && r.result === 'pass').length;
+  const avgCycles = totalReviews > 0
+    ? reviewHistory.reduce((sum, r) => sum + r.cycle, 0) / totalReviews
+    : 0;
+
+  // Token estimates (rough: based on context payloads)
+  const estimatedTokens = agentHistory.length * 15000; // ~15K per agent invocation average
+
+  // Time per story
+  const avgTimePerStory = completedTasks.length > 0 && state?.session?.startedAt
+    ? (Date.now() - new Date(state.session.startedAt).getTime()) / Math.max(passedStories, 1)
+    : 0;
+
+  return {
+    stories: {
+      total: totalStories,
+      passed: passedStories,
+      remaining: totalStories - passedStories,
+      completionRate: totalStories > 0 ? Math.round(passedStories / totalStories * 100) : 0,
+    },
+    agents: {
+      totalInvocations: agentHistory.length,
+      byType: agentCounts,
+      totalDurationMs: totalAgentDuration,
+      avgDurationMs: agentHistory.length > 0 ? Math.round(totalAgentDuration / agentHistory.length) : 0,
+    },
+    reviews: {
+      total: totalReviews,
+      passedFirstTry,
+      firstTryRate: totalReviews > 0 ? Math.round(passedFirstTry / totalReviews * 100) : 0,
+      avgCycles: Math.round(avgCycles * 10) / 10,
+    },
+    tasks: {
+      completed: completedTasks.length,
+    },
+    tokens: {
+      estimated: estimatedTokens,
+      estimatedCost: estimateTokenCost(estimatedTokens),
+    },
+    git: gitStats,
+    session: {
+      startedAt: state?.session?.startedAt || null,
+      lastActivity: state?.session?.lastActivity || null,
+      avgTimePerStoryMs: Math.round(avgTimePerStory),
+    },
+  };
+}
+
+/**
+ * Format metrics for human-readable display.
+ */
+export function formatMetrics(metrics) {
+  const lines = [];
+
+  // Stories
+  lines.push('  Stories');
+  lines.push(`    Completed:     ${metrics.stories.passed}/${metrics.stories.total} (${metrics.stories.completionRate}%)`);
+  lines.push(`    Remaining:     ${metrics.stories.remaining}`);
+  lines.push('');
+
+  // Agents
+  lines.push('  Agent Invocations');
+  lines.push(`    Total:         ${metrics.agents.totalInvocations}`);
+  if (Object.keys(metrics.agents.byType).length > 0) {
+    const sorted = Object.entries(metrics.agents.byType).sort((a, b) => b[1] - a[1]);
+    for (const [name, count] of sorted) {
+      lines.push(`      ${name.padEnd(20)} ${count}`);
+    }
+  }
+  if (metrics.agents.avgDurationMs > 0) {
+    lines.push(`    Avg duration:  ${formatDuration(metrics.agents.avgDurationMs)}`);
+  }
+  lines.push('');
+
+  // Reviews
+  if (metrics.reviews.total > 0) {
+    lines.push('  Review Gate');
+    lines.push(`    Reviews:       ${metrics.reviews.total}`);
+    lines.push(`    First-try pass: ${metrics.reviews.passedFirstTry} (${metrics.reviews.firstTryRate}%)`);
+    lines.push(`    Avg cycles:    ${metrics.reviews.avgCycles}`);
+    lines.push('');
+  }
+
+  // Tokens
+  if (metrics.tokens.estimated > 0) {
+    lines.push('  Token Usage (estimated)');
+    lines.push(`    Total:         ~${formatNumber(metrics.tokens.estimated)} tokens`);
+    lines.push(`    Est. cost:     ~$${metrics.tokens.estimatedCost.toFixed(2)}`);
+    lines.push('');
+  }
+
+  // Git
+  if (metrics.git.ctxCommits > 0) {
+    lines.push('  Git');
+    lines.push(`    CTX commits:   ${metrics.git.ctxCommits}`);
+    lines.push(`    Total commits: ${metrics.git.totalCommits}`);
+    lines.push('');
+  }
+
+  // Session
+  if (metrics.session.avgTimePerStoryMs > 0) {
+    lines.push('  Session');
+    lines.push(`    Avg per story: ${formatDuration(metrics.session.avgTimePerStoryMs)}`);
+    lines.push(`    Started:       ${metrics.session.startedAt || 'N/A'}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format metrics as JSON for external processing.
+ */
+export function formatMetricsJson(metrics) {
+  return JSON.stringify(metrics, null, 2);
+}
+
+// --- internal ---
+
+function loadPrd(ctxDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(ctxDir, 'PRD.json'), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function collectGitStats(projectDir) {
+  try {
+    const ctxCommits = parseInt(
+      execSync('git log --oneline --grep="^ctx(" --no-color 2>/dev/null | wc -l', {
+        cwd: projectDir, encoding: 'utf-8', timeout: 5000,
+      }).trim(), 10) || 0;
+
+    const totalCommits = parseInt(
+      execSync('git rev-list --count HEAD 2>/dev/null', {
+        cwd: projectDir, encoding: 'utf-8', timeout: 5000,
+      }).trim(), 10) || 0;
+
+    return { ctxCommits, totalCommits };
+  } catch {
+    return { ctxCommits: 0, totalCommits: 0 };
+  }
+}
+
+function estimateTokenCost(tokens) {
+  // Rough estimate: $3/M input + $15/M output, assume 60/40 split
+  const inputTokens = tokens * 0.6;
+  const outputTokens = tokens * 0.4;
+  return (inputTokens / 1_000_000 * 3) + (outputTokens / 1_000_000 * 15);
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${Math.round(ms / 1000)}s`;
+  return `${Math.round(ms / 60000)}m`;
+}
+
+function formatNumber(n) {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(0)}K`;
+  return String(n);
+}

package/src/pipeline.js

@@ -0,0 +1,269 @@
+import fs from 'fs';
+import path from 'path';
+import { readState, writeState, transitionPhase, logAgentInvocation, completeAgentInvocation } from './state.js';
+import { buildContext } from './context.js';
+import { runAgent } from './runner.js';
+import { discoverAgents } from './agents.js';
+
+/**
+ * Valid pipeline sequences. Each step maps to an agent file.
+ */
+const AGENT_FILES = {
+  plan:     'ctx-planner.md',
+  execute:  'ctx-executor.md',
+  verify:   'ctx-verifier.md',
+  review:   'ctx-reviewer.md',
+  audit:    'ctx-auditor.md',
+  research: 'ctx-researcher.md',
+  debug:    'ctx-debugger.md',
+};
+
+/**
+ * Validate that a pipeline sequence is logically valid.
+ * Returns { valid, error }.
+ */
+export function validatePipeline(steps) {
+  if (!steps || steps.length === 0) {
+    return { valid: false, error: 'Pipeline requires at least one step.' };
+  }
+
+  for (const step of steps) {
+    if (!AGENT_FILES[step]) {
+      const available = Object.keys(AGENT_FILES).join(', ');
+      return { valid: false, error: `Unknown pipeline step "${step}". Available: ${available}` };
+    }
+  }
+
+  // Validate ordering constraints
+  const idx = (s) => steps.indexOf(s);
+  if (steps.includes('execute') && steps.includes('plan') && idx('execute') < idx('plan')) {
+    return { valid: false, error: 'Cannot execute before planning.' };
+  }
+  if (steps.includes('verify') && steps.includes('execute') && idx('verify') < idx('execute')) {
+    return { valid: false, error: 'Cannot verify before executing.' };
+  }
+
+  return { valid: true, error: null };
+}
+
+/**
+ * Parse a pipeline string like "plan,execute,verify" into steps.
+ */
+export function parsePipelineString(str) {
+  return str.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Execute a pipeline of agents sequentially.
+ * Each agent's output (or summary) is passed as context to the next.
+ *
+ * Options:
+ *   steps      - array of step names: ['plan', 'execute', 'verify']
+ *   message    - initial user message
+ *   ctxDir     - .ctx directory path
+ *   projectDir - project root
+ *   agentsDir  - agents directory
+ *   streaming  - stream output (default true)
+ *   timeout    - per-agent timeout in ms
+ *   onStep     - callback({ step, index, total, status })
+ *
+ * Returns { completed: string[], failed: string|null, outputs: object }
+ */
+export async function executePipeline({ steps, message, ctxDir, projectDir, agentsDir, streaming = true, timeout = 300000, onStep = null }) {
+  const { valid, error } = validatePipeline(steps);
+  if (!valid) throw new Error(error);
+
+  // Initialize pipeline state
+  const pipelineState = {
+    steps,
+    currentStep: 0,
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    completedSteps: [],
+    failedStep: null,
+    outputs: {},
+  };
+
+  // Save pipeline state
+  const state = readState(ctxDir);
+  if (state) {
+    state.pipeline = pipelineState;
+    writeState(ctxDir, state);
+  }
+
+  let previousOutput = message;
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const agentFile = AGENT_FILES[step];
+    const agentPath = path.join(agentsDir, agentFile);
+
+    // Notify callback
+    if (onStep) onStep({ step, index: i, total: steps.length, status: 'starting' });
+
+    // Update pipeline state
+    pipelineState.currentStep = i;
+    if (state) {
+      state.pipeline = pipelineState;
+      writeState(ctxDir, state);
+    }
+
+    // Build agent-specific context
+    const { context } = buildContext(step, projectDir, ctxDir);
+
+    // Compose prompt: previous output feeds into next agent
+    const agentMessage = i === 0
+      ? previousOutput
+      : `Previous agent (${steps[i - 1]}) output summary:\n${summarizeOutput(previousOutput)}\n\nOriginal request: ${message}`;
+
+    // Log invocation
+    logAgentInvocation(ctxDir, agentFile, `Pipeline step ${i + 1}/${steps.length}: ${step}`);
+
+    try {
+      const result = await runAgent({
+        agentPath,
+        message: agentMessage,
+        streaming,
+        timeout,
+        context,
+      });
+
+      completeAgentInvocation(ctxDir, agentFile);
+
+      // Store output for next agent
+      previousOutput = result.stdout || `Step "${step}" completed successfully.`;
+      pipelineState.outputs[step] = previousOutput.slice(0, 2000); // Cap stored output
+      pipelineState.completedSteps.push(step);
+
+      // Save step output to file for reference
+      saveStepOutput(ctxDir, step, i, previousOutput);
+
+      if (onStep) onStep({ step, index: i, total: steps.length, status: 'completed' });
+
+    } catch (err) {
+      pipelineState.failedStep = step;
+      pipelineState.status = 'failed';
+      pipelineState.failedAt = new Date().toISOString();
+      pipelineState.failureReason = err.message;
+
+      if (state) {
+        state.pipeline = pipelineState;
+        writeState(ctxDir, state);
+      }
+
+      if (onStep) onStep({ step, index: i, total: steps.length, status: 'failed' });
+
+      return {
+        completed: pipelineState.completedSteps,
+        failed: step,
+        error: err.message,
+        outputs: pipelineState.outputs,
+      };
+    }
+  }
+
+  // Pipeline complete
+  pipelineState.status = 'completed';
+  pipelineState.completedAt = new Date().toISOString();
+  if (state) {
+    state.pipeline = pipelineState;
+    writeState(ctxDir, state);
+  }
+
+  return {
+    completed: pipelineState.completedSteps,
+    failed: null,
+    error: null,
+    outputs: pipelineState.outputs,
+  };
+}
+
+/**
+ * Resume a failed pipeline from the failed step.
+ */
+export async function resumePipeline({ ctxDir, projectDir, agentsDir, streaming = true, timeout = 300000, onStep = null }) {
+  const state = readState(ctxDir);
+  if (!state?.pipeline) {
+    throw new Error('No pipeline state found. Start a new pipeline with: ctx-cc pipeline <steps> <message>');
+  }
+
+  const { pipeline } = state;
+  if (pipeline.status !== 'failed') {
+    throw new Error(`Pipeline is "${pipeline.status}", not failed. Nothing to resume.`);
+  }
+
+  // Rebuild steps from the failed step onward
+  const failedIdx = pipeline.steps.indexOf(pipeline.failedStep);
+  const remainingSteps = pipeline.steps.slice(failedIdx);
+  const previousMessage = pipeline.outputs[pipeline.steps[failedIdx - 1]] || 'Resume from failure.';
+
+  return executePipeline({
+    steps: remainingSteps,
+    message: previousMessage,
+    ctxDir,
+    projectDir,
+    agentsDir,
+    streaming,
+    timeout,
+    onStep,
+  });
+}
+
+/**
+ * Get pipeline status from state.
+ */
+export function getPipelineStatus(ctxDir) {
+  const state = readState(ctxDir);
+  if (!state?.pipeline) return null;
+  return state.pipeline;
+}
+
+/**
+ * Format pipeline status for display.
+ */
+export function formatPipelineStatus(pipeline) {
+  if (!pipeline) return '  No active pipeline.';
+
+  const lines = [];
+  lines.push(`  Status:  ${pipeline.status}`);
+  lines.push(`  Steps:   ${pipeline.steps.join(' → ')}`);
+  lines.push('');
+
+  for (let i = 0; i < pipeline.steps.length; i++) {
+    const step = pipeline.steps[i];
+    let icon = '○'; // pending
+    if (pipeline.completedSteps.includes(step)) icon = '✓';
+    if (step === pipeline.failedStep) icon = '✗';
+    if (i === pipeline.currentStep && pipeline.status === 'running') icon = '▸';
+
+    lines.push(`  ${icon} ${step}`);
+  }
+
+  if (pipeline.failedStep) {
+    lines.push('');
+    lines.push(`  Failed at: ${pipeline.failedStep}`);
+    lines.push(`  Reason: ${pipeline.failureReason || 'unknown'}`);
+    lines.push(`  Resume: ctx-cc pipeline resume`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- internal ---
+
+function summarizeOutput(output) {
+  if (!output) return 'No output.';
+  // Take first 1500 chars as summary
+  const maxLen = 1500;
+  if (output.length <= maxLen) return output;
+  return output.slice(0, maxLen) + '\n\n... (output truncated)';
+}
+
+function saveStepOutput(ctxDir, step, index, output) {
+  const pipeDir = path.join(ctxDir, 'pipeline');
+  if (!fs.existsSync(pipeDir)) fs.mkdirSync(pipeDir, { recursive: true });
+  const filePath = path.join(pipeDir, `${String(index + 1).padStart(2, '0')}-${step}.md`);
+  fs.writeFileSync(filePath, `# Pipeline Step: ${step}\n\n${output}\n`);
+}
+
+export { AGENT_FILES };