@jackwener/opencli 1.6.1 → 1.6.3

package/dist/src/interceptor.js

@@ -0,0 +1,183 @@
+/**
+ * Shared XHR/Fetch interceptor JavaScript generators.
+ *
+ * Provides a single source of truth for monkey-patching browser
+ * fetch() and XMLHttpRequest to capture API responses matching
+ * a URL pattern. Used by:
+ *   - Page.installInterceptor()  (browser.ts)
+ *   - stepIntercept              (pipeline/steps/intercept.ts)
+ *   - stepTap                    (pipeline/steps/tap.ts)
+ */
+/**
+ * Helper: define a non-enumerable property on window.
+ * Avoids detection via Object.keys(window) or for..in loops.
+ */
+const DEFINE_HIDDEN = `
+      function __defHidden(obj, key, val) {
+        try {
+          Object.defineProperty(obj, key, { value: val, writable: true, enumerable: false, configurable: true });
+        } catch { obj[key] = val; }
+      }`;
+/**
+ * Helper: disguise a patched function so toString() returns native code signature.
+ */
+const DISGUISE_FN = `
+      function __disguise(fn, name) {
+        const nativeStr = 'function ' + name + '() { [native code] }';
+        // Override toString on the instance AND patch Function.prototype.toString
+        // to handle Function.prototype.toString.call(fn) bypasses.
+        const _origToString = Function.prototype.toString;
+        const _patchedFns = window.__dFns || (function() {
+          const m = new Map();
+          Object.defineProperty(window, '__dFns', { value: m, enumerable: false, configurable: true });
+          // Patch Function.prototype.toString once to consult the map
+          Object.defineProperty(Function.prototype, 'toString', {
+            value: function() {
+              const override = m.get(this);
+              return override !== undefined ? override : _origToString.call(this);
+            },
+            writable: true, configurable: true
+          });
+          return m;
+        })();
+        _patchedFns.set(fn, nativeStr);
+        try { Object.defineProperty(fn, 'name', { value: name, configurable: true }); } catch {}
+        return fn;
+      }`;
+/**
+ * Generate JavaScript source that installs a fetch/XHR interceptor.
+ * Captured responses are pushed to `window.__opencli_intercepted`.
+ *
+ * @param patternExpr - JS expression resolving to a URL substring to match (e.g. a JSON.stringify'd string)
+ * @param opts.arrayName - Global array name for captured data (default: '__opencli_intercepted')
+ * @param opts.patchGuard - Global boolean name to prevent double-patching (default: '__opencli_interceptor_patched')
+ */
+export function generateInterceptorJs(patternExpr, opts = {}) {
+    const arr = opts.arrayName ?? '__opencli_intercepted';
+    const guard = opts.patchGuard ?? '__opencli_interceptor_patched';
+    // Store the current pattern in a separate global so it can be updated
+    // without re-patching fetch/XHR (the patchGuard only prevents double-patching).
+    const patternVar = `${guard}_pattern`;
+    return `
+    () => {
+      ${DEFINE_HIDDEN}
+      ${DISGUISE_FN}
+
+      if (!window.${arr}) __defHidden(window, '${arr}', []);
+      if (!window.${arr}_errors) __defHidden(window, '${arr}_errors', []);
+      __defHidden(window, '${patternVar}', ${patternExpr});
+      const __checkMatch = (url) => window.${patternVar} && url.includes(window.${patternVar});
+
+      if (!window.${guard}) {
+        // ── Patch fetch ──
+        const __origFetch = window.fetch;
+        window.fetch = __disguise(async function(...args) {
+          const reqUrl = typeof args[0] === 'string' ? args[0]
+            : (args[0] && args[0].url) || '';
+          const response = await __origFetch.apply(this, args);
+          if (__checkMatch(reqUrl)) {
+            try {
+              const clone = response.clone();
+              const json = await clone.json();
+              window.${arr}.push(json);
+            } catch(e) { window.${arr}_errors.push({ url: reqUrl, error: String(e) }); }
+          }
+          return response;
+        }, 'fetch');
+
+        // ── Patch XMLHttpRequest ──
+        const __XHR = XMLHttpRequest.prototype;
+        const __origOpen = __XHR.open;
+        const __origSend = __XHR.send;
+        __XHR.open = __disguise(function(method, url) {
+          Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+          return __origOpen.apply(this, arguments);
+        }, 'open');
+        __XHR.send = __disguise(function() {
+          if (__checkMatch(this.__iurl)) {
+            this.addEventListener('load', function() {
+              try {
+                window.${arr}.push(JSON.parse(this.responseText));
+              } catch(e) { window.${arr}_errors.push({ url: this.__iurl, error: String(e) }); }
+            });
+          }
+          return __origSend.apply(this, arguments);
+        }, 'send');
+
+        __defHidden(window, '${guard}', true);
+      }
+    }
+  `;
+}
+/**
+ * Generate JavaScript source to read and clear intercepted data.
+ */
+export function generateReadInterceptedJs(arrayName = '__opencli_intercepted') {
+    return `
+    () => {
+      const data = window.${arrayName} || [];
+      window.${arrayName} = [];
+      return data;
+    }
+  `;
+}
+/**
+ * Generate a self-contained tap interceptor for store-action bridge.
+ * Unlike the global interceptor, this one:
+ * - Installs temporarily, restores originals in finally block
+ * - Resolves a promise on first capture (for immediate await)
+ * - Returns captured data directly
+ *
+ * Reuses the shared DISGUISE_FN for consistent toString() disguising.
+ */
+export function generateTapInterceptorJs(patternExpr) {
+    return {
+        setupVar: `
+      let captured = null;
+      let captureResolve;
+      const capturePromise = new Promise(r => { captureResolve = r; });
+      const capturePattern = ${patternExpr};
+      ${DISGUISE_FN}
+    `,
+        capturedVar: 'captured',
+        promiseVar: 'capturePromise',
+        resolveVar: 'captureResolve',
+        fetchPatch: `
+      const origFetch = window.fetch;
+      window.fetch = __disguise(async function(...fetchArgs) {
+        const resp = await origFetch.apply(this, fetchArgs);
+        try {
+          const url = typeof fetchArgs[0] === 'string' ? fetchArgs[0]
+            : fetchArgs[0] instanceof Request ? fetchArgs[0].url : String(fetchArgs[0]);
+          if (capturePattern && url.includes(capturePattern) && !captured) {
+            try { captured = await resp.clone().json(); captureResolve(); } catch {}
+          }
+        } catch {}
+        return resp;
+      }, 'fetch');
+    `,
+        xhrPatch: `
+      const origXhrOpen = XMLHttpRequest.prototype.open;
+      const origXhrSend = XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.open = __disguise(function(method, url) {
+        Object.defineProperty(this, '__iurl', { value: String(url), writable: true, enumerable: false, configurable: true });
+        return origXhrOpen.apply(this, arguments);
+      }, 'open');
+      XMLHttpRequest.prototype.send = __disguise(function(body) {
+        if (capturePattern && this.__iurl?.includes(capturePattern)) {
+          this.addEventListener('load', function() {
+            if (!captured) {
+              try { captured = JSON.parse(this.responseText); captureResolve(); } catch {}
+            }
+          });
+        }
+        return origXhrSend.apply(this, arguments);
+      }, 'send');
+    `,
+        restorePatch: `
+      window.fetch = origFetch;
+      XMLHttpRequest.prototype.open = origXhrOpen;
+      XMLHttpRequest.prototype.send = origXhrSend;
+    `,
+    };
+}

