@jackwener/opencli 1.3.1 → 1.3.2

package/dist/errors.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { CliError, BrowserConnectError, AdapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, SelectorError, } from './errors.js';
+describe('Error type hierarchy', () => {
+    it('all error types extend CliError', () => {
+        const errors = [
+            new BrowserConnectError('test'),
+            new AdapterLoadError('test'),
+            new CommandExecutionError('test'),
+            new ConfigError('test'),
+            new AuthRequiredError('example.com'),
+            new TimeoutError('test', 30),
+            new ArgumentError('test'),
+            new EmptyResultError('test/cmd'),
+            new SelectorError('.btn'),
+        ];
+        for (const err of errors) {
+            expect(err).toBeInstanceOf(CliError);
+            expect(err).toBeInstanceOf(Error);
+        }
+    });
+    it('AuthRequiredError has correct code, domain, and auto-generated hint', () => {
+        const err = new AuthRequiredError('bilibili.com');
+        expect(err.code).toBe('AUTH_REQUIRED');
+        expect(err.domain).toBe('bilibili.com');
+        expect(err.message).toBe('Not logged in to bilibili.com');
+        expect(err.hint).toContain('https://bilibili.com');
+    });
+    it('AuthRequiredError accepts custom message', () => {
+        const err = new AuthRequiredError('x.com', 'No ct0 cookie found');
+        expect(err.message).toBe('No ct0 cookie found');
+        expect(err.hint).toContain('https://x.com');
+    });
+    it('TimeoutError has correct code and hint', () => {
+        const err = new TimeoutError('bilibili/hot', 60);
+        expect(err.code).toBe('TIMEOUT');
+        expect(err.message).toBe('bilibili/hot timed out after 60s');
+        expect(err.hint).toContain('timeout');
+    });
+    it('ArgumentError has correct code', () => {
+        const err = new ArgumentError('Argument "limit" must be a valid number');
+        expect(err.code).toBe('ARGUMENT');
+    });
+    it('EmptyResultError has default hint', () => {
+        const err = new EmptyResultError('hackernews/top');
+        expect(err.code).toBe('EMPTY_RESULT');
+        expect(err.message).toBe('hackernews/top returned no data');
+        expect(err.hint).toBeTruthy();
+    });
+    it('SelectorError has default hint about page changes', () => {
+        const err = new SelectorError('.submit-btn');
+        expect(err.code).toBe('SELECTOR');
+        expect(err.message).toContain('.submit-btn');
+        expect(err.hint).toContain('report');
+    });
+    it('BrowserConnectError has correct code', () => {
+        const err = new BrowserConnectError('Cannot connect');
+        expect(err.code).toBe('BROWSER_CONNECT');
+    });
+});

package/dist/execution.js

@@ -11,14 +11,11 @@
 import { Strategy, getRegistry, fullName } from './registry.js';
 import { pathToFileURL } from 'node:url';
 import { executePipeline } from './pipeline/index.js';
-import { AdapterLoadError } from './errors.js';
+import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 /** Set of TS module paths that have been loaded */
 const _loadedModules = new Set();
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /**
  * Validates and coerces arguments based on the command's Arg definitions.
  */
