@tikoci/centrs 0.1.6 → 0.1.8-next.0

package/src/core/execute-command.ts

@@ -13,6 +13,8 @@
  * 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;
@@ -24,8 +26,10 @@ export interface CanonicalExecuteCommand {
 
 /**
  * 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,
+ * 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
@@ -96,10 +100,313 @@ export function canonicalizeExecuteCommand(
 }
 
 export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
-	return (
-		command.mode === "structured" &&
-		["add", "set", "remove"].includes(command.verb)
-	);
+	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[] {

package/src/core/inspect.ts

@@ -30,16 +30,21 @@ import { CentrsError } from "../errors.ts";
  * protocol layer (no import cycle).
  */
 export interface InspectBackend {
-	inspect(request: "child" | "completion", path: string): Promise<unknown[]>;
+	inspect(
+		request: "child" | "completion",
+		path: string,
+		input?: string,
+	): Promise<unknown[]>;
 }
 
 /**
  * The `/console/inspect` request modes (lsp's `InspectRequest`). Only `child`
  * and `completion` are wired today (the two the {@link InspectBackend} seam
- * exposes); `highlight` (token-level error detection) and `syntax` (parse tree),
- * plus the `input`/`.query`/`.proplist` request fields, are the documented
- * Phase-2 extension point for value-level validation — widen the adapter seam
- * when adding them.
+ * exposes), plus `input` for completion over CLI text
+ * ({@link inspectWhereBooleans}); `highlight` (token-level error detection),
+ * `syntax` (parse tree) and the `.query`/`.proplist` request fields are the
+ * documented extension point for value-level validation — widen the adapter
+ * seam when adding them.
  */
 export type InspectRequestKind =
 	| "child"
@@ -55,12 +60,20 @@ export interface InspectChildItem {
 }
 
 /** A row from `request=completion`: a candidate token for a path/argument. */
+/**
+ * One `request=completion` row. These are the only fields RouterOS sends, on
+ * every build recorded from 7.9.2 to 7.25beta3 (lsp-routeros-ts
+ * `test-data/inspect-shapes.v*.json`). `text` is the candidate's help string,
+ * never its name.
+ */
 export interface InspectCompletionItem {
 	type?: string;
-	name?: string;
 	completion?: string;
-	value?: string;
+	show?: string;
+	style?: string;
 	text?: string;
+	offset?: string;
+	preference?: string;
 }
 
 /**
@@ -99,31 +112,23 @@ export function isCommandNode(child: InspectChildItem, name: string): boolean {
 }
 
 /**
- * Flatten completion rows into attribute names. Reads every name-like field a
- * RouterOS build might populate (`completion`/`name`/`value`/`text`), strips
- * everything from the first `=` onward (the `name=value` completion form), and
- * drops blanks. Returns the names in row order **without** de-duplication or
- * sorting — callers that need a stable set wrap with `[...new Set(names)].sort()`
- * (both current callers do).
+ * The candidate names from completion rows: `completion` of each
+ * `show: "true"` row that is not `syntax-meta`. `show: "false"` rows are
+ * syntax completions (`[`, `(`, `$`, `"`, `*`, `<value>`), not properties
+ * (CHR 7.23.7, on both `print,proplist` and `get,value-name`; #380). At an
+ * argument boundary RouterOS also offers a shown `=` ("argument value
+ * separator", `style: "syntax-meta"`) on every recorded build, 7.9.2 →
+ * 7.25beta3; no build offers a `name=value` completion. Returns
+ * the names in row order **without** de-duplication or sorting; callers that
+ * need a stable set wrap with `[...new Set(names)].sort()`.
  */
 export function extractCompletionNames(
 	rows: readonly InspectCompletionItem[],
 ): string[] {
 	return rows
-		.flatMap((row) => [row.completion, row.name, row.value, row.text])
-		.filter((value): value is string => typeof value === "string")
-		.map((value) => nameBeforeEquals(value).trim())
-		.filter((value) => value.length > 0);
-}
-
-/**
- * The token before the first `=` in a RouterOS completion row. Plain string
- * slicing (no regex) — `value.replace(/=.*$/, "")` triggers a CodeQL
- * polynomial-ReDoS flag on this exported function's caller-supplied input.
- */
-function nameBeforeEquals(value: string): string {
-	const eq = value.indexOf("=");
-	return eq === -1 ? value : value.slice(0, eq);
+		.filter((row) => row.show === "true" && row.style !== "syntax-meta")
+		.map((row) => row.completion?.trim() ?? "")
+		.filter((name) => name.length > 0);
 }
 
 /** `request=child` for a token path. */
@@ -200,3 +205,36 @@ export async function inspectChildrenOrEmpty(
 		throw error;
 	}
 }
+
+/**
+ * Which of `names` are booleans in `<menu>/print where`, asked of the device:
+ * completion after `where <name>=` offers exactly `no` and `yes` as `arg` rows
+ * for a boolean (`disabled`, `dynamic`, `running`), and `none`-styled values
+ * or `<value>` otherwise (enums such as `protocol` or `arp`, strings, numbers;
+ * CHR 7.24.5, #397). A `--query` bare name needs this: RouterOS reads
+ * `where disabled` as `disabled=yes` but `where comment` as "comment is set",
+ * and only the device knows which a property is. One request per name.
+ */
+export async function inspectWhereBooleans(
+	backend: InspectBackend,
+	menuPath: string,
+	names: readonly string[],
+): Promise<Set<string>> {
+	const booleans = new Set<string>();
+	const menu = menuPath.replace(/\/$/, "");
+	for (const name of names) {
+		const rows = (await backend.inspect(
+			"completion",
+			"",
+			`${menu}/print where ${name}=`,
+		)) as InspectCompletionItem[];
+		const values = rows
+			.filter((row) => row.style !== "syntax-meta")
+			.map((row) => `${row.style}:${row.completion}`)
+			.sort();
+		if (values.join(" ") === "arg:no arg:yes") {
+			booleans.add(name);
+		}
+	}
+	return booleans;
+}