@jackwener/opencli 1.7.11 → 1.7.13

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.
@@ -118,13 +131,19 @@ installNodeNetwork();
 //    user-CLI discovery MUST run after built-in discovery to preserve the
 //    intended override order (user adapters override built-in ones).
 //  - discoverPlugins runs last: plugins may override both built-in and user CLIs.
-const [, ,] = await Promise.all([
-    ensureUserCliCompatShims(),
-    ensureUserAdapters(),
-    discoverClis(BUILTIN_CLIS),
-]);
-await discoverClis(USER_CLIS);
-await discoverPlugins();
+const skipUserDiscovery = argv[0] === 'convention-audit';
+if (skipUserDiscovery) {
+    await discoverClis(BUILTIN_CLIS);
+}
+else {
+    const [, ,] = await Promise.all([
+        ensureUserCliCompatShims(),
+        ensureUserAdapters(),
+        discoverClis(BUILTIN_CLIS),
+    ]);
+    await discoverClis(USER_CLIS);
+    await discoverPlugins();
+}
 // Register exit hook: notice appears after command output (same as npm/gh/yarn)
 registerUpdateNoticeOnExit();
 // Kick off background fetch for next run (non-blocking)

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

@@ -11,6 +11,8 @@ export interface ManifestEntry {
     name: string;
     aliases?: string[];
     description: string;
+    access: 'read' | 'write';
+    example?: string;
     domain?: string;
     strategy: string;
     browser: boolean;
@@ -26,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;
@@ -36,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/plugin.test.js

@@ -361,7 +361,7 @@ describe('listPlugins', () => {
     });
     it('lists installed plugins', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         const plugins = listPlugins();
         const found = plugins.find(p => p.name === '__test-list-plugin__');
         expect(found).toBeDefined();
@@ -369,7 +369,7 @@ describe('listPlugins', () => {
     });
     it('includes version metadata from the lock file', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(testDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         const lock = _readLockFile();
         lock['__test-list-plugin__'] = {
             source: { kind: 'git', url: 'https://github.com/user/repo.git' },
@@ -393,7 +393,7 @@ describe('listPlugins', () => {
         const localTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-list-'));
         const linkPath = path.join(PLUGINS_DIR, '__test-list-plugin__');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
-        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         try {
             fs.unlinkSync(linkPath);
         }
@@ -435,13 +435,13 @@ describe('uninstallPlugin', () => {
     });
     it('removes plugin directory', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test" })');
+        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test", access: "read" })');
         uninstallPlugin('__test-uninstall__');
         expect(fs.existsSync(testDir)).toBe(false);
     });
     it('removes lock entry on uninstall', () => {
         fs.mkdirSync(testDir, { recursive: true });
-        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test" })');
+        fs.writeFileSync(path.join(testDir, 'test.js'), 'cli({ site: "test", name: "test", access: "read" })');
         const lock = _readLockFile();
         lock['__test-uninstall__'] = {
             source: { kind: 'git', url: 'https://github.com/user/repo.git' },
@@ -464,7 +464,7 @@ describe('updatePlugin', () => {
         const localTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-update-'));
         const linkPath = path.join(PLUGINS_DIR, '__test-local-update__');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
-        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(localTarget, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         fs.symlinkSync(localTarget, linkPath, 'dir');
         const lock = _readLockFile();
         lock['__test-local-update__'] = {
@@ -540,7 +540,7 @@ describe('postInstallMonorepoLifecycle', () => {
             private: true,
             workspaces: ['packages/*'],
         }));
-        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
     });
     afterEach(() => {
         fs.rmSync(repoDir, { recursive: true, force: true });
@@ -575,9 +575,9 @@ describe('updateAllPlugins', () => {
         fs.mkdirSync(testDirA, { recursive: true });
         fs.mkdirSync(testDirB, { recursive: true });
         fs.mkdirSync(testDirC, { recursive: true });
-        fs.writeFileSync(path.join(testDirA, 'cmd.js'), 'cli({ site: "a", name: "cmd" })');
-        fs.writeFileSync(path.join(testDirB, 'cmd.js'), 'cli({ site: "b", name: "cmd" })');
-        fs.writeFileSync(path.join(testDirC, 'cmd.js'), 'cli({ site: "c", name: "cmd" })');
+        fs.writeFileSync(path.join(testDirA, 'cmd.js'), 'cli({ site: "a", name: "cmd", access: "read" })');
+        fs.writeFileSync(path.join(testDirB, 'cmd.js'), 'cli({ site: "b", name: "cmd", access: "read" })');
+        fs.writeFileSync(path.join(testDirC, 'cmd.js'), 'cli({ site: "c", name: "cmd", access: "read" })');
         const lock = _readLockFile();
         lock['plugin-a'] = {
             source: { kind: 'git', url: 'https://github.com/user/plugin-a.git' },
@@ -622,7 +622,7 @@ describe('updateAllPlugins', () => {
                 const cloneUrl = String(args[3]);
                 const cloneDir = String(args[4]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'cmd.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(cloneDir, 'cmd.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 if (cloneUrl.includes('plugin-b')) {
                     fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: 'plugin-b' }));
                 }
@@ -709,7 +709,7 @@ describe('monorepo uninstall with symlink', () => {
         monoDir = path.join(_getMonoreposDir(), '__test-mono__');
         const subDir = path.join(monoDir, 'packages', 'sub');
         fs.mkdirSync(subDir, { recursive: true });
-        fs.writeFileSync(path.join(subDir, 'cmd.js'), 'cli({ site: "test", name: "cmd" })');
+        fs.writeFileSync(path.join(subDir, 'cmd.js'), 'cli({ site: "test", name: "cmd", access: "read" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(subDir, pluginDir, 'dir');
         const lock = _readLockFile();
@@ -776,7 +776,7 @@ describe('listPlugins with monorepo metadata', () => {
     const testLink = path.join(PLUGINS_DIR, '__test-mono-list__');
     beforeEach(() => {
         fs.mkdirSync(testSymlinkTarget, { recursive: true });
-        fs.writeFileSync(path.join(testSymlinkTarget, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(testSymlinkTarget, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         try {
             fs.unlinkSync(testLink);
@@ -823,7 +823,7 @@ describe('installLocalPlugin', () => {
     const pluginName = '__test-local-plugin__';
     beforeEach(() => {
         tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-local-install-'));
-        fs.writeFileSync(path.join(tmpDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(tmpDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
     });
     afterEach(() => {
         const linkPath = path.join(PLUGINS_DIR, pluginName);
@@ -963,7 +963,7 @@ describe('installPlugin transactional staging', () => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[args.length - 1]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: standaloneName }));
                 return '';
             }
@@ -994,7 +994,7 @@ describe('installPlugin transactional staging', () => {
                         alpha: { path: 'packages/alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 return '';
             }
             if (cmd === 'npm' && Array.isArray(args) && args[0] === 'install') {
@@ -1051,7 +1051,7 @@ describe('installPlugin with existing monorepo', () => {
                 [pluginName]: { path: `packages/${pluginName}` },
             },
         }));
-        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+        fs.writeFileSync(path.join(subDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
         mockExecFileSync.mockImplementation((cmd, args) => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[4]);
@@ -1110,7 +1110,7 @@ describe('updatePlugin transactional staging', () => {
     });
     it('keeps the existing standalone plugin when staged update preparation fails', () => {
         fs.mkdirSync(standaloneDir, { recursive: true });
-        fs.writeFileSync(path.join(standaloneDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.writeFileSync(path.join(standaloneDir, 'old.js'), 'cli({ site: "old", name: "old", access: "read" })');
         const lock = _readLockFile();
         lock[standaloneName] = {
             source: {
@@ -1125,7 +1125,7 @@ describe('updatePlugin transactional staging', () => {
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
                 const cloneDir = String(args[4]);
                 fs.mkdirSync(cloneDir, { recursive: true });
-                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(cloneDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 fs.writeFileSync(path.join(cloneDir, 'package.json'), JSON.stringify({ name: standaloneName }));
                 return '';
             }
@@ -1145,7 +1145,7 @@ describe('updatePlugin transactional staging', () => {
     it('keeps the existing monorepo repo and link when staged update preparation fails', () => {
         const subDir = path.join(monorepoRepoDir, 'packages', monorepoPluginName);
         fs.mkdirSync(subDir, { recursive: true });
-        fs.writeFileSync(path.join(subDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.writeFileSync(path.join(subDir, 'old.js'), 'cli({ site: "old", name: "old", access: "read" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(subDir, monorepoLink, 'dir');
         const lock = _readLockFile();
@@ -1174,7 +1174,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: `packages/${monorepoPluginName}` },
                     },
                 }));
-                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(alphaDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 return '';
             }
             if (cmd === 'npm' && Array.isArray(args) && args[0] === 'install') {
@@ -1194,7 +1194,7 @@ describe('updatePlugin transactional staging', () => {
     it('relinks monorepo plugins when the updated manifest moves their subPath', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });
-        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old", access: "read" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(oldSubDir, monorepoLink, 'dir');
         const lock = _readLockFile();
@@ -1219,7 +1219,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: 'packages/moved-alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 return '';
             }
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
@@ -1238,7 +1238,7 @@ describe('updatePlugin transactional staging', () => {
     it('rejects monorepo updates whose manifest path escapes the repo root', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });
-        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old", access: "read" })');
         fs.mkdirSync(PLUGINS_DIR, { recursive: true });
         fs.symlinkSync(oldSubDir, monorepoLink, 'dir');
         const lock = _readLockFile();
@@ -1279,7 +1279,7 @@ describe('updatePlugin transactional staging', () => {
     it('rolls back the monorepo repo swap when relinking fails', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });
-        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old", access: "read" })');
         fs.mkdirSync(monorepoLink, { recursive: true });
         fs.writeFileSync(path.join(monorepoLink, 'blocker.txt'), 'not a symlink');
         const lock = _readLockFile();
@@ -1304,7 +1304,7 @@ describe('updatePlugin transactional staging', () => {
                         [monorepoPluginName]: { path: 'packages/moved-alpha' },
                     },
                 }));
-                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello" })');
+                fs.writeFileSync(path.join(movedDir, 'hello.js'), 'cli({ site: "test", name: "hello", access: "read" })');
                 return '';
             }
             if (cmd === 'git' && Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {

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,33 +19,37 @@ 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;
     aliases?: string[];
     description: string;
+    access: CommandAccess;
+    /** Canonical invocation shown in agent-facing help. Generated when omitted. */
+    example?: string;
     domain?: string;
     strategy?: Strategy;
     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.
      *
@@ -63,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';
 }
@@ -89,6 +94,7 @@ export type InternalCliCommand = CliCommand & {
 type RequiredCliOptions = {
     site: string;
     name: string;
+    access: CommandAccess;
     description?: string;
     args?: Arg[];
 };

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 = {}));
@@ -17,6 +16,8 @@ export function cli(opts) {
         name: opts.name,
         aliases: opts.aliases,
         description: opts.description ?? '',
+        access: opts.access,
+        example: opts.example,
         domain: opts.domain,
         strategy: opts.strategy,
         browser: opts.browser,
@@ -24,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);
@@ -58,11 +56,13 @@ export function strategyLabel(cmd) {
  *   2. Derived from strategy + domain (the defaults below)
  */
 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) {
@@ -76,6 +76,24 @@ function normalizeCommand(cmd) {
         ? { ...cmd, strategy, browser: true, navigateBefore }
         : { ...cmd, strategy, browser: false, navigateBefore };
 }
+function assertCommandAccess(cmd) {
+    if (cmd.access === 'read' || cmd.access === 'write')
+        return;
+    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);