@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/cli/retrieve.ts

@@ -11,16 +11,23 @@ import {
 } from "../errors.ts";
 import {
 	buildRetrieveErrorEnvelope,
+	buildRetrieveErrorEnvelopeFromResolved,
 	buildRetrieveFanoutErrorEnvelope,
 	describeCentrs,
 	fanoutExitCode,
+	type ResolvedRetrieveRequest,
 	type RetrieveOutputFormat,
 	type RetrieveRequest,
 	renderRetrieveEnvelope,
 	renderRetrieveFanoutEnvelope,
+	renderRetrieveStreamLine,
 	retrieve,
 	retrieveFanout,
+	retrieveFollow,
 	retrieveOutputFormats,
+	retrieveSample,
+	retrieveWait,
+	type ValidationTrace,
 } from "../index.ts";
 import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
 import {
@@ -50,7 +57,7 @@ import {
 export const retrieveCommand: CliCommandMetadata = {
 	name: "retrieve",
 	usage:
-		"centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]",
+		"centrs retrieve <target> <routeros-path> [flags] | centrs retrieve <target...> <routeros-path> [flags] | centrs retrieve --host <host|url> <routeros-path> [flags] | centrs retrieve --group <name> <routeros-path> [flags]",
 	summary:
 		"Read RouterOS values through the shared core using the selected protocol.",
 	options: [
@@ -58,13 +65,14 @@ export const retrieveCommand: CliCommandMetadata = {
 			flag: "--via",
 			valueName: "<protocol>",
 			description:
-				"Pin the protocol selector. Defaults to `rest-api` for retrieve.",
+				"Pin the protocol selector. Defaults to `rest-api` for retrieve (`--sample` included), and to `native-api` under `--follow`.",
 		},
 		...selectionCommandOptions,
 		{
 			flag: "--host",
 			valueName: "<host|url>",
-			description: "Override the resolved host or base URL for the target.",
+			description:
+				"Host or base URL to dial. With no <target> it is the target (no CDB lookup); with one it overrides the resolved host.",
 		},
 		{
 			flag: "--port",
@@ -86,7 +94,7 @@ export const retrieveCommand: CliCommandMetadata = {
 			flag: "--timeout",
 			valueName: "<ms|5s>",
 			description:
-				"Operation timeout. REST currently rejects values above 60s.",
+				"Per-request timeout, separate from --wait's overall deadline. REST currently rejects values above 60s.",
 		},
 		{
 			flag: "--attribute",
@@ -111,13 +119,59 @@ export const retrieveCommand: CliCommandMetadata = {
 			flag: "--query / --filter",
 			valueName: "<expr>",
 			description:
-				"RouterOS-side row filter (maps to `.query`). Not implemented yet — returns `validation/not-implemented`.",
+				"Row filter written as after `print where` (`disabled`, `mtu>=1500 and !dynamic`), run on the router as an API query; repeatable, AND-ed. No `~` or `in`.",
+		},
+		{
+			flag: "--follow",
+			description:
+				"Keep the menu's rows current over native-api `listen`: snapshot frames, a `synced` line, then a line per change, then a summary (NDJSON for json/yaml/ndjson). Single target, list menus whose print takes follow-only.",
+		},
+		{
+			flag: "--sample",
+			valueName: "<interval>",
+			description:
+				"Read the menu again every interval (with a unit, e.g. `5s`): one line per complete read, then a summary. With --wait, sets polling cadence and returns one final envelope. Sees counters and state listen never reports. Single target; rest-api or native-api.",
+		},
+		{
+			flag: "--wait",
+			valueName: "<deadline>",
+			description:
+				"Wait for a successful read or a condition until this overall deadline, with a unit (e.g. `2m`). Retries refused, closed, reset and timed-out connections and a down or unreachable host; other errors fail at once. One final envelope; single target.",
+		},
+		{
+			flag: "--until",
+			valueName: "<expr>",
+			description:
+				"With --wait: succeed when any selected row matches this --query grammar predicate; repeatable, AND-ed. Returns the matching rows. Already true succeeds on the initial read.",
+		},
+		{
+			flag: "--until-empty",
+			description:
+				"With --wait: succeed on a completed read with zero rows selected by --query. Silence and failed reads never satisfy it.",
+		},
+		{
+			flag: "--sweep",
+			valueName: "<duration>",
+			description:
+				"`--follow` only: how often a membership sweep finds removals RouterOS does not send, including silent exits from --query. Needs a unit; default `10s`; `0` turns it off.",
+		},
+		{
+			flag: "--count",
+			valueName: "<n>",
+			description:
+				"`--follow`: stop after N live changes (snapshot frames and `synced` do not count). `--sample`: stop after N samples.",
+		},
+		{
+			flag: "--duration",
+			valueName: "<duration>",
+			description:
+				"`--follow`/`--sample`: stop after this wall-clock window (e.g. `30s`), counted from the end of validation.",
 		},
 		{
 			flag: "--format",
 			valueName: `<${retrieveOutputFormats.join("|")}>`,
 			description:
-				"Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope.",
+				"Output format for the CLI response. Defaults to text; use --json or --format json for the structured envelope. `ndjson` prints each envelope as one compact line.",
 		},
 		{
 			flag: "--json",
@@ -164,6 +218,8 @@ type RetrieveCliArgs = RetrieveRequest & {
 
 export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 	let request: RetrieveCliArgs | undefined;
+	let resolved: ResolvedRetrieveRequest | undefined;
+	const trace: ValidationTrace = {};
 
 	try {
 		request = parseRetrieveCliArgs(args);
@@ -177,6 +233,28 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 		// single-target envelope.
 		const selectionFlags = request.selectionFlags ?? emptySelectionFlags();
 		const targetPositionals = request.targetPositionals ?? [];
+		if (
+			request.wait !== undefined ||
+			request.follow ||
+			request.sample !== undefined
+		) {
+			const mode =
+				request.wait !== undefined
+					? "--wait"
+					: request.follow
+						? "--follow"
+						: "--sample";
+			if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+				throw new CentrsError({
+					code: "usage/fanout-not-supported",
+					summary: `\`retrieve ${mode}\` watches one router and cannot fan out across multiple targets.`,
+					remediation: `Watch a single router (no \`--group\`/\`--where\`/\`--all\`/\`--default\`/multiple positionals); run one \`${mode}\` per router to watch several.`,
+				});
+			}
+			return request.wait !== undefined
+				? await runRetrieveWaitCli(request, args)
+				: await runRetrieveStreamCli(request, args);
+		}
 		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
 			return await runRetrieveFanoutCli(
 				request,
@@ -186,7 +264,12 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 			);
 		}
 
-		const envelope = await retrieve(request);
+		const envelope = await retrieve(request, Bun.env, {
+			trace,
+			onResolved: (value) => {
+				resolved = value;
+			},
+		});
 		const resolvedFormat =
 			(
 				envelope.meta.operation as {
@@ -209,13 +292,17 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 					env: Bun.env,
 				})
 			: [];
-		if (format === "json" || format === "yaml") {
+		if (format !== "text") {
 			// When parsing failed before a request existed, build the error envelope
 			// from an empty request rather than reconstructing positionals from raw
 			// args — a credential value (e.g. the token after `--password` /
 			// `--cdb-password`) would otherwise be echoed as `meta.target.input`.
+			// A failure after resolution keeps the resolved target, via and
+			// setting sources (#433).
 			const envelope = withTips(
-				buildRetrieveErrorEnvelope(request ?? { path: "" }, error),
+				resolved
+					? buildRetrieveErrorEnvelopeFromResolved(resolved, error, trace)
+					: buildRetrieveErrorEnvelope(request ?? { path: "" }, error),
 				tips,
 			);
 			console.error(
@@ -244,6 +331,61 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 	}
 }
 
+/**
+ * Every `--follow`/`--sample` envelope goes to stdout, one per line, errors
+ * included; any failure sets exit 1, even after successful lines. Ctrl-C asks
+ * for a bounded stop that still ends with a summary.
+ */
+async function runRetrieveStreamCli(
+	request: RetrieveCliArgs,
+	args: readonly string[],
+): Promise<number> {
+	const format = inferRequestedFormat(args, request);
+	const controller = new AbortController();
+	const onSigint = (): void => controller.abort();
+	process.on("SIGINT", onSigint);
+	let exitCode = 0;
+	try {
+		const stream = request.follow ? retrieveFollow : retrieveSample;
+		for await (const envelope of stream(request, Bun.env, {
+			signal: controller.signal,
+		})) {
+			// A config-file `CENTRS_FORMAT` is known only after resolution.
+			const resolvedFormat = envelope.meta.operation?.request.format ?? format;
+			console.log(renderRetrieveStreamLine(envelope, resolvedFormat));
+			if (!envelope.ok) exitCode = 1;
+		}
+	} finally {
+		process.off("SIGINT", onSigint);
+	}
+	return exitCode;
+}
+
+async function runRetrieveWaitCli(
+	request: RetrieveCliArgs,
+	args: readonly string[],
+): Promise<number> {
+	const controller = new AbortController();
+	const onSigint = (): void => controller.abort();
+	process.on("SIGINT", onSigint);
+	try {
+		const envelope = await retrieveWait(request, Bun.env, {
+			signal: controller.signal,
+		});
+		console.log(
+			renderRetrieveEnvelope(
+				envelope,
+				envelope.meta.operation?.request.format ??
+					inferRequestedFormat(args, request),
+				{ verbose: request.verbose },
+			),
+		);
+		return envelope.ok ? 0 : 1;
+	} finally {
+		process.off("SIGINT", onSigint);
+	}
+}
+
 async function runRetrieveFanoutCli(
 	request: RetrieveCliArgs,
 	selectionFlags: SelectionFlags,
@@ -348,10 +490,11 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 				request.listAttributes = true;
 				break;
 			case "--filter":
-				request.filter = expectValue(args, ++index, arg);
-				break;
 			case "--query":
-				request.query = expectValue(args, ++index, arg);
+				request.query = [
+					...[request.query ?? []].flat(),
+					expectValue(args, ++index, arg),
+				];
 				break;
 			case "--max-results":
 				request.maxResultsBytes = Number.parseInt(
@@ -377,6 +520,33 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 			case "--verbose":
 				request.verbose = true;
 				break;
+			case "--follow":
+				request.follow = true;
+				break;
+			case "--sample":
+				request.sample = expectValue(args, ++index, arg);
+				break;
+			case "--sweep":
+				request.sweep = expectValue(args, ++index, arg);
+				break;
+			case "--count":
+				request.count = parseCountFlag(expectValue(args, ++index, arg));
+				break;
+			case "--duration":
+				request.duration = expectValue(args, ++index, arg);
+				break;
+			case "--wait":
+				request.wait = expectValue(args, ++index, arg);
+				break;
+			case "--until":
+				request.until = [
+					...[request.until ?? []].flat(),
+					expectValue(args, ++index, arg),
+				];
+				break;
+			case "--until-empty":
+				request.untilEmpty = true;
+				break;
 			default: {
 				const consumed = consumeSelectionFlag(args, index, selectionFlags);
 				if (consumed !== null) {
@@ -428,18 +598,28 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 
 	// A single `--quickchr <name>` is single-target mode: the machine name is the
 	// target (resolved from the live descriptor inside the resolver); the lone
-	// positional is the routeros-path.
-	if (selectionFlags.quickchr.length === 1) {
-		if (positional.length === 0 || path.length === 0) {
+	// positional is the routeros-path. The `--host` flag stands in for a missing
+	// `<router>` the same way (#428), with no CDB lookup; `CENTRS_HOST` never
+	// counts.
+	const quickchr = selectionFlags.quickchr[0];
+	const hostOnly =
+		quickchr === undefined &&
+		targetPositionals.length === 0 &&
+		request.host !== undefined;
+	if (quickchr !== undefined || hostOnly) {
+		if (path.length === 0) {
+			const flag = hostOnly ? "--host" : "--quickchr";
+			const example = hostOnly ? "--host 192.0.2.10" : "--quickchr lab";
 			throw new CentrsError({
 				code: "input/invalid-command",
-				summary: "`centrs retrieve --quickchr` requires a <routeros-path>.",
-				remediation:
-					"Add the RouterOS menu path as the final positional, e.g. `centrs retrieve --quickchr lab /system/resource`.",
+				summary: `\`centrs retrieve ${flag}\` requires a <routeros-path>.`,
+				remediation: `Add the RouterOS menu path as the final positional, e.g. \`centrs retrieve ${example} /system/resource\`.`,
 				context: { command: "retrieve", missingPath: true },
 			});
 		}
-		request.quickchr = selectionFlags.quickchr[0];
+		if (quickchr !== undefined) {
+			request.quickchr = quickchr;
+		}
 		return request;
 	}
 
@@ -448,7 +628,7 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 			command: "retrieve",
 			summary: "`centrs retrieve` requires a <target> and a <routeros-path>.",
 			remediation:
-				"Pass the router host/identity then the RouterOS path, e.g. `centrs retrieve 192.0.2.10 /system/resource`.",
+				"Pass the router host/identity then the RouterOS path, e.g. `centrs retrieve 192.0.2.10 /system/resource`, or name the host with `--host <host|url>`.",
 		});
 	}
 	// Single-target: exactly one target positional (more would be fan-out mode).
@@ -456,6 +636,20 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 	return request;
 }
 
+function parseCountFlag(value: string): number {
+	// The whole token: `parseInt` would accept `10abc` as 10.
+	if (!/^\d+$/.test(value.trim())) {
+		throw new CentrsError({
+			code: "settings/invalid-integer",
+			summary: `\`--count\` must be a positive integer. Received: ${value}`,
+			remediation:
+				"Pass how many live changes (`--follow`) or samples (`--sample`) to wait for, e.g. `--count 1`.",
+			context: { flag: "--count" },
+		});
+	}
+	return Number.parseInt(value, 10);
+}
+
 function inferRequestedFormat(
 	args: readonly string[],
 	request?: RetrieveRequest,
@@ -471,8 +665,8 @@ function inferRequestedFormat(
 		return args[formatIndex + 1] as RetrieveOutputFormat;
 	}
 	const envFormat = process.env["CENTRS_FORMAT"];
-	if (envFormat === "json" || envFormat === "yaml" || envFormat === "text") {
-		return envFormat;
+	if (retrieveOutputFormats.includes(envFormat as RetrieveOutputFormat)) {
+		return envFormat as RetrieveOutputFormat;
 	}
 	return "text";
 }

package/src/cli/terminal.ts

@@ -37,7 +37,8 @@ import { selectionFlagTokens } from "./selection.ts";
 
 export const terminalCommand: CliCommandMetadata = {
 	name: "terminal",
-	usage: "centrs terminal <router> [flags]",
+	usage:
+		"centrs terminal <router> [flags] | centrs terminal --host <host> [flags]",
 	summary: "Open an interactive RouterOS console (ssh or mac-telnet).",
 	options: [
 		{
@@ -50,7 +51,7 @@ export const terminalCommand: CliCommandMetadata = {
 			flag: "--host",
 			valueName: "<host>",
 			description:
-				"Override the target host (ssh) / UDP delivery host (mac-telnet, default L2 broadcast).",
+				"ssh: the host to dial (the target when no <router> is given; no CDB lookup). mac-telnet: the UDP delivery host (default L2 broadcast).",
 		},
 		{
 			flag: "--port",
@@ -299,16 +300,20 @@ export function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 	if (help) {
 		return { help: true, request: {} };
 	}
+	// The `--host` flag stands in for a missing `<router>` (#428), with no CDB
+	// lookup; `CENTRS_HOST` never counts.
 	const targetInput = positional[0];
-	if (!targetInput) {
+	if (!targetInput && flags.host === undefined) {
 		throw missingTargetError({
 			command: "terminal",
 			summary: "`centrs terminal` requires a <router> target.",
 			remediation:
-				"Pass the device MAC (or a CDB identity/ip) as the first argument; run `centrs terminal --help` for the shape.",
+				"Pass the device MAC (or a CDB identity/ip) as the first argument, or name an ssh host with `--host <host>`; run `centrs terminal --help` for the shape.",
 		});
 	}
-	flags.targetInput = targetInput;
+	if (targetInput) {
+		flags.targetInput = targetInput;
+	}
 	return { request: flags };
 }
 

package/src/cli/transfer.ts

@@ -18,7 +18,7 @@ import {
 	type TransferOutputFormat,
 	type TransferRequest,
 	type TransferVerb,
-	transfer,
+	transferEnvelope,
 	transferFanout,
 	transferOutputFormats,
 	transferVerbs,
@@ -62,7 +62,7 @@ const VERB_ALIASES: Record<string, TransferVerb> = {
 export const transferCommand: CliCommandMetadata = {
 	name: "transfer",
 	usage:
-		"centrs transfer <router> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]",
+		"centrs transfer <router>|--host <host> upload <local> [remote] | download <remote> [local] | list [path] | remove <remote> | mkdir <remote> | copy <src> <dst> [flags]",
 	summary:
 		"Copy files to/from a RouterOS device and manage device files (rest/native/sftp).",
 	options: [
@@ -85,7 +85,8 @@ export const transferCommand: CliCommandMetadata = {
 		},
 		{
 			flag: "--force / --overwrite",
-			description: "Replace an existing destination. Default refuses it.",
+			description:
+				"Skip the existing-destination check on the device for `upload`/`mkdir`/`copy` (`upload` then overwrites). Default refuses an existing target. `download` always replaces the local file.",
 		},
 		...selectionCommandOptions,
 		{
@@ -118,7 +119,8 @@ export const transferCommand: CliCommandMetadata = {
 		{
 			flag: "--host",
 			valueName: "<host|url>",
-			description: "Override the resolved host or base URL.",
+			description:
+				"Host or base URL to dial. With no <router> before the verb it is the target (no CDB lookup); with one it overrides the resolved host.",
 		},
 		{
 			flag: "--port",
@@ -199,11 +201,18 @@ export async function runTransferCli(
 		}
 		request = parsed.request;
 
-		const envelope = await transfer(request);
+		const envelope = await transferEnvelope(request);
 		const format = resolvedFormat(request);
 		const rendered = renderTransferEnvelope(envelope, format, {
 			verbose: request.verbose,
 		});
+		if (!envelope.ok) {
+			console.error(
+				// codeql[js/clear-text-logging] The envelope carries auth provenance only (`username`, `passwordProvided`, setting sources), never the password; see buildTransferErrorEnvelopeFromResolved.
+				format === "text" ? rendered + formatTipsText(envelope.tips) : rendered,
+			);
+			return 1;
+		}
 		// A download to stdout (`local === "-"`) has already streamed the file bytes
 		// to stdout inside `transfer()`; keep the structured envelope on stderr so it
 		// cannot interleave with — and corrupt — the piped payload.
@@ -502,7 +511,7 @@ function assemblePositionals(
 	} else {
 		const verbIndex = positional.findIndex(isTransferVerbToken);
 		if (verbIndex === -1) {
-			if (positional.length === 0 && !hasSelector) {
+			if (positional.length === 0 && !hasSelector && flags.host === undefined) {
 				throw missingTargetError({
 					command: "transfer",
 					summary:
@@ -536,7 +545,10 @@ function assemblePositionals(
 	}
 
 	// Single-target (not fan-out mode) needs exactly one resolved target: one
-	// positional, or one `--quickchr <name>` (the named-live-provider).
+	// positional, one `--quickchr <name>` (the named-live-provider), or the
+	// `--host` flag with no positional before the verb (#428; no CDB lookup,
+	// `CENTRS_HOST` never counts). The `upload`/`download` aliases always read their first
+	// positional as the target, since a path count can't tell them apart.
 	if (!isFanoutMode(selectionFlags, targetPositionals.length)) {
 		if (selectionFlags.quickchr.length === 1) {
 			request.quickchr = selectionFlags.quickchr[0];
@@ -544,11 +556,14 @@ function assemblePositionals(
 		}
 		const targetInput = targetPositionals[0];
 		if (!targetInput) {
+			if (flags.host !== undefined && !fixedVerb) {
+				return { request, targetPositionals };
+			}
 			throw missingTargetError({
 				command: "transfer",
 				summary: "`centrs transfer` requires a <router> target.",
 				remediation:
-					"Pass the router host/identity as the first argument; run `centrs transfer --help` for the command shape.",
+					"Pass the router host/identity as the first argument, or name the host with `--host <host>` (`transfer` verb form only); run `centrs transfer --help` for the command shape.",
 			});
 		}
 		request.targetInput = targetInput;

package/src/core/envelope.ts

@@ -159,6 +159,11 @@ export interface EnvelopeValidationMeta {
 	enabled: boolean;
 	/** Validator identity, e.g. `/console/inspect` or `:put [:parse]`. */
 	source?: string;
+	/**
+	 * The gate's verdict. Absent when the gate never produced one: a transport,
+	 * auth or device error interrupted it, or a failure came before it ran.
+	 * `stages[]` then says which stage was not reached and why (GH#435).
+	 */
 	result?: "passed" | "failed" | "skipped";
 	/** Syntax gate status for commands that use RouterOS `:parse`. */
 	syntax?: boolean;
@@ -176,6 +181,15 @@ export interface EnvelopeValidationMeta {
 	stages?: readonly EnvelopeValidationStage[];
 }
 
+/**
+ * The `reason` a stage carries when the gate never reached it: the error that
+ * stopped the run before that stage produced a verdict (GH#435). One wording
+ * across commands, so a consumer can match on the `not reached:` prefix.
+ */
+export function notReachedReason(code: string): string {
+	return `not reached: ${code}`;
+}
+
 export interface EnvelopeTimingMeta {
 	startedAt?: string;
 	durationMs?: number;

package/src/core/error-catalog.ts

@@ -40,6 +40,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/already-exists",
 		summary: "A CDB entry with that target already exists.",
 	},
+	{
+		code: "cdb/create-failed",
+		summary: "A new CDB file could not be created at the resolved location.",
+	},
 	{
 		code: "cdb/created",
 		summary: "A new CDB file was created at the resolved location.",
@@ -57,6 +61,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/empty-selection",
 		summary: "The target selection matched no CDB records.",
 	},
+	{
+		code: "cdb/file-exists",
+		summary:
+			"`devices init` found a CDB already at the resolved location and wrote nothing.",
+	},
 	{
 		code: "cdb/invalid-option",
 		summary: "A comment kv-soup option carried an invalid value.",
@@ -164,6 +173,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"A file path contains a character the transport cannot quote (e.g. a quote or newline).",
 	},
+	{
+		code: "input/invalid-query",
+		summary:
+			"A --query expression does not parse as a `print where` condition.",
+	},
 	{
 		code: "input/invalid-radius",
 		summary:
@@ -177,6 +191,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "input/invalid-target",
 		summary: "The target string is invalid for the requested operation.",
 	},
+	{
+		code: "input/local-destination",
+		summary:
+			"A local download destination cannot be written (missing parent directory, a directory, or no permission).",
+	},
 	{
 		code: "input/local-file-not-found",
 		summary: "A local file required for the transfer could not be read.",
@@ -189,8 +208,17 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "input/max-results-exceeded",
 		summary: "Output exceeded the requested byte budget.",
 	},
+	{
+		code: "input/unsupported-query",
+		summary:
+			"A --query uses something the RouterOS API query cannot run (`~`, `in`, a `$variable` or `[command]`).",
+	},
 
 	// internal/*
+	{
+		code: "internal/byte-string",
+		summary: "A binary RouterOS word held a character that is not a byte.",
+	},
 	{
 		code: "internal/devices-failed",
 		summary: "The devices command failed with an unexpected internal error.",
@@ -430,6 +458,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"Auto-selection moved the operation to a different method (informational auto-hop).",
 	},
+	{
+		code: "transport/cancel-unacknowledged",
+		summary:
+			"RouterOS did not acknowledge a stream's /cancel within the timeout; centrs ended the stream and closed the session locally.",
+	},
 	{
 		code: "transport/capability-unsupported",
 		summary: "The chosen transport cannot perform this kind of operation.",
@@ -479,6 +512,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "transport/network",
 		summary: "A network request to the device failed.",
 	},
+	{
+		code: "transport/stream-overflow",
+		summary:
+			"More stream replies were waiting unread than the buffer allows, so centrs ended the stream rather than drop any.",
+	},
 	{
 		code: "transport/timeout",
 		summary: "The transport request timed out.",
@@ -510,6 +548,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
 	},
+	{
+		code: "usage/removed-flag",
+		summary:
+			"A flag or request field was removed; the error names its replacement.",
+	},
 	{
 		code: "usage/stdin-ignored",
 		summary:
@@ -544,14 +587,29 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 
 	// validation/*
+	{
+		code: "validation/not-followable",
+		summary:
+			"The RouterOS menu cannot be followed: it is a single record, or its print has no follow-only.",
+	},
 	{
 		code: "validation/not-implemented",
 		summary: "The requested validation feature is not implemented yet.",
 	},
+	{
+		code: "validation/menu-unavailable",
+		summary:
+			"RouterOS 7 publishes this menu or command, but this device does not have it — usually hardware, build or version.",
+	},
 	{
 		code: "validation/option",
 		summary: "An unknown option value was supplied.",
 	},
+	{
+		code: "validation/package-missing",
+		summary:
+			"This device has no such menu or command; MikroTik publishes it in a package that is likely not installed.",
+	},
 	{
 		code: "validation/syntax",
 		summary:
@@ -564,7 +622,18 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "validation/unknown-path",
-		summary: "The RouterOS path does not expose the requested command.",
+		summary:
+			"The RouterOS path does not exist, or does not expose the requested command.",
+	},
+	{
+		code: "wait/deadline-exceeded",
+		summary:
+			"The wait deadline passed before readiness or its condition was established.",
+	},
+	{
+		code: "wait/interrupted",
+		summary:
+			"The wait was cancelled before readiness or its condition was established.",
 	},
 ];