@jackwener/opencli 1.7.11 → 1.7.12

package/dist/src/browser/base-page.js

@@ -61,6 +61,7 @@ export class BasePage {
     _lastUrl = null;
     /** Cached previous snapshot hashes for incremental diff marking */
     _prevSnapshotHashes = null;
+    _cdpTargetMarkerSeq = 0;
     /**
      * Safely evaluate JS with pre-serialized arguments.
      * Each key in `args` becomes a `const` declaration with JSON-serialized value,
@@ -154,8 +155,9 @@ export class BasePage {
     async click(ref, opts = {}) {
         // Phase 1: Resolve target with fingerprint verification
         const resolved = await runResolve(this, ref, opts);
+        const nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
         // Phase 2: Execute click on resolved element
-        const result = await this.evaluate(clickResolvedJs());
+        const result = await this.evaluate(clickResolvedJs({ skipScroll: nativeScrolled }));
         if (typeof result === 'string' || result == null)
             return resolved;
         if (result.status === 'clicked')
@@ -217,12 +219,78 @@ export class BasePage {
             return false;
         }
     }
+    /**
+     * Run a DOM-domain CDP command against `window.__resolved`.
+     *
+     * CDP DOM.focus / DOM.scrollIntoViewIfNeeded need a nodeId, while our
+     * resolver stores the live Element in page JS. Bridge the two worlds with a
+     * short-lived marker attribute, then query it through CDP.
+     */
+    async tryCdpOnResolvedElement(method) {
+        const cdp = this.cdp;
+        if (typeof cdp !== 'function')
+            return false;
+        const markerAttr = 'data-opencli-cdp-target';
+        const markerValue = `${Date.now().toString(36)}-${++this._cdpTargetMarkerSeq}`;
+        const selector = `[${markerAttr}="${markerValue}"]`;
+        let marked = false;
+        try {
+            const marker = await this.evaluateWithArgs(`
+        (() => {
+          const el = window.__resolved;
+          if (!el || el.nodeType !== 1 || typeof el.setAttribute !== 'function') {
+            return { ok: false };
+          }
+          el.setAttribute(markerAttr, markerValue);
+          return { ok: true };
+        })()
+      `, { markerAttr, markerValue });
+            marked = marker?.ok === true;
+            if (!marked)
+                return false;
+            await cdp.call(this, 'DOM.enable', {}).catch(() => undefined);
+            const doc = await cdp.call(this, 'DOM.getDocument', {});
+            const rootNodeId = doc?.root?.nodeId;
+            if (typeof rootNodeId !== 'number')
+                return false;
+            const query = await cdp.call(this, 'DOM.querySelector', {
+                nodeId: rootNodeId,
+                selector,
+            });
+            const nodeId = query?.nodeId;
+            if (typeof nodeId !== 'number' || nodeId <= 0)
+                return false;
+            await cdp.call(this, method, { nodeId });
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (marked) {
+                await this.evaluateWithArgs(`
+          (() => {
+            for (const el of document.querySelectorAll(selector)) {
+              el.removeAttribute(markerAttr);
+            }
+          })()
+        `, { selector, markerAttr }).catch(() => undefined);
+            }
+        }
+    }
     async typeText(ref, text, opts = {}) {
         const resolved = await runResolve(this, ref, opts);
         let typed = false;
+        let nativeScrolled = false;
+        let nativeFocused = false;
         if (typeof this.nativeType === 'function' || typeof this.insertText === 'function') {
             try {
-                const preparation = await this.evaluate(prepareNativeTypeResolvedJs());
+                nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
+                nativeFocused = await this.tryCdpOnResolvedElement('DOM.focus');
+                const preparation = await this.evaluate(prepareNativeTypeResolvedJs({
+                    skipScroll: nativeScrolled,
+                    skipFocus: nativeFocused,
+                }));
                 typed = preparation?.ok === true && await this.tryNativeType(text);
             }
             catch {
@@ -243,7 +311,8 @@ export class BasePage {
     }
     async scrollTo(ref, opts = {}) {
         const resolved = await runResolve(this, ref, opts);
-        const result = (await this.evaluate(scrollResolvedJs()));
+        const nativeScrolled = await this.tryCdpOnResolvedElement('DOM.scrollIntoViewIfNeeded');
+        const result = (await this.evaluate(scrollResolvedJs({ skipScroll: nativeScrolled })));
         // Fold match_level into the scroll payload so the user-facing envelope
         // carries it the same way click / type do.
         if (result && typeof result === 'object') {

package/dist/src/browser/base-page.test.js

@@ -17,15 +17,23 @@ class TestPage extends BasePage {
 }
 class ActionPage extends BasePage {
     results = [];
+    withArgsResults = [];
     scripts = [];
+    withArgs = [];
     nativeType;
     insertText;
     nativeKeyPress;
+    cdp;
     async goto() { }
     async evaluate(js) {
         this.scripts.push(js);
         return this.results.shift() ?? null;
     }
+    async evaluateWithArgs(js, args) {
+        this.scripts.push(js);
+        this.withArgs.push(args);
+        return this.withArgsResults.shift() ?? null;
+    }
     async getCookies() { return []; }
     async screenshot() { return ''; }
     async tabs() { return []; }
@@ -100,6 +108,27 @@ describe('BasePage native input routing', () => {
         expect(page.scripts[1]).toContain('nearestContentEditableHost');
         expect(page.scripts.join('\n')).not.toContain("return 'typed'");
     });
+    it('uses CDP DOM focus and scroll before native text insertion when available', async () => {
+        const page = new ActionPage();
+        page.nativeType = vi.fn().mockResolvedValue(undefined);
+        page.cdp = vi.fn()
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 7 })
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 7 })
+            .mockResolvedValueOnce({});
+        page.results = [resolveOk, { ok: true, mode: 'input' }];
+        page.withArgsResults = [{ ok: true }, undefined, { ok: true }, undefined];
+        await page.typeText('#q', 'hello');
+        expect(page.cdp).toHaveBeenCalledWith('DOM.scrollIntoViewIfNeeded', { nodeId: 7 });
+        expect(page.cdp).toHaveBeenCalledWith('DOM.focus', { nodeId: 7 });
+        expect(page.nativeType).toHaveBeenCalledWith('hello');
+        expect(page.scripts.at(-1)).toContain('if (false) el.scrollIntoView');
+        expect(page.scripts.at(-1)).toContain('if (false) {');
+    });
     it('keeps the DOM setter fallback when native text insertion is unavailable', async () => {
         const page = new ActionPage();
         page.results = [resolveOk, 'typed'];
@@ -117,6 +146,19 @@ describe('BasePage native input routing', () => {
         expect(page.scripts).toHaveLength(3);
         expect(page.scripts[2]).toContain("return 'typed'");
     });
+    it('uses CDP DOM scrollIntoViewIfNeeded before JS click when available', async () => {
+        const page = new ActionPage();
+        page.cdp = vi.fn()
+            .mockResolvedValueOnce({})
+            .mockResolvedValueOnce({ root: { nodeId: 1 } })
+            .mockResolvedValueOnce({ nodeId: 9 })
+            .mockResolvedValueOnce({});
+        page.results = [resolveOk, { status: 'clicked', x: 1, y: 2 }];
+        page.withArgsResults = [{ ok: true }, undefined];
+        await page.click('#save');
+        expect(page.cdp).toHaveBeenCalledWith('DOM.scrollIntoViewIfNeeded', { nodeId: 9 });
+        expect(page.scripts.at(-1)).toContain('if (false) el.scrollIntoView');
+    });
     it('presses key chords through native CDP key events when available', async () => {
         const page = new ActionPage();
         page.nativeKeyPress = vi.fn().mockResolvedValue(undefined);

package/dist/src/browser/cdp.js

@@ -320,6 +320,12 @@ class CDPPage extends BasePage {
     async cdp(method, params = {}) {
         return this.bridge.send(method, params);
     }
+    async handleJavaScriptDialog(accept, promptText) {
+        await this.cdp('Page.handleJavaScriptDialog', {
+            accept,
+            ...(promptText !== undefined && { promptText }),
+        });
+    }
     async nativeClick(x, y) {
         await this.cdp('Input.dispatchMouseEvent', {
             type: 'mousePressed',

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

@@ -58,10 +58,12 @@ describe('CDPBridge cookies', () => {
         expect(page.nativeType).toBeTypeOf('function');
         expect(page.nativeKeyPress).toBeTypeOf('function');
         expect(page.nativeClick).toBeTypeOf('function');
+        expect(page.handleJavaScriptDialog).toBeTypeOf('function');
         expect(page.cdp).toBeTypeOf('function');
         await page.nativeType('hello');
         await page.nativeKeyPress('a', ['Ctrl']);
         await page.nativeClick(10, 20);
+        await page.handleJavaScriptDialog(true, 'ok');
         await page.cdp('Page.getLayoutMetrics', {});
         expect(send.mock.calls).toEqual([
             ['Input.insertText', { text: 'hello' }],
@@ -69,6 +71,7 @@ describe('CDPBridge cookies', () => {
             ['Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', modifiers: 2 }],
             ['Input.dispatchMouseEvent', { type: 'mousePressed', x: 10, y: 20, button: 'left', clickCount: 1 }],
             ['Input.dispatchMouseEvent', { type: 'mouseReleased', x: 10, y: 20, button: 'left', clickCount: 1 }],
+            ['Page.handleJavaScriptDialog', { accept: true, promptText: 'ok' }],
             ['Page.getLayoutMetrics', {}],
         ]);
     });

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

@@ -68,6 +68,7 @@ export declare class Page extends BasePage {
     }>>;
     evaluateInFrame(js: string, frameIndex: number): Promise<unknown>;
     cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    handleJavaScriptDialog(accept: boolean, promptText?: string): Promise<void>;
     /** CDP native click fallback — called when JS el.click() fails */
     protected tryNativeClick(x: number, y: number): Promise<boolean>;
     /** Precise click using DOM.getContentQuads/getBoxModel for inline elements */

package/dist/src/browser/page.js

@@ -283,6 +283,12 @@ export class Page extends BasePage {
             ...this._cmdOpts(),
         });
     }
+    async handleJavaScriptDialog(accept, promptText) {
+        await this.cdp('Page.handleJavaScriptDialog', {
+            accept,
+            ...(promptText !== undefined && { promptText }),
+        });
+    }
     /** CDP native click fallback — called when JS el.click() fails */
     async tryNativeClick(x, y) {
         try {

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

@@ -102,6 +102,23 @@ describe('Page network capture compatibility', () => {
         expect(warnMock).toHaveBeenCalledTimes(1);
     });
 });
+describe('Page CDP helpers', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('handles JavaScript dialogs through the CDP passthrough', async () => {
+        sendCommandMock.mockResolvedValueOnce({});
+        const page = new Page('browser:default');
+        await page.handleJavaScriptDialog(true, 'confirm');
+        expect(sendCommandMock).toHaveBeenCalledWith('cdp', expect.objectContaining({
+            workspace: 'browser:default',
+            cdpMethod: 'Page.handleJavaScriptDialog',
+            cdpParams: { accept: true, promptText: 'confirm' },
+        }));
+    });
+});
 describe('Page active target tracking', () => {
     beforeEach(() => {
         sendCommandMock.mockReset();

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

@@ -72,7 +72,9 @@ export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): str
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function clickResolvedJs(): string;
+export declare function clickResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS for type that uses the unified resolver.
  */
@@ -84,12 +86,17 @@ export declare function typeResolvedJs(text: string): string;
  * focus the editable target, select its current contents, then let CDP insert
  * real browser text input so rich editors can update their internal state.
  */
-export declare function prepareNativeTypeResolvedJs(): string;
+export declare function prepareNativeTypeResolvedJs(opts?: {
+    skipScroll?: boolean;
+    skipFocus?: boolean;
+}): string;
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function scrollResolvedJs(): string;
+export declare function scrollResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS to get text content of resolved element.
  */

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

@@ -277,12 +277,13 @@ export function resolveTargetJs(ref, opts = {}) {
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export function clickResolvedJs() {
+export function clickResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
     return `
     (() => {
       const el = window.__resolved;
       if (!el) throw new Error('No resolved element');
-      el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      if (${shouldScroll}) 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);
@@ -338,7 +339,9 @@ export function typeResolvedJs(text) {
  * focus the editable target, select its current contents, then let CDP insert
  * real browser text input so rich editors can update their internal state.
  */
-export function prepareNativeTypeResolvedJs() {
+export function prepareNativeTypeResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    const shouldFocus = opts.skipFocus ? 'false' : 'true';
     return `
     (() => {
       const original = window.__resolved;
@@ -369,11 +372,13 @@ export function prepareNativeTypeResolvedJs() {
       }
 
       window.__resolved = el;
-      el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
-      try {
-        el.focus({ preventScroll: true });
-      } catch (_) {
-        el.focus();
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
+      if (${shouldFocus}) {
+        try {
+          el.focus({ preventScroll: true });
+        } catch (_) {
+          el.focus();
+        }
       }
 
       if (editableHost) {
@@ -410,12 +415,13 @@ export function prepareNativeTypeResolvedJs() {
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export function scrollResolvedJs() {
+export function scrollResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
     return `
     (() => {
       const el = window.__resolved;
       if (!el) throw new Error('No resolved element');
-      el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
       return { scrolled: true, tag: el.tagName.toLowerCase(), text: (el.textContent || '').trim().slice(0, 80) };
     })()
   `;

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

@@ -31,11 +31,15 @@ export type Fixture = {
     expect?: FixtureExpect;
 };
 export type ValidationFailure = {
-    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy';
+    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;
@@ -51,6 +55,7 @@ export declare function writeFixture(site: string, command: string, fixture: Fix
  */
 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.

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

@@ -30,6 +30,26 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+const DEFAULT_MAX_TOP_LEVEL_KEYS = 12;
+const DEFAULT_MAX_NESTED_DEPTH = 1;
+const ID_SHAPED_KEY_PATTERNS = [
+    /^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(site, command) {
     return path.join(os.homedir(), '.opencli', 'sites', site, 'verify', `${command}.json`);
 }
@@ -180,6 +200,39 @@ export function validateRows(rows, fixture) {
     });
     return failures;
 }
+export function validateRowShape(rows, opts = {}) {
+    const failures = [];
+    const maxTopLevelKeys = opts.maxTopLevelKeys ?? DEFAULT_MAX_TOP_LEVEL_KEYS;
+    const maxNestedDepth = opts.maxNestedDepth ?? DEFAULT_MAX_NESTED_DEPTH;
+    rows.forEach((row, i) => {
+        const keys = Object.keys(row);
+        if (keys.length > maxTopLevelKeys) {
+            failures.push({
+                rule: 'shapeKeyCount',
+                detail: `row has ${keys.length} top-level keys, expected at most ${maxTopLevelKeys}`,
+                rowIndex: i,
+            });
+        }
+        for (const [key, value] of Object.entries(row)) {
+            const depth = nestedDepth(value);
+            if (depth > maxNestedDepth) {
+                failures.push({
+                    rule: 'shapeDepth',
+                    detail: `"${key}" nesting depth is ${depth}, expected at most ${maxNestedDepth}`,
+                    rowIndex: i,
+                });
+            }
+            for (const path of nestedIdPaths(value, key)) {
+                failures.push({
+                    rule: 'shapeNestedId',
+                    detail: `id-shaped field "${path}" must be a top-level row key`,
+                    rowIndex: i,
+                });
+            }
+        }
+    });
+    return failures;
+}
 /**
  * Convert fixture args into argv tokens appended after the command name.
  * - Array form is passed through verbatim (stringified), supporting positional subjects.
@@ -221,6 +274,40 @@ function jsType(v) {
         return 'array';
     return typeof v;
 }
+function nestedDepth(value) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return 0;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 1;
+        return 1 + Math.max(...value.map(nestedDepth));
+    }
+    const values = Object.values(value);
+    if (values.length === 0)
+        return 1;
+    return 1 + Math.max(...values.map(nestedDepth));
+}
+function nestedIdPaths(value, prefix) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return [];
+    const paths = [];
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            paths.push(...nestedIdPaths(item, `${prefix}[${index}]`));
+        });
+        return paths;
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        const childPath = `${prefix}.${key}`;
+        if (isIdShapedKey(key))
+            paths.push(childPath);
+        paths.push(...nestedIdPaths(nested, childPath));
+    }
+    return paths;
+}
+function isIdShapedKey(key) {
+    return ID_SHAPED_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
 function typeMatches(actual, declared) {
     const allowed = declared.split('|').map((s) => s.trim()).filter(Boolean);
     if (allowed.length === 0)

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { deriveFixture, expandFixtureArgs, parseSeedArgs, validateRows } from './verify-fixture.js';
+import { deriveFixture, expandFixtureArgs, parseSeedArgs, validateRows, validateRowShape } from './verify-fixture.js';
 describe('validateRows', () => {
     it('passes when rows meet all expectations', () => {
         const fixture = {
@@ -98,6 +98,49 @@ describe('validateRows', () => {
         expect(failures.map((f) => f.rowIndex)).toEqual([1, 2, 3, 4]);
     });
 });
+describe('validateRowShape', () => {
+    it('passes flat rows with a compact key set', () => {
+        const failures = validateRowShape([
+            { id: '1', title: 'A', author: { name: 'Ada' }, tags: ['ai', 'web'] },
+        ]);
+        expect(failures).toEqual([]);
+    });
+    it('reports rows with too many top-level keys', () => {
+        const row = Object.fromEntries(Array.from({ length: 13 }, (_, i) => [`k${i}`, i]));
+        const failures = validateRowShape([row]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeKeyCount',
+                detail: 'row has 13 top-level keys, expected at most 12',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nesting deeper than one level', () => {
+        const failures = validateRowShape([
+            { title: 'A', stats: { author: { name: 'Ada' } } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeDepth',
+                detail: '"stats" nesting depth is 2, expected at most 1',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nested id-shaped fields even when one-level nesting is otherwise allowed', () => {
+        const failures = validateRowShape([
+            { title: 'A', author: { user_id: 'u1', name: 'Ada' } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeNestedId',
+                detail: 'id-shaped field "author.user_id" must be a top-level row key',
+                rowIndex: 0,
+            },
+        ]);
+    });
+});
 describe('deriveFixture', () => {
     it('returns rowCount.min=0 when rows are empty', () => {
         expect(deriveFixture([])).toEqual({ expect: { rowCount: { min: 0 } } });

package/dist/src/build-manifest.js

@@ -75,6 +75,7 @@ function isCliCommandValue(value, site) {
         && typeof value.site === 'string'
         && value.site === site
         && typeof value.name === 'string'
+        && (value.access === 'read' || value.access === 'write')
         && Array.isArray(value.args);
 }
 function toManifestEntry(cmd, modulePath, sourceFile) {
@@ -83,6 +84,8 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         name: cmd.name,
         aliases: cmd.aliases,
         description: cmd.description ?? '',
+        access: cmd.access,
+        example: cmd.example,
         domain: cmd.domain,
         strategy: (cmd.strategy ?? 'public').toString().toLowerCase(),
         browser: cmd.browser ?? true,