@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/launcher.js

@@ -0,0 +1,226 @@
+/**
+ * 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 async 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;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    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 ~/.webcmd/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 ~/.webcmd/apps.yaml`);
+    }
+    throw lastMissingExecutableError ?? new CommandExecutionError(`Could not launch ${label}`, `Install ${label}, reinstall it, or register a custom app path in ~/.webcmd/apps.yaml`);
+}
+export function electronLaunchArgs(port, extraArgs = []) {
+    return [
+        `--remote-debugging-port=${port}`,
+        '--remote-allow-origins=*',
+        ...extraArgs,
+    ];
+}
+function manualElectronLaunchHint(label, port) {
+    return `Start ${label} manually with --remote-debugging-port=${port} --remote-allow-origins=*, then either:`;
+}
+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 ~/.webcmd/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` +
+            `${manualElectronLaunchHint(label, port)}\n` +
+            `  • Set WEBCMD_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} --remote-allow-origins=*`);
+        }
+        process.stderr.write(`  Restarting ${label}...\n`);
+        await 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 ~/.webcmd/apps.yaml`);
+    }
+    // Step 4: Launch
+    //
+    // Chrome / Electron 142+ enforces an Origin allow-list on the CDP
+    // WebSocket upgrade (ws://127.0.0.1:<port>/devtools/page/<id>). Without
+    // --remote-allow-origins=* every ws client other than chrome://inspect
+    // gets HTTP 403 "Rejected an incoming WebSocket connection from the
+    // http://127.0.0.1:<port> origin". This affects every Electron app
+    // webcmd launches because they all bundle a recent Chromium. Same
+    // mitigation as Puppeteer / Playwright / chrome-devtools-mcp.
+    const args = electronLaunchArgs(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,153 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { detectProcess, discoverAppPath, electronLaunchArgs, 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('electronLaunchArgs', () => {
+    it('includes Chromium 142 WebSocket origin allow-list for auto-launched Electron apps', () => {
+        expect(electronLaunchArgs(9234)).toEqual([
+            '--remote-debugging-port=9234',
+            '--remote-allow-origins=*',
+        ]);
+    });
+    it('preserves app-specific extra launch args after the required CDP flags', () => {
+        expect(electronLaunchArgs(9234, ['--foo=bar'])).toEqual([
+            '--remote-debugging-port=9234',
+            '--remote-allow-origins=*',
+            '--foo=bar',
+        ]);
+    });
+});
+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/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Unified logging for webcmd.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+export declare const log: {
+    /** Informational message (always shown) */
+    info(msg: string): void;
+    /** Lightweight status line for adapter progress updates */
+    status(msg: string): void;
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg: string): void;
+    /** Warning (always shown) */
+    warn(msg: string): void;
+    /** Error (always shown) */
+    error(msg: string): void;
+    /** Verbose output (shown when -v flag or WEBCMD_VERBOSE is set) */
+    verbose(msg: string): void;
+    /** Alias for verbose output. */
+    debug(msg: string): void;
+    /** Step-style debug (for pipeline steps, etc.) */
+    step(stepNum: number, total: number, op: string, preview?: string): void;
+    /** Step result summary */
+    stepResult(summary: string): void;
+};

package/dist/src/logger.js

@@ -0,0 +1,49 @@
+/**
+ * Unified logging for webcmd.
+ *
+ * All framework output (warnings, debug info, errors) should go through
+ * this module so that verbosity levels are respected consistently.
+ */
+function isVerbose() {
+    return !!process.env.WEBCMD_VERBOSE;
+}
+export const log = {
+    /** Informational message (always shown) */
+    info(msg) {
+        process.stderr.write(`ℹ  ${msg}\n`);
+    },
+    /** Lightweight status line for adapter progress updates */
+    status(msg) {
+        process.stderr.write(`${msg}\n`);
+    },
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg) {
+        process.stderr.write(`${msg}\n`);
+    },
+    /** Warning (always shown) */
+    warn(msg) {
+        process.stderr.write(`⚠  ${msg}\n`);
+    },
+    /** Error (always shown) */
+    error(msg) {
+        process.stderr.write(`✖  ${msg}\n`);
+    },
+    /** Verbose output (shown when -v flag or WEBCMD_VERBOSE is set) */
+    verbose(msg) {
+        if (isVerbose()) {
+            process.stderr.write(`[verbose] ${msg}\n`);
+        }
+    },
+    /** Alias for verbose output. */
+    debug(msg) {
+        this.verbose(msg);
+    },
+    /** Step-style debug (for pipeline steps, etc.) */
+    step(stepNum, total, op, preview = '') {
+        process.stderr.write(`  [${stepNum}/${total}] ${op}${preview}\n`);
+    },
+    /** Step result summary */
+    stepResult(summary) {
+        process.stderr.write(`       → ${summary}\n`);
+    },
+};

package/dist/src/main.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * webcmd — Make any website your CLI. AI-powered.
+ */
+export {};

