@tikoci/centrs 0.1.2 → 0.1.4

package/src/protocols/adapter.ts

@@ -610,23 +610,39 @@ class NativeApiAdapter implements ProtocolAdapter {
 	async execute(
 		request: ProtocolExecuteRequest,
 	): Promise<ProtocolExecuteResult> {
-		const command: NativeApiCommand = request.script
-			? { command: "/execute", attributes: { script: request.script } }
-			: { command: `${request.path.replace(/\/$/, "")}/${request.command}` };
-		if (
-			!request.script &&
-			request.attributes &&
-			Object.keys(request.attributes).length > 0
-		) {
+		if (request.script !== undefined) {
+			return normalizeNativeExecute(await this.executeScript(request.script));
+		}
+		const command: NativeApiCommand = {
+			command: `${request.path.replace(/\/$/, "")}/${request.command}`,
+		};
+		if (request.attributes && Object.keys(request.attributes).length > 0) {
 			command.attributes = request.attributes;
 		}
-		if (!request.script && request.queries && request.queries.length > 0) {
+		if (request.queries && request.queries.length > 0) {
 			command.queries = request.queries;
 		}
 		const replies = await this.talk(command);
 		return { records: repliesToRecords(replies) };
 	}
 
+	/**
+	 * Run a script through native `/execute` with `as-string`, the sole shared
+	 * path for both the CLI-shaped `execute` command and the `api` run+script
+	 * verb: without `as-string` the native API schedules a background job and
+	 * returns only its id rather than the captured output (CHR-grounded —
+	 * mirrors REST `/rest/execute`).
+	 */
+	private async executeScript(
+		script: string,
+	): Promise<Record<string, string>[]> {
+		const replies = await this.talk({
+			command: "/execute",
+			attributes: { script, "as-string": "" },
+		});
+		return repliesToRecords(replies);
+	}
+
 	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
 		const base = request.path.replace(/\/$/, "");
 		switch (request.verb) {
@@ -682,15 +698,7 @@ class NativeApiAdapter implements ProtocolAdapter {
 			}
 			case "run": {
 				if (request.script !== undefined) {
-					// `as-string` makes `/execute` run synchronously and return the captured
-					// output; without it the native API schedules a job and returns its id
-					// (CHR-grounded — mirrors REST `/rest/execute`).
-					const records = repliesToRecords(
-						await this.talk({
-							command: "/execute",
-							attributes: { script: request.script, "as-string": "" },
-						}),
-					);
+					const records = await this.executeScript(request.script);
 					return { data: restStyleRunData(records) };
 				}
 				const command: NativeApiCommand = { command: base };
@@ -1089,6 +1097,18 @@ function exhaustiveApiVerb(verb: never): never {
 	throw new Error(`Unhandled api verb: ${String(verb)}`);
 }
 
+/** Re-map an `as-string` native `/execute` reply into `ProtocolExecuteResult`,
+ * mirroring `normalizeRestExecute`'s `ret`-vs-records split. */
+function normalizeNativeExecute(
+	records: readonly Record<string, string>[],
+): ProtocolExecuteResult {
+	const ret = records.length === 1 ? records[0]?.["ret"] : undefined;
+	if (typeof ret === "string") {
+		return { records: [], ret };
+	}
+	return { records: [...records] };
+}
+
 function normalizeRestExecute(data: unknown): ProtocolExecuteResult {
 	if (Array.isArray(data)) {
 		return { records: data.filter(isPlainObject) as Record<string, string>[] };

package/src/protocols/index.ts

@@ -7,6 +7,11 @@
  * Status per protocol is the implementation reality (`implemented` flag).
  * Per-cell status across commands is in `docs/MATRIX.md`. Selection rules
  * are in `docs/CONSTITUTION.md` (protocol selection).
+ *
+ * Contract with MATRIX (asserted by `test/unit/protocol-registry.test.ts`):
+ * every `CHR-passed` cell in the `docs/MATRIX.md` grid implies its protocol
+ * here is `implemented: true` and lists the matching capability. MATRIX stays
+ * the only status surface; this registry must never under-claim against it.
  */
 
 export type ProtocolCapability =
@@ -35,7 +40,7 @@ export const protocolPlans = [
 	},
 	{
 		id: "native-api",
-		capabilities: ["retrieve", "execute", "proxy"],
+		capabilities: ["retrieve", "execute", "transfer", "proxy"],
 		notes:
 			"Binary API (TCP 8728 / TLS 8729). Transport base implemented in native-api.ts (word/sentence codec, login, tagged talk); command wiring tracked in docs/MATRIX.md.",
 		implemented: true,
@@ -44,8 +49,8 @@ export const protocolPlans = [
 		id: "ssh",
 		capabilities: ["execute", "terminal", "transfer"],
 		notes:
-			"Reuses host ssh client. Important execute/terminal path after grounding.",
-		implemented: false,
+			"Reuses host ssh client. execute/terminal/transfer all CHR-passed (docs/MATRIX.md); facts in ssh.ts, sftp.ts, terminal.ts.",
+		implemented: true,
 	},
 	{
 		id: "snmp",
@@ -56,8 +61,9 @@ export const protocolPlans = [
 	{
 		id: "mndp",
 		capabilities: ["discover"],
-		notes: "Passive hint source only; not authoritative inventory.",
-		implemented: false,
+		notes:
+			"Passive hint source only; not authoritative inventory. discover CHR-passed (docs/MATRIX.md); facts in src/data/mndp.ts.",
+		implemented: true,
 	},
 	{
 		id: "mac-telnet",

package/src/protocols/mac-telnet-console.ts

@@ -39,10 +39,11 @@
  *     scraped for: `(evl …)` = ok, `syntax error (line …)` = malformed, and
  *     `bad parameter <name> (line …)` = unknown attribute. A single console
  *     `:parse` therefore covers both the syntax and the unknown-attribute
- *     (semantic) gate — no `/console/inspect` table parsing needed.
+ *     (name-level) gate — no `/console/inspect` table parsing needed.
  */
 
 import { parseRouterOsPosition } from "../core/routeros-errors.ts";
+import { routerOsStringLiteral } from "../core/routeros-string.ts";
 import { CentrsError } from "../errors.ts";
 import {
 	type MacAddress,
@@ -323,8 +324,11 @@ export class MacTelnetConsole {
 	 * Validate a command without running it, using a single console `:parse`.
 	 * Throws `validation/syntax` for malformed CLI and
 	 * `validation/unknown-attribute` for a rejected parameter; returns the parsed
-	 * form on success. One gate covers both because the console's `:parse`
-	 * reports `bad parameter <name>` as well as `syntax error`.
+	 * form on success. One gate covers both because the console prints the
+	 * `:parse` return value, which carries `bad parameter <name>` as well as the
+	 * `(<%%` / `(line N column M)` syntax diagnostics — see
+	 * {@link classifyParseResult} for the full grammar and why the matcher is
+	 * anchored to the diagnostic shape rather than to bare words.
 	 */
 	async parseGate(cli: string): Promise<string> {
 		const { output } = await this.run(parseScriptFor(cli));
@@ -604,17 +608,61 @@ export function parseScriptFor(cli: string): string {
 	return `:put [:parse ${routerOsStringLiteral(cli)}]`;
 }
 
+/*
+ * The `:parse` diagnostic grammar, anchored to where RouterOS actually emits
+ * each shape. Anchoring is load-bearing, not cosmetic: an *accepted* return
+ * echoes the script body, so `:put "bad parameter x"` comes back as
+ * `(evl /putmessage=bad parameter x)`. An unanchored search reads that echoed
+ * content as a verdict and refuses to run a valid command (GH#230).
+ *
+ * Two shapes, both corpus-verified against lsp-routeros-ts
+ * `parseil_results.il_text` (2736 rows, RouterOS 7.20.8/7.22.1/7.23rc1):
+ *
+ *   1. WRAPPED — the diagnostic sits inside the returned value, marked by the
+ *      `(evl ` / `(<%%` wrapper. It can appear mid-return, because a
+ *      multi-statement script reports the offending statement in place. Every
+ *      corpus `bad parameter` (8/8) follows `(evl `, and every `bad command
+ *      name` (135/135) follows `(<%%`.
+ *   2. BARE — the diagnostic *is* the whole return, printed on its own line
+ *      with RouterOS's position suffix. All 425 corpus rows of this shape are
+ *      the entire return; none appear embedded. Requiring both line-start and
+ *      the `(line N column M)` suffix is what separates a real verdict from
+ *      echoed body text.
+ */
+const WRAPPED_BAD_PARAMETER = /\(evl\s+bad parameter\s+(\S+)/i;
+const WRAPPED_BAD_COMMAND = /\(<%%\s*bad command name\b/i;
+const BARE_BAD_PARAMETER =
+	/^[ \t]*bad parameter\s+(\S+)[^\n]*\(line \d+ column \d+\)/im;
+const BARE_SYNTAX =
+	/^[ \t]*(?:syntax error|bad command name|expected [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
+
 /**
- * Classify the output of a console `:put [:parse "<cli>"]`. A single console
- * `:parse` reports both forms (grounded on CHR 7.23.1): `bad parameter <name>`
- * for an unknown attribute and `syntax error` / `bad command name` for malformed
- * CLI. Throws the matching `validation/*` error; returns on a clean parse.
+ * Classify the printed value of `:put [:parse "<cli>"]`. Grounded on CHR 7.23.3
+ * (see GH#230): `:parse` *never* throws — it returns a value whose text carries
+ * the verdict. For a bare menu path the accepted form is `(evl /canonical/path)`
+ * (abbreviations expanded); for script-shaped input the accepted return echoes
+ * the statement body and may contain arbitrary text — including text that looks
+ * like a diagnostic. Rejections are therefore matched only in the positions
+ * RouterOS emits them (see the grammar note above): wrapped as
+ * `(evl bad parameter <name> (line N column M) /path)` /
+ * `(<%% bad command name <name> (line N column M) a;b;c)`, or bare and
+ * line-initial as `expected … (line N column M)` / `syntax error (line N column
+ * M)`. A single `:parse` covers both the syntax and the unknown-attribute
+ * (name-level) gate on every transport — REST and native API expose the same text
+ * in the `ret` value (HTTP 200 / `as-string`), the console transports print it.
+ *
+ * Throws the matching `validation/*` error; returns on a clean parse.
  */
-export function classifyParseResult(output: string, cli: string): void {
-	// The console `:parse` rejection carries RouterOS's authoritative byte offset
+export function classifyParseResult(
+	output: string,
+	cli: string,
+	via: string = "mac-telnet",
+): void {
+	// The `:parse` rejection carries RouterOS's authoritative byte offset
 	// (`… (line N column M)`); surface it as the structured `error.position`.
 	const position = parseRouterOsPosition(output);
-	const unknown = output.match(/bad parameter\s+(\S+)/i);
+	const unknown =
+		output.match(WRAPPED_BAD_PARAMETER) ?? output.match(BARE_BAD_PARAMETER);
 	if (unknown) {
 		throw new CentrsError({
 			code: "validation/unknown-attribute",
@@ -624,13 +672,13 @@ export function classifyParseResult(output: string, cli: string): void {
 			context: {
 				command: cli,
 				parameter: cleanToken(unknown[1] ?? ""),
-				validationSource: ":put [:parse ...] over mac-telnet",
+				validationSource: `:put [:parse ...] over ${via}`,
 				detail: output,
 			},
 			...(position ? { position } : {}),
 		});
 	}
-	if (/syntax error|bad command name|expected\b/i.test(output)) {
+	if (WRAPPED_BAD_COMMAND.test(output) || BARE_SYNTAX.test(output)) {
 		throw new CentrsError({
 			code: "validation/syntax",
 			summary: "RouterOS rejected the command syntax while parsing it.",
@@ -638,7 +686,7 @@ export function classifyParseResult(output: string, cli: string): void {
 				"Fix the RouterOS CLI syntax (quotes, brackets, attribute form), then retry.",
 			context: {
 				command: cli,
-				validationSource: ":put [:parse ...] over mac-telnet",
+				validationSource: `:put [:parse ...] over ${via}`,
 				detail: output,
 			},
 			...(position ? { position } : {}),
@@ -646,10 +694,6 @@ export function classifyParseResult(output: string, cli: string): void {
 	}
 }
 
-function routerOsStringLiteral(value: string): string {
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
 function cleanToken(token: string): string {
 	return token.replace(/^["'`]+|["'`.,;:)]+$/g, "");
 }

package/src/resolver/cdb.ts

@@ -153,6 +153,7 @@ function warningFromDevices(warning: DevicesWarning): ResolverWarning {
 export async function resolveCdb(
 	input: CdbResolveInput,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): Promise<CdbResolution | undefined> {
 	if (!input.targetInput) {
 		return undefined;
@@ -162,12 +163,18 @@ export async function resolveCdb(
 		cdbFile: input.cdbFile,
 		cdbPassword: input.cdbPassword,
 		env,
+		config,
 	});
+	// A user-configured `centrs.env` default CDB path counts as explicit, same
+	// as an env var: it is an intentional choice, not the built-in fallback,
+	// so a missing file there should surface as a real error rather than
+	// silently degrading to "no CDB in play".
 	const explicitCdb =
 		input.cdbFile !== undefined ||
 		input.cdbPassword !== undefined ||
 		env[ENV_CDB_FILE] !== undefined ||
-		env[ENV_CDB_PASSWORD] !== undefined;
+		env[ENV_CDB_PASSWORD] !== undefined ||
+		config[ENV_CDB_FILE] !== undefined;
 	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
 		return undefined;
 	}
@@ -178,6 +185,7 @@ export async function resolveCdb(
 			cdbFile: input.cdbFile,
 			cdbPassword: input.cdbPassword,
 			env,
+			config,
 		});
 	} catch (error) {
 		if (
@@ -312,7 +320,7 @@ export async function expandCdbGroup(
 	return { targets, warnings, empty: false };
 }
 
-function resolutionFromEntry(
+export function resolutionFromEntry(
 	entry: WinBoxCdbEntry,
 	recordIndex: number,
 ): CdbResolution {

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 | expandSelection}) 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));
+}