@jackwener/opencli 1.3.3 → 1.4.1

package/dist/explore.js

@@ -8,11 +8,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { DEFAULT_BROWSER_EXPLORE_TIMEOUT, browserSession, runWithTimeout } from './runtime.js';
-import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_ROLES } from './constants.js';
+import { LIMIT_PARAMS } from './constants.js';
 import { detectFramework } from './scripts/framework.js';
 import { discoverStores } from './scripts/store.js';
 import { interactFuzz } from './scripts/interact.js';
 import { log } from './logger.js';
+import { urlToPattern, findArrayPath, flattenFields, detectFieldRoles, inferCapabilityName, inferStrategy, detectAuthFromHeaders, classifyQueryParams, } from './analysis.js';
 // ── Site name detection ────────────────────────────────────────────────────
 const KNOWN_SITE_ALIASES = {
     'x.com': 'twitter', 'twitter.com': 'twitter',
@@ -75,78 +76,16 @@ function parseNetworkRequests(raw) {
     }
     return [];
 }
-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(headers) {
-    if (!headers)
-        return [];
-    const indicators = [];
-    const keys = Object.keys(headers).map(k => k.toLowerCase());
-    if (keys.some(k => k === 'authorization'))
-        indicators.push('bearer');
-    if (keys.some(k => k.startsWith('x-csrf') || k.startsWith('x-xsrf')))
-        indicators.push('csrf');
-    if (keys.some(k => k.startsWith('x-s') || k === 'x-t' || k === 'x-s-common'))
-        indicators.push('signature');
-    return indicators;
-}
 function analyzeResponseBody(body) {
     if (!body || typeof body !== 'object')
         return null;
-    const candidates = [];
-    function findArrays(obj, path, depth) {
-        if (depth > 4)
-            return;
-        if (Array.isArray(obj) && obj.length >= 2 && obj.some(item => item && typeof item === 'object' && !Array.isArray(item))) {
-            candidates.push({ path, items: obj });
-        }
-        if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
-            for (const [key, val] of Object.entries(obj))
-                findArrays(val, path ? `${path}.${key}` : key, depth + 1);
-        }
-    }
-    findArrays(body, '', 0);
-    if (!candidates.length)
+    const result = findArrayPath(body);
+    if (!result)
         return null;
-    candidates.sort((a, b) => b.items.length - a.items.length);
-    const best = candidates[0];
-    const sample = best.items[0];
+    const sample = result.items[0];
     const sampleFields = sample && typeof sample === 'object' ? flattenFields(sample, '', 2) : [];
-    const detectedFields = {};
-    for (const [role, aliases] of Object.entries(FIELD_ROLES)) {
-        for (const f of sampleFields) {
-            if (aliases.includes(f.split('.').pop()?.toLowerCase() ?? '')) {
-                detectedFields[role] = f;
-                break;
-            }
-        }
-    }
-    return { itemPath: best.path || null, itemCount: best.items.length, detectedFields, sampleFields };
-}
-function flattenFields(obj, prefix, maxDepth) {
-    if (maxDepth <= 0 || !obj || typeof obj !== 'object')
-        return [];
-    const names = [];
-    const record = obj;
-    for (const key of Object.keys(record)) {
-        const full = prefix ? `${prefix}.${key}` : key;
-        names.push(full);
-        const val = record[key];
-        if (val && typeof val === 'object' && !Array.isArray(val))
-            names.push(...flattenFields(val, full, maxDepth - 1));
-    }
-    return names;
+    const detectedFields = detectFieldRoles(sampleFields);
+    return { itemPath: result.path || null, itemCount: result.items.length, detectedFields, sampleFields };
 }
 function isBooleanRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
@@ -176,39 +115,6 @@ function scoreEndpoint(ep) {
         s -= 3;
     return s;
 }
-function inferCapabilityName(url, goal) {
-    if (goal)
-        return goal;
-    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('userinfo') || 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));
-        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';
-}
 // ── Framework detection ────────────────────────────────────────────────────
 const FRAMEWORK_DETECT_JS = detectFramework.toString();
 // ── Store discovery ────────────────────────────────────────────────────────
