@tikoci/centrs 0.1.4 → 0.1.7

package/src/api.ts

@@ -3,9 +3,10 @@
  *
  * The structured middle of the verb trichotomy (see `commands/api/README.md`):
  * one command per operation (no code blocks), structured input **and** output,
- * validated through `/console/inspect`, runnable over REST or the native API. The
+ * validated through `/console/inspect` (or live `:parse` for `/execute` scripts),
+ * runnable over REST or the native API. The
  * orchestrator is transport-agnostic — it normalizes the endpoint, resolves the
- * method→verb map, runs the inspect gate and the write-confirmation gate, then
+ * method→verb map, runs the validation and write-confirmation gates, then
  * hands a normalized {@link ProtocolApiRequest} to the adapter. REST vs native
  * mechanics (id-in-URL vs `=.id=`, `.query` vs `?`-words) live in the adapter.
  *
@@ -21,26 +22,36 @@ import type {
 	CommonSettingsMeta,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	EnvelopeValidationStage,
 	Tip,
+	ValidationTrace,
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip } from "./core/envelope.ts";
 import {
-	extractCompletionNames,
-	inspectChildren,
+	inspectArgumentNames,
 	inspectChildrenOrEmpty,
-	inspectCompletions,
-	isArgumentNode,
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { mapRouterOsResultError } from "./core/routeros-errors.ts";
+import { toYaml } from "./core/yaml.ts";
 import { CentrsError, serializeCentrsError } from "./errors.ts";
-import { promptForWriteConfirmation } from "./execute.ts";
+import {
+	promptForWriteConfirmation,
+	validateRouterOsScript,
+} from "./execute.ts";
+import {
+	assertOfflineSyntax,
+	isOfflineGateRejection,
+	OFFLINE_GATE_SOURCE,
+} from "./offline-gate.ts";
 import {
 	type ApiVerb,
 	createProtocolAdapter,
 	type ProtocolAdapter,
 	type ProtocolApiRequest,
+	type ProtocolApiResult,
 	plannedProtocols,
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
@@ -64,7 +75,6 @@ import {
 	resolveTarget,
 	toCoreSource,
 } from "./resolver/index.ts";
-import { toYaml } from "./retrieve.ts";
 
 export const apiOutputFormats = ["json", "yaml", "text"] as const;
 export type ApiOutputFormat = (typeof apiOutputFormats)[number];
@@ -97,7 +107,11 @@ export interface ApiRequest {
 	rawQuery?: readonly string[];
 	/** `--proplist` / `--attribute` property projection. */
 	proplist?: readonly string[];
-	/** `--raw`: bare RouterOS body passthrough; implies `--validate=false`. */
+	/**
+	 * `--raw`: bare RouterOS body passthrough. DEFAULTS `--validate` to false; an
+	 * explicit `validate` still wins, and its failures render through the `--raw`
+	 * error contract (#154).
+	 */
 	raw?: boolean;
 	/** `--listen`: native-api-only open-ended follow (later phase; rejected here). */
 	listen?: boolean;
@@ -124,6 +138,23 @@ export interface ApiRequest {
 	confirm?: (prompt: string) => Promise<boolean>;
 }
 
+/**
+ * The `--raw` / `--validate` precedence for a summary built BEFORE (or instead
+ * of) full resolution — a usage error, or a fan-out member that never reached
+ * `resolveApiRequest`.
+ *
+ * Ambient sources are deliberately out of reach here: this runs where the CDB
+ * and config tiers have not been loaded, so it reports the two layers it CAN
+ * see. That is why it is a shared helper rather than an inlined expression —
+ * both call sites used to spell `request.raw ? false : …`, which contradicted
+ * the resolved request by reporting `validate: false` for an explicit
+ * `--raw --validate=true` (#154).
+ */
+function summarizedValidate(request: ApiRequest): boolean {
+	if (request.validate !== undefined) return request.validate;
+	return !(request.raw ?? false);
+}
+
 export interface NormalizedApiEndpoint {
 	/** Canonical slash path with the leading `/rest` and any trailing id/`listen` removed. */
 	path: string;
@@ -247,21 +278,32 @@ export async function apiEnvelope(
 	env: Record<string, string | undefined> = Bun.env,
 ): Promise<ApiEnvelope> {
 	let resolved: ResolvedApiRequest | undefined;
+	// The gate finishes inside `runResolvedApi`, but the error envelope is built
+	// out here after the throw has unwound past it. Without the trace, a
+	// `transport/*` or `routeros/*` fault on the request — both stages already
+	// settled — reported `/console/inspect` as the validator that failed.
+	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveApiRequest(request, env);
 		await assertApiWriteConfirmed(request, resolved);
-		return await runResolvedApi(resolved);
+		return await runResolvedApi(resolved, trace);
 	} catch (error) {
 		return resolved
-			? buildApiErrorEnvelopeFromResolved(resolved, error)
+			? buildApiErrorEnvelopeFromResolved(resolved, error, trace)
 			: buildApiErrorEnvelope(request, error, env);
 	}
 }
 
 export async function runResolvedApi(
 	resolved: ResolvedApiRequest,
+	trace: ValidationTrace = {},
 ): Promise<ApiSuccessEnvelope> {
 	assertListenCapability(resolved);
+	// Validate the complete request shape before constructing a backend or
+	// running either validation stage. In particular, `/execute` must reject
+	// extra body fields deterministically instead of letting live `:parse`
+	// surface an unrelated transport or authentication failure first.
+	const protocolRequest = buildProtocolApiRequest(resolved);
 	const backend = createProtocolAdapter({
 		protocol: resolved.via.value,
 		host: resolved.target.host,
@@ -279,20 +321,21 @@ export async function runResolvedApi(
 	let tips: Tip[] = [];
 	try {
 		if (resolved.validate.value) {
-			const result = await validateApiRequest(resolved, backend);
+			const result = await validateApiRequest(resolved, backend, trace);
 			validation = result.validation;
 			tips = result.tips;
 		} else {
-			validation = {
-				enabled: false,
-				source: "disabled",
-				result: "skipped",
-				syntax: false,
-				semantic: false,
-			};
+			validation = disabledApiValidationMeta(resolved);
+		}
+		// Recorded BEFORE the request, so a transport drop or RouterOS fault below
+		// reports the gate that actually settled rather than a guess.
+		trace.validation = validation;
+
+		const result = await backend.apiRequest(protocolRequest);
+		const routerOsFailure = apiRouterOsFailureFromResult(resolved, result);
+		if (routerOsFailure) {
+			throw routerOsFailure;
 		}
-
-		const result = await backend.apiRequest(buildProtocolApiRequest(resolved));
 		return {
 			ok: true,
 			data: result.data,
@@ -305,6 +348,35 @@ export async function runResolvedApi(
 	}
 }
 
+/**
+ * A `/execute` run that RouterOS *transported* successfully but *rejected* at
+ * runtime.
+ *
+ * `as-string` makes the console's own text the reply body, so a rejected
+ * script comes back as an ordinary 200/`!done` carrying `no such item`. Both
+ * adapters surface that text as `data`, so without this the caller-addressed
+ * `/execute` would report a failure as `ok: true` — exactly the shape
+ * `execute` normalizes in `routerOsFailureFromResult`. Structured path
+ * requests are untouched: their faults already arrive as HTTP >=400 or a
+ * `!trap`, and their `data` is a record, not console text.
+ */
+function apiRouterOsFailureFromResult(
+	resolved: ResolvedApiRequest,
+	result: ProtocolApiResult,
+): CentrsError | undefined {
+	if (!resolved.scriptMode || typeof result.data !== "string") {
+		return undefined;
+	}
+	const via = resolved.via.value;
+	return mapRouterOsResultError(result.data, {
+		transport:
+			via === "rest-api" || via === "mac-telnet" || via === "ssh"
+				? via
+				: "native-api",
+		context: { via },
+	});
+}
+
 /**
  * The open-ended `--stream` follow path: an async generator yielding one
  * {@link ApiEnvelope} per `/listen` change frame, then a terminating summary
@@ -371,14 +443,18 @@ async function* streamResolvedApi(
 	const startedAt = Date.now();
 	let frames = 0;
 	let stopReason: ApiStreamStopReason | undefined;
+	let cancelUnacknowledged = false;
 	let durationTimer: ReturnType<typeof setTimeout> | undefined;
+	// The first stop cause wins: the cancel grace window keeps the loop alive
+	// after a stop, so a later timer or frame must not relabel it.
 	const onExternalAbort = (): void => {
 		stopReason ??= "interrupted";
+		clearTimeout(durationTimer);
 		controller.abort();
 	};
 	if (resolved.durationMs !== undefined) {
 		durationTimer = setTimeout(() => {
-			stopReason = "duration-elapsed";
+			stopReason ??= "duration-elapsed";
 			controller.abort();
 		}, resolved.durationMs);
 	}
@@ -395,11 +471,14 @@ async function* streamResolvedApi(
 		for await (const record of backend.listen(protocolRequest, {
 			signal: controller.signal,
 			onListening,
+			onCancelUnacknowledged: () => {
+				cancelUnacknowledged = true;
+			},
 		})) {
 			frames += 1;
 			yield streamFrameEnvelope(resolved, validation, record, frames);
 			if (resolved.count !== undefined && frames >= resolved.count) {
-				stopReason = "count-reached";
+				stopReason ??= "count-reached";
 				break;
 			}
 		}
@@ -409,6 +488,15 @@ async function* streamResolvedApi(
 			stopReason ?? "interrupted",
 			frames,
 			Date.now() - startedAt,
+			cancelUnacknowledged
+				? [
+						{
+							code: "transport/cancel-unacknowledged",
+							message: `RouterOS did not acknowledge /cancel within ${resolved.timeoutMs.value}ms; centrs closed the session locally.`,
+							context: { timeoutMs: resolved.timeoutMs.value },
+						},
+					]
+				: [],
 		);
 	} catch (error) {
 		// A mid-stream failure is itself a frame, tagged `stream.kind="frame"` so
@@ -468,6 +556,7 @@ function streamSummaryEnvelope(
 	stopReason: ApiStreamStopReason,
 	frames: number,
 	durationMs: number,
+	streamWarnings: readonly Warning[] = [],
 ): ApiSuccessEnvelope {
 	const summary: ApiStreamSummary = { stopReason, frames, durationMs };
 	const meta = metaFromResolved(resolved, validation, summary);
@@ -476,7 +565,7 @@ function streamSummaryEnvelope(
 	return {
 		ok: true,
 		data: summary,
-		warnings: [...resolved.warnings],
+		warnings: [...resolved.warnings, ...streamWarnings],
 		tips: [],
 		meta,
 	};
@@ -574,19 +663,40 @@ export async function resolveApiRequest(
 			)));
 	const via = resolveApiProtocol(request, env, listen, cdbResolution, config);
 	const format = resolveApiFormat(request, env, config);
-	// `--raw` forces validation off (constitution: --raw waiver); otherwise the
-	// inspect gate is on by default.
-	const validate: ResolvedSetting<boolean> = raw
-		? { value: false, source: { kind: "cli", key: "--raw" } }
-		: resolveBooleanSetting(
-				request.validate,
-				env,
-				"CENTRS_VALIDATE",
-				true,
-				"validate",
-				cdbResolution?.overrides.validate,
-				config,
-			);
+	// `--raw` is a PRECEDENCE LAYER, not an override (#154). It ranks below an
+	// explicit `--validate` and above every ambient source, so:
+	//
+	//   --validate=true|false   explicit CLI flag   ← wins
+	//   --raw                   → validate=false
+	//   CENTRS_VALIDATE / CDB comment-kv / config
+	//   default                 → validate=true
+	//
+	// It used to short-circuit the whole ladder, which silently discarded an
+	// explicit `--validate=true` — and env, CDB and config with it. `--raw
+	// --validate=true` is the intended way to debug `api` when centrs itself is
+	// suspect: the gate runs and a failure renders through `rawErrorPayload` as
+	// `{code,message}` on stderr with a nonzero exit, which is the `--raw` error
+	// contract for any other preflight failure. `--raw` still outranks the
+	// ambient sources rather than merely lowering the default, so it behaves the
+	// same on every machine regardless of a `CENTRS_VALIDATE` in the environment.
+	//
+	// The `--raw` arm must SHORT-CIRCUIT, not merely win a comparison: resolving
+	// the ambient layer first would parse `CENTRS_VALIDATE` even when `--raw`
+	// decides the value, so a malformed ambient value threw `settings/invalid-
+	// boolean` out of a call `--raw` had already settled — the same
+	// machine-dependence this layer exists to remove.
+	const validate: ResolvedSetting<boolean> =
+		raw && request.validate === undefined
+			? { value: false, source: { kind: "cli", key: "--raw" } }
+			: resolveBooleanSetting(
+					request.validate,
+					env,
+					"CENTRS_VALIDATE",
+					true,
+					"validate",
+					cdbResolution?.overrides.validate,
+					config,
+				);
 	const timeoutMs = resolveApiTimeout(
 		request.timeout,
 		env,
@@ -906,6 +1016,10 @@ export function buildProtocolApiRequest(
 	return request;
 }
 
+/** The api device-stage validator for structured path input. */
+const API_DEVICE_STAGE_SOURCE = "/console/inspect request=child";
+const API_SCRIPT_DEVICE_STAGE_SOURCE = ":put [:parse]";
+
 interface ApiValidationResult {
 	validation: EnvelopeValidationMeta;
 	tips: Tip[];
@@ -913,22 +1027,63 @@ interface ApiValidationResult {
 
 /**
  * The structured-input gate. Because the input is a path (not a CLI string) the
- * validator is `/console/inspect`, never `:put [:parse]`. Path existence via
- * `request=child`; add/set attribute validity via `request=child`+`completion`. A
+ * 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`.
  */
 async function validateApiRequest(
 	resolved: ResolvedApiRequest,
 	backend: ProtocolAdapter,
+	trace: ValidationTrace = {},
 ): Promise<ApiValidationResult> {
 	if (resolved.scriptMode) {
+		// `/execute` carries a CLI string, so use the same offline -> live `:parse`
+		// pipeline as `execute`. `/console/inspect` remains inapplicable because
+		// there is no structured menu path/body to inspect.
+		const script = scriptOf(resolved);
+		const offline = script
+			? assertOfflineSyntax(script, {
+					surface: "api /execute",
+					via: resolved.via.value,
+				})
+			: undefined;
+		trace.offlineVerdict = offline?.verdict;
+		if (script !== undefined) {
+			await validateRouterOsScript(script, backend, resolved.via.value);
+		}
+		const offlineReason =
+			offline === undefined
+				? "no `script` field to analyze"
+				: offline.verdict === "warn"
+					? "analyzer abstained on part of the input"
+					: undefined;
 		return {
 			validation: {
 				enabled: true,
-				source: "/console/inspect (script, not-applicable)",
+				source:
+					offline === undefined
+						? "not-applicable"
+						: API_SCRIPT_DEVICE_STAGE_SOURCE,
 				result: "passed",
-				syntax: false,
+				syntax: script !== undefined,
 				semantic: "not-applicable",
+				stages: [
+					{
+						stage: "offline",
+						source: OFFLINE_GATE_SOURCE,
+						result: offline === undefined ? "skipped" : "passed",
+						...(offlineReason ? { reason: offlineReason } : {}),
+					},
+					{
+						stage: "device",
+						source: API_SCRIPT_DEVICE_STAGE_SOURCE,
+						result: script === undefined ? "skipped" : "passed",
+						...(script === undefined
+							? { reason: "no `script` field to parse" }
+							: {}),
+					},
+				],
 			},
 			tips: [],
 		};
@@ -970,7 +1125,7 @@ async function validateApiRequest(
 		// Only reject when inspect actually surfaced the command's arguments; if it
 		// returns none, skip rather than false-reject a valid command.
 		if (isCommand && Object.keys(resolved.body).length > 0) {
-			const available = await inspectApiAttributes(backend, tokens);
+			const available = await inspectArgumentNames(backend, tokens);
 			if (available.length > 0) {
 				const requested = Object.keys(resolved.body);
 				const missing = requested.filter(
@@ -988,7 +1143,7 @@ async function validateApiRequest(
 							parameter: missing[0],
 							requestedAttributes: requested,
 							availableAttributes: available,
-							validationSource: "/console/inspect request=child+completion",
+							validationSource: "/console/inspect request=child",
 						},
 					});
 				}
@@ -1013,7 +1168,7 @@ async function validateApiRequest(
 	}
 
 	if (resolved.verb === "add" || resolved.verb === "set") {
-		const available = await inspectApiAttributes(backend, [
+		const available = await inspectArgumentNames(backend, [
 			...tokens,
 			resolved.verb,
 		]);
@@ -1033,14 +1188,14 @@ async function validateApiRequest(
 					parameter: missing[0],
 					requestedAttributes: requested,
 					availableAttributes: available,
-					validationSource: "/console/inspect request=child+completion",
+					validationSource: "/console/inspect request=child",
 				},
 			});
 		}
 		return {
 			validation: {
 				enabled: true,
-				source: "/console/inspect request=child+completion",
+				source: "/console/inspect request=child",
 				result: "passed",
 				syntax: false,
 				semantic: true,
@@ -1062,6 +1217,21 @@ async function validateApiRequest(
 	};
 }
 
+/**
+ * The `/execute` script body, when there is one to analyze.
+ *
+ * A missing or blank `script` is not this gate's error to raise:
+ * {@link buildProtocolApiRequest} already rejects it with an actionable
+ * `input/invalid-command` naming the three ways to pass one. Reporting a syntax
+ * fault for an absent field would be the wrong diagnosis.
+ */
+function scriptOf(resolved: ResolvedApiRequest): string | undefined {
+	const script = resolved.body["script"];
+	return typeof script === "string" && script.trim().length > 0
+		? script
+		: undefined;
+}
+
 function unknownPathError(resolved: ResolvedApiRequest): CentrsError {
 	return new CentrsError({
 		code: "validation/unknown-path",
@@ -1076,23 +1246,6 @@ function unknownPathError(resolved: ResolvedApiRequest): CentrsError {
 	});
 }
 
-async function inspectApiAttributes(
-	backend: ProtocolAdapter,
-	commandTokens: readonly string[],
-): Promise<string[]> {
-	const children = await inspectChildren(backend, commandTokens);
-	const childAttributes = children
-		.filter(isArgumentNode)
-		.map((child) => child.name)
-		.filter(
-			(name): name is string => typeof name === "string" && name.length > 0,
-		);
-	const completionRows = await inspectCompletions(backend, commandTokens);
-	return [
-		...new Set([...childAttributes, ...extractCompletionNames(completionRows)]),
-	].sort();
-}
-
 async function assertApiWriteConfirmed(
 	request: ApiRequest,
 	resolved: ResolvedApiRequest,
@@ -1299,7 +1452,7 @@ export function buildApiErrorEnvelope(
 						: false,
 					listen: request.listen ?? false,
 					yes: request.yes ?? false,
-					validate: request.raw ? false : (request.validate ?? true),
+					validate: summarizedValidate(request),
 					raw: request.raw ?? false,
 					format: resolveErrorFormat(request, env),
 				},
@@ -1315,6 +1468,7 @@ export function buildApiErrorEnvelope(
 export function buildApiErrorEnvelopeFromResolved(
 	resolved: ResolvedApiRequest,
 	error: unknown,
+	trace?: ValidationTrace,
 ): ApiErrorEnvelope {
 	const centrsError = asApiError(error);
 	return {
@@ -1322,17 +1476,134 @@ export function buildApiErrorEnvelopeFromResolved(
 		error: serializeCentrsError(centrsError),
 		warnings: [...resolved.warnings],
 		tips: [],
-		meta: metaFromResolved(resolved, {
-			enabled: resolved.validate.value,
-			source: resolved.validate.value ? "/console/inspect" : "disabled",
-			result: resolved.validate.value ? "failed" : "skipped",
+		meta: metaFromResolved(
+			resolved,
+			trace?.validation ??
+				failedApiValidationMeta(resolved, centrsError, trace),
+		),
+	};
+}
+
+/**
+ * `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
+ * that failed (GH#354).
+ */
+function failedApiValidationMeta(
+	resolved: ResolvedApiRequest,
+	error: CentrsError,
+	trace?: ValidationTrace,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return disabledApiValidationMeta(resolved);
+	}
+	if (isOfflineGateRejection(error)) {
+		return {
+			enabled: true,
+			source: OFFLINE_GATE_SOURCE,
+			result: "failed",
 			syntax: false,
-			semantic: resolved.validate.value
-				? resolved.scriptMode
-					? "not-applicable"
-					: false
-				: false,
-		}),
+			semantic: "not-applicable",
+			stages: [
+				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
+				{
+					stage: "device",
+					source: apiDeviceStageSource(resolved),
+					result: "skipped",
+					reason: "offline analysis rejected the script; no connection opened",
+				},
+			],
+		};
+	}
+	// `stages` is only asserted when a `validation/*` error identifies the device
+	// stage as the rejecter. Everything downstream — a RouterOS fault on the
+	// request, a transport drop — passed the gate and is served by
+	// `trace.validation` before this function is ever reached.
+	const deviceRejected = error.code.startsWith("validation/");
+	return {
+		enabled: true,
+		source: apiDeviceStageSource(resolved),
+		result: "failed",
+		syntax: false,
+		semantic: resolved.scriptMode ? "not-applicable" : false,
+		...(deviceRejected
+			? {
+					stages: [
+						offlineApiStage(resolved, trace),
+						deviceStageFailed(resolved),
+					],
+				}
+			: {}),
+	};
+}
+
+/**
+ * The offline-stage entry for an api gate that reached the device stage.
+ *
+ * Script mode is the only api shape stage 1 analyzes; a structured path request
+ * is a path plus a body, not a CLI string, so its offline stage is `skipped`
+ * with the reason spelled out rather than silently reported as passed.
+ */
+function offlineApiStage(
+	resolved: ResolvedApiRequest,
+	trace?: ValidationTrace,
+): EnvelopeValidationStage {
+	if (!resolved.scriptMode) {
+		return {
+			stage: "offline",
+			source: OFFLINE_GATE_SOURCE,
+			result: "skipped",
+			reason: "structured path request, not a CLI string (GH#354)",
+		};
+	}
+	return {
+		stage: "offline",
+		source: OFFLINE_GATE_SOURCE,
+		result: "passed",
+		...(trace?.offlineVerdict === "warn"
+			? { reason: "analyzer abstained on part of the input" }
+			: {}),
+	};
+}
+
+function apiDeviceStageSource(resolved: ResolvedApiRequest): string {
+	return resolved.scriptMode
+		? API_SCRIPT_DEVICE_STAGE_SOURCE
+		: API_DEVICE_STAGE_SOURCE;
+}
+
+function deviceStageFailed(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationStage {
+	return {
+		stage: "device",
+		source: apiDeviceStageSource(resolved),
+		result: "failed",
+	};
+}
+
+/**
+ * `--validate=false` (including a bare `--raw`). Both stages are listed as
+ * `skipped` rather than omitted, so a consumer reading `stages` never has to
+ * special-case the disabled shape; `enabled: false` already carries the why.
+ */
+function disabledApiValidationMeta(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationMeta {
+	return {
+		enabled: false,
+		source: "disabled",
+		result: "skipped",
+		syntax: false,
+		semantic: resolved.scriptMode ? "not-applicable" : false,
+		stages: [
+			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
+			{
+				stage: "device",
+				source: apiDeviceStageSource(resolved),
+				result: "skipped",
+			},
+		],
 	};
 }
 
@@ -1525,7 +1796,7 @@ export function apiRequestSummaryFromRequest(
 		write: parsed ? isApiMutating(parsed, normalized.path) : false,
 		listen,
 		yes: request.yes ?? false,
-		validate: request.raw ? false : (request.validate ?? true),
+		validate: summarizedValidate(request),
 		raw: request.raw ?? false,
 		format: resolveErrorFormat(request, env),
 		query: buildApiQuery(request),

package/src/cli/api.ts

@@ -94,7 +94,7 @@ export const apiCommand: CliCommandMetadata = {
 		{
 			flag: "--raw",
 			description:
-				"Strip the envelope; emit bare RouterOS JSON. Implies `--validate=false`; does not imply `--yes`.",
+				"Strip the envelope; emit bare RouterOS JSON. Defaults `--validate` to false (an explicit `--validate=true` still runs the gate); does not imply `--yes`.",
 		},
 		{
 			flag: "--yes",

package/src/cli/btest.ts

@@ -23,10 +23,10 @@ import {
 	renderBtestClientEnvelope,
 	renderBtestServerEnvelope,
 } from "../btest.ts";
+import { toYaml } from "../core/yaml.ts";
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import { describeCentrs, parseDuration } from "../index.ts";
 import type { BtestDirection, BtestProtocol } from "../protocols/btest.ts";
-import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	type CliCommandOption,