@tikoci/centrs 0.1.6 → 0.1.8-next.0

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 {
@@ -32,7 +33,11 @@ import {
 	writeWinBoxCdb,
 } from "./data/winbox-cdb-write.ts";
 import { parseDeviceRecord } from "./devices-schema.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
 	applyCommentKv,
@@ -79,6 +84,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 +111,7 @@ export interface DevicesGroupSummary {
 }
 
 export type DevicesCommand =
+	| "init"
 	| "list"
 	| "show"
 	| "groups"
@@ -223,20 +233,104 @@ 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> {
@@ -250,33 +344,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 +846,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;
@@ -1739,20 +1845,22 @@ function renderYamlInline(value: unknown, indent: string): string {
 function renderText(envelope: DevicesEnvelope<unknown>): string {
 	const lines: string[] = [];
 	if (!envelope.ok) {
-		const error = envelope.error;
-		lines.push(`[${error.code}] ${error.summary}`);
-		if (error.remediation) {
-			lines.push(`Fix: ${error.remediation}`);
-		}
-		if (error.detailsUrl) {
-			lines.push(`Details: ${error.detailsUrl}`);
-		}
+		lines.push(formatCentrsErrorText(envelope.error));
 		appendWarnings(lines, envelope.warnings);
 		appendTips(lines, envelope.tips);
 		return lines.join("\n");
 	}
 
 	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 +1936,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 || "-",

package/src/discover.ts

@@ -37,7 +37,12 @@ import {
 	loadCdb,
 	resolveDevicesSettings,
 } from "./devices.ts";
-import { asCentrsError, CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	asCentrsError,
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import { parseCommentKv, renderCommentKvToken } from "./resolver/comment-kv.ts";
 import { normalizeMac } from "./resolver/mac.ts";
 
@@ -771,13 +776,7 @@ export function renderDiscoverEnvelope(
 function renderDiscoverText(envelope: DiscoverEnvelope): string {
 	const lines: string[] = [];
 	if (!envelope.ok) {
-		lines.push(`[${envelope.error.code}] ${envelope.error.summary}`);
-		if (envelope.error.remediation) {
-			lines.push(`Fix: ${envelope.error.remediation}`);
-		}
-		if (envelope.error.detailsUrl) {
-			lines.push(`Details: ${envelope.error.detailsUrl}`);
-		}
+		lines.push(formatCentrsErrorText(envelope.error));
 		appendDiscoverWarnings(lines, envelope.warnings);
 		return lines.join("\n");
 	}

package/src/errors.ts

@@ -5,7 +5,16 @@
  */
 export const ERROR_DETAILS_BASE_URL = "https://tikoci.github.io/centrs/errors/";
 
+/**
+ * Remediation for a device-stage `:parse` rejection. It does not claim the
+ * syntax is wrong: RouterOS rejects an absent menu (unknown path, package not
+ * installed) in the same words, and #361 tracks telling those apart.
+ */
+export const SYNTAX_REJECTED_REMEDIATION =
+	"RouterOS refused to parse this command; its own words are in `Device said`. Check the syntax with `centrs explain '<command>'`. A menu that does not exist on this device (an unknown path, or a package that is not installed) is rejected the same way.";
+
 export type CentrsErrorCode =
+	| `wait/${string}`
 	| `auth/${string}`
 	| `cdb/${string}`
 	| `discover/${string}`
@@ -120,34 +129,134 @@ export function asCentrsError(
 	});
 }
 
+/**
+ * The one text renderer for an error, shared by every command (GH#362).
+ *
+ * Order: header, where (`At:`), the device's own words (`Device said:`), `Fix:`,
+ * `Details:`. Where and the device's words print without `--verbose`: they are
+ * what lets a caller recover from a remediation that names the wrong cause.
+ * `--verbose` adds the full `context` object. A command that has more to say
+ * (warnings, tips) appends to this output; it never re-derives the header.
+ */
 export function formatCentrsErrorText(
 	error: CentrsError | SerializedCentrsError,
 	options: { verbose?: boolean } = {},
 ): string {
 	const serialized = serializeCentrsError(error);
-	const lines = [`[${serialized.code}] ${serialized.summary}`];
+	const lines = errorFields(serialized);
+	if (options.verbose && serialized.context) {
+		lines.push("");
+		lines.push(terminalSafe(JSON.stringify(serialized.context, null, 2)));
+	}
+	return lines.join("\n");
+}
+
+/**
+ * The same fields as `formatCentrsErrorText`, on one line joined by ` — `, for
+ * output that must stay line-per-record (`api --stream --format text`).
+ * `--verbose` adds nothing here: a context block cannot be one line.
+ */
+export function formatCentrsErrorLine(
+	error: CentrsError | SerializedCentrsError,
+): string {
+	return errorFields(serializeCentrsError(error)).map(oneLine).join(" — ");
+}
+
+function errorFields(serialized: SerializedCentrsError): string[] {
+	const lines = [`[${serialized.code}] ${terminalSafe(serialized.summary)}`];
 
 	if (serialized.position) {
 		// RouterOS's authoritative byte column (1-based); see RouterOsErrorPosition.
 		lines.push(
 			`At: line ${serialized.position.line}, column ${serialized.position.column} (RouterOS byte offset)`,
 		);
+	} else {
+		const offline = offlineSpanText(serialized.context);
+		if (offline) lines.push(offline);
+	}
+
+	const deviceSaid = deviceSaidText(serialized);
+	if (deviceSaid) {
+		lines.push(`Device said: ${terminalSafe(deviceSaid)}`);
 	}
 
 	if (serialized.remediation) {
-		lines.push(`Fix: ${serialized.remediation}`);
+		lines.push(`Fix: ${terminalSafe(serialized.remediation)}`);
 	}
 
 	if (serialized.detailsUrl) {
 		lines.push(`Details: ${serialized.detailsUrl}`);
 	}
 
-	if (options.verbose && serialized.context) {
-		lines.push("");
-		lines.push(JSON.stringify(serialized.context, null, 2));
-	}
+	return lines;
+}
 
-	return lines.join("\n");
+const DEVICE_SAID_MAX = 240;
+
+/**
+ * Control characters other than tab and newline, C1 included. Summaries and
+ * `detail` carry router-supplied text; an ESC or CR in it would drive the
+ * terminal. `JSON.stringify` escapes C0 but not C1, so serialized excerpts need
+ * this too. `--json` keeps the raw value.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+const TERMINAL_CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+
+function terminalSafe(text: string): string {
+	return text.replace(TERMINAL_CONTROL, " ");
+}
+
+/** Compact records also replace tab/newline so external text cannot add rows. */
+export function terminalSafeLine(text: string): string {
+	return terminalSafe(text).replace(/[\t\n]/g, " ");
+}
+
+function oneLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * RouterOS's own verdict, from `context.detail`: the raw `:parse` return or the
+ * trap / REST message, as `mapRouterOsError` and `classifyParseResult` store it.
+ * Collapsed to one line and capped. Omitted when the summary already quotes it,
+ * so a trap message is not printed twice. `--json` keeps it unabridged.
+ */
+function deviceSaidText(error: SerializedCentrsError): string | undefined {
+	const detail = error.context?.["detail"];
+	if (typeof detail !== "string") return undefined;
+	const said = oneLine(detail);
+	if (said.length === 0 || oneLine(error.summary).includes(said))
+		return undefined;
+	return said.length > DEVICE_SAID_MAX
+		? `${said.slice(0, DEVICE_SAID_MAX)}…`
+		: said;
+}
+
+/**
+ * The offline gate's rejected byte range (`context.span`, 0-based, end-exclusive,
+ * into `context.command`). Labelled as offline analysis so it is never mistaken
+ * for a RouterOS-reported position (see `src/offline-gate.ts`).
+ */
+function offlineSpanText(
+	context: Record<string, unknown> | undefined,
+): string | undefined {
+	const span = context?.["span"];
+	if (
+		!span ||
+		typeof span !== "object" ||
+		typeof (span as { start?: unknown }).start !== "number" ||
+		typeof (span as { end?: unknown }).end !== "number"
+	) {
+		return undefined;
+	}
+	const { start, end } = span as { start: number; end: number };
+	const command = context?.["command"];
+	const excerpt =
+		typeof command === "string" && end > start
+			? `: ${terminalSafe(JSON.stringify(new TextDecoder().decode(new TextEncoder().encode(command).subarray(start, end))))}`
+			: "";
+	// Half-open, exactly as `context.span` carries it.
+	return `At: bytes [${start}, ${end}) (offline analysis)${excerpt}`;
 }
 
 export function serializeUnknownError(error: unknown): unknown {

package/src/execute-fanout.ts

@@ -15,7 +15,7 @@
  *   - A `--default` / `__default__` member is guarded from being dialed as the
  *     literal hostname `"__default__"` — it fails that one target deterministically
  *     with `target/unresolved`.
- *   - A **write-shaped** command (add/set/remove) is confirmed ONCE up front
+ *   - A **write-shaped** command is confirmed ONCE up front
  *     (`--yes`), never per target; without `--yes` the error names the blast radius
  *     (how many routers). Write-ness is target-independent (`canonicalizeExecuteCommand`).
  */
@@ -38,7 +38,12 @@ import {
 	summarizeFanout,
 } from "./core/fanout.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+	terminalSafeLine,
+} from "./errors.ts";
 import {
 	buildExecuteErrorEnvelopeFromResolved,
 	type ExecuteEnvelope,
@@ -428,11 +433,7 @@ export function renderExecuteFanoutEnvelope(
 		return toYaml(envelope);
 	}
 	if (!envelope.ok) {
-		const lines = [`[${envelope.error.code}] ${envelope.error.summary}`];
-		if (envelope.error.remediation) {
-			lines.push(`Fix: ${envelope.error.remediation}`);
-		}
-		return lines.join("\n");
+		return formatCentrsErrorText(envelope.error, options);
 	}
 	const operation = envelope.meta.operation;
 	const { total, ok, failed } = envelope.data.summary;
@@ -453,10 +454,14 @@ export function renderExecuteFanoutEnvelope(
 			);
 		} else {
 			lines.push(
-				`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				terminalSafeLine(
+					`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				),
 			);
 			if (options.verbose && target.error.remediation) {
-				lines.push(`        Fix: ${target.error.remediation}`);
+				lines.push(
+					terminalSafeLine(`        Fix: ${target.error.remediation}`),
+				);
 			}
 		}
 	}