@@ -231,18 +137,13 @@ function analyzeEndpoints(networkEntries) {
         const key = `${entry.method}:${pattern}`;
         if (seen.has(key))
             continue;
-        const qp = [];
-        try {
-            new URL(entry.url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
-                qp.push(k); });
-        }
-        catch { }
+        const { params: qp, hasSearch, hasPagination, hasLimit } = classifyQueryParams(entry.url);
         const ep = {
             pattern, method: entry.method, url: entry.url, status: entry.status, contentType: ct,
-            queryParams: qp, hasSearchParam: qp.some(p => SEARCH_PARAMS.has(p)),
-            hasPaginationParam: qp.some(p => PAGINATION_PARAMS.has(p)),
-            hasLimitParam: qp.some(p => LIMIT_PARAMS.has(p)),
-            authIndicators: detectAuthIndicators(entry.requestHeaders),
+            queryParams: qp, hasSearchParam: hasSearch,
+            hasPaginationParam: hasPagination,
+            hasLimitParam: hasLimit || qp.some(p => LIMIT_PARAMS.has(p)),
+            authIndicators: detectAuthFromHeaders(entry.requestHeaders),
             responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
             score: 0,
         };

package/dist/external-clis.yaml

@@ -14,22 +14,6 @@
   install:
     mac: "brew install --cask obsidian"
 
-- name: readwise
-  binary: readwise
-  description: "Readwise & Reader CLI — highlights, annotations, reading list"
-  homepage: "https://github.com/readwiseio/readwise-cli"
-  tags: [reading, highlights]
-  install:
-    default: "npm install -g @readwiseio/readwise-cli"
-
-- name: kubectl
-  binary: kubectl
-  description: "Kubernetes command-line tool"
-  homepage: "https://kubernetes.io/docs/reference/kubectl/"
-  tags: [kubernetes, k8s, devops]
-  install:
-    mac: "brew install kubectl"
-
 - name: docker
   binary: docker
   description: "Docker command-line interface"
@@ -37,12 +21,3 @@
   tags: [docker, containers, devops]
   install:
     mac: "brew install --cask docker"
-
-- name: gws
-  binary: gws
-  description: "Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar"
-  homepage: "https://github.com/nicholasgasior/gws"
-  tags: [google, docs, sheets, drive, workspace]
-  install:
-    mac: "brew install gws"
-    default: "npm install -g @nicholasgasior/gws"

package/dist/external.js

@@ -6,6 +6,7 @@ import { spawnSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
+import { getErrorMessage } from './errors.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function getUserRegistryPath() {
     const home = os.homedir();
@@ -24,7 +25,7 @@ export function loadExternalClis() {
         }
     }
     catch (err) {
-        log.warn(`Failed to parse built-in external-clis.yaml: ${err.message}`);
+        log.warn(`Failed to parse built-in external-clis.yaml: ${getErrorMessage(err)}`);
     }
     // 2. Load user custom
     const userPath = getUserRegistryPath();
