@jackwener/opencli 1.4.0 → 1.5.0

package/dist/errors.d.ts

@@ -12,8 +12,10 @@ export declare class CliError extends Error {
     readonly hint?: string;
     constructor(code: string, message: string, hint?: string);
 }
+export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
 export declare class BrowserConnectError extends CliError {
-    constructor(message: string, hint?: string);
+    readonly kind: BrowserConnectKind;
+    constructor(message: string, hint?: string, kind?: BrowserConnectKind);
 }
 export declare class AdapterLoadError extends CliError {
     constructor(message: string, hint?: string);

package/dist/errors.js

@@ -12,74 +12,50 @@ export class CliError extends Error {
     hint;
     constructor(code, message, hint) {
         super(message);
-        this.name = 'CliError';
+        this.name = new.target.name;
         this.code = code;
         this.hint = hint;
     }
 }
-// ── Browser / Connection ────────────────────────────────────────────────────
 export class BrowserConnectError extends CliError {
-    constructor(message, hint) {
+    kind;
+    constructor(message, hint, kind = 'unknown') {
         super('BROWSER_CONNECT', message, hint);
-        this.name = 'BrowserConnectError';
+        this.kind = kind;
     }
 }
-// ── Adapter loading ─────────────────────────────────────────────────────────
 export class AdapterLoadError extends CliError {
-    constructor(message, hint) {
-        super('ADAPTER_LOAD', message, hint);
-        this.name = 'AdapterLoadError';
-    }
+    constructor(message, hint) { super('ADAPTER_LOAD', message, hint); }
 }
-// ── Command execution ───────────────────────────────────────────────────────
 export class CommandExecutionError extends CliError {
-    constructor(message, hint) {
-        super('COMMAND_EXEC', message, hint);
-        this.name = 'CommandExecutionError';
-    }
+    constructor(message, hint) { super('COMMAND_EXEC', message, hint); }
 }
-// ── Configuration ───────────────────────────────────────────────────────────
 export class ConfigError extends CliError {
-    constructor(message, hint) {
-        super('CONFIG', message, hint);
-        this.name = 'ConfigError';
-    }
+    constructor(message, hint) { super('CONFIG', message, hint); }
 }
-// ── Authentication / Login ──────────────────────────────────────────────────
 export class AuthRequiredError extends CliError {
     domain;
     constructor(domain, message) {
         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, seconds) {
         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, hint) {
-        super('ARGUMENT', message, hint);
-        this.name = 'ArgumentError';
-    }
+    constructor(message, hint) { super('ARGUMENT', message, hint); }
 }
-// ── Empty result ────────────────────────────────────────────────────────────
 export class EmptyResultError extends CliError {
     constructor(command, hint) {
         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, hint) {
         super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.');
-        this.name = 'SelectorError';
     }
 }
 // ── Utilities ───────────────────────────────────────────────────────────
@@ -95,4 +71,11 @@ export const ERROR_ICONS = {
     ARGUMENT: '❌',
     EMPTY_RESULT: '📭',
     SELECTOR: '🔍',
+    COMMAND_EXEC: '💥',
+    ADAPTER_LOAD: '📦',
+    NETWORK: '🌐',
+    API_ERROR: '🚫',
+    RATE_LIMITED: '⏳',
+    PAGE_CHANGED: '🔄',
+    CONFIG: '⚙️ ',
 };

package/dist/execution.d.ts

@@ -9,8 +9,6 @@
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
-import { type CliCommand, type Arg } from './registry.js';
-type CommandArgs = Record<string, unknown>;
+import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
 export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
 export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean): Promise<unknown>;
-export {};

package/dist/execution.js

@@ -12,10 +12,13 @@
 import { Strategy, getRegistry, fullName } from './registry.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 } from './hooks.js';
+import { checkDaemonStatus } from './browser/discover.js';
+import { PKG_VERSION } from './version.js';
+import chalk from 'chalk';
 const _loadedModules = new Set();
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
@@ -126,6 +129,23 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
     let result;
     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/dist/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/dist/hooks.js

@@ -15,6 +15,8 @@ const _hooks = globalThis.__opencli_hooks__ ??= new Map();
 // ── Registration API (used by plugins) ─────────────────────────────────────
 function addHook(name, fn) {
     const list = _hooks.get(name) ?? [];
+    if (list.includes(fn))
+        return;
     list.push(fn);
     _hooks.set(name, list);
 }

package/dist/main.js

@@ -19,12 +19,17 @@ 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);
 const BUILTIN_CLIS = path.resolve(__dirname, 'clis');
 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/dist/output.js

