ralph-cli-sandboxed 0.2.5 → 0.2.7

package/dist/commands/run.js

@@ -1,9 +1,140 @@
 import { spawn } from "child_process";
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, appendFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
 import { validatePrd, smartMerge, readPrdFile, writePrd, expandPrdFileReferences } from "../utils/prd-validator.js";
+/**
+ * Parses a stream-json line and extracts displayable text.
+ * Formats output similar to Claude Code's normal terminal display.
+ */
+function parseStreamJsonLine(line, debug = false) {
+    try {
+        const json = JSON.parse(line);
+        if (debug && json.type) {
+            process.stderr.write(`[stream-json] type: ${json.type}\n`);
+        }
+        // Handle Claude Code CLI stream-json events
+        const type = json.type;
+        switch (type) {
+            // === Text Content ===
+            case "content_block_delta":
+                // Incremental text updates - the main streaming content
+                if (json.delta?.type === "text_delta") {
+                    return json.delta.text || "";
+                }
+                // Tool input being streamed
+                if (json.delta?.type === "input_json_delta") {
+                    return ""; // Don't show partial JSON, wait for complete tool call
+                }
+                return json.delta?.text || "";
+            case "text":
+                return json.text || "";
+            // === Tool Use ===
+            case "content_block_start":
+                if (json.content_block?.type === "tool_use") {
+                    const toolName = json.content_block?.name || "unknown";
+                    return `\n── Tool: ${toolName} ──\n`;
+                }
+                if (json.content_block?.type === "text") {
+                    return json.content_block?.text || "";
+                }
+                return "";
+            case "content_block_stop":
+                // End of a content block - add newline after tool use
+                return "";
+            // === Tool Results ===
+            case "tool_result":
+                const toolOutput = json.content || json.output || "";
+                const truncated = typeof toolOutput === "string" && toolOutput.length > 500
+                    ? toolOutput.substring(0, 500) + "... (truncated)"
+                    : toolOutput;
+                return `\n── Tool Result ──\n${typeof truncated === "string" ? truncated : JSON.stringify(truncated, null, 2)}\n`;
+            // === Assistant Messages ===
+            case "assistant":
+                const contents = json.message?.content || json.content || [];
+                let output = "";
+                for (const block of contents) {
+                    if (block.type === "text") {
+                        output += block.text || "";
+                    }
+                    else if (block.type === "tool_use") {
+                        output += `\n── Tool: ${block.name} ──\n`;
+                        if (block.input) {
+                            output += JSON.stringify(block.input, null, 2) + "\n";
+                        }
+                    }
+                }
+                return output;
+            case "message_start":
+                // Beginning of a new message
+                return "\n";
+            case "message_delta":
+                // Message completion info (stop_reason, usage)
+                if (json.delta?.stop_reason) {
+                    return `\n[${json.delta.stop_reason}]\n`;
+                }
+                return "";
+            case "message_stop":
+                return "\n";
+            // === System/User Events ===
+            case "system":
+                if (json.message) {
+                    return `[System] ${json.message}\n`;
+                }
+                return "";
+            case "user":
+                // User message echo - usually not needed to display
+                return "";
+            // === Results and Errors ===
+            case "result":
+                if (json.result !== undefined) {
+                    return `\n── Result ──\n${JSON.stringify(json.result, null, 2)}\n`;
+                }
+                return "";
+            case "error":
+                const errMsg = json.error?.message || JSON.stringify(json.error);
+                return `\n[Error] ${errMsg}\n`;
+            // === File Operations (Claude Code specific) ===
+            case "file_edit":
+            case "file_write":
+                const filePath = json.path || json.file || "unknown";
+                return `\n── Writing: ${filePath} ──\n`;
+            case "file_read":
+                const readPath = json.path || json.file || "unknown";
+                return `── Reading: ${readPath} ──\n`;
+            case "bash":
+            case "command":
+                const cmd = json.command || json.content || "";
+                return `\n── Running: ${cmd} ──\n`;
+            case "bash_output":
+            case "command_output":
+                const cmdOutput = json.output || json.content || "";
+                return cmdOutput + "\n";
+            default:
+                // Fallback: check for common text fields
+                if (json.text)
+                    return json.text;
+                if (json.content && typeof json.content === "string")
+                    return json.content;
+                if (json.message && typeof json.message === "string")
+                    return json.message;
+                if (json.output && typeof json.output === "string")
+                    return json.output;
+                if (debug) {
+                    process.stderr.write(`[stream-json] unhandled type: ${type}, keys: ${Object.keys(json).join(", ")}\n`);
+                }
+                return "";
+        }
+    }
+    catch (e) {
+        // Not valid JSON
+        if (debug) {
+            process.stderr.write(`[stream-json] parse error: ${e}\n`);
+        }
+        return "";
+    }
+}
 const CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
 /**
  * Creates a filtered PRD file containing only incomplete items (passes: false).
@@ -71,9 +202,11 @@ function syncPassesFromTasks(tasksPath, prdPath) {
         return 0;
     }
 }
-async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model) {
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model, streamJson) {
     return new Promise((resolve, reject) => {
         let output = "";
+        let jsonLogPath;
+        let lineBuffer = ""; // Buffer for incomplete JSON lines
         // Build CLI arguments: config args + yolo args + model args + prompt args
         const cliArgs = [
             ...(cliConfig.args ?? []),
@@ -84,6 +217,19 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
             const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
             cliArgs.push(...yoloArgs);
         }
+        // Add stream-json output format if enabled
+        if (streamJson?.enabled) {
+            cliArgs.push("--output-format", "stream-json", "--verbose", "--print");
+            // Setup JSON log file if saving raw JSON
+            if (streamJson.saveRawJson) {
+                const outputDir = join(process.cwd(), streamJson.outputDir);
+                if (!existsSync(outputDir)) {
+                    mkdirSync(outputDir, { recursive: true });
+                }
+                const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+                jsonLogPath = join(outputDir, `ralph-run-${timestamp}.jsonl`);
+            }
+        }
         // Add model args if model is specified
         if (model && cliConfig.modelArgs) {
             cliArgs.push(...cliConfig.modelArgs, model);
@@ -95,16 +241,85 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
         cliArgs.push(...promptArgs, promptValue);
         if (debug) {
             console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+            if (jsonLogPath) {
+                console.log(`[debug] Saving raw JSON to: ${jsonLogPath}\n`);
+            }
         }
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: ["inherit", "pipe", "inherit"],
         });
         proc.stdout.on("data", (data) => {
             const chunk = data.toString();
-            output += chunk;
-            process.stdout.write(chunk);
+            if (streamJson?.enabled) {
+                // Process stream-json output: parse JSON and display clean text
+                lineBuffer += chunk;
+                const lines = lineBuffer.split("\n");
+                // Keep the last incomplete line in the buffer
+                lineBuffer = lines.pop() || "";
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    if (!trimmedLine)
+                        continue;
+                    // Check if this is a JSON line
+                    if (trimmedLine.startsWith("{")) {
+                        // Save raw JSON if enabled
+                        if (jsonLogPath) {
+                            try {
+                                appendFileSync(jsonLogPath, trimmedLine + "\n");
+                            }
+                            catch {
+                                // Ignore write errors
+                            }
+                        }
+                        // Parse and display clean text
+                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        if (text) {
+                            process.stdout.write(text);
+                            output += text; // Accumulate parsed text for completion detection
+                        }
+                    }
+                    else {
+                        // Non-JSON line - display as-is (might be status messages, errors, etc.)
+                        process.stdout.write(trimmedLine + "\n");
+                        output += trimmedLine + "\n";
+                    }
+                }
+            }
+            else {
+                // Standard output: pass through as-is
+                output += chunk;
+                process.stdout.write(chunk);
+            }
         });
         proc.on("close", (code) => {
+            // Process any remaining buffered content
+            if (streamJson?.enabled && lineBuffer.trim()) {
+                const trimmedLine = lineBuffer.trim();
+                if (trimmedLine.startsWith("{")) {
+                    if (jsonLogPath) {
+                        try {
+                            appendFileSync(jsonLogPath, trimmedLine + "\n");
+                        }
+                        catch {
+                            // Ignore write errors
+                        }
+                    }
+                    const text = parseStreamJsonLine(trimmedLine, debug);
+                    if (text) {
+                        process.stdout.write(text);
+                        output += text;
+                    }
+                }
+                else {
+                    // Non-JSON remaining content
+                    process.stdout.write(trimmedLine + "\n");
+                    output += trimmedLine + "\n";
+                }
+            }
+            // Ensure final newline for clean output
+            if (streamJson?.enabled) {
+                process.stdout.write("\n");
+            }
             resolve({ exitCode: code ?? 0, output });
         });
         proc.on("error", (err) => {
@@ -265,6 +480,13 @@ export async function run(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
+    // Check if stream-json output is enabled
+    const streamJsonConfig = config.docker?.asciinema?.streamJson;
+    const streamJson = streamJsonConfig?.enabled ? {
+        enabled: true,
+        saveRawJson: streamJsonConfig.saveRawJson !== false, // default true
+        outputDir: config.docker?.asciinema?.outputDir || ".recordings",
+    } : undefined;
     // Progress tracking: stop only if no tasks complete after N iterations
     const MAX_ITERATIONS_WITHOUT_PROGRESS = 3;
     // Get requested iteration count (may be adjusted dynamically)
@@ -285,6 +507,12 @@ export async function run(args) {
     if (category) {
         console.log(`Filtering PRD items by category: ${category}`);
     }
+    if (streamJson?.enabled) {
+        console.log("Stream JSON output enabled - displaying formatted Claude output");
+        if (streamJson.saveRawJson) {
+            console.log(`Raw JSON logs will be saved to: ${streamJson.outputDir}/`);
+        }
+    }
     console.log();
     // Track temp file for cleanup
     let filteredPrdPath = null;
@@ -381,7 +609,7 @@ export async function run(args) {
                     break;
                 }
             }
-            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model, streamJson);
             // Sync any completed items from prd-tasks.json back to prd.json
             // This catches cases where the LLM updated prd-tasks.json instead of prd.json
             syncPassesFromTasks(filteredPrdPath, paths.prd);

package/dist/config/languages.json

@@ -259,7 +259,7 @@
       "checkCommand": "swift build",
       "testCommand": "swift test",
       "docker": {
-        "install": "# Install Swift toolchain\nRUN apt-get update && apt-get install -y \\\n    binutils \\\n    git \\\n    gnupg2 \\\n    libc6-dev \\\n    libcurl4-openssl-dev \\\n    libedit2 \\\n    libgcc-11-dev \\\n    libpython3-dev \\\n    libsqlite3-0 \\\n    libstdc++-11-dev \\\n    libxml2-dev \\\n    libz3-dev \\\n    pkg-config \\\n    tzdata \\\n    unzip \\\n    zlib1g-dev \\\n    && rm -rf /var/lib/apt/lists/*\nRUN ARCH=$(dpkg --print-architecture) && \\\n    if [ \"$ARCH\" = \"amd64\" ]; then SWIFT_ARCH=\"x86_64\"; else SWIFT_ARCH=\"aarch64\"; fi && \\\n    curl -fsSL https://download.swift.org/swift-5.10-release/ubuntu2204/swift-5.10-RELEASE/swift-5.10-RELEASE-ubuntu22.04-${SWIFT_ARCH}.tar.gz | tar -xz -C /opt\nENV PATH=\"/opt/swift-5.10-RELEASE-ubuntu22.04/usr/bin:$PATH\""
+        "install": "# Install Swift toolchain\nRUN apt-get update && apt-get install -y \\\n    binutils \\\n    git \\\n    gnupg2 \\\n    libc6-dev \\\n    libcurl4-openssl-dev \\\n    libedit2 \\\n    libgcc-11-dev \\\n    libpython3-dev \\\n    libsqlite3-0 \\\n    libstdc++-11-dev \\\n    libxml2-dev \\\n    libz3-dev \\\n    pkg-config \\\n    tzdata \\\n    unzip \\\n    zlib1g-dev \\\n    && rm -rf /var/lib/apt/lists/*\nRUN ARCH=$(dpkg --print-architecture) && \\\n    if [ \"$ARCH\" = \"amd64\" ]; then \\\n        SWIFT_PLATFORM=\"ubuntu2204\"; \\\n        SWIFT_FILE=\"swift-5.10-RELEASE-ubuntu22.04\"; \\\n    else \\\n        SWIFT_PLATFORM=\"ubuntu2204-aarch64\"; \\\n        SWIFT_FILE=\"swift-5.10-RELEASE-ubuntu22.04-aarch64\"; \\\n    fi && \\\n    curl -fsSL https://download.swift.org/swift-5.10-release/${SWIFT_PLATFORM}/swift-5.10-RELEASE/${SWIFT_FILE}.tar.gz | tar -xz -C /opt && \\\n    mv /opt/${SWIFT_FILE} /opt/swift\nENV PATH=\"/opt/swift/usr/bin:$PATH\""
       },
       "technologies": [
         { "name": "Vapor", "description": "Server-side Swift web framework" },

package/dist/config/skills.json

@@ -0,0 +1,12 @@
+{
+  "skills": {
+    "swift": [
+      {
+        "name": "swift-main-naming",
+        "description": "Prevents naming files main.swift when using @main attribute",
+        "instructions": "IMPORTANT: In Swift, files containing the @main attribute MUST NOT be named main.swift.\n\nWhen the @main attribute is used (e.g., @main struct App), Swift automatically generates an entry point. If the file is also named main.swift, Swift treats it as having a manual entry point, causing a conflict.\n\nRULES:\n- Never name a file main.swift if it contains @main attribute\n- Use descriptive names like App.swift, MyApp.swift, or the actual type name\n- If you encounter a main.swift with @main, rename it to match the type (e.g., struct MyApp -> MyApp.swift)\n\nEXAMPLES:\n\nBAD:\n```\n// main.swift\n@main\nstruct App {\n    static func main() { ... }\n}\n```\n\nGOOD:\n```\n// App.swift\n@main\nstruct App {\n    static func main() { ... }\n}\n```",
+        "userInvocable": false
+      }
+    ]
+  }
+}

package/dist/templates/prompts.d.ts

@@ -48,9 +48,20 @@ export interface CliProviderConfig {
 interface CliProvidersJson {
     providers: Record<string, CliProviderConfig>;
 }
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    instructions: string;
+    userInvocable?: boolean;
+}
+interface SkillsJson {
+    skills: Record<string, SkillDefinition[]>;
+}
 export declare function getLanguagesJson(): LanguagesJson;
 export declare function getCliProvidersJson(): CliProvidersJson;
 export declare function getCliProviders(): Record<string, CliProviderConfig>;
+export declare function getSkillsJson(): SkillsJson;
+export declare function getSkillsForLanguage(language: string): SkillDefinition[];
 export declare function getLanguages(): Record<string, LanguageConfig>;
 export declare const LANGUAGES: Record<string, LanguageConfig>;
 export declare function generatePromptTemplate(): string;

package/dist/templates/prompts.js

@@ -17,6 +17,12 @@ function loadCliProvidersConfig() {
     const content = readFileSync(configPath, "utf-8");
     return JSON.parse(content);
 }
+// Load skills from JSON config file
+function loadSkillsConfig() {
+    const configPath = join(__dirname, "..", "config", "skills.json");
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+}
 // Convert JSON config to the legacy format for compatibility
 function convertToLanguageConfig(config) {
     return {
@@ -31,6 +37,7 @@ function convertToLanguageConfig(config) {
 let _languagesCache = null;
 let _languagesJsonCache = null;
 let _cliProvidersCache = null;
+let _skillsCache = null;
 export function getLanguagesJson() {
     if (!_languagesJsonCache) {
         _languagesJsonCache = loadLanguagesConfig();
@@ -46,6 +53,16 @@ export function getCliProvidersJson() {
 export function getCliProviders() {
     return getCliProvidersJson().providers;
 }
+export function getSkillsJson() {
+    if (!_skillsCache) {
+        _skillsCache = loadSkillsConfig();
+    }
+    return _skillsCache;
+}
+export function getSkillsForLanguage(language) {
+    const skills = getSkillsJson().skills;
+    return skills[language] || [];
+}
 export function getLanguages() {
     if (!_languagesCache) {
         const json = getLanguagesJson();

package/dist/utils/config.d.ts

@@ -5,6 +5,27 @@ export interface CliConfig {
     promptArgs?: string[];
     modelArgs?: string[];
 }
+export interface McpServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface SkillConfig {
+    name: string;
+    description: string;
+    instructions: string;
+    userInvocable?: boolean;
+}
+export interface StreamJsonConfig {
+    enabled: boolean;
+    saveRawJson?: boolean;
+}
+export interface AsciinemaConfig {
+    enabled: boolean;
+    autoRecord?: boolean;
+    outputDir?: string;
+    streamJson?: StreamJsonConfig;
+}
 export interface RalphConfig {
     language: string;
     checkCommand: string;
@@ -23,6 +44,20 @@ export interface RalphConfig {
             name?: string;
             email?: string;
         };
+        packages?: string[];
+        buildCommands?: {
+            root?: string[];
+            node?: string[];
+        };
+        startCommand?: string;
+        asciinema?: AsciinemaConfig;
+        firewall?: {
+            allowedDomains?: string[];
+        };
+    };
+    claude?: {
+        mcpServers?: Record<string, McpServerConfig>;
+        skills?: SkillConfig[];
     };
 }
 export declare const DEFAULT_CLI_CONFIG: CliConfig;

package/dist/utils/prompt.d.ts

@@ -5,6 +5,6 @@ export declare function createPrompt(): {
 export declare function promptSelectWithArrows(message: string, options: string[]): Promise<string>;
 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>;
+export declare function promptConfirm(message: string, defaultValue?: boolean): Promise<boolean>;
 export declare function promptMultiSelect(message: string, options: string[]): Promise<string[]>;
 export declare function promptMultiSelectWithArrows(message: string, options: string[]): Promise<string[]>;

package/dist/utils/prompt.js

@@ -96,11 +96,17 @@ export async function promptSelect(message, options) {
         console.log("Invalid selection.");
     }
 }
-export async function promptConfirm(message) {
+export async function promptConfirm(message, defaultValue = true) {
     const prompt = createPrompt();
+    const hint = defaultValue ? "(Y/n)" : "(y/N)";
     while (true) {
-        const answer = await prompt.question(`${message} (y/n): `);
+        const answer = await prompt.question(`${message} ${hint}: `);
         const normalized = answer.trim().toLowerCase();
+        // Empty input returns default
+        if (normalized === "") {
+            prompt.close();
+            return defaultValue;
+        }
         if (normalized === "y" || normalized === "yes") {
             prompt.close();
             return true;

package/docs/DEVELOPMENT.md

@@ -0,0 +1,161 @@
+# Development
+
+Guide for contributing to ralph-cli-sandboxed.
+
+## Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/choas/ralph-cli-sandboxed
+cd ralph-cli-sandboxed
+
+# Install dependencies
+npm install
+```
+
+## Development Mode
+
+Run ralph directly from TypeScript source without building:
+
+```bash
+npm run dev -- <args>
+
+# Examples:
+npm run dev -- --version
+npm run dev -- list
+npm run dev -- once
+npm run dev -- help
+```
+
+This uses `tsx` to run TypeScript directly, allowing you to test changes immediately.
+
+## Building
+
+```bash
+# Build for distribution
+npm run build
+
+# This runs:
+# 1. tsc - Compiles TypeScript to dist/
+# 2. Copies config files to dist/config/
+```
+
+## Project Structure
+
+```
+ralph-cli-sandboxed/
+├── src/
+│   ├── index.ts              # CLI entry point
+│   ├── commands/             # Command implementations
+│   │   ├── init.ts           # ralph init
+│   │   ├── run.ts            # ralph run
+│   │   ├── once.ts           # ralph once
+│   │   ├── prd.ts            # PRD management commands
+│   │   ├── docker.ts         # Docker commands
+│   │   ├── prompt.ts         # ralph prompt
+│   │   ├── fix-prd.ts        # ralph fix-prd
+│   │   └── help.ts           # ralph help
+│   ├── utils/
+│   │   ├── config.ts         # Configuration loading
+│   │   ├── prd-validator.ts  # PRD validation and recovery
+│   │   └── prompt.ts         # Interactive prompts
+│   ├── templates/
+│   │   └── prompts.ts        # Prompt template generation
+│   └── config/
+│       ├── languages.json    # Language configurations
+│       └── cli-providers.json # CLI provider configurations
+├── docs/                     # Documentation
+├── dist/                     # Compiled output (generated)
+└── package.json
+```
+
+## Adding a New Language
+
+Edit `src/config/languages.json`:
+
+```json
+{
+  "languages": {
+    "your-language": {
+      "name": "Your Language",
+      "description": "Description here",
+      "checkCommand": "your-check-command",
+      "testCommand": "your-test-command",
+      "docker": {
+        "install": "# Installation commands for Dockerfile"
+      },
+      "technologies": [
+        { "name": "Framework", "description": "Description" }
+      ]
+    }
+  }
+}
+```
+
+## Adding a New CLI Provider
+
+Edit `src/config/cli-providers.json`:
+
+```json
+{
+  "providers": {
+    "your-cli": {
+      "name": "Your CLI",
+      "description": "Description",
+      "command": "cli-command",
+      "defaultArgs": [],
+      "yoloArgs": ["--auto-approve-flag"],
+      "promptArgs": ["--prompt"],
+      "docker": {
+        "install": "# Installation commands"
+      },
+      "envVars": ["YOUR_API_KEY"],
+      "modelArgs": ["--model"]
+    }
+  }
+}
+```
+
+## Testing Changes
+
+Since ralph automates AI agents, testing requires caution:
+
+1. **Use a test project** - Create a sample project to test changes
+2. **Use `ralph once`** - Run single iterations for testing
+3. **Check output** - Review `.ralph/progress.txt` and git commits
+
+## Platform-Specific Dependencies
+
+The `node_modules` folder contains platform-specific binaries. If you switch between environments:
+
+```bash
+# When switching between host and container
+rm -rf node_modules && npm install
+```
+
+Or use a separate volume for container node_modules:
+
+```bash
+docker run -v $(pwd):/workspace -v /workspace/node_modules your-image
+```
+
+## Code Style
+
+- TypeScript with ES2022 target
+- Node.js 18+ required
+- Use async/await for asynchronous operations
+- Keep functions focused and small
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## Requirements
+
+- Node.js 18+
+- npm
+- Docker (for testing container functionality)