@inceptionstack/roundhouse 0.2.2 → 0.3.1

package/src/cli/doctor/checks/system.ts

@@ -0,0 +1,86 @@
+/**
+ * System requirement checks: Node, npm, pip3, ffmpeg, ffprobe, whisper
+ */
+
+import type { DoctorCheck, DoctorContext, DoctorCheckResult } from "../types";
+import { which, getVersion, run } from "../shell";
+
+function sysCheck(id: string, name: string, fn: (ctx: DoctorContext) => Promise<DoctorCheckResult>): DoctorCheck {
+  return { id, category: "system", name, run: fn };
+}
+
+export const systemChecks: DoctorCheck[] = [
+  sysCheck("node", "Node.js", async () => {
+    const ver = await getVersion("node");
+    if (!ver) return { id: "node", category: "system", name: "Node.js", status: "fail", summary: "not found on PATH" };
+    const major = parseInt(ver.replace("v", ""));
+    return {
+      id: "node", category: "system", name: "Node.js", summary: ver,
+      status: major >= 20 ? "pass" : "warn",
+      details: major < 20 ? ["Node.js 20+ recommended"] : undefined,
+    };
+  }),
+
+  sysCheck("npm", "npm", async () => {
+    const ver = await getVersion("npm");
+    return {
+      id: "npm", category: "system", name: "npm", summary: ver ?? "not found",
+      status: ver ? "pass" : "fail",
+    };
+  }),
+
+  sysCheck("pip3", "pip3", async () => {
+    const ver = await getVersion("pip3");
+    return {
+      id: "pip3", category: "system", name: "pip3", summary: ver ? ver.split(" ")[1] ?? ver : "not found",
+      status: ver ? "pass" : "warn",
+      details: !ver ? ["Needed for whisper STT auto-install"] : undefined,
+    };
+  }),
+
+  sysCheck("ffmpeg", "ffmpeg", async (ctx) => {
+    const path = await which("ffmpeg");
+    if (path) {
+      const ver = await run("ffmpeg", ["-version"]);
+      const v = ver?.split("\n")[0]?.match(/version\s+([\S]+)/)?.[1] ?? "unknown";
+      return { id: "ffmpeg", category: "system", name: "ffmpeg", status: "pass", summary: v };
+    }
+    return {
+      id: "ffmpeg", category: "system", name: "ffmpeg", status: "warn", summary: "not found",
+      details: ["Needed for voice audio conversion"],
+      fix: { description: "Install ffmpeg", command: "sudo dnf install -y ffmpeg || sudo apt-get install -y ffmpeg" },
+    };
+  }),
+
+  sysCheck("ffprobe", "ffprobe", async () => {
+    const path = await which("ffprobe");
+    return {
+      id: "ffprobe", category: "system", name: "ffprobe", summary: path ? "available" : "not found",
+      status: path ? "pass" : "warn",
+      details: !path ? ["Needed for audio duration checks"] : undefined,
+    };
+  }),
+
+  sysCheck("whisper", "whisper", async (ctx) => {
+    // Check same paths as the whisper provider
+    const { access: acc, constants: c } = await import("node:fs/promises");
+    const { join: j } = await import("node:path");
+    const { homedir: h } = await import("node:os");
+    const paths = [j(h(), ".local", "bin", "whisper"), "/usr/local/bin/whisper", "/usr/bin/whisper"];
+    for (const p of paths) {
+      try { await acc(p, c.X_OK); return { id: "whisper", category: "system", name: "whisper", status: "pass", summary: p }; } catch {}
+    }
+    return {
+      id: "whisper", category: "system", name: "whisper", status: "warn", summary: "not found",
+      details: ["Needed for voice message transcription"],
+      fix: {
+        description: "Install whisper",
+        command: "pip3 install --user openai-whisper",
+        run: async () => {
+          const result = await run("pip3", ["install", "--user", "openai-whisper"], 300000);
+          return result !== null;
+        },
+      },
+    };
+  }),
+];

package/src/cli/doctor/checks/systemd.ts

