@tikoci/centrs 0.1.7 → 0.1.8

package/docs/errors/validation/menu-unavailable.md

@@ -0,0 +1,22 @@
+# `validation/menu-unavailable`
+
+RouterOS 7 publishes this menu or command, but this device does not have it —
+usually hardware, build or version.
+
+Same detection as
+[`validation/package-missing`](package-missing.md): RouterOS rejected a path
+segment, and centrs's path catalog knows the path. This code is used when the
+published gates are not a package alone — a hardware capability
+(`/interface/w60g` needs `60ghz`), a build condition, or no gate at all, which
+usually means the device's RouterOS version predates or dropped the menu.
+The path can end in a command rather than a menu: `/system/license/output` is
+published `nochr`, so a CHR rejects it here, and the summary calls it a command.
+
+`error.context` carries `path`, `segment`, `gates` (root-first, each with the
+`package`, `syscap` and `conditions` MikroTik published) and `detail`.
+
+## Fix
+
+The command is not the problem. Compare the gates with the device: installed
+packages (`/system/package/print`), model, and RouterOS version
+(`/system/resource/print`). Run the command only on devices that have the menu.

package/docs/errors/validation/not-followable.md

@@ -0,0 +1,23 @@
+# `validation/not-followable`
+
+The RouterOS menu cannot be followed: it is a single record, or its print has
+no follow-only.
+
+## When it happens
+
+`centrs retrieve <router> <menu> --follow` checks the menu live through
+`/console/inspect` before following it. RouterOS can follow a menu only when
+its `print` takes `follow-only`, which is the same thing native-API `listen`
+needs. Single-record menus such as `/system/resource`, `/system/identity` and
+`/ip/dns` never take it, and neither do some list menus.
+
+Nothing was followed. The error's `context.singleton` says which case it was.
+
+## Fix
+
+- Read the menu once: `centrs retrieve <router> <menu>`.
+- To see a value change over time, sample it:
+  `centrs retrieve <router> <menu> --sample 5s` (one line per complete read,
+  until `--count`, `--duration` or Ctrl-C).
+- If you expected the menu to be followable, check the path with
+  `centrs retrieve <router> <menu> --list-attributes`.

package/docs/errors/validation/package-missing.md

@@ -0,0 +1,29 @@
+# `validation/package-missing`
+
+This device has no such menu or command; MikroTik publishes it in a package
+that is likely not installed.
+
+RouterOS's `:parse` reports a menu it does not have as `syntax error` (slash
+spelling, `/zerotier/print`) or `bad command name` (space spelling,
+`/zerotier print`). Both point at the segment it could not resolve. centrs
+looks that path up in its path catalog — every RouterOS 7.10–7.25 build, all
+extra packages — and when MikroTik publishes it behind a package and nothing
+else, reports this code instead of `validation/syntax`.
+
+`error.context` carries:
+
+- `path` — the absent menu or command, from the root (`/zerotier`). The summary
+  says which, from the path catalog's kind. An abbreviated segment
+  is expanded when the catalog has one unique completion.
+- `segment` — the segment as written.
+- `packages` — the published package names. These are MikroTik's build names
+  and can differ from the installable package (`wireless-rep` ships in
+  `wireless`, `userman-5` in `user-manager`).
+- `gates` — every published gate on the path, root-first.
+- `detail` — RouterOS's own words; `error.position` is its byte column.
+
+## Fix
+
+The command is not the problem. Check the installed packages with
+`/system/package/print`, install the package and reboot, or run the command only
+on devices that have it.

package/docs/errors/validation/unknown-path.md

@@ -1,9 +1,21 @@
 # `validation/unknown-path`
 
-The RouterOS path does not expose the requested command.
+The RouterOS path does not exist, or does not expose the requested command.
+
+Two sources raise it:
+
+- **`execute` / `validate`** — RouterOS's `:parse` rejected a path segment, and
+  the path is in no published RouterOS 7 build centrs knows of (its path
+  catalog covers 7.10–7.25, all extra packages). Usually a typo.
+  `error.context.path` is the path through the rejected segment,
+  `error.context.segment` the segment as written, and `error.position`
+  RouterOS's byte column. A path the catalog does know is reported as
+  [`validation/package-missing`](package-missing.md) or
+  [`validation/menu-unavailable`](menu-unavailable.md) instead.
+- **`retrieve` / `api`** — `/console/inspect` shows the path has no command of
+  the kind requested (no `print` or `get` to read with).
 
 ## Fix
 
