@jobshimo/browser-link 0.22.0 → 0.23.0

package/dist/cdp/gate.d.ts

@@ -0,0 +1,31 @@
+export type CdpDirectGate = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Exact wording agents receive when cdp-direct is off entirely. Agents get
+ * this string and NOTHING else — there is no bypass, no partial access, no
+ * alternate path to a `cdp:` tab while this check fails. */
+export declare const CDP_DIRECT_DISABLED_ERROR = "cdp-direct is disabled. The user can enable it with: browser-link config set cdp-direct.enabled true";
+/** Exact wording agents receive when cdp-direct is enabled but no live
+ * grant exists (never granted, revoked, or expired). */
+export declare const CDP_DIRECT_NO_GRANT_ERROR = "cdp-direct requires an active grant. Ask the user to run: browser-link cdp allow";
+/**
+ * The ONE gate every cdp-direct code path runs through, in the exact order
+ * the feature's permission model requires: (1) is cdp-direct enabled at
+ * all, (2) is there a live, unexpired grant. Re-evaluated on every call —
+ * never cached — because either condition can flip mid-session (the user
+ * disables the setting, or a time-boxed grant simply expires) and the very
+ * next tool call must see that.
+ *
+ * Called from two places by design: `tools/browser-dispatch.ts`'s routing
+ * layer (so an agent gets the exact error text above before any cdp-direct
+ * code runs at all) AND `cdp/transport.ts` itself (defense in depth, so the
+ * transport module is never safe to call without this check even if a
+ * future caller reaches it directly). `cdp/targets.ts`'s `browser.list_tabs`
+ * discovery also gates on this, but treats a failing gate as "show nothing"
+ * rather than an error — an agent that has never heard of cdp-direct should
+ * not see it mentioned in a routine list_tabs call.
+ */
+export declare function checkCdpDirectGate(now?: number): CdpDirectGate;

package/dist/cdp/gate.js

@@ -0,0 +1,35 @@
+import { loadConfig } from '../config.js';
+import { isGrantLive, loadGrant } from './grant.js';
+/** Exact wording agents receive when cdp-direct is off entirely. Agents get
+ * this string and NOTHING else — there is no bypass, no partial access, no
+ * alternate path to a `cdp:` tab while this check fails. */
+export const CDP_DIRECT_DISABLED_ERROR = 'cdp-direct is disabled. The user can enable it with: browser-link config set cdp-direct.enabled true';
+/** Exact wording agents receive when cdp-direct is enabled but no live
+ * grant exists (never granted, revoked, or expired). */
+export const CDP_DIRECT_NO_GRANT_ERROR = 'cdp-direct requires an active grant. Ask the user to run: browser-link cdp allow';
+/**
+ * The ONE gate every cdp-direct code path runs through, in the exact order
+ * the feature's permission model requires: (1) is cdp-direct enabled at
+ * all, (2) is there a live, unexpired grant. Re-evaluated on every call —
+ * never cached — because either condition can flip mid-session (the user
+ * disables the setting, or a time-boxed grant simply expires) and the very
+ * next tool call must see that.
+ *
+ * Called from two places by design: `tools/browser-dispatch.ts`'s routing
+ * layer (so an agent gets the exact error text above before any cdp-direct
+ * code runs at all) AND `cdp/transport.ts` itself (defense in depth, so the
+ * transport module is never safe to call without this check even if a
+ * future caller reaches it directly). `cdp/targets.ts`'s `browser.list_tabs`
+ * discovery also gates on this, but treats a failing gate as "show nothing"
+ * rather than an error — an agent that has never heard of cdp-direct should
+ * not see it mentioned in a routine list_tabs call.
+ */
+export function checkCdpDirectGate(now = Date.now()) {
+    const cfg = loadConfig();
+    if (cfg.cdpDirectEnabled !== true)
+        return { ok: false, error: CDP_DIRECT_DISABLED_ERROR };
+    if (!isGrantLive(loadGrant(), now))
+        return { ok: false, error: CDP_DIRECT_NO_GRANT_ERROR };
+    return { ok: true };
+}
+//# sourceMappingURL=gate.js.map

package/dist/cdp/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/cdp/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIpD;;4DAE4D;AAC5D,MAAM,CAAC,MAAM,yBAAyB,GACpC,sGAAsG,CAAC;AAEzG;wDACwD;AACxD,MAAM,CAAC,MAAM,yBAAyB,GACpC,kFAAkF,CAAC;AAErF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;IACzD,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,GAAG,CAAC,gBAAgB,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC1F,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC;IAC3F,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/cdp/grant.d.ts

