hacksh 0.16.0 → 0.18.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`.
@@ -523,7 +528,7 @@ finishes. A printer failure rejects the invocation without changing a successful
 
 ### Interactive input
 
-Every `run` context has a `prompt` with `select`, `confirm`, and `text` methods. Interactive input
+Every `run` context has a `prompt` with `select`, `autocomplete`, `confirm`, and `text` methods. Interactive input
 is separate from `logger`: prompts share the invocation's selected printer, serialized output queue,
 terminal lock, output mode, and abort signal.
 
@@ -557,15 +562,57 @@ uses `initialValue` when supplied and otherwise means no. Text displays its plac
 using it as input, supports editing, and repeats the prompt only when `validate` returns a nonempty
 message; `""` means valid. Backspace removes one Unicode code point. Input pasted after a selection
 or confirmation is retained for the next sequential prompt instead of being discarded.
-The built-in prompt API intentionally stops at select, confirm, and text; it does not provide a
-multiselect prompt.
+The built-in prompt API does not provide a multiselect prompt.
+
+Use `autocomplete` for a searchable single choice:
+
+```ts
+const environment = await prompt.autocomplete({
+  message: "Environment",
+  placeholder: "Type to filter…",
+  options: [
+    { value: "production", label: "Production", priority: 20 },
+    { value: "staging", label: "Staging", hint: "safe default", priority: 10 },
+  ],
+  sortBy: (item) => item.priority,
+}); // "production" | "staging"; displays Staging before Production
+```
+
+Autocomplete filters labels (falling back to values) by case-insensitive substring,
+preserving the configured option order rather than ranking matches. An empty query
+shows all options, initially with none selected. Down enters selection at the first
+match; Up/Down move without wrapping. Up at the first match or Escape returns to
+editing. Typing or Backspace while selecting edits the query and returns to input.
+Enter submits only a selected match; it does nothing while editing or with no matches.
+Backspace removes one grapheme cluster. Escape while editing and Ctrl-C cancel.
+The placeholder is display-only, reappears when the query becomes empty, and remains
+until the terminal delivers committed input; OS IME composition is not observable.
+The pretty printer anchors the real cursor at the input end, including wrapped input.
+
+Both `select` and `autocomplete` accept `sortBy: (item) => string | number`. The
+callback receives the complete inferred option item, including custom fields such
+as `priority`; the prompt still returns only its `value`, preserving literal types.
+Without `sortBy`, options retain their definition order. With it, keys are computed
+once per option at prompt startup and sorted ascending, stably: equal keys retain
+definition order, and the original array is never reordered. Autocomplete filtering
+preserves this sorted order without recomputing keys. `initialValue` on select
+chooses a value in the sorted list without changing that order.
+
+Numeric keys use numeric order; strings use locale-independent UTF-16 lexical
+order, not locale-aware collation or numeric-string ordering. All keys in one
+prompt must have the same type. Invalid keys (including `NaN`) or mixed types
+produce `HackshPromptError` with reason `invalid-options`; a thrown callback
+produces `input-error` with the original error as `cause`.
+Explicit option types take the whole item type, for example
+`SelectOptions<{ value: "staging" | "production"; priority: number }>`.
 
 Prompts are allowed only when the resolved mode is interactive: pretty output outside CI with TTY
 stdin and stdout. JSON, CI, and non-TTY invocations throw `HackshPromptError` immediately even if a
 default is available. Its `reason` and `prompt` fields identify why input failed and the prompt's
-`kind`, `message`, and select `choices`. Reasons distinguish `non-interactive`, `cancelled`,
+`kind`, `message`, and select/autocomplete `choices`. Reasons distinguish `non-interactive`, `cancelled`,
 `aborted`, `eof`, `overlapping`, `invalid-options`, `input-error`, and `printer-error`. Ctrl-C and
-Escape cancel; `runMain` reports cancellation and exits with status 130. A prompt that starts or is
+Escape cancel (except Escape from autocomplete selection, which returns to editing);
+`runMain` reports cancellation and exits with status 130. A prompt that starts or is
 waiting after the invocation's `signal` aborts fails with `aborted` and the signal's reason as its
 `cause`. Only one prompt may be active in an invocation. Input listeners and raw terminal mode are
 restored after every outcome.
@@ -606,14 +653,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 +669,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 +734,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 +761,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 +898,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`.
@@ -810,6 +920,17 @@ await showUsage(main, {
 | `vp run ready`         | Run check, test, and build                            |
 | `pnpm test:packed`     | Test the tarball with Node 22.18, host Node, and Deno |
 
+The autocomplete API has PTY tests in `src/autocomplete-pty.test.ts`.
+Run them with `pnpm test run src/autocomplete-pty.test.ts`. They launch
+`src/fixtures/autocomplete-pty-cli.ts`, a CLI using the public `prompt.autocomplete`
+API, and interpret its output with a headless terminal, checking visible choices,
+placeholder transitions, cursor coordinates, and submission/cancellation cleanup.
+For manual terminal verification, run `node src/fixtures/autocomplete-pty-cli.ts`.
+Expected screens use indented multiline strings; ANSI handling stays in
+`src/test-support/terminal.ts`. OS IME composition windows are outside this suite.
+The development-only `node-pty` dependency requires Python and a C/C++ build
+toolchain (Xcode Command Line Tools on macOS).
+
 The packed-consumer test must execute its Node consumer with exactly Node 22.18.0. Run pnpm itself
 under that version, or supply an absolute executable path explicitly:
 

package/dist/{command-B-Ok_6KW.d.ts → command-Czf4qXhe.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);
 }
@@ -87,7 +91,7 @@ declare class HackshValidationError extends HackshUsageError {
   readonly issues: ReadonlyArray<HackshIssue>;
   constructor(command: AnyCommandDef, issues: ReadonlyArray<HackshIssue>);
 }
-type PromptKind = "select" | "confirm" | "text";
+type PromptKind = "select" | "autocomplete" | "confirm" | "text";
 type HackshPromptErrorReason = "non-interactive" | "cancelled" | "aborted" | "eof" | "overlapping" | "invalid-options" | "input-error" | "printer-error";
 interface PromptErrorDetails {
   kind: PromptKind;
@@ -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);
 }
