cralph 1.0.0-alpha.0 → 1.0.0-alpha.1

package/README.md

@@ -1,12 +1,16 @@
 # cralph
 
-Claude in a loop. Point at refs, give it rules, let it cook.
+<p align="center">
+  <img src="assets/ralph.png" alt="Ralph cooking" width="500">
+</p>
+
+Claude in a loop. Point at refs, give it a rule, let it cook.
 
 ```
-refs/  ──loop──>  output/
-(source)   │      (result)
+refs/  ──loop──>  ./
+(source)   │      (output in cwd)
            │
-        rules.md
+        rule.md
 ```
 
 ## What is Ralph?
@@ -34,37 +38,37 @@ npm install -g cralph
 ## Usage
 
 ```bash
-# Interactive - prompts for everything
+# Run - auto-detects ralph.paths.json in cwd
 cralph
 
-# With flags
-cralph --refs ./source --rules ./rules.md --output ./out
+# First run (no config) - interactive mode generates ralph.paths.json
+cralph
 
-# With config file
-cralph --paths-file ralph.paths.json
+# Override with flags
+cralph --refs ./source --rule ./rule.md --output .
 ```
 
 ## Path Selection
 
-When prompted, choose how to specify each path:
+Simple multiselect for all paths:
 
-| Mode | What it does |
-|------|--------------|
-| Select from cwd | Pick directories/files interactively |
-| Manual | Type the path |
-| Paths file | Load from JSON config |
+- **Space** to toggle selection
+- **Enter** to confirm
+- **Ctrl+C** to exit
+- Shows all directories up to 3 levels deep
+- Pre-selects current values in edit mode
 
 ## Config File
 
 ```json
 {
   "refs": ["./refs", "./more-refs"],
-  "rules": "./.cursor/rules/my-rules.mdc",
-  "output": "./output"
+  "rule": "./.cursor/rules/my-rules.mdc",
+  "output": "."
 }
 ```
 
-Name it `ralph.paths.json` and cralph auto-detects it.
+Name it `ralph.paths.json` and cralph auto-detects it. Output is typically `.` (current directory) since you'll run cralph in your repo.
 
 ## How It Works
 
@@ -73,6 +77,58 @@ Name it `ralph.paths.json` and cralph auto-detects it.
 3. Runs `claude -p --dangerously-skip-permissions` in a loop
 4. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
