@jackwener/opencli 1.6.1 → 1.6.2

package/src/clis/zhihu/question.test.ts

@@ -1,30 +1,29 @@
 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: unknown, args: { questionId: string; answerLimit: number }) => {
-      expect(args).toEqual({ questionId: '2021881398772981878', answerLimit: 3 });
+    const goto = vi.fn().mockResolvedValue(undefined);
+    const evaluate = vi.fn().mockImplementation(async (js: string) => {
+      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,
-    } as any;
+    const page = { goto, evaluate } as any;
 
     await expect(
       cmd!.func!(page, { id: '2021881398772981878', limit: 3 }),
@@ -37,15 +36,15 @@ describe('zhihu question', () => {
       },
     ]);
 
+    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 }),
     } as any;
 
     await expect(
@@ -53,19 +52,45 @@ describe('zhihu question', () => {
     ).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 = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn().mockResolvedValue({ __httpError: 500 }),
+    } as any;
 
+    await expect(
+      cmd!.func!(page, { id: '2021881398772981878', limit: 3 }),
+    ).rejects.toMatchObject({
+      code: 'FETCH_ERROR',
+      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 = {
-      evaluate: vi.fn().mockResolvedValue({ ok: false, status: 500 }),
+      goto: vi.fn().mockResolvedValue(undefined),
+      evaluate: vi.fn().mockResolvedValue(null),
     } as any;
 
     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',
     });
   });
