@tikoci/centrs 0.1.9-next.22 → 0.1.9-next.24

package/src/retrieve.ts

@@ -455,12 +455,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 +531,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 +635,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 +663,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,
@@ -1499,8 +1531,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 +1557,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/transfer.ts

@@ -1401,13 +1401,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 +1504,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 +1532,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 },
 		),
 	};
 }