The Open Standard for Generative UI
import spawn from "cross-spawn";
import { QUIET_COMMAND_CAPTURE_LIMIT } from "./command-output";
import { withSpinner } from "./spinner";
const DIAGNOSTIC_TAIL_LIMIT = 16 * 1024;
export type CommandResult = {
durationMs: number;
status: number | null;
signal: NodeJS.Signals | null;
error?: Error;
diagnosticTail: string;
};
/** Quiet npm/npx progress when we spawn a nested package-manager CLI. */
export function mutedNpmEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
return {
...base,
npm_config_loglevel: "error",
NPM_CONFIG_LOGLEVEL: "error",
};
}
export type RunCommandOptions = {
env?: NodeJS.ProcessEnv;
/** When false, capture stdout/stderr without writing them to the parent. Default true. */
echo?: boolean;
/** Default inherit so interactive CLIs can prompt. Use ignore for login probes. */
stdin?: "inherit" | "ignore";
/** Inherit stdout/stderr so the child sees a TTY (needed for `vercel login`). */
inheritOutput?: boolean;
/** Max bytes retained in `diagnosticTail` when output is piped. Default 16KiB. */
captureLimit?: number;
};
/**
* `spawn.sync(..., { stdio: "inherit" })` exposes exit status but not the output
* needed to distinguish dependency, workspace, and package-compatibility failures.
* This runner preserves normal terminal streaming while retaining only a bounded
* local tail for allowlisted classification. The tail must never be sent to telemetry.
*
* Running asynchronously also lets the parent forward SIGINT/SIGTERM, wait for the
* child to close, and return cancellation metadata before telemetry is flushed.
*/
export function runCommand(
command: string,
args: string[],
cwd: string,
options: RunCommandOptions = {},
): Promise<CommandResult> {
return new Promise((resolve) => {
const startedAt = Date.now();
const echo = options.echo !== false;
const inheritOutput = Boolean(options.inheritOutput);
const captureLimit = options.captureLimit ?? DIAGNOSTIC_TAIL_LIMIT;
const child = spawn(command, args, {
cwd,
env: options.env,
stdio: [
options.stdin === "ignore" ? "ignore" : "inherit",
inheritOutput ? "inherit" : "pipe",
inheritOutput ? "inherit" : "pipe",
],
});
let diagnosticTail = "";
let settled = false;
let forwardedSignal: NodeJS.Signals | null = null;
let forceKillTimer: NodeJS.Timeout | undefined;
const observe = (chunk: Buffer) => {
diagnosticTail = (diagnosticTail + chunk.toString("utf8")).slice(-captureLimit);
};
if (!inheritOutput) {
child.stdout?.on("data", (chunk: Buffer) => {
if (echo) process.stdout.write(chunk);
observe(chunk);
});
child.stderr?.on("data", (chunk: Buffer) => {
if (echo) process.stderr.write(chunk);
observe(chunk);
});
}
const finish = (result: Omit<CommandResult, "diagnosticTail" | "durationMs">) => {
if (settled) return;
settled = true;
process.off("SIGINT", onSigint);
process.off("SIGTERM", onSigterm);
if (forceKillTimer) clearTimeout(forceKillTimer);
resolve({
...result,
diagnosticTail,
durationMs: Math.max(0, Date.now() - startedAt),
});
};
// Prevent the parent from exiting before the child reports which signal stopped it.
const forwardSignal = (signal: NodeJS.Signals) => {
if (forwardedSignal) {
child.kill("SIGKILL");
return;
}
forwardedSignal = signal;
child.kill(signal);
// Do not hang indefinitely when a child ignores the forwarded signal.
forceKillTimer = setTimeout(() => child.kill("SIGKILL"), 5000);
forceKillTimer.unref();
};
const onSigint = () => forwardSignal("SIGINT");
const onSigterm = () => forwardSignal("SIGTERM");
process.on("SIGINT", onSigint);
process.on("SIGTERM", onSigterm);
child.once("error", (error) => finish({ status: null, signal: forwardedSignal, error }));
child.once("close", (status, signal) => finish({ status, signal: forwardedSignal ?? signal }));
});
}
export type QuietCommandOptions = {
command: string;
args: string[];
cwd: string;
label: string;
env?: NodeJS.ProcessEnv;
captureLimit?: number;
};
/** Run a command with output captured and a spinner in the terminal. */
export async function runQuietCommand(opts: QuietCommandOptions): Promise<CommandResult> {
return withSpinner(opts.label, () =>
runCommand(opts.command, opts.args, opts.cwd, {
echo: false,
stdin: "ignore",
captureLimit: opts.captureLimit ?? QUIET_COMMAND_CAPTURE_LIMIT,
env: opts.env,
}),
);
}