@jackwener/opencli 1.7.11 → 1.7.12

package/dist/src/convention-audit.test.js

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { renderConventionAuditText, runConventionAudit } from './convention-audit.js';
+describe('convention audit', () => {
+    const tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    function makeProject(manifest, files) {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-convention-audit-'));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, 'clis'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'cli-manifest.json'), JSON.stringify(manifest, null, 2));
+        for (const [relative, content] of Object.entries(files)) {
+            const file = path.join(root, 'clis', relative);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, content);
+        }
+        return root;
+    }
+    it('reports column, metadata, typed-error, and write-pair violations', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title', 'authorName'],
+                sourceFile: 'demo/search.js',
+            },
+            {
+                site: 'demo',
+                name: 'like',
+                access: 'write',
+                sourceFile: 'demo/like.js',
+            },
+            {
+                site: 'demo',
+                name: 'missing',
+                columns: [],
+                sourceFile: 'demo/missing.js',
+            },
+            {
+                site: 'clean',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title'],
+                sourceFile: 'clean/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run(kwargs) {
+          const limit = Math.min(kwargs.limit, 100);
+          try {
+            await fetch('/items');
+          } catch {
+            return [];
+          }
+          rows.push({
+            id: item.id,
+            title: item.title ?? 'unknown',
+            url: item.url,
+            authorName: item.authorName,
+          });
+          return limit;
+        }
+      `,
+            'demo/like.js': 'export async function run() { return { ok: true }; }',
+            'demo/missing.js': 'export async function run() { return { ok: true }; }',
+            'clean/search.js': 'export async function run() { rows.push({ id: item.id, title: item.title }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const category = (rule) => report.categories.find((item) => item.rule === rule);
+        expect(report.ok).toBe(false);
+        expect(category('silent-column-drop').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+        expect(category('camelCase-in-columns').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: { column: 'authorName' },
+        });
+        expect(category('missing-access-metadata').violations[0]).toMatchObject({ command: 'demo/missing' });
+        expect(category('silent-clamp').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-empty-fallback').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-sentinel').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('write-without-delete-pair').violations[0]).toMatchObject({
+            command: 'demo/like',
+            details: { expected_any_of: ['unlike'] },
+        });
+    });
+    it('supports site and command target filters', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+            { site: 'other', name: 'search', access: 'read', columns: ['id'], sourceFile: 'other/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+            'other/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+        });
+        expect(runConventionAudit({ projectRoot: root, site: 'demo' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'other/search' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'missing' }).summary.commands).toBe(0);
+    });
+    it('renders a compact text report', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1 }); }',
+        });
+        const text = renderConventionAuditText(runConventionAudit({ projectRoot: root }));
+        expect(text).toContain('Convention Audit Report');
+        expect(text).toContain('OK - no convention violations found.');
+    });
+    it('scans pipeline map blocks for silent column drops', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'feed', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/feed.js' },
+        ], {
+            'demo/feed.js': `
+        cli({
+          site: 'demo',
+          name: 'feed',
+          access: 'read',
+          columns: ['id', 'title'],
+          pipeline: [
+            { map: {
+              id: '\${{ item.id }}',
+              title: '\${{ item.title }}',
+              url: '\${{ item.url }}',
+            } },
+          ],
+        });
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/feed',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+    });
+    it('ignores ok:false diagnostic objects when checking emitted rows', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'url'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          if (!document.querySelector('.items')) {
+            return { ok: false, bodyLen: document.body.innerText.length, sample: document.body.innerText.slice(0, 800), url: location.href };
+          }
+          return rows.map((row) => ({ id: row.id, url: row.url }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('ignores raw intermediate keys when a final mapper converts them into columns', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'rating', 'reviews', 'price'],
+                sourceFile: 'demo/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            starClass: item.starClass,
+            reviewsRaw: item.reviewsRaw,
+            priceRaw: item.priceRaw,
+          });
+          return rows.map((r) => ({
+            id: r.id,
+            rating: r.starClass ? Number(r.starClass) / 10 : null,
+            reviews: parseReviewCount(r.reviewsRaw),
+            price: parsePrice(r.priceRaw),
+          }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('still reports raw keys emitted directly without a final mapper', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            title: titleRaw,
+            titleRaw,
+          });
+          return rows;
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['titleRaw'] }),
+        });
+    });
+    it('only reports empty array fallbacks inside catch blocks', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'guard', access: 'read', columns: ['id'], sourceFile: 'demo/guard.js' },
+            { site: 'demo', name: 'catch', access: 'read', columns: ['id'], sourceFile: 'demo/catch.js' },
+        ], {
+            'demo/guard.js': 'export async function run() { if (!store) return []; rows.push({ id: 1 }); }',
+            'demo/catch.js': 'export async function run() { try { await fetch("/"); } catch (err) { return []; } rows.push({ id: 1 }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-empty-fallback').violations;
+        expect(violations.map((violation) => violation.command)).toEqual(['demo/catch']);
+    });
+});

