@tikoci/centrs 0.1.2 → 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

@@ -7,6 +7,7 @@ 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";
@@ -22,6 +23,7 @@ const commandSummaries: ReadonlyArray<{ name: string; summary: string }> = [
 	discoverCommand,
 	btestCommand,
 	mcpCommand,
+	settingsCommand,
 ].map((command) => ({ name: command.name, summary: command.summary }));
 
 export function renderCliHelp(): string {
@@ -85,6 +87,9 @@ 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(
@@ -104,6 +109,7 @@ export async function runCli(
 		}
 
 		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",
@@ -118,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).",
@@ -295,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.",
@@ -315,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:
@@ -425,6 +475,11 @@ 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.",

package/src/core/fanout.ts

@@ -11,9 +11,18 @@
  * and counting.
  */
 
-import { CentrsError } from "../errors.ts";
+import { CentrsError, serializeCentrsError } from "../errors.ts";
 import type { RouterOsProtocol } from "../protocols/index.ts";
-import type { FanoutSummary } from "./envelope.ts";
+import type {
+	CentrsEnvelope,
+	CentrsErrorEnvelope,
+	CentrsSuccessEnvelope,
+	CommonSettingsMeta,
+	EnvelopeTargetMeta,
+	FanoutData,
+	FanoutSummary,
+	Warning,
+} from "./envelope.ts";
 
 /** Transport-aware default worker-pool size (REST drops parallel POSTs above ~8). */
 export const FANOUT_CONCURRENCY_DEFAULTS: Record<
@@ -158,3 +167,135 @@ export function fanoutBackoffMs(attempt: number): number {
 export function defaultFanoutSleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/**
+ * The per-command fan-out loop, generic over the selection member, the resolved
+ * per-target plan, and the inner envelope type. Mirrors the original
+ * `retrieveGroup` worker exactly: resolve each member (a resolve failure becomes
+ * an inner error envelope, never a throw out of the batch); run the resolved
+ * request through {@link runWithRetry} (a retryable transient drop is retried,
+ * everything else recovers to an inner error envelope). Results are returned in
+ * input (record-index) order via {@link runBoundedPool}.
+ */
+export async function runFanout<Member, Resolved, Env>(opts: {
+	members: readonly Member[];
+	concurrency: number;
+	resolve: (member: Member) => Promise<Resolved> | Resolved;
+	onResolveError: (member: Member, error: unknown) => Env;
+	execute: (resolved: Resolved, member: Member) => Promise<Env>;
+	onExecuteError: (resolved: Resolved, member: Member, error: unknown) => Env;
+	sleep?: (ms: number) => Promise<void>;
+}): Promise<Env[]> {
+	return runBoundedPool(opts.members, opts.concurrency, async (member) => {
+		let resolved: Resolved;
+		try {
+			resolved = await opts.resolve(member);
+		} catch (error) {
+			return opts.onResolveError(member, error);
+		}
+		return runWithRetry<Env>(
+			() => opts.execute(resolved, member),
+			(error) => opts.onExecuteError(resolved, member, error),
+			{ sleep: opts.sleep },
+		);
+	});
+}
+
+/**
+ * The uniform fan-out process exit code (granular 0/2/1; see
+ * `docs/CONSTITUTION.md`, Target selection). `0` = every target ok (or an empty
+ * selection); `2` = partial (some ok, some failed); `1` = orchestration error
+ * (outer `ok: false`) OR every target failed. Decoupled from the envelope's
+ * outer `ok`, which only reports orchestration success.
+ */
+export function fanoutExitCode(envelope: {
+	ok: boolean;
+	data?: { summary?: FanoutSummary };
+}): 0 | 1 | 2 {
+	if (!envelope.ok) {
+		return 1;
+	}
+	const summary = envelope.data?.summary;
+	if (!summary || summary.total === 0 || summary.failed === 0) {
+		return 0;
+	}
+	if (summary.ok === 0) {
+		return 1;
+	}
+	return 2;
+}
+
+/** Collapse per-target `via` to one value, or `null` when targets disagree. */
+export function commonVia(
+	targets: readonly { meta: { via: RouterOsProtocol | null } }[],
+): RouterOsProtocol | null {
+	let via: RouterOsProtocol | null | undefined;
+	for (const target of targets) {
+		const candidate = target.meta.via;
+		if (via === undefined) {
+			via = candidate;
+		} else if (via !== candidate) {
+			return null;
+		}
+	}
+	return via ?? null;
+}
+
+/**
+ * Assemble the locked fan-out success envelope: `data = { summary, targets }`,
+ * outer `ok: true` = orchestration succeeded. The command owns its outer
+ * `operation` meta shape and passes it in.
+ */
+export function buildFanoutEnvelope<Data, Op, OuterOp>(input: {
+	summary: FanoutSummary;
+	targets: readonly CentrsEnvelope<Data, Op>[];
+	warnings: readonly Warning[];
+	settings: CommonSettingsMeta;
+	via: RouterOsProtocol | null;
+	operation: OuterOp;
+}): CentrsSuccessEnvelope<FanoutData<Data, Op>, OuterOp> {
+	return {
+		ok: true,
+		data: { summary: input.summary, targets: input.targets },
+		warnings: input.warnings,
+		tips: [],
+		meta: {
+			target: {},
+			via: input.via,
+			settings: input.settings,
+			operation: input.operation,
+		},
+	};
+}
+
+/**
+ * Build an INNER per-target error envelope for a member that failed to resolve
+ * (before any transport attempt). Carries the member's target meta so the
+ * fan-out output identifies which device failed.
+ */
+export function buildFanoutResolveFailure<Op = unknown>(input: {
+	error: unknown;
+	target: EnvelopeTargetMeta;
+	warnings?: readonly Warning[];
+	summary?: string;
+}): CentrsErrorEnvelope<Op> {
+	const centrsError =
+		input.error instanceof CentrsError
+			? input.error
+			: new CentrsError({
+					code: "internal/unhandled",
+					summary: input.summary ?? "Failed to resolve a fanout target.",
+					cause: input.error,
+				});
+	return {
+		ok: false,
+		error: serializeCentrsError(centrsError),
+		warnings: input.warnings ?? [],
+		tips: [],
+		meta: {
+			target: input.target,
+			via: null,
+			settings: {},
+		},
+	};
+}