@tikoci/centrs 0.1.3 → 0.1.4

package/src/core/routeros-string.ts

@@ -0,0 +1,24 @@
+/**
+ * Quote RouterOS command text as one double-quoted string literal.
+ *
+ * `$` is load-bearing here: RouterOS expands variables inside double quotes,
+ * so leaving it bare changes the bytes seen by wrappers such as
+ * `:put [:parse "<input>"]` before the parser receives them.
+ * Control whitespace (`\t`/`\r`/`\n`) is escaped so the decoded string
+ * carries the caller's original bytes. This is defensive: RouterOS 7.20
+ * changelog says "replace TAB characters with spaces when editing scripts
+ * and added `tab-width` in `/console/settings`" — version-gated (absent
+ * before 7.20), width-configurable via `tab-width`, and scoped to the
+ * script editor, not grounded as string-literal expansion (see #276).
+ * Escaping preserves the caller's bytes whether the device expands or
+ * preserves a raw tab.
+ */
+export function routerOsStringLiteral(value: string): string {
+	return `"${value
+		.replaceAll("\\", "\\\\")
+		.replaceAll('"', '\\"')
+		.replaceAll("$", "\\$")
+		.replaceAll("\t", "\\t")
+		.replaceAll("\r", "\\r")
+		.replaceAll("\n", "\\n")}"`;
+}

package/src/errors.ts

@@ -13,6 +13,7 @@ export type CentrsErrorCode =
 	| `input/${string}`
 	| `internal/${string}`
 	| `mndp/${string}`
+	| `quickchr/${string}`
 	| `routeros/${string}`
 	| `settings/${string}`
 	| `target/${string}`

package/src/execute-fanout.ts

@@ -9,7 +9,7 @@
  *
  * Boundaries (see `commands/execute/README.md`, `docs/CONSTITUTION.md`), shared
  * with `api-fanout.ts` / `retrieve-fanout.ts`:
- *   - The CDB is loaded ONCE (`expandCdbSelection`); a cdb member is resolved with
+ *   - The CDB is loaded ONCE (`expandSelection`); a cdb member is resolved with
  *     its pre-resolved record, so `resolveCdb`'s `__default__` synthetic fallback
  *     never collides ad-hoc literals.
  *   - A `--default` / `__default__` member is guarded from being dialed as the
@@ -52,12 +52,12 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type TargetSelection,
 } from "./resolver/index.ts";
 import { toYaml } from "./retrieve.ts";
@@ -69,6 +69,8 @@ export interface ExecuteSelectionSummary {
 	all: boolean;
 	default: boolean;
 	positionals: readonly string[];
+	/** quickchr machine names (`--quickchr`, repeatable; exclusive of the rest). */
+	quickchr?: readonly string[];
 }
 
 export interface ExecuteFanoutOperationMeta {
@@ -91,10 +93,10 @@ export type ExecuteFanoutErrorEnvelope =
 export interface ExecuteFanoutInternals {
 	expand?: (
 		selection: TargetSelection,
-		input: CdbSelectionResolveInput,
+		input: SelectionResolveInput,
 		env: Record<string, string | undefined>,
 		config?: Record<string, string | undefined>,
-	) => Promise<CdbSelectionExpansion>;
+	) => Promise<SelectionExpansion>;
 	execute?: (
 		resolved: ResolvedExecuteRequest,
 	) => Promise<ExecuteSuccessEnvelope>;
@@ -116,6 +118,7 @@ function summarizeSelection(
 		all: selection.all,
 		default: selection.default,
 		positionals: selection.positionals,
+		quickchr: selection.quickchr,
 	};
 }
 
