ralph-cli-sandboxed 0.7.0 → 0.7.1

package/README.md

@@ -518,9 +518,10 @@ ralph docker run
 
 Features:
 - Based on [Claude Code devcontainer](https://github.com/anthropics/claude-code/tree/main/.devcontainer)
-- Network sandboxing (firewall allows only GitHub, npm, Anthropic API)
+- Network sandboxing (firewall allows only GitHub, npm, Anthropic API, plus language-specific domains — e.g., `deno.land`, `jsr.io`, `esm.sh` for Deno projects)
 - Your `~/.claude` credentials mounted automatically (Pro/Max OAuth)
 - Language-specific tooling pre-installed
+- Language-specific Claude Code hooks (e.g., Deno projects auto-install a `PreToolUse` hook that blocks `npm`/`npx`/`yarn`/`pnpm` commands)
 
 See [docs/DOCKER.md](docs/DOCKER.md) for detailed Docker configuration, customization, and troubleshooting.
 
@@ -554,6 +555,25 @@ Responders handle messages and can answer questions about your codebase:
 
 See [docs/CHAT-CLIENTS.md](docs/CHAT-CLIENTS.md) for chat platform setup and [docs/CHAT-RESPONDERS.md](docs/CHAT-RESPONDERS.md) for responder configuration.
 
+## MCP Server
+
+Ralph provides an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes PRD management as tools for AI assistants. This lets MCP-compatible clients like Claude Code list, add, toggle, and check the status of PRD entries directly through tool calls.
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "ralph-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+See [docs/MCP.md](docs/MCP.md) for available tools, parameters, return values, and example conversations.
+
 ## How It Works
 
 1. **Read PRD**: Claude reads your requirements from `prd.json`

package/dist/commands/docker.js

@@ -657,22 +657,70 @@ else
 fi
 `;
 }
+// Generate block-npm-commands.sh hook script for Deno projects
+function generateBlockNpmCommandsHook() {
+    return `#!/bin/bash
+# Claude Code PreToolUse hook: blocks npm/npx/yarn/pnpm commands in Deno projects
+# Generated by ralph-cli
+#
+# This project uses Deno. npm/npx/yarn/pnpm should not be used for
+# package management or script execution. Use deno commands instead.
+
+set -e
+
+# Read the command from hook JSON input on stdin
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Match package-manager invocations at shell-command boundaries.
+# Examples matched: npm test, cd app && pnpm install
+# Examples ignored: grep "npm test" README.md
+if echo "$COMMAND" | grep -qE '(^|[;&|][&|]?[[:space:]]*)(npm|npx|yarn|pnpm)([[:space:]]|$)'; then
+  jq -n --arg reason "Blocked: This is a Deno project. Use 'deno' commands instead of npm/npx/yarn/pnpm. Examples: 'deno task' instead of 'npm run', 'deno test' instead of 'npm test', 'deno add' or import maps instead of 'npm install'." '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $reason
+    }
+  }'
+else
+  exit 0
+fi
+`;
+}
 // Generate .claude/settings.json with hooks configuration
-function generateClaudeSettings() {
-    const settings = {
-        hooks: {
-            PreToolUse: [
+function generateClaudeSettings(language) {
+    const hooks = [
+        {
+            matcher: "Bash",
+            hooks: [
                 {
-                    matcher: "Bash",
-                    hooks: [
-                        {
-                            type: "command",
-                            command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/block-dangerous-commands.sh',
-                        },
-                    ],
+                    type: "command",
+                    command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/block-dangerous-commands.sh',
                 },
             ],
         },
+    ];
+    // Add Deno-specific hook to block npm commands
+    if (language === "deno") {
+        hooks.push({
+            matcher: "Bash",
+            hooks: [
+                {
+                    type: "command",
+                    command: '"$CLAUDE_PROJECT_DIR"/.claude/hooks/block-npm-commands.sh',
+                },
+            ],
+        });
+    }
+    const settings = {
+        hooks: {
+            PreToolUse: hooks,
+        },
     };
     return JSON.stringify(settings, null, 2) + "\n";
 }
@@ -683,13 +731,17 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         mkdirSync(dockerDir, { recursive: true });
         console.log(`Created ${DOCKER_DIR}/`);
     }
+    // Merge custom firewall domains with language-specific domains
     const customDomains = dockerConfig?.firewall?.allowedDomains || [];
+    const languagesJson = getLanguagesJson();
+    const langFirewallDomains = languagesJson.languages[language]?.docker?.firewallDomains || [];
+    const allFirewallDomains = [...new Set([...customDomains, ...langFirewallDomains])];
     const files = [
         {
             name: "Dockerfile",
             content: generateDockerfile(language, javaVersion, cliProvider, dockerConfig, cliModel),
         },
-        { name: "init-firewall.sh", content: generateFirewallScript(customDomains) },
+        { name: "init-firewall.sh", content: generateFirewallScript(allFirewallDomains) },
         { name: "docker-compose.yml", content: generateDockerCompose(imageName, dockerConfig) },
         { name: ".dockerignore", content: DOCKERIGNORE },
     ];
@@ -794,12 +846,32 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         chmodSync(hookScriptPath, 0o755);
         console.log("Created .claude/hooks/block-dangerous-commands.sh");
     }
+    // Generate Deno-specific hook to block npm commands
+    if (language === "deno") {
+        const npmHookPath = join(hooksDir, "block-npm-commands.sh");
+        if (existsSync(npmHookPath) && !force) {
+            const overwrite = await promptConfirm(".claude/hooks/block-npm-commands.sh already exists. Overwrite?");
+            if (overwrite) {
+                writeFileSync(npmHookPath, generateBlockNpmCommandsHook());
+                chmodSync(npmHookPath, 0o755);
+                console.log("Created .claude/hooks/block-npm-commands.sh");
+            }
+            else {
+                console.log("Skipped .claude/hooks/block-npm-commands.sh");
+            }
+        }
+        else {
+            writeFileSync(npmHookPath, generateBlockNpmCommandsHook());
+            chmodSync(npmHookPath, 0o755);
+            console.log("Created .claude/hooks/block-npm-commands.sh");
+        }
+    }
     // Generate .claude/settings.json with hooks configuration
     const settingsPath = join(projectRoot, ".claude", "settings.json");
     if (existsSync(settingsPath) && !force) {
         const overwrite = await promptConfirm(".claude/settings.json already exists. Overwrite?");
         if (overwrite) {
-            writeFileSync(settingsPath, generateClaudeSettings());
+            writeFileSync(settingsPath, generateClaudeSettings(language));
             console.log("Created .claude/settings.json");
         }
         else {
@@ -807,7 +879,7 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         }
     }
     else {
-        writeFileSync(settingsPath, generateClaudeSettings());
+        writeFileSync(settingsPath, generateClaudeSettings(language));
         console.log("Created .claude/settings.json");
     }
     // Save config hash for change detection

package/dist/commands/run.js

@@ -1,4 +1,4 @@
-import { spawn, execSync } from "child_process";
+import { spawn, execSync, execFileSync } from "child_process";
 import { existsSync, readFileSync, writeFileSync, unlinkSync, appendFileSync, mkdirSync, copyFileSync, } from "fs";
 import { extname, join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer, saveBranchState, loadBranchState, clearBranchState, getProjectName, } from "../utils/config.js";
@@ -62,10 +62,14 @@ function ensureWorktree(branch, worktreesBase) {
         return worktreePath;
     }
     console.log(`\x1b[90m[ralph] Creating worktree for branch "${branch}" at ${worktreePath}\x1b[0m`);
+    // Validate branch name to prevent command injection
+    if (!/^[a-zA-Z0-9_\-./]+$/.test(branch)) {
+        throw new Error(`Invalid branch name "${branch}": contains disallowed characters`);
+    }
     // Check if the branch already exists
     let branchExists = false;
     try {
-        execSync(`git rev-parse --verify "${branch}"`, { stdio: "pipe" });
+        execFileSync("git", ["rev-parse", "--verify", branch], { stdio: "pipe" });
         branchExists = true;
     }
     catch {
@@ -73,11 +77,11 @@ function ensureWorktree(branch, worktreesBase) {
     }
     try {
         if (branchExists) {
-            execSync(`git worktree add "${worktreePath}" "${branch}"`, { stdio: "pipe" });
+            execFileSync("git", ["worktree", "add", worktreePath, branch], { stdio: "pipe" });
         }
         else {
             // Create new branch from current HEAD
-            execSync(`git worktree add -b "${branch}" "${worktreePath}"`, { stdio: "pipe" });
+            execFileSync("git", ["worktree", "add", "-b", branch, worktreePath], { stdio: "pipe" });
         }
     }
     catch (err) {

package/dist/config/languages.json

@@ -376,7 +376,8 @@
       "checkCommand": "deno check **/*.ts",
       "testCommand": "deno test",
       "docker": {
-        "install": "# Install Deno\nRUN curl -fsSL https://deno.land/install.sh | sh\nENV DENO_INSTALL=\"/root/.deno\"\nENV PATH=\"${DENO_INSTALL}/bin:${PATH}\""
+        "install": "# Install Deno (as node user so it installs to /home/node/.deno)\nRUN su - node -c 'curl -fsSL https://deno.land/install.sh | sh'\nENV DENO_INSTALL=\"/home/node/.deno\"\nENV PATH=\"${DENO_INSTALL}/bin:${PATH}\"",
+        "firewallDomains": ["deno.land", "jsr.io", "esm.sh"]
       },
       "technologies": [
         { "name": "Fresh", "description": "Next-gen web framework for Deno" },

package/dist/config/responder-presets.json

@@ -47,6 +47,16 @@
       "trigger": "@code",
       "timeout": 300000,
       "maxLength": 2000
+    },
+    "audit": {
+      "name": "Security Auditor",
+      "description": "Claude Code responder for running npm audit and fixing vulnerabilities",
+      "type": "claude-code",
+      "trigger": "@audit",
+      "systemPrompt": "You are a security auditor for the {{project}} project. Your task is to:\n\n1. Run `npm audit` to identify security vulnerabilities\n2. Analyze the severity and impact of each vulnerability\n3. Run `npm audit fix` to apply safe, non-breaking fixes\n4. For remaining issues that require `--force`, evaluate whether the breaking changes are acceptable and apply them if safe\n5. For vulnerabilities that cannot be auto-fixed, investigate alternatives:\n   - Check if a newer major version of the package resolves the issue\n   - Look for alternative packages without vulnerabilities\n   - Add overrides in package.json if the vulnerability is not exploitable in context\n6. Report a summary of what was fixed and what remains\n\nAlways run `npm audit` again after fixes to verify the final state. Prefer safe fixes over forced ones. Do not remove packages without confirming they are unused.\n\nIMPORTANT: After all fixes are applied, run `npm audit` one final time to verify the result. Include the full audit output in your response so the success pattern can be validated.",
+      "timeout": 300000,
+      "maxLength": 3000,
+      "successPattern": "found 0 vulnerabilities"
     }
   },
   "bundles": {

package/dist/config/skills.json

@@ -8,6 +8,14 @@
         "userInvocable": false
       }
     ],
+    "deno": [
+      {
+        "name": "deno-no-npm",
+        "description": "Prevents using npm/npx, yarn, or pnpm in Deno projects — use deno commands instead",
+        "instructions": "IMPORTANT: This project uses Deno as its runtime. Do NOT use npm, npx, yarn, or pnpm for package management or script execution.\n\nAVOID these commands:\n- `npm install`, `npm run`, `npm test`, `npm start`\n- `npx <package>`\n- `yarn add`, `yarn run`\n- `pnpm install`, `pnpm run`\n- Do NOT create or modify `package.json` for dependency management\n\nINSTEAD, use Deno's built-in tools:\n- Dependencies: Use `import` with URLs or `deno.json` imports map\n  - `import { serve } from \"https://deno.land/std/http/server.ts\";`\n  - Or add to `deno.json`: `{ \"imports\": { \"std/\": \"https://deno.land/std/\" } }`\n  - Use `jsr:` imports for JSR packages: `import { z } from \"jsr:@zod/zod\";`\n- Run scripts: `deno run`, `deno task`\n- Type checking: `deno check`\n- Testing: `deno test`\n- Formatting: `deno fmt`\n- Linting: `deno lint`\n- Install tools: `deno install`\n- Compile: `deno compile`\n\nDeno uses `deno.json` (or `deno.jsonc`) for project configuration, NOT `package.json`.\n\nIf you need an npm package that has no Deno equivalent, use the `npm:` specifier:\n  `import express from \"npm:express\";`\nThis uses Deno's built-in npm compatibility — no need to run `npm install`.",
+        "userInvocable": false
+      }
+    ],
     "swift": [
       {
         "name": "swift-main-naming",

package/dist/mcp-server.d.ts

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

package/dist/mcp-server.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from "fs";
+import { dirname, extname, join } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+import YAML from "yaml";
+import { getRalphDir, getPrdFiles } from "./utils/config.js";
+import { DEFAULT_PRD_YAML } from "./templates/prompts.js";
+import { VALID_CATEGORIES } from "./utils/prd-validator.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CATEGORIES = VALID_CATEGORIES;
+// Structured error codes for MCP tool error responses
+const ErrorCode = {
+    PRD_NOT_FOUND: "PRD_NOT_FOUND",
+    PRD_PARSE_ERROR: "PRD_PARSE_ERROR",
+    PRD_WRITE_ERROR: "PRD_WRITE_ERROR",
+    INVALID_INDEX: "INVALID_INDEX",
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+};
+function classifyError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("No PRD file found") || message.includes("ENOENT")) {
+        return { code: ErrorCode.PRD_NOT_FOUND, message };
+    }
+    if (message.includes("does not contain an array") ||
+        message.includes("JSON") ||
+        message.includes("YAML")) {
+        return { code: ErrorCode.PRD_PARSE_ERROR, message };
+    }
+    if (message.includes("EACCES") || message.includes("EPERM")) {
+        return { code: ErrorCode.PRD_WRITE_ERROR, message };
+    }
+    return { code: ErrorCode.INTERNAL_ERROR, message };
+}
+function errorResponse(code, message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ code, message }),
+            },
+        ],
+        isError: true,
+    };
+}
+const PRD_FILE_JSON = "prd.json";
+/**
+ * Saves PRD entries to disk, auto-detecting format from file extension.
+ */
+function savePrd(entries) {
+    const prdFiles = getPrdFiles();
+    const path = prdFiles.primary ?? join(getRalphDir(), PRD_FILE_JSON);
+    const ext = extname(path).toLowerCase();
+    try {
+        if (ext === ".yaml" || ext === ".yml") {
+            writeFileSync(path, YAML.stringify(entries));
+        }
+        else {
+            writeFileSync(path, JSON.stringify(entries, null, 2) + "\n");
+        }
+        // One-time migration: if a secondary PRD file exists, remove it now that
+        // the merged entries have been written to the primary file.
+        if (prdFiles.secondary && existsSync(prdFiles.secondary)) {
+            unlinkSync(prdFiles.secondary);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to save PRD file at ${path}: ${msg}`);
+    }
+}
+function getVersion() {
+    try {
+        const packagePath = join(__dirname, "..", "package.json");
+        const packageJson = JSON.parse(readFileSync(packagePath, "utf-8"));
+        return packageJson.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Parses a PRD file based on its extension (MCP-safe version that throws instead of process.exit).
+ */
+function parsePrdFile(path) {
+    const content = readFileSync(path, "utf-8");
+    const ext = extname(path).toLowerCase();
+    let result;
+    if (ext === ".yaml" || ext === ".yml") {
+        result = YAML.parse(content);
+    }
+    else {
+        result = JSON.parse(content);
+    }
+    if (result == null)
+        return [];
+    if (!Array.isArray(result)) {
+        throw new Error(`${path} does not contain an array`);
+    }
+    return result.map((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            throw new Error(`${path}[${index}]: entry must be an object`);
+        }
+        const obj = entry;
+        if (typeof obj.category !== "string" || !CATEGORIES.includes(obj.category)) {
+            throw new Error(`${path}[${index}]: missing or invalid "category" (expected one of: ${CATEGORIES.join(", ")})`);
+        }
+        if (typeof obj.description !== "string" || obj.description.trim().length === 0) {
+            throw new Error(`${path}[${index}]: missing or invalid "description" (expected string)`);
+        }
+        if (!Array.isArray(obj.steps) || !obj.steps.every((s) => typeof s === "string")) {
+            throw new Error(`${path}[${index}]: missing or invalid "steps" (expected string array)`);
+        }
+        if (typeof obj.passes !== "boolean") {
+            throw new Error(`${path}[${index}]: missing or invalid "passes" (expected boolean)`);
+        }
+        if (obj.branch !== undefined && typeof obj.branch !== "string") {
+            throw new Error(`${path}[${index}]: invalid "branch" (expected string)`);
+        }
+        return {
+            category: obj.category,
+            description: obj.description,
+            steps: obj.steps,
+            passes: obj.passes,
+            ...(obj.branch !== undefined && { branch: obj.branch }),
+        };
+    });
+}
+/**
+ * Loads PRD entries (MCP-safe version that throws instead of process.exit).
+ */
+function loadPrd() {
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
+        const ralphDir = getRalphDir();
+        const prdPath = join(ralphDir, "prd.yaml");
+        try {
+            if (!existsSync(ralphDir)) {
+                mkdirSync(ralphDir, { recursive: true });
+            }
+            writeFileSync(prdPath, DEFAULT_PRD_YAML);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to save PRD file at ${prdPath}: ${msg}`);
+        }
+        return parsePrdFile(prdPath);
+    }
+    if (!prdFiles.primary) {
+        throw new Error("No PRD file found. Run `ralph init` to create one.");
+    }
+    const primary = parsePrdFile(prdFiles.primary);
+    if (prdFiles.both && prdFiles.secondary) {
+        const secondary = parsePrdFile(prdFiles.secondary);
+        return [...primary, ...secondary];
+    }
+    return primary;
+}
+const server = new McpServer({
+    name: "ralph-mcp",
+    version: getVersion(),
+});
+// ralph_prd_list tool
+server.tool("ralph_prd_list", "List PRD entries with optional category and status filters", {
+    category: z.enum(CATEGORIES).optional().describe("Filter by category"),
+    status: z
+        .enum(["all", "passing", "failing"])
+        .optional()
+        .describe("Filter by status: all (default), passing, or failing"),
+}, async ({ category, status }) => {
+    try {
+        const prd = loadPrd();
+        let filtered = prd.map((entry, i) => ({ ...entry, index: i + 1 }));
+        if (category) {
+            filtered = filtered.filter((entry) => entry.category === category);
+        }
+        if (status === "passing") {
+            filtered = filtered.filter((entry) => entry.passes);
+        }
+        else if (status === "failing") {
+            filtered = filtered.filter((entry) => !entry.passes);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(filtered, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const { code, message } = classifyError(err);
+        return errorResponse(code, message);
+    }
+});
+// ralph_prd_add tool
+server.tool("ralph_prd_add", "Add a new PRD entry with category, description, and verification steps", {
+    category: z.enum(CATEGORIES).describe("Category for the new entry"),
+    description: z.string().min(1).describe("Description of the requirement"),
+    steps: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("Verification steps to check if requirement is met"),
+    branch: z.string().optional().describe("Git branch associated with this entry"),
+}, async ({ category, description, steps, branch }) => {
+    try {
+        const entry = {
+            category,
+            description,
+            steps,
+            passes: false,
+        };
+        if (branch) {
+            entry.branch = branch;
+        }
+        const prd = loadPrd();
+        prd.push(entry);
+        savePrd(prd);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: `Added entry #${prd.length}: "${description}"`,
+                        entry: { ...entry, index: prd.length },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const { code, message } = classifyError(err);
+        return errorResponse(code, message);
+    }
+});
+// ralph_prd_status tool
+server.tool("ralph_prd_status", "Get PRD completion status with counts, percentage, per-category breakdown, and remaining items", {}, async () => {
+    try {
+        const prd = loadPrd();
+        if (prd.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ passing: 0, total: 0, percentage: 0, categories: {}, remaining: [] }, null, 2),
+                    },
+                ],
+            };
+        }
+        const passing = prd.filter((e) => e.passes).length;
+        const total = prd.length;
+        const percentage = Math.round((passing / total) * 100);
+        const categories = {};
+        prd.forEach((entry) => {
+            if (!categories[entry.category]) {
+                categories[entry.category] = { passing: 0, total: 0 };
+            }
+            categories[entry.category].total++;
+            if (entry.passes)
+                categories[entry.category].passing++;
+        });
+        const remaining = prd.reduce((acc, entry, i) => {
+            if (!entry.passes) {
+                acc.push({ index: i + 1, category: entry.category, description: entry.description });
+            }
+            return acc;
+        }, []);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ passing, total, percentage, categories, remaining }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const { code, message } = classifyError(err);
+        return errorResponse(code, message);
+    }
+});
+// ralph_prd_toggle tool
+server.tool("ralph_prd_toggle", "Toggle completion status (passes) for PRD entries by 1-based index", {
+    indices: z
+        .array(z.number().int().min(1))
+        .min(1)
+        .describe("1-based indices of PRD entries to toggle"),
+}, async ({ indices }) => {
+    try {
+        const prd = loadPrd();
+        // Validate all indices are in range
+        for (const index of indices) {
+            if (index > prd.length) {
+                return errorResponse(ErrorCode.INVALID_INDEX, `Invalid entry number: ${index}. Must be 1-${prd.length}`);
+            }
+        }
+        // Deduplicate and sort
+        const uniqueIndices = [...new Set(indices)].sort((a, b) => a - b);
+        const toggled = uniqueIndices.map((index) => {
+            const entry = prd[index - 1];
+            entry.passes = !entry.passes;
+            return {
+                index,
+                description: entry.description,
+                passes: entry.passes,
+            };
+        });
+        savePrd(prd);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ message: `Toggled ${toggled.length} entry/entries`, toggled }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const { code, message } = classifyError(err);
+        return errorResponse(code, message);
+    }
+});
+function isConnectionError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes("EPIPE") ||
+        message.includes("ECONNRESET") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ERR_USE_AFTER_CLOSE") ||
+        message.includes("write after end") ||
+        message.includes("This socket has been ended") ||
+        message.includes("transport") ||
+        message.includes("broken pipe"));
+}
+async function main() {
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        if (isConnectionError(error)) {
+            console.error("MCP connection error: transport closed or unavailable.");
+            process.exit(0);
+        }
+        console.error("Server error:", error);
+        process.exit(1);
+    }
+}
+process.on("uncaughtException", (error) => {
+    if (isConnectionError(error)) {
+        process.exit(0);
+    }
+    console.error("Uncaught exception:", error);
+    process.exit(1);
+});
+process.on("unhandledRejection", (reason, promise) => {
+    if (isConnectionError(reason)) {
+        process.exit(0);
+    }
+    console.error("Unhandled rejection at:", promise, "reason:", reason);
+    process.exit(1);
+});
+main();

