@inceptionstack/roundhouse 0.5.0 → 0.5.2

package/README.md

@@ -10,7 +10,7 @@ Multiple chat inputs (Telegram, Slack, Discord via [Vercel Chat SDK](https://cha
 ```bash
 npm install -g @inceptionstack/roundhouse
 roundhouse setup --telegram
-roundhouse start  # macOS (foreground) — Linux auto-starts via systemd
+roundhouse start  # Auto-starts via LaunchAgent (macOS) or systemd (Linux)
 ```
 
 ## Architecture
@@ -483,6 +483,7 @@ No other changes needed — the gateway's unified handler covers all platforms.
 | `src/cli/cli.ts` | CLI: start, run, install, tui, update, logs, etc. |
 | `src/cli/env-file.ts` | Shared env file parsing, serialization, and quoting |
 | `src/cli/systemd.ts` | Shared systemd service management (unit generation, install, status) |
+| `src/cli/launchd.ts` | macOS LaunchAgent management (plist generation, install, status) |
 | `src/cli/doctor.ts` | CLI doctor command |
 | `src/cli/doctor/runner.ts` | Shared doctor runner (CLI + gateway) |
 | `src/cli/doctor/checks/` | Individual health check modules |

package/architecture.md

@@ -276,9 +276,10 @@ cli/cli.ts
   ├── agents/registry.ts (getAgentSdkPackage)
   ├── cli/env-file.ts (parseEnvFile, serializeEnvFile, envQuote)
   ├── cli/systemd.ts (resolveExecStart, generateUnit, writeServiceUnit, systemctl, etc.)
+  ├── cli/launchd.ts (generatePlist, installLaunchAgent, uninstallLaunchAgent, isLaunchAgentRunning)
   ├── cli/doctor.ts → cli/doctor/runner.ts → cli/doctor/checks/*
   ├── cli/cron.ts → cron/store.ts, cron/runner.ts, cron/helpers.ts
-  └── cli/setup.ts → cli/env-file.ts, cli/systemd.ts, cli/setup-telegram.ts, bundle.ts
+  └── cli/setup.ts → cli/env-file.ts, cli/systemd.ts, cli/launchd.ts, cli/setup-telegram.ts, bundle.ts
 
 gateway.ts also imports:
   → commands/update.ts → bundle.ts (bundle provisioning)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/cli/cli.ts

@@ -5,6 +5,7 @@
  */
 
 import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
 import { readFile } from "node:fs/promises";
 import { readdirSync, statSync } from "node:fs";
 import { execSync, execFileSync, spawn } from "node:child_process";
@@ -54,6 +55,28 @@ function run(cmd: string, opts?: { silent?: boolean }): string {
 // ── Commands ────────────────────────────────────────
 
 async function cmdStart() {
+  // macOS: check launchd agent
+  if (process.platform === "darwin") {
+    const { isLaunchAgentInstalled, isLaunchAgentRunning, PLIST_PATH } = await import("./launchd.ts");
+    if (isLaunchAgentInstalled()) {
+      if (isLaunchAgentRunning()) {
+        console.log("Roundhouse is already running (LaunchAgent).");
+        console.log("  Logs: ~/.roundhouse/logs/roundhouse.log");
+        console.log("  Stop: roundhouse stop");
+        return;
+      }
+      // Load it
+      try {
+        execFileSync("launchctl", ["load", PLIST_PATH], { stdio: "pipe" });
+        console.log("LaunchAgent started.");
+        console.log("  Logs: ~/.roundhouse/logs/roundhouse.log");
+        return;
+      } catch {
+        // Fall through to foreground
+      }
+    }
+  }
+
   if (isServiceInstalled()) {
     if (isServiceActive()) {
       console.log("Roundhouse is already running.");
@@ -74,7 +97,7 @@ async function cmdStart() {
 
   console.log("No systemd service found. Running in foreground (use Ctrl+C to stop)...");
   if (process.platform !== "darwin") {
-    console.log("  Tip: run 'roundhouse install' to set up the systemd daemon.\n");
+    console.log("  Tip: run 'roundhouse setup --telegram' to install as systemd daemon.\n");
   } else {
     console.log("");
   }
@@ -147,6 +170,16 @@ async function cmdInstall() {
   console.log("  and installs the systemd service — all in one command.\n");
 }
 async function cmdUninstall() {
+  if (process.platform === "darwin") {
+    const { uninstallLaunchAgent, isLaunchAgentInstalled } = await import("./launchd.ts");
+    if (isLaunchAgentInstalled()) {
+      await uninstallLaunchAgent();
+      console.log("  ✅ LaunchAgent removed. Config preserved at:", CONFIG_PATH);
+    } else {
+      console.log("  No LaunchAgent installed.");
+    }
+    return;
+  }
 
   console.log("[roundhouse] Removing systemd daemon...");
   try { systemctl("stop"); } catch {}
@@ -166,19 +199,54 @@ async function cmdUpdate() {
   }
 
   console.log(`[roundhouse] Updated to v${result.latestVersion}`);
-  console.log("\n[roundhouse] Restarting daemon...");
-  try {
-    systemctl("restart", "Updated and restarted.");
-  } catch {
-    console.log("  ⚠️  Daemon not running. Start with: roundhouse install");
+
+  if (process.platform === "darwin") {
+    // Try to restart launchd agent
+    const { isLaunchAgentInstalled, PLIST_PATH } = await import("./launchd.ts");
+    if (isLaunchAgentInstalled()) {
+      try {
+        execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" });
+        execFileSync("launchctl", ["load", PLIST_PATH], { stdio: "pipe" });
+        console.log("\n  ✅ Updated and restarted (LaunchAgent).");
+      } catch {
+        console.log("\n  ✅ Update complete. Restart with: roundhouse start");
+      }
+    } else {
+      console.log("\n  ✅ Update complete. Restart with: roundhouse start");
+    }
+  } else if (!isServiceInstalled()) {
+    console.log("\n  ✅ Update complete. Restart with: roundhouse start");
+  } else {
+    console.log("\n[roundhouse] Restarting daemon...");
+    try {
+      systemctl("restart", "Updated and restarted.");
+    } catch {
+      console.log("  ⚠️  Could not restart. Run: roundhouse start");
+    }
   }
 }
 
 async function cmdStatus() {
+  // macOS: check launchd
+  if (process.platform === "darwin") {
+    const { isLaunchAgentInstalled, isLaunchAgentRunning } = await import("./launchd.ts");
+    if (isLaunchAgentRunning()) {
+      console.log("\n  ✅ Roundhouse is running (LaunchAgent).\n");
+      console.log("  Logs: ~/.roundhouse/logs/roundhouse.log");
+      console.log("  Stop: roundhouse stop\n");
+    } else if (isLaunchAgentInstalled()) {
+      console.log("\n  ⚠️  LaunchAgent installed but not running.\n");
+      console.log("  Start with: roundhouse start\n");
+    } else {
+      console.log("\n  ❌ Roundhouse is not running.\n");
+      console.log("  Start with: roundhouse start\n");
+    }
+    return;
+  }
+
   if (!isServiceActive()) {
     console.log("\n  ❌ Roundhouse is not running.\n");
-    console.log("  Install with: roundhouse install");
-    console.log("  Or start foreground: roundhouse start\n");
+    console.log("  Start with: roundhouse start\n");
     return;
   }
 
@@ -264,15 +332,47 @@ async function cmdStatus() {
   console.log();
 }
 
-function cmdLogs() {
+async function cmdLogs() {
+  if (process.platform === "darwin") {
+    const logPath = resolve(homedir(), ".roundhouse", "logs", "roundhouse.log");
+    const child = spawn("tail", ["-f", "-n", "100", logPath], { stdio: "inherit" });
+    child.on("error", () => console.log("Could not read logs. Check ~/.roundhouse/logs/"));
+    return;
+  }
   const child = spawn("journalctl", ["-u", SERVICE_NAME, "-f", "--no-pager", "-n", "100"], {
     stdio: "inherit",
   });
   child.on("error", () => console.log("Could not read logs. Is the daemon installed?"));
 }
 
-function cmdStop() { systemctl("stop", "Daemon stopped."); }
-function cmdRestart() { systemctl("restart", "Daemon restarted."); }
+async function cmdStop() {
+  if (process.platform === "darwin") {
+    const { isLaunchAgentInstalled, PLIST_PATH } = await import("./launchd.ts");
+    if (isLaunchAgentInstalled()) {
+      try { execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" }); } catch (e: any) { if (!e.message?.includes("Could not find")) console.warn("  (unload warning:", e.message?.split("\n")[0], ")"); }
+      console.log("LaunchAgent stopped.");
+    } else {
+      console.log("No LaunchAgent installed. Nothing to stop.");
+    }
+    return;
+  }
+  systemctl("stop", "Daemon stopped.");
+}
+
+async function cmdRestart() {
+  if (process.platform === "darwin") {
+    const { isLaunchAgentInstalled, PLIST_PATH } = await import("./launchd.ts");
+    if (isLaunchAgentInstalled()) {
+      try { execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" }); } catch {}
+      execFileSync("launchctl", ["load", PLIST_PATH], { stdio: "pipe" });
+      console.log("LaunchAgent restarted.");
+    } else {
+      console.log("No LaunchAgent installed. Run: roundhouse setup --telegram");
+    }
+    return;
+  }
+  systemctl("restart", "Daemon restarted.");
+}
 
 async function cmdConfig() {
   console.log(`Config path: ${CONFIG_PATH}\n`);

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

@@ -47,7 +47,7 @@ export const configChecks: DoctorCheck[] = [
           details: [`${ctx.configPath} does not exist`],
           fix: {
             description: "Create default config",
-            command: `roundhouse install`,
+            command: `roundhouse setup --telegram`,
             run: async () => {
               const configDir = dirname(ctx.configPath);
               await mkdir(configDir, { recursive: true });

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

@@ -23,7 +23,7 @@ export const systemdChecks: DoctorCheck[] = [
         id: "systemd-unit", category: "systemd", name: "Service unit",
         status: result ? "pass" : "warn",
         summary: result ? "installed" : "not installed",
-        details: !result ? ["Run: roundhouse install"] : undefined,
+        details: !result ? ["Run: roundhouse setup --telegram"] : undefined,
       };
     },
   },

package/src/cli/launchd.ts

@@ -0,0 +1,144 @@
+/**
+ * launchd.ts — macOS launchd service management for roundhouse
+ *
+ * Generates and installs a LaunchAgent plist so roundhouse
+ * auto-starts on login and can be managed via launchctl.
+ */
+
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { whichSync } from "./systemd";
+import { ROUNDHOUSE_DIR } from "../config";
+const __dirname = new URL(".", import.meta.url).pathname.replace(/\/$/, "");
+
+const LABEL = "com.inceptionstack.roundhouse";
+const PLIST_DIR = resolve(homedir(), "Library", "LaunchAgents");
+export const PLIST_PATH = resolve(PLIST_DIR, `${LABEL}.plist`);
+/**
+ * Generate a LaunchAgent plist for roundhouse.
+ */
+export function generatePlist(): string {
+  const nodeBin = whichSync("node") || process.execPath;
+  const roundhouseBin = whichSync("roundhouse");
+
+  let programArgs: string[];
+  if (roundhouseBin) {
+    programArgs = [nodeBin, roundhouseBin, "run"];
+  } else {
+    // Fallback: tsx path
+    const tsxBin = whichSync("tsx") || resolve(__dirname, "..", "..", "node_modules", ".bin", "tsx");
+    const cliPath = resolve(__dirname, "cli.ts");
+    programArgs = [nodeBin, tsxBin, cliPath, "run"];
+  }
+
+  const logDir = resolve(ROUNDHOUSE_DIR, "logs");
+  let envSection = "";
+  const envVars: Record<string, string> = {
+    HOME: homedir(),
+    PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+    ROUNDHOUSE_CONFIG: resolve(ROUNDHOUSE_DIR, "gateway.config.json"),
+    NODE_NO_WARNINGS: "1",
+  };
+
+  envSection = Object.entries(envVars)
+    .map(([k, v]) => `      <key>${escapeXml(k)}</key>\n      <string>${escapeXml(v)}</string>`)
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${LABEL}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgs.map(a => `        <string>${escapeXml(a)}</string>`).join("\n")}
+    </array>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+${envSection}
+    </dict>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>${escapeXml(resolve(logDir, "roundhouse.log"))}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(resolve(logDir, "roundhouse.err"))}</string>
+
+    <key>WorkingDirectory</key>
+    <string>${escapeXml(homedir())}</string>
+
+    <key>ThrottleInterval</key>
+    <integer>5</integer>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Install the plist and load the service.
+ */
+export async function installLaunchAgent(): Promise<void> {
+  await mkdir(PLIST_DIR, { recursive: true });
+  await mkdir(resolve(ROUNDHOUSE_DIR, "logs"), { recursive: true });
+
+  const plist = generatePlist();
+  await writeFile(PLIST_PATH, plist, { mode: 0o644 });
+
+  // Unload first if already loaded (ignore errors)
+  try {
+    execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" });
+  } catch {}
+
+  // Load the agent
+  execFileSync("launchctl", ["load", PLIST_PATH], { stdio: "pipe" });
+}
+
+/**
+ * Unload and remove the launch agent.
+ */
+export async function uninstallLaunchAgent(): Promise<void> {
+  try {
+    execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" });
+  } catch {}
+
+  const { unlink } = await import("node:fs/promises");
+  try {
+    await unlink(PLIST_PATH);
+  } catch {}
+}
+
+/**
+ * Check if the launch agent is loaded and running.
+ */
+export function isLaunchAgentRunning(): boolean {
+  try {
+    const output = execFileSync("launchctl", ["list", LABEL], { encoding: "utf8", stdio: "pipe" });
+    return output.includes(LABEL);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if the plist file exists.
+ */
+export function isLaunchAgentInstalled(): boolean {
+  return existsSync(PLIST_PATH);
+}
+
+function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+

package/src/cli/setup.ts

@@ -448,11 +448,26 @@ async function stepValidateToken(opts: SetupOptions): Promise<BotInfo> {
 async function stepStopGateway(): Promise<void> {
   step("④", "Checking for running gateway...");
 
-  if (platform() !== "linux") {
-    ok("Not Linux — skipping service check");
+  if (platform() === "darwin") {
+    try {
+      const { isLaunchAgentRunning, PLIST_PATH } = await import("./launchd.ts");
+      if (isLaunchAgentRunning()) {
+        log("   Stopping existing LaunchAgent...");
+        execFileSync("launchctl", ["unload", PLIST_PATH], { stdio: "pipe" });
+        ok("LaunchAgent stopped");
+      } else {
+        ok("No running gateway");
+      }
+    } catch {
+      ok("No running gateway");
+    }
     return;
   }
 
+  if (platform() !== "linux") {
+    ok("Skipped (not Linux or macOS)");
+    return;
+  }
   if (isServiceActive()) {
     log("   Stopping existing gateway...");
     try {
@@ -835,16 +850,30 @@ async function stepRegisterCommands(opts: SetupOptions): Promise<void> {
 }
 
 async function stepInstallSystemd(opts: SetupOptions): Promise<void> {
-  step("⑩b", "Installing systemd service...");
+  step("⑩b", "Installing service...");
+
+  // macOS: install launchd agent
+  if (platform() === "darwin") {
+    try {
+      const { installLaunchAgent } = await import("./launchd.ts");
+      await installLaunchAgent();
+      ok("LaunchAgent installed and loaded");
+      log("   Logs: ~/.roundhouse/logs/roundhouse.log");
+    } catch (err: any) {
+      warn(`LaunchAgent install failed: ${err.message}`);
+      log("   Run manually: roundhouse start");
+    }
+    return;
+  }
+
 
   if (!opts.systemd) {
     ok("Skipped (--no-systemd)");
     log("   Run manually: roundhouse start");
     return;
   }
-
   if (platform() !== "linux") {
-    warn(`Systemd not available (${platform()})`);
+    warn(`Service install not supported on ${platform()}`);
     log("   Run manually: roundhouse start");
     return;
   }
@@ -853,7 +882,7 @@ async function stepInstallSystemd(opts: SetupOptions): Promise<void> {
   if (!hasSudoAccess()) {
     warn("No passwordless sudo — cannot install systemd service");
     log("   Run manually: roundhouse start");
-    log("   Or install with: sudo roundhouse install");
+    log("   Or install with: roundhouse setup --telegram");
     return;
   }
 
@@ -1135,25 +1164,40 @@ async function runHeadlessTelegramSetup(opts: SetupOptions): Promise<void> {
     await stepRegisterCommands(opts);
     logger.ok("Bot commands registered");
 
+    let serviceInstalled = false;
     // Step 9: Install and start service
     logger.step(9, 9, "service.install", "Installing and starting service");
-    if (!opts.systemd) {
+    if (!opts.systemd && platform() !== "darwin") {
       logger.warn("service.skip", "--no-systemd: service not installed. Start manually: roundhouse start");
     } else {
       await stepInstallSystemd(opts);
-      logger.ok("Service installed and started");
 
-      // Verify service is active
-      try {
-        const { execFileSync } = await import("node:child_process");
-        const state = execFileSync("systemctl", ["is-active", "roundhouse"], { encoding: "utf8" }).trim();
-        if (state === "active") {
-          logger.ok("Service is active");
-        } else {
-          logger.warn("service.state", `Service state: ${state}`);
+      // Verify service is active and set serviceInstalled based on reality
+      if (platform() === "darwin") {
+        try {
+          const { isLaunchAgentRunning } = await import("./launchd.ts");
+          if (isLaunchAgentRunning()) {
+            logger.ok("LaunchAgent is running");
+            serviceInstalled = true;
+          } else {
+            logger.warn("service.state", "LaunchAgent loaded but not yet running");
+          }
+        } catch {
+          logger.warn("service.state", "Could not verify LaunchAgent state");
+        }
+      } else {
+        try {
+          const { execFileSync } = await import("node:child_process");
+          const state = execFileSync("systemctl", ["is-active", "roundhouse"], { encoding: "utf8" }).trim();
+          if (state === "active") {
+            logger.ok("Service is active");
+            serviceInstalled = true;
+          } else {
+            logger.warn("service.state", `Service state: ${state}`);
+          }
+        } catch {
+          logger.warn("service.state", "Could not verify service state");
         }
-      } catch {
-        logger.warn("service.state", "Could not verify service state");
       }
     }
 
@@ -1162,7 +1206,7 @@ async function runHeadlessTelegramSetup(opts: SetupOptions): Promise<void> {
       botUsername: botInfo.username,
       pairingLink,
       pairingStatus: "pending",
-      serviceInstalled: opts.systemd,
+      serviceInstalled,
     });
     log("");
     log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━`);