@tikoci/centrs 0.1.8 → 0.1.9-next.22

package/src/retrieve-sample.ts

@@ -17,15 +17,19 @@ import {
 	buildRetrieveErrorEnvelopeFromResolved,
 	executeRetrieve,
 	type ResolvedRetrieveRequest,
-	type RetrieveEnvelope,
 	type RetrieveRequest,
 	type RetrieveSampleStopReason,
 	type RetrieveSampleSummary,
+	type RetrieveStreamLine,
 	type RetrieveSuccessEnvelope,
 	resolveRetrieveRequest,
 	validateRetrieveRead,
 } from "./retrieve.ts";
-import { failedStreamEnvelope, streamEnvelope } from "./retrieve-stream.ts";
+import {
+	failedStreamEnvelope,
+	streamEnvelope,
+	streamLineEnvelope,
+} from "./retrieve-stream.ts";
 
 export interface RetrieveSampleOptions {
 	/** Ctrl-C: ends the sample with `stopReason: "interrupted"`. */
@@ -33,16 +37,17 @@ export interface RetrieveSampleOptions {
 }
 
 /**
- * Sample one menu: yields a `sample` line per complete read, then exactly one
- * summary (successful, or an error envelope carrying the partial count).
- * Errors before the first read (resolution, validation) yield one error
- * envelope without a summary.
+ * Sample one menu: yields `started` (the full meta), a `sample` line per
+ * complete read (only its `meta.operation`), then exactly one summary
+ * (successful, or an error envelope carrying the partial count). Errors before
+ * the first read (resolution, validation) yield one error envelope without a
+ * summary.
  */
 export async function* retrieveSample(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined> = Bun.env,
 	options: RetrieveSampleOptions = {},
-): AsyncGenerator<RetrieveEnvelope, void, void> {
+): AsyncGenerator<RetrieveStreamLine, void, void> {
 	if (request.wait !== undefined) {
 		yield buildRetrieveErrorEnvelope(
 			request,
@@ -126,6 +131,7 @@ export async function* retrieveSample(
 				sample.durationMs,
 			);
 		}
+		yield streamEnvelope(resolved, validation, null, { kind: "started" });
 		try {
 			while (stopReason === undefined) {
 				const sentAt = Date.now();
@@ -141,7 +147,7 @@ export async function* retrieveSample(
 				// A read still in flight at the stop is not a complete sample.
 				if (result === undefined) break;
 				samples += 1;
-				yield streamEnvelope(resolved, validation, result.data, {
+				yield streamLineEnvelope(result.data, {
 					kind: "sample",
 					index: samples,
 					at: new Date(sentAt).toISOString(),

package/src/retrieve-stream.ts

@@ -2,7 +2,9 @@
  * Line helpers shared by the two streaming forms of `retrieve`: `--follow`
  * (`src/retrieve-follow.ts`) and `--sample` (`src/retrieve-sample.ts`). Each
  * line is one envelope whose `meta.operation.stream` says what it is
- * (`commands/retrieve/README.md` → Follow, Sample).
+ * (`commands/retrieve/README.md` → Follow, Sample). A stream opens with a
+ * full-meta `started` line and ends with a full-meta `summary`; the data lines
+ * between carry only `meta.operation` (#462, #473).
  */
 
 import type { EnvelopeValidationMeta, Tip } from "./core/envelope.ts";
@@ -11,15 +13,16 @@ import {
 	buildRetrieveErrorEnvelopeFromResolved,
 	metaFromResolved,
 	type ResolvedRetrieveRequest,
-	type RetrieveEnvelope,
 	type RetrieveErrorEnvelope,
 	type RetrieveOutputFormat,
+	type RetrieveStreamLine,
+	type RetrieveStreamLineEnvelope,
 	type RetrieveStreamMeta,
 	type RetrieveSuccessEnvelope,
 	retrieveRequestSummary,
 } from "./retrieve.ts";
 
-/** One stream line's envelope: `data` plus its `meta.operation.stream` marker. */
+/** A full-meta stream line (`started`, `synced`, `summary`): `data` plus its marker. */
 export function streamEnvelope(
 	resolved: ResolvedRetrieveRequest,
 	validation: EnvelopeValidationMeta,
@@ -45,6 +48,27 @@ export function streamEnvelope(
 	};
 }
 
+/** A `frame` or `sample` line: only its `meta.operation` (#462, #473). */
+export function streamLineEnvelope(
+	data: unknown,
+	stream: RetrieveStreamMeta,
+	tips: Tip[] = [],
+): RetrieveStreamLineEnvelope {
+	return {
+		ok: true,
+		data,
+		warnings: [],
+		tips,
+		meta: {
+			operation: {
+				kind: "data",
+				objectCount: data === null ? 0 : Array.isArray(data) ? data.length : 1,
+				stream,
+			},
+		},
+	};
+}
+
 /**
  * The failed summary that ends a stream after it started: the error, plus the
  * partial counts as a `summary` marker. `stopReason` is `routeros-error` when
@@ -77,17 +101,19 @@ export function failedStreamEnvelope(
  * One stream envelope as one line: compact NDJSON for every structured format
  * (a multi-line YAML document cannot be a stream line), and a short row for
  * `text`. Router text is JSON-escaped so it cannot carry terminal control
- * bytes.
+ * bytes. In text, only `frame` and `sample` rows are data
+ * ({@link isStreamDataLine}); the CLI writes the rest to stderr, and an empty
+ * string (a `started` line without tips) prints nothing.
  */
 export function renderRetrieveStreamLine(
-	envelope: RetrieveEnvelope,
+	envelope: RetrieveStreamLine,
 	format: RetrieveOutputFormat,
 ): string {
 	if (format !== "text") return JSON.stringify(envelope);
 	if (!envelope.ok) return formatCentrsErrorLine(envelope.error);
 	const stream = envelope.meta.operation?.stream;
 	switch (stream?.kind) {
-		case "notice":
+		case "started":
 			return envelope.tips
 				.map((tip) => `tip: ${tip.message}${tip.fix ? ` ${tip.fix}` : ""}`)
 				.join("\n");
@@ -110,6 +136,12 @@ export function renderRetrieveStreamLine(
 	}
 }
 
+/** Whether a stream line is a data row: text stdout carries only these (#473). */
+export function isStreamDataLine(envelope: RetrieveStreamLine): boolean {
+	const kind = envelope.ok ? envelope.meta.operation?.stream?.kind : undefined;
+	return kind === "frame" || kind === "sample";
+}
+
 function escaped(text: string): string {
 	return JSON.stringify(text).slice(1, -1);
 }

package/src/retrieve.ts

@@ -5,6 +5,7 @@ import type {
 	CommonSettingsMeta,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	StreamLineEnvelope,
 	ValidationTrace,
 } from "./core/envelope.ts";
 import { notReachedReason } from "./core/envelope.ts";
@@ -51,6 +52,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -230,15 +232,20 @@ export interface RetrieveSampleSummary {
  * (`commands/retrieve/README.md` → Follow, Sample). A `frame` is one row
  * change: `upsert` carries the latest full row, `removed` carries
  * `data: null`; `id` is the row identity even when the projection leaves `.id`
- * out of `data`. A `sample` is one complete read; `at` is when it was sent
+ * out of `data`. `observedAt` is when centrs received the reply the frame is
+ * built from (host clock, ISO 8601; a replayed bootstrap change keeps its
+ * arrival time). A `sample` is one complete read; `at` is when it was sent
  * (host clock) and `readMs` how long it took. The two summaries are told apart
- * by their counts (`frames` vs `samples`).
+ * by their counts (`frames` vs `samples`). `started` is the first line of
+ * every stream that got past validation: the full meta, `data: null`, and any
+ * advice in `tips` (#473).
  */
 export type RetrieveStreamMeta =
-	| { kind: "notice" }
+	| { kind: "started" }
 	| {
 			kind: "frame";
 			index: number;
+			observedAt: string;
 			phase: "snapshot" | "live";
 			change: "upsert" | "removed";
 			id: string;
@@ -264,6 +271,23 @@ export interface RetrieveOperationMeta {
 }
 
 export type RetrieveEnvelope = CentrsEnvelope<unknown, RetrieveOperationMeta>;
+
+/**
+ * A `--follow` frame or `--sample` sample line: only its own `meta.operation`
+ * (#462, #473). The rest of the meta is on the stream's `started` and
+ * `summary` lines (and `synced` for `--follow`).
+ */
+export type RetrieveStreamLineEnvelope = StreamLineEnvelope<
+	unknown,
+	Pick<RetrieveOperationMeta, "kind" | "objectCount"> & {
+		stream: RetrieveStreamMeta;
+	}
+>;
+
+/** One `retrieve --follow` or `--sample` line: a full envelope or a data line. */
+export type RetrieveStreamLine = RetrieveEnvelope | RetrieveStreamLineEnvelope;
+/** One `retrieve --follow` line. */
+export type RetrieveFollowLine = RetrieveStreamLine;
 export type RetrieveSuccessEnvelope = CentrsSuccessEnvelope<
 	unknown,
 	RetrieveOperationMeta
@@ -352,7 +376,7 @@ export async function retrieve(
 			summary:
 				"`follow` yields a stream of envelopes instead of one `retrieve` result.",
 			remediation:
-				"Consume it with `retrieveFollow()` (library) or `centrs retrieve … --follow` (CLI): snapshot frames, `synced`, live frames, then a summary.",
+				"Consume it with `retrieveFollow()` (library) or `centrs retrieve … --follow` (CLI): `started`, snapshot frames, `synced`, live frames, then a summary.",
 			context: { capability: "follow" },
 		});
 	}
@@ -362,7 +386,7 @@ export async function retrieve(
 			summary:
 				"`sample` yields a stream of envelopes instead of one `retrieve` result.",
 			remediation:
-				"Consume it with `retrieveSample()` (library) or `centrs retrieve … --sample <interval>` (CLI): one line per complete read, then a summary.",
+				"Consume it with `retrieveSample()` (library) or `centrs retrieve … --sample <interval>` (CLI): `started`, one line per complete read, then a summary.",
 			context: { capability: "sample" },
 		});
 	}
@@ -547,7 +571,7 @@ export function buildRetrieveErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: requestedVia,
 			settings: {},
 		},
@@ -653,7 +677,7 @@ export function renderRetrieveEnvelope(
 		case "text":
 			return (
 				(envelope.ok
-					? renderRetrieveSuccessText(envelope, options)
+					? renderRetrieveSuccessText(envelope)
 					: formatCentrsErrorText(envelope.error, options)) +
 				(envelope.meta.operation?.wait
 					? `\nwait: ${envelope.meta.operation.wait.stopReason}; ${envelope.meta.operation.wait.elapsedMs}ms; ${envelope.meta.operation.wait.attempts} attempt(s), ${envelope.meta.operation.wait.observations} observation(s)`
@@ -664,64 +688,42 @@ export function renderRetrieveEnvelope(
 	}
 }
 
-function renderRetrieveSuccessText(
-	envelope: RetrieveSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
-	const lines: string[] = [];
-	const verbose = options.verbose ?? false;
-	const meta = envelope.meta;
-	const operation = meta.operation;
-
-	if (verbose) {
-		const target = meta.target;
-		lines.push(`target: ${target.input ?? target.host} -> ${target.baseUrl}`);
-		lines.push(`via: ${meta.via}`);
-		lines.push(
-			`sources: via=${formatCoreSource(meta.settings.via)}, host=${formatCoreSource(
-				meta.settings.host,
-			)}, port=${formatCoreSource(meta.settings.port)}, timeout=${formatCoreSource(
-				meta.settings.timeoutMs,
-			)}, format=${formatCoreSource(meta.settings.format)}, validate=${formatCoreSource(
-				meta.settings.validate,
-			)}`,
-		);
-		if (meta.validation?.enabled) {
-			lines.push(`validation: ${meta.validation.source}`);
-		}
-		lines.push("");
-	}
-
-	if (operation?.kind === "attributes") {
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderRetrieveSuccessText(envelope: RetrieveSuccessEnvelope): string {
+	if (envelope.meta.operation?.kind === "attributes") {
 		const attributes = Array.isArray(envelope.data)
 			? (envelope.data as readonly string[])
 			: [];
-		lines.push(...attributes);
-	} else if (typeof envelope.data === "string") {
-		lines.push(envelope.data);
-	} else {
-		lines.push(JSON.stringify(envelope.data, null, 2));
-	}
-
-	if (envelope.warnings.length > 0) {
-		lines.push("");
-		for (const warning of envelope.warnings) {
-			lines.push(`warning [${warning.code}]: ${warning.message}`);
-		}
+		return attributes.join("\n");
 	}
+	return typeof envelope.data === "string"
+		? envelope.data
+		: JSON.stringify(envelope.data, null, 2);
+}
 
-	if (envelope.tips.length > 0) {
-		lines.push("");
-		lines.push("Tips:");
-		for (const item of envelope.tips) {
-			lines.push(`  - [${item.code}] ${item.message}`);
-			if (item.fix) {
-				lines.push(`    fix: ${item.fix}`);
-			}
-		}
+/**
+ * The `--verbose` header of a text-mode retrieve result (stderr, #470); none
+ * for a failure before resolution (`via: null`).
+ */
+export function retrieveVerboseLines(envelope: RetrieveEnvelope): string[] {
+	const meta = envelope.meta;
+	if (meta.via === null) return [];
+	const target = meta.target;
+	const lines = [
+		`target: ${target.input ?? target.host}${target.baseUrl ? ` -> ${target.baseUrl}` : ""}`,
+		`via: ${meta.via}`,
+		`sources: via=${formatCoreSource(meta.settings.via)}, host=${formatCoreSource(
+			meta.settings.host,
+		)}, port=${formatCoreSource(meta.settings.port)}, timeout=${formatCoreSource(
+			meta.settings.timeoutMs,
+		)}, format=${formatCoreSource(meta.settings.format)}, validate=${formatCoreSource(
+			meta.settings.validate,
+		)}`,
+	];
+	if (meta.validation?.enabled) {
+		lines.push(`validation: ${meta.validation.source}`);
 	}
-
-	return lines.join("\n");
+	return lines;
 }
 
 export function retrieveRequestSummary(
@@ -1445,6 +1447,18 @@ function resolveProtocol(
 	return via as ResolvedSetting<RouterOsProtocol>;
 }
 
+/**
+ * The output format a request resolves to (config < env < CLI; the CDB never
+ * sets it). The `--follow` CLI needs it before the first line, because frame
+ * lines carry no `meta.operation.request` (#462).
+ */
+export async function resolveRetrieveOutputFormat(
+	request: RetrieveRequest,
+	env: Record<string, string | undefined> = Bun.env,
+): Promise<RetrieveOutputFormat> {
+	return resolveFormat(request, env, await loadEnvFileDefaults(env)).value;
+}
+
 function resolveFormat(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,

package/src/transfer-fanout.ts

@@ -48,9 +48,11 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
+	redactTargetInput,
 	type SelectionExpansion,
 	type SelectionMember,
 	type SelectionResolveInput,
@@ -95,6 +97,8 @@ export interface TransferFanoutOperationMeta {
 	concurrency: number;
 	summary: FanoutSummary;
 	request: TransferFanoutRequestSummary;
+	/** Hoisted from the targets when every target used the same login (#461). */
+	auth?: { username?: string; passwordProvided: boolean };
 	selection: TransferSelectionSummary;
 }
 
@@ -135,7 +139,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,
 	};
 }
@@ -299,6 +303,9 @@ export async function transferFanout(
 	const concurrency = resolveFanoutConcurrency(options.concurrency, "rest-api");
 
 	if (expansion.empty) {
+		if (isTransferWriteVerb(request.verb)) {
+			throw emptyWriteSelectionError(expansion, `\`${request.verb}\``);
+		}
 		return transferFanoutEnvelope({
 			selection: selectionSummary,
 			concurrency,

package/src/transfer.ts

@@ -60,6 +60,7 @@ import {
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
+	redactTargetInput,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
@@ -1594,7 +1595,7 @@ export function buildTransferErrorEnvelope(
 		warnings: [],
 		tips: [],
 		meta: {
-			target: { input: request.targetInput },
+			target: { input: redactTargetInput(request.targetInput) },
 			via: null,
 			settings: {},
 		},
@@ -1615,19 +1616,16 @@ export function renderTransferEnvelope(
 			return toYaml(envelope);
 		case "text":
 			return envelope.ok
-				? renderSuccessText(envelope, options)
+				? renderSuccessText(envelope)
 				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveFormat(format);
 	}
 }
 
-function renderSuccessText(
-	envelope: TransferSuccessEnvelope,
-	options: { verbose?: boolean },
-): string {
+/** Text mode renders only the data; the CLI writes the rest to stderr (#470). */
+function renderSuccessText(envelope: TransferSuccessEnvelope): string {
 	const lines: string[] = [];
-	const operation = envelope.meta.operation;
 
 	if (Array.isArray(envelope.data)) {
 		// list
@@ -1653,21 +1651,19 @@ function renderSuccessText(
 		lines.push(parts.join(" "));
 	}
 
-	if (options.verbose && operation) {
-		lines.push("");
-		lines.push(`via: ${envelope.meta.via}`);
-	}
-
-	if (envelope.warnings.length > 0) {
-		lines.push("");
-		for (const warning of envelope.warnings) {
-			lines.push(`warning [${warning.code}]: ${warning.message}`);
-		}
-	}
-
 	return lines.join("\n");
 }
 
+/**
+ * The `--verbose` header of a text-mode transfer result (stderr, #470); none
+ * for a failure before resolution.
+ */
+export function transferVerboseLines(envelope: TransferEnvelope): string[] {
+	return envelope.meta.operation && envelope.meta.via !== null
+		? [`via: ${envelope.meta.via}`]
+		: [];
+}
+
 // ── Small helpers ────────────────────────────────────────────────────────────
 
 function uploadSizeHint(request: TransferRequest): number | undefined {