@tikoci/centrs 0.1.2 → 0.1.3

package/src/resolver/comment-kv.ts

@@ -17,9 +17,12 @@
  *   token (which may have been quoted).
  * - Free-form text outside well-formed `key=value` tokens is inert: no value,
  *   no warning.
- * - Allowlisted keys populate `values`. First-class CDB keys are rejected with
- *   a `cdb/reserved-option` warning (they have dedicated CDB tags and must not
- *   live in the comment). Any other key emits `cdb/unknown-option`.
+ * - Allowlisted keys populate `values`; lookup keys (`identity`/`mac`/`ip`)
+ *   populate `lookups`; geo facts (`lat`/`lon`/`altitude`/`altitude-type`,
+ *   issue #146 Slice 1) populate `geo` — all three are recognized (no warning).
+ *   First-class CDB keys are rejected with a `cdb/reserved-option` warning
+ *   (they have dedicated CDB tags and must not live in the comment). Any other
+ *   key emits `cdb/unknown-option`.
  *
  * This module is intentionally pure: it returns raw string values. Type
  * coercion (`validate` -> boolean, `timeout`/`port` -> integer) and settings
@@ -52,6 +55,23 @@ export const commentKvLookupKeys = ["identity", "mac", "ip"] as const;
 
 export type CommentKvLookupKey = (typeof commentKvLookupKeys)[number];
 
+/**
+ * Device GPS facts (issue #146 Slice 1): recognized comment-kv keys that are
+ * **facts, not settings** — queryable via `--where` and surfaced in `devices
+ * show`/`list`'s `location` block, but never coerced into resolver settings
+ * (distinct from both the override allowlist above and the lookup keys below).
+ * See `commands/devices/README.md` (Location / GPS) and `src/resolver/geo.ts`
+ * for parsing/validation.
+ */
+export const commentKvGeoKeys = [
+	"lat",
+	"lon",
+	"altitude",
+	"altitude-type",
+] as const;
+
+export type CommentKvGeoKey = (typeof commentKvGeoKeys)[number];
+
 /**
  * First-class CDB fields. These have dedicated CDB tags and must never be
  * expressed through the comment kv-soup; `devices set` refuses to write them
@@ -76,6 +96,8 @@ export interface CommentKvResult {
 	values: Partial<Record<CommentKvKey, string>>;
 	/** Lookup keys (identity/mac/ip), last-wins, raw string values. */
 	lookups: Partial<Record<CommentKvLookupKey, string>>;
+	/** Geo facts (lat/lon/altitude/altitude-type), last-wins, raw string values. */
+	geo: Partial<Record<CommentKvGeoKey, string>>;
 	warnings: CommentKvWarning[];
 }
 
@@ -95,6 +117,7 @@ const BARE_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
 const allowSet = new Set<string>(commentKvAllowlist);
 const reservedSet = new Set<string>(commentKvReservedKeys);
 const lookupSet = new Set<string>(commentKvLookupKeys);