-See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `validation/unknown-path`.
+Check the spelling of the segment in `error.context.segment`. `centrs explain
+'<command>'` shows how the rest of the command reads offline.

package/docs/errors/wait/deadline-exceeded.md

@@ -0,0 +1,14 @@
+# `wait/deadline-exceeded`
+
+The wait deadline passed before readiness or its condition was established.
+
+## Fix
+
+Check the predicate and the router's current state, then choose a longer
+`--wait` if the operation legitimately needs more time. `--timeout` bounds
+individual requests and does not extend the overall deadline.
+
+`meta.operation.wait` reports `deadline-elapsed`, elapsed milliseconds,
+attempts and completed observations. A failed or unfinished read never proves
+an empty result. If the last attempt failed with a transient transport error,
+that error is preserved instead of this code.

package/docs/errors/wait/interrupted.md

@@ -0,0 +1,10 @@
+# `wait/interrupted`
+
+The wait was cancelled before readiness or its condition was established.
+
+## Fix
+
+Run the wait again when you want to continue. Ctrl-C or an aborted library
+signal is a failure to establish the condition, even if some reads completed.
+The final envelope reports `meta.operation.wait.stopReason: "interrupted"`
+and the partial attempts and observations.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -12,18 +12,18 @@
 	"packageManager": "bun@1.3.14",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.5.7",
-		"@secretlint/secretlint-rule-preset-recommend": "^13.0.2",
-		"@types/bun": "^1.3.13",
+		"@biomejs/biome": "2.5.15",
+		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
+		"@types/bun": "1.3.14",
 		"cloc": "^2.6.0-cloc",
-		"cspell": "^10.0.0",
+		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
-		"markdownlint-cli2": "^0.23.0",
-		"secretlint": "^13.0.2",
-		"typedoc": "^0.28.19"
+		"markdownlint-cli2": "^0.23.3",
+		"secretlint": "^13.0.7",
+		"typedoc": "^0.28.20"
 	},
 	"optionalDependencies": {
-		"@tikoci/quickchr": "^0.4.7"
+		"@tikoci/quickchr": "^0.4.8"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
@@ -133,10 +133,13 @@
 		"explain:token-census:readme:check": "bun run scripts/explain-token-census.ts --readme --check",
 		"security": "bun run lint:secretlint && bun run lint:markdownlint"
 	},
+	"overrides": {
+		"smol-toml": "^1.9.1"
+	},
 	"type": "module",
 	"types": "src/index.ts",
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"zod": "^4.4.3"
+		"@modelcontextprotocol/sdk": "^1.32.1",
+		"zod": "^4.6.7"
 	}
 }

package/src/absent-menu.ts

