local-browser-bridge 0.1.0

package/dist/src/chrome-relay-helper.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHROME_RELAY_STATE_PATH_ENV = void 0;
+exports.getDefaultChromeRelayStateOutputPath = getDefaultChromeRelayStateOutputPath;
+exports.getHomeChromeRelayStateOutputPath = getHomeChromeRelayStateOutputPath;
+exports.resolveChromeRelayStateOutputPath = resolveChromeRelayStateOutputPath;
+exports.buildChromeRelayFixtureState = buildChromeRelayFixtureState;
+exports.writeChromeRelayStateSnapshot = writeChromeRelayStateSnapshot;
+exports.writeChromeRelayFixtureState = writeChromeRelayFixtureState;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const errors_1 = require("./errors");
+const chrome_relay_state_1 = require("./chrome-relay-state");
+exports.CHROME_RELAY_STATE_PATH_ENV = "LOCAL_BROWSER_BRIDGE_CHROME_RELAY_STATE_PATH";
+const DEFAULT_OUTPUT_PATH = ".local-browser-bridge/chrome-relay-state.json";
+function nowIso() {
+    return new Date().toISOString();
+}
+function oneHourFromNowIso() {
+    return new Date(Date.now() + 60 * 60 * 1000).toISOString();
+}
+function oneMinuteAgoIso() {
+    return new Date(Date.now() - 60 * 1000).toISOString();
+}
+function resolveSharedTab(options) {
+    return {
+        id: options.tabId ?? "tab-123",
+        title: options.title ?? "Relay Example",
+        url: options.url ?? "https://example.com/shared"
+    };
+}
+function getDefaultChromeRelayStateOutputPath() {
+    return (0, node_path_1.resolve)(process.cwd(), DEFAULT_OUTPUT_PATH);
+}
+function getHomeChromeRelayStateOutputPath() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), DEFAULT_OUTPUT_PATH);
+}
+function resolveChromeRelayStateOutputPath(explicitPath) {
+    const trimmedExplicit = explicitPath?.trim();
+    if (trimmedExplicit) {
+        return (0, node_path_1.resolve)(trimmedExplicit);
+    }
+    const configured = process.env[exports.CHROME_RELAY_STATE_PATH_ENV]?.trim();
+    if (configured) {
+        return (0, node_path_1.resolve)(configured);
+    }
+    return getDefaultChromeRelayStateOutputPath();
+}
+function buildChromeRelayFixtureState(options) {
+    const version = options.version?.trim() || "1.1.0";
+    const updatedAt = options.updatedAt?.trim() || nowIso();
+    if (options.flow === "extension-missing") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: false
+        };
+    }
+    if (options.flow === "disconnected") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: true,
+            connected: false
+        };
+    }
+    if (options.flow === "click-required") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: true,
+            connected: true,
+            userGestureRequired: true
+        };
+    }
+    if (options.flow === "share-required") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: true,
+            connected: true,
+            userGestureRequired: false,
+            shareRequired: true
+        };
+    }
+    if (options.flow === "clear-shared-tab") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: true,
+            connected: true,
+            userGestureRequired: false,
+            shareRequired: false,
+            sharedTab: null
+        };
+    }
+    if (options.flow === "shared-tab") {
+        return {
+            version,
+            updatedAt,
+            extensionInstalled: true,
+            connected: true,
+            userGestureRequired: false,
+            shareRequired: false,
+            resumable: options.resumable ?? true,
+            resumeRequiresUserGesture: options.resumeRequiresUserGesture ?? false,
+            expiresAt: options.expiresAt?.trim() || oneHourFromNowIso(),
+            sharedTab: resolveSharedTab(options)
+        };
+    }
+    return {
+        version,
+        updatedAt,
+        extensionInstalled: true,
+        connected: true,
+        userGestureRequired: false,
+        shareRequired: false,
+        resumable: options.resumable ?? false,
+        resumeRequiresUserGesture: options.resumeRequiresUserGesture ?? true,
+        expiresAt: options.expiresAt?.trim() || oneMinuteAgoIso(),
+        sharedTab: resolveSharedTab(options)
+    };
+}
+async function writeChromeRelayStateSnapshot(state, options) {
+    const validation = (0, chrome_relay_state_1.validateChromeRelayState)(state);
+    if (!validation.ok || !validation.probe) {
+        throw new errors_1.AppError(`Refusing to write invalid chrome relay state: ${validation.errors.join("; ")}`, 400, "invalid_relay_state");
+    }
+    const outputPath = resolveChromeRelayStateOutputPath(options?.outputPath);
+    await (0, promises_1.mkdir)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    const tempPath = `${outputPath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await (0, promises_1.writeFile)(tempPath, `${JSON.stringify(validation.probe, null, 2)}\n`, "utf8");
+        await (0, promises_1.rename)(tempPath, outputPath);
+    }
+    catch (error) {
+        await (0, promises_1.rm)(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return outputPath;
+}
+async function writeChromeRelayFixtureState(options) {
+    const state = buildChromeRelayFixtureState(options);
+    const path = await writeChromeRelayStateSnapshot(state, { outputPath: options.outputPath });
+    return {
+        flow: options.flow,
+        path,
+        state
+    };
+}

package/dist/src/chrome-relay-state.d.ts

@@ -0,0 +1,23 @@
+export interface ChromeRelayStateTabProbe {
+    id?: string;
+    url?: string;
+    title?: string;
+}
+export interface ChromeRelayStateProbe {
+    version?: string;
+    updatedAt?: string;
+    extensionInstalled?: boolean;
+    connected?: boolean;
+    userGestureRequired?: boolean;
+    shareRequired?: boolean;
+    resumable?: boolean;
+    expiresAt?: string;
+    resumeRequiresUserGesture?: boolean;
+    sharedTab?: ChromeRelayStateTabProbe | null;
+}
+export interface ChromeRelayStateValidationResult {
+    ok: boolean;
+    probe?: ChromeRelayStateProbe;
+    errors: string[];
+}
+export declare function validateChromeRelayState(raw: unknown): ChromeRelayStateValidationResult;

package/dist/src/chrome-relay-state.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateChromeRelayState = validateChromeRelayState;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === "boolean";
+}
+function isOptionalTimestamp(value) {
+    return value === undefined || (isNonEmptyString(value) && !Number.isNaN(Date.parse(value)));
+}
+function validateChromeRelayState(raw) {
+    if (!isRecord(raw)) {
+        return { ok: false, errors: ["relay state must be a JSON object"] };
+    }
+    const errors = [];
+    const sharedTabRaw = raw.sharedTab;
+    let sharedTab;
+    if (sharedTabRaw === null) {
+        sharedTab = null;
+    }
+    else if (sharedTabRaw === undefined) {
+        sharedTab = undefined;
+    }
+    else if (isRecord(sharedTabRaw)) {
+        const id = isNonEmptyString(sharedTabRaw.id) ? sharedTabRaw.id : undefined;
+        const url = isNonEmptyString(sharedTabRaw.url) ? sharedTabRaw.url : undefined;
+        const title = isNonEmptyString(sharedTabRaw.title) ? sharedTabRaw.title : undefined;
+        if ((sharedTabRaw.id !== undefined && id === undefined) || (sharedTabRaw.url !== undefined && url === undefined) || (sharedTabRaw.title !== undefined && title === undefined)) {
+            errors.push("sharedTab fields must be non-empty strings when present");
+        }
+        if (!id && !url && !title) {
+            errors.push("sharedTab must include at least one of id, url, or title");
+        }
+        sharedTab = { id, url, title };
+    }
+    else {
+        errors.push("sharedTab must be an object or null");
+    }
+    if (raw.version !== undefined && !isNonEmptyString(raw.version)) {
+        errors.push("version must be a non-empty string when present");
+    }
+    if (!isOptionalTimestamp(raw.updatedAt)) {
+        errors.push("updatedAt must be an ISO 8601 timestamp when present");
+    }
+    if (!isOptionalTimestamp(raw.expiresAt)) {
+        errors.push("expiresAt must be an ISO 8601 timestamp when present");
+    }
+    for (const key of ["extensionInstalled", "connected", "userGestureRequired", "shareRequired", "resumable", "resumeRequiresUserGesture"]) {
+        if (!isOptionalBoolean(raw[key])) {
+            errors.push(`${key} must be a boolean when present`);
+        }
+    }
+    const extensionInstalled = typeof raw.extensionInstalled === "boolean" ? raw.extensionInstalled : undefined;
+    const connected = typeof raw.connected === "boolean" ? raw.connected : undefined;
+    const userGestureRequired = typeof raw.userGestureRequired === "boolean" ? raw.userGestureRequired : undefined;
+    const shareRequired = typeof raw.shareRequired === "boolean" ? raw.shareRequired : undefined;
+    const resumable = typeof raw.resumable === "boolean" ? raw.resumable : undefined;
+    const resumeRequiresUserGesture = typeof raw.resumeRequiresUserGesture === "boolean" ? raw.resumeRequiresUserGesture : undefined;
+    const version = isNonEmptyString(raw.version) ? raw.version : undefined;
+    const updatedAt = isNonEmptyString(raw.updatedAt) ? raw.updatedAt : undefined;
+    const expiresAt = isNonEmptyString(raw.expiresAt) ? raw.expiresAt : undefined;
+    const hasSharedTabObject = sharedTab !== undefined && sharedTab !== null;
+    if (extensionInstalled === false && connected === true) {
+        errors.push("extensionInstalled=false cannot be combined with connected=true");
+    }
+    if (extensionInstalled === false && hasSharedTabObject) {
+        errors.push("extensionInstalled=false cannot be combined with sharedTab");
+    }
+    if (connected === false && hasSharedTabObject) {
+        errors.push("connected=false cannot be combined with sharedTab");
+    }
+    if (connected === false && shareRequired === true) {
+        errors.push("connected=false cannot be combined with shareRequired=true");
+    }
+    if (connected === false && userGestureRequired === true) {
+        errors.push("connected=false cannot be combined with userGestureRequired=true");
+    }
+    if (userGestureRequired === true && hasSharedTabObject) {
+        errors.push("userGestureRequired=true cannot be combined with sharedTab");
+    }
+    if (shareRequired === true && hasSharedTabObject) {
+        errors.push("shareRequired=true cannot be combined with sharedTab");
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return {
+        ok: true,
+        errors: [],
+        probe: {
+            version,
+            updatedAt,
+            extensionInstalled,
+            connected,
+            userGestureRequired,
+            shareRequired,
+            resumable,
+            expiresAt,
+            resumeRequiresUserGesture,
+            sharedTab
+        }
+    };
+}

package/dist/src/claude-code.d.ts

@@ -0,0 +1,20 @@
+import { type BridgeAdapter, type BridgeConnectionResult, type BridgeRoute, type BridgeSessionResult } from "./reference-adapter";
+import { type BrowserAttachUxInterpretation } from "./browser-attach-ux-helper";
+import type { BridgeCapabilitiesContract, BrowserDiagnostics } from "./types";
+export type ClaudeCodeRouteName = "safari" | "chrome-direct" | "chrome-relay";
+export interface ClaudeCodeRouteInput {
+    route: ClaudeCodeRouteName;
+    sessionId?: string;
+}
+export interface ClaudeCodePreparedRoute<TCapabilities = BridgeCapabilitiesContract, TResult extends BridgeSessionResult = BridgeSessionResult> {
+    blocked: boolean;
+    capabilities: TCapabilities;
+    diagnostics: BrowserDiagnostics;
+    operation: "attach" | "resumeSession";
+    route: BridgeRoute;
+    routeUx: BrowserAttachUxInterpretation;
+    prompt?: string;
+    connection?: BridgeConnectionResult<TCapabilities, TResult>;
+}
+export declare function normalizeClaudeCodeRoute(input: ClaudeCodeRouteInput): BridgeRoute;
+export declare function prepareClaudeCodeRoute<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends BridgeSessionResult = BridgeSessionResult>(adapter: BridgeAdapter<TCapabilities, TAttachResult, TResumeResult>, input: ClaudeCodeRouteInput): Promise<ClaudeCodePreparedRoute<TCapabilities, TAttachResult | TResumeResult>>;

package/dist/src/claude-code.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClaudeCodeRoute = normalizeClaudeCodeRoute;
+exports.prepareClaudeCodeRoute = prepareClaudeCodeRoute;
+const reference_adapter_1 = require("./reference-adapter");
+const browser_attach_ux_helper_1 = require("./browser-attach-ux-helper");
+function toBrowser(route) {
+    return route === "safari" ? "safari" : "chrome";
+}
+function toAttachMode(route) {
+    return route === "chrome-relay" ? "relay" : "direct";
+}
+function normalizeClaudeCodeRoute(input) {
+    const browser = toBrowser(input.route);
+    const attachMode = toAttachMode(input.route);
+    return input.sessionId ? { browser, attachMode, sessionId: input.sessionId } : { browser, attachMode };
+}
+async function prepareClaudeCodeRoute(adapter, input) {
+    const route = normalizeClaudeCodeRoute(input);
+    const capabilities = await adapter.getCapabilities();
+    const diagnostics = await adapter.getDiagnostics(route.browser);
+    const operation = "sessionId" in route ? "resumeSession" : "attach";
+    const routeUx = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromDiagnostics)({
+        browser: route.browser,
+        attachMode: route.attachMode ?? "direct",
+        diagnostics,
+        operation
+    });
+    if (routeUx.state === "blocked") {
+        return {
+            blocked: true,
+            capabilities,
+            diagnostics,
+            operation,
+            route,
+            routeUx,
+            prompt: routeUx.prompt
+        };
+    }
+    const result = "sessionId" in route ? await adapter.resume(route.sessionId) : await adapter.attach(route);
+    const session = (0, reference_adapter_1.sessionFromBridgeResult)(result);
+    const sessionUx = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromSession)({
+        session,
+        operation
+    });
+    const connection = {
+        capabilities,
+        diagnostics,
+        operation,
+        route,
+        routeUx,
+        result,
+        session,
+        sessionUx
+    };
+    return {
+        blocked: false,
+        capabilities,
+        diagnostics,
+        operation,
+        route,
+        routeUx,
+        prompt: connection.sessionUx.prompt ?? connection.routeUx.prompt,
+        connection
+    };
+}

package/dist/src/cli-reference-adapter.d.ts

@@ -0,0 +1,13 @@
+import { type BridgeAdapter, type BridgeSessionResult } from "./reference-adapter";
+import type { BridgeCapabilitiesContract, ResumedSession } from "./types";
+export interface CliBridgeCommand {
+    args: string[];
+}
+export interface CliBridgeCommandResult {
+    stdout: string;
+}
+export type CliBridgeExecutor = (command: CliBridgeCommand) => Promise<CliBridgeCommandResult>;
+export interface CreateCliBridgeAdapterOptions<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession> {
+    execute: CliBridgeExecutor;
+}
+export declare function createCliBridgeAdapter<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession>(options: CreateCliBridgeAdapterOptions<TCapabilities, TAttachResult, TResumeResult>): BridgeAdapter<TCapabilities, TAttachResult, TResumeResult>;

package/dist/src/cli-reference-adapter.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCliBridgeAdapter = createCliBridgeAdapter;
+const errors_1 = require("./errors");
+const reference_adapter_1 = require("./reference-adapter");
+function parseJsonEnvelope(stdout, context) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new errors_1.AppError(`Expected ${context} command to return valid JSON.`, 500, "invalid_transport_response", { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+function requireEnvelopeField(envelope, key, context) {
+    const value = envelope[key];
+    if (value === undefined || value === null) {
+        throw new errors_1.AppError(`Expected ${context} command output to include ${String(key)}.`, 500, "invalid_transport_response");
+    }
+    return value;
+}
+async function runCommand(execute, args, context) {
+    const result = await execute({ args });
+    return parseJsonEnvelope(result.stdout, context);
+}
+function createCliBridgeAdapter(options) {
+    return (0, reference_adapter_1.createBridgeAdapter)({
+        async getCapabilities() {
+            const envelope = await runCommand(options.execute, ["capabilities"], "capabilities");
+            return requireEnvelopeField(envelope, "capabilities", "capabilities");
+        },
+        async getDiagnostics(browser) {
+            const envelope = await runCommand(options.execute, ["diagnostics", "--browser", browser], "diagnostics");
+            return requireEnvelopeField(envelope, "diagnostics", "diagnostics");
+        },
+        async attach(args) {
+            const commandArgs = ["attach", "--browser", args.browser];
+            if (args.attachMode) {
+                commandArgs.push("--attach-mode", args.attachMode);
+            }
+            const envelope = await runCommand(options.execute, commandArgs, "attach");
+            return requireEnvelopeField(envelope, "session", "attach");
+        },
+        async resume(sessionId) {
+            const envelope = await runCommand(options.execute, ["resume", "--id", sessionId], "resumeSession");
+            return requireEnvelopeField(envelope, "resumedSession", "resumeSession");
+        }
+    });
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { AttachService } from "./service/attach-service";
+export declare function runCli(args: string[], service?: AttachService): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const http_1 = require("./http");
+const browser_1 = require("./browser");
+const attach_service_1 = require("./service/attach-service");
+const errors_1 = require("./errors");
+const target_1 = require("./target");
+const connection_ux_1 = require("./connection-ux");
+function printUsage() {
+    process.stdout.write([
+        "Usage:",
+        "  local-browser-bridge front-tab [--browser safari|chrome]",
+        "  local-browser-bridge tab [--browser safari|chrome] (--window-index 1 --tab-index 2 | --signature <signature>)",
+        "  local-browser-bridge tabs [--browser safari|chrome]",
+        "  local-browser-bridge attach [--browser safari|chrome] [--attach-mode direct|relay] [--window-index 1 --tab-index 2 | --signature <signature>]",
+        "  local-browser-bridge activate [--browser safari|chrome] [--window-index 1 --tab-index 2 | --signature <signature>]",
+        "  local-browser-bridge navigate [--browser safari|chrome] [--window-index 1 --tab-index 2 | --signature <signature>] --url <url>",
+        "  local-browser-bridge screenshot [--browser safari|chrome] [--window-index 1 --tab-index 2 | --signature <signature>] [--output <path>]",
+        "  local-browser-bridge capabilities [--browser safari|chrome]",
+        "  local-browser-bridge diagnostics [--browser safari|chrome]",
+        "  local-browser-bridge doctor --route safari|chrome-direct|chrome-relay [--session-id <session-id>]",
+        "  local-browser-bridge connect --route safari|chrome-direct|chrome-relay [--session-id <session-id>]",
+        "  local-browser-bridge sessions",
+        "  local-browser-bridge session --id <session-id>",
+        "  local-browser-bridge resume --id <session-id>",
+        "  local-browser-bridge session-activate --id <session-id>",
+        "  local-browser-bridge session-navigate --id <session-id> --url <url>",
+        "  local-browser-bridge session-screenshot --id <session-id> [--output <path>]",
+        "  local-browser-bridge serve [--host 127.0.0.1] [--port 3000]",
+        "",
+        "Safari is the primary adapter. Chrome/Chromium is descriptor/stub-only in this phase.",
+        "Compatibility: the safari-attach-tool binary name still works as an alias."
+    ].join("\n") + "\n");
+}
+function readFlag(args, name, fallback) {
+    const index = args.indexOf(name);
+    if (index === -1) {
+        return fallback;
+    }
+    return args[index + 1] ?? fallback;
+}
+function readTarget(args) {
+    return (0, target_1.buildTabTarget)({
+        windowIndex: readFlag(args, "--window-index"),
+        tabIndex: readFlag(args, "--tab-index"),
+        signature: readFlag(args, "--signature"),
+        url: readFlag(args, "--url"),
+        title: readFlag(args, "--title")
+    });
+}
+function readOutputPath(args) {
+    return readFlag(args, "--output");
+}
+function readAttachMode(args) {
+    const value = readFlag(args, "--attach-mode")?.trim();
+    if (!value) {
+        return undefined;
+    }
+    if (value === "direct" || value === "relay") {
+        return value;
+    }
+    throw new errors_1.AppError("--attach-mode must be direct or relay.", 400, "invalid_attach_mode");
+}
+function readRequiredFlag(args, name, code) {
+    const value = readFlag(args, name)?.trim();
+    if (!value) {
+        throw new errors_1.AppError(`${name} is required.`, 400, code);
+    }
+    return value;
+}
+function readRequiredRoute(args) {
+    return (0, connection_ux_1.normalizeConnectionRouteName)(readRequiredFlag(args, "--route", "missing_route"));
+}
+function writeJson(payload) {
+    (0, errors_1.writeJsonLine)(process.stdout, payload);
+}
+async function runCli(args, service = new attach_service_1.AttachService()) {
+    const command = args[0];
+    if (!command || command === "--help" || command === "-h") {
+        printUsage();
+        return;
+    }
+    if (command === "front-tab") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ frontTab: await service.inspectFrontTab(browser) });
+        return;
+    }
+    if (command === "tab") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ tab: await service.inspectTab(browser, readTarget(args)) });
+        return;
+    }
+    if (command === "tabs") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ tabs: await service.listTabs(browser) });
+        return;
+    }
+    if (command === "attach") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({
+            session: await service.attach(browser, {
+                target: readTarget(args),
+                attach: { mode: readAttachMode(args) }
+            })
+        });
+        return;
+    }
+    if (command === "activate") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ activation: await service.activate(browser, readTarget(args)) });
+        return;
+    }
+    if (command === "navigate") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        const url = readRequiredFlag(args, "--url", "missing_url");
+        writeJson({ navigation: await service.navigate(browser, readTarget(args), { url }) });
+        return;
+    }
+    if (command === "screenshot") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ screenshot: await service.screenshot(browser, readTarget(args), { outputPath: readOutputPath(args) }) });
+        return;
+    }
+    if (command === "capabilities") {
+        const browserFlag = readFlag(args, "--browser");
+        const browser = browserFlag ? (0, browser_1.normalizeBrowser)(browserFlag) : undefined;
+        writeJson({ capabilities: service.getCapabilities(browser) });
+        return;
+    }
+    if (command === "diagnostics") {
+        const browser = (0, browser_1.normalizeBrowser)(readFlag(args, "--browser"));
+        writeJson({ diagnostics: await service.diagnostics(browser) });
+        return;
+    }
+    if (command === "doctor") {
+        writeJson(await (0, connection_ux_1.doctorConnectionRoute)(service, {
+            route: readRequiredRoute(args),
+            sessionId: readFlag(args, "--session-id")
+        }));
+        return;
+    }
+    if (command === "connect") {
+        writeJson(await (0, connection_ux_1.connectConnectionRoute)(service, {
+            route: readRequiredRoute(args),
+            sessionId: readFlag(args, "--session-id")
+        }));
+        return;
+    }
+    if (command === "sessions") {
+        writeJson({ sessions: await service.listSessions() });
+        return;
+    }
+    if (command === "session") {
+        const id = readRequiredFlag(args, "--id", "missing_id");
+        writeJson({ session: await service.getSession(id) });
+        return;
+    }
+    if (command === "resume") {
+        const id = readRequiredFlag(args, "--id", "missing_id");
+        writeJson({ resumedSession: await service.resumeSession(id) });
+        return;
+    }
+    if (command === "session-activate") {
+        const id = readRequiredFlag(args, "--id", "missing_id");
+        writeJson({ sessionActivation: await service.activateSession(id) });
+        return;
+    }
+    if (command === "session-navigate") {
+        const id = readRequiredFlag(args, "--id", "missing_id");
+        const url = readRequiredFlag(args, "--url", "missing_url");
+        writeJson({ sessionNavigation: await service.navigateSession(id, { url }) });
+        return;
+    }
+    if (command === "session-screenshot") {
+        const id = readRequiredFlag(args, "--id", "missing_id");
+        writeJson({ sessionScreenshot: await service.screenshotSession(id, { outputPath: readOutputPath(args) }) });
+        return;
+    }
+    if (command === "serve") {
+        const host = readFlag(args, "--host", "127.0.0.1") ?? "127.0.0.1";
+        const port = Number(readFlag(args, "--port", "3000") ?? "3000");
+        const server = (0, http_1.createApiServer)(service);
+        await new Promise((resolve) => server.listen(port, host, resolve));
+        process.stdout.write(`Server listening on http://${host}:${port}\n`);
+        return;
+    }
+    throw new errors_1.AppError(`Unknown command: ${command}`, 400, "unknown_command");
+}
+async function main() {
+    await runCli(process.argv.slice(2));
+}
+if (require.main === module) {
+    main().catch((error) => {
+        const { payload } = (0, errors_1.toErrorPayload)(error);
+        (0, errors_1.writeJsonLine)(process.stderr, payload);
+        process.exitCode = 1;
+    });
+}

