@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/src/core/menu-path.ts

@@ -0,0 +1,89 @@
+/**
+ * RouterOS menu-path grammar for the read surfaces (`retrieve`, `api`) and
+ * the REST URL guard every REST request passes through (#586).
+ *
+ * Every dir and command name in the RouterOS 7.9–7.26 command tree (rosetta
+ * v0.12.0, 579 dirs / 5370 commands) is letters, digits and hyphens,
+ * starting with a letter or digit (`/interface/6to4`); case folds. Anything else
+ * in a menu segment is not a menu, and some of it changes what the request
+ * addresses: in a REST URL, `#` and `?` turn the appended `/print` into a
+ * fragment or query, so `retrieve '/system/reboot#'` posted to
+ * `/rest/system/reboot` and rebooted the router (CHR 7.24.5).
+ */
+
+import { CentrsError } from "../errors.ts";
+import { pathTokens } from "./inspect.ts";
+
+const MENU_SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
+
+/** The menu segments of `path` that are not RouterOS menu or command names. */
+export function invalidMenuSegments(path: string): string[] {
+	// Case folds, as RouterOS menus do (`src/explain/menus.ts` isMenuPath);
+	// letter case cannot change how a URL parses, so it is not a hazard.
+	return pathTokens(path).filter(
+		(segment) => !MENU_SEGMENT.test(segment.toLowerCase()),
+	);
+}
+
+/**
+ * Reject a read-surface path whose segments are not RouterOS menu names.
+ * Runs before any network work and regardless of `--validate`: that flag
+ * skips command validation, not the guarantee that a read dispatches a read.
+ */
+export function assertRouterOsMenuPath(
+	path: string,
+	context: { readonly flag?: string; readonly endpoint?: string } = {},
+): void {
+	const invalid = invalidMenuSegments(path);
+	if (invalid.length === 0) {
+		return;
+	}
+	throw new CentrsError({
+		code: "input/invalid-routeros-path",
+		summary: `RouterOS path ${JSON.stringify(path)} has a segment that is not a menu name: ${invalid.map((segment) => JSON.stringify(segment)).join(", ")}.`,
+		remediation:
+			"Write the menu path with letters, digits and hyphens between slashes, such as `/ip/address` or `/system/resource`. Filter rows with `--query`, not characters in the path.",
+		context: { path, invalidSegments: invalid, ...context },
+	});
+}
+
+/**
+ * Characters and segments that make a WHATWG URL address something other
+ * than the path as written: `?` starts a query, `#` a fragment, `\` is read
+ * as `/`, tabs and newlines are stripped, and `.`/`..` segments collapse
+ * (also percent-encoded: `%2e%2e`, `.%2E`).
+ * RouterOS does not decode percent-escapes in REST paths (`reboot%23` is
+ * "no such command or directory" on CHR 7.24.5), so the rest is inert.
+ */
+function hasUrlStructuralCharacter(path: string): boolean {
+	for (const char of path) {
+		const code = char.charCodeAt(0);
+		if (char === "?" || char === "#" || char === "\\") return true;
+		if (code <= 0x1f || code === 0x7f) return true;
+	}
+	return false;
+}
+
+/** `.`/`..` and the percent-encoded forms WHATWG also collapses (`%2e%2e`, `.%2E`). */
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+
+/**
+ * Refuse a REST request path that the URL parser would rewrite. This is the
+ * backstop under every REST caller (retrieve, api, execute, transfer, explain)
+ * so an appended `/print` can never be cut off before dispatch.
+ */
+export function assertRestRequestPath(path: string): void {
+	const dotSegment = path
+		.split("/")
+		.some((segment) => DOT_SEGMENT.test(segment));
+	if (!hasUrlStructuralCharacter(path) && !dotSegment) {
+		return;
+	}
+	throw new CentrsError({
+		code: "input/invalid-routeros-path",
+		summary: `Refusing REST request path ${JSON.stringify(path)}: it contains characters the URL would reinterpret (?, #, \\, control characters, or a . / .. segment), so the request would not reach the path as written.`,
+		remediation:
+			"Remove the character from the path. Pass filters with `--query` and values as fields; names containing these characters can be selected with a query instead of the URL path.",
+		context: { path, via: "rest-api" },
+	});
+}

