diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 2de4ecb64a..75bccb49b5 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -56,8 +56,8 @@ use self::source::{ requested_source_layout, select_source_layout, }; pub(crate) use self::update::{ - maybe_refresh_startup_update_check, render_update_json, render_update_report, - runtime_update_plan, + RuntimeUpdatePlan, maybe_refresh_startup_update_check, render_update_json, + render_update_report, runtime_update_check, runtime_update_plan, }; pub(crate) use self::version::runtime_version_display; use self::version::{ diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 43b38f0261..3ca1ff1a55 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -525,8 +525,8 @@ pub(super) fn python_for_install( Ok(python) } -/// The interpreter a *preview* of the install reports, found without preparing -/// one. +/// The interpreter a *preview* of the install, or an update check, reports, +/// found without preparing one. /// /// [`resolve_python_launcher`] ends by downloading a managed `uv`, having it /// install Python, and saving that Python's path in the configuration when no @@ -538,7 +538,10 @@ pub(super) fn python_for_install( /// resolution raises before that step (an unusable `ROCM_CLI_PYTHON`, a /// disabled managed bootstrap) is raised here too, so a preview never succeeds /// on a host where the install would refuse. -fn plan_python_launcher(paths: &AppPaths, requirement: PythonRequirement) -> Result { +pub(super) fn plan_python_launcher( + paths: &AppPaths, + requirement: PythonRequirement, +) -> Result { let env = python_resolver_env_override().unwrap_or_else(PythonResolverEnv::from_process_env); plan_python_launcher_in(paths, &env, requirement) } @@ -655,6 +658,28 @@ impl PlannedPython { } } + /// The `python_note:` line of an update check, in the same terms as + /// [`Self::note`] but for the step an update would take. An update check + /// needs the interpreter's wheel tag to read the index, and a host with no + /// interpreter gets it from the one the layout requires, so this line is how + /// the check says it did not go and prepare one. Built from the decision, as + /// the preview's is. + pub(super) fn update_note(&self) -> Option { + match self { + Self::Ready(_) => None, + Self::WouldPrepareManaged { + version, + requirement, + tag_check, + } => { + let unchecked = unchecked_tag_caveat(*tag_check, *requirement); + Some(format!( + "no usable Python was found; updating would use uv to install managed Python {version}{unchecked} and save its path in the configuration, which this check did not do" + )) + } + } + } + /// The progress line that names the chosen interpreter: the one an install /// goes on with, or, for a preview on a host with no usable Python, what a /// real install would prepare. It is the only line that predicts the @@ -988,7 +1013,7 @@ fn python_venv_probe_temp_root() -> Result { mod tests { use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; - use crate::therock::test_support::test_paths; + use crate::therock::test_support::{RestoredEnv, test_paths}; #[cfg(unix)] fn write_fake_python_with_venv(dir: &Path, name: &str) -> Result { @@ -1410,43 +1435,6 @@ exit 1 // ---- a dry run prepares no Python ---------------------------------------- - /// Process environment variables set for one test and restored on drop. - /// Every caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. - struct RestoredEnv(Vec<(&'static str, Option)>); - - impl RestoredEnv { - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 - fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { - let saved = vars - .iter() - .map(|(key, _)| (*key, std::env::var_os(key))) - .collect(); - for (key, value) in vars { - unsafe { - match value { - Some(value) => std::env::set_var(key, value), - None => std::env::remove_var(key), - } - } - } - Self(saved) - } - } - - impl Drop for RestoredEnv { - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 - fn drop(&mut self) { - for (key, value) in self.0.drain(..) { - unsafe { - match value { - Some(value) => std::env::set_var(key, value), - None => std::env::remove_var(key), - } - } - } - } - } - /// A `uv` that records its arguments in `marker` and then fails. A host that /// reaches it has gone on to prepare a managed Python; failing keeps a test /// that does reach it from going on to the network. @@ -1541,6 +1529,16 @@ exit 1 ) } + /// What an update check goes on with, searching only this host's folder. + fn plan_for_update_check(&self) -> Result { + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: vec![self.search_dir.clone()], + ..PythonResolverEnv::from_process_env() + }); + plan_python_launcher(&self.paths, python_requirement(SourceLayout::Canonical)) + } + fn uv_was_run(&self) -> bool { self.uv_marker.exists() } @@ -2300,6 +2298,81 @@ exit 1 Ok(()) } + /// An update check reads the index by the interpreter's wheel tag. On a host + /// with no interpreter that tag is the one the layout requires, which a real + /// update would prepare an interpreter to match, so the check needs nothing + /// prepared. The note it prints says so, and the folders agree; the same host + /// DOES reach `uv` for the install, so an unrun stand-in means the check + /// stayed out of it. The Gherkin scenario `update-09` drives the same case + /// through the built binary. + #[cfg(unix)] + #[test] + fn an_update_check_with_no_usable_python_reads_the_required_tag_and_prepares_nothing() + -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-update-check-none")?; + let requirement = python_requirement(SourceLayout::Canonical); + + let planned = host.plan_for_update_check()?; + + let compatibility = planned.wheel_compatibility()?; + assert_eq!(compatibility.python_tag, requirement.tag); + assert!(!compatibility.platform_tags.is_empty()); + assert_eq!( + planned.update_note().as_deref(), + Some( + "no usable Python was found; updating would use uv to install managed Python 3.12 and save its path in the configuration, which this check did not do" + ) + ); + assert!(!host.uv_was_run(), "the update check ran uv"); + assert_eq!( + snapshot(&host.paths), + Vec::::new(), + "the update check created files or folders under the config, data or cache folder" + ); + + // Control: the install on the same host does reach `uv`. + assert!(host.python_for_install(false).is_err()); + assert!( + host.uv_was_run(), + "the stand-in uv is not reachable, so the checks above prove nothing" + ); + Ok(()) + } + + /// A usable interpreter needs no note, and a managed Python whose tag cannot + /// be read off its version says so in the update note as in the preview's. + #[cfg(unix)] + #[test] + fn an_update_note_is_absent_for_a_usable_python_and_flags_an_unreadable_tag() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-update-note")?; + { + let _unreadable = RestoredEnv::set(&[( + "ROCM_CLI_MANAGED_PYTHON_VERSION", + Some(Path::new("pypy@3.10")), + )]); + let planned = host.plan_for_update_check()?; + let note = planned.update_note().expect("nothing was prepared"); + assert!( + note.contains("managed Python pypy@3.10 (its wheel tag cannot be checked until it is installed; cp312 is required)") + && note.ends_with("which this check did not do"), + "{note}" + ); + } + + write_fake_python_with_venv(&host.search_dir, "python3")?; + let planned = host.plan_for_update_check()?; + assert!(matches!(planned, PlannedPython::Ready(_)), "{planned:?}"); + assert_eq!(planned.update_note(), None); + assert!(!host.uv_was_run()); + Ok(()) + } + /// The version-to-tag reading the preview's refusal rests on, and that it is /// the same rule `python_launcher_install_ready` applies (same message). #[test] diff --git a/apps/rocm/src/therock/test_support.rs b/apps/rocm/src/therock/test_support.rs index e0b41a46d0..f27c50dd8e 100644 --- a/apps/rocm/src/therock/test_support.rs +++ b/apps/rocm/src/therock/test_support.rs @@ -11,7 +11,45 @@ use crate::runtime_registry::{InstalledRuntimeManifest, runtime_manifest_path}; use anyhow::Result; use rocm_core::AppPaths; use std::fs; -use std::path::PathBuf; +use std::path::{Path, PathBuf}; + +/// Process environment variables set for one test and restored on drop. Every +/// caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. +pub(super) struct RestoredEnv(Vec<(&'static str, Option)>); + +impl RestoredEnv { + /// Sets (`Some`) or removes (`None`) each variable, remembering what it was. + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + pub(super) fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { + let saved = vars + .iter() + .map(|(key, _)| (*key, std::env::var_os(key))) + .collect(); + for (key, value) in vars { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + Self(saved) + } +} + +impl Drop for RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn drop(&mut self) { + for (key, value) in self.0.drain(..) { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + } +} pub(super) fn family_for_test(family: &str, raw_arch: Option<&str>) -> FamilyResolution { FamilyResolution { diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index ccfea9278a..a006fece71 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -4,14 +4,20 @@ //! Whether an installed runtime has something newer to offer, and the bounded //! startup check that asks. `runtime_update_plan` resolves the latest source for -//! one runtime (`resolve_latest_for_manifest`, which re-resolves a wheel -//! runtime through `resolve_pip_runtime_with_timeout` and a tarball one through +//! one runtime, and `runtime_update_check` does the same for a caller that +//! changes nothing (the report, the JSON, the startup check and an apply's +//! preview). They differ in `PythonAccess`: given a wheel runtime that records +//! no usable Python, the plan prepares a managed Python (an apply needs one), +//! while the check works the wheel tag out from the interpreter the layout +//! requires and carries a `python_note` saying the preparation was left undone +//! (`resolve_latest_for_manifest` re-resolves a wheel runtime through +//! `resolve_pip_runtime_with_timeout` and a tarball one through //! `resolve_tarball_artifact_with_timeout`, on the layout the runtime was //! installed from) and `runtime_freshness` classifies it (`RuntimeFreshness`: //! up to date, update available, repair available, or ahead of the index) into //! a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` show //! the plans for `rocm update` (the JSON form is what the dashboard's update -//! check parses), and `maybe_refresh_startup_update_check` keeps one +//! check parses and carries no `python_note`), and `maybe_refresh_startup_update_check` keeps one //! `StartupUpdateCheckRecord` in the cache so the check runs at most once an //! interval and is bounded by a short download timeout. //! @@ -25,8 +31,8 @@ use super::family::family_override_or_recovered_arch; use super::process::SuppressProgressOutput; use super::python::{ - PythonLauncher, PythonSource, python_launcher_install_ready, python_requirement, - resolve_python_launcher, wheel_compatibility_for_python, + PythonLauncher, PythonSource, plan_python_launcher, python_launcher_install_ready, + python_requirement, resolve_python_launcher, wheel_compatibility_for_python, }; use super::resolve::{ AggregateDeviceTarget, resolve_pip_runtime_with_timeout, resolve_tarball_artifact_with_timeout, @@ -84,6 +90,22 @@ pub(crate) struct RuntimeUpdatePlan { pub source_layout_generation: Option, pub repair_required: bool, pub update_available: bool, + /// Set when the runtime records no usable Python and the check left one + /// unprepared: what an update would do about it. + pub python_note: Option, +} + +/// Whether resolving a wheel runtime's latest version may prepare a Python. +/// +/// Reading the index needs the interpreter's wheel tag. A runtime that records +/// a usable Python supplies it. For one that does not, an apply goes on to +/// prepare a managed Python (it needs one for the install that follows), but a +/// check changes nothing, so it works the tag out from the interpreter the +/// layout requires and says it left the preparation undone. +#[derive(Debug, Clone, Copy, Eq, PartialEq)] +enum PythonAccess { + MayPrepare, + SearchOnly, } #[derive(Debug, Clone, Copy, Eq, PartialEq)] @@ -117,6 +139,7 @@ struct ResolvedRuntimeUpdate { format: String, source_layout_generation: String, wheel_composition: Option, + python_note: Option, } pub(crate) fn render_update_report(paths: &AppPaths) -> Result { @@ -145,7 +168,7 @@ pub(crate) fn render_update_report(paths: &AppPaths) -> Result { } for manifest in &manifests { - let plan = match runtime_update_plan(paths, manifest, &manifests, None) { + let plan = match runtime_update_check(paths, manifest, &manifests, None) { Ok(plan) => Some(plan), Err(error) => { let _ = writeln!( @@ -182,6 +205,9 @@ pub(crate) fn render_update_report(paths: &AppPaths) -> Result { manifest.install_root.display() ); let _ = writeln!(output, " source: {}", plan.latest_source); + if let Some(note) = &plan.python_note { + let _ = writeln!(output, " python_note: {note}"); + } if plan.update_available { let next_step = if plan.repair_required { format!( @@ -248,7 +274,7 @@ pub(crate) fn render_update_json( let manifests = load_runtime_manifests(paths)?; let mut runtimes = Vec::with_capacity(manifests.len()); for manifest in &manifests { - match runtime_update_plan(paths, manifest, &manifests, download_timeout_secs) { + match runtime_update_check(paths, manifest, &manifests, download_timeout_secs) { Ok(plan) => runtimes.push(UpdateJsonRuntime { runtime_key: manifest.runtime_key.clone(), channel: manifest.channel.clone(), @@ -357,13 +383,49 @@ fn runtime_freshness_with_manifests( } } +/// The plan an apply works from. A wheel runtime that records no usable Python +/// has one prepared here, since the install that follows needs it. pub(crate) fn runtime_update_plan( paths: &AppPaths, manifest: &InstalledRuntimeManifest, manifests: &[InstalledRuntimeManifest], download_timeout_secs: Option, ) -> Result { - let latest = resolve_latest_for_manifest(paths, manifest, download_timeout_secs)?; + plan_runtime_update( + paths, + manifest, + manifests, + download_timeout_secs, + PythonAccess::MayPrepare, + ) +} + +/// The same plan for a caller that changes nothing: the update report, the JSON +/// the dashboard reads, and the preview of an apply. It never prepares a Python. +pub(crate) fn runtime_update_check( + paths: &AppPaths, + manifest: &InstalledRuntimeManifest, + manifests: &[InstalledRuntimeManifest], + download_timeout_secs: Option, +) -> Result { + plan_runtime_update( + paths, + manifest, + manifests, + download_timeout_secs, + PythonAccess::SearchOnly, + ) +} + +fn plan_runtime_update( + paths: &AppPaths, + manifest: &InstalledRuntimeManifest, + manifests: &[InstalledRuntimeManifest], + download_timeout_secs: Option, + python_access: PythonAccess, +) -> Result { + let latest = + resolve_latest_for_manifest(paths, manifest, download_timeout_secs, python_access)?; let freshness = runtime_freshness_with_manifests( manifests, manifest, @@ -386,6 +448,7 @@ pub(crate) fn runtime_update_plan( source_layout_generation: Some(latest.source_layout_generation), repair_required: freshness == RuntimeFreshness::RepairAvailable, update_available: freshness.update_available(), + python_note: latest.python_note, }) } @@ -417,6 +480,7 @@ fn resolve_latest_for_manifest( paths: &AppPaths, manifest: &InstalledRuntimeManifest, download_timeout_secs: Option, + python_access: PythonAccess, ) -> Result { let channel = TheRockChannel::parse(&manifest.channel)?; let layout = manifest_source_layout(manifest)?; @@ -437,12 +501,17 @@ fn resolve_latest_for_manifest( executable, source: PythonSource::Manifest, }); - let python_executable = match manifest_python { - Some(python) => python, - None => resolve_python_launcher(paths, requirement)?, + let (wheel_compatibility, python_note) = match (manifest_python, python_access) { + (Some(python), _) => (wheel_compatibility_for_python(&python.executable)?, None), + (None, PythonAccess::MayPrepare) => { + let python = resolve_python_launcher(paths, requirement)?; + (wheel_compatibility_for_python(&python.executable)?, None) + } + (None, PythonAccess::SearchOnly) => { + let planned = plan_python_launcher(paths, requirement)?; + (planned.wheel_compatibility()?, planned.update_note()) + } }; - let wheel_compatibility = - wheel_compatibility_for_python(&python_executable.executable)?; let family_override = manifest_wheel_family_override(manifest); let resolution = resolve_pip_runtime_with_timeout( paths, @@ -488,6 +557,7 @@ fn resolve_latest_for_manifest( format: "wheel".to_owned(), source_layout_generation: resolution.layout.generation().to_owned(), wheel_composition, + python_note, }) } "tarball" => { @@ -512,6 +582,7 @@ fn resolve_latest_for_manifest( format: "tarball".to_owned(), source_layout_generation: artifact.layout.generation().to_owned(), wheel_composition: None, + python_note: None, }) } other => bail!("unknown manifest format `{other}`"), @@ -585,7 +656,12 @@ fn build_startup_update_check_record( now_unix_ms: u128, download_timeout_secs: Option, ) -> StartupUpdateCheckRecord { - match resolve_latest_for_manifest(paths, manifest, download_timeout_secs) { + match resolve_latest_for_manifest( + paths, + manifest, + download_timeout_secs, + PythonAccess::SearchOnly, + ) { Ok(latest) => { let freshness = runtime_freshness_with_manifests( manifests, @@ -654,11 +730,15 @@ mod tests { use super::super::process::{PROGRESS_LINE_SINK, progress_output_suppressed}; use super::super::python::{OverridePythonResolverEnv, PythonResolverEnv}; use super::super::source::THEROCK_SOURCE_LAYOUT_GENERATION; + #[cfg(unix)] + use super::super::test_support::RestoredEnv; use super::super::test_support::{ test_paths, test_runtime_manifest, write_test_runtime_manifest, }; use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; + #[cfg(unix)] + use std::path::Path; /// Updating a next-layout manifest whose family is a group label (as /// `gfx125X-dcgpu` always is) must recover the exact arch this runtime was @@ -1242,4 +1322,141 @@ mod tests { let _ = fs::remove_dir_all(root); Ok(()) } + + /// The bug: a read-only look at a wheel runtime that records no usable Python, + /// on a host with none, went on to prepare one (download a managed `uv`, have + /// it install Python, save the path in the configuration). Driven here, each + /// against the same host: the update report, the JSON the dashboard reads, + /// the startup check, `runtime_update_check` itself, and + /// `apply_runtime_update` with `dry_run` (the preview of an apply, which takes + /// the check). Each must leave `uv` unrun and the configuration and managed + /// tools absent, and each must still reach the index (the connection to the + /// unreachable index is what each error names), so the absences are not a + /// check that stopped early. `runtime_update_plan` and a real + /// `apply_runtime_update` do prepare one on the same host, which is also what + /// shows the stand-in `uv` is reachable. That a `--dry-run` takes the check and + /// an apply the plan is pinned on every platform by + /// `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` in `update_cmd.rs`; + /// which function is the check is pinned only here and by scenario `update-10` + /// on Linux, and no test on Windows pins it. The Gherkin scenarios `update-09` + /// and `update-10` drive the report and the preview through the built binary. + #[cfg(unix)] + #[test] + fn the_update_checks_prepare_no_python_and_the_apply_plan_does() -> Result<()> { + use rocm_core::fake_executable::write_fake_executable; + + let _env_lock = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = test_paths("update-checks-prepare-no-python"); + + let marker = root.join("uv-was-run"); + let tools = root.join("tools"); + fs::create_dir_all(&tools)?; + let uv = tools.join("uv"); + write_fake_executable( + &uv, + format!("#!/bin/sh\necho \"$@\" >> '{}'\nexit 1\n", marker.display()), + )?; + let search = root.join("search"); + fs::create_dir_all(&search)?; + // Port 9 refuses the connection at once, so a check that gets past + // Python fails at the index without touching the network. + let unreachable_index = "http://127.0.0.1:9/"; + let _env = RestoredEnv::set(&[ + ("ROCM_CLI_UV_BINARY", Some(uv.as_path())), + ("ROCM_CLI_PYTHON", None), + ("ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", None), + ("ROCM_CLI_MANAGED_PYTHON_VERSION", None), + ("ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK", None), + ("ROCM_CLI_THEROCK_ALLOW_BASE_OVERRIDE", Some(Path::new("1"))), + ( + "ROCM_CLI_THEROCK_RELEASE_PIP_BASE", + Some(Path::new(unreachable_index)), + ), + ]); + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: vec![search], + ..PythonResolverEnv::from_process_env() + }); + + // The fixture's recorded interpreter does not exist, so the runtime + // records no usable Python. + let manifest = test_runtime_manifest("wheel-no-python", "therock-release:gfx120X-all", 1); + write_test_runtime_manifest(&paths, &manifest)?; + let manifests = load_runtime_manifests(&paths)?; + + let prepared_nothing = |what: &str| { + assert!(!marker.exists(), "{what} ran uv"); + assert!( + !paths.config_path().exists(), + "{what} saved a Python path in the configuration" + ); + assert!( + !rocm_core::managed_tools_dir(&paths.data_dir).exists(), + "{what} created the managed tools folder" + ); + }; + + let report = render_update_report(&paths)?; + assert!(report.contains("127.0.0.1:9"), "{report}"); + prepared_nothing("the update report"); + + let document = render_update_json(&paths, Some(1))?; + assert_eq!(document.runtimes[0].status, "error"); + assert!( + document.runtimes[0] + .message + .as_deref() + .is_some_and(|message| message.contains("127.0.0.1:9")), + "{document:?}" + ); + prepared_nothing("the update JSON"); + + let record = maybe_refresh_startup_update_check_at(&paths, None, 0)? + .expect("a registered runtime is checked at startup"); + assert!( + record + .message + .as_deref() + .is_some_and(|message| message.contains("127.0.0.1:9")), + "{record:?}" + ); + prepared_nothing("the startup check"); + + let error = runtime_update_check(&paths, &manifest, &manifests, Some(1)) + .expect_err("the index is unreachable") + .to_string(); + assert!(error.contains("127.0.0.1:9"), "{error}"); + prepared_nothing("the update check"); + + let mut config = rocm_core::RocmCliConfig::default(); + let preview = + crate::update_cmd::apply_runtime_update(&paths, &mut config, None, false, true) + .expect_err("the index is unreachable") + .to_string(); + assert!(preview.contains("127.0.0.1:9"), "{preview}"); + prepared_nothing("the --dry-run preview"); + + // Control: the plan an apply works from does reach `uv` on this host, and + // so does a real apply, which takes that plan. + assert!(runtime_update_plan(&paths, &manifest, &manifests, Some(1)).is_err()); + assert!( + marker.exists(), + "the stand-in uv is not reachable, so the checks above prove nothing" + ); + fs::remove_file(&marker)?; + assert!( + crate::update_cmd::apply_runtime_update(&paths, &mut config, None, false, false) + .is_err() + ); + assert!( + marker.exists(), + "a real apply did not take the plan that prepares a Python" + ); + + fs::remove_dir_all(&root).ok(); + Ok(()) + } } diff --git a/apps/rocm/src/update_cmd.rs b/apps/rocm/src/update_cmd.rs index 1b64a253c8..c329c90d9f 100644 --- a/apps/rocm/src/update_cmd.rs +++ b/apps/rocm/src/update_cmd.rs @@ -254,16 +254,61 @@ pub(crate) const fn update_should_preview_or_apply(apply: bool, dry_run: bool) - apply || dry_run } +/// Which planner each path takes is pinned in two places. The `--dry-run` choice, +/// the check and not the plan, is pinned on every platform by +/// `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` below, which runs +/// `apply_runtime_update_with`. That `runtime_update_check` is the check and +/// `runtime_update_plan` the plan, which the two arguments below cannot tell +/// apart by type, is pinned only on Unix: by +/// `the_update_checks_prepare_no_python_and_the_apply_plan_does` in +/// `therock/update.rs` and by scenario `update-10` on Linux. No test on Windows +/// pins that pairing. pub(crate) fn apply_runtime_update( paths: &AppPaths, config: &mut RocmCliConfig, runtime_selector: Option<&str>, activate: bool, dry_run: bool, +) -> Result { + apply_runtime_update_with( + paths, + config, + runtime_selector, + activate, + dry_run, + |source, manifests| therock::runtime_update_check(paths, source, manifests, None), + |source, manifests| therock::runtime_update_plan(paths, source, manifests, None), + ) +} + +/// The update flow with its two planners passed in. A `--dry-run` only previews, +/// so it takes `check`, which prepares nothing; a real apply takes `apply_plan`, +/// which prepares the Python the install that follows needs. Taking them as +/// arguments lets a test run the choice on every platform without a host that +/// has no Python. +fn apply_runtime_update_with( + paths: &AppPaths, + config: &mut RocmCliConfig, + runtime_selector: Option<&str>, + activate: bool, + dry_run: bool, + check: impl FnOnce( + &therock::InstalledRuntimeManifest, + &[therock::InstalledRuntimeManifest], + ) -> Result, + apply_plan: impl FnOnce( + &therock::InstalledRuntimeManifest, + &[therock::InstalledRuntimeManifest], + ) -> Result, ) -> Result { let manifests = therock::load_runtime_manifests(paths)?; let source = select_runtime_update_source(&manifests, config, runtime_selector)?; - let plan = therock::runtime_update_plan(paths, source, &manifests, None)?; + let planned = if dry_run { + check(source, &manifests) + } else { + apply_plan(source, &manifests) + }; + let plan = planned?; let mut output = String::new(); let _ = writeln!(output, "runtime update"); let _ = writeln!(output, " source_runtime_key: {}", source.runtime_key); @@ -289,6 +334,11 @@ pub(crate) fn apply_runtime_update( return Ok(output); } + // The plan's `python_note` is not printed here: the preview below prints its + // own `python_note:` from the decision a real install takes (scenario + // `update-10` asserts it), so a second line would say the same thing twice. + // A dry run that finds nothing newer returned above and prints neither; the + // plain `rocm update` report is where the check's note shows. if dry_run { let _ = writeln!(output, " mode: dry-run"); let install_plan = therock::install_sdk_for_update( @@ -440,6 +490,73 @@ mod tests { use crate::test_support::write_test_pip_runtime; use crate::tests::{test_paths, test_runtime_manifest_for_update}; + /// A `--dry-run` takes its plan from the check and an apply from the plan, + /// and calls only that one: the check must never be the one that prepares a + /// Python, and an apply must still get the plan that does. Both planners + /// report nothing newer, so the flow returns before it installs or previews + /// anything and the test needs no host without a Python, which runs it on + /// every platform. Which `therock` function is the check is pinned only on + /// Unix, by `the_update_checks_prepare_no_python_and_the_apply_plan_does` in + /// `therock/update.rs`, and by scenario `update-10`. + #[test] + fn a_dry_run_takes_the_check_and_an_apply_takes_the_plan() -> Result<()> { + let (root, paths) = test_paths("update-takes-check-or-plan"); + write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all", + "therock-release:gfx120X-all", + "7.13.0a20260416", + 1, + )?; + let calls = std::cell::RefCell::new(Vec::new()); + let planner = |name: &'static str| { + let calls = &calls; + move |source: &therock::InstalledRuntimeManifest, + _: &[therock::InstalledRuntimeManifest]| { + calls.borrow_mut().push(name); + Ok(therock::RuntimeUpdatePlan { + latest_version: source.version.clone(), + latest_source: String::new(), + format: source.format.clone(), + status: "up_to_date".to_owned(), + target_runtime_key: source.runtime_key.clone(), + device_target: None, + source_layout_generation: None, + repair_required: false, + update_available: false, + python_note: None, + }) + } + }; + let take = |dry_run: bool| -> Result<(String, Vec<&'static str>)> { + calls.borrow_mut().clear(); + let output = apply_runtime_update_with( + &paths, + &mut RocmCliConfig::default(), + None, + false, + dry_run, + planner("check"), + planner("plan"), + )?; + Ok((output, calls.borrow().clone())) + }; + let (output, taken) = take(true)?; + assert_eq!(taken, ["check"], "a --dry-run took the plan: {output}"); + assert!( + output.contains("result: no newer runtime found"), + "{output}" + ); + let (output, taken) = take(false)?; + assert_eq!(taken, ["plan"], "an apply took the check: {output}"); + assert!( + output.contains("result: no newer runtime found"), + "{output}" + ); + fs::remove_dir_all(root).ok(); + Ok(()) + } + #[test] fn render_update_text_reports_all_update_surfaces() -> Result<()> { let (root, paths) = test_paths("update-surfaces"); diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 0cf7d08d56..6e9e2f6ac9 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -208,15 +208,16 @@ pub const TELEMETRY_TOOL_NAMES: [&str; 4] = [ // stop has finished). `doctor`/`examine` can re-register the configured setup // runtime in the runtime registry when its entry is missing. `update_check` and // `install_sdk_dry_run` cache package-index metadata under the cache folder. -// `update_check` can also, on a host with no usable Python on PATH, download a -// managed `uv` and Python into the data folder and record that Python in the -// saved config; `install_sdk_dry_run` prepares no Python and saves no Python -// path: on such a host it reports the Python a real install would prepare. It -// fetches no `uv` either: a ROCm 10 preview runs a `uv` that is already -// installed to resolve the package versions and, with none, prints the lines -// that depend on them as not resolved, so it creates no `tools` folder in the -// data folder. (`update_check` still resolves with `uv` and can fetch it.) The -// boundary type +// Neither prepares a Python or saves a Python path: on a host with no usable +// Python on PATH they report the Python a real update or install would prepare +// (`update_check` runs `rocm update`, whose text report then carries a +// `python_note:` line saying so), and only a real apply or install, which these +// tools never run, prepares it. `install_sdk_dry_run` fetches no `uv` either: a +// ROCm 10 preview runs a `uv` that is already installed to resolve the package +// versions and, with none, prints the lines that depend on them as not resolved, +// so it creates no `tools` folder in the data folder. (`update_check` on a ROCm +// 10 or newer runtime still resolves with `uv` and can fetch the managed `uv` +// into the data folder, though never a Python.) The boundary type // (`SharedRocmToolExecutor`) is plain data — importing it does NOT pull // `rocm-core` into this crate; the `agent` module stays the sole `rig` namer. // --------------------------------------------------------------------------- diff --git a/docs/architecture.md b/docs/architecture.md index e7f079d9bf..326f0053d5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,7 +108,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. - [`therock/source.rs`](../apps/rocm/src/therock/source.rs) — full domain extraction, a child of `therock.rs` that depends only on `therock/version.rs` (split out of `therock.rs`): where an install reads from. `TheRockChannel` (release or nightly) and `SourceLayout` (the canonical stream, or ROCm 10's separately hosted next layout) are the two axes; `resolve_source` maps a pair to the `ResolvedSource` wheel-index and tarball-catalog bases, honouring a `ROCM_CLI_THEROCK_*_BASE` override only behind the explicit opt-in (`therock_base_override_allowed`, `select_base_override`, `env_override_base`); `select_source_layout`, `requested_source_layout` and `next_layout_requested` decide the layout from a pin; `RuntimeVersionSelector` is the version or build date a user pins (`pub(crate)`, re-exported by `therock.rs`). `FamilyResolution` lives here rather than in `therock/family.rs` because choosing the layout reads it; that keeps the dependency one-way, with `family.rs` building on this file. `TheRockChannel`, `SourceLayout`, `ResolvedSource` and `FamilyResolution` (with their methods and fields), `RuntimeVersionSelector`'s `describe` and `matches_version`, `resolve_source`, the three layout functions, and the `THEROCK_SOURCE_LAYOUT_GENERATION` and `THEROCK_NEXT_MIN_MAJOR` constants are `pub(super)` for `therock.rs` and its siblings; the base-override helpers and the other constants (the per-channel and next-layout base URLs, and the next layout's generation tag) are private to this file. - [`therock/family.rs`](../apps/rocm/src/therock/family.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` for `TheRockChannel` and `FamilyResolution` (split out of `therock.rs`): which package family a request targets. `resolve_family` picks it from `--family`, `ROCM_CLI_THEROCK_FAMILY`, a managed runtime or the host GPU, in that order, and refuses a GPU with no ROCm build (`unsupported_host_gpu_message`, `unsupported_requested_target_message`) instead of substituting another family; `family_override_or_recovered_arch` and `raw_arch_agreeing_with_family` recover the exact arch behind a grouped family; `family_resolution_hint` is the recovery text appended when no runtime is found. `resolve_family`, `family_override_or_recovered_arch` and `family_resolution_hint` are `pub(super)`; the rest is private. -- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. +- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. - [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/process.rs` and `therock/python.rs` (split out of `therock.rs`): asking an installed runtime about itself through its own interpreter. `probe_rocm_sdk_runtime` runs `ROCM_SDK_PROBE_SCRIPT` and parses what `rocm_sdk` reports into the `RocmSdkPythonProbe` that [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) owns and validates; `probe_runtime_devices` runs `RUNTIME_DEVICE_PROBE_SCRIPT` to count the devices the runtime's torch can open and whether one can run a kernel (`RuntimeDeviceProbe`); `probe_torch_alignment` reads the installed torch and the one an engine pins from distribution metadata without importing torch (`TorchAlignmentProbe`); and `split_local_version`, `requirement_pinned_version` and `install_pinned_package` are the torch-pin helpers [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) uses to put the SDK's torch back after an engine install. The `pub(crate)` items are re-exported by `therock.rs` for [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs); `probe_rocm_sdk_runtime_for_target`, which `install_wheel_runtime` calls with the device payload it just chose, is `pub(super)`. - [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. @@ -116,12 +116,12 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds only on `therock/source.rs` for `SourceLayout` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): who may fetch `uv` while a wheel stack is resolved. `UvAccess` says how far a resolution may go (`Acquire`, what a real install and `rocm update` pass, or `PresentOnly`, a preview's), `plan_version_resolution` turns that, the layout and whether a `uv` is present into a `VersionResolution` (scrape the indexes, compile with a `UvChoice`, or skip) without touching anything, and `uv_for_compile` hands the compile step the `uv` it runs, acquiring it only on `Acquire`, with the context a failed fetch has always carried. `UvPolicy` carries the access and the two real lookups (`find_uv_binary`, `ensure_uv_binary`) as closures so a test can count what a resolution asks for. Everything is `pub(super)` and read by `wheel.rs`; the state matrix over layout, access and presence lives in this module's tests. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. - [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) — full domain extraction, a leaf child of `therock.rs` (split out of `install_wheel_runtime`) that builds on `therock/python.rs` and `therock/resolve.rs` for the Python decision and the resolution it prints: the `sdk install` plan a wheel install prints, key by key. `WheelPlan` carries the facts, `write_wheel_plan` writes the lines a preview and a real install share, and `write_dry_run_tail` the lines only a preview adds (the `uv` commands it would run and the manifest path). `PlanStack` is the one place the plan differs: `Resolved` carries the package specs, runtime key, install folder and manifest path, and `NeedsUv` (a ROCm 10 preview on a host with no `uv`, see `UnresolvedPipRuntime` in `therock/resolve/wheel.rs`) prints those as `not resolved by this preview` and adds the `resolution_note:` line, so one writer serves both and a line the plan gains appears in both. `unresolved_wheel_preview` renders the second kind whole. `therock.rs` reads it through `pub(super)` items; it reads the provenance, host-note and `venv_python_path` helpers back from `therock.rs`. -- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests and on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for the startup-check record (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan` and `maybe_refresh_startup_update_check` are `pub(crate)` and re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. -- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. +- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests and on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for the startup-check record (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. +- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`, and `RestoredEnv`, which sets or removes process environment variables for one test and puts them back on drop, so a caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds one). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. - [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) — the chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run immediately and which need the user's approval first. It owns `ChatRocmCommandAction` (read-only, or approval with the titles the approval prompt shows) and `ChatToolApprovalRequest`, the validators (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `validate_required_chat_string`, `validate_optional_chat_integer`, `reject_control_characters_in_tool_arguments` (which refuses a model-supplied tool name or argument carrying a terminal control character, for every tool except `rocm_command`, whose argv `normalized_chat_rocm_command_args` screens entry by entry), `validate_serve_command_safety`, the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), and `validate_chat_rocm_command_safety`, which applies them to a `serve` argv and also refuses a system install folder (`chat_install_prefix_is_system`)), the classifiers (`chat_rocm_command_action`, `chat_rocm_command_action_from_args`, `chat_install_driver_action`, `canonicalize_chat_rocm_command`, `normalized_chat_rocm_command_args`, `chat_tool_call_is_read_only`), `chat_tool_approval_request`, and the readers that turn a tool call into its argv and one-line command (`rocm_chat_tool_requested_args`, `rocm_chat_tool_requested_command`, with `push_optional_json_cli_arg` and `json_string`). It moved verbatim from `chat.rs` with the tests that exercise only these items. It depends on [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `providers::ChatToolCall`, `service_launch::is_loopback_host`, `services_text::validate_service_id`, `shell_quote::has_terminal_control_character`, `therock::RuntimeVersionSelector` and `driver_install::host_install_driver_only_reports`, none of which imports `chat`, so `freeform_planner.rs` calls `validate_serve_command_safety` and `validate_chat_rocm_command_safety` here instead of through `chat`, and keeps no copy of the serve rules. `chat.rs`'s child modules call into it and `chat.rs` re-exports `validate_chat_tool_call`, `chat_tool_call_is_read_only` and `chat_tool_approval_request` (read by `dash_seam.rs`), and `ChatRocmCommandAction`, `chat_install_driver_action`, `chat_rocm_command_action_from_args` and `rocm_chat_tool_requested_args`, which only other modules' tests read as `crate::chat::` (`driver_plan.rs`, `system_packages.rs`). - [`uninstall.rs`](../apps/rocm/src/uninstall.rs) — mechanical relocation, owns types: `uninstall()`, the refusal of the hidden `--force` (`reject_force`, which `main.rs` calls from the `uninstall` dispatch arm), plus the installer `PATH` undo and running-executable deletion. The shared plan type and its file-removal helpers live in [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) below instead, because [`storage.rs`](../apps/rocm/src/storage.rs) reuses them too. The two modules depend on each other: `uninstall_plan.rs` reads this module's `pub(crate)` `PathEdit`, `PATH_EDIT_RECORD`, `plan_path_edits`, `plan_is_empty`, `removal_count` and `render_extra_plan`. - [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) — mechanical relocation, shares crate-visible types (Phase 6f, ROCMAI-212): the uninstall-plan types (`UninstallOptions`, `UninstallPlan`, `UninstallPlanEntry`), the `PlanAudience` a rendered plan is written for (a person at a terminal, a captured caller, or the assistant's preview), which decides what the dry-run footer says comes next, building the plan (`build_uninstall_plan`, `plan_installed_binaries`, and the installed-binary/shared-cache discovery helpers behind them), rendering it (`render_uninstall_dry_run`, which renders for the assistant, and `render_uninstall_plan`), the `[y/N]` confirmation prompt (`confirm_uninstall`), and the filesystem removal primitive both [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`storage.rs`](../apps/rocm/src/storage.rs) call to carry a plan out (`remove_path`, and the entry-resolution helpers behind it). Kept separate from `uninstall.rs` rather than folded into it, since `uninstall.rs`'s own doc comment and name both describe `uninstall()`'s exclusive logic (the installer `PATH` undo and running-executable deletion), while this module's plan/render/removal helpers are shared with `storage.rs`. `main.rs` (`UninstallOptions`), `uninstall.rs` (which also imports `PlanAudience` and picks it from `interactive_terminal`), `storage.rs`, `runtimes_cmd.rs`, `chat/mcp_bridge.rs` (which calls `render_uninstall_dry_run` and does not import `PlanAudience`), and [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) (Unix-only property tests, which render as `PlanAudience::Captured`) each import the subset of these `pub(crate)` types and helpers they need; see this module's own doc comment for which symbol each one uses. -- [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types (Phase 6f, ROCMAI-210): `rocm update`'s command handler (`update()`, the body of the `update` arm of `dispatch()`) and its rendering/activation logic — the read-only status report (`render_update_text`, `append_update_surfaces`), the predicate deciding whether `update` should route into the mutating path instead of that report (`update_should_preview_or_apply`), applying a runtime update (`apply_runtime_update`, `append_update_activate_summary`), and the update-source/installed-runtime pickers behind it (`select_runtime_update_source`, `select_installed_update_runtime`). `const ROLLBACK_RECOVERY_HINT` stays in `main.rs` as a shared crate-root constant, because callers outside this module also use it ([`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimesCommand::Activate` handler and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `render_sdk_install_success`); this module reaches it via its `use crate::{...};` import, the same way `gpu_policy.rs`'s `device_policy_name` stays in `main.rs`. `update()` is `pub(crate)` and called from [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` through a re-import (`use crate::update_cmd::update;`), and calls `update_should_preview_or_apply`, `apply_runtime_update` and `render_update_text` itself; `render_update_text` is also `pub(crate)` and read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the read-only `rocm update` handling), while `apply_runtime_update` and `update_should_preview_or_apply` keep the `pub(crate)` they had when `dispatch()` called them directly, though only `update()` calls them now; `select_runtime_update_source` is also `pub(crate)`, read from [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs)'s property tests via `crate::update_cmd::select_runtime_update_source`. `append_update_surfaces`, `append_update_activate_summary`, and `select_installed_update_runtime` have no callers outside this module and stay private. The cluster's regression tests live in `update_cmd.rs`'s own `mod tests`, reaching shared fixtures (`test_paths`, `test_runtime_manifest_for_update`, `write_test_pip_runtime`) through `crate::tests::`/`crate::test_support::` the same way other mechanically relocated modules do. +- [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types (Phase 6f, ROCMAI-210): `rocm update`'s command handler (`update()`, the body of the `update` arm of `dispatch()`) and its rendering/activation logic — the read-only status report (`render_update_text`, `append_update_surfaces`), the predicate deciding whether `update` should route into the mutating path instead of that report (`update_should_preview_or_apply`), applying a runtime update (`apply_runtime_update`, a thin wrapper that hands `apply_runtime_update_with` the check and the plan from `therock/update.rs`, so a unit test can run the choice between them on any platform; `append_update_activate_summary`), and the update-source/installed-runtime pickers behind it (`select_runtime_update_source`, `select_installed_update_runtime`). `const ROLLBACK_RECOVERY_HINT` stays in `main.rs` as a shared crate-root constant, because callers outside this module also use it ([`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimesCommand::Activate` handler and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `render_sdk_install_success`); this module reaches it via its `use crate::{...};` import, the same way `gpu_policy.rs`'s `device_policy_name` stays in `main.rs`. `update()` is `pub(crate)` and called from [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` through a re-import (`use crate::update_cmd::update;`), and calls `update_should_preview_or_apply`, `apply_runtime_update` and `render_update_text` itself; `render_update_text` is also `pub(crate)` and read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the read-only `rocm update` handling), while `apply_runtime_update` and `update_should_preview_or_apply` keep the `pub(crate)` they had when `dispatch()` called them directly, though only `update()` calls them now; `select_runtime_update_source` is also `pub(crate)`, read from [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs)'s property tests via `crate::update_cmd::select_runtime_update_source`. `append_update_surfaces`, `append_update_activate_summary`, and `select_installed_update_runtime` have no callers outside this module and stay private. The cluster's regression tests live in `update_cmd.rs`'s own `mod tests`, reaching shared fixtures (`test_paths`, `test_runtime_manifest_for_update`, `write_test_pip_runtime`) through `crate::tests::`/`crate::test_support::` the same way other mechanically relocated modules do. Further `apps/rocm` modules, not part of the `main.rs` split: diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 062ec8d8cc..f61b855ce8 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -178,6 +178,16 @@ Expected result: preview`. Run the real install (or any command that fetches `uv`), then the preview again, and it prints the complete plan; so does a preview with `ROCM_CLI_UV_BINARY` naming a `uv`. +- On the same host, with a wheel runtime registered whose manifest records no + usable Python, `rocm update` (also `--json`, `--dry-run`, and the check the + CLI runs at startup) still reports. The text report gives the runtime's + verdict and a `python_note:` line saying an update would use `uv` to install + the managed Python, which the check did not do. Afterwards the data folder has + no `tools` folder and the config folder has no `config.json`. That holds for a + canonical-layout runtime; for a ROCm 10 or newer runtime the check still + resolves the package versions with `uv` and can fetch the managed `uv` into the + data folder, though never a Python. `rocm update --apply` on the same host does + prepare the Python, since the install needs it. - With `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP=1`, or a `ROCM_CLI_MANAGED_PYTHON_VERSION` whose Python the layout does not accept (such as `3.13` for the canonical layout), on the same host the preview fails diff --git a/docs/testing.md b/docs/testing.md index a0d360b38b..488bfd0285 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -839,8 +839,8 @@ progress output and that `uv` was not run and no file was written. Beside it are `a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way`. The preview does still write its package-index cache under the cache folder. The `update_check` tool and the plain `rocm update` check (no `--apply`) are not -previews in this sense: they resolve with `uv` and can fetch it, and prepare a -managed Python too. +previews in this sense: on a ROCm 10 or newer runtime they resolve with `uv` and +can fetch it. They prepare no Python, though (see `update-09` and `update-10`). Then it verifies: @@ -2423,6 +2423,34 @@ cargo test -p rocm --bin rocm render_update_text_reports_all_update_surfaces surfaces honestly. `rocm update --apply` remains runtime-only until production metadata feeds exist for the other surfaces. +A check changes nothing, and that includes Python. Reading the index for a wheel +runtime needs the interpreter's wheel tag. A runtime that records a usable Python +supplies it. For one that does not, on a host with no usable Python, the check +used to download a managed `uv`, have it install Python and save that Python's +path in the config, only to ask it for the tag. The text report, `--json`, the +startup check that runs ahead of other commands, and the plan behind +`rocm update --apply --dry-run` now take the tag from the interpreter the layout +requires instead and prepare nothing; the text report adds a `python_note:` line +saying an update would use `uv` to install the managed Python, which the check did +not do. `--json` carries no such line, since its shape is the dashboard's +contract. `rocm update --apply` still prepares the Python, because the install +that follows needs it. Scenarios `update-09` (the report) and `update-10` +(`--dry-run`) check the note against the state it left, as `runtime-23` does for +the install preview: the recording `uv` was never run, and there is no +managed-tools folder and no saved config. They run on Linux; the entry points the +scenarios do not drive are covered by +`the_update_checks_prepare_no_python_and_the_apply_plan_does` in +[update.rs](../apps/rocm/src/therock/update.rs), which drives the report, the +JSON, the startup check, the check plan and `apply_runtime_update` with +`--dry-run`, with the plan an apply works from, and a real apply, as the controls +that show the stand-in `uv` is reachable. Which of the two plans a `--dry-run` and +an apply take is also pinned on every platform, Windows included, by +`a_dry_run_takes_the_check_and_an_apply_takes_the_plan` in +[update_cmd.rs](../apps/rocm/src/update_cmd.rs). Unlike the install preview, which fetches no +`uv`, the check on a ROCm 10 or newer runtime still resolves the package versions +with `uv pip compile` and can fetch the managed `uv`, though never a Python; the +scenarios above use the canonical layout, which needs no `uv`. + Runtime version-ordering tests: ```bash @@ -2430,6 +2458,13 @@ cargo test -p rocm --bin rocm version_proptests cargo xtask e2e -- -n 'update-0[78]' ``` +Update checks that must not prepare Python: + +```bash +cargo test -p rocm --bin rocm the_update_checks_prepare_no_python +cargo xtask e2e -- -n 'update-(09|10)' +``` + Where `rocm install sdk` and `rocm update` compare runtime versions, they compare them in one PEP 440 order over published version strings (`7.9` < `7.10.0`, `7.0.0b1` < `7.0.0rc1` < `7.0.0` < `7.0.0.post1`, `7.2.4.70204` above diff --git a/tests/e2e-cucumber/features/update.feature b/tests/e2e-cucumber/features/update.feature index 21ad0c1a35..078a27cfa2 100644 --- a/tests/e2e-cucumber/features/update.feature +++ b/tests/e2e-cucumber/features/update.feature @@ -92,3 +92,49 @@ Feature: Update report When the user checks for updates against that catalog Then the report calls the runtime the catalog spells differently up to date And the report offers no update for the four-component runtime that is ahead of the catalog + + # `rocm update` is a check: it reads the installed runtimes and the index and + # changes nothing. To tell which wheels fit a wheel runtime it needs the + # interpreter's tag, and on a host with no usable Python it used to go and get + # one: it downloaded a managed `uv`, had `uv` install Python and saved that + # Python's path in the configuration, all before printing the report. The same + # resolution runs for `rocm update --json` (the dashboard's check) and for the + # startup check that runs ahead of other commands, so a read-only look at the + # runtimes could prepare a Python. Now the check works the tag out from the + # interpreter the install would prepare, says it would prepare one, and + # prepares nothing. + # + # The report's note says the check prepared nothing, so the Then checks that + # note and the state together, as runtime-23 does for the install preview: the + # recording `uv` is reached only by going on to prepare a Python, so its log not + # existing means no preparation was attempted, and the managed tools folder and + # the configuration must be absent too. The first Then shows the check still got + # as far as a verdict, so the absences are not just a command that stopped + # early. `--json` and the startup check are pinned by the unit tests in + # `apps/rocm/src/therock/update.rs`. + # + # Linux only, for the same empty-`PATH` host as runtime-23. The canonical + # release index is served from a loopback fixture, so no network is needed. + @id:update-check-prepares-no-python @requires-os:linux + Scenario: update-09 - Checking for updates on a host with no usable Python prepares no Python + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And a registered wheel runtime older than the index with no recorded Python + When the user checks for updates against the pip index + Then the report offers the newer runtime and says it would prepare a managed Python + And the update check prepared no Python, as it says + + # The sibling for `--dry-run`, which promises to show what `--apply` would do + # and change nothing. Its plan step resolved the same way and prepared the + # Python before the preview was printed; the apply itself still prepares what it + # needs, which the unit tests keep apart from the check. + # + # Linux only, for the same empty-`PATH` host as update-09. + @id:update-dry-run-prepares-no-python @requires-os:linux + Scenario: update-10 - Previewing an update on a host with no usable Python prepares no Python + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And a registered wheel runtime older than the index with no recorded Python + When the user previews applying the update to that wheel runtime + Then the preview says a real install would prepare a managed Python + And the preview prepared no Python, as it says diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 9a3ee87d27..ed2d54a65d 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -502,6 +502,100 @@ async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) .expect("failed to write runtime manifest"); } +/// Registry key for the planted canonical wheel runtime below. +const OLDER_WHEEL_RUNTIME_KEY: &str = "release-wheel-gfx1200-7-9-0"; + +/// Plants a canonical-layout wheel runtime older than the release index the +/// fixture serves, whose manifest records no Python (a runtime registered before +/// the field was written, or whose recorded interpreter is gone). The update +/// check then has to find an interpreter for itself, which on the host the +/// recording-uv Given builds means preparing one. No `source_layout_generation` +/// is recorded, so the manifest reads as the canonical stream, as an old one does. +#[given("a registered wheel runtime older than the index with no recorded Python")] +async fn registered_older_wheel_runtime_without_python(world: &mut E2eWorld) { + let install_root = root(world).join("runtime-older-wheel"); + std::fs::create_dir_all(&install_root).expect("failed to create install root"); + let registry = root(world).join("data").join("runtimes").join("registry"); + std::fs::create_dir_all(®istry).expect("failed to create registry dir"); + let manifest = serde_json::to_string_pretty(&serde_json::json!({ + "runtime_key": OLDER_WHEEL_RUNTIME_KEY, + "runtime_id": format!("therock-release:{RAW_ARCH}"), + "channel": "release", + "format": "wheel", + "family": RAW_ARCH, + "family_source": "manual", + "version": "7.9.0", + "install_root": install_root, + "selected_artifact_url": "https://example.invalid/rocm", + "read_only": false, + "installed_at_unix_ms": 1_700_000_000_000u64, + })) + .expect("failed to serialize runtime manifest"); + std::fs::write( + registry.join(format!("{OLDER_WHEEL_RUNTIME_KEY}.json")), + manifest, + ) + .expect("failed to write runtime manifest"); +} + +#[when("the user checks for updates against the pip index")] +async fn check_updates_against_pip_index(world: &mut E2eWorld) { + preview_ok(world, &["update"]); +} + +#[when("the user previews applying the update to that wheel runtime")] +async fn preview_apply_update_to_older_wheel_runtime(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "update", + "--apply", + "--dry-run", + "--runtime", + OLDER_WHEEL_RUNTIME_KEY, + ], + ); +} + +/// The report reached a verdict (the runtime is behind the index) and says what +/// the update would do about Python, without a path that would be a guess. +#[then("the report offers the newer runtime and says it would prepare a managed Python")] +async fn report_offers_update_and_names_the_python_it_would_prepare(world: &mut E2eWorld) { + assert_contains( + world, + &format!("runtime {OLDER_WHEEL_RUNTIME_KEY} format=wheel"), + "the runtime line", + ); + assert_contains(world, "status=update_available", "the runtime's verdict"); + assert_contains( + world, + &format!("latest={CURRENT_ROCM_VERSION}"), + "the version the index publishes", + ); + assert_contains( + world, + &format!( + "python_note: no usable Python was found; updating would use uv to install managed \ + Python {CANONICAL_MANAGED_PYTHON}" + ), + "the note about the Python an update would prepare", + ); +} + +/// The check says it prepared no Python, and the state it left agrees. Claim and +/// filesystem are checked together: the note alone would pass with the bug +/// present, and so would empty folders alone if the check had stopped before it +/// got to Python. +#[then("the update check prepared no Python, as it says")] +async fn update_check_prepared_no_python(world: &mut E2eWorld) { + assert_contains( + world, + "which this check did not do", + "the note about what the check skipped", + ); + assert_no_python_prepared(world); +} + /// Makes the planted ROCm 10 runtime the active default, so a real install /// without consent reaches the non-interactive refusal: past every point where /// the plan is chosen and announced, but before `uv`, any download or any