@jackwener/opencli 1.4.1 → 1.5.0

package/dist/discovery.js

@@ -19,6 +19,7 @@ import { log } from './logger.js';
 export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', 'plugins');
 /** Matches files that register commands via cli() or lifecycle hooks */
 const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
+import { parseYamlArgs } from './yaml-schema.js';
 function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
     if (!rawStrategy)
         return fallback;
@@ -71,6 +72,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                     pipeline: entry.pipeline,
                     timeoutSeconds: entry.timeout,
                     source: `manifest:${entry.site}/${entry.name}`,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
                     navigateBefore: entry.navigateBefore,
                 };
                 registerCommand(cmd);
@@ -91,6 +94,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                     columns: entry.columns,
                     timeoutSeconds: entry.timeout,
                     source: modulePath,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
                     navigateBefore: entry.navigateBefore,
                     _lazy: true,
                     _modulePath: modulePath,
@@ -153,20 +158,7 @@ async function registerYamlCli(filePath, defaultSite) {
         const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
         const strategy = parseStrategy(strategyStr);
         const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
-        const args = [];
-        if (cliDef.args && typeof cliDef.args === 'object') {
-            for (const [argName, argDef] of Object.entries(cliDef.args)) {
-                args.push({
-                    name: argName,
-                    type: argDef?.type ?? 'str',
-                    default: argDef?.default,
-                    required: argDef?.required ?? false,
-                    positional: argDef?.positional ?? false,
-                    help: argDef?.description ?? argDef?.help ?? '',
-                    choices: argDef?.choices,
-                });
-            }
-        }
+        const args = parseYamlArgs(cliDef.args);
         const cmd = {
             site,
             name,
@@ -179,6 +171,8 @@ async function registerYamlCli(filePath, defaultSite) {
             pipeline: cliDef.pipeline,
             timeoutSeconds: cliDef.timeout,
             source: filePath,
+            deprecated: cliDef.deprecated,
+            replacedBy: cliDef.replacedBy,
             navigateBefore: cliDef.navigateBefore,
         };
         registerCommand(cmd);

package/dist/doctor.d.ts

@@ -20,6 +20,7 @@ export type DoctorReport = {
     cliVersion?: string;
     daemonRunning: boolean;
     extensionConnected: boolean;
+    extensionVersion?: string;
     connectivity?: ConnectivityResult;
     sessions?: Array<{
         workspace: string;

package/dist/doctor.js

@@ -10,6 +10,7 @@ import { checkDaemonStatus } from './browser/discover.js';
 import { BrowserBridge } from './browser/index.js';
 import { listSessions } from './browser/daemon-client.js';
 import { getErrorMessage } from './errors.js';
+import { getRuntimeLabel } from './runtime-detect.js';
 /**
  * Test connectivity by attempting a real browser command.
  */
@@ -64,23 +65,29 @@ export async function runBrowserDoctor(opts = {}) {
     if (connectivity && !connectivity.ok) {
         issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
     }
+    if (status.extensionVersion && opts.cliVersion && status.extensionVersion !== opts.cliVersion) {
+        issues.push(`Extension version mismatch: extension v${status.extensionVersion} ≠ CLI v${opts.cliVersion}\n` +
+            '  Download the latest extension from: https://github.com/jackwener/opencli/releases');
+    }
     return {
         cliVersion: opts.cliVersion,
         daemonRunning: status.running,
         extensionConnected: status.extensionConnected,
+        extensionVersion: status.extensionVersion,
         connectivity,
         sessions,
         issues,
     };
 }
 export function renderBrowserDoctorReport(report) {
-    const lines = [chalk.bold(`opencli v${report.cliVersion ?? 'unknown'} doctor`), ''];
+    const lines = [chalk.bold(`opencli v${report.cliVersion ?? 'unknown'} doctor`) + chalk.dim(` (${getRuntimeLabel()})`), ''];
     // Daemon status
     const daemonIcon = report.daemonRunning ? chalk.green('[OK]') : chalk.red('[MISSING]');
     lines.push(`${daemonIcon} Daemon: ${report.daemonRunning ? `running on port ${DEFAULT_DAEMON_PORT}` : 'not running'}`);
     // Extension status
     const extIcon = report.extensionConnected ? chalk.green('[OK]') : chalk.yellow('[MISSING]');
-    lines.push(`${extIcon} Extension: ${report.extensionConnected ? 'connected' : 'not connected'}`);
+    const extVersion = report.extensionVersion ? chalk.dim(` (v${report.extensionVersion})`) : '';
+    lines.push(`${extIcon} Extension: ${report.extensionConnected ? 'connected' : 'not connected'}${extVersion}`);
     // Connectivity
     if (report.connectivity) {
         const connIcon = report.connectivity.ok ? chalk.green('[OK]') : chalk.red('[FAIL]');

package/dist/download/index.js

@@ -7,6 +7,8 @@ import * as path from 'node:path';
 import * as https from 'node:https';
 import * as http from 'node:http';
 import * as os from 'node:os';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { URL } from 'node:url';
 import { isBinaryInstalled } from '../external.js';
 import { getErrorMessage } from '../errors.js';
@@ -68,65 +70,75 @@ export async function httpDownload(url, destPath, options = {}, redirectCount =
         if (cookies) {
             requestHeaders['Cookie'] = cookies;
         }
-        // Ensure directory exists
-        const dir = path.dirname(destPath);
-        fs.mkdirSync(dir, { recursive: true });
         const tempPath = `${destPath}.tmp`;
-        const file = fs.createWriteStream(tempPath);
-        const request = protocol.get(url, { headers: requestHeaders, timeout }, (response) => {
-            // Handle redirects
-            if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-                file.close();
-                if (fs.existsSync(tempPath))
-                    fs.unlinkSync(tempPath);
-                if (redirectCount >= maxRedirects) {
-                    resolve({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
-                    return;
-                }
-                const redirectUrl = resolveRedirectUrl(url, response.headers.location);
-                const originalHost = new URL(url).hostname;
-                const redirectHost = new URL(redirectUrl).hostname;
-                // Do not forward cookies when a redirect crosses host boundaries.
-                const redirectOptions = originalHost === redirectHost
-                    ? options
-                    : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
-                httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1).then(resolve);
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
                 return;
+            settled = true;
+            resolve(result);
+        };
+        const cleanupTempFile = async () => {
+            try {
+                await fs.promises.rm(tempPath, { force: true });
             }
-            if (response.statusCode !== 200) {
-                file.close();
-                if (fs.existsSync(tempPath))
-                    fs.unlinkSync(tempPath);
-                resolve({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
-                return;
+            catch {
+                // Ignore cleanup errors so the original failure is preserved.
             }
-            const totalSize = parseInt(response.headers['content-length'] || '0', 10);
-            let received = 0;
-            response.on('data', (chunk) => {
-                received += chunk.length;
-                if (onProgress)
-                    onProgress(received, totalSize);
-            });
-            response.pipe(file);
-            file.on('finish', () => {
-                file.close();
-                // Rename temp file to final destination
-                fs.renameSync(tempPath, destPath);
-                resolve({ success: true, size: received });
-            });
+        };
+        const request = protocol.get(url, { headers: requestHeaders, timeout }, (response) => {
+            void (async () => {
+                // Handle redirects before creating any file handles.
+                if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+                    response.resume();
+                    if (redirectCount >= maxRedirects) {
+                        finish({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
+                        return;
+                    }
+                    const redirectUrl = resolveRedirectUrl(url, response.headers.location);
+                    const originalHost = new URL(url).hostname;
+                    const redirectHost = new URL(redirectUrl).hostname;
+                    const redirectOptions = originalHost === redirectHost
+                        ? options
+                        : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
+                    finish(await httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1));
+                    return;
+                }
+                if (response.statusCode !== 200) {
+                    response.resume();
+                    finish({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
+                    return;
+                }
+                const totalSize = parseInt(response.headers['content-length'] || '0', 10);
+                let received = 0;
+                const progressStream = new Transform({
+                    transform(chunk, _encoding, callback) {
+                        received += chunk.length;
+                        if (onProgress)
+                            onProgress(received, totalSize);
+                        callback(null, chunk);
+                    },
+                });
+                try {
+                    await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+                    await pipeline(response, progressStream, fs.createWriteStream(tempPath));
+                    await fs.promises.rename(tempPath, destPath);
+                    finish({ success: true, size: received });
+                }
+                catch (err) {
+                    await cleanupTempFile();
+                    finish({ success: false, size: 0, error: getErrorMessage(err) });
+                }
+            })();
         });
         request.on('error', (err) => {
-            file.close();
-            if (fs.existsSync(tempPath))
-                fs.unlinkSync(tempPath);
-            resolve({ success: false, size: 0, error: err.message });
+            void (async () => {
+                await cleanupTempFile();
+                finish({ success: false, size: 0, error: err.message });
+            })();
         });
         request.on('timeout', () => {
-            request.destroy();
-            file.close();
-            if (fs.existsSync(tempPath))
-                fs.unlinkSync(tempPath);
-            resolve({ success: false, size: 0, error: 'Timeout' });
+            request.destroy(new Error('Timeout'));
         });
     });
 }

package/dist/download/index.test.js

@@ -5,11 +5,19 @@ import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { formatCookieHeader, httpDownload, resolveRedirectUrl } from './index.js';
 const servers = [];
+const tempDirs = [];
 afterEach(async () => {
     await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
         server.close((err) => (err ? reject(err) : resolve()));
     })));
     servers.length = 0;
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tempDirs.length = 0;
 });
 async function startServer(handler, hostname = '127.0.0.1') {
     const server = http.createServer(handler);
@@ -21,7 +29,9 @@ async function startServer(handler, hostname = '127.0.0.1') {
     }
     return `http://${hostname}:${address.port}`;
 }
-describe('download helpers', () => {
+// Windows Defender can briefly lock newly-written .tmp files, causing EPERM.
+// Retry once to handle this flakiness.
+describe('download helpers', { retry: process.platform === 'win32' ? 2 : 0 }, () => {
     it('resolves relative redirects against the original URL', () => {
         expect(resolveRedirectUrl('https://example.com/a/file', '/cdn/file.bin')).toBe('https://example.com/cdn/file.bin');
         expect(resolveRedirectUrl('https://example.com/a/file', '../next')).toBe('https://example.com/next');
@@ -38,7 +48,8 @@ describe('download helpers', () => {
             res.setHeader('Location', '/loop');
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'file.txt');
         const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
         expect(result).toEqual({
@@ -60,7 +71,8 @@ describe('download helpers', () => {
             res.setHeader('Location', targetUrl);
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'redirect.txt');
         const result = await httpDownload(`${redirectUrl}/start`, destPath, { cookies: 'sid=abc' });
         expect(result).toEqual({ success: true, size: 2 });
@@ -79,7 +91,8 @@ describe('download helpers', () => {
             res.setHeader('Location', targetUrl);
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'redirect-header.txt');
         const result = await httpDownload(`${redirectUrl}/start`, destPath, {
             headers: { Cookie: 'sid=header-cookie' },

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/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, };