hacksh 0.15.0 → 0.17.0

package/README.md

@@ -2,17 +2,33 @@
 
 Define a type-safe command-line interface with a Zod 4 object schema. The same schema parses and
 validates arguments, infers the value passed to `run`, and generates help. Run external commands
-with the context’s `exec`, use its `logger` for progress, and request interactive input with `prompt`.
-
-The name comes from 拍手 (_hakushu_), the Japanese word for "clap", as a nod to
-[clap](https://github.com/clap-rs/clap), the command-line argument parser for Rust. It is spelled
-with _hack_ and _sh_, as in shell.
-
-hacksh draws heavily on [Citty](https://github.com/unjs/citty) for its command API design and
-[Clack](https://github.com/bombshell-dev/clack) for its interactive prompts and terminal output.
-Many thanks to both projects and their contributors. hacksh uses Zod schemas for argument validation
-and type inference, including tuples for positional arguments; it does not guarantee API or behavior
-compatibility with Citty or Clack.
+with the context’s `exec`, write results with `output`, use its `logger` for progress, and request
+interactive input with `prompt`.
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Arguments](#arguments)
+  - [Options and flags](#options-and-flags)
+  - [Positional arguments](#positional-arguments)
+  - [Argument metadata](#argument-metadata)
+  - [Environment variables](#environment-variables)
+  - [Unknown arguments and forwarding](#unknown-arguments-and-forwarding)
+- [Subcommands](#subcommands)
+- [The run context](#the-run-context)
+  - [External commands](#external-commands)
+  - [Command output](#command-output)
+  - [Structured logging](#structured-logging)
+  - [Interactive input](#interactive-input)
+  - [Cancellation and exit status](#cancellation-and-exit-status)
+- [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)
+- [Development](#development)
+- [Name and acknowledgments](#name-and-acknowledgments)
 
 ## Install
 
@@ -24,7 +40,7 @@ hacksh is an ESM package and supports Node.js 22.18 or newer. Zod is a peer depe
 application controls the Zod 4 version it uses. The public schema types and schema inspection use
 the shared `zod/v4/core` API and accept schemas created with either `zod` or `zod/mini`.
 
-## Define and run a command
+## Quick start
 
 ```ts
 import { z } from "zod";
@@ -40,14 +56,14 @@ const main = defineCommand({
     ]),
     repo: z.string().optional().meta({ description: "Repository directory", alias: "C" }),
   }),
-  async run({ args, exec }) {
+  async run({ args, exec, output }) {
     const [ref] = args.positionals;
     const { stdout } = await exec(
       "git",
       ["show", "--no-patch", "--format=%h %s", "--end-of-options", ref],
       { cwd: args.repo },
     );
-    console.log(stdout);
+    output.println(stdout);
   },
 });
 
@@ -61,20 +77,15 @@ git-summary --help
 git-summary --version
 ```
 
-Use an `async run` handler and its `exec` for external commands. It captures output, removes one
-final newline, throws on failure, and observes invocation cancellation. Pass arguments as an array;
-there is no command string to quote or split. You do not need a `node:child_process` import or a
-custom process wrapper for these behaviors. See [External commands](#external-commands) for expected
-nonzero exits, stdin, and terminal access.
+`args` is inferred from the Zod schema, and `exec` runs external commands with an argument array,
+captures output with one final newline removed, throws on failure, and observes invocation
+cancellation. See [Arguments](#arguments) for option and positional rules,
+[The run context](#the-run-context) for `exec`, `output`, `logger`, `prompt`, and `signal`, and
+[Output formats](#output-formats) for how results and logs are split between stdout and stderr.
 
-`console.log` above writes the command’s data to stdout. Direct stdout writes are not converted
-to JSON by hacksh’s output mode. Logger events go through the printer; their stream depends on
-the level, so informational logs also share stdout by default.
+## Arguments
 
-`--version` is a root-only builtin. It prints the root command's `version`. When the root has
-none, `runMain` resolves the executable (`process.argv[1]`) through symlinks and prints the
-`version` of the nearest ancestor `package.json` that declares one, so a published CLI reports its
-package version without repeating it in code. `runCommand` does not search the filesystem.
+### Options and flags
 
 Boolean fields are flags and other fields take a value. Both a schema key and its kebab-case form
 are accepted (`--dryRun` and `--dry-run`). Every boolean flag also accepts a `--no-` prefixed form
@@ -84,7 +95,25 @@ Boolean flags also accept the explicit forms `--verbose=true` and
 `--no-verbose=false`) are validation errors. Value options accept `--repo ./my-repo` and
 `--repo=./my-repo`; values such as `false` remain strings for non-boolean fields.
 
-## Positional arguments
+Boolean flags are shown in help as `--[no-]name` because they also accept the `--no-` form. The
+`negatable` field of `UsageOptionSummary` carries the same information for machine-readable
+help, where `flags` keeps the literal `--name` spelling.
+
+`--help` and `--version` are built in:
+
+- `--version` is a root-only builtin. It prints the root command's `version`. When the root has
+  none, `runMain` resolves the executable (`process.argv[1]`) through symlinks and prints the
+  `version` of the nearest ancestor `package.json` that declares one, so a published CLI reports its
+  package version without repeating it in code. `runCommand` does not search the filesystem.
+- Without an alias of the same letter, `-h` and `-v` are shorthands for `--help` and `--version`.
+  Defining an `h` or `v` alias on an option replaces the shorthand while keeping `--help` and
+  `--version` available.
+- Both `help` and `version` option names are reserved and throw a `TypeError` from `defineCommand`
+  on every command.
+- Output selection does not reserve any additional command-line flags, so names such as `--json`,
+  `--output`, and `--log-format` remain available to application schemas.
+
+### Positional arguments
 
 Declare positional arguments as a `z.tuple` in the `positionals` field. Tuple items are assigned in order,
 and the tuple rest collects all remaining values. Optional or defaulted items must come after
@@ -101,6 +130,7 @@ const copy = defineCommand({
   }),
   run({ args }) {
     const [destination, ...files] = args.positionals; // [string, ...string[]]
+    return { destination, files };
   },
 });
 ```
@@ -114,58 +144,7 @@ Help and validation errors label each item with its `.meta({ title })`, such as
 labeled `ARGS`. Use `z.array` instead of a tuple to accept only variadic values. Without a rest,
 additional positional arguments are rejected by default, as are unknown options.
 
-### Unknown arguments and forwarding
-
-A command rejects unknown options and excess positional arguments before its `run` handler or
-schema transforms execute. For ordinary commands, declare the accepted arguments in `args`;
-there is no need to inspect `input.unknown` manually. Errors are `HackshValidationError` instances,
-with each rejected token in `issues[].arg`.
-
-Everything after `--` is always collected unchanged in `input.passthrough`, independently of this policy.
-Use that explicit boundary when forwarding arguments to another executable:
-
-```ts
-const forward = defineCommand({
-  name: "git-forward",
-  async run({ exec, input }) {
-    const { stdout } = await exec("git", input.passthrough);
-    console.log(stdout);
-  },
-});
-// git-forward -- status --short
-```
-
-For a wrapper that also accepts undeclared arguments before `--`, set `allowUnknownArgs: true`:
-
-```ts
-const wrapper = defineCommand({
-  allowUnknownArgs: true,
-  async run({ input, exec }) {
-    await exec("some-tool", [...input.unknown, ...input.passthrough]);
-  },
-});
-```
-
-`input.unknown` preserves the order of unknown option tokens and excess positional values. Unknown
-options do not consume a following value: if the schema has an unfilled positional slot, that
-value fills it. Known options are still parsed and validated. Use `--` when a child's arguments
-must not be interpreted by this command. A handler that does not use `input.passthrough` ignores those
-arguments; commands that require rejecting them can check `input.passthrough.length` explicitly.
-
-`allowUnknownArgs` defaults to `false`, inherits down the selected subcommand route, and can be
-overridden by each child. A child's setting does not change validation of its parent's arguments.
-Definitions are not mutated, so reusing a child under another root does not retain inherited settings.
-Standalone `parseArgs` uses the supplied command's setting and does not resolve a parent route.
-
-Once routing succeeds, help and root version output take precedence over argument validation,
-including unknown arguments. Routing errors such as an unknown subcommand still fail. A child's
-undeclared `--version` is an unknown argument, since the version builtin belongs to the root.
-
-**Migrating from 0.11.0:** unknown input was previously accepted by default. Add
-`allowUnknownArgs: true` to commands that intentionally use `input.unknown`, or to their shared parent.
-No migration is needed for `--` forwarding.
-
-## Argument metadata
+### Argument metadata
 
 Use Zod 4 `.meta({ alias, valueName, env, title, description })` on each argument schema.
 Importing hacksh types `alias`, `env`, and `valueName` on Zod's global metadata; any other key stays
@@ -213,7 +192,8 @@ OPTIONS
   -v, -V, --[no-]verbose  Show details (Default: false)
 ```
 
-- `alias` gives a named option one or more single-character short forms.
+- `alias` gives a named option one or more single-character short forms. Defining `v` above replaces
+  the default `-v` version shorthand, so `convert -v` sets `verbose`.
 - `valueName` sets the value label of a named option.
 - `env` overrides an option's automatic environment variable name, or disables it with `false`.
 - `title` labels a positional argument; `description` supplies its help text.
@@ -222,19 +202,9 @@ Place metadata on the outer schema to override metadata inherited through wrappe
 `.describe(text)` remains equivalent to description metadata; new code should use `.meta({ description: text })`.
 With `zod/mini`, use `.check(mini.meta({ ... }))`.
 
-Boolean flags are shown as `--[no-]name` because they also accept the `--no-` form. The
-`negatable` field of `UsageOptionSummary` carries the same information for machine-readable
-help, where `flags` keeps the literal `--name` spelling.
-
 `defineCommand` validates metadata types and throws a `TypeError` for empty or multi-character
 aliases, duplicate aliases, and option-only metadata (`alias`, `env`, `valueName`) on positional
-schemas. Without an alias of the same letter, `-h` and `-v` are shorthands
-for `--help` and `--version`. Defining an `h` or `v` alias replaces the shorthand, so `convert -v`
-above sets `verbose`; `--help` and `--version` remain available. Both `help` and `version` option
-names are reserved and throw a `TypeError` from `defineCommand` on every command.
-Output selection does not reserve
-any additional command-line flags, so names such as `--json`, `--output`, and `--log-format` remain
-available to application schemas.
+schemas.
 
 ### Environment variables
 
@@ -272,6 +242,53 @@ MY_CLI_DEPLOY_TARGET=prod MY_CLI_DEPLOY_DRY_RUN=true GITHUB_TOKEN=t my-cli deplo
 - Two options that resolve to the same name on one route, such as a root `deployTarget` and a
   `deploy` subcommand's `target`, make the invocation throw a `TypeError`.
 
+### Unknown arguments and forwarding
+
+A command rejects unknown options and excess positional arguments before its `run` handler or
+schema transforms execute. For ordinary commands, declare the accepted arguments in `args`;
+there is no need to inspect `input.unknown` manually. Errors are `HackshValidationError` instances,
+with each rejected token in `issues[].arg`.
+
+Everything after `--` is always collected unchanged in `input.passthrough`, independently of this policy.
+Use that explicit boundary when forwarding arguments to another executable:
+
+```ts
+const forward = defineCommand({
+  name: "git-forward",
+  async run({ exec, input, output }) {
+    const { stdout } = await exec("git", input.passthrough);
+    output.println(stdout);
+  },
+});
+// git-forward -- status --short
+```
+
+For a wrapper that also accepts undeclared arguments before `--`, set `allowUnknownArgs: true`:
+
+```ts
+const wrapper = defineCommand({
+  allowUnknownArgs: true,
+  async run({ input, exec }) {
+    await exec("some-tool", [...input.unknown, ...input.passthrough]);
+  },
+});
+```
+
+`input.unknown` preserves the order of unknown option tokens and excess positional values. Unknown
+options do not consume a following value: if the schema has an unfilled positional slot, that
+value fills it. Known options are still parsed and validated. Use `--` when a child's arguments
+must not be interpreted by this command. A handler that does not use `input.passthrough` ignores those
+arguments; commands that require rejecting them can check `input.passthrough.length` explicitly.
+
+`allowUnknownArgs` defaults to `false`, inherits down the selected subcommand route, and can be
+overridden by each child. A child's setting does not change validation of its parent's arguments.
+Definitions are not mutated, so reusing a child under another root does not retain inherited settings.
+Standalone `parseArgs` uses the supplied command's setting and does not resolve a parent route.
+
+Once routing succeeds, help and root version output take precedence over argument validation,
+including unknown arguments. Routing errors such as an unknown subcommand still fail. A child's
+undeclared `--version` is an unknown argument, since the version builtin belongs to the root.
+
 ## Subcommands
 
 ```ts
@@ -305,107 +322,34 @@ listing, including usage shown for an unknown command. Hidden commands remain av
 their own `--help` output remains available. If every subcommand is hidden, help keeps the generic
 `<COMMAND>` syntax but omits the empty `COMMANDS` section.
 
-## Structured logging
-
-Every `run` context has a `logger`. Its `trace`, `debug`, `info`, `warn`, `error`, and `fatal`
-methods emit structured records through the invocation's printer. `step` and `success` are
-info-level records with a distinct semantic kind for presentation. Placeholders in braces use the
-record's properties. Every level is emitted and displayed by the default printer; there is no
-built-in severity threshold or verbose flag.
-
-```ts
-const deploy = defineCommand({
-  name: "deploy",
-  async run({ logger }) {
-    const log = logger.with({ app: "web", env: "prod" });
-    log.step("Deploying {app} to {env}");
-    log.getChild("upload").debug("Uploaded {files} files", { files: 12 });
-    log.success("Deployed {app}");
-  },
-});
-```
-
-Properties passed to an individual call override properties bound by `with`. `getChild` appends a
-category segment; hacksh automatically starts the category with the named root and each resolved
-subcommand. Missing placeholders, and placeholders whose values cannot be converted to text,
-remain unchanged without discarding their properties. Passing an `Error` to `error` or `fatal`
-uses its message and adds a canonical, schema-free error summary as `properties.error`. Error
-values nested in other log properties are summarized the same way before custom printers receive
-the event.
-
-Each `log` print event contains a `record` with `level`, `kind`, `category`, interpolated `message`,
-template `rawMessage`, merged `properties`, and a numeric `timestamp`. Logger calls do not need to
-be awaited: they use the invocation's serialized output queue, which is drained before execution
-finishes. A printer failure rejects the invocation without changing a successful `run` value.
-
-## Interactive input
-
-Every `run` context has a `prompt` with `select`, `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.
-
-```ts
-const deploy = defineCommand({
-  name: "deploy",
-  async run({ logger, prompt }) {
-    const environment = await prompt.select({
-      message: "Environment",
-      options: [
-        { value: "staging", hint: "safe default" },
-        { value: "production", label: "Production" },
-      ] as const,
-      initialValue: "staging",
-    }); // "staging" | "production"
-    const confirmed = await prompt.confirm({ message: `Deploy to ${environment}?` });
-    if (!confirmed) return;
-    const release = await prompt.text({
-      message: "Release name",
-      placeholder: "v1.2.3",
-      validate: (value) => (value.length === 0 ? "A release name is required" : undefined),
-    });
-    logger.success("Deploying {release}", { release });
-  },
-});
-```
+## The run context
 
-Select values retain their literal union type. Arrow keys change the selected choice, Enter accepts
-it, and `initialValue` controls the initial selection. Confirm accepts `y`, `n`, or Enter; Enter
-uses `initialValue` when supplied and otherwise means no. Text displays its placeholder without
-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.
+Every `run` handler receives a `CommandContext` with:
 
-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`,
-`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
-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.
-Failed prompts emit a non-visible `closed` prompt state through the same printer before rejecting,
-so callers that catch cancellation, EOF, input, or printer errors do not leave stale terminal UI.
+- `args` — validated output inferred from the command's `args` schema.
+- `input` — the raw selected command segment (`argv`), accepted unknown tokens (`unknown`), and
+  tokens after `--` (`passthrough`). For a routed child, `input.argv` excludes parent options and
+  subcommand names.
+- `command` — the resolved command definition. An unnamed subcommand is represented by a completed
+  copy whose `name` is its key; the original definition is not mutated.
+- `exec` — runs external commands under the invocation's environment, printer, and cancellation.
+- `output` — writes the command's results to stdout through the invocation's printer.
+- `logger` — emits structured log records to stderr through the invocation's printer.
+- `prompt` — requests interactive `select`, `confirm`, or `text` input.
+- `signal` — an `AbortSignal` for the invocation.
 
-Active pretty prompts redraw in place rather than appending a block for every key. A completed
-prompt collapses to one result line. If a logger event arrives while a prompt is active, the
-printer removes the prompt, renders the event, and then redraws the current prompt state.
-Physical rows are calculated from explicit newlines, ANSI-free Unicode display width, and
-`stdout.columns`, including terminal wrapping. When a custom output writer does not expose a
-positive `columns` value, the renderer conservatively counts explicit lines only.
-
-## External commands
+### External commands
 
 Every `run` context has an `exec` function that starts an executable with an argument array. It
 never uses a shell, so spaces, quotes, `$`, `;`, `|`, and `*` in arguments reach the child
 unchanged. By default it resolves with the captured output and rejects with `HackshExecError`
 when the command fails. Pass `reject: false` to receive failures as results instead. Prefer this
-context API to `spawnSync` or a custom subprocess wrapper inside a command handler so execution
-uses the invocation’s environment, cancellation, and printer.
+context API to `node:child_process`, `spawnSync`, or a custom subprocess wrapper inside a command
+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 }) {
@@ -419,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 });
   },
@@ -434,7 +378,7 @@ UTF-8 `stdout` and `stderr` with one final newline removed. A failure's `reason`
 gives `ExecSuccess`, while `false` or a `boolean` variable gives `ExecResult`, which must be
 narrowed before reading `exitCode`.
 
-### Working with captured output
+#### Working with captured output
 
 Use `stdout` directly for a single value such as a commit ID or repository path. Do not call
 `.trim()` on paths: surrounding whitespace can be part of the name. `exec` already removes one
@@ -446,7 +390,7 @@ that format and parse it with `JSON.parse` (and a Zod schema when validation is
 helper. Splitting that format on newlines would break paths containing newlines. hacksh does not
 parse Git records or infer whether stdout is text, JSON, or a list.
 
-### Execution options
+#### Execution options
 
 Options are `cwd`, `env`, `input`, `reject`, `timeout` (milliseconds), `signal` (an
 `AbortSignal`), `maxBuffer` (bytes per stream, default 100,000,000), `forceKillAfterDelay`
@@ -517,36 +461,200 @@ reads the whole environment to start a process.
 To test a command without starting processes, call its `run` with a context whose `exec` is your own
 function of type `Exec`.
 
+### Command output
+
+Every `run` context has an `output` for the data the command produces, kept apart from progress
+and diagnostics on `logger`. `print(text)` writes text exactly as given, `println(text)` adds a
+newline, and `json(value)` writes a JSON value.
+
+```ts
+const report = defineCommand({
+  name: "report",
+  async run({ logger, output }) {
+    logger.step("Collecting commits");
+    output.print(renderTable(rows)); // already ends with a newline
+    output.println(`${rows.length} rows`);
+    output.json({ rows });
+  },
+});
+```
+
+In pretty output, text goes to stdout unchanged and `json` values are indented with two spaces.
+In JSON output, each call writes one line on stdout: `{"type":"output","kind":"text","text":...}`
+holding the exact text, including the newline `println` adds, or
+`{"type":"output","kind":"json","data":...}`. Concatenating the `text` values reproduces the
+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.
+`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`.
+
+### Structured logging
+
+Every `run` context has a `logger`. Its `trace`, `debug`, `info`, `warn`, `error`, and `fatal`
+methods emit structured records through the invocation's printer. `step` and `success` are
+info-level records with a distinct semantic kind for presentation. Placeholders in braces use the
+record's properties. Every level is emitted and displayed by the default printer; there is no
+built-in severity threshold or verbose flag.
+
+```ts
+const deploy = defineCommand({
+  name: "deploy",
+  async run({ logger }) {
+    const log = logger.with({ app: "web", env: "prod" });
+    log.step("Deploying {app} to {env}");
+    log.getChild("upload").debug("Uploaded {files} files", { files: 12 });
+    log.success("Deployed {app}");
+  },
+});
+```
+
+Properties passed to an individual call override properties bound by `with`. `getChild` appends a
+category segment; hacksh automatically starts the category with the named root and each resolved
+subcommand. Missing placeholders, and placeholders whose values cannot be converted to text,
+remain unchanged without discarding their properties. Passing an `Error` to `error` or `fatal`
+uses its message and adds a canonical, schema-free error summary as `properties.error`. Error
+values nested in other log properties are summarized the same way before custom printers receive
+the event.
+
+Each `log` print event contains a `record` with `level`, `kind`, `category`, interpolated `message`,
+template `rawMessage`, merged `properties`, and a numeric `timestamp`. Logger calls do not need to
+be awaited: they use the invocation's serialized output queue, which is drained before execution
+finishes. A printer failure rejects the invocation without changing a successful `run` value.
+
+### Interactive input
+
+Every `run` context has a `prompt` with `select`, `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.
+
+```ts
+const deploy = defineCommand({
+  name: "deploy",
+  async run({ logger, prompt }) {
+    const environment = await prompt.select({
+      message: "Environment",
+      options: [
+        { value: "staging", hint: "safe default" },
+        { value: "production", label: "Production" },
+      ] as const,
+      initialValue: "staging",
+    }); // "staging" | "production"
+    const confirmed = await prompt.confirm({ message: `Deploy to ${environment}?` });
+    if (!confirmed) return;
+    const release = await prompt.text({
+      message: "Release name",
+      placeholder: "v1.2.3",
+      validate: (value) => (value.length === 0 ? "A release name is required" : undefined),
+    });
+    logger.success("Deploying {release}", { release });
+  },
+});
+```
+
+Select values retain their literal union type. Arrow keys change the selected choice, Enter accepts
+it, and `initialValue` controls the initial selection. Confirm accepts `y`, `n`, or Enter; Enter
+uses `initialValue` when supplied and otherwise means no. Text displays its placeholder without
+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.
+
+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`,
+`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
+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.
+Failed prompts emit a non-visible `closed` prompt state through the same printer before rejecting,
+so callers that catch cancellation, EOF, input, or printer errors do not leave stale terminal UI.
+
+Active pretty prompts redraw in place rather than appending a block for every key. A completed
+prompt collapses to one result line. If a logger or output event arrives while a prompt is active, the
+printer removes the prompt, renders the event, and then redraws the current prompt state.
+Physical rows are calculated from explicit newlines, ANSI-free Unicode display width, and
+`stdout.columns`, including terminal wrapping. When a custom output writer does not expose a
+positive `columns` value, the renderer conservatively counts explicit lines only.
+
+### Cancellation and exit status
+
+Every `run` context has a `signal`, an `AbortSignal` for that invocation. `exec` calls and prompts
+already follow it; pass it to `fetch` and other APIs that accept one. Cancellation is cooperative:
+hacksh does not stop code that ignores the signal.
+
+```ts
+import { defineCommand, HackshExitError, runCommand } from "hacksh";
+
+const check = defineCommand({
+  name: "check",
+  async run({ signal }) {
+    const response = await fetch("https://example.com/health", { signal });
+    if (!response.ok) throw new HackshExitError(2, `Health check returned ${response.status}`);
+  },
+});
+
+const controller = new AbortController();
+await runCommand(check, [], { signal: controller.signal });
+```
+
+`runCommand` accepts a `signal` option and never listens for process signals or exits. If that
+signal is already aborted, `runCommand` rejects with its reason without calling `run`; aborting it
+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. 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 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
 
 `runMain` and `runCommand` resolve one output mode before command routing, parsing, or execution.
 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" });
 // HACKSH_OUTPUT=json my-cli --help overrides the configured preference.
 ```
 
+stdout carries the command's results: `output` events, help, and version. Every log level, errors,
+and `exec` events go to stderr, so a pipe such as `my-cli | jq` receives only results while logs
+remain visible on the terminal. Direct writes such as `console.log` bypass the printer and are not
+converted to JSON.
+
 The resolved `OutputMode` has `format`, `interactive`, and `color` fields. Interaction is enabled
-only for pretty output outside CI when both stdin and stdout are TTYs. Color is enabled only for
-pretty output to a stdout TTY when `NO_COLOR` is empty or absent. These decisions are independent: an
-explicit pretty format in CI can use color, but remains noninteractive. `env`, `stdin`, `stdout`,
+only for pretty output outside CI when both stdin and stdout are TTYs. `color` has a `stdout` and a
+`stderr` flag; each is enabled only for pretty output when that stream is a TTY and `NO_COLOR` is
+empty or absent, so logs stay colored on the terminal when stdout is redirected. These decisions
+are independent: an explicit pretty format in CI can use color, but remains noninteractive. `env`,
+`stdin`, `stdout`,
 and `stderr` can be supplied in execution options for embedded or tested invocations.
 Custom `stdin` values implement the readable-stream operations `on`, `removeListener`, `resume`,
 and `pause`; `isTTY`, `isRaw`, `readableFlowing`, and `setRawMode` describe optional terminal
 capabilities. A stream without those readable operations fails with an `input-error` if prompting
 is attempted.
 
-JSON output contains exactly one `PrintEvent` object per line. Help and version events and
-trace/debug/info logs go to stdout; errors, warning/error/fatal logs, and `exec` events go to
-stderr. Usage attached
-to an error retains its `stderr` stream. Every log level is emitted by default. JSON strings have
+JSON output contains exactly one `PrintEvent` object per line, on the streams described above.
+Usage attached to an error retains its `stderr` stream. Every log level is emitted by default. JSON strings have
 terminal control sequences removed, and the printer never serializes executable command or Zod
 schema objects.
 
@@ -575,16 +683,117 @@ block. All six log levels are displayed by default.
 ```
 
 Pretty output uses Unicode symbols by default. Set `unicode: false` on `runMain` or `runCommand` for
-ASCII marks and bars. Color is still resolved from the selected output mode: it requires pretty
-output and a stdout TTY, and any non-empty `NO_COLOR` disables it. Unicode selection does not affect
+ASCII marks and bars. Color is still resolved from the selected output mode: each event is colored
+only when its stream is a TTY, and any non-empty `NO_COLOR` disables it. Unicode selection does not affect
 JSON output. An invocation does not add automatic start or end messages; the renderer presents only
 the semantic events that the command emits.
 
-## Programmatic execution and errors
+## Programmatic API and errors
+
+### Entry points
+
+`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:
+
+```ts
+import { runMain } from "hacksh";
+
+const mainEntry = (argv: string[] = ["--verbose"]) => runMain(main, { argv });
+await mainEntry(); // uses the local default
+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 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.message}`);
+  },
+});
+```
+
+### Composable run functions
 
-`runCommand(command, argv, options)` handles help and version output without exiting, throws errors
-to its caller, and returns the selected `run` handler's result. Pass a `printer` in `options` to
-receive all output produced by that invocation as structured events:
+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,
+output-mode helpers, `Printer`, `PrintEvent`, and renderer-facing event and summary types from
+`hacksh/printer`. A custom printer can narrow `PrintEvent` on `event.type` without importing
+each individual event type.
+
+Pass a `printer` in `options` to receive all output produced by an invocation as structured events:
 
 ```ts
 import { runCommand } from "hacksh";
@@ -601,27 +810,24 @@ await runCommand(main, ["--help"], { printer });
 // events[0] is { type: "usage", usage, text, stream: "stdout" }
 ```
 
-The current events are `usage`, `version`, `error`, `log`, `prompt`, and `exec`. Usage events include the resolved
+The current events are `usage`, `version`, `error`, `log`, `prompt`, `output`, and `exec`. Usage events include the resolved
 command's schema-free name, version, description, synopsis, arguments, options, and visible child
 commands, plus rendered text and the intended `stdout` or `stderr` stream. Version events include
 the version string. Error events contain a schema-free summary with an explicit `kind`, structured
 validation issues, standard `Error` fields, custom enumerable properties, and recursively
 canonical causes; log events contain the structured record described above. Prompt events contain
-the prompt kind, status, current value or choices, placeholder, and validation message. Printer calls are serialized, may be asynchronous, and are
+the prompt kind, status, current value or choices, placeholder, and validation message. Output
+events carry `kind: "text"` with `text` or `kind: "json"` with `data`. Printer calls are serialized, may be asynchronous, and are
 drained before `runCommand` or `runMain` completes or exits. A printer rejection rejects
 `runCommand`.
 
-The root `hacksh` entry exposes command-definition and execution APIs. Import printer factories,
-output-mode helpers, `Printer`, `PrintEvent`, and renderer-facing event and summary types from
-`hacksh/printer`. A custom printer can narrow `PrintEvent` on `event.type` without importing
-each individual event type.
-
 Use `createPrettyPrinter({ color, unicode, stdout, stderr })` to reuse the built-in human-readable
-renderer with custom writable targets, or `createJsonPrinter({ stdout, stderr })` to reuse the
+renderer with custom writable targets; `color` is one boolean or a `{ stdout, stderr }` pair, or `createJsonPrinter({ stdout, stderr })` to reuse the
 built-in JSON-lines behavior. The pretty renderer has no public theme API; replacing the fixed
-presentation requires a custom `Printer`. `summarizeUsage(command)` returns the same canonical help
-metadata carried by a usage event. `resolveOutputMode(...)` exposes the selection contract for
-wrappers and presentation or prompting layers.
+presentation requires a custom `Printer`. `resolveOutputMode(...)` exposes the selection contract
+for wrappers and presentation or prompting layers.
+
+### Standalone parsing and help
 
 For parsing and usage rendering without execution, use the composition APIs. `parseArgs`
 parses exactly the supplied command definition and argument segment, returns its schema output only,
@@ -630,7 +836,8 @@ refinements and transformations. It does not route subcommands, act on help or v
 bypass validation; callers that resolve commands themselves must pass the selected command and
 its segment. `renderUsage` returns a string synchronously with no output side effects. `showUsage`
 requires an explicit `printer`, sends the same text and structured help summary as a usage event,
-and awaits the printer. Its optional `stream` defaults to `"stdout"`.
+and awaits the printer. Its optional `stream` defaults to `"stdout"`. `summarizeUsage(command)`
+returns the same canonical help metadata carried by a usage event.
 
 ```ts
 import { parseArgs, renderUsage, showUsage } from "hacksh";
@@ -647,83 +854,18 @@ await showUsage(main, {
 });
 ```
 
-The `run` context includes `command`, the actual resolved command definition. An unnamed subcommand
-is represented by a completed copy whose `name` is its key; the original definition is not mutated.
-`args` contains validated schema output. `input` separates the original selected command segment
-(`argv`), accepted unknown tokens (`unknown`), and tokens after `--` (`passthrough`).
-For a routed child, `input.argv` excludes the parent options and subcommand names.
-
-`defineCommand` preserves the handler's return type. `runCommand` 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.
-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:
-
-```ts
-import { runMain } from "hacksh";
-
-const mainEntry = (argv: string[] = ["--verbose"]) => runMain(main, { argv });
-await mainEntry(); // uses the local default
-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:
-
-```ts
-await runMain(main, {
-  argv: ["--help"],
-  async onError(error) {
-    console.error(`gh-pr-commits: ${error instanceof Error ? error.message : String(error)}`);
-  },
-});
-```
-
-Usage failures are `HackshUsageError` instances. Argument failures are
-`HackshValidationError` instances whose `issues` identify CLI names such as `--repo` or `<PR>`.
-Prompt failures are `HackshPromptError` instances with structured `reason` and `prompt` fields.
-
-## Cancellation and exit status
-
-Every `run` context has a `signal`, an `AbortSignal` for that invocation. `exec` calls and prompts
-already follow it; pass it to `fetch` and other APIs that accept one. Cancellation is cooperative:
-hacksh does not stop code that ignores the signal.
+### Errors
 
-```ts
-import { defineCommand, HackshExitError, runCommand } from "hacksh";
-
-const check = defineCommand({
-  name: "check",
-  async run({ signal }) {
-    const response = await fetch("https://example.com/health", { signal });
-    if (!response.ok) throw new HackshExitError(2, `Health check returned ${response.status}`);
-  },
-});
-
-const controller = new AbortController();
-await runCommand(check, [], { signal: controller.signal });
-```
-
-`runCommand` accepts a `signal` option and never listens for process signals or exits. If that
-signal is already aborted, `runCommand` rejects with its reason without calling `run`; aborting it
-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.
-
-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.
+- `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`.
+- `HackshPromptError` — interactive prompt failures, with structured `reason` and `prompt` fields.
+- `HackshExecError` — external command failures when `reject` is not `false`, with the full failure
+  in `error.result`.
+- `HackshExitError` — thrown by a command handler to exit with a specific status code (`0`–`255`)
+  and optional message.
 
 ## Development
 
@@ -742,3 +884,15 @@ under that version, or supply an absolute executable path explicitly:
 ```sh
 HACKSH_MINIMUM_NODE=/absolute/path/to/node-v22.18.0 pnpm test:packed
 ```
+
+## Name and acknowledgments
+
+The name comes from 拍手 (_hakushu_), the Japanese word for "clap", as a nod to
+[clap](https://github.com/clap-rs/clap), the command-line argument parser for Rust. It is spelled
+with _hack_ and _sh_, as in shell.
+
+hacksh draws heavily on [Citty](https://github.com/unjs/citty) for its command API design and
+[Clack](https://github.com/bombshell-dev/clack) for its interactive prompts and terminal output.
+Many thanks to both projects and their contributors. hacksh uses Zod schemas for argument validation
+and type inference, including tuples for positional arguments; it does not guarantee API or behavior
+compatibility with Citty or Clack.