@@ -0,0 +1,280 @@
+/**
+ * Tell a menu this device does not have apart from a real syntax error (GH#361).
+ *
+ * RouterOS's `:parse` reports an absent menu as if it were a syntax fault, in two
+ * spellings that both name the segment it could not resolve (CHR 7.23.7):
+ *
+ *   /zerotier/print       -> syntax error (line 1 column 10)
+ *   /zerotier print       -> (<%% bad command name zerotier (line 1 column 2) …)
+ *
+ * The slash spelling points at the `/` right AFTER the absent segment; the space
+ * spelling names the segment and points at its first byte. The column is a 1-based
+ * BYTE column on the given line (`:put "é"; /zerotier/print` -> column 21, not 20).
+ * Nesting moves the column but not the rule: `:put [/interface/w60g/get …]`,
+ * `/ip/address { /zerotier/print }` and a second line all point at the `/` after
+ * the absent segment.
+ *
+ * Once the segment is located, the path catalog says what it is. Both shipped
+ * tables are built from all-extra-packages builds, so a path they carry exists in
+ * SOME RouterOS 7 build, and its published gates explain why this one lacks it:
+ *
+ * The path can end in a command (`/system/license/output`, gated `nochr`), not
+ * only a menu; the summary uses the catalog's kind.
+ *
+ * - a package gate alone           -> `validation/package-missing`
+ * - any other gate, or none        -> `validation/menu-unavailable`
+ * - not in either table            -> `validation/unknown-path`
+ *
+ * Anything this cannot locate exactly returns `undefined`, and the caller keeps
+ * its `validation/syntax`. Abstaining is always safe; guessing a path is not.
+ */
+
+import { CentrsError, type RouterOsErrorPosition } from "./errors.ts";
+import {
+	type CatalogGate,
+	effectiveGates,
+	PATH_CATALOG,
+} from "./explain/catalog.ts";
+import { MENU_PATHS } from "./explain/menus.ts";
+import { explainCommand } from "./explain.ts";
+
+const NAME = /[a-z0-9-]/i;
+const BAD_COMMAND_NAME = /bad command name\s+(\S+)\s+\(line \d+ column \d+\)/i;
+const BARE_SYNTAX_ERROR = /^[ \t]*syntax error \(line \d+ column \d+\)/im;
+/** What may precede the leading `/` of an absolute path run. */
+const RUN_BOUNDARY = /[\s[{;(]/;
+
+/** The located absent segment, as a path from the root. */
+interface AbsentPath {
+	/** Lower-cased segments from the root through the absent one. */
+	segments: string[];
+	/** The segment RouterOS could not resolve, as written. */
+	segment: string;
+}
+
+export function absentMenuError(
+	cli: string,
+	output: string,
+	position: RouterOsErrorPosition | undefined,
+	via: string,
+): CentrsError | undefined {
+	if (position === undefined) return undefined;
+	const offset = offsetOf(cli, position);
+	if (offset === undefined) return undefined;
+	const absent = locateAbsentPath(cli, output, offset);
+	if (absent === undefined) return undefined;
+
+	const segments = expandAbbreviations(absent.segments);
+	const path = `/${segments.join("/")}`;
+	const context = {
+		command: cli,
+		path,
+		segment: absent.segment,
+		validationSource: `:put [:parse ...] over ${via}`,
+		detail: output,
+	};
+
+	if (!isPublished(path)) {
+		return new CentrsError({
+			code: "validation/unknown-path",
+			summary: `RouterOS has no \`${path}\` menu or command, and centrs's path catalog has none.`,
+			remediation: `Check the spelling of \`${absent.segment}\`: the catalog covers every RouterOS 7.10–7.25 build with all extra packages. \`centrs explain '<command>'\` shows how the rest of the command reads.`,
+			context,
+			position,
+		});
+	}
+
+	const noun = PATH_CATALOG.get(path)?.kind === "command" ? "command" : "menu";
+	const gates = gatesOf(segments);
+	const packages = unique(gates.flatMap((gate) => gate.package ?? []));
+	const others = gates.filter(
+		(gate) => gate.conditions !== undefined || gate.syscap !== undefined,
+	);
+	if (packages.length > 0 && others.length === 0) {
+		const named = packages.map((name) => `\`${name}\``).join(", ");
+		return new CentrsError({
+			code: "validation/package-missing",
+			summary: `This device has no \`${path}\` ${noun}; MikroTik publishes it in package ${named}, which is likely not installed.`,
+			remediation: `The command is not the problem. Check the installed packages with \`/system/package/print\`; install ${named} (MikroTik's published name; the installable package can be named differently) and reboot, or run this only on devices that have it.`,
+			context: { ...context, packages, gates },
+			position,
+		});
+	}
+	return new CentrsError({
+		code: "validation/menu-unavailable",
+		summary: `This device has no \`${path}\` ${noun}, although RouterOS 7 publishes one.`,
+		remediation: `The command is not the problem. ${gateAdvice(gates)}`,
+		context: { ...context, gates },
+		position,
+	});
+}
+
+/** The UTF-16 index of RouterOS's 1-based line / byte column, or `undefined`. */
+function offsetOf(
+	cli: string,
+	{ line, column }: RouterOsErrorPosition,
+): number | undefined {
+	const lines = cli.split("\n");
+	const text = lines[line - 1];
+	if (text === undefined || column < 1) return undefined;
+	const bytes = new TextEncoder().encode(text);
+	if (column - 1 > bytes.length) return undefined;
+	const prefix = new TextDecoder("utf-8", { fatal: true }).decode(
+		bytes.slice(0, column - 1),
+	);
+	let start = 0;
+	for (let index = 0; index < line - 1; index++)
+		start += (lines[index] as string).length + 1;
+	return start + prefix.length;
+}
+
+function locateAbsentPath(
+	cli: string,
+	output: string,
+	offset: number,
+): AbsentPath | undefined {
+	const named = output.match(BAD_COMMAND_NAME);
+	if (named) {
+		const segment = named[1] as string;
+		if (cli.slice(offset, offset + segment.length) !== segment)
+			return undefined;
+		return cli[offset - 1] === "/"
+			? slashRun(cli, offset, offset + segment.length)
+			: spaceSpelling(cli, offset, segment);
+	}
+	if (!BARE_SYNTAX_ERROR.test(output) || cli[offset] !== "/") return undefined;
+	let start = offset;
+	while (start > 0 && NAME.test(cli[start - 1] as string)) start--;
+	if (start === offset || cli[start - 1] !== "/") return undefined;
+	return slashRun(cli, start, offset);
+}
+
+/**
+ * `/a/b/<segment>` — walk back over `name/` pairs to the run's leading `/`, which
+ * must sit at a statement boundary. A relative run (`../x`, `ip/x`) abstains.
+ */
+function slashRun(
+	cli: string,
+	start: number,
+	end: number,
+): AbsentPath | undefined {
+	let runStart = start - 1;
+	while (runStart > 0 && cli[runStart] === "/") {
+		let nameStart = runStart;
+		while (nameStart > 0 && NAME.test(cli[nameStart - 1] as string))
+			nameStart--;
+		if (nameStart === runStart) break;
+		if (cli[nameStart - 1] !== "/") return undefined;
+		runStart = nameStart - 1;
+	}
+	if (runStart > 0 && !RUN_BOUNDARY.test(cli[runStart - 1] as string))
+		return undefined;
+	const segments = cli
+		.slice(runStart + 1, end)
+		.toLowerCase()
+		.split("/");
+	return { segments, segment: cli.slice(start, end) };
+}
+
+/**
+ * `/ip nosuchmenu print` — the parent comes from the offline analyzer's reading
+ * of the statement that holds the segment. Menu-scope blocks and anything else
+ * the analyzer did not resolve abstain, and so does a segment that appears more
+ * than once (`/ip ip print`): which occurrence RouterOS rejected is not mapped.
+ */
+function spaceSpelling(
+	cli: string,
+	offset: number,
+	segment: string,
+): AbsentPath | undefined {
+	const { structure } = explainCommand(cli);
+	const holders = [...structure.statements, ...structure.subcommands]
+		.filter(
+			(entry) =>
+				entry.resolution === "resolved" &&
+				entry.command !== undefined &&
+				entry.span.start <= offset &&
+				offset < entry.span.end,
+		)
+		.sort((a, b) => a.span.end - a.span.start - (b.span.end - b.span.start));
+	const command = holders[0]?.command;
+	if (command === undefined) return undefined;
+	const words = [
+		...command.path.split("/").filter(Boolean),
+		...("verb" in command ? [command.verb] : []),
+	].map((word) => word.toLowerCase());
+	const index = words.indexOf(segment.toLowerCase());
+	if (index < 0 || words.lastIndexOf(segment.toLowerCase()) !== index)
+		return undefined;
+	return { segments: words.slice(0, index + 1), segment };
+}
+
+/** RouterOS accepts a unique prefix; resolve one against the catalog's children. */
+function expandAbbreviations(segments: readonly string[]): string[] {
+	const out: string[] = [];
+	for (const segment of segments) {
+		const parent = out.length === 0 ? "" : `/${out.join("/")}`;
+		if (isPublished(`${parent}/${segment}`)) {
+			out.push(segment);
+			continue;
+		}
+		const children = new Set<string>();
+		for (const path of publishedPaths())
+			if (path.startsWith(`${parent}/${segment}`)) {
+				const child = path.slice(parent.length + 1).split("/")[0] as string;
+				children.add(child);
+			}
+		out.push(children.size === 1 ? ([...children][0] as string) : segment);
+	}
+	return out;
+}
+
+function* publishedPaths(): Iterable<string> {
+	yield* PATH_CATALOG.keys();
+	yield* MENU_PATHS;
+}
+
+/** A path, or anything under it, is in one of the two shipped tables. */
+function isPublished(path: string): boolean {
+	if (PATH_CATALOG.has(path) || MENU_PATHS.has(path)) return true;
+	for (const known of publishedPaths())
+		if (known.startsWith(`${path}/`)) return true;
+	return false;
+}
+
+/**
+ * The path's own gates, root-first. A container row the publication left ungated
+ * (`/iot`) borrows the package every catalog row under it agrees on — all 62
+ * `/iot/*` rows say `iot` — and borrows nothing when they disagree.
+ */
+function gatesOf(segments: readonly string[]): CatalogGate[] {
+	const gates = effectiveGates(segments);
+	if (gates.some((gate) => gate.package !== undefined)) return gates;
+	const path = `/${segments.join("/")}`;
+	const below = [...PATH_CATALOG].filter(([known]) =>
+		known.startsWith(`${path}/`),
+	);
+	const packages = unique(below.map(([, entry]) => entry.package ?? ""));
+	if (below.length > 0 && packages.length === 1 && packages[0] !== "")
+		return [...gates, { path, package: packages[0] as string }];
+	return gates;
+}
+
+function gateAdvice(gates: readonly CatalogGate[]): string {
+	if (gates.length === 0)
+		return "MikroTik publishes no package or hardware requirement for it, so the usual cause is the RouterOS version: compare `/system/resource/print` with the version that introduced the menu.";
+	const parts = gates.map((gate) =>
+		[
+			gate.package && `package \`${gate.package}\``,
+			gate.syscap && `hardware capability \`${gate.syscap}\``,
+			gate.conditions && `build \`${gate.conditions}\``,
+		]
+			.filter(Boolean)
+			.join(" and "),
+	);
+	return `MikroTik publishes it as needing ${unique(parts).join("; ")}. Check \`/system/package/print\` and the device model, or run this only on devices that have it.`;
+}
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values)];
+}

