rafcode 1.2.0 → 2.0.0

package/src/core/worktree.ts

@@ -0,0 +1,357 @@
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { logger } from '../utils/logger.js';
+
+export interface WorktreeCreateResult {
+  success: boolean;
+  worktreePath: string;
+  branch: string;
+  error?: string;
+}
+
+export interface WorktreeMergeResult {
+  success: boolean;
+  merged: boolean;
+  fastForward: boolean;
+  error?: string;
+}
+
+export interface WorktreeValidation {
+  exists: boolean;
+  isValidWorktree: boolean;
+  hasProjectFolder: boolean;
+  hasPlans: boolean;
+  projectPath: string | null;
+}
+
+/**
+ * Get the git toplevel directory (repo root).
+ * Returns null if not in a git repo.
+ */
+export function getRepoRoot(): string | null {
+  try {
+    return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8', stdio: 'pipe' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the basename of the repo root directory.
+ * E.g., "/Users/me/projects/myapp" -> "myapp"
+ * Returns null if not in a git repo.
+ */
+export function getRepoBasename(): string | null {
+  const root = getRepoRoot();
+  if (!root) {
+    return null;
+  }
+  return path.basename(root);
+}
+
+/**
+ * Get the current branch name.
+ * Returns null if not in a git repo or in detached HEAD state.
+ */
+export function getCurrentBranch(): string | null {
+  try {
+    const branch = execSync('git branch --show-current', { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compute the worktree path for a project.
+ * Returns `~/.raf/worktrees/<repo-basename>/<project-id>`.
+ *
+ * @param repoBasename - The basename of the repo root directory
+ * @param projectId - The full project folder name (e.g., "020-worktree-weaver")
+ */
+export function computeWorktreePath(repoBasename: string, projectId: string): string {
+  return path.join(os.homedir(), '.raf', 'worktrees', repoBasename, projectId);
+}
+
+/**
+ * Compute the worktree base directory for a repo.
+ * Returns `~/.raf/worktrees/<repo-basename>/`.
+ *
+ * @param repoBasename - The basename of the repo root directory
+ */
+export function computeWorktreeBaseDir(repoBasename: string): string {
+  return path.join(os.homedir(), '.raf', 'worktrees', repoBasename);
+}
+
+/**
+ * Get the project path inside a worktree.
+ * The project folder is at the same relative path from repo root as in the main repo.
+ *
+ * @param worktreePath - The worktree root directory
+ * @param projectRelativePath - The relative path from repo root to the project folder (e.g., "RAF/020-worktree-weaver")
+ */
+export function getWorktreeProjectPath(worktreePath: string, projectRelativePath: string): string {
+  return path.join(worktreePath, projectRelativePath);
+}
+
+/**
+ * Create a git worktree at the computed path with a new branch.
+ *
+ * @param repoBasename - The basename of the repo root directory
+ * @param projectId - The full project folder name (used as both directory name and branch name)
+ */
+export function createWorktree(repoBasename: string, projectId: string): WorktreeCreateResult {
+  const worktreePath = computeWorktreePath(repoBasename, projectId);
+  const branch = projectId;
+
+  // Ensure parent directory exists
+  const baseDir = computeWorktreeBaseDir(repoBasename);
+  try {
+    fs.mkdirSync(baseDir, { recursive: true });
+  } catch (error) {
+    return {
+      success: false,
+      worktreePath,
+      branch,
+      error: `Failed to create parent directory ${baseDir}: ${error}`,
+    };
+  }
+
+  try {
+    execSync(`git worktree add "${worktreePath}" -b "${branch}"`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    });
+    return { success: true, worktreePath, branch };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      worktreePath,
+      branch,
+      error: `Failed to create worktree: ${msg}`,
+    };
+  }
+}
+
+/**
+ * Validate that a worktree exists, is a valid git worktree, and contains the expected project content.
+ *
+ * @param worktreePath - The worktree root directory
+ * @param projectRelativePath - The relative path from repo root to the project folder
+ */
+export function validateWorktree(worktreePath: string, projectRelativePath: string): WorktreeValidation {
+  const result: WorktreeValidation = {
+    exists: false,
+    isValidWorktree: false,
+    hasProjectFolder: false,
+    hasPlans: false,
+    projectPath: null,
+  };
+
+  // Check directory exists
+  if (!fs.existsSync(worktreePath)) {
+    return result;
+  }
+  result.exists = true;
+
+  // Check it appears in git worktree list
+  try {
+    const listOutput = execSync('git worktree list --porcelain', { encoding: 'utf-8', stdio: 'pipe' });
+    const normalizedWorktreePath = path.resolve(worktreePath);
+    const isListed = listOutput.split('\n').some(line => {
+      if (line.startsWith('worktree ')) {
+        const listedPath = path.resolve(line.slice('worktree '.length).trim());
+        return listedPath === normalizedWorktreePath;
+      }
+      return false;
+    });
+    result.isValidWorktree = isListed;
+  } catch {
+    return result;
+  }
+
+  // Check project folder exists in worktree
+  const projectPath = getWorktreeProjectPath(worktreePath, projectRelativePath);
+  if (fs.existsSync(projectPath)) {
+    result.hasProjectFolder = true;
+    result.projectPath = projectPath;
+
+    // Check for plans directory
+    const plansDir = path.join(projectPath, 'plans');
+    if (fs.existsSync(plansDir)) {
+      result.hasPlans = true;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Merge a worktree branch into the current branch.
+ * Attempts fast-forward first; falls back to merge commit.
+ * On conflicts, aborts merge and returns failure.
+ *
+ * MUST be called from the original repo (not the worktree).
+ *
+ * @param branch - The branch name to merge (typically the project folder name)
+ * @param originalBranch - The branch to merge into (the branch that was active when worktree was created)
+ */
+export function mergeWorktreeBranch(branch: string, originalBranch: string): WorktreeMergeResult {
+  // Switch to the original branch
+  try {
+    execSync(`git checkout "${originalBranch}"`, { encoding: 'utf-8', stdio: 'pipe' });
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      merged: false,
+      fastForward: false,
+      error: `Failed to checkout ${originalBranch}: ${msg}`,
+    };
+  }
+
+  // Try fast-forward merge first
+  try {
+    execSync(`git merge --ff-only "${branch}"`, { encoding: 'utf-8', stdio: 'pipe' });
+    return { success: true, merged: true, fastForward: true };
+  } catch {
+    // Fast-forward not possible, try regular merge
+  }
+
+  // Try regular merge
+  try {
+    execSync(`git merge "${branch}"`, { encoding: 'utf-8', stdio: 'pipe' });
+    return { success: true, merged: true, fastForward: false };
+  } catch {
+    // Merge conflicts - abort
+    try {
+      execSync('git merge --abort', { encoding: 'utf-8', stdio: 'pipe' });
+    } catch {
+      logger.warn('Failed to abort merge - repo may be in an inconsistent state');
+    }
+
+    return {
+      success: false,
+      merged: false,
+      fastForward: false,
+      error: `Merge conflicts detected. Please merge branch "${branch}" into "${originalBranch}" manually.`,
+    };
+  }
+}
+
+/**
+ * Remove a single worktree.
+ * Used for failed-plan cleanup and post-completion cleanup.
+ * The git branch is preserved — only the worktree directory is removed.
+ *
+ * @param worktreePath - The worktree directory to remove
+ * @returns true if removal succeeded, false otherwise
+ */
+export function removeWorktree(worktreePath: string): { success: boolean; error?: string } {
+  try {
+    execSync(`git worktree remove "${worktreePath}"`, { encoding: 'utf-8', stdio: 'pipe' });
+    return { success: true };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      error: `Failed to remove worktree at ${worktreePath}: ${msg}`,
+    };
+  }
+}
+
+/**
+ * Check if a local branch exists.
+ *
+ * @param branchName - The branch name to check
+ * @returns true if the branch exists locally
+ */
+export function branchExists(branchName: string): boolean {
+  try {
+    const output = execSync(`git branch --list "${branchName}"`, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+    return output.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create a git worktree at the computed path from an existing branch.
+ * Unlike `createWorktree()`, this does NOT create a new branch — it attaches
+ * to a branch that already exists locally.
+ *
+ * @param repoBasename - The basename of the repo root directory
+ * @param projectId - The full project folder name (used as both directory name and branch name)
+ */
+export function createWorktreeFromBranch(repoBasename: string, projectId: string): WorktreeCreateResult {
+  const worktreePath = computeWorktreePath(repoBasename, projectId);
+  const branch = projectId;
+
+  // Check branch exists
+  if (!branchExists(branch)) {
+    return {
+      success: false,
+      worktreePath,
+      branch,
+      error: `Branch "${branch}" does not exist locally`,
+    };
+  }
+
+  // Ensure parent directory exists
+  const baseDir = computeWorktreeBaseDir(repoBasename);
+  try {
+    fs.mkdirSync(baseDir, { recursive: true });
+  } catch (error) {
+    return {
+      success: false,
+      worktreePath,
+      branch,
+      error: `Failed to create parent directory ${baseDir}: ${error}`,
+    };
+  }
+
+  try {
+    execSync(`git worktree add "${worktreePath}" "${branch}"`, {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    });
+    return { success: true, worktreePath, branch };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      worktreePath,
+      branch,
+      error: `Failed to create worktree: ${msg}`,
+    };
+  }
+}
+
+/**
+ * List all worktree project directories for the current repo.
+ * Scans `~/.raf/worktrees/<repo-basename>/` and returns the list of project folder names.
+ *
+ * @param repoBasename - The basename of the repo root directory
+ * @returns Sorted array of project folder names (e.g., ['020-worktree-weaver', '021-another-feature'])
+ */
+export function listWorktreeProjects(repoBasename: string): string[] {
+  const baseDir = computeWorktreeBaseDir(repoBasename);
+
+  if (!fs.existsSync(baseDir)) {
+    return [];
+  }
+
+  try {
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    const projects = entries
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name)
+      .sort();
+    return projects;
+  } catch {
+    return [];
+  }
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { createPlanCommand } from './commands/plan.js';
 import { createDoCommand } from './commands/do.js';
 import { createStatusCommand } from './commands/status.js';
+import { createMigrateCommand } from './commands/migrate.js';
 import { getVersion } from './utils/version.js';
 
 const program = new Command();
@@ -16,5 +17,6 @@ program
 program.addCommand(createPlanCommand());
 program.addCommand(createDoCommand());
 program.addCommand(createStatusCommand());
+program.addCommand(createMigrateCommand());
 
 program.parse();

package/src/parsers/stream-renderer.ts

@@ -0,0 +1,139 @@
+/**
+ * Renders stream-json events from Claude CLI into human-readable verbose output.
+ *
+ * Event types from `claude -p --output-format stream-json --verbose`:
+ * - system (init): Session initialization info
+ * - assistant: Claude's response with text or tool_use content blocks
+ * - user: Tool results (tool_result content blocks)
+ * - result: Final result with success/failure status
+ */
+
+export interface StreamEvent {
+  type: string;
+  subtype?: string;
+  message?: {
+    content?: ContentBlock[];
+  };
+  result?: string;
+  tool_use_result?: {
+    type?: string;
+    file?: {
+      filePath?: string;
+    };
+  };
+}
+
+interface ContentBlock {
+  type: string;
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+/**
+ * Describes what a tool is doing in human-readable form.
+ */
+function describeToolUse(name: string, input: Record<string, unknown>): string {
+  switch (name) {
+    case 'Read':
+      return `Reading ${input.file_path ?? 'file'}`;
+    case 'Write':
+      return `Writing ${input.file_path ?? 'file'}`;
+    case 'Edit':
+      return `Editing ${input.file_path ?? 'file'}`;
+    case 'Bash':
+      return `Running: ${truncate(String(input.command ?? ''), 120)}`;
+    case 'Glob':
+      return `Searching files: ${input.pattern ?? ''}`;
+    case 'Grep':
+      return `Searching for: ${truncate(String(input.pattern ?? ''), 80)}`;
+    case 'WebFetch':
+      return `Fetching: ${input.url ?? ''}`;
+    case 'WebSearch':
+      return `Searching web: ${input.query ?? ''}`;
+    case 'TodoWrite':
+      return 'Updating task list';
+    case 'Task':
+      return `Launching agent: ${truncate(String(input.description ?? input.prompt ?? ''), 80)}`;
+    case 'NotebookEdit':
+      return `Editing notebook: ${input.notebook_path ?? ''}`;
+    default:
+      return `Using tool: ${name}`;
+  }
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.substring(0, maxLen - 3) + '...';
+}
+
+export interface RenderResult {
+  /** Text to display to stdout (may be empty if no display needed) */
+  display: string;
+  /** Text content to accumulate for output parsing (completion markers, etc.) */
+  textContent: string;
+}
+
+/**
+ * Parse and render a single NDJSON line from stream-json output.
+ * Returns display text for stdout and text content for output accumulation.
+ */
+export function renderStreamEvent(line: string): RenderResult {
+  if (!line.trim()) {
+    return { display: '', textContent: '' };
+  }
+
+  let event: StreamEvent;
+  try {
+    event = JSON.parse(line) as StreamEvent;
+  } catch {
+    // Not valid JSON - pass through raw
+    return { display: line + '\n', textContent: line };
+  }
+
+  switch (event.type) {
+    case 'system':
+      return { display: '', textContent: '' };
+
+    case 'assistant':
+      return renderAssistant(event);
+
+    case 'user':
+      // Tool results — skip verbose display (the tool_use already described what's happening)
+      return { display: '', textContent: '' };
+
+    case 'result':
+      return renderResult(event);
+
+    default:
+      return { display: '', textContent: '' };
+  }
+}
+
+function renderAssistant(event: StreamEvent): RenderResult {
+  const content = event.message?.content;
+  if (!content || !Array.isArray(content)) {
+    return { display: '', textContent: '' };
+  }
+
+  let display = '';
+  let textContent = '';
+
+  for (const block of content) {
+    if (block.type === 'text' && block.text) {
+      textContent += block.text;
+      display += block.text + '\n';
+    } else if (block.type === 'tool_use' && block.name) {
+      const description = describeToolUse(block.name, block.input ?? {});
+      display += `  → ${description}\n`;
+    }
+  }
+
+  return { display, textContent };
+}
+
+function renderResult(_event: StreamEvent): RenderResult {
+  // The result event's text duplicates the last assistant message,
+  // which is already captured. Skip to avoid double-counting.
+  return { display: '', textContent: '' };
+}

package/src/prompts/amend.ts

@@ -1,10 +1,12 @@
 import { DerivedTask } from '../core/state-derivation.js';
+import { encodeTaskId } from '../utils/paths.js';
 
 export interface AmendPromptParams {
   projectPath: string;
   existingTasks: Array<DerivedTask & { taskName: string }>;
   nextTaskNumber: number;
   newTaskDescription: string;
+  worktreeMode?: boolean;
 }
 
 export interface AmendPromptResult {
@@ -23,7 +25,9 @@ export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
     existingTasks,
     nextTaskNumber,
     newTaskDescription,
+    worktreeMode,
   } = params;
+  const worktreeFlag = worktreeMode ? ' --worktree' : '';
 
   const existingTasksSummary = existingTasks
     .map((task) => {
@@ -35,7 +39,11 @@ export function getAmendPrompt(params: AmendPromptParams): AmendPromptResult {
             : '[PENDING]';
       const modifiability =
         task.status === 'completed' ? '[PROTECTED]' : '[MODIFIABLE]';
-      return `- Task ${task.id}: ${task.taskName} ${status} ${modifiability}`;
+      const outcomeRef =
+        task.status === 'completed'
+          ? `\n  Outcome: ${projectPath}/outcomes/${task.planFile.replace('plans/', '').replace(/\.md$/, '')}.md`
+          : '';
+      return `- Task ${task.id}: ${task.taskName} ${status} ${modifiability}${outcomeRef}`;
     })
     .join('\n');
 
@@ -59,7 +67,7 @@ You are in AMENDMENT MODE. This means:
 - You MAY modify [MODIFIABLE] tasks (pending/failed) if the user requests changes
 - NEVER modify [PROTECTED] tasks (completed) - their outcomes depend on the original plan
 - DO NOT renumber existing tasks
-- You can create NEW tasks starting from number ${nextTaskNumber.toString().padStart(3, '0')}
+- You can create NEW tasks starting from number ${encodeTaskId(nextTaskNumber)}
 
 ## Project Location
 
@@ -94,6 +102,13 @@ Read the user's description of new tasks and identify what needs to be added. Co
 - Dependencies on completed tasks (check the ## Dependencies section in existing plan files)
 - Whether new tasks should reference existing task outcomes
 
+**Identifying Follow-up Tasks**: When a new task is a follow-up, fix, or iteration of a previously completed task, you MUST reference the previous task's outcome in the new plan's Context section. This gives the executing agent full context about what was done before.
+
+Use this format in the Context section:
+\`This is a follow-up to task NN. See outcome: {projectPath}/outcomes/NN-task-name.md\`
+
+The outcome file paths for completed tasks are listed above in the Existing Tasks section.
+
 ### Step 3: Interview the User
 
 For EACH new task you identify, use the AskUserQuestion tool to gather:
@@ -109,15 +124,15 @@ After EACH interview question is answered, append the Q&A pair to the existing d
 
 Use this format:
 \`\`\`markdown
-## [Amendment] [Question asked]
+## [Question asked]
 [User's answer]
 \`\`\`
 
 ### Step 4: Create New Plan Files
 
 After interviewing the user about all NEW tasks, create plan files starting from the next available number:
-- ${projectPath}/plans/${nextTaskNumber.toString().padStart(3, '0')}-task-name.md
-- ${projectPath}/plans/${(nextTaskNumber + 1).toString().padStart(3, '0')}-task-name.md
+- ${projectPath}/plans/${encodeTaskId(nextTaskNumber)}-task-name.md
+- ${projectPath}/plans/${encodeTaskId(nextTaskNumber + 1)}-task-name.md
 - etc.
 
 Each plan file should follow this structure:
@@ -131,10 +146,11 @@ Each plan file should follow this structure:
 ## Context
 [Why this task is needed, how it fits into the larger project]
 [Reference relevant existing tasks if applicable]
+[For follow-up/fix tasks: "This is a follow-up to task NN. See outcome: {projectPath}/outcomes/NN-task-name.md"]
 
 ## Dependencies
 [Optional section - omit if task has no dependencies]
-[Comma-separated list of task IDs this task depends on, e.g., "001, 002"]
+[Comma-separated list of task IDs this task depends on, e.g., "01, 02"]
 [If a dependency fails, this task will be automatically blocked]
 
 ## Requirements
@@ -169,7 +185,9 @@ After creating all new plan files:
 2. Display this exit message to the user:
 
 \`\`\`
-Planning complete! Press Ctrl-C twice to exit to exit this session 
+Planning complete! To exit this session and run your tasks:
+  1. Press Ctrl-C twice to exit
+  2. Then run: raf do <project>${worktreeFlag}
 \`\`\`
 
 ## Important Rules
@@ -177,10 +195,10 @@ Planning complete! Press Ctrl-C twice to exit to exit this session
 1. NEVER modify COMPLETED task plans - they are [PROTECTED] because their outcomes depend on the original plan
 2. You MAY modify non-completed task plans (pending/failed) if the user requests changes - they are [MODIFIABLE]
 3. ALWAYS interview the user before creating or modifying plans
-4. New tasks start from number ${nextTaskNumber.toString().padStart(3, '0')}
+4. New tasks start from number ${encodeTaskId(nextTaskNumber)}
 5. Use descriptive, kebab-case names for plan files
 6. Each plan should be self-contained with all context needed
-7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "001, 002")
+7. Specify task dependencies using the ## Dependencies section with task IDs only (e.g., "01, 02")
 8. Tasks without dependencies should omit the Dependencies section entirely
 9. Be specific - vague plans lead to poor execution
 

package/src/prompts/execution.ts

@@ -83,8 +83,8 @@ ${previousOutcomes.map((o) => `### Task ${o.taskId}\n${o.content}`).join('\n\n')
 `;
   }
 
-  // Zero-pad task number to 3 digits
-  const paddedTaskNumber = taskNumber.toString().padStart(3, '0');
+  // Encode task number to 2-char base36
+  const paddedTaskNumber = taskNumber.toString(36).padStart(2, '0');
 
   const commitInstructions = autoCommit
     ? `
@@ -98,6 +98,8 @@ After successfully completing the task:
 2. Commit with message: "RAF[${projectNumber}:${paddedTaskNumber}] <description>"
    - Write a concise description of what was accomplished
    - Focus on the actual change, not the task name
+   - The commit message must be a SINGLE LINE — no body, no trailers
+   - Do NOT add Co-Authored-By or any other trailers to the commit message
 
 **IMPORTANT - On Failure**: If the task fails, do NOT commit. Just write the outcome file with the \`<promise>FAILED</promise>\` marker and stop. Uncommitted changes will be preserved for debugging.
 `
@@ -164,12 +166,10 @@ First, read the plan file to understand exactly what needs to be done.
 ### Step 2: Execute the Task
 
 Follow the implementation steps in the plan. Key guidelines:
-- **Use the Task tool to delegate work to subagents** - Split complex work into subtasks and use specialized agents (Explore for codebase investigation, Plan for design decisions, general-purpose for implementation)
 - Write clean, maintainable code
 - Follow existing code patterns in the project
 - Add appropriate error handling
-- Write tests if specified in the plan
-- Follow any CLAUDE.md instructions if present
+- Follow any CLAUDE.md instructions
 ${dependencyContextSection}${outcomesSection}
 ### Step 3: Verify Completion