@tikoci/centrs 0.1.3 → 0.1.4

package/src/api-fanout.ts

@@ -7,7 +7,7 @@
  * `ApiEnvelope`s into the locked `FanoutData` shape (`src/core/envelope.ts`).
  *
  * Boundaries (see `commands/api/README.md`, `docs/CONSTITUTION.md`):
- *   - The CDB is loaded ONCE (`expandCdbSelection`); a cdb member is resolved
+ *   - The CDB is loaded ONCE (`expandSelection`); a cdb member is resolved
  *     with its pre-resolved record, so `resolveCdb`'s `__default__` synthetic
  *     fallback never collides ad-hoc literals.
  *   - A `--default` / `__default__` member is guarded from being dialed as the
@@ -53,12 +53,12 @@ import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
 import { toYaml } from "./retrieve.ts";
@@ -70,6 +70,8 @@ export interface ApiSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface ApiFanoutOperationMeta {
@@ -92,10 +94,10 @@ export type ApiFanoutErrorEnvelope =
 export interface ApiFanoutInternals {
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	execute?: (resolved: ResolvedApiRequest) => Promise<ApiSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -113,6 +115,7 @@ function summarizeSelection(selection: TargetSelection): ApiSelectionSummary {
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
@@ -120,7 +123,7 @@ function summarizeSelection(selection: TargetSelection): ApiSelectionSummary {
 function fanoutVia(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): RouterOsProtocol {
 	// Deliberately CLI/env only, not `config` — see the note above this
 	// function's caller.
@@ -139,7 +142,7 @@ function fanoutVia(
 	return anyNative ? "native-api" : "rest-api";
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -151,6 +154,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -163,7 +169,7 @@ function memberTargetMeta(member: CdbSelectionMember): {
  */
 function relabelAdhocMember(
 	envelope: ApiEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): ApiEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -209,7 +215,7 @@ export async function apiFanout(
 		assertApiProtocolSupported(pinnedVia);
 	}
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -243,7 +249,7 @@ export async function apiFanout(
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
-		CdbSelectionMember,
+		SelectionMember,
 		ResolvedApiRequest,
 		ApiEnvelope
 	>({
@@ -267,6 +273,15 @@ export async function apiFanout(
 					{ cdbResolution: member.resolution, config },
 				);
 			}
+			if (member.kind === "quickchr") {
+				// The live descriptor resolves here, per member — a stopped/unknown
+				// machine is an inner per-target failure, not an expansion error.
+				return resolveApiRequest(
+					{ ...request, targetInput: undefined, quickchr: member.name },
+					env,
+					{ config },
+				);
+			}
 			return resolveApiRequest({ ...request, targetInput: member.input }, env, {
 				config,
 			});
@@ -302,7 +317,7 @@ async function assertFanoutWriteConfirmed(
 	request: ApiRequest,
 	summary: ApiRequestSummary,
 	method: string,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): Promise<void> {
 	if (!summary.write || request.yes) {
 		return;
@@ -329,7 +344,7 @@ async function assertFanoutWriteConfirmed(
 interface ApiFanoutSuccessInput {
 	summary: FanoutSummary;
 	targets: readonly ApiEnvelope[];
-	warnings: CdbSelectionExpansion["warnings"];
+	warnings: SelectionExpansion["warnings"];
 	via: RouterOsProtocol | null;
 	concurrency: number;
 	requestSummary: ApiRequestSummary;

package/src/api.ts

@@ -45,11 +45,13 @@ import {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	isIpTransport,
 	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -57,6 +59,7 @@ import {
 	resolveBooleanSetting,
 	resolveCdb,
 	resolveMacTarget,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -72,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. */
@@ -542,17 +551,27 @@ export async function resolveApiRequest(
 	const query = buildApiQuery(request);
 	const proplist = buildApiProplist(request);
 
-	const cdbResolution =
-		override?.cdbResolution ??
-		(await resolveCdb(
-			{
-				targetInput: request.targetInput,
-				cdbFile: request.cdbFile,
-				cdbPassword: request.cdbPassword,
-			},
-			env,
-			config,
-		));
+	// 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
@@ -575,48 +594,70 @@ export async function resolveApiRequest(
 		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,
+				via.value,
+				cdbResolution,
 				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 target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-		config,
-	);
-	const auth = resolveAuth(
-		{ username: request.username, password: request.password },
-		env,
-		cdbResolution,
-		config,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-		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,
@@ -644,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 ?? []),
 	};
 }
 
@@ -942,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",
@@ -987,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",

package/src/cli/api.ts

@@ -21,6 +21,7 @@ import {
 	formatCentrsErrorText,
 } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -36,6 +37,7 @@ import {
 	withTips,
 } from "./missing-target.ts";
 import {
+	assertQuickchrExclusive,
 	buildTargetSelection,
 	consumeSelectionFlag,
 	emptySelectionFlags,
@@ -57,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).",
@@ -168,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",
@@ -366,6 +368,20 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			console.log(renderCommandHelp(describeCentrs(), apiCommand));
 			return 0;
 		}
+		// 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;
@@ -389,8 +405,6 @@ 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,
@@ -399,6 +413,11 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				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.
@@ -410,7 +429,7 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 			return await runApiListenCli(parsed, args);
 		}
 
-		if (!parsed.targetInput) {
+		if (!parsed.targetInput && parsed.quickchr === undefined) {
 			throw missingTargetError({
 				command: "api",
 				summary: "`centrs api` requires a <router> and an <endpoint>.",

package/src/cli/btest.ts

@@ -95,8 +95,14 @@ export const btestCommand: CliCommandMetadata = {
 		},
 		{ flag: "--random-data", description: "(client) Incompressible payload." },
 		{
-			flag: "--authenticate[=false]",
-			description: "(server) Require EC-SRP5 auth. Default true.",
+			flag: "--nat-mode",
+			description:
+				"(client, UDP only) Originate an outbound datagram first so server→client data can traverse NAT. Automatic when the test receives.",
+		},
+		{
+			flag: "--authenticate / --no-authenticate",
+			description:
+				"(server) Require EC-SRP5 auth. Default true; `--authenticate=false` also accepted.",
 		},
 		{
 			flag: "--bind",
@@ -129,6 +135,16 @@ export const btestCommand: CliCommandMetadata = {
 			valueName: "<port>",
 			description: "Control port. Default 2000.",
 		},
+		{
+			flag: "--cdb-file",
+			valueName: "<path>",
+			description: "(client) Read target credentials from a WinBox CDB file.",
+		},
+		{
+			flag: "--cdb-password",
+			valueName: "<password>",
+			description: "(client) Decrypt an encrypted WinBox CDB file.",
+		},
 		{
 			flag: "--format",
 			valueName: `<${btestOutputFormats.join("|")}>`,

package/src/cli/execute.ts

@@ -14,6 +14,7 @@ import {
 	renderExecuteFanoutEnvelope,
 } from "../execute-fanout.ts";
 import { describeCentrs } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -29,9 +30,11 @@ import {
 	withTips,
 } from "./missing-target.ts";
 import {
+	assertQuickchrExclusive,
 	buildTargetSelection,
 	consumeSelectionFlag,
 	emptySelectionFlags,
+	hasTargetSelector,
 	isFanoutMode,
 	type SelectionFlags,
 	selectionCommandOptions,
@@ -105,9 +108,9 @@ export const executeCommand: CliCommandMetadata = {
 			description: "Per-request timeout (for REST, max 60s).",
 		},
 		{
-			flag: "--validate[=false]",
+			flag: "--validate / --no-validate",
 			description:
-				"Run RouterOS :parse and /console/inspect validation before execution (default true).",
+				"Run RouterOS :parse and /console/inspect validation before execution (default true; `--validate=false` also accepted).",
 		},
 		{
 			flag: "--yes",
@@ -265,12 +268,12 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 	parsed.selectionFlags = selectionFlags;
 	// Positional boundary for execute (see `docs/CONSTITUTION.md` → Target selection):
 	//   - `--` present: targets are the positionals BEFORE it, command is AFTER it.
-	//   - selector flag present, no `--`: every positional is the command (targets
-	//     come from the selector).
+	//   - selector flag (or `--quickchr`) present, no `--`: every positional is the
+	//     command (targets come from the flag).
 	//   - otherwise (no `--`, no selector): legacy single-target split — first
 	//     positional is the target, the rest is the command. Multiple positional
 	//     targets therefore REQUIRE `--`.
-	const hasSelector = isFanoutMode(selectionFlags, 0);
+	const hasSelector = hasTargetSelector(selectionFlags);
 	if (endOfOptions) {
 		parsed.targetPositionals = positional;
 		parsed.command = afterDashDash.join(" ");
@@ -300,6 +303,17 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 		// own envelope shape, single up-front write-confirm, and granular exit code.
 		const selectionFlags = parsed.selectionFlags ?? emptySelectionFlags();
 		const targetPositionals = parsed.targetPositionals ?? [];
+		assertQuickchrExclusive(selectionFlags, targetPositionals.length);
+		// Direct connection overrides conflict with `--quickchr` globally: reject
+		// before fan-out dispatch so a repeated `--quickchr` gets one usage error
+		// (exit 1), never per-member failures. The resolver re-checks for library
+		// callers.
+		if (selectionFlags.quickchr.length > 0) {
+			assertNoQuickchrOverrideConflict(
+				parsed,
+				selectionFlags.quickchr[0] ?? "",
+			);
+		}
 		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
 			return await runExecuteFanoutCli(
 				parsed,
@@ -308,12 +322,17 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 				args,
 			);
 		}
+		// A single `--quickchr <name>` is single-target mode: the machine name is
+		// the target (resolved from the live descriptor inside the resolver).
+		if (selectionFlags.quickchr.length === 1) {
+			parsed.quickchr = selectionFlags.quickchr[0];
+		}
 
 		// No positional at all: lead with the missing-target guidance (CDB picker /
 		// discover) rather than the missing-command error — there is nothing to run
 		// without a device. A lone positional is treated as the target, so the
 		// "requires a command" path still fires for `execute <target>`.
-		if (!parsed.targetInput) {
+		if (!parsed.targetInput && parsed.quickchr === undefined) {
 			throw missingTargetError({
 				command: "execute",
 				summary: "`centrs execute` requires a <target> and a RouterOS command.",