macroclaw 0.18.0 → 0.20.0

package/README.md

@@ -9,7 +9,7 @@ A lightweight bridge that turns a Telegram chat into a personal AI assistant —
 Macroclaw runs with `dangerouslySkipPermissions` enabled. This is intentional — the bot
 is designed to run in an isolated environment (container or VM) where the workspace is
 the entire world. The single authorized chat ID ensures only one user can interact with
-the bot.
+the bot. See [Docker](#docker) for the recommended containerized setup.
 
 ## Requirements
 
@@ -55,6 +55,8 @@ Session state (Claude session IDs) is stored separately in `~/.macroclaw/session
 
 ## Commands
 
+Run `macroclaw --help` or `macroclaw <command> --help` for the complete reference.
+
 | Command | Description |
 |---------|-------------|
 | `macroclaw start` | Start the bridge |
@@ -80,6 +82,43 @@ Both paths install macroclaw globally via `bun install -g`, register it as a **l
 
 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.
 
+## Docker
+
+Run macroclaw in a Docker container. The workspace is bind-mounted from the host; everything else (settings, Claude auth, sessions) lives in a named Docker volume.
+
+```bash
+# 1. Login to Claude Code (one-time, interactive — use /login inside the session)
+docker compose run --rm -w /workspace --entrypoint claude macroclaw
+
+# 2. Setup macroclaw (one-time, interactive — bot token, chat ID, model)
+docker compose run --rm macroclaw setup --skip-service
+
+# 3. Start the bridge
+docker compose up -d
+```
+
+The `WORKSPACE` env var is pre-set in `docker-compose.yml` so you don't need to configure the workspace path during setup. The `--skip-service` flag skips the service installation prompt (not applicable in Docker).
+
+To build a specific version:
+
+```bash
+docker compose build --build-arg VERSION=0.18.0
+```
+
+To reset everything (remove containers, volumes, and images):
+
+```bash
+docker compose down -v --rmi all
+```
+
+### Development with Docker
+
+Use `Dockerfile.dev` to build from local source instead of the published npm package:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/cli.test.ts

@@ -18,10 +18,11 @@ mock.module("node:child_process", () => ({
 
 const { main } = await import("./cli");
 
-function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<string, unknown>) => Promise<unknown>; installService?: () => Promise<void> }) {
+function createMockWizard(overrides?: { collectSettings?: (defaults?: Record<string, unknown>) => Promise<unknown>; installService?: () => Promise<void>; forceInstallService?: () => Promise<void> }) {
 	return {
 		collectSettings: overrides?.collectSettings ?? mock(async () => ({ botToken: "tok", chatId: "123" })),
 		installService: overrides?.installService ?? mock(async () => {}),
+		forceInstallService: overrides?.forceInstallService ?? mock(async () => {}),
 	} as unknown as SetupWizard;
 }
 
@@ -94,6 +95,23 @@ describe("Cli.setup", () => {
 		expect((wizard.installService as ReturnType<typeof mock>)).toHaveBeenCalled();
 	});
 
+	it("skips service install when --skip-service is set", async () => {
+		const wizard = createMockWizard();
+		const cli = new Cli({ wizard, settings: createMockSettings() });
+		await cli.setup({ skipService: true });
+		expect((wizard.collectSettings as ReturnType<typeof mock>)).toHaveBeenCalled();
+		expect((wizard.installService as ReturnType<typeof mock>)).not.toHaveBeenCalled();
+	});
+
+	it("force installs service when --install-service is set", async () => {
+		const forceInstallService = mock(async () => {});
+		const wizard = { ...createMockWizard(), forceInstallService } as unknown as SetupWizard;
+		const cli = new Cli({ wizard, settings: createMockSettings() });
+		await cli.setup({ installService: true });
+		expect(forceInstallService).toHaveBeenCalled();
+		expect((wizard.installService as ReturnType<typeof mock>)).not.toHaveBeenCalled();
+	});
+
 	it("creates default wizard when none provided", () => {
 		const cli = new Cli({ settings: createMockSettings() });
 		expect(cli).toBeDefined();

package/src/cli.ts

@@ -18,10 +18,15 @@ export class Cli {
 		this.#serviceManager = opts?.systemService ?? new SystemServiceManager();
 	}
 
-	async setup(): Promise<void> {
+	async setup(opts?: { skipService?: boolean; installService?: boolean }): Promise<void> {
 		const defaults = this.#settingsManager.loadRaw() ?? undefined;
 		const settings = await this.#setupWizard.collectSettings(defaults);
 		this.#settingsManager.save(settings);
+		if (opts?.skipService) return;
+		if (opts?.installService) {
+			await this.#setupWizard.forceInstallService();
+			return;
+		}
 		await this.#setupWizard.installService();
 	}
 
@@ -123,7 +128,11 @@ const startCommand = defineCommand({
 
 const setupCommand = defineCommand({
 	meta: { name: "setup", description: "Run the interactive setup wizard" },
-	run: () => defaultCli.setup().catch(handleError),
+	args: {
+		"skip-service": { type: "boolean", description: "Skip the service installation prompt" },
+		"install-service": { type: "boolean", description: "Install as a system service without prompting" },
+	},
+	run: ({ args }) => defaultCli.setup({ skipService: args["skip-service"], installService: args["install-service"] }).catch(handleError),
 });
 
 const claudeCommand = defineCommand({

package/src/cron.test.ts

@@ -254,7 +254,7 @@ describe("CronScheduler", () => {
 
   it("does not write file when no non-recurring jobs fired", () => {
     writeScheduleConfig({
-      jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope", recurring: false }],
+      jobs: [{ name: "recurring", cron: nonMatchingCron(), prompt: "nope" }],
     });
 
     const onJob = makeOnJob();
@@ -318,9 +318,9 @@ describe("missed non-recurring events", () => {
     expect(onJob).not.toHaveBeenCalled();
   });
 
-  it("does not fire non-recurring jobs older than threshold", () => {
+  it("fires non-recurring job missed by more than 5 minutes", () => {
     writeScheduleConfig({
-      jobs: [{ name: "old", cron: minutesAgoCron(10), prompt: "too late", recurring: false }],
+      jobs: [{ name: "old", cron: minutesAgoCron(10), prompt: "still fires", recurring: false }],
     });
 
     const onJob = makeOnJob();
@@ -328,8 +328,13 @@ describe("missed non-recurring events", () => {
     cron.start();
     cron.stop();
 
-    expect(onJob).not.toHaveBeenCalled();
+    expect(onJob).toHaveBeenCalledTimes(1);
+    const call = onJob.mock.calls[0];
+    expect(call[0]).toBe("old");
+    expect(call[1]).toContain("[missed event, should have fired");
+    expect(call[1]).toContain("still fires");
+
     const updated = readScheduleConfig();
-    expect(updated.jobs).toHaveLength(1);
+    expect(updated.jobs).toHaveLength(0);
   });
 });

package/src/cron.ts

@@ -25,7 +25,6 @@ export interface CronSchedulerConfig {
 }
 
 const TICK_INTERVAL = 10_000; // 10 seconds
-const MISSED_THRESHOLD = 300_000; // 5 minutes
 
 export class CronScheduler {
   #lastMinute = -1;
@@ -88,8 +87,8 @@ export class CronScheduler {
           if (job.recurring === false) {
             firedNonRecurring.push(i);
           }
-        } else if (job.recurring === false && diff < MISSED_THRESHOLD) {
-          // Non-recurring job missed (service was down) — fire with missed prefix
+        } else if (job.recurring === false && diff >= 60_000) {
+          // Non-recurring job in the past — fire regardless of how late
           const missedMinutes = Math.round(diff / 60_000);
           const firedAt = prev.toISOString();
           const missedPrompt = `[missed event, should have fired ${missedMinutes} min ago at ${firedAt}] ${job.prompt}`;

package/src/setup.test.ts

@@ -383,6 +383,31 @@ it("installs service when user answers yes", async () => {
     expect(io.written).toContainEqual(expect.stringContaining("Service installation failed: Permission denied"));
   });
 
+  it("forceInstallService installs without prompting", async () => {
+    mockInstall.mockClear();
+    const installer = createMockServiceInstaller();
+    const io = createMockIO([
+      "sk-test-token",  // oauth token (macOS)
+    ]);
+
+    const wizard = new SetupWizard(io, { serviceInstaller: installer, platform: "darwin" });
+    await wizard.forceInstallService();
+
+    expect(mockInstall).toHaveBeenCalled();
+    expect(io.written).toContainEqual(expect.stringContaining("Service installed and started."));
+  });
+
+  it("forceInstallService skips on Linux without prompting", async () => {
+    mockInstall.mockClear();
+    const installer = createMockServiceInstaller();
+    const io = createMockIO([]);
+
+    const wizard = new SetupWizard(io, { serviceInstaller: installer, platform: "linux" });
+    await wizard.forceInstallService();
+
+    expect(mockInstall).toHaveBeenCalled();
+  });
+
   it("fails fast when claude CLI is not found", async () => {
     mockExecSync.mockImplementation(() => { throw new Error("not found"); });
     const io = createMockIO([]);

package/src/setup.ts

@@ -116,29 +116,42 @@ export class SetupWizard {
       const installAnswer = await this.#io.ask("Install as a system service? [Y/n]: ");
       if (installAnswer.toLowerCase() === "n" || installAnswer.toLowerCase() === "no") return;
 
-      let oauthToken: string | undefined;
-      if (this.#platform === "darwin") {
-        this.#io.write("\nmacOS requires a long-lived OAuth token for the service.\n");
-        this.#io.write("Run `claude setup-token` in another terminal, then paste the token here.\n\n");
-        oauthToken = await this.#io.ask("OAuth token: ");
-        if (!oauthToken) {
-          this.#io.write("No token provided. Skipping service installation.\n");
-          return;
-        }
-      }
+      await this.#doInstallService();
+    } finally {
+      this.#io.close();
+    }
+  }
 
-      try {
-        const svc = this.#serviceInstaller ?? new (await import("./system-service")).SystemServiceManager();
-        const logCmd = svc.install(oauthToken);
-        this.#io.write(`Service installed and started. Check logs:\n  ${logCmd}\n`);
-      } catch (err) {
-        this.#io.write(`Service installation failed: ${(err as Error).message}\n`);
-      }
+  async forceInstallService(): Promise<void> {
+    this.#io.open();
+    try {
+      await this.#doInstallService();
     } finally {
       this.#io.close();
     }
   }
 
+  async #doInstallService(): Promise<void> {
+    let oauthToken: string | undefined;
+    if (this.#platform === "darwin") {
+      this.#io.write("\nmacOS requires a long-lived OAuth token for the service.\n");
+      this.#io.write("Run `claude setup-token` in another terminal, then paste the token here.\n\n");
+      oauthToken = await this.#io.ask("OAuth token: ");
+      if (!oauthToken) {
+        this.#io.write("No token provided. Skipping service installation.\n");
+        return;
+      }
+    }
+
+    try {
+      const svc = this.#serviceInstaller ?? new (await import("./system-service")).SystemServiceManager();
+      const logCmd = svc.install(oauthToken);
+      this.#io.write(`Service installed and started. Check logs:\n  ${logCmd}\n`);
+    } catch (err) {
+      this.#io.write(`Service installation failed: ${(err as Error).message}\n`);
+    }
+  }
+
   async #askValidated(field: SetupField, prompt: string, fallback: string): Promise<string> {
     const schema = settingsSchema.shape[field];
     let value = await this.#io.ask(prompt) || fallback;