@jackwener/opencli 1.6.1 → 1.6.2

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);

package/dist/launcher.test.js

@@ -1,12 +1,24 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { probeCDP, detectProcess, discoverAppPath } from './launcher.js';
+import { detectProcess, discoverAppPath, launchDetachedApp, launchElectronApp, probeCDP, resolveExecutableCandidates } from './launcher.js';
+function createMockChildProcess() {
+    const listeners = new Map();
+    return {
+        once: vi.fn((event, handler) => {
+            listeners.set(event, [...(listeners.get(event) ?? []), handler]);
+        }),
+        off: vi.fn((event, handler) => {
+            listeners.set(event, (listeners.get(event) ?? []).filter((listener) => listener !== handler));
+        }),
+        unref: vi.fn(),
+        emit: (event, value) => {
+            for (const listener of listeners.get(event) ?? [])
+                listener(value);
+        },
+    };
+}
 vi.mock('node:child_process', () => ({
     execFileSync: vi.fn(),
-    spawn: vi.fn(() => ({
-        unref: vi.fn(),
-        pid: 12345,
-        on: vi.fn(),
-    })),
+    spawn: vi.fn(),
 }));
 const cp = vi.mocked(await import('node:child_process'));
 describe('probeCDP', () => {
@@ -28,7 +40,7 @@ describe('detectProcess', () => {
         const result = detectProcess('NonExistentApp');
         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);
@@ -55,3 +67,72 @@ 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;
+        });
+        await expect(launchDetachedApp('/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], 'Antigravity'))
+            .resolves
+            .toBeUndefined();
+        expect(child.unref).toHaveBeenCalledTimes(1);
+    });
+    it('converts ENOENT into a controlled launch error', async () => {
+        const child = createMockChildProcess();
+        cp.spawn.mockImplementation(() => {
+            queueMicrotask(() => child.emit('error', Object.assign(new Error('missing binary'), { code: 'ENOENT' })));
+            return child;
+        });
+        await expect(launchDetachedApp('/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], 'Antigravity'))
+            .rejects
+            .toThrow('Could not launch Antigravity');
+        expect(child.unref).not.toHaveBeenCalled();
+    });
+});
+describe('resolveExecutableCandidates', () => {
+    it('prefers explicit executable candidates over processName', () => {
+        const app = {
+            port: 9234,
+            processName: 'Antigravity',
+            executableNames: ['Electron', 'Antigravity'],
+        };
+        expect(resolveExecutableCandidates('/Applications/Antigravity.app', app)).toEqual([
+            '/Applications/Antigravity.app/Contents/MacOS/Electron',
+            '/Applications/Antigravity.app/Contents/MacOS/Antigravity',
+        ]);
+    });
+});
+describe('launchElectronApp', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        cp.spawn.mockReset();
+    });
+    it('falls back to the next executable candidate when the first is missing', async () => {
+        const firstChild = createMockChildProcess();
+        const secondChild = createMockChildProcess();
+        const app = {
+            port: 9234,
+            processName: 'Antigravity',
+            executableNames: ['Electron', 'Antigravity'],
+        };
+        cp.spawn
+            .mockImplementationOnce(() => {
+            queueMicrotask(() => firstChild.emit('error', Object.assign(new Error('missing binary'), { code: 'ENOENT' })));
+            return firstChild;
+        })
+            .mockImplementationOnce(() => {
+            queueMicrotask(() => secondChild.emit('spawn'));
+            return secondChild;
+        });
+        await expect(launchElectronApp('/Applications/Antigravity.app', app, ['--remote-debugging-port=9234'], 'Antigravity')).resolves.toBeUndefined();
+        expect(cp.spawn).toHaveBeenNthCalledWith(1, '/Applications/Antigravity.app/Contents/MacOS/Electron', ['--remote-debugging-port=9234'], { detached: true, stdio: 'ignore' });
+        expect(cp.spawn).toHaveBeenNthCalledWith(2, '/Applications/Antigravity.app/Contents/MacOS/Antigravity', ['--remote-debugging-port=9234'], { detached: true, stdio: 'ignore' });
+        expect(secondChild.unref).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/output.d.ts

@@ -3,6 +3,8 @@
  */
 export interface RenderOptions {
     fmt?: string;
+    /** True when the user explicitly passed -f on the command line */
+    fmtExplicit?: boolean;
     columns?: string[];
     title?: string;
     elapsed?: number;

package/dist/output.js

@@ -15,7 +15,16 @@ function resolveColumns(rows, opts) {
     return opts.columns ?? Object.keys(rows[0] ?? {});
 }
 export function render(data, opts = {}) {
-    const fmt = opts.fmt ?? 'table';
+    let fmt = opts.fmt ?? 'table';
+    // Non-TTY auto-downgrade only when format was NOT explicitly passed by user.
+    // Priority: explicit -f (any value) > OUTPUT env var > TTY auto-detect > table
+    if (!opts.fmtExplicit) {
+        const envFmt = process.env.OUTPUT?.trim().toLowerCase();
+        if (envFmt)
+            fmt = envFmt;
+        else if (fmt === 'table' && !process.stdout.isTTY)
+            fmt = 'yaml';
+    }
     if (data === null || data === undefined) {
         console.log(data);
         return;

package/dist/output.test.d.ts

@@ -1,4 +1 @@
-/**
- * Tests for output.ts: render function format coverage.
- */
 export {};

package/dist/output.test.js

@@ -1,95 +1,62 @@
-/**
- * Tests for output.ts: render function format coverage.
- */
-import { describe, it, expect, vi, afterEach } from 'vitest';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { render } from './output.js';
-afterEach(() => {
-    vi.restoreAllMocks();
-});
-describe('render', () => {
-    it('renders JSON output', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ title: 'Hello', rank: 1 }], { fmt: 'json' });
-        expect(log).toHaveBeenCalledOnce();
-        const output = log.mock.calls[0]?.[0];
-        const parsed = JSON.parse(output);
-        expect(parsed).toEqual([{ title: 'Hello', rank: 1 }]);
-    });
-    it('renders Markdown table output', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ name: 'Alice', score: 100 }], { fmt: 'md', columns: ['name', 'score'] });
-        const calls = log.mock.calls.map(c => c[0]);
-        expect(calls[0]).toContain('| name | score |');
-        expect(calls[1]).toContain('| --- | --- |');
-        expect(calls[2]).toContain('| Alice | 100 |');
-    });
-    it('renders CSV output with proper quoting', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ name: 'Alice, Bob', value: 'say "hi"' }], { fmt: 'csv' });
-        const calls = log.mock.calls.map(c => c[0]);
-        // Header
-        expect(calls[0]).toBe('name,value');
-        // Values with commas/quotes are quoted
-        expect(calls[1]).toContain('"Alice, Bob"');
-        expect(calls[1]).toContain('"say ""hi"""');
-    });
-    it('handles null and undefined data', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render(null, { fmt: 'json' });
-        expect(log).toHaveBeenCalledWith(null);
-    });
-    it('renders single object as single-row table', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render({ title: 'Test' }, { fmt: 'json' });
-        const output = log.mock.calls[0]?.[0];
-        const parsed = JSON.parse(output);
-        expect(parsed).toEqual({ title: 'Test' });
-    });
-    it('handles empty array gracefully', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([], { fmt: 'table' });
-        // Should show "(no data)" for empty arrays
-        expect(log).toHaveBeenCalled();
-    });
-    it('uses custom columns for CSV', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ a: 1, b: 2, c: 3 }], { fmt: 'csv', columns: ['a', 'c'] });
-        const calls = log.mock.calls.map(c => c[0]);
-        expect(calls[0]).toBe('a,c');
-        expect(calls[1]).toBe('1,3');
-    });
-    it('renders YAML output', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ title: 'Hello', rank: 1 }], { fmt: 'yaml' });
-        expect(log).toHaveBeenCalledOnce();
-        expect(log.mock.calls[0]?.[0]).toContain('- title: Hello');
-        expect(log.mock.calls[0]?.[0]).toContain('rank: 1');
-    });
-    it('renders yml alias as YAML output', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render({ title: 'Hello' }, { fmt: 'yml' });
-        expect(log).toHaveBeenCalledOnce();
-        expect(log.mock.calls[0]?.[0]).toContain('title: Hello');
-    });
-    it('handles null values in CSV cells', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ name: 'test', value: null }], { fmt: 'csv' });
-        const calls = log.mock.calls.map(c => c[0]);
-        expect(calls[1]).toBe('test,');
-    });
-    it('renders single-field rows in plain mode as the bare value', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ response: 'Gemini says hi' }], { fmt: 'plain' });
-        expect(log).toHaveBeenCalledWith('Gemini says hi');
-    });
-    it('renders multi-field rows in plain mode as key-value lines', () => {
-        const log = vi.spyOn(console, 'log').mockImplementation(() => { });
-        render([{ status: 'ok', file: '~/tmp/a.png', link: 'https://example.com' }], { fmt: 'plain' });
-        const calls = log.mock.calls.map(c => c[0]);
-        expect(calls).toEqual([
-            'status: ok',
-            'file: ~/tmp/a.png',
-            'link: https://example.com',
-        ]);
+describe('output TTY detection', () => {
+    const originalIsTTY = process.stdout.isTTY;
+    const originalEnv = process.env.OUTPUT;
+    let logSpy;
+    beforeEach(() => {
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: originalIsTTY, writable: true });
+        if (originalEnv === undefined)
+            delete process.env.OUTPUT;
+        else
+            process.env.OUTPUT = originalEnv;
+        logSpy.mockRestore();
+    });
+    it('outputs YAML in non-TTY when format is default table', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        // commanderAdapter always passes fmt:'table' as default — this must still trigger downgrade
+        render([{ name: 'alice', score: 10 }], { fmt: 'table', columns: ['name', 'score'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('name: alice');
+        expect(out).toContain('score: 10');
+    });
+    it('outputs table in TTY when format is default table', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, writable: true });
+        render([{ name: 'alice', score: 10 }], { fmt: 'table', columns: ['name', 'score'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('alice');
+    });
+    it('respects explicit -f json even in non-TTY', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        render([{ name: 'alice' }], { fmt: 'json' });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
+    });
+    it('OUTPUT env var overrides default table in non-TTY', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        process.env.OUTPUT = 'json';
+        render([{ name: 'alice' }], { fmt: 'table' });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
+    });
+    it('explicit -f flag takes precedence over OUTPUT env var', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        process.env.OUTPUT = 'json';
+        render([{ name: 'alice' }], { fmt: 'csv', fmtExplicit: true });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('name');
+        expect(out).toContain('alice');
+        expect(out).not.toContain('"name"'); // not JSON
+    });
+    it('explicit -f table overrides non-TTY auto-downgrade', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
+        render([{ name: 'alice' }], { fmt: 'table', fmtExplicit: true, columns: ['name'] });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        // Should be table output, not YAML
+        expect(out).not.toContain('name: alice');
+        expect(out).toContain('alice');
     });
 });

