@tikoci/centrs 0.1.4 → 0.1.7

package/src/core/inspect.ts

@@ -5,10 +5,16 @@
  * (path tokenizing, the comma-path join, node-type predicates, completion-name
  * extraction). This module is the single home so a third consumer — `api`, and a
  * future `explain`/`check` — reuses one grounded implementation instead of
- * forking a fourth. It deliberately holds only the transport-agnostic
- * *primitives*; each command composes its own discovery strategy on top (their
- * strategies differ: `retrieve` probes print/get support, `execute` unions
- * child-args with completions), so the strategy stays in the command.
+ * forking a fourth. It holds the transport-agnostic *primitives* plus the one
+ * discovery strategy that is shared verbatim: {@link inspectArgumentNames},
+ * command-level `request=child` only, used by `execute` and `api`. Strategies
+ * that differ stay in the command — `retrieve` probes print/get support and
+ * reads argument-level completion (`print,proplist` / `get,value-name`) with a
+ * child fallback.
+ *
+ * Command-level `request=completion` is not part of any argument-discovery
+ * strategy: on RouterOS 7.12.2 it hangs the REST handler and closes the
+ * native-API connection. See {@link inspectArgumentNames}.
  *
  * Grounding: the request modes mirror `tikoci/lsp-routeros-ts`
  * (`server/src/routeros.ts` `InspectRequest`). The behavioral facts (the array-
@@ -49,12 +55,20 @@ export interface InspectChildItem {
 }
 
 /** A row from `request=completion`: a candidate token for a path/argument. */
+/**
+ * One `request=completion` row. These are the only fields RouterOS sends, on
+ * every build recorded from 7.9.2 to 7.25beta3 (lsp-routeros-ts
+ * `test-data/inspect-shapes.v*.json`). `text` is the candidate's help string,
+ * never its name.
+ */
 export interface InspectCompletionItem {
 	type?: string;
-	name?: string;
 	completion?: string;
-	value?: string;
+	show?: string;
+	style?: string;
 	text?: string;
+	offset?: string;
+	preference?: string;
 }
 
 /**
@@ -93,31 +107,23 @@ export function isCommandNode(child: InspectChildItem, name: string): boolean {
 }
 
 /**
- * Flatten completion rows into attribute names. Reads every name-like field a
- * RouterOS build might populate (`completion`/`name`/`value`/`text`), strips
- * everything from the first `=` onward (the `name=value` completion form), and
- * drops blanks. Returns the names in row order **without** de-duplication or
- * sorting — callers that need a stable set wrap with `[...new Set(names)].sort()`
- * (both current callers do).
+ * The candidate names from completion rows: `completion` of each
+ * `show: "true"` row that is not `syntax-meta`. `show: "false"` rows are
+ * syntax completions (`[`, `(`, `$`, `"`, `*`, `<value>`), not properties
+ * (CHR 7.23.7, on both `print,proplist` and `get,value-name`; #380). At an
+ * argument boundary RouterOS also offers a shown `=` ("argument value
+ * separator", `style: "syntax-meta"`) on every recorded build, 7.9.2 →
+ * 7.25beta3; no build offers a `name=value` completion. Returns
+ * the names in row order **without** de-duplication or sorting; callers that
+ * need a stable set wrap with `[...new Set(names)].sort()`.
  */
 export function extractCompletionNames(
 	rows: readonly InspectCompletionItem[],
 ): string[] {
 	return rows
-		.flatMap((row) => [row.completion, row.name, row.value, row.text])
-		.filter((value): value is string => typeof value === "string")
-		.map((value) => nameBeforeEquals(value).trim())
-		.filter((value) => value.length > 0);
-}
-
-/**
- * The token before the first `=` in a RouterOS completion row. Plain string
- * slicing (no regex) — `value.replace(/=.*$/, "")` triggers a CodeQL
- * polynomial-ReDoS flag on this exported function's caller-supplied input.
- */
-function nameBeforeEquals(value: string): string {
-	const eq = value.indexOf("=");
-	return eq === -1 ? value : value.slice(0, eq);
+		.filter((row) => row.show === "true" && row.style !== "syntax-meta")
+		.map((row) => row.completion?.trim() ?? "")
+		.filter((name) => name.length > 0);
 }
 
 /** `request=child` for a token path. */
@@ -131,6 +137,32 @@ export async function inspectChildren(
 	)) as InspectChildItem[];
 }
 