@@ -124,7 +127,7 @@ function fanoutVia(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	globalVia: RouterOsProtocol,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): RouterOsProtocol {
 	// Deliberately CLI/env only, not `config` — see the identical note in
 	// `retrieve-fanout.ts`'s `resolveFanoutConcurrencyProtocol`.
@@ -139,7 +142,7 @@ function fanoutVia(
 	return anyNative ? "native-api" : globalVia;
 }
 
-function memberTargetMeta(member: CdbSelectionMember): {
+function memberTargetMeta(member: SelectionMember): {
 	input?: string;
 	identity?: string;
 	recordIndex?: number;
@@ -151,6 +154,9 @@ function memberTargetMeta(member: CdbSelectionMember): {
 			recordIndex: member.recordIndex,
 		};
 	}
+	if (member.kind === "quickchr") {
+		return { input: member.name, identity: member.name };
+	}
 	return { input: member.input };
 }
 
@@ -163,7 +169,7 @@ function memberTargetMeta(member: CdbSelectionMember): {
  */
 function relabelAdhocMember(
 	envelope: ExecuteEnvelope,
-	member: CdbSelectionMember,
+	member: SelectionMember,
 ): ExecuteEnvelope {
 	if (member.kind !== "literal") {
 		return envelope;
@@ -195,7 +201,7 @@ export async function executeFanout(
 	const global = resolveExecuteGlobalContext(request, env, config);
 	const selectionSummary = summarizeSelection(selection);
 
-	const expand = internals.expand ?? expandCdbSelection;
+	const expand = internals.expand ?? expandSelection;
 	const expansion = await expand(
 		selection,
 		{
@@ -230,7 +236,7 @@ export async function executeFanout(
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
-		CdbSelectionMember,
+		SelectionMember,
 		ResolvedExecuteRequest,
 		ExecuteEnvelope
 	>({
@@ -254,6 +260,15 @@ export async function executeFanout(
 					{ cdbResolution: member.resolution, config },
 				);
 			}
+			if (member.kind === "quickchr") {
+				// The live descriptor resolves here, per member — a stopped/unknown
+				// machine is an inner per-target failure, not an expansion error.
+				return resolveExecuteRequest(
+					{ ...request, targetInput: undefined, quickchr: member.name },
+					env,
+					{ config },
+				);
+			}
 			return resolveExecuteRequest(
 				{ ...request, targetInput: member.input },
 				env,
@@ -292,7 +307,7 @@ export async function executeFanout(
 async function assertFanoutWriteConfirmed(
 	request: ExecuteRequest,
 	summary: ExecuteRequestSummary,
-	expansion: CdbSelectionExpansion,
+	expansion: SelectionExpansion,
 ): Promise<void> {
 	if (!summary.write || request.yes) {
 		return;
@@ -323,7 +338,7 @@ interface ExecuteFanoutEnvelopeInput {
 	requestSummary: ExecuteRequestSummary;
 	settings: CommonSettingsMeta;
 	via: RouterOsProtocol | null;
-	warnings: CdbSelectionExpansion["warnings"];
+	warnings: SelectionExpansion["warnings"];
 	targets: readonly ExecuteEnvelope[];
 }
 

package/src/execute.ts

@@ -17,6 +17,7 @@ import {
 	pathTokens,
 } from "./core/inspect.ts";
 import { mapRouterOsError } from "./core/routeros-errors.ts";
+import { routerOsStringLiteral } from "./core/routeros-string.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
 import {
 	createProtocolAdapter,
@@ -31,6 +32,7 @@ import {
 	parseScriptFor,
 } from "./protocols/mac-telnet-console.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	effectiveHostCandidate,
 	isIpTransport,
@@ -38,6 +40,7 @@ import {
 	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -46,6 +49,7 @@ import {
 	resolveCdb,
 	resolveMacTarget,
 	resolveOptionalIntegerSetting,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -57,6 +61,12 @@ export type ExecuteOutputFormat = (typeof executeOutputFormats)[number];
 
 export interface ExecuteRequest {
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password/sshKey.
+	 */
+	quickchr?: string;
 	command: string;
 	via?: string;
 	host?: string;
@@ -286,19 +296,30 @@ export async function resolveExecuteRequest(
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
 	const config = options.config ?? (await loadEnvFileDefaults(env));
+	// A quickchr target is a named-live-provider: it supplies host/port/auth from
+	// the live descriptor and bypasses CDB/env resolution for those fields
+	// entirely (no CDB load, no `__default__` ladder, no MAC resolution).
+	let quickchrResolution: Awaited<
+		ReturnType<typeof resolveQuickchrTarget>
+	> | null = null;
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+	}
 	// Fan-out passes the pre-resolved CDB record for a member (the CDB is loaded
-	// once in `expandCdbSelection`); single-target resolves it here.
-	const cdbResolution =
-		options.cdbResolution ??
-		(await resolveCdb(
-			{
-				targetInput: request.targetInput,
-				cdbFile: request.cdbFile,
-				cdbPassword: request.cdbPassword,
-			},
-			env,
-			config,
-		));
+	// once in `expandSelection`); single-target resolves it here.
+	const cdbResolution = quickchrResolution
+		? undefined
+		: (options.cdbResolution ??
+			(await resolveCdb(
+				{
+					targetInput: request.targetInput,
+					cdbFile: request.cdbFile,
+					cdbPassword: request.cdbPassword,
+				},
+				env,
+				config,
+			)));
 	const via = resolveExecuteProtocol(request, env, cdbResolution, config);
 	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -325,50 +346,72 @@ export async function resolveExecuteRequest(
 		undefined,
 		config,
 	);
-	const macResolution = isIpTransport(via.value)
-		? await resolveMacTarget({
-				host: request.host,
-				targetInput: request.targetInput,
-				cdbTarget: cdbResolution?.target,
+	const macResolution =
+		quickchrResolution === null && isIpTransport(via.value)
+			? await resolveMacTarget({
+					host: request.host,
+					targetInput: request.targetInput,
+					cdbTarget: cdbResolution?.target,
+					env,
+					config,
+					policy: parseResolvePolicy(
+						request.resolve ??
+							env["CENTRS_RESOLVE"] ??
+							config["CENTRS_RESOLVE"],
+					),
+					operation: "execute",
+				})
+			: undefined;
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, via.value)
+		: null;
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+					macResolution,
+				},
 				env,
+				via.value,
+				cdbResolution,
 				config,
-				policy: parseResolvePolicy(
-					request.resolve ?? env["CENTRS_RESOLVE"] ?? config["CENTRS_RESOLVE"],
-				),
-				operation: "execute",
-			})
-		: undefined;
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-		config,
-	);
-	const auth = resolveAuth(
-		{
-			username: request.username,
-			password: request.password,
-			sshKey: request.sshKey,
-		},
-		env,
-		cdbResolution,
-		config,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-		config,
-	);
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{
+					username: request.username,
+					password: request.password,
+					sshKey: request.sshKey,
+				},
+				env,
+				cdbResolution,
+				config,
+			);
+	// A quickchr TLS/SSH endpoint is trusted by provenance (self-signed VM cert /
+	// ephemeral host key) — `insecure` is forced with provider provenance and the
+	// provider-trust warning rides the envelope (see QuickchrConnection.insecure).
+	const insecure =
+		connection?.insecure === true
+			? {
+					value: true,
+					source: {
+						kind: "provider" as const,
+						key: `quickchr:${request.quickchr}`,
+					},
+				}
+			: resolveBooleanSetting(
+					request.insecure,
+					env,
+					"CENTRS_INSECURE",
+					false,
+					"insecure",
+					cdbResolution?.overrides.insecure,
+					config,
+				);
 
 	return {
 		command: request.command,
@@ -383,7 +426,9 @@ export async function resolveExecuteRequest(
 		maxResultsBytes,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
 	};
 }
 
@@ -694,7 +739,7 @@ async function validateExecuteCommand(
 			context: {
 				path: resolved.canonical.path,
 				verb: resolved.canonical.verb,
-				attribute: missing[0],
+				parameter: missing[0],
 				requestedAttributes: requested,
 				availableAttributes,
 				validationSource: "/console/inspect request=child+completion",
@@ -716,7 +761,7 @@ async function validateExecuteCommand(
  * Validate a command over a console transport (mac-telnet or ssh) with a single
  * `:put [:parse ...]`. Unlike REST/native (a syntax gate plus a `/console/inspect`
  * semantic gate), one console `:parse` reports both `syntax error` and `bad
- * parameter <name>`, so it covers syntax and the unknown-attribute (semantic)
+ * parameter <name>`, so it covers syntax and the unknown-attribute (name-level)
  * gate at once — identical strings over mac-telnet and ssh (CHR 7.23.1 grounded;
  * see `mac-telnet-console.ts` and `ssh.ts`).
  */
@@ -745,7 +790,7 @@ async function validateConsoleParseCommand(
 		script: parseScriptFor(resolved.command),
 	});
 	// Throws validation/syntax or validation/unknown-attribute on a bad parse.
-	classifyParseResult(result.ret ?? "", resolved.command);
+	classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
 	return {
 		enabled: true,
 		source: `:put [:parse ...] over ${resolved.via.value}`,
@@ -777,7 +822,14 @@ async function runSyntaxGate(
 	}
 	const script = `:put [:parse ${routerOsStringLiteral(resolved.command)}]`;
 	try {
-		await backend.execute({ path: "", command: "", script });
+		// GH#230: `:parse` never throws (CHR 7.23.3). The diagnostic rides the
+		// success value's text — over REST/native the `ret` field (HTTP 200 /
+		// `as-string`), over console the printed output. The old code only watched
+		// for a thrown transport/RouterOS error and so never rejected anything.
+		// Read the return and classify it: one `:parse` covers syntax and the
+		// unknown-attribute (name-level) gate.
+		const result = await backend.execute({ path: "", command: "", script });
+		classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
 	} catch (error) {
 		// The preflight is a syntax gate, but `backend.execute` also surfaces
 		// connection and authentication failures (login happens lazily here).
@@ -788,6 +840,9 @@ async function runSyntaxGate(
 		if (error instanceof CentrsError && isPreflightTransportError(error)) {
 			throw error;
 		}
+		if (error instanceof CentrsError && error.code.startsWith("validation/")) {
+			throw error;
+		}
 		// If the mapped RouterOS fault carried a `(line N column M)` byte offset,
 		// keep it on the wrapped syntax error rather than dropping it.
 		const position = error instanceof CentrsError ? error.position : undefined;
@@ -1374,10 +1429,6 @@ function tokenizeRouterOsCli(input: string): string[] {
 	return tokens;
 }
 
-function routerOsStringLiteral(value: string): string {
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
 function syntaxCause(error: unknown): unknown {
 	if (error instanceof CentrsError) {
 		return error.causeData ?? error.context ?? error.toJSON();

package/src/explain/arg-tokens.ts

@@ -0,0 +1,114 @@
+/**
+ * B2 arg fill — claims argument names and their `=` on the residual.
+ *
+ * This is the second B2 fill of #264, added after the operator fill. It runs
+ * **after** the proof-only spans (`comment` + `variable-*`) and **before** the
+ * operator fill, so the fill order is structural: `spans` claims first, then
+ * `arg`, then `operator` sees only what neither wanted. That ordering is why the
+ * operator fill can abstain on `, / = -` outside `( )`, on bytes glued after
+ * an argument `=`, and on bytes glued into an argument name — those bytes
+ * belong to a later fill, not to a smarter operator scanner.
+ *
+ * The source is `src/explain/args.ts`'s `Argument` — `span` and `valueSpan`
+ * already rebased into document analyzed-byte space by `src/explain.ts`. The
+ * name run is `[span.start, valueSpan.start - 1)` and the `=` is the single
+ * byte at `valueSpan.start - 1`; the value itself is `valueSpan` and is left
+ * for the next fill (see #293). A `positional` has no `name`/`valueSpan` and a
+ * `query` is a `?` word whose interior `args.ts` explicitly refuses to split
+ * (see `Argument.value`'s doc comment), so both are ignored — the `=` is
+ * derived from the token shape, never by scanning for the byte.
+ *
+ * `Argument.value` is not `Argument.text` and is never read: `value` is absent
+ * whenever the source spells a substitution or an escape this phase does not
+ * decode. This slice claims `span`/`valueSpan` *positions* only.
+ *
+ * A statement whose bytes were normalized is not addressable: `explain.ts`
+ * already refuses those (`its text was normalized`), and this fill inherits the
+ * refusal — it only sees tokens from `read === true` statements, which are
+ * exactly the addressable ones.
+ *
+ * Vocabulary is provisional until #264 B5: one `arg` class for both the name
+ * bytes and the `=` separator (design decision 2 of #293 — emit first, name
+ * later; `highlight`'s `syntax-meta` is a residual merge and never a source).
+ * If B5 splits the `=` into its own class, the byte coverage does not move,
+ * only the retag.
+ */
+
+import type { ExplainArgumentToken, ExplainToken } from "../explain.ts";
+import { clipToResidual } from "./token-ranges.ts";
+
+export type ArgCandidate = ExplainArgumentToken;
+
+/**
+ * Argument name + `=` spans on the residual.
+ *
+ * `analyzed` is the ASCII-normalized document text (only used for length
+ * checks); `residual` is the gap set left by earlier fills (sorted, no
+ * overlaps); `candidates` are the already-rebased `Argument` tokens from
+ * `read === true` statements. Every emitted span's bytes are fully inside
+ * `residual`, sorted by `start`, non-overlapping, and carry
+ * `class: "arg"` + `ev: "e11"`.
+ */
+export function argSpans(
+	analyzed: string,
+	residual: readonly { start: number; end: number }[],
+	candidates: readonly ArgCandidate[],
+): ExplainToken[] {
+	const len = analyzed.length;
+	if (len === 0 || residual.length === 0 || candidates.length === 0) return [];
+
+	const out: ExplainToken[] = [];
+
+	for (const candidate of candidates) {
+		if (candidate.kind !== "attribute") continue;
+		if (candidate.valueSpan === undefined) continue;
+		if (candidate.name === undefined) continue;
+		const nameStart = candidate.span.start;
+		const eqEnd = candidate.valueSpan.start;
+		const eqStart = eqEnd - 1;
+		const nameEnd = eqStart;
+		// Defensive: token shape must give non-empty name and single-byte `=`.
+		if (
+			!Number.isInteger(nameStart) ||
+			!Number.isInteger(nameEnd) ||
+			!Number.isInteger(eqStart) ||
+			!Number.isInteger(eqEnd)
+		)
+			continue;
+		if (nameStart < 0 || eqEnd > len) continue;
+		// Non-empty name. This is also what rejects `valueSpan.start === 0`, where
+		// `eqStart` would be -1: `nameEnd` is -1 too, so any `nameStart >= 0` trips
+		// it. `analyzed[-1]` on the next line would be `undefined` and continue
+		// anyway, so the order is safe either way — but the name check is the one
+		// that carries the intent.
+		if (nameStart >= nameEnd) continue;
+		// The whole token's `=` byte must be `=` in the analyzed text — a cheap
+		// shape check that catches a caller that passed un-rebased or misaligned
+		// spans. Not a scan for `=`; the position is derived from `valueSpan`.
+		if (analyzed[eqStart] !== "=") continue;
+		// Also ensure the candidate lies fully inside the analyzed length.
+		if (candidate.span.start < 0 || candidate.span.end > len) continue;
+		if (candidate.valueSpan.start < 0 || candidate.valueSpan.end > len)
+			continue;
+
+		// The name run and the `=` are contiguous (`nameEnd === eqStart`), so
+		// clip them as ONE range per candidate. That yields the maximal `[name=]`
+		// run for free — split only where the residual itself has a hole — and
+		// makes cross-candidate fusion structurally impossible rather than merely
+		// unreachable: coalescing adjacent runs globally would merge two distinct
+		// attributes into one token if `lexArguments` ever stopped guaranteeing a
+		// separator between them. A `variable-*` span claiming only the `=` still
+		// leaves the name run behind, because the residual hole does the splitting.
+		for (const r of clipToResidual(nameStart, eqEnd, residual)) {
+			out.push({
+				start: r.start,
+				end: r.end,
+				class: "arg" as const,
+				ev: "e11",
+			});
+		}
+	}
+
+	out.sort((a, b) => a.start - b.start || a.end - b.end);
+	return out;
+}