SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Typed parameter contracts and JSON Schemas for solid.box and solid.extrude (#2829) (#2611)
Matthew Knutson953fd7d5f8fe
diff --git a/Cargo.lock b/Cargo.lockindex 38e2042046..1df6cfe09e 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -1175,6 +1175,12 @@ version = "0.1.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76"+[[package]]+name = "dyn-clone"+version = "1.0.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"+[[package]]name = "ecolor"version = "0.36.2"@@ -3514,6 +3520,26 @@ dependencies = ["bitflags 2.13.2",]+[[package]]+name = "ref-cast"+version = "1.0.27"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"+dependencies = [+ "ref-cast-impl",+]++[[package]]+name = "ref-cast-impl"+version = "1.0.27"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]+[[package]]name = "regex-syntax"version = "0.8.11"@@ -3741,6 +3767,31 @@ dependencies = ["windows-sys 0.61.2",]+[[package]]+name = "schemars"+version = "1.2.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ab508826f74a77ca9d5aba6ff19b522583ee3eaf28a19384ff3d0e5835fadf6e"+dependencies = [+ "dyn-clone",+ "ref-cast",+ "schemars_derive",+ "serde",+ "serde_json",+]++[[package]]+name = "schemars_derive"+version = "1.2.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e1c3a92094fa7d61aa124645844facb6b554dfc797136d0f5fd1f890e2bffc69"+dependencies = [+ "proc-macro2",+ "quote",+ "serde_derive_internals",+ "syn 3.0.6",+]+[[package]]name = "scoped-tls"version = "1.0.1"@@ -3860,6 +3911,17 @@ dependencies = ["syn 3.0.6",]+[[package]]+name = "serde_derive_internals"+version = "0.30.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]+[[package]]name = "serde_json"version = "1.0.151"@@ -3873,6 +3935,17 @@ dependencies = ["zmij",]+[[package]]+name = "serde_path_to_error"+version = "0.1.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"+dependencies = [+ "itoa",+ "serde",+ "serde_core",+]+[[package]]name = "serde_repr"version = "0.1.21"@@ -4164,8 +4237,10 @@ name = "solidcraft-engine"version = "0.16.2"dependencies = ["log",+ "schemars","serde","serde_json",+ "serde_path_to_error","solidcraft-doc","solidcraft-geom","solidcraft-io",diff --git a/Cargo.toml b/Cargo.tomlindex fa02d78296..a4cecf4f30 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -36,6 +36,9 @@ proc-macro2 = "1"quote = "1"syn = { version = "2", features = ["full"] }serde_json = { version = "1", features = ["float_roundtrip"] }+# command parameter and result schemas+schemars = "1.2"+serde_path_to_error = "0.1"log = "0.4"sha2 = "0.10"moxcms = { version = "0.8.1", default-features = false, features = ["extended_range"] }diff --git a/apps/solidcraft-cli/src/main.rs b/apps/solidcraft-cli/src/main.rsindex 5be417c49b..dec00af12d 100644--- a/apps/solidcraft-cli/src/main.rs+++ b/apps/solidcraft-cli/src/main.rs@@ -13,6 +13,7 @@//! solidcraft-cli recipe <recipe.json> translate an oracle recipe to a script//! solidcraft-cli oracle <case-dir>... replay recipes and compare with expected.json//! solidcraft-cli mcp [--in design|script] [--connect HOST:PORT [--token T]] [--allow-path DIR]... [--allow-any-path]+//! [--param-check off|warn|strict]//! MCP server on stdio (docs/mcp.md)//! solidcraft-cli licences SolidCraft's licence and the third-party licences//! solidcraft-cli icon --out F.png|F.ico [--size N] the app icon (packaging; drawn, not a file)@@ -71,6 +72,7 @@ const USAGE: &str = "usage:solidcraft-cli oracle <case-dir>... [--json]solidcraft-cli fuzz [--from N] [--count N] [--jobs J] [--timeout S] [--steps N] [--minimise] [--out DIR] [--report FILE]solidcraft-cli mcp [--in design.solidcraft|script.json] [--connect 127.0.0.1:PORT [--token T]] [--allow-path DIR]... [--allow-any-path]+ [--param-check off|warn|strict]solidcraft-cli crashes [list [--json] | show <id> | replay <id> | dir | clear [<id>]]solidcraft-cli licencessolidcraft-cli gpu [--policy auto|hardware|software|cpu]@@ -154,7 +156,14 @@ pub fn read_json(path: &str) -> Result<Value, String> {/// A session from a design file, a STEP/3MF/STL file, a command script, or an oracle recipe.pub fn load(path: &str) -> Result<Session, String> {+ load_checked(path, solidcraft_engine::schema::ParamCheck::Off)+}++/// `load`, with scripts and recipes run at the parameter-check level `check`, which the+/// session keeps.+fn load_checked(path: &str, check: solidcraft_engine::schema::ParamCheck) -> Result<Session, String> {let mut s = Session::default();+ s.param_check = check;if solidcraft_engine::io::is_step_path(path) || solidcraft_engine::io::is_mesh_path(path) {s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?;return Ok(s);@@ -164,16 +173,22 @@ pub fn load(path: &str) -> Result<Session, String> {let doc = solidcraft_engine::io::read_design(&bytes).map_err(|e| format!("{path}: {e}"))?;let mut session = Session::new(doc);session.path = Some(path.to_owned());+ session.param_check = check;return Ok(session);}let v: Value = serde_json::from_slice(&bytes).map_err(|e| format!("{path}: {e}"))?;if v.get("format").and_then(Value::as_str).is_some_and(|f| solidcraft_engine::doc::format::version_of(f).is_some()) {s.execute("doc.open", &json!({"path": path})).map_err(|e| e.to_string())?;- } else if v.get("features").is_some() && v.get("commands").is_none() {- let script = recipe::to_script(&v)?;- s.run_script(&script).map_err(|e| e.to_string())?;} else {- s.run_script(&v).map_err(|e| e.to_string())?;+ 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())?;}Ok(s)}@@ -536,6 +551,17 @@ 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}`"))?+ }+ };+ 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");+ }let backend: Box<dyn solidcraft_mcp::Backend> = match (flag(args, "--connect"), flag(args, "--in")) {(Some(_), Some(_)) => return Err("mcp: use either --connect or --in, not both".into()),(Some(addr), None) => {@@ -552,8 +578,12 @@ fn cmd_mcp(args: &[String]) -> Result<(), String> {}Box::new(remote)}- (None, Some(path)) => Box::new(solidcraft_mcp::Headless::new(load(path)?)),- (None, None) => Box::new(solidcraft_mcp::Headless::default()),+ (None, Some(path)) => Box::new(solidcraft_mcp::Headless::new(load_checked(path, param_check)?)),+ (None, None) => {+ let mut headless = solidcraft_mcp::Headless::default();+ headless.session.param_check = param_check;+ Box::new(headless)+ }};let stdin = std::io::stdin();let stdout = std::io::stdout();diff --git a/apps/solidcraft-cli/tests/mcp_param_check.rs b/apps/solidcraft-cli/tests/mcp_param_check.rsnew file mode 100644index 0000000000..0dab929240--- /dev/null+++ b/apps/solidcraft-cli/tests/mcp_param_check.rs@@ -0,0 +1,50 @@+//! `mcp --in script --param-check <level>`: the level applies to the script the session starts+//! from too, so a misspelled key in it is refused (strict) or reported on stderr (warn) instead of+//! silently ignored.++use std::process::{Command, Stdio};++#[test]+fn param_check_applies_to_the_starting_script() {+ let dir = std::env::temp_dir().join(format!("solidcraft-mcp-param-check-{}", std::process::id()));+ std::fs::create_dir_all(&dir).unwrap();+ let script = dir.join("typo.json");+ let box_ = r#"{"command": "solid.box", "params": {"length": 5, "width": 5, "height": 5, "operaton": "cut"}}"#;+ std::fs::write(&script, format!(r#"{{"commands": [{box_}]}}"#)).unwrap();+ let run = |level: &str| {+ Command::new(env!("CARGO_BIN_EXE_solidcraft-cli"))+ .args(["mcp", "--in", script.to_str().unwrap(), "--param-check", level])+ .stdin(Stdio::null())+ .output()+ .unwrap()+ };+ let strict = run("strict");+ let stderr = String::from_utf8_lossy(&strict.stderr);+ assert!(!strict.status.success(), "{stderr}");+ assert!(stderr.contains("unknown key `operaton`; did you mean `operation`?"), "{stderr}");+ // Warn: the script runs, and its warnings go to stderr.+ let warn = run("warn");+ let stderr = String::from_utf8_lossy(&warn.stderr);+ assert!(warn.status.success(), "{stderr}");+ assert!(stderr.contains("step 1: unknown key `operaton`; did you mean `operation`?"), "{stderr}");+ // A warned step's warning is printed even when a later step fails.+ let failing = dir.join("typo_then_failure.json");+ std::fs::write(&failing, format!(r#"{{"commands": [{box_}, {{"command": "no.such_command"}}]}}"#)).unwrap();+ let out = Command::new(env!("CARGO_BIN_EXE_solidcraft-cli"))+ .args(["mcp", "--in", failing.to_str().unwrap(), "--param-check", "warn"])+ .stdin(Stdio::null())+ .output()+ .unwrap();+ let stderr = String::from_utf8_lossy(&out.stderr);+ assert!(!out.status.success(), "{stderr}");+ assert!(stderr.contains("step 1: unknown key `operaton`") && stderr.contains("step 2"), "{stderr}");+ // Off: the script runs as before, and the server ends with its input.+ let off = run("off");+ assert!(off.status.success(), "{}", String::from_utf8_lossy(&off.stderr));+ assert!(!String::from_utf8_lossy(&off.stderr).contains("operaton"));+ // A bare flag is an error, not off.+ let bare = Command::new(env!("CARGO_BIN_EXE_solidcraft-cli")).args(["mcp", "--param-check"]).stdin(Stdio::null()).output().unwrap();+ assert!(!bare.status.success());+ assert!(String::from_utf8_lossy(&bare.stderr).contains("--param-check wants off, warn or strict"));+ std::fs::remove_dir_all(&dir).ok();+}diff --git a/assets/locales/en.json b/assets/locales/en.jsonindex 1419c4bb27..77c030df3b 100644--- a/assets/locales/en.json+++ b/assets/locales/en.json@@ -422,6 +422,7 @@"cmd.edit_checkpoint": "Checkpoint","cmd.edit_restore_checkpoint": "Restore Checkpoint","cmd.engine_commands": "List Commands",+ "cmd.engine_describe": "Describe Command","cmd.explode_create": "Exploded View","cmd.explode_delete": "Delete Exploded View","cmd.explode_list": "List Exploded Views",diff --git a/assets/locales/ja.json b/assets/locales/ja.jsonindex 09499f0146..d6f0ace302 100644--- a/assets/locales/ja.json+++ b/assets/locales/ja.json@@ -422,6 +422,7 @@"cmd.edit_checkpoint": "チェックポイント","cmd.edit_restore_checkpoint": "チェックポイントを復元","cmd.engine_commands": "コマンドを一覧表示",+ "cmd.engine_describe": "コマンドの詳細を表示","cmd.explode_create": "分解図","cmd.explode_delete": "分解図を削除","cmd.explode_list": "分解図を一覧表示",diff --git a/assets/locales/zh.json b/assets/locales/zh.jsonindex cee0926ddd..f236bdb8dd 100644--- a/assets/locales/zh.json+++ b/assets/locales/zh.json@@ -422,6 +422,7 @@"cmd.edit_checkpoint": "检查点","cmd.edit_restore_checkpoint": "恢复检查点","cmd.engine_commands": "列出命令",+ "cmd.engine_describe": "描述命令","cmd.explode_create": "爆炸图","cmd.explode_delete": "删除爆炸图","cmd.explode_list": "列出爆炸图",diff --git a/crates/engine/Cargo.toml b/crates/engine/Cargo.tomlindex 58ab39c2a8..3080f1b8ca 100644--- a/crates/engine/Cargo.toml+++ b/crates/engine/Cargo.toml@@ -17,6 +17,13 @@ solidcraft-io = { workspace = true }solidcraft-render = { workspace = true }serde = { workspace = true }serde_json = { workspace = true }+schemars = { workspace = true }+serde_path_to_error = { workspace = true }thiserror = { workspace = true }log = { workspace = true }web-time = { workspace = true }++[features]+# Turns on the parameter-contract audit recorder (`SOLIDCRAFT_PARAM_AUDIT`, see+# `src/schema/record.rs`), for checking a new contract against the whole test suite.+param-audit = []diff --git a/crates/engine/src/cmd/face_tests.rs b/crates/engine/src/cmd/face_tests.rsindex 5ff74c3a38..73c02e39b7 100644--- a/crates/engine/src/cmd/face_tests.rs+++ b/crates/engine/src/cmd/face_tests.rs@@ -260,7 +260,7 @@ fn join_keeps_exact_face_attachments_from_both_operands() {run(&mut s, "sketch.create", json!({"plane":"YZ"}));run(&mut s, "sketch.circle.center", json!({"center":[0,20],"radius":5}));run(&mut s, "sketch.finish", json!({}));- run(&mut s, "solid.extrude", json!({"distance":20,"symmetric":true,"operation":"join"}));+ run(&mut s, "solid.extrude", json!({"distance":20,"operation":"join"}));run(&mut s, "sketch.create", json!({"plane":{"face":[0,0,40]}}));run(&mut s, "sketch.circle.center", json!({"center":[0,0],"radius":4}));run(&mut s, "sketch.finish", json!({}));diff --git a/crates/engine/src/cmd/features.rs b/crates/engine/src/cmd/features.rsindex ec9d9748e8..ceba6a01d9 100644--- a/crates/engine/src/cmd/features.rs+++ b/crates/engine/src/cmd/features.rs@@ -11,13 +11,19 @@ use solidcraft_geom::Vec3;use super::{CommandSpec, not_in_sketch};use crate::params::{bad, bool_, expr, req_expr, str_, string_list, vec2, vec3};+use crate::schema::{BoxParams, ExtrudeParams, FeatureResult, TypedContract, output_schema_for};use crate::{EngineError, Result, Session};+const BOX_CONTRACT: TypedContract<BoxParams> = TypedContract::new();+const EXTRUDE_CONTRACT: TypedContract<ExtrudeParams> = TypedContract::new();+pub static COMMANDS: &[CommandSpec] = &[- CommandSpec::new("solid.extrude", "Extrude", extrude)+ CommandSpec::new("solid.extrude", "Extrude", crate::checked!("solid.extrude", EXTRUDE_CONTRACT, extrude)).at("SOLID", "CREATE").icon("extrude").key("E")+ .contract(&EXTRUDE_CONTRACT)+ .output(output_schema_for::<FeatureResult>).params("distance: expr (or through_all: true); taper?: angle expr; sketch?: id|name (default: active or last sketch); profiles?: all | [index] | [{curves: [ids]}] (the profile whose outer loop is made of exactly these curves, or pieces of them; found again on every recompute, so it follows parameter changes; islands inside are its holes; an error when no profile or several match) | [{point:[x,y]}] (index and point picks are stored by their curves when that finds the same profile); face?: [x,y,z] (extrude a planar body face instead of a sketch profile); faces?: [[x,y,z],…] (coplanar faces of one body); face_body?: name (whose face, where faces of several bodies meet at the point); direction?: positive|negative|symmetric (distance is total thickness, split evenly around the start plane); convention?: total_distance|legacy_per_side (default total_distance; legacy preserves older symmetric extents); distance2?: expr (Two Sides: a second distance the other way from the first side, which may be through_all or to; with direction: negative the first side goes against the normal and distance2 along it); start_offset?: expr (along the sketch normal, also with direction: negative); to?: [x,y,z] (To Object: a face, vertex or point; to_offset?: expr past it); from?: [x,y,z] (From Object: start at that face or point); operation?: new|join|cut|intersect|auto (cut into a body, otherwise join existing solids; new in an empty component); targets?: [body] (Join from a face, or from a sketch on a body's face, defaults to that face's body; explicit targets or participants override); name?; body_name?; thin?: true (Thin: a wall along sketch curves instead of the profiles) with curves?: [curve ids] (open chains and closed loops, joined where they meet end to end; default: every drawn curve of the sketch), thickness: expr, side?: center|inside|outside|two_sides (a closed loop's inside is the area it encloses, an open chain's the side it bends toward, a straight line's the left of its first curve as drawn; default center), thickness2?: expr (two_sides: the thickness outside); corners are mitred, crossing walls are one"),CommandSpec::new("solid.revolve", "Revolve", revolve).at("SOLID", "CREATE")@@ -28,7 +34,12 @@ pub static COMMANDS: &[CommandSpec] = &[.icon("sweep").params("sketch: profile sketch; profiles?; path_sketch: sketch; path: [curve ids in order]; orientation?: perpendicular (default: square to the path, turning with it) | parallel (as drawn: the profile moves without turning; the path must keep crossing its plane) | [x,y,z] (square to the path, its turn about the path fixed by this direction); twist?: angle expr (the profile turns this much about the path over its length; within 4 turns); scale?: expr (the profile's scale at the end, linear along the path; 0.01…100); rails?: [{sketch?: sketch (default path_sketch), curves: [curve ids in order]}] (guide rails, one or two, each meeting every plane square to the path once along it, from the end nearest the path's start: one rail turns the profile so its point where the rail starts stays on the rail and scales it with the rail's distance from the path; two rails carry it between them, its points where they start staying on both; rails take the default orientation, no twist and no scale, and a path without sharp corners); rail_fit?: scale (default: the profile grows and shrinks evenly) | stretch (only across to the rail, between the rails); operation?, targets?, name?, body_name?"),CommandSpec::new("solid.loft", "Loft", loft).at("SOLID", "CREATE").icon("loft").params("sections: [{sketch, profiles?} | {sketch, point: id} (an apex)] (2…50, in order; matching hole counts, no holes at an apex); rails?: [{sketch, curves: [ids in order]}] (one or two guide rails from the first section to the last, through every section's outline: the loft follows them between the sections; not with sections that have holes); rail_fit?: scale|stretch (default scale: with one rail the sections grow evenly with the rail's distance from their middle, with two with the distance between the rails; stretch: only that way); operation?, targets?, name?, body_name?"),- CommandSpec::new("solid.box", "Box", prim_box).at("SOLID", "CREATE").icon("box").params("length, width, height: expr; corner?: [x,y,z] | center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"),+ CommandSpec::new("solid.box", "Box", crate::checked!("solid.box", BOX_CONTRACT, prim_box))+ .at("SOLID", "CREATE")+ .icon("box")+ .contract(&BOX_CONTRACT)+ .output(output_schema_for::<FeatureResult>)+ .params("length, width, height: expr; corner?: [x,y,z] | center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"),CommandSpec::new("solid.cylinder", "Cylinder", prim_cylinder).at("SOLID", "CREATE").icon("cylinder").params("radius | diameter, height: expr; base?: [x,y,z] (centre of the bottom: numbers in mm or length expressions; default: the origin); axis?: X|Y|Z|[x,y,z] (default Z); operation?, targets?: [body], name?, body_name?"),CommandSpec::new("solid.sphere", "Sphere", prim_sphere).at("SOLID", "CREATE").icon("sphere").params("radius | diameter: expr; center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"),CommandSpec::new("solid.torus", "Torus", prim_torus).at("SOLID", "CREATE").icon("torus").params("major, minor: expr (radii); center?: [x,y,z] (numbers in mm or length expressions; default: the origin); operation?, targets?: [body], name?, body_name?"),@@ -334,7 +345,7 @@ pub(super) fn stable_profiles(s: &Session, kind: &mut FeatureKind) -> Result<()>Ok(())}-pub(super) fn profiles(p: &Value, cmd: &str) -> Result<ProfileSel> {+pub(crate) fn profiles(p: &Value, cmd: &str) -> Result<ProfileSel> {let Some(v) = p.get("profiles") else { return Ok(ProfileSel::All) };match v {Value::Object(fields) => {@@ -560,8 +571,19 @@ fn add_feature_in(s: &mut Session, p: &Value, kind: FeatureKind, world: bool) ->// A warning (a Boolean that needed a retry, a reference found again elsewhere) is part of// the reply: a script or an agent sees it without asking the timeline (#616).let warning = r.as_ref().and_then(|r| r.warning.clone());- Ok(json!({"feature": id, "name": fname, "bodies": bodies, "created_bodies": created, "changed_bodies": changed,- "removed_bodies": removed, "warning": warning, "ms": r.map(|r| r.ms)}))+ let owned = |names: Vec<&str>| names.into_iter().map(str::to_string).collect();+ let reply = FeatureResult {+ feature: id,+ name: fname,+ bodies: owned(bodies),+ created_bodies: owned(created),+ changed_bodies: owned(changed),+ removed_bodies: owned(removed),+ warning,+ ms: r.map(|r| r.ms),+ param_warnings: Vec::new(),+ };+ serde_json::to_value(reply).map_err(|e| EngineError::Other(e.to_string()))}fn extrude(s: &mut Session, p: &Value) -> Result<Value> {diff --git a/crates/engine/src/cmd/inspect.rs b/crates/engine/src/cmd/inspect.rsindex fc82f8864e..db25052dce 100644--- a/crates/engine/src/cmd/inspect.rs+++ b/crates/engine/src/cmd/inspect.rs@@ -44,6 +44,13 @@ pub static COMMANDS: &[CommandSpec] = &[.doc_only().params("→ the built-in materials, then the design's own (user: true, with their look)"),CommandSpec::new("engine.commands", "List Commands", commands).icon("list").noundo(),+ CommandSpec::new("engine.describe", "Describe Command", crate::checked!("engine.describe", DESCRIBE_CONTRACT, describe))+ .icon("list")+ .noundo()+ .doc_only()+ .contract(&DESCRIBE_CONTRACT)+ .output(crate::schema::output_schema_for::<crate::schema::DescribeResult>)+ .params("command: a command id. Returns {id, label, params, input, output} (and param_warnings in the warn parameter-check mode): the command's parameter documentation and, once the command has a typed contract, the JSON Schemas (2020-12) of its parameters and of a successful result (null otherwise). Read-only."),];pub fn measure_json(b: &solidcraft_doc::ModelBody) -> Value {@@ -319,6 +326,23 @@ fn model_faces(s: &mut Session, p: &Value) -> Result<Value> {Ok(json!({"body": b.name, "faces": faces}))}+const DESCRIBE_CONTRACT: crate::schema::TypedContract<crate::schema::DescribeParams> = crate::schema::TypedContract::new();++/// A command's prose documentation and, for converted commands, its schemas.+fn describe(_s: &mut Session, p: &Value) -> Result<Value> {+ let id = p.get("command").and_then(Value::as_str).ok_or_else(|| crate::params::bad("engine.describe", "`command` must be a command id"))?;+ let spec = super::find_command(id).ok_or_else(|| crate::EngineError::UnknownCommand(id.to_string()))?;+ let reply = crate::schema::DescribeResult {+ id: spec.id.to_string(),+ label: spec.label.to_string(),+ params: spec.params.to_string(),+ input: spec.contract.map(|c| c.input_schema().to_value()),+ output: spec.output.map(|f| f().to_value()),+ param_warnings: Vec::new(),+ };+ serde_json::to_value(reply).map_err(|e| crate::EngineError::Other(e.to_string()))+}+fn commands(s: &mut Session, _p: &Value) -> Result<Value> {Ok(Value::Array(crate::command_specs().iter().map(|c| serde_json::to_value(c.info(s)).unwrap_or_default()).collect()))}diff --git a/crates/engine/src/cmd/mod.rs b/crates/engine/src/cmd/mod.rsindex 864bf78276..9e8f0623e0 100644--- a/crates/engine/src/cmd/mod.rs+++ b/crates/engine/src/cmd/mod.rs@@ -35,6 +35,7 @@ mod edit;mod face;mod features;mod features_more;+pub(crate) use features::profiles as feature_profiles;pub use features::{auto_operation, extrude_reach};pub use sketch_modify::trim_piece;mod component_link;@@ -96,6 +97,7 @@ pub type Run = fn(&mut Session, &Value) -> Result<Value>;/// evaluate as usual).pub type LiveRun = fn(&mut Session, &Value) -> Result<(Value, Option<crate::LiveEdit>)>;pub type Enabled = fn(&Session) -> std::result::Result<(), String>;+pub type SchemaFn = fn() -> schemars::Schema;pub struct CommandSpec {pub id: &'static str,@@ -120,6 +122,11 @@ pub struct CommandSpec {pub reads_model: bool,/// Registered but not built yet (see `planned!`): the GitHub issue number that tracks it.pub planned: Option<&'static str>,+ /// The command's typed parameter contract, which carries its input schema; `None` until+ /// the command is converted (see `crate::schema`).+ pub contract: Option<&'static dyn crate::schema::Contract>,+ /// The JSON Schema of a successful result; `None` until described.+ pub output: Option<SchemaFn>,}impl CommandSpec {@@ -138,6 +145,8 @@ impl CommandSpec {live: None,reads_model: true,planned: None,+ contract: None,+ output: None,}}/// Not built yet; `issue` tracks building it.@@ -168,6 +177,16 @@ impl CommandSpec {self.shortcut = Some(k);self}+ /// The command's typed parameter contract (see `crate::schema`).+ pub const fn contract(mut self, c: &'static dyn crate::schema::Contract) -> Self {+ self.contract = Some(c);+ self+ }+ /// The JSON Schema of a successful result.+ pub const fn output(mut self, f: SchemaFn) -> Self {+ self.output = Some(f);+ self+ }pub const fn params(mut self, p: &'static str) -> Self {self.params = p;self@@ -325,7 +344,7 @@ pub(crate) fn did_you_mean(id: &str) -> String {}/// Levenshtein distance: the single-character edits that turn `a` into `b`.-fn edit_distance(a: &str, b: &str) -> usize {+pub(crate) fn edit_distance(a: &str, b: &str) -> usize {let b: Vec<char> = b.chars().collect();let mut row: Vec<usize> = (0..=b.len()).collect();for (i, ca) in a.chars().enumerate() {diff --git a/crates/engine/src/hole_face_tests.rs b/crates/engine/src/hole_face_tests.rsindex 43d6499e1a..ededdd4314 100644--- a/crates/engine/src/hole_face_tests.rs+++ b/crates/engine/src/hole_face_tests.rs@@ -92,7 +92,7 @@ fn a_slanted_hole_stays_on_its_axis_when_its_face_moves() {// part: a 40 x 40 x 20 box at z 0..20 (32000 mm³).fn box_part(s: &mut Session) {- run(s, "solid.box", json!({"length": 40, "width": 40, "height": 20, "name": "Part", "position": [20, 20, 0]}));+ run(s, "solid.box", json!({"length": 40, "width": 40, "height": 20, "name": "Part"}));}/// A sketch named `Pts` on the XY plane lifted to `z`, holding the given points (ids p0, p1, ...).diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rsindex 9f1fc0bbaa..a11fba4afa 100644--- a/crates/engine/src/lib.rs+++ b/crates/engine/src/lib.rs@@ -20,6 +20,7 @@ pub mod product_scene;pub mod recovery;pub mod render_jobs;pub mod sample;+pub mod schema;mod slicer_icon;pub mod slicers;pub mod timing;@@ -230,6 +231,9 @@ pub struct Session {pub revision: u64,/// Project a face's edges into a sketch created on it (the default; `sketch.auto_project`).pub auto_project: bool,+ /// How calls that break a command's parameter contract are treated (off by default). It+ /// belongs to the session, not the design, so it survives opening and starting designs.+ pub param_check: schema::ParamCheck,/// The component new sketches and features go into (0 = the root).pub active_component: u64,/// The placement used when authoring shared component geometry.@@ -374,6 +378,7 @@ impl Session {log: Vec::new(),revision: 1,auto_project: true,+ param_check: schema::ParamCheck::Off,active_component: 0,active_occurrence_path: None,pending_moves: Default::default(),@@ -403,10 +408,12 @@ impl Session {/// are the user's rather than the design's: `auto_project` is a preference (#680).pub fn replace_design(&mut self, fresh: Session) {let auto_project = self.auto_project;+ let param_check = self.param_check;let render_viewport = self.render_viewport.clone();let render_jobs = self.render_jobs.scratch();*self = fresh;self.auto_project = auto_project;+ self.param_check = param_check;self.render_viewport = render_viewport;self.render_jobs = render_jobs;}@@ -846,6 +853,7 @@ impl Session {log: Vec::new(),revision: self.revision,auto_project: self.auto_project,+ param_check: self.param_check,active_component: self.active_component,active_occurrence_path: self.active_occurrence_path.clone(),pending_moves: self.pending_moves.clone(),@@ -976,18 +984,24 @@ impl Session {/// Run a script: a JSON array of `{"command": id, "params": {...}}` (or an object with a/// `commands` array). Stops at the first error. Returns each command's result.pub fn run_script(&mut self, script: &Value) -> Result<Vec<Value>> {- Ok(self.run_script_with(script, None)?.0)+ Ok(self.run_script_with(script, None, &mut |_, _| {})?.0)+ }++ /// [`Session::run_script`], calling `each(index, result)` as each command succeeds, so a+ /// caller sees the steps before a later one fails.+ pub fn run_script_each(&mut self, script: &Value, each: &mut dyn FnMut(usize, &Value)) -> Result<Vec<Value>> {+ Ok(self.run_script_with(script, None, each)?.0)}/// [`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))?;+ let (results, timings) = self.run_script_with(script, Some(profile), &mut |_, _| {})?;Ok((results, timings.unwrap_or(Value::Null)))}- fn run_script_with(&mut self, script: &Value, profile: Option<bool>) -> Result<(Vec<Value>, Option<Value>)> {+ fn run_script_with(&mut self, script: &Value, profile: Option<bool>, each: &mut dyn FnMut(usize, &Value)) -> Result<(Vec<Value>, Option<Value>)> {let list = match script {Value::Array(a) => a.clone(),Value::Object(o) => {@@ -1016,7 +1030,9 @@ impl Session {}None => self.execute(id, &p),};- out.push(r.map_err(|e| EngineError::Other(format!("step {} ({id}): {e}", i + 1)))?);+ let r = r.map_err(|e| EngineError::Other(format!("step {} ({id}): {e}", i + 1)))?;+ each(i, &r);+ out.push(r);}let timings = profile.map(|_| serde_json::json!({"timings": steps, "total_ms": timing::round_ms(clock.ms())}));Ok((out, timings))diff --git a/crates/engine/src/schema/check.rs b/crates/engine/src/schema/check.rsnew file mode 100644index 0000000000..a98883e848--- /dev/null+++ b/crates/engine/src/schema/check.rs@@ -0,0 +1,270 @@+//! Contracts, the unknown-key check and the adapter that runs a converted command.++use std::any::TypeId;+use std::collections::{BTreeSet, HashMap};+use std::marker::PhantomData;+use std::sync::{Arc, Mutex, OnceLock};++use schemars::generate::SchemaSettings;+use schemars::{JsonSchema, Schema};+use serde::de::DeserializeOwned;+use serde_json::{Map, Value, json};++use super::record;+use crate::cmd::Run;+use crate::params::bad;+use crate::{Result, Session};++/// How a session treats calls that break a command's contract.+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]+pub enum ParamCheck {+ /// Nothing is checked; commands behave as they always have.+ #[default]+ Off,+ /// The call runs, and a successful object result gains `param_warnings`.+ Warn,+ /// The call is refused, and nothing runs.+ Strict,+}++impl ParamCheck {+ pub fn parse(s: &str) -> Option<ParamCheck> {+ match s.trim().to_ascii_lowercase().as_str() {+ "off" => Some(ParamCheck::Off),+ "warn" => Some(ParamCheck::Warn),+ "strict" => Some(ParamCheck::Strict),+ _ => None,+ }+ }+}++/// The JSON Schema (2020-12) of what deserializes into `T`: a command's parameters.+pub fn input_schema_for<T: JsonSchema>() -> Schema {+ SchemaSettings::draft2020_12().for_deserialize().into_generator().into_root_schema_for::<T>()+}++/// The JSON Schema (2020-12) of what `T` serializes to: a command's result.+pub fn output_schema_for<T: JsonSchema>() -> Schema {+ SchemaSettings::draft2020_12().for_serialize().into_generator().into_root_schema_for::<T>()+}++/// One way a call breaks a contract.+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]+pub struct Issue {+ /// Where: a top-level key (each field type reads its whole value); empty for the whole call.+ pub path: String,+ /// The message, in the engine's style (without the `invalid parameters for …` prefix).+ pub message: String,+ /// For an unknown key, the closest key the command takes.+ pub suggestion: Option<String>,+}++/// A command's typed parameter contract.+pub trait Contract: Sync {+ /// The parameters' JSON Schema.+ fn input_schema(&self) -> Schema;+ /// The top-level keys the command takes.+ fn allowed_keys(&self) -> Arc<BTreeSet<String>>;+ /// Unknown keys and badly shaped parameters in `params`, without running anything.+ fn check(&self, params: &Value) -> Vec<Issue>;+}++/// The contract "the parameters deserialize into `P`". Stateless; `fn() -> P` keeps it+/// `Send + Sync` whatever `P` is.+pub struct TypedContract<P>(PhantomData<fn() -> P>);++impl<P> TypedContract<P> {+ pub const fn new() -> Self {+ TypedContract(PhantomData)+ }+}++impl<P> Default for TypedContract<P> {+ fn default() -> Self {+ Self::new()+ }+}++/// Allowed keys per contract type, worked out once from its schema.+static KEYS: OnceLock<Mutex<HashMap<TypeId, Arc<BTreeSet<String>>>>> = OnceLock::new();++impl<P: DeserializeOwned + JsonSchema + 'static> Contract for TypedContract<P> {+ fn input_schema(&self) -> Schema {+ input_schema_for::<P>()+ }++ fn allowed_keys(&self) -> Arc<BTreeSet<String>> {+ let keys = KEYS.get_or_init(Default::default);+ let mut keys = keys.lock().unwrap_or_else(|poisoned| poisoned.into_inner());+ keys.entry(TypeId::of::<P>()).or_insert_with(|| Arc::new(schema_keys(input_schema_for::<P>().as_value()))).clone()+ }++ fn check(&self, params: &Value) -> Vec<Issue> {+ let object = match params {+ // `Session::execute` reads `null` as `{}`.+ Value::Null => return Vec::new(),+ Value::Object(o) => o,+ _ => return vec![Issue { path: String::new(), message: "parameters must be an object".into(), suggestion: None }],+ };+ let mut issues = unknown_keys(object, &self.allowed_keys());+ if let Err(e) = serde_path_to_error::deserialize::<_, P>(params) {+ issues.push(parse_issue(&e));+ }+ issues+ }+}++/// The most keys of one call that are looked at, and the longest key given a suggestion.+const MAX_KEYS: usize = 64;+const MAX_KEY_LEN: usize = 64;+const MAX_MESSAGE_LEN: usize = 300;+const MAX_WHOLE_LEN: usize = 4096;++/// Marks a deserializer's message as complete as it is (a handler's own wording, such as+/// ``unknown operation `bogus` (…)``), so [`parse_issue`] doesn't put the key in front.+const WHOLE: char = '\u{1}';++/// `message`, marked as complete (see [`WHOLE`]).+pub(crate) fn whole(message: impl std::fmt::Display) -> String {+ format!("{WHOLE}{message}")+}++/// The top-level property names of a schema, following `allOf`/`anyOf`/`oneOf` and `$ref`s+/// into the root's `$defs`.+pub(crate) fn schema_keys(root: &Value) -> BTreeSet<String> {+ fn walk(root: &Value, node: &Value, out: &mut BTreeSet<String>, depth: usize) {+ if depth > 16 {+ return;+ }+ if let Some(props) = node.get("properties").and_then(Value::as_object) {+ out.extend(props.keys().cloned());+ }+ for k in ["allOf", "anyOf", "oneOf"] {+ for branch in node.get(k).and_then(Value::as_array).into_iter().flatten() {+ walk(root, branch, out, depth + 1);+ }+ }+ if let Some(name) = node.get("$ref").and_then(Value::as_str).and_then(|r| r.strip_prefix("#/$defs/"))+ && let Some(target) = root.get("$defs").and_then(|d| d.get(name))+ {+ walk(root, target, out, depth + 1);+ }+ }+ let mut out = BTreeSet::new();+ walk(root, root, &mut out, 0);+ out+}++/// The keys of `params` that `allowed` doesn't list, each with the closest allowed key.+fn unknown_keys(params: &Map<String, Value>, allowed: &BTreeSet<String>) -> Vec<Issue> {+ let mut issues: Vec<Issue> = params+ .keys()+ .take(MAX_KEYS)+ .filter(|k| !allowed.contains(*k))+ .map(|k| {+ let suggestion = nearest(k, allowed);+ // A hostile key is cut, so errors and warnings stay small.+ let k = truncate(k, MAX_KEY_LEN);+ let message = match &suggestion {+ Some(s) => format!("unknown key `{k}`; did you mean `{s}`?"),+ None => format!("unknown key `{k}`"),+ };+ Issue { path: k, message, suggestion }+ })+ .collect();+ if params.len() > MAX_KEYS {+ issues.push(Issue { path: String::new(), message: format!("too many parameters ({}; at most {MAX_KEYS})", params.len()), suggestion: None });+ }+ issues+}++/// `s` cut to at most `max` bytes, on a character boundary, with `…` when cut.+pub(crate) fn truncate(s: &str, max: usize) -> String {+ if s.len() <= max {+ return s.to_string();+ }+ let mut end = max;+ while end > 0 && !s.is_char_boundary(end) {+ end -= 1;+ }+ format!("{}…", s.get(..end).unwrap_or_default())+}++/// The allowed key closest to `key`, when it is close enough to be a likely typo. Keys are+/// short, so short keys may be one edit away at most (`x` is not a typo of `to`).+fn nearest(key: &str, allowed: &BTreeSet<String>) -> Option<String> {+ if key.len() > MAX_KEY_LEN {+ return None;+ }+ let key = key.to_ascii_lowercase();+ let near = (key.chars().count() / 3).max(1);+ allowed+ .iter()+ .map(|a| (crate::cmd::edit_distance(&key, &a.to_ascii_lowercase()), a))+ .filter(|(d, _)| *d <= near)+ .min_by_key(|(d, _)| *d)+ .map(|(_, a)| a.clone())+}++/// A deserialization failure as an issue, in the engine's style.+fn parse_issue(e: &serde_path_to_error::Error<serde_json::Error>) -> Issue {+ let path = e.path().to_string();+ let path = if path == "." { String::new() } else { path };+ let inner = e.inner().to_string();+ if let Some(complete) = inner.strip_prefix(WHOLE) {+ // The handler's own message, which names the caller's value: in full up to a generous+ // cap, since the contract also checks keys the handler ignores (`side` without `thin`).+ return Issue { path, message: truncate(complete, MAX_WHOLE_LEN), suggestion: None };+ }+ let message = if let Some(field) = inner.strip_prefix("missing field `").and_then(|r| r.split('`').next()) {+ let at = if path.is_empty() { field.to_string() } else { format!("{path}.{field}") };+ return Issue { path: at.clone(), message: format!("`{at}` is required"), suggestion: None };+ } else if path.is_empty() {+ inner+ } else if inner.starts_with("must ") {+ format!("`{path}` {inner}")+ } else if let Some((_, expected)) = inner.strip_prefix("invalid type: ").and_then(|r| r.rsplit_once(", expected ")) {+ // serde's wording for the plain types, in the engine's (`thin` must be true or false).+ let expected = match expected {+ "a boolean" => "true or false",+ "a string" => "text",+ other => other,+ };+ format!("`{path}` must be {expected}")+ } else {+ format!("`{path}`: {inner}")+ };+ // serde quotes the caller's value, which may be long.+ Issue { path, message: truncate(&message, MAX_MESSAGE_LEN), suggestion: None }+}++/// Run `handler` as the command `id`, checking the call against `contract` as the session's+/// [`ParamCheck`] level asks (see the module docs). With the level off and no audit recorder,+/// this is exactly `handler(s, p)`.+pub fn run_checked(s: &mut Session, p: &Value, id: &str, contract: &dyn Contract, handler: Run) -> Result<Value> {+ let level = s.param_check;+ let recording = record::enabled();+ if level == ParamCheck::Off && !recording {+ return handler(s, p);+ }+ let issues = contract.check(p);+ if level == ParamCheck::Strict+ && let Some(first) = issues.first()+ {+ if recording {+ record::note(id, &issues, None, p);+ }+ return Err(bad(id, first.message.clone()));+ }+ let result = handler(s, p);+ if recording && !issues.is_empty() {+ record::note(id, &issues, Some(&result), p);+ }+ match result {+ Ok(Value::Object(mut o)) if level == ParamCheck::Warn && !issues.is_empty() => {+ o.insert("param_warnings".into(), json!(issues.iter().map(|i| i.message.as_str()).collect::<Vec<_>>()));+ Ok(Value::Object(o))+ }+ other => other,+ }+}diff --git a/crates/engine/src/schema/commands.rs b/crates/engine/src/schema/commands.rsnew file mode 100644index 0000000000..c9d7920d08--- /dev/null+++ b/crates/engine/src/schema/commands.rs@@ -0,0 +1,220 @@+//! The converted commands' parameter contracts and result types.+//!+//! Field doc comments are the schemas' descriptions. Keys the handlers read only in some+//! situations (`sketch` without `face`, the thin-wall keys with `thin: true`) are optional+//! fields whose descriptions say so; the contracts don't check the combinations, and the+//! handlers ignore those keys otherwise.++use schemars::JsonSchema;+use serde::{Deserialize, Serialize};+use serde_json::Value;++use super::types::{+ AngleExpr, ConventionParam, DirectionParam, ExtentKeyword, ExtrudeOperation, FacesParam, FromPoint, IdOrName, LengthExpr, OperationParam, Point3,+ PointExpr3, ProfilesParam, StringList, ThinSideParam, ToPoint, present,+};++/// Add a box primitive.+#[derive(Debug, Deserialize, JsonSchema)]+#[schemars(deny_unknown_fields)]+pub struct BoxParams {+ /// Size along X.+ pub length: LengthExpr,+ /// Size along Y.+ pub width: LengthExpr,+ /// Size along Z.+ pub height: LengthExpr,+ /// The box's minimum corner. Default: the origin. When both `corner` and `center` are given,+ /// `corner` is used.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "PointExpr3")]+ pub corner: Option<PointExpr3>,+ /// The box's centre, instead of `corner`.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "PointExpr3")]+ pub center: Option<PointExpr3>,+ /// How the box combines with existing bodies. Default: new.+ #[serde(default)]+ pub operation: Option<OperationParam>,+ /// The bodies a join, cut or intersect works on. Default: the bodies the box meets.+ #[serde(default)]+ pub targets: Option<StringList>,+ /// The bodies taking part (the same as `targets` for a primitive).+ #[serde(default)]+ pub participants: Option<StringList>,+ /// The feature's name in the timeline.+ #[serde(default)]+ pub name: Option<String>,+ /// The new body's name.+ #[serde(default)]+ pub body_name: Option<String>,+ /// Names for the new bodies, in order.+ #[serde(default)]+ pub body_names: Option<StringList>,+}++/// Extrude sketch profiles (or a planar body face) into a solid.+#[derive(Debug, Deserialize, JsonSchema)]+#[schemars(deny_unknown_fields)]+pub struct ExtrudeParams {+ /// How far: the length one way; with `direction: symmetric`, the total thickness (per side+ /// with `convention: legacy_per_side`); with `distance2`, the first side's length. Required+ /// unless `through_all` or `to` is given.+ #[serde(default)]+ pub distance: Option<LengthExpr>,+ /// The sketch to extrude, by id or name. Default: the active sketch, else the last one.+ /// Ignored when `face` is given.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "IdOrName")]+ pub sketch: Option<IdOrName>,+ /// Which of the sketch's profiles to extrude. Default: all of them. Ignored when `face` is+ /// given; not allowed with `thin`.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "ProfilesParam")]+ pub profiles: Option<ProfilesParam>,+ /// A point on a planar body face to extrude instead of a sketch profile.+ #[serde(default)]+ pub face: Option<Point3>,+ /// Several coplanar faces of one body to extrude together, by a point on each. Not with+ /// `face`, `sketch` or `profiles`.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "FacesParam")]+ pub faces: Option<FacesParam>,+ /// The body whose face to use, where faces of several bodies meet at `face` (or `faces`).+ #[serde(default)]+ pub face_body: Option<String>,+ /// With `face`, among placed instances: the body whose placement `face` is read in (read by+ /// the engine's frame mapping, before the command runs). Default: `face_body`, else the+ /// body nearest the point.+ #[serde(default)]+ pub body: Option<String>,+ /// Extrude through everything in the way.+ #[serde(default)]+ pub through_all: Option<bool>,+ /// `"through_all"`, the same as `through_all: true`.+ #[serde(default)]+ pub extent: Option<ExtentKeyword>,+ /// Draft angle of the side walls.+ #[serde(default)]+ pub taper: Option<AngleExpr>,+ /// Which way to extrude. Default: positive.+ #[serde(default)]+ pub direction: Option<DirectionParam>,+ /// Two Sides: a second distance the other way from the first side, which may be+ /// `through_all` or `to`; with `direction: negative` the first side goes against the normal+ /// and `distance2` along it.+ #[serde(default)]+ pub distance2: Option<LengthExpr>,+ /// Start this far from the sketch plane, along its normal.+ #[serde(default)]+ pub start_offset: Option<LengthExpr>,+ /// How a symmetric distance is read. Default: total_distance.+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "ConventionParam")]+ pub convention: Option<ConventionParam>,+ /// Extrude up to this face, vertex or point (To Object).+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "ToPoint")]+ pub to: Option<ToPoint>,+ /// How far past `to` to go.+ #[serde(default)]+ pub to_offset: Option<LengthExpr>,+ /// Start at this face or point (From Object).+ #[serde(default, deserialize_with = "present")]+ #[schemars(with = "FromPoint")]+ pub from: Option<FromPoint>,+ /// How the extrusion combines with existing bodies. Default: new.+ #[serde(default)]+ pub operation: Option<ExtrudeOperation>,+ /// The bodies a join, cut or intersect works on. Default for a join from a body's face:+ /// that body.+ #[serde(default)]+ pub targets: Option<StringList>,+ /// The bodies taking part; overrides the default scope.+ #[serde(default)]+ pub participants: Option<StringList>,+ /// The feature's name in the timeline.+ #[serde(default)]+ pub name: Option<String>,+ /// The new body's name.+ #[serde(default)]+ pub body_name: Option<String>,+ /// Names for the new bodies, in order.+ #[serde(default)]+ pub body_names: Option<StringList>,+ /// A thin wall along sketch curves instead of solid profiles.+ // `skip_serializing_if` keeps schemars from writing `default: null`, which `bool` refuses.+ #[serde(default, deserialize_with = "present", skip_serializing_if = "Option::is_none")]+ #[schemars(with = "bool")]+ pub thin: Option<bool>,+ /// With `thin`: the curves the wall follows. Default: every drawn curve of the sketch.+ #[serde(default)]+ pub curves: Option<StringList>,+ /// With `thin`: the wall's thickness.+ #[serde(default)]+ pub thickness: Option<LengthExpr>,+ /// With `thin`: which side of the curves the wall lies on. Default: center.+ #[serde(default)]+ pub side: Option<ThinSideParam>,+ /// With `thin` and `side: two_sides`: the thickness outside.+ #[serde(default)]+ pub thickness2: Option<LengthExpr>,+}++/// Which command to describe.+#[derive(Debug, Deserialize, JsonSchema)]+#[schemars(deny_unknown_fields)]+pub struct DescribeParams {+ /// The command's id, such as `solid.extrude`.+ #[serde(deserialize_with = "command_id")]+ pub command: String,+}++/// A command id, with the `engine.describe` handler's message for anything else.+fn command_id<'de, D: serde::Deserializer<'de>>(d: D) -> Result<String, D::Error> {+ match Value::deserialize(d)? {+ Value::String(s) => Ok(s),+ _ => Err(serde::de::Error::custom("must be a command id")),+ }+}++/// What `engine.describe` returns.+#[derive(Debug, Serialize, JsonSchema)]+pub struct DescribeResult {+ pub id: String,+ pub label: String,+ /// The command's parameter documentation, as prose.+ pub params: String,+ /// The parameters' JSON Schema, or `null` when the command has no contract yet.+ pub input: Option<Value>,+ /// The successful result's JSON Schema, or `null` when not described yet.+ pub output: Option<Value>,+ /// In the warn parameter-check mode: what the call's parameters got wrong.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub param_warnings: Vec<String>,+}++/// What a feature command returns.+#[derive(Debug, Serialize, JsonSchema)]+pub struct FeatureResult {+ /// The new feature's id.+ pub feature: u64,+ /// The new feature's name.+ pub name: String,+ /// Every body after the feature.+ pub bodies: Vec<String>,+ /// The bodies the feature made.+ pub created_bodies: Vec<String>,+ /// Bodies that were there before and now have other geometry.+ pub changed_bodies: Vec<String>,+ /// Bodies that are gone.+ pub removed_bodies: Vec<String>,+ /// A warning from the evaluation (a Boolean that needed a retry, a reference found again+ /// elsewhere), or `null`.+ pub warning: Option<String>,+ /// How long the feature took to evaluate, in milliseconds.+ pub ms: Option<f64>,+ /// In the warn parameter-check mode: what the call's parameters got wrong.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub param_warnings: Vec<String>,+}diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rsnew file mode 100644index 0000000000..3ca5105276--- /dev/null+++ b/crates/engine/src/schema/mod.rs@@ -0,0 +1,54 @@+//! Typed parameter contracts for commands.+//!+//! A converted command declares a [`Contract`]: a Rust type its parameters must deserialize+//! into, from which the input JSON Schema is generated. The contract is checked *in front of*+//! the unchanged handler, which still reads the raw parameters, so a command's behaviour does+//! not change unless the session's [`ParamCheck`] level asks for warnings or refusals.+//!+//! - **Off** (the default): nothing is parsed or checked; the handler runs as before.+//! - **Warn**: the handler runs; a successful object result gains `param_warnings`.+//! - **Strict**: a call with an unknown key or a parameter of the wrong shape is refused, and+//! nothing runs.+//!+//! Unknown keys are the top-level keys a call sends that the contract's schema does not list.+//! Keys the engine reads around a command count too: `frames::to_local` reads `body` for+//! commands with picks (extrude's `face`), which the extrude contract declares; it otherwise+//! rewrites only keys a call already has. `live` is read only for commands with `.live(…)`, and+//! `timeline.redefine` adds only `convention` and `participants`, which the contracts declare.+//!+//! The shared field types in [`types`] decide acceptance by calling the same helpers the+//! handlers use (`params::vec3`, `params::expr`, `Operation::parse`, `features::profiles`…), so+//! "the contract accepts it" means "the handler's own reader accepts it". Where the handler is+//! more lenient (a value of the wrong type read as if the key were absent), the contract is the+//! stricter of the two; that difference is what warn and strict surface.+//!+//! To convert a command: declare its parameters type in `commands.rs` (and its reply type, for+//! an output schema), give its `CommandSpec` `checked!(…)`, `.contract(…)` and `.output(…)` as+//! `solid.extrude` does, and add it to `schemas_and_the_key_check_agree` and, for messages it+//! already gives, `strict_keeps_todays_errors`. Then run the whole test suite with the audit+//! recorder (see `record.rs`): a call that succeeds today but breaks the contract is either a+//! form the contract is missing or a caller's mistake.++mod check;+mod commands;+#[cfg_attr(target_arch = "wasm32", path = "record_wasm.rs")]+mod record;+mod types;++#[cfg(test)]+mod tests;++pub use check::{Contract, Issue, ParamCheck, TypedContract, input_schema_for, output_schema_for, run_checked};+pub use commands::{BoxParams, DescribeParams, DescribeResult, ExtrudeParams, FeatureResult};+pub use types::*;++/// A command's `run` that checks the call against `$contract` before running `$handler`+/// (see [`run_checked`]). Expands to a non-capturing closure, which coerces to the registry's+/// `Run` function pointer.+#[macro_export]+#[doc(hidden)]+macro_rules! checked {+ ($id:literal, $contract:path, $handler:path) => {+ |s: &mut $crate::Session, p: &serde_json::Value| $crate::schema::run_checked(s, p, $id, &$contract, $handler)+ };+}diff --git a/crates/engine/src/schema/record.rs b/crates/engine/src/schema/record.rsnew file mode 100644index 0000000000..ed7894c398--- /dev/null+++ b/crates/engine/src/schema/record.rs@@ -0,0 +1,96 @@+//! The audit recorder, for checking a new contract against every caller the tests have: in a+//! build with the `param-audit` feature, when `SOLIDCRAFT_PARAM_AUDIT` names a directory, every+//! call to a command with a contract that breaks it is recorded, with what the command did, so a+//! test run shows which callers the contracts would warn about or refuse. Without the feature it+//! is compiled (so it is linted and tested) but never on.+//!+//! ```text+//! SOLIDCRAFT_PARAM_AUDIT=$PWD/audit cargo test --workspace --no-fail-fast --features solidcraft-engine/param-audit+//! python3 scripts/param_audit.py audit+//! ```+//!+//! A line whose outcome is `ok` is a call that works today and that strict would refuse: a form+//! the contract is missing, or a mistake the handler silently ignores.+//!+//! Records are aggregated per process by signature (command, issues, outcome, test thread) and+//! written to `<dir>/audit-<pid>.jsonl` when a signature is first seen and again each time its+//! count reaches a power of two; readers keep the highest `count` per signature in each file+//! and add the files up. A process keeps at most 4096 signatures and counts later new ones+//! under one `dropped` line. Writing never fails a command.++use std::collections::HashMap;+use std::io::Write;+use std::path::PathBuf;+use std::sync::{Mutex, OnceLock};++use serde_json::{Value, json};++use super::check::{Issue, truncate};+use crate::Result;++static DIR: OnceLock<Option<PathBuf>> = OnceLock::new();+static SEEN: OnceLock<Mutex<HashMap<String, u64>>> = OnceLock::new();++/// The most signatures a process keeps; later new ones are dropped, and one line says so.+const MAX_SIGNATURES: usize = 4096;++fn dir() -> Option<&'static PathBuf> {+ DIR.get_or_init(|| std::env::var_os("SOLIDCRAFT_PARAM_AUDIT").filter(|v| !v.is_empty()).map(PathBuf::from)).as_ref()+}++/// Whether the recorder is on: built with `param-audit` and the variable set (read once per+/// process).+pub fn enabled() -> bool {+ cfg!(feature = "param-audit") && dir().is_some()+}++/// Count one more call with signature `key`. A new signature beyond `max` is counted under+/// one `dropped` entry instead. Returns whether it was dropped and the count, when the count is+/// a power of two (a line is due).+pub(crate) fn tally(seen: &mut HashMap<String, u64>, key: String, max: usize) -> Option<(bool, u64)> {+ let dropped = seen.len() >= max && !seen.contains_key(&key);+ let count = seen.entry(if dropped { "dropped".into() } else { key }).or_insert(0);+ *count += 1;+ count.is_power_of_two().then_some((dropped, *count))+}++/// One line of the audit file; `sample_params` is cut to 1 KB (empty for `null`).+pub(crate) fn line(command: &str, issues: &[impl serde::Serialize], outcome: &str, source: &str, count: u64, params: &Value) -> Value {+ let sample = if params.is_null() { String::new() } else { truncate(¶ms.to_string(), 1024) };+ json!({"command": command, "issues": issues, "outcome": outcome, "source": source, "count": count, "sample_params": sample})+}++/// What a call did, for its audit line: `ok`, `error: …` from the handler, or `refused` when+/// strict refused it before the handler ran (`None`).+pub(crate) fn outcome_text(outcome: Option<&Result<Value>>) -> String {+ match outcome {+ None => "refused".to_string(),+ Some(Ok(_)) => "ok".to_string(),+ Some(Err(e)) => format!("error: {}", truncate(&e.to_string(), 200)),+ }+}++/// Record one call of `command` that broke its contract with `issues`, and what it did+/// (`None`: refused before the handler ran).+pub fn note(command: &str, issues: &[Issue], outcome: Option<&Result<Value>>, params: &Value) {+ let Some(dir) = dir().filter(|_| enabled()) else { return };+ // A handler's own message names the caller's value, which may be long.+ let mut messages: Vec<String> = issues.iter().map(|i| truncate(&i.message, 300)).collect();+ messages.sort_unstable();+ messages.dedup();+ let outcome = outcome_text(outcome);+ let source = std::thread::current().name().unwrap_or("unnamed").to_string();+ let key = json!([command, messages, outcome, source]).to_string();+ let seen = SEEN.get_or_init(Default::default);+ // The lock is held while writing, so this process's lines never interleave.+ let mut seen = seen.lock().unwrap_or_else(|poisoned| poisoned.into_inner());+ let line = match tally(&mut seen, key, MAX_SIGNATURES) {+ None => return,+ Some((true, count)) => line("*", &["too many signatures; later new ones dropped"], "dropped", "*", count, &Value::Null),+ Some((false, count)) => line(command, &messages, &outcome, &source, count, params),+ };+ let path = dir.join(format!("audit-{}.jsonl", std::process::id()));+ if let Ok(mut f) = std::fs::OpenOptions::new().create(true).append(true).open(path) {+ let _ = f.write_all(format!("{line}\n").as_bytes());+ }+}diff --git a/crates/engine/src/schema/record_wasm.rs b/crates/engine/src/schema/record_wasm.rsnew file mode 100644index 0000000000..32d618f1b0--- /dev/null+++ b/crates/engine/src/schema/record_wasm.rs@@ -0,0 +1,12 @@+//! The audit recorder is native-only; in the browser it is never on.++use serde_json::Value;++use super::check::Issue;+use crate::Result;++pub fn enabled() -> bool {+ false+}++pub fn note(_command: &str, _issues: &[Issue], _outcome: Option<&Result<Value>>, _params: &Value) {}diff --git a/crates/engine/src/schema/tests.rs b/crates/engine/src/schema/tests.rsnew file mode 100644index 0000000000..390c4eaab0--- /dev/null+++ b/crates/engine/src/schema/tests.rs@@ -0,0 +1,633 @@+use serde::de::DeserializeOwned;+use serde_json::{Value, json};++use super::check::schema_keys;+use super::*;+use crate::Session;++fn parse<T: DeserializeOwned>(v: Value) -> Option<T> {+ serde_json::from_value(v).ok()+}++fn box_contract() -> TypedContract<BoxParams> {+ TypedContract::new()+}++fn messages(issues: &[Issue]) -> Vec<String> {+ issues.iter().map(|i| i.message.clone()).collect()+}++#[test]+fn expressions_accept_what_params_expr_accepts() {+ for v in [json!(5), json!(-2.5), json!("w / 2"), json!(" 30 mm "), json!(999_999_999.0)] {+ let want = crate::params::expr(&json!({ "v": v.clone() }), "v");+ assert_eq!(parse::<LengthExpr>(v.clone()).map(|e| e.0), want, "{v}");+ assert!(want.is_some(), "{v}");+ }+ let long = "x".repeat(4097);+ // The cap is in bytes: 2049 two-byte characters are too long (the schema's maxLength counts+ // characters, so it can't say this).+ let wide = "é".repeat(2049);+ for v in [json!(true), json!(null), json!(""), json!(" "), json!(1e9), json!(-1e9), json!([1]), json!({}), json!(long), json!(wide)] {+ assert!(crate::params::expr(&json!({ "v": v.clone() }), "v").is_none(), "{v}");+ assert!(parse::<LengthExpr>(v.clone()).is_none(), "{v}");+ assert!(parse::<AngleExpr>(v.clone()).is_none(), "{v}");+ }+}++#[test]+fn points_accept_what_the_point_readers_accept() {+ assert!(parse::<Point3>(json!([1, 2, 3])).is_some());+ assert!(parse::<Point3>(json!({"x": 1, "y": 2, "z": 3, "label": "extra keys are fine"})).is_some());+ for v in [json!([1, 2]), json!([1, 2, 3, 4]), json!(["a", 2, 3]), json!(null), json!({"x": 1, "y": 2}), json!([1e9, 0, 0])] {+ assert!(parse::<Point3>(v.clone()).is_none(), "{v}");+ }+ assert!(parse::<Point2>(json!([1, 2])).is_some());+ assert!(parse::<Point2>(json!([1, 2, 3])).is_none());+ assert!(parse::<PointExpr3>(json!([1, "w / 2", 3])).is_some());+ assert!(parse::<PointExpr3>(json!({"x": "a", "y": 0, "z": "b + 1"})).is_some());+ for v in [json!([1, 2]), json!(null), json!([true, 1, 2]), json!({"x": 1, "y": 2}), json!("origin")] {+ assert!(parse::<PointExpr3>(v.clone()).is_none(), "{v}");+ }+}++#[test]+fn names_and_lists() {+ assert_eq!(parse::<StringList>(json!("A")).map(|l| l.0), Some(vec!["A".to_string()]));+ assert_eq!(parse::<StringList>(json!(["A", "B"])).map(|l| l.0), Some(vec!["A".to_string(), "B".to_string()]));+ let too_many: Vec<&str> = vec!["x"; 10_001];+ for v in [json!([1]), json!(5), json!(null), json!(too_many.clone())] {+ assert!(parse::<StringList>(v.clone()).is_none(), "{v}");+ }+ let c = TypedContract::<ExtrudeParams>::new();+ assert_eq!(messages(&c.check(&json!({"distance": 5, "targets": too_many}))), vec!["`targets` must have at most 10000 items"]);+ assert!(parse::<IdOrName>(json!(3)).is_some());+ assert!(parse::<IdOrName>(json!("Base")).is_some());+ assert!(parse::<IdOrName>(json!(null)).is_none());+}++#[test]+fn operations_match_operation_parse() {+ for s in [+ "new",+ "join",+ "cut",+ "intersect",+ "newbody",+ "newcomponent",+ "union",+ "add",+ "subtract",+ "difference",+ "intersection",+ "New Body",+ "NEW-body",+ "Cut",+ ] {+ assert!(parse::<OperationParam>(json!(s)).is_some(), "{s}");+ assert!(parse::<ExtrudeOperation>(json!(s)).is_some(), "{s}");+ }+ assert!(parse::<OperationParam>(json!("auto")).is_none(), "box takes no auto");+ assert!(parse::<ExtrudeOperation>(json!("AUTO")).is_some());+ assert!(parse::<ExtrudeOperation>(json!(" auto")).is_none(), "auto is matched without trimming");+ for v in [json!("bogus"), json!(5), json!(null)] {+ assert!(parse::<OperationParam>(v.clone()).is_none(), "{v}");+ }+}++#[test]+fn extrude_keywords() {+ assert!(parse::<DirectionParam>(json!("SYMMETRIC")).is_some());+ assert!(parse::<DirectionParam>(json!("flip")).is_some());+ assert!(parse::<DirectionParam>(json!(" symmetric")).is_none(), "not trimmed");+ assert!(parse::<ExtentKeyword>(json!("Through_All")).is_some());+ assert!(parse::<ExtentKeyword>(json!("to_next")).is_none());+ assert!(parse::<ConventionParam>(json!("total_distance")).is_some());+ assert!(parse::<ConventionParam>(json!("Total_Distance")).is_none(), "serde, case-sensitive");+ assert!(parse::<ThinSideParam>(json!(" Two-Sides ")).is_some(), "ThinSide::parse trims and maps '-'");+ assert!(parse::<ThinSideParam>(json!("middle")).is_none());+}++#[test]+fn profiles_match_features_profiles() {+ for v in [json!("all"), json!("ALL"), json!(0), json!([0, 1]), json!([{"point": [1, 2]}]), json!([["l1", "l2"]]), json!([{"curves": ["l1"]}])] {+ assert!(parse::<ProfilesParam>(v.clone()).is_some(), "{v}");+ }+ for v in [json!("none"), json!([]), json!([true]), json!(null), json!(-1), json!([0, {"point": [1, 2]}])] {+ assert!(parse::<ProfilesParam>(v.clone()).is_none(), "{v}");+ }+ let c = TypedContract::<ExtrudeParams>::new();+ let issue = |profiles: Value| messages(&c.check(&json!({"distance": 5, "profiles": profiles})));+ assert_eq!(issue(json!([])), vec!["`profiles` is empty"]);+ assert_eq!(issue(json!(1.5)), vec!["`profiles` must be \"all\", an index or a list"]);+ assert_eq!(issue(json!(vec![0; 10_001])), vec!["`profiles` must have at most 10000 items"]);+}++#[test]+fn unknown_keys_get_suggestions() {+ let c = box_contract();+ let issues = c.check(&json!({"length": 5, "width": 5, "height": 5, "operaton": "cut", "colour": "red"}));+ assert_eq!(messages(&issues), vec!["unknown key `colour`", "unknown key `operaton`; did you mean `operation`?"]);+ assert_eq!(issues.iter().find(|i| i.path == "operaton").and_then(|i| i.suggestion.clone()), Some("operation".into()));+ // A hostile key is cut in the message.+ let issues = c.check(&json!({"length": 5, "width": 5, "height": 5, "k".repeat(100_000): 1}));+ assert_eq!(messages(&issues), vec![format!("unknown key `{}…`", "k".repeat(64))]);+ // Short keys get a suggestion only one edit away.+ let issues = TypedContract::<ExtrudeParams>::new().check(&json!({"distance": 5, "x": 1, "p0": 1, "ids": 1, "sid": "inside"}));+ assert_eq!(messages(&issues), vec!["unknown key `ids`", "unknown key `p0`", "unknown key `sid`; did you mean `side`?", "unknown key `x`"]);+}++#[test]+fn shape_problems_are_issues() {+ let c = box_contract();+ assert_eq!(messages(&c.check(&json!({"width": 5, "height": 5}))), vec!["`length` is required"]);+ assert_eq!(messages(&c.check(&json!({"length": true, "width": 5, "height": 5}))), vec!["`length` must be a number or an expression"]);+ assert_eq!(+ messages(&c.check(&json!({"length": 5, "width": 5, "height": 5, "corner": null}))),+ vec!["`corner` must be a point [x, y, z] of numbers or length expressions"]+ );+ assert_eq!(messages(&c.check(&json!({"length": 5, "width": 5, "height": 5, "name": 7}))), vec!["`name` must be text"]);+ let e = TypedContract::<ExtrudeParams>::new();+ assert_eq!(messages(&e.check(&json!({"distance": 5, "thin": "true"}))), vec!["`thin` must be true or false"]);+ // serde quotes the caller's value: split at the last ", expected ", and cap the message.+ assert_eq!(messages(&e.check(&json!({"distance": 5, "through_all": "x, expected y"}))), vec!["`through_all` must be true or false"]);+ let long = messages(&e.check(&json!({"distance": 5, "through_all": format!("{}, expected y", "a".repeat(100_000))})));+ assert_eq!(long, vec!["`through_all` must be true or false"]);+ assert_eq!(messages(&c.check(&json!([1, 2, 3]))), vec!["parameters must be an object"]);+ assert!(c.check(&json!(null)).is_empty(), "null is read as {{}}, which the handler then judges");+ let many: serde_json::Map<String, Value> = (0..70).map(|i| (format!("k{i}"), json!(1))).collect();+ assert!(messages(&c.check(&Value::Object(many))).iter().any(|m| m.starts_with("too many parameters")));+}++#[test]+fn schemas_and_the_key_check_agree() {+ for (schema, fields) in [+ (+ input_schema_for::<BoxParams>(),+ vec!["body_name", "body_names", "center", "corner", "height", "length", "name", "operation", "participants", "targets", "width"],+ ),+ (+ input_schema_for::<ExtrudeParams>(),+ vec![+ "body",+ "body_name",+ "body_names",+ "convention",+ "curves",+ "direction",+ "distance",+ "distance2",+ "extent",+ "face",+ "face_body",+ "faces",+ "from",+ "name",+ "operation",+ "participants",+ "profiles",+ "side",+ "sketch",+ "start_offset",+ "taper",+ "targets",+ "thickness",+ "thickness2",+ "thin",+ "through_all",+ "to",+ "to_offset",+ ],+ ),+ ] {+ let v = schema.as_value();+ assert_eq!(schema_keys(v).into_iter().collect::<Vec<_>>(), fields);+ assert_eq!(v.get("additionalProperties"), Some(&json!(false)), "the schema refuses unknown keys too");+ assert_eq!(v.get("$schema").and_then(Value::as_str), Some("https://json-schema.org/draft/2020-12/schema"));+ }+}++#[test]+fn present_null_is_refused_but_absent_is_fine() {+ let base = json!({"length": 5, "width": 5, "height": 5});+ assert!(box_contract().check(&base).is_empty());+ let c: TypedContract<ExtrudeParams> = TypedContract::new();+ assert!(c.check(&json!({"distance": 5})).is_empty());+ // `body` picks the placed instance `face` is read in (frames::to_local), so it is a key.+ assert!(c.check(&json!({"distance": 5, "face": [0, 0, 0], "body": "Part"})).is_empty());+ for key in ["sketch", "profiles", "faces", "convention", "to", "from", "thin"] {+ let mut p = json!({"distance": 5});+ p[key] = Value::Null;+ assert_eq!(c.check(&p).len(), 1, "{key}: null");+ }+ // Keys today's reader treats `null` like absence stay optional.+ for key in ["taper", "direction", "face", "operation", "name"] {+ let mut p = json!({"distance": 5});+ p[key] = Value::Null;+ assert!(c.check(&p).is_empty(), "{key}: null");+ }+}++fn sketch_rectangle(s: &mut Session) {+ for (id, p) in [+ ("sketch.create", json!({"plane": "XY"})),+ ("sketch.rectangle.center", json!({"center": [0, 0], "corner": [10, 10]})),+ ("sketch.finish", json!({})),+ ] {+ if let Err(e) = s.execute(id, &p) {+ panic!("{id}: {e}");+ }+ }+}++fn features(s: &Session) -> usize {+ s.doc.features.len()+}++#[test]+fn off_runs_the_handler_untouched() {+ let mut s = Session::default();+ assert_eq!(s.param_check, ParamCheck::Off);+ let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"}));+ let r = r.unwrap_or_else(|e| panic!("{e}"));+ assert!(r.get("param_warnings").is_none());+ assert_eq!(r["created_bodies"], json!(["Body1"]), "the typo is ignored, as before: a new body");+}++#[test]+fn warn_runs_and_reports() {+ let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() };+ let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"})).unwrap_or_else(|e| panic!("{e}"));+ assert_eq!(r["param_warnings"], json!(["unknown key `operaton`; did you mean `operation`?"]));+ assert_eq!(features(&s), 1);+ let r = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "corner": [20, 0, 0]})).unwrap_or_else(|e| panic!("{e}"));+ assert!(r.get("param_warnings").is_none(), "a clean call carries no warnings");+}++#[test]+fn strict_refuses_and_leaves_the_design_alone() {+ let mut s = Session { param_check: ParamCheck::Strict, ..Session::default() };+ let e = s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "operaton": "cut"})).err().map(|e| e.to_string());+ assert_eq!(e.as_deref(), Some("invalid parameters for `solid.box`: unknown key `operaton`; did you mean `operation`?"));+ assert_eq!(features(&s), 0);+ sketch_rectangle(&mut s);+ let before = features(&s);+ let e = s.execute("solid.extrude", &json!({"distance": 5, "tapper": "10 deg"})).err().map(|e| e.to_string());+ assert_eq!(e.as_deref(), Some("invalid parameters for `solid.extrude`: unknown key `tapper`; did you mean `taper`?"));+ let e = s.execute("solid.extrude", &json!({"distance": 5, "operation": 5})).err().map(|e| e.to_string());+ assert!(e.as_deref().is_some_and(|e| e.contains("`operation` must be one of")), "{e:?}");+ assert_eq!(features(&s), before);+ s.execute("solid.extrude", &json!({"distance": 5, "direction": "symmetric"})).unwrap_or_else(|e| panic!("{e}"));+ assert_eq!(features(&s), before + 1);+}++#[test]+fn nested_runs_are_checked_too() {+ let mut s = Session::default();+ sketch_rectangle(&mut s);+ s.execute("solid.extrude", &json!({"distance": 5, "name": "Slab"})).unwrap_or_else(|e| panic!("{e}"));+ s.param_check = ParamCheck::Strict;+ let e = s+ .execute("timeline.redefine", &json!({"feature": "Slab", "command": "solid.extrude", "params": {"distance": 8, "directon": "symmetric"}}))+ .err()+ .map(|e| e.to_string());+ assert!(e.as_deref().is_some_and(|e| e.contains("unknown key `directon`; did you mean `direction`?")), "{e:?}");+}++#[test]+fn the_level_survives_a_new_design() {+ let mut s = Session { param_check: ParamCheck::Strict, ..Session::default() };+ s.execute("file.new", &json!({})).unwrap_or_else(|e| panic!("{e}"));+ assert_eq!(s.param_check, ParamCheck::Strict);+ assert_eq!(s.scratch().param_check, ParamCheck::Strict);+}++#[test]+fn feature_result_serializes_like_the_old_reply() {+ for (warning, ms) in [(None, None), (Some("a Boolean needed a retry".to_string()), Some(12.5)), (None, Some(0.0)), (None, Some(1.0 / 3.0))] {+ let old = json!({"feature": 7, "name": "Box1", "bodies": ["A", "B"], "created_bodies": ["B"], "changed_bodies": [],+ "removed_bodies": ["C"], "warning": warning, "ms": ms});+ let new = FeatureResult {+ feature: 7,+ name: "Box1".into(),+ bodies: vec!["A".into(), "B".into()],+ created_bodies: vec!["B".into()],+ changed_bodies: vec![],+ removed_bodies: vec!["C".into()],+ warning: warning.clone(),+ ms,+ param_warnings: vec![],+ };+ assert_eq!(serde_json::to_value(&new).ok(), Some(old));+ }+}++/// Whether `v` conforms to `node` of the schema `root`, for the keywords these schemas use+/// apart from `pattern`: `type`, `properties`, `required`, `additionalProperties: false`,+/// `items`, `minItems`, `maxItems`, `uniqueItems`, `enum`, `minLength`, `maxLength`, `minimum`,+/// `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `anyOf`, `not` and `$ref`. (`integer`+/// here is what serde reads as one, so `1.0` is not.)+fn conforms(root: &Value, node: &Value, v: &Value) -> bool {+ if let Some(name) = node.get("$ref").and_then(Value::as_str).and_then(|r| r.strip_prefix("#/$defs/")) {+ return root.get("$defs").and_then(|d| d.get(name)).is_some_and(|t| conforms(root, t, v));+ }+ if let Some(branches) = node.get("anyOf").and_then(Value::as_array)+ && !branches.iter().any(|b| conforms(root, b, v))+ {+ return false;+ }+ if node.get("not").is_some_and(|n| conforms(root, n, v)) {+ return false;+ }+ let is = |t: &str| match t {+ "null" => v.is_null(),+ "boolean" => v.is_boolean(),+ "integer" => v.is_u64() || v.is_i64(),+ "number" => v.is_number(),+ "string" => v.is_string(),+ "array" => v.is_array(),+ "object" => v.is_object(),+ _ => false,+ };+ let typed = match node.get("type") {+ Some(Value::String(t)) => is(t),+ Some(Value::Array(ts)) => ts.iter().filter_map(Value::as_str).any(is),+ _ => true,+ };+ if !typed {+ return false;+ }+ if let (Some(items), Some(a)) = (node.get("items"), v.as_array())+ && !a.iter().all(|x| conforms(root, items, x))+ {+ return false;+ }+ let bound = |k: &str| node.get(k).and_then(Value::as_u64).map(|n| n as usize);+ if let Some(a) = v.as_array() {+ let unique = a.iter().enumerate().all(|(i, x)| !a.iter().skip(i + 1).any(|y| y == x));+ if bound("minItems").is_some_and(|n| a.len() < n)+ || bound("maxItems").is_some_and(|n| a.len() > n)+ || (node.get("uniqueItems") == Some(&json!(true)) && !unique)+ {+ return false;+ }+ }+ if let Some(s) = v.as_str() {+ let n = s.chars().count();+ if bound("minLength").is_some_and(|m| n < m) || bound("maxLength").is_some_and(|m| n > m) {+ return false;+ }+ }+ if let Some(x) = v.as_f64() {+ let limit = |k: &str| node.get(k).and_then(Value::as_f64);+ if limit("minimum").is_some_and(|m| x < m)+ || limit("maximum").is_some_and(|m| x > m)+ || limit("exclusiveMinimum").is_some_and(|m| x <= m)+ || limit("exclusiveMaximum").is_some_and(|m| x >= m)+ {+ return false;+ }+ }+ if let Some(values) = node.get("enum").and_then(Value::as_array)+ && !values.contains(v)+ {+ return false;+ }+ if let Some(o) = v.as_object() {+ let props = node.get("properties").and_then(Value::as_object);+ let mut required = node.get("required").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str);+ if !required.all(|k| o.contains_key(k)) {+ return false;+ }+ for (k, x) in o {+ match props.and_then(|p| p.get(k)) {+ Some(p) if !conforms(root, p, x) => return false,+ None if node.get("additionalProperties") == Some(&json!(false)) => return false,+ _ => {}+ }+ }+ }+ true+}++#[test]+fn replies_match_the_output_schema() {+ let schema = output_schema_for::<FeatureResult>();+ let schema = schema.as_value();+ let required: Vec<&str> = schema.get("required").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).collect();+ assert!(!required.contains(&"param_warnings"));+ let mut s = Session::default();+ sketch_rectangle(&mut s);+ s.param_check = ParamCheck::Warn;+ let replies = [+ s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "corner": [20, 0, 0]})),+ s.execute("solid.extrude", &json!({"distance": 5, "operation": "join"})),+ s.execute("solid.box", &json!({"length": 5, "width": 5, "height": 5, "colour": "red"})),+ ];+ for r in replies {+ let r = r.unwrap_or_else(|e| panic!("{e}"));+ assert!(conforms(schema, schema, &r), "{r} doesn't match {schema}");+ }+ // The check itself catches a wrong type, a wrong item type and a missing key. (The output+ // schema leaves other keys open, so a new result key doesn't break clients.)+ let ok = json!({"feature": 1, "name": "Box1", "bodies": [], "created_bodies": [], "changed_bodies": [], "removed_bodies": [], "warning": null, "ms": null});+ assert!(conforms(schema, schema, &ok));+ for (k, v) in [("feature", json!("1")), ("bodies", json!([1])), ("warning", json!(5)), ("ms", json!("1"))] {+ let mut bad = ok.clone();+ bad[k] = v;+ assert!(!conforms(schema, schema, &bad), "{bad}");+ }+ let mut bad = ok.clone();+ bad.as_object_mut().map(|o| o.remove("name"));+ assert!(!conforms(schema, schema, &bad), "{bad}");+}++#[cfg(not(target_arch = "wasm32"))]+#[test]+fn the_recorder_keeps_a_bounded_number_of_signatures() {+ use super::record::tally;+ let mut seen = std::collections::HashMap::new();+ // Lines are due at counts 1, 2, 4, …+ assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 1)));+ assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 2)));+ assert_eq!(tally(&mut seen, "a".into(), 2), None);+ assert_eq!(tally(&mut seen, "b".into(), 2), Some((false, 1)));+ // Full: new signatures are counted under one entry; known ones still count.+ assert_eq!(tally(&mut seen, "c".into(), 2), Some((true, 1)));+ assert_eq!(tally(&mut seen, "d".into(), 2), Some((true, 2)));+ assert_eq!(tally(&mut seen, "a".into(), 2), Some((false, 4)));+ assert_eq!(seen.len(), 3);+}++#[test]+fn describe_returns_both_schemas() {+ let mut s = Session::default();+ let d = s.execute("engine.describe", &json!({"command": "solid.box"})).unwrap_or_else(|e| panic!("{e}"));+ assert_eq!(d["id"], "solid.box");+ assert!(d["input"]["properties"].get("length").is_some());+ assert!(d["output"]["properties"].get("created_bodies").is_some());+ // Its own output schema lists the warnings warn mode can add.+ let own = s.execute("engine.describe", &json!({"command": "engine.describe"})).unwrap_or_else(|e| panic!("{e}"));+ assert!(own["output"]["properties"].get("param_warnings").is_some(), "{own}");+ let d = s.execute("engine.describe", &json!({"command": "solid.revolve"})).unwrap_or_else(|e| panic!("{e}"));+ assert!(d["input"].is_null() && d["output"].is_null(), "unconverted commands have no schemas yet");+ let e = s.execute("engine.describe", &json!({"command": "solid.extrud"})).err().map(|e| e.to_string());+ assert!(e.as_deref().is_some_and(|e| e.contains("did you mean `solid.extrude`")), "{e:?}");+}++/// The profiles schema and the contract agree on every listed case; the schema is deliberately+/// narrower on non-text curve ids and loops past the outer one (and describes the app's+/// `whole_boundaries` selection only by its `type`).+#[test]+fn the_profiles_schema_matches_the_contract() {+ let root = input_schema_for::<ExtrudeParams>();+ let root = root.as_value();+ let node = &root["properties"]["profiles"];+ let accepted = |v: &Value| parse::<ProfilesParam>(v.clone()).is_some();+ for v in [+ json!(3),+ json!(-1),+ json!([]),+ json!([0, 1]),+ json!([0, {"point": [1, 2]}]),+ json!([{"point": [1, 2]}, {"point": [3, 4]}]),+ json!([{"point": [1e9, 2]}]),+ json!([["l1"]]),+ json!([[]]),+ json!([{"curves": "l1"}, ["l2"]]),+ json!([{"curves": []}]),+ json!([{"loops": []}]),+ json!([{"loops": [5]}]),+ json!([{"loops": [{"curves": ["l1"]}]}]),+ json!({}),+ json!({"offset_boundaries": ["a"]}),+ json!({"offset_boundaries": []}),+ json!({"offset_boundaries": ["a", "a"]}),+ json!({"type": "offset_boundaries", "associations": ["a", "b"]}),+ json!({"type": "something"}),+ serde_json::from_str("18446744073709551616").unwrap_or_default(),+ // The helper's precedence: all items with `point` are points; `curves` before `loops`;+ // `offset_boundaries` before `type`.+ json!([{"point": null, "curves": ["l1"]}]),+ json!([{"point": [1, 2], "curves": ["l1"]}]),+ json!([{"curves": [], "loops": [{"curves": ["l1"]}]}]),+ json!([{"point": [0, 0], "curves": ["l1"]}, ["l2"]]),+ json!([{"point": [1, 2], "curves": ["a"]}, {"curves": ["b"]}]),+ json!([{"point": [0, 0], "loops": [{"curves": ["l1"]}]}, {"curves": "l2"}]),+ json!({"type": "offset_boundaries", "associations": ["a"], "offset_boundaries": []}),+ ] {+ assert_eq!(conforms(root, node, &v), accepted(&v), "{v}");+ }+ // An index is bounded to what the helper reads as a u64. (`conforms` refuses 2^64 above on+ // type alone, so the bound itself is checked here.)+ let index = |b: &Value| b.get("type") == Some(&json!("integer"));+ let bounds: Vec<&Value> = root["$defs"]["Profiles"]["anyOf"]+ .as_array()+ .into_iter()+ .flatten()+ .flat_map(|b| [b, &b["items"]])+ .filter(|b| index(b))+ .map(|b| &b["maximum"])+ .collect();+ assert_eq!(bounds, [&json!(u64::MAX), &json!(u64::MAX)]);+ // Where the schema is deliberately narrower: non-text ids and loops past the outer one.+ for v in [json!([["l1", 5]]), json!([{"loops": [{"curves": ["l1"]}, 5]}])] {+ assert!(accepted(&v) && !conforms(root, node, &v), "{v}");+ }+}++#[cfg(not(target_arch = "wasm32"))]+#[test]+fn recorder_lines_have_the_documented_shape() {+ let l = super::record::line("solid.box", &["unknown key `x`"], "ok", "a_test", 4, &json!({"x": "y".repeat(5000)}));+ let keys: Vec<&str> = l.as_object().into_iter().flat_map(|o| o.keys().map(String::as_str)).collect();+ assert_eq!(keys, ["command", "count", "issues", "outcome", "sample_params", "source"]);+ assert_eq!((l["command"].clone(), l["count"].clone(), l["outcome"].clone()), (json!("solid.box"), json!(4), json!("ok")));+ assert!(l["sample_params"].as_str().is_some_and(|s| s.len() <= 1024 + "…".len() && s.ends_with('…')), "{l}");+ // A strict refusal is told apart from a handler's error.+ use super::record::outcome_text;+ assert_eq!(outcome_text(None), "refused");+ assert_eq!(outcome_text(Some(&Ok(json!({})))), "ok");+ assert_eq!(outcome_text(Some(&Err(crate::EngineError::Other("boom".into())))), "error: boom");+ // The recorder is on exactly when built with `param-audit` and the variable names a directory.+ let set = std::env::var_os("SOLIDCRAFT_PARAM_AUDIT").is_some_and(|v| !v.is_empty());+ assert_eq!(super::record::enabled(), cfg!(feature = "param-audit") && set);+}++/// A call that already fails gets the same error in strict as with the check off, apart from+/// the missing-key, missing-instead-of-wrong-type, non-object, profile-index, 10,000-item and+/// over-4-KB messages the report lists.+#[test]+fn strict_keeps_todays_errors() {+ let cases = [+ ("solid.box", json!({"length": 5, "width": 5, "height": 5, "operation": "bogus"})),+ ("solid.box", json!({"length": true, "width": 5, "height": 5})),+ ("solid.box", json!({"length": 5, "width": 5, "height": 5, "corner": [1, 2]})),+ ("solid.extrude", json!({"distance": 5, "operation": "bogus"})),+ ("solid.extrude", json!({"distance": 5, "direction": "sideways"})),+ ("solid.extrude", json!({"distance": 5, "direction": "SIDEWAYS"})),+ ("solid.extrude", json!({"distance": 5, "profiles": [{"point": [1]}]})),+ ("solid.extrude", json!({"distance": 5, "profiles": [["l1"], 7]})),+ ("solid.extrude", json!({"distance": 5, "profiles": []})),+ ("solid.extrude", json!({"distance": 5, "profiles": [true]})),+ ("solid.extrude", json!({"distance": 5, "faces": []})),+ ("solid.extrude", json!({"distance": 5, "faces": null})),+ ("solid.extrude", json!({"distance": 5, "faces": [[1, 2]]})),+ ("solid.extrude", json!({"distance": 5, "profiles": {"offset_boundaries": ["a", "a"]}})),+ ("solid.extrude", json!({"distance": 5, "thin": true, "thickness": 1, "side": "middle"})),+ ("solid.extrude", json!({"distance": 5, "thin": "true"})),+ ("solid.extrude", json!({"distance": 5, "to": [1, 2]})),+ ("solid.extrude", json!({"distance": 5, "from": "x"})),+ ("solid.extrude", json!({"distance": 5, "sketch": true})),+ ("solid.extrude", json!({"distance": 5, "convention": "per_side"})),+ ("solid.extrude", json!({"distance": " "})),+ ("solid.extrude", json!({"distance": 5, "operation": "x".repeat(1000)})),+ ("engine.describe", json!({"command": 5})),+ ("engine.describe", json!({"command": null})),+ ("engine.describe", json!({"command": "solid.extrud"})),+ ];+ for (id, p) in cases {+ let error = |level: ParamCheck| {+ let mut s = Session { param_check: level, ..Session::default() };+ sketch_rectangle(&mut s);+ s.execute(id, &p).err().map(|e| e.to_string())+ };+ let off = error(ParamCheck::Off);+ assert!(off.is_some(), "{p} should fail today");+ assert_eq!(error(ParamCheck::Strict), off, "{p}");+ }+}++/// Every `default` in the input schemas is a value its own property schema allows.+#[test]+fn schema_defaults_are_valid() {+ for root in [input_schema_for::<BoxParams>(), input_schema_for::<ExtrudeParams>()] {+ let root = root.as_value();+ for (key, property) in root["properties"].as_object().into_iter().flatten() {+ if let Some(d) = property.get("default") {+ assert!(conforms(root, property, d), "`{key}`: default {d} doesn't match {property}");+ }+ }+ }+}++/// The expression schema's "not blank" pattern uses exactly the whitespace Rust's `trim` does.+#[test]+fn the_blank_pattern_matches_trim() {+ let listed = |c: char| super::types::WHITESPACE.iter().any(|&(a, b)| (a..=b).contains(&c));+ for c in (0..=0x10_ffff).filter_map(char::from_u32) {+ assert_eq!(listed(c), c.is_whitespace(), "U+{:04X}", c as u32);+ }+ assert_eq!(super::types::not_blank_pattern(), r"[^\u0009-\u000d\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028-\u2029\u202f\u205f\u3000]");+ assert!(parse::<LengthExpr>(json!("\u{85}")).is_none() && parse::<LengthExpr>(json!("\u{feff}")).is_some());+}++/// A handler-worded message for a key the handler ignores stays bounded in a warning.+#[test]+fn long_values_in_handler_messages_are_capped() {+ let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() };+ sketch_rectangle(&mut s);+ let r = s.execute("solid.extrude", &json!({"distance": 5, "side": "x".repeat(1_000_000)})).unwrap_or_else(|e| panic!("{e}"));+ let w = r["param_warnings"][0].as_str().unwrap_or_default();+ assert!(w.starts_with("unknown side `xxx") && w.len() <= 4096 + "…".len(), "{} bytes", w.len());+}diff --git a/crates/engine/src/schema/types.rs b/crates/engine/src/schema/types.rsnew file mode 100644index 0000000000..519641f585--- /dev/null+++ b/crates/engine/src/schema/types.rs@@ -0,0 +1,585 @@+//! Shared parameter types. Each one decides acceptance with the helper the handlers already+//! use, applied to the raw JSON value, so a contract can never accept a value its handler's own+//! reader would refuse. Their schemas describe the accepted forms.++use std::borrow::Cow;++use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};+use serde::de::Error as _;+use serde::{Deserialize, Deserializer};+use serde_json::{Value, json};+use solidcraft_doc::{Expr, Operation, ThinSide};+use solidcraft_geom::{Vec2, Vec3};++use super::check::whole;+use crate::params;++/// For optional fields whose key may be absent but not `null`: absent is `None` (with+/// `#[serde(default)]`), a present value, `null` included, goes to `T`'s deserializer. Pair it+/// with `#[schemars(with = "T")]` so the schema has no `null` branch.+pub fn present<'de, D: Deserializer<'de>, T: Deserialize<'de>>(d: D) -> Result<Option<T>, D::Error> {+ T::deserialize(d).map(Some)+}++/// A coordinate's schema: a number below 1e9 in size, as `params::finite` requires.+fn coordinate() -> Value {+ json!({"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9})+}++/// The characters Rust's `trim` removes (Unicode `White_Space`), as ranges. A regex's `\s`+/// differs (it has U+FEFF and lacks U+0085), so the expression schema spells them out.+pub(crate) const WHITESPACE: [(char, char); 10] = [+ ('\u{9}', '\u{d}'),+ (' ', ' '),+ ('\u{85}', '\u{85}'),+ ('\u{a0}', '\u{a0}'),+ ('\u{1680}', '\u{1680}'),+ ('\u{2000}', '\u{200a}'),+ ('\u{2028}', '\u{2029}'),+ ('\u{202f}', '\u{202f}'),+ ('\u{205f}', '\u{205f}'),+ ('\u{3000}', '\u{3000}'),+];++/// A pattern for text that isn't blank once trimmed: a character outside [`WHITESPACE`].+pub(crate) fn not_blank_pattern() -> String {+ let u = |c: char| format!("\\u{:04x}", c as u32);+ let class: String = WHITESPACE.iter().map(|&(a, b)| if a == b { u(a) } else { format!("{}-{}", u(a), u(b)) }).collect();+ format!("[^{class}]")+}++/// `v` as the only key of an object, for the helpers that read `p.get(key)`.+fn wrap(v: Value) -> Value {+ json!({ "v": v })+}++macro_rules! expr_type {+ ($(#[$doc:meta])* $name:ident, $title:literal, $description:literal) => {+ $(#[$doc])*+ #[derive(Clone, Debug, PartialEq)]+ pub struct $name(pub Expr);++ impl<'de> Deserialize<'de> for $name {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ params::expr(&wrap(Value::deserialize(d)?), "v").map($name).ok_or_else(|| D::Error::custom("must be a number or an expression"))+ }+ }++ impl JsonSchema for $name {+ fn schema_name() -> Cow<'static, str> {+ $title.into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({+ "description": $description,+ "anyOf": [+ {"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9},+ {"type": "string", "minLength": 1, "maxLength": 4096, "pattern": not_blank_pattern()}+ ]+ })+ }+ }+ };+}++expr_type!(+ /// A length: a number, read in the design's length unit, or an expression such as+ /// `"w / 2"` or `"30 mm"`.+ LengthExpr,+ "LengthExpr",+ "A length: a number in the design's length unit, or an expression such as \"w / 2\" or \"30 mm\"."+);+expr_type!(+ /// An angle: a number of degrees, or an expression such as `"30 deg"` or `"a / 2"`.+ AngleExpr,+ "AngleExpr",+ "An angle: a number of degrees, or an expression such as \"30 deg\" or \"a / 2\"."+);++/// A point in mm: `[x, y, z]` or `{x, y, z}` of finite numbers (read by `params::vec3`).+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct Point3(pub Vec3);++impl<'de> Deserialize<'de> for Point3 {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ params::vec3(&Value::deserialize(d)?).map(Point3).ok_or_else(|| D::Error::custom("must be a point [x, y, z] of numbers"))+ }+}++impl JsonSchema for Point3 {+ fn schema_name() -> Cow<'static, str> {+ "Point3".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ let c = coordinate();+ json_schema!({+ "description": "A point in mm: [x, y, z] or {\"x\", \"y\", \"z\"}.",+ "anyOf": [+ {"type": "array", "items": c, "minItems": 3, "maxItems": 3},+ {"type": "object", "properties": {"x": c, "y": c, "z": c}, "required": ["x", "y", "z"]}+ ]+ })+ }+}++macro_rules! target_point {+ ($(#[$doc:meta])* $name:ident, $message:literal) => {+ $(#[$doc])*+ #[derive(Clone, Copy, Debug, PartialEq)]+ pub struct $name(pub Vec3);++ impl<'de> Deserialize<'de> for $name {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ params::vec3(&Value::deserialize(d)?).map($name).ok_or_else(|| D::Error::custom($message))+ }+ }++ impl JsonSchema for $name {+ fn schema_name() -> Cow<'static, str> {+ stringify!($name).into()+ }+ fn inline_schema() -> bool {+ true+ }+ fn json_schema(generator: &mut SchemaGenerator) -> Schema {+ generator.subschema_for::<Point3>()+ }+ }+ };+}++target_point!(+ /// Extrude's `to`: a [`Point3`], with the handler's message.+ ToPoint,+ "must be a point [x, y, z] on the face, vertex or point to extrude to"+);+target_point!(+ /// Extrude's `from`: a [`Point3`], with the handler's message.+ FromPoint,+ "must be a point [x, y, z] on the face or point to start from"+);++/// Extrude's `faces`: 1 to 1024 points on coplanar faces of one body, read as the handler reads+/// them, with its messages.+#[derive(Clone, Debug, PartialEq)]+pub struct FacesParam(pub Vec<Vec3>);++impl<'de> Deserialize<'de> for FacesParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let v = Value::deserialize(d)?;+ let faces = v+ .as_array()+ .filter(|faces| !faces.is_empty() && faces.len() <= 1024)+ .ok_or_else(|| D::Error::custom(whole("faces must contain between 1 and 1024 points")))?;+ faces+ .iter()+ .map(params::vec3)+ .collect::<Option<Vec<_>>>()+ .map(FacesParam)+ .ok_or_else(|| D::Error::custom(whole("faces must be points [x,y,z]")))+ }+}++impl JsonSchema for FacesParam {+ fn schema_name() -> Cow<'static, str> {+ "Faces".into()+ }+ fn json_schema(generator: &mut SchemaGenerator) -> Schema {+ let point = generator.subschema_for::<Point3>();+ json_schema!({+ "description": "Points in mm, one on each of the coplanar faces of one body to extrude together.",+ "type": "array", "items": point, "minItems": 1, "maxItems": 1024+ })+ }+}++/// A sketch point in mm: `[x, y]` or `{x, y}` of finite numbers (read by `params::vec2`).+#[derive(Clone, Copy, Debug, PartialEq)]+pub struct Point2(pub Vec2);++impl<'de> Deserialize<'de> for Point2 {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ params::vec2(&Value::deserialize(d)?).map(Point2).ok_or_else(|| D::Error::custom("must be a point [x, y] of numbers"))+ }+}++impl JsonSchema for Point2 {+ fn schema_name() -> Cow<'static, str> {+ "Point2".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ let c = coordinate();+ json_schema!({+ "description": "A sketch point in mm: [x, y] or {\"x\", \"y\"}.",+ "anyOf": [+ {"type": "array", "items": c, "minItems": 2, "maxItems": 2},+ {"type": "object", "properties": {"x": c, "y": c}, "required": ["x", "y"]}+ ]+ })+ }+}++/// A placement point: `[x, y, z]` or `{x, y, z}`, each a number (mm) or a length expression,+/// as `features::point_param` reads it. Whether the expressions evaluate is checked by the+/// handler, which has the design.+#[derive(Clone, Debug, PartialEq)]+pub struct PointExpr3(pub [Expr; 3]);++impl<'de> Deserialize<'de> for PointExpr3 {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let v = Value::deserialize(d)?;+ let coords: Option<Vec<&Value>> = match &v {+ Value::Array(a) if a.len() == 3 => Some(a.iter().collect()),+ Value::Object(o) => ["x", "y", "z"].iter().map(|k| o.get(*k)).collect(),+ _ => None,+ };+ coords+ .and_then(|c| c.into_iter().map(|c| params::expr(&wrap(c.clone()), "v")).collect::<Option<Vec<Expr>>>())+ .and_then(|c| <[Expr; 3]>::try_from(c).ok())+ .map(PointExpr3)+ .ok_or_else(|| D::Error::custom("must be a point [x, y, z] of numbers or length expressions"))+ }+}++impl JsonSchema for PointExpr3 {+ fn schema_name() -> Cow<'static, str> {+ "PointExpr3".into()+ }+ fn json_schema(generator: &mut SchemaGenerator) -> Schema {+ let c = generator.subschema_for::<LengthExpr>();+ json_schema!({+ "description": "A point: [x, y, z] or {\"x\", \"y\", \"z\"}, each a number in mm or a length expression.",+ "anyOf": [+ {"type": "array", "items": c, "minItems": 3, "maxItems": 3},+ {"type": "object", "properties": {"x": c, "y": c, "z": c}, "required": ["x", "y", "z"]}+ ]+ })+ }+}++/// A feature referred to by its id (a number) or its name (a string).+#[derive(Clone, Debug, PartialEq)]+pub struct IdOrName(pub String);++impl<'de> Deserialize<'de> for IdOrName {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ match Value::deserialize(d)? {+ Value::Number(n) => Ok(IdOrName(n.to_string())),+ Value::String(s) => Ok(IdOrName(s)),+ _ => Err(D::Error::custom("must be an id or name")),+ }+ }+}++impl JsonSchema for IdOrName {+ fn schema_name() -> Cow<'static, str> {+ "IdOrName".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({"description": "A feature's id (a number) or its name.", "type": ["number", "string"]})+ }+}++/// One name or a list of names, at most 10 000.+#[derive(Clone, Debug, Default, PartialEq)]+pub struct StringList(pub Vec<String>);++impl<'de> Deserialize<'de> for StringList {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let fail = || D::Error::custom("must be a name or a list of names");+ match Value::deserialize(d)? {+ Value::String(s) => Ok(StringList(vec![s])),+ Value::Array(a) if a.len() > 10_000 => Err(D::Error::custom("must have at most 10000 items")),+ Value::Array(a) => a+ .into_iter()+ .map(|v| if let Value::String(s) = v { Some(s) } else { None })+ .collect::<Option<Vec<_>>>()+ .map(StringList)+ .ok_or_else(fail),+ _ => Err(fail()),+ }+ }+}++impl JsonSchema for StringList {+ fn schema_name() -> Cow<'static, str> {+ "StringList".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ json_schema!({+ "description": "A name, or a list of names.",+ "anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}, "maxItems": 10000}]+ })+ }+}++/// The spellings `Operation::parse` accepts, canonical ones first (it also ignores case, spaces,+/// '_' and '-', which an enum can't say).+const OPERATIONS: [&str; 13] = [+ "new",+ "join",+ "cut",+ "intersect",+ "new_body",+ "newbody",+ "new_component",+ "newcomponent",+ "union",+ "add",+ "subtract",+ "difference",+ "intersection",+];++/// A string `ok` accepts. A string it refuses gets `unknown(s)` (the handler's own message,+/// marked [`whole`]); anything else, which the handlers ignore, "must be one of `expected`".+fn string_matching<'de, D: Deserializer<'de>>(+ d: D,+ ok: impl Fn(&str) -> bool,+ expected: &str,+ unknown: impl Fn(&str) -> String,+) -> Result<String, D::Error> {+ match Value::deserialize(d)? {+ Value::String(s) if ok(&s) => Ok(s),+ Value::String(s) => Err(D::Error::custom(unknown(&s))),+ _ => Err(D::Error::custom(format!("must be one of {expected}"))),+ }+}++/// `features::operation`'s message for an operation it doesn't know.+fn unknown_operation(s: &str) -> String {+ whole(format!("unknown operation `{s}` (new, join, cut, intersect)"))+}++fn enum_schema(values: &[&str], description: &str) -> Schema {+ json_schema!({"description": description, "type": "string", "enum": values})+}++/// How a feature combines with existing bodies, as `features::operation` reads it.+#[derive(Clone, Debug, PartialEq)]+pub struct OperationParam(pub Operation);++impl<'de> Deserialize<'de> for OperationParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let s = string_matching(d, |s| Operation::parse(s).is_some(), "new, join, cut or intersect", unknown_operation)?;+ Operation::parse(&s).map(OperationParam).ok_or_else(|| D::Error::custom("must be one of new, join, cut or intersect"))+ }+}++impl JsonSchema for OperationParam {+ fn schema_name() -> Cow<'static, str> {+ "Operation".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ enum_schema(+ &OPERATIONS,+ "How the feature combines with existing bodies: new, join, cut or intersect. The others are aliases. Matching ignores case, spaces, '_' and '-'.",+ )+ }+}++/// Extrude's operation: the above or `auto` (matched with `eq_ignore_ascii_case`, as the+/// handler does).+#[derive(Clone, Debug, PartialEq)]+pub struct ExtrudeOperation(pub String);++impl<'de> Deserialize<'de> for ExtrudeOperation {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let ok = |s: &str| s.eq_ignore_ascii_case("auto") || Operation::parse(s).is_some();+ string_matching(d, ok, "new, join, cut, intersect or auto", unknown_operation).map(ExtrudeOperation)+ }+}++impl JsonSchema for ExtrudeOperation {+ fn schema_name() -> Cow<'static, str> {+ "ExtrudeOperation".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ let mut values = vec!["auto"];+ values.extend(OPERATIONS);+ enum_schema(+ &values,+ "How the extrusion combines with existing bodies: auto (cut into a body, otherwise join; new in an empty component), new, join, cut or intersect. The others are aliases. Matching ignores case, spaces, '_' and '-' (only case for auto).",+ )+ }+}++const DIRECTIONS: [&str; 6] = ["positive", "negative", "symmetric", "one_side", "reverse", "flip"];++/// Extrude's direction, as `extent_param` reads it (lowercased, not trimmed).+#[derive(Clone, Debug, PartialEq)]+pub struct DirectionParam(pub String);++impl<'de> Deserialize<'de> for DirectionParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let ok = |s: &str| DIRECTIONS.contains(&s.to_ascii_lowercase().as_str());+ // The handler names the direction lowercased.+ let unknown = |s: &str| whole(format!("unknown direction `{}`", s.to_ascii_lowercase()));+ string_matching(d, ok, "positive, negative or symmetric", unknown).map(DirectionParam)+ }+}++impl JsonSchema for DirectionParam {+ fn schema_name() -> Cow<'static, str> {+ "Direction".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ enum_schema(+ &DIRECTIONS,+ "Which way to extrude: positive (the default), negative, or symmetric (the distance is the total thickness, split evenly around the start plane). one_side is an alias of positive; reverse and flip of negative. Matching ignores case.",+ )+ }+}++/// The `extent` keyword: only `through_all` (ignoring case) is meaningful.+#[derive(Clone, Debug, PartialEq)]+pub struct ExtentKeyword;++impl<'de> Deserialize<'de> for ExtentKeyword {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ match Value::deserialize(d)? {+ Value::String(s) if s.eq_ignore_ascii_case("through_all") => Ok(ExtentKeyword),+ _ => Err(D::Error::custom("must be through_all")),+ }+ }+}++impl JsonSchema for ExtentKeyword {+ fn schema_name() -> Cow<'static, str> {+ "ExtentKeyword".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ enum_schema(&["through_all"], "\"through_all\" (any case) is the same as through_all: true.")+ }+}++/// Extrude's distance convention, as `extent_param` reads it (serde, case-sensitive).+#[derive(Clone, Debug, PartialEq)]+pub struct ConventionParam(pub solidcraft_doc::ExtrudeConvention);++impl<'de> Deserialize<'de> for ConventionParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ serde_json::from_value(Value::deserialize(d)?).map(ConventionParam).map_err(|_| D::Error::custom("must be total_distance or legacy_per_side"))+ }+}++impl JsonSchema for ConventionParam {+ fn schema_name() -> Cow<'static, str> {+ "ExtrudeConvention".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ enum_schema(+ &["total_distance", "legacy_per_side"],+ "total_distance (the default): a symmetric distance is the total thickness. legacy_per_side keeps older designs' per-side meaning.",+ )+ }+}++/// A thin wall's side, as `ThinSide::parse` reads it.+#[derive(Clone, Debug, PartialEq)]+pub struct ThinSideParam(pub ThinSide);++impl<'de> Deserialize<'de> for ThinSideParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let s = string_matching(+ d,+ |s| ThinSide::parse(s).is_some(),+ "center, inside, outside or two_sides",+ |s| whole(format!("unknown side `{s}` (center, inside, outside or two_sides)")),+ )?;+ ThinSide::parse(&s).map(ThinSideParam).ok_or_else(|| D::Error::custom("must be one of center, inside, outside or two_sides"))+ }+}++impl JsonSchema for ThinSideParam {+ fn schema_name() -> Cow<'static, str> {+ "ThinSide".into()+ }+ fn json_schema(_: &mut SchemaGenerator) -> Schema {+ enum_schema(+ &["center", "inside", "outside", "two_sides", "centre", "centered", "centred", "symmetric", "side1", "side_1", "side2", "side_2", "both"],+ "Which side of the curves the wall lies on: center (the default), inside, outside or two_sides. The others are aliases. Matching ignores case and surrounding spaces, and reads ' ' and '-' as '_'.",+ )+ }+}++/// Which sketch profiles a feature uses. Accepted exactly when `features::profiles` accepts+/// it; kept as the raw value for the handler.+#[derive(Clone, Debug, PartialEq)]+pub struct ProfilesParam(pub Value);++impl<'de> Deserialize<'de> for ProfilesParam {+ fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {+ let v = Value::deserialize(d)?;+ match crate::cmd::feature_profiles(&json!({ "profiles": v }), "profiles") {+ Ok(_) => Ok(ProfilesParam(v)),+ // The helper's messages as they are, apart from two terse ones, which get the+ // contract's `must be` wording.+ Err(crate::EngineError::BadParams { msg, .. }) => Err(D::Error::custom(match msg.as_str() {+ "profile index" => "must be \"all\", an index or a list".to_string(),+ "too many profiles" => "must have at most 10000 items".to_string(),+ _ => whole(msg),+ })),+ Err(e) => Err(D::Error::custom(e.to_string())),+ }+ }+}++impl JsonSchema for ProfilesParam {+ fn schema_name() -> Cow<'static, str> {+ "Profiles".into()+ }+ fn json_schema(generator: &mut SchemaGenerator) -> Schema {+ let point = generator.subschema_for::<Point2>();+ let curves = json!({"type": "array", "items": {"type": "string"}, "minItems": 1});+ let named = json!({"anyOf": [{"type": "string"}, curves]});+ let list = |items: Value| json!({"type": "array", "minItems": 1, "maxItems": 10000, "items": items});+ // An index is what the helper reads as a u64.+ let index = json!({"type": "integer", "minimum": 0, "maximum": u64::MAX});+ let loops = json!({"type": "array", "minItems": 1, "items": {+ "type": "object", "properties": {"outer": {"type": "boolean"}, "curves": named}, "required": ["curves"]+ }});+ let associations = json!({+ "type": "array", "minItems": 1, "maxItems": 128, "uniqueItems": true,+ "items": {"type": "string", "minLength": 1, "maxLength": 512}+ });+ // A list is all indices, all points, or all curve selections, as the helper reads it;+ // the `not`s give its precedence (a list whose items all have `point` is points, an+ // item's `curves` wins over its `loops`; `type: whole_boundaries` wins over an+ // `offset_boundaries` key, which wins over `type: offset_boundaries`). Narrower than+ // the helper in one way: every curve id and every loop must be well formed, where the+ // helper drops non-text ids and reads only the outer loop.+ let curve_object = json!({"type": "object", "properties": {"curves": named}, "required": ["curves"]});+ let loops_object = json!({+ "type": "object", "properties": {"loops": loops}, "required": ["loops"], "not": {"required": ["curves"]}+ });+ let curve_list = json!({+ "type": "array", "minItems": 1, "maxItems": 10000, "items": {"anyOf": [curves, curve_object, loops_object]},+ "not": {"items": {"type": "object", "required": ["point"]}}+ });+ json_schema!({+ "description": "Which sketch profiles to use: \"all\" (the default, any case), an index, or a list of indices, of {\"point\": [x, y]} inside a profile, or of curve selections (a list of curve ids, {\"curves\": [ids]} or {\"loops\": [...]}). Picks by index or point are stored by the curves around the profile.",+ "anyOf": [+ {"type": "string", "pattern": "^[Aa][Ll][Ll]$"},+ index.clone(),+ list(index),+ list(json!({"type": "object", "properties": {"point": point}, "required": ["point"]})),+ curve_list,+ {+ "description": "Internal selections written by the app.",+ "anyOf": [+ {"type": "object", "properties": {"type": {"enum": ["whole_boundaries"]}}, "required": ["type"]},+ {+ "type": "object", "properties": {"offset_boundaries": associations}, "required": ["offset_boundaries"],+ "not": {"properties": {"type": {"enum": ["whole_boundaries"]}}, "required": ["type"]}+ },+ {+ "type": "object", "properties": {"type": {"enum": ["offset_boundaries"]}, "associations": associations},+ "required": ["type", "associations"], "not": {"required": ["offset_boundaries"]}+ }+ ]+ }+ ]+ })+ }+}diff --git a/crates/mcp/src/server.rs b/crates/mcp/src/server.rsindex b3091ef31e..584f5b4f9b 100644--- a/crates/mcp/src/server.rs+++ b/crates/mcp/src/server.rs@@ -31,7 +31,7 @@ and degrees in expressions (internally radians), Z is up. Model like this: `sketand dimension (`sketch.dimension {entities, value}`; values may name parameters), `sketch.finish`, then features \(`solid.extrude {distance, operation?: new|join|cut|intersect}`, `solid.revolve`, `solid.fillet {edges: [[x,y,z] point on \edge], radius}`, `solid.chamfer`, patterns, mirror, primitives). Use `batch` for several steps at once, \-`list_commands` for ids and parameter docs, `inspect_design` / `measure` to verify, `body_topology` to find edge points, \+`list_commands` for ids and parameter docs, `describe_command` for a command's schemas, `inspect_design` / `measure` to verify, `body_topology` to find edge points, \`set_parameter` to drive the design and `screenshot` to look at it.";pub struct Server {diff --git a/crates/mcp/src/tests.rs b/crates/mcp/src/tests.rsindex e60ef2aaef..98ea3b515b 100644--- a/crates/mcp/src/tests.rs+++ b/crates/mcp/src/tests.rs@@ -88,6 +88,7 @@ fn handshake_and_tools_list() {let names: Vec<&str> = tools["result"]["tools"].as_array().unwrap().iter().map(|t| t["name"].as_str().unwrap()).collect();for want in ["list_commands",+ "describe_command","execute","batch","inspect_design",@@ -1479,7 +1480,7 @@ fn tool_annotations_tell_the_whole_truth() {for name in ["execute", "batch", "save", "export", "open", "screenshot"] {assert_eq!(hints(name), (false, true, true), "{name}");}- for name in ["list_commands", "inspect_design", "measure", "body_topology", "crash_reports"] {+ for name in ["list_commands", "describe_command", "inspect_design", "measure", "body_topology", "crash_reports"] {assert_eq!(hints(name), (true, false, false), "{name}");}assert_eq!(hints("new_design"), (false, true, false));@@ -1547,3 +1548,24 @@ fn batch_reports_timings_and_profile() {assert_eq!(body["timings"][0]["command"], "a.one", "{body}");assert!(body["timings"][0].get("profile").is_none(), "{body}");}++/// `describe_command` serves a converted command's schemas, and a headless session set to strict+/// refuses a misspelt key through `execute` without touching the design.+#[test]+fn describe_command_and_strict_parameter_checking() {+ let mut s = server();+ let d = tool(&mut s, "describe_command", json!({"id": "solid.box"}));+ assert!(d["input"]["properties"].get("operation").is_some(), "{d}");+ assert!(d["output"]["properties"].get("created_bodies").is_some(), "{d}");++ let mut headless = Headless::default();+ headless.session.param_check = solidcraft_engine::schema::ParamCheck::Strict;+ let mut s = Server::new(Box::new(headless));+ call(&mut s, 1, "initialize", json!({"protocolVersion": PROTOCOL_VERSION, "capabilities": {}, "clientInfo": {"name": "t", "version": "1"}}));+ let r = raw_tool(&mut s, "execute", json!({"command": "solid.box", "params": {"length": 5, "width": 5, "height": 5, "operaton": "cut"}}));+ assert_eq!(r["result"]["isError"], json!(true), "{r}");+ let text = r["result"]["content"][0]["text"].as_str().unwrap_or_default();+ assert!(text.contains("unknown key `operaton`; did you mean `operation`?"), "{text}");+ let m = tool(&mut s, "measure", json!({}));+ assert_eq!(m["body_count"], json!(0), "{m}");+}diff --git a/crates/mcp/src/tools.rs b/crates/mcp/src/tools.rsindex a5d4a9330d..750a43c1e0 100644--- a/crates/mcp/src/tools.rs+++ b/crates/mcp/src/tools.rs@@ -72,6 +72,14 @@ pub fn tool_definitions() -> Vec<Value> {obj(json!({"filter": string("Substring to match, e.g. \"sketch\", \"fillet\", \"pattern\"")}), &[]),Effect::ReadOnly,),+ tool(+ "describe_command",+ "Describe a command",+ "One command's parameter docs and, for commands with a typed contract (solid.box, solid.extrude and engine.describe so far), the \+ JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); null for the others.",+ obj(json!({"id": string("Command id, e.g. \"solid.extrude\"")}), &["id"]),+ Effect::ReadOnly,+ ),tool("execute","Execute a command",@@ -388,6 +396,10 @@ fn dispatch(b: &mut dyn Backend, name: &str, a: &Map<String, Value>) -> Result<V};Ok(Value::Array(all.as_array().map(|v| v.iter().filter(|c| hit(c)).cloned().collect()).unwrap_or_default()))}+ "describe_command" => {+ let id = str_arg(a, "id").ok_or("`id` is required")?;+ exec(b, "engine.describe", json!({"command": id}))+ }"execute" => {let id = str_arg(a, "command").ok_or("`command` is required")?;let v = exec(b, id, a.get("params").cloned().filter(Value::is_object).unwrap_or(json!({})))?;diff --git a/crates/ui-egui/src/agent_chat/gate.rs b/crates/ui-egui/src/agent_chat/gate.rsindex 2eb4141c51..ecf49851a4 100644--- a/crates/ui-egui/src/agent_chat/gate.rs+++ b/crates/ui-egui/src/agent_chat/gate.rs@@ -64,7 +64,7 @@ fn reads_only(id: &str) -> bool {|| id.starts_with("model.")|| id.ends_with(".inspect")|| id.ends_with(".list")- || matches!(id, "edit.checkpoint" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers")+ || matches!(id, "edit.checkpoint" | "render.status" | "render.backends" | "render.settings.get" | "file.slicers" | "engine.describe")}/// Commands that read or write a file by their nature: any string they are given in a path@@ -235,6 +235,7 @@ mod tests {assert_eq!(exec("sketch.inspect", json!({"sketch": 1})), Verdict::Run { change: false });assert_eq!(exec("inspect.measure", json!({})), Verdict::Run { change: false });assert_eq!(request("document.inspect", &json!({}), 0), Verdict::Run { change: false });+ assert_eq!(exec("engine.describe", json!({"command": "solid.box"})), Verdict::Run { change: false });}#[test]diff --git a/docs/mcp.md b/docs/mcp.mdindex 7b15492b28..71c033616c 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -47,6 +47,16 @@ A `batch` that could not be sent says the app is not running, so it is safe to sstdout carries only protocol messages; errors go to stderr. Bridged screenshots are written to atemporary file by the app and read back by the server, so both must run on the same machine.+### Parameter checking++Commands with a typed parameter contract (`solid.box`, `solid.extrude` and `engine.describe`+so far; `describe_command` shows a command's schemas) can be checked as they are called.+`--param-check off|warn|strict` sets the level for a headless session, including a script or+recipe given with `--in`; the default is `off`, which changes nothing. `warn` runs the call and+adds `param_warnings` to its result, such as ``unknown key `operaton`; did you mean+`operation`?`` (a starting script's warnings go to stderr). `strict` refuses the call, and the+design is left as it was. Calls bridged to the app are not checked yet.+### Which files the agent can reachTool calls read, write and delete files only inside the server's folders:@@ -99,11 +109,11 @@ file dialogs are never limited.### Tool annotationsEach tool says what it may do, for clients that ask before running tools (or auto-approve on-these hints). `list_commands`, `inspect_design`, `measure`, `body_topology` and `crash_reports`-are read-only. `set_parameter`, `undo` and `redo` change the design undoably. `new_design`-replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and `screenshot` (whose-`path` writes a file) can read, write, overwrite or delete files: they are not read-only,-`destructiveHint` and `openWorldHint` are true.+these hints). `list_commands`, `describe_command`, `inspect_design`, `measure`, `body_topology`+and `crash_reports` are read-only. `set_parameter`, `undo` and `redo` change the design undoably.+`new_design` replaces it (destructive). `execute`, `batch`, `open`, `save`, `export` and+`screenshot` (whose `path` writes a file) can read, write, overwrite or delete files: they are+not read-only, `destructiveHint` and `openWorldHint` are true.### Client configuration@@ -143,6 +153,7 @@ They cover the workflow, the command shapes, how to verify with `measure`, and t| Tool | Arguments | What it does ||---|---|---|| `list_commands` | `filter?` | The command catalog: id, label, tab/panel, shortcut, parameter docs, enabled now. `filter` matches id, label, tab and panel. |+| `describe_command` | `id` | One command's parameter docs (`params`) and, for commands with a typed contract (`solid.box`, `solid.extrude` and `engine.describe` so far), the JSON Schemas (2020-12) of its parameters (`input`) and of a successful result (`output`); `null` for the others. The same as `execute` `engine.describe {command}`. || `execute` | `command`, `params?`, `verbose?` (default true) | Run any command with JSON parameters (`list_commands` shows them). Failures leave the design unchanged. A feature command replies with the feature (`feature`, `name`), every body (`bodies`) and the bodies it created, changed and removed (`created_bodies`, `changed_bodies`, `removed_bodies`). `verbose: false` uses the same compact reply as `batch`. || `batch` | `commands: [{command, params}]`, `rollback?` (default true), `verbose?` (default true), `timings?`, `profile?` (default false) | Run steps in order, stop at the first error and undo the completed steps. The reply names the failing step (`failed.index`, `failed.command`, `failed.error`) and every result before it. `verbose: false` keeps the reply small in large designs: feature steps leave out the full body list (`created_bodies`, `changed_bodies`, `removed_bodies` stay) and sketch steps the ids they repeat outside `created`. Bridged to an app that has `engine.batch`, the whole batch is one control request (one frame of the app). Older apps, and apps showing the agent cursor, get the steps one by one. `timings: true` adds `timings: [{index, command, ms}]` for every step run, the failing one included, and `total_ms`. `profile: true` also adds each step's `profile: {boolean_ms, tessellate_ms, other_ms}`, its time in kernel booleans, in tessellation and the rest. Steps are timed where they run: in the app when bridged. An app without `engine.batch` is timed step by step, without `profile`. || `inspect_design` | `measure?` (default true), `sketches?` (default true) | Design properties (`metadata`: project, author… and other tools' keys; set them with `execute` `document.metadata.set`), parameters, timeline (type, suppressed, rolled back, error, warning, timing), bodies (volume, area, centre of mass, bbox, face/edge/vertex counts, visible; `removed_later: true` while a sketch is being edited on a rolled-back timeline and a later feature deletes the body, which is then not shown), sketches (curves, points, constraints, profiles, DOF, solve status, visible), selection, undo depth. Hide helper sketches, bodies or construction planes with `execute` `browser.visibility` (`{items, visible}` or `{folder, visible}`), and joint glyphs with `{joints: [id or name], visible}` or `{folder: "joints", visible}` (a hidden joint still constrains and drives; `joint.list` reports each joint's `visible`). |diff --git a/scripts/param_audit.py b/scripts/param_audit.pynew file mode 100644index 0000000000..1140e16036--- /dev/null+++ b/scripts/param_audit.py@@ -0,0 +1,88 @@+#!/usr/bin/env python3+"""Summarise a parameter-contract audit: the calls that break a command's contract, by issue.++Usage: param_audit.py AUDIT_DIR [OUT_JSON]++AUDIT_DIR is the directory `SOLIDCRAFT_PARAM_AUDIT` named for a test run built with the engine's+`param-audit` feature (see crates/engine/src/schema/record.rs). Each process writes one+audit-<pid>.jsonl, repeating a signature's line as its count grows, so this keeps the highest+count per signature in each file and adds the files up.++The report has three parts:+ SUCCEEDS TODAY calls that work now and that strict would refuse: a form the contract is+ missing (fix the contract) or a mistake the handler ignores (fix the caller)+ ALREADY FAILS calls the handler rejects anyway+ REFUSED calls strict refused (tests that run with strict on)++OUT_JSON, when given, receives every signature with its summed count.+"""+import json+import sys+from collections import Counter, defaultdict+from pathlib import Path+++def load(audit_dir):+ signatures = {}+ malformed = []+ files = sorted(audit_dir.glob("audit-*.jsonl"))+ for f in files:+ per_file = {}+ for n, line in enumerate(f.read_text(encoding="utf-8", errors="replace").splitlines(), 1):+ if not line.strip():+ continue+ try:+ r = json.loads(line)+ key = json.dumps([r["command"], r["issues"], r["outcome"], r["source"]])+ except (json.JSONDecodeError, KeyError) as e:+ malformed.append(f"{f.name}:{n}: {e}")+ continue+ if key not in per_file or r["count"] > per_file[key]["count"]:+ per_file[key] = r+ for key, r in per_file.items():+ if key in signatures:+ signatures[key] = {**signatures[key], "count": signatures[key]["count"] + r["count"]}+ else:+ signatures[key] = dict(r)+ return files, signatures, malformed+++def by_issue(records):+ counts = Counter()+ examples = defaultdict(list)+ for r in records:+ for issue in r["issues"]:+ counts[(r["command"], issue)] += r["count"]+ if len(examples[(r["command"], issue)]) < 3:+ examples[(r["command"], issue)].append(f"{r['source']}: {r['sample_params'][:300]}")+ return counts, examples+++def main():+ if len(sys.argv) not in (2, 3):+ sys.exit(__doc__.split("\n\n")[1])+ files, signatures, malformed = load(Path(sys.argv[1]))+ records = list(signatures.values())+ parts = [+ ("SUCCEEDS TODAY, STRICT WOULD REFUSE", [r for r in records if r["outcome"] == "ok"], True),+ ("ALREADY FAILS TODAY", [r for r in records if r["outcome"] not in ("ok", "refused")], False),+ ("REFUSED BY STRICT", [r for r in records if r["outcome"] == "refused"], False),+ ]+ print(f"files: {len(files)} signatures: {len(signatures)} malformed lines: {len(malformed)}")+ for m in malformed[:10]:+ print(" malformed:", m)+ for label, part, show_examples in parts:+ counts, examples = by_issue(part)+ print(f"\n== {label}: {len(part)} signatures, at least {sum(r['count'] for r in part)} calls")+ for (command, issue), n in counts.most_common():+ print(f" {n:>7} {command:14} {issue}")+ if show_examples:+ for e in examples[(command, issue)]:+ print(f" e.g. {e}")+ if len(sys.argv) == 3:+ out = {"signatures": records, "malformed": malformed}+ Path(sys.argv[2]).write_text(json.dumps(out, indent=1), encoding="utf-8")+++if __name__ == "__main__":+ main()