package/src/core/routeros-errors.ts

@@ -107,6 +107,31 @@ function cleanToken(token: string): string {
  * rules here; keep the most specific patterns above broader ones.
  */
 export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
+	{
+		code: "routeros/permission-denied",
+		description:
+			"RouterOS refused the command because the user's group lacks a policy it needs.",
+		// Grounded on CHR 7.25. REST answers HTTP 500 with this as `detail`:
+		// `not enough permissions (9)` for a write without `write`, and
+		// `std failure: not allowed (9)` for any request (even a GET) when the
+		// group has `rest-api` but not `api` (fixed in 7.26beta3). The native API traps with the
+		// first string; `/execute as-string` returns it as text with a
+		// `(<path>; line N)` suffix. In a multi-statement script the refusal is
+		// the last line, after earlier statements' stdout (#549: `:put
+		// "p5-first"; /system/identity/set …` as a read-only user returns HTTP
+		// 200 with ret `p5-first\r\nnot enough permissions (9)
+		// (/system/identity/set; line 1)`, identical on native-api), so the
+		// trailed form matches too — with the location suffix required, so a
+		// script that merely prints the bare phrase stays ordinary output.
+		test: /not enough permissions|not allowed \(9\)/i,
+		resultTest:
+			/^(?:not enough permissions \(9\)(?: \(\/[^\s();]+; line \d+\))?|[\s\S]*\r?\nnot enough permissions \(9\) \(\/[^\s();]+; line \d+\))$/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS refused the command for lack of permission: ${raw.trim()}`,
+			remediation:
+				"Grant the missing policy to the RouterOS user's group (`/user/group`): `read` for reads, `write` for changes. If every REST request fails with `not allowed (9)`, the group has `rest-api` without `api`; before RouterOS 7.26beta3, REST needs both. Retrying will not help.",
+		}),
+	},
 	{
 		code: "routeros/unknown-path",
 		description:

package/src/devices.ts

@@ -19,6 +19,7 @@ import {
 	decryptWinBoxCdb,
 	type EncryptedWinBoxCdbFile,
 	encodeOpenWinBoxCdb,
+	encryptWinBoxCdb,
 	parseWinBoxCdb,
 	type WinBoxCdbEntry,
 	type WinBoxCdbField,
@@ -112,6 +113,7 @@ export interface DevicesGroupSummary {
 
 export type DevicesCommand =
 	| "init"
+	| "encrypt"
 	| "list"
 	| "show"
 	| "groups"
@@ -165,7 +167,7 @@ export interface LoadedCdb {
 	entries: readonly WinBoxCdbEntry[];
 	settings: DevicesSettings;
 	warnings: readonly DevicesWarning[];
-	/** True when the source file on disk was encrypted (writes are blocked). */
+	/** True when the source file on disk was encrypted. */
 	encrypted: boolean;
 }
 
@@ -232,7 +234,7 @@ function isAlreadyExistsError(cause: unknown): boolean {
 }
 
 /**
- * Create an empty open CDB at `path` without clobbering an existing file.
+ * Create an empty CDB at `path` without clobbering an existing file.
  * The bytes are written to a private temp file first and then hard-linked
  * into place: `link` fails with EEXIST instead of replacing, and `path` never
  * exists half-written, so a concurrent creator that loses the race reads a
@@ -242,14 +244,20 @@ function isAlreadyExistsError(cause: unknown): boolean {
  * file. Mode `0o600` keeps the CDB (device credentials) unreadable by other
  * local users instead of falling back to the process umask default.
  */
-async function createEmptyCdbNoClobber(path: string): Promise<boolean> {
+async function createEmptyCdbNoClobber(
+	path: string,
+	password?: string,
+): Promise<boolean> {
 	await mkdir(dirname(path), { recursive: true });
 	const tempPath = `${path}.init.${randomUUID()}`;
 	const handle = await open(tempPath, "wx", 0o600);
 	try {
 		try {
 			await handle.chmod(0o600);
-			await handle.write(encodeOpenWinBoxCdb([]));
+			const bytes = encodeOpenWinBoxCdb([]);
+			await handle.write(
+				password === undefined ? bytes : encryptWinBoxCdb(bytes, password),
+			);
 			await handle.sync();
 		} finally {
 			await handle.close();
@@ -270,11 +278,19 @@ export interface DevicesInitData {
 	cdbFile: string;
 	/** False when a readable CDB was already there; nothing was written. */
 	created: boolean;
+	/** Actual mode of the newly created or verified existing CDB. */
+	encrypted: boolean;
 	recordCount: number;
 }
 
+export interface InitCdbOptions extends LoadCdbOptions {
+	/** Require encryption; an existing open CDB is refused, never converted. */
+	encrypt?: boolean;
+}
+
 /**
- * `devices init` (#376): create an empty open CDB at the resolved path, the
+ * `devices init`: create an empty CDB (open by default, encrypted with
+ * `encrypt: true`) at the resolved path, the
  * explicit counterpart of the default path's first-run auto-create. Never
  * clobbers: like `git init`, re-running on an existing, readable CDB succeeds
  * with a `cdb/file-exists` warning and writes nothing, so a workspace bootstrap
@@ -282,15 +298,29 @@ export interface DevicesInitData {
  * (not a CDB, or encrypted without a password) fails with the load error.
  */
 export async function initCdb(
-	options: LoadCdbOptions,
+	options: InitCdbOptions,
 ): Promise<CentrsSuccessEnvelope<DevicesInitData, DevicesOperationMeta>> {
 	const settings = resolveDevicesSettings(options);
 	const cdbFile = settings.cdbFile.value;
+	if (options.encrypt) requireEncryptionPassword(settings);
 	const existingResult = async () => {
 		const existing = await loadCdb(options);
+		if (options.encrypt && !existing.encrypted) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `An open CDB already exists at ${cdbFile}; encrypted initialization wrote nothing.`,
+				remediation: `Run \`centrs devices encrypt --cdb-file ${cdbFile}\` to convert the existing CDB explicitly.`,
+				context: { cdbFile },
+			});
+		}
 		return {
 			ok: true as const,
-			data: { cdbFile, created: false, recordCount: existing.entries.length },
+			data: {
+				cdbFile,
+				created: false,
+				encrypted: existing.encrypted,
+				recordCount: existing.entries.length,
+			},
 			warnings: [
 				...existing.warnings,
 				{
@@ -310,7 +340,10 @@ export async function initCdb(
 	}
 	let created: boolean;
 	try {
-		created = await createEmptyCdbNoClobber(cdbFile);
+		created = await createEmptyCdbNoClobber(
+			cdbFile,
+			options.encrypt ? settings.cdbPassword.value : undefined,
+		);
 	} catch (cause) {
 		throw new CentrsError({
 			code: "cdb/create-failed",
@@ -326,13 +359,113 @@ export async function initCdb(
 	}
 	return {
 		ok: true,
-		data: { cdbFile, created: true, recordCount: 0 },
+		data: {
+			cdbFile,
+			created: true,
+			encrypted: options.encrypt === true,
+			recordCount: 0,
+		},
 		warnings: [],
 		tips: [],
 		meta: devicesMeta("init", settings),
 	};
 }
 
+function requireEncryptionPassword(settings: DevicesSettings): void {
+	if (
+		!settings.cdbPassword.provided ||
+		settings.cdbPassword.value.length === 0
+	) {
+		throw new CentrsError({
+			code: "cdb/password-required",
+			summary: "CDB encryption requires a non-empty password.",
+			remediation:
+				"Pass --cdb-password or set CENTRS_CDB_PASSWORD to a non-empty CDB password.",
+		});
+	}
+}
+
+export interface EncryptCdbOptions extends LoadCdbOptions {
+	/**
+	 * Skip the plaintext pre-conversion snapshot. Existing backups are still
+	 * retained untouched; without the snapshot a forgotten password is final.
+	 */
+	skipBackup?: boolean;
+}
+
+export interface DevicesEncryptData {
+	cdbFile: string;
+	encrypted: true;
+	/** False when the CDB was already encrypted and the password verified. */
+	changed: boolean;
+	recordCount: number;
+	/** Plaintext pre-conversion snapshot; absent when unchanged or `skipBackup`. */
+	backupPath?: string;
+}
+
+/**
+ * Explicitly convert an existing open CDB with a fresh salt and atomic replacement.
+ * Retain all backups: converting the active file does not protect old plaintext.
+ * Close WinBox and other writers first; this is not a cross-process transaction (#581).
+ * Already-encrypted files are verified with the supplied password and left untouched.
+ * `skipBackup` omits the new plaintext snapshot; it never deletes older backups.
+ */
+export async function encryptCdb(
+	options: EncryptCdbOptions,
+): Promise<CentrsSuccessEnvelope<DevicesEncryptData, DevicesOperationMeta>> {
+	const settings = resolveDevicesSettings(options);
+	requireEncryptionPassword(settings);
+	const cdbFile = settings.cdbFile.value;
+	// Pin even the default path so conversion never implicitly creates a file.
+	const cdb = await loadCdb({ ...options, cdbFile });
+	let backupPath: string | undefined;
+	if (!cdb.encrypted) {
+		try {
+			const written = await writeWinBoxCdb(
+				cdbFile,
+				cdb.entries.map((entry) => entry.record),
+				{
+					encryptWith: { password: settings.cdbPassword.value },
+					backupRetention: -1,
+					skipBackup: options.skipBackup === true,
+				},
+			);
+			backupPath = written.backupPath;
+		} catch (cause) {
+			throw new CentrsError({
+				code: "cdb/encrypt-failed",
+				summary: `Could not encrypt the CDB at ${cdbFile}.`,
+				remediation:
+					"Check directory permissions and available disk space; retain the original and any backups before retrying.",
+				context: { cdbFile },
+				cause,
+			});
+		}
+	}
+	return {
+		ok: true,
+		data: {
+			cdbFile,
+			encrypted: true,
+			changed: !cdb.encrypted,
+			recordCount: cdb.entries.length,
+			...(backupPath ? { backupPath } : {}),
+		},
+		warnings: [
+			...cdb.warnings.filter(
+				(warning) => warning.code !== "cdb/password-not-needed",
+			),
+			{
+				code: "cdb/plaintext-backups",
+				message:
+					"Backups may contain plaintext credentials. Encryption protects only the active CDB; no backups were deleted or encrypted.",
+			},
+		],
+		tips: [],
+		meta: devicesMeta("encrypt", settings),
+	};
+}
+
 export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 	const settings = resolveDevicesSettings(options);
 	const warnings: DevicesWarning[] = [];
@@ -1859,6 +1992,18 @@ function renderText(envelope: DevicesEnvelope<unknown>): string {
 					? `created ${data.cdbFile}`
 					: `exists ${data.cdbFile} (${data.recordCount} record(s))`,
 			);
+			lines.push(`encrypted:     ${data.encrypted}`);
+			break;
+		}
+		case "encrypt": {
+			const data = envelope.data as DevicesEncryptData;
+			lines.push(
+				data.changed
+					? `encrypted ${data.cdbFile}`
+					: `verified encrypted ${data.cdbFile} (unchanged)`,
+			);
+			lines.push(`records:       ${data.recordCount}`);
+			if (data.backupPath) lines.push(`backup:        ${data.backupPath}`);
 			break;
 		}
 		case "list":

package/src/execute-cmr.ts

@@ -1002,8 +1002,7 @@ function devicePassed(
 		source: CMR_VALIDATION_SOURCE,
 		result: "passed",
 		syntax: true,
-		semantic:
-			resolved.canonical.mode === "structured" ? true : "not-applicable",
+		...(resolved.canonical.mode === "structured" ? { semantic: true } : {}),
 		stages: passedStages(
 			offline ?? { verdict: "pass", warnings: [] },
 			CMR_VALIDATION_SOURCE,
@@ -1023,12 +1022,7 @@ function deviceRejected(
 		enabled: true,
 		source: CMR_VALIDATION_SOURCE,
 		result: "failed",
-		...(nameRejected
-			? { syntax: true, semantic: false }
-			: {
-					syntax: false,
-					...(structured ? {} : { semantic: "not-applicable" as const }),
-				}),
+		...(nameRejected ? { syntax: true, semantic: false } : { syntax: false }),
 		stages: [
 			offlineStagePassed(offline?.verdict),
 			{ stage: "device", source: CMR_VALIDATION_SOURCE, result: "failed" },

package/src/execute-fanout.ts

@@ -60,6 +60,7 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -206,6 +207,7 @@ export async function executeFanout(
 	internals: ExecuteFanoutInternals = {},
 	options: ExecuteFanoutOptions = {},
 ): Promise<ExecuteFanoutEnvelope> {
+	assertNoMatchInFanout(request.match);
 	// Validate + canonicalize the command ONCE, before selection expansion: a bad
 	// command shape is an outer error regardless of how many targets resolve, and
 	// write-ness is target-independent.

package/src/execute.ts

@@ -27,6 +27,7 @@ import { buildTip, notReachedReason } from "./core/envelope.ts";
 import {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
+	isBareMenuPathCommand,
 	isWriteShaped,
 } from "./core/execute-command.ts";
 import { sentWriteWarnings } from "./core/fanout.ts";
@@ -40,6 +41,7 @@ import {
 	SYNTAX_REJECTED_REMEDIATION,
 	serializeCentrsError,
 } from "./errors.ts";
+import { countExecutableStatements } from "./explain/segment.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -118,6 +120,12 @@ export interface ExecuteRequest {
 	maxResultsBytes?: number;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** Opt-in host ARP resolution for a MAC target (`none` default, or `arp`). */
 	resolve?: string;
 	stdinIsTty?: boolean;
@@ -162,6 +170,7 @@ export type ExecuteErrorEnvelope = CentrsErrorEnvelope<ExecuteOperationMeta>;
 export {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
+	isBareMenuPathCommand,
 	isWriteShaped,
 };
 
@@ -364,6 +373,7 @@ export async function resolveExecuteRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
@@ -608,6 +618,22 @@ export function buildExecuteErrorEnvelope(
 	};
 }
 
+/**
+ * Whether the dispatch carried more than one statement (#549). Mirrors
+ * `runCommand`: the consoles run the raw CLI text whatever the canonical mode,
+ * while REST/native run structured input as one path-POST/talk sentence — a
+ * `;` inside a structured value never separates there, so the refusal means
+ * nothing ran. Executed control scopes count too: `:if … do={ A; B }` applies
+ * A before a refused B, while stored bodies never run at dispatch.
+ */
+function isMultiStatementDispatch(resolved: ResolvedExecuteRequest): boolean {
+	const runsRawText =
+		resolved.via.value === "mac-telnet" ||
+		resolved.via.value === "ssh" ||
+		resolved.canonical.mode === "script";
+	return runsRawText && countExecutableStatements(resolved.command) > 1;
+}
+
 export function buildExecuteErrorEnvelopeFromResolved(
 	resolved: ResolvedExecuteRequest,
 	error: unknown,
@@ -633,6 +659,7 @@ export function buildExecuteErrorEnvelopeFromResolved(
 				isWriteShaped(resolved.canonical),
 				centrsError,
 				trace,
+				isMultiStatementDispatch(resolved),
 			),
 		],
 		tips: resolvedExecuteTips(resolved),
@@ -664,20 +691,15 @@ function failedValidationMeta(
 	}
 	const deviceSource = deviceStageSource(resolved);
 	const structured = resolved.canonical.mode === "structured";
-	// A flat summary is present only when its check gave a verdict (GH#435).
-	// Script-shaped input has no semantic half at all: `not-applicable`. For
-	// structured input, a syntax rejection means the name-level check was
-	// never asked, so `semantic` is left out rather than reported `false`.
-	const semanticNotReached = structured
-		? {}
-		: { semantic: "not-applicable" as const };
+	// A flat summary is present only when a stage gave that verdict (#535). A
+	// syntax rejection means the name-level check was never asked, so
+	// `semantic` is left out rather than reported `false`.
 	if (isOfflineGateRejection(error)) {
 		return {
 			enabled: true,
 			source: OFFLINE_GATE_SOURCE,
 			result: "failed",
 			syntax: false,
-			...semanticNotReached,
 			stages: [
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
@@ -705,9 +727,7 @@ function failedValidationMeta(
 			enabled: true,
 			source: deviceSource,
 			result: "failed",
-			...(nameRejected
-				? { syntax: true, semantic: false }
-				: { syntax: false, ...semanticNotReached }),
+			...(nameRejected ? { syntax: true, semantic: false } : { syntax: false }),
 			stages: [
 				offlineStagePassed(trace?.offlineVerdict),
 				{ stage: "device", source: deviceSource, result: "failed" },
@@ -781,15 +801,14 @@ export function offlineStagePassed(
  * `validate=false`. Both stages are listed as `skipped` rather than omitted:
  * the constitution's rule is that a gated surface always reports each stage, so
  * a consumer reading `stages` never has to special-case the disabled shape.
- * `reason` is left off — `enabled: false` already says why.
+ * `reason` is left off — `enabled: false` already says why. No stage answered,
+ * so there is no `syntax` / `semantic` summary (#535).
  */
 export function disabledValidationMeta(): EnvelopeValidationMeta {
 	return {
 		enabled: false,
 		source: "disabled",
 		result: "skipped",
-		syntax: false,
-		semantic: false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
 			{ stage: "device", source: "device preflight", result: "skipped" },
@@ -862,7 +881,6 @@ async function validateExecuteCommand(
 			source: ":put [:parse]",
 			result: "passed",
 			syntax: true,
-			semantic: "not-applicable",
 			stages: passedStages(offline, ":put [:parse]"),
 		};
 	}
@@ -929,8 +947,7 @@ async function validateConsoleParseCommand(
 		source: `:put [:parse ...] over ${resolved.via.value}`,
 		result: "passed",
 		syntax: true,
-		semantic:
-			resolved.canonical.mode === "structured" ? true : "not-applicable",
+		...(resolved.canonical.mode === "structured" ? { semantic: true } : {}),
 		stages: passedStages(
 			offline,
 			`:put [:parse ...] over ${resolved.via.value}`,
@@ -1452,20 +1469,38 @@ function executeRequestSummary(
  * downstream auth error.
  */
 export function resolvedExecuteTips(resolved: ResolvedExecuteRequest): Tip[] {
+	const tips: Tip[] = [];
 	if (
 		resolved.via.value === "mac-telnet" &&
 		resolved.auth.username === undefined &&
 		!resolved.auth.passwordProvided
 	) {
-		return [
+		tips.push(
 			buildTip(
 				"tip/mac-telnet-no-credentials",
 				"No username or password was resolved for this mac-telnet target.",
 				"mac-telnet logs in with RouterOS credentials over MTWEI (MD5 is refused): pass --username/--password, set CENTRS_USERNAME/CENTRS_PASSWORD, or add a CDB record for this device.",
 			),
-		];
+		);
+	}
+	// A bare menu path runs — the write gate no longer stops it — but it
+	// answers nothing: consoles navigate silently and the APIs refuse it with
+	// `no such command`. Name the read that does answer. `canonical` is
+	// always resolved in production; the guard keeps hermetic stubs total.
+	if (
+		resolved.canonical !== undefined &&
+		isBareMenuPathCommand(resolved.canonical)
+	) {
+		const menu = `${resolved.canonical.path}/${resolved.canonical.verb}`;
+		tips.push(
+			buildTip(
+				"tip/execute-bare-menu-path",
+				`"${menu}" is a menu path, not a command: consoles navigate to it (no output) and the APIs refuse it with "no such command".`,
+				`Append a verb such as "${menu}/print", or read rows with "centrs retrieve <router> ${menu}".`,
+			),
+		);
 	}
-	return [];
+	return tips;
 }
 
 function dataFromResult(result: ProtocolExecuteResult): unknown {