ralph-cli-claude 0.1.0

package/dist/commands/once.d.ts

@@ -0,0 +1 @@
+export declare function once(_args: string[]): Promise<void>;

package/dist/commands/once.js

@@ -0,0 +1,28 @@
+import { spawn } from "child_process";
+import { checkFilesExist, loadPrompt, getPaths } from "../utils/config.js";
+export async function once(_args) {
+    checkFilesExist();
+    const prompt = loadPrompt();
+    const paths = getPaths();
+    console.log("Starting single ralph iteration...\n");
+    return new Promise((resolve, reject) => {
+        const proc = spawn("claude", [
+            "--permission-mode", "acceptEdits",
+            "--dangerously-skip-permissions",
+            "-p",
+            `@${paths.prd} @${paths.progress} ${prompt}`,
+        ], {
+            stdio: "inherit",
+            shell: true,
+        });
+        proc.on("close", (code) => {
+            if (code !== 0) {
+                console.error(`\nClaude exited with code ${code}`);
+            }
+            resolve();
+        });
+        proc.on("error", (err) => {
+            reject(new Error(`Failed to start claude: ${err.message}`));
+        });
+    });
+}

package/dist/commands/prd.d.ts

@@ -0,0 +1 @@
+export declare function prd(args: string[]): Promise<void>;

package/dist/commands/prd.js

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { promptInput, promptSelect } from "../utils/prompt.js";
+import { getRalphDir } from "../utils/config.js";
+const PRD_FILE = "prd.json";
+const CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
+function getPrdPath() {
+    return join(getRalphDir(), PRD_FILE);
+}
+function loadPrd() {
+    const path = getPrdPath();
+    if (!existsSync(path)) {
+        throw new Error(".ralph/prd.json not found. Run 'ralph init' first.");
+    }
+    return JSON.parse(readFileSync(path, "utf-8"));
+}
+function savePrd(entries) {
+    writeFileSync(getPrdPath(), JSON.stringify(entries, null, 2) + "\n");
+}
+async function add() {
+    console.log("Add new PRD entry\n");
+    const category = await promptSelect("Select category:", CATEGORIES);
+    const description = await promptInput("\nDescription: ");
+    if (!description) {
+        console.error("Description is required.");
+        process.exit(1);
+    }
+    console.log("\nEnter verification steps (empty line to finish):");
+    const steps = [];
+    let stepNum = 1;
+    while (true) {
+        const step = await promptInput(`  Step ${stepNum}: `);
+        if (!step)
+            break;
+        steps.push(step);
+        stepNum++;
+    }
+    if (steps.length === 0) {
+        steps.push("Verify the feature works as expected");
+    }
+    const entry = {
+        category,
+        description,
+        steps,
+        passes: false,
+    };
+    const prd = loadPrd();
+    prd.push(entry);
+    savePrd(prd);
+    console.log(`\nAdded entry #${prd.length}: "${description}"`);
+}
+function list() {
+    const prd = loadPrd();
+    if (prd.length === 0) {
+        console.log("No PRD entries found.");
+        return;
+    }
+    console.log("\nPRD Entries:\n");
+    prd.forEach((entry, i) => {
+        const status = entry.passes ? "\x1b[32m[PASS]\x1b[0m" : "\x1b[33m[    ]\x1b[0m";
+        console.log(`  ${i + 1}. ${status} [${entry.category}] ${entry.description}`);
+        entry.steps.forEach((step, j) => {
+            console.log(`       ${j + 1}. ${step}`);
+        });
+        console.log();
+    });
+}
+function status() {
+    const prd = loadPrd();
+    if (prd.length === 0) {
+        console.log("No PRD entries found.");
+        return;
+    }
+    const passing = prd.filter((e) => e.passes).length;
+    const total = prd.length;
+    const percentage = Math.round((passing / total) * 100);
+    console.log(`\nPRD Status: ${passing}/${total} passing (${percentage}%)\n`);
+    // Progress bar
+    const barWidth = 30;
+    const filled = Math.round((passing / total) * barWidth);
+    const bar = "\x1b[32m" + "\u2588".repeat(filled) + "\x1b[0m" + "\u2591".repeat(barWidth - filled);
+    console.log(`  [${bar}]\n`);
+    // By category
+    const byCategory = {};
+    prd.forEach((entry) => {
+        if (!byCategory[entry.category]) {
+            byCategory[entry.category] = { pass: 0, total: 0 };
+        }
+        byCategory[entry.category].total++;
+        if (entry.passes)
+            byCategory[entry.category].pass++;
+    });
+    console.log("  By category:");
+    Object.entries(byCategory).forEach(([cat, stats]) => {
+        console.log(`    ${cat}: ${stats.pass}/${stats.total}`);
+    });
+    if (passing === total) {
+        console.log("\n  \x1b[32m\u2713 All requirements complete!\x1b[0m");
+    }
+    else {
+        const remaining = prd.filter((e) => !e.passes);
+        console.log(`\n  Remaining (${remaining.length}):`);
+        remaining.forEach((entry) => {
+            console.log(`    - [${entry.category}] ${entry.description}`);
+        });
+    }
+}
+function toggle(args) {
+    const index = parseInt(args[0]);
+    if (!index || isNaN(index)) {
+        console.error("Usage: ralph prd toggle <number>");
+        process.exit(1);
+    }
+    const prd = loadPrd();
+    if (index < 1 || index > prd.length) {
+        console.error(`Invalid entry number. Must be 1-${prd.length}`);
+        process.exit(1);
+    }
+    const entry = prd[index - 1];
+    entry.passes = !entry.passes;
+    savePrd(prd);
+    const statusText = entry.passes ? "PASSING" : "NOT PASSING";
+    console.log(`Entry #${index} "${entry.description}" is now ${statusText}`);
+}
+export async function prd(args) {
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "add":
+            await add();
+            break;
+        case "list":
+            list();
+            break;
+        case "status":
+            status();
+            break;
+        case "toggle":
+            toggle(args.slice(1));
+            break;
+        default:
+            console.error("Usage: ralph prd <add|list|status|toggle>");
+            console.error("\nSubcommands:");
+            console.error("  add           Add a new PRD entry");
+            console.error("  list          List all PRD entries");
+            console.error("  status        Show completion status");
+            console.error("  toggle <n>    Toggle passes status for entry n");
+            process.exit(1);
+    }
+}