@@ -0,0 +1,45 @@
+/**
+ * On-disk record of a `browser-link cdp allow` grant — the time-boxed human
+ * consent that, together with `cdp-direct.enabled`, is required before any
+ * tool may address a `cdp:` tab (see `gate.ts`). Lives in its own small JSON
+ * file in the data dir, never in the repo, never in `config.json` (a grant
+ * is a momentary permission, not a persistent preference).
+ */
+export interface CdpGrant {
+    grantedAt: number;
+    /** `null` means the grant never expires ("never" / `--minutes 0`) —
+     * documented in the CLI help and README as reducing the security
+     * posture, not a default anyone should reach for casually. */
+    expiresAt: number | null;
+}
+/** Absolute path of the grant file — exported so the CLI can name it in an
+ * honest "could not remove" error (see `commands/cdp.ts`) rather than
+ * leaving the user guessing which file to delete by hand. */
+export declare function grantFilePath(): string;
+/** Read the current grant, or `null` when none exists or the file is
+ * corrupt/unreadable — corruption degrades to "no grant" (the safer
+ * failure mode for a permission file) rather than throwing. */
+export declare function loadGrant(): CdpGrant | null;
+/** Record a fresh grant. `ttlMinutes: 0` means "never expires"
+ * (`expiresAt: null`); any other value is the grant's lifetime in minutes
+ * from `now`. `now` is a parameter so tests do not need to mock the clock. */
+export declare function saveGrant(ttlMinutes: number, now?: number): CdpGrant;
+/** Revoke the current grant, if any. Idempotent — revoking with no grant
+ * present is not an error and is a no-op.
+ *
+ * Deliberately does NOT swallow an unlink failure: this is a SECURITY
+ * operation, and a grant file that survives a "revoke" (a transient
+ * Windows lock, an EPERM, a read-only dir) is still honoured by the gate
+ * on the very next tool call — so reporting success while the door stays
+ * open would be a lie. The error propagates; the CLI (`revokeCdpDirect` in
+ * `commands/cdp.ts`) catches it and tells the user the grant may still be
+ * active and to remove the file by hand. */
+export declare function clearGrant(): void;
+/** Whether `grant` is currently live: present, and either non-expiring or
+ * not yet past its `expiresAt`. */
+export declare function isGrantLive(grant: CdpGrant | null, now?: number): boolean;
+/** Milliseconds remaining on `grant`, or `null` when it never expires or
+ * does not exist (callers distinguish "no grant" from "never expires" by
+ * checking `grant` itself first). Never negative — an expired grant reads
+ * as `0` remaining, not a negative number. */
+export declare function remainingMs(grant: CdpGrant | null, now?: number): number | null;

