@tikoci/centrs 0.1.2 → 0.1.4

package/src/cli/settings.ts

@@ -0,0 +1,286 @@
+/**
+ * `centrs settings` CLI surface: command metadata, subcommand parsing,
+ * dispatch, and error-to-envelope rendering. Core logic lives in
+ * `../settings.ts`; this file only does CLI-shaped plumbing, mirroring
+ * `./devices.ts`'s pattern for the other transport-less command.
+ *
+ * Bare `centrs settings` (no subcommand) behaves like `print` regardless of
+ * TTY — the interactive first-time-setup flow (`@clack/prompts`) is an
+ * explicitly deferred later slice (`commands/settings/README.md`), not built
+ * here.
+ */
+
+import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import { describeCentrs } from "../index.ts";
+import { defaultSettingsPath } from "../resolver/index.ts";
+import {
+	buildSettingsErrorEnvelope,
+	renderSettingsEnvelope,
+	type SettingsCommand,
+	type SettingsEnvelope,
+	type SettingsOutputFormat,
+	settingsGet,
+	settingsOutputFormats,
+	settingsPrint,
+	settingsReset,
+	settingsSet,
+} from "../settings.ts";
+import {
+	type CliCommandMetadata,
+	expectValue,
+	renderCommandHelp,
+	unknownFlagError,
+} from "./common.ts";
+
+export const settingsCommand: CliCommandMetadata = {
+	name: "settings",
+	usage: "centrs settings [print|get|set|reset] [args] [flags]",
+	summary:
+		"Manage centrs's own global preferences (`centrs.env`) and inspect the `__default__` CDB record.",
+	options: [
+		{
+			flag: "--all",
+			description:
+				"`print` only — also list unrecognized CENTRS_* lines found in the file.",
+		},
+		{
+			flag: "--cdb-file",
+			valueName: "<path>",
+			description:
+				"`print` only — CDB to probe for the `__default__` record summary (falls back to normal CDB resolution; never centrs.env).",
+		},
+		{
+			flag: "--cdb-password",
+			valueName: "<secret>",
+			description: "`print` only — decrypt password for the probed CDB.",
+		},
+		{
+			flag: "--skip-env-file",
+			description:
+				"`print` only — note that other commands in this environment would not see centrs.env (settings itself always reads the real file).",
+		},
+		{
+			flag: "--format",
+			valueName: `<${settingsOutputFormats.join("|")}>`,
+			description: "Output format for the CLI response.",
+		},
+		{ flag: "--json", description: "Shortcut for `--format json`." },
+		{ flag: "--help", description: "Show this help." },
+	],
+};
+
+type SettingsSubcommand = SettingsCommand;
+
+interface SettingsCliArgs {
+	help?: boolean;
+	subcommand: SettingsSubcommand;
+	attr?: string;
+	value?: string;
+	all?: boolean;
+	cdbFile?: string;
+	cdbPassword?: string;
+	skipEnvFile?: boolean;
+	format?: SettingsOutputFormat;
+}
+
+function parseSettingsCliArgs(args: readonly string[]): SettingsCliArgs {
+	const positional: string[] = [];
+	let help = false;
+	let all = false;
+	let cdbFile: string | undefined;
+	let cdbPassword: string | undefined;
+	let skipEnvFile = false;
+	let format: SettingsOutputFormat | undefined;
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) {
+			continue;
+		}
+		switch (arg) {
+			case "--help":
+			case "-h":
+				help = true;
+				break;
+			case "--all":
+				all = true;
+				break;
+			case "--cdb-file":
+				cdbFile = expectValue(args, ++index, arg);
+				break;
+			case "--cdb-password":
+				cdbPassword = expectValue(args, ++index, arg);
+				break;
+			case "--skip-env-file":
+				skipEnvFile = true;
+				break;
+			case "--format": {
+				const value = expectValue(args, ++index, arg);
+				if (!settingsOutputFormats.includes(value as SettingsOutputFormat)) {
+					throw new Error(
+						`--format must be one of ${settingsOutputFormats.join(", ")}; got ${value}.`,
+					);
+				}
+				format = value as SettingsOutputFormat;
+				break;
+			}
+			case "--json":
+				format = "json";
+				break;
+			default:
+				// A negative-integer value (e.g. `settings set max-results -1`) looks
+				// like a flag but is a legitimate positional — `settings` has no flag
+				// shaped like a bare negative number, so this is unambiguous.
+				if (arg.startsWith("-") && !/^-\d+$/.test(arg)) {
+					throw unknownFlagError("settings", arg, settingsCommand.options);
+				}
+				positional.push(arg);
+				break;
+		}
+	}
+
+	const result: SettingsCliArgs = {
+		help,
+		subcommand: "print",
+		all,
+		cdbFile,
+		cdbPassword,
+		skipEnvFile,
+		format,
+	};
+	if (help) {
+		return result;
+	}
+
+	const [rawSub, ...rest] = positional;
+	// Bare `centrs settings` (no subcommand at all) behaves like `print`.
+	if (rawSub === undefined) {
+		return result;
+	}
+
+	const subcommands: readonly SettingsSubcommand[] = [
+		"print",
+		"get",
+		"set",
+		"reset",
+	];
+	if (!subcommands.includes(rawSub as SettingsSubcommand)) {
+		throw new Error(
+			`Unknown settings subcommand: ${rawSub}. Use print, get, set, or reset (or omit the subcommand for print).`,
+		);
+	}
+	result.subcommand = rawSub as SettingsSubcommand;
+
+	if (result.subcommand === "print" || result.subcommand === "reset") {
+		if (rest.length > 1) {
+			throw new Error(
+				`\`centrs settings ${result.subcommand}\` accepts at most one <attr>.`,
+			);
+		}
+		result.attr = rest[0];
+	} else if (result.subcommand === "get") {
+		if (rest.length !== 1) {
+			throw new Error("`centrs settings get` requires exactly one <attr>.");
+		}
+		result.attr = rest[0];
+	} else if (result.subcommand === "set") {
+		if (rest.length !== 2) {
+			throw new Error("`centrs settings set` requires exactly <attr> <value>.");
+		}
+		result.attr = rest[0];
+		result.value = rest[1];
+	}
+
+	return result;
+}
+
+export async function runSettingsCli(args: readonly string[]): Promise<number> {
+	let parsed: SettingsCliArgs | undefined;
+	let envSnapshot: Record<string, string | undefined> | undefined;
+	try {
+		parsed = parseSettingsCliArgs(args);
+		if (parsed.help) {
+			console.log(renderCommandHelp(describeCentrs(), settingsCommand));
+			return 0;
+		}
+
+		envSnapshot = Bun.env;
+		let envelope: SettingsEnvelope<unknown>;
+		switch (parsed.subcommand) {
+			case "print":
+				envelope = await settingsPrint({
+					attr: parsed.attr,
+					all: parsed.all,
+					env: envSnapshot,
+					skipEnvFile: parsed.skipEnvFile,
+					cdbFile: parsed.cdbFile,
+					cdbPassword: parsed.cdbPassword,
+				});
+				break;
+			case "get":
+				if (!parsed.attr) {
+					throw new Error("Missing <attr> for settings get.");
+				}
+				envelope = await settingsGet({ attr: parsed.attr, env: envSnapshot });
+				break;
+			case "set":
+				if (!parsed.attr || parsed.value === undefined) {
+					throw new Error("Missing <attr> <value> for settings set.");
+				}
+				envelope = await settingsSet({
+					attr: parsed.attr,
+					value: parsed.value,
+					env: envSnapshot,
+				});
+				break;
+			case "reset":
+				envelope = await settingsReset({
+					attr: parsed.attr,
+					env: envSnapshot,
+				});
+				break;
+			default:
+				throw new Error("Unreachable settings subcommand.");
+		}
+
+		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) {
+		const format = parsed?.format ?? inferSettingsFormat(args);
+		const settingsFile = defaultSettingsPath(envSnapshot ?? Bun.env);
+		const centrsError = asCentrsError(error, {
+			code: "input/invalid-command",
+			summary: error instanceof Error ? error.message : String(error),
+			remediation:
+				"Use `centrs settings --help` to inspect the supported subcommands and flags.",
+		});
+		const envelope = buildSettingsErrorEnvelope(
+			parsed?.subcommand ?? "print",
+			settingsFile,
+			[],
+			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;
+	}
+}
+
+function inferSettingsFormat(args: readonly string[]): SettingsOutputFormat {
+	if (args.includes("--json")) {
+		return "json";
+	}
+	const formatIndex = args.indexOf("--format");
+	const value = formatIndex >= 0 ? args[formatIndex + 1] : undefined;
+	if (value && settingsOutputFormats.includes(value as SettingsOutputFormat)) {
+		return value as SettingsOutputFormat;
+	}
+	return "text";
+}

package/src/cli/terminal.ts

@@ -6,7 +6,11 @@
  * `process.*`); the core relay in `../terminal.ts` stays io-agnostic.
  */
 
