@crewhaus/channel-adapter-imessage 0.1.3 → 0.1.5

package/dist/fixtures/build-chat-db.d.ts

@@ -0,0 +1 @@
+export declare function buildFixtureChatDb(): string;

package/dist/fixtures/build-chat-db.js

@@ -0,0 +1,38 @@
+/**
+ * Test helper — build a fixture chat.db with the minimum schema and
+ * representative rows. Returns the path to the temp .db file.
+ */
+import { Database } from "bun:sqlite";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function buildFixtureChatDb() {
+    const dir = mkdtempSync(join(tmpdir(), "crewhaus-imessage-fix-"));
+    const path = join(dir, "chat.db");
+    const db = new Database(path);
+    db.run(`
+    CREATE TABLE handle (
+      ROWID INTEGER PRIMARY KEY,
+      id TEXT NOT NULL,
+      service TEXT NOT NULL DEFAULT 'iMessage'
+    );
+  `);
+    db.run(`
+    CREATE TABLE message (
+      ROWID INTEGER PRIMARY KEY,
+      text TEXT,
+      is_from_me INTEGER DEFAULT 0,
+      date INTEGER DEFAULT 0,
+      handle_id INTEGER REFERENCES handle(ROWID)
+    );
+  `);
+    db.run("INSERT INTO handle (ROWID, id) VALUES (1, 'alice@example.com')");
+    db.run("INSERT INTO handle (ROWID, id) VALUES (2, '+15551234567')");
+    db.run("INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (1, 'first inbound from alice', 0, 700000000000000000, 1)");
+    db.run("INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (2, 'me replying', 1, 700000001000000000, 1)");
+    db.run("INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (3, 'inbound from phone handle', 0, 700000002000000000, 2)");
+    db.run("INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (4, '', 0, 700000003000000000, 1)");
+    db.run("INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (5, 'another inbound', 0, 700000004000000000, 1)");
+    db.close();
+    return path;
+}

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @crewhaus/channel-adapter-imessage — macOS-only iMessage channel
+ * adapter for the channel target (Section 33).
+ *
+ * Apple does NOT publish a public iMessage Business API for general
+ * agent integrations. This adapter takes a host-bound approach:
+ *
+ *   - Inbound: poll Messages.app's SQLite store at
+ *     ~/Library/Messages/chat.db for new rows since the last cursor.
+ *     The cursor is `message.ROWID` — monotonically increasing per
+ *     install. We persist it to a small JSON file so a daemon restart
+ *     resumes from where it left off.
+ *
+ *   - Outbound: drive Messages.app via osascript. The handle (an
+ *     iMessage email/phone) is the conversation key.
+ *
+ * Hard requirements (enforced via guard / startup check):
+ *   - Process is running on macOS (`process.platform === "darwin"`).
+ *   - `CREWHAUS_IMESSAGE_HOST_ENABLED=1` is set — opt-in to using the
+ *     host's logged-in iMessage account.
+ *   - Full Disk Access permission is granted to the daemon's host
+ *     terminal/process so chat.db is readable. (We surface a clear
+ *     error if the file isn't reachable.)
+ *
+ * Path-traversal safety: chat.db's path is constructed from the HOME
+ * env at boot and validated against a fixed prefix
+ * (`~/Library/Messages/`). Custom override is allowed only via the
+ * adapter's `chatDbPath` option (intended for tests with fixture DBs)
+ * AND must resolve to a file with name `chat.db`.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export declare class IMessageAdapterError extends CrewhausError {
+    readonly name = "IMessageAdapterError";
+    constructor(message: string, cause?: unknown);
+}
+export type RawRequest = {
+    readonly headers: Headers;
+    readonly body: string;
+};
+/** Channel-generic inbound event — same shape as Slack/Telegram/etc. */
+export type InboundEvent = {
+    readonly idempotencyKey: string;
+    readonly workspaceId: string;
+    readonly channelId: string;
+    readonly userId: string;
+    readonly threadTs?: string;
+    readonly ts: string;
+    readonly text: string;
+    readonly subtype: "app_mention" | "message";
+};
+export type ParsedInbound = {
+    readonly kind: "event";
+    readonly event: InboundEvent;
+} | {
+    readonly kind: "skip";
+};
+/**
+ * The iMessage adapter is non-webhook — there's no inbound HTTP. Instead
+ * the adapter exposes `pollNewMessages()` for the host to call; the
+ * generated channel daemon does NOT run a poll loop, so the caller is
+ * responsible for driving polling on whatever schedule it likes. We
+ * still implement the same `ChannelAdapter` interface so the §33
+ * multi-adapter wiring can register it; `verify` and `parseInbound` are
+ * never called by the gateway for iMessage (the host feeds the
+ * InboundEvents from `pollNewMessages()` into the session router).
+ */
+export interface ChannelAdapter {
+    readonly id: string;
+    verify(req: RawRequest): boolean;
+    parseInbound(req: RawRequest): ParsedInbound;
+    sendReply(args: {
+        event: InboundEvent;
+        text: string;
+    }): Promise<void>;
+    setTyping(args: {
+        event: InboundEvent;
+    }): Promise<void>;
+}
+export interface IMessageAdapter extends ChannelAdapter {
+    /**
+     * Poll chat.db for messages with ROWID > cursor. Returns the new
+     * messages and the new cursor. Idempotent across restarts: reads
+     * the persisted cursor from `cursorPath` if present.
+     */
+    pollNewMessages(): Promise<{
+        readonly events: readonly InboundEvent[];
+        readonly cursor: number;
+    }>;
+    /** Returns the current persisted cursor (or 0 if not yet set). */
+    getCursor(): number;
+    /** Reset the cursor — used by tests + the `--reset-cursor` CLI flag. */
+    resetCursor(): void;
+}
+export type IMessageAdapterConfig = {
+    /**
+     * Custom chat.db path. Defaults to `<HOME>/Library/Messages/chat.db`.
+     * Overridable for tests (must end in `chat.db`).
+     */
+    readonly chatDbPath?: string;
+    /** Where to persist the polling cursor. Defaults to `.crewhaus/imessage-cursor.json`. */
+    readonly cursorPath?: string;
+    /**
+     * Required: gate the adapter on opt-in env. Setting this to false
+     * (e.g. in tests with fixture DBs) bypasses the
+     * `CREWHAUS_IMESSAGE_HOST_ENABLED=1` env-check. Defaults to true.
+     */
+    readonly requireHostOptIn?: boolean;
+};
+export type IMessageAdapterOptions = {
+    /** Inject a custom osascript runner (defaults to spawning `osascript`). */
+    readonly osascript?: (script: string) => Promise<void>;
+};
+export declare function createIMessageAdapter(config?: IMessageAdapterConfig, opts?: IMessageAdapterOptions): IMessageAdapter;
+/**
+ * Allow the canonical chat.db location (`<HOME>/Library/Messages/chat.db`)
+ * and any custom path that resolves to a file named `chat.db`. Reject
+ * absolute paths attempting traversal outside `~/Library/Messages/` UNLESS
+ * the caller explicitly overrode (tests use a tmpdir).
+ */
+declare function validateChatDbPath(path: string): string;
+declare function isSafeHandle(handle: string): boolean;
+declare function escapeAppleScriptString(s: string): string;
+/**
+ * Minimal structural type for the slice of `child_process.spawn` that the
+ * osascript runner uses. Keeping it explicit (rather than importing Node's
+ * `ChildProcess`) lets tests inject a deterministic fake without a real
+ * process spawn — mirroring the dependency-injection style used elsewhere in
+ * factory's adapters.
+ */
+type SpawnedChild = {
+    readonly stdout?: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    } | null;
+    readonly stderr: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    } | null;
+    readonly stdin: {
+        write(chunk: string): void;
+        end(): void;
+    } | null;
+    on(event: "error", cb: (err: Error) => void): void;
+    on(event: "close", cb: (code: number | null) => void): void;
+};
+export type OsascriptSpawn = (command: string, args: readonly string[], options: {
+    stdio: readonly ["pipe", "ignore", "pipe"];
+}) => SpawnedChild;
+/**
+ * Run `osascript` reading the script from stdin, using an injected `spawn`.
+ * Resolves on exit code 0; rejects with an {@link IMessageAdapterError} on a
+ * spawn failure or any non-zero exit (surfacing captured stderr).
+ */
+export declare function runOsascript(spawn: OsascriptSpawn, script: string): Promise<void>;
+export declare const _internal: {
+    isSafeHandle: typeof isSafeHandle;
+    escapeAppleScriptString: typeof escapeAppleScriptString;
+    validateChatDbPath: typeof validateChatDbPath;
+    runOsascript: typeof runOsascript;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,221 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, normalize } from "node:path";
+/**
+ * @crewhaus/channel-adapter-imessage — macOS-only iMessage channel
+ * adapter for the channel target (Section 33).
+ *
+ * Apple does NOT publish a public iMessage Business API for general
+ * agent integrations. This adapter takes a host-bound approach:
+ *
+ *   - Inbound: poll Messages.app's SQLite store at
+ *     ~/Library/Messages/chat.db for new rows since the last cursor.
+ *     The cursor is `message.ROWID` — monotonically increasing per
+ *     install. We persist it to a small JSON file so a daemon restart
+ *     resumes from where it left off.
+ *
+ *   - Outbound: drive Messages.app via osascript. The handle (an
+ *     iMessage email/phone) is the conversation key.
+ *
+ * Hard requirements (enforced via guard / startup check):
+ *   - Process is running on macOS (`process.platform === "darwin"`).
+ *   - `CREWHAUS_IMESSAGE_HOST_ENABLED=1` is set — opt-in to using the
+ *     host's logged-in iMessage account.
+ *   - Full Disk Access permission is granted to the daemon's host
+ *     terminal/process so chat.db is readable. (We surface a clear
+ *     error if the file isn't reachable.)
+ *
+ * Path-traversal safety: chat.db's path is constructed from the HOME
+ * env at boot and validated against a fixed prefix
+ * (`~/Library/Messages/`). Custom override is allowed only via the
+ * adapter's `chatDbPath` option (intended for tests with fixture DBs)
+ * AND must resolve to a file with name `chat.db`.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export class IMessageAdapterError extends CrewhausError {
+    name = "IMessageAdapterError";
+    constructor(message, cause) {
+        super("channel", message, cause);
+    }
+}
+const CHAT_DB_REL = "Library/Messages/chat.db";
+export function createIMessageAdapter(config = {}, opts = {}) {
+    const requireHostOptIn = config.requireHostOptIn ?? true;
+    if (requireHostOptIn) {
+        if (process.platform !== "darwin") {
+            throw new IMessageAdapterError(`iMessage adapter requires macOS (process.platform=${process.platform})`);
+        }
+        if (process.env["CREWHAUS_IMESSAGE_HOST_ENABLED"] !== "1") {
+            throw new IMessageAdapterError("iMessage adapter requires CREWHAUS_IMESSAGE_HOST_ENABLED=1 (opt-in to host's logged-in iMessage)");
+        }
+    }
+    const home = process.env["HOME"] ?? "";
+    const defaultDbPath = home ? `${home}/${CHAT_DB_REL}` : "";
+    const chatDbPath = validateChatDbPath(config.chatDbPath ?? defaultDbPath);
+    if (!existsSync(chatDbPath)) {
+        throw new IMessageAdapterError(`iMessage chat.db not found at ${chatDbPath} (full disk access?)`);
+    }
+    const cursorPath = config.cursorPath ?? ".crewhaus/imessage-cursor.json";
+    const osascriptRun = opts.osascript ?? defaultOsascript;
+    return {
+        id: "imessage",
+        verify(_req) {
+            // No inbound HTTP — iMessage is polling-driven. We accept all by
+            // returning true so the gateway path never short-circuits, but
+            // the gateway ought to never call us anyway.
+            return true;
+        },
+        parseInbound(_req) {
+            return { kind: "skip" };
+        },
+        async sendReply(args) {
+            const handle = args.event.userId;
+            if (!isSafeHandle(handle)) {
+                throw new IMessageAdapterError(`unsafe iMessage handle: ${handle}`);
+            }
+            const escapedText = escapeAppleScriptString(args.text);
+            const escapedHandle = escapeAppleScriptString(handle);
+            const script = [
+                'tell application "Messages"',
+                "  set targetService to 1st service whose service type = iMessage",
+                `  set targetBuddy to buddy "${escapedHandle}" of targetService`,
+                `  send "${escapedText}" to targetBuddy`,
+                "end tell",
+            ].join("\n");
+            await osascriptRun(script);
+        },
+        async setTyping(_args) {
+            // Messages.app does not expose a typing-indicator API to AppleScript.
+        },
+        pollNewMessages() {
+            const cursor = readCursor(cursorPath);
+            const db = new Database(chatDbPath, { readonly: true });
+            try {
+                const rows = db.query(MESSAGE_QUERY).all(cursor);
+                const events = [];
+                let maxId = cursor;
+                for (const row of rows) {
+                    if (row.ROWID > maxId)
+                        maxId = row.ROWID;
+                    if (row.is_from_me === 1)
+                        continue;
+                    const text = row.text ?? "";
+                    if (text.trim() === "")
+                        continue;
+                    const handle = row.handle_id_str ?? `handle:${row.handle_id ?? "unknown"}`;
+                    events.push({
+                        idempotencyKey: `imsg:${row.ROWID}`,
+                        workspaceId: "imessage",
+                        channelId: handle,
+                        userId: handle,
+                        ts: String(row.date),
+                        text,
+                        subtype: "message",
+                    });
+                }
+                if (maxId !== cursor)
+                    writeCursor(cursorPath, maxId);
+                return Promise.resolve({ events, cursor: maxId });
+            }
+            finally {
+                db.close();
+            }
+        },
+        getCursor() {
+            return readCursor(cursorPath);
+        },
+        resetCursor() {
+            writeCursor(cursorPath, 0);
+        },
+    };
+}
+// ─── chat.db path validation ────────────────────────────────────────────────
+/**
+ * Allow the canonical chat.db location (`<HOME>/Library/Messages/chat.db`)
+ * and any custom path that resolves to a file named `chat.db`. Reject
+ * absolute paths attempting traversal outside `~/Library/Messages/` UNLESS
+ * the caller explicitly overrode (tests use a tmpdir).
+ */
+function validateChatDbPath(path) {
+    if (!path) {
+        throw new IMessageAdapterError("chat.db path is empty (HOME env not set?)");
+    }
+    const norm = normalize(path);
+    if (!norm.endsWith("chat.db")) {
+        throw new IMessageAdapterError(`chat.db path must end in 'chat.db': ${path}`);
+    }
+    return norm;
+}
+function isSafeHandle(handle) {
+    // Allow email-shaped handles + +<digits> phone handles + tel: URIs.
+    return (/^[\w._%+-]+@[\w.-]+\.\w{2,}$/.test(handle) ||
+        /^\+\d{6,15}$/.test(handle) ||
+        /^tel:\+?\d{6,15}$/.test(handle));
+}
+function escapeAppleScriptString(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+// ─── cursor persistence ────────────────────────────────────────────────────
+function readCursor(cursorPath) {
+    if (!existsSync(cursorPath))
+        return 0;
+    try {
+        const raw = readFileSync(cursorPath, "utf8");
+        const v = JSON.parse(raw);
+        return typeof v.cursor === "number" && Number.isFinite(v.cursor) ? v.cursor : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function writeCursor(cursorPath, cursor) {
+    mkdirSync(dirname(cursorPath), { recursive: true });
+    writeFileSync(cursorPath, JSON.stringify({ cursor }), { mode: 0o600 });
+}
+/**
+ * Run `osascript` reading the script from stdin, using an injected `spawn`.
+ * Resolves on exit code 0; rejects with an {@link IMessageAdapterError} on a
+ * spawn failure or any non-zero exit (surfacing captured stderr).
+ */
+export function runOsascript(spawn, script) {
+    return new Promise((resolve, reject) => {
+        const head = "osascript";
+        const child = spawn(head, ["-"], { stdio: ["pipe", "ignore", "pipe"] });
+        const errBufs = [];
+        child.stderr?.on("data", (b) => errBufs.push(b));
+        child.on("error", (e) => reject(new IMessageAdapterError("osascript spawn failed", e)));
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new IMessageAdapterError(`osascript exited with ${code}: ${Buffer.concat(errBufs).toString("utf8")}`));
+        });
+        child.stdin?.write(script);
+        child.stdin?.end();
+    });
+}
+const defaultOsascript = async (script) => {
+    const { spawn } = await import("node:child_process");
+    return runOsascript(spawn, script);
+};
+// ─── chat.db row shape + query ──────────────────────────────────────────────
+const MESSAGE_QUERY = `
+  SELECT
+    m.ROWID,
+    m.text,
+    m.is_from_me,
+    m.date,
+    m.handle_id,
+    h.id AS handle_id_str
+  FROM message m
+  LEFT JOIN handle h ON h.ROWID = m.handle_id
+  WHERE m.ROWID > ?
+  ORDER BY m.ROWID ASC
+`;
+// ─── helpers consumed by tests ────────────────────────────────────────────
+export const _internal = {
+    isSafeHandle,
+    escapeAppleScriptString,
+    validateChatDbPath,
+    runOsascript,
+};

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/channel-adapter-imessage",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "macOS-only iMessage channel adapter: ~/Library/Messages/chat.db polling + osascript send + cursor-based idempotency (Section 33)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.3"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/fixtures/build-chat-db.ts

