@tikoci/centrs 0.1.2 → 0.1.4

package/src/devices.ts

@@ -38,10 +38,24 @@ import {
 	applyCommentKv,
 	type CommentKvUpdate,
 	commentKvAllowlist,
+	commentKvGeoKeys,
 	commentKvLookupKeys,
 	commentKvReservedKeys,
 	parseCommentKv,
+	parseRawCommentFacts,
 } from "./resolver/comment-kv.ts";
+import { entryFacts, entryLocation, matchesWhere } from "./resolver/facts.ts";
+import {
+	type BboxPredicate,
+	type DeviceLocation,
+	deviceLocation,
+	matchesBbox,
+	matchesNear,
+	type NearPredicate,
+	parseAltitude,
+	parseAltitudeType,
+	parseLatLon,
+} from "./resolver/geo.ts";
 import { normalizeMac } from "./resolver/mac.ts";
 
 export type { SettingSource, SettingSourceKind };
@@ -66,6 +80,8 @@ export interface DevicesListItem {
 	cdbRecordIndex: number;
 	source?: string;
 	sources?: Record<string, SettingSource>;
+	/** GPS location, parsed from the `lat`/`lon`/`altitude`/`altitude-type` comment facts (issue #146). */
+	location?: DeviceLocation;
 }
 
 export interface DevicesShowItem extends DevicesListItem {
@@ -126,6 +142,13 @@ export interface LoadCdbOptions {
 	cdbFile?: string;
 	cdbPassword?: string;
 	env?: Record<string, string | undefined>;
+	/**
+	 * The `centrs.env` config tier (`src/resolver/config-file.ts`). Only
+	 * `CENTRS_CDB_FILE` reads it — `CENTRS_CDB_PASSWORD` deliberately never
+	 * does, same reasoning as `CENTRS_USERNAME`/`CENTRS_PASSWORD` in
+	 * `resolver/target.ts`'s `resolveAuth`.
+	 */
+	config?: Record<string, string | undefined>;
 }
 
 export interface LoadedCdb {
@@ -154,6 +177,11 @@ export function resolveDevicesSettings(
 	const env = options.env ?? {};
 	let cdbFileSource: SettingSource = { kind: "default", key: "default" };
 	let cdbFile = defaultCdbPath(env);
+	const configCdbFile = options.config?.[ENV_CDB_FILE];
+	if (configCdbFile) {
+		cdbFile = configCdbFile;
+		cdbFileSource = { kind: "config", key: ENV_CDB_FILE };
+	}
 	const envCdbFile = env[ENV_CDB_FILE];
 	if (envCdbFile) {
 		cdbFile = envCdbFile;
@@ -197,10 +225,12 @@ function isAlreadyExistsError(cause: unknown): boolean {
  * Create an empty open CDB at `path` without clobbering an existing file.
  * Uses an exclusive-create open (`wx`) so a concurrent writer's CDB is never
  * overwritten; the caller treats EEXIST as "another process created it".
+ * Mode `0o600` keeps the CDB (device credentials) unreadable by other local
+ * users instead of falling back to the process umask default.
  */
 async function createEmptyCdbNoClobber(path: string): Promise<void> {
 	await mkdir(dirname(path), { recursive: true });
-	const handle = await open(path, "wx");
+	const handle = await open(path, "wx", 0o600);
 	try {
 		await handle.write(encodeOpenWinBoxCdb([]));
 		await handle.sync();
@@ -434,9 +464,21 @@ function credentialsMissingTips(
 	];
 }
 
+/** One `--where attr=value` device-class clause for `devices list` (exact-match, AND-combined). */
+export interface DevicesWhereClause {
+	key: string;
+	value: string;
+}
+
 export interface ListDevicesArgs {
 	cdb: LoadedCdb;
 	group?: string;
+	/** Repeatable `--where attr=value`, AND-combined (constitution: target selection grammar). */
+	where?: readonly DevicesWhereClause[];
+	/** `--near <lat>,<lon>,<radius>`: keep devices whose GPS is within radius. */
+	near?: NearPredicate;
+	/** `--bbox <south>,<west>,<north>,<east>`: keep devices whose GPS is in the box. */
+	bbox?: BboxPredicate;
 }
 
 export function listDevices(
@@ -446,18 +488,27 @@ export function listDevices(
 	let entries = args.cdb.entries;
 	let indices = entries.map((_, index) => index);
 
-	if (args.group !== undefined) {
-		const wanted = args.group;
+	// Each selector narrows the working (entries, indices) pair (AND-combined —
+	// `devices list` is a *filter* surface, distinct from the fan-out resolver's
+	// union). `--where` uses the shared `entryFacts`/`matchesWhere` from
+	// `src/resolver/facts.ts`, so the list filter and the fan-out selector match
+	// against identical device-class facts.
+	const narrow = (keep: (entry: WinBoxCdbEntry) => boolean): void => {
 		const filtered: { entry: WinBoxCdbEntry; index: number }[] = [];
-		for (let index = 0; index < entries.length; index += 1) {
-			const entry = entries[index];
-			if (entry && entry.group === wanted) {
-				filtered.push({ entry, index });
+		for (let position = 0; position < entries.length; position += 1) {
+			const entry = entries[position];
+			if (entry && keep(entry)) {
+				filtered.push({ entry, index: indices[position] ?? -1 });
 			}
 		}
 		entries = filtered.map((item) => item.entry);
 		indices = filtered.map((item) => item.index);
-		if (filtered.length === 0) {
+	};
+
+	if (args.group !== undefined) {
+		const wanted = args.group;
+		narrow((entry) => entry.group === wanted);
+		if (entries.length === 0) {
 			warnings.push({
 				code: "cdb/empty-group",
 				message: `No entries matched group "${wanted}".`,
@@ -466,6 +517,30 @@ export function listDevices(
 		}
 	}
 
+	if (args.where && args.where.length > 0) {
+		const where = args.where;
+		narrow((entry) =>
+			matchesWhere(entryFacts(entry.comment, entry.target, entry.group), where),
+		);
+	}
+
+	if (args.near !== undefined || args.bbox !== undefined) {
+		const { near, bbox } = args;
+		// Geo predicates union among themselves (near OR bbox, like the fan-out
+		// resolver), then AND-compose with group/where above. A geo-less device
+		// carries no location and is silently excluded (not an error).
+		narrow((entry) => {
+			const loc = entryLocation(entry.comment);
+			if (loc === undefined) {
+				return false;
+			}
+			return (
+				(near !== undefined && matchesNear(loc, near)) ||
+				(bbox !== undefined && matchesBbox(loc, bbox))
+			);
+		});
+	}
+
 	const data: DevicesListItem[] = entries.map((entry, position) =>
 		entryToListItem(entry, indices[position] ?? -1),
 	);
@@ -677,6 +752,10 @@ function entryToListItem(
 			key: `record:${cdbRecordIndex}:source`,
 		};
 	}
+	const location = deviceLocation(parseRawCommentFacts(entry.comment));
+	if (location !== undefined) {
+		item.location = location;
+	}
 	return item;
 }
 
@@ -805,7 +884,7 @@ function entryToShowItem(
 	entry: WinBoxCdbEntry,
 	cdbRecordIndex: number,
 ): DevicesShowItem {
-	return {
+	const item: DevicesShowItem = {
 		target: entry.target,
 		recordType: entry.recordType,
 		recordTypeName: recordTypeName(entry.recordType),
@@ -821,6 +900,11 @@ function entryToShowItem(
 		flags: entry.flags,
 		cdbRecordIndex,
 	};
+	const location = deviceLocation(parseRawCommentFacts(entry.comment));
+	if (location !== undefined) {
+		item.location = location;
+	}
+	return item;
 }
 
 export interface ListGroupsArgs {
@@ -1094,6 +1178,7 @@ async function persistRecords(
 const ALLOWLIST_SET = new Set<string>(commentKvAllowlist);
 const RESERVED_SET = new Set<string>(commentKvReservedKeys);
 const LOOKUP_SET = new Set<string>(commentKvLookupKeys);
+const GEO_SET = new Set<string>(commentKvGeoKeys);
 
 /**
  * The `usage/not-implemented` error raised by `devices edit`, whose interactive
@@ -1110,19 +1195,92 @@ export function editInteractiveOnlyError(): CentrsError {
 	});
 }
 
+/**
+ * Validate + (for the one enum field) normalize a single geo update's value.
+ * `lat`/`lon`/`altitude` are validated but returned verbatim (stored exactly
+ * as typed); `altitude-type` is validated AND canonicalized to upper case,
+ * since it is a closed two-value enum rather than a freeform/numeric field
+ * (see `src/resolver/geo.ts`). Throws `input/invalid-coordinate` /
+ * `input/invalid-altitude` on a bad value; a `value: null` removal passes
+ * through untouched (nothing to validate).
+ */
+function normalizeGeoUpdate(update: CommentKvUpdate): CommentKvUpdate {
+	if (update.value === null) {
+		return update;
+	}
+	switch (update.key) {
+		case "lat":
+			parseLatLon(update.value, "lat");
+			return update;
+		case "lon":
+			parseLatLon(update.value, "lon");
+			return update;
+		case "altitude":
+			parseAltitude(update.value);
+			return update;
+		case "altitude-type":
+			return { key: update.key, value: parseAltitudeType(update.value) };
+		default:
+			return update;
+	}
+}
+
+/**
+ * `lat`/`lon` must land together: setting one without the other, when the
+ * other is not already on the record, is `input/incomplete-gps` (also catches
+ * removing one half of an existing pair). Checked against the MERGE of
+ * `baseComment` (the record's existing comment for `set`, or the base
+ * `--comment` for `add`) and `updates`, so an already-complete record editing
+ * an unrelated key never trips this.
+ */
+function validateGeoPairing(
+	baseComment: string,
+	updates: readonly CommentKvUpdate[],
+	target: string,
+): void {
+	const priorFacts = parseRawCommentFacts(baseComment);
+	let lat = priorFacts["lat"];
+	let lon = priorFacts["lon"];
+	for (const update of updates) {
+		if (update.key === "lat") {
+			lat = update.value === null ? undefined : update.value;
+		} else if (update.key === "lon") {
+			lon = update.value === null ? undefined : update.value;
+		}
+	}
+	const hasLat = lat !== undefined;
+	const hasLon = lon !== undefined;
+	if (hasLat === hasLon) {
+		return;
+	}
+	throw new CentrsError({
+		code: "input/incomplete-gps",
+		summary: `Target "${target}" would end up with only ${hasLat ? "lat" : "lon"} set; lat and lon must be set together.`,
+		remediation:
+			"Pass both --lat and --lon (or lat=... and lon=... together), or use --gps <lat>,<lon>[,<altitude>[,<altitude-type>]] to set both at once.",
+		context: { target, hasLat, hasLon },
+	});
+}
+
 /**
  * Validate the `k=v` comment positionals shared by `add` and `set`. First-class
  * CDB fields are reserved and throw `cdb/reserved-key` (use the matching flag);
- * tokens outside the recognized override + lookup keys throw `cdb/unknown-option`
- * under `strict`, else append a `cdb/unknown-option` warning. Recognized keys
- * (allowlist overrides + `identity`/`mac`/`ip` lookups) pass silently.
+ * tokens outside the recognized override + lookup + geo keys throw
+ * `cdb/unknown-option` under `strict`, else append a `cdb/unknown-option`
+ * warning. Recognized keys (allowlist overrides, `identity`/`mac`/`ip`
+ * lookups, `lat`/`lon`/`altitude`/`altitude-type` geo facts) pass silently.
+ * Geo values are further validated (range/enum) and checked for `lat`/`lon`
+ * pairing via `src/resolver/geo.ts`; returns the updates with `altitude-type`
+ * normalized to its canonical upper-case form (the only geo field that is not
+ * stored verbatim — see `normalizeGeoUpdate`).
  */
 function validateCommentKvUpdates(
 	updates: readonly CommentKvUpdate[],
 	target: string,
 	strict: boolean | undefined,
 	warnings: DevicesWarning[],
-): void {
+	baseComment = "",
+): CommentKvUpdate[] {
 	const reserved = updates
 		.map((update) => update.key)
 		.filter((key) => RESERVED_SET.has(key));
@@ -1130,12 +1288,17 @@ function validateCommentKvUpdates(
 		throw new CentrsError({
 			code: "cdb/reserved-key",
 			summary: `Comment kv-soup cannot carry first-class CDB field(s): ${reserved.join(", ")}.`,
-			remediation: `Set ${reserved.join(", ")} with the matching --flag; the comment kv-soup is for ${commentKvAllowlist.join(", ")} plus identity/mac/ip.`,
+			remediation: `Set ${reserved.join(", ")} with the matching --flag; the comment kv-soup is for ${commentKvAllowlist.join(", ")} plus identity/mac/ip/${commentKvGeoKeys.join("/")}.`,
 			context: { target, reservedKeys: reserved },
 		});
 	}
+
+	const normalized = updates.map((update) =>
+		GEO_SET.has(update.key) ? normalizeGeoUpdate(update) : update,
+	);
+
 	for (const key of updates.map((update) => update.key)) {
-		if (ALLOWLIST_SET.has(key) || LOOKUP_SET.has(key)) {
+		if (ALLOWLIST_SET.has(key) || LOOKUP_SET.has(key) || GEO_SET.has(key)) {
 			continue;
 		}
 		if (strict) {
@@ -1152,6 +1315,17 @@ function validateCommentKvUpdates(
 			context: { target, key },
 		});
 	}
+
+	// Only enforce lat/lon pairing when THIS update actually touches a coordinate
+	// (add or remove). Otherwise an unrelated `set timeout=…` on a record that
+	// already carries a legacy/hand-edited incomplete pair would spuriously fail
+	// with `input/incomplete-gps`; leave a pre-existing pair untouched.
+	if (
+		normalized.some((update) => update.key === "lat" || update.key === "lon")
+	) {
+		validateGeoPairing(baseComment, normalized, target);
+	}
+	return normalized;
 }
 
 export interface AddDeviceArgs {
@@ -1192,8 +1366,13 @@ export async function addDevice(
 	}
 
 	const warnings: DevicesWarning[] = [...args.cdb.warnings];
-	const updates = args.commentKvUpdates ?? [];
-	validateCommentKvUpdates(updates, args.target, args.strict, warnings);
+	const updates = validateCommentKvUpdates(
+		args.commentKvUpdates ?? [],
+		args.target,
+		args.strict,
+		warnings,
+		args.comment ?? "",
+	);
 	const comment =
 		updates.length > 0 || args.comment !== undefined
 			? applyCommentKv(args.comment ?? "", updates)
@@ -1281,11 +1460,16 @@ export async function setDevice(
 	args: SetDeviceArgs,
 ): Promise<DevicesMutationEnvelope> {
 	const match = requireSingleMatch(args.cdb.entries, args.target, args.match);
-	const updates = args.updates ?? [];
+	const prior = match.entry;
 	const warnings: DevicesWarning[] = [...args.cdb.warnings];
-	validateCommentKvUpdates(updates, args.target, args.strict, warnings);
+	const updates = validateCommentKvUpdates(
+		args.updates ?? [],
+		args.target,
+		args.strict,
+		warnings,
+		prior.comment,
+	);
 
-	const prior = match.entry;
 	const comment = applyCommentKv(prior.comment, updates);
 	const carried = extraFields(prior.record);
 
@@ -1669,6 +1853,14 @@ function renderShowText(lines: string[], data: DevicesShowEnvelopeData): void {
 	lines.push(`profile:       ${entry.profile || "-"}`);
 	lines.push(`session:       ${entry.session || "-"}`);
 	lines.push(`comment:       ${entry.comment || "-"}`);
+	if (entry.location) {
+		const { lat, lon, altitude, altitudeType } = entry.location;
+		const altitudePart =
+			altitude !== undefined
+				? ` altitude=${altitude}${altitudeType ? ` (${altitudeType})` : ""}`
+				: "";
+		lines.push(`location:      lat=${lat} lon=${lon}${altitudePart}`);
+	}
 	if (entry.romonAgent) {
 		lines.push(`romon-agent:   ${entry.romonAgent}`);
 	}

package/src/discover.ts

@@ -50,6 +50,11 @@ export const DISCOVER_DEFAULT_REFRESH_INTERVAL_MS = 5_000;
 /** Default CDB group assigned to saved neighbors. */
 export const DISCOVER_DEFAULT_GROUP = "discovered";
 
+/** MNDP uses SO_REUSEPORT where available; Windows does not support it. */
+export function defaultMndpReusePort(platform = process.platform): boolean {
+	return platform !== "win32";
+}
+
 export interface ListenMndpOptions {
 	/** Listen window in ms before the listener resolves. Default 15000. */
 	timeoutMs?: number;
@@ -69,7 +74,7 @@ export interface ListenMndpOptions {
 	refreshIntervalMs?: number;
 	/** Enable `SO_REUSEADDR`. Default true. */
 	reuseAddr?: boolean;
-	/** Enable `SO_REUSEPORT` for coexistence with other MNDP listeners. Default true. */
+	/** Enable `SO_REUSEPORT` for coexistence with other MNDP listeners. Default true except on Windows. */
 	reusePort?: boolean;
 	/** Called once with the actually-bound port (useful with `port: 0`). */
 	onBound?: (port: number) => void;
@@ -180,7 +185,7 @@ export function listenMndp(
 		const socket = createSocket({
 			type: "udp4",
 			reuseAddr: options.reuseAddr ?? true,
-			reusePort: options.reusePort ?? true,
+			reusePort: options.reusePort ?? defaultMndpReusePort(),
 		});
 		let settled = false;
 		let boundPort = requestedPort;

package/src/errors.ts

@@ -13,6 +13,7 @@ export type CentrsErrorCode =
 	| `input/${string}`
 	| `internal/${string}`
 	| `mndp/${string}`
+	| `quickchr/${string}`
 	| `routeros/${string}`
 	| `settings/${string}`
 	| `target/${string}`