@jackwener/opencli 1.3.0 → 1.3.2

package/src/errors.ts

@@ -2,11 +2,12 @@
  * Unified error types for opencli.
  *
  * All errors thrown by the framework should extend CliError so that
- * the top-level handler in main.ts can render consistent, helpful output.
+ * the top-level handler in commanderAdapter.ts can render consistent,
+ * helpful output with emoji-coded severity and actionable hints.
  */
 
 export class CliError extends Error {
-  /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'ADAPTER_LOAD') */
+  /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
   readonly code: string;
   /** Human-readable hint on how to fix the problem */
   readonly hint?: string;
@@ -19,6 +20,8 @@ export class CliError extends Error {
   }
 }
 
+// ── Browser / Connection ────────────────────────────────────────────────────
+
 export class BrowserConnectError extends CliError {
   constructor(message: string, hint?: string) {
     super('BROWSER_CONNECT', message, hint);
@@ -26,6 +29,8 @@ export class BrowserConnectError extends CliError {
   }
 }
 
+// ── Adapter loading ─────────────────────────────────────────────────────────
+
 export class AdapterLoadError extends CliError {
   constructor(message: string, hint?: string) {
     super('ADAPTER_LOAD', message, hint);
@@ -33,6 +38,8 @@ export class AdapterLoadError extends CliError {
   }
 }
 
+// ── Command execution ───────────────────────────────────────────────────────
+
 export class CommandExecutionError extends CliError {
   constructor(message: string, hint?: string) {
     super('COMMAND_EXEC', message, hint);
@@ -40,9 +47,92 @@ export class CommandExecutionError extends CliError {
   }
 }
 
+// ── Configuration ───────────────────────────────────────────────────────────
+
 export class ConfigError extends CliError {
   constructor(message: string, hint?: string) {
     super('CONFIG', message, hint);
     this.name = 'ConfigError';
   }
 }
+
+// ── Authentication / Login ──────────────────────────────────────────────────
+
+export class AuthRequiredError extends CliError {
+  readonly domain: string;
+
+  constructor(domain: string, message?: string) {
+    super(
+      'AUTH_REQUIRED',
+      message ?? `Not logged in to ${domain}`,
+      `Please open Chrome and log in to https://${domain}`,
+    );
+    this.name = 'AuthRequiredError';
+    this.domain = domain;
+  }
+}
+
+// ── Timeout ─────────────────────────────────────────────────────────────────
+
+export class TimeoutError extends CliError {
+  constructor(label: string, seconds: number) {
+    super(
+      'TIMEOUT',
+      `${label} timed out after ${seconds}s`,
+      'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var',
+    );
+    this.name = 'TimeoutError';
+  }
+}
+
+// ── Argument validation ─────────────────────────────────────────────────────
+
+export class ArgumentError extends CliError {
+  constructor(message: string, hint?: string) {
+    super('ARGUMENT', message, hint);
+    this.name = 'ArgumentError';
+  }
+}
+
+// ── Empty result ────────────────────────────────────────────────────────────
+
+export class EmptyResultError extends CliError {
+  constructor(command: string, hint?: string) {
+    super(
+      'EMPTY_RESULT',
+      `${command} returned no data`,
+      hint ?? 'The page structure may have changed, or you may need to log in',
+    );
+    this.name = 'EmptyResultError';
+  }
+}
+
+// ── Selector / DOM ──────────────────────────────────────────────────────────
+
+export class SelectorError extends CliError {
+  constructor(selector: string, hint?: string) {
+    super(
+      'SELECTOR',
+      `Could not find element: ${selector}`,
+      hint ?? 'The page UI may have changed. Please report this issue.',
+    );
+    this.name = 'SelectorError';
+  }
+}
+
+// ── Utilities ───────────────────────────────────────────────────────────
+
+/** Extract a human-readable message from an unknown caught value. */
+export function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Error code → emoji mapping for CLI output rendering. */
+export const ERROR_ICONS: Record<string, string> = {
+  AUTH_REQUIRED: '🔒',
+  BROWSER_CONNECT: '🔌',
+  TIMEOUT: '⏱ ',
+  ARGUMENT: '❌',
+  EMPTY_RESULT: '📭',
+  SELECTOR: '🔍',
+};

package/src/execution.ts

@@ -13,7 +13,7 @@ import { type CliCommand, type InternalCliCommand, type Arg, Strategy, getRegist
 import type { IPage } from './types.js';
 import { pathToFileURL } from 'node:url';
 import { executePipeline } from './pipeline/index.js';
-import { AdapterLoadError } from './errors.js';
+import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 
@@ -21,9 +21,6 @@ import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMM
 const _loadedModules = new Set<string>();
 type CommandArgs = Record<string, unknown>;
 
-function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
 
 /**
  * Validates and coerces arguments based on the command's Arg definitions.
@@ -36,7 +33,10 @@ export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): Comm
     
     // 1. Check required
     if (argDef.required && (val === undefined || val === null || val === '')) {
-      throw new Error(`Argument "${argDef.name}" is required.\n${argDef.help ? `Hint: ${argDef.help}` : ''}`);
+      throw new ArgumentError(
+        `Argument "${argDef.name}" is required.`,
+        argDef.help ?? `Provide a value for --${argDef.name}`,
+      );
     }
 
     if (val !== undefined && val !== null) {
@@ -44,7 +44,7 @@ export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): Comm
       if (argDef.type === 'int' || argDef.type === 'number') {
         const num = Number(val);
         if (Number.isNaN(num)) {
-          throw new Error(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
+          throw new ArgumentError(`Argument "${argDef.name}" must be a valid number. Received: "${val}"`);
         }
         result[argDef.name] = num;
       } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
@@ -52,7 +52,7 @@ export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): Comm
           const lower = val.toLowerCase();
           if (lower === 'true' || lower === '1') result[argDef.name] = true;
           else if (lower === 'false' || lower === '0') result[argDef.name] = false;
-          else throw new Error(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
+          else throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
         } else {
           result[argDef.name] = Boolean(val);
         }
@@ -62,7 +62,7 @@ export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): Comm
       const coercedVal = result[argDef.name];
       if (argDef.choices && argDef.choices.length > 0) {
         if (!argDef.choices.map(String).includes(String(coercedVal))) {
-          throw new Error(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
+          throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
         }
       }
     } else if (argDef.default !== undefined) {
@@ -104,7 +104,10 @@ async function runCommand(
 
   if (cmd.func) return cmd.func(page!, kwargs, debug);
   if (cmd.pipeline) return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
-  throw new Error(`Command ${fullName(cmd)} has no func or pipeline`);
+  throw new CommandExecutionError(
+    `Command ${fullName(cmd)} has no func or pipeline`,
+    'This is likely a bug in the adapter definition. Please report this issue.',
+  );
 }
 
 /**
@@ -140,7 +143,8 @@ export async function executeCommand(
   try {
     kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
   } catch (err) {
-    throw new Error(`[Argument Validation Error]\n${getErrorMessage(err)}`);
+    if (err instanceof ArgumentError) throw err;
+    throw new ArgumentError(getErrorMessage(err));
   }
 
   if (shouldUseBrowserSession(cmd)) {

package/src/explore.ts

@@ -15,6 +15,7 @@ import { detectFramework } from './scripts/framework.js';
 import { discoverStores } from './scripts/store.js';
 import { interactFuzz } from './scripts/interact.js';
 import type { IPage } from './types.js';
+import { log } from './logger.js';
 
 // ── Site name detection ────────────────────────────────────────────────────
 
@@ -224,7 +225,8 @@ function flattenFields(obj: unknown, prefix: string, maxDepth: number): string[]
 }
 
 function isBooleanRecord(value: unknown): value is Record<string, boolean> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && Object.values(value as Record<string, unknown>).every(v => typeof v === 'boolean');
 }
 
 function scoreEndpoint(ep: { contentType: string; responseAnalysis: AnalyzedEndpoint['responseAnalysis']; pattern: string; status: number | null; hasSearchParam: boolean; hasPaginationParam: boolean; hasLimitParam: boolean }): number {
@@ -453,7 +455,7 @@ export async function exploreUrl(
            const clicks = await page.evaluate(INTERACT_FUZZ_JS);
            await page.wait(2); // wait for XHRs to settle
          } catch (e) {
-           // fuzzing is best-effort, don't fail the whole explore
+           log.debug(`Interactive fuzzing skipped: ${e instanceof Error ? e.message : String(e)}`);
          }
       }
 

package/src/external.test.ts

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockExecFileSync, mockPlatform } = vi.hoisted(() => ({
+  mockExecFileSync: vi.fn(),
+  mockPlatform: vi.fn(() => 'darwin'),
+}));
+
+vi.mock('node:child_process', () => ({
+  spawnSync: vi.fn(),
+  execFileSync: mockExecFileSync,
+}));
+
+vi.mock('node:os', async () => {
+  const actual = await vi.importActual<typeof import('node:os')>('node:os');
+  return {
+    ...actual,
+    platform: mockPlatform,
+  };
+});
+
+import { installExternalCli, parseCommand, type ExternalCliConfig } from './external.js';
+
+describe('parseCommand', () => {
+  it('splits binaries and quoted arguments without invoking a shell', () => {
+    expect(parseCommand('npm install -g "@scope/tool name"')).toEqual({
+      binary: 'npm',
+      args: ['install', '-g', '@scope/tool name'],
+    });
+  });
+
+  it('rejects shell operators', () => {
+    expect(() => parseCommand('brew install gh && rm -rf /')).toThrow(
+      'Install command contains unsafe shell operators',
+    );
+  });
+});
+
+describe('installExternalCli', () => {
+  const cli: ExternalCliConfig = {
+    name: 'readwise',
+    binary: 'readwise',
+    install: {
+      default: 'npm install -g @readwiseio/readwise-cli',
+    },
+  };
+
+  beforeEach(() => {
+    mockExecFileSync.mockReset();
+    mockPlatform.mockReturnValue('darwin');
+  });
+
+  it('retries with .cmd on Windows when the bare binary is unavailable', () => {
+    mockPlatform.mockReturnValue('win32');
+    mockExecFileSync
+      .mockImplementationOnce(() => {
+        const err = new Error('not found') as NodeJS.ErrnoException;
+        err.code = 'ENOENT';
+        throw err;
+      })
+      .mockReturnValueOnce(Buffer.from(''));
+
+    expect(installExternalCli(cli)).toBe(true);
+    expect(mockExecFileSync).toHaveBeenNthCalledWith(
+      1,
+      'npm',
+      ['install', '-g', '@readwiseio/readwise-cli'],
+      { stdio: 'inherit' },
+    );
+    expect(mockExecFileSync).toHaveBeenNthCalledWith(
+      2,
+      'npm.cmd',
+      ['install', '-g', '@readwiseio/readwise-cli'],
+      { stdio: 'inherit' },
+    );
+  });
+
+  it('does not mask non-ENOENT failures', () => {
+    mockPlatform.mockReturnValue('win32');
+    mockExecFileSync.mockImplementationOnce(() => {
+      const err = new Error('permission denied') as NodeJS.ErrnoException;
+      err.code = 'EACCES';
+      throw err;
+    });
+
+    expect(installExternalCli(cli)).toBe(false);
+    expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+  });
+});

package/src/external.ts

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { spawnSync, execSync, execFileSync } from 'node:child_process';
+import { spawnSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
@@ -82,6 +82,60 @@ export function getInstallCmd(installConfig?: ExternalCliInstall): string | null
   return null;
 }
 
+/**
+ * Safely parses a command string into a binary and argument list.
+ * Rejects commands containing shell operators (&&, ||, |, ;, >, <, `) that
+ * cannot be safely expressed as execFileSync arguments.
+ *
+ * Args:
+ *   cmd: Raw command string from YAML config (e.g. "brew install gh")
+ *
+ * Returns:
+ *   Object with `binary` and `args` fields, or throws on unsafe input.
+ */
+export function parseCommand(cmd: string): { binary: string; args: string[] } {
+  const shellOperators = /&&|\|\|?|;|[><`]/;
+  if (shellOperators.test(cmd)) {
+    throw new Error(
+      `Install command contains unsafe shell operators and cannot be executed securely: "${cmd}". ` +
+        `Please install the tool manually.`
+    );
+  }
+
+  // Tokenise respecting single- and double-quoted segments (no variable expansion).
+  const tokens: string[] = [];
+  const re = /(?:"([^"]*)")|(?:'([^']*)')|(\S+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(cmd)) !== null) {
+    tokens.push(match[1] ?? match[2] ?? match[3]);
+  }
+
+  if (tokens.length === 0) {
+    throw new Error(`Install command is empty.`);
+  }
+
+  const [binary, ...args] = tokens;
+  return { binary, args };
+}
+
+function shouldRetryWithCmdShim(binary: string, err: NodeJS.ErrnoException): boolean {
+  return os.platform() === 'win32' && !path.extname(binary) && err.code === 'ENOENT';
+}
+
+function runInstallCommand(cmd: string): void {
+  const { binary, args } = parseCommand(cmd);
+
+  try {
+    execFileSync(binary, args, { stdio: 'inherit' });
+  } catch (err: any) {
+    if (shouldRetryWithCmdShim(binary, err)) {
+      execFileSync(`${binary}.cmd`, args, { stdio: 'inherit' });
+      return;
+    }
+    throw err;
+  }
+}
+
 export function installExternalCli(cli: ExternalCliConfig): boolean {
   if (!cli.install) {
     console.error(chalk.red(`No auto-install command configured for '${cli.name}'.`));
@@ -99,7 +153,7 @@ export function installExternalCli(cli: ExternalCliConfig): boolean {
   console.log(chalk.cyan(`🔹 '${cli.name}' is not installed. Auto-installing...`));
   console.log(chalk.dim(`$ ${cmd}`));
   try {
-    execSync(cmd, { stdio: 'inherit' });
+    runInstallCommand(cmd);
     console.log(chalk.green(`✅ Installed '${cli.name}' successfully.\n`));
     return true;
   } catch (err: any) {

package/src/generate.ts

@@ -12,7 +12,8 @@ import { exploreUrl } from './explore.js';
 import type { IBrowserFactory } from './runtime.js';
 import { synthesizeFromExplore, type SynthesizeCandidateSummary, type SynthesizeResult } from './synthesize.js';
 
-// TODO: implement real CLI registration (copy candidate YAML to user clis dir)
+// Registration is a no-op stub — candidates are written to disk by synthesize,
+// but not yet auto-copied into the user clis dir.
 interface RegisterCandidatesOptions {
   target: string;
   builtinClis?: string;

package/src/main.ts

@@ -3,6 +3,16 @@
  * opencli — Make any website your CLI. AI-powered.
  */
 
+// Ensure standard system paths are available for child processes.
+// Some environments (GUI apps, cron, IDE terminals) launch with a minimal PATH
+// that excludes /usr/local/bin, /usr/sbin, etc., causing external CLIs to fail.
+if (process.platform !== 'win32') {
+  const std = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  const cur = new Set((process.env.PATH ?? '').split(':').filter(Boolean));
+  for (const p of std) cur.add(p);
+  process.env.PATH = [...cur].join(':');
+}
+
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';

package/src/plugin.test.ts

@@ -6,7 +6,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { PLUGINS_DIR } from './discovery.js';
-import { listPlugins, uninstallPlugin, _parseSource } from './plugin.js';
+import { listPlugins, uninstallPlugin, updatePlugin, _parseSource } from './plugin.js';
 
 describe('parseSource', () => {
   it('parses github:user/repo format', () => {
@@ -84,3 +84,9 @@ describe('uninstallPlugin', () => {
     expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
   });
 });
+
+describe('updatePlugin', () => {
+  it('throws for non-existent plugin', () => {
+    expect(() => updatePlugin('__nonexistent__')).toThrow('not installed');
+  });
+});

package/src/plugin.ts

@@ -18,6 +18,32 @@ export interface PluginInfo {
   source?: string;
 }
 
+/**
+ * Shared post-install lifecycle: npm install → host symlink → TS transpile.
+ * Called by both installPlugin() and updatePlugin().
+ */
+function postInstallLifecycle(pluginDir: string): void {
+  const pkgJsonPath = path.join(pluginDir, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) return;
+
+  try {
+    execFileSync('npm', ['install', '--omit=dev'], {
+      cwd: pluginDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    // Non-fatal: npm install may fail if no real deps
+  }
+
+  // Symlink host opencli so TS plugins resolve '@jackwener/opencli/registry'
+  // against the running host, not a stale npm-published version.
+  linkHostOpencli(pluginDir);
+
+  // Transpile .ts → .js via esbuild (production node can't load .ts directly).
+  transpilePluginTs(pluginDir);
+}
+
 /**
  * Install a plugin from a source.
  * Currently supports "github:user/repo" format (git clone wrapper).
@@ -52,31 +78,7 @@ export function installPlugin(source: string): string {
     throw new Error(`Failed to clone plugin: ${err.message}`);
   }
 
-  // If the plugin has a package.json, run npm install for regular deps,
-  // then symlink the host opencli into node_modules for peerDep resolution.
-  const pkgJsonPath = path.join(targetDir, 'package.json');
-  if (fs.existsSync(pkgJsonPath)) {
-    try {
-      execFileSync('npm', ['install', '--omit=dev'], {
-        cwd: targetDir,
-        encoding: 'utf-8',
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-    } catch {
-      // Non-fatal: npm install may fail if no real deps
-    }
-
-    // Symlink host opencli into plugin's node_modules so TS plugins
-    // can resolve '@jackwener/opencli/registry' against the running host.
-    // This is more reliable than depending on the npm-published version
-    // which may lag behind the local installation.
-    linkHostOpencli(targetDir);
-
-    // Transpile TS plugin files to JS so they work in production mode
-    // (node cannot load .ts files directly without tsx).
-    transpilePluginTs(targetDir);
-  }
-
+  postInstallLifecycle(targetDir);
   return name;
 }
 
@@ -91,6 +93,28 @@ export function uninstallPlugin(name: string): void {
   fs.rmSync(targetDir, { recursive: true, force: true });
 }
 
+/**
+ * Update a plugin by name (git pull + re-install lifecycle).
+ */
+export function updatePlugin(name: string): void {
+  const targetDir = path.join(PLUGINS_DIR, name);
+  if (!fs.existsSync(targetDir)) {
+    throw new Error(`Plugin "${name}" is not installed.`);
+  }
+
+  try {
+    execFileSync('git', ['pull', '--ff-only'], {
+      cwd: targetDir,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err: any) {
+    throw new Error(`Failed to update plugin: ${err.message}`);
+  }
+
+  postInstallLifecycle(targetDir);
+}
+
 /**
  * List all installed plugins.
  */