@jackwener/opencli 1.7.12 → 1.7.13

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,8 +7,29 @@ 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 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 installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;

package/dist/src/help.js

@@ -50,18 +50,32 @@ export function wrapCommaList(items, opts = {}) {
         lines.push(line);
     return lines.join('\n');
 }
-export function formatRootAdapterHelpText(siteNames) {
-    if (siteNames.length === 0)
-        return '';
+export function classifyAdapter(domain) {
+    if (!domain)
+        return 'site';
+    return domain.includes('.') ? 'site' : 'app';
+}
+function formatGroupSection(label, names) {
+    if (names.length === 0)
+        return [];
     return [
+        `${label} (${names.length}):`,
+        wrapCommaList(names),
         '',
-        `Site adapters (${siteNames.length}):`,
-        wrapCommaList(siteNames),
-        '',
-        "Run 'opencli list' for full command details, or 'opencli <site> --help' to inspect one site.",
-        "Agent tip: use 'opencli <site> --help -f yaml' for structured commands, args, access, and examples.",
-        '',
-    ].join('\n');
+    ];
+}
+export function formatRootAdapterHelpText(groups) {
+    const total = groups.external.length + groups.apps.length + groups.sites.length;
+    if (total === 0)
+        return '';
+    const lines = [''];
+    lines.push(...formatGroupSection('External CLIs', groups.external));
+    lines.push(...formatGroupSection('App adapters', groups.apps));
+    lines.push(...formatGroupSection('Site adapters', groups.sites));
+    lines.push("Run 'opencli list' for full command details, or 'opencli <site> --help' to inspect one site.");
+    lines.push("Agent tip: use 'opencli <site> --help -f yaml' for structured commands, args, access, and examples.");
+    lines.push('');
+    return lines.join('\n');
 }
 function compactArg(arg) {
     return {
@@ -84,26 +98,35 @@ function compactCommand(cmd, opts = {}) {
         ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
         args: cmd.args.map(compactArg),
         example: formatCommandExample(cmd),
+        ...(cmd.browserSession ? { browserSession: cmd.browserSession } : {}),
+        ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
         ...(opts.includeColumns && cmd.columns?.length ? { columns: cmd.columns } : {}),
-        ...(cmd.deprecated ? { deprecated: cmd.deprecated } : {}),
-        ...(cmd.replacedBy ? { replacedBy: cmd.replacedBy } : {}),
     };
 }
-export function rootHelpData(program, siteNames) {
-    const siteSet = new Set(siteNames);
+export function rootHelpData(program, groups) {
+    const adapterNames = new Set([...groups.external, ...groups.apps, ...groups.sites]);
     const commands = program.commands
-        .filter(command => !siteSet.has(command.name()))
+        .filter(command => !adapterNames.has(command.name()))
         .map(command => ({
         name: command.name(),
         description: command.description(),
     }));
+    const sortLocale = (a, b) => a.localeCompare(b);
     return {
         name: program.name(),
         description: program.description(),
         commands,
+        external_clis: {
+            count: groups.external.length,
+            clis: [...groups.external].sort(sortLocale),
+        },
+        app_adapters: {
+            count: groups.apps.length,
+            apps: [...groups.apps].sort(sortLocale),
+        },
         site_adapters: {
-            count: siteNames.length,
-            sites: [...siteNames].sort((a, b) => a.localeCompare(b)),
+            count: groups.sites.length,
+            sites: [...groups.sites].sort(sortLocale),
         },
         next: [
             'opencli <site> --help -f yaml',
@@ -144,6 +167,5 @@ export function installStructuredHelp(command, data, textSuffix) {
 }
 export function formatSiteCommandDescription(cmd) {
     const access = cmd.access === 'write' ? '[write]' : '[read]';
-    const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
-    return `${access} ${cmd.description}${deprecatedSuffix}`;
+    return `${access} ${cmd.description}`;
 }

package/dist/src/help.test.d.ts

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

package/dist/src/help.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { classifyAdapter, formatRootAdapterHelpText } from './help.js';
+describe('classifyAdapter', () => {
+    it('classifies DNS-style domains as site', () => {
+        expect(classifyAdapter('www.bilibili.com')).toBe('site');
+        expect(classifyAdapter('chatgpt.com')).toBe('site');
+        expect(classifyAdapter('claude.ai')).toBe('site');
+        expect(classifyAdapter('grok.com')).toBe('site');
+    });
+    it('classifies localhost as app (Electron / osascript desktop integrations)', () => {
+        expect(classifyAdapter('localhost')).toBe('app');
+    });
+    it('classifies non-DNS domain strings as app (e.g. literal "doubao-app")', () => {
+        expect(classifyAdapter('doubao-app')).toBe('app');
+    });
+    it('defaults missing domain to site (most adapters without explicit domain are public web scrapers)', () => {
+        expect(classifyAdapter(undefined)).toBe('site');
+    });
+});
+describe('formatRootAdapterHelpText', () => {
+    it('renders all three sections in External / App / Site order when populated', () => {
+        const text = formatRootAdapterHelpText({
+            external: ['gh', 'docker'],
+            apps: ['chatwise', 'codex'],
+            sites: ['bilibili'],
+        });
+        expect(text).toContain('External CLIs (2):');
+        expect(text).toContain('App adapters (2):');
+        expect(text).toContain('Site adapters (1):');
+        expect(text.indexOf('External CLIs')).toBeLessThan(text.indexOf('App adapters'));
+        expect(text.indexOf('App adapters')).toBeLessThan(text.indexOf('Site adapters'));
+    });
+    it('omits empty sections instead of rendering a (0) header', () => {
+        const text = formatRootAdapterHelpText({
+            external: [],
+            apps: [],
+            sites: ['bilibili'],
+        });
+        expect(text).not.toContain('External CLIs');
+        expect(text).not.toContain('App adapters');
+        expect(text).toContain('Site adapters (1):');
+    });
+    it('returns empty string when all groups are empty', () => {
+        expect(formatRootAdapterHelpText({ external: [], apps: [], sites: [] })).toBe('');
+    });
+    it('always renders the agent discovery hint when any section is populated', () => {
+        const text = formatRootAdapterHelpText({
+            external: [],
+            apps: [],
+            sites: ['bilibili'],
+        });
+        expect(text).toContain("'opencli <site> --help -f yaml'");
+    });
+});

package/dist/src/main.js

@@ -28,7 +28,7 @@ const __dirname = path.dirname(__filename);
 const BUILTIN_CLIS = path.join(findPackageRoot(__filename), 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 // ── Session lifecycle flags ──────────────────────────────────────────────
-// `--live` / `--focus` are top-level-ish toggles that tweak the automation
+// `--live` / `--focus` / `--reuse` are top-level-ish toggles that tweak the automation
 // window's lifecycle. We strip them from argv before Commander runs so they
 // can be placed anywhere and work on any subcommand (adapter or browser).
 {
@@ -42,6 +42,19 @@ const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
         process.env.OPENCLI_WINDOW_FOCUSED = '1';
         process.argv.splice(focusIdx, 1);
     }
+    const reuseIdx = process.argv.findIndex(arg => arg === '--reuse' || arg.startsWith('--reuse='));
+    if (reuseIdx !== -1) {
+        const arg = process.argv[reuseIdx];
+        const value = arg.startsWith('--reuse=')
+            ? arg.slice('--reuse='.length)
+            : process.argv[reuseIdx + 1];
+        if (value !== 'none' && value !== 'site') {
+            process.stderr.write(`--reuse must be one of: none, site. Received: "${value ?? ''}"\n`);
+            process.exit(EXIT_CODES.USAGE_ERROR);
+        }
+        process.env.OPENCLI_BROWSER_REUSE = value;
+        process.argv.splice(reuseIdx, arg.startsWith('--reuse=') ? 1 : 2);
+    }
 }
 // ── Ultra-fast path: lightweight commands bypass full discovery ──────────
 // These are high-frequency or trivial paths that must not pay the startup tax.

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

@@ -28,9 +28,7 @@ export interface ManifestEntry {
     }>;
     columns?: string[];
     pipeline?: Record<string, unknown>[];
-    timeout?: number;
-    deprecated?: boolean | string;
-    replacedBy?: string;
+    defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
     type: 'js';
     /** Relative path from clis/ dir, e.g. 'bilibili/search.js' */
     modulePath?: string;
@@ -38,4 +36,8 @@ export interface ManifestEntry {
     sourceFile?: string;
     /** Pre-navigation control — see CliCommand.navigateBefore */
     navigateBefore?: boolean | string;
+    /** Browser session lifecycle defaults — see CliCommand.browserSession */
+    browserSession?: {
+        reuse?: 'none' | 'site';
+    };
 }

package/dist/src/pipeline/executor.js

@@ -32,7 +32,7 @@ export async function executePipeline(page, pipeline, ctx = {}) {
         }
     }
     catch (err) {
-        // Attempt cleanup: close automation window on pipeline failure
+        // Attempt cleanup: release automation tab lease on pipeline failure.
         if (page?.closeWindow) {
             try {
                 await page.closeWindow();

package/dist/src/pipeline/executor.test.js

@@ -14,6 +14,7 @@ function createMockPage(overrides = {}) {
         snapshot: vi.fn().mockResolvedValue(''),
         click: vi.fn(),
         typeText: vi.fn(),
+        fillText: vi.fn(),
         pressKey: vi.fn(),
         getFormState: vi.fn().mockResolvedValue({}),
         wait: vi.fn(),
@@ -159,6 +160,13 @@ describe('executePipeline', () => {
         ]);
         expect(page.click).toHaveBeenCalledWith('5');
     });
+    it('fill step calls page.fillText with raw rendered text', async () => {
+        const page = createMockPage();
+        await executePipeline(page, [
+            { fill: { ref: '@5', text: 'line1\\n/ / ${{ args.tail }}' } },
+        ], { args: { tail: 'raw' } });
+        expect(page.fillText).toHaveBeenCalledWith('5', 'line1\\n/ / raw');
+    });
     it('navigate preserves existing data through pipeline', async () => {
         const page = createMockPage({
             evaluate: vi.fn().mockResolvedValue([{ a: 1 }]),

package/dist/src/pipeline/registry.d.ts

@@ -13,6 +13,15 @@ export type StepHandler<TData = unknown, TResult = unknown, TParams = unknown> =
  * Get a registered step handler by name.
  */
 export declare function getStep(name: string): StepHandler | undefined;
+/**
+ * List all currently registered step names. Used by `validate.ts` to allowlist
+ * step names without maintaining a parallel hand-coded list.
+ *
+ * Note: this depends on registerStep() side effects below already having run.
+ * Importing this module triggers all core registrations at the bottom of the
+ * file, so the returned array reflects every core + plugin step at call time.
+ */
+export declare function getRegisteredStepNames(): string[];
 /**
  * Register a new custom step handler for the YAML pipeline.
  */