@@ -38,7 +39,7 @@ export function loadExternalClis() {
         }
     }
     catch (err) {
-        log.warn(`Failed to parse user external-clis.yaml: ${err.message}`);
+        log.warn(`Failed to parse user external-clis.yaml: ${getErrorMessage(err)}`);
     }
     return Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -78,7 +79,7 @@ export function getInstallCmd(installConfig) {
  *   Object with `binary` and `args` fields, or throws on unsafe input.
  */
 export function parseCommand(cmd) {
-    const shellOperators = /&&|\|\|?|;|[><`]/;
+    const shellOperators = /&&|\|\|?|;|[><`$#\n\r]|\$\(/;
     if (shellOperators.test(cmd)) {
         throw new Error(`Install command contains unsafe shell operators and cannot be executed securely: "${cmd}". ` +
             `Please install the tool manually.`);
@@ -97,7 +98,8 @@ export function parseCommand(cmd) {
     return { binary, args };
 }
 function shouldRetryWithCmdShim(binary, err) {
-    return os.platform() === 'win32' && !path.extname(binary) && err.code === 'ENOENT';
+    const code = err instanceof Error ? err.code : undefined;
+    return os.platform() === 'win32' && !path.extname(binary) && code === 'ENOENT';
 }
 function runInstallCommand(cmd) {
     const { binary, args } = parseCommand(cmd);
@@ -133,7 +135,7 @@ export function installExternalCli(cli) {
         return true;
     }
     catch (err) {
-        console.error(chalk.red(`❌ Failed to install '${cli.name}': ${err.message}`));
+        console.error(chalk.red(`❌ Failed to install '${cli.name}': ${getErrorMessage(err)}`));
         return false;
     }
 }

package/dist/external.test.js

@@ -25,6 +25,10 @@ describe('parseCommand', () => {
     it('rejects shell operators', () => {
         expect(() => parseCommand('brew install gh && rm -rf /')).toThrow('Install command contains unsafe shell operators');
     });
+    it('rejects command substitution and multiline input', () => {
+        expect(() => parseCommand('brew install $(whoami)')).toThrow('Install command contains unsafe shell operators');
+        expect(() => parseCommand('brew install gh\nrm -rf /')).toThrow('Install command contains unsafe shell operators');
+    });
 });
 describe('installExternalCli', () => {
     const cli = {

package/dist/generate.d.ts

@@ -9,20 +9,13 @@
  */
 import type { IBrowserFactory } from './runtime.js';
 import { type SynthesizeCandidateSummary } from './synthesize.js';
-interface RegisterCandidatesResult {
-    ok: boolean;
-    count: number;
-}
 export interface GenerateCliOptions {
     url: string;
     BrowserFactory: new () => IBrowserFactory;
-    builtinClis?: string;
-    userClis?: string;
     goal?: string | null;
     site?: string;
     waitSeconds?: number;
     top?: number;
-    register?: boolean;
     workspace?: string;
 }
 export interface GenerateCliResult {
@@ -43,8 +36,6 @@ export interface GenerateCliResult {
         candidate_count: number;
         candidates: Array<Pick<SynthesizeCandidateSummary, 'name' | 'strategy' | 'confidence'>>;
     };
-    register: RegisterCandidatesResult | null;
 }
 export declare function generateCliFromUrl(opts: GenerateCliOptions): Promise<GenerateCliResult>;
 export declare function renderGenerateSummary(r: GenerateCliResult): string;
-export {};

package/dist/generate.js

@@ -9,9 +9,6 @@
  */
 import { exploreUrl } from './explore.js';
 import { synthesizeFromExplore } from './synthesize.js';
-function registerCandidates(_opts) {
-    return { ok: true, count: 0 };
-}
 const CAPABILITY_ALIASES = {
     search: ['search', '搜索', '查找', 'query', 'keyword'],
     hot: ['hot', '热门', '热榜', '热搜', 'popular', 'top', 'ranking'],
@@ -51,7 +48,10 @@ function selectCandidate(candidates, goal) {
             return exact;
     }
     const lower = (goal ?? '').trim().toLowerCase();
-    const partial = candidates.find(c => c.name?.toLowerCase().includes(lower) || lower.includes(c.name?.toLowerCase()));
+    const partial = candidates.find(c => {
+        const cName = c.name?.toLowerCase() ?? '';
+        return cName.includes(lower) || lower.includes(cName);
+    });
     return partial ?? candidates[0];
 }
 export async function generateCliFromUrl(opts) {
@@ -70,19 +70,6 @@ export async function generateCliFromUrl(opts) {
     // Step 3: Select best candidate for goal
     const selected = selectCandidate(synthesizeResult.candidates ?? [], opts.goal);
     const selectedSite = synthesizeResult.site ?? exploreResult.site;
-    // Step 4: Register (if requested)
-    let registerResult = null;
-    if (opts.register !== false && synthesizeResult.candidate_count > 0) {
-        try {
-            registerResult = registerCandidates({
-                target: synthesizeResult.out_dir,
-                builtinClis: opts.builtinClis,
-                userClis: opts.userClis,
-                name: selected?.name,
-            });
-        }
-        catch { }
-    }
     const ok = exploreResult.endpoint_count > 0 && synthesizeResult.candidate_count > 0;
     return {
         ok,
@@ -106,7 +93,6 @@ export async function generateCliFromUrl(opts) {
                 confidence: c.confidence,
             })),
         },
-        register: registerResult,
     };
 }
 export function renderGenerateSummary(r) {
@@ -127,8 +113,6 @@ export function renderGenerateSummary(r) {
     for (const c of r.synthesize?.candidates ?? []) {
         lines.push(`    • ${c.name} (${c.strategy}, ${((c.confidence ?? 0) * 100).toFixed(0)}%)`);
     }
-    if (r.register)
-        lines.push(`\nRegistered: ${r.register.count ?? 0}`);
     const fw = r.explore?.framework ?? {};
     const fwNames = Object.entries(fw).filter(([, v]) => v).map(([k]) => k);
     if (fwNames.length)

package/dist/hooks.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+export type HookName = 'onStartup' | 'onBeforeExecute' | 'onAfterExecute';
+export interface HookContext {
+    /** Command full name in "site/name" format, or "__startup__" for onStartup */
+    command: string;
+    /** Coerced and validated arguments */
+    args: Record<string, unknown>;
+    /** Epoch ms when execution started (set by executeCommand) */
+    startedAt?: number;
+    /** Epoch ms when execution finished (set by executeCommand) */
+    finishedAt?: number;
+    /** Error thrown by the command, if execution failed */
+    error?: unknown;
+    /** Plugins can attach arbitrary data here for cross-hook communication */
+    [key: string]: unknown;
+}
+export type HookFn = (ctx: HookContext, result?: unknown) => void | Promise<void>;
+declare global {
+    var __opencli_hooks__: Map<HookName, HookFn[]> | undefined;
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export declare function onStartup(fn: HookFn): void;
+/** Register a hook that fires before every command execution. */
+export declare function onBeforeExecute(fn: HookFn): void;
+/** Register a hook that fires after every command execution with the result. */
+export declare function onAfterExecute(fn: HookFn): void;
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export declare function emitHook(name: HookName, ctx: HookContext, result?: unknown): Promise<void>;
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export declare function clearAllHooks(): void;

package/dist/hooks.js

@@ -0,0 +1,56 @@
+/**
+ * Plugin lifecycle hooks: allows plugins to tap into opencli's execution lifecycle.
+ *
+ * Hooks use globalThis (like the command registry) to guarantee a single shared
+ * instance across all module copies — critical when TS plugins are loaded via
+ * npm link / peerDependency symlinks.
+ *
+ * Available hooks:
+ *   onStartup        — fired once after all commands & plugins are discovered
+ *   onBeforeExecute  — fired before every command execution
+ *   onAfterExecute   — fired after every command execution (receives result)
+ */
+import { log } from './logger.js';
+const _hooks = globalThis.__opencli_hooks__ ??= new Map();
+// ── Registration API (used by plugins) ─────────────────────────────────────
+function addHook(name, fn) {
+    const list = _hooks.get(name) ?? [];
+    list.push(fn);
+    _hooks.set(name, list);
+}
+/** Register a hook that fires once after all plugins are discovered. */
+export function onStartup(fn) {
+    addHook('onStartup', fn);
+}
+/** Register a hook that fires before every command execution. */
+export function onBeforeExecute(fn) {
+    addHook('onBeforeExecute', fn);
+}
+/** Register a hook that fires after every command execution with the result. */
+export function onAfterExecute(fn) {
+    addHook('onAfterExecute', fn);
+}
+// ── Emit API (used internally by opencli core) ─────────────────────────────
+/**
+ * Trigger all registered handlers for a hook.
+ * Each handler is wrapped in try/catch — a failing hook never blocks command execution.
+ */
+export async function emitHook(name, ctx, result) {
+    const handlers = _hooks.get(name);
+    if (!handlers || handlers.length === 0)
+        return;
+    for (const fn of handlers) {
+        try {
+            await fn(ctx, result);
+        }
+        catch (err) {
+            log.warn(`Hook ${name} handler failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/**
+ * Remove all registered hooks. Intended for testing only.
+ */
+export function clearAllHooks() {
+    _hooks.clear();
+}

package/dist/hooks.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+export {};

package/dist/hooks.test.js

@@ -0,0 +1,92 @@
+/**
+ * Tests for the plugin lifecycle hooks system.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { onStartup, onBeforeExecute, onAfterExecute, emitHook, clearAllHooks, } from './hooks.js';
+beforeEach(() => {
+    clearAllHooks();
+});
+describe('hook registration and emission', () => {
+    it('onBeforeExecute hook is called with context', async () => {
+        const calls = [];
+        onBeforeExecute((ctx) => { calls.push({ ...ctx }); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: { limit: 5 }, startedAt: 100 });
+        expect(calls).toHaveLength(1);
+        expect(calls[0].command).toBe('test/cmd');
+        expect(calls[0].args).toEqual({ limit: 5 });
+        expect(calls[0].startedAt).toBe(100);
+    });
+    it('onAfterExecute hook receives result', async () => {
+        const results = [];
+        onAfterExecute((_ctx, result) => { results.push(result); });
+        const mockResult = [{ title: 'item1' }, { title: 'item2' }];
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, mockResult);
+        expect(results).toHaveLength(1);
+        expect(results[0]).toEqual(mockResult);
+    });
+    it('onStartup hook fires', async () => {
+        let fired = false;
+        onStartup(() => { fired = true; });
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(fired).toBe(true);
+    });
+    it('multiple hooks on the same event fire in order', async () => {
+        const order = [];
+        onBeforeExecute(() => { order.push(1); });
+        onBeforeExecute(() => { order.push(2); });
+        onBeforeExecute(() => { order.push(3); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual([1, 2, 3]);
+    });
+    it('async hooks are awaited', async () => {
+        const order = [];
+        onBeforeExecute(async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            order.push('async-done');
+        });
+        onBeforeExecute(() => { order.push('sync'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        expect(order).toEqual(['async-done', 'sync']);
+    });
+});
+describe('hook error isolation', () => {
+    it('failing hook does not prevent other hooks from running', async () => {
+        const calls = [];
+        onBeforeExecute(() => { calls.push('first'); });
+        onBeforeExecute(() => { throw new Error('boom'); });
+        onBeforeExecute(() => { calls.push('third'); });
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        // First and third should still run despite the second throwing
+        expect(calls).toEqual(['first', 'third']);
+    });
+    it('async hook rejection does not prevent other hooks', async () => {
+        const calls = [];
+        onAfterExecute(() => { calls.push('before-reject'); });
+        onAfterExecute(async () => { throw new Error('async boom'); });
+        onAfterExecute(() => { calls.push('after-reject'); });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, null);
+        expect(calls).toEqual(['before-reject', 'after-reject']);
+    });
+});
+describe('no-op when no hooks registered', () => {
+    it('emitHook with no registered hooks does nothing', async () => {
+        // Should not throw
+        await emitHook('onBeforeExecute', { command: 'test/cmd', args: {} });
+        await emitHook('onAfterExecute', { command: 'test/cmd', args: {} }, []);
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+    });
+});
+describe('clearAllHooks', () => {
+    it('removes all hooks', async () => {
+        let called = false;
+        onStartup(() => { called = true; });
+        clearAllHooks();
+        await emitHook('onStartup', { command: '__startup__', args: {} });
+        expect(called).toBe(false);
+    });
+});
+describe('globalThis singleton', () => {
+    it('uses globalThis.__opencli_hooks__ for shared state', () => {
+        expect(globalThis.__opencli_hooks__).toBeInstanceOf(Map);
+    });
+});