hacksh 0.12.0 → 0.14.0

package/dist/index.js

@@ -1,10 +1,10 @@
+import { a as createExec, c as HackshPromptError, d as summarizeError, f as summarizeErrors, i as resolveOutputMode, l as HackshUsageError, n as createJsonPrinter, o as HackshExecError, r as createPrintQueue, s as HackshExitError, t as createPrettyPrinter, u as HackshValidationError } from "./pretty-BFub611x.js";
 import { globalRegistry, safeParseAsync } from "zod/v4/core";
-import { inspect, parseArgs as parseArgs$1, stripVTControlCharacters, styleText } from "node:util";
-import { spawn } from "node:child_process";
-import { emitKeypressEvents } from "node:readline";
-import { PassThrough } from "node:stream";
+import { parseArgs as parseArgs$1 } from "node:util";
 import { readFile, realpath } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+import { PassThrough } from "node:stream";
 //#region src/options.ts
 function kebabCase(value) {
 	return value.replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
@@ -12,6 +12,9 @@ function kebabCase(value) {
 function aliasList(value) {
 	return typeof value === "string" ? [value] : value;
 }
+//#endregion
+//#region src/schema.ts
+const POSITIONALS_KEY = "positionals";
 function definition(schema) {
 	return schema._zod.def;
 }
@@ -35,8 +38,23 @@ function readArgInfo(schema) {
 	let defaultValue;
 	let description;
 	let title;
+	let alias;
+	let valueName;
+	let env;
 	while (current) {
 		const metadata = globalRegistry.get(current);
+		if (metadata) {
+			if (metadata.alias !== void 0 && typeof metadata.alias !== "string" && !(Array.isArray(metadata.alias) && metadata.alias.every((value) => typeof value === "string"))) throw new TypeError("Argument metadata `alias` must be a string or an array of strings");
+			if (metadata.env !== void 0 && typeof metadata.env !== "string" && metadata.env !== false) throw new TypeError("Argument metadata `env` must be a string or false");
+			for (const key of [
+				"valueName",
+				"title",
+				"description"
+			]) if (metadata[key] !== void 0 && typeof metadata[key] !== "string") throw new TypeError(`Argument metadata \`${key}\` must be a string`);
+			alias ??= metadata.alias;
+			valueName ??= metadata.valueName;
+			env ??= metadata.env;
+		}
 		description ??= metadata?.description;
 		title ??= metadata?.title;
 		const def = definition(current);
@@ -51,12 +69,15 @@ function readArgInfo(schema) {
 		defaultValue,
 		description,
 		title,
+		alias,
+		valueName,
+		env,
 		choices: enumChoices(base)
 	};
 }
-/** Read the `_` tuple or array schema that declares positional arguments. */
+/** Read the `positionals` tuple or array schema that declares positional arguments. */
 function readPositionals(shape) {
-	const field = shape["_"];
+	const field = shape[POSITIONALS_KEY];
 	if (!field) return void 0;
 	const def = definition(unwrapInput(field));
 	let items;
@@ -67,7 +88,7 @@ function readPositionals(shape) {
 	} else if (def.type === "array") {
 		items = [];
 		rest = def.element;
-	} else throw new TypeError("Positional arguments `_` must use a tuple or array schema");
+	} else throw new TypeError("Positional arguments `positionals` must use a tuple or array schema");
 	return {
 		items: items.map((schema, index) => ({
 			schema,
@@ -115,24 +136,31 @@ function defineCommand(def) {
 		let sawOptional = false;
 		for (const { schema, label } of positionals.items) {
 			const info = readArgInfo(schema);
+			if (info.alias !== void 0 || info.env !== void 0 || info.valueName !== void 0) throw new TypeError(`Positional argument \`${label}\` cannot have alias, env, or valueName metadata`);
 			if (isArrayInput(schema)) throw new TypeError(`Positional argument \`${label}\` cannot be an array; use a tuple rest`);
 			if (!info.takesValue) throw new TypeError(`Boolean argument \`${label}\` cannot be positional`);
 			if (sawOptional && info.required) throw new TypeError(`Required positional \`${label}\` cannot follow an optional positional`);
 			sawOptional ||= !info.required;
 		}
+		if (positionals.rest) {
+			const info = readArgInfo(positionals.rest.schema);
+			if (info.alias !== void 0 || info.env !== void 0 || info.valueName !== void 0) throw new TypeError(`Positional argument \`${positionals.rest.label}\` cannot have alias, env, or valueName metadata`);
+		}
 		if (def.subCommands && Object.keys(def.subCommands).length > 0) throw new TypeError("A command cannot define both positional arguments and subcommands");
 	}
 	const usedAliases = /* @__PURE__ */ new Set();
-	for (const [key, options] of Object.entries(def.argOptions ?? {})) {
-		if (key === "_") throw new TypeError("Positional arguments cannot have argument options");
-		const schema = shape[key];
-		if (!schema) throw new TypeError(`Unknown argument options key \`${key}\``);
-		if (options?.env !== void 0) {
+	for (const [key, schema] of Object.entries(shape)) {
+		const options = readArgInfo(schema);
+		if (key === "positionals") {
+			if (options.alias !== void 0 || options.env !== void 0 || options.valueName !== void 0) throw new TypeError("Positional arguments cannot have alias, env, or valueName metadata");
+			continue;
+		}
+		if (options.env !== void 0) {
 			if (options.env === "") throw new TypeError(`Environment variable name for \`${key}\` cannot be empty`);
 			if (isArrayInput(schema)) throw new TypeError(`Option \`${key}\` cannot use an environment variable because it accepts an array`);
 			if (isObjectInput(schema)) throw new TypeError(`Option \`${key}\` cannot use an environment variable because it accepts an object`);
 		}
-		if (options?.alias === void 0) continue;
+		if (options.alias === void 0) continue;
 		for (const alias of aliasList(options.alias)) {
 			if (alias.length !== 1) throw new TypeError(`Alias \`${alias}\` must be exactly one character`);
 			if (usedAliases.has(alias)) throw new TypeError(`Duplicate alias \`${alias}\``);
@@ -140,228 +168,12 @@ function defineCommand(def) {
 		}
 	}
 	for (const key of Object.keys(shape)) {
-		if (key === "help") throw new TypeError("Option `help` conflicts with the builtin --help");
-		if (key !== "_" && /^no[-A-Z]/.test(key)) throw new TypeError(`Option \`${key}\` conflicts with --no- negation`);
+		if (key === "help" || key === "version") throw new TypeError(`Option \`${key}\` conflicts with the builtin --${key}`);
+		if (key !== "positionals" && /^no[-A-Z]/.test(key)) throw new TypeError(`Option \`${key}\` conflicts with --no- negation`);
 	}
 	return def;
 }
 //#endregion
-//#region src/errors.ts
-var HackshUsageError = class extends Error {
-	command;
-	constructor(message, command, options) {
-		super(message, options);
-		this.name = "HackshUsageError";
-		this.command = command;
-	}
-};
-var HackshValidationError = class extends HackshUsageError {
-	issues;
-	constructor(command, issues) {
-		super(`Invalid arguments:\n${issues.map(({ arg, message }) => `  ${arg}: ${message}`).join("\n")}`, command);
-		this.name = "HackshValidationError";
-		this.issues = issues;
-	}
-};
-/** An input request that could not be completed safely. */
-var HackshPromptError = class extends Error {
-	reason;
-	prompt;
-	constructor(reason, prompt, message, options) {
-		super(message, options);
-		this.name = "HackshPromptError";
-		this.reason = reason;
-		this.prompt = prompt;
-	}
-};
-/** An external command that did not succeed; `result` is not enumerable so error summaries omit child output. */
-var HackshExecError = class extends Error {
-	#result;
-	constructor(message, result, options) {
-		super(message, options);
-		this.name = "HackshExecError";
-		this.#result = result;
-	}
-	get result() {
-		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);
-	} catch {
-		return fallback;
-	}
-}
-function readProperty(value, key) {
-	try {
-		return Reflect.get(value, key);
-	} catch {
-		return "[Unserializable]";
-	}
-}
-function enumerableKeys(value) {
-	try {
-		return Object.keys(value);
-	} catch {
-		return [];
-	}
-}
-function hasToJSON(value) {
-	try {
-		return typeof Reflect.get(value, "toJSON") === "function";
-	} catch {
-		return false;
-	}
-}
-function isPlainObject(value) {
-	try {
-		const prototype = Object.getPrototypeOf(value);
-		return prototype === Object.prototype || prototype === null;
-	} catch {
-		return false;
-	}
-}
-function summarizeIssue({ arg, message, issue }, seen) {
-	if (!issue) return {
-		arg,
-		message
-	};
-	const details = {};
-	for (const key of enumerableKeys(issue)) {
-		if ([
-			"code",
-			"path",
-			"message",
-			"inst"
-		].includes(key)) continue;
-		details[key] = summarizeErrors(readProperty(issue, key), seen);
-	}
-	const code = readProperty(issue, "code");
-	const path = readProperty(issue, "path");
-	return {
-		arg,
-		message,
-		...typeof code === "string" ? { code } : {},
-		...Array.isArray(path) ? { path } : {},
-		...Object.keys(details).length === 0 ? {} : { details }
-	};
-}
-function errorKind(error) {
-	if (error instanceof HackshPromptError) return "prompt";
-	if (error instanceof HackshValidationError) return "validation";
-	if (error instanceof HackshUsageError) return "usage";
-	return "error";
-}
-function summarizeErrorWithSeen(error, seen) {
-	const summary = {
-		kind: errorKind(error),
-		name: safeString$1(readProperty(error, "name"), "Error"),
-		message: safeString$1(readProperty(error, "message"), "[Unserializable error message]")
-	};
-	seen.set(error, summary);
-	const stack = readProperty(error, "stack");
-	const cause = readProperty(error, "cause");
-	if (typeof stack === "string") summary.stack = stack;
-	if (cause !== void 0) summary.cause = summarizeErrors(cause, seen);
-	if (error instanceof HackshValidationError) summary.issues = error.issues.map((issue) => summarizeIssue(issue, seen));
-	const reserved = /* @__PURE__ */ new Set([
-		"name",
-		"message",
-		"stack",
-		"cause",
-		"command",
-		"issues"
-	]);
-	const properties = {};
-	for (const key of enumerableKeys(error)) {
-		if (reserved.has(key)) continue;
-		properties[key] = summarizeErrors(readProperty(error, key), seen);
-	}
-	if (Object.keys(properties).length > 0) summary.properties = properties;
-	return summary;
-}
-/** Recursively replace Error values with command- and schema-free summaries. */
-function summarizeErrors(value, seen = /* @__PURE__ */ new WeakMap()) {
-	if (typeof value !== "object" || value === null) return value;
-	const existing = seen.get(value);
-	if (existing !== void 0) return existing;
-	if (value instanceof Error) return summarizeErrorWithSeen(value, seen);
-	if (Array.isArray(value)) {
-		const result = [];
-		seen.set(value, result);
-		let changed = false;
-		for (const item of value) {
-			const summarized = summarizeErrors(item, seen);
-			result.push(summarized);
-			changed ||= summarized !== item;
-		}
-		if (changed) return result;
-		seen.set(value, value);
-		return value;
-	}
-	if (value instanceof Map) {
-		const result = /* @__PURE__ */ new Map();
-		seen.set(value, result);
-		let changed = false;
-		for (const [key, item] of value) {
-			const summarizedKey = summarizeErrors(key, seen);
-			const summarizedItem = summarizeErrors(item, seen);
-			result.set(summarizedKey, summarizedItem);
-			changed ||= summarizedKey !== key || summarizedItem !== item;
-		}
-		if (changed) return result;
-		seen.set(value, value);
-		return value;
-	}
-	if (value instanceof Set) {
-		const result = /* @__PURE__ */ new Set();
-		seen.set(value, result);
-		let changed = false;
-		for (const item of value) {
-			const summarized = summarizeErrors(item, seen);
-			result.add(summarized);
-			changed ||= summarized !== item;
-		}
-		if (changed) return result;
-		seen.set(value, value);
-		return value;
-	}
-	if (ArrayBuffer.isView(value) || hasToJSON(value) || !isPlainObject(value)) return value;
-	const result = {};
-	seen.set(value, result);
-	let changed = false;
-	for (const key of enumerableKeys(value)) {
-		const original = readProperty(value, key);
-		const summarized = summarizeErrors(original, seen);
-		result[key] = summarized;
-		changed ||= summarized !== original;
-	}
-	if (changed) return result;
-	seen.set(value, value);
-	return value;
-}
-/** Convert any thrown value into a canonical error description. */
-function summarizeError(error) {
-	if (error instanceof Error) return summarizeErrorWithSeen(error, /* @__PURE__ */ new WeakMap());
-	return {
-		kind: "thrown",
-		name: "NonErrorThrown",
-		message: safeString$1(error, "[Unserializable thrown value]"),
-		value: summarizeErrors(error)
-	};
-}
-//#endregion
 //#region src/environment.ts
 const commandPaths = /* @__PURE__ */ new WeakMap();
 function registerCommandPath(command, path) {
@@ -378,9 +190,9 @@ function optionEnvNames(command, path) {
 	const names = /* @__PURE__ */ new Map();
 	if (!command.args) return names;
 	for (const [key, schema] of Object.entries(schemaShape(command.args))) {
-		if (key === "_") continue;
+		if (key === "positionals") continue;
 		if (isArrayInput(schema) || isObjectInput(schema)) continue;
-		const configured = command.argOptions?.[key]?.env;
+		const configured = readArgInfo(schema).env;
 		if (configured === false) continue;
 		if (typeof configured === "string") {
 			names.set(key, configured);
@@ -420,13 +232,13 @@ function optionModel(command) {
 	const parserOptions = {};
 	const allAliases = /* @__PURE__ */ new Set();
 	if (command.args) for (const [key, schema] of Object.entries(schemaShape(command.args))) {
-		if (key === "_") continue;
-		const alias = command.argOptions?.[key]?.alias;
-		const aliases = alias ? aliasList(alias) : [];
+		if (key === "positionals") continue;
+		const info = readArgInfo(schema);
+		const aliases = info.alias === void 0 ? [] : aliasList(info.alias);
 		const definition = {
 			key,
 			kebabName: kebabCase(key),
-			takesValue: readArgInfo(schema).takesValue
+			takesValue: info.takesValue
 		};
 		const type = definition.takesValue ? "string" : "boolean";
 		for (const name of /* @__PURE__ */ new Set([key, definition.kebabName])) {
@@ -454,7 +266,7 @@ function commandPositionals(command) {
 function displayName(command, path) {
 	const [first, index] = path;
 	if (typeof first !== "string") return "arguments";
-	if (first !== "_") return `--${kebabCase(first)}`;
+	if (first !== "positionals") return `--${kebabCase(first)}`;
 	const positionals = commandPositionals(command);
 	if (!positionals || typeof index !== "number") return "arguments";
 	const item = positionals.items[index];
@@ -606,7 +418,7 @@ async function parseCommandArgs(command, rawArgs, tokenized = tokenizeCommandArg
 	const input = {};
 	const positionals = commandPositionals(command);
 	const positionalValues = [];
-	if (positionals) input["_"] = positionalValues;
+	if (positionals) input[POSITIONALS_KEY] = positionalValues;
 	const extraArgs = [];
 	for (const token of tokenized.tokens) if (token.kind === "known-option") input[token.definition.key] = token.value;
 	else if (token.kind === "unknown-option") extraArgs.push(token.value);
@@ -679,803 +491,91 @@ var TerminalLock = class {
 	}
 };
 //#endregion
-//#region src/exec.ts
-const OPTION_KEYS = /* @__PURE__ */ new Set([
-	"cwd",
-	"env",
-	"input",
-	"reject",
-	"timeout",
-	"signal",
-	"maxBuffer",
-	"forceKillAfterDelay",
-	"stdin",
-	"stdout",
-	"stderr",
-	"interactive",
-	"display",
-	"redact"
-]);
-const MAX_DELAY = 2147483647;
-const REFUSAL_MESSAGE = {
-	"json-output": "Command cannot use the terminal in JSON output mode",
-	"non-interactive": "Command requires an interactive terminal",
-	overlapping: "Command cannot use the terminal while it is in use"
-};
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function assertNoNul(value, label) {
-	if (value.includes("\0")) throw new TypeError(`${label} must not contain NUL characters`);
-}
-function readInteger(value, label, minimum, maximum) {
-	if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value > maximum) throw new TypeError(`${label} must be an integer from ${minimum} to ${maximum}`);
-	return value;
-}
-function readEnum(value, label, allowed) {
-	if (typeof value === "string" && allowed.includes(value)) return value;
-	throw new TypeError(`Exec option \`${label}\` must be ${allowed.map((item) => JSON.stringify(item)).join(" or ")}`);
-}
-function readBoolean(value, label) {
-	if (typeof value !== "boolean") throw new TypeError(`Exec option \`${label}\` must be a boolean`);
-	return value;
-}
-function readRedact(value) {
-	if (!Array.isArray(value)) throw new TypeError("Exec option `redact` must be an array");
-	for (const item of value) {
-		if (typeof item !== "string" || item === "") throw new TypeError("Exec option `redact` must contain only non-empty strings");
-		assertNoNul(item, "Exec option `redact`");
-	}
-	return value;
-}
-function mergeEnvironment(base, overrides) {
-	if (overrides === void 0 && base === void 0) return void 0;
-	if (overrides !== void 0 && !isRecord(overrides)) throw new TypeError("Exec option `env` must be an object");
-	const merged = {};
-	for (const [key, value] of Object.entries(base ?? process.env)) if (value !== void 0) merged[key] = value;
-	for (const [key, value] of Object.entries(overrides ?? {})) {
-		if (key === "" || key.includes("=") || key.includes("\0")) throw new TypeError(`Invalid environment variable name ${JSON.stringify(key)}`);
-		if (value === void 0) {
-			delete merged[key];
-			continue;
-		}
-		if (typeof value !== "string") throw new TypeError(`Environment variable ${key} must be a string or undefined`);
-		assertNoNul(value, `Environment variable ${key}`);
-		merged[key] = value;
-	}
-	return merged;
-}
-function redactValue(value, secrets) {
-	let redacted = value;
-	for (const secret of [...secrets].sort((left, right) => right.length - left.length)) redacted = redacted.split(secret).join("***");
-	return redacted;
-}
-function redactCommand(command, secrets) {
-	if (secrets.length === 0) return command;
-	return {
-		file: redactValue(command.file, secrets),
-		args: command.args.map((arg) => redactValue(arg, secrets)),
-		cwd: command.cwd === void 0 ? void 0 : redactValue(command.cwd, secrets)
-	};
-}
-function redactError(error, secrets) {
-	const source = error;
-	const redacted = new Error(redactValue(error.message, secrets));
-	if (typeof error.stack === "string") redacted.stack = redactValue(error.stack, secrets);
-	if (source.code !== void 0) redacted.code = source.code;
-	if (source.errno !== void 0) redacted.errno = source.errno;
-	if (typeof source.syscall === "string") redacted.syscall = redactValue(source.syscall, secrets);
-	if (typeof source.path === "string") redacted.path = redactValue(source.path, secrets);
-	if (Array.isArray(source.spawnargs)) redacted.spawnargs = source.spawnargs.map((arg) => typeof arg === "string" ? redactValue(arg, secrets) : arg);
-	return redacted;
-}
-function observedError(plan, error) {
-	return plan.redact.length === 0 ? error : redactError(error, plan.redact);
-}
-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;
-	if (!Array.isArray(argv) || !argv.every((arg) => typeof arg === "string")) throw new TypeError("Exec args must be an array of strings");
-	for (const arg of argv) assertNoNul(arg, "Exec args");
-	const raw = options === void 0 ? {} : options;
-	if (!isRecord(raw)) throw new TypeError("Exec options must be an object");
-	for (const key of Object.keys(raw)) if (!OPTION_KEYS.has(key)) throw new TypeError(`Unknown exec option \`${key}\``);
-	const { cwd, input, reject, timeout, signal, maxBuffer, forceKillAfterDelay } = raw;
-	if (cwd !== void 0) {
-		if (typeof cwd !== "string" || cwd === "") throw new TypeError("Exec option `cwd` must be a non-empty string");
-		assertNoNul(cwd, "Exec option `cwd`");
-	}
-	if (input !== void 0 && typeof input !== "string") throw new TypeError("Exec option `input` must be a string");
-	if (reject !== void 0 && typeof reject !== "boolean") throw new TypeError("Exec option `reject` must be a boolean");
-	if (signal !== void 0 && !(signal instanceof AbortSignal)) throw new TypeError("Exec option `signal` must be an AbortSignal");
-	const stdin = raw.stdin === void 0 ? "pipe" : readEnum(raw.stdin, "stdin", ["pipe", "inherit"]);
-	const stdout = raw.stdout === void 0 ? "pipe" : readEnum(raw.stdout, "stdout", ["pipe", "inherit"]);
-	const stderr = raw.stderr === void 0 ? "pipe" : readEnum(raw.stderr, "stderr", ["pipe", "inherit"]);
-	if (input !== void 0 && stdin === "inherit") throw new TypeError("Exec option `input` cannot be combined with stdin inherit");
-	const command = {
-		file,
-		args: [...argv],
-		cwd
-	};
-	const redact = raw.redact === void 0 ? [] : readRedact(raw.redact);
-	return {
-		command,
-		reported: redactCommand(command, redact),
-		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 === 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,
-		stdout,
-		stderr,
-		interactive: raw.interactive === void 0 ? false : readBoolean(raw.interactive, "interactive"),
-		display: raw.display === void 0 ? true : readBoolean(raw.display, "display"),
-		redact
-	};
-}
-function stripFinalNewline(text) {
-	if (text.endsWith("\r\n")) return text.slice(0, -2);
-	if (text.endsWith("\n")) return text.slice(0, -1);
-	return text;
-}
-function collect(stream, limit, onLimit) {
-	const chunks = [];
-	let length = 0;
-	let exceeded = false;
-	stream.on("data", (chunk) => {
-		if (exceeded) return;
-		const remaining = limit - length;
-		if (chunk.length <= remaining) {
-			chunks.push(chunk);
-			length += chunk.length;
-			return;
+//#region src/logger.ts
+function interpolate(message, properties) {
+	return message.replace(/\{([^{}]+)\}/g, (placeholder, key) => {
+		if (!Object.hasOwn(properties, key)) return placeholder;
+		try {
+			return String(properties[key]);
+		} catch {
+			return placeholder;
 		}
-		chunks.push(chunk.subarray(0, remaining));
-		length = limit;
-		exceeded = true;
-		onLimit();
 	});
-	return () => stripFinalNewline(Buffer.concat(chunks).toString("utf8"));
-}
-function toResult(command, outcome, stdout, stderr) {
-	const failed = {
-		status: "failed",
-		command,
-		stdout,
-		stderr
-	};
-	if (outcome.cause) return {
-		...failed,
-		reason: outcome.cause
-	};
-	if (outcome.spawnError) return {
-		...failed,
-		reason: "spawn",
-		error: outcome.spawnError
-	};
-	const { code, signal } = outcome.exit ?? {
-		code: null,
-		signal: null
-	};
-	if (signal !== null) return {
-		...failed,
-		reason: "signal",
-		signal
-	};
-	if (code !== 0) return {
-		...failed,
-		reason: "exit-code",
-		exitCode: code ?? 1
-	};
-	return {
-		status: "succeeded",
-		command,
-		stdout,
-		stderr,
-		exitCode: 0
-	};
-}
-function isSpawnErrno(error) {
-	return error instanceof Error && "syscall" in error;
-}
-function commandStdio(plan) {
-	return {
-		stdin: plan.stdin === "inherit" ? "inherit" : plan.input === void 0 ? "ignore" : "input",
-		stdout: plan.stdout,
-		stderr: plan.stderr
-	};
 }
-function usesTerminal(plan, stdio) {
-	return plan.interactive || stdio.stdin === "inherit" || stdio.stdout === "inherit" || stdio.stderr === "inherit";
-}
-function startChild(plan) {
-	const stdio = commandStdio(plan);
-	try {
-		return spawn(plan.command.file, plan.command.args, {
-			cwd: plan.command.cwd,
-			env: plan.env,
-			shell: false,
-			windowsHide: true,
-			stdio: [
-				stdio.stdin === "inherit" ? "inherit" : stdio.stdin === "input" ? "pipe" : "ignore",
-				stdio.stdout,
-				stdio.stderr
-			]
-		});
-	} catch (error) {
-		if (isSpawnErrno(error)) return error;
-		throw error;
-	}
-}
-function runPlan(plan) {
-	const outcome = {
-		cause: void 0,
-		spawnError: void 0,
-		exit: void 0
-	};
-	if (plan.signal.aborted) {
-		outcome.cause = "aborted";
-		return Promise.resolve(toResult(plan.reported, outcome, "", ""));
-	}
-	const child = startChild(plan);
-	if (child instanceof Error) {
-		outcome.spawnError = observedError(plan, child);
-		return Promise.resolve(toResult(plan.reported, outcome, "", ""));
-	}
-	return new Promise((resolve) => {
-		const stdout = child.stdout;
-		const stderr = child.stderr;
-		let settled = false;
-		let killTimer;
-		const settle = () => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeoutTimer);
-			clearTimeout(killTimer);
-			plan.signal.removeEventListener("abort", onAbort);
-			resolve(toResult(plan.reported, outcome, readStdout(), readStderr()));
-		};
-		const release = () => {
-			stdout?.destroy();
-			stderr?.destroy();
-			settle();
+function createBoundLogger(printer, category, boundProperties) {
+	function emit(level, kind, input, properties = {}) {
+		const rawMessage = input instanceof Error ? input.message : input;
+		const mergedProperties = {
+			...boundProperties,
+			...properties
 		};
-		const terminate = (cause) => {
-			if (settled || outcome.cause) return;
-			outcome.cause = cause;
-			if (outcome.exit) {
-				release();
-				return;
+		if (input instanceof Error) mergedProperties.error = input;
+		const summarizedProperties = summarizeErrors(mergedProperties);
+		printer.print({
+			type: "log",
+			record: {
+				level,
+				kind,
+				category,
+				message: interpolate(rawMessage, mergedProperties),
+				rawMessage,
+				properties: summarizedProperties,
+				timestamp: Date.now()
 			}
-			child.kill("SIGTERM");
-			killTimer = setTimeout(() => child.kill("SIGKILL"), plan.forceKillAfterDelay);
-		};
-		const onAbort = () => terminate("aborted");
-		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 });
-		child.on("error", (error) => {
-			if (child.pid !== void 0) return;
-			outcome.spawnError = observedError(plan, error);
-			release();
 		});
-		child.on("exit", (code, signal) => {
-			outcome.exit = {
-				code,
-				signal
-			};
-			clearTimeout(killTimer);
-			if (outcome.cause) release();
-		});
-		child.on("close", settle);
-		if (child.stdin) {
-			child.stdin.on("error", () => void 0);
-			child.stdin.end(plan.input);
-		}
-	});
-}
-function formatArgument(value) {
-	return value === "" || /[\s"'\\$`;|&<>*?()[\]{}~#!]/.test(value) ? JSON.stringify(value) : value;
-}
-function formatExecCommand(command) {
-	return [command.file, ...command.args].map(formatArgument).join(" ");
-}
-function failureMessage(plan, result) {
-	const display = formatExecCommand(plan.reported);
-	switch (result.reason) {
-		case "exit-code": return `Command failed with exit code ${result.exitCode}: ${display}`;
-		case "signal": return `Command was terminated by ${result.signal}: ${display}`;
-		case "spawn": return `Command could not be started (${result.error.code ?? result.error.message}): ${display}`;
-		case "timeout": return `Command timed out after ${plan.timeout} ms: ${display}`;
-		case "aborted": return `Command was aborted: ${display}`;
-		case "output-limit": return `Command output exceeded ${plan.maxBuffer} bytes: ${display}`;
-		case "json-output":
-		case "non-interactive":
-		case "overlapping": return `${REFUSAL_MESSAGE[result.reason]}: ${display}`;
 	}
-}
-function emptyFailure(plan, reason) {
 	return {
-		status: "failed",
-		command: plan.reported,
-		stdout: "",
-		stderr: "",
-		reason
+		category,
+		trace: (message, properties) => emit("trace", "message", message, properties),
+		debug: (message, properties) => emit("debug", "message", message, properties),
+		info: (message, properties) => emit("info", "message", message, properties),
+		warn: (message, properties) => emit("warning", "message", message, properties),
+		error: (message, properties) => emit("error", "message", message, properties),
+		fatal: (message, properties) => emit("fatal", "message", message, properties),
+		step: (message, properties) => emit("info", "step", message, properties),
+		success: (message, properties) => emit("info", "success", message, properties),
+		with: (properties) => createBoundLogger(printer, category, {
+			...boundProperties,
+			...properties
+		}),
+		getChild: (child) => createBoundLogger(printer, [...category, child], boundProperties)
 	};
 }
-function complete(plan, result) {
-	if (result.status === "failed" && plan.reject) throw new HackshExecError(failureMessage(plan, result), result, result.reason === "spawn" ? { cause: result.error } : void 0);
-	return result;
-}
-function blockedReason(plan, context, stdio) {
-	const inherited = stdio.stdin === "inherit" || stdio.stdout === "inherit" || stdio.stderr === "inherit";
-	if (context.mode.format === "json" && inherited) return "json-output";
-	if (plan.interactive && !context.mode.interactive) return "non-interactive";
-}
-async function execute(file, args, options, context) {
-	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));
-	const holdTerminal = usesTerminal(plan, stdio);
-	if (holdTerminal && !context.terminal.acquire("exec")) return complete(plan, emptyFailure(plan, "overlapping"));
-	try {
-		if (plan.display) {
-			const { file, args, cwd } = plan.reported;
-			await context.print({
-				type: "exec",
-				phase: "start",
-				command: cwd === void 0 ? {
-					file,
-					args
-				} : {
-					file,
-					args,
-					cwd
-				},
-				stdio,
-				interactive: plan.interactive
-			});
-		}
-		return complete(plan, await runPlan(plan));
-	} finally {
-		if (holdTerminal) context.terminal.release();
-	}
-}
-function createExec(context) {
-	return ((file, args, options) => execute(file, args, options, context));
+/** Create the logger for one command invocation. */
+function createLogger(printer, category) {
+	return createBoundLogger(printer, [...category], {});
 }
 //#endregion
-//#region src/serialization.ts
-function safeString(value) {
-	try {
-		return String(value);
-	} catch {
-		return "[Unserializable]";
-	}
-}
-function normalizeProperty(value, key, ancestors) {
-	try {
-		return normalizeJson(Reflect.get(value, key), ancestors);
-	} catch {
-		return "[Unserializable]";
-	}
-}
-function normalizedKeys(value) {
+//#region src/package-version.ts
+async function findPackageVersion(entry) {
+	if (!entry) return void 0;
+	let directory;
 	try {
-		return Object.keys(value);
+		directory = dirname(await realpath(entry));
 	} catch {
 		return;
 	}
-}
-const noToJson = Symbol("noToJson");
-function normalizedToJson(value, ancestors) {
-	let toJSON;
-	try {
-		toJSON = Reflect.get(value, "toJSON");
-	} catch {
-		return noToJson;
-	}
-	if (typeof toJSON !== "function") return noToJson;
-	try {
-		const result = Reflect.apply(toJSON, value, []);
-		return result === value ? noToJson : normalizeJson(result, ancestors);
-	} catch {
-		return noToJson;
-	}
-}
-function isArrayBufferView(value) {
-	try {
-		return ArrayBuffer.isView(value);
-	} catch {
-		return false;
-	}
-}
-/** Normalize arbitrary event data into values accepted by JSON.stringify. */
-function normalizeJson(value, ancestors = /* @__PURE__ */ new Set()) {
-	switch (typeof value) {
-		case "string": return stripVTControlCharacters(value);
-		case "boolean": return value;
-		case "number": return Number.isFinite(value) ? value : null;
-		case "bigint": return value.toString();
-		case "undefined": return "[undefined]";
-		case "symbol": return `[symbol:${stripVTControlCharacters(value.description ?? "")}]`;
-		case "function": return `[function:${stripVTControlCharacters(value.name || "anonymous")}]`;
-	}
-	if (value === null) return null;
-	if (ancestors.has(value)) return "[Circular]";
-	const nextAncestors = new Set(ancestors).add(value);
-	if (value instanceof Error) return normalizeJson(summarizeError(value), nextAncestors);
-	const jsonValue = normalizedToJson(value, nextAncestors);
-	if (jsonValue !== noToJson) return jsonValue;
-	if (isArrayBufferView(value)) {
-		if (value instanceof DataView) return Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
-		try {
-			return Array.from(value, (item) => normalizeJson(item, nextAncestors));
-		} catch {
-			return "[Unserializable]";
-		}
-	}
-	if (value instanceof ArrayBuffer) return Array.from(new Uint8Array(value));
-	if (Array.isArray(value)) return Array.from({ length: value.length }, (_, index) => normalizeProperty(value, index, nextAncestors));
-	if (value instanceof Map) try {
-		return [...value].map(([key, item]) => [normalizeJson(key, nextAncestors), normalizeJson(item, nextAncestors)]);
-	} catch {
-		return "[Unserializable]";
-	}
-	if (value instanceof Set) try {
-		return [...value].map((item) => normalizeJson(item, nextAncestors));
-	} catch {
-		return "[Unserializable]";
-	}
-	const keys = normalizedKeys(value);
-	if (!keys) return safeString(value);
-	const result = {};
-	for (const key of keys) result[stripVTControlCharacters(key)] = normalizeProperty(value, key, nextAncestors);
-	return result;
-}
-//#endregion
-//#region src/printer.ts
-function fallbackValue(value) {
-	try {
-		return String(value);
-	} catch {
-		return "[Unserializable]";
+	for (;;) {
+		const version = await readPackageVersion(join(directory, "package.json"));
+		if (version !== void 0) return version;
+		const parent = dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
 	}
 }
-function validatePreference(value, source) {
-	if (value === void 0) return void 0;
-	if (value === "auto" || value === "pretty" || value === "json") return value;
-	throw new TypeError(`Invalid ${source} value ${fallbackValue(value)}; expected auto, pretty, or json`);
-}
-function readEnvironment(env, key) {
+async function readPackageVersion(path) {
+	let text;
 	try {
-		return env[key];
+		text = await readFile(path, "utf8");
 	} catch {
 		return;
 	}
-}
-/** Resolve output behavior once, before command routing or argument parsing. */
-function resolveOutputMode(options = {}) {
-	const env = options.env ?? process.env;
-	const configured = validatePreference(options.output, "output");
-	const requested = validatePreference(readEnvironment(env, "HACKSH_OUTPUT"), "HACKSH_OUTPUT") ?? configured ?? "auto";
-	const ci = Boolean(readEnvironment(env, "CI"));
-	const format = requested === "auto" ? ci ? "json" : "pretty" : requested;
-	const inputIsTTY = options.inputIsTTY ?? process.stdin.isTTY === true;
-	const outputIsTTY = options.outputIsTTY ?? process.stdout.isTTY === true;
-	return {
-		format,
-		interactive: format === "pretty" && !ci && inputIsTTY && outputIsTTY,
-		color: format === "pretty" && outputIsTTY && !readEnvironment(env, "NO_COLOR")
-	};
-}
-function isErrorLevel(level) {
-	return level === "warning" || level === "error" || level === "fatal";
-}
-function eventStream(event) {
-	if (event.type === "error" || event.type === "exec") return "stderr";
-	if (event.type === "usage") return event.stream;
-	if (event.type === "log" && isErrorLevel(event.record.level)) return "stderr";
-	return "stdout";
-}
-function formatTextEvent(event) {
-	switch (event.type) {
-		case "usage": return event.text;
-		case "version": return event.version;
-		case "error": return event.error.kind === "usage" || event.error.kind === "validation" ? event.error.message : `Error: ${event.error.message}`;
-		case "log": return event.record.message;
-		case "prompt": return event.prompt.message;
-		case "exec": return `$ ${formatExecCommand(event.command)}`;
-	}
-}
-/** Undecorated console compatibility adapter; automatic output uses the selected format printer. */
-const consolePrinter = { print(event) {
-	const text = formatTextEvent(event);
-	return eventStream(event) === "stdout" ? console.log(text) : console.error(text);
-} };
-/** Create an undecorated stream-backed compatibility adapter. */
-function createStreamPrinter(options) {
-	return { print(event) {
-		(eventStream(event) === "stdout" ? options.stdout : options.stderr).write(`${formatTextEvent(event)}\n`);
-	} };
-}
-/** Create a one-semantic-event-per-line JSON printer. */
-function createJsonPrinter(options = {}) {
-	const stdout = options.stdout ?? process.stdout;
-	const stderr = options.stderr ?? process.stderr;
-	return { print(event) {
-		let serialized;
-		try {
-			serialized = JSON.stringify(normalizeJson(event));
-		} catch {
-			serialized = JSON.stringify({
-				type: event.type,
-				serializationError: "Event data could not be serialized"
-			});
-		}
-		const line = `${serialized}\n`;
-		(eventStream(event) === "stdout" ? stdout : stderr).write(line);
-	} };
-}
-/** Serialize printer calls and retain failures until the invocation drains its output. */
-function createPrintQueue(target) {
-	let pending;
-	let failure;
-	let failed = false;
-	function recordFailure(error) {
-		if (!failed) failure = error;
-		failed = true;
-	}
-	function track(execution, retainFailure) {
-		const barrier = execution.catch((error) => {
-			if (retainFailure) recordFailure(error);
-		});
-		pending = barrier;
-		barrier.then(() => {
-			if (pending === barrier) pending = void 0;
-		});
-		return retainFailure ? barrier : execution;
-	}
-	function enqueue(event, retainFailure) {
-		if (pending) return track(pending.then(() => target.print(event)), retainFailure);
-		try {
-			const result = target.print(event);
-			if (result) return track(Promise.resolve(result), retainFailure);
-		} catch (error) {
-			if (retainFailure) recordFailure(error);
-			else return Promise.reject(error);
-		}
-	}
-	return {
-		printer: { print(event) {
-			return enqueue(event, true);
-		} },
-		async printChecked(event) {
-			await enqueue(event, false);
-		},
-		async drain() {
-			await pending;
-			if (failed) throw failure;
-		}
-	};
-}
-//#endregion
-//#region src/pretty.ts
-const unicodeSymbols = {
-	bar: "│",
-	marks: {
-		trace: "·",
-		debug: "◆",
-		info: "●",
-		warning: "▲",
-		error: "■",
-		fatal: "✖",
-		step: "◇",
-		success: "✔",
-		usage: "◆",
-		version: "●",
-		errorEvent: "■",
-		prompt: "?",
-		exec: "$"
-	}
-};
-const asciiSymbols = {
-	bar: "|",
-	marks: {
-		trace: ".",
-		debug: ":",
-		info: "i",
-		warning: "!",
-		error: "x",
-		fatal: "X",
-		step: ">",
-		success: "+",
-		usage: "?",
-		version: "i",
-		errorEvent: "x",
-		prompt: "?",
-		exec: "$"
-	}
-};
-const markStyles = {
-	trace: "gray",
-	debug: "magenta",
-	info: "blue",
-	warning: "yellow",
-	error: "red",
-	fatal: [
-		"bgRed",
-		"white",
-		"bold"
-	],
-	step: "cyan",
-	success: "green",
-	usage: "cyan",
-	version: "blue",
-	errorEvent: "red",
-	prompt: "cyan",
-	exec: "gray"
-};
-function safelyInspect(value) {
-	if (typeof value === "string") return value;
 	try {
-		return inspect(value, {
-			breakLength: 80,
-			colors: false,
-			compact: false,
-			depth: null,
-			sorted: true
-		});
+		const { version } = JSON.parse(text);
+		return typeof version === "string" ? version : void 0;
 	} catch {
-		return "[Unserializable]";
-	}
-}
-function propertyLines(properties) {
-	const lines = [];
-	for (const key of Object.keys(properties).sort()) {
-		const rendered = `  ${key}: ${safelyInspect(properties[key])}`.split("\n");
-		lines.push(rendered[0] ?? "");
-		for (const continuation of rendered.slice(1)) lines.push(`    ${continuation}`);
-	}
-	return lines;
-}
-function logLines(record) {
-	const category = record.category.length > 0 ? `[${record.category.join(":")}] ` : "";
-	const message = record.message.split("\n");
-	return [
-		`${category}${message[0] ?? ""}`,
-		...message.slice(1),
-		...propertyLines(record.properties)
-	];
-}
-function errorLines(error) {
-	const lines = error.message.split("\n");
-	const details = {};
-	if (error.cause !== void 0) details.cause = error.cause;
-	if (error.properties !== void 0) Object.assign(details, error.properties);
-	if (error.value !== void 0) details.value = error.value;
-	return [...lines, ...propertyLines(details)];
-}
-function eventMark(event) {
-	if (event.type === "usage") return "usage";
-	if (event.type === "version") return "version";
-	if (event.type === "error") return "errorEvent";
-	if (event.type === "prompt") return event.prompt.status === "submitted" ? "success" : "prompt";
-	if (event.type === "exec") return "exec";
-	return event.record.kind === "message" ? event.record.level : event.record.kind;
-}
-function eventLines(event) {
-	switch (event.type) {
-		case "usage": return event.text.split("\n");
-		case "version": return event.version.split("\n");
-		case "error": return errorLines(event.error);
-		case "log": return logLines(event.record);
-		case "prompt": {
-			const { prompt } = event;
-			if (prompt.status === "submitted") {
-				const result = prompt.kind === "select" ? prompt.choices.find(({ value }) => value === prompt.value)?.label ?? prompt.value : prompt.kind === "confirm" ? prompt.value ? "Yes" : "No" : prompt.value;
-				return [`${prompt.message}: ${result}`];
-			}
-			const lines = [prompt.message];
-			if (prompt.kind === "select") for (const choice of prompt.choices) lines.push(`${choice.selected ? ">" : " "} ${choice.label}${choice.hint ? ` — ${choice.hint}` : ""}`);
-			else if (prompt.kind === "confirm") lines.push(`${prompt.value ? "Yes" : "No"}${prompt.defaultValue === void 0 ? "" : ` (default: ${prompt.defaultValue ? "yes" : "no"})`}`);
-			else lines.push(prompt.value || (prompt.placeholder ? `(${prompt.placeholder})` : ""));
-			if (prompt.error) lines.push(prompt.error);
-			return lines;
-		}
-		case "exec": {
-			const lines = [formatExecCommand(event.command)];
-			if (event.command.cwd !== void 0) lines.push(...propertyLines({ cwd: event.command.cwd }));
-			return lines;
-		}
-	}
-}
-function colorize(enabled, style, text) {
-	return enabled ? styleText(style, text, { validateStream: false }) : text;
-}
-const graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
-const combiningMark = /\p{Mark}/u;
-const pictograph = /\p{Extended_Pictographic}/u;
-function isWideCodePoint(codePoint) {
-	return codePoint >= 4352 && (codePoint <= 4447 || codePoint === 9001 || codePoint === 9002 || codePoint >= 11904 && codePoint <= 42191 && codePoint !== 12351 || codePoint >= 44032 && codePoint <= 55203 || codePoint >= 63744 && codePoint <= 64255 || codePoint >= 65040 && codePoint <= 65049 || codePoint >= 65072 && codePoint <= 65135 || codePoint >= 65280 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || codePoint >= 131072 && codePoint <= 262141);
-}
-function displayWidth(text) {
-	let width = 0;
-	for (const { segment } of graphemeSegmenter.segment(stripVTControlCharacters(text))) {
-		if (segment === "	") {
-			width += 8 - width % 8;
-			continue;
-		}
-		if (pictograph.test(segment) || Array.from(segment).some((value) => isWideCodePoint(value.codePointAt(0)))) {
-			width += 2;
-			continue;
-		}
-		for (const value of segment) {
-			const codePoint = value.codePointAt(0);
-			if (codePoint < 32 || codePoint >= 127 && codePoint < 160) continue;
-			if (codePoint === 8205 || codePoint >= 65024 && codePoint <= 65039) continue;
-			if (!combiningMark.test(value)) width += 1;
-		}
-	}
-	return width;
-}
-function renderedRows(rendered, columns) {
-	const width = Number.isInteger(columns) && columns !== void 0 && columns > 0 ? columns : void 0;
-	return rendered.split("\n").reduce((rows, line) => {
-		if (!width) return rows + 1;
-		return rows + Math.max(1, Math.ceil(displayWidth(line) / width));
-	}, 0);
-}
-/** Create the fixed human-readable renderer used for pretty output. */
-function createPrettyPrinter(options) {
-	const stdout = options.stdout ?? process.stdout;
-	const stderr = options.stderr ?? process.stderr;
-	const symbols = options.unicode ? unicodeSymbols : asciiSymbols;
-	let activePrompt;
-	function render(event) {
-		const mark = eventMark(event);
-		const lines = eventLines(event);
-		const firstPrefix = colorize(options.color, markStyles[mark], symbols.marks[mark]);
-		const barPrefix = colorize(options.color, "gray", symbols.bar);
-		return lines.map((line, index) => `${index === 0 ? firstPrefix : barPrefix}${line ? `  ${line}` : ""}`).join("\n");
-	}
-	function eraseActivePrompt() {
-		return activePrompt ? "\x1B[1A\x1B[2K".repeat(activePrompt.lines) : "";
+		return;
 	}
-	return { print(event) {
-		const rendered = render(event);
-		if (event.type === "prompt") {
-			const erase = eraseActivePrompt();
-			if (event.prompt.status === "closed") {
-				activePrompt = void 0;
-				if (erase) stdout.write(erase);
-				return;
-			}
-			if (event.prompt.status === "submitted") activePrompt = void 0;
-			else activePrompt = {
-				rendered,
-				lines: renderedRows(rendered, stdout.columns)
-			};
-			stdout.write(`${erase}${rendered}\n`);
-			return;
-		}
-		const erase = eraseActivePrompt();
-		if (!activePrompt) {
-			(eventStream(event) === "stdout" ? stdout : stderr).write(`${rendered}\n`);
-			return;
-		}
-		stdout.write(erase);
-		if (event.type === "error") activePrompt = void 0;
-		(eventStream(event) === "stdout" ? stdout : stderr).write(`${rendered}\n`);
-		if (activePrompt) stdout.write(`${activePrompt.rendered}\n`);
-	} };
 }
 //#endregion
 //#region src/prompts.ts
@@ -1761,103 +861,6 @@ var PromptController = class {
 	}
 };
 //#endregion
-//#region src/logger.ts
-function interpolate(message, properties) {
-	return message.replace(/\{([^{}]+)\}/g, (placeholder, key) => {
-		if (!Object.hasOwn(properties, key)) return placeholder;
-		try {
-			return String(properties[key]);
-		} catch {
-			return placeholder;
-		}
-	});
-}
-function createBoundLogger(printer, category, boundProperties, prompts) {
-	function emit(level, kind, input, properties = {}) {
-		const rawMessage = input instanceof Error ? input.message : input;
-		const mergedProperties = {
-			...boundProperties,
-			...properties
-		};
-		if (input instanceof Error) mergedProperties.error = input;
-		const summarizedProperties = summarizeErrors(mergedProperties);
-		printer.print({
-			type: "log",
-			record: {
-				level,
-				kind,
-				category,
-				message: interpolate(rawMessage, mergedProperties),
-				rawMessage,
-				properties: summarizedProperties,
-				timestamp: Date.now()
-			}
-		});
-	}
-	return {
-		category,
-		trace: (message, properties) => emit("trace", "message", message, properties),
-		debug: (message, properties) => emit("debug", "message", message, properties),
-		info: (message, properties) => emit("info", "message", message, properties),
-		warn: (message, properties) => emit("warning", "message", message, properties),
-		error: (message, properties) => emit("error", "message", message, properties),
-		fatal: (message, properties) => emit("fatal", "message", message, properties),
-		step: (message, properties) => emit("info", "step", message, properties),
-		success: (message, properties) => emit("info", "success", message, properties),
-		select: (options) => prompts.select(options),
-		confirm: (options) => prompts.confirm(options),
-		text: (options) => prompts.text(options),
-		with: (properties) => createBoundLogger(printer, category, {
-			...boundProperties,
-			...properties
-		}, prompts),
-		getChild: (child) => createBoundLogger(printer, [...category, child], boundProperties, prompts)
-	};
-}
-/** Create the logger for one command invocation. */
-function createLogger(printer, category, options) {
-	const prompts = new PromptController({
-		interactive: options.interactive,
-		input: options.input,
-		print: (event) => options.printPrompt(event),
-		terminal: options.terminal,
-		signal: options.signal
-	});
-	return createBoundLogger(printer, [...category], {}, prompts);
-}
-//#endregion
-//#region src/package-version.ts
-async function findPackageVersion(entry) {
-	if (!entry) return void 0;
-	let directory;
-	try {
-		directory = dirname(await realpath(entry));
-	} catch {
-		return;
-	}
-	for (;;) {
-		const version = await readPackageVersion(join(directory, "package.json"));
-		if (version !== void 0) return version;
-		const parent = dirname(directory);
-		if (parent === directory) return void 0;
-		directory = parent;
-	}
-}
-async function readPackageVersion(path) {
-	let text;
-	try {
-		text = await readFile(path, "utf8");
-	} catch {
-		return;
-	}
-	try {
-		const { version } = JSON.parse(text);
-		return typeof version === "string" ? version : void 0;
-	} catch {
-		return;
-	}
-}
-//#endregion
 //#region src/output.ts
 function consoleWriter(method, stream) {
 	return {
@@ -1952,12 +955,11 @@ function summarizeUsage(command) {
 		});
 	}
 	const envNames = optionEnvNames(command, commandEnvPath(command));
-	const options = Object.entries(shape).filter(([key]) => key !== "_").map(([key, schema]) => {
+	const options = Object.entries(shape).filter(([key]) => key !== POSITIONALS_KEY).map(([key, schema]) => {
 		const info = readArgInfo(schema);
-		const argOptions = command.argOptions?.[key];
-		const aliases = argOptions?.alias ? aliasList(argOptions.alias).map((item) => `-${item}`) : [];
+		const aliases = info.alias === void 0 ? [] : aliasList(info.alias).map((item) => `-${item}`);
 		const name = kebabCase(key);
-		const valueName = argOptions?.valueName ?? name;
+		const valueName = info.valueName ?? name;
 		const envName = envNames.get(key);
 		return {
 			name,
@@ -2016,15 +1018,14 @@ function formatUsage(summary) {
 	return lines.join("\n");
 }
 /** Generate usage text without writing to stdout or stderr. */
-async function renderUsage(command) {
+function renderUsage(command) {
 	return formatUsage(summarizeUsage(command));
 }
-/** Generate and write usage text, awaiting asynchronous writers. */
-async function showUsage(command, options = {}) {
+/** Generate a usage event and await its printer. */
+async function showUsage(command, options) {
 	const usage = summarizeUsage(command);
 	const text = formatUsage(usage);
-	if (options.write) return options.write(text);
-	return (options.printer ?? selectOutputPrinter(options)).print({
+	return options.printer.print({
 		type: "usage",
 		usage,
 		text,
@@ -2079,8 +1080,7 @@ function resolveCommand(root, rawArgs) {
 		remaining = remaining.slice(index + 1);
 	}
 }
-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");
+async function executeCommand(root, argv, output, env, signal, fallbackVersion = async () => void 0) {
 	const { printer } = output;
 	const argEnv = env ?? process.env;
 	const resolved = resolveCommand(root, argv);
@@ -2093,7 +1093,7 @@ async function executeCommand(root, argv, displayUsage, output, env, signal, fal
 		return;
 	}
 	if (resolved.segments.some(({ tokenized }) => tokenized.help)) {
-		await printUsage(displayUsage, resolved.command, printer, "stdout");
+		await showUsage(resolved.command, { printer });
 		return;
 	}
 	for (const parent of resolved.parents) await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized, argEnv, commandEnvPath(parent.command));
@@ -2102,13 +1102,18 @@ async function executeCommand(root, argv, displayUsage, output, env, signal, fal
 	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, {
+		command: resolved.command,
+		args: parsed.args,
+		input: {
+			argv: resolved.rawArgs,
+			unknown: parsed.extraArgs,
+			passthrough: parsed.passthrough
+		},
+		logger: createLogger(printer, category),
+		prompt: new PromptController({
 			interactive: output.interactive,
 			input: output.input,
-			printPrompt: (event) => output.printChecked(event),
+			print: (event) => output.printChecked(event),
 			terminal: output.terminal,
 			signal
 		}),
@@ -2125,14 +1130,6 @@ async function executeCommand(root, argv, displayUsage, output, env, signal, fal
 		signal
 	});
 }
-function printUsage(displayUsage, command, printer, stream) {
-	return displayUsage(command, { write: (text) => printer.print({
-		type: "usage",
-		usage: summarizeUsage(command),
-		text,
-		stream
-	}) });
-}
 function prepareOutput(options, env) {
 	const input = options.stdin ?? process.stdin;
 	const mode = resolveOutputMode({
@@ -2152,7 +1149,7 @@ function prepareOutput(options, env) {
 async function runCommand(root, argv, options = {}) {
 	const output = prepareOutput(options, options.env ?? process.env);
 	try {
-		return await executeCommand(root, argv, options.showUsage ?? showUsage, output, options.env, options.signal ?? new AbortController().signal);
+		return await executeCommand(root, argv, output, options.env, options.signal ?? new AbortController().signal);
 	} finally {
 		await output.drain();
 	}
@@ -2207,16 +1204,18 @@ async function reportOutputSetupError(error, options) {
 	});
 	return drainAndExit(output);
 }
-async function reportCommandError(error, output, displayUsage) {
+async function reportCommandError(error, output) {
 	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");
+	if (error instanceof HackshUsageError) await showUsage(error.command, {
+		printer: output.printer,
+		stream: "stderr"
+	});
 }
 async function runMain(command, options = {}) {
-	const displayUsage = options.showUsage ?? showUsage;
 	let output;
 	try {
 		output = prepareOutput(options, options.env ?? process.env);
@@ -2229,14 +1228,14 @@ async function runMain(command, options = {}) {
 		return drainAndExit(output, signals.exitCode() ?? code);
 	};
 	try {
-		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage, output, options.env, signals.signal, () => findPackageVersion(process.argv[1]));
+		await executeCommand(command, options.argv ?? process.argv.slice(2), output, options.env, signals.signal, () => findPackageVersion(process.argv[1]));
 	} catch (error) {
 		if (options.onError) {
 			await options.onError(error);
 			return exit(commandErrorExitCode(error));
 		}
 		try {
-			await reportCommandError(error, output, displayUsage);
+			await reportCommandError(error, output);
 		} finally {
 			await exit(commandErrorExitCode(error));
 		}
@@ -2247,13 +1246,7 @@ async function runMain(command, options = {}) {
 	if (signalExitCode !== void 0) return drainAndExit(output, signalExitCode);
 	await output.drain();
 }
-function createMain(command, options = {}) {
-	return (argv) => runMain(command, argv === void 0 ? options : {
-		...options,
-		argv
-	});
-}
 //#endregion
-export { HackshExecError, HackshExitError, HackshPromptError, HackshUsageError, HackshValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
+export { HackshExecError, HackshExitError, HackshPromptError, HackshUsageError, HackshValidationError, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
 
 //# sourceMappingURL=index.js.map