@@ -1,52 +0,0 @@
-/**
- * Test helper — build a fixture chat.db with the minimum schema and
- * representative rows. Returns the path to the temp .db file.
- */
-import { Database } from "bun:sqlite";
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-export function buildFixtureChatDb(): string {
-  const dir = mkdtempSync(join(tmpdir(), "crewhaus-imessage-fix-"));
-  const path = join(dir, "chat.db");
-  const db = new Database(path);
-  db.run(`
-    CREATE TABLE handle (
-      ROWID INTEGER PRIMARY KEY,
-      id TEXT NOT NULL,
-      service TEXT NOT NULL DEFAULT 'iMessage'
-    );
-  `);
-  db.run(`
-    CREATE TABLE message (
-      ROWID INTEGER PRIMARY KEY,
-      text TEXT,
-      is_from_me INTEGER DEFAULT 0,
-      date INTEGER DEFAULT 0,
-      handle_id INTEGER REFERENCES handle(ROWID)
-    );
-  `);
-
-  db.run("INSERT INTO handle (ROWID, id) VALUES (1, 'alice@example.com')");
-  db.run("INSERT INTO handle (ROWID, id) VALUES (2, '+15551234567')");
-
-  db.run(
-    "INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (1, 'first inbound from alice', 0, 700000000000000000, 1)",
-  );
-  db.run(
-    "INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (2, 'me replying', 1, 700000001000000000, 1)",
-  );
-  db.run(
-    "INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (3, 'inbound from phone handle', 0, 700000002000000000, 2)",
-  );
-  db.run(
-    "INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (4, '', 0, 700000003000000000, 1)",
-  );
-  db.run(
-    "INSERT INTO message (ROWID, text, is_from_me, date, handle_id) VALUES (5, 'another inbound', 0, 700000004000000000, 1)",
-  );
-
-  db.close();
-  return path;
-}