@@ -5,7 +5,11 @@ import chalk from 'chalk';
 import Table from 'cli-table3';
 import yaml from 'js-yaml';
 function normalizeRows(data) {
-    return Array.isArray(data) ? data : [data];
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === 'object')
+        return [data];
+    return [{ value: data }];
 }
 function resolveColumns(rows, opts) {
     return opts.columns ?? Object.keys(rows[0] ?? {});

package/dist/pipeline/executor.js

@@ -4,8 +4,7 @@
 import { getStep } from './registry.js';
 import { log } from '../logger.js';
 import { ConfigError } from '../errors.js';
-/** Steps that interact with the browser and may fail transiently */
-const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot']);
+import { BROWSER_ONLY_STEPS } from '../capabilityRouting.js';
 export async function executePipeline(page, pipeline, ctx = {}) {
     const args = ctx.args ?? {};
     const debug = ctx.debug ?? false;
@@ -33,7 +32,7 @@ export async function executePipeline(page, pipeline, ctx = {}) {
     }
     catch (err) {
         // Attempt cleanup: close automation window on pipeline failure
-        if (page && typeof page.closeWindow === 'function') {
+        if (page?.closeWindow) {
             try {
                 await page.closeWindow();
             }
@@ -44,7 +43,7 @@ export async function executePipeline(page, pipeline, ctx = {}) {
     return data;
 }
 async function executeStepWithRetry(handler, page, params, data, args, op, configRetries) {
-    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 {
             return await handler(page, params, data, args);

package/dist/plugin-manifest.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Plugin manifest: reads and validates opencli-plugin.json files.
+ *
+ * Supports two modes:
+ * 1. Single plugin: repo root IS the plugin directory.
+ * 2. Monorepo: repo contains multiple plugins declared in `plugins` field.
+ */
+export interface SubPluginEntry {
+    /** Relative path from repo root to the sub-plugin directory. */
+    path: string;
+    version?: string;
+    description?: string;
+    /** Semver range for opencli compatibility (overrides top-level). */
+    opencli?: string;
+    /** When true, this sub-plugin is skipped during install. */
+    disabled?: boolean;
+}
+export interface PluginManifest {
+    /** Plugin name (single-plugin mode). */
+    name?: string;
+    /** Semantic version of the plugin (single-plugin mode). */
+    version?: string;
+    /** Semver range for opencli compatibility, e.g. ">=1.0.0". */
+    opencli?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Monorepo sub-plugins. Key = logical plugin name. */
+    plugins?: Record<string, SubPluginEntry>;
+}
+export declare const MANIFEST_FILENAME = "opencli-plugin.json";
+/**
+ * Read and parse opencli-plugin.json from a directory.
+ * Returns null if the file does not exist or is unparseable.
+ */
+export declare function readPluginManifest(dir: string): PluginManifest | null;
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export declare function isMonorepo(manifest: PluginManifest): boolean;
+/**
+ * Get the list of enabled sub-plugins from a monorepo manifest.
+ * Returns entries sorted by key name.
+ */
+export declare function getEnabledPlugins(manifest: PluginManifest): Array<{
+    name: string;
+    entry: SubPluginEntry;
+}>;
+/**
+ * Check if the current opencli version satisfies a semver range string.
+ *
+ * Supports a simplified subset of semver ranges:
+ *   ">=1.0.0"   – greater than or equal
+ *   "<=1.5.0"   – less than or equal
+ *   ">1.0.0"    – strictly greater
+ *   "<2.0.0"    – strictly less
+ *   "^1.2.0"    – compatible (>=1.2.0 and <2.0.0)
+ *   "~1.2.0"    – patch-level (>=1.2.0 and <1.3.0)
+ *   "1.2.0"     – exact match
+ *   ">=1.0.0 <2.0.0" – multiple constraints (space-separated, all must match)
+ *
+ * Returns true if compatible, false if not, and true for empty/undefined
+ * ranges (no constraint = always compatible).
+ */
+export declare function checkCompatibility(range: string | undefined): boolean;
+/** Parse a version string ("1.2.3") into [major, minor, patch]. */
+export declare function parseVersion(version: string): [number, number, number] | null;
+/**
+ * Check if a version string satisfies a range expression.
+ * Space-separated constraints are ANDed together.
+ */
+export declare function satisfiesRange(versionStr: string, range: string): boolean;
+export { readPluginManifest as _readPluginManifest, isMonorepo as _isMonorepo, getEnabledPlugins as _getEnabledPlugins, checkCompatibility as _checkCompatibility, parseVersion as _parseVersion, satisfiesRange as _satisfiesRange, };

package/dist/plugin-manifest.js

@@ -0,0 +1,160 @@
+/**
+ * Plugin manifest: reads and validates opencli-plugin.json files.
+ *
+ * Supports two modes:
+ * 1. Single plugin: repo root IS the plugin directory.
+ * 2. Monorepo: repo contains multiple plugins declared in `plugins` field.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PKG_VERSION } from './version.js';
+export const MANIFEST_FILENAME = 'opencli-plugin.json';
+// ── Read / Validate ─────────────────────────────────────────────────────────
+/**
+ * Read and parse opencli-plugin.json from a directory.
+ * Returns null if the file does not exist or is unparseable.
+ */
+export function readPluginManifest(dir) {
+    const manifestPath = path.join(dir, MANIFEST_FILENAME);
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true when the manifest declares a monorepo (has `plugins` field). */
+export function isMonorepo(manifest) {
+    return (manifest.plugins !== undefined &&
+        manifest.plugins !== null &&
+        typeof manifest.plugins === 'object' &&
+        Object.keys(manifest.plugins).length > 0);
+}
+/**
+ * Get the list of enabled sub-plugins from a monorepo manifest.
+ * Returns entries sorted by key name.
+ */
+export function getEnabledPlugins(manifest) {
+    if (!manifest.plugins)
+        return [];
+    return Object.entries(manifest.plugins)
+        .filter(([, entry]) => !entry.disabled)
+        .map(([name, entry]) => ({ name, entry }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+// ── Version compatibility ───────────────────────────────────────────────────
+/**
+ * Check if the current opencli version satisfies a semver range string.
+ *
+ * Supports a simplified subset of semver ranges:
+ *   ">=1.0.0"   – greater than or equal
+ *   "<=1.5.0"   – less than or equal
+ *   ">1.0.0"    – strictly greater
+ *   "<2.0.0"    – strictly less
+ *   "^1.2.0"    – compatible (>=1.2.0 and <2.0.0)
+ *   "~1.2.0"    – patch-level (>=1.2.0 and <1.3.0)
+ *   "1.2.0"     – exact match
+ *   ">=1.0.0 <2.0.0" – multiple constraints (space-separated, all must match)
+ *
+ * Returns true if compatible, false if not, and true for empty/undefined
+ * ranges (no constraint = always compatible).
+ */
+export function checkCompatibility(range) {
+    if (!range || range.trim() === '')
+        return true;
+    return satisfiesRange(PKG_VERSION, range);
+}
+/** Parse a version string ("1.2.3") into [major, minor, patch]. */
+export function parseVersion(version) {
+    const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+}
+/** Compare two version tuples: -1 if a<b, 0 if equal, 1 if a>b. */
+function compareVersions(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] < b[i])
+            return -1;
+        if (a[i] > b[i])
+            return 1;
+    }
+    return 0;
+}
+/** Check if a version satisfies a single constraint like ">=1.2.0". */
+function satisfiesSingleConstraint(version, constraint) {
+    const trimmed = constraint.trim();
+    if (!trimmed)
+        return true;
+    // ^1.2.0 → >=1.2.0 <2.0.0
+    if (trimmed.startsWith('^')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        const upper = [target[0] + 1, 0, 0];
+        return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+    }
+    // ~1.2.0 → >=1.2.0 <1.3.0
+    if (trimmed.startsWith('~')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        const upper = [target[0], target[1] + 1, 0];
+        return compareVersions(version, target) >= 0 && compareVersions(version, upper) < 0;
+    }
+    // >=, <=, >, <, =
+    if (trimmed.startsWith('>=')) {
+        const target = parseVersion(trimmed.slice(2));
+        if (!target)
+            return true;
+        return compareVersions(version, target) >= 0;
+    }
+    if (trimmed.startsWith('<=')) {
+        const target = parseVersion(trimmed.slice(2));
+        if (!target)
+            return true;
+        return compareVersions(version, target) <= 0;
+    }
+    if (trimmed.startsWith('>')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) > 0;
+    }
+    if (trimmed.startsWith('<')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) < 0;
+    }
+    if (trimmed.startsWith('=')) {
+        const target = parseVersion(trimmed.slice(1));
+        if (!target)
+            return true;
+        return compareVersions(version, target) === 0;
+    }
+    // Exact match
+    const target = parseVersion(trimmed);
+    if (!target)
+        return true;
+    return compareVersions(version, target) === 0;
+}
+/**
+ * Check if a version string satisfies a range expression.
+ * Space-separated constraints are ANDed together.
+ */
+export function satisfiesRange(versionStr, range) {
+    const version = parseVersion(versionStr);
+    if (!version)
+        return true; // Can't parse our own version → assume ok
+    // Split on whitespace for multi-constraint ranges (e.g. ">=1.0.0 <2.0.0")
+    const constraints = range.trim().split(/\s+/);
+    return constraints.every((c) => satisfiesSingleConstraint(version, c));
+}
+// ── Exports for testing ─────────────────────────────────────────────────────
+export { readPluginManifest as _readPluginManifest, isMonorepo as _isMonorepo, getEnabledPlugins as _getEnabledPlugins, checkCompatibility as _checkCompatibility, parseVersion as _parseVersion, satisfiesRange as _satisfiesRange, };

package/dist/plugin-manifest.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin manifest: reading, validating, and compatibility checks.
+ */
+export {};