@locusai/locus-telegram 0.21.6

package/src/index.ts

@@ -0,0 +1,169 @@
+/**
+ * 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 {
+  pm2Delete,
+  pm2Logs,
+  pm2Restart,
+  pm2Start,
+  pm2Status,
+  pm2Stop,
+} from "./pm2.js";
+
+const logger = createLogger("telegram");
+
+export async function main(args: string[]): Promise<void> {
+  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(): void {
+  const result = pm2Start();
+  logger.info(result);
+}
+
+function handleStop(): void {
+  const result = pm2Stop();
+  logger.info(result);
+}
+
+function handleRestart(): void {
+  const result = pm2Restart();
+  logger.info(result);
+}
+
+function handleDelete(): void {
+  const result = pm2Delete();
+  logger.info(result);
+}
+
+function handleStatus(): void {
+  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: string[]): void {
+  const lines = args[0] ? Number(args[0]) : 50;
+  const logs = pm2Logs(lines);
+  console.log(logs);
+}
+
+// ─── Direct Bot Execution ───────────────────────────────────────────────────
+
+async function handleBot(): Promise<void> {
+  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(): void {
+  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
+
+  Configuration (via locus config):
+    packages.telegram.botToken    Telegram Bot API token (from @BotFather)
+    packages.telegram.chatIds     Comma-separated chat IDs or JSON array
+
+  Setup:
+    locus config packages.telegram.botToken "123456:ABC-DEF..."
+    locus config packages.telegram.chatIds "12345678"
+
+  Examples:
+    locus pkg telegram start      # Start in background
+    locus pkg telegram bot        # Run in foreground (development)
+  `);
+}

package/src/pm2.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROCESS_NAME = "locus-telegram";
+
+function getPm2Bin(): string {
+  // 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: string): string {
+  const pm2 = getPm2Bin();
+  try {
+    return execSync(`${pm2} ${args}`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+  } catch (error: unknown) {
+    const err = error as { stderr?: string; message?: string };
+    throw new Error(err.stderr?.trim() || err.message || "PM2 command failed");
+  }
+}
+
+function getBotScriptPath(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  const packageRoot = dirname(dirname(currentFile));
+  return join(packageRoot, "bin", "locus-telegram.js");
+}
+
+export function pm2Start(): string {
+  const script = getBotScriptPath();
+  const pm2 = getPm2Bin();
+
+  try {
+    // Check if already running
+    const list = pm2Exec("jlist");
+    const processes = JSON.parse(list) as Array<{ name: string }>;
+    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(): string {
+  pm2Exec(`stop ${PROCESS_NAME}`);
+  return `Stopped ${PROCESS_NAME}`;
+}
+
+export function pm2Restart(): string {
+  pm2Exec(`restart ${PROCESS_NAME}`);
+  return `Restarted ${PROCESS_NAME}`;
+}
+
+export function pm2Delete(): string {
+  pm2Exec(`delete ${PROCESS_NAME}`);
+  return `Deleted ${PROCESS_NAME}`;
+}
+
+export interface Pm2Status {
+  name: string;
+  status: string;
+  pid: number | null;
+  uptime: number | null;
+  memory: number | null;
+  restarts: number;
+}
+
+export function pm2Status(): Pm2Status | null {
+  try {
+    const list = pm2Exec("jlist");
+    const processes = JSON.parse(list) as Array<{
+      name: string;
+      pm2_env?: {
+        status?: string;
+        pm_uptime?: number;
+        restart_time?: number;
+      };
+      pid?: number;
+      monit?: { memory?: number };
+    }>;
+
+    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): string {
+  try {
+    return pm2Exec(`logs ${PROCESS_NAME} --nostream --lines ${lines}`);
+  } catch {
+    return "No logs available.";
+  }
+}

package/src/ui/format.ts

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ */
+
+/** Maximum Telegram message length (4096 chars). */
+const MAX_MESSAGE_LENGTH = 4096;
+
+/** Maximum length for a code block inside a message. */
+const MAX_CODE_LENGTH = 3800;
+
+/** Escape HTML special characters for Telegram HTML mode. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** Wrap text in a code block. */
+export function codeBlock(text: string, language = ""): string {
+  const truncated = truncate(text, MAX_CODE_LENGTH);
+  return `<pre><code${language ? ` class="language-${language}"` : ""}>${escapeHtml(truncated)}</code></pre>`;
+}
+
+/** Wrap text in inline code. */
+export function inlineCode(text: string): string {
+  return `<code>${escapeHtml(text)}</code>`;
+}
+
+/** Bold text. */
+export function bold(text: string): string {
+  return `<b>${text}</b>`;
+}
+
+/** Italic text. */
+export function italic(text: string): string {
+  return `<i>${text}</i>`;
+}
+
+/** Truncate text to a max length, appending "..." if truncated. */
+export function truncate(text: string, maxLength = MAX_MESSAGE_LENGTH): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 20)}\n\n... (truncated)`;
+}
+
+/** Split long output into multiple messages if needed. */
+export function splitMessage(text: string): string[] {
+  if (text.length <= MAX_MESSAGE_LENGTH) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= MAX_MESSAGE_LENGTH) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Try to split at a newline
+    let splitIdx = remaining.lastIndexOf("\n", MAX_MESSAGE_LENGTH);
+    if (splitIdx === -1 || splitIdx < MAX_MESSAGE_LENGTH / 2) {
+      splitIdx = MAX_MESSAGE_LENGTH;
+    }
+
+    chunks.push(remaining.slice(0, splitIdx));
+    remaining = remaining.slice(splitIdx);
+  }
+
+  return chunks;
+}
+
+/** Format a command result as a Telegram message. */
+export function formatCommandResult(
+  command: string,
+  output: string,
+  exitCode: number
+): string {
+  const status = exitCode === 0 ? "✅" : "❌";
+  const header = `${status} ${bold(escapeHtml(command))}`;
+
+  if (!output.trim()) {
+    return exitCode === 0
+      ? `${header}\n\nCompleted successfully.`
+      : `${header}\n\nFailed with exit code ${exitCode}.`;
+  }
+
+  return `${header}\n\n${codeBlock(output.trim())}`;
+}
+
+/** Format a streaming progress message. */
+export function formatStreamingMessage(
+  command: string,
+  output: string,
+  isComplete: boolean
+): string {
+  const status = isComplete ? "✅" : "⏳";
+  const header = `${status} ${bold(escapeHtml(command))}`;
+
+  if (!output.trim()) {
+    return `${header}\n\n${italic("Running...")}`;
+  }
+
+  // Take last N lines for streaming display
+  const lines = output.trim().split("\n");
+  const lastLines = lines.slice(-30).join("\n");
+
+  return `${header}\n\n${codeBlock(lastLines)}`;
+}
+
+/** Format an error message. */
+export function formatError(message: string, detail?: string): string {
+  let text = `❌ ${bold("Error")}\n\n${escapeHtml(message)}`;
+  if (detail) {
+    text += `\n\n${codeBlock(detail)}`;
+  }
+  return text;
+}
+
+/** Format a success message. */
+export function formatSuccess(message: string): string {
+  return `✅ ${escapeHtml(message)}`;
+}
+
+/** Format an info message. */
+export function formatInfo(message: string): string {
+  return `ℹ️ ${escapeHtml(message)}`;
+}

package/src/ui/keyboards.ts

@@ -0,0 +1,83 @@
+/**
+ * Inline keyboard builders for interactive Telegram responses.
+ *
+ * Keyboards are attached to messages to let users take actions
+ * without typing commands manually.
+ */
+
+import { InlineKeyboard } from "grammy";
+
+// ─── Callback Data Prefixes ─────────────────────────────────────────────────
+
+export const CB = {
+  APPROVE_PLAN: "plan:approve",
+  REJECT_PLAN: "plan:reject",
+  SHOW_PLAN_DETAILS: "plan:details",
+  CONFIRM_ACTION: "confirm:yes",
+  CANCEL_ACTION: "confirm:no",
+  VIEW_PR: "pr:view:",
+  VIEW_LOGS: "logs:view",
+  RUN_AGAIN: "run:again:",
+  APPROVE_REVIEW: "review:approve:",
+  REQUEST_CHANGES: "review:changes:",
+  VIEW_DIFF: "review:diff:",
+  RUN_SPRINT: "sprint:run",
+  VIEW_ISSUES: "issues:view",
+  STASH_POP: "stash:pop",
+  STASH_LIST: "stash:list",
+  STASH_DROP: "stash:drop",
+} as const;
+
+// ─── Keyboard Builders ──────────────────────────────────────────────────────
+
+/** Keyboard shown after plan creation. */
+export function planKeyboard(): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("✅ Approve Plan", CB.APPROVE_PLAN)
+    .text("❌ Reject Plan", CB.REJECT_PLAN)
+    .row()
+    .text("📋 Show Details", CB.SHOW_PLAN_DETAILS);
+}
+
+/** Keyboard shown after a run completes. */
+export function runCompleteKeyboard(issueNumber?: number): InlineKeyboard {
+  const kb = new InlineKeyboard();
+  kb.text("📄 View Logs", CB.VIEW_LOGS);
+  if (issueNumber) {
+    kb.text("🔄 Run Again", `${CB.RUN_AGAIN}${issueNumber}`);
+  }
+  return kb;
+}
+
+/** Keyboard shown after review. */
+export function reviewKeyboard(prNumber: number): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("✅ Approve", `${CB.APPROVE_REVIEW}${prNumber}`)
+    .text("🔄 Request Changes", `${CB.REQUEST_CHANGES}${prNumber}`)
+    .row()
+    .text("📝 View Diff", `${CB.VIEW_DIFF}${prNumber}`);
+}
+
+/** Confirmation keyboard for destructive operations. */
+export function confirmKeyboard(): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("✅ Confirm", CB.CONFIRM_ACTION)
+    .text("❌ Cancel", CB.CANCEL_ACTION);
+}
+
+/** Keyboard shown after status check. */
+export function statusKeyboard(): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("🚀 Run Sprint", CB.RUN_SPRINT)
+    .text("📋 Issues", CB.VIEW_ISSUES)
+    .row()
+    .text("📄 Logs", CB.VIEW_LOGS);
+}
+
+/** Keyboard for stash operations. */
+export function stashKeyboard(): InlineKeyboard {
+  return new InlineKeyboard()
+    .text("📤 Pop", CB.STASH_POP)
+    .text("📋 List", CB.STASH_LIST)
+    .text("🗑 Drop", CB.STASH_DROP);
+}

package/src/ui/messages.ts

@@ -0,0 +1,189 @@
+/**
+ * Predefined response message templates for common bot interactions.
+ *
+ * All messages use HTML formatting for Telegram.
+ */
+
+import { bold, codeBlock, escapeHtml, italic } from "./format.js";
+
+// ─── Welcome & Help ─────────────────────────────────────────────────────────
+
+export function welcomeMessage(): string {
+  return [
+    `${bold("🤖 Locus Telegram Bot")}`,
+    "",
+    "Control your Locus agent directly from Telegram.",
+    "",
+    `${bold("Locus Commands")}`,
+    "/run [issue#...] — Execute issues",
+    "/status — Dashboard view",
+    "/issues [filters] — 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",
+    "",
+    `${bold("Git Commands")}`,
+    "/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",
+    "",
+    `${bold("Service Commands")}`,
+    "/service start|stop|restart|status|logs",
+    "",
+    "/help — Show this message",
+  ].join("\n");
+}
+
+// ─── Plan Messages ──────────────────────────────────────────────────────────
+
+export function planCreatedMessage(planOutput: string): string {
+  return [
+    `📋 ${bold("Plan Created")}`,
+    "",
+    codeBlock(planOutput),
+    "",
+    italic("Use the buttons below to approve or reject the plan."),
+  ].join("\n");
+}
+
+export function planApprovedMessage(): string {
+  return `✅ ${bold("Plan Approved")} — Proceeding with execution.`;
+}
+
+export function planRejectedMessage(): string {
+  return `❌ ${bold("Plan Rejected")} — No changes will be made.`;
+}
+
+// ─── Run Messages ───────────────────────────────────────────────────────────
+
+export function runStartedMessage(target: string): string {
+  return `🚀 ${bold("Run Started")} — ${escapeHtml(target)}`;
+}
+
+export function runCompletedMessage(target: string, prNumber?: number): string {
+  const lines = [`✅ ${bold("Run Completed")} — ${escapeHtml(target)}`];
+  if (prNumber) {
+    lines.push("", `Pull Request: #${prNumber}`);
+  }
+  return lines.join("\n");
+}
+
+export function runFailedMessage(target: string, error: string): string {
+  return [
+    `❌ ${bold("Run Failed")} — ${escapeHtml(target)}`,
+    "",
+    codeBlock(error),
+  ].join("\n");
+}
+
+// ─── Review Messages ────────────────────────────────────────────────────────
+
+export function reviewStartedMessage(prNumber: number): string {
+  return `🔍 ${bold("Reviewing")} PR #${prNumber}...`;
+}
+
+export function reviewCompletedMessage(
+  prNumber: number,
+  output: string
+): string {
+  return [
+    `✅ ${bold("Review Complete")} — PR #${prNumber}`,
+    "",
+    codeBlock(output),
+  ].join("\n");
+}
+
+// ─── Git Messages ───────────────────────────────────────────────────────────
+
+export function gitCommitMessage(message: string, hash: string): string {
+  return [
+    `✅ ${bold("Committed")}`,
+    "",
+    `Message: ${escapeHtml(message)}`,
+    `Hash: ${escapeHtml(hash)}`,
+  ].join("\n");
+}
+
+export function gitBranchCreatedMessage(name: string): string {
+  return `✅ Branch ${bold(escapeHtml(name))} created.`;
+}
+
+export function gitCheckoutMessage(branch: string): string {
+  return `✅ Switched to branch ${bold(escapeHtml(branch))}.`;
+}
+
+export function gitStashMessage(action: string): string {
+  return `✅ ${bold("Stash")} — ${escapeHtml(action)} completed.`;
+}
+
+export function prCreatedMessage(prNumber: number, url: string): string {
+  return [
+    `✅ ${bold("Pull Request Created")}`,
+    "",
+    `PR #${prNumber}: ${escapeHtml(url)}`,
+  ].join("\n");
+}
+
+// ─── Service Messages ───────────────────────────────────────────────────────
+
+export function serviceStatusMessage(
+  status: string,
+  pid: number | null,
+  uptime: number | null,
+  memory: number | null,
+  restarts: number
+): string {
+  const uptimeStr = uptime ? formatUptime(uptime) : "N/A";
+  const memoryStr = memory ? formatMemory(memory) : "N/A";
+
+  return [
+    `🤖 ${bold("Locus Telegram Bot")}`,
+    "",
+    `Status: ${bold(status)}`,
+    `PID: ${pid ?? "N/A"}`,
+    `Uptime: ${uptimeStr}`,
+    `Memory: ${memoryStr}`,
+    `Restarts: ${restarts}`,
+  ].join("\n");
+}
+
+export function serviceNotRunningMessage(): string {
+  return [
+    `⚠️ ${bold("Bot Not Running")}`,
+    "",
+    "Start the bot with:",
+    `${bold("locus pkg telegram start")}`,
+  ].join("\n");
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function formatUptime(startTimeMs: number): string {
+  const diff = Date.now() - startTimeMs;
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+function formatMemory(bytes: number): string {
+  const mb = bytes / (1024 * 1024);
+  return `${mb.toFixed(1)} MB`;
+}