@jackwener/opencli 1.5.4 → 1.5.5

package/dist/cli-manifest.json

@@ -9282,6 +9282,61 @@
     "type": "ts",
     "modulePath": "sinafinance/news.js"
   },
+  {
+    "site": "sinafinance",
+    "name": "rolling-news",
+    "description": "新浪财经滚动新闻",
+    "domain": "finance.sina.com.cn/roll",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [],
+    "columns": [
+      "column",
+      "title",
+      "date",
+      "url"
+    ],
+    "type": "ts",
+    "modulePath": "sinafinance/rolling-news.js"
+  },
+  {
+    "site": "sinafinance",
+    "name": "stock",
+    "description": "新浪财经行情（A股/港股/美股）",
+    "domain": "suggest3.sinajs.cn,hq.sinajs.cn",
+    "strategy": "public",
+    "browser": false,
+    "args": [
+      {
+        "name": "key",
+        "type": "string",
+        "required": true,
+        "positional": true,
+        "help": "Stock name or code (e.g. 贵州茅台, 腾讯控股, AAPL)"
+      },
+      {
+        "name": "market",
+        "type": "string",
+        "default": "auto",
+        "required": false,
+        "help": "Market: cn, hk, us, auto (default: auto searches cn → hk → us)"
+      }
+    ],
+    "columns": [
+      "Symbol",
+      "Name",
+      "Price",
+      "Change",
+      "ChangePercent",
+      "Open",
+      "High",
+      "Low",
+      "Volume",
+      "MarketCap"
+    ],
+    "type": "ts",
+    "modulePath": "sinafinance/stock.js"
+  },
   {
     "site": "smzdm",
     "name": "search",

package/dist/cli.js

@@ -14,7 +14,7 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { getErrorMessage } from './errors.js';
+import { EXIT_CODES, getErrorMessage } from './errors.js';
 export function runCli(BUILTIN_CLIS, USER_CLIS) {
     const program = new Command();
     // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
@@ -108,7 +108,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         const { verifyClis, renderVerifyReport } = await import('./verify.js');
         const r = await verifyClis({ builtinClis: BUILTIN_CLIS, userClis: USER_CLIS, target, smoke: opts.smoke });
         console.log(renderVerifyReport(r));
-        process.exitCode = r.ok ? 0 : 1;
+        process.exitCode = r.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
     });
     // ── Built-in: explore / synthesize / generate / cascade ───────────────────
     program
@@ -164,7 +164,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
             workspace,
         });
         console.log(renderGenerateSummary(r));
-        process.exitCode = r.ok ? 0 : 1;
+        process.exitCode = r.ok ? EXIT_CODES.SUCCESS : EXIT_CODES.GENERIC_ERROR;
     });
     // ── Built-in: record ─────────────────────────────────────────────────────
     program
@@ -186,7 +186,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
             timeoutMs: parseInt(opts.timeout, 10),
         });
         console.log(renderRecordSummary(result));
-        process.exitCode = result.candidateCount > 0 ? 0 : 1;
+        process.exitCode = result.candidateCount > 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.EMPTY_RESULT;
     });
     program
         .command('cascade')
