@pinet/imessage-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @pinet/imessage-bridge
+
+Thin macOS/iMessage **send-first** package for the `extensions` repo.
+
+## What this slice does
+
+This package now covers the smallest useful live transport path:
+
+- adapter-local readiness checks for a local macOS iMessage MVP
+- an AppleScript-backed outbound adapter for **send-first** delivery
+- transport-local helpers that the shared broker/runtime core can call without burying iMessage logic inside `slack-bridge`
+
+## Current MVP shape
+
+The current implementation is intentionally narrow:
+
+- **macOS only**
+- **send-first**
+- **AppleScript delivery** through `/usr/bin/osascript`
+- **shared-core delivery** via the broker adapter seam
+- **local history readiness** still modeled against `~/Library/Messages/chat.db`
+
+That means outbound sends can work even when the local Messages database is unavailable, while startup/readiness reporting still makes the history blocker explicit.
+
+## Trust boundary notes
+
+`@pinet/imessage-bridge` is an intentional **same-host local-power surface**.
+
+- When enabled, outbound sends run through the local Messages app via `/usr/bin/osascript` as the current macOS user.
+- There is no extra approval or policy layer inside this package today; the trust boundary is local operator intent on the same host.
+- The current MVP is still **send-first**, so outbound capability can be ready even when local history access is unavailable.
+- Missing `chat.db` only blocks local history/readiness depth. It does **not** remove the outbound send power when AppleScript remains available.
+
+Treat this as explicit local outbound power, not as a remote-safe transport or a generic policy-enforced messaging surface.
+
+In the current repo bring-up path, enable the adapter with `slack-bridge.imessage.enabled: true` and start the broker runtime with `/pinet start`.
+
+## What stays in this package
+
+- readiness detection
+- canonical local path assumptions for the Messages database
+- AppleScript send helper + adapter-local transport code
+- stable default thread-id helper for send-first bring-up
+
+## Publishing
+
+This package is included in the full npm publish set tracked in
+[`../plans/npm-publish.md`](../plans/npm-publish.md). Use the GitHub Actions
+workflow's default dry-run/readiness path for validation; do not publish, tag, or
+bump versions without explicit maintainer release approval.
+
+## What stays out of scope
+
+- inbound iMessage sync
+- chat database query plumbing
+- generic transport UI redesign
+- WhatsApp or other transport work
+- broad Slack/Pinet separation cleanup beyond the existing broker adapter seam
+
+## Example
+
+```ts
+import {
+  createIMessageAdapter,
+  detectIMessageMvpEnvironment,
+  getDefaultIMessageThreadId,
+} from "@pinet/imessage-bridge";
+
+const readiness = detectIMessageMvpEnvironment();
+if (readiness.canAttemptSend) {
+  const adapter = createIMessageAdapter();
+  await adapter.connect();
+  await adapter.send({
+    threadId: getDefaultIMessageThreadId("chat:alice"),
+    channel: "chat:alice",
+    text: "hello from pi",
+  });
+}
+```

package/dist/adapter.d.ts

