hacksh 0.9.0 → 0.11.0

package/README.md

@@ -304,10 +304,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.
 
@@ -352,7 +354,8 @@ narrowed before reading `exitCode`.
 
 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,6 +574,42 @@ 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.
+
+```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.
+
 ## Development
 
 | Command                | Description                                           |

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;
@@ -32,6 +32,11 @@ declare class HackshExecError extends Error {
   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 {
+  readonly exitCode: number;
+  constructor(exitCode: number, message?: string, options?: ErrorOptions);
+}
 type HackshErrorKind = "error" | "prompt" | "usage" | "validation" | "thrown";
 interface ValidationIssueSummary {
   arg: string;
@@ -367,6 +372,7 @@ interface CommandContext<S extends ArgsSchema> {
   extraArgs: string[];
   logger: Logger;
   exec: Exec;
+  signal: AbortSignal;
 }
 interface CommandDef<S extends ArgsSchema = EmptyArgs> {
   name?: string;
@@ -403,6 +409,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>;
@@ -415,5 +422,5 @@ interface RunMainOptions extends OutputOptions {
 declare function runMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): Promise<void>;
 declare function createMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): (argv?: string[]) => Promise<void>;
 //#endregion
-export { type ArgOptions, type ArgOptionsMap, type CommandContext, type CommandDef, type ConfirmOptions, type ConfirmPromptState, type ErrorPrintEvent, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecPrintEvent, type ExecResult, type ExecReturn, type ExecSuccess, type HackshErrorKind, type HackshErrorSummary, HackshExecError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type JsonPrinterOptions, type LogKind, type LogLevel, type LogPrintEvent, type LogProperties, type LogRecord, type Logger, type OutputFormat, type OutputMode, type OutputOptions, type OutputPreference, type OutputWriter, type PrettyPrinterOptions, type PrintEvent, type PrintStream, type Printer, type PromptChoiceState, type PromptErrorDetails, type PromptKind, type PromptPrintEvent, type PromptState, type PromptStatus, type Prompter, type ResolveOutputModeOptions, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type SelectPromptState, type ShowUsageCallback, type ShowUsageOptions, type StreamPrinterOptions, type TerminalInput, type TerminalOutput, type TextOptions, type TextPromptState, type UsageArgumentSummary, type UsageCommandSummary, type UsageOptionSummary, type UsageOutput, type UsagePrintEvent, type UsageSummary, type UsageWriter, type ValidationIssueSummary, type VersionPrintEvent, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
+export { type ArgOptions, type ArgOptionsMap, type CommandContext, type CommandDef, type ConfirmOptions, type ConfirmPromptState, type ErrorPrintEvent, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecPrintEvent, type ExecResult, type ExecReturn, type ExecSuccess, type HackshErrorKind, type HackshErrorSummary, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type JsonPrinterOptions, type LogKind, type LogLevel, type LogPrintEvent, type LogProperties, type LogRecord, type Logger, type OutputFormat, type OutputMode, type OutputOptions, type OutputPreference, type OutputWriter, type PrettyPrinterOptions, type PrintEvent, type PrintStream, type Printer, type PromptChoiceState, type PromptErrorDetails, type PromptKind, type PromptPrintEvent, type PromptState, type PromptStatus, type Prompter, type ResolveOutputModeOptions, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type SelectPromptState, type ShowUsageCallback, type ShowUsageOptions, type StreamPrinterOptions, type TerminalInput, type TerminalOutput, type TextOptions, type TextPromptState, type UsageArgumentSummary, type UsageCommandSummary, type UsageOptionSummary, type UsageOutput, type UsagePrintEvent, type UsageSummary, type UsageWriter, type ValidationIssueSummary, type VersionPrintEvent, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -185,6 +185,16 @@ var HackshExecError = class extends Error {
 		return this.#result;
 	}
 };
+/** A requested process exit status; `runMain` exits with it and reports only a non-empty message. */
+var HackshExitError = class extends Error {
+	exitCode;
+	constructor(exitCode, message, options) {
+		if (!Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) throw new TypeError("Exit code must be an integer from 0 to 255");
+		super(message, options);
+		this.name = "HackshExitError";
+		this.exitCode = exitCode;
+	}
+};
 function safeString$1(value, fallback) {
 	try {
 		return String(value);
@@ -757,7 +767,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;
@@ -787,11 +797,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,
@@ -902,7 +912,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, "", ""));
 	}
@@ -921,7 +931,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 = () => {
@@ -943,7 +953,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);
@@ -1003,8 +1013,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));
@@ -1493,11 +1503,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 {
@@ -1511,6 +1523,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;
@@ -1597,6 +1610,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");
@@ -1608,12 +1622,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));
 				})
@@ -1798,7 +1815,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);
 }
@@ -2055,9 +2073,10 @@ function resolveCommand(root, rawArgs) {
 		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() ?? "";
@@ -2071,16 +2090,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) {
@@ -2107,26 +2143,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();
 	}
@@ -2139,8 +2159,33 @@ async function drainAndExit(output, code = 1) {
 	}
 }
 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);
@@ -2156,6 +2201,14 @@ async function reportOutputSetupError(error, options) {
 	});
 	return drainAndExit(output);
 }
+async function reportCommandError(error, output, displayUsage) {
+	if (error instanceof HackshExitError && error.message === "") return;
+	await output.printer.print({
+		type: "error",
+		error: summarizeError(error)
+	});
+	if (error instanceof HackshUsageError) await printUsage(displayUsage, error.command, output.printer, "stderr");
+}
 async function runMain(command, options = {}) {
 	const displayUsage = options.showUsage ?? showUsage;
 	let output;
@@ -2164,33 +2217,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 {
-			if (error instanceof HackshUsageError) {
-				await output.printer.print({
-					type: "error",
-					error: summarizeError(error)
-				});
-				await printUsage(displayUsage, error.command, output.printer, "stderr");
-			} else await output.printer.print({
-				type: "error",
-				error: summarizeError(error)
-			});
+			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 = {}) {
@@ -2200,6 +2248,6 @@ function createMain(command, options = {}) {
 	});
 }
 //#endregion
-export { HackshExecError, HackshPromptError, HackshUsageError, HackshValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
+export { HackshExecError, HackshExitError, HackshPromptError, HackshUsageError, HackshValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
 
 //# sourceMappingURL=index.js.map