package/dist/commands/run.d.ts

@@ -0,0 +1 @@
+export declare function run(args: string[]): Promise<void>;

package/dist/commands/run.js

@@ -0,0 +1,64 @@
+import { spawn } from "child_process";
+import { checkFilesExist, loadPrompt, getPaths } from "../utils/config.js";
+async function runIteration(prompt, paths) {
+    return new Promise((resolve, reject) => {
+        let output = "";
+        const proc = spawn("claude", [
+            "--permission-mode", "acceptEdits",
+            "--dangerously-skip-permissions",
+            "-p",
+            `@${paths.prd} @${paths.progress} ${prompt}`,
+        ], {
+            stdio: ["inherit", "pipe", "inherit"],
+            shell: true,
+        });
+        proc.stdout.on("data", (data) => {
+            const chunk = data.toString();
+            output += chunk;
+            process.stdout.write(chunk);
+        });
+        proc.on("close", (code) => {
+            resolve({ exitCode: code ?? 0, output });
+        });
+        proc.on("error", (err) => {
+            reject(new Error(`Failed to start claude: ${err.message}`));
+        });
+    });
+}
+export async function run(args) {
+    const iterations = parseInt(args[0]);
+    if (!iterations || iterations < 1 || isNaN(iterations)) {
+        console.error("Usage: ralph run <iterations>");
+        console.error("  <iterations> must be a positive integer");
+        process.exit(1);
+    }
+    checkFilesExist();
+    const prompt = loadPrompt();
+    const paths = getPaths();
+    console.log(`Starting ${iterations} ralph iteration(s)...\n`);
+    for (let i = 1; i <= iterations; i++) {
+        console.log(`\n${"=".repeat(50)}`);
+        console.log(`Iteration ${i} of ${iterations}`);
+        console.log(`${"=".repeat(50)}\n`);
+        const { exitCode, output } = await runIteration(prompt, paths);
+        if (exitCode !== 0) {
+            console.error(`\nClaude exited with code ${exitCode}`);
+            console.log("Continuing to next iteration...");
+        }
+        // Check for completion signal
+        if (output.includes("<promise>COMPLETE</promise>")) {
+            console.log("\n" + "=".repeat(50));
+            console.log("PRD COMPLETE - All features implemented!");
+            console.log("=".repeat(50));
+            // Try to send notification (optional)
+            try {
+                spawn("tt", ["notify", "Ralph: PRD Complete!"], { stdio: "ignore" });
+            }
+            catch {
+                // tt notify not available, ignore
+            }
+            break;
+        }
+    }
+    console.log("\nRalph run finished.");
+}

