@jackwener/opencli 1.7.11 → 1.7.12

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.d.ts

@@ -27,11 +27,15 @@ export interface RequiredEnv {
 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';
 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[];
@@ -89,6 +93,7 @@ export type InternalCliCommand = CliCommand & {
 type RequiredCliOptions = {
     site: string;
     name: string;
+    access: CommandAccess;
     description?: string;
     args?: Arg[];
 };

package/dist/src/registry.js

@@ -17,6 +17,7 @@ export function cli(opts) {
         name: opts.name,
         aliases: opts.aliases,
         description: opts.description ?? '',
+        access: opts.access,
         domain: opts.domain,
         strategy: opts.strategy,
         browser: opts.browser,
@@ -58,6 +59,7 @@ export function strategyLabel(cmd) {
  *   2. Derived from strategy + domain (the defaults below)
  */
 function normalizeCommand(cmd) {
+    assertCommandAccess(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;
@@ -76,6 +78,12 @@ 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'`);
+}
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);
     const canonicalKey = fullName(normalized);

package/dist/src/registry.test.js

@@ -7,13 +7,14 @@ describe('cli() registration', () => {
     it('registers a command and returns it', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'hello',
+            name: 'hello', access: 'read',
             description: 'A test command',
             strategy: Strategy.PUBLIC,
             browser: false,
         });
         expect(cmd.site).toBe('test-registry');
         expect(cmd.name).toBe('hello');
+        expect(cmd.access).toBe('read');
         expect(cmd.strategy).toBe(Strategy.PUBLIC);
         expect(cmd.browser).toBe(false);
         expect(cmd.args).toEqual([]);
@@ -21,7 +22,7 @@ describe('cli() registration', () => {
     it('puts registered command in the registry', () => {
         cli({
             site: 'test-registry',
-            name: 'registered',
+            name: 'registered', access: 'read',
             description: 'test',
         });
         const registry = getRegistry();
@@ -30,7 +31,7 @@ describe('cli() registration', () => {
     it('defaults strategy to COOKIE when browser is true', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'default-strategy',
+            name: 'default-strategy', access: 'read',
         });
         expect(cmd.strategy).toBe(Strategy.COOKIE);
         expect(cmd.browser).toBe(true);
@@ -38,7 +39,7 @@ describe('cli() registration', () => {
     it('defaults strategy to PUBLIC when browser is false', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'no-browser',
+            name: 'no-browser', access: 'read',
             browser: false,
         });
         expect(cmd.strategy).toBe(Strategy.PUBLIC);
@@ -46,7 +47,7 @@ describe('cli() registration', () => {
     it('preserves LOCAL strategy on registration', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'local-strategy',
+            name: 'local-strategy', access: 'read',
             description: 'reads local credentials',
             strategy: Strategy.LOCAL,
             browser: false,
@@ -55,15 +56,15 @@ describe('cli() registration', () => {
         expect(cmd.browser).toBe(false);
     });
     it('overwrites existing command on re-registration', () => {
-        cli({ site: 'test-registry', name: 'overwrite', description: 'v1' });
-        cli({ site: 'test-registry', name: 'overwrite', description: 'v2' });
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v1' });
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v2' });
         const reg = getRegistry();
         expect(reg.get('test-registry/overwrite')?.description).toBe('v2');
     });
     it('registers aliases as alternate registry keys for the same command', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'canonical',
+            name: 'canonical', access: 'read',
             description: 'test aliases',
             aliases: ['compat', 'legacy-name'],
         });
@@ -76,18 +77,24 @@ describe('cli() registration', () => {
     it('preserves defaultFormat on the registered command', () => {
         const cmd = cli({
             site: 'test-registry',
-            name: 'plain-default',
+            name: 'plain-default', access: 'read',
             description: 'prefers plain output',
             defaultFormat: 'plain',
         });
         expect(cmd.defaultFormat).toBe('plain');
         expect(getRegistry().get('test-registry/plain-default')?.defaultFormat).toBe('plain');
     });
+    it('rejects commands without explicit access metadata', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'missing-access',
+        })).toThrow("Command test-registry/missing-access must declare access: 'read' | 'write'");
+    });
 });
 describe('fullName', () => {
     it('returns site/name', () => {
         const cmd = {
-            site: 'bilibili', name: 'hot', description: '', args: [],
+            site: 'bilibili', name: 'hot', access: 'read', description: '', args: [],
         };
         expect(fullName(cmd)).toBe('bilibili/hot');
     });
@@ -95,14 +102,14 @@ describe('fullName', () => {
 describe('strategyLabel', () => {
     it('returns strategy string', () => {
         const cmd = {
-            site: 'test', name: 'test', description: '', args: [],
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
             strategy: Strategy.INTERCEPT,
         };
         expect(strategyLabel(cmd)).toBe('intercept');
     });
     it('returns public when no strategy set', () => {
         const cmd = {
-            site: 'test', name: 'test', description: '', args: [],
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
         };
         expect(strategyLabel(cmd)).toBe('public');
     });
@@ -111,7 +118,7 @@ describe('registerCommand', () => {
     it('registers a pre-built command', () => {
         const cmd = {
             site: 'test-registry',
-            name: 'direct-reg',
+            name: 'direct-reg', access: 'read',
             description: 'directly registered',
             args: [],
             strategy: Strategy.HEADER,
@@ -125,7 +132,7 @@ describe('registerCommand', () => {
 describe('normalizeCommand (via registerCommand)', () => {
     it('COOKIE + domain → navigateBefore is the domain URL', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-domain', description: '', args: [],
+            site: 'test-norm', name: 'cookie-domain', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'x.com',
         });
         const cmd = getRegistry().get('test-norm/cookie-domain');
@@ -134,7 +141,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('COOKIE without domain → navigateBefore is true (auth context, no URL)', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-nodomain', description: '', args: [],
+            site: 'test-norm', name: 'cookie-nodomain', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE,
         });
         const cmd = getRegistry().get('test-norm/cookie-nodomain');
@@ -143,7 +150,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('INTERCEPT → navigateBefore is true (auth context)', () => {
         registerCommand({
-            site: 'test-norm', name: 'intercept', description: '', args: [],
+            site: 'test-norm', name: 'intercept', access: 'read', description: '', args: [],
             strategy: Strategy.INTERCEPT, domain: 'example.com',
         });
         const cmd = getRegistry().get('test-norm/intercept');
@@ -152,7 +159,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('PUBLIC → browser false, navigateBefore undefined', () => {
         registerCommand({
-            site: 'test-norm', name: 'public', description: '', args: [],
+            site: 'test-norm', name: 'public', access: 'read', description: '', args: [],
             strategy: Strategy.PUBLIC,
         });
         const cmd = getRegistry().get('test-norm/public');
@@ -161,7 +168,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('LOCAL → browser false, navigateBefore undefined', () => {
         registerCommand({
-            site: 'test-norm', name: 'local', description: '', args: [],
+            site: 'test-norm', name: 'local', access: 'read', description: '', args: [],
             strategy: Strategy.LOCAL,
         });
         const cmd = getRegistry().get('test-norm/local');
@@ -172,7 +179,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('explicit navigateBefore: false overrides COOKIE + domain', () => {
         registerCommand({
-            site: 'test-norm', name: 'cookie-override', description: '', args: [],
+            site: 'test-norm', name: 'cookie-override', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'amazon.com', navigateBefore: false,
         });
         const cmd = getRegistry().get('test-norm/cookie-override');
@@ -181,7 +188,7 @@ describe('normalizeCommand (via registerCommand)', () => {
     });
     it('explicit navigateBefore URL overrides strategy default', () => {
         registerCommand({
-            site: 'test-norm', name: 'explicit-url', description: '', args: [],
+            site: 'test-norm', name: 'explicit-url', access: 'read', description: '', args: [],
             strategy: Strategy.COOKIE, domain: 'x.com',
             navigateBefore: 'https://x.com/explore',
         });

package/dist/src/serialization.d.ts

@@ -24,15 +24,19 @@ export declare function serializeCommand(cmd: CliCommand): {
     name: string;
     aliases: string[];
     description: string;
+    access: import("./registry.js").CommandAccess;
     strategy: string;
     browser: boolean;
     args: SerializedArg[];
     columns: string[];
     domain: string | null;
+    example: string;
     deprecated: string | boolean | null;
     replacedBy: string | null;
 };
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export declare function formatCommandExample(cmd: CliCommand): string;
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export declare function formatRegistryHelpText(cmd: CliCommand): string;

package/dist/src/serialization.js

@@ -26,11 +26,13 @@ export function serializeCommand(cmd) {
         name: cmd.name,
         aliases: cmd.aliases ?? [],
         description: cmd.description,
+        access: cmd.access,
         strategy: strategyLabel(cmd),
         browser: !!cmd.browser,
         args: cmd.args.map(serializeArg),
         columns: cmd.columns ?? [],
         domain: cmd.domain ?? null,
+        example: formatCommandExample(cmd),
         deprecated: cmd.deprecated ?? null,
         replacedBy: cmd.replacedBy ?? null,
     };
@@ -51,6 +53,29 @@ function summarizeChoices(choices) {
         return choices.join(', ');
     return `${choices.slice(0, 4).join(', ')}, ... (+${choices.length - 4} more)`;
 }
+function formatValuePlaceholder(name) {
+    return `<${name}>`;
+}
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export function formatCommandExample(cmd) {
+    if (cmd.example?.trim())
+        return cmd.example.trim();
+    const parts = ['opencli', cmd.site, cmd.name];
+    for (const arg of cmd.args) {
+        if (arg.positional && arg.required) {
+            parts.push(formatValuePlaceholder(arg.name));
+        }
+    }
+    for (const arg of cmd.args) {
+        if (arg.positional || !arg.required)
+            continue;
+        parts.push(`--${arg.name}`);
+        if (arg.type !== 'bool' && arg.type !== 'boolean')
+            parts.push(formatValuePlaceholder(arg.name));
+    }
+    parts.push('-f', 'yaml');
+    return parts.join(' ');
+}
 /** Generate the --help appendix showing registry metadata not exposed by Commander. */
 export function formatRegistryHelpText(cmd) {
     const lines = [];
@@ -61,7 +86,7 @@ export function formatRegistryHelpText(cmd) {
         lines.push(`  ${prefix}: ${summarizeChoices(a.choices)}${def}`);
     }
     const meta = [];
-    meta.push(`Strategy: ${strategyLabel(cmd)}`);
+    meta.push(`Access: ${cmd.access}`);
     meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
     if (cmd.domain)
         meta.push(`Domain: ${cmd.domain}`);
@@ -72,6 +97,7 @@ export function formatRegistryHelpText(cmd) {
     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(', ')}`);
     return '\n' + lines.join('\n') + '\n';

package/dist/src/serialization.test.js

@@ -1,11 +1,11 @@
 import { describe, expect, it } from 'vitest';
 import { Strategy } from './registry.js';
-import { formatRegistryHelpText, serializeCommand } from './serialization.js';
+import { formatCommandExample, formatRegistryHelpText, serializeCommand } from './serialization.js';
 describe('formatRegistryHelpText', () => {
     it('summarizes long choices lists so help text stays readable', () => {
         const cmd = {
             site: 'demo',
-            name: 'dynamic',
+            name: 'dynamic', access: 'read',
             description: 'Demo command',
             strategy: Strategy.PUBLIC,
             browser: false,
@@ -24,6 +24,7 @@ describe('formatRegistryHelpText', () => {
         const cmd = {
             site: 'demo',
             name: 'get',
+            access: 'read',
             aliases: ['metadata'],
             description: 'Demo command',
             strategy: Strategy.COOKIE,
@@ -32,8 +33,29 @@ describe('formatRegistryHelpText', () => {
         };
         expect(serializeCommand(cmd)).toMatchObject({
             command: 'demo/get',
+            access: 'read',
             aliases: ['metadata'],
         });
         expect(formatRegistryHelpText(cmd)).toContain('Aliases: metadata');
     });
+    it('surfaces access and canonical examples instead of strategy as primary help metadata', () => {
+        const cmd = {
+            site: 'bilibili',
+            name: 'hot',
+            access: 'read',
+            description: 'Bilibili hot videos',
+            strategy: Strategy.COOKIE,
+            browser: true,
+            args: [],
+        };
+        expect(formatCommandExample(cmd)).toBe('opencli bilibili hot -f yaml');
+        expect(serializeCommand(cmd)).toMatchObject({
+            command: 'bilibili/hot',
+            access: 'read',
+            example: 'opencli bilibili hot -f yaml',
+        });
+        expect(formatRegistryHelpText(cmd)).toContain('Access: read');
+        expect(formatRegistryHelpText(cmd)).toContain('Example: opencli bilibili hot -f yaml');
+        expect(formatRegistryHelpText(cmd)).not.toContain('Strategy:');
+    });
 });

package/dist/src/types.d.ts

@@ -130,6 +130,8 @@ export interface IPage {
     setActivePage?(page?: string): void;
     /** Send a raw CDP command via chrome.debugger passthrough. */
     cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Accept or dismiss the currently open JavaScript alert/confirm/prompt dialog. */
+    handleJavaScriptDialog?(accept: boolean, promptText?: string): Promise<void>;
     /** List cross-origin iframe targets in snapshot order. */
     frames?(): Promise<Array<{
         index: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.11",
+  "version": "1.7.12",
   "publishConfig": {
     "access": "public"
   },
@@ -57,6 +57,9 @@
     "test:adapter": "vitest run --project adapter",
     "test:all": "vitest run",
     "test:e2e": "vitest run --project e2e",
+    "advise:listing-id-pairing": "node scripts/check-listing-id-pairing.mjs",
+    "check:silent-column-drop": "node scripts/check-silent-column-drop.mjs",
+    "check:typed-error-lint": "node scripts/check-typed-error-lint.mjs",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"