@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/execute-fanout.ts

@@ -33,6 +33,7 @@ import {
 	buildFanoutResolveFailure,
 	commonVia,
 	defaultFanoutSleep,
+	mayRetryUnsentWrite,
 	resolveFanoutConcurrency,
 	runFanout,
 	summarizeFanout,
@@ -59,9 +60,11 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	redactTargetInput,
 	type SelectionExpansion,
 	type SelectionMember,
 	type SelectionResolveInput,
@@ -84,6 +87,8 @@ export interface ExecuteFanoutOperationMeta {
 	concurrency: number;
 	summary: FanoutSummary;
 	request: ExecuteRequestSummary;
+	/** Hoisted from the targets when every target used the same login (#461). */
+	auth?: { username?: string; passwordProvided: boolean };
 	selection: ExecuteSelectionSummary;
 }
 
@@ -105,6 +110,7 @@ export interface ExecuteFanoutInternals {
 	) => Promise<SelectionExpansion>;
 	execute?: (
 		resolved: ResolvedExecuteRequest,
+		trace: ValidationTrace,
 	) => Promise<ExecuteSuccessEnvelope>;
 	sleep?: (ms: number) => Promise<void>;
 }
@@ -123,7 +129,7 @@ function summarizeSelection(
 		where: selection.where.map((clause) => `${clause.key}=${clause.value}`),
 		all: selection.all,
 		default: selection.default,
-		positionals: selection.positionals,
+		positionals: selection.positionals.map((value) => redactTargetInput(value)),
 		quickchr: selection.quickchr,
 	};
 }