package/dist/cdp/grant.js

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getDataDir } from '../map/paths.js';
+function grantFile() {
+    return join(getDataDir(), 'cdp-grant.json');
+}
+/** Absolute path of the grant file — exported so the CLI can name it in an
+ * honest "could not remove" error (see `commands/cdp.ts`) rather than
+ * leaving the user guessing which file to delete by hand. */
+export function grantFilePath() {
+    return grantFile();
+}
+function isCdpGrant(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.grantedAt === 'number' && (v.expiresAt === null || typeof v.expiresAt === 'number'));
+}
+/** Read the current grant, or `null` when none exists or the file is
+ * corrupt/unreadable — corruption degrades to "no grant" (the safer
+ * failure mode for a permission file) rather than throwing. */
+export function loadGrant() {
+    const path = grantFile();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isCdpGrant(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Record a fresh grant. `ttlMinutes: 0` means "never expires"
+ * (`expiresAt: null`); any other value is the grant's lifetime in minutes
+ * from `now`. `now` is a parameter so tests do not need to mock the clock. */
+export function saveGrant(ttlMinutes, now = Date.now()) {
+    const path = grantFile();
+    mkdirSync(dirname(path), { recursive: true });
+    const grant = {
+        grantedAt: now,
+        expiresAt: ttlMinutes === 0 ? null : now + ttlMinutes * 60_000,
+    };
+    writeFileSync(path, JSON.stringify(grant, null, 2) + '\n', 'utf8');
+    return grant;
+}
+/** Revoke the current grant, if any. Idempotent — revoking with no grant
+ * present is not an error and is a no-op.
+ *
+ * Deliberately does NOT swallow an unlink failure: this is a SECURITY
+ * operation, and a grant file that survives a "revoke" (a transient
+ * Windows lock, an EPERM, a read-only dir) is still honoured by the gate
+ * on the very next tool call — so reporting success while the door stays
+ * open would be a lie. The error propagates; the CLI (`revokeCdpDirect` in
+ * `commands/cdp.ts`) catches it and tells the user the grant may still be
+ * active and to remove the file by hand. */
+export function clearGrant() {
+    const path = grantFile();
+    if (!existsSync(path))
+        return;
+    unlinkSync(path);
+}
+/** Whether `grant` is currently live: present, and either non-expiring or
+ * not yet past its `expiresAt`. */
+export function isGrantLive(grant, now = Date.now()) {
+    if (!grant)
+        return false;
+    if (grant.expiresAt === null)
+        return true;
+    return grant.expiresAt > now;
+}
+/** Milliseconds remaining on `grant`, or `null` when it never expires or
+ * does not exist (callers distinguish "no grant" from "never expires" by
+ * checking `grant` itself first). Never negative — an expired grant reads
+ * as `0` remaining, not a negative number. */
+export function remainingMs(grant, now = Date.now()) {
+    if (!grant || grant.expiresAt === null)
+        return null;
+    return Math.max(0, grant.expiresAt - now);
+}
+//# sourceMappingURL=grant.js.map

package/dist/cdp/grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant.js","sourceRoot":"","sources":["../../src/cdp/grant.ts"],"names":[],"mappings":"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"}

package/dist/cdp/inpage/builders.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Build the snapshot expression. Filters are applied INSIDE the page so the
+ * server never receives the dropped material at all — that's where the token
+ * win for `within_selector` / `only_interactive` / `exclude` actually lives.
+ * The serializer omits empty-string fields per entry (token win that applies
+ * unconditionally on every snapshot).
+ *
+ * The scan pierces open Shadow DOM roots and same-origin iframes via
+ * `deepQueryAll` (see `deep-query.ts`). `within_selector` itself is resolved
+ * with `deepQueryFirst`, so a subtree inside a shadow root or iframe can be
+ * targeted too. Matched entries that live inside an iframe carry an
+ * optional `frame` field with the innermost hosting iframe's selector, and
+ * entries whose generated selector could not be made unique across the deep
+ * search scope carry `ambiguous: true` (see `genSelectorInfo`).
+ */
+export interface SnapshotOpts {
+    within_selector?: string;
+    only_interactive?: boolean;
+    exclude?: string[];
+    max_interactive?: number;
+}
+export declare function buildSnapshotJs(opts?: SnapshotOpts): string;
+/** Build the find-by-text expression. Returns one of:
+ *   { matched: true, selector, coords:{x,y}, tag, text, frame?, ambiguous? }
+ *   { matched: false, reason: 'not-found', error?, near_misses?: [{text,selector,role?}] }
+ *   { matched: false, reason: 'multiple-matches', candidates: [{selector,text,tag}] }
+ *
+ * Role-aware: when `role` is provided, only elements whose explicit ARIA
+ * role or implicit role match are considered. When omitted, the search
+ * scans a broad set of interactive + clickable elements.
+ *
+ * The scan pierces open Shadow DOM roots and same-origin iframes via
+ * `deepQueryAll`. `coords` are mapped to TOP-LEVEL viewport coordinates
+ * (accounting for ancestor iframe offsets) so they are directly usable by
+ * `browser.drag` and other coordinate-based tools.
+ *
+ * `not-found` carries up to 3 `near_misses` — VISIBLE interactive-ish
+ * elements ranked by (1) case-insensitive substring containment of the
+ * query in the candidate's accessible text/name, then (2) token overlap —
+ * so the agent gets a "did you mean" instead of a bare miss. Omitted
+ * entirely when nothing scores (no junk suggestions). When `role` narrowed
+ * the scan and the text DOES exist outside that role, `error` names the
+ * exclusion explicitly (e.g. `text matched 2 elements but none with role
+ * "button" — closest: <div onclick> "GIF picker"`) and `near_misses` is
+ * populated from that broader, role-agnostic match set instead.
+ *
+ * Near-miss entries use `genSelector` (not `genSelectorInfo`), so the
+ * `ambiguous` flag is intentionally NOT carried — a near-miss selector
+ * that collides with structurally-identical twins in other roots resolves
+ * first-match-wins silently. Documented on the tool as: hints for the
+ * next `find`, never click targets.
+ */
+export interface FindOpts {
+    text: string;
+    role?: string;
+    exact?: boolean;
+}
+export declare function buildFindJs(opts: FindOpts): string;
+/**
+ * Build the click-resolution expression: resolves the selector across the
+ * deep search scope, scrolls the element (and every ancestor iframe) into
+ * view, computes the TOP-LEVEL viewport click point, and — unless `force`
+ * is set — hit-tests that point before returning it, so a covering overlay
+ * is caught before dispatching CDP mouse events. Returns:
+ *   { ok: true, x, y, tag }
+ *   { ok: false, reason: 'invalid-selector', error }
+ *   { ok: false, reason: 'not-found' }
+ *   { ok: false, reason: 'occluded', blocker }
+ *
+ * The `invalid-selector` check runs BEFORE `deepQueryFirst` — a malformed
+ * CSS selector throws the identical `SyntaxError` from every root's own
+ * `querySelector`, which `deepQueryFirst`'s per-root try/catch otherwise
+ * swallows into an indistinguishable "not-found". Checking once against
+ * `document` up front separates "the selector text is broken" from "the
+ * selector is valid but nothing on the page matches it".
+ */
+export interface ClickResolveOpts {
+    selector: string;
+    force: boolean;
+}
+export declare function buildClickResolveJs(opts: ClickResolveOpts): string;
+/**
+ * Build the type-resolution expression: resolves the selector across the
+ * deep search scope, focuses it, optionally clears its value, and reports
+ * success so the caller can follow up with CDP `Input.insertText` (which
+ * types into whatever currently has focus at the browser level — works the
+ * same whether that focus target lives in the top document, a shadow root,
+ * or a same-origin iframe). Returns:
+ *   { ok: true }
+ *   { ok: false, reason: 'invalid-selector', error }
+ *   { ok: false, reason: 'not-found' }
+ *
+ * Same invalid-selector pre-check as `buildClickResolveJs` — see its doc
+ * comment for why the check has to run before `deepQueryFirst`.
+ */
+export interface TypeResolveOpts {
+    selector: string;
+    clear: boolean;
+}
+export declare function buildTypeResolveJs(opts: TypeResolveOpts): string;
+/**
+ * Build the focus-resolution expression for `browser.press`'s optional
+ * `selector`: resolves the selector across the deep search scope and
+ * focuses it, reporting success so the caller can follow up with the CDP
+ * key event sequence (which — like `Input.insertText` — targets whatever
+ * currently has focus at the browser level). Intentionally separate from
+ * `buildTypeResolveJs`: press never clears a value, and naming it
+ * distinctly keeps the press code path readable on its own.
+ */
+export interface FocusResolveOpts {
+    selector: string;
+}
+export declare function buildFocusJs(opts: FocusResolveOpts): string;
+/**
+ * Build the settle-await expression shared by `browser.click`, `.type` and
+ * `.press`. Called AFTER the action's CDP input events have been
+ * dispatched: installs one `MutationObserver` on `document` (subtree,
+ * childList, attributes, characterData) and resolves once no mutation has
+ * landed for `settle_ms` consecutive milliseconds, or once `settle_timeout_ms`
+ * total has elapsed — whichever comes first. Returned as a Promise so the
+ * caller's `evaluateInTab` (CDP `Runtime.evaluate` with `awaitPromise: true`)
+ * waits for it naturally.
+ *
+ * Baseline `url`/`activeElement` are captured at the TOP of this
+ * expression — i.e. right after the action's own focus/navigation side
+ * effects have already landed (dispatch already happened by the time this
+ * runs), so `focus_moved`/`url_changed` report drift that happened DURING
+ * the settle window, not the action's own expected effect.
+ *
+ * The result omits `url_changed` / `focus_moved` when they did not change
+ * — token-lean by construction, no post-filtering needed.
+ */
+export interface SettleOpts {
+    /** Quiet-period length in ms. Caller is expected to have already
+     * clamped this to (0, 2000] — 0 means "don't call this builder at all". */
+    settle_ms: number;
+    /** Overall cap in ms. Caller is expected to have already clamped this
+     * to [0, 10000]. */
+    settle_timeout_ms: number;
+}
+export declare function buildSettleJs(opts: SettleOpts): string;
+/**
+ * Build the `browser.state` expression: a compact orientation snapshot —
+ * current url/title, the deep-resolved focused element, visible dialog-role
+ * elements, scroll position, and viewport size. Cheaper than a full
+ * `browser.snapshot` when the agent only needs "where am I right now".
+ *
+ * `focused` descends through `document.activeElement` past shadow-root and
+ * same-origin-iframe boundaries to the real innermost focused element (a
+ * shadow host or an <iframe> being "active" at one level is not the actual
+ * focus target the agent cares about). Its `selector` goes through the same
+ * `genSelectorInfo` uniqueness check `snapshot`/`find` use, so it carries
+ * `ambiguous: true` under the same structurally-identical-twins condition.
+ *
+ * `dialogs` matches visible `[role=dialog]`, `[role=alertdialog]` and open
+ * `<dialog>` elements found via the same deep walk, with a best-effort
+ * `label` resolved from aria-label / aria-labelledby / the first heading
+ * inside the dialog.
+ *
+ * Every optional field is omitted when there is nothing to report: no
+ * `focused` beyond `<body>`, no `dialogs` when none are open, and no
+ * `scroll` when the page is at its default (0,0) position — token-lean by
+ * construction, matching the omit-falsy convention the other builders use.
+ */
+export declare function buildStateJs(): string;