macroclaw 0.3.0 → 0.5.0

package/README.md

@@ -5,52 +5,6 @@ Telegram-to-Claude-Code bridge. Bun + Grammy.
 Uses the Claude Code CLI (`claude -p`) rather than the Agent SDK to avoid any possible
 ToS issues with using a Claude subscription programmatically.
 
-## Vision
-
-Macroclaw is a minimal bridge between Telegram and Claude Code. It handles the parts
-that a Claude session can't: receiving messages, managing processes, scheduling tasks,
-and delivering responses.
-
-Everything else — personality, memory, skills, behavior, conventions — lives in the
-workspace. The platform stays small so the workspace can be infinitely customizable
-without touching platform code.
-
-## Architecture
-
-Macroclaw follows a **thin platform, rich workspace** design:
-
-**Platform** (this repo) — the runtime bridge:
-- Telegram bot connection and message routing
-- Claude Code process orchestration and session management
-- Background agent spawning and lifecycle
-- Cron scheduler (reads job definitions from workspace)
-- Message queue (FIFO, serial processing)
-- Timeout management and auto-retry
-
-**Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
-- [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
-- [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
-- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
-- [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
-
-### Where does a new feature belong?
-
-**Platform** when it:
-- Requires external API access (Telegram, future integrations)
-- Manages processes (spawning Claude, background agents, timeouts)
-- Operates outside Claude sessions (cron scheduling, message queuing)
-- Is a security boundary (chat authorization, workspace isolation)
-- Is bootstrap logic (workspace initialization)
-
-**Workspace** when it:
-- Defines agent behavior or personality
-- Is a convention Claude can follow via instructions
-- Can be implemented as a skill
-- Is data that Claude reads/writes (memory, tasks, cron definitions)
-- Is a formatting or response style rule
-
-> **Litmus test:** Could this feature work if you just wrote instructions in CLAUDE.md and/or created a skill? If yes → workspace. If no → platform.
-
 ## Security Model
 
 Macroclaw runs with `dangerouslySkipPermissions` enabled. This is intentional — the bot
@@ -63,26 +17,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,36 +52,92 @@ 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
 ```
 
+## Vision
+
+Macroclaw is a minimal bridge between Telegram and Claude Code. It handles the parts
+that a Claude session can't: receiving messages, managing processes, scheduling tasks,
+and delivering responses.
+
+Everything else — personality, memory, skills, behavior, conventions — lives in the
+workspace. The platform stays small so the workspace can be infinitely customizable
+without touching platform code.
+
+## Architecture
+
+Macroclaw follows a **thin platform, rich workspace** design:
+
+**Platform** (this repo) — the runtime bridge:
+- Telegram bot connection and message routing
+- Claude Code process orchestration and session management
+- Background agent spawning and lifecycle
+- Cron scheduler (reads job definitions from workspace)
+- Message queue (FIFO, serial processing)
+- Timeout management and auto-retry
+
+**Workspace** — the intelligence layer, initialized from [`workspace-template/`](workspace-template/):
+- [`CLAUDE.md`](workspace-template/CLAUDE.md) — agent behavior, conventions, response style
+- [`.claude/skills/`](workspace-template/.claude/skills/) — teachable capabilities
+- [`.macroclaw/cron.json`](workspace-template/.macroclaw/cron.json) — scheduled job definitions
+- [`MEMORY.md`](workspace-template/MEMORY.md) — persistent memory
+
+### Where does a new feature belong?
+
+**Platform** when it:
+- Requires external API access (Telegram, future integrations)
+- Manages processes (spawning Claude, background agents, timeouts)
+- Operates outside Claude sessions (cron scheduling, message queuing)
+- Is a security boundary (chat authorization, workspace isolation)
+- Is bootstrap logic (workspace initialization)
+
+**Workspace** when it:
+- Defines agent behavior or personality
+- Is a convention Claude can follow via instructions
+- Can be implemented as a skill
+- Is data that Claude reads/writes (memory, tasks, cron definitions)
+- Is a formatting or response style rule
+
+> **Litmus test:** Could this feature work if you just wrote instructions in CLAUDE.md and/or created a skill? If yes → workspace. If no → platform.
+
 ## License
 
 MIT

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.3.0",
+  "version": "0.5.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");
+	});
+});