@@ -223,6 +229,12 @@ export async function executeFanout(
 	const concurrency = resolveFanoutConcurrency(options.concurrency, via);
 
 	if (expansion.empty) {
+		if (global.summary.write) {
+			throw emptyWriteSelectionError(
+				expansion,
+				`\`${global.summary.command}\``,
+			);
+		}
 		return executeFanoutEnvelope({
 			selection: selectionSummary,
 			concurrency,
@@ -308,6 +320,8 @@ export async function executeFanout(
 				),
 				member,
 			),
+		mayRetry: (resolved) =>
+			mayRetryUnsentWrite(global.summary.write, traces.get(resolved)),
 		sleep,
 	});
 

package/src/execute.ts

@@ -1,3 +1,16 @@
+import {
+	assertNotCmrDashboardIl,
+	assertNotCmrDashboardPath,
+	cmrRunScriptWarnings,
+	cmrScriptWarnings,
+} from "./core/cmr.ts";
+import {
+	type CmrFleetRead,
+	cmrFleetCommand,
+	cmrFleetGate,
+	cmrFleetReadable,
+	readCmrFleet,
+} from "./core/cmr-fleet.ts";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
@@ -16,6 +29,7 @@ import {
 	canonicalizeExecuteCommand,
 	isWriteShaped,
 } from "./core/execute-command.ts";
+import { sentWriteWarnings } from "./core/fanout.ts";
 import { inspectArgumentNames, pathTokens } from "./core/inspect.ts";
 import { mapRouterOsResultError } from "./core/routeros-errors.ts";
 import { routerOsStringLiteral } from "./core/routeros-string.ts";
@@ -37,6 +51,7 @@ import {
 	getProtocolPlan,
 	type ProtocolAdapter,
 	type ProtocolExecuteResult,
+	type ProtocolSendOptions,
 	plannedProtocols,
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
@@ -57,6 +72,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -163,6 +179,8 @@ export interface ResolvedExecuteRequest {
 	yes: boolean;
 	verbose: boolean;
 	warnings: readonly Warning[];
+	/** A CMR fleet command's reach, read before the write gate (#453). */
+	cmrFleet?: CmrFleetRead;
 }
 
 export async function execute(
@@ -194,6 +212,7 @@ export async function executeEnvelope(
 	const trace: ValidationTrace = {};
 	try {
 		resolved = await resolveExecuteRequest(request, env);
+		resolved = await withCmrFleetScope(resolved);
 		await assertWriteConfirmed(request, resolved);
 		return await runResolvedExecute(resolved, trace);
 	} catch (error) {
@@ -288,7 +307,11 @@ export async function runResolvedExecute(
 		// reports the gate that actually passed rather than a guess.
 		trace.validation = validation;
 
-		const result = await runCommand(resolved, backend);
+		const result = await runCommand(resolved, backend, {
+			onSent: () => {
+				trace.dispatched = true;
+			},
+		});
 		const routerOsFailure = routerOsFailureFromResult(
 			result,
 			resolved.via.value,
@@ -319,6 +342,7 @@ export async function resolveExecuteRequest(
 ): Promise<ResolvedExecuteRequest> {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
+	assertNotStructuredDashboard(canonical);
 	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
@@ -450,9 +474,12 @@ export async function resolveExecuteRequest(
 		maxResultsBytes,
 		yes: request.yes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: connection
-			? [...connection.warnings]
-			: (cdbResolution?.warnings ?? []),
+		warnings: [
+			...(connection ? connection.warnings : (cdbResolution?.warnings ?? [])),
+			...(canonical.mode === "structured"
+				? cmrRunScriptWarnings(`${canonical.path}/${canonical.verb}`)
+				: cmrScriptWarnings(canonical.input)),
+		],
 	};
 }
 
@@ -477,6 +504,7 @@ export function resolveExecuteGlobalContext(
 ): ExecuteGlobalContext {
 	validateExecuteRequestShape(request);
 	const canonical = canonicalizeExecuteCommand(request.command);
+	assertNotStructuredDashboard(canonical);
 	const via = resolveExecuteProtocol(request, env, undefined, config);
 	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -556,7 +584,7 @@ export function buildExecuteErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: requestedVia,
 			settings: {},
 			operation: {
@@ -599,7 +627,14 @@ export function buildExecuteErrorEnvelopeFromResolved(
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
-		warnings: [...resolved.warnings],
+		warnings: [
+			...resolved.warnings,
+			...sentWriteWarnings(
+				isWriteShaped(resolved.canonical),
+				centrsError,
+				trace,
+			),
+		],
 		tips: resolvedExecuteTips(resolved),
 		meta: metaFromResolved(
 			resolved,
@@ -729,7 +764,7 @@ function deviceStageSource(resolved: ResolvedExecuteRequest): string {
  * judge. An absent verdict means the caller did not thread a trace, so say
  * nothing extra rather than invent the reason.
  */
-function offlineStagePassed(
+export function offlineStagePassed(
 	verdict: ValidationTrace["offlineVerdict"],
 ): EnvelopeValidationStage {
 	return {
@@ -748,7 +783,7 @@ function offlineStagePassed(
  * a consumer reading `stages` never has to special-case the disabled shape.
  * `reason` is left off — `enabled: false` already says why.
  */
-function disabledValidationMeta(): EnvelopeValidationMeta {
+export function disabledValidationMeta(): EnvelopeValidationMeta {
 	return {
 		enabled: false,
 		source: "disabled",
@@ -774,7 +809,7 @@ export function renderExecuteEnvelope(
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
-				? renderExecuteSuccessText(envelope, options)
+				? renderExecuteSuccessText(envelope)
 				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveOutputFormat(format);
@@ -888,6 +923,7 @@ async function validateConsoleParseCommand(
 	});
 	// Throws validation/syntax or validation/unknown-attribute on a bad parse.
 	classifyParseResult(result.ret ?? "", resolved.command, resolved.via.value);
+	assertNotCmrDashboardIl(result.ret ?? "", resolved.command);
 	return {
 		enabled: true,
 		source: `:put [:parse ...] over ${resolved.via.value}`,
@@ -908,7 +944,7 @@ async function validateConsoleParseCommand(
  * `warn` is an abstention, and saying so is the difference between "the analyzer
  * read all of this" and "it declined to judge part of it".
  */
-function passedStages(
+export function passedStages(
 	offline: OfflineGateResult,
 	deviceSource: string,
 ): EnvelopeValidationStage[] {
@@ -939,6 +975,7 @@ export async function validateRouterOsScript(
 	via: RouterOsProtocol,
 ): Promise<void> {
 	const script = `:put [:parse ${routerOsStringLiteral(command)}]`;
+	let il: string;
 	try {
 		// 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 /
@@ -947,7 +984,8 @@ export async function validateRouterOsScript(
 		// 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 ?? "", command, via);
+		il = result.ret ?? "";
+		classifyParseResult(il, command, via);
 	} catch (error) {
 		// The preflight is a syntax gate, but `backend.execute` also surfaces
 		// connection and authentication failures (login happens lazily here).
@@ -984,6 +1022,20 @@ export async function validateRouterOsScript(
 			causeData: syntaxCause(error),
 		});
 	}
+	assertNotCmrDashboardIl(il, command);
+}
+
+/**
+ * The plain spellings of the dashboard are refused before anything is dialed.
+ * Every other spelling (a relative menu change, a block, a substitution) is
+ * found in the `:parse` return, so it is refused by validation.
+ */
+function assertNotStructuredDashboard(
+	canonical: CanonicalExecuteCommand,
+): void {
+	if (canonical.mode === "structured") {
+		assertNotCmrDashboardPath(`${canonical.path}/${canonical.verb}`);
+	}
 }
 
 /**
@@ -998,22 +1050,32 @@ function isPreflightTransportError(error: CentrsError): boolean {
 async function runCommand(
 	resolved: ResolvedExecuteRequest,
 	backend: ProtocolAdapter,
+	options: ProtocolSendOptions,
 ): Promise<ProtocolExecuteResult> {
 	if (resolved.via.value === "mac-telnet" || resolved.via.value === "ssh") {
 		// Console transports: run the raw CLI line and capture the console output
 		// (structured path-POST / tagged talk do not apply). ssh runs it as a
 		// single `ssh host "<command>"`; mac-telnet drives the L2 console.
-		return backend.execute({ path: "", command: "", script: resolved.command });
+		return backend.execute(
+			{ path: "", command: "", script: resolved.command },
+			options,
+		);
 	}
 	if (resolved.canonical.mode === "script") {
-		return backend.execute({ path: "", command: "", script: resolved.command });
+		return backend.execute(
+			{ path: "", command: "", script: resolved.command },
+			options,
+		);
 	}
-	return backend.execute({
-		path: resolved.canonical.path,
-		command: resolved.canonical.verb,
-		attributes: resolved.canonical.attributes,
-		queries: resolved.canonical.queries,
-	});
+	return backend.execute(
+		{
+			path: resolved.canonical.path,
+			command: resolved.canonical.verb,
+			attributes: resolved.canonical.attributes,
+			queries: resolved.canonical.queries,
+		},
+		options,
+	);
 }
 
 async function assertWriteConfirmed(
@@ -1023,9 +1085,13 @@ async function assertWriteConfirmed(
 	if (!isWriteShaped(resolved.canonical) || resolved.yes) {
 		return;
 	}
+	const fleet = resolved.cmrFleet
+		? cmrFleetGate(resolved.cmrFleet, targetName(resolved))
+		: undefined;
 	if (request.stdinIsTty ?? process.stdin.isTTY) {
 		const confirmed = await (request.confirm ?? promptForWriteConfirmation)(
-			`Run write-shaped RouterOS command over ${resolved.via.value}? Type yes to continue: `,
+			fleet?.prompt ??
+				`Run write-shaped RouterOS command over ${resolved.via.value}? Type yes to continue: `,
 		);
 		if (confirmed) {
 			return;
@@ -1034,6 +1100,7 @@ async function assertWriteConfirmed(
 	throw new CentrsError({
 		code: "usage/confirmation-required",
 		summary:
+			fleet?.summary ??
 			"Write-shaped RouterOS execute commands require explicit confirmation.",
 		remediation:
 			"Pass `--yes` in non-interactive automation, or answer `yes` at the TTY prompt after reviewing the command.",
@@ -1042,10 +1109,75 @@ async function assertWriteConfirmed(
 			path: resolved.canonical.path,
 			verb: resolved.canonical.verb,
 			via: resolved.via.value,
+			...fleet?.context,
 		},
 	});
 }
 
+function targetName(resolved: ResolvedExecuteRequest): string {
+	return (
+		resolved.target.identity ?? resolved.target.input ?? resolved.target.host
+	);
+}
+
+/**
+ * #453: a write-shaped CMR fleet command (`/cmr/device/reboot labels=all`) 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`. Structured input only:
+ * a script's selectors (`[find …]`, positionals) are not resolved.
+ */
+async function withCmrFleetScope(
+	resolved: ResolvedExecuteRequest,
+): Promise<ResolvedExecuteRequest> {
+	const { canonical } = resolved;
+	if (canonical.mode !== "structured" || !isWriteShaped(canonical)) {
+		return resolved;
+	}
+	const command = cmrFleetCommand(
+		`${canonical.path}/${canonical.verb}`,
+		canonical.attributes,
+	);
+	if (!command) return resolved;
+	if (!cmrFleetReadable(resolved.via.value)) {
+		return {
+			...resolved,
+			cmrFleet: {
+				scope: {
+					command: command.command,
+					unresolved: `${resolved.via.value} has no structured read`,
+				},
+				warnings: [],
+			},
+		};
+	}
+	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();
+	}
+}
+
 export async function promptForWriteConfirmation(
 	prompt: string,
 ): Promise<boolean> {
@@ -1399,27 +1531,28 @@ function applyMaxResultsBudget(
 	return envelope;
 }
 
-function renderExecuteSuccessText(
-	envelope: ExecuteSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines: string[] = [];
-	if (options.verbose) {
-		lines.push(
-			`target: ${envelope.meta.target.input ?? envelope.meta.target.host}`,
-		);
-		lines.push(`via: ${envelope.meta.via}`);
-		if (envelope.meta.validation?.source) {
-			lines.push(`validation: ${envelope.meta.validation.source}`);
-		}
-		lines.push("");
-	}
-	if (typeof envelope.data === "string") {
-		lines.push(envelope.data);
-	} else {
-		lines.push(JSON.stringify(envelope.data, null, 2));
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderExecuteSuccessText(envelope: ExecuteSuccessEnvelope): string {
+	return typeof envelope.data === "string"
+		? envelope.data
+		: JSON.stringify(envelope.data, null, 2);
+}
+
+/**
+ * The `--verbose` header of a text-mode execute result (stderr, #470). A
+ * failure after resolution still names its target; one before has no
+ * transport (`via: null`) and no header.
+ */
+export function executeVerboseLines(envelope: ExecuteEnvelope): string[] {
+	if (envelope.meta.via === null) return [];
+	const lines = [
+		`target: ${envelope.meta.target.input ?? envelope.meta.target.host}`,
+		`via: ${envelope.meta.via}`,
+	];
+	if (envelope.meta.validation?.source) {
+		lines.push(`validation: ${envelope.meta.validation.source}`);
 	}
-	return lines.join("\n");
+	return lines;
 }
 
 function syntaxCause(error: unknown): unknown {

package/src/index.ts

@@ -6,6 +6,8 @@ export {
 	type ApiOutputFormat,
 	type ApiRequest,
 	type ApiRequestSummary,
+	type ApiStreamFrameEnvelope,
+	type ApiStreamLine,
 	type ApiStreamMeta,
 	type ApiStreamStopReason,
 	type ApiStreamSummary,
@@ -16,6 +18,7 @@ export {
 	apiOutputFormats,
 	apiRequestSummaryFromRequest,
 	apiStream,
+	apiVerboseLines,
 	buildApiBody,
 	buildApiErrorEnvelope,
 	buildApiErrorEnvelopeFromResolved,
@@ -81,10 +84,12 @@ export {
 	type EnvelopeValidationMeta,
 	type EnvelopeValidationStage,
 	type FanoutData,
+	type FanoutMemberOperation,
 	type FanoutSummary,
 	normalizeWarnings,
 	type SettingSource,
 	type SettingSourceKind,
+	type StreamLineEnvelope,
 	type ValidationTrace,
 	type Warning,
 } from "./core/envelope.ts";
@@ -92,6 +97,8 @@ export {
 	buildFanoutEnvelope,
 	buildFanoutResolveFailure,
 	commonVia,
+	compactFanoutTargets,
+	expandFanoutTarget,
 	FANOUT_BACKOFF_BASE_MS,
 	FANOUT_CONCURRENCY_DEFAULTS,
 	FANOUT_MAX_RETRIES,
@@ -279,6 +286,7 @@ export {
 	execute,
 	executeEnvelope,
 	executeOutputFormats,
+	executeVerboseLines,
 	isWriteShaped,
 	renderExecuteEnvelope,
 	resolveExecuteGlobalContext,
@@ -286,6 +294,23 @@ export {
 	runResolvedExecute,
 	validateExecuteRequestShape,
 } from "./execute.ts";
+export {
+	buildExecuteCmrErrorEnvelope,
+	CMR_VALIDATION_SOURCE,
+	type CmrController,
+	type CmrDevice,
+	type CmrScriptCall,
+	type CmrScriptOutcome,
+	type CmrScriptRow,
+	type ExecuteCmrData,
+	type ExecuteCmrEnvelope,
+	type ExecuteCmrErrorEnvelope,
+	type ExecuteCmrInternals,
+	type ExecuteCmrOperationMeta,
+	type ExecuteCmrRequest,
+	executeCmr,
+	renderExecuteCmrEnvelope,
+} from "./execute-cmr.ts";
 export {
 	buildExecuteFanoutErrorEnvelope,
 	type ExecuteFanoutData,
@@ -587,6 +612,7 @@ export {
 	type RetrieveEnvelope,
 	type RetrieveErrorEnvelope,
 	type RetrieveFollowCounts,
+	type RetrieveFollowLine,
 	type RetrieveFollowSettings,
 	type RetrieveFollowStopReason,
 	type RetrieveFollowSummary,
@@ -599,15 +625,19 @@ export {
 	type RetrieveSampleSettings,
 	type RetrieveSampleStopReason,
 	type RetrieveSampleSummary,
+	type RetrieveStreamLine,
+	type RetrieveStreamLineEnvelope,
 	type RetrieveStreamMeta,
 	type RetrieveSuccessEnvelope,
 	type RetrieveWarning,
 	renderRetrieveEnvelope,
 	resolveRetrieveGlobalContext,
+	resolveRetrieveOutputFormat,
 	resolveRetrieveRequest,
 	retrieve,
 	retrieveEnvelope,
 	retrieveOutputFormats,
+	retrieveVerboseLines,
 	runResolvedRetrieve,
 	validateRetrieveRequestShape,
 } from "./retrieve.ts";
@@ -633,7 +663,10 @@ export {
 	type RetrieveSampleOptions,
 	retrieveSample,
 } from "./retrieve-sample.ts";
-export { renderRetrieveStreamLine } from "./retrieve-stream.ts";
+export {
+	isStreamDataLine,
+	renderRetrieveStreamLine,
+} from "./retrieve-stream.ts";
 export { type RetrieveWaitOptions, retrieveWait } from "./retrieve-wait.ts";
 export {
 	buildSettingsErrorEnvelope,
@@ -701,6 +734,7 @@ export {
 	transferEnvelope,
 	transferMethods,
 	transferOutputFormats,
+	transferVerboseLines,
 	transferVerbs,
 	validateTransferRequestShape,
 } from "./transfer.ts";

package/src/mcp/safety.ts

@@ -19,6 +19,11 @@ import {
 import { CentrsError } from "../errors.ts";
 import type { McpWritePolicy } from "../mcp.ts";
 import { parseCommentKv } from "../resolver/comment-kv.ts";
+import {
+	assertNoTargetCredentials,
+	assertNoTargetPassword,
+	redactTargetInput,
+} from "../resolver/target.ts";
 import type { CentrsMcpConfig } from "./config.ts";
 
 export interface RegisteredTarget {
@@ -68,10 +73,16 @@ export function resolveRegisteredTarget(
 	cdb: LoadedCdb,
 	target: string,
 ): RegisteredTarget {
+	// Before the lookup, whose refusal echoes the target (#478).
+	assertNoTargetPassword(target);
 	let entry: DevicesShowItem;
 	try {
 		entry = showDevice({ cdb, target }).data.entry;
 	} catch (error) {
+		// Preserve registered identities; mask credential-shaped lookup failures.
+		if (redactTargetInput(target) !== target) {
+			assertNoTargetCredentials(target);
+		}
 		if (error instanceof CentrsError && error.code === "cdb/not-found-target") {
 			throw new CentrsError({
 				code: "cdb/target-not-registered",

package/src/mcp/tools.ts

@@ -36,6 +36,7 @@ import {
 import type { CommentKvUpdate } from "../resolver/comment-kv.ts";
 import { parseBbox, parseNear } from "../resolver/geo.ts";
 import { parseDuration } from "../resolver/settings.ts";
+import { redactTargetInput } from "../resolver/target.ts";
 import { retrieveEnvelope } from "../retrieve.ts";
 import {
 	buildRetrieveFanoutErrorEnvelope,
@@ -89,7 +90,9 @@ function mcpErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: context.target ? { input: context.target } : {},
+			target: context.target
+				? { input: redactTargetInput(context.target) }
+				: {},
 			via: null,
 			settings: {},
 			operation: { kind: "mcp", tool },