fix: class an unavailable Casework inspection as operational and keep its cause

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registry-bregctl/src/project_dev/mod.rs

@@ -434,8 +434,10 @@ struct Usage(&'static str);
 /// `registry.rstack.error.v1` object, plus `run_id` and `recovery` when a run
 /// still has resources to release.
 fn error_report(error: &anyhow::Error) -> (Value, u8) {
-    let operational =
-        error.is::<Operational>() || error.is::<CleanupPending>() || error.is::<RecoveryNeeded>();
+    let operational = error.is::<Operational>()
+        || error.is::<CleanupPending>()
+        || error.is::<RecoveryNeeded>()
+        || error.is::<products::InspectionUnavailable>();
     let (class, code) = if operational {
         ("operational", crate::OPERATIONAL_FAILURE_EXIT)
     } else if error.is::<Usage>() {

crates/registry-bregctl/src/project_dev/products.rs

@@ -830,7 +830,20 @@ impl InspectionUnavailable {
             remedy: remedy.to_owned(),
         }
     }
+}
 
+/// An inspection that could not complete, keeping the cause in the reason. The
+/// cause comes from spawning the tool, its timeout, temporary files and the
+/// report parse; none of those messages carries a configured value.
+fn inspection_failed(field: &str, action: &str, error: &anyhow::Error) -> InspectionUnavailable {
+    InspectionUnavailable::new(
+        field,
+        &format!("The selected `caseworkctl` helper could not {action}: {error:#}."),
+        "Install the matching Casework tools or provide RSTACK_CASEWORKCTL_BIN, then run the check again.",
+    )
+}
+
+impl InspectionUnavailable {
     pub(super) fn field(&self) -> &str {
         &self.field
     }
@@ -1075,12 +1088,10 @@ fn casework_principals(
                 "Run `rstack casework check` for authored diagnostics, then correct the Casework project.",
             ).into());
         }
-        Err(_) => {
-            return Err(InspectionUnavailable::new(
-                &project.field,
-                "The selected `caseworkctl` helper could not inspect the Casework project.",
-                "Install the matching Casework tools or provide RSTACK_CASEWORKCTL_BIN, then run the check again.",
-            ).into());
+        Err(error) => {
+            return Err(
+                inspection_failed(&project.field, "inspect the Casework project", &error).into(),
+            );
         }
     };
     let status_profile = plan
@@ -1238,13 +1249,7 @@ fn check_casework_binding(
     binding: &super::bindings::CaseworkContextProvider,
     terminate: &AtomicBool,
 ) -> Result<()> {
-    let unavailable = || {
-        InspectionUnavailable::new(
-            &project.field,
-            "The selected `caseworkctl` helper could not check the Casework configuration the run writes.",
-            "Install the matching Casework tools or provide RSTACK_CASEWORKCTL_BIN, then run the check again.",
-        )
-    };
+    let action = "check the Casework configuration the run writes";
     let checked = (|| {
         let directory = tempfile::tempdir()?;
         // The runtime loader refuses a file reached through a symbolic link,
@@ -1272,8 +1277,9 @@ fn check_casework_binding(
             terminate,
         )
     })();
-    let Ok((status, report)) = checked else {
-        return Err(unavailable().into());
+    let (status, report) = match checked {
+        Ok(checked) => checked,
+        Err(error) => return Err(inspection_failed(&project.field, action, &error).into()),
     };
     match casework_binding_check(status.code(), &report, &binding.id) {
         BindingCheck::Accepted => Ok(()),
@@ -1286,7 +1292,12 @@ fn check_casework_binding(
             "Correct the value so the product accepts the configuration the run writes for this binding.",
         )
         .into()),
-        BindingCheck::Unchecked => Err(unavailable().into()),
+        BindingCheck::Unchecked => Err(inspection_failed(
+            &project.field,
+            action,
+            &anyhow::anyhow!("caseworkctl check did not report a result for the binding"),
+        )
+        .into()),
     }
 }
 
@@ -2532,6 +2543,30 @@ mod tests {
         assert_ne!(fs::read_to_string(other.join(FIELD_KEY)).unwrap(), encoded);
     }
 
+    #[test]
+    fn an_unavailable_inspection_is_operational_and_names_its_cause() {
+        let class =
+            |error: &anyhow::Error| super::super::error_report(error).0["error"]["class"].clone();
+        let unavailable = anyhow::Error::new(InspectionUnavailable::new(
+            "products[0]",
+            "The Casework project cannot be inspected.",
+            "Install the tools.",
+        ));
+        assert_eq!(class(&unavailable), "operational");
+
+        let terminate = AtomicBool::new(false);
+        let missing = Path::new("/nonexistent/caseworkctl");
+        let error = explain_casework_facts(missing, Path::new("."), &terminate).unwrap_err();
+        let reason = inspection_failed("products[0]", "inspect the Casework project", &error);
+        assert!(
+            reason.reason().contains(
+                "could not inspect the Casework project: cannot start caseworkctl explain"
+            ),
+            "{}",
+            reason.reason()
+        );
+    }
+
     #[test]
     fn missed_readiness_and_start_deadlines_are_operational() {
         let class =

crates/registry-bregctl/tests/project_dev.rs

@@ -1217,7 +1217,7 @@ fragment or userinfo."
     assert_eq!(diagnostic["path"], "/products/1/project");
     assert_eq!(
         diagnostic["message"],
-        "The selected `caseworkctl` helper could not check the Casework configuration the run writes."
+        "The selected `caseworkctl` helper could not check the Casework configuration the run writes: caseworkctl check did not report a result for the binding."
     );
     assert!(!state.exists());
 }
@@ -1309,7 +1309,7 @@ fn check_distinguishes_an_unavailable_casework_helper_from_an_invalid_project()
     assert_eq!(diagnostic["path"], "/products/1/project");
     assert_eq!(
         diagnostic["message"],
-        "The selected `caseworkctl` helper could not inspect the Casework project."
+        "The selected `caseworkctl` helper could not inspect the Casework project: caseworkctl explain did not complete successfully."
     );
     assert!(!state.exists());
 

products/casework/CHANGELOG.md

@@ -11,8 +11,9 @@
   with each access profile's `id` and `principalClaim`, so a caller no longer
   reads them from a review policy's `dependencies`. The member is additive.
 
-- `caseworkctl check --runtime-config` refuses a `contextProviders` binding
-  that startup would refuse, such as a `resource` that is not an absolute URI
+- `caseworkctl check --runtime-config`, and every other command that loads the
+  runtime configuration, refuses a `contextProviders` binding that startup
+  would refuse, such as a `resource` that is not an absolute URI
   or a `baseUrl` that is not HTTPS, without resolving a secret. The diagnostic
   `casework.runtime.invalid-context-provider` sits at the member and names the
   rule it breaks.

products/platform/CHANGELOG.md

@@ -14,7 +14,8 @@
   `registry.rstack.error.v1` object, published as
   `schemas/rstack-dev-error.v1.schema.json`. Its `error.class` is `domain`
   (exit 1), `usage` (exit 2) or `operational` (exit 3); a run that still holds
-  resources adds its `run_id` and a `recovery` object.
+  resources adds its `run_id`, with a `recovery` object when the resources to
+  release are known.
 - A BReg project with encrypted fields runs under `rstack dev` without extra
   setup. Each run draws its own development data key into its run directory,
   readable only by your user, and the key is removed with the run.