hacksh 0.5.4 → 0.7.0

package/dist/index.js

@@ -1,5 +1,6 @@
 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";
 //#region src/options.ts
@@ -167,6 +168,18 @@ var HackshPromptError = class extends Error {
 		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;
+	}
+};
 function safeString$1(value, fallback) {
 	try {
 		return String(value);
@@ -630,6 +643,395 @@ async function parseArgs(command, argv, options) {
 	return (await parseCommandArgs(command, argv, tokenizeCommandArgs(command, argv), options?.env, envPath)).args;
 }
 //#endregion
+//#region src/terminal.ts
+var TerminalLock = class {
+	#owner;
+	get owner() {
+		return this.#owner;
+	}
+	acquire(owner) {
+		if (this.#owner !== void 0) return false;
+		this.#owner = owner;
+		return true;
+	}
+	release() {
+		this.#owner = void 0;
+	}
+};
+//#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, baseEnv) {
+	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(baseEnv, raw.env),
+		input,
+		reject: reject ?? true,
+		timeout: timeout === void 0 ? void 0 : readInteger(timeout, "Exec option `timeout`", 1, MAX_DELAY),
+		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;
+		}
+		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();
+		};
+		const terminate = (cause) => {
+			if (settled || outcome.cause) return;
+			outcome.cause = cause;
+			if (outcome.exit) {
+				release();
+				return;
+			}
+			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
+	};
+}
+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.env);
+	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));
+}
+//#endregion
 //#region src/serialization.ts
 function safeString(value) {
 	try {
@@ -758,7 +1160,7 @@ function isErrorLevel(level) {
 	return level === "warning" || level === "error" || level === "fatal";
 }
 function eventStream(event) {
-	if (event.type === "error") return "stderr";
+	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";
@@ -770,6 +1172,7 @@ function formatTextEvent(event) {
 		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. */
@@ -859,7 +1262,8 @@ const unicodeSymbols = {
 		usage: "◆",
 		version: "●",
 		errorEvent: "■",
-		prompt: "?"
+		prompt: "?",
+		exec: "$"
 	}
 };
 const asciiSymbols = {
@@ -876,7 +1280,8 @@ const asciiSymbols = {
 		usage: "?",
 		version: "i",
 		errorEvent: "x",
-		prompt: "?"
+		prompt: "?",
+		exec: "$"
 	}
 };
 const markStyles = {
@@ -895,7 +1300,8 @@ const markStyles = {
 	usage: "cyan",
 	version: "blue",
 	errorEvent: "red",
-	prompt: "cyan"
+	prompt: "cyan",
+	exec: "gray"
 };
 function safelyInspect(value) {
 	if (typeof value === "string") return value;
@@ -942,6 +1348,7 @@ function eventMark(event) {
 	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) {
@@ -963,6 +1370,11 @@ function eventLines(event) {
 			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) {
@@ -1075,11 +1487,12 @@ var PromptController = class {
 	#inputValue;
 	#printEvent;
 	#bufferedKeys = [];
-	#active = false;
+	#terminal;
 	constructor(options) {
 		this.#interactive = options.interactive;
 		this.#inputValue = options.input;
 		this.#printEvent = (event) => options.print(event);
+		this.#terminal = options.terminal;
 	}
 	async #print(state, prompt) {
 		try {
@@ -1093,9 +1506,8 @@ var PromptController = class {
 	}
 	async #run(prompt, initial, accept, update, submitted, closed) {
 		if (!this.#interactive) throw promptError("non-interactive", prompt, `Cannot request ${prompt.kind} input in non-interactive mode: ${prompt.message}`);
-		if (this.#active) throw promptError("overlapping", prompt, "Another prompt is already active");
 		const input = asInput(this.#inputValue, prompt);
-		this.#active = true;
+		if (!this.#terminal.acquire("prompt")) throw promptError("overlapping", prompt, this.#terminal.owner === "exec" ? "A command is using the terminal" : "Another prompt is already active");
 		let originallyFlowing = false;
 		let rawChanged = false;
 		let outcome;
@@ -1218,7 +1630,7 @@ var PromptController = class {
 			try {
 				await this.#print(closed(), prompt);
 			} catch {} finally {
-				this.#active = false;
+				this.#terminal.release();
 			}
 			throw failure;
 		};
@@ -1233,7 +1645,7 @@ var PromptController = class {
 			} catch {}
 			throw error;
 		} finally {
-			this.#active = false;
+			this.#terminal.release();
 		}
 	}
 	async select(options) {
@@ -1380,7 +1792,8 @@ function createLogger(printer, category, options) {
 	const prompts = new PromptController({
 		interactive: options.interactive,
 		input: options.input,
-		print: (event) => options.printPrompt(event)
+		print: (event) => options.printPrompt(event),
+		terminal: options.terminal
 	});
 	return createBoundLogger(printer, [...category], {}, prompts);
 }
@@ -1605,7 +2018,8 @@ function resolveCommand(root, rawArgs) {
 		remaining = remaining.slice(index + 1);
 	}
 }
-async function executeCommand(root, argv, displayUsage, printer, loggerOptions, env) {
+async function executeCommand(root, argv, displayUsage, printer, loggerOptions, execContext) {
+	const env = execContext.env ?? process.env;
 	const resolved = resolveCommand(root, argv);
 	if (resolved.segments[0]?.tokenized.version) {
 		await printer.print({
@@ -1626,7 +2040,8 @@ async function executeCommand(root, argv, displayUsage, printer, loggerOptions,
 		...parsed,
 		cmd: resolved.command,
 		rawArgs: resolved.rawArgs,
-		logger: createLogger(printer, category, loggerOptions)
+		logger: createLogger(printer, category, loggerOptions),
+		exec: createExec(execContext)
 	});
 }
 function printUsage(displayUsage, command, printer, stream) {
@@ -1647,19 +2062,32 @@ function prepareOutput(options, env) {
 	});
 	return {
 		...createPrintQueue(selectOutputPrinter(options, options.printer, mode)),
+		format: mode.format,
 		interactive: mode.interactive,
-		input
+		input,
+		terminal: new TerminalLock()
+	};
+}
+function invocationExec(output, env) {
+	return {
+		env,
+		mode: {
+			format: output.format,
+			interactive: output.interactive
+		},
+		print: (event) => output.printer.print(event),
+		terminal: output.terminal
 	};
 }
 async function runCommand(root, argv, options = {}) {
-	const env = options.env ?? process.env;
-	const output = prepareOutput(options, env);
+	const output = prepareOutput(options, options.env ?? process.env);
 	try {
 		return await executeCommand(root, argv, options.showUsage ?? showUsage, output.printer, {
 			interactive: output.interactive,
 			input: output.input,
-			printPrompt: (event) => output.printChecked(event)
-		}, env);
+			printPrompt: (event) => output.printChecked(event),
+			terminal: output.terminal
+		}, invocationExec(output, options.env));
 	} finally {
 		await output.drain();
 	}
@@ -1691,10 +2119,9 @@ async function reportOutputSetupError(error, options) {
 }
 async function runMain(command, options = {}) {
 	const displayUsage = options.showUsage ?? showUsage;
-	const env = options.env ?? process.env;
 	let output;
 	try {
-		output = prepareOutput(options, env);
+		output = prepareOutput(options, options.env ?? process.env);
 	} catch (error) {
 		return reportOutputSetupError(error, options);
 	}
@@ -1702,8 +2129,9 @@ async function runMain(command, options = {}) {
 		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage, output.printer, {
 			interactive: output.interactive,
 			input: output.input,
-			printPrompt: (event) => output.printChecked(event)
-		}, env);
+			printPrompt: (event) => output.printChecked(event),
+			terminal: output.terminal
+		}, invocationExec(output, options.env));
 	} catch (error) {
 		if (options.onError) {
 			await options.onError(error);
@@ -1733,6 +2161,6 @@ function createMain(command, options = {}) {
 	});
 }
 //#endregion
-export { HackshPromptError, HackshUsageError, HackshValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
+export { HackshExecError, HackshPromptError, HackshUsageError, HackshValidationError, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
 
 //# sourceMappingURL=index.js.map