cralph 1.0.0-beta.2 → 1.0.0-beta.4

package/index.ts

@@ -1,5 +1,7 @@
 // Re-export for programmatic usage
 export * from "./src/types";
-export { buildConfig, loadPathsFile, validateConfig } from "./src/paths";
+export { loadPathsFile, validateConfig, resolvePathsConfig, toRelativePath } from "./src/paths";
 export { createPrompt, buildPrompt } from "./src/prompt";
-export { run, cleanupSubprocess } from "./src/runner";
+export { run, checkClaudeAuth } from "./src/runner";
+export { cleanupSubprocess, setShuttingDown, isShuttingDown } from "./src/state";
+export { getPlatform, isClaudeInstalled, checkClaudeInstallation } from "./src/platform";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cralph",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",
@@ -30,7 +30,8 @@
     "assets"
   ],
   "scripts": {
-    "start": "bun run src/cli.ts"
+    "start": "bun run src/cli.ts",
+    "type-check": "tsgo --noEmit --pretty"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/src/cli.ts

@@ -16,28 +16,30 @@ import {
 } from "./paths";
 import { run, checkClaudeAuth } from "./runner";
 import type { RalphConfig } from "./types";
-import { setShuttingDown, isShuttingDown, cleanupSubprocess } from "./state";
+import { setShuttingDown, isShuttingDown, cleanupSubprocess, throwIfCancelled } from "./state";
+import { checkClaudeInstallation } from "./platform";
 
 // Graceful shutdown on Ctrl+C
 function setupGracefulExit() {
+  const exit = (code: number) => process.exit(code);
+  
   process.on("SIGINT", () => {
     if (isShuttingDown()) {
       // Force exit on second Ctrl+C
-      Bun.exit(1);
+      exit(1);
     }
     setShuttingDown();
     cleanupSubprocess();
     console.log("\n");
     consola.info("Cancelled.");
-    // Use Bun.exit for immediate termination
-    Bun.exit(0);
+    exit(0);
   });
   
   // Also handle SIGTERM
   process.on("SIGTERM", () => {
     setShuttingDown();
     cleanupSubprocess();
-    Bun.exit(0);
+    exit(0);
   });
 }
 
@@ -88,7 +90,17 @@ const main = defineCommand({
     let config: RalphConfig;
 
     try {
-      // Check Claude authentication first - before any prompts
+      // Check Claude CLI is installed first
+      const claudeCheck = await checkClaudeInstallation();
+      
+      if (!claudeCheck.installed) {
+        consola.error("Claude CLI is not installed\n");
+        consola.box(claudeCheck.installInstructions);
+        consola.info("After installing, run cralph again.");
+        process.exit(1);
+      }
+      
+      // Check Claude authentication
       consola.start("Checking Claude authentication...");
       const isAuthed = await checkClaudeAuth();
       
@@ -144,8 +156,11 @@ const main = defineCommand({
         // Offer to save config
         const saveConfig = await consola.prompt("Save configuration to .ralph/paths.json?", {
           type: "confirm",
+          cancel: "symbol",
           initial: true,
         });
+        
+        throwIfCancelled(saveConfig);
 
         if (saveConfig === true) {
           const ralphDir = join(cwd, ".ralph");
@@ -179,8 +194,11 @@ const main = defineCommand({
       if (!args.yes) {
         const proceed = await consola.prompt("Start processing?", {
           type: "confirm",
+          cancel: "symbol",
           initial: true,
         });
+        
+        throwIfCancelled(proceed);
 
         if (proceed !== true) {
           consola.info("Cancelled.");

package/src/paths.ts

@@ -1,9 +1,10 @@
 import { consola } from "consola";
 import { resolve, join } from "path";
-import { readdir, stat, mkdir, type Dirent } from "fs/promises";
+import { readdir, stat, mkdir } from "fs/promises";
+import type { Dirent } from "fs";
 import type { PathsFileConfig, RalphConfig } from "./types";
 import { isAccessError, shouldExcludeDir } from "./platform";
-import { isShuttingDown } from "./state";
+import { throwIfCancelled } from "./state";
 
 // Starter rule template for new projects
 const STARTER_RULE = `I want a file named hello.txt
@@ -199,6 +200,7 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
         `No .ralph/ found in ${cwd}`,
         {
           type: "select",
+          cancel: "symbol",
           options: [
             { label: "📦 Create starter structure", value: "create" },
             { label: "⚙️  Configure manually", value: "manual" },
@@ -206,16 +208,9 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
         }
       );
       
-      // Handle Ctrl+C (returns Symbol) or shutdown in progress or unexpected values
-      if (typeof action === "symbol" || isShuttingDown() || (action !== "create" && action !== "manual")) {
-        throw new Error("Selection cancelled");
-      }
+      throwIfCancelled(action);
       
       if (action === "create") {
-        // Double-check we're not shutting down before executing
-        if (isShuttingDown()) {
-          throw new Error("Selection cancelled");
-        }
         await createStarterStructure(cwd);
         process.exit(0);
       }
@@ -252,16 +247,19 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
   console.log(CONTROLS);
   const selected = await consola.prompt("Select refs directories:", {
     type: "multiselect",
+    cancel: "symbol",
     options,
     initial: initialValues,
   });
 
-  // Handle cancel (symbol) or empty result
-  if (typeof selected === "symbol" || !selected || (Array.isArray(selected) && selected.length === 0)) {
+  // Handle cancel (symbol), shutdown, or empty result
+  throwIfCancelled(selected);
+  if (!selected || (Array.isArray(selected) && selected.length === 0)) {
     throw new Error("Selection cancelled");
   }
   
-  return selected as string[];
+  // Cast is safe: multiselect with string values returns string[]
+  return selected as unknown as string[];
 }
 
 /**
@@ -285,17 +283,18 @@ export async function selectRule(cwd: string, defaultRule?: string): Promise<str
     hint: f === defaultRule ? "current" : (f.endsWith(".mdc") ? "cursor rule" : "markdown"),
   }));
 
-  // Find index of default for initial selection
-  const initialIndex = defaultRule ? files.findIndex((f) => f === defaultRule) : 0;
+  // Find initial value for default selection
+  const initialValue = defaultRule && files.includes(defaultRule) ? defaultRule : files[0];
 
   console.log(CONTROLS);
   const selected = await consola.prompt("Select rule file:", {
     type: "select",
+    cancel: "symbol",
     options,
-    initial: initialIndex >= 0 ? initialIndex : 0,
+    initial: initialValue,
   });
 
-  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+  throwIfCancelled(selected);
   return selected as string;
 }
 
@@ -317,21 +316,20 @@ export async function selectOutput(cwd: string, defaultOutput?: string): Promise
     })),
   ];
 
-  // Find initial index
-  let initialIndex = 0;
-  if (defaultDir) {
-    const idx = defaultDir === "." ? 0 : dirs.findIndex((d) => d === defaultDir) + 1;
-    if (idx >= 0) initialIndex = idx;
-  }
+  // Determine initial value for default selection
+  const initialValue = defaultDir && (defaultDir === "." || dirs.includes(defaultDir)) 
+    ? defaultDir 
+    : ".";
 
   console.log(CONTROLS);
   const selected = await consola.prompt("Select output directory:", {
     type: "select",
+    cancel: "symbol",
     options,
-    initial: initialIndex,
+    initial: initialValue,
   });
 
-  if (typeof selected === "symbol") throw new Error("Selection cancelled");
+  throwIfCancelled(selected);
 
   if (selected === ".") {
     return cwd;
@@ -360,6 +358,7 @@ export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise
       `Found .ralph/paths.json. What would you like to do?`,
       {
         type: "select",
+        cancel: "symbol",
         options: [
           { label: "🚀 Run with this config", value: "run" },
           { label: "✏️  Edit configuration", value: "edit" },
@@ -367,9 +366,7 @@ export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise
       }
     );
     
-    if (typeof action === "symbol") {
-      throw new Error("Selection cancelled");
-    }
+    throwIfCancelled(action);
     
     if (action === "run") {
       return { action: "run", path: filePath };

package/src/platform.ts

@@ -1,4 +1,5 @@
 import { platform } from "os";
+import { which } from "bun";
 
 /**
  * Supported platforms
@@ -111,3 +112,79 @@ export const EXCLUDED_DIRS = [
 export function shouldExcludeDir(dirName: string): boolean {
   return EXCLUDED_DIRS.includes(dirName) || isSystemExcludedDir(dirName);
 }
+
+// ============================================================================
+// Claude CLI Detection
+// ============================================================================
+
+/**
+ * Platform-specific install instructions for Claude CLI
+ */
+const CLAUDE_INSTALL_INSTRUCTIONS: Record<Platform, string> = {
+  darwin: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code
+
+Or via Homebrew:
+  brew install claude`,
+  linux: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+  win32: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+  unknown: `Install Claude CLI:
+  npm install -g @anthropic-ai/claude-code`,
+};
+
+/**
+ * Get platform-specific Claude CLI install instructions
+ */
+export function getClaudeInstallInstructions(): string {
+  return CLAUDE_INSTALL_INSTRUCTIONS[getPlatform()];
+}
+
+/**
+ * Check if Claude CLI is installed and available in PATH
+ */
+export async function isClaudeInstalled(): Promise<boolean> {
+  try {
+    const claudePath = which("claude");
+    return claudePath !== null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Result of Claude CLI check
+ */
+export interface ClaudeCheckResult {
+  installed: boolean;
+  path?: string;
+  installInstructions: string;
+}
+
+/**
+ * Check Claude CLI installation and return detailed result
+ */
+export async function checkClaudeInstallation(): Promise<ClaudeCheckResult> {
+  const installInstructions = getClaudeInstallInstructions();
+  
+  try {
+    const claudePath = which("claude");
+    if (claudePath) {
+      return {
+        installed: true,
+        path: claudePath,
+        installInstructions,
+      };
+    }
+    return {
+      installed: false,
+      installInstructions,
+    };
+  } catch {
+    return {
+      installed: false,
+      installInstructions,
+    };
+  }
+}

package/src/prompt.ts

@@ -2,26 +2,67 @@ import type { RalphConfig } from "./types";
 
 /**
  * The main ralph prompt template.
- * Generic prompt for any Ralph use case.
+ * Based on ralph-ref best practices for autonomous agent loops.
  */
-const BASE_PROMPT = `You are an autonomous agent running in a loop.
+const BASE_PROMPT = `You are an autonomous coding agent running in a loop.
 
 FIRST: Read and internalize the rules provided below.
 
-Your job is to follow the rules and complete the task. Write output to the output directory.
+## Your Task Each Iteration
 
-If refs paths are provided, they are READ-ONLY reference material. Never delete, move, or modify files in refs.
+1. Read the TODO file and check the Patterns section first
+2. Pick the FIRST uncompleted task (marked with [ ])
+3. Implement that SINGLE task
+4. Run quality checks (typecheck, lint, test - whatever the project requires)
+5. If checks pass, mark the task [x] complete
+6. Append your progress with learnings (see format below)
+7. If ALL tasks are complete, output the completion signal
 
-**IMPORTANT: At the end of EVERY iteration, update the TODO file with your progress.**
-Keep the TODO structure with these sections:
-- **# Tasks** - Checklist with [ ] for pending and [x] for done
-- **# Notes** - Any relevant notes or context
+## Critical Rules
 
-STOPPING CONDITION: When done, update the TODO file, then output exactly:
+- **ONE task per iteration** - Do not try to complete multiple tasks
+- **Quality first** - Do NOT mark a task complete if tests/typecheck fail
+- **Keep changes focused** - Minimal, targeted changes only
+- **Follow existing patterns** - Match the codebase style
+
+## Progress Format
+
+After completing a task, APPEND to the Notes section:
+
+\`\`\`
+## [Task Title] - Done
+- What was implemented
+- Files changed
+- **Learnings:**
+  - Patterns discovered
+  - Gotchas encountered
+\`\`\`
+
+## Consolidate Patterns
+
+If you discover a REUSABLE pattern, add it to the **# Patterns** section at the TOP of the TODO file:
+
+\`\`\`
+# Patterns
+- Example: Use \`sql<number>\` template for aggregations
+- Example: Always update X when changing Y
+\`\`\`
+
+Only add patterns that are general and reusable, not task-specific details.
+
+## Refs (Read-Only)
+
+If refs paths are provided, they are READ-ONLY reference material. Never modify files in refs.
+
+## Stop Condition
+
+After completing a task, check if ALL tasks are marked [x] complete.
+
+If ALL tasks are done, output exactly:
 
 <promise>COMPLETE</promise>
 
-This signals the automation to stop. Only output this tag when truly done.`;
+If there are still pending tasks, end your response normally (the loop will continue).`;
 
 /**
  * Build the complete prompt with config and rules injected
@@ -37,18 +78,18 @@ export function buildPrompt(config: RalphConfig, rulesContent: string, todoFile:
 
 ## Configuration
 
-**TODO file (update after each iteration):**
+**TODO file (read first, update after each task):**
 ${todoFile}
 
-**Refs paths (optional, read-only reference material):**
+**Refs (read-only reference material):**
 ${refsList}
 
-**Output directory:**
+**Output directory (write your work here):**
 ${config.output}
 
 ---
 
-## Rules
+## Rules (Your Instructions)
 
 ${rulesContent}
 `;

package/src/runner.ts

@@ -4,19 +4,27 @@ import { mkdir } from "fs/promises";
 import { homedir } from "os";
 import type { RalphConfig, RunnerState, IterationResult } from "./types";
 import { createPrompt } from "./prompt";
-import { setCurrentProcess } from "./state";
+import { setCurrentProcess, throwIfCancelled } from "./state";
 
 const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
 const AUTH_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
 
-const INITIAL_TODO_CONTENT = `# Tasks
+const INITIAL_TODO_CONTENT = `# Patterns
+
+_None yet - add reusable patterns discovered during work_
+
+---
+
+# Tasks
 
 - [ ] Task 1
 - [ ] Task 2
 
+---
+
 # Notes
 
-_None yet_
+_Append progress and learnings here after each iteration_
 `;
 
 /**
@@ -103,7 +111,6 @@ export async function checkClaudeAuth(): Promise<boolean> {
   }
 }
 
-
 /**
  * Check if the TODO file is in a clean/initial state
  */
@@ -150,10 +157,13 @@ Ralph Session: ${state.startTime.toISOString()}
       "Found existing TODO with progress. Reset to start fresh?",
       {
         type: "confirm",
+        cancel: "symbol",
         initial: true,
       }
     );
     
+    throwIfCancelled(response);
+    
     if (response === true) {
       await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
       consola.info("TODO reset to clean state");

package/src/state.ts

@@ -1,12 +1,16 @@
 /**
  * Global state shared across modules
- * 
+ *
  * This module provides centralized state management for:
  * - Graceful shutdown handling (Ctrl+C / SIGINT / SIGTERM)
+ * - Prompt cancellation detection
  * - Subprocess tracking for cleanup
  */
 
-// Shutdown state
+// ============================================================================
+// Shutdown State
+// ============================================================================
+
 let shuttingDown = false;
 
 /**
@@ -30,7 +34,28 @@ export function resetShutdownState(): void {
   shuttingDown = false;
 }
 
-// Subprocess tracking
+// ============================================================================
+// Prompt Cancellation
+// ============================================================================
+
+/**
+ * Check if a prompt result indicates cancellation and throw if so.
+ * Handles Symbol returns from consola prompts (when cancel: "symbol")
+ * and shutdown state.
+ *
+ * @param result - The result from a consola.prompt() call
+ * @throws Error with message "Selection cancelled" if cancelled
+ */
+export function throwIfCancelled(result: unknown): void {
+  if (typeof result === "symbol" || isShuttingDown()) {
+    throw new Error("Selection cancelled");
+  }
+}
+
+// ============================================================================
+// Subprocess Tracking
+// ============================================================================
+
 let currentProc: ReturnType<typeof Bun.spawn> | null = null;
 
 /**