@jackwener/opencli 1.3.2 → 1.4.0

package/dist/download/index.test.js

@@ -1,5 +1,26 @@
-import { describe, expect, it } from 'vitest';
-import { formatCookieHeader, resolveRedirectUrl } from './index.js';
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { formatCookieHeader, httpDownload, resolveRedirectUrl } from './index.js';
+const servers = [];
+afterEach(async () => {
+    await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    })));
+    servers.length = 0;
+});
+async function startServer(handler, hostname = '127.0.0.1') {
+    const server = http.createServer(handler);
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, hostname, resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to start test server');
+    }
+    return `http://${hostname}:${address.port}`;
+}
 describe('download helpers', () => {
     it('resolves relative redirects against the original URL', () => {
         expect(resolveRedirectUrl('https://example.com/a/file', '/cdn/file.bin')).toBe('https://example.com/cdn/file.bin');
@@ -11,4 +32,60 @@ describe('download helpers', () => {
             { name: 'ct0', value: 'def', domain: 'example.com' },
         ])).toBe('sid=abc; ct0=def');
     });
+    it('fails after exceeding the redirect limit', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', '/loop');
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'file.txt');
+        const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
+        expect(result).toEqual({
+            success: false,
+            size: 0,
+            error: 'Too many redirects (> 2)',
+        });
+        expect(fs.existsSync(destPath)).toBe(false);
+    });
+    it('does not forward cookies across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'redirect.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, { cookies: 'sid=abc' });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
+    it('does not forward cookie headers across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const destPath = path.join(tempDir, 'redirect-header.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, {
+            headers: { Cookie: 'sid=header-cookie' },
+        });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
 });

package/dist/download/media-download.js

@@ -8,6 +8,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { getErrorMessage } from '../errors.js';
 import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, } from './index.js';
 import { DownloadProgressTracker, formatBytes } from './progress.js';
 // ============================================================
@@ -89,14 +90,15 @@ export async function downloadMedia(items, options) {
                 });
             }
             catch (err) {
+                const msg = getErrorMessage(err);
                 if (progressBar)
-                    progressBar.fail(err.message);
+                    progressBar.fail(msg);
                 tracker.onFileComplete(false);
                 results.push({
                     index: i + 1,
                     type: media.type,
                     status: 'failed',
-                    size: err.message,
+                    size: msg,
                 });
             }
         }

package/dist/engine.test.js

