ctx-cc 4.1.1 → 4.1.2

package/src/handoff.js

@@ -1,156 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { readState } from './state.js';
-
-const HANDOFF_FILE = 'HANDOFF.json';
-const HANDOFFS_DIR = 'handoffs';
-
-/**
- * Create a handoff file from current state.
- * Serializes state + generates a human-readable context summary.
- */
-export function createHandoff(ctxDir) {
-  const state = readState(ctxDir);
-  if (!state) {
-    throw new Error('No STATE.json found. Nothing to pause.');
-  }
-
-  const handoff = {
-    version: '4.0',
-    createdAt: new Date().toISOString(),
-    state: { ...state },
-    summary: generateSummary(state),
-    nextAction: getNextAction(state),
-    decisions: extractDecisions(ctxDir),
-  };
-
-  // Archive existing handoff if present
-  archiveHandoff(ctxDir);
-
-  // Write new handoff
-  const handoffPath = path.join(ctxDir, HANDOFF_FILE);
-  fs.writeFileSync(handoffPath, JSON.stringify(handoff, null, 2) + '\n');
-
-  return handoff;
-}
-
-/**
- * Read a handoff file. Returns null if not found.
- */
-export function readHandoff(ctxDir) {
-  const handoffPath = path.join(ctxDir, HANDOFF_FILE);
-  try {
-    return JSON.parse(fs.readFileSync(handoffPath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Resume from a handoff. Restores state and returns context for continuation.
- */
-export function resumeFromHandoff(ctxDir) {
-  const handoff = readHandoff(ctxDir);
-  if (!handoff) {
-    throw new Error('No paused session found. Run /ctx:pause first to create a checkpoint.');
-  }
-
-  // Clean up handoff file after resume
-  const handoffPath = path.join(ctxDir, HANDOFF_FILE);
-  archiveHandoff(ctxDir);
-
-  return handoff;
-}
-
-/**
- * Format handoff for human-readable display.
- */
-export function formatHandoff(handoff) {
-  if (!handoff) return '  No paused session found.';
-
-  const lines = [
-    `  Paused at:    ${handoff.createdAt}`,
-    `  Phase:        ${handoff.state?.phase || 'unknown'}`,
-    `  Story:        ${handoff.state?.activeStory || 'none'} ${handoff.state?.storyTitle ? `— ${handoff.state.storyTitle}` : ''}`,
-    `  Tasks done:   ${(handoff.state?.completedTasks || []).length}`,
-    '',
-    '  Summary:',
-    `    ${handoff.summary}`,
-    '',
-    `  Next action:  ${handoff.nextAction}`,
-  ];
-
-  if (handoff.decisions && handoff.decisions.length > 0) {
-    lines.push('', '  Key decisions:');
-    for (const d of handoff.decisions) {
-      lines.push(`    - ${d}`);
-    }
-  }
-
-  return lines.join('\n');
-}
-
-// --- internal ---
-
-function generateSummary(state) {
-  const parts = [`Phase: ${state.phase}`];
-
-  if (state.activeStory) {
-    parts.push(`Working on: ${state.activeStory} ${state.storyTitle ? `(${state.storyTitle})` : ''}`);
-  }
-
-  const taskCount = (state.completedTasks || []).length;
-  if (taskCount > 0) {
-    parts.push(`Completed ${taskCount} task(s)`);
-    const lastTask = state.completedTasks[taskCount - 1];
-    parts.push(`Last completed: ${lastTask.title}`);
-  }
-
-  const agentCount = (state.agentHistory || []).length;
-  if (agentCount > 0) {
-    const lastAgent = state.agentHistory[agentCount - 1];
-    parts.push(`Last agent: ${lastAgent.agent} (${lastAgent.taskSummary})`);
-  }
-
-  return parts.join('. ');
-}
-
-function getNextAction(state) {
-  const actions = {
-    init: 'Run /ctx:plan to create an execution plan',
-    plan: 'Run /ctx:execute to start building',
-    execute: 'Continue execution or run /ctx:verify',
-    verify: 'Check verification results and advance',
-    complete: 'Pick next story from PRD',
-  };
-  return actions[state.phase] || 'Run /ctx:status to check state';
-}
-
-function extractDecisions(ctxDir) {
-  // Try to read CONTEXT.md for decisions
-  try {
-    const contextPath = path.join(ctxDir, 'CONTEXT.md');
-    const content = fs.readFileSync(contextPath, 'utf-8');
-    const decisions = [];
-    for (const line of content.split('\n')) {
-      if (line.startsWith('- ') && (line.includes('decision') || line.includes('chose') || line.includes('decided'))) {
-        decisions.push(line.slice(2));
-      }
-    }
-    return decisions;
-  } catch {
-    return [];
-  }
-}
-
-function archiveHandoff(ctxDir) {
-  const handoffPath = path.join(ctxDir, HANDOFF_FILE);
-  if (!fs.existsSync(handoffPath)) return;
-
-  const archiveDir = path.join(ctxDir, HANDOFFS_DIR);
-  if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir, { recursive: true });
-
-  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const archivePath = path.join(archiveDir, `HANDOFF-${timestamp}.json`);
-  fs.renameSync(handoffPath, archivePath);
-}

package/src/hooks.js

@@ -1,218 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { readState, writeState } from './state.js';
-
-const CTX_HOOK_MARKER = '// CTX_HOOKS';
-
-/**
- * Hook definitions that CTX generates for Claude Code settings.json.
- * Each hook has: event, matcher (optional), command, description.
- */
-const HOOK_DEFINITIONS = {
-  // Record agent completion in STATE.json
-  subagentCompletion: {
-    event: 'SubagentStop',
-    command: `node -e "
-      const fs=require('fs'),p=require('path');
-      const d=p.join(process.cwd(),'.ctx','STATE.json');
-      if(!fs.existsSync(d))process.exit(0);
-      const s=JSON.parse(fs.readFileSync(d,'utf-8'));
-      const h=s.agentHistory||[];
-      for(let i=h.length-1;i>=0;i--){
-        if(!h[i].completedAt){h[i].completedAt=new Date().toISOString();break;}
-      }
-      s.session={...s.session,lastActivity:new Date().toISOString()};
-      fs.writeFileSync(d,JSON.stringify(s,null,2)+'\\n');
-    "`,
-    description: 'Record agent completion in STATE.json',
-    configKey: 'hooks.subagentCompletion',
-    default: true,
-  },
-
-  // Block commits without test file changes
-  blockCommitWithoutTests: {
-    event: 'PreToolUse',
-    matcher: 'Bash',
-    command: `node -e "
-      const cmd=process.env.TOOL_INPUT||'';
-      if(!/git commit/.test(cmd))process.exit(0);
-      const {execSync}=require('child_process');
-      try{
-        const diff=execSync('git diff --cached --name-only',{encoding:'utf-8'});
-        const files=diff.trim().split('\\n');
-        const hasCode=files.some(f=>/\\.(js|ts|jsx|tsx|py|go|rs)$/.test(f));
-        const hasTest=files.some(f=>/\\.(test|spec)\\.|__tests__/.test(f));
-        if(hasCode&&!hasTest){
-          console.error('CTX: Commit blocked — code changes without tests.');
-          console.error('Files: '+files.filter(f=>/\\.(js|ts|jsx|tsx|py|go|rs)$/.test(f)).join(', '));
-          process.exit(2);
-        }
-      }catch{}
-    "`,
-    description: 'Block commits without corresponding test changes',
-    configKey: 'hooks.blockCommitWithoutTests',
-    default: false,
-  },
-
-  // Enforce TDD mode (strict/warn/off)
-  tddEnforcement: {
-    event: 'PreToolUse',
-    matcher: 'Bash',
-    command: `node -e "
-      const cmd=process.env.TOOL_INPUT||'';
-      if(!/git commit/.test(cmd))process.exit(0);
-      const fs=require('fs'),p=require('path');
-      const cfgPath=p.join(process.cwd(),'.ctx','config.json');
-      let mode='off';
-      try{const c=JSON.parse(fs.readFileSync(cfgPath,'utf-8'));mode=c.hooks?.tddMode||'off';}catch{}
-      if(mode==='off')process.exit(0);
-      const {execSync}=require('child_process');
-      try{
-        const diff=execSync('git diff --cached --name-only',{encoding:'utf-8'});
-        const files=diff.trim().split('\\n');
-        const hasCode=files.some(f=>/\\.(js|ts|jsx|tsx|py|go|rs)$/.test(f)&&!/\\.(test|spec)\\.|__tests__/.test(f));
-        const hasTest=files.some(f=>/\\.(test|spec)\\.|__tests__/.test(f));
-        if(hasCode&&!hasTest){
-          if(mode==='strict'){
-            console.error('CTX TDD: Commit blocked — write tests first.');
-            process.exit(2);
-          }else if(mode==='warn'){
-            console.error('CTX TDD Warning: Code changes without tests.');
-          }
-        }
-      }catch{}
-    "`,
-    description: 'TDD enforcement (strict/warn/off)',
-    configKey: 'hooks.tddMode',
-    default: 'off',
-  },
-};
-
-/**
- * Generate Claude Code hooks section for settings.json.
- * Reads current config to determine which hooks are enabled.
- *
- * Returns an array of hook objects ready for settings.json.
- */
-export function generateHooks(config = {}) {
-  const hooks = [];
-  const hooksConfig = config.hooks || {};
-
-  for (const [key, def] of Object.entries(HOOK_DEFINITIONS)) {
-    const configValue = getNestedValue(hooksConfig, key);
-    const enabled = configValue !== undefined ? configValue : def.default;
-
-    // Skip disabled hooks
-    if (enabled === false || enabled === 'off') continue;
-
-    const hook = {
-      type: def.event,
-      command: `${CTX_HOOK_MARKER} ${def.command.replace(/\n\s*/g, ' ').trim()}`,
-    };
-
-    if (def.matcher) {
-      hook.matcher = def.matcher;
-    }
-
-    hooks.push(hook);
-  }
-
-  return hooks;
-}
-
-/**
- * Write hooks to .claude/settings.json, preserving user's existing hooks.
- */
-export function syncHooks(settingsDir, config = {}) {
-  const settingsPath = path.join(settingsDir, 'settings.json');
-  let settings = {};
-
-  // Read existing settings
-  try {
-    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-  } catch {}
-
-  // Preserve user hooks (non-CTX)
-  const existingHooks = settings.hooks || {};
-  const userHooks = {};
-
-  for (const [event, hookList] of Object.entries(existingHooks)) {
-    if (Array.isArray(hookList)) {
-      userHooks[event] = hookList.filter(h => !h.command?.includes(CTX_HOOK_MARKER));
-    }
-  }
-
-  // Generate CTX hooks
-  const ctxHooks = generateHooks(config);
-
-  // Merge: group by event type
-  const merged = { ...userHooks };
-  for (const hook of ctxHooks) {
-    const event = hook.type;
-    if (!merged[event]) merged[event] = [];
-    merged[event].push({
-      matcher: hook.matcher || undefined,
-      command: hook.command,
-    });
-  }
-
-  // Clean up empty arrays
-  for (const [key, val] of Object.entries(merged)) {
-    if (Array.isArray(val) && val.length === 0) delete merged[key];
-  }
-
-  settings.hooks = merged;
-
-  // Write back
-  if (!fs.existsSync(settingsDir)) fs.mkdirSync(settingsDir, { recursive: true });
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-
-  return { hooksGenerated: ctxHooks.length, settingsPath };
-}
-
-/**
- * List all available hooks with their current status.
- */
-export function listHooks(config = {}) {
-  const hooksConfig = config.hooks || {};
-  const result = [];
-
-  for (const [key, def] of Object.entries(HOOK_DEFINITIONS)) {
-    const configValue = getNestedValue(hooksConfig, key);
-    const status = configValue !== undefined ? configValue : def.default;
-
-    result.push({
-      key,
-      event: def.event,
-      description: def.description,
-      configKey: def.configKey,
-      status: status === false ? 'disabled' : status === true ? 'enabled' : String(status),
-      default: def.default,
-    });
-  }
-
-  return result;
-}
-
-/**
- * Format hooks list for display.
- */
-export function formatHooksList(hooks) {
-  const lines = [];
-  const maxKey = Math.max(20, ...hooks.map(h => h.configKey.length));
-
-  for (const h of hooks) {
-    const icon = h.status === 'disabled' || h.status === 'off' ? '○' : '●';
-    lines.push(`  ${icon} ${h.configKey.padEnd(maxKey)}  ${h.status.padEnd(10)}  ${h.description}`);
-  }
-
-  return lines.join('\n');
-}
-
-// --- internal ---
-
-function getNestedValue(obj, key) {
-  return key.split('.').reduce((o, k) => o?.[k], obj);
-}
-
-export { HOOK_DEFINITIONS, CTX_HOOK_MARKER };

package/src/lifecycle.js

@@ -1,194 +0,0 @@
-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$/, '');
-}