@jackwener/opencli 1.6.0 → 1.6.2

package/dist/clis/yuanbao/shared.js

@@ -0,0 +1,49 @@
+import { AuthRequiredError } from '../../errors.js';
+export const YUANBAO_DOMAIN = 'yuanbao.tencent.com';
+export const YUANBAO_URL = 'https://yuanbao.tencent.com/';
+const SESSION_HINT = 'Likely login/auth/challenge/session issue in the existing yuanbao.tencent.com browser session.';
+/**
+ * Reusable visibility check for injected browser scripts.
+ * Embed in page.evaluate strings via `${IS_VISIBLE_JS}`.
+ */
+export const IS_VISIBLE_JS = `const isVisible = (node) => {
+  if (!(node instanceof HTMLElement)) return false;
+  const rect = node.getBoundingClientRect();
+  const style = window.getComputedStyle(node);
+  return rect.width > 0
+    && rect.height > 0
+    && style.display !== 'none'
+    && style.visibility !== 'hidden';
+};`;
+export function authRequired(message) {
+    return new AuthRequiredError(YUANBAO_DOMAIN, `${message} ${SESSION_HINT}`);
+}
+export async function isOnYuanbao(page) {
+    const url = await page.evaluate('window.location.href').catch(() => '');
+    if (typeof url !== 'string' || !url)
+        return false;
+    try {
+        const hostname = new URL(url).hostname;
+        return hostname === YUANBAO_DOMAIN || hostname.endsWith(`.${YUANBAO_DOMAIN}`);
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureYuanbaoPage(page) {
+    if (!(await isOnYuanbao(page))) {
+        await page.goto(YUANBAO_URL, { waitUntil: 'load', settleMs: 2500 });
+        await page.wait(1);
+    }
+}
+export async function hasLoginGate(page) {
+    const result = await page.evaluate(`(() => {
+    const bodyText = document.body.innerText || '';
+    const hasWechatLoginText = bodyText.includes('微信扫码登录');
+    const hasWechatIframe = Array.from(document.querySelectorAll('iframe'))
+      .some((frame) => (frame.getAttribute('src') || '').includes('open.weixin.qq.com/connect/qrconnect'));
+
+    return hasWechatLoginText || hasWechatIframe;
+  })()`);
+    return Boolean(result);
+}

package/dist/clis/zhihu/question.js

@@ -1,5 +1,14 @@
 import { cli, Strategy } from '../../registry.js';
 import { AuthRequiredError, CliError } from '../../errors.js';
+function stripHtml(html) {
+    return html
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+        .trim();
+}
 cli({
     site: 'zhihu',
     name: 'question',
@@ -13,30 +22,32 @@ cli({
     columns: ['rank', 'author', 'votes', 'content'],
     func: async (page, kwargs) => {
         const { id, limit = 5 } = kwargs;
+        const questionId = String(id);
+        if (!/^\d+$/.test(questionId)) {
+            throw new CliError('INVALID_INPUT', 'Question ID must be numeric', 'Example: opencli zhihu question 123456789');
+        }
         const answerLimit = Number(limit);
-        const stripHtml = (html) => (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').trim();
-        // Only fetch answers here. The question detail endpoint is not used by the
-        // current CLI output and can fail independently, which would incorrectly
-        // turn a successful answers response into a login error.
-        const result = await page.evaluate(async ({ questionId, answerLimit }) => {
-            const aResp = await fetch(`https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${answerLimit}&offset=0&sort_by=default&include=data[*].content,voteup_count,comment_count,author`, { credentials: 'include' });
-            if (!aResp.ok)
-                return { ok: false, status: aResp.status };
-            const a = await aResp.json();
-            return { ok: true, answers: Array.isArray(a?.data) ? a.data : [] };
-        }, { questionId: String(id), answerLimit });
-        if (!result?.ok) {
-            if (result?.status === 401 || result?.status === 403) {
+        await page.goto(`https://www.zhihu.com/question/${questionId}`);
+        const url = `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${answerLimit}&offset=0&sort_by=default&include=data[*].content,voteup_count,comment_count,author`;
+        const data = await page.evaluate(`
+      (async () => {
+        const r = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+        if (!r.ok) return { __httpError: r.status };
+        return await r.json();
+      })()
+    `);
+        if (!data || data.__httpError) {
+            const status = data?.__httpError;
+            if (status === 401 || status === 403) {
                 throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch question data from Zhihu');
             }
-            throw new CliError('FETCH_ERROR', `Zhihu question answers request failed with HTTP ${result?.status ?? 'unknown'}`, 'Try again later or rerun with -v for more detail');
+            throw new CliError('FETCH_ERROR', status ? `Zhihu question answers request failed (HTTP ${status})` : 'Zhihu question answers request failed', 'Try again later or rerun with -v for more detail');
         }
-        const answers = result.answers.slice(0, answerLimit).map((a, i) => ({
+        return (data.data || []).map((item, i) => ({
             rank: i + 1,
-            author: a.author?.name ?? 'anonymous',
-            votes: a.voteup_count ?? 0,
-            content: stripHtml(a.content ?? '').slice(0, 200),
+            author: item.author?.name || 'anonymous',
+            votes: item.voteup_count || 0,
+            content: stripHtml(item.content || '').substring(0, 200),
         }));
-        return answers;
     },
 });

package/dist/clis/zhihu/question.test.js

@@ -1,27 +1,26 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '../../registry.js';
-import { AuthRequiredError } from '../../errors.js';
+import { AuthRequiredError, CliError } from '../../errors.js';
 import './question.js';
 describe('zhihu question', () => {
-    it('returns answers even when the unused question detail request fails', async () => {
+    it('returns answers from the Zhihu API', async () => {
         const cmd = getRegistry().get('zhihu/question');
         expect(cmd?.func).toBeTypeOf('function');
-        const evaluate = vi.fn().mockImplementation(async (_fn, args) => {
-            expect(args).toEqual({ questionId: '2021881398772981878', answerLimit: 3 });
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            expect(js).toContain('questions/2021881398772981878/answers?limit=3');
+            expect(js).toContain("credentials: 'include'");
             return {
-                ok: true,
-                answers: [
+                data: [
                     {
                         author: { name: 'alice' },
                         voteup_count: 12,
-                        content: '<p>Hello <b>Zhihu</b></p>',
+                        content: 'Hello Zhihu',
                     },
                 ],
             };
         });
-        const page = {
-            evaluate,
-        };
+        const page = { goto, evaluate };
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).resolves.toEqual([
             {
                 rank: 1,
@@ -30,25 +29,44 @@ describe('zhihu question', () => {
                 content: 'Hello Zhihu',
             },
         ]);
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/question/2021881398772981878');
         expect(evaluate).toHaveBeenCalledTimes(1);
     });
     it('maps auth-like answer failures to AuthRequiredError', async () => {
         const cmd = getRegistry().get('zhihu/question');
-        expect(cmd?.func).toBeTypeOf('function');
         const page = {
-            evaluate: vi.fn().mockResolvedValue({ ok: false, status: 403 }),
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 403 }),
         };
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).rejects.toBeInstanceOf(AuthRequiredError);
     });
-    it('preserves non-auth fetch failures as CliError instead of login errors', async () => {
+    it('preserves non-auth fetch failures as CliError', async () => {
         const cmd = getRegistry().get('zhihu/question');
-        expect(cmd?.func).toBeTypeOf('function');
         const page = {
-            evaluate: vi.fn().mockResolvedValue({ ok: false, status: 500 }),
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 500 }),
         };
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).rejects.toMatchObject({
             code: 'FETCH_ERROR',
-            message: 'Zhihu question answers request failed with HTTP 500',
+            message: 'Zhihu question answers request failed (HTTP 500)',
         });
     });
+    it('handles null evaluate response as fetch error', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue(null),
+        };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).rejects.toMatchObject({
+            code: 'FETCH_ERROR',
+            message: 'Zhihu question answers request failed',
+        });
+    });
+    it('rejects non-numeric question IDs', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: "abc'; alert(1); //", limit: 1 })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
 });

package/dist/commanderAdapter.js

@@ -49,7 +49,8 @@ export function registerCommandToProgram(siteCmd, cmd) {
             positionalArgs.push(arg);
         }
         else {
-            const flag = arg.required ? `--${arg.name} <value>` : `--${arg.name} [value]`;
+            const expectsValue = arg.required || arg.valueRequired;
+            const flag = expectsValue ? `--${arg.name} <value>` : `--${arg.name} [value]`;
             if (arg.required)
                 subCmd.requiredOption(flag, arg.help ?? '');
             else if (arg.default != null)
@@ -83,8 +84,10 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 if (v !== undefined)
                     kwargs[arg.name] = normalizeArgValue(arg.type, v, arg.name);
             }
+            cmd.validateArgs?.(kwargs);
             const verbose = optionsRecord.verbose === true;
             let format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
+            const formatExplicit = subCmd.getOptionValueSource('format') === 'cli';
             if (verbose)
                 process.env.OPENCLI_VERBOSE = '1';
             if (cmd.deprecated) {
@@ -97,7 +100,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 return;
             }
             const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
-            if (format === 'table' && resolved.defaultFormat) {
+            if (!formatExplicit && format === 'table' && resolved.defaultFormat) {
                 format = resolved.defaultFormat;
             }
             if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
@@ -105,6 +108,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
             }
             renderOutput(result, {
                 fmt: format,
+                fmtExplicit: formatExplicit,
                 columns: resolved.columns,
                 title: `${resolved.site}/${resolved.name}`,
                 elapsed: (Date.now() - startTime) / 1000,
@@ -198,7 +202,7 @@ async function renderError(err, cmdName, verbose) {
     if (err instanceof AuthRequiredError) {
         console.error(chalk.red(`🔒 Not logged in to ${err.domain}`));
         // Respect custom hints set by the adapter; fall back to generic guidance.
-        console.error(chalk.yellow(`→ ${err.hint ?? `Open Chrome and log in to https://${err.domain}, then retry.`}`));
+        console.error(chalk.yellow(`→ ${err.hint ?? `Open Chrome or Chromium and log in to https://${err.domain}, then retry.`}`));
         return;
     }
     // ── TimeoutError ──────────────────────────────────────────────────────
@@ -255,7 +259,7 @@ async function renderError(err, cmdName, verbose) {
     const kind = classifyGenericError(msg);
     if (kind === 'auth') {
         console.error(chalk.red(`🔒 ${msg}`));
-        console.error(chalk.yellow('→ Open Chrome, log in to the target site, then retry.'));
+        console.error(chalk.yellow('→ Open Chrome or Chromium, log in to the target site, then retry.'));
         return;
     }
     if (kind === 'http') {

package/dist/commanderAdapter.test.js

@@ -100,6 +100,48 @@ describe('commanderAdapter boolean alias support', () => {
         expect(kwargs.undo).toBe(false);
     });
 });
+describe('commanderAdapter value-required optional options', () => {
+    const cmd = {
+        site: 'instagram',
+        name: 'post',
+        description: 'Post to Instagram',
+        browser: true,
+        args: [
+            { name: 'image', valueRequired: true, help: 'Single image path' },
+            { name: 'images', valueRequired: true, help: 'Comma-separated image paths' },
+            { name: 'content', positional: true, required: false, help: 'Caption text' },
+        ],
+        validateArgs: (kwargs) => {
+            if (!kwargs.image && !kwargs.images) {
+                throw new Error('media required');
+            }
+        },
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.OPENCLI_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('requires a value when --image is present', async () => {
+        const program = new Command();
+        program.exitOverride();
+        const siteCmd = program.command('instagram');
+        registerCommandToProgram(siteCmd, cmd);
+        await expect(program.parseAsync(['node', 'opencli', 'instagram', 'post', '--image'])).rejects.toMatchObject({ code: 'commander.optionMissingArgument' });
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+    });
+    it('runs validateArgs before executeCommand so missing media does not dispatch the browser command', async () => {
+        const program = new Command();
+        const siteCmd = program.command('instagram');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'instagram', 'post', 'caption only']);
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+        expect(process.exitCode).toBeDefined();
+    });
+});
 describe('commanderAdapter command aliases', () => {
     const cmd = {
         site: 'notebooklm',

package/dist/completion.js

@@ -21,7 +21,9 @@ const BUILTIN_COMMANDS = [
     'generate',
     'cascade',
     'doctor',
-    'setup',
+    'plugin',
+    'install',
+    'register',
     'completion',
 ];
 /**

package/dist/completion.test.d.ts

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

package/dist/completion.test.js

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+const { mockGetRegistry } = vi.hoisted(() => ({
+    mockGetRegistry: vi.fn(() => new Map([
+        ['github/issues', { site: 'github', name: 'issues' }],
+    ])),
+}));
+vi.mock('./registry.js', () => ({
+    getRegistry: mockGetRegistry,
+}));
+import { getCompletions } from './completion.js';
+describe('getCompletions', () => {
+    it('includes top-level built-ins that are registered outside the site registry', () => {
+        const completions = getCompletions([], 1);
+        expect(completions).toContain('plugin');
+        expect(completions).toContain('install');
+        expect(completions).toContain('register');
+        expect(completions).not.toContain('setup');
+    });
+    it('still includes discovered site names', () => {
+        const completions = getCompletions([], 1);
+        expect(completions).toContain('github');
+    });
+});

package/dist/doctor.js

@@ -55,7 +55,7 @@ export async function runBrowserDoctor(opts = {}) {
         issues.push('Daemon is not running. It should start automatically when you run an opencli browser command.');
     }
     if (status.running && !status.extensionConnected) {
-        issues.push('Daemon is running but the Chrome extension is not connected.\n' +
+        issues.push('Daemon is running but the Chrome/Chromium extension is not connected.\n' +
             'Please install the opencli Browser Bridge extension:\n' +
             '  1. Download from https://github.com/jackwener/opencli/releases\n' +
             '  2. Open chrome://extensions/ → Enable Developer Mode\n' +

package/dist/electron-apps.d.ts

@@ -9,6 +9,8 @@ export interface ElectronAppEntry {
     port: number;
     /** macOS process name for detection via pgrep */
     processName: string;
+    /** Candidate executable names inside Contents/MacOS/, tried in order */
+    executableNames?: string[];
     /** macOS bundle ID for path discovery */
     bundleId?: string;
     /** Human-readable name for prompts */

package/dist/electron-apps.js

@@ -15,7 +15,13 @@ export const builtinApps = {
     notion: { port: 9230, processName: 'Notion', bundleId: 'notion.id', displayName: 'Notion' },
     'discord-app': { port: 9232, processName: 'Discord', bundleId: 'com.discord.app', displayName: 'Discord' },
     'doubao-app': { port: 9225, processName: 'Doubao', bundleId: 'com.volcengine.doubao', displayName: 'Doubao' },
-    antigravity: { port: 9234, processName: 'Antigravity', bundleId: 'dev.antigravity.app', displayName: 'Antigravity' },
+    antigravity: {
+        port: 9234,
+        processName: 'Antigravity',
+        executableNames: ['Electron', 'Antigravity'],
+        bundleId: 'dev.antigravity.app',
+        displayName: 'Antigravity',
+    },
     chatgpt: { port: 9236, processName: 'ChatGPT', bundleId: 'com.openai.chat', displayName: 'ChatGPT' },
 };
 /** Merge builtin + user-defined apps. User entries are additive only. */

package/dist/errors.js

@@ -72,7 +72,7 @@ export class ConfigError extends CliError {
 export class AuthRequiredError extends CliError {
     domain;
     constructor(domain, message) {
-        super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome and log in to https://${domain}`, EXIT_CODES.NOPERM);
+        super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome or Chromium and log in to https://${domain}`, EXIT_CODES.NOPERM);
         this.domain = domain;
     }
 }

package/dist/execution.js

@@ -19,7 +19,7 @@ import { emitHook } from './hooks.js';
 import { checkDaemonStatus } from './browser/discover.js';
 import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
-import { resolveElectronEndpoint } from './launcher.js';
+import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 const _loadedModules = new Set();
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
@@ -111,29 +111,11 @@ function ensureRequiredEnv(cmd) {
         return;
     throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
 }
-/**
- * Check if the browser is already on the target domain, avoiding redundant navigation.
- * Returns true if current page hostname matches the pre-nav URL hostname.
- */
-async function isAlreadyOnDomain(page, targetUrl) {
-    if (!page.getCurrentUrl)
-        return false;
-    try {
-        const currentUrl = await page.getCurrentUrl();
-        if (!currentUrl)
-            return false;
-        const currentHost = new URL(currentUrl).hostname;
-        const targetHost = new URL(targetUrl).hostname;
-        return currentHost === targetHost;
-    }
-    catch {
-        return false;
-    }
-}
 export async function executeCommand(cmd, rawKwargs, debug = false) {
     let kwargs;
     try {
         kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+        cmd.validateArgs?.(kwargs);
     }
     catch (err) {
         if (err instanceof ArgumentError)
@@ -152,8 +134,18 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             const electron = isElectronApp(cmd.site);
             let cdpEndpoint;
             if (electron) {
-                // Electron apps: auto-detect, prompt restart if needed, launch with CDP
-                cdpEndpoint = await resolveElectronEndpoint(cmd.site);
+                // Electron apps: respect manual endpoint override, then try auto-detect
+                const manualEndpoint = process.env.OPENCLI_CDP_ENDPOINT;
+                if (manualEndpoint) {
+                    const port = Number(new URL(manualEndpoint).port);
+                    if (!await probeCDP(port)) {
+                        throw new CommandExecutionError(`CDP not reachable at ${manualEndpoint}`, 'Check that the app is running with --remote-debugging-port and the endpoint is correct.');
+                    }
+                    cdpEndpoint = manualEndpoint;
+                }
+                else {
+                    cdpEndpoint = await resolveElectronEndpoint(cmd.site);
+                }
             }
             else {
                 // Browser Bridge: fail-fast when daemon is up but extension is missing.
@@ -162,7 +154,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
                 if (status.running && !status.extensionConnected) {
                     throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
                         '  1. Download: https://github.com/jackwener/opencli/releases\n' +
-                        '  2. chrome://extensions → Developer Mode → Load unpacked\n' +
+                        '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
                         '  Then run: opencli doctor');
                 }
             }
@@ -171,19 +163,17 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
             result = await browserSession(BrowserFactory, async (page) => {
                 const preNavUrl = resolvePreNav(cmd);
                 if (preNavUrl) {
-                    const skip = await isAlreadyOnDomain(page, preNavUrl);
-                    if (skip) {
-                        if (debug)
-                            log.debug('[pre-nav] Already on target domain, skipping navigation');
+                    // Navigate directly — the extension's handleNavigate already has a fast-path
+                    // that skips navigation if the tab is already at the target URL.
+                    // This avoids an extra exec round-trip (getCurrentUrl) on first command and
+                    // lets the extension create the automation window with the target URL directly
+                    // instead of about:blank.
+                    try {
+                        await page.goto(preNavUrl);
                     }
-                    else {
-                        try {
-                            await page.goto(preNavUrl);
-                        }
-                        catch (err) {
-                            if (debug)
-                                log.debug(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
-                        }
+                    catch (err) {
+                        if (debug)
+                            log.debug(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
                     }
                 }
                 return runWithTimeout(runCommand(cmd, page, kwargs, debug), {

package/dist/explore.js

@@ -263,7 +263,7 @@ export async function exploreUrl(url, opts) {
                     await page.wait(2); // wait for XHRs to settle
                 }
                 catch (e) {
-                    log.debug(`Interactive fuzzing skipped: ${e instanceof Error ? e.message : String(e)}`);
+                    log.verbose(`Interactive fuzzing skipped: ${e instanceof Error ? e.message : String(e)}`);
                 }
             }
             // Step 3: Read page metadata

package/dist/launcher.d.ts

@@ -8,6 +8,7 @@
  * 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.
@@ -28,6 +29,9 @@ export declare function killProcess(processName: string): void;
  * 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.
  *

package/dist/launcher.js

@@ -10,6 +10,7 @@
  */
 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';
@@ -38,6 +39,8 @@ export function probeCDP(port, timeoutMs = PROBE_TIMEOUT_MS) {
  * 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;
@@ -50,6 +53,8 @@ export function detectProcess(processName) {
  * 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' });
     }
@@ -91,6 +96,57 @@ export function discoverAppPath(displayName) {
 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) {
@@ -119,7 +175,13 @@ export async function resolveElectronEndpoint(site) {
         log.debug(`[launcher] CDP already available on port ${port}`);
         return endpoint;
     }
-    // Step 2: Running without CDP?
+    // 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`);
@@ -136,14 +198,8 @@ export async function resolveElectronEndpoint(site) {
         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 executable = resolveExecutable(appPath, processName);
     const args = [`--remote-debugging-port=${port}`, ...(app.extraArgs ?? [])];
-    log.debug(`[launcher] Launching: ${executable} ${args.join(' ')}`);
-    const child = spawn(executable, args, {
-        detached: true,
-        stdio: 'ignore',
-    });
-    child.unref();
+    await launchElectronApp(appPath, app, args, label);
     // Step 5: Poll for readiness
     process.stderr.write(`  Waiting for ${label} on port ${port}...\n`);
     await pollForReady(port);