-import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
 import {
 	buildTerminalErrorEnvelope,
 	describeCentrs,
@@ -19,6 +23,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -28,6 +33,7 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import { selectionFlagTokens } from "./selection.ts";
 
 export const terminalCommand: CliCommandMetadata = {
 	name: "terminal",
@@ -181,10 +187,12 @@ 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",
@@ -205,7 +213,7 @@ interface ParsedTerminal {
 	request: TerminalRequest;
 }
 
-function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
+export function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 	const flags: TerminalRequest = {};
 	const positional: string[] = [];
 	let help = false;
@@ -268,14 +276,21 @@ function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 				flags.verbose = true;
 				break;
 			default:
-				if (arg.startsWith("-")) {
-					throw asCentrsError(new Error(`Unknown terminal flag: ${arg}`), {
-						code: "input/invalid-command",
-						summary: `Unknown terminal flag: ${arg}`,
+				// A single interactive session cannot fan out: reject a target-selection
+				// flag with the shared `usage/fanout-not-supported` (mirrors `api --stream`).
+				if ((selectionFlagTokens as readonly string[]).includes(arg)) {
+					throw new CentrsError({
+						code: "usage/fanout-not-supported",
+						summary:
+							"`centrs terminal` is a single interactive session and cannot fan out across a multi-target selection.",
 						remediation:
-							"Remove the flag or run `centrs terminal --help` for the supported options.",
+							"Open a terminal to one router at a time; use `execute` / `api` for multi-target commands.",
+						context: { flag: arg, capability: "terminal" },
 					});
 				}
+				if (arg.startsWith("-")) {
+					throw unknownFlagError("terminal", arg, terminalCommand.options);
+				}
 				positional.push(arg);
 				break;
 		}