@jackwener/opencli 1.7.5 → 1.7.6

package/dist/src/browser/shape.js

@@ -0,0 +1,95 @@
+/**
+ * JSON shape inference for browser network response previews.
+ *
+ * Produces a flat path → type descriptor map so agents can understand
+ * response structure without paying the token cost of the full body.
+ *
+ * Descriptors:
+ *   string | number | boolean | null              primitives
+ *   string(len=N)                                 strings longer than sampleStringLen
+ *   array(0) | array(N)                           array at depth cap or summarized
+ *   object | object(empty)                        objects at depth cap or summarized
+ *   (truncated)                                   output size budget exceeded
+ */
+const ROOT = '$';
+export function inferShape(value, opts = {}) {
+    const maxDepth = opts.maxDepth ?? 6;
+    const maxBytes = opts.maxBytes ?? 2048;
+    const sampleStringLen = opts.sampleStringLen ?? 80;
+    const out = {};
+    let bytes = 2; // account for `{}` braces when serialized
+    let truncated = false;
+    const add = (path, desc) => {
+        if (truncated)
+            return false;
+        const entryBytes = JSON.stringify(path).length + JSON.stringify(desc).length + 2; // ":" + ","
+        if (bytes + entryBytes > maxBytes) {
+            out['(truncated)'] = `reached ${maxBytes}B budget`;
+            truncated = true;
+            return false;
+        }
+        out[path] = desc;
+        bytes += entryBytes;
+        return true;
+    };
+    const walk = (node, path, depth) => {
+        if (truncated)
+            return;
+        if (node === null) {
+            add(path, 'null');
+            return;
+        }
+        const t = typeof node;
+        if (t === 'string') {
+            const s = node;
+            add(path, s.length > sampleStringLen ? `string(len=${s.length})` : 'string');
+            return;
+        }
+        if (t === 'number' || t === 'boolean') {
+            add(path, t);
+            return;
+        }
+        if (t === 'undefined' || t === 'function' || t === 'symbol' || t === 'bigint') {
+            add(path, t);
+            return;
+        }
+        if (Array.isArray(node)) {
+            if (node.length === 0) {
+                add(path, 'array(0)');
+                return;
+            }
+            if (depth >= maxDepth) {
+                add(path, `array(${node.length})`);
+                return;
+            }
+            if (!add(path, `array(${node.length})`))
+                return;
+            walk(node[0], `${path}[0]`, depth + 1);
+            return;
+        }
+        // plain object
+        const obj = node;
+        const keys = Object.keys(obj);
+        if (keys.length === 0) {
+            add(path, 'object(empty)');
+            return;
+        }
+        if (depth >= maxDepth) {
+            add(path, `object(keys=${keys.length})`);
+            return;
+        }
+        if (!add(path, 'object'))
+            return;
+        for (const k of keys) {
+            if (truncated)
+                return;
+            const childPath = isSafeIdent(k) ? `${path}.${k}` : `${path}[${JSON.stringify(k)}]`;
+            walk(obj[k], childPath, depth + 1);
+        }
+    };
+    walk(value, ROOT, 0);
+    return out;
+}
+function isSafeIdent(key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key);
+}

package/dist/src/browser/shape.test.d.ts

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

