@jackwener/opencli 1.7.12 → 1.7.14

package/dist/src/execution.js

@@ -4,13 +4,14 @@
  * This is the single entry point for executing any CLI command. It handles:
  * 1. Argument validation and coercion
  * 2. Browser session lifecycle (if needed)
- * 3. Domain pre-navigation for cookie/header strategies
+ * 3. Domain pre-navigation for cookie strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { getRegistry, fullName, } from './registry.js';
 import { pathToFileURL } from 'node:url';
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
@@ -28,6 +29,7 @@ const _loadedModules = new Map();
 /** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
 const _moduleMtimes = new Map();
 const _userClisDir = `${os.homedir()}/.opencli/clis/`;
+const INTERACTIVE_BROWSER_IDLE_TIMEOUT_SECONDS = 600;
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
         return 'off';
@@ -138,14 +140,37 @@ function resolvePreNav(cmd) {
     // strategy → navigateBefore expansion already happened in normalizeCommand().
     return null;
 }
-function ensureRequiredEnv(cmd) {
-    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
-        const value = process.env[name];
-        return value === undefined || value === null || value === '';
-    });
-    if (!missing)
-        return;
-    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+function urlMatchesDomain(url, domain) {
+    if (!url || !domain)
+        return false;
+    try {
+        const hostname = new URL(url).hostname;
+        return hostname === domain || hostname.endsWith(`.${domain}`);
+    }
+    catch {
+        return false;
+    }
+}
+function isDomainRootPreNav(preNavUrl, domain) {
+    if (!domain)
+        return false;
+    try {
+        const parsed = new URL(preNavUrl);
+        const hostnameMatches = parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`);
+        const rootPath = parsed.pathname === '' || parsed.pathname === '/';
+        return hostnameMatches && rootPath && parsed.search === '' && parsed.hash === '';
+    }
+    catch {
+        return false;
+    }
+}
+async function shouldRunPreNav(cmd, page, reuse, preNavUrl) {
+    if (reuse !== 'site' || !cmd.domain)
+        return true;
+    if (!isDomainRootPreNav(preNavUrl, cmd.domain))
+        return true;
+    const currentUrl = await page.getCurrentUrl?.().catch(() => null);
+    return !urlMatchesDomain(currentUrl, cmd.domain);
 }
 export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
     let kwargs;
@@ -157,6 +182,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             throw err;
         throw new ArgumentError(getErrorMessage(err));
     }
+    const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
     const traceMode = normalizeTraceMode(opts.trace);
     const hookCtx = {
         command: fullName(cmd),
@@ -183,17 +209,19 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     cdpEndpoint = await resolveElectronEndpoint(cmd.site);
                 }
             }
-            ensureRequiredEnv(cmd);
             const BrowserFactory = getBrowserFactory(cmd.site);
             const contextId = resolveProfileContextId(opts.profile);
             const internal = cmd;
+            const browserReuse = resolveBrowserSessionReuse(cmd);
+            const workspace = resolveBrowserWorkspace(cmd, browserReuse);
+            const idleTimeout = browserReuse === 'site' ? INTERACTIVE_BROWSER_IDLE_TIMEOUT_SECONDS : undefined;
             result = await browserSession(BrowserFactory, async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
                         scope: {
                             contextId,
-                            workspace: `site:${cmd.site}`,
+                            workspace,
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
@@ -210,7 +238,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     await page.startNetworkCapture?.().catch(() => false);
                 }
                 const preNavUrl = resolvePreNav(cmd);
-                if (preNavUrl) {
+                if (preNavUrl && await shouldRunPreNav(cmd, page, browserReuse, preNavUrl)) {
                     observation?.record({
                         stream: 'action',
                         name: 'pre_navigate',
@@ -253,12 +281,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
-                // --live / OPENCLI_LIVE=1 keeps the automation window open after the
-                // command finishes, so agents (or humans) can inspect the page state.
-                const keepOpen = process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
+                // --live / OPENCLI_LIVE=1 keeps the current automation tab lease after
+                // the command finishes, so agents (or humans) can inspect the page state.
+                const keepOpen = browserReuse !== 'none' || process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
                 try {
+                    const browserTimeout = userTimeoutSec !== null
+                        ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
+                        : DEFAULT_BROWSER_COMMAND_TIMEOUT;
                     const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                        timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                        timeout: browserTimeout,
                         label: fullName(cmd),
                     });
                     observation?.record({
@@ -270,8 +301,9 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await collectObservationEvidence(observation, page).catch(() => { });
                         exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
                     }
-                    // Adapter commands are one-shot — close the automation window immediately
-                    // instead of waiting for the 30s idle timeout.
+                    // Adapter commands are one-shot — release the current tab lease immediately
+                    // instead of waiting for the 30s idle timeout. The automation container
+                    // window stays open for reuse.
                     if (!keepOpen)
                         await page.closeWindow?.().catch(() => { });
                     return result;
@@ -294,23 +326,26 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                             exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
                         }
                     }
-                    // Close the automation window on failure too — without this, the window
-                    // lingers until the extension's idle timer fires (unreliable on Windows
-                    // where MV3 service workers may be suspended before setTimeout triggers).
+                    // Release the tab lease on failure too — without this, the lease lingers
+                    // until the extension's idle timer fires (unreliable on Windows where
+                    // MV3 service workers may be suspended before setTimeout triggers).
                     if (!keepOpen)
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace: `site:${cmd.site}:${crypto.randomUUID()}`, cdpEndpoint, contextId });
+            }, { workspace, cdpEndpoint, contextId, idleTimeout });
         }
         else {
-            // Non-browser commands: apply timeout only when explicitly configured.
-            const timeout = cmd.timeoutSeconds;
-            if (timeout !== undefined && timeout > 0) {
+            // Non-browser commands: enforce a timeout only when the command exposes
+            // a `--timeout` arg (and the resolved value is positive). Without that
+            // arg there is no meaningful default — non-browser cmds are diverse
+            // enough that a hard cap would do more harm than good.
+            if (userTimeoutSec !== null) {
+                const ceiling = userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS;
                 result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
-                    timeout,
+                    timeout: ceiling,
                     label: fullName(cmd),
-                    hint: `Increase the adapter's timeoutSeconds setting (currently ${timeout}s)`,
+                    hint: `Pass a higher --timeout value (currently ${userTimeoutSec}s)`,
                 });
             }
             else {
@@ -401,3 +436,52 @@ export function prepareCommandArgs(cmd, rawKwargs) {
     cmd.validateArgs?.(kwargs);
     return kwargs;
 }
+/**
+ * Runtime ceiling padding (seconds) added on top of the user's `--timeout`.
+ * The adapter's polling loop typically uses the full user value; the padding
+ * gives us room for the adapter to return + closeWindow + trace export before
+ * the runtime kills the Promise.
+ */
+const RUNTIME_TIMEOUT_PADDING_SECONDS = 30;
+function readEnvBrowserSessionReuse() {
+    const raw = process.env.OPENCLI_BROWSER_REUSE;
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'none' || raw === 'site')
+        return raw;
+    throw new ArgumentError(`--reuse must be one of: none, site. Received: "${raw}"`);
+}
+function resolveBrowserSessionReuse(cmd) {
+    return readEnvBrowserSessionReuse() ?? cmd.browserSession?.reuse ?? 'none';
+}
+function resolveBrowserWorkspace(cmd, reuse) {
+    if (reuse === 'site')
+        return `site:${cmd.site}`;
+    return `site:${cmd.site}:${crypto.randomUUID()}`;
+}
+/**
+ * Resolve the user-controllable `--timeout` arg, in seconds.
+ *
+ * Convention: a command opts into runtime-enforced timeouts by declaring an
+ * arg named `timeout`. The arg's `default` flows through `prepareCommandArgs`
+ * into `kwargs.timeout`, so by the time runtime enforcement runs, the value
+ * is the merged user-supplied-or-default seconds.
+ *
+ * Returns the parsed positive integer (seconds), or null if the command does
+ * not expose a `timeout` arg. Declaring `timeout` opts into runtime timeout
+ * enforcement, so invalid values must fail upfront instead of silently
+ * disabling the runtime ceiling.
+ */
+function readUserTimeoutSeconds(cmd, kwargs) {
+    if (!cmd.args.some(a => a.name === 'timeout'))
+        return null;
+    const raw = kwargs.timeout;
+    if (raw === undefined || raw === null || raw === '') {
+        throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
+    }
+    return parsed;
+}

