local-browser-bridge 0.1.0

package/dist/src/service/attach-service.d.ts

@@ -0,0 +1,28 @@
+import type { ActivationArtifact, AttachRequest, AttachmentSession, BrowserAdapter, BridgeCapabilitiesContract, BrowserDiagnostics, BrowserTabTarget, NavigationArtifact, ResumedSession, ScreenshotArtifact, NavigateOptions, ScreenshotOptions, SessionActivation, SessionNavigation, SessionScreenshot, SupportedBrowser, TabMetadata } from "../types";
+import { SessionStore } from "../store/session-store";
+interface AttachServiceOptions {
+    store?: SessionStore;
+    adapterFactory?: (browser: SupportedBrowser) => BrowserAdapter;
+}
+export declare class AttachService {
+    private readonly store;
+    private readonly adapterFactory;
+    constructor(options?: AttachServiceOptions);
+    inspectFrontTab(browser: SupportedBrowser): Promise<TabMetadata>;
+    inspectTab(browser: SupportedBrowser, target?: BrowserTabTarget): Promise<TabMetadata>;
+    listTabs(browser: SupportedBrowser): Promise<TabMetadata[]>;
+    activate(browser: SupportedBrowser, target?: BrowserTabTarget): Promise<ActivationArtifact>;
+    activateSession(id: string): Promise<SessionActivation>;
+    navigate(browser: SupportedBrowser, target: BrowserTabTarget, options: NavigateOptions): Promise<NavigationArtifact>;
+    navigateSession(id: string, options: NavigateOptions): Promise<SessionNavigation>;
+    screenshot(browser: SupportedBrowser, target?: BrowserTabTarget, options?: ScreenshotOptions): Promise<ScreenshotArtifact>;
+    attach(browser: SupportedBrowser, targetOrRequest?: BrowserTabTarget | AttachRequest): Promise<AttachmentSession>;
+    listSessions(): Promise<AttachmentSession[]>;
+    diagnostics(browser: SupportedBrowser): Promise<BrowserDiagnostics>;
+    getCapabilities(browser?: SupportedBrowser): BridgeCapabilitiesContract;
+    getSession(id: string): Promise<AttachmentSession>;
+    screenshotSession(id: string, options?: ScreenshotOptions): Promise<SessionScreenshot>;
+    resumeSession(id: string): Promise<ResumedSession>;
+    private buildScreenshotPath;
+}
+export {};

