ctx-cc 3.5.0 → 4.0.0

package/src/config.js

@@ -0,0 +1,112 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '..');
+
+const DEFAULT_CONFIG_PATH = path.join(packageRoot, 'templates', 'config.json');
+
+/**
+ * Load config from a path, falling back to defaults.
+ */
+export function loadConfig(configPath) {
+  const defaults = safeReadJson(DEFAULT_CONFIG_PATH) || {};
+  const user = (configPath ? safeReadJson(configPath) : null) || {};
+  return deepMerge(defaults, user);
+}
+
+/**
+ * Get a nested value by dot-notation key.
+ * getByPath({ a: { b: 1 } }, 'a.b') → 1
+ */
+export function getByPath(obj, key) {
+  return key.split('.').reduce((o, k) => (o != null ? o[k] : undefined), obj);
+}
+
+/**
+ * Set a nested value by dot-notation key.
+ * setByPath({}, 'a.b', 1) → { a: { b: 1 } }
+ */
+export function setByPath(obj, key, value) {
+  const keys = key.split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (current[keys[i]] == null || typeof current[keys[i]] !== 'object') {
+      current[keys[i]] = {};
+    }
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = coerceValue(value);
+  return obj;
+}
+
+/**
+ * List all config keys as flat dot-notation paths.
+ */
+export function flattenKeys(obj, prefix = '') {
+  const keys = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      keys.push(...flattenKeys(v, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+  return keys;
+}
+
+/**
+ * Save config to a JSON file.
+ */
+export function saveConfig(configPath, config) {
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Format config as a readable table.
+ */
+export function formatConfigTable(config) {
+  const keys = flattenKeys(config);
+  const maxKey = Math.max(20, ...keys.map(k => k.length));
+  const lines = keys.map(k => {
+    const val = getByPath(config, k);
+    return `  ${k.padEnd(maxKey)}  ${JSON.stringify(val)}`;
+  });
+  return lines.join('\n');
+}
+
+// --- internal ---
+
+function safeReadJson(filepath) {
+  try {
+    return JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const [key, val] of Object.entries(source)) {
+    if (val && typeof val === 'object' && !Array.isArray(val) && target[key] && typeof target[key] === 'object') {
+      result[key] = deepMerge(target[key], val);
+    } else {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+function coerceValue(str) {
+  if (str === 'true') return true;
+  if (str === 'false') return false;
+  if (str === 'null') return null;
+  if (/^\d+$/.test(str)) return parseInt(str, 10);
+  if (/^\d+\.\d+$/.test(str)) return parseFloat(str);
+  return str;
+}

package/src/context.js

@@ -0,0 +1,241 @@
+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

@@ -0,0 +1,156 @@
+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);
+}