ctx-cc 3.5.0 → 4.1.0

package/src/state.js

@@ -0,0 +1,267 @@
+import fs from 'fs';
+import path from 'path';
+
+const STATE_FILE = 'STATE.json';
+const LOCK_FILE = 'STATE.lock';
+
+/**
+ * Valid phases and their allowed transitions.
+ */
+const TRANSITIONS = {
+  init:     ['plan'],
+  plan:     ['execute'],
+  execute:  ['verify'],
+  verify:   ['complete', 'execute'],  // execute = fix failures
+  complete: ['init'],                  // reset for next story
+};
+
+// Any phase can reset to init
+const UNIVERSAL_TARGETS = ['init'];
+
+const VALID_PHASES = Object.keys(TRANSITIONS);
+
+/**
+ * Create a fresh state object for a new project/story.
+ */
+export function createInitialState(storyId = null, storyTitle = '') {
+  return {
+    version: '4.0',
+    phase: 'init',
+    activeStory: storyId,
+    storyTitle,
+    completedTasks: [],
+    agentHistory: [],
+    pipeline: null,
+    session: {
+      startedAt: isoNow(),
+      lastActivity: isoNow(),
+    },
+  };
+}
+
+/**
+ * Resolve the .ctx directory for a project.
+ */
+export function resolveCtxDir(projectDir = process.cwd()) {
+  return path.join(projectDir, '.ctx');
+}
+
+/**
+ * Read STATE.json from .ctx directory. Returns null if not found.
+ */
+export function readState(ctxDir) {
+  const statePath = path.join(ctxDir, STATE_FILE);
+  try {
+    return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write STATE.json to .ctx directory.
+ * Updates session.lastActivity automatically.
+ */
+export function writeState(ctxDir, state) {
+  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
+
+  state.session = state.session || {};
+  state.session.lastActivity = isoNow();
+
+  const statePath = path.join(ctxDir, STATE_FILE);
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+  return state;
+}
+
+/**
+ * Initialize state for a new project. Creates .ctx/STATE.json.
+ * Returns the new state.
+ */
+export function initState(ctxDir, storyId = null, storyTitle = '') {
+  const state = createInitialState(storyId, storyTitle);
+  return writeState(ctxDir, state);
+}
+
+/**
+ * Validate a phase transition. Returns { valid, error }.
+ */
+export function validateTransition(currentPhase, targetPhase) {
+  if (!VALID_PHASES.includes(currentPhase)) {
+    return { valid: false, error: `Invalid current phase: "${currentPhase}". Valid phases: ${VALID_PHASES.join(', ')}` };
+  }
+  if (!VALID_PHASES.includes(targetPhase)) {
+    return { valid: false, error: `Invalid target phase: "${targetPhase}". Valid phases: ${VALID_PHASES.join(', ')}` };
+  }
+
+  const allowed = [...(TRANSITIONS[currentPhase] || []), ...UNIVERSAL_TARGETS];
+  if (!allowed.includes(targetPhase)) {
+    const hint = phaseHint(currentPhase, targetPhase);
+    return {
+      valid: false,
+      error: `Cannot transition from "${currentPhase}" to "${targetPhase}". Allowed: ${allowed.join(', ')}.${hint}`,
+    };
+  }
+
+  return { valid: true, error: null };
+}
+
+/**
+ * Transition to a new phase. Validates and writes state.
+ * Returns the updated state or throws on invalid transition.
+ */
+export function transitionPhase(ctxDir, targetPhase) {
+  const state = readState(ctxDir);
+  if (!state) {
+    throw new Error('No STATE.json found. Run /ctx:init first.');
+  }
+
+  const { valid, error } = validateTransition(state.phase, targetPhase);
+  if (!valid) throw new Error(error);
+
+  state.phase = targetPhase;
+  return writeState(ctxDir, state);
+}
+
+/**
+ * Log an agent invocation to state history.
+ */
+export function logAgentInvocation(ctxDir, agentName, taskSummary) {
+  const state = readState(ctxDir);
+  if (!state) return null;
+
+  const entry = {
+    agent: agentName,
+    invokedAt: isoNow(),
+    completedAt: null,
+    taskSummary,
+  };
+
+  state.agentHistory = state.agentHistory || [];
+  state.agentHistory.push(entry);
+  writeState(ctxDir, state);
+  return entry;
+}
+
+/**
+ * Mark the last invocation of an agent as completed.
+ */
+export function completeAgentInvocation(ctxDir, agentName) {
+  const state = readState(ctxDir);
+  if (!state || !state.agentHistory) return;
+
+  // Find last incomplete invocation of this agent
+  for (let i = state.agentHistory.length - 1; i >= 0; i--) {
+    if (state.agentHistory[i].agent === agentName && !state.agentHistory[i].completedAt) {
+      state.agentHistory[i].completedAt = isoNow();
+      break;
+    }
+  }
+
+  writeState(ctxDir, state);
+}
+
+/**
+ * Record a completed task.
+ */
+export function recordCompletedTask(ctxDir, taskId, title, criteriaIds = []) {
+  const state = readState(ctxDir);
+  if (!state) return;
+
+  state.completedTasks = state.completedTasks || [];
+  state.completedTasks.push({
+    taskId,
+    title,
+    completedAt: isoNow(),
+    criteriaSatisfied: criteriaIds,
+  });
+
+  writeState(ctxDir, state);
+}
+
+/**
+ * Acquire a simple lockfile. Returns true if acquired, false if already locked.
+ */
+export function acquireLock(ctxDir) {
+  const lockPath = path.join(ctxDir, LOCK_FILE);
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, lockedAt: isoNow() }), { flag: 'wx' });
+    return true;
+  } catch {
+    // Check if lock is stale (PID no longer running)
+    try {
+      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+      try {
+        process.kill(lock.pid, 0); // Test if process exists
+        return false; // Process still running, lock is valid
+      } catch {
+        // Process dead, steal the lock
+        fs.unlinkSync(lockPath);
+        return acquireLock(ctxDir);
+      }
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Release the lockfile.
+ */
+export function releaseLock(ctxDir) {
+  const lockPath = path.join(ctxDir, LOCK_FILE);
+  try {
+    fs.unlinkSync(lockPath);
+  } catch {
+    // Already released
+  }
+}
+
+/**
+ * Format state for human-readable display.
+ */
+export function formatStatus(state) {
+  if (!state) return '  No CTX state found. Run /ctx:init to initialize.';
+
+  const lines = [];
+  lines.push(`  Phase:        ${state.phase}`);
+  lines.push(`  Story:        ${state.activeStory || 'none'} ${state.storyTitle ? `— ${state.storyTitle}` : ''}`);
+  lines.push(`  Tasks done:   ${(state.completedTasks || []).length}`);
+  lines.push(`  Agent calls:  ${(state.agentHistory || []).length}`);
+  lines.push(`  Last active:  ${state.session?.lastActivity || 'unknown'}`);
+
+  const nextAction = NEXT_ACTIONS[state.phase];
+  if (nextAction) {
+    lines.push('');
+    lines.push(`  Next action:  ${nextAction}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- internal ---
+
+const NEXT_ACTIONS = {
+  init:     '/ctx:plan — create an execution plan',
+  plan:     '/ctx:execute — start building',
+  execute:  '/ctx:verify — verify acceptance criteria',
+  verify:   '/ctx:next — advance to next story or fix failures',
+  complete: '/ctx:next — pick next story from PRD',
+};
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+// Provide helpful hints for common invalid transitions
+function phaseHint(current, target) {
+  const hints = {
+    'init→execute': ' Run /ctx:plan first to create a plan.',
+    'init→verify': ' Run /ctx:plan then /ctx:execute first.',
+    'plan→verify': ' Run /ctx:execute first to build the code.',
+    'plan→complete': ' Run /ctx:execute then /ctx:verify first.',
+    'execute→complete': ' Run /ctx:verify first to check acceptance criteria.',
+  };
+  return hints[`${current}→${target}`] || '';
+}
+
+export { VALID_PHASES, TRANSITIONS };

package/src/worktree.js

@@ -0,0 +1,244 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { readState, writeState } from './state.js';
+import { buildContext } from './context.js';
+import { runAgent } from './runner.js';
+
+const WORKTREES_DIR = '.ctx/worktrees';
+
+/**
+ * Parse a dependency graph from the parallelizer agent output.
+ * Input format: array of { taskId, title, dependsOn: [taskId] }
+ * Returns waves: [ [task, task], [task], ... ]
+ */
+export function buildWaves(tasks) {
+  if (!tasks || tasks.length === 0) return [];
+
+  const completed = new Set();
+  const waves = [];
+  const remaining = [...tasks];
+  let safetyCounter = 0;
+
+  while (remaining.length > 0 && safetyCounter < 100) {
+    safetyCounter++;
+    const wave = [];
+
+    for (let i = remaining.length - 1; i >= 0; i--) {
+      const task = remaining[i];
+      const deps = task.dependsOn || [];
+      const allDepsComplete = deps.every(d => completed.has(d));
+
+      if (allDepsComplete) {
+        wave.push(task);
+        remaining.splice(i, 1);
+      }
+    }
+
+    if (wave.length === 0) {
+      // Circular dependency — force remaining into a single wave
+      waves.push(remaining.splice(0));
+      break;
+    }
+
+    waves.push(wave);
+    for (const t of wave) completed.add(t.taskId);
+  }
+
+  return waves;
+}
+
+/**
+ * Create a git worktree for a task.
+ * Returns the worktree path.
+ */
+export function createWorktree(projectDir, taskId) {
+  const worktreeBase = path.join(projectDir, WORKTREES_DIR);
+  if (!fs.existsSync(worktreeBase)) fs.mkdirSync(worktreeBase, { recursive: true });
+
+  const worktreePath = path.join(worktreeBase, taskId);
+  const branchName = `ctx-task-${taskId}`;
+
+  try {
+    // Create branch and worktree
+    execSync(`git worktree add "${worktreePath}" -b "${branchName}" HEAD`, {
+      cwd: projectDir, encoding: 'utf-8', timeout: 10000,
+    });
+    return worktreePath;
+  } catch (err) {
+    throw new Error(`Failed to create worktree for ${taskId}: ${err.message}`);
+  }
+}
+
+/**
+ * Merge a worktree branch back to the current branch.
+ * Returns { merged: boolean, conflicts: boolean, error: string|null }
+ */
+export function mergeWorktree(projectDir, taskId) {
+  const branchName = `ctx-task-${taskId}`;
+
+  try {
+    const result = execSync(`git merge --no-ff "${branchName}" -m "ctx(merge): task ${taskId}"`, {
+      cwd: projectDir, encoding: 'utf-8', timeout: 10000,
+    });
+    return { merged: true, conflicts: false, error: null };
+  } catch (err) {
+    if (err.message.includes('CONFLICT') || err.message.includes('Merge conflict')) {
+      // Abort the merge
+      try { execSync('git merge --abort', { cwd: projectDir, timeout: 5000 }); } catch {}
+      return { merged: false, conflicts: true, error: `Merge conflicts in task ${taskId}` };
+    }
+    return { merged: false, conflicts: false, error: err.message };
+  }
+}
+
+/**
+ * Clean up a worktree and its branch.
+ */
+export function cleanupWorktree(projectDir, taskId) {
+  const worktreePath = path.join(projectDir, WORKTREES_DIR, taskId);
+  const branchName = `ctx-task-${taskId}`;
+
+  try {
+    execSync(`git worktree remove "${worktreePath}" --force`, {
+      cwd: projectDir, timeout: 10000,
+    });
+  } catch {
+    // Manual cleanup
+    if (fs.existsSync(worktreePath)) fs.rmSync(worktreePath, { recursive: true, force: true });
+    try { execSync('git worktree prune', { cwd: projectDir, timeout: 5000 }); } catch {}
+  }
+
+  // Delete branch
+  try {
+    execSync(`git branch -D "${branchName}"`, { cwd: projectDir, timeout: 5000 });
+  } catch {}
+}
+
+/**
+ * Execute a wave of tasks in parallel using git worktrees.
+ * Each task runs in its own worktree with a separate claude process.
+ *
+ * Returns { results: [{ taskId, success, error }], conflicts: [taskId] }
+ */
+export async function executeWave({ wave, agentsDir, agentFile, projectDir, ctxDir, streaming = false, timeout = 300000 }) {
+  const agentPath = path.join(agentsDir, agentFile);
+
+  // Create worktrees for all tasks
+  const worktrees = [];
+  for (const task of wave) {
+    try {
+      const wtPath = createWorktree(projectDir, task.taskId);
+      worktrees.push({ task, worktreePath: wtPath });
+    } catch (err) {
+      worktrees.push({ task, worktreePath: null, error: err.message });
+    }
+  }
+
+  // Run agents in parallel (non-streaming for parallel execution)
+  const promises = worktrees.map(async ({ task, worktreePath, error }) => {
+    if (error) return { taskId: task.taskId, success: false, error };
+
+    try {
+      const { context } = buildContext('execute', worktreePath, ctxDir);
+      await runAgent({
+        agentPath,
+        message: `Execute task: ${task.title}\n\n${task.description || ''}`,
+        streaming: false, // Must be non-streaming for parallel
+        timeout,
+        context,
+      });
+      return { taskId: task.taskId, success: true, error: null };
+    } catch (err) {
+      return { taskId: task.taskId, success: false, error: err.message };
+    }
+  });
+
+  const results = await Promise.all(promises);
+
+  // Merge successful worktrees back
+  const conflicts = [];
+  for (const result of results) {
+    if (result.success) {
+      const merge = mergeWorktree(projectDir, result.taskId);
+      if (merge.conflicts) {
+        conflicts.push(result.taskId);
+        result.success = false;
+        result.error = merge.error;
+      }
+    }
+    // Cleanup worktree
+    cleanupWorktree(projectDir, result.taskId);
+  }
+
+  return { results, conflicts };
+}
+
+/**
+ * Execute all waves sequentially (wave N+1 waits for wave N).
+ *
+ * Options:
+ *   waves, agentsDir, agentFile, projectDir, ctxDir, streaming, timeout, onWave
+ *
+ * Returns { waveResults: [...], conflicts: [...] }
+ */
+export async function executeAllWaves({ waves, agentsDir, agentFile, projectDir, ctxDir, streaming = false, timeout = 300000, onWave = null }) {
+  const allResults = [];
+  const allConflicts = [];
+
+  for (let i = 0; i < waves.length; i++) {
+    const wave = waves[i];
+    if (onWave) onWave({ waveIndex: i, total: waves.length, taskCount: wave.length, status: 'starting' });
+
+    const { results, conflicts } = await executeWave({
+      wave, agentsDir, agentFile, projectDir, ctxDir, streaming, timeout,
+    });
+
+    allResults.push({ waveIndex: i, results });
+    allConflicts.push(...conflicts);
+
+    if (onWave) onWave({ waveIndex: i, total: waves.length, taskCount: wave.length, status: 'completed', results });
+
+    // Update state with wave progress
+    const state = readState(ctxDir);
+    if (state) {
+      state.waveProgress = state.waveProgress || [];
+      state.waveProgress.push({
+        waveIndex: i,
+        completedAt: new Date().toISOString(),
+        taskResults: results.map(r => ({ taskId: r.taskId, success: r.success })),
+      });
+      writeState(ctxDir, state);
+    }
+  }
+
+  // Re-queue conflicting tasks as sequential
+  if (allConflicts.length > 0) {
+    const state = readState(ctxDir);
+    if (state) {
+      state.conflictTasks = allConflicts;
+      writeState(ctxDir, state);
+    }
+  }
+
+  return { waveResults: allResults, conflicts: allConflicts };
+}
+
+/**
+ * Format wave execution results for display.
+ */
+export function formatWaveResults(waveResults, conflicts) {
+  const lines = [];
+  for (const wave of waveResults) {
+    lines.push(`  Wave ${wave.waveIndex + 1}:`);
+    for (const r of wave.results) {
+      const icon = r.success ? '✓' : '✗';
+      lines.push(`    ${icon} ${r.taskId}${r.error ? ` — ${r.error}` : ''}`);
+    }
+  }
+  if (conflicts.length > 0) {
+    lines.push('');
+    lines.push(`  ⚠ Merge conflicts (re-queued as sequential): ${conflicts.join(', ')}`);
+  }
+  return lines.join('\n');
+}

package/templates/PRD.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://ctx.dev/schemas/prd.json",
-  "version": "2.1",
+  "version": "3.5",
   "project": {
     "name": "{{project_name}}",
     "description": "{{project_description}}",