package/dist/src/execution.test.js

@@ -3,44 +3,353 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { executeCommand, prepareCommandArgs } from './execution.js';
-import { TimeoutError, toEnvelope } from './errors.js';
+import { ArgumentError, TimeoutError, toEnvelope } from './errors.js';
 import { cli, Strategy } from './registry.js';
-import { withTimeoutMs } from './runtime.js';
 import * as runtime from './runtime.js';
 import * as capRouting from './capabilityRouting.js';
 describe('executeCommand — non-browser timeout', () => {
-    it('applies timeoutSeconds to non-browser commands', async () => {
+    it('applies the user --timeout arg as the ceiling for non-browser commands', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
         const cmd = cli({
             site: 'test-execution',
             name: 'non-browser-timeout', access: 'read',
-            description: 'test non-browser timeout',
+            description: 'test non-browser --timeout enforcement',
             browser: false,
             strategy: Strategy.PUBLIC,
-            timeoutSeconds: 0.01,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        // Ceiling = user-supplied/default timeout + 30s padding (adapter return room).
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: 35,
+            label: 'test-execution/non-browser-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('fires a TimeoutError when the inner adapter exceeds the --timeout ceiling', async () => {
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-timeout-fires', access: 'read',
+            description: 'test that the ceiling actually cancels the adapter',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 1, help: 'Max seconds' },
+            ],
             func: () => new Promise(() => { }),
         });
-        // Sentinel timeout at 200ms — if the inner 10ms timeout fires first,
-        // the error will be a TimeoutError with the command label, not 'sentinel'.
-        const error = await withTimeoutMs(executeCommand(cmd, {}), 200, 'sentinel timeout')
-            .catch((err) => err);
+        // Spy on runWithTimeout to intercept and pass a tiny ceiling so the test
+        // doesn't have to wait the real (1+30)s. We still verify the TimeoutError
+        // surface — code, label, hint — that users see.
+        vi.spyOn(runtime, 'runWithTimeout').mockImplementation(async (promise, opts) => {
+            return runtime.withTimeoutMs(promise, 50, () => new TimeoutError(opts.label ?? 'op', opts.timeout, opts.hint));
+        });
+        const error = await executeCommand(cmd, {}).catch((err) => err);
         expect(error).toBeInstanceOf(TimeoutError);
         expect(error).toMatchObject({
             code: 'TIMEOUT',
-            message: 'test-execution/non-browser-timeout timed out after 0.01s',
+            hint: 'Pass a higher --timeout value (currently 1s)',
         });
+        vi.restoreAllMocks();
     });
-    it('skips timeout when timeoutSeconds is 0', async () => {
+    it('runs non-browser commands without a ceiling when no --timeout arg is declared', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
         const cmd = cli({
             site: 'test-execution',
-            name: 'non-browser-zero-timeout', access: 'read',
-            description: 'test zero timeout bypasses wrapping',
+            name: 'non-browser-no-timeout', access: 'read',
+            description: 'test that omitting --timeout means no ceiling',
             browser: false,
             strategy: Strategy.PUBLIC,
-            timeoutSeconds: 0,
-            func: () => new Promise(() => { }),
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid --timeout values instead of silently disabling the non-browser ceiling', async () => {
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'non-browser-invalid-timeout', access: 'read',
+            description: 'test invalid --timeout fails upfront',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: -1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: 1.5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('applies the user --timeout arg as the ceiling for browser commands (with +30s padding)', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-with-timeout', access: 'read',
+            description: 'test browser --timeout enforcement',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: 35,
+            label: 'test-execution/browser-with-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('falls back to DEFAULT_BROWSER_COMMAND_TIMEOUT for browser commands without a --timeout arg', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-no-timeout', access: 'read',
+            description: 'test browser fallback to global default',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(runWithTimeoutSpy).toHaveBeenCalledTimes(1);
+        expect(runWithTimeoutSpy.mock.calls[0]?.[1]).toMatchObject({
+            timeout: runtime.DEFAULT_BROWSER_COMMAND_TIMEOUT,
+            label: 'test-execution/browser-no-timeout',
+        });
+        vi.restoreAllMocks();
+    });
+    it('reuses a site-scoped browser workspace and keeps the tab lease open', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-site', access: 'read',
+            description: 'test site-scoped browser reuse',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
         });
-        // With timeout guard skipped, the sentinel fires instead.
-        await expect(withTimeoutMs(executeCommand(cmd, {}), 50, 'sentinel timeout')).rejects.toThrow('sentinel timeout');
+        await executeCommand(cmd, {});
+        await executeCommand(cmd, {});
+        expect(sessionOpts).toHaveLength(2);
+        expect(sessionOpts[0]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
+        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('keeps default browser commands on one-shot workspaces', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-default', access: 'read',
+            description: 'test default one-shot browser workspace',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        await executeCommand(cmd, {});
+        expect(sessionOpts).toHaveLength(2);
+        expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[1]?.workspace).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[0]?.workspace).not.toBe(sessionOpts[1]?.workspace);
+        expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+        expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
+        expect(closeWindow).toHaveBeenCalledTimes(2);
+        vi.restoreAllMocks();
+    });
+    it('lets user --reuse none override adapter reuse metadata', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const prev = process.env.OPENCLI_BROWSER_REUSE;
+        process.env.OPENCLI_BROWSER_REUSE = 'none';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-reuse-override-none', access: 'read',
+                description: 'test user reuse override',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                browserSession: { reuse: 'site' },
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+            expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+            expect(closeWindow).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OPENCLI_BROWSER_REUSE;
+            else
+                process.env.OPENCLI_BROWSER_REUSE = prev;
+            vi.restoreAllMocks();
+        }
+    });
+    it('skips repeated domain pre-navigation for site-reused browser sessions', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('https://grok.com/chat/abc'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-skip-prenav', access: 'read',
+            description: 'test reused same-domain tabs do not reset conversation state',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'grok.com',
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(goto).not.toHaveBeenCalled();
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('keeps explicit path pre-navigation for site-reused browser sessions', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('https://example.com/other'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-reuse-path-prenav', access: 'read',
+            description: 'test explicit path pre-navigation still runs',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'example.com',
+            navigateBefore: 'https://example.com/dashboard',
+            browserSession: { reuse: 'site' },
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {});
+        expect(goto).toHaveBeenCalledWith('https://example.com/dashboard');
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('respects navigateBefore=false so adapter range validation fails before browser navigation', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            goto,
+            getCurrentUrl: vi.fn().mockResolvedValue('about:blank'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-limit-no-prenav', access: 'read',
+            description: 'test adapter range validation can fail before pre-nav',
+            browser: true,
+            strategy: Strategy.COOKIE,
+            domain: 'www.facebook.com',
+            navigateBefore: false,
+            args: [
+                { name: 'limit', type: 'int', required: false, default: 15, help: 'Limit' },
+            ],
+            func: async (_page, args) => {
+                const limit = Number(args.limit);
+                if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+                    throw new ArgumentError('--limit must be a positive integer in [1, 100]');
+                }
+                return [{ ok: true }];
+            },
+        });
+        await expect(executeCommand(cmd, { limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(goto).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid --timeout values instead of falling back to the browser default', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const runWithTimeoutSpy = vi.spyOn(runtime, 'runWithTimeout');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-timeout', access: 'read',
+            description: 'test invalid browser --timeout fails upfront',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: -1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(executeCommand(cmd, { timeout: 1.5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(runWithTimeoutSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
+    it('rejects invalid browser --timeout before opening a session or pre-navigating', async () => {
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        const browserSessionSpy = vi.spyOn(runtime, 'browserSession');
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-invalid-timeout-prenav', access: 'read',
+            description: 'test invalid browser --timeout fails before session setup',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            navigateBefore: 'https://example.com/',
+            args: [
+                { name: 'timeout', type: 'int', required: false, default: 5, help: 'Max seconds' },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, { timeout: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(browserSessionSpy).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
     });
     it('calls closeWindow on browser command failure', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);

package/dist/src/help.d.ts

@@ -7,9 +7,34 @@ export declare function wrapCommaList(items: readonly string[], opts?: {
     width?: number;
     indent?: string;
 }): string;
-export declare function formatRootAdapterHelpText(siteNames: readonly string[]): string;
-export declare function rootHelpData(program: Command, siteNames: readonly string[]): Record<string, unknown>;
+/**
+ * Adapter category for help-text grouping.
+ *
+ * - `site`: web site adapter (real DNS-style domain, e.g. `www.bilibili.com`)
+ * - `app`: desktop app adapter (Electron/osascript, signaled by `domain: 'localhost'`
+ *   or other non-DNS string like `'doubao-app'`)
+ *
+ * Classification is derived from the adapter's `domain` field — no new schema
+ * required. Adapters without a `domain` field default to `site` (most are
+ * public web scrapers).
+ */
+export type AdapterKind = 'site' | 'app';
+export declare function classifyAdapter(domain: string | undefined): AdapterKind;
+export interface RootAdapterGroups {
+    /** Externally-registered CLIs (docker, gh, vercel, ...) — passthrough binaries */
+    external: readonly string[];
+    /** Desktop-app adapters (chatgpt-app, chatwise, codex, ...) */
+    apps: readonly string[];
+    /** Web-site adapters (bilibili, dianping, ...) */
+    sites: readonly string[];
+}
+export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+export declare function formatCommandListTerm(cmd: CliCommand): string;
+export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
 export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
 export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
+export declare function formatCommonOptionsHelpText(): string;
+export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
+export declare function formatCommandHelpText(cmd: CliCommand): string;
 export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
 export declare function formatSiteCommandDescription(cmd: CliCommand): string;