@tikoci/centrs 0.1.7 → 0.1.8

package/src/explain/menus.ts

@@ -5,7 +5,7 @@
  * the drift gate. The generator (`scripts/gen-explain-menus.ts`) carries the
  * full rationale, the source pin, and why absence here is safe.
  *
- * Union of the `dir` and `path` nodes in 6 pinned restraml typed trees
+ * Union of the `dir` and `path` nodes in 8 pinned restraml typed trees
  * (`https://tikoci.github.io/restraml/`), all extra-packages builds:
  *
  * | Tree | Arch | RouterOS | Nodes | Containers |
@@ -16,9 +16,11 @@
  * | `7.24.4/extra/deep-inspect.arm64.json` | arm64 | 7.24.4 | 42,691 | 575 |
  * | `7.25beta5/extra/deep-inspect.x86.json` | x86 | 7.25beta5 | 41,794 | 557 |
  * | `7.25beta5/extra/deep-inspect.arm64.json` | arm64 | 7.25beta5 | 43,150 | 578 |
+ * | `7.26beta1/extra/deep-inspect.x86.json` | x86 | 7.26beta1 | 43,294 | 576 |
+ * | `7.26beta1/extra/deep-inspect.arm64.json` | arm64 | 7.26beta1 | 44,650 | 597 |
  *
  * Zero node-type conflicts across those trees — no `dir`↔`cmd` flip across
- * 4 versions or across architectures — which is what makes the union
+ * 5 versions or across architectures — which is what makes the union
  * version-less rather than version-keyed. Generation aborts if that ever stops
  * holding.
  *
