@tikoci/centrs 0.1.8-next.0 → 0.1.8

package/CHANGELOG.md

@@ -8,6 +8,27 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.8 — 2026-10-12
+
+Release (npm tag `latest`; `next` moves forward to 0.1.8). Everything in
+0.1.8-next.0 below, plus two fixes from field-testing it.
+
+### Fixed
+
+- `retrieve --wait` with no deadline value names `--wait` (#445). Written as a
+  bare switch, `--wait --until 'expr'` read `--until` as the deadline and
+  shifted the predicate into a second target, so the CLI reported
+  `usage/fanout-not-supported`. It now fails `settings/invalid-timeout`
+  ("Received the flag: --until"), and every deadline without a unit gets the
+  `--wait`-specific message. A real multi-target `--wait` still gets the
+  fanout refusal.
+- MCP accepts a registered device by its `identity=`, `mac=` or `ip=` comment
+  key, as the CLI does (#444). The allowlist gate now matches with the same
+  resolver the call dials with, so the `mcp=` write policy checked is the
+  policy of the record the call runs against. A name on more than one record
+  fails `identity/ambiguous` with the candidates in `context.matches` and an
+  MCP remediation, instead of resolving to the first.
+
 ## 0.1.8-next.0 — 2026-10-12
 
 Pre-release (npm tag `next`; `latest` stays on 0.1.7). Install with

package/commands/mcp/README.md

@@ -149,7 +149,11 @@ The authorization boundary is the WinBox CDB (constitution: identity and CDB),
 which is already centrs's device registry **and** native credential store. The
 MCP server applies it as a hard allowlist:
 
-- **Targets resolve through the CDB only** — by name, MAC, or `group`. Inline
+- **Targets resolve through the CDB only** — by record target, by the
+  `identity=`/`mac=`/`ip=` comment keys (the same matcher the CLI dials with, so
+  the write policy checked belongs to the record the call runs against), or by
+  `group`. A name on
+  more than one record fails `identity/ambiguous` rather than picking one. Inline
   ad-hoc `host` + `username` + `password` are **rejected by default** with
   `cdb/target-not-registered`, whose `fix` points at `centrs_devices add`. An
   agent therefore cannot reach an arbitrary router with arbitrary credentials.

package/commands/mcp/examples.md

@@ -37,10 +37,27 @@ Envelope: `ok: true`, `data.path = "/ip/route"`, `data.verb = "add"`,
 
 Envelope: `ok: false`, `error.code = "cdb/target-not-registered"`, and
 `error.fix`/`remediation` names `centrs_devices add`. No connection is attempted.
-RouterOS-facing MCP tools accept only a CDB `target` (name/MAC/URL) — there is
+RouterOS-facing MCP tools accept only a CDB-registered `target` — the record's
+address (IP/URL/MAC) or its `identity=`/`mac=`/`ip=` comment key — and there is
 no inline `host`/`username`/`password` executor parameter, so RouterOS actions
 use credentials already stored in the CDB.
 
+### 2b. A record's `identity=` name passes the allowlist
+
+The harness registers `$NAME` with the comment `identity=mcp-lab mcp=rw
+via=rest-api`.
+
+```json
+{ "name": "centrs_retrieve",
+  "arguments": { "target": "mcp-lab", "path": "/system/resource" } }
+```
+
+Envelope: `ok: true`, and `meta.target` names the record the call dialed:
+`identity = "mcp-lab"`, `recordIndex = 0`, and `baseUrl` is `$NAME`'s REST URL.
+The allowlist gate and the dialing resolver use the same matcher, so a name on
+more than one record fails `identity/ambiguous` instead of picking one (asserted
+offline in `test/unit/mcp-safety.test.ts`; the CHR test registers one record).
+
 ### 3. `centrs_validate` accepts the bare `blackhole` flag
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.8-next.0",
+	"version": "0.1.8",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {

package/src/cli/retrieve.ts

@@ -28,6 +28,7 @@ import {
 	retrieveSample,
 	retrieveWait,
 	type ValidationTrace,
+	validateRetrieveRequestShape,
 } from "../index.ts";
 import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
@@ -245,6 +246,12 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 						? "--follow"
 						: "--sample";
 			if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+				// A value-less `--wait` swallows the next flag and shifts a
+				// positional into a second target, so report a flag-value error
+				// before the fanout refusal names the wrong mistake (#445). Only
+				// here: single-target streams report shape errors as their own
+				// stdout envelope.
+				validateRetrieveRequestShape(request);
 				throw new CentrsError({
 					code: "usage/fanout-not-supported",
 					summary: `\`retrieve ${mode}\` watches one router and cannot fan out across multiple targets.`,

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

@@ -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()
@@ -340,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

package/src/retrieve.ts

@@ -874,6 +874,9 @@ export function applyMaxResultsBudget(
 export function validateRetrieveRequestShape(
 	request: RetrieveRequest,
 ): readonly string[] {
+	// Flag values before the path: a value-less flag shifts the positionals,
+	// so the path check would blame the wrong token (#445).
+	resolveWaitSettings(request);
 	if (!request.path.startsWith("/")) {
 		throw new CentrsError({
 			code: "input/invalid-routeros-path",
@@ -885,7 +888,6 @@ export function validateRetrieveRequestShape(
 	}
 
 	const query = resolveRetrieveQuery(request);
-	resolveWaitSettings(request);
 	if (query && request.listAttributes) {
 		throw new CentrsError({
 			code: "usage/conflicting-flags",
@@ -1027,13 +1029,16 @@ function resolveWaitSettings(
 	// A unit is required for the same reason as `--sample`: a bare `30` would
 	// be a 30 ms deadline, which expires before validation completes.
 	const text = String(request.wait).trim();
-	const deadlineMs = /^\d+$/.test(text) ? -1 : parseDuration(text);
+	const deadlineMs = /^\d+(ms|s|m)$/i.test(text) ? parseDuration(text) : -1;
 	if (deadlineMs <= 0)
 		throw new CentrsError({
 			code: "settings/invalid-timeout",
-			summary: `\`--wait\` needs a positive deadline with a unit. Received: ${text}`,
+			// `--wait --until …` reads `--until` as the deadline (#445).
+			summary: text.startsWith("-")
+				? `\`--wait\` needs a deadline value before the next flag. Received the flag: ${text}`
+				: `\`--wait\` needs a positive deadline with a unit. Received: ${text}`,
 			remediation:
-				"Pass an overall duration such as `--wait 30s` or `--wait 5m`.",
+				"Pass an overall duration such as `--wait 30s` or `--wait 5m`, e.g. `--wait 20s --until 'running'`.",
 			context: { flag: "--wait", value: text },
 		});
 	return {