@tikoci/centrs 0.1.7 → 0.1.8-next.0

package/src/protocols/adapter.ts

@@ -16,6 +16,7 @@
 
 import { mapRouterOsError } from "../core/routeros-errors.ts";
 import { CentrsError } from "../errors.ts";
+import { formatEndpoint } from "./endpoint.ts";
 import type { RouterOsProtocol } from "./index.ts";
 import {
 	createUdpMacTelnetTransport,
@@ -28,6 +29,7 @@ import {
 import { MacTelnetConsole } from "./mac-telnet-console.ts";
 import {
 	type ApiReply,
+	byteStringBytes,
 	connectNativeApi,
 	type NativeApiCommand,
 	type NativeApiSession,
@@ -52,6 +54,8 @@ export interface ProtocolAdapterConfig {
 	password: string;
 	/** Per-command timeout in milliseconds. */
 	timeoutMs: number;
+	/** Abandon every operation, including validation and native connection/login. */
+	signal?: AbortSignal;
 	/** Target device MAC, for L2 transports (mac-telnet). */
 	mac?: string;
 	/** Client (in-packet source) MAC for mac-telnet; a synthetic one is used when omitted. */
@@ -67,9 +71,20 @@ export interface ProtocolAdapterConfig {
 }
 
 /** Projection/detail options for a menu `list`. */
-export interface RetrieveListOptions {
+export interface RetrieveListOptions extends RetrieveReadOptions {
 	proplist?: readonly string[];
 	detail?: boolean;
+	/** Row filter in REST `.query` form (no leading `?`); native prefixes each with `?`. */
+	query?: readonly string[];
+}
+
+/** Options every retrieve read takes. */
+export interface RetrieveReadOptions {
+	/**
+	 * Abandon the read: REST aborts the HTTP request at once. Native reads
+	 * share the session, so they end when the adapter is closed.
+	 */
+	signal?: AbortSignal;
 }
 
 /** What an adapter can do. Lets callers pick a transport per capability. */
@@ -96,6 +111,14 @@ export interface ProtocolExecuteRequest {
 	queries?: readonly string[];
 	/** Raw CLI line for the `/rest/execute` script fallback. */
 	script?: string;
+	/**
+	 * Attribute values and reply strings are byte strings, one code unit per
+	 * byte (0–255), instead of UTF-8 text. RouterOS carries `/file` contents
+	 * as raw bytes on both wires, so this is how `transfer` moves arbitrary
+	 * bytes (#404); a non-ASCII value such as a file name must be passed as its
+	 * UTF-8 byte string. Honored by REST and native-api; not with `script`.
+	 */
+	binary?: boolean;
 }
 
 /** Result of an `execute` round-trip. */
@@ -134,6 +157,21 @@ export interface ProtocolApiRequest {
 	proplist?: readonly string[];
 	/** Raw console line for the `/execute` script form (`run`); when set, `path`/`attributes` are ignored. */
 	script?: string;
+	/** `print` only: send the menu's `listen` command instead (the literal `<menu>/listen` endpoint). */
+	listen?: boolean;
+}
+
+/**
+ * One reply of an incremental native command, as RouterOS sent it: an `!re`
+ * row, or an `!empty` (zero rows: an empty finite read, a zero-row
+ * `print interval=` tick, or a listen cancelled before it sent anything).
+ */
+export interface ProtocolStreamReply {
+	type: "re" | "empty";
+	/** The row's attributes; always `{}` for `!empty`. */
+	attributes: Record<string, string>;
+	/** The reply arrived after `options.signal` aborted (see `ApiReply.afterStop`). */
+	afterStop?: true;
 }
 
 /** Result of an `apiRequest` round-trip: the response body shaped for the envelope. */
@@ -142,7 +180,7 @@ export interface ProtocolApiResult {
 	data: unknown;
 }
 
-/** Options for an open-ended `listen` follow. */
+/** Options for incremental native command replies. */
 export interface ProtocolListenOptions {
 	/** Abort the listen (sends `/cancel`); the generator then ends cleanly. */
 	signal?: AbortSignal;
@@ -160,6 +198,21 @@ export interface ProtocolListenOptions {
 	cancelGraceMs?: number;
 	/** Fired when that wait expires without the router's acknowledgement. */
 	onCancelUnacknowledged?: () => void;
+	/** Attributes carried by the command's terminal `!done`, not a row frame. */
+	onDone?: (attributes: Record<string, string>) => void;
+	/**
+	 * Every reply (`re`, `empty`, `trap`, `done`), called synchronously in wire
+	 * order as it arrives, before the generator yields it. Concurrent streams
+	 * on one connection can be ordered against each other only this way; the
+	 * generators' own interleaving depends on microtask scheduling.
+	 */
+	onReply?: (reply: ProtocolTappedReply) => void;
+}
+
+/** A reply seen by {@link ProtocolListenOptions.onReply}. */
+export interface ProtocolTappedReply {
+	type: "re" | "empty" | "trap" | "done";
+	attributes: Record<string, string>;
 }
 
 /**
@@ -173,9 +226,14 @@ export interface ProtocolAdapter {
 	/** Capability flags describing what this adapter supports. */
 	readonly capabilities: ProtocolAdapterCapabilities;
 	/** `/console/inspect` probe (`request=child` or `request=completion`). */
-	inspect(request: "child" | "completion", path: string): Promise<unknown[]>;
+	/** `/console/inspect`; `input` is the CLI-text form (`request=completion input=…`). */
+	inspect(
+		request: "child" | "completion",
+		path: string,
+		input?: string,
+	): Promise<unknown[]>;
 	/** Read a single record (singleton menu) as an object. */
-	getSingleton(path: string): Promise<unknown>;
+	getSingleton(path: string, options?: RetrieveReadOptions): Promise<unknown>;
 	/** Read a menu as an array of records, optionally projected/detailed. */
 	list(path: string, options: RetrieveListOptions): Promise<unknown[]>;
 	/** Run a CLI-shaped command (WP-1c write surface). */
@@ -183,15 +241,16 @@ export interface ProtocolAdapter {
 	/** Run a normalized structured `api` request (the gh-api passthrough surface). */
 	apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult>;
 	/**
-	 * Open-ended `/listen` follow (native-api only). Yields one rest-style change
-	 * record per `!re` frame (deletions carry `.dead`), until cancelled via
-	 * `options.signal` or the consumer stopping. REST and console transports
-	 * reject with `transport/capability-unsupported`.
+	 * Incremental native replies to the literal command (the same mapping as
+	 * `apiRequest`; never rewritten into a `listen`). Yields each `!re` and
+	 * `!empty` as it arrives, until natural completion, cancellation, or
+	 * failure. REST and console transports reject with
+	 * `transport/capability-unsupported`.
 	 */
-	listen(
+	stream(
 		request: ProtocolApiRequest,
 		options: ProtocolListenOptions,
-	): AsyncIterable<Record<string, unknown>>;
+	): AsyncIterable<ProtocolStreamReply>;
 	/** Release any underlying connection. Safe to call when never connected. */
 	close(): Promise<void>;
 }
@@ -236,28 +295,48 @@ class RestAdapter implements ProtocolAdapter {
 	async inspect(
 		request: "child" | "completion",
 		path: string,
+		input?: string,
 	): Promise<unknown[]> {
-		return this.restPost<unknown[]>("/console/inspect", { request, path });
+		return this.restPost<unknown[]>(
+			"/console/inspect",
+			input === undefined ? { request, path } : { request, input },
+		);
 	}
 
-	async getSingleton(path: string): Promise<unknown> {
-		return this.restGet(path);
+	async getSingleton(
+		path: string,
+		options: RetrieveReadOptions = {},
+	): Promise<unknown> {
+		return this.restGet(path, options.signal);
 	}
 
 	async list(path: string, options: RetrieveListOptions): Promise<unknown[]> {
-		const hasProjection =
-			(options.proplist?.length ?? 0) > 0 || options.detail === true;
-		if (!hasProjection) {
-			return (await this.restGet(path)) as unknown[];
+		const hasBody =
+			(options.proplist?.length ?? 0) > 0 ||
+			(options.query?.length ?? 0) > 0 ||
+			options.detail === true;
+		if (!hasBody) {
+			return (await this.restGet(path, options.signal)) as unknown[];
 		}
-		const body: { ".proplist"?: readonly string[]; detail?: string } = {};
+		const body: {
+			".proplist"?: readonly string[];
+			".query"?: readonly string[];
+			detail?: string;
+		} = {};
 		if (options.proplist && options.proplist.length > 0) {
 			body[".proplist"] = options.proplist;
 		}
+		if (options.query && options.query.length > 0) {
+			body[".query"] = options.query;
+		}
 		if (options.detail) {
 			body.detail = "true";
 		}
-		return this.restPost<unknown[]>(`${path.replace(/\/$/, "")}/print`, body);
+		return this.restPost<unknown[]>(
+			`${path.replace(/\/$/, "")}/print`,
+			body,
+			options.signal,
+		);
 	}
 
 	async execute(
@@ -271,6 +350,21 @@ class RestAdapter implements ProtocolAdapter {
 			return normalizeRestExecute(data);
 		}
 		const target = `${request.path.replace(/\/$/, "")}/${request.command}`;
+		if (request.binary) {
+			// RouterOS stores the UTF-8 encoding of each JSON code point, so a
+			// `\u0080` escape lands as `c2 80`; only raw bytes in the body are
+			// exact. Replies carry 0x80–0xff unescaped too (CHR, #404).
+			const response = await this.fetchRest(
+				target,
+				{
+					method: "POST",
+					body: byteStringBytes(JSON.stringify(request.attributes ?? {})),
+					headers: { "Content-Type": "application/json" },
+				},
+				true,
+			);
+			return normalizeRestExecute(response.data);
+		}
 		const data = await this.restPost<unknown>(target, request.attributes ?? {});
 		return normalizeRestExecute(data);
 	}
@@ -333,7 +427,10 @@ class RestAdapter implements ProtocolAdapter {
 					return { data: result.ret ?? result.records };
 				}
 				return {
-					data: await this.requestRest("POST", base, request.attributes ?? {}),
+					data: await this.requestRest("POST", base, {
+						...request.attributes,
+						...restQueryBody(request),
+					}),
 				};
 			}
 			default:
@@ -341,15 +438,15 @@ class RestAdapter implements ProtocolAdapter {
 		}
 	}
 
-	// REST cannot hold an open-ended follow (the 60s cap); listen is native-only.
+	// REST cannot hold an open-ended follow (the 60s cap); streaming is native-only.
 	// biome-ignore lint/correctness/useYield: a throw-only async generator yields nothing.
-	async *listen(): AsyncGenerator<Record<string, unknown>> {
+	async *stream(): AsyncGenerator<ProtocolStreamReply> {
 		throw new CentrsError({
 			code: "transport/capability-unsupported",
 			summary: "REST cannot follow an open-ended `--stream` (60s cap).",
 			remediation:
 				"Open-ended follow is native-api only: use `--via native-api`, or drop `--stream` for a bounded one-shot.",
-			context: { protocol: this.protocol, capability: "listen" },
+			context: { protocol: this.protocol, capability: "stream" },
 		});
 	}
 
@@ -374,19 +471,21 @@ class RestAdapter implements ProtocolAdapter {
 		return response.data;
 	}
 
-	private async restGet(path: string): Promise<unknown> {
-		const response = await this.fetchRest(path, { method: "GET" });
+	private async restGet(path: string, signal?: AbortSignal): Promise<unknown> {
+		const response = await this.fetchRest(path, { method: "GET", signal });
 		return response.data;
 	}
 
 	private async restPost<T = unknown>(
 		path: string,
 		body: Record<string, unknown>,
+		signal?: AbortSignal,
 	): Promise<T> {
 		const response = await this.fetchRest(path, {
 			method: "POST",
 			body: JSON.stringify(body),
 			headers: { "Content-Type": "application/json" },
+			signal,
 		});
 		return response.data as T;
 	}
@@ -394,6 +493,7 @@ class RestAdapter implements ProtocolAdapter {
 	private async fetchRest(
 		path: string,
 		init: RequestInit,
+		binary = false,
 	): Promise<RestResponse> {
 		const url = joinRestUrl(this.config.baseUrl, path);
 		const headers = new Headers(init.headers);
@@ -418,13 +518,25 @@ class RestAdapter implements ProtocolAdapter {
 		} = {
 			...init,
 			headers,
-			signal: controller.signal,
+			// A caller's signal abandons the request; the timeout still applies.
+			signal: AbortSignal.any([
+				controller.signal,
+				...[init.signal, this.config.signal].filter(
+					(signal): signal is AbortSignal =>
+						signal !== undefined && signal !== null,
+				),
+			]),
 			tls: { rejectUnauthorized: this.config.insecure !== true },
 		};
 
 		try {
 			const response = await fetch(url, fetchInit);
-			const text = await response.text();
+			// A binary reply decodes as a byte string through Buffer's latin1;
+			// WHATWG latin1 is windows-1252 and loses 0x80–0x9f. Errors stay UTF-8
+			// text for the message.
+			const text = Buffer.from(await response.arrayBuffer()).toString(
+				binary && response.ok ? "latin1" : "utf8",
+			);
 			const data = parseResponseBody(text);
 			if (!response.ok) {
 				throw this.mapHttpFailure(response.status, text, data, path);
@@ -451,7 +563,7 @@ class RestAdapter implements ProtocolAdapter {
 		if (status === 401 || status === 403) {
 			return new CentrsError({
 				code: "transport/auth-failed",
-				summary: `RouterOS rejected the REST credentials for ${host}:${port}.`,
+				summary: `RouterOS rejected the REST credentials for ${formatEndpoint(host, port)}.`,
 				remediation:
 					"Check `--username` / `--password` or the matching `CENTRS_*` environment variables, and confirm the user has RouterOS REST access.",
 				context: { via: protocol, host, port, path, status },
@@ -497,7 +609,7 @@ class RestAdapter implements ProtocolAdapter {
 		) {
 			return new CentrsError({
 				code: "transport/timeout",
-				summary: `Timed out waiting for ${protocol} to respond from ${host}:${port}.`,
+				summary: `Timed out waiting for ${protocol} to respond from ${formatEndpoint(host, port)}.`,
 				remediation:
 					"Increase `--timeout` within the REST ceiling, or confirm the host and port are reachable.",
 				context: { via: protocol, host, port, path, timeoutMs },
@@ -518,7 +630,7 @@ class RestAdapter implements ProtocolAdapter {
 		) {
 			return new CentrsError({
 				code: "transport/connection-refused",
-				summary: `Connection refused by ${host}:${port} over ${protocol}.`,
+				summary: `Connection refused by ${formatEndpoint(host, port)} over ${protocol}.`,
 				remediation:
 					"Check that the RouterOS REST service is enabled on that port and that any local forwarding or firewall rules are correct.",
 				context: { via: protocol, host, port, path },
@@ -550,7 +662,7 @@ class RestAdapter implements ProtocolAdapter {
 		if (messages.some((candidate) => candidate.includes("certificate"))) {
 			return new CentrsError({
 				code: "transport/tls-certificate",
-				summary: `TLS certificate validation failed for ${host}:${port}.`,
+				summary: `TLS certificate validation failed for ${formatEndpoint(host, port)}.`,
 				remediation:
 					"RouterOS ships a self-signed certificate by default. Install a trusted chain, or pass `--insecure` (`CENTRS_INSECURE=1`) to accept it; an HTTP URL also avoids TLS.",
 				context: { via: protocol, host, port, path },
@@ -560,7 +672,7 @@ class RestAdapter implements ProtocolAdapter {
 
 		return new CentrsError({
 			code: "transport/network",
-			summary: `Network request to ${host}:${port} failed over ${protocol}.`,
+			summary: `Network request to ${formatEndpoint(host, port)} failed over ${protocol}.`,
 			remediation:
 				"Check the host, port, and service availability, then re-run with `--format json` if you need the structured cause data.",
 			context: { via: protocol, host, port, path },
@@ -569,6 +681,34 @@ class RestAdapter implements ProtocolAdapter {
 	}
 }
 
+/** One native sentence shape for one-shot and incremental API requests. */
+function nativeCommandFor(request: ProtocolApiRequest): NativeApiCommand {
+	const base = request.path.replace(/\/$/, "");
+	const command: NativeApiCommand = {
+		command:
+			request.script !== undefined
+				? "/execute"
+				: request.verb === "run"
+					? base
+					: request.verb === "print" && request.listen
+						? `${base}/listen`
+						: `${base}/${request.verb}`,
+		attributes:
+			request.script !== undefined
+				? { script: request.script, "as-string": "" }
+				: { ...request.attributes },
+	};
+	if (request.verb === "set" || request.verb === "remove") {
+		command.attributes = { ...command.attributes, ".id": request.id ?? "" };
+	}
+	const queries = (request.query ?? []).map((word) => `?${word}`);
+	if (request.id && request.verb === "print")
+		queries.push(`?.id=${request.id}`);
+	if (queries.length > 0) command.queries = queries;
+	if (request.proplist?.length) command.proplist = request.proplist;
+	return command;
+}
+
 class NativeApiAdapter implements ProtocolAdapter {
 	readonly protocol: RouterOsProtocol;
 	readonly capabilities: ProtocolAdapterCapabilities = {
@@ -577,18 +717,23 @@ class NativeApiAdapter implements ProtocolAdapter {
 		inspect: true,
 	};
 	private session?: NativeApiSession;
+	private readonly onAbort = (): void => {
+		this.session?.close();
+	};
 
 	constructor(private readonly config: ProtocolAdapterConfig) {
 		this.protocol = config.protocol;
+		config.signal?.addEventListener("abort", this.onAbort, { once: true });
 	}
 
 	async inspect(
 		request: "child" | "completion",
 		path: string,
+		input?: string,
 	): Promise<unknown[]> {
 		const replies = await this.talk({
 			command: "/console/inspect",
-			attributes: { request, path },
+			attributes: input === undefined ? { request, path } : { request, input },
 		});
 		return repliesToRecords(replies);
 	}
@@ -611,6 +756,9 @@ class NativeApiAdapter implements ProtocolAdapter {
 		if (options.detail) {
 			command.attributes = { detail: "" };
 		}
+		if (options.query && options.query.length > 0) {
+			command.queries = options.query.map((word) => `?${word}`);
+		}
 		const replies = await this.talk(command);
 		return repliesToRecords(replies);
 	}
@@ -630,6 +778,9 @@ class NativeApiAdapter implements ProtocolAdapter {
 		if (request.queries && request.queries.length > 0) {
 			command.queries = request.queries;
 		}
+		if (request.binary) {
+			command.binary = true;
+		}
 		const replies = await this.talk(command);
 		return { records: repliesToRecords(replies) };
 	}
@@ -652,110 +803,60 @@ class NativeApiAdapter implements ProtocolAdapter {
 	}
 
 	async apiRequest(request: ProtocolApiRequest): Promise<ProtocolApiResult> {
-		const base = request.path.replace(/\/$/, "");
+		const records = repliesToRecords(
+			await this.talk(nativeCommandFor(request)),
+		);
 		switch (request.verb) {
-			case "print": {
-				const command: NativeApiCommand = { command: `${base}/print` };
-				const queries: string[] = [];
-				// REST `.query` words map 1:1 to native `?`-prefixed words (CHR-grounded).
-				for (const word of request.query ?? []) {
-					queries.push(`?${word}`);
-				}
-				// No native get-one-by-id shorthand: address a single row with `?.id=`.
-				if (request.id) {
-					queries.push(`?.id=${request.id}`);
-				}
-				if (queries.length > 0) {
-					command.queries = queries;
-				}
-				if (request.proplist && request.proplist.length > 0) {
-					command.proplist = request.proplist;
-				}
-				const records = repliesToRecords(await this.talk(command));
+			case "print":
 				return { data: request.id ? (records[0] ?? null) : records };
-			}
-			case "add": {
-				const records = repliesToRecords(
-					await this.talk({
-						command: `${base}/add`,
-						attributes: request.attributes ?? {},
-					}),
-				);
-				return { data: restStyleMutationData(records) };
-			}
-			case "set": {
-				const records = repliesToRecords(
-					await this.talk({
-						command: `${base}/set`,
-						attributes: {
-							...(request.attributes ?? {}),
-							".id": request.id ?? "",
-						},
-					}),
-				);
-				return { data: restStyleMutationData(records) };
-			}
-			case "remove": {
-				const records = repliesToRecords(
-					await this.talk({
-						command: `${base}/remove`,
-						attributes: { ".id": request.id ?? "" },
-					}),
-				);
+			case "add":
+			case "set":
+			case "remove":
 				return { data: restStyleMutationData(records) };
-			}
-			case "run": {
-				if (request.script !== undefined) {
-					const records = await this.executeScript(request.script);
-					return { data: restStyleRunData(records) };
-				}
-				const command: NativeApiCommand = { command: base };
-				if (request.attributes && Object.keys(request.attributes).length > 0) {
-					command.attributes = request.attributes;
-				}
-				return { data: repliesToRecords(await this.talk(command)) };
-			}
+			case "run":
+				return {
+					data:
+						request.script !== undefined ? restStyleRunData(records) : records,
+				};
 			default:
 				return exhaustiveApiVerb(request.verb);
 		}
 	}
 
-	async *listen(
+	async *stream(
 		request: ProtocolApiRequest,
 		options: ProtocolListenOptions,
-	): AsyncGenerator<Record<string, unknown>> {
-		const base = request.path.replace(/\/$/, "");
-		const command: NativeApiCommand = { command: `${base}/listen` };
-		// A listen can filter which changes it follows with the same `?`-words /
-		// `=.proplist=` as print (REST `.query` word == native `?`-word minus `?`).
-		const queries = (request.query ?? []).map((word) => `?${word}`);
-		// An addressed row (`ip/address/*1 --stream`) follows just that row, the
-		// same `?.id=` mapping one-shot native reads use.
-		if (request.id) {
-			queries.push(`?.id=${request.id}`);
-		}
-		if (queries.length > 0) {
-			command.queries = queries;
-		}
-		if (request.proplist && request.proplist.length > 0) {
-			command.proplist = request.proplist;
-		}
+	): AsyncGenerator<ProtocolStreamReply> {
+		if (options.signal?.aborted) return;
 		const session = await this.connect();
-		for await (const reply of session.listen(command, {
+		const { onReply } = options;
+		for await (const reply of session.listen(nativeCommandFor(request), {
 			...options,
 			cancelGraceMs: options.cancelGraceMs ?? this.config.timeoutMs,
+			onReply: onReply
+				? (reply) =>
+						onReply({
+							type: reply.type.slice(1) as ProtocolTappedReply["type"],
+							attributes: { ...reply.attributes },
+						})
+				: undefined,
 		})) {
-			// Each `!re` becomes a rest-style record (string values; `.dead` preserved).
-			yield { ...reply.attributes };
+			yield {
+				type: reply.type === "!empty" ? "empty" : "re",
+				attributes: { ...reply.attributes },
+				...(reply.afterStop ? { afterStop: true as const } : {}),
+			};
 		}
 	}
 
 	async close(): Promise<void> {
+		this.config.signal?.removeEventListener("abort", this.onAbort);
 		this.session?.close();
 		this.session = undefined;
 	}
 
 	private async connect(): Promise<NativeApiSession> {
+		this.config.signal?.throwIfAborted();
 		if (this.session) {
 			return this.session;
 		}
@@ -769,7 +870,12 @@ class NativeApiAdapter implements ProtocolAdapter {
 			// RouterOS's self-signed cert. (Previously native-api always accepted.)
 			rejectUnauthorized: this.config.insecure !== true,
 			timeoutMs: this.config.timeoutMs,
+			signal: this.config.signal,
 		});
+		if (this.config.signal?.aborted) {
+			session.close();
+			this.config.signal.throwIfAborted();
+		}
 		this.session = session;
 		return session;
 	}
@@ -897,8 +1003,8 @@ class MacTelnetAdapter implements ProtocolAdapter {
 	}
 
 	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
-	async *listen(): AsyncGenerator<Record<string, unknown>> {
-		throw this.unsupported("open-ended listen streaming");
+	async *stream(): AsyncGenerator<ProtocolStreamReply> {
+		throw this.unsupported("incremental native replies");
 	}
 
 	async close(): Promise<void> {
@@ -1048,8 +1154,8 @@ class SshExecAdapter implements ProtocolAdapter {
 	}
 
 	// biome-ignore lint/correctness/useYield: a reject-only async generator yields nothing.
-	async *listen(): AsyncGenerator<Record<string, unknown>> {
-		throw this.unsupported("open-ended listen streaming");
+	async *stream(): AsyncGenerator<ProtocolStreamReply> {
+		throw this.unsupported("incremental native replies");
 	}
 
 	close(): Promise<void> {

package/src/protocols/btest-session.ts

@@ -80,6 +80,7 @@ import {
 	ecSrp5ServerPublicKey,
 	ecSrp5ServerShared,
 } from "./ec-srp5.ts";
+import { formatEndpoint } from "./endpoint.ts";
 
 /** Default status-exchange cadence (RouterOS uses ~1s). */
 export const BTEST_STATUS_INTERVAL_MS = 1000;
@@ -320,7 +321,7 @@ export function connectBtestControl(
 				reject(
 					new CentrsError({
 						code: "transport/connection-refused",
-						summary: `No btest server answered on ${host}:${port}.`,
+						summary: `No btest server answered on ${formatEndpoint(host, port)}.`,
 						remediation:
 							"Enable /tool/bandwidth-server on the device (or start `centrs btest server`) and check the host/--port.",
 						context: { host, port, cause: code },
@@ -332,7 +333,7 @@ export function connectBtestControl(
 			reject(
 				new CentrsError({
 					code: "transport/network",
-					summary: `Failed to open the btest control connection to ${host}:${port}.`,
+					summary: `Failed to open the btest control connection to ${formatEndpoint(host, port)}.`,
 					remediation: "Check the host, --port, and network reachability.",
 					context: { host, port, cause: code },
 					cause: error,

package/src/protocols/endpoint.ts

@@ -0,0 +1,10 @@
+/**
+ * `host:port` for messages and endpoint labels. An IPv6 host is bracketed
+ * (`[2001:db8::5]:9`), because a bare `2001:db8::5:9` reads as another address.
+ * Sockets still take the bare host.
+ */
+export function formatEndpoint(host: string, port: number): string {
+	const bracketed =
+		host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+	return `${bracketed}:${port}`;
+}

package/src/protocols/mac-telnet-console.ts

@@ -42,9 +42,10 @@
  *     (name-level) gate — no `/console/inspect` table parsing needed.
  */
 
+import { absentMenuError } from "../absent-menu.ts";
 import { parseRouterOsPosition } from "../core/routeros-errors.ts";
 import { routerOsStringLiteral } from "../core/routeros-string.ts";
-import { CentrsError } from "../errors.ts";
+import { CentrsError, SYNTAX_REJECTED_REMEDIATION } from "../errors.ts";
 import {
 	type MacAddress,
 	type MacTelnetDatagramSink,
@@ -681,11 +682,13 @@ export function classifyParseResult(
 		});
 	}
 	if (WRAPPED_BAD_COMMAND.test(output) || BARE_SYNTAX.test(output)) {
+		// An absent menu reads as a syntax error; name it instead (GH#361).
+		const absent = absentMenuError(cli, output, position, via);
+		if (absent) throw absent;
 		throw new CentrsError({
 			code: "validation/syntax",
 			summary: "RouterOS rejected the command syntax while parsing it.",
-			remediation:
-				"Fix the RouterOS CLI syntax (quotes, brackets, attribute form), then retry.",
+			remediation: SYNTAX_REJECTED_REMEDIATION,
 			context: {
 				command: cli,
 				validationSource: `:put [:parse ...] over ${via}`,