@jackwener/opencli 1.6.0 → 1.6.2

package/src/launcher.ts

@@ -11,6 +11,7 @@
 
 import { execFileSync, spawn } from 'node:child_process';
 import { request as httpRequest } from 'node:http';
+import * as path from 'node:path';
 import type { ElectronAppEntry } from './electron-apps.js';
 import { getElectronApp } from './electron-apps.js';
 import { confirmPrompt } from './tui.js';
@@ -46,6 +47,7 @@ export function probeCDP(port: number, timeoutMs: number = PROBE_TIMEOUT_MS): Pr
  * Uses pgrep on macOS/Linux.
  */
 export function detectProcess(processName: string): boolean {
+  if (process.platform === 'win32') return false; // pgrep not available on Windows
   try {
     execFileSync('pgrep', ['-x', processName], { encoding: 'utf-8', stdio: 'pipe' });
     return true;
@@ -58,6 +60,7 @@ export function detectProcess(processName: string): boolean {
  * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
  */
 export function killProcess(processName: string): void {
+  if (process.platform === 'win32') return; // pkill not available on Windows
   try {
     execFileSync('pkill', ['-x', processName], { stdio: 'pipe' });
   } catch {
@@ -101,6 +104,78 @@ function resolveExecutable(appPath: string, processName: string): string {
   return `${appPath}/Contents/MacOS/${processName}`;
 }
 
+function isMissingExecutableError(err: unknown, label: string): boolean {
+  return err instanceof CommandExecutionError
+    && err.message.startsWith(`Could not launch ${label}: executable not found at `);
+}
+
+export function resolveExecutableCandidates(appPath: string, app: ElectronAppEntry): string[] {
+  const executableNames = app.executableNames?.length ? app.executableNames : [app.processName];
+  return [...new Set(executableNames)].map((name) => resolveExecutable(appPath, name));
+}
+
+export async function launchDetachedApp(executable: string, args: string[], label: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(executable, args, {
+      detached: true,
+      stdio: 'ignore',
+    });
+
+    const onError = (err: NodeJS.ErrnoException): void => {
+      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: string, app: ElectronAppEntry, args: string[], label: string): Promise<void> {
+  const executables = resolveExecutableCandidates(appPath, app);
+  let lastMissingExecutableError: CommandExecutionError | undefined;
+
+  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 as CommandExecutionError;
+        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: number): Promise<void> {
   const deadline = Date.now() + POLL_TIMEOUT_MS;
   while (Date.now() < deadline) {
@@ -138,7 +213,17 @@ export async function resolveElectronEndpoint(site: string): Promise<string> {
     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`);
@@ -166,15 +251,8 @@ export async function resolveElectronEndpoint(site: string): Promise<string> {
   }
 
   // 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`);

package/src/output.test.ts

@@ -1,109 +1,69 @@
-/**
- * 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);
-  });
+describe('output TTY detection', () => {
+  const originalIsTTY = process.stdout.isTTY;
+  const originalEnv = process.env.OUTPUT;
+  let logSpy: ReturnType<typeof vi.spyOn>;
 
-  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' });
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
   });
 
-  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();
+  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('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('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: any[]) => c[0]).join('\n');
+    expect(out).toContain('name: alice');
+    expect(out).toContain('score: 10');
   });
 
-  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('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: any[]) => c[0]).join('\n');
+    expect(out).toContain('alice');
   });
 
-  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('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: any[]) => c[0]).join('\n');
+    expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
   });
 
-  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('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: any[]) => c[0]).join('\n');
+    expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
   });
 
-  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('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: any[]) => c[0]).join('\n');
+    expect(out).toContain('name');
+    expect(out).toContain('alice');
+    expect(out).not.toContain('"name"');  // not JSON
   });
 
-  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',
-    ]);
+  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: any[]) => c[0]).join('\n');
+    // Should be table output, not YAML
+    expect(out).not.toContain('name: alice');
+    expect(out).toContain('alice');
   });
 });

package/src/output.ts

@@ -8,6 +8,8 @@ import yaml from 'js-yaml';
 
 export interface RenderOptions {
   fmt?: string;
+  /** True when the user explicitly passed -f on the command line */
+  fmtExplicit?: boolean;
   columns?: string[];
   title?: string;
   elapsed?: number;
@@ -26,7 +28,14 @@ function resolveColumns(rows: Record<string, unknown>[], opts: RenderOptions): s
 }
 
 export function render(data: unknown, opts: RenderOptions = {}): void {
-  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/src/pipeline/executor.test.ts

@@ -20,8 +20,6 @@ function createMockPage(overrides: Partial<IPage> = {}): IPage {
     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/src/pipeline/steps/download.test.ts

@@ -34,8 +34,6 @@ function createMockPage(getCookies: IPage['getCookies']): IPage {
     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/src/registry.ts

@@ -17,6 +17,7 @@ export interface Arg {
   type?: string;
   default?: unknown;
   required?: boolean;
+  valueRequired?: boolean;
   positional?: boolean;
   help?: string;
   choices?: string[];
@@ -47,6 +48,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/src/serialization.ts

@@ -14,6 +14,7 @@ export type SerializedArg = {
   name: string;
   type: string;
   required: boolean;
+  valueRequired: boolean;
   positional: boolean;
   choices: string[];
   default: unknown;
@@ -26,6 +27,7 @@ export function serializeArg(a: Arg): SerializedArg {
     name: a.name,
     type: a.type ?? 'string',
     required: !!a.required,
+    valueRequired: !!a.valueRequired,
     positional: !!a.positional,
     choices: a.choices ?? [],
     default: a.default ?? null,

package/src/types.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>;
@@ -67,11 +67,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>;

package/tests/e2e/browser-auth.test.ts

@@ -105,6 +105,15 @@ describe('login-required commands — graceful failure', () => {
     await expectGracefulAuthFailure(['xiaohongshu', 'notifications', '--limit', '3', '-f', 'json']);
   }, 60_000);
 
+  // ── yuanbao (requires login) ──
+  it('yuanbao new fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['yuanbao', 'new', '-f', 'json']);
+  }, 60_000);
+
+  it('yuanbao ask fails gracefully without login', async () => {
+    await expectGracefulAuthFailure(['yuanbao', 'ask', '你好', '-f', 'json']);
+  }, 60_000);
+
   // ── pixiv (requires login) ──
   it('pixiv ranking fails gracefully without login', async () => {
     await expectGracefulAuthFailure(['pixiv', 'ranking', '--limit', '3', '-f', 'json']);