package/dist/src/codex.d.ts

@@ -0,0 +1,17 @@
+import { type BridgeConnectionResult, type BridgeSessionResult } from "./reference-adapter";
+import { type CliBridgeExecutor, type CreateCliBridgeAdapterOptions } from "./cli-reference-adapter";
+import { type CreateHttpBridgeAdapterOptions, type HttpBridgeExecutor } from "./http-reference-adapter";
+import type { BridgeCapabilitiesContract, ResumedSession } from "./types";
+export type CodexRouteName = "safari" | "chrome-direct" | "chrome-relay";
+export interface CodexRouteInput {
+    route: CodexRouteName;
+    sessionId?: string;
+}
+export interface ConnectCodexViaCliOptions<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession> extends CodexRouteInput, CreateCliBridgeAdapterOptions<TCapabilities, TAttachResult, TResumeResult> {
+}
+export interface ConnectCodexViaHttpOptions<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession> extends CodexRouteInput, CreateHttpBridgeAdapterOptions<TCapabilities, TAttachResult, TResumeResult> {
+}
+export declare function normalizeCodexRoute(route: CodexRouteName, sessionId?: string): import("./reference-adapter").BridgeRoute;
+export declare function connectCodexViaCli<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession>(options: ConnectCodexViaCliOptions<TCapabilities, TAttachResult, TResumeResult>): Promise<BridgeConnectionResult<TCapabilities, TAttachResult | TResumeResult>>;
+export declare function connectCodexViaHttp<TCapabilities = BridgeCapabilitiesContract, TAttachResult extends BridgeSessionResult = BridgeSessionResult, TResumeResult extends ResumedSession = ResumedSession>(options: ConnectCodexViaHttpOptions<TCapabilities, TAttachResult, TResumeResult>): Promise<BridgeConnectionResult<TCapabilities, TAttachResult | TResumeResult>>;
+export type { CliBridgeExecutor, HttpBridgeExecutor };