package/dist/src/main.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * webcmd — 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 fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getCompletionsFromManifest, hasAllManifests, printCompletionScriptFast } from './completion-fast.js';
+import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+import { PKG_VERSION } from './version.js';
+import { EXIT_CODES } from './errors.js';
+import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_MAJOR } from './runtime-detect.js';
+import { unsupportedDaemonPortEnvMessage } from './constants.js';
+import { CONFIG_DIR_NAME } from './brand.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Adapters are JS-first and live at <package-root>/clis/.
+// Use findPackageRoot so the path works both in dev (src/main.ts) and prod (dist/src/main.js).
+const BUILTIN_CLIS = path.join(findPackageRoot(__filename), 'clis');
+const USER_CLIS = path.join(os.homedir(), CONFIG_DIR_NAME, 'clis');
+// ── Ultra-fast path: lightweight commands bypass full discovery ──────────
+// These are high-frequency or trivial paths that must not pay the startup tax.
+const argv = process.argv.slice(2);
+if (typeof globalThis.Bun === 'undefined' && !isSupportedNodeVersion(process.version)) {
+    process.stderr.write([
+        `Webcmd requires Node.js >= ${MIN_SUPPORTED_NODE_MAJOR}.0.0.`,
+        `Current runtime: ${process.version}`,
+        'Upgrade Node.js, then retry the same command.',
+        '',
+    ].join('\n'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+}
+if (process.env.WEBCMD_DAEMON_PORT) {
+    process.stderr.write(`error: ${unsupportedDaemonPortEnvMessage(process.env.WEBCMD_DAEMON_PORT)}\n`);
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+}
+// Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
+// e.g. `webcmd --version` or `webcmd -V`, but NOT `webcmd gh --version`
+if (argv[0] === '--version' || argv[0] === '-V') {
+    process.stdout.write(PKG_VERSION + '\n');
+    process.exit(EXIT_CODES.SUCCESS);
+}
+// Fast path: completion <shell> — print shell script without discovery
+if (argv[0] === 'completion' && argv.length >= 2) {
+    if (printCompletionScriptFast(argv[1])) {
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // Unknown shell — fall through to full path for proper error handling
+}
+// Fast path: --get-completions — read from manifest, skip discovery
+const getCompIdx = process.argv.indexOf('--get-completions');
+if (getCompIdx !== -1) {
+    // Only include manifests that actually exist on disk.
+    // With sparse override, the user clis dir may exist but have no manifest.
+    const manifestPaths = [getCliManifestPath(BUILTIN_CLIS)];
+    const userManifest = getCliManifestPath(USER_CLIS);
+    try {
+        fs.accessSync(userManifest);
+        manifestPaths.push(userManifest);
+    }
+    catch { /* no user manifest */ }
+    if (hasAllManifests(manifestPaths)) {
+        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++;
+            }
+            else {
+                words.push(rest[i]);
+            }
+        }
+        if (cursor === undefined)
+            cursor = words.length;
+        const candidates = getCompletionsFromManifest(words, cursor, manifestPaths);
+        process.stdout.write(candidates.join('\n') + '\n');
+        process.exit(EXIT_CODES.SUCCESS);
+    }
+    // No manifest — fall through to full discovery path below
+}
+// ── Full startup path ───────────────────────────────────────────────────
+// Dynamic imports: these are deferred so the fast path above never pays the cost.
+const { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters } = await import('./discovery.js');
+const { getCompletions } = await import('./completion.js');
+const { runCli } = await import('./cli.js');
+const { emitHook } = await import('./hooks.js');
+const { installNodeNetwork } = await import('./node-network.js');
+const { registerUpdateNoticeOnExit, checkForUpdateBackground } = await import('./update-check.js');
+installNodeNetwork();
+// Parallelise independent startup I/O:
+//  - Built-in adapter discovery has no dependency on user-dir setup.
+//  - ensureUserCliCompatShims and ensureUserAdapters operate on different paths
+//    (~/.webcmd/node_modules/ vs ~/.webcmd/clis/ + adapter-manifest.json).
+//  - registerCommand() overwrites on name collision (see registry.ts), so
+//    user-CLI discovery MUST run after built-in discovery to preserve the
+//    intended override order (user adapters override built-in ones).
+//  - discoverPlugins runs last: plugins may override both built-in and user CLIs.
+const skipUserDiscovery = argv[0] === 'convention-audit';
+if (skipUserDiscovery) {
+    await discoverClis(BUILTIN_CLIS);
+}
+else {
+    const [, ,] = await Promise.all([
+        ensureUserCliCompatShims(),
+        ensureUserAdapters(),
+        discoverClis(BUILTIN_CLIS),
+    ]);
+    await discoverClis(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();
+// ── Fallback completion: manifest unavailable, use full registry ─────────
+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++;
+        }
+        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);
+}
+// Rewrite `webcmd browser <session> <subcommand> ...` so commander (which
+// can't combine a parent positional with subcommand dispatch) sees the internal
+// `--session <name>` flag form. Also refuses the retired `webcmd browser
+// --session foo ...` user form with a friendly usage error.
+const { rewriteBrowserArgv, BrowserSessionArgvError, escapeLeadingDashPositional } = await import('./cli-argv-preprocess.js');
+try {
+    let rewritten = rewriteBrowserArgv(process.argv.slice(2));
+    // Insert a `--` separator before a required positional whose value starts
+    // with `-` (e.g. opaque securityId tokens; #1160). Skipped when the
+    // manifest is unavailable so the user-cli / dev paths still work.
+    try {
+        const manifestPath = getCliManifestPath(BUILTIN_CLIS);
+        if (fs.existsSync(manifestPath)) {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            if (Array.isArray(manifest))
+                rewritten = escapeLeadingDashPositional(rewritten, manifest);
+        }
+    }
+    catch { /* manifest unavailable; skip the dash escape */ }
+    process.argv.splice(2, process.argv.length - 2, ...rewritten);
+}
+catch (err) {
+    if (err instanceof BrowserSessionArgvError) {
+        process.stderr.write(`error: ${err.message}\n`);
+        process.exit(EXIT_CODES.GENERIC_ERROR);
+    }
+    throw err;
+}
+await emitHook('onStartup', { command: '__startup__', args: {} });
+runCli(BUILTIN_CLIS, USER_CLIS);