primcli 1.34.0 → 1.36.0

package/dist/json-output-KAIuP9rG.js

@@ -0,0 +1,254 @@
+import { format } from "node:util";
+//#region src/oclif/json-output.ts
+/**
+* Parse-safe `--json` output.
+*
+* Agents often run commands with stderr merged into stdout (`2>&1`).
+* A command that prints a JSON document on stdout and a notice on
+* stderr then hands the caller text that is not JSON, and a delivered
+* send can look like an unknown outcome. With `--json`, every guarded
+* command therefore prints exactly one JSON document on stdout, on
+* success and on failure, and writes nothing to stderr:
+*
+* - Anything the command would have written to stderr (notices, hints,
+*   cursors, warnings) goes into the document's `warnings` array.
+* - A failure adds `error` and `exit_code` to the document. When the
+*   command printed no document of its own, the CLI builds one.
+* - A command whose `--json` output is a bare JSON array keeps that
+*   documented shape on success; its stderr notices are dropped.
+*
+* Commands that stream several documents (`listen`) are not guarded.
+*/
+const GUARDED = Symbol.for("primitive.cli.jsonOutputGuard");
+/** True when `--json` appears before any `--` separator. */
+function jsonOutputRequested(argv) {
+	const end = argv.indexOf("--");
+	return (end === -1 ? argv : argv.slice(0, end)).includes("--json");
+}
+function chunkToString(chunk, encoding) {
+	if (typeof chunk === "string") return chunk;
+	if (chunk instanceof Uint8Array) return Buffer.from(chunk).toString(typeof encoding === "string" ? encoding : "utf8");
+	return String(chunk);
+}
+function capturingWrite(sink) {
+	return (chunk, encoding, callback) => {
+		sink.push(chunkToString(chunk, encoding));
+		const done = typeof encoding === "function" ? encoding : callback;
+		if (typeof done === "function") done();
+		return true;
+	};
+}
+/**
+* Redirect stdout and stderr (both the streams and the console methods
+* that write to them) into memory until `restore` is called. Nested
+* captures restore in reverse order, so a guarded command that runs
+* another guarded command still produces one document.
+*/
+function captureOutput() {
+	const stdout = [];
+	const stderr = [];
+	const originalStdoutWrite = process.stdout.write;
+	const originalStderrWrite = process.stderr.write;
+	const originalConsole = {
+		debug: console.debug,
+		error: console.error,
+		info: console.info,
+		log: console.log,
+		warn: console.warn
+	};
+	const toStdout = (...args) => {
+		stdout.push(`${format(...args)}\n`);
+	};
+	const toStderr = (...args) => {
+		stderr.push(`${format(...args)}\n`);
+	};
+	process.stdout.write = capturingWrite(stdout);
+	process.stderr.write = capturingWrite(stderr);
+	console.log = toStdout;
+	console.info = toStdout;
+	console.debug = toStderr;
+	console.error = toStderr;
+	console.warn = toStderr;
+	return {
+		stderr,
+		stdout,
+		restore: () => {
+			process.stdout.write = originalStdoutWrite;
+			process.stderr.write = originalStderrWrite;
+			console.debug = originalConsole.debug;
+			console.error = originalConsole.error;
+			console.info = originalConsole.info;
+			console.log = originalConsole.log;
+			console.warn = originalConsole.warn;
+		}
+	};
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseJson(text) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Split captured stderr into an API error payload (the JSON object the
+* CLI prints for a failed request) and plain-text warning lines.
+*/
+const ANSI_SEQUENCE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[A-Za-z]`, "g");
+function stripAnsi(text) {
+	return text.replace(ANSI_SEQUENCE, "");
+}
+function summarizeStderr(chunks) {
+	let errorPayload = null;
+	const warnings = [];
+	for (const chunk of chunks) {
+		const trimmed = stripAnsi(chunk).trim();
+		if (trimmed === "") continue;
+		if (trimmed.startsWith("{")) {
+			const parsed = parseJson(trimmed);
+			if (parsed.ok && isPlainObject(parsed.value)) {
+				if (errorPayload === null) errorPayload = parsed.value;
+				else warnings.push(JSON.stringify(parsed.value));
+				continue;
+			}
+		}
+		for (const line of trimmed.split("\n")) {
+			const text = line.trim();
+			if (text !== "" && !warnings.includes(text)) warnings.push(text);
+		}
+	}
+	return {
+		errorPayload,
+		warnings
+	};
+}
+function errorExitCode(error) {
+	const exit = error?.oclif?.exit;
+	return typeof exit === "number" ? exit : void 0;
+}
+/** An oclif `this.exit(n)` unwinds by throwing; it is not a failure message. */
+function isExitSignal(error) {
+	return error?.code === "EEXIT";
+}
+function thrownErrorBody(error) {
+	if (error instanceof Error) {
+		const body = { message: error.message };
+		const code = error.code;
+		if (typeof code === "string" && code !== "EEXIT") body.code = code;
+		return body;
+	}
+	return { message: String(error) };
+}
+/**
+* Build the single JSON document a guarded `--json` command prints from
+* what it wrote to stdout and stderr and how it ended.
+*/
+function composeJsonDocument(input) {
+	const { errorPayload, warnings: stderrLines } = summarizeStderr(input.stderr);
+	const failed = input.exitCode !== 0;
+	let warnings = stderrLines;
+	if (!failed && errorPayload !== null) warnings = [...warnings, JSON.stringify(errorPayload)];
+	const failure = () => {
+		if (errorPayload !== null) return errorPayload;
+		if (input.thrown && !isExitSignal(input.thrown.error)) return thrownErrorBody(input.thrown.error);
+		return { message: warnings.at(-1) ?? `The command failed with exit code ${input.exitCode}.` };
+	};
+	const text = input.stdout.trim();
+	let document;
+	let hasDocument = false;
+	if (text !== "") {
+		const parsed = parseJson(text);
+		document = parsed.ok ? parsed.value : { output: text };
+		hasDocument = true;
+	}
+	if (!hasDocument) {
+		if (failed) return {
+			error: failure(),
+			exit_code: input.exitCode,
+			...warnings.length > 0 ? { warnings } : {}
+		};
+		return warnings.length > 0 ? { summary: warnings.join("\n") } : {};
+	}
+	if (!isPlainObject(document)) {
+		if (!failed) return document;
+		return {
+			data: document,
+			error: failure(),
+			exit_code: input.exitCode,
+			...warnings.length > 0 ? { warnings } : {}
+		};
+	}
+	const merged = { ...document };
+	const stated = new Set([merged.outcome_message, merged.summary].filter((value) => typeof value === "string"));
+	warnings = warnings.filter((warning) => !stated.has(warning));
+	if (failed) {
+		if (merged.error === void 0 || merged.error === null) merged.error = failure();
+		if (merged.exit_code === void 0) merged.exit_code = input.exitCode;
+	}
+	if (warnings.length > 0) {
+		const existing = merged.warnings;
+		if (existing === void 0 || existing === null) merged.warnings = warnings;
+		else if (Array.isArray(existing)) merged.warnings = [...existing, ...warnings.filter((warning) => !existing.includes(warning))];
+		else merged.cli_warnings = warnings;
+	}
+	return merged;
+}
+/**
+* Make `cls` print one JSON document under `--json`. Idempotent per
+* class; command aliases that share a class are guarded once.
+*/
+function guardJsonOutput(cls) {
+	const prototype = cls.prototype;
+	if (Object.hasOwn(prototype, GUARDED)) return;
+	const originalRun = prototype._run;
+	prototype[GUARDED] = true;
+	prototype._run = async function guardedRun() {
+		if (!jsonOutputRequested(this.argv)) return originalRun.call(this);
+		const capture = captureOutput();
+		let result;
+		let thrown;
+		try {
+			result = await originalRun.call(this);
+		} catch (error) {
+			thrown = { error };
+		} finally {
+			capture.restore();
+		}
+		const document = composeJsonDocument({
+			exitCode: thrown ? isExitSignal(thrown.error) ? errorExitCode(thrown.error) ?? 0 : errorExitCode(thrown.error) ?? (typeof process.exitCode === "number" && process.exitCode !== 0 ? process.exitCode : 1) : typeof process.exitCode === "number" ? process.exitCode : 0,
+			stderr: capture.stderr,
+			stdout: capture.stdout.join(""),
+			thrown
+		});
+		console.log(JSON.stringify(document, null, 2));
+		if (thrown) {
+			if (thrown.error !== null && typeof thrown.error === "object") thrown.error.skipOclifErrorHandling = true;
+			throw thrown.error;
+		}
+		return result;
+	};
+}
+/** Command ids whose `--json` streams several documents over time. */
+const STREAMING_JSON_COMMAND_IDS = new Set(["listen"]);
+/**
+* Guard every command in `commands` that accepts `--json`, except the
+* streaming ones. Called once by the command registry.
+*/
+function guardJsonOutputCommands(commands) {
+	const streaming = /* @__PURE__ */ new Set();
+	for (const id of STREAMING_JSON_COMMAND_IDS) if (commands[id] !== void 0) streaming.add(commands[id]);
+	for (const command of Object.values(commands)) {
+		if (streaming.has(command)) continue;
+		const flags = command.flags;
+		const enableJsonFlag = command.enableJsonFlag;
+		if (flags && "json" in flags || enableJsonFlag === true) guardJsonOutput(command);
+	}
+}
+//#endregion
+export { jsonOutputRequested as n, guardJsonOutputCommands as t };