@tikoci/centrs 0.1.2 → 0.1.4

package/src/cli/btest.ts

@@ -29,8 +29,10 @@ import type { BtestDirection, BtestProtocol } from "../protocols/btest.ts";
 import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
+	type CliCommandOption,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 import {
 	buildTargetSelectionTips,
@@ -93,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",
@@ -127,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("|")}>`,
@@ -136,6 +154,22 @@ export const btestCommand: CliCommandMetadata = {
 	],
 };
 
+/**
+ * btest's single option list documents both subcommands. Scope "did you mean?"
+ * hints to the active mode so a client typo never suggests a server-only flag
+ * (and vice versa). Shared flags carry no `(client)`/`(server)` marker, so they
+ * stay in both; if a marker is ever dropped the flag just widens to both
+ * modes — it degrades to the old behavior, never a crash.
+ */
+function btestOptionsFor(
+	mode: "client" | "server",
+): readonly CliCommandOption[] {
+	const other = mode === "client" ? "(server)" : "(client)";
+	return btestCommand.options.filter(
+		(option) => !option.description.includes(other),
+	);
+}
+
 /** Parse a bandwidth value: a bare integer or a `K`/`M`/`G` suffix (bits/sec). */
 function parseBandwidth(value: string, flag: string): number {
 	const match = value.trim().match(/^(\d+(?:\.\d+)?)([kKmMgG]?)$/);
@@ -276,7 +310,7 @@ function parseClientArgs(args: readonly string[]): ClientCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-"))
-					throw new Error(`Unknown btest client flag: ${arg}`);
+					throw unknownFlagError("btest", arg, btestOptionsFor("client"));
 				if (request.targetInput !== undefined)
 					throw new Error(`Unexpected extra argument: ${arg}`);
 				request.targetInput = arg;
@@ -341,7 +375,7 @@ function parseServerArgs(args: readonly string[]): ServerCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-"))
-					throw new Error(`Unknown btest server flag: ${arg}`);
+					throw unknownFlagError("btest", arg, btestOptionsFor("server"));
 				throw new Error(
 					`\`centrs btest server\` takes no positional arguments; got: ${arg}.`,
 				);

package/src/cli/common.ts

@@ -33,6 +33,17 @@ export function expectValue(
 	return value;
 }
 
