@tikoci/centrs 0.1.1 → 0.1.3

package/src/cli/transfer.ts

@@ -6,16 +6,20 @@
  * `../cli.ts`. Mirrors the shape of `./retrieve.ts`.
  */
 
+import { fanoutExitCode } from "../core/fanout.ts";
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import {
 	buildTransferErrorEnvelope,
+	buildTransferFanoutErrorEnvelope,
 	CentrsError,
 	describeCentrs,
 	renderTransferEnvelope,
+	renderTransferFanoutEnvelope,
 	type TransferOutputFormat,
 	type TransferRequest,
 	type TransferVerb,
 	transfer,
+	transferFanout,
 	transferOutputFormats,
 	transferVerbs,
 } from "../index.ts";
@@ -23,6 +27,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -32,6 +37,14 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import {
+	buildTargetSelection,
+	consumeSelectionFlag,
+	emptySelectionFlags,
+	isFanoutMode,
+	type SelectionFlags,
+	selectionCommandOptions,
+} from "./selection.ts";
 
 /** Sub-verb aliases, resolved to canonical verbs silently (commands/AGENTS.md). */
 const VERB_ALIASES: Record<string, TransferVerb> = {
@@ -73,6 +86,18 @@ export const transferCommand: CliCommandMetadata = {
 			valueName: "(--overwrite)",
 			description: "Replace an existing destination. Default refuses it.",
 		},
+		...selectionCommandOptions,
+		{
+			flag: "--out-dir",
+			valueName: "<dir>",
+			description:
+				"`download` fan-out only: write one file per target into <dir>, named by CDB identity. Required when downloading across a selection.",
+		},
+		{
+			flag: "--yes",
+			description:
+				"Confirm a mutating fan-out (upload/remove/mkdir/copy) across multiple routers in non-interactive runs.",
+		},
 		{
 			flag: "--verify",
 			valueName: "<size|checksum|off>",
@@ -159,6 +184,17 @@ export async function runTransferCli(
 			console.log(renderCommandHelp(describeCentrs(), transferCommand));
 			return 0;
 		}
+
+		// Fan-out mode (a selector flag, or >1 positional target before the verb)
+		// has its own envelope shape, single up-front write-confirm, and exit code.
+		if (isFanoutMode(parsed.selectionFlags, parsed.targetPositionals.length)) {
+			return await runTransferFanoutCli(
+				parsed.request,
+				parsed.selectionFlags,
+				parsed.targetPositionals,
+				args,
+			);
+		}
 		request = parsed.request;
 
 		const envelope = await transfer(request);
@@ -196,12 +232,14 @@ export async function runTransferCli(
 				tips,
 			);
 			console.error(
+				// codeql[js/clear-text-logging] The transfer error path redacts password/cdbPassword before any renderer (redactTransferRequest), and buildTransferErrorEnvelope only emits targetInput.
 				renderTransferEnvelope(envelope, format, {
 					verbose: safeRequest?.verbose ?? false,
 				}),
 			);
 		} else {
 			console.error(
+				// codeql[js/clear-text-logging] Credentials are redacted from the request before rendering (redactTransferRequest) and never reach the error/stderr; same known false positive dismissed across all CLI commands.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -217,6 +255,46 @@ export async function runTransferCli(
 	}
 }
 
+async function runTransferFanoutCli(
+	request: TransferRequest,
+	selectionFlags: SelectionFlags,
+	targetPositionals: readonly string[],
+	args: readonly string[],
+): Promise<number> {
+	const selection = buildTargetSelection(selectionFlags, targetPositionals);
+	const format = inferRequestedFormat(args, request);
+	try {
+		const envelope = await transferFanout(
+			{ ...request, stdinIsTty: process.stdin.isTTY },
+			selection,
+			Bun.env,
+			{},
+			{ concurrency: selectionFlags.concurrency, allowAdhoc: true },
+		);
+		console.log(
+			renderTransferFanoutEnvelope(envelope, format, {
+				verbose: request.verbose ?? false,
+			}),
+		);
+		// Granular exit contract: 0 all-ok / 2 partial / 1 all-failed.
+		return fanoutExitCode(envelope);
+	} catch (error) {
+		// Strip credentials before any renderer touches the request (stderr/CI logs):
+		// pass an explicitly redacted request, with no raw-request fallback path.
+		const envelope = buildTransferFanoutErrorEnvelope(
+			{ ...request, password: undefined, cdbPassword: undefined },
+			error,
+		);
+		console.error(
+			// codeql[js/clear-text-logging] No secret logged: request is redactTransferRequest'd (password/cdbPassword stripped) before the builder; fan-out error meta is {target:{},via,settings:{}}.
+			renderTransferFanoutEnvelope(envelope, format, {
+				verbose: request.verbose ?? false,
+			}),
+		);
+		return 1;
+	}
+}
+
 /**
  * Strip credential fields before a failed request is handed to the error
  * envelope/text renderers. Those outputs land on stderr (and CI logs), so the
@@ -237,13 +315,16 @@ function redactTransferRequest(
 interface ParsedTransfer {
 	help?: boolean;
 	request: TransferRequest;
+	selectionFlags: SelectionFlags;
+	targetPositionals: readonly string[];
 }
 
-function parseTransferCliArgs(
+export function parseTransferCliArgs(
 	args: readonly string[],
 	fixedVerb?: TransferVerb,
 ): ParsedTransfer {
 	const flags: Partial<TransferRequest> & { verbose?: boolean } = {};
+	const selectionFlags = emptySelectionFlags();
 	const positional: string[] = [];
 	let help = false;
 	// `--verify <mode>` and `--no-verify` both map to the single `verify` field,
@@ -326,28 +407,39 @@ function parseTransferCliArgs(
 			case "--no-validate":
 				flags.validate = false;
 				break;
+			case "--out-dir":
+				flags.outDir = expectValue(args, ++index, arg);
+				break;
+			case "--yes":
+				flags.yes = true;
+				break;
 			case "--verbose":
 				flags.verbose = true;
 				break;
-			default:
+			default: {
+				const consumed = consumeSelectionFlag(args, index, selectionFlags);
+				if (consumed !== null) {
+					index = consumed;
+					break;
+				}
 				// A lone `-` is the stdin/stdout positional (upload from / download
 				// to a pipe), not a flag.
 				if (arg !== "-" && arg.startsWith("-")) {
-					throw new CentrsError({
-						code: "input/invalid-command",
-						summary: `Unknown transfer flag: ${arg}`,
-						remediation:
-							"Remove the flag or run `centrs transfer --help` for the supported options.",
-						context: { flag: arg },
-					});
+					throw unknownFlagError("transfer", arg, transferCommand.options);
 				}
 				positional.push(arg);
 				break;
+			}
 		}
 	}
 
 	if (help) {
-		return { help: true, request: { verb: fixedVerb ?? "list" } };
+		return {
+			help: true,
+			request: { verb: fixedVerb ?? "list" },
+			selectionFlags,
+			targetPositionals: [],
+		};
 	}
 
 	if (sawNoVerify && explicitVerify !== undefined && explicitVerify !== "off") {
@@ -359,67 +451,101 @@ function parseTransferCliArgs(
 		});
 	}
 
-	const request = assemblePositionals(positional, flags, fixedVerb);
-	return { request };
+	const { request, targetPositionals } = assemblePositionals(
+		positional,
+		flags,
+		selectionFlags,
+		fixedVerb,
+	);
+	return { request, selectionFlags, targetPositionals };
+}
+
+/** Whether a positional token is a transfer verb keyword (canonical or alias). */
+function isTransferVerbToken(token: string): boolean {
+	return transferVerbs.includes(token as TransferVerb) || token in VERB_ALIASES;
 }
 
 /**
- * Map positionals to the per-verb request shape. For the top-level alias the
- * verb is fixed and the first positional is `<router>`; for `centrs transfer`
- * the positionals are `<router> <verb> …`.
+ * Map positionals to the per-verb request shape and split fan-out targets. The
+ * boundary is the **verb keyword**: positionals before it are targets, the verb +
+ * paths follow. The top-level `upload`/`download` alias fixes the verb, so its
+ * positionals are paths; with a selector present, positional fan-out targets are
+ * not expressible there (fan-out comes from the selector). See
+ * `docs/CONSTITUTION.md` (Target selection).
  */
 function assemblePositionals(
 	positional: readonly string[],
 	flags: Partial<TransferRequest> & { verbose?: boolean },
+	selectionFlags: SelectionFlags,
 	fixedVerb?: TransferVerb,
-): TransferRequest {
-	let targetInput: string | undefined;
+): { request: TransferRequest; targetPositionals: readonly string[] } {
+	const hasSelector = isFanoutMode(selectionFlags, 0);
 	let verb: TransferVerb;
+	let targetPositionals: readonly string[];
 	let rest: readonly string[];
 
 	if (fixedVerb) {
-		targetInput = positional[0];
 		verb = fixedVerb;
-		rest = positional.slice(1);
-	} else {
-		targetInput = positional[0];
-		const rawVerb = positional[1];
-		// A missing target gets the tagged missing-target error (CDB picker tip);
-		// a present target with no verb is a distinct "which verb?" usage error.
-		if (!targetInput) {
-			throw missingTargetError({
-				command: "transfer",
-				summary:
-					"`centrs transfer` requires a <router> target and a verb (upload|download|list|remove|mkdir|copy).",
-				remediation:
-					"Pass the target then a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
-			});
+		if (hasSelector) {
+			// alias + selector: targets come from the selector; positionals are paths.
+			targetPositionals = [];
+			rest = positional;
+		} else {
+			targetPositionals = positional[0] !== undefined ? [positional[0]] : [];
+			rest = positional.slice(1);
 		}
-		if (!rawVerb) {
+	} else {
+		const verbIndex = positional.findIndex(isTransferVerbToken);
+		if (verbIndex === -1) {
+			if (positional.length === 0 && !hasSelector) {
+				throw missingTargetError({
+					command: "transfer",
+					summary:
+						"`centrs transfer` requires a <router> target and a verb (upload|download|list|remove|mkdir|copy).",
+					remediation:
+						"Pass the target then a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
+				});
+			}
 			throw new CentrsError({
 				code: "input/invalid-command",
 				summary:
-					"`centrs transfer` requires a verb after the <router> (upload|download|list|remove|mkdir|copy).",
+					"`centrs transfer` requires a verb (upload|download|list|remove|mkdir|copy).",
 				remediation:
 					"Pass a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
-				context: { targetInput, verb: rawVerb },
+				context: { positionals: positional },
 			});
 		}
-		verb = canonicalVerb(rawVerb);
-		rest = positional.slice(2);
+		targetPositionals = positional.slice(0, verbIndex);
+		verb = canonicalVerb(positional[verbIndex] as string);
+		rest = positional.slice(verbIndex + 1);
 	}
 
-	if (!targetInput) {
-		throw missingTargetError({
-			command: "transfer",
-			summary: "`centrs transfer` requires a <router> target.",
-			remediation:
-				"Pass the router host/identity as the first argument; run `centrs transfer --help` for the command shape.",
-		});
+	const request: TransferRequest = { verb, ...flags };
+	applyVerbPaths(request, verb, rest);
+
+	// Single-target (not fan-out mode) needs exactly one resolved target.
+	if (!isFanoutMode(selectionFlags, targetPositionals.length)) {
+		const targetInput = targetPositionals[0];
+		if (!targetInput) {
+			throw missingTargetError({
+				command: "transfer",
+				summary: "`centrs transfer` requires a <router> target.",
+				remediation:
+					"Pass the router host/identity as the first argument; run `centrs transfer --help` for the command shape.",
+			});
+		}
+		request.targetInput = targetInput;
 	}
 
-	const request: TransferRequest = { verb, targetInput, ...flags };
+	return { request, targetPositionals };
+}
 
+/** Map the post-verb positionals onto the per-verb request fields. */
+function applyVerbPaths(
+	request: TransferRequest,
+	verb: TransferVerb,
+	rest: readonly string[],
+): void {
 	switch (verb) {
 		case "upload":
 			request.local = rest[0];
@@ -441,8 +567,6 @@ function assemblePositionals(
 			request.remoteDest = rest[1];
 			break;
 	}
-
-	return request;
 }
 
 function canonicalVerb(raw: string): TransferVerb {

package/src/cli.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env bun
 
+import { apiCommand, runApiCli } from "./cli/api.ts";
 import { btestCommand, runBtestCli } from "./cli/btest.ts";
 import { devicesCommand, runDevicesCli } from "./cli/devices.ts";
 import { discoverCommand, runDiscoverCli } from "./cli/discover.ts";
 import { executeCommand, runExecuteCli } from "./cli/execute.ts";
 import { mcpCommand, runMcpCli } from "./cli/mcp.ts";
 import { retrieveCommand, runRetrieveCli } from "./cli/retrieve.ts";
+import { runSettingsCli, settingsCommand } from "./cli/settings.ts";
 import { runTerminalCli, terminalCommand } from "./cli/terminal.ts";
 import { runTransferCli, transferCommand } from "./cli/transfer.ts";
 import { asCentrsError, formatCentrsErrorText } from "./errors.ts";
@@ -14,12 +16,14 @@ import { describeCentrs, plannedProtocols, plannedSurfaces } from "./index.ts";
 const commandSummaries: ReadonlyArray<{ name: string; summary: string }> = [
 	retrieveCommand,
 	executeCommand,
+	apiCommand,
 	transferCommand,
 	terminalCommand,
 	devicesCommand,
 	discoverCommand,
 	btestCommand,
 	mcpCommand,
+	settingsCommand,
 ].map((command) => ({ name: command.name, summary: command.summary }));
 
 export function renderCliHelp(): string {
@@ -54,6 +58,9 @@ export async function runCli(
 		if (command === "execute") {
 			return await runExecuteCli(rest);
 		}
+		if (command === "api") {
+			return await runApiCli(rest);
+		}
 		if (command === "transfer") {
 			return await runTransferCli(rest);
 		}
@@ -80,8 +87,29 @@ export async function runCli(
 		if (command === "mcp") {
 			return await runMcpCli(rest);
 		}
+		if (command === "settings") {
+			return await runSettingsCli(rest);
+		}
+		// `stream` (and the `tail` shorthand) folded into `api --stream`.
+		if (command === "stream" || command === "tail") {
+			console.error(
+				formatCentrsErrorText(
+					asCentrsError(
+						new Error(`\`centrs ${command}\` has been folded into \`api\`.`),
+						{
+							code: "input/invalid-command",
+							summary: `\`centrs ${command}\` is no longer a command — open-ended follow is now \`api … --stream\`.`,
+							remediation:
+								"Use `centrs api <router> <endpoint> --stream` (native-api only), e.g. `centrs api edge1 ip/address --stream`.",
+						},
+					),
+				),
+			);
+			return 1;
+		}
 
 		console.error(
+			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			formatCentrsErrorText(
 				asCentrsError(new Error(`Unknown centrs command: ${command}`), {
 					code: "input/invalid-command",
@@ -96,6 +124,7 @@ export async function runCli(
 		// to a structured envelope, so reaching here means an unconverted throw
 		// escaped. Never let a raw stack trace reach the user.
 		console.error(
+			// codeql[js/clear-text-logging] password reaches here only as SettingSource provenance ({kind,key}), never the value — see CommonSettingsMeta.password in src/core/envelope.ts.
 			formatCentrsErrorText(
 				asCentrsError(error, {
 					code: "internal/unhandled",

package/src/core/error-catalog.ts

@@ -53,6 +53,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/empty-group",
 		summary: "The named CDB group contains no records.",
 	},
+	{
+		code: "cdb/empty-selection",
+		summary: "The target selection matched no CDB records.",
+	},
 	{
 		code: "cdb/invalid-option",
 		summary: "A comment kv-soup option carried an invalid value.",
@@ -129,10 +133,27 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 
 	// input/*
+	{
+		code: "input/incomplete-gps",
+		summary: "lat/lon (or a --gps tuple) were not given as a complete pair.",
+	},
+	{
+		code: "input/invalid-altitude",
+		summary: "The altitude is not a number, or altitude-type is not MSL/AGL.",
+	},
+	{
+		code: "input/invalid-bbox",
+		summary:
+			"The --bbox is not four lat-first corners with south<=north and west<=east.",
+	},
 	{
 		code: "input/invalid-command",
 		summary: "The request shape was invalid (bad or missing arguments).",
 	},
+	{
+		code: "input/invalid-coordinate",
+		summary: "The latitude or longitude is not a number in its valid range.",
+	},
 	{
 		code: "input/invalid-match",
 		summary:
@@ -143,6 +164,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"A file path contains a character the transport cannot quote (e.g. a quote or newline).",
 	},
+	{
+		code: "input/invalid-radius",
+		summary:
+			"The --near radius is not a number with an optional m/km/mi/ft suffix.",
+	},
 	{
 		code: "input/invalid-routeros-path",
 		summary: "The RouterOS path is malformed (it must be slash-prefixed).",
@@ -181,6 +207,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "internal/native-api-length",
 		summary: "A native-API word length could not be encoded.",
 	},
+	{
+		code: "internal/settings-failed",
+		summary: "The settings command failed with an unexpected internal error.",
+	},
 	{
 		code: "internal/unhandled",
 		summary: "An unexpected internal error occurred (this is a centrs bug).",
@@ -218,6 +248,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The RouterOS native API returned a !trap with no more specific mapping.",
 	},
+	{
+		code: "routeros/btest-connection-count-single-stream",
+		summary:
+			"Fewer TCP data connections were opened than --connection-count requested (e.g. authenticated multi-connection is not yet supported), so throughput will not scale to the full count.",
+	},
 	{
 		code: "routeros/btest-protocol",
 		summary: "A bandwidth-test (btest) packet could not be decoded.",
@@ -227,6 +262,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The btest server refused a client because max-sessions is reached.",
 	},
+	{
+		code: "routeros/btest-udp-tx-size-ignored",
+		summary:
+			"For UDP --direction both, the btest wire protocol carries a single tx-size; --remote-udp-tx-size is ignored and --local-udp-tx-size is used for both directions.",
+	},
 	{
 		code: "routeros/command-failed",
 		summary: "RouterOS reported a command failure.",
@@ -285,6 +325,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 
 	// settings/*
+	{
+		code: "settings/consequential-value",
+		summary:
+			"`settings set` accepted a syntactically valid value with a real, non-obvious consequence (e.g. a global --insecure default, or a transfer-via value gated elsewhere).",
+	},
 	{
 		code: "settings/invalid-boolean",
 		summary: "A boolean-like setting received a non-boolean value.",
@@ -305,6 +350,21 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "settings/invalid-via",
 		summary: "An unsupported protocol identifier was supplied to --via.",
 	},
+	{
+		code: "settings/reserved-key",
+		summary:
+			"`settings set`/`reset` refused a credential-shaped or self-referential CENTRS_* key.",
+	},
+	{
+		code: "settings/skip-env-file-active",
+		summary:
+			"`settings print` ran under --skip-env-file; the shown centrs.env values would not apply to other commands run in the same environment.",
+	},
+	{
+		code: "settings/unknown-key",
+		summary:
+			"`settings get`/`set` received a token that is not a recognized CENTRS_*-shaped setting.",
+	},
 	{
 		code: "settings/unsafe-protocol-blocked",
 		summary:
@@ -415,6 +475,15 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
 	},
+	{
+		code: "usage/fanout-not-supported",
+		summary:
+			"The command or mode cannot fan out across multiple targets (e.g. terminal, --listen/--stream).",
+	},
+	{
+		code: "usage/invalid-method",
+		summary: "The -X/--method value is not a supported HTTP method.",
+	},
 	{
 		code: "usage/missing-group",
 		summary: "The operation requires a non-empty --group value.",