package/dist/commands/scripts.d.ts

@@ -0,0 +1 @@
+export declare function scripts(_args: string[]): Promise<void>;

package/dist/commands/scripts.js

@@ -0,0 +1,115 @@
+import { existsSync, writeFileSync, chmodSync } from "fs";
+import { join } from "path";
+import { promptConfirm } from "../utils/prompt.js";
+import { getRalphDir } from "../utils/config.js";
+const RALPH_ONCE_SH = `#!/usr/bin/env bash
+# Generated by ralph-cli
+# Run a single automation iteration
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+RALPH_DIR="$SCRIPT_DIR/.ralph"
+
+if [ ! -f "$RALPH_DIR/prompt.md" ]; then
+  echo "Error: .ralph/prompt.md not found. Run 'ralph init' first."
+  exit 1
+fi
+
+PROMPT=$(cat "$RALPH_DIR/prompt.md")
+
+claude --permission-mode acceptEdits --dangerously-skip-permissions \\
+  -p "@$RALPH_DIR/prd.json @$RALPH_DIR/progress.txt $PROMPT"
+`;
+const RALPH_SH = `#!/usr/bin/env bash
+# Generated by ralph-cli
+# Run multiple automation iterations
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+RALPH_DIR="$SCRIPT_DIR/.ralph"
+
+if [ -z "$1" ]; then
+  echo "Usage: ./ralph.sh <iterations>"
+  echo "  <iterations>  Number of automation cycles to run"
+  exit 1
+fi
+
+if ! [[ "$1" =~ ^[0-9]+$ ]] || [ "$1" -lt 1 ]; then
+  echo "Error: iterations must be a positive integer"
+  exit 1
+fi
+
+ITERATIONS=$1
+
+if [ ! -f "$RALPH_DIR/prompt.md" ]; then
+  echo "Error: .ralph/prompt.md not found. Run 'ralph init' first."
+  exit 1
+fi
+
+PROMPT=$(cat "$RALPH_DIR/prompt.md")
+
+TEMP_FILE=$(mktemp)
+trap "rm -f $TEMP_FILE" EXIT
+
+for ((i=1; i<=ITERATIONS; i++)); do
+  echo ""
+  echo "=================================================="
+  echo "Iteration $i of $ITERATIONS"
+  echo "=================================================="
+  echo ""
+
+  set +e
+  claude --permission-mode acceptEdits --dangerously-skip-permissions \\
+    -p "@$RALPH_DIR/prd.json @$RALPH_DIR/progress.txt $PROMPT" | tee "$TEMP_FILE"
+  set -e
+
+  if grep -q "<promise>COMPLETE</promise>" "$TEMP_FILE"; then
+    echo ""
+    echo "=================================================="
+    echo "PRD COMPLETE - All features implemented!"
+    echo "=================================================="
+
+    # Try to send notification (optional)
+    if command -v tt &> /dev/null; then
+      tt notify "Ralph: PRD Complete!"
+    fi
+
+    break
+  fi
+done
+
+echo ""
+echo "Ralph run finished."
+`;
+export async function scripts(_args) {
+    const cwd = process.cwd();
+    const ralphDir = getRalphDir();
+    // Check if .ralph directory exists (means init was run)
+    if (!existsSync(ralphDir)) {
+        console.error("Error: .ralph/ directory not found. Run 'ralph init' first.");
+        process.exit(1);
+    }
+    console.log("Generate shell scripts for sandboxed environments\n");
+    const files = [
+        { name: "ralph.sh", content: RALPH_SH },
+        { name: "ralph-once.sh", content: RALPH_ONCE_SH },
+    ];
+    for (const file of files) {
+        const filePath = join(cwd, file.name);
+        if (existsSync(filePath)) {
+            const overwrite = await promptConfirm(`${file.name} already exists. Overwrite?`);
+            if (!overwrite) {
+                console.log(`Skipped ${file.name}`);
+                continue;
+            }
+        }
+        writeFileSync(filePath, file.content);
+        chmodSync(filePath, 0o755);
+        console.log(`Created ${file.name}`);
+    }
+    console.log("\nShell scripts created! Usage:");
+    console.log("  ./ralph-once.sh      # Single iteration");
+    console.log("  ./ralph.sh 5         # Run 5 iterations");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { help } from "./commands/help.js";
+import { init } from "./commands/init.js";
+import { once } from "./commands/once.js";
+import { run } from "./commands/run.js";
+import { prd } from "./commands/prd.js";
+import { scripts } from "./commands/scripts.js";
+import { docker } from "./commands/docker.js";
+const commands = {
+    help,
+    init,
+    once,
+    run,
+    prd,
+    scripts,
+    docker,
+};
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        help([]);
+        process.exit(0);
+    }
+    const handler = commands[command];
+    if (!handler) {
+        console.error(`Unknown command: ${command}`);
+        console.error(`Run 'ralph help' for usage information.`);
+        process.exit(1);
+    }
+    try {
+        await handler(args.slice(1));
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error: ${error.message}`);
+        }
+        else {
+            console.error("An unexpected error occurred");
+        }
+        process.exit(1);
+    }
+}
+main();

package/dist/templates/prompts.d.ts

@@ -0,0 +1,10 @@
+export interface LanguageConfig {
+    name: string;
+    checkCommand: string;
+    testCommand: string;
+    description: string;
+}
+export declare const LANGUAGES: Record<string, LanguageConfig>;
+export declare function generatePrompt(config: LanguageConfig): string;
+export declare const DEFAULT_PRD = "[\n  {\n    \"category\": \"setup\",\n    \"description\": \"Example: Project builds successfully\",\n    \"steps\": [\n      \"Run the build command\",\n      \"Verify no errors occur\"\n    ],\n    \"passes\": false\n  }\n]";
+export declare const DEFAULT_PROGRESS = "# Progress Log\n";

package/dist/templates/prompts.js

@@ -0,0 +1,72 @@
+export const LANGUAGES = {
+    bun: {
+        name: "Bun (TypeScript)",
+        checkCommand: "bun check",
+        testCommand: "bun test",
+        description: "Bun runtime with TypeScript",
+    },
+    node: {
+        name: "Node.js (TypeScript)",
+        checkCommand: "npm run typecheck",
+        testCommand: "npm test",
+        description: "Node.js with TypeScript",
+    },
+    python: {
+        name: "Python",
+        checkCommand: "mypy .",
+        testCommand: "pytest",
+        description: "Python with mypy type checking",
+    },
+    go: {
+        name: "Go",
+        checkCommand: "go build ./...",
+        testCommand: "go test ./...",
+        description: "Go language",
+    },
+    rust: {
+        name: "Rust",
+        checkCommand: "cargo check",
+        testCommand: "cargo test",
+        description: "Rust with Cargo",
+    },
+    none: {
+        name: "None (custom)",
+        checkCommand: "echo 'no check configured'",
+        testCommand: "echo 'no tests configured'",
+        description: "Custom configuration",
+    },
+};
+export function generatePrompt(config) {
+    return `You are an AI developer working on this project. Your task is to implement features from the PRD.
+
+INSTRUCTIONS:
+1. Read the @prd.json file to find the highest priority feature that has "passes": false
+2. Implement that feature completely
+3. Verify your changes work by running:
+   - Type/build check: ${config.checkCommand}
+   - Tests: ${config.testCommand}
+4. Update the PRD entry to set "passes": true once verified
+5. Append a brief note about what you did to @progress.txt
+6. Create a git commit with a descriptive message for this feature
+7. Only work on ONE feature per execution
+
+IMPORTANT:
+- Focus on a single feature at a time
+- Ensure all checks pass before marking complete
+- Write clear commit messages
+- If the PRD is fully complete (all items pass), output: <promise>COMPLETE</promise>
+
+Now, read the PRD and begin working on the highest priority incomplete feature.`;
+}
+export const DEFAULT_PRD = `[
+  {
+    "category": "setup",
+    "description": "Example: Project builds successfully",
+    "steps": [
+      "Run the build command",
+      "Verify no errors occur"
+    ],
+    "passes": false
+  }
+]`;
+export const DEFAULT_PROGRESS = `# Progress Log\n`;

package/dist/utils/config.d.ts

@@ -0,0 +1,17 @@
+export interface RalphConfig {
+    language: string;
+    checkCommand: string;
+    testCommand: string;
+    imageName?: string;
+}
+export declare function getRalphDir(): string;
+export declare function loadConfig(): RalphConfig;
+export declare function loadPrompt(): string;
+export declare function checkFilesExist(): void;
+export declare function getPaths(): {
+    dir: string;
+    config: string;
+    prompt: string;
+    prd: string;
+    progress: string;
+};

package/dist/utils/config.js

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+const RALPH_DIR = ".ralph";
+const CONFIG_FILE = "config.json";
+const PROMPT_FILE = "prompt.md";
+const PRD_FILE = "prd.json";
+const PROGRESS_FILE = "progress.txt";
+export function getRalphDir() {
+    return join(process.cwd(), RALPH_DIR);
+}
+export function loadConfig() {
+    const configPath = join(getRalphDir(), CONFIG_FILE);
+    if (!existsSync(configPath)) {
+        throw new Error(".ralph/config.json not found. Run 'ralph init' first.");
+    }
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+}
+export function loadPrompt() {
+    const promptPath = join(getRalphDir(), PROMPT_FILE);
+    if (!existsSync(promptPath)) {
+        throw new Error(".ralph/prompt.md not found. Run 'ralph init' first.");
+    }
+    return readFileSync(promptPath, "utf-8");
+}
+export function checkFilesExist() {
+    const ralphDir = getRalphDir();
+    if (!existsSync(ralphDir)) {
+        throw new Error(".ralph/ directory not found. Run 'ralph init' first.");
+    }
+    const requiredFiles = [CONFIG_FILE, PROMPT_FILE, PRD_FILE, PROGRESS_FILE];
+    for (const file of requiredFiles) {
+        if (!existsSync(join(ralphDir, file))) {
+            throw new Error(`.ralph/${file} not found. Run 'ralph init' first.`);
+        }
+    }
+}
+export function getPaths() {
+    const ralphDir = getRalphDir();
+    return {
+        dir: ralphDir,
+        config: join(ralphDir, CONFIG_FILE),
+        prompt: join(ralphDir, PROMPT_FILE),
+        prd: join(ralphDir, PRD_FILE),
+        progress: join(ralphDir, PROGRESS_FILE),
+    };
+}

package/dist/utils/prompt.d.ts

@@ -0,0 +1,7 @@
+export declare function createPrompt(): {
+    question: (query: string) => Promise<string>;
+    close: () => void;
+};
+export declare function promptInput(message: string): Promise<string>;
+export declare function promptSelect(message: string, options: string[]): Promise<string>;
+export declare function promptConfirm(message: string): Promise<boolean>;

package/dist/utils/prompt.js

@@ -0,0 +1,53 @@
+import * as readline from "readline";
+export function createPrompt() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return {
+        question: (query) => new Promise((resolve) => {
+            rl.question(query, (answer) => {
+                resolve(answer);
+            });
+        }),
+        close: () => rl.close(),
+    };
+}
+export async function promptInput(message) {
+    const prompt = createPrompt();
+    const answer = await prompt.question(message);
+    prompt.close();
+    return answer.trim();
+}
+export async function promptSelect(message, options) {
+    console.log(`\n${message}`);
+    options.forEach((opt, i) => {
+        console.log(`  ${i + 1}. ${opt}`);
+    });
+    const prompt = createPrompt();
+    while (true) {
+        const answer = await prompt.question("\nEnter number: ");
+        const num = parseInt(answer.trim());
+        if (num >= 1 && num <= options.length) {
+            prompt.close();
+            return options[num - 1];
+        }
+        console.log("Invalid selection.");
+    }
+}
+export async function promptConfirm(message) {
+    const prompt = createPrompt();
+    while (true) {
+        const answer = await prompt.question(`${message} (y/n): `);
+        const normalized = answer.trim().toLowerCase();
+        if (normalized === "y" || normalized === "yes") {
+            prompt.close();
+            return true;
+        }
+        if (normalized === "n" || normalized === "no") {
+            prompt.close();
+            return false;
+        }
+        console.log("Please enter y or n.");
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ralph-cli-claude",
+  "version": "0.1.0",
+  "description": "AI-driven development automation CLI for Claude Code",
+  "type": "module",
+  "bin": {
+    "ralph": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "npx tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "readline": "^1.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "cli",
+    "claude",
+    "claude-code",
+    "ai",
+    "automation",
+    "prd",
+    "anthropic",
+    "llm",
+    "developer-tools",
+    "devtools"
+  ],
+  "author": "Lars Gregori",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/choas/ralph-cli-claude.git"
+  },
+  "homepage": "https://github.com/choas/ralph-cli-claude#readme",
+  "bugs": {
+    "url": "https://github.com/choas/ralph-cli-claude/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}