@@ -251,7 +251,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }
         catch (err) {
             console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
     pluginCmd
@@ -266,7 +266,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }
         catch (err) {
             console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
     pluginCmd
@@ -277,12 +277,12 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         .action(async (name, opts) => {
         if (!name && !opts.all) {
             console.error(chalk.red('Error: Please specify a plugin name or use the --all flag.'));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         if (name && opts.all) {
             console.error(chalk.red('Error: Cannot specify both a plugin name and --all.'));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         const { updatePlugin, updateAllPlugins } = await import('./plugin.js');
@@ -309,7 +309,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
             console.log();
             if (hasErrors) {
                 console.error(chalk.red('Completed with some errors.'));
-                process.exitCode = 1;
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
             }
             else {
                 console.log(chalk.green('✅ All plugins updated successfully.'));
@@ -323,7 +323,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }
         catch (err) {
             console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
     pluginCmd
@@ -408,7 +408,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }
         catch (err) {
             console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
     // ── External CLIs ─────────────────────────────────────────────────────────
@@ -421,7 +421,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         const ext = externalClis.find(e => e.name === name);
         if (!ext) {
             console.error(chalk.red(`External CLI '${name}' not found in registry.`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
         installExternalCli(ext);
@@ -446,7 +446,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }
         catch (err) {
             console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     }
     for (const ext of externalClis) {
@@ -485,7 +485,7 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
             console.error(chalk.dim(`  Tip: '${binary}' exists on your PATH. Use 'opencli register ${binary}' to add it as an external CLI.`));
         }
         program.outputHelp();
-        process.exitCode = 1;
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
     });
     program.parse();
 }

package/dist/clis/antigravity/serve.js

@@ -11,7 +11,7 @@
  */
 import { createServer } from 'node:http';
 import { CDPBridge } from '../../browser/cdp.js';
-import { getErrorMessage } from '../../errors.js';
+import { EXIT_CODES, getErrorMessage } from '../../errors.js';
 // ─── Helpers ─────────────────────────────────────────────────────────
 function generateMsgId() {
     const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
@@ -506,7 +506,7 @@ export async function startServe(opts = {}) {
         console.error('\n[serve] Shutting down...');
         cdp?.close().catch(() => { });
         server.close();
-        process.exit(0);
+        process.exit(EXIT_CODES.SUCCESS);
     };
     process.on('SIGTERM', shutdown);
     process.on('SIGINT', shutdown);

package/dist/clis/sinafinance/rolling-news.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sinafinance rolling news feed
+ */
+export {};

package/dist/clis/sinafinance/rolling-news.js

@@ -0,0 +1,40 @@
+/**
+ * Sinafinance rolling news feed
+ */
+import { cli, Strategy } from '../../registry.js';
+cli({
+    site: 'sinafinance',
+    name: 'rolling-news',
+    description: '新浪财经滚动新闻',
+    domain: 'finance.sina.com.cn/roll',
+    strategy: Strategy.COOKIE,
+    args: [],
+    columns: ['column', 'title', 'date', 'url'],
+    func: async (page, _args) => {
+        await page.goto(`https://finance.sina.com.cn/roll/#pageid=384&lid=2519`);
+        await page.wait({ selector: '.d_list_txt li', timeout: 10000 });
+        const payload = await page.evaluate(`
+      (() => {
+        const cleanText = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+        const results = [];
+        document.querySelectorAll('.d_list_txt li').forEach(el => {
+          const titleEl = el.querySelector('.c_tit a');
+          const columnEl = el.querySelector('.c_chl');
+          const dateEl = el.querySelector('.c_time');
+          const url = titleEl?.getAttribute('href') || '';
+          if (!url) return;
+          results.push({
+            title: cleanText(titleEl?.textContent || ''),
+            column: cleanText(columnEl?.textContent || ''),
+            date: cleanText(dateEl?.textContent || ''),
+            url: url,
+          });
+        });
+        return results;
+      })()
+    `);
+        if (!Array.isArray(payload))
+            return [];
+        return payload;
+    },
+});

package/dist/clis/sinafinance/stock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sinafinance stock quote — A股 / 港股 / 美股
+ *
+ * Uses two public Sina APIs (no browser required):
+ *   suggest3.sinajs.cn  — symbol search
+ *   hq.sinajs.cn        — real-time quote
+ */
+export {};

package/dist/clis/sinafinance/stock.js

@@ -0,0 +1,117 @@
+/**
+ * Sinafinance stock quote — A股 / 港股 / 美股
+ *
+ * Uses two public Sina APIs (no browser required):
+ *   suggest3.sinajs.cn  — symbol search
+ *   hq.sinajs.cn        — real-time quote
+ */
+import { cli, Strategy } from '../../registry.js';
+import { CliError } from '../../errors.js';
+const MARKET_CN = '11';
+const MARKET_HK = '31';
+const MARKET_US = '41';
+async function fetchGBK(url) {
+    const res = await fetch(url, { headers: { Referer: 'https://finance.sina.com.cn' } });
+    if (!res.ok)
+        throw new CliError('FETCH_ERROR', `Sina API HTTP ${res.status}`, 'Check your network');
+    const buf = await res.arrayBuffer();
+    return new TextDecoder('gbk').decode(buf);
+}
+function parseSuggest(raw, markets) {
+    const m = raw.match(/suggestvalue="(.*)"/s);
+    if (!m)
+        return [];
+    return m[1].split(';').filter(Boolean).map(s => {
+        const p = s.split(',');
+        return { name: p[4] || p[0] || '', market: p[1] || '', symbol: p[3] || '' };
+    }).filter(e => markets.includes(e.market));
+}
+function hqSymbol(e) {
+    if (e.market === MARKET_HK)
+        return `hk${e.symbol}`;
+    if (e.market === MARKET_US)
+        return `gb_${e.symbol}`;
+    return e.symbol; // A股: already "sh600519" / "sz300XXX"
+}
+function parseHq(raw, sym) {
+    const escaped = sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const m = raw.match(new RegExp(`hq_str_${escaped}="([^"]*)"`));
+    return m ? m[1].split(',') : [];
+}
+function fmtMktCap(val) {
+    const n = parseFloat(val);
+    if (!n)
+        return '';
+    if (n >= 1e12)
+        return (n / 1e12).toFixed(2) + 'T';
+    if (n >= 1e9)
+        return (n / 1e9).toFixed(2) + 'B';
+    if (n >= 1e6)
+        return (n / 1e6).toFixed(2) + 'M';
+    return String(n);
+}
+cli({
+    site: 'sinafinance',
+    name: 'stock',
+    description: '新浪财经行情（A股/港股/美股）',
+    domain: 'suggest3.sinajs.cn,hq.sinajs.cn',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'key', type: 'string', required: true, positional: true, help: 'Stock name or code (e.g. 贵州茅台, 腾讯控股, AAPL)' },
+        { name: 'market', type: 'string', default: 'auto', help: 'Market: cn, hk, us, auto (default: auto searches cn → hk → us)' },
+    ],
+    columns: ['Symbol', 'Name', 'Price', 'Change', 'ChangePercent', 'Open', 'High', 'Low', 'Volume', 'MarketCap'],
+    func: async (_page, args) => {
+        const key = String(args.key);
+        const market = String(args.market);
+        const marketMap = {
+            cn: [MARKET_CN], hk: [MARKET_HK], us: [MARKET_US],
+            auto: [MARKET_CN, MARKET_HK, MARKET_US],
+        };
+        const targetMarkets = marketMap[market];
+        if (!targetMarkets) {
+            throw new CliError('INPUT_ERROR', `Invalid market: "${market}"`, 'Expected cn, hk, us, or auto');
+        }
+        // 1. Search symbol — only request the markets we care about
+        const suggestRaw = await fetchGBK(`https://suggest3.sinajs.cn/suggest/type=${targetMarkets.join(',')}&key=${encodeURIComponent(key)}`);
+        const entries = parseSuggest(suggestRaw, targetMarkets);
+        if (!entries.length) {
+            throw new CliError('NOT_FOUND', `No stock found for "${key}"`, 'Try a different name, code, or --market');
+        }
+        // Pick best match: score by name similarity, tiebreak by market priority
+        const needle = key.toLowerCase();
+        const score = (e) => {
+            const n = e.name.toLowerCase();
+            if (n === needle)
+                return 1;
+            if (n.includes(needle))
+                return needle.length / n.length;
+            return 0;
+        };
+        const best = entries.sort((a, b) => {
+            const d = score(b) - score(a);
+            return d !== 0 ? d : targetMarkets.indexOf(a.market) - targetMarkets.indexOf(b.market);
+        })[0];
+        // 2. Fetch quote
+        const sym = hqSymbol(best);
+        const hqRaw = await fetchGBK(`https://hq.sinajs.cn/list=${sym}`);
+        const f = parseHq(hqRaw, sym);
+        if (f.length < 2 || !f[0]) {
+            throw new CliError('NOT_FOUND', `No quote data for "${key}"`, 'Market may be closed or data unavailable');
+        }
+        if (best.market === MARKET_CN) {
+            const price = parseFloat(f[3]);
+            const prev = parseFloat(f[2]);
+            const chg = (price - prev).toFixed(2);
+            const chgPct = ((price - prev) / prev * 100).toFixed(2) + '%';
+            return [{ Symbol: sym.toUpperCase(), Name: f[0], Price: f[3], Change: chg, ChangePercent: chgPct, Open: f[1], High: f[4], Low: f[5], Volume: f[8], MarketCap: '' }];
+        }
+        if (best.market === MARKET_HK) {
+            // [2]=price [4]=high [5]=low [6]=open [7]=change [8]=change% [11]=volume
+            return [{ Symbol: best.symbol, Name: f[1], Price: f[2], Change: f[7], ChangePercent: f[8] + '%', Open: f[6], High: f[4], Low: f[5], Volume: f[11], MarketCap: '' }];
+        }
+        // MARKET_US: [1]=price [2]=change% [4]=change [6]=open [7]=today_low [8]=52wH [9]=52wL [10]=volume [12]=mktcap
+        return [{ Symbol: best.symbol.toUpperCase(), Name: f[0], Price: f[1], Change: f[4], ChangePercent: f[2] + '%', Open: f[6], High: f[8], Low: f[9], Volume: f[10], MarketCap: fmtMktCap(f[12]) }];
+    },
+});

package/dist/commanderAdapter.js

@@ -14,7 +14,7 @@ import { fullName, getRegistry } from './registry.js';
 import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand } from './execution.js';
-import { CliError, ERROR_ICONS, getErrorMessage, BrowserConnectError, AuthRequiredError, TimeoutError, SelectorError, EmptyResultError, ArgumentError, AdapterLoadError, CommandExecutionError, } from './errors.js';
+import { CliError, EXIT_CODES, ERROR_ICONS, getErrorMessage, BrowserConnectError, AuthRequiredError, TimeoutError, SelectorError, EmptyResultError, ArgumentError, AdapterLoadError, CommandExecutionError, } from './errors.js';
 import { checkDaemonStatus } from './browser/discover.js';
 export function normalizeArgValue(argType, value, name) {
     if (argType !== 'bool')
@@ -28,7 +28,7 @@ export function normalizeArgValue(argType, value, name) {
         return true;
     if (normalized === 'false')
         return false;
-    throw new CliError('ARGUMENT', `"${name}" must be either "true" or "false".`);
+    throw new ArgumentError(`"${name}" must be either "true" or "false".`);
 }
 /**
  * Register a single CliCommand as a Commander subcommand.
@@ -106,10 +106,33 @@ export function registerCommandToProgram(siteCmd, cmd) {
         }
         catch (err) {
             await renderError(err, fullName(cmd), optionsRecord.verbose === true);
-            process.exitCode = 1;
+            process.exitCode = resolveExitCode(err);
         }
     });
 }
+// ── Exit code resolution ─────────────────────────────────────────────────────
+/**
+ * Map any thrown value to a Unix process exit code.
+ *
+ * - CliError subclasses carry their own exitCode (set in errors.ts).
+ * - Generic Error objects are classified by message pattern so that
+ *   un-typed auth / not-found errors from adapters still produce
+ *   meaningful exit codes for shell scripts.
+ */
+function resolveExitCode(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    // Pattern-based fallback for untyped errors thrown by third-party adapters.
+    const msg = getErrorMessage(err);
+    const kind = classifyGenericError(msg);
+    if (kind === 'auth')
+        return EXIT_CODES.NOPERM;
+    if (kind === 'not-found')
+        return EXIT_CODES.EMPTY_RESULT;
+    if (kind === 'http')
+        return EXIT_CODES.GENERIC_ERROR; // HTTP 4xx/5xx → generic; renderer shows details
+    return EXIT_CODES.GENERIC_ERROR;
+}
 // ── Error rendering ──────────────────────────────────────────────────────────
 const ISSUES_URL = 'https://github.com/jackwener/opencli/issues';
 /** Pattern-based classifier for untyped errors thrown by adapters. */

package/dist/daemon.js

@@ -21,6 +21,7 @@
 import { createServer } from 'node:http';
 import { WebSocketServer, WebSocket } from 'ws';
 import { DEFAULT_DAEMON_PORT } from './constants.js';
+import { EXIT_CODES } from './errors.js';
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
 // ─── State ───────────────────────────────────────────────────────────
@@ -41,7 +42,7 @@ function resetIdleTimer() {
         clearTimeout(idleTimer);
     idleTimer = setTimeout(() => {
         console.error('[daemon] Idle timeout, shutting down');
-        process.exit(0);
+        process.exit(EXIT_CODES.SUCCESS);
     }, IDLE_TIMEOUT);
 }
 // ─── HTTP Server ─────────────────────────────────────────────────────
@@ -269,10 +270,10 @@ httpServer.listen(PORT, '127.0.0.1', () => {
 httpServer.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {
         console.error(`[daemon] Port ${PORT} already in use — another daemon is likely running. Exiting.`);
-        process.exit(1);
+        process.exit(EXIT_CODES.SERVICE_UNAVAIL);
     }
     console.error('[daemon] Server error:', err.message);
-    process.exit(1);
+    process.exit(EXIT_CODES.GENERIC_ERROR);
 });
 // Graceful shutdown
 function shutdown() {
@@ -285,7 +286,7 @@ function shutdown() {
     if (extensionWs)
         extensionWs.close();
     httpServer.close();
-    process.exit(0);
+    process.exit(EXIT_CODES.SUCCESS);
 }
 process.on('SIGTERM', shutdown);
 process.on('SIGINT', shutdown);

package/dist/errors.d.ts

@@ -4,13 +4,41 @@
  * All errors thrown by the framework should extend CliError so that
  * the top-level handler in commanderAdapter.ts can render consistent,
  * helpful output with emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * opencli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
+ *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
+ *  77   Permission denied / auth needed (AuthRequiredError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERIC_ERROR: 1;
+    readonly USAGE_ERROR: 2;
+    readonly EMPTY_RESULT: 66;
+    readonly SERVICE_UNAVAIL: 69;
+    readonly TEMPFAIL: 75;
+    readonly NOPERM: 77;
+    readonly CONFIG_ERROR: 78;
+    readonly INTERRUPTED: 130;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
 export declare class CliError extends Error {
     /** 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;
-    constructor(code: string, message: string, hint?: string);
+    /** Unix process exit code — defaults to 1 (generic error) */
+    readonly exitCode: ExitCode;
+    constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
 }
 export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
 export declare class BrowserConnectError extends CliError {

package/dist/errors.js

@@ -4,61 +4,99 @@
  * All errors thrown by the framework should extend CliError so that
  * the top-level handler in commanderAdapter.ts can render consistent,
  * helpful output with emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * opencli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
+ *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
+ *  77   Permission denied / auth needed (AuthRequiredError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
+// ── Exit code table ──────────────────────────────────────────────────────────
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERIC_ERROR: 1,
+    USAGE_ERROR: 2, // Bad arguments / command misuse
+    EMPTY_RESULT: 66, // No data / not found           (EX_NOINPUT)
+    SERVICE_UNAVAIL: 69, // Daemon / browser unavailable  (EX_UNAVAILABLE)
+    TEMPFAIL: 75, // Timeout — try again later     (EX_TEMPFAIL)
+    NOPERM: 77, // Auth required / permission    (EX_NOPERM)
+    CONFIG_ERROR: 78, // Missing / invalid config      (EX_CONFIG)
+    INTERRUPTED: 130, // Ctrl-C / SIGINT
+};
+// ── Base class ───────────────────────────────────────────────────────────────
 export class CliError extends Error {
     /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
     code;
     /** Human-readable hint on how to fix the problem */
     hint;
-    constructor(code, message, hint) {
+    /** Unix process exit code — defaults to 1 (generic error) */
+    exitCode;
+    constructor(code, message, hint, exitCode = EXIT_CODES.GENERIC_ERROR) {
         super(message);
         this.name = new.target.name;
         this.code = code;
         this.hint = hint;
+        this.exitCode = exitCode;
     }
 }
 export class BrowserConnectError extends CliError {
     kind;
     constructor(message, hint, kind = 'unknown') {
-        super('BROWSER_CONNECT', message, hint);
+        super('BROWSER_CONNECT', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
         this.kind = kind;
     }
 }
 export class AdapterLoadError extends CliError {
-    constructor(message, hint) { super('ADAPTER_LOAD', message, hint); }
+    constructor(message, hint) {
+        super('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+    }
 }
 export class CommandExecutionError extends CliError {
-    constructor(message, hint) { super('COMMAND_EXEC', message, hint); }
+    constructor(message, hint) {
+        super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
+    }
 }
 export class ConfigError extends CliError {
-    constructor(message, hint) { super('CONFIG', message, hint); }
+    constructor(message, hint) {
+        super('CONFIG', message, hint, EXIT_CODES.CONFIG_ERROR);
+    }
 }
 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}`);
+        super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome and log in to https://${domain}`, EXIT_CODES.NOPERM);
         this.domain = domain;
     }
 }
 export class TimeoutError extends CliError {
     constructor(label, seconds, hint) {
-        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var');
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var', EXIT_CODES.TEMPFAIL);
     }
 }
 export class ArgumentError extends CliError {
-    constructor(message, hint) { super('ARGUMENT', message, hint); }
+    constructor(message, hint) {
+        super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
+    }
 }
 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');
+        super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in', EXIT_CODES.EMPTY_RESULT);
     }
 }
 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.');
+        super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.', EXIT_CODES.GENERIC_ERROR);
     }
 }
-// ── Utilities ───────────────────────────────────────────────────────────
+// ── Utilities ───────────────────────────────────────────────────────────────
 /** Extract a human-readable message from an unknown caught value. */
 export function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);

package/dist/external.js

@@ -6,7 +6,7 @@ import { spawnSync, execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import chalk from 'chalk';
 import { log } from './logger.js';
-import { getErrorMessage } from './errors.js';
+import { EXIT_CODES, getErrorMessage } from './errors.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function getUserRegistryPath() {
     const home = os.homedir();
@@ -154,7 +154,7 @@ export function executeExternalCli(name, args, preloaded) {
         // 2. Try to auto install
         const success = installExternalCli(cli);
         if (!success) {
-            process.exitCode = 1;
+            process.exitCode = EXIT_CODES.SERVICE_UNAVAIL;
             return;
         }
     }
@@ -162,7 +162,7 @@ export function executeExternalCli(name, args, preloaded) {
     const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
     if (result.error) {
         console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
-        process.exitCode = 1;
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
         return;
     }
     if (result.status !== null) {

package/dist/main.js

@@ -21,6 +21,7 @@ import { runCli } from './cli.js';
 import { emitHook } from './hooks.js';
 import { installNodeNetwork } from './node-network.js';
 import { registerUpdateNoticeOnExit, checkForUpdateBackground } from './update-check.js';
+import { EXIT_CODES } from './errors.js';
 installNodeNetwork();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -53,7 +54,7 @@ if (getCompIdx !== -1) {
         cursor = words.length;
     const candidates = getCompletions(words, cursor);
     process.stdout.write(candidates.join('\n') + '\n');
-    process.exit(0);
+    process.exit(EXIT_CODES.SUCCESS);
 }
 await emitHook('onStartup', { command: '__startup__', args: {} });
 runCli(BUILTIN_CLIS, USER_CLIS);