@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/cli/api.ts

@@ -4,6 +4,7 @@ import {
 	apiEnvelope,
 	apiOutputFormats,
 	apiStream,
+	apiVerboseLines,
 	buildApiErrorEnvelope,
 	normalizeApiEndpoint,
 	removedListenError,
@@ -26,6 +27,8 @@ import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	printTextHeader,
+	printTextNotes,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -106,7 +109,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--stream",
 			description:
-				"Stream the command's native replies (`!re` rows and `!empty`) as NDJSON, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it.",
+				"Stream the command's native replies (`!re` rows and `!empty`) as NDJSON: a `started` line, a line per reply, then a summary envelope. Never changes the command: a GET streams one print. To follow changes, request `<menu>/listen`, which implies it.",
 		},
 		{
 			flag: "--count",
@@ -190,7 +193,7 @@ export const apiCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--verbose",
-			description: "Include additional context in text output.",
+			description: "Include additional context in text output, on stderr.",
 		},
 	],
 };
@@ -542,16 +545,22 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			)?.request?.format ??
 			parsed.format ??
 			"json";
+		// `--raw` is a bare payload by contract; `--json` carries the notes.
+		const text = resolvedFormat === "text" && !parsed.raw;
+		if (text && parsed.verbose) {
+			printTextHeader(apiVerboseLines(envelope));
+		}
 		const rendered = renderApiEnvelope(envelope, resolvedFormat, {
 			raw: parsed.raw,
 			verbose: parsed.verbose,
 		});
 		if (envelope.ok) {
 			console.log(rendered);
-			return 0;
+		} else {
+			console.error(rendered);
 		}