package/src/api-fanout.ts

@@ -15,13 +15,14 @@
  *     with `target/unresolved`.
  *   - A mutating fan-out is confirmed ONCE up front (`--yes`), never per target;
  *     without `--yes` the error names the blast radius (how many routers).
- *   - `--listen`/`--stream` and `--raw` are rejected in fan-out mode by the CLI
+ *   - `--stream` and `--raw` are rejected in fan-out mode by the CLI
  *     before reaching here (single-session / envelope-stripping).
  */
 
 import {
 	type ApiEnvelope,
 	type ApiOperationMeta,
+	type ApiOutputFormat,
 	type ApiRequest,
 	type ApiRequestSummary,
 	type ApiSuccessEnvelope,
@@ -51,7 +52,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 { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
@@ -428,26 +434,26 @@ export function buildApiFanoutErrorEnvelope(
 }
 
 /**
- * Render an api fan-out envelope. `json`/`yaml` serialize the whole envelope;
- * `text` renders a summary line plus one line per target in record-index order.
+ * Render an api fan-out envelope. `json`/`yaml` serialize the whole envelope,
+ * `ndjson` as one compact line; `text` renders a summary line plus one line
+ * per target in record-index order.
  */
 export function renderApiFanoutEnvelope(
 	envelope: ApiFanoutEnvelope | ApiFanoutErrorEnvelope,
-	format: "json" | "yaml" | "text",
+	format: ApiOutputFormat,
 	options: { verbose?: boolean } = {},
 ): string {
 	if (format === "json") {
 		return JSON.stringify(envelope, null, 2);
 	}
+	if (format === "ndjson") {
+		return JSON.stringify(envelope);
+	}
 	if (format === "yaml") {
 		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;
@@ -468,10 +474,14 @@ export function renderApiFanoutEnvelope(
 			);
 		} 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}`),
+				);
 			}
 		}
 	}