@tikoci/centrs 0.1.7 → 0.1.8-next.0

package/src/settings.ts

@@ -26,7 +26,11 @@ import type {
 import { buildTip } from "./core/envelope.ts";
 import { toYaml } from "./core/yaml.ts";
 import { loadCdb, resolveDevicesSettings } from "./devices.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
 	DEFAULT_RECORD_TARGET,
@@ -38,7 +42,6 @@ import {
 	readSettingsFileRaw,
 	resolveOptionalIntegerSetting,
 } from "./resolver/index.ts";
-import { retrieveOutputFormats } from "./retrieve.ts";
 
 // ── Envelope shape ───────────────────────────────────────────────────────────
 
@@ -155,6 +158,12 @@ const TRANSFER_VIA_VALUES = [
 	"ftp",
 ] as const;
 
+/**
+ * The formats every command renders. `ndjson` is per-command (`api`,
+ * `retrieve`), so a shared `format` setting must not select it.
+ */
+const sharedOutputFormats = ["text", "json", "yaml"] as const;
+
 /**
  * The 13 `CENTRS_*` keys `settings` fully manages (validated get/set/print/
  * reset). `commands/settings/README.md` ("Not yet wired — exclude from v1")
@@ -169,14 +178,14 @@ export const settingsManagedKeys: readonly SettingsKeyDef[] = [
 		parse: (raw) => {
 			const value = raw.trim();
 			if (
-				!retrieveOutputFormats.includes(
-					value as (typeof retrieveOutputFormats)[number],
+				!sharedOutputFormats.includes(
+					value as (typeof sharedOutputFormats)[number],
 				)
 			) {
 				throw new CentrsError({
 					code: "settings/invalid-format",
 					summary: `Unsupported output format: ${value}`,
-					remediation: `Choose one of ${retrieveOutputFormats.join(", ")}.`,
+					remediation: `Choose one of ${sharedOutputFormats.join(", ")}.`,
 				});
 			}
 			return { value, write: value };
@@ -981,7 +990,7 @@ export function renderSettingsEnvelope(
 	}
 	return envelope.ok
 		? renderSettingsSuccessText(envelope)
-		: renderSettingsErrorText(envelope);
+		: formatCentrsErrorText(envelope.error);
 }
 
 function formatValue(value: SettingsValue | null): string {
@@ -1068,12 +1077,3 @@ function renderSettingsSuccessText(
 
 	return lines.join("\n");
 }
-
-function renderSettingsErrorText(envelope: SettingsErrorEnvelope): string {
-	const error = envelope.error;
-	const lines = [`[${error.code}] ${error.summary}`];
-	if (error.remediation) {
-		lines.push(`Fix: ${error.remediation}`);
-	}
-	return lines.join("\n");
-}

package/src/transfer-fanout.ts

@@ -39,7 +39,12 @@ import {
 	summarizeFanout,
 } from "./core/fanout.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+	terminalSafeLine,
+} from "./errors.ts";
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
@@ -53,7 +58,9 @@ import {
 } from "./resolver/index.ts";
 import {
 	buildTransferErrorEnvelope,
+	buildTransferErrorEnvelopeFromResolved,
 	isTransferWriteVerb,
+	type ResolvedTransferRequest,
 	type TransferEnvelope,
 	type TransferOperationMeta,
 	type TransferOutputFormat,
@@ -317,14 +324,20 @@ export async function transferFanout(
 				)
 			: undefined;
 
+	// Resolution happens inside `transfer()`, so a failure after it would lose the
+	// resolved target/method/sources unless the member's resolution is kept.
+	const resolvedByMember = new Map<SelectionMember, ResolvedTransferRequest>();
 	const execute =
 		internals.execute ??
-		((req: TransferRequest, member: SelectionMember) =>
-			transfer(req, env, {
+		((req: TransferRequest, member: SelectionMember) => {
+			resolvedByMember.delete(member);
+			return transfer(req, env, {
 				// cdb members carry their pre-resolved record (CDB loaded once);
 				// literals fall through to single-target resolution.
 				cdbResolution: member.kind === "cdb" ? member.resolution : undefined,
-			}));
+				onResolved: (resolved) => resolvedByMember.set(member, resolved),
+			});
+		});
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
@@ -373,11 +386,15 @@ export async function transferFanout(
 			}),
 		execute: async (resolved, member) =>
 			relabelAdhocMember(await execute(resolved.request, member), member),
-		onExecuteError: (resolved, member, error) =>
-			applyMemberMeta(
-				buildTransferErrorEnvelope(resolved.request, error),
+		onExecuteError: (planned, member, error) => {
+			const resolved = resolvedByMember.get(member);
+			return applyMemberMeta(
+				resolved
+					? buildTransferErrorEnvelopeFromResolved(resolved, error)
+					: buildTransferErrorEnvelope(planned.request, error),
 				member,
-			),
+			);
+		},
 		sleep,
 	});
 
@@ -501,11 +518,7 @@ export function renderTransferFanoutEnvelope(
 		return toYaml(envelope);
 	}
 	if (!envelope.ok) {
-		const lines = [`[${envelope.error.code}] ${envelope.error.summary}`];
-		if (envelope.error.remediation) {
-			lines.push(`Fix: ${envelope.error.remediation}`);
-		}
-		return lines.join("\n");
+		return formatCentrsErrorText(envelope.error, options);
 	}
 	const operation = envelope.meta.operation;
 	const { total, ok, failed } = envelope.data.summary;
@@ -530,10 +543,22 @@ export function renderTransferFanoutEnvelope(
 			lines.push(`  [${index}] ok    ${label}${detail}`);
 		} else {
 			lines.push(
-				`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				terminalSafeLine(
+					`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				),
 			);
 			if (options.verbose && target.error.remediation) {
-				lines.push(`        Fix: ${target.error.remediation}`);
+				lines.push(
+					terminalSafeLine(`        Fix: ${target.error.remediation}`),
+				);
+			}
+			for (const tip of target.tips) {
+				lines.push(
+					terminalSafeLine(`        tip [${tip.code}]: ${tip.message}`),
+				);
+				if (options.verbose && tip.fix) {
+					lines.push(terminalSafeLine(`          fix: ${tip.fix}`));
+				}
 			}
 		}
 	}

package/src/transfer.ts

@@ -18,19 +18,32 @@
  *   error (examples P1–P4).
  */
 
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import {
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	type Stats,
+	statSync,
+	writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type {
 	CentrsEnvelope,
 	CentrsErrorEnvelope,
 	CentrsSuccessEnvelope,
 	SettingSource as CoreSettingSource,
 	EnvelopeValidationMeta,
+	Tip,
 	Warning,
 } from "./core/envelope.ts";
+import { buildTip } from "./core/envelope.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+} from "./errors.ts";
 import {
 	createProtocolAdapter,
 	type ProtocolAdapter,
@@ -194,7 +207,7 @@ export type TransferSuccessEnvelope = CentrsSuccessEnvelope<
 >;
 export type TransferErrorEnvelope = CentrsErrorEnvelope<TransferOperationMeta>;
 
-interface ResolvedTransferRequest {
+export interface ResolvedTransferRequest {
 	verb: TransferVerb;
 	method: TransferMethod;
 	protocol: RouterOsProtocol;
@@ -219,12 +232,23 @@ interface ResolvedTransferRequest {
 
 // ── Public entry ────────────────────────────────────────────────────────────
 
+export interface TransferOptions {
+	cdbResolution?: CdbResolution;
+	/**
+	 * Called once resolution succeeds, before any connection. A caller that
+	 * catches the later throw uses it to keep the resolved target, method and
+	 * setting sources in its error envelope.
+	 */
+	onResolved?: (resolved: ResolvedTransferRequest) => void;
+}
+
 export async function transfer(
 	request: TransferRequest,
 	env: Record<string, string | undefined> = Bun.env,
-	options: { cdbResolution?: CdbResolution } = {},
+	options: TransferOptions = {},
 ): Promise<TransferSuccessEnvelope> {
 	const resolved = await resolveTransferRequest(request, env, options);
+	options.onResolved?.(resolved);
 	const backend = createFileBackend(resolved);
 	try {
 		return await runResolvedTransfer(resolved, backend);
@@ -233,6 +257,33 @@ export async function transfer(
 	}
 }
 
+/**
+ * {@link transfer} as an envelope that never throws. A failure after resolution
+ * carries the resolved target, method and setting sources
+ * ({@link buildTransferErrorEnvelopeFromResolved}); a failure before it keeps
+ * only the caller's input ({@link buildTransferErrorEnvelope}).
+ */
+export async function transferEnvelope(
+	request: TransferRequest,
+	env: Record<string, string | undefined> = Bun.env,
+	options: TransferOptions = {},
+): Promise<TransferEnvelope> {
+	let resolved: ResolvedTransferRequest | undefined;
+	try {
+		return await transfer(request, env, {
+			...options,
+			onResolved: (value) => {
+				resolved = value;
+				options.onResolved?.(value);
+			},
+		});
+	} catch (error) {
+		return resolved
+			? buildTransferErrorEnvelopeFromResolved(resolved, error)
+			: buildTransferErrorEnvelope(request, error);
+	}
+}
+
 /**
  * Build the file backend for the resolved method. `rest`/`native` wrap the
  * shared {@link ProtocolAdapter} `/file` command seam; `sftp` drives the host
@@ -393,6 +444,9 @@ async function runDownload(
 	warnings: Warning[],
 ): Promise<VerbResult> {
 	const remote = requireRemote(resolved);
+	// A destination that cannot be written fails before any device read, so a
+	// typo in the local path costs no transfer and never reads as a centrs bug.
+	checkLocalSink(resolved);
 	const row = await backend.findFile(remote);
 	if (!row) {
 		throw new CentrsError({
@@ -534,7 +588,10 @@ function isRestFamily(method: TransferMethod): boolean {
 	return method === "rest" || method === "native";
 }
 
-/** REST / native-api `/file` command seam. The one place those wire shapes live. */
+/**
+ * REST / native-api `/file` command seam. The one place those wire shapes live.
+ * Contents move in the adapters' `binary` mode, as byte strings (#404).
+ */
 class AdapterFileBackend implements FileBackend {
 	constructor(private readonly adapter: ProtocolAdapter) {}
 
@@ -565,7 +622,6 @@ class AdapterFileBackend implements FileBackend {
 		bytes: Buffer,
 		existing: FileRow | undefined,
 	): Promise<void> {
-		const text = bytes.toString("utf8");
 		let id = existing?.id;
 		if (!id) {
 			const added = await this.adapter.execute({
@@ -587,7 +643,8 @@ class AdapterFileBackend implements FileBackend {
 		await this.adapter.execute({
 			path: "/file",
 			command: "set",
-			attributes: { ".id": id, contents: text },
+			attributes: { ".id": id, contents: bytes.toString("latin1") },
+			binary: true,
 		});
 	}
 
@@ -598,8 +655,9 @@ class AdapterFileBackend implements FileBackend {
 				path: "/file",
 				command: "get",
 				attributes: { ".id": row.id, "value-name": "contents" },
+				binary: true,
 			});
-			return Buffer.from(extractContents(result), "utf8");
+			return Buffer.from(extractContents(result), "latin1");
 		}
 		const parts: Buffer[] = [];
 		let offset = 0;
@@ -610,12 +668,13 @@ class AdapterFileBackend implements FileBackend {
 				path: "/file",
 				command: "read",
 				attributes: {
-					file: row.name,
+					file: Buffer.from(row.name, "utf8").toString("latin1"),
 					offset: String(offset),
 					"chunk-size": String(FILE_READ_CHUNK_BYTES),
 				},
+				binary: true,
 			});
-			const chunk = Buffer.from(extractReadData(result), "utf8");
+			const chunk = Buffer.from(extractReadData(result), "latin1");
 			if (chunk.byteLength === 0) {
 				break;
 			}
@@ -1249,7 +1308,58 @@ function writeLocalSink(
 	// so a newly created destination file gets owner-only permissions
 	// instead of the process umask default. Mode only applies on creation —
 	// an existing destination keeps its current permissions.
-	writeFileSync(local, bytes, { mode: 0o600 });
+	try {
+		writeFileSync(local, bytes, { mode: 0o600 });
+	} catch (error) {
+		throw localSinkError(local, "cannot be written", error);
+	}
+}
+
+/**
+ * The local half of download's validate-before-write: the parent directory
+ * must exist (centrs does not create it) and the destination must not be a
+ * directory. stdout (`-`) needs no check.
+ */
+function checkLocalSink(resolved: ResolvedTransferRequest): void {
+	const local = resolved.local ?? basename(resolved.remote ?? "");
+	if (local === "-") {
+		return;
+	}
+	const parent = dirname(local);
+	if (!statLocal(local, parent)?.isDirectory()) {
+		throw localSinkError(local, `has no parent directory ${parent}`);
+	}
+	if (statLocal(local, local)?.isDirectory()) {
+		throw localSinkError(local, "is a directory");
+	}
+}
+
+/**
+ * `statSync` for the sink preflight. Only a missing entry reads as absent;
+ * `throwIfNoEntry` does not cover EACCES, ENOTDIR or ELOOP, and those are
+ * still the caller's path, not a centrs fault.
+ */
+function statLocal(local: string, path: string): Stats | undefined {
+	try {
+		return statSync(path, { throwIfNoEntry: false });
+	} catch (error) {
+		throw localSinkError(local, `cannot be checked (${path})`, error);
+	}
+}
+
+function localSinkError(
+	local: string,
+	reason: string,
+	cause?: unknown,
+): CentrsError {
+	return new CentrsError({
+		code: "input/local-destination",
+		summary: `Local destination ${local} ${reason}.`,
+		remediation:
+			"Create the parent directory first (centrs does not create it), or pass a writable file path, or `-` for stdout.",
+		context: { local },
+		cause,
+	});
 }
 
 function localLabel(resolved: ResolvedTransferRequest): string {
@@ -1362,20 +1472,121 @@ function metaFromResolved(
 	};
 }
 
+function asTransferError(error: unknown): CentrsError {
+	return error instanceof CentrsError
+		? error
+		: new CentrsError({
+				code: "internal/unhandled",
+				summary: "transfer failed with an unexpected internal error.",
+				remediation:
+					"Re-run with `--format json` to capture the structured error details.",
+				cause: error,
+			});
+}
+
+/**
+ * The error envelope for a failure after resolution: the same target, method,
+ * setting sources and operation meta a success would carry, so the caller can
+ * see which host, user and credential sources were tried. Secrets never enter
+ * it — auth meta is `username` + `passwordProvided` only.
+ */
+export function buildTransferErrorEnvelopeFromResolved(
+	resolved: ResolvedTransferRequest,
+	error: unknown,
+): TransferErrorEnvelope {
+	const centrsError = asTransferError(error);
+	return {
+		ok: false,
+		error: serializeCentrsError(centrsError),
+		warnings: [...resolved.warnings],
+		tips: transferErrorTips(resolved, centrsError),
+		// Which probe ran before the failure is unknown here, so no `result`.
+		meta: metaFromResolved(
+			resolved,
+			baseData(resolved, {
+				op: resolved.verb,
+				remote: resolved.remote,
+				local: resolved.local,
+			}),
+			{
+				enabled: resolved.validate.value,
+				source: resolved.validate.value
+					? "device /file existence probe"
+					: "disabled",
+			},
+		),
+	};
+}
+
+/**
+ * Batch sftp never sends a password. When one was resolved anyway, say so —
+ * "the API accepted this password" is otherwise read as "SFTP tried it" (#391).
+ * The REST/native alternative is advice only (never a fallback) and is left out
+ * when the upload is known to exceed their write cap.
+ */
+function transferErrorTips(
+	resolved: ResolvedTransferRequest,
+	error: CentrsError,
+): Tip[] {
+	if (
+		resolved.method !== "sftp" ||
+		error.code !== "auth/failed" ||
+		!resolved.auth.passwordProvided
+	) {
+		return [];
+	}
+	const source = resolved.auth.passwordSource
+		? ` (from ${describeSource(toCoreSource(resolved.auth.passwordSource))})`
+		: "";
+	const tips = [
+		buildTip(
+			"tip/sftp-password-not-used",
+			`A password was resolved${source}, but batch SFTP does not send it; it tries SSH keys only.`,
+			"Install the user's public key on the device and select it with --ssh-key, or use a password transport for this transfer.",
+		),
+	];
+	if (!uploadExceedsWriteCap(resolved)) {
+		// An explicit port here is the SSH port; carried over, rest would dial it.
+		const portSource = toCoreSource(resolved.target.portSource);
+		const port =
+			portSource.kind === "default"
+				? ""
+				: ` Port ${resolved.target.port} (from ${describeSource(portSource)}) is the SSH port; point --port at the REST service or leave it unset.`;
+		tips.push(
+			buildTip(
+				"tip/transfer-password-transport",
+				"`--via rest` and `--via native-api` log in with the resolved username and password.",
+				`Re-run with --via rest; uploads over rest/native-api are capped at ${REST_FILE_WRITE_CAP_BYTES} bytes.${port}`,
+			),
+		);
+	}
+	return tips;
+}
+
+function describeSource(source: CoreSettingSource): string {
+	return source.key ? `${source.kind} ${source.key}` : source.kind;
+}
+
+function uploadExceedsWriteCap(resolved: ResolvedTransferRequest): boolean {
+	if (
+		resolved.verb !== "upload" ||
+		resolved.local === undefined ||
+		resolved.local === "-"
+	) {
+		return false;
+	}
+	try {
+		return statSync(resolved.local).size > REST_FILE_WRITE_CAP_BYTES;
+	} catch {
+		return false;
+	}
+}
+
 export function buildTransferErrorEnvelope(
 	request: TransferRequest,
 	error: unknown,
 ): TransferErrorEnvelope {
-	const centrsError =
-		error instanceof CentrsError
-			? error
-			: new CentrsError({
-					code: "internal/unhandled",
-					summary: "transfer failed with an unexpected internal error.",
-					remediation:
-						"Re-run with `--format json` to capture the structured error details.",
-					cause: error,
-				});
+	const centrsError = asTransferError(error);
 
 	return {
 		ok: false,
@@ -1405,7 +1616,7 @@ export function renderTransferEnvelope(
 		case "text":
 			return envelope.ok
 				? renderSuccessText(envelope, options)
-				: renderErrorText(envelope);
+				: formatCentrsErrorText(envelope.error, options);
 		default:
 			return exhaustiveFormat(format);
 	}
@@ -1457,15 +1668,6 @@ function renderSuccessText(
 	return lines.join("\n");
 }
 
-function renderErrorText(envelope: TransferErrorEnvelope): string {
-	const { error } = envelope;
-	const lines = [`[${error.code}] ${error.summary}`];
-	if (error.remediation) {
-		lines.push(`Fix: ${error.remediation}`);
-	}
-	return lines.join("\n");
-}
-
 // ── Small helpers ────────────────────────────────────────────────────────────
 
 function uploadSizeHint(request: TransferRequest): number | undefined {