@locusai/locus-telegram 0.21.6

package/README.md

@@ -0,0 +1,117 @@
+# locus-telegram
+
+Remote-control your [Locus](https://github.com/locusai/locus) agent from Telegram. Full CLI command mapping, git operations, interactive keyboards, and built-in PM2 process management.
+
+## Setup
+
+### 1. Create a Telegram Bot
+
+1. Open [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot` and follow the prompts
+3. Copy the bot token
+
+### 2. Get Your Chat ID
+
+1. Send any message to your new bot
+2. Visit `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates`
+3. Find `"chat":{"id": <YOUR_CHAT_ID>}` in the response
+
+### 3. Configure Locus
+
+```sh
+locus config packages.telegram.botToken "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+locus config packages.telegram.chatIds "12345678"
+```
+
+Multiple chat IDs can be comma-separated: `"12345678,87654321"`
+
+### 4. Install & Start
+
+```sh
+locus install locus-telegram
+locus pkg telegram start
+```
+
+## Usage
+
+### Service Management (PM2)
+
+```sh
+locus pkg telegram start      # Start bot in background via PM2
+locus pkg telegram stop        # Stop the bot
+locus pkg telegram restart     # Restart the bot
+locus pkg telegram status      # Show process status
+locus pkg telegram logs [n]    # Show last n lines of logs
+locus pkg telegram bot         # Run in foreground (development)
+```
+
+### Telegram Commands
+
+#### Locus CLI
+
+| Command | Description |
+|---------|-------------|
+| `/run [issue#...]` | Execute issues |
+| `/status` | Dashboard view |
+| `/issues` | List issues |
+| `/issue <#>` | Show issue details |
+| `/sprint [sub]` | Sprint management |
+| `/plan [args]` | AI planning |
+| `/review <pr#>` | Code review |
+| `/iterate <pr#>` | Re-execute with feedback |
+| `/discuss [topic]` | AI discussion |
+| `/exec [prompt]` | REPL / one-shot |
+| `/logs` | View logs |
+| `/config [path]` | View config |
+| `/artifacts` | View artifacts |
+
+#### Git Operations
+
+| Command | Description |
+|---------|-------------|
+| `/gitstatus` | Git status |
+| `/stage [files\|.]` | Stage files |
+| `/commit <message>` | Commit changes |
+| `/stash [pop\|list\|drop]` | Stash operations |
+| `/branch [name]` | List/create branches |
+| `/checkout <branch>` | Switch branch |
+| `/diff` | Show diff |
+| `/pr <title>` | Create pull request |
+
+#### Service
+
+| Command | Description |
+|---------|-------------|
+| `/service start\|stop\|restart\|status\|logs` | Manage bot process |
+
+### Interactive Features
+
+The bot automatically shows inline keyboard buttons after certain commands:
+
+- **After `/plan`** — Approve, Reject, or Show Details
+- **After `/run`** — View Logs, Run Again
+- **After `/review`** — Approve, Request Changes, View Diff
+- **After `/status`** — Run Sprint, View Issues, View Logs
+- **After `/stash`** — Pop, List, Drop
+
+Non-command text messages are automatically sent to `locus exec` as prompts.
+
+## Security
+
+Only chat IDs listed in `packages.telegram.chatIds` in the locus config can interact with the bot. All other messages are silently ignored.
+
+## Development
+
+```sh
+cd packages/telegram
+bun install
+bun run build        # Compile TypeScript
+bun run typecheck    # Type-check only
+
+# Configure (if not already done)
+locus config packages.telegram.botToken "..."
+locus config packages.telegram.chatIds "..."
+
+# Run in foreground for development
+locus pkg telegram bot
+```

package/bin/locus-telegram.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../dist/index.js";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/dist/bot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Bot instance — sets up grammy bot, registers middleware, commands,
+ * and callback query handlers.
+ */
+import { Bot } from "grammy";
+import type { TelegramConfig } from "./config.js";
+export declare function createBot(config: TelegramConfig): Bot;

package/dist/bot.js

@@ -0,0 +1,203 @@
+/**
+ * Bot instance — sets up grammy bot, registers middleware, commands,
+ * and callback query handlers.
+ */
+import { Bot } from "grammy";
+import { createLogger } from "@locusai/sdk";
+import { handleLocusCommand } from "./commands/locus.js";
+import { handleGitStatus, handleStage, handleCommit, handleStash, handleBranch, handleCheckout, handleDiff, handlePR, } from "./commands/git.js";
+import { handleService } from "./commands/service.js";
+import { CB } from "./ui/keyboards.js";
+import { welcomeMessage } from "./ui/messages.js";
+import { formatSuccess, formatInfo } from "./ui/format.js";
+const logger = createLogger("telegram");
+// ─── Bot Factory ────────────────────────────────────────────────────────────
+export function createBot(config) {
+    const bot = new Bot(config.botToken);
+    // ── Auth Middleware ─────────────────────────────────────────────────────
+    bot.use(async (ctx, next) => {
+        const chatId = ctx.chat?.id;
+        if (!chatId || !config.allowedChatIds.includes(chatId)) {
+            logger.warn("Unauthorized access attempt", {
+                chatId,
+                from: ctx.from?.username,
+            });
+            return; // silently ignore
+        }
+        await next();
+    });
+    // ── Help / Start ────────────────────────────────────────────────────────
+    bot.command("start", async (ctx) => {
+        await ctx.reply(welcomeMessage(), { parse_mode: "HTML" });
+    });
+    bot.command("help", async (ctx) => {
+        await ctx.reply(welcomeMessage(), { parse_mode: "HTML" });
+    });
+    // ── Locus CLI Commands ──────────────────────────────────────────────────
+    const locusCommands = [
+        "run",
+        "status",
+        "issues",
+        "issue",
+        "sprint",
+        "plan",
+        "review",
+        "iterate",
+        "discuss",
+        "exec",
+        "logs",
+        "config",
+        "artifacts",
+    ];
+    for (const cmd of locusCommands) {
+        bot.command(cmd, async (ctx) => {
+            const args = parseArgs(ctx.message?.text ?? "", cmd);
+            await handleLocusCommand(ctx, cmd, args);
+        });
+    }
+    // ── Git Commands ────────────────────────────────────────────────────────
+    bot.command("gitstatus", async (ctx) => {
+        await handleGitStatus(ctx);
+    });
+    bot.command("stage", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "stage");
+        await handleStage(ctx, args);
+    });
+    bot.command("commit", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "commit");
+        await handleCommit(ctx, args);
+    });
+    bot.command("stash", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "stash");
+        await handleStash(ctx, args);
+    });
+    bot.command("branch", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "branch");
+        await handleBranch(ctx, args);
+    });
+    bot.command("checkout", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "checkout");
+        await handleCheckout(ctx, args);
+    });
+    bot.command("diff", async (ctx) => {
+        await handleDiff(ctx);
+    });
+    bot.command("pr", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "pr");
+        await handlePR(ctx, args);
+    });
+    // ── Service Commands ────────────────────────────────────────────────────
+    bot.command("service", async (ctx) => {
+        const args = parseArgs(ctx.message?.text ?? "", "service");
+        await handleService(ctx, args);
+    });
+    // ── Callback Query Handlers ─────────────────────────────────────────────
+    registerCallbackHandlers(bot);
+    // ── Fallback ────────────────────────────────────────────────────────────
+    bot.on("message:text", async (ctx) => {
+        // Treat non-command text as a locus exec prompt
+        const text = ctx.message.text;
+        if (text.startsWith("/"))
+            return; // unknown command — ignore
+        await handleLocusCommand(ctx, "exec", [text]);
+    });
+    return bot;
+}
+// ─── Callback Query Handlers ────────────────────────────────────────────────
+function registerCallbackHandlers(bot) {
+    // Plan callbacks
+    bot.callbackQuery(CB.APPROVE_PLAN, async (ctx) => {
+        await ctx.answerCallbackQuery({ text: "Plan approved!" });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await ctx.reply(formatSuccess("Plan approved. Starting execution..."), {
+            parse_mode: "HTML",
+        });
+        // Trigger the run
+        await handleLocusCommand(ctx, "run", []);
+    });
+    bot.callbackQuery(CB.REJECT_PLAN, async (ctx) => {
+        await ctx.answerCallbackQuery({ text: "Plan rejected." });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await ctx.reply(formatInfo("Plan rejected. No changes will be made."), {
+            parse_mode: "HTML",
+        });
+    });
+    bot.callbackQuery(CB.SHOW_PLAN_DETAILS, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleLocusCommand(ctx, "plan", ["--show"]);
+    });
+    // Run callbacks
+    bot.callbackQuery(CB.VIEW_LOGS, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleLocusCommand(ctx, "logs", ["--lines", "30"]);
+    });
+    bot.callbackQuery(/^run:again:(\d+)$/, async (ctx) => {
+        const issue = ctx.match[1];
+        await ctx.answerCallbackQuery({ text: `Re-running issue #${issue}` });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await handleLocusCommand(ctx, "run", [issue]);
+    });
+    // Review callbacks
+    bot.callbackQuery(/^review:approve:(\d+)$/, async (ctx) => {
+        const pr = ctx.match[1];
+        await ctx.answerCallbackQuery({ text: "Approving PR..." });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await ctx.reply(formatSuccess(`Approved PR #${pr}`), {
+            parse_mode: "HTML",
+        });
+    });
+    bot.callbackQuery(/^review:changes:(\d+)$/, async (ctx) => {
+        const pr = ctx.match[1];
+        await ctx.answerCallbackQuery();
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await ctx.reply(formatInfo(`Requesting changes on PR #${pr}. Reply with your feedback and I'll pass it along via /iterate ${pr}`), { parse_mode: "HTML" });
+    });
+    bot.callbackQuery(/^review:diff:(\d+)$/, async (ctx) => {
+        const pr = ctx.match[1];
+        await ctx.answerCallbackQuery();
+        await handleLocusCommand(ctx, "review", [pr, "--diff"]);
+    });
+    // Status callbacks
+    bot.callbackQuery(CB.RUN_SPRINT, async (ctx) => {
+        await ctx.answerCallbackQuery({ text: "Starting sprint run..." });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await handleLocusCommand(ctx, "run", []);
+    });
+    bot.callbackQuery(CB.VIEW_ISSUES, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleLocusCommand(ctx, "issues", []);
+    });
+    // Stash callbacks
+    bot.callbackQuery(CB.STASH_POP, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleStash(ctx, ["pop"]);
+    });
+    bot.callbackQuery(CB.STASH_LIST, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleStash(ctx, ["list"]);
+    });
+    bot.callbackQuery(CB.STASH_DROP, async (ctx) => {
+        await ctx.answerCallbackQuery();
+        await handleStash(ctx, ["drop"]);
+    });
+    // Confirmation callbacks
+    bot.callbackQuery(CB.CONFIRM_ACTION, async (ctx) => {
+        await ctx.answerCallbackQuery({ text: "Confirmed!" });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    });
+    bot.callbackQuery(CB.CANCEL_ACTION, async (ctx) => {
+        await ctx.answerCallbackQuery({ text: "Cancelled." });
+        await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+        await ctx.reply(formatInfo("Action cancelled."), { parse_mode: "HTML" });
+    });
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/** Parse arguments from a Telegram command message. */
+function parseArgs(text, command) {
+    // Remove the /command part (handles @botname suffix too)
+    const prefixRegex = new RegExp(`^/${command}(@\\S+)?\\s*`);
+    const rest = text.replace(prefixRegex, "").trim();
+    if (!rest)
+        return [];
+    return rest.split(/\s+/);
+}

