@tikoci/centrs 0.1.2 → 0.1.4

package/src/api.ts

@@ -45,10 +45,13 @@ import {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	isIpTransport,
+	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -56,6 +59,7 @@ import {
 	resolveBooleanSetting,
 	resolveCdb,
 	resolveMacTarget,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -71,6 +75,12 @@ export type ApiMethod = (typeof apiMethods)[number];
 
 export interface ApiRequest {
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password.
+	 */
+	quickchr?: string;
 	/** REST-style endpoint path, leniently normalized (`ip/address`, `/rest/ip/address`, `"ip address"`, `ip/address/*1`, `ip/address/listen`). */
 	endpoint: string;
 	/** HTTP method (`-X`), default `GET`, case-insensitive. */
@@ -500,8 +510,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 +551,29 @@ 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);
+	// A quickchr target is a named-live-provider: host/port/auth come from the
+	// live descriptor, bypassing CDB, `__default__`, and MAC resolution.
+	let quickchrResolution: Awaited<
+		ReturnType<typeof resolveQuickchrTarget>
+	> | null = null;
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+	}
+	const cdbResolution = quickchrResolution
+		? undefined
+		: (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,49 +585,79 @@ 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({
-				host: request.host,
-				targetInput: request.targetInput,
-				cdbTarget: cdbResolution?.target,
+	const macResolution =
+		quickchrResolution === null && isIpTransport(via.value)
+			? await resolveMacTarget({
+					host: request.host,
+					targetInput: request.targetInput,
+					cdbTarget: cdbResolution?.target,
+					env,
+					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",
+				})
+			: undefined;
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, via.value)
+		: null;
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+					macResolution,
+				},
 				env,
-				policy: parseResolvePolicy(request.resolve ?? env["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",
-			})
-		: undefined;
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-	);
-	const auth = resolveAuth(
-		{ username: request.username, password: request.password },
-		env,
-		cdbResolution,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-	);
+				via.value,
+				cdbResolution,
+				config,
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{ username: request.username, password: request.password },
+				env,
+				cdbResolution,
+				config,
+			);
+	// A quickchr TLS endpoint is trusted by provenance (self-signed VM cert) —
+	// `insecure` is forced with provider provenance and the provider-trust
+	// warning rides the envelope (see QuickchrConnection.insecure).
+	const insecure =
+		connection?.insecure === true
+			? {
+					value: true,
+					source: {
+						kind: "provider" as const,
+						key: `quickchr:${request.quickchr}`,
+					},
+				}
+			: resolveBooleanSetting(
+					request.insecure,
+					env,
+					"CENTRS_INSECURE",
+					false,
+					"insecure",
+					cdbResolution?.overrides.insecure,
+					config,
+				);
 
 	return {
 		endpoint: request.endpoint,
@@ -620,7 +685,9 @@ export async function resolveApiRequest(
 		insecure,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
 	};
 }
 
@@ -918,7 +985,7 @@ async function validateApiRequest(
 						context: {
 							path: resolved.path,
 							verb: resolved.verb,
-							attribute: missing[0],
+							parameter: missing[0],
 							requestedAttributes: requested,
 							availableAttributes: available,
 							validationSource: "/console/inspect request=child+completion",
@@ -963,7 +1030,7 @@ async function validateApiRequest(
 				context: {
 					path: resolved.path,
 					verb: resolved.verb,
-					attribute: missing[0],
+					parameter: missing[0],
 					requestedAttributes: requested,
 					availableAttributes: available,
 					validationSource: "/console/inspect request=child+completion",
@@ -1082,6 +1149,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 +1162,7 @@ function resolveApiProtocol(
 		"via",
 		undefined,
 		cdb?.overrides.via,
+		config,
 	);
 	if (!via) {
 		throw new CentrsError({
@@ -1102,29 +1171,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 +1215,8 @@ function resolveApiFormat(
 		"json",
 		"format",
 		parseApiOutputFormat,
+		undefined,
+		config,
 	) as ResolvedSetting<ApiOutputFormat>;
 }
 
@@ -1141,6 +1225,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 +1246,7 @@ function resolveApiTimeout(
 			return parsed;
 		},
 		commentKv,
+		config,
 	);
 	if (!resolved) {
 		throw new Error("timeout resolution produced no value");
@@ -1402,7 +1488,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 +1504,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,12 +9,19 @@ import {
 	renderApiEnvelope,
 	renderApiStreamLine,
 } from "../api.ts";
+import {
+	apiFanout,
+	buildApiFanoutErrorEnvelope,
+	renderApiFanoutEnvelope,
+} from "../api-fanout.ts";
+import { fanoutExitCode } from "../core/fanout.ts";
 import {
 	asCentrsError,
 	CentrsError,
 	formatCentrsErrorText,
 } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -29,6 +36,15 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import {
+	assertQuickchrExclusive,
+	buildTargetSelection,
+	consumeSelectionFlag,
+	emptySelectionFlags,
+	isFanoutMode,
+	type SelectionFlags,
+	selectionCommandOptions,
+} from "./selection.ts";
 
 export const apiCommand: CliCommandMetadata = {
 	name: "api",
@@ -43,7 +59,7 @@ export const apiCommand: CliCommandMetadata = {
 				"HTTP method, default GET (case-insensitive). GET→print, PUT→add, PATCH→set, DELETE→remove, POST→run.",
 		},
 		{
-			flag: "-f",
+			flag: "-f / --field",
 			valueName: "<key=value>",
 			description:
 				"Body field, repeatable; assembled into the JSON body (verbatim string values).",
@@ -106,6 +122,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>",
@@ -153,9 +170,9 @@ export const apiCommand: CliCommandMetadata = {
 			description: "Per-request timeout (for REST, max 60s).",
 		},
 		{
-			flag: "--validate[=false]",
+			flag: "--validate / --no-validate",
 			description:
-				"Run `/console/inspect` validation before the request (default true).",
+				"Run `/console/inspect` validation before the request (default true; `--validate=false` also accepted).",
 		},
 		{
 			flag: "--format",
@@ -179,11 +196,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 +335,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 +368,20 @@ 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`.",
-			});
+		// Selection-shape usage errors fire before `--input` is read: a bad
+		// `--quickchr` combination must not block on stdin (`--input -`) or
+		// degrade into per-member fan-out failures. The resolver re-checks the
+		// override conflict for library callers.
+		const selectionFlags = parsed.selectionFlags ?? emptySelectionFlags();
+		const targetPositionals = parsed.targetPositionals ?? [];
+		assertQuickchrExclusive(selectionFlags, targetPositionals.length);
+		if (selectionFlags.quickchr.length > 0) {
+			assertNoQuickchrOverrideConflict(
+				parsed,
+				selectionFlags.quickchr[0] ?? "",
+			);
 		}
+
 		// Resolve `--input` (file / stdin) before handing the body to the orchestrator.
 		if (parsed.inputPath !== undefined) {
 			const inputPath = parsed.inputPath;
@@ -364,6 +402,23 @@ 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).
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			return await runApiFanoutCli(
+				parsed,
+				selectionFlags,
+				targetPositionals,
+				args,
+			);
+		}
+		// A single `--quickchr <name>` is single-target mode (streaming included):
+		// the machine name is the target, resolved from the live descriptor.
+		if (selectionFlags.quickchr.length === 1) {
+			parsed.quickchr = selectionFlags.quickchr[0];
+		}
+
 		// 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 +429,15 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			return await runApiListenCli(parsed, args);
 		}
 
+		if (!parsed.targetInput && parsed.quickchr === undefined) {
+			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 +471,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 +483,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 +506,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.