@tikoci/centrs 0.1.3 → 0.1.6

package/src/core/preflight.ts

@@ -0,0 +1,306 @@
+/**
+ * Capability/version pre-flight for centrs-generated RouterOS commands (#129).
+ *
+ * centrs sometimes generates a command that assumes a device capability the
+ * device may lack (e.g. `transfer mkdir` → `/file add type=directory`, absent
+ * on older RouterOS). Without a pre-flight that surfaces as a raw protocol
+ * error; with one it becomes a typed `routeros/version-unsupported` error
+ * naming the versions that do support the operation. (Distinct from
+ * `routeros/unsupported-capability`, which is a *protocol*-side gap — the
+ * transport cannot carry the operation at all.)
+ *
+ * Design:
+ * - A {@link CapabilityRequirement} carries the supported
+ *   {@link RouterOsVersionRange} list as **data**. Ranges are inclusive-`min` /
+ *   exclusive-`maxExclusive`, so a backported feature is a list of per-release-
+ *   line minimums (e.g. `[{min:"7.21.4", maxExclusive:"7.22"}, {min:"7.22.2"}]`).
+ *   The grounding for each requirement (CHR run, rosetta changelog/command-diff)
+ *   lives at the requirement's definition site — this module only evaluates.
+ * - The device version comes from a {@link DeviceVersion}: a live read
+ *   ({@link probeDeviceVersion}), the CDB record's stored `version=` comment
+ *   fact ({@link versionFactFromComment} — stale-but-cheap, written by
+ *   `discover --save`/`devices --check`), or the caller.
+ * - An **unknown** version never blocks (crash-early: the device's own error
+ *   still surfaces through the RouterOS error mapping); only a version known to
+ *   be outside every supported range fails, via {@link assertCapability}.
+ *
+ * Version ordering is suffix-aware: `7.23beta1 < 7.23beta2 < 7.23rc1 < 7.23 <
+ * 7.23.1` (RouterOS version format `MAJOR.MINOR[.PATCH][beta|rc N]`). The
+ * comparator tolerates trailing channel/date noise (`"7.21.4 (long-term) …"`),
+ * matching what `/system/resource` reports. Promoted from the integration
+ * harness's `routerOsAtLeast` (`test/integration/chr.ts`), which now delegates
+ * here.
+ */
+
+import { CentrsError } from "../errors.ts";
+import type { ProtocolAdapter } from "../protocols/adapter.ts";
+import { parseRawCommentFacts } from "../resolver/comment-kv.ts";
+
+/** Parsed RouterOS version, ordered by the tuple (major, minor, patch, stage, stageIteration). */
+export interface RouterOsVersionParts {
+	major: number;
+	minor: number;
+	patch: number;
+	/** Prerelease stage rank: beta=0 < rc=1 < release=2. */
+	stageRank: 0 | 1 | 2;
+	/** Iteration within the stage (`beta2` → 2); 0 for a release. */
+	stageIteration: number;
+}
+
+/**
+ * Parse a RouterOS version out of a possibly-noisy string
+ * (`"7.21.4 (long-term) 2026-04-21"` → 7.21.4). Returns `undefined` when no
+ * `major.minor` shape is present.
+ */
+export function parseRouterOsVersion(
+	raw: string,
+): RouterOsVersionParts | undefined {
+	// Bounded digit runs ({1,4}) keep this linear on adversarial input — an
+	// unbounded `\d+` here is a polynomial-ReDoS vector on strings of many
+	// repeated digits (CodeQL js/polynomial-redos). RouterOS version numbers
+	// never approach four digits per field, so the bound is free.
+	//
+	// The `(?<![\d.])` / `(?!\d)` token boundaries keep the (unanchored) match
+	// from latching onto a *fragment* of a larger number: without them
+	// `"12345.67"` matched `"2345.67"` and `"127.0.0.1"` matched `"127.0"`.
+	// They still allow legitimately noisy strings ("7.23.2 (stable)", "v7.23").
+	const match = raw.match(
+		/(?<![\d.])(\d{1,4})\.(\d{1,4})(?:\.(\d{1,4}))?(?:(beta|rc)(\d{1,4}))?(?![\d.])/i,
+	);
+	if (!match) {
+		return undefined;
+	}
+	const stage = match[4]?.toLowerCase();
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3] ?? 0),
+		stageRank: stage === undefined ? 2 : stage === "rc" ? 1 : 0,
+		stageIteration: Number(match[5] ?? 0),
+	};
+}
+
+/**
+ * Compare two RouterOS version strings: negative when `a < b`, 0 when equal,
+ * positive when `a > b`. An unparseable version sorts below every parseable
+ * one (and equal to another unparseable one).
+ */
+export function compareRouterOsVersion(a: string, b: string): number {
+	const left = parseRouterOsVersion(a);
+	const right = parseRouterOsVersion(b);
+	if (left === undefined || right === undefined) {
+		return (left === undefined ? 0 : 1) - (right === undefined ? 0 : 1);
+	}
+	return (
+		left.major - right.major ||
+		left.minor - right.minor ||
+		left.patch - right.patch ||
+		left.stageRank - right.stageRank ||
+		left.stageIteration - right.stageIteration
+	);
+}
+
+/** True when `running` ≥ `target`. Unparseable `running` is never ≥ a parseable target. */
+export function routerOsVersionAtLeast(
+	running: string,
+	target: string,
+): boolean {
+	if (
+		parseRouterOsVersion(running) === undefined &&
+		parseRouterOsVersion(target) !== undefined
+	) {
+		return false;
+	}
+	return compareRouterOsVersion(running, target) >= 0;
+}
+
+/**
+ * One contiguous supported window. `min` is inclusive; `maxExclusive` bounds a
+ * backport window (omit it for "this version and everything after").
+ */
+export interface RouterOsVersionRange {
+	min: string;
+	maxExclusive?: string;
+}
+
+/**
+ * True when `version` falls inside `range`. A malformed range is a definition
+ * bug in a {@link CapabilityRequirement}, not a device condition, so it throws
+ * rather than failing open (an unparseable `min` would otherwise sort below
+ * every real version and mark everything supported).
+ */
+export function versionInRange(
+	version: string,
+	range: RouterOsVersionRange,
+): boolean {
+	if (parseRouterOsVersion(range.min) === undefined) {
+		throw new TypeError(
+			`Invalid capability range min ${JSON.stringify(range.min)}; ` +
+				"set CapabilityRequirement.supported[].min to a RouterOS major.minor[.patch] version.",
+		);
+	}
+	if (
+		range.maxExclusive !== undefined &&
+		(parseRouterOsVersion(range.maxExclusive) === undefined ||
+			compareRouterOsVersion(range.min, range.maxExclusive) >= 0)
+	) {
+		throw new TypeError(
+			`Invalid capability range maxExclusive ${JSON.stringify(range.maxExclusive)}; ` +
+				"set CapabilityRequirement.supported[].maxExclusive to a RouterOS version greater than min.",
+		);
+	}
+	if (!routerOsVersionAtLeast(version, range.min)) {
+		return false;
+	}
+	return (
+		range.maxExclusive === undefined ||
+		compareRouterOsVersion(version, range.maxExclusive) < 0
+	);
+}
+
+/**
+ * A capability a centrs-generated command depends on, with the version windows
+ * where RouterOS provides it. Define these next to the consumer (e.g. the
+ * transfer spec owns the `mkdir` requirement) and document the grounding
+ * evidence there.
+ */
+export interface CapabilityRequirement {
+	/** Stable slug for error context, e.g. `file-add-directory`. */
+	capability: string;
+	/** Human phrase for the operation, e.g. "create directories with `/file add type=directory`". */
+	summary: string;
+	/** Windows where the capability exists; supported when ANY range matches. */
+	supported: readonly RouterOsVersionRange[];
+	/** Extra guidance appended to the typed error's remediation. */
+	remediation?: string;
+}
+
+/** Where a pre-flighted device version came from (error context + envelope provenance). */
+export type DeviceVersionSource = "live" | "cdb-fact" | "caller";
+
+/** A device version paired with its provenance. */
+export interface DeviceVersion {
+	version: string;
+	source: DeviceVersionSource;
+}
+
+export type PreflightState = "supported" | "unsupported" | "unknown";
+
+/** Outcome of a capability pre-flight. */
+export interface PreflightVerdict {
+	state: PreflightState;
+	/** Echo of the checked device version, when one was available. */
+	device?: DeviceVersion;
+}
+
+/**
+ * Evaluate a requirement against a device version. `unknown` when no version
+ * is available or it does not parse — callers proceed on `unknown` (the device
+ * still reports its own error, mapped by the RouterOS error vocabulary).
+ */
+export function checkCapability(
+	requirement: CapabilityRequirement,
+	device?: DeviceVersion,
+): PreflightVerdict {
+	if (
+		device === undefined ||
+		parseRouterOsVersion(device.version) === undefined
+	) {
+		return { state: "unknown" };
+	}
+	const supported = requirement.supported.some((range) =>
+		versionInRange(device.version, range),
+	);
+	return { state: supported ? "supported" : "unsupported", device };
+}
+
+/** Render supported windows for humans: `7.21.4–7.22 (excl.), 7.22.2+`. */
+export function renderSupportedRanges(
+	ranges: readonly RouterOsVersionRange[],
+): string {
+	return ranges
+		.map((range) =>
+			range.maxExclusive === undefined
+				? `${range.min}+`
+				: `${range.min}–${range.maxExclusive} (excl.)`,
+		)
+		.join(", ");
+}
+
+/**
+ * Pre-flight gate: throw a typed `routeros/version-unsupported` error when
+ * the device version is known and outside every supported window; otherwise
+ * return the verdict (`unknown` passes — see {@link checkCapability}).
+ */
+export function assertCapability(
+	requirement: CapabilityRequirement,
+	device?: DeviceVersion,
+): PreflightVerdict {
+	const verdict = checkCapability(requirement, device);
+	if (verdict.state !== "unsupported" || verdict.device === undefined) {
+		return verdict;
+	}
+	const supported = renderSupportedRanges(requirement.supported);
+	throw new CentrsError({
+		code: "routeros/version-unsupported",
+		summary: `RouterOS ${verdict.device.version} cannot ${requirement.summary}; it needs ${supported}.`,
+		remediation:
+			(requirement.remediation ? `${requirement.remediation} ` : "") +
+			(verdict.device.source === "cdb-fact"
+				? "The version came from the stored CDB `version=` fact and may be stale; upgrade RouterOS, or refresh the fact if the device was already upgraded."
+				: "Upgrade RouterOS to a supported version."),
+		context: {
+			capability: requirement.capability,
+			version: verdict.device.version,
+			versionSource: verdict.device.source,
+			supported: requirement.supported.map((range) => ({ ...range })),
+		},
+	});
+}
+
+/**
+ * Read a stored device version from a CDB record's comment kv-soup (`version=`
+ * — the derived fact `discover --save` and `devices --check` write). Stale by
+ * nature; provenance is `cdb-fact`.
+ */
+export function versionFactFromComment(
+	comment: string,
+): DeviceVersion | undefined {
+	const version = parseRawCommentFacts(comment)["version"];
+	if (version === undefined || parseRouterOsVersion(version) === undefined) {
+		return undefined;
+	}
+	return { version, source: "cdb-fact" };
+}
+
+/**
+ * Live device-version probe over an already-built adapter. Structured
+ * transports read `/system/resource`; console transports (ssh/mac-telnet) run
+ * `:put [/system/resource/ get version]`. Transport/auth errors propagate —
+ * only a well-formed reply that simply lacks a version yields `undefined`.
+ */
+export async function probeDeviceVersion(
+	adapter: ProtocolAdapter,
+): Promise<DeviceVersion | undefined> {
+	if (adapter.capabilities.retrieve) {
+		const resource = await adapter.getSingleton("/system/resource");
+		const version =
+			typeof resource === "object" && resource !== null
+				? (resource as Record<string, unknown>)["version"]
+				: undefined;
+		if (typeof version === "string" && parseRouterOsVersion(version)) {
+			return { version, source: "live" };
+		}
+		return undefined;
+	}
+	const result = await adapter.execute({
+		path: "/system/resource",
+		command: "print",
+		script: ":put [/system/resource/ get version]",
+	});
+	const version = result.ret?.trim();
+	if (version && parseRouterOsVersion(version)) {
+		return { version, source: "live" };
+	}
+	return undefined;
+}

