@tikoci/centrs 0.1.0

package/src/core/routeros-errors.ts

@@ -0,0 +1,268 @@
+/**
+ * Grounded RouterOS error vocabulary.
+ *
+ * RouterOS surfaces faults as plain strings. Over REST those strings arrive in
+ * the HTTP `detail` field (HTTP >=400); over the native API they arrive as the
+ * `!trap` `message` attribute. Grounded on CHR 7.23, the two transports carry
+ * the **same** text for the same fault, so one ordered rule table maps both.
+ *
+ * `mapRouterOsError` is the single place that turns a raw RouterOS string into a
+ * typed `CentrsError`. New groundings are added by appending a rule to
+ * `routerOsErrorRules`; the matcher is ordered, first-match-wins. Every mapping
+ * preserves the original RouterOS string in `context.detail` so nothing is lost.
+ *
+ * The authoritative vocabulary is the live router's own strings (see
+ * `docs/CONSTITUTION.md`, "Error model"). Ground new mappings on CHR evidence,
+ * not on assumption.
+ */
+
+import {
+	CentrsError,
+	type CentrsErrorCode,
+	type RouterOsErrorPosition,
+} from "../errors.ts";
+
+/**
+ * Matches RouterOS's `(line N column M)` source location. Not anchored — the
+ * console embeds it mid-string (e.g. `(evl bad parameter no-such-arg (line 1
+ * column 28) /ip/address/add)`), so the location is found wherever it appears.
+ */
+const ROUTEROS_POSITION_RE = /\(line (\d+) column (\d+)\)/i;
+
+/**
+ * Extract RouterOS's `(line N column M)` parse position from a raw fault string,
+ * or `undefined` when absent. The console `:parse` rejection carries it — either
+ * bare (`bad parameter address (line 1 column 35)`) or embedded in the parsed
+ * `(evl … (line N column M) /path)` form; REST/native `unknown parameter` strings
+ * do not. `column` is RouterOS's authoritative 1-based **byte** offset — see
+ * {@link RouterOsErrorPosition}.
+ */
+export function parseRouterOsPosition(
+	text: string,
+): RouterOsErrorPosition | undefined {
+	const match = text.match(ROUTEROS_POSITION_RE);
+	if (!match) {
+		return undefined;
+	}
+	const line = Number.parseInt(match[1] ?? "", 10);
+	const column = Number.parseInt(match[2] ?? "", 10);
+	if (!Number.isFinite(line) || !Number.isFinite(column)) {
+		return undefined;
+	}
+	return { line, column };
+}
+
+/** Transport that produced the raw RouterOS string. */
+export type RouterOsErrorTransport =
+	| "rest-api"
+	| "native-api"
+	| "mac-telnet"
+	| "ssh";
+
+/** Options that refine how a raw RouterOS string is mapped. */
+export interface MapRouterOsErrorOptions {
+	/** Transport the string came from; selects the catch-all code. */
+	transport?: RouterOsErrorTransport;
+	/** HTTP status, when the string came from a REST `detail` body. */
+	httpStatus?: number;
+	/** Extra context merged into the resulting error (caller wins). */
+	context?: Record<string, unknown>;
+}
+
+/** What a rule's `build` step contributes to the resulting error. */
+export interface RouterOsErrorRuleResult {
+	summary: string;
+	remediation: string;
+	context?: Record<string, unknown>;
+}
+
+/**
+ * One ordered grounding rule. `test` is matched (case-insensitively) against the
+ * trimmed RouterOS string; the first rule whose `test` matches wins and its
+ * `build` produces the normalized error fields.
+ */
+export interface RouterOsErrorRule {
+	/** Normalized `routeros/*` code this rule yields. */
+	code: CentrsErrorCode;
+	/** One-line human description of the fault class (used for docs/tests). */
+	description: string;
+	/** Pattern matched against the trimmed RouterOS string. */
+	test: RegExp;
+	/** Builds the normalized error fields from the regex match and raw string. */
+	build: (match: RegExpMatchArray, raw: string) => RouterOsErrorRuleResult;
+}
+
+function cleanToken(token: string): string {
+	return token.replace(/^["'`]+|["'`.,;:]+$/g, "");
+}
+
+/**
+ * Ordered RouterOS error groundings (CHR 7.23). First match wins. Append new
+ * rules here; keep the most specific patterns above broader ones.
+ */
+export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
+	{
+		code: "routeros/unknown-path",
+		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,
+		build: (_match, raw) => ({
+			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
+			remediation:
+				"Check the slash-prefixed RouterOS path against the device's command tree (use `--list-attributes` or `--no-validate` to narrow the mismatch).",
+		}),
+	},
+	{
+		code: "routeros/unknown-attribute",
+		description: "RouterOS rejected an unknown parameter/attribute name.",
+		// REST/native say "unknown parameter <name>"; the interactive console
+		// (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,
+		build: (match) => {
+			const parameter = cleanToken(match[1] ?? "");
+			return {
+				summary: `RouterOS does not recognize the parameter "${parameter}".`,
+				remediation:
+					"Remove or rename the attribute; use `--list-attributes` to see the parameters this RouterOS path accepts.",
+				context: { parameter },
+			};
+		},
+	},
+	{
+		code: "routeros/unknown-path",
+		description:
+			"RouterOS console rejected the command word ('bad command name …').",
+		// Console form (mac-telnet) of an unrecognized command/path word.
+		test: /bad command name/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS does not recognize the command: ${raw.trim()}`,
+			remediation:
+				"Check the slash-prefixed RouterOS path/command against the device's command tree.",
+		}),
+	},
+	{
+		code: "routeros/invalid-value",
+		description: "RouterOS rejected the value supplied for an argument.",
+		test: /invalid value (?:for argument|of)\s+(\S+)/i,
+		build: (match) => {
+			const argument = cleanToken(match[1] ?? "");
+			return {
+				summary: `RouterOS rejected the value supplied for "${argument}".`,
+				remediation:
+					"Supply a value that matches the argument's expected type/format for this RouterOS path.",
+				context: { argument },
+			};
+		},
+	},
+	{
+		code: "routeros/session-closed",
+		description:
+			"RouterOS closed the REST session before the request completed (60-second cap).",
+		test: /session closed/i,
+		build: () => ({
+			summary: "RouterOS closed the session before the request completed.",
+			remediation:
+				"RouterOS enforces a 60-second hard timeout on REST sessions; reduce the scope of the request or choose a path that completes within that ceiling.",
+		}),
+	},
+	{
+		code: "routeros/command-failed",
+		description:
+			"Generic RouterOS command failure carrying a `failure: <msg>` string.",
+		test: /^\s*failure:\s*(.+?)\s*$/i,
+		build: (match) => {
+			const failure = (match[1] ?? "").trim();
+			return {
+				summary: `RouterOS command failed: ${failure}`,
+				remediation:
+					"Inspect the RouterOS failure message, then adjust the path, attributes, 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,
+		build: (match) => {
+			const failure = (match[1] ?? "").trim();
+			return {
+				summary: `RouterOS command failed: ${failure}`,
+				remediation:
+					"Inspect the RouterOS failure message, then adjust the script or request shape accordingly.",
+				context: { failure },
+			};
+		},
+	},
+	{
+		// Bare path-shaped `<path> not found` (no `failure:` prefix). Placed AFTER
+		// `routeros/command-failed` so a `failure: <object> not found` command
+		// rejection is classified as a command failure, not a path mismatch.
+		code: "routeros/unknown-path",
+		description: "RouterOS reported a path-shaped 'not found'.",
+		test: /not found/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
+			remediation:
+				"Check the slash-prefixed RouterOS path against the device's command tree (use `--list-attributes` or `--no-validate` to narrow the mismatch).",
+		}),
+	},
+];
+
+/**
+ * Maps a raw RouterOS error string to a normalized {@link CentrsError}.
+ *
+ * Matching is case-insensitive and tolerant of leading/trailing whitespace and
+ * an optional `failure: ` prefix. When no rule matches, the catch-all depends on
+ * the transport: native API yields `routeros/api-trap`, REST yields
+ * `routeros/request-failed`. The original string is always preserved in
+ * `context.detail` (and `cause` for the catch-all).
+ */
+export function mapRouterOsError(
+	raw: string,
+	opts: MapRouterOsErrorOptions = {},
+): CentrsError {
+	const trimmed = raw.trim();
+	const position = parseRouterOsPosition(raw);
+	const baseContext: Record<string, unknown> = {
+		detail: raw,
+		...(opts.httpStatus !== undefined ? { httpStatus: opts.httpStatus } : {}),
+	};
+
+	for (const rule of routerOsErrorRules) {
+		const match = trimmed.match(rule.test);
+		if (!match) {
+			continue;
+		}
+		const result = rule.build(match, raw);
+		return new CentrsError({
+			code: rule.code,
+			summary: result.summary,
+			remediation: result.remediation,
+			context: { ...baseContext, ...result.context, ...opts.context },
+			...(position ? { position } : {}),
+			causeData: raw,
+		});
+	}
+
+	const catchAllCode: CentrsErrorCode =
+		opts.transport === "rest-api" ||
+		opts.transport === "mac-telnet" ||
+		opts.transport === "ssh"
+			? "routeros/request-failed"
+			: "routeros/api-trap";
+
+	return new CentrsError({
+		code: catchAllCode,
+		summary: trimmed
+			? `RouterOS reported an error: ${trimmed}`
+			: "RouterOS reported an unspecified error.",
+		remediation:
+			"Inspect the original RouterOS message; the command word, path, or an attribute is likely invalid.",
+		context: { ...baseContext, ...opts.context },
+		...(position ? { position } : {}),
+		causeData: raw,
+	});
+}

package/src/data/AGENTS.md

@@ -0,0 +1,11 @@
+# Data Source Rules
+
+Follow `docs/CONSTITUTION.md` (identity / CDB sections) and
+`commands/devices/README.md`.
+
+- Keep device source provenance visible: explicit input, environment, SQLite cache, WinBox CDB, The Dude `dude.db`, and MNDP are not equally authoritative.
+- Do not silently persist credentials or discovered devices. Persistence must be controlled by a typed setting and explained in interactive output.
+- MNDP is a hint source. Lack of MNDP data must not make a device invalid.
+- Prefer shared SQLite infrastructure over one database per feature unless a spec justifies separation.
+- Reuse tikoci `donny` knowledge for Dude database structures and related Nova/TLV encoding.
+- `mndp.ts` TypeDoc should document the MNDP TLV structure and attribute values inline (type codes, field meanings), so the generated API docs are self-sufficient and centrs consumers do not have to depend on the external `routeros-mndp` skill for the wire format. The skill stays canonical; the typedoc must stand alone.

package/src/data/mndp-cache.ts

@@ -0,0 +1,132 @@
+/**
+ * In-memory MNDP neighbor cache with a TTL/expiry policy.
+ *
+ * MNDP devices announce themselves on a ~30/60s cycle (and reply within
+ * seconds to a refresh), so the natural shape is a short-lived cache keyed by
+ * MAC that forgets neighbors which stop announcing. This is a process-local
+ * cache only — the CDB remains the single durable datastore (see
+ * `docs/CONSTITUTION.md`); nothing here is persisted.
+ *
+ * TTL decision (folded into `commands/discover/README.md`): entries expire
+ * {@link MNDP_CACHE_DEFAULT_TTL_MS} (180s = three announce cycles) after they
+ * were last seen. Three cycles tolerates a couple of dropped broadcasts before
+ * a still-present neighbor is dropped. The clock is injectable so expiry is
+ * deterministic in tests.
+ */
+
+import { type MndpNeighbor, mndpNeighborKey } from "./mndp.ts";
+
+/** Default neighbor TTL: three ~60s announce cycles. */
+export const MNDP_CACHE_DEFAULT_TTL_MS = 180_000;
+
+export interface MndpCacheEntry {
+	/** Cache key (lower-cased MAC, or a synthetic key for MAC-less packets). */
+	key: string;
+	/** Most recent decoded announcement for this key. */
+	neighbor: MndpNeighbor;
+	/** Epoch ms when this key was first observed in the cache's lifetime. */
+	firstSeenAt: number;
+	/** Epoch ms when this key was last observed; drives expiry. */
+	lastSeenAt: number;
+}
+
+export interface MndpCacheOptions {
+	/** Time-to-live in ms after `lastSeenAt`. Default 180000. */
+	ttlMs?: number;
+	/** Clock injection (epoch ms). Defaults to `Date.now`. */
+	now?: () => number;
+}
+
+/** A neighbor cache that expires entries TTL ms after they were last seen. */
+export class MndpCache {
+	private readonly ttlMs: number;
+	private readonly clock: () => number;
+	private readonly store = new Map<string, MndpCacheEntry>();
+
+	constructor(options: MndpCacheOptions = {}) {
+		this.ttlMs = options.ttlMs ?? MNDP_CACHE_DEFAULT_TTL_MS;
+		this.clock = options.now ?? Date.now;
+	}
+
+	/** TTL this cache enforces, in milliseconds. */
+	get timeToLiveMs(): number {
+		return this.ttlMs;
+	}
+
+	private isExpired(entry: MndpCacheEntry, at: number): boolean {
+		return at - entry.lastSeenAt >= this.ttlMs;
+	}
+
+	/**
+	 * Record a freshly decoded neighbor. Upserts by {@link mndpNeighborKey},
+	 * refreshing `lastSeenAt` and replacing the stored announcement. Returns the
+	 * resulting entry.
+	 */
+	observe(neighbor: MndpNeighbor, at: number = this.clock()): MndpCacheEntry {
+		const key = mndpNeighborKey(neighbor);
+		const existing = this.store.get(key);
+		const firstSeenAt =
+			existing && !this.isExpired(existing, at) ? existing.firstSeenAt : at;
+		const entry: MndpCacheEntry = {
+			key,
+			neighbor,
+			firstSeenAt,
+			lastSeenAt: at,
+		};
+		this.store.set(key, entry);
+		return entry;
+	}
+
+	/** Look up a single neighbor by MAC (case-insensitive); skips expired ones. */
+	get(mac: string, at: number = this.clock()): MndpCacheEntry | undefined {
+		const entry = this.store.get(mac.toLowerCase());
+		if (!entry || this.isExpired(entry, at)) {
+			return undefined;
+		}
+		return entry;
+	}
+
+	/** Drop expired entries; returns the number removed. */
+	prune(at: number = this.clock()): number {
+		let removed = 0;
+		for (const [key, entry] of this.store) {
+			if (this.isExpired(entry, at)) {
+				this.store.delete(key);
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+
+	/** Number of non-expired entries currently held. */
+	size(at: number = this.clock()): number {
+		let count = 0;
+		for (const entry of this.store.values()) {
+			if (!this.isExpired(entry, at)) {
+				count += 1;
+			}
+		}
+		return count;
+	}
+
+	/** Live entries sorted by cache key (deterministic ordering). */
+	entries(at: number = this.clock()): readonly MndpCacheEntry[] {
+		const live: MndpCacheEntry[] = [];
+		for (const entry of this.store.values()) {
+			if (!this.isExpired(entry, at)) {
+				live.push(entry);
+			}
+		}
+		return live.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+	}
+
+	/** Live neighbors sorted by cache key (deterministic ordering). */
+	neighbors(at: number = this.clock()): readonly MndpNeighbor[] {
+		return this.entries(at).map((entry) => entry.neighbor);
+	}
+
+	/** Remove every entry. */
+	clear(): void {
+		this.store.clear();
+	}
+}