@tikoci/centrs 0.1.4 → 0.1.7

package/src/cli/devices.ts

@@ -22,6 +22,7 @@ import {
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	initCdb,
 	listDevices,
 	listGroups,
 	loadCdb,
@@ -46,7 +47,8 @@ import {
 
 export const devicesCommand: CliCommandMetadata = {
 	name: "devices",
-	usage: "centrs devices <list|show|groups|add|edit|set|remove> [args] [flags]",
+	usage:
+		"centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]",
 	summary:
 		"Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.",
 	options: [
@@ -197,6 +199,7 @@ export const devicesCommand: CliCommandMetadata = {
 };
 
 type DevicesSubcommand =
+	| "init"
 	| "list"
 	| "show"
 	| "groups"
@@ -378,6 +381,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	}
 
 	const subcommands: readonly DevicesSubcommand[] = [
+		"init",
 		"list",
 		"show",
 		"groups",
@@ -389,14 +393,14 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const [rawSub, ...rest] = positional;
 	if (rawSub === undefined) {
 		throw new Error(
-			"`centrs devices` requires a subcommand: list, show, groups, add, edit, set, or remove.",
+			"`centrs devices` requires a subcommand: init, list, show, groups, add, edit, set, or remove.",
 		);
 	}
 	// Resolve aliases (print/get/rm/delete) to the canonical verb before validating.
 	const sub = SUBCOMMAND_ALIASES[rawSub] ?? (rawSub as DevicesSubcommand);
 	if (!subcommands.includes(sub)) {
 		throw new Error(
-			`Unknown devices subcommand: ${rawSub}. Use list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
+			`Unknown devices subcommand: ${rawSub}. Use init, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
 		);
 	}
 	parsed.subcommand = sub;
@@ -606,6 +610,15 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		}
 
 		envSnapshot = Bun.env;
+		if (parsed.subcommand === "init") {
+			const envelope = await initCdb({
+				cdbFile: parsed.cdbFile,
+				cdbPassword: parsed.cdbPassword,
+				env: envSnapshot,
+			});
+			console.log(renderDevicesEnvelope(envelope, parsed.format ?? "text"));
+			return 0;
+		}
 		const cdb = await loadCdb({
 			cdbFile: parsed.cdbFile,
 			cdbPassword: parsed.cdbPassword,

package/src/cli/explain.ts

@@ -92,7 +92,7 @@ export const explainCliCommand: CliCommandMetadata = {
 		{
 			flag: "--tokens",
 			description:
-				"Emit the total, gapless token partition behind `data.tokens[]` (provisional `class` until #264 B5: every byte not claimed by an analyzer is `unclassified`).",
+				"Emit the total, gapless token partition behind `data.tokens[]` (every byte not claimed by an analyzer is `unclassified`).",
 		},
 		{
 			flag: "--format",

package/src/cli/terminal.ts

@@ -6,6 +6,7 @@
  * `process.*`); the core relay in `../terminal.ts` stays io-agnostic.
  */
 
+import { toYaml } from "../core/yaml.ts";
 import {
 	asCentrsError,
 	CentrsError,
@@ -18,7 +19,6 @@ import {
 	type TerminalIo,
 	type TerminalRequest,
 } from "../index.ts";
-import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,

package/src/core/envelope.ts

@@ -111,6 +111,50 @@ export interface EnvelopeTargetMeta {
 	sources?: Record<string, SettingSource>;
 }
 
+/**
+ * One stage of the two-stage validation gate (GH#354).
+ *
+ * `offline` is the corpus-gated analyzer (`src/offline-gate.ts`): it opens no
+ * connection, so a `failed` offline stage means the device was never contacted.
+ * `device` is the RouterOS-side preflight — `:put [:parse …]` and/or
+ * `/console/inspect request=child`, depending on the command and transport.
+ *
+ * Stages appear in the order they run, and a stage that did not run is still
+ * listed with `result: "skipped"`. That is the point of the array: a reader must
+ * be able to tell "the device accepted it" from "the device was never asked".
+ */
+export interface EnvelopeValidationStage {
+	stage: "offline" | "device";
+	/** Validator identity, e.g. `offline explain (canonicalizer)` or `:put [:parse]`. */
+	source: string;
+	result: "passed" | "failed" | "skipped";
+	/** Why a stage was skipped, when the reason is not simply `validate=false`. */
+	reason?: string;
+}
+
+/**
+ * Mutable sink that lets an error path report the validation that ACTUALLY ran.
+ *
+ * `runResolvedExecute` / `runResolvedApi` finish the gate and then do the real
+ * work, and the error envelope is built by a *different* function after the
+ * throw unwinds past them. Without this, a `routeros/*` fault on the run — which
+ * happens with both gate stages already green — got a reconstructed
+ * `result: "failed"` that erased the real outcome. The runner writes
+ * {@link ValidationTrace.validation} the moment the gate returns; the error
+ * builder prefers it over anything it could guess (GH#354, PR #356 review).
+ */
+export interface ValidationTrace {
+	/** The completed gate result, set once validation finishes. */
+	validation?: EnvelopeValidationMeta;
+	/**
+	 * The stage-1 verdict, recorded as soon as stage 1 returns — before stage 2
+	 * can throw. `warn` is an abstention, and an error envelope that reported it
+	 * as `passed` would be telling a consumer the analyzer read bytes it declined
+	 * to judge.
+	 */
+	offlineVerdict?: "pass" | "warn";
+}
+
 export interface EnvelopeValidationMeta {
 	enabled: boolean;
 	/** Validator identity, e.g. `/console/inspect` or `:put [:parse]`. */
@@ -121,6 +165,15 @@ export interface EnvelopeValidationMeta {
 	/** Semantic `/console/inspect` gate status, or not-applicable for script mode. */
 	semantic?: boolean | "not-applicable";
 	availableAttributes?: readonly string[];
+	/**
+	 * Per-stage detail for the gate described in
+	 * `docs/CONSTITUTION.md` → "Validation is the product".
+	 *
+	 * The flat `source` / `syntax` / `semantic` fields above stay the summary
+	 * view and keep their meaning; this is the breakdown behind them. Absent on
+	 * surfaces that have no RouterOS-command gate at all (`btest`).
+	 */
+	stages?: readonly EnvelopeValidationStage[];
 }
 
 export interface EnvelopeTimingMeta {

package/src/core/error-catalog.ts

@@ -40,6 +40,10 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/already-exists",
 		summary: "A CDB entry with that target already exists.",
 	},
+	{
+		code: "cdb/create-failed",
+		summary: "A new CDB file could not be created at the resolved location.",
+	},
 	{
 		code: "cdb/created",
 		summary: "A new CDB file was created at the resolved location.",
@@ -57,6 +61,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		code: "cdb/empty-selection",
 		summary: "The target selection matched no CDB records.",
 	},
+	{
+		code: "cdb/file-exists",
+		summary:
+			"`devices init` found a CDB already at the resolved location and wrote nothing.",
+	},
 	{
 		code: "cdb/invalid-option",
 		summary: "A comment kv-soup option carried an invalid value.",
@@ -430,6 +439,11 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"Auto-selection moved the operation to a different method (informational auto-hop).",
 	},
+	{
+		code: "transport/cancel-unacknowledged",
+		summary:
+			"RouterOS did not acknowledge a stream's /cancel within the timeout; centrs ended the stream and closed the session locally.",
+	},
 	{
 		code: "transport/capability-unsupported",
 		summary: "The chosen transport cannot perform this kind of operation.",
@@ -554,7 +568,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "validation/syntax",
-		summary: "RouterOS rejected the command syntax during the :parse gate.",
+		summary:
+			"The command syntax was rejected by the validation gate — offline analysis, or the RouterOS :parse probe.",
 	},
 	{
 		code: "validation/unknown-attribute",

package/src/core/execute-command.ts

@@ -0,0 +1,455 @@
+/**
+ * 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.
+ */
+
+import { isKnownMenuPath } from "../explain/is-known-menu.ts";
+
+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 for which validation and transport path runs. Write-shape
+ * detection is intentionally independent: a raw-script fallback must not bypass
+ * confirmation merely because it cannot be represented as attributes. 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 {
+	if (command.mode === "structured") {
+		if (FILE_OUTPUT_ATTRIBUTE in command.attributes) {
+			return true;
+		}
+		return !READ_ONLY_EXECUTE_VERBS.has(command.verb.toLowerCase());
+	}
+	return scriptContainsWriteShapedCommand(command.input);
+}
+
+/**
+ * The attribute that turns an otherwise read-only verb 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.
+ */
+const FILE_OUTPUT_ATTRIBUTE = "file";
+
+/** True for a `file=<name>` token — the write-shaping output redirect. */
+function isFileOutputToken(token: string): boolean {
+	return token.startsWith(`${FILE_OUTPUT_ATTRIBUTE}=`);
+}
+
+/**
+ * Commands that are safe to execute without write confirmation.
+ *
+ * This is deliberately an allowlist: RouterOS publishes no mutation bit for a
+ * command, and treating a newly introduced verb as read-only would silently
+ * widen the execution boundary. False positives require `--yes`; false
+ * negatives mutate a router. API uses the same conservative rule (only
+ * print/get/listen are read-classed).
+ */
+const READ_ONLY_EXECUTE_VERBS: ReadonlySet<string> = new Set([
+	"check",
+	"check-installation",
+	"export",
+	"find",
+	"get",
+	"monitor",
+	"monitor-traffic",
+	"ping",
+	"print",
+	"scan",
+	"sniff",
+	"torch",
+	"traceroute",
+]);
+
+/** Known mutators disambiguate the space-separated CLI spelling from a menu. */
+const KNOWN_WRITE_EXECUTE_VERBS: ReadonlySet<string> = new Set([
+	"add",
+	"comment",
+	"delete",
+	"disable",
+	"edit",
+	"enable",
+	"flush",
+	"format",
+	"format-drive",
+	"import",
+	"install",
+	"move",
+	"password",
+	"reboot",
+	"redo",
+	"remove",
+	"reset",
+	"reset-configuration",
+	"reset-counters",
+	"reset-counters-all",
+	"run",
+	"set",
+	"shutdown",
+	"sign",
+	"start",
+	"stop",
+	"unset",
+	"upgrade",
+	"undo",
+]);
+
+/** Script directives that can launch a command outside the visible statement. */
+const WRITE_SHAPED_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
+	":execute",
+]);
+
+/**
+ * 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).
+ */
+const READ_ONLY_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
+	":break",
+	":continue",
+	":do",
+	":error",
+	":for",
+	":foreach",
+	":if",
+	":len",
+	":local",
+	":onerror",
+	":pick",
+	":put",
+	":return",
+	":tostr",
+	":typeof",
+	":while",
+]);
+
+function scriptContainsWriteShapedCommand(input: string): boolean {
+	for (const statement of splitUnquotedStatements(input)) {
+		const tokens = tokenizeRouterOsCli(statement);
+		// `file=` redirects output to a device file, so it is a write even under a
+		// read verb. Checked before the verb rules for the same reason the
+		// structured branch checks it independently of the allowlist.
+		if (
+			tokens.some((token) => isFileOutputToken(trimGroupingPunctuation(token)))
+		) {
+			return true;
+		}
+		// A script may navigate to a menu on one line and use a relative verb on
+		// the next. Recognize grounded mutators even when no slash appears in that
+		// statement; quoted words were masked before tokenization.
+		if (
+			tokens.some((token) =>
+				KNOWN_WRITE_EXECUTE_VERBS.has(trimGroupingPunctuation(token)),
+			)
+		) {
+			return true;
+		}
+		if (
+			tokens.some((token) =>
+				WRITE_SHAPED_SCRIPT_DIRECTIVES.has(token.replace(/^[{[(]+/, "")),
+			)
+		) {
+			return true;
+		}
+		// 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)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * The commands a statement runs: one at its start and one after every `[` or
+ * `{`, wherever that opener sits — an argument value (`in=[/ip address find]`,
+ * `do={/user expire-password $i}`), a sigil (`$[…]`), a concatenation
+ * (`"x".[…]`) or a token of its own (`do={ /user … }`). Parentheses group
+ * 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[][] = [];
+	const starts = [0];
+	for (let index = 0; index < statement.length; index += 1) {
+		const char = statement[index];
+		if (char === "[" || char === "{") starts.push(index + 1);
+	}
+	for (const start of starts) {
+		const nextOpener = statement.slice(start).search(/[[{(]/);
+		const segment =
+			nextOpener < 0
+				? statement.slice(start)
+				: statement.slice(start, start + nextOpener);
+		const tokens = tokenizeRouterOsCli(segment);
+		const head = tokens[0];
+		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);
+	}
+	return heads;
+}
+
+/**
+ * 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
+ * in those words (`/ip firewall filter print`, `/interface 6to4 print`, `/ip
+ * firewall/filter print`). A word opening a bracket starts a nested command
+ * (`new-mutator [find]`) and a word trailing a closer ends this one (`:put [/ip
+ * address find]`), so the run stops at either.
+ */
+function commandWords(head: string, following: readonly string[]): string[] {
+	const words: string[] = [];
+	const headWord = trimGroupingPunctuation(head);
+	if (headWord.startsWith(":")) return [headWord];
+	words.push(...headWord.split("/").filter(Boolean));
+	if (headWord !== head) return words;
+	for (const token of following) {
+		if (/^[{[(]/.test(token)) break;
+		const word = trimGroupingPunctuation(token);
+		if (!/^[A-Za-z0-9][A-Za-z0-9-]*(?:\/[A-Za-z0-9][A-Za-z0-9-]*)*$/.test(word))
+			break;
+		words.push(...word.split("/"));
+		if (word !== token) break;
+	}
+	return words;
+}
+
+/**
+ * A command is read-only when it is a read-only script directive, or when the
+ * first word past the longest known menu prefix is a read verb. Walking the
+ * menu table rather than taking the first known verb keeps an unlearned
+ * command from borrowing a later argument: `/user expire-password print` names
+ * `expire-password` (a published command, absent from every allowlist) with
+ * the username `print`. The menu table is a floor, so an unknown menu fails
+ * closed here, as does a run of menus with no verb (navigation for a later
+ * relative command).
+ */
+function isReadOnlyCommand(words: readonly string[]): boolean {
+	const head = words[0] ?? "";
+	if (head.startsWith(":")) return READ_ONLY_SCRIPT_DIRECTIVES.has(head);
+	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());
+}
+
+function trimGroupingPunctuation(value: string): string {
+	let start = 0;
+	let end = value.length;
+	while (start < end && "{[(".includes(value[start] ?? "")) start += 1;
+	while (end > start && "}])".includes(value[end - 1] ?? "")) end -= 1;
+	return value.slice(start, end);
+}
+
+/**
+ * Split at real statement boundaries and blank quoted text, which does not
+ * execute — except a `$[…]` or `$(…)` substitution inside a double-quoted
+ * string, which is code: `:put "$[/system identity set name=x]"` runs the set.
+ * Its body is kept (with its opener, so it becomes a command head) and may nest
+ * strings of its own. The frame grammar is `explain`'s (`stepFrame` in
+ * `src/explain/quoted-string.ts`).
+ */
+function splitUnquotedStatements(input: string): string[] {
+	const statements: string[] = [];
+	let current = "";
+	// `"` / `'` are string frames; `]` / `)` are the closer a code frame inside
+	// a string is waiting for. An empty stack is top-level code.
+	const frames: string[] = [];
+	let escaped = false;
+	for (let index = 0; index < input.length; index += 1) {
+		const char = input[index] ?? "";
+		const top = frames.at(-1);
+		const inString = top === '"' || top === "'";
+		if (escaped) {
+			current += inString ? " " : char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			current += inString ? " " : char;
+			continue;
+		}
+		if (inString) {
+			if (char === top) {
+				frames.pop();
+			} else if (
+				top === '"' &&
+				char === "$" &&
+				(input[index + 1] === "[" || input[index + 1] === "(")
+			) {
+				const opener = input[index + 1] ?? "";
+				frames.push(opener === "[" ? "]" : ")");
+				current += ` ${opener}`;
+				index += 1;
+				continue;
+			}
+			current += " ";
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			frames.push(char);
+			current += " ";
+			continue;
+		}
+		if (top !== undefined) {
+			// Inside a string's code frame: track nesting to find its closer.
+			if (char === top) frames.pop();
+			else if (char === "[") frames.push("]");
+			else if (char === "(") frames.push(")");
+		}
+		if (char === ";" || char === "\n" || char === "\r") {
+			statements.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	statements.push(current);
+	return statements;
+}
+
+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;
+}