@tikoci/centrs 0.1.0 → 0.1.2

package/src/core/fanout.ts

@@ -0,0 +1,160 @@
+/**
+ * Transport-agnostic fan-out engine.
+ *
+ * `retrieve` group fan-out (`src/retrieve-fanout.ts`) grew the reusable
+ * machinery: a bounded worker pool, transport-aware concurrency defaults, a
+ * retry allowlist with jittered backoff, and the ok/failed summary. `api` — and
+ * any later fan-out command — needs the identical behavior, so it lives here as
+ * one vocabulary. The command-specific orchestration (CDB group expansion,
+ * per-target resolve, envelope shaping, text rendering) stays in each command's
+ * fan-out module; this core only knows about generic items, concurrency, retry,
+ * and counting.
+ */
+
+import { CentrsError } from "../errors.ts";
+import type { RouterOsProtocol } from "../protocols/index.ts";
+import type { FanoutSummary } from "./envelope.ts";
+
+/** Transport-aware default worker-pool size (REST drops parallel POSTs above ~8). */
+export const FANOUT_CONCURRENCY_DEFAULTS: Record<
+	"rest-api" | "native-api",
+	number
+> = {
+	"rest-api": 8,
+	"native-api": 4,
+};
+
+/** Extra attempts after the first try (jittered backoff between them). */
+export const FANOUT_MAX_RETRIES = 2;
+
+/** Base backoff in milliseconds; doubled per attempt with up to +base jitter. */
+export const FANOUT_BACKOFF_BASE_MS = 200;
+
+/** RouterOS-style codes that are safe to retry under fan-out. */
+export const FANOUT_RETRYABLE_CODES = [
+	"transport/network",
+	"transport/connection-closed",
+] as const;
+
+/** Resolve and validate the worker-pool size. */
+export function resolveFanoutConcurrency(
+	requested: number | undefined,
+	via: RouterOsProtocol,
+): number {
+	if (requested !== undefined) {
+		if (!Number.isInteger(requested) || requested < 1) {
+			throw new CentrsError({
+				code: "usage/invalid-concurrency",
+				summary: `--concurrency must be an integer >= 1. Received: ${requested}`,
+				remediation: "Pass a positive integer, e.g. `--concurrency 4`.",
+				context: { concurrency: requested },
+			});
+		}
+		return requested;
+	}
+	if (via === "native-api") {
+		return FANOUT_CONCURRENCY_DEFAULTS["native-api"];
+	}
+	return FANOUT_CONCURRENCY_DEFAULTS["rest-api"];
+}
+
+/**
+ * Classify a per-target failure as retryable. Only the locked allowlist retries:
+ * generic transport/network failures and dropped/closed connections (including
+ * REST 5xx mapped to `transport/connection-closed`). Router-side (`routeros/*`),
+ * validation, auth, cdb, target, input, usage, timeout, TLS, connection-refused,
+ * and DNS failures are deterministic and never retried.
+ */
+export function isRetryableFanoutError(error: unknown): boolean {
+	if (!(error instanceof CentrsError)) {
+		return false;
+	}
+	return (FANOUT_RETRYABLE_CODES as readonly string[]).includes(error.code);
+}
+
+/** Count inner `ok`/`failed` across a completed target set. */
+export function summarizeFanout(
+	targets: readonly { ok: boolean }[],
+): FanoutSummary {
+	let ok = 0;
+	let failed = 0;
+	for (const target of targets) {
+		if (target.ok) {
+			ok += 1;
+		} else {
+			failed += 1;
+		}
+	}
+	return { total: targets.length, ok, failed };
+}
+
+/**
+ * Ordered bounded worker pool. Runs `worker` over `items` with at most
+ * `concurrency` in flight, returning results in INPUT order regardless of
+ * completion order.
+ */
+export async function runBoundedPool<I, O>(
+	items: readonly I[],
+	concurrency: number,
+	worker: (item: I, index: number) => Promise<O>,
+): Promise<O[]> {
+	const results = new Array<O>(items.length);
+	let next = 0;
+	const width = Math.max(1, Math.min(concurrency, items.length));
+
+	async function drain(): Promise<void> {
+		for (;;) {
+			const index = next;
+			next += 1;
+			if (index >= items.length) {
+				return;
+			}
+			results[index] = await worker(items[index] as I, index);
+		}
+	}
+
+	await Promise.all(Array.from({ length: width }, () => drain()));
+	return results;
+}
+
+/**
+ * Run `run`, retrying only {@link isRetryableFanoutError} failures up to
+ * `maxRetries` times with jittered backoff. A non-retryable error, or the final
+ * exhausted attempt, is converted to a value via `recover` (so a fan-out target
+ * yields an inner error envelope instead of throwing out of the batch).
+ */
+export async function runWithRetry<T>(
+	run: () => Promise<T>,
+	recover: (error: unknown) => T,
+	options: {
+		sleep?: (ms: number) => Promise<void>;
+		maxRetries?: number;
+	} = {},
+): Promise<T> {
+	const sleep = options.sleep ?? defaultFanoutSleep;
+	const maxRetries = options.maxRetries ?? FANOUT_MAX_RETRIES;
+	let attempt = 0;
+	for (;;) {
+		try {
+			return await run();
+		} catch (error) {
+			if (attempt < maxRetries && isRetryableFanoutError(error)) {
+				attempt += 1;
+				await sleep(fanoutBackoffMs(attempt));
+				continue;
+			}
+			return recover(error);
+		}
+	}
+}
+
+/** Backoff for attempt N: base·2^(N-1) plus up to +base jitter. */
+export function fanoutBackoffMs(attempt: number): number {
+	const base = FANOUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+	return base + Math.floor(Math.random() * FANOUT_BACKOFF_BASE_MS);
+}
+
+/** Real timer sleep; tests inject a no-op. */
+export function defaultFanoutSleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/core/inspect.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared `/console/inspect` client primitives.
+ *
+ * `retrieve` and `execute` each grew their own private copy of these helpers
+ * (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.
+ *
+ * Grounding: the request modes mirror `tikoci/lsp-routeros-ts`
+ * (`server/src/routeros.ts` `InspectRequest`). The behavioral facts (the array-
+ * typed `path`, completion shapes) are confirmed on CHR 7.23.1 in
+ * `commands/api/AGENTS.md` — read that before changing wire behavior here.
+ */
+
+import { CentrsError } from "../errors.ts";
+
+/**
+ * The transport seam this module needs. A {@link ProtocolAdapter} satisfies it
+ * structurally; depending on the narrow shape keeps `core/` decoupled from the
+ * protocol layer (no import cycle).
+ */
+export interface InspectBackend {
+	inspect(request: "child" | "completion", path: string): Promise<unknown[]>;
+}
+
+/**
+ * The `/console/inspect` request modes (lsp's `InspectRequest`). Only `child`
+ * and `completion` are wired today (the two the {@link InspectBackend} seam
+ * exposes); `highlight` (token-level error detection) and `syntax` (parse tree),
+ * plus the `input`/`.query`/`.proplist` request fields, are the documented
+ * Phase-2 extension point for value-level validation — widen the adapter seam
+ * when adding them.
+ */
+export type InspectRequestKind =
+	| "child"
+	| "completion"
+	| "highlight"
+	| "syntax";
+
+/** A row from `request=child`: a menu/argument node under a path. */
+export interface InspectChildItem {
+	type?: string;
+	name?: string;
+	"node-type"?: string;
+}
+
+/** A row from `request=completion`: a candidate token for a path/argument. */
+export interface InspectCompletionItem {
+	type?: string;
+	name?: string;
+	completion?: string;
+	value?: string;
+	text?: string;
+}
+
+/**
+ * Split a slash RouterOS path into menu tokens, dropping the leading slash and
+ * empties: `"/ip/address"` → `["ip", "address"]`.
+ */
+export function pathTokens(path: string): string[] {
+	return path.split("/").filter(Boolean);
+}
+
+/**
+ * Join menu tokens into the COMMA form `/console/inspect` expects for its `path`
+ * argument: `["ip", "address"]` → `"ip,address"`.
+ *
+ * The inspect `path` argument is internally a RouterOS *array*: a comma string
+ * is `:toarray`-split into the menu-walk tokens, whereas a `/`-prefixed command
+ * string is not split and matches no menu (confirmed on CHR 7.23.1 — slash forms
+ * return nothing; see `commands/api/AGENTS.md`). So callers must pass tokens
+ * joined by comma, never a slash command.
+ */
+export function inspectPath(tokens: readonly string[]): string {
+	return tokens.join(",");
+}
+
+/** True for an argument (`arg`) node from `request=child`. */
+export function isArgumentNode(child: InspectChildItem): boolean {
+	return child.type === "arg" || child["node-type"] === "arg";
+}
+
+/** True for a command (`cmd`) node with the given name (e.g. `print`, `get`). */
+export function isCommandNode(child: InspectChildItem, name: string): boolean {
+	return (
+		child.name === name &&
+		(child.type === "cmd" || child["node-type"] === "cmd")
+	);
+}
+
+/**
+ * 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).
+ */
+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);
+}
+
+/** `request=child` for a token path. */
+export async function inspectChildren(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectChildItem[]> {
+	return (await backend.inspect(
+		"child",
+		inspectPath(tokens),
+	)) as InspectChildItem[];
+}
+
+/** `request=completion` for a token path. */
+export async function inspectCompletions(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectCompletionItem[]> {
+	return (await backend.inspect(
+		"completion",
+		inspectPath(tokens),
+	)) as InspectCompletionItem[];
+}
+
+/**
+ * {@link inspectChildren} that swallows a "path not found" trap to an empty
+ * list, so the caller can classify the absence itself (REST returns an empty
+ * child list; native traps). Only the two grounded not-found codes are
+ * swallowed — `routeros/unknown-path` (the classified form) and the legacy
+ * `routeros/api-trap` catch-all; every other error propagates. Use this for the
+ * existence probe, not for attribute/value discovery (where a trap is a real
+ * failure).
+ */
+export async function inspectChildrenOrEmpty(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<InspectChildItem[]> {
+	try {
+		return await inspectChildren(backend, tokens);
+	} catch (error) {
+		if (
+			error instanceof CentrsError &&
+			(error.code === "routeros/api-trap" ||
+				error.code === "routeros/unknown-path")
+		) {
+			return [];
+		}
+		throw error;
+	}
+}

package/src/discover.ts

@@ -18,7 +18,8 @@
  */
 
 import { createSocket } from "node:dgram";
-import type { CentrsEnvelope, EnvelopeMeta } from "./core/envelope.ts";
+import type { CentrsEnvelope, EnvelopeMeta, Tip } from "./core/envelope.ts";
+import { buildTip } from "./core/envelope.ts";
 import {
 	MNDP_BROADCAST_ADDRESS,
 	MNDP_PORT,
@@ -27,7 +28,7 @@ import {
 	parseMndpPacket,
 } from "./data/mndp.ts";
 import { MndpCache } from "./data/mndp-cache.ts";
-import { winBoxCdbRecordType } from "./data/winbox-cdb.ts";
+import { type WinBoxCdbEntry, winBoxCdbRecordType } from "./data/winbox-cdb.ts";
 import type { WriteWinBoxCdbOptions } from "./data/winbox-cdb-write.ts";
 import {
 	addDevice,
@@ -37,7 +38,8 @@ import {
 	resolveDevicesSettings,
 } from "./devices.ts";
 import { asCentrsError, CentrsError, serializeCentrsError } from "./errors.ts";
-import { renderCommentKvToken } from "./resolver/comment-kv.ts";
+import { parseCommentKv, renderCommentKvToken } from "./resolver/comment-kv.ts";
+import { normalizeMac } from "./resolver/mac.ts";
 
 export { MNDP_PORT, MndpCache };
 
@@ -396,38 +398,75 @@ function toDiscoverNeighbor(
 }
 
 /**
- * Build the human/structured comment for a saved neighbor. The only kv token is
- * the allowlisted `source=mndp`; the parenthesized detail is free-form (no
- * `key=value` shapes) so it preserves provenance without emitting
- * `cdb/unknown-option` warnings later.
+ * Build the comment for a saved neighbor: the allowlisted `source=mndp` token
+ * and the `identity=`/`mac=` **lookup keys** (so the device resolves by any of
+ * its identifiers — see `commands/devices/README.md`, Identity model), followed
+ * by a free-form, parenthesized provenance detail. `identity=` is written
+ * whenever advertised; `mac=` only when the **target is the IP** (a `macTarget`
+ * record's target already *is* the MAC, so a `mac=` key would be redundant). The
+ * parenthesized detail carries no `key=value` shapes, so it stays inert and
+ * never emits a `cdb/unknown-option` warning later.
  */
+
+// Strip `=` from free-form device-advertised strings so they can't be
+// misinterpreted as lookup key=value tokens if parseCommentKv ever processes
+// the parenthesized section.
+function sanitizeDetail(value: string): string {
+	return value.replaceAll("=", "≔");
+}
+
 export function formatMndpProvenanceComment(
 	neighbor: MndpNeighbor,
 	at: Date,
 ): string {
-	const detail: string[] = [`discovered ${at.toISOString()} via MNDP`];
+	const tokens: string[] = [renderCommentKvToken("source", "mndp")];
 	if (neighbor.identity) {
-		detail.push(`identity: ${neighbor.identity}`);
+		tokens.push(renderCommentKvToken("identity", neighbor.identity));
+	}
+	if (neighbor.ipv4 && neighbor.macAddress) {
+		tokens.push(renderCommentKvToken("mac", neighbor.macAddress));
 	}
+	const detail: string[] = [`discovered ${at.toISOString()} via MNDP`];
 	if (neighbor.platform) {
-		detail.push(`platform: ${neighbor.platform}`);
+		detail.push(`platform: ${sanitizeDetail(neighbor.platform)}`);
 	}
 	if (neighbor.board) {
-		detail.push(`board: ${neighbor.board}`);
+		detail.push(`board: ${sanitizeDetail(neighbor.board)}`);
 	}
 	if (neighbor.version) {
-		detail.push(`version: ${neighbor.version}`);
-	}
-	if (neighbor.macAddress) {
-		detail.push(`mac: ${neighbor.macAddress}`);
+		detail.push(`version: ${sanitizeDetail(neighbor.version)}`);
 	}
 	if (neighbor.interfaceName) {
-		detail.push(`interface: ${neighbor.interfaceName}`);
+		detail.push(`interface: ${sanitizeDetail(neighbor.interfaceName)}`);
 	}
 	if (neighbor.softwareId) {
-		detail.push(`software-id: ${neighbor.softwareId}`);
+		detail.push(`software-id: ${sanitizeDetail(neighbor.softwareId)}`);
 	}
-	return `${renderCommentKvToken("source", "mndp")} (${detail.join("; ")})`;
+	return `${tokens.join(" ")} (${detail.join("; ")})`;
+}
+
+/**
+ * True when a discovered neighbor's MAC already names a CDB entry — as the
+ * `target` of a `macTarget` record or as a `mac=` lookup key on any record. MNDP
+ * always carries the MAC and it is globally unique, so it is the de-dupe key
+ * (`commands/discover/README.md`, `--save` de-dupe); `identity` is *not*, since
+ * factory-default devices all report `MikroTik`.
+ */
+function neighborMacKnown(
+	entries: readonly WinBoxCdbEntry[],
+	mac: string | undefined,
+): boolean {
+	const want = normalizeMac(mac ?? "");
+	if (!want) {
+		return false;
+	}
+	return entries.some((entry) => {
+		if (normalizeMac(entry.target) === want) {
+			return true;
+		}
+		const lookupMac = parseCommentKv(entry.comment).lookups.mac;
+		return lookupMac !== undefined && normalizeMac(lookupMac) === want;
+	});
 }
 
 /** Target a neighbor maps to in the CDB: its IPv4, else its MAC. */
@@ -457,9 +496,12 @@ export interface SaveDiscoveredNeighborsResult {
 
 /**
  * Persist discovered neighbors into the CDB via {@link addDevice}. De-dupe
- * rule: a neighbor whose target (IPv4, else MAC) already names a CDB entry is
- * skipped — never overwritten — so hand-curated records win. New neighbors are
- * added with `group=discovered` and `source=mndp` provenance. The CDB is
+ * rule: a neighbor whose **MAC** already names a CDB entry — as a `macTarget`
+ * record's `target` or a `mac=` lookup key on any record (see
+ * {@link neighborMacKnown}) — is skipped, never overwritten; a neighbor whose
+ * `target` string already names an entry is likewise skipped. Hand-curated
+ * records always win. New neighbors are added with `group=discovered`, the
+ * `identity=`/`mac=` lookup keys, and `source=mndp` provenance. The CDB is
  * reloaded between writes so each `addDevice` sees the prior additions.
  */
 export async function saveDiscoveredNeighbors(
@@ -484,7 +526,13 @@ export async function saveDiscoveredNeighbors(
 		if (!target) {
 			continue;
 		}
-		const exists = cdb.entries.some((entry) => entry.target === target);
+		// De-dupe on the MAC (globally unique, always advertised), and also skip a
+		// target string that already names an entry — both guard a hand-curated
+		// record from being clobbered, and the latter keeps `addDevice` from
+		// failing `cdb/already-exists` on a colliding connectable address.
+		const exists =
+			neighborMacKnown(cdb.entries, neighbor.macAddress) ||
+			cdb.entries.some((entry) => entry.target === target);
 		const detail: DiscoverSaveRecord = {
 			target,
 			action: exists ? "skipped-existing" : "added",
@@ -646,11 +694,22 @@ export async function discover(
 		}
 	}
 
+	const tips: Tip[] = [];
+	if (!options.save && neighbors.length > 0) {
+		tips.push(
+			buildTip(
+				"tip/discover-save",
+				`Found ${neighbors.length} neighbor(s); this run did not save them (read-only without --save).`,
+				"Re-run with `--save` to persist them into the CDB (group=discovered) so you can target them by identity/ip/mac.",
+			),
+		);
+	}
+
 	return {
 		ok: true,
 		data: { count: neighbors.length, neighbors },
 		warnings,
-		tips: [],
+		tips,
 		meta: discoverMeta(operation, options),
 	};
 }
@@ -743,9 +802,23 @@ function renderDiscoverText(envelope: DiscoverEnvelope): string {
 		);
 	}
 	appendDiscoverWarnings(lines, envelope.warnings);
+	appendDiscoverTips(lines, envelope.tips);
 	return lines.join("\n");
 }
 
+function appendDiscoverTips(lines: string[], tips: readonly Tip[]): void {
+	if (tips.length === 0) {
+		return;
+	}
+	lines.push("Tips:");
+	for (const item of tips) {
+		lines.push(`  - [${item.code}] ${item.message}`);
+		if (item.fix) {
+			lines.push(`    fix: ${item.fix}`);
+		}
+	}
+}
+
 function appendDiscoverWarnings(
 	lines: string[],
 	warnings: readonly DevicesWarning[],

package/src/execute.ts

@@ -9,6 +9,13 @@ import type {
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
+import {
+	extractCompletionNames,
+	inspectChildren,
+	inspectCompletions,
+	isArgumentNode,
+	pathTokens,
+} from "./core/inspect.ts";
 import { mapRouterOsError } from "./core/routeros-errors.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
@@ -132,20 +139,6 @@ export interface ResolvedExecuteRequest {
 	warnings: readonly Warning[];
 }
 
-interface InspectChildItem {
-	type?: string;
-	name?: string;
-	"node-type"?: string;
-}
-
-interface InspectCompletionItem {
-	type?: string;
-	name?: string;
-	completion?: string;
-	value?: string;
-	text?: string;
-}
-
 export async function execute(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined> = Bun.env,
@@ -735,24 +728,18 @@ async function inspectExecuteAttributes(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
 ): Promise<string[]> {
-	const commandPath = inspectPath([
+	const commandTokens = [
 		...pathTokens(resolved.canonical.path),
 		resolved.canonical.verb,
-	]);
-	const children = (await backend.inspect(
-		"child",
-		commandPath,
-	)) as InspectChildItem[];
+	];
+	const children = await inspectChildren(backend, commandTokens);
 	const childAttributes = children
 		.filter(isArgumentNode)
 		.map((child) => child.name)
 		.filter(
 			(name): name is string => typeof name === "string" && name.length > 0,
 		);
-	const completionRows = (await backend.inspect(
-		"completion",
-		commandPath,
-	)) as InspectCompletionItem[];
+	const completionRows = await inspectCompletions(backend, commandTokens);
 	return [
 		...new Set([...childAttributes, ...extractCompletionNames(completionRows)]),
 	].sort();
@@ -819,7 +806,9 @@ async function assertWriteConfirmed(
 	});
 }
 
-async function promptForWriteConfirmation(prompt: string): Promise<boolean> {
+export async function promptForWriteConfirmation(
+	prompt: string,
+): Promise<boolean> {
 	process.stderr.write(prompt);
 	for await (const chunk of Bun.stdin.stream()) {
 		const answer = new TextDecoder().decode(chunk).trim().toLowerCase();
@@ -1299,28 +1288,6 @@ function syntaxCause(error: unknown): unknown {
 	return error;
 }
 
-function pathTokens(path: string): string[] {
-	return path.split("/").filter(Boolean);
-}
-
-function inspectPath(tokens: readonly string[]): string {
-	return tokens.join(",");
-}
-
-function isArgumentNode(child: InspectChildItem): boolean {
-	return child.type === "arg" || child["node-type"] === "arg";
-}
-
-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) => value.replace(/=.*$/, "").trim())
-		.filter((value) => value.length > 0);
-}
-
 function parseOutputFormat(value: string): ExecuteOutputFormat {
 	if (executeOutputFormats.includes(value as ExecuteOutputFormat)) {
 		return value as ExecuteOutputFormat;