export type CommandResultKind = "success" | "usage_error" | "runtime_error"; export interface CommandResult { exitCode: number; kind: CommandResultKind; /** The command already emitted its structured/human output. */ presented?: boolean; } const SUCCESS_RESULT: CommandResult = { exitCode: 0, kind: "success" }; let pendingResult: CommandResult = SUCCESS_RESULT; let rootExitRequester: ((exitCode: number) => void) | undefined; let rootExitCodeSanitizer: (() => void) | undefined; export const USAGE_EXIT_CODE = 2; export class CliUsageError extends Error { readonly result: CommandResult; readonly hint?: string; readonly code: string; constructor( message = "Invalid command usage", options: { exitCode?: number; presented?: boolean; hint?: string; code?: string } = {}, ) { super(message); this.name = "CliUsageError"; this.hint = options.hint; this.code = options.code ?? "usage_error"; this.result = { exitCode: options.exitCode ?? USAGE_EXIT_CODE, kind: "usage_error", presented: options.presented, }; } } export class CliRuntimeError extends Error { readonly result: CommandResult; constructor( message = "Command failed", options: { exitCode?: number; presented?: boolean; cause?: unknown } = {}, ) { super(message, options.cause === undefined ? undefined : { cause: options.cause }); this.name = "CliRuntimeError"; this.result = { exitCode: options.exitCode ?? 1, kind: "runtime_error", presented: options.presented, }; } } /** Internal control-flow signal for an early, already-presented result. */ export class CliResultSignal extends Error { readonly result: CommandResult; constructor(result: CommandResult) { super(`CLI result ${result.exitCode}`); this.name = "CliResultSignal"; this.result = result; } } export function failCommand(exitCode = 1, cause?: unknown): never { throw new CliRuntimeError("Command failed", { exitCode, presented: true, cause }); } export function failUsage(exitCode = USAGE_EXIT_CODE): never { throw new CliUsageError("Invalid command usage", { exitCode, presented: true }); } export function finishCommand(exitCode = 0): never { throw new CliResultSignal({ exitCode, kind: exitCode === 0 ? "success" : "runtime_error", presented: true, }); } /** Record a non-fatal result while allowing output/finalizers to complete. */ export function setCommandResult(result: CommandResult): void { if (pendingResult.exitCode !== 0 && result.exitCode === 0) return; pendingResult = result; } export function setCommandExitCode(exitCode: number): void { setCommandResult({ exitCode, kind: exitCode === 0 ? "success" : "runtime_error", presented: true, }); } export function consumeCommandResult(): CommandResult { const result = pendingResult; pendingResult = SUCCESS_RESULT; return result; } /** Called only by cli.ts to retain ownership of forced process termination. */ export function registerRootExitRequester(requester: (exitCode: number) => void): void { rootExitRequester = requester; } /** Called only by cli.ts to retain ownership of process exit-code mutation. */ export function registerRootExitCodeSanitizer(sanitizer: () => void): void { rootExitCodeSanitizer = sanitizer; } /** Ask cli.ts to clear stray process exit state after a successful render. */ export function sanitizeSuccessfulExitCode(): void { rootExitCodeSanitizer?.(); } export async function outputWritten(): Promise { const written = (stream: NodeJS.WriteStream) => new Promise((resolve) => stream.write("", () => resolve())); await Promise.all([written(process.stdout), written(process.stderr)]); } let drainsToExit = false; const DRAIN_GRACE_MS = 8_000; export function drainToExit(): void { drainsToExit = true; } export interface ProcessEnd { exit(exitCode: number): void; setExitCode(exitCode: number): void; later: typeof setTimeout; } export function endProcess(exitCode: number, host: ProcessEnd): void { if (!drainsToExit) return host.exit(exitCode); host.setExitCode(exitCode); host.later(() => host.exit(exitCode), DRAIN_GRACE_MS).unref(); } /** Ask cli.ts to finalize telemetry/output and then terminate the process. */ export function requestCliExit(exitCode = 0): void { if (!rootExitRequester) { setCommandResult({ exitCode, kind: exitCode === 0 ? "success" : "runtime_error", presented: true, }); return; } rootExitRequester(exitCode); } type UnrefableTimer = { unref: () => void; }; function isUnrefableTimer( timer: ReturnType, ): timer is ReturnType & UnrefableTimer { return ( typeof timer === "object" && timer !== null && "unref" in timer && typeof timer.unref === "function" ); } /** For a command whose result is out: ends the process if anything it started is still holding it. */ export function scheduleCliExit(exitCode = 0): void { const timer = setTimeout(() => requestCliExit(exitCode), 100); if (isUnrefableTimer(timer)) timer.unref(); }