@jackwener/opencli 1.1.0 → 1.2.0

package/dist/execution.js

@@ -0,0 +1,153 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie/header strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ */
+import { Strategy, getRegistry, fullName } from './registry.js';
+import { pathToFileURL } from 'node:url';
+import { executePipeline } from './pipeline/index.js';
+import { AdapterLoadError } 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.
+ */
+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 Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+        }
+        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}"`);
+                }
+                result[argDef.name] = num;
+            }
+            else if (argDef.type === 'boolean' || argDef.type === 'bool') {
+                if (typeof val === 'string') {
+                    const lower = val.toLowerCase();
+                    if (lower === 'true' || lower === '1')
+                        result[argDef.name] = true;
+                    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}"`);
+                }
+                else {
+                    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))) {
+                    throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+                }
+            }
+        }
+        else if (argDef.default !== undefined) {
+            result[argDef.name] = argDef.default;
+        }
+    }
+    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;
+        if (!_loadedModules.has(modulePath)) {
+            try {
+                await import(pathToFileURL(modulePath).href);
+                _loadedModules.add(modulePath);
+            }
+            catch (err) {
+                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)
+            return updated.func(page, kwargs, debug);
+        if (updated?.pipeline)
+            return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+    }
+    if (cmd.func)
+        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`);
+}
+/**
+ * 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.
+ */
+export async function executeCommand(cmd, rawKwargs, debug = false) {
+    let kwargs;
+    try {
+        kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+    }
+    catch (err) {
+        throw new Error(`[Argument Validation Error]\n${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);
+                }
+                catch { }
+            }
+            return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                label: fullName(cmd),
+            });
+        }, { workspace: `site:${cmd.site}` });
+    }
+    // Non-browser commands run directly
+    return runCommand(cmd, null, kwargs, debug);
+}

package/dist/explore.d.ts

@@ -5,8 +5,80 @@
  * captures network traffic, analyzes JSON responses, and automatically
  * infers CLI capabilities from discovered API endpoints.
  */
+import type { IBrowserFactory } from './runtime.js';
 export declare function detectSiteName(url: string): string;
 export declare function slugify(value: string): string;