package/dist/src/discovery.js

@@ -124,6 +124,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                 name: entry.name,
                 aliases: entry.aliases,
                 description: entry.description ?? '',
+                access: entry.access,
+                example: entry.example,
                 domain: entry.domain,
                 strategy: parseStrategy(entry.strategy),
                 browser: entry.browser,

package/dist/src/doctor.js

@@ -285,7 +285,6 @@ export function renderBrowserDoctorReport(report) {
     }
     else if (report.daemonRunning && report.extensionConnected) {
         lines.push('', styleText('green', 'Everything looks good!'));
-        lines.push(styleText('dim', 'Tip: writing a new adapter? Run `opencli browser analyze <url>` for one-shot site recon.'));
     }
     return lines.join('\n');
 }

package/dist/src/doctor.test.js

@@ -43,7 +43,7 @@ describe('doctor report rendering', () => {
         expect(text).toContain('(v1.7.9)');
         expect(text).toContain('[OK] Extension: connected (v1.6.8)');
         expect(text).toContain('Everything looks good!');
-        expect(text).toContain('opencli browser analyze <url>');
+        expect(text).not.toContain('opencli browser analyze <url>');
     });
     it('renders a warning when daemon version is stale', () => {
         const text = strip(renderBrowserDoctorReport({

package/dist/src/engine.test.js

@@ -27,7 +27,7 @@ export const helper = true;
 import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'temp-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -57,7 +57,7 @@ cli({
 import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'fallback-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -86,7 +86,7 @@ import { htmlToMarkdown } from '@jackwener/opencli/utils';
 
 cli({
   site: 'legacy-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -204,7 +204,7 @@ describe('executeCommand', () => {
     it('accepts kebab-case option names after Commander camelCases them', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'kebab-arg-test',
+            name: 'kebab-arg-test', access: 'read',
             description: 'test command with kebab-case arg',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -219,7 +219,7 @@ describe('executeCommand', () => {
     it('executes a command with func', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'func-test',
+            name: 'func-test', access: 'read',
             description: 'test command with func',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -233,7 +233,7 @@ describe('executeCommand', () => {
     it('executes a command with pipeline', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'pipe-test',
+            name: 'pipe-test', access: 'read',
             description: 'test command with pipeline',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -248,7 +248,7 @@ describe('executeCommand', () => {
     it('throws for command with no func or pipeline', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'empty-test',
+            name: 'empty-test', access: 'read',
             description: 'empty command',
             browser: false,
         });
@@ -258,7 +258,7 @@ describe('executeCommand', () => {
         let receivedDebug = false;
         const cmd = cli({
             site: 'test-engine',
-            name: 'debug-test',
+            name: 'debug-test', access: 'read',
             description: 'debug test',
             browser: false,
             func: async (_kwargs, debug) => {
@@ -276,7 +276,7 @@ describe('executeCommand', () => {
         });
         const cmd = cli({
             site: 'test-engine',
-            name: 'failing-test',
+            name: 'failing-test', access: 'read',
             description: 'failing command',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -297,7 +297,7 @@ describe('executeCommand', () => {
             .mockResolvedValue('http://127.0.0.1:9228');
         const cmd = cli({
             site: 'chatwise',
-            name: 'status',
+            name: 'status', access: 'read',
             description: 'chatwise status',
             browser: true,
             strategy: Strategy.PUBLIC,

package/dist/src/execution.js

@@ -301,7 +301,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace: `site:${cmd.site}`, cdpEndpoint, contextId });
+            }, { workspace: `site:${cmd.site}:${crypto.randomUUID()}`, cdpEndpoint, contextId });
         }
         else {
             // Non-browser commands: apply timeout only when explicitly configured.

package/dist/src/execution.test.js

@@ -12,7 +12,7 @@ describe('executeCommand — non-browser timeout', () => {
     it('applies timeoutSeconds to non-browser commands', async () => {
         const cmd = cli({
             site: 'test-execution',
-            name: 'non-browser-timeout',
+            name: 'non-browser-timeout', access: 'read',
             description: 'test non-browser timeout',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -32,7 +32,7 @@ describe('executeCommand — non-browser timeout', () => {
     it('skips timeout when timeoutSeconds is 0', async () => {
         const cmd = cli({
             site: 'test-execution',
-            name: 'non-browser-zero-timeout',
+            name: 'non-browser-zero-timeout', access: 'read',
             description: 'test zero timeout bypasses wrapping',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -53,7 +53,7 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-close-on-error',
+            name: 'browser-close-on-error', access: 'read',
             description: 'test closeWindow on failure',
             browser: true,
             strategy: Strategy.PUBLIC,
@@ -73,7 +73,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-success',
+                name: 'browser-live-success', access: 'read',
                 description: 'test closeWindow skipped with --live on success',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -100,7 +100,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-failure',
+                name: 'browser-live-failure', access: 'read',
                 description: 'test closeWindow skipped with --live on failure',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -121,7 +121,7 @@ describe('executeCommand — non-browser timeout', () => {
         const validateArgs = vi.fn();
         const cmd = {
             site: 'test-execution',
-            name: 'prepared-validation',
+            name: 'prepared-validation', access: 'read',
             description: 'test prepared validation path',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -164,7 +164,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-failure',
+                name: 'browser-trace-failure', access: 'read',
                 description: 'test trace export',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -224,7 +224,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-success',
+                name: 'browser-trace-success', access: 'read',
                 description: 'test trace export on success',
                 browser: true,
                 strategy: Strategy.PUBLIC,
@@ -281,7 +281,7 @@ describe('executeCommand — non-browser timeout', () => {
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-trace-export-fails',
+                name: 'browser-trace-export-fails', access: 'read',
                 description: 'test trace export failure handling',
                 browser: true,
                 strategy: Strategy.PUBLIC,

package/dist/src/help.d.ts

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import type { CliCommand } from './registry.js';
+export type StructuredHelpFormat = 'yaml' | 'json';
+export declare function getRequestedHelpFormat(argv?: readonly string[]): StructuredHelpFormat | undefined;
+export declare function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string;
+export declare function wrapCommaList(items: readonly string[], opts?: {
+    width?: number;
+    indent?: string;
+}): string;
+export declare function formatRootAdapterHelpText(siteNames: readonly string[]): string;
+export declare function rootHelpData(program: Command, siteNames: readonly string[]): Record<string, unknown>;
+export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
+export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
+export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;
+export declare function formatSiteCommandDescription(cmd: CliCommand): string;

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

@@ -11,6 +11,8 @@ export interface ManifestEntry {
     name: string;
     aliases?: string[];
     description: string;
+    access: 'read' | 'write';
+    example?: string;
     domain?: string;
     strategy: string;
     browser: boolean;