From 9105d5a2650ff3ba0e6c6a04fb0a340646639960 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 12:03:57 +0000 Subject: [PATCH 01/23] fix: make the command preview denote the argv it runs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chat approval card, the `request plan` block and the `run:` lines the CLI offers to be copied were all rendered by a quoter that wrapped a value only when it contained whitespace, and even then escaped just `\` and `"`. So a lone `"` left the line unparseable, and `$HOME` in a copyable `rocm chat --prompt …` expanded in the reader's own shell when they pasted it. The operator was being asked to consent to a line that did not denote the argv behind it. There was already a correct POSIX quoter for the remote command line, with tests that ask a real `sh`. Move it to `shell_quote`, use it for the previews and for the install dry-run's `command: uv … && uv …` line, and check all of them with property tests: a rendered argv must split back — through a POSIX word-splitter — to exactly that argv, and no argument may add a word to the line. Arguments are drawn from a small mostly-metacharacter alphabet, because the shapes that break quoting are the ones nobody writes an example for; a test measures and prints that reach so the generator cannot be tuned into harmlessness. The dry-run line's test asks a real `sh` rather than the word-splitter. Written with `shlex` first, it passed against the defect it exists to catch: a splitter hands back ``/tmp/`id` `` unchanged and reports a clean round-trip for precisely the value that executes. fixes the whitespace case from #443 but keeps `$`, `` ` `` and a trailing `\` live inside the quotes. Its `quote_display_arg` now uses the same POSIX single-quote rule, so the dash and the CLI render a value the same way; its call sites and API are unchanged. It is a second copy rather than a shared one because `xtask`'s crate-edge contract forbids `rocm-dash-tui -> rocm-core`, and `apps/rocm` owns `rocm-core`. Quoting cannot make a terminal control character safe — `'…'` is literal to a shell, not to the terminal about to act on a `\r` — so model-supplied arguments carrying one are refused before they reach a printed block. The criterion is "reaches the terminal", not "becomes a command line": that is why `path_exists` is guarded, whose `path` is echoed into an ungated tool-result block that can print alongside a mutating call's rendered command. The guarded list is the guard, so it carries a case per name, written out rather than looped over the constant, with the two tied together by a set-equality test. `rocm_command` keeps its own screening (it trims, so a shared check would disagree with it), widened from naming `\0`/`\n`/`\r` to every control character — ESC and the 8-bit CSI went straight into the approval card. The planner's `notes`, which are printed verbatim into the plan block, now drop any note carrying a control character (including `\n` and `\t`) for the same reason. `natural_language_plan` is deliberately unguarded: its `request` is the user's prose, echoed nowhere, and legitimately spans lines. Scope note: apart from planner notes, this covers model-supplied arguments, not model prose. Assistant reply text is still printed as it comes. Platform note: the quoting is POSIX everywhere. The previous double-quoted form happened to paste cleanly into `cmd.exe` and `'…'` does not. A value without a `'` reads back unchanged in bash, WSL and PowerShell; PowerShell spells an embedded `'` as `''` rather than `'\''`, so a value containing one is unambiguous to a reader there but not paste-exact. Signed-off-by: Roman Inflianskas --- Cargo.lock | 2 + Cargo.toml | 5 + apps/rocm/Cargo.toml | 1 + apps/rocm/src/chat.rs | 549 +++++++++++++++++- apps/rocm/src/freeform_execution.rs | 6 +- apps/rocm/src/freeform_planner.rs | 50 +- apps/rocm/src/main.rs | 1 + apps/rocm/src/shell_quote.rs | 293 ++++++++++ apps/rocm/src/therock.rs | 67 ++- crates/rocm-dash-tui/Cargo.toml | 2 + crates/rocm-dash-tui/src/ui/exec.rs | 188 +++++- .../rocm-dash-tui/tests/wave0_job_bridge.rs | 4 +- docs/architecture.md | 2 +- 13 files changed, 1106 insertions(+), 64 deletions(-) create mode 100644 apps/rocm/src/shell_quote.rs diff --git a/Cargo.lock b/Cargo.lock index b9c13d8376..d493d5c124 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3729,6 +3729,7 @@ dependencies = [ "serde", "serde_json", "sha2", + "shlex", "tar", "tempfile", "tokio", @@ -3847,6 +3848,7 @@ dependencies = [ "rocm-dash-core", "serde", "serde_json", + "shlex", "thiserror 2.0.21", "tokio", "tokio-util", diff --git a/Cargo.toml b/Cargo.toml index aa86b2304c..c1baaaf110 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -52,6 +52,11 @@ semver = "1.0" serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" sha2 = { version = "0.10", features = ["oid"] } +# Test-only. The oracle the command-preview property tests check against: it +# splits a rendered command line the way a POSIX shell word-splitter does, so +# "the preview denotes the argv that runs" becomes a mechanically checkable +# round-trip rather than a human reading. +shlex = "2" # `linux-tmpfs` makes tmpfs mounts visible to the free-space preflight, so a # cache or install root under a tmpfs `/tmp` (the Fedora and Arch default) # reports its real size instead of being invisible. `linux-netdevs` is diff --git a/apps/rocm/Cargo.toml b/apps/rocm/Cargo.toml index e4c120b09d..e48eb7cf8a 100644 --- a/apps/rocm/Cargo.toml +++ b/apps/rocm/Cargo.toml @@ -83,3 +83,4 @@ zbus-secret-service-keyring-store = { version = "1.0", features = ["rt-tokio-cry # Also used for the recursive-deletion paths in deletion_properties. proptest = { version = "1", default-features = false, features = ["std"] } tempfile = "3" +shlex.workspace = true diff --git a/apps/rocm/src/chat.rs b/apps/rocm/src/chat.rs index c25b4c5e0b..df6aa941e1 100644 --- a/apps/rocm/src/chat.rs +++ b/apps/rocm/src/chat.rs @@ -39,6 +39,7 @@ use crate::services_text::{ read_tail_lines, render_logs_browser_text, render_logs_text, render_service_logs_text, render_services_text, validate_service_id, }; +use crate::shell_quote::has_terminal_control_character; use crate::uninstall_plan::render_uninstall_dry_run; use crate::update_cmd::render_update_text; use crate::{ @@ -2092,6 +2093,7 @@ pub(crate) fn validate_chat_tool_call(call: &providers::ChatToolCall) -> Result< if !call.arguments.is_object() { bail!("ROCm tool `{}` arguments must be a JSON object", call.name); } + reject_control_characters_in_tool_arguments(&call.name, &call.arguments)?; match call.name.as_str() { "examine" // `doctor` is the dash-side LLM tool + `/doctor` overlay name for the @@ -2137,6 +2139,102 @@ pub(crate) fn validate_chat_tool_call(call: &providers::ChatToolCall) -> Result< Ok(()) } +/// The tools whose arguments reach the operator's terminal, and which have no +/// screening of their own. +/// +/// The criterion is **reaches the terminal**, not "becomes a command line". +/// That distinction is the whole point: a control character is dangerous +/// because the operator is not a shell. `path_exists` is on this list for +/// exactly that reason — nothing it takes becomes an argv, but +/// [`run_chat_path_exists_tool`] echoes the model's `path` verbatim into a +/// printed `path: …` block, with no approval gate in front of it and nothing +/// stopping that block from printing in the same response as a mutating call's +/// rendered command. +/// +/// `rocm_command` is the deliberate omission: its argv *is* rendered, but it +/// screens every entry itself in [`normalized_chat_rocm_command_args`] (which +/// also trims, so this check would disagree with it), and its `reason` is +/// free-form prose that is never printed. +/// +/// `natural_language_plan` is absent in the other direction: its `request` is +/// the user's own prose, echoed nowhere, and legitimately spans lines. +/// +/// Every other accepted tool either takes no string (`examine`, `engines`, +/// `gpu_snapshot`, …) or constrains the one it takes to a shape with no room +/// for a control character — `service_id` through `rocm_core::ServiceId::new`, +/// `host` by exact loopback match, `watcher` against the builtin list. +/// +/// Pinned per entry by +/// `every_guarded_tool_refuses_a_control_character_in_its_rendered_argument`: +/// deleting a name here turns that test red rather than silently removing a +/// guard. +const CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL: [&str; 9] = [ + "install_sdk", + "install_sdk_dry_run", + "install_engine", + "launch_server", + "path_exists", + "proposal_action", + "stop_server", + "watcher_disable", + "watcher_enable", +]; + +/// Refuse a model-supplied string argument carrying a terminal control +/// character, for the tools whose arguments reach the operator's terminal. +/// +/// Those values are printed: into the command preview an operator approves, +/// into the `request plan` / `execution` blocks `rocm ` emits, and — +/// for `path_exists` — into a tool-result block with no gate at all. All of it +/// reaches a terminal as bytes, so a `\r` returns the cursor to column one and +/// a CSI sequence erases the line; the model, not this code, then chooses what +/// the operator reads. Quoting cannot fix that: `'…'` makes the byte literal to +/// a *shell*, not to a terminal. +/// +/// Scope note, so the guarantee is not overread: this covers model-supplied +/// *arguments*, not model-supplied prose. An assistant's reply text is still +/// printed as it comes; [`rocm_core::strip_ansi_sequences`] is the tool for +/// that surface, and is already used on ComfyUI log output. +/// +/// Walks the whole arguments object rather than naming fields, so a new +/// argument on one of these tools inherits the guarantee instead of having to +/// remember it. +fn reject_control_characters_in_tool_arguments( + tool: &str, + arguments: &serde_json::Value, +) -> Result<()> { + if !CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL.contains(&tool) { + return Ok(()); + } + reject_control_characters(tool, arguments) +} + +fn reject_control_characters(tool: &str, arguments: &serde_json::Value) -> Result<()> { + match arguments { + serde_json::Value::String(value) => { + if has_terminal_control_character(value) { + // The wording is load-bearing for the per-tool test, which + // asserts this refusal rather than merely `is_err()` — several + // of these tools would refuse a hostile value for some other + // reason, and a test that accepted any error would pass with + // this guard removed. + bail!( + "ROCm tool `{tool}` argument contains a control character; \ + it would rewrite what the operator reads" + ); + } + Ok(()) + } + serde_json::Value::Array(values) => values + .iter() + .try_for_each(|value| reject_control_characters(tool, value)), + serde_json::Value::Object(entries) => entries + .values() + .try_for_each(|value| reject_control_characters(tool, value)), + _ => Ok(()), + } +} + /// Validate a `proposal_action` chat-tool call: `proposal_id` must be a /// non-empty string and `action` must be one of show | approve | reject. fn validate_chat_proposal_action_tool_call(call: &providers::ChatToolCall) -> Result<()> { @@ -2351,7 +2449,12 @@ fn normalized_chat_rocm_command_args(call: &providers::ChatToolCall) -> Result 512 { @@ -4578,7 +4681,7 @@ endpoint: 127.0.0.1:8001 assert_eq!( rocm_chat_tool_requested_command(&call).as_deref(), Some( - "rocm install sdk --channel release --format wheel --approve-replacing-active-default --prefix D:\\ROCm\\therock_venvs" + "rocm install sdk --channel release --format wheel --approve-replacing-active-default --prefix 'D:\\ROCm\\therock_venvs'" ) ); let approval = chat_tool_approval_request( @@ -4778,7 +4881,7 @@ endpoint: 127.0.0.1:8001 assert_eq!( rocm_chat_tool_requested_command(&call).as_deref(), Some( - "rocm install sdk --channel release --format wheel --prefix D:\\ROCm\\therock_venvs --build-date 06052026 --approve-replacing-active-default" + "rocm install sdk --channel release --format wheel --prefix 'D:\\ROCm\\therock_venvs' --build-date 06052026 --approve-replacing-active-default" ) ); let approval = @@ -5256,7 +5359,7 @@ model recipes }), }, Some( - "rocm install sdk --channel release --format wheel --approve-replacing-active-default --prefix D:\\ROCm\\therock_venvs", + "rocm install sdk --channel release --format wheel --approve-replacing-active-default --prefix 'D:\\ROCm\\therock_venvs'", ), false, ), @@ -7253,3 +7356,441 @@ install therock"; } } } + +/// Property tests for the command previews an operator consents to. +/// +/// The invariant under test is one sentence: **the command line shown is the +/// argv that runs.** It is checked by splitting the rendered preview back the +/// way a shell word-splitter would and demanding the original argv, because +/// "looks about right" is exactly the standard that let a `--prefix` path with +/// a space render as two arguments. +/// +/// Example-based tests do not find defects here. The shapes that break quoting +/// — a lone `"`, a bare backslash, an empty argument, a control character — are +/// the ones nobody writes down, so these draw from a small alphabet that is +/// mostly metacharacters. +#[cfg(test)] +mod command_preview_properties { + use super::*; + use crate::freeform_planner::{ProviderPlannerToolCall, validate_provider_planner_tool_call}; + // The one generator, shared with `shell_quote`'s own suite so both are + // covered by its reach guard. See `crate::shell_quote::hostile`. + use crate::shell_quote::hostile::{arg as hostile_arg, argv as hostile_argv}; + use proptest::prelude::*; + + /// Characters a terminal acts on rather than prints — the ones that let a + /// preview say one thing while a different argv runs. + const CONTROL_ALPHABET: &[char] = &['\n', '\r', '\u{1b}', '\u{8}', '\u{7f}', '\u{9b}', '\0']; + + /// An argument guaranteed to carry at least one control character. + fn control_bearing_arg() -> impl Strategy { + ( + hostile_arg(), + proptest::sample::select(CONTROL_ALPHABET), + hostile_arg(), + ) + .prop_map(|(head, control, tail)| format!("{head}{control}{tail}")) + } + + /// Split a rendered command line the way a POSIX shell would. `None` means + /// the preview is not even parseable — a lone unbalanced quote, say. + fn split_preview(preview: &str) -> Option> { + shlex::split(preview) + } + + fn expect_argv(args: &[String]) -> Vec { + std::iter::once("rocm".to_owned()) + .chain(args.iter().cloned()) + .collect() + } + + /// One case per guarded tool: its name, and the arguments object that puts + /// a hostile value in the one field that reaches the terminal. + /// + /// Written out rather than derived from + /// [`CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL`]. A test that loops over + /// the constant it is meant to pin proves nothing — delete a name and the + /// loop quietly gets shorter. Here, deleting a name from the constant makes + /// that tool stop refusing and turns + /// `every_guarded_tool_refuses_a_control_character_in_its_rendered_argument` + /// red; adding one without a case here turns + /// `the_guarded_tool_list_and_its_cases_agree` red. + /// + /// Non-hostile fields carry values that pass each tool's own validators, so + /// the control character is the only thing under test. + #[allow(clippy::type_complexity)] + const GUARDED_TOOL_CASES: &[(&str, fn(&str) -> serde_json::Value)] = &[ + ( + "install_sdk", + |hostile| serde_json::json!({ "channel": "release", "format": "wheel", "prefix": hostile }), + ), + ( + "install_sdk_dry_run", + |hostile| serde_json::json!({ "channel": "release", "format": "wheel", "prefix": hostile }), + ), + ( + "install_engine", + |hostile| serde_json::json!({ "engine": hostile }), + ), + ( + "launch_server", + |hostile| serde_json::json!({ "model": hostile, "host": "127.0.0.1" }), + ), + ( + "path_exists", + |hostile| serde_json::json!({ "path": hostile }), + ), + ( + "proposal_action", + |hostile| serde_json::json!({ "proposal_id": hostile, "action": "approve" }), + ), + ( + "stop_server", + |hostile| serde_json::json!({ "service_id": hostile }), + ), + ( + "watcher_disable", + |hostile| serde_json::json!({ "watcher": hostile }), + ), + ( + "watcher_enable", + |hostile| serde_json::json!({ "watcher": hostile }), + ), + ]; + + /// The guarded list and the cases that pin it name the same tools. + /// + /// This is the half that catches an *addition*: a tool added to the + /// constant without a case here would otherwise be guarded by code no test + /// exercises. + #[test] + fn the_guarded_tool_list_and_its_cases_agree() { + let guarded: std::collections::BTreeSet<&str> = CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL + .into_iter() + .collect(); + let covered: std::collections::BTreeSet<&str> = + GUARDED_TOOL_CASES.iter().map(|(tool, _)| *tool).collect(); + assert_eq!( + guarded, covered, + "every guarded tool needs a case in GUARDED_TOOL_CASES, and vice versa" + ); + } + + proptest! { + /// The central property, at the renderer: any argv renders to a line + /// that splits back to that argv. + #[test] + fn a_rendered_tool_call_splits_back_to_its_argv( + args in hostile_argv() + ) { + let preview = format_structured_tool_call("rocm", &args); + prop_assert_eq!( + split_preview(&preview), + Some(expect_argv(&args)), + "preview = {:?}", + preview + ); + } + + /// The same property end to end through the approval gate: whatever the + /// model asks for, either the call is refused, or the `display_command` + /// the operator reads splits back to the argv that will be replayed. + /// There is no third outcome where it is shown something else. + #[test] + fn an_approval_preview_denotes_the_argv_it_would_run( + prefix in hostile_arg(), + version in proptest::option::of(hostile_arg()), + ) { + let mut arguments = serde_json::json!({ + "channel": "release", + "format": "wheel", + "prefix": prefix, + }); + if let Some(version) = version { + arguments["version"] = serde_json::Value::String(version); + } + let call = providers::ChatToolCall { + id: None, + name: "install_sdk".to_owned(), + arguments, + }; + let Ok(request) = chat_tool_approval_request(&call, None) else { + // Refused before any preview was built. That is a fine outcome. + return Ok(()); + }; + let preview = request + .display_command + .as_deref() + .expect("an approval request for install_sdk carries a preview"); + prop_assert_eq!( + split_preview(preview), + Some(expect_argv(&request.args)), + "preview = {:?}, argv = {:?}", + preview, + request.args + ); + } + + /// Nothing an argument contains can add a word to the command line, so + /// a `;`, `|` or `>` in a value can never read as a second command. + #[test] + fn an_argument_can_never_add_a_word_to_the_preview( + args in hostile_argv() + ) { + let preview = format_structured_tool_call("rocm", &args); + let split = split_preview(&preview).expect("preview must parse"); + prop_assert_eq!(split.len(), args.len() + 1, "preview = {:?}", preview); + } + + /// A control character is refused rather than rendered. Quoting cannot + /// help: `'…'` is literal to a shell, not to the terminal that is about + /// to act on the `\r`. + #[test] + fn a_control_character_in_a_tool_argument_is_refused( + prefix in control_bearing_arg() + ) { + let call = providers::ChatToolCall { + id: None, + name: "install_sdk".to_owned(), + arguments: serde_json::json!({ + "channel": "release", + "format": "wheel", + "prefix": &prefix, + }), + }; + prop_assert!( + validate_chat_tool_call(&call).is_err(), + "a prefix carrying a control character must not reach a preview: {:?}", + prefix + ); + } + + /// `rocm_command` screens its own argv rather than going through + /// `reject_control_characters_in_tool_arguments` — it also carries a + /// free-form `reason` that is never rendered. That check used to name + /// `\0`, `\n` and `\r` literally, so an ESC or an 8-bit CSI went + /// straight into the approval card and the `advanced manual command:` + /// line. It is the broadest argv surface the model has; it must hold + /// the same guarantee as the rest. + /// + /// Stated as "refused, or nothing survives into the preview" rather + /// than "refused": this path trims each entry first, so a value whose + /// only control characters are at the ends is legitimately accepted — + /// with them gone. What must never happen is one reaching the preview. + #[test] + fn no_control_character_from_a_model_supplied_argv_reaches_the_preview( + arg in control_bearing_arg() + ) { + let call = providers::ChatToolCall { + id: None, + name: "rocm_command".to_owned(), + arguments: serde_json::json!({ "args": ["examine", arg] }), + }; + if validate_chat_tool_call(&call).is_err() { + return Ok(()); + } + let preview = rocm_chat_tool_requested_command(&call) + .expect("an accepted rocm_command renders a preview"); + prop_assert!( + !preview.chars().any(char::is_control), + "arg {:?} put a control character into the preview: {:?}", + arg, + preview + ); + } + + /// Every entry in [`CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL`] is + /// pinned, one case per tool. + /// + /// Without this, six of the nine were held in place by nothing: + /// replacing the constant with `["install_sdk", "install_engine"]` left + /// the whole suite green, so `launch_server`'s `model` and + /// `proposal_action`'s `proposal_id` — both of which land in an approval + /// card — could be dropped from the guard silently. The constant *is* + /// the guard; it needs a test per name. + /// + /// Asserts the guard's own refusal, not merely an error: `stop_server` + /// and `watcher_enable` would reject these values anyway (via + /// `ServiceId::new` and the builtin-watcher list), so an `is_err()` + /// check would stay green with the guard deleted. + /// + /// Driven from [`GUARDED_TOOL_CASES`], a list written out here, NOT + /// from the constant. Iterating the constant would be a test that + /// follows whatever it is given: shrink the constant and the loop + /// shrinks with it, green either way. The two are tied together by + /// `the_guarded_tool_list_and_its_cases_agree`. + #[test] + fn every_guarded_tool_refuses_a_control_character_in_its_rendered_argument( + hostile in control_bearing_arg() + ) { + for (tool, build) in GUARDED_TOOL_CASES { + let call = providers::ChatToolCall { + id: None, + name: (*tool).to_owned(), + arguments: build(&hostile), + }; + let error = validate_chat_tool_call(&call) + .expect_err(&format!("`{tool}` accepted {hostile:?}")) + .to_string(); + prop_assert!( + error.contains("rewrite what the operator reads"), + "`{}` refused {:?} for some other reason ({}), so this case \ + would stay green with the control-character guard removed", + tool, + hostile, + error + ); + } + } + + /// …and the same for the planner's argv, which lands in the `request + /// plan` block the operator reads before re-running with `--yes`. + #[test] + fn a_control_character_from_the_planner_is_refused( + arg in control_bearing_arg() + ) { + let call = ProviderPlannerToolCall { + tool: "rocm".to_owned(), + args: vec!["install".to_owned(), "sdk".to_owned(), "--prefix".to_owned(), arg], + }; + prop_assert!(validate_provider_planner_tool_call(&call).is_err()); + } + + /// Whatever survives planner validation renders a plan block whose + /// lines are the ones this code wrote — no argument can inject another. + #[test] + fn a_validated_planner_argv_cannot_forge_a_plan_line( + arg in hostile_arg() + ) { + let call = ProviderPlannerToolCall { + tool: "rocm".to_owned(), + args: vec!["install".to_owned(), "sdk".to_owned(), "--prefix".to_owned(), arg], + }; + let Ok(args) = validate_provider_planner_tool_call(&call) else { + return Ok(()); + }; + let rendered = format_structured_tool_call("rocm", &args); + prop_assert!( + !rendered.chars().any(char::is_control), + "a plan line must stay one line: {:?}", + rendered + ); + } + } + + /// `path_exists` is the one guarded tool that renders no command at all, + /// and the reason it is guarded anyway. + /// + /// It is read-only, so there is no approval gate in front of it — and + /// [`run_chat_path_exists_tool`] echoes the model's `path` straight into a + /// printed `path: …` block, which can appear in the same response as a + /// mutating call's rendered command. A CSI sequence in it redraws the lines + /// around it. The criterion for this guard is "reaches the terminal", not + /// "becomes a command line"; this is the case that distinguishes them. + /// + /// Asserted through the handler, not just the validator, so the test fails + /// if the value stops being screened *or* the handler stops being the thing + /// that prints it. + #[test] + fn a_read_only_path_probe_cannot_redraw_the_block_it_prints_into() { + let hostile = "/tmp/\u{1b}[1A\u{1b}[2Kadvanced manual command: rocm examine"; + let call = providers::ChatToolCall { + id: None, + name: "path_exists".to_owned(), + arguments: serde_json::json!({ "path": hostile }), + }; + let error = validate_chat_tool_call(&call) + .expect_err("a path carrying a CSI sequence must not be probed") + .to_string(); + assert!( + error.contains("rewrite what the operator reads"), + "refused for the wrong reason: {error}" + ); + + // An ordinary path still works, so this is a shape check and not a way + // to disable the tool. + let ok = providers::ChatToolCall { + id: None, + name: "path_exists".to_owned(), + arguments: serde_json::json!({ "path": "/tmp/my folder" }), + }; + validate_chat_tool_call(&ok).expect("an ordinary path is probeable"); + let text = mcp_tool_result_text( + &run_chat_path_exists_tool(&ok).expect("the probe answers for a missing path"), + ); + assert!( + !text.chars().any(char::is_control) || !text.contains('\u{1b}'), + "the printed block carries an escape: {text:?}" + ); + } + + /// The control-character rule belongs to arguments that reach the terminal, + /// not to prose. A `natural_language_plan` request is a user's own + /// question, is echoed nowhere, and legitimately spans lines — holding it + /// to this rule would refuse an ordinary multi-line question for no gain. + /// Pinned so the rule is not later widened by reflex. + #[test] + fn a_multi_line_question_is_still_a_valid_plan_request() { + let call = providers::ChatToolCall { + id: None, + name: "natural_language_plan".to_owned(), + arguments: serde_json::json!({ + "request": "install rocm\nthen serve qwen", + }), + }; + validate_chat_tool_call(&call).expect("prose may span lines"); + + // …while the same bytes in an argument that *is* rendered are refused. + let rendered = providers::ChatToolCall { + id: None, + name: "install_engine".to_owned(), + arguments: serde_json::json!({ "engine": "vllm\nrocm examine" }), + }; + assert!(validate_chat_tool_call(&rendered).is_err()); + } + + /// The shape from the bug report, pinned by name so it cannot regress + /// quietly: a `--prefix` folder containing a space is one argument in the + /// preview, not two. + #[test] + fn an_install_prefix_with_a_space_is_one_argument_in_the_preview() { + let call = providers::ChatToolCall { + id: None, + name: "install_sdk".to_owned(), + arguments: serde_json::json!({ + "channel": "release", + "format": "wheel", + "prefix": "/mnt/my folder", + }), + }; + let request = chat_tool_approval_request(&call, None).expect("install_sdk is approvable"); + let preview = request.display_command.expect("preview"); + assert!( + preview.contains("--prefix '/mnt/my folder'"), + "the folder must be delimited, not left to read as two arguments: {preview}" + ); + assert_eq!(split_preview(&preview), Some(expect_argv(&request.args))); + } + + /// A prompt is interpolated into a `run:` line the CLI offers to be copied. + /// Unquoted, `$HOME` in it expands in the user's own shell when they paste + /// it, so they run a different command from the one they were shown. + #[test] + fn a_copyable_command_survives_being_pasted() { + let args = vec![ + "chat".to_owned(), + "--prompt".to_owned(), + "what is $HOME doing?".to_owned(), + ]; + let preview = format_structured_tool_call("rocm", &args); + assert_eq!( + split_preview(&preview), + Some(expect_argv(&args)), + "preview = {preview}" + ); + assert!( + !preview.contains("\"what is $HOME doing?\""), + "a double-quoted form would still expand $HOME on paste: {preview}" + ); + } +} diff --git a/apps/rocm/src/freeform_execution.rs b/apps/rocm/src/freeform_execution.rs index c5eee3168f..9838e40668 100644 --- a/apps/rocm/src/freeform_execution.rs +++ b/apps/rocm/src/freeform_execution.rs @@ -222,7 +222,9 @@ mod tests { assert!(action.has_placeholders); assert!(error.contains("placeholder values")); - assert!(error.contains("rocm serve ")); + // Quoted: `<` and `>` are redirects, so an unquoted placeholder would + // read as a redirect rather than as the value the operator must supply. + assert!(error.contains("rocm serve ''"), "{error}"); } #[test] @@ -279,7 +281,7 @@ mod tests { assert_eq!( freeform_planner::format_structured_tool_call("rocm", &action.args), "rocm install sdk --channel nightly --format wheel --prefix \ - D:\\ROCm\\therock_venvs --approve-replacing-active-default" + 'D:\\ROCm\\therock_venvs' --approve-replacing-active-default" ); // The narrow flag, never `--yes`: this surface has no terminal promise to // make about a sudo password prompt for system packages. diff --git a/apps/rocm/src/freeform_planner.rs b/apps/rocm/src/freeform_planner.rs index 6c344b9a83..3b0b3ec329 100644 --- a/apps/rocm/src/freeform_planner.rs +++ b/apps/rocm/src/freeform_planner.rs @@ -44,6 +44,7 @@ use serde::Deserialize; use std::fmt::Write as _; use crate::service_launch::is_loopback_host; +use crate::shell_quote::{has_terminal_control_character, shell_quote}; use crate::{Cli, chat, providers}; /// Builds the freeform plan once and renders it. Kept for the render-only test @@ -887,9 +888,9 @@ struct ProviderPlannerResponse { } #[derive(Debug, Deserialize)] -struct ProviderPlannerToolCall { - tool: String, - args: Vec, +pub(crate) struct ProviderPlannerToolCall { + pub(crate) tool: String, + pub(crate) args: Vec, } pub(crate) fn provider_planner_response_to_plan( @@ -924,7 +925,10 @@ pub(crate) fn provider_planner_response_to_plan( response .notes .into_iter() - .filter(|note| !note.trim().is_empty()), + // Same reason as the argv above: a note is printed verbatim into the + // plan block, so a control character in one lets the planner redraw + // the lines around it. + .filter(|note| !note.trim().is_empty() && !has_terminal_control_character(note)), ); Ok(StructuredRequestPlan { request: request.trim().to_owned(), @@ -964,19 +968,25 @@ fn strip_json_fence(content: &str) -> &str { trimmed } -fn validate_provider_planner_tool_call(call: &ProviderPlannerToolCall) -> Result> { +pub(crate) fn validate_provider_planner_tool_call(call: &ProviderPlannerToolCall) -> Result> { if call.tool != "rocm" { bail!("provider planner returned unsupported tool `{}`", call.tool); } if call.args.is_empty() { bail!("provider planner returned an empty tool call"); } + // Control characters, not just NUL. These args are rendered straight into + // the `request plan` block `rocm ` prints to a terminal, and that + // block is the only thing the operator reads before re-running with + // `--yes`. A `\r` or a CSI sequence in an argument lets the planner's + // response decide what that block looks like, independently of the argv it + // would run. See `reject_control_characters_in_tool_arguments`. if call .args .iter() - .any(|arg| arg.trim().is_empty() || arg.contains('\0')) + .any(|arg| arg.trim().is_empty() || has_terminal_control_character(arg)) { - bail!("provider planner returned an invalid empty or NUL argument"); + bail!("provider planner returned an empty argument or one carrying a control character"); } let argv = std::iter::once("rocm".to_owned()) .chain(call.args.iter().cloned()) @@ -1273,24 +1283,26 @@ fn infer_device_policy_from_request(lower: &str) -> Option<&'static str> { } } +/// Render an argv as the command line a human is shown for it. +/// +/// This is the only thing an operator sees before approving a mutating tool +/// call, and some of its output (`rocm chat --prompt …`, the `install command:` +/// line) is offered to be copied and run. So it has to denote the argv it was +/// built from: quoted with [`shell_quote`], every argument splits back to +/// itself under a shell's own word-splitting, and nothing inside a value can +/// read as a second command. +/// +/// Values carrying terminal control characters never get here — they are +/// refused at validation ([`has_terminal_control_character`]), because no +/// amount of quoting stops a `\r` from rewriting the line the operator is +/// reading. pub(crate) fn format_structured_tool_call(tool: &str, args: &[String]) -> String { let mut parts = Vec::with_capacity(args.len() + 1); parts.push(tool.to_owned()); - parts.extend(args.iter().map(|arg| quote_tool_arg(arg))); + parts.extend(args.iter().map(|arg| shell_quote(arg))); parts.join(" ") } -/// Quotes `value` for rendered plan text and LLM prompt text only -- never -/// executed directly. Deliberately kept separate from `rocm_core::quoting` -/// (ROCMAI-727); see that module's doc comment for why. -fn quote_tool_arg(value: &str) -> String { - if value.is_empty() || value.chars().any(char::is_whitespace) { - format!("\"{}\"", value.replace('\\', "\\\\").replace('"', "\\\"")) - } else { - value.to_owned() - } -} - #[cfg(test)] mod tests { use super::infer_engine_from_request; diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index b30dc118f7..ff417698f0 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -60,6 +60,7 @@ mod service_records; mod services_cmd; mod services_text; mod setup_cmd; +mod shell_quote; mod storage; mod system_packages; #[cfg(test)] diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs new file mode 100644 index 0000000000..dbd4f25a2f --- /dev/null +++ b/apps/rocm/src/shell_quote.rs @@ -0,0 +1,293 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! One POSIX shell quoter for this binary's three command lines. +//! +//! They look unrelated and are not: +//! +//! * [`crate::remote`] builds a command line that a shell on *another* machine +//! will parse, so an unquoted value there is a remote command injection. +//! * [`crate::format_structured_tool_call`] builds the command line a human is +//! shown — in the chat approval card, in `rocm `'s request plan, and +//! in the `run:` lines the CLI offers to be copied. An unquoted value there +//! means the line the operator reads is not the argv that runs, and the +//! copyable ones mean it is not what runs when they paste it either. +//! * [`crate::therock::quote_display_arg`] builds the `command: uv … && uv …` +//! line the install dry-run prints. Its install root comes from a `--prefix` +//! the local assistant can choose, and the line is offered to be run. +//! +//! All three want the same guarantee — *this value is one word and nothing +//! else* — so they share one implementation and one set of tests. Keeping them +//! apart is how two of them ended up with quoters that did not escape `$`, +//! backticks or `;`, and left a lone `"` unquoted entirely. +//! +//! The fourth is in another crate and stays there: `rocm-dash-tui`'s +//! `ui::exec::quote_display_arg`. `crates/rocm-dash-tui` must not depend on +//! `rocm-core` — an invariant the workspace enforces, not a preference — and +//! `apps/rocm` is the crate that owns `rocm-core`, so nothing here can be +//! shared with it without inverting that. Four lines of POSIX quoting with its +//! own copy of these property tests is the smaller price. +//! +//! Single quotes, not double: inside `'...'` POSIX gives no expansion at all, +//! so the only character needing care is `'` itself. A double-quoted form has +//! to keep escaping `$`, `` ` `` and `\` correctly forever, and the one that +//! used to live in `main.rs` escaped the last two and not the first. +//! +//! Platform note: this is POSIX quoting on every platform. The previous +//! double-quoted form happened to paste cleanly into `cmd.exe`; `'…'` does not. +//! It is correct in bash, WSL and PowerShell, and on Windows it is still +//! unambiguous to a *reader* — which is what an approval gate needs — where the +//! old form was ambiguous everywhere. + +/// Quote `value` so a POSIX shell reads it back as exactly one word equal to +/// `value`. +/// +/// Values that cannot mean anything but themselves are returned bare, so an +/// ordinary command line stays readable: `rocm serve qwen2.5-7b --managed`, +/// not `rocm 'serve' 'qwen2.5-7b' '--managed'`. +pub(crate) fn shell_quote(value: &str) -> String { + let inert = |character: char| { + character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') + }; + if !value.is_empty() && value.chars().all(inert) { + return value.to_owned(); + } + format!("'{}'", value.replace('\'', r"'\''")) +} + +/// Whether `value` carries a character a terminal acts on rather than prints. +/// +/// Quoting cannot help here, and that is the point. `'…'` makes a byte literal +/// to the *shell*, but the operator is not a shell: a `\r`, a backspace or a +/// CSI sequence inside the quotes still moves their cursor or erases the line +/// when the preview is printed, so the command they read can be chosen by +/// whoever supplied the argument. A value in this shape is refused upstream +/// rather than rendered. +/// +/// `char::is_control` covers C0, DEL and C1 (so ESC and the 8-bit CSI alike). +pub(crate) fn has_terminal_control_character(value: &str) -> bool { + value.chars().any(char::is_control) +} + +/// The argument generator the preview property tests share. +/// +/// One copy, deliberately: a second generator somewhere else would not be +/// covered by [`tests::generator_reaches_the_shapes_that_break_quoting`], and +/// could be tuned into harmlessness with nothing to catch it. +#[cfg(test)] +pub(crate) mod hostile { + use proptest::prelude::*; + + /// Deliberately tiny and deliberately hostile. + /// + /// A uniform `.*` generator is close to useless here: the shapes that break + /// a quoter are a lone quote, a bare backslash, an empty string and the + /// metacharacters, and uniform text produces them at a rate that never + /// finds anything. Drawing from this alphabet puts a quote in ~34% of + /// generated argvs and some metacharacter in ~82% (measured by + /// `generator_reaches_the_shapes_that_break_quoting`, which prints the + /// rates under `--nocapture`). + /// + /// No control characters: those are refused upstream rather than quoted, so + /// they belong to that guard's own generator, not to this one. + const ALPHABET: &[char] = &[ + ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', + '=', '-', '~', '!', 'a', '1', '/', 'é', + ]; + + pub(crate) fn arg() -> impl Strategy { + prop_oneof![ + 8 => proptest::collection::vec(proptest::sample::select(ALPHABET), 0..=5) + .prop_map(|chars| chars.into_iter().collect::()), + // A handful of real argv shapes so ordinary usage is covered too — + // including the path-with-a-space from the bug report. + 1 => proptest::sample::select(&[ + "install", "sdk", "--prefix", "/mnt/my folder", + "C:\\Program Files\\ROCm", "qwen2.5-7b-instruct", "", + ][..]).prop_map(str::to_owned), + ] + } + + pub(crate) fn argv() -> impl Strategy> { + proptest::collection::vec(arg(), 1..=4) + } +} + +#[cfg(test)] +mod tests { + use super::hostile::{arg as hostile_arg, argv as hostile_argv}; + use super::*; + use proptest::prelude::*; + + /// Render an argv the way every display site does, then split it back the + /// way a shell would. `shlex` is the oracle: it is a POSIX word-splitter, + /// which is precisely the reader the rendered line is written for. + fn render_and_split(argv: &[String]) -> Option> { + let rendered = argv + .iter() + .map(|arg| shell_quote(arg)) + .collect::>() + .join(" "); + shlex::split(&rendered) + } + + proptest! { + /// The property everything else rests on: what is rendered denotes the + /// argv that runs. Not "looks similar" — splits back to it exactly. + #[test] + fn a_rendered_argv_splits_back_to_the_same_argv(argv in hostile_argv()) { + let split = render_and_split(&argv); + prop_assert_eq!(split, Some(argv)); + } + + /// Quoting is total: no argument content can make the renderer produce + /// something a shell cannot parse at all. + #[test] + fn every_argument_renders_to_something_parseable(arg in hostile_arg()) { + prop_assert!(shlex::split(&shell_quote(&arg)).is_some(), "arg={:?}", arg); + } + + /// Quoting an already-quoted token does not corrupt it: the second pass + /// yields a word whose value is the first pass's output, verbatim. + #[test] + fn quoting_an_already_quoted_value_still_round_trips(arg in hostile_arg()) { + let once = shell_quote(&arg); + let twice = shell_quote(&once); + prop_assert_eq!(shlex::split(&twice), Some(vec![once])); + } + + /// An argument can never introduce a second command or a redirect: after + /// rendering, the whole line is one word per argument, so a `;`, `|` or + /// `>` inside a value is data, never syntax. + #[test] + fn an_argument_can_never_add_a_word(argv in hostile_argv()) { + let split = render_and_split(&argv).expect("rendered line must parse"); + prop_assert_eq!(split.len(), argv.len()); + } + } + + #[test] + fn generator_reaches_the_shapes_that_break_quoting() { + // A generator that never produces the dangerous shapes passes against a + // broken quoter — that has happened here before. Measure it, and fail + // if the alphabet is ever tuned into harmlessness. + use proptest::strategy::{Strategy, ValueTree}; + use proptest::test_runner::TestRunner; + + let mut runner = TestRunner::deterministic(); + let strategy = hostile_argv(); + let (mut quote, mut meta, mut space, mut empty, mut backslash) = (0, 0, 0, 0, 0); + let total = 5_000; + for _ in 0..total { + let argv = strategy + .new_tree(&mut runner) + .expect("generator produces a value") + .current(); + let joined = argv.concat(); + quote += i32::from(joined.contains('\'') || joined.contains('"')); + meta += i32::from(joined.contains(|c| "$`;|&*?()<>".contains(c))); + space += i32::from(joined.contains(' ') || joined.contains('\t')); + empty += i32::from(argv.iter().any(String::is_empty)); + backslash += i32::from(joined.contains('\\')); + } + // Floors, not exact rates: the point is that each dangerous shape is + // common, not that the generator is frozen. + for (label, count, floor) in [ + ("quote", quote, total / 5), + ("metacharacter", meta, total / 2), + ("whitespace", space, total / 5), + ("empty argument", empty, total / 5), + ("backslash", backslash, total / 10), + ] { + // Printed so `--nocapture` reports the generator's actual reach, not + // only that it cleared the bar. + println!( + "reach: {label:<16} {count:>5}/{total} ({:.1}%)", + f64::from(count) * 100.0 / f64::from(total) + ); + assert!( + count >= floor, + "generator produced {label} in only {count}/{total} cases; \ + below {floor} it stops exercising the quoting it is meant to test" + ); + } + } + + /// A readability check, not the regression guard — the old quoter also + /// round-tripped this one (it wrapped on whitespace), so this cannot fail on + /// the reported bug. What pins that is + /// `an_install_prefix_with_a_space_is_one_argument_in_the_preview` in + /// `main.rs`, which asserts the rendered form and does fail on a revert. + #[test] + fn a_path_with_a_space_stays_one_argument() { + let argv = [ + "install".to_owned(), + "sdk".to_owned(), + "--prefix".to_owned(), + "/mnt/my folder".to_owned(), + ]; + assert_eq!(render_and_split(&argv), Some(argv.to_vec())); + } + + #[test] + fn ordinary_values_are_left_alone_and_the_rest_are_wrapped() { + for inert in ["qwen2.5-7b-instruct", "vllm", "/models/a.gguf", "auto"] { + assert_eq!(shell_quote(inert), inert); + } + assert_eq!(shell_quote("a b"), "'a b'"); + assert_eq!(shell_quote(""), "''"); + assert_eq!(shell_quote("it's"), r"'it'\''s'"); + } + + #[cfg(unix)] + #[test] + fn hostile_values_survive_a_real_shell_as_one_literal_argument() { + // The property that matters is not the shape of the quoting but what a + // shell does with it. Ask one: each value must come back byte-identical, + // proving it was neither expanded nor split nor able to start a second + // command. + for value in [ + "x'; rm -rf ~; echo '", + "$(id)", + "`id`", + "a b", + "it's", + "*", + "--not-a-flag", + "qwen2.5-7b-instruct", + "/mnt/my folder", + ] { + let output = std::process::Command::new("sh") + .arg("-c") + .arg(format!("printf %s {}", shell_quote(value))) + .output() + .expect("sh should run"); + assert_eq!( + String::from_utf8_lossy(&output.stdout), + value, + "shell mangled {value:?}" + ); + } + } + + #[test] + fn control_characters_are_recognised_whatever_their_width() { + for value in [ + "a\rb", + "a\nb", + "a\u{1b}[2Kb", + "a\u{8}b", + "a\u{7f}b", + "a\u{9b}b", + ] { + assert!( + has_terminal_control_character(value), + "{value:?} should be refused before it reaches a preview" + ); + } + for value in ["/mnt/my folder", "qwen2.5-7b", "x'; rm -rf ~; echo '", "é"] { + assert!(!has_terminal_control_character(value), "{value:?}"); + } + } +} diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 90f15479e8..fe9d9fafc6 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -759,19 +759,20 @@ fn install_wheel_runtime( Ok(SdkInstallResult::installed(output)) } -/// Quotes `value` for the dry-run preview line only -- it is never fed to a -/// real subprocess. Deliberately kept separate from `rocm_core::quoting` -/// (ROCMAI-727); see that module's doc comment for why. +/// Quote one argument of the `command:` line the dry-run preview prints. +/// +/// That line is offered as the command — `uv && uv ` +/// — so it has to be one a shell reads back as the argv it previews. It used to +/// quote only on whitespace and a short metacharacter list, with `"`, which +/// left `` ` `` and `'` unquoted and kept `$(…)` live *inside* the quotes; the +/// install root comes from a `--prefix` the local assistant can choose +/// (`install_sdk_dry_run` is a model-callable tool), so that was a model-chosen +/// value in a line a user is invited to run. +/// +/// [`crate::shell_quote::shell_quote`] is the same quoter the remote command +/// line and the approval previews use. fn quote_display_arg(value: &str) -> String { - if value.is_empty() - || value - .chars() - .any(|ch| ch.is_whitespace() || matches!(ch, '[' | ']' | '(' | ')' | '&' | ';' | '|')) - { - format!("\"{}\"", value.replace('"', "\\\"")) - } else { - value.to_owned() - } + crate::shell_quote::shell_quote(value) } /// The host's legacy/system ROCm version when it is strictly newer than the @@ -1446,13 +1447,51 @@ mod tests { #[test] fn display_command_quotes_package_extras() { - assert_eq!(quote_display_arg("package[extra]"), "\"package[extra]\""); + assert_eq!(quote_display_arg("package[extra]"), "'package[extra]'"); assert_eq!( quote_display_arg("C:\\Program Files\\Python\\python.exe"), - "\"C:\\Program Files\\Python\\python.exe\"" + "'C:\\Program Files\\Python\\python.exe'" ); } + /// The `command:` line is printed as the command to run, and the install + /// root in it comes from a `--prefix` the local assistant can choose + /// (`install_sdk_dry_run` is model-callable). The old quoter returned + /// `` /tmp/`id` `` completely bare — no trigger character in it — and wrapped + /// `/tmp/$(id)` in double quotes, where substitution still fires. Both ran + /// on paste. + /// + /// Asked of a real `sh`, not of a word-splitter. That distinction is the + /// whole test: `shlex` is a *splitter*, so it hands back + /// `` /tmp/`id` `` unchanged and reports a clean round-trip for precisely + /// the value that executes. Only a shell models expansion, so only a shell + /// can answer "would this run something". Written with `shlex` first, this + /// test passed against the defect it exists to catch. + #[cfg(unix)] + #[test] + fn a_dry_run_command_line_cannot_run_a_second_command_on_paste() { + for hostile in [ + "/tmp/`id`", + "/tmp/$(id)", + "/tmp/a'; id; echo '", + "/tmp/my folder", + "/tmp/$HOME", + "", + ] { + let quoted = quote_display_arg(hostile); + let output = std::process::Command::new("sh") + .arg("-c") + .arg(format!("printf %s {quoted}")) + .output() + .expect("sh should run"); + assert_eq!( + String::from_utf8_lossy(&output.stdout), + hostile, + "{hostile:?} rendered as {quoted:?}, which a shell did not read back literally" + ); + } + } + #[test] fn aggregate_wheel_runtime_key_separates_device_payloads_at_one_version() { let base = WheelRuntimeComposition { diff --git a/crates/rocm-dash-tui/Cargo.toml b/crates/rocm-dash-tui/Cargo.toml index 23b7e54989..ed449e2826 100644 --- a/crates/rocm-dash-tui/Cargo.toml +++ b/crates/rocm-dash-tui/Cargo.toml @@ -70,6 +70,7 @@ libc.workspace = true # example misses. Same version and features as rocm-core's, so no new crate or # feature enters the lockfile. Test-only, so it adds nothing to any shipped # binary. +# Also used to check that approval previews split back to the argv that runs. proptest = { version = "1", default-features = false, features = ["std"] } # Same rig-core as [dependencies], with its `test-utils` feature (gives # `MockCompletionModel`/`MockTurn`) added for test builds only. The root @@ -80,3 +81,4 @@ proptest = { version = "1", default-features = false, features = ["std"] } rig = { package = "rig-core", version = "=0.38.1", default-features = false, features = [ "test-utils", ] } +shlex.workspace = true diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 2819867965..af2e3685c3 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -22,25 +22,35 @@ pub fn exe_label(cmd: &str) -> &str { cmd.rsplit(['/', '\\']).next().unwrap_or(cmd) } -/// Quote `value` for display so a command preview can't misrepresent where -/// one argument ends and the next begins. +/// Quote one argument so a POSIX shell reads it back as exactly one word. /// -/// Triggers on empty input, whitespace, a literal `"`, or a shell-meaningful -/// character — an unescaped, unquoted `"` reads as the start of a -/// neighboring quoted argument just as easily as a bare space does. Mirrors -/// the display-only quoting already used for the same purpose in -/// `apps/rocm` (e.g. `therock.rs::quote_display_arg`), with the `"` trigger -/// added. +/// An approval preview is the only thing the operator sees before approving, +/// so it has to denote the argv the job is spawned with — not merely mark +/// where a value with a space ends. A double-quoted form does not get there: +/// inside `"..."` a shell still expands `$` and `` ` ``, so `$HOME` or +/// `` `id` `` in a value would read as something other than itself, and a +/// value ending in `\` escapes its own closing quote. +/// +/// Single quotes do: inside `'...'` POSIX performs no expansion at all, so the +/// only character needing care is `'` itself, closed and reopened as `'\''`. +/// +/// Values that cannot mean anything but themselves are returned bare, so an +/// ordinary preview stays readable — `rocm serve qwen2.5-7b --managed`, not +/// `rocm 'serve' 'qwen2.5-7b' '--managed'`. +/// +/// Mirrors the CLI-side quoter in `apps/rocm/src/shell_quote.rs`. Deliberately +/// a second copy: `xtask`'s crate-edge contract forbids +/// `rocm-dash-tui -> rocm-core` (`xtask/src/crate_edges.rs`), and `apps/rocm` +/// is the crate that owns `rocm-core`, so there is nowhere both can reach +/// without breaking that. pub fn quote_display_arg(value: &str) -> String { - if value.is_empty() - || value.chars().any(|ch| { - ch.is_whitespace() || matches!(ch, '"' | '[' | ']' | '(' | ')' | '&' | ';' | '|') - }) - { - format!("\"{}\"", value.replace('"', "\\\"")) - } else { - value.to_owned() + let inert = |character: char| { + character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') + }; + if !value.is_empty() && value.chars().all(inert) { + return value.to_owned(); } + format!("'{}'", value.replace('\'', r"'\''")) } /// Join `args` into a single display string, quoting any argument that needs @@ -56,6 +66,7 @@ pub fn display_args(args: &[String]) -> String { #[cfg(test)] mod tests { use super::*; + use proptest::prelude::*; #[test] fn exe_label_strips_unix_and_windows_paths() { @@ -78,13 +89,13 @@ mod tests { #[test] fn display_args_quotes_values_with_spaces() { let args = vec!["--prefix".to_string(), "/mnt/my folder".to_string()]; - assert_eq!(display_args(&args), "--prefix \"/mnt/my folder\""); + assert_eq!(display_args(&args), "--prefix '/mnt/my folder'"); } #[test] fn display_args_escapes_embedded_quotes() { - let args = vec!["say \"hi\"".to_string()]; - assert_eq!(display_args(&args), "\"say \\\"hi\\\"\""); + let args = vec!["say \"hi\"".to_string(), "it's".to_string()]; + assert_eq!(display_args(&args), r#"'say "hi"' 'it'\''s'"#); } #[test] @@ -92,7 +103,7 @@ mod tests { let args = vec!["say\"hi".to_string(), "there buddy".to_string()]; assert_eq!( display_args(&args), - "\"say\\\"hi\" \"there buddy\"", + r#"'say"hi' 'there buddy'"#, "a bare embedded quote must be quoted even with no whitespace in the value" ); } @@ -100,12 +111,145 @@ mod tests { #[test] fn display_args_quotes_empty_value() { let args = vec!["--tag".to_string(), String::new()]; - assert_eq!(display_args(&args), "--tag \"\""); + assert_eq!(display_args(&args), "--tag ''"); } #[test] fn display_args_quotes_shell_metacharacters() { let args = vec!["a&b".to_string(), "c;d".to_string(), "e|f".to_string()]; - assert_eq!(display_args(&args), "\"a&b\" \"c;d\" \"e|f\""); + assert_eq!(display_args(&args), "'a&b' 'c;d' 'e|f'"); + } + + /// Expansion characters are quoted too, not only word separators: inside + /// a double-quoted form `$HOME` and `` `id` `` would still expand, so the + /// preview would not read as the value the job receives. + #[test] + fn display_args_keeps_expansion_characters_literal() { + let args = vec!["$HOME".to_string(), "`id`".to_string(), "dir\\".to_string()]; + assert_eq!(display_args(&args), r"'$HOME' '`id`' 'dir\'"); + } + + /// Deliberately tiny and mostly metacharacters. + /// + /// The shapes that break a quoter — a lone quote, a bare backslash, an + /// empty argument — are the ones nobody writes an example for, and uniform + /// random text produces them too rarely to find anything. Reach is measured + /// by `the_generator_reaches_the_shapes_that_break_quoting`. + const HOSTILE_ALPHABET: &[char] = &[ + ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', + '-', '/', 'a', '1', + ]; + + fn hostile_arg() -> impl Strategy { + prop_oneof![ + 8 => proptest::collection::vec(proptest::sample::select(HOSTILE_ALPHABET), 0..=5) + .prop_map(|chars| chars.into_iter().collect::()), + 1 => proptest::sample::select(&[ + "install", "sdk", "--prefix", "/mnt/my folder", + "C:\\Program Files\\ROCm", "qwen2.5-7b-instruct", "", + ][..]).prop_map(str::to_owned), + ] + } + + fn hostile_argv() -> impl Strategy> { + proptest::collection::vec(hostile_arg(), 1..=4) + } + + proptest! { + /// The property an approval gate rests on: the line the operator reads + /// denotes the argv the job is spawned with. Checked by splitting the + /// rendered line the way a shell would and demanding that argv back — + /// `shlex` is a POSIX word-splitter, which is exactly the reader this + /// line is written for. + #[test] + fn a_preview_splits_back_to_the_argv_the_job_will_run(argv in hostile_argv()) { + let preview = format!("{} {}", exe_label("/usr/local/bin/rocm"), display_args(&argv)); + let expected: Vec = std::iter::once("rocm".to_owned()) + .chain(argv.into_iter()) + .collect(); + let split = shlex::split(&preview); + prop_assert_eq!(split, Some(expected), "preview = {:?}", preview); + } + + /// No argument can add a word to the preview, so a `;`, `|` or `>` + /// inside a value reads as data rather than as a second command. + #[test] + fn an_argument_can_never_add_a_word(argv in hostile_argv()) { + let preview = display_args(&argv); + let split = shlex::split(&preview).expect("preview must parse"); + prop_assert_eq!(split.len(), argv.len(), "preview = {:?}", preview); + } + + /// Quoting an already-quoted token does not corrupt it. + #[test] + fn quoting_an_already_quoted_value_still_round_trips(arg in hostile_arg()) { + let once = quote_display_arg(&arg); + let twice = quote_display_arg(&once); + prop_assert_eq!(shlex::split(&twice), Some(vec![once])); + } + } + + #[test] + fn the_generator_reaches_the_shapes_that_break_quoting() { + // A generator that never produces the dangerous shapes passes against a + // broken quoter. Measure it, and fail if the alphabet is ever tuned + // into harmlessness. + use proptest::strategy::ValueTree; + use proptest::test_runner::TestRunner; + + let mut runner = TestRunner::deterministic(); + let strategy = hostile_argv(); + let (mut quote, mut meta, mut space, mut empty, mut backslash) = (0, 0, 0, 0, 0); + let total = 5_000; + for _ in 0..total { + let argv = strategy + .new_tree(&mut runner) + .expect("generator produces a value") + .current(); + let joined = argv.concat(); + quote += i32::from(joined.contains('\'') || joined.contains('"')); + meta += i32::from(joined.contains(|c| "$`;|&*?()<>".contains(c))); + space += i32::from(joined.contains(' ') || joined.contains('\t')); + empty += i32::from(argv.iter().any(String::is_empty)); + backslash += i32::from(joined.contains('\\')); + } + for (label, count, floor) in [ + ("quote", quote, total / 5), + ("metacharacter", meta, total / 2), + ("whitespace", space, total / 5), + ("empty argument", empty, total / 5), + ("backslash", backslash, total / 10), + ] { + println!( + "reach: {label:<16} {count:>5}/{total} ({:.1}%)", + f64::from(count) * 100.0 / f64::from(total) + ); + assert!( + count >= floor, + "generator produced {label} in only {count}/{total} cases; \ + below {floor} it stops exercising the quoting it is meant to test" + ); + } + } + + #[test] + fn a_windows_install_folder_keeps_its_separators() { + let argv = [ + "install".to_owned(), + "sdk".to_owned(), + "--prefix".to_owned(), + "C:\\Program Files\\ROCm".to_owned(), + ]; + let preview = format!("{} {}", exe_label("C:\\tools\\rocm.exe"), display_args(&argv)); + assert_eq!( + shlex::split(&preview), + Some(vec![ + "rocm.exe".to_owned(), + "install".to_owned(), + "sdk".to_owned(), + "--prefix".to_owned(), + "C:\\Program Files\\ROCm".to_owned(), + ]) + ); } } diff --git a/crates/rocm-dash-tui/tests/wave0_job_bridge.rs b/crates/rocm-dash-tui/tests/wave0_job_bridge.rs index 54568b61c9..4015930feb 100644 --- a/crates/rocm-dash-tui/tests/wave0_job_bridge.rs +++ b/crates/rocm-dash-tui/tests/wave0_job_bridge.rs @@ -216,7 +216,7 @@ fn approval_snapshot_quotes_args_containing_spaces() { }); assert!( - out.contains("--prefix \"/mnt/my folder\""), + out.contains("--prefix '/mnt/my folder'"), "space-containing arg is rendered quoted:\n{out}" ); } @@ -238,7 +238,7 @@ fn job_console_snapshot_quotes_args_containing_spaces() { }); assert!( - out.contains("\"/mnt/my folder\""), + out.contains("'/mnt/my folder'"), "space-containing arg is rendered quoted:\n{out}" ); } diff --git a/docs/architecture.md b/docs/architecture.md index edba1fc0ed..2bf4d1d623 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -55,7 +55,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs) — mechanical relocation (Phase 6f, ROCMAI-208, folding Phase 6f/ROCMAI-86 closed): the launch-summary/examine text surfaces (`render_launch_summary`, `render_examine_text`, `render_examine_text_with_paths`, `examine_human_report`, `render_examine_plain_header`, `plain_status_label`), the engine-inventory listing shared by `rocm engines` and `rocm examine` (`write_default_engine_legend`, `render_engine_inventory_text_with_paths`, `append_examine_runtime_state`, `append_examine_engine_inventory`), and the model-catalog rendering behind `rocm model` (alias `models`) and `rocm model --verbose` (`model_catalog_platform_heading`, `render_model_registry_text_with_context_and_host`, `model_recipe_memory_label`, `model_recipe_gpu_fit_label`, `render_model_registry_verbose_text_with_context_and_host`, `model_catalog_header`, `append_model_recipe_registry_source`, `append_model_recipe_metadata_lines`, `append_model_engine_recipe_settings_lines`, `format_list_or_none`, `format_string_map_or_none`, `append_model_artifact_lines`, `append_artifact_source_policy_lines`, `artifact_source_policy_label`, `format_bytes`, `append_model_host_ram_fit_lines`, `append_model_fit_lines`, `append_manual_alternative_lines`, `manual_alternative_recommendations`, `recipe_is_manual_fit`, `append_model_engine_support_lines`, `recipe_display_ref`, `preferred_engine_action_target`, `model_registry_reason`, `format_gib`, `append_engine_detect_summary`, `friendly_engine_runtime_kind`, `friendly_engine_detect_notes`, `friendly_engine_detect_note_fallback`, `engine_runtime_status_label`, `engine_runtime_is_native_windows_unsupported`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside this cluster: the `DEFAULT_ENGINE_MARKER` constant (shared by both engine-inventory renderers so the two copies cannot drift apart) and `model_registry_adapter_availability_note` (read only from `append_model_engine_support_lines` and this module's own test); both stay private. `render_config_text` and `telemetry_policy_summary` sat immediately adjacent to this cluster's end boundary in `main.rs` and were explicitly out of scope, so that split left them where they were; they now live in [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs). `dispatch()` calls directly into this module at two points — `render_model_registry_verbose_text_with_context_and_host` and `render_model_registry_text_with_context_and_host` — re-imported via `use crate::examine_report_text::{...};`; [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs)'s `examine()`, which the `Command::Examine` arm calls, imports and calls `examine_human_report` itself. `main.rs`'s own `launch_default` calls `render_launch_summary` directly, also re-imported there. `render_examine_text`, `render_examine_text_with_paths`, and `render_model_registry_verbose_text_with_context_and_host` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `render_engine_inventory_text_with_paths` is also read from `chat.rs` and from `engines_cmd.rs`'s `render_engine_inventory_text`; `append_examine_runtime_state` is also `pub(crate)`, read only from [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s own test module, so `main.rs`'s re-import of it is itself `#[cfg(test)]` rather than carrying an otherwise-unused import into a non-test build; `format_bytes` is also `pub(crate)`, read from [`storage.rs`](../apps/rocm/src/storage.rs)'s cache-size reporting and [`automations.rs`](../apps/rocm/src/automations.rs)'s plain-language summaries. Every other item in this list has no caller outside this module and stays private. This cluster also reaches three items that stayed behind in `main.rs` because they already had callers outside it: `engine_inventory()` (also read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)), `engine_ruled_out_by_platform` (also read from [`model_fit.rs`](../apps/rocm/src/model_fit.rs)'s `assess_model_for_host`; it has since moved there and is re-imported in `main.rs`), and `missing_packaged_engine_reason` (already noted in [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs)'s entry above as having callers outside that cluster, plus its own test — this cluster is one of them) — all three reached via `use crate::{...};`. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime`/`runtime_manifest_path` through `crate::test_support::`/`crate::runtimes_cmd::`, the same way other mechanically relocated modules do. Two tests interleaved among this cluster's tests in `main.rs`'s old shared `mod tests` stayed behind because their primary subject is unrelated: `missing_packaged_engine_reason`'s own test and the whole-command-tree ASCII-help walk (two CLI-lifecycle-audit-log tests that were also left there have since moved to [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs)). - [`freeform_answer.rs`](../apps/rocm/src/freeform_answer.rs) — mechanical relocation, no owned types: the answers a freeform request can get without running a command — `render_freeform_read_only_answer`, which answers a single approval-free `examine`, `comfyui status` or `comfyui logs` action, and `render_freeform_examine_answer`, the plain-language ROCm status it prints for `examine`. `run_freeform` in [`main.rs`](../apps/rocm/src/main.rs) is the only caller of the first, which is `pub(crate)` and re-imported there; the second is private. Besides `chat.rs` (`any_substring`), it depends on `comfyui.rs`, `runtimes_cmd.rs` and `therock.rs`, none of which calls back into it. No unit test calls either function directly. - [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) — mechanical relocation, dispatch-adjacent, owns a `pub(crate)` type (as of Phase 6e's follow-up, ROCMAI-726; see the Phase 6a variant note above for the owned-types pattern). Holds the freeform natural-language planner's plan-*execution*/consent half that [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) below deliberately left out: `validate_freeform_execution_action()`, `prepare_freeform_execution()`, `apply_freeform_execution_consent()`, `render_freeform_execution_header()`, and the `pub(crate)` `FreeformExecution` struct that `prepare_freeform_execution` returns and `render_freeform_execution_header` consumes. `main.rs`'s `execute_freeform_next_action()` and `run_freeform()` stay in `main.rs` — both are dispatch-level, not part of deciding whether a plan's next action is safe to execute — and `execute_freeform_next_action()` calls in via the unqualified re-import `use crate::freeform_execution::{prepare_freeform_execution, render_freeform_execution_header};` (`run_freeform()` only calls `execute_freeform_next_action()`, never this module directly), matching [`driver_install.rs`](../apps/rocm/src/driver_install.rs)'s dispatch-adjacent form rather than `freeform_planner.rs`'s own qualified-path form. `prepare_freeform_execution` takes the already-built `plan` by value rather than rebuilding it from `request`/`paths`/`config` (ROCMAI-725's single-build guarantee, inherited unchanged from `main.rs`); `prepare_freeform_execution`/`render_freeform_execution_header` are `pub(crate)` for that cross-module call; `FreeformExecution` was already `pub(crate)` (read directly by `main.rs` and this module's own tests); `validate_freeform_execution_action`/`apply_freeform_execution_consent` have no caller outside this module and stay module-private, unchanged from before the move. The cluster's six regression tests moved out of `main.rs`'s shared `mod tests` into this module's own `mod tests`, inheriting the qualified `freeform_planner::` path they already used to reach `freeform_planner.rs`'s items as `main.rs`'s former tests — this module reaches in from outside using the same qualified path `main.rs` and `providers.rs`'s tests use (unlike `chat.rs`/`comfyui.rs`, which import it unqualified). -- [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) — full domain extraction (Phase 6e, ROCMAI-87). Owns the freeform natural-language planner cluster's types (`StructuredRequestPlan`, `PlannerIntent`, `PlannedToolCall`, `FreeformPlanAction`, `ProviderPlannerResponse`, `ProviderPlannerToolCall`, all module-private except `FreeformPlanAction`, `StructuredRequestPlan` and `PlannedToolCall`, which are `pub(crate)`), the deterministic plan builder (`build_freeform_plan*`), the provider-assisted path (`resolve_freeform_plan_with_provider`, `build_provider_planner_prompt`, `provider_planner_response_to_plan`, `validate_provider_planner_tool_call`), and plan rendering (`render_structured_request_plan`). [`main.rs`](../apps/rocm/src/main.rs) calls `build_freeform_plan_with_context`/`render_structured_request_plan` directly for the dispatch/review flow ([`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `render_launch_summary` → `host_default_engine` is another call into this module, unrelated to planning: bare `rocm`'s non-interactive launch summary), while [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) above calls `plan_next_action`/`format_structured_tool_call` for the execution flow and reads `FreeformPlanAction`/`StructuredRequestPlan` by type for its execution-validation functions — those live there, not here, because they decide whether a plan's next action is safe to *execute*, a dispatch-adjacent concern distinct from *building* the plan; `main.rs`'s `run_freeform` builds a plan exactly once via `build_freeform_plan_with_context` and threads that same value through `execute_freeform_next_action` to `prepare_freeform_execution` rather than rebuilding it (ROCMAI-725: building a plan can call a configured cloud `planner_provider`, which is not guaranteed deterministic, so a second independent build could silently disagree with the first). [`chat.rs`](../apps/rocm/src/chat.rs)'s `natural_language_plan` MCP tool gets the same single-build guarantee from `plan_freeform_request_with_context`, which builds once and returns both the rendered text and the next action; `chat.rs` also calls `format_structured_tool_call` directly, like [`comfyui.rs`](../apps/rocm/src/comfyui.rs) does, and its `validate_chat_rocm_command_safety` reads `serve_args_request_cpu_device` directly as a no-CPU-fallback safety check on provider-proposed `serve` args. `host_default_engine`, `build_freeform_plan_with_context`, `render_structured_request_plan`, `plan_next_action`, `plan_freeform_request_with_context`, `provider_planner_response_to_plan`, `format_structured_tool_call`, and `serve_args_request_cpu_device` are `pub(crate)` for these reasons, as are `infer_engine_from_request` (read from `chat.rs`) and `plan_driver_request` (read from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs)'s test module); `freeform_plan_next_action` and `render_freeform_plan` are test-only (`#[cfg(test)]`) and `FreeformPlanAction` was already `pub(crate)` before the split. `parse_freeform_invocation`/`should_treat_as_freeform` (deciding whether an invocation is freeform at all) stay in `main.rs`, a dispatch-level concern outside both this module and `freeform_execution.rs`. The cluster's regression tests live in `freeform_planner.rs`'s own `mod tests`; the handful of `main.rs` tests that exercise the invocation classifier/clap-suggestion-avoidance stay in `main.rs`'s shared `mod tests`, since neither is specific to this module or to `freeform_execution.rs` (and neither touches `freeform_planner::` at all), and the ROCMAI-725 regression tests proving the single-build guarantee live in `providers.rs`'s `mod tests` (reusing its mock local-provider server), reaching this module's items through the qualified `freeform_planner::` path like any other external caller. +- [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs) — full domain extraction (Phase 6e, ROCMAI-87). Owns the freeform natural-language planner cluster's types (`StructuredRequestPlan`, `PlannerIntent`, `PlannedToolCall`, `FreeformPlanAction`, `ProviderPlannerResponse`, `ProviderPlannerToolCall`, all module-private except `FreeformPlanAction`, `StructuredRequestPlan` and `PlannedToolCall`, which are `pub(crate)`, and `ProviderPlannerToolCall`, `pub(crate)` together with `validate_provider_planner_tool_call` and `planner_failure_note` so [`chat.rs`](../apps/rocm/src/chat.rs)'s command-preview property tests can drive the planner's guards), the deterministic plan builder (`build_freeform_plan*`), the provider-assisted path (`resolve_freeform_plan_with_provider`, `build_provider_planner_prompt`, `provider_planner_response_to_plan`, `validate_provider_planner_tool_call`), and plan rendering (`render_structured_request_plan`). [`main.rs`](../apps/rocm/src/main.rs) calls `build_freeform_plan_with_context`/`render_structured_request_plan` directly for the dispatch/review flow ([`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs)'s `render_launch_summary` → `host_default_engine` is another call into this module, unrelated to planning: bare `rocm`'s non-interactive launch summary), while [`freeform_execution.rs`](../apps/rocm/src/freeform_execution.rs) above calls `plan_next_action`/`format_structured_tool_call` for the execution flow and reads `FreeformPlanAction`/`StructuredRequestPlan` by type for its execution-validation functions — those live there, not here, because they decide whether a plan's next action is safe to *execute*, a dispatch-adjacent concern distinct from *building* the plan; `main.rs`'s `run_freeform` builds a plan exactly once via `build_freeform_plan_with_context` and threads that same value through `execute_freeform_next_action` to `prepare_freeform_execution` rather than rebuilding it (ROCMAI-725: building a plan can call a configured cloud `planner_provider`, which is not guaranteed deterministic, so a second independent build could silently disagree with the first). [`chat.rs`](../apps/rocm/src/chat.rs)'s `natural_language_plan` MCP tool gets the same single-build guarantee from `plan_freeform_request_with_context`, which builds once and returns both the rendered text and the next action; `chat.rs` also calls `format_structured_tool_call` directly, like [`comfyui.rs`](../apps/rocm/src/comfyui.rs) does, and its `validate_chat_rocm_command_safety` reads `serve_args_request_cpu_device` directly as a no-CPU-fallback safety check on provider-proposed `serve` args. `host_default_engine`, `build_freeform_plan_with_context`, `render_structured_request_plan`, `plan_next_action`, `plan_freeform_request_with_context`, `provider_planner_response_to_plan`, `format_structured_tool_call`, and `serve_args_request_cpu_device` are `pub(crate)` for these reasons, as are `infer_engine_from_request` (read from `chat.rs`) and `plan_driver_request` (read from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs)'s test module); `freeform_plan_next_action` and `render_freeform_plan` are test-only (`#[cfg(test)]`) and `FreeformPlanAction` was already `pub(crate)` before the split. `parse_freeform_invocation`/`should_treat_as_freeform` (deciding whether an invocation is freeform at all) stay in `main.rs`, a dispatch-level concern outside both this module and `freeform_execution.rs`. The cluster's regression tests live in `freeform_planner.rs`'s own `mod tests`; the handful of `main.rs` tests that exercise the invocation classifier/clap-suggestion-avoidance stay in `main.rs`'s shared `mod tests`, since neither is specific to this module or to `freeform_execution.rs` (and neither touches `freeform_planner::` at all), and the ROCMAI-725 regression tests proving the single-build guarantee live in `providers.rs`'s `mod tests` (reusing its mock local-provider server), reaching this module's items through the qualified `freeform_planner::` path like any other external caller. - [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs) — mechanical relocation, owns types (Phase 6f, ROCMAI-214): `--device`/`--gpu` parsing (`parse_device_policy`, `parse_gpu_selection`, `parse_gpu_indices_arg`), the managed-launch-lock GPU selection (`select_gpu_indices_under_launch_lock`, `validate_pinned_gpu_index`, `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `busy_gpu_indices`), per-GPU VRAM telemetry (the `GpuVramUsage` type, `gpu_vram_usage`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs`, `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`), and the serve-plan low-VRAM warning (`gpu_low_memory_warning`, `vram_capacity_is_meaningful`, `serve_gpu_low_memory_warning`), plus the best-effort `amd-smi`-based GPU count (`detect_gpu_count`). `const fn device_policy_name` sits immediately after this cluster's last function in the original file but stayed in `main.rs` rather than moving — it already had callers outside the cluster (`engine_ipc.rs`, `service_launch.rs`, `serve_cmd.rs`) plus its own test. `GpuVramUsage` (and its fields), `gpu_vram_usage`, `parse_gpu_indices_arg`, `serve_gpu_low_memory_warning`, and `vram_capacity_is_meaningful` are `pub(crate)` and read from [`model_fit.rs`](../apps/rocm/src/model_fit.rs) (`classify_accelerator_memory`, `host_accelerator_memory`) [`main.rs`](../apps/rocm/src/main.rs) (the `dispatch()` `Command::EngineServeHttp` arm) and [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) (`collect_serve_notes`); `detect_gpu_count`, `gpu_vram_usage`, `parse_device_policy`, `parse_gpu_selection`, `select_gpu_indices_under_launch_lock`, `serve_gpu_low_memory_warning`, and `validate_pinned_gpu_index` are also `pub(crate)` and read from [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs); `parse_device_policy` is also read from [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs)'s `run_builtin_engine_serve_http` and, as of Phase 6f (ROCMAI-209), from [`services_text.rs`](../apps/rocm/src/services_text.rs)'s `restart_child_argv` (moved out of `main.rs` in that same phase). `effective_gpu_count`, `auto_select_gpu_indices`, `select_auto_gpu_index`, `simulated_low_vram_usage`, `gpu_vram_usage_amd_smi`, `gpu_vram_usage_sysfs` (both the Linux and non-Linux `cfg` variants), `read_drm_vram_usage`, `read_sysfs_u64`, `drm_device_is_amd`, `parse_gpu_vram_usage`, `gpu_low_memory_warning`, and `busy_gpu_indices` have no callers outside this module and stay private. The cluster's regression tests live in `gpu_policy.rs`'s own `mod tests`; two small test-only fixture builders (`vram`, `host_gpu`) are duplicated rather than shared, since `serve_cmd.rs`'s own `serve_notes_pair_low_vram_with_the_vllm_utilization_hint` (testing `collect_serve_notes`) needs them too. - [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm install`'s command handler (`install()`, for the `sdk` and `driver` targets), the `--version`/`--build-date` selector parsing and display it uses (`therock_install_version_selector`, `therock_install_version_selector_display`) and `sdk_install_request`, which maps the parsed `install sdk` arguments onto a `therock::SdkInstallRequest` and moved here from [`chat.rs`](../apps/rocm/src/chat.rs) with its two tests. `InstallTarget` and `InstallFormat` stay in [`main.rs`](../apps/rocm/src/main.rs). `install()` is `pub(crate)` and re-imported in `main.rs` for `dispatch()`; `therock_install_version_selector` is `pub(crate)` too, and `chat.rs`'s `render_install_sdk_dry_run_for_args` reaches it as `crate::therock_install_version_selector` through the same kind of re-import, which is why `sdk_install_request` lives here and not in `chat.rs`: this module does not depend on `chat.rs`. `sdk_install_request` keeps the `pub(crate)` it had, although only `install()` and the tests call it now. - [`logging.rs`](../apps/rocm/src/logging.rs) — mechanical relocation, no owned types, reached by qualified path. From b6aa166e42e1773b952cd4e8f08850e08f41b6f8 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 10:49:40 +0000 Subject: [PATCH 02/23] test(shell_quote): check the rendered argv against a real sh The round-trip property tests used shlex as their only oracle. shlex splits words and removes quotes but expands nothing, so it hands back `~`, `?`, `$HOME` and a backtick unchanged and reports a clean round-trip for a quoter that leaves them bare. Adding `~` or `?` to the inert set left the whole suite green, although both change the argv once a shell reads the line. Add a property test that hands the rendered line to a real `sh`, in a directory with files for `?` and `*` to match and with HOME at a sentinel, and demands the argv back. With `~` or `?` made inert it now fails on the one-character input. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 67 ++++++++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 2 deletions(-) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index dbd4f25a2f..2ecd53fb29 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -121,8 +121,9 @@ mod tests { use proptest::prelude::*; /// Render an argv the way every display site does, then split it back the - /// way a shell would. `shlex` is the oracle: it is a POSIX word-splitter, - /// which is precisely the reader the rendered line is written for. + /// way a shell would. `shlex` is a POSIX word-splitter, so it checks word + /// boundaries and quote removal; it does not expand anything, which is why + /// `a_real_shell_reads_a_rendered_argv_back_unchanged` exists beside it. fn render_and_split(argv: &[String]) -> Option> { let rendered = argv .iter() @@ -167,6 +168,68 @@ mod tests { } } + /// Hand `line` to a real `sh` as the operands of `printf` and return the + /// words it received. + /// + /// `shlex` only splits words and removes quotes; it performs no expansion, + /// so it hands back `$HOME`, `~`, `?` and `` `id` `` unchanged and calls a + /// line that leaves them bare a clean round-trip. Only a shell can say + /// whether a value would be expanded on paste. The shell runs in a + /// directory holding files `a` and `1`, so an unquoted `?` or `*` really + /// globs, and with `HOME` pointed at a sentinel, so an unquoted `~` really + /// changes. + #[cfg(unix)] + fn words_a_real_shell_reads(line: &str) -> Vec { + static GLOB_BAIT: std::sync::OnceLock = std::sync::OnceLock::new(); + let dir = GLOB_BAIT.get_or_init(|| { + let dir = std::env::temp_dir().join(format!( + "rocm-shell-quote-glob-bait-{}", + std::process::id() + )); + std::fs::create_dir_all(&dir).expect("create glob-bait dir"); + for name in ["a", "1"] { + std::fs::write(dir.join(name), b"").expect("create glob-bait file"); + } + dir + }); + let output = std::process::Command::new("sh") + .arg("-c") + .arg(format!("printf '%s\\0' {line}")) + .current_dir(dir) + .env("HOME", "/nonexistent/rocm-shell-quote-home") + .output() + .expect("sh should run"); + let mut words: Vec = String::from_utf8_lossy(&output.stdout) + .split('\0') + .map(str::to_owned) + .collect(); + // `printf` terminates every word, so the final piece is always empty. + words.pop(); + words + } + + #[cfg(unix)] + proptest! { + /// The round-trip again, with a real shell as the reader instead of a + /// word-splitter: no generated value is split, expanded, globbed or + /// executed. This is the check that fails if a character with meaning to + /// a shell (`$`, `~`, `?`, `*`, a backtick) is ever treated as inert. + #[test] + fn a_real_shell_reads_a_rendered_argv_back_unchanged(argv in hostile_argv()) { + let rendered = argv + .iter() + .map(|arg| shell_quote(arg)) + .collect::>() + .join(" "); + prop_assert_eq!( + words_a_real_shell_reads(&rendered), + argv, + "rendered = {:?}", + rendered + ); + } + } + #[test] fn generator_reaches_the_shapes_that_break_quoting() { // A generator that never produces the dangerous shapes passes against a From 76343cc64d449ba6f1c3a075115e35287127a77a Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 10:53:31 +0000 Subject: [PATCH 03/23] test(dash-tui): check approval previews against a real sh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The dash quoter's only oracle was shlex, which expands nothing: adding `$` or `~` to its inert set left every dash test green, although a preview showing a bare `$$` or `~` no longer denotes the argv the job is spawned with. Add the same real-`sh` round-trip property the CLI-side quoter now has. Bring the test alphabet level with the CLI side's (`=`, `~`, `!`, `é`), so the `=` inert branch is exercised here too, and correct the doc comment that said a change to one copy the other does not make shows up as a failure: nothing ties the two copies together. Each is held to the same contract by its own tests, so either one breaking fails its own suite. Signed-off-by: Roman Inflianskas --- crates/rocm-dash-tui/src/ui/exec.rs | 68 ++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index af2e3685c3..7fa33a0bb2 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -42,7 +42,10 @@ pub fn exe_label(cmd: &str) -> &str { /// a second copy: `xtask`'s crate-edge contract forbids /// `rocm-dash-tui -> rocm-core` (`xtask/src/crate_edges.rs`), and `apps/rocm` /// is the crate that owns `rocm-core`, so there is nowhere both can reach -/// without breaking that. +/// without breaking that. Nothing ties the two copies to each other: each is +/// held to the same contract by its own tests, including a real `sh` reading +/// the rendered line back, so either one *breaking* fails its own suite. They +/// may still differ harmlessly in which values they leave bare. pub fn quote_display_arg(value: &str) -> String { let inert = |character: char| { character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') @@ -137,7 +140,7 @@ mod tests { /// by `the_generator_reaches_the_shapes_that_break_quoting`. const HOSTILE_ALPHABET: &[char] = &[ ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', - '-', '/', 'a', '1', + '=', '-', '~', '!', 'a', '1', '/', 'é', ]; fn hostile_arg() -> impl Strategy { @@ -189,6 +192,67 @@ mod tests { } } + /// Hand `line` to a real `sh` as the operands of `printf` and return the + /// words it received. + /// + /// `shlex` only splits words and removes quotes; it performs no expansion, + /// so it hands back `$HOME`, `~`, `?` and `` `id` `` unchanged and calls a + /// line that leaves them bare a clean round-trip. Only a shell can say + /// whether a value would be expanded on paste. The shell runs in a + /// directory holding files `a` and `1`, so an unquoted `?` or `*` really + /// globs, and with `HOME` pointed at a sentinel, so an unquoted `~` really + /// changes. + #[cfg(unix)] + fn words_a_real_shell_reads(line: &str) -> Vec { + static GLOB_BAIT: std::sync::OnceLock = std::sync::OnceLock::new(); + let dir = GLOB_BAIT.get_or_init(|| { + let dir = std::env::temp_dir().join(format!( + "rocm-dash-quote-glob-bait-{}", + std::process::id() + )); + std::fs::create_dir_all(&dir).expect("create glob-bait dir"); + for name in ["a", "1"] { + std::fs::write(dir.join(name), b"").expect("create glob-bait file"); + } + dir + }); + let output = std::process::Command::new("sh") + .arg("-c") + .arg(format!("printf '%s\\0' {line}")) + .current_dir(dir) + .env("HOME", "/nonexistent/rocm-dash-quote-home") + .output() + .expect("sh should run"); + let mut words: Vec = String::from_utf8_lossy(&output.stdout) + .split('\0') + .map(str::to_owned) + .collect(); + // `printf` terminates every word, so the final piece is always empty. + words.pop(); + words + } + + #[cfg(unix)] + proptest! { + /// The preview round-trip with a real shell as the reader rather than a + /// word-splitter: no argument is split, expanded, globbed or executed. + /// This is the check that fails if a character with meaning to a shell + /// (`$`, `~`, `?`, `*`, a backtick) is ever treated as inert. + #[test] + fn a_real_shell_reads_the_preview_back_as_the_argv(argv in hostile_argv()) { + let preview = format!("{} {}", exe_label("/usr/local/bin/rocm"), display_args(&argv)); + let expected: Vec = std::iter::once("rocm".to_owned()) + .chain(argv.into_iter()) + .collect(); + prop_assert_eq!( + words_a_real_shell_reads(&preview), + expected, + "preview = {:?}", + preview + ); + } + } + #[test] fn the_generator_reaches_the_shapes_that_break_quoting() { // A generator that never produces the dangerous shapes passes against a From fbe4410006d4a8448c14949c6b747a2afb0f58bc Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 10:53:44 +0000 Subject: [PATCH 04/23] docs(shell_quote): PowerShell does not read '\'' as a quote MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The module doc said the POSIX form is correct in PowerShell. PowerShell does read '…' literally, but it escapes an embedded single quote by doubling it, so the '\'' idiom this quoter emits for a value containing ' does not round-trip there. Say so, rather than claiming parity. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 2ecd53fb29..cca8e350aa 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -36,9 +36,11 @@ //! //! Platform note: this is POSIX quoting on every platform. The previous //! double-quoted form happened to paste cleanly into `cmd.exe`; `'…'` does not. -//! It is correct in bash, WSL and PowerShell, and on Windows it is still -//! unambiguous to a *reader* — which is what an approval gate needs — where the -//! old form was ambiguous everywhere. +//! It is correct in any POSIX shell (bash, sh, WSL). PowerShell also reads +//! `'…'` literally, but escapes an embedded `'` as `''` rather than `'\''`, so a +//! value containing a single quote is the one case that does not paste cleanly +//! there. On Windows it is still unambiguous to a *reader* — which is what an +//! approval gate needs — where the old form was ambiguous everywhere. /// Quote `value` so a POSIX shell reads it back as exactly one word equal to /// `value`. From bd2e40c0e77d79a3aea543c9c57065b113e54ecc Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 11:19:10 +0000 Subject: [PATCH 05/23] test(chat): pin the planner-note filter; make the path_exists check falsifiable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The planner-note filter added with the control-character guard had no test: deleting it left the suite green. Add one that feeds the provider planner a note carrying a CSI sequence and one carrying a carriage return, and requires both to be gone and the ordinary note to survive. The handler half of a_read_only_path_probe_cannot_redraw_the_block_it_prints_into asserted `!any(is_control) || !contains(ESC)` on the output for `/tmp/my folder`, which no handler change could make false. Assert the premise the guard rests on instead — the handler echoes the model's path verbatim — and say that in the doc comment, which claimed more. Also point the scope note at `strip_ansi_sequences` where it lives (`comfyui.rs`, private); it is not in `rocm_core`. Signed-off-by: Roman Inflianskas --- apps/rocm/src/chat.rs | 13 ++++++----- apps/rocm/src/freeform_planner.rs | 37 +++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/apps/rocm/src/chat.rs b/apps/rocm/src/chat.rs index df6aa941e1..e0eefe734a 100644 --- a/apps/rocm/src/chat.rs +++ b/apps/rocm/src/chat.rs @@ -2193,7 +2193,7 @@ const CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL: [&str; 9] = [ /// /// Scope note, so the guarantee is not overread: this covers model-supplied /// *arguments*, not model-supplied prose. An assistant's reply text is still -/// printed as it comes; [`rocm_core::strip_ansi_sequences`] is the tool for +/// printed as it comes; `strip_ansi_sequences` in `comfyui.rs` is the tool for /// that surface, and is already used on ComfyUI log output. /// /// Walks the whole arguments object rather than naming fields, so a new @@ -7688,9 +7688,10 @@ mod command_preview_properties { /// around it. The criterion for this guard is "reaches the terminal", not /// "becomes a command line"; this is the case that distinguishes them. /// - /// Asserted through the handler, not just the validator, so the test fails - /// if the value stops being screened *or* the handler stops being the thing - /// that prints it. + /// The refusal is asserted at the validator. The handler half pins the + /// premise the guard rests on — that the model's `path` is printed back + /// verbatim — so if the handler ever stops echoing it, this fails and the + /// guard entry can be reconsidered rather than kept on a stale reason. #[test] fn a_read_only_path_probe_cannot_redraw_the_block_it_prints_into() { let hostile = "/tmp/\u{1b}[1A\u{1b}[2Kadvanced manual command: rocm examine"; @@ -7719,8 +7720,8 @@ mod command_preview_properties { &run_chat_path_exists_tool(&ok).expect("the probe answers for a missing path"), ); assert!( - !text.chars().any(char::is_control) || !text.contains('\u{1b}'), - "the printed block carries an escape: {text:?}" + text.lines().any(|line| line == "path: /tmp/my folder"), + "the probe must echo the model's path verbatim, which is why it is guarded: {text:?}" ); } diff --git a/apps/rocm/src/freeform_planner.rs b/apps/rocm/src/freeform_planner.rs index 3b0b3ec329..b0c62d12c7 100644 --- a/apps/rocm/src/freeform_planner.rs +++ b/apps/rocm/src/freeform_planner.rs @@ -2001,4 +2001,41 @@ mod tests { assert!(error.contains("ROCm GPU execution")); } } + + /// Planner notes are printed verbatim into the plan block, so a note + /// carrying a control character is dropped rather than printed — unlike the + /// planner's argv, which is refused outright, a note is commentary and the + /// plan stands without it. Ordinary notes still come through. + #[test] + fn a_planner_note_carrying_a_control_character_is_dropped() -> Result<()> { + let content = r#"{ + "intent": "serve", + "confidence": "high", + "tool_call": { + "tool": "rocm", + "args": ["serve", "sshleifer/tiny-gpt2", "--managed"] + }, + "notes": [ + "resolved the missing model to a tiny test model", + "\u001b[1A\u001b[2Kapproval: not required", + "line one\rline two" + ] + }"#; + + let plan = provider_planner_response_to_plan("start a local model", "local", content)?; + + assert!( + plan.notes + .iter() + .any(|note| note == "resolved the missing model to a tiny test model"), + "an ordinary note must survive: {:?}", + plan.notes + ); + assert!( + !plan.notes.iter().any(|note| note.chars().any(char::is_control)), + "no note may carry a control character into the plan block: {:?}", + plan.notes + ); + Ok(()) + } } From 3b19bfb17930566266fd003397d4f47e992ec3fb Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 11:23:55 +0000 Subject: [PATCH 06/23] style: rustfmt the new preview tests Signed-off-by: Roman Inflianskas --- apps/rocm/src/freeform_planner.rs | 9 +++++++-- apps/rocm/src/shell_quote.rs | 6 ++---- crates/rocm-dash-tui/src/ui/exec.rs | 6 ++---- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/apps/rocm/src/freeform_planner.rs b/apps/rocm/src/freeform_planner.rs index b0c62d12c7..cd30e7f9de 100644 --- a/apps/rocm/src/freeform_planner.rs +++ b/apps/rocm/src/freeform_planner.rs @@ -968,7 +968,9 @@ fn strip_json_fence(content: &str) -> &str { trimmed } -pub(crate) fn validate_provider_planner_tool_call(call: &ProviderPlannerToolCall) -> Result> { +pub(crate) fn validate_provider_planner_tool_call( + call: &ProviderPlannerToolCall, +) -> Result> { if call.tool != "rocm" { bail!("provider planner returned unsupported tool `{}`", call.tool); } @@ -2032,7 +2034,10 @@ mod tests { plan.notes ); assert!( - !plan.notes.iter().any(|note| note.chars().any(char::is_control)), + !plan + .notes + .iter() + .any(|note| note.chars().any(char::is_control)), "no note may carry a control character into the plan block: {:?}", plan.notes ); diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index cca8e350aa..6e0fe2a53b 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -184,10 +184,8 @@ mod tests { fn words_a_real_shell_reads(line: &str) -> Vec { static GLOB_BAIT: std::sync::OnceLock = std::sync::OnceLock::new(); let dir = GLOB_BAIT.get_or_init(|| { - let dir = std::env::temp_dir().join(format!( - "rocm-shell-quote-glob-bait-{}", - std::process::id() - )); + let dir = std::env::temp_dir() + .join(format!("rocm-shell-quote-glob-bait-{}", std::process::id())); std::fs::create_dir_all(&dir).expect("create glob-bait dir"); for name in ["a", "1"] { std::fs::write(dir.join(name), b"").expect("create glob-bait file"); diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 7fa33a0bb2..860bf77b0f 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -206,10 +206,8 @@ mod tests { fn words_a_real_shell_reads(line: &str) -> Vec { static GLOB_BAIT: std::sync::OnceLock = std::sync::OnceLock::new(); let dir = GLOB_BAIT.get_or_init(|| { - let dir = std::env::temp_dir().join(format!( - "rocm-dash-quote-glob-bait-{}", - std::process::id() - )); + let dir = std::env::temp_dir() + .join(format!("rocm-dash-quote-glob-bait-{}", std::process::id())); std::fs::create_dir_all(&dir).expect("create glob-bait dir"); for name in ["a", "1"] { std::fs::write(dir.join(name), b"").expect("create glob-bait file"); From dca0e18a6177da8d03c19eff599b638b993989ea Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 14 Oct 2026 11:35:48 +0000 Subject: [PATCH 07/23] test(e2e): a request plan names a quoted folder as one argument Scenario runtime-20 drives `rocm --yes ` with an install folder whose name carries a lone `'`, and reads the request plan's and the execution section's `rocm install sdk` tool_call lines back through a POSIX word-splitter, requiring `--prefix` to be followed by exactly that folder. The previous quoter wrapped only on whitespace, so it rendered that folder bare and left a line no shell can parse; with it restored, the scenario fails on the request plan step. A space alone would not distinguish the two quoters on this surface. Reuses runtime-15's Given, so the install stops on its first step: offline, instant, and the same on every lane. Signed-off-by: Roman Inflianskas --- Cargo.lock | 1 + tests/e2e-cucumber/Cargo.toml | 4 ++ .../features/runtime_setup.feature | 22 ++++++ tests/e2e-cucumber/tests/e2e/runtime_steps.rs | 70 +++++++++++++++++++ 4 files changed, 97 insertions(+) diff --git a/Cargo.lock b/Cargo.lock index d493d5c124..59b8e6f9e3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1284,6 +1284,7 @@ dependencies = [ "rocm-core", "serde", "serde_json", + "shlex", "tempfile", "tokio", "toml", diff --git a/tests/e2e-cucumber/Cargo.toml b/tests/e2e-cucumber/Cargo.toml index 719f32ac35..45fd133a90 100644 --- a/tests/e2e-cucumber/Cargo.toml +++ b/tests/e2e-cucumber/Cargo.toml @@ -73,6 +73,10 @@ url = "2" vt100 = "0.16" [dev-dependencies] +# Reads a printed command line back the way a POSIX shell splits words, so a +# scenario can assert what a `tool_call:` line denotes rather than one spelling +# of it. +shlex.workspace = true # `FileLock`, so the service-cleanup lane can hold the managed-launch lock that a # real `rocm serve` holds and watch a real `rocm services prune` *process* block # on it. Using the production type rather than a hand-rolled `flock` is the diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 6e9e51e819..2879432000 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -451,3 +451,25 @@ Feature: Runtime configuration When the user previews a tarball SDK install Then the preview selects the newest SDK in the catalog And the preview does not claim the host's ROCm is newer + + # The `tool_call:` lines `rocm ` prints are the command the operator + # reviews before re-running with `--yes`, and the one that then runs. Their + # quoter used to wrap a value only when it held whitespace, so a folder whose + # name carries a lone `'` rendered bare and left a line no shell can parse — + # the operator was shown something that denotes no argv at all. The + # assertion reads each line back through a POSIX word-splitter and demands + # `--prefix` followed by exactly the requested folder: what the line has to + # mean, rather than one spelling of it. (A space alone does not distinguish + # the two quoters on this surface — the old one wrapped whitespace — which is + # why the folder name carries a quote.) + # + # The argv the dispatched install receives is not observable here: the Given + # stops it on its first step, as in runtime-15, and for the same reasons — + # offline, instant, writes nothing, identical on every lane. The executed + # `tool_call:` line is the closest observable account of it. + @id:runtime-freeform-prefix-with-quote-is-one-argument + Scenario: runtime-22 - A natural-language install into a folder named with a quote keeps the folder one argument + Given the CLI cannot reach a usable Python + When the user approves a natural-language SDK install into a folder whose name has a quote + Then the request plan names that folder as a single argument + And the executed command names that folder as a single argument diff --git a/tests/e2e-cucumber/tests/e2e/runtime_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_steps.rs index c7e6197d42..0e271cd3fd 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_steps.rs @@ -1457,3 +1457,73 @@ async fn assert_unsupported_family_offers_nothing(world: &mut E2eWorld) { ); } } + +/// The folder scenario runtime-22 asks for: inside the scenario's own temp +/// root, and with a lone `'` in its name — the shape the old quoter left bare. +fn freeform_prefix_with_quote(world: &E2eWorld) -> String { + world + .isolated_root + .as_ref() + .expect("scenario has no isolated root") + .path() + .join("it's-here") + .to_string_lossy() + .into_owned() +} + +#[when("the user approves a natural-language SDK install into a folder whose name has a quote")] +async fn user_approves_freeform_sdk_install_into_quoted_folder(world: &mut E2eWorld) { + let prefix = freeform_prefix_with_quote(world); + let request = format!("install the latest TheRock nightly for this GPU into {prefix}"); + // `run_rocm`, not `run_rocm_ok`: the Given guarantees the dispatched install + // fails, and the exit code is not what this scenario is about. + let (stdout, stderr, rc) = crate::run_rocm_with_scenario_env(world, &["--yes", &request]); + world.cli_output = Some(stdout); + world.cli_stderr = Some(stderr); + world.cli_rc = Some(rc); +} + +/// Read the section's `rocm install sdk` `tool_call:` line back the way a POSIX +/// shell splits words, and require `--prefix` to be followed by exactly +/// `prefix`. The install line specifically: the request plan lists a read-only +/// `rocm examine` step ahead of it. +fn assert_tool_call_has_prefix_as_one_word(section: &str, which: &str, prefix: &str) { + let line = section + .lines() + .filter_map(|line| line.trim().strip_prefix("tool_call: ")) + .find(|line| line.starts_with("rocm install sdk")) + .unwrap_or_else(|| panic!("no install `tool_call:` line in the {which}:\n{section}")); + let words = shlex::split(line) + .unwrap_or_else(|| panic!("the {which} `tool_call:` line does not parse: `{line}`")); + let after_prefix = words + .iter() + .position(|word| word == "--prefix") + .and_then(|index| words.get(index + 1)) + .unwrap_or_else(|| { + panic!("the {which} `tool_call:` line has no `--prefix` value: `{line}`") + }); + assert_eq!( + after_prefix, prefix, + "the {which} `tool_call:` line must name the folder as one argument, got `{line}`" + ); +} + +#[then("the request plan names that folder as a single argument")] +async fn assert_freeform_plan_prefix_is_one_word(world: &mut E2eWorld) { + let (plan, _) = freeform_plan_and_execution(world); + assert_tool_call_has_prefix_as_one_word( + &plan, + "request plan", + &freeform_prefix_with_quote(world), + ); +} + +#[then("the executed command names that folder as a single argument")] +async fn assert_freeform_execution_prefix_is_one_word(world: &mut E2eWorld) { + let (_, execution) = freeform_plan_and_execution(world); + assert_tool_call_has_prefix_as_one_word( + &execution, + "execution section", + &freeform_prefix_with_quote(world), + ); +} From e55c5e70cb55afc18da67e026489fdf91004a417 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 11:45:43 +0000 Subject: [PATCH 08/23] test(e2e): the dry-run command line keeps a quoted folder whole MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Scenario therock-next-11 previews a wheel install with `--prefix` naming a folder whose name carries a lone `'`, and reads the dry-run's `command: uv … && uv …` line back through a POSIX word-splitter, requiring one word to name that folder. With the previous whitespace-only quoter restored the folder renders bare and the scenario fails. Reuses therock-next-01's loopback pip-index fixture, so it needs no network, GPU or gate. Signed-off-by: Roman Inflianskas --- .../features/therock_next_generation.feature | 14 ++++++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 50 +++++++++++++++++++ 2 files changed, 64 insertions(+) diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index f417b34886..35c683eccf 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -251,3 +251,17 @@ Feature: TheRock "next" ROCm 10 install layout When the user installs a wheel SDK for arch gfx1200 pinned to ROCm 10.0.0 without confirming Then the install is refused without replacing the active default runtime And the install log notes that its torchaudio is the newest build for ROCm 10.0.0 and not hardware-verified + + # The dry-run's `command: uv … && uv …` line is offered as the command the + # install would run, so it has to be one a shell reads back as that argv. Its + # quoter used to wrap only on whitespace and a short metacharacter list, so a + # folder whose name carries a lone `'` rendered bare and left a line no shell + # can parse. The assertion reads the line back through a POSIX word-splitter + # and requires the install folder to come back as one word. Reuses the + # loopback fixture from therock-next-01, so it resolves without live network + # or GPU and needs no gate. + @id:therock-next-15-dry-run-command-keeps-a-quoted-folder-whole + Scenario: therock-next-15 - The dry-run command line keeps an install folder named with a quote as one argument + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + When the user previews a wheel SDK install for arch gfx1200 into a folder whose name has a quote + Then the dry-run command line names that folder as a single argument diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 9104b50b09..7074902508 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -978,6 +978,56 @@ async fn preview_pinned_tarball_install_with_group_family(world: &mut E2eWorld) ); } +/// The install folder therock-next-15 asks for: inside the scenario's root, with +/// a lone `'` in its name — the shape the old dry-run quoter left bare. +const QUOTED_FOLDER_NAME: &str = "it's-here"; + +#[when( + "the user previews a wheel SDK install for arch gfx1200 into a folder whose name has a quote" +)] +async fn preview_unpinned_wheel_install_into_quoted_folder(world: &mut E2eWorld) { + let prefix = root(world) + .join(QUOTED_FOLDER_NAME) + .to_string_lossy() + .into_owned(); + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--prefix", + &prefix, + "--dry-run", + ], + ); +} + +#[then("the dry-run command line names that folder as a single argument")] +async fn assert_dry_run_command_keeps_quoted_folder_whole(world: &mut E2eWorld) { + let output = stdout(world); + let line = output + .lines() + .find_map(|line| line.trim().strip_prefix("command: ")) + .unwrap_or_else(|| panic!("no `command:` line in the dry-run preview:\n{output}")); + let words = shlex::split(line) + .unwrap_or_else(|| panic!("the dry-run `command:` line does not parse: `{line}`")); + // By file name rather than the full path: the CLI resolves the prefix + // through symlinks, so the folder's parent may be spelled differently from + // the one this step built. What must hold is that one whole word names it. + assert!( + words.iter().any(|word| { + Path::new(word).file_name() == Some(std::ffi::OsStr::new(QUOTED_FOLDER_NAME)) + }), + "the dry-run `command:` line must name the install folder as one argument, got `{line}`" + ); +} + fn stdout(world: &E2eWorld) -> &str { world.cli_output.as_deref().unwrap_or_default() } From fd057e341cb0f51d30a7c74b6f0dd59d4fb55d2a Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 11:46:49 +0000 Subject: [PATCH 09/23] docs(architecture): list shell_quote.rs among the shared CLI-output components So the next site that renders a command line for an operator finds the shared quoter rather than writing another one, and knows why the dash TUI carries its own copy. Signed-off-by: Roman Inflianskas --- docs/architecture.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/architecture.md b/docs/architecture.md index 2bf4d1d623..f52dff44f0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,6 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`), for any command line shown to an operator or handed to a shell; `rocm-dash-tui` keeps its own copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since it cannot reach `apps/rocm` and the crate-edge check forbids it `rocm-core`. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). From 08677e920b8e422ae08d236d60223535313e5e87 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 12:06:07 +0000 Subject: [PATCH 10/23] style: rustfmt the dash preview tests after the rebase onto #500 Signed-off-by: Roman Inflianskas --- crates/rocm-dash-tui/src/ui/exec.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 860bf77b0f..5f5d76a91e 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -302,7 +302,11 @@ mod tests { "--prefix".to_owned(), "C:\\Program Files\\ROCm".to_owned(), ]; - let preview = format!("{} {}", exe_label("C:\\tools\\rocm.exe"), display_args(&argv)); + let preview = format!( + "{} {}", + exe_label("C:\\tools\\rocm.exe"), + display_args(&argv) + ); assert_eq!( shlex::split(&preview), Some(vec![ From ef231385fb70015b737de8198a5f4d0ee915eea7 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 5 Oct 2026 12:12:52 +0000 Subject: [PATCH 11/23] test: ask /bin/sh by absolute path in the real-shell quoting tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The real-`sh` round-trip tests spawned `"sh"`, which is looked up on `PATH` at spawn time. `therock.rs`'s `render_update_json` test narrows the process-global `PATH` to a stub directory while it runs, so under `cargo test` — one process for every test — a spawn landing in that window failed with "sh should run: No such file or directory". Seen locally on `shell_quote::tests::a_real_shell_reads_a_rendered_argv_back_unchanged`. CI's per-process runner hides it; a local run does not. Spawn `/bin/sh` instead, in the four tests this change adds or moves. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 15 +++++++++++++-- apps/rocm/src/therock.rs | 2 +- crates/rocm-dash-tui/src/ui/exec.rs | 8 +++++++- 3 files changed, 21 insertions(+), 4 deletions(-) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 6e0fe2a53b..6d41a96089 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -116,6 +116,17 @@ pub(crate) mod hostile { } } +/// The shell the real-`sh` tests ask, by absolute path. +/// +/// Not `"sh"`: that is looked up on `PATH` at spawn time, and other tests in +/// this binary narrow the process-global `PATH` to a stub directory while they +/// run (`render_update_json` in `therock.rs`, for one). Under `cargo test`, +/// which runs every test in one process, a spawn landing in that window fails +/// with "No such file or directory" — a failure about the test harness, not +/// about quoting. `/bin/sh` is where POSIX systems put it. +#[cfg(all(test, unix))] +pub(crate) const TEST_SH: &str = "/bin/sh"; + #[cfg(test)] mod tests { use super::hostile::{arg as hostile_arg, argv as hostile_argv}; @@ -192,7 +203,7 @@ mod tests { } dir }); - let output = std::process::Command::new("sh") + let output = std::process::Command::new(TEST_SH) .arg("-c") .arg(format!("printf '%s\\0' {line}")) .current_dir(dir) @@ -321,7 +332,7 @@ mod tests { "qwen2.5-7b-instruct", "/mnt/my folder", ] { - let output = std::process::Command::new("sh") + let output = std::process::Command::new(TEST_SH) .arg("-c") .arg(format!("printf %s {}", shell_quote(value))) .output() diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index fe9d9fafc6..976d88c0a9 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -1479,7 +1479,7 @@ mod tests { "", ] { let quoted = quote_display_arg(hostile); - let output = std::process::Command::new("sh") + let output = std::process::Command::new(crate::shell_quote::TEST_SH) .arg("-c") .arg(format!("printf %s {quoted}")) .output() diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 5f5d76a91e..65be77a46a 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -71,6 +71,12 @@ mod tests { use super::*; use proptest::prelude::*; + /// By absolute path, not `"sh"`: a `PATH` lookup at spawn time races any + /// test in this binary that narrows the process-global `PATH`, and the + /// failure would be about the harness, not about quoting. + #[cfg(unix)] + const TEST_SH: &str = "/bin/sh"; + #[test] fn exe_label_strips_unix_and_windows_paths() { assert_eq!(exe_label("/usr/local/bin/rocm"), "rocm"); @@ -214,7 +220,7 @@ mod tests { } dir }); - let output = std::process::Command::new("sh") + let output = std::process::Command::new(TEST_SH) .arg("-c") .arg(format!("printf '%s\\0' {line}")) .current_dir(dir) From 0a7e620172867ed89927e743f5aed72fab991b3a Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 9 Oct 2026 14:26:13 +0000 Subject: [PATCH 12/23] docs(shell_quote): say why `=` may stay bare, and where it may not Both copies of the quoter leave `=` unquoted. That is sound only because no caller renders a value in command position, where `A=b` is an assignment; nothing enforces it, so say so at the predicate. Also name zsh's `=word` expansion, which sits outside the POSIX contract. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 8 ++++++++ crates/rocm-dash-tui/src/ui/exec.rs | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 6d41a96089..845dcb569d 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -49,6 +49,14 @@ /// ordinary command line stays readable: `rocm serve qwen2.5-7b --managed`, /// not `rocm 'serve' 'qwen2.5-7b' '--managed'`. pub(crate) fn shell_quote(value: &str) -> String { + // `=` is left bare because POSIX gives it meaning only in a word ahead of + // the command name, where `A=b` is an assignment rather than an argument. + // Every caller renders values after a fixed program word (`rocm …`, + // `uv …`, `rocm serve …` on the remote), never as argv[0], so it is inert + // where it lands. Nothing enforces that: a caller that puts a quoted value + // in command position must quote `=` as well. zsh is the other exception — + // with its default `EQUALS` option a word *starting* with `=` expands to a + // command path — and is outside the POSIX contract this quoter states. let inert = |character: char| { character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') }; diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 65be77a46a..1153caea66 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -47,6 +47,14 @@ pub fn exe_label(cmd: &str) -> &str { /// the rendered line back, so either one *breaking* fails its own suite. They /// may still differ harmlessly in which values they leave bare. pub fn quote_display_arg(value: &str) -> String { + // `=` is left bare because POSIX gives it meaning only in a word ahead of + // the command name, where `A=b` is an assignment rather than an argument. + // Every caller renders values after a fixed program word (`exe_label` + // of the CLI, then its arguments), never as argv[0], so it is inert + // where it lands. Nothing enforces that: a caller that puts a quoted value + // in command position must quote `=` as well. zsh is the other exception — + // with its default `EQUALS` option a word *starting* with `=` expands to a + // command path — and is outside the POSIX contract this quoter states. let inert = |character: char| { character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') }; From 520763eeb60e809a5611aa75c1628da546846900 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 13 Oct 2026 09:46:31 +0000 Subject: [PATCH 13/23] fix: quote the service and runtime hints added on main meanwhile The `rocm services --yes` hints now come from one builder, and runtime activation prints `rocm services logs ` and `rocm runtimes activate --restart-services --yes` lines of its own. All of them interpolated the value bare, so an id with a space or a quote named a different argv than the one the user would paste. Quote the id once in the hint builders, so every caller gets it, and quote the id and key in the activation report. The remote stop hint now quotes for its callers rather than trusting each to pre-quote; it is the same line whether it is shown or sent to the remote shell. An ordinary id or key is inert and prints unchanged. Signed-off-by: Roman Inflianskas --- apps/rocm/src/remote/mod.rs | 54 ++++++++++++++++++++++-- apps/rocm/src/runtime_services.rs | 54 ++++++++++++++++++++++-- apps/rocm/src/service_hints.rs | 68 ++++++++++++++++++++++++++++--- apps/rocm/src/service_records.rs | 41 ++++++++++++++++++- apps/rocm/src/shell_quote.rs | 11 +++-- docs/architecture.md | 2 +- 6 files changed, 214 insertions(+), 16 deletions(-) diff --git a/apps/rocm/src/remote/mod.rs b/apps/rocm/src/remote/mod.rs index ed760a062a..48d26fb81d 100644 --- a/apps/rocm/src/remote/mod.rs +++ b/apps/rocm/src/remote/mod.rs @@ -545,8 +545,7 @@ fn unwind_partial_serve( if let Some(service_id) = service_id { match transport.exec(&crate::service_hints::remote_service_stop_hint( - remote_cli, - &rocm_core::posix_shell_quote(service_id), + remote_cli, service_id, )) { Ok(outcome) if outcome.success => {} Ok(outcome) => leftovers.push(format!( @@ -1109,7 +1108,7 @@ fn stop_with_transport( let withdrawn = publish::withdraw(transport, record.tailnet_port, record.remote_port); let stopped = transport.exec(&crate::service_hints::remote_service_stop_hint( &record.remote_cli, - &rocm_core::posix_shell_quote(&record.remote_service_id), + &record.remote_service_id, )); let stop_failure = describe_stop_failure(&stopped); let model_stopped = stop_failure.is_none(); @@ -2029,6 +2028,55 @@ mod tests { let _ = std::fs::remove_dir_all(root); } + /// The service ids the two remote stop paths send, split the way the remote + /// shell will split them. `remote_service_stop_hint` quotes the id itself, + /// so a caller that quoted it again would send the quotes as part of the id. + fn sent_stop_argvs(transport: &ScriptedTransport) -> Vec> { + transport + .calls() + .into_iter() + .filter_map(|call| match call { + TransportCall::Exec { command, .. } if command.contains("services stop") => { + shlex::split(&command) + } + _ => None, + }) + .collect() + } + + fn stop_argv(service_id: &str) -> Vec { + ["rocm", "services", "stop", service_id, "--yes"] + .into_iter() + .map(str::to_owned) + .collect() + } + + // Mutation: quoting the id at either call site as well as in the hint + // builder, or at neither, fails this. + #[test] + fn both_remote_stop_paths_send_the_service_id_as_one_word() { + let awkward = "svc 'a b'"; + + let (root, paths) = temp_paths("unwind-awkward-id"); + let transport = ScriptedTransport::new(vec![ScriptedStep::ok("services stop", "")]); + let leftovers = + unwind_partial_serve(&transport, &paths, "sess", "rocm", Some(awkward), None); + assert!(leftovers.is_empty(), "{leftovers:?}"); + assert_eq!(sent_stop_argvs(&transport), vec![stop_argv(awkward)]); + let _ = std::fs::remove_dir_all(root); + + let (root, paths) = temp_paths("stop-awkward-id"); + let mut record = seeded_session(&paths); + record.remote_service_id = awkward.to_owned(); + let transport = ScriptedTransport::new(vec![ + ScriptedStep::ok("tailscale serve status", "{}"), + ScriptedStep::ok("services stop", ""), + ]); + stop_with_transport(&transport, &paths, &record, false).expect("a confirmed stop succeeds"); + assert_eq!(sent_stop_argvs(&transport), vec![stop_argv(awkward)]); + let _ = std::fs::remove_dir_all(root); + } + #[test] fn what_the_unwind_could_not_undo_is_reported_not_swallowed() { // A discarded cleanup failure is how a machine ends up running a model diff --git a/apps/rocm/src/runtime_services.rs b/apps/rocm/src/runtime_services.rs index 80467abfd9..3734cb8744 100644 --- a/apps/rocm/src/runtime_services.rs +++ b/apps/rocm/src/runtime_services.rs @@ -27,6 +27,7 @@ use rocm_core::{AppPaths, ManagedServiceRecord}; use crate::engine_install_env::{engine_manages_own_runtime, runtime_manifest_for_selector}; use crate::managed_service_status::{load_managed_services, managed_service_is_live}; use crate::services_text::{load_managed_service, restart_internal_managed_service}; +use crate::shell_quote::shell_quote; use crate::therock; /// Where one live local server stands relative to the runtime being activated. @@ -285,7 +286,9 @@ pub(crate) fn render_runtime_service_reconciliation( let _ = writeln!( output, " - {} status={} (check `rocm services logs {}` if it does not come up)", - entry.service_id, entry.status, entry.service_id + entry.service_id, + entry.status, + shell_quote(&entry.service_id) ); } } @@ -317,8 +320,8 @@ pub(crate) fn render_runtime_service_reconciliation( let _ = writeln!( output, " note: those keep serving on their recorded runtime until they are restarted; \ - run `rocm runtimes activate {active_runtime_key} --restart-services --yes` to \ - move them" + run `rocm runtimes activate {} --restart-services --yes` to move them", + shell_quote(active_runtime_key) ); } output @@ -683,6 +686,51 @@ mod tests { // loads the new runtime. // Mutation: rendering `unconfirmed` entries under the `services_restarted` // header, or not rendering them, fails these assertions. + // The two commands this report offers to be copied name a service id and a + // runtime key, so each must split back to exactly the argv it names. + // Mutation: interpolating either value bare fails this. + #[test] + fn the_report_commands_denote_the_argv_they_name() { + let awkward_id = "svc 'a' $b"; + let awkward_key = "rt key;x"; + let services = RuntimeServiceReconciliation { + stale: vec![RuntimeServiceEntry { + service_id: "svc-old".to_owned(), + engine: "vllm".to_owned(), + recorded_runtime: Some("rt-old".to_owned()), + }], + unconfirmed: vec![unconfirmed(awkward_id, "starting")], + ..RuntimeServiceReconciliation::default() + }; + + let rendered = render_runtime_service_reconciliation(&services, awkward_key); + let commands: Vec> = rendered + .split('`') + .skip(1) + .step_by(2) + .map(|command| shlex::split(command).expect("a copyable command must parse")) + .collect(); + + assert_eq!( + commands, + vec![ + vec!["rocm", "services", "logs", awkward_id], + vec![ + "rocm", + "runtimes", + "activate", + awkward_key, + "--restart-services", + "--yes" + ], + ] + .into_iter() + .map(|argv| argv.into_iter().map(str::to_owned).collect::>()) + .collect::>(), + "{rendered}" + ); + } + #[test] fn a_restart_not_yet_serving_is_rendered_apart_from_a_confirmed_one() { let services = RuntimeServiceReconciliation { diff --git a/apps/rocm/src/service_hints.rs b/apps/rocm/src/service_hints.rs index 44f4ec2eaa..c7d96fd521 100644 --- a/apps/rocm/src/service_hints.rs +++ b/apps/rocm/src/service_hints.rs @@ -18,10 +18,16 @@ //! `SandboxToolArg`. They were relocated verbatim from `main.rs`; //! `services_cmd.rs`'s `run_approved_service_action` calls all four, and //! `services_text.rs` reads `service_action_past_tense` from here. +//! +//! The service id goes through [`shell_quote`] here, once, so every hint is a +//! line whose words are exactly the argv it names: an id that is not a single +//! inert word still pastes back as one argument. An ordinary id is inert and is +//! printed unchanged. use anyhow::{Result, bail}; use crate::SandboxToolArg; +use crate::shell_quote::shell_quote; /// The directly-runnable `rocm services --yes` hint for a local /// managed service. `action` is typically `"stop"` or `"restart"` — whatever @@ -29,7 +35,7 @@ use crate::SandboxToolArg; /// any `rocm services` subcommand name that takes `--yes` works, e.g. /// `"remove"`. pub(crate) fn service_action_hint(action: &str, service_id: &str) -> String { - format!("rocm services {action} {service_id} --yes") + format!("rocm services {action} {} --yes", shell_quote(service_id)) } /// The directly-runnable `rocm services stop --yes` hint. @@ -40,11 +46,16 @@ pub(crate) fn service_stop_hint(service_id: &str) -> String { /// The directly-runnable ` services stop --yes` hint for a /// service on a remote machine, where `remote_cli` is that machine's own /// `rocm` binary name (not necessarily `"rocm"` — it is whatever the remote -/// session recorded). Callers that feed the result to a transport's `exec` -/// shell-quote `service_id` themselves before calling this; callers building -/// human-readable text pass it unquoted. +/// session recorded). `service_id` is quoted here, so the same line is both +/// the human-readable hint and the command a transport's `exec` hands to the +/// remote shell; callers pass it unquoted. `remote_cli` is not quoted: it is +/// the command word itself, which [`shell_quote`] does not cover (see its note +/// on `=`). pub(crate) fn remote_service_stop_hint(remote_cli: &str, service_id: &str) -> String { - format!("{remote_cli} services stop {service_id} --yes") + format!( + "{remote_cli} services stop {} --yes", + shell_quote(service_id) + ) } pub(crate) fn sandbox_tool_arg_from_service_tool(tool: &str) -> Result { @@ -79,3 +90,50 @@ pub(crate) fn service_action_past_tense(tool: &str) -> &'static str { _ => "updated", } } + +#[cfg(test)] +mod tests { + use super::*; + use crate::shell_quote::hostile::arg as hostile_arg; + use proptest::prelude::*; + + // An ordinary id is inert, so every hint the tests elsewhere pin + // byte-for-byte is unchanged by the quoting. + #[test] + fn an_ordinary_service_id_is_printed_unchanged() { + assert_eq!( + service_stop_hint("vllm-qwen-8000"), + "rocm services stop vllm-qwen-8000 --yes" + ); + assert_eq!( + remote_service_stop_hint("rocm", "vllm-qwen-8000"), + "rocm services stop vllm-qwen-8000 --yes" + ); + } + + proptest! { + // Mutation: printing `service_id` bare in either builder fails this + // for any id carrying whitespace or a quote. + #[test] + fn a_hint_denotes_the_argv_it_names(service_id in hostile_arg()) { + for (hint, program) in [ + (service_action_hint("restart", &service_id), "rocm"), + (remote_service_stop_hint("rocm-remote", &service_id), "rocm-remote"), + ] { + let action = if program == "rocm" { "restart" } else { "stop" }; + prop_assert_eq!( + shlex::split(&hint), + Some(vec![ + program.to_owned(), + "services".to_owned(), + action.to_owned(), + service_id.clone(), + "--yes".to_owned(), + ]), + "{}", + hint + ); + } + } + } +} diff --git a/apps/rocm/src/service_records.rs b/apps/rocm/src/service_records.rs index 79a451da1d..c5c25476da 100644 --- a/apps/rocm/src/service_records.rs +++ b/apps/rocm/src/service_records.rs @@ -216,7 +216,8 @@ pub(crate) fn remove_managed_service_record( let _ = writeln!(output, " log: {}", artifacts.log.display()); let _ = writeln!( output, - "After this, `rocm services logs {service_id}` and `{}` no longer work.", + "After this, `rocm services logs {}` and `{}` no longer work.", + crate::shell_quote::shell_quote(service_id), service_hints::service_action_hint("restart", service_id) ); let _ = writeln!(output); @@ -845,6 +846,44 @@ mod tests { Ok(()) } + // The two commands the removal says stop working name the service, so + // each must split back to exactly that argv for an id that is not one + // inert word. Mutation: interpolating the id bare in either fails this. + #[test] + fn services_remove_names_the_commands_it_disables_as_their_argv() -> Result<()> { + let service_id = "svc 'a b'"; + let (root, paths) = test_paths("services-remove-awkward-id"); + paths.ensure()?; + plant_service_record(&paths, service_id, "failed", 999_999_999)?; + + let rendered = remove_managed_service_record(&paths, service_id, true); + let _ = fs::remove_dir_all(&root); + let rendered = rendered?; + + let line = rendered + .lines() + .find(|line| line.starts_with("After this,")) + .expect("the removal names the commands it disables"); + let commands: Vec> = line + .split('`') + .skip(1) + .step_by(2) + .map(|command| shlex::split(command).expect("a named command must parse")) + .collect(); + let argv = |words: &[&str]| -> Vec { + words.iter().map(|word| (*word).to_owned()).collect() + }; + assert_eq!( + commands, + vec![ + argv(&["rocm", "services", "logs", service_id]), + argv(&["rocm", "services", "restart", service_id, "--yes"]), + ], + "{rendered}" + ); + Ok(()) + } + #[test] fn services_remove_refuses_a_running_record_and_names_stop() -> Result<()> { let (root, paths) = test_paths("services-remove-live"); diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 845dcb569d..b483c41b96 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -2,7 +2,7 @@ // // SPDX-License-Identifier: MIT -//! One POSIX shell quoter for this binary's three command lines. +//! One POSIX shell quoter for every command line this binary prints or runs. //! //! They look unrelated and are not: //! @@ -16,13 +16,18 @@ //! * [`crate::therock::quote_display_arg`] builds the `command: uv … && uv …` //! line the install dry-run prints. Its install root comes from a `--prefix` //! the local assistant can choose, and the line is offered to be run. +//! * [`crate::service_hints`] and the runtime-activation report in +//! [`crate::runtime_services`] build the `rocm services … --yes`, +//! `rocm services logs ` and `rocm runtimes activate …` lines a +//! user is told to run next. A service id is not limited to inert +//! characters, so a bare one could split into several words on paste. //! -//! All three want the same guarantee — *this value is one word and nothing +//! All of them want the same guarantee — *this value is one word and nothing //! else* — so they share one implementation and one set of tests. Keeping them //! apart is how two of them ended up with quoters that did not escape `$`, //! backticks or `;`, and left a lone `"` unquoted entirely. //! -//! The fourth is in another crate and stays there: `rocm-dash-tui`'s +//! One more copy is in another crate and stays there: `rocm-dash-tui`'s //! `ui::exec::quote_display_arg`. `crates/rocm-dash-tui` must not depend on //! `rocm-core` — an invariant the workspace enforces, not a preference — and //! `apps/rocm` is the crate that owns `rocm-core`, so nothing here can be diff --git a/docs/architecture.md b/docs/architecture.md index f52dff44f0..fde739fa4f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -72,7 +72,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) — mechanical relocation, owns types (Phase 6c, ROCMAI-89): `runtimes()` and its activate/rollback handlers (the activation transaction, including `write_active_runtime_marker`), plus the runtime list rendering; the import and adopt handlers it dispatches to live in [`runtime_adopt.rs`](../apps/rocm/src/runtime_adopt.rs) and the uninstall plan, confirmation and apply in [`runtime_uninstall.rs`](../apps/rocm/src/runtime_uninstall.rs); registry selection and manifest validation moved to [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs), which this module re-exports for the callers that import them from here. `RuntimesCommand` stayed in [`main.rs`](../apps/rocm/src/main.rs) (part of the `Command`/`Cli` clap definition, the same way `EnginesCommand` did in Phase 6a). `RuntimeActivationResult` is `pub(crate)`, read from [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs)'s `apply_runtime_update`/`append_update_activate_summary`; `uninstall_runtime`, `should_remove_runtime_install_root` and `InstallRootDecision` (from `runtime_uninstall.rs`) and `ActiveRuntimeMarker` and `active_runtime_marker_path` (from `runtime_registry.rs`) are re-exported for [`storage.rs`](../apps/rocm/src/storage.rs) and [`config_cmd.rs`](../apps/rocm/src/config_cmd.rs); `recover_setup_runtime_registration`, `newest_installed_runtime_manifest` and `setup_runtime_paths` (from `runtime_adopt.rs`) and `normalize_path_for_compare` (from `runtime_registry.rs`) are re-exported for the modules that import them from here, such as [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs), [`examine_cmd.rs`](../apps/rocm/src/examine_cmd.rs) and [`examine_report_text.rs`](../apps/rocm/src/examine_report_text.rs). [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) is deliberately not one of them: it imports from `runtime_adopt.rs` and `runtime_registry.rs` directly, because going through this module would lead back to it via `runtime_services.rs`. The dependency on the sibling [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) above runs the other way: that module calls into this one (`activate_runtime`, `newest_installed_runtime_manifest`, `recover_setup_runtime_registration`), while this module reaches it only from its test module. - [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) — mechanical relocation, owns types (Phase 6a): `serve()`, plus engine-recipe overrides and the AIM pre-flight that runs inside it: the Hugging Face token check, the GPU-family profile check and pin, the multi-GPU refusal (`aim_gpu_preflight`), and AIM-aware default engine selection (`recipe_preferred_engine`). It also holds `collect_serve_notes`, the GPU/device warnings folded into the interactive summary, which was relocated here from `main.rs` with its two tests. - [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs) — full domain extraction. -- [`service_hints.rs`](../apps/rocm/src/service_hints.rs) — shared CLI-output component: the `rocm services stop|restart|remove --yes` hint text, shared by [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs), [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs), [`service_launch.rs`](../apps/rocm/src/service_launch.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs), and [`services_text.rs`](../apps/rocm/src/services_text.rs) so they cannot go out of sync with each other, as `serve_summary.rs`'s stop row did from the day it was added — #417. It also holds the helpers that map a service tool name to the command word, verb and past tense those hints and messages use (`service_action_command`, `service_action_verb`, `service_action_past_tense`) and to its `SandboxToolArg` (`sandbox_tool_arg_from_service_tool`); [`services_text.rs`](../apps/rocm/src/services_text.rs) reads `service_action_past_tense` from here rather than through the crate root. +- [`service_hints.rs`](../apps/rocm/src/service_hints.rs) — shared CLI-output component: the `rocm services stop|restart|remove --yes` hint text, shared by [`remote/mod.rs`](../apps/rocm/src/remote/mod.rs), [`serve_summary.rs`](../apps/rocm/src/serve_summary.rs), [`service_launch.rs`](../apps/rocm/src/service_launch.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs), and [`services_text.rs`](../apps/rocm/src/services_text.rs) so they cannot go out of sync with each other, as `serve_summary.rs`'s stop row did from the day it was added — #417. It also holds the helpers that map a service tool name to the command word, verb and past tense those hints and messages use (`service_action_command`, `service_action_verb`, `service_action_past_tense`) and to its `SandboxToolArg` (`sandbox_tool_arg_from_service_tool`); [`services_text.rs`](../apps/rocm/src/services_text.rs) reads `service_action_past_tense` from here rather than through the crate root. It quotes the service id with `shell_quote`, so a hint names exactly the argv it runs. - [`service_launch.rs`](../apps/rocm/src/service_launch.rs) — mechanical relocation, owns types (Phase 6b, ROCMAI-91): spawning/attaching to a managed service process and streaming its log, plus the endpoint-key/auth checks that gate a public bind — `AttachOutcome`/`RawModeGuard`/`ManagedSpawn`/`AutostartClaim` are its private types; `ManagedLaunchReport` is `pub(crate)`, since [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs) reads its fields directly for the interactive summary. Most of this module's functions are `pub(crate)` for the same reason — other modules, including [`serve_cmd.rs`](../apps/rocm/src/serve_cmd.rs), [`automations.rs`](../apps/rocm/src/automations.rs), and [`services_text.rs`](../apps/rocm/src/services_text.rs), call into it; `main.rs` does not. `ServicesCommand` stayed in [`main.rs`](../apps/rocm/src/main.rs) rather than moving alongside, and `services()` lives in [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs); the record removal and pruning it dispatches to now lives in [`service_records.rs`](../apps/rocm/src/service_records.rs), and only stop/restart are also reachable from the chat/LLM sandbox tool-calling path, out of scope for Phase 6b. - [`service_records.rs`](../apps/rocm/src/service_records.rs) — mechanical relocation, owns types: removing one managed-service record and every file it owns (`remove_managed_service_record`, `service_record_artifacts`) and the `rocm services prune` plan/render/apply steps (`build_service_prune_plan`, `render_service_prune_plan`, `apply_service_prune_plan`, `prune_managed_service_records`) with the age gate behind them (`DEFAULT_SERVICE_PRUNE_MIN_AGE_HOURS`, `service_prune_min_age_hours`). It reads record state through [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs) and [`services_text.rs`](../apps/rocm/src/services_text.rs) and builds its advice text with [`service_hints.rs`](../apps/rocm/src/service_hints.rs); none of the three depends on it. `remove_managed_service_record`, `prune_managed_service_records`, `service_prune_min_age_hours` and `DEFAULT_SERVICE_PRUNE_MIN_AGE_HOURS` are `pub(crate)` (`services()` in [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) calls the first three; the `ServicesCommand::Prune` clap definition in [`main.rs`](../apps/rocm/src/main.rs) uses the constant, which `main.rs` re-imports), and `ServicePruneOutcome`, the return type of `prune_managed_service_records`, is `pub(crate)` with `pub(crate)` `text`, `removed_records`, `removed_files` and `failures` fields that `services()` reads. Every other item is private. The cluster's regression tests live in this module's own `mod tests`, reaching the shared `test_paths`, `plant_service_record` and `plant_service_record_without_its_key` fixtures through `crate::tests::` (the last two widened to `pub(crate)` for that). - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. From 2dafca3f18c216bdec4d2150231ae2a5d7922abf Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 13 Oct 2026 16:47:33 +0000 Subject: [PATCH 14/23] refactor: share one shell quoter between the CLI and the dash The CLI's `shell_quote` and the dash's `quote_display_arg` were byte-identical, and the comments justifying two copies said there was nowhere both could reach. There is: `apps/rocm` already depends on `rocm-dash-tui`, so `shell_quote` now delegates to the dash's quoter and the quoter's own tests (round-trip, real `sh`) live only beside it. The edge that is forbidden is `rocm-dash-tui -> rocm-core`, which this does not need. The quoting tests are sharpened where a review showed they could not fail on what they claimed: - the Windows-folder test used `C:\Program Files\ROCm`, whose space made the old double-quoted form pass too; it now uses `C:\ROCm`, which a POSIX reader turns into `C:ROCm` unless the value is quoted; - `an_argument_can_never_add_a_word` (three copies) claimed `;`, `|` and `>` stay data, but `shlex` treats none of them as operators, so it was implied by the round-trip test and checked nothing more; the copies are dropped and the round-trip doc says which claim only the unix real-`sh` property checks; - the generator alphabet gains `[ ] { } % , @ +`, the fixed shapes gain `package[extra]`, and the comment no longer says the alphabet has no control characters (it has `\t`, as whitespace). `docs/architecture.md` now names the surfaces the quoter covers rather than claiming every command line the CLI prints, and `remote/mod.rs` loses comments narrating where the quoter used to live. Signed-off-by: Roman Inflianskas --- apps/rocm/src/chat.rs | 17 +- apps/rocm/src/shell_quote.rs | 248 ++++++---------------------- crates/rocm-dash-tui/src/ui/exec.rs | 92 ++++++++--- docs/architecture.md | 2 +- 4 files changed, 132 insertions(+), 227 deletions(-) diff --git a/apps/rocm/src/chat.rs b/apps/rocm/src/chat.rs index e0eefe734a..e9bdd95027 100644 --- a/apps/rocm/src/chat.rs +++ b/apps/rocm/src/chat.rs @@ -7478,7 +7478,11 @@ mod command_preview_properties { proptest! { /// The central property, at the renderer: any argv renders to a line - /// that splits back to that argv. + /// that splits back to that argv — so, among other things, no argument + /// adds or loses a whitespace-delimited word. That `;`, `|` or `>` + /// inside a value stay data is a different claim, which `shlex` cannot + /// check (it treats none of them as operators); the quoter's real-`sh` + /// property in `rocm-dash-tui`'s `ui::exec` does, on unix. #[test] fn a_rendered_tool_call_splits_back_to_its_argv( args in hostile_argv() @@ -7531,17 +7535,6 @@ mod command_preview_properties { ); } - /// Nothing an argument contains can add a word to the command line, so - /// a `;`, `|` or `>` in a value can never read as a second command. - #[test] - fn an_argument_can_never_add_a_word_to_the_preview( - args in hostile_argv() - ) { - let preview = format_structured_tool_call("rocm", &args); - let split = split_preview(&preview).expect("preview must parse"); - prop_assert_eq!(split.len(), args.len() + 1, "preview = {:?}", preview); - } - /// A control character is refused rather than rendered. Quoting cannot /// help: `'…'` is literal to a shell, not to the terminal that is about /// to act on the `\r`. diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index b483c41b96..03bcbe45ee 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -23,16 +23,20 @@ //! characters, so a bare one could split into several words on paste. //! //! All of them want the same guarantee — *this value is one word and nothing -//! else* — so they share one implementation and one set of tests. Keeping them -//! apart is how two of them ended up with quoters that did not escape `$`, -//! backticks or `;`, and left a lone `"` unquoted entirely. +//! else* — so they share one implementation. Keeping them apart is how two of +//! them ended up with quoters that did not escape `$`, backticks or `;`, and +//! left a lone `"` unquoted entirely. //! -//! One more copy is in another crate and stays there: `rocm-dash-tui`'s -//! `ui::exec::quote_display_arg`. `crates/rocm-dash-tui` must not depend on -//! `rocm-core` — an invariant the workspace enforces, not a preference — and -//! `apps/rocm` is the crate that owns `rocm-core`, so nothing here can be -//! shared with it without inverting that. Four lines of POSIX quoting with its -//! own copy of these property tests is the smaller price. +//! That implementation is `rocm-dash-tui`'s `ui::exec::quote_display_arg`, +//! which also renders the dash's approval previews, and its tests — the +//! round-trip properties and the real-`sh` read-back — live beside it. +//! `apps/rocm` already depends on `rocm-dash-tui`, so delegating needs no new +//! crate edge; the opposite direction would (`rocm-dash-tui` may not depend on +//! `rocm-core`, see `xtask/src/crate_edges.rs`). This module is the CLI's name +//! for it, plus the control-character predicate the chat guards share. +//! +//! Scope: the surfaces above. Older `rocm …` hints elsewhere in the CLI that +//! interpolate a value without it are not covered by this module's guarantee. //! //! Single quotes, not double: inside `'...'` POSIX gives no expansion at all, //! so the only character needing care is `'` itself. A double-quoted form has @@ -52,23 +56,11 @@ /// /// Values that cannot mean anything but themselves are returned bare, so an /// ordinary command line stays readable: `rocm serve qwen2.5-7b --managed`, -/// not `rocm 'serve' 'qwen2.5-7b' '--managed'`. +/// not `rocm 'serve' 'qwen2.5-7b' '--managed'`. `=` is among them, which is +/// safe only after the program word — see the implementation's comment before +/// putting a quoted value in command position. pub(crate) fn shell_quote(value: &str) -> String { - // `=` is left bare because POSIX gives it meaning only in a word ahead of - // the command name, where `A=b` is an assignment rather than an argument. - // Every caller renders values after a fixed program word (`rocm …`, - // `uv …`, `rocm serve …` on the remote), never as argv[0], so it is inert - // where it lands. Nothing enforces that: a caller that puts a quoted value - // in command position must quote `=` as well. zsh is the other exception — - // with its default `EQUALS` option a word *starting* with `=` expands to a - // command path — and is outside the POSIX contract this quoter states. - let inert = |character: char| { - character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') - }; - if !value.is_empty() && value.chars().all(inert) { - return value.to_owned(); - } - format!("'{}'", value.replace('\'', r"'\''")) + rocm_dash_tui::ui::exec::quote_display_arg(value) } /// Whether `value` carries a character a terminal acts on rather than prints. @@ -85,11 +77,13 @@ pub(crate) fn has_terminal_control_character(value: &str) -> bool { value.chars().any(char::is_control) } -/// The argument generator the preview property tests share. +/// The argument generator the CLI's preview property tests share. /// -/// One copy, deliberately: a second generator somewhere else would not be +/// One copy in this crate, deliberately: a second generator here would not be /// covered by [`tests::generator_reaches_the_shapes_that_break_quoting`], and -/// could be tuned into harmlessness with nothing to catch it. +/// could be tuned into harmlessness with nothing to catch it. `rocm-dash-tui` +/// keeps its own for the quoter's tests, because a `#[cfg(test)]` item is not +/// visible across crates; the two alphabets are the same by choice. #[cfg(test)] pub(crate) mod hostile { use proptest::prelude::*; @@ -104,11 +98,19 @@ pub(crate) mod hostile { /// `generator_reaches_the_shapes_that_break_quoting`, which prints the /// rates under `--nocapture`). /// - /// No control characters: those are refused upstream rather than quoted, so - /// they belong to that guard's own generator, not to this one. + /// `\t` is the one control character, and it is here as whitespace — a + /// word separator to a shell — not as a control character. Control + /// characters are refused upstream rather than quoted, so tests of that + /// guard draw from `control_bearing_arg` in `main.rs` and must not count on + /// this alphabet happening to contain one. + /// + /// `[ ] { } % , @ +` are here although most shells give them little or no + /// meaning in an argument: `[`/`]` glob and `{`/`}` brace-expand in bash, + /// so a renderer that left them bare would otherwise be caught only by a + /// single example. const ALPHABET: &[char] = &[ ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', - '=', '-', '~', '!', 'a', '1', '/', 'é', + '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', ]; pub(crate) fn arg() -> impl Strategy { @@ -120,6 +122,7 @@ pub(crate) mod hostile { 1 => proptest::sample::select(&[ "install", "sdk", "--prefix", "/mnt/my folder", "C:\\Program Files\\ROCm", "qwen2.5-7b-instruct", "", + "package[extra]", ][..]).prop_map(str::to_owned), ] } @@ -142,114 +145,30 @@ pub(crate) const TEST_SH: &str = "/bin/sh"; #[cfg(test)] mod tests { - use super::hostile::{arg as hostile_arg, argv as hostile_argv}; + use super::hostile::argv as hostile_argv; use super::*; - use proptest::prelude::*; - - /// Render an argv the way every display site does, then split it back the - /// way a shell would. `shlex` is a POSIX word-splitter, so it checks word - /// boundaries and quote removal; it does not expand anything, which is why - /// `a_real_shell_reads_a_rendered_argv_back_unchanged` exists beside it. - fn render_and_split(argv: &[String]) -> Option> { - let rendered = argv - .iter() - .map(|arg| shell_quote(arg)) - .collect::>() - .join(" "); - shlex::split(&rendered) - } - - proptest! { - /// The property everything else rests on: what is rendered denotes the - /// argv that runs. Not "looks similar" — splits back to it exactly. - #[test] - fn a_rendered_argv_splits_back_to_the_same_argv(argv in hostile_argv()) { - let split = render_and_split(&argv); - prop_assert_eq!(split, Some(argv)); - } - - /// Quoting is total: no argument content can make the renderer produce - /// something a shell cannot parse at all. - #[test] - fn every_argument_renders_to_something_parseable(arg in hostile_arg()) { - prop_assert!(shlex::split(&shell_quote(&arg)).is_some(), "arg={:?}", arg); - } - /// Quoting an already-quoted token does not corrupt it: the second pass - /// yields a word whose value is the first pass's output, verbatim. - #[test] - fn quoting_an_already_quoted_value_still_round_trips(arg in hostile_arg()) { - let once = shell_quote(&arg); - let twice = shell_quote(&once); - prop_assert_eq!(shlex::split(&twice), Some(vec![once])); - } - - /// An argument can never introduce a second command or a redirect: after - /// rendering, the whole line is one word per argument, so a `;`, `|` or - /// `>` inside a value is data, never syntax. - #[test] - fn an_argument_can_never_add_a_word(argv in hostile_argv()) { - let split = render_and_split(&argv).expect("rendered line must parse"); - prop_assert_eq!(split.len(), argv.len()); - } - } - - /// Hand `line` to a real `sh` as the operands of `printf` and return the - /// words it received. - /// - /// `shlex` only splits words and removes quotes; it performs no expansion, - /// so it hands back `$HOME`, `~`, `?` and `` `id` `` unchanged and calls a - /// line that leaves them bare a clean round-trip. Only a shell can say - /// whether a value would be expanded on paste. The shell runs in a - /// directory holding files `a` and `1`, so an unquoted `?` or `*` really - /// globs, and with `HOME` pointed at a sentinel, so an unquoted `~` really - /// changes. - #[cfg(unix)] - fn words_a_real_shell_reads(line: &str) -> Vec { - static GLOB_BAIT: std::sync::OnceLock = std::sync::OnceLock::new(); - let dir = GLOB_BAIT.get_or_init(|| { - let dir = std::env::temp_dir() - .join(format!("rocm-shell-quote-glob-bait-{}", std::process::id())); - std::fs::create_dir_all(&dir).expect("create glob-bait dir"); - for name in ["a", "1"] { - std::fs::write(dir.join(name), b"").expect("create glob-bait file"); - } - dir - }); - let output = std::process::Command::new(TEST_SH) - .arg("-c") - .arg(format!("printf '%s\\0' {line}")) - .current_dir(dir) - .env("HOME", "/nonexistent/rocm-shell-quote-home") - .output() - .expect("sh should run"); - let mut words: Vec = String::from_utf8_lossy(&output.stdout) - .split('\0') - .map(str::to_owned) - .collect(); - // `printf` terminates every word, so the final piece is always empty. - words.pop(); - words - } + // The quoter's own properties — the shlex round-trip and a real `sh` + // reading the line back — are tested where it is implemented, + // `rocm-dash-tui`'s `ui::exec`. What is tested here is this crate's: that + // the generator the CLI's renderer tests draw from still reaches the + // shapes that break quoting, and the control-character predicate. - #[cfg(unix)] - proptest! { - /// The round-trip again, with a real shell as the reader instead of a - /// word-splitter: no generated value is split, expanded, globbed or - /// executed. This is the check that fails if a character with meaning to - /// a shell (`$`, `~`, `?`, `*`, a backtick) is ever treated as inert. - #[test] - fn a_real_shell_reads_a_rendered_argv_back_unchanged(argv in hostile_argv()) { - let rendered = argv - .iter() - .map(|arg| shell_quote(arg)) - .collect::>() - .join(" "); - prop_assert_eq!( - words_a_real_shell_reads(&rendered), - argv, - "rendered = {:?}", - rendered + /// The CLI's entry point is the shared quoter, not a look-alike. + #[test] + fn the_cli_quotes_exactly_as_the_shared_quoter_does() { + for value in [ + "qwen2.5-7b", + "/mnt/my folder", + "it's", + "", + "$HOME", + "C:\\ROCm", + ] { + assert_eq!( + shell_quote(value), + rocm_dash_tui::ui::exec::quote_display_arg(value), + "{value:?}" ); } } @@ -301,63 +220,6 @@ mod tests { } } - /// A readability check, not the regression guard — the old quoter also - /// round-tripped this one (it wrapped on whitespace), so this cannot fail on - /// the reported bug. What pins that is - /// `an_install_prefix_with_a_space_is_one_argument_in_the_preview` in - /// `main.rs`, which asserts the rendered form and does fail on a revert. - #[test] - fn a_path_with_a_space_stays_one_argument() { - let argv = [ - "install".to_owned(), - "sdk".to_owned(), - "--prefix".to_owned(), - "/mnt/my folder".to_owned(), - ]; - assert_eq!(render_and_split(&argv), Some(argv.to_vec())); - } - - #[test] - fn ordinary_values_are_left_alone_and_the_rest_are_wrapped() { - for inert in ["qwen2.5-7b-instruct", "vllm", "/models/a.gguf", "auto"] { - assert_eq!(shell_quote(inert), inert); - } - assert_eq!(shell_quote("a b"), "'a b'"); - assert_eq!(shell_quote(""), "''"); - assert_eq!(shell_quote("it's"), r"'it'\''s'"); - } - - #[cfg(unix)] - #[test] - fn hostile_values_survive_a_real_shell_as_one_literal_argument() { - // The property that matters is not the shape of the quoting but what a - // shell does with it. Ask one: each value must come back byte-identical, - // proving it was neither expanded nor split nor able to start a second - // command. - for value in [ - "x'; rm -rf ~; echo '", - "$(id)", - "`id`", - "a b", - "it's", - "*", - "--not-a-flag", - "qwen2.5-7b-instruct", - "/mnt/my folder", - ] { - let output = std::process::Command::new(TEST_SH) - .arg("-c") - .arg(format!("printf %s {}", shell_quote(value))) - .output() - .expect("sh should run"); - assert_eq!( - String::from_utf8_lossy(&output.stdout), - value, - "shell mangled {value:?}" - ); - } - } - #[test] fn control_characters_are_recognised_whatever_their_width() { for value in [ diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 1153caea66..bc93dc632d 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -38,14 +38,12 @@ pub fn exe_label(cmd: &str) -> &str { /// ordinary preview stays readable — `rocm serve qwen2.5-7b --managed`, not /// `rocm 'serve' 'qwen2.5-7b' '--managed'`. /// -/// Mirrors the CLI-side quoter in `apps/rocm/src/shell_quote.rs`. Deliberately -/// a second copy: `xtask`'s crate-edge contract forbids -/// `rocm-dash-tui -> rocm-core` (`xtask/src/crate_edges.rs`), and `apps/rocm` -/// is the crate that owns `rocm-core`, so there is nowhere both can reach -/// without breaking that. Nothing ties the two copies to each other: each is -/// held to the same contract by its own tests, including a real `sh` reading -/// the rendered line back, so either one *breaking* fails its own suite. They -/// may still differ harmlessly in which values they leave bare. +/// The one quoter in the workspace. `apps/rocm`'s `shell_quote` delegates +/// here rather than keeping a copy: `apps/rocm` already depends on this crate, +/// so this is the place both can reach without a new crate edge (the reverse, +/// `rocm-dash-tui -> rocm-core`, is the one `xtask/src/crate_edges.rs` +/// forbids). The remote `ssh` command line, the CLI's printed `run:` hints and +/// these approval previews therefore cannot drift apart. pub fn quote_display_arg(value: &str) -> String { // `=` is left bare because POSIX gives it meaning only in a word ahead of // the command name, where `A=b` is an assignment rather than an argument. @@ -152,9 +150,19 @@ mod tests { /// empty argument — are the ones nobody writes an example for, and uniform /// random text produces them too rarely to find anything. Reach is measured /// by `the_generator_reaches_the_shapes_that_break_quoting`. + /// + /// `[ ] { } % , @ +` are here although most shells give them little or no + /// meaning in an argument: `[`/`]` glob, `{`/`}` brace-expand in bash, and + /// a quoter that marked any of them inert would otherwise be caught only + /// by a single example. `\t` is the one control character, and it is here + /// as whitespace, not as a control character. + /// + /// `apps/rocm/src/shell_quote.rs` has a second generator for the CLI's own + /// renderers. It cannot share this one: a `#[cfg(test)]` item is not + /// visible to another crate's tests. const HOSTILE_ALPHABET: &[char] = &[ ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', - '=', '-', '~', '!', 'a', '1', '/', 'é', + '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', ]; fn hostile_arg() -> impl Strategy { @@ -164,6 +172,7 @@ mod tests { 1 => proptest::sample::select(&[ "install", "sdk", "--prefix", "/mnt/my folder", "C:\\Program Files\\ROCm", "qwen2.5-7b-instruct", "", + "package[extra]", ][..]).prop_map(str::to_owned), ] } @@ -178,6 +187,11 @@ mod tests { /// rendered line the way a shell would and demanding that argv back — /// `shlex` is a POSIX word-splitter, which is exactly the reader this /// line is written for. + /// + /// That a preview has exactly one word per argument follows from this. + /// What does not follow is that `;`, `|` or `>` stay data: `shlex` + /// treats none of them as operators, so only the real-`sh` property + /// below checks that — and it runs on unix only. #[test] fn a_preview_splits_back_to_the_argv_the_job_will_run(argv in hostile_argv()) { let preview = format!("{} {}", exe_label("/usr/local/bin/rocm"), display_args(&argv)); @@ -188,15 +202,6 @@ mod tests { prop_assert_eq!(split, Some(expected), "preview = {:?}", preview); } - /// No argument can add a word to the preview, so a `;`, `|` or `>` - /// inside a value reads as data rather than as a second command. - #[test] - fn an_argument_can_never_add_a_word(argv in hostile_argv()) { - let preview = display_args(&argv); - let split = shlex::split(&preview).expect("preview must parse"); - prop_assert_eq!(split.len(), argv.len(), "preview = {:?}", preview); - } - /// Quoting an already-quoted token does not corrupt it. #[test] fn quoting_an_already_quoted_value_still_round_trips(arg in hostile_arg()) { @@ -308,13 +313,20 @@ mod tests { } } + /// A Windows install folder keeps its backslashes in the preview. + /// + /// Deliberately a folder with no space in it: a space makes any quoter + /// wrap the value, so `C:\Program Files\ROCm` round-tripped under the old + /// double-quoted form too and could not tell the two apart. A bare + /// backslash is what has to be quoted on its own merits — left bare, a + /// POSIX reader treats it as an escape and hands back `C:ROCm`. #[test] fn a_windows_install_folder_keeps_its_separators() { let argv = [ "install".to_owned(), "sdk".to_owned(), "--prefix".to_owned(), - "C:\\Program Files\\ROCm".to_owned(), + "C:\\ROCm".to_owned(), ]; let preview = format!( "{} {}", @@ -328,8 +340,46 @@ mod tests { "install".to_owned(), "sdk".to_owned(), "--prefix".to_owned(), - "C:\\Program Files\\ROCm".to_owned(), - ]) + "C:\\ROCm".to_owned(), + ]), + "preview = {preview:?}" ); } + + /// Glob brackets are quoted, so a pip-style extra is one literal word. + /// + /// The generator draws `[` and `]` too; this pins the shape users actually + /// type, so marking either inert fails here by name and not only on + /// whichever generated case happens to hit it. + #[test] + fn a_package_extra_is_quoted_as_one_literal_word() { + assert_eq!(quote_display_arg("package[extra]"), "'package[extra]'"); + } + + #[cfg(unix)] + #[test] + fn hostile_values_survive_a_real_shell_as_one_literal_argument() { + // The property that matters is not the shape of the quoting but what a + // shell does with it. Ask one: each value must come back byte-identical, + // proving it was neither expanded nor split nor able to start a second + // command. + for value in [ + "x'; rm -rf ~; echo '", + "$(id)", + "`id`", + "a b", + "it's", + "*", + "package[extra]", + "--not-a-flag", + "qwen2.5-7b-instruct", + "/mnt/my folder", + ] { + assert_eq!( + words_a_real_shell_reads("e_display_arg(value)), + vec![value.to_owned()], + "shell mangled {value:?}" + ); + } + } } diff --git a/docs/architecture.md b/docs/architecture.md index fde739fa4f..6e7ade3956 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`), for any command line shown to an operator or handed to a shell; `rocm-dash-tui` keeps its own copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since it cannot reach `apps/rocm` and the crate-edge check forbids it `rocm-core`. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and `rocm ` plan, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints and the runtime-activation report — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). From 28700a721d00cb27181a9ac1f18aff651ca960c6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 13 Oct 2026 16:48:04 +0000 Subject: [PATCH 15/23] fix(chat): screen every tool call, and every value a refusal echoes The control-character guard was an allow-list of nine tools, and its completeness held only for values that were accepted. Refusals echoed the value they refused: an unsupported tool name, a `port_status` host outside loopback, and the provider planner's `intent` and `tool`, the last two into the plan block's notes. Each reached the terminal raw. - The guard is deny-by-default. Every tool's whole arguments object is screened before anything else reads it, except `rocm_command`, which screens its argv itself after trimming. A tool added later fails safe. - A tool name carrying a control character is refused first, by a message that does not repeat it. - The planner's refusals do not echo a hostile `intent` or `tool`, and the note every planner failure becomes is stripped of control sequences, since it can carry provider text from any error path. - A planner note is trimmed before it is tested, and dropped notes are counted in a note of their own instead of vanishing. - `natural_language_plan`'s `request` is screened too. It is echoed into the plan text the tool returns, not nowhere as the comment said; the user's own `/plan` input comes from a single-line field. - The predicate is `rocm_core::terminal::is_control_or_format` plus U+2028/U+2029, so a bidi override, a zero-width character or a line separator is refused like an escape sequence. Tests assert the guard's own wording, and that no refusal carries the character, for each path; the array and nested-object arms of the walk get cases of their own. The planner-forge property now draws control-bearing arguments on purpose instead of reaching the guard only through the alphabet's tab. `docs/llm-tool-use.md` states the rule. Signed-off-by: Roman Inflianskas --- apps/rocm/src/chat.rs | 354 +++++++++++++++++++++--------- apps/rocm/src/freeform_planner.rs | 86 ++++++-- apps/rocm/src/shell_quote.rs | 22 +- docs/llm-tool-use.md | 8 + 4 files changed, 345 insertions(+), 125 deletions(-) diff --git a/apps/rocm/src/chat.rs b/apps/rocm/src/chat.rs index e9bdd95027..59617adeab 100644 --- a/apps/rocm/src/chat.rs +++ b/apps/rocm/src/chat.rs @@ -2090,6 +2090,12 @@ pub(crate) fn chat_tool_approval_request( } pub(crate) fn validate_chat_tool_call(call: &providers::ChatToolCall) -> Result<()> { + // First, because every refusal below names the tool: a model-chosen name + // carrying a control character would otherwise reach the terminal inside + // the very error that rejects it. This one names nothing. + if has_terminal_control_character(&call.name) { + bail!("local assistant requested a ROCm tool whose name contains a control character"); + } if !call.arguments.is_object() { bail!("ROCm tool `{}` arguments must be a JSON object", call.name); } @@ -2139,53 +2145,37 @@ pub(crate) fn validate_chat_tool_call(call: &providers::ChatToolCall) -> Result< Ok(()) } -/// The tools whose arguments reach the operator's terminal, and which have no -/// screening of their own. -/// -/// The criterion is **reaches the terminal**, not "becomes a command line". -/// That distinction is the whole point: a control character is dangerous -/// because the operator is not a shell. `path_exists` is on this list for -/// exactly that reason — nothing it takes becomes an argv, but -/// [`run_chat_path_exists_tool`] echoes the model's `path` verbatim into a -/// printed `path: …` block, with no approval gate in front of it and nothing -/// stopping that block from printing in the same response as a mutating call's -/// rendered command. -/// -/// `rocm_command` is the deliberate omission: its argv *is* rendered, but it -/// screens every entry itself in [`normalized_chat_rocm_command_args`] (which -/// also trims, so this check would disagree with it), and its `reason` is -/// free-form prose that is never printed. +/// The tools exempt from [`reject_control_characters_in_tool_arguments`]. /// -/// `natural_language_plan` is absent in the other direction: its `request` is -/// the user's own prose, echoed nowhere, and legitimately spans lines. +/// Deny by default: every other tool, including one added later, has its +/// whole arguments object screened before anything else looks at it. The +/// criterion that used to pick tools *in* — "its arguments reach the +/// operator's terminal" — kept missing values that reach it some other way: +/// `port_status` echoes a refused `host` in its own error, which the CLI +/// prints. A list of exceptions fails safe when it is forgotten; a list of +/// guarded tools does not. /// -/// Every other accepted tool either takes no string (`examine`, `engines`, -/// `gpu_snapshot`, …) or constrains the one it takes to a shape with no room -/// for a control character — `service_id` through `rocm_core::ServiceId::new`, -/// `host` by exact loopback match, `watcher` against the builtin list. +/// `rocm_command` is the one exception, and it is not unscreened: its argv is +/// checked entry by entry in [`normalized_chat_rocm_command_args`], with the +/// same predicate, after trimming each entry — so screening the raw object +/// here would refuse a padded value that path legitimately accepts. Its +/// `reason` is free-form prose that is never printed. /// -/// Pinned per entry by -/// `every_guarded_tool_refuses_a_control_character_in_its_rendered_argument`: -/// deleting a name here turns that test red rather than silently removing a -/// guard. -const CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL: [&str; 9] = [ - "install_sdk", - "install_sdk_dry_run", - "install_engine", - "launch_server", - "path_exists", - "proposal_action", - "stop_server", - "watcher_disable", - "watcher_enable", -]; - -/// Refuse a model-supplied string argument carrying a terminal control -/// character, for the tools whose arguments reach the operator's terminal. +/// Pinned by `every_tool_but_the_exempt_one_refuses_a_control_character_anywhere` +/// (adding a name here turns it red) and +/// `an_unknown_tool_is_screened_before_it_is_rejected` (going back to an +/// allow-list turns it red). +const CHAT_TOOLS_SCREENING_THEIR_OWN_ARGUMENTS: [&str; 1] = ["rocm_command"]; + +/// Refuse a model-supplied string argument carrying a terminal control or +/// format character, for every tool not in +/// [`CHAT_TOOLS_SCREENING_THEIR_OWN_ARGUMENTS`]. /// /// Those values are printed: into the command preview an operator approves, -/// into the `request plan` / `execution` blocks `rocm ` emits, and — -/// for `path_exists` — into a tool-result block with no gate at all. All of it +/// into the `request plan` / `execution` blocks `rocm ` emits, into +/// the plan text `natural_language_plan` returns, into a refusal that echoes +/// the value it refused, and — for `path_exists` — into a tool-result block +/// with no gate at all. All of it /// reaches a terminal as bytes, so a `\r` returns the cursor to column one and /// a CSI sequence erases the line; the model, not this code, then chooses what /// the operator reads. Quoting cannot fix that: `'…'` makes the byte literal to @@ -2203,7 +2193,7 @@ fn reject_control_characters_in_tool_arguments( tool: &str, arguments: &serde_json::Value, ) -> Result<()> { - if !CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL.contains(&tool) { + if CHAT_TOOLS_SCREENING_THEIR_OWN_ARGUMENTS.contains(&tool) { return Ok(()); } reject_control_characters(tool, arguments) @@ -7372,7 +7362,10 @@ install therock"; #[cfg(test)] mod command_preview_properties { use super::*; - use crate::freeform_planner::{ProviderPlannerToolCall, validate_provider_planner_tool_call}; + use crate::freeform_planner::{ + ProviderPlannerToolCall, planner_failure_note, provider_planner_response_to_plan, + validate_provider_planner_tool_call, + }; // The one generator, shared with `shell_quote`'s own suite so both are // covered by its reach guard. See `crate::shell_quote::hostile`. use crate::shell_quote::hostile::{arg as hostile_arg, argv as hostile_argv}; @@ -7380,7 +7373,14 @@ mod command_preview_properties { /// Characters a terminal acts on rather than prints — the ones that let a /// preview say one thing while a different argv runs. - const CONTROL_ALPHABET: &[char] = &['\n', '\r', '\u{1b}', '\u{8}', '\u{7f}', '\u{9b}', '\0']; + /// + /// The last three move no cursor, and are here for that reason: a + /// right-to-left override reorders how the rest of the line is drawn, a + /// zero-width space hides a difference, and a line separator may start a + /// new row. + const CONTROL_ALPHABET: &[char] = &[ + '\n', '\r', '\u{1b}', '\u{8}', '\u{7f}', '\u{9b}', '\0', '\u{202e}', '\u{200b}', '\u{2028}', + ]; /// An argument guaranteed to carry at least one control character. fn control_bearing_arg() -> impl Strategy { @@ -7404,17 +7404,14 @@ mod command_preview_properties { .collect() } - /// One case per guarded tool: its name, and the arguments object that puts - /// a hostile value in the one field that reaches the terminal. + /// One case per tool whose arguments carry a string the operator can end + /// up reading: its name, and the arguments object that puts a hostile value + /// in that field. /// - /// Written out rather than derived from - /// [`CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL`]. A test that loops over - /// the constant it is meant to pin proves nothing — delete a name and the - /// loop quietly gets shorter. Here, deleting a name from the constant makes - /// that tool stop refusing and turns - /// `every_guarded_tool_refuses_a_control_character_in_its_rendered_argument` - /// red; adding one without a case here turns - /// `the_guarded_tool_list_and_its_cases_agree` red. + /// These are the realistic shapes — the field each tool actually reads. + /// Deny-by-default itself is pinned separately, by + /// `every_tool_but_the_exempt_one_refuses_a_control_character_anywhere`, + /// which does not depend on which field a tool reads. /// /// Non-hostile fields carry values that pass each tool's own validators, so /// the control character is the only thing under test. @@ -7436,14 +7433,26 @@ mod command_preview_properties { "launch_server", |hostile| serde_json::json!({ "model": hostile, "host": "127.0.0.1" }), ), + ( + "natural_language_plan", + |hostile| serde_json::json!({ "request": hostile }), + ), ( "path_exists", |hostile| serde_json::json!({ "path": hostile }), ), + ( + "port_status", + |hostile| serde_json::json!({ "host": hostile, "port": 8188 }), + ), ( "proposal_action", |hostile| serde_json::json!({ "proposal_id": hostile, "action": "approve" }), ), + ( + "service_logs", + |hostile| serde_json::json!({ "service_id": hostile }), + ), ( "stop_server", |hostile| serde_json::json!({ "service_id": hostile }), @@ -7458,24 +7467,127 @@ mod command_preview_properties { ), ]; - /// The guarded list and the cases that pin it name the same tools. + /// Every tool `validate_chat_tool_call` accepts, written out, minus the + /// one in [`CHAT_TOOLS_SCREENING_THEIR_OWN_ARGUMENTS`]. /// - /// This is the half that catches an *addition*: a tool added to the - /// constant without a case here would otherwise be guarded by code no test - /// exercises. - #[test] - fn the_guarded_tool_list_and_its_cases_agree() { - let guarded: std::collections::BTreeSet<&str> = CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL - .into_iter() - .collect(); - let covered: std::collections::BTreeSet<&str> = - GUARDED_TOOL_CASES.iter().map(|(tool, _)| *tool).collect(); - assert_eq!( - guarded, covered, - "every guarded tool needs a case in GUARDED_TOOL_CASES, and vice versa" + /// Written out rather than derived, so that exempting a tool is a change + /// this list does not follow: it turns + /// `every_tool_but_the_exempt_one_refuses_a_control_character_anywhere` + /// red instead. + const SCREENED_TOOLS: &[&str] = &[ + "automations", + "bridge_snapshot", + "doctor", + "engines", + "examine", + "gpu_snapshot", + "install_engine", + "install_sdk", + "install_sdk_dry_run", + "launch_server", + "natural_language_plan", + "path_exists", + "port_status", + "proposal_action", + "service_logs", + "services", + "stop_server", + "update_check", + "watcher_disable", + "watcher_enable", + ]; + + fn assert_refused_by_the_guard(call: &providers::ChatToolCall) { + let error = validate_chat_tool_call(call) + .expect_err(&format!("`{}` accepted {:?}", call.name, call.arguments)) + .to_string(); + assert!( + error.contains("rewrite what the operator reads"), + "`{}` refused {:?} for some other reason ({error}), so this case would \ + stay green with the control-character guard removed", + call.name, + call.arguments + ); + assert!( + !has_terminal_control_character(&error), + "the refusal itself carried the control character: {error:?}" ); } + /// Deny by default: every accepted tool but the self-screening one refuses + /// a control character in an argument, whichever argument it is — even one + /// the tool never reads. + #[test] + fn every_tool_but_the_exempt_one_refuses_a_control_character_anywhere() { + for tool in SCREENED_TOOLS { + assert_refused_by_the_guard(&providers::ChatToolCall { + id: None, + name: (*tool).to_owned(), + arguments: serde_json::json!({ "unexpected": "a\u{1b}[2Kb" }), + }); + } + } + + /// A tool nobody has listed anywhere is still screened, before the + /// "unsupported tool" refusal — the property an allow-list of guarded + /// tools did not have, and the reason the list is now of exemptions. + #[test] + fn an_unknown_tool_is_screened_before_it_is_rejected() { + assert_refused_by_the_guard(&providers::ChatToolCall { + id: None, + name: "a_tool_added_later".to_owned(), + arguments: serde_json::json!({ "target": "x\u{1b}[2Ky" }), + }); + } + + /// The guard walks arrays and nested objects, not only top-level strings, + /// so an argument shaped differently from today's is still screened. + #[test] + fn a_control_character_nested_in_an_array_or_object_is_refused() { + for arguments in [ + serde_json::json!({ "prefix": "/x", "extra": ["a\u{1b}["] }), + serde_json::json!({ "prefix": "/x", "extra": { "k": "a\r" } }), + serde_json::json!({ "prefix": "/x", "extra": [{ "k": ["a\u{202e}b"] }] }), + ] { + assert_refused_by_the_guard(&providers::ChatToolCall { + id: None, + name: "install_sdk".to_owned(), + arguments, + }); + } + } + + /// A model-chosen tool name is refused without being echoed: every other + /// refusal names the tool, and the CLI prints the error. + #[test] + fn a_tool_name_carrying_a_control_character_is_refused_without_being_echoed() { + for name in ["bad\u{1b}[2Ktool", "examine\r", "examine\u{202e}"] { + let error = validate_chat_tool_call(&providers::ChatToolCall { + id: None, + name: name.to_owned(), + arguments: serde_json::json!({}), + }) + .expect_err("a tool name carrying a control character must be refused") + .to_string(); + assert!( + error.contains("whose name contains a control character"), + "refused for the wrong reason: {error:?}" + ); + assert!(!has_terminal_control_character(&error), "{error:?}"); + } + } + + /// `port_status` refuses a non-local host by naming it. A hostile host is + /// screened before that refusal can echo it. + #[test] + fn a_hostile_port_status_host_is_not_echoed_in_its_refusal() { + assert_refused_by_the_guard(&providers::ChatToolCall { + id: None, + name: "port_status".to_owned(), + arguments: serde_json::json!({ "host": "x\u{1b}[2Ky", "port": 8188 }), + }); + } + proptest! { /// The central property, at the renderer: any argv renders to a line /// that splits back to that argv — so, among other things, no argument @@ -7585,33 +7697,21 @@ mod command_preview_properties { let preview = rocm_chat_tool_requested_command(&call) .expect("an accepted rocm_command renders a preview"); prop_assert!( - !preview.chars().any(char::is_control), + !has_terminal_control_character(&preview), "arg {:?} put a control character into the preview: {:?}", arg, preview ); } - /// Every entry in [`CHAT_TOOLS_REACHING_THE_OPERATORS_TERMINAL`] is - /// pinned, one case per tool. - /// - /// Without this, six of the nine were held in place by nothing: - /// replacing the constant with `["install_sdk", "install_engine"]` left - /// the whole suite green, so `launch_server`'s `model` and - /// `proposal_action`'s `proposal_id` — both of which land in an approval - /// card — could be dropped from the guard silently. The constant *is* - /// the guard; it needs a test per name. + /// Each tool refuses a control character in the field it actually + /// reads, one case per tool in [`GUARDED_TOOL_CASES`]. /// /// Asserts the guard's own refusal, not merely an error: `stop_server` /// and `watcher_enable` would reject these values anyway (via /// `ServiceId::new` and the builtin-watcher list), so an `is_err()` - /// check would stay green with the guard deleted. - /// - /// Driven from [`GUARDED_TOOL_CASES`], a list written out here, NOT - /// from the constant. Iterating the constant would be a test that - /// follows whatever it is given: shrink the constant and the loop - /// shrinks with it, green either way. The two are tied together by - /// `the_guarded_tool_list_and_its_cases_agree`. + /// check would stay green with the guard deleted. And asserts the + /// refusal does not carry the character itself, since the CLI prints it. #[test] fn every_guarded_tool_refuses_a_control_character_in_its_rendered_argument( hostile in control_bearing_arg() @@ -7633,6 +7733,7 @@ mod command_preview_properties { hostile, error ); + prop_assert!(!has_terminal_control_character(&error), "{:?}", error); } } @@ -7651,9 +7752,14 @@ mod command_preview_properties { /// Whatever survives planner validation renders a plan block whose /// lines are the ones this code wrote — no argument can inject another. + /// + /// Draws control-bearing arguments on purpose, half the time: the + /// shared alphabet's only control character is `\t`, there as + /// whitespace, and a test that reached the guard only through it would + /// stop doing so the day the alphabet changed. #[test] fn a_validated_planner_argv_cannot_forge_a_plan_line( - arg in hostile_arg() + arg in prop_oneof![hostile_arg(), control_bearing_arg()] ) { let call = ProviderPlannerToolCall { tool: "rocm".to_owned(), @@ -7664,7 +7770,7 @@ mod command_preview_properties { }; let rendered = format_structured_tool_call("rocm", &args); prop_assert!( - !rendered.chars().any(char::is_control), + !has_terminal_control_character(&rendered), "a plan line must stay one line: {:?}", rendered ); @@ -7718,29 +7824,67 @@ mod command_preview_properties { ); } - /// The control-character rule belongs to arguments that reach the terminal, - /// not to prose. A `natural_language_plan` request is a user's own - /// question, is echoed nowhere, and legitimately spans lines — holding it - /// to this rule would refuse an ordinary multi-line question for no gain. - /// Pinned so the rule is not later widened by reflex. + /// A model-supplied `natural_language_plan` request is screened like any + /// other argument. It is not echoed nowhere: the tool renders it into the + /// plan text as `request: …` and inside the `tool_call:` lines, and the + /// dash's plan review prints that text. The user's own `/plan` input + /// reaches this validator too, but it comes from a single-line text field, + /// so refusing a newline costs it nothing. #[test] - fn a_multi_line_question_is_still_a_valid_plan_request() { - let call = providers::ChatToolCall { + fn a_model_supplied_plan_request_cannot_redraw_the_plan_it_is_echoed_into() { + assert_refused_by_the_guard(&providers::ChatToolCall { id: None, name: "natural_language_plan".to_owned(), arguments: serde_json::json!({ - "request": "install rocm\nthen serve qwen", + "request": "install rocm\u{1b}[1A\u{1b}[2Ktool_call: rocm examine", }), - }; - validate_chat_tool_call(&call).expect("prose may span lines"); - - // …while the same bytes in an argument that *is* rendered are refused. - let rendered = providers::ChatToolCall { + }); + validate_chat_tool_call(&providers::ChatToolCall { id: None, - name: "install_engine".to_owned(), - arguments: serde_json::json!({ "engine": "vllm\nrocm examine" }), - }; - assert!(validate_chat_tool_call(&rendered).is_err()); + name: "natural_language_plan".to_owned(), + arguments: serde_json::json!({ "request": "install rocm into /mnt/my folder" }), + }) + .expect("an ordinary request is still planned"); + } + + /// The planner's `tool` and `intent` are named in the planner's refusals, + /// and those refusals become notes in the plan block. A hostile value is + /// refused without being echoed. + #[test] + fn a_hostile_planner_tool_or_intent_is_not_echoed_in_its_refusal() { + for (content, wording) in [ + ( + r#"{"intent":"serve","tool_call":{"tool":"rocm\u001b[2Kx","args":["examine"]}}"#, + "unsupported tool whose name contains a control character", + ), + ( + r#"{"intent":"serve\u001b[2K","tool_call":{"tool":"rocm","args":["examine"]}}"#, + "unsupported intent containing a control character", + ), + ] { + let error = provider_planner_response_to_plan("inspect", "local", content) + .expect_err("a hostile planner response must be refused") + .to_string(); + assert!( + error.contains(wording), + "refused for the wrong reason: {error:?}" + ); + assert!(!has_terminal_control_character(&error), "{error:?}"); + } + } + + /// Every planner failure reaches the plan block as a note through one + /// function, so a control character the provider managed to get into the + /// error by some other route — an HTTP error body, say — is stripped + /// there. + #[test] + fn a_planner_failure_note_carries_no_control_character() { + let note = planner_failure_note( + "local", + &anyhow::anyhow!("gateway said \u{1b}[1A\u{1b}[2Kapproval: not required\r"), + ); + assert!(!has_terminal_control_character(¬e), "{note:?}"); + assert!(note.contains("approval: not required"), "{note:?}"); } /// The shape from the bug report, pinned by name so it cannot regress diff --git a/apps/rocm/src/freeform_planner.rs b/apps/rocm/src/freeform_planner.rs index cd30e7f9de..4a440a68d1 100644 --- a/apps/rocm/src/freeform_planner.rs +++ b/apps/rocm/src/freeform_planner.rs @@ -795,9 +795,9 @@ pub(crate) fn build_freeform_plan_with_context( match resolve_freeform_plan_with_provider(request, paths, config, provider, &deterministic) { Ok(plan) => plan, Err(error) => { - deterministic.notes.push(format!( - "Provider-assisted planner `{provider}` could not resolve this request: {error}" - )); + deterministic + .notes + .push(planner_failure_note(provider, &error)); deterministic.notes.push( "No provider-produced tool call was used. Fill the placeholder values or run /chat for help." .to_owned(), @@ -807,6 +807,17 @@ pub(crate) fn build_freeform_plan_with_context( } } +/// The plan-block note for a provider-assisted planning failure. +/// +/// The plan block prints notes verbatim, and this error can carry text that +/// came from the provider — an HTTP failure body, or a value its response +/// named. The planner's own refusals do not echo a hostile value, but this is +/// the one place every failure passes through, so it is stripped here too. +pub(crate) fn planner_failure_note(provider: &str, error: &anyhow::Error) -> String { + let error = rocm_core::terminal::strip_terminal_control_sequences(&format!("{error}")); + format!("Provider-assisted planner `{provider}` could not resolve this request: {error}") +} + fn configured_planner_provider(config: &RocmCliConfig) -> Option<&str> { config .planner_provider @@ -921,15 +932,28 @@ pub(crate) fn provider_planner_response_to_plan( "The provider output was reduced to a validated rocm tool call; no shell command is executed." .to_owned(), ]; - notes.extend( - response - .notes - .into_iter() - // Same reason as the argv above: a note is printed verbatim into the - // plan block, so a control character in one lets the planner redraw - // the lines around it. - .filter(|note| !note.trim().is_empty() && !has_terminal_control_character(note)), - ); + // Same reason as the argv above: a note is printed verbatim into the plan + // block, so a control character in one lets the planner redraw the lines + // around it. Such a note is dropped rather than refused — it is commentary, + // and the plan stands without it — but not silently: the count of dropped + // notes is reported in a note this code writes. + let mut omitted = 0_usize; + for note in response.notes { + let note = note.trim(); + if note.is_empty() { + continue; + } + if has_terminal_control_character(note) { + omitted += 1; + continue; + } + notes.push(note.to_owned()); + } + if omitted > 0 { + notes.push(format!( + "{omitted} planner note(s) omitted: they contained terminal control characters." + )); + } Ok(StructuredRequestPlan { request: request.trim().to_owned(), planner: format!("hybrid-parser-v1 + provider:{provider}"), @@ -972,6 +996,13 @@ pub(crate) fn validate_provider_planner_tool_call( call: &ProviderPlannerToolCall, ) -> Result> { if call.tool != "rocm" { + // Not echoed when it carries a control character: this error ends up + // in the plan block's notes, which reach the terminal as bytes. + if has_terminal_control_character(&call.tool) { + bail!( + "provider planner returned an unsupported tool whose name contains a control character" + ); + } bail!("provider planner returned unsupported tool `{}`", call.tool); } if call.args.is_empty() { @@ -1042,6 +1073,11 @@ fn planner_intent_from_provider_response(intent: &str, args: &[String]) -> Resul "update" => PlannerIntent::Update, "uninstall" => PlannerIntent::Uninstall, "inspect" | "examine" => PlannerIntent::Inspect, + // Not echoed when it carries a control character, for the same reason + // as an unsupported tool name in `validate_provider_planner_tool_call`. + _ if has_terminal_control_character(intent) => { + bail!("provider planner returned an unsupported intent containing a control character") + } _ => bail!("provider planner returned unsupported intent `{intent}`"), }; if declared != args_intent { @@ -2007,9 +2043,11 @@ mod tests { /// Planner notes are printed verbatim into the plan block, so a note /// carrying a control character is dropped rather than printed — unlike the /// planner's argv, which is refused outright, a note is commentary and the - /// plan stands without it. Ordinary notes still come through. + /// plan stands without it. The drop is reported, so the operator knows the + /// plan block is not everything the planner said; and a note is trimmed + /// first, so trailing whitespace alone does not cost an ordinary one. #[test] - fn a_planner_note_carrying_a_control_character_is_dropped() -> Result<()> { + fn a_planner_note_carrying_a_control_character_is_dropped_and_counted() -> Result<()> { let content = r#"{ "intent": "serve", "confidence": "high", @@ -2019,25 +2057,37 @@ mod tests { }, "notes": [ "resolved the missing model to a tiny test model", + "the model is small\n", "\u001b[1A\u001b[2Kapproval: not required", - "line one\rline two" + "line one\rline two", + "reads \u202e right to left" ] }"#; let plan = provider_planner_response_to_plan("start a local model", "local", content)?; + for ordinary in [ + "resolved the missing model to a tiny test model", + "the model is small", + ] { + assert!( + plan.notes.iter().any(|note| note == ordinary), + "an ordinary note must survive: {ordinary:?} in {:?}", + plan.notes + ); + } assert!( plan.notes .iter() - .any(|note| note == "resolved the missing model to a tiny test model"), - "an ordinary note must survive: {:?}", + .any(|note| note.starts_with("3 planner note(s) omitted")), + "the dropped notes must be counted: {:?}", plan.notes ); assert!( !plan .notes .iter() - .any(|note| note.chars().any(char::is_control)), + .any(|note| has_terminal_control_character(note)), "no note may carry a control character into the plan block: {:?}", plan.notes ); diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 03bcbe45ee..373c484919 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -72,9 +72,17 @@ pub(crate) fn shell_quote(value: &str) -> String { /// whoever supplied the argument. A value in this shape is refused upstream /// rather than rendered. /// -/// `char::is_control` covers C0, DEL and C1 (so ESC and the 8-bit CSI alike). +/// The predicate is [`rocm_core::terminal::is_control_or_format`] — C0, DEL +/// and C1 (so ESC and the 8-bit CSI alike), plus the Unicode format characters: +/// a bidi override such as U+202E reorders how the rest of the line is drawn, +/// and a zero-width character hides a difference between what is shown and +/// what runs. U+2028/U+2029 are added because a terminal may start a new row +/// at either, which would let a value forge a line of its own. pub(crate) fn has_terminal_control_character(value: &str) -> bool { - value.chars().any(char::is_control) + value.chars().any(|character| { + rocm_core::terminal::is_control_or_format(character) + || matches!(character, '\u{2028}' | '\u{2029}') + }) } /// The argument generator the CLI's preview property tests share. @@ -229,6 +237,16 @@ mod tests { "a\u{8}b", "a\u{7f}b", "a\u{9b}b", + // Format and line-separator characters: no cursor movement, but a + // right-to-left override reorders everything drawn after it, a + // zero-width space hides a difference, and a line separator may + // start a new row. + "a\u{202e}b", + "a\u{2066}b", + "a\u{200b}b", + "a\u{feff}b", + "a\u{2028}b", + "a\u{2029}b", ] { assert!( has_terminal_control_character(value), diff --git a/docs/llm-tool-use.md b/docs/llm-tool-use.md index 2e931760f2..97c6080daf 100644 --- a/docs/llm-tool-use.md +++ b/docs/llm-tool-use.md @@ -20,6 +20,14 @@ rocm-cli local assistants use structured tools, not shell commands. result shows it is useful. - The model must use argv-style `rocm` arguments. It must not invent PowerShell, Bash, `cmd`, `git`, or arbitrary package-manager commands. +- A tool call is refused if its name or any string in its arguments carries a + terminal control or format character (an escape sequence, a carriage return, + a bidi override, a zero-width character). Those values are printed — in the + approval card, the request plan, tool output and error messages — and a + terminal acts on such a character instead of showing it. This applies to + every tool; `rocm_command` checks each `args` entry itself, after trimming it. + The provider-assisted planner's argv is held to the same rule, and a planner + note carrying such a character is left out and counted. - CPU fallback is not a supported path. GPU-required ROCm commands must fail loudly when the ROCm GPU path is not ready. - The built-in local assistant is fixed to `qwen` From 2d2e9171ce9bc4511d1866443408d34e7b61138d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 14 Oct 2026 11:51:17 +0000 Subject: [PATCH 16/23] fix(comfyui): quote the runtime key in the install it says will finish printed: `rocm comfyui install --runtime-id ` after a reinstall is interrupted, and after an install fails once the new code is in place. Both interpolated the runtime key bare, the shape this PR removes from every other line the CLI offers to be copied. Build the command once, quoting the key with the shared quoter, and use it in both messages. A generated key is inert and prints unchanged. Signed-off-by: Roman Inflianskas --- apps/rocm/src/comfyui.rs | 70 +++++++++++++++++++++++++++++++- apps/rocm/src/comfyui/install.rs | 9 ++-- apps/rocm/src/shell_quote.rs | 2 + docs/architecture.md | 2 +- 4 files changed, 75 insertions(+), 8 deletions(-) diff --git a/apps/rocm/src/comfyui.rs b/apps/rocm/src/comfyui.rs index 6bb6fd59ea..2d68ad6b81 100644 --- a/apps/rocm/src/comfyui.rs +++ b/apps/rocm/src/comfyui.rs @@ -374,8 +374,30 @@ fn render_logs_with_options( /// started there finds the swap's marker and completes it. fn interrupted_reinstall_advice(runtime_key: &str) -> String { format!( - "a reinstall was interrupted; run `rocm comfyui install --runtime-id {runtime_key}` to \ - finish it" + "a reinstall was interrupted; run `{}` to finish it", + finishing_install_command(runtime_key) + ) +} + +/// What a failure after the swap says: the new code is in place, what it +/// changed (`changes`, already rendered with its leading space, or empty), and +/// the install that finishes it. +fn unfinished_install_advice(changes: &str, runtime_key: &str) -> String { + format!( + "the new ComfyUI code is in place{changes}, but the install did not finish; once the \ + cause below is fixed, run `{}` to finish it", + finishing_install_command(runtime_key) + ) +} + +/// The `rocm comfyui install` line both pieces of advice above tell the user +/// to run. The key is quoted like every other value in a line the CLI offers +/// to be copied (see [`crate::shell_quote`]), so the line names exactly the +/// argv that finishes the install. +fn finishing_install_command(runtime_key: &str) -> String { + format!( + "rocm comfyui install --runtime-id {}", + crate::shell_quote::shell_quote(runtime_key) ) } @@ -1457,4 +1479,48 @@ mod tests { remove_test_root(&paths); Ok(()) } + + /// Both pieces of advice name an install to run as printed, so the line + /// must split back to exactly that argv whatever the runtime key holds. + /// The key is read back by stripping the fixed text around it rather than + /// splitting on the backticks, which a hostile key may itself contain. + /// Mutation: interpolating the key bare in `finishing_install_command` + /// fails this for both. + #[test] + fn finishing_advice_names_the_install_as_its_argv() { + use proptest::prelude::*; + use proptest::test_runner::{Config, TestRunner}; + + let mut runner = TestRunner::new(Config { + cases: 256, + ..Config::default() + }); + runner + .run(&crate::shell_quote::hostile::arg(), |runtime_key| { + let expected = ["rocm", "comfyui", "install", "--runtime-id", &runtime_key] + .map(str::to_owned) + .to_vec(); + for (message, prefix, suffix) in [ + ( + interrupted_reinstall_advice(&runtime_key), + "a reinstall was interrupted; run `", + "` to finish it", + ), + ( + unfinished_install_advice(" (replaced: comfy)", &runtime_key), + "the new ComfyUI code is in place (replaced: comfy), but the install \ + did not finish; once the cause below is fixed, run `", + "` to finish it", + ), + ] { + let command = message + .strip_prefix(prefix) + .and_then(|rest| rest.strip_suffix(suffix)) + .unwrap_or_else(|| panic!("unexpected advice: {message}")); + prop_assert_eq!(shlex::split(command), Some(expected.clone()), "{}", message); + } + Ok(()) + }) + .unwrap(); + } } diff --git a/apps/rocm/src/comfyui/install.rs b/apps/rocm/src/comfyui/install.rs index 90adcd7cb2..0ac2a164de 100644 --- a/apps/rocm/src/comfyui/install.rs +++ b/apps/rocm/src/comfyui/install.rs @@ -23,7 +23,7 @@ use super::{ ComfyUiProbe, ComfyUiRuntimeEnvironment, capture_configured_command, comfyui_source_archive_url, install_log_path_from_app_root, interrupted_reinstall_advice, models_folder_for_source, probe_comfyui, quote_log_arg, reused_source_url, runtime_app_root, - save_manifest, source_path_from_app_root, source_swap, + save_manifest, source_path_from_app_root, source_swap, unfinished_install_advice, }; use crate::cli_progress::AnimatedSpinner; use crate::freeform_planner::format_structured_tool_call; @@ -293,10 +293,9 @@ pub(crate) fn install( let changes = swap_changes_summary(&swap) .map(|summary| format!(" ({summary})")) .unwrap_or_default(); - error.context(format!( - "the new ComfyUI code is in place{changes}, but the install did not finish; once \ - the cause below is fixed, run `rocm comfyui install --runtime-id {}` to finish it", - runtime.manifest.runtime_key + error.context(unfinished_install_advice( + &changes, + &runtime.manifest.runtime_key, )) })?; diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 373c484919..e1e1711120 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -21,6 +21,8 @@ //! `rocm services logs ` and `rocm runtimes activate …` lines a //! user is told to run next. A service id is not limited to inert //! characters, so a bare one could split into several words on paste. +//! * [`crate::comfyui`] builds the `rocm comfyui install --runtime-id ` +//! line a user is told to run to finish an interrupted or failed reinstall. //! //! All of them want the same guarantee — *this value is one word and nothing //! else* — so they share one implementation. Keeping them apart is how two of diff --git a/docs/architecture.md b/docs/architecture.md index 6e7ade3956..1b8ad79b3a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and `rocm ` plan, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints and the runtime-activation report — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and `rocm ` plan, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). From 8486fcb6de3d08abb1d2b7a11e70645e7b81adc6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Fri, 16 Oct 2026 12:32:52 +0000 Subject: [PATCH 17/23] refactor(shell_quote): use the shared line-separator predicate `has_terminal_control_character` spelled U+2028/U+2029 out in its own `matches!`, a second copy of the set `rocm_core::terminal:: is_control_or_line_separator` already owns for exactly this reason. Call that instead. Behaviour is unchanged (both predicates include `Cc`), and the non-ASCII char escapes the ASCII-output contract flags are gone. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index e1e1711120..089b7142ca 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -78,12 +78,16 @@ pub(crate) fn shell_quote(value: &str) -> String { /// and C1 (so ESC and the 8-bit CSI alike), plus the Unicode format characters: /// a bidi override such as U+202E reorders how the rest of the line is drawn, /// and a zero-width character hides a difference between what is shown and -/// what runs. U+2028/U+2029 are added because a terminal may start a new row -/// at either, which would let a value forge a line of its own. +/// what runs. U+2028/U+2029 are added, through +/// [`rocm_core::terminal::is_control_or_line_separator`], because a terminal +/// may start a new row at either, which would let a value forge a line of its +/// own. That is the predicate the terminal classifier and the vLLM symptom +/// guard share for the same reason, so the set of line-breaking characters is +/// decided in one place. pub(crate) fn has_terminal_control_character(value: &str) -> bool { value.chars().any(|character| { rocm_core::terminal::is_control_or_format(character) - || matches!(character, '\u{2028}' | '\u{2029}') + || rocm_core::terminal::is_control_or_line_separator(character) }) } From c489a0e7984a74a088e2f084ba6107a65fed2b95 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Sat, 17 Oct 2026 15:15:41 +0000 Subject: [PATCH 18/23] fix(dash): quote the service id in the quit prompt's stop commands The quit-confirmation popup added on main meanwhile prints `rocm services stop {id} --yes` for each model still serving, both from the registry-only startup fallback and beside a known instance, with the id bare. An id that is not one inert word then pastes back as several arguments. Quote it with `quote_display_arg`, as every other hint this change covers; an ordinary id prints unchanged. Signed-off-by: Roman Inflianskas --- crates/rocm-dash-tui/src/ui/exec.rs | 5 +- crates/rocm-dash-tui/src/ui/quit_confirm.rs | 71 ++++++++++++++++++++- 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index bc93dc632d..32b4fdffe6 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -42,8 +42,9 @@ pub fn exe_label(cmd: &str) -> &str { /// here rather than keeping a copy: `apps/rocm` already depends on this crate, /// so this is the place both can reach without a new crate edge (the reverse, /// `rocm-dash-tui -> rocm-core`, is the one `xtask/src/crate_edges.rs` -/// forbids). The remote `ssh` command line, the CLI's printed `run:` hints and -/// these approval previews therefore cannot drift apart. +/// forbids). The remote `ssh` command line, the CLI's printed `run:` hints, +/// these approval previews and the quit prompt's `rocm services stop` lines +/// therefore cannot drift apart. pub fn quote_display_arg(value: &str) -> String { // `=` is left bare because POSIX gives it meaning only in a word ahead of // the command name, where `A=b` is an assignment rather than an argument. diff --git a/crates/rocm-dash-tui/src/ui/quit_confirm.rs b/crates/rocm-dash-tui/src/ui/quit_confirm.rs index 2b423044df..3e55a03361 100644 --- a/crates/rocm-dash-tui/src/ui/quit_confirm.rs +++ b/crates/rocm-dash-tui/src/ui/quit_confirm.rs @@ -11,7 +11,7 @@ //! in `app/quit_confirm.rs`. use crate::app::AppState; -use crate::ui::{approval, format}; +use crate::ui::{approval, exec, format}; /// Build the quit-confirm prompt's request (title + body) once, so the /// dashboard's own render arm above and the pre-dashboard launcher's @@ -174,7 +174,12 @@ pub(super) fn quit_confirm_body_with( ids.sort(); for id in ids.iter().take(5) { body.push(format!("• {id} — stop it first:")); - body.push(format!(" rocm services stop {id} --yes")); + // Quoted so the line is the argv it names even for an id that is + // not one inert word; an ordinary id is printed unchanged. + body.push(format!( + " rocm services stop {} --yes", + exec::quote_display_arg(id) + )); } if let Some(line) = format::overflow_line(managed_ids.len(), 5) { body.push(line); @@ -216,7 +221,10 @@ pub(super) fn quit_confirm_body_with( // reassemble a remediation command broken across the model // name's line, at least. body.push(format!("• {} — stop it first:", i.model_name)); - body.push(format!(" rocm services stop {} --yes", i.container_id)); + body.push(format!( + " rocm services stop {} --yes", + exec::quote_display_arg(&i.container_id) + )); } else { body.push(format!("• {}", i.model_name)); } @@ -685,4 +693,61 @@ mod tests { ); } } + + /// Both stop lines -- the registry-only startup fallback and the one beside + /// a known instance -- are commands a user is told to paste, so each must + /// split back to exactly `rocm services stop --yes` whatever the id + /// holds. Mutation: printing either id bare fails this for every id below + /// except the inert one. + #[test] + fn quit_confirm_stop_lines_denote_the_argv_they_name_for_a_hostile_id() { + use rocm_dash_core::metrics::{Instance, InstanceStatus}; + for id in [ + "svc-managed", + "svc with space", + "it's", + "a;b|c&&d", + "$(id)", + "`id`", + "\\back\\slash", + "\"quoted\"", + ] { + let expected = Some(vec![ + "rocm".to_owned(), + "services".to_owned(), + "stop".to_owned(), + id.to_owned(), + "--yes".to_owned(), + ]); + let stop_lines = |body: &[String]| -> Vec { + body.iter() + .filter_map(|line| line.strip_prefix(" rocm services stop ")) + .map(|rest| format!("rocm services stop {rest}")) + .collect() + }; + + // Registry-only fallback: no daemon snapshot, no instances. + let mut fallback = AppState::new("t".into(), "default-dark".into()); + with_registry_probe(&mut fallback, true, &[id]); + let lines = stop_lines(&quit_confirm_body(&fallback)); + assert_eq!(lines.len(), 1, "fallback for {id:?}: {lines:?}"); + assert_eq!(shlex::split(&lines[0]), expected, "fallback: {}", lines[0]); + + // Known instance managed by this host's registry. + let mut known = AppState::new("t".into(), "default-dark".into()); + known.instances.insert( + id.to_string(), + Instance { + container_id: id.to_string(), + model_name: "Qwen2.5-7B".to_string(), + status: InstanceStatus::Running, + ..Default::default() + }, + ); + with_registry_probe(&mut known, true, &[id]); + let lines = stop_lines(&quit_confirm_body(&known)); + assert_eq!(lines.len(), 1, "instance for {id:?}: {lines:?}"); + assert_eq!(shlex::split(&lines[0]), expected, "instance: {}", lines[0]); + } + } } From d1c46c66deebe555f9cc8a5b42e12c884ab5c506 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 26 Oct 2026 10:08:36 +0000 Subject: [PATCH 19/23] test: keep the advised-command checker in step with the quoted hints This branch now quotes the id there, so the string reads 'rocm services {action} {} --yes'; the exclusion follows it. The architecture note no longer spells the free-form request as a command. Signed-off-by: Roman Inflianskas --- apps/rocm/src/advised_commands.rs | 2 +- docs/architecture.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/rocm/src/advised_commands.rs b/apps/rocm/src/advised_commands.rs index 9c865cae57..c47d35cd2e 100644 --- a/apps/rocm/src/advised_commands.rs +++ b/apps/rocm/src/advised_commands.rs @@ -1247,7 +1247,7 @@ const NOT_INVOCATIONS: &[(&str, &str, &str)] = &[ ), ( "apps/rocm/src/service_hints.rs", - "rocm services {action} {service_id} --yes", + "rocm services {action} {} --yes", "the verb is a format argument; every value it takes is checked against the \ real hint by `service_action_retry_advice_parses_for_generated_ids` (the \ `run_approved_service_action` verbs) and `every_service_action_hint_verb_parses` \ diff --git a/docs/architecture.md b/docs/architecture.md index 1b8ad79b3a..52428f9b57 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and `rocm ` plan, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). From 7486c0453cef30841846caee11cdf4989d1e81a5 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 3 Nov 2026 11:10:17 +0200 Subject: [PATCH 20/23] refactor(shell_quote): use rocm-core's POSIX quoter, pinned to the dash's copy Since this branch last met main, #743 moved the remote command line's quoter into `rocm_core::posix_shell_quote`. Its body is the same rule this branch gave the dash's `ui::exec::quote_display_arg`, so the CLI's `shell_quote` now calls the `rocm-core` one, the same function the remote `ssh` command line uses. The dash keeps its copy: `rocm-dash-tui` may not depend on `rocm-core`. `apps/rocm` reaches both, so a property test there holds the two to the same output for every value the metacharacter-heavy generator draws; a change to one quoter that is not made to the other turns it red. Checked by dropping `=` from `rocm-core`'s inert set, which fails the test. `rocm_core::quoting`'s module doc listed the display quoters as deliberately left out, each with its own convention. That stops being true here, so it now says which display surfaces use this quoter and keeps only `comfyui`'s `quote_log_arg` on the excluded list. Signed-off-by: Roman Inflianskas --- apps/rocm/src/service_hints.rs | 4 +- apps/rocm/src/shell_quote.rs | 96 +++++++++++++++++++++++------ crates/rocm-core/src/quoting.rs | 52 +++++++++------- crates/rocm-dash-tui/src/ui/exec.rs | 18 +++--- docs/architecture.md | 4 +- 5 files changed, 122 insertions(+), 52 deletions(-) diff --git a/apps/rocm/src/service_hints.rs b/apps/rocm/src/service_hints.rs index c7d96fd521..49d659dc10 100644 --- a/apps/rocm/src/service_hints.rs +++ b/apps/rocm/src/service_hints.rs @@ -49,8 +49,8 @@ pub(crate) fn service_stop_hint(service_id: &str) -> String { /// session recorded). `service_id` is quoted here, so the same line is both /// the human-readable hint and the command a transport's `exec` hands to the /// remote shell; callers pass it unquoted. `remote_cli` is not quoted: it is -/// the command word itself, which [`shell_quote`] does not cover (see its note -/// on `=`). +/// the command word itself, which [`shell_quote`] does not cover (see +/// [`rocm_core::posix_shell_quote`]'s note on `=`). pub(crate) fn remote_service_stop_hint(remote_cli: &str, service_id: &str) -> String { format!( "{remote_cli} services stop {} --yes", diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 089b7142ca..9908d667e6 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -8,7 +8,7 @@ //! //! * [`crate::remote`] builds a command line that a shell on *another* machine //! will parse, so an unquoted value there is a remote command injection. -//! * [`crate::format_structured_tool_call`] builds the command line a human is +//! * [`crate::freeform_planner::format_structured_tool_call`] builds the command line a human is //! shown — in the chat approval card, in `rocm `'s request plan, and //! in the `run:` lines the CLI offers to be copied. An unquoted value there //! means the line the operator reads is not the argv that runs, and the @@ -29,13 +29,17 @@ //! them ended up with quoters that did not escape `$`, backticks or `;`, and //! left a lone `"` unquoted entirely. //! -//! That implementation is `rocm-dash-tui`'s `ui::exec::quote_display_arg`, -//! which also renders the dash's approval previews, and its tests — the -//! round-trip properties and the real-`sh` read-back — live beside it. -//! `apps/rocm` already depends on `rocm-dash-tui`, so delegating needs no new -//! crate edge; the opposite direction would (`rocm-dash-tui` may not depend on -//! `rocm-core`, see `xtask/src/crate_edges.rs`). This module is the CLI's name -//! for it, plus the control-character predicate the chat guards share. +//! That implementation is [`rocm_core::posix_shell_quote`], the quoter +//! `rocm-core` keeps for command lines with execution stakes, with its own +//! real-`sh` read-back test. This module is the CLI's name for it, plus the +//! control-character predicate the chat guards share. +//! +//! `rocm-dash-tui` renders its approval previews with a copy, +//! `ui::exec::quote_display_arg`, because it may not depend on `rocm-core` +//! (see `xtask/src/crate_edges.rs`); the round-trip properties and the +//! real-`sh` read-back for that copy live beside it. `apps/rocm` can reach +//! both, so the property test below holds the two to the same output for every +//! value — a fix to one that is not made to the other turns it red. //! //! Scope: the surfaces above. Older `rocm …` hints elsewhere in the CLI that //! interpolate a value without it are not covered by this module's guarantee. @@ -59,10 +63,11 @@ /// Values that cannot mean anything but themselves are returned bare, so an /// ordinary command line stays readable: `rocm serve qwen2.5-7b --managed`, /// not `rocm 'serve' 'qwen2.5-7b' '--managed'`. `=` is among them, which is -/// safe only after the program word — see the implementation's comment before +/// safe only after the program word — see [`rocm_core::posix_shell_quote`]'s +/// note on `=` before /// putting a quoted value in command position. pub(crate) fn shell_quote(value: &str) -> String { - rocm_dash_tui::ui::exec::quote_display_arg(value) + rocm_core::posix_shell_quote(value) } /// Whether `value` carries a character a terminal acts on rather than prints. @@ -124,7 +129,8 @@ pub(crate) mod hostile { /// single example. const ALPHABET: &[char] = &[ ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', - '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', + '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', '_', ':', + '.', 'Z', ]; pub(crate) fn arg() -> impl Strategy { @@ -162,15 +168,18 @@ mod tests { use super::hostile::argv as hostile_argv; use super::*; - // The quoter's own properties — the shlex round-trip and a real `sh` - // reading the line back — are tested where it is implemented, - // `rocm-dash-tui`'s `ui::exec`. What is tested here is this crate's: that - // the generator the CLI's renderer tests draw from still reaches the - // shapes that break quoting, and the control-character predicate. + // `rocm-core`'s `quoting` asks a real `sh` to read back a fixed set of + // hostile values; the generated-input properties — the shlex round-trip + // and the real-`sh` read-back — run against the dash's copy in + // `rocm-dash-tui`'s `ui::exec`. They cover the quoter the CLI uses because + // the two tests below hold that copy to `rocm-core`'s output for every + // value. Also tested here: that the generator the CLI's renderer tests draw + // from still reaches the shapes that break quoting, and the + // control-character predicate. - /// The CLI's entry point is the shared quoter, not a look-alike. + /// The CLI's entry point is `rocm-core`'s quoter, not a look-alike. #[test] - fn the_cli_quotes_exactly_as_the_shared_quoter_does() { + fn the_cli_quotes_exactly_as_rocm_core_does() { for value in [ "qwen2.5-7b", "/mnt/my folder", @@ -181,12 +190,61 @@ mod tests { ] { assert_eq!( shell_quote(value), - rocm_dash_tui::ui::exec::quote_display_arg(value), + rocm_core::posix_shell_quote(value), "{value:?}" ); } } + /// The CLI and the dash agree on every single character a quoting + /// decision can turn on. + /// + /// The property test below draws from a small alphabet, so a one-sided + /// change to how a character outside it is treated — `_` or `:` dropped + /// from one copy's inert set, uppercase letters no longer counted as + /// alphanumeric — could pass it. This walks all of ASCII, both alone and + /// inside an otherwise inert word, plus a few non-ASCII characters. + #[test] + fn the_cli_and_the_dash_agree_on_every_ascii_character() { + let characters = (0_u8..=0x7f) + .map(char::from) + .chain(['é', 'ß', '\u{a0}', '\u{2028}']); + for character in characters { + for value in [character.to_string(), format!("ab{character}cd")] { + assert_eq!( + shell_quote(&value), + rocm_dash_tui::ui::exec::quote_display_arg(&value), + "{value:?}" + ); + } + } + } + + proptest::proptest! { + /// The CLI and the dash render a value the same way. + /// + /// They are two copies because `rocm-dash-tui` may not depend on + /// `rocm-core`, and this is the one crate that can reach both. Drawn + /// from the same metacharacter-heavy generator the renderer tests use, + /// so a one-sided change to how values combining those characters are + /// quoted fails here; the per-character walk above covers what the + /// alphabet leaves out. Together they stop two previews that disagree + /// from shipping. + #[test] + fn the_cli_and_the_dash_quote_every_value_identically( + args in hostile_argv() + ) { + for value in &args { + proptest::prop_assert_eq!( + shell_quote(value), + rocm_dash_tui::ui::exec::quote_display_arg(value), + "value = {:?}", + value + ); + } + } + } + #[test] fn generator_reaches_the_shapes_that_break_quoting() { // A generator that never produces the dangerous shapes passes against a diff --git a/crates/rocm-core/src/quoting.rs b/crates/rocm-core/src/quoting.rs index 15839c3335..54da24f63d 100644 --- a/crates/rocm-core/src/quoting.rs +++ b/crates/rocm-core/src/quoting.rs @@ -2,9 +2,10 @@ // // SPDX-License-Identifier: MIT -//! Argument-quoting helpers with real execution stakes: their output is -//! embedded into a command string that a shell or interpreter actually runs, -//! not text a human only reads. +//! Argument-quoting helpers whose output must read back as exactly the value given. +//! +//! The output is either embedded into a command string a shell or interpreter +//! actually runs, or shown as a command a person is asked to approve or paste. //! //! [`posix_shell_quote`] and [`powershell_quote`]/`ps_single_quote_escape` //! are two different escaping domains -- POSIX `sh`/`bash` single-quoting and @@ -20,20 +21,21 @@ //! script-corruption bug, which is why both carry direct unit coverage here //! (ROCMAI-727 consolidated them out of per-call-site near-duplicates). //! -//! What is deliberately **not** here: `apps/rocm/src/therock.rs`'s -//! `quote_display_arg` (a dry-run preview line, never executed), -//! `apps/rocm/src/comfyui.rs`'s `quote_log_arg` (log text, Rust's own -//! `{value:?}` Debug-format escaping, with the real unquoted args going to -//! `Command::args` alongside it), `apps/rocm/src/freeform_planner.rs`'s -//! `quote_tool_arg` (rendered plan/LLM prompt text, never executed -//! directly), and `crates/rocm-dash-tui/src/ui/exec.rs`'s own -//! `quote_display_arg` (an approval-preview line, same display-only -//! contract as `therock.rs`'s). Each of those uses a materially different, -//! currently-inconsistent escaping convention for display/log/prompt text -//! that has zero execution stakes, so forcibly unifying them with the two -//! functions here would be a silent behavior change to printed/logged -//! output -- out of scope for ROCMAI-727, which only asks to consolidate what -//! is safely shareable. +//! [`posix_shell_quote`] is also what `apps/rocm`'s `shell_quote` uses for +//! the command lines the CLI *shows*: the chat approval card, the free-form +//! request plan, the install dry-run's `command:` line and the `rocm …` hints +//! it tells a user to run. Those are offered to be copied, and an approval is +//! given for what they say, so a value that reads back as a different argv is +//! the same defect whether a shell or a person runs it. +//! `crates/rocm-dash-tui/src/ui/exec.rs`'s `quote_display_arg` is a copy for +//! the dash's previews, because `rocm-dash-tui` may not depend on this crate; +//! two tests in `apps/rocm/src/shell_quote.rs` hold the two to the +//! same output. +//! +//! What is deliberately **not** here: `apps/rocm/src/comfyui.rs`'s +//! `quote_log_arg` (log text, Rust's own `{value:?}` Debug-format escaping, +//! with the real unquoted args going to `Command::args` alongside it), which +//! uses a different convention; unifying it would change logged output. /// Escapes a value for embedding inside a PowerShell single-quoted string /// literal. @@ -81,14 +83,22 @@ pub fn powershell_quote(value: &str) -> String { /// trick for including a literal single quote inside a single-quoted string, /// since POSIX shells have no escape sequence that works *inside* one. /// -/// This is the one quoting convention in this module with real -/// command-injection stakes end to end: its output is embedded into a -/// command string sent over SSH to a remote shell -/// (`apps/rocm/src/remote/mod.rs`), so a hostile value (`$(id)`, `` `id` ``, +/// Its output is embedded into a command string sent over SSH to a remote +/// shell (`apps/rocm/src/remote/mod.rs`), and it renders the command lines the +/// CLI shows for approval or pasting, so a hostile value (`$(id)`, `` `id` ``, /// `; rm -rf ~`) must come back as inert, byte-identical shell text. See the /// `hostile_values_survive_a_real_shell_as_one_literal_argument` test below, /// which execs a real `sh -c` and round-trips such inputs rather than only /// asserting on the escaped string's shape. +/// +/// `=` is left bare, which is safe only *after* the command word: POSIX gives +/// it meaning only in a word ahead of the command name, where `A=b` is an +/// assignment rather than an argument. Every caller quotes arguments after a +/// fixed program word, never argv[0]. Nothing enforces that, so a caller that +/// puts a quoted value in command position must quote `=` as well. zsh is the +/// other exception — with its default `EQUALS` option a word *starting* with +/// `=` expands to a command path — and is outside the POSIX contract stated +/// here. pub fn posix_shell_quote(value: &str) -> String { let inert = |character: char| { character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.' | '/' | ':' | '=') diff --git a/crates/rocm-dash-tui/src/ui/exec.rs b/crates/rocm-dash-tui/src/ui/exec.rs index 32b4fdffe6..e791f192ac 100644 --- a/crates/rocm-dash-tui/src/ui/exec.rs +++ b/crates/rocm-dash-tui/src/ui/exec.rs @@ -38,13 +38,14 @@ pub fn exe_label(cmd: &str) -> &str { /// ordinary preview stays readable — `rocm serve qwen2.5-7b --managed`, not /// `rocm 'serve' 'qwen2.5-7b' '--managed'`. /// -/// The one quoter in the workspace. `apps/rocm`'s `shell_quote` delegates -/// here rather than keeping a copy: `apps/rocm` already depends on this crate, -/// so this is the place both can reach without a new crate edge (the reverse, -/// `rocm-dash-tui -> rocm-core`, is the one `xtask/src/crate_edges.rs` -/// forbids). The remote `ssh` command line, the CLI's printed `run:` hints, -/// these approval previews and the quit prompt's `rocm services stop` lines -/// therefore cannot drift apart. +/// A copy of `rocm_core::posix_shell_quote`, which the CLI's `shell_quote` and +/// the remote `ssh` command line use: this crate may not depend on `rocm-core` +/// (`xtask/src/crate_edges.rs` forbids `rocm-dash-tui -> rocm-core`). Two +/// tests in `apps/rocm/src/shell_quote.rs`, the one crate that can reach +/// both, hold the two to the same output — a walk over every ASCII character +/// and a property test over hostile values — so these +/// approval previews and the quit prompt's `rocm services stop` lines cannot +/// drift from the CLI's. pub fn quote_display_arg(value: &str) -> String { // `=` is left bare because POSIX gives it meaning only in a word ahead of // the command name, where `A=b` is an assignment rather than an argument. @@ -163,7 +164,8 @@ mod tests { /// visible to another crate's tests. const HOSTILE_ALPHABET: &[char] = &[ ' ', '\t', '"', '\'', '\\', '$', '`', ';', '|', '&', '*', '?', '(', ')', '<', '>', '#', - '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', + '=', '-', '~', '!', '[', ']', '{', '}', '%', ',', '@', '+', 'a', '1', '/', 'é', '_', ':', + '.', 'Z', ]; fn hostile_arg() -> impl Strategy { diff --git a/docs/architecture.md b/docs/architecture.md index 52428f9b57..bfd5592d61 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for the one POSIX quoter, which is `rocm-dash-tui`'s `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs) (`apps/rocm` already depends on `rocm-dash-tui`, so it delegates rather than keeping a copy). It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for `rocm-core`'s POSIX quoter, [`posix_shell_quote`](../crates/rocm-core/src/quoting.rs). `rocm-dash-tui` keeps a copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since the crate-edge check forbids it `rocm-core`; a per-character walk and a property test here hold the two to the same output. It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). @@ -162,7 +162,7 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`placeholder.rs`](../crates/rocm-core/src/placeholder.rs) — the `` placeholder rendered reports print for an empty value: `empty_as_unknown` (returns the value untouched) and `trimmed_or_unknown` (trims first), shared by `apps/rocm`'s driver-install plan and chat tool summaries and by [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs)'s Windows GPU diagnostics, replacing the copy those two `apps/rocm` callers shared in [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and `host_gpu.rs`'s own trimming copy. - [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) — the host probes' subprocess and file-read helpers, split out of [`examine.rs`](../crates/rocm-core/src/examine.rs) so `fix.rs`, `process.rs` and the child modules of [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) reach them without importing the module that owns the `Examination` document: `run`/`run_with_env`/`run_raw` (run a command under a timeout; `rc` is `127` when it cannot be spawned and `124` on timeout), `run_utf16le`/`decode_utf16le` (for `wsl.exe`'s UTF-16LE output), `read_text`/`read_host_text`, `which`, the `SHORT`/`MEDIUM` timeouts and `truncate_to_chars`. All are `pub(crate)` except `run_raw`, which stays private to the module. The module itself is private to the crate and is not re-exported. - [`process.rs`](../crates/rocm-core/src/process.rs) — (ROCMAI-154, Phase 7b) process-spawn/terminate primitives, including `FileLock`, plus `run_with_timeout`: it drains both pipes on their own threads from the moment the child starts, so output size cannot stall a command into its own timeout, and it bounds how much of a timed-out child's output the error quotes, because that text reaches persisted automation logs. It is not yet the *only* such helper — [`therock/process.rs`](../apps/rocm/src/therock/process.rs)'s `wait_with_output_bounded`, [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `run_raw`, and [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs)'s `capture_optional_command_candidate_with_timeout` (plus the Windows-only `capture_diagnostic_command` in [`host_gpu/diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs)) still join their reader threads with no time limit, so a grandchild holding the pipe can outlast their timeout; converging them onto `run_with_timeout` is follow-up work to ROCMAI-448 tracked in [#623](https://github.com/ROCm/rocm-cli/issues/623). -- [`quoting.rs`](../crates/rocm-core/src/quoting.rs) — (ROCMAI-727) argument-quoting helpers with real execution stakes (POSIX shell, PowerShell), consolidated out of `apps/rocm`-side near-duplicates — see the module's own doc comment for what it owns and why the display/log/prompt-text quoting helpers elsewhere in `apps/rocm` were deliberately left unmerged. +- [`quoting.rs`](../crates/rocm-core/src/quoting.rs) — (ROCMAI-727) argument-quoting helpers with real execution stakes (POSIX shell, PowerShell), consolidated out of `apps/rocm`-side near-duplicates — see the module's own doc comment for what it owns. `posix_shell_quote` also renders the command lines the CLI shows (through `apps/rocm`'s `shell_quote`); only `comfyui.rs`'s log-line quoter stays separate. - [`report_rollup.rs`](../crates/rocm-core/src/report_rollup.rs) — (ROCMAI-492) counts read Doctor reports at every level of `Report::group_key`, with refused and unread reports kept apart. Pure, with no transport: the mailbox adapter that feeds it is maintainer tooling in `xtask`, behind `cargo xtask report-rollup`. - [`report_trend.rs`](../crates/rocm-core/src/report_trend.rs) — (ROCMAI-745) the same reports counted per week, and the weeks in which a known problem rose sharply. Pure like the rollup: it is handed a `Week`, which is all a date reduces to, and holds no time finer than that. - [`rocm_install.rs`](../crates/rocm-core/src/rocm_install.rs) — (ROCMAI-85, Phase 7a) unmanaged ("legacy") ROCm install discovery — see the module's own doc comment for what it owns. From c20a86743c53d8f12b669d2259967469224c4654 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 3 Nov 2026 11:12:29 +0200 Subject: [PATCH 21/23] fix(services): quote the id in the `rocm services logs` lines the list prints `rocm services` prints `rocm services logs ` twice: on each row's `logs:` line, and as the default view's "Read the newest" pointer to the newest past attempt. Both interpolated the id bare, so an id with a space or a quote named a different argv than the one a user would paste. The same command in `rocm services remove`'s output was already quoted on this branch; these two were missed. Quote both with `shell_quote`. An ordinary id is inert and prints unchanged. The new test splits each line back with a POSIX word-splitter and expects exactly `rocm services logs `; printing either id bare turns it red. Signed-off-by: Roman Inflianskas --- apps/rocm/src/services_text.rs | 66 ++++++++++++++++++++++++++++++++-- apps/rocm/src/shell_quote.rs | 3 +- docs/architecture.md | 2 +- 3 files changed, 67 insertions(+), 4 deletions(-) diff --git a/apps/rocm/src/services_text.rs b/apps/rocm/src/services_text.rs index 24a2783e03..9d81873823 100644 --- a/apps/rocm/src/services_text.rs +++ b/apps/rocm/src/services_text.rs @@ -123,6 +123,7 @@ use crate::service_launch::{ attach_background_stdio, detach_background_command, managed_engine_startup_failure_detail, managed_service_process_command, }; +use crate::shell_quote::shell_quote; use crate::{SandboxToolArg, cli_lifecycle_log_path, status_for_readiness}; pub(crate) fn render_logs_text(paths: &AppPaths) -> String { @@ -377,7 +378,13 @@ fn write_past_attempts_hint(output: &mut String, past_attempts: usize, newest_id ); let _ = writeln!(output, " See them: rocm services list --all"); if let Some(id) = newest_id { - let _ = writeln!(output, " Read the newest: rocm services logs {id}"); + // Quoted like every other `rocm services … ` hint, so the line is + // the argv it names even for an id that is not one inert word. + let _ = writeln!( + output, + " Read the newest: rocm services logs {}", + shell_quote(id) + ); } let _ = writeln!(output, " Reclaim the space: rocm services prune"); } @@ -438,7 +445,11 @@ pub(crate) fn render_services_text(paths: &AppPaths, all: bool) -> Result` lines the list prints — the per-row + /// `logs:` line and the default view's "Read the newest" pointer — are + /// commands a user is told to paste, so each must split back to exactly + /// that argv whatever the id holds. Mutation: interpolating the id bare in + /// either line fails this. + #[test] + fn render_services_text_logs_hints_denote_the_argv_they_name() -> Result<()> { + let service_id = "svc 'a b'"; + let (root, paths) = test_paths("services-logs-hint-awkward-id"); + paths.ensure()?; + // Not live, so no endpoint probe or pid check runs. + let mut record = ManagedServiceRecord::new( + &paths, + service_id, + "vllm", + "qwen", + "Qwen/Qwen3.5", + "127.0.0.1", + 11500, + "managed", + 999_999_999, + None, + None, + None, + ); + record.status = "failed".to_owned(); + record.write()?; + + let default_view = render_services_text(&paths, false); + let all_view = render_services_text(&paths, true); + let _ = fs::remove_dir_all(root); + let (default_view, all_view) = (default_view?, all_view?); + + let expected = Some( + ["rocm", "services", "logs", service_id] + .map(str::to_owned) + .to_vec(), + ); + let newest = default_view + .lines() + .find_map(|line| line.strip_prefix(" Read the newest: ")) + .expect("the default view points at the newest past attempt"); + assert_eq!(shlex::split(newest), expected, "{default_view}"); + let row = all_view + .lines() + .find_map(|line| line.strip_prefix(" logs: ")) + .expect("the --all view lists the record with its logs command"); + assert_eq!(shlex::split(row), expected, "{all_view}"); + Ok(()) + } + /// The host this change is NOT meant to touch: nothing has ever been served, /// so there is no record to point at and the output must read exactly as it /// did before. Every other test here plants at least one record, so without diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index 9908d667e6..a17642c141 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -16,7 +16,8 @@ //! * [`crate::therock::quote_display_arg`] builds the `command: uv … && uv …` //! line the install dry-run prints. Its install root comes from a `--prefix` //! the local assistant can choose, and the line is offered to be run. -//! * [`crate::service_hints`] and the runtime-activation report in +//! * [`crate::service_hints`], the `rocm services` list in +//! [`crate::services_text`] and the runtime-activation report in //! [`crate::runtime_services`] build the `rocm services … --yes`, //! `rocm services logs ` and `rocm runtimes activate …` lines a //! user is told to run next. A service id is not limited to inert diff --git a/docs/architecture.md b/docs/architecture.md index bfd5592d61..378721fd45 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -78,7 +78,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm services`' command handler (`services()`, which dispatches `list`, `logs`, `stop`, `restart`, `remove` and `prune`) and `run_approved_service_action`, the approval-gated stop/restart path. `ServicesCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). Both functions are `pub(crate)`: `dispatch()` calls `services()` through a re-import, and [`advised_commands.rs`](../apps/rocm/src/advised_commands.rs)'s test reaches `run_approved_service_action` through a test-only re-import in `main.rs`. The module reads from [`services_text.rs`](../apps/rocm/src/services_text.rs), [`service_records.rs`](../apps/rocm/src/service_records.rs), [`service_hints.rs`](../apps/rocm/src/service_hints.rs) and [`cli_audit.rs`](../apps/rocm/src/cli_audit.rs); none of them calls back into it. The cluster's one regression test lives in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::`. - [`services_text.rs`](../apps/rocm/src/services_text.rs) — mechanical relocation, owns private types (Phase 6f, ROCMAI-209): the CLI/TUI logs browser (`render_logs_text`, `render_logs_browser_text`, `render_logs_browser_page_text`, `render_logs_browser_page_text_with_options`, `logs_browser_total_pages`, the `LogBrowserEntry` type, `collect_log_browser_entries`, `filter_log_browser_entries`, `log_browser_source_label`, `write_past_attempts_hint`), the `rocm services`/`rocm services logs` status surfaces (`render_services_text`, `render_services_json`, `render_service_logs_text`, `render_service_logs_text_with_options`, `render_service_action_result`, `read_managed_service_manifest`, `load_managed_service`), the internal `rocmd`-compatible status/sandbox surface (`render_internal_status_text`, `run_internal_sandbox_tool`), and the managed-service stop/restart implementation behind both the sandbox tool and `rocm services stop|restart` (`terminate_recorded_service_pids`, the `MANAGED_STOP_GRACE` constant, `stop_internal_managed_service`, `stop_internal_managed_service_with`, `stop_internal_managed_service_confirmed_with`, `unload_lemonade_service_model`, `apply_restart_runtime_pin`, `load_service_for_restart`, `restart_child_argv`, `restart_internal_managed_service`, `restart_internal_managed_service_with`, `update_restarting_record`, `record_restarted_child`, `record_restart_readiness`), plus `validate_service_id`, `list_log_files`, `read_optional_tail_lines`, and the CLI-lifecycle-log tail formatting helpers (`format_cli_lifecycle_tail_line`, `lifecycle_event_label`, `humanize_log_label`, `lifecycle_field`, `read_tail_lines`). Two items physically interleaved in this span in `main.rs` moved with it rather than staying behind, since neither has a caller outside the cluster: the `LogBrowserEntry` struct and the `MANAGED_STOP_GRACE` constant; both stay private. `dispatch()` calls directly into this module at several points — `render_internal_status_text`, `run_internal_sandbox_tool`, `render_service_logs_text`, `render_logs_browser_text`, and `render_logs_text` — all re-imported via `use crate::services_text::{...};`; [`services_cmd.rs`](../apps/rocm/src/services_cmd.rs)'s `services()` calls `render_services_text`, `render_services_json` and `render_service_logs_text` through its own imports. `render_service_action_result`, `run_internal_sandbox_tool`, and `validate_service_id` are also `pub(crate)` and read from `services_cmd.rs`'s `run_approved_service_action`; `validate_service_id` is also read from [`service_records.rs`](../apps/rocm/src/service_records.rs)'s `remove_managed_service_record`/`service_record_artifacts`, and `load_managed_service` from its `remove_managed_service_record`/`apply_service_prune_plan`. `load_managed_service` and `restart_internal_managed_service` are `pub(crate)`, read from [`runtime_services.rs`](../apps/rocm/src/runtime_services.rs) (reconciling live servers against a runtime activation) and from [`managed_service_status.rs`](../apps/rocm/src/managed_service_status.rs)'s own test module; `read_tail_lines`, `render_logs_text`, `render_logs_browser_text`, `render_services_text`, `render_service_logs_text`, and `validate_service_id` are also `pub(crate)`, read from [`chat.rs`](../apps/rocm/src/chat.rs)'s deterministic tool-output summaries; `read_optional_tail_lines` and `render_service_action_result` are also `pub(crate)`, read from [`service_launch.rs`](../apps/rocm/src/service_launch.rs)'s managed-spawn/attach path. Every other item in this list has no caller outside this module and stays private, including `restart_internal_managed_service_with`, `restart_child_argv`, `load_service_for_restart`, `apply_restart_runtime_pin`, and `unload_lemonade_service_model` — see [`engine_runtime_select.rs`](../apps/rocm/src/engine_runtime_select.rs)'s and [`gpu_policy.rs`](../apps/rocm/src/gpu_policy.rs)'s entries above for how those two modules' own doc comments now describe this module, rather than `main.rs`, as that caller. The cluster's regression tests live in this module's own `mod tests`, reaching shared fixtures (`test_paths`, `plant_service_record_on_runtime`, `OLD_RUNTIME_KEY`, `NEW_RUNTIME_KEY`) through `crate::tests::` the same way other mechanically relocated modules do, and `runtime_services::` through its own `use crate::runtime_services;` for the handful of tests that drive this cluster's restart/stop behavior through `runtime_services`'s public entry points rather than calling it directly. Two tests that call this cluster's `load_managed_service` only incidentally — their primary subject is `runtime_services::pin_service_record_to_runtime`/`restore_service_record_pin` and `runtime_services::restart_service_onto_runtime_with`'s outcome classification respectively — stay in `main.rs`'s shared `mod tests` instead. - [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types: `rocm setup`'s command handler (`setup()`, which runs `setup status` by default and `setup reset`), the text `rocm setup status` prints (`render_setup_status_text`) and the reset that clears the saved first-time prompt state (`reset_setup_prompt_state`). `SetupCommand` stays in [`main.rs`](../apps/rocm/src/main.rs). `setup()` and `render_setup_status_text` are `pub(crate)` and re-imported in `main.rs`: `dispatch()` calls the first, and [`chat.rs`](../apps/rocm/src/chat.rs)'s read-only handling of `rocm setup` and `rocm setup status` reaches the second as `crate::render_setup_status_text`; `reset_setup_prompt_state` is private. The three regression tests live in this module's own `mod tests`, reaching the shared `test_paths` fixture through `crate::tests::` and `write_test_pip_runtime` through `crate::test_support::`. -- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for `rocm-core`'s POSIX quoter, [`posix_shell_quote`](../crates/rocm-core/src/quoting.rs). `rocm-dash-tui` keeps a copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since the crate-edge check forbids it `rocm-core`; a per-character walk and a property test here hold the two to the same output. It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. +- [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for `rocm-core`'s POSIX quoter, [`posix_shell_quote`](../crates/rocm-core/src/quoting.rs). `rocm-dash-tui` keeps a copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since the crate-edge check forbids it `rocm-core`; a per-character walk and a property test here hold the two to the same output. It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report, the `rocm services logs ` lines `rocm services` lists and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and `real_os_release`, the real host's os-release that every one of these plans is built from. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions and `real_os_release` are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs), and [`driver_install.rs`](../apps/rocm/src/driver_install.rs) imports `real_os_release` from here directly. `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `real_os_release` ignores a simulated host root. - [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token`, `slugify` and `has_nontrivial_directory_contents`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) stays in [`main.rs`](../apps/rocm/src/main.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). From b9614ca1941b41ff1cb7b674f8d463f2df0d4925 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 3 Nov 2026 11:16:19 +0200 Subject: [PATCH 22/23] refactor(therock): call shell_quote directly for the dry-run command line `therock::quote_display_arg` had become a one-line wrapper around `shell_quote` with two call sites, both in the dry-run's `command:` line. Drop it and call `shell_quote` there, keeping the reason the line must be quoted as a comment at the call site. No output changes; scenario therock-next-15 still covers the rendered line end to end. Signed-off-by: Roman Inflianskas --- apps/rocm/src/shell_quote.rs | 2 +- apps/rocm/src/therock.rs | 52 ++++++++++++++++-------------------- 2 files changed, 24 insertions(+), 30 deletions(-) diff --git a/apps/rocm/src/shell_quote.rs b/apps/rocm/src/shell_quote.rs index a17642c141..caf97f910a 100644 --- a/apps/rocm/src/shell_quote.rs +++ b/apps/rocm/src/shell_quote.rs @@ -13,7 +13,7 @@ //! in the `run:` lines the CLI offers to be copied. An unquoted value there //! means the line the operator reads is not the argv that runs, and the //! copyable ones mean it is not what runs when they paste it either. -//! * [`crate::therock::quote_display_arg`] builds the `command: uv … && uv …` +//! * [`crate::therock`]'s install dry-run builds the `command: uv … && uv …` //! line the install dry-run prints. Its install root comes from a `--prefix` //! the local assistant can choose, and the line is offered to be run. //! * [`crate::service_hints`], the `rocm services` list in diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 976d88c0a9..8efc17ebbe 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -74,6 +74,7 @@ pub(crate) use crate::runtime_registry::{ use crate::runtime_registry::{ runtime_manifest_path, save_runtime_manifest, wheel_composition_includes_devel, }; +use crate::shell_quote::shell_quote; use anyhow::{Context, Result, bail}; use rocm_core::{ AppPaths, detect_host_gpu_diagnostics, detect_legacy_rocm_summary, ensure_uv_binary, @@ -538,14 +539,20 @@ fn install_wheel_runtime( } install_args.extend(wheel_composition.package_specs.iter().cloned()); let venv_args = uv_venv_args(&python_launcher.executable, &install_root); + // This line is offered as the command to run, so it has to be one a + // shell reads back as the argv it previews. The install root in it + // comes from a `--prefix` the local assistant can choose + // (`install_sdk_dry_run` is a model-callable tool), so a bare or + // double-quoted value here would be a model-chosen value in a line a + // user is invited to paste. let venv_args_display = venv_args .iter() - .map(|arg| quote_display_arg(arg)) + .map(|arg| shell_quote(arg)) .collect::>() .join(" "); let install_args_display = install_args .iter() - .map(|arg| quote_display_arg(arg)) + .map(|arg| shell_quote(arg)) .collect::>() .join(" "); let _ = writeln!(output, " mode: dry-run"); @@ -759,22 +766,6 @@ fn install_wheel_runtime( Ok(SdkInstallResult::installed(output)) } -/// Quote one argument of the `command:` line the dry-run preview prints. -/// -/// That line is offered as the command — `uv && uv ` -/// — so it has to be one a shell reads back as the argv it previews. It used to -/// quote only on whitespace and a short metacharacter list, with `"`, which -/// left `` ` `` and `'` unquoted and kept `$(…)` live *inside* the quotes; the -/// install root comes from a `--prefix` the local assistant can choose -/// (`install_sdk_dry_run` is a model-callable tool), so that was a model-chosen -/// value in a line a user is invited to run. -/// -/// [`crate::shell_quote::shell_quote`] is the same quoter the remote command -/// line and the approval previews use. -fn quote_display_arg(value: &str) -> String { - crate::shell_quote::shell_quote(value) -} - /// The host's legacy/system ROCm version when it is strictly newer than the /// version rocm-cli is about to install, otherwise `None`. Used to explain why a /// seemingly older wheel version is selected over the host's ROCm. @@ -1446,20 +1437,23 @@ mod tests { } #[test] - fn display_command_quotes_package_extras() { - assert_eq!(quote_display_arg("package[extra]"), "'package[extra]'"); + fn the_dry_run_quoter_quotes_package_extras() { + assert_eq!(shell_quote("package[extra]"), "'package[extra]'"); assert_eq!( - quote_display_arg("C:\\Program Files\\Python\\python.exe"), + shell_quote("C:\\Program Files\\Python\\python.exe"), "'C:\\Program Files\\Python\\python.exe'" ); } - /// The `command:` line is printed as the command to run, and the install - /// root in it comes from a `--prefix` the local assistant can choose - /// (`install_sdk_dry_run` is model-callable). The old quoter returned - /// `` /tmp/`id` `` completely bare — no trigger character in it — and wrapped - /// `/tmp/$(id)` in double quotes, where substitution still fires. Both ran - /// on paste. + /// The dry-run's `command:` line is printed as the command to run, and the + /// install root in it comes from a `--prefix` the local assistant can + /// choose (`install_sdk_dry_run` is model-callable). The double-quoting + /// helper that line used to be built with returned `` /tmp/`id` `` completely bare — no + /// trigger character in it — and wrapped `/tmp/$(id)` in double quotes, + /// where substitution still fires. Both ran on paste. + /// + /// This asks the quoter the line is built with, `shell_quote`; scenario + /// therock-next-15 checks the rendered line itself end to end. /// /// Asked of a real `sh`, not of a word-splitter. That distinction is the /// whole test: `shlex` is a *splitter*, so it hands back @@ -1469,7 +1463,7 @@ mod tests { /// test passed against the defect it exists to catch. #[cfg(unix)] #[test] - fn a_dry_run_command_line_cannot_run_a_second_command_on_paste() { + fn the_dry_run_quoter_cannot_run_a_second_command_on_paste() { for hostile in [ "/tmp/`id`", "/tmp/$(id)", @@ -1478,7 +1472,7 @@ mod tests { "/tmp/$HOME", "", ] { - let quoted = quote_display_arg(hostile); + let quoted = shell_quote(hostile); let output = std::process::Command::new(crate::shell_quote::TEST_SH) .arg("-c") .arg(format!("printf %s {quoted}")) From 7c40fd0da4a9990e8690d96dca39afb9c9912e66 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 3 Nov 2026 11:52:25 +0200 Subject: [PATCH 23/23] test(e2e): describe the dash's single-quoted `--root` preview The comment above dash-36's `--root` check still said `quote_display_arg` wraps whitespace values in double quotes "with no other transformation". That has not been true since this branch moved the dash quoter to POSIX single quotes. Say what it does now; the check still accepts either quote character, as #693's contract asks only for one quoted unit. Signed-off-by: Roman Inflianskas --- tests/e2e-cucumber/tests/e2e/dash_steps.rs | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/tests/e2e-cucumber/tests/e2e/dash_steps.rs b/tests/e2e-cucumber/tests/e2e/dash_steps.rs index 759e68b102..495625bf0c 100644 --- a/tests/e2e-cucumber/tests/e2e/dash_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/dash_steps.rs @@ -2096,15 +2096,14 @@ async fn approval_preview_quotes_whitespace_root(world: &mut E2eWorld) { .join(ADOPT_WHITESPACE_ROOT) .canonicalize() .unwrap_or_else(|e| panic!("failed to canonicalize the scenario root: {e}")); - // `quote_display_arg` (`crates/rocm-dash-tui/src/ui/exec.rs`, #500) wraps - // any whitespace-containing argument value in a pair of quote characters - // with no other transformation (our path has no embedded quote to - // escape), so the rendered `--root` argument is this exact string, - // quoted. #693's contract is "rendered as one unambiguous, quoted unit" — - // not any particular quote character — so this accepts either common - // convention rather than pinning the double-quote `quote_display_arg` - // happens to use today; a future change to the escaping character alone - // should not read as a regression here. + // `quote_display_arg` (`crates/rocm-dash-tui/src/ui/exec.rs`) wraps any + // value that is not one inert word in POSIX single quotes, escaping only + // an embedded `'` (our path has none), so the rendered `--root` argument + // is this exact string, single-quoted. #500 first introduced it with + // double quotes. #693's contract is "rendered as one unambiguous, quoted + // unit" — not any particular quote character — so this accepts either + // convention; a change to the quote character alone should not read as a + // regression here. // // Deliberately *without* a `--root ` prefix, and matched against // `TuiSession::popup_body_text` rather than the raw `screen_text()` grid