@jackwener/opencli 1.5.4 → 1.5.5

package/src/errors.ts

@@ -4,48 +4,96 @@
  * 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
+} as const;
+
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+
+// ── Base class ───────────────────────────────────────────────────────────────
+
 export 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;
+  /** Unix process exit code — defaults to 1 (generic error) */
+  readonly exitCode: ExitCode;
 
-  constructor(code: string, message: string, hint?: string) {
+  constructor(code: string, message: string, hint?: string, exitCode: ExitCode = EXIT_CODES.GENERIC_ERROR) {
     super(message);
     this.name = new.target.name;
     this.code = code;
     this.hint = hint;
+    this.exitCode = exitCode;
   }
 }
 
+// ── Typed subclasses ─────────────────────────────────────────────────────────
+
 export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
 
 export class BrowserConnectError extends CliError {
   readonly kind: BrowserConnectKind;
   constructor(message: string, hint?: string, kind: BrowserConnectKind = '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: string, hint?: string) { super('ADAPTER_LOAD', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+  }
 }
 
 export class CommandExecutionError extends CliError {
-  constructor(message: string, hint?: string) { super('COMMAND_EXEC', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
+  }
 }
 
 export class ConfigError extends CliError {
-  constructor(message: string, hint?: string) { super('CONFIG', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('CONFIG', message, hint, EXIT_CODES.CONFIG_ERROR);
+  }
 }
 
 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}`);
+    super(
+      'AUTH_REQUIRED',
+      message ?? `Not logged in to ${domain}`,
+      `Please open Chrome and log in to https://${domain}`,
+      EXIT_CODES.NOPERM,
+    );
     this.domain = domain;
   }
 }
@@ -56,27 +104,40 @@ export class TimeoutError extends CliError {
       '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: string, hint?: string) { super('ARGUMENT', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
+  }
 }
 
 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');
+    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: string, hint?: string) {
-    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: unknown): string {

package/src/external.ts

@@ -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));
 
@@ -180,7 +180,7 @@ export function executeExternalCli(name: string, args: string[], preloaded?: Ext
     // 2. Try to auto install
     const success = installExternalCli(cli);
     if (!success) {
-      process.exitCode = 1;
+      process.exitCode = EXIT_CODES.SERVICE_UNAVAIL;
       return;
     }
   }
@@ -189,7 +189,7 @@ export function executeExternalCli(name: string, args: string[], preloaded?: Ext
   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;
   }
   

package/src/main.ts

@@ -22,6 +22,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();
 
@@ -57,7 +58,7 @@ if (getCompIdx !== -1) {
   if (cursor === undefined) 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: {} });

package/src/tui.ts

@@ -4,6 +4,7 @@
  * Uses raw stdin mode + ANSI escape codes for interactive prompts.
  */
 import chalk from 'chalk';
+import { EXIT_CODES } from './errors.js';
 
 export interface CheckboxItem {
   label: string;
@@ -161,7 +162,7 @@ export async function checkboxPrompt(
       // Ctrl+C — exit process
       if (key === '\x03') {
         cleanup();
-        process.exit(130);
+        process.exit(EXIT_CODES.INTERRUPTED);
       }
     }