ctx-cc 4.1.1 → 4.1.3

package/src/context.js

@@ -1,241 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-
-/**
- * Default context profiles per agent category.
- * Each profile lists which context sources the agent receives.
- *
- * Sources:
- *   state    — .ctx/STATE.json
- *   prd      — .ctx/PRD.json (active story only)
- *   plan     — .ctx/phases/<story>/PLAN.md
- *   repoMap  — .ctx/REPO-MAP.md
- *   gitDiff  — git diff (staged + unstaged)
- *   gitLog   — recent commits
- *   fileTree — directory listing
- *   readme   — README.md first 100 lines
- */
-const DEFAULT_PROFILES = {
-  // Planning agents — need requirements and architecture, not code diffs
-  plan:        ['state', 'prd', 'repoMap', 'readme'],
-  predict:     ['state', 'prd', 'repoMap', 'fileTree'],
-  criteria:    ['state', 'prd'],
-  discuss:     ['state', 'prd', 'repoMap'],
-  parallelize: ['state', 'plan'],
-
-  // Execution agents — need the plan and relevant source files
-  execute:     ['state', 'plan', 'repoMap'],
-  debug:       ['state', 'gitDiff', 'gitLog', 'repoMap'],
-
-  // Review agents — need the diff, not the full tree
-  review:      ['state', 'gitDiff', 'prd'],
-  audit:       ['state', 'gitDiff'],
-  verify:      ['state', 'prd', 'gitDiff'],
-
-  // Mapper agents — need filesystem overview
-  map:         ['fileTree', 'readme'],
-  'arch-map':  ['fileTree', 'readme'],
-  'tech-map':  ['fileTree', 'readme'],
-  'quality-map': ['fileTree'],
-  'concerns-map': ['fileTree', 'gitLog'],
-
-  // Knowledge agents
-  research:    ['state', 'prd', 'repoMap'],
-  learn:       ['state', 'repoMap'],
-  design:      ['state', 'prd', 'readme'],
-
-  // Coordination agents
-  handoff:     ['state'],
-  team:        ['state'],
-  qa:          ['state', 'prd', 'readme'],
-};
-
-// Estimated tokens per source (conservative)
-const SOURCE_TOKEN_ESTIMATES = {
-  state: 500,
-  prd: 1000,
-  plan: 1500,
-  repoMap: 2000,
-  gitDiff: 3000,
-  gitLog: 500,
-  fileTree: 1000,
-  readme: 800,
-};
-
-/**
- * Load context manifest from file, or return defaults.
- */
-export function loadContextManifest(ctxDir) {
-  const manifestPath = path.join(ctxDir, 'context-manifest.json');
-  try {
-    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-  } catch {
-    return DEFAULT_PROFILES;
-  }
-}
-
-/**
- * Get the context profile for an agent command.
- * Checks: agent frontmatter 'context-profile' → manifest → defaults.
- */
-export function getContextProfile(agentCommand, manifest = DEFAULT_PROFILES) {
-  return manifest[agentCommand] || ['state', 'repoMap']; // fallback: minimal
-}
-
-/**
- * Build context string for an agent based on its profile.
- * Returns { context: string, estimatedTokens: number, warnings: string[] }.
- */
-export function buildContext(agentCommand, projectDir, ctxDir, options = {}) {
-  const manifest = loadContextManifest(ctxDir);
-  const sources = getContextProfile(agentCommand, manifest);
-  const tokenLimit = options.tokenLimit || 100_000;
-
-  const sections = [];
-  let estimatedTokens = 0;
-  const warnings = [];
-
-  for (const source of sources) {
-    const { content, tokens } = loadSource(source, projectDir, ctxDir);
-    if (content) {
-      sections.push(content);
-      estimatedTokens += tokens;
-    }
-  }
-
-  if (estimatedTokens > tokenLimit * 0.8) {
-    warnings.push(`Context payload ~${estimatedTokens} tokens (${Math.round(estimatedTokens / tokenLimit * 100)}% of limit). Consider reducing context sources.`);
-  }
-
-  return {
-    context: sections.join('\n\n---\n\n'),
-    estimatedTokens,
-    warnings,
-  };
-}
-
-/**
- * Estimate token count from a string (chars / 4 approximation).
- */
-export function estimateTokens(text) {
-  return Math.ceil((text || '').length / 4);
-}
-
-// --- Source loaders ---
-
-function loadSource(source, projectDir, ctxDir) {
-  const loaders = {
-    state: () => safeRead(path.join(ctxDir, 'STATE.json'), '## Project State\n```json\n', '\n```'),
-    prd: () => loadPrdStory(ctxDir),
-    plan: () => loadCurrentPlan(ctxDir),
-    repoMap: () => safeRead(path.join(ctxDir, 'REPO-MAP.md'), '## Repository Map\n'),
-    gitDiff: () => loadGitDiff(projectDir),
-    gitLog: () => loadGitLog(projectDir),
-    fileTree: () => loadFileTree(projectDir),
-    readme: () => loadReadme(projectDir),
-  };
-
-  const loader = loaders[source];
-  if (!loader) return { content: null, tokens: 0 };
-
-  try {
-    const content = loader();
-    return { content, tokens: estimateTokens(content) };
-  } catch {
-    return { content: null, tokens: 0 };
-  }
-}
-
-function safeRead(filePath, prefix = '', suffix = '') {
-  try {
-    const content = fs.readFileSync(filePath, 'utf-8');
-    return `${prefix}${content}${suffix}`;
-  } catch {
-    return null;
-  }
-}
-
-function loadPrdStory(ctxDir) {
-  try {
-    const prd = JSON.parse(fs.readFileSync(path.join(ctxDir, 'PRD.json'), 'utf-8'));
-    const current = prd.metadata?.currentStory;
-    if (!current) return `## PRD\nProject: ${prd.project?.name || 'unknown'}\nNo active story.`;
-
-    const story = (prd.stories || []).find(s => s.id === current);
-    if (!story) return null;
-
-    return [
-      `## Active Story: ${story.id} — ${story.title}`,
-      story.description,
-      '',
-      '### Acceptance Criteria',
-      ...(story.acceptanceCriteria || []).map((c, i) => `${i + 1}. ${c}`),
-    ].join('\n');
-  } catch {
-    return null;
-  }
-}
-
-function loadCurrentPlan(ctxDir) {
-  try {
-    const state = JSON.parse(fs.readFileSync(path.join(ctxDir, 'STATE.json'), 'utf-8'));
-    const storyId = state.activeStory;
-    if (!storyId) return null;
-
-    const planPath = path.join(ctxDir, 'phases', storyId, 'PLAN.md');
-    return safeRead(planPath, '## Execution Plan\n');
-  } catch {
-    return null;
-  }
-}
-
-function loadGitDiff(projectDir) {
-  try {
-    const diff = execSync('git diff HEAD --stat --no-color 2>/dev/null && echo "---" && git diff HEAD --no-color 2>/dev/null', {
-      cwd: projectDir, encoding: 'utf-8', timeout: 10000, maxBuffer: 1024 * 1024,
-    }).trim();
-    if (!diff || diff === '---') return null;
-    // Truncate if too large
-    const maxChars = 12000; // ~3000 tokens
-    const truncated = diff.length > maxChars ? diff.slice(0, maxChars) + '\n\n... (diff truncated)' : diff;
-    return `## Git Diff\n\`\`\`diff\n${truncated}\n\`\`\``;
-  } catch {
-    return null;
-  }
-}
-
-function loadGitLog(projectDir) {
-  try {
-    const log = execSync('git log --oneline -10 --no-color 2>/dev/null', {
-      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
-    }).trim();
-    return log ? `## Recent Commits\n\`\`\`\n${log}\n\`\`\`` : null;
-  } catch {
-    return null;
-  }
-}
-
-function loadFileTree(projectDir) {
-  try {
-    const tree = execSync(
-      'find . -type f -not -path "./.git/*" -not -path "./node_modules/*" -not -path "./.ctx/*" -not -path "./.next/*" -not -path "./dist/*" -not -path "./.cache/*" | head -200 | sort',
-      { cwd: projectDir, encoding: 'utf-8', timeout: 5000, maxBuffer: 512 * 1024 }
-    ).trim();
-    return tree ? `## File Tree\n\`\`\`\n${tree}\n\`\`\`` : null;
-  } catch {
-    return null;
-  }
-}
-
-function loadReadme(projectDir) {
-  try {
-    const readme = fs.readFileSync(path.join(projectDir, 'README.md'), 'utf-8');
-    const lines = readme.split('\n').slice(0, 100);
-    return `## README (first 100 lines)\n${lines.join('\n')}`;
-  } catch {
-    return null;
-  }
-}
-
-export { DEFAULT_PROFILES };

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 };