@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/src/api.ts

@@ -45,6 +45,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { assertRouterOsMenuPath } from "./core/menu-path.ts";
 import {
 	compileQueryWords,
 	type ParsedQuery,
@@ -62,6 +63,7 @@ import {
 	promptForWriteConfirmation,
 	validateRouterOsScript,
 } from "./execute.ts";
+import { countExecutableStatements } from "./explain/segment.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -159,6 +161,12 @@ export interface ApiRequest {
 	verbose?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** Opt-in host ARP resolution for a MAC target (`none` default, or `arp`). */
 	resolve?: string;
 	stdinIsTty?: boolean;
@@ -541,7 +549,7 @@ async function* streamResolvedApi(
 			trace.validation = validation;
 			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
 		} else {
-			validation = disabledValidationMeta();
+			validation = disabledApiValidationMeta(resolved);
 		}
 	} catch (error) {
 		await backend.close();
@@ -824,16 +832,6 @@ function adapterForResolved(resolved: ResolvedApiRequest): ProtocolAdapter {
 	});
 }
 
-function disabledValidationMeta(): EnvelopeValidationMeta {
-	return {
-		enabled: false,
-		source: "disabled",
-		result: "skipped",
-		syntax: false,
-		semantic: false,
-	};
-}
-
 export async function resolveApiRequest(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
@@ -946,6 +944,7 @@ export async function resolveApiRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
@@ -1347,7 +1346,8 @@ interface ApiValidationResult {
  * validator is `/console/inspect`, never `:put [:parse]`. Path existence and
  * add/set attribute validity both come from `request=child` — command-level
  * `request=completion` is unsafe on RouterOS 7.12.2 (`core/inspect.ts`). A
- * `/execute` script is a CLI string → `semantic: not-applicable`.
+ * `/execute` script is a CLI string, so it has no `semantic` summary; a
+ * structured request runs no `:parse`, so it has no `syntax` summary (#535).
  */
 async function validateApiRequest(
 	resolved: ResolvedApiRequest,
@@ -1383,8 +1383,7 @@ async function validateApiRequest(
 						? "not-applicable"
 						: API_SCRIPT_DEVICE_STAGE_SOURCE,
 				result: "passed",
-				syntax: script !== undefined,
-				semantic: "not-applicable",
+				...(script !== undefined ? { syntax: true } : {}),
 				stages: [
 					{
 						stage: "offline",
@@ -1468,13 +1467,7 @@ async function validateApiRequest(
 			}
 		}
 		return {
-			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
-			},
+			validation: structuredValidationPassed(resolved),
 			tips,
 			queryMenu: isCommand ? `/${parent.join("/")}` : resolved.path,
 		};
@@ -1513,11 +1506,7 @@ async function validateApiRequest(
 		}
 		return {
 			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
+				...structuredValidationPassed(resolved),
 				availableAttributes: available,
 			},
 			tips,
@@ -1526,13 +1515,7 @@ async function validateApiRequest(
 	}
 
 	return {
-		validation: {
-			enabled: true,
-			source: "/console/inspect request=child",
-			result: "passed",
-			syntax: false,
-			semantic: true,
-		},
+		validation: structuredValidationPassed(resolved),
 		tips,
 		queryMenu: resolved.path,
 	};
@@ -1857,6 +1840,12 @@ export function buildApiErrorEnvelopeFromResolved(
 	trace?: ValidationTrace,
 ): ApiErrorEnvelope {
 	const centrsError = asApiError(error);
+	// A structured request is one operation; only a `/execute` script can
+	// carry several statements into one dispatch (#549), at the top level or
+	// inside an executed control scope.
+	const script = resolved.scriptMode ? scriptOf(resolved) : undefined;
+	const multiStatement =
+		script !== undefined && countExecutableStatements(script) > 1;
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
@@ -1866,6 +1855,7 @@ export function buildApiErrorEnvelopeFromResolved(
 				isApiMutating(resolved.method, resolved.path),
 				centrsError,
 				trace,
+				multiStatement,
 			),
 		],
 		tips: [],
@@ -1877,6 +1867,22 @@ export function buildApiErrorEnvelopeFromResolved(
 	};
 }
 
+/** A structured request the device stage passed; stage 1 does not apply to it. */
+function structuredValidationPassed(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationMeta {
+	return {
+		enabled: true,
+		source: API_DEVICE_STAGE_SOURCE,
+		result: "passed",
+		semantic: true,
+		stages: [
+			offlineApiStage(resolved),
+			{ stage: "device", source: API_DEVICE_STAGE_SOURCE, result: "passed" },
+		],
+	};
+}
+
 /**
  * `meta.validation` for an api error envelope. A stage-1 rejection opened no
  * connection, so the meta must not report `/console/inspect` as the validator
@@ -1896,7 +1902,6 @@ function failedApiValidationMeta(
 			source: OFFLINE_GATE_SOURCE,
 			result: "failed",
 			syntax: false,
-			semantic: "not-applicable",
 			stages: [
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
@@ -1911,14 +1916,14 @@ function failedApiValidationMeta(
 	// Only a `validation/*` error identifies the device stage as the rejecter.
 	// Everything downstream of a passed gate — a RouterOS fault on the request,
 	// a transport drop — is served by `trace.validation` before this function is
-	// ever reached.
+	// ever reached. A script is refused by `:parse` (syntax); a structured
+	// request by `/console/inspect` (names) (#535).
 	if (error.code.startsWith("validation/")) {
 		return {
 			enabled: true,
 			source: apiDeviceStageSource(resolved),
 			result: "failed",
-			syntax: false,
-			semantic: resolved.scriptMode ? "not-applicable" : false,
+			...(resolved.scriptMode ? { syntax: false } : { semantic: false }),
 			stages: [offlineApiStage(resolved, trace), deviceStageFailed(resolved)],
 		};
 	}
@@ -2012,8 +2017,6 @@ function disabledApiValidationMeta(
 		enabled: false,
 		source: "disabled",
 		result: "skipped",
-		syntax: false,
-		semantic: resolved.scriptMode ? "not-applicable" : false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
 			{
@@ -2181,6 +2184,10 @@ export function validateApiRequestShape(request: ApiRequest): void {
 				"Pass a path with at least one menu segment, such as `ip/address`.",
 		});
 	}
+	// Before transport choice and regardless of --validate: a `#`/`?` in the
+	// path cut `/print` off the REST URL and a GET read posted to the bare
+	// command, rebooting the router (#586).
+	assertRouterOsMenuPath(normalized.path, { endpoint: request.endpoint });
 }
 
 /**

package/src/btest.ts

@@ -113,6 +113,12 @@ export interface BtestClientRequest {
 	natMode?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	env?: Record<string, string | undefined>;
 	signal?: AbortSignal;
 	/** Live per-interval frame callback (text/csv streaming). */
@@ -264,6 +270,7 @@ export async function btestClient(
 				targetInput: request.targetInput,
 				cdbFile: request.cdbFile,
 				cdbPassword: request.cdbPassword,
+				match: request.match,
 			},
 			env,
 		);

package/src/cli/api.ts

@@ -23,7 +23,10 @@ import {
 	formatCentrsErrorText,
 } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
-import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
+import {
+	assertNoMatchInFanout,
+	assertNoQuickchrOverrideConflict,
+} from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -165,6 +168,12 @@ export const apiCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -330,6 +339,9 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;
@@ -473,6 +485,11 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				selectionFlags.quickchr[0] ?? "",
 			);
 		}
+		// `--match` + fan-out is refused here too, before `--input -` can block
+		// on stdin; `apiFanout` keeps the same check for library callers (#583).
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			assertNoMatchInFanout(parsed.match);
+		}
 
 		// Resolve `--input` (file / stdin) before handing the body to the orchestrator.
 		if (parsed.inputPath !== undefined) {

package/src/cli/btest.ts

@@ -145,6 +145,12 @@ export const btestCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "(client) Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"(client) Pick one of several CDB records saved for <router> (as `devices show --match`); `btest server` rejects it.",
+		},
 		{
 			flag: "--format",
 			valueName: `<${btestOutputFormats.join("|")}>`,
@@ -302,6 +308,9 @@ function parseClientArgs(args: readonly string[]): ClientCliArgs {
 			case "--cdb-password":
 				request.cdbPassword = expectValue(args, ++i, arg);
 				break;
+			case "--match":
+				request.match = expectValue(args, ++i, arg);
+				break;
 			case "--csv":
 				parsed.format = "csv";
 				break;

package/src/cli/devices.ts

@@ -22,6 +22,7 @@ import {
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	encryptCdb,
 	initCdb,
 	listDevices,
 	listGroups,
@@ -48,10 +49,20 @@ import {
 export const devicesCommand: CliCommandMetadata = {
 	name: "devices",
 	usage:
-		"centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]",
+		"centrs devices <init|encrypt|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: [
+		{
+			flag: "--encrypt",
+			description:
+				"`init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB.",
+		},
+		{
+			flag: "--no-backup",
+			description:
+				"`encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered.",
+		},
 		{
 			flag: "--cdb-file",
 			valueName: "<path>",
@@ -62,7 +73,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--cdb-password",
 			valueName: "<secret>",
 			description:
-				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes.",
+				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used for `init --encrypt`, `encrypt`, and to re-encrypt on writes.",
 		},
 		{
 			flag: "--via",
@@ -200,6 +211,7 @@ export const devicesCommand: CliCommandMetadata = {
 
 type DevicesSubcommand =
 	| "init"
+	| "encrypt"
 	| "list"
 	| "show"
 	| "groups"
@@ -226,6 +238,8 @@ interface DevicesCliArgs {
 	subcommand?: DevicesSubcommand;
 	cdbFile?: string;
 	cdbPassword?: string;
+	encrypt?: boolean;
+	noBackup?: boolean;
 	group?: string;
 	where?: string[];
 	via?: string;
@@ -254,20 +268,44 @@ interface DevicesCliArgs {
 	bbox?: BboxPredicate;
 }
 
+/**
+ * Flags `init`/`encrypt` honor. They touch only the CDB file, never a record,
+ * so record, selection, and provenance flags would be silently ignored there.
+ */
+const CDB_FILE_FLAGS: Readonly<Record<"init" | "encrypt", readonly string[]>> =
+	{
+		init: ["--cdb-file", "--cdb-password", "--format", "--json", "--encrypt"],
+		encrypt: [
+			"--cdb-file",
+			"--cdb-password",
+			"--format",
+			"--json",
+			"--no-backup",
+		],
+	};
+
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const parsed: DevicesCliArgs = {};
 	const positional: string[] = [];
+	const suppliedFlags: string[] = [];
 
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) {
 			continue;
 		}
+		if (arg.startsWith("-")) suppliedFlags.push(arg);
 		switch (arg) {
 			case "--help":
 			case "-h":
 				parsed.help = true;
 				break;
+			case "--encrypt":
+				parsed.encrypt = true;
+				break;
+			case "--no-backup":
+				parsed.noBackup = true;
+				break;
 			case "--cdb-file":
 				parsed.cdbFile = expectValue(args, ++index, arg);
 				break;
@@ -382,6 +420,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 
 	const subcommands: readonly DevicesSubcommand[] = [
 		"init",
+		"encrypt",
 		"list",
 		"show",
 		"groups",
@@ -393,17 +432,23 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const [rawSub, ...rest] = positional;
 	if (rawSub === undefined) {
 		throw new Error(
-			"`centrs devices` requires a subcommand: init, list, show, groups, add, edit, set, or remove.",
+			"`centrs devices` requires a subcommand: init, encrypt, 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 init, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
+			`Unknown devices subcommand: ${rawSub}. Use init, encrypt, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
 		);
 	}
 	parsed.subcommand = sub;
+	if (parsed.encrypt && sub !== "init")
+		throw new Error(
+			"--encrypt is supported only by devices init; use devices encrypt for conversion.",
+		);
+	if (parsed.noBackup && sub !== "encrypt")
+		throw new Error("--no-backup is supported only by devices encrypt.");
 
 	// Reject flags that don't apply to the resolved subcommand instead of
 	// silently ignoring the user's input: `--where`/`--near`/`--bbox` select
@@ -446,6 +491,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			context: { subcommand: sub, flag: geoFlag },
 		});
 	}
+	if (sub === "init" || sub === "encrypt") {
+		const allowed = CDB_FILE_FLAGS[sub];
+		const ignored = suppliedFlags.find((flag) => !allowed.includes(flag));
+		if (ignored !== undefined) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `\`${ignored}\` is not supported by \`centrs devices ${sub}\`.`,
+				remediation: `\`centrs devices ${sub}\` accepts only ${allowed.map((flag) => `\`${flag}\``).join(", ")}. Edit records with \`centrs devices add\`/\`set\`.`,
+				context: { subcommand: sub, flag: ignored },
+			});
+		}
+	}
 
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
@@ -511,7 +568,14 @@ function parseKvArg(token: string): CommentKvUpdate {
 	// canonical key a `--lon`/`--lat`/`--altitude` flag would use. A no-op for
 	// every non-geo key.
 	const key = canonicalizeGeoKey(token.slice(0, eq));
-	return { key, value: parseKvValue(token.slice(eq + 1)) };
+	const value = parseKvValue(token.slice(eq + 1));
+	// An empty value removes the token (`devices set <t> via=` deletes the
+	// `via` override) instead of storing a literally-empty value, per
+	// `commands/devices/README.md` (Comment kv-soup). The core upsert/remove
+	// model lives in `applyCommentKv` (`src/resolver/comment-kv.ts`), which
+	// treats `value: null` as removal; the CLI lowers `key=` to that form
+	// here. There is currently no need to store a literally-empty value.
+	return { key, value: value === "" ? null : value };
 }
 
 /**
@@ -610,12 +674,16 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		}
 
 		envSnapshot = Bun.env;
-		if (parsed.subcommand === "init") {
-			const envelope = await initCdb({
+		if (parsed.subcommand === "init" || parsed.subcommand === "encrypt") {
+			const options = {
 				cdbFile: parsed.cdbFile,
 				cdbPassword: parsed.cdbPassword,
 				env: envSnapshot,
-			});
+			};
+			const envelope =
+				parsed.subcommand === "init"
+					? await initCdb({ ...options, encrypt: parsed.encrypt })
+					: await encryptCdb({ ...options, skipBackup: parsed.noBackup });
 			console.log(renderDevicesEnvelope(envelope, parsed.format ?? "text"));
 			return 0;
 		}

package/src/cli/execute.ts

@@ -121,6 +121,12 @@ export const executeCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -262,6 +268,9 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;