@tikoci/centrs 0.1.4 → 0.1.6

package/src/core/execute-command.ts

@@ -0,0 +1,148 @@
+/**
+ * The **script-vs-structured execution gate** and its canonical command shape.
+ *
+ * `execute.ts` owned this pair, which put every consumer of the gate — the MCP
+ * tool surface and `explain`'s offline analysis among them — one import away
+ * from the transport stack (`mac-telnet` -> `node:dgram`, `native-api` ->
+ * `node:crypto`). The functions themselves are pure string work, so they live in
+ * `src/core/` and `execute.ts` re-exports them: the public API, the locked
+ * contract table in `test/unit/execute-canonicalize-contract.test.ts`, and the
+ * gate's behavior are all unchanged by the move (#312).
+ *
+ * Nothing here reads settings, the filesystem, CDB, or a device. Changing that
+ * re-couples `explain`'s browser entry to the transport graph.
+ */
+
+export interface CanonicalExecuteCommand {
+	mode: "structured" | "script";
+	input: string;
+	path: string;
+	verb: string;
+	attributes: Record<string, string>;
+	queries: string[];
+}
+
+/**
+ * The **script-vs-structured execution gate** — centrs's load-bearing
+ * discriminator (with {@link isWriteShaped}) for which validation runs and
+ * whether the write-confirmation prompt fires. centrs owns this gate; the shared,
+ * prose-tolerant, multi-command canonicalizer that `rosetta` / `lsp-routeros-ts`
+ * publish is for *canonicalization*, never the structured-mode predicate —
+ * widening what counts as `structured` is a product regression. Behavior is
+ * pinned by `test/unit/execute-canonicalize-contract.test.ts`.
+ *
+ * centrs deliberately does **not** vendor the shared parser yet. Preconditions
+ * for adopting it: (1) that contract stays green (no gate widening); (2) the
+ * vendored file is clean under centrs's strict `tsconfig` (or explicitly
+ * quarantined with justification); (3) `lsp-routeros-ts` also vendors/consumes
+ * the same parser shape, so it is genuinely shared, not a premature first copy.
+ */
+export function canonicalizeExecuteCommand(
+	input: string,
+): CanonicalExecuteCommand {
+	const asScript = (): CanonicalExecuteCommand => ({
+		mode: "script",
+		input,
+		path: "",
+		verb: "",
+		attributes: {},
+		queries: [],
+	});
+
+	const trimmed = input.trim();
+	if (!trimmed.startsWith("/")) {
+		return asScript();
+	}
+
+	const tokens = tokenizeRouterOsCli(trimmed);
+	const pathToken = tokens[0] ?? "";
+	const pathParts = pathToken.split("/").filter(Boolean);
+	if (pathParts.length < 2) {
+		return asScript();
+	}
+
+	const verb = pathParts.at(-1) ?? "";
+	const path = `/${pathParts.slice(0, -1).join("/")}`;
+	const attributes: Record<string, string> = {};
+	const queries: string[] = [];
+	for (const token of tokens.slice(1)) {
+		// `[...]` subshell selectors (e.g. `numbers=[find ...]`) cannot be
+		// represented as a structured attribute map: the inner command contains
+		// spaces this tokenizer splits on, which would mangle a write-shaped
+		// command into corrupt key=value pairs. Fall back to the raw-script path
+		// so RouterOS evaluates the subshell with its real semantics.
+		if (token.includes("[") || token.includes("]")) {
+			return asScript();
+		}
+		if (token.startsWith("?")) {
+			queries.push(token);
+			continue;
+		}
+		const separator = token.indexOf("=");
+		if (separator <= 0) {
+			return asScript();
+		}
+		attributes[token.slice(0, separator)] = token.slice(separator + 1);
+	}
+
+	return {
+		mode: "structured",
+		input,
+		path,
+		verb,
+		attributes,
+		queries,
+	};
+}
+
+export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
+	return (
+		command.mode === "structured" &&
+		["add", "set", "remove"].includes(command.verb)
+	);
+}
+
+function tokenizeRouterOsCli(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | undefined;
+	let escaped = false;
+	for (const char of input) {
+		if (escaped) {
+			current += char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (char === quote) {
+				quote = undefined;
+			} else {
+				current += char;
+			}
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			if (current.length > 0) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (escaped) {
+		current += "\\";
+	}
+	if (current.length > 0) {
+		tokens.push(current);
+	}
+	return tokens;
+}

package/src/core/inspect.ts

@@ -5,10 +5,16 @@
  * (path tokenizing, the comma-path join, node-type predicates, completion-name
  * extraction). This module is the single home so a third consumer — `api`, and a
  * future `explain`/`check` — reuses one grounded implementation instead of
- * forking a fourth. It deliberately holds only the transport-agnostic
- * *primitives*; each command composes its own discovery strategy on top (their
- * strategies differ: `retrieve` probes print/get support, `execute` unions
- * child-args with completions), so the strategy stays in the command.
+ * forking a fourth. It holds the transport-agnostic *primitives* plus the one
+ * discovery strategy that is shared verbatim: {@link inspectArgumentNames},
+ * command-level `request=child` only, used by `execute` and `api`. Strategies
+ * that differ stay in the command — `retrieve` probes print/get support and
+ * reads argument-level completion (`print,proplist` / `get,value-name`) with a
+ * child fallback.
+ *
+ * Command-level `request=completion` is not part of any argument-discovery
+ * strategy: on RouterOS 7.12.2 it hangs the REST handler and closes the
+ * native-API connection. See {@link inspectArgumentNames}.
  *
  * Grounding: the request modes mirror `tikoci/lsp-routeros-ts`
  * (`server/src/routeros.ts` `InspectRequest`). The behavioral facts (the array-
@@ -131,6 +137,32 @@ export async function inspectChildren(
 	)) as InspectChildItem[];
 }
 
+/**
+ * Return the argument names exposed by `request=child` at a command path.
+ *
+ * Do not supplement this with a command-level `request=completion`: RouterOS
+ * 7.12.2 hangs the REST handler and closes the native-API connection for that
+ * request shape, while `child` returns the complete argument list immediately.
+ * Argument-level completion (for example `print,proplist`) is a distinct probe
+ * and remains available through {@link inspectCompletions}.
+ */
+export async function inspectArgumentNames(
+	backend: InspectBackend,
+	tokens: readonly string[],
+): Promise<string[]> {
+	const children = await inspectChildren(backend, tokens);
+	return [
+		...new Set(
+			children
+				.filter(isArgumentNode)
+				.map((child) => child.name)
+				.filter(
+					(name): name is string => typeof name === "string" && name.length > 0,
+				),
+		),
+	].sort();
+}
+
 /** `request=completion` for a token path. */
 export async function inspectCompletions(
 	backend: InspectBackend,

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/execute-fanout.ts

@@ -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,
@@ -60,7 +62,6 @@ import {
 	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 {
@@ -233,6 +234,11 @@ 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<
@@ -282,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,