@tikoci/centrs 0.1.2 → 0.1.3

package/src/api.ts

@@ -47,6 +47,7 @@ import {
 import {
 	type CdbResolution,
 	isIpTransport,
+	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
 	type ResolvedAuth,
@@ -500,8 +501,20 @@ function disabledValidationMeta(): EnvelopeValidationMeta {
 export async function resolveApiRequest(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
+	override?: {
+		/**
+		 * A pre-resolved CDB record, supplied by fan-out so the CDB is loaded ONCE
+		 * (not per member) and a `--default`/literal member is never re-resolved
+		 * through `resolveCdb`'s `__default__` synthetic-target fallback.
+		 */
+		cdbResolution?: CdbResolution;
+		/** A pre-loaded `centrs.env` config tier, supplied by fan-out so the file
+		 * is read ONCE (not per member). */
+		config?: Record<string, string | undefined>;
+	},
 ): Promise<ResolvedApiRequest> {
 	validateApiRequestShape(request);
+	const config = override?.config ?? (await loadEnvFileDefaults(env));
 	const normalized = normalizeApiEndpoint(request.endpoint);
 	const method = parseApiMethod(request.method);
 	const verb = mapMethodToVerb(method);
@@ -529,16 +542,19 @@ export async function resolveApiRequest(
 	const query = buildApiQuery(request);
 	const proplist = buildApiProplist(request);
 
-	const cdbResolution = await resolveCdb(
-		{
-			targetInput: request.targetInput,
-			cdbFile: request.cdbFile,
-			cdbPassword: request.cdbPassword,
-		},
-		env,
-	);
-	const via = resolveApiProtocol(request, env, listen, cdbResolution);
-	const format = resolveApiFormat(request, env);
+	const cdbResolution =
+		override?.cdbResolution ??
+		(await resolveCdb(
+			{
+				targetInput: request.targetInput,
+				cdbFile: request.cdbFile,
+				cdbPassword: request.cdbPassword,
+			},
+			env,
+			config,
+		));
+	const via = resolveApiProtocol(request, env, listen, cdbResolution, config);
+	const format = resolveApiFormat(request, env, config);
 	// `--raw` forces validation off (constitution: --raw waiver); otherwise the
 	// inspect gate is on by default.
 	const validate: ResolvedSetting<boolean> = raw
@@ -550,12 +566,14 @@ export async function resolveApiRequest(
 				true,
 				"validate",
 				cdbResolution?.overrides.validate,
+				config,
 			);
 	const timeoutMs = resolveApiTimeout(
 		request.timeout,
 		env,
 		via.value,
 		cdbResolution?.overrides.timeoutMs,
+		config,
 	);
 	const macResolution = isIpTransport(via.value)
 		? await resolveMacTarget({
@@ -563,7 +581,10 @@ export async function resolveApiRequest(
 				targetInput: request.targetInput,
 				cdbTarget: cdbResolution?.target,
 				env,
-				policy: parseResolvePolicy(request.resolve ?? env["CENTRS_RESOLVE"]),
+				config,
+				policy: parseResolvePolicy(
+					request.resolve ?? env["CENTRS_RESOLVE"] ?? config["CENTRS_RESOLVE"],
+				),
 				// api has no Layer-2 transport (rest-api/native-api only), so MAC
 				// remediation matches retrieve's (no mac-telnet suggestion).
 				operation: "retrieve",
@@ -579,11 +600,13 @@ export async function resolveApiRequest(
 		env,
 		via.value,
 		cdbResolution,
+		config,
 	);
 	const auth = resolveAuth(
 		{ username: request.username, password: request.password },
 		env,
 		cdbResolution,
+		config,
 	);
 	const insecure = resolveBooleanSetting(
 		request.insecure,
@@ -592,6 +615,7 @@ export async function resolveApiRequest(
 		false,
 		"insecure",
 		cdbResolution?.overrides.insecure,
+		config,
 	);
 
 	return {
@@ -1082,6 +1106,7 @@ function resolveApiProtocol(
 	env: Record<string, string | undefined>,
 	listen: boolean,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
 	// A `/listen` endpoint (or `--listen`) infers native-api when `--via` is unset;
 	// REST stays the default for one-shot calls.
@@ -1094,6 +1119,7 @@ function resolveApiProtocol(
 		"via",
 		undefined,
 		cdb?.overrides.via,
+		config,
 	);
 	if (!via) {
 		throw new CentrsError({
@@ -1102,29 +1128,42 @@ function resolveApiProtocol(
 			remediation: "Report this bug; api should default to rest-api.",
 		});
 	}
-	if (!plannedProtocols.includes(via.value as RouterOsProtocol)) {
+	assertApiProtocolSupported(via.value);
+	return via as ResolvedSetting<RouterOsProtocol>;
+}
+
+/**
+ * Reject a protocol identifier `api` cannot run over. Throws `settings/invalid-via`
+ * for an unknown protocol and `routeros/protocol-not-implemented` for a known
+ * transport (e.g. ssh / mac-telnet) that `api` does not support. Shared so a
+ * globally-pinned `--via` / `CENTRS_VIA` can be rejected as an orchestration
+ * pre-flight error in fan-out (`api-fanout.ts`) rather than degrading into N
+ * identical per-target resolve failures.
+ */
+export function assertApiProtocolSupported(via: string): void {
+	if (!plannedProtocols.includes(via as RouterOsProtocol)) {
 		throw new CentrsError({
 			code: "settings/invalid-via",
-			summary: `Unsupported protocol identifier: ${via.value}`,
+			summary: `Unsupported protocol identifier: ${via}`,
 			remediation: "`api` runs over `rest-api` (default) or `native-api`.",
-			context: { via: via.value },
+			context: { via },
 		});
 	}
-	if (via.value !== "rest-api" && via.value !== "native-api") {
+	if (via !== "rest-api" && via !== "native-api") {
 		throw new CentrsError({
 			code: "routeros/protocol-not-implemented",
-			summary: `api over ${via.value} is not supported.`,
+			summary: `api over ${via} is not supported.`,
 			remediation:
 				"Use `--via rest-api` (default) or `--via native-api`. Console transports (ssh/mac-telnet) run through `execute`/`terminal`.",
-			context: { via: via.value, capability: "execute" },
+			context: { via, capability: "execute" },
 		});
 	}
-	return via as ResolvedSetting<RouterOsProtocol>;
 }
 
 function resolveApiFormat(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<ApiOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -1133,6 +1172,8 @@ function resolveApiFormat(
 		"json",
 		"format",
 		parseApiOutputFormat,
+		undefined,
+		config,
 	) as ResolvedSetting<ApiOutputFormat>;
 }
 
@@ -1141,6 +1182,7 @@ function resolveApiTimeout(
 	env: Record<string, string | undefined>,
 	via: RouterOsProtocol,
 	commentKv?: ResolvedSetting<number>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -1161,6 +1203,7 @@ function resolveApiTimeout(
 			return parsed;
 		},
 		commentKv,
+		config,
 	);
 	if (!resolved) {
 		throw new Error("timeout resolution produced no value");
@@ -1402,7 +1445,7 @@ export function validateApiRequestShape(request: ApiRequest): void {
 	}
 }
 
-function parseApiMethod(method: string | undefined): ApiMethod {
+export function parseApiMethod(method: string | undefined): ApiMethod {
 	if (method === undefined) {
 		return "GET";
 	}
@@ -1418,6 +1461,35 @@ function parseApiMethod(method: string | undefined): ApiMethod {
 	});
 }
 
+/**
+ * Build the request-level summary (no target) for the fan-out outer meta and
+ * for an empty selection where no per-target inner envelope exists. Mirrors the
+ * summary `buildApiErrorEnvelope` assembles from a bare request.
+ */
+export function apiRequestSummaryFromRequest(
+	request: ApiRequest,
+	env: Record<string, string | undefined> = Bun.env,
+): ApiRequestSummary {
+	const normalized = normalizeApiEndpoint(request.endpoint);
+	const parsed = tryParseApiMethod(request.method);
+	const listen = (request.listen ?? false) || normalized.listen;
+	return {
+		endpoint: request.endpoint,
+		path: normalized.path,
+		id: normalized.id,
+		method: parsed ?? request.method ?? "GET",
+		verb: parsed ? mapMethodToVerb(parsed) : null,
+		write: parsed ? isApiMutating(parsed, normalized.path) : false,
+		listen,
+		yes: request.yes ?? false,
+		validate: request.raw ? false : (request.validate ?? true),
+		raw: request.raw ?? false,
+		format: resolveErrorFormat(request, env),
+		query: buildApiQuery(request),
+		proplist: buildApiProplist(request),
+	};
+}
+
 /** Parse a method without throwing: a valid {@link ApiMethod}, or `undefined` when invalid. */
 function tryParseApiMethod(method: string | undefined): ApiMethod | undefined {
 	if (method === undefined) {

package/src/cli/api.ts

@@ -9,6 +9,12 @@ import {
 	renderApiEnvelope,
 	renderApiStreamLine,
 } from "../api.ts";
+import {
+	apiFanout,
+	buildApiFanoutErrorEnvelope,
+	renderApiFanoutEnvelope,
+} from "../api-fanout.ts";
+import { fanoutExitCode } from "../core/fanout.ts";
 import {
 	asCentrsError,
 	CentrsError,
@@ -29,6 +35,14 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import {
+	buildTargetSelection,
+	consumeSelectionFlag,
+	emptySelectionFlags,
+	isFanoutMode,
+	type SelectionFlags,
+	selectionCommandOptions,
+} from "./selection.ts";
 
 export const apiCommand: CliCommandMetadata = {
 	name: "api",
@@ -106,6 +120,7 @@ export const apiCommand: CliCommandMetadata = {
 			valueName: "<rest-api|native-api>",
 			description: "Pin the transport; no silent downgrade. Default rest-api.",
 		},
+		...selectionCommandOptions,
 		{
 			flag: "--host",
 			valueName: "<host|url>",
@@ -179,11 +194,16 @@ interface ApiCliArgs extends ApiRequest {
 	format?: ApiOutputFormat;
 	/** Unresolved `--input` value (`-` or a path); read into `inputBody` in the runner. */
 	inputPath?: string;
+	/** Parsed target-selection flags (fan-out grammar). */
+	selectionFlags?: SelectionFlags;
+	/** Positionals before the endpoint — the fan-out target list. */
+	targetPositionals?: string[];
 }
 
 export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 	const parsed: ApiCliArgs = { endpoint: "" };
 	const positional: string[] = [];
+	const selectionFlags = emptySelectionFlags();
 
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
@@ -313,17 +333,27 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 				parsed.format = value as ApiOutputFormat;
 				break;
 			}
-			default:
+			default: {
+				const consumed = consumeSelectionFlag(args, index, selectionFlags);
+				if (consumed !== null) {
+					index = consumed;
+					break;
+				}
 				if (arg.startsWith("-")) {
 					throw unknownFlagError("api", arg, apiCommand.options);
 				}
 				positional.push(arg);
 				break;
+			}
 		}
 	}
 
-	parsed.targetInput = positional[0];
-	parsed.endpoint = positional[1] ?? "";
+	// api/retrieve positional boundary: the FINAL positional is the endpoint; every
+	// preceding positional is a fan-out target.
+	parsed.endpoint = positional.at(-1) ?? "";
+	parsed.targetPositionals = positional.slice(0, -1);
+	parsed.selectionFlags = selectionFlags;
+	parsed.targetInput = parsed.targetPositionals[0];
 	parsed.stdinIsTty = process.stdin.isTTY;
 	return parsed;
 }
@@ -336,14 +366,6 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			console.log(renderCommandHelp(describeCentrs(), apiCommand));
 			return 0;
 		}
-		if (!parsed.targetInput) {
-			throw missingTargetError({
-				command: "api",
-				summary: "`centrs api` requires a <router> and an <endpoint>.",
-				remediation:
-					"Pass the router host/identity then the endpoint, e.g. `centrs api 192.0.2.10 ip/address`.",
-			});
-		}
 		// Resolve `--input` (file / stdin) before handing the body to the orchestrator.
 		if (parsed.inputPath !== undefined) {
 			const inputPath = parsed.inputPath;
@@ -364,6 +386,20 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			}
 		}
 
+		// Fan-out mode (selector flag present, or >1 positional target) has its own
+		// envelope shape, guards, and granular exit code. It runs first and rejects
+		// `--stream`/`--listen` + fan-out itself (single-session is exclusive).
+		const selectionFlags = parsed.selectionFlags ?? emptySelectionFlags();
+		const targetPositionals = parsed.targetPositionals ?? [];
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			return await runApiFanoutCli(
+				parsed,
+				selectionFlags,
+				targetPositionals,
+				args,
+			);
+		}
+
 		// Open-ended follow (`--stream`/`--listen`, or a `/listen` endpoint) consumes
 		// the NDJSON envelope stream instead of a single one-shot envelope.
 		const streaming =
@@ -374,6 +410,15 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			return await runApiListenCli(parsed, args);
 		}
 
+		if (!parsed.targetInput) {
+			throw missingTargetError({
+				command: "api",
+				summary: "`centrs api` requires a <router> and an <endpoint>.",
+				remediation:
+					"Pass the router host/identity then the endpoint, e.g. `centrs api 192.0.2.10 ip/address`.",
+			});
+		}
+
 		const envelope = await apiEnvelope(parsed);
 		const resolvedFormat =
 			(
@@ -407,6 +452,7 @@ 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,
@@ -418,12 +464,14 @@ 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",
@@ -439,6 +487,82 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 	}
 }
 
+async function runApiFanoutCli(
+	parsed: ApiCliArgs,
+	selectionFlags: SelectionFlags,
+	targetPositionals: readonly string[],
+	args: readonly string[],
+): Promise<number> {
+	const selection = buildTargetSelection(selectionFlags, targetPositionals);
+	const format = inferApiFormat(args, parsed);
+	try {
+		// `--raw` strips the envelope; incompatible with per-target envelopes.
+		if (parsed.raw) {
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary:
+					"`--raw` cannot combine with a multi-target selection; fan-out needs per-target envelopes.",
+				remediation:
+					"Drop `--raw` to fan out, or target a single router for the bare RouterOS body.",
+				context: { flags: ["--raw", "fanout"] },
+			});
+		}
+		// `--listen`/`--stream` is single-session.
+		const listenRequested =
+			(parsed.listen ?? false) || endpointInfersListen(parsed.endpoint);
+		if (listenRequested) {
+			throw new CentrsError({
+				code: "usage/fanout-not-supported",
+				summary:
+					"`api --stream`/`--listen` is single-session and cannot fan out across multiple targets.",
+				remediation:
+					"Follow a stream against a single router (no `--group`/`--where`/`--all`/`--default`/multiple positionals).",
+				context: { capability: "listen" },
+			});
+		}
+		const envelope = await apiFanout(
+			parsed,
+			selection,
+			Bun.env,
+			{},
+			{
+				concurrency: selectionFlags.concurrency,
+				allowAdhoc: true,
+			},
+		);
+		const resolvedFormat = envelope.meta.operation?.request.format ?? format;
+		console.log(
+			renderApiFanoutEnvelope(envelope, resolvedFormat, {
+				verbose: parsed.verbose ?? false,
+			}),
+		);
+		return fanoutExitCode(envelope);
+	} catch (error) {
+		const envelope = buildApiFanoutErrorEnvelope(
+			parsed,
+			selection,
+			error,
+			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,
+			}),
+		);
+		return 1;
+	}
+}
+
+/** Whether an endpoint's trailing segment infers `--listen` (without throwing). */
+function endpointInfersListen(endpoint: string): boolean {
+	try {
+		return normalizeApiEndpoint(endpoint).listen;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Consume the open-ended `--stream` follow: print one line per change frame
  * (NDJSON under `json`, human rows under `text`), then the terminating summary.

package/src/cli/btest.ts

@@ -29,8 +29,10 @@ import type { BtestDirection, BtestProtocol } from "../protocols/btest.ts";
 import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
+	type CliCommandOption,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -136,6 +138,22 @@ export const btestCommand: CliCommandMetadata = {
 	],
 };
 
+/**
+ * btest's single option list documents both subcommands. Scope "did you mean?"
+ * hints to the active mode so a client typo never suggests a server-only flag
+ * (and vice versa). Shared flags carry no `(client)`/`(server)` marker, so they
+ * stay in both; if a marker is ever dropped the flag just widens to both
+ * modes — it degrades to the old behavior, never a crash.
+ */
+function btestOptionsFor(
+	mode: "client" | "server",
+): readonly CliCommandOption[] {
+	const other = mode === "client" ? "(server)" : "(client)";
+	return btestCommand.options.filter(
+		(option) => !option.description.includes(other),
+	);
+}
+
 /** Parse a bandwidth value: a bare integer or a `K`/`M`/`G` suffix (bits/sec). */
 function parseBandwidth(value: string, flag: string): number {
 	const match = value.trim().match(/^(\d+(?:\.\d+)?)([kKmMgG]?)$/);
@@ -276,7 +294,7 @@ function parseClientArgs(args: readonly string[]): ClientCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-"))
-					throw new Error(`Unknown btest client flag: ${arg}`);
+					throw unknownFlagError("btest", arg, btestOptionsFor("client"));
 				if (request.targetInput !== undefined)
 					throw new Error(`Unexpected extra argument: ${arg}`);
 				request.targetInput = arg;
@@ -341,7 +359,7 @@ function parseServerArgs(args: readonly string[]): ServerCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-"))
-					throw new Error(`Unknown btest server flag: ${arg}`);
+					throw unknownFlagError("btest", arg, btestOptionsFor("server"));
 				throw new Error(
 					`\`centrs btest server\` takes no positional arguments; got: ${arg}.`,
 				);

package/src/cli/common.ts

@@ -33,6 +33,17 @@ export function expectValue(
 	return value;
 }
 
+/**
+ * Parse a strictly-integer flag value, or `undefined` when the whole token is
+ * not an integer. Rejects numeric prefixes (`2abc` → undefined, not `2`) and
+ * decimals (`1.5`), which a bare `Number.parseInt` would silently truncate —
+ * the trap shared by `--port` / `--count` / `--concurrency`.
+ */
+export function parseStrictInteger(value: string): number | undefined {
+	const trimmed = value.trim();
+	return /^-?\d+$/.test(trimmed) ? Number.parseInt(trimmed, 10) : undefined;
+}
+
 /** Flatten an option's `flag` field ("-X / --method") into individual `-`/`--` tokens. */
 export function knownFlags(options: readonly CliCommandOption[]): string[] {
 	const flags: string[] = [];