cralph 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -38,10 +38,10 @@ npm install -g cralph
 ## Usage
 
 ```bash
-# Run - auto-detects ralph.paths.json in cwd
+# Run - auto-detects .ralph/paths.json in cwd
 cralph
 
-# First run (no config) - interactive mode generates ralph.paths.json
+# First run (no config) - interactive mode generates .ralph/paths.json
 cralph
 
 # Override with flags
@@ -68,20 +68,41 @@ Simple multiselect for all paths:
 }
 ```
 
-Name it `ralph.paths.json` and cralph auto-detects it. Output is typically `.` (current directory) since you'll run cralph in your repo.
+Save as `.ralph/paths.json` and cralph auto-detects it. Output is typically `.` (current directory) since you'll run cralph in your repo.
 
 ## How It Works
 
-1. Reads your source material from `refs/`
-2. Injects your rules into the prompt
-3. Runs `claude -p --dangerously-skip-permissions` in a loop
-4. Stops when Claude outputs `<promise>COMPLETE</promise>`
+1. Checks if Claude CLI is authenticated (exits with instructions if not)
+2. Reads your source material from `refs/`
+3. Injects your rule into the prompt
+4. Runs `claude -p --dangerously-skip-permissions` in a loop
+5. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
 ## Expected Behavior
 
+**Auth check (runs first):**
+```
+◐ Checking Claude authentication...
+✔ Claude authenticated
+```
+
+If not authenticated:
+```
+◐ Checking Claude authentication...
+✖ Claude CLI is not authenticated
+
+╭─────────────────────╮
+│ claude              │
+│                     │
+│ Then type: /login   │
+╰─────────────────────╯
+
+ℹ After logging in, run cralph again.
+```
+
 **Auto-detect existing config:**
 ```
-❯ Found ralph.paths.json. What would you like to do?
+❯ Found .ralph/paths.json. What would you like to do?
 ● 🚀 Run with this config
 ○ ✏️  Edit configuration
 ```
