@locusai/locus-telegram 0.21.6

package/src/commands/git.ts

@@ -0,0 +1,309 @@
+/**
+ * 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 type { Context } from "grammy";
+import {
+  bold,
+  codeBlock,
+  escapeHtml,
+  formatError,
+  formatSuccess,
+} 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: string): string {
+  return execSync(`git ${args}`, {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+    cwd: process.cwd(),
+  });
+}
+
+function gitSafe(args: string): string | null {
+  try {
+    return git(args);
+  } catch {
+    return null;
+  }
+}
+
+// ─── Command Handlers ───────────────────────────────────────────────────────
+
+/** /gitstatus — show git status */
+export async function handleGitStatus(ctx: Context): Promise<void> {
+  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: unknown) {
+    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: Context, args: string[]): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Failed to stage files", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}
+
+/** /commit <message> — commit staged changes */
+export async function handleCommit(
+  ctx: Context,
+  args: string[]
+): Promise<void> {
+  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: unknown) {
+    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: Context, args: string[]): Promise<void> {
+  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: unknown) {
+    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: Context,
+  args: string[]
+): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Branch operation failed", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}
+
+/** /checkout <branch> — switch to a branch */
+export async function handleCheckout(
+  ctx: Context,
+  args: string[]
+): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Checkout failed", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}
+
+/** /diff — show git diff summary */
+export async function handleDiff(ctx: Context): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Diff failed", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}
+
+/** /pr <title> — create a pull request */
+export async function handlePR(ctx: Context, args: string[]): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Failed to create PR", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}

package/src/commands/locus.ts

@@ -0,0 +1,232 @@
+/**
+ * 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 type { Context } from "grammy";
+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: Record<string, string[]> = {
+  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: Context,
+  command: string,
+  args: string[]
+): Promise<void> {
+  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: Context,
+  displayCmd: string,
+  fullArgs: string[],
+  command: string,
+  args: string[]
+): Promise<void> {
+  const child = invokeLocusStream(fullArgs);
+
+  let output = "";
+  let lastEditTime = 0;
+  let editTimer: ReturnType<typeof setTimeout> | null = 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: Buffer) => {
+    output += chunk.toString();
+
+    // Debounce edits
+    if (editTimer) clearTimeout(editTimer);
+    editTimer = setTimeout(editMessage, EDIT_INTERVAL);
+  });
+
+  child.stderr?.on("data", (chunk: Buffer) => {
+    output += chunk.toString();
+  });
+
+  await new Promise<void>((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: Context,
+  displayCmd: string,
+  fullArgs: string[],
+  command: string
+): Promise<void> {
+  const child = invokeLocusStream(fullArgs);
+  let output = "";
+
+  child.stdout?.on("data", (chunk: Buffer) => {
+    output += chunk.toString();
+  });
+
+  child.stderr?.on("data", (chunk: Buffer) => {
+    output += chunk.toString();
+  });
+
+  await new Promise<void>((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: string,
+  args: string[],
+  exitCode: number
+) {
+  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/src/commands/service.ts

@@ -0,0 +1,89 @@
+/**
+ * Service management commands — PM2 lifecycle control via Telegram.
+ */
+
+import type { Context } from "grammy";
+import {
+  pm2Delete,
+  pm2Logs,
+  pm2Restart,
+  pm2Start,
+  pm2Status,
+  pm2Stop,
+} from "../pm2.js";
+import { codeBlock, formatError, formatSuccess } from "../ui/format.js";
+import {
+  serviceNotRunningMessage,
+  serviceStatusMessage,
+} from "../ui/messages.js";
+
+/** /service <subcommand> — manage the bot process */
+export async function handleService(
+  ctx: Context,
+  args: string[]
+): Promise<void> {
+  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: unknown) {
+    await ctx.reply(formatError("Service command failed", String(error)), {
+      parse_mode: "HTML",
+    });
+  }
+}

package/src/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Configuration for the Telegram bot, read from the Locus config system.
+ *
+ * Users configure via:
+ *   locus config packages.telegram.botToken "123456:ABC..."
+ *   locus config packages.telegram.chatIds "12345678,87654321"
+ */
+
+import { readLocusConfig } from "@locusai/sdk";
+
+export interface TelegramConfig {
+  botToken: string;
+  allowedChatIds: number[];
+}
+
+export function loadTelegramConfig(): TelegramConfig {
+  const locusConfig = readLocusConfig();
+  const pkg = locusConfig.packages?.telegram;
+
+  const botToken = pkg?.botToken;
+  if (!botToken || typeof botToken !== "string") {
+    throw new Error(
+      'Telegram bot token not configured. Run:\n  locus config packages.telegram.botToken "<your-token>"\n\nGet a token from @BotFather on Telegram.'
+    );
+  }
+
+  const chatIdsRaw = pkg?.chatIds;
+  if (!chatIdsRaw) {
+    throw new Error(
+      'Telegram chat IDs not configured. Run:\n  locus config packages.telegram.chatIds "12345678"\n\nSend /start to your bot, then use the chat ID from the Telegram API.'
+    );
+  }
+
+  const allowedChatIds = parseChatIds(chatIdsRaw);
+
+  if (allowedChatIds.length === 0) {
+    throw new Error(
+      "packages.telegram.chatIds must contain at least one chat ID."
+    );
+  }
+
+  return { botToken, allowedChatIds };
+}
+
+function parseChatIds(raw: unknown): number[] {
+  // Support both array of numbers and comma-separated string
+  if (Array.isArray(raw)) {
+    return raw.map((id) => {
+      const parsed = Number(id);
+      if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid chat ID: "${id}". Must be a number.`);
+      }
+      return parsed;
+    });
+  }
+
+  if (typeof raw === "string") {
+    return raw
+      .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 (typeof raw === "number") {
+    return [raw];
+  }
+
+  throw new Error(
+    "Invalid chatIds format. Expected a number, array of numbers, or comma-separated string."
+  );
+}