ralph-cli-sandboxed 0.4.1 → 0.4.2

package/dist/responders/cli-responder.js

@@ -0,0 +1,298 @@
+/**
+ * CLI Responder - Executes configured CLI commands with user messages.
+ * Useful for integrating with aider, custom scripts, or other AI CLIs.
+ */
+import { spawn } from "child_process";
+import { truncateResponse } from "./llm-responder.js";
+/**
+ * Default timeout for CLI execution (2 minutes).
+ */
+const DEFAULT_TIMEOUT = 120000;
+/**
+ * Default max length for chat responses (characters).
+ */
+const DEFAULT_MAX_LENGTH = 2000;
+/**
+ * Interval for sending progress updates (milliseconds).
+ */
+const PROGRESS_INTERVAL = 5000;
+/**
+ * Replaces {{message}} placeholder in command string with the actual message.
+ * Escapes the message to prevent shell injection.
+ */
+export function replaceMessagePlaceholder(command, message) {
+    // Escape single quotes in the message for safe shell interpolation
+    const escapedMessage = message.replace(/'/g, "'\\''");
+    return command.replace(/\{\{message\}\}/g, escapedMessage);
+}
+/**
+ * Parses a command string into command and arguments.
+ * Handles quoted strings and basic shell syntax.
+ */
+export function parseCommand(commandString) {
+    const tokens = [];
+    let current = "";
+    let inSingleQuote = false;
+    let inDoubleQuote = false;
+    let escapeNext = false;
+    for (let i = 0; i < commandString.length; i++) {
+        const char = commandString[i];
+        if (escapeNext) {
+            current += char;
+            escapeNext = false;
+            continue;
+        }
+        if (char === "\\") {
+            escapeNext = true;
+            continue;
+        }
+        if (char === "'" && !inDoubleQuote) {
+            inSingleQuote = !inSingleQuote;
+            continue;
+        }
+        if (char === '"' && !inSingleQuote) {
+            inDoubleQuote = !inDoubleQuote;
+            continue;
+        }
+        if (char === " " && !inSingleQuote && !inDoubleQuote) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+    const [command, ...args] = tokens;
+    return { command: command || "", args };
+}
+/**
+ * Executes a CLI command with the given message.
+ *
+ * The command string can include {{message}} placeholder which will be replaced
+ * with the user's message. If no placeholder is present, the message is appended
+ * as an argument.
+ *
+ * @param message The user message to include in the command
+ * @param responderConfig The responder configuration
+ * @param options Optional execution options
+ * @returns The responder result with response or error
+ */
+export async function executeCLIResponder(message, responderConfig, options) {
+    const timeout = options?.timeout ?? responderConfig.timeout ?? DEFAULT_TIMEOUT;
+    const maxLength = options?.maxLength ?? responderConfig.maxLength ?? DEFAULT_MAX_LENGTH;
+    const cwd = options?.cwd ?? process.cwd();
+    const onProgress = options?.onProgress;
+    const additionalEnv = options?.env ?? {};
+    // Get command from config
+    const commandTemplate = responderConfig.command;
+    if (!commandTemplate) {
+        return {
+            success: false,
+            response: "",
+            error: "CLI responder requires a 'command' field in configuration",
+        };
+    }
+    // Replace {{message}} placeholder or append message as argument
+    let commandString;
+    if (commandTemplate.includes("{{message}}")) {
+        commandString = replaceMessagePlaceholder(commandTemplate, message);
+    }
+    else {
+        // Append message as a quoted argument
+        const escapedMessage = message.replace(/'/g, "'\\''");
+        commandString = `${commandTemplate} '${escapedMessage}'`;
+    }
+    // Parse the command string
+    const { command, args } = parseCommand(commandString);
+    if (!command) {
+        return {
+            success: false,
+            response: "",
+            error: "Failed to parse command from configuration",
+        };
+    }
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let killed = false;
+        let lastProgressSent = 0;
+        let progressTimer = null;
+        // Spawn the process
+        let proc;
+        try {
+            proc = spawn(command, args, {
+                cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: false,
+                env: { ...process.env, ...additionalEnv },
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            resolve({
+                success: false,
+                response: "",
+                error: `Failed to spawn command "${command}": ${error}`,
+            });
+            return;
+        }
+        // Handle timeout
+        const timeoutTimer = setTimeout(() => {
+            killed = true;
+            proc.kill("SIGTERM");
+            // Give it a moment to terminate gracefully, then force kill
+            setTimeout(() => {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    // Already dead
+                }
+            }, 2000);
+            if (progressTimer) {
+                clearInterval(progressTimer);
+            }
+            resolve({
+                success: false,
+                response: stdout,
+                error: `Command timed out after ${Math.round(timeout / 1000)} seconds`,
+            });
+        }, timeout);
+        // Set up progress updates
+        if (onProgress) {
+            progressTimer = setInterval(() => {
+                const now = Date.now();
+                if (now - lastProgressSent >= PROGRESS_INTERVAL && stdout.length > 0) {
+                    // Send a progress indicator
+                    const lines = stdout.split("\n");
+                    const lastLine = lines[lines.length - 1] || lines[lines.length - 2] || "";
+                    const truncatedLine = lastLine.length > 100 ? lastLine.substring(0, 100) + "..." : lastLine;
+                    onProgress(`⏳ Running... ${truncatedLine}`);
+                    lastProgressSent = now;
+                }
+            }, PROGRESS_INTERVAL);
+        }
+        // Capture stdout
+        proc.stdout?.on("data", (data) => {
+            stdout += data.toString();
+        });
+        // Capture stderr
+        proc.stderr?.on("data", (data) => {
+            stderr += data.toString();
+        });
+        // Handle process completion
+        proc.on("close", (code) => {
+            if (killed)
+                return;
+            clearTimeout(timeoutTimer);
+            if (progressTimer) {
+                clearInterval(progressTimer);
+            }
+            if (code === 0 || code === null) {
+                // Success - format and truncate output
+                const output = formatCLIOutput(stdout, stderr);
+                const { text, truncated, originalLength } = truncateResponse(output, maxLength);
+                resolve({
+                    success: true,
+                    response: text,
+                    truncated,
+                    originalLength: truncated ? originalLength : undefined,
+                });
+            }
+            else {
+                // Failure - include stderr in error message
+                const errorMsg = stderr.trim() || `Command exited with code ${code}`;
+                const output = formatCLIOutput(stdout, "");
+                const { text, truncated, originalLength } = truncateResponse(output, maxLength);
+                resolve({
+                    success: false,
+                    response: text,
+                    error: errorMsg,
+                    truncated,
+                    originalLength: truncated ? originalLength : undefined,
+                });
+            }
+        });
+        // Handle spawn errors
+        proc.on("error", (err) => {
+            if (killed)
+                return;
+            clearTimeout(timeoutTimer);
+            if (progressTimer) {
+                clearInterval(progressTimer);
+            }
+            resolve({
+                success: false,
+                response: "",
+                error: `Command error: ${err.message}`,
+            });
+        });
+    });
+}
+/**
+ * Formats CLI output for chat display.
+ * Cleans up ANSI codes, excessive whitespace, and combines stdout/stderr.
+ */
+function formatCLIOutput(stdout, stderr) {
+    // Combine stdout and stderr
+    let output = stdout;
+    if (stderr.trim()) {
+        output = output.trim() + "\n\n[stderr]\n" + stderr.trim();
+    }
+    // Remove ANSI escape codes
+    let cleaned = output.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+    // Remove carriage returns (used for progress overwriting)
+    cleaned = cleaned.replace(/\r/g, "");
+    // Collapse multiple blank lines into one
+    cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+    // Trim leading/trailing whitespace
+    cleaned = cleaned.trim();
+    // If output is empty, provide a default message
+    if (!cleaned) {
+        return "(Command completed with no output)";
+    }
+    return cleaned;
+}
+/**
+ * Creates a reusable CLI responder function.
+ * This is useful for handling multiple messages with the same configuration.
+ *
+ * @param responderConfig The responder configuration
+ * @returns A function that executes the responder with a message
+ */
+export function createCLIResponder(responderConfig) {
+    return async (message, options) => {
+        return executeCLIResponder(message, responderConfig, options);
+    };
+}
+/**
+ * Validates that a responder configuration is valid for CLI execution.
+ *
+ * @param responderConfig The responder configuration to validate
+ * @returns An error message if invalid, or null if valid
+ */
+export function validateCLIResponder(responderConfig) {
+    if (responderConfig.type !== "cli") {
+        return `Responder type is "${responderConfig.type}", expected "cli"`;
+    }
+    if (!responderConfig.command) {
+        return "CLI responder requires a 'command' field";
+    }
+    if (typeof responderConfig.command !== "string") {
+        return "CLI responder 'command' field must be a string";
+    }
+    // Check that timeout is reasonable if specified
+    if (responderConfig.timeout !== undefined) {
+        if (responderConfig.timeout < 1000) {
+            return `Timeout ${responderConfig.timeout}ms is too short (minimum: 1000ms)`;
+        }
+        if (responderConfig.timeout > 600000) {
+            return `Timeout ${responderConfig.timeout}ms is too long (maximum: 600000ms / 10 minutes)`;
+        }
+    }
+    return null;
+}

package/dist/responders/llm-responder.d.ts

@@ -0,0 +1,135 @@
+/**
+ * LLM Responder - Sends messages to LLM providers and returns responses.
+ * Used by chat clients to respond to messages matched by the responder matcher.
+ */
+import { ResponderConfig, RalphConfig } from "../utils/config.js";
+/**
+ * Result of executing a responder.
+ */
+export interface ResponderResult {
+    /** Whether the responder executed successfully */
+    success: boolean;
+    /** The response text (may be truncated) */
+    response: string;
+    /** Error message if success is false */
+    error?: string;
+    /** Whether the response was truncated */
+    truncated?: boolean;
+    /** Original response length before truncation */
+    originalLength?: number;
+}
+/**
+ * A message in conversation history.
+ */
+export interface ConversationMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/**
+ * Options for executing an LLM responder.
+ */
+export interface LLMResponderOptions {
+    /** Override the project name for {{project}} placeholder */
+    projectName?: string;
+    /** Override default max tokens */
+    maxTokens?: number;
+    /** Override default temperature */
+    temperature?: number;
+    /** Responder name for logging */
+    responderName?: string;
+    /** Responder trigger for logging */
+    trigger?: string;
+    /** Thread context length for logging */
+    threadContextLength?: number;
+    /** Enable debug logging to console */
+    debug?: boolean;
+    /** Previous conversation messages for multi-turn chat */
+    conversationHistory?: ConversationMessage[];
+}
+/**
+ * Replaces {{project}} placeholder in system prompt with actual project name.
+ */
+export declare function applyProjectPlaceholder(systemPrompt: string, projectName: string): string;
+/**
+ * Gets the project name from the current working directory.
+ */
+export declare function getProjectName(): string;
+/**
+ * Result of processing a git diff request.
+ */
+export interface GitDiffResult {
+    message: string;
+    diffIncluded: boolean;
+    gitCommand?: string;
+    diffLength?: number;
+}
+/**
+ * Detects if the message contains a git diff request and fetches the diff.
+ * Returns the message with diff content prepended, or the original message if no diff requested.
+ */
+export declare function processGitDiffRequest(message: string): GitDiffResult;
+/**
+ * Result of detecting and reading files from a message.
+ */
+export interface FileDetectionResult {
+    /** Files that were found and read */
+    filesRead: Array<{
+        path: string;
+        content: string;
+        lineNumber?: number;
+        truncated: boolean;
+    }>;
+    /** Files that were mentioned but not found */
+    filesNotFound: string[];
+    /** Total content length of all files */
+    totalLength: number;
+}
+/**
+ * Detects file paths in a message and reads their contents.
+ * Supports formats like:
+ *   - src/utils/config.ts
+ *   - src/utils/config.ts:42 (with line number)
+ *   - ./relative/path.js
+ *   - package.json
+ */
+export declare function detectAndReadFiles(message: string): FileDetectionResult;
+/**
+ * Formats detected files as context to prepend to the user message.
+ */
+export declare function formatFileContext(fileResult: FileDetectionResult): string;
+/**
+ * Truncates a response to the specified max length.
+ * Adds a truncation indicator if the response was shortened.
+ */
+export declare function truncateResponse(response: string, maxLength: number): {
+    text: string;
+    truncated: boolean;
+    originalLength: number;
+};
+/**
+ * Executes an LLM responder with the given message.
+ *
+ * @param message The user message to send to the LLM
+ * @param responderConfig The responder configuration
+ * @param config Optional Ralph config (loaded automatically if not provided)
+ * @param options Optional execution options
+ * @returns The responder result with response or error
+ */
+export declare function executeLLMResponder(message: string, responderConfig: ResponderConfig, config?: RalphConfig, options?: LLMResponderOptions): Promise<ResponderResult>;
+/**
+ * Creates a reusable LLM responder function with pre-loaded configuration.
+ * This is useful for handling multiple messages without reloading config each time.
+ *
+ * @param responderConfig The responder configuration
+ * @param config The Ralph configuration
+ * @returns A function that executes the responder with a message
+ */
+export declare function createLLMResponder(responderConfig: ResponderConfig, config: RalphConfig): (message: string, options?: LLMResponderOptions) => Promise<ResponderResult>;
+/**
+ * Validates that a responder configuration is valid for LLM execution.
+ *
+ * @param responderConfig The responder configuration to validate
+ * @param config The Ralph configuration for looking up providers
+ * @returns An error message if invalid, or null if valid
+ */
+export declare function validateLLMResponder(responderConfig: ResponderConfig, config: RalphConfig): string | null;