local-browser-bridge 0.1.0

package/dist/tests/codex.test.js

@@ -0,0 +1,210 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const codex_1 = require("../src/codex");
+const capabilities = {
+    schemaVersion: 1,
+    kind: "local-browser-bridge",
+    product: { name: "local-browser-bridge", version: "0.1.0" }
+};
+const diagnostics = {
+    browser: "chrome",
+    checkedAt: "2026-03-30T12:00:00.000Z",
+    runtime: {
+        platform: "darwin",
+        arch: "arm64",
+        nodeVersion: "v25.8.0",
+        safariRunning: true
+    },
+    host: {
+        osascriptAvailable: true,
+        screencaptureAvailable: true,
+        safariApplicationAvailable: true
+    },
+    supportedFeatures: {
+        inspectTabs: true,
+        attach: true,
+        activate: true,
+        navigate: true,
+        screenshot: true,
+        savedSessions: true,
+        cli: true,
+        httpApi: true
+    },
+    constraints: [],
+    attach: {
+        direct: {
+            mode: "direct",
+            source: "user-browser",
+            scope: "browser",
+            supported: true,
+            ready: false,
+            state: "attention-required",
+            blockers: []
+        },
+        relay: {
+            mode: "relay",
+            source: "extension-relay",
+            scope: "tab",
+            supported: true,
+            ready: true,
+            state: "ready",
+            blockers: []
+        }
+    }
+};
+const session = {
+    schemaVersion: 1,
+    id: "sess-codex-relay",
+    kind: "chrome-readonly",
+    browser: "chrome",
+    target: { type: "front" },
+    tab: {
+        browser: "chrome",
+        windowIndex: 1,
+        tabIndex: 1,
+        title: "Shared tab",
+        url: "https://example.com",
+        attachedAt: "2026-03-30T12:00:00.000Z",
+        identity: {
+            signature: "sig",
+            urlKey: "https://example.com",
+            titleKey: "Shared tab",
+            origin: "https://example.com",
+            pathname: "/"
+        }
+    },
+    frontTab: {
+        browser: "chrome",
+        windowIndex: 1,
+        tabIndex: 1,
+        title: "Shared tab",
+        url: "https://example.com",
+        attachedAt: "2026-03-30T12:00:00.000Z",
+        identity: {
+            signature: "sig",
+            urlKey: "https://example.com",
+            titleKey: "Shared tab",
+            origin: "https://example.com",
+            pathname: "/"
+        }
+    },
+    attach: {
+        mode: "relay",
+        source: "extension-relay",
+        scope: "tab",
+        resumable: true
+    },
+    semantics: {
+        inspect: "shared-tab-only",
+        list: "saved-session",
+        resume: "current-shared-tab",
+        tabReference: {
+            windowIndex: "synthetic-shared-tab-position",
+            tabIndex: "synthetic-shared-tab-position"
+        }
+    },
+    capabilities: {
+        resume: true,
+        activate: false,
+        navigate: false,
+        screenshot: false
+    },
+    status: {
+        state: "read-only",
+        canAct: false
+    },
+    createdAt: "2026-03-30T12:00:00.000Z"
+};
+const resumedSession = {
+    session: {
+        ...session,
+        id: "sess-codex-relay-resumed"
+    },
+    tab: session.tab,
+    resumedAt: "2026-03-30T12:05:00.000Z",
+    resolution: {
+        strategy: "front",
+        matched: true,
+        attachMode: "relay",
+        semantics: "current-shared-tab"
+    }
+};
+(0, node_test_1.default)("normalizeCodexRoute maps Codex route names into bridge routes", () => {
+    strict_1.default.deepEqual((0, codex_1.normalizeCodexRoute)("safari"), {
+        browser: "safari",
+        attachMode: "direct"
+    });
+    strict_1.default.deepEqual((0, codex_1.normalizeCodexRoute)("chrome-direct"), {
+        browser: "chrome",
+        attachMode: "direct"
+    });
+    strict_1.default.deepEqual((0, codex_1.normalizeCodexRoute)("chrome-relay", "sess-1"), {
+        browser: "chrome",
+        attachMode: "relay",
+        sessionId: "sess-1"
+    });
+});
+(0, node_test_1.default)("connectCodexViaHttp reuses the shared HTTP adapter and route flow", async () => {
+    const requests = [];
+    const connection = await (0, codex_1.connectCodexViaHttp)({
+        route: "chrome-relay",
+        async execute(request) {
+            requests.push(request);
+            if (request.method === "GET" && request.path === "/v1/capabilities") {
+                return { body: { capabilities } };
+            }
+            if (request.method === "GET" && request.path === "/v1/diagnostics?browser=chrome") {
+                return { body: { diagnostics } };
+            }
+            if (request.method === "POST" && request.path === "/v1/attach") {
+                return { body: { session } };
+            }
+            throw new Error(`Unexpected request: ${request.method} ${request.path}`);
+        }
+    });
+    strict_1.default.equal(connection.operation, "attach");
+    strict_1.default.equal(connection.routeUx.label, "Chrome (shared tab, read-only)");
+    strict_1.default.equal(connection.session.id, "sess-codex-relay");
+    strict_1.default.deepEqual(requests, [
+        { method: "GET", path: "/v1/capabilities" },
+        { method: "GET", path: "/v1/diagnostics?browser=chrome" },
+        {
+            method: "POST",
+            path: "/v1/attach",
+            body: { browser: "chrome", attach: { mode: "relay" } }
+        }
+    ]);
+});
+(0, node_test_1.default)("connectCodexViaCli reuses the shared CLI adapter and resume flow", async () => {
+    const commands = [];
+    const connection = await (0, codex_1.connectCodexViaCli)({
+        route: "chrome-relay",
+        sessionId: "sess-codex-relay-resumed",
+        async execute(command) {
+            commands.push(command.args);
+            if (command.args[0] === "capabilities") {
+                return { stdout: JSON.stringify({ capabilities }) };
+            }
+            if (command.args[0] === "diagnostics") {
+                return { stdout: JSON.stringify({ diagnostics }) };
+            }
+            if (command.args[0] === "resume") {
+                return { stdout: JSON.stringify({ resumedSession }) };
+            }
+            throw new Error(`Unexpected command: ${command.args.join(" ")}`);
+        }
+    });
+    strict_1.default.equal(connection.operation, "resumeSession");
+    strict_1.default.equal(connection.session.id, "sess-codex-relay-resumed");
+    strict_1.default.equal(connection.sessionUx.sharedTabScoped, true);
+    strict_1.default.deepEqual(commands, [
+        ["capabilities"],
+        ["diagnostics", "--browser", "chrome"],
+        ["resume", "--id", "sess-codex-relay-resumed"]
+    ]);
+});