+/**
+ * Return the argument names exposed by `request=child` at a command path.
+ *
+ * Do not supplement this with a command-level `request=completion`: RouterOS
+ * 7.12.2 hangs the REST handler and closes the native-API connection for that
+ * request shape, while `child` returns the complete argument list immediately.
+ * Argument-level completion (for example `print,proplist`) is a distinct probe
+ * and remains available through {@link inspectCompletions}.
+ */
+export async function inspectArgumentNames(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<string[]> {
+	const children = await inspectChildren(backend, tokens);
+	return [
+		...new Set(
+			children
+				.filter(isArgumentNode)
+				.map((child) => child.name)
+				.filter(
+					(name): name is string => typeof name === "string" && name.length > 0,
+				),
+		),
+	].sort();
+}
+
 /** `request=completion` for a token path. */
 export async function inspectCompletions(
 	backend: InspectBackend,

package/src/core/routeros-errors.ts

@@ -88,6 +88,12 @@ export interface RouterOsErrorRule {
 	description: string;
 	/** Pattern matched against the trimmed RouterOS string. */
 	test: RegExp;
+	/**
+	 * Anchored form safe for classifying a successful transport's returned text.
+	 * Unlike an HTTP error body / native trap, `/execute as-string` also carries
+	 * ordinary stdout, so substring matches would turn user output into failures.
+	 */
+	resultTest?: RegExp;
 	/** Builds the normalized error fields from the regex match and raw string. */
 	build: (match: RegExpMatchArray, raw: string) => RouterOsErrorRuleResult;
 }
@@ -106,6 +112,8 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"RouterOS did not recognize the command path or menu item ('no such ...').",
 		test: /no such command prefix|no such item|no such entry/i,
+		resultTest:
+			/^(?:failure:\s*)?(?:no such command prefix|no such item|no such entry)\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -119,6 +127,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		// (mac-telnet) says "bad parameter <name> (line N column M)" for the same
 		// fault. Grounded on CHR 7.23.1.
 		test: /(?:unknown|bad) parameter\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?(?:unknown|bad) parameter\s+\S+.*$/i,
 		build: (match) => {
 			const parameter = cleanToken(match[1] ?? "");
 			return {
@@ -135,6 +144,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			"RouterOS console rejected the command word ('bad command name …').",
 		// Console form (mac-telnet) of an unrecognized command/path word.
 		test: /bad command name/i,
+		resultTest: /^(?:failure:\s*)?(?:\(<%%\s*)?bad command name\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the command: ${raw.trim()}`,
 			remediation:
@@ -145,6 +155,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/invalid-value",
 		description: "RouterOS rejected the value supplied for an argument.",
 		test: /invalid value (?:for argument|of)\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?invalid value (?:for argument|of)\s+\S+.*$/i,
 		build: (match) => {
 			const argument = cleanToken(match[1] ?? "");
 			return {
@@ -155,11 +166,24 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/invalid-value",
+		description:
+			"RouterOS rejected a value because it does not match the accepted domain.",
+		test: /input does not match/i,
+		resultTest: /^(?:failure:\s*)?input does not match\b.*$/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS rejected the supplied value: ${raw.trim()}`,
+			remediation:
+				"Check the accepted values for this command on the target RouterOS version, then retry with a matching value.",
+		}),
+	},
 	{
 		code: "routeros/session-closed",
 		description:
 			"RouterOS closed the REST session before the request completed (60-second cap).",
 		test: /session closed/i,
+		resultTest: /^(?:failure:\s*)?session closed\b.*$/i,
 		build: () => ({
 			summary: "RouterOS closed the session before the request completed.",
 			remediation:
@@ -171,6 +195,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"Generic RouterOS command failure carrying a `failure: <msg>` string.",
 		test: /^\s*failure:\s*(.+?)\s*$/i,
+		resultTest: /^\s*failure:\s*.+?\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -181,11 +206,27 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/command-failed",
+		description: "Generic RouterOS command failure carrying an error prefix.",
+		test: /^\s*error:\s*(.+?)\s*$/i,
+		resultTest: /^\s*error:\s*.+?\s*$/i,
+		build: (match) => {
+			const failure = (match[1] ?? "").trim();
+			return {
+				summary: `RouterOS command failed: ${failure}`,
+				remediation:
+					"Inspect the RouterOS error message, then adjust the script or request shape accordingly.",
+				context: { failure },
+			};
+		},
+	},
 	{
 		code: "routeros/command-failed",
 		description:
 			"RouterOS /execute as-string returned a script :error value with source location.",
 		test: /^\s*(.+?)\s*\(:error; line \d+\)\s*$/i,
+		resultTest: /^\s*.+?\s*\(:error; line \d+\)\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -203,6 +244,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/unknown-path",
 		description: "RouterOS reported a path-shaped 'not found'.",
 		test: /not found/i,
+		resultTest: /^\s*\/\S+\s+not found\s*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -211,6 +253,30 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 	},
 ];
 
+/**
+ * Grounded result shapes that intentionally use the transport-specific
+ * catch-all mapping. They are errors, but do not carry enough information for a
+ * more specific normalized code.
+ */
+const ROUTEROS_RESULT_CATCH_ALL =
+	/^(?:syntax error|expected (?:end of command|command name|input value))\b[^\n]*$/i;
+
+/**
+ * Map text returned by a successful transport only when it matches a grounded,
+ * stdout-safe result shape. Returns `undefined` for ordinary script output.
+ */
+export function mapRouterOsResultError(
+	raw: string,
+	opts: MapRouterOsErrorOptions = {},
+): CentrsError | undefined {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return undefined;
+	const matched =
+		ROUTEROS_RESULT_CATCH_ALL.test(trimmed) ||
+		routerOsErrorRules.some((rule) => rule.resultTest?.test(trimmed));
+	return matched ? mapRouterOsError(raw, opts) : undefined;
+}
+
 /**
  * Maps a raw RouterOS error string to a normalized {@link CentrsError}.
  *

package/src/core/version.ts

@@ -0,0 +1,4 @@
+import packageMetadata from "../../package.json" with { type: "json" };
+
+/** Package version reported by every frontend and the root library surface. */
+export const centrsVersion = packageMetadata.version;

package/src/core/yaml.ts

@@ -0,0 +1,86 @@
+/**
+ * Envelope YAML rendering — the `--format yaml` writer shared by every command.
+ *
+ * This is a **renderer, not a YAML library**: it serializes the envelope shapes
+ * centrs builds (scalars, arrays, plain objects) and quotes every string through
+ * `JSON.stringify`, which is valid YAML double-quoted scalar syntax. It does not
+ * parse YAML, emit anchors/aliases, or handle cycles.
+ *
+ * It lives in `src/core/` because it is **pure** — no Bun, filesystem, network,
+ * or CDB reach. `retrieve.ts` used to own it, which put every consumer of
+ * `toYaml` one import away from the transport stack; `explain`'s offline entry
+ * runs in a browser only because this function no longer drags that graph
+ * behind it (#312). Every importer now takes `toYaml` from here; `retrieve.ts`
+ * is one of them, and the function itself moved character for character.
+ */
+
+/**
+ * Render `value` as YAML at `indent` spaces of nesting.
+ *
+ * `undefined` object entries are dropped (they have no YAML spelling and the
+ * envelope uses them for absent-optional); `undefined` in scalar position and
+ * `null` both render `null`. A non-plain object that is neither array nor
+ * scalar falls back to its JSON text as a quoted scalar rather than guessing.
+ */
+export function toYaml(value: unknown, indent = 0): string {
+	const prefix = " ".repeat(indent);
+	if (value === null || value === undefined) {
+		return "null";
+	}
+	if (typeof value === "string") {
+		return yamlScalar(value);
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		return String(value);
+	}
+	if (Array.isArray(value)) {
+		if (value.length === 0) {
+			return `${prefix}[]`;
+		}
+		return value
+			.map((item) => {
+				if (isScalar(item)) {
+					return `${prefix}- ${toYaml(item, indent + 2)}`;
+				}
+				return `${prefix}-\n${toYaml(item, indent + 2)}`;
+			})
+			.join("\n");
+	}
+	if (isPlainObject(value)) {
+		const entries = Object.entries(value).filter(
+			([, entryValue]) => entryValue !== undefined,
+		);
+		if (entries.length === 0) {
+			return `${prefix}{}`;
+		}
+		return entries
+			.map(([key, entryValue]) => {
+				if (isScalar(entryValue)) {
+					return `${prefix}${key}: ${toYaml(entryValue, indent + 2)}`;
+				}
+				return `${prefix}${key}:\n${toYaml(entryValue, indent + 2)}`;
+			})
+			.join("\n");
+	}
+	return yamlScalar(JSON.stringify(value));
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isScalar(value: unknown): value is boolean | number | string | null {
+	return (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	);
+}
+
+function yamlScalar(value: string): string {
+	if (value.length === 0) {
+		return '""';
+	}
+	return JSON.stringify(value);
+}

package/src/data/winbox-cdb-write.ts

@@ -20,6 +20,7 @@
  */
 
 import {
+	chmod,
 	copyFile,
 	mkdir,
 	open,
@@ -137,10 +138,21 @@ export async function writeWinBoxCdb(
 	let backupPath: string | undefined;
 	const prunedBackups: string[] = [];
 	const targetExists = await pathExists(target);
+	// The backup and the replacement both carry the CDB's mode (a new CDB gets
+	// 0600): the file holds device credentials, and neither a plain open nor
+	// `copyFile` is guaranteed to keep it narrower than the umask default,
+	// e.g. 0644 (#382 review).
+	const mode = targetExists ? (await stat(target)).mode & 0o777 : 0o600;
 	if (targetExists && !options.skipBackup) {
 		const stamp = backupStamp(options.now ?? new Date());
 		backupPath = join(dir, `${backupPrefix(target)}${stamp}`);
 		await copyFile(target, backupPath);
+		try {
+			await chmod(backupPath, mode);
+		} catch (error) {
+			await unlink(backupPath).catch(() => undefined);
+			throw error;
+		}
 
 		if (retention >= 0) {
 			const backups = await listWinBoxCdbBackups(target);
@@ -159,15 +171,17 @@ export async function writeWinBoxCdb(
 		dir,
 		`${basename(target)}${TEMP_INFIX}${process.pid}.${Date.now().toString(36)}`,
 	);
-	const handle = await open(tempPath, "w");
-	try {
-		await handle.write(bytes);
-		await handle.sync();
-	} finally {
-		await handle.close();
-	}
-
+	// Any failure before the rename removes the temp file: it holds the
+	// serialized CDB, credentials included.
 	try {
+		const handle = await open(tempPath, "w", mode);
+		try {
+			await handle.chmod(mode);
+			await handle.write(bytes);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
 		await rename(tempPath, target);
 	} catch (error) {
 		await unlink(tempPath).catch(() => undefined);

package/src/devices.ts

@@ -1,4 +1,5 @@
-import { mkdir, open } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import type {
@@ -79,6 +80,10 @@ export interface DevicesListItem {
 	user: string;
 	cdbRecordIndex: number;
 	source?: string;
+	/** `identity=` / `mac=` / `ip=` comment lookup keys — the names `<router>` resolves by (issue #378). */
+	identity?: string;
+	mac?: string;
+	ip?: string;
 	sources?: Record<string, SettingSource>;
 	/** GPS location, parsed from the `lat`/`lon`/`altitude`/`altitude-type` comment facts (issue #146). */
 	location?: DeviceLocation;
@@ -102,6 +107,7 @@ export interface DevicesGroupSummary {
 }
 
 export type DevicesCommand =
+	| "init"
 	| "list"
 	| "show"
 	| "groups"
@@ -223,22 +229,106 @@ 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.
+ * The bytes are written to a private temp file first and then hard-linked
+ * into place: `link` fails with EEXIST instead of replacing, and `path` never
+ * exists half-written, so a concurrent creator that loses the race reads a
+ * complete CDB (#382 review). Returns false when `link` found a CDB already
+ * there (another process created it). Only `link`'s EEXIST means that: a
+ * recursive `mkdir` also reports EEXIST when a path component is a regular
+ * file. 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> {
+async function createEmptyCdbNoClobber(path: string): Promise<boolean> {
 	await mkdir(dirname(path), { recursive: true });
-	const handle = await open(path, "wx", 0o600);
+	const tempPath = `${path}.init.${randomUUID()}`;
+	const handle = await open(tempPath, "wx", 0o600);
 	try {
-		await handle.write(encodeOpenWinBoxCdb([]));
-		await handle.sync();
+		try {
+			await handle.chmod(0o600);
+			await handle.write(encodeOpenWinBoxCdb([]));
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
+		await link(tempPath, path);
+		return true;
+	} catch (error) {
+		if (isAlreadyExistsError(error)) {
+			return false;
+		}
+		throw error;
 	} finally {
-		await handle.close();
+		await unlink(tempPath);
 	}
 }
 
+export interface DevicesInitData {
+	cdbFile: string;
+	/** False when a readable CDB was already there; nothing was written. */
+	created: boolean;
+	recordCount: number;
+}
+
+/**
+ * `devices init` (#376): create an empty open CDB at the resolved path, the
+ * explicit counterpart of the default path's first-run auto-create. Never
+ * clobbers: like `git init`, re-running on an existing, readable CDB succeeds
+ * with a `cdb/file-exists` warning and writes nothing, so a workspace bootstrap
+ * script can run it unconditionally. An existing file that does not load
+ * (not a CDB, or encrypted without a password) fails with the load error.
+ */
+export async function initCdb(
+	options: LoadCdbOptions,
+): Promise<CentrsSuccessEnvelope<DevicesInitData, DevicesOperationMeta>> {
+	const settings = resolveDevicesSettings(options);
+	const cdbFile = settings.cdbFile.value;
+	const existingResult = async () => {
+		const existing = await loadCdb(options);
+		return {
+			ok: true as const,
+			data: { cdbFile, created: false, recordCount: existing.entries.length },
+			warnings: [
+				...existing.warnings,
+				{
+					code: "cdb/file-exists",
+					message: `A CDB already exists at ${cdbFile} (${existing.entries.length} record(s)); nothing was written.`,
+				},
+			],
+			tips: [],
+			meta: devicesMeta("init", settings),
+		};
+	};
+	// Check first: an existing CDB in a read-only directory is still an
+	// idempotent success, although no temp file could be created beside it.
+	// A `false` from the create covers a creator that wins the race after this.
+	if (await Bun.file(cdbFile).exists()) {
+		return existingResult();
+	}
+	let created: boolean;
+	try {
+		created = await createEmptyCdbNoClobber(cdbFile);
+	} catch (cause) {
+		throw new CentrsError({
+			code: "cdb/create-failed",
+			summary: `Could not create a CDB at ${cdbFile}.`,
+			remediation:
+				"Check that the directory is writable, or pass --cdb-file PATH to a writable location.",
+			context: { cdbFile },
+			cause,
+		});
+	}
+	if (!created) {
+		return existingResult();
+	}
+	return {
+		ok: true,
+		data: { cdbFile, created: true, recordCount: 0 },
+		warnings: [],
+		tips: [],
+		meta: devicesMeta("init", settings),
+	};
+}
+
 export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 	const settings = resolveDevicesSettings(options);
 	const warnings: DevicesWarning[] = [];
@@ -250,33 +340,33 @@ export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 		// `devices`/identity commands work out of the box. An explicit missing
 		// path stays an error (typo protection).
 		if (settings.cdbFile.source.kind === "default") {
+			// `false` means another process won the race and created the CDB
+			// after our existence check; that file is authoritative, so fall
+			// through and read it instead of erroring.
+			let created: boolean;
 			try {
-				await createEmptyCdbNoClobber(settings.cdbFile.value);
+				created = await createEmptyCdbNoClobber(settings.cdbFile.value);
+			} catch (cause) {
+				throw new CentrsError({
+					code: "cdb/not-found",
+					summary: `CDB file not found and could not be created: ${settings.cdbFile.value}`,
+					remediation:
+						"Check directory permissions for ~/.config/tikoci, or pass --cdb-file PATH to a writable location.",
+					context: { cdbFile: settings.cdbFile.value },
+					cause,
+				});
+			}
+			if (created) {
 				warnings.push({
 					code: "cdb/created",
 					message: `No CDB found at the default path; created an empty CDB at ${settings.cdbFile.value}.`,
 				});
-			} catch (cause) {
-				// EEXIST means another process won the race and created the CDB
-				// between our existence check and the exclusive open — that file
-				// is authoritative; fall through and read it instead of erroring.
-				if (!isAlreadyExistsError(cause)) {
-					throw new CentrsError({
-						code: "cdb/not-found",
-						summary: `CDB file not found and could not be created: ${settings.cdbFile.value}`,
-						remediation:
-							"Check directory permissions for ~/.config/tikoci, or pass --cdb-file PATH to a writable location.",
-						context: { cdbFile: settings.cdbFile.value },
-						cause,
-					});
-				}
 			}
 		} else {
 			throw new CentrsError({
 				code: "cdb/not-found",
 				summary: `CDB file not found: ${settings.cdbFile.value}`,
-				remediation:
-					"Pass --cdb-file PATH, set CENTRS_CDB_FILE, or place a CDB at ~/.config/tikoci/winbox.cdb.",
+				remediation: `To start a new CDB there, run \`centrs devices init --cdb-file ${settings.cdbFile.value}\`. Otherwise check the path; an explicit --cdb-file or CENTRS_CDB_FILE is never created implicitly.`,
 				context: { cdbFile: settings.cdbFile.value },
 			});
 		}
@@ -752,6 +842,18 @@ function entryToListItem(
 			key: `record:${cdbRecordIndex}:source`,
 		};
 	}
+	for (const key of commentKvLookupKeys) {
+		const value = parsed.lookups[key];
+		// Same non-blank rule as `entryRouterKeys`: never advertise a key that
+		// does not resolve.
+		if (value !== undefined && value.trim().length > 0) {
+			item[key] = value;
+			sources[key] = {
+				kind: "comment-kv",
+				key: `record:${cdbRecordIndex}:${key}`,
+			};
+		}
+	}
 	const location = deviceLocation(parseRawCommentFacts(entry.comment));
 	if (location !== undefined) {
 		item.location = location;
@@ -1753,6 +1855,15 @@ function renderText(envelope: DevicesEnvelope<unknown>): string {
 	}
 
 	switch (envelope.meta.operation?.command) {
+		case "init": {
+			const data = envelope.data as DevicesInitData;
+			lines.push(
+				data.created
+					? `created ${data.cdbFile}`
+					: `exists ${data.cdbFile} (${data.recordCount} record(s))`,
+			);
+			break;
+		}
 		case "list":
 			renderListText(lines, envelope.data as readonly DevicesListItem[]);
 			break;
@@ -1828,12 +1939,15 @@ function renderListText(
 		lines.push("(no entries)");
 		return;
 	}
-	lines.push(["INDEX", "TARGET", "TYPE", "USER", "GROUP"].join("\t"));
+	lines.push(
+		["INDEX", "TARGET", "IDENTITY", "TYPE", "USER", "GROUP"].join("\t"),
+	);
 	for (const item of items) {
 		lines.push(
 			[
 				String(item.cdbRecordIndex),
 				item.target,
+				item.identity || "-",
 				item.recordTypeName,
 				item.user || "-",
 				item.group || "-",