@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/core/envelope.ts

@@ -15,6 +15,10 @@
  * - `meta` is invariant across commands. Only `data` and `meta.operation` vary
  *   per command. Do not add command-specific keys beside `target`/`via`/
  *   `settings`/`validation`/`timing`/`truncated`; put them in `meta.operation`.
+ * - Shared meta is written once (#461, #462, #473). A fan-out target omits
+ *   what its outer envelope already says ({@link FanoutMemberOperation}); a
+ *   stream's data lines between `started` and `summary` carry only their
+ *   `meta.operation` ({@link StreamLineEnvelope}).
  * - CLI render must be lossless against the JSON envelope; `--format json|yaml`
  *   select serialization, not different shapes. Omit `undefined`; use `null`
  *   only where absence is meaningful and must round-trip (e.g. `via: null` when
@@ -109,6 +113,17 @@ export interface EnvelopeTargetMeta {
 	source?: SettingSource;
 	/** Provenance per resolved field once the resolver is wired (WP-0c). */
 	sources?: Record<string, SettingSource>;
+	/**
+	 * `execute --cmr`: the CMR client this result belongs to, as the controller
+	 * knows it. `id` is the controller's `/cmr/device` row; `deviceKey` is the
+	 * device half of its `ids`. The client is never dialed directly; the
+	 * controller is the fan-out's outer `meta.target`.
+	 */
+	cmr?: {
+		id: string;
+		deviceKey?: string;
+		address?: string;
+	};
 }
 
 /**
@@ -153,6 +168,11 @@ export interface ValidationTrace {
 	 * to judge.
 	 */
 	offlineVerdict?: "pass" | "warn";
+	/**
+	 * Set immediately before the RouterOS request is sent. A failure after this
+	 * point may have run on the router, so a write must not be replayed (#448).
+	 */
+	dispatched?: boolean;
 }
 
 export interface EnvelopeValidationMeta {
@@ -271,9 +291,34 @@ export interface FanoutSummary {
 	failed: number;
 }
 
+/**
+ * A fan-out target's `meta.operation`. `request` and `auth` are omitted when
+ * they equal the outer `meta.operation`'s, and the target's `meta.settings`
+ * keeps only the keys whose source differs from the outer `meta.settings`, so
+ * a reader takes `target ?? outer` (per key for settings).
+ */
+export type FanoutMemberOperation<Operation> = Omit<
+	Operation,
+	"request" | "auth"
+> &
+	Partial<Pick<Operation, Extract<keyof Operation, "request" | "auth">>>;
+
 export interface FanoutData<Data = unknown, Operation = unknown> {
 	summary: FanoutSummary;
-	targets: readonly CentrsEnvelope<Data, Operation>[];
+	targets: readonly CentrsEnvelope<Data, FanoutMemberOperation<Operation>>[];
+}
+
+/**
+ * A stream data line that carries only its own `meta.operation`; the rest of
+ * its meta is on the stream's `started` and `summary` lines (and `synced` for
+ * `retrieve --follow`).
+ */
+export interface StreamLineEnvelope<Data = unknown, Operation = unknown> {
+	ok: true;
+	data: Data;
+	warnings: readonly Warning[];
+	tips: readonly Tip[];
+	meta: { operation: Operation };
 }
 
 /** Normalize an optional warnings list to a readonly array. */

package/src/core/error-catalog.ts

@@ -55,11 +55,13 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "cdb/empty-group",
-		summary: "The named CDB group contains no records.",
+		summary:
+			"The named CDB group contains no records: a warning for a read, an error for a write-shaped fan-out.",
 	},
 	{
 		code: "cdb/empty-selection",
-		summary: "The target selection matched no CDB records.",
+		summary:
+			"The target selection matched no CDB records: a warning for a read, an error for a write-shaped fan-out.",
 	},
 	{
 		code: "cdb/file-exists",
@@ -262,6 +264,83 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary: "A received MNDP datagram could not be decoded.",
 	},
 
+	// cmr/* — `execute --cmr` (#450)
+	{
+		code: "cmr/cancelled",
+		summary:
+			"The operation was cancelled before the command was sent to a CMR client.",
+	},
+	{
+		code: "cmr/caller-policy-not-enforced",
+		summary:
+			"Warning: the controller login lacks a policy the CMR command runs with on the clients, and RouterOS does not check it.",
+	},
+	{
+		code: "cmr/client-script-not-validated",
+		summary:
+			"Warning: a caller-addressed `/cmr/device/run-script` was validated as a controller request; its script was not validated on the clients.",
+	},
+	{
+		code: "cmr/client-disconnected",
+		summary:
+			"CMR skipped a client that is not connected to its controller; the command was not sent.",
+	},
+	{
+		code: "cmr/empty-selection",
+		summary:
+			"The CMR selection matched no device on the controller: for `--cmr`, a warning for a read and an error for a write; for a fleet command such as `/cmr/vlan/add`, a warning.",
+	},
+	{
+		code: "cmr/membership-changed",
+		summary:
+			"A CMR client left the label selection or changed its key between validation and dispatch; the command was not sent.",
+	},
+	{
+		code: "cmr/not-a-controller",
+		summary:
+			"The target does not answer `/cmr/device`; it is not a CMR controller.",
+	},
+	{
+		code: "cmr/console-only",
+		summary:
+			"The CMR command is an interactive console view that breaks an API session, so centrs refused it before running it.",
+	},
+	{
+		code: "cmr/outcome-unknown",
+		summary:
+			"The command was sent to a CMR client but no final status came back; it may still be running.",
+	},
+	{
+		code: "cmr/output-truncated",
+		summary:
+			"Warning: CMR clipped a client's command output at its ~60 KiB cap.",
+	},
+	{
+		code: "cmr/policy-denied",
+		summary:
+			"A CMR client refused a statement because CMR scripts run without the policy it needs; earlier statements already ran.",
+	},
+	{
+		code: "cmr/rule-selects-every-device",
+		summary:
+			"Warning: a CMR rule command has no device `labels` (and, for VLAN, no `port-labels`), so the rule applies to every device, the controller included.",
+	},
+	{
+		code: "cmr/selection-includes-controller",
+		summary:
+			"Warning: a CMR fleet command selects the controller's own row as well as its clients.",
+	},
+	{
+		code: "cmr/selection-incomplete",
+		summary:
+			"The controller did not answer whether every device matches the labels, so nothing was run.",
+	},
+	{
+		code: "cmr/validation-incomplete",
+		summary:
+			"A CMR client's validation result was incomplete or clipped, so the command was not sent to it.",
+	},
+
 	// quickchr/*
 	{
 		code: "quickchr/package-unavailable",
@@ -533,6 +612,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "transport/unsupported-operation",
 		summary: "The chosen transport does not support this operation.",
 	},
+	{
+		code: "transport/write-outcome-unknown",
+		summary:
+			"Warning: a write failed after it was sent, so it may have run on the router; centrs did not retry it.",
+	},
 
 	// usage/*
 	{
@@ -544,6 +628,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/conflicting-flags",
 		summary: "Two or more supplied flags conflict.",
 	},
+	{
+		code: "usage/flag-after-separator",
+		summary:
+			"A centrs flag was written after `--`, where every token is RouterOS input.",
+	},
 	{
 		code: "usage/invalid-concurrency",
 		summary: "The --concurrency value must be an integer >= 1.",
@@ -567,6 +656,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "usage/invalid-method",
 		summary: "The -X/--method value is not a supported HTTP method.",
 	},
+	{
+		code: "usage/missing-labels",
+		summary: "`--cmr` was given without a `--labels` expression.",
+	},
 	{
 		code: "usage/missing-group",
 		summary: "The operation requires a non-empty --group value.",

package/src/core/execute-command.ts

@@ -101,7 +101,7 @@ export function canonicalizeExecuteCommand(
 
 export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
 	if (command.mode === "structured") {
-		if (FILE_OUTPUT_ATTRIBUTE in command.attributes) {
+		if (Object.keys(command.attributes).some(isFileOutputAttribute)) {
 			return true;
 		}
 		return !READ_ONLY_EXECUTE_VERBS.has(command.verb.toLowerCase());
@@ -110,21 +110,35 @@ export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
 }
 
 /**
- * The attribute that turns an otherwise read-only verb into a device write.
+ * The attributes that turn an otherwise read-only command into a device write.
  *
  * RouterOS routes command output to a file on the device when `file=` is
  * supplied, so a read verb creates a file: `/ip/address/export file=address`
  * writes `address.rsc`, and `/file/print file=test` writes `test.txt` (both
  * from the RouterOS manual — "Configuration Export" and "Scripting Tips and
  * Tricks", where that idiom is the documented way to create a file and needs
- * the script `write` policy). The verb allowlist cannot see that, so the
- * attribute is checked independently of it.
+ * the script `write` policy). `:serialize` spells it `file-name=` (its
+ * `/console/inspect` arguments, 7.13.5 through 7.26beta1). The verb and
+ * directive allowlists cannot see either, so they are checked independently.
  */
-const FILE_OUTPUT_ATTRIBUTE = "file";
+const FILE_OUTPUT_ATTRIBUTES: readonly string[] = ["file", "file-name"];
 
-/** True for a `file=<name>` token — the write-shaping output redirect. */
+/**
+ * RouterOS accepts argument prefixes (`fi=`, `file-n=`), including on
+ * `:serialize` (CHR 7.26beta1). An ambiguous prefix stays write-shaped too:
+ * only the device can disambiguate it, so the local gate fails closed.
+ */
+function isFileOutputAttribute(name: string): boolean {
+	return (
+		name.length > 0 &&
+		FILE_OUTPUT_ATTRIBUTES.some((full) => full.startsWith(name))
+	);
+}
+
+/** True for an output-file argument, including its abbreviated spellings. */
 function isFileOutputToken(token: string): boolean {
-	return token.startsWith(`${FILE_OUTPUT_ATTRIBUTE}=`);
+	const separator = token.indexOf("=");
+	return separator > 0 && isFileOutputAttribute(token.slice(0, separator));
 }
 
 /**
@@ -193,27 +207,59 @@ const WRITE_SHAPED_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
 /**
  * Script directives that are safe to run without device-write confirmation:
  * output, control flow and pure value functions, all members of `explain`'s
- * grounded root-cmd vocabulary (`ROOT_CMDS` in `src/explain/write.ts`). A
- * directive's `do={…}` or `[…]` body is its own command head and is checked on
- * its own. Deliberately absent: `:execute` and `:parse` (run built code),
- * `:global` and `:set` (outlive the script), and `:import`, `:password`,
- * `:undo`, `:redo` (configuration changes).
+ * grounded root-cmd vocabulary (`ROOT_CMDS` in `src/explain/write.ts`) and
+ * present on 7.26beta1. A directive's `do={…}` or `[…]` body is its own
+ * command head and is checked on its own. That holds because a script-typed
+ * argument (`:do command=`, `:if do=`, `:retry command=`, `:time`, `:onerror
+ * in=`) runs only a `{…}` block: RouterOS refuses a quoted string or a variable
+ * holding one there as an invalid value (CHR 7.24.5 and 7.26beta1, #458), so
+ * no body can hide in text the gate blanks. The value functions (#458) take
+ * only values; `:serialize` alone can write, through `file-name=` (it creates
+ * the file on 7.26beta1), which the file-output check catches.
+ *
+ * Deliberately absent: `:execute` and `:parse` (run built code), `:global` and
+ * `:set` (outlive the script), and `:import`, `:password`, `:undo`, `:redo`
+ * (configuration changes). A directive missing here costs `--yes`; one wrongly
+ * here bypasses the gate.
  */
 const READ_ONLY_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
 	":break",
 	":continue",
+	":convert",
+	":delay",
+	":deserialize",
 	":do",
 	":error",
+	":find",
 	":for",
 	":foreach",
 	":if",
+	":jobname",
 	":len",
 	":local",
+	":nothing",
 	":onerror",
 	":pick",
 	":put",
+	":range",
+	":retry",
 	":return",
+	":rndnum",
+	":rndstr",
+	":serialize",
+	":time",
+	":timestamp",
+	":toarray",
+	":tobool",
+	":tocrlf",
+	":toid",
+	":toip",
+	":toip6",
+	":tolf",
+	":tonsec",
+	":tonum",
 	":tostr",
+	":totime",
 	":typeof",
 	":while",
 ]);
@@ -249,7 +295,11 @@ function scriptContainsWriteShapedCommand(input: string): boolean {
 		// Every command the statement runs must be proven read-only, not just the
 		// first: `:foreach i in=[/ip address find] do={/user expire-password $i}`
 		// reads with `find` and writes with an unlearned mutator.
-		if (!commandHeads(statement).every(isReadOnlyCommand)) {
+		if (
+			!commandHeads(statement).every(
+				(head) => !head.spacedFileOutput && isReadOnlyCommand(head.words),
+			)
+		) {
 			return true;
 		}
 	}
@@ -264,12 +314,23 @@ function scriptContainsWriteShapedCommand(input: string): boolean {
  * expressions, not commands, so they do not start one. Each head reads only up
  * to the next opener, which begins its own head.
  */
-function commandHeads(statement: string): string[][] {
-	const heads: string[][] = [];
+function commandHeads(
+	statement: string,
+): { words: string[]; spacedFileOutput: boolean }[] {
+	const heads: { words: string[]; spacedFileOutput: boolean }[] = [];
 	const starts = [0];
+	// Match group ends once. Each command can then skip its nested bodies
+	// without walking them again; deeply nested reads stay linear in input size.
+	const closes = new Map<number, number>();
+	const open: number[] = [];
 	for (let index = 0; index < statement.length; index += 1) {
-		const char = statement[index];
+		const char = statement[index] ?? "";
 		if (char === "[" || char === "{") starts.push(index + 1);
+		if ("[{(".includes(char)) open.push(index);
+		else if ("]})".includes(char)) {
+			const start = open.pop();
+			if (start !== undefined) closes.set(start, index);
+		}
 	}
 	for (const start of starts) {
 		const nextOpener = statement.slice(start).search(/[[{(]/);
@@ -282,11 +343,58 @@ function commandHeads(statement: string): string[][] {
 		if (head === undefined) continue;
 		const words = commandWords(head, tokens.slice(1));
 		// A lone closer (`}` ending a multi-line block) runs nothing.
-		if (words.length > 0) heads.push(words);
+		if (words.length > 0)
+			heads.push({
+				words,
+				spacedFileOutput: hasSpacedFileOutput(statement, start, words, closes),
+			});
 	}
 	return heads;
 }
 
+/**
+ * RouterOS also accepts `file value` / `file-name value` without `=`. These
+ * belong to print/export/serialize, not a loop variable or a pure function's
+ * value. Read the command's own tokens, skipping nested expressions and
+ * blocks: `:serialize value=[:tostr file] file-n "out"` has one file argument
+ * after its nested read. Quoted text is already masked by the statement split.
+ * Grounded on CHR 7.26beta1, with export also checked on long-term.
+ */
+function hasSpacedFileOutput(
+	statement: string,
+	start: number,
+	words: readonly string[],
+	closes: ReadonlyMap<number, number>,
+): boolean {
+	let commandWords: number;
+	if (words[0] === ":serialize") {
+		commandWords = 1;
+	} else {
+		const depth = menuDepth(words);
+		if (words[depth] !== "print" && words[depth] !== "export") return false;
+		commandWords = depth + 1;
+	}
+	let own = "";
+	for (let index = start; index < statement.length; index += 1) {
+		const char = statement[index] ?? "";
+		if ("[{(".includes(char)) {
+			own += " ";
+			index = closes.get(index) ?? statement.length;
+		} else if ("]})".includes(char)) {
+			break;
+		} else own += char;
+	}
+	let consumed = 0;
+	for (const token of tokenizeRouterOsCli(own)) {
+		if (consumed < commandWords) {
+			consumed += token.split("/").filter(Boolean).length;
+			continue;
+		}
+		if (!token.includes("=") && isFileOutputAttribute(token)) return true;
+	}
+	return false;
+}
+
 /**
  * The path segments and verb of one command, from its head token and the bare
  * words after it. The space-separated spelling puts menu segments and the verb
@@ -299,6 +407,19 @@ function commandWords(head: string, following: readonly string[]): string[] {
 	const words: string[] = [];
 	const headWord = trimGroupingPunctuation(head);
 	if (headWord.startsWith(":")) return [headWord];
+	// `/serialize …` is the root command `:serialize`: at statement start the
+	// sigil is optional and `/` binds the root vocabulary (CHR 7.23.2, see
+	// `src/explain/symbols.ts`). Only the absolute one-segment form is read
+	// this way. A bare `delay` may be a relative menu command after earlier
+	// navigation, so it keeps the menu-verb rule and fails closed.
+	const root = /^\/([A-Za-z0-9-]+)$/.exec(headWord)?.[1]?.toLowerCase();
+	if (
+		root !== undefined &&
+		READ_ONLY_SCRIPT_DIRECTIVES.has(`:${root}`) &&
+		!isKnownMenuPath([root])
+	) {
+		return [`:${root}`];
+	}
 	words.push(...headWord.split("/").filter(Boolean));
 	if (headWord !== head) return words;
 	for (const token of following) {
@@ -325,12 +446,16 @@ function commandWords(head: string, following: readonly string[]): string[] {
 function isReadOnlyCommand(words: readonly string[]): boolean {
 	const head = words[0] ?? "";
 	if (head.startsWith(":")) return READ_ONLY_SCRIPT_DIRECTIVES.has(head);
+	const verb = words[menuDepth(words)];
+	return verb !== undefined && READ_ONLY_EXECUTE_VERBS.has(verb.toLowerCase());
+}
+
+function menuDepth(words: readonly string[]): number {
 	let depth = 0;
 	while (depth < words.length && isKnownMenuPath(words.slice(0, depth + 1))) {
 		depth += 1;
 	}
-	const verb = words[depth];
-	return verb !== undefined && READ_ONLY_EXECUTE_VERBS.has(verb.toLowerCase());
+	return depth;
 }
 
 function trimGroupingPunctuation(value: string): string {