-		console.error(rendered);
-		return 1;
+		if (text) printTextNotes(envelope);
+		return envelope.ok ? 0 : 1;
 	} catch (error) {
 		const format = inferApiFormat(args, parsed);
 		const tips = isMissingTargetError(error)
@@ -566,7 +575,6 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			// missing `--input` file) instead of falling back to plain text.
 			const envelope = withTips(buildApiErrorEnvelope(parsed, error), tips);
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				renderApiEnvelope(envelope, format, {
 					raw: true,
 					verbose: parsed.verbose ?? false,
@@ -578,14 +586,12 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				tips,
 			);
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				renderApiEnvelope(envelope, format, {
 					verbose: parsed?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
-				// codeql[js/clear-text-logging] CLI catch-block error render. No secret logged: envelope stores only passwordProvided (boolean) and target.input (router, not the password).
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -659,7 +665,6 @@ async function runApiFanoutCli(
 			Bun.env,
 		);
 		console.error(
-			// codeql[js/clear-text-logging] Fan-out CLI catch-block error render — twin of #80/#81. No secret logged: the error envelope's request summary, selection and target carry no auth fields; serializeCentrsError holds only code/summary/remediation/context.
 			renderApiFanoutEnvelope(envelope, format, {
 				verbose: parsed.verbose ?? false,
 			}),
@@ -679,8 +684,9 @@ function endpointInfersListen(endpoint: string): boolean {
 
 /**
  * Emit all structured stream outcomes on stdout. Any failure sets exit 1,
- * including a terminal error after successful rows. Raw mode retains its
- * stderr error contract; Ctrl-C requests bounded cancellation.
+ * including a terminal error after successful rows. Text puts only frame rows
+ * on stdout; raw mode retains its stderr error contract; Ctrl-C requests
+ * bounded cancellation.
  */
 async function runApiStreamCli(
 	parsed: ApiCliArgs,
@@ -697,17 +703,25 @@ async function runApiStreamCli(
 			Bun.env,
 			controller.signal,
 		)) {
-			// `--raw` is bare payloads only; a notice has none.
-			if (parsed.raw && envelope.meta.operation?.stream?.kind === "notice")
-				continue;
+			const kind = envelope.ok
+				? envelope.meta.operation?.stream?.kind
+				: undefined;
+			// `--raw` is bare payloads only; `started` has none.
+			if (parsed.raw && kind === "started") continue;
 			const line = renderApiStreamLine(envelope, format, {
 				raw: parsed.raw,
 				verbose: parsed.verbose,
 			});
-			if (envelope.ok || !parsed.raw) {
+			if (parsed.raw) {
+				if (envelope.ok) console.log(line);
+				else console.error(line);
+			} else if (format !== "text" || kind === "frame") {
 				console.log(line);
 			} else {
-				console.error(line);
+				// Text stdout is data (#470, #473): status lines, tips, warnings
+				// and errors go to stderr. `started` renders its own tips.
+				if (line) console.error(line);
+				printTextNotes({ warnings: envelope.warnings, tips: [] });
 			}
 			if (!envelope.ok) exitCode = 1;
 		}

package/src/cli/common.ts

@@ -6,7 +6,51 @@
  * together.
  */
 
-import { CentrsError } from "../errors.ts";
+import type { Tip, Warning } from "../core/envelope.ts";
+import { CentrsError, terminalSafeLine } from "../errors.ts";
+import { redactTargetInput } from "../resolver/target.ts";
+import { formatTipsText } from "./missing-target.ts";
+
+/**
+ * Warnings that a single-target text-mode CLI leaves out (#470).
+ * `transport/provider-trust` rides every quickchr run over TLS or SSH, so
+ * printing it would be noise. `--json` keeps every warning.
+ */
+const TEXT_QUIET_WARNING_CODES: readonly string[] = [
+	"transport/provider-trust",
+];
+
+/**
+ * One `warning [<code>]: <message>` line per envelope warning, in the same form
+ * as fan-out text, minus {@link TEXT_QUIET_WARNING_CODES}.
+ */
+export function textWarningLines(warnings: readonly Warning[]): string[] {
+	return warnings
+		.filter((warning) => !TEXT_QUIET_WARNING_CODES.includes(warning.code))
+		.map((warning) =>
+			terminalSafeLine(`warning [${warning.code}]: ${warning.message}`),
+		);
+}
+
+/**
+ * #470: in text mode a single-target command's stdout is its data and nothing
+ * else. The notes around the data go to stderr: the `--verbose` header before
+ * it ({@link printTextHeader}), then warnings and tips after it. This applies
+ * on success and on failure, so a write whose outcome is unknown still says so.
+ */
+export function printTextNotes(envelope: {
+	warnings: readonly Warning[];
+	tips: readonly Tip[];
+}): void {
+	for (const line of textWarningLines(envelope.warnings)) console.error(line);
+	const tips = formatTipsText(envelope.tips);
+	if (tips) console.error(tips);
+}
+
+/** The `--verbose` header of a text-mode result, on stderr (#470). */
+export function printTextHeader(lines: readonly string[]): void {
+	if (lines.length > 0) console.error(lines.join("\n"));
+}
 
 export interface CliCommandOption {
 	flag: string;
@@ -106,6 +150,141 @@ export function unknownFlagError(
 	});
 }
 
+/** Single-quote a token for a shell line a user can copy, unless it is plain. */
+function shellQuote(token: string): string {
+	return /^[\w/:=.,@%+-]+$/.test(token)
+		? token
+		: `'${token.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * A centrs flag written after a bare `--` (#459).
+ *
+ * `--` makes every later token RouterOS input, so a trailing `--json` (the
+ * habitual position: `execute r1 -- '/cmd' --json`) went to the router and
+ * failed there as `unknown-attribute`. The RouterOS command is one quoted
+ * argument in every documented form, so a later token that is exactly one of
+ * this command's LONG flags (or its `--flag=value` spelling) is this mistake.
+ * Short aliases (`-u`, `-h`) are left alone: a lone `-x` is plausible
+ * RouterOS input, `--json` is not. A command that really needs such a token
+ * can carry it inside the quoted command.
+ *
+ * Throws `usage/flag-after-separator` with the command line rewritten with the
+ * flags (and their values) moved before `--`. Password values are never
+ * echoed. A no-op when there is no `--`.
+ */
+export function rejectFlagsAfterSeparator(
+	command: string,
+	args: readonly string[],
+	options: readonly CliCommandOption[],
+): void {
+	const optionByFlag = new Map<string, CliCommandOption>();
+	for (const option of options) {
+		for (const token of option.flag.split("/")) {
+			const trimmed = token.trim();
+			if (trimmed.startsWith("-") && trimmed !== "--") {
+				optionByFlag.set(trimmed, option);
+			}
+		}
+	}
+	let separator = -1;
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index] ?? "";
+		if (token === "--") {
+			separator = index;
+			break;
+		}
+		// A flag's value may itself be `--`; only the parser's separator counts.
+		if (optionByFlag.get(token)?.valueName !== undefined) index += 1;
+	}
+	if (separator === -1) return;
+	const secret = (flag: string) =>
+		flag.startsWith("-") && flag.includes("password");
+	const before: string[] = [];
+	for (let index = 0; index < separator; index += 1) {
+		const token = args[index] ?? "";
+		const [name = ""] = token.split("=");
+		const equal = token.indexOf("=");
+		if (equal >= 0 && optionByFlag.get(name)?.valueName !== undefined) {
+			before.push(
+				name,
+				secret(name) ? "<password>" : redactTargetInput(token.slice(equal + 1)),
+			);
+			continue;
+		}
+		if (equal >= 0 && secret(name)) {
+			before.push(`${name}=<password>`);
+			continue;
+		}
+		before.push(redactTargetInput(token));
+		if (optionByFlag.get(name)?.valueName !== undefined || secret(name)) {
+			const value = args[index + 1];
+			if (index + 1 < separator && value !== undefined) {
+				before.push(secret(name) ? "<password>" : redactTargetInput(value));
+				index += 1;
+			}
+		}
+	}
+	const unsupportedInlineBooleans: string[] = [];
+	const moved: string[] = [];
+	const kept: string[] = [];
+	const flags: string[] = [];
+	const after = args.slice(separator + 1);
+	for (let index = 0; index < after.length; index += 1) {
+		const token = after[index] ?? "";
+		const [name = "", ...valueParts] = token.split("=");
+		const option = name.startsWith("--") ? optionByFlag.get(name) : undefined;
+		if (option === undefined) {
+			kept.push(token);
+			continue;
+		}
+		flags.push(name);
+		// The parsers take a value flag's value as the next token (`--timeout 30s`,
+		// never `--timeout=30s`), so the fixed line splits it; only a boolean's
+		// supported `=` form (`--validate=no`) is kept as typed.
+		if (valueParts.length > 0) {
+			if (option.valueName === undefined) {
+				if (command !== "execute" || name !== "--validate") {
+					unsupportedInlineBooleans.push(name);
+				}
+				moved.push(token);
+			} else {
+				moved.push(name, secret(name) ? "<password>" : valueParts.join("="));
+			}
+			continue;
+		}
+		moved.push(name);
+		const value = after[index + 1];
+		if (option.valueName !== undefined && value !== undefined) {
+			moved.push(secret(name) ? "<password>" : value);
+			index += 1;
+		}
+	}
+	if (flags.length === 0) return;
+	// A moved --host value needs the same redaction as a positional target.
+	// Keep the RouterOS command itself verbatim; it is not a target.
+	const fixed = [
+		"centrs",
+		command,
+		...before,
+		...moved.map((token) => redactTargetInput(token)),
+		"--",
+		...kept,
+	]
+		.map(shellQuote)
+		.join(" ");
+	const list = flags.map((flag) => `\`${flag}\``).join(", ");
+	throw new CentrsError({
+		code: "usage/flag-after-separator",
+		summary: `${list} ${flags.length === 1 ? "comes" : "come"} after \`--\`, so ${flags.length === 1 ? "it" : "they"} would be sent to RouterOS as part of the command.`,
+		remediation:
+			unsupportedInlineBooleans.length > 0
+				? `Put centrs flags before \`--\`. These flags accept no value: ${unsupportedInlineBooleans.map((flag) => `\`${flag}\``).join(", ")}. Use a bare flag to enable it, or omit it to keep the default.`
+				: `Put centrs flags before \`--\`: \`${fixed}\``,
+		context: { flags },
+	});
+}
+
 export function renderCommandHelp(
 	describe: string,
 	command: CliCommandMetadata,

package/src/cli/devices.ts

@@ -746,10 +746,8 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 			centrsError,
 		);
 		if (format === "json" || format === "yaml") {
-			// 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.
 			console.error(renderDevicesEnvelope(envelope, format));
 		} else {
-			// 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.
 			console.error(formatCentrsErrorText(centrsError));
 		}
 		return 1;

package/src/cli/discover.ts

@@ -207,7 +207,6 @@ export async function runDiscoverCli(args: readonly string[]): Promise<number> {
 			remediation:
 				"Use `centrs discover --help` to inspect the supported flags.",
 		});
-		// 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.
 		console.error(formatCentrsErrorText(centrsError));
 		return 1;
 	}

package/src/cli/execute.ts

@@ -1,13 +1,23 @@
 import { fanoutExitCode } from "../core/fanout.ts";
-import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
 import {
 	buildExecuteErrorEnvelope,
 	type ExecuteOutputFormat,
 	type ExecuteRequest,
 	executeEnvelope,
 	executeOutputFormats,
+	executeVerboseLines,
 	renderExecuteEnvelope,
 } from "../execute.ts";
+import {
+	buildExecuteCmrErrorEnvelope,
+	executeCmr,
+	renderExecuteCmrEnvelope,
+} from "../execute-cmr.ts";
 import {
 	buildExecuteFanoutErrorEnvelope,
 	executeFanout,
@@ -18,6 +28,9 @@ import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	printTextHeader,
+	printTextNotes,
+	rejectFlagsAfterSeparator,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -54,6 +67,17 @@ export const executeCommand: CliCommandMetadata = {
 				"Pin the protocol selector; no silent downgrade when set. A bare MAC target defaults to mac-telnet.",
 		},
 		...selectionCommandOptions,
+		{
+			flag: "--cmr",
+			description:
+				"Run on CMR clients through their controller: the <target> is the controller (RouterOS 7.26beta1+, `cmr` package). Needs `--labels`; native-api or rest-api only.",
+		},
+		{
+			flag: "--labels",
+			valueName: "<expr>",
+			description:
+				"With `--cmr`: RouterOS label expression selecting clients (comma list; plain = OR, `+` AND, `-` AND NOT, `all`).",
+		},
 		{
 			flag: "--host",
 			valueName: "<host|url>",
@@ -135,24 +159,27 @@ export const executeCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--verbose",
-			description: "Include additional context in text output.",
+			description: "Include additional context in text output, on stderr.",
 		},
 		{
 			flag: "--",
 			description:
-				"End centrs option parsing: every following token is the literal RouterOS command, even flag-shaped ones (e.g. `-- /interface print where disabled=yes`).",
+				"End centrs option parsing: every following token is the literal RouterOS command (e.g. `-- /interface print where disabled=yes`). Put centrs flags before it; one of execute's own long flags after it is refused as `usage/flag-after-separator`.",
 		},
 	],
 };
 
 interface ExecuteCliArgs extends ExecuteRequest {
 	help?: boolean;
+	cmr?: boolean;
+	labels?: string;
 	format?: ExecuteOutputFormat;
 	selectionFlags?: SelectionFlags;
 	targetPositionals?: readonly string[];
 }
 
 export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