+/**
+ * Parse a strictly-integer flag value, or `undefined` when the whole token is
+ * not an integer. Rejects numeric prefixes (`2abc` → undefined, not `2`) and
+ * decimals (`1.5`), which a bare `Number.parseInt` would silently truncate —
+ * the trap shared by `--port` / `--count` / `--concurrency`.
+ */
+export function parseStrictInteger(value: string): number | undefined {
+	const trimmed = value.trim();
+	return /^-?\d+$/.test(trimmed) ? Number.parseInt(trimmed, 10) : undefined;
+}
+
 /** Flatten an option's `flag` field ("-X / --method") into individual `-`/`--` tokens. */
 export function knownFlags(options: readonly CliCommandOption[]): string[] {
 	const flags: string[] = [];

package/src/cli/devices.ts

@@ -4,20 +4,31 @@
  * unchanged from the former monolithic `cli.ts`.
  */
 
-import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+} from "../errors.ts";
 import {
 	addDevice,
+	type BboxPredicate,
 	buildDevicesErrorEnvelope,
 	type CommentKvUpdate,
+	canonicalizeGeoKey,
 	type DevicesCommand,
 	type DevicesEnvelope,
 	type DevicesOutputFormat,
+	type DevicesWhereClause,
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
 	listDevices,
 	listGroups,
 	loadCdb,
+	type NearPredicate,
+	parseBbox,
+	parseGpsTuple,
+	parseNear,
 	recordTypeFromName,
 	removeDevice,
 	renderDevicesEnvelope,
@@ -30,6 +41,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 
 export const devicesCommand: CliCommandMetadata = {
@@ -62,6 +74,24 @@ export const devicesCommand: CliCommandMetadata = {
 			description:
 				"`list` filter / `add`,`edit` first-class group field for the target entry.",
 		},
+		{
+			flag: "--where",
+			valueName: "<attr=value>",
+			description:
+				"`list` only — repeatable device-class filter over CDB facts (AND-combined), e.g. `--where lat=37.7749`.",
+		},
+		{
+			flag: "--near",
+			valueName: "<lat>,<lon>,<radius>",
+			description:
+				"`list` only — GPS filter: devices within radius (m/km/mi/ft; bare number = km). Lat-first.",
+		},
+		{
+			flag: "--bbox",
+			valueName: "<south>,<west>,<north>,<east>",
+			description:
+				"`list` only — GPS filter: devices inside the lat-first bounding box.",
+		},
 		{
 			flag: "--members",
 			description: "`groups` only — expand each group's membership.",
@@ -115,6 +145,36 @@ export const devicesCommand: CliCommandMetadata = {
 			valueName: `<${Object.keys(winBoxCdbRecordType).join("|")}>`,
 			description: "`add` only — record type (default `ipAdmin`).",
 		},
+		{
+			flag: "--lat / --latitude",
+			valueName: "<deg>",
+			description:
+				"`add`,`set` — latitude in decimal degrees (-90..90); a comment-kv fact, paired with --lon.",
+		},
+		{
+			flag: "--lon / --lng / --longitude / --long",
+			valueName: "<deg>",
+			description:
+				"`add`,`set` — longitude in decimal degrees (-180..180); a comment-kv fact, paired with --lat.",
+		},
+		{
+			flag: "--altitude / --alt / --ele / --elevation",
+			valueName: "<meters>",
+			description:
+				"`add`,`set` — altitude in meters (may be negative); a comment-kv fact.",
+		},
+		{
+			flag: "--altitude-type / --alt-type",
+			valueName: "<MSL|AGL>",
+			description:
+				"`add`,`set` — vertical datum for --altitude (default MSL); case-insensitive.",
+		},
+		{
+			flag: "--gps",
+			valueName: "<lat>,<lon>[,<altitude>[,<altitude-type>]]",
+			description:
+				"`add`,`set` — combined lat,lon[,altitude[,altitude-type]] convenience (lat-first; missing altitude-type defaults MSL).",
+		},
 		{
 			flag: "--force",
 			description: "`add` only — overwrite the existing (target, user) entry.",
@@ -164,6 +224,7 @@ interface DevicesCliArgs {
 	cdbFile?: string;
 	cdbPassword?: string;
 	group?: string;
+	where?: string[];
 	via?: string;
 	members?: boolean;
 	explain?: boolean;
@@ -181,6 +242,13 @@ interface DevicesCliArgs {
 	format?: DevicesOutputFormat;
 	target?: string;
 	kvArgs?: string[];
+	lat?: string;
+	lon?: string;
+	altitude?: string;
+	altitudeType?: string;
+	gps?: string;
+	near?: NearPredicate;
+	bbox?: BboxPredicate;
 }
 
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
@@ -206,6 +274,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			case "--group":
 				parsed.group = expectValue(args, ++index, arg);
 				break;
+			case "--where":
+				parsed.where = [
+					...(parsed.where ?? []),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--near":
+				parsed.near = parseNear(expectValue(args, ++index, arg));
+				break;
+			case "--bbox":
+				parsed.bbox = parseBbox(expectValue(args, ++index, arg));
+				break;
 			case "--via":
 				parsed.via = expectValue(args, ++index, arg);
 				break;
@@ -242,6 +322,29 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			case "--record-type":
 				parsed.recordType = expectValue(args, ++index, arg);
 				break;
+			case "--lat":
+			case "--latitude":
+				parsed.lat = expectValue(args, ++index, arg);
+				break;
+			case "--lon":
+			case "--lng":
+			case "--longitude":
+			case "--long":
+				parsed.lon = expectValue(args, ++index, arg);
+				break;
+			case "--altitude":
+			case "--alt":
+			case "--ele":
+			case "--elevation":
+				parsed.altitude = expectValue(args, ++index, arg);
+				break;
+			case "--altitude-type":
+			case "--alt-type":
+				parsed.altitudeType = expectValue(args, ++index, arg);
+				break;
+			case "--gps":
+				parsed.gps = expectValue(args, ++index, arg);
+				break;
 			case "--force":
 				parsed.force = true;
 				break;
@@ -263,7 +366,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown devices flag: ${arg}`);
+					throw unknownFlagError("devices", arg, devicesCommand.options);
 				}
 				positional.push(arg);
 				break;
@@ -298,6 +401,48 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 	parsed.subcommand = sub;
 
+	// Reject flags that don't apply to the resolved subcommand instead of
+	// silently ignoring the user's input: `--where`/`--near`/`--bbox` select
+	// records for `list`; the GPS *setter* flags write via `add`/`set`.
+	const selectorFlag =
+		(parsed.where?.length ?? 0) > 0
+			? "--where"
+			: parsed.near !== undefined
+				? "--near"
+				: parsed.bbox !== undefined
+					? "--bbox"
+					: undefined;
+	if (selectorFlag !== undefined && sub !== "list") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `\`${selectorFlag}\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"`--where`/`--near`/`--bbox` select records for `centrs devices list`. For `add`/`set`, name the `<target>` directly.",
+			context: { subcommand: sub, flag: selectorFlag },
+		});
+	}
+	const geoFlag =
+		parsed.lat !== undefined
+			? "--lat"
+			: parsed.lon !== undefined
+				? "--lon"
+				: parsed.altitude !== undefined
+					? "--altitude"
+					: parsed.altitudeType !== undefined
+						? "--altitude-type"
+						: parsed.gps !== undefined
+							? "--gps"
+							: undefined;
+	if (geoFlag !== undefined && sub !== "add" && sub !== "set") {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `GPS flag \`${geoFlag}\` is not supported by \`centrs devices ${sub}\`.`,
+			remediation:
+				"Store GPS with `centrs devices add`/`set` (e.g. `--gps <lat>,<lon>`); query it with `centrs devices list --where lat=…` / `--near`.",
+			context: { subcommand: sub, flag: geoFlag },
+		});
+	}
+
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
 			throw new Error(
@@ -324,6 +469,32 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	return parsed;
 }
 
+/**
+ * Parse a `--where attr=value` token for `devices list` (constitution: target
+ * selection grammar). Mirrors `src/cli/selection.ts` `parseWhereClause`: a
+ * structured `input/invalid-command` (not a bare `Error`) so the surfaced error
+ * keeps its remediation/context, consistent with every other CLI surface. Geo
+ * alias canonicalization (`latitude=`→`lat=`) is NOT done here — it happens once,
+ * centrally, in `matchesWhere` (`src/resolver/facts.ts`), so `devices list` and
+ * every fan-out command's `--where` behave identically.
+ */
+function parseWhereClause(token: string): DevicesWhereClause {
+	const eq = token.indexOf("=");
+	if (eq <= 0) {
+		throw new CentrsError({
+			code: "input/invalid-command",
+			summary: `--where must be \`<attr>=<value>\`; received: ${token}`,
+			remediation:
+				"Pass a device-class selector like `--where board=RB5009` (matches a CDB fact or core field).",
+			context: { where: token },
+		});
+	}
+	return {
+		key: token.slice(0, eq),
+		value: token.slice(eq + 1),
+	};
+}
+
 function parseKvArg(token: string): CommentKvUpdate {
 	const eq = token.indexOf("=");
 	if (eq <= 0) {
@@ -331,7 +502,51 @@ function parseKvArg(token: string): CommentKvUpdate {
 			`Invalid kv override "${token}"; expected key=value (use key= to clear a value).`,
 		);
 	}
-	return { key: token.slice(0, eq), value: parseKvValue(token.slice(eq + 1)) };
+	// Alias canonicalization happens in ONE place (`canonicalizeGeoKey`) so a
+	// bare `lng=…`/`latitude=…`/`elevation=…` positional lands under the same
+	// canonical key a `--lon`/`--lat`/`--altitude` flag would use. A no-op for
+	// every non-geo key.
+	const key = canonicalizeGeoKey(token.slice(0, eq));
+	return { key, value: parseKvValue(token.slice(eq + 1)) };
+}
+
+/**
+ * Lower the per-device GPS flags (`--lat`/`--lon`/`--altitude`/
+ * `--altitude-type` and their aliases, plus the combined `--gps`) into
+ * comment-kv updates. These are CLI conveniences only — no new first-class CDB
+ * tag — so they merge into the same `CommentKvUpdate[]` as bare `k=v`
+ * positionals; range/enum/pairing validation happens once, in
+ * `validateCommentKvUpdates` (`src/devices.ts`), regardless of which flag
+ * produced the update. `--gps` is expanded first so a discrete `--lat`/`--lon`/
+ * `--altitude`/`--altitude-type` flag passed alongside it wins (applied later
+ * in the array).
+ */
+function buildGeoUpdates(parsed: DevicesCliArgs): CommentKvUpdate[] {
+	const updates: CommentKvUpdate[] = [];
+	if (parsed.gps !== undefined) {
+		const gps = parseGpsTuple(parsed.gps);
+		updates.push({ key: "lat", value: gps.raw.lat });
+		updates.push({ key: "lon", value: gps.raw.lon });
+		if (gps.raw.altitude !== undefined) {
+			updates.push({ key: "altitude", value: gps.raw.altitude });
+		}
+		if (gps.raw.altitudeType !== undefined) {
+			updates.push({ key: "altitude-type", value: gps.raw.altitudeType });
+		}
+	}
+	if (parsed.lat !== undefined) {
+		updates.push({ key: "lat", value: parsed.lat });
+	}
+	if (parsed.lon !== undefined) {
+		updates.push({ key: "lon", value: parsed.lon });
+	}
+	if (parsed.altitude !== undefined) {
+		updates.push({ key: "altitude", value: parsed.altitude });
+	}
+	if (parsed.altitudeType !== undefined) {
+		updates.push({ key: "altitude-type", value: parsed.altitudeType });
+	}
+	return updates;
 }
 
 function parseKvValue(value: string): string {
@@ -400,7 +615,13 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		let envelope: DevicesEnvelope<unknown>;
 		switch (parsed.subcommand) {
 			case "list":
-				envelope = listDevices({ cdb, group: parsed.group });
+				envelope = listDevices({
+					cdb,
+					group: parsed.group,
+					where: (parsed.where ?? []).map(parseWhereClause),
+					near: parsed.near,
+					bbox: parsed.bbox,
+				});
 				break;
 			case "show":
 				if (!parsed.target) {
@@ -441,7 +662,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					profile: resolveProfile(parsed),
 					session: parsed.session,
 					comment: parsed.comment,
-					commentKvUpdates: (parsed.kvArgs ?? []).map(parseKvArg),
+					commentKvUpdates: [
+						...buildGeoUpdates(parsed),
+						...(parsed.kvArgs ?? []).map(parseKvArg),
+					],
 					force: parsed.force,
 					strict: parsed.strict,
 				});
@@ -459,7 +683,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 					cdb,
 					target: parsed.target,
 					match: parsed.match,
-					updates: (parsed.kvArgs ?? []).map(parseKvArg),
+					updates: [
+						...buildGeoUpdates(parsed),
+						...(parsed.kvArgs ?? []).map(parseKvArg),
+					],
 					user: parsed.user,
 					password: parsed.password,
 					group: parsed.group,
@@ -506,8 +733,10 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 			centrsError,
 		);
 		if (format === "json" || format === "yaml") {
+			// 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.
 			console.error(renderDevicesEnvelope(envelope, format));
 		} else {
+			// 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.
 			console.error(formatCentrsErrorText(centrsError));
 		}
 		return 1;

package/src/cli/discover.ts

@@ -20,6 +20,7 @@ import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
+	unknownFlagError,
 } from "./common.ts";
 
 export const discoverCommand: CliCommandMetadata = {
@@ -134,7 +135,7 @@ function parseDiscoverCliArgs(args: readonly string[]): DiscoverCliArgs {
 				break;
 			default:
 				if (arg.startsWith("-")) {
-					throw new Error(`Unknown discover flag: ${arg}`);
+					throw unknownFlagError("discover", arg, discoverCommand.options);
 				}
 				throw new Error(
 					`\`centrs discover\` does not accept positional arguments; got: ${arg}.`,
@@ -206,6 +207,7 @@ export async function runDiscoverCli(args: readonly string[]): Promise<number> {
 			remediation:
 				"Use `centrs discover --help` to inspect the supported flags.",
 		});
+		// 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.
 		console.error(formatCentrsErrorText(centrsError));
 		return 1;
 	}