package/dist/responders/claude-code-responder.js

@@ -40,8 +40,15 @@ export async function executeClaudeCodeResponder(prompt, responderConfig, option
         let killed = false;
         let lastProgressSent = 0;
         let progressTimer = null;
+        // Build effective prompt: prepend systemPrompt if configured
+        let effectivePrompt = prompt;
+        if (responderConfig.systemPrompt) {
+            effectivePrompt = prompt
+                ? `${responderConfig.systemPrompt}\n\nUser request: ${prompt}`
+                : responderConfig.systemPrompt;
+        }
         // Build the command arguments
-        const args = ["-p", prompt, "--dangerously-skip-permissions", "--print"];
+        const args = ["-p", effectivePrompt, "--dangerously-skip-permissions", "--print"];
         // Spawn claude process
         let proc;
         try {
@@ -115,6 +122,21 @@ export async function executeClaudeCodeResponder(prompt, responderConfig, option
             if (code === 0 || code === null) {
                 // Success - format and truncate output
                 const output = formatClaudeCodeOutput(stdout);
+                // Check successPattern if configured - output must match for run to succeed
+                if (responderConfig.successPattern) {
+                    const pattern = new RegExp(responderConfig.successPattern, "i");
+                    if (!pattern.test(output)) {
+                        const { text, truncated, originalLength } = truncateResponse(output, maxLength);
+                        resolve({
+                            success: false,
+                            response: text,
+                            error: `Output did not match required success pattern: ${responderConfig.successPattern}`,
+                            truncated,
+                            originalLength: truncated ? originalLength : undefined,
+                        });
+                        return;
+                    }
+                }
                 const { text, truncated, originalLength } = truncateResponse(output, maxLength);
                 resolve({
                     success: true,
@@ -155,7 +177,7 @@ export async function executeClaudeCodeResponder(prompt, responderConfig, option
  */
 function formatClaudeCodeOutput(output) {
     // Remove ANSI escape codes
-    // eslint-disable-next-line no-control-regex
+    // oxlint-disable-next-line no-control-regex
     let cleaned = output.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
     // Remove carriage returns (used for progress overwriting)
     cleaned = cleaned.replace(/\r/g, "");

package/dist/responders/cli-responder.js

@@ -244,7 +244,7 @@ function formatCLIOutput(stdout, stderr) {
         output = output.trim() + "\n\n[stderr]\n" + stderr.trim();
     }
     // Remove ANSI escape codes
-    // eslint-disable-next-line no-control-regex
+    // oxlint-disable-next-line no-control-regex
     let cleaned = output.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
     // Remove carriage returns (used for progress overwriting)
     cleaned = cleaned.replace(/\r/g, "");

package/dist/templates/prompts.d.ts

@@ -8,6 +8,7 @@ export interface DockerConfig {
     versionConfigurable?: boolean;
     gradleVersion?: string;
     kotlinVersion?: string;
+    firewallDomains?: string[];
 }
 export interface LanguageConfigJson {
     name: string;

package/dist/utils/chat-client.js

@@ -84,7 +84,7 @@ export function escapeHtml(text) {
  */
 export function stripAnsiCodes(text) {
     // Match ANSI escape sequences: ESC[...m (SGR), ESC[...K (EL), etc.
-    // eslint-disable-next-line no-control-regex
+    // oxlint-disable-next-line no-control-regex
     return text.replace(/\x1B\[[0-9;]*[mKJHfsu]/g, "");
 }
 /**

package/dist/utils/config.d.ts

@@ -130,6 +130,7 @@ export interface ResponderConfig {
     command?: string;
     timeout?: number;
     maxLength?: number;
+    successPattern?: string;
 }
 /**
  * Named responders configuration.

package/dist/utils/prd-validator.d.ts

@@ -19,6 +19,7 @@ interface ExtractedItem {
     description: string;
     passes: boolean;
 }
+export declare const VALID_CATEGORIES: readonly ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
 /**
  * Validates that a PRD structure is correct.
  * Returns validation result with parsed data if valid.

package/dist/utils/prd-validator.js

@@ -1,7 +1,15 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
 import { join, dirname, extname } from "path";
 import YAML from "yaml";
-const VALID_CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
+export const VALID_CATEGORIES = [
+    "ui",
+    "feature",
+    "bugfix",
+    "setup",
+    "development",
+    "testing",
+    "docs",
+];
 /**
  * Validates that a PRD structure is correct.
  * Returns validation result with parsed data if valid.
@@ -49,6 +57,11 @@ export function validatePrd(content) {
         if (entry.branch !== undefined && typeof entry.branch !== "string") {
             errors.push(`${prefix} 'branch' field must be a string if provided`);
         }
+        else if (typeof entry.branch === "string" &&
+            entry.branch !== "" &&
+            !/^[a-zA-Z0-9_\-./]+$/.test(entry.branch)) {
+            errors.push(`${prefix} 'branch' field contains invalid characters (only alphanumeric, hyphens, underscores, dots, and slashes allowed)`);
+        }
         // If no errors for this item, add to valid data
         if (errors.filter((e) => e.startsWith(prefix)).length === 0) {
             const validEntry = {
@@ -91,9 +104,7 @@ export function extractPassingItems(corrupted) {
     // Handle object with wrapped arrays
     if (typeof corrupted === "object") {
         const obj = corrupted;
-        // Common wrapper keys LLMs might use
-        const wrapperKeys = ["features", "items", "entries", "prd", "tasks", "requirements"];
-        for (const key of wrapperKeys) {
+        for (const key of PRD_WRAPPER_KEYS) {
             if (Array.isArray(obj[key])) {
                 for (const item of obj[key]) {
                     const extracted = extractFromItem(item);
@@ -234,8 +245,7 @@ export function attemptRecovery(corrupted) {
     // Strategy 1: Unwrap from common wrapper objects
     if (typeof corrupted === "object" && corrupted !== null && !Array.isArray(corrupted)) {
         const obj = corrupted;
-        const wrapperKeys = ["features", "items", "entries", "prd", "tasks", "requirements"];
-        for (const key of wrapperKeys) {
+        for (const key of PRD_WRAPPER_KEYS) {
             if (Array.isArray(obj[key])) {
                 const result = attemptArrayRecovery(obj[key]);
                 if (result)

package/dist/utils/responder-logger.d.ts

@@ -28,10 +28,7 @@ export declare function logResponderCall(entry: ResponderLogEntry): void;
  * Log a responder call to console (for debug mode).
  */
 export declare function logResponderCallToConsole(entry: ResponderLogEntry): void;
-/**
- * Create a log entry and optionally log to console.
- */
-export declare function createResponderLog(options: {
+export interface CreateResponderLogOptions {
     responderName?: string;
     responderType?: string;
     trigger?: string;
@@ -44,4 +41,8 @@ export declare function createResponderLog(options: {
     message: string;
     systemPrompt?: string;
     debug?: boolean;
-}): void;
+}
+/**
+ * Create a log entry and optionally log to console.
+ */
+export declare function createResponderLog(options: CreateResponderLogOptions): void;

package/dist/utils/responder-presets.d.ts

@@ -12,6 +12,7 @@ export interface ResponderPreset {
     command?: string;
     timeout?: number;
     maxLength?: number;
+    successPattern?: string;
 }
 /**
  * Bundle of presets for quick setup.

package/dist/utils/responder-presets.js

@@ -83,6 +83,8 @@ export function presetToResponderConfig(preset) {
         config.timeout = preset.timeout;
     if (preset.maxLength)
         config.maxLength = preset.maxLength;
+    if (preset.successPattern)
+        config.successPattern = preset.successPattern;
     return config;
 }
 /**

package/dist/utils/responder.js

@@ -109,10 +109,7 @@ export class ResponderMatcher {
                 // Extract args: everything after the trigger
                 const triggerIndex = match.index + match[0].indexOf(match[1]);
                 const afterTrigger = message.slice(triggerIndex + match[1].length);
-                const args = afterTrigger
-                    .replace(/^[:]\s*/, "")
-                    .replace(/^\s+/, "")
-                    .trim();
+                const args = this.extractArgsAfterTrigger(afterTrigger, 0);
                 return { name: responderName, responder, args };
             }
         }

package/docs/MCP.md

@@ -0,0 +1,192 @@
+# MCP Server
+
+Ralph includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes PRD management tools to any MCP-compatible client. This allows AI assistants like Claude to read, update, and track your PRD directly through tool calls.
+
+## Overview
+
+The MCP server runs over **stdio** transport and provides four tools:
+
+| Tool | Description |
+|------|-------------|
+| `ralph_prd_list` | List PRD entries with optional filters |
+| `ralph_prd_add` | Add a new PRD entry |
+| `ralph_prd_status` | Get completion status and breakdown |
+| `ralph_prd_toggle` | Toggle pass/fail status for entries |
+
+## Installation
+
+The MCP server is included with ralph. Install ralph globally or use npx:
+
+```bash
+npm install -g ralph-cli-sandboxed
+```
+
+The server binary is available as `ralph-mcp` after installation.
+
+## MCP Client Configuration
+
+### Claude Code
+
+Add the following to your project's `.mcp.json` file (or `~/.claude/mcp.json` for global access):
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "ralph-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If ralph is installed locally (not globally), use npx:
+
+```json
+{
+  "mcpServers": {
+    "ralph": {
+      "command": "npx",
+      "args": ["--package", "ralph-cli-sandboxed", "ralph-mcp"]
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP client that supports stdio transport can connect to the ralph MCP server. Point your client at the `ralph-mcp` binary with no arguments.
+
+## Available Tools
+
+### ralph_prd_list
+
+List PRD entries with optional category and status filters.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | enum | No | Filter by category: `ui`, `feature`, `bugfix`, `setup`, `development`, `testing`, `docs` |
+| `status` | enum | No | Filter by status: `all` (default), `passing`, `failing` |
+
+**Returns:** JSON array of entries, each containing:
+
+```json
+[
+  {
+    "category": "feature",
+    "description": "Add user authentication",
+    "steps": ["Create login form", "Implement JWT tokens"],
+    "passes": false,
+    "index": 1
+  }
+]
+```
+
+**Examples:**
+- List all entries: `ralph_prd_list({})`
+- List failing features: `ralph_prd_list({ category: "feature", status: "failing" })`
+- List passing entries: `ralph_prd_list({ status: "passing" })`
+
+### ralph_prd_add
+
+Add a new PRD entry with category, description, and verification steps.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | enum | Yes | Category: `ui`, `feature`, `bugfix`, `setup`, `development`, `testing`, `docs` |
+| `description` | string | Yes | Description of the requirement |
+| `steps` | string[] | Yes | Non-empty array of verification steps |
+| `branch` | string | No | Git branch associated with this entry |
+
+**Returns:** JSON with confirmation message and the added entry including its 1-based index.
+
+```json
+{
+  "message": "Added entry #3: \"Add dark mode support\"",
+  "entry": {
+    "category": "feature",
+    "description": "Add dark mode support",
+    "steps": ["Add theme toggle", "Implement dark CSS variables"],
+    "passes": false,
+    "index": 3
+  }
+}
+```
+
+### ralph_prd_status
+
+Get PRD completion status with counts, percentage, per-category breakdown, and remaining items. Takes no parameters.
+
+**Returns:**
+
+```json
+{
+  "passing": 5,
+  "total": 8,
+  "percentage": 63,
+  "categories": {
+    "feature": { "passing": 3, "total": 5 },
+    "setup": { "passing": 2, "total": 2 },
+    "docs": { "passing": 0, "total": 1 }
+  },
+  "remaining": [
+    { "index": 3, "category": "feature", "description": "Add search functionality" },
+    { "index": 6, "category": "feature", "description": "Add notifications" },
+    { "index": 8, "category": "docs", "description": "Write API documentation" }
+  ]
+}
+```
+
+### ralph_prd_toggle
+
+Toggle the completion status (`passes`) for one or more PRD entries by their 1-based index.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `indices` | number[] | Yes | 1-based indices of PRD entries to toggle |
+
+**Returns:** JSON with confirmation and list of toggled entries.
+
+```json
+{
+  "message": "Toggled 2 entry/entries",
+  "toggled": [
+    { "index": 1, "description": "Add login page", "passes": true },
+    { "index": 3, "description": "Add search", "passes": false }
+  ]
+}
+```
+
+Out-of-range indices return an error. Duplicate indices are deduplicated before toggling.
+
+## Example Conversations
+
+### Checking project progress
+
+> **User:** What's the status of our PRD?
+>
+> **Assistant:** *(calls `ralph_prd_status`)* Your PRD is 63% complete (5 of 8 tasks passing). You have 3 remaining items: search functionality, notifications, and API documentation.
+
+### Adding a new requirement
+
+> **User:** We need to add internationalization support.
+>
+> **Assistant:** *(calls `ralph_prd_add` with category "feature", description "Add internationalization (i18n) support", steps ["Install i18n library", "Extract user-facing strings", "Add language switcher"])* Done! Added as entry #9 in the feature category.
+
+### Marking work as complete
+
+> **User:** I've finished the search functionality (item 3).
+>
+> **Assistant:** *(calls `ralph_prd_toggle` with indices [3])* Toggled entry #3 "Add search functionality" to passing.
+
+### Filtering the PRD
+
+> **User:** Show me all the incomplete feature tasks.
+>
+> **Assistant:** *(calls `ralph_prd_list` with category "feature", status "failing")* You have 2 incomplete feature tasks: notifications (#6) and i18n support (#9).

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {
-    "ralph": "dist/index.js"
+    "ralph": "dist/index.js",
+    "ralph-mcp": "dist/mcp-server.js"
   },
   "main": "./dist/index.js",
   "files": [
@@ -13,10 +14,10 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && npm run copy-config",
+    "build": "npx tsc && npm run copy-config",
     "copy-config": "mkdir -p dist/config && cp src/config/*.json dist/config/",
     "dev": "npx tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "npx tsc --noEmit",
     "lint": "oxlint src/",
     "format": "oxfmt src/",
     "format:check": "oxfmt --check src/",
@@ -26,8 +27,8 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.80.0",
-    "@inkjs/ui": "^2.0.0",
+    "@anthropic-ai/sdk": "^0.82.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@slack/bolt": "^4.6.0",
     "@slack/web-api": "^7.15.0",
     "discord.js": "^14.16.0",
@@ -35,8 +36,8 @@
     "ink-text-input": "^6.0.0",
     "openai": "^6.33.0",
     "react": "^19.2.4",
-    "readline": "^1.3.0",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",