+	rejectFlagsAfterSeparator("execute", args, executeCommand.options);
 	const parsed: ExecuteCliArgs = { command: "" };
 	const selectionFlags = emptySelectionFlags();
 	const positional: string[] = [];
@@ -194,6 +221,12 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 			case "--yes":
 				parsed.yes = true;
 				break;
+			case "--cmr":
+				parsed.cmr = true;
+				break;
+			case "--labels":
+				parsed.labels = expectValue(args, ++index, arg);
+				break;
 			case "--validate":
 				parsed.validate = true;
 				break;
@@ -322,6 +355,14 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 				selectionFlags.quickchr[0] ?? "",
 			);
 		}
+		if (parsed.cmr || parsed.labels !== undefined) {
+			return await runExecuteCmrCli(
+				parsed,
+				selectionFlags,
+				targetPositionals,
+				args,
+			);
+		}
 		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
 			return await runExecuteFanoutCli(
 				parsed,
@@ -363,15 +404,20 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 			)?.request?.format ??
 			parsed.format ??
 			"text";
+		const text = resolvedFormat === "text";
+		if (text && parsed.verbose) {
+			printTextHeader(executeVerboseLines(envelope));
+		}
 		const rendered = renderExecuteEnvelope(envelope, resolvedFormat, {
 			verbose: parsed.verbose,
 		});
 		if (envelope.ok) {
 			console.log(rendered);
-			return 0;
+		} else {
+			console.error(rendered);
 		}
