@tikoci/centrs 0.1.2 → 0.1.4

package/src/core/fanout.ts

@@ -11,9 +11,18 @@
  * and counting.
  */
 
-import { CentrsError } from "../errors.ts";
+import { CentrsError, serializeCentrsError } from "../errors.ts";
 import type { RouterOsProtocol } from "../protocols/index.ts";
-import type { FanoutSummary } from "./envelope.ts";
+import type {
+	CentrsEnvelope,
+	CentrsErrorEnvelope,
+	CentrsSuccessEnvelope,
+	CommonSettingsMeta,
+	EnvelopeTargetMeta,
+	FanoutData,
+	FanoutSummary,
+	Warning,
+} from "./envelope.ts";
 
 /** Transport-aware default worker-pool size (REST drops parallel POSTs above ~8). */
 export const FANOUT_CONCURRENCY_DEFAULTS: Record<
@@ -158,3 +167,135 @@ export function fanoutBackoffMs(attempt: number): number {
 export function defaultFanoutSleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/**
+ * The per-command fan-out loop, generic over the selection member, the resolved
+ * per-target plan, and the inner envelope type. Mirrors the original
+ * `retrieveGroup` worker exactly: resolve each member (a resolve failure becomes
+ * an inner error envelope, never a throw out of the batch); run the resolved
+ * request through {@link runWithRetry} (a retryable transient drop is retried,
+ * everything else recovers to an inner error envelope). Results are returned in
+ * input (record-index) order via {@link runBoundedPool}.
+ */
+export async function runFanout<Member, Resolved, Env>(opts: {
+	members: readonly Member[];
+	concurrency: number;
+	resolve: (member: Member) => Promise<Resolved> | Resolved;
+	onResolveError: (member: Member, error: unknown) => Env;
+	execute: (resolved: Resolved, member: Member) => Promise<Env>;
+	onExecuteError: (resolved: Resolved, member: Member, error: unknown) => Env;
+	sleep?: (ms: number) => Promise<void>;
+}): Promise<Env[]> {
+	return runBoundedPool(opts.members, opts.concurrency, async (member) => {
+		let resolved: Resolved;
+		try {
+			resolved = await opts.resolve(member);
+		} catch (error) {
+			return opts.onResolveError(member, error);
+		}
+		return runWithRetry<Env>(
+			() => opts.execute(resolved, member),
+			(error) => opts.onExecuteError(resolved, member, error),
+			{ sleep: opts.sleep },
+		);
+	});
+}
+
+/**
+ * The uniform fan-out process exit code (granular 0/2/1; see
+ * `docs/CONSTITUTION.md`, Target selection). `0` = every target ok (or an empty
+ * selection); `2` = partial (some ok, some failed); `1` = orchestration error
+ * (outer `ok: false`) OR every target failed. Decoupled from the envelope's
+ * outer `ok`, which only reports orchestration success.
+ */
+export function fanoutExitCode(envelope: {
+	ok: boolean;
+	data?: { summary?: FanoutSummary };
+}): 0 | 1 | 2 {
+	if (!envelope.ok) {
+		return 1;
+	}
+	const summary = envelope.data?.summary;
+	if (!summary || summary.total === 0 || summary.failed === 0) {
+		return 0;
+	}
+	if (summary.ok === 0) {
+		return 1;
+	}
+	return 2;
+}
+
+/** Collapse per-target `via` to one value, or `null` when targets disagree. */
+export function commonVia(
+	targets: readonly { meta: { via: RouterOsProtocol | null } }[],
+): RouterOsProtocol | null {
+	let via: RouterOsProtocol | null | undefined;
+	for (const target of targets) {
+		const candidate = target.meta.via;
+		if (via === undefined) {
+			via = candidate;
+		} else if (via !== candidate) {
+			return null;
+		}
+	}
+	return via ?? null;
+}
+
+/**
+ * Assemble the locked fan-out success envelope: `data = { summary, targets }`,
+ * outer `ok: true` = orchestration succeeded. The command owns its outer
+ * `operation` meta shape and passes it in.
+ */
+export function buildFanoutEnvelope<Data, Op, OuterOp>(input: {
+	summary: FanoutSummary;
+	targets: readonly CentrsEnvelope<Data, Op>[];
+	warnings: readonly Warning[];
+	settings: CommonSettingsMeta;
+	via: RouterOsProtocol | null;
+	operation: OuterOp;
+}): CentrsSuccessEnvelope<FanoutData<Data, Op>, OuterOp> {
+	return {
+		ok: true,
+		data: { summary: input.summary, targets: input.targets },
+		warnings: input.warnings,
+		tips: [],
+		meta: {
+			target: {},
+			via: input.via,
+			settings: input.settings,
+			operation: input.operation,
+		},
+	};
+}
+
+/**
+ * Build an INNER per-target error envelope for a member that failed to resolve
+ * (before any transport attempt). Carries the member's target meta so the
+ * fan-out output identifies which device failed.
+ */
+export function buildFanoutResolveFailure<Op = unknown>(input: {
+	error: unknown;
+	target: EnvelopeTargetMeta;
+	warnings?: readonly Warning[];
+	summary?: string;
+}): CentrsErrorEnvelope<Op> {
+	const centrsError =
+		input.error instanceof CentrsError
+			? input.error
+			: new CentrsError({
+					code: "internal/unhandled",
+					summary: input.summary ?? "Failed to resolve a fanout target.",
+					cause: input.error,
+				});
+	return {
+		ok: false,
+		error: serializeCentrsError(centrsError),
+		warnings: input.warnings ?? [],
+		tips: [],
+		meta: {
+			target: input.target,
+			via: null,
+			settings: {},
+		},
+	};
+}

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")}"`;
+}