package/dist/commands/git.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Git command handlers — stage, commit, stash, branch, checkout, diff, PR.
+ *
+ * Uses direct git subprocess calls for fast, local operations.
+ * PR creation uses `gh` CLI (same as the locus CLI does).
+ */
+import type { Context } from "grammy";
+/** /gitstatus — show git status */
+export declare function handleGitStatus(ctx: Context): Promise<void>;
+/** /stage [files|.] — stage files for commit */
+export declare function handleStage(ctx: Context, args: string[]): Promise<void>;
+/** /commit <message> — commit staged changes */
+export declare function handleCommit(ctx: Context, args: string[]): Promise<void>;
+/** /stash [pop|list|drop|save] — stash operations */
+export declare function handleStash(ctx: Context, args: string[]): Promise<void>;
+/** /branch [name] — list branches or create a new one */
+export declare function handleBranch(ctx: Context, args: string[]): Promise<void>;
+/** /checkout <branch> — switch to a branch */
+export declare function handleCheckout(ctx: Context, args: string[]): Promise<void>;
+/** /diff — show git diff summary */
+export declare function handleDiff(ctx: Context): Promise<void>;
+/** /pr <title> — create a pull request */
+export declare function handlePR(ctx: Context, args: string[]): Promise<void>;

package/dist/commands/git.js

