@jackwener/opencli 1.3.2 → 1.4.0

package/dist/plugin.test.js

@@ -1,11 +1,13 @@
 /**
- * Tests for plugin management: install, uninstall, list.
+ * Tests for plugin management: install, uninstall, list, and lock file support.
  */
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { PLUGINS_DIR } from './discovery.js';
-import { listPlugins, uninstallPlugin, updatePlugin, _parseSource } from './plugin.js';
+import * as pluginModule from './plugin.js';
+const { LOCK_FILE, _getCommitHash, listPlugins, _readLockFile, _resolveEsbuildBin, uninstallPlugin, updatePlugin, _parseSource, _updateAllPlugins, _validatePluginStructure, _writeLockFile, } = pluginModule;
 describe('parseSource', () => {
     it('parses github:user/repo format', () => {
         const result = _parseSource('github:ByteYue/opencli-plugin-github-trending');
@@ -34,6 +36,131 @@ describe('parseSource', () => {
         expect(_parseSource('npm:some-package')).toBeNull();
     });
 });
+describe('validatePluginStructure', () => {
+    const testDir = path.join(PLUGINS_DIR, '__test-validate__');
+    beforeEach(() => {
+        fs.mkdirSync(testDir, { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(testDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('returns invalid for non-existent directory', () => {
+        const res = _validatePluginStructure(path.join(PLUGINS_DIR, '__does_not_exist__'));
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('does not exist');
+    });
+    it('returns invalid for empty directory', () => {
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('No command files found');
+    });
+    it('returns valid for YAML plugin', () => {
+        fs.writeFileSync(path.join(testDir, 'cmd.yaml'), 'site: test');
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(true);
+        expect(res.errors).toHaveLength(0);
+    });
+    it('returns valid for JS plugin', () => {
+        fs.writeFileSync(path.join(testDir, 'cmd.js'), 'console.log("hi");');
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(true);
+        expect(res.errors).toHaveLength(0);
+    });
+    it('returns invalid for TS plugin without package.json', () => {
+        fs.writeFileSync(path.join(testDir, 'cmd.ts'), 'console.log("hi");');
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('contains .ts files but no package.json');
+    });
+    it('returns invalid for TS plugin with missing type: module', () => {
+        fs.writeFileSync(path.join(testDir, 'cmd.ts'), 'console.log("hi");');
+        fs.writeFileSync(path.join(testDir, 'package.json'), JSON.stringify({ name: 'test' }));
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(false);
+        expect(res.errors[0]).toContain('must have "type": "module"');
+    });
+    it('returns valid for TS plugin with correct package.json', () => {
+        fs.writeFileSync(path.join(testDir, 'cmd.ts'), 'console.log("hi");');
+        fs.writeFileSync(path.join(testDir, 'package.json'), JSON.stringify({ type: 'module' }));
+        const res = _validatePluginStructure(testDir);
+        expect(res.valid).toBe(true);
+        expect(res.errors).toHaveLength(0);
+    });
+});
+describe('lock file', () => {
+    const backupPath = `${LOCK_FILE}.test-backup`;
+    let hadOriginal = false;
+    beforeEach(() => {
+        hadOriginal = fs.existsSync(LOCK_FILE);
+        if (hadOriginal) {
+            fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+            fs.copyFileSync(LOCK_FILE, backupPath);
+        }
+    });
+    afterEach(() => {
+        if (hadOriginal) {
+            fs.copyFileSync(backupPath, LOCK_FILE);
+            fs.unlinkSync(backupPath);
+            return;
+        }
+        try {
+            fs.unlinkSync(LOCK_FILE);
+        }
+        catch { }
+    });
+    it('reads empty lock when file does not exist', () => {
+        try {
+            fs.unlinkSync(LOCK_FILE);
+        }
+        catch { }
+        expect(_readLockFile()).toEqual({});
+    });
+    it('round-trips lock entries', () => {
+        const entries = {
+            'test-plugin': {
+                source: 'https://github.com/user/repo.git',
+                commitHash: 'abc1234567890def',
+                installedAt: '2025-01-01T00:00:00.000Z',
+            },
+            'another-plugin': {
+                source: 'https://github.com/user/another.git',
+                commitHash: 'def4567890123abc',
+                installedAt: '2025-02-01T00:00:00.000Z',
+                updatedAt: '2025-03-01T00:00:00.000Z',
+            },
+        };
+        _writeLockFile(entries);
+        expect(_readLockFile()).toEqual(entries);
+    });
+    it('handles malformed lock file gracefully', () => {
+        fs.mkdirSync(path.dirname(LOCK_FILE), { recursive: true });
+        fs.writeFileSync(LOCK_FILE, 'not valid json');
+        expect(_readLockFile()).toEqual({});
+    });
+});
+describe('getCommitHash', () => {
+    it('returns a hash for a git repo', () => {
+        const hash = _getCommitHash(process.cwd());
+        expect(hash).toBeDefined();
+        expect(hash).toMatch(/^[0-9a-f]{40}$/);
+    });
+    it('returns undefined for non-git directory', () => {
+        expect(_getCommitHash(os.tmpdir())).toBeUndefined();
+    });
+});
+describe('resolveEsbuildBin', () => {
+    it('resolves a usable esbuild executable path', () => {
+        const binPath = _resolveEsbuildBin();
+        expect(binPath).not.toBeNull();
+        expect(typeof binPath).toBe('string');
+        expect(fs.existsSync(binPath)).toBe(true);
+        // On Windows the resolved path ends with 'esbuild.cmd', on Unix 'esbuild'
+        expect(binPath).toMatch(/esbuild(\.cmd)?$/);
+    });
+});
 describe('listPlugins', () => {
     const testDir = path.join(PLUGINS_DIR, '__test-list-plugin__');
     afterEach(() => {
@@ -50,6 +177,24 @@ describe('listPlugins', () => {
         expect(found).toBeDefined();
         expect(found.commands).toContain('hello');
     });
+    it('includes version metadata from the lock file', () => {
+        fs.mkdirSync(testDir, { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        const lock = _readLockFile();
+        lock['__test-list-plugin__'] = {
+            source: 'https://github.com/user/repo.git',
+            commitHash: 'abcdef1234567890abcdef1234567890abcdef12',
+            installedAt: '2025-01-01T00:00:00.000Z',
+        };
+        _writeLockFile(lock);
+        const plugins = listPlugins();
+        const found = plugins.find(p => p.name === '__test-list-plugin__');
+        expect(found).toBeDefined();
+        expect(found.version).toBe('abcdef1');
+        expect(found.installedAt).toBe('2025-01-01T00:00:00.000Z');
+        delete lock['__test-list-plugin__'];
+        _writeLockFile(lock);
+    });
     it('returns empty array when no plugins dir', () => {
         // listPlugins should handle missing dir gracefully
         const plugins = listPlugins();
@@ -70,6 +215,19 @@ describe('uninstallPlugin', () => {
         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.yaml'), 'site: test');
+        const lock = _readLockFile();
+        lock['__test-uninstall__'] = {
+            source: 'https://github.com/user/repo.git',
+            commitHash: 'abc123',
+            installedAt: '2025-01-01T00:00:00.000Z',
+        };
+        _writeLockFile(lock);
+        uninstallPlugin('__test-uninstall__');
+        expect(_readLockFile()['__test-uninstall__']).toBeUndefined();
+    });
     it('throws for non-existent plugin', () => {
         expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
     });
@@ -79,3 +237,61 @@ describe('updatePlugin', () => {
         expect(() => updatePlugin('__nonexistent__')).toThrow('not installed');
     });
 });
+vi.mock('node:child_process', () => {
+    return {
+        execFileSync: vi.fn((_cmd, args, opts) => {
+            if (Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
+                if (opts?.cwd === os.tmpdir()) {
+                    throw new Error('not a git repository');
+                }
+                return '1234567890abcdef1234567890abcdef12345678\n';
+            }
+            if (opts && opts.cwd && String(opts.cwd).endsWith('plugin-b')) {
+                throw new Error('Network error');
+            }
+            return '';
+        }),
+        execSync: vi.fn(() => ''),
+    };
+});
+describe('updateAllPlugins', () => {
+    const testDirA = path.join(PLUGINS_DIR, 'plugin-a');
+    const testDirB = path.join(PLUGINS_DIR, 'plugin-b');
+    const testDirC = path.join(PLUGINS_DIR, 'plugin-c');
+    beforeEach(() => {
+        fs.mkdirSync(testDirA, { recursive: true });
+        fs.mkdirSync(testDirB, { recursive: true });
+        fs.mkdirSync(testDirC, { recursive: true });
+        fs.writeFileSync(path.join(testDirA, 'cmd.yaml'), 'site: a');
+        fs.writeFileSync(path.join(testDirB, 'cmd.yaml'), 'site: b');
+        fs.writeFileSync(path.join(testDirC, 'cmd.yaml'), 'site: c');
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(testDirA, { recursive: true });
+        }
+        catch { }
+        try {
+            fs.rmSync(testDirB, { recursive: true });
+        }
+        catch { }
+        try {
+            fs.rmSync(testDirC, { recursive: true });
+        }
+        catch { }
+        vi.clearAllMocks();
+    });
+    it('collects successes and failures without throwing', () => {
+        const results = _updateAllPlugins();
+        const resA = results.find(r => r.name === 'plugin-a');
+        const resB = results.find(r => r.name === 'plugin-b');
+        const resC = results.find(r => r.name === 'plugin-c');
+        expect(resA).toBeDefined();
+        expect(resA.success).toBe(true);
+        expect(resB).toBeDefined();
+        expect(resB.success).toBe(false);
+        expect(resB.error).toContain('Network error');
+        expect(resC).toBeDefined();
+        expect(resC.success).toBe(true);
+    });
+});

package/dist/record.js

@@ -17,7 +17,8 @@ import * as readline from 'node:readline';
 import chalk from 'chalk';
 import yaml from 'js-yaml';
 import { sendCommand } from './browser/daemon-client.js';
-import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES, } from './constants.js';
+import { SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES } from './constants.js';
+import { urlToPattern, findArrayPath, inferCapabilityName, inferStrategy, detectAuthFromContent, classifyQueryParams, } from './analysis.js';
 // ── Interceptor JS ─────────────────────────────────────────────────────────
 /**
  * Generates a full-capture interceptor that stores {url, method, status, body}
@@ -110,92 +111,6 @@ function generateReadRecordedJs() {
   `;
 }
 // ── Analysis helpers ───────────────────────────────────────────────────────
-function urlToPattern(url) {
-    try {
-        const p = new URL(url);
-        const pathNorm = p.pathname
-            .replace(/\/\d+/g, '/{id}')
-            .replace(/\/[0-9a-fA-F]{8,}/g, '/{hex}')
-            .replace(/\/BV[a-zA-Z0-9]{10}/g, '/{bvid}');
-        const params = [];
-        p.searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
-            params.push(k); });
-        return `${p.host}${pathNorm}${params.length ? '?' + params.sort().map(k => `${k}={}`).join('&') : ''}`;
-    }
-    catch {
-        return url;
-    }
-}
-function detectAuthIndicators(url, body) {
-    const indicators = [];
-    // Heuristic: if body contains sign/w_rid fields, it's likely signed
-    if (body && typeof body === 'object') {
-        const keys = Object.keys(body).map(k => k.toLowerCase());
-        if (keys.some(k => k.includes('sign') || k === 'w_rid' || k.includes('token'))) {
-            indicators.push('signature');
-        }
-    }
-    // Check URL for common auth patterns
-    if (url.includes('/wbi/') || url.includes('w_rid='))
-        indicators.push('signature');
-    if (url.includes('bearer') || url.includes('access_token'))
-        indicators.push('bearer');
-    return indicators;
-}
-function findArrayPath(obj, depth = 0) {
-    if (depth > 5 || !obj || typeof obj !== 'object')
-        return null;
-    if (Array.isArray(obj)) {
-        if (obj.length >= 2 && obj.some(i => i && typeof i === 'object' && !Array.isArray(i))) {
-            return { path: '', items: obj };
-        }
-        return null;
-    }
-    let best = null;
-    for (const [key, val] of Object.entries(obj)) {
-        const found = findArrayPath(val, depth + 1);
-        if (found) {
-            const fullPath = found.path ? `${key}.${found.path}` : key;
-            const candidate = { path: fullPath, items: found.items };
-            if (!best || candidate.items.length > best.items.length)
-                best = candidate;
-        }
-    }
-    return best;
-}
-function inferCapabilityName(url) {
-    const u = url.toLowerCase();
-    if (u.includes('hot') || u.includes('popular') || u.includes('ranking') || u.includes('trending'))
-        return 'hot';
-    if (u.includes('search'))
-        return 'search';
-    if (u.includes('feed') || u.includes('timeline') || u.includes('dynamic'))
-        return 'feed';
-    if (u.includes('comment') || u.includes('reply'))
-        return 'comments';
-    if (u.includes('history'))
-        return 'history';
-    if (u.includes('profile') || u.includes('me'))
-        return 'me';
-    if (u.includes('favorite') || u.includes('collect') || u.includes('bookmark'))
-        return 'favorite';
-    try {
-        const segs = new URL(url).pathname
-            .split('/')
-            .filter(s => s && !s.match(/^\d+$/) && !s.match(/^[0-9a-f]{8,}$/i) && !s.match(/^v\d+$/));
-        if (segs.length)
-            return segs[segs.length - 1].replace(/[^a-z0-9]/gi, '_').toLowerCase();
-    }
-    catch { }
-    return 'data';
-}
-function inferStrategy(authIndicators) {
-    if (authIndicators.includes('signature'))
-        return 'intercept';
-    if (authIndicators.includes('bearer') || authIndicators.includes('csrf'))
-        return 'header';
-    return 'cookie';
-}
 function scoreRequest(req, arrayResult) {
     let s = 0;
     if (arrayResult) {
@@ -247,14 +162,7 @@ function buildRecordedYaml(site, pageUrl, req, capName, arrayResult, authIndicat
             ? ''
             : itemPath.split('.').map(p => `?.${p}`).join('');
     // Detect search/limit/page params (must be before fetch URL building to use hasSearch/hasPage)
-    const qp = [];
-    try {
-        new URL(req.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
-            qp.push(k); });
-    }
-    catch { }
-    const hasSearch = qp.some(p => SEARCH_PARAMS.has(p));
-    const hasPage = qp.some(p => PAGINATION_PARAMS.has(p));
+    const { hasSearch, hasPagination: hasPage } = classifyQueryParams(req.url);
     // Build evaluate script
     const mapLines = Object.entries(detectedFields)
         .map(([role, field]) => `          ${role}: item?.${field}`)
@@ -363,10 +271,9 @@ export async function recordSession(opts) {
         let stopped = false;
         const stop = () => { stopped = true; };
         const { promise: enterPromise, cleanup: cleanupEnter } = waitForEnter();
-        const enterRace = enterPromise.then(stop);
+        enterPromise.then(stop);
         const timeoutPromise = new Promise(r => setTimeout(() => {
             stop();
-            cleanupEnter(); // close readline to prevent process from hanging
             r();
         }, timeoutMs));
         // Poll loop: drain captured data + inject interceptor into any new tabs
@@ -394,6 +301,7 @@ export async function recordSession(opts) {
             }
         }, pollMs);
         await Promise.race([enterPromise, timeoutPromise]);
+        cleanupEnter(); // Always clean up readline to prevent process from hanging
         clearInterval(pollInterval);
         // Final drain from all known tabs
         for (const tabId of injectedTabs) {
@@ -476,7 +384,7 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
     const scored = [];
     for (const [pattern, req] of seen) {
         const arrayResult = findArrayPath(req.body);
-        const authIndicators = detectAuthIndicators(req.url, req.body);
+        const authIndicators = detectAuthFromContent(req.url, req.body);
         const score = scoreRequest(req, arrayResult);
         if (score > 0) {
             scored.push({ req, pattern, arrayResult, authIndicators, score });

package/dist/registry-api.d.ts

@@ -9,3 +9,5 @@
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
 export type { CliCommand, Arg, CliOptions } from './registry.js';
 export type { IPage } from './types.js';
+export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
+export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/registry-api.js

@@ -7,3 +7,4 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';

package/dist/registry.d.ts

@@ -18,6 +18,10 @@ export interface Arg {
     help?: string;
     choices?: string[];
 }
+export interface RequiredEnv {
+    name: string;
+    help?: string;
+}
 export type CommandArgs = Record<string, any>;
 export interface CliCommand {
     site: string;
@@ -34,6 +38,7 @@ export interface CliCommand {
     /** Origin of this command: 'yaml', 'ts', or plugin name. */
     source?: string;
     footerExtra?: (kwargs: CommandArgs) => string | undefined;
+    requiredEnv?: RequiredEnv[];
     /**
      * Control pre-navigation for cookie/header context before command execution.
      *
@@ -65,5 +70,3 @@ export declare function getRegistry(): Map<string, CliCommand>;
 export declare function fullName(cmd: CliCommand): string;
 export declare function strategyLabel(cmd: CliCommand): string;
 export declare function registerCommand(cmd: CliCommand): void;
-export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';
-export type { SerializedArg } from './serialization.js';

package/dist/registry.js

@@ -26,6 +26,7 @@ export function cli(opts) {
         pipeline: opts.pipeline,
         timeoutSeconds: opts.timeoutSeconds,
         footerExtra: opts.footerExtra,
+        requiredEnv: opts.requiredEnv,
         navigateBefore: opts.navigateBefore,
     };
     const key = fullName(cmd);
@@ -44,5 +45,3 @@ export function strategyLabel(cmd) {
 export function registerCommand(cmd) {
     _registry.set(fullName(cmd), cmd);
 }
-// Re-export serialization helpers from their dedicated module
-export { serializeArg, serializeCommand, formatArgSummary, formatRegistryHelpText } from './serialization.js';

package/dist/runtime.d.ts

@@ -7,7 +7,6 @@ export declare function getBrowserFactory(): new () => IBrowserFactory;
 export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;
-export declare const DEFAULT_BROWSER_SMOKE_TIMEOUT: number;
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */

package/dist/runtime.js

@@ -7,10 +7,20 @@ import { TimeoutError } from './errors.js';
 export function getBrowserFactory() {
     return (process.env.OPENCLI_CDP_ENDPOINT ? CDPBridge : BrowserBridge);
 }
-export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
-export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '60', 10);
-export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_EXPLORE_TIMEOUT ?? '120', 10);
-export const DEFAULT_BROWSER_SMOKE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_SMOKE_TIMEOUT ?? '60', 10);
+function parseEnvTimeout(envVar, fallback) {
+    const raw = process.env[envVar];
+    if (raw === undefined)
+        return fallback;
+    const parsed = parseInt(raw, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        console.error(`[runtime] Invalid ${envVar}="${raw}", using default ${fallback}s`);
+        return fallback;
+    }
+    return parsed;
+}
+export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_CONNECT_TIMEOUT', 30);
+export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_COMMAND_TIMEOUT', 60);
+export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseEnvTimeout('OPENCLI_BROWSER_EXPLORE_TIMEOUT', 120);
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */

package/dist/snapshotFormatter.d.ts

@@ -1,18 +1,11 @@
 /**
  * Aria snapshot formatter: parses Playwright MCP snapshot text into clean format.
  *
- * Multi-pass pipeline:
- * 1. Parse & filter: strip annotations, metadata, noise roles, ads, decorators
- * 2. Deduplicate: generic/text child matching parent label
- * 3. Deduplicate: heading + link with identical labels
- * 4. Deduplicate: nested identical links
- * 5. Prune: empty containers (iterative bottom-up)
- * 6. Collapse: single-child containers
+ * 4-pass pipeline:
+ * 1. Parse & filter: strip annotations, metadata, noise, ads, boilerplate subtrees
+ * 2. Deduplicate: generic/text parent match, heading+link, nested identical links
+ * 3. Prune: empty containers (iterative bottom-up)
+ * 4. Collapse: single-child containers
  */
-export interface FormatOptions {
-    interactive?: boolean;
-    compact?: boolean;
-    maxDepth?: number;
-    maxTextLength?: number;
-}
-export declare function formatSnapshot(raw: string, opts?: FormatOptions): string;
+import type { SnapshotOptions } from './types.js';
+export declare function formatSnapshot(raw: string, opts?: SnapshotOptions): string;