@@ -0,0 +1,23 @@
+import type { InboundMessage as IMessageAdapterInboundMessage, MessageAdapter, OutboundMessage as IMessageAdapterOutboundMessage } from "@pinet/transport-core";
+import { type RunAppleScript } from "./send.js";
+import { type DetectIMessageMvpEnvironmentOptions, type IMessageMvpEnvironment } from "./mvp.js";
+export type { IMessageAdapterInboundMessage, IMessageAdapterOutboundMessage };
+export interface IMessageAdapterOptions {
+    osascriptPath?: string;
+    runAppleScript?: RunAppleScript;
+    detectEnvironmentOptions?: DetectIMessageMvpEnvironmentOptions;
+    detectEnvironment?: (options?: DetectIMessageMvpEnvironmentOptions) => IMessageMvpEnvironment;
+}
+export interface IMessageAdapter extends MessageAdapter {
+    readonly name: "imessage";
+}
+export declare class AppleScriptIMessageAdapter implements IMessageAdapter {
+    readonly name: "imessage";
+    private readonly options;
+    constructor(options?: IMessageAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    onInbound(_handler: (msg: IMessageAdapterInboundMessage) => void): void;
+    send(msg: IMessageAdapterOutboundMessage): Promise<void>;
+}
+export declare function createIMessageAdapter(options?: IMessageAdapterOptions): IMessageAdapter;

package/dist/adapter.js

@@ -0,0 +1,44 @@
+import { assertIMessageSendCapability, sendIMessage } from "./send.js";
+import { formatIMessageMvpReadiness, } from "./mvp.js";
+export class AppleScriptIMessageAdapter {
+    name = "imessage";
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async connect() {
+        const detectEnvironment = this.options.detectEnvironment;
+        const environment = detectEnvironment
+            ? detectEnvironment(this.options.detectEnvironmentOptions)
+            : null;
+        if (environment) {
+            if (!environment.canAttemptSend) {
+                throw new Error([
+                    "iMessage send-first adapter is not ready.",
+                    ...formatIMessageMvpReadiness(environment),
+                ].join(" "));
+            }
+            return;
+        }
+        assertIMessageSendCapability(this.options.detectEnvironmentOptions);
+    }
+    async disconnect() {
+        // The current send-first adapter does not hold inbound subscriptions or
+        // long-lived connection state beyond the shared MessageAdapter surface.
+    }
+    onInbound(_handler) {
+        // The shared MessageAdapter contract requires an inbound hook, but the
+        // current iMessage adapter is send-only and intentionally ignores it.
+    }
+    async send(msg) {
+        await sendIMessage({
+            recipient: msg.channel,
+            text: msg.content?.text ?? msg.text,
+            osascriptPath: this.options.osascriptPath,
+            runAppleScript: this.options.runAppleScript,
+        });
+    }
+}
+export function createIMessageAdapter(options = {}) {
+    return new AppleScriptIMessageAdapter(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { APPLESCRIPT_BINARY_PATH, DEFAULT_MESSAGES_DB_RELATIVE_PATH, type DetectIMessageMvpEnvironmentOptions, detectIMessageMvpEnvironment, formatIMessageMvpReadiness, getDefaultMessagesDbPath, type IMessageMvpEnvironment, type IMessageMvpEnvironmentBlocker, } from "./mvp.js";
+export { AppleScriptIMessageAdapter, createIMessageAdapter, type IMessageAdapter, type IMessageAdapterInboundMessage, type IMessageAdapterOptions, type IMessageAdapterOutboundMessage, } from "./adapter.js";
+export { assertIMessageSendCapability, buildIMessageSendAppleScript, getDefaultIMessageThreadId, normalizeIMessageRecipient, runAppleScript, sendIMessage, type RunAppleScript, type RunAppleScriptInput, type RunAppleScriptResult, type SendIMessageOptions, } from "./send.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { APPLESCRIPT_BINARY_PATH, DEFAULT_MESSAGES_DB_RELATIVE_PATH, detectIMessageMvpEnvironment, formatIMessageMvpReadiness, getDefaultMessagesDbPath, } from "./mvp.js";
+export { AppleScriptIMessageAdapter, createIMessageAdapter, } from "./adapter.js";
+export { assertIMessageSendCapability, buildIMessageSendAppleScript, getDefaultIMessageThreadId, normalizeIMessageRecipient, runAppleScript, sendIMessage, } from "./send.js";

package/dist/mvp.d.ts

@@ -0,0 +1,23 @@
+export declare const APPLESCRIPT_BINARY_PATH = "/usr/bin/osascript";
+export declare const DEFAULT_MESSAGES_DB_RELATIVE_PATH: string;
+export type IMessageMvpEnvironmentBlocker = "unsupported_platform" | "missing_osascript" | "missing_messages_db";
+export interface IMessageMvpEnvironment {
+    platform: NodeJS.Platform;
+    homeDir: string;
+    messagesDbPath: string;
+    osascriptPath: string;
+    osascriptAvailable: boolean;
+    messagesDbAvailable: boolean;
+    canAttemptSend: boolean;
+    canAttemptHistoryRead: boolean;
+    readyForLocalMvp: boolean;
+    blockers: IMessageMvpEnvironmentBlocker[];
+}
+export interface DetectIMessageMvpEnvironmentOptions {
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    pathExists?: (candidatePath: string) => boolean;
+}
+export declare function getDefaultMessagesDbPath(homeDir?: string): string;
+export declare function detectIMessageMvpEnvironment(options?: DetectIMessageMvpEnvironmentOptions): IMessageMvpEnvironment;
+export declare function formatIMessageMvpReadiness(environment: IMessageMvpEnvironment): string[];

package/dist/mvp.js

@@ -0,0 +1,65 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+export const APPLESCRIPT_BINARY_PATH = "/usr/bin/osascript";
+export const DEFAULT_MESSAGES_DB_RELATIVE_PATH = path.join("Library", "Messages", "chat.db");
+export function getDefaultMessagesDbPath(homeDir = os.homedir()) {
+    return path.join(homeDir, DEFAULT_MESSAGES_DB_RELATIVE_PATH);
+}
+export function detectIMessageMvpEnvironment(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? os.homedir();
+    const pathExists = options.pathExists ?? existsSync;
+    const osascriptPath = APPLESCRIPT_BINARY_PATH;
+    const messagesDbPath = getDefaultMessagesDbPath(homeDir);
+    const supportedPlatform = platform === "darwin";
+    const osascriptAvailable = supportedPlatform && pathExists(osascriptPath);
+    const messagesDbAvailable = supportedPlatform && pathExists(messagesDbPath);
+    const blockers = [];
+    if (!supportedPlatform) {
+        blockers.push("unsupported_platform");
+    }
+    if (supportedPlatform && !osascriptAvailable) {
+        blockers.push("missing_osascript");
+    }
+    if (supportedPlatform && !messagesDbAvailable) {
+        blockers.push("missing_messages_db");
+    }
+    const canAttemptSend = supportedPlatform && osascriptAvailable;
+    const canAttemptHistoryRead = supportedPlatform && messagesDbAvailable;
+    return {
+        platform,
+        homeDir,
+        messagesDbPath,
+        osascriptPath,
+        osascriptAvailable,
+        messagesDbAvailable,
+        canAttemptSend,
+        canAttemptHistoryRead,
+        readyForLocalMvp: canAttemptSend && canAttemptHistoryRead,
+        blockers,
+    };
+}
+export function formatIMessageMvpReadiness(environment) {
+    const lines = [
+        `platform: ${environment.platform}`,
+        `osascript: ${environment.osascriptAvailable ? "ready" : "missing"} (${environment.osascriptPath})`,
+        `messages-db: ${environment.messagesDbAvailable ? "ready" : "missing"} (${environment.messagesDbPath})`,
+        "trust-boundary: same-host local-power surface; when enabled, outbound sends go through the local Messages app via /usr/bin/osascript as the current macOS user.",
+    ];
+    if (environment.readyForLocalMvp) {
+        lines.push("mvp: local macOS iMessage send/history scaffold is ready");
+        return lines;
+    }
+    if (environment.canAttemptSend && !environment.canAttemptHistoryRead) {
+        lines.push("mvp: send-first ready; local history is unavailable");
+        lines.push(`mvp blockers: ${environment.blockers.join(", ")}`);
+        return lines;
+    }
+    if (environment.blockers.length === 0) {
+        lines.push("mvp: not ready");
+        return lines;
+    }
+    lines.push(`mvp blockers: ${environment.blockers.join(", ")}`);
+    return lines;
+}

package/dist/send.d.ts

@@ -0,0 +1,23 @@
+import { type DetectIMessageMvpEnvironmentOptions } from "./mvp.js";
+export interface RunAppleScriptInput {
+    osascriptPath: string;
+    scriptLines: string[];
+    args: string[];
+}
+export interface RunAppleScriptResult {
+    stdout: string;
+    stderr: string;
+}
+export type RunAppleScript = (input: RunAppleScriptInput) => Promise<RunAppleScriptResult> | RunAppleScriptResult;
+export interface SendIMessageOptions {
+    recipient: string;
+    text: string;
+    osascriptPath?: string;
+    runAppleScript?: RunAppleScript;
+}
+export declare function normalizeIMessageRecipient(recipient: string): string;
+export declare function getDefaultIMessageThreadId(recipient: string): string;
+export declare function buildIMessageSendAppleScript(): string[];
+export declare function runAppleScript(input: RunAppleScriptInput): Promise<RunAppleScriptResult>;
+export declare function assertIMessageSendCapability(options?: DetectIMessageMvpEnvironmentOptions): void;
+export declare function sendIMessage(options: SendIMessageOptions): Promise<RunAppleScriptResult>;

package/dist/send.js

@@ -0,0 +1,55 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { APPLESCRIPT_BINARY_PATH, detectIMessageMvpEnvironment, formatIMessageMvpReadiness, } from "./mvp.js";
+const execFileAsync = promisify(execFile);
+export function normalizeIMessageRecipient(recipient) {
+    const normalized = recipient.trim();
+    if (!normalized) {
+        throw new Error("iMessage recipient is required.");
+    }
+    return normalized;
+}
+export function getDefaultIMessageThreadId(recipient) {
+    return `imessage:${normalizeIMessageRecipient(recipient).toLowerCase()}`;
+}
+export function buildIMessageSendAppleScript() {
+    return [
+        "on run argv",
+        "set recipientHandle to item 1 of argv",
+        "set messageBody to item 2 of argv",
+        'tell application "Messages"',
+        "set targetService to 1st service whose service type = iMessage",
+        "set targetBuddy to buddy recipientHandle of targetService",
+        "send messageBody to targetBuddy",
+        "end tell",
+        "end run",
+    ];
+}
+export async function runAppleScript(input) {
+    const args = [...input.scriptLines.flatMap((line) => ["-e", line]), ...input.args];
+    const result = await execFileAsync(input.osascriptPath, args);
+    return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+export function assertIMessageSendCapability(options = {}) {
+    const environment = detectIMessageMvpEnvironment(options);
+    if (environment.canAttemptSend) {
+        return;
+    }
+    throw new Error(["iMessage send-first adapter is not ready.", ...formatIMessageMvpReadiness(environment)].join(" "));
+}
+export async function sendIMessage(options) {
+    const recipient = normalizeIMessageRecipient(options.recipient);
+    const text = options.text.trim();
+    if (!text) {
+        throw new Error("iMessage text is required.");
+    }
+    const runner = options.runAppleScript ?? runAppleScript;
+    return runner({
+        osascriptPath: options.osascriptPath ?? APPLESCRIPT_BINARY_PATH,
+        scriptLines: buildIMessageSendAppleScript(),
+        args: [recipient, text],
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pinet/imessage-bridge",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "macOS/iMessage send-first adapter and readiness helpers for pi",
+  "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugu91/extensions.git",
+    "directory": "imessage-bridge"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/"
+  ],
+  "pi": {},
+  "scripts": {
+    "build": "node ../scripts/build-package.mjs",
+    "prepack": "pnpm run build",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@pinet/transport-core": "0.1.0"
+  },
+  "types": "./dist/index.d.ts"
+}