@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/api.ts

@@ -15,6 +15,14 @@
  * structured validation, confirmation, and result-envelope surface.
  */
 
+import { assertNotCmrDashboardPath, cmrRunScriptWarnings } from "./core/cmr.ts";
+import {
+	type CmrFleetRead,
+	cmrFleetCommand,
+	cmrFleetGate,
+	cmrFleetReadable,
+	readCmrFleet,
+} from "./core/cmr-fleet.ts";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
@@ -23,11 +31,13 @@ import type {
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
 	EnvelopeValidationStage,
+	StreamLineEnvelope,
 	Tip,
 	ValidationTrace,
 	Warning,
 } from "./core/envelope.ts";
 import { buildTip, notReachedReason } from "./core/envelope.ts";
+import { sentWriteWarnings } from "./core/fanout.ts";
 import {
 	inspectArgumentNames,
 	inspectChildrenOrEmpty,
@@ -78,6 +88,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -211,19 +222,24 @@ export type ApiStreamStopReason =
 	| "transport-error";
 
 /**
- * Per-line marker on `--stream` NDJSON output: a leading `notice`, one wire
- * reply, or the terminating summary. A `notice` (`data: null`, not counted)
- * comes first only when the request has advice in `tips` — what RouterOS will
- * not report for it — so even a watch that never gets a reply sees it. A frame's `reply` is `re` (a row; `data` is the row) or
- * `empty` (RouterOS `!empty`: zero rows; `data` is `null`). `afterStop` marks a
- * reply that arrived after centrs stopped the stream locally, such as the
- * `!empty` a cancelled listen sends; it is not evidence of an empty table.
+ * Per-line marker on `--stream` NDJSON output: the leading `started`, one wire
+ * reply, or the terminating summary. `started` (`data: null`, not counted)
+ * comes first on every stream that passed its preflight: it carries the full
+ * meta and any advice in `tips` — what RouterOS will not report for the
+ * request — so even a watch that never gets a reply sees both (#473). A frame
+ * carries only its `meta.operation`. Its `reply` is `re` (a row; `data` is the
+ * row) or `empty` (RouterOS `!empty`: zero rows; `data` is `null`), and
+ * `observedAt` is when centrs received it (host clock, ISO 8601; a slow reader
+ * does not move it). `afterStop` marks a reply that arrived after centrs
+ * stopped the stream locally, such as the `!empty` a cancelled listen sends;
+ * it is not evidence of an empty table.
  */
 export type ApiStreamMeta =
-	| { kind: "notice" }
+	| { kind: "started" }
 	| {
 			kind: "frame";
 			index: number;
+			observedAt: string;
 			reply: "re" | "empty";
 			afterStop?: true;
 	  }
@@ -263,6 +279,15 @@ export interface ApiOperationMeta {
 }
 
 export type ApiEnvelope = CentrsEnvelope<unknown, ApiOperationMeta>;
+/** A `--stream` frame line: only its own `meta.operation` (#473). */
+export type ApiStreamFrameEnvelope = StreamLineEnvelope<
+	unknown,
+	Pick<ApiOperationMeta, "kind" | "objectCount"> & {
+		stream: Extract<ApiStreamMeta, { kind: "frame" }>;
+	}
+>;
+/** One `--stream` line: a full envelope (`started`, `summary`, error) or a frame. */
+export type ApiStreamLine = ApiEnvelope | ApiStreamFrameEnvelope;
 export type ApiSuccessEnvelope = CentrsSuccessEnvelope<
 	unknown,
 	ApiOperationMeta
@@ -309,6 +334,8 @@ export interface ResolvedApiRequest {
 	yes: boolean;
 	verbose: boolean;
 	warnings: readonly Warning[];
+	/** A CMR fleet command's reach, read before the write gate (#453). */
+	cmrFleet?: CmrFleetRead;
 }
 
 export async function api(
@@ -340,6 +367,7 @@ export async function apiEnvelope(
 	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveApiRequest(request, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertApiWriteConfirmed(request, resolved);
 		return await runResolvedApi(resolved, trace);
 	} catch (error) {
@@ -393,6 +421,11 @@ export async function runResolvedApi(
 			resolved === request
 				? protocolRequest
 				: buildProtocolApiRequest(resolved),
+			{
+				onSent: () => {
+					trace.dispatched = true;
+				},
+			},
 		);
 		const routerOsFailure = apiRouterOsFailureFromResult(resolved, result);
 		if (routerOsFailure) {
@@ -440,10 +473,11 @@ function apiRouterOsFailureFromResult(
 }
 
 /**
- * The `--stream` path: an async generator yielding one {@link ApiEnvelope} per
- * native reply (`!re` row or `!empty`) to the literal command, then a
- * terminating summary envelope (`data` = {@link ApiStreamSummary}). It never
- * rewrites the command; a `<menu>/listen` endpoint is how to follow changes.
+ * The `--stream` path: an async generator yielding a full-meta `started` line,
+ * one {@link ApiStreamFrameEnvelope} per native reply (`!re` row or `!empty`)
+ * to the literal command, then a terminating summary envelope (`data` =
+ * {@link ApiStreamSummary}). It never rewrites the command; a `<menu>/listen`
+ * endpoint is how to follow changes.
  * Streaming is native-api only — a `rest-api` (or otherwise unresolved)
  * transport yields a single error envelope. `--count`/`--duration` and
  * `externalSignal` (Ctrl-C) bound it. Errors before the first frame
@@ -457,7 +491,7 @@ export async function* apiStream(
 	env: Record<string, string | undefined> = Bun.env,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
-): AsyncGenerator<ApiEnvelope, void, void> {
+): AsyncGenerator<ApiStreamLine, void, void> {
 	// `apiStream` is inherently the streaming surface, so force `stream` on the
 	// request: otherwise a caller that omits it would resolve `via` to the
 	// rest-api default and be rejected. An explicit `--via rest-api` still
@@ -466,6 +500,7 @@ export async function* apiStream(
 	let resolved: ResolvedApiRequest | undefined;
 	try {
 		resolved = await resolveApiRequest(streamRequest, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertApiWriteConfirmed(streamRequest, resolved);
 		if (resolved.via.value !== "native-api") {
 			throw new CentrsError({
@@ -490,16 +525,18 @@ async function* streamResolvedApi(
 	request: ResolvedApiRequest,
 	externalSignal?: AbortSignal,
 	onListening?: () => void,
-): AsyncGenerator<ApiEnvelope, void, void> {
+): AsyncGenerator<ApiStreamLine, void, void> {
 	const backend = adapterForResolved(request);
 
 	let resolved = request;
 	let validation: EnvelopeValidationMeta;
+	let validationTips: Tip[] = [];
 	const trace: ValidationTrace = {};
 	try {
 		if (resolved.validate.value) {
 			const result = await validateApiRequest(resolved, backend, trace);
 			validation = result.validation;
+			validationTips = result.tips;
 			// The boolean probe below runs after the gate passed (GH#435).
 			trace.validation = validation;
 			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
@@ -512,9 +549,27 @@ async function* streamResolvedApi(
 		return;
 	}
 
-	// Request-shape advice is known before the first reply: deliver it first,
-	// and keep it on whichever terminal summary follows (#409 review).
-	const tips = streamTips(resolved);
+	// Request-shape advice is known before the first reply: deliver it on
+	// `started`, and keep it on whichever terminal summary follows (#409 review).
+	// The gate's own tips are the same advice the one-shot path returns.
+	const tips = [...validationTips, ...streamTips(resolved)];
+	// Arrival times in wire order, stamped by the synchronous reply tap: the
+	// session queues replies, so a slow reader must not move them. Read by a
+	// head index, not `shift()`, which is O(n) per frame on a backlog.
+	const arrivals: number[] = [];
+	let arrivalsHead = 0;
+	const nextArrival = (): number => {
+		const at = arrivals[arrivalsHead] ?? Date.now();
+		arrivalsHead += 1;
+		if (arrivalsHead >= arrivals.length) {
+			arrivals.length = 0;
+			arrivalsHead = 0;
+		} else if (arrivalsHead >= 1024 && arrivalsHead * 2 >= arrivals.length) {
+			arrivals.splice(0, arrivalsHead);
+			arrivalsHead = 0;
+		}
+		return at;
+	};
 	const controller = new AbortController();
 	const startedAt = Date.now();
 	const counts = { frames: 0, rows: 0, empty: 0 };
@@ -555,15 +610,21 @@ async function* streamResolvedApi(
 	}
 
 	try {
-		// A consumer may return immediately after this notice; keep it inside
+		// A consumer may return immediately after this line; keep it inside
 		// the session cleanup scope, just like every wire reply.
-		if (tips.length > 0) {
-			yield streamNoticeEnvelope(resolved, validation, tips);
-		}
+		yield streamStartedEnvelope(resolved, validation, tips);
 		const protocolRequest = buildProtocolApiRequest(resolved);
 		for await (const reply of backend.stream(protocolRequest, {
 			signal: controller.signal,
-			onListening,
+			onReply: (tapped) => {
+				if (tapped.type === "re" || tapped.type === "empty") {
+					arrivals.push(Date.now());
+				}
+			},
+			onListening: () => {
+				trace.dispatched = true;
+				onListening?.();
+			},
 			onCancelUnacknowledged: () => {
 				cancelUnacknowledged = true;
 			},
@@ -575,7 +636,7 @@ async function* streamResolvedApi(
 			counts.frames += 1;
 			if (reply.type === "empty") counts.empty += 1;
 			else counts.rows += 1;
-			yield streamFrameEnvelope(resolved, validation, reply, counts.frames);
+			yield streamFrameEnvelope(reply, counts.frames, nextArrival());
 			// `--count` counts rows only: an empty tick must never use up the
 			// count before the data it is waiting for arrives.
 			if (
@@ -602,7 +663,7 @@ async function* streamResolvedApi(
 			done,
 		);
 	} catch (error) {
-		const envelope = buildApiErrorEnvelopeFromResolved(resolved, error);
+		const envelope = buildApiErrorEnvelopeFromResolved(resolved, error, trace);
 		envelope.meta.validation = validation;
 		envelope.warnings = [...envelope.warnings, ...cancellationWarnings()];
 		envelope.tips = [...envelope.tips, ...tips];
@@ -628,29 +689,39 @@ async function* streamResolvedApi(
 }
 
 function streamFrameEnvelope(
-	resolved: ResolvedApiRequest,
-	validation: EnvelopeValidationMeta,
 	reply: ProtocolStreamReply,
 	index: number,
-): ApiSuccessEnvelope {
+	observedAt: number,
+): ApiStreamFrameEnvelope {
 	const data = reply.type === "empty" ? null : reply.attributes;
-	const meta = metaFromResolved(resolved, validation, data);
-	meta.operation.stream = {
-		kind: "frame",
-		index,
-		reply: reply.type,
-		...(reply.afterStop ? { afterStop: true as const } : {}),
+	return {
+		ok: true,
+		data,
+		warnings: [],
+		tips: [],
+		meta: {
+			operation: {
+				kind: "api",
+				objectCount: countResultObjects(data),
+				stream: {
+					kind: "frame",
+					index,
+					observedAt: new Date(observedAt).toISOString(),
+					reply: reply.type,
+					...(reply.afterStop ? { afterStop: true as const } : {}),
+				},
+			},
+		},
 	};
-	return { ok: true, data, warnings: [], tips: [], meta };
 }
 
-function streamNoticeEnvelope(
+function streamStartedEnvelope(
 	resolved: ResolvedApiRequest,
 	validation: EnvelopeValidationMeta,
 	tips: Tip[],
 ): ApiSuccessEnvelope {
 	const meta = metaFromResolved(resolved, validation, null);
-	meta.operation.stream = { kind: "notice" };
+	meta.operation.stream = { kind: "started" };
 	return { ok: true, data: null, warnings: [], tips, meta };
 }
 
@@ -1029,9 +1100,10 @@ export async function resolveApiRequest(
 		insecure,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: connection
-			? [...connection.warnings]
-			: (cdbResolution?.warnings ?? []),
+		warnings: [
+			...(connection ? connection.warnings : (cdbResolution?.warnings ?? [])),
+			...(verb === "run" ? cmrRunScriptWarnings(normalized.path) : []),
+		],
 	};
 }
 
@@ -1081,8 +1153,9 @@ export function mapMethodToVerb(method: ApiMethod): ApiVerb {
 }
 
 /**
- * Read-only **iff** the method is `GET`, or the terminal path verb is
- * `print`/`get`/`listen`. Everything else is a write needing confirmation. Keyed
+ * Read-only **iff** the method is `GET`, the terminal path verb is
+ * `print`/`get`/`listen`, or it is a POST to exactly `/console/inspect`. Everything
+ * else is a write needing confirmation. Keyed
  * on the verb/method, not the wire HTTP method — a `POST …/print` paged read does
  * not prompt; `--listen` never relaxes the gate (a streaming-but-mutating
  * `/system/license/renew` still confirms). See `commands/api/README.md`.
@@ -1091,6 +1164,13 @@ export function isApiMutating(method: ApiMethod, path: string): boolean {
 	if (method === "GET") {
 		return false;
 	}
+	// `/console/inspect` describes the command tree and parses input; it never
+	// runs it, so a POST to it (the only way to pass `request=`) is a read
+	// (#458). POST and the exact path only: PUT/PATCH/DELETE map to
+	// add/set/remove, and an abbreviation stays a write.
+	if (method === "POST" && pathTokens(path).join("/") === "console/inspect") {
+		return false;
+	}
 	const terminal = pathTokens(path).at(-1);
 	if (terminal === "print" || terminal === "get" || terminal === "listen") {
 		return false;
@@ -1494,9 +1574,18 @@ async function assertApiWriteConfirmed(
 	if (!isApiMutating(resolved.method, resolved.path) || resolved.yes) {
 		return;
 	}
+	const fleet = resolved.cmrFleet
+		? cmrFleetGate(
+				resolved.cmrFleet,
+				resolved.target.identity ??
+					resolved.target.input ??
+					resolved.target.host,
+			)
+		: undefined;
 	if (request.stdinIsTty ?? process.stdin.isTTY) {
 		const confirmed = await (request.confirm ?? promptForWriteConfirmation)(
-			`Run mutating ${resolved.method} ${resolved.path} over ${resolved.via.value}? Type yes to continue: `,
+			fleet?.prompt ??
+				`Run mutating ${resolved.method} ${resolved.path} over ${resolved.via.value}? Type yes to continue: `,
 		);
 		if (confirmed) {
 			return;
@@ -1504,7 +1593,9 @@ async function assertApiWriteConfirmed(
 	}
 	throw new CentrsError({
 		code: "usage/confirmation-required",
-		summary: `A mutating ${resolved.method} ${resolved.path} request requires explicit confirmation.`,
+		summary:
+			fleet?.summary ??
+			`A mutating ${resolved.method} ${resolved.path} request requires explicit confirmation.`,
 		remediation:
 			"Pass `--yes` in non-interactive automation, or answer `yes` at the TTY prompt after reviewing the request.",
 		context: {
@@ -1512,10 +1603,61 @@ async function assertApiWriteConfirmed(
 			path: resolved.path,
 			method: resolved.method,
 			via: resolved.via.value,
+			...fleet?.context,
 		},
 	});
 }
 
+/**
+ * #453: a mutating CMR fleet request (`POST /cmr/device/reboot`, `PUT
+ * /cmr/vlan`) is one request to the controller that acts on every device it
+ * selects. Read the controller's inventory before the gate so the gate names
+ * that reach, and add the fleet warnings, with or without `--yes`. A `PUT`,
+ * `PATCH` or `DELETE` is the menu's `add`, `set` or `remove`; the `*id` is its
+ * `numbers`.
+ */
+async function withCmrFleetScope(
+	resolved: ResolvedApiRequest,
+): Promise<ResolvedApiRequest> {
+	if (resolved.scriptMode || !isApiMutating(resolved.method, resolved.path)) {
+		return resolved;
+	}
+	const command = cmrFleetCommand(
+		resolved.verb === "run"
+			? resolved.path
+			: `${resolved.path}/${resolved.verb}`,
+		resolved.id === undefined
+			? resolved.body
+			: { ...resolved.body, numbers: resolved.id },
+	);
+	if (!command || !cmrFleetReadable(resolved.via.value)) return resolved;
+	const adapter = createProtocolAdapter({
+		protocol: resolved.via.value,
+		host: resolved.target.host,
+		port: resolved.target.port,
+		tls: resolved.target.tls,
+		baseUrl: resolved.target.baseUrl,
+		username: resolved.auth.username,
+		password: resolved.auth.password,
+		timeoutMs: resolved.timeoutMs.value,
+		insecure: resolved.insecure.value,
+	});
+	try {
+		const cmrFleet = await readCmrFleet(
+			command,
+			adapter,
+			resolved.auth.username,
+		);
+		return {
+			...resolved,
+			cmrFleet,
+			warnings: [...resolved.warnings, ...cmrFleet.warnings],
+		};
+	} finally {
+		await adapter.close();
+	}
+}
+
 function assertStreamCapability(resolved: ResolvedApiRequest): void {
 	if (!resolved.stream) {
 		return;
@@ -1534,7 +1676,7 @@ function assertStreamCapability(resolved: ResolvedApiRequest): void {
 		summary:
 			"`--stream` yields incremental replies instead of a one-shot `api` result.",
 		remediation:
-			"Consume the stream via `apiStream()` (library) or `centrs api … --stream` (CLI); both yield an NDJSON envelope per reply frame plus a final summary.",
+			"Consume the stream via `apiStream()` (library) or `centrs api … --stream` (CLI); both yield a `started` line, a line per reply frame, then a final summary.",
 		context: { via: resolved.via.value, capability: "stream" },
 	});
 }
@@ -1678,7 +1820,7 @@ export function buildApiErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: requestedVia,
 			settings: {},
 			operation: {
@@ -1718,7 +1860,14 @@ export function buildApiErrorEnvelopeFromResolved(
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
-		warnings: [...resolved.warnings],
+		warnings: [
+			...resolved.warnings,
+			...sentWriteWarnings(
+				isApiMutating(resolved.method, resolved.path),
+				centrsError,
+				trace,
+			),
+		],
 		tips: [],
 		meta: metaFromResolved(
 			resolved,
@@ -1912,7 +2061,7 @@ export function renderApiEnvelope(
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
-				? renderApiSuccessText(envelope, options)
+				? renderApiSuccessText(envelope)
 				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveFormat(format);
@@ -1924,11 +2073,12 @@ export function renderApiEnvelope(
  * object per line) for both `json` and `yaml`, and a concise human row for
  * `text`. `yaml` deliberately falls back to NDJSON here — YAML's multi-line
  * document form is incompatible with line-delimited streaming. Unlike
- * {@link renderApiEnvelope} this never pretty-prints — every frame and the
- * summary are one line each, so a consumer can read the stream line by line.
+ * {@link renderApiEnvelope} this never pretty-prints — `started`, every frame
+ * and the summary are one line each, so a consumer can read the stream line
+ * by line. In text, a `started` line without tips renders as an empty string.
  */
 export function renderApiStreamLine(
-	envelope: ApiEnvelope,
+	envelope: ApiStreamLine,
 	format: ApiOutputFormat,
 	options: { raw?: boolean; verbose?: boolean } = {},
 ): string {
@@ -1951,13 +2101,15 @@ export function renderApiStreamLine(
 	return JSON.stringify(envelope);
 }
 
-function renderApiStreamFrameText(envelope: ApiSuccessEnvelope): string {
+function renderApiStreamFrameText(
+	envelope: Exclude<ApiStreamLine, ApiErrorEnvelope>,
+): string {
 	const stream = envelope.meta.operation?.stream;
 	if (stream?.kind === "summary") {
 		const empty = stream.empty > 0 ? `, ${stream.empty} empty` : "";
 		return `— ${stream.stopReason}: ${stream.rows} row(s)${empty} in ${stream.durationMs}ms`;
 	}
-	if (stream?.kind === "notice") {
+	if (stream?.kind === "started") {
 		return envelope.tips
 			.map((tip) => `tip: ${tip.message}${tip.fix ? ` ${tip.fix}` : ""}`)
 			.join("\n");
@@ -1985,24 +2137,24 @@ function rawErrorPayload(
 	return payload;
 }
 
-function renderApiSuccessText(
-	envelope: ApiSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines: string[] = [];
-	if (options.verbose) {
-		lines.push(`via: ${envelope.meta.via}`);
-		if (envelope.meta.validation?.source) {
-			lines.push(`validation: ${envelope.meta.validation.source}`);
-		}
-		lines.push("");
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderApiSuccessText(envelope: ApiSuccessEnvelope): string {
+	return typeof envelope.data === "string"
+		? envelope.data
+		: JSON.stringify(envelope.data, null, 2);
+}
+
+/**
+ * The `--verbose` header of a text-mode api result (stderr, #470); none for a
+ * failure before resolution (`via: null`).
+ */
+export function apiVerboseLines(envelope: ApiEnvelope): string[] {
+	if (envelope.meta.via === null) return [];
+	const lines = [`via: ${envelope.meta.via}`];
+	if (envelope.meta.validation?.source) {
+		lines.push(`validation: ${envelope.meta.validation.source}`);
 	}
-	lines.push(
-		typeof envelope.data === "string"
-			? envelope.data
-			: JSON.stringify(envelope.data, null, 2),
-	);
-	return lines.join("\n");
+	return lines;
 }
 
 export function validateApiRequestShape(request: ApiRequest): void {
@@ -2020,6 +2172,7 @@ export function validateApiRequestShape(request: ApiRequest): void {
 		});
 	}
 	const normalized = normalizeApiEndpoint(request.endpoint);
+	assertNotCmrDashboardPath(normalized.path);
 	if (pathTokens(normalized.path).length === 0) {
 		throw new CentrsError({
 			code: "input/invalid-path",
@@ -2096,11 +2249,17 @@ export function apiRequestSummaryFromRequest(
 		validate: summarizedValidate(request),
 		raw: request.raw ?? false,
 		format: resolveErrorFormat(request, env),
-		query: summaryQuery(request),
-		proplist: buildApiProplist(request),
+		// Empty lists are omitted, as in the resolved summary, so a fan-out
+		// target's request compares equal to the outer one (#461).
+		query: nonEmpty(summaryQuery(request)),
+		proplist: nonEmpty(buildApiProplist(request)),
 	};
 }
 
+function nonEmpty(list: string[] | undefined): string[] | undefined {
+	return list && list.length > 0 ? list : undefined;
+}
+
 /** {@link buildApiQuery} for an error summary, which must not throw on the expression it reports. */
 function summaryQuery(request: ApiRequest): string[] | undefined {
 	try {

package/src/btest.ts

@@ -37,7 +37,12 @@ import {
 	handleBtestServerConnection,
 	runBtestClientSession,
 } from "./protocols/btest-session.ts";
-import { resolveAuth, resolveCdb, resolveTarget } from "./resolver/index.ts";
+import {
+	redactTargetInput,
+	resolveAuth,
+	resolveCdb,
+	resolveTarget,
+} from "./resolver/index.ts";
 
 export { BTEST_PORT, BTEST_UDP_PORT_START };
 
@@ -424,7 +429,7 @@ function buildClientErrorEnvelope(
 			target: {
 				...(request.host !== undefined ? { host: request.host } : {}),
 				...(request.targetInput !== undefined
-					? { input: request.targetInput }
+					? { input: redactTargetInput(request.targetInput) }
 					: {}),
 				port: operation.controlPort,
 			},