+const geoSet = new Set<string>(commentKvGeoKeys);
 
 function isAllowlistKey(key: string): key is CommentKvKey {
 	return allowSet.has(key);
@@ -104,6 +127,10 @@ function isLookupKey(key: string): key is CommentKvLookupKey {
 	return lookupSet.has(key);
 }
 
+function isGeoKey(key: string): key is CommentKvGeoKey {
+	return geoSet.has(key);
+}
+
 /**
  * Shell-word tokenize a comment, tracking which characters originated inside a
  * quoted span so the kv splitter can require a bare, unquoted key.
@@ -208,6 +235,7 @@ function splitKv(word: ShellWord): { key: string; value: string } | undefined {
 export function parseCommentKv(comment: string): CommentKvResult {
 	const values: Partial<Record<CommentKvKey, string>> = {};
 	const lookups: Partial<Record<CommentKvLookupKey, string>> = {};
+	const geo: Partial<Record<CommentKvGeoKey, string>> = {};
 	const warnings: CommentKvWarning[] = [];
 
 	for (const word of tokenize(comment)) {
@@ -219,6 +247,10 @@ export function parseCommentKv(comment: string): CommentKvResult {
 			lookups[kv.key] = kv.value;
 			continue;
 		}
+		if (isGeoKey(kv.key)) {
+			geo[kv.key] = kv.value;
+			continue;
+		}
 		if (isAllowlistKey(kv.key)) {
 			values[kv.key] = kv.value;
 			continue;
@@ -238,7 +270,29 @@ export function parseCommentKv(comment: string): CommentKvResult {
 		});
 	}
 
-	return { values, lookups, warnings };
+	return { values, lookups, geo, warnings };
+}
+
+/**
+ * Read EVERY well-formed `key=value` token from a comment as raw facts —
+ * **no allowlist filter, no warnings, no setting coercion**. This is the
+ * device-class selector surface (`--where`): derived facts a record carries in
+ * its comment (e.g. `board=RB5009`, `version=7.23.1`) are real selectors here,
+ * even though they are NOT settings (so {@link parseCommentKv} drops them with a
+ * `cdb/unknown-option` warning). Last token wins on a duplicate bare key. Core
+ * CDB fields (`target`/`identity`/`group`/`mac`) are layered ON TOP of this map
+ * by the selector and win, so a hand-written `group=`/`target=` comment token
+ * can never spoof a first-class field.
+ */
+export function parseRawCommentFacts(comment: string): Record<string, string> {
+	const facts: Record<string, string> = {};
+	for (const word of tokenize(comment)) {
+		const kv = splitKv(word);
+		if (kv) {
+			facts[kv.key] = kv.value;
+		}
+	}
+	return facts;
 }
 
 /**

package/src/resolver/config-file.ts

@@ -0,0 +1,136 @@
+/**
+ * `centrs.env` — the user-global config-file precedence tier (constitution:
+ * "Settings precedence", `default < config < comment-kv < env < cli`).
+ *
+ * Two read paths, deliberately kept separate:
+ *
+ * - {@link loadEnvFileDefaults} is what every *other* command calls to pick
+ *   up the `config` tier. It honors `CENTRS_SKIP_ENV_FILE` (returns `{}` when
+ *   set) and is safe to call unconditionally once per invocation.
+ * - {@link readSettingsFileRaw} is what the `settings` command itself calls.
+ *   `settings` always inspects/edits the real file regardless of
+ *   `--skip-env-file` — that flag controls whether *other* commands see the
+ *   file's values, not whether `settings` can see the file.
+ *
+ * The path resolver takes an injectable `env` map (mirroring
+ * `defaultCdbPath` in `src/devices.ts`) so tests can point
+ * `XDG_CONFIG_HOME` at a per-test temp directory instead of touching a real
+ * user's `~/.config`.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseBoolean, REFUSED_CONFIG_ENV_KEYS } from "./settings.ts";
+
+const ENV_XDG_CONFIG_HOME = "XDG_CONFIG_HOME";
+const ENV_HOME = "HOME";
+const ENV_SKIP_ENV_FILE = "CENTRS_SKIP_ENV_FILE";
+const CONFIG_RELATIVE_DIR = "tikoci";
+const CONFIG_FILE_NAME = "centrs.env";
+
+/**
+ * Resolve `${XDG_CONFIG_HOME:-~/.config}/tikoci/centrs.env`. This is a
+ * deliberately different base-path convention from `defaultCdbPath`'s
+ * `$HOME`-only scheme — the constitution and the settings spec already
+ * commit to XDG for this file specifically.
+ */
+export function defaultSettingsPath(
+	env?: Record<string, string | undefined>,
+): string {
+	const xdgConfigHome = env?.[ENV_XDG_CONFIG_HOME];
+	const configHome =
+		xdgConfigHome && xdgConfigHome.length > 0
+			? xdgConfigHome
+			: join(env?.[ENV_HOME] ?? homedir(), ".config");
+	return join(configHome, CONFIG_RELATIVE_DIR, CONFIG_FILE_NAME);
+}
+
+function isSkippingEnvFile(env: Record<string, string | undefined>): boolean {
+	const raw = env[ENV_SKIP_ENV_FILE];
+	if (raw === undefined) {
+		return false;
+	}
+	try {
+		return parseBoolean(raw, ENV_SKIP_ENV_FILE);
+	} catch {
+		return false;
+	}
+}
+
+export interface SettingsFileContents {
+	readonly exists: boolean;
+	/** Every non-blank, non-comment line verbatim, in file order. */
+	readonly lines: readonly string[];
+}
+
+/**
+ * Raw line-level read, no `CENTRS_SKIP_ENV_FILE` short-circuit. Used by
+ * `settings` itself, which must always see the real file.
+ */
+export async function readSettingsFileRaw(
+	path: string,
+): Promise<SettingsFileContents> {
+	const file = Bun.file(path);
+	if (!(await file.exists())) {
+		return { exists: false, lines: [] };
+	}
+	const text = await file.text();
+	return { exists: true, lines: text.split("\n") };
+}
+
+/**
+ * Parse `CENTRS_*=value` lines into a flat map. Blank lines and `#`
+ * comments are ignored; a later duplicate key wins. Malformed lines
+ * (no `=`, or a key that isn't a bare identifier) are silently skipped —
+ * a hand-edited file with foreign content should not fail every other
+ * command's settings resolution.
+ */
+export function parseEnvFileDefaults(
+	lines: readonly string[],
+): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const rawLine of lines) {
+		const line = rawLine.trim();
+		if (line.length === 0 || line.startsWith("#")) {
+			continue;
+		}
+		const separatorIndex = line.indexOf("=");
+		if (separatorIndex <= 0) {
+			continue;
+		}
+		const key = line.slice(0, separatorIndex).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+			continue;
+		}
+		result[key] = line.slice(separatorIndex + 1).trim();
+	}
+	return result;
+}
+
+/**
+ * The `config` tier every command resolver call should pass through. Empty
+ * (`{}`) when the file is absent or `CENTRS_SKIP_ENV_FILE` is active — never
+ * throws, since a missing or foreign-content file is not an error for
+ * anything but `settings` itself.
+ *
+ * Credential/self-referential keys ({@link REFUSED_CONFIG_ENV_KEYS}) are
+ * stripped even if a hand-edited file contains them: most resolvers already
+ * never consult `config` for these, but dropping them here means the shared
+ * `config` map itself never carries a secret, rather than relying on every
+ * call site to keep excluding it. `parseEnvFileDefaults` is left unfiltered
+ * so `settings print --all` can still inspect/redact a hand-added line.
+ */
+export async function loadEnvFileDefaults(
+	env: Record<string, string | undefined> = Bun.env,
+): Promise<Record<string, string>> {
+	if (isSkippingEnvFile(env)) {
+		return {};
+	}
+	const path = defaultSettingsPath(env);
+	const { lines } = await readSettingsFileRaw(path);
+	const parsed = parseEnvFileDefaults(lines);
+	for (const key of REFUSED_CONFIG_ENV_KEYS) {
+		delete parsed[key];
+	}
+	return parsed;
+}