+interface InferredCapability {
+    name: string;
+    description: string;
+    strategy: string;
+    confidence: number;
+    endpoint: string;
+    itemPath: string | null;
+    recommendedColumns: string[];
+    recommendedArgs: Array<{
+        name: string;
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+    storeHint?: {
+        store: string;
+        action: string;
+    };
+}
+export interface ExploreManifest {
+    site: string;
+    target_url: string;
+    final_url: string;
+    title: string;
+    framework: Record<string, boolean>;
+    stores: Array<{
+        type: DiscoveredStore['type'];
+        id: string;
+        actions: string[];
+    }>;
+    top_strategy: string;
+    explored_at?: string;
+}
+export interface ExploreAuthSummary {
+    top_strategy: string;
+    indicators: string[];
+    framework: Record<string, boolean>;
+}
+export interface ExploreEndpointArtifact {
+    pattern: string;
+    method: string;
+    url: string;
+    status: number | null;
+    contentType: string;
+    score: number;
+    queryParams: string[];
+    itemPath: string | null;
+    itemCount: number;
+    detectedFields: Record<string, string>;
+    authIndicators: string[];
+}
+export interface ExploreResult {
+    site: string;
+    target_url: string;
+    final_url: string;
+    title: string;
+    framework: Record<string, boolean>;
+    stores: DiscoveredStore[];
+    top_strategy: string;
+    endpoint_count: number;
+    api_endpoint_count: number;
+    capabilities: InferredCapability[];
+    auth_indicators: string[];
+    out_dir: string;
+}
+export interface ExploreBundle {
+    manifest: ExploreManifest;
+    endpoints: ExploreEndpointArtifact[];
+    capabilities: InferredCapability[];
+    auth: ExploreAuthSummary;
+}
 export interface DiscoveredStore {
     type: 'pinia' | 'vuex';
     id: string;
@@ -14,7 +86,7 @@ export interface DiscoveredStore {
     stateKeys: string[];
 }
 export declare function exploreUrl(url: string, opts: {
-    BrowserFactory: new () => any;
+    BrowserFactory: new () => IBrowserFactory;
     site?: string;
     goal?: string;
     authenticated?: boolean;
@@ -24,5 +96,6 @@ export declare function exploreUrl(url: string, opts: {
     clickLabels?: string[];
     auto?: boolean;
     workspace?: string;
-}): Promise<Record<string, any>>;
-export declare function renderExploreSummary(result: Record<string, any>): string;
+}): Promise<ExploreResult>;
+export declare function renderExploreSummary(result: ExploreResult): string;
+export {};

package/dist/explore.js

@@ -147,6 +147,9 @@ function flattenFields(obj, prefix, maxDepth) {
     }
     return names;
 }
+function isBooleanRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 function scoreEndpoint(ep) {
     let s = 0;
     if (ep.contentType.includes('json'))
@@ -210,6 +213,120 @@ const FRAMEWORK_DETECT_JS = detectFramework.toString();
 const STORE_DISCOVER_JS = discoverStores.toString();
 // ── Auto-Interaction (Fuzzing) ─────────────────────────────────────────────
 const INTERACT_FUZZ_JS = interactFuzz.toString();
+// ── Analysis helpers (extracted from exploreUrl) ───────────────────────────
+/** Filter, deduplicate, and score network endpoints. */
+function analyzeEndpoints(networkEntries) {
+    const seen = new Map();
+    for (const entry of networkEntries) {
+        if (!entry.url)
+            continue;
+        const ct = entry.contentType.toLowerCase();
+        if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm'))
+            continue;
+        if (entry.status && entry.status >= 400)
+            continue;
+        const pattern = urlToPattern(entry.url);
+        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 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),
+            responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
+            score: 0,
+        };
+        ep.score = scoreEndpoint(ep);
+        seen.set(key, ep);
+    }
+    const analyzed = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
+    return { analyzed, totalCount: seen.size };
+}
+/** Infer CLI capabilities from analyzed endpoints. */
+function inferCapabilitiesFromEndpoints(endpoints, stores, opts) {
+    const capabilities = [];
+    const usedNames = new Set();
+    for (const ep of endpoints.slice(0, 8)) {
+        let capName = inferCapabilityName(ep.url, opts.goal);
+        if (usedNames.has(capName)) {
+            const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
+            capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
+        }
+        usedNames.add(capName);
+        const cols = [];
+        if (ep.responseAnalysis) {
+            for (const role of ['title', 'url', 'author', 'score', 'time']) {
+                if (ep.responseAnalysis.detectedFields[role])
+                    cols.push(role);
+            }
+        }
+        const args = [];
+        if (ep.hasSearchParam)
+            args.push({ name: 'keyword', type: 'str', required: true });
+        args.push({ name: 'limit', type: 'int', required: false, default: 20 });
+        if (ep.hasPaginationParam)
+            args.push({ name: 'page', type: 'int', required: false, default: 1 });
+        const epStrategy = inferStrategy(ep.authIndicators);
+        let storeHint;
+        if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
+            for (const s of stores) {
+                const matchingAction = s.actions.find(a => capName.split('_').some(part => a.toLowerCase().includes(part)) ||
+                    a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get'));
+                if (matchingAction) {
+                    storeHint = { store: s.id, action: matchingAction };
+                    break;
+                }
+            }
+        }
+        capabilities.push({
+            name: capName, description: `${opts.site ?? detectSiteName(opts.url)} ${capName}`,
+            strategy: storeHint ? 'store-action' : epStrategy,
+            confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
+            itemPath: ep.responseAnalysis?.itemPath ?? null,
+            recommendedColumns: cols.length ? cols : ['title', 'url'],
+            recommendedArgs: args,
+            ...(storeHint ? { storeHint } : {}),
+        });
+    }
+    const allAuth = new Set(endpoints.flatMap(ep => ep.authIndicators));
+    const topStrategy = allAuth.has('signature') ? 'intercept'
+        : allAuth.has('bearer') || allAuth.has('csrf') ? 'header'
+            : allAuth.size === 0 ? 'public' : 'cookie';
+    return { capabilities, topStrategy, authIndicators: [...allAuth] };
+}
+/** Write explore artifacts (manifest, endpoints, capabilities, auth, stores) to disk. */
+async function writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores) {
+    await fs.promises.mkdir(targetDir, { recursive: true });
+    const tasks = [
+        fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
+            site: result.site, target_url: result.target_url, final_url: result.final_url, title: result.title,
+            framework: result.framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
+            top_strategy: result.top_strategy, explored_at: new Date().toISOString(),
+        }, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
+            pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
+            contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
+            itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
+            detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
+        })), null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(result.capabilities, null, 2)),
+        fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
+            top_strategy: result.top_strategy, indicators: result.auth_indicators, framework: result.framework,
+        }, null, 2)),
+    ];
+    if (stores.length > 0) {
+        tasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
+    }
+    await Promise.all(tasks);
+}
 // ── Main explore function ──────────────────────────────────────────────────
 export async function exploreUrl(url, opts) {
     const waitSeconds = opts.waitSeconds ?? 3.0;
@@ -287,7 +404,7 @@ export async function exploreUrl(url, opts) {
             let framework = {};
             try {
                 const fw = await page.evaluate(FRAMEWORK_DETECT_JS);
-                if (fw && typeof fw === 'object')
+                if (isBooleanRecord(fw))
                     framework = fw;
             }
             catch { }
@@ -301,120 +418,20 @@ export async function exploreUrl(url, opts) {
                 }
                 catch { }
             }
-            // Step 7: Analyze endpoints
-            const seen = new Map();
-            for (const entry of networkEntries) {
-                if (!entry.url)
-                    continue;
-                const ct = entry.contentType.toLowerCase();
-                if (ct.includes('image/') || ct.includes('font/') || ct.includes('css') || ct.includes('javascript') || ct.includes('wasm'))
-                    continue;
-                if (entry.status && entry.status >= 400)
-                    continue;
-                const pattern = urlToPattern(entry.url);
-                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 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),
-                    responseAnalysis: entry.responseBody ? analyzeResponseBody(entry.responseBody) : null,
-                    score: 0,
-                };
-                ep.score = scoreEndpoint(ep);
-                seen.set(key, ep);
-            }
-            const analyzedEndpoints = [...seen.values()].filter(ep => ep.score >= 5).sort((a, b) => b.score - a.score);
-            // Step 8: Infer capabilities
-            const capabilities = [];
-            const usedNames = new Set();
-            for (const ep of analyzedEndpoints.slice(0, 8)) {
-                let capName = inferCapabilityName(ep.url, opts.goal);
-                if (usedNames.has(capName)) {
-                    const suffix = ep.pattern.split('/').filter(s => s && !s.startsWith('{') && !s.includes('.')).pop();
-                    capName = suffix ? `${capName}_${suffix}` : `${capName}_${usedNames.size}`;
-                }
-                usedNames.add(capName);
-                const cols = [];
-                if (ep.responseAnalysis) {
-                    for (const role of ['title', 'url', 'author', 'score', 'time']) {
-                        if (ep.responseAnalysis.detectedFields[role])
-                            cols.push(role);
-                    }
-                }
-                const args = [];
-                if (ep.hasSearchParam)
-                    args.push({ name: 'keyword', type: 'str', required: true });
-                args.push({ name: 'limit', type: 'int', required: false, default: 20 });
-                if (ep.hasPaginationParam)
-                    args.push({ name: 'page', type: 'int', required: false, default: 1 });
-                // Link store actions to capabilities when store-action strategy is recommended
-                const epStrategy = inferStrategy(ep.authIndicators);
-                let storeHint;
-                if ((epStrategy === 'intercept' || ep.authIndicators.includes('signature')) && stores.length > 0) {
-                    // Try to find a store/action that matches this endpoint's purpose
-                    for (const s of stores) {
-                        const matchingAction = s.actions.find(a => capName.split('_').some(part => a.toLowerCase().includes(part)) ||
-                            a.toLowerCase().includes('fetch') || a.toLowerCase().includes('get'));
-                        if (matchingAction) {
-                            storeHint = { store: s.id, action: matchingAction };
-                            break;
-                        }
-                    }
-                }
-                capabilities.push({
-                    name: capName, description: `${opts.site ?? detectSiteName(url)} ${capName}`,
-                    strategy: storeHint ? 'store-action' : epStrategy,
-                    confidence: Math.min(ep.score / 20, 1.0), endpoint: ep.pattern,
-                    itemPath: ep.responseAnalysis?.itemPath ?? null,
-                    recommendedColumns: cols.length ? cols : ['title', 'url'],
-                    recommendedArgs: args,
-                    ...(storeHint ? { storeHint } : {}),
-                });
-            }
-            // Step 9: Determine overall auth strategy
-            const allAuth = new Set(analyzedEndpoints.flatMap(ep => ep.authIndicators));
-            const topStrategy = allAuth.has('signature') ? 'intercept' : allAuth.has('bearer') || allAuth.has('csrf') ? 'header' : allAuth.size === 0 ? 'public' : 'cookie';
+            // Step 7+8: Analyze endpoints and infer capabilities
+            const { analyzed: analyzedEndpoints, totalCount } = analyzeEndpoints(networkEntries);
+            const { capabilities, topStrategy, authIndicators } = inferCapabilitiesFromEndpoints(analyzedEndpoints, stores, { site: opts.site, goal: opts.goal, url });
+            // Step 9: Assemble result and write artifacts
             const siteName = opts.site ?? detectSiteName(metadata.url || url);
             const targetDir = opts.outDir ?? path.join('.opencli', 'explore', siteName);
