@jackwener/opencli 1.4.0 → 1.5.0

package/src/errors.ts

@@ -14,109 +14,61 @@ export class CliError extends Error {
 
   constructor(code: string, message: string, hint?: string) {
     super(message);
-    this.name = 'CliError';
+    this.name = new.target.name;
     this.code = code;
     this.hint = hint;
   }
 }
 
-// ── Browser / Connection ────────────────────────────────────────────────────
+export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
 
 export class BrowserConnectError extends CliError {
-  constructor(message: string, hint?: string) {
+  readonly kind: BrowserConnectKind;
+  constructor(message: string, hint?: string, kind: BrowserConnectKind = 'unknown') {
     super('BROWSER_CONNECT', message, hint);
-    this.name = 'BrowserConnectError';
+    this.kind = kind;
   }
 }
 
-// ── Adapter loading ─────────────────────────────────────────────────────────
-
 export class AdapterLoadError extends CliError {
-  constructor(message: string, hint?: string) {
-    super('ADAPTER_LOAD', message, hint);
-    this.name = 'AdapterLoadError';
-  }
+  constructor(message: string, hint?: string) { super('ADAPTER_LOAD', message, hint); }
 }
 
-// ── Command execution ───────────────────────────────────────────────────────
-
 export class CommandExecutionError extends CliError {
-  constructor(message: string, hint?: string) {
-    super('COMMAND_EXEC', message, hint);
-    this.name = 'CommandExecutionError';
-  }
+  constructor(message: string, hint?: string) { super('COMMAND_EXEC', message, hint); }
 }
 
-// ── Configuration ───────────────────────────────────────────────────────────
-
 export class ConfigError extends CliError {
-  constructor(message: string, hint?: string) {
-    super('CONFIG', message, hint);
-    this.name = 'ConfigError';
-  }
+  constructor(message: string, hint?: string) { super('CONFIG', message, hint); }
 }
 
-// ── 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';
+    super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome and log in to https://${domain}`);
     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';
+    super('TIMEOUT', `${label} timed out after ${seconds}s`, 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var');
   }
 }
 
-// ── Argument validation ─────────────────────────────────────────────────────
-
 export class ArgumentError extends CliError {
-  constructor(message: string, hint?: string) {
-    super('ARGUMENT', message, hint);
-    this.name = 'ArgumentError';
-  }
+  constructor(message: string, hint?: string) { super('ARGUMENT', message, hint); }
 }
 
-// ── 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';
+    super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in');
   }
 }
 
-// ── 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';
+    super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.');
   }
 }
 