package/dist/src/launcher.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+import type { ElectronAppEntry } from './electron-apps.js';
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export declare function probeCDP(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export declare function detectProcess(processName: string): boolean;
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export declare function killProcess(processName: string): void;
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export declare function discoverAppPath(displayName: string): string | null;
+export declare function resolveExecutableCandidates(appPath: string, app: ElectronAppEntry): string[];
+export declare function launchDetachedApp(executable: string, args: string[], label: string): Promise<void>;
+export declare function launchElectronApp(appPath: string, app: ElectronAppEntry, args: string[], label: string): Promise<void>;
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export declare function resolveElectronEndpoint(site: string): Promise<string>;

package/dist/src/launcher.js

@@ -0,0 +1,208 @@
+/**
+ * Electron app launcher — auto-detect, confirm, launch, and connect.
+ *
+ * Flow:
+ * 1. Probe CDP port → already running with debug? connect directly
+ * 2. Detect process → running without CDP? prompt to restart
+ * 3. Discover app path → not installed? error
+ * 4. Launch with --remote-debugging-port
+ * 5. Poll /json until ready
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { request as httpRequest } from 'node:http';
+import * as path from 'node:path';
+import { getElectronApp } from './electron-apps.js';
+import { confirmPrompt } from './tui.js';
+import { CommandExecutionError } from './errors.js';
+import { log } from './logger.js';
+const POLL_INTERVAL_MS = 500;
+const POLL_TIMEOUT_MS = 15_000;
+const PROBE_TIMEOUT_MS = 2_000;
+const KILL_GRACE_MS = 3_000;
+/**
+ * Probe whether a CDP endpoint is listening on the given port.
+ * Returns true if http://127.0.0.1:{port}/json responds successfully.
+ */
+export function probeCDP(port, timeoutMs = PROBE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const req = httpRequest({ hostname: '127.0.0.1', port, path: '/json', method: 'GET', timeout: timeoutMs }, (res) => {
+            res.resume();
+            resolve(res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300);
+        });
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+        req.end();
+    });
+}
+/**
+ * Check if a process with the given name is running.
+ * Uses pgrep on macOS/Linux.
+ */
+export function detectProcess(processName) {
+    if (process.platform === 'win32')
+        return false; // pgrep not available on Windows
+    try {
+        execFileSync('pgrep', ['-x', processName], { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
+ */
+export function killProcess(processName) {
+    if (process.platform === 'win32')
+        return; // pkill not available on Windows
+    try {
+        execFileSync('pkill', ['-x', processName], { stdio: 'pipe' });
+    }
+    catch {
+        // Process may have already exited
+    }
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (Date.now() < deadline) {
+        if (!detectProcess(processName))
+            return;
+        execFileSync('sleep', ['0.2'], { stdio: 'pipe' });
+    }
+    try {
+        execFileSync('pkill', ['-9', '-x', processName], { stdio: 'pipe' });
+    }
+    catch {
+        // Ignore
+    }
+}
+/**
+ * Discover the app installation path on macOS.
+ * Uses osascript to resolve the app name to a POSIX path.
+ * Returns null if the app is not installed.
+ */
+export function discoverAppPath(displayName) {
+    if (process.platform !== 'darwin') {
+        return null;
+    }
+    try {
+        const result = execFileSync('osascript', [
+            '-e', `POSIX path of (path to application "${displayName}")`,
+        ], { encoding: 'utf-8', stdio: 'pipe', timeout: 5_000 });
+        return result.trim().replace(/\/$/, '');
+    }
+    catch {
+        return null;
+    }
+}
+function resolveExecutable(appPath, processName) {
+    return `${appPath}/Contents/MacOS/${processName}`;
+}
+function isMissingExecutableError(err, label) {
+    return err instanceof CommandExecutionError
+        && err.message.startsWith(`Could not launch ${label}: executable not found at `);
+}
+export function resolveExecutableCandidates(appPath, app) {
+    const executableNames = app.executableNames?.length ? app.executableNames : [app.processName];
+    return [...new Set(executableNames)].map((name) => resolveExecutable(appPath, name));
+}
+export async function launchDetachedApp(executable, args, label) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, args, {
+            detached: true,
+            stdio: 'ignore',
+        });
+        const onError = (err) => {
+            if (err.code === 'ENOENT') {
+                reject(new CommandExecutionError(`Could not launch ${label}: executable not found at ${executable}`, `Install ${label}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`));
+                return;
+            }
+            reject(new CommandExecutionError(`Failed to launch ${label}`, err.message));
+        };
+        child.once('error', onError);
+        child.once('spawn', () => {
+            child.off('error', onError);
+            child.unref();
+            resolve();
+        });
+    });
+}
+export async function launchElectronApp(appPath, app, args, label) {
+    const executables = resolveExecutableCandidates(appPath, app);
+    let lastMissingExecutableError;
+    for (const executable of executables) {
+        log.debug(`[launcher] Launching: ${executable} ${args.join(' ')}`);
+        try {
+            await launchDetachedApp(executable, args, label);
+            return;
+        }
+        catch (err) {
+            if (isMissingExecutableError(err, label)) {
+                lastMissingExecutableError = err;
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (executables.length > 1) {
+        throw new CommandExecutionError(`Could not launch ${label}: no compatible executable found in ${path.join(appPath, 'Contents', 'MacOS')}`, `Tried: ${executables.map((executable) => path.basename(executable)).join(', ')}. Install ${label}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`);
+    }
+    throw lastMissingExecutableError ?? new CommandExecutionError(`Could not launch ${label}`, `Install ${label}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`);
+}
+async function pollForReady(port) {
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await probeCDP(port, 1_000))
+            return;
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    }
+    throw new CommandExecutionError(`App launched but CDP not available on port ${port} after ${POLL_TIMEOUT_MS / 1000}s`, 'The app may be slow to start. Try running the command again.');
+}
+/**
+ * Main entry point: resolve an Electron app to a CDP endpoint URL.
+ *
+ * Returns the endpoint URL: http://127.0.0.1:{port}
+ */
+export async function resolveElectronEndpoint(site) {
+    const app = getElectronApp(site);
+    if (!app) {
+        throw new CommandExecutionError(`No Electron app registered for site "${site}"`, 'Register the app in ~/.opencli/apps.yaml or check the site name.');
+    }
+    const { port, processName, displayName } = app;
+    const label = displayName ?? processName;
+    const endpoint = `http://127.0.0.1:${port}`;
+    // Step 1: Already running with CDP?
+    log.debug(`[launcher] Probing CDP on port ${port}...`);
+    if (await probeCDP(port)) {
+        log.debug(`[launcher] CDP already available on port ${port}`);
+        return endpoint;
+    }
+    // Step 2: Running without CDP? (process detection requires Unix tools)
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+        throw new CommandExecutionError(`${label} is not reachable on CDP port ${port}.`, `Auto-launch is not yet supported on ${process.platform}.\n` +
+            `Start ${label} manually with --remote-debugging-port=${port}, then either:\n` +
+            `  • Set OPENCLI_CDP_ENDPOINT=http://127.0.0.1:${port}\n` +
+            `  • Or just re-run the command once ${label} is listening on port ${port}.`);
+    }
+    const isRunning = detectProcess(processName);
+    if (isRunning) {
+        log.debug(`[launcher] ${label} is running but CDP not available`);
+        const confirmed = await confirmPrompt(`${label} is running but CDP is not enabled. Restart with debug port?`, true);
+        if (!confirmed) {
+            throw new CommandExecutionError(`${label} needs to be restarted with CDP enabled.`, `Manually restart: kill the app and relaunch with --remote-debugging-port=${port}`);
+        }
+        process.stderr.write(`  Restarting ${label}...\n`);
+        killProcess(processName);
+    }
+    // Step 3: Discover path
+    const appPath = discoverAppPath(label);
+    if (!appPath) {
+        throw new CommandExecutionError(`Could not find ${label} on this machine.`, `Install ${label} or register a custom path in ~/.opencli/apps.yaml`);
+    }
+    // Step 4: Launch
+    const args = [`--remote-debugging-port=${port}`, ...(app.extraArgs ?? [])];
+    await launchElectronApp(appPath, app, args, label);
+    // Step 5: Poll for readiness
+    process.stderr.write(`  Waiting for ${label} on port ${port}...\n`);
+    await pollForReady(port);
+    process.stderr.write(`  Connected to ${label} on port ${port}.\n`);
+    return endpoint;
+}