-            await fs.promises.mkdir(targetDir, { recursive: true });
             const result = {
                 site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
                 framework, stores, top_strategy: topStrategy,
-                endpoint_count: analyzedEndpoints.length + [...seen.values()].filter(ep => ep.score < 5).length,
+                endpoint_count: totalCount,
                 api_endpoint_count: analyzedEndpoints.length,
-                capabilities, auth_indicators: [...allAuth],
+                capabilities, auth_indicators: authIndicators,
             };
-            // Write artifacts
-            const writeTasks = [];
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'manifest.json'), JSON.stringify({
-                site: siteName, target_url: url, final_url: metadata.url, title: metadata.title,
-                framework, stores: stores.map(s => ({ type: s.type, id: s.id, actions: s.actions })),
-                top_strategy: topStrategy, explored_at: new Date().toISOString(),
-            }, null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'endpoints.json'), JSON.stringify(analyzedEndpoints.map(ep => ({
-                pattern: ep.pattern, method: ep.method, url: ep.url, status: ep.status,
-                contentType: ep.contentType, score: ep.score, queryParams: ep.queryParams,
-                itemPath: ep.responseAnalysis?.itemPath ?? null, itemCount: ep.responseAnalysis?.itemCount ?? 0,
-                detectedFields: ep.responseAnalysis?.detectedFields ?? {}, authIndicators: ep.authIndicators,
-            })), null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'capabilities.json'), JSON.stringify(capabilities, null, 2)));
-            writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'auth.json'), JSON.stringify({
-                top_strategy: topStrategy, indicators: [...allAuth], framework,
-            }, null, 2)));
-            if (stores.length > 0) {
-                writeTasks.push(fs.promises.writeFile(path.join(targetDir, 'stores.json'), JSON.stringify(stores, null, 2)));
-            }
-            await Promise.all(writeTasks);
+            await writeExploreArtifacts(targetDir, result, analyzedEndpoints, stores);
             return { ...result, out_dir: targetDir };
         })(), { timeout: exploreTimeout, label: `Explore ${url}` });
     }, { workspace: opts.workspace });
