@tikoci/centrs 0.1.1 → 0.1.2

package/src/btest.ts

@@ -138,6 +138,8 @@ export interface BtestClientData {
 	stopReason: BtestStopReason;
 	serverUdpPort?: number;
 	clientUdpPort?: number;
+	/** TCP data connections actually driven (1 + joined secondaries). */
+	activeConnections: number;
 }
 
 export interface BtestClientOperationMeta {
@@ -215,9 +217,37 @@ export async function btestClient(
 		controlPort,
 	};
 
+	const warnings: {
+		code: string;
+		message: string;
+		context?: Record<string, unknown>;
+	}[] = [];
+
 	try {
 		validateClientOptions(request);
 
+		// The btest wire command carries a single tx-size field; --remote-udp-tx-size
+		// and --local-udp-tx-size map to it separately only for receive (remote wins)
+		// and transmit (local wins). For both, localUdpTxSize wins and
+		// remoteUdpTxSize is silently discarded — warn when they differ so the user
+		// knows which size the server will actually use.
+		if (
+			protocol === "udp" &&
+			direction === "both" &&
+			request.remoteUdpTxSize !== undefined &&
+			request.localUdpTxSize !== undefined &&
+			request.remoteUdpTxSize !== request.localUdpTxSize
+		) {
+			warnings.push({
+				code: "routeros/btest-udp-tx-size-ignored",
+				message: `--remote-udp-tx-size (${request.remoteUdpTxSize}) is ignored for --direction both; the btest wire protocol carries a single tx-size and --local-udp-tx-size (${request.localUdpTxSize}) is used for both directions.`,
+				context: {
+					ignored: request.remoteUdpTxSize,
+					used: request.localUdpTxSize,
+				},
+			});
+		}
+
 		const cdbResolution = await resolveCdb(
 			{
 				targetInput: request.targetInput,
@@ -273,6 +303,9 @@ export async function btestClient(
 				? { statusIntervalMs: request.intervalMs }
 				: {}),
 			...(txSize !== undefined ? { txSize } : {}),
+			...(request.connectionCount !== undefined
+				? { tcpConnectionCount: request.connectionCount }
+				: {}),
 			...(request.localTxSpeed !== undefined
 				? { localTxSpeed: request.localTxSpeed }
 				: {}),
@@ -301,6 +334,7 @@ export async function btestClient(
 			txTotalAvgBps: secs > 0 ? (summary.totalTxBytes * 8) / secs : 0,
 			rxTotalAvgBps: secs > 0 ? (summary.totalRxBytes * 8) / secs : 0,
 			stopReason: summary.stopReason,
+			activeConnections: summary.activeConnections,
 		};
 		if (summary.username !== undefined) data.user = summary.username;
 		if (summary.serverUdpPort !== undefined)
@@ -308,10 +342,36 @@ export async function btestClient(
 		if (summary.clientUdpPort !== undefined)
 			data.clientUdpPort = summary.clientUdpPort;
 
+		// TCP multi-connection: centrs now opens the negotiated extra data
+		// connections (fan-out). It still degrades to a single stream when the server
+		// negotiates no session token — notably authenticated (EC-SRP5) sessions,
+		// whose post-auth token centrs does not yet capture. Warn only when the
+		// realized fan-out fell short of the request, with the actual count.
+		if (
+			protocol === "tcp" &&
+			request.connectionCount !== undefined &&
+			request.connectionCount > 1 &&
+			summary.activeConnections < request.connectionCount
+		) {
+			const single = summary.activeConnections === 1;
+			warnings.push({
+				code: "routeros/btest-connection-count-single-stream",
+				message: `--connection-count (${request.connectionCount}) requested, but ${summary.activeConnections} TCP data connection(s) are active${
+					single && summary.authKind !== "none"
+						? " — authenticated multi-connection is not yet supported"
+						: ""
+				}; throughput will not scale to the full count.`,
+				context: {
+					requested: request.connectionCount,
+					active: summary.activeConnections,
+				},
+			});
+		}
+
 		return {
 			ok: true,
 			data,
-			warnings: [],
+			warnings: warnings.map((w) => ({ ...w })),
 			tips: [],
 			meta: clientMeta(target.host, controlPort, operation, auth.username),
 		};

package/src/cli/api.ts

@@ -0,0 +1,536 @@
+import {
+	type ApiOutputFormat,
+	type ApiRequest,
+	apiEnvelope,
+	apiListen,
+	apiOutputFormats,
+	buildApiErrorEnvelope,
+	normalizeApiEndpoint,
+	renderApiEnvelope,
+	renderApiStreamLine,
+} from "../api.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
+import { describeCentrs } from "../index.ts";
+import {
+	type CliCommandMetadata,
+	expectValue,
+	renderCommandHelp,
+	unknownFlagError,
+} from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+	withTips,
+} from "./missing-target.ts";
+
+export const apiCommand: CliCommandMetadata = {
+	name: "api",
+	usage: "centrs api <router> <endpoint> [flags]",
+	summary:
+		"Structured RouterOS API passthrough (gh-api style) over REST or native API.",
+	options: [
+		{
+			flag: "-X / --method",
+			valueName: "<verb>",
+			description:
+				"HTTP method, default GET (case-insensitive). GET→print, PUT→add, PATCH→set, DELETE→remove, POST→run.",
+		},
+		{
+			flag: "-f",
+			valueName: "<key=value>",
+			description:
+				"Body field, repeatable; assembled into the JSON body (verbatim string values).",
+		},
+		{
+			flag: "-d / --data",
+			valueName: "<json>",
+			description: "Raw JSON request body. Conflicts with `-f` / `--input`.",
+		},
+		{
+			flag: "--input",
+			valueName: "<file|->",
+			description: "Read the raw JSON body from a file or stdin (`-`).",
+		},
+		{
+			flag: "--query / --filter",
+			valueName: "<expr>",
+			description:
+				"RouterOS-side row filter, AND-combined, repeatable: name=value, name!=value, name>value, name<value, name.",
+		},
+		{
+			flag: "--raw-query",
+			valueName: "<word>",
+			description:
+				"Verbatim RouterOS query word (repeatable) for OR / absence / stack expressions.",
+		},
+		{
+			flag: "--attribute / --proplist",
+			valueName: "<a,b>",
+			description: "Property projection → `.proplist`.",
+		},
+		{
+			flag: "--raw",
+			description:
+				"Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does not imply `--yes`.",
+		},
+		{
+			flag: "--yes",
+			description:
+				"Confirm a mutating (non-read) request in non-interactive runs.",
+		},
+		{
+			flag: "--stream / --listen",
+			description:
+				"Follow changes as an NDJSON envelope stream (native-api only; the `/listen` endpoint infers it). Ends with a summary envelope.",
+		},
+		{
+			flag: "--count",
+			valueName: "<n>",
+			description: "Stop a `--stream` after N change frames.",
+		},
+		{
+			flag: "--duration",
+			valueName: "<dur>",
+			description:
+				"Stop a `--stream` after this wall-clock window (e.g. `5s`).",
+		},
+		{
+			flag: "--via",
+			valueName: "<rest-api|native-api>",
+			description: "Pin the transport; no silent downgrade. Default rest-api.",
+		},
+		{
+			flag: "--host",
+			valueName: "<host|url>",
+			description: "Override the resolved host or base URL for the target.",
+		},
+		{
+			flag: "--port",
+			valueName: "<port>",
+			description: "Override the resolved management port.",
+		},
+		{
+			flag: "--username / --user / -u",
+			valueName: "<name>",
+			description: "RouterOS username. Falls back to `CENTRS_USERNAME`.",
+		},
+		{
+			flag: "--password",
+			valueName: "<secret>",
+			description: "RouterOS password. Falls back to `CENTRS_PASSWORD`.",
+		},
+		{
+			flag: "--insecure",
+			description:
+				"Accept a self-signed `api-ssl`/REST TLS cert. Default verifies.",
+		},
+		{
+			flag: "--cdb-file",
+			valueName: "<path>",
+			description: "Read target credentials from a WinBox CDB file.",
+		},
+		{
+			flag: "--cdb-password",
+			valueName: "<password>",
+			description: "Decrypt an encrypted WinBox CDB file.",
+		},
+		{
+			flag: "--resolve",
+			valueName: "<none|arp>",
+			description:
+				"Resolve a MAC-address target to an IP via the host ARP cache (default none).",
+		},
+		{
+			flag: "--timeout",
+			valueName: "<duration>",
+			description: "Per-request timeout (for REST, max 60s).",
+		},
+		{
+			flag: "--validate[=false]",
+			description:
+				"Run `/console/inspect` validation before the request (default true).",
+		},
+		{
+			flag: "--format",
+			valueName: "<json|yaml|text>",
+			description:
+				"Output format. Defaults to json for api; `CENTRS_FORMAT` overrides.",
+		},
+		{
+			flag: "--json",
+			description: "Shortcut for `--format json`.",
+		},
+		{
+			flag: "--verbose",
+			description: "Include additional context in text output.",
+		},
+	],
+};
+
+interface ApiCliArgs extends ApiRequest {
+	help?: boolean;
+	format?: ApiOutputFormat;
+	/** Unresolved `--input` value (`-` or a path); read into `inputBody` in the runner. */
+	inputPath?: string;
+}
+
+export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
+	const parsed: ApiCliArgs = { endpoint: "" };
+	const positional: string[] = [];
+
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === undefined) {
+			continue;
+		}
+		if (arg.startsWith("--validate=")) {
+			parsed.validate = parseBooleanFlag(arg.slice("--validate=".length), arg);
+			continue;
+		}
+		switch (arg) {
+			case "--help":
+			case "-h":
+				parsed.help = true;
+				break;
+			case "--json":
+				parsed.format = "json";
+				break;
+			case "--verbose":
+				parsed.verbose = true;
+				break;
+			case "--yes":
+				parsed.yes = true;
+				break;
+			case "--raw":
+				parsed.raw = true;
+				break;
+			case "--stream":
+			case "--listen":
+				parsed.listen = true;
+				break;
+			case "--validate":
+				parsed.validate = true;
+				break;
+			case "--no-validate":
+				parsed.validate = false;
+				break;
+			case "-X":
+			case "--method":
+				parsed.method = expectValue(args, ++index, arg);
+				break;
+			case "-f":
+			case "--field": {
+				const kv = expectValue(args, ++index, arg);
+				const eq = kv.indexOf("=");
+				if (eq <= 0) {
+					throw new Error(`${arg} expects key=value; got ${kv}`);
+				}
+				parsed.fields = {
+					...(parsed.fields ?? {}),
+					[kv.slice(0, eq)]: kv.slice(eq + 1),
+				};
+				break;
+			}
+			case "-d":
+			case "--data":
+				parsed.data = expectValue(args, ++index, arg);
+				break;
+			case "--input":
+				parsed.inputPath = expectValue(args, ++index, arg);
+				break;
+			case "--query":
+			case "--filter":
+				parsed.query = [
+					...(parsed.query ?? []),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--raw-query":
+				parsed.rawQuery = [
+					...(parsed.rawQuery ?? []),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--attribute":
+			case "--proplist":
+				parsed.proplist = [
+					...(parsed.proplist ?? []),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--duration":
+				parsed.duration = expectValue(args, ++index, arg);
+				break;
+			case "--count":
+				parsed.count = parseIntegerFlag(expectValue(args, ++index, arg), arg);
+				break;
+			case "--via":
+				parsed.via = expectValue(args, ++index, arg);
+				break;
+			case "--host":
+				parsed.host = expectValue(args, ++index, arg);
+				break;
+			case "--port":
+				parsed.port = parseIntegerFlag(expectValue(args, ++index, arg), arg);
+				break;
+			case "--user":
+			case "-u":
+			case "--username":
+				parsed.username = expectValue(args, ++index, arg);
+				break;
+			case "--password":
+				parsed.password = expectValue(args, ++index, arg);
+				break;
+			case "--insecure":
+				parsed.insecure = true;
+				break;
+			case "--cdb-file":
+				parsed.cdbFile = expectValue(args, ++index, arg);
+				break;
+			case "--cdb-password":
+				parsed.cdbPassword = expectValue(args, ++index, arg);
+				break;
+			case "--resolve":
+				parsed.resolve = expectValue(args, ++index, arg);
+				break;
+			case "--timeout":
+				parsed.timeout = expectValue(args, ++index, arg);
+				break;
+			case "--format": {
+				const value = expectValue(args, ++index, arg);
+				if (!apiOutputFormats.includes(value as ApiOutputFormat)) {
+					throw new Error(
+						`--format must be one of ${apiOutputFormats.join(", ")}; got ${value}.`,
+					);
+				}
+				parsed.format = value as ApiOutputFormat;
+				break;
+			}
+			default:
+				if (arg.startsWith("-")) {
+					throw unknownFlagError("api", arg, apiCommand.options);
+				}
+				positional.push(arg);
+				break;
+		}
+	}
+
+	parsed.targetInput = positional[0];
+	parsed.endpoint = positional[1] ?? "";
+	parsed.stdinIsTty = process.stdin.isTTY;
+	return parsed;
+}
+
+export async function runApiCli(args: readonly string[]): Promise<number> {
+	let parsed: ApiCliArgs | undefined;
+	try {
+		parsed = parseApiCliArgs(args);
+		if (parsed.help) {
+			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;
+			try {
+				parsed.inputBody =
+					inputPath === "-"
+						? await Bun.stdin.text()
+						: await Bun.file(inputPath).text();
+			} catch (error) {
+				throw new CentrsError({
+					code: "input/local-file-not-found",
+					summary: `Cannot read the --input body from ${inputPath === "-" ? "stdin" : inputPath}.`,
+					remediation:
+						"Check the path and read permissions, or pipe the JSON body into `--input -`.",
+					context: { input: inputPath },
+					cause: error,
+				});
+			}
+		}
+
+		// Open-ended follow (`--stream`/`--listen`, or a `/listen` endpoint) consumes
+		// the NDJSON envelope stream instead of a single one-shot envelope.
+		const streaming =
+			parsed.listen === true ||
+			(parsed.endpoint.length > 0 &&
+				normalizeApiEndpoint(parsed.endpoint).listen);
+		if (streaming) {
+			return await runApiListenCli(parsed, args);
+		}
+
+		const envelope = await apiEnvelope(parsed);
+		const resolvedFormat =
+			(
+				envelope.meta.operation as {
+					request?: { format?: ApiOutputFormat };
+				}
+			)?.request?.format ??
+			parsed.format ??
+			"json";
+		const rendered = renderApiEnvelope(envelope, resolvedFormat, {
+			raw: parsed.raw,
+			verbose: parsed.verbose,
+		});
+		if (envelope.ok) {
+			console.log(rendered);
+			return 0;
+		}
+		console.error(rendered);
+		return 1;
+	} catch (error) {
+		const format = inferApiFormat(args, parsed);
+		const tips = isMissingTargetError(error)
+			? await buildTargetSelectionTips({
+					cdbFile: parsed?.cdbFile ?? cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
+		if (parsed?.raw) {
+			// `--raw` defines a compact JSON error contract (code/message → stderr);
+			// keep that machine shape on the pre-envelope failure path too (e.g. a
+			// missing `--input` file) instead of falling back to plain text.
+			const envelope = withTips(buildApiErrorEnvelope(parsed, error), tips);
+			console.error(
+				renderApiEnvelope(envelope, format, {
+					raw: true,
+					verbose: parsed.verbose ?? false,
+				}),
+			);
+		} else if (format === "json" || format === "yaml") {
+			const envelope = withTips(
+				buildApiErrorEnvelope(parsed ?? { endpoint: "" }, error),
+				tips,
+			);
+			console.error(
+				renderApiEnvelope(envelope, format, {
+					verbose: parsed?.verbose ?? false,
+				}),
+			);
+		} else {
+			console.error(
+				formatCentrsErrorText(
+					asCentrsError(error, {
+						code: "input/invalid-command",
+						summary: error instanceof Error ? error.message : String(error),
+						remediation:
+							"Use `centrs api --help` to inspect the supported endpoint shape and flags.",
+					}),
+					{ verbose: parsed?.verbose ?? args.includes("--verbose") },
+				) + formatTipsText(tips),
+			);
+		}
+		return 1;
+	}
+}
+
+/**
+ * Consume the open-ended `--stream` follow: print one line per change frame
+ * (NDJSON under `json`, human rows under `text`), then the terminating summary.
+ * Ctrl-C (SIGINT) cancels the listen and still emits the summary. The exit code
+ * reflects whether the stream *started* cleanly — a failure before the first
+ * frame is `1`; a mid-stream error frame leaves a started stream at `0`.
+ */
+async function runApiListenCli(
+	parsed: ApiCliArgs,
+	args: readonly string[],
+): Promise<number> {
+	const format = inferApiFormat(args, parsed);
+	const controller = new AbortController();
+	const onSigint = (): void => controller.abort();
+	process.on("SIGINT", onSigint);
+	let exitCode = 0;
+	let first = true;
+	try {
+		for await (const envelope of apiListen(
+			parsed,
+			Bun.env,
+			controller.signal,
+		)) {
+			const line = renderApiStreamLine(envelope, format, {
+				raw: parsed.raw,
+				verbose: parsed.verbose,
+			});
+			if (envelope.ok) {
+				console.log(line);
+			} else {
+				console.error(line);
+				if (first) {
+					exitCode = 1;
+				}
+			}
+			first = false;
+		}
+	} finally {
+		process.off("SIGINT", onSigint);
+	}
+	return exitCode;
+}
+
+function inferApiFormat(
+	args: readonly string[],
+	parsed?: ApiCliArgs,
+): ApiOutputFormat {
+	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 &&
+			apiOutputFormats.includes(value as ApiOutputFormat)
+		) {
+			return value as ApiOutputFormat;
+		}
+	}
+	// Honor CENTRS_FORMAT on the parse-time error path so the catch render matches
+	// buildApiErrorEnvelope's env-aware `meta.operation.request.format`. CLI flags
+	// above still win.
+	const envFormat = Bun.env["CENTRS_FORMAT"];
+	if (
+		envFormat !== undefined &&
+		apiOutputFormats.includes(envFormat as ApiOutputFormat)
+	) {
+		return envFormat as ApiOutputFormat;
+	}
+	// api is machine-first: default to the structured json envelope, not text.
+	return "json";
+}
+
+function parseIntegerFlag(value: string, flag: string): number {
+	// Validate the whole token: `Number.parseInt` would silently accept prefixes
+	// like `8728ms` / `10abc` and send a request to the wrong port/count.
+	if (!/^-?\d+$/.test(value.trim())) {
+		throw new Error(`${flag} must be an integer; got ${value}.`);
+	}
+	return Number.parseInt(value, 10);
+}
+
+function parseBooleanFlag(value: string, flag: string): boolean {
+	if (["true", "1", "yes", "on"].includes(value.toLowerCase())) {
+		return true;
+	}
+	if (["false", "0", "no", "off"].includes(value.toLowerCase())) {
+		return false;
+	}
+	throw new Error(`${flag} must be true or false; got ${value}.`);
+}

package/src/cli/common.ts

@@ -6,6 +6,8 @@
  * together.
  */
 
+import { CentrsError } from "../errors.ts";
+
 export interface CliCommandOption {
 	flag: string;
 	valueName?: string;
@@ -31,6 +33,68 @@ export function expectValue(
 	return value;
 }
 
+/** Flatten an option's `flag` field ("-X / --method") into individual `-`/`--` tokens. */
+export function knownFlags(options: readonly CliCommandOption[]): string[] {
+	const flags: string[] = [];
+	for (const option of options) {
+		for (const token of option.flag.split("/")) {
+			const trimmed = token.trim();
+			if (trimmed.startsWith("-")) {
+				flags.push(trimmed);
+			}
+		}
+	}
+	return flags;
+}
+
+function editDistance(a: string, b: string): number {
+	let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+	for (let i = 1; i <= a.length; i += 1) {
+		const curr = [i];
+		for (let j = 1; j <= b.length; j += 1) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(
+				(curr[j - 1] ?? 0) + 1,
+				(prev[j] ?? 0) + 1,
+				(prev[j - 1] ?? 0) + cost,
+			);
+		}
+		prev = curr;
+	}
+	return prev[b.length] ?? 0;
+}
+
+/** Closest known flags to `arg` (Levenshtein ≤ 2 — tight enough to avoid noise), nearest first, capped at 3. */
+export function closestFlags(arg: string, flags: readonly string[]): string[] {
+	return [...new Set(flags)]
+		.map((flag) => ({ flag, distance: editDistance(arg, flag) }))
+		.filter(({ distance }) => distance <= 2)
+		.sort((left, right) => left.distance - right.distance)
+		.slice(0, 3)
+		.map(({ flag }) => flag);
+}
+
+/**
+ * Actionable "unknown flag" error: lists the closest canonical matches (and
+ * aliases) so humans and agents can recover (commands/AGENTS.md → "Did you
+ * mean?"). Shared seam — parsers pass their own `command` + option metadata.
+ */
+export function unknownFlagError(
+	command: string,
+	arg: string,
+	options: readonly CliCommandOption[],
+): CentrsError {
+	const suggestions = closestFlags(arg, knownFlags(options));
+	const hint =
+		suggestions.length > 0 ? ` Did you mean ${suggestions.join(", ")}?` : "";
+	return new CentrsError({
+		code: "input/invalid-command",
+		summary: `Unknown ${command} flag: ${arg}.${hint}`,
+		remediation: `Run \`centrs ${command} --help\` to see the supported flags${suggestions.length > 0 ? " and their aliases" : ""}.`,
+		context: { flag: arg, suggestions },
+	});
+}
+
 export function renderCommandHelp(
 	describe: string,
 	command: CliCommandMetadata,