@jackwener/opencli 1.7.12 → 1.7.14

package/dist/src/help.js

@@ -1,6 +1,33 @@
 import yaml from 'js-yaml';
 import { fullName } from './registry.js';
 import { formatCommandExample } from './serialization.js';
+const COMMON_OPTIONS = [
+    {
+        flags: '-f, --format <fmt>',
+        name: 'format',
+        help: 'Output format: table, plain, json, yaml, md, csv',
+        default: 'table',
+        choices: ['table', 'plain', 'json', 'yaml', 'md', 'csv'],
+    },
+    {
+        flags: '--trace <mode>',
+        name: 'trace',
+        help: 'Trace capture: off, on, retain-on-failure',
+        default: 'off',
+        choices: ['off', 'on', 'retain-on-failure'],
+    },
+    {
+        flags: '-v, --verbose',
+        name: 'verbose',
+        help: 'Debug output',
+        default: false,
+    },
+    {
+        flags: '-h, --help',
+        name: 'help',
+        help: 'display help for command',
+    },
+];
 function normalizeStructuredHelpFormat(value) {
     const normalized = value?.toLowerCase();
     if (normalized === 'yaml' || normalized === 'yml')
@@ -50,18 +77,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 all command args/options in one structured response.");
+    lines.push('');
+    return lines.join('\n');
 }
 function compactArg(arg) {
     return {
@@ -75,35 +116,82 @@ function compactArg(arg) {
         ...(arg.help ? { help: arg.help } : {}),
     };
 }
-function compactCommand(cmd, opts = {}) {
+function compactCommonOption(option) {
+    return {
+        name: option.name,
+        flags: option.flags,
+        help: option.help,
+        ...('default' in option ? { default: option.default } : {}),
+        ...('choices' in option ? { choices: option.choices } : {}),
+    };
+}
+function positionals(cmd) {
+    return cmd.args.filter(arg => arg.positional);
+}
+function commandOptions(cmd) {
+    return cmd.args.filter(arg => !arg.positional);
+}
+function formatPositionals(args) {
+    return args
+        .map(arg => arg.required ? `<${arg.name}>` : `[${arg.name}]`)
+        .join(' ');
+}
+function formatCommandOptionTerm(arg) {
+    if (arg.required || arg.valueRequired)
+        return `--${arg.name} <value>`;
+    return `--${arg.name} [value]`;
+}
+export function formatCommandListTerm(cmd) {
+    const positionalText = formatPositionals(positionals(cmd));
+    const optionText = commandOptions(cmd).length > 0 ? ' [options]' : '';
+    return `${cmd.name}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
+}
+function formatUsage(cmd) {
+    const positionalText = formatPositionals(positionals(cmd));
+    return `opencli ${cmd.site} ${cmd.name}${positionalText ? ` ${positionalText}` : ''} [options]`;
+}
+function compactCommand(cmd) {
     return {
         name: cmd.name,
         command: `opencli ${cmd.site} ${cmd.name}`,
+        usage: formatUsage(cmd),
         access: cmd.access,
         description: cmd.description,
+        browser: !!cmd.browser,
+        ...(cmd.domain ? { domain: cmd.domain } : {}),
         ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
-        args: cmd.args.map(compactArg),
+        positionals: positionals(cmd).map(compactArg),
+        command_options: commandOptions(cmd).map(compactArg),
         example: formatCommandExample(cmd),
-        ...(opts.includeColumns && cmd.columns?.length ? { columns: cmd.columns } : {}),
-        ...(cmd.deprecated ? { deprecated: cmd.deprecated } : {}),
-        ...(cmd.replacedBy ? { replacedBy: cmd.replacedBy } : {}),
+        ...(cmd.browserSession ? { browserSession: cmd.browserSession } : {}),
+        ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
+        ...(cmd.columns?.length ? { columns: cmd.columns } : {}),
     };
 }
-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',
@@ -119,6 +207,7 @@ export function siteHelpData(site, commands) {
         site,
         command_count: unique.length,
         commands: unique.map(cmd => compactCommand(cmd)),
+        common_options: COMMON_OPTIONS.map(compactCommonOption),
         next: [
             `opencli ${site} <command> --help -f yaml`,
             `opencli ${site} <command> -f yaml`,
@@ -128,10 +217,95 @@ export function siteHelpData(site, commands) {
 export function commandHelpData(cmd) {
     return {
         site: cmd.site,
-        ...compactCommand(cmd, { includeColumns: true }),
+        ...compactCommand(cmd),
+        common_options: COMMON_OPTIONS.map(compactCommonOption),
         output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
     };
 }
+function formatRows(rows) {
+    if (rows.length === 0)
+        return [];
+    const width = Math.min(Math.max(...rows.map(([left]) => left.length)), 34);
+    return rows.map(([left, right]) => `  ${left.padEnd(width + 2)}${right}`);
+}
+function formatArgHelp(arg) {
+    const parts = [];
+    if (arg.help)
+        parts.push(arg.help);
+    if (arg.default !== undefined)
+        parts.push(`default: ${arg.default}`);
+    if (arg.choices?.length)
+        parts.push(`choices: ${arg.choices.join(', ')}`);
+    return parts.join('  ');
+}
+export function formatCommonOptionsHelpText() {
+    const rows = COMMON_OPTIONS.map(option => {
+        const details = [option.help];
+        if ('default' in option)
+            details.push(`default: ${option.default}`);
+        if ('choices' in option)
+            details.push(`choices: ${option.choices.join(', ')}`);
+        return [option.flags, details.join('  ')];
+    });
+    return ['Common options:', ...formatRows(rows)].join('\n');
+}
+export function formatSiteHelpText(site, commands) {
+    const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const lines = [
+        `Usage: opencli ${site} <command> [args] [options]`,
+        '',
+        wrapCommaList(unique.map(cmd => cmd.name), { indent: '' }),
+        '',
+        'Commands:',
+        ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
+        '',
+        formatCommonOptionsHelpText(),
+        '',
+        `Agent tip: use 'opencli ${site} --help -f yaml' to get all command args/options in one structured response.`,
+        '',
+    ];
+    return lines.join('\n');
+}
+export function formatCommandHelpText(cmd) {
+    const lines = [
+        `Usage: ${formatUsage(cmd)}`,
+        '',
+        cmd.description,
+        '',
+    ];
+    const positionalRows = positionals(cmd).map(arg => [
+        arg.name,
+        formatArgHelp(arg),
+    ]);
+    if (positionalRows.length) {
+        lines.push('Arguments:', ...formatRows(positionalRows), '');
+    }
+    const optionRows = commandOptions(cmd).map(arg => [
+        formatCommandOptionTerm(arg),
+        formatArgHelp(arg),
+    ]);
+    if (optionRows.length) {
+        lines.push('Command options:', ...formatRows(optionRows), '');
+    }
+    lines.push(formatCommonOptionsHelpText(), '');
+    const meta = [];
+    meta.push(`Access: ${cmd.access}`);
+    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+    if (cmd.domain)
+        meta.push(`Domain: ${cmd.domain}`);
+    if (cmd.defaultFormat)
+        meta.push(`Default format: ${cmd.defaultFormat}`);
+    if (cmd.aliases?.length)
+        meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
+    lines.push(meta.join(' | '));
+    lines.push(`Example: ${formatCommandExample(cmd)}`);
+    if (cmd.columns?.length)
+        lines.push(`Output columns: ${cmd.columns.join(', ')}`);
+    lines.push("Agent tip: use '--help -f yaml' for structured args/options.");
+    lines.push('');
+    return lines.join('\n');
+}
 export function installStructuredHelp(command, data, textSuffix) {
     const original = command.helpInformation.bind(command);
     command.helpInformation = ((contextOptions) => {
@@ -144,6 +318,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.
  */

package/dist/src/pipeline/registry.js

@@ -3,7 +3,7 @@
  * Allows core and third-party plugins to register custom YAML operations.
  */
 // Import core steps
-import { stepNavigate, stepClick, stepType, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
+import { stepNavigate, stepClick, stepType, stepFill, stepWait, stepPress, stepSnapshot, stepEvaluate } from './steps/browser.js';
 import { stepFetch } from './steps/fetch.js';
 import { stepSelect, stepMap, stepFilter, stepSort, stepLimit } from './steps/transform.js';
 import { stepIntercept } from './steps/intercept.js';
@@ -16,6 +16,17 @@ const _stepRegistry = new Map();
 export function getStep(name) {
     return _stepRegistry.get(name);
 }
+/**
+ * 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 function getRegisteredStepNames() {
+    return [..._stepRegistry.keys()];
+}
 /**
  * Register a new custom step handler for the YAML pipeline.
  */
@@ -32,6 +43,7 @@ registerStep('evaluate', stepEvaluate);
 registerStep('snapshot', stepSnapshot);
 registerStep('click', stepClick);
 registerStep('type', stepType);
+registerStep('fill', stepFill);
 registerStep('wait', stepWait);
 registerStep('press', stepPress);
 registerStep('map', stepMap);

package/dist/src/pipeline/steps/browser.d.ts

@@ -6,6 +6,7 @@ import type { IPage } from '../../types.js';
 export declare function stepNavigate(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepClick(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepType(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
+export declare function stepFill(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepWait(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepPress(page: IPage | null, params: unknown, data: unknown, args: Record<string, unknown>): Promise<unknown>;
 export declare function stepSnapshot(page: IPage | null, params: unknown, _data: unknown, _args: Record<string, unknown>): Promise<unknown>;

package/dist/src/pipeline/steps/browser.js

@@ -29,6 +29,16 @@ export async function stepType(page, params, data, args) {
     }
     return data;
 }
+export async function stepFill(page, params, data, args) {
+    if (isRecord(params)) {
+        const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
+        const text = String(render(params.text ?? '', { args, data }));
+        await page.fillText(ref, text);
+        if (params.submit)
+            await page.pressKey('Enter');
+    }
+    return data;
+}
 export async function stepWait(page, params, data, args) {
     if (typeof params === 'number')
         await page.wait(params);

package/dist/src/pipeline/steps/download.test.js

@@ -25,6 +25,7 @@ function createMockPage(getCookies) {
         snapshot: vi.fn().mockResolvedValue(''),
         click: vi.fn(),
         typeText: vi.fn(),
+        fillText: vi.fn(),
         pressKey: vi.fn(),
         scrollTo: vi.fn(),
         getFormState: vi.fn().mockResolvedValue({}),

package/dist/src/registry-api.d.ts

@@ -7,7 +7,7 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
-export type { CliCommand, Arg, CliOptions, CommandArgs } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, BrowserSessionOptions, BrowserSessionReuse } from './registry.js';
 export type { IPage } from './types.js';
 export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
 export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/registry.d.ts

@@ -6,7 +6,6 @@ export declare enum Strategy {
     PUBLIC = "public",
     LOCAL = "local",
     COOKIE = "cookie",
-    HEADER = "header",
     INTERCEPT = "intercept",
     UI = "ui"
 }
@@ -20,14 +19,20 @@ export interface Arg {
     help?: string;
     choices?: string[];
 }
-export interface RequiredEnv {
-    name: string;
-    help?: string;
-}
 export type CommandArgs = Record<string, any>;
 export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type CommandAccess = 'read' | 'write';
+export type BrowserSessionReuse = 'none' | 'site';
+export interface BrowserSessionOptions {
+    /**
+     * Control whether browser-backed adapter commands reuse a stable tab lease.
+     *
+     * - `none`: one-shot workspace per command execution (default)
+     * - `site`: all commands for this site share `site:<site>` until idle expiry
+     */
+    reuse?: BrowserSessionReuse;
+}
 interface BaseCliCommand {
     site: string;
     name: string;
@@ -41,16 +46,10 @@ interface BaseCliCommand {
     args: Arg[];
     columns?: string[];
     pipeline?: Record<string, unknown>[];
-    timeoutSeconds?: number;
     /** Origin of this command: 'yaml', 'ts', or plugin name. */
     source?: string;
     footerExtra?: (kwargs: CommandArgs) => string | undefined;
-    requiredEnv?: RequiredEnv[];
     validateArgs?: (kwargs: CommandArgs) => void;
-    /** Deprecation note shown in help / execution warnings. */
-    deprecated?: boolean | string;
-    /** Preferred replacement command, if any. */
-    replacedBy?: string;
     /**
      * Control pre-navigation and browser-session requirement.
      *
@@ -67,6 +66,8 @@ interface BaseCliCommand {
      * Adapter authors can set this explicitly to override the strategy-based default.
      */
     navigateBefore?: boolean | string;
+    /** Browser session lifecycle defaults for adapter commands. */
+    browserSession?: BrowserSessionOptions;
     /** Override the default CLI output format when the user does not pass -f/--format. */
     defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
 }

package/dist/src/registry.js

@@ -6,7 +6,6 @@ export var Strategy;
     Strategy["PUBLIC"] = "public";
     Strategy["LOCAL"] = "local";
     Strategy["COOKIE"] = "cookie";
-    Strategy["HEADER"] = "header";
     Strategy["INTERCEPT"] = "intercept";
     Strategy["UI"] = "ui";
 })(Strategy || (Strategy = {}));
@@ -18,6 +17,7 @@ export function cli(opts) {
         aliases: opts.aliases,
         description: opts.description ?? '',
         access: opts.access,
+        example: opts.example,
         domain: opts.domain,
         strategy: opts.strategy,
         browser: opts.browser,
@@ -25,12 +25,9 @@ export function cli(opts) {
         columns: opts.columns,
         func: opts.func,
         pipeline: opts.pipeline,
-        timeoutSeconds: opts.timeoutSeconds,
         footerExtra: opts.footerExtra,
-        requiredEnv: opts.requiredEnv,
-        deprecated: opts.deprecated,
-        replacedBy: opts.replacedBy,
         navigateBefore: opts.navigateBefore,
+        browserSession: opts.browserSession,
         defaultFormat: opts.defaultFormat,
     };
     registerCommand(cmd);
@@ -60,11 +57,12 @@ export function strategyLabel(cmd) {
  */
 function normalizeCommand(cmd) {
     assertCommandAccess(cmd);
+    assertBrowserSessionOptions(cmd);
     const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL);
     let navigateBefore = cmd.navigateBefore;
     if (navigateBefore === undefined) {
-        if ((strategy === Strategy.COOKIE || strategy === Strategy.HEADER) && cmd.domain) {
+        if (strategy === Strategy.COOKIE && cmd.domain) {
             navigateBefore = `https://${cmd.domain}`;
         }
         else if (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL) {
@@ -84,6 +82,18 @@ function assertCommandAccess(cmd) {
     const key = `${cmd.site}/${cmd.name}`;
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
+function assertBrowserSessionOptions(cmd) {
+    if (cmd.browserSession === undefined)
+        return;
+    const key = `${cmd.site}/${cmd.name}`;
+    if (cmd.browserSession === null || typeof cmd.browserSession !== 'object' || Array.isArray(cmd.browserSession)) {
+        throw new Error(`Command ${key} browserSession must be an object`);
+    }
+    const reuse = cmd.browserSession.reuse;
+    if (reuse !== undefined && reuse !== 'none' && reuse !== 'site') {
+        throw new Error(`Command ${key} browserSession.reuse must be one of: none, site`);
+    }
+}
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);
     const canonicalKey = fullName(normalized);

package/dist/src/registry.test.js

@@ -121,12 +121,12 @@ describe('registerCommand', () => {
             name: 'direct-reg', access: 'read',
             description: 'directly registered',
             args: [],
-            strategy: Strategy.HEADER,
+            strategy: Strategy.COOKIE,
             browser: true,
         };
         registerCommand(cmd);
         const reg = getRegistry();
-        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.HEADER);
+        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.COOKIE);
     });
 });
 describe('normalizeCommand (via registerCommand)', () => {