package/dist/src/browser/shape.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { inferShape } from './shape.js';
+describe('inferShape', () => {
+    it('describes primitives at root', () => {
+        expect(inferShape('hello')).toEqual({ $: 'string' });
+        expect(inferShape(42)).toEqual({ $: 'number' });
+        expect(inferShape(true)).toEqual({ $: 'boolean' });
+        expect(inferShape(null)).toEqual({ $: 'null' });
+    });
+    it('summarizes long strings with their length', () => {
+        const long = 'x'.repeat(200);
+        expect(inferShape(long, { sampleStringLen: 80 })).toEqual({ $: 'string(len=200)' });
+    });
+    it('walks nested objects and emits dotted paths', () => {
+        const shape = inferShape({ user: { id: 1, name: 'bob' } });
+        expect(shape).toEqual({
+            $: 'object',
+            '$.user': 'object',
+            '$.user.id': 'number',
+            '$.user.name': 'string',
+        });
+    });
+    it('quotes unsafe keys using bracket notation', () => {
+        const shape = inferShape({ 'weird key': 1, '123bad': 2 });
+        expect(shape['$["weird key"]']).toBe('number');
+        expect(shape['$["123bad"]']).toBe('number');
+    });
+    it('samples the first array element and reports length', () => {
+        const shape = inferShape({ items: [{ a: 1 }, { a: 2 }, { a: 3 }] });
+        expect(shape['$.items']).toBe('array(3)');
+        expect(shape['$.items[0]']).toBe('object');
+        expect(shape['$.items[0].a']).toBe('number');
+    });
+    it('marks empty containers explicitly', () => {
+        const shape = inferShape({ arr: [], obj: {} });
+        expect(shape['$.arr']).toBe('array(0)');
+        expect(shape['$.obj']).toBe('object(empty)');
+    });
+    it('collapses subtrees past maxDepth', () => {
+        const deep = { a: { b: { c: { d: { e: { f: 'too deep' } } } } } };
+        const shape = inferShape(deep, { maxDepth: 2 });
+        expect(shape['$.a.b']).toMatch(/^object/);
+        expect(shape['$.a.b.c']).toBeUndefined();
+    });
+    it('truncates when the byte budget is exhausted', () => {
+        const wide = {};
+        for (let i = 0; i < 500; i++)
+            wide[`field_${i}`] = i;
+        const shape = inferShape(wide, { maxBytes: 256 });
+        expect(shape['(truncated)']).toMatch(/256B/);
+        expect(Object.keys(shape).length).toBeLessThan(500);
+    });
+    it('stops descending into an array once the budget is hit by its own descriptor', () => {
+        // Budget just large enough for `$` + one deep array descriptor, not its element.
+        const shape = inferShape({ items: [{ deep: 1 }] }, { maxBytes: 40 });
+        expect(shape['$.items[0]']).toBeUndefined();
+        expect(shape['(truncated)']).toBeDefined();
+    });
+    it('handles the Twitter UserTweets payload envelope', () => {
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        rest_id: '42',
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [
+                                    { type: 'TimelinePinEntry', entries: [] },
+                                    { entries: [{ entryId: 'tweet-1', content: { entryType: 'TimelineTimelineItem' } }] },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const shape = inferShape(payload, { maxDepth: 10 });
+        expect(shape['$.data.user.result.rest_id']).toBe('string');
+        expect(shape['$.data.user.result.timeline_v2.timeline.instructions']).toBe('array(2)');
+        expect(shape['$.data.user.result.timeline_v2.timeline.instructions[0]']).toBe('object');
+    });
+});

package/dist/src/browser/target-errors.d.ts

@@ -5,18 +5,31 @@
  * goes through the unified resolver. When resolution fails, one of these
  * structured errors is thrown so that AI agents and adapter authors get
  * actionable diagnostics instead of a generic "Element not found".
+ *
+ * Numeric-ref codes (from snapshot indices):
+ *   - not_found: the ref no longer exists in the DOM
+ *   - stale_ref: the ref still exists but points to a different element
+ *
+ * CSS-selector codes (from `--selector <css>` entrypoints):
+ *   - invalid_selector:       selector syntax rejected by querySelectorAll
+ *   - selector_not_found:     0 matches
+ *   - selector_ambiguous:     >1 matches for a write op without --nth
+ *   - selector_nth_out_of_range: --nth beyond matches_n
  */
-export type TargetErrorCode = 'not_found' | 'ambiguous' | 'stale_ref';
+export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range';
 export interface TargetErrorInfo {
     code: TargetErrorCode;
     message: string;
     hint: string;
     candidates?: string[];
+    /** CSS-path match count, when the error was raised mid-resolution */
+    matches_n?: number;
 }
 export declare class TargetError extends Error {
     readonly code: TargetErrorCode;
     readonly hint: string;
     readonly candidates?: string[];
+    readonly matches_n?: number;
     constructor(info: TargetErrorInfo);
     /** Serialize for structured output to AI agents */
     toJSON(): TargetErrorInfo;

package/dist/src/browser/target-errors.js

@@ -5,17 +5,29 @@
  * goes through the unified resolver. When resolution fails, one of these
  * structured errors is thrown so that AI agents and adapter authors get
  * actionable diagnostics instead of a generic "Element not found".
+ *
+ * Numeric-ref codes (from snapshot indices):
+ *   - not_found: the ref no longer exists in the DOM
+ *   - stale_ref: the ref still exists but points to a different element
+ *
+ * CSS-selector codes (from `--selector <css>` entrypoints):
+ *   - invalid_selector:       selector syntax rejected by querySelectorAll
+ *   - selector_not_found:     0 matches
+ *   - selector_ambiguous:     >1 matches for a write op without --nth
+ *   - selector_nth_out_of_range: --nth beyond matches_n
  */
 export class TargetError extends Error {
     code;
     hint;
     candidates;
+    matches_n;
     constructor(info) {
         super(info.message);
         this.name = 'TargetError';
         this.code = info.code;
         this.hint = info.hint;
         this.candidates = info.candidates;
+        this.matches_n = info.matches_n;
     }
     /** Serialize for structured output to AI agents */
     toJSON() {
@@ -24,6 +36,7 @@ export class TargetError extends Error {
             message: this.message,
             hint: this.hint,
             ...(this.candidates && { candidates: this.candidates }),
+            ...(this.matches_n !== undefined && { matches_n: this.matches_n }),
         };
     }
 }

package/dist/src/browser/target-errors.test.js

@@ -14,16 +14,47 @@ describe('TargetError', () => {
         expect(err.hint).toContain('fresh snapshot');
         expect(err.candidates).toBeUndefined();
     });
-    it('creates ambiguous error with candidates', () => {
+    it('creates selector_ambiguous error with candidates + matches_n', () => {
         const err = new TargetError({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'CSS selector ".btn" matched 3 elements',
-            hint: 'Use a more specific selector.',
+            hint: 'Use a more specific selector, or pass --nth.',
             candidates: ['<button> "Login"', '<button> "Sign Up"', '<button> "Cancel"'],
+            matches_n: 3,
         });
-        expect(err.code).toBe('ambiguous');
+        expect(err.code).toBe('selector_ambiguous');
         expect(err.candidates).toHaveLength(3);
         expect(err.candidates[0]).toContain('Login');
+        expect(err.matches_n).toBe(3);
+    });
+    it('creates invalid_selector error', () => {
+        const err = new TargetError({
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: >>> (unexpected token)',
+            hint: 'Check the selector syntax.',
+        });
+        expect(err.code).toBe('invalid_selector');
+        expect(err.message).toContain('Invalid CSS selector');
+    });
+    it('creates selector_not_found error with matches_n=0', () => {
+        const err = new TargetError({
+            code: 'selector_not_found',
+            message: 'CSS selector ".missing" matched 0 elements',
+            hint: 'Check the page or use browser find.',
+            matches_n: 0,
+        });
+        expect(err.code).toBe('selector_not_found');
+        expect(err.matches_n).toBe(0);
+    });
+    it('creates selector_nth_out_of_range error', () => {
+        const err = new TargetError({
+            code: 'selector_nth_out_of_range',
+            message: 'matched 3 elements, but --nth=5 is out of range',
+            hint: 'Use --nth between 0 and 2.',
+            matches_n: 3,
+        });
+        expect(err.code).toBe('selector_nth_out_of_range');
+        expect(err.matches_n).toBe(3);
     });
     it('creates stale_ref error', () => {
         const err = new TargetError({
@@ -36,17 +67,19 @@ describe('TargetError', () => {
     });
     it('serializes to JSON for structured output', () => {
         const err = new TargetError({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'matched 3',
             hint: 'be specific',
             candidates: ['a', 'b'],
+            matches_n: 3,
         });
         const json = err.toJSON();
         expect(json).toEqual({
-            code: 'ambiguous',
+            code: 'selector_ambiguous',
             message: 'matched 3',
             hint: 'be specific',
             candidates: ['a', 'b'],
+            matches_n: 3,
         });
     });
     it('omits candidates from JSON when not present', () => {

package/dist/src/browser/target-resolver.d.ts

@@ -1,26 +1,73 @@
 /**
  * Unified target resolver for browser actions.
  *
- * Replaces the ad-hoc 4-strategy fallback in dom-helpers.ts with a
- * principled resolution pipeline:
+ * Resolution pipeline:
  *
- * 1. Input classification: numeric → ref path, CSS-like → CSS path
- * 2. Ref path: lookup by data-opencli-ref, then verify fingerprint
- * 3. CSS path: querySelectorAll + uniqueness check
- * 4. Structured errors: stale_ref / ambiguous / not_found
+ * 1. Input classification: all-digit → numeric ref path, otherwise → CSS path.
+ *    The CSS path passes the raw string to `querySelectorAll` and lets the
+ *    browser parser decide what's valid. No frontend regex whitelist — the
+ *    goal is that any selector accepted by `browser find --css` is accepted
+ *    by the same selector on `get/click/type/select`.
+ * 2. Ref path: cascading match levels (see below), using data-opencli-ref
+ *    plus the fingerprint map populated by snapshot + find.
+ * 3. CSS path: querySelectorAll + match-count policy (see ResolveOptions)
+ * 4. Structured errors:
+ *    - numeric: not_found / stale_ref
+ *    - CSS:     invalid_selector / selector_not_found / selector_ambiguous
+ *               / selector_nth_out_of_range
  *
  * All JS is generated as strings for page.evaluate() — runs in the browser.
+ *
+ * ── Cascading stale-ref (browser-use style) ──────────────────────────
+ * Strict equality on the fingerprint rejected too many live pages — SPA
+ * re-renders swap text / role while keeping id + testId. The resolver
+ * now walks three tiers before giving up:
+ *
+ *   1. EXACT        — tag + strong id (id or testId) agree, ≤1 soft mismatch
+ *   2. STABLE       — tag + strong id agree, soft signals drifted (aria-label,
+ *                     role, text) — agent gets a warning but the action
+ *                     proceeds so dynamic pages don't stall
+ *   3. REIDENTIFIED — original ref either missing from the DOM or fully
+ *                     mismatched, but the fingerprint uniquely identifies
+ *                     a single other live element via id / testId /
+ *                     aria-label. Re-tag that element with the old ref and
+ *                     surface match_level so the caller knows we swapped.
+ *
+ * Only when all three fail do we emit `stale_ref`. Every success envelope
+ * carries `match_level` so downstream CLIs can surface the weakest tier
+ * a caller actually traversed.
  */
+export interface ResolveOptions {
+    /**
+     * When CSS matches multiple elements, pick the element at this 0-based
+     * index instead of raising `selector_ambiguous`. Raises
+     * `selector_nth_out_of_range` if `nth >= matches.length`.
+     */
+    nth?: number;
+    /**
+     * When CSS matches multiple elements, pick the first match instead of
+     * raising `selector_ambiguous`. Used by read commands (get text / value /
+     * attributes) to deliver a best-effort answer + matches_n in the envelope.
+     * Ignored when `nth` is also set (nth wins).
+     */
+    firstOnMulti?: boolean;
+}
+/** Tier the resolver traversed to land the target. Callers may surface this to agents. */
+export type TargetMatchLevel = 'exact' | 'stable' | 'reidentified';
 /**
  * Generate JS that resolves a target to a single DOM element.
  *
  * Returns a JS expression that evaluates to:
- *   { ok: true, el: Element }                      — success (el is assigned to `__resolved`)
- *   { ok: false, code, message, hint, candidates }  — structured error
+ *   { ok: true, matches_n, match_level }            — success (el stored in `__resolved`)
+ *   { ok: false, code, message, hint, candidates, matches_n? }  — structured error
+ *
+ * `match_level` is always set on success:
+ *   - CSS path → 'exact'
+ *   - numeric ref path → whichever tier matched ('exact' / 'stable' / 'reidentified')
  *
- * The resolved element is stored in `__resolved` for the caller to use.
+ * The resolved element is stored in `window.__resolved` for downstream helpers.
  */
-export declare function resolveTargetJs(ref: string): string;
+export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): string;
 /**
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.