@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/help.js

@@ -0,0 +1,149 @@
+import yaml from 'js-yaml';
+import { fullName } from './registry.js';
+import { formatCommandExample } from './serialization.js';
+function normalizeStructuredHelpFormat(value) {
+    const normalized = value?.toLowerCase();
+    if (normalized === 'yaml' || normalized === 'yml')
+        return 'yaml';
+    if (normalized === 'json')
+        return 'json';
+    return undefined;
+}
+export function getRequestedHelpFormat(argv = process.argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '-f' || token === '--format') {
+            return normalizeStructuredHelpFormat(argv[i + 1]);
+        }
+        if (token.startsWith('--format=')) {
+            return normalizeStructuredHelpFormat(token.slice('--format='.length));
+        }
+        if (token.startsWith('-f') && token.length > 2) {
+            return normalizeStructuredHelpFormat(token.slice(2));
+        }
+    }
+    return undefined;
+}
+export function renderStructuredHelp(data, format) {
+    if (format === 'json')
+        return `${JSON.stringify(data, null, 2)}\n`;
+    return yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true });
+}
+export function wrapCommaList(items, opts = {}) {
+    const width = Math.max(opts.width ?? process.stdout.columns ?? 100, 40);
+    const indent = opts.indent ?? '  ';
+    const sorted = [...items].sort((a, b) => a.localeCompare(b));
+    const lines = [];
+    let line = indent;
+    sorted.forEach((item, index) => {
+        const token = `${item}${index < sorted.length - 1 ? ',' : ''}`;
+        const prefix = line === indent ? '' : ' ';
+        if (line.length + prefix.length + token.length > width && line.trim()) {
+            lines.push(line);
+            line = `${indent}${token}`;
+        }
+        else {
+            line += `${prefix}${token}`;
+        }
+    });
+    if (line.trim())
+        lines.push(line);
+    return lines.join('\n');
+}
+export function formatRootAdapterHelpText(siteNames) {
+    if (siteNames.length === 0)
+        return '';
+    return [
+        '',
+        `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');
+}
+function compactArg(arg) {
+    return {
+        name: arg.name,
+        ...(arg.type && arg.type !== 'string' ? { type: arg.type } : {}),
+        ...(arg.positional ? { positional: true } : {}),
+        ...(arg.required ? { required: true } : {}),
+        ...(arg.valueRequired ? { valueRequired: true } : {}),
+        ...(arg.default !== undefined ? { default: arg.default } : {}),
+        ...(arg.choices?.length ? { choices: arg.choices } : {}),
+        ...(arg.help ? { help: arg.help } : {}),
+    };
+}
+function compactCommand(cmd, opts = {}) {
+    return {
+        name: cmd.name,
+        command: `opencli ${cmd.site} ${cmd.name}`,
+        access: cmd.access,
+        description: cmd.description,
+        ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
+        args: cmd.args.map(compactArg),
+        example: formatCommandExample(cmd),
+        ...(opts.includeColumns && cmd.columns?.length ? { columns: cmd.columns } : {}),
+        ...(cmd.deprecated ? { deprecated: cmd.deprecated } : {}),
+        ...(cmd.replacedBy ? { replacedBy: cmd.replacedBy } : {}),
+    };
+}
+export function rootHelpData(program, siteNames) {
+    const siteSet = new Set(siteNames);
+    const commands = program.commands
+        .filter(command => !siteSet.has(command.name()))
+        .map(command => ({
+        name: command.name(),
+        description: command.description(),
+    }));
+    return {
+        name: program.name(),
+        description: program.description(),
+        commands,
+        site_adapters: {
+            count: siteNames.length,
+            sites: [...siteNames].sort((a, b) => a.localeCompare(b)),
+        },
+        next: [
+            'opencli <site> --help -f yaml',
+            'opencli list -f yaml',
+            'opencli <site> <command> -f yaml',
+        ],
+    };
+}
+export function siteHelpData(site, commands) {
+    const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        site,
+        command_count: unique.length,
+        commands: unique.map(cmd => compactCommand(cmd)),
+        next: [
+            `opencli ${site} <command> --help -f yaml`,
+            `opencli ${site} <command> -f yaml`,
+        ],
+    };
+}
+export function commandHelpData(cmd) {
+    return {
+        site: cmd.site,
+        ...compactCommand(cmd, { includeColumns: true }),
+        output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
+    };
+}
+export function installStructuredHelp(command, data, textSuffix) {
+    const original = command.helpInformation.bind(command);
+    command.helpInformation = ((contextOptions) => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(data(), format);
+        const suffix = typeof textSuffix === 'function' ? textSuffix() : textSuffix ?? '';
+        return original(contextOptions) + suffix;
+    });
+}
+export function formatSiteCommandDescription(cmd) {
+    const access = cmd.access === 'write' ? '[write]' : '[read]';
+    const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
+    return `${access} ${cmd.description}${deprecatedSuffix}`;
+}

package/dist/src/main.js

@@ -118,13 +118,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

@@ -0,0 +1,41 @@
+/**
+ * Shared manifest types — kept in their own module so both runtime code
+ * (discovery.ts) and the build-time compiler (build-manifest.ts) can
+ * import them without pulling each other in. This is what lets us
+ * exclude `src/build-manifest.ts` from `tsc`'s emit set: the only thing
+ * runtime code needs from build-manifest is the `ManifestEntry` type,
+ * and that lives here.
+ */
+export interface ManifestEntry {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    access: 'read' | 'write';
+    example?: string;
+    domain?: string;
+    strategy: string;
+    browser: boolean;
+    args: Array<{
+        name: string;
+        type?: string;
+        default?: unknown;
+        required?: boolean;
+        valueRequired?: boolean;
+        positional?: boolean;
+        help?: string;
+        choices?: string[];
+    }>;
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    timeout?: number;
+    deprecated?: boolean | string;
+    replacedBy?: string;
+    type: 'js';
+    /** Relative path from clis/ dir, e.g. 'bilibili/search.js' */
+    modulePath?: string;
+    /** Relative path to the source file from clis/ dir (e.g. 'site/cmd.js') */
+    sourceFile?: string;
+    /** Pre-navigation control — see CliCommand.navigateBefore */
+    navigateBefore?: boolean | string;
+}

package/dist/src/manifest-types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared manifest types — kept in their own module so both runtime code
+ * (discovery.ts) and the build-time compiler (build-manifest.ts) can
+ * import them without pulling each other in. This is what lets us
+ * exclude `src/build-manifest.ts` from `tsc`'s emit set: the only thing
+ * runtime code needs from build-manifest is the `ManifestEntry` type,
+ * and that lives here.
+ */
+export {};

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);