@@ -109,15 +130,24 @@ Name it `ralph.paths.json` and cralph auto-detects it. Output is typically `.` (
 
 **Save config after selection:**
 ```
-? Save configuration to ralph.paths.json? (Y/n)
-✔ Saved ralph.paths.json
+? Save configuration to .ralph/paths.json? (Y/n)
+✔ Saved .ralph/paths.json
+```
+
+**TODO state check (on run):**
+```
+? Found existing TODO with progress. Reset to start fresh? (y/N)
 ```
+- If the `.ralph/TODO.md` file has been modified from previous runs, you'll be asked whether to reset it
+- Default is **No** (continue with existing progress)
+- Choose **Yes** to start fresh with a clean TODO
 
 **Cancellation:**
 - Press `Ctrl+C` at any time to exit
 - Running Claude processes are terminated cleanly
 
 **Output Files:**
+- `.ralph/paths.json` - Configuration file
 - `.ralph/ralph.log` - Session log with timestamps
 - `.ralph/TODO.md` - Agent status tracker
 
@@ -127,7 +157,8 @@ Name it `ralph.paths.json` and cralph auto-detects it. Output is typically `.` (
 bun test
 ```
 
-Tests validate config loading, prompt building, and CLI behavior without calling Claude.
+- **Unit tests** validate config loading, prompt building, and CLI behavior
+- **E2E tests** run the full loop with Claude (requires authentication)
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cralph",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",

package/src/cli.ts

@@ -2,7 +2,8 @@
 
 import { defineCommand, runMain } from "citty";
 import { consola } from "consola";
-import { resolve } from "path";
+import { resolve, join } from "path";
+import { mkdir } from "fs/promises";
 import {
   buildConfig,
   loadPathsFile,
@@ -12,7 +13,7 @@ import {
   selectOutput,
   checkForPathsFile,
 } from "./paths";
-import { run, cleanupSubprocess } from "./runner";
+import { run, cleanupSubprocess, checkClaudeAuth } from "./runner";
 import type { RalphConfig } from "./types";
 
 // Graceful shutdown on Ctrl+C
@@ -73,6 +74,12 @@ const main = defineCommand({
       alias: "h",
       required: false,
     },
+    yes: {
+      type: "boolean",
+      description: "Auto-confirm all prompts (for CI/automation)",
+      alias: "y",
+      required: false,
+    },
   },
   async run({ args }) {
     setupGracefulExit();
@@ -80,8 +87,23 @@ const main = defineCommand({
     let config: RalphConfig;
 
     try {
+      // Check Claude authentication first - before any prompts
+      consola.start("Checking Claude authentication...");
+      const isAuthed = await checkClaudeAuth();
+      
+      if (!isAuthed) {
+        consola.error("Claude CLI is not authenticated\n");
+        consola.box("claude\n\nThen type: /login");
+        consola.info("After logging in, run cralph again.");
+        process.exit(1);
+      }
+      
+      consola.success("Claude authenticated");
+
       // Check for existing paths file in cwd
-      const pathsFileResult = await checkForPathsFile(cwd);
+      const pathsFileResult = args.yes 
+        ? await checkForPathsFile(cwd, true) // Auto-run if --yes
+        : await checkForPathsFile(cwd);
       
       if (pathsFileResult?.action === "run") {
         // Use existing config file
@@ -97,19 +119,15 @@ const main = defineCommand({
         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;
-            }
+          const filePath = join(cwd, ".ralph", "paths.json");
+          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),
+            };
           }
         } else {
           consola.info("Interactive configuration mode");
@@ -131,22 +149,25 @@ const main = defineCommand({
         config = { refs, rule, output };
 
         // Offer to save config
-        const saveConfig = await consola.prompt("Save configuration to ralph.paths.json?", {
+        const saveConfig = await consola.prompt("Save configuration to .ralph/paths.json?", {
           type: "confirm",
           initial: true,
         });
 
         if (saveConfig === true) {
+          const ralphDir = join(cwd, ".ralph");
+          await mkdir(ralphDir, { recursive: 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"),
+            join(ralphDir, "paths.json"),
             JSON.stringify(pathsConfig, null, 2)
           );
-          consola.success("Saved ralph.paths.json");
+          consola.success("Saved .ralph/paths.json");
         }
       }
 
@@ -161,15 +182,17 @@ const main = defineCommand({
       consola.info(`  Output: ${config.output}`);
       console.log();
 
-      // Confirm before running
-      const proceed = await consola.prompt("Start processing?", {
-        type: "confirm",
-        initial: true,
-      });
+      // Confirm before running (skip if --yes)
+      if (!args.yes) {
+        const proceed = await consola.prompt("Start processing?", {
+          type: "confirm",
+          initial: true,
+        });
 
-      if (proceed !== true) {
-        consola.info("Cancelled.");
-        process.exit(0);
+        if (proceed !== true) {
+          consola.info("Cancelled.");
+          process.exit(0);
+        }
       }
 
       // Run the main loop

package/src/paths.ts

@@ -221,35 +221,38 @@ export async function selectOutput(cwd: string, defaultOutput?: string): Promise
 /**
  * Check if a paths file exists and offer to use it
  * Returns: { action: "run", path: string } | { action: "edit" } | null
+ * @param autoRun - If true, skip prompt and auto-select "run" when config exists
  */
-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()) {
-      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 (typeof action === "symbol") {
-        throw new Error("Selection cancelled");
-      }
-      
-      if (action === "run") {
-        return { action: "run", path: filePath };
+export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise<{ action: "run"; path: string } | { action: "edit" } | null> {
+  const filePath = join(cwd, ".ralph", "paths.json");
+  const file = Bun.file(filePath);
+  
+  if (await file.exists()) {
+    // Auto-run if flag is set
+    if (autoRun) {
+      return { action: "run", path: filePath };
+    }
+    
+    console.log(CONTROLS);
+    const action = await consola.prompt(
+      `Found .ralph/paths.json. What would you like to do?`,
+      {
+        type: "select",
+        options: [
+          { label: "🚀 Run with this config", value: "run" },
+          { label: "✏️  Edit configuration", value: "edit" },
+        ],
       }
-      return { action: "edit" };
+    );
+    
+    if (typeof action === "symbol") {
+      throw new Error("Selection cancelled");
+    }
+    
+    if (action === "run") {
+      return { action: "run", path: filePath };
     }
+    return { action: "edit" };
   }
 
   return null;

package/src/runner.ts

@@ -6,6 +6,67 @@ import { createPrompt } from "./prompt";
 
 const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
 
+const INITIAL_TODO_CONTENT = `# Ralph Agent Status
+
+## Current Status
+
+Idle - waiting for documents in refs/
+
+## Processed Files
+
+_None yet_
+
+## Pending
+
+_Check refs/ for new documents_
+`;
+
+/**
+ * Check if Claude CLI is authenticated by sending a minimal test prompt
+ */
+export async function checkClaudeAuth(): Promise<boolean> {
+  try {
+    // Send a minimal prompt to test auth
+    const proc = Bun.spawn(["claude", "-p"], {
+      stdin: new Blob(["Reply with just 'ok'"]),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    
+    const output = stdout + stderr;
+    
+    // Check for auth errors
+    if (output.includes("authentication_error") || 
+        output.includes("OAuth token has expired") ||
+        output.includes("Please run /login") ||
+        output.includes("401")) {
+      return false;
+    }
+    
+    // If exit code is 0, auth is working
+    return exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+
+/**
+ * Check if the TODO file is in a clean/initial state
+ */
+async function isTodoClean(todoPath: string): Promise<boolean> {
+  const file = Bun.file(todoPath);
+  if (!(await file.exists())) {
+    return true; // Non-existent is considered clean
+  }
+  const content = await file.text();
+  return content.trim() === INITIAL_TODO_CONTENT.trim();
+}
+
 /**
  * Initialize the runner state and log file
  */
@@ -27,26 +88,29 @@ Ralph Session: ${state.startTime.toISOString()}
 
   await Bun.write(state.logFile, logHeader);
 
-  // Initialize TODO file if not exists
+  // Check TODO file state
   const todoFile = Bun.file(state.todoFile);
-  if (!(await todoFile.exists())) {
-    await Bun.write(
-      state.todoFile,
-      `# Ralph Agent Status
-
-## Current Status
-
-Idle - waiting for documents in refs/
-
-## Processed Files
-
-_None yet_
-
-## Pending
-
-_Check refs/ for new documents_
-`
+  const todoExists = await todoFile.exists();
+  
+  if (!todoExists) {
+    // Create fresh TODO file
+    await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
+  } else if (!(await isTodoClean(state.todoFile))) {
+    // TODO exists and has been modified - ask about reset
+    const response = await consola.prompt(
+      "Found existing TODO with progress. Reset to start fresh?",
+      {
+        type: "confirm",
+        initial: false,
+      }
     );
+    
+    if (response === true) {
+      await Bun.write(state.todoFile, INITIAL_TODO_CONTENT);
+      consola.info("TODO reset to clean state");
+    } else {
+      consola.info("Continuing with existing TODO state");
+    }
   }
 
   return state;