package/dist/src/launcher.test.d.ts

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

package/dist/src/launcher.test.js

@@ -0,0 +1,138 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { detectProcess, discoverAppPath, launchDetachedApp, launchElectronApp, probeCDP, resolveExecutableCandidates } from './launcher.js';
+function createMockChildProcess() {
+    const listeners = new Map();
+    return {
+        once: vi.fn((event, handler) => {
+            listeners.set(event, [...(listeners.get(event) ?? []), handler]);
+        }),
+        off: vi.fn((event, handler) => {
+            listeners.set(event, (listeners.get(event) ?? []).filter((listener) => listener !== handler));
+        }),
+        unref: vi.fn(),
+        emit: (event, value) => {
+            for (const listener of listeners.get(event) ?? [])
+                listener(value);
+        },
+    };
+}
+vi.mock('node:child_process', () => ({
+    execFileSync: vi.fn(),
+    spawn: vi.fn(),
+}));
+const cp = vi.mocked(await import('node:child_process'));
+describe('probeCDP', () => {
+    it('returns false when CDP endpoint is unreachable', async () => {
+        const result = await probeCDP(59999, 500);
+        expect(result).toBe(false);
+    });
+});
+describe('detectProcess', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns false when pgrep finds no process', () => {
+        cp.execFileSync.mockImplementation(() => {
+            const err = new Error('exit 1');
+            err.status = 1;
+            throw err;
+        });
+        const result = detectProcess('NonExistentApp');
+        expect(result).toBe(false);
+    });
+    it.skipIf(process.platform === 'win32')('returns true when pgrep finds a process', () => {
+        cp.execFileSync.mockReturnValue('12345\n');
+        const result = detectProcess('Cursor');
+        expect(result).toBe(true);
+    });
+});
+describe('discoverAppPath', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it.skipIf(process.platform !== 'darwin')('returns path when osascript succeeds', () => {
+        cp.execFileSync.mockReturnValue('/Applications/Cursor.app/\n');
+        const result = discoverAppPath('Cursor');
+        expect(result).toBe('/Applications/Cursor.app');
+    });
+    it.skipIf(process.platform !== 'darwin')('returns null when osascript fails', () => {
+        cp.execFileSync.mockImplementation(() => {
+            throw new Error('app not found');
+        });
+        const result = discoverAppPath('NonExistent');
+        expect(result).toBeNull();
+    });
+    it.skipIf(process.platform === 'darwin')('returns null on non-darwin platform', () => {
+        const result = discoverAppPath('Cursor');
+        expect(result).toBeNull();
+    });
+});
+describe('launchDetachedApp', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        cp.spawn.mockReset();
+    });
+    it('unrefs the process after spawn succeeds', async () => {
+        const child = createMockChildProcess();
+        cp.spawn.mockImplementation(() => {
+            queueMicrotask(() => child.emit('spawn'));
+            return child;
+        });
+        await expect(launchDetachedApp('/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], 'Antigravity'))
+            .resolves
+            .toBeUndefined();
+        expect(child.unref).toHaveBeenCalledTimes(1);
+    });
+    it('converts ENOENT into a controlled launch error', async () => {
+        const child = createMockChildProcess();
+        cp.spawn.mockImplementation(() => {
+            queueMicrotask(() => child.emit('error', Object.assign(new Error('missing binary'), { code: 'ENOENT' })));
+            return child;
+        });
+        await expect(launchDetachedApp('/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], 'Antigravity'))
+            .rejects
+            .toThrow('Could not launch Antigravity');
+        expect(child.unref).not.toHaveBeenCalled();
+    });
+});
+describe('resolveExecutableCandidates', () => {
+    it('prefers explicit executable candidates over processName', () => {
+        const app = {
+            port: 9234,
+            processName: 'Antigravity',
+            executableNames: ['Electron', 'Antigravity'],
+        };
+        expect(resolveExecutableCandidates('/Applications/Antigravity.app', app)).toEqual([
+            '/Applications/Antigravity.app/Contents/MacOS/Electron',
+            '/Applications/Antigravity.app/Contents/MacOS/Antigravity',
+        ]);
+    });
+});
+describe('launchElectronApp', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        cp.spawn.mockReset();
+    });
+    it('falls back to the next executable candidate when the first is missing', async () => {
+        const firstChild = createMockChildProcess();
+        const secondChild = createMockChildProcess();
+        const app = {
+            port: 9234,
+            processName: 'Antigravity',
+            executableNames: ['Electron', 'Antigravity'],
+        };
+        cp.spawn
+            .mockImplementationOnce(() => {
+            queueMicrotask(() => firstChild.emit('error', Object.assign(new Error('missing binary'), { code: 'ENOENT' })));
+            return firstChild;
+        })
+            .mockImplementationOnce(() => {
+            queueMicrotask(() => secondChild.emit('spawn'));
+            return secondChild;
+        });
+        await expect(launchElectronApp('/Applications/Antigravity.app', app, ['--remote-debugging-port=9234'], 'Antigravity')).resolves.toBeUndefined();
+        expect(cp.spawn).toHaveBeenNthCalledWith(1, '/Applications/Antigravity.app/Contents/MacOS/Electron', ['--remote-debugging-port=9234'], { detached: true, stdio: 'ignore' });
+        expect(cp.spawn).toHaveBeenNthCalledWith(2, '/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], { detached: true, stdio: 'ignore' });
+        expect(secondChild.unref).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/src/main.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * 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 path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters, USER_CLIS_DIR } from './discovery.js';
+import { getCompletions } from './completion.js';
+import { runCli } from './cli.js';
+import { emitHook } from './hooks.js';
+import { installNodeNetwork } from './node-network.js';
+import { registerUpdateNoticeOnExit, checkForUpdateBackground } from './update-check.js';
+import { EXIT_CODES } from './errors.js';
+installNodeNetwork();
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const BUILTIN_CLIS = path.resolve(__dirname, '..', 'clis');
+const USER_CLIS = USER_CLIS_DIR;
+// Sequential: plugins must run after built-in discovery so they can override built-in commands.
+await ensureUserCliCompatShims();
+await ensureUserAdapters();
+await discoverClis(BUILTIN_CLIS, USER_CLIS);
+await discoverPlugins();
+// Register exit hook: notice appears after command output (same as npm/gh/yarn)
+registerUpdateNoticeOnExit();
+// Kick off background fetch for next run (non-blocking)
+checkForUpdateBackground();
+// ── Fast-path: handle --get-completions before commander parses ─────────
+// Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
+const getCompIdx = process.argv.indexOf('--get-completions');
+if (getCompIdx !== -1) {
+    const rest = process.argv.slice(getCompIdx + 1);
+    let cursor;
+    const words = [];
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === '--cursor' && i + 1 < rest.length) {
+            cursor = parseInt(rest[i + 1], 10);
+            i++; // skip the value
+        }
+        else {
+            words.push(rest[i]);
+        }
+    }
+    if (cursor === undefined)
+        cursor = words.length;
+    const candidates = getCompletions(words, cursor);
+    process.stdout.write(candidates.join('\n') + '\n');
+    process.exit(EXIT_CODES.SUCCESS);
+}
+await emitHook('onStartup', { command: '__startup__', args: {} });
+runCli(BUILTIN_CLIS, USER_CLIS);

package/dist/src/node-network.test.d.ts

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

package/dist/src/output.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Output formatting: table, JSON, Markdown, CSV, YAML.
+ */
+export interface RenderOptions {
+    fmt?: string;
+    /** True when the user explicitly passed -f on the command line */
+    fmtExplicit?: boolean;
+    columns?: string[];
+    title?: string;
+    elapsed?: number;
+    source?: string;
+    footerExtra?: string;
+}
+export declare function render(data: unknown, opts?: RenderOptions): void;