@jackwener/opencli 1.7.14 → 1.7.16

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

@@ -68,9 +68,23 @@ export type TargetMatchLevel = 'exact' | 'stable' | 'reidentified';
  * The resolved element is stored in `window.__resolved` for downstream helpers.
  */
 export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): string;
+/**
+ * Generate JS that scrolls + measures `__resolved` without clicking.
+ *
+ * Generic click prefers CDP `Input.dispatchMouseEvent`, which fires the full
+ * pointer/mouse chain that Radix/MUI/shadcn dropdowns rely on. Keep measurement
+ * separate so the CDP-primary path does not call DOM `el.click()` first.
+ */
+export declare function boundingRectResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
+ *
+ * This is the JS fallback path. BasePage.click uses boundingRectResolvedJs for
+ * the CDP-primary path and only reaches this when native click is unavailable
+ * or the target has no usable rect.
  */
 export declare function clickResolvedJs(opts?: {
     skipScroll?: boolean;

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

@@ -273,9 +273,37 @@ export function resolveTargetJs(ref, opts = {}) {
     })()
   `;
 }
+/**
+ * Generate JS that scrolls + measures `__resolved` without clicking.
+ *
+ * Generic click prefers CDP `Input.dispatchMouseEvent`, which fires the full
+ * pointer/mouse chain that Radix/MUI/shadcn dropdowns rely on. Keep measurement
+ * separate so the CDP-primary path does not call DOM `el.click()` first.
+ */
+export function boundingRectResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) throw new Error('No resolved element');
+      if (${shouldScroll}) 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 };
+    })()
+  `;
+}
 /**
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
+ *
+ * This is the JS fallback path. BasePage.click uses boundingRectResolvedJs for
+ * the CDP-primary path and only reaches this when native click is unavailable
+ * or the target has no usable rect.
  */
 export function clickResolvedJs(opts = {}) {
     const shouldScroll = opts.skipScroll ? 'false' : 'true';

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,108 @@
+/**
+ * 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.
+ */
+const OVERLAY_ID = '__opencli_visual_ref_overlay';
+export function installVisualRefOverlayJs(opts = {}) {
+    const maxRefs = Math.max(1, Math.min(opts.maxRefs ?? 120, 500));
+    return `
+    (() => {
+      const OVERLAY_ID = ${JSON.stringify(OVERLAY_ID)};
+      const MAX_REFS = ${maxRefs};
+      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(OVERLAY_ID)})?.remove();
+      return true;
+    })()
+  `.trim();
+}

package/dist/src/build-manifest.d.ts

@@ -66,6 +66,29 @@ export declare function loadManifestEntries(filePath: string, site: string, impo
 export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
 export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+/**
+ * Metadata audit: every positional arg must carry a non-empty `help` string.
+ *
+ * Why this is a hard gate (not advisory):
+ *   - `opencli twitter followers --help` rendered `Arguments:\n  user  ` with
+ *     an empty trailing column. Agents and humans both saw a blank field —
+ *     impossible to recover the parameter's purpose without reading source.
+ *   - This is metadata completeness, not stylistic taste; failing closed is
+ *     the only way to keep the help surface trustworthy as adapters land.
+ *
+ * Note: semantic quality (e.g. "what does the optional positional mean when
+ * omitted?") is intentionally NOT enforced here. That belongs to a follow-up
+ * advisory audit — see PR plan `Arg metadata v2` for the structured
+ * `when_omitted / when_present / value_format` schema.
+ */
+export interface ManifestMetadataIssue {
+    site: string;
+    command: string;
+    arg: string;
+    sourceFile?: string;
+    reason: string;
+}
+export declare function findManifestMetadataIssues(entries: readonly ManifestEntry[]): ManifestMetadataIssue[];
 /**
  * Diff helper: returns site/name keys that exist in `prev` but not in
  * `next`. Used as a safety net to detect accidental mass-deletions caused

package/dist/src/build-manifest.js

@@ -209,6 +209,28 @@ export async function buildManifest() {
 export function serializeManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+export function findManifestMetadataIssues(entries) {
+    const issues = [];
+    for (const entry of entries) {
+        if (!Array.isArray(entry.args))
+            continue;
+        for (const arg of entry.args) {
+            if (!arg.positional)
+                continue;
+            const help = typeof arg.help === 'string' ? arg.help.trim() : '';
+            if (help === '') {
+                issues.push({
+                    site: entry.site,
+                    command: entry.name,
+                    arg: arg.name,
+                    sourceFile: entry.sourceFile,
+                    reason: 'positional arg missing non-empty `help` text',
+                });
+            }
+        }
+    }
+    return issues;
+}
 /**
  * Diff helper: returns site/name keys that exist in `prev` but not in
  * `next`. Used as a safety net to detect accidental mass-deletions caused
@@ -278,6 +300,18 @@ async function main() {
             + `Always run via tsx (\`npm run build-manifest\`), not against compiled dist/.\n`);
         process.exit(1);
     }
+    const metadataIssues = findManifestMetadataIssues(entries);
+    if (metadataIssues.length > 0) {
+        process.stderr.write(`❌ ${metadataIssues.length} positional arg(s) missing \`help\` text:\n`);
+        for (const issue of metadataIssues) {
+            const where = issue.sourceFile ? ` (${issue.sourceFile})` : '';
+            process.stderr.write(`  - ${issue.site}/${issue.command} positional "${issue.arg}"${where}\n`);
+        }
+        process.stderr.write(`\nEvery positional arg must declare a non-empty \`help\` string so\n`
+            + `\`opencli <site> <cmd> --help\` shows callers what the parameter is for.\n`
+            + `Add \`help: '...'\` to each arg above and re-run the build.\n`);
+        process.exit(1);
+    }
     const existing = readExistingManifest(OUTPUT);
     if (existing) {
         const removed = diffRemovedEntries(existing, entries);

package/dist/src/build-manifest.test.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, getRegistry, Strategy } from './registry.js';
-import { ManifestImportError, diffRemovedEntries, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
+import { ManifestImportError, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -222,6 +222,113 @@ describe('manifest helper rules', () => {
         expect(diffRemovedEntries(prev, prev)).toEqual([]);
         expect(diffRemovedEntries([], next)).toEqual([]);
     });
+    it('findManifestMetadataIssues flags positionals with empty/missing help', () => {
+        // The build-time hard gate. A positional with `help: ''` or no `help` at
+        // all renders `Arguments:\n  <name>` with a blank trailing column —
+        // unrecoverable for both humans and agents reading help. Failing closed
+        // here is the only way to keep help text trustworthy as adapters land.
+        //
+        // Semantic quality (e.g. what does an *optional* positional mean when
+        // omitted?) is intentionally NOT enforced — that belongs to the planned
+        // Arg metadata v2 advisory pass.
+        const entries = [
+            // Positional with usable help — clean.
+            {
+                site: 'demo',
+                name: 'ok',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'q', positional: true, required: true, help: 'Search query' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/ok.js',
+            },
+            // Positional with empty help string — must flag.
+            {
+                site: 'demo',
+                name: 'empty-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'user', positional: true, required: false, help: '' },
+                ],
+                type: 'js',
+                sourceFile: 'demo/empty.js',
+            },
+            // Positional with whitespace-only help — must flag.
+            {
+                site: 'demo',
+                name: 'whitespace-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'id', positional: true, required: true, help: '   ' },
+                ],
+                type: 'js',
+            },
+            // Positional with no help field at all — must flag.
+            {
+                site: 'demo',
+                name: 'missing-help',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'name', positional: true, required: true },
+                ],
+                type: 'js',
+            },
+            // NON-positional flag with empty help — must NOT flag (gate is
+            // intentionally scoped to positionals; named flags carry the flag
+            // name itself in the help line).
+            {
+                site: 'demo',
+                name: 'flag-only',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [
+                    { name: 'limit', required: false, help: '' },
+                ],
+                type: 'js',
+            },
+        ];
+        const issues = findManifestMetadataIssues(entries);
+        expect(issues).toHaveLength(3);
+        expect(issues.map(i => `${i.site}/${i.command}/${i.arg}`).sort()).toEqual([
+            'demo/empty-help/user',
+            'demo/missing-help/name',
+            'demo/whitespace-help/id',
+        ]);
+        // sourceFile flows through when present so the build error points at the
+        // exact file to fix.
+        const emptyHelp = issues.find(i => i.command === 'empty-help');
+        expect(emptyHelp?.sourceFile).toBe('demo/empty.js');
+    });
+    it('findManifestMetadataIssues returns [] for fully-documented entries', () => {
+        expect(findManifestMetadataIssues([])).toEqual([]);
+        expect(findManifestMetadataIssues([
+            {
+                site: 'demo',
+                name: 'no-args',
+                access: 'read',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [],
+                type: 'js',
+            },
+        ])).toEqual([]);
+    });
     it('parseBuildManifestArgs reads --allow-removals[=N]', () => {
         expect(parseBuildManifestArgs([]).allowRemovals).toBe(0);
         expect(parseBuildManifestArgs(['--allow-removals=5']).allowRemovals).toBe(5);