-		console.error(rendered);
-		return 1;
+		if (text) printTextNotes(envelope);
+		return envelope.ok ? 0 : 1;
 	} catch (error) {
 		// Parse/usage errors land here too: surface them through the same typed
 		// envelope as every other runner (no raw message, no exit code 2).
@@ -388,14 +434,12 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 				tips,
 			);
 			console.error(
-				// codeql[js/clear-text-logging] No secret reaches this sink. The tainted 'password' flows in only as provenance (SettingSource={kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 				renderExecuteEnvelope(envelope, format, {
 					verbose: parsed?.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",
@@ -441,7 +485,6 @@ async function runExecuteFanoutCli(
 	} catch (error) {
 		const envelope = buildExecuteFanoutErrorEnvelope(parsed, error);
 		console.error(
-			// codeql[js/clear-text-logging] Twin of #80/#81/#83/#84. No secret logged: buildExecuteFanoutErrorEnvelope meta is {target:{},via,settings:{}}; CodeQL taints the whole request object but the builder projects the password away.
 			renderExecuteFanoutEnvelope(envelope, format, {
 				verbose: parsed.verbose ?? false,
 			}),
@@ -450,6 +493,107 @@ async function runExecuteFanoutCli(
 	}
 }
 
+/**
+ * `execute --cmr`: the single target is the CMR controller; `--labels` picks
+ * the clients. Fan-out selectors would mix two selection sources, so they are
+ * refused rather than combined (#450).
+ */
+async function runExecuteCmrCli(
+	parsed: ExecuteCliArgs,
+	selectionFlags: SelectionFlags,
+	targetPositionals: readonly string[],
+	args: readonly string[],
+): Promise<number> {
+	const format = inferExecuteFormat(args, parsed);
+	const controller = new AbortController();
+	// First Ctrl-C cancels (unsent members become `cmr/cancelled`); a second
+	// one exits at once in case a controller call does not end promptly.
+	const onSigint = (): void => {
+		if (controller.signal.aborted) process.exit(130);
+		controller.abort();
+	};
+	process.on("SIGINT", onSigint);
+	try {
+		if (!parsed.cmr) {
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary:
+					"`--labels` selects CMR clients and only applies with `--cmr`.",
+				remediation:
+					"Add `--cmr` and name the controller as the target, or drop `--labels`.",
+			});
+		}
+		if (
+			hasTargetSelector({ ...selectionFlags, quickchr: [] }) ||
+			selectionFlags.quickchr.length > 1 ||
+			targetPositionals.length > 1
+		) {
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary:
+					"`--cmr` takes one controller target; CDB fan-out selectors and several targets cannot be combined with it.",
+				remediation:
+					"Name one controller (a positional, `--host` or one `--quickchr`) and pick clients with `--labels`.",
+				context: {
+					positionals: targetPositionals.length,
+					quickchr: selectionFlags.quickchr.length,
+				},
+			});
+		}
+		if (selectionFlags.quickchr.length === 1) {
+			parsed.quickchr = selectionFlags.quickchr[0];
+		}
+		if (
+			!parsed.targetInput &&
+			parsed.quickchr === undefined &&
+			parsed.host === undefined
+		) {
+			throw missingTargetError({
+				command: "execute",
+				summary:
+					"`centrs execute --cmr` requires the CMR controller as its <target>.",
+				remediation:
+					'Name the controller, e.g. `centrs execute ctl --cmr --labels all -- ":put ok"`.',
+			});
+		}
+		const envelope = await executeCmr({
+			...parsed,
+			labels: parsed.labels ?? "",
+			concurrency: selectionFlags.concurrency,
+			signal: controller.signal,
+		});
+		const resolvedFormat = envelope.meta.operation?.request.format ?? format;
+		console.log(
+			renderExecuteCmrEnvelope(envelope, resolvedFormat, {
+				verbose: parsed.verbose ?? false,
+			}),
+		);
+		return fanoutExitCode(envelope);
+	} catch (error) {
+		console.error(
+			renderExecuteCmrEnvelope(
+				buildExecuteCmrErrorEnvelope(
+					{ targetInput: parsed.targetInput, via: parsed.via },
+					error,
+				),
+				format,
+				{
+					verbose: parsed.verbose ?? false,
+				},
+			),
+		);
+		return 1;
+	} finally {
+		process.off("SIGINT", onSigint);
+	}
+}
+
+/**
+ * The output format for an error that may have struck before parsing finished.
+ * Reads the argv the way the parser does: only tokens before `--` (after it is
+ * RouterOS input), last format flag wins, and a value-taking flag's value is
+ * skipped, so `--format yaml -- '/x' --json` renders YAML.
+ */
 function inferExecuteFormat(
 	args: readonly string[],
 	parsed?: ExecuteCliArgs,
@@ -457,22 +601,33 @@ function inferExecuteFormat(
 	if (parsed?.format) {
 		return parsed.format;
 	}
-	if (args.includes("--json")) {
-		return "json";
-	}
-	const index = args.indexOf("--format");
-	if (index >= 0) {
-		const value = args[index + 1];
-		if (
-			value !== undefined &&
-			executeOutputFormats.includes(value as ExecuteOutputFormat)
-		) {
-			return value as ExecuteOutputFormat;
+	let format: ExecuteOutputFormat = "text";
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined || arg === "--") break;
+		if (arg === "--json") {
+			format = "json";
+		} else if (arg === "--format") {
+			const value = args[index + 1];
+			if (executeOutputFormats.includes(value as ExecuteOutputFormat)) {
+				format = value as ExecuteOutputFormat;
+			}
+			index += 1;
+		} else if (EXECUTE_VALUE_FLAGS.has(arg)) {
+			index += 1;
 		}
 	}
-	return "text";
+	return format;
 }
 
+const EXECUTE_VALUE_FLAGS: ReadonlySet<string> = new Set(
+	executeCommand.options.flatMap((option) =>
+		option.valueName === undefined
+			? []
+			: option.flag.split("/").map((token) => token.trim()),
+	),
+);
+
 function parseIntegerFlag(value: string, flag: string): number {
 	const parsed = Number.parseInt(value, 10);
 	if (!Number.isInteger(parsed)) {

package/src/cli/explain.ts

@@ -51,6 +51,7 @@ import type { ResolvedSetting } from "../resolver/settings.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
+	rejectFlagsAfterSeparator,
 	renderCommandHelp,
 	unknownFlagError,
 } from "./common.ts";
@@ -118,6 +119,7 @@ export interface ExplainCliArgs {
 }
 
 export function parseExplainCliArgs(args: readonly string[]): ExplainCliArgs {
+	rejectFlagsAfterSeparator("explain", args, explainCliCommand.options);
 	const parsed: ExplainCliArgs = {
 		positionals: [],
 		failOn: "error",

package/src/cli/mcp.ts

@@ -101,7 +101,6 @@ export async function runMcpCli(args: readonly string[]): Promise<number> {
 		return 0;
 	} catch (error) {
 		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/mcp-start",