@tikoci/centrs 0.1.4 → 0.1.6

package/src/index.ts

@@ -1,5 +1,3 @@
-export const centrsVersion = "0.1.0";
-
 export {
 	type ApiEnvelope,
 	type ApiErrorEnvelope,
@@ -81,6 +79,7 @@ export {
 	type EnvelopeMeta,
 	type EnvelopeTargetMeta,
 	type EnvelopeValidationMeta,
+	type EnvelopeValidationStage,
 	type FanoutData,
 	type FanoutSummary,
 	normalizeWarnings,
@@ -110,6 +109,7 @@ export {
 	type InspectChildItem,
 	type InspectCompletionItem,
 	type InspectRequestKind,
+	inspectArgumentNames,
 	inspectChildren,
 	inspectChildrenOrEmpty,
 	inspectCompletions,
@@ -136,6 +136,7 @@ export {
 	versionFactFromComment,
 	versionInRange,
 } from "./core/preflight.ts";
+export { centrsVersion } from "./core/version.ts";
 export {
 	encodeMndpPacket,
 	MNDP_BROADCAST_ADDRESS,
@@ -305,13 +306,20 @@ export {
 // relative to the statement it was handed; the `Token` is that rebased into
 // document space by `explainCommand`. A consumer reading `explainCommand`'s
 // result wants the latter.
+//
+// `lexExplainArgumentTokens` is the skip-tolerant reading (#316) and is
+// exported for the same reason `lexExplainValueAnchors` is: a consumer building
+// its own token-level rule needs the reading a rule wants, not the one a
+// renderer wants. Its `undecided` tokens carry no `value` and never become one.
 export {
 	type Argument as ExplainArgument,
 	type ArgumentKind as ExplainArgumentKind,
 	type ArgumentReading as ExplainArgumentReading,
 	type ArgumentsRead as ExplainArgumentsRead,
 	type ArgumentsUnread as ExplainArgumentsUnread,
+	type ArgumentTokenReading as ExplainArgumentTokenReading,
 	lexArguments as lexExplainArguments,
+	lexArgumentTokens as lexExplainArgumentTokens,
 	lexValueAnchors as lexExplainValueAnchors,
 	type ValueAnchor as ExplainValueAnchor,
 	type ValueAnchorKind as ExplainValueAnchorKind,
@@ -478,6 +486,14 @@ export {
 	explainOutputFormats,
 	renderExplainEnvelope,
 } from "./explain.ts";
+export {
+	assertOfflineSyntax,
+	isOfflineGateRejection,
+	OFFLINE_GATE_SOURCE,
+	type OfflineGateFinding,
+	type OfflineGateResult,
+	type ValidationStageName,
+} from "./offline-gate.ts";
 export {
 	type ApiVerb,
 	createProtocolAdapter,
@@ -672,6 +688,7 @@ export {
 	transferFanout,
 } from "./transfer-fanout.ts";
 
+import { centrsVersion } from "./core/version.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 
 export const plannedSurfaces = ["api", "cli", "tui", "mcp", "proxy"] as const;

package/src/mcp/server.ts

@@ -10,6 +10,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { centrsVersion } from "../core/version.ts";
 import { type CentrsMcpConfig, resolveMcpConfig } from "./config.ts";
 import {
 	buildDevicesResource,
@@ -79,7 +80,7 @@ export function createCentrsMcpServer(
 	config: CentrsMcpConfig = resolveMcpConfig(),
 ): McpServer {
 	const server = new McpServer(
-		{ name: "centrs-mcp", version: "0.1.0" },
+		{ name: "centrs-mcp", version: centrsVersion },
 		{ instructions: SERVER_INSTRUCTIONS },
 	);
 

package/src/offline-gate.ts

@@ -0,0 +1,148 @@
+/**
+ * Stage 1 of the validation gate: the offline analyzer in front of the device
+ * preflight (GH#354).
+ *
+ * centrs used to run two validators that did not know about each other — the
+ * device preflight (`:put [:parse …]` plus `/console/inspect request=child`)
+ * that `execute` / `api` / `validate` share, and offline `explain`, which is
+ * byte-accurate and corpus-gated but took no part in validation at all. This
+ * module is the seam that joins them: every CLI-shaped input is analyzed here
+ * first, with no connection, and only then handed to the device stage.
+ *
+ * Three things that buys, in the order they matter:
+ *
+ * 1. A syntax fault is rejected with a **byte span** and **no round trip** — the
+ *    protocol adapter is never even constructed.
+ * 2. The device stage narrows to the semantic half it is actually needed for
+ *    (`:parse` is name-level only; `/console/inspect` owns the attribute set).
+ * 3. Where the device probe is unsafe or unavailable — the 7.12.2 class of
+ *    problem in GH#343 — the gate degrades to a real gate instead of to nothing.
+ *
+ * **A clean offline pass is necessary, never sufficient.** `explain` publishes
+ * `runtimeAcceptance: "not-proven"` for a reason: `/console/inspect` accepts
+ * forms the runtime rejects, and the analyzer has no per-menu schema (decision 3
+ * — no offline schema snapshot). The device stage is not optional and this
+ * module never reports success on its behalf. `verdict: "warn"` is an
+ * ABSTENTION, not a rejection, and passes through for the same reason.
+ *
+ * `--validate=false` disables BOTH stages — one flag, one meaning. That was
+ * settled with the `--raw` precedence layer on GH#154 and is why callers gate
+ * this on the same resolved `validate` setting as the device stage; the escape
+ * hatch has to cover a stage-1 defect too (GH#355 is a live example of the
+ * analyzer being wrong in the other direction).
+ *
+ * The offending byte range rides `context.span`, never {@link CentrsError}'s
+ * `position`. `RouterOsErrorPosition` is documented as RouterOS's own
+ * authoritative 1-based byte column, "carried verbatim; never re-derived"
+ * (`errors.ts`) — synthesizing one from offline analysis would make a
+ * centrs-derived offset indistinguishable from a device-reported one.
+ */
+
+import { CentrsError } from "./errors.ts";
+import { type ExplainDiagnostic, explainCommand } from "./explain.ts";
+
+/** Validator identity for `meta.validation` and error context. */
+export const OFFLINE_GATE_SOURCE = "offline explain (canonicalizer)";
+
+/** Which stage of the two-stage gate produced a verdict. */
+export type ValidationStageName = "offline" | "device";
+
+/** One rejected span, flattened out of {@link ExplainDiagnostic} for the error context. */
+export interface OfflineGateFinding {
+	/** The `explain/<analyzer>/<slug>` diagnostic code. */
+	code: string;
+	message: string;
+	/** Byte offsets into the analyzed input, end-exclusive. */
+	start: number;
+	end: number;
+}
+
+/** Outcome of a stage-1 run that did not reject. */
+export interface OfflineGateResult {
+	/**
+	 * `pass` — the analyzer read the whole input. `warn` — it ABSTAINED on part
+	 * of it (an unresolved menu, say). Both proceed to the device stage; only
+	 * `fail` throws.
+	 */
+	verdict: "pass" | "warn";
+	/** Warning-severity diagnostics, kept so a caller can surface the abstention. */
+	warnings: readonly OfflineGateFinding[];
+}
+
+function findingOf(diagnostic: ExplainDiagnostic): OfflineGateFinding {
+	return {
+		code: diagnostic.code,
+		message: diagnostic.message,
+		start: diagnostic.span.start,
+		end: diagnostic.span.end,
+	};
+}
+
+/**
+ * Run the offline stage over a RouterOS CLI string.
+ *
+ * Throws `validation/syntax` when the analyzer rejects the input; returns the
+ * verdict otherwise. Never opens a connection and never throws for any other
+ * reason — `explainCommand` itself is documented as total.
+ *
+ * `surface` names the caller in the error context (`execute`, `api /execute`) so
+ * a reader can tell which command's gate spoke; `via` is the resolved protocol
+ * when the caller has one, purely for context.
+ */
+export function assertOfflineSyntax(
+	command: string,
+	options: { surface: string; via?: string },
+): OfflineGateResult {
+	const analysis = explainCommand(command);
+	const errors = analysis.diagnostics.filter(
+		(diagnostic) => diagnostic.severity === "error",
+	);
+	const warnings = analysis.diagnostics
+		.filter((diagnostic) => diagnostic.severity === "warning")
+		.map(findingOf);
+
+	if (analysis.verdict !== "fail") {
+		return { verdict: analysis.verdict === "warn" ? "warn" : "pass", warnings };
+	}
+
+	// A `fail` verdict always carries at least one error diagnostic, but read it
+	// defensively: an empty list would otherwise produce an error that says
+	// nothing about what was wrong, which is worse than a generic summary.
+	const findings = errors.map(findingOf);
+	const first = findings[0];
+	throw new CentrsError({
+		code: "validation/syntax",
+		summary: first
+			? `RouterOS syntax rejected by offline analysis: ${first.message}`
+			: "RouterOS syntax rejected by offline analysis.",
+		remediation:
+			"Run `centrs explain '<command>'` to see the offending bytes in context, " +
+			"fix the syntax, then retry. `--validate=false` bypasses both validation " +
+			"stages if you are deliberately probing a RouterOS edge centrs reads wrong.",
+		context: {
+			command,
+			validationStage: "offline" satisfies ValidationStageName,
+			validationSource: OFFLINE_GATE_SOURCE,
+			surface: options.surface,
+			...(options.via ? { via: options.via } : {}),
+			...(first ? { span: { start: first.start, end: first.end } } : {}),
+			diagnostics: findings,
+		},
+		causeData: first?.code ?? "offline analysis rejected the input",
+	});
+}
+
+/**
+ * True when `error` is the rejection {@link assertOfflineSyntax} throws.
+ *
+ * Callers use this to build honest envelope metadata: on a stage-1 rejection the
+ * device stage did not run, and no connection was opened, so the meta must not
+ * claim `:parse` or `/console/inspect` failed.
+ */
+export function isOfflineGateRejection(error: unknown): boolean {
+	return (
+		error instanceof CentrsError &&
+		error.code === "validation/syntax" &&
+		(error.context?.["validationStage"] as string | undefined) === "offline"
+	);
+}

package/src/retrieve-fanout.ts

@@ -46,6 +46,7 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
@@ -71,7 +72,6 @@ import {
 	resolveRetrieveGlobalContext,
 	resolveRetrieveRequest,
 	runResolvedRetrieve,
-	toYaml,
 	validateRetrieveRequestShape,
 } from "./retrieve.ts";
 

package/src/retrieve.ts

@@ -15,6 +15,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -1192,62 +1193,3 @@ function exhaustiveOutputFormat(value: never): never {
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-
-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 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/settings.ts

@@ -24,6 +24,7 @@ import type {
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
+import { toYaml } from "./core/yaml.ts";
 import { loadCdb, resolveDevicesSettings } from "./devices.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
@@ -37,7 +38,7 @@ import {
 	readSettingsFileRaw,
 	resolveOptionalIntegerSetting,
 } from "./resolver/index.ts";
-import { retrieveOutputFormats, toYaml } from "./retrieve.ts";
+import { retrieveOutputFormats } from "./retrieve.ts";
 
 // ── Envelope shape ───────────────────────────────────────────────────────────
 

package/src/transfer-fanout.ts

@@ -38,6 +38,7 @@ import {
 	runFanout,
 	summarizeFanout,
 } from "./core/fanout.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
@@ -50,7 +51,6 @@ import {
 	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 import {
 	buildTransferErrorEnvelope,
 	isTransferWriteVerb,

package/src/transfer.ts

@@ -29,6 +29,7 @@ import type {
 	EnvelopeValidationMeta,
 	Warning,
 } from "./core/envelope.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -54,7 +55,6 @@ import {
 	resolveTarget,
 	toCoreSource,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 export const transferOutputFormats = ["text", "json", "yaml"] as const;
 export type TransferOutputFormat = (typeof transferOutputFormats)[number];