@@ -0,0 +1,76 @@
+/**
+ * Systemd service checks
+ */
+
+import type { DoctorCheck } from "../types";
+import { run, runLoose } from "../shell";
+
+/** Redact known secret patterns from log lines */
+function redactSecrets(line: string): string {
+  return line
+    .replace(/\b\d{8,}:[A-Za-z0-9_-]{20,}\b/g, "[REDACTED:TOKEN]")
+    .replace(/\b(sk-|pk-|key-|sk-proj-|sk-ant-)[A-Za-z0-9_-]{10,}\b/g, "[REDACTED:KEY]")
+    .replace(/Bearer\s+[A-Za-z0-9._-]{20,}/gi, "Bearer [REDACTED]")
+    .replace(/(https?:\/\/)[^:]+:[^@]+@/g, "$1[REDACTED]@");
+}
+
+export const systemdChecks: DoctorCheck[] = [
+  {
+    id: "systemd-unit", category: "systemd", name: "Service unit",
+    async run(ctx) {
+      const result = await run("systemctl", ["cat", ctx.serviceName]);
+      return {
+        id: "systemd-unit", category: "systemd", name: "Service unit",
+        status: result ? "pass" : "warn",
+        summary: result ? "installed" : "not installed",
+        details: !result ? ["Run: roundhouse install"] : undefined,
+      };
+    },
+  },
+
+  {
+    id: "systemd-active", category: "systemd", name: "Service status",
+    async run(ctx) {
+      // Use runLoose because systemctl exits non-zero for inactive/failed
+      const active = await runLoose("systemctl", ["is-active", ctx.serviceName]);
+      if (active === "active") {
+        return { id: "systemd-active", category: "systemd", name: "Service status", status: "pass", summary: "active" };
+      }
+      if (active === "inactive" || active === "failed") {
+        const enabled = await runLoose("systemctl", ["is-enabled", ctx.serviceName]);
+        return {
+          id: "systemd-active", category: "systemd", name: "Service status",
+          status: "warn", summary: active,
+          details: [
+            active === "failed" ? "Service has failed. Check: roundhouse logs" : "Service is stopped.",
+            ...(enabled === "disabled" ? ["Service is disabled. Run: sudo systemctl enable roundhouse"] : []),
+          ],
+        };
+      }
+      // null = systemctl not available or service not found
+      return {
+        id: "systemd-active", category: "systemd", name: "Service status",
+        status: "info", summary: "not installed or systemctl unavailable",
+      };
+    },
+  },
+
+  {
+    id: "systemd-errors", category: "systemd", name: "Recent errors",
+    async run(ctx) {
+      const logs = await run("journalctl", ["-u", ctx.serviceName, "--since", "1 hour ago", "--no-pager", "-p", "err", "-q"]);
+      if (logs === null) {
+        return { id: "systemd-errors", category: "systemd", name: "Recent errors", status: "info", summary: "cannot read journal" };
+      }
+      const lines = logs.split("\n").filter(Boolean);
+      if (lines.length === 0) {
+        return { id: "systemd-errors", category: "systemd", name: "Recent errors", status: "pass", summary: "none in last hour" };
+      }
+      return {
+        id: "systemd-errors", category: "systemd", name: "Recent errors",
+        status: "warn", summary: `${lines.length} error(s) in last hour`,
+        details: lines.slice(0, 5).map(redactSecrets),
+      };
+    },
+  },
+];

package/src/cli/doctor/output.ts

