hacksh 0.1.1 → 0.2.0

package/dist/index.js

@@ -1,5 +1,7 @@
 import { globalRegistry, safeParseAsync } from "zod/v4/core";
-import { parseArgs as parseArgs$1 } from "node:util";
+import { inspect, parseArgs as parseArgs$1, stripVTControlCharacters, styleText } from "node:util";
+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();
@@ -144,6 +146,182 @@ var ZittyValidationError = class extends ZittyUsageError {
 		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;
+	}
+};
+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 ZittyValidationError) return "validation";
+	if (error instanceof ZittyUsageError) 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 ZittyValidationError) 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/parser.ts
 function optionModel(command) {
@@ -360,6 +538,801 @@ async function parseArgs(command, argv) {
 	return (await parseCommandArgs(command, argv)).args;
 }
 //#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) {
+	try {
+		return Object.keys(value);
+	} 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]";
+	}
+}
+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) {
+	try {
+		return env[key];
+	} 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") 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;
+	}
+}
+/** 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: "?"
+	}
+};
+const asciiSymbols = {
+	bar: "|",
+	marks: {
+		trace: ".",
+		debug: ":",
+		info: "i",
+		warning: "!",
+		error: "x",
+		fatal: "X",
+		step: ">",
+		success: "+",
+		usage: "?",
+		version: "i",
+		errorEvent: "x",
+		prompt: "?"
+	}
+};
+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"
+};
+function safelyInspect(value) {
+	if (typeof value === "string") return value;
+	try {
+		return inspect(value, {
+			breakLength: 80,
+			colors: false,
+			compact: false,
+			depth: null,
+			sorted: true
+		});
+	} 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";
+	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;
+		}
+	}
+}
+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 { 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
+function details$1(kind, message, choices) {
+	let normalizedMessage;
+	try {
+		normalizedMessage = typeof message === "string" ? message : String(message);
+	} catch {
+		normalizedMessage = "[Unserializable prompt message]";
+	}
+	return {
+		kind,
+		message: normalizedMessage,
+		...choices === void 0 ? {} : { choices }
+	};
+}
+function promptError(reason, prompt, message, cause) {
+	return new HackshPromptError(reason, prompt, message, cause === void 0 ? void 0 : { cause });
+}
+function validateMessage(kind, message, choices) {
+	if (typeof message !== "string" || message.length === 0) throw promptError("invalid-options", details$1(kind, message, choices), `Invalid ${kind} prompt: message must be a non-empty string`);
+}
+function asInput(value, prompt) {
+	if (typeof value !== "object" || value === null || typeof Reflect.get(value, "on") !== "function" || typeof Reflect.get(value, "removeListener") !== "function" || typeof Reflect.get(value, "resume") !== "function" || typeof Reflect.get(value, "pause") !== "function") throw promptError("input-error", prompt, "Interactive input is not a readable stream");
+	return value;
+}
+var PromptController = class {
+	#interactive;
+	#inputValue;
+	#printEvent;
+	#bufferedKeys = [];
+	#active = false;
+	constructor(options) {
+		this.#interactive = options.interactive;
+		this.#inputValue = options.input;
+		this.#printEvent = (event) => options.print(event);
+	}
+	async #print(state, prompt) {
+		try {
+			await this.#printEvent({
+				type: "prompt",
+				prompt: state
+			});
+		} catch (cause) {
+			throw promptError("printer-error", prompt, "The prompt could not be displayed", cause);
+		}
+	}
+	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.#active) throw promptError("overlapping", prompt, "Another prompt is already active");
+		const input = asInput(this.#inputValue, prompt);
+		this.#active = true;
+		let originallyFlowing = false;
+		let rawChanged = false;
+		let outcome;
+		try {
+			originallyFlowing = input.readableFlowing === true;
+			if (input.setRawMode && input.isRaw !== true) {
+				input.setRawMode(true);
+				rawChanged = true;
+			}
+			await this.#print(initial, prompt);
+			outcome = {
+				ok: true,
+				value: await new Promise((resolve, reject) => {
+					const keypressInput = new PassThrough();
+					emitKeypressEvents(keypressInput);
+					let settled = false;
+					let draining = false;
+					let finalized = false;
+					let completion;
+					const queuedKeys = this.#bufferedKeys.splice(0);
+					const finalize = () => {
+						if (finalized || !settled || draining) return;
+						finalized = true;
+						cleanup();
+						completion?.();
+					};
+					const finish = (action) => {
+						if (settled) return;
+						settled = true;
+						completion = action;
+						finalize();
+					};
+					const fail = (reason, message, cause) => {
+						finish(() => reject(promptError(reason, prompt, message, cause)));
+					};
+					const handleKeypress = async (character, key = {}) => {
+						if (settled) return;
+						if (key.ctrl && key.name === "c" || key.name === "escape") {
+							fail("cancelled", "Prompt cancelled");
+							return;
+						}
+						if (key.ctrl && key.name === "d") {
+							fail("eof", "Prompt input ended before a value was submitted");
+							return;
+						}
+						try {
+							const value = accept(character ?? "", key);
+							if (value !== void 0) {
+								finish(() => resolve(value));
+								return;
+							}
+							const state = update(character ?? "", key);
+							if (state) await this.#print(state, prompt);
+						} catch (cause) {
+							if (cause instanceof HackshPromptError) finish(() => reject(cause));
+							else fail("input-error", "Prompt input could not be processed", cause);
+						}
+					};
+					const drainKeys = async () => {
+						if (draining || finalized) return;
+						draining = true;
+						try {
+							while (queuedKeys.length > 0) {
+								if (settled) {
+									this.#bufferedKeys.push(...queuedKeys.splice(0));
+									break;
+								}
+								const next = queuedKeys.shift();
+								await handleKeypress(next.character, next.key);
+							}
+						} finally {
+							draining = false;
+							finalize();
+						}
+					};
+					const onKeypress = (character, key = {}) => {
+						queuedKeys.push({
+							character,
+							key
+						});
+						drainKeys().catch((cause) => fail("input-error", "Prompt input could not be processed", cause));
+					};
+					const onEnd = () => fail("eof", "Prompt input ended before a value was submitted");
+					const onError = (cause) => fail("input-error", "Prompt input failed", cause);
+					const onData = (chunk) => {
+						if (typeof chunk === "string" || chunk instanceof Uint8Array) keypressInput.write(chunk);
+						else fail("input-error", "Prompt input produced a non-byte value");
+					};
+					const cleanup = () => {
+						keypressInput.removeListener("keypress", onKeypress);
+						keypressInput.destroy();
+						input.removeListener("data", onData);
+						input.removeListener("end", onEnd);
+						input.removeListener("close", onEnd);
+						input.removeListener("error", onError);
+					};
+					keypressInput.on("keypress", onKeypress);
+					input.on("data", onData);
+					input.on("end", onEnd);
+					input.on("close", onEnd);
+					input.on("error", onError);
+					input.resume();
+					drainKeys().catch((cause) => fail("input-error", "Prompt input could not be processed", cause));
+				})
+			};
+		} catch (cause) {
+			outcome = {
+				ok: false,
+				error: cause instanceof HackshPromptError ? cause : promptError("input-error", prompt, "Prompt input could not be initialized", cause)
+			};
+		}
+		let restoreError;
+		try {
+			if (rawChanged) input.setRawMode?.(false);
+			if (!originallyFlowing) input.pause();
+		} catch (cause) {
+			restoreError = promptError("input-error", prompt, "Prompt input could not be restored", cause);
+		}
+		const closeWithFailure = async (failure) => {
+			try {
+				await this.#print(closed(), prompt);
+			} catch {} finally {
+				this.#active = false;
+			}
+			throw failure;
+		};
+		if (restoreError) return closeWithFailure(restoreError);
+		if (!outcome.ok) return closeWithFailure(outcome.error);
+		try {
+			await this.#print(submitted(outcome.value), prompt);
+			return outcome.value;
+		} catch (error) {
+			try {
+				await this.#print(closed(), prompt);
+			} catch {}
+			throw error;
+		} finally {
+			this.#active = false;
+		}
+	}
+	async select(options) {
+		const choices = Array.isArray(options?.options) ? options.options.map((option) => typeof option === "object" && option !== null && typeof option.value === "string" ? option.value : "[Invalid choice]") : [];
+		const prompt = details$1("select", options?.message, choices);
+		validateMessage("select", options?.message, choices);
+		if (!Array.isArray(options.options) || options.options.length === 0) throw promptError("invalid-options", prompt, "A select prompt requires at least one choice");
+		const seen = /* @__PURE__ */ new Set();
+		for (const option of options.options) {
+			if (typeof option !== "object" || option === null || typeof option.value !== "string" || option.value.length === 0 || option.label !== void 0 && typeof option.label !== "string" || option.hint !== void 0 && typeof option.hint !== "string") throw promptError("invalid-options", prompt, "Select choices must have valid string values");
+			if (seen.has(option.value)) throw promptError("invalid-options", prompt, `Duplicate select choice: ${option.value}`);
+			seen.add(option.value);
+		}
+		let selected = options.initialValue === void 0 ? 0 : choices.indexOf(options.initialValue);
+		if (selected < 0) throw promptError("invalid-options", prompt, `Unknown initial select value: ${String(options.initialValue)}`);
+		const state = (status = "active") => ({
+			kind: "select",
+			message: options.message,
+			status,
+			value: options.options[selected].value,
+			choices: options.options.map(({ value, label, hint }, index) => ({
+				value,
+				label: label ?? value,
+				...hint === void 0 ? {} : { hint },
+				selected: index === selected
+			}))
+		});
+		return await this.#run(prompt, state(), (_character, key) => key.name === "return" || key.name === "enter" ? options.options[selected].value : void 0, (_character, key) => {
+			if (key.name !== "up" && key.name !== "down") return void 0;
+			selected = (selected + (key.name === "up" ? -1 : 1) + options.options.length) % options.options.length;
+			return state();
+		}, () => state("submitted"), () => state("closed"));
+	}
+	async confirm(options) {
+		const prompt = details$1("confirm", options?.message);
+		validateMessage("confirm", options?.message);
+		if (options.initialValue !== void 0 && typeof options.initialValue !== "boolean") throw promptError("invalid-options", prompt, "Confirm initialValue must be a boolean");
+		const value = options.initialValue ?? false;
+		const state = (result, status = "active") => ({
+			kind: "confirm",
+			message: options.message,
+			status,
+			value: result,
+			...options.initialValue === void 0 ? {} : { defaultValue: options.initialValue }
+		});
+		return await this.#run(prompt, state(value), (character, key) => {
+			if (key.name === "return" || key.name === "enter") return value;
+			if (character.toLowerCase() === "y") return true;
+			if (character.toLowerCase() === "n") return false;
+		}, () => void 0, (submitted) => state(submitted, "submitted"), () => state(value, "closed"));
+	}
+	async text(options) {
+		const prompt = details$1("text", options?.message);
+		validateMessage("text", options?.message);
+		if (options.placeholder !== void 0 && typeof options.placeholder !== "string") throw promptError("invalid-options", prompt, "Text placeholder must be a string");
+		if (options.validate !== void 0 && typeof options.validate !== "function") throw promptError("invalid-options", prompt, "Text validate must be a function");
+		let value = "";
+		let validationError;
+		const state = (status = validationError ? "error" : "active") => ({
+			kind: "text",
+			message: options.message,
+			status,
+			value,
+			...options.placeholder === void 0 ? {} : { placeholder: options.placeholder },
+			...validationError === void 0 ? {} : { error: validationError }
+		});
+		return await this.#run(prompt, state(), (_character, key) => {
+			if (key.name !== "return" && key.name !== "enter") return void 0;
+			let error;
+			try {
+				error = options.validate?.(value);
+			} catch (cause) {
+				throw promptError("input-error", prompt, "Text validation failed", cause);
+			}
+			if (error !== void 0 && typeof error !== "string") throw promptError("input-error", prompt, "Text validation must return a string or undefined");
+			validationError = error || void 0;
+			return validationError === void 0 ? value : void 0;
+		}, (character, key) => {
+			if (key.name === "return" || key.name === "enter") return state();
+			validationError = void 0;
+			if (key.name === "backspace") value = Array.from(value).slice(0, -1).join("");
+			else if (!key.ctrl && !key.meta && character.length > 0) value += character;
+			else return void 0;
+			return state();
+		}, () => state("submitted"), () => state("closed"));
+	}
+};
+//#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)
+	});
+	return createBoundLogger(printer, [...category], {}, prompts);
+}
+//#endregion
+//#region src/output.ts
+function consoleWriter(method, stream) {
+	return {
+		get isTTY() {
+			return stream.isTTY;
+		},
+		get columns() {
+			return stream.columns;
+		},
+		write(text) {
+			if (!text.endsWith("\n")) return stream.write(text);
+			console[method](text.slice(0, -1));
+		}
+	};
+}
+/** Resolve the automatic output policy and select its printer for one operation. */
+function selectOutputPrinter(options, override, resolvedMode) {
+	const stdin = options.stdin ?? process.stdin;
+	const stdout = options.stdout ?? process.stdout;
+	const stderr = options.stderr ?? process.stderr;
+	const mode = resolvedMode ?? resolveOutputMode({
+		output: options.output,
+		env: options.env,
+		inputIsTTY: stdin.isTTY,
+		outputIsTTY: stdout.isTTY
+	});
+	if (override) return override;
+	if (mode.format === "json") return createJsonPrinter({
+		stdout,
+		stderr
+	});
+	const useConsole = options.stdout === void 0 && options.stderr === void 0;
+	return createPrettyPrinter({
+		color: mode.color,
+		unicode: options.unicode ?? true,
+		stdout: options.stdout ?? (useConsole ? consoleWriter("log", stdout) : stdout),
+		stderr: options.stderr ?? (useConsole ? consoleWriter("error", process.stderr) : stderr)
+	});
+}
+//#endregion
 //#region src/usage.ts
 function details(description, required, defaultValue, choices) {
 	const parts = [description];
@@ -372,64 +1345,118 @@ function formatDefault(value) {
 	if (typeof value === "string") return value;
 	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return value.toString();
 	if (value === null) return "null";
-	return JSON.stringify(value) ?? "undefined";
+	try {
+		return JSON.stringify(value) ?? "undefined";
+	} catch {
+		return "[Unserializable]";
+	}
 }
 function heading(command) {
 	const identity = command.name ? `${command.name}${command.version ? ` v${command.version}` : ""}` : command.version ? `v${command.version}` : void 0;
 	if (command.description && identity) return `${command.description} (${identity})`;
 	return command.description ?? identity;
 }
-function formatUsage(command) {
-	const lines = [];
-	const title = heading(command);
-	if (title) lines.push(title, "");
+/** Build a serializable help summary without retaining command or schema objects. */
+function summarizeUsage(command) {
 	const shape = command.args ? schemaShape(command.args) : {};
 	const positionals = readPositionals(shape);
-	const items = positionals?.items ?? [];
-	const rest = positionals?.rest;
-	const syntax = items.map(({ schema, label }) => readArgInfo(schema).required ? `<${label}>` : `[${label}]`);
-	if (rest) syntax.push(`[${rest.label}...]`);
+	const positionalItems = positionals?.items ?? [];
+	const syntax = positionalItems.map(({ schema, label }) => readArgInfo(schema).required ? `<${label}>` : `[${label}]`);
+	if (positionals?.rest) syntax.push(`[${positionals.rest.label}...]`);
 	if (command.subCommands && Object.keys(command.subCommands).length > 0) syntax.push("<COMMAND>");
-	lines.push(`USAGE ${command.name ?? "command"} [OPTIONS]${syntax.length ? ` ${syntax.join(" ")}` : ""}`);
-	if (items.length > 0 || rest) {
+	const args = positionalItems.map(({ schema, label }) => {
+		const info = readArgInfo(schema);
+		return {
+			name: label,
+			required: info.required,
+			variadic: false,
+			...info.description === void 0 ? {} : { description: info.description },
+			...info.choices === void 0 ? {} : { choices: info.choices },
+			...info.defaultValue === void 0 ? {} : { defaultValue: summarizeErrors(info.defaultValue) }
+		};
+	});
+	if (positionals?.rest) {
+		const info = readArgInfo(positionals.rest.schema);
+		args.push({
+			name: positionals.rest.label,
+			required: false,
+			variadic: true,
+			...info.description === void 0 ? {} : { description: info.description },
+			...info.choices === void 0 ? {} : { choices: info.choices }
+		});
+	}
+	const options = Object.entries(shape).filter(([key]) => key !== "_").map(([key, schema]) => {
+		const info = readArgInfo(schema);
+		const argOptions = command.argOptions?.[key];
+		const aliases = argOptions?.alias ? aliasList(argOptions.alias).map((item) => `-${item}`) : [];
+		const name = kebabCase(key);
+		const valueName = argOptions?.valueName ?? name;
+		return {
+			name,
+			flags: [...aliases, `--${name}`],
+			takesValue: info.takesValue,
+			required: info.required,
+			...info.takesValue ? { valueName } : {},
+			...info.description === void 0 ? {} : { description: info.description },
+			...info.choices === void 0 ? {} : { choices: info.choices },
+			...info.defaultValue === void 0 ? {} : { defaultValue: summarizeErrors(info.defaultValue) },
+			...argOptions?.negatedDescription === void 0 ? {} : { negatedDescription: argOptions.negatedDescription }
+		};
+	});
+	const commands = Object.entries(command.subCommands ?? {}).filter(([, child]) => !child.hidden).map(([name, child]) => ({
+		name,
+		...child.description === void 0 ? {} : { description: child.description }
+	}));
+	const name = command.name ?? "command";
+	const title = heading(command);
+	return {
+		name,
+		...title === void 0 ? {} : { heading: title },
+		...command.version === void 0 ? {} : { version: command.version },
+		...command.description === void 0 ? {} : { description: command.description },
+		synopsis: `${name} [OPTIONS]${syntax.length ? ` ${syntax.join(" ")}` : ""}`,
+		arguments: args,
+		options,
+		commands
+	};
+}
+function formatUsage(summary) {
+	const lines = [];
+	if (summary.heading) lines.push(summary.heading, "");
+	lines.push(`USAGE ${summary.synopsis}`);
+	if (summary.arguments.length > 0) {
 		lines.push("", "ARGUMENTS", "");
-		for (const { schema, label } of items) {
-			const info = readArgInfo(schema);
-			lines.push(`  ${label}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd());
-		}
-		if (rest) {
-			const info = readArgInfo(rest.schema);
-			lines.push(`  ${rest.label}...  ${details(info.description, false, void 0, info.choices)}`.trimEnd());
-		}
+		for (const argument of summary.arguments) lines.push(`  ${argument.name}${argument.variadic ? "..." : ""}  ${details(argument.description, argument.required, argument.defaultValue, argument.choices)}`.trimEnd());
 	}
-	const options = Object.entries(shape).filter(([key]) => key !== "_");
-	if (options.length > 0) {
+	if (summary.options.length > 0) {
 		lines.push("", "OPTIONS", "");
-		for (const [key, schema] of options) {
-			const info = readArgInfo(schema);
-			const argOptions = command.argOptions?.[key];
-			const prefix = argOptions?.alias ? `${aliasList(argOptions.alias).map((item) => `-${item}`).join(", ")}, ` : "";
-			const valueName = argOptions?.valueName ?? kebabCase(key);
-			const long = `--${kebabCase(key)}${info.takesValue ? `=<${valueName}>` : ""}`;
-			lines.push(`  ${prefix}${long}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd());
-			if (!info.takesValue && argOptions?.negatedDescription) lines.push(`  --no-${kebabCase(key)}  ${argOptions.negatedDescription}`);
+		for (const option of summary.options) {
+			const flags = option.flags.map((flag) => flag.startsWith("--") && option.takesValue ? `${flag}=<${option.valueName}>` : flag);
+			lines.push(`  ${flags.join(", ")}  ${details(option.description, option.required, option.defaultValue, option.choices)}`.trimEnd());
+			if (!option.takesValue && option.negatedDescription) lines.push(`  --no-${option.name}  ${option.negatedDescription}`);
 		}
 	}
-	const visibleSubCommands = Object.entries(command.subCommands ?? {}).filter(([, child]) => !child.hidden);
-	if (visibleSubCommands.length > 0) {
+	if (summary.commands.length > 0) {
 		lines.push("", "COMMANDS", "");
-		for (const [name, child] of visibleSubCommands) lines.push(`  ${name}  ${child.description ?? ""}`.trimEnd());
+		for (const command of summary.commands) lines.push(`  ${command.name}  ${command.description ?? ""}`.trimEnd());
 	}
 	return lines.join("\n");
 }
 /** Generate usage text without writing to stdout or stderr. */
 async function renderUsage(command) {
-	return formatUsage(command);
+	return formatUsage(summarizeUsage(command));
 }
 /** Generate and write usage text, awaiting asynchronous writers. */
 async function showUsage(command, options = {}) {
-	const text = await renderUsage(command);
-	return (options.write ?? console.log)(text);
+	const usage = summarizeUsage(command);
+	const text = formatUsage(usage);
+	if (options.write) return options.write(text);
+	return (options.printer ?? selectOutputPrinter(options)).print({
+		type: "usage",
+		usage,
+		text,
+		stream: options.stream ?? "stdout"
+	});
 }
 //#endregion
 //#region src/run.ts
@@ -475,46 +1502,124 @@ function resolveCommand(root, rawArgs) {
 		remaining = remaining.slice(index + 1);
 	}
 }
-async function executeCommand(root, argv, displayUsage) {
+async function executeCommand(root, argv, displayUsage, printer, loggerOptions) {
 	const resolved = resolveCommand(root, argv);
 	if (resolved.segments[0]?.tokenized.version) {
-		console.log(root.version ?? "");
+		await printer.print({
+			type: "version",
+			version: root.version ?? ""
+		});
 		return;
 	}
 	if (resolved.segments.some(({ tokenized }) => tokenized.help)) {
-		await displayUsage(resolved.command, { write: (text) => console.log(text) });
+		await printUsage(displayUsage, resolved.command, printer, "stdout");
 		return;
 	}
 	for (const parent of resolved.parents) await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized);
 	const parsed = await parseCommandArgs(resolved.command, resolved.rawArgs, resolved.tokenized);
 	if (!resolved.command.run) throw new ZittyUsageError("No command specified", resolved.command);
+	const category = resolved.segments.flatMap(({ command }) => command.name === void 0 ? [] : [command.name]);
 	return resolved.command.run({
 		...parsed,
 		cmd: resolved.command,
-		rawArgs: resolved.rawArgs
+		rawArgs: resolved.rawArgs,
+		logger: createLogger(printer, category, loggerOptions)
+	});
+}
+function printUsage(displayUsage, command, printer, stream) {
+	return displayUsage(command, { write: (text) => printer.print({
+		type: "usage",
+		usage: summarizeUsage(command),
+		text,
+		stream
+	}) });
+}
+function prepareOutput(options) {
+	const input = options.stdin ?? process.stdin;
+	const mode = resolveOutputMode({
+		output: options.output,
+		env: options.env,
+		inputIsTTY: input.isTTY,
+		outputIsTTY: (options.stdout ?? process.stdout).isTTY
 	});
+	return {
+		...createPrintQueue(selectOutputPrinter(options, options.printer, mode)),
+		interactive: mode.interactive,
+		input
+	};
+}
+async function runCommand(root, argv, options = {}) {
+	const output = prepareOutput(options);
+	try {
+		return await executeCommand(root, argv, options.showUsage ?? showUsage, output.printer, {
+			interactive: output.interactive,
+			input: output.input,
+			printPrompt: (event) => output.printChecked(event)
+		});
+	} finally {
+		await output.drain();
+	}
 }
-async function runCommand(root, argv) {
-	return executeCommand(root, argv, showUsage);
+async function drainAndExit(output, code = 1) {
+	try {
+		await output.drain();
+	} finally {
+		process.exit(code);
+	}
+}
+function commandErrorExitCode(error) {
+	return error instanceof HackshPromptError && error.reason === "cancelled" ? 130 : 1;
+}
+async function reportOutputSetupError(error, options) {
+	if (options.onError) {
+		await options.onError(error);
+		return drainAndExit(createPrintQueue(options.printer ?? { print: () => void 0 }));
+	}
+	const output = createPrintQueue(options.printer ?? createJsonPrinter({
+		stdout: options.stdout ?? process.stdout,
+		stderr: options.stderr ?? process.stderr
+	}));
+	await output.printer.print({
+		type: "error",
+		error: summarizeError(error)
+	});
+	return drainAndExit(output);
 }
 async function runMain(command, options = {}) {
 	const displayUsage = options.showUsage ?? showUsage;
+	let output;
 	try {
-		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage);
+		output = prepareOutput(options);
+	} catch (error) {
+		return reportOutputSetupError(error, options);
+	}
+	try {
+		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage, output.printer, {
+			interactive: output.interactive,
+			input: output.input,
+			printPrompt: (event) => output.printChecked(event)
+		});
 	} catch (error) {
 		if (options.onError) {
 			await options.onError(error);
-			process.exit(1);
+			return drainAndExit(output, commandErrorExitCode(error));
 		}
 		try {
 			if (error instanceof ZittyUsageError) {
-				console.error(error.message);
-				await displayUsage(error.command, { write: (text) => console.error(text) });
-			} else console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+				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)
+			});
 		} finally {
-			process.exit(1);
+			await drainAndExit(output, commandErrorExitCode(error));
 		}
 	}
+	await output.drain();
 }
 function createMain(command, options = {}) {
 	return (argv) => runMain(command, argv === void 0 ? options : {
@@ -523,6 +1628,6 @@ function createMain(command, options = {}) {
 	});
 }
 //#endregion
-export { ZittyUsageError, ZittyValidationError, createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+export { HackshPromptError, ZittyUsageError, ZittyValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
 
 //# sourceMappingURL=index.js.map