@locusai/locus-telegram 0.21.6

package/dist/commands/locus.js

@@ -0,0 +1,169 @@
+/**
+ * Locus CLI command passthrough — maps every Telegram command to
+ * the corresponding `locus` CLI invocation via `@locusai/sdk`.
+ *
+ * Long-running commands stream output by editing the Telegram message
+ * in place at regular intervals.
+ */
+import { invokeLocusStream } from "@locusai/sdk";
+import { formatCommandResult, formatStreamingMessage, } from "../ui/format.js";
+import { planKeyboard, reviewKeyboard, runCompleteKeyboard, statusKeyboard, } from "../ui/keyboards.js";
+import { reviewStartedMessage, runStartedMessage, } from "../ui/messages.js";
+// ─── Command Map ────────────────────────────────────────────────────────────
+/** Maps Telegram command names to locus CLI arguments. */
+const COMMAND_MAP = {
+    run: ["run"],
+    status: ["status"],
+    issues: ["issue", "list"],
+    issue: ["issue", "show"],
+    sprint: ["sprint"],
+    plan: ["plan"],
+    review: ["review"],
+    iterate: ["iterate"],
+    discuss: ["discuss"],
+    exec: ["exec"],
+    logs: ["logs"],
+    config: ["config"],
+    artifacts: ["artifacts"],
+};
+/** Commands that produce long-running streaming output. */
+const STREAMING_COMMANDS = new Set([
+    "run",
+    "plan",
+    "review",
+    "iterate",
+    "discuss",
+    "exec",
+]);
+/** Minimum interval between message edits (ms) to avoid Telegram rate limits. */
+const EDIT_INTERVAL = 2000;
+// ─── Handlers ───────────────────────────────────────────────────────────────
+/**
+ * Execute a locus CLI command, streaming output to the Telegram chat.
+ */
+export async function handleLocusCommand(ctx, command, args) {
+    const cliArgs = COMMAND_MAP[command];
+    if (!cliArgs) {
+        await ctx.reply(`Unknown command: /${command}`);
+        return;
+    }
+    const fullArgs = [...cliArgs, ...args];
+    const displayCmd = `locus ${fullArgs.join(" ")}`;
+    const isStreaming = STREAMING_COMMANDS.has(command);
+    // Send pre-messages for specific commands
+    if (command === "run" && args.length > 0) {
+        await ctx.reply(runStartedMessage(args.join(" ")), { parse_mode: "HTML" });
+    }
+    else if (command === "review" && args.length > 0) {
+        await ctx.reply(reviewStartedMessage(Number(args[0])), {
+            parse_mode: "HTML",
+        });
+    }
+    if (isStreaming) {
+        await handleStreamingCommand(ctx, displayCmd, fullArgs, command, args);
+    }
+    else {
+        await handleBufferedCommand(ctx, displayCmd, fullArgs, command);
+    }
+}
+/**
+ * Handle a streaming command — edit the message in place as output arrives.
+ */
+async function handleStreamingCommand(ctx, displayCmd, fullArgs, command, args) {
+    const child = invokeLocusStream(fullArgs);
+    let output = "";
+    let lastEditTime = 0;
+    let editTimer = null;
+    // Send initial "running" message
+    const msg = await ctx.reply(formatStreamingMessage(displayCmd, "", false), {
+        parse_mode: "HTML",
+    });
+    const editMessage = async () => {
+        const now = Date.now();
+        if (now - lastEditTime < EDIT_INTERVAL)
+            return;
+        lastEditTime = now;
+        try {
+            await ctx.api.editMessageText(msg.chat.id, msg.message_id, formatStreamingMessage(displayCmd, output, false), { parse_mode: "HTML" });
+        }
+        catch {
+            // Edit can fail if content hasn't changed — ignore
+        }
+    };
+    child.stdout?.on("data", (chunk) => {
+        output += chunk.toString();
+        // Debounce edits
+        if (editTimer)
+            clearTimeout(editTimer);
+        editTimer = setTimeout(editMessage, EDIT_INTERVAL);
+    });
+    child.stderr?.on("data", (chunk) => {
+        output += chunk.toString();
+    });
+    await new Promise((resolve) => {
+        child.on("close", async (exitCode) => {
+            if (editTimer)
+                clearTimeout(editTimer);
+            // Final edit with complete output
+            try {
+                await ctx.api.editMessageText(msg.chat.id, msg.message_id, formatStreamingMessage(displayCmd, output, true), { parse_mode: "HTML" });
+            }
+            catch {
+                // ignore edit failures
+            }
+            // Send keyboard for post-command actions
+            const keyboard = getPostCommandKeyboard(command, args, exitCode ?? 0);
+            if (keyboard) {
+                await ctx.reply(exitCode === 0 ? "What would you like to do next?" : "Command failed.", { reply_markup: keyboard });
+            }
+            resolve();
+        });
+    });
+}
+/**
+ * Handle a buffered command — collect all output, then send once.
+ */
+async function handleBufferedCommand(ctx, displayCmd, fullArgs, command) {
+    const child = invokeLocusStream(fullArgs);
+    let output = "";
+    child.stdout?.on("data", (chunk) => {
+        output += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+        output += chunk.toString();
+    });
+    await new Promise((resolve) => {
+        child.on("close", async (exitCode) => {
+            const result = formatCommandResult(displayCmd, output, exitCode ?? 0);
+            const keyboard = getPostCommandKeyboard(command, [], exitCode ?? 0);
+            await ctx.reply(result, {
+                parse_mode: "HTML",
+                reply_markup: keyboard ?? undefined,
+            });
+            resolve();
+        });
+    });
+}
+// ─── Post-Command Keyboards ────────────────────────────────────────────────
+function getPostCommandKeyboard(command, args, exitCode) {
+    if (exitCode !== 0)
+        return null;
+    switch (command) {
+        case "plan":
+            return planKeyboard();
+        case "review":
+            if (args.length > 0) {
+                return reviewKeyboard(Number(args[0]));
+            }
+            return null;
+        case "run":
+            if (args.length > 0) {
+                return runCompleteKeyboard(Number(args[0]));
+            }
+            return runCompleteKeyboard();
+        case "status":
+            return statusKeyboard();
+        default:
+            return null;
+    }
+}