@@ -0,0 +1,58 @@
+/**
+ * cli/doctor/output.ts — Colored output for doctor
+ */
+
+import type { DoctorCheckResult, DoctorStatus } from "./types";
+
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY === true;
+const c = (code: string, text: string) => useColor ? `${code}${text}\x1b[0m` : text;
+
+const ICONS: Record<DoctorStatus | "fixed", string> = {
+  pass: c("\x1b[32m", "[✓]"),
+  warn: c("\x1b[33m", "[!]"),
+  fail: c("\x1b[31m", "[✗]"),
+  info: c("\x1b[36m", "[-]"),
+  fixed: c("\x1b[32m", "[fixed]"),
+};
+
+export function formatResult(r: DoctorCheckResult, verbose: boolean): string {
+  const icon = r.fixed ? ICONS.fixed : ICONS[r.status];
+  const lines: string[] = [];
+  lines.push(`    ${icon} ${r.name}: ${r.summary}`);
+
+  if ((verbose || r.status === "fail" || r.status === "warn") && r.details?.length) {
+    for (const d of r.details) {
+      lines.push(`        ${d}`);
+    }
+  }
+
+  if (r.fix && !r.fixed && (r.status === "fail" || r.status === "warn")) {
+    if (r.fix.command) {
+      lines.push(`        Fix: ${r.fix.command}`);
+    }
+    lines.push(`        Auto-fix: ${r.fix.run ? "yes (--fix)" : "no"}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function formatSummary(results: DoctorCheckResult[]): string {
+  const counts = { pass: 0, warn: 0, fail: 0, info: 0, fixed: 0 };
+  for (const r of results) {
+    if (r.fixed) counts.fixed++;
+    else counts[r.status]++;
+  }
+
+  const parts: string[] = [];
+  if (counts.fail) parts.push(c("\x1b[31m", `${counts.fail} failure(s)`));
+  if (counts.warn) parts.push(c("\x1b[33m", `${counts.warn} warning(s)`));
+  if (counts.fixed) parts.push(c("\x1b[32m", `${counts.fixed} fixed`));
+  if (counts.pass) parts.push(c("\x1b[32m", `${counts.pass} passed`));
+
+  return `\nDoctor found ${parts.join(", ")}.`;
+}
+
+export function formatCategoryHeader(category: string): string {
+  const name = category.charAt(0).toUpperCase() + category.slice(1);
+  return `\n  ${name}`;
+}

package/src/cli/doctor/runner.ts

@@ -0,0 +1,142 @@
+/**
+ * cli/doctor/runner.ts — Shared doctor execution logic
+ *
+ * Used by both CLI (cmdDoctor) and gateway (/doctor command).
+ */
+
+import type { DoctorCheck, DoctorCheckResult, DoctorContext } from "./types";
+import { CONFIG_PATH, SERVICE_NAME, resolveEnvFilePath, resolveConfigPath } from "../../config";
+import { systemChecks } from "./checks/system";
+import { configChecks } from "./checks/config";
+import { credentialChecks } from "./checks/credentials";
+import { agentChecks } from "./checks/agent";
+import { systemdChecks } from "./checks/systemd";
+import { diskChecks } from "./checks/disk";
+import { sttChecks } from "./checks/stt";
+
+/** Create a DoctorContext with sensible defaults */
+export async function createDoctorContext(overrides: Partial<DoctorContext> = {}): Promise<DoctorContext> {
+  return {
+    fix: false,
+    verbose: false,
+    json: false,
+    configPath: (await resolveConfigPath()).path,
+    envFilePath: await resolveEnvFilePath(),
+    serviceName: SERVICE_NAME,
+    now: new Date(),
+    env: process.env,
+    ...overrides,
+  };
+}
+
+const ALL_CHECKS: DoctorCheck[] = [
+  ...systemChecks,
+  ...configChecks,
+  ...credentialChecks,
+  ...agentChecks,
+  ...sttChecks,
+  ...diskChecks,
+  ...systemdChecks,
+];
+
+/**
+ * Run all doctor checks and return results.
+ * If fix=true, attempts to fix fixable issues.
+ */
+export async function runDoctor(ctx: DoctorContext): Promise<DoctorCheckResult[]> {
+  const results: DoctorCheckResult[] = [];
+
+  for (const check of ALL_CHECKS) {
+    try {
+      const result = await check.run(ctx);
+
+      // Attempt fix if requested
+      if (ctx.fix && result.fix?.run && (result.status === "fail" || result.status === "warn")) {
+        try {
+          const success = await result.fix.run(ctx);
+          if (success) {
+            result.fixed = true;
+            result.status = "pass";
+            result.summary = `${result.summary} → fixed`;
+          }
+        } catch (err) {
+          result.details = [...(result.details ?? []), `Fix failed: ${(err as Error).message}`];
+        }
+      }
+
+      results.push(result);
+    } catch (err) {
+      results.push({
+        id: check.id,
+        category: check.category,
+        name: check.name,
+        status: "fail",
+        summary: `check crashed: ${(err as Error).message}`,
+      });
+    }
+  }
+
+  return results;
+}
+
+/** Format results for Telegram (Markdown) — shows every check */
+export function formatDoctorTelegram(results: DoctorCheckResult[]): string {
+  const counts = { pass: 0, warn: 0, fail: 0, info: 0, fixed: 0 };
+  for (const r of results) {
+    if (r.fixed) counts.fixed++;
+    else counts[r.status]++;
+  }
+
+  const STATUS_ICON: Record<string, string> = {
+    pass: "✅",
+    warn: "⚠️",
+    fail: "❌",
+    info: "ℹ️",
+  };
+
+  const lines: string[] = [
+    "🩺 *Roundhouse Doctor*",
+    "",
+  ];
+
+  // Status summary line
+  const statusParts: string[] = [];
+  if (counts.fail) statusParts.push(`❌ ${counts.fail} fail`);
+  if (counts.warn) statusParts.push(`⚠️ ${counts.warn} warn`);
+  if (counts.fixed) statusParts.push(`🔧 ${counts.fixed} fixed`);
+  statusParts.push(`✅ ${counts.pass} pass`);
+  lines.push(statusParts.join(" · "));
+
+  // Group by category, show every check
+  const categories = [...new Set(results.map((r) => r.category))];
+  for (const cat of categories) {
+    const catResults = results.filter((r) => r.category === cat);
+    lines.push("");
+    lines.push(`*${capitalize(cat)}*`);
+    for (const r of catResults) {
+      const icon = r.fixed ? "🔧" : (STATUS_ICON[r.status] ?? "❓");
+      lines.push(`${icon} ${esc(r.name)}: ${esc(r.summary)}`);
+
+      // Show details for warnings and failures
+      if ((r.status === "fail" || r.status === "warn") && r.details?.length) {
+        for (const d of r.details.slice(0, 3)) {
+          lines.push(`    ${esc(d)}`);
+        }
+      }
+      if (r.fix?.command && (r.status === "fail" || r.status === "warn") && !r.fixed) {
+        lines.push(`    Fix: \`${esc(r.fix.command)}\``);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Escape Telegram Markdown special characters in dynamic text */
+function esc(s: string): string {
+  return s.replace(/([\\\[\]_*`])/g, "\\$1");
+}

package/src/cli/doctor/shell.ts

@@ -0,0 +1,33 @@
+/**
+ * cli/doctor/shell.ts — Shell helpers for doctor checks
+ */
+
+import { execFile } from "node:child_process";
+
+/** Run a command and return stdout, or null on failure */
+export function run(cmd: string, args: string[] = [], timeoutMs = 10000): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout) => {
+      resolve(err ? null : stdout.trim());
+    });
+  });
+}
+
+/** Run a command and return stdout even if exit code is non-zero. Returns null only on spawn failure. */
+export function runLoose(cmd: string, args: string[] = [], timeoutMs = 10000): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(cmd, args, { timeout: timeoutMs }, (_err, stdout, _stderr) => {
+      resolve(stdout?.trim() || null);
+    });
+  });
+}
+
+/** Check if a command exists and return its path or null */
+export async function which(cmd: string): Promise<string | null> {
+  return run("which", [cmd]);
+}
+
+/** Get version from a command (e.g. node --version → "v25.9.0") */
+export async function getVersion(cmd: string, flag = "--version"): Promise<string | null> {
+  return run(cmd, [flag]);
+}

package/src/cli/doctor/types.ts

@@ -0,0 +1,44 @@
+/**
+ * cli/doctor/types.ts — Doctor check types
+ */
+
+export type DoctorStatus = "pass" | "warn" | "fail" | "info";
+
+export type DoctorCategory =
+  | "system" | "config" | "credentials" | "agent" | "sessions"
+  | "stt" | "systemd" | "network" | "disk" | "permissions";
+
+export interface DoctorContext {
+  fix: boolean;
+  verbose: boolean;
+  json: boolean;
+  configPath: string;
+  envFilePath: string;
+  serviceName: string;
+  now: Date;
+  env: NodeJS.ProcessEnv;
+}
+
+export interface DoctorFix {
+  description: string;
+  command?: string;
+  run?: (ctx: DoctorContext) => Promise<boolean>;
+}
+
+export interface DoctorCheckResult {
+  id: string;
+  category: DoctorCategory;
+  name: string;
+  status: DoctorStatus;
+  summary: string;
+  details?: string[];
+  fix?: DoctorFix;
+  fixed?: boolean;
+}
+
+export interface DoctorCheck {
+  id: string;
+  category: DoctorCategory;
+  name: string;
+  run(ctx: DoctorContext): Promise<DoctorCheckResult>;
+}

package/src/cli/doctor.ts

@@ -0,0 +1,48 @@
+/**
+ * cli/doctor.ts — roundhouse doctor CLI command
+ */
+
+import type { DoctorCategory } from "./doctor/types";
+import { formatResult, formatSummary, formatCategoryHeader } from "./doctor/output";
+import { runDoctor, createDoctorContext } from "./doctor/runner";
+
+const CATEGORY_ORDER: DoctorCategory[] = [
+  "system", "config", "credentials", "agent", "stt", "disk", "systemd",
+];
+
+export async function cmdDoctor(args: string[]): Promise<void> {
+  const fix = args.includes("--fix");
+  const verbose = args.includes("--verbose") || args.includes("-v");
+  const json = args.includes("--json");
+
+  const ctx = await createDoctorContext({ fix, verbose, json });
+
+  if (!json) {
+    console.log("\nRoundhouse Doctor\n");
+    if (fix) console.log("  Running with --fix (will attempt to fix issues)\n");
+  }
+
+  const results = await runDoctor(ctx);
+
+  if (json) {
+    const counts = { pass: 0, warn: 0, fail: 0, info: 0, fixed: 0 };
+    for (const r of results) {
+      if (r.fixed) counts.fixed++;
+      else counts[r.status]++;
+    }
+    console.log(JSON.stringify({ ok: counts.fail === 0, summary: counts, results }, null, 2));
+  } else {
+    for (const cat of CATEGORY_ORDER) {
+      const catResults = results.filter((r) => r.category === cat);
+      if (catResults.length === 0) continue;
+      console.log(formatCategoryHeader(cat));
+      for (const r of catResults) {
+        console.log(formatResult(r, verbose));
+      }
+    }
+    console.log(formatSummary(results));
+  }
+
+  const hasFail = results.some((r) => r.status === "fail" && !r.fixed);
+  process.exit(hasFail ? 1 : 0);
+}

package/src/cli/setup-telegram.ts

@@ -0,0 +1,148 @@
+/**
+ * cli/setup-telegram.ts — Telegram API helpers for setup
+ *
+ * Zero-dependency Telegram Bot API client using global fetch.
+ * Token is never logged — redacted in all error messages.
+ */
+
+import { randomBytes } from "node:crypto";
+import { BOT_COMMANDS } from "../commands";
+
+// ── Types ────────────────────────────────────────────
+
+export interface BotInfo {
+  id: number;
+  username: string;
+  firstName: string;
+}
+
+export interface PairResult {
+  chatId: number;
+  userId: number;
+  username: string;
+}
+
+// ── API helper ───────────────────────────────────────
+
+function redactToken(token: string): string {
+  if (token.length < 10) return "***";
+  return token.slice(0, 4) + "..." + token.slice(-4);
+}
+
+async function telegramApi(
+  token: string,
+  method: string,
+  params?: Record<string, unknown>,
+): Promise<any> {
+  const url = `https://api.telegram.org/bot${token}/${method}`;
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: params ? JSON.stringify(params) : undefined,
+  });
+  const data = await resp.json() as any;
+  if (!data.ok) {
+    throw new Error(
+      `Telegram API ${method} failed: ${data.description ?? "unknown error"} (token: ${redactToken(token)})`,
+    );
+  }
+  return data;
+}
+
+// ── Public functions ─────────────────────────────────
+
+/** Validate a bot token and return bot info */
+export async function validateBotToken(token: string): Promise<BotInfo> {
+  const data = await telegramApi(token, "getMe");
+  const r = data.result;
+  return { id: r.id, username: r.username, firstName: r.first_name ?? r.username };
+}
+
+/** Check if a webhook is active (conflicts with polling) */
+export async function checkWebhook(token: string): Promise<string | null> {
+  const data = await telegramApi(token, "getWebhookInfo");
+  const url = data.result?.url;
+  return url && url.length > 0 ? url : null;
+}
+
+/** Register bot commands with Telegram */
+export async function registerBotCommands(token: string): Promise<void> {
+  await telegramApi(token, "setMyCommands", { commands: BOT_COMMANDS });
+}
+
+/** Send a message to a chat */
+export async function sendMessage(token: string, chatId: number, text: string): Promise<void> {
+  await telegramApi(token, "sendMessage", { chat_id: chatId, text });
+}
+
+/**
+ * Pair with a Telegram user — wait for them to send /start <nonce>.
+ * Returns the user's chat ID and numeric user ID, or null on timeout.
+ */
+export async function pairTelegram(
+  token: string,
+  botUsername: string,
+  allowedUsers: string[],
+  timeoutMs = 300_000,
+  log: (msg: string) => void = console.log,
+): Promise<PairResult | null> {
+  const nonce = `rh-${randomBytes(3).toString("hex")}`;
+  const normalizedUsers = allowedUsers.map((u) => u.replace(/^@/, "").toLowerCase());
+
+  // Clear stale updates — advance offset past existing
+  let offset = 0;
+  try {
+    const stale = await telegramApi(token, "getUpdates", { offset: -1, limit: 1 });
+    if (stale.result?.length > 0) {
+      offset = stale.result[stale.result.length - 1].update_id + 1;
+      await telegramApi(token, "getUpdates", { offset, timeout: 0 });
+    }
+  } catch {
+    // If getUpdates fails, start from 0
+  }
+
+  log(`   Open https://t.me/${botUsername} and send: /start ${nonce}`);
+  log(`   Waiting... (Ctrl+C to skip)\n`);
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const pollTimeout = Math.min(10, Math.floor((deadline - Date.now()) / 1000));
+    if (pollTimeout <= 0) break;
+
+    try {
+      const updates = await telegramApi(token, "getUpdates", { offset, timeout: pollTimeout });
+
+      for (const update of updates.result ?? []) {
+        offset = update.update_id + 1;
+        const msg = update.message;
+        if (!msg?.from?.username) continue;
+
+        const fromUser = msg.from.username.toLowerCase();
+        const text = (msg.text ?? "").trim();
+
+        // Accept /start <nonce> from allowed user (exact match)
+        if (normalizedUsers.includes(fromUser) && (text === `/start ${nonce}` || text === nonce)) {
+          // Send welcome
+          await telegramApi(token, "sendMessage", {
+            chat_id: msg.chat.id,
+            text: "✅ Roundhouse paired successfully!\n\nThe gateway is starting up. Send /status once it's ready.",
+          });
+
+          // Advance offset past consumed updates only
+          await telegramApi(token, "getUpdates", { offset, timeout: 0 });
+
+          return {
+            chatId: msg.chat.id,
+            userId: msg.from.id,
+            username: msg.from.username,
+          };
+        }
+      }
+    } catch (err) {
+      // Network hiccup — retry
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+
+  return null;
+}