@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.27

package/src/retrieve.ts

@@ -20,6 +20,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { assertRouterOsMenuPath } from "./core/menu-path.ts";
 import {
 	compileQueryWords,
 	type ParsedQuery,
@@ -101,6 +102,12 @@ export interface RetrieveRequest {
 	maxResultsBytes?: number;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** Opt-in host ARP resolution for a MAC target (`none` default, or `arp`). */
 	resolve?: string;
 	/** CDB group selector — expands to a fanout over all matching records. */
@@ -455,12 +462,10 @@ export async function runResolvedRetrieve(
 				await inspectRetrievePath(resolved, backend),
 				backend,
 			);
-			const validation: EnvelopeValidationMeta = {
-				enabled: true,
-				source: "live /console/inspect request=child+completion",
-				result: "passed",
+			const validation = retrieveValidationPassed(
+				"live /console/inspect request=child+completion",
 				availableAttributes,
-			};
+			);
 			trace.validation = validation;
 			const envelope = buildSuccessEnvelope(
 				resolved,
@@ -533,14 +538,26 @@ export async function validateRetrieveRead(
 	return {
 		inspection,
 		query,
-		validation: {
-			enabled: true,
-			source: availableAttributes
+		validation: retrieveValidationPassed(
+			availableAttributes
 				? "live /console/inspect request=child+completion"
 				: "live /console/inspect request=child",
-			result: "passed",
 			availableAttributes,
-		},
+		),
+	};
+}
+
+/** retrieve's gate is the device stage alone; a path read has no CLI string to analyze. */
+function retrieveValidationPassed(
+	source: string,
+	availableAttributes: readonly string[] | undefined,
+): EnvelopeValidationMeta {
+	return {
+		enabled: true,
+		source,
+		result: "passed",
+		availableAttributes,
+		stages: [{ stage: "device", source, result: "passed" }],
 	};
 }
 
@@ -625,29 +642,20 @@ const RETRIEVE_DEVICE_STAGE_SOURCE = "live /console/inspect";
  * an inspect answer: `validation/*`, and the singleton `--query` refusal
  * (`usage/conflicting-flags`). A `transport/*` or `auth/*` failure means the
  * device never answered; a `routeros/*` error is a device answer that is not
- * a verdict; `internal/*` is a centrs defect. Those four report no `result`.
+ * a verdict; `internal/*` is a centrs defect. A `wait/*` error ends a `--wait`
+ * whose gate never settled; one that settled reports its own result instead
+ * (#537). Those five report no `result`.
  */
 function unsettledValidationMeta(
 	resolved: ResolvedRetrieveRequest,
 	error: CentrsError,
 ): EnvelopeValidationMeta {
+	if (stoppedBeforeGateAnswer(error.code)) {
+		return notReachedValidationMeta(resolved, error.code);
+	}
 	if (!resolved.validate.value) {
 		return { enabled: false, source: "disabled" };
 	}
-	if (/^(transport|auth|routeros|internal)\//.test(error.code)) {
-		return {
-			enabled: true,
-			source: RETRIEVE_DEVICE_STAGE_SOURCE,
-			stages: [
-				{
-					stage: "device",
-					source: RETRIEVE_DEVICE_STAGE_SOURCE,
-					result: "skipped",
-					reason: notReachedReason(error.code),
-				},
-			],
-		};
-	}
 	return {
 		enabled: true,
 		source: RETRIEVE_DEVICE_STAGE_SOURCE,
@@ -662,6 +670,37 @@ function unsettledValidationMeta(
 	};
 }
 
+/** Whether an error code stops a run without being a gate answer (GH#435, #537). */
+export function stoppedBeforeGateAnswer(code: string): boolean {
+	return /^(transport|auth|routeros|internal|wait)\//.test(code);
+}
+
+/**
+ * `meta.validation` when the gate was never reached. `cause` is the error code
+ * that stopped it, or `interrupted` for a caller's cancellation, which has no
+ * code (#537).
+ */
+export function notReachedValidationMeta(
+	resolved: ResolvedRetrieveRequest,
+	cause: string,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return { enabled: false, source: "disabled" };
+	}
+	return {
+		enabled: true,
+		source: RETRIEVE_DEVICE_STAGE_SOURCE,
+		stages: [
+			{
+				stage: "device",
+				source: RETRIEVE_DEVICE_STAGE_SOURCE,
+				result: "skipped",
+				reason: notReachedReason(cause),
+			},
+		],
+	};
+}
+
 export function renderRetrieveEnvelope(
 	envelope: RetrieveEnvelope,
 	format: RetrieveOutputFormat,
@@ -888,6 +927,9 @@ export function validateRetrieveRequestShape(
 			context: { path: request.path },
 		});
 	}
+	// Every transport, even under --validate=false: a malformed segment can
+	// cut the appended `/print` off a REST URL and dispatch a write (#586).
+	assertRouterOsMenuPath(request.path);
 
 	const query = resolveRetrieveQuery(request);
 	if (query && request.listAttributes) {
@@ -1325,6 +1367,7 @@ export async function resolveRetrieveRequest(
 			targetInput: request.targetInput,
 			cdbFile: request.cdbFile,
 			cdbPassword: request.cdbPassword,
+			match: request.match,
 		},
 		env,
 		config,
@@ -1499,8 +1542,7 @@ export async function inspectRetrievePath(
 		throw new CentrsError({
 			code: "validation/unknown-path",
 			summary: `RouterOS path ${resolved.path} does not expose a retrieve command.`,
-			remediation:
-				"Check the slash-prefixed RouterOS path, or use a known readable path such as `/system/resource`, `/system/identity`, `/ip/address`, or `/interface`.",
+			remediation: retrieveUnknownPathRemediation(resolved.path),
 			context: {
 				path: resolved.path,
 				validationSource: "/console/inspect request=child",
@@ -1526,6 +1568,25 @@ export async function inspectRetrievePath(
 	};
 }
 
+/**
+ * The `validation/unknown-path` remediation for a retrieve read. One path
+ * earns a targeted hint: `/system/routerboard` exists only on MikroTik
+ * hardware, so its absence on CHR and x86 systems is expected rather than a
+ * typo — and the caller's likely want, the device's license ID, lives at
+ * `/system/license` instead (`system-id` on CHR, `software-id` on x86; manual
+ * "RouterOS License Keys", CLI Reference `/system/license`). The example
+ * reads the whole object because a projected attribute would fail on one
+ * platform or the other. The hint is static on purpose: on hardware the menu
+ * always validates, so this branch only fires where the menu is genuinely
+ * absent, and no extra round trip is needed to say so.
+ */
+export function retrieveUnknownPathRemediation(path: string): string {
+	if (path.replace(/\/$/, "").toLowerCase() === "/system/routerboard") {
+		return "This device exposes no /system/routerboard menu — expected on CHR and x86 systems, which have no routerboard. For this device's license ID, read /system/license instead: `centrs retrieve <router> /system/license` (system-id on CHR, software-id on x86).";
+	}
+	return "Check the slash-prefixed RouterOS path, or use a known readable path such as `/system/resource`, `/system/identity`, `/ip/address`, or `/interface`.";
+}
+
 /**
  * Inspect the menu's attribute names and reject requested ones it lacks with
  * `validation/unknown-attribute`. Shared by one-shot retrieve and `--follow`.

package/src/settings.ts

@@ -153,6 +153,7 @@ const TRANSFER_VIA_VALUES = [
 	"native",
 	"native-api",
 	"sftp",
+	"ssh",
 	"scp",
 	"fetch",
 	"ftp",

package/src/terminal.ts

@@ -81,6 +81,12 @@ export interface TerminalRequest {
 	insecure?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	format?: string;
 	verbose?: boolean;
 }
@@ -154,6 +160,7 @@ export async function resolveTerminalRequest(
 			targetInput: request.targetInput,
 			cdbFile: request.cdbFile,
 			cdbPassword: request.cdbPassword,
+			match: request.match,
 		},
 		env,
 		config,

package/src/transfer-fanout.ts

@@ -48,6 +48,7 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -265,6 +266,7 @@ export async function transferFanout(
 	options: TransferFanoutOptions = {},
 ): Promise<TransferFanoutEnvelope> {
 	validateTransferRequestShape(request);
+	assertNoMatchInFanout(request.match);
 	const config = await loadEnvFileDefaults(env);
 	const selectionSummary = summarizeSelection(selection);
 	const requestSummary: TransferFanoutRequestSummary = {

package/src/transfer.ts

@@ -113,6 +113,20 @@ export const transferMethods = [
 ] as const;
 export type TransferMethod = (typeof transferMethods)[number];
 
+/**
+ * The transfer method a CDB record's transport preference (`via=` in its
+ * comment, shared with execute) selects (#591). A transport missing here
+ * (mac-telnet, winbox, …) cannot carry files and fails `settings/invalid-via`
+ * when the record's preference is what decided the method.
+ */
+export const transferMethodForTransport: Partial<
+	Record<RouterOsProtocol, TransferMethod>
+> = {
+	ssh: "sftp",
+	"rest-api": "rest",
+	"native-api": "native",
+};
+
 /** RouterOS `/file` contents write cap (`/file/set contents`). */
 export const REST_FILE_WRITE_CAP_BYTES = 60_000;
 /** Maximum `/file/read` chunk RouterOS accepts (`chunk-size` upper bound). */
@@ -158,6 +172,12 @@ export interface TransferRequest {
 	name?: string;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** `download` fan-out: directory to write one file per target into. */
 	outDir?: string;
 	/** Fan-out write gate: confirm a mutating fan-out (upload/remove/mkdir/copy). */
@@ -410,7 +430,7 @@ async function runUpload(
 		isRestFamily(resolved.method) &&
 		bytes.byteLength > REST_FILE_WRITE_CAP_BYTES
 	) {
-		throw restWriteCapError(remote, bytes.byteLength);
+		throw restWriteCapError(remote, bytes.byteLength, resolved.via);
 	}
 
 	const existing = await backend.findFile(remote);
@@ -879,13 +899,6 @@ export async function resolveTransferRequest(
 	const direction: TransferDirection =
 		request.verb === "upload" ? "upload" : "download";
 	const sizeHint = uploadSizeHint(request);
-	const { method, protocol, via } = selectTransferMethod(
-		request,
-		direction,
-		sizeHint,
-		env,
-		config,
-	);
 
 	// A quickchr target is a named-live-provider: host/port/auth come from the
 	// live descriptor, bypassing CDB and the `__default__` ladder. For
@@ -908,10 +921,21 @@ export async function resolveTransferRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
 			)));
+	// After CDB resolution: a record's `via=` preference is a layer of the
+	// method choice, mapped from transport to transfer-method names (#591).
+	const { method, protocol, via } = selectTransferMethod(
+		request,
+		direction,
+		sizeHint,
+		env,
+		config,
+		cdbResolution?.overrides.via,
+	);
 
 	const format = resolveTransferFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -1041,6 +1065,7 @@ export function selectTransferMethod(
 	uploadBytes: number | undefined,
 	env: Record<string, string | undefined>,
 	config: Record<string, string | undefined> = {},
+	cdbVia?: ResolvedSetting<RouterOsProtocol>,
 ): {
 	method: TransferMethod;
 	protocol: RouterOsProtocol;
@@ -1053,10 +1078,32 @@ export function selectTransferMethod(
 		"auto",
 		"via",
 		undefined,
-		undefined,
+		cdbVia === undefined
+			? undefined
+			: {
+					value: transferMethodForTransport[cdbVia.value] ?? cdbVia.value,
+					source: cdbVia.source,
+				},
 		config,
 	) as ResolvedSetting<string>;
 	const requested = via.value;
+	if (
+		via.source.kind === "comment-kv" &&
+		cdbVia !== undefined &&
+		transferMethodForTransport[cdbVia.value] === undefined
+	) {
+		throw new CentrsError({
+			code: "settings/invalid-via",
+			summary: `The CDB record prefers \`via=${cdbVia.value}\`, which cannot carry files.`,
+			remediation:
+				"Pass `--via sftp`, `--via rest` or `--via native` for this transfer (or set `CENTRS_TRANSFER_VIA`). The record's `via` stays in effect for execute.",
+			context: {
+				via: cdbVia.value,
+				source: cdbVia.source.key,
+				supported: Object.keys(transferMethodForTransport),
+			},
+		});
+	}
 
 	if (requested === "auto") {
 		// Auto: REST family carries reads and small writes; a large upload exceeds
@@ -1078,7 +1125,8 @@ export function selectTransferMethod(
 	if (requested === "native" || requested === "native-api") {
 		return { method: "native", protocol: "native-api", via };
 	}
-	if (requested === "sftp") {
+	// `ssh` is the transport name `execute` and CDB `via=` use (#591).
+	if (requested === "sftp" || requested === "ssh") {
 		return { method: "sftp", protocol: "ssh", via };
 	}
 	if (requested === "scp" || requested === "fetch") {
@@ -1401,13 +1449,26 @@ function buildSuccessEnvelope(
 		data,
 		warnings,
 		tips: [],
-		meta: metaFromResolved(resolved, operationData, {
-			enabled: resolved.validate.value,
-			source: resolved.validate.value
-				? "device /file existence probe"
-				: "disabled",
-			result: resolved.validate.value ? "passed" : "skipped",
-		}),
+		meta: metaFromResolved(
+			resolved,
+			operationData,
+			!hasExistenceProbe(resolved)
+				? { enabled: false }
+				: resolved.validate.value
+					? {
+							enabled: true,
+							source: TRANSFER_DEVICE_STAGE_SOURCE,
+							result: "passed",
+							stages: [
+								{
+									stage: "device",
+									source: TRANSFER_DEVICE_STAGE_SOURCE,
+									result: "passed",
+								},
+							],
+						}
+					: { enabled: false, source: "disabled", result: "skipped" },
+		),
 	};
 }
 
@@ -1491,6 +1552,16 @@ function asTransferError(error: unknown): CentrsError {
  * see which host, user and credential sources were tried. Secrets never enter
  * it — auth meta is `username` + `passwordProvided` only.
  */
+const TRANSFER_DEVICE_STAGE_SOURCE = "device /file existence probe";
+
+/**
+ * `list` reads `/file` and has no precondition probe, so it is not a gate:
+ * like `explain`, it reports `{ enabled: false }` and no verdict (#535).
+ */
+function hasExistenceProbe(resolved: ResolvedTransferRequest): boolean {
+	return resolved.verb !== "list";
+}
+
 export function buildTransferErrorEnvelopeFromResolved(
 	resolved: ResolvedTransferRequest,
 	error: unknown,
@@ -1509,12 +1580,14 @@ export function buildTransferErrorEnvelopeFromResolved(
 				remote: resolved.remote,
 				local: resolved.local,
 			}),
-			{
-				enabled: resolved.validate.value,
-				source: resolved.validate.value
-					? "device /file existence probe"
-					: "disabled",
-			},
+			hasExistenceProbe(resolved)
+				? {
+						enabled: resolved.validate.value,
+						source: resolved.validate.value
+							? TRANSFER_DEVICE_STAGE_SOURCE
+							: "disabled",
+					}
+				: { enabled: false },
 		),
 	};
 }
@@ -1747,13 +1820,30 @@ function targetExistsError(remote: string): CentrsError {
 	});
 }
 
-function restWriteCapError(remote: string, bytes: number): CentrsError {
+function restWriteCapError(
+	remote: string,
+	bytes: number,
+	via: ResolvedSetting<string>,
+): CentrsError {
+	// A pinned REST method is never hopped to sftp; name the pin so a record
+	// or env preference the caller did not type is visible (#591 review).
+	const pinnedBy =
+		via.source.kind === "comment-kv"
+			? ` The method came from the CDB record's \`via=\` (\`${via.source.key}\`).`
+			: via.source.kind === "env" || via.source.kind === "config"
+				? ` The method came from \`${via.source.key}=${via.value}\` (${via.source.kind}).`
+				: "";
 	return new CentrsError({
 		code: "transport/unsupported-operation",
 		summary: `Cannot write ${bytes} bytes to ${remote} over REST/native (60 KB cap).`,
-		remediation:
-			"Large uploads need sftp (lands with the SSH transport); the REST `/file` write cap is 60 KB.",
-		context: { remote, bytes, capBytes: REST_FILE_WRITE_CAP_BYTES },
+		remediation: `Pass \`--via sftp\` for this upload; the REST \`/file\` write cap is 60 KB.${pinnedBy}`,
+		context: {
+			remote,
+			bytes,
+			capBytes: REST_FILE_WRITE_CAP_BYTES,
+			via: via.value,
+			viaSource: via.source.key ?? via.source.kind,
+		},
 	});
 }