@@ -1,16 +1,19 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { discoverClis, discoverPlugins, PLUGINS_DIR } from './discovery.js';
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
+import { clearAllHooks, onAfterExecute } from './hooks.js';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
 describe('discoverClis', () => {
     it('handles non-existent directories gracefully', async () => {
         // Should not throw for missing directories
-        await expect(discoverClis('/tmp/nonexistent-opencli-test-dir')).resolves.not.toThrow();
+        await expect(discoverClis(path.join(os.tmpdir(), 'nonexistent-opencli-test-dir'))).resolves.not.toThrow();
     });
     it('imports only CLI command modules during filesystem discovery', async () => {
-        const tempRoot = await fs.promises.mkdtemp(path.join('/tmp', 'opencli-discovery-'));
+        const tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-discovery-'));
         const siteDir = path.join(tempRoot, 'temp-site');
         const helperPath = path.join(siteDir, 'helper.ts');
         const commandPath = path.join(siteDir, 'hello.ts');
@@ -21,7 +24,7 @@ globalThis.__opencli_helper_loaded__ = true;
 export const helper = true;
 `);
             await fs.promises.writeFile(commandPath, `
-import { cli, Strategy } from '${path.join(process.cwd(), 'src', 'registry.ts')}';
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'temp-site',
   name: 'hello',
@@ -41,6 +44,33 @@ cli({
             await fs.promises.rm(tempRoot, { recursive: true, force: true });
         }
     });
+    it('falls back to filesystem discovery when the manifest is invalid', async () => {
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-manifest-fallback-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, 'fallback-site');
+        const commandPath = path.join(siteDir, 'hello.ts');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, '{ invalid json');
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: 'fallback-site',
+  name: 'hello',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            expect(getRegistry().get('fallback-site/hello')).toBeDefined();
+        }
+        finally {
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
 });
 describe('discoverPlugins', () => {
     const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
@@ -80,6 +110,10 @@ columns: [message]
     });
 });
 describe('executeCommand', () => {
+    beforeEach(() => {
+        clearAllHooks();
+        vi.unstubAllEnvs();
+    });
     it('accepts kebab-case option names after Commander camelCases them', async () => {
         const cmd = cli({
             site: 'test-engine',
@@ -148,4 +182,42 @@ describe('executeCommand', () => {
         await executeCommand(cmd, {}, true);
         expect(receivedDebug).toBe(true);
     });
+    it('fires onAfterExecute even when command execution throws', async () => {
+        const seen = [];
+        onAfterExecute((ctx) => {
+            seen.push({ error: ctx.error, finishedAt: ctx.finishedAt });
+        });
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'failing-test',
+            description: 'failing command',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            func: async () => {
+                throw new Error('boom');
+            },
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('boom');
+        expect(seen).toHaveLength(1);
+        expect(seen[0].error).toBeInstanceOf(Error);
+        expect(seen[0].error.message).toBe('boom');
+        expect(typeof seen[0].finishedAt).toBe('number');
+    });
+    it('fails fast for chatwise commands when OPENCLI_CDP_ENDPOINT is missing', async () => {
+        const cmd = cli({
+            site: 'chatwise',
+            name: 'status',
+            description: 'chatwise status',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            requiredEnv: [
+                {
+                    name: 'OPENCLI_CDP_ENDPOINT',
+                    help: 'Set OPENCLI_CDP_ENDPOINT before running chatwise commands.',
+                },
+            ],
+            func: async () => [{ ok: true }],
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('requires environment variable OPENCLI_CDP_ENDPOINT');
+    });
 });

package/dist/execution.d.ts

@@ -7,18 +7,10 @@
  * 3. Domain pre-navigation for cookie/header strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { type CliCommand, type Arg } from './registry.js';
 type CommandArgs = Record<string, unknown>;
-/**
- * Validates and coerces arguments based on the command's Arg definitions.
- */
 export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
-/**
- * Execute a CLI command. Automatically manages browser sessions when needed.
- *
- * This is the unified entry point — callers don't need to care about
- * whether the command requires a browser or not.
- */
 export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean): Promise<unknown>;
 export {};

package/dist/execution.js

@@ -7,6 +7,7 @@
  * 3. Domain pre-navigation for cookie/header strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { Strategy, getRegistry, fullName } from './registry.js';
 import { pathToFileURL } from 'node:url';
@@ -14,21 +15,16 @@ import { executePipeline } from './pipeline/index.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 */
+import { emitHook } from './hooks.js';
 const _loadedModules = new Set();
-/**
- * Validates and coerces arguments based on the command's Arg definitions.
- */
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
     for (const argDef of cmdArgs) {
         const val = result[argDef.name];
-        // 1. Check required
         if (argDef.required && (val === undefined || val === null || val === '')) {
             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)) {
@@ -50,7 +46,6 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
                     result[argDef.name] = Boolean(val);
                 }
             }
-            // 3. Choices validation
             const coercedVal = result[argDef.name];
             if (argDef.choices && argDef.choices.length > 0) {
                 if (!argDef.choices.map(String).includes(String(coercedVal))) {
@@ -64,11 +59,7 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
     }
     return result;
 }
-/**
- * Run a command's func or pipeline against a page.
- */
 async function runCommand(cmd, page, kwargs, debug) {
-    // Lazy-load TS module on first execution (manifest fast-path)
     const internal = cmd;
     if (internal._lazy && internal._modulePath) {
         const modulePath = internal._modulePath;
@@ -81,10 +72,13 @@ async function runCommand(cmd, page, kwargs, debug) {
                 throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
             }
         }
-        // After loading, the module's cli() call will have updated the registry.
         const updated = getRegistry().get(fullName(cmd));
-        if (updated?.func)
+        if (updated?.func) {
+            if (!page && updated.browser !== false) {
+                throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
+            }
             return updated.func(page, kwargs, debug);
+        }
         if (updated?.pipeline)
             return executePipeline(page, updated.pipeline, { args: kwargs, debug });
     }
@@ -94,30 +88,25 @@ async function runCommand(cmd, page, kwargs, debug) {
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     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.
- *
- * COOKIE/HEADER strategies need the browser on the target domain so
- * `fetch(url, { credentials: 'include' })` carries cookies.
- * Adapters that handle their own navigation set `navigateBefore: false`.
- */
 function resolvePreNav(cmd) {
     if (cmd.navigateBefore === false)
         return null;
     if (typeof cmd.navigateBefore === 'string')
         return cmd.navigateBefore;
-    // Default: pre-navigate for COOKIE/HEADER strategies with a domain
     if ((cmd.strategy === Strategy.COOKIE || cmd.strategy === Strategy.HEADER) && cmd.domain) {
         return `https://${cmd.domain}`;
     }
     return null;
 }
-/**
- * Execute a CLI command. Automatically manages browser sessions when needed.
- *
- * This is the unified entry point — callers don't need to care about
- * whether the command requires a browser or not.
- */
+function ensureRequiredEnv(cmd) {
+    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
+        const value = process.env[name];
+        return value === undefined || value === null || value === '';
+    });
+    if (!missing)
+        return;
+    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+}
 export async function executeCommand(cmd, rawKwargs, debug = false) {
     let kwargs;
     try {
@@ -128,25 +117,46 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             throw err;
         throw new ArgumentError(getErrorMessage(err));
     }
-    if (shouldUseBrowserSession(cmd)) {
-        const BrowserFactory = getBrowserFactory();
-        return browserSession(BrowserFactory, async (page) => {
-            // Pre-navigate to target domain for cookie/header context if needed.
-            // Each adapter controls this via `navigateBefore` (see CliCommand docs).
-            const preNavUrl = resolvePreNav(cmd);
-            if (preNavUrl) {
-                try {
-                    await page.goto(preNavUrl);
-                    await page.wait(2);
+    const hookCtx = {
+        command: fullName(cmd),
+        args: kwargs,
+        startedAt: Date.now(),
+    };
+    await emitHook('onBeforeExecute', hookCtx);
+    let result;
+    try {
+        if (shouldUseBrowserSession(cmd)) {
+            ensureRequiredEnv(cmd);
+            const BrowserFactory = getBrowserFactory();
+            result = await browserSession(BrowserFactory, async (page) => {
+                const preNavUrl = resolvePreNav(cmd);
+                if (preNavUrl) {
+                    try {
+                        await page.goto(preNavUrl);
+                        await page.wait(2);
+                    }
+                    catch (err) {
+                        if (debug)
+                            console.error(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
+                    }
                 }
-                catch { }
-            }
-            return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
-                label: fullName(cmd),
-            });
-        }, { workspace: `site:${cmd.site}` });
+                return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                    timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                    label: fullName(cmd),
+                });
+            }, { workspace: `site:${cmd.site}` });
+        }
+        else {
+            result = await runCommand(cmd, null, kwargs, debug);
+        }
     }
-    // Non-browser commands run directly
-    return runCommand(cmd, null, kwargs, debug);
+    catch (err) {
+        hookCtx.error = err;
+        hookCtx.finishedAt = Date.now();
+        await emitHook('onAfterExecute', hookCtx);
+        throw err;
+    }
+    hookCtx.finishedAt = Date.now();
+    await emitHook('onAfterExecute', hookCtx, result);
+    return result;
 }

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

@@ -22,14 +22,6 @@
   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"

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;
     }
 }