@tikoci/centrs 0.1.2 → 0.1.4

package/src/cli/retrieve.ts

@@ -4,23 +4,30 @@
  * unchanged from the former monolithic `cli.ts`.
  */
 
-import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
 import {
 	buildRetrieveErrorEnvelope,
 	buildRetrieveFanoutErrorEnvelope,
 	describeCentrs,
+	fanoutExitCode,
 	type RetrieveOutputFormat,
 	type RetrieveRequest,
 	renderRetrieveEnvelope,
 	renderRetrieveFanoutEnvelope,
 	retrieve,
-	retrieveGroup,
+	retrieveFanout,
 	retrieveOutputFormats,
 } from "../index.ts";
+import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -30,11 +37,20 @@ import {
 	missingTargetError,
 	withTips,
 } from "./missing-target.ts";
+import {
+	assertQuickchrExclusive,
+	buildTargetSelection,
+	consumeSelectionFlag,
+	emptySelectionFlags,
+	isFanoutMode,
+	type SelectionFlags,
+	selectionCommandOptions,
+} from "./selection.ts";
 
 export const retrieveCommand: CliCommandMetadata = {
 	name: "retrieve",
 	usage:
-		"centrs retrieve <target> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]",
+		"centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]",
 	summary:
 		"Read RouterOS values through the shared core using the selected protocol.",
 	options: [
@@ -44,18 +60,7 @@ export const retrieveCommand: CliCommandMetadata = {
 			description:
 				"Pin the protocol selector. Defaults to `rest-api` for retrieve.",
 		},
-		{
-			flag: "--group",
-			valueName: "<name>",
-			description:
-				"Fan out over every CDB record in the group. Replaces the <target> positional.",
-		},
-		{
-			flag: "--concurrency",
-			valueName: "<n>",
-			description:
-				"Bounded worker-pool size for `--group` fanout (REST 8, native-api 4 by default).",
-		},
+		...selectionCommandOptions,
 		{
 			flag: "--host",
 			valueName: "<host|url>",
@@ -98,10 +103,16 @@ export const retrieveCommand: CliCommandMetadata = {
 			description: "Request the RouterOS detail/all-attributes shape.",
 		},
 		{
-			flag: "--list-attributes",
+			flag: "--list-attributes / --list",
 			description:
 				"List inspect-derived attributes without running the data call.",
 		},
+		{
+			flag: "--query / --filter",
+			valueName: "<expr>",
+			description:
+				"RouterOS-side row filter (maps to `.query`). Not implemented yet — returns `validation/not-implemented`.",
+		},
 		{
 			flag: "--format",
 			valueName: `<${retrieveOutputFormats.join("|")}>`,
@@ -145,37 +156,50 @@ export const retrieveCommand: CliCommandMetadata = {
 	],
 };
 
+type RetrieveCliArgs = RetrieveRequest & {
+	help?: boolean;
+	selectionFlags?: SelectionFlags;
+	targetPositionals?: readonly string[];
+};
+
 export async function runRetrieveCli(args: readonly string[]): Promise<number> {
-	let request: RetrieveRequest | undefined;
+	let request: RetrieveCliArgs | undefined;
 
 	try {
 		request = parseRetrieveCliArgs(args);
-		if ((request as { help?: boolean }).help) {
+		if (request.help) {
 			console.log(renderCommandHelp(describeCentrs(), retrieveCommand));
 			return 0;
 		}
 
-		const envelope = request.group
-			? await retrieveGroup(request)
-			: await retrieve(request);
+		// Fan-out mode (a selector flag present, or >1 positional target) has its own
+		// envelope shape and granular exit code; a plain single-target call keeps the
+		// single-target envelope.
+		const selectionFlags = request.selectionFlags ?? emptySelectionFlags();
+		const targetPositionals = request.targetPositionals ?? [];
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			return await runRetrieveFanoutCli(
+				request,
+				selectionFlags,
+				targetPositionals,
+				args,
+			);
+		}
+
+		const envelope = await retrieve(request);
 		const resolvedFormat =
 			(
 				envelope.meta.operation as {
 					request?: { format?: RetrieveOutputFormat };
 				}
 			)?.request?.format ?? "text";
-		const output = request.group
-			? renderRetrieveFanoutEnvelope(
-					envelope as Parameters<typeof renderRetrieveFanoutEnvelope>[0],
-					resolvedFormat,
-					{ verbose: request.verbose },
-				)
-			: renderRetrieveEnvelope(
-					envelope as Parameters<typeof renderRetrieveEnvelope>[0],
-					resolvedFormat,
-					{ verbose: request.verbose },
-				);
-		console.log(output);
+		console.log(
+			renderRetrieveEnvelope(
+				envelope as Parameters<typeof renderRetrieveEnvelope>[0],
+				resolvedFormat,
+				{ verbose: request.verbose },
+			),
+		);
 		return 0;
 	} catch (error) {
 		const format = inferRequestedFormat(args, request);
@@ -186,31 +210,23 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 				})
 			: [];
 		if (format === "json" || format === "yaml") {
-			if (request?.group) {
-				const envelope = buildRetrieveFanoutErrorEnvelope(request, error);
-				console.error(
-					renderRetrieveFanoutEnvelope(envelope, format, {
-						verbose: request?.verbose ?? false,
-					}),
-				);
-			} else {
-				// When parsing failed before a request existed, build the error
-				// envelope from an empty request rather than reconstructing positionals
-				// from raw args — a credential value (e.g. the token after
-				// `--password` / `--cdb-password`) would otherwise be echoed as
-				// `meta.target.input`.
-				const envelope = withTips(
-					buildRetrieveErrorEnvelope(request ?? { path: "" }, error),
-					tips,
-				);
-				console.error(
-					renderRetrieveEnvelope(envelope, format, {
-						verbose: request?.verbose ?? false,
-					}),
-				);
-			}
+			// When parsing failed before a request existed, build the error envelope
+			// from an empty request rather than reconstructing positionals from raw
+			// args — a credential value (e.g. the token after `--password` /
+			// `--cdb-password`) would otherwise be echoed as `meta.target.input`.
+			const envelope = withTips(
+				buildRetrieveErrorEnvelope(request ?? { path: "" }, error),
+				tips,
+			);
+			console.error(
+				// codeql[js/clear-text-logging] Twin of the established redacted-request dismissals: error builders carry only targetInput (host)+via (protocol); the raw password never reaches this render.
+				renderRetrieveEnvelope(envelope, format, {
+					verbose: request?.verbose ?? false,
+				}),
+			);
 		} else {
 			console.error(
+				// codeql[js/clear-text-logging] Same false-positive pattern: password parsed from args never reaches error.message in the text-format catch path.
 				formatCentrsErrorText(
 					asCentrsError(error, {
 						code: "input/invalid-command",
@@ -228,12 +244,50 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 	}
 }
 
-function parseRetrieveCliArgs(args: readonly string[]): RetrieveRequest & {
-	help?: boolean;
-} {
-	const request: RetrieveRequest & { help?: boolean } = {
+async function runRetrieveFanoutCli(
+	request: RetrieveCliArgs,
+	selectionFlags: SelectionFlags,
+	targetPositionals: readonly string[],
+	args: readonly string[],
+): Promise<number> {
+	const selection = buildTargetSelection(selectionFlags, targetPositionals);
+	const format = inferRequestedFormat(args, request);
+	try {
+		const envelope = await retrieveFanout(
+			request,
+			selection,
+			Bun.env,
+			{},
+			{
+				concurrency: selectionFlags.concurrency,
+				allowAdhoc: true,
+			},
+		);
+		const resolvedFormat = envelope.meta.operation?.request.format ?? format;
+		console.log(
+			renderRetrieveFanoutEnvelope(envelope, resolvedFormat, {
+				verbose: request.verbose ?? false,
+			}),
+		);
+		// Granular exit contract: 0 all-ok / 2 partial / 1 all-failed.
+		return fanoutExitCode(envelope);
+	} catch (error) {
+		const envelope = buildRetrieveFanoutErrorEnvelope(request, error);
+		console.error(
+			// codeql[js/clear-text-logging] Twin of #80/#81/#83. No secret logged: error builders carry only targetInput (host)+via (protocol); serializeCentrsError holds code/summary/remediation/context.
+			renderRetrieveFanoutEnvelope(envelope, format, {
+				verbose: request.verbose ?? false,
+			}),
+		);
+		return 1;
+	}
+}
+
+function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
+	const request: RetrieveCliArgs = {
 		path: "",
 	};
+	const selectionFlags = emptySelectionFlags();
 	const positional: string[] = [];
 
 	for (let index = 0; index < args.length; index += 1) {
@@ -314,15 +368,6 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveRequest & {
 			case "--resolve":
 				request.resolve = expectValue(args, ++index, arg);
 				break;
-			case "--group":
-				request.group = expectValue(args, ++index, arg);
-				break;
-			case "--concurrency":
-				request.concurrency = Number.parseInt(
-					expectValue(args, ++index, arg),
-					10,
-				);
-				break;
 			case "--validate":
 				request.validate = true;
 				break;
@@ -332,35 +377,73 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveRequest & {
 			case "--verbose":
 				request.verbose = true;
 				break;
-			default:
+			default: {
+				const consumed = consumeSelectionFlag(args, index, selectionFlags);
+				if (consumed !== null) {
+					index = consumed;
+					break;
+				}
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown retrieve flag: ${arg}`);
+					throw unknownFlagError("retrieve", arg, retrieveCommand.options);
 				}
 				positional.push(arg);
 				break;
+			}
 		}
 	}
 
+	request.selectionFlags = selectionFlags;
+
 	if (request.help) {
 		return request;
 	}
 
-	if (request.group !== undefined) {
-		if (positional.length < 1) {
-			throw new Error(
-				"`centrs retrieve --group <name>` requires a <routeros-path>.",
-			);
+	// api/retrieve positional boundary: the FINAL positional is the routeros-path;
+	// every preceding positional is a fan-out target.
+	const path = positional.at(-1) ?? "";
+	const targetPositionals = positional.slice(0, -1);
+	request.path = path;
+	request.targetPositionals = targetPositionals;
+	assertQuickchrExclusive(selectionFlags, targetPositionals.length);
+	// Direct connection overrides conflict with `--quickchr` globally: reject at
+	// parse time 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(request, selectionFlags.quickchr[0] ?? "");
+	}
+
+	if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+		if (positional.length === 0 || path.length === 0) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary:
+					"`centrs retrieve` fan-out requires a <routeros-path> after the selectors/targets.",
+				remediation:
+					"Add the RouterOS menu path as the final positional, e.g. `centrs retrieve --group prod /system/resource`.",
+				context: { command: "retrieve", missingPath: true },
+			});
 		}
-		if (positional.length > 1) {
-			throw new Error(
-				"`centrs retrieve --group <name>` takes only a <routeros-path>; the group replaces the <target> positional.",
-			);
+		return request;
+	}
+
+	// A single `--quickchr <name>` is single-target mode: the machine name is the
+	// target (resolved from the live descriptor inside the resolver); the lone
+	// positional is the routeros-path.
+	if (selectionFlags.quickchr.length === 1) {
+		if (positional.length === 0 || path.length === 0) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: "`centrs retrieve --quickchr` requires a <routeros-path>.",
+				remediation:
+					"Add the RouterOS menu path as the final positional, e.g. `centrs retrieve --quickchr lab /system/resource`.",
+				context: { command: "retrieve", missingPath: true },
+			});
 		}
-		request.path = positional[0] ?? "";
+		request.quickchr = selectionFlags.quickchr[0];
 		return request;
 	}
 
-	if (positional.length === 0) {
+	if (positional.length === 0 || targetPositionals.length === 0) {
 		throw missingTargetError({
 			command: "retrieve",
 			summary: "`centrs retrieve` requires a <target> and a <routeros-path>.",
@@ -368,14 +451,8 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveRequest & {
 				"Pass the router host/identity then the RouterOS path, e.g. `centrs retrieve 192.0.2.10 /system/resource`.",
 		});
 	}
-	if (positional.length < 2) {
-		throw new Error(
-			"`centrs retrieve` requires a <routeros-path> after the <target>.",
-		);
-	}
-
-	request.targetInput = positional[0];
-	request.path = positional[1] ?? "";
+	// Single-target: exactly one target positional (more would be fan-out mode).
+	request.targetInput = targetPositionals[0];
 	return request;
 }
 

package/src/cli/selection.ts

@@ -0,0 +1,260 @@
+/**
+ * Shared target-selection flag parser.
+ *
+ * The fan-out grammar (`--group` / `--where` / `--all` / `--default` /
+ * `--concurrency`) is parsed ONCE here so every command's hand-rolled `switch`
+ * loop delegates to it instead of re-implementing the grammar. This helper owns
+ * ONLY the flag selectors — it does NOT consume positionals, because a
+ * positional means a different thing per command (endpoint / path / command /
+ * transfer verb + paths). Each command splits its own positionals into
+ * `(targetPositionals, operationArgs)` and hands the target positionals to
+ * {@link buildTargetSelection}. See `docs/CONSTITUTION.md` (Target selection).
+ */
+
+import { CentrsError } from "../errors.ts";
+import {
+	type BboxPredicate,
+	type NearPredicate,
+	parseBbox,
+	parseNear,
+	type SelectionWhereClause,
+	type TargetSelection,
+} from "../resolver/index.ts";
+import {
+	type CliCommandOption,
+	expectValue,
+	parseStrictInteger,
+} from "./common.ts";
+
+/**
+ * The shared target-selection flags, as command-help rows. Spread into each
+ * fan-out command's `options` so `<command> --help` lists them and the
+ * "did you mean?" suggester knows them — one source, so a future command can't
+ * forget them.
+ */
+export const selectionCommandOptions: readonly CliCommandOption[] = [
+	{
+		flag: "--group",
+		valueName: "<name>",
+		description:
+			"Fan out across every CDB record in the group (repeatable; de-duped by record index).",
+	},
+	{
+		flag: "--where",
+		valueName: "<attr>=<value>",
+		description:
+			"Device-class selector over CDB facts + core fields (repeatable, AND-combined).",
+	},
+	{
+		flag: "--near",
+		valueName: "<lat>,<lon>,<radius>",
+		description:
+			"Geo selector: devices whose GPS is within radius (m/km/mi/ft; bare number = km). Lat-first.",
+	},
+	{
+		flag: "--bbox",
+		valueName: "<south>,<west>,<north>,<east>",
+		description:
+			"Geo selector: devices whose GPS is inside the lat-first bounding box.",
+	},
+	{
+		flag: "--all",
+		description: "Fan out across every CDB record (excludes `__default__`).",
+	},
+	{
+		flag: "--default",
+		description: "Select the reserved `__default__` record.",
+	},
+	{
+		flag: "--quickchr",
+		valueName: "<name>",
+		description:
+			"Target a running quickchr-managed CHR VM by name (repeatable; fans out when repeated). Exclusive of positional targets and CDB selectors; conflicts with direct connection overrides (--host/--port/--username/--password, and --ssh-key where the command has it).",
+	},
+	{
+		flag: "--concurrency",
+		valueName: "<n>",
+		description:
+			"Max in-flight targets during fan-out (transport-aware default: rest-api 8, native-api 4).",
+	},
+];
+
+/** Mutable accumulator a command threads through its parse loop. */
+export interface SelectionFlags {
+	groups: string[];
+	where: SelectionWhereClause[];
+	near?: NearPredicate;
+	bbox?: BboxPredicate;
+	all: boolean;
+	default: boolean;
+	/** Repeatable `--quickchr <name>` (named-live-provider; exclusive in v1). */
+	quickchr: string[];
+	concurrency?: number;
+}
+
+export function emptySelectionFlags(): SelectionFlags {
+	return { groups: [], where: [], all: false, default: false, quickchr: [] };
+}
+
+/** The selection flag tokens, for a command's `--help` table + unknown-flag suggestions. */
+export const selectionFlagTokens = [
+	"--group",
+	"--where",
+	"--near",
+	"--bbox",
+	"--all",
+	"--default",
+	"--quickchr",
+	"--concurrency",
+] as const;
+
+function parseWhereClause(raw: string): SelectionWhereClause {
+	const eq = raw.indexOf("=");
+	if (eq <= 0) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `--where must be \`<attr>=<value>\`; received: ${raw}`,
+			remediation:
+				"Pass a device-class selector like `--where board=RB5009` (matches a CDB fact or core field).",
+			context: { where: raw },
+		});
+	}
+	return { key: raw.slice(0, eq), value: raw.slice(eq + 1) };
+}
+
+/**
+ * Try to consume one selection flag at `args[index]`. Returns the new loop index
+ * when consumed (the caller sets its index to this and continues), or `null`
+ * when the arg is not a selection flag (the caller handles it). Mutates `acc`.
+ */
+export function consumeSelectionFlag(
+	args: readonly string[],
+	index: number,
+	acc: SelectionFlags,
+): number | null {
+	const arg = args[index];
+	switch (arg) {
+		case "--all":
+			acc.all = true;
+			return index;
+		case "--default":
+			acc.default = true;
+			return index;
+		case "--group":
+			acc.groups.push(expectValue(args, index + 1, arg));
+			return index + 1;
+		case "--where":
+			acc.where.push(parseWhereClause(expectValue(args, index + 1, arg)));
+			return index + 1;
+		case "--near":
+			acc.near = parseNear(expectValue(args, index + 1, arg));
+			return index + 1;
+		case "--bbox":
+			acc.bbox = parseBbox(expectValue(args, index + 1, arg));
+			return index + 1;
+		case "--quickchr":
+			acc.quickchr.push(expectValue(args, index + 1, arg));
+			return index + 1;
+		case "--concurrency": {
+			const raw = expectValue(args, index + 1, arg);
+			const parsed = parseStrictInteger(raw);
+			if (parsed === undefined || parsed < 1) {
+				throw new CentrsError({
+					code: "usage/invalid-concurrency",
+					summary: `--concurrency must be an integer >= 1. Received: ${raw}`,
+					remediation: "Pass a positive integer, e.g. `--concurrency 4`.",
+					context: { concurrency: raw },
+				});
+			}
+			acc.concurrency = parsed;
+			return index + 1;
+		}
+		default:
+			return null;
+	}
+}
+
+/** Assemble a {@link TargetSelection} from parsed flags + the command's target positionals. */
+export function buildTargetSelection(
+	flags: SelectionFlags,
+	positionals: readonly string[],
+): TargetSelection {
+	return {
+		positionals,
+		groups: flags.groups,
+		all: flags.all,
+		default: flags.default,
+		where: flags.where,
+		near: flags.near,
+		bbox: flags.bbox,
+		quickchr: flags.quickchr,
+	};
+}
+
+/** True when any CDB selector flag is present (quickchr and positionals excluded). */
+function hasCdbSelector(flags: SelectionFlags): boolean {
+	return (
+		flags.all ||
+		flags.default ||
+		flags.groups.length > 0 ||
+		flags.where.length > 0 ||
+		flags.near !== undefined ||
+		flags.bbox !== undefined
+	);
+}
+
+/**
+ * `--quickchr` exclusivity (v1, `docs/CONSTITUTION.md` → Resolution providers):
+ * a command targets quickchr machines OR CDB/literal targets, never both.
+ * Commands call this after splitting positionals, in both single-target and
+ * fan-out mode; relaxing it later is additive.
+ */
+export function assertQuickchrExclusive(
+	flags: SelectionFlags,
+	targetPositionalCount: number,
+): void {
+	if (flags.quickchr.length === 0) {
+		return;
+	}
+	if (hasCdbSelector(flags) || targetPositionalCount > 0) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"`--quickchr` is exclusive: a command targets quickchr machines or CDB/literal targets, not both.",
+			remediation:
+				"Drop the positional target / CDB selector (or the `--quickchr` flag) so the selection has one target source.",
+			context: {
+				quickchr: [...flags.quickchr],
+				positionals: targetPositionalCount,
+			},
+		});
+	}
+}
+
+/**
+ * True when any target-taking flag is present, so positionals are operation
+ * args, not targets. Superset of {@link isFanoutMode}'s flag term: a single
+ * `--quickchr` names the target (like a lone positional, still single-target
+ * mode) but already claims the positional slots.
+ */
+export function hasTargetSelector(flags: SelectionFlags): boolean {
+	return hasCdbSelector(flags) || flags.quickchr.length > 0;
+}
+
+/**
+ * Fan-out mode is keyed on INTENT, not resolved count: any selector flag, more
+ * than one positional target, or a repeated `--quickchr`. A plain
+ * single-positional call — and a single `--quickchr <name>` — stays
+ * single-target (never `FanoutData`); a selector that resolves to one/zero
+ * members is still fan-out mode. See `docs/CONSTITUTION.md` (Target selection).
+ */
+export function isFanoutMode(
+	flags: SelectionFlags,
+	targetPositionalCount: number,
+): boolean {
+	return (
+		hasCdbSelector(flags) ||
+		flags.quickchr.length > 1 ||
+		targetPositionalCount > 1
+	);
+}