@jackwener/opencli 1.7.10 → 1.7.11

package/dist/src/cli.js

@@ -1759,6 +1759,7 @@ cli({
             fs.mkdirSync(dir, { recursive: true });
             fs.writeFileSync(filePath, template, 'utf-8');
             console.log(`Created: ${filePath}`);
+            console.log('First time on this site? Run: opencli browser analyze <url>');
             console.log(`Edit the file to implement your adapter, then run: opencli browser verify ${name}`);
         }
         catch (err) {
@@ -1773,6 +1774,7 @@ cli({
         .option('--update-fixture', 'Overwrite an existing fixture with one derived from current output')
         .option('--no-fixture', 'Ignore any fixture file for this run (no value-level validation)')
         .option('--strict-memory', 'Fail (not just warn) when ~/.opencli/sites/<site>/endpoints.json or notes.md is missing')
+        .option('--seed-args <value>', 'Seed args when no fixture exists; use JSON array/object for multiple args or flags')
         .option('--trace <mode>', 'Trace capture for the adapter subprocess: off, on, retain-on-failure', 'off')
         .description('Execute an adapter and validate output; uses fixture at ~/.opencli/sites/<site>/verify/<cmd>.json when present')
         .action(async (name, opts = {}) => {
@@ -1790,7 +1792,7 @@ cli({
                 return;
             }
             const { execFileSync } = await import('node:child_process');
-            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs } = await import('./browser/verify-fixture.js');
+            const { loadFixture, writeFixture, deriveFixture, validateRows, fixturePath, expandFixtureArgs, parseSeedArgs } = await import('./browser/verify-fixture.js');
             const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.js`);
             if (!fs.existsSync(filePath)) {
                 console.error(`Adapter not found: ${filePath}`);
@@ -1807,9 +1809,10 @@ cli({
             //   - array form    ["123", "--limit", "3"]   → verbatim (for positional subjects)
             const adapterSrc = fs.readFileSync(filePath, 'utf-8');
             const hasLimitArg = /['"]limit['"]/.test(adapterSrc);
-            const fixtureArgs = fixture?.args;
-            const cliArgs = expandFixtureArgs(fixtureArgs);
-            if (cliArgs.length === 0 && hasLimitArg)
+            const seedArgs = parseSeedArgs(opts.seedArgs);
+            const explicitArgs = fixture?.args ?? seedArgs;
+            const cliArgs = expandFixtureArgs(explicitArgs);
+            if (explicitArgs === undefined && cliArgs.length === 0 && hasLimitArg)
                 cliArgs.push('--limit', '3');
             const traceArgs = opts.trace && opts.trace !== 'off' ? ['--trace', opts.trace] : [];
             const argDisplay = [...cliArgs, ...traceArgs].join(' ');
@@ -1858,10 +1861,10 @@ cli({
                     console.log(`  Use --update-fixture to overwrite.`);
                 }
                 else {
-                    const seedArgs = fixtureArgs !== undefined
-                        ? fixtureArgs
+                    const fixtureArgs = explicitArgs !== undefined
+                        ? explicitArgs
                         : (hasLimitArg ? { limit: 3 } : undefined);
-                    const derived = deriveFixture(rows, seedArgs);
+                    const derived = deriveFixture(rows, fixtureArgs);
                     const p = writeFixture(site, command, derived);
                     console.log(`\n  ${fixture ? '↻ Updated' : '✎ Wrote'} fixture: ${p}`);
                     console.log(`  Review and hand-tune the derived expectations (add patterns / notEmpty, tighten rowCount).`);

package/dist/src/cli.test.js

@@ -151,6 +151,64 @@ describe('browser verify', () => {
             fs.rmSync(fakeHome, { recursive: true, force: true });
         }
     });
+    it('uses --seed-args when no fixture args exist', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-seed-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture', '--seed-args', 'opencli-verify']);
+            expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+            const [, execArgs] = mockExecFileSync.mock.calls[0];
+            expect(execArgs.slice(-5)).toEqual(['hn', 'top', 'opencli-verify', '--format', 'json']);
+        }
+        finally {
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
+    it('writes --seed-args into a starter fixture', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-write-seed-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        mockExecFileSync.mockReturnValue(JSON.stringify([{ title: 'ok' }]));
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--write-fixture', '--seed-args', 'opencli-verify']);
+            const fixtureFile = path.join(fakeHome, '.opencli', 'sites', 'hn', 'verify', 'top.json');
+            const fixture = JSON.parse(fs.readFileSync(fixtureFile, 'utf-8'));
+            expect(fixture.args).toEqual(['opencli-verify']);
+            expect(fixture.expect.columns).toEqual(['title']);
+        }
+        finally {
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
 });
 describe('profile list', () => {
     const stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => { });

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,
     };
 }
@@ -279,6 +285,7 @@ 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

@@ -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).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/manifest-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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;
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.10",
+  "version": "1.7.11",
   "publishConfig": {
     "access": "public"
   },
@@ -42,7 +42,7 @@
     "dev": "tsx src/main.ts",
     "dev:bun": "bun src/main.ts",
     "build": "npm run clean-dist && tsc && npm run copy-yaml && npm run build-manifest",
-    "build-manifest": "node dist/src/build-manifest.js",
+    "build-manifest": "tsx src/build-manifest.ts",
     "clean-dist": "node scripts/clean-dist.cjs",
     "copy-yaml": "node scripts/copy-yaml.cjs",
     "start": "node dist/src/main.js",