ctx-cc 3.5.0 → 4.0.0

package/src/agents.js

@@ -0,0 +1,109 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Parse YAML-like frontmatter from a markdown file.
+ * Returns { attrs: {}, body: string } or null if no frontmatter.
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+
+  const attrs = {};
+  for (const line of match[1].split('\n')) {
+    const sep = line.indexOf(':');
+    if (sep === -1) continue;
+    const key = line.slice(0, sep).trim();
+    const val = line.slice(sep + 1).trim();
+    attrs[key] = val;
+  }
+
+  return { attrs, body: match[2] };
+}
+
+/**
+ * Derive a CLI command name from an agent filename.
+ * ctx-planner.md → plan
+ * ctx-arch-mapper.md → arch-map
+ * ctx-quality-mapper.md → quality-map
+ */
+export function deriveCommandName(filename) {
+  const base = filename.replace(/\.md$/, '').replace(/^ctx-/, '');
+
+  // Special mapping: *-mapper → *-map (shorter CLI names)
+  if (base.endsWith('-mapper')) return base.replace(/-mapper$/, '-map');
+  // Special mapping: *-suggester → base (e.g. criteria-suggester → criteria)
+  if (base.endsWith('-suggester')) return base.replace(/-suggester$/, '');
+  // Special mapping: *-coordinator → coordinate
+  if (base.endsWith('-coordinator')) return base.replace(/-coordinator$/, '');
+
+  // Common verb forms for shorter commands
+  const verbMap = {
+    'planner': 'plan',
+    'executor': 'execute',
+    'researcher': 'research',
+    'debugger': 'debug',
+    'reviewer': 'review',
+    'designer': 'design',
+    'verifier': 'verify',
+    'discusser': 'discuss',
+    'learner': 'learn',
+    'predictor': 'predict',
+    'auditor': 'audit',
+    'parallelizer': 'parallelize',
+    'mapper': 'map',
+    'handoff': 'handoff',
+    'team': 'team',
+    'qa': 'qa',
+  };
+
+  return verbMap[base] || base;
+}
+
+/**
+ * Discover all agents from a directory.
+ * Returns an array of { file, command, name, description, tools, color }.
+ */
+export function discoverAgents(agentsDir) {
+  if (!fs.existsSync(agentsDir)) return [];
+
+  const agents = [];
+  const entries = fs.readdirSync(agentsDir).filter(f => f.startsWith('ctx-') && f.endsWith('.md')).sort();
+
+  for (const file of entries) {
+    try {
+      const content = fs.readFileSync(path.join(agentsDir, file), 'utf-8');
+      const fm = parseFrontmatter(content);
+      if (!fm || !fm.attrs.name) {
+        process.stderr.write(`Warning: skipping ${file} (missing or invalid frontmatter)\n`);
+        continue;
+      }
+
+      agents.push({
+        file,
+        command: deriveCommandName(file),
+        name: fm.attrs.name,
+        description: fm.attrs.description || '',
+        tools: fm.attrs.tools || '',
+        color: fm.attrs.color || 'white',
+      });
+    } catch (err) {
+      process.stderr.write(`Warning: skipping ${file} (${err.message})\n`);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Format agents as a table for display.
+ */
+export function formatAgentTable(agents) {
+  const maxCmd = Math.max(12, ...agents.map(a => a.command.length));
+  const header = `  ${'Command'.padEnd(maxCmd)}  Description`;
+  const sep = `  ${'─'.repeat(maxCmd)}  ${'─'.repeat(50)}`;
+
+  const rows = agents.map(a => `  ${a.command.padEnd(maxCmd)}  ${a.description}`);
+
+  return [header, sep, ...rows].join('\n');
+}

package/src/auto.js

@@ -0,0 +1,287 @@
+import fs from 'fs';
+import path from 'path';
+import { readState, writeState, initState, transitionPhase } from './state.js';
+import { executePipeline } from './pipeline.js';
+import { runReviewGate, isReviewGateEnabled } from './review-gate.js';
+import { selectStory, listPendingStories } from './lifecycle.js';
+import { commitTask } from './commits.js';
+
+const STOP_FILE = 'STOP';
+const AUTO_LOG = 'AUTO-LOG.md';
+
+const DEFAULTS = {
+  maxIterationsPerStory: 5,
+  maxTotalTimeMs: 2 * 60 * 60 * 1000, // 2 hours
+  pipeline: ['plan', 'execute'],
+};
+
+/**
+ * Run autonomous execution loop across all P1 stories (or a single story).
+ *
+ * Options:
+ *   ctxDir, projectDir, agentsDir, config
+ *   storyId      — single story to process (null = all P1)
+ *   retryFailed  — only retry previously failed stories
+ *   streaming    — stream agent output
+ *   timeout      — per-agent timeout in ms
+ *   onEvent      — callback({ type, story, message, ... })
+ */
+export async function runAutoLoop({ ctxDir, projectDir, agentsDir, config = {}, storyId = null, retryFailed = false, streaming = true, timeout = 300000, onEvent = null }) {
+  const maxIterations = config.maxIterationsPerStory || DEFAULTS.maxIterationsPerStory;
+  const maxTime = config.maxTotalTimeMs || DEFAULTS.maxTotalTimeMs;
+  const startTime = Date.now();
+
+  // Initialize auto log
+  const logPath = path.join(ctxDir, AUTO_LOG);
+  appendLog(logPath, `# CTX Auto Loop — ${new Date().toISOString()}\n`);
+
+  // Determine stories to process
+  const stories = resolveStories(ctxDir, storyId, retryFailed);
+  if (stories.length === 0) {
+    emit(onEvent, { type: 'no_stories', message: 'No stories to process.' });
+    return { completed: [], failed: [], skipped: [], totalTime: 0 };
+  }
+
+  emit(onEvent, { type: 'start', storyCount: stories.length, maxIterations, maxTime });
+  appendLog(logPath, `\nProcessing ${stories.length} stories. Max ${maxIterations} iterations each.\n`);
+
+  const completed = [];
+  const failed = [];
+  const skipped = [];
+
+  for (const story of stories) {
+    // Check stop file
+    if (shouldStop(ctxDir)) {
+      emit(onEvent, { type: 'stopped', message: 'STOP file detected. Halting after current story.' });
+      appendLog(logPath, `\n⏹ Stopped by STOP file at ${new Date().toISOString()}\n`);
+      skipped.push(...stories.slice(stories.indexOf(story)));
+      break;
+    }
+
+    // Check time limit
+    if (Date.now() - startTime > maxTime) {
+      emit(onEvent, { type: 'timeout', message: `Time limit (${maxTime / 1000 / 60}min) exceeded.` });
+      appendLog(logPath, `\n⏱ Time limit exceeded at ${new Date().toISOString()}\n`);
+      skipped.push(...stories.slice(stories.indexOf(story)));
+      break;
+    }
+
+    emit(onEvent, { type: 'story_start', story: story.id, title: story.title });
+    appendLog(logPath, `\n## ${story.id} — ${story.title}\nStarted: ${new Date().toISOString()}\n`);
+
+    const result = await processStory({
+      story, ctxDir, projectDir, agentsDir, config,
+      maxIterations, streaming, timeout, onEvent, logPath,
+    });
+
+    if (result.success) {
+      completed.push(story.id);
+      appendLog(logPath, `Result: ✓ COMPLETED (${result.iterations} iterations)\n`);
+    } else {
+      failed.push({ id: story.id, reason: result.reason });
+      appendLog(logPath, `Result: ✗ FAILED — ${result.reason}\n`);
+    }
+  }
+
+  // Write summary
+  const totalTime = Date.now() - startTime;
+  const summary = buildSummary(completed, failed, skipped, totalTime);
+  appendLog(logPath, `\n---\n${summary}`);
+
+  emit(onEvent, { type: 'complete', completed, failed, skipped, totalTime });
+
+  // Clean up stop file if it exists
+  cleanupStopFile(ctxDir);
+
+  return { completed, failed, skipped, totalTime };
+}
+
+/**
+ * Create a STOP file to gracefully halt the auto loop.
+ */
+export function createStopFile(ctxDir) {
+  const stopPath = path.join(ctxDir, STOP_FILE);
+  fs.writeFileSync(stopPath, `Stop requested at ${new Date().toISOString()}\n`);
+}
+
+/**
+ * Format auto loop results for display.
+ */
+export function formatAutoResult({ completed, failed, skipped, totalTime }) {
+  const lines = [];
+  const mins = Math.round(totalTime / 1000 / 60);
+
+  lines.push(`  Total time: ${mins} minutes`);
+  lines.push('');
+
+  if (completed.length > 0) {
+    lines.push(`  ✓ Completed (${completed.length}):`);
+    for (const id of completed) lines.push(`    ${id}`);
+  }
+
+  if (failed.length > 0) {
+    lines.push(`  ✗ Failed (${failed.length}):`);
+    for (const f of failed) lines.push(`    ${f.id} — ${f.reason}`);
+  }
+
+  if (skipped.length > 0) {
+    lines.push(`  ○ Skipped (${skipped.length}):`);
+    for (const s of skipped) lines.push(`    ${s.id || s}`);
+  }
+
+  if (failed.length > 0) {
+    lines.push('');
+    lines.push('  Retry failed: ctx-cc auto --retry-failed');
+  }
+
+  return lines.join('\n');
+}
+
+// --- internal ---
+
+async function processStory({ story, ctxDir, projectDir, agentsDir, config, maxIterations, streaming, timeout, onEvent, logPath }) {
+  // Select story
+  selectStory(ctxDir, story.id);
+
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    emit(onEvent, { type: 'iteration', story: story.id, iteration, max: maxIterations });
+    appendLog(logPath, `  Iteration ${iteration}/${maxIterations}: `);
+
+    // Run pipeline: plan → execute
+    try {
+      transitionPhase(ctxDir, 'init'); // Reset to init for fresh pipeline
+      const pipeResult = await executePipeline({
+        steps: ['plan', 'execute'],
+        message: `Implement story ${story.id}: ${story.title}\n\n${story.description || ''}\n\nAcceptance criteria:\n${(story.acceptanceCriteria || []).map((c, i) => `${i + 1}. ${c}`).join('\n')}`,
+        ctxDir, projectDir, agentsDir,
+        streaming, timeout,
+      });
+
+      if (pipeResult.failed) {
+        appendLog(logPath, `pipeline failed at ${pipeResult.failed}\n`);
+        if (iteration === maxIterations) {
+          return { success: false, iterations: iteration, reason: `Pipeline failed: ${pipeResult.error}` };
+        }
+        continue; // Retry
+      }
+    } catch (err) {
+      appendLog(logPath, `pipeline error: ${err.message}\n`);
+      if (iteration === maxIterations) {
+        return { success: false, iterations: iteration, reason: err.message };
+      }
+      continue;
+    }
+
+    // Run review gate (if enabled)
+    if (isReviewGateEnabled(config)) {
+      try {
+        const reviewResult = await runReviewGate({
+          ctxDir, projectDir, agentsDir, streaming, timeout, config,
+        });
+
+        if (reviewResult.escalated) {
+          return { success: false, iterations: iteration, reason: 'Review loop exceeded — human review required.' };
+        }
+
+        if (!reviewResult.passed) {
+          appendLog(logPath, `review failed (cycle ${reviewResult.cycle})\n`);
+          if (iteration === maxIterations) {
+            return { success: false, iterations: iteration, reason: `Review failed: ${reviewResult.feedback}` };
+          }
+          continue; // Retry with feedback
+        }
+      } catch (err) {
+        appendLog(logPath, `review error: ${err.message}\n`);
+        // Review errors don't block — continue
+      }
+    }
+
+    // If we get here, story passed
+    appendLog(logPath, `passed\n`);
+
+    // Commit
+    commitTask({
+      projectDir, ctxDir,
+      agentName: 'auto',
+      taskId: story.id,
+      taskTitle: story.title,
+      criteriaIds: story.acceptanceCriteria || [],
+    });
+
+    // Mark story as passed in PRD
+    markStoryPassed(ctxDir, story.id);
+
+    return { success: true, iterations: iteration, reason: null };
+  }
+
+  return { success: false, iterations: maxIterations, reason: `Max iterations (${maxIterations}) exceeded.` };
+}
+
+function resolveStories(ctxDir, storyId, retryFailed) {
+  if (storyId) {
+    // Single story mode
+    try {
+      const prd = JSON.parse(fs.readFileSync(path.join(ctxDir, 'PRD.json'), 'utf-8'));
+      const story = (prd.stories || []).find(s => s.id === storyId);
+      return story ? [story] : [];
+    } catch {
+      return [];
+    }
+  }
+
+  const pending = listPendingStories(ctxDir);
+
+  if (retryFailed) {
+    // Read auto log for failed stories
+    const state = readState(ctxDir);
+    const failedIds = new Set((state?.autoFailedStories || []).map(f => f.id || f));
+    return pending.filter(s => failedIds.has(s.id));
+  }
+
+  // All P1 stories first, then P2, etc.
+  return pending.sort((a, b) => (a.priority || 99) - (b.priority || 99));
+}
+
+function markStoryPassed(ctxDir, storyId) {
+  try {
+    const prdPath = path.join(ctxDir, 'PRD.json');
+    const prd = JSON.parse(fs.readFileSync(prdPath, 'utf-8'));
+    const story = (prd.stories || []).find(s => s.id === storyId);
+    if (story) {
+      story.passes = true;
+      story.verifiedAt = new Date().toISOString();
+      prd.metadata = prd.metadata || {};
+      prd.metadata.passedStories = (prd.metadata.passedStories || 0) + 1;
+      fs.writeFileSync(prdPath, JSON.stringify(prd, null, 2) + '\n');
+    }
+  } catch {}
+}
+
+function shouldStop(ctxDir) {
+  return fs.existsSync(path.join(ctxDir, STOP_FILE));
+}
+
+function cleanupStopFile(ctxDir) {
+  const stopPath = path.join(ctxDir, STOP_FILE);
+  try { fs.unlinkSync(stopPath); } catch {}
+}
+
+function appendLog(logPath, text) {
+  fs.appendFileSync(logPath, text);
+}
+
+function buildSummary(completed, failed, skipped, totalTime) {
+  const mins = Math.round(totalTime / 1000 / 60);
+  return [
+    `## Summary`,
+    `- Completed: ${completed.length}`,
+    `- Failed: ${failed.length}`,
+    `- Skipped: ${skipped.length}`,
+    `- Total time: ${mins} minutes`,
+    `- Finished: ${new Date().toISOString()}`,
+  ].join('\n') + '\n';
+}
+
+function emit(fn, event) {
+  if (fn) fn(event);
+}

package/src/capabilities.js

@@ -0,0 +1,171 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Default capability manifests per agent category.
+ * Defines which tools each agent type is allowed to use.
+ */
+const DEFAULT_CAPABILITIES = {
+  // Planning agents — read-only + write plans
+  planning: {
+    agents: ['ctx-planner.md', 'ctx-predictor.md', 'ctx-criteria-suggester.md', 'ctx-parallelizer.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Write', 'Agent', 'AskUserQuestion'],
+    denied: ['Edit', 'Bash', 'NotebookEdit'],
+    reason: 'Planning agents should not modify code directly.',
+  },
+
+  // Execution agents — full code access, no orchestration
+  execution: {
+    agents: ['ctx-executor.md', 'ctx-debugger.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'],
+    denied: ['Agent'],
+    reason: 'Execution agents should not spawn other agents.',
+  },
+
+  // Review agents — read + run tests, no modifications
+  review: {
+    agents: ['ctx-reviewer.md', 'ctx-auditor.md', 'ctx-verifier.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash'],
+    denied: ['Write', 'Edit', 'NotebookEdit'],
+    reason: 'Review agents should not modify code.',
+  },
+
+  // Mapper agents — read-only analysis
+  mapping: {
+    agents: ['ctx-mapper.md', 'ctx-arch-mapper.md', 'ctx-tech-mapper.md', 'ctx-quality-mapper.md', 'ctx-concerns-mapper.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'Write'],
+    denied: ['Edit'],
+    reason: 'Mapper agents analyze but should not modify existing code.',
+  },
+
+  // Knowledge agents — read + web research
+  knowledge: {
+    agents: ['ctx-researcher.md', 'ctx-learner.md'],
+    allowed: ['Read', 'Glob', 'Grep', 'Bash', 'Write', 'WebSearch', 'WebFetch'],
+    denied: ['Edit'],
+    reason: 'Knowledge agents gather info but should not modify code.',
+  },
+
+  // Coordination agents — state management
+  coordination: {
+    agents: ['ctx-team-coordinator.md', 'ctx-handoff.md', 'ctx-discusser.md'],
+    allowed: ['Read', 'Write', 'Glob', 'Grep', 'AskUserQuestion'],
+    denied: ['Edit', 'Bash'],
+    reason: 'Coordination agents manage state, not code.',
+  },
+
+  // Design agents — read + generate
+  design: {
+    agents: ['ctx-designer.md'],
+    allowed: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
+    denied: [],
+    reason: 'Design agents may need full access for asset generation.',
+  },
+
+  // QA agents — full read + browser
+  qa: {
+    agents: ['ctx-qa.md'],
+    allowed: ['Read', 'Write', 'Glob', 'Grep', 'Bash'],
+    denied: ['Edit'],
+    reason: 'QA agents test but should not fix code.',
+  },
+};
+
+/**
+ * Load capability manifest from file, or return defaults.
+ */
+export function loadCapabilityManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return DEFAULT_CAPABILITIES;
+  }
+}
+
+/**
+ * Find the category for a given agent file.
+ */
+export function findAgentCategory(agentFile, manifest = DEFAULT_CAPABILITIES) {
+  for (const [category, config] of Object.entries(manifest)) {
+    if (config.agents.includes(agentFile)) {
+      return { category, ...config };
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a tool is allowed for an agent.
+ * Returns { allowed: boolean, reason: string|null }.
+ */
+export function checkToolAllowed(agentFile, toolName, manifest = DEFAULT_CAPABILITIES) {
+  const category = findAgentCategory(agentFile, manifest);
+  if (!category) {
+    // Unknown agent — allow everything (permissive for custom agents)
+    return { allowed: true, reason: null };
+  }
+
+  if (category.denied.includes(toolName)) {
+    return {
+      allowed: false,
+      reason: `Tool "${toolName}" denied for ${category.category} agents. ${category.reason}`,
+    };
+  }
+
+  return { allowed: true, reason: null };
+}
+
+/**
+ * Generate a PreToolUse hook command that enforces capability restrictions.
+ * Returns the hook command string.
+ */
+export function generateCapabilityHookCommand(ctxDir) {
+  return `node -e "
+    const fs=require('fs'),p=require('path');
+    const tool=process.env.TOOL_NAME||'';
+    const agent=process.env.CURRENT_AGENT||'';
+    if(!agent||!tool)process.exit(0);
+    const mPath=p.join('${ctxDir}','capability-manifest.json');
+    let manifest;
+    try{manifest=JSON.parse(fs.readFileSync(mPath,'utf-8'));}catch{process.exit(0);}
+    for(const[cat,cfg]of Object.entries(manifest)){
+      if(cfg.agents.includes(agent)&&cfg.denied.includes(tool)){
+        console.error('CTX: Tool '+tool+' blocked for '+cat+' agent '+agent);
+        const logDir=p.join('${ctxDir}','violations.log');
+        fs.appendFileSync(logDir,new Date().toISOString()+' | '+agent+' | '+tool+' | BLOCKED\\n');
+        process.exit(2);
+      }
+    }
+  "`.replace(/\n\s*/g, ' ').trim();
+}
+
+/**
+ * Save default capability manifest to .ctx/ for customization.
+ */
+export function saveCapabilityManifest(ctxDir) {
+  const manifestPath = path.join(ctxDir, 'capability-manifest.json');
+  if (!fs.existsSync(ctxDir)) fs.mkdirSync(ctxDir, { recursive: true });
+  fs.writeFileSync(manifestPath, JSON.stringify(DEFAULT_CAPABILITIES, null, 2) + '\n');
+  return manifestPath;
+}
+
+/**
+ * Format capabilities for display.
+ */
+export function formatCapabilities(manifest = DEFAULT_CAPABILITIES) {
+  const lines = [];
+  for (const [category, config] of Object.entries(manifest)) {
+    lines.push(`  ${category}:`);
+    lines.push(`    Agents:  ${config.agents.map(a => a.replace('ctx-', '').replace('.md', '')).join(', ')}`);
+    lines.push(`    Allowed: ${config.allowed.join(', ')}`);
+    if (config.denied.length > 0) {
+      lines.push(`    Denied:  ${config.denied.join(', ')}`);
+    }
+    lines.push(`    Reason:  ${config.reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export { DEFAULT_CAPABILITIES };

package/src/commits.js

@@ -0,0 +1,94 @@
+import { execSync } from 'child_process';
+import { readState, writeState, recordCompletedTask } from './state.js';
+
+/**
+ * Create an atomic git commit for a completed task.
+ *
+ * Checks that there are staged or unstaged changes before committing.
+ * Commit message format: ctx(<agent>): <task-title>
+ * Body includes acceptance criteria satisfied.
+ *
+ * Returns { committed: boolean, hash: string|null, error: string|null }
+ */
+export function commitTask({ projectDir, ctxDir, agentName, taskId, taskTitle, criteriaIds = [] }) {
+  try {
+    // Check for changes
+    const status = execSync('git status --porcelain', {
+      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
+    }).trim();
+
+    if (!status) {
+      return { committed: false, hash: null, error: 'No changes to commit.' };
+    }
+
+    // Stage all changes (excluding .ctx/ state files to avoid noise)
+    execSync('git add -A -- . ":!.ctx/STATE.json" ":!.ctx/STATE.lock" ":!.ctx/HANDOFF.json"', {
+      cwd: projectDir, timeout: 5000,
+    });
+
+    // Build commit message
+    const subject = `ctx(${agentName}): ${taskTitle}`;
+    const body = buildCommitBody(taskId, criteriaIds);
+    const message = `${subject}\n\n${body}`;
+
+    // Commit
+    execSync(`git commit -m ${shellEscape(message)}`, {
+      cwd: projectDir, encoding: 'utf-8', timeout: 10000,
+    });
+
+    // Get commit hash
+    const hash = execSync('git rev-parse --short HEAD', {
+      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
+    }).trim();
+
+    // Record in state
+    recordCompletedTask(ctxDir, taskId, taskTitle, criteriaIds);
+
+    // Log commit in agent history
+    const state = readState(ctxDir);
+    if (state) {
+      state.lastCommit = { hash, taskId, taskTitle, committedAt: new Date().toISOString() };
+      writeState(ctxDir, state);
+    }
+
+    return { committed: true, hash, error: null };
+  } catch (err) {
+    return { committed: false, hash: null, error: err.message };
+  }
+}
+
+/**
+ * Show CTX commit log for the current story.
+ */
+export function getCtxCommitLog(projectDir, limit = 20) {
+  try {
+    const log = execSync(`git log --oneline --grep="^ctx(" -${limit} --no-color`, {
+      cwd: projectDir, encoding: 'utf-8', timeout: 5000,
+    }).trim();
+    return log || 'No CTX commits found.';
+  } catch {
+    return 'No CTX commits found.';
+  }
+}
+
+// --- internal ---
+
+function buildCommitBody(taskId, criteriaIds) {
+  const lines = [];
+  if (taskId) lines.push(`Task: ${taskId}`);
+  if (criteriaIds.length > 0) {
+    lines.push('');
+    lines.push('Acceptance criteria satisfied:');
+    for (const id of criteriaIds) {
+      lines.push(`  - ${id}`);
+    }
+  }
+  lines.push('');
+  lines.push('Co-Authored-By: Claude <noreply@anthropic.com>');
+  return lines.join('\n');
+}
+
+function shellEscape(str) {
+  // Use $'...' syntax for strings with newlines
+  return "$'" + str.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n') + "'";
+}