@@ -273,7 +277,15 @@ interface TextPromptState extends PromptStateBase {
   value: string;
   placeholder?: string;
 }
-type PromptState = SelectPromptState | ConfirmPromptState | TextPromptState;
+interface AutocompletePromptState extends PromptStateBase {
+  kind: "autocomplete";
+  query: string;
+  placeholder?: string;
+  phase: "input" | "select";
+  choices: readonly PromptChoiceState[];
+  value?: string;
+}
+type PromptState = SelectPromptState | ConfirmPromptState | TextPromptState | AutocompletePromptState;
 interface PromptPrintEvent {
   type: "prompt";
   prompt: PromptState;
@@ -348,10 +360,16 @@ interface SelectOption<T extends string> {
   label?: string;
   hint?: string;
 }
-interface SelectOptions<T extends string> {
+interface ChoiceOptions<TItem extends SelectOption<string>> {
   message: string;
-  options: readonly SelectOption<T>[];
-  initialValue?: T;
+  options: readonly TItem[];
+  sortBy?: (item: NoInfer<TItem>) => string | number;
+}
+interface SelectOptions<TItem extends SelectOption<string>> extends ChoiceOptions<TItem> {
+  initialValue?: NoInfer<TItem["value"]>;
+}
+interface AutocompleteOptions<TItem extends SelectOption<string>> extends ChoiceOptions<TItem> {
+  placeholder?: string;
 }
 interface ConfirmOptions {
   message: string;
@@ -363,7 +381,8 @@ interface TextOptions {
   validate?(value: string): string | undefined;
 }
 interface Prompter {
-  select<const T extends string>(options: SelectOptions<T>): Promise<T>;
+  select<const TItem extends SelectOption<string>>(options: SelectOptions<TItem>): Promise<TItem["value"]>;
+  autocomplete<const TItem extends SelectOption<string>>(options: AutocompleteOptions<TItem>): Promise<TItem["value"]>;
   confirm(options: ConfirmOptions): Promise<boolean>;
   text(options: TextOptions): Promise<string>;
 }
@@ -410,7 +429,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 { Logger as $, PromptStatus as A, resolveOutputMode as B, OutputWriter as C, PromptChoiceState as D, Printer as E, TerminalOutput as F, UsageSummary as G, UsageArgumentSummary as H, TextPromptState as I, summarizeUsage as J, renderUsage as K, UsagePrintEvent as L, SelectPromptState as M, StreamColors as N, PromptPrintEvent as O, TerminalInput as P, LogRecord as Q, VersionPrintEvent as R, OutputPrintEvent as S, PrintStream as T, UsageCommandSummary as U, ShowUsageOptions as V, UsageOptionSummary as W, LogLevel as X, LogKind as Y, LogProperties as Z, JsonPrinterOptions as _, ExecOptions as _t, ArgsSchema as a, HackshIssue as at, OutputMode as b, ExecSkipped as bt, Prompter as c, HackshUsageError as ct, TextOptions as d, PromptKind as dt, HackshError as et, Output as f, ValidationIssueSummary as ft, ExecPrintEvent as g, ExecFailureReason as gt, ErrorPrintEvent as h, ExecFailure as ht, defineCommand as i, HackshExitError as it, ResolveOutputModeOptions as j, PromptState as k, SelectOption as l, HackshValidationError as lt, ConfirmPromptState as m, ExecCommand as mt, CommandContext as n, HackshErrorSummary as nt, AutocompleteOptions as o, HackshPromptError as ot, AutocompletePromptState as p, Exec as pt, showUsage as q, CommandDef as r, HackshExecError as rt, ConfirmOptions as s, HackshPromptErrorReason as st, AnyCommandDef as t, HackshErrorKind as tt, SelectOptions as u, PromptErrorDetails as ut, LogPrintEvent as v, ExecResult as vt, PrintEvent as w, OutputPreference as x, ExecSuccess as xt, OutputFormat as y, ExecReturn as yt, createJsonPrinter as z };
+//# sourceMappingURL=command-Czf4qXhe.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 { $ as Logger, E as Printer, F as TerminalOutput, J as summarizeUsage, K as renderUsage, P as TerminalInput, V as ShowUsageOptions, _t as ExecOptions, a as ArgsSchema, at as HackshIssue, bt as ExecSkipped, c as Prompter, ct as HackshUsageError, d as TextOptions, dt as PromptKind, et as HackshError, f as Output, gt as ExecFailureReason, ht as ExecFailure, i as defineCommand, it as HackshExitError, l as SelectOption, lt as HackshValidationError, mt as ExecCommand, n as CommandContext, o as AutocompleteOptions, ot as HackshPromptError, pt as Exec, q as showUsage, r as CommandDef, rt as HackshExecError, s as ConfirmOptions, st as HackshPromptErrorReason, t as AnyCommandDef, u as SelectOptions, ut as PromptErrorDetails, vt as ExecResult, x as OutputPreference, xt as ExecSuccess, yt as ExecReturn } from "./command-Czf4qXhe.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 AutocompleteOptions, 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