@jackwener/opencli 1.7.1 → 1.7.3

package/dist/src/cli.js

@@ -369,9 +369,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         await page.wait(0.3);
         await page.typeText(index, text);
         // Detect autocomplete/combobox fields and wait for dropdown suggestions
+        const safeIndex = JSON.stringify(String(index));
         const isAutocomplete = await page.evaluate(`
         (() => {
-          const el = document.querySelector('[data-opencli-ref="${index}"]');
+          const el = document.querySelector('[data-opencli-ref="' + ${safeIndex} + '"]');
           if (!el) return false;
           const role = el.getAttribute('role');
           const ac = el.getAttribute('aria-autocomplete');
@@ -390,9 +391,10 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     browser.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text')
         .description('Select dropdown option')
         .action(browserAction(async (page, index, option) => {
+        const safeIdx = JSON.stringify(String(index));
         const result = await page.evaluate(`
         (function() {
-          var sel = document.querySelector('[data-opencli-ref="${index}"]');
+          var sel = document.querySelector('[data-opencli-ref="' + ${safeIdx} + '"]');
           if (!sel || sel.tagName !== 'SELECT') return { error: 'Not a <select>' };
           var match = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
           if (!match) return { error: 'Option not found', available: Array.from(sel.options).map(o => o.text.trim()) };
@@ -891,6 +893,114 @@ cli({
             process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
+    // ── Built-in: adapter management ─────────────────────────────────────────
+    const adapterCmd = program.command('adapter').description('Manage CLI adapters');
+    adapterCmd
+        .command('status')
+        .description('Show which sites have local overrides vs using official baseline')
+        .action(async () => {
+        const os = await import('node:os');
+        const userClisDir = path.join(os.homedir(), '.opencli', 'clis');
+        const builtinClisDir = BUILTIN_CLIS;
+        try {
+            const userEntries = await fs.promises.readdir(userClisDir, { withFileTypes: true });
+            const userSites = userEntries.filter(e => e.isDirectory()).map(e => e.name).sort();
+            let builtinSites = [];
+            try {
+                const builtinEntries = await fs.promises.readdir(builtinClisDir, { withFileTypes: true });
+                builtinSites = builtinEntries.filter(e => e.isDirectory()).map(e => e.name).sort();
+            }
+            catch { /* no builtin dir */ }
+            if (userSites.length === 0) {
+                console.log('No local adapter overrides. All sites use the official baseline.');
+                return;
+            }
+            console.log(`Local overrides in ~/.opencli/clis/ (${userSites.length} sites):\n`);
+            for (const site of userSites) {
+                const isOfficial = builtinSites.includes(site);
+                const label = isOfficial ? 'override' : 'custom';
+                console.log(`  ${site} [${label}]`);
+            }
+            console.log(`\nOfficial baseline: ${builtinSites.length} sites in package`);
+        }
+        catch {
+            console.log('No local adapter overrides. All sites use the official baseline.');
+        }
+    });
+    adapterCmd
+        .command('eject')
+        .description('Copy an official adapter to ~/.opencli/clis/ for local editing')
+        .argument('<site>', 'Site name (e.g. twitter, bilibili)')
+        .action(async (site) => {
+        const os = await import('node:os');
+        const userClisDir = path.join(os.homedir(), '.opencli', 'clis');
+        const builtinSiteDir = path.join(BUILTIN_CLIS, site);
+        const userSiteDir = path.join(userClisDir, site);
+        try {
+            await fs.promises.access(builtinSiteDir);
+        }
+        catch {
+            console.error(styleText('red', `Error: Site "${site}" not found in official adapters.`));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        try {
+            await fs.promises.access(userSiteDir);
+            console.error(styleText('yellow', `Site "${site}" already exists in ~/.opencli/clis/. Use "opencli adapter reset ${site}" first to restore official version.`));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        catch { /* good, doesn't exist yet */ }
+        fs.cpSync(builtinSiteDir, userSiteDir, { recursive: true });
+        console.log(styleText('green', `✅ Ejected "${site}" to ~/.opencli/clis/${site}/`));
+        console.log('You can now edit the adapter files. Changes take effect immediately.');
+        console.log(styleText('yellow', 'Note: Official updates to this adapter will overwrite your changes.'));
+    });
+    adapterCmd
+        .command('reset')
+        .description('Remove local override and restore official adapter version')
+        .argument('[site]', 'Site name (e.g. twitter, bilibili)')
+        .option('--all', 'Reset all local overrides')
+        .action(async (site, opts) => {
+        const os = await import('node:os');
+        const userClisDir = path.join(os.homedir(), '.opencli', 'clis');
+        if (opts.all) {
+            try {
+                const userEntries = await fs.promises.readdir(userClisDir, { withFileTypes: true });
+                const dirs = userEntries.filter(e => e.isDirectory());
+                if (dirs.length === 0) {
+                    console.log('No local sites to reset.');
+                    return;
+                }
+                for (const dir of dirs) {
+                    fs.rmSync(path.join(userClisDir, dir.name), { recursive: true, force: true });
+                }
+                console.log(styleText('green', `✅ Reset ${dirs.length} site(s). All adapters now use official baseline.`));
+            }
+            catch {
+                console.log('No local sites to reset.');
+            }
+            return;
+        }
+        if (!site) {
+            console.error(styleText('red', 'Error: Please specify a site name or use --all.'));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const userSiteDir = path.join(userClisDir, site);
+        try {
+            await fs.promises.access(userSiteDir);
+        }
+        catch {
+            console.error(styleText('yellow', `Site "${site}" has no local override.`));
+            return;
+        }
+        const isOfficial = fs.existsSync(path.join(BUILTIN_CLIS, site));
+        fs.rmSync(userSiteDir, { recursive: true, force: true });
+        console.log(styleText('green', isOfficial
+            ? `✅ Reset "${site}". Now using official baseline.`
+            : `✅ Removed custom site "${site}".`));
+    });
     // ── Built-in: daemon ──────────────────────────────────────────────────────
     const daemonCmd = program.command('daemon').description('Manage the opencli daemon');
     daemonCmd

package/dist/src/daemon.js

@@ -27,6 +27,7 @@ const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_P
 // ─── State ───────────────────────────────────────────────────────────
 let extensionWs = null;
 let extensionVersion = null;
+let extensionCompatRange = null;
 const pending = new Map();
 const LOG_BUFFER_SIZE = 200;
 const logBuffer = [];
@@ -111,6 +112,7 @@ async function handleRequest(req, res) {
             uptime,
             extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
             extensionVersion,
+            extensionCompatRange,
             pending: pending.size,
             memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
             port: PORT,
@@ -188,6 +190,7 @@ wss.on('connection', (ws) => {
     log.info('[daemon] Extension connected');
     extensionWs = ws;
     extensionVersion = null; // cleared until hello message arrives
+    extensionCompatRange = null;
     // ── Heartbeat: ping every 15s, close if 2 pongs missed ──
     let missedPongs = 0;
     const heartbeatInterval = setInterval(() => {
@@ -213,6 +216,7 @@ wss.on('connection', (ws) => {
             // Handle hello message from extension (version handshake)
             if (msg.type === 'hello') {
                 extensionVersion = typeof msg.version === 'string' ? msg.version : null;
+                extensionCompatRange = typeof msg.compatRange === 'string' ? msg.compatRange : null;
                 return;
             }
             // Handle log messages from extension
@@ -244,6 +248,7 @@ wss.on('connection', (ws) => {
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
+            extensionCompatRange = null;
             // Reject all pending requests since the extension is gone
             for (const [id, p] of pending) {
                 clearTimeout(p.timer);

package/dist/src/discovery.d.ts

@@ -23,8 +23,11 @@ export declare const PLUGINS_DIR: string;
  */
 export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
 /**
- * First-run fallback: if postinstall was skipped (--ignore-scripts) or failed,
- * trigger adapter fetch on first CLI invocation when ~/.opencli/clis/ is empty.
+ * Ensure the user adapters directory exists.
+ *
+ * With smart sync, ~/.opencli/clis/ only holds files that differ from the
+ * package baseline (upstream-synced cache + autofix output + user overrides).
+ * Built-in adapters are loaded directly from the installed package.
  */
 export declare function ensureUserAdapters(): Promise<void>;
 /**

package/dist/src/discovery.js

@@ -14,7 +14,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Strategy, registerCommand } from './registry.js';
 import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
-import { findPackageRoot, getCliManifestPath, getFetchAdaptersScriptPath } from './package-paths.js';
+import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 /** User runtime directory: ~/.opencli */
 export const USER_OPENCLI_DIR = path.join(os.homedir(), '.opencli');
 /** User CLIs directory: ~/.opencli/clis */
@@ -77,43 +77,15 @@ export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
         log.warn(`Could not create symlink at ${symlinkPath}: ${getErrorMessage(err)}`);
     }
 }
-const ADAPTER_MANIFEST_PATH = path.join(USER_OPENCLI_DIR, 'adapter-manifest.json');
 /**
- * First-run fallback: if postinstall was skipped (--ignore-scripts) or failed,
- * trigger adapter fetch on first CLI invocation when ~/.opencli/clis/ is empty.
+ * Ensure the user adapters directory exists.
+ *
+ * With smart sync, ~/.opencli/clis/ only holds files that differ from the
+ * package baseline (upstream-synced cache + autofix output + user overrides).
+ * Built-in adapters are loaded directly from the installed package.
  */
 export async function ensureUserAdapters() {
-    // If adapter manifest already exists, adapters were fetched — nothing to do
-    try {
-        await fs.promises.access(ADAPTER_MANIFEST_PATH);
-        return;
-    }
-    catch {
-        // No manifest — first run or postinstall was skipped
-    }
-    // Check if clis dir has any content (could be manually populated)
-    try {
-        const entries = await fs.promises.readdir(USER_CLIS_DIR);
-        if (entries.length > 0)
-            return;
-    }
-    catch {
-        // Dir doesn't exist — needs fetch
-    }
-    log.info('First run detected — copying adapters (one-time setup)...');
-    try {
-        const { execFileSync } = await import('node:child_process');
-        const scriptPath = getFetchAdaptersScriptPath(PACKAGE_ROOT);
-        execFileSync(process.execPath, [scriptPath], {
-            stdio: 'inherit',
-            env: { ...process.env, _OPENCLI_FIRST_RUN: '1' },
-            timeout: 120_000,
-        });
-    }
-    catch (err) {
-        log.warn(`Could not fetch adapters on first run: ${getErrorMessage(err)}`);
-        log.warn('Built-in adapters from the package will be used.');
-    }
+    await fs.promises.mkdir(USER_CLIS_DIR, { recursive: true });
 }
 /**
  * Discover and register CLI commands.

package/dist/src/doctor.d.ts

@@ -21,6 +21,7 @@ export type DoctorReport = {
     extensionConnected: boolean;
     extensionFlaky?: boolean;
     extensionVersion?: string;
+    latestExtensionVersion?: string;
     connectivity?: ConnectivityResult;
     sessions?: Array<{
         workspace: string;

package/dist/src/doctor.js

@@ -9,7 +9,37 @@ import { BrowserBridge } from './browser/index.js';
 import { getDaemonHealth, listSessions } from './browser/daemon-client.js';
 import { getErrorMessage } from './errors.js';
 import { getRuntimeLabel } from './runtime-detect.js';
+import { getCachedLatestExtensionVersion } from './update-check.js';
 const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
+/** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
+function parseSemver(v) {
+    const parts = v.replace(/^v/, '').split('-')[0].split('.').map(Number);
+    if (parts.length < 3 || parts.some(isNaN))
+        return null;
+    return [parts[0], parts[1], parts[2]];
+}
+/** Returns true if `a` is strictly newer than `b`. */
+function isNewerVersion(a, b) {
+    const va = parseSemver(a);
+    const vb = parseSemver(b);
+    if (!va || !vb)
+        return false;
+    const cmp = va[0] - vb[0] || va[1] - vb[1] || va[2] - vb[2];
+    return cmp > 0;
+}
+/** Check if version satisfies a simple range like ">=1.7.0". */
+function satisfiesRange(version, range) {
+    const match = range.match(/^(>=?)\s*(\S+)$/);
+    if (!match)
+        return true; // Unknown range format — don't block
+    const [, op, rangeVer] = match;
+    const v = parseSemver(version);
+    const r = parseSemver(rangeVer);
+    if (!v || !r)
+        return true;
+    const cmp = v[0] - r[0] || v[1] - r[1] || v[2] - r[2];
+    return op === '>=' ? cmp >= 0 : cmp > 0;
+}
 /**
  * Test connectivity by attempting a real browser command.
  */
@@ -80,7 +110,16 @@ export async function runBrowserDoctor(opts = {}) {
         issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
     }
     const extensionVersion = health.status?.extensionVersion;
-    if (extensionVersion && opts.cliVersion) {
+    const extensionCompatRange = health.status?.extensionCompatRange;
+    if (extensionVersion && opts.cliVersion && extensionCompatRange) {
+        if (!satisfiesRange(opts.cliVersion, extensionCompatRange)) {
+            issues.push(`CLI version incompatible with extension: extension v${extensionVersion} requires CLI ${extensionCompatRange}, but CLI is v${opts.cliVersion}\n` +
+                '  Update the CLI: npm install -g @jackwener/opencli\n' +
+                '  Or download a compatible extension from: https://github.com/jackwener/opencli/releases');
+        }
+    }
+    else if (extensionVersion && opts.cliVersion) {
+        // Fallback for older extensions that don't send compatRange
         const extMajor = extensionVersion.split('.')[0];
         const cliMajor = opts.cliVersion.split('.')[0];
         if (extMajor !== cliMajor) {
@@ -88,6 +127,12 @@ export async function runBrowserDoctor(opts = {}) {
                 '  Download the latest extension from: https://github.com/jackwener/opencli/releases');
         }
     }
+    // Extension update check (from cached background fetch)
+    const latestExtensionVersion = getCachedLatestExtensionVersion();
+    if (extensionVersion && latestExtensionVersion && isNewerVersion(latestExtensionVersion, extensionVersion)) {
+        issues.push(`Extension update available: v${extensionVersion} → v${latestExtensionVersion}\n` +
+            '  Download from: https://github.com/jackwener/opencli/releases');
+    }
     return {
         cliVersion: opts.cliVersion,
         daemonRunning,
@@ -95,6 +140,7 @@ export async function runBrowserDoctor(opts = {}) {
         extensionConnected,
         extensionFlaky,
         extensionVersion,
+        latestExtensionVersion,
         connectivity,
         sessions,
         issues,
@@ -114,7 +160,10 @@ export function renderBrowserDoctorReport(report) {
     const extIcon = report.extensionFlaky
         ? styleText('yellow', '[WARN]')
         : report.extensionConnected ? styleText('green', '[OK]') : styleText('yellow', '[MISSING]');
-    const extVersion = report.extensionVersion ? styleText('dim', ` (v${report.extensionVersion})`) : '';
+    const extUpdateHint = report.extensionVersion && report.latestExtensionVersion && isNewerVersion(report.latestExtensionVersion, report.extensionVersion)
+        ? styleText('yellow', ` → v${report.latestExtensionVersion} available`)
+        : '';
+    const extVersion = report.extensionVersion ? styleText('dim', ` (v${report.extensionVersion})`) + extUpdateHint : '';
     const extLabel = report.extensionFlaky
         ? 'unstable (connected during live check, then disconnected)'
         : report.extensionConnected ? 'connected' : 'not connected';

package/dist/src/electron-apps.js

@@ -22,7 +22,7 @@ export const builtinApps = {
         bundleId: 'dev.antigravity.app',
         displayName: 'Antigravity',
     },
-    chatgpt: { port: 9236, processName: 'ChatGPT', bundleId: 'com.openai.chat', displayName: 'ChatGPT' },
+    'chatgpt-app': { port: 9236, processName: 'ChatGPT', bundleId: 'com.openai.chat', displayName: 'ChatGPT' },
 };
 /** Merge builtin + user-defined apps. User entries are additive only. */
 export function loadApps(userApps) {

package/dist/src/engine.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { discoverClis, discoverPlugins, ensureUserCliCompatShims, PLUGINS_DIR } from './discovery.js';
+import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters, PLUGINS_DIR } from './discovery.js';
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 import { clearAllHooks, onAfterExecute } from './hooks.js';
@@ -103,6 +103,34 @@ cli({
         }
     });
 });
+describe('ensureUserAdapters', () => {
+    it('creates user clis directory without triggering full copy', async () => {
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-ensure-'));
+        const clisDir = path.join(tempDir, 'clis');
+        try {
+            // Patch USER_CLIS_DIR is not easy, so we test the function behavior indirectly:
+            // ensureUserAdapters should not throw and should be very fast (no fetch script)
+            const start = Date.now();
+            await ensureUserAdapters();
+            const elapsed = Date.now() - start;
+            // Should complete quickly (< 1s) since it only creates a directory
+            expect(elapsed).toBeLessThan(1000);
+        }
+        finally {
+            await fs.promises.rm(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('discoverClis handles empty user directory gracefully', async () => {
+        const emptyDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-empty-'));
+        try {
+            // Should not throw for an empty directory (no adapters to discover)
+            await expect(discoverClis(emptyDir)).resolves.not.toThrow();
+        }
+        finally {
+            await fs.promises.rm(emptyDir, { recursive: true, force: true });
+        }
+    });
+});
 describe('discoverPlugins', () => {
     const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
     const yamlPath = path.join(testPluginDir, 'greeting.yaml');

package/dist/src/errors.d.ts

@@ -82,6 +82,7 @@ export interface ErrorEnvelope {
         help?: string;
         exitCode: number;
         stack?: string;
+        cause?: string;
     };
 }
 /** Extract a human-readable message from an unknown caught value. */

package/dist/src/errors.js

@@ -106,8 +106,19 @@ export class PluginError extends CliError {
 export function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/** Serialize an error cause chain into a readable string. */
+function serializeCause(cause) {
+    if (cause instanceof Error) {
+        const parts = [cause.message];
+        if (cause.cause)
+            parts.push(`  caused by: ${serializeCause(cause.cause)}`);
+        return parts.join('\n');
+    }
+    return String(cause);
+}
 /** Build an ErrorEnvelope from any caught value. */
 export function toEnvelope(err) {
+    const cause = err instanceof Error && err.cause ? serializeCause(err.cause) : undefined;
     if (err instanceof CliError) {
         return {
             ok: false,
@@ -116,6 +127,7 @@ export function toEnvelope(err) {
                 message: err.message,
                 ...(err.hint ? { help: err.hint } : {}),
                 exitCode: err.exitCode,
+                ...(cause ? { cause } : {}),
             },
         };
     }
@@ -126,6 +138,7 @@ export function toEnvelope(err) {
             code: 'UNKNOWN',
             message: msg,
             exitCode: EXIT_CODES.GENERIC_ERROR,
+            ...(cause ? { cause } : {}),
         },
     };
 }

package/dist/src/execution.js

@@ -11,16 +11,20 @@
  */
 import { getRegistry, fullName } from './registry.js';
 import { pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
 import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } from './errors.js';
 import { isDiagnosticEnabled, collectDiagnostic, emitDiagnostic } from './diagnostic.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { emitHook } from './hooks.js';
-import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
 import { probeCDP, resolveElectronEndpoint } from './launcher.js';
-const _loadedModules = new Set();
+const _loadedModules = new Map();
+/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
+const _moduleMtimes = new Map();
+const _userClisDir = `${os.homedir()}/.opencli/clis/`;
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
     for (const argDef of cmdArgs) {
@@ -67,15 +71,34 @@ async function runCommand(cmd, page, kwargs, debug) {
     const internal = cmd;
     if (internal._lazy && internal._modulePath) {
         const modulePath = internal._modulePath;
-        if (!_loadedModules.has(modulePath)) {
+        // Hot-reload: if a user adapter's file has changed on disk, invalidate cache
+        const isUserAdapter = modulePath.startsWith(_userClisDir);
+        if (isUserAdapter && _loadedModules.has(modulePath)) {
             try {
-                await import(pathToFileURL(modulePath).href);
-                _loadedModules.add(modulePath);
+                const stat = fs.statSync(modulePath);
+                const prevMtime = _moduleMtimes.get(modulePath);
+                if (prevMtime !== undefined && stat.mtimeMs !== prevMtime) {
+                    _loadedModules.delete(modulePath);
+                    _moduleMtimes.delete(modulePath);
+                }
             }
-            catch (err) {
+            catch { /* file may have been deleted; let import below handle it */ }
+        }
+        if (!_loadedModules.has(modulePath)) {
+            const url = pathToFileURL(modulePath).href;
+            const importUrl = _moduleMtimes.has(modulePath) ? `${url}?t=${Date.now()}` : url;
+            const loadPromise = import(importUrl).then(() => {
+                try {
+                    _moduleMtimes.set(modulePath, fs.statSync(modulePath).mtimeMs);
+                }
+                catch { }
+            }, (err) => {
+                _loadedModules.delete(modulePath);
                 throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
-            }
+            });
+            _loadedModules.set(modulePath, loadPromise);
         }
+        await _loadedModules.get(modulePath);
         const updated = getRegistry().get(fullName(cmd));
         if (updated?.func) {
             if (!page && updated.browser !== false) {
@@ -159,7 +182,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.goto(preNavUrl);
                     }
                     catch (err) {
-                        log.warn(`Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`);
+                        throw new CommandExecutionError(`Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`, 'Check that the site is reachable and the browser extension is running.');
                     }
                 }
                 try {
@@ -173,13 +196,17 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     return result;
                 }
                 catch (err) {
-                    // Collect diagnostic while page is still alive (before browserSession closes it).
+                    // Collect diagnostic while page is still alive (before closing the window).
                     if (isDiagnosticEnabled()) {
                         const internal = cmd;
                         const ctx = await collectDiagnostic(err, internal, page);
                         emitDiagnostic(ctx);
                         diagnosticEmitted = true;
                     }
+                    // Close the automation window on failure too — without this, the window
+                    // lingers until the extension's idle timer fires (unreliable on Windows
+                    // where MV3 service workers may be suspended before setTimeout triggers).
+                    await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
             }, { workspace: `site:${cmd.site}`, cdpEndpoint });

package/dist/src/execution.test.js

@@ -3,6 +3,8 @@ import { executeCommand, prepareCommandArgs } from './execution.js';
 import { TimeoutError } from './errors.js';
 import { cli, Strategy } from './registry.js';
 import { withTimeoutMs } from './runtime.js';
+import * as runtime from './runtime.js';
+import * as capRouting from './capabilityRouting.js';
 describe('executeCommand — non-browser timeout', () => {
     it('applies timeoutSeconds to non-browser commands', async () => {
         const cmd = cli({
@@ -37,6 +39,27 @@ describe('executeCommand — non-browser timeout', () => {
         // With timeout guard skipped, the sentinel fires instead.
         await expect(withTimeoutMs(executeCommand(cmd, {}), 50, 'sentinel timeout')).rejects.toThrow('sentinel timeout');
     });
+    it('calls closeWindow on browser command failure', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        // Mock shouldUseBrowserSession to return true
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        // Mock browserSession to invoke the callback with our mock page
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => {
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-close-on-error',
+            description: 'test closeWindow on failure',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => { throw new Error('adapter failure'); },
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('adapter failure');
+        expect(closeWindow).toHaveBeenCalledTimes(1);
+        vi.restoreAllMocks();
+    });
     it('does not re-run custom validation when args are already prepared', async () => {
         const validateArgs = vi.fn();
         const cmd = {

package/dist/src/logger.d.ts

@@ -15,9 +15,9 @@ export declare const log: {
     warn(msg: string): void;
     /** Error (always shown) */
     error(msg: string): void;
-    /** Verbose output (only when OPENCLI_VERBOSE is set or -v flag) */
+    /** Verbose output (shown when -v flag, OPENCLI_VERBOSE, or DEBUG=opencli is set) */
     verbose(msg: string): void;
-    /** Debug output (only when DEBUG includes 'opencli') */
+    /** @deprecated Use log.verbose() instead. Kept as alias for backward compatibility. */
     debug(msg: string): void;
     /** Step-style debug (for pipeline steps, etc.) */
     step(stepNum: number, total: number, op: string, preview?: string): void;

package/dist/src/logger.js

@@ -6,10 +6,7 @@
  */
 import { styleText } from 'node:util';
 function isVerbose() {
-    return !!process.env.OPENCLI_VERBOSE;
-}
-function isDebug() {
-    return !!process.env.DEBUG?.includes('opencli');
+    return !!process.env.OPENCLI_VERBOSE || !!process.env.DEBUG?.includes('opencli');
 }
 export const log = {
     /** Informational message (always shown) */
@@ -32,17 +29,15 @@ export const log = {
     error(msg) {
         process.stderr.write(`${styleText('red', '✖')}  ${msg}\n`);
     },
-    /** Verbose output (only when OPENCLI_VERBOSE is set or -v flag) */
+    /** Verbose output (shown when -v flag, OPENCLI_VERBOSE, or DEBUG=opencli is set) */
     verbose(msg) {
         if (isVerbose()) {
             process.stderr.write(`${styleText('dim', '[verbose]')} ${msg}\n`);
         }
     },
-    /** Debug output (only when DEBUG includes 'opencli') */
+    /** @deprecated Use log.verbose() instead. Kept as alias for backward compatibility. */
     debug(msg) {
-        if (isDebug()) {
-            process.stderr.write(`${styleText('dim', '[debug]')} ${msg}\n`);
-        }
+        this.verbose(msg);
     },
     /** Step-style debug (for pipeline steps, etc.) */
     step(stepNum, total, op, preview = '') {

package/dist/src/main.js

@@ -45,14 +45,15 @@ if (argv[0] === 'completion' && argv.length >= 2) {
 // Fast path: --get-completions — read from manifest, skip discovery
 const getCompIdx = process.argv.indexOf('--get-completions');
 if (getCompIdx !== -1) {
-    // Only require manifest for directories that actually exist.
-    // If user clis dir doesn't exist, there are no user adapters to miss.
+    // 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(USER_CLIS);
-        manifestPaths.push(getCliManifestPath(USER_CLIS));
+        fs.accessSync(userManifest);
+        manifestPaths.push(userManifest);
     }
-    catch { /* no user dir */ }
+    catch { /* no user manifest */ }
     if (hasAllManifests(manifestPaths)) {
         const rest = process.argv.slice(getCompIdx + 1);
         let cursor;