@@ -57,6 +59,18 @@ export const MENU_PATHS: ReadonlySet<string> = new Set([
 	"/certificate/scep-server/ra",
 	"/certificate/scep-server/requests",
 	"/certificate/settings",
+	"/cmr",
+	"/cmr/alert",
+	"/cmr/client",
+	"/cmr/device",
+	"/cmr/layout",
+	"/cmr/layout/link",
+	"/cmr/layout/node",
+	"/cmr/upgrade",
+	"/cmr/upgrade/job",
+	"/cmr/vlan",
+	"/cmr/wifi",
+	"/cmr/wifi/radio",
 	"/console",
 	"/console/settings",
 	"/container",
@@ -183,6 +197,8 @@ export const MENU_PATHS: ReadonlySet<string> = new Set([
 	"/interface/wifi/capsman/remote-cap",
 	"/interface/wifi/channel",
 	"/interface/wifi/configuration",
+	"/interface/wifi/dashboard",
+	"/interface/wifi/dashboard/settings",
 	"/interface/wifi/datapath",
 	"/interface/wifi/interworking",
 	"/interface/wifi/network",
@@ -526,6 +542,8 @@ export const MENU_PATHS: ReadonlySet<string> = new Set([
 	"/system/clock/manual",
 	"/system/console",
 	"/system/console/screen",
+	"/system/dashboard",
+	"/system/dashboard/settings",
 	"/system/default-configuration",
 	"/system/default-configuration/caps-mode-script",
 	"/system/default-configuration/custom-script",
@@ -583,6 +601,9 @@ export const MENU_PATHS: ReadonlySet<string> = new Set([
 	"/task",
 	"/terminal",
 	"/tool",
+	"/tool/apptraffic",
+	"/tool/apptraffic/stats",
+	"/tool/apptraffic/stats/categories",
 	"/tool/bandwidth-server",
 	"/tool/bandwidth-server/session",
 	"/tool/calea",

package/src/explain.ts

@@ -108,7 +108,11 @@ import {
 	isWriteShaped,
 } from "./core/execute-command.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import { argSpans } from "./explain/arg-tokens.ts";
 import {
 	type ArgumentKind,
@@ -2495,11 +2499,7 @@ function renderExplainText(
 ): 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));
 		lines.push(...tipLines(envelope.tips));
 		return lines.join("\n");
 	}

package/src/index.ts

@@ -12,10 +12,10 @@ export {
 	type ApiSuccessEnvelope,
 	api,
 	apiEnvelope,
-	apiListen,
 	apiMethods,
 	apiOutputFormats,
 	apiRequestSummaryFromRequest,
+	apiStream,
 	buildApiBody,
 	buildApiErrorEnvelope,
 	buildApiErrorEnvelopeFromResolved,
@@ -85,6 +85,7 @@ export {
 	normalizeWarnings,
 	type SettingSource,
 	type SettingSourceKind,
+	type ValidationTrace,
 	type Warning,
 } from "./core/envelope.ts";
 export {
@@ -576,24 +577,36 @@ export {
 	type TargetSelection,
 	toCoreSource,
 } from "./resolver/index.ts";
+export type { RetrieveWaitMeta, RetrieveWaitSettings } from "./retrieve.ts";
 export {
 	buildResolvedRetrieve,
 	buildRetrieveErrorEnvelope,
 	buildRetrieveErrorEnvelopeFromResolved,
+	FOLLOW_SWEEP_DEFAULT_MS,
 	type ResolvedRetrieveRequest,
 	type RetrieveEnvelope,
 	type RetrieveErrorEnvelope,
+	type RetrieveFollowCounts,
+	type RetrieveFollowSettings,
+	type RetrieveFollowStopReason,
+	type RetrieveFollowSummary,
 	type RetrieveGlobalContext,
 	type RetrieveOperationMeta,
+	type RetrieveOptions,
 	type RetrieveOutputFormat,
 	type RetrieveRequest,
 	type RetrieveRequestSummary,
+	type RetrieveSampleSettings,
+	type RetrieveSampleStopReason,
+	type RetrieveSampleSummary,
+	type RetrieveStreamMeta,
 	type RetrieveSuccessEnvelope,
 	type RetrieveWarning,
 	renderRetrieveEnvelope,
 	resolveRetrieveGlobalContext,
 	resolveRetrieveRequest,
 	retrieve,
+	retrieveEnvelope,
 	retrieveOutputFormats,
 	runResolvedRetrieve,
 	validateRetrieveRequestShape,
@@ -611,6 +624,17 @@ export {
 	retrieveFanout,
 	retrieveGroup,
 } from "./retrieve-fanout.ts";
+export {
+	FOLLOW_BUFFER_LIMIT,
+	type RetrieveFollowOptions,
+	retrieveFollow,
+} from "./retrieve-follow.ts";
+export {
+	type RetrieveSampleOptions,
+	retrieveSample,
+} from "./retrieve-sample.ts";
+export { renderRetrieveStreamLine } from "./retrieve-stream.ts";
+export { type RetrieveWaitOptions, retrieveWait } from "./retrieve-wait.ts";
 export {
 	buildSettingsErrorEnvelope,
 	renderSettingsEnvelope,
@@ -652,10 +676,12 @@ export {
 } from "./terminal.ts";
 export {
 	buildTransferErrorEnvelope,
+	buildTransferErrorEnvelopeFromResolved,
 	FILE_READ_CHUNK_BYTES,
 	isTransferWriteVerb,
 	normalizeRemotePath,
 	REST_FILE_WRITE_CAP_BYTES,
+	type ResolvedTransferRequest,
 	renderTransferEnvelope,
 	resolveTransferRequest,
 	runResolvedTransfer,
@@ -666,11 +692,13 @@ export {
 	type TransferMethod,
 	type TransferOp,
 	type TransferOperationMeta,
+	type TransferOptions,
 	type TransferOutputFormat,
 	type TransferRequest,
 	type TransferSuccessEnvelope,
 	type TransferVerb,
 	transfer,
+	transferEnvelope,
 	transferMethods,
 	transferOutputFormats,
 	transferVerbs,

package/src/mcp/safety.ts

@@ -10,7 +10,12 @@
  * `mcp=rw`, else `cdb/write-not-permitted`.
  */
 
-import { type LoadedCdb, loadCdb } from "../devices.ts";
+import {
+	type DevicesShowItem,
+	type LoadedCdb,
+	loadCdb,
+	showDevice,
+} from "../devices.ts";
 import { CentrsError } from "../errors.ts";
 import type { McpWritePolicy } from "../mcp.ts";
 import { parseCommentKv } from "../resolver/comment-kv.ts";
@@ -52,30 +57,50 @@ export async function loadAllowlistCdb(
  * `cdb/target-not-registered` when no record matches — the friendly,
  * MCP-specific framing of "this device is not on the allowlist", pointing at
  * `centrs_devices add` rather than leaking the CLI's `cdb/not-found-target`.
+ *
+ * Matches with {@link showDevice}, the matcher the core resolver dials with
+ * (target, `identity=`, `mac=`, `ip=`), so the record whose write policy is
+ * checked here is the record the call then runs against (#444). A name that
+ * matches more than one record fails `identity/ambiguous` rather than taking
+ * the first.
  */
 export function resolveRegisteredTarget(
 	cdb: LoadedCdb,
 	target: string,
 ): RegisteredTarget {
-	for (let index = 0; index < cdb.entries.length; index += 1) {
-		const entry = cdb.entries[index];
-		if (entry && entry.target === target) {
-			return {
-				target,
-				user: entry.user,
-				group: entry.group,
-				recordIndex: index,
-				writePolicy: readWritePolicy(entry.comment),
-			};
+	let entry: DevicesShowItem;
+	try {
+		entry = showDevice({ cdb, target }).data.entry;
+	} catch (error) {
+		if (error instanceof CentrsError && error.code === "cdb/not-found-target") {
+			throw new CentrsError({
+				code: "cdb/target-not-registered",
+				summary: `Target "${target}" is not registered in the CDB allowlist.`,
+				remediation:
+					"Register the device first with the `centrs_devices` tool (op `add`) or `centrs devices add`, then retry. The MCP server only acts on CDB-registered targets, by target or by its `identity=`, `mac=` or `ip=` comment key.",
+				context: { target, cdbFile: cdb.settings.cdbFile.value },
+			});
+		}
+		// The CLI remediation names `--match`, which no MCP tool takes.
+		if (error instanceof CentrsError && error.code === "identity/ambiguous") {
+			throw new CentrsError({
+				code: error.code,
+				summary: error.summary,
+				remediation:
+					"Retry with one candidate's address from `context.matches[].target` as `target`. If the candidates share that address too, the CDB holds duplicate records for it: remove or edit the extra one with the `centrs_devices` tool (op `remove` or `set`).",
+				context: error.context,
+				cause: error,
+			});
 		}
+		throw error;
 	}
-	throw new CentrsError({
-		code: "cdb/target-not-registered",
-		summary: `Target "${target}" is not registered in the CDB allowlist.`,
-		remediation:
-			"Register the device first with the `centrs_devices` tool (op `add`) or `centrs devices add`, then retry. The MCP server only acts on CDB-registered targets.",
-		context: { target, cdbFile: cdb.settings.cdbFile.value },
-	});
+	return {
+		target: entry.target,
+		user: entry.user,
+		group: entry.group,
+		recordIndex: entry.cdbRecordIndex,
+		writePolicy: readWritePolicy(entry.comment),
+	};
 }
 
 /**

package/src/mcp/tools.ts

@@ -36,7 +36,7 @@ import {
 import type { CommentKvUpdate } from "../resolver/comment-kv.ts";
 import { parseBbox, parseNear } from "../resolver/geo.ts";
 import { parseDuration } from "../resolver/settings.ts";
-import { buildRetrieveErrorEnvelope, retrieve } from "../retrieve.ts";
+import { retrieveEnvelope } from "../retrieve.ts";
 import {
 	buildRetrieveFanoutErrorEnvelope,
 	retrieveGroup,
@@ -193,7 +193,7 @@ export const validateInputShape = {
 	target: z
 		.string()
 		.describe(
-			"CDB-registered target (name / IP / URL / MAC). Must be on the allowlist.",
+			"CDB-registered target: its address (IP / URL / MAC) or its identity=, mac= or ip= comment key. Must be on the allowlist.",
 		),
 	command: z.string().describe("RouterOS CLI command to dry-run."),
 	via: z
@@ -248,7 +248,9 @@ export const retrieveInputShape = {
 	target: z
 		.string()
 		.optional()
-		.describe("CDB-registered single target. Use either target or group."),
+		.describe(
+			"CDB-registered single target: its address (IP / URL / MAC) or its identity=, mac= or ip= comment key. Use either target or group.",
+		),
 	group: z
 		.string()
 		.optional()
@@ -264,11 +266,13 @@ export const retrieveInputShape = {
 		.boolean()
 		.optional()
 		.describe("Return every attribute instead of the default projection."),
-	filter: z.string().optional().describe("RouterOS-style filter expression."),
+	filter: z.string().optional().describe("Alias of `query`."),
 	query: z
-		.string()
+		.union([z.string(), z.array(z.string())])
 		.optional()
-		.describe("Raw query word(s) appended to the read."),
+		.describe(
+			"Row filter written as after `print where`, e.g. `type=ether and !disabled`; run on the router, several are AND-ed. No `~` (regex) or `in`.",
+		),
 	via: z.string().optional().describe("Override transport."),
 	timeout: z
 		.union([z.string(), z.number()])
@@ -324,18 +328,11 @@ export async function handleRetrieve(
 		cdbPassword: config.cdbPassword,
 	};
 
+	if (args.group === undefined) return await retrieveEnvelope(request);
 	try {
-		const envelope =
-			args.group !== undefined
-				? await retrieveGroup(request)
-				: await retrieve(request);
-		return envelope;
+		return await retrieveGroup(request);
 	} catch (error) {
-		const envelope =
-			args.group !== undefined
-				? buildRetrieveFanoutErrorEnvelope(request, error)
-				: buildRetrieveErrorEnvelope(request, error);
-		return envelope;
+		return buildRetrieveFanoutErrorEnvelope(request, error);
 	}
 }
 
@@ -345,7 +342,7 @@ export const executeInputShape = {
 	target: z
 		.string()
 		.describe(
-			"CDB-registered target. Inline host+credentials are not accepted.",
+			"CDB-registered target: its address (IP / URL / MAC) or its identity=, mac= or ip= comment key. Inline host+credentials are not accepted.",
 		),
 	command: z.string().describe("RouterOS CLI command to run."),
 	confirm: z