cralph 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -36,7 +36,7 @@ bun add -g cralph
 ## Quick Start
 
 ```bash
-# In an empty directory - creates starter structure
+# In any directory without .ralph/ - creates starter structure
 cralph
 
 # Edit rule.md with your instructions, then run again
@@ -59,10 +59,11 @@ cralph --yes
 ## How It Works
 
 1. Checks Claude CLI auth (cached for 6 hours)
-2. Loads config from `.ralph/paths.json`
-3. Runs `claude -p --dangerously-skip-permissions` in a loop
-4. Claude updates `.ralph/TODO.md` after each iteration
-5. Stops when Claude outputs `<promise>COMPLETE</promise>`
+2. Looks for `.ralph/` in current directory only (not subdirectories)
+3. Loads config from `.ralph/paths.json` or creates starter structure
+4. Runs `claude -p --dangerously-skip-permissions` in a loop
+5. Claude updates `.ralph/TODO.md` after each iteration
+6. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
 ## Config
 
@@ -102,23 +103,31 @@ Claude maintains this structure:
 Any relevant context
 ```
 
-## First Run (Empty Directory)
+## First Run (No .ralph/ in cwd)
 
 ```
-? No directories found. Create starter structure in /path/to/dir? (Y/n)
+❯ No .ralph/ found in /path/to/dir
+● 📦 Create starter structure
+○ ⚙️  Configure manually
+```
+
+Select **Create starter structure** to generate the default config:
 
+```
 ℹ Created .ralph/refs/ directory
 ℹ Created .ralph/rule.md with starter template
 ℹ Created .ralph/paths.json
 
-╭──────────────────────────────────────────────╮
-│ 1. Add source files to .ralph/refs/          │
-│ 2. Edit .ralph/rule.md with your instructions│
-│ 3. Run cralph again                          │
-╰──────────────────────────────────────────────╯
+╭─────────────────────────────────────────────────╮
+│  1. Add source files to .ralph/refs/            │
+│  2. Edit .ralph/rule.md with your instructions  │
+│  3. Run cralph again                            │
+╰─────────────────────────────────────────────────╯
 ```
 
-Use `--yes` to skip confirmation (for CI/automation).
+Select **Configure manually** to skip starter creation and pick your own refs/rule/output.
+
+Use `--yes` to auto-create starter structure (for CI/automation).
 
 ## Prompts
 
@@ -140,13 +149,25 @@ Use `--yes` to skip confirmation (for CI/automation).
 - **Enter** - Confirm
 - **Ctrl+C** - Exit
 
+## Platform Support
+
+cralph works on **macOS**, **Linux**, and **Windows** with platform-specific handling:
+
+| Platform | Protected Directories Skipped |
+|----------|------------------------------|
+| macOS    | Library, Photos Library, Photo Booth Library |
+| Linux    | lost+found, proc, sys |
+| Windows  | System Volume Information, $Recycle.Bin, Windows |
+
+Permission errors (`EPERM`, `EACCES`) are handled gracefully on all platforms, allowing the CLI to run from any directory.
+
 ## Testing
 
 ```bash
 bun test
 ```
 
-- **Unit tests** - Config, prompt building, CLI
+- **Unit tests** - Config, prompt building, CLI, access error handling, platform detection, shutdown state
 - **E2E tests** - Full loop with Claude (requires auth)
 
 ## Requirements

package/package.json

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

package/src/cli.ts

@@ -5,38 +5,39 @@ import { consola } from "consola";
 import { resolve, join } from "path";
 import { mkdir } from "fs/promises";
 import {
-  buildConfig,
   loadPathsFile,
   validateConfig,
   selectRefs,
   selectRule,
   selectOutput,
   checkForPathsFile,
+  resolvePathsConfig,
+  toRelativePath,
 } from "./paths";
-import { run, cleanupSubprocess, checkClaudeAuth } from "./runner";
+import { run, checkClaudeAuth } from "./runner";
 import type { RalphConfig } from "./types";
