hacksh 0.10.0 → 0.12.0

package/README.md

@@ -1,7 +1,8 @@
 # hacksh
 
 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.
+validates arguments, infers the value passed to `run`, and generates help. Run external commands
+with the context’s `exec`, and use its `logger` for progress and interactive prompts.
 
 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
@@ -30,21 +31,22 @@ import { z } from "zod";
 import { defineCommand, runMain } from "hacksh";
 
 const main = defineCommand({
-  name: "gh-pr-commits",
+  name: "git-summary",
   version: "0.1.0",
-  description: "List commits in a GitHub pull request",
+  description: "Show a commit summary",
   args: z.object({
-    _: z.tuple([
-      z.coerce.number().int().optional().describe("Pull request number").meta({ title: "PR" }),
-    ]),
-    repo: z.string().optional().describe("Repository in OWNER/REPO format"),
-    verbose: z.boolean().default(false).describe("Show details"),
+    _: z.tuple([z.string().default("HEAD").describe("Commit to inspect").meta({ title: "REF" })]),
+    repo: z.string().optional().describe("Repository directory"),
   }),
-  argOptions: { repo: { alias: "R" }, verbose: { alias: ["v", "V"] } },
-  async run({ args, rawArgs, extraArgs, passthrough, logger }) {
-    // args is { _: [number?]; repo?: string; verbose: boolean }
-    logger.info("Loading commits for {repo}", { repo: args.repo ?? "the current repository" });
-    logger.debug("Invocation arguments", { rawArgs, extraArgs, passthrough });
+  argOptions: { repo: { alias: "C" } },
+  async run({ args, exec }) {
+    const [ref] = args._;
+    const { stdout } = await exec(
+      "git",
+      ["show", "--no-patch", "--format=%h %s", "--end-of-options", ref],
+      { cwd: args.repo },
+    );
+    console.log(stdout);
   },
 });
 
@@ -52,11 +54,22 @@ await runMain(main);
 ```
 
 ```sh
-gh-pr-commits 42 -R owner/repo --verbose
-gh-pr-commits --help
-gh-pr-commits --version
+git-summary
+git-summary HEAD~1 -C ./my-repo
+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.
+
+`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.
+
 `--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
@@ -67,8 +80,8 @@ are accepted (`--dryRun` and `--dry-run`). Every boolean flag also accepts a `--
 that sets it to `false`, such as `--no-verbose`, which is how a default-on flag is disabled.
 Boolean flags also accept the explicit forms `--verbose=true` and
 `--verbose=false`; other inline values and values on a negated flag (such as
-`--no-verbose=false`) are validation errors. Value options accept `--repo owner/repo` and
-`--repo=owner/repo`; values such as `false` remain strings for non-boolean fields.
+`--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
 
@@ -98,8 +111,58 @@ copy out a.txt b.txt   # { _: ["out", "a.txt", "b.txt"] }
 Help and validation errors label each item with its `.meta({ title })`, such as `<DESTINATION>` and
 `[FILES...]`. Untitled items are labeled by position (`ARG1`, `ARG2`, ...) and an untitled rest is
 labeled `ARGS`. Use `z.array` instead of a tuple to accept only variadic values. Without a rest,
-additional positional arguments are kept in `extraArgs`. Unknown options are also kept in
-`extraArgs`; arguments after `--` are kept in `passthrough`.
+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 `extraArgs` manually. Errors are `HackshValidationError` instances,
+with each rejected token in `issues[].arg`.
+
+Everything after `--` is always collected unchanged in `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, passthrough }) {
+    const { stdout } = await exec("git", 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({ extraArgs, passthrough, exec }) {
+    await exec("some-tool", [...extraArgs, ...passthrough]);
+  },
+});
+```
+
+`extraArgs` 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 `passthrough` ignores those
+arguments; commands that require rejecting them can check `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 `extraArgs`, or to their shared parent.
+No migration is needed for `--` forwarding.
 
 ## Argument options
 
@@ -304,10 +367,12 @@ 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`, `eof`,
-`overlapping`, `invalid-options`, `input-error`, and `printer-error`. Ctrl-C and Escape cancel;
-`runMain` reports cancellation and exits with status 130. Only one prompt may be active in an
-invocation. Input listeners and raw terminal mode are restored after every outcome.
+`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.
 
@@ -323,21 +388,27 @@ positive `columns` value, the renderer conservatively counts explicit lines only
 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.
+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.
 
 ```ts
-const sync = defineCommand({
-  name: "sync",
+const check = defineCommand({
+  name: "check-head",
   async run({ exec, logger }) {
-    const { stdout: branch } = await exec("git", ["branch", "--show-current"]);
-    const upstream = await exec("git", ["rev-parse", "--abbrev-ref", "@{upstream}"], {
+    const head = await exec("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], {
       reject: false,
     });
-    if (upstream.status === "failed") {
-      logger.warn("{branch} has no upstream", { branch });
-      return;
+    if (head.status === "failed") {
+      // Only this specific exit means that the revision was not found.
+      if (head.reason === "exit-code" && head.exitCode === 1) {
+        logger.warn("The repository has no HEAD commit");
+        return;
+      }
+      // Missing executables, cancellation, and other failures must still fail the command.
+      throw new Error("Could not inspect HEAD", { cause: head });
     }
-    await exec("git", ["pull", "--ff-only"], { cwd: "/path/to/repo", timeout: 60_000 });
+    logger.info("HEAD is {commit}", { commit: head.stdout });
   },
 });
 ```
@@ -350,9 +421,24 @@ 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
+
+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
+final LF or CRLF; it preserves other whitespace and NUL separators.
+
+Interpret structured output according to the child command’s format. If it offers JSON, request
+that format and parse it with `JSON.parse` (and a Zod schema when validation is needed). For Git’s
+`--porcelain -z` output, keep the NUL delimiters and parse the records in a named, application-specific
+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
+
 Options are `cwd`, `env`, `input`, `reject`, `timeout` (milliseconds), `signal` (an
 `AbortSignal`), `maxBuffer` (bytes per stream, default 100,000,000), and `forceKillAfterDelay`
-(milliseconds, default 5,000). `input` is written to stdin and closed; otherwise stdin is empty.
+(milliseconds, default 5,000). Every call also stops with `aborted` when the invocation's `signal`
+aborts. `input` is written to stdin and closed; otherwise stdin is empty.
 Output beyond `maxBuffer` is truncated to that many bytes. On timeout, abort, or output limit,
 hacksh sends `SIGTERM` to the child it started and `SIGKILL` after `forceKillAfterDelay`; it does
 not stop grandchildren, and it does not wait for them to close inherited pipes. Invalid arguments
@@ -571,7 +657,36 @@ 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.
 
-## Exit status
+## 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; 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

package/dist/index.d.ts

@@ -14,7 +14,7 @@ declare class HackshValidationError extends HackshUsageError {
   constructor(command: AnyCommandDef, issues: ReadonlyArray<HackshIssue>);
 }
 type PromptKind = "select" | "confirm" | "text";
-type HackshPromptErrorReason = "non-interactive" | "cancelled" | "eof" | "overlapping" | "invalid-options" | "input-error" | "printer-error";
+type HackshPromptErrorReason = "non-interactive" | "cancelled" | "aborted" | "eof" | "overlapping" | "invalid-options" | "input-error" | "printer-error";
 interface PromptErrorDetails {
   kind: PromptKind;
   message: string;
@@ -372,12 +372,15 @@ interface CommandContext<S extends ArgsSchema> {
   extraArgs: string[];
   logger: Logger;
   exec: Exec;
+  signal: AbortSignal;
 }
 interface CommandDef<S extends ArgsSchema = EmptyArgs> {
   name?: string;
   version?: string;
   description?: string;
   hidden?: boolean;
+  /** Keep unknown options and excess positionals in extraArgs. Inherits from the parent; defaults to false. */
+  allowUnknownArgs?: boolean;
   args?: S;
   argOptions?: ArgOptionsMap<S>;
   subCommands?: Record<string, CommandDef<ArgsSchema>>;
@@ -408,6 +411,7 @@ declare function createPrettyPrinter(options: PrettyPrinterOptions): Printer;
 //#region src/run.d.ts
 interface RunCommandOptions extends OutputOptions {
   printer?: Printer;
+  signal?: AbortSignal;
   showUsage?: ShowUsageCallback;
 }
 declare function runCommand<S extends ArgsSchema>(root: CommandDef<S>, argv: string[], options?: RunCommandOptions): Promise<unknown>;

package/dist/index.js

@@ -108,6 +108,7 @@ function schemaShape(schema) {
 //#endregion
 //#region src/command.ts
 function defineCommand(def) {
+	if (def.allowUnknownArgs !== void 0 && typeof def.allowUnknownArgs !== "boolean") throw new TypeError("allowUnknownArgs must be a boolean");
 	const shape = def.args ? schemaShape(def.args) : {};
 	const positionals = readPositionals(shape);
 	if (positionals) {
@@ -611,6 +612,10 @@ async function parseCommandArgs(command, rawArgs, tokenized = tokenizeCommandArg
 	else if (token.kind === "unknown-option") extraArgs.push(token.value);
 	else if (positionals && (positionals.rest || positionalValues.length < positionals.items.length)) positionalValues.push(token.value);
 	else extraArgs.push(token.value);
+	if (!command.allowUnknownArgs && extraArgs.length > 0) throw new HackshValidationError(command, extraArgs.map((arg) => ({
+		arg,
+		message: "unexpected argument"
+	})));
 	const envSources = /* @__PURE__ */ new Map();
 	if (env && command.args) {
 		const shape = schemaShape(command.args);
@@ -767,7 +772,7 @@ function redactError(error, secrets) {
 function observedError(plan, error) {
 	return plan.redact.length === 0 ? error : redactError(error, plan.redact);
 }
-function parsePlan(file, args, options, baseEnv) {
+function parsePlan(file, args, options, context) {
 	if (typeof file !== "string" || file === "") throw new TypeError("Exec file must be a non-empty string");
 	assertNoNul(file, "Exec file");
 	const argv = args === void 0 ? [] : args;
@@ -797,11 +802,11 @@ function parsePlan(file, args, options, baseEnv) {
 	return {
 		command,
 		reported: redactCommand(command, redact),
-		env: mergeEnvironment(baseEnv, raw.env),
+		env: mergeEnvironment(context.env, raw.env),
 		input,
 		reject: reject ?? true,
 		timeout: timeout === void 0 ? void 0 : readInteger(timeout, "Exec option `timeout`", 1, MAX_DELAY),
-		signal,
+		signal: signal === void 0 ? context.signal : AbortSignal.any([context.signal, signal]),
 		maxBuffer: maxBuffer === void 0 ? 1e8 : readInteger(maxBuffer, "Exec option `maxBuffer`", 1, Number.MAX_SAFE_INTEGER),
 		forceKillAfterDelay: forceKillAfterDelay === void 0 ? 5e3 : readInteger(forceKillAfterDelay, "Exec option `forceKillAfterDelay`", 0, MAX_DELAY),
 		stdin,
@@ -912,7 +917,7 @@ function runPlan(plan) {
 		spawnError: void 0,
 		exit: void 0
 	};
-	if (plan.signal?.aborted) {
+	if (plan.signal.aborted) {
 		outcome.cause = "aborted";
 		return Promise.resolve(toResult(plan.reported, outcome, "", ""));
 	}
@@ -931,7 +936,7 @@ function runPlan(plan) {
 			settled = true;
 			clearTimeout(timeoutTimer);
 			clearTimeout(killTimer);
-			plan.signal?.removeEventListener("abort", onAbort);
+			plan.signal.removeEventListener("abort", onAbort);
 			resolve(toResult(plan.reported, outcome, readStdout(), readStderr()));
 		};
 		const release = () => {
@@ -953,7 +958,7 @@ function runPlan(plan) {
 		const readStdout = stdout ? collect(stdout, plan.maxBuffer, () => terminate("output-limit")) : () => "";
 		const readStderr = stderr ? collect(stderr, plan.maxBuffer, () => terminate("output-limit")) : () => "";
 		const timeoutTimer = plan.timeout === void 0 ? void 0 : setTimeout(() => terminate("timeout"), plan.timeout);
-		plan.signal?.addEventListener("abort", onAbort, { once: true });
+		plan.signal.addEventListener("abort", onAbort, { once: true });
 		child.on("error", (error) => {
 			if (child.pid !== void 0) return;
 			outcome.spawnError = observedError(plan, error);
@@ -1013,8 +1018,8 @@ function blockedReason(plan, context, stdio) {
 	if (plan.interactive && !context.mode.interactive) return "non-interactive";
 }
 async function execute(file, args, options, context) {
-	const plan = parsePlan(file, args, options, context.env);
-	if (plan.signal?.aborted) return complete(plan, emptyFailure(plan, "aborted"));
+	const plan = parsePlan(file, args, options, context);
+	if (plan.signal.aborted) return complete(plan, emptyFailure(plan, "aborted"));
 	const stdio = commandStdio(plan);
 	const blocked = blockedReason(plan, context, stdio);
 	if (blocked) return complete(plan, emptyFailure(plan, blocked));
@@ -1503,11 +1508,13 @@ var PromptController = class {
 	#printEvent;
 	#bufferedKeys = [];
 	#terminal;
+	#signal;
 	constructor(options) {
 		this.#interactive = options.interactive;
 		this.#inputValue = options.input;
 		this.#printEvent = (event) => options.print(event);
 		this.#terminal = options.terminal;
+		this.#signal = options.signal;
 	}
 	async #print(state, prompt) {
 		try {
@@ -1521,6 +1528,7 @@ var PromptController = class {
 	}
 	async #run(prompt, initial, accept, update, submitted, closed) {
 		if (!this.#interactive) throw promptError("non-interactive", prompt, `Cannot request ${prompt.kind} input in non-interactive mode: ${prompt.message}`);
+		if (this.#signal.aborted) throw promptError("aborted", prompt, "Prompt aborted", this.#signal.reason);
 		const input = asInput(this.#inputValue, prompt);
 		if (!this.#terminal.acquire("prompt")) throw promptError("overlapping", prompt, this.#terminal.owner === "exec" ? "A command is using the terminal" : "Another prompt is already active");
 		let originallyFlowing = false;
@@ -1607,6 +1615,7 @@ var PromptController = class {
 					};
 					const onEnd = () => fail("eof", "Prompt input ended before a value was submitted");
 					const onError = (cause) => fail("input-error", "Prompt input failed", cause);
+					const onAbort = () => fail("aborted", "Prompt aborted", this.#signal.reason);
 					const onData = (chunk) => {
 						if (typeof chunk === "string" || chunk instanceof Uint8Array) keypressInput.write(chunk);
 						else fail("input-error", "Prompt input produced a non-byte value");
@@ -1618,12 +1627,15 @@ var PromptController = class {
 						input.removeListener("end", onEnd);
 						input.removeListener("close", onEnd);
 						input.removeListener("error", onError);
+						this.#signal.removeEventListener("abort", onAbort);
 					};
 					keypressInput.on("keypress", onKeypress);
 					input.on("data", onData);
 					input.on("end", onEnd);
 					input.on("close", onEnd);
 					input.on("error", onError);
+					this.#signal.addEventListener("abort", onAbort, { once: true });
+					if (this.#signal.aborted) onAbort();
 					input.resume();
 					drainKeys().catch((cause) => fail("input-error", "Prompt input could not be processed", cause));
 				})
@@ -1808,7 +1820,8 @@ function createLogger(printer, category, options) {
 		interactive: options.interactive,
 		input: options.input,
 		print: (event) => options.printPrompt(event),
-		terminal: options.terminal
+		terminal: options.terminal,
+		signal: options.signal
 	});
 	return createBoundLogger(printer, [...category], {}, prompts);
 }
@@ -2059,15 +2072,17 @@ function resolveCommand(root, rawArgs) {
 		const parentPath = commandEnvPath(command);
 		command = {
 			...child,
-			name: child.name ?? key
+			name: child.name ?? key,
+			allowUnknownArgs: child.allowUnknownArgs ?? command.allowUnknownArgs
 		};
 		registerCommandPath(command, parentPath === void 0 ? void 0 : [...parentPath, key]);
 		remaining = remaining.slice(index + 1);
 	}
 }
-async function executeCommand(root, argv, displayUsage, printer, loggerOptions, execContext, fallbackVersion = async () => void 0) {
+async function executeCommand(root, argv, displayUsage, output, env, signal, fallbackVersion = async () => void 0) {
 	if (root.args && "version" in schemaShape(root.args)) throw new TypeError("Root option `version` conflicts with the builtin --version");
-	const env = execContext.env ?? process.env;
+	const { printer } = output;
+	const argEnv = env ?? process.env;
 	const resolved = resolveCommand(root, argv);
 	if (resolved.segments[0]?.tokenized.version) {
 		const version = root.version ?? await fallbackVersion() ?? "";
@@ -2081,16 +2096,33 @@ async function executeCommand(root, argv, displayUsage, printer, loggerOptions,
 		await printUsage(displayUsage, resolved.command, printer, "stdout");
 		return;
 	}
-	for (const parent of resolved.parents) await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized, env, commandEnvPath(parent.command));
-	const parsed = await parseCommandArgs(resolved.command, resolved.rawArgs, resolved.tokenized, env, commandEnvPath(resolved.command));
+	for (const parent of resolved.parents) await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized, argEnv, commandEnvPath(parent.command));
+	const parsed = await parseCommandArgs(resolved.command, resolved.rawArgs, resolved.tokenized, argEnv, commandEnvPath(resolved.command));
 	if (!resolved.command.run) throw new HackshUsageError("No command specified", resolved.command);
+	signal.throwIfAborted();
 	const category = resolved.segments.flatMap(({ command }) => command.name === void 0 ? [] : [command.name]);
 	return resolved.command.run({
 		...parsed,
 		cmd: resolved.command,
 		rawArgs: resolved.rawArgs,
-		logger: createLogger(printer, category, loggerOptions),
-		exec: createExec(execContext)
+		logger: createLogger(printer, category, {
+			interactive: output.interactive,
+			input: output.input,
+			printPrompt: (event) => output.printChecked(event),
+			terminal: output.terminal,
+			signal
+		}),
+		exec: createExec({
+			env,
+			mode: {
+				format: output.format,
+				interactive: output.interactive
+			},
+			print: (event) => printer.print(event),
+			terminal: output.terminal,
+			signal
+		}),
+		signal
 	});
 }
 function printUsage(displayUsage, command, printer, stream) {
@@ -2117,26 +2149,10 @@ function prepareOutput(options, env) {
 		terminal: new TerminalLock()
 	};
 }
-function invocationExec(output, env) {
-	return {
-		env,
-		mode: {
-			format: output.format,
-			interactive: output.interactive
-		},
-		print: (event) => output.printer.print(event),
-		terminal: output.terminal
-	};
-}
 async function runCommand(root, argv, options = {}) {
 	const output = prepareOutput(options, options.env ?? process.env);
 	try {
-		return await executeCommand(root, argv, options.showUsage ?? showUsage, output.printer, {
-			interactive: output.interactive,
-			input: output.input,
-			printPrompt: (event) => output.printChecked(event),
-			terminal: output.terminal
-		}, invocationExec(output, options.env));
+		return await executeCommand(root, argv, options.showUsage ?? showUsage, output, options.env, options.signal ?? new AbortController().signal);
 	} finally {
 		await output.drain();
 	}
@@ -2152,6 +2168,30 @@ function commandErrorExitCode(error) {
 	if (error instanceof HackshExitError) return error.exitCode;
 	return error instanceof HackshPromptError && error.reason === "cancelled" ? 130 : 1;
 }
+const SIGNAL_EXIT_CODES = {
+	SIGINT: 130,
+	SIGTERM: 143
+};
+function listenForExitSignals() {
+	const controller = new AbortController();
+	let exitCode;
+	const listeners = Object.entries(SIGNAL_EXIT_CODES).map(([signal, code]) => {
+		const listener = () => {
+			if (exitCode !== void 0) process.exit(code);
+			exitCode = code;
+			controller.abort(new DOMException(`Received ${signal}`, "AbortError"));
+		};
+		process.on(signal, listener);
+		return [signal, listener];
+	});
+	return {
+		signal: controller.signal,
+		exitCode: () => exitCode,
+		release() {
+			for (const [signal, listener] of listeners) process.removeListener(signal, listener);
+		}
+	};
+}
 async function reportOutputSetupError(error, options) {
 	if (options.onError) {
 		await options.onError(error);
@@ -2183,24 +2223,28 @@ async function runMain(command, options = {}) {
 	} catch (error) {
 		return reportOutputSetupError(error, options);
 	}
+	const signals = listenForExitSignals();
+	const exit = (code) => {
+		signals.release();
+		return drainAndExit(output, signals.exitCode() ?? code);
+	};
 	try {
-		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage, output.printer, {
-			interactive: output.interactive,
-			input: output.input,
-			printPrompt: (event) => output.printChecked(event),
-			terminal: output.terminal
-		}, invocationExec(output, options.env), () => findPackageVersion(process.argv[1]));
+		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage, output, options.env, signals.signal, () => findPackageVersion(process.argv[1]));
 	} catch (error) {
 		if (options.onError) {
 			await options.onError(error);
-			return drainAndExit(output, commandErrorExitCode(error));
+			return exit(commandErrorExitCode(error));
 		}
 		try {
 			await reportCommandError(error, output, displayUsage);
 		} finally {
-			await drainAndExit(output, commandErrorExitCode(error));
+			await exit(commandErrorExitCode(error));
 		}
+	} finally {
+		signals.release();
 	}
+	const signalExitCode = signals.exitCode();
+	if (signalExitCode !== void 0) return drainAndExit(output, signalExitCode);
 	await output.drain();
 }
 function createMain(command, options = {}) {