+## Expected Behavior
+
+**Auto-detect existing config:**
+```
+❯ Found ralph.paths.json. What would you like to do?
+● 🚀 Run with this config
+○ ✏️  Edit configuration
+```
+
+**Interactive Mode (no config file):**
+```
+ℹ Interactive configuration mode
+
+↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
+❯ Select refs directories:
+◻ 📁 src
+◻ 📁 src/components
+◼ 📁 docs
+
+↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
+❯ Select rule file:
+● 📄 .cursor/rules/my-rules.mdc (cursor rule)
+○ 📄 README.md
+
+↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
+❯ Select output directory:
+● 📍 Current directory (.)
+○ 📁 docs
+```
+
+**Save config after selection:**
+```
+? Save configuration to ralph.paths.json? (Y/n)
+✔ Saved ralph.paths.json
+```
+
+**Cancellation:**
+- Press `Ctrl+C` at any time to exit
+- Running Claude processes are terminated cleanly
+
+**Output Files:**
+- `.ralph/ralph.log` - Session log with timestamps
+- `.ralph/TODO.md` - Agent status tracker
+
+## Testing
+
+```bash
+bun test
+```
+
+Tests validate config loading, prompt building, and CLI behavior without calling Claude.
+
 ## Requirements
 
 - [Bun](https://bun.sh)

package/index.ts

@@ -2,4 +2,4 @@
 export * from "./src/types";
 export { buildConfig, loadPathsFile, validateConfig } from "./src/paths";
 export { createPrompt, buildPrompt } from "./src/prompt";
-export { run } from "./src/runner";
+export { run, cleanupSubprocess } from "./src/runner";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cralph",
-  "version": "1.0.0-alpha.0",
-  "description": "Claude in a loop. Point at refs, give it rules, let it cook.",
+  "version": "1.0.0-alpha.1",
+  "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",
   "repository": {
@@ -26,7 +26,8 @@
     "src",
     "index.ts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "assets"
   ],
   "scripts": {
     "start": "bun run src/cli.ts"

package/src/cli.ts

@@ -8,91 +8,146 @@ import {
   loadPathsFile,
   validateConfig,
   selectRefs,
-  selectRules,
+  selectRule,
   selectOutput,
+  checkForPathsFile,
 } from "./paths";
-import { run } from "./runner";
+import { run, cleanupSubprocess } from "./runner";
 import type { RalphConfig } from "./types";
 
+// Graceful shutdown on Ctrl+C
+function setupGracefulExit() {
+  let shuttingDown = false;
+  
+  process.on("SIGINT", () => {
+    if (shuttingDown) {
+      // Force exit on second Ctrl+C
+      process.exit(1);
+    }
+    shuttingDown = true;
+    cleanupSubprocess();
+    console.log("\n");
+    consola.info("Cancelled.");
+    // Use setImmediate to ensure output is flushed
+    setImmediate(() => process.exit(0));
+  });
+  
+  // Also handle SIGTERM
+  process.on("SIGTERM", () => {
+    cleanupSubprocess();
+    process.exit(0);
+  });
+}
+
 const main = defineCommand({
   meta: {
     name: "cralph",
     version: "1.0.0",
-    description: "Claude in a loop. Point at refs, give it rules, let it cook.",
+    description: "Claude in a loop. Point at refs, give it a rule, let it cook.",
   },
   args: {
     refs: {
       type: "string",
       description: "Comma-separated refs paths (source material)",
+      valueHint: "path1,path2",
+      alias: "r",
       required: false,
     },
-    rules: {
+    rule: {
       type: "string",
-      description: "Path to rules file (.mdc or .md)",
+      description: "Path to rule file (.mdc or .md)",
+      valueHint: "rule.md",
+      alias: "u",
       required: false,
     },
     output: {
       type: "string",
-      description: "Output directory",
+      description: "Output directory where results will be written",
+      valueHint: ".",
+      alias: "o",
       required: false,
     },
-    "paths-file": {
-      type: "string",
-      description: "Path to configuration file (JSON)",
+    help: {
+      type: "boolean",
+      description: "Show this help message",
+      alias: "h",
       required: false,
     },
   },
   async run({ args }) {
+    setupGracefulExit();
     const cwd = process.cwd();
     let config: RalphConfig;
 
     try {
-      // If paths-file is provided, use it
-      if (args["paths-file"]) {
-        const pathsFilePath = resolve(cwd, args["paths-file"]);
-        consola.info(`Loading config from ${pathsFilePath}`);
-        const loaded = await loadPathsFile(pathsFilePath);
+      // Check for existing paths file in cwd
+      const pathsFileResult = await checkForPathsFile(cwd);
+      
+      if (pathsFileResult?.action === "run") {
+        // Use existing config file
+        consola.info(`Loading config from ${pathsFileResult.path}`);
+        const loaded = await loadPathsFile(pathsFileResult.path);
         config = {
           refs: loaded.refs.map((r) => resolve(cwd, r)),
-          rules: resolve(cwd, loaded.rules),
+          rule: resolve(cwd, loaded.rule),
           output: resolve(cwd, loaded.output),
         };
-      }
-      // If all args are provided via CLI flags
-      else if (args.refs && args.rules && args.output) {
-        config = {
-          refs: args.refs.split(",").map((r) => resolve(cwd, r.trim())),
-          rules: resolve(cwd, args.rules),
-          output: resolve(cwd, args.output),
-        };
-      }
-      // Interactive mode - some or no args provided
-      else {
-        consola.info("Interactive configuration mode\n");
-
-        // Use provided args or prompt for missing ones
-        let refs: string[];
-        if (args.refs) {
-          refs = args.refs.split(",").map((r) => resolve(cwd, r.trim()));
+      } else {
+        // Load existing config for edit mode defaults
+        let existingConfig: RalphConfig | null = null;
+        if (pathsFileResult?.action === "edit") {
+          consola.info("Edit configuration");
+          const candidates = ["ralph.paths.json", ".ralph.paths.json", "paths.json"];
+          for (const candidate of candidates) {
+            const filePath = resolve(cwd, candidate);
+            const file = Bun.file(filePath);
+            if (await file.exists()) {
+              const loaded = await loadPathsFile(filePath);
+              existingConfig = {
+                refs: loaded.refs.map((r) => resolve(cwd, r)),
+                rule: resolve(cwd, loaded.rule),
+                output: resolve(cwd, loaded.output),
+              };
+              break;
+            }
+          }
         } else {
-          refs = await selectRefs(cwd);
+          consola.info("Interactive configuration mode");
         }
 
-        let rules: string;
-        if (args.rules) {
-          rules = resolve(cwd, args.rules);
-        } else {
-          rules = await selectRules(cwd);
-        }
+        // Interactive selection
+        const refs = args.refs 
+          ? args.refs.split(",").map((r) => resolve(cwd, r.trim()))
+          : await selectRefs(cwd, existingConfig?.refs);
+        
+        const rule = args.rule 
+          ? resolve(cwd, args.rule)
+          : await selectRule(cwd, existingConfig?.rule);
+        
+        const output = args.output 
+          ? resolve(cwd, args.output)
+          : await selectOutput(cwd, existingConfig?.output);
 
-        let output: string;
-        if (args.output) {
-          output = resolve(cwd, args.output);
-        } else {
-          output = await selectOutput(cwd);
-        }
+        config = { refs, rule, output };
+
+        // Offer to save config
+        const saveConfig = await consola.prompt("Save configuration to ralph.paths.json?", {
+          type: "confirm",
+          initial: true,
+        });
 
-        config = { refs, rules, output };
+        if (saveConfig === true) {
+          const pathsConfig = {
+            refs: config.refs.map((r) => "./" + r.replace(cwd + "/", "")),
+            rule: "./" + config.rule.replace(cwd + "/", ""),
+            output: config.output === cwd ? "." : "./" + config.output.replace(cwd + "/", ""),
+          };
+          await Bun.write(
+            resolve(cwd, "ralph.paths.json"),
+            JSON.stringify(pathsConfig, null, 2)
+          );
+          consola.success("Saved ralph.paths.json");
+        }
       }
 
       // Validate configuration
@@ -102,7 +157,7 @@ const main = defineCommand({
       // Show config summary
       consola.info("Configuration:");
       consola.info(`  Refs: ${config.refs.join(", ")}`);
-      consola.info(`  Rules: ${config.rules}`);
+      consola.info(`  Rule: ${config.rule}`);
       consola.info(`  Output: ${config.output}`);
       console.log();
 
@@ -120,6 +175,13 @@ const main = defineCommand({
       // Run the main loop
       await run(config);
     } catch (error) {
+      // Handle graceful cancellation
+      if (error instanceof Error && error.message.includes("cancelled")) {
+        console.log();
+        consola.info("Cancelled.");
+        process.exit(0);
+      }
+      
       if (error instanceof Error) {
         consola.error(error.message);
       } else {

package/src/paths.ts

@@ -1,7 +1,11 @@
 import { consola } from "consola";
-import { resolve, join, basename } from "path";
+import { resolve, join } from "path";
 import { readdir, stat } from "fs/promises";
-import type { PathSelectionMode, PathsFileConfig, RalphConfig } from "./types";
+import type { PathsFileConfig, RalphConfig } from "./types";
+
+// Dim text helper
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+const CONTROLS = dim("↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit");
 
 /**
  * List directories in a given path
@@ -13,6 +17,52 @@ async function listDirectories(basePath: string): Promise<string[]> {
     .map((e) => e.name);
 }
 
+/**
+ * Directories to exclude from listing
+ */
+const EXCLUDED_DIRS = [
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".output",
+  "coverage",
+  "__pycache__",
+  "vendor",
+  ".cache",
+];
+
+/**
+ * List directories recursively up to a certain depth
+ */
+async function listDirectoriesRecursive(
+  basePath: string,
+  maxDepth: number = 3
+): Promise<string[]> {
+  const results: string[] = [];
+
+  async function walk(dir: string, depth: number) {
+    if (depth > maxDepth) return;
+    
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip hidden and excluded directories
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith(".")) continue;
+      if (EXCLUDED_DIRS.includes(entry.name)) continue;
+      
+      const fullPath = join(dir, entry.name);
+      results.push(fullPath);
+      await walk(fullPath, depth + 1);
+    }
+  }
+
+  await walk(basePath, 1);
+  return results;
+}
+
 /**
  * List files matching patterns in a directory (recursive)
  */
@@ -26,7 +76,10 @@ async function listFilesRecursive(
     const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
-      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      if (entry.isDirectory()) {
+        // Skip hidden and excluded directories
+        if (entry.name.startsWith(".")) continue;
+        if (EXCLUDED_DIRS.includes(entry.name)) continue;
         await walk(fullPath);
       } else if (entry.isFile()) {
         if (extensions.some((ext) => entry.name.endsWith(ext))) {
@@ -40,26 +93,6 @@ async function listFilesRecursive(
   return results;
 }
 
-/**
- * Prompt user for path selection mode
- */
-async function askSelectionMode(label: string): Promise<PathSelectionMode> {
-  const mode = await consola.prompt(`How would you like to specify ${label}?`, {
-    type: "select",
-    options: [
-      { label: "Select from current directory", value: "select" },
-      { label: "Enter path manually", value: "manual" },
-      { label: "Use paths file", value: "file" },
-    ],
-  });
-
-  if (typeof mode === "symbol") {
-    throw new Error("Selection cancelled");
-  }
-
-  return mode as PathSelectionMode;
-}
-
 /**
  * Load configuration from a paths file
  */
@@ -73,143 +106,149 @@ export async function loadPathsFile(filePath: string): Promise<PathsFileConfig>
 }
 
 /**
- * Prompt user to select refs directories
+ * Prompt user to select refs directories (simple multiselect)
  */
-export async function selectRefs(cwd: string): Promise<string[]> {
-  const mode = await askSelectionMode("refs (reference material)");
-
-  if (mode === "manual") {
-    const input = await consola.prompt(
-      "Enter refs paths (comma-separated):",
-      { type: "text" }
-    );
-    if (typeof input === "symbol") throw new Error("Selection cancelled");
-    return input
-      .split(",")
-      .map((p) => resolve(cwd, p.trim()))
-      .filter(Boolean);
+export async function selectRefs(cwd: string, defaults?: string[]): Promise<string[]> {
+  // Get all directories up to 3 levels deep
+  const allDirs = await listDirectoriesRecursive(cwd, 3);
+  
+  if (allDirs.length === 0) {
+    consola.warn("No directories found");
+    throw new Error("No directories available to select");
   }
 
-  if (mode === "select") {
-    const dirs = await listDirectories(cwd);
-    if (dirs.length === 0) {
-      consola.warn("No directories found in current directory");
-      return selectRefs(cwd); // retry
-    }
+  // Convert to relative paths for display
+  const options = allDirs.map((d) => {
+    const relative = d.replace(cwd + "/", "");
+    const isDefault = defaults?.includes(d);
+    return {
+      label: `📁 ${relative}`,
+      value: d,
+      hint: isDefault ? "current" : undefined,
+    };
+  });
 
-    const selected = await consola.prompt("Select refs directories:", {
-      type: "multiselect",
-      options: dirs.map((d) => ({ label: d, value: d })),
-    });
+  // Get initial selections (indices of defaults)
+  const initialValues = defaults?.filter((d) => allDirs.includes(d)) || [];
 
-    if (typeof selected === "symbol") throw new Error("Selection cancelled");
-    return (selected as string[]).map((d) => resolve(cwd, d));
-  }
+  console.log(CONTROLS);
+  const selected = await consola.prompt("Select refs directories:", {
+    type: "multiselect",
+    options,
+    initial: initialValues,
+  });
 
-  // file mode - will be handled at config level
-  throw new Error("Use loadPathsFile for file-based configuration");
+  // Handle cancel (symbol) or empty result
+  if (typeof selected === "symbol" || !selected || (Array.isArray(selected) && selected.length === 0)) {
+    throw new Error("Selection cancelled");
+  }
+  
+  return selected as string[];
 }
 
 /**
- * Prompt user to select a rules file
+ * Prompt user to select a rule file
  */
-export async function selectRules(cwd: string): Promise<string> {
-  const mode = await askSelectionMode("rules file");
-
-  if (mode === "manual") {
-    const input = await consola.prompt("Enter rules file path:", {
-      type: "text",
-    });
-    if (typeof input === "symbol") throw new Error("Selection cancelled");
-    return resolve(cwd, input.trim());
+export async function selectRule(cwd: string, defaultRule?: string): Promise<string> {
+  const files = await listFilesRecursive(cwd, [".mdc", ".md"]);
+  if (files.length === 0) {
+    consola.warn("No .mdc or .md files found");
+    throw new Error("No rule files available to select");
   }
 
-  if (mode === "select") {
-    const files = await listFilesRecursive(cwd, [".mdc", ".md"]);
-    if (files.length === 0) {
-      consola.warn("No .mdc or .md files found");
-      return selectRules(cwd); // retry
-    }
-
-    // Show relative paths for readability
-    const options = files.map((f) => ({
-      label: f.replace(cwd + "/", ""),
-      value: f,
-    }));
+  // Show relative paths for readability
+  const options = files.map((f) => ({
+    label: `📄 ${f.replace(cwd + "/", "")}`,
+    value: f,
+    hint: f === defaultRule ? "current" : (f.endsWith(".mdc") ? "cursor rule" : "markdown"),
+  }));
 
-    const selected = await consola.prompt("Select rules file:", {
-      type: "select",
-      options,
-    });
+  // Find index of default for initial selection
+  const initialIndex = defaultRule ? files.findIndex((f) => f === defaultRule) : 0;
 
-    if (typeof selected === "symbol") throw new Error("Selection cancelled");
-    return selected as string;
-  }
+  console.log(CONTROLS);
+  const selected = await consola.prompt("Select rule file:", {
+    type: "select",
+    options,
+    initial: initialIndex >= 0 ? initialIndex : 0,
+  });
 
-  throw new Error("Use loadPathsFile for file-based configuration");
+  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+  return selected as string;
 }
 
 /**
  * Prompt user to select output directory
  */
-export async function selectOutput(cwd: string): Promise<string> {
-  const mode = await askSelectionMode("output directory");
-
-  if (mode === "manual") {
-    const input = await consola.prompt("Enter output directory path:", {
-      type: "text",
-      default: "./docs",
-    });
-    if (typeof input === "symbol") throw new Error("Selection cancelled");
-    return resolve(cwd, input.trim());
+export async function selectOutput(cwd: string, defaultOutput?: string): Promise<string> {
+  const dirs = await listDirectories(cwd);
+  
+  // Determine default value for matching
+  const defaultDir = defaultOutput === cwd ? "." : defaultOutput?.replace(cwd + "/", "");
+  
+  const options = [
+    { label: "📍 Current directory (.)", value: ".", hint: defaultDir === "." ? "current" : "Output here" },
+    ...dirs.map((d) => ({ 
+      label: `📁 ${d}`, 
+      value: d,
+      hint: d === defaultDir ? "current" : undefined,
+    })),
+  ];
+
+  // Find initial index
+  let initialIndex = 0;
+  if (defaultDir) {
+    const idx = defaultDir === "." ? 0 : dirs.findIndex((d) => d === defaultDir) + 1;
+    if (idx >= 0) initialIndex = idx;
   }
 
-  if (mode === "select") {
-    const dirs = await listDirectories(cwd);
-    const options = [
-      { label: "(create new)", value: "__new__" },
-      ...dirs.map((d) => ({ label: d, value: d })),
-    ];
-
-    const selected = await consola.prompt("Select output directory:", {
-      type: "select",
-      options,
-    });
-
-    if (typeof selected === "symbol") throw new Error("Selection cancelled");
-
-    if (selected === "__new__") {
-      const newDir = await consola.prompt("Enter new directory name:", {
-        type: "text",
-        default: "docs",
-      });
-      if (typeof newDir === "symbol") throw new Error("Selection cancelled");
-      return resolve(cwd, newDir.trim());
-    }
+  console.log(CONTROLS);
+  const selected = await consola.prompt("Select output directory:", {
+    type: "select",
+    options,
+    initial: initialIndex,
+  });
 
-    return resolve(cwd, selected as string);
+  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+
+  if (selected === ".") {
+    return cwd;
   }
 
-  throw new Error("Use loadPathsFile for file-based configuration");
+  return resolve(cwd, selected as string);
 }
 
 /**
  * Check if a paths file exists and offer to use it
+ * Returns: { action: "run", path: string } | { action: "edit" } | null
  */
-export async function checkForPathsFile(cwd: string): Promise<string | null> {
+export async function checkForPathsFile(cwd: string): Promise<{ action: "run"; path: string } | { action: "edit" } | null> {
   const candidates = ["ralph.paths.json", ".ralph.paths.json", "paths.json"];
 
   for (const candidate of candidates) {
     const filePath = join(cwd, candidate);
     const file = Bun.file(filePath);
     if (await file.exists()) {
-      const useIt = await consola.prompt(
-        `Found ${candidate}. Use it for configuration?`,
-        { type: "confirm", initial: true }
+      console.log(CONTROLS);
+      const action = await consola.prompt(
+        `Found ${candidate}. What would you like to do?`,
+        {
+          type: "select",
+          options: [
+            { label: "🚀 Run with this config", value: "run" },
+            { label: "✏️  Edit configuration", value: "edit" },
+          ],
+        }
       );
-      if (useIt === true) {
-        return filePath;
+      
+      if (typeof action === "symbol") {
+        throw new Error("Selection cancelled");
+      }
+      
+      if (action === "run") {
+        return { action: "run", path: filePath };
       }
+      return { action: "edit" };
     }
   }
 
@@ -229,10 +268,10 @@ export async function validateConfig(config: RalphConfig): Promise<void> {
     }
   }
 
-  // Check rules file
-  const rulesFile = Bun.file(config.rules);
-  if (!(await rulesFile.exists())) {
-    throw new Error(`Rules file does not exist: ${config.rules}`);
+  // Check rule file
+  const ruleFile = Bun.file(config.rule);
+  if (!(await ruleFile.exists())) {
+    throw new Error(`Rule file does not exist: ${config.rule}`);
   }
 
   // Output directory will be created if needed
@@ -249,15 +288,15 @@ export async function buildConfig(cwd: string): Promise<RalphConfig> {
     const loaded = await loadPathsFile(pathsFile);
     return {
       refs: loaded.refs.map((r) => resolve(cwd, r)),
-      rules: resolve(cwd, loaded.rules),
+      rule: resolve(cwd, loaded.rule),
       output: resolve(cwd, loaded.output),
     };
   }
 
   // Interactive selection
   const refs = await selectRefs(cwd);
-  const rules = await selectRules(cwd);
+  const rule = await selectRule(cwd);
   const output = await selectOutput(cwd);
 
-  return { refs, rules, output };
+  return { refs, rule, output };
 }

package/src/prompt.ts

@@ -49,11 +49,11 @@ ${rulesContent}
 }
 
 /**
- * Read rules file and build complete prompt
+ * Read rule file and build complete prompt
  */
 export async function createPrompt(config: RalphConfig): Promise<string> {
-  const rulesFile = Bun.file(config.rules);
-  const rulesContent = await rulesFile.text();
+  const ruleFile = Bun.file(config.rule);
+  const ruleContent = await ruleFile.text();
 
-  return buildPrompt(config, rulesContent);
+  return buildPrompt(config, ruleContent);
 }

package/src/runner.ts

@@ -85,6 +85,23 @@ async function countRefs(refs: string[]): Promise<number> {
   return count;
 }
 
+// Track current subprocess for cleanup
+let currentProc: ReturnType<typeof Bun.spawn> | null = null;
+
+/**
+ * Kill any running subprocess on exit
+ */
+export function cleanupSubprocess() {
+  if (currentProc) {
+    try {
+      currentProc.kill();
+    } catch {
+      // Process may have already exited
+    }
+    currentProc = null;
+  }
+}
+
 /**
  * Run a single Claude iteration
  */
@@ -105,11 +122,15 @@ async function runIteration(
     stderr: "pipe",
     cwd,
   });
+  
+  currentProc = proc;
 
   // Collect output
   const stdout = await new Response(proc.stdout).text();
   const stderr = await new Response(proc.stderr).text();
   const exitCode = await proc.exited;
+  
+  currentProc = null;
 
   const output = stdout + stderr;
 

package/src/types.ts

@@ -1,14 +1,9 @@
-/**
- * Path selection mode for CLI prompts
- */
-export type PathSelectionMode = "manual" | "select" | "file";
-
 /**
  * Configuration loaded from a paths file (e.g., ralph.paths.json)
  */
 export interface PathsFileConfig {
   refs: string[];
-  rules: string;
+  rule: string;
   output: string;
 }
 
@@ -18,8 +13,8 @@ export interface PathsFileConfig {
 export interface RalphConfig {
   /** Paths to reference material directories/files */
   refs: string[];
-  /** Path to the rules file (.mdc or .md) */
-  rules: string;
+  /** Path to the rule file (.mdc or .md) */
+  rule: string;
   /** Output directory for generated docs */
   output: string;
 }