+import { setShuttingDown, isShuttingDown, cleanupSubprocess } from "./state";
 
 // Graceful shutdown on Ctrl+C
 function setupGracefulExit() {
-  let shuttingDown = false;
-  
   process.on("SIGINT", () => {
-    if (shuttingDown) {
+    if (isShuttingDown()) {
       // Force exit on second Ctrl+C
-      process.exit(1);
+      Bun.exit(1);
     }
-    shuttingDown = true;
+    setShuttingDown();
     cleanupSubprocess();
     console.log("\n");
     consola.info("Cancelled.");
-    // Use setImmediate to ensure output is flushed
-    setImmediate(() => process.exit(0));
+    // Use Bun.exit for immediate termination
+    Bun.exit(0);
   });
   
   // Also handle SIGTERM
   process.on("SIGTERM", () => {
+    setShuttingDown();
     cleanupSubprocess();
-    process.exit(0);
+    Bun.exit(0);
   });
 }
 
@@ -109,11 +110,7 @@ const main = defineCommand({
         // 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)),
-          rule: resolve(cwd, loaded.rule),
-          output: resolve(cwd, loaded.output),
-        };
+        config = resolvePathsConfig(loaded, cwd);
       } else {
         // Load existing config for edit mode defaults
         let existingConfig: RalphConfig | null = null;
@@ -123,11 +120,7 @@ const main = defineCommand({
           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),
-            };
+            existingConfig = resolvePathsConfig(loaded, cwd);
           }
         } else {
           consola.info("Interactive configuration mode");
@@ -159,9 +152,9 @@ const main = defineCommand({
           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 + "/", ""),
+            refs: config.refs.map((r) => toRelativePath(r, cwd)),
+            rule: toRelativePath(config.rule, cwd),
+            output: toRelativePath(config.output, cwd),
           };
           await Bun.write(
             join(ralphDir, "paths.json"),

package/src/paths.ts

@@ -1,43 +1,69 @@
 import { consola } from "consola";
 import { resolve, join } from "path";
-import { readdir, stat, mkdir } from "fs/promises";
+import { readdir, stat, mkdir, type Dirent } from "fs/promises";
 import type { PathsFileConfig, RalphConfig } from "./types";
+import { isAccessError, shouldExcludeDir } from "./platform";
+import { isShuttingDown } from "./state";
+
+// Starter rule template for new projects
+const STARTER_RULE = `I want a file named hello.txt
+`;
 
 // 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
+ * Convert a PathsFileConfig to a resolved RalphConfig
  */
-async function listDirectories(basePath: string): Promise<string[]> {
-  const entries = await readdir(basePath, { withFileTypes: true });
-  return entries
-    .filter((e) => e.isDirectory() && !e.name.startsWith("."))
-    .map((e) => e.name);
+export function resolvePathsConfig(loaded: PathsFileConfig, cwd: string): RalphConfig {
+  return {
+    refs: loaded.refs.map((r) => resolve(cwd, r)),
+    rule: resolve(cwd, loaded.rule),
+    output: resolve(cwd, loaded.output),
+  };
 }
 
 /**
- * Directories to exclude from listing
+ * Convert an absolute path to a relative path for config storage
+ */
+export function toRelativePath(absolutePath: string, cwd: string): string {
+  if (absolutePath === cwd) return ".";
+  return "./" + absolutePath.replace(cwd + "/", "");
+}
+
+/**
+ * Check if a directory entry should be skipped during traversal
+ */
+function shouldSkipDirectory(entry: Dirent): boolean {
+  if (!entry.isDirectory()) return true;
+  if (entry.name.startsWith(".")) return true;
+  if (shouldExcludeDir(entry.name)) return true;
+  return false;
+}
+
+/**
+ * List directories in a given path
  */
-const EXCLUDED_DIRS = [
-  "node_modules",
-  "dist",
-  "build",
-  ".git",
-  ".next",
-  ".nuxt",
-  ".output",
-  "coverage",
-  "__pycache__",
-  "vendor",
-  ".cache",
-];
+async function listDirectories(basePath: string): Promise<string[]> {
+  try {
+    const entries = await readdir(basePath, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name);
+  } catch (error) {
+    // Silently skip directories we can't access
+    if (isAccessError(error)) {
+      return [];
+    }
+    throw error;
+  }
+}
 
 /**
  * List directories recursively up to a certain depth
  */
-async function listDirectoriesRecursive(
+export async function listDirectoriesRecursive(
   basePath: string,
   maxDepth: number = 3
 ): Promise<string[]> {
@@ -46,12 +72,19 @@ async function listDirectoriesRecursive(
   async function walk(dir: string, depth: number) {
     if (depth > maxDepth) return;
     
-    const entries = await readdir(dir, { withFileTypes: true });
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      // Silently skip directories we can't access
+      if (isAccessError(error)) {
+        return;
+      }
+      throw error;
+    }
+    
     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;
+      if (shouldSkipDirectory(entry)) continue;
       
       const fullPath = join(dir, entry.name);
       results.push(fullPath);
@@ -66,20 +99,28 @@ async function listDirectoriesRecursive(
 /**
  * List files matching patterns in a directory (recursive)
  */
-async function listFilesRecursive(
+export async function listFilesRecursive(
   basePath: string,
   extensions: string[]
 ): Promise<string[]> {
   const results: string[] = [];
 
   async function walk(dir: string) {
-    const entries = await readdir(dir, { withFileTypes: true });
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      // Silently skip directories we can't access
+      if (isAccessError(error)) {
+        return;
+      }
+      throw error;
+    }
+    
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
       if (entry.isDirectory()) {
-        // Skip hidden and excluded directories
-        if (entry.name.startsWith(".")) continue;
-        if (EXCLUDED_DIRS.includes(entry.name)) continue;
+        if (shouldSkipDirectory(entry)) continue;
         await walk(fullPath);
       } else if (entry.isFile()) {
         if (extensions.some((ext) => entry.name.endsWith(ext))) {
@@ -140,27 +181,58 @@ export async function createStarterStructure(cwd: string): Promise<void> {
  * @param autoConfirm - If true, skip confirmation prompts
  */
 export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?: boolean): Promise<string[]> {
-  // Get all directories up to 3 levels deep
-  let allDirs = await listDirectoriesRecursive(cwd, 3);
-  
-  if (allDirs.length === 0) {
+  // Check if .ralph/ exists in cwd - if not, offer to create starter structure
+  const ralphDir = join(cwd, ".ralph");
+  let ralphExists = false;
+  try {
+    await stat(ralphDir);
+    ralphExists = true;
+  } catch {
+    ralphExists = false;
+  }
+
+  if (!ralphExists) {
     // Ask before creating starter structure (skip if autoConfirm)
     if (!autoConfirm) {
-      const confirm = await consola.prompt(
-        `No directories found. Create starter structure in ${cwd}?`,
+      console.log(CONTROLS);
+      const action = await consola.prompt(
+        `No .ralph/ found in ${cwd}`,
         {
-          type: "confirm",
-          initial: true,
+          type: "select",
+          options: [
+            { label: "📦 Create starter structure", value: "create" },
+            { label: "⚙️  Configure manually", value: "manual" },
+          ],
         }
       );
       
-      if (confirm !== true) {
-        throw new Error("Setup cancelled");
+      // 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");
       }
+      
+      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);
+      }
+      
+      // action === "manual" - continue to directory selection
+    } else {
+      // Auto-confirm mode: create starter structure
+      await createStarterStructure(cwd);
+      process.exit(0);
     }
-    
-    await createStarterStructure(cwd);
-    process.exit(0);
+  }
+
+  // Get all directories up to 3 levels deep
+  let allDirs = await listDirectoriesRecursive(cwd, 3);
+  
+  if (allDirs.length === 0) {
+    throw new Error("No directories found to select from");
   }
 
   // Convert to relative paths for display
@@ -192,9 +264,6 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
   return selected as string[];
 }
 
-const STARTER_RULE = `I want a file named hello.txt
-`;
-
 /**
  * Prompt user to select a rule file
  */
@@ -332,27 +401,3 @@ export async function validateConfig(config: RalphConfig): Promise<void> {
 
   // Output directory will be created if needed
 }
-
-/**
- * Interactive configuration builder
- */
-export async function buildConfig(cwd: string): Promise<RalphConfig> {
-  // Check for existing paths file first
-  const pathsFile = await checkForPathsFile(cwd);
-
-  if (pathsFile) {
-    const loaded = await loadPathsFile(pathsFile);
-    return {
-      refs: loaded.refs.map((r) => resolve(cwd, r)),
-      rule: resolve(cwd, loaded.rule),
-      output: resolve(cwd, loaded.output),
-    };
-  }
-
-  // Interactive selection
-  const refs = await selectRefs(cwd);
-  const rule = await selectRule(cwd);
-  const output = await selectOutput(cwd);
-
-  return { refs, rule, output };
-}

package/src/platform.ts

@@ -0,0 +1,113 @@
+import { platform } from "os";
+
+/**
+ * Supported platforms
+ */
+export type Platform = "darwin" | "linux" | "win32" | "unknown";
+
+/**
+ * Get the current platform
+ */
+export function getPlatform(): Platform {
+  const p = platform();
+  if (p === "darwin" || p === "linux" || p === "win32") {
+    return p;
+  }
+  return "unknown";
+}
+
+/**
+ * Platform-specific configuration
+ */
+interface PlatformConfig {
+  /** Error codes that indicate permission/access denied */
+  accessErrorCodes: string[];
+  /** Directories to always exclude from scanning */
+  systemExcludedDirs: string[];
+}
+
+/**
+ * Platform configurations
+ */
+const PLATFORM_CONFIGS: Record<Platform, PlatformConfig> = {
+  darwin: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // macOS protected directories
+      "Library",
+      "Photos Library.photoslibrary",
+      "Photo Booth Library",
+    ],
+  },
+  linux: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // Linux protected directories
+      "lost+found",
+      "proc",
+      "sys",
+    ],
+  },
+  win32: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [
+      // Windows protected directories
+      "System Volume Information",
+      "$Recycle.Bin",
+      "Windows",
+    ],
+  },
+  unknown: {
+    accessErrorCodes: ["EPERM", "EACCES"],
+    systemExcludedDirs: [],
+  },
+};
+
+/**
+ * Get platform-specific configuration
+ */
+export function getPlatformConfig(): PlatformConfig {
+  return PLATFORM_CONFIGS[getPlatform()];
+}
+
+/**
+ * Check if an error is a permission/access error for the current platform
+ */
+export function isAccessError(error: unknown): boolean {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = (error as { code: string }).code;
+    return getPlatformConfig().accessErrorCodes.includes(code);
+  }
+  return false;
+}
+
+/**
+ * Check if a directory should be excluded on the current platform
+ */
+export function isSystemExcludedDir(dirName: string): boolean {
+  return getPlatformConfig().systemExcludedDirs.includes(dirName);
+}
+
+/**
+ * Common directories to exclude across all platforms (project-related)
+ */
+export const EXCLUDED_DIRS = [
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".output",
+  "coverage",
+  "__pycache__",
+  "vendor",
+  ".cache",
+];
+
+/**
+ * Check if a directory should be excluded (combines common + platform-specific)
+ */
+export function shouldExcludeDir(dirName: string): boolean {
+  return EXCLUDED_DIRS.includes(dirName) || isSystemExcludedDir(dirName);
+}

package/src/runner.ts

@@ -4,6 +4,7 @@ import { mkdir } from "fs/promises";
 import { homedir } from "os";
 import type { RalphConfig, RunnerState, IterationResult } from "./types";
 import { createPrompt } from "./prompt";
+import { setCurrentProcess } from "./state";
 
 const COMPLETION_SIGNAL = "<promise>COMPLETE</promise>";
 const AUTH_CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
@@ -175,23 +176,6 @@ async function log(state: RunnerState, message: string): Promise<void> {
   await Bun.write(state.logFile, existing + logLine);
 }
 
-// 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
  */
@@ -213,14 +197,14 @@ async function runIteration(
     cwd,
   });
   
-  currentProc = proc;
+  setCurrentProcess(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;
+  setCurrentProcess(null);
 
   const output = stdout + stderr;
 

package/src/state.ts

@@ -0,0 +1,55 @@
+/**
+ * Global state shared across modules
+ * 
+ * This module provides centralized state management for:
+ * - Graceful shutdown handling (Ctrl+C / SIGINT / SIGTERM)
+ * - Subprocess tracking for cleanup
+ */
+
+// Shutdown state
+let shuttingDown = false;
+
+/**
+ * Mark the process as shutting down
+ */
+export function setShuttingDown(): void {
+  shuttingDown = true;
+}
+
+/**
+ * Check if the process is shutting down (Ctrl+C was pressed)
+ */
+export function isShuttingDown(): boolean {
+  return shuttingDown;
+}
+
+/**
+ * Reset shutdown state (for testing purposes only)
+ */
+export function resetShutdownState(): void {
+  shuttingDown = false;
+}
+
+// Subprocess tracking
+let currentProc: ReturnType<typeof Bun.spawn> | null = null;
+
+/**
+ * Set the current running subprocess for tracking
+ */
+export function setCurrentProcess(proc: ReturnType<typeof Bun.spawn> | null): void {
+  currentProc = proc;
+}
+
+/**
+ * Kill any running subprocess on exit
+ */
+export function cleanupSubprocess(): void {
+  if (currentProc) {
+    try {
+      currentProc.kill();
+    } catch {
+      // Process may have already exited
+    }
+    currentProc = null;
+  }
+}