+
+  it('rejects non-numeric question IDs', async () => {
+    const cmd = getRegistry().get('zhihu/question');
+    const page = { goto: vi.fn(), evaluate: vi.fn() } as any;
+
+    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/src/clis/zhihu/question.ts

@@ -1,6 +1,16 @@
 import { cli, Strategy } from '../../registry.js';
 import { AuthRequiredError, CliError } from '../../errors.js';
 
+function stripHtml(html: string): string {
+  return html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .trim();
+}
+
 cli({
   site: 'zhihu',
   name: 'question',
@@ -14,45 +24,40 @@ 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: string) =>
-      (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').trim();
+    await page.goto(`https://www.zhihu.com/question/${questionId}`);
 
-    // 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 as any).evaluate(
-      async ({ questionId, answerLimit }: { questionId: string; answerLimit: number }) => {
-        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 as const, status: aResp.status };
-        const a = await aResp.json();
-        return { ok: true as const, answers: Array.isArray(a?.data) ? a.data : [] };
-      },
-      { questionId: String(id), answerLimit },
-    );
+    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: any = 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 (!result?.ok) {
-      if (result?.status === 401 || result?.status === 403) {
+    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'}`,
+        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: any, i: number) => ({
+    return (data.data || []).map((item: any, i: number) => ({
       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/src/commanderAdapter.test.ts

@@ -125,6 +125,57 @@ describe('commanderAdapter boolean alias support', () => {
   });
 });
 
+describe('commanderAdapter value-required optional options', () => {
+  const cmd: CliCommand = {
+    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: CliCommand = {
     site: 'notebooklm',

package/src/commanderAdapter.ts

@@ -62,7 +62,8 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
       subCmd.argument(bracket, arg.help ?? '');
       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) subCmd.option(flag, arg.help ?? '', String(arg.default));
       else subCmd.option(flag, arg.help ?? '');
@@ -93,9 +94,11 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
         const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
         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) {
         const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
@@ -109,7 +112,7 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
       }
 
       const resolved = getRegistry().get(fullName(cmd)) ?? cmd;
-      if (format === 'table' && resolved.defaultFormat) {
+      if (!formatExplicit && format === 'table' && resolved.defaultFormat) {
         format = resolved.defaultFormat;
       }
 
@@ -118,6 +121,7 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
       }
       renderOutput(result, {
         fmt: format,
+        fmtExplicit: formatExplicit,
         columns: resolved.columns,
         title: `${resolved.site}/${resolved.name}`,
         elapsed: (Date.now() - startTime) / 1000,
@@ -209,7 +213,7 @@ async function renderError(err: unknown, cmdName: string, verbose: boolean): Pro
   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;
   }
 
@@ -270,7 +274,7 @@ async function renderError(err: unknown, cmdName: string, verbose: boolean): Pro
 
   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/src/completion.test.ts

@@ -0,0 +1,30 @@
+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/src/completion.ts

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

package/src/doctor.ts

@@ -84,7 +84,7 @@ export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<Doctor
   }
   if (status.running && !status.extensionConnected) {
     issues.push(
-      'Daemon is running but the Chrome extension is not connected.\n' +
+      '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/src/electron-apps.ts

@@ -15,6 +15,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 */
@@ -30,7 +32,13 @@ export const builtinApps: Record<string, ElectronAppEntry> = {
   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' },
 };
 

package/src/errors.ts

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

package/src/execution.ts

@@ -21,7 +21,7 @@ import { emitHook, type HookContext } 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<string>();
 
@@ -131,23 +131,6 @@ function ensureRequiredEnv(cmd: CliCommand): void {
   );
 }
 
-/**
- * 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: IPage, targetUrl: string): Promise<boolean> {
-  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: CliCommand,
   rawKwargs: CommandArgs,
@@ -156,6 +139,7 @@ export async function executeCommand(
   let kwargs: CommandArgs;
   try {
     kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
+    cmd.validateArgs?.(kwargs);
   } catch (err) {
     if (err instanceof ArgumentError) throw err;
     throw new ArgumentError(getErrorMessage(err));
@@ -175,8 +159,20 @@ export async function executeCommand(
       let cdpEndpoint: string | undefined;
 
       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.
         // 300ms timeout avoids a full 2s wait on cold-start.
@@ -186,7 +182,7 @@ export async function executeCommand(
             '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',
           );
         }
@@ -197,15 +193,15 @@ export async function executeCommand(
       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');
-          } 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}`);
-            }
+          // 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);
+          } 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/src/explore.ts

@@ -386,7 +386,7 @@ export async function exploreUrl(
            const clicks = await page.evaluate(INTERACT_FUZZ_JS);
            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)}`);
          }
       }
 

package/src/launcher.test.ts

@@ -1,13 +1,34 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { probeCDP, detectProcess, discoverAppPath } from './launcher.js';
+import type { ElectronAppEntry } from './electron-apps.js';
+import { detectProcess, discoverAppPath, launchDetachedApp, launchElectronApp, probeCDP, resolveExecutableCandidates } from './launcher.js';
+
+interface MockChildProcess {
+  once: ReturnType<typeof vi.fn>;
+  off: ReturnType<typeof vi.fn>;
+  unref: ReturnType<typeof vi.fn>;
+  emit: (event: string, value?: unknown) => void;
+}
+
+function createMockChildProcess(): MockChildProcess {
+  const listeners = new Map<string, Array<(value?: unknown) => void>>();
+
+  return {
+    once: vi.fn((event: string, handler: (value?: unknown) => void) => {
+      listeners.set(event, [...(listeners.get(event) ?? []), handler]);
+    }),
+    off: vi.fn((event: string, handler: (value?: unknown) => void) => {
+      listeners.set(event, (listeners.get(event) ?? []).filter((listener) => listener !== handler));
+    }),
+    unref: vi.fn(),
+    emit: (event: string, value?: unknown) => {
+      for (const listener of listeners.get(event) ?? []) listener(value);
+    },
+  };
+}
 
 vi.mock('node:child_process', () => ({
   execFileSync: vi.fn(),
-  spawn: vi.fn(() => ({
-    unref: vi.fn(),
-    pid: 12345,
-    on: vi.fn(),
-  })),
+  spawn: vi.fn(),
 }));
 
 const cp = vi.mocked(await import('node:child_process'));
@@ -34,7 +55,7 @@ describe('detectProcess', () => {
     expect(result).toBe(false);
   });
 
-  it('returns true when pgrep finds a process', () => {
+  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);
@@ -65,3 +86,96 @@ describe('discoverAppPath', () => {
     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 as unknown as ReturnType<typeof cp.spawn>;
+    });
+
+    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 as unknown as ReturnType<typeof cp.spawn>;
+    });
+
+    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: ElectronAppEntry = {
+      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: ElectronAppEntry = {
+      port: 9234,
+      processName: 'Antigravity',
+      executableNames: ['Electron', 'Antigravity'],
+    };
+
+    cp.spawn
+      .mockImplementationOnce(() => {
+        queueMicrotask(() => firstChild.emit('error', Object.assign(new Error('missing binary'), { code: 'ENOENT' })));
+        return firstChild as unknown as ReturnType<typeof cp.spawn>;
+      })
+      .mockImplementationOnce(() => {
+        queueMicrotask(() => secondChild.emit('spawn'));
+        return secondChild as unknown as ReturnType<typeof cp.spawn>;
+      });
+
+    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);
+  });
+});