package/src/core/routeros-string.ts

@@ -0,0 +1,24 @@
+/**
+ * Quote RouterOS command text as one double-quoted string literal.
+ *
+ * `$` is load-bearing here: RouterOS expands variables inside double quotes,
+ * so leaving it bare changes the bytes seen by wrappers such as
+ * `:put [:parse "<input>"]` before the parser receives them.
+ * Control whitespace (`\t`/`\r`/`\n`) is escaped so the decoded string
+ * carries the caller's original bytes. This is defensive: RouterOS 7.20
+ * changelog says "replace TAB characters with spaces when editing scripts
+ * and added `tab-width` in `/console/settings`" — version-gated (absent
+ * before 7.20), width-configurable via `tab-width`, and scoped to the
+ * script editor, not grounded as string-literal expansion (see #276).
+ * Escaping preserves the caller's bytes whether the device expands or
+ * preserves a raw tab.
+ */
+export function routerOsStringLiteral(value: string): string {
+	return `"${value
+		.replaceAll("\\", "\\\\")
+		.replaceAll('"', '\\"')
+		.replaceAll("$", "\\$")
+		.replaceAll("\t", "\\t")
+		.replaceAll("\r", "\\r")
+		.replaceAll("\n", "\\n")}"`;
+}

package/src/core/version.ts

