@jackwener/opencli 1.7.12 → 1.7.13

package/dist/src/cli.test.js

@@ -96,6 +96,90 @@ describe('createProgram root help descriptions', () => {
                 registry.set(key, value);
         }
     });
+    it('groups adapters into App / Site buckets by domain field', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            cli({
+                site: 'chatwise',
+                name: 'ask',
+                access: 'write',
+                description: 'Ask Chatwise desktop app',
+                domain: 'localhost',
+                strategy: Strategy.UI,
+                browser: true,
+            });
+            const program = createProgram('', '');
+            const help = program.helpInformation();
+            // Two separate sections, each with own count
+            expect(help).toContain('App adapters (1):');
+            expect(help).toMatch(/App adapters \(1\):\n {2}chatwise/);
+            expect(help).toContain('Site adapters (1):');
+            expect(help).toMatch(/Site adapters \(1\):\n {2}bilibili/);
+            // App adapters appear before Site adapters (External CLIs are absent here)
+            expect(help.indexOf('App adapters')).toBeLessThan(help.indexOf('Site adapters'));
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
+    it('exposes external_clis / app_adapters / site_adapters in structured help', () => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        const argv = process.argv;
+        registry.clear();
+        try {
+            cli({
+                site: 'bilibili',
+                name: 'hot',
+                access: 'read',
+                description: 'Bilibili hot videos',
+                domain: 'www.bilibili.com',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+            });
+            cli({
+                site: 'chatwise',
+                name: 'ask',
+                access: 'write',
+                description: 'Ask Chatwise desktop app',
+                domain: 'localhost',
+                strategy: Strategy.UI,
+                browser: true,
+            });
+            const program = createProgram('', '');
+            process.argv = ['node', 'opencli', '--help', '-f', 'yaml'];
+            const data = yaml.load(program.helpInformation());
+            expect(data.app_adapters.count).toBe(1);
+            expect(data.app_adapters.apps).toEqual(['chatwise']);
+            expect(data.site_adapters.count).toBe(1);
+            expect(data.site_adapters.sites).toEqual(['bilibili']);
+            expect(data.external_clis.count).toBeGreaterThanOrEqual(0);
+            expect(Array.isArray(data.external_clis.clis)).toBe(true);
+            // Adapters must NOT leak into the core commands list
+            const commandNames = data.commands.map((cmd) => cmd.name);
+            expect(commandNames).not.toContain('bilibili');
+            expect(commandNames).not.toContain('chatwise');
+        }
+        finally {
+            process.argv = argv;
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
     it('renders root structured help with built-ins and site adapter names', () => {
         const registry = getRegistry();
         const snapshot = new Map(registry);
@@ -1624,6 +1708,16 @@ describe('browser click/type commands', () => {
         evaluate: vi.fn().mockResolvedValue(false),
         click: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
         typeText: vi.fn().mockResolvedValue({ matches_n: 1, match_level: 'exact' }),
+        fillText: vi.fn().mockResolvedValue({
+            filled: true,
+            verified: true,
+            expected: '',
+            actual: '',
+            length: 0,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'input',
+        }),
         wait: vi.fn().mockResolvedValue(undefined),
     }));
     it('emits {clicked, target, matches_n, match_level} on success', async () => {
@@ -1721,6 +1815,62 @@ describe('browser click/type commands', () => {
         expect(browserState.page.click).toHaveBeenCalledWith('.field', { nth: 3 });
         expect(browserState.page.typeText).toHaveBeenCalledWith('.field', 'x', { nth: 3 });
     });
+    it('fill: delegates exact raw text to page.fillText and emits verification details', async () => {
+        browserState.page.fillText.mockResolvedValueOnce({
+            filled: true,
+            verified: true,
+            expected: 'line1\\n/ / raw',
+            actual: 'line1\\n/ / raw',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'textarea',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'line1\\n/ / raw']);
+        expect(browserState.page.fillText).toHaveBeenCalledWith('#msg', 'line1\\n/ / raw', {});
+        expect(lastJsonLog()).toEqual({
+            filled: true,
+            verified: true,
+            target: '#msg',
+            text: 'line1\\n/ / raw',
+            actual: 'line1\\n/ / raw',
+            length: 14,
+            matches_n: 1,
+            match_level: 'exact',
+            mode: 'textarea',
+        });
+        expect(process.exitCode).toBeUndefined();
+    });
+    it('fill: sets a non-zero exit code when verification fails', async () => {
+        browserState.page.fillText.mockResolvedValueOnce({
+            filled: true,
+            verified: false,
+            expected: 'expected',
+            actual: 'actual',
+            length: 6,
+            matches_n: 1,
+            match_level: 'exact',
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '#msg', 'expected']);
+        expect(lastJsonLog()).toEqual({
+            filled: true,
+            verified: false,
+            target: '#msg',
+            text: 'expected',
+            actual: 'actual',
+            length: 6,
+            matches_n: 1,
+            match_level: 'exact',
+        });
+        expect(process.exitCode).toBeDefined();
+    });
+    it('fill: forwards --nth to page.fillText', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'fill', '.field', 'x', '--nth', '2']);
+        expect(browserState.page.fillText).toHaveBeenCalledWith('.field', 'x', { nth: 2 });
+    });
 });
 describe('browser select command', () => {
     const { lastJsonLog } = installSelectorFirstTestHarness('select', () => ({

package/dist/src/commanderAdapter.js

@@ -89,11 +89,6 @@ export function registerCommandToProgram(siteCmd, cmd) {
             const formatExplicit = subCmd.getOptionValueSource('format') === 'cli';
             if (verbose)
                 process.env.OPENCLI_VERBOSE = '1';
-            if (cmd.deprecated) {
-                const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
-                const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
-                log.warn(`Deprecated: ${message}${replacement}`);
-            }
             const globals = typeof subCmd.optsWithGlobals === 'function' ? subCmd.optsWithGlobals() : {};
             const result = await executeCommand(cmd, kwargs, verbose, {
                 prepared: true,

package/dist/src/commanderAdapter.test.js

@@ -279,7 +279,6 @@ describe('commanderAdapter error envelope output', () => {
         expect(output).toContain('xsec_token');
         expect(output).toContain('--trace=retain-on-failure');
         expect(output).toContain('opencli xiaohongshu note --trace retain-on-failure');
-        expect(output).not.toContain('OPENCLI_DIAGNOSTIC');
         stderrSpy.mockRestore();
     });
     it('outputs YAML error envelope for selector errors', async () => {

package/dist/src/discovery.js

@@ -131,12 +131,11 @@ async function loadFromManifest(manifestPath, clisDir) {
                 browser: entry.browser,
                 args: entry.args ?? [],
                 columns: entry.columns,
+                defaultFormat: entry.defaultFormat,
                 pipeline: entry.pipeline,
-                timeoutSeconds: entry.timeout,
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
-                deprecated: entry.deprecated,
-                replacedBy: entry.replacedBy,
                 navigateBefore: entry.navigateBefore,
+                browserSession: entry.browserSession,
                 _lazy: true,
                 _modulePath: modulePath,
             };
@@ -170,7 +169,6 @@ async function discoverClisFromFs(dir) {
         await Promise.all(files.map(async (file) => {
             const filePath = path.join(siteDir, file);
             if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-                log.warn(`Ignoring YAML adapter ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
                 return;
             }
             if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
@@ -218,7 +216,6 @@ async function discoverPluginDir(dir, site) {
     await Promise.all(files.map(async (file) => {
         const filePath = path.join(dir, file);
         if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-            log.warn(`Ignoring YAML plugin ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
             return;
         }
         if (file.endsWith('.js') && !file.endsWith('.d.js')) {

package/dist/src/errors.js

@@ -73,7 +73,7 @@ export class AuthRequiredError extends CliError {
 }
 export class TimeoutError extends CliError {
     constructor(label, seconds, hint) {
-        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var', EXIT_CODES.TEMPFAIL);
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with --timeout <seconds> (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)', EXIT_CODES.TEMPFAIL);
     }
 }
 export class ArgumentError extends CliError {

package/dist/src/execution.d.ts

@@ -4,7 +4,7 @@
  * 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)

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;
+}