Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

CLI: run takes --param-check (#6921) (#6924)

Rick Morgans2356a63aea70
diff --git a/apps/solidcraft-cli/examples/studio_evidence.rs b/apps/solidcraft-cli/examples/studio_evidence.rs
index a08e6dd17c..fd41400f26 100644
--- a/apps/solidcraft-cli/examples/studio_evidence.rs
+++ b/apps/solidcraft-cli/examples/studio_evidence.rs
@@ -66,7 +66,7 @@ fn run() -> Result<(), String> {
let mut session = Session::default();
eprintln!("Generating original CAD scene from {recipe_path}");
let generation_start = Instant::now();
- let (commands, command_timings) = session.run_script_timed(&recipe, false).map_err(|e| e.to_string())?;
+ let (commands, command_timings) = session.run_script_timed(&recipe, false, &mut |_, _| {}).map_err(|e| e.to_string())?;
let generation_seconds = generation_start.elapsed().as_secs_f64();
let design_path = output.with_extension(solidcraft_engine::io::DESIGN_EXT);
session.execute("file.save_as", &json!({"path":design_path})).map_err(|e| e.to_string())?;
diff --git a/apps/solidcraft-cli/src/main.rs b/apps/solidcraft-cli/src/main.rs
index ba6fa03d1d..77d93ed902 100644
--- a/apps/solidcraft-cli/src/main.rs
+++ b/apps/solidcraft-cli/src/main.rs
@@ -2,6 +2,7 @@
//!
//! ```text
//! solidcraft-cli run <script.json|design.sc|part.step|mesh.3mf> [--in design|part.step|mesh.3mf] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]
+//! [--param-check off|warn|strict]
//! solidcraft-cli eval <script.json|design.sc|part.step> [--in design.sc|part.step] [--json-out FILE] (alias: inspect) measurements as JSON
//! solidcraft-cli script <design.sc> [--out script.json] the design's history as a command script
//! solidcraft-cli bench-open <design.sc | part.step> [--parse-only] [--save OUT.sc] [--display LEVEL [--edit NAME EXPR]] [--ops script.json] loading timings as JSON lines
@@ -57,7 +58,7 @@ struct Command {
}
/// `run`'s lines in the usage.
-const USAGE_RUN: &str = " solidcraft-cli run <script.json|design.sc|part.step> [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]\n solidcraft-cli run --in <design.sc|part.step> [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n";
+const USAGE_RUN: &str = " solidcraft-cli run <script.json|design.sc|part.step> [--in design.sc|part.step] [--out FILE]... [--save FILE] [--quiet] [--results] [--timings] [--profile] [--json-out FILE] [--allow-errors]\n [--param-check off|warn|strict]\n solidcraft-cli run --in <design.sc|part.step> [--out FILE]...\n (a timeline feature that fails fails the run and nothing is written; --allow-errors writes anyway)\n (--param-check checks each step against its command's contract: warn reports on stderr, strict stops the run)\n (--timings prints {timings: [{index, command, ms}], total_ms} for a script, with --results its results too;\n --profile adds each command's profile: {boolean_ms, tessellate_ms, other_ms}, the kernel's share)\n";
/// `eval`'s lines in the usage.
const USAGE_EVAL: &str = " solidcraft-cli eval <script.json|design.sc|part.step> [--in design.sc|part.step] [--json-out FILE] (alias: inspect)\n solidcraft-cli eval --in <script.json|design.sc|part.step> [--json-out FILE]\n (with both inputs, runs the positional script on --in before measuring; does not automatically save the modified design)\n (--json-out FILE writes the JSON that run (with --results, else the measurement) and eval print to FILE instead of stdout,\n as plain UTF-8: a shell's > can re-encode it, e.g. Windows PowerShell adds a byte-order mark)\n";
/// `script`'s lines in the usage.
@@ -299,18 +300,36 @@ fn load_checked(path: &str, check: solidcraft_engine::schema::ParamCheck) -> Res
s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?;
} else {
let script = if v.get("features").is_some() && v.get("commands").is_none() { recipe::to_script(&v)? } else { v };
- // Warn level: each step's `param_warnings` as it completes, even when a later step fails
- // (stderr, so stdout stays the caller's).
- let mut warn = |step: usize, r: &Value| {
- for w in r.get("param_warnings").and_then(Value::as_array).into_iter().flatten() {
- eprintln!("{path}: step {}: {}", step + 1, w.as_str().unwrap_or_default());
- }
- };
- s.run_script_each(&script, &mut warn).map_err(|e| e.to_string())?;
+ run_script_warning(&mut s, path, &script)?;
}
Ok(s)
}
+/// Run `script`, read from `path`, on `s`. At the warn level each step's `param_warnings` go to
+/// stderr as the step completes, even when a later step fails (stdout stays the caller's).
+fn run_script_warning(s: &mut Session, path: &str, script: &Value) -> Result<Vec<Value>, String> {
+ s.run_script_each(script, &mut |step, r| print_param_warnings(path, step, r)).map_err(|e| e.to_string())
+}
+
+/// Step `step`'s `param_warnings` on stderr, one per line, named after the script at `path`.
+fn print_param_warnings(path: &str, step: usize, r: &Value) {
+ for w in r.get("param_warnings").and_then(Value::as_array).into_iter().flatten() {
+ eprintln!("{path}: step {}: {}", step + 1, w.as_str().unwrap_or_default());
+ }
+}
+
+/// `--param-check off|warn|strict`: how calls that break a command's parameter contract are
+/// treated (docs/mcp.md); off when the option isn't given.
+fn parse_param_check(cmd: &str, args: &[String]) -> Result<solidcraft_engine::schema::ParamCheck, String> {
+ match flag(args, "--param-check") {
+ None if args.iter().any(|a| a == "--param-check") => Err(format!("{cmd}: --param-check wants off, warn or strict")),
+ None => Ok(solidcraft_engine::schema::ParamCheck::Off),
+ Some(v) => {
+ solidcraft_engine::schema::ParamCheck::parse(v).ok_or_else(|| format!("{cmd}: --param-check wants off, warn or strict, not `{v}`"))
+ }
+ }
+}
+
fn flag<'a>(args: &'a [String], name: &str) -> Option<&'a str> {
args.iter().position(|a| a == name).and_then(|i| args.get(i + 1)).map(String::as_str)
}
@@ -367,7 +386,15 @@ fn print_json(v: &Value, file: Option<&str>) -> Result<(), String> {
fn cmd_run(args: &[String]) -> Result<(), String> {
install_renderer();
let json_out = json_out(args)?;
- known_args("run", args, &["--in", "--out", "--save", "--json-out"], &["--quiet", "--results", "--timings", "--profile", "--allow-errors"], true)?;
+ // Before the option check, so a bare `--param-check` gets the words `mcp` uses.
+ let check = parse_param_check("run", args)?;
+ known_args(
+ "run",
+ args,
+ &["--in", "--out", "--save", "--json-out", "--param-check"],
+ &["--quiet", "--results", "--timings", "--profile", "--allow-errors"],
+ true,
+ )?;
let base = flag(args, "--in");
let path = positional(args);
if path.is_none() && base.is_none() {
@@ -380,23 +407,25 @@ fn cmd_run(args: &[String]) -> Result<(), String> {
let (mut s, results) = if want_results || timings {
// Collect every command's result or time (scripts only), then process requested files too.
let mut s = match base {
- Some(b) => load(b)?,
+ Some(b) => load_checked(b, check)?,
None => Session::default(),
};
+ s.param_check = check;
let needs = if want_results { "--results needs a script" } else { "--timings needs a script" };
- let v = read_json(path.ok_or(needs)?)?;
+ let script = path.ok_or(needs)?;
+ let v = read_json(script)?;
let out = if timings {
- let (r, mut t) = s.run_script_timed(&v, profile).map_err(|e| e.to_string())?;
+ let (r, mut t) = s.run_script_timed(&v, profile, &mut |step, r| print_param_warnings(script, step, r)).map_err(|e| e.to_string())?;
if want_results && let Some(o) = t.as_object_mut() {
o.insert("results".into(), Value::Array(r));
}
t
} else {
- Value::Array(s.run_script(&v).map_err(|e| e.to_string())?)
+ Value::Array(run_script_warning(&mut s, script, &v)?)
};
(s, Some(out))
} else {
- (open(base, path)?, None)
+ (open(base, path, check)?, None)
};
// A feature that fails leaves the bodies as they were before it (a parameter change can
// break a feature without failing the command that made it): writing them would hand out
@@ -421,16 +450,16 @@ fn cmd_run(args: &[String]) -> Result<(), String> {
}
/// The session `run`, `eval` and `snapshot` start from: `--in` (a design or STEP file) with the
-/// positional script run on top of it, or either one alone.
-fn open(base: Option<&str>, path: Option<&String>) -> Result<Session, String> {
+/// positional script run on top of it, or either one alone, with scripts run at `check`.
+fn open(base: Option<&str>, path: Option<&String>, check: solidcraft_engine::schema::ParamCheck) -> Result<Session, String> {
match (base, path) {
(Some(b), Some(p)) => {
- let mut s = load(b)?;
- s.run_script(&read_json(p)?).map_err(|e| e.to_string())?;
+ let mut s = load_checked(b, check)?;
+ run_script_warning(&mut s, p, &read_json(p)?)?;
Ok(s)
}
- (Some(b), None) => load(b),
- (None, Some(p)) => load(p),
+ (Some(b), None) => load_checked(b, check),
+ (None, Some(p)) => load_checked(p, check),
(None, None) => Err(usage()),
}
}
@@ -473,7 +502,7 @@ fn timeline_ok(s: &Session) -> Result<(), String> {
fn cmd_eval(args: &[String]) -> Result<(), String> {
let json_out = json_out(args)?;
known_args("eval", args, &["--in", "--json-out"], &[], true)?;
- let mut s = open(flag(args, "--in"), positional(args))?;
+ let mut s = open(flag(args, "--in"), positional(args), solidcraft_engine::schema::ParamCheck::Off)?;
let m = s.execute("inspect.measure", &json!({})).map_err(|e| e.to_string())?;
let d = s.execute("document.inspect", &json!({})).map_err(|e| e.to_string())?;
let out = json!({
@@ -567,7 +596,7 @@ fn cmd_snapshot(args: &[String]) -> Result<(), String> {
Some(x) => x.parse().ok().filter(|n| (16..=8192).contains(n)).ok_or_else(|| format!("{name} must be 16 to 8192 pixels, not `{x}`")),
};
let (w, h) = (size("--width", 1280)?, size("--height", 800)?);
- let mut s = open(flag(args, "--in"), positional(args))?;
+ let mut s = open(flag(args, "--in"), positional(args), solidcraft_engine::schema::ParamCheck::Off)?;
// How the bodies are drawn and where the model is cut, through the commands the app's
// Appearance dialog and Section Analysis run (`preview`).
preview::apply(&mut s, &flags(args, "--body"), &flags(args, "--tool"), flag(args, "--section"))?;
@@ -691,14 +720,8 @@ fn cmd_mcp(args: &[String]) -> Result<(), String> {
eprintln!("solidcraft mcp: the design's folder is left out because {why}; add it with --allow-path if you mean it");
}
}
- // How a headless session treats calls that break a command's parameter contract (docs/mcp.md).
- let param_check = match flag(args, "--param-check") {
- None if args.iter().any(|a| a == "--param-check") => return Err("mcp: --param-check wants off, warn or strict".into()),
- None => solidcraft_engine::schema::ParamCheck::Off,
- Some(v) => {
- solidcraft_engine::schema::ParamCheck::parse(v).ok_or_else(|| format!("mcp: --param-check wants off, warn or strict, not `{v}`"))?
- }
- };
+ // How a headless session treats calls that break a command's parameter contract.
+ let param_check = parse_param_check("mcp", args)?;
if param_check != solidcraft_engine::schema::ParamCheck::Off && flag(args, "--connect").is_some() {
eprintln!("solidcraft mcp: --param-check applies to headless sessions; calls to the app are not checked yet");
}
diff --git a/apps/solidcraft-cli/tests/run_results.rs b/apps/solidcraft-cli/tests/run_results.rs
index 4534a1ebba..51fe28534c 100644
--- a/apps/solidcraft-cli/tests/run_results.rs
+++ b/apps/solidcraft-cli/tests/run_results.rs
@@ -496,6 +496,78 @@ fn timings_and_profile_report_each_command() {
assert!(String::from_utf8_lossy(&output.stderr).contains("--timings needs a script"));
}
+/// #6921: `--param-check` checks a script's steps against their contracts on every path `run`
+/// takes (a script alone, on an `--in` design or script, with `--results`, `--timings` or
+/// `--profile`), and a warning reaches stderr even when a later step fails.
+#[test]
+fn param_check_reaches_every_script_run_takes() {
+ let dir = Scratch::new();
+ let typo = dir.0.join("typo.json");
+ let step = json!({"command": "solid.box", "params": {"length": 2, "width": 3, "height": 4, "operaton": "new"}});
+ std::fs::write(&typo, json!({"commands": [step.clone()]}).to_string()).unwrap();
+ let base = dir.0.join("base.solidcraft");
+ json_output(cli().arg("run").arg(dir.script()).arg("--save").arg(&base).output().unwrap());
+ let saved = dir.0.join("saved.solidcraft");
+ let start = dir.script();
+ let (typo, base, saved_arg, start) = (typo.to_str().unwrap(), base.to_str().unwrap(), saved.to_str().unwrap(), start.to_str().unwrap());
+ let paths = [&[][..], &["--in", base], &["--in", start], &["--results"], &["--timings"], &["--timings", "--profile"]];
+ let run = |level: Option<&str>, extra: &[&str]| {
+ std::fs::remove_file(&saved).ok();
+ let check = level.map(|l| ["--param-check", l]).into_iter().flatten();
+ cli().args(["run", typo, "--save", saved_arg]).args(check).args(extra).output().unwrap()
+ };
+
+ // Off, the default: the step runs as it always has, without a word.
+ let off = run(None, &[]);
+ assert!(off.status.success() && !String::from_utf8_lossy(&off.stderr).contains("operaton"), "{off:?}");
+ assert_eq!(body_count(&saved), 1);
+
+ // Warn: each path runs the step, saves, and reports it on stderr; `--results` keeps it too.
+ for extra in paths {
+ let output = run(Some("warn"), extra);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(output.status.success(), "{extra:?}: {stderr}");
+ assert!(stderr.contains("step 1: unknown key `operaton`; did you mean `operation`?"), "{extra:?}: {stderr}");
+ assert!(saved.exists(), "{extra:?}");
+ if extra == ["--results"] {
+ let results: Value = serde_json::from_slice(&output.stdout).unwrap();
+ assert!(results[0]["param_warnings"][0].as_str().is_some_and(|w| w.contains("operaton")), "{results}");
+ }
+ }
+
+ // Strict: on each path the run stops at the step, and nothing is written.
+ for extra in paths {
+ let output = run(Some("strict"), extra);
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert_eq!(output.status.code(), Some(1), "{extra:?}: {stderr}");
+ assert!(stderr.contains("unknown key `operaton`"), "{extra:?}: {stderr}");
+ assert!(!saved.exists(), "{extra:?}");
+ }
+
+ // Warn, with a later step that fails: the run fails, and the first step's warning is still
+ // reported, timed or not.
+ let failing = dir.0.join("failing.json");
+ let fail = json!({"command": "solid.extrude", "params": {"sketch": "Nope"}});
+ std::fs::write(&failing, json!({"commands": [step, fail]}).to_string()).unwrap();
+ for extra in [&[][..], &["--timings"]] {
+ let output = cli().arg("run").arg(&failing).args(["--param-check", "warn"]).args(extra).output().unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert_eq!(output.status.code(), Some(1), "{extra:?}: {stderr}");
+ assert!(stderr.contains("step 1: unknown key `operaton`") && stderr.contains("no sketch `Nope`"), "{extra:?}: {stderr}");
+ }
+
+ // A level it doesn't know and a missing value fail.
+ for (bad, says) in [
+ (&["--param-check", "loud"][..], "--param-check wants off, warn or strict, not `loud`"),
+ (&["--param-check"], "run: --param-check wants off, warn or strict"),
+ ] {
+ let output = cli().args(["run", typo]).args(bad).output().unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert_eq!(output.status.code(), Some(1), "{bad:?}: {stderr}");
+ assert!(stderr.contains(says), "{bad:?}: {stderr}");
+ }
+}
+
fn render_setup_script(dir: &Scratch, job: Value) -> PathBuf {
let path = dir.0.join("render.json");
std::fs::write(
diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs
index 470e4faf7b..319fa753d4 100644
--- a/crates/engine/src/lib.rs
+++ b/crates/engine/src/lib.rs
@@ -1810,9 +1810,10 @@ impl Session {
/// [`Session::run_script`], timing each command (#1833): the results and
/// `{"timings": [{"index", "command", "ms", "profile"?}], "total_ms"}`, with `profile` the
- /// kernel's share of each command ([`timing`]).
- pub fn run_script_timed(&mut self, script: &Value, profile: bool) -> Result<(Vec<Value>, Value)> {
- let (results, timings) = self.run_script_with(script, Some(profile), &mut |_, _| {})?;
+ /// kernel's share of each command ([`timing`]). `each` is called as in
+ /// [`Session::run_script_each`].
+ pub fn run_script_timed(&mut self, script: &Value, profile: bool, each: &mut dyn FnMut(usize, &Value)) -> Result<(Vec<Value>, Value)> {
+ let (results, timings) = self.run_script_with(script, Some(profile), each)?;
Ok((results, timings.unwrap_or(Value::Null)))
}
diff --git a/crates/engine/src/timing.rs b/crates/engine/src/timing.rs
index a3dede46f1..42e9e87f5a 100644
--- a/crates/engine/src/timing.rs
+++ b/crates/engine/src/timing.rs
@@ -87,7 +87,7 @@ mod tests {
{"command": "solid.box", "params": {"length": 4, "width": 4, "height": 30, "operation": "join"}},
]});
let mut s = crate::Session::default();
- let (results, t) = s.run_script_timed(&script, true).unwrap();
+ let (results, t) = s.run_script_timed(&script, true, &mut |_, _| {}).unwrap();
assert_eq!(results.len(), 2);
let rows = t["timings"].as_array().unwrap();
assert_eq!(rows.len(), 2);
@@ -100,12 +100,12 @@ mod tests {
let total = t["total_ms"].as_f64().unwrap();
assert!(total + 0.01 >= rows.iter().map(|r| r["ms"].as_f64().unwrap()).sum::<f64>(), "{t}");
// Without profile: the same rows, no kernel split; the plain run is unchanged.
- let (_, t) = crate::Session::default().run_script_timed(&script, false).unwrap();
+ let (_, t) = crate::Session::default().run_script_timed(&script, false, &mut |_, _| {}).unwrap();
assert!(t["timings"][0].get("profile").is_none());
assert_eq!(crate::Session::default().run_script(&script).unwrap().len(), 2);
// A failing step still fails the run, with its step number.
let bad = json!([{"command": "solid.box", "params": {"length": -1}}]);
- let e = crate::Session::default().run_script_timed(&bad, true).unwrap_err().to_string();
+ let e = crate::Session::default().run_script_timed(&bad, true, &mut |_, _| {}).unwrap_err().to_string();
assert!(e.contains("step 1"), "{e}");
}
}
diff --git a/docs/book/src/guide/getting-started.md b/docs/book/src/guide/getting-started.md
index 86ff49ca49..bee052ea81 100644
--- a/docs/book/src/guide/getting-started.md
+++ b/docs/book/src/guide/getting-started.md
@@ -312,6 +312,13 @@ rebuilds it; `run` then exits with status 1, lists the failing features and writ
its `--out` and `--save` files, because the bodies lack what those features should have made.
`--allow-errors` writes them anyway.
+`--param-check warn|strict` checks each step against its command's parameter contract, for the
+commands that have one (`describe_command` in the MCP server shows them); the default, `off`,
+checks nothing. A misspelt optional key, such as `operaton` for `solid.box`'s `operation`, is
+otherwise ignored, and the step builds without it. `warn` runs the step and prints
+``script.json: step 1: unknown key `operaton`; did you mean `operation`?`` on stderr; `strict`
+stops the run at that step, and nothing is written.
+
`run` prints each command's result with `--results` (otherwise the measurement), and `eval`
prints the measurement, as JSON on stdout. `--json-out FILE` writes that JSON to a file
instead. The file is plain UTF-8, which is not what a redirect gives you everywhere: Windows