@jackwener/opencli 1.7.17 → 1.7.19

package/clis/zhihu/recommend.test.js

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CliError } from '@jackwener/opencli/errors';
+import './recommend.js';
+
+describe('zhihu recommend', () => {
+    it('returns recommendations from the Zhihu feed API', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        expect(cmd?.func).toBeTypeOf('function');
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            expect(js).toContain('/api/v3/feed/topstory/recommend?limit=10&desktop=true');
+            expect(js).toContain("credentials: 'include'");
+            return {
+                data: [
+                    {
+                        id: '0_1',
+                        target: {
+                            id: '101',
+                            type: 'answer',
+                            author: { name: 'alice' },
+                            voteup_count: 12,
+                            question: { id: '202', title: 'Question title' },
+                        },
+                    },
+                    {
+                        id: '1_1',
+                        target: {
+                            id: '303',
+                            type: 'article',
+                            title: 'Article title',
+                            author: { name: 'bob' },
+                            reaction: { statistics: { like_count: 7 } },
+                        },
+                    },
+                ],
+                paging: { is_end: true },
+            };
+        });
+        const page = { goto, evaluate };
+        await expect(cmd.func(page, { limit: 2 })).resolves.toEqual([
+            {
+                rank: 1,
+                type: 'answer',
+                title: 'Question title',
+                author: 'alice',
+                votes: 12,
+                url: 'https://www.zhihu.com/question/202/answer/101',
+            },
+            {
+                rank: 2,
+                type: 'article',
+                title: 'Article title',
+                author: 'bob',
+                votes: 7,
+                url: 'https://zhuanlan.zhihu.com/p/303',
+            },
+        ]);
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com');
+        expect(evaluate).toHaveBeenCalledTimes(1);
+    });
+
+    it('follows paging.next until the requested limit is reached', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn()
+                .mockResolvedValueOnce({
+                    data: [
+                        { id: '0_1', target: { id: 'a1', type: 'answer', author: { name: 'alice' }, question: { id: 'q1', title: 'first' } } },
+                        { id: '1_1', target: { id: 'a2', type: 'answer', author: { name: 'bob' }, question: { id: 'q2', title: 'second' } } },
+                    ],
+                    paging: {
+                        is_end: false,
+                        next: 'https://www.zhihu.com/api/v3/feed/topstory/recommend?action=down&after_id=1&page_number=2',
+                    },
+                })
+                .mockResolvedValueOnce({
+                    data: [
+                        { id: '1_1', target: { id: 'a2', type: 'answer', author: { name: 'bob duplicate' }, question: { id: 'q2', title: 'duplicate' } } },
+                        { id: '2_1', target: { id: 'q3', type: 'question', title: 'third' } },
+                    ],
+                    paging: { is_end: true },
+                }),
+        };
+        await expect(cmd.func(page, { limit: 3 })).resolves.toEqual([
+            { rank: 1, type: 'answer', title: 'first', author: 'alice', votes: 0, url: 'https://www.zhihu.com/question/q1/answer/a1' },
+            { rank: 2, type: 'answer', title: 'second', author: 'bob', votes: 0, url: 'https://www.zhihu.com/question/q2/answer/a2' },
+            { rank: 3, type: 'question', title: 'third', author: '', votes: 0, url: 'https://www.zhihu.com/question/q3' },
+        ]);
+        expect(page.evaluate).toHaveBeenCalledTimes(2);
+        expect(page.evaluate.mock.calls[1][0]).toContain('after_id=1');
+    });
+
+    it('maps auth-like failures to AuthRequiredError', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 403 }),
+        };
+        await expect(cmd.func(page, { limit: 3 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('preserves non-auth fetch failures as CliError', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 500 }),
+        };
+        await expect(cmd.func(page, { limit: 3 })).rejects.toMatchObject({
+            code: 'FETCH_ERROR',
+            message: 'Zhihu recommendations request failed (HTTP 500)',
+        });
+    });
+
+    it('handles null evaluate response as fetch error', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue(null),
+        };
+        await expect(cmd.func(page, { limit: 3 })).rejects.toMatchObject({
+            code: 'FETCH_ERROR',
+            message: 'Zhihu recommendations request failed',
+        });
+    });
+
+    it('rejects invalid limits before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { limit: 0 })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('rejects excessive limits before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/recommend');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { limit: 1001 })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+});

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

@@ -8,7 +8,7 @@
  * Subclasses implement the transport-specific methods: goto, evaluate,
  * getCookies, screenshot, tabs, etc.
  */
-import type { BrowserCookie, FetchJsonOptions, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+import type { BrowserCookie, BrowserEvaluateFunction, FetchJsonOptions, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
 import { type ResolveOptions, type TargetMatchLevel } from './target-resolver.js';
 export interface ResolveSuccess {
     matches_n: number;
@@ -60,7 +60,8 @@ export declare abstract class BasePage implements IPage {
         settleMs?: number;
         allowBoundNavigation?: boolean;
     }): Promise<void>;
-    abstract evaluate(js: string): Promise<unknown>;
+    abstract evaluate<T = unknown>(js: string): Promise<T>;
+    abstract evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
     /**
      * Safely evaluate JS with pre-serialized arguments.
      * Each key in `args` becomes a `const` declaration with JSON-serialized value,

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

@@ -29,8 +29,8 @@ class ActionPage extends BasePage {
     setFileInput;
     cdp;
     async goto() { }
-    async evaluate(js) {
-        this.scripts.push(js);
+    async evaluate(input) {
+        this.scripts.push(typeof input === 'string' ? input : input.toString());
         return this.results.shift() ?? null;
     }
     async evaluateWithArgs(js, args) {

package/dist/src/browser/cdp.js

@@ -10,7 +10,7 @@
 import { WebSocket } from 'ws';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
-import { wrapForEval } from './utils.js';
+import { buildEvaluateExpression } from './utils.js';
 import { generateStealthJs } from './stealth.js';
 import { waitForDomStableJs } from './dom-helpers.js';
 import { isRecord, saveBase64ToFile } from '../utils.js';
@@ -181,8 +181,8 @@ class CDPPage extends BasePage {
             await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
         }
     }
-    async evaluate(js) {
-        const expression = wrapForEval(js);
+    async evaluate(input, ...args) {
+        const expression = buildEvaluateExpression(input, args);
         const result = await this.bridge.send('Runtime.evaluate', {
             expression,
             returnByValue: true,

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

@@ -8,7 +8,7 @@
  * by the navigate action and pass it to all subsequent commands. This ensures
  * page-scoped operations target the correct page without guessing.
  */
-import type { BrowserCookie, BrowserDownloadWaitResult, ScreenshotOptions } from '../types.js';
+import type { BrowserCookie, BrowserDownloadWaitResult, BrowserEvaluateFunction, ScreenshotOptions } from '../types.js';
 import { BasePage } from './base-page.js';
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
@@ -38,7 +38,8 @@ export declare class Page extends BasePage {
     /** Bind this Page instance to a specific page identity (targetId). */
     setActivePage(page?: string): void;
     private _markUnsupportedNetworkCapture;
-    evaluate(js: string): Promise<unknown>;
+    evaluate<T = unknown>(js: string): Promise<T>;
+    evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
     getCookies(opts?: {
         domain?: string;
         url?: string;

package/dist/src/browser/page.js

@@ -9,7 +9,7 @@
  * page-scoped operations target the correct page without guessing.
  */
 import { sendCommand, sendCommandFull } from './daemon-client.js';
-import { wrapForEval } from './utils.js';
+import { buildEvaluateExpression } from './utils.js';
 import { saveBase64ToFile } from '../utils.js';
 import { generateStealthJs } from './stealth.js';
 import { waitForDomStableJs } from './dom-helpers.js';
@@ -137,8 +137,8 @@ export class Page extends BasePage {
         log.warn('Browser Bridge extension does not support network capture; continuing without it. ' +
             'Explore output may miss API endpoints until you reload or reinstall the extension.');
     }
-    async evaluate(js) {
-        const code = wrapForEval(js);
+    async evaluate(input, ...args) {
+        const code = buildEvaluateExpression(input, args);
         try {
             return await sendCommand('exec', { code, ...this._cmdOpts() });
         }
@@ -294,7 +294,7 @@ export class Page extends BasePage {
         return Array.isArray(result) ? result : [];
     }
     async evaluateInFrame(js, frameIndex) {
-        const code = wrapForEval(js);
+        const code = buildEvaluateExpression(js);
         return sendCommand('exec', { code, frameIndex, ...this._cmdOpts() });
     }
     async cdp(method, params = {}) {

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

@@ -74,6 +74,37 @@ describe('Page.evaluate', () => {
         expect(value).toBe(42);
         expect(sendCommandMock).toHaveBeenCalledTimes(2);
     });
+    it('serializes function-form evaluate calls with JSON args', async () => {
+        sendCommandMock.mockResolvedValueOnce('/opencli');
+        const page = new Page('twitter', undefined, undefined, undefined, 'adapter');
+        const href = await page.evaluate((selector) => {
+            const link = document.querySelector(selector);
+            return link ? link.getAttribute('href') : null;
+        }, 'a[data-testid="AppTabBar_Profile_Link"]');
+        expect(href).toBe('/opencli');
+        expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
+            session: 'twitter',
+            surface: 'adapter',
+            code: expect.stringContaining('(...["a[data-testid=\\"AppTabBar_Profile_Link\\"]"])'),
+        }));
+        const code = sendCommandMock.mock.calls[0]?.[1]?.code;
+        expect(code).toContain('document.querySelector(selector)');
+    });
+    it('rejects non-JSON-serializable evaluate args before sending to the daemon', async () => {
+        const page = new Page('default');
+        const circular = {};
+        circular.self = circular;
+        await expect(page.evaluate((value) => value, circular)).rejects.toThrow('JSON-serializable');
+        expect(sendCommandMock).not.toHaveBeenCalled();
+    });
+    it('keeps string evaluate behavior unchanged', async () => {
+        sendCommandMock.mockResolvedValueOnce(42);
+        const page = new Page('default');
+        await expect(page.evaluate('21 + 21')).resolves.toBe(42);
+        expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
+            code: '21 + 21',
+        }));
+    });
 });
 describe('Page network capture compatibility', () => {
     beforeEach(() => {

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

@@ -1,6 +1,14 @@
 /**
  * Utility functions for browser operations
  */
+type EvaluateFunction = (...args: any[]) => 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
@@ -8,3 +16,5 @@
  * - `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

@@ -1,6 +1,34 @@
 /**
  * Utility functions for browser operations
  */
+function describeJsonError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * 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 function serializeFunctionForEval(fn, args = []) {
+    const source = fn.toString().trim();
+    const isFunctionSource = /^(async\s+)?function[\s(]/.test(source)
+        || /^(async\s*)?(\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/.test(source);
+    if (!isFunctionSource || source.includes('[native code]')) {
+        throw new Error('page.evaluate(fn) requires a serializable arrow/function expression');
+    }
+    let serializedArgs;
+    try {
+        serializedArgs = JSON.stringify(args);
+    }
+    catch (err) {
+        throw new Error(`page.evaluate arguments must be JSON-serializable: ${describeJsonError(err)}`);
+    }
+    if (serializedArgs === undefined) {
+        throw new Error('page.evaluate arguments must be JSON-serializable');
+    }
+    return `(${source})(...${serializedArgs})`;
+}
 /**
  * Wrap JS code for CDP Runtime.evaluate:
  * - Already an IIFE `(...)()` → send as-is
@@ -25,3 +53,12 @@ export function wrapForEval(js) {
     // Everything else: bare expression, `new Promise(...)`, etc. → evaluate directly
     return code;
 }
+export function buildEvaluateExpression(input, args = []) {
+    if (typeof input === 'function') {
+        return serializeFunctionForEval(input, args);
+    }
+    if (args.length > 0) {
+        throw new Error('page.evaluate string input does not accept args; use page.evaluate(fn, ...args) instead');
+    }
+    return wrapForEval(input);
+}

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

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

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

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { buildEvaluateExpression, wrapForEval } from './utils.js';
+describe('browser eval utils', () => {
+    it('keeps existing string eval wrapping behavior', () => {
+        expect(wrapForEval('21 + 21')).toBe('21 + 21');
+        expect(wrapForEval('() => 42')).toBe('(() => 42)()');
+    });
+    it('serializes function eval arguments as JSON', () => {
+        const code = buildEvaluateExpression((selector) => {
+            return document.querySelector(selector)?.textContent ?? null;
+        }, ['.title']);
+        expect(code).toContain('document.querySelector(selector)');
+        expect(code).toContain('(...[".title"])');
+    });
+    it('accepts compact async arrow functions', () => {
+        const fn = new Function('return async()=>42')();
+        expect(buildEvaluateExpression(fn)).toBe('(async()=>42)(...[])');
+    });
+    it('rejects string eval with stray args', () => {
+        expect(() => buildEvaluateExpression('document.title', ['ignored']))
+            .toThrow('use page.evaluate(fn, ...args)');
+    });
+    it('rejects non-JSON-serializable function args', () => {
+        const circular = {};
+        circular.self = circular;
+        expect(() => buildEvaluateExpression((value) => value, [circular]))
+            .toThrow('JSON-serializable');
+    });
+});

package/dist/src/cli-argv-preprocess.d.ts

@@ -0,0 +1,37 @@
+/**
+ * argv preprocessing: rewrite `opencli browser <session> <subcommand> ...`
+ * into `opencli browser --session <session> <subcommand> ...` so commander
+ * (which can't combine a parent positional with subcommand dispatch) can parse it.
+ *
+ * The user-facing form is positional; the internal form uses --session. Help text
+ * for the `browser` command is overridden to advertise the positional form.
+ */
+/**
+ * Returns the set of reserved subcommand names (exposed for tests so they stay
+ * synced with the actual registrations in cli.ts).
+ */
+export declare function getBrowserSubcommandNames(): ReadonlySet<string>;
+/**
+ * Rewrite `argv` to convert the positional `<session>` after `browser`
+ * into the internal `--session <name>` flag form.
+ *
+ * Only acts when `browser` is the root command (i.e. the first non-flag token
+ * after any leading root options), so it can't mis-interpret occurrences of
+ * the literal word `browser` deeper in the argv (e.g. `opencli adapter init
+ * browser/x`, or a URL value containing `browser`).
+ *
+ * Leaves argv unchanged when:
+ *   - root command is not `browser`
+ *   - the token after `browser` is a flag (e.g. `--help`)
+ *   - the token after `browser` is a known subcommand name (session was
+ *     omitted; commander will surface its own required-flag error)
+ */
+export declare function rewriteBrowserArgv(argv: readonly string[]): string[];
+/**
+ * Thrown by the preprocessor when user argv uses a retired/old form that we
+ * intentionally refuse to accept. main.ts catches this and exits with a
+ * usage error so it does not bubble up as an internal stacktrace.
+ */
+export declare class BrowserSessionArgvError extends Error {
+    constructor(message: string);
+}

package/dist/src/cli-argv-preprocess.js

@@ -0,0 +1,131 @@
+/**
+ * argv preprocessing: rewrite `opencli browser <session> <subcommand> ...`
+ * into `opencli browser --session <session> <subcommand> ...` so commander
+ * (which can't combine a parent positional with subcommand dispatch) can parse it.
+ *
+ * The user-facing form is positional; the internal form uses --session. Help text
+ * for the `browser` command is overridden to advertise the positional form.
+ */
+/**
+ * Browser subcommand names. If `<session>` would collide with one of these,
+ * we treat it as a missing-positional error and leave argv alone so commander
+ * reports a usable diagnostic.
+ *
+ * Keep in sync with the subcommands declared on the `browser` command in cli.ts.
+ */
+const BROWSER_SUBCOMMAND_NAMES = new Set([
+    'analyze',
+    'back',
+    'bind',
+    'check',
+    'click',
+    'close',
+    'console',
+    'dblclick',
+    'dialog',
+    'drag',
+    'eval',
+    'extract',
+    'fill',
+    'find',
+    'focus',
+    'frames',
+    'get',
+    'help',
+    'hover',
+    'init',
+    'keys',
+    'network',
+    'open',
+    'screenshot',
+    'scroll',
+    'select',
+    'state',
+    'tab',
+    'type',
+    'unbind',
+    'uncheck',
+    'upload',
+    'verify',
+    'wait',
+]);
+/**
+ * Root program options that consume the following token as their value. Used by
+ * the preprocessor to identify which token is the root command name (so e.g.
+ * `opencli --profile work browser foo state` is recognised as the `browser`
+ * command with `<session>=foo`, not the value of --profile).
+ *
+ * Keep in sync with `program.option(...)` calls in cli.ts.
+ */
+const ROOT_VALUE_FLAGS = new Set(['--profile']);
+/**
+ * Returns the set of reserved subcommand names (exposed for tests so they stay
+ * synced with the actual registrations in cli.ts).
+ */
+export function getBrowserSubcommandNames() {
+    return BROWSER_SUBCOMMAND_NAMES;
+}
+/**
+ * Rewrite `argv` to convert the positional `<session>` after `browser`
+ * into the internal `--session <name>` flag form.
+ *
+ * Only acts when `browser` is the root command (i.e. the first non-flag token
+ * after any leading root options), so it can't mis-interpret occurrences of
+ * the literal word `browser` deeper in the argv (e.g. `opencli adapter init
+ * browser/x`, or a URL value containing `browser`).
+ *
+ * Leaves argv unchanged when:
+ *   - root command is not `browser`
+ *   - the token after `browser` is a flag (e.g. `--help`)
+ *   - the token after `browser` is a known subcommand name (session was
+ *     omitted; commander will surface its own required-flag error)
+ */
+export function rewriteBrowserArgv(argv) {
+    const result = [...argv];
+    // Walk past leading root flags + their values to find the root command token.
+    let i = 0;
+    while (i < result.length) {
+        const tok = result[i];
+        if (!tok.startsWith('-'))
+            break;
+        // `--flag=value` consumes one slot regardless of whether the flag expects a value.
+        if (tok.includes('=')) {
+            i += 1;
+            continue;
+        }
+        if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
+            i += 2;
+        }
+        else {
+            i += 1;
+        }
+    }
+    if (result[i] !== 'browser')
+        return result;
+    const sessionIdx = i + 1;
+    const next = result[sessionIdx];
+    if (next === undefined)
+        return result;
+    // The retired `--session` flag must not be a working public entrance.
+    if (next === '--session' || next === '--session=' || next.startsWith('--session=')) {
+        throw new BrowserSessionArgvError('The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>');
+    }
+    if (next.startsWith('-'))
+        return result;
+    if (BROWSER_SUBCOMMAND_NAMES.has(next))
+        return result;
+    // Splice in --session <name> in place of the positional.
+    result.splice(sessionIdx, 1, '--session', next);
+    return result;
+}
+/**
+ * Thrown by the preprocessor when user argv uses a retired/old form that we
+ * intentionally refuse to accept. main.ts catches this and exits with a
+ * usage error so it does not bubble up as an internal stacktrace.
+ */
+export class BrowserSessionArgvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BrowserSessionArgvError';
+    }
+}

package/dist/src/cli-argv-preprocess.test.d.ts

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