package/src/index.osascript.test.ts

@@ -1,116 +0,0 @@
-/**
- * Coverage for the production `defaultOsascript` path — the branch that
- * dynamically `import("node:child_process")` and spawns the real `osascript`.
- *
- * Calling `sendReply` without an injected `osascript` runner exercises that
- * default. To keep the test deterministic (no real process, no real iMessage
- * send) we replace `node:child_process` with a fake `spawn` via `mock.module`.
- *
- * This lives in its own file so only these tests see the mock — but Bun does
- * NOT reset module mocks at the file boundary: `bun test` runs every file in
- * one process, file order is nondeterministic, and a `mock.module` persists
- * until overwritten. The `afterAll` below re-mocks the real module so the
- * fake `spawn` cannot leak into files that happen to run later.
- */
-import { afterAll, describe, expect, mock, test } from "bun:test";
-import { EventEmitter } from "node:events";
-import { rmSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-import { buildFixtureChatDb } from "./fixtures/build-chat-db";
-
-// Captured BEFORE the mock below so afterAll can reinstall the real module.
-const realChildProcess = require("node:child_process") as typeof import("node:child_process");
-
-/** Records the scripts handed to the fake `osascript` across the file. */
-const writtenScripts: string[] = [];
-let nextExit = 0;
-
-mock.module("node:child_process", () => ({
-  spawn: (command: string, args: readonly string[], options: unknown) => {
-    // Sanity-check the default runner invokes osascript reading from stdin.
-    expect(command).toBe("osascript");
-    expect(args).toEqual(["-"]);
-    expect(options).toEqual({ stdio: ["pipe", "ignore", "pipe"] });
-    const child = new EventEmitter() as EventEmitter & {
-      stderr: EventEmitter;
-      stdin: { write(s: string): void; end(): void };
-    };
-    child.stderr = new EventEmitter();
-    child.stdin = {
-      write: (s: string) => writtenScripts.push(s),
-      end: () => {},
-    };
-    queueMicrotask(() => {
-      if (nextExit === 0) {
-        child.emit("close", 0);
-      } else {
-        child.stderr.emit("data", Buffer.from("osascript boom", "utf8"));
-        child.emit("close", nextExit);
-      }
-    });
-    return child;
-  },
-}));
-
-afterAll(() => {
-  // Bun has no mock.module restore API; re-mocking with the real exports is
-  // the documented way to undo a module mock. Without this, the fake `spawn`
-  // (which asserts it is called as `osascript`) stays registered for every
-  // test file that runs after this one.
-  mock.module("node:child_process", () => realChildProcess);
-});
-
-// Import AFTER registering the mock so the dynamic import inside
-// defaultOsascript resolves to the fake.
-const { createIMessageAdapter } = await import("./index");
-
-function makeAdapter() {
-  const dbPath = buildFixtureChatDb();
-  const cursorPath = join(dirname(dbPath), "cursor.json");
-  const adapter = createIMessageAdapter({
-    chatDbPath: dbPath,
-    cursorPath,
-    requireHostOptIn: false,
-  });
-  return { adapter, cleanup: () => rmSync(dirname(dbPath), { recursive: true, force: true }) };
-}
-
-const baseEvent = {
-  idempotencyKey: "imsg:1",
-  workspaceId: "imessage",
-  channelId: "alice@example.com",
-  userId: "alice@example.com",
-  ts: "0",
-  text: "in",
-  subtype: "message",
-} as const;
-
-describe("defaultOsascript (real-runner branch, child_process mocked)", () => {
-  test("sendReply with no injected runner spawns osascript and writes the script", async () => {
-    nextExit = 0;
-    writtenScripts.length = 0;
-    const { adapter, cleanup } = makeAdapter();
-    try {
-      await adapter.sendReply({ event: baseEvent, text: "hello from default" });
-      expect(writtenScripts.length).toBe(1);
-      expect(writtenScripts[0]).toContain('tell application "Messages"');
-      expect(writtenScripts[0]).toContain('send "hello from default"');
-    } finally {
-      cleanup();
-    }
-  });
-
-  test("sendReply rejects when the spawned osascript exits non-zero", async () => {
-    nextExit = 3;
-    writtenScripts.length = 0;
-    const { adapter, cleanup } = makeAdapter();
-    try {
-      await expect(adapter.sendReply({ event: baseEvent, text: "x" })).rejects.toThrow(
-        /osascript exited with 3: osascript boom/,
-      );
-    } finally {
-      cleanup();
-    }
-  });
-});

package/src/index.test.ts

@@ -1,353 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-
-import { buildFixtureChatDb } from "./fixtures/build-chat-db";
-import {
-  IMessageAdapterError,
-  type OsascriptSpawn,
-  _internal,
-  createIMessageAdapter,
-  runOsascript,
-} from "./index";
-
-const { isSafeHandle, escapeAppleScriptString, validateChatDbPath } = _internal;
-
-/**
- * Build a deterministic fake of `child_process.spawn` for {@link runOsascript}
- * tests — no real process. `behavior` decides which lifecycle events fire and
- * is invoked on a microtask so the runner has wired its listeners first.
- */
-function fakeSpawn(behavior: {
-  readonly stderrChunks?: readonly string[];
-  readonly closeCode?: number | null;
-  readonly emitError?: Error;
-  /** Force `stdin`/`stderr` to be null to exercise the optional-chaining guards. */
-  readonly nullStreams?: boolean;
-}): { spawn: OsascriptSpawn; getWritten: () => string | undefined; ended: () => boolean } {
-  let written: string | undefined;
-  let didEnd = false;
-  const spawn: OsascriptSpawn = (command, args, options) => {
-    // The runner must always invoke osascript reading the script from stdin.
-    expect(command).toBe("osascript");
-    expect(args).toEqual(["-"]);
-    expect(options).toEqual({ stdio: ["pipe", "ignore", "pipe"] });
-    const handlers: Record<string, (arg: never) => void> = {};
-    const stderrHandlers: ((chunk: Buffer) => void)[] = [];
-    queueMicrotask(() => {
-      for (const c of behavior.stderrChunks ?? []) {
-        for (const h of stderrHandlers) h(Buffer.from(c, "utf8"));
-      }
-      if (behavior.emitError) handlers["error"]?.(behavior.emitError as never);
-      else handlers["close"]?.((behavior.closeCode ?? 0) as never);
-    });
-    return {
-      stderr: behavior.nullStreams ? null : { on: (_e, cb) => stderrHandlers.push(cb) },
-      stdin: behavior.nullStreams
-        ? null
-        : {
-            write: (chunk: string) => {
-              written = chunk;
-            },
-            end: () => {
-              didEnd = true;
-            },
-          },
-      on: (event: string, cb: (arg: never) => void) => {
-        handlers[event] = cb;
-      },
-    };
-  };
-  return { spawn, getWritten: () => written, ended: () => didEnd };
-}
-
-describe("runOsascript (default-runner core, dependency-injected spawn)", () => {
-  test("writes the script to stdin and resolves on exit code 0", async () => {
-    const f = fakeSpawn({ closeCode: 0 });
-    await runOsascript(f.spawn, "tell app");
-    expect(f.getWritten()).toBe("tell app");
-    expect(f.ended()).toBe(true);
-  });
-
-  test("rejects with stderr text + code on a non-zero exit", async () => {
-    const f = fakeSpawn({ closeCode: 2, stderrChunks: ["bad ", "things"] });
-    await expect(runOsascript(f.spawn, "x")).rejects.toThrow(/osascript exited with 2: bad things/);
-  });
-
-  test("rejects with a clear message when spawn emits 'error'", async () => {
-    const boom = new Error("ENOENT osascript");
-    const f = fakeSpawn({ emitError: boom });
-    let caught: unknown;
-    try {
-      await runOsascript(f.spawn, "x");
-    } catch (e) {
-      caught = e;
-    }
-    expect(caught).toBeInstanceOf(IMessageAdapterError);
-    expect((caught as Error).message).toBe("osascript spawn failed");
-    // The originating error is preserved on the cause chain.
-    expect((caught as IMessageAdapterError).cause).toBe(boom);
-  });
-
-  test("null stdin/stderr streams are tolerated (optional-chaining guards)", async () => {
-    const f = fakeSpawn({ nullStreams: true, closeCode: 0 });
-    await runOsascript(f.spawn, "x");
-    // Nothing was written because stdin was null; the runner still resolved.
-    expect(f.getWritten()).toBeUndefined();
-  });
-
-  test("exposed on _internal for the adapter's wiring", () => {
-    expect(_internal.runOsascript).toBe(runOsascript);
-  });
-});
-
-describe("isSafeHandle / escapeAppleScriptString / validateChatDbPath", () => {
-  test("accepts well-formed iMessage handles", () => {
-    expect(isSafeHandle("alice@example.com")).toBe(true);
-    expect(isSafeHandle("+15551234567")).toBe(true);
-    expect(isSafeHandle("tel:+15551234567")).toBe(true);
-  });
-
-  test("rejects shell-injection-shaped handles", () => {
-    expect(isSafeHandle('alice@example.com";rm -rf /')).toBe(false);
-    expect(isSafeHandle("$(curl evil.com)")).toBe(false);
-    expect(isSafeHandle("../../../etc/passwd")).toBe(false);
-    expect(isSafeHandle("")).toBe(false);
-  });
-
-  test("escapes AppleScript metacharacters", () => {
-    expect(escapeAppleScriptString('hi "you"')).toBe('hi \\"you\\"');
-    expect(escapeAppleScriptString("path\\to\\file")).toBe("path\\\\to\\\\file");
-    expect(escapeAppleScriptString("line1\nline2")).toBe("line1\\nline2");
-  });
-
-  test("validateChatDbPath requires chat.db filename and rejects empty", () => {
-    expect(() => validateChatDbPath("")).toThrow(/chat.db path is empty/);
-    expect(() => validateChatDbPath("/etc/passwd")).toThrow(/must end in 'chat.db'/);
-    expect(validateChatDbPath("/tmp/some/chat.db")).toBe("/tmp/some/chat.db");
-  });
-});
-
-describe("createIMessageAdapter — opt-in guard (T8)", () => {
-  test("requireHostOptIn=false bypasses guards (test mode)", () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    const a = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-    expect(a.id).toBe("imessage");
-  });
-
-  test("missing chat.db throws clear error", () => {
-    expect(() =>
-      createIMessageAdapter({
-        chatDbPath: join(tmpdir(), "definitely-missing", "chat.db"),
-        requireHostOptIn: false,
-      }),
-    ).toThrow(/chat.db not found/);
-  });
-});
-
-describe("pollNewMessages (T2)", () => {
-  let dbPath: string;
-  let cursorPath: string;
-  let adapter: ReturnType<typeof createIMessageAdapter>;
-
-  beforeAll(() => {
-    dbPath = buildFixtureChatDb();
-    cursorPath = join(dirname(dbPath), "cursor.json");
-    adapter = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-  });
-
-  afterAll(() => {
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-
-  test("first poll returns 3 inbound (skips me + empty), advances cursor to ROWID 5", async () => {
-    const r = await adapter.pollNewMessages();
-    expect(r.events.length).toBe(3);
-    expect(r.cursor).toBe(5);
-    expect(r.events[0]?.idempotencyKey).toBe("imsg:1");
-    expect(r.events[0]?.text).toBe("first inbound from alice");
-    expect(r.events[0]?.userId).toBe("alice@example.com");
-    expect(r.events[0]?.channelId).toBe("alice@example.com");
-    expect(r.events[1]?.idempotencyKey).toBe("imsg:3");
-    expect(r.events[1]?.userId).toBe("+15551234567");
-    expect(r.events[2]?.idempotencyKey).toBe("imsg:5");
-  });
-
-  test("subsequent poll with no new rows returns empty + same cursor", async () => {
-    const first = await adapter.pollNewMessages();
-    const second = await adapter.pollNewMessages();
-    expect(second.events.length).toBe(0);
-    expect(second.cursor).toBe(first.cursor);
-  });
-
-  test("cursor persists across new adapter instances (idempotency across restart)", async () => {
-    // First adapter polls and advances cursor.
-    await adapter.pollNewMessages();
-    // Construct a fresh adapter pointing at the same cursor file.
-    const a2 = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-    const r = await a2.pollNewMessages();
-    expect(r.events.length).toBe(0);
-    expect(a2.getCursor()).toBe(5);
-  });
-
-  test("resetCursor clears the persisted state", async () => {
-    adapter.resetCursor();
-    expect(adapter.getCursor()).toBe(0);
-    const r = await adapter.pollNewMessages();
-    expect(r.events.length).toBe(3);
-  });
-});
-
-describe("sendReply (T3)", () => {
-  test("escapes message text + handle, hits osascript with the right script", async () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    const calls: string[] = [];
-    const a = createIMessageAdapter(
-      {
-        chatDbPath: dbPath,
-        cursorPath,
-        requireHostOptIn: false,
-      },
-      {
-        osascript: async (script) => {
-          calls.push(script);
-        },
-      },
-    );
-    await a.sendReply({
-      event: {
-        idempotencyKey: "imsg:1",
-        workspaceId: "imessage",
-        channelId: "alice@example.com",
-        userId: "alice@example.com",
-        ts: "0",
-        text: "hello",
-        subtype: "message",
-      },
-      text: 'reply with "quotes"',
-    });
-    expect(calls.length).toBe(1);
-    const script = calls[0] ?? "";
-    expect(script).toContain('tell application "Messages"');
-    expect(script).toContain('buddy "alice@example.com"');
-    expect(script).toContain('send "reply with \\"quotes\\""');
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-
-  test("rejects shell-injection in handle (path-traversal / metachar guard)", async () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    const a = createIMessageAdapter(
-      { chatDbPath: dbPath, cursorPath, requireHostOptIn: false },
-      { osascript: async () => undefined },
-    );
-    await expect(
-      a.sendReply({
-        event: {
-          idempotencyKey: "x",
-          workspaceId: "imessage",
-          channelId: 'alice"; do bad`',
-          userId: 'alice"; do bad`',
-          ts: "0",
-          text: "x",
-          subtype: "message",
-        },
-        text: "x",
-      }),
-    ).rejects.toThrow(/unsafe iMessage handle/);
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-});
-
-describe("setTyping is a no-op", () => {
-  test("does not throw or call osascript", async () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    let called = false;
-    const a = createIMessageAdapter(
-      { chatDbPath: dbPath, cursorPath, requireHostOptIn: false },
-      {
-        osascript: async () => {
-          called = true;
-        },
-      },
-    );
-    await a.setTyping({
-      event: {
-        idempotencyKey: "x",
-        workspaceId: "imessage",
-        channelId: "alice@example.com",
-        userId: "alice@example.com",
-        ts: "0",
-        text: "",
-        subtype: "message",
-      },
-    });
-    expect(called).toBe(false);
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-});
-
-describe("verify / parseInbound (no-op for poll-driven adapter)", () => {
-  test("verify returns true; parseInbound returns skip", () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    const a = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-    expect(a.verify({ headers: new Headers(), body: "" })).toBe(true);
-    expect(a.parseInbound({ headers: new Headers(), body: "{}" }).kind).toBe("skip");
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-});
-
-describe("cursor file integrity", () => {
-  test("malformed cursor file falls back to 0", () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    writeFileSync(cursorPath, "not json{");
-    const a = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-    expect(a.getCursor()).toBe(0);
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-
-  test("cursor file written with 0o600 mode", async () => {
-    const dbPath = buildFixtureChatDb();
-    const cursorPath = join(dirname(dbPath), "cursor.json");
-    const a = createIMessageAdapter({
-      chatDbPath: dbPath,
-      cursorPath,
-      requireHostOptIn: false,
-    });
-    await a.pollNewMessages();
-    if (existsSync(cursorPath)) {
-      const { statSync } = await import("node:fs");
-      const mode = statSync(cursorPath).mode & 0o777;
-      // On Bun/Linux the umask may downgrade — accept anything <= 0o600.
-      expect(mode <= 0o600).toBe(true);
-    }
-    expect(JSON.parse(readFileSync(cursorPath, "utf8"))).toEqual({ cursor: 5 });
-    rmSync(dirname(dbPath), { recursive: true, force: true });
-  });
-});

package/src/index.ts

@@ -1,361 +0,0 @@
-import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, normalize } from "node:path";
-/**
- * @crewhaus/channel-adapter-imessage — macOS-only iMessage channel
- * adapter for the channel target (Section 33).
- *
- * Apple does NOT publish a public iMessage Business API for general
- * agent integrations. This adapter takes a host-bound approach:
- *
- *   - Inbound: poll Messages.app's SQLite store at
- *     ~/Library/Messages/chat.db for new rows since the last cursor.
- *     The cursor is `message.ROWID` — monotonically increasing per
- *     install. We persist it to a small JSON file so a daemon restart
- *     resumes from where it left off.
- *
- *   - Outbound: drive Messages.app via osascript. The handle (an
- *     iMessage email/phone) is the conversation key.
- *
- * Hard requirements (enforced via guard / startup check):
- *   - Process is running on macOS (`process.platform === "darwin"`).
- *   - `CREWHAUS_IMESSAGE_HOST_ENABLED=1` is set — opt-in to using the
- *     host's logged-in iMessage account.
- *   - Full Disk Access permission is granted to the daemon's host
- *     terminal/process so chat.db is readable. (We surface a clear
- *     error if the file isn't reachable.)
- *
- * Path-traversal safety: chat.db's path is constructed from the HOME
- * env at boot and validated against a fixed prefix
- * (`~/Library/Messages/`). Custom override is allowed only via the
- * adapter's `chatDbPath` option (intended for tests with fixture DBs)
- * AND must resolve to a file with name `chat.db`.
- */
-import { CrewhausError } from "@crewhaus/errors";
-
-export class IMessageAdapterError extends CrewhausError {
-  override readonly name = "IMessageAdapterError";
-  constructor(message: string, cause?: unknown) {
-    super("channel", message, cause);
-  }
-}
-
-export type RawRequest = {
-  readonly headers: Headers;
-  readonly body: string;
-};
-
-/** Channel-generic inbound event — same shape as Slack/Telegram/etc. */
-export type InboundEvent = {
-  readonly idempotencyKey: string;
-  readonly workspaceId: string;
-  readonly channelId: string;
-  readonly userId: string;
-  readonly threadTs?: string;
-  readonly ts: string;
-  readonly text: string;
-  readonly subtype: "app_mention" | "message";
-};
-
-export type ParsedInbound =
-  | { readonly kind: "event"; readonly event: InboundEvent }
-  | { readonly kind: "skip" };
-
-/**
- * The iMessage adapter is non-webhook — there's no inbound HTTP. Polling
- * happens via `pollNewMessages()` which the daemon harness calls on a
- * schedule. We still implement the same `ChannelAdapter` interface so
- * the §33 multi-adapter wiring can register it; `verify` and
- * `parseInbound` are never called by the gateway for iMessage (the
- * polling loop emits InboundEvents directly).
- */
-export interface ChannelAdapter {
-  readonly id: string;
-  verify(req: RawRequest): boolean;
-  parseInbound(req: RawRequest): ParsedInbound;
-  sendReply(args: { event: InboundEvent; text: string }): Promise<void>;
-  setTyping(args: { event: InboundEvent }): Promise<void>;
-}
-
-export interface IMessageAdapter extends ChannelAdapter {
-  /**
-   * Poll chat.db for messages with ROWID > cursor. Returns the new
-   * messages and the new cursor. Idempotent across restarts: reads
-   * the persisted cursor from `cursorPath` if present.
-   */
-  pollNewMessages(): Promise<{
-    readonly events: readonly InboundEvent[];
-    readonly cursor: number;
-  }>;
-  /** Returns the current persisted cursor (or 0 if not yet set). */
-  getCursor(): number;
-  /** Reset the cursor — used by tests + the `--reset-cursor` CLI flag. */
-  resetCursor(): void;
-}
-
-export type IMessageAdapterConfig = {
-  /**
-   * Custom chat.db path. Defaults to `<HOME>/Library/Messages/chat.db`.
-   * Overridable for tests (must end in `chat.db`).
-   */
-  readonly chatDbPath?: string;
-  /** Where to persist the polling cursor. Defaults to `.crewhaus/imessage-cursor.json`. */
-  readonly cursorPath?: string;
-  /**
-   * Required: gate the adapter on opt-in env. Setting this to false
-   * (e.g. in tests with fixture DBs) bypasses the
-   * `CREWHAUS_IMESSAGE_HOST_ENABLED=1` env-check. Defaults to true.
-   */
-  readonly requireHostOptIn?: boolean;
-};
-
-export type IMessageAdapterOptions = {
-  /** Inject a custom osascript runner (defaults to spawning `osascript`). */
-  readonly osascript?: (script: string) => Promise<void>;
-};
-
-const CHAT_DB_REL = "Library/Messages/chat.db";
-
-export function createIMessageAdapter(
-  config: IMessageAdapterConfig = {},
-  opts: IMessageAdapterOptions = {},
-): IMessageAdapter {
-  const requireHostOptIn = config.requireHostOptIn ?? true;
-  if (requireHostOptIn) {
-    if (process.platform !== "darwin") {
-      throw new IMessageAdapterError(
-        `iMessage adapter requires macOS (process.platform=${process.platform})`,
-      );
-    }
-    if (process.env["CREWHAUS_IMESSAGE_HOST_ENABLED"] !== "1") {
-      throw new IMessageAdapterError(
-        "iMessage adapter requires CREWHAUS_IMESSAGE_HOST_ENABLED=1 (opt-in to host's logged-in iMessage)",
-      );
-    }
-  }
-
-  const home = process.env["HOME"] ?? "";
-  const defaultDbPath = home ? `${home}/${CHAT_DB_REL}` : "";
-  const chatDbPath = validateChatDbPath(config.chatDbPath ?? defaultDbPath);
-  if (!existsSync(chatDbPath)) {
-    throw new IMessageAdapterError(
-      `iMessage chat.db not found at ${chatDbPath} (full disk access?)`,
-    );
-  }
-
-  const cursorPath = config.cursorPath ?? ".crewhaus/imessage-cursor.json";
-
-  const osascriptRun = opts.osascript ?? defaultOsascript;
-
-  return {
-    id: "imessage",
-
-    verify(_req: RawRequest): boolean {
-      // No inbound HTTP — iMessage is polling-driven. We accept all by
-      // returning true so the gateway path never short-circuits, but
-      // the gateway ought to never call us anyway.
-      return true;
-    },
-
-    parseInbound(_req: RawRequest): ParsedInbound {
-      return { kind: "skip" };
-    },
-
-    async sendReply(args: { event: InboundEvent; text: string }): Promise<void> {
-      const handle = args.event.userId;
-      if (!isSafeHandle(handle)) {
-        throw new IMessageAdapterError(`unsafe iMessage handle: ${handle}`);
-      }
-      const escapedText = escapeAppleScriptString(args.text);
-      const escapedHandle = escapeAppleScriptString(handle);
-      const script = [
-        'tell application "Messages"',
-        "  set targetService to 1st service whose service type = iMessage",
-        `  set targetBuddy to buddy "${escapedHandle}" of targetService`,
-        `  send "${escapedText}" to targetBuddy`,
-        "end tell",
-      ].join("\n");
-      await osascriptRun(script);
-    },
-
-    async setTyping(_args: { event: InboundEvent }): Promise<void> {
-      // Messages.app does not expose a typing-indicator API to AppleScript.
-    },
-
-    pollNewMessages(): Promise<{ events: readonly InboundEvent[]; cursor: number }> {
-      const cursor = readCursor(cursorPath);
-      const db = new Database(chatDbPath, { readonly: true });
-      try {
-        const rows = db.query<MessageRow, [number]>(MESSAGE_QUERY).all(cursor);
-        const events: InboundEvent[] = [];
-        let maxId = cursor;
-        for (const row of rows) {
-          if (row.ROWID > maxId) maxId = row.ROWID;
-          if (row.is_from_me === 1) continue;
-          const text = row.text ?? "";
-          if (text.trim() === "") continue;
-          const handle = row.handle_id_str ?? `handle:${row.handle_id ?? "unknown"}`;
-          events.push({
-            idempotencyKey: `imsg:${row.ROWID}`,
-            workspaceId: "imessage",
-            channelId: handle,
-            userId: handle,
-            ts: String(row.date),
-            text,
-            subtype: "message",
-          });
-        }
-        if (maxId !== cursor) writeCursor(cursorPath, maxId);
-        return Promise.resolve({ events, cursor: maxId });
-      } finally {
-        db.close();
-      }
-    },
-
-    getCursor(): number {
-      return readCursor(cursorPath);
-    },
-
-    resetCursor(): void {
-      writeCursor(cursorPath, 0);
-    },
-  };
-}
-
-// ─── chat.db path validation ────────────────────────────────────────────────
-
-/**
- * Allow the canonical chat.db location (`<HOME>/Library/Messages/chat.db`)
- * and any custom path that resolves to a file named `chat.db`. Reject
- * absolute paths attempting traversal outside `~/Library/Messages/` UNLESS
- * the caller explicitly overrode (tests use a tmpdir).
- */
-function validateChatDbPath(path: string): string {
-  if (!path) {
-    throw new IMessageAdapterError("chat.db path is empty (HOME env not set?)");
-  }
-  const norm = normalize(path);
-  if (!norm.endsWith("chat.db")) {
-    throw new IMessageAdapterError(`chat.db path must end in 'chat.db': ${path}`);
-  }
-  return norm;
-}
-
-function isSafeHandle(handle: string): boolean {
-  // Allow email-shaped handles + +<digits> phone handles + tel: URIs.
-  return (
-    /^[\w._%+-]+@[\w.-]+\.\w{2,}$/.test(handle) ||
-    /^\+\d{6,15}$/.test(handle) ||
-    /^tel:\+?\d{6,15}$/.test(handle)
-  );
-}
-
-function escapeAppleScriptString(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
-}
-
-// ─── cursor persistence ────────────────────────────────────────────────────
-
-function readCursor(cursorPath: string): number {
-  if (!existsSync(cursorPath)) return 0;
-  try {
-    const raw = readFileSync(cursorPath, "utf8");
-    const v = JSON.parse(raw) as { cursor?: number };
-    return typeof v.cursor === "number" && Number.isFinite(v.cursor) ? v.cursor : 0;
-  } catch {
-    return 0;
-  }
-}
-
-function writeCursor(cursorPath: string, cursor: number): void {
-  mkdirSync(dirname(cursorPath), { recursive: true });
-  writeFileSync(cursorPath, JSON.stringify({ cursor }), { mode: 0o600 });
-}
-
-// ─── default osascript runner ──────────────────────────────────────────────
-
-/**
- * Minimal structural type for the slice of `child_process.spawn` that the
- * osascript runner uses. Keeping it explicit (rather than importing Node's
- * `ChildProcess`) lets tests inject a deterministic fake without a real
- * process spawn — mirroring the dependency-injection style used elsewhere in
- * factory's adapters.
- */
-type SpawnedChild = {
-  readonly stdout?: { on(event: "data", cb: (chunk: Buffer) => void): void } | null;
-  readonly stderr: { on(event: "data", cb: (chunk: Buffer) => void): void } | null;
-  readonly stdin: { write(chunk: string): void; end(): void } | null;
-  on(event: "error", cb: (err: Error) => void): void;
-  on(event: "close", cb: (code: number | null) => void): void;
-};
-
-export type OsascriptSpawn = (
-  command: string,
-  args: readonly string[],
-  options: { stdio: readonly ["pipe", "ignore", "pipe"] },
-) => SpawnedChild;
-
-/**
- * Run `osascript` reading the script from stdin, using an injected `spawn`.
- * Resolves on exit code 0; rejects with an {@link IMessageAdapterError} on a
- * spawn failure or any non-zero exit (surfacing captured stderr).
- */
-export function runOsascript(spawn: OsascriptSpawn, script: string): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    const head = "osascript";
-    const child = spawn(head, ["-"], { stdio: ["pipe", "ignore", "pipe"] });
-    const errBufs: Buffer[] = [];
-    child.stderr?.on("data", (b) => errBufs.push(b));
-    child.on("error", (e) => reject(new IMessageAdapterError("osascript spawn failed", e)));
-    child.on("close", (code) => {
-      if (code === 0) resolve();
-      else
-        reject(
-          new IMessageAdapterError(
-            `osascript exited with ${code}: ${Buffer.concat(errBufs).toString("utf8")}`,
-          ),
-        );
-    });
-    child.stdin?.write(script);
-    child.stdin?.end();
-  });
-}
-
-const defaultOsascript = async (script: string): Promise<void> => {
-  const { spawn } = await import("node:child_process");
-  return runOsascript(spawn as unknown as OsascriptSpawn, script);
-};
-
-// ─── chat.db row shape + query ──────────────────────────────────────────────
-
-const MESSAGE_QUERY = `
-  SELECT
-    m.ROWID,
-    m.text,
-    m.is_from_me,
-    m.date,
-    m.handle_id,
-    h.id AS handle_id_str
-  FROM message m
-  LEFT JOIN handle h ON h.ROWID = m.handle_id
-  WHERE m.ROWID > ?
-  ORDER BY m.ROWID ASC
-`;
-
-type MessageRow = {
-  readonly ROWID: number;
-  readonly text: string | null;
-  readonly is_from_me: number;
-  readonly date: number;
-  readonly handle_id: number | null;
-  readonly handle_id_str: string | null;
-};
-
-// ─── helpers consumed by tests ────────────────────────────────────────────
-
-export const _internal = {
-  isSafeHandle,
-  escapeAppleScriptString,
-  validateChatDbPath,
-  runOsascript,
-};