@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/cli/retrieve.ts

@@ -15,17 +15,20 @@ import {
 	buildRetrieveFanoutErrorEnvelope,
 	describeCentrs,
 	fanoutExitCode,
+	isStreamDataLine,
 	type ResolvedRetrieveRequest,
 	type RetrieveOutputFormat,
 	type RetrieveRequest,
 	renderRetrieveEnvelope,
 	renderRetrieveFanoutEnvelope,
 	renderRetrieveStreamLine,
+	resolveRetrieveOutputFormat,
 	retrieve,
 	retrieveFanout,
 	retrieveFollow,
 	retrieveOutputFormats,
 	retrieveSample,
+	retrieveVerboseLines,
 	retrieveWait,
 	type ValidationTrace,
 	validateRetrieveRequestShape,
@@ -34,6 +37,8 @@ import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	printTextHeader,
+	printTextNotes,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -125,13 +130,13 @@ export const retrieveCommand: CliCommandMetadata = {
 		{
 			flag: "--follow",
 			description:
-				"Keep the menu's rows current over native-api `listen`: snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only.",
+				"Keep the menu's rows current over native-api `listen`: a `started` line, snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only.",
 		},
 		{
 			flag: "--sample",
 			valueName: "<interval>",
 			description:
-				"Read the menu again every interval (with a unit, e.g. `5s`): one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api.",
+				"Read the menu again every interval (with a unit, e.g. `5s`): a `started` line, one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api.",
 		},
 		{
 			flag: "--wait",
@@ -206,7 +211,7 @@ export const retrieveCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--verbose",
-			description: "Show resolved setting sources in text output.",
+			description: "Show resolved setting sources in text output, on stderr.",
 		},
 	],
 };
@@ -283,6 +288,10 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 					request?: { format?: RetrieveOutputFormat };
 				}
 			)?.request?.format ?? "text";
+		const text = resolvedFormat === "text";
+		if (text && request.verbose) {
+			printTextHeader(retrieveVerboseLines(envelope));
+		}
 		console.log(
 			renderRetrieveEnvelope(
 				envelope as Parameters<typeof renderRetrieveEnvelope>[0],
@@ -290,6 +299,7 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 				{ verbose: request.verbose },
 			),
 		);
