@tikoci/centrs 0.1.2 → 0.1.4

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,12 +32,15 @@ import {
 	parseScriptFor,
 } from "./protocols/mac-telnet-console.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	effectiveHostCandidate,
 	isIpTransport,
 	isMacAddress,
+	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -45,6 +49,7 @@ import {
 	resolveCdb,
 	resolveMacTarget,
 	resolveOptionalIntegerSetting,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -56,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;
@@ -277,19 +288,40 @@ export async function runResolvedExecute(
 export async function resolveExecuteRequest(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
+	options: {
+		cdbResolution?: CdbResolution;
+		config?: Record<string, string | undefined>;
+	} = {},
 ): Promise<ResolvedExecuteRequest> {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
-	const cdbResolution = await resolveCdb(
-		{
-			targetInput: request.targetInput,
-			cdbFile: request.cdbFile,
-			cdbPassword: request.cdbPassword,
-		},
-		env,
-	);
-	const via = resolveExecuteProtocol(request, env, cdbResolution);
-	const format = resolveFormat(request, env);
+	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 `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(
 		request.validate,
 		env,
@@ -297,57 +329,89 @@ export async function resolveExecuteRequest(
 		true,
 		"validate",
 		cdbResolution?.overrides.validate,
+		config,
 	);
 	const timeoutMs = resolveTimeoutSetting(
 		request.timeout,
 		env,
 		via.value,
 		cdbResolution?.overrides.timeoutMs,
+		config,
 	);
 	const maxResultsBytes = resolveOptionalIntegerSetting(
 		request.maxResultsBytes,
 		env,
 		"CENTRS_MAX_RESULTS",
 		"max-results",
+		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,
-				policy: parseResolvePolicy(request.resolve ?? env["CENTRS_RESOLVE"]),
-				operation: "execute",
-			})
-		: undefined;
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-	);
-	const auth = resolveAuth(
-		{
-			username: request.username,
-			password: request.password,
-			sshKey: request.sshKey,
-		},
-		env,
-		cdbResolution,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
-	);
+				via.value,
+				cdbResolution,
+				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,
@@ -362,7 +426,82 @@ export async function resolveExecuteRequest(
 		maxResultsBytes,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
+	};
+}
+
+export interface ExecuteGlobalContext {
+	via: RouterOsProtocol;
+	write: boolean;
+	summary: ExecuteRequestSummary;
+	settings: CommonSettingsMeta;
+}
+
+/**
+ * Resolve the target-independent settings (protocol, format, validate, timeout,
+ * max-results) for a fan-out's outer `meta.operation.request` summary and its
+ * transport-aware concurrency default. No CDB record is consulted; the global
+ * `--via` (default `native-api`) decides the summary and concurrency base. Also
+ * canonicalizes the command once so write-ness is known before any target runs.
+ */
+export function resolveExecuteGlobalContext(
+	request: ExecuteRequest,
+	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
+): ExecuteGlobalContext {
+	validateExecuteRequestShape(request);
+	const canonical = canonicalizeExecuteCommand(request.command);
+	const via = resolveExecuteProtocol(request, env, undefined, config);
+	const format = resolveFormat(request, env, config);
+	const validate = resolveBooleanSetting(
+		request.validate,
+		env,
+		"CENTRS_VALIDATE",
+		true,
+		"validate",
+		undefined,
+		config,
+	);
+	const timeoutMs = resolveTimeoutSetting(
+		request.timeout,
+		env,
+		via.value,
+		undefined,
+		config,
+	);
+	const maxResultsBytes = resolveOptionalIntegerSetting(
+		request.maxResultsBytes,
+		env,
+		"CENTRS_MAX_RESULTS",
+		"max-results",
+		undefined,
+		config,
+	);
+	return {
+		via: via.value,
+		write: isWriteShaped(canonical),
+		summary: {
+			command: request.command,
+			canonical,
+			write: isWriteShaped(canonical),
+			yes: request.yes ?? false,
+			validate: validate.value,
+			verbose: request.verbose ?? false,
+			timeoutMs: timeoutMs.value,
+			format: format.value,
+			maxResultsBytes: maxResultsBytes?.value,
+		},
+		settings: {
+			via: toCoreSource(via.source),
+			timeoutMs: toCoreSource(timeoutMs.source),
+			format: toCoreSource(format.source),
+			validate: toCoreSource(validate.source),
+			maxResultsBytes: maxResultsBytes
+				? toCoreSource(maxResultsBytes.source)
+				: undefined,
+		},
 	};
 }
 
@@ -600,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",
@@ -622,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`).
  */
@@ -651,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}`,
@@ -683,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).
@@ -694,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;
@@ -756,16 +905,6 @@ async function runCommand(
 		return backend.execute({ path: "", command: "", script: resolved.command });
 	}
 	if (resolved.canonical.mode === "script") {
-		if (resolved.via.value === "native-api") {
-			throw new CentrsError({
-				code: "transport/unsupported-operation",
-				summary:
-					"The native API execute path requires a slash-prefixed RouterOS command.",
-				remediation:
-					"Use a path-shaped command such as `/system/identity/set name=x`, or pin `--via rest-api` for `/rest/execute` script mode.",
-				context: { via: resolved.via.value, command: resolved.command },
-			});
-		}
 		return backend.execute({ path: "", command: "", script: resolved.command });
 	}
 	return backend.execute({
@@ -821,8 +960,9 @@ function resolveExecuteProtocol(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
-	const defaultVia = isUnresolvedMacTarget(request, env, cdb)
+	const defaultVia = isUnresolvedMacTarget(request, env, cdb, config)
 		? "mac-telnet"
 		: "native-api";
 	const via = resolveStringSetting(
@@ -833,6 +973,7 @@ function resolveExecuteProtocol(
 		"via",
 		undefined,
 		cdb?.overrides.via,
+		config,
 	);
 	if (!via) {
 		throw new CentrsError({
@@ -877,8 +1018,13 @@ function isUnresolvedMacTarget(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): boolean {
-	if (request.via !== undefined || env["CENTRS_VIA"] !== undefined) {
+	if (
+		request.via !== undefined ||
+		env["CENTRS_VIA"] !== undefined ||
+		config["CENTRS_VIA"] !== undefined
+	) {
 		return false;
 	}
 	// Decide the default transport from the *effective* target (host >
@@ -890,6 +1036,7 @@ function isUnresolvedMacTarget(
 		targetInput: request.targetInput,
 		cdbTarget: cdb?.target,
 		env,
+		config,
 	});
 	return candidate ? isMacAddress(candidate) : false;
 }
@@ -897,6 +1044,7 @@ function isUnresolvedMacTarget(
 function resolveFormat(
 	request: ExecuteRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<ExecuteOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -905,6 +1053,8 @@ function resolveFormat(
 		"text",
 		"format",
 		parseOutputFormat,
+		undefined,
+		config,
 	) as ResolvedSetting<ExecuteOutputFormat>;
 }
 
@@ -930,6 +1080,7 @@ function resolveTimeoutSetting(
 	env: Record<string, string | undefined>,
 	via: RouterOsProtocol,
 	commentKv?: ResolvedSetting<number>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -950,6 +1101,7 @@ function resolveTimeoutSetting(
 			return parsed;
 		},
 		commentKv,
+		config,
 	);
 	if (!resolved) {
 		throw new Error("timeout resolution produced no value");
@@ -1277,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;
+}