ralph-cli-sandboxed 0.2.9 → 0.3.0

package/dist/index.js

@@ -10,6 +10,11 @@ import { prd, prdAdd, prdList, prdStatus, prdToggle, prdClean, parseListArgs } f
 import { docker } from "./commands/docker.js";
 import { prompt } from "./commands/prompt.js";
 import { fixPrd } from "./commands/fix-prd.js";
+import { daemon } from "./commands/daemon.js";
+import { notify } from "./commands/notify.js";
+import { chat } from "./commands/chat.js";
+import { listen } from "./commands/listen.js";
+import { config } from "./commands/config.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 function getPackageInfo() {
@@ -25,6 +30,11 @@ const commands = {
     prd,
     prompt,
     docker,
+    daemon,
+    notify,
+    chat,
+    listen,
+    config,
     "fix-prd": (args) => fixPrd(args),
     // Top-level PRD commands (shortcuts)
     add: () => prdAdd(),

package/dist/providers/telegram.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Telegram chat client implementation.
+ * Uses the Telegram Bot API with long polling to receive messages.
+ */
+import { ChatClient, ChatCommandHandler, ChatMessageHandler, TelegramSettings } from "../utils/chat-client.js";
+export declare class TelegramChatClient implements ChatClient {
+    readonly provider: "telegram";
+    private settings;
+    private connected;
+    private polling;
+    private lastUpdateId;
+    private pollingTimeout;
+    private debug;
+    constructor(settings: TelegramSettings, debug?: boolean);
+    /**
+     * Make a request to the Telegram Bot API.
+     */
+    private apiRequest;
+    /**
+     * Check if a chat ID is allowed.
+     */
+    private isChatAllowed;
+    /**
+     * Start long polling for updates.
+     */
+    private poll;
+    connect(onCommand: ChatCommandHandler, onMessage?: ChatMessageHandler): Promise<void>;
+    sendMessage(chatId: string, text: string): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+}
+/**
+ * Create a Telegram chat client from settings.
+ */
+export declare function createTelegramClient(settings: TelegramSettings, debug?: boolean): ChatClient;

package/dist/providers/telegram.js

@@ -0,0 +1,190 @@
+/**
+ * Telegram chat client implementation.
+ * Uses the Telegram Bot API with long polling to receive messages.
+ */
+import https from "https";
+import { parseCommand, } from "../utils/chat-client.js";
+export class TelegramChatClient {
+    provider = "telegram";
+    settings;
+    connected = false;
+    polling = false;
+    lastUpdateId = 0;
+    pollingTimeout = null;
+    debug;
+    constructor(settings, debug = false) {
+        this.settings = settings;
+        this.debug = debug;
+    }
+    /**
+     * Make a request to the Telegram Bot API.
+     */
+    async apiRequest(method, body) {
+        return new Promise((resolve, reject) => {
+            const url = `https://api.telegram.org/bot${this.settings.botToken}/${method}`;
+            const options = {
+                method: body ? "POST" : "GET",
+                headers: body
+                    ? {
+                        "Content-Type": "application/json",
+                    }
+                    : undefined,
+            };
+            const req = https.request(url, options, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk;
+                });
+                res.on("end", () => {
+                    try {
+                        const response = JSON.parse(data);
+                        if (response.ok && response.result !== undefined) {
+                            resolve(response.result);
+                        }
+                        else {
+                            reject(new Error(`Telegram API error: ${response.description || "Unknown error"} (code: ${response.error_code})`));
+                        }
+                    }
+                    catch (err) {
+                        reject(new Error(`Failed to parse Telegram response: ${data}`));
+                    }
+                });
+            });
+            req.on("error", (err) => {
+                reject(new Error(`Telegram request failed: ${err.message}`));
+            });
+            if (body) {
+                req.write(JSON.stringify(body));
+            }
+            req.end();
+        });
+    }
+    /**
+     * Check if a chat ID is allowed.
+     */
+    isChatAllowed(chatId) {
+        // If no allowed chat IDs specified, allow all
+        if (!this.settings.allowedChatIds || this.settings.allowedChatIds.length === 0) {
+            return true;
+        }
+        return this.settings.allowedChatIds.includes(chatId);
+    }
+    /**
+     * Start long polling for updates.
+     */
+    async poll(onCommand, onMessage) {
+        if (!this.polling)
+            return;
+        try {
+            const updates = await this.apiRequest("getUpdates", {
+                offset: this.lastUpdateId + 1,
+                timeout: 30, // Long polling timeout in seconds
+            });
+            for (const update of updates) {
+                this.lastUpdateId = update.update_id;
+                if (update.message?.text) {
+                    const chatId = String(update.message.chat.id);
+                    // Check if chat is allowed
+                    if (!this.isChatAllowed(chatId)) {
+                        if (this.debug) {
+                            console.log(`[telegram] Ignoring message from unauthorized chat: ${chatId}`);
+                        }
+                        continue;
+                    }
+                    const message = {
+                        text: update.message.text,
+                        chatId,
+                        senderId: update.message.from ? String(update.message.from.id) : undefined,
+                        senderName: update.message.from
+                            ? [update.message.from.first_name, update.message.from.last_name].filter(Boolean).join(" ")
+                            : undefined,
+                        timestamp: new Date(update.message.date * 1000),
+                        raw: update,
+                    };
+                    // Call raw message handler if provided
+                    if (onMessage) {
+                        try {
+                            await onMessage(message);
+                        }
+                        catch (err) {
+                            if (this.debug) {
+                                console.error(`[telegram] Message handler error: ${err}`);
+                            }
+                        }
+                    }
+                    // Try to parse as a command
+                    const command = parseCommand(message.text, message);
+                    if (command) {
+                        try {
+                            await onCommand(command);
+                        }
+                        catch (err) {
+                            if (this.debug) {
+                                console.error(`[telegram] Command handler error: ${err}`);
+                            }
+                            // Send error message to chat
+                            await this.sendMessage(chatId, `Error executing command: ${err instanceof Error ? err.message : "Unknown error"}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (this.debug) {
+                console.error(`[telegram] Poll error: ${err}`);
+            }
+            // Wait a bit before retrying on error
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+        }
+        // Schedule next poll
+        if (this.polling) {
+            this.pollingTimeout = setTimeout(() => this.poll(onCommand, onMessage), 100);
+        }
+    }
+    async connect(onCommand, onMessage) {
+        if (this.connected) {
+            throw new Error("Already connected");
+        }
+        // Verify bot token by calling getMe
+        try {
+            const me = await this.apiRequest("getMe");
+            if (this.debug) {
+                console.log(`[telegram] Connected as @${me.username || me.first_name} (ID: ${me.id})`);
+            }
+        }
+        catch (err) {
+            throw new Error(`Failed to connect to Telegram: ${err instanceof Error ? err.message : "Unknown error"}`);
+        }
+        this.connected = true;
+        this.polling = true;
+        // Start polling
+        this.poll(onCommand, onMessage);
+    }
+    async sendMessage(chatId, text) {
+        if (!this.connected) {
+            throw new Error("Not connected");
+        }
+        await this.apiRequest("sendMessage", {
+            chat_id: chatId,
+            text,
+            parse_mode: "HTML",
+        });
+    }
+    async disconnect() {
+        this.polling = false;
+        this.connected = false;
+        if (this.pollingTimeout) {
+            clearTimeout(this.pollingTimeout);
+            this.pollingTimeout = null;
+        }
+    }
+    isConnected() {
+        return this.connected;
+    }
+}
+/**
+ * Create a Telegram chat client from settings.
+ */
+export function createTelegramClient(settings, debug = false) {
+    return new TelegramChatClient(settings, debug);
+}

package/dist/utils/chat-client.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Chat client interface for communicating with external chat services.
+ * This provides a unified interface for different chat providers (Telegram, Discord, Slack, etc.)
+ */
+export interface ChatMessage {
+    /** The text content of the message */
+    text: string;
+    /** The chat/channel ID the message was sent in */
+    chatId: string;
+    /** The sender's ID (user or bot) */
+    senderId?: string;
+    /** The sender's display name */
+    senderName?: string;
+    /** Timestamp when the message was received */
+    timestamp: Date;
+    /** Raw message data from the provider */
+    raw?: unknown;
+}
+export interface ChatCommand {
+    /** The project ID extracted from the message (e.g., "abc" from "abc run") */
+    projectId: string;
+    /** The command name (e.g., "run", "status", "add", "exec") */
+    command: string;
+    /** Arguments passed to the command */
+    args: string[];
+    /** The original message */
+    message: ChatMessage;
+}
+export interface ChatClientConfig {
+    /** Whether the chat client is enabled */
+    enabled: boolean;
+    /** The chat provider type (e.g., "telegram") */
+    provider: "telegram";
+    /** Provider-specific settings */
+    settings: TelegramSettings;
+}
+export interface TelegramSettings {
+    /** Telegram Bot API token */
+    botToken: string;
+    /** Allowed chat IDs (for security - only respond in these chats) */
+    allowedChatIds?: string[];
+}
+export type ChatProvider = "telegram";
+/**
+ * Callback for handling incoming chat commands.
+ */
+export type ChatCommandHandler = (command: ChatCommand) => Promise<void>;
+/**
+ * Callback for handling raw messages (for custom processing).
+ */
+export type ChatMessageHandler = (message: ChatMessage) => Promise<void>;
+/**
+ * Abstract interface for chat clients.
+ * Implementations should handle provider-specific API calls.
+ */
+export interface ChatClient {
+    /** The provider type */
+    readonly provider: ChatProvider;
+    /**
+     * Connect to the chat service and start listening for messages.
+     * @param onCommand Callback for parsed commands (e.g., "abc run")
+     * @param onMessage Optional callback for all messages
+     */
+    connect(onCommand: ChatCommandHandler, onMessage?: ChatMessageHandler): Promise<void>;
+    /**
+     * Send a text message to a specific chat.
+     * @param chatId The chat ID to send to
+     * @param text The message text
+     */
+    sendMessage(chatId: string, text: string): Promise<void>;
+    /**
+     * Disconnect from the chat service.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if the client is currently connected.
+     */
+    isConnected(): boolean;
+}
+/**
+ * Project registration for chat commands.
+ * Maps project IDs to their configurations.
+ */
+export interface ChatProjectRegistration {
+    /** Short project ID (3-digit identifier) */
+    projectId: string;
+    /** Full project name */
+    projectName: string;
+    /** Path to the project's .ralph directory */
+    ralphDir: string;
+    /** The chat ID where this project was registered */
+    chatId: string;
+    /** Timestamp when registered */
+    registeredAt: Date;
+}
+/**
+ * Generate a short project ID (3 alphanumeric characters).
+ * Used to identify projects in chat commands.
+ */
+export declare function generateProjectId(): string;
+/**
+ * Parse a chat message to extract a command.
+ *
+ * Supports slash commands (preferred):
+ * - "/run" -> { command: "run", args: [] }
+ * - "/status" -> { command: "status", args: [] }
+ * - "/exec npm test" -> { command: "exec", args: ["npm", "test"] }
+ * - "/add Fix the login bug" -> { command: "add", args: ["Fix", "the", "login", "bug"] }
+ */
+export declare function parseCommand(text: string, message: ChatMessage): ChatCommand | null;
+/**
+ * Format a status message for a project.
+ */
+export declare function formatStatusMessage(projectName: string, status: "running" | "idle" | "completed" | "error", details?: string): string;

package/dist/utils/chat-client.js

@@ -0,0 +1,76 @@
+/**
+ * Chat client interface for communicating with external chat services.
+ * This provides a unified interface for different chat providers (Telegram, Discord, Slack, etc.)
+ */
+/**
+ * Generate a short project ID (3 alphanumeric characters).
+ * Used to identify projects in chat commands.
+ */
+export function generateProjectId() {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let id = "";
+    for (let i = 0; i < 3; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return id;
+}
+/**
+ * Parse a chat message to extract a command.
+ *
+ * Supports slash commands (preferred):
+ * - "/run" -> { command: "run", args: [] }
+ * - "/status" -> { command: "status", args: [] }
+ * - "/exec npm test" -> { command: "exec", args: ["npm", "test"] }
+ * - "/add Fix the login bug" -> { command: "add", args: ["Fix", "the", "login", "bug"] }
+ */
+export function parseCommand(text, message) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    // Valid commands
+    const validCommands = ["run", "status", "add", "exec", "stop", "help", "start", "action"];
+    // Check for slash command format: /command [args...]
+    if (trimmed.startsWith("/")) {
+        const parts = trimmed.slice(1).split(/\s+/);
+        if (parts.length === 0)
+            return null;
+        const [command, ...args] = parts;
+        const cmd = command.toLowerCase();
+        // Handle Telegram's /start command specially
+        if (cmd === "start") {
+            return {
+                projectId: "",
+                command: "help",
+                args: [],
+                message,
+            };
+        }
+        if (!validCommands.includes(cmd)) {
+            return null;
+        }
+        return {
+            projectId: "",
+            command: cmd,
+            args,
+            message,
+        };
+    }
+    return null;
+}
+/**
+ * Format a status message for a project.
+ */
+export function formatStatusMessage(projectName, status, details) {
+    const statusIcons = {
+        running: "[...]",
+        idle: "[_]",
+        completed: "[OK]",
+        error: "[X]",
+    };
+    const icon = statusIcons[status] || "[?]";
+    let message = `${icon} ${projectName}: ${status}`;
+    if (details) {
+        message += `\n${details}`;
+    }
+    return message;
+}

package/dist/utils/config.d.ts

@@ -27,12 +27,55 @@ export interface AsciinemaConfig {
     outputDir?: string;
     streamJson?: StreamJsonConfig;
 }
+export interface DaemonActionConfig {
+    command: string;
+    description?: string;
+}
+export interface NtfyNotificationConfig {
+    topic: string;
+    server?: string;
+}
+export interface NotificationsConfig {
+    provider: "ntfy" | "command";
+    ntfy?: NtfyNotificationConfig;
+    command?: string;
+}
+/**
+ * Event types that can trigger daemon calls.
+ * - task_complete: Fired after each task is completed
+ * - ralph_complete: Fired when ralph finishes all work (PRD complete)
+ * - iteration_complete: Fired after each iteration
+ * - error: Fired when an error occurs
+ */
+export type DaemonEventType = "task_complete" | "ralph_complete" | "iteration_complete" | "error";
+export interface DaemonEventConfig {
+    action: string;
+    args?: string[];
+    message?: string;
+}
+export interface DaemonConfig {
+    enabled?: boolean;
+    socketPath?: string;
+    actions?: Record<string, DaemonActionConfig>;
+    events?: Partial<Record<DaemonEventType, DaemonEventConfig[]>>;
+}
+export interface TelegramChatSettings {
+    enabled?: boolean;
+    botToken: string;
+    allowedChatIds?: string[];
+}
+export interface ChatConfig {
+    enabled?: boolean;
+    provider?: "telegram";
+    telegram?: TelegramChatSettings;
+}
 export interface RalphConfig {
     language: string;
     checkCommand: string;
     testCommand: string;
     imageName?: string;
     notifyCommand?: string;
+    notifications?: NotificationsConfig;
     technologies?: string[];
     javaVersion?: number;
     cli?: CliConfig;
@@ -55,11 +98,15 @@ export interface RalphConfig {
         firewall?: {
             allowedDomains?: string[];
         };
+        autoStart?: boolean;
+        restartCount?: number;
     };
     claude?: {
         mcpServers?: Record<string, McpServerConfig>;
         skills?: SkillConfig[];
     };
+    daemon?: DaemonConfig;
+    chat?: ChatConfig;
 }
 export declare const DEFAULT_CLI_CONFIG: CliConfig;
 export declare function getCliConfig(config: RalphConfig): CliConfig;

package/dist/utils/daemon-client.d.ts

@@ -0,0 +1,36 @@
+export interface DaemonRequest {
+    action: string;
+    args?: string[];
+}
+export interface DaemonResponse {
+    success: boolean;
+    message?: string;
+    output?: string;
+    error?: string;
+}
+/**
+ * Get the appropriate messages path based on whether we're in a container or on host.
+ */
+export declare function getDaemonSocketPath(): string;
+/**
+ * Check if the daemon is available (messages file can be written).
+ */
+export declare function isDaemonAvailable(): boolean;
+/**
+ * Send a request to the daemon and get a response.
+ *
+ * @param action The action to execute
+ * @param args Optional arguments to pass to the action
+ * @param timeout Timeout in milliseconds (default: 10000)
+ */
+export declare function sendDaemonRequest(action: string, args?: string[], timeout?: number): Promise<DaemonResponse>;
+/**
+ * Send a ping to check if daemon is responsive.
+ */
+export declare function pingDaemon(): Promise<boolean>;
+/**
+ * Send a notification through the daemon.
+ *
+ * @param message The notification message
+ */
+export declare function sendDaemonNotification(message: string): Promise<DaemonResponse>;

package/dist/utils/daemon-client.js

@@ -0,0 +1,70 @@
+import { existsSync } from "fs";
+import { isRunningInContainer } from "./config.js";
+import { getMessagesPath, sendMessage, waitForResponse, } from "./message-queue.js";
+/**
+ * Get the appropriate messages path based on whether we're in a container or on host.
+ */
+export function getDaemonSocketPath() {
+    // For backwards compatibility, return the messages path
+    return getMessagesPath(isRunningInContainer());
+}
+/**
+ * Check if the daemon is available (messages file can be written).
+ */
+export function isDaemonAvailable() {
+    const messagesPath = getMessagesPath(isRunningInContainer());
+    // In container, check if the .ralph directory is mounted
+    if (isRunningInContainer()) {
+        return existsSync("/workspace/.ralph");
+    }
+    // On host, check if .ralph directory exists
+    return existsSync(messagesPath.replace("/messages.json", ""));
+}
+/**
+ * Send a request to the daemon and get a response.
+ *
+ * @param action The action to execute
+ * @param args Optional arguments to pass to the action
+ * @param timeout Timeout in milliseconds (default: 10000)
+ */
+export async function sendDaemonRequest(action, args, timeout = 10000) {
+    const messagesPath = getMessagesPath(isRunningInContainer());
+    try {
+        // Send message via file queue
+        const messageId = sendMessage(messagesPath, "sandbox", action, args);
+        // Wait for response
+        const response = await waitForResponse(messagesPath, messageId, timeout);
+        if (!response) {
+            return {
+                success: false,
+                error: `Request timed out after ${timeout}ms. Make sure the daemon is running on the host.`,
+            };
+        }
+        return {
+            success: response.success,
+            output: response.output,
+            error: response.error,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `Failed to send message: ${err instanceof Error ? err.message : "unknown error"}`,
+        };
+    }
+}
+/**
+ * Send a ping to check if daemon is responsive.
+ */
+export async function pingDaemon() {
+    const response = await sendDaemonRequest("ping", [], 5000);
+    return response.success && response.output === "pong";
+}
+/**
+ * Send a notification through the daemon.
+ *
+ * @param message The notification message
+ */
+export async function sendDaemonNotification(message) {
+    return sendDaemonRequest("notify", [message]);
+}

package/dist/utils/message-queue.d.ts

@@ -0,0 +1,58 @@
+export interface Message {
+    id: string;
+    from: "sandbox" | "host";
+    action: string;
+    args?: string[];
+    timestamp: number;
+    status: "pending" | "done";
+    response?: {
+        success: boolean;
+        output?: string;
+        error?: string;
+    };
+}
+/**
+ * Get the path to the messages file.
+ * Uses /workspace/.ralph in container, .ralph in host.
+ */
+export declare function getMessagesPath(inContainer: boolean): string;
+/**
+ * Read all messages from the queue.
+ */
+export declare function readMessages(messagesPath: string): Message[];
+/**
+ * Write messages to the queue (atomic write).
+ */
+export declare function writeMessages(messagesPath: string, messages: Message[]): void;
+/**
+ * Initialize the messages file with a daemon_started message.
+ * Called when the daemon starts.
+ */
+export declare function initializeMessages(messagesPath: string): void;
+/**
+ * Add a message to the queue.
+ * Returns the message ID.
+ */
+export declare function sendMessage(messagesPath: string, from: "sandbox" | "host", action: string, args?: string[]): string;
+export type MessageResponse = {
+    success: boolean;
+    output?: string;
+    error?: string;
+};
+/**
+ * Wait for a response to a message.
+ * Returns the response or null if timeout.
+ */
+export declare function waitForResponse(messagesPath: string, messageId: string, timeout?: number, pollInterval?: number): Promise<MessageResponse | null>;
+/**
+ * Get pending messages for a recipient.
+ */
+export declare function getPendingMessages(messagesPath: string, from: "sandbox" | "host"): Message[];
+/**
+ * Mark a message as done with a response.
+ */
+export declare function respondToMessage(messagesPath: string, messageId: string, response: MessageResponse): boolean;
+/**
+ * Clean up old messages (older than maxAge milliseconds).
+ */
+export declare function cleanupOldMessages(messagesPath: string, maxAge?: number): number;