@@ -0,0 +1,255 @@
+/**
+ * Git command handlers — stage, commit, stash, branch, checkout, diff, PR.
+ *
+ * Uses direct git subprocess calls for fast, local operations.
+ * PR creation uses `gh` CLI (same as the locus CLI does).
+ */
+import { execSync } from "node:child_process";
+import { codeBlock, formatError, formatSuccess, bold, escapeHtml } from "../ui/format.js";
+import { stashKeyboard } from "../ui/keyboards.js";
+import { gitBranchCreatedMessage, gitCheckoutMessage, gitCommitMessage, gitStashMessage, prCreatedMessage, } from "../ui/messages.js";
+// ─── Git Helper ─────────────────────────────────────────────────────────────
+function git(args) {
+    return execSync(`git ${args}`, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        cwd: process.cwd(),
+    });
+}
+function gitSafe(args) {
+    try {
+        return git(args);
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Command Handlers ───────────────────────────────────────────────────────
+/** /gitstatus — show git status */
+export async function handleGitStatus(ctx) {
+    try {
+        const status = git("status --short");
+        if (!status.trim()) {
+            await ctx.reply(formatSuccess("Working tree is clean."), {
+                parse_mode: "HTML",
+            });
+            return;
+        }
+        const branch = git("branch --show-current").trim();
+        await ctx.reply(`${bold("Branch:")} ${escapeHtml(branch)}\n\n${codeBlock(status)}`, { parse_mode: "HTML" });
+    }
+    catch (error) {
+        await ctx.reply(formatError("Failed to get git status", String(error)), { parse_mode: "HTML" });
+    }
+}
+/** /stage [files|.] — stage files for commit */
+export async function handleStage(ctx, args) {
+    const target = args.length > 0 ? args.join(" ") : ".";
+    try {
+        git(`add ${target}`);
+        const status = git("status --short");
+        await ctx.reply(`${formatSuccess(`Staged: ${target}`)}\n\n${codeBlock(status)}`, { parse_mode: "HTML" });
+    }
+    catch (error) {
+        await ctx.reply(formatError("Failed to stage files", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}
+/** /commit <message> — commit staged changes */
+export async function handleCommit(ctx, args) {
+    if (args.length === 0) {
+        await ctx.reply(formatError("Usage: /commit <message>"), {
+            parse_mode: "HTML",
+        });
+        return;
+    }
+    const message = args.join(" ");
+    try {
+        const result = git(`commit -m ${JSON.stringify(message)}`);
+        // Extract short hash from commit output
+        const hashMatch = result.match(/\[[\w/.-]+ ([a-f0-9]+)\]/);
+        const hash = hashMatch?.[1] ?? "unknown";
+        await ctx.reply(gitCommitMessage(message, hash), {
+            parse_mode: "HTML",
+        });
+    }
+    catch (error) {
+        const errStr = String(error);
+        if (errStr.includes("nothing to commit")) {
+            await ctx.reply(formatError("Nothing to commit. Stage changes first with /stage"), {
+                parse_mode: "HTML",
+            });
+        }
+        else {
+            await ctx.reply(formatError("Failed to commit", errStr), {
+                parse_mode: "HTML",
+            });
+        }
+    }
+}
+/** /stash [pop|list|drop|save] — stash operations */
+export async function handleStash(ctx, args) {
+    const subcommand = args[0] ?? "push";
+    try {
+        switch (subcommand) {
+            case "push":
+            case "save": {
+                const message = args.slice(1).join(" ");
+                const stashArgs = message
+                    ? `stash push -m ${JSON.stringify(message)}`
+                    : "stash push";
+                git(stashArgs);
+                await ctx.reply(gitStashMessage("Changes stashed"), {
+                    parse_mode: "HTML",
+                    reply_markup: stashKeyboard(),
+                });
+                break;
+            }
+            case "pop": {
+                git("stash pop");
+                await ctx.reply(gitStashMessage("Stash popped"), {
+                    parse_mode: "HTML",
+                });
+                break;
+            }
+            case "list": {
+                const list = gitSafe("stash list") ?? "";
+                if (!list.trim()) {
+                    await ctx.reply(formatSuccess("No stashes."), {
+                        parse_mode: "HTML",
+                    });
+                }
+                else {
+                    await ctx.reply(codeBlock(list), { parse_mode: "HTML" });
+                }
+                break;
+            }
+            case "drop": {
+                const stashRef = args[1] ?? "stash@{0}";
+                git(`stash drop ${stashRef}`);
+                await ctx.reply(gitStashMessage(`Dropped ${stashRef}`), {
+                    parse_mode: "HTML",
+                });
+                break;
+            }
+            default: {
+                // Default: just stash
+                git("stash push");
+                await ctx.reply(gitStashMessage("Changes stashed"), {
+                    parse_mode: "HTML",
+                    reply_markup: stashKeyboard(),
+                });
+            }
+        }
+    }
+    catch (error) {
+        await ctx.reply(formatError("Stash operation failed", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}
+/** /branch [name] — list branches or create a new one */
+export async function handleBranch(ctx, args) {
+    try {
+        if (args.length === 0) {
+            // List branches
+            const branches = git("branch -a --format='%(refname:short)'");
+            const current = git("branch --show-current").trim();
+            await ctx.reply(`${bold("Current:")} ${escapeHtml(current)}\n\n${codeBlock(branches)}`, { parse_mode: "HTML" });
+        }
+        else {
+            // Create new branch
+            const branchName = args[0];
+            git(`branch ${branchName}`);
+            await ctx.reply(gitBranchCreatedMessage(branchName), {
+                parse_mode: "HTML",
+            });
+        }
+    }
+    catch (error) {
+        await ctx.reply(formatError("Branch operation failed", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}
+/** /checkout <branch> — switch to a branch */
+export async function handleCheckout(ctx, args) {
+    if (args.length === 0) {
+        await ctx.reply(formatError("Usage: /checkout <branch>"), {
+            parse_mode: "HTML",
+        });
+        return;
+    }
+    const branch = args[0];
+    try {
+        git(`checkout ${branch}`);
+        await ctx.reply(gitCheckoutMessage(branch), { parse_mode: "HTML" });
+    }
+    catch (error) {
+        await ctx.reply(formatError("Checkout failed", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}
+/** /diff — show git diff summary */
+export async function handleDiff(ctx) {
+    try {
+        const diff = git("diff --stat");
+        if (!diff.trim()) {
+            const staged = git("diff --cached --stat");
+            if (!staged.trim()) {
+                await ctx.reply(formatSuccess("No changes."), {
+                    parse_mode: "HTML",
+                });
+            }
+            else {
+                await ctx.reply(`${bold("Staged changes:")}\n\n${codeBlock(staged)}`, { parse_mode: "HTML" });
+            }
+        }
+        else {
+            await ctx.reply(`${bold("Unstaged changes:")}\n\n${codeBlock(diff)}`, { parse_mode: "HTML" });
+        }
+    }
+    catch (error) {
+        await ctx.reply(formatError("Diff failed", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}
+/** /pr <title> — create a pull request */
+export async function handlePR(ctx, args) {
+    if (args.length === 0) {
+        await ctx.reply(formatError("Usage: /pr <title>"), {
+            parse_mode: "HTML",
+        });
+        return;
+    }
+    const title = args.join(" ");
+    try {
+        // Push current branch first
+        const branch = git("branch --show-current").trim();
+        try {
+            git(`push -u origin ${branch}`);
+        }
+        catch {
+            // May already be pushed — continue
+        }
+        // Create PR using gh CLI
+        const result = execSync(`gh pr create --title ${JSON.stringify(title)} --body "Created via Locus Telegram Bot" --head ${branch}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            cwd: process.cwd(),
+        });
+        const prMatch = result.match(/\/pull\/(\d+)/);
+        const prNumber = prMatch ? Number(prMatch[1]) : 0;
+        await ctx.reply(prCreatedMessage(prNumber, result.trim()), {
+            parse_mode: "HTML",
+        });
+    }
+    catch (error) {
+        await ctx.reply(formatError("Failed to create PR", String(error)), {
+            parse_mode: "HTML",
+        });
+    }
+}

package/dist/commands/locus.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 type { Context } from "grammy";
+/**
+ * Execute a locus CLI command, streaming output to the Telegram chat.
+ */
+export declare function handleLocusCommand(ctx: Context, command: string, args: string[]): Promise<void>;