package/dist/commands/service.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Service management commands — PM2 lifecycle control via Telegram.
+ */
+import type { Context } from "grammy";
+/** /service <subcommand> — manage the bot process */
+export declare function handleService(ctx: Context, args: string[]): Promise<void>;

package/dist/commands/service.js

@@ -0,0 +1,58 @@
+/**
+ * Service management commands — PM2 lifecycle control via Telegram.
+ */
+import { formatError, formatSuccess, codeBlock } from "../ui/format.js";
+import { pm2Start, pm2Stop, pm2Restart, pm2Delete, pm2Status, pm2Logs, } from "../pm2.js";
+import { serviceStatusMessage, serviceNotRunningMessage } from "../ui/messages.js";
+/** /service <subcommand> — manage the bot process */
+export async function handleService(ctx, args) {
+    const subcommand = args[0] ?? "status";
+    try {
+        switch (subcommand) {
+            case "start": {
+                const result = pm2Start();
+                await ctx.reply(formatSuccess(result), { parse_mode: "HTML" });
+                break;
+            }
+            case "stop": {
+                const result = pm2Stop();
+                await ctx.reply(formatSuccess(result), { parse_mode: "HTML" });
+                break;
+            }
+            case "restart": {
+                const result = pm2Restart();
+                await ctx.reply(formatSuccess(result), { parse_mode: "HTML" });
+                break;
+            }
+            case "delete": {
+                const result = pm2Delete();
+                await ctx.reply(formatSuccess(result), { parse_mode: "HTML" });
+                break;
+            }
+            case "status": {
+                const status = pm2Status();
+                if (!status) {
+                    await ctx.reply(serviceNotRunningMessage(), {
+                        parse_mode: "HTML",
+                    });
+                }
+                else {
+                    await ctx.reply(serviceStatusMessage(status.status, status.pid, status.uptime, status.memory, status.restarts), { parse_mode: "HTML" });
+                }
+                break;
+            }
+            case "logs": {
+                const lines = args[1] ? Number(args[1]) : 50;
+                const logs = pm2Logs(lines);
+                await ctx.reply(codeBlock(logs), { parse_mode: "HTML" });
+                break;
+            }
+            default: {
+                await ctx.reply(formatError("Unknown service command. Use: start, stop, restart, delete, status, logs"), { parse_mode: "HTML" });
+            }
+        }
+    }
+    catch (error) {
+        await ctx.reply(formatError("Service command failed", String(error)), { parse_mode: "HTML" });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Environment configuration for the Telegram bot.
+ *
+ * Required env vars:
+ *   LOCUS_TELEGRAM_BOT_TOKEN  — Telegram Bot API token from @BotFather
+ *   LOCUS_TELEGRAM_CHAT_ID    — Comma-separated list of allowed chat IDs
+ */
+export interface TelegramConfig {
+    botToken: string;
+    allowedChatIds: number[];
+}
+export declare function loadTelegramConfig(): TelegramConfig;

package/dist/config.js

@@ -0,0 +1,32 @@
+/**
+ * Environment configuration for the Telegram bot.
+ *
+ * Required env vars:
+ *   LOCUS_TELEGRAM_BOT_TOKEN  — Telegram Bot API token from @BotFather
+ *   LOCUS_TELEGRAM_CHAT_ID    — Comma-separated list of allowed chat IDs
+ */
+export function loadTelegramConfig() {
+    const botToken = process.env.LOCUS_TELEGRAM_BOT_TOKEN;
+    if (!botToken) {
+        throw new Error("LOCUS_TELEGRAM_BOT_TOKEN is required. Get one from @BotFather on Telegram.");
+    }
+    const chatIdRaw = process.env.LOCUS_TELEGRAM_CHAT_ID;
+    if (!chatIdRaw) {
+        throw new Error("LOCUS_TELEGRAM_CHAT_ID is required. Send /start to your bot and use the chat ID.");
+    }
+    const allowedChatIds = chatIdRaw
+        .split(",")
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0)
+        .map((id) => {
+        const parsed = Number.parseInt(id, 10);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Invalid chat ID: "${id}". Must be a number.`);
+        }
+        return parsed;
+    });
+    if (allowedChatIds.length === 0) {
+        throw new Error("LOCUS_TELEGRAM_CHAT_ID must contain at least one chat ID.");
+    }
+    return { botToken, allowedChatIds };
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Main entry point for locus-telegram.
+ *
+ * Dispatches to either:
+ *   - PM2 service management (start/stop/restart/status/logs)
+ *   - Direct bot execution (bot)
+ *
+ * Usage:
+ *   locus pkg telegram start      → start bot via PM2
+ *   locus pkg telegram stop       → stop bot via PM2
+ *   locus pkg telegram restart    → restart bot
+ *   locus pkg telegram status     → show PM2 process status
+ *   locus pkg telegram logs       → tail PM2 logs
+ *   locus pkg telegram bot        → run bot directly (foreground)
+ */
+export declare function main(args: string[]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,144 @@
+/**
+ * Main entry point for locus-telegram.
+ *
+ * Dispatches to either:
+ *   - PM2 service management (start/stop/restart/status/logs)
+ *   - Direct bot execution (bot)
+ *
+ * Usage:
+ *   locus pkg telegram start      → start bot via PM2
+ *   locus pkg telegram stop       → stop bot via PM2
+ *   locus pkg telegram restart    → restart bot
+ *   locus pkg telegram status     → show PM2 process status
+ *   locus pkg telegram logs       → tail PM2 logs
+ *   locus pkg telegram bot        → run bot directly (foreground)
+ */
+import { createLogger } from "@locusai/sdk";
+import { createBot } from "./bot.js";
+import { loadTelegramConfig } from "./config.js";
+import { pm2Start, pm2Stop, pm2Restart, pm2Delete, pm2Status, pm2Logs, } from "./pm2.js";
+const logger = createLogger("telegram");
+export async function main(args) {
+    const command = args[0] ?? "help";
+    switch (command) {
+        case "start":
+            return handleStart();
+        case "stop":
+            return handleStop();
+        case "restart":
+            return handleRestart();
+        case "delete":
+            return handleDelete();
+        case "status":
+            return handleStatus();
+        case "logs":
+            return handleLogs(args.slice(1));
+        case "bot":
+            return handleBot();
+        case "help":
+        case "--help":
+        case "-h":
+            return printHelp();
+        default:
+            console.error(`Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+// ─── PM2 Service Commands ───────────────────────────────────────────────────
+function handleStart() {
+    const result = pm2Start();
+    logger.info(result);
+}
+function handleStop() {
+    const result = pm2Stop();
+    logger.info(result);
+}
+function handleRestart() {
+    const result = pm2Restart();
+    logger.info(result);
+}
+function handleDelete() {
+    const result = pm2Delete();
+    logger.info(result);
+}
+function handleStatus() {
+    const status = pm2Status();
+    if (!status) {
+        logger.warn("Bot is not running");
+        return;
+    }
+    const uptimeStr = status.uptime
+        ? `${Math.floor((Date.now() - status.uptime) / 1000)}s`
+        : "N/A";
+    const memStr = status.memory
+        ? `${(status.memory / (1024 * 1024)).toFixed(1)}MB`
+        : "N/A";
+    console.log(`
+  Name:     ${status.name}
+  Status:   ${status.status}
+  PID:      ${status.pid ?? "N/A"}
+  Uptime:   ${uptimeStr}
+  Memory:   ${memStr}
+  Restarts: ${status.restarts}
+  `);
+}
+function handleLogs(args) {
+    const lines = args[0] ? Number(args[0]) : 50;
+    const logs = pm2Logs(lines);
+    console.log(logs);
+}
+// ─── Direct Bot Execution ───────────────────────────────────────────────────
+async function handleBot() {
+    const config = loadTelegramConfig();
+    const bot = createBot(config);
+    logger.info("Starting Telegram bot...");
+    logger.info(`Allowed chat IDs: ${config.allowedChatIds.join(", ")}`);
+    // Graceful shutdown
+    const shutdown = () => {
+        logger.info("Shutting down bot...");
+        bot.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    await bot.start({
+        onStart: () => {
+            logger.info("Bot is running. Send /help in Telegram to get started.");
+        },
+    });
+}
+// ─── Help ───────────────────────────────────────────────────────────────────
+function printHelp() {
+    console.log(`
+  locus-telegram — Remote-control Locus via Telegram
+
+  Usage:
+    locus pkg telegram <command>
+
+  Commands:
+    start       Start the bot via PM2 (background)
+    stop        Stop the bot
+    restart     Restart the bot
+    delete      Remove the bot from PM2
+    status      Show bot process status
+    logs [n]    Show last n lines of logs (default: 50)
+    bot         Run the bot directly (foreground)
+    help        Show this help message
+
+  Environment Variables:
+    LOCUS_TELEGRAM_BOT_TOKEN    Telegram Bot API token (from @BotFather)
+    LOCUS_TELEGRAM_CHAT_ID      Comma-separated list of allowed chat IDs
+
+  Examples:
+    # Set up environment
+    export LOCUS_TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
+    export LOCUS_TELEGRAM_CHAT_ID="12345678"
+
+    # Start in background
+    locus pkg telegram start
+
+    # Run in foreground (for development)
+    locus pkg telegram bot
+  `);
+}

package/dist/pm2.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PM2 programmatic wrapper for managing the Telegram bot process.
+ *
+ * Uses pm2 package API to start/stop/restart/status/logs the bot.
+ */
+export declare function pm2Start(): string;
+export declare function pm2Stop(): string;
+export declare function pm2Restart(): string;
+export declare function pm2Delete(): string;
+export interface Pm2Status {
+    name: string;
+    status: string;
+    pid: number | null;
+    uptime: number | null;
+    memory: number | null;
+    restarts: number;
+}
+export declare function pm2Status(): Pm2Status | null;
+export declare function pm2Logs(lines?: number): string;

package/dist/pm2.js

@@ -0,0 +1,112 @@
+/**
+ * PM2 programmatic wrapper for managing the Telegram bot process.
+ *
+ * Uses pm2 package API to start/stop/restart/status/logs the bot.
+ */
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const PROCESS_NAME = "locus-telegram";
+function getPm2Bin() {
+    // Try local node_modules first, then global
+    try {
+        const result = execSync("which pm2", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (result)
+            return result;
+    }
+    catch {
+        // fall through
+    }
+    // Try npx as fallback
+    return "npx pm2";
+}
+function pm2Exec(args) {
+    const pm2 = getPm2Bin();
+    try {
+        return execSync(`${pm2} ${args}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            env: process.env,
+        });
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(err.stderr?.trim() || err.message || "PM2 command failed");
+    }
+}
+function getBotScriptPath() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const packageRoot = dirname(dirname(currentFile));
+    return join(packageRoot, "bin", "locus-telegram.js");
+}
+export function pm2Start() {
+    const script = getBotScriptPath();
+    const pm2 = getPm2Bin();
+    // Pass env vars through to the PM2 process
+    const envArgs = [];
+    if (process.env.LOCUS_TELEGRAM_BOT_TOKEN) {
+        envArgs.push("--env", `LOCUS_TELEGRAM_BOT_TOKEN=${process.env.LOCUS_TELEGRAM_BOT_TOKEN}`);
+    }
+    try {
+        // Check if already running
+        const list = pm2Exec("jlist");
+        const processes = JSON.parse(list);
+        const existing = processes.find((p) => p.name === PROCESS_NAME);
+        if (existing) {
+            pm2Exec(`restart ${PROCESS_NAME}`);
+            return `Restarted ${PROCESS_NAME}`;
+        }
+    }
+    catch {
+        // Not running, start fresh
+    }
+    execSync(`${pm2} start ${JSON.stringify(script)} --name ${PROCESS_NAME} -- bot`, {
+        encoding: "utf-8",
+        stdio: "inherit",
+        env: process.env,
+    });
+    return `Started ${PROCESS_NAME}`;
+}
+export function pm2Stop() {
+    pm2Exec(`stop ${PROCESS_NAME}`);
+    return `Stopped ${PROCESS_NAME}`;
+}
+export function pm2Restart() {
+    pm2Exec(`restart ${PROCESS_NAME}`);
+    return `Restarted ${PROCESS_NAME}`;
+}
+export function pm2Delete() {
+    pm2Exec(`delete ${PROCESS_NAME}`);
+    return `Deleted ${PROCESS_NAME}`;
+}
+export function pm2Status() {
+    try {
+        const list = pm2Exec("jlist");
+        const processes = JSON.parse(list);
+        const proc = processes.find((p) => p.name === PROCESS_NAME);
+        if (!proc)
+            return null;
+        return {
+            name: PROCESS_NAME,
+            status: proc.pm2_env?.status ?? "unknown",
+            pid: proc.pid ?? null,
+            uptime: proc.pm2_env?.pm_uptime ?? null,
+            memory: proc.monit?.memory ?? null,
+            restarts: proc.pm2_env?.restart_time ?? 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function pm2Logs(lines = 50) {
+    try {
+        return pm2Exec(`logs ${PROCESS_NAME} --nostream --lines ${lines}`);
+    }
+    catch {
+        return "No logs available.";
+    }
+}

package/dist/ui/format.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Output formatting utilities for Telegram messages.
+ *
+ * Telegram supports a subset of Markdown (MarkdownV2) and HTML.
+ * We use HTML mode for reliability — fewer escaping issues than MarkdownV2.
+ */
+/** Escape HTML special characters for Telegram HTML mode. */
+export declare function escapeHtml(text: string): string;
+/** Wrap text in a code block. */
+export declare function codeBlock(text: string, language?: string): string;
+/** Wrap text in inline code. */
+export declare function inlineCode(text: string): string;
+/** Bold text. */
+export declare function bold(text: string): string;
+/** Italic text. */
+export declare function italic(text: string): string;
+/** Truncate text to a max length, appending "..." if truncated. */
+export declare function truncate(text: string, maxLength?: number): string;
+/** Split long output into multiple messages if needed. */
+export declare function splitMessage(text: string): string[];
+/** Format a command result as a Telegram message. */
+export declare function formatCommandResult(command: string, output: string, exitCode: number): string;
+/** Format a streaming progress message. */
+export declare function formatStreamingMessage(command: string, output: string, isComplete: boolean): string;
+/** Format an error message. */
+export declare function formatError(message: string, detail?: string): string;
+/** Format a success message. */
+export declare function formatSuccess(message: string): string;
+/** Format an info message. */
+export declare function formatInfo(message: string): string;