From 6868e6e6d68a57be95a111c78123b183150ec091 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Thu, 12 Nov 2026 15:31:21 +0200 Subject: [PATCH 1/5] feat(runtimes): add --json to rocm runtimes list (ROCMAI-148) Scripts that want the registered runtimes, which one is active and which is the rollback target currently have to scrape the text table and its `*`/`-` markers. `rocm runtimes list --json` prints the same listing as one JSON document on stdout, through the shared JsonOrText helper. The listing is now computed once into a value and both forms render from it, so the JSON `active`/`rollback_target` flags and the text markers cannot disagree. Unset values are null in the JSON, and the empty-registry next-step hint stays text-only. The text output of `rocm runtimes list` is unchanged except where `default_runtime_id` matches a runtime id only when letter case is ignored. The listing now applies one default-id rule, ASCII case ignored, to both the active marker and the problem report: the false "missing manifest for active_runtime_id" line printed next to an active runtime is gone, and runtime ids that differ only in case now report an ambiguous-runtime line instead. docs/json-output.md audits `--json` support per command family, states the rules those commands follow (stdout carries only the document, errors stay on stderr, documented fields change only additively), and records where the listing still differs from the resolver `rocm examine` uses. Whether to adopt a shared envelope across commands is left open there. Signed-off-by: Roman Inflianskas --- README.md | 8 +- apps/rocm/src/cli.rs | 24 +- apps/rocm/src/dash.rs | 23 +- apps/rocm/src/runtime_registry.rs | 9 +- apps/rocm/src/runtimes_cmd.rs | 1032 +++++++++++++++-- docs/architecture.md | 4 +- docs/json-output.md | 167 +++ docs/manual-testing.md | 15 + docs/testing.md | 55 + docs/ux-guidelines.md | 8 + .../features/runtime_lifecycle.feature | 60 + .../tests/e2e/runtime_lifecycle_steps.rs | 375 +++++- 12 files changed, 1630 insertions(+), 150 deletions(-) create mode 100644 docs/json-output.md diff --git a/README.md b/README.md index 2088138772..04cd5cb432 100644 --- a/README.md +++ b/README.md @@ -801,7 +801,7 @@ old date is a hint to look at the driver, not a finding that it is broken. See Manage multiple side-by-side ROCm runtimes: ``` -rocm runtimes list +rocm runtimes list [--json] rocm runtimes activate [--restart-services [--yes]] rocm runtimes rollback [--restart-services [--yes]] rocm runtimes uninstall [--yes] [--dry-run] @@ -817,6 +817,12 @@ can appear more than once: a `--devel` install and a plain one of the same version are two separate runtimes, as are two installs that resolved different GPU device payloads. +`list --json` prints the same listing as one JSON document on stdout for +scripts: each runtime with its key, version, mode, status and toolchain, and +`active` and `rollback_target` flags in place of the `*` and `-` markers. Unset +values are `null`. Fields may be added in later releases; existing ones are not +renamed or removed. + `activate` and `rollback` change which runtime the next install or server picks up. A server that is already running is not moved: it keeps serving on the runtime it started with until it is restarted. Both commands count the diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 0096036fed..8fdc159966 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -980,7 +980,11 @@ rocm engines install vllm --reinstall")] #[derive(Subcommand, Debug)] pub(crate) enum RuntimesCommand { /// Show ROCm runtimes known to ROCm CLI. - List, + List { + /// Print the runtime list as JSON instead of text. + #[arg(long)] + json: bool, + }, /// Use the selected ROCm runtime by default. Activate { /// Runtime key or friendly runtime selector. @@ -2123,6 +2127,24 @@ mod tests { } } + /// `--json` belongs to `list` alone: bare `rocm runtimes` stays the text + /// listing, so a script has to name the subcommand to get JSON. + #[test] + fn runtimes_json_is_a_list_flag() { + for (args, json) in [(&["list", "--json"][..], true), (&["list"][..], false)] { + match parse_runtimes(args).expect("runtimes list parses").command { + Some(Command::Runtimes { + command: Some(RuntimesCommand::List { json: parsed }), + }) => assert_eq!(parsed, json, "{args:?}"), + other => panic!("expected runtimes list, got {other:?}"), + } + } + assert!( + parse_runtimes(&["--json"]).is_err(), + "`rocm runtimes --json` must be rejected, not read as `list --json`" + ); + } + fn parse_serve(args: &[&str]) -> Result { let mut argv = vec!["rocm", "serve", "qwen"]; argv.extend_from_slice(args); diff --git a/apps/rocm/src/dash.rs b/apps/rocm/src/dash.rs index 679ec85650..aaa5ce429b 100644 --- a/apps/rocm/src/dash.rs +++ b/apps/rocm/src/dash.rs @@ -212,9 +212,26 @@ fn runtime_summaries(paths: &AppPaths, config: &RocmCliConfig) -> Vec = manifests .iter() .filter(|m| Some(m.runtime_id.as_str()) == default_id) diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index 41eabb776e..61300196b5 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -665,10 +665,17 @@ pub(crate) fn select_runtime_manifest<'a>( pub(crate) fn runtime_usability_status(manifest: &InstalledRuntimeManifest) -> String { match validate_runtime_manifest_for_activation(manifest) { Ok(()) => "ready".to_owned(), - Err(error) => format!("unusable ({error})"), + Err(error) => unusable_status_text(&error.to_string()), } } +/// How the text reports name a runtime that fails the manifest check +/// activation applies, given the reason it fails it. `rocm runtimes list` +/// prints the same words from the reason it also carries in its JSON. +pub(crate) fn unusable_status_text(reason: &str) -> String { + format!("unusable ({reason})") +} + pub(crate) fn validate_runtime_manifest_for_activation( manifest: &InstalledRuntimeManifest, ) -> Result<()> { diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index 950960a6b2..d900cf5dec 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -3,17 +3,19 @@ // SPDX-License-Identifier: MIT //! `rocm runtimes` command: its dispatch, activate/rollback, and the runtime -//! list rendering. Import and adopt (and recovering the runtime `rocm setup` -//! created) live in `runtime_adopt.rs`, and uninstall in +//! list, which `runtimes_listing` computes once into a `RuntimesListing` that +//! prints either as the text table or, with `--json`, as that value serialized +//! (`docs/json-output.md`). Import and adopt (and recovering the runtime +//! `rocm setup` created) live in `runtime_adopt.rs`, and uninstall in //! `runtime_uninstall.rs`. Registry selection and manifest validation live in //! `runtime_registry.rs`; the names other modules import from here //! (`current_runtime_manifest`, `select_runtime_manifest`, //! `validate_runtime_manifest_for_activation`, `runtime_usability_status`, //! and the registry path helpers) are re-exported from this module. //! -//! Mechanically relocated from `main.rs` with no behavior change — the -//! `dispatch()` call site stays byte-identical (`runtimes(command)`, -//! re-imported via `use crate::runtimes_cmd::{runtimes, ...};`). +//! `runtimes(command)` is the entry point `main.rs`'s `dispatch()` calls for +//! `rocm runtimes`, imported there via +//! `use crate::runtimes_cmd::{runtimes, ...};`. //! `RuntimesCommand` lives in `cli.rs` (part of the `Command`/`Cli` clap //! definition) and is reached via `use crate::RuntimesCommand`, a re-import in //! `main.rs`, the same way `engines_cmd.rs` reaches `EnginesCommand`. @@ -38,9 +40,11 @@ use std::fmt::Write as _; use std::fs; +use std::path::PathBuf; use anyhow::{Context, Result}; use rocm_core::{AppPaths, RocmCliConfig, require_yes_or_interactive}; +use serde::Serialize; use crate::runtime_adopt::{ AdoptRuntimeOptions, adopt_runtime_from_python_options, import_runtime_manifest, @@ -48,6 +52,7 @@ use crate::runtime_adopt::{ pub(crate) use crate::runtime_adopt::{ newest_installed_runtime_manifest, recover_setup_runtime_registration, setup_runtime_paths, }; +use crate::runtime_registry::unusable_status_text; pub(crate) use crate::runtime_registry::{ ActiveRuntimeMarker, active_runtime_marker_path, current_runtime_manifest, default_runtime_id_matches, normalize_path_for_compare, runtime_keys_text, @@ -86,7 +91,7 @@ pub(crate) fn ensure_runtime_service_restart_approved(command: &RuntimesCommand) restart_services, yes, } => runtime_services::ensure_service_restart_approved(*restart_services, *yes, "rollback"), - RuntimesCommand::List + RuntimesCommand::List { .. } | RuntimesCommand::Uninstall { .. } | RuntimesCommand::Import { .. } | RuntimesCommand::Adopt { .. } => Ok(()), @@ -96,15 +101,15 @@ pub(crate) fn ensure_runtime_service_restart_approved(command: &RuntimesCommand) pub(crate) fn runtimes(command: Option) -> Result<()> { let paths = AppPaths::discover()?; let mut config = RocmCliConfig::load(&paths)?; - let command = command.unwrap_or(RuntimesCommand::List); + let command = command.unwrap_or(RuntimesCommand::List { json: false }); // Checked before anything is written: a refused restart must leave the // previously active runtime in place, not switch the runtime and then // decline the half of the job the user actually asked for. ensure_runtime_service_restart_approved(&command)?; match command { - RuntimesCommand::List => { - print!("{}", render_runtimes_text(&paths, &config)?); + RuntimesCommand::List { json } => { + cli_report::print_json_or_text(json, &runtimes_listing(&paths, &config)?)?; } RuntimesCommand::Activate { runtime, @@ -580,141 +585,348 @@ const ACTIVE_RUNTIME_MARKER: &str = "*"; /// [`ACTIVE_RUNTIME_MARKER`]. const ROLLBACK_RUNTIME_MARKER: &str = "-"; -pub(crate) fn render_runtimes_text(paths: &AppPaths, config: &RocmCliConfig) -> Result { - recover_setup_runtime_registration(paths, config)?; - let manifests = therock::load_runtime_manifests(paths)?; - let mut output = String::new(); - let _ = writeln!(output, "registered ROCm runtimes"); - let _ = writeln!( - output, - " active_runtime_id: {}", - config.default_runtime_id.as_deref().unwrap_or("") - ); - let _ = writeln!( - output, - " active_runtime_key: {}", - config.active_runtime_key.as_deref().unwrap_or("") - ); - let _ = writeln!( - output, - " previous_runtime_key: {}", - config.previous_runtime_key.as_deref().unwrap_or("") - ); - let _ = writeln!( - output, - " registry: {}", - runtime_registry_dir(paths).display() - ); - let _ = writeln!( - output, - " marker: {}", - active_runtime_marker_path(paths).display() - ); - if let Some(active_runtime_key) = config.active_runtime_key.as_deref() - && !manifests - .iter() - .any(|manifest| manifest.runtime_key == active_runtime_key) - { - let _ = writeln!( - output, - " active_status: missing manifest for active_runtime_key={active_runtime_key}" - ); +/// What `rocm runtimes list` reports, computed once and printed either as text +/// or, with `--json`, as this struct serialized. +/// +/// Every per-runtime fact the text shows is a field here, so the text marker +/// and the JSON `active`/`rollback_target` flags come from the same +/// computation. The text adds only presentation: the marker legend, the +/// next-step hint for an empty registry, the build date it derives from +/// `version`, and the `unusable (…)` wording around `unusable_reason`. The JSON +/// form is additive-only: fields may be added, but none is renamed, removed or +/// given a new meaning (see `docs/json-output.md`). +#[derive(Debug, Serialize)] +pub(crate) struct RuntimesListing { + /// `default_runtime_id` from the config, as configured; `null` when unset. + /// Not necessarily the active runtime's `runtime_id`: an `active_runtime_key` + /// takes precedence, and the id may differ in letter case or match nothing. + active_runtime_id: Option, + active_runtime_key: Option, + previous_runtime_key: Option, + registry: PathBuf, + marker: PathBuf, + /// Why the configured active runtime cannot be resolved, or `null`. + active_problem: Option, + /// Newest install first, ties broken by `runtime_key`, as the registry + /// loader sorts them (`sort_manifests_newest_install_first`). + runtimes: Vec, +} + +/// Why the configured active runtime does not resolve to one manifest. The +/// text form prints it as the `active_status:` line. +#[derive(Debug, Serialize, PartialEq, Eq)] +#[serde(tag = "kind", rename_all = "snake_case")] +enum ActiveRuntimeProblem { + /// `active_runtime_key` is set but no registered manifest has that key. + MissingManifestForKey { runtime_key: String }, + /// No `active_runtime_key`; `default_runtime_id` matches no manifest's id, + /// ASCII letter case ignored. + MissingManifestForId { runtime_id: String }, + /// No `active_runtime_key`; `default_runtime_id` matches more than one + /// manifest's id (letter case ignored), so none is active until one key is + /// activated. + AmbiguousRuntimeId { + runtime_id: String, + runtime_keys: Vec, + }, +} + +/// One registered runtime in [`RuntimesListing`]. +#[derive(Debug, Serialize)] +struct RuntimeListingEntry { + runtime_key: String, + runtime_id: String, + /// The version the manifest records; the text form adds the build date. + version: String, + format: String, + family: String, + mode: RuntimeMode, + /// Serialized as the two JSON fields `status` and `unusable_reason`. + #[serde(flatten)] + usability: RuntimeUsability, + /// `included` or `excluded`, the words `toolchain_state_text` uses. + toolchain: &'static str, + active: bool, + rollback_target: bool, + install_root: PathBuf, +} + +#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)] +#[serde(rename_all = "kebab-case")] +enum RuntimeMode { + /// ROCm CLI installed it and may remove its folder. + Managed, + /// Imported or adopted; ROCm CLI never changes its folder. + ReadOnly, +} + +impl RuntimeMode { + const fn as_str(self) -> &'static str { + match self { + Self::Managed => "managed", + Self::ReadOnly => "read-only", + } } - if config.active_runtime_key.is_none() - && let Some(default_runtime_id) = config.default_runtime_id.as_deref() - { - let matches = manifests - .iter() - .filter(|manifest| manifest.runtime_id == default_runtime_id) - .collect::>(); - if matches.is_empty() { - let _ = writeln!( - output, - " active_status: missing manifest for active_runtime_id={default_runtime_id}" - ); - } else if matches.len() > 1 { - let _ = writeln!( - output, - " active_status: ambiguous runtime_id={default_runtime_id}; activate one runtime_key: {}", - runtime_keys_text(&matches) - ); +} + +/// Whether a runtime passes the manifest check that `rocm runtimes activate` +/// applies (`validate_runtime_manifest_for_activation`). Passing it does not +/// promise the activation succeeds: that can still refuse on an ambiguous +/// selector, unreadable server records or a failed config or marker write. An +/// unusable runtime always carries the reason, so the listing cannot report one +/// without saying why. +#[derive(Debug)] +enum RuntimeUsability { + Ready, + /// The human-readable message the manifest check failed with (not a + /// stable code). + Unusable { + reason: String, + }, +} + +impl RuntimeUsability { + /// The JSON `status` value. + const fn status(&self) -> &'static str { + match self { + Self::Ready => "ready", + Self::Unusable { .. } => "unusable", } } - if manifests.is_empty() { - let _ = writeln!(output, " installed: none"); - let _ = writeln!( - output, - " next step: rocm install sdk --channel release --format wheel" - ); - return Ok(output); + + /// The JSON `unusable_reason` value: `None` exactly when ready. + fn unusable_reason(&self) -> Option<&str> { + match self { + Self::Ready => None, + Self::Unusable { reason } => Some(reason), + } + } +} + +/// Two fields, `status` (`ready` or `unusable`) and `unusable_reason` (`null` +/// when ready), flattened into each runtime's JSON object. +impl Serialize for RuntimeUsability { + fn serialize(&self, serializer: S) -> Result { + use serde::ser::SerializeStruct as _; + let mut fields = serializer.serialize_struct("RuntimeUsability", 2)?; + fields.serialize_field("status", self.status())?; + fields.serialize_field("unusable_reason", &self.unusable_reason())?; + fields.end() } +} + +/// Recover the runtime `rocm setup` created, load the registry, and compute +/// everything `rocm runtimes list` reports, in either form. +pub(crate) fn runtimes_listing( + paths: &AppPaths, + config: &RocmCliConfig, +) -> Result { + recover_setup_runtime_registration(paths, config)?; + let manifests = therock::load_runtime_manifests(paths)?; + // With no `active_runtime_key`, `default_runtime_id` is matched by one rule, + // `default_runtime_id_matches` (ASCII letter case ignored), for both the + // problem and the `active` flag below, so the listing cannot mark a runtime + // active and also report its manifest missing. let default_runtime_matches = default_runtime_id_matches(config, &manifests); - let single_default_runtime_key = - if config.active_runtime_key.is_none() && default_runtime_matches.len() == 1 { - Some(default_runtime_matches[0].runtime_key.clone()) + let (active_problem, single_default_runtime_key) = + if let Some(active_runtime_key) = config.active_runtime_key.as_deref() { + let problem = (!manifests + .iter() + .any(|manifest| manifest.runtime_key == active_runtime_key)) + .then(|| ActiveRuntimeProblem::MissingManifestForKey { + runtime_key: active_runtime_key.to_owned(), + }); + (problem, None) + } else if let Some(default_runtime_id) = config.default_runtime_id.as_deref() { + match default_runtime_matches.as_slice() { + [] => ( + Some(ActiveRuntimeProblem::MissingManifestForId { + runtime_id: default_runtime_id.to_owned(), + }), + None, + ), + [manifest] => (None, Some(manifest.runtime_key.clone())), + matches => ( + Some(ActiveRuntimeProblem::AmbiguousRuntimeId { + runtime_id: default_runtime_id.to_owned(), + runtime_keys: matches + .iter() + .map(|manifest| manifest.runtime_key.clone()) + .collect(), + }), + None, + ), + } } else { - None + (None, None) }; - drop(default_runtime_matches); - let _ = writeln!(output, " installed:"); - let _ = writeln!( - output, - " legend: {ACTIVE_RUNTIME_MARKER} = active, {ROLLBACK_RUNTIME_MARKER} = rollback target" - ); - let _ = writeln!(output); - for manifest in manifests { - let active = config - .active_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key == manifest.runtime_key) - || single_default_runtime_key.as_deref() == Some(manifest.runtime_key.as_str()); - let rollback = config - .previous_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key == manifest.runtime_key); - let marker = if active { - Some(ACTIVE_RUNTIME_MARKER) - } else if rollback { - Some(ROLLBACK_RUNTIME_MARKER) - } else { - None - }; - let status = runtime_usability_status(&manifest); - let mode = if manifest.read_only { - "read-only" - } else { - "managed" - }; - // The compiler is opt-in and `rocm update` reinstalls whatever this - // says, so an install missing it should not be silent about that. - // `rocm examine` reports the same thing for the active runtime. - let toolchain = toolchain_state_text(manifest.includes_devel()); - cli_report::write_marked_row( - &mut output, - " ", - marker, - format_args!( - "{} runtime_id={} version={} format={} family={} mode={} status={} toolchain={}", - manifest.runtime_key, - manifest.runtime_id, - therock::runtime_version_display(&manifest.version), - manifest.format, - manifest.family, + let runtimes = manifests + .into_iter() + .map(|manifest| { + let active = config + .active_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key == manifest.runtime_key) + || single_default_runtime_key.as_deref() == Some(manifest.runtime_key.as_str()); + let rollback_target = config + .previous_runtime_key + .as_deref() + .is_some_and(|runtime_key| runtime_key == manifest.runtime_key); + // The manifest check `rocm runtimes activate` applies, so "ready" + // here means the runtime passes that check, not that an activation + // is sure to succeed (see `RuntimeUsability`). + let usability = match validate_runtime_manifest_for_activation(&manifest) { + Ok(()) => RuntimeUsability::Ready, + Err(error) => RuntimeUsability::Unusable { + reason: error.to_string(), + }, + }; + let mode = if manifest.read_only { + RuntimeMode::ReadOnly + } else { + RuntimeMode::Managed + }; + // The compiler is opt-in and `rocm update` reinstalls whatever this + // says, so an install missing it should not be silent about that. + // `rocm examine` reports the same thing for the active runtime. + let toolchain = toolchain_state_text(manifest.includes_devel()); + RuntimeListingEntry { + runtime_key: manifest.runtime_key, + runtime_id: manifest.runtime_id, + version: manifest.version, + format: manifest.format, + family: manifest.family, mode, - status, - toolchain - ), + usability, + toolchain, + active, + rollback_target, + install_root: manifest.install_root, + } + }) + .collect(); + + Ok(RuntimesListing { + active_runtime_id: config.default_runtime_id.clone(), + active_runtime_key: config.active_runtime_key.clone(), + previous_runtime_key: config.previous_runtime_key.clone(), + registry: runtime_registry_dir(paths), + marker: active_runtime_marker_path(paths), + active_problem, + runtimes, + }) +} + +impl cli_report::JsonOrText for RuntimesListing { + fn render_text(&self) -> String { + let mut output = String::new(); + let unset = |value: &Option| value.clone().unwrap_or_else(|| "".to_owned()); + let _ = writeln!(output, "registered ROCm runtimes"); + let _ = writeln!( + output, + " active_runtime_id: {}", + unset(&self.active_runtime_id) ); let _ = writeln!( output, - " install_root: {}", - manifest.install_root.display() + " active_runtime_key: {}", + unset(&self.active_runtime_key) ); + let _ = writeln!( + output, + " previous_runtime_key: {}", + unset(&self.previous_runtime_key) + ); + let _ = writeln!(output, " registry: {}", self.registry.display()); + let _ = writeln!(output, " marker: {}", self.marker.display()); + match &self.active_problem { + None => {} + Some(ActiveRuntimeProblem::MissingManifestForKey { runtime_key }) => { + let _ = writeln!( + output, + " active_status: missing manifest for active_runtime_key={runtime_key}" + ); + } + Some(ActiveRuntimeProblem::MissingManifestForId { runtime_id }) => { + let _ = writeln!( + output, + " active_status: missing manifest for active_runtime_id={runtime_id}" + ); + } + Some(ActiveRuntimeProblem::AmbiguousRuntimeId { + runtime_id, + runtime_keys, + }) => { + let _ = writeln!( + output, + " active_status: ambiguous runtime_id={runtime_id}; activate one runtime_key: {}", + runtime_keys.join(", ") + ); + } + } + if self.runtimes.is_empty() { + let _ = writeln!(output, " installed: none"); + let _ = writeln!( + output, + " next step: rocm install sdk --channel release --format wheel" + ); + return output; + } + + let _ = writeln!(output, " installed:"); + let _ = writeln!( + output, + " legend: {ACTIVE_RUNTIME_MARKER} = active, {ROLLBACK_RUNTIME_MARKER} = rollback target" + ); + let _ = writeln!(output); + for runtime in &self.runtimes { + // Active wins when a runtime is both. `rocm runtimes activate` and + // `rollback` never record a runtime as its own rollback target, so + // only a config edited outside the CLI reaches this. + let marker = if runtime.active { + Some(ACTIVE_RUNTIME_MARKER) + } else if runtime.rollback_target { + Some(ROLLBACK_RUNTIME_MARKER) + } else { + None + }; + let status = match &runtime.usability { + RuntimeUsability::Ready => runtime.usability.status().to_owned(), + RuntimeUsability::Unusable { reason } => unusable_status_text(reason), + }; + cli_report::write_marked_row( + &mut output, + " ", + marker, + format_args!( + "{} runtime_id={} version={} format={} family={} mode={} status={} toolchain={}", + runtime.runtime_key, + runtime.runtime_id, + therock::runtime_version_display(&runtime.version), + runtime.format, + runtime.family, + runtime.mode.as_str(), + status, + runtime.toolchain + ), + ); + let _ = writeln!( + output, + " install_root: {}", + runtime.install_root.display() + ); + } + output } +} - Ok(output) +/// The text form of `rocm runtimes list`, for callers that want the string +/// (the chat assistant's read-only tool) rather than printing it. +pub(crate) fn render_runtimes_text(paths: &AppPaths, config: &RocmCliConfig) -> Result { + use cli_report::JsonOrText as _; + Ok(runtimes_listing(paths, config)?.render_text()) } pub(crate) fn activate_runtime( @@ -1239,6 +1451,570 @@ pub(crate) mod tests { Ok(()) } + /// What `rocm runtimes list --json` prints for `config`, as the JSON value a + /// script reads. + fn runtimes_list_json(paths: &AppPaths, config: &RocmCliConfig) -> Result { + Ok(serde_json::to_value(runtimes_listing(paths, config)?)?) + } + + /// The `runtime_key`s whose `flag` is true, in listing order. + fn runtime_keys_flagged(listing: &serde_json::Value, flag: &str) -> Vec { + listing["runtimes"] + .as_array() + .expect("runtimes is an array") + .iter() + .filter(|runtime| { + // Every runtime must carry `flag` as a boolean: read as + // `runtime[flag] == true`, a missing or renamed field would + // count as false and "nothing is flagged" would still pass. + runtime + .get(flag) + .and_then(serde_json::Value::as_bool) + .unwrap_or_else(|| panic!("a runtime has no boolean `{flag}`:\n{listing:#}")) + }) + .map(|runtime| { + runtime["runtime_key"] + .as_str() + .unwrap_or_default() + .to_owned() + }) + .collect() + } + + fn listed_runtime<'a>( + listing: &'a serde_json::Value, + runtime_key: &str, + ) -> &'a serde_json::Value { + listing["runtimes"] + .as_array() + .expect("runtimes is an array") + .iter() + .find(|runtime| runtime["runtime_key"] == runtime_key) + .unwrap_or_else(|| panic!("{runtime_key} is listed:\n{listing:#}")) + } + + #[test] + fn runtimes_list_json_with_nothing_registered_lists_nothing_and_no_active_runtime() -> Result<()> + { + let (root, paths) = test_paths("runtime-list-json-empty"); + let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + assert_eq!(listing["runtimes"], serde_json::json!([])); + for unset in [ + "active_runtime_id", + "active_runtime_key", + "previous_runtime_key", + "active_problem", + ] { + assert_null_field(&listing, unset); + } + for path in ["registry", "marker"] { + assert!( + listing.get(path).is_some_and(serde_json::Value::is_string), + "`{path}` is always a path:\n{listing:#}" + ); + } + assert!( + listing.get("next_step").is_none(), + "the next-step hint is text-only:\n{listing:#}" + ); + Ok(()) + } + + #[test] + fn runtimes_list_json_flags_the_active_runtime_and_the_rollback_target() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-active-rollback"); + for (key, version, build) in [ + ("rt-first", "7.12.0", 10), + ("rt-second", "7.13.0", 20), + ("rt-idle", "7.11.0", 5), + ] { + write_test_pip_runtime(&paths, key, "therock-release:gfx120X-all", version, build)?; + } + let config = RocmCliConfig { + active_runtime_key: Some("rt-second".to_owned()), + previous_runtime_key: Some("rt-first".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-second"]); + assert_eq!( + runtime_keys_flagged(&listing, "rollback_target"), + ["rt-first"] + ); + assert_eq!(listing["active_runtime_key"], "rt-second"); + assert_eq!(listing["previous_runtime_key"], "rt-first"); + assert_null_field(&listing, "active_problem"); + let second = listed_runtime(&listing, "rt-second"); + assert_eq!(second["runtime_id"], "therock-release:gfx120X-all"); + assert_eq!(second["version"], "7.13.0"); + assert_eq!(second["format"], "wheel"); + assert_eq!(second["family"], "gfx120X-all"); + assert_eq!(second["mode"], "managed"); + assert_eq!(second["status"], "ready"); + assert_null_field(second, "unusable_reason"); + assert_eq!(second["toolchain"], "included"); + Ok(()) + } + + #[test] + fn runtimes_list_json_marks_the_one_runtime_matching_the_default_id_active() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-default-id"); + write_test_pip_runtime( + &paths, + "rt-gfx120x", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + write_test_pip_runtime( + &paths, + "rt-gfx110x", + "therock-release:gfx110X-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-gfx120x"]); + assert_eq!(listing["active_runtime_id"], "therock-release:gfx120X-all"); + assert_null_field(&listing, "active_runtime_key"); + assert_null_field(&listing, "active_problem"); + Ok(()) + } + + #[test] + fn runtimes_list_json_reports_an_active_key_with_no_manifest() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-missing-key"); + write_test_pip_runtime( + &paths, + "rt-present", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + active_runtime_key: Some("rt-gone".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!( + listing["active_problem"], + serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}) + ); + assert!(runtime_keys_flagged(&listing, "active").is_empty()); + Ok(()) + } + + #[test] + fn runtimes_list_json_reports_a_default_id_with_no_manifest() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-missing-id"); + write_test_pip_runtime( + &paths, + "rt-present", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some("therock-release:gfx110X-all".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!( + listing["active_problem"], + serde_json::json!({ + "kind": "missing_manifest_for_id", + "runtime_id": "therock-release:gfx110X-all" + }) + ); + assert!(runtime_keys_flagged(&listing, "active").is_empty()); + Ok(()) + } + + #[test] + fn runtimes_list_json_reports_a_default_id_matching_two_runtimes_as_ambiguous() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-ambiguous-id"); + write_test_pip_runtime( + &paths, + "rt-newer", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + write_test_pip_runtime( + &paths, + "rt-older", + "therock-release:gfx120X-all", + "7.12.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let text = render_runtimes_text(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!( + listing["active_problem"], + serde_json::json!({ + "kind": "ambiguous_runtime_id", + "runtime_id": "therock-release:gfx120X-all", + "runtime_keys": ["rt-newer", "rt-older"] + }) + ); + assert!(runtime_keys_flagged(&listing, "active").is_empty()); + // The text form prints the same problem from the same value. + assert!( + text.contains( + " active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ + activate one runtime_key: rt-newer, rt-older\n" + ), + "{text}" + ); + Ok(()) + } + + /// `key` is present in `value` and `null`. Indexing a `serde_json::Value` + /// returns `null` for a missing key too, so `value[key] == Value::Null` + /// would stay green if the key were dropped from the document. + fn assert_null_field(value: &serde_json::Value, key: &str) { + assert_eq!( + value.as_object().and_then(|object| object.get(key)), + Some(&serde_json::Value::Null), + "`{key}` must be present and null:\n{value:#}" + ); + } + + /// The `runtime_key`s the text form marks with `glyph`, in listing order. + fn runtime_keys_marked(text: &str, glyph: &str) -> Vec { + text.lines() + .filter_map(|line| line.strip_prefix(&format!(" {glyph} "))) + .filter_map(|row| row.split_whitespace().next()) + .map(str::to_owned) + .collect() + } + + /// With no `active_runtime_key`, the listing matches `default_runtime_id` + /// ignoring ASCII letter case, and `active` and `active_problem` use that + /// one rule (`default_runtime_id_matches`). A default id that differs from + /// its one runtime's id only in case marks that runtime active and reports + /// no problem; `rocm config set-default-runtime` stores the id as typed, + /// so this state is one command away. Because both fields use the same + /// rule, `active_problem` never reports as missing a runtime that `active` + /// marks. + #[test] + fn runtimes_list_matches_a_default_id_differing_only_in_case_with_one_rule() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-default-id-case"); + write_test_pip_runtime( + &paths, + "rt-gfx120x", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some("THEROCK-RELEASE:GFX120X-ALL".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let text = render_runtimes_text(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-gfx120x"]); + assert_null_field(&listing, "active_problem"); + assert_eq!( + runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), + ["rt-gfx120x"] + ); + assert!(!text.contains("active_status:"), "{text}"); + Ok(()) + } + + /// Under the same rule, a default id matching two runtime ids that differ + /// only in letter case matches both: neither is active, and the listing + /// reports the id as ambiguous, naming both keys in listing order. The + /// runtime whose id equals the default exactly counts as one match among + /// the two, not as the winner. + #[test] + fn runtimes_list_reports_a_default_id_matching_ids_differing_only_in_case_as_ambiguous() + -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-ambiguous-id-case"); + write_test_pip_runtime( + &paths, + "rt-upper", + "therock-release:gfx120X-all", + "7.13.0", + 20, + )?; + write_test_pip_runtime( + &paths, + "rt-lower", + "therock-release:gfx120x-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + default_runtime_id: Some("therock-release:gfx120X-all".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let text = render_runtimes_text(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!( + listing["active_problem"], + serde_json::json!({ + "kind": "ambiguous_runtime_id", + "runtime_id": "therock-release:gfx120X-all", + "runtime_keys": ["rt-upper", "rt-lower"] + }) + ); + assert!(runtime_keys_flagged(&listing, "active").is_empty()); + assert!( + text.contains( + " active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ + activate one runtime_key: rt-upper, rt-lower\n" + ), + "{text}" + ); + Ok(()) + } + + /// The text prints `mode=` from `RuntimeMode::as_str` and the JSON from the + /// serde `kebab-case` rename; both are documented as the same words, so + /// every variant must agree. The exhaustive `match` turns a new variant + /// into a compile error here, which forces a look at this test, but it + /// does not add the variant to `all`: whoever adds the match arm must add + /// the variant to `all` too. + #[test] + fn runtime_mode_text_and_json_words_agree_for_every_variant() -> Result<()> { + let all = [RuntimeMode::Managed, RuntimeMode::ReadOnly]; + for mode in all { + match mode { + RuntimeMode::Managed | RuntimeMode::ReadOnly => {} + } + assert_eq!(serde_json::to_value(mode)?, mode.as_str(), "{mode:?}"); + } + Ok(()) + } + + /// The documented shape of `rocm runtimes list --json` (docs/json-output.md): + /// exactly these top-level and per-runtime keys, the registry and marker + /// paths, each runtime's own install root, and newest install first with + /// ties broken by `runtime_key`. + #[test] + fn runtimes_list_json_has_exactly_the_documented_fields_newest_install_first() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-contract"); + let mut install_roots = std::collections::BTreeMap::new(); + // Five runtimes share one install time and are planted in reverse key + // order, so the order the registry is read in cannot pass for the + // `runtime_key` tie-break by accident. + for (key, build) in [ + ("rt-old", 10), + ("rt-tie-e", 20), + ("rt-tie-d", 20), + ("rt-new", 30), + ("rt-tie-c", 20), + ("rt-tie-b", 20), + ("rt-tie-a", 20), + ] { + let manifest = write_test_pip_runtime( + &paths, + key, + "therock-release:gfx120X-all", + "7.13.0", + build, + )?; + install_roots.insert(key, manifest.install_root); + } + let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(&root); + + // Compared as sets: the key order of a `serde_json::Map` depends on + // whether its `preserve_order` feature is on, and is not documented. + let key_set = |value: &serde_json::Value| -> std::collections::BTreeSet { + value + .as_object() + .expect("an object") + .keys() + .cloned() + .collect() + }; + assert_eq!( + key_set(&listing), + std::collections::BTreeSet::from( + [ + "active_runtime_id", + "active_runtime_key", + "previous_runtime_key", + "registry", + "marker", + "active_problem", + "runtimes", + ] + .map(String::from) + ) + ); + assert_eq!( + listing["registry"], + serde_json::to_value(runtime_registry_dir(&paths))? + ); + assert_eq!( + listing["marker"], + serde_json::to_value(active_runtime_marker_path(&paths))? + ); + + let runtimes = listing["runtimes"] + .as_array() + .expect("runtimes is an array"); + let order: Vec<&str> = runtimes + .iter() + .map(|runtime| runtime["runtime_key"].as_str().unwrap_or_default()) + .collect(); + assert_eq!( + order, + [ + "rt-new", "rt-tie-a", "rt-tie-b", "rt-tie-c", "rt-tie-d", "rt-tie-e", "rt-old", + ] + ); + for runtime in runtimes { + assert_eq!( + key_set(runtime), + std::collections::BTreeSet::from( + [ + "runtime_key", + "runtime_id", + "version", + "format", + "family", + "mode", + "status", + "unusable_reason", + "toolchain", + "active", + "rollback_target", + "install_root", + ] + .map(String::from) + ) + ); + let key = runtime["runtime_key"].as_str().unwrap_or_default(); + assert_eq!( + runtime["install_root"], + serde_json::to_value(&install_roots[key])?, + "{key}" + ); + } + Ok(()) + } + + /// A runtime can be both the active one and the recorded rollback target + /// when the config says so (`rocm runtimes activate` and `rollback` never + /// write that, but the config file is read as it is). Both JSON flags are true; + /// the text has one marker column, and active wins it. + #[test] + fn runtimes_list_marks_a_runtime_both_active_and_rollback_target_as_active() -> Result<()> { + let (root, paths) = test_paths("runtime-list-active-and-rollback"); + write_test_pip_runtime( + &paths, + "rt-both", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let config = RocmCliConfig { + active_runtime_key: Some("rt-both".to_owned()), + previous_runtime_key: Some("rt-both".to_owned()), + ..RocmCliConfig::default() + }; + let listing = runtimes_list_json(&paths, &config)?; + let text = render_runtimes_text(&paths, &config)?; + let _ = fs::remove_dir_all(root); + + assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-both"]); + assert_eq!( + runtime_keys_flagged(&listing, "rollback_target"), + ["rt-both"] + ); + assert_eq!( + runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), + ["rt-both"] + ); + assert!( + runtime_keys_marked(&text, ROLLBACK_RUNTIME_MARKER).is_empty(), + "{text}" + ); + Ok(()) + } + + #[test] + fn runtimes_list_json_reports_a_runtime_whose_install_root_is_gone_as_unusable() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-unusable"); + let manifest = write_test_pip_runtime( + &paths, + "rt-gone", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + fs::remove_dir_all(&manifest.install_root)?; + let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; + let text = render_runtimes_text(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + let runtime = listed_runtime(&listing, "rt-gone"); + assert_eq!(runtime["status"], "unusable"); + let reason = runtime["unusable_reason"] + .as_str() + .expect("an unusable runtime says why"); + assert!(reason.starts_with("install root is missing: "), "{reason}"); + assert!( + text.contains(&format!("status=unusable ({reason}) toolchain=")), + "the text shows the same reason:\n{text}" + ); + Ok(()) + } + + #[test] + fn runtimes_list_json_reports_an_imported_runtime_as_read_only() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-read-only"); + let manifest = write_test_pip_runtime( + &paths, + "rt-imported", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let imported = therock::InstalledRuntimeManifest { + read_only: true, + ..manifest + }; + fs::write( + runtime_manifest_path(&paths, &imported.runtime_key), + serde_json::to_vec_pretty(&imported)?, + )?; + let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + assert_eq!(listed_runtime(&listing, "rt-imported")["mode"], "read-only"); + Ok(()) + } + #[cfg(unix)] fn test_active_runtime_marker(paths: &AppPaths, runtime_key: &str) -> ActiveRuntimeMarker { ActiveRuntimeMarker { diff --git a/docs/architecture.md b/docs/architecture.md index b97561e7a3..3811a8ae9d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,7 +108,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) | The installed-runtime registry: the manifest model, where manifests live, writing and loading them, selection and activation validation, and the active-runtime marker. | domain | | [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) | Reconciling running local servers with a runtime being activated or rolled back: classifying each, the report, and moving stale ones with `--restart-services`. | domain | | [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs) | `rocm runtimes uninstall`: planning, revalidating after the prompt, and applying the removal of a registered runtime, including clearing a Lemonade record inside its folder. | domain | -| [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback with the active-runtime marker write, and the runtime list. | relocation | +| [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) | `rocm runtimes` (`runtimes`): activation and rollback with the active-runtime marker write, and the runtime list (`runtimes_listing`, printed as text or `--json` through `JsonOrText`). | relocation | | [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) | `rocm serve` (`serve`): engine selection (`select_serve_engine`), the AIM pre-flight, and the GPU and device notes folded into the summary. | relocation | | [`serve_port.rs`](../apps/rocm/src/serve_port.rs) | The `rocm serve` port policy: turns an automatic or explicit `--port` request into one leased port before any manifest, log, key or child exists. | domain | | [`serve_recipe.rs`](../apps/rocm/src/serve_recipe.rs) | The pure transforms `serve()` applies to an engine's launch recipe hint: the catalog mapping, then `--tool-call-parser`, `--gpu-memory-utilization`, generation defaults and `--engine-env`. | relocation | @@ -859,7 +859,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, and a check that the text markers and JSON flags agree. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | | [`tests/e2e/service_stop_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_stop_steps.rs) | Steps for [`service_stop.feature`](../tests/e2e-cucumber/features/service_stop.feature) and [`engine_ipc.feature`](../tests/e2e-cucumber/features/engine_ipc.feature): `rocm services stop` and the daemon's `stop_server` tool against a planted service record, and how the daemon reads what an engine child prints, with a stand-in `rocm` staged beside a copy of `rocmd`; and the confirmed stop against a real recorded process, a recorded PID that now belongs to a different process, and a parent that has started a child. | flat | diff --git a/docs/json-output.md b/docs/json-output.md new file mode 100644 index 0000000000..c46b7353fb --- /dev/null +++ b/docs/json-output.md @@ -0,0 +1,167 @@ + + +# JSON output + +Which `rocm` commands print JSON with `--json`, the rules they follow, and the +commands that do not have it yet. + +## Rules + +- **Text is the default.** `--json` is opt-in per command; leaving it out never + changes the text a person reads. +- **JSON goes to stdout, and only JSON.** With `--json`, stdout holds one JSON + document and nothing else, so a script can parse all of it. Diagnostics, + progress and warnings go to stderr. A command that has no single document to + print is listed below as unsupported rather than given a `--json` that mixes + the two. +- **Errors are not JSON today.** A command that fails with `--json` prints its + error to stderr, prints nothing on stdout, and exits non-zero (1, unless the + command documents its own code, as `rocm fix` does). A script tells success + from failure by the exit code, not by parsing an error document. A JSON error + shape belongs to the shared envelope below. The one refusal printed as JSON + today is `rocm diagnose --report --json` declining to prepare a report: that + is the command working, so it exits 0 and prints `refusal_envelope` from + [report.rs](../crates/rocm-core/src/report.rs) (`schema`, `refused`, + `explanation`, `architecture_matrix`). +- **Documented fields do not change silently.** A field may be added. Renaming + or removing one, or giving it a new meaning, needs a versioned transition: + publish the new shape under a new version and keep the old one readable while + callers move. +- **Two shapes are frozen contracts** that other tools are built against: + - `rocm examine --json` — the Examination document the diagnosis tooling + reads. `examination_top_level_keys_match_examine_py_contract` in + [examine.rs](../crates/rocm-core/src/examine.rs) fails if a top-level field + is added, removed or renamed. + - `rocm fix --json` — the fix catalog, carrying `contract_version` + (`CATALOG_CONTRACT_VERSION` in + [manifest.rs](../crates/rocm-core/src/fix/manifest.rs), 1 today). The + rocm-doctor skill states the version it needs, and scenario `skill-07` + holds the two equal. +- **New commands print through the shared helper.** A command whose output is + one value implements `JsonOrText` and calls `print_json_or_text` in + [cli_report.rs](../apps/rocm/src/cli_report.rs), which writes pretty JSON plus + one newline, or the text, and nothing else. + +## Which commands have `--json` + +| Command | Today | Decision | Proven by | +|---|---|---|---| +| `rocm examine` | supported; pretty JSON | supported, frozen | `examine-07`, `examine-08`; `examination_top_level_keys_match_examine_py_contract` | +| `rocm diagnose` | supported; pretty JSON (`DiagnoseOutput` through `JsonOrText`); with `--report`, the prepared report or its refusal | supported | `diagnose-02`, `diagnose-03` | +| `rocm fix` | the catalog only: `--json` is refused with a fix id; `contract_version` 1 | catalog supported, frozen; a JSON result for applying one fix waits for the envelope | `skill-07` | +| `rocm update` | supported for the check; one compact JSON line, not pretty, and refused with `--apply` and `--dry-run` | supported; the compact form is a known difference from the others | `update-02`, `update-03` | +| `rocm storage report` | supported; pretty JSON through `JsonOrText` | supported | `json_or_text_impl_renders_the_report_and_serializes_it` | +| `rocm services list` | supported; pretty JSON. `rocm remote` reads it back over its control channel | supported | `services_json_round_trips_and_applies_the_same_liveness_filter_as_the_table`; exercised indirectly by `remote-15` (`@requires-docker`), whose `rocm remote` reads it back | +| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-19` to `runtime-lifecycle-23` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | +| `rocm runtimes activate`, `rollback`, `uninstall`, `import`, `adopt` | none | follow-up: they change state, so they need the envelope's result and refusal shapes | — | +| `rocm services logs` | none | intentionally unsupported: streamed text, and `-f` never ends | — | +| `rocm services stop`, `restart`, `remove`, `prune` | none | follow-up: needs the envelope, including the refusal path | — | +| `rocm install sdk`, `rocm install driver` | none | follow-up: long-running with progress; needs the envelope and an audit that progress stays off stdout | — | +| `rocm uninstall` | none (`--dry-run` prints the plan as text) | follow-up | — | +| `rocm daemon --status` | none | follow-up; a one-shot snapshot, so a good next command | — | +| `rocm daemon` | none | intentionally unsupported: it runs until stopped | — | + +Commands not in the table (for example `rocm engines list`, `rocm config show`, +`rocm automations list`, `rocm comfyui status`, `rocm setup status`, +`rocm version`) have no `--json` and no decision recorded yet. + +## `rocm runtimes list --json` + +The same listing as the text form, as one object: + +| Field | Value | +|---|---| +| `active_runtime_id` | the configured default runtime id as written in the config, or `null`. Not necessarily the active runtime's `runtime_id`: `active_runtime_key` takes precedence when set, and the id may differ from its runtime's in letter case or match no runtime at all. Read each runtime's `active` flag to see which one is in use | +| `active_runtime_key` | the configured active runtime key, or `null` | +| `previous_runtime_key` | the rollback target's key, or `null` | +| `registry`, `marker` | paths of the runtime registry folder and the active-runtime marker | +| `active_problem` | `null`, or why no runtime is active (matched as described under the known limitation below): `{"kind": "missing_manifest_for_key", "runtime_key"}`, `{"kind": "missing_manifest_for_id", "runtime_id"}`, or `{"kind": "ambiguous_runtime_id", "runtime_id", "runtime_keys": [...]}` | +| `runtimes` | one object per registered runtime, newest install first, ties broken by `runtime_key` | + +Each runtime carries `runtime_key`, `runtime_id`, `version` (as recorded; the +text adds the build date), `format`, `family`, `mode` (`managed` or +`read-only`), `status` (`ready` when the runtime passes the manifest check +that activation applies, `unusable` when it fails it; `ready` does not promise +that an activation succeeds), `unusable_reason` (`null` when ready, otherwise +why the runtime fails that check: text for a person, not a code to match on), +`toolchain` (`included` or `excluded`), `active`, +`rollback_target` and `install_root`. `active` and `rollback_target` are the facts the text marks with +`*` and `-`; a runtime that is both is shown as `*` in the text. The text's +next-step hint for an empty registry is not part of the JSON. + +### Known limitation: the listing's matching rules + +`rocm runtimes list` decides which runtime is active, which is the rollback +target and what `active_problem` says with rules of its own, which are not all +the ones `rocm examine`, `rocm runtimes activate` and `rocm runtimes rollback` +resolve with. Today: + +- When `active_runtime_key` is set, `active` marks the runtime whose key + equals it exactly, and `active_problem` is `missing_manifest_for_key` when + no runtime's key equals it exactly. `default_runtime_id` is then not + consulted. +- When no `active_runtime_key` is set, `default_runtime_id` is matched against + each runtime's id with ASCII letter case ignored, by one rule for both + fields: exactly one match is marked `active` with `active_problem` `null`; no + match gives `missing_manifest_for_id`; several give `ambiguous_runtime_id` + and nothing active. `rocm config set-default-runtime` reaches this state: it + stores the id as typed, clears `active_runtime_key` and + `previous_runtime_key`, and tries to remove the active-runtime marker file + (best effort: a failed removal is ignored). +- `rollback_target` marks the runtime whose key equals `previous_runtime_key` + exactly. + +The commands acting on the active runtime also accept an `active_runtime_key` +that differs from a runtime's only in letter case, and fall back to +`default_runtime_id` when `active_runtime_key` names no runtime. +`rocm runtimes rollback` also ignores whitespace around `previous_runtime_key` +and accepts one that differs from a runtime's key in letter case or names a +runtime by its id. For the active runtime, the commands take the first +runtime in list order whose key matches `active_runtime_key` ignoring case, +even when a later one has that key exactly; rollback tries an exact match +first. + +The CLI records the active and rollback keys exactly as the runtimes have +them, so most of these differences need a change made outside the CLI: a key +edited by hand in the config shows nothing active in the listing, or no +rollback target; and if the active runtime's registry entry is deleted while +exactly one other registered runtime has the same id as `default_runtime_id` +(activation records the active runtime's id there), the commands fall back to +that runtime while the listing reports `missing_manifest_for_key`. One +difference is reachable from the CLI alone, on a case-sensitive filesystem: +`rocm runtimes import` and `rocm runtimes adopt --runtime-key` store keys as +given, so two runtimes can have keys that differ only in letter case. When the +one activated by its exact key is not the first of the two in list order, the +listing marks it active while the commands act on the other. Each registry +entry is a file named `.json`, so on a case-insensitive filesystem (the +default on Windows volumes, and on drvfs mounts under WSL) the second key names +the first one's file: the command refuses it, or with `--replace` overwrites +the first runtime's entry, and this state cannot occur. + +`active` and `rollback_target` mean what the rules above say, and that meaning +is part of the documented shape. Changing those rules, for example to match the +resolution `rocm examine` uses, would change what the two flags report for the +same configuration, so it is a contract change under the versioning rule +above, not an additive one. + +The shape is additive-only: fields may be added, none will be renamed or +removed without a versioned transition. It carries no version field yet; one +arrives with the envelope if that is adopted. + +## Open decision: a shared envelope + +Every command above prints its own top-level value (an object, or for +`rocm services list` an array). The mutating commands that +are still follow-ups need more than a value: whether the action ran, was +refused or failed, and why, in a shape a script can rely on across commands. A +shared envelope (for example a version, an outcome, the command's result and an +error object) would give them that. + +It is not adopted. Wrapping the existing outputs in it would change documented +shapes, including the two frozen contracts, so it can only arrive alongside +them, under a versioned transition, and the decision belongs with the first +mutating command that needs it. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 5666fcb787..ce66d89c54 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -111,6 +111,21 @@ Expected result: - `rocm runtimes list` shows the runtime key for the installed TheRock venv. - The active runtime is ready, or the output gives one clear next command. +Then read the same listing as JSON: + +```powershell +rocm runtimes list --json | python -m json.tool +``` + +Expected result: + +- `python -m json.tool` accepts the output and prints it back. Only stdout + enters the pipeline (stderr still shows on the console), so this checks that + stdout holds the document alone; a parse error means something else, such as + a banner, progress or hint line, reached stdout. +- The runtime the text form marks `*` has `"active": true`, and it is the only + one; the runtime marked `-`, if any, has `"rollback_target": true`. + Optional: an unreadable settings file. Copy `config.json` from the config directory aside, cut the original off part-way through, and run `rocm version` without `ROCM_CLI_DATA_DIR` set. Expected result: diff --git a/docs/testing.md b/docs/testing.md index faa7b7970c..c98ad7982b 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1786,6 +1786,60 @@ List registered managed or read-only runtimes and their exact side-by-side keys: ```bash rocm runtimes list +rocm runtimes list --json +``` + +`--json` prints the same listing as one JSON document on stdout and nothing +else: unset values are `null` rather than ``, each runtime carries +`active` and `rollback_target` flags computed from the same values the text's +`*`/`-` markers are drawn from, and the empty-registry next-step hint is +text-only. The rules every `--json` command follows, and which commands have +one, are in [json-output.md](json-output.md). Scenarios +`@id:runtime-lifecycle-list-json-marks-active-and-rollback` +(`runtime-lifecycle-19`) and `@id:runtime-lifecycle-list-json-empty-registry` +(`runtime-lifecycle-20`) parse the whole of stdout as one document, so a stray +line before or after it fails them; `runtime-lifecycle-19` also checks each +runtime's values as planted, lists the same state as text and checks that the +`*`/`-` rows name the runtimes the JSON flags, and `runtime-lifecycle-07` covers +the text markers on their own. +`@id:runtime-lifecycle-list-json-reports-unusable-runtime` +(`runtime-lifecycle-21`) deletes a runtime's folder and reads +`"status": "unusable"` with the reason `install root is missing: `, and +`@id:runtime-lifecycle-list-json-reports-missing-active-manifest` +(`runtime-lifecycle-22`) deletes the active runtime's registry entry and reads +`active_problem` of kind `missing_manifest_for_key`. No scenario checks the +listing's order: scenario 19's two runtimes share one install time, and the +registry is read in filesystem order, which can match key order by chance. +The order is pinned by unit tests: +`runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` +plants five runtimes with one install time in reverse key order beside older +and newer ones, and `registry_sort_is_newest_install_first_then_by_key` tests +the sort on its own. + +The listing's matching rules, including how it uses `default_runtime_id` +and where it differs from what `rocm examine` and `rocm runtimes +activate`/`rollback` resolve, are in +[json-output.md](json-output.md#known-limitation-the-listings-matching-rules). +`rocm config set-default-runtime` reaches the state where only +`default_runtime_id` is set. +`@id:runtime-lifecycle-list-default-id-in-other-letter-case` +(`runtime-lifecycle-23`) sets the first runtime's id in upper case and checks +that the JSON marks that runtime active with `active_problem` `null`, and that +the text marks it `*` with no `active_status:` line. The other branches of that +path are covered by unit tests: +`runtimes_list_json_marks_the_one_runtime_matching_the_default_id_active` +(an exact single match), +`runtimes_list_matches_a_default_id_differing_only_in_case_with_one_rule`, +`runtimes_list_json_reports_a_default_id_with_no_manifest` +(`missing_manifest_for_id`), +`runtimes_list_json_reports_a_default_id_matching_two_runtimes_as_ambiguous` +and `runtimes_list_reports_a_default_id_matching_ids_differing_only_in_case_as_ambiguous` +(`ambiguous_runtime_id`): + +```bash +cargo xtask e2e -- -n "runtime-lifecycle-(07|19|20|21|22|23) " +cargo test -p rocm --bin rocm runtimes_list +cargo test -p rocm --bin rocm registry_sort_is_newest_install_first_then_by_key ``` Activate one validated runtime: @@ -1904,6 +1958,7 @@ Focused unit coverage: ```bash cargo test -p rocm --bin rocm runtime_activation +cargo test -p rocm --bin rocm runtimes_list cargo test -p rocm --bin rocm runtime_import cargo test -p rocm --bin rocm runtime_adopt cargo test -p rocm --bin rocm runtime_install_writes diff --git a/docs/ux-guidelines.md b/docs/ux-guidelines.md index eb71fb298d..72b161daee 100644 --- a/docs/ux-guidelines.md +++ b/docs/ux-guidelines.md @@ -179,3 +179,11 @@ Command navigability follow-up notes: - Keep backend labels such as wheels, tarballs, runtime keys, registries, and daemon policy out of first-visible TUI screens unless the user opens an explicit advanced/debug view. + +## Machine-Readable Output + +- Text for a person is the default; `--json` is an explicit opt-in per command. +- With `--json`, stdout carries one JSON document and nothing else. Progress, + warnings and diagnostics go to stderr so a piped document stays parseable. +- Which commands have `--json`, the frozen contracts, and the rules for + changing a documented field are in [json-output.md](json-output.md). diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index 5f8da06c42..ec303ecfb4 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -262,3 +262,63 @@ Feature: Runtime lifecycle state machine And the server is still counted as left on the first runtime And the switch to the second runtime was kept And the server record still names the first runtime + + # A script reads the runtime list without scraping the table. stdout must hold + # one JSON document and nothing else; diagnostics belong on stderr. The active + # and rollback flags are the facts the text marks with `*` and `-`, so the + # scenario also lists the same state as text and checks that both forms mark + # the same runtimes. + @id:runtime-lifecycle-list-json-marks-active-and-rollback + Scenario: runtime-lifecycle-19 - A script reads the runtime list as JSON + Given two registered runtimes with the second active after the first + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON lists both runtimes with their recorded values + And the JSON marks the second runtime active and the first as the rollback target + And the text listing marks the same runtimes as the JSON + + # The empty registry is where the text form prints placeholders (``) + # and a next-step hint; the JSON form has to stay a parseable document with + # nulls instead, not fall back to that text. + @id:runtime-lifecycle-list-json-empty-registry + Scenario: runtime-lifecycle-20 - Listing runtimes as JSON with none registered + Given no ROCm runtime is registered + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON lists no runtimes and no active runtime + + # A runtime whose folder was deleted outside the CLI stays registered, but + # activation would refuse it. A script has to see that from the document + # alone, without trying the activation. + @id:runtime-lifecycle-list-json-reports-unusable-runtime + Scenario: runtime-lifecycle-21 - The JSON runtime list reports a runtime whose folder is gone as unusable + Given two registered runtimes with the second active after the first + And the first runtime's folder has been deleted + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON reports the first runtime unusable because its folder is missing + And the JSON reports the second runtime ready + + # The active runtime's registry entry was removed by hand while the config + # still names it. The document has to say so, not just mark nothing active. + @id:runtime-lifecycle-list-json-reports-missing-active-manifest + Scenario: runtime-lifecycle-22 - The JSON runtime list says when the active runtime's registry entry is gone + Given two registered runtimes with the second active after the first + And the second runtime's registry entry has been deleted + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON reports that the active runtime key has no registered runtime + And the JSON marks no runtime active + + # `rocm config set-default-runtime` stores the id as typed and clears the + # active key, so the list decides the active runtime from the default id + # alone. An id that differs from a runtime's only in letter case still names + # that runtime, and the list must not also report its registry entry missing. + @id:runtime-lifecycle-list-default-id-in-other-letter-case + Scenario: runtime-lifecycle-23 - A default runtime set in other letter case is listed as active with no problem + Given two registered runtimes and none active + When the user sets the default runtime to the first runtime's id in other letter case + And the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON marks only the first runtime active and reports no problem + And the text listing marks the first runtime active with no active_status line diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 1838780c1e..2c9dd7e179 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -27,6 +27,14 @@ use crate::E2eWorld; // `:` form only in `runtime_id`, which is a manifest field value, never a filename. const FIRST_KEY: &str = "release-tarball-gfx942"; const SECOND_KEY: &str = "release-tarball-gfx1100"; +/// The GPU families `FIRST_KEY` and `SECOND_KEY` are planted with; each family +/// also names the runtime's install folder (see [`planted_install_root`]). +const FIRST_FAMILY: &str = "gfx942"; +/// The version every planted runtime records: a dated nightly-style version, so +/// the JSON (which carries the version as recorded) and the text (which adds +/// the build date) can be told apart. +const PLANTED_VERSION: &str = "7.14.0a20260601"; +const SECOND_FAMILY: &str = "gfx1100"; /// Two keys that differ only in letter case. Each is its own `.json` in the /// registry, so the pair can only coexist on a case-sensitive filesystem — which /// is why the scenario using them carries `@requires-case-sensitive-fs`. @@ -66,8 +74,7 @@ fn plant_runtime(world: &E2eWorld, key: &str, family: &str) -> PathBuf { .all(|ch| ch.is_ascii_alphanumeric() || ch == '-'), "runtime key must be production-style and safe as a registry filename: {key}" ); - let root = world.isolated_root.as_ref().expect("no isolated root"); - let install_root = root.path().join(format!("runtime-{family}")); + let install_root = planted_install_root(world, family); std::fs::create_dir_all(&install_root).expect("failed to create install root"); std::fs::write(install_root.join("payload.txt"), "payload") .expect("failed to write runtime payload"); @@ -80,6 +87,16 @@ fn plant_runtime(world: &E2eWorld, key: &str, family: &str) -> PathBuf { install_root } +/// Where [`plant_runtime`] puts the install root of a runtime of `family`. +fn planted_install_root(world: &E2eWorld, family: &str) -> PathBuf { + world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join(format!("runtime-{family}")) +} + /// The runtime registry under the scenario's isolated data dir — where the CLI /// reads `.json` manifests from. One definition, so a layout change cannot /// leave the planting and the counting looking in different places. @@ -118,7 +135,7 @@ fn runtime_manifest_json(key: &str, family: &str, install_root: &Path) -> String "format": "tarball", "family": family, "family_source": "manual", - "version": "1.0.0", + "version": PLANTED_VERSION, "install_root": install_root, "selected_artifact_url": format!("https://example.invalid/{key}.tar.gz"), "read_only": true, @@ -302,20 +319,47 @@ fn write_import_manifest(world: &E2eWorld) -> PathBuf { #[given("two registered runtimes and none active")] async fn two_runtimes(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, "gfx942"); - plant_runtime(world, SECOND_KEY, "gfx1100"); + plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + plant_runtime(world, SECOND_KEY, SECOND_FAMILY); } #[given("two registered runtimes with the second active after the first")] async fn two_runtimes_second_active(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, "gfx942"); - plant_runtime(world, SECOND_KEY, "gfx1100"); + plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + plant_runtime(world, SECOND_KEY, SECOND_FAMILY); // Activate first, then second, so `previous_runtime_key` records the first — // the state rollback must return to. crate::run_rocm_ok(world, &["runtimes", "activate", FIRST_KEY]); crate::run_rocm_ok(world, &["runtimes", "activate", SECOND_KEY]); } +/// Nothing to plant: each scenario starts from an empty isolated root. Asserted +/// rather than assumed, so a fixture that starts seeding runtimes cannot turn +/// the empty-registry scenario into one that lists something. +#[given("no ROCm runtime is registered")] +async fn no_runtime_registered(world: &mut E2eWorld) { + let registry = registry_dir(world); + let registered = std::fs::read_dir(®istry).map_or(0, Iterator::count); + assert_eq!( + registered, + 0, + "the isolated registry {} must start empty", + registry.display() + ); +} + +#[given("the first runtime's folder has been deleted")] +async fn first_runtime_folder_deleted(world: &mut E2eWorld) { + std::fs::remove_dir_all(planted_install_root(world, FIRST_FAMILY)) + .expect("failed to delete the first runtime's install root"); +} + +#[given("the second runtime's registry entry has been deleted")] +async fn second_runtime_manifest_deleted(world: &mut E2eWorld) { + std::fs::remove_file(registry_dir(world).join(format!("{SECOND_KEY}.json"))) + .expect("failed to delete the second runtime's manifest"); +} + #[given("two registered runtimes whose keys differ only in letter case")] async fn two_case_twin_runtimes(world: &mut E2eWorld) { // Distinct families only so each twin gets its own install root. @@ -347,8 +391,8 @@ async fn two_case_twin_runtimes(world: &mut E2eWorld) { #[given("two registered runtimes and a local server recorded on the first")] async fn two_runtimes_and_service_on_first(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, "gfx942"); - plant_runtime(world, SECOND_KEY, "gfx1100"); + plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + plant_runtime(world, SECOND_KEY, SECOND_FAMILY); // Planted BEFORE either activation, so the same record covers both halves of // the scenario: while the first runtime is the one being activated the // server is on it (nothing left behind), and activating the second leaves it @@ -358,8 +402,8 @@ async fn two_runtimes_and_service_on_first(world: &mut E2eWorld) { #[given("two registered runtimes and a publicly bound local server recorded on the first")] async fn two_runtimes_and_public_service_on_first(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, "gfx942"); - plant_runtime(world, SECOND_KEY, "gfx1100"); + plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + plant_runtime(world, SECOND_KEY, SECOND_FAMILY); // `0.0.0.0` with no endpoint key file planted is the whole setup. Restarting // a public bind that has no key is refused before the stop, so the // activation's restart fails while the server is left up on the first @@ -369,8 +413,8 @@ async fn two_runtimes_and_public_service_on_first(world: &mut E2eWorld) { #[given("two registered runtimes and a local server recording no runtime")] async fn two_runtimes_and_service_without_runtime(world: &mut E2eWorld) { - plant_runtime(world, FIRST_KEY, "gfx942"); - plant_runtime(world, SECOND_KEY, "gfx1100"); + plant_runtime(world, FIRST_KEY, FIRST_FAMILY); + plant_runtime(world, SECOND_KEY, SECOND_FAMILY); // `runtime_id: None` is the whole setup — a record that predates runtime // pinning and so says nothing about which runtime its server loaded. write_service_record_with( @@ -432,7 +476,7 @@ async fn services_cannot_be_read(world: &mut E2eWorld) { #[given("a registered read-only runtime")] async fn one_readonly_runtime(world: &mut E2eWorld) { - let install_root = plant_runtime(world, FIRST_KEY, "gfx942"); + let install_root = plant_runtime(world, FIRST_KEY, FIRST_FAMILY); // Stash the install_root path so the uninstall scenario can assert it survives. world.model_name = Some(install_root.to_string_lossy().into_owned()); } @@ -584,6 +628,24 @@ async fn list_runtimes(world: &mut E2eWorld) { record(world, stdout, stderr, rc); } +/// The first runtime's id in upper case, which differs from the registered +/// `therock-release:gfx942` only in letter case. +fn first_runtime_id_in_other_case() -> String { + format!("therock-release:{FIRST_FAMILY}").to_ascii_uppercase() +} + +#[when("the user sets the default runtime to the first runtime's id in other letter case")] +async fn set_default_runtime_in_other_case(world: &mut E2eWorld) { + let runtime_id = first_runtime_id_in_other_case(); + crate::run_rocm_ok(world, &["config", "set-default-runtime", &runtime_id]); +} + +#[when("the user lists the registered runtimes as JSON")] +async fn list_runtimes_json(world: &mut E2eWorld) { + let (stdout, stderr, rc) = crate::run_rocm(world, &["runtimes", "list", "--json"]); + record(world, stdout, stderr, rc); +} + #[when("the user uninstalls that runtime")] async fn uninstall(world: &mut E2eWorld) { let (stdout, stderr, rc) = @@ -872,6 +934,291 @@ async fn second_marked_rollback(world: &mut E2eWorld) { ); } +/// The whole of stdout parsed as one JSON value: `serde_json::from_str` refuses +/// anything but whitespace after the value, so a stray line before or after the +/// document fails here rather than in a script that pipes it. +fn listing_json(world: &E2eWorld) -> serde_json::Value { + let out = ok_output(world); + serde_json::from_str(&out).unwrap_or_else(|error| { + panic!( + "stdout of `runtimes list --json` is not one JSON document ({error}):\n{}", + combined(world) + ) + }) +} + +/// The `runtime_key` of every listed runtime whose boolean `flag` is set. +/// Every runtime must carry `flag` as a boolean: read through `runtime[flag]` +/// alone, a missing or renamed field would count as `false` and an assertion +/// that nothing is flagged would still pass. +fn listed_keys_with(listing: &serde_json::Value, flag: &str) -> Vec { + listing["runtimes"] + .as_array() + .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")) + .iter() + .filter(|runtime| { + runtime + .get(flag) + .and_then(serde_json::Value::as_bool) + .unwrap_or_else(|| panic!("a runtime has no boolean `{flag}`:\n{listing:#}")) + }) + .map(|runtime| { + runtime["runtime_key"] + .as_str() + .unwrap_or_else(|| panic!("a runtime has no runtime_key:\n{listing:#}")) + .to_owned() + }) + .collect() +} + +/// The `runtime_key`s of the runtime rows the text form of `runtimes list` +/// marks with `glyph`, in listing order. A row is exactly what the CLI's +/// `write_marked_row` prints under `installed:`: two spaces, the marker, a +/// space, then ` runtime_id=...`. Anchoring on that layout keeps a +/// legend, status or path line that happens to start with `- ` from counting. +fn text_rows_marked(text: &str, glyph: &str) -> Vec { + text.lines() + .filter_map(|line| line.strip_prefix(&format!(" {glyph} "))) + .filter_map(|row| { + let (key, rest) = row.split_once(' ')?; + rest.starts_with("runtime_id=").then(|| key.to_owned()) + }) + .collect() +} + +#[then("the output is a single JSON document and nothing else")] +async fn output_is_one_json_document(world: &mut E2eWorld) { + let listing = listing_json(world); + assert!( + listing.is_object(), + "expected a JSON object, got:\n{listing:#}" + ); + let out = world.cli_output.as_deref().unwrap_or_default(); + assert!( + out.starts_with('{'), + "stdout must start with the document itself, got {out:?}" + ); + assert!( + out.ends_with('\n') && !out.ends_with("\n\n"), + "the document must end with exactly one newline, got {out:?}" + ); +} + +/// `key` is present in `value` and `null`. `value[key]` alone reads a missing +/// key as `null` too, so it would not notice the key being dropped. +fn assert_null_field(value: &serde_json::Value, key: &str) { + assert_eq!( + value.as_object().and_then(|object| object.get(key)), + Some(&serde_json::Value::Null), + "`{key}` must be present and null:\n{value:#}" + ); +} + +/// The listed runtime whose `runtime_key` is `key`. +fn listed_runtime<'a>(listing: &'a serde_json::Value, key: &str) -> &'a serde_json::Value { + listing["runtimes"] + .as_array() + .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")) + .iter() + .find(|runtime| runtime["runtime_key"] == key) + .unwrap_or_else(|| panic!("{key} is not listed:\n{listing:#}")) +} + +/// Both planted runtimes, each with the values `plant_runtime` recorded in its +/// manifest, and nothing else. The listing's order is not checked here: both +/// share one install time, so the order rests on the `runtime_key` tie-break, +/// which the unit tests +/// `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` +/// and `registry_sort_is_newest_install_first_then_by_key` pin. +#[then("the JSON lists both runtimes with their recorded values")] +async fn json_lists_both_runtimes(world: &mut E2eWorld) { + let listing = listing_json(world); + let mut listed: Vec<&str> = listing["runtimes"] + .as_array() + .expect("`runtimes` is an array") + .iter() + .map(|runtime| runtime["runtime_key"].as_str().unwrap_or_default()) + .collect(); + listed.sort_unstable(); + let mut expected = [FIRST_KEY, SECOND_KEY]; + expected.sort_unstable(); + assert_eq!(listed, expected, "{listing:#}"); + for (key, family) in [(FIRST_KEY, FIRST_FAMILY), (SECOND_KEY, SECOND_FAMILY)] { + let runtime = listed_runtime(&listing, key); + assert_eq!( + runtime["runtime_id"], + format!("therock-release:{family}"), + "{key}" + ); + assert_eq!(runtime["family"], family, "{key}"); + assert_eq!(runtime["format"], "tarball", "{key}"); + // As recorded, not the text's display form with the build date. + assert_eq!(runtime["version"], PLANTED_VERSION, "{key}"); + assert_eq!(runtime["mode"], "read-only", "{key}"); + assert_eq!(runtime["status"], "ready", "{key}"); + assert_null_field(runtime, "unusable_reason"); + // The planted manifest has no `devel` field, which the CLI reads as + // a legacy install that included the toolchain. + assert_eq!(runtime["toolchain"], "included", "{key}"); + let install_root = runtime["install_root"] + .as_str() + .unwrap_or_else(|| panic!("{key} has no install_root:\n{listing:#}")); + assert_eq!( + Path::new(install_root), + planted_install_root(world, family), + "{key}" + ); + } +} + +#[then("the JSON marks the second runtime active and the first as the rollback target")] +async fn json_marks_active_and_rollback(world: &mut E2eWorld) { + let listing = listing_json(world); + assert_eq!( + listed_keys_with(&listing, "active"), + [SECOND_KEY], + "{listing:#}" + ); + assert_eq!( + listed_keys_with(&listing, "rollback_target"), + [FIRST_KEY], + "{listing:#}" + ); + assert_eq!(listing["active_runtime_key"], SECOND_KEY, "{listing:#}"); + assert_eq!(listing["previous_runtime_key"], FIRST_KEY, "{listing:#}"); + // A healthy state reports no problem, in either form. + assert_null_field(&listing, "active_problem"); + let text = crate::run_rocm_ok(world, &["runtimes", "list"]); + assert!( + !text.contains("active_status:"), + "a healthy listing must print no active_status line:\n{text}" + ); +} + +#[then("the JSON lists no runtimes and no active runtime")] +async fn json_lists_nothing(world: &mut E2eWorld) { + let listing = listing_json(world); + assert_eq!(listing["runtimes"], serde_json::json!([]), "{listing:#}"); + for unset in [ + "active_runtime_id", + "active_runtime_key", + "previous_runtime_key", + "active_problem", + ] { + assert_null_field(&listing, unset); + } + // The paths are reported even with nothing registered, and each is the + // isolated data dir's own: swapping the two would fail here. + let runtimes_dir = registry_dir(world) + .parent() + .expect("the registry has a parent") + .to_path_buf(); + for (field, expected) in [ + ("registry", registry_dir(world)), + ("marker", runtimes_dir.join("active.json")), + ] { + let reported = listing + .get(field) + .and_then(serde_json::Value::as_str) + .unwrap_or_else(|| panic!("`{field}` is not a path:\n{listing:#}")); + assert_eq!(Path::new(reported), expected, "`{field}`:\n{listing:#}"); + } +} + +/// Lists the same state as text and compares its `*`/`-` rows with the JSON +/// flags just read, so the two forms are shown to agree, not assumed to. +#[then("the text listing marks the same runtimes as the JSON")] +async fn text_marks_match_json(world: &mut E2eWorld) { + let listing = listing_json(world); + let text = crate::run_rocm_ok(world, &["runtimes", "list"]); + let active = listed_keys_with(&listing, "active"); + // Two empty lists agree too; this step is only evidence where something is + // active. + assert!( + !active.is_empty(), + "the JSON marks no runtime active, so there is nothing to compare:\n{listing:#}" + ); + // The text has one marker column and gives it to `*` when a runtime is + // both active and the rollback target, so `-` shows only the others. + let rollback_only: Vec = listed_keys_with(&listing, "rollback_target") + .into_iter() + .filter(|key| !active.contains(key)) + .collect(); + assert_eq!(text_rows_marked(&text, "*"), active, "{text}"); + assert_eq!(text_rows_marked(&text, "-"), rollback_only, "{text}"); +} + +#[then("the JSON marks only the first runtime active and reports no problem")] +async fn json_marks_first_active_without_problem(world: &mut E2eWorld) { + let listing = listing_json(world); + // The state under test: the id as typed, and no active key. + assert_eq!( + listing["active_runtime_id"], + first_runtime_id_in_other_case(), + "{listing:#}" + ); + assert_null_field(&listing, "active_runtime_key"); + assert_eq!( + listed_keys_with(&listing, "active"), + [FIRST_KEY], + "{listing:#}" + ); + assert_null_field(&listing, "active_problem"); +} + +#[then("the text listing marks the first runtime active with no active_status line")] +async fn text_marks_first_active_without_status(world: &mut E2eWorld) { + let text = crate::run_rocm_ok(world, &["runtimes", "list"]); + assert_eq!(text_rows_marked(&text, "*"), [FIRST_KEY], "{text}"); + assert!( + !text.contains("active_status:"), + "the runtime it marks active must not also be reported missing:\n{text}" + ); +} + +#[then("the JSON reports the first runtime unusable because its folder is missing")] +async fn json_reports_first_unusable(world: &mut E2eWorld) { + let listing = listing_json(world); + let runtime = listed_runtime(&listing, FIRST_KEY); + assert_eq!(runtime["status"], "unusable", "{listing:#}"); + // The reason is prose for a person, not a code; it is the message + // activation refuses with, naming the folder that is gone. + let folder = planted_install_root(world, FIRST_FAMILY); + assert_eq!( + runtime["unusable_reason"], + format!("install root is missing: {}", folder.display()), + "{listing:#}" + ); +} + +#[then("the JSON reports the second runtime ready")] +async fn json_reports_second_ready(world: &mut E2eWorld) { + let listing = listing_json(world); + let runtime = listed_runtime(&listing, SECOND_KEY); + assert_eq!(runtime["status"], "ready", "{listing:#}"); + assert_null_field(runtime, "unusable_reason"); +} + +#[then("the JSON reports that the active runtime key has no registered runtime")] +async fn json_reports_missing_active_manifest(world: &mut E2eWorld) { + let listing = listing_json(world); + assert_eq!( + listing["active_problem"], + serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": SECOND_KEY}), + "{listing:#}" + ); + assert_eq!(listing["active_runtime_key"], SECOND_KEY, "{listing:#}"); +} + +#[then("the JSON marks no runtime active")] +async fn json_marks_none_active(world: &mut E2eWorld) { + let listing = listing_json(world); + assert!( + listed_keys_with(&listing, "active").is_empty(), + "{listing:#}" + ); +} + #[then("the CLI refuses and requires --yes")] async fn uninstall_refused_without_yes(world: &mut E2eWorld) { let rc = world.cli_rc.expect("no command rc recorded"); From 70b3926f1ad2102bbd33995bd447c8abd15ac780 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 13:01:29 +0200 Subject: [PATCH 2/5] fix(runtimes): list the runtime the commands act on (ROCMAI-148) `rocm runtimes list` decided which runtime was active and which was the rollback target by rules of its own, so it could mark a runtime other than the one `rocm examine`, `rocm runtimes activate`, `rollback`, `uninstall` and `rocm update` act on: an active key in other letter case, a dead key whose default id still resolves, case-twin keys, or a previous key that rollback trims, matches ignoring case or reads as a runtime id. The listing now asks the resolvers those commands use: `current_runtime_manifest` for `active` and `select_runtime_manifest` on `previous_runtime_key` for `rollback_target`. `active_problem` reports the configuration with the same matching, so a dead active key is still reported as `missing_manifest_for_key` while the runtime the commands fall back to is marked active. The resolvers are unchanged. In the JSON, `active_runtime_id` is renamed `default_runtime_id`, the config value it carries; the text label stays `active_runtime_id:`. `registry`, `marker` and `install_root` are written lossily, so a path that is not valid UTF-8 no longer makes `--json` fail with empty stdout. `toolchain` is an enum serialized with the words the text and `rocm examine` print. docs/json-output.md describes which runtimes are marked, lists the surfaces that still resolve differently (the dash runtime manager, `rocm setup status`, `rocm engines install`), and states the exit codes: 1 for a failed command unless documented, 2 for a command line the argument parser rejects. The dash comment keeps only the dash's own rules and points there. A state matrix of in-memory unit tests covers every configuration row; scenarios runtime-lifecycle-24 and -25 check an active key in other letter case and a dead key falling back to the default id, each against `rocm examine --json`. Signed-off-by: Roman Inflianskas --- apps/rocm/src/dash.rs | 25 +- apps/rocm/src/runtimes_cmd.rs | 826 ++++++++++++++++-- docs/architecture.md | 2 +- docs/json-output.md | 156 ++-- docs/manual-testing.md | 2 + docs/testing.md | 64 +- .../features/runtime_lifecycle.feature | 32 + .../tests/e2e/runtime_lifecycle_steps.rs | 149 +++- 8 files changed, 1064 insertions(+), 192 deletions(-) diff --git a/apps/rocm/src/dash.rs b/apps/rocm/src/dash.rs index aaa5ce429b..21a4cc01e0 100644 --- a/apps/rocm/src/dash.rs +++ b/apps/rocm/src/dash.rs @@ -212,26 +212,11 @@ fn runtime_summaries(paths: &AppPaths, config: &RocmCliConfig) -> Vec = manifests .iter() .filter(|m| Some(m.runtime_id.as_str()) == default_id) diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index d900cf5dec..780fb35ddc 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -599,25 +599,36 @@ const ROLLBACK_RUNTIME_MARKER: &str = "-"; pub(crate) struct RuntimesListing { /// `default_runtime_id` from the config, as configured; `null` when unset. /// Not necessarily the active runtime's `runtime_id`: an `active_runtime_key` - /// takes precedence, and the id may differ in letter case or match nothing. - active_runtime_id: Option, + /// that names a runtime takes precedence, and the id may differ in letter + /// case or match nothing. The text form labels it `active_runtime_id:`, as + /// `rocm examine` does. + default_runtime_id: Option, active_runtime_key: Option, previous_runtime_key: Option, + /// Paths are written with `to_string_lossy`, so a path that is not valid + /// UTF-8 is listed with U+FFFD in place of its bad bytes rather than + /// failing the whole document. + #[serde(serialize_with = "serialize_path_lossy")] registry: PathBuf, + #[serde(serialize_with = "serialize_path_lossy")] marker: PathBuf, - /// Why the configured active runtime cannot be resolved, or `null`. + /// What is wrong with the configured active runtime setting, or `null`. + /// See [`active_runtime_problem`] for when it is set beside an `active` + /// runtime. active_problem: Option, /// Newest install first, ties broken by `runtime_key`, as the registry /// loader sorts them (`sort_manifests_newest_install_first`). runtimes: Vec, } -/// Why the configured active runtime does not resolve to one manifest. The -/// text form prints it as the `active_status:` line. +/// What is wrong with the configured active runtime setting. The text form +/// prints it as the `active_status:` line. #[derive(Debug, Serialize, PartialEq, Eq)] #[serde(tag = "kind", rename_all = "snake_case")] enum ActiveRuntimeProblem { - /// `active_runtime_key` is set but no registered manifest has that key. + /// `active_runtime_key` is set but names no registered runtime, ASCII + /// letter case ignored. Reported even when `default_runtime_id` then + /// resolves a runtime, which the listing marks `active`. MissingManifestForKey { runtime_key: String }, /// No `active_runtime_key`; `default_runtime_id` matches no manifest's id, /// ASCII letter case ignored. @@ -644,13 +655,53 @@ struct RuntimeListingEntry { /// Serialized as the two JSON fields `status` and `unusable_reason`. #[serde(flatten)] usability: RuntimeUsability, - /// `included` or `excluded`, the words `toolchain_state_text` uses. - toolchain: &'static str, + toolchain: RuntimeToolchain, + /// The runtime `current_runtime_manifest` resolves for this config: the + /// one `rocm examine`, `rocm runtimes activate` and `rollback` treat as + /// the active runtime. active: bool, + /// The runtime `select_runtime_manifest` resolves `previous_runtime_key` + /// to, which is the runtime `rocm runtimes rollback` selects (and then + /// refuses if it is unusable). rollback_target: bool, + #[serde(serialize_with = "serialize_path_lossy")] install_root: PathBuf, } +/// A path as a JSON string, through `to_string_lossy`. serde's own `Path` +/// impl fails on a path that is not valid UTF-8, which would leave +/// `rocm runtimes list --json` printing nothing for a listing the text form +/// prints (with the same replacement, through `Path::display`). +fn serialize_path_lossy( + path: &std::path::Path, + serializer: S, +) -> Result { + serializer.serialize_str(&path.to_string_lossy()) +} + +/// Whether a runtime carries the compiler toolchain. The text and the JSON +/// print the same word, the one `toolchain_state_text` gives `rocm examine`. +#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)] +#[serde(rename_all = "lowercase")] +enum RuntimeToolchain { + Included, + Excluded, +} + +impl RuntimeToolchain { + const fn from_includes_devel(includes_devel: bool) -> Self { + if includes_devel { + Self::Included + } else { + Self::Excluded + } + } + + const fn as_str(self) -> &'static str { + toolchain_state_text(matches!(self, Self::Included)) + } +} + #[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)] #[serde(rename_all = "kebab-case")] enum RuntimeMode { @@ -723,57 +774,49 @@ pub(crate) fn runtimes_listing( ) -> Result { recover_setup_runtime_registration(paths, config)?; let manifests = therock::load_runtime_manifests(paths)?; + Ok(listing_from_manifests( + config, + manifests, + runtime_registry_dir(paths), + active_runtime_marker_path(paths), + )) +} - // With no `active_runtime_key`, `default_runtime_id` is matched by one rule, - // `default_runtime_id_matches` (ASCII letter case ignored), for both the - // problem and the `active` flag below, so the listing cannot mark a runtime - // active and also report its manifest missing. - let default_runtime_matches = default_runtime_id_matches(config, &manifests); - let (active_problem, single_default_runtime_key) = - if let Some(active_runtime_key) = config.active_runtime_key.as_deref() { - let problem = (!manifests - .iter() - .any(|manifest| manifest.runtime_key == active_runtime_key)) - .then(|| ActiveRuntimeProblem::MissingManifestForKey { - runtime_key: active_runtime_key.to_owned(), - }); - (problem, None) - } else if let Some(default_runtime_id) = config.default_runtime_id.as_deref() { - match default_runtime_matches.as_slice() { - [] => ( - Some(ActiveRuntimeProblem::MissingManifestForId { - runtime_id: default_runtime_id.to_owned(), - }), - None, - ), - [manifest] => (None, Some(manifest.runtime_key.clone())), - matches => ( - Some(ActiveRuntimeProblem::AmbiguousRuntimeId { - runtime_id: default_runtime_id.to_owned(), - runtime_keys: matches - .iter() - .map(|manifest| manifest.runtime_key.clone()) - .collect(), - }), - None, - ), - } - } else { - (None, None) - }; +/// The listing of `manifests`, in the order given, for `config`. Split from +/// the registry read so every configuration can be tested in memory, including +/// keys that differ only in letter case, which one registry folder cannot hold +/// on a case-insensitive filesystem. +/// +/// `active` and `rollback_target` are not decided by rules of the listing's +/// own: they are the runtimes the commands themselves resolve, by the same +/// functions, so the listing marks what those commands act on. +fn listing_from_manifests( + config: &RocmCliConfig, + manifests: Vec, + registry: PathBuf, + marker: PathBuf, +) -> RuntimesListing { + // Compared by position, not by key: keys can differ only in letter case, + // and the resolver's choice between such twins is part of what is listed. + let position = |resolved: &therock::InstalledRuntimeManifest| { + manifests + .iter() + .position(|manifest| std::ptr::eq(manifest, resolved)) + }; + let active_index = current_runtime_manifest(config, &manifests).and_then(position); + // `rocm runtimes rollback` selects `previous_runtime_key` this way; a value + // it refuses (no match, or ambiguous) names no rollback target. + let rollback_index = config + .previous_runtime_key + .as_deref() + .and_then(|selector| select_runtime_manifest(&manifests, selector).ok()) + .and_then(position); + let active_problem = active_runtime_problem(config, &manifests); let runtimes = manifests .into_iter() - .map(|manifest| { - let active = config - .active_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key == manifest.runtime_key) - || single_default_runtime_key.as_deref() == Some(manifest.runtime_key.as_str()); - let rollback_target = config - .previous_runtime_key - .as_deref() - .is_some_and(|runtime_key| runtime_key == manifest.runtime_key); + .enumerate() + .map(|(index, manifest)| { // The manifest check `rocm runtimes activate` applies, so "ready" // here means the runtime passes that check, not that an activation // is sure to succeed (see `RuntimeUsability`). @@ -791,7 +834,7 @@ pub(crate) fn runtimes_listing( // The compiler is opt-in and `rocm update` reinstalls whatever this // says, so an install missing it should not be silent about that. // `rocm examine` reports the same thing for the active runtime. - let toolchain = toolchain_state_text(manifest.includes_devel()); + let toolchain = RuntimeToolchain::from_includes_devel(manifest.includes_devel()); RuntimeListingEntry { runtime_key: manifest.runtime_key, runtime_id: manifest.runtime_id, @@ -801,22 +844,64 @@ pub(crate) fn runtimes_listing( mode, usability, toolchain, - active, - rollback_target, + active: active_index == Some(index), + rollback_target: rollback_index == Some(index), install_root: manifest.install_root, } }) .collect(); - Ok(RuntimesListing { - active_runtime_id: config.default_runtime_id.clone(), + RuntimesListing { + default_runtime_id: config.default_runtime_id.clone(), active_runtime_key: config.active_runtime_key.clone(), previous_runtime_key: config.previous_runtime_key.clone(), - registry: runtime_registry_dir(paths), - marker: active_runtime_marker_path(paths), + registry, + marker, active_problem, runtimes, - }) + } +} + +/// What is wrong with the configured active runtime setting, by the matching +/// `current_runtime_manifest` applies. +/// +/// It reports the configuration, so it can disagree with `active` in exactly +/// one case: an `active_runtime_key` that names no runtime is reported as +/// `MissingManifestForKey` even when the resolver then falls back to +/// `default_runtime_id` and finds one, which is marked active. The commands act +/// on that runtime, so the listing marks it; the key is still dead, so the +/// listing says so. With no `active_runtime_key`, the problem comes from the +/// same `default_runtime_id_matches` the resolver falls back to, so it is set +/// exactly when nothing is active. +fn active_runtime_problem( + config: &RocmCliConfig, + manifests: &[therock::InstalledRuntimeManifest], +) -> Option { + if let Some(runtime_key) = config.active_runtime_key.as_deref() { + // The resolver's key step on its own: the same call with the default + // id it would fall back to taken away. + let mut key_only = config.clone(); + key_only.default_runtime_id = None; + return current_runtime_manifest(&key_only, manifests) + .is_none() + .then(|| ActiveRuntimeProblem::MissingManifestForKey { + runtime_key: runtime_key.to_owned(), + }); + } + let runtime_id = config.default_runtime_id.as_deref()?; + match default_runtime_id_matches(config, manifests).as_slice() { + [] => Some(ActiveRuntimeProblem::MissingManifestForId { + runtime_id: runtime_id.to_owned(), + }), + [_] => None, + matches => Some(ActiveRuntimeProblem::AmbiguousRuntimeId { + runtime_id: runtime_id.to_owned(), + runtime_keys: matches + .iter() + .map(|manifest| manifest.runtime_key.clone()) + .collect(), + }), + } } impl cli_report::JsonOrText for RuntimesListing { @@ -827,7 +912,7 @@ impl cli_report::JsonOrText for RuntimesListing { let _ = writeln!( output, " active_runtime_id: {}", - unset(&self.active_runtime_id) + unset(&self.default_runtime_id) ); let _ = writeln!( output, @@ -884,7 +969,9 @@ impl cli_report::JsonOrText for RuntimesListing { for runtime in &self.runtimes { // Active wins when a runtime is both. `rocm runtimes activate` and // `rollback` never record a runtime as its own rollback target, so - // only a config edited outside the CLI reaches this. + // only a change made outside the CLI reaches this: a hand-edited + // config, or the active runtime's registry entry deleted while the + // default id falls back to the rollback target. let marker = if runtime.active { Some(ACTIVE_RUNTIME_MARKER) } else if runtime.rollback_target { @@ -909,7 +996,7 @@ impl cli_report::JsonOrText for RuntimesListing { runtime.family, runtime.mode.as_str(), status, - runtime.toolchain + runtime.toolchain.as_str() ), ); let _ = writeln!( @@ -1502,7 +1589,7 @@ pub(crate) mod tests { assert_eq!(listing["runtimes"], serde_json::json!([])); for unset in [ - "active_runtime_id", + "default_runtime_id", "active_runtime_key", "previous_runtime_key", "active_problem", @@ -1585,7 +1672,7 @@ pub(crate) mod tests { let _ = fs::remove_dir_all(root); assert_eq!(runtime_keys_flagged(&listing, "active"), ["rt-gfx120x"]); - assert_eq!(listing["active_runtime_id"], "therock-release:gfx120X-all"); + assert_eq!(listing["default_runtime_id"], "therock-release:gfx120X-all"); assert_null_field(&listing, "active_runtime_key"); assert_null_field(&listing, "active_problem"); Ok(()) @@ -1795,6 +1882,607 @@ pub(crate) mod tests { Ok(()) } + // ── State matrix: what the listing marks, for every configuration ── + // + // Built in memory through `listing_from_manifests`, so keys that differ + // only in letter case are listed as they would be on a case-sensitive + // filesystem without writing them to one: on a case-insensitive one the + // second `.json` would overwrite the first. + + /// A registered runtime with just the fields the listing reads. Its + /// install root does not exist, so it is listed `unusable`, which no row + /// below depends on. + fn listed_runtime_manifest( + runtime_key: &str, + runtime_id: &str, + ) -> therock::InstalledRuntimeManifest { + serde_json::from_value(serde_json::json!({ + "runtime_key": runtime_key, + "runtime_id": runtime_id, + "channel": "release", + "format": "wheel", + "family": "gfx120X-all", + "family_source": "test", + "version": "7.13.0", + "install_root": format!("/nonexistent/rocm-list-state/{runtime_key}"), + "selected_artifact_url": "https://example.invalid/therock", + "installed_at_unix_ms": 10, + })) + .expect("a minimal runtime manifest deserializes") + } + + const ID_A: &str = "therock-release:gfx120X-all"; + const ID_B: &str = "therock-release:gfx110X-all"; + + /// Runtimes `rt-a` (id `ID_A`) and `rt-b` (id `ID_B`), in that order. + fn two_distinct_runtimes() -> Vec { + vec![ + listed_runtime_manifest("rt-a", ID_A), + listed_runtime_manifest("rt-b", ID_B), + ] + } + + /// Keys `rt-twin` and `RT-TWIN`, in that order, with distinct ids. + fn case_twin_runtimes() -> Vec { + vec![ + listed_runtime_manifest("rt-twin", ID_A), + listed_runtime_manifest("RT-TWIN", ID_B), + ] + } + + /// One row of the state matrix: a configuration, the runtimes, and what + /// the listing must say about them in both forms. + struct ListingState { + config: RocmCliConfig, + manifests: Vec, + /// The key marked `active` (JSON) and `*` (text). + active: Option<&'static str>, + /// The key flagged `rollback_target` (JSON); marked `-` in the text + /// unless it is also active. + rollback: Option<&'static str>, + /// The JSON `active_problem`. + problem: serde_json::Value, + /// The text's `active_status:` line, without its indentation. + status_line: Option<&'static str>, + } + + fn config_with( + default_runtime_id: Option<&str>, + active_runtime_key: Option<&str>, + previous_runtime_key: Option<&str>, + ) -> RocmCliConfig { + RocmCliConfig { + default_runtime_id: default_runtime_id.map(str::to_owned), + active_runtime_key: active_runtime_key.map(str::to_owned), + previous_runtime_key: previous_runtime_key.map(str::to_owned), + ..RocmCliConfig::default() + } + } + + fn assert_listing_state(state: &ListingState) -> Result<()> { + use cli_report::JsonOrText as _; + let listing = listing_from_manifests( + &state.config, + state.manifests.clone(), + PathBuf::from("registry"), + PathBuf::from("active.json"), + ); + let json = serde_json::to_value(&listing)?; + let text = listing.render_text(); + let context = format!("{json:#}\n{text}"); + + // The listing marks what the commands resolve: `current_runtime_manifest` + // for the active runtime, `select_runtime_manifest` for rollback. + let resolved_active = current_runtime_manifest(&state.config, &state.manifests) + .map(|manifest| manifest.runtime_key.as_str()); + assert_eq!(resolved_active, state.active, "resolver vs row:\n{context}"); + let resolved_rollback = state + .config + .previous_runtime_key + .as_deref() + .and_then(|selector| select_runtime_manifest(&state.manifests, selector).ok()) + .map(|manifest| manifest.runtime_key.as_str()); + assert_eq!( + resolved_rollback, state.rollback, + "resolver vs row:\n{context}" + ); + + let expected_active: Vec = state.active.iter().map(|k| (*k).to_owned()).collect(); + let expected_rollback: Vec = + state.rollback.iter().map(|k| (*k).to_owned()).collect(); + assert_eq!( + runtime_keys_flagged(&json, "active"), + expected_active, + "{context}" + ); + assert_eq!( + runtime_keys_flagged(&json, "rollback_target"), + expected_rollback, + "{context}" + ); + assert_eq!(json["active_problem"], state.problem, "{context}"); + assert_eq!( + runtime_keys_marked(&text, ACTIVE_RUNTIME_MARKER), + expected_active, + "{context}" + ); + let rollback_only: Vec = expected_rollback + .into_iter() + .filter(|key| Some(key.as_str()) != state.active) + .collect(); + assert_eq!( + runtime_keys_marked(&text, ROLLBACK_RUNTIME_MARKER), + rollback_only, + "{context}" + ); + let status_lines: Vec<&str> = text + .lines() + .map(str::trim_start) + .filter(|line| line.starts_with("active_status:")) + .collect(); + assert_eq!( + status_lines, + state.status_line.into_iter().collect::>(), + "{context}" + ); + Ok(()) + } + + fn state_no_config() -> ListingState { + ListingState { + config: RocmCliConfig::default(), + manifests: two_distinct_runtimes(), + active: None, + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_key_exact() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), None), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// The default id names the other runtime, so the key alone decides. + fn state_key_in_other_case() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("RT-A"), None), + manifests: two_distinct_runtimes(), + active: Some("rt-a"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// The one documented case where `active_problem` is set beside an + /// `active` runtime: the key is dead, the default id still resolves. + fn state_stale_key_default_resolves() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-gone"), None), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: None, + problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), + status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), + } + } + + fn state_stale_key_default_missing() -> ListingState { + ListingState { + config: config_with(Some("therock-release:gfx90a"), Some("rt-gone"), None), + manifests: two_distinct_runtimes(), + active: None, + rollback: None, + problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), + status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), + } + } + + fn state_stale_key_default_ambiguous() -> ListingState { + ListingState { + config: config_with(Some(ID_A), Some("rt-gone"), None), + manifests: vec![ + listed_runtime_manifest("rt-a", ID_A), + listed_runtime_manifest("rt-a2", ID_A), + ], + active: None, + rollback: None, + problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), + status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), + } + } + + fn state_default_matches_none() -> ListingState { + ListingState { + config: config_with(Some("therock-release:gfx90a"), None, None), + manifests: two_distinct_runtimes(), + active: None, + rollback: None, + problem: serde_json::json!({ + "kind": "missing_manifest_for_id", + "runtime_id": "therock-release:gfx90a" + }), + status_line: Some( + "active_status: missing manifest for active_runtime_id=therock-release:gfx90a", + ), + } + } + + fn state_default_matches_one() -> ListingState { + ListingState { + config: config_with(Some(ID_B), None, None), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_default_matches_one_in_other_case() -> ListingState { + ListingState { + config: config_with(Some("THEROCK-RELEASE:GFX110X-ALL"), None, None), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_default_matches_two() -> ListingState { + ListingState { + config: config_with(Some(ID_A), None, None), + manifests: vec![ + listed_runtime_manifest("rt-a", ID_A), + listed_runtime_manifest("rt-a2", ID_A), + ], + active: None, + rollback: None, + problem: serde_json::json!({ + "kind": "ambiguous_runtime_id", + "runtime_id": ID_A, + "runtime_keys": ["rt-a", "rt-a2"] + }), + status_line: Some( + "active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ + activate one runtime_key: rt-a, rt-a2", + ), + } + } + + /// Ids differing only in case are two matches, even though one equals the + /// default exactly. + fn state_default_matches_two_differing_in_case() -> ListingState { + ListingState { + config: config_with(Some(ID_A), None, None), + manifests: vec![ + listed_runtime_manifest("rt-a", ID_A), + listed_runtime_manifest("rt-a-lower", "therock-release:gfx120x-all"), + ], + active: None, + rollback: None, + problem: serde_json::json!({ + "kind": "ambiguous_runtime_id", + "runtime_id": ID_A, + "runtime_keys": ["rt-a", "rt-a-lower"] + }), + status_line: Some( + "active_status: ambiguous runtime_id=therock-release:gfx120X-all; \ + activate one runtime_key: rt-a, rt-a-lower", + ), + } + } + + /// Case twins: the resolver takes the first key matching in list order, + /// even when a later one equals the active key exactly, and the listing + /// marks that first one, because that is what the commands act on. + fn state_case_twins_key_names_the_second() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("RT-TWIN"), None), + manifests: case_twin_runtimes(), + active: Some("rt-twin"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_case_twins_key_names_the_first() -> ListingState { + ListingState { + config: config_with(Some(ID_A), Some("rt-twin"), None), + manifests: case_twin_runtimes(), + active: Some("rt-twin"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_previous_key_exact() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), Some("rt-a")), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: Some("rt-a"), + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_previous_key_in_other_case() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), Some("RT-A")), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: Some("rt-a"), + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_previous_key_is_a_runtime_id() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), Some(ID_A)), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: Some("rt-a"), + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_previous_key_with_whitespace() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), Some(" rt-a\n")), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: Some("rt-a"), + problem: serde_json::Value::Null, + status_line: None, + } + } + + fn state_previous_key_missing() -> ListingState { + ListingState { + config: config_with(Some(ID_B), Some("rt-b"), Some("rt-gone")), + manifests: two_distinct_runtimes(), + active: Some("rt-b"), + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// Matches both twins only by letter case: rollback refuses it as + /// ambiguous, so nothing is the rollback target. + fn state_previous_key_ambiguous_case_twins() -> ListingState { + ListingState { + config: config_with(None, None, Some("Rt-Twin")), + manifests: case_twin_runtimes(), + active: None, + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// A runtime id two runtimes share: rollback refuses it as ambiguous. + fn state_previous_key_ambiguous_runtime_id() -> ListingState { + ListingState { + config: config_with(None, None, Some(ID_A)), + manifests: vec![ + listed_runtime_manifest("rt-a", ID_A), + listed_runtime_manifest("rt-a2", ID_A), + ], + active: None, + rollback: None, + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// Rollback takes an exact key over its case twin. + fn state_previous_key_names_one_case_twin_exactly() -> ListingState { + ListingState { + config: config_with(None, None, Some("RT-TWIN")), + manifests: case_twin_runtimes(), + active: None, + rollback: Some("RT-TWIN"), + problem: serde_json::Value::Null, + status_line: None, + } + } + + /// The active runtime's registry entry was deleted and the default id it + /// shared with the rollback target now resolves that one: it is both, and + /// the text marks it `*`. + fn state_stale_key_falls_back_to_the_rollback_target() -> ListingState { + ListingState { + config: config_with(Some(ID_A), Some("rt-gone"), Some("rt-a")), + manifests: two_distinct_runtimes(), + active: Some("rt-a"), + rollback: Some("rt-a"), + problem: serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": "rt-gone"}), + status_line: Some("active_status: missing manifest for active_runtime_key=rt-gone"), + } + } + + #[test] + fn listing_state_no_config() -> Result<()> { + assert_listing_state(&state_no_config()) + } + + #[test] + fn listing_state_key_exact() -> Result<()> { + assert_listing_state(&state_key_exact()) + } + + #[test] + fn listing_state_key_in_other_case() -> Result<()> { + assert_listing_state(&state_key_in_other_case()) + } + + #[test] + fn listing_state_stale_key_default_resolves() -> Result<()> { + assert_listing_state(&state_stale_key_default_resolves()) + } + + #[test] + fn listing_state_stale_key_default_missing() -> Result<()> { + assert_listing_state(&state_stale_key_default_missing()) + } + + #[test] + fn listing_state_stale_key_default_ambiguous() -> Result<()> { + assert_listing_state(&state_stale_key_default_ambiguous()) + } + + #[test] + fn listing_state_default_matches_none() -> Result<()> { + assert_listing_state(&state_default_matches_none()) + } + + #[test] + fn listing_state_default_matches_one() -> Result<()> { + assert_listing_state(&state_default_matches_one()) + } + + #[test] + fn listing_state_default_matches_one_in_other_case() -> Result<()> { + assert_listing_state(&state_default_matches_one_in_other_case()) + } + + #[test] + fn listing_state_default_matches_two() -> Result<()> { + assert_listing_state(&state_default_matches_two()) + } + + #[test] + fn listing_state_default_matches_two_differing_in_case() -> Result<()> { + assert_listing_state(&state_default_matches_two_differing_in_case()) + } + + #[test] + fn listing_state_case_twins_key_names_the_second() -> Result<()> { + assert_listing_state(&state_case_twins_key_names_the_second()) + } + + #[test] + fn listing_state_case_twins_key_names_the_first() -> Result<()> { + assert_listing_state(&state_case_twins_key_names_the_first()) + } + + #[test] + fn listing_state_previous_key_exact() -> Result<()> { + assert_listing_state(&state_previous_key_exact()) + } + + #[test] + fn listing_state_previous_key_in_other_case() -> Result<()> { + assert_listing_state(&state_previous_key_in_other_case()) + } + + #[test] + fn listing_state_previous_key_is_a_runtime_id() -> Result<()> { + assert_listing_state(&state_previous_key_is_a_runtime_id()) + } + + #[test] + fn listing_state_previous_key_with_whitespace() -> Result<()> { + assert_listing_state(&state_previous_key_with_whitespace()) + } + + #[test] + fn listing_state_previous_key_missing() -> Result<()> { + assert_listing_state(&state_previous_key_missing()) + } + + #[test] + fn listing_state_previous_key_ambiguous_case_twins() -> Result<()> { + assert_listing_state(&state_previous_key_ambiguous_case_twins()) + } + + #[test] + fn listing_state_previous_key_ambiguous_runtime_id() -> Result<()> { + assert_listing_state(&state_previous_key_ambiguous_runtime_id()) + } + + #[test] + fn listing_state_previous_key_names_one_case_twin_exactly() -> Result<()> { + assert_listing_state(&state_previous_key_names_one_case_twin_exactly()) + } + + #[test] + fn listing_state_stale_key_falls_back_to_the_rollback_target() -> Result<()> { + assert_listing_state(&state_stale_key_falls_back_to_the_rollback_target()) + } + + /// A data dir whose path is not valid UTF-8 still lists as JSON: the + /// paths are written lossily, as the text form writes them, instead of + /// failing serialization and leaving stdout empty. + #[cfg(unix)] + #[test] + fn runtimes_list_json_writes_a_non_utf8_path_lossily() -> Result<()> { + use std::os::unix::ffi::OsStrExt as _; + let data_dir = PathBuf::from(std::ffi::OsStr::from_bytes(b"/data-\xff")); + let mut runtime = listed_runtime_manifest("rt-a", ID_A); + runtime.install_root = data_dir.join("rt-a"); + let listing = listing_from_manifests( + &RocmCliConfig::default(), + vec![runtime], + data_dir.join("registry"), + data_dir.join("active.json"), + ); + let json = serde_json::to_value(&listing)?; + assert_eq!(json["registry"], "/data-\u{fffd}/registry", "{json:#}"); + assert_eq!(json["marker"], "/data-\u{fffd}/active.json", "{json:#}"); + assert_eq!( + listed_runtime(&json, "rt-a")["install_root"], + "/data-\u{fffd}/rt-a", + "{json:#}" + ); + Ok(()) + } + + /// The text prints `toolchain=` from `RuntimeToolchain::as_str`, which is + /// `toolchain_state_text`, the word `rocm examine` prints; the JSON prints + /// the serde `lowercase` rename. Both are documented as `included` and + /// `excluded`, so a change to either word fails here instead of silently + /// changing the JSON. As for the mode test below, a new variant must be + /// added to `all` as well as to the match. + #[test] + fn runtime_toolchain_text_and_json_words_agree_for_every_variant() -> Result<()> { + let all = [RuntimeToolchain::Included, RuntimeToolchain::Excluded]; + for toolchain in all { + match toolchain { + RuntimeToolchain::Included | RuntimeToolchain::Excluded => {} + } + assert_eq!( + serde_json::to_value(toolchain)?, + toolchain.as_str(), + "{toolchain:?}" + ); + } + assert_eq!( + RuntimeToolchain::from_includes_devel(true).as_str(), + "included" + ); + assert_eq!( + RuntimeToolchain::from_includes_devel(false).as_str(), + "excluded" + ); + Ok(()) + } + /// The text prints `mode=` from `RuntimeMode::as_str` and the JSON from the /// serde `kebab-case` rename; both are documented as the same words, so /// every variant must agree. The exhaustive `match` turns a new variant @@ -1859,7 +2547,7 @@ pub(crate) mod tests { key_set(&listing), std::collections::BTreeSet::from( [ - "active_runtime_id", + "default_runtime_id", "active_runtime_key", "previous_runtime_key", "registry", diff --git a/docs/architecture.md b/docs/architecture.md index 3811a8ae9d..c195ce04f0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -859,7 +859,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, and a check that the text markers and JSON flags agree. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, and a check that the text markers and JSON flags agree. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | | [`tests/e2e/service_stop_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_stop_steps.rs) | Steps for [`service_stop.feature`](../tests/e2e-cucumber/features/service_stop.feature) and [`engine_ipc.feature`](../tests/e2e-cucumber/features/engine_ipc.feature): `rocm services stop` and the daemon's `stop_server` tool against a planted service record, and how the daemon reads what an engine child prints, with a stand-in `rocm` staged beside a copy of `rocmd`; and the confirmed stop against a real recorded process, a recorded PID that now belongs to a different process, and a parent that has started a child. | flat | diff --git a/docs/json-output.md b/docs/json-output.md index c46b7353fb..46eb20cbe2 100644 --- a/docs/json-output.md +++ b/docs/json-output.md @@ -19,12 +19,15 @@ commands that do not have it yet. print is listed below as unsupported rather than given a `--json` that mixes the two. - **Errors are not JSON today.** A command that fails with `--json` prints its - error to stderr, prints nothing on stdout, and exits non-zero (1, unless the - command documents its own code, as `rocm fix` does). A script tells success - from failure by the exit code, not by parsing an error document. A JSON error - shape belongs to the shared envelope below. The one refusal printed as JSON - today is `rocm diagnose --report --json` declining to prepare a report: that - is the command working, so it exits 0 and prints `refusal_envelope` from + error to stderr, prints nothing on stdout, and exits 1, unless the command + documents its own code, as `rocm fix` does. Command lines the argument parser + rejects (an unknown flag, such as `--json` on a command without one, or a + missing argument) exit 2 with a usage message on stderr, before the command + runs. A script tells success from failure by the exit code, not by parsing an + error document. A JSON error shape belongs to the shared envelope below. The + one refusal printed as JSON today is `rocm diagnose --report --json` + declining to prepare a report: that is the command working, so it exits 0 + and prints `refusal_envelope` from [report.rs](../crates/rocm-core/src/report.rs) (`schema`, `refused`, `explanation`, `architecture_matrix`). - **Documented fields do not change silently.** A field may be added. Renaming @@ -56,7 +59,7 @@ commands that do not have it yet. | `rocm update` | supported for the check; one compact JSON line, not pretty, and refused with `--apply` and `--dry-run` | supported; the compact form is a known difference from the others | `update-02`, `update-03` | | `rocm storage report` | supported; pretty JSON through `JsonOrText` | supported | `json_or_text_impl_renders_the_report_and_serializes_it` | | `rocm services list` | supported; pretty JSON. `rocm remote` reads it back over its control channel | supported | `services_json_round_trips_and_applies_the_same_liveness_filter_as_the_table`; exercised indirectly by `remote-15` (`@requires-docker`), whose `rocm remote` reads it back | -| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-19` to `runtime-lifecycle-23` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | +| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-19` to `runtime-lifecycle-25` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | | `rocm runtimes activate`, `rollback`, `uninstall`, `import`, `adopt` | none | follow-up: they change state, so they need the envelope's result and refusal shapes | — | | `rocm services logs` | none | intentionally unsupported: streamed text, and `-f` never ends | — | | `rocm services stop`, `restart`, `remove`, `prune` | none | follow-up: needs the envelope, including the refusal path | — | @@ -75,11 +78,11 @@ The same listing as the text form, as one object: | Field | Value | |---|---| -| `active_runtime_id` | the configured default runtime id as written in the config, or `null`. Not necessarily the active runtime's `runtime_id`: `active_runtime_key` takes precedence when set, and the id may differ from its runtime's in letter case or match no runtime at all. Read each runtime's `active` flag to see which one is in use | +| `default_runtime_id` | the configured default runtime id as written in the config, or `null`. The text form labels it `active_runtime_id:`. Not necessarily the active runtime's `runtime_id`: an `active_runtime_key` that names a runtime takes precedence, and the id may differ from its runtime's in letter case or match no runtime at all. Read each runtime's `active` flag to see which one is in use | | `active_runtime_key` | the configured active runtime key, or `null` | -| `previous_runtime_key` | the rollback target's key, or `null` | +| `previous_runtime_key` | the configured rollback key, or `null` | | `registry`, `marker` | paths of the runtime registry folder and the active-runtime marker | -| `active_problem` | `null`, or why no runtime is active (matched as described under the known limitation below): `{"kind": "missing_manifest_for_key", "runtime_key"}`, `{"kind": "missing_manifest_for_id", "runtime_id"}`, or `{"kind": "ambiguous_runtime_id", "runtime_id", "runtime_keys": [...]}` | +| `active_problem` | `null`, or what is wrong with the configured active runtime, as described under [which runtimes are marked](#which-runtimes-are-marked): `{"kind": "missing_manifest_for_key", "runtime_key"}`, `{"kind": "missing_manifest_for_id", "runtime_id"}`, or `{"kind": "ambiguous_runtime_id", "runtime_id", "runtime_keys": [...]}` | | `runtimes` | one object per registered runtime, newest install first, ties broken by `runtime_key` | Each runtime carries `runtime_key`, `runtime_id`, `version` (as recorded; the @@ -88,65 +91,88 @@ text adds the build date), `format`, `family`, `mode` (`managed` or that activation applies, `unusable` when it fails it; `ready` does not promise that an activation succeeds), `unusable_reason` (`null` when ready, otherwise why the runtime fails that check: text for a person, not a code to match on), -`toolchain` (`included` or `excluded`), `active`, +`toolchain` (`included` or `excluded`, the words `rocm examine` uses), `active`, `rollback_target` and `install_root`. `active` and `rollback_target` are the facts the text marks with `*` and `-`; a runtime that is both is shown as `*` in the text. The text's next-step hint for an empty registry is not part of the JSON. -### Known limitation: the listing's matching rules - -`rocm runtimes list` decides which runtime is active, which is the rollback -target and what `active_problem` says with rules of its own, which are not all -the ones `rocm examine`, `rocm runtimes activate` and `rocm runtimes rollback` -resolve with. Today: - -- When `active_runtime_key` is set, `active` marks the runtime whose key - equals it exactly, and `active_problem` is `missing_manifest_for_key` when - no runtime's key equals it exactly. `default_runtime_id` is then not - consulted. -- When no `active_runtime_key` is set, `default_runtime_id` is matched against - each runtime's id with ASCII letter case ignored, by one rule for both - fields: exactly one match is marked `active` with `active_problem` `null`; no - match gives `missing_manifest_for_id`; several give `ambiguous_runtime_id` - and nothing active. `rocm config set-default-runtime` reaches this state: it - stores the id as typed, clears `active_runtime_key` and - `previous_runtime_key`, and tries to remove the active-runtime marker file - (best effort: a failed removal is ignored). -- `rollback_target` marks the runtime whose key equals `previous_runtime_key` - exactly. - -The commands acting on the active runtime also accept an `active_runtime_key` -that differs from a runtime's only in letter case, and fall back to -`default_runtime_id` when `active_runtime_key` names no runtime. -`rocm runtimes rollback` also ignores whitespace around `previous_runtime_key` -and accepts one that differs from a runtime's key in letter case or names a -runtime by its id. For the active runtime, the commands take the first -runtime in list order whose key matches `active_runtime_key` ignoring case, -even when a later one has that key exactly; rollback tries an exact match -first. - -The CLI records the active and rollback keys exactly as the runtimes have -them, so most of these differences need a change made outside the CLI: a key -edited by hand in the config shows nothing active in the listing, or no -rollback target; and if the active runtime's registry entry is deleted while -exactly one other registered runtime has the same id as `default_runtime_id` -(activation records the active runtime's id there), the commands fall back to -that runtime while the listing reports `missing_manifest_for_key`. One -difference is reachable from the CLI alone, on a case-sensitive filesystem: -`rocm runtimes import` and `rocm runtimes adopt --runtime-key` store keys as -given, so two runtimes can have keys that differ only in letter case. When the -one activated by its exact key is not the first of the two in list order, the -listing marks it active while the commands act on the other. Each registry -entry is a file named `.json`, so on a case-insensitive filesystem (the -default on Windows volumes, and on drvfs mounts under WSL) the second key names -the first one's file: the command refuses it, or with `--replace` overwrites -the first runtime's entry, and this state cannot occur. - -`active` and `rollback_target` mean what the rules above say, and that meaning -is part of the documented shape. Changing those rules, for example to match the -resolution `rocm examine` uses, would change what the two flags report for the -same configuration, so it is a contract change under the versioning rule -above, not an additive one. +`registry`, `marker` and `install_root` are strings. A path that is not valid +UTF-8 is written with each invalid sequence replaced by U+FFFD, as the text +form prints it, so such a path cannot be passed back to the filesystem from the +JSON as it stands. + +### Which runtimes are marked + +`active` marks the runtime that `rocm examine`, `rocm runtimes activate`, +`rocm runtimes rollback`, `rocm runtimes uninstall` and `rocm update` treat as +the active one: the listing asks the resolver they use +(`current_runtime_manifest` in +[runtime_registry.rs](../apps/rocm/src/runtime_registry.rs)) rather than +applying rules of its own. That resolver takes the first runtime in list order +whose key matches `active_runtime_key` with ASCII letter case ignored; when +`active_runtime_key` is unset or names no runtime, it takes the one runtime +whose id matches `default_runtime_id`, letter case ignored, and nothing when +that matches none or several. + +`rollback_target` marks the runtime `rocm runtimes rollback` selects: +`previous_runtime_key` resolved the way rollback resolves it +(`select_runtime_manifest`, same file), which ignores surrounding whitespace, +takes an exact key first, then the one key differing only in letter case, then +the one runtime whose id matches. When that selection fails (the value names +nothing, or matches several runtimes), no runtime is the rollback target. A +selected runtime whose `status` is `unusable` is still marked; rollback then +refuses it at the manifest check. + +`active_problem` reports the configuration, by the same matching: + +- `missing_manifest_for_key` when `active_runtime_key` is set and no runtime's + key matches it, letter case ignored. This is the one case where a problem is + reported beside an `active` runtime: when `default_runtime_id` still resolves + one runtime, the commands fall back to it and the listing marks it active, + while `active_problem` still says the configured key names nothing. This + happens when the active runtime's registry entry is deleted outside the CLI + while another registered runtime has the same id (activation records the + active runtime's id as `default_runtime_id`, and installs of one channel and + family share an id). +- With no `active_runtime_key`: `missing_manifest_for_id` when + `default_runtime_id` matches no runtime's id, `ambiguous_runtime_id` when it + matches several (ids differing only in letter case count as several), and + `null` when it matches one, which is then the active runtime. `rocm config + set-default-runtime` reaches this state: it stores the id as typed, clears + `active_runtime_key` and `previous_runtime_key`, and tries to remove the + active-runtime marker file (best effort: a failed removal is ignored). + +Two runtimes can have keys that differ only in letter case on a +case-sensitive filesystem, since `rocm runtimes import` and +`rocm runtimes adopt --runtime-key` store keys as given. For such a pair the +resolver takes the first in list order even when `active_runtime_key` equals +the other exactly, and the listing marks that first one, because it is the one +those commands act on. Each registry entry is a file named `.json`, so on +a case-insensitive filesystem (the default on Windows volumes, and on drvfs +mounts under WSL) the second key names the first one's file: the command +refuses it, or with `--replace` overwrites the first runtime's entry, and this +state cannot occur. + +Not every surface resolves the active runtime this way. Known differences: + +- The runtime manager in `rocm dash` matches exactly: `active_runtime_key` + equal to a runtime's key, or with no `active_runtime_key` the single runtime + whose id equals `default_runtime_id`, and `previous_runtime_key` equal to a + runtime's key. It shows nothing active where the listing marks a runtime + through letter case or through the default-id fallback after a dead key, + shows no rollback target for a `previous_runtime_key` in other letter case, + with surrounding whitespace or given as a runtime id. Of two keys differing + only in letter case it marks the one equal to `active_runtime_key`, where the + listing marks the first in list order, and of two ids differing only in case + it marks the one equal to `default_runtime_id`, where the listing reports + `ambiguous_runtime_id`. +- `rocm setup status` looks `active_runtime_key` up ignoring letter case but + does not fall back to `default_runtime_id`. +- `rocm engines install` without `--runtime-id`, for an engine that runs on the + ROCm runtime, resolves `active_runtime_key` (or, when it is unset, + `default_runtime_id`) the way rollback resolves a key: a dead key fails the + install instead of falling back, and a key matching case twins only by letter + case is refused as ambiguous. The shape is additive-only: fields may be added, none will be renamed or removed without a versioned transition. It carries no version field yet; one diff --git a/docs/manual-testing.md b/docs/manual-testing.md index ce66d89c54..50f058343b 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -125,6 +125,8 @@ Expected result: a banner, progress or hint line, reached stdout. - The runtime the text form marks `*` has `"active": true`, and it is the only one; the runtime marked `-`, if any, has `"rollback_target": true`. +- The runtime marked active is the one `rocm examine` reports: its + `install_root` is the `active_runtime_root` that `rocm examine` prints. Optional: an unreadable settings file. Copy `config.json` from the config directory aside, cut the original off part-way through, and run `rocm version` diff --git a/docs/testing.md b/docs/testing.md index c98ad7982b..51a154c268 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1816,29 +1816,51 @@ plants five runtimes with one install time in reverse key order beside older and newer ones, and `registry_sort_is_newest_install_first_then_by_key` tests the sort on its own. -The listing's matching rules, including how it uses `default_runtime_id` -and where it differs from what `rocm examine` and `rocm runtimes -activate`/`rollback` resolve, are in -[json-output.md](json-output.md#known-limitation-the-listings-matching-rules). -`rocm config set-default-runtime` reaches the state where only -`default_runtime_id` is set. +Which runtimes the listing marks `active` and `rollback_target`, and when it +reports `active_problem`, are in +[json-output.md](json-output.md#which-runtimes-are-marked): the listing asks +the resolver `rocm examine`, `rocm runtimes activate`/`rollback`, +`rocm runtimes uninstall` and `rocm update` use, and the surfaces that still +resolve differently are listed there. `@id:runtime-lifecycle-list-default-id-in-other-letter-case` -(`runtime-lifecycle-23`) sets the first runtime's id in upper case and checks -that the JSON marks that runtime active with `active_problem` `null`, and that -the text marks it `*` with no `active_status:` line. The other branches of that -path are covered by unit tests: -`runtimes_list_json_marks_the_one_runtime_matching_the_default_id_active` -(an exact single match), -`runtimes_list_matches_a_default_id_differing_only_in_case_with_one_rule`, -`runtimes_list_json_reports_a_default_id_with_no_manifest` -(`missing_manifest_for_id`), -`runtimes_list_json_reports_a_default_id_matching_two_runtimes_as_ambiguous` -and `runtimes_list_reports_a_default_id_matching_ids_differing_only_in_case_as_ambiguous` -(`ambiguous_runtime_id`): - -```bash -cargo xtask e2e -- -n "runtime-lifecycle-(07|19|20|21|22|23) " +(`runtime-lifecycle-23`) sets the first runtime's id in upper case through +`rocm config set-default-runtime` and checks that the JSON marks that runtime +active with `active_problem` `null`, and that the text marks it `*` with no +`active_status:` line. +`@id:runtime-lifecycle-list-active-key-in-other-letter-case` +(`runtime-lifecycle-24`) edits the config's active runtime key to the first +runtime's key in upper case while the default id still names the second, and +checks that both forms mark the first runtime active with no problem and that +`rocm examine --json` reports the first runtime's folder as +`active_runtime_root`. +`@id:runtime-lifecycle-list-dead-active-key-falls-back-to-default` +(`runtime-lifecycle-25`) edits the key to one no runtime has while the default +id still names the second runtime, and checks that both forms mark the second +runtime active, that the JSON reports `missing_manifest_for_key` and the text +the matching `active_status:` line, and that `rocm examine --json` reports the +second runtime's folder. +The `listing_state_*` unit tests in +[runtimes_cmd.rs](../apps/rocm/src/runtimes_cmd.rs) list a state matrix in +memory, one test per row (no config; an active key exact, in other case, or naming nothing with +the default id resolving one, none or several; no active key with the default +id matching none, one, one in other case, two, or two differing in case; keys +differing only in case; a previous key exact, in other case, given as a runtime +id, with whitespace, naming nothing, ambiguous, or naming one of two case twins +exactly; and a dead key falling back to the rollback target). Each checks the +JSON flags, `active_problem`, the text markers and the `active_status:` line, +and that `active` and `rollback_target` are what `current_runtime_manifest` and +`select_runtime_manifest` resolve. Keys differing only in case are built in +memory, so these tests hold on a case-insensitive filesystem too. +`runtimes_list_json_writes_a_non_utf8_path_lossily` (Unix only) lists a data +folder whose path is not valid UTF-8, and +`runtime_toolchain_text_and_json_words_agree_for_every_variant` holds the +`toolchain` words in the text and the JSON together: + +```bash +cargo xtask e2e -- -n "runtime-lifecycle-(07|19|20|21|22|23|24|25) " cargo test -p rocm --bin rocm runtimes_list +cargo test -p rocm --bin rocm listing_state +cargo test -p rocm --bin rocm runtime_toolchain_text_and_json_words_agree_for_every_variant cargo test -p rocm --bin rocm registry_sort_is_newest_install_first_then_by_key ``` diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index ec303ecfb4..6e207346b6 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -320,5 +320,37 @@ Feature: Runtime lifecycle state machine When the user sets the default runtime to the first runtime's id in other letter case And the user lists the registered runtimes as JSON Then the output is a single JSON document and nothing else + And the JSON shows the default runtime as typed and no active runtime key And the JSON marks only the first runtime active and reports no problem And the text listing marks the first runtime active with no active_status line + + # A config edited by hand can name the active runtime in other letter case. + # The commands that act on the active runtime match its key ignoring case, so + # the list has to mark the runtime they act on, and `rocm examine` has to + # report that same runtime. The default runtime still names the second + # runtime, so a list that fell back to it would mark the wrong one. + @id:runtime-lifecycle-list-active-key-in-other-letter-case + Scenario: runtime-lifecycle-24 - An active runtime named in other letter case is listed as the one examine reports + Given two registered runtimes with the second active after the first + And the configuration names the first runtime as active in other letter case + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON marks only the first runtime active and reports no problem + And the text listing marks the first runtime active with no active_status line + And examine reports the first runtime as the active one + + # The configured active runtime is not registered, but the default runtime + # still names a registered one and the commands fall back to it. The list + # marks that runtime active, as `rocm examine` reports it, and still says the + # configured active runtime is missing, in both forms. + @id:runtime-lifecycle-list-dead-active-key-falls-back-to-default + Scenario: runtime-lifecycle-25 - A missing active runtime is reported while the default runtime the commands use is listed active + Given two registered runtimes with the second active after the first + And the configuration names an unregistered runtime as active + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON marks only the second runtime active + And the JSON reports that the active runtime key has no registered runtime + And the text listing marks the same runtimes as the JSON + And the text listing says the active runtime key has no registered runtime + And examine reports the second runtime as the active one diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 2c9dd7e179..d0e8edeaf8 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -246,21 +246,42 @@ fn ids_listed_under<'a>(report: &'a str, section: &str) -> Vec<&'a str> { /// anyway: it is written first, so it is the half that would be left naming the /// new runtime if the restore did not run. fn config_active_runtime_key(world: &E2eWorld) -> Option { - let config_dir = world + read_config(world) + .get("active_runtime_key") + .and_then(serde_json::Value::as_str) + .map(str::to_owned) +} + +/// The isolated `config.json`. +fn config_path(world: &E2eWorld) -> PathBuf { + world .isolate_env() .into_iter() .find(|(key, _)| *key == "ROCM_CLI_CONFIG_DIR") .map(|(_, value)| PathBuf::from(value)) - .expect("isolate_env did not set ROCM_CLI_CONFIG_DIR"); - let config = config_dir.join("config.json"); + .expect("isolate_env did not set ROCM_CLI_CONFIG_DIR") + .join("config.json") +} + +fn read_config(world: &E2eWorld) -> serde_json::Value { + let config = config_path(world); let text = std::fs::read_to_string(&config) .unwrap_or_else(|error| panic!("failed to read {}: {error}", config.display())); - let value: serde_json::Value = serde_json::from_str(&text) - .unwrap_or_else(|error| panic!("{} is not valid JSON: {error}", config.display())); - value - .get("active_runtime_key") - .and_then(serde_json::Value::as_str) - .map(str::to_owned) + serde_json::from_str(&text) + .unwrap_or_else(|error| panic!("{} is not valid JSON: {error}", config.display())) +} + +/// Edit the config the way a person editing the file by hand would: set +/// `active_runtime_key` and leave every other value as the CLI wrote it. +fn set_config_active_runtime_key(world: &E2eWorld, runtime_key: &str) { + let mut config = read_config(world); + config["active_runtime_key"] = serde_json::Value::from(runtime_key); + let path = config_path(world); + std::fs::write( + &path, + serde_json::to_string_pretty(&config).expect("config serializes"), + ) + .unwrap_or_else(|error| panic!("failed to write {}: {error}", path.display())); } /// The runtime key recorded in the isolated active-runtime marker @@ -360,6 +381,25 @@ async fn second_runtime_manifest_deleted(world: &mut E2eWorld) { .expect("failed to delete the second runtime's manifest"); } +/// A key no runtime is registered under: what the config holds after the +/// active runtime's registry entry goes without the CLI noticing. +const UNREGISTERED_KEY: &str = "release-tarball-gfx90a"; + +#[given("the configuration names the first runtime as active in other letter case")] +async fn config_names_first_in_other_case(world: &mut E2eWorld) { + let other_case = FIRST_KEY.to_ascii_uppercase(); + assert_ne!( + other_case, FIRST_KEY, + "the edit must change the letter case" + ); + set_config_active_runtime_key(world, &other_case); +} + +#[given("the configuration names an unregistered runtime as active")] +async fn config_names_unregistered_runtime(world: &mut E2eWorld) { + set_config_active_runtime_key(world, UNREGISTERED_KEY); +} + #[given("two registered runtimes whose keys differ only in letter case")] async fn two_case_twin_runtimes(world: &mut E2eWorld) { // Distinct families only so each twin gets its own install root. @@ -1100,7 +1140,7 @@ async fn json_lists_nothing(world: &mut E2eWorld) { let listing = listing_json(world); assert_eq!(listing["runtimes"], serde_json::json!([]), "{listing:#}"); for unset in [ - "active_runtime_id", + "default_runtime_id", "active_runtime_key", "previous_runtime_key", "active_problem", @@ -1148,16 +1188,20 @@ async fn text_marks_match_json(world: &mut E2eWorld) { assert_eq!(text_rows_marked(&text, "-"), rollback_only, "{text}"); } -#[then("the JSON marks only the first runtime active and reports no problem")] -async fn json_marks_first_active_without_problem(world: &mut E2eWorld) { +#[then("the JSON shows the default runtime as typed and no active runtime key")] +async fn json_shows_default_as_typed(world: &mut E2eWorld) { let listing = listing_json(world); - // The state under test: the id as typed, and no active key. assert_eq!( - listing["active_runtime_id"], + listing["default_runtime_id"], first_runtime_id_in_other_case(), "{listing:#}" ); assert_null_field(&listing, "active_runtime_key"); +} + +#[then("the JSON marks only the first runtime active and reports no problem")] +async fn json_marks_first_active_without_problem(world: &mut E2eWorld) { + let listing = listing_json(world); assert_eq!( listed_keys_with(&listing, "active"), [FIRST_KEY], @@ -1166,6 +1210,64 @@ async fn json_marks_first_active_without_problem(world: &mut E2eWorld) { assert_null_field(&listing, "active_problem"); } +#[then("the JSON marks only the second runtime active")] +async fn json_marks_only_second_active(world: &mut E2eWorld) { + let listing = listing_json(world); + assert_eq!( + listed_keys_with(&listing, "active"), + [SECOND_KEY], + "{listing:#}" + ); +} + +/// The install root `rocm examine --json` reports (`summary.active_runtime_root`) +/// for the active runtime, which comes from the resolver the commands use. +fn examined_active_runtime_root(world: &E2eWorld) -> PathBuf { + let (stdout, stderr, rc) = + crate::run_rocm(world, &["examine", "--framework", "skip", "--json"]); + assert_eq!(rc, 0, "examine failed:\n{stdout}\n{stderr}"); + let examined: serde_json::Value = serde_json::from_str(&stdout) + .unwrap_or_else(|error| panic!("examine --json is not JSON ({error}):\n{stdout}")); + let root = examined["summary"]["active_runtime_root"] + .as_str() + .unwrap_or_else(|| panic!("examine reports no active runtime root:\n{examined:#}")); + PathBuf::from(root) +} + +#[then("examine reports the first runtime as the active one")] +async fn examine_reports_first_active(world: &mut E2eWorld) { + assert_eq!( + examined_active_runtime_root(world), + planted_install_root(world, FIRST_FAMILY) + ); +} + +#[then("examine reports the second runtime as the active one")] +async fn examine_reports_second_active(world: &mut E2eWorld) { + assert_eq!( + examined_active_runtime_root(world), + planted_install_root(world, SECOND_FAMILY) + ); +} + +#[then("the text listing says the active runtime key has no registered runtime")] +async fn text_reports_missing_active_key(world: &mut E2eWorld) { + let key = config_active_runtime_key(world).expect("the config names an active runtime key"); + let text = crate::run_rocm_ok(world, &["runtimes", "list"]); + let status: Vec<&str> = text + .lines() + .map(str::trim_start) + .filter(|line| line.starts_with("active_status:")) + .collect(); + assert_eq!( + status, + [format!( + "active_status: missing manifest for active_runtime_key={key}" + )], + "{text}" + ); +} + #[then("the text listing marks the first runtime active with no active_status line")] async fn text_marks_first_active_without_status(world: &mut E2eWorld) { let text = crate::run_rocm_ok(world, &["runtimes", "list"]); @@ -1199,15 +1301,30 @@ async fn json_reports_second_ready(world: &mut E2eWorld) { assert_null_field(runtime, "unusable_reason"); } +/// Names the key the config holds, read back from the config file, and checks +/// that no listed runtime has it in any letter case. #[then("the JSON reports that the active runtime key has no registered runtime")] async fn json_reports_missing_active_manifest(world: &mut E2eWorld) { let listing = listing_json(world); + let key = config_active_runtime_key(world).expect("the config names an active runtime key"); assert_eq!( listing["active_problem"], - serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": SECOND_KEY}), + serde_json::json!({"kind": "missing_manifest_for_key", "runtime_key": key}), "{listing:#}" ); - assert_eq!(listing["active_runtime_key"], SECOND_KEY, "{listing:#}"); + assert_eq!(listing["active_runtime_key"], key.as_str(), "{listing:#}"); + let listed: Vec<&str> = listing["runtimes"] + .as_array() + .expect("`runtimes` is an array") + .iter() + .filter_map(|runtime| runtime["runtime_key"].as_str()) + .collect(); + assert!( + !listed + .iter() + .any(|listed| listed.eq_ignore_ascii_case(&key)), + "`{key}` is registered after all:\n{listing:#}" + ); } #[then("the JSON marks no runtime active")] From 96cd2e221d37b8ae48ba507797ba5be0e24136f5 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 13:54:07 +0200 Subject: [PATCH 3/5] test(runtimes): assert runtimes list --json prints nothing on stdout when it fails (ROCMAI-148) The JSON rules say a failing --json command prints its error to stderr, nothing on stdout, and exits 1, but every runtimes list scenario was a success path. Scenario runtime-lifecycle-29 replaces a registry entry with a folder of the same name, which the listing cannot read on any platform or as root (an entry that reads but does not parse is skipped, so it cannot stand in), and checks exit 1, an empty stdout, and a plain-text error naming that entry. Signed-off-by: Roman Inflianskas --- docs/architecture.md | 2 +- docs/json-output.md | 2 +- docs/testing.md | 10 ++++- .../features/runtime_lifecycle.feature | 12 +++++ .../tests/e2e/runtime_lifecycle_steps.rs | 45 +++++++++++++++++++ 5 files changed, 67 insertions(+), 4 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 144f5ef983..21b94b0220 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -865,7 +865,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, and a check that the text markers and JSON flags agree. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, a check that the text markers and JSON flags agree, and a `--json` list that fails on a registry entry it cannot read and prints nothing on stdout. | flat | | [`tests/e2e/runtime_side_by_side_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_side_by_side_steps.rs) | Steps for the side-by-side scenarios in [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` list, activate and uninstall over managed wheel runtimes planted as installs from before and after the ROCm 10 layout leave them, comparing their install records byte for byte. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | diff --git a/docs/json-output.md b/docs/json-output.md index 9550cf0055..c959907459 100644 --- a/docs/json-output.md +++ b/docs/json-output.md @@ -59,7 +59,7 @@ commands that do not have it yet. | `rocm update` | supported for the check; one compact JSON line, not pretty, and refused with `--apply` and `--dry-run` | supported; the compact form is a known difference from the others | `update-02`, `update-03` | | `rocm storage report` | supported; pretty JSON through `JsonOrText` | supported | `json_or_text_impl_renders_the_report_and_serializes_it` | | `rocm services list` | supported; pretty JSON. `rocm remote` reads it back over its control channel | supported | `services_json_round_trips_and_applies_the_same_liveness_filter_as_the_table`; exercised indirectly by `remote-15` (`@requires-docker`), whose `rocm remote` reads it back | -| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-22` to `runtime-lifecycle-28` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | +| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-22` to `runtime-lifecycle-29` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | | `rocm runtimes activate`, `rollback`, `uninstall`, `import`, `adopt` | none | follow-up: they change state, so they need the envelope's result and refusal shapes | — | | `rocm services logs` | none | intentionally unsupported: streamed text, and `-f` never ends | — | | `rocm services stop`, `restart`, `remove`, `prune` | none | follow-up: needs the envelope, including the refusal path | — | diff --git a/docs/testing.md b/docs/testing.md index af44203676..fcdf6e4f68 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1807,7 +1807,13 @@ the text markers on their own. `"status": "unusable"` with the reason `install root is missing: `, and `@id:runtime-lifecycle-list-json-reports-missing-active-manifest` (`runtime-lifecycle-25`) deletes the active runtime's registry entry and reads -`active_problem` of kind `missing_manifest_for_key`. No scenario checks the +`active_problem` of kind `missing_manifest_for_key`. +`@id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout` +(`runtime-lifecycle-29`) covers the failure half of those rules: it replaces a +registry entry with a folder of the same name, so the listing cannot read it +(an entry that reads but does not parse is skipped, not an error), and checks +that `--json` exits 1 with nothing on stdout and a plain-text error on stderr +naming that entry. No scenario checks the listing's order: scenario 22's two runtimes share one install time, and the registry is read in filesystem order, which can match key order by chance. The order is pinned by unit tests: @@ -1857,7 +1863,7 @@ folder whose path is not valid UTF-8, and `toolchain` words in the text and the JSON together: ```bash -cargo xtask e2e -- -n "runtime-lifecycle-(07|22|23|24|25|26|27|28) " +cargo xtask e2e -- -n "runtime-lifecycle-(07|22|23|24|25|26|27|28|29) " cargo test -p rocm --bin rocm runtimes_list cargo test -p rocm --bin rocm listing_state cargo test -p rocm --bin rocm runtime_toolchain_text_and_json_words_agree_for_every_variant diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index 190a02ce9c..99952df692 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -400,3 +400,15 @@ Feature: Runtime lifecycle state machine And the text listing marks the same runtimes as the JSON And the text listing says the active runtime key has no registered runtime And examine reports the second runtime as the active one + + # `--json` changes what a successful list prints, not how a failure is + # reported: errors are not JSON. A registry entry the CLI cannot read stops + # the list, so a script has to learn that from the exit code and an empty + # stdout rather than from a document that looks like a shorter list. + @id:runtime-lifecycle-list-json-failure-prints-nothing-on-stdout + Scenario: runtime-lifecycle-29 - A runtime list that cannot be read fails as JSON with nothing on stdout + Given two registered runtimes with the second active after the first + And the first runtime's registry entry cannot be read + When the user lists the registered runtimes as JSON + Then the list fails with nothing printed on stdout + And the error on stderr is plain text naming the unreadable registry entry diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 9c7f8d792f..8729290ed1 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -393,6 +393,20 @@ async fn second_runtime_manifest_deleted(world: &mut E2eWorld) { .expect("failed to delete the second runtime's manifest"); } +/// The registry entry is replaced by a folder of the same name: the listing +/// finds it among the entries and fails reading it, on every platform and +/// whoever runs the suite, where a file with its permissions removed is still +/// read by root and cannot be made unreadable the same way on Windows. An entry +/// that reads but does not parse would not do: the listing skips those. +#[given("the first runtime's registry entry cannot be read")] +async fn first_runtime_manifest_unreadable(world: &mut E2eWorld) { + let entry = registry_dir(world).join(format!("{FIRST_KEY}.json")); + std::fs::remove_file(&entry) + .unwrap_or_else(|error| panic!("failed to delete {}: {error}", entry.display())); + std::fs::create_dir(&entry) + .unwrap_or_else(|error| panic!("failed to create {}: {error}", entry.display())); +} + /// A key no runtime is registered under: what the config holds after the /// active runtime's registry entry goes without the CLI noticing. const UNREGISTERED_KEY: &str = "release-tarball-gfx90a"; @@ -1334,6 +1348,37 @@ async fn json_reports_missing_active_manifest(world: &mut E2eWorld) { ); } +/// The failure half of the JSON rules in docs/json-output.md: exit 1 and an +/// empty stdout, so a script that reads stdout cannot mistake the failure for a +/// listing. +#[then("the list fails with nothing printed on stdout")] +async fn list_fails_with_empty_stdout(world: &mut E2eWorld) { + let stderr = world.cli_stderr.as_deref().unwrap_or_default(); + assert_eq!(world.cli_rc, Some(1), "stderr:\n{stderr}"); + assert_eq!( + world.cli_output.as_deref(), + Some(""), + "stdout must be empty when the list fails; stderr:\n{stderr}" + ); +} + +/// The error is the plain text a person reads, not a JSON error document, and +/// it names the entry that could not be read so the user knows what to repair. +#[then("the error on stderr is plain text naming the unreadable registry entry")] +async fn stderr_names_unreadable_entry(world: &mut E2eWorld) { + let stderr = world.cli_stderr.as_deref().unwrap_or_default(); + assert!( + serde_json::from_str::(stderr.trim()).is_err(), + "the error must not be a JSON document:\n{stderr}" + ); + let entry = registry_dir(world).join(format!("{FIRST_KEY}.json")); + assert!( + stderr.contains(&format!("failed to read {}", entry.display())), + "stderr must name {}:\n{stderr}", + entry.display() + ); +} + #[then("the JSON marks no runtime active")] async fn json_marks_none_active(world: &mut E2eWorld) { let listing = listing_json(world); From 5e2b0d49c7fcc6de38ed688b398f6eef7216c0b0 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 15:17:42 +0200 Subject: [PATCH 4/5] feat(runtimes): include provenance in runtimes list --json (ROCMAI-148) The text listing names each runtime's channel, package source, source layout generation and exact GPU target on its `provenance:` line, but the JSON form left them out, so a script had to parse the text to learn which stream or GPU a runtime was installed for. Each runtime in `rocm runtimes list --json` now carries a `provenance` object with the same four facts under the same names, as strings, or `null` where the text prints `unrecorded`, so a script cannot take the placeholder for a recorded value. The JSON takes its names and order from a new `RuntimeProvenance::recorded_fields`, which `fields` (what the text and `rocm examine` print) is now derived from, so the two forms cannot name the facts differently. Unit tests pin the object for recorded, unrecorded, blank and padded values, check that the text line and the JSON object agree for each runtime, and add the object to the exact-key-set contract test. Scenario runtime-lifecycle-31 reads the provenance from the JSON for planted nightly, older and adopted runtimes and compares it with the text listing. It turns the startup update check off, as the examine scenarios do, because with wheel runtimes registered that check can print a progress line on stdout ahead of the document. README, docs/json-output.md, docs/testing.md and docs/manual-testing.md describe the field. Signed-off-by: Roman Inflianskas --- README.md | 9 +- apps/rocm/src/runtime_registry.rs | 33 +-- apps/rocm/src/runtimes_cmd.rs | 238 +++++++++++++++++- docs/architecture.md | 2 +- docs/json-output.md | 13 +- docs/manual-testing.md | 3 + docs/testing.md | 28 ++- .../features/runtime_lifecycle.feature | 23 ++ .../tests/e2e/runtime_lifecycle_steps.rs | 129 +++++++++- 9 files changed, 450 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 885c4420b0..376ec591e9 100644 --- a/README.md +++ b/README.md @@ -897,10 +897,11 @@ and a plain one of the same version are two separate runtimes, as are two installs that resolved different GPU device payloads. `list --json` prints the same listing as one JSON document on stdout for -scripts: each runtime with its key, version, mode, status and toolchain, and -`active` and `rollback_target` flags in place of the `*` and `-` markers. Unset -values are `null`. Fields may be added in later releases; existing ones are not -renamed or removed. +scripts: each runtime with its key, version, mode, status and toolchain, its +`provenance` as an object with the same four facts, and `active` and +`rollback_target` flags in place of the `*` and `-` markers. Unset values, +including a provenance fact the text shows as `unrecorded`, are `null`. Fields +may be added in later releases; existing ones are not renamed or removed. `activate` and `rollback` change which runtime the next install or server picks up. A server that is already running is not moved: it keeps serving on diff --git a/apps/rocm/src/runtime_registry.rs b/apps/rocm/src/runtime_registry.rs index 36de929ace..ac6392d7b8 100644 --- a/apps/rocm/src/runtime_registry.rs +++ b/apps/rocm/src/runtime_registry.rs @@ -250,25 +250,30 @@ pub(crate) struct RuntimeProvenance<'a> { pub device_target: Option<&'a str>, } -impl RuntimeProvenance<'_> { +impl<'a> RuntimeProvenance<'a> { + /// Each fact as `(name, recorded value)`, in display order, with `None` for + /// a fact that was not recorded. + /// + /// The one place the names and their order are written down: + /// [`Self::fields`] shows these, and `rocm runtimes list --json` writes them + /// as its `provenance` object, with `null` for `None`. + pub(crate) const fn recorded_fields(&self) -> [(&'static str, Option<&'a str>); 4] { + [ + ("channel", self.channel), + ("source", self.source), + ("source_layout_generation", self.source_layout_generation), + ("device_target", self.device_target), + ] + } + /// Each fact as `(name, shown value)`, in display order, with /// [`UNRECORDED_PROVENANCE`] for a fact that was not recorded. /// /// `rocm runtimes list` and `rocm examine` both print from this, so the /// names and values the two show for one runtime cannot drift apart. - pub(crate) fn fields(&self) -> [(&'static str, &str); 4] { - fn shown(value: Option<&str>) -> &str { - value.unwrap_or(UNRECORDED_PROVENANCE) - } - [ - ("channel", shown(self.channel)), - ("source", shown(self.source)), - ( - "source_layout_generation", - shown(self.source_layout_generation), - ), - ("device_target", shown(self.device_target)), - ] + pub(crate) fn fields(&self) -> [(&'static str, &'a str); 4] { + self.recorded_fields() + .map(|(name, value)| (name, value.unwrap_or(UNRECORDED_PROVENANCE))) } } diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index a6098670cd..b60007780e 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -601,7 +601,8 @@ const ROLLBACK_RUNTIME_MARKER: &str = "-"; /// and the JSON `active`/`rollback_target` flags come from the same /// computation. The text adds only presentation: the marker legend, the /// next-step hint for an empty registry, the build date it derives from -/// `version`, and the `unusable (…)` wording around `unusable_reason`. The JSON +/// `version`, the `unusable (…)` wording around `unusable_reason`, and the word +/// `unrecorded` for a provenance fact the JSON writes as `null`. The JSON /// form is additive-only: fields may be added, but none is renamed, removed or /// given a new meaning (see `docs/json-output.md`). #[derive(Debug, Serialize)] @@ -677,15 +678,17 @@ struct RuntimeListingEntry { install_root: PathBuf, /// Where the runtime came from, as its manifest recorded it /// (`InstalledRuntimeManifest::provenance`). The text form prints it as the - /// `provenance:` line under `install_root:`. - #[serde(skip)] + /// `provenance:` line under `install_root:`; the JSON form as an object + /// with the same names, `null` where the text prints `unrecorded`. provenance: RuntimeListingProvenance, } /// An owned copy of a runtime's [`RuntimeProvenance`], so the listing can /// outlive the manifests it was computed from. It holds the recorded values -/// (trimmed, `None` when unrecorded) and prints through -/// [`RuntimeProvenance::fields`], the same as `rocm examine`. +/// (trimmed, `None` when unrecorded). The text prints them through +/// [`RuntimeProvenance::fields`], the same as `rocm examine`, and the JSON +/// writes them through [`RuntimeProvenance::recorded_fields`], so the two forms +/// take their names and order from one list. #[derive(Debug, Clone, PartialEq, Eq)] struct RuntimeListingProvenance { channel: Option, @@ -714,6 +717,21 @@ impl RuntimeListingProvenance { } } +/// One JSON object holding each fact under the name the text prints it with, +/// as a string, or `null` when it was not recorded. Not the text's +/// `unrecorded` word: a script must not read that placeholder as a value. +impl Serialize for RuntimeListingProvenance { + fn serialize(&self, serializer: S) -> Result { + use serde::ser::SerializeMap as _; + let fields = self.as_provenance().recorded_fields(); + let mut object = serializer.serialize_map(Some(fields.len()))?; + for (name, value) in fields { + object.serialize_entry(name, &value)?; + } + object.end() + } +} + /// A path as a JSON string, through `to_string_lossy`. serde's own `Path` /// impl fails on a path that is not valid UTF-8, which would leave /// `rocm runtimes list --json` printing nothing for a listing the text form @@ -3055,6 +3073,19 @@ pub(crate) mod tests { "active", "rollback_target", "install_root", + "provenance", + ] + .map(String::from) + ) + ); + assert_eq!( + key_set(&runtime["provenance"]), + std::collections::BTreeSet::from( + [ + "channel", + "source", + "source_layout_generation", + "device_target", ] .map(String::from) ) @@ -3073,6 +3104,203 @@ pub(crate) mod tests { /// when the config says so (`rocm runtimes activate` and `rollback` never /// write that, but the config file is read as it is). Both JSON flags are true; /// the text has one marker column, and active wins it. + /// Plants the runtimes whose provenance the JSON tests read: one per way a + /// fact can be recorded or not. Returns their keys, in this order: a + /// nightly that recorded every fact, a runtime from before the layout and + /// target were recorded, an adopted one (the adoption marker is not a + /// source), a tarball install (no exact target), one whose values are + /// padded with whitespace, and one whose every value is blank. + fn plant_provenance_runtimes(paths: &AppPaths) -> Result<[String; 6]> { + let base = write_test_pip_runtime( + paths, + "release-pip-legacy", + "therock-release:gfx120X-all", + "7.13.0", + 10, + )?; + let legacy = therock::InstalledRuntimeManifest { + index_url: None, + source_layout_generation: None, + wheel_composition: None, + ..base.clone() + }; + let nightly = nightly_exact_target_manifest(base); + write_test_pip_runtime( + paths, + &nightly.runtime_key, + &nightly.runtime_id, + &nightly.version, + 20, + )?; + let adopted = therock::InstalledRuntimeManifest { + runtime_key: "adopted-release-pip".to_owned(), + index_url: None, + selected_artifact_url: crate::runtime_registry::ADOPTED_RUNTIME_ARTIFACT_URL.to_owned(), + read_only: true, + ..legacy.clone() + }; + let tarball = therock::InstalledRuntimeManifest { + runtime_key: "release-tarball-gfx120x-all-7-13-0".to_owned(), + format: "tarball".to_owned(), + selected_artifact_url: "https://example.invalid/tarball/rocm-7.13.0.tar.gz".to_owned(), + source_layout_generation: Some("multi-arch-v2".to_owned()), + ..legacy.clone() + }; + let padded = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-padded".to_owned(), + channel: " release ".to_owned(), + index_url: Some(" https://example.invalid/simple ".to_owned()), + source_layout_generation: Some(" multi-arch-v2 ".to_owned()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: "multi-arch-v2".to_owned(), + package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], + rocm_sdk_target: Some(" gfx1201 ".to_owned()), + }), + ..legacy.clone() + }; + let all_blank = therock::InstalledRuntimeManifest { + runtime_key: "release-pip-all-blank".to_owned(), + channel: String::new(), + index_url: Some(" ".to_owned()), + selected_artifact_url: String::new(), + source_layout_generation: Some(String::new()), + wheel_composition: Some(therock::WheelRuntimeComposition { + source_layout_generation: String::new(), + package_specs: vec!["rocm[libraries]==7.13.0".to_owned()], + rocm_sdk_target: Some(String::new()), + }), + ..legacy.clone() + }; + let planted = [nightly, legacy, adopted, tarball, padded, all_blank]; + for manifest in &planted { + rewrite_manifest(paths, manifest)?; + } + Ok(planted.map(|manifest| manifest.runtime_key)) + } + + /// The JSON names each runtime's provenance facts as strings, trimmed, and + /// writes `null` for one recorded nowhere or recorded blank — never the + /// text's `unrecorded` placeholder, which a script would read as a value. + /// Each object is compared whole, so a fact under the wrong name, a missing + /// one or a placeholder in place of `null` fails here. + #[test] + fn runtimes_list_json_names_recorded_provenance_and_null_for_unrecorded() -> Result<()> { + let (root, paths) = test_paths("runtime-list-json-provenance"); + let [nightly, legacy, adopted, tarball, padded, all_blank] = + plant_provenance_runtimes(&paths)?; + let listing = runtimes_list_json(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + + let provenance = |key: &str| listed_runtime(&listing, key)["provenance"].clone(); + for (key, expected) in [ + ( + nightly, + serde_json::json!({ + "channel": "nightly", + "source": "https://example.invalid/whl-multi-arch", + "source_layout_generation": "next-v1", + "device_target": "gfx1201", + }), + ), + ( + legacy, + serde_json::json!({ + "channel": "release", + "source": "https://example.invalid/therock", + "source_layout_generation": null, + "device_target": null, + }), + ), + ( + adopted, + serde_json::json!({ + "channel": "release", + "source": null, + "source_layout_generation": null, + "device_target": null, + }), + ), + ( + tarball, + serde_json::json!({ + "channel": "release", + "source": "https://example.invalid/tarball/rocm-7.13.0.tar.gz", + "source_layout_generation": "multi-arch-v2", + "device_target": null, + }), + ), + ( + padded, + serde_json::json!({ + "channel": "release", + "source": "https://example.invalid/simple", + "source_layout_generation": "multi-arch-v2", + "device_target": "gfx1201", + }), + ), + ( + all_blank, + serde_json::json!({ + "channel": null, + "source": null, + "source_layout_generation": null, + "device_target": null, + }), + ), + ] { + assert_eq!(provenance(&key), expected, "{key}:\n{listing:#}"); + } + Ok(()) + } + + /// The text's `provenance:` line and the JSON's `provenance` object name + /// the same facts with the same values for every runtime, the text printing + /// `unrecorded` exactly where the JSON has `null`. Both forms are rendered + /// from one listing of the same registry and compared fact by fact, over + /// every way a fact can be recorded or not. + #[test] + fn runtimes_list_text_and_json_name_the_same_provenance() -> Result<()> { + use cli_report::JsonOrText as _; + let (root, paths) = test_paths("runtime-list-provenance-agree"); + let keys = plant_provenance_runtimes(&paths)?; + let listing = runtimes_listing(&paths, &RocmCliConfig::default())?; + let _ = fs::remove_dir_all(root); + let text = listing.render_text(); + let json = serde_json::to_value(&listing)?; + + for key in keys { + let text_pairs: Vec<(String, String)> = provenance_line(&text, &key) + .trim_start() + .strip_prefix("provenance: ") + .expect("provenance prefix") + .split(' ') + .map(|pair| pair.split_once('=').expect("name=value pair")) + .map(|(name, value)| (name.to_owned(), value.to_owned())) + .collect(); + let object = listed_runtime(&json, &key)["provenance"] + .as_object() + .unwrap_or_else(|| panic!("{key} has no provenance object:\n{json:#}")) + .clone(); + assert_eq!( + text_pairs.len(), + object.len(), + "{key}: the text and the JSON name different facts:\n{text}\n{json:#}" + ); + for (name, shown) in text_pairs { + let in_json = object + .get(&name) + .unwrap_or_else(|| panic!("{key}: the JSON has no {name}:\n{json:#}")); + let expected = match in_json { + serde_json::Value::Null => crate::runtime_registry::UNRECORDED_PROVENANCE, + serde_json::Value::String(value) => value.as_str(), + other => panic!("{key}: {name} is neither a string nor null: {other}"), + }; + assert_eq!(shown, expected, "{key}: {name}:\n{text}\n{json:#}"); + } + } + Ok(()) + } + #[test] fn runtimes_list_marks_a_runtime_both_active_and_rollback_target_as_active() -> Result<()> { let (root, paths) = test_paths("runtime-list-active-and-rollback"); diff --git a/docs/architecture.md b/docs/architecture.md index bbb1f1835b..4264273d84 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -865,7 +865,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/model_catalog_steps.rs`](../tests/e2e-cucumber/tests/e2e/model_catalog_steps.rs) | Steps for [`model_catalog.feature`](../tests/e2e-cucumber/features/model_catalog.feature): the verbose catalog's AIM entry, its Docker-unavailable flag and its staleness warning. | flat | | [`tests/e2e/planner_steps.rs`](../tests/e2e-cucumber/tests/e2e/planner_steps.rs) | Steps for the planning-assistant scenarios in [`chat.feature`](../tests/e2e-cucumber/features/chat.feature), with a scripted mock proving a request is handed over once and its plan is the one shown. | flat | | [`tests/e2e/remote_steps.rs`](../tests/e2e-cucumber/tests/e2e/remote_steps.rs) | Steps for [`remote.feature`](../tests/e2e-cucumber/features/remote.feature): `rocm remote` against the `fake-tailscale` stand-in and a status document the step writes. | flat | -| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, listing planted nightly wheel, older and adopted runtimes with their provenance, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, a check that the text markers and JSON flags agree, and a `--json` list that fails on a registry entry it cannot read and prints nothing on stdout. | flat | +| [`tests/e2e/runtime_lifecycle_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs) | Steps for [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` activate, rollback, uninstall and import over planted read-only tarball runtimes, listing planted nightly wheel, older and adopted runtimes with their provenance in the text and in the JSON, and `runtimes list` as text and as `--json`, including the JSON for a runtime whose folder was deleted and for an active key whose registry entry was, a default runtime set in other letter case through `rocm config set-default-runtime`, an active key edited to other letter case or to a key no runtime has, checked against the active runtime `rocm examine --json` reports, a check that the text markers and JSON flags agree, and a `--json` list that fails on a registry entry it cannot read and prints nothing on stdout. | flat | | [`tests/e2e/runtime_side_by_side_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_side_by_side_steps.rs) | Steps for the side-by-side scenarios in [`runtime_lifecycle.feature`](../tests/e2e-cucumber/features/runtime_lifecycle.feature): `rocm runtimes` list, activate and uninstall over managed wheel runtimes planted as installs from before and after the ROCm 10 layout leave them, comparing their install records byte for byte. | flat | | [`tests/e2e/runtime_steps.rs`](../tests/e2e-cucumber/tests/e2e/runtime_steps.rs) | Steps for [`runtime_setup.feature`](../tests/e2e-cucumber/features/runtime_setup.feature): SDK install previews and installs, runtime folders reached through a link, and the managed runtime they leave active. | flat | | [`tests/e2e/service_cleanup_steps.rs`](../tests/e2e-cucumber/tests/e2e/service_cleanup_steps.rs) | Steps for [`service_record_cleanup.feature`](../tests/e2e-cucumber/features/service_record_cleanup.feature): `rocm services remove` and `prune` over planted service records, asserting on the files that survive, and [`service_record_unqueryable.feature`](../tests/e2e-cucumber/features/service_record_unqueryable.feature): a record whose process cannot be queried (the `e2e-test-hooks` build reads `ROCM_E2E_UNQUERYABLE_PIDS`) is stopped as unverified, refused by `remove`, and cleared by `remove --force` only when no recorded process is confirmed running. | flat | diff --git a/docs/json-output.md b/docs/json-output.md index ec8f509e8d..c652e35d7d 100644 --- a/docs/json-output.md +++ b/docs/json-output.md @@ -59,7 +59,7 @@ commands that do not have it yet. | `rocm update` | supported for the check; one compact JSON line, not pretty, and refused with `--apply` and `--dry-run` | supported; the compact form is a known difference from the others | `update-02`, `update-03` | | `rocm storage report` | supported; pretty JSON through `JsonOrText` | supported | `json_or_text_impl_renders_the_report_and_serializes_it` | | `rocm services list` | supported; pretty JSON. `rocm remote` reads it back over its control channel | supported | `services_json_round_trips_and_applies_the_same_liveness_filter_as_the_table`; exercised indirectly by `remote-15` (`@requires-docker`), whose `rocm remote` reads it back | -| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-23` to `runtime-lifecycle-30` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | +| `rocm runtimes list` | supported; pretty JSON through `JsonOrText` | supported, additive-only, no version field yet | `runtime-lifecycle-23` to `runtime-lifecycle-31` and `runtimes_list_json_has_exactly_the_documented_fields_newest_install_first`; what each covers is in [testing.md](testing.md#runtime-selection-and-activation) | | `rocm runtimes activate`, `rollback`, `uninstall`, `import`, `adopt` | none | follow-up: they change state, so they need the envelope's result and refusal shapes | — | | `rocm services logs` | none | intentionally unsupported: streamed text, and `-f` never ends | — | | `rocm services stop`, `restart`, `remove`, `prune` | none | follow-up: needs the envelope, including the refusal path | — | @@ -92,10 +92,19 @@ that activation applies, `unusable` when it fails it; `ready` does not promise that an activation succeeds), `unusable_reason` (`null` when ready, otherwise why the runtime fails that check: text for a person, not a code to match on), `toolchain` (`included` or `excluded`, the words `rocm examine` uses), `active`, -`rollback_target` and `install_root`. `active` and `rollback_target` are the facts the text marks with +`rollback_target`, `install_root` and `provenance`. `active` and `rollback_target` are the facts the text marks with `*` and `-`; a runtime that is both is shown as `*` in the text. The text's next-step hint for an empty registry is not part of the JSON. +`provenance` is an object with the four facts the text prints on the runtime's +`provenance:` line, under the same names: `channel`, `source` (the package +index, else the downloaded archive), `source_layout_generation` and +`device_target`. Each is the value the manifest recorded, trimmed, or `null` +where the text prints `unrecorded`: a fact recorded nowhere or recorded blank, +the source of an adopted runtime, the exact target of a tarball or family-wide +install. A script reads `null` as "not recorded"; nothing is guessed from other +facts. + `registry`, `marker` and `install_root` are strings. A path that is not valid UTF-8 is written with each invalid sequence replaced by U+FFFD, as the text form prints it, so such a path cannot be passed back to the filesystem from the diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 0ea7b537fb..afdbad36ac 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -141,6 +141,9 @@ Expected result: one; the runtime marked `-`, if any, has `"rollback_target": true`. - The runtime marked active is the one `rocm examine` reports: its `install_root` is the `active_runtime_root` that `rocm examine` prints. +- Each runtime's `provenance` object names the same `channel`, `source`, + `source_layout_generation` and `device_target` as its `provenance:` line in + the text, with `null` where the text shows `unrecorded`. Optional: an unreadable settings file. Copy `config.json` from the config directory aside, cut the original off part-way through, and run `rocm version` diff --git a/docs/testing.md b/docs/testing.md index 968d24b3d8..65f1ab9775 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1863,7 +1863,7 @@ folder whose path is not valid UTF-8, and `toolchain` words in the text and the JSON together: ```bash -cargo xtask e2e -- -n "runtime-lifecycle-(07|23|24|25|26|27|28|29|30) " +cargo xtask e2e -- -n "runtime-lifecycle-(07|23|24|25|26|27|28|29|30|31) " cargo test -p rocm --bin rocm runtimes_list cargo test -p rocm --bin rocm listing_state cargo test -p rocm --bin rocm runtime_toolchain_text_and_json_words_agree_for_every_variant @@ -1927,6 +1927,32 @@ the `examine` lines. Both plant read-only manifests and run on the mock lane: RUSTC_WRAPPER= cargo xtask e2e -- -n 'runtime-lifecycle-22 |examine-54 ' ``` +`rocm runtimes list --json` gives each runtime the same four facts as a +`provenance` object under the same names, with `null` where the text prints +`unrecorded` ([json-output.md](json-output.md)). Both +forms render from one listing, and the JSON takes its names and order from +`RuntimeProvenance::recorded_fields`, the list `RuntimeProvenance::fields` +shows. `runtimes_list_json_names_recorded_provenance_and_null_for_unrecorded` +in [runtimes_cmd.rs](../apps/rocm/src/runtimes_cmd.rs) pins the whole object +for a nightly, an older, an adopted, a tarball, a padded and an all-blank +runtime; `runtimes_list_text_and_json_name_the_same_provenance` checks over the +same runtimes that the text line and the JSON object name the same facts with +the same values; and +`runtimes_list_json_has_exactly_the_documented_fields_newest_install_first` +pins the object's key set. +`@id:runtime-lifecycle-list-json-names-runtime-provenance` +(`runtime-lifecycle-31`) plants the runtimes of `runtime-lifecycle-22`, reads +each one's provenance from the JSON, and compares it with the text listing of +the same state. It sets `ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK`, as the +examine scenarios that plant a runtime do: with wheel runtimes registered, the +startup update check looks for a Python and the network and can print a +progress line on stdout ahead of the document. It runs on the mock lane: + +```bash +cargo xtask e2e -- -n 'runtime-lifecycle-31 ' +cargo test -p rocm --bin rocm runtimes_list +``` + Activate one validated runtime: ```bash diff --git a/tests/e2e-cucumber/features/runtime_lifecycle.feature b/tests/e2e-cucumber/features/runtime_lifecycle.feature index 2cba8db0e7..19bfe62a5b 100644 --- a/tests/e2e-cucumber/features/runtime_lifecycle.feature +++ b/tests/e2e-cucumber/features/runtime_lifecycle.feature @@ -432,3 +432,26 @@ Feature: Runtime lifecycle state machine When the user lists the registered runtimes as JSON Then the list fails with nothing printed on stdout And the error on stderr is plain text naming the unreadable registry entry + + # A script reads where each runtime came from out of the JSON listing instead + # of parsing the text's `provenance:` line. A fact the manifest never recorded + # has no value there, where the text prints `unrecorded`, so a script cannot + # take the placeholder for a recorded value. The same runtimes as + # `runtime-lifecycle-22` are planted, and the text listing of the same state + # is compared fact by fact, so the two forms are shown to agree. The startup + # update check is off: with wheel runtimes registered it looks for a Python + # and the network, and can print ahead of the document, which is not what + # this scenario is about. The planted manifests need no SDK download or GPU, + # so this runs on the mock lane. + @id:runtime-lifecycle-list-json-names-runtime-provenance + Scenario: runtime-lifecycle-31 - A script reads from the JSON runtime list which stream, source and GPU each runtime was installed from + Given a registered nightly runtime installed for one exact GPU + And a registered runtime installed before its source layout and GPU target were recorded + And a registered runtime adopted from an environment ROCm CLI did not install + And ROCm CLI does not check for runtime updates when it starts + When the user lists the registered runtimes as JSON + Then the output is a single JSON document and nothing else + And the JSON names the nightly runtime's channel, package source, source layout and exact GPU target + And the JSON gives no value for each fact the older runtime did not record instead of guessing + And the JSON gives no package source for the adopted runtime + And the text listing names the same provenance as the JSON for every runtime diff --git a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs index 59c94bef81..429d3573ca 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_lifecycle_steps.rs @@ -670,6 +670,23 @@ async fn registered_adopted_runtime(world: &mut E2eWorld) { plant_adopted_runtime(world); } +/// A registered wheel runtime makes `rocm` start with the startup update check, +/// which looks for a usable Python and the network, and prints a progress line +/// on stdout ahead of a `--json` document when the Python on `PATH` does not fit +/// (the examine steps turn it off for the same reason). The scenarios that set +/// this are about the listing, not updates. Like every scenario env it is +/// consumed by one run, so a step that runs `rocm` again sets it again. +fn disable_startup_update_check(world: &mut E2eWorld) { + world + .command_env + .push(("ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK", "1".into())); +} + +#[given("ROCm CLI does not check for runtime updates when it starts")] +async fn no_startup_update_check(world: &mut E2eWorld) { + disable_startup_update_check(world); +} + #[given("a runtime manifest to import")] async fn manifest_to_import(world: &mut E2eWorld) { let path = write_import_manifest(world); @@ -829,9 +846,12 @@ async fn set_default_runtime_in_other_case(world: &mut E2eWorld) { crate::run_rocm_ok(world, &["config", "set-default-runtime", &runtime_id]); } +/// Runs with the scenario's command environment (none unless a Given step set +/// one), which this run consumes. #[when("the user lists the registered runtimes as JSON")] async fn list_runtimes_json(world: &mut E2eWorld) { - let (stdout, stderr, rc) = crate::run_rocm(world, &["runtimes", "list", "--json"]); + let (stdout, stderr, rc) = + crate::run_rocm_with_scenario_env(world, &["runtimes", "list", "--json"]); record(world, stdout, stderr, rc); } @@ -2102,3 +2122,110 @@ async fn adopted_listing_says_source_unrecorded(world: &mut E2eWorld) { adoption marker as a package source:\n{out}" ); } + +/// The `provenance` object the JSON listing gives `runtime_key`, compared whole +/// against `expected` by the steps below, so a fact under another name, a +/// missing one, or the text's `unrecorded` in place of `null` fails. +fn assert_json_provenance(world: &E2eWorld, runtime_key: &str, expected: &serde_json::Value) { + let listing = listing_json(world); + assert_eq!( + &listed_runtime(&listing, runtime_key)["provenance"], + expected, + "{runtime_key}:\n{listing:#}" + ); +} + +#[then( + "the JSON names the nightly runtime's channel, package source, source layout and exact GPU target" +)] +async fn json_names_nightly_provenance(world: &mut E2eWorld) { + assert_json_provenance( + world, + NIGHTLY_EXACT_TARGET_KEY, + &serde_json::json!({ + "channel": "nightly", + "source": NIGHTLY_SOURCE, + "source_layout_generation": NIGHTLY_SOURCE_LAYOUT, + "device_target": NIGHTLY_DEVICE_TARGET, + }), + ); +} + +/// The older runtime's family is the exact `gfx942`, so a target guessed from +/// it would be a plausible string here rather than `null`. +#[then( + "the JSON gives no value for each fact the older runtime did not record instead of guessing" +)] +async fn json_gives_null_for_unrecorded_facts(world: &mut E2eWorld) { + assert_json_provenance( + world, + FIRST_KEY, + &serde_json::json!({ + "channel": "release", + "source": format!("https://example.invalid/{FIRST_KEY}.tar.gz"), + "source_layout_generation": null, + "device_target": null, + }), + ); +} + +#[then("the JSON gives no package source for the adopted runtime")] +async fn json_gives_adopted_runtime_no_source(world: &mut E2eWorld) { + assert_json_provenance( + world, + ADOPTED_KEY, + &serde_json::json!({ + "channel": "release", + "source": null, + "source_layout_generation": null, + "device_target": null, + }), + ); +} + +/// Lists the same state as text and compares every runtime's `provenance:` line +/// with the JSON object just read: the same names, the same values, and +/// `unrecorded` exactly where the JSON has `null`. +#[then("the text listing names the same provenance as the JSON for every runtime")] +async fn text_provenance_matches_json(world: &mut E2eWorld) { + let listing = listing_json(world); + // The listing run consumed the scenario's setting; this run sets it again. + disable_startup_update_check(world); + let (text, stderr, rc) = crate::run_rocm_with_scenario_env(world, &["runtimes", "list"]); + assert_eq!(rc, 0, "the text listing failed:\n{text}\n{stderr}"); + let runtimes = listing["runtimes"] + .as_array() + .unwrap_or_else(|| panic!("`runtimes` is not an array:\n{listing:#}")); + assert!( + !runtimes.is_empty(), + "the JSON lists no runtime, so there is nothing to compare:\n{listing:#}" + ); + for runtime in runtimes { + let key = runtime["runtime_key"] + .as_str() + .unwrap_or_else(|| panic!("a runtime has no runtime_key:\n{listing:#}")); + let object = runtime["provenance"] + .as_object() + .unwrap_or_else(|| panic!("{key} has no provenance object:\n{listing:#}")); + let shown: Vec<(&str, &str)> = listed_provenance(&text, key) + .split(' ') + .map(|pair| { + pair.split_once('=') + .unwrap_or_else(|| panic!("{key}: {pair:?} is not name=value:\n{text}")) + }) + .collect(); + assert_eq!( + shown.len(), + object.len(), + "{key}: the text and the JSON name different facts:\n{text}\n{listing:#}" + ); + for (name, value) in shown { + let expected = match object.get(name) { + Some(serde_json::Value::Null) => "unrecorded", + Some(serde_json::Value::String(recorded)) => recorded.as_str(), + other => panic!("{key}: the JSON's {name} is {other:?}:\n{listing:#}"), + }; + assert_eq!(value, expected, "{key}: {name}:\n{text}\n{listing:#}"); + } + } +} From dec432bec843fac3d2c75474bcf687d97306d5a6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 17 Nov 2026 15:29:25 +0200 Subject: [PATCH 5/5] docs(runtimes): state the startup update check caveat and fix a misplaced test comment (ROCMAI-148) docs/json-output.md promises that --json leaves only the document on stdout. The startup update check that runs before most commands can still print a Python progress line on stdout first, once per check interval, when the runtime it checks is a wheel install whose recorded Python is unusable and the Python it finds instead does not fit. State that exception and the variable that turns the check off, so a script author knows about it until the follow-up moves the line. Also move the doc comment of the active-and-rollback-target list test back above that test; the provenance fixture helper had been inserted between them. Signed-off-by: Roman Inflianskas --- apps/rocm/src/runtimes_cmd.rs | 8 ++++---- docs/json-output.md | 9 +++++++++ 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/apps/rocm/src/runtimes_cmd.rs b/apps/rocm/src/runtimes_cmd.rs index b60007780e..b42621f43a 100644 --- a/apps/rocm/src/runtimes_cmd.rs +++ b/apps/rocm/src/runtimes_cmd.rs @@ -3100,10 +3100,6 @@ pub(crate) mod tests { Ok(()) } - /// A runtime can be both the active one and the recorded rollback target - /// when the config says so (`rocm runtimes activate` and `rollback` never - /// write that, but the config file is read as it is). Both JSON flags are true; - /// the text has one marker column, and active wins it. /// Plants the runtimes whose provenance the JSON tests read: one per way a /// fact can be recorded or not. Returns their keys, in this order: a /// nightly that recorded every fact, a runtime from before the layout and @@ -3301,6 +3297,10 @@ pub(crate) mod tests { Ok(()) } + /// A runtime can be both the active one and the recorded rollback target + /// when the config says so (`rocm runtimes activate` and `rollback` never + /// write that, but the config file is read as it is). Both JSON flags are true; + /// the text has one marker column, and active wins it. #[test] fn runtimes_list_marks_a_runtime_both_active_and_rollback_target_as_active() -> Result<()> { let (root, paths) = test_paths("runtime-list-active-and-rollback"); diff --git a/docs/json-output.md b/docs/json-output.md index c652e35d7d..f35214b089 100644 --- a/docs/json-output.md +++ b/docs/json-output.md @@ -18,6 +18,15 @@ commands that do not have it yet. progress and warnings go to stderr. A command that has no single document to print is listed below as unsupported rather than given a `--json` that mixes the two. + + One known exception, tracked as a follow-up: the startup update check that + runs before most commands can print a progress line on stdout ahead of the + document, such as `Python from PATH is not usable for this ROCm install`. + It runs at most once per check interval, and prints only when the runtime it + checks is a wheel install whose recorded Python is not usable and a Python + it finds instead (on `PATH`, or a saved managed one) does not fit. Setting + `ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK` turns the check off, and with it the + line. - **Errors are not JSON today.** A command that fails with `--json` prints its error to stderr, prints nothing on stdout, and exits 1, unless the command documents its own code, as `rocm fix` does. Command lines the argument parser