package/dist/src/service/attach-service.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachService = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const browser_1 = require("../browser");
+const capabilities_1 = require("../capabilities");
+const chrome_1 = require("../browser/chrome");
+const errors_1 = require("../errors");
+const session_metadata_1 = require("../session-metadata");
+const session_store_1 = require("../store/session-store");
+const target_1 = require("../target");
+class AttachService {
+    store;
+    adapterFactory;
+    constructor(options = {}) {
+        this.store = options.store ?? new session_store_1.SessionStore();
+        this.adapterFactory = options.adapterFactory ?? browser_1.getBrowserAdapter;
+    }
+    async inspectFrontTab(browser) {
+        return this.inspectTab(browser, { type: "front" });
+    }
+    async inspectTab(browser, target = { type: "front" }) {
+        return this.adapterFactory(browser).resolveTab(target);
+    }
+    async listTabs(browser) {
+        return this.adapterFactory(browser).listTabs();
+    }
+    async activate(browser, target = { type: "front" }) {
+        return this.adapterFactory(browser).performSessionAction({
+            action: "activate",
+            target
+        });
+    }
+    async activateSession(id) {
+        const session = await this.getSession(id);
+        const activation = await this.activate(session.browser, session.target);
+        return {
+            session,
+            activation
+        };
+    }
+    async navigate(browser, target, options) {
+        return this.adapterFactory(browser).performSessionAction({
+            action: "navigate",
+            target,
+            options
+        });
+    }
+    async navigateSession(id, options) {
+        const resumed = await this.resumeSession(id);
+        const navigation = await this.navigate(resumed.session.browser, {
+            type: "indexed",
+            windowIndex: navigationTargetWindowIndex(resumed.tab),
+            tabIndex: navigationTargetTabIndex(resumed.tab)
+        }, options);
+        const updatedSession = {
+            ...resumed.session,
+            target: (0, target_1.buildSignatureTargetFromTab)(navigation.tab),
+            tab: navigation.tab,
+            frontTab: navigation.tab
+        };
+        await this.store.update(updatedSession);
+        return {
+            session: (0, session_metadata_1.normalizeAttachmentSession)(updatedSession),
+            navigation
+        };
+    }
+    async screenshot(browser, target = { type: "front" }, options = {}) {
+        const outputPath = options.outputPath ?? this.buildScreenshotPath(browser);
+        return this.adapterFactory(browser).performSessionAction({
+            action: "screenshot",
+            target,
+            options: { outputPath }
+        });
+    }
+    async attach(browser, targetOrRequest = { type: "front" }) {
+        const request = isAttachRequest(targetOrRequest)
+            ? targetOrRequest
+            : { target: targetOrRequest };
+        const target = request.target ?? { type: "front" };
+        if (browser === "chrome" && request.attach?.mode === "relay") {
+            const relay = await (0, chrome_1.resolveChromeRelayAttach)(target);
+            const createdAt = new Date().toISOString();
+            const session = (0, session_metadata_1.normalizeAttachmentSession)({
+                id: (0, node_crypto_1.randomUUID)(),
+                browser,
+                target: (0, target_1.buildSignatureTargetFromTab)(relay.tab),
+                tab: relay.tab,
+                frontTab: relay.tab,
+                createdAt,
+                attach: {
+                    mode: "relay",
+                    source: "extension-relay",
+                    scope: "tab",
+                    resumable: relay.resumable,
+                    expiresAt: relay.expiresAt,
+                    resumeRequiresUserGesture: relay.resumeRequiresUserGesture,
+                    trustedAt: relay.trustedAt
+                }
+            });
+            return this.store.create(session);
+        }
+        const tab = await this.inspectTab(browser, target);
+        const createdAt = new Date().toISOString();
+        const session = (0, session_metadata_1.normalizeAttachmentSession)({
+            id: (0, node_crypto_1.randomUUID)(),
+            browser,
+            target: (0, target_1.buildSignatureTargetFromTab)(tab),
+            tab,
+            frontTab: tab,
+            createdAt
+        });
+        return this.store.create(session);
+    }
+    async listSessions() {
+        return this.store.list();
+    }
+    async diagnostics(browser) {
+        return this.adapterFactory(browser).getDiagnostics();
+    }
+    getCapabilities(browser) {
+        return (0, capabilities_1.getBridgeCapabilities)(browser);
+    }
+    async getSession(id) {
+        const session = await this.store.get(id);
+        if (!session) {
+            throw new errors_1.AppError(`Session not found: ${id}`, 404, "session_not_found");
+        }
+        return session;
+    }
+    async screenshotSession(id, options = {}) {
+        const session = await this.getSession(id);
+        const screenshot = await this.screenshot(session.browser, session.target, { outputPath: options.outputPath ?? this.buildScreenshotPath(session.browser, session.id) });
+        return {
+            session,
+            screenshot
+        };
+    }
+    async resumeSession(id) {
+        const session = await this.getSession(id);
+        if (session.browser === "chrome" && session.attach.mode === "relay") {
+            const resumed = await (0, chrome_1.resumeChromeRelaySession)(session);
+            const refreshedSession = await this.store.update(resumed.session);
+            return {
+                ...resumed,
+                session: refreshedSession
+            };
+        }
+        const tabs = await this.listTabs(session.browser);
+        const { target } = session;
+        if (target.type === "front") {
+            const tab = await this.inspectTab(session.browser, target);
+            return {
+                session,
+                tab,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "front",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        if (target.type === "indexed") {
+            const tab = await this.inspectTab(session.browser, target);
+            return {
+                session,
+                tab,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "indexed",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        const byNativeIdentity = target.native?.kind === "chrome-devtools-target"
+            ? tabs.find((tab) => tab.identity.native?.kind === "chrome-devtools-target" &&
+                tab.identity.native.targetId === target.native?.targetId)
+            : undefined;
+        if (byNativeIdentity) {
+            return {
+                session,
+                tab: byNativeIdentity,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "native_identity",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        const bySignature = tabs.find((tab) => tab.identity.signature === target.signature);
+        if (bySignature) {
+            return {
+                session,
+                tab: bySignature,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "signature",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        const byUrlTitle = tabs.find((tab) => tab.url === target.url && tab.identity.titleKey === (session.tab.identity?.titleKey ?? ""));
+        if (byUrlTitle) {
+            return {
+                session,
+                tab: byUrlTitle,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "url_title",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        const byUrl = target.url ? tabs.find((tab) => tab.url === target.url) : undefined;
+        if (byUrl) {
+            return {
+                session,
+                tab: byUrl,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "url",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        const byLastKnown = target.lastKnownWindowIndex && target.lastKnownTabIndex
+            ? tabs.find((tab) => tab.windowIndex === target.lastKnownWindowIndex && tab.tabIndex === target.lastKnownTabIndex)
+            : undefined;
+        if (byLastKnown) {
+            return {
+                session,
+                tab: byLastKnown,
+                resumedAt: new Date().toISOString(),
+                resolution: {
+                    strategy: "last_known_index",
+                    matched: true,
+                    attachMode: session.attach.mode,
+                    semantics: session.semantics.resume
+                }
+            };
+        }
+        throw new errors_1.AppError(`Unable to resume session ${id}; the saved ${session.browser} tab can no longer be matched.`, 404, "tab_not_found");
+    }
+    buildScreenshotPath(browser, sessionId) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const fileName = sessionId ? `${browser}-${sessionId}-${stamp}.png` : `${browser}-${stamp}.png`;
+        return (0, node_path_1.resolve)(process.cwd(), ".data", "screenshots", fileName);
+    }
+}
+exports.AttachService = AttachService;
+function navigationTargetWindowIndex(tab) {
+    return tab.windowIndex;
+}
+function navigationTargetTabIndex(tab) {
+    return tab.tabIndex;
+}
+function isAttachRequest(value) {
+    return typeof value === "object" && value !== null && ("attach" in value || "target" in value);
+}

package/dist/src/session-metadata.d.ts

@@ -0,0 +1,4 @@
+import type { AttachmentSession } from "./types";
+type AttachmentSessionRecord = Omit<AttachmentSession, "schemaVersion" | "kind" | "capabilities" | "status" | "attach" | "semantics"> & Partial<Pick<AttachmentSession, "schemaVersion" | "kind" | "capabilities" | "status" | "attach" | "semantics">>;
+export declare function normalizeAttachmentSession(session: AttachmentSessionRecord): AttachmentSession;
+export {};

package/dist/src/session-metadata.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAttachmentSession = normalizeAttachmentSession;
+const capabilities_1 = require("./capabilities");
+function buildSessionKind(browser) {
+    return (0, capabilities_1.getBrowserCapabilityDescriptor)(browser).kind;
+}
+function buildSessionCapabilities(browser) {
+    const descriptor = (0, capabilities_1.getBrowserCapabilityDescriptor)(browser);
+    return {
+        resume: true,
+        activate: descriptor.operations.activate,
+        navigate: descriptor.operations.navigate,
+        screenshot: descriptor.operations.screenshot
+    };
+}
+function buildSessionStatus(capabilities) {
+    const canAct = capabilities.activate || capabilities.navigate || capabilities.screenshot;
+    return {
+        state: canAct ? "actionable" : "read-only",
+        canAct
+    };
+}
+function buildSessionSemantics(browser, attach) {
+    if (browser === "chrome" && attach.mode === "relay") {
+        return {
+            inspect: "shared-tab-only",
+            list: "saved-session",
+            resume: "current-shared-tab",
+            tabReference: {
+                windowIndex: "synthetic-shared-tab-position",
+                tabIndex: "synthetic-shared-tab-position"
+            },
+            notes: [
+                "Relay sessions describe the last tab explicitly shared through the extension, not general Chrome tab visibility.",
+                "Resume only checks the currently shared relay tab and may require the user to share the tab again."
+            ]
+        };
+    }
+    return {
+        inspect: "browser-tabs",
+        list: "saved-session",
+        resume: "saved-browser-target",
+        tabReference: {
+            windowIndex: "browser-position",
+            tabIndex: "browser-position"
+        }
+    };
+}
+function defaultAttachMode(browser) {
+    return browser === "chrome" ? "direct" : "direct";
+}
+function buildSessionAttach(browser, existing) {
+    const mode = existing?.mode ?? defaultAttachMode(browser);
+    if (browser === "chrome") {
+        return {
+            mode,
+            source: existing?.source ?? (mode === "relay" ? "extension-relay" : "user-browser"),
+            scope: existing?.scope ?? (mode === "relay" ? "tab" : "browser"),
+            resumable: existing?.resumable,
+            expiresAt: existing?.expiresAt,
+            resumeRequiresUserGesture: existing?.resumeRequiresUserGesture,
+            trustedAt: existing?.trustedAt
+        };
+    }
+    return {
+        mode: "direct",
+        source: existing?.source ?? "user-browser",
+        scope: existing?.scope ?? "browser",
+        resumable: existing?.resumable,
+        expiresAt: existing?.expiresAt,
+        resumeRequiresUserGesture: existing?.resumeRequiresUserGesture,
+        trustedAt: existing?.trustedAt
+    };
+}
+function normalizeAttachmentSession(session) {
+    const attach = buildSessionAttach(session.browser, session.attach);
+    const capabilities = buildSessionCapabilities(session.browser);
+    return {
+        ...session,
+        schemaVersion: 1,
+        kind: buildSessionKind(session.browser),
+        attach,
+        semantics: buildSessionSemantics(session.browser, attach),
+        capabilities,
+        status: buildSessionStatus(capabilities)
+    };
+}

package/dist/src/store/session-store.d.ts

@@ -0,0 +1,14 @@
+import type { AttachmentSession } from "../types";
+interface SessionStoreOptions {
+    filePath?: string;
+}
+export declare class SessionStore {
+    private readonly filePath;
+    constructor(options?: SessionStoreOptions);
+    list(): Promise<AttachmentSession[]>;
+    get(id: string): Promise<AttachmentSession | undefined>;
+    create(session: AttachmentSession): Promise<AttachmentSession>;
+    update(session: AttachmentSession): Promise<AttachmentSession>;
+    private ensureFile;
+}
+export {};

package/dist/src/store/session-store.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const session_metadata_1 = require("../session-metadata");
+class SessionStore {
+    filePath;
+    constructor(options = {}) {
+        this.filePath = options.filePath ?? (0, node_path_1.resolve)(process.cwd(), ".data", "sessions.json");
+    }
+    async list() {
+        await this.ensureFile();
+        const raw = await (0, promises_1.readFile)(this.filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed.map(session_metadata_1.normalizeAttachmentSession).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    async get(id) {
+        const sessions = await this.list();
+        return sessions.find((session) => session.id === id);
+    }
+    async create(session) {
+        const sessions = await this.list();
+        const normalizedSession = (0, session_metadata_1.normalizeAttachmentSession)(session);
+        sessions.unshift(normalizedSession);
+        await (0, promises_1.writeFile)(this.filePath, JSON.stringify(sessions, null, 2) + "\n", "utf8");
+        return normalizedSession;
+    }
+    async update(session) {
+        const sessions = await this.list();
+        const normalizedSession = (0, session_metadata_1.normalizeAttachmentSession)(session);
+        const index = sessions.findIndex((candidate) => candidate.id === normalizedSession.id);
+        if (index === -1) {
+            sessions.unshift(normalizedSession);
+        }
+        else {
+            sessions[index] = normalizedSession;
+        }
+        await (0, promises_1.writeFile)(this.filePath, JSON.stringify(sessions, null, 2) + "\n", "utf8");
+        return normalizedSession;
+    }
+    async ensureFile() {
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.filePath), { recursive: true });
+        try {
+            await (0, promises_1.readFile)(this.filePath, "utf8");
+        }
+        catch {
+            await (0, promises_1.writeFile)(this.filePath, "[]\n", "utf8");
+        }
+    }
+}
+exports.SessionStore = SessionStore;

package/dist/src/target.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserTabTarget, TabMetadata } from "./types";
+export declare function buildTabTarget(input?: {
+    windowIndex?: string | number;
+    tabIndex?: string | number;
+    signature?: string;
+    url?: string;
+    title?: string;
+}): BrowserTabTarget;
+export declare function buildSignatureTargetFromTab(tab: TabMetadata): BrowserTabTarget;

package/dist/src/target.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTabTarget = buildTabTarget;
+exports.buildSignatureTargetFromTab = buildSignatureTargetFromTab;
+const errors_1 = require("./errors");
+function parseIndex(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new errors_1.AppError(`${fieldName} must be a positive integer.`, 400, "invalid_target");
+    }
+    return parsed;
+}
+function parseNonEmpty(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function buildTabTarget(input = {}) {
+    const windowIndex = parseIndex(input.windowIndex, "windowIndex");
+    const tabIndex = parseIndex(input.tabIndex, "tabIndex");
+    const signature = parseNonEmpty(input.signature);
+    const url = parseNonEmpty(input.url);
+    const title = parseNonEmpty(input.title);
+    if (signature) {
+        return {
+            type: "signature",
+            signature,
+            url,
+            title,
+            lastKnownWindowIndex: windowIndex,
+            lastKnownTabIndex: tabIndex
+        };
+    }
+    if (windowIndex === undefined && tabIndex === undefined) {
+        return { type: "front" };
+    }
+    if (windowIndex === undefined || tabIndex === undefined) {
+        throw new errors_1.AppError("windowIndex and tabIndex must be provided together for an explicit tab target.", 400, "invalid_target");
+    }
+    return {
+        type: "indexed",
+        windowIndex,
+        tabIndex
+    };
+}
+function buildSignatureTargetFromTab(tab) {
+    return {
+        type: "signature",
+        signature: tab.identity.signature,
+        url: tab.url,
+        title: tab.title,
+        lastKnownWindowIndex: tab.windowIndex,
+        lastKnownTabIndex: tab.tabIndex,
+        native: tab.identity.native
+    };
+}