+		if (text) printTextNotes(envelope);
 		return 0;
 	} catch (error) {
 		const format = inferRequestedFormat(args, request);
@@ -313,14 +323,12 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 				tips,
 			);
 			console.error(
-				// codeql[js/clear-text-logging] Twin of the established redacted-request dismissals: error builders carry only targetInput (host)+via (protocol); the raw password never reaches this render.
 				renderRetrieveEnvelope(envelope, format, {
 					verbose: request?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
-				// codeql[js/clear-text-logging] Same false-positive pattern: password parsed from args never reaches error.message in the text-format catch path.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -340,14 +348,21 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 
 /**
  * Every `--follow`/`--sample` envelope goes to stdout, one per line, errors
- * included; any failure sets exit 1, even after successful lines. Ctrl-C asks
- * for a bounded stop that still ends with a summary.
+ * included; any failure sets exit 1, even after successful lines. In text,
+ * stdout is data (#470, #473): only `frame`/`sample` rows go there, and the
+ * status lines, tips, warnings and errors go to stderr. Ctrl-C asks for a
+ * bounded stop that still ends with a summary.
  */
 async function runRetrieveStreamCli(
 	request: RetrieveCliArgs,
 	args: readonly string[],
 ): Promise<number> {
-	const format = inferRequestedFormat(args, request);
+	// Resolved once, up front: a config-file `CENTRS_FORMAT` is not in `args`,
+	// and follow frame lines carry no request (#462). An invalid format is
+	// reported by the stream's own error line, rendered as the args ask.
+	const format = await resolveRetrieveOutputFormat(request, Bun.env).catch(() =>
+		inferRequestedFormat(args, request),
+	);
 	const controller = new AbortController();
 	const onSigint = (): void => controller.abort();
 	process.on("SIGINT", onSigint);
@@ -357,9 +372,14 @@ async function runRetrieveStreamCli(
 		for await (const envelope of stream(request, Bun.env, {
 			signal: controller.signal,
 		})) {
-			// A config-file `CENTRS_FORMAT` is known only after resolution.
-			const resolvedFormat = envelope.meta.operation?.request.format ?? format;
-			console.log(renderRetrieveStreamLine(envelope, resolvedFormat));
+			const line = renderRetrieveStreamLine(envelope, format);
+			if (format !== "text" || isStreamDataLine(envelope)) {
+				console.log(line);
+			} else {
+				// `started` renders its own tips; the summary repeats them.
+				if (line) console.error(line);
+				printTextNotes({ warnings: envelope.warnings, tips: [] });
+			}
 			if (!envelope.ok) exitCode = 1;
 		}
 	} finally {
@@ -379,14 +399,17 @@ async function runRetrieveWaitCli(
 		const envelope = await retrieveWait(request, Bun.env, {
 			signal: controller.signal,
 		});
+		const format =
+			envelope.meta.operation?.request.format ??
+			inferRequestedFormat(args, request);
+		const text = format === "text";
+		if (text && request.verbose) {
+			printTextHeader(retrieveVerboseLines(envelope));
+		}
 		console.log(
-			renderRetrieveEnvelope(
-				envelope,
-				envelope.meta.operation?.request.format ??
-					inferRequestedFormat(args, request),
-				{ verbose: request.verbose },
-			),
+			renderRetrieveEnvelope(envelope, format, { verbose: request.verbose }),
 		);
+		if (text) printTextNotes(envelope);
 		return envelope.ok ? 0 : 1;
 	} finally {
 		process.off("SIGINT", onSigint);
@@ -423,7 +446,6 @@ async function runRetrieveFanoutCli(
 	} catch (error) {
 		const envelope = buildRetrieveFanoutErrorEnvelope(request, error);
 		console.error(
-			// codeql[js/clear-text-logging] Twin of #80/#81/#83. No secret logged: error builders carry only targetInput (host)+via (protocol); serializeCentrsError holds code/summary/remediation/context.
 			renderRetrieveFanoutEnvelope(envelope, format, {
 				verbose: request.verbose ?? false,
 			}),

package/src/cli/settings.ts

@@ -244,7 +244,6 @@ export async function runSettingsCli(args: readonly string[]): Promise<number> {
 		}
 
 		const format = parsed.format ?? "text";
-		// codeql[js/clear-text-logging] passwordSet is a has-password boolean, never the secret; the property-NAME heuristic (maybePassword) matches the field name, not its value type.
 		console.log(renderSettingsEnvelope(envelope, format));
 		return 0;
 	} catch (error) {
@@ -263,10 +262,8 @@ export async function runSettingsCli(args: readonly string[]): Promise<number> {
 			centrsError,
 		);
 		if (format === "json" || format === "yaml") {
-			// codeql[js/clear-text-logging] sink renders only a literal error string (e.g. "Missing value for --password."), never the real value; CodeQL over-taints via shared expectValue/CentrsError code.
 			console.error(renderSettingsEnvelope(envelope, format));
 		} else {
-			// codeql[js/clear-text-logging] sink renders only a literal error string (e.g. "Missing value for --password."), never the real value; CodeQL over-taints via shared expectValue/CentrsError code.
 			console.error(formatCentrsErrorText(centrsError));
 		}
 		return 1;

package/src/cli/terminal.ts

@@ -188,12 +188,10 @@ export async function runTerminalCli(args: readonly string[]): Promise<number> {
 		if (format === "json" || format === "yaml") {
 			const envelope = withTips(buildTerminalErrorEnvelope(error), tips);
 			console.error(
-				// codeql[js/clear-text-logging] CLI error renderer false positive; password reaches neither the error nor the stderr renderers. Dismissed across all CLI commands.
 				format === "yaml" ? toYaml(envelope) : JSON.stringify(envelope),
 			);
 		} else {
 			console.error(
-				// codeql[js/clear-text-logging] Password parsed from args never reaches error.message in the text-format catch path; the parsed request (which holds the raw password) is never rendered.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",

package/src/cli/transfer.ts

@@ -21,12 +21,15 @@ import {
 	transferEnvelope,
 	transferFanout,
 	transferOutputFormats,
+	transferVerboseLines,
 	transferVerbs,
 } from "../index.ts";
 import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	printTextHeader,
+	printTextNotes,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -167,7 +170,7 @@ export const transferCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--verbose",
-			description: "Show the resolved transport in text output.",
+			description: "Show the resolved transport in text output, on stderr.",
 		},
 	],
 };
@@ -206,11 +209,12 @@ export async function runTransferCli(
 		const rendered = renderTransferEnvelope(envelope, format, {
 			verbose: request.verbose,
 		});
+		if (format === "text" && request.verbose) {
+			printTextHeader(transferVerboseLines(envelope));
+		}
 		if (!envelope.ok) {
-			console.error(
-				// codeql[js/clear-text-logging] The envelope carries auth provenance only (`username`, `passwordProvided`, setting sources), never the password; see buildTransferErrorEnvelopeFromResolved.
-				format === "text" ? rendered + formatTipsText(envelope.tips) : rendered,
-			);
+			console.error(rendered);
+			if (format === "text") printTextNotes(envelope);
 			return 1;
 		}
 		// A download to stdout (`local === "-"`) has already streamed the file bytes
@@ -221,6 +225,7 @@ export async function runTransferCli(
 		} else {
 			console.log(rendered);
 		}
+		if (format === "text") printTextNotes(envelope);
 		return 0;
 	} catch (error) {
 		// Drop credential fields before any renderer touches the request: error
@@ -243,14 +248,12 @@ export async function runTransferCli(
 				tips,
 			);
 			console.error(
-				// codeql[js/clear-text-logging] The transfer error path redacts password/cdbPassword before any renderer (redactTransferRequest), and buildTransferErrorEnvelope only emits targetInput.
 				renderTransferEnvelope(envelope, format, {
 					verbose: safeRequest?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
-				// codeql[js/clear-text-logging] Credentials are redacted from the request before rendering (redactTransferRequest) and never reach the error/stderr; same known false positive dismissed across all CLI commands.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -297,7 +300,6 @@ async function runTransferFanoutCli(
 			error,
 		);
 		console.error(
-			// codeql[js/clear-text-logging] No secret logged: request is redactTransferRequest'd (password/cdbPassword stripped) before the builder; fan-out error meta is {target:{},via,settings:{}}.
 			renderTransferFanoutEnvelope(envelope, format, {
 				verbose: request.verbose ?? false,
 			}),

package/src/cli/version.ts

@@ -0,0 +1,87 @@
+/**
+ * `centrs --version` / `-V` (#463): the package version, for scripts, agents and
+ * field reports.
+ *
+ * Text output is the bare version string (`0.1.9-next.0`), so a script can use
+ * it as is. `--json` / `--format json|yaml` return the standard envelope with
+ * `data.version`. Format comes from flags only, never `CENTRS_FORMAT`, so a
+ * plain `centrs --version` always prints the bare string.
+ */
+
+import type { CentrsEnvelope } from "../core/envelope.ts";
+import { centrsVersion } from "../core/version.ts";
+import { toYaml } from "../core/yaml.ts";
+import { CentrsError, formatCentrsErrorText } from "../errors.ts";
+
+const versionFormats = ["text", "json", "yaml"] as const;
+type VersionFormat = (typeof versionFormats)[number];
+
+export type VersionEnvelope = CentrsEnvelope<
+	{ version: string },
+	{ command: "version" }
+>;
+
+export function versionEnvelope(): VersionEnvelope {
+	return {
+		ok: true,
+		data: { version: centrsVersion },
+		warnings: [],
+		tips: [],
+		meta: {
+			target: {},
+			via: null,
+			settings: {},
+			operation: { command: "version" },
+		},
+	};
+}
+
+function parseVersionFormat(args: readonly string[]): VersionFormat {
+	let format: VersionFormat = "text";
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--json") {
+			format = "json";
+		} else if (arg === "--yaml") {
+			format = "yaml";
+		} else if (arg === "--format") {
+			const value = args[++index];
+			if (!versionFormats.includes(value as VersionFormat)) {
+				throw new CentrsError({
+					code: "settings/invalid-format",
+					summary: `--format must be one of ${versionFormats.join(", ")}; got ${value ?? "(missing)"}.`,
+					remediation: `Choose one of ${versionFormats.join(", ")}.`,
+					context: { format: value },
+				});
+			}
+			format = value as VersionFormat;
+		} else {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `\`centrs --version\` takes only an output format; got ${arg}.`,
+				remediation:
+					"Run `centrs --version`, or `centrs --version --json` for the envelope.",
+				context: { arg },
+			});
+		}
+	}
+	return format;
+}
+
+export function runVersionCli(args: readonly string[]): number {
+	let format: VersionFormat;
+	try {
+		format = parseVersionFormat(args);
+	} catch (error) {
+		console.error(formatCentrsErrorText(error as CentrsError));
+		return 1;
+	}
+	if (format === "json") {
+		console.log(JSON.stringify(versionEnvelope(), null, 2));
+	} else if (format === "yaml") {
+		console.log(toYaml(versionEnvelope()));
+	} else {
+		console.log(centrsVersion);
+	}
+	return 0;
+}

package/src/cli.ts

@@ -12,6 +12,7 @@ import { retrieveCommand, runRetrieveCli } from "./cli/retrieve.ts";
 import { runSettingsCli, settingsCommand } from "./cli/settings.ts";
 import { runTerminalCli, terminalCommand } from "./cli/terminal.ts";
 import { runTransferCli, transferCommand } from "./cli/transfer.ts";
+import { runVersionCli } from "./cli/version.ts";
 import { asCentrsError, formatCentrsErrorText } from "./errors.ts";
 import { describeCentrs, plannedProtocols, plannedSurfaces } from "./index.ts";
 
@@ -48,7 +49,7 @@ export function renderCliHelp(): string {
 			(command) => `  ${command.name.padEnd(12)} ${command.summary}`,
 		),
 		"",
-		"Use `centrs <command> --help` for command-specific options.",
+		"Use `centrs <command> --help` for command-specific options, and `centrs --version` (`-V`) for the version alone.",
 	].join("\n");
 }
 
@@ -60,6 +61,9 @@ export async function runCli(
 			console.log(renderCliHelp());
 			return 0;
 		}
+		if (args[0] === "--version" || args[0] === "-V") {
+			return runVersionCli(args.slice(1));
+		}
 
 		const [command, ...rest] = args;
 		if (command === "retrieve") {
@@ -122,7 +126,6 @@ export async function runCli(
 		}
 
 		console.error(
-			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			formatCentrsErrorText(
 				asCentrsError(new Error(`Unknown centrs command: ${command}`), {
 					code: "input/invalid-command",
@@ -137,7 +140,6 @@ export async function runCli(
 		// to a structured envelope, so reaching here means an unconverted throw
 		// escaped. Never let a raw stack trace reach the user.
 		console.error(
-			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			formatCentrsErrorText(
 				asCentrsError(error, {
 					code: "internal/unhandled",