package/dist/tests/demo-client-smoke.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/demo-client-smoke.test.js

@@ -0,0 +1,405 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_http_1 = require("node:http");
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function createCapabilitiesPayload() {
+    return {
+        capabilities: {
+            schemaVersion: 1,
+            browsers: [
+                {
+                    browser: "safari",
+                    kind: "safari-actionable",
+                    operations: {
+                        attach: true,
+                        diagnostics: true,
+                        resumeSession: true,
+                        activate: true,
+                        navigate: true,
+                        screenshot: true
+                    }
+                },
+                {
+                    browser: "chrome",
+                    kind: "chrome-readonly",
+                    operations: {
+                        attach: true,
+                        diagnostics: true,
+                        resumeSession: true,
+                        activate: false,
+                        navigate: false,
+                        screenshot: false
+                    }
+                }
+            ]
+        }
+    };
+}
+function createSafariDiagnostics(blockers = []) {
+    const ready = blockers.length === 0;
+    return {
+        diagnostics: {
+            browser: "safari",
+            checkedAt: "2026-03-28T12:00:00.000Z",
+            preflight: {
+                inspect: { ready, blockers },
+                automation: { ready, blockers },
+                screenshot: { ready: true, blockers: [] }
+            }
+        }
+    };
+}
+function createChromeDiagnostics(args) {
+    return {
+        diagnostics: {
+            browser: "chrome",
+            checkedAt: "2026-03-28T12:00:00.000Z",
+            attach: {
+                direct: {
+                    mode: "direct",
+                    ready: args.direct.ready,
+                    state: args.direct.state,
+                    blockers: args.direct.blockers ?? []
+                },
+                relay: {
+                    mode: "relay",
+                    ready: args.relay.ready,
+                    state: args.relay.state,
+                    blockers: args.relay.blockers ?? []
+                }
+            }
+        }
+    };
+}
+function createSafariSession() {
+    return {
+        session: {
+            id: "session-safari-demo",
+            schemaVersion: 1,
+            browser: "safari",
+            kind: "safari-actionable",
+            attach: { mode: "direct", scope: "browser" },
+            semantics: {
+                inspect: "browser-tabs",
+                resume: "saved-browser-target",
+                tabReference: { windowIndex: "browser-position", tabIndex: "browser-position" }
+            },
+            capabilities: { resume: true, activate: true, navigate: true, screenshot: true },
+            status: { state: "actionable", canAct: true }
+        }
+    };
+}
+function createChromeDirectSession() {
+    return {
+        session: {
+            id: "session-chrome-direct-demo",
+            schemaVersion: 1,
+            browser: "chrome",
+            kind: "chrome-readonly",
+            attach: { mode: "direct", scope: "browser" },
+            semantics: {
+                inspect: "browser-tabs",
+                resume: "saved-browser-target",
+                tabReference: { windowIndex: "browser-position", tabIndex: "browser-position" }
+            },
+            capabilities: { resume: true, activate: false, navigate: false, screenshot: false },
+            status: { state: "read-only", canAct: false }
+        }
+    };
+}
+function createChromeRelaySession() {
+    return {
+        session: {
+            id: "session-chrome-relay-demo",
+            schemaVersion: 1,
+            browser: "chrome",
+            kind: "chrome-readonly",
+            attach: {
+                mode: "relay",
+                scope: "tab",
+                resumable: false,
+                resumeRequiresUserGesture: true,
+                expiresAt: "2099-03-28T12:00:00.000Z"
+            },
+            semantics: {
+                inspect: "shared-tab-only",
+                resume: "current-shared-tab",
+                tabReference: {
+                    windowIndex: "synthetic-shared-tab-position",
+                    tabIndex: "synthetic-shared-tab-position"
+                }
+            },
+            capabilities: { resume: true, activate: false, navigate: false, screenshot: false },
+            status: { state: "read-only", canAct: false }
+        }
+    };
+}
+async function readJsonBody(request) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    if (chunks.length === 0) {
+        return undefined;
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function writeStubJson(response, payload, successStatusCode) {
+    const statusCode = payload && typeof payload === "object" && "error" in payload && payload.error && typeof payload.error === "object" && "statusCode" in payload.error
+        ? Number(payload.error.statusCode)
+        : successStatusCode;
+    response.writeHead(statusCode, { "content-type": "application/json" });
+    response.end(JSON.stringify(payload));
+}
+async function withStubBridge(state, run) {
+    const server = (0, node_http_1.createServer)(async (request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        const body = request.method === "POST" ? await readJsonBody(request) : undefined;
+        state.requests.push({ method: request.method, url: `${url.pathname}${url.search}`, body });
+        if (request.method === "GET" && url.pathname === "/v1/capabilities") {
+            response.writeHead(200, { "content-type": "application/json" });
+            response.end(JSON.stringify(state.capabilities));
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/v1/diagnostics") {
+            const browser = url.searchParams.get("browser") ?? "";
+            response.writeHead(200, { "content-type": "application/json" });
+            response.end(JSON.stringify(state.diagnosticsByBrowser[browser]));
+            return;
+        }
+        if (request.method === "POST" && url.pathname === "/v1/attach") {
+            const attachMode = body && typeof body === "object" && "attach" in body && body.attach && typeof body.attach === "object" && "mode" in body.attach
+                ? String(body.attach.mode)
+                : "direct";
+            writeStubJson(response, state.attachResponseByMode[attachMode], 201);
+            return;
+        }
+        if (request.method === "POST" && url.pathname.startsWith("/v1/sessions/") && url.pathname.endsWith("/resume")) {
+            writeStubJson(response, state.resumeResponse, 200);
+            return;
+        }
+        response.writeHead(404, { "content-type": "application/json" });
+        response.end(JSON.stringify({ error: { code: "not_found", message: "not found", statusCode: 404 } }));
+    });
+    await new Promise((resolvePromise) => server.listen(0, "127.0.0.1", resolvePromise));
+    const address = server.address();
+    strict_1.default.ok(address && typeof address === "object");
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+    try {
+        return await run(baseUrl);
+    }
+    finally {
+        await new Promise((resolvePromise, reject) => server.close((error) => (error ? reject(error) : resolvePromise())));
+    }
+}
+async function runDemo(route, args) {
+    return await execFileAsync(process.execPath, ["--experimental-strip-types", "examples/clients/http-node.ts", route], {
+        cwd: process.cwd(),
+        env: {
+            ...process.env,
+            LOCAL_BROWSER_BRIDGE_URL: args?.baseUrl,
+            LOCAL_BROWSER_BRIDGE_SESSION_ID: args?.sessionId
+        }
+    });
+}
+(0, node_test_1.default)("http demo smoke: safari route uses capabilities + diagnostics and renders actionable labeling", async () => {
+    const state = {
+        capabilities: createCapabilitiesPayload(),
+        diagnosticsByBrowser: {
+            safari: createSafariDiagnostics(),
+            chrome: createChromeDiagnostics({
+                direct: { ready: false, state: "unavailable" },
+                relay: { ready: false, state: "unavailable" }
+            })
+        },
+        attachResponseByMode: {
+            direct: createSafariSession(),
+            relay: createChromeRelaySession()
+        },
+        requests: []
+    };
+    await withStubBridge(state, async (baseUrl) => {
+        const result = await runDemo("safari", { baseUrl });
+        strict_1.default.match(result.stdout, /Requested route: safari/);
+        strict_1.default.match(result.stdout, /Capabilities: kind=safari-actionable/);
+        strict_1.default.match(result.stdout, /Selected path: Safari \(actionable\)/);
+        strict_1.default.match(result.stdout, /Diagnostics readiness: state=ready, ready=true/);
+        strict_1.default.match(result.stdout, /Attaching via Safari \(actionable\)/);
+        strict_1.default.match(result.stdout, /Session kind: safari-actionable/);
+        strict_1.default.match(result.stdout, /User-facing label: Safari \(actionable\)/);
+        strict_1.default.match(result.stdout, /Runtime actions: activate=true, navigate=true, screenshot=true/);
+        strict_1.default.deepEqual(state.requests.map((entry) => `${entry.method} ${entry.url}`), ["GET /v1/capabilities", "GET /v1/diagnostics?browser=safari", "POST /v1/attach"]);
+        strict_1.default.deepEqual(state.requests[2]?.body, {
+            browser: "safari",
+            attach: { mode: "direct" }
+        });
+    });
+});
+(0, node_test_1.default)("http demo smoke: chrome-direct route renders read-only browser path and no silent relay fallback", async () => {
+    const state = {
+        capabilities: createCapabilitiesPayload(),
+        diagnosticsByBrowser: {
+            chrome: createChromeDiagnostics({
+                direct: { ready: true, state: "ready" },
+                relay: {
+                    ready: false,
+                    state: "attention-required",
+                    blockers: [{ code: "relay_share_required", message: "share first" }]
+                }
+            }),
+            safari: createSafariDiagnostics()
+        },
+        attachResponseByMode: {
+            direct: createChromeDirectSession(),
+            relay: createChromeRelaySession()
+        },
+        requests: []
+    };
+    await withStubBridge(state, async (baseUrl) => {
+        const result = await runDemo("chrome-direct", { baseUrl });
+        strict_1.default.match(result.stdout, /Requested route: chrome-direct/);
+        strict_1.default.match(result.stdout, /Capabilities: kind=chrome-readonly/);
+        strict_1.default.match(result.stdout, /Selected path: Chrome \(direct, read-only\)/);
+        strict_1.default.match(result.stdout, /Diagnostics readiness: state=ready, ready=true/);
+        strict_1.default.match(result.stdout, /Attaching via Chrome \(direct, read-only\)/);
+        strict_1.default.match(result.stdout, /Session kind: chrome-readonly/);
+        strict_1.default.match(result.stdout, /Session attach mode: direct/);
+        strict_1.default.match(result.stdout, /Flow state: attached/);
+        strict_1.default.match(result.stdout, /User-facing label: Chrome \(direct, read-only\)/);
+        strict_1.default.match(result.stdout, /Show inspect\/resume UI only\. Hide activate\/navigate\/screenshot\./);
+        strict_1.default.deepEqual(state.requests.map((entry) => `${entry.method} ${entry.url}`), ["GET /v1/capabilities", "GET /v1/diagnostics?browser=chrome", "POST /v1/attach"]);
+        strict_1.default.deepEqual(state.requests[2]?.body, {
+            browser: "chrome",
+            attach: { mode: "direct" }
+        });
+    });
+});
+(0, node_test_1.default)("http demo smoke: chrome-relay route renders shared-tab labeling and relay resume prompt", async () => {
+    const state = {
+        capabilities: createCapabilitiesPayload(),
+        diagnosticsByBrowser: {
+            chrome: createChromeDiagnostics({
+                direct: { ready: false, state: "unavailable" },
+                relay: { ready: true, state: "ready" }
+            }),
+            safari: createSafariDiagnostics()
+        },
+        attachResponseByMode: {
+            direct: createChromeDirectSession(),
+            relay: createChromeRelaySession()
+        },
+        requests: [],
+        resumeResponse: {
+            resumedSession: createChromeRelaySession()
+        }
+    };
+    await withStubBridge(state, async (baseUrl) => {
+        const result = await runDemo("chrome-relay", { baseUrl, sessionId: "saved-relay-session" });
+        strict_1.default.match(result.stdout, /Requested route: chrome-relay/);
+        strict_1.default.match(result.stdout, /Selected path: Chrome \(shared tab, read-only\)/);
+        strict_1.default.match(result.stdout, /Diagnostics readiness: state=ready, ready=true/);
+        strict_1.default.match(result.stdout, /Resuming saved session saved-relay-session for Chrome \(shared tab, read-only\)/);
+        strict_1.default.match(result.stdout, /Session kind: chrome-readonly/);
+        strict_1.default.match(result.stdout, /Session attach mode: relay/);
+        strict_1.default.match(result.stdout, /Flow state: resumed/);
+        strict_1.default.match(result.stdout, /User-facing label: Chrome \(shared tab, read-only\)/);
+        strict_1.default.match(result.stdout, /Describe this as a shared-tab session, not a browser-wide Chrome session\./);
+        strict_1.default.match(result.stdout, /Derive relay behavior from attach\.mode=relay plus the returned semantics fields\./);
+        strict_1.default.match(result.stdout, /Inspect semantics: shared-tab-only/);
+        strict_1.default.match(result.stdout, /Resume semantics: current-shared-tab/);
+        strict_1.default.match(result.stdout, /Tab reference semantics: windowIndex=synthetic-shared-tab-position, tabIndex=synthetic-shared-tab-position/);
+        strict_1.default.match(result.stdout, /Scope note: Chrome relay is still limited to the currently shared tab and remains read-only\./);
+        strict_1.default.match(result.stdout, /Resume prompt: That shared-tab grant is no longer active\. Click the relay extension again on the original tab, then retry resume\./);
+        strict_1.default.deepEqual(state.requests.map((entry) => `${entry.method} ${entry.url}`), ["GET /v1/capabilities", "GET /v1/diagnostics?browser=chrome", "POST /v1/sessions/saved-relay-session/resume"]);
+    });
+});
+(0, node_test_1.default)("http demo smoke: relay attach failures surface structured relay branch prompts", async () => {
+    const state = {
+        capabilities: createCapabilitiesPayload(),
+        diagnosticsByBrowser: {
+            chrome: createChromeDiagnostics({
+                direct: { ready: true, state: "ready" },
+                relay: { ready: true, state: "ready" }
+            }),
+            safari: createSafariDiagnostics()
+        },
+        attachResponseByMode: {
+            direct: createChromeDirectSession(),
+            relay: {
+                error: {
+                    code: "relay_attach_target_out_of_scope",
+                    message: "Chrome relay attach is scoped to the currently shared tab only; use the front tab target or omit an explicit target.",
+                    statusCode: 409,
+                    details: {
+                        context: { browser: "chrome", attachMode: "relay", operation: "attach" },
+                        relay: {
+                            branch: "use-current-shared-tab",
+                            retryable: true,
+                            userActionRequired: true,
+                            phase: "target-selection",
+                            sharedTabScope: "current-shared-tab",
+                            currentSharedTabMatches: false
+                        }
+                    }
+                }
+            }
+        },
+        requests: []
+    };
+    await withStubBridge(state, async (baseUrl) => {
+        try {
+            await runDemo("chrome-relay", { baseUrl });
+            strict_1.default.fail("expected the demo to exit with an error");
+        }
+        catch (error) {
+            const execError = error;
+            strict_1.default.equal(execError.code, 1);
+            strict_1.default.match(execError.stderr ?? "", /Relay failure branch: use-current-shared-tab/);
+            strict_1.default.match(execError.stderr ?? "", /Relay failure phase: target-selection/);
+            strict_1.default.match(execError.stderr ?? "", /Relay UX state: user-action-required/);
+            strict_1.default.match(execError.stderr ?? "", /Relay failure category: shared-tab-read-only-scope-limitation/);
+            strict_1.default.match(execError.stderr ?? "", /Relay failure retryable: true/);
+            strict_1.default.match(execError.stderr ?? "", /Scope note: Chrome relay is still limited to the currently shared tab and remains read-only\./);
+            strict_1.default.match(execError.stderr ?? "", /Relay user prompt: Chrome relay attach only works for the tab that is currently shared\. Use the shared tab or share a different tab first\./);
+        }
+    });
+});
+(0, node_test_1.default)("http demo smoke: readiness blockers surface documented prompts without attempting attach", async () => {
+    const state = {
+        capabilities: createCapabilitiesPayload(),
+        diagnosticsByBrowser: {
+            chrome: createChromeDiagnostics({
+                direct: {
+                    ready: false,
+                    state: "unavailable",
+                    blockers: [
+                        {
+                            code: "direct_unavailable_attach_endpoint_missing",
+                            message: "missing local DevTools endpoint"
+                        }
+                    ]
+                },
+                relay: { ready: false, state: "unavailable" }
+            }),
+            safari: createSafariDiagnostics()
+        },
+        attachResponseByMode: {
+            direct: createChromeDirectSession(),
+            relay: createChromeRelaySession()
+        },
+        requests: []
+    };
+    await withStubBridge(state, async (baseUrl) => {
+        const result = await runDemo("chrome-direct", { baseUrl });
+        strict_1.default.match(result.stdout, /User prompt: Chrome direct attach needs a local DevTools endpoint that is already available on this machine\./);
+        strict_1.default.match(result.stdout, /Attach skipped because the selected path is not ready\./);
+        strict_1.default.deepEqual(state.requests.map((entry) => `${entry.method} ${entry.url}`), ["GET /v1/capabilities", "GET /v1/diagnostics?browser=chrome"]);
+    });
+});

package/dist/tests/docs-fixtures.test.d.ts

@@ -0,0 +1 @@
+export {};