package/dist/pipeline/executor.test.js

@@ -17,8 +17,6 @@ function createMockPage(overrides = {}) {
         getFormState: vi.fn().mockResolvedValue({}),
         wait: vi.fn(),
         tabs: vi.fn().mockResolvedValue([]),
-        closeTab: vi.fn(),
-        newTab: vi.fn(),
         selectTab: vi.fn(),
         networkRequests: vi.fn().mockResolvedValue([]),
         consoleMessages: vi.fn().mockResolvedValue(''),

package/dist/pipeline/steps/download.test.js

@@ -29,8 +29,6 @@ function createMockPage(getCookies) {
         getFormState: vi.fn().mockResolvedValue({}),
         wait: vi.fn(),
         tabs: vi.fn().mockResolvedValue([]),
-        closeTab: vi.fn(),
-        newTab: vi.fn(),
         selectTab: vi.fn(),
         networkRequests: vi.fn().mockResolvedValue([]),
         consoleMessages: vi.fn().mockResolvedValue([]),

package/dist/registry.d.ts

@@ -14,6 +14,7 @@ export interface Arg {
     type?: string;
     default?: unknown;
     required?: boolean;
+    valueRequired?: boolean;
     positional?: boolean;
     help?: string;
     choices?: string[];
@@ -40,6 +41,7 @@ export interface CliCommand {
     source?: string;
     footerExtra?: (kwargs: CommandArgs) => string | undefined;
     requiredEnv?: RequiredEnv[];
+    validateArgs?: (kwargs: CommandArgs) => void;
     /** Deprecation note shown in help / execution warnings. */
     deprecated?: boolean | string;
     /** Preferred replacement command, if any. */

package/dist/serialization.d.ts

@@ -9,6 +9,7 @@ export type SerializedArg = {
     name: string;
     type: string;
     required: boolean;
+    valueRequired: boolean;
     positional: boolean;
     choices: string[];
     default: unknown;

package/dist/serialization.js

@@ -11,6 +11,7 @@ export function serializeArg(a) {
         name: a.name,
         type: a.type ?? 'string',
         required: !!a.required,
+        valueRequired: !!a.valueRequired,
         positional: !!a.positional,
         choices: a.choices ?? [],
         default: a.default ?? null,

package/dist/types.d.ts

@@ -56,8 +56,8 @@ export interface IPage {
     getFormState(): Promise<any>;
     wait(options: number | WaitOptions): Promise<void>;
     tabs(): Promise<any>;
-    closeTab(index?: number): Promise<void>;
-    newTab(): Promise<void>;
+    closeTab?(index?: number): Promise<void>;
+    newTab?(): Promise<void>;
     selectTab(index: number): Promise<void>;
     networkRequests(includeStatic?: boolean): Promise<any>;
     consoleMessages(level?: string): Promise<any>;
@@ -70,11 +70,18 @@ export interface IPage {
     getInterceptedRequests(): Promise<any[]>;
     waitForCapture(timeout?: number): Promise<void>;
     screenshot(options?: ScreenshotOptions): Promise<string>;
+    startNetworkCapture?(pattern?: string): Promise<void>;
+    readNetworkCapture?(): Promise<unknown[]>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly — no base64 encoding or payload size limits.
      */
     setFileInput?(files: string[], selector?: string): Promise<void>;
+    /**
+     * Insert text via native CDP Input.insertText into the currently focused element.
+     * Useful for rich editors that ignore synthetic DOM value/text mutations.
+     */
+    insertText?(text: string): Promise<void>;
     closeWindow?(): Promise<void>;
     /** Returns the current page URL, or null if unavailable. */
     getCurrentUrl?(): Promise<string | null>;