@@ -129,10 +81,17 @@ export function getErrorMessage(error: unknown): string {
 
 /** Error code → emoji mapping for CLI output rendering. */
 export const ERROR_ICONS: Record<string, string> = {
-  AUTH_REQUIRED: '🔒',
+  AUTH_REQUIRED:   '🔒',
   BROWSER_CONNECT: '🔌',
-  TIMEOUT: '⏱ ',
-  ARGUMENT: '❌',
-  EMPTY_RESULT: '📭',
-  SELECTOR: '🔍',
+  TIMEOUT:         '⏱ ',
+  ARGUMENT:        '❌',
+  EMPTY_RESULT:    '📭',
+  SELECTOR:        '🔍',
+  COMMAND_EXEC:    '💥',
+  ADAPTER_LOAD:    '📦',
+  NETWORK:         '🌐',
+  API_ERROR:       '🚫',
+  RATE_LIMITED:    '⏳',
+  PAGE_CHANGED:    '🔄',
+  CONFIG:          '⚙️ ',
 };

package/src/execution.ts

@@ -10,17 +10,19 @@
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 
-import { type CliCommand, type InternalCliCommand, type Arg, Strategy, getRegistry, fullName } from './registry.js';
+import { type CliCommand, type InternalCliCommand, type Arg, type CommandArgs, Strategy, getRegistry, fullName } from './registry.js';
 import type { IPage } from './types.js';
 import { pathToFileURL } from 'node:url';
 import { executePipeline } from './pipeline/index.js';
-import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } from './errors.js';
+import { AdapterLoadError, ArgumentError, BrowserConnectError, CommandExecutionError, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { emitHook, type HookContext } from './hooks.js';
+import { checkDaemonStatus } from './browser/discover.js';
+import { PKG_VERSION } from './version.js';
+import chalk from 'chalk';
 
 const _loadedModules = new Set<string>();
-type CommandArgs = Record<string, unknown>;
 
 export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
   const result: CommandArgs = { ...kwargs };
@@ -151,6 +153,29 @@ export async function executeCommand(
   let result: unknown;
   try {
     if (shouldUseBrowserSession(cmd)) {
+      // ── Fail-fast: only when daemon is UP but extension is not connected ──
+      // If daemon is not running, let browserSession() handle auto-start as usual.
+      // We only short-circuit when the daemon confirms the extension is missing —
+      // that's a clear setup gap, not a transient startup state.
+      // Use a short timeout: localhost responds in <50ms when running.
+      // 300ms avoids a full 2s wait on cold-start (daemon not yet running).
+      const status = await checkDaemonStatus({ timeout: 300 });
+      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' +
+          '  Then run: opencli doctor',
+        );
+      }
+      // ── Version mismatch: warn but don't block ──
+      if (status.extensionVersion && status.extensionVersion !== PKG_VERSION) {
+        process.stderr.write(
+          chalk.yellow(`⚠  Extension v${status.extensionVersion} ≠ CLI v${PKG_VERSION} — consider updating the extension.\n`)
+        );
+      }
+
       ensureRequiredEnv(cmd);
       const BrowserFactory = getBrowserFactory();
       result = await browserSession(BrowserFactory, async (page) => {

package/src/external-clis.yaml

@@ -14,14 +14,6 @@
   install:
     mac: "brew install --cask obsidian"
 
-- name: readwise
-  binary: readwise
-  description: "Readwise & Reader CLI — highlights, annotations, reading list"
-  homepage: "https://github.com/readwiseio/readwise-cli"
-  tags: [reading, highlights]
-  install:
-    default: "npm install -g @readwiseio/readwise-cli"
-
 - name: docker
   binary: docker
   description: "Docker command-line interface"
@@ -29,12 +21,3 @@
   tags: [docker, containers, devops]
   install:
     mac: "brew install --cask docker"
-
-- name: gws
-  binary: gws
-  description: "Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar"
-  homepage: "https://github.com/nicholasgasior/gws"
-  tags: [google, docs, sheets, drive, workspace]
-  install:
-    mac: "brew install gws"
-    default: "npm install -g @nicholasgasior/gws"

package/src/hooks.ts

@@ -44,6 +44,7 @@ const _hooks: Map<HookName, HookFn[]> =
 
 function addHook(name: HookName, fn: HookFn): void {
   const list = _hooks.get(name) ?? [];
+  if (list.includes(fn)) return;
   list.push(fn);
   _hooks.set(name, list);
 }

package/src/main.ts

@@ -20,6 +20,7 @@ import { discoverClis, discoverPlugins } from './discovery.js';
 import { getCompletions } from './completion.js';
 import { runCli } from './cli.js';
 import { emitHook } from './hooks.js';
+import { registerUpdateNoticeOnExit, checkForUpdateBackground } from './update-check.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -29,6 +30,11 @@ const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 await discoverClis(BUILTIN_CLIS, USER_CLIS);
 await discoverPlugins();
 
+// Register exit hook: notice appears after command output (same as npm/gh/yarn)
+registerUpdateNoticeOnExit();
+// Kick off background fetch for next run (non-blocking)
+checkForUpdateBackground();
+
 // ── Fast-path: handle --get-completions before commander parses ─────────
 // Usage: opencli --get-completions --cursor <N> [word1 word2 ...]
 const getCompIdx = process.argv.indexOf('--get-completions');

package/src/output.ts

@@ -16,7 +16,9 @@ export interface RenderOptions {
 }
 
 function normalizeRows(data: unknown): Record<string, unknown>[] {
-  return Array.isArray(data) ? data : [data as Record<string, unknown>];
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === 'object') return [data as Record<string, unknown>];
+  return [{ value: data }];
 }
 
 function resolveColumns(rows: Record<string, unknown>[], opts: RenderOptions): string[] {

package/src/pipeline/executor.ts

@@ -7,6 +7,7 @@ import type { IPage } from '../types.js';
 import { getStep, type StepHandler } from './registry.js';
 import { log } from '../logger.js';
 import { ConfigError } from '../errors.js';
+import { BROWSER_ONLY_STEPS } from '../capabilityRouting.js';
 
 export interface PipelineContext {
   args?: Record<string, unknown>;
@@ -15,9 +16,6 @@ export interface PipelineContext {
   stepRetries?: number;
 }
 
-/** Steps that interact with the browser and may fail transiently */
-const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot']);
-
 export async function executePipeline(
   page: IPage | null,
   pipeline: unknown[],
@@ -50,8 +48,8 @@ export async function executePipeline(
     }
   } catch (err) {
     // Attempt cleanup: close automation window on pipeline failure
-    if (page && typeof (page as unknown as Record<string, unknown>).closeWindow === 'function') {
-      try { await (page as unknown as { closeWindow: () => Promise<void> }).closeWindow(); } catch { /* ignore */ }
+    if (page?.closeWindow) {
+      try { await page.closeWindow(); } catch { /* ignore */ }
     }
     throw err;
   }
@@ -67,7 +65,7 @@ async function executeStepWithRetry(
   op: string,
   configRetries?: number,
 ): Promise<unknown> {
-  const maxRetries = configRetries ?? (BROWSER_STEPS.has(op) ? 2 : 0);
+  const maxRetries = configRetries ?? (BROWSER_ONLY_STEPS.has(op) ? 2 : 0);
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {

package/src/plugin-manifest.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  _readPluginManifest as readPluginManifest,
+  _isMonorepo as isMonorepo,
+  _getEnabledPlugins as getEnabledPlugins,
+  _parseVersion as parseVersion,
+  _satisfiesRange as satisfiesRange,
+  MANIFEST_FILENAME,
+  type PluginManifest,
+} from './plugin-manifest.js';
+
+// ── readPluginManifest ──────────────────────────────────────────────────────
+
+describe('readPluginManifest', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns null when no manifest file exists', () => {
+    expect(readPluginManifest(tmpDir)).toBeNull();
+  });
+
+  it('returns null for malformed JSON', () => {
+    fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), 'not json {{{');
+    expect(readPluginManifest(tmpDir)).toBeNull();
+  });
+
+  it('returns null for non-object JSON (array)', () => {
+    fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '["a","b"]');
+    expect(readPluginManifest(tmpDir)).toBeNull();
+  });
+
+  it('returns null for non-object JSON (string)', () => {
+    fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), '"hello"');
+    expect(readPluginManifest(tmpDir)).toBeNull();
+  });
+
+  it('reads a single-plugin manifest', () => {
+    const manifest: PluginManifest = {
+      name: 'polymarket',
+      version: '1.2.0',
+      opencli: '>=1.0.0',
+      description: 'Prediction market analysis',
+    };
+    fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+    const result = readPluginManifest(tmpDir);
+    expect(result).toEqual(manifest);
+  });
+
+  it('reads a monorepo manifest', () => {
+    const manifest: PluginManifest = {
+      version: '1.0.0',
+      opencli: '>=0.9.0',
+      description: 'My plugin collection',
+      plugins: {
+        polymarket: {
+          path: 'packages/polymarket',
+          description: 'Prediction market',
+          version: '1.2.0',
+        },
+        defi: {
+          path: 'packages/defi',
+          description: 'DeFi data',
+          version: '0.8.0',
+          disabled: true,
+        },
+      },
+    };
+    fs.writeFileSync(path.join(tmpDir, MANIFEST_FILENAME), JSON.stringify(manifest));
+    const result = readPluginManifest(tmpDir);
+    expect(result).toEqual(manifest);
+    expect(result!.plugins!.polymarket.path).toBe('packages/polymarket');
+    expect(result!.plugins!.defi.disabled).toBe(true);
+  });
+});
+
+// ── isMonorepo ──────────────────────────────────────────────────────────────
+
+describe('isMonorepo', () => {
+  it('returns false for single-plugin manifest', () => {
+    expect(isMonorepo({ name: 'test', version: '1.0.0' })).toBe(false);
+  });
+
+  it('returns false for empty plugins object', () => {
+    expect(isMonorepo({ plugins: {} })).toBe(false);
+  });
+
+  it('returns true for manifest with plugins', () => {
+    expect(
+      isMonorepo({
+        plugins: {
+          foo: { path: 'packages/foo' },
+        },
+      }),
+    ).toBe(true);
+  });
+});
+
+// ── getEnabledPlugins ───────────────────────────────────────────────────────
+
+describe('getEnabledPlugins', () => {
+  it('returns empty array for no plugins', () => {
+    expect(getEnabledPlugins({ name: 'test' })).toEqual([]);
+  });
+
+  it('filters out disabled plugins', () => {
+    const manifest: PluginManifest = {
+      plugins: {
+        foo: { path: 'packages/foo' },
+        bar: { path: 'packages/bar', disabled: true },
+        baz: { path: 'packages/baz' },
+      },
+    };
+    const result = getEnabledPlugins(manifest);
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.name)).toEqual(['baz', 'foo']); // sorted
+  });
+
+  it('returns all when none disabled', () => {
+    const manifest: PluginManifest = {
+      plugins: {
+        charlie: { path: 'packages/charlie' },
+        alpha: { path: 'packages/alpha' },
+      },
+    };
+    const result = getEnabledPlugins(manifest);
+    expect(result).toHaveLength(2);
+    expect(result[0].name).toBe('alpha');
+    expect(result[1].name).toBe('charlie');
+  });
+});
+
+// ── parseVersion ────────────────────────────────────────────────────────────
+
+describe('parseVersion', () => {
+  it('parses standard versions', () => {
+    expect(parseVersion('1.2.3')).toEqual([1, 2, 3]);
+    expect(parseVersion('0.0.0')).toEqual([0, 0, 0]);
+    expect(parseVersion('10.20.30')).toEqual([10, 20, 30]);
+  });
+
+  it('parses versions with prerelease suffix', () => {
+    expect(parseVersion('1.2.3-beta.1')).toEqual([1, 2, 3]);
+  });
+
+  it('returns null for invalid versions', () => {
+    expect(parseVersion('abc')).toBeNull();
+    expect(parseVersion('')).toBeNull();
+    expect(parseVersion('1.2')).toBeNull();
+  });
+});
+
+// ── satisfiesRange ──────────────────────────────────────────────────────────
+
+describe('satisfiesRange', () => {
+  it('handles >= constraint', () => {
+    expect(satisfiesRange('1.4.1', '>=1.0.0')).toBe(true);
+    expect(satisfiesRange('1.0.0', '>=1.0.0')).toBe(true);
+    expect(satisfiesRange('0.9.9', '>=1.0.0')).toBe(false);
+  });
+
+  it('handles <= constraint', () => {
+    expect(satisfiesRange('1.0.0', '<=1.0.0')).toBe(true);
+    expect(satisfiesRange('0.9.0', '<=1.0.0')).toBe(true);
+    expect(satisfiesRange('1.0.1', '<=1.0.0')).toBe(false);
+  });
+
+  it('handles > constraint', () => {
+    expect(satisfiesRange('1.0.1', '>1.0.0')).toBe(true);
+    expect(satisfiesRange('1.0.0', '>1.0.0')).toBe(false);
+  });
+
+  it('handles < constraint', () => {
+    expect(satisfiesRange('0.9.9', '<1.0.0')).toBe(true);
+    expect(satisfiesRange('1.0.0', '<1.0.0')).toBe(false);
+  });
+
+  it('handles ^ (caret) constraint', () => {
+    expect(satisfiesRange('1.2.0', '^1.2.0')).toBe(true);
+    expect(satisfiesRange('1.9.9', '^1.2.0')).toBe(true);
+    expect(satisfiesRange('2.0.0', '^1.2.0')).toBe(false);
+    expect(satisfiesRange('1.1.0', '^1.2.0')).toBe(false);
+  });
+
+  it('handles ~ (tilde) constraint', () => {
+    expect(satisfiesRange('1.2.0', '~1.2.0')).toBe(true);
+    expect(satisfiesRange('1.2.9', '~1.2.0')).toBe(true);
+    expect(satisfiesRange('1.3.0', '~1.2.0')).toBe(false);
+  });
+
+  it('handles exact match', () => {
+    expect(satisfiesRange('1.2.3', '1.2.3')).toBe(true);
+    expect(satisfiesRange('1.2.4', '1.2.3')).toBe(false);
+  });
+
+  it('handles compound range (AND)', () => {
+    expect(satisfiesRange('1.5.0', '>=1.0.0 <2.0.0')).toBe(true);
+    expect(satisfiesRange('2.0.0', '>=1.0.0 <2.0.0')).toBe(false);
+    expect(satisfiesRange('0.9.0', '>=1.0.0 <2.0.0')).toBe(false);
+  });
+
+  it('returns true for empty range', () => {
+    expect(satisfiesRange('1.0.0', '')).toBe(true);
+    expect(satisfiesRange('1.0.0', '  ')).toBe(true);
+  });
+
+  it('returns true for unparseable version', () => {
+    expect(satisfiesRange('dev', '>=1.0.0')).toBe(true);
+  });
+});