package/src/resolver/facts.ts

@@ -0,0 +1,78 @@
+/**
+ * Device-class fact extraction + selector matching, shared by the fan-out
+ * resolver ({@link ../resolver/selection.ts | expandCdbSelection}) and
+ * `devices list` (`src/devices.ts`) so **both surfaces match `--where` /
+ * `--near` / `--bbox` against identical semantics**.
+ *
+ * This is a deliberate leaf module — it imports only from `comment-kv.ts`,
+ * `mac.ts`, and `geo.ts` (all leaves). It exists because `src/devices.ts` and
+ * `src/resolver/cdb.ts` form a cycle (`cdb.ts` imports `devices.ts`), so
+ * `devices.ts` cannot import `cdb.ts`'s `identityFromComment`/`macFromComment`
+ * nor `selection.ts`'s local `entryFacts` without a circular import. That forced
+ * the `--where` fact-builder to be duplicated in both files; hosting it here
+ * removes the duplication and the "keep the two in sync" hazard.
+ */
+
+import { parseCommentKv, parseRawCommentFacts } from "./comment-kv.ts";
+import {
+	canonicalizeGeoKey,
+	type DeviceLocation,
+	deviceLocation,
+} from "./geo.ts";
+import { normalizeMac } from "./mac.ts";
+
+/** One exact-match device-class clause (`attr=value`), AND-combined by callers. */
+export interface WhereClause {
+	key: string;
+	value: string;
+}
+
+/**
+ * Turn a CDB entry's `(comment, target, group)` into the device-class fact map
+ * `--where` matches against: every raw comment-kv token, with the core fields
+ * (`target`/`identity`/`group`/`mac`) layered **on top** so a hand-written
+ * comment token can never spoof a first-class field. MAC is normalized so a
+ * `mac=` lookup or a MAC `target` compares separator/case-insensitively.
+ */
+export function entryFacts(
+	comment: string,
+	target: string,
+	group: string,
+): Record<string, string> {
+	const facts = parseRawCommentFacts(comment);
+	const lookups = parseCommentKv(comment).lookups;
+	facts["target"] = target;
+	facts["identity"] = lookups.identity ?? target;
+	facts["group"] = group;
+	const mac = normalizeMac(lookups.mac ?? "") ?? normalizeMac(target);
+	if (mac !== undefined) {
+		facts["mac"] = mac;
+	}
+	return facts;
+}
+
+/**
+ * True when every `--where` clause matches the entry's facts (exact,
+ * AND-combined). The clause key is run through {@link canonicalizeGeoKey} here —
+ * the single seam — so a geo alias (`--where latitude=…`/`lng=…`/`elevation=…`)
+ * matches the canonical `lat`/`lon`/`altitude` fact the write side stores, on
+ * BOTH `devices list` and every fan-out command's `--where`. A no-op for
+ * non-geo keys.
+ */
+export function matchesWhere(
+	facts: Record<string, string>,
+	where: readonly WhereClause[],
+): boolean {
+	return where.every(
+		(clause) => facts[canonicalizeGeoKey(clause.key)] === clause.value,
+	);
+}
+
+/**
+ * Read a CDB entry's GPS location from its comment, or `undefined` when it
+ * carries no well-formed `lat`/`lon`. The single seam `--near`/`--bbox` use to
+ * exclude geo-less devices (never an error — they simply don't match).
+ */
+export function entryLocation(comment: string): DeviceLocation | undefined {
+	return deviceLocation(parseRawCommentFacts(comment));
+}