hacksh 0.16.0 → 0.17.0

package/README.md

@@ -23,6 +23,7 @@ interactive input with `prompt`.
 - [Output formats](#output-formats)
 - [Programmatic API and errors](#programmatic-api-and-errors)
   - [Entry points](#entry-points)
+  - [Composable run functions](#composable-run-functions)
   - [Printers and events](#printers-and-events)
   - [Standalone parsing and help](#standalone-parsing-and-help)
   - [Errors](#errors)
@@ -129,6 +130,7 @@ const copy = defineCommand({
   }),
   run({ args }) {
     const [destination, ...files] = args.positionals; // [string, ...string[]]
+    return { destination, files };
   },
 });
 ```
@@ -346,6 +348,8 @@ context API to `node:child_process`, `spawnSync`, or a custom subprocess wrapper
 handler so execution uses the invocation’s environment, cancellation, and printer.
 
 ```ts
+import { HackshExecError } from "hacksh";
+
 const check = defineCommand({
   name: "check-head",
   async run({ exec, logger }) {
@@ -359,7 +363,7 @@ const check = defineCommand({
         return;
       }
       // Missing executables, cancellation, and other failures must still fail the command.
-      throw new Error("Could not inspect HEAD", { cause: head });
+      throw new HackshExecError("Could not inspect HEAD", head);
     }
     logger.info("HEAD is {commit}", { commit: head.stdout });
   },
@@ -482,8 +486,9 @@ holding the exact text, including the newline `println` adds, or
 pretty stdout, except that terminal control sequences are removed as in every JSON string. `json`
 values are normalized like log properties.
 
-hacksh never prints a `run` return value; it is returned to `runCommand` callers only. Output that
-was written before a failure stays written, and the error follows on stderr. Like logger calls,
+hacksh never prints a `run` return value; it is returned to `runCommand` callers only.
+`runMain` reports thrown `HackshError` instances on stderr and rethrows other exceptions.
+Output that was written before a failure stays written. Like logger calls,
 `output` calls do not need to be awaited and are drained before execution finishes. Writing to
 `process.stdout` or `console.log` directly bypasses the printer, the output mode, and any `stdout`
 writer given to `runMain` or `runCommand`.
@@ -606,14 +611,15 @@ later aborts the context's `signal`.
 
 `runMain` listens for `SIGINT` and `SIGTERM` while it runs and removes those listeners before it
 returns or exits. The first signal aborts the invocation with an `AbortError` named after the
-signal; once `run` settles, output is drained and the process exits with 130 for `SIGINT` or 143 for
-`SIGTERM`, even if `run` threw. A second signal while `run` is still pending exits immediately with
-that signal's status.
+signal. When `run` returns, throws a `HackshError`, or rejects with that exact signal reason,
+output is drained and the process exits with 130 for `SIGINT` or 143 for `SIGTERM`. Unrelated
+exceptions and output failures still reject instead of being converted to a signal exit.
+A second signal while the invocation is pending exits immediately with that signal's status.
 
 Throw `HackshExitError(exitCode, message?)` to choose the exit status, an integer from 0 to 255.
-`runMain` prints a non-empty message as an ordinary error and prints nothing when the message is
-omitted; `onError` still receives the error. `runCommand` rethrows it, so library callers read
-`exitCode` from the caught error. Other failures exit with 1, or 130 for a cancelled prompt.
+`runMain` prints a non-empty message as an ordinary CLI error and prints nothing when the message
+is omitted; `onError` still receives the error. `runCommand` rethrows it unchanged.
+Other `HackshError` instances exit with 1, or 130 for a cancelled prompt.
 
 ## Output formats
 
@@ -621,10 +627,9 @@ omitted; `onError` still receives the error. `runCommand` rethrows it, so librar
 Their `output` option accepts `"auto"` (the default), `"pretty"`, or `"json"`. A valid
 `HACKSH_OUTPUT` environment value takes precedence over that option. `auto` selects JSON only when
 `CI` has a non-empty value; redirecting or piping stdout alone retains pretty output. Invalid
-explicit option or environment values never execute the command. `runCommand` rejects with a
-`TypeError`. `runMain` gives that error to `onError` when configured; otherwise it emits the error
-through a supplied printer or as a dedicated JSON error line, drains output, and exits with status
-code `1`. Output values are case-sensitive.
+explicit option or environment values never execute the command. Both entry points reject with a
+`TypeError`; `runMain` does not call `onError`, print a fallback error event, or force an exit.
+Output values are case-sensitive.
 
 ```ts
 await runMain(main, { output: "auto" });
@@ -687,13 +692,19 @@ the semantic events that the command emits.
 
 ### Entry points
 
-`defineCommand` preserves the handler's return type. `runCommand(command, argv, options)` handles
-help and version output without exiting, throws errors to its caller, and returns a promise of the
-awaited handler result, unioned with results from every possible routed descendant and `undefined`
-for help/version. Routing-only commands add no handler result. Async and void handlers retain their
-result types; `runMain` deliberately discards results.
-
-`runMain(command)` reads `process.argv`, prints validation or usage errors, and exits with status 1.
+`defineCommand` preserves the handler's exact return type. Handlers are ordinary functions that
+return values or `void`, synchronously or asynchronously. `runCommand(command, argv, options)`
+returns a promise of the awaited result, unioned with results from every possible routed
+descendant and `undefined` for help/version. Routing-only commands add no handler result.
+Thrown exceptions, argument errors, and output failures reject the promise. `runCommand` never
+exits or automatically prints a return value or error.
+
+`runMain(command)` reads `process.argv`, discards return values, and only handles thrown
+`HackshError` instances as normal CLI failures. Other exceptions reject without automatic error
+display, `onError`, or process exit. Pending output is drained and signal listeners are removed
+on both success and rejection. Output failures also reject, including while reporting a CLI
+error; they are not hidden by a forced exit. See
+[Cancellation and exit status](#cancellation-and-exit-status) for exit codes.
 Use `argv` to inject arguments. Omitting it uses `process.argv.slice(2)`; an empty array is an
 explicit empty invocation. `runMain` returns `Promise<void>`. A reusable entry point is an ordinary
 local function:
@@ -708,18 +719,73 @@ await mainEntry([]); // explicitly supplies no arguments
 
 Help and the usage appended to validation or routing errors use the invocation's printer.
 Usage events target stdout for help and stderr for errors. Pass `onError` to replace the entire
-default error display, including usage; output written by this application callback remains its
-own responsibility:
+default display of a `HackshError`, including usage. It receives the original error instance;
+output written by this application callback remains its own responsibility. If the callback
+throws or rejects, `runMain` drains output, removes its listeners, and rejects without exiting:
 
 ```ts
 await runMain(main, {
   argv: ["--help"],
   async onError(error) {
-    console.error(`gh-pr-commits: ${error instanceof Error ? error.message : String(error)}`);
+    console.error(`gh-pr-commits: ${error.message}`);
   },
 });
 ```
 
+### Composable run functions
+
+Use ordinary functions and `await`; no handler factory or result envelope is required.
+Throw a `HackshError` subclass for an expected CLI failure. Catch only the specific failures
+the caller can recover from and rethrow everything else:
+
+```ts
+import { z } from "zod";
+import { defineCommand, HackshError, type CommandContext } from "hacksh";
+
+class AppError extends HackshError {}
+
+class NotFoundError extends AppError {
+  readonly id: string;
+
+  constructor(id: string) {
+    super(`User ${id} was not found`);
+    this.id = id;
+  }
+}
+
+const users = new Map([["alice", { id: "alice", displayName: "Alice" }]]);
+
+function loadUser(id: string) {
+  const user = users.get(id);
+  if (!user) throw new NotFoundError(id);
+  return user;
+}
+
+const schema = z.object({ id: z.string() });
+
+function run({ args }: CommandContext<typeof schema>) {
+  try {
+    return loadUser(args.id);
+  } catch (error) {
+    if (error instanceof NotFoundError) {
+      return { id: error.id, displayName: "Guest" };
+    }
+    throw error;
+  }
+}
+
+const command = defineCommand({ args: schema, run });
+```
+
+The context's `args` is the validated, transformed schema output, not raw argv. Domain functions
+such as `loadUser` need not depend on `CommandContext`. Omit the recovery branch when an expected
+failure should reach `runMain` and be displayed there.
+
+`HackshError(message?, options?)` supports the standard `ErrorOptions.cause` and uses the concrete
+subclass name as `error.name`. Application subclasses can add their own fields. A plain `Error`,
+`TypeError`, or non-error thrown value is not classified as an expected CLI failure. Do not
+blanket-wrap unknown exceptions in `HackshError`: doing so would hide that distinction.
+
 ### Printers and events
 
 The root `hacksh` entry exposes command-definition and execution APIs. Import printer factories,
@@ -790,6 +856,8 @@ await showUsage(main, {
 
 ### Errors
 
+- `HackshError` — base class for expected CLI failures. Extend it for application-specific errors;
+  all error classes below inherit from it.
 - `HackshUsageError` — routing and usage failures (such as an unknown subcommand).
 - `HackshValidationError` — argument and option validation failures, whose `issues` identify CLI
   names such as `--repo` or `<PR>` and rejected unknown tokens in `issues[].arg`.

package/dist/{command-B-Ok_6KW.d.ts → command-t16M3-AZ.d.ts}

@@ -79,7 +79,11 @@ interface HackshIssue {
   message: string;
   issue?: $ZodIssue;
 }
-declare class HackshUsageError extends Error {
+/** An expected CLI failure that runMain reports; application errors can extend this class. */
+declare class HackshError extends Error {
+  constructor(message?: string, options?: ErrorOptions);
+}
+declare class HackshUsageError extends HackshError {
   readonly command: AnyCommandDef;
   constructor(message: string, command: AnyCommandDef, options?: ErrorOptions);
 }
@@ -95,19 +99,19 @@ interface PromptErrorDetails {
   choices?: readonly string[];
 }
 /** An input request that could not be completed safely. */
-declare class HackshPromptError extends Error {
+declare class HackshPromptError extends HackshError {
   readonly reason: HackshPromptErrorReason;
   readonly prompt: PromptErrorDetails;
   constructor(reason: HackshPromptErrorReason, prompt: PromptErrorDetails, message: string, options?: ErrorOptions);
 }
 /** An external command that did not succeed; `result` is not enumerable so error summaries omit child output. */
-declare class HackshExecError extends Error {
+declare class HackshExecError extends HackshError {
   #private;
   constructor(message: string, result: ExecFailure, options?: ErrorOptions);
   get result(): ExecFailure;
 }
 /** A requested process exit status; `runMain` exits with it and reports only a non-empty message. */
-declare class HackshExitError extends Error {
+declare class HackshExitError extends HackshError {
   readonly exitCode: number;
   constructor(exitCode: number, message?: string, options?: ErrorOptions);
 }
@@ -410,7 +414,7 @@ interface CommandDef<S extends ArgsSchema = EmptyArgs, R = unknown, Children ext
   run?(context: CommandContext<S>): R;
 }
 type AnyCommandDef = CommandDef<ArgsSchema>;
-declare function defineCommand<S extends ArgsSchema = EmptyArgs, R = never, Children extends Record<string, AnyCommandDef> = {}>(def: CommandDef<S, R, Children>): CommandDef<S, NoInfer<R>, NoInfer<Children>>;
+declare function defineCommand<S extends ArgsSchema = EmptyArgs, R = never, Children extends Record<string, AnyCommandDef> = {}>(def: CommandDef<S, R, Children>): NoInfer<CommandDef<S, R, Children>>;
 //#endregion
-export { HackshErrorSummary as $, SelectPromptState as A, UsageArgumentSummary as B, PrintStream as C, PromptState as D, PromptPrintEvent as E, UsagePrintEvent as F, showUsage as G, UsageOptionSummary as H, VersionPrintEvent as I, LogLevel as J, summarizeUsage as K, createJsonPrinter as L, TerminalInput as M, TerminalOutput as N, PromptStatus as O, TextPromptState as P, HackshErrorKind as Q, resolveOutputMode as R, PrintEvent as S, PromptChoiceState as T, UsageSummary as U, UsageCommandSummary as V, renderUsage as W, LogRecord as X, LogProperties as Y, Logger as Z, OutputFormat as _, ExecSkipped as _t, ArgsSchema as a, HackshUsageError as at, OutputPrintEvent as b, SelectOption as c, PromptKind as ct, Output as d, ExecCommand as dt, HackshExecError as et, ConfirmPromptState as f, ExecFailure as ft, LogPrintEvent as g, ExecReturn as gt, JsonPrinterOptions as h, ExecResult as ht, defineCommand as i, HackshPromptErrorReason as it, StreamColors as j, ResolveOutputModeOptions as k, SelectOptions as l, ValidationIssueSummary as lt, ExecPrintEvent as m, ExecOptions as mt, CommandContext as n, HackshIssue as nt, ConfirmOptions as o, HackshValidationError as ot, ErrorPrintEvent as p, ExecFailureReason as pt, LogKind as q, CommandDef as r, HackshPromptError as rt, Prompter as s, PromptErrorDetails as st, AnyCommandDef as t, HackshExitError as tt, TextOptions as u, Exec as ut, OutputMode as v, ExecSuccess as vt, Printer as w, OutputWriter as x, OutputPreference as y, ShowUsageOptions as z };
-//# sourceMappingURL=command-B-Ok_6KW.d.ts.map
+export { HackshErrorKind as $, SelectPromptState as A, UsageArgumentSummary as B, PrintStream as C, PromptState as D, PromptPrintEvent as E, UsagePrintEvent as F, showUsage as G, UsageOptionSummary as H, VersionPrintEvent as I, LogLevel as J, summarizeUsage as K, createJsonPrinter as L, TerminalInput as M, TerminalOutput as N, PromptStatus as O, TextPromptState as P, HackshError as Q, resolveOutputMode as R, PrintEvent as S, PromptChoiceState as T, UsageSummary as U, UsageCommandSummary as V, renderUsage as W, LogRecord as X, LogProperties as Y, Logger as Z, OutputFormat as _, ExecReturn as _t, ArgsSchema as a, HackshPromptErrorReason as at, OutputPrintEvent as b, SelectOption as c, PromptErrorDetails as ct, Output as d, Exec as dt, HackshErrorSummary as et, ConfirmPromptState as f, ExecCommand as ft, LogPrintEvent as g, ExecResult as gt, JsonPrinterOptions as h, ExecOptions as ht, defineCommand as i, HackshPromptError as it, StreamColors as j, ResolveOutputModeOptions as k, SelectOptions as l, PromptKind as lt, ExecPrintEvent as m, ExecFailureReason as mt, CommandContext as n, HackshExitError as nt, ConfirmOptions as o, HackshUsageError as ot, ErrorPrintEvent as p, ExecFailure as pt, LogKind as q, CommandDef as r, HackshIssue as rt, Prompter as s, HackshValidationError as st, AnyCommandDef as t, HackshExecError as tt, TextOptions as u, ValidationIssueSummary as ut, OutputMode as v, ExecSkipped as vt, Printer as w, OutputWriter as x, OutputPreference as y, ExecSuccess as yt, ShowUsageOptions as z };
+//# sourceMappingURL=command-t16M3-AZ.d.ts.map

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { G as showUsage, K as summarizeUsage, M as TerminalInput, N as TerminalOutput, W as renderUsage, Z as Logger, _t as ExecSkipped, a as ArgsSchema, at as HackshUsageError, c as SelectOption, ct as PromptKind, d as Output, dt as ExecCommand, et as HackshExecError, ft as ExecFailure, gt as ExecReturn, ht as ExecResult, i as defineCommand, it as HackshPromptErrorReason, l as SelectOptions, mt as ExecOptions, n as CommandContext, nt as HackshIssue, o as ConfirmOptions, ot as HackshValidationError, pt as ExecFailureReason, r as CommandDef, rt as HackshPromptError, s as Prompter, st as PromptErrorDetails, t as AnyCommandDef, tt as HackshExitError, u as TextOptions, ut as Exec, vt as ExecSuccess, w as Printer, y as OutputPreference, z as ShowUsageOptions } from "./command-B-Ok_6KW.js";
+import { G as showUsage, K as summarizeUsage, M as TerminalInput, N as TerminalOutput, Q as HackshError, W as renderUsage, Z as Logger, _t as ExecReturn, a as ArgsSchema, at as HackshPromptErrorReason, c as SelectOption, ct as PromptErrorDetails, d as Output, dt as Exec, ft as ExecCommand, gt as ExecResult, ht as ExecOptions, i as defineCommand, it as HackshPromptError, l as SelectOptions, lt as PromptKind, mt as ExecFailureReason, n as CommandContext, nt as HackshExitError, o as ConfirmOptions, ot as HackshUsageError, pt as ExecFailure, r as CommandDef, rt as HackshIssue, s as Prompter, st as HackshValidationError, t as AnyCommandDef, tt as HackshExecError, u as TextOptions, vt as ExecSkipped, w as Printer, y as OutputPreference, yt as ExecSuccess, z as ShowUsageOptions } from "./command-t16M3-AZ.js";
 import { output } from "zod/v4/core";
 //#region src/parser.d.ts
 /**
@@ -33,11 +33,11 @@ type CommandResult<C> = HandlerResult<C> | (C extends {
 } ? Children extends Record<string, AnyCommandDef> ? string extends keyof Children ? unknown : CommandResult<Children[keyof Children]> : never : never);
 declare function runCommand<C extends AnyCommandDef>(root: C, argv: string[], options?: RunCommandOptions): Promise<CommandResult<C> | undefined>;
 interface RunMainOptions extends OutputOptions {
-  onError?: (error: unknown) => void | Promise<void>;
+  onError?: (error: HackshError) => void | Promise<void>;
   argv?: string[];
   printer?: Printer;
 }
 declare function runMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): Promise<void>;
 //#endregion
-export { type CommandContext, type CommandDef, type ConfirmOptions, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecResult, type ExecReturn, type ExecSkipped, type ExecSuccess, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type Logger, type Output, type OutputOptions, type PromptErrorDetails, type PromptKind, type Prompter, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type ShowUsageOptions, type TextOptions, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
+export { type CommandContext, type CommandDef, type ConfirmOptions, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecResult, type ExecReturn, type ExecSkipped, type ExecSuccess, HackshError, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type Logger, type Output, type OutputOptions, type PromptErrorDetails, type PromptKind, type Prompter, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type ShowUsageOptions, type TextOptions, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as createExec, c as HackshPromptError, d as summarizeError, f as summarizeErrors, i as resolveOutputMode, l as HackshUsageError, n as createJsonPrinter, o as HackshExecError, r as createPrintQueue, s as HackshExitError, t as createPrettyPrinter, u as HackshValidationError } from "./pretty-DJ2CE6TU.js";
+import { a as createExec, c as HackshExitError, d as HackshValidationError, f as summarizeError, i as resolveOutputMode, l as HackshPromptError, n as createJsonPrinter, o as HackshError, p as summarizeErrors, r as createPrintQueue, s as HackshExecError, t as createPrettyPrinter, u as HackshUsageError } from "./pretty-Db7-kATM.js";
 import { globalRegistry, safeParseAsync } from "zod/v4/core";
 import { parseArgs as parseArgs$1 } from "node:util";
 import { readFile, realpath } from "node:fs/promises";
@@ -1178,13 +1178,6 @@ async function runCommand(root, argv, options = {}) {
 		await output.drain();
 	}
 }
-async function drainAndExit(output, code = 1) {
-	try {
-		await output.drain();
-	} finally {
-		process.exit(code);
-	}
-}
 function commandErrorExitCode(error) {
 	if (error instanceof HackshExitError) return error.exitCode;
 	return error instanceof HackshPromptError && error.reason === "cancelled" ? 130 : 1;
@@ -1213,21 +1206,6 @@ function listenForExitSignals() {
 		}
 	};
 }
-async function reportOutputSetupError(error, options) {
-	if (options.onError) {
-		await options.onError(error);
-		return drainAndExit(createPrintQueue(options.printer ?? { print: () => void 0 }));
-	}
-	const output = createPrintQueue(options.printer ?? createJsonPrinter({
-		stdout: options.stdout ?? process.stdout,
-		stderr: options.stderr ?? process.stderr
-	}));
-	await output.printer.print({
-		type: "error",
-		error: summarizeError(error)
-	});
-	return drainAndExit(output);
-}
 async function reportCommandError(error, output) {
 	if (error instanceof HackshExitError && error.message === "") return;
 	await output.printer.print({
@@ -1240,37 +1218,33 @@ async function reportCommandError(error, output) {
 	});
 }
 async function runMain(command, options = {}) {
-	let output;
-	try {
-		output = prepareOutput(options, options.env ?? process.env);
-	} catch (error) {
-		return reportOutputSetupError(error, options);
-	}
+	const output = prepareOutput(options, options.env ?? process.env);
 	const signals = listenForExitSignals();
-	const exit = (code) => {
-		signals.release();
-		return drainAndExit(output, signals.exitCode() ?? code);
-	};
+	let exitCode;
 	try {
-		await executeCommand(command, options.argv ?? process.argv.slice(2), output, options.env, signals.signal, () => findPackageVersion(process.argv[1]));
-	} catch (error) {
-		if (options.onError) {
-			await options.onError(error);
-			return exit(commandErrorExitCode(error));
+		try {
+			await executeCommand(command, options.argv ?? process.argv.slice(2), output, options.env, signals.signal, () => findPackageVersion(process.argv[1]));
+		} catch (error) {
+			const signalExitCode = signals.exitCode();
+			if (signalExitCode !== void 0 && error === signals.signal.reason) exitCode = signalExitCode;
+			else {
+				if (!(error instanceof HackshError)) throw error;
+				if (options.onError) await options.onError(error);
+				else await reportCommandError(error, output);
+				exitCode = commandErrorExitCode(error);
+			}
 		}
+	} finally {
 		try {
-			await reportCommandError(error, output);
+			await output.drain();
 		} finally {
-			await exit(commandErrorExitCode(error));
+			signals.release();
 		}
-	} finally {
-		signals.release();
 	}
-	const signalExitCode = signals.exitCode();
-	if (signalExitCode !== void 0) return drainAndExit(output, signalExitCode);
-	await output.drain();
+	const code = signals.exitCode() ?? exitCode;
+	if (code !== void 0) process.exit(code);
 }
 //#endregion
-export { HackshExecError, HackshExitError, HackshPromptError, HackshUsageError, HackshValidationError, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
+export { HackshError, HackshExecError, HackshExitError, HackshPromptError, HackshUsageError, HackshValidationError, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
 
 //# sourceMappingURL=index.js.map