@@ -28,14 +25,14 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
         const val = result[argDef.name];
         // 1. Check required
         if (argDef.required && (val === undefined || val === null || val === '')) {
-            throw new Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+            throw new ArgumentError(`Argument "${argDef.name}" is required.`, argDef.help ?? `Provide a value for --${argDef.name}`);
         }
         if (val !== undefined && val !== null) {
             // 2. Type coercion
             if (argDef.type === 'int' || argDef.type === 'number') {
                 const num = Number(val);
                 if (Number.isNaN(num)) {
-                    throw new Error(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+                    throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
                 }
                 result[argDef.name] = num;
             }
@@ -47,7 +44,7 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
                     else if (lower === 'false' || lower === '0')
                         result[argDef.name] = false;
                     else
-                        throw new Error(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+                        throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
                 }
                 else {
                     result[argDef.name] = Boolean(val);
@@ -57,7 +54,7 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
             const coercedVal = result[argDef.name];
             if (argDef.choices && argDef.choices.length > 0) {
                 if (!argDef.choices.map(String).includes(String(coercedVal))) {
-                    throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+                    throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
                 }
             }
         }
@@ -95,7 +92,7 @@ async function runCommand(cmd, page, kwargs, debug) {
         return cmd.func(page, kwargs, debug);
     if (cmd.pipeline)
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
-    throw new Error(`Command ${fullName(cmd)} has no func or pipeline`);
+    throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
 }
 /**
  * Resolve the pre-navigation URL for a command, or null to skip.
@@ -127,7 +124,9 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
         kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
     }
     catch (err) {
-        throw new Error(`[Argument Validation Error]\n${getErrorMessage(err)}`);
+        if (err instanceof ArgumentError)
+            throw err;
+        throw new ArgumentError(getErrorMessage(err));
     }
     if (shouldUseBrowserSession(cmd)) {
         const BrowserFactory = getBrowserFactory();

package/dist/explore.js

@@ -12,6 +12,7 @@ import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_
 import { detectFramework } from './scripts/framework.js';
 import { discoverStores } from './scripts/store.js';
 import { interactFuzz } from './scripts/interact.js';
+import { log } from './logger.js';
 // ── Site name detection ────────────────────────────────────────────────────
 const KNOWN_SITE_ALIASES = {
     'x.com': 'twitter', 'twitter.com': 'twitter',
@@ -148,7 +149,8 @@ function flattenFields(obj, prefix, maxDepth) {
     return names;
 }
 function isBooleanRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        && Object.values(value).every(v => typeof v === 'boolean');
 }
 function scoreEndpoint(ep) {
     let s = 0;
@@ -360,7 +362,7 @@ export async function exploreUrl(url, opts) {
                     await page.wait(2); // wait for XHRs to settle
                 }
                 catch (e) {
-                    // fuzzing is best-effort, don't fail the whole explore
+                    log.debug(`Interactive fuzzing skipped: ${e instanceof Error ? e.message : String(e)}`);
                 }
             }
             // Step 3: Read page metadata

package/dist/external.d.ts

@@ -15,6 +15,21 @@ export interface ExternalCliConfig {
 export declare function loadExternalClis(): ExternalCliConfig[];
 export declare function isBinaryInstalled(binary: string): boolean;
 export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export declare function parseCommand(cmd: string): {
+    binary: string;
+    args: string[];
+};
 export declare function installExternalCli(cli: ExternalCliConfig): boolean;
 export declare function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void;
 export interface RegisterOptions {

package/dist/external.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { spawnSync, execSync, execFileSync } from 'node:child_process';
+import { spawnSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
@@ -66,6 +66,52 @@ export function getInstallCmd(installConfig) {
         return installConfig.default;
     return null;
 }
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export function parseCommand(cmd) {
+    const shellOperators = /&&|\|\|?|;|[><`]/;
+    if (shellOperators.test(cmd)) {
+        throw new Error(`Install command contains unsafe shell operators and cannot be executed securely: "${cmd}". ` +
+            `Please install the tool manually.`);
+    }
+    // Tokenise respecting single- and double-quoted segments (no variable expansion).
+    const tokens = [];
+    const re = /(?:"([^"]*)")|(?:'([^']*)')|(\S+)/g;
+    let match;
+    while ((match = re.exec(cmd)) !== null) {
+        tokens.push(match[1] ?? match[2] ?? match[3]);
+    }
+    if (tokens.length === 0) {
+        throw new Error(`Install command is empty.`);
+    }
+    const [binary, ...args] = tokens;
+    return { binary, args };
+}
+function shouldRetryWithCmdShim(binary, err) {
+    return os.platform() === 'win32' && !path.extname(binary) && err.code === 'ENOENT';
+}
+function runInstallCommand(cmd) {
+    const { binary, args } = parseCommand(cmd);
+    try {
+        execFileSync(binary, args, { stdio: 'inherit' });
+    }
+    catch (err) {
+        if (shouldRetryWithCmdShim(binary, err)) {
+            execFileSync(`${binary}.cmd`, args, { stdio: 'inherit' });
+            return;
+        }
+        throw err;
+    }
+}
 export function installExternalCli(cli) {
     if (!cli.install) {
         console.error(chalk.red(`No auto-install command configured for '${cli.name}'.`));
@@ -82,7 +128,7 @@ export function installExternalCli(cli) {
     console.log(chalk.cyan(`🔹 '${cli.name}' is not installed. Auto-installing...`));
     console.log(chalk.dim(`$ ${cmd}`));
     try {
-        execSync(cmd, { stdio: 'inherit' });
+        runInstallCommand(cmd);
         console.log(chalk.green(`✅ Installed '${cli.name}' successfully.\n`));
         return true;
     }

package/dist/external.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/external.test.js

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { mockExecFileSync, mockPlatform } = vi.hoisted(() => ({
+    mockExecFileSync: vi.fn(),
+    mockPlatform: vi.fn(() => 'darwin'),
+}));
+vi.mock('node:child_process', () => ({
+    spawnSync: vi.fn(),
+    execFileSync: mockExecFileSync,
+}));
+vi.mock('node:os', async () => {
+    const actual = await vi.importActual('node:os');
+    return {
+        ...actual,
+        platform: mockPlatform,
+    };
+});
+import { installExternalCli, parseCommand } from './external.js';
+describe('parseCommand', () => {
+    it('splits binaries and quoted arguments without invoking a shell', () => {
+        expect(parseCommand('npm install -g "@scope/tool name"')).toEqual({
+            binary: 'npm',
+            args: ['install', '-g', '@scope/tool name'],
+        });
+    });
+    it('rejects shell operators', () => {
+        expect(() => parseCommand('brew install gh && rm -rf /')).toThrow('Install command contains unsafe shell operators');
+    });
+});
+describe('installExternalCli', () => {
+    const cli = {
+        name: 'readwise',
+        binary: 'readwise',
+        install: {
+            default: 'npm install -g @readwiseio/readwise-cli',
+        },
+    };
+    beforeEach(() => {
+        mockExecFileSync.mockReset();
+        mockPlatform.mockReturnValue('darwin');
+    });
+    it('retries with .cmd on Windows when the bare binary is unavailable', () => {
+        mockPlatform.mockReturnValue('win32');
+        mockExecFileSync
+            .mockImplementationOnce(() => {
+            const err = new Error('not found');
+            err.code = 'ENOENT';
+            throw err;
+        })
+            .mockReturnValueOnce(Buffer.from(''));
+        expect(installExternalCli(cli)).toBe(true);
+        expect(mockExecFileSync).toHaveBeenNthCalledWith(1, 'npm', ['install', '-g', '@readwiseio/readwise-cli'], { stdio: 'inherit' });
+        expect(mockExecFileSync).toHaveBeenNthCalledWith(2, 'npm.cmd', ['install', '-g', '@readwiseio/readwise-cli'], { stdio: 'inherit' });
+    });
+    it('does not mask non-ENOENT failures', () => {
+        mockPlatform.mockReturnValue('win32');
+        mockExecFileSync.mockImplementationOnce(() => {
+            const err = new Error('permission denied');
+            err.code = 'EACCES';
+            throw err;
+        });
+        expect(installExternalCli(cli)).toBe(false);
+        expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/main.js

@@ -2,6 +2,16 @@
 /**
  * opencli — Make any website your CLI. AI-powered.
  */
+// Ensure standard system paths are available for child processes.
+// Some environments (GUI apps, cron, IDE terminals) launch with a minimal PATH
+// that excludes /usr/local/bin, /usr/sbin, etc., causing external CLIs to fail.
+if (process.platform !== 'win32') {
+    const std = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+    const cur = new Set((process.env.PATH ?? '').split(':').filter(Boolean));
+    for (const p of std)
+        cur.add(p);
+    process.env.PATH = [...cur].join(':');
+}
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';

package/dist/plugin.d.ts

@@ -19,6 +19,10 @@ export declare function installPlugin(source: string): string;
  * Uninstall a plugin by name.
  */
 export declare function uninstallPlugin(name: string): void;
+/**
+ * Update a plugin by name (git pull + re-install lifecycle).
+ */
+export declare function updatePlugin(name: string): void;
 /**
  * List all installed plugins.
  */

package/dist/plugin.js

@@ -9,6 +9,30 @@ import * as path from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 import { PLUGINS_DIR } from './discovery.js';
 import { log } from './logger.js';
+/**
+ * Shared post-install lifecycle: npm install → host symlink → TS transpile.
+ * Called by both installPlugin() and updatePlugin().
+ */
+function postInstallLifecycle(pluginDir) {
+    const pkgJsonPath = path.join(pluginDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return;
+    try {
+        execFileSync('npm', ['install', '--omit=dev'], {
+            cwd: pluginDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        // Non-fatal: npm install may fail if no real deps
+    }
+    // Symlink host opencli so TS plugins resolve '@jackwener/opencli/registry'
+    // against the running host, not a stale npm-published version.
+    linkHostOpencli(pluginDir);
+    // Transpile .ts → .js via esbuild (production node can't load .ts directly).
+    transpilePluginTs(pluginDir);
+}
 /**
  * Install a plugin from a source.
  * Currently supports "github:user/repo" format (git clone wrapper).
@@ -37,29 +61,7 @@ export function installPlugin(source) {
     catch (err) {
         throw new Error(`Failed to clone plugin: ${err.message}`);
     }
-    // If the plugin has a package.json, run npm install for regular deps,
-    // then symlink the host opencli into node_modules for peerDep resolution.
-    const pkgJsonPath = path.join(targetDir, 'package.json');
-    if (fs.existsSync(pkgJsonPath)) {
-        try {
-            execFileSync('npm', ['install', '--omit=dev'], {
-                cwd: targetDir,
-                encoding: 'utf-8',
-                stdio: ['pipe', 'pipe', 'pipe'],
-            });
-        }
-        catch {
-            // Non-fatal: npm install may fail if no real deps
-        }
-        // Symlink host opencli into plugin's node_modules so TS plugins
-        // can resolve '@jackwener/opencli/registry' against the running host.
-        // This is more reliable than depending on the npm-published version
-        // which may lag behind the local installation.
-        linkHostOpencli(targetDir);
-        // Transpile TS plugin files to JS so they work in production mode
-        // (node cannot load .ts files directly without tsx).
-        transpilePluginTs(targetDir);
-    }
+    postInstallLifecycle(targetDir);
     return name;
 }
 /**
@@ -72,6 +74,26 @@ export function uninstallPlugin(name) {
     }
     fs.rmSync(targetDir, { recursive: true, force: true });
 }
+/**
+ * Update a plugin by name (git pull + re-install lifecycle).
+ */
+export function updatePlugin(name) {
+    const targetDir = path.join(PLUGINS_DIR, name);
+    if (!fs.existsSync(targetDir)) {
+        throw new Error(`Plugin "${name}" is not installed.`);
+    }
+    try {
+        execFileSync('git', ['pull', '--ff-only'], {
+            cwd: targetDir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        throw new Error(`Failed to update plugin: ${err.message}`);
+    }
+    postInstallLifecycle(targetDir);
+}
 /**
  * List all installed plugins.
  */

package/dist/plugin.test.js

@@ -5,7 +5,7 @@ import { describe, it, expect, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { PLUGINS_DIR } from './discovery.js';
-import { listPlugins, uninstallPlugin, _parseSource } from './plugin.js';
+import { listPlugins, uninstallPlugin, updatePlugin, _parseSource } from './plugin.js';
 describe('parseSource', () => {
     it('parses github:user/repo format', () => {
         const result = _parseSource('github:ByteYue/opencli-plugin-github-trending');
@@ -74,3 +74,8 @@ describe('uninstallPlugin', () => {
         expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
     });
 });
+describe('updatePlugin', () => {
+    it('throws for non-existent plugin', () => {
+        expect(() => updatePlugin('__nonexistent__')).toThrow('not installed');
+    });
+});

package/dist/record.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Record mode — capture API calls from a live browser session.
+ *
+ * Flow:
+ *   1. Navigate to the target URL in an automation tab
+ *   2. Inject a full-capture fetch/XHR interceptor (records url + method + body)
+ *   3. Poll every 2s and print newly captured requests
+ *   4. User operates the page; press Enter to stop
+ *   5. Analyze captured requests → infer capabilities → write YAML candidates
+ *
+ * Design: no new daemon endpoints, no extension changes.
+ * Uses existing exec + navigate actions only.
+ */
+import type { IPage } from './types.js';
+export interface RecordedRequest {
+    url: string;
+    method: string;
+    status: number | null;
+    contentType: string;
+    body: unknown;
+    capturedAt: number;
+}
+export interface RecordResult {
+    site: string;
+    url: string;
+    requests: RecordedRequest[];
+    outDir: string;
+    candidateCount: number;
+    candidates: Array<{
+        name: string;
+        path: string;
+        strategy: string;
+    }>;
+}
+export interface RecordOptions {
+    BrowserFactory: new () => {
+        connect(o?: unknown): Promise<IPage>;
+        close(): Promise<void>;
+    };
+    site?: string;
+    url: string;
+    outDir?: string;
+    pollMs?: number;
+    timeoutMs?: number;
+}
+export declare function recordSession(opts: RecordOptions): Promise<RecordResult>;
+export declare function renderRecordSummary(result: RecordResult): string;