@@ -444,11 +461,15 @@ export function renderExploreSummary(result) {
     lines.push(`Output: ${result.out_dir}`);
     return lines.join('\n');
 }
-async function readPageMetadata(page /* IPage */) {
+async function readPageMetadata(page) {
     try {
         const result = await page.evaluate(`() => ({ url: window.location.href, title: document.title || '' })`);
-        if (result && typeof result === 'object')
-            return { url: String(result.url ?? ''), title: String(result.title ?? '') };
+        if (result && typeof result === 'object' && !Array.isArray(result)) {
+            return {
+                url: String(result.url ?? ''),
+                title: String(result.title ?? ''),
+            };
+        }
     }
     catch { }
     return { url: '', title: '' };

package/dist/external-clis.yaml

@@ -0,0 +1,48 @@
+- name: gh
+  binary: gh
+  description: "GitHub CLI — repos, PRs, issues, releases, gists"
+  homepage: "https://cli.github.com"
+  tags: [github, git, dev]
+  install:
+    mac: "brew install gh"
+
+- name: obsidian
+  binary: obsidian
+  description: "Obsidian vault management — notes, search, tags, tasks, sync"
+  homepage: "https://obsidian.md/help/cli"
+  tags: [notes, knowledge, markdown]
+  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"
+  homepage: "https://docs.docker.com/engine/reference/commandline/cli/"
+  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.d.ts

@@ -16,5 +16,10 @@ export declare function loadExternalClis(): ExternalCliConfig[];
 export declare function isBinaryInstalled(binary: string): boolean;
 export declare function getInstallCmd(installConfig?: ExternalCliInstall): string | null;
 export declare function installExternalCli(cli: ExternalCliConfig): boolean;
-export declare function executeExternalCli(name: string, args: string[]): Promise<void>;
-export declare function registerExternalCli(name: string, binary?: string, install?: string, description?: string): void;
+export declare function executeExternalCli(name: string, args: string[], preloaded?: ExternalCliConfig[]): void;
+export interface RegisterOptions {
+    binary?: string;
+    install?: string;
+    description?: string;
+}
+export declare function registerExternalCli(name: string, opts?: RegisterOptions): void;

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 } from 'node:child_process';
+import { spawnSync, execSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
@@ -45,8 +45,7 @@ export function loadExternalClis() {
 export function isBinaryInstalled(binary) {
     try {
         const isWindows = os.platform() === 'win32';
-        const cmd = isWindows ? 'where' : 'command -v';
-        execSync(`${cmd} ${binary}`, { stdio: 'ignore' });
+        execFileSync(isWindows ? 'where' : 'which', [binary], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -92,8 +91,8 @@ export function installExternalCli(cli) {
         return false;
     }
 }
-export async function executeExternalCli(name, args) {
-    const configs = loadExternalClis();
+export function executeExternalCli(name, args, preloaded) {
+    const configs = preloaded ?? loadExternalClis();
     const cli = configs.find((c) => c.name === name);
     if (!cli) {
         throw new Error(`External CLI '${name}' not found in registry.`);
@@ -107,8 +106,7 @@ export async function executeExternalCli(name, args) {
             return;
         }
     }
-    // 3. Passthrough execution
-    // We use spawnSync to properly inherit stdio and block until completion
+    // 3. Passthrough execution with stdio inherited
     const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
     if (result.error) {
         console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
@@ -119,7 +117,7 @@ export async function executeExternalCli(name, args) {
         process.exitCode = result.status;
     }
 }
-export function registerExternalCli(name, binary, install, description) {
+export function registerExternalCli(name, opts) {
     const userPath = getUserRegistryPath();
     const configDir = path.dirname(userPath);
     if (!fs.existsSync(configDir)) {
@@ -138,14 +136,13 @@ export function registerExternalCli(name, binary, install, description) {
     const existingIndex = items.findIndex((c) => c.name === name);
     const newItem = {
         name,
-        binary: binary || name,
+        binary: opts?.binary || name,
     };
-    if (description)
-        newItem.description = description;
-    if (install)
-        newItem.install = { default: install };
+    if (opts?.description)
+        newItem.description = opts.description;
+    if (opts?.install)
+        newItem.install = { default: opts.install };
     if (existingIndex >= 0) {
-        // Merge
         items[existingIndex] = { ...items[existingIndex], ...newItem };
         console.log(chalk.green(`Updated '${name}' in user registry.`));
     }