macroclaw 0.2.0 → 0.4.0

package/README.md

@@ -63,26 +63,22 @@ the bot.
 - [Bun](https://bun.sh/) runtime
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and logged in
 
-## Setup
+## Quick Start
 
 ```bash
-# Run directly (no install needed)
-bunx macroclaw
-
-# Or install globally
-bun install -g macroclaw
-macroclaw
+bunx macroclaw setup
 ```
 
-On first launch, an interactive setup wizard guides you through configuration.
+This runs the setup wizard, which:
+1. Asks for your **Telegram bot token** (from [@BotFather](https://t.me/BotFather))
+2. Starts the bot temporarily so you can send `/chatid` to discover your chat ID
+3. Asks for your **chat ID**, **model** preference, **workspace path**, and optional **OpenAI API key**
+4. Saves settings to `~/.macroclaw/settings.json`
+5. Offers to install as a system service — this installs macroclaw globally (`bun install -g`), registers it as a **launchd** agent (macOS) or **systemd** unit (Linux), and starts the bridge automatically
 
-The setup wizard will:
-1. Ask for your **Telegram bot token** (from [@BotFather](https://t.me/BotFather))
-2. Start the bot temporarily so you can send `/chatid` to discover your chat ID
-3. Ask for your **chat ID**, **model** preference, **workspace path**, and optional **OpenAI API key**
-4. Save settings to `~/.macroclaw/settings.json`
+No separate install step needed — answering yes to the service prompt handles everything.
 
-On subsequent runs, settings are loaded from the file. Environment variables override file settings (see `.env.example`).
+On subsequent runs, settings are pre-filled from the file.
 
 ### Configuration
 
@@ -102,31 +98,41 @@ Env vars take precedence over settings file values. On startup, a masked setting
 
 Session state (Claude session IDs) is stored separately in `~/.macroclaw/sessions.json`.
 
-## Usage
+## Commands
 
-Run inside a tmux session so it survives SSH disconnects:
+| Command | Description |
+|---------|-------------|
+| `macroclaw start` | Start the bridge |
+| `macroclaw setup` | Run the interactive setup wizard |
+| `macroclaw claude` | Open Claude Code CLI in the main session |
+| `macroclaw service install` | Install globally and register as a system service |
+| `macroclaw service uninstall` | Stop and remove the system service |
+| `macroclaw service start` | Start the system service |
+| `macroclaw service stop` | Stop the system service |
+| `macroclaw service update` | Reinstall latest version and restart |
 
-```bash
-tmux new -s macroclaw       # start session
-macroclaw                   # run the bot
+### Running as a service
+
+The recommended path is `bunx macroclaw setup` and answering yes to the service prompt (see [Quick Start](#quick-start)).
 
-# Ctrl+B, D              — detach (bot keeps running)
-# tmux attach -t macroclaw — reattach later
-# tmux kill-session -t macroclaw — stop everything
+If macroclaw is already installed and configured, you can also install the service directly:
+
+```bash
+macroclaw service install
 ```
 
+Both paths install macroclaw globally via `bun install -g`, register it as a **launchd** agent (macOS) or **systemd** unit (Linux) with auto-restart, and start the bridge.
+
+On Linux, the command runs as a normal user. Only the privileged operations (writing to `/etc/systemd/system/`, systemctl commands) are elevated via `sudo`, which prompts for a password when needed. Package installation and path resolution stay in the user's environment.
+
 ## Development
 
 ```bash
 git clone git@github.com:macrosak/macroclaw.git
 cd macroclaw
-cp .env.example .env  # fill in real values
+cp .env.example .env  # fill in real values (see .env.example for available vars)
 bun install --frozen-lockfile
-```
 
-## Development
-
-```bash
 bun run dev    # start with watch mode
 bun test       # run tests (100% coverage enforced)
 bun run claude # open Claude Code CLI in current main session

package/bin/macroclaw.js

@@ -3,4 +3,6 @@ if (typeof Bun === "undefined") {
   console.error("macroclaw requires Bun. Install it: https://bun.sh");
   process.exit(1);
 }
-await import("../src/index.ts");
+const { runMain } = await import("citty");
+const { main } = await import("../src/cli.ts");
+await runMain(main);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",
@@ -17,8 +17,8 @@
     "url": "https://github.com/macrosak/macroclaw"
   },
   "scripts": {
-    "start": "bun run src/index.ts",
-    "dev": "bun run --watch src/index.ts",
+    "start": "bun run src/cli.ts",
+    "dev": "bun run --watch src/cli.ts",
     "check": "tsc --noEmit && biome check && bun test",
     "typecheck": "tsc --noEmit",
     "lint": "biome check",
@@ -28,6 +28,7 @@
     "claude": "set -a && . ./.env && set +a && cd ${WORKSPACE:-~/.macroclaw-workspace} && claude --resume $(node -p \"require('$HOME/.macroclaw/settings.json').sessionId\") --model ${MODEL:-sonnet}"
   },
   "dependencies": {
+    "citty": "^0.2.1",
     "cron-parser": "^5.5.0",
     "grammy": "^1.39.3",
     "openai": "^6.27.0",

package/src/claude.ts

@@ -133,4 +133,4 @@ export class Claude {
       completion,
     };
   }
-}
+}

package/src/cli.test.ts

@@ -0,0 +1,293 @@
+import { describe, expect, it, mock } from "bun:test";
+import { runCommand } from "citty";
+import { Cli, handleError, loadRawSettings, type SetupDeps } from "./cli";
+import type { SystemService } from "./service";
+
+// Only mock ./index — safe since no other test imports it
+const mockStart = mock(async () => {});
+mock.module("./index", () => ({ start: mockStart }));
+
+const { main } = await import("./cli");
+
+function createMockSetupDeps(): SetupDeps & { saved: { settings: unknown; dir: string } | null } {
+	const result: SetupDeps & { saved: { settings: unknown; dir: string } | null } = {
+		saved: null,
+		initLogger: async () => {},
+		saveSettings: () => {},
+		loadRawSettings: () => null,
+		runSetupWizard: async (io) => {
+			await io.ask("test?");
+			io.write("done");
+			io.close?.();
+			return { botToken: "tok", chatId: "123" };
+		},
+		createReadlineInterface: () => ({
+			question: (_q: string, cb: (a: string) => void) => cb("answer"),
+			close: () => {},
+		}),
+		resolveDir: () => "/home/test/.macroclaw",
+	};
+	result.saveSettings = (settings: unknown, dir: string) => { result.saved = { settings, dir }; };
+	return result;
+}
+
+describe("CLI routing", () => {
+	it("requires a subcommand when no args given", async () => {
+		await expect(runCommand(main, { rawArgs: [] })).rejects.toThrow("No command specified");
+	});
+
+	it("routes 'start' subcommand to start", async () => {
+		mockStart.mockClear();
+		await runCommand(main, { rawArgs: ["start"] });
+		expect(mockStart).toHaveBeenCalled();
+	});
+
+	it("has all subcommands defined", () => {
+		expect(main.subCommands).toBeDefined();
+		const subs = main.subCommands as Record<string, unknown>;
+		expect(subs.start).toBeDefined();
+		expect(subs.setup).toBeDefined();
+		expect(subs.claude).toBeDefined();
+		expect(subs.service).toBeDefined();
+	});
+
+	it("has correct meta", () => {
+		expect(main.meta).toEqual({
+			name: "macroclaw",
+			description: "Telegram-to-Claude-Code bridge",
+			version: "0.0.0-dev",
+		});
+	});
+});
+
+describe("Cli.setup", () => {
+	it("runs wizard and saves settings", async () => {
+		const deps = createMockSetupDeps();
+		const cli = new Cli(deps);
+		await cli.setup();
+		expect(deps.saved).toEqual({
+			settings: { botToken: "tok", chatId: "123" },
+			dir: "/home/test/.macroclaw",
+		});
+	});
+
+	it("calls initLogger", async () => {
+		const deps = createMockSetupDeps();
+		const mockInit = mock(async () => {});
+		deps.initLogger = mockInit;
+		const cli = new Cli(deps);
+		await cli.setup();
+		expect(mockInit).toHaveBeenCalled();
+	});
+
+	it("passes existing settings as defaults to wizard", async () => {
+		const existing = { botToken: "old-tok", chatId: "999" };
+		let receivedDefaults: unknown = null;
+		const deps = createMockSetupDeps();
+		deps.loadRawSettings = () => existing;
+		deps.runSetupWizard = async (io, opts) => {
+			receivedDefaults = opts?.defaults;
+			io.close?.();
+			return { botToken: "tok", chatId: "123" };
+		};
+		const cli = new Cli(deps);
+		await cli.setup();
+		expect(receivedDefaults).toEqual(existing);
+	});
+
+	it("closes readline after wizard completes", async () => {
+		const deps = createMockSetupDeps();
+		const mockClose = mock(() => {});
+		deps.createReadlineInterface = () => ({
+			question: (_q: string, cb: (a: string) => void) => cb("answer"),
+			close: mockClose,
+		});
+		const cli = new Cli(deps);
+		await cli.setup();
+		expect(mockClose).toHaveBeenCalled();
+	});
+});
+
+function mockService(overrides?: Partial<SystemService>): SystemService {
+	return {
+		install: mock(() => ""),
+		uninstall: mock(() => {}),
+		start: mock(() => ""),
+		stop: mock(() => {}),
+		update: mock(() => ""),
+		...overrides,
+	};
+}
+
+describe("Cli.service", () => {
+	it("runs install action", () => {
+		const install = mock(() => "tail -f /logs");
+		const cli = new Cli(undefined, mockService({ install }));
+		cli.service("install");
+		expect(install).toHaveBeenCalled();
+	});
+
+	it("runs uninstall action", () => {
+		const uninstall = mock(() => {});
+		const cli = new Cli(undefined, mockService({ uninstall }));
+		cli.service("uninstall");
+		expect(uninstall).toHaveBeenCalled();
+	});
+
+	it("runs start action", () => {
+		const start = mock(() => "tail -f /logs");
+		const cli = new Cli(undefined, mockService({ start }));
+		cli.service("start");
+		expect(start).toHaveBeenCalled();
+	});
+
+	it("runs stop action", () => {
+		const stop = mock(() => {});
+		const cli = new Cli(undefined, mockService({ stop }));
+		cli.service("stop");
+		expect(stop).toHaveBeenCalled();
+	});
+
+	it("runs update action", () => {
+		const update = mock(() => "tail -f /logs");
+		const cli = new Cli(undefined, mockService({ update }));
+		cli.service("update");
+		expect(update).toHaveBeenCalled();
+	});
+
+	it("throws for unknown action", () => {
+		const cli = new Cli(undefined, mockService());
+		expect(() => cli.service("bogus")).toThrow("Unknown service action: bogus");
+	});
+
+	it("throws service errors", () => {
+		const cli = new Cli(undefined, mockService({ install: () => { throw new Error("Settings not found."); } }));
+		expect(() => cli.service("install")).toThrow("Settings not found.");
+	});
+});
+
+describe("Cli.claude", () => {
+	it("builds claude command with session and model", async () => {
+		const fs = await import("node:fs");
+		const dir = `/tmp/macroclaw-test-claude-${Date.now()}`;
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", chatId: "123", model: "opus", workspace: "/tmp" }));
+		fs.writeFileSync(`${dir}/sessions.json`, JSON.stringify({ mainSessionId: "sess-123" }));
+
+		let capturedCmd = "";
+		let capturedOpts: any = {};
+		const exec = mock((cmd: string, opts: object) => { capturedCmd = cmd; capturedOpts = opts; });
+
+		const deps = createMockSetupDeps();
+		deps.resolveDir = () => dir;
+		const cli = new Cli(deps);
+		cli.claude(exec);
+
+		fs.rmSync(dir, { recursive: true });
+
+		expect(capturedCmd).toBe("claude --resume sess-123 --model opus");
+		expect(capturedOpts.cwd).toBe("/tmp");
+		expect(capturedOpts.stdio).toBe("inherit");
+		expect(capturedOpts.env.CLAUDECODE).toBe("");
+	});
+
+	it("omits --resume when no session exists", async () => {
+		const fs = await import("node:fs");
+		const dir = `/tmp/macroclaw-test-claude-${Date.now()}`;
+		fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(`${dir}/settings.json`, JSON.stringify({ botToken: "tok", chatId: "123", model: "sonnet", workspace: "/tmp" }));
+		fs.writeFileSync(`${dir}/sessions.json`, JSON.stringify({}));
+
+		let capturedCmd = "";
+		const exec = mock((cmd: string, _opts: object) => { capturedCmd = cmd; });
+
+		const deps = createMockSetupDeps();
+		deps.resolveDir = () => dir;
+		const cli = new Cli(deps);
+		cli.claude(exec);
+
+		fs.rmSync(dir, { recursive: true });
+
+		expect(capturedCmd).toBe("claude --model sonnet");
+	});
+
+	it("throws when settings are missing", () => {
+		const deps = createMockSetupDeps();
+		deps.resolveDir = () => "/nonexistent/path";
+		const cli = new Cli(deps);
+		expect(() => cli.claude(mock())).toThrow("Settings not found");
+	});
+});
+
+describe("loadRawSettings", () => {
+	it("returns null when file does not exist", () => {
+		expect(loadRawSettings("/nonexistent/path")).toBeNull();
+	});
+
+	it("reads and parses valid settings file", async () => {
+		const dir = await import("node:fs").then(fs => {
+			const d = `/tmp/macroclaw-test-${Date.now()}`;
+			fs.mkdirSync(d, { recursive: true });
+			fs.writeFileSync(`${d}/settings.json`, JSON.stringify({ botToken: "tok", chatId: "123" }));
+			return d;
+		});
+		const result = loadRawSettings(dir);
+		expect(result).toEqual({ botToken: "tok", chatId: "123" });
+		await import("node:fs").then(fs => fs.rmSync(dir, { recursive: true }));
+	});
+
+	it("returns null for invalid JSON", async () => {
+		const dir = await import("node:fs").then(fs => {
+			const d = `/tmp/macroclaw-test-${Date.now()}`;
+			fs.mkdirSync(d, { recursive: true });
+			fs.writeFileSync(`${d}/settings.json`, "not json");
+			return d;
+		});
+		expect(loadRawSettings(dir)).toBeNull();
+		await import("node:fs").then(fs => fs.rmSync(dir, { recursive: true }));
+	});
+
+	it("returns null for non-object JSON", async () => {
+		const dir = await import("node:fs").then(fs => {
+			const d = `/tmp/macroclaw-test-${Date.now()}`;
+			fs.mkdirSync(d, { recursive: true });
+			fs.writeFileSync(`${d}/settings.json`, '"just a string"');
+			return d;
+		});
+		expect(loadRawSettings(dir)).toBeNull();
+		await import("node:fs").then(fs => fs.rmSync(dir, { recursive: true }));
+	});
+});
+
+describe("handleError", () => {
+	it("prints error message and exits", () => {
+		const mockExit = mock((_code?: number) => { throw new Error("exit"); });
+		const mockConsoleError = mock((..._args: unknown[]) => {});
+		const origExit = process.exit;
+		const origError = console.error;
+		process.exit = mockExit as typeof process.exit;
+		console.error = mockConsoleError;
+		try {
+			handleError(new Error("Settings not found."));
+		} catch { /* exit throws */ }
+		process.exit = origExit;
+		console.error = origError;
+		expect(mockConsoleError).toHaveBeenCalledWith("Settings not found.");
+		expect(mockExit).toHaveBeenCalledWith(1);
+	});
+
+	it("handles non-Error values", () => {
+		const mockExit = mock((_code?: number) => { throw new Error("exit"); });
+		const mockConsoleError = mock((..._args: unknown[]) => {});
+		const origExit = process.exit;
+		const origError = console.error;
+		process.exit = mockExit as typeof process.exit;
+		console.error = mockConsoleError;
+		try {
+			handleError("string error");
+		} catch { /* exit throws */ }
+		process.exit = origExit;
+		console.error = origError;
+		expect(mockConsoleError).toHaveBeenCalledWith("string error");
+	});
+});

package/src/cli.ts

@@ -0,0 +1,186 @@
+import {execSync} from "node:child_process";
+import {existsSync, readFileSync} from "node:fs";
+import {join, resolve} from "node:path";
+import {createInterface} from "node:readline";
+import {defineCommand} from "citty";
+import {initLogger} from "./logger";
+import {ServiceManager, type SystemService} from "./service";
+import {loadSessions} from "./sessions";
+import {loadSettings, saveSettings} from "./settings";
+import {runSetupWizard} from "./setup";
+
+export interface SetupDeps {
+	initLogger: () => Promise<void>;
+	saveSettings: (settings: unknown, dir: string) => void;
+	loadRawSettings: (dir: string) => Record<string, unknown> | null;
+	runSetupWizard: (io: { ask: (q: string) => Promise<string>; write: (m: string) => void; close?: () => void }, opts?: { defaults?: Record<string, unknown>; onSettingsReady?: (settings: unknown) => void }) => Promise<unknown>;
+	createReadlineInterface: () => { question: (q: string, cb: (a: string) => void) => void; close: () => void };
+	resolveDir: () => string;
+}
+
+export function loadRawSettings(dir: string): Record<string, unknown> | null {
+	const path = join(dir, "settings.json");
+	if (!existsSync(path)) return null;
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8"));
+		return typeof raw === "object" && raw !== null ? raw : null;
+	} catch {
+		return null;
+	}
+}
+
+function defaultSetupDeps(): SetupDeps {
+	return {
+		initLogger,
+		saveSettings: saveSettings as (settings: unknown, dir: string) => void,
+		loadRawSettings,
+		runSetupWizard: runSetupWizard as SetupDeps["runSetupWizard"],
+		createReadlineInterface: () => createInterface({ input: process.stdin, output: process.stdout }),
+		resolveDir: () => resolve(process.env.HOME || "~", ".macroclaw"),
+	};
+}
+
+function defaultSystemService(): SystemService {
+	return new ServiceManager();
+}
+
+export class Cli {
+	readonly #setupDeps: SetupDeps;
+	readonly #systemService: SystemService;
+
+	constructor(setupDeps?: Partial<SetupDeps>, systemService?: SystemService) {
+		this.#setupDeps = { ...defaultSetupDeps(), ...setupDeps };
+		this.#systemService = systemService ?? defaultSystemService();
+	}
+
+	async setup(): Promise<void> {
+		await this.#setupDeps.initLogger();
+		const rl = this.#setupDeps.createReadlineInterface();
+		const io = {
+			ask: (question: string): Promise<string> =>
+				new Promise((res) => rl.question(question, (answer: string) => res(answer.trim()))),
+			write: (msg: string) => process.stdout.write(msg),
+			close: () => rl.close(),
+		};
+		const dir = this.#setupDeps.resolveDir();
+		const defaults = this.#setupDeps.loadRawSettings(dir) ?? undefined;
+		const settings = await this.#setupDeps.runSetupWizard(io, {
+			defaults,
+			onSettingsReady: (s) => this.#setupDeps.saveSettings(s, dir),
+		});
+		this.#setupDeps.saveSettings(settings, dir);
+	}
+
+	claude(exec: (cmd: string, opts: object) => void = (cmd, opts) => execSync(cmd, opts)): void {
+		const dir = this.#setupDeps.resolveDir();
+		const settings = loadSettings(dir);
+		if (!settings) throw new Error("Settings not found. Run `macroclaw setup` first.");
+		const sessions = loadSessions(dir);
+		const args = ["claude"];
+		if (sessions.mainSessionId) args.push("--resume", sessions.mainSessionId);
+		args.push("--model", settings.model);
+		exec(args.join(" "), { cwd: settings.workspace, stdio: "inherit", env: { ...process.env, CLAUDECODE: "" } });
+	}
+
+	service(action: string, token?: string): void {
+		switch (action) {
+			case "install": {
+				const logCmd = this.#systemService.install(token);
+				console.log(`Service installed and started. Check logs:\n  ${logCmd}`);
+				break;
+			}
+			case "uninstall":
+				this.#systemService.uninstall();
+				console.log("Service uninstalled.");
+				break;
+			case "start": {
+				const logCmd = this.#systemService.start();
+				console.log(`Service started. Check logs:\n  ${logCmd}`);
+				break;
+			}
+			case "stop":
+				this.#systemService.stop();
+				console.log("Service stopped.");
+				break;
+			case "update": {
+				const logCmd = this.#systemService.update();
+				console.log(`Service updated. Check logs:\n  ${logCmd}`);
+				break;
+			}
+			default:
+				throw new Error(`Unknown service action: ${action}`);
+		}
+	}
+}
+
+export function handleError(err: unknown): never {
+	console.error(err instanceof Error ? err.message : String(err));
+	process.exit(1);
+}
+
+async function runStart(): Promise<void> {
+	const { start } = await import("./index");
+	await start();
+}
+
+const defaultCli = new Cli();
+
+const startCommand = defineCommand({
+	meta: { name: "start", description: "Start the macroclaw bridge" },
+	run: () => runStart().catch(handleError),
+});
+
+const setupCommand = defineCommand({
+	meta: { name: "setup", description: "Run the interactive setup wizard" },
+	run: () => defaultCli.setup().catch(handleError),
+});
+
+const claudeCommand = defineCommand({
+	meta: { name: "claude", description: "Open Claude Code CLI in the main session" },
+	run: () => { try { defaultCli.claude(); } catch (err) { handleError(err); } },
+});
+
+const serviceInstallCommand = defineCommand({
+	meta: { name: "install", description: "Install and start macroclaw as a system service" },
+	args: {
+		token: { type: "string", description: "Claude OAuth token from `claude setup-token` (required on macOS)" },
+	},
+	run: ({ args }) => { try { defaultCli.service("install", args.token); } catch (err) { handleError(err); } },
+});
+
+const serviceUninstallCommand = defineCommand({
+	meta: { name: "uninstall", description: "Stop and remove the system service" },
+	run: () => { try { defaultCli.service("uninstall"); } catch (err) { handleError(err); } },
+});
+
+const serviceStartCommand = defineCommand({
+	meta: { name: "start", description: "Start the system service" },
+	run: () => { try { defaultCli.service("start"); } catch (err) { handleError(err); } },
+});
+
+const serviceStopCommand = defineCommand({
+	meta: { name: "stop", description: "Stop the system service" },
+	run: () => { try { defaultCli.service("stop"); } catch (err) { handleError(err); } },
+});
+
+const serviceUpdateCommand = defineCommand({
+	meta: { name: "update", description: "Reinstall latest version and restart the service" },
+	run: () => { try { defaultCli.service("update"); } catch (err) { handleError(err); } },
+});
+
+const serviceCommand = defineCommand({
+	meta: { name: "service", description: "Manage macroclaw system service" },
+	subCommands: {
+		install: serviceInstallCommand,
+		uninstall: serviceUninstallCommand,
+		start: serviceStartCommand,
+		stop: serviceStopCommand,
+		update: serviceUpdateCommand,
+	},
+});
+
+export const main = defineCommand({
+	meta: { name: "macroclaw", description: "Telegram-to-Claude-Code bridge", version: "0.0.0-dev" },
+	subCommands: { start: startCommand, setup: setupCommand, claude: claudeCommand, service: serviceCommand },
+});
+