@@ -0,0 +1,4 @@
+import packageMetadata from "../../package.json" with { type: "json" };
+
+/** Package version reported by every frontend and the root library surface. */
+export const centrsVersion = packageMetadata.version;

package/src/core/yaml.ts

@@ -0,0 +1,86 @@
+/**
+ * Envelope YAML rendering — the `--format yaml` writer shared by every command.
+ *
+ * This is a **renderer, not a YAML library**: it serializes the envelope shapes
+ * centrs builds (scalars, arrays, plain objects) and quotes every string through
+ * `JSON.stringify`, which is valid YAML double-quoted scalar syntax. It does not
+ * parse YAML, emit anchors/aliases, or handle cycles.
+ *
+ * It lives in `src/core/` because it is **pure** — no Bun, filesystem, network,
+ * or CDB reach. `retrieve.ts` used to own it, which put every consumer of
+ * `toYaml` one import away from the transport stack; `explain`'s offline entry
+ * runs in a browser only because this function no longer drags that graph
+ * behind it (#312). Every importer now takes `toYaml` from here; `retrieve.ts`
+ * is one of them, and the function itself moved character for character.
+ */
+
+/**
+ * Render `value` as YAML at `indent` spaces of nesting.
+ *
+ * `undefined` object entries are dropped (they have no YAML spelling and the
+ * envelope uses them for absent-optional); `undefined` in scalar position and
+ * `null` both render `null`. A non-plain object that is neither array nor
+ * scalar falls back to its JSON text as a quoted scalar rather than guessing.
+ */
+export function toYaml(value: unknown, indent = 0): string {
+	const prefix = " ".repeat(indent);
+	if (value === null || value === undefined) {
+		return "null";
+	}
+	if (typeof value === "string") {
+		return yamlScalar(value);
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		return String(value);
+	}
+	if (Array.isArray(value)) {
+		if (value.length === 0) {
+			return `${prefix}[]`;
+		}
+		return value
+			.map((item) => {
+				if (isScalar(item)) {
+					return `${prefix}- ${toYaml(item, indent + 2)}`;
+				}
+				return `${prefix}-\n${toYaml(item, indent + 2)}`;
+			})
+			.join("\n");
+	}
+	if (isPlainObject(value)) {
+		const entries = Object.entries(value).filter(
+			([, entryValue]) => entryValue !== undefined,
+		);
+		if (entries.length === 0) {
+			return `${prefix}{}`;
+		}
+		return entries
+			.map(([key, entryValue]) => {
+				if (isScalar(entryValue)) {
+					return `${prefix}${key}: ${toYaml(entryValue, indent + 2)}`;
+				}
+				return `${prefix}${key}:\n${toYaml(entryValue, indent + 2)}`;
+			})
+			.join("\n");
+	}
+	return yamlScalar(JSON.stringify(value));
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isScalar(value: unknown): value is boolean | number | string | null {
+	return (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	);
+}
+
+function yamlScalar(value: string): string {
+	if (value.length === 0) {
+		return '""';
+	}
+	return JSON.stringify(value);
+}

package/src/errors.ts

@@ -13,6 +13,7 @@ export type CentrsErrorCode =
 	| `input/${string}`
 	| `internal/${string}`
 	| `mndp/${string}`
+	| `quickchr/${string}`
 	| `routeros/${string}`
 	| `settings/${string}`
 	| `target/${string}`

package/src/execute-fanout.ts

@@ -9,7 +9,7 @@
  *
  * Boundaries (see `commands/execute/README.md`, `docs/CONSTITUTION.md`), shared
  * with `api-fanout.ts` / `retrieve-fanout.ts`:
- *   - The CDB is loaded ONCE (`expandCdbSelection`); a cdb member is resolved with
+ *   - The CDB is loaded ONCE (`expandSelection`); a cdb member is resolved with
  *     its pre-resolved record, so `resolveCdb`'s `__default__` synthetic fallback
  *     never collides ad-hoc literals.
  *   - A `--default` / `__default__` member is guarded from being dialed as the
@@ -26,6 +26,7 @@ import type {
 	CommonSettingsMeta,
 	FanoutData,
 	FanoutSummary,
+	ValidationTrace,
 } from "./core/envelope.ts";
 import {
 	buildFanoutEnvelope,
@@ -36,6 +37,7 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	buildExecuteErrorEnvelopeFromResolved,
@@ -52,15 +54,14 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 /** Compact description of the selector that produced the fan-out. */
 export interface ExecuteSelectionSummary {
@@ -69,6 +70,8 @@ export interface ExecuteSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface ExecuteFanoutOperationMeta {
@@ -91,10 +94,10 @@ export type ExecuteFanoutErrorEnvelope =
 export interface ExecuteFanoutInternals {
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	execute?: (
 		resolved: ResolvedExecuteRequest,
 	) => Promise<ExecuteSuccessEnvelope>;
@@ -116,6 +119,7 @@ function summarizeSelection(
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
@@ -124,7 +128,7 @@ function fanoutVia(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	globalVia: RouterOsProtocol,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): RouterOsProtocol {
 	// Deliberately CLI/env only, not `config` — see the identical note in
 	// `retrieve-fanout.ts`'s `resolveFanoutConcurrencyProtocol`.
@@ -139,7 +143,7 @@ function fanoutVia(
 	return anyNative ? "native-api" : globalVia;
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -151,6 +155,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -163,7 +170,7 @@ function memberTargetMeta(member: CdbSelectionMember): {
  */
 function relabelAdhocMember(
 	envelope: ExecuteEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): ExecuteEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -195,7 +202,7 @@ export async function executeFanout(
 	const global = resolveExecuteGlobalContext(request, env, config);
 	const selectionSummary = summarizeSelection(selection);
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -227,10 +234,15 @@ export async function executeFanout(
 	await assertFanoutWriteConfirmed(request, global.summary, expansion);
 
 	const execute = internals.execute ?? runResolvedExecute;
+	// Per-target validation trace. `execute` and `onExecuteError` are separate
+	// callbacks that share only the resolved request, so the request object is
+	// the key: without it a per-target error envelope would reconstruct
+	// `meta.validation` instead of reporting the gate that actually ran (GH#354).
+	const traces = new WeakMap<ResolvedExecuteRequest, ValidationTrace>();
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
-		CdbSelectionMember,
+		SelectionMember,
 		ResolvedExecuteRequest,
 		ExecuteEnvelope
 	>({
@@ -254,6 +266,15 @@ export async function executeFanout(
 					{ cdbResolution: member.resolution, config },
 				);
 			}
+			if (member.kind === "quickchr") {
+				// The live descriptor resolves here, per member — a stopped/unknown
+				// machine is an inner per-target failure, not an expansion error.
+				return resolveExecuteRequest(
+					{ ...request, targetInput: undefined, quickchr: member.name },
+					env,
+					{ config },
+				);
+			}
 			return resolveExecuteRequest(
 				{ ...request, targetInput: member.input },
 				env,
@@ -267,11 +288,19 @@ export async function executeFanout(
 				warnings: member.kind === "cdb" ? [...member.resolution.warnings] : [],
 				summary: "Failed to resolve a fanout target.",
 			}),
-		execute: async (resolved, member) =>
-			relabelAdhocMember(await execute(resolved), member),
+		execute: async (resolved, member) => {
+			const trace: ValidationTrace = {};
+			traces.set(resolved, trace);
+			return relabelAdhocMember(await execute(resolved, trace), member);
+		},
 		onExecuteError: (resolved, member, error) =>
 			relabelAdhocMember(
-				buildExecuteErrorEnvelopeFromResolved(resolved, error),
+				buildExecuteErrorEnvelopeFromResolved(
+					resolved,
+					error,
+					undefined,
+					traces.get(resolved),
+				),
 				member,
 			),
 		sleep,
@@ -292,7 +321,7 @@ export async function executeFanout(
 async function assertFanoutWriteConfirmed(
 	request: ExecuteRequest,
 	summary: ExecuteRequestSummary,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): Promise<void> {
 	if (!summary.write || request.yes) {
 		return;
@@ -323,7 +352,7 @@ interface ExecuteFanoutEnvelopeInput {
 	requestSummary: ExecuteRequestSummary;
 	settings: CommonSettingsMeta;
 	via: RouterOsProtocol | null;
-	warnings: CdbSelectionExpansion["warnings"];
+	warnings: SelectionExpansion["warnings"];
 	targets: readonly ExecuteEnvelope[];
 }