@jackwener/opencli 1.7.10 → 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.d.ts

@@ -5,6 +5,7 @@
  */
 import type { BrowserSessionInfo } from './types.js';
 import type { BrowserProfileStatus } from './browser/daemon-client.js';
+import { type AdapterShadow } from './adapter-shadow.js';
 export type DoctorOptions = {
     yes?: boolean;
     live?: boolean;
@@ -29,6 +30,7 @@ export type DoctorReport = {
     connectivity?: ConnectivityResult;
     sessions?: BrowserSessionInfo[];
     profiles?: BrowserProfileStatus[];
+    adapterShadows?: AdapterShadow[];
     issues: string[];
 };
 /**

package/dist/src/doctor.js

@@ -12,6 +12,7 @@ import { getRuntimeLabel } from './runtime-detect.js';
 import { getCachedLatestExtensionVersion } from './update-check.js';
 import { aliasForContextId, loadProfileConfig } from './browser/profile.js';
 import { formatDaemonVersion, isDaemonStale, staleDaemonIssue } from './browser/daemon-version.js';
+import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
 const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
 /** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
 function parseSemver(v) {
@@ -107,6 +108,7 @@ export async function runBrowserDoctor(opts = {}) {
         }
     }
     const extensionVersion = health.status?.extensionVersion;
+    const adapterShadows = findShadowedUserAdapters();
     const issues = [];
     if (daemonFlaky) {
         issues.push('Daemon connectivity is unstable. The live browser test succeeded, but the daemon was no longer running immediately afterward.\n' +
@@ -171,6 +173,9 @@ export async function runBrowserDoctor(opts = {}) {
         issues.push(`Extension update available: v${extensionVersion} → v${latestExtensionVersion}\n` +
             '  Download from: https://github.com/jackwener/opencli/releases');
     }
+    if (adapterShadows.length > 0) {
+        issues.push(formatAdapterShadowIssue(adapterShadows));
+    }
     return {
         cliVersion: opts.cliVersion,
         daemonRunning,
@@ -184,6 +189,7 @@ export async function runBrowserDoctor(opts = {}) {
         connectivity,
         sessions,
         profiles,
+        adapterShadows,
         issues,
     };
 }

package/dist/src/doctor.test.js

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-const { mockGetDaemonHealth, mockListSessions, mockConnect, mockClose } = vi.hoisted(() => ({
+const { mockGetDaemonHealth, mockListSessions, mockConnect, mockClose, mockFindShadowedUserAdapters } = vi.hoisted(() => ({
     mockGetDaemonHealth: vi.fn(),
     mockListSessions: vi.fn(),
     mockConnect: vi.fn(),
     mockClose: vi.fn(),
+    mockFindShadowedUserAdapters: vi.fn(),
 }));
 vi.mock('./browser/daemon-client.js', () => ({
     getDaemonHealth: mockGetDaemonHealth,
@@ -15,11 +16,19 @@ vi.mock('./browser/index.js', () => ({
         close = mockClose;
     },
 }));
+vi.mock('./adapter-shadow.js', async () => {
+    const actual = await vi.importActual('./adapter-shadow.js');
+    return {
+        ...actual,
+        findShadowedUserAdapters: mockFindShadowedUserAdapters,
+    };
+});
 import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
 describe('doctor report rendering', () => {
     const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
     beforeEach(() => {
         vi.clearAllMocks();
+        mockFindShadowedUserAdapters.mockReturnValue([]);
     });
     it('renders OK-style report when daemon and extension connected', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -34,6 +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).not.toContain('opencli browser analyze <url>');
     });
     it('renders a warning when daemon version is stale', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -273,6 +283,31 @@ describe('doctor report rendering', () => {
             expect.stringContaining('Stale daemon detected: daemon v1.7.6 != CLI v1.7.9'),
         ]));
     });
+    it('reports local adapter shadows as a warning issue', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.9',
+                extensionConnected: true,
+                extensionVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        mockFindShadowedUserAdapters.mockReturnValueOnce([
+            {
+                name: 'instagram/saved',
+                userPath: '/home/me/.opencli/clis/instagram/saved.js',
+                builtinPath: '/pkg/clis/instagram/saved.js',
+            },
+        ]);
+        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        expect(report.adapterShadows).toHaveLength(1);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Local adapter overrides shadow packaged adapters'),
+        ]));
+    });
     it('reports profile-required when multiple profiles are connected without a selection', async () => {
         const status = {
             state: 'profile-required',

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;