publishport-opencli 1.0.0

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

@@ -0,0 +1,423 @@
+export function resolveTargetJs(j,g={}){const q=JSON.stringify(j),w=g.nth!==void 0?String(g.nth|0):"null",y=g.firstOnMulti===!0?"true":"false";return`
+    (() => {
+      const ref = ${q};
+      const nth = ${w};
+      const firstOnMulti = ${y};
+      const identity = window.__opencli_ref_identity || {};
+
+      // ── Classify input ──
+      // Numeric = snapshot ref. Everything else is handed to querySelectorAll
+      // and whatever the browser parser accepts is a valid selector. No regex
+      // shortlist up front: \`find --css\` and \`get/click/type/select\` must agree
+      // on the same selector surface (see contract note at the top of this file).
+      const isNumeric = /^\\d+$/.test(ref);
+
+      if (isNumeric) {
+        // ── Ref path (cascading match levels) ──
+
+        // Shared helper: compute a fingerprint off a live element, same shape
+        // snapshot + find populate into \`__opencli_ref_identity\`. Kept inline
+        // (not imported) because this source string is compiled standalone.
+        function fingerprintOf(node) {
+          return {
+            tag: node.tagName.toLowerCase(),
+            role: node.getAttribute('role') || '',
+            text: (node.textContent || '').trim().slice(0, 30),
+            ariaLabel: node.getAttribute('aria-label') || '',
+            id: node.id || '',
+            testId: node.getAttribute('data-testid') || node.getAttribute('data-test') || '',
+          };
+        }
+
+        // Classify how strongly a live element matches a stored fingerprint.
+        // Returns one of 'exact' | 'stable' | 'mismatch'.
+        //
+        // 'exact'  — tag + every non-empty stored field agrees (±text prefix).
+        // 'stable' — tag agrees AND at least one strong id (id or testId) still
+        //            matches; soft signals (aria-label, role, text) may have
+        //            drifted. This covers SPA re-render / i18n label swaps.
+        // 'mismatch' otherwise.
+        function classifyMatch(fp, liveFp) {
+          if (fp.tag !== liveFp.tag) return 'mismatch';
+
+          const idMatch = !fp.id || fp.id === liveFp.id;
+          const testIdMatch = !fp.testId || fp.testId === liveFp.testId;
+          const roleMatch = !fp.role || fp.role === liveFp.role;
+          const ariaMatch = !fp.ariaLabel || fp.ariaLabel === liveFp.ariaLabel;
+          const textMatch = !fp.text || (
+            !!liveFp.text && (liveFp.text.startsWith(fp.text) || fp.text.startsWith(liveFp.text))
+          );
+
+          if (idMatch && testIdMatch && roleMatch && ariaMatch && textMatch) return 'exact';
+
+          // Strong id decides: if id + testId still agree and we had at least one
+          // of them, accept as stable regardless of soft-signal drift.
+          const hadStrongId = !!fp.id || !!fp.testId;
+          if (hadStrongId && idMatch && testIdMatch) return 'stable';
+
+          return 'mismatch';
+        }
+
+        // Try to recover a stale ref by searching the page for a live element
+        // whose fingerprint still matches. Uniqueness is required — if two
+        // candidates match equally well, we refuse rather than silently pick
+        // the wrong one. Covers ref annotations lost to a re-mount.
+        function reidentify(fp) {
+          if (!fp) return null;
+          const candidates = [];
+          function tryAdd(el) {
+            if (el && el.nodeType === 1 && classifyMatch(fp, fingerprintOf(el)) !== 'mismatch') {
+              if (candidates.indexOf(el) === -1) candidates.push(el);
+            }
+          }
+          // Prefer strong-id lookups. If id / testId is present and yields a
+          // unique element, that's our hit.
+          try {
+            if (fp.id) {
+              const byId = document.getElementById(fp.id);
+              if (byId) tryAdd(byId);
+            }
+            if (fp.testId) {
+              const byTestIdA = document.querySelectorAll('[data-testid="' + fp.testId.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byTestIdA.length; i++) tryAdd(byTestIdA[i]);
+              const byTestIdB = document.querySelectorAll('[data-test="' + fp.testId.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byTestIdB.length; i++) tryAdd(byTestIdB[i]);
+            }
+            // aria-label is only a useful shortlist when nothing stronger is set
+            if (candidates.length === 0 && fp.ariaLabel) {
+              const byAria = document.querySelectorAll('[aria-label="' + fp.ariaLabel.replace(/"/g, '\\\\"') + '"]');
+              for (let i = 0; i < byAria.length; i++) tryAdd(byAria[i]);
+            }
+          } catch (_) { /* bad selectors from weird fp values — skip */ }
+          return candidates.length === 1 ? candidates[0] : null;
+        }
+
+        const fp = identity[ref];
+        let el = document.querySelector('[data-opencli-ref="' + ref + '"]');
+        if (!el) el = document.querySelector('[data-ref="' + ref + '"]');
+
+        // If the ref tag is gone from the DOM, last-chance reidentify.
+        if (!el) {
+          const recovered = reidentify(fp);
+          if (recovered) {
+            try {
+              recovered.setAttribute('data-opencli-ref', ref);
+              identity[ref] = fingerprintOf(recovered);
+            } catch (_) {}
+            window.__resolved = recovered;
+            return { ok: true, matches_n: 1, match_level: 'reidentified' };
+          }
+          return {
+            ok: false,
+            code: 'not_found',
+            message: 'ref=' + ref + ' not found in DOM',
+            hint: 'The element may have been removed. Re-run \`opencli browser state\` to get a fresh snapshot.',
+          };
+        }
+
+        // No stored fingerprint (older page / unknown ref) — accept as exact.
+        if (!fp) {
+          window.__resolved = el;
+          return { ok: true, matches_n: 1, match_level: 'exact' };
+        }
+
+        const liveFp = fingerprintOf(el);
+        const level = classifyMatch(fp, liveFp);
+
+        if (level === 'exact' || level === 'stable') {
+          window.__resolved = el;
+          return { ok: true, matches_n: 1, match_level: level };
+        }
+
+        // Tag / strong-id mismatch — try to find the real element elsewhere
+        // before giving up. Covers e.g. a modal re-mount that discarded the
+        // data-opencli-ref attribute on the surviving node.
+        const recovered = reidentify(fp);
+        if (recovered && recovered !== el) {
+          try {
+            el.removeAttribute('data-opencli-ref');
+            recovered.setAttribute('data-opencli-ref', ref);
+            identity[ref] = fingerprintOf(recovered);
+          } catch (_) {}
+          window.__resolved = recovered;
+          return { ok: true, matches_n: 1, match_level: 'reidentified' };
+        }
+
+        return {
+          ok: false,
+          code: 'stale_ref',
+          message: 'ref=' + ref + ' was <' + fp.tag + '>' + (fp.text ? '"' + fp.text + '"' : '')
+            + ' but now points to <' + liveFp.tag + '>' + (liveFp.text ? '"' + liveFp.text.slice(0, 30) + '"' : ''),
+          hint: 'The page has changed since the last snapshot. Re-run \`opencli browser state\` to refresh.',
+        };
+      }
+
+      // ── CSS selector path (any non-numeric input) ──
+      {
+        let matches;
+        try {
+          matches = document.querySelectorAll(ref);
+        } catch (e) {
+          return {
+            ok: false,
+            code: 'invalid_selector',
+            message: 'Invalid CSS selector: ' + ref + ' (' + ((e && e.message) || String(e)) + ')',
+            hint: 'Check the selector syntax. Use ref numbers from snapshot for reliable targeting.',
+          };
+        }
+
+        if (matches.length === 0) {
+          return {
+            ok: false,
+            code: 'selector_not_found',
+            message: 'CSS selector "' + ref + '" matched 0 elements',
+            hint: 'The element may not exist or may be hidden. Re-run \`opencli browser state\` to check, or use \`opencli browser find --css\` to explore candidates.',
+            matches_n: 0,
+          };
+        }
+
+        if (nth !== null) {
+          if (nth < 0 || nth >= matches.length) {
+            return {
+              ok: false,
+              code: 'selector_nth_out_of_range',
+              message: 'CSS selector "' + ref + '" matched ' + matches.length + ' elements, but --nth=' + nth + ' is out of range',
+              hint: 'Use --nth between 0 and ' + (matches.length - 1) + ', or omit --nth to target the first match (read ops) or require explicit disambiguation (write ops).',
+              matches_n: matches.length,
+            };
+          }
+          window.__resolved = matches[nth];
+          return { ok: true, matches_n: matches.length, match_level: 'exact' };
+        }
+
+        if (matches.length > 1 && !firstOnMulti) {
+          const candidates = [];
+          const limit = Math.min(matches.length, 5);
+          for (let i = 0; i < limit; i++) {
+            const m = matches[i];
+            const tag = m.tagName.toLowerCase();
+            const text = (m.textContent || '').trim().slice(0, 40);
+            const id = m.id ? '#' + m.id : '';
+            candidates.push('<' + tag + id + '>' + (text ? ' "' + text + '"' : ''));
+          }
+          return {
+            ok: false,
+            code: 'selector_ambiguous',
+            message: 'CSS selector "' + ref + '" matched ' + matches.length + ' elements',
+            hint: 'Pass --nth <n> (0-based) to pick one, or use a more specific selector. Use \`opencli browser find --css\` to list all candidates.',
+            candidates: candidates,
+            matches_n: matches.length,
+          };
+        }
+
+        // Single match, OR multi-match with firstOnMulti (read path)
+        window.__resolved = matches[0];
+        return { ok: true, matches_n: matches.length, match_level: 'exact' };
+      }
+    })()
+  `}export function boundingRectResolvedJs(j={}){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (${j.skipScroll?"false":"true"}) el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      const rect = el.getBoundingClientRect();
+      const w = Math.round(rect.width);
+      const h = Math.round(rect.height);
+      const x = Math.round(rect.left + rect.width / 2);
+      const y = Math.round(rect.top + rect.height / 2);
+      const visible = w > 0 && h > 0;
+      return { x, y, w, h, visible };
+    })()
+  `}export function clickResolvedJs(j={}){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (${j.skipScroll?"false":"true"}) el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      const rect = el.getBoundingClientRect();
+      const x = Math.round(rect.left + rect.width / 2);
+      const y = Math.round(rect.top + rect.height / 2);
+      try {
+        el.click();
+        return { status: 'clicked', x, y, w: Math.round(rect.width), h: Math.round(rect.height) };
+      } catch (e) {
+        return { status: 'js_failed', x, y, w: Math.round(rect.width), h: Math.round(rect.height), error: e.message };
+      }
+    })()
+  `}export function typeResolvedJs(j){const g=JSON.stringify(j);return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      el.focus();
+      if (el.isContentEditable) {
+        const sel = window.getSelection();
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        document.execCommand('delete', false);
+        document.execCommand('insertText', false, ${g});
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+      } else {
+        const proto = el instanceof HTMLTextAreaElement
+          ? HTMLTextAreaElement.prototype
+          : HTMLInputElement.prototype;
+        const nativeSetter = Object.getOwnPropertyDescriptor(proto, 'value')?.set;
+        if (nativeSetter) {
+          nativeSetter.call(el, ${g});
+        } else {
+          el.value = ${g};
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+      }
+      return 'typed';
+    })()
+  `}export function prepareNativeTypeResolvedJs(j={}){const g=j.skipScroll?"false":"true",q=j.skipFocus?"false":"true";return`
+    (() => {
+      const original = window.__resolved;
+      if (!original) throw new Error('No resolved element');
+
+      function nearestContentEditableHost(el) {
+        let current = el;
+        while (current && current.nodeType === 1) {
+          if (current.hasAttribute && current.hasAttribute('contenteditable')) return current;
+          current = current.parentElement;
+        }
+        return el.isContentEditable ? el : null;
+      }
+
+      const editableHost = original.isContentEditable ? nearestContentEditableHost(original) : null;
+      const inputTypes = new Set(['', 'text', 'search', 'url', 'tel', 'email', 'password']);
+      const isInput = original instanceof HTMLInputElement;
+      const isTextarea = original instanceof HTMLTextAreaElement;
+      const isTextControl = isTextarea || (isInput && inputTypes.has((original.getAttribute('type') || original.type || '').toLowerCase()));
+      const el = editableHost || (isTextControl ? original : null);
+
+      if (!el) {
+        return {
+          ok: false,
+          reason: 'not_editable',
+          tag: original.tagName ? original.tagName.toLowerCase() : '',
+        };
+      }
+
+      window.__resolved = el;
+      if (${g}) el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
+      if (${q}) {
+        try {
+          el.focus({ preventScroll: true });
+        } catch (_) {
+          el.focus();
+        }
+      }
+
+      if (editableHost) {
+        const sel = window.getSelection();
+        if (!sel) return { ok: false, reason: 'selection_unavailable', mode: 'contenteditable' };
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        return { ok: true, mode: 'contenteditable' };
+      }
+
+      let selected = false;
+      try {
+        if (typeof el.setSelectionRange === 'function') {
+          el.setSelectionRange(0, String(el.value || '').length);
+          selected = true;
+        }
+      } catch (_) {}
+      try {
+        if (!selected && typeof el.select === 'function') {
+          el.select();
+          selected = true;
+        }
+      } catch (_) {}
+
+      return selected
+        ? { ok: true, mode: isTextarea ? 'textarea' : 'input' }
+        : { ok: false, reason: 'selection_unavailable', mode: isTextarea ? 'textarea' : 'input' };
+    })()
+  `}export function verifyFilledResolvedJs(j){const g=JSON.stringify(j);return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) return { ok: false, reason: 'no_resolved_element' };
+
+      const tag = el.tagName ? el.tagName.toLowerCase() : '';
+      const isInput = el instanceof HTMLInputElement;
+      const isTextarea = el instanceof HTMLTextAreaElement;
+      const mode = el.isContentEditable
+        ? 'contenteditable'
+        : isTextarea
+          ? 'textarea'
+          : isInput
+            ? 'input'
+            : '';
+
+      if (!mode) {
+        return {
+          ok: false,
+          reason: 'not_editable',
+          tag,
+          role: el.getAttribute ? (el.getAttribute('role') || '') : '',
+        };
+      }
+
+      const actual = mode === 'contenteditable' ? (el.innerText || '') : String(el.value || '');
+      return {
+        ok: actual === ${g},
+        actual,
+        expected: ${g},
+        length: actual.length,
+        mode,
+      };
+    })()
+  `}export function scrollResolvedJs(j={}){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (${j.skipScroll?"false":"true"}) el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
+      return { scrolled: true, tag: el.tagName.toLowerCase(), text: (el.textContent || '').trim().slice(0, 80) };
+    })()
+  `}export function getTextResolvedJs(){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return el.textContent?.trim() ?? null;
+    })()
+  `}export function getValueResolvedJs(){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return el.value ?? null;
+    })()
+  `}export function getAttributesResolvedJs(){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      return JSON.stringify(Object.fromEntries([...el.attributes].map(a => [a.name, a.value])));
+    })()
+  `}export function selectResolvedJs(j){const g=JSON.stringify(j);return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (el.tagName !== 'SELECT') return { error: 'Not a <select>' };
+      const match = Array.from(el.options).find(o => o.text.trim() === ${g} || o.value === ${g});
+      if (!match) return { error: 'Option not found', available: Array.from(el.options).map(o => o.text.trim()) };
+      const setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+      if (setter) setter.call(el, match.value); else el.value = match.value;
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+      return { selected: match.text };
+    })()
+  `}export function isAutocompleteResolvedJs(){return`
+    (() => {
+      const el = window.__resolved;
+      if (!el) return false;
+      const role = el.getAttribute('role');
+      const ac = el.getAttribute('aria-autocomplete');
+      const list = el.getAttribute('list');
+      return role === 'combobox' || ac === 'list' || ac === 'both' || !!list;
+    })()
+  `}

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

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

package/dist/src/browser/trace.d.ts

@@ -0,0 +1,21 @@
+interface CommandBody {
+    id?: unknown;
+    action?: unknown;
+    contextId?: unknown;
+    session?: unknown;
+    surface?: unknown;
+    url?: unknown;
+}
+/** 命令已下发给扩展。 */
+export declare function traceDispatch(body: CommandBody): void;
+/** 命令拿到结果（成功 / 业务失败 / 断连致 result-unknown）。ms = dispatch→result 的延迟。 */
+export declare function traceResult(id: string, ok: boolean, ms: number, errorCode?: string, page?: string): void;
+/** 命令超时（daemon 侧 timeoutMs 到点仍无结果）。 */
+export declare function traceTimeout(id: string, ms: number, action?: string): void;
+/** 扩展（某 profile/contextId）连上 daemon。冷启后的首个 connect 即重连开销的右端点。 */
+export declare function traceExtConnect(ctx: string, extVersion?: string | null): void;
+/** 扩展断开。与下一个 ext-connect 配对即一次重连开销。 */
+export declare function traceExtDisconnect(ctx: string): void;
+/** 扩展转发来的 console 日志（Phase 2 的开窗 / 复用 / 销毁细节走这条）。 */
+export declare function traceExtLog(level: string, msg: string): void;
+export {};

package/dist/src/browser/trace.js

@@ -0,0 +1,2 @@
+import{appendFileSync as N}from"node:fs";import{log as O}from"../logger.js";const H=process.env.OPENCLI_BROWSER_TRACE_FILE?.trim(),B=!!H;let J=!1;function G(q){if(!B)return;try{N(H,JSON.stringify({t:Date.now(),...q})+`
+`)}catch(z){if(!J){J=!0;O.warn(`[trace] failed to write browser trace to ${H}: ${z instanceof Error?z.message:String(z)} (further trace errors suppressed)`)}}}function Q(q,z){if(q!=="navigate"||typeof z!=="string"||!z)return;try{const D=new URL(z);return D.origin+D.pathname}catch{return}}export function traceDispatch(q){if(!B)return;G({ev:"dispatch",id:typeof q.id==="string"?q.id:void 0,action:typeof q.action==="string"?q.action:"unknown",ctx:typeof q.contextId==="string"?q.contextId:void 0,session:typeof q.session==="string"?q.session:void 0,surface:typeof q.surface==="string"?q.surface:void 0,url:Q(q.action,q.url)})}export function traceResult(q,z,D,K,M){if(!B)return;G({ev:"result",id:q,ok:z,ms:D,errorCode:K,page:M})}export function traceTimeout(q,z,D){if(!B)return;G({ev:"timeout",id:q,ms:z,action:D})}export function traceExtConnect(q,z){if(!B)return;G({ev:"ext-connect",ctx:q,extVersion:z??void 0})}export function traceExtDisconnect(q){if(!B)return;G({ev:"ext-disconnect",ctx:q})}export function traceExtLog(q,z){if(!B)return;G({ev:"ext-log",level:q,msg:z})}

package/dist/src/browser/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for browser operations
+ */
+type EvaluateFunction = (...args: never[]) => unknown;
+/**
+ * Serialize a function-form page.evaluate call for CDP Runtime.evaluate.
+ *
+ * Functions execute in the browser page context, so they cannot close over
+ * Node-side variables. Pass external values as JSON-serializable args instead.
+ */
+export declare function serializeFunctionForEval(fn: EvaluateFunction, args?: readonly unknown[]): string;
+/**
+ * Wrap JS code for CDP Runtime.evaluate:
+ * - Already an IIFE `(...)()` → send as-is
+ * - Arrow/function literal → wrap as IIFE `(code)()`
+ * - `new Promise(...)` or raw expression → send as-is (expression)
+ */
+export declare function wrapForEval(js: string): string;
+export declare function buildEvaluateExpression(input: string | EvaluateFunction, args?: readonly unknown[]): string;
+export {};

package/dist/src/browser/utils.js

@@ -0,0 +1 @@
+function G(q){return q instanceof Error?q.message:String(q)}export function serializeFunctionForEval(q,k=[]){const B=q.toString().trim();if(!(/^(async\s+)?function[\s(]/.test(B)||/^(async\s*)?(\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/.test(B))||B.includes("[native code]"))throw Error("page.evaluate(fn) requires a serializable arrow/function expression");let C;try{C=JSON.stringify(k)}catch(D){throw Error(`page.evaluate arguments must be JSON-serializable: ${G(D)}`)}if(C===void 0)throw Error("page.evaluate arguments must be JSON-serializable");return`(${B})(...${C})`}export function wrapForEval(q){if(typeof q!=="string")return"undefined";const k=q.trim();if(!k)return"undefined";if(/^\([\s\S]*\)\s*\(.*\)\s*$/.test(k))return k;if(/^(async\s+)?(\([^)]*\)|[A-Za-z_]\w*)\s*=>/.test(k))return`(${k})()`;if(/^(async\s+)?function[\s(]/.test(k))return`(${k})()`;return k}export function buildEvaluateExpression(q,k=[]){if(typeof q==="function")return serializeFunctionForEval(q,k);if(k.length>0)throw Error("page.evaluate string input does not accept args; use page.evaluate(fn, ...args) instead");return wrapForEval(q)}

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

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

package/dist/src/browser/verify-fixture.d.ts

@@ -0,0 +1,65 @@
+export type FixtureExpect = {
+    rowCount?: {
+        min?: number;
+        max?: number;
+    };
+    columns?: string[];
+    types?: Record<string, string>;
+    patterns?: Record<string, string>;
+    notEmpty?: string[];
+    /**
+     * Substrings/regex fragments that MUST NOT appear in the column value.
+     *
+     * Catches silent content contamination that `notEmpty` alone misses —
+     * e.g. a `description` field that accidentally carries "address: ..." /
+     * "category: ..." fragments from sibling DOM nodes, or a `title` that
+     * bled in a navigation-breadcrumb prefix. Each entry is matched as a
+     * plain substring against the stringified column value.
+     */
+    mustNotContain?: Record<string, string[]>;
+    /**
+     * Columns whose values must be truthy. Complements `notEmpty` (which
+     * only rejects empty-string/null/undefined) by also catching silent
+     * `|| 0` / `|| false` fallbacks in numeric/boolean fields. Fires when
+     * the value coerces to `false` in JS.
+     */
+    mustBeTruthy?: string[];
+};
+export type FixtureArgs = Record<string, unknown> | unknown[];
+export type Fixture = {
+    args?: FixtureArgs;
+    expect?: FixtureExpect;
+};
+export type ValidationFailure = {
+    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy' | 'shapeKeyCount' | 'shapeDepth' | 'shapeNestedId';
+    detail: string;
+    rowIndex?: number;
+};
+export type Row = Record<string, unknown>;
+export type RowShapeOptions = {
+    maxTopLevelKeys?: number;
+    maxNestedDepth?: number;
+};
+export declare function fixturePath(site: string, command: string): string;
+export declare function loadFixture(site: string, command: string): Fixture | null;
+export declare function writeFixture(site: string, command: string, fixture: Fixture): string;
+/**
+ * Derive a reasonable fixture from sample output. Used by `--write-fixture`
+ * to seed a first draft the author can hand-tune.
+ *
+ * Heuristics:
+ * - rowCount.min = 1 if rows non-empty, else 0
+ * - columns = keys from the first row
+ * - types = typeof of the first row's values, with "number|string" for mixed
+ * - no auto patterns / notEmpty — author should add those deliberately
+ */
+export declare function deriveFixture(rows: Row[], args?: FixtureArgs): Fixture;
+export declare function validateRows(rows: Row[], fixture: Fixture): ValidationFailure[];
+export declare function validateRowShape(rows: Row[], opts?: RowShapeOptions): ValidationFailure[];
+/**
+ * Convert fixture args into argv tokens appended after the command name.
+ * - Array form is passed through verbatim (stringified), supporting positional subjects.
+ * - Object form is expanded to `--key value` pairs.
+ */
+export declare function expandFixtureArgs(args: FixtureArgs | undefined): string[];
+export declare function parseSeedArgs(raw: string | undefined): FixtureArgs | undefined;

package/dist/src/browser/verify-fixture.js

@@ -0,0 +1,2 @@
+import*as O from"node:fs";import*as b from"node:os";import*as M from"node:path";const I=12,K=1,S=[/^id$/i,/_id$/i,/Id$/,/^short_id$/i,/^bvid$/i,/^aid$/i,/^tid$/i,/^asin$/i,/^sku$/i,/^isbn$/i,/^doi$/i,/^slug$/i,/^hn_id$/i,/^username$/i,/^handle$/i,/^uri$/i];export function fixturePath(z,G){return M.join(b.homedir(),".opencli","sites",z,"verify",`${G}.json`)}export function loadFixture(z,G){const q=fixturePath(z,G);if(!O.existsSync(q))return null;try{const B=O.readFileSync(q,"utf-8");return JSON.parse(B)}catch(B){throw Error(`Failed to parse fixture ${q}: ${B instanceof Error?B.message:String(B)}`)}}export function writeFixture(z,G,q){const B=fixturePath(z,G);O.mkdirSync(M.dirname(B),{recursive:!0});O.writeFileSync(B,`${JSON.stringify(q,null,2)}
+`,"utf-8");return B}export function deriveFixture(z,G){const q={};if(z.length===0){q.rowCount={min:0};return{...G?{args:G}:{},expect:q}}q.rowCount={min:1};const B=z[0],Z=Object.keys(B);q.columns=Z;const R={};for(const V of Z){const F=new Set;for(const H of z){const Q=H[V];F.add(j(Q))}R[V]=[...F].sort().join("|")}q.types=R;return{...G?{args:G}:{},expect:q}}export function validateRows(z,G){const q=[],B=G.expect;if(!B)return q;if(B.rowCount){const{min:Q,max:W}=B.rowCount;if(typeof Q==="number"&&z.length<Q)q.push({rule:"rowCount",detail:`got ${z.length} rows, expected at least ${Q}`});if(typeof W==="number"&&z.length>W)q.push({rule:"rowCount",detail:`got ${z.length} rows, expected at most ${W}`})}const Z=B.columns??[],R=B.types??{},V=B.patterns??{},F=B.notEmpty??[],H={};for(const[Q,W]of Object.entries(V))try{H[Q]=new RegExp(W)}catch(J){q.push({rule:"pattern",detail:`pattern for "${Q}" invalid: ${J instanceof Error?J.message:String(J)}`})}z.forEach((Q,W)=>{for(const J of Z)if(!(J in Q))q.push({rule:"column",detail:`missing column "${J}"`,rowIndex:W});for(const[J,$]of Object.entries(R)){if(!(J in Q))continue;const C=j(Q[J]);if(!A(C,$))q.push({rule:"type",detail:`"${J}" is ${C}, expected ${$}`,rowIndex:W})}for(const[J,$]of Object.entries(H)){if(!(J in Q))continue;const C=Q[J];if(C===null||C===void 0)continue;if(!$.test(String(C)))q.push({rule:"pattern",detail:`"${J}"=${JSON.stringify(String(C).slice(0,60))} does not match /${$.source}/`,rowIndex:W})}for(const J of F){const $=Q[J];if($===null||$===void 0||String($).trim()==="")q.push({rule:"notEmpty",detail:`"${J}" is empty`,rowIndex:W})}for(const[J,$]of Object.entries(B.mustNotContain??{})){if(!(J in Q))continue;const C=Q[J];if(C===null||C===void 0)continue;const N=String(C);for(const Y of $)if(N.includes(Y))q.push({rule:"mustNotContain",detail:`"${J}" contains forbidden substring ${JSON.stringify(Y)}`,rowIndex:W})}for(const J of B.mustBeTruthy??[]){if(!(J in Q))continue;if(!Q[J])q.push({rule:"mustBeTruthy",detail:`"${J}" is falsy (${JSON.stringify(Q[J])}) — likely silent fallback`,rowIndex:W})}});return q}export function validateRowShape(z,G={}){const q=[],B=G.maxTopLevelKeys??I,Z=G.maxNestedDepth??K;z.forEach((R,V)=>{const F=Object.keys(R);if(F.length>B)q.push({rule:"shapeKeyCount",detail:`row has ${F.length} top-level keys, expected at most ${B}`,rowIndex:V});for(const[H,Q]of Object.entries(R)){const W=U(Q);if(W>Z)q.push({rule:"shapeDepth",detail:`"${H}" nesting depth is ${W}, expected at most ${Z}`,rowIndex:V});for(const J of X(Q,H))q.push({rule:"shapeNestedId",detail:`id-shaped field "${J}" must be a top-level row key`,rowIndex:V})}});return q}export function expandFixtureArgs(z){if(!z)return[];if(Array.isArray(z))return z.map((q)=>String(q));const G=[];for(const[q,B]of Object.entries(z))G.push(`--${q}`,String(B));return G}export function parseSeedArgs(z){if(z===void 0)return;const G=z.trim();if(!G)return;try{const q=JSON.parse(G);if(Array.isArray(q))return q;if(q!==null&&typeof q==="object")return q;return[q]}catch{return[z]}}function j(z){if(z===null)return"null";if(Array.isArray(z))return"array";return typeof z}function U(z){if(z===null||z===void 0||typeof z!=="object")return 0;if(Array.isArray(z)){if(z.length===0)return 1;return 1+Math.max(...z.map(U))}const G=Object.values(z);if(G.length===0)return 1;return 1+Math.max(...G.map(U))}function X(z,G){if(z===null||z===void 0||typeof z!=="object")return[];const q=[];if(Array.isArray(z)){z.forEach((B,Z)=>{q.push(...X(B,`${G}[${Z}]`))});return q}for(const[B,Z]of Object.entries(z)){const R=`${G}.${B}`;if(L(B))q.push(R);q.push(...X(Z,R))}return q}function L(z){return S.some((G)=>G.test(z))}function A(z,G){const q=G.split("|").map((B)=>B.trim()).filter(Boolean);if(q.length===0)return!0;if(q.includes("any"))return!0;return q.includes(z)}

package/dist/src/browser/verify-fixture.test.d.ts

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

package/dist/src/browser/visual-refs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Visual ref overlay for annotated screenshots.
+ *
+ * The overlay is intentionally DOM-side and temporary. It reuses the same
+ * `data-opencli-ref` attributes produced by the DOM snapshot path so the
+ * screenshot labels map back to normal `browser click <ref>` targets.
+ */
+export declare function installVisualRefOverlayJs(opts?: {
+    maxRefs?: number;
+}): string;
+export declare function removeVisualRefOverlayJs(): string;

package/dist/src/browser/visual-refs.js

@@ -0,0 +1,94 @@
+const e="__opencli_visual_ref_overlay";export function installVisualRefOverlayJs(t={}){const n=Math.max(1,Math.min(t.maxRefs??120,500));return`
+    (() => {
+      const OVERLAY_ID = ${JSON.stringify(e)};
+      const MAX_REFS = ${n};
+      document.getElementById(OVERLAY_ID)?.remove();
+
+      const overlay = document.createElement('div');
+      overlay.id = OVERLAY_ID;
+      overlay.setAttribute('aria-hidden', 'true');
+      Object.assign(overlay.style, {
+        position: 'fixed',
+        inset: '0',
+        zIndex: '2147483647',
+        pointerEvents: 'none',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+      });
+
+      const refs = Array.from(document.querySelectorAll('[data-opencli-ref]'))
+        .map((el) => {
+          const rawRef = el.getAttribute('data-opencli-ref') || '';
+          const ref = Number(rawRef);
+          const rect = el.getBoundingClientRect();
+          const visible = Number.isFinite(ref)
+            && rect.width >= 2
+            && rect.height >= 2
+            && rect.bottom >= 0
+            && rect.right >= 0
+            && rect.top <= window.innerHeight
+            && rect.left <= window.innerWidth;
+          return { el, rawRef, ref, rect, visible };
+        })
+        .filter((entry) => entry.visible)
+        .sort((a, b) => a.ref - b.ref)
+        .slice(0, MAX_REFS);
+
+      for (const entry of refs) {
+        const left = Math.max(0, Math.min(window.innerWidth - 1, entry.rect.left));
+        const top = Math.max(0, Math.min(window.innerHeight - 1, entry.rect.top));
+        const right = Math.max(0, Math.min(window.innerWidth, entry.rect.right));
+        const bottom = Math.max(0, Math.min(window.innerHeight, entry.rect.bottom));
+        const width = Math.max(2, right - left);
+        const height = Math.max(2, bottom - top);
+
+        const box = document.createElement('div');
+        Object.assign(box.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: top + 'px',
+          width: width + 'px',
+          height: height + 'px',
+          border: '2px solid #ff3b30',
+          borderRadius: '4px',
+          boxSizing: 'border-box',
+          boxShadow: '0 0 0 1px rgba(255,255,255,.9), 0 4px 16px rgba(0,0,0,.25)',
+          background: 'rgba(255,59,48,.08)',
+        });
+
+        const badge = document.createElement('div');
+        badge.textContent = entry.rawRef;
+        Object.assign(badge.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: Math.max(0, top - 20) + 'px',
+          minWidth: '18px',
+          height: '18px',
+          padding: '0 5px',
+          borderRadius: '999px',
+          border: '1px solid rgba(255,255,255,.95)',
+          background: '#ff3b30',
+          color: '#fff',
+          fontSize: '12px',
+          fontWeight: '700',
+          lineHeight: '18px',
+          textAlign: 'center',
+          textShadow: '0 1px 1px rgba(0,0,0,.25)',
+          boxShadow: '0 2px 8px rgba(0,0,0,.35)',
+        });
+
+        overlay.appendChild(box);
+        overlay.appendChild(badge);
+      }
+
+      document.documentElement.appendChild(overlay);
+      return {
+        annotated: refs.length,
+        truncated: refs.length >= MAX_REFS,
+      };
+    })()
+  `.trim()}export function removeVisualRefOverlayJs(){return`
+    (() => {
+      document.getElementById(${JSON.stringify(e)})?.remove();
+      return true;
+    })()
+  `.trim()}