SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
//! Design properties (#1015): `document.metadata` reads the design's `metadata` object, and
//! `document.metadata.set` and `document.metadata.remove` change it, each in one undo step. The
//! keys SolidCraft reads, and the checks a change gets, are `solidcraft_doc::metadata`'s
//! (`KEYS`, the rows the design takes); keys other tools wrote are kept as they are. The UI's Design
//! Properties dialog, scripts and MCP agents all go through these commands. A change evaluates
//! nothing: properties are no geometry.
use serde_json::{Map, Value, json};
use solidcraft_doc::metadata::{self, BOM_TYPE, MAX_KEYS, Owner};
use super::CommandSpec;
use crate::params::{bad, str_};
use crate::schema::metadata::{MetadataParams, MetadataRemoveParams, MetadataRemoveResult, MetadataResult, MetadataSetParams, MetadataSetResult};
use crate::schema::{TypedContract, output_schema_for};
use crate::{Result, Session};
const READ_CONTRACT: TypedContract<MetadataParams> = TypedContract::new();
const SET_CONTRACT: TypedContract<MetadataSetParams> = TypedContract::new();
const REMOVE_CONTRACT: TypedContract<MetadataRemoveParams> = TypedContract::new();
pub static COMMANDS: &[CommandSpec] = &[
CommandSpec::new("document.metadata", "Design Properties", crate::checked!("document.metadata", read))
.icon("settings")
.noundo()
.doc_only()
.contract(&READ_CONTRACT)
.output(output_schema_for::<MetadataResult>)
.params(
"→ metadata: the design's metadata object as saved (other tools' keys too); properties: each of SolidCraft's design \
properties (project, part number, revision…), its text or null (absent, or not text)",
),
CommandSpec::new("document.metadata.set", "Change Design Properties", crate::checked!("document.metadata.set", set))
.icon("settings")
.doc_only()
.contract(&SET_CONTRACT)
.output(output_schema_for::<MetadataSetResult>)
.params(
"key and value, or values: {key: value, …} (all or nothing, one undo step). SolidCraft's keys, the ones document.metadata's \
properties lists, take text (\"\" or null removes); another tool's data goes under its reverse-DNS key such as \
com.example.tool (an object; null removes) → metadata, changed: [keys]",
),
CommandSpec::new("document.metadata.remove", "Remove Design Property", crate::checked!("document.metadata.remove", remove))
.icon("delete")
.doc_only()
.contract(&REMOVE_CONTRACT)
.output(output_schema_for::<MetadataRemoveResult>)
.params("key, or keys: [keys] (any key, also one another tool wrote) → metadata, removed: [keys that were there]"),
];
/// A reply built from its schema's type, so the two can't drift apart.
fn reply(cmd: &str, r: impl serde::Serialize) -> Result<Value> {
serde_json::to_value(r).map_err(|e| bad(cmd, e.to_string()))
}
fn read(s: &mut Session, _: &Value) -> Result<Value> {
let m = &s.doc.metadata;
let properties: Map<String, Value> = metadata::keys(Owner::Design).map(|k| (k.name.to_string(), json!(m.text(k.name)))).collect();
reply("document.metadata", MetadataResult { metadata: m.0.clone(), properties })
}
fn set(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "document.metadata.set";
let entries: Vec<(&str, &Value)> = match (p.get("values"), p.get("key")) {
(Some(Value::Object(values)), None) if values.len() <= MAX_KEYS => values.iter().map(|(k, v)| (k.as_str(), v)).collect(),
(Some(Value::Object(_)), None) => return Err(bad(cmd, format!("`values` can hold at most {MAX_KEYS} keys"))),
(None, Some(_)) => {
let key = str_(p, "key").ok_or_else(|| bad(cmd, "`key` must be text"))?;
let value = p.get("value").ok_or_else(|| bad(cmd, "`value` is required (null removes the key)"))?;
vec![(key, value)]
}
_ => return Err(bad(cmd, "give `key` and `value`, or `values`: {key: value, …}")),
};
let mut next = s.doc.metadata.clone();
let mut changed = Vec::new();
for (key, value) in entries {
if key == BOM_TYPE {
return Err(bad(cmd, "`bom_type` is a component's part property: set it with component.metadata.set"));
}
if next.set(Owner::Design, key, value.clone()).map_err(|e| bad(cmd, e.to_string()))? {
changed.push(key.to_string());
}
}
// Only a real change touches the design (an undo step, unsaved changes).
if next != s.doc.metadata {
s.doc_mut().metadata = next;
}
reply(cmd, MetadataSetResult { metadata: s.doc.metadata.0.clone(), changed, param_warnings: Vec::new() })
}
fn remove(s: &mut Session, p: &Value) -> Result<Value> {
let cmd = "document.metadata.remove";
let keys: Vec<&str> = match (p.get("keys"), p.get("key")) {
(Some(Value::Array(keys)), None) if keys.len() <= MAX_KEYS => {
keys.iter().map(Value::as_str).collect::<Option<_>>().ok_or_else(|| bad(cmd, "`keys` must be a list of keys"))?
}
(None, Some(_)) => vec![str_(p, "key").ok_or_else(|| bad(cmd, "`key` must be text"))?],
_ => return Err(bad(cmd, format!("give `key`, or `keys`: a list of at most {MAX_KEYS} keys"))),
};
let mut removed: Vec<&str> = Vec::new();
for k in keys {
if s.doc.metadata.get(k).is_some() && !removed.contains(&k) {
removed.push(k);
}
}
if !removed.is_empty() {
let m = &mut s.doc_mut().metadata;
for k in &removed {
m.remove(k);
}
}
let removed = removed.into_iter().map(str::to_string).collect();
reply(cmd, MetadataRemoveResult { metadata: s.doc.metadata.0.clone(), removed, param_warnings: Vec::new() })
}
#[cfg(test)]
mod tests {
use super::*;
fn run(s: &mut Session, id: &str, p: Value) -> Value {
match s.execute(id, &p) {
Ok(v) => v,
Err(e) => panic!("{id} {p}: {e}"),
}
}
/// A folder of its own for one test's files.
fn scratch(name: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("solidcraft-metadata-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
#[test]
fn properties_set_read_and_remove_in_one_undo_step_each() {
let mut s = Session::default();
run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10}));
s.mark_saved();
let undo = s.undo.len();
let r = run(
&mut s,
"document.metadata.set",
json!({"values": {"author": "Jane Doe", "part_number": "ACME-1042", "com.acme.shop": {"shop_id": 88123}}}),
);
assert_eq!(r["changed"], json!(["author", "com.acme.shop", "part_number"]));
assert_eq!(s.undo.len(), undo + 1, "several keys, one undo step");
assert!(s.is_dirty());
let r = run(&mut s, "document.metadata", json!({}));
assert_eq!(r["properties"]["author"], "Jane Doe");
assert_eq!(r["properties"]["project"], Value::Null);
assert_eq!(r["metadata"]["com.acme.shop"]["shop_id"], 88123);
// Setting what is already there changes nothing: no undo step.
let r = run(&mut s, "document.metadata.set", json!({"key": "author", "value": "Jane Doe"}));
assert_eq!(r["changed"], json!([]));
assert_eq!(s.undo.len(), undo + 1);
let r = run(&mut s, "document.metadata.remove", json!({"keys": ["author", "author", "not.there"]}));
assert_eq!(r["removed"], json!(["author"]));
assert_eq!(s.doc.metadata.author(), None);
run(&mut s, "edit.undo", json!({}));
assert_eq!(s.doc.metadata.author(), Some("Jane Doe"));
run(&mut s, "edit.undo", json!({}));
assert!(s.doc.metadata.is_empty());
assert!(!s.is_dirty(), "undone back to the saved design");
run(&mut s, "edit.redo", json!({}));
assert_eq!(s.doc.metadata.part_number(), Some("ACME-1042"));
}
#[test]
fn a_refused_change_leaves_the_design_as_it_was() {
let mut s = Session::default();
run(&mut s, "document.metadata.set", json!({"key": "author", "value": "Jane"}));
let undo = s.undo.len();
for p in [
json!({"values": {"project": "P", "author": 42}}),
json!({"values": {"project": "P", "colour": "red"}}),
json!({"values": {"project": "P", "com.acme": "not an object"}}),
json!({"key": "author"}),
json!({"key": 7, "value": "x"}),
json!({"key": "author", "value": "x", "values": {}}),
json!({"values": [1, 2]}),
json!({}),
] {
assert!(s.execute("document.metadata.set", &p).is_err(), "{p}");
}
for p in [json!({}), json!({"keys": "author"}), json!({"keys": [1]}), json!({"key": ["author"]})] {
assert!(s.execute("document.metadata.remove", &p).is_err(), "{p}");
}
assert_eq!(s.undo.len(), undo);
assert_eq!(s.doc.metadata.project(), None, "all or nothing");
assert_eq!(s.doc.metadata.author(), Some("Jane"));
}
#[test]
fn other_tools_keys_and_odd_values_survive_open_edit_and_save() {
let dir = scratch("roundtrip");
// A design another tool added metadata to by hand: a namespaced object with every kind of
// JSON value, a well-known key of the wrong type, a key a newer SolidCraft might read, and
// numbers no feature input could hold.
let foreign = json!({
"author": 42,
"revision": "B",
"com.acme.description": {"shop_id": 88123, "nested": {"list": [1, 2.5, null, true, "x", {"deep": []}]}, "big": 1.5e300},
"org.printfarm": {"slicer_profile": "PETG-0.2"},
"future_key": ["kept"],
});
let mut design: Value = serde_json::from_str(&solidcraft_doc::Document::new("Foreign").to_json()).unwrap();
design["metadata"] = foreign.clone();
let plain = dir.join("foreign.json");
std::fs::write(&plain, serde_json::to_string_pretty(&design).unwrap()).unwrap();
let mut s = Session::default();
run(&mut s, "doc.open", json!({"path": plain}));
assert_eq!(serde_json::to_value(&s.doc.metadata).unwrap(), foreign, "opened as it was");
assert_eq!(s.doc.metadata.author(), None, "a number is not an author");
let r = run(&mut s, "document.metadata", json!({}));
assert_eq!(r["properties"]["author"], Value::Null);
assert_eq!(r["properties"]["revision"], "B");
run(&mut s, "document.metadata.set", json!({"key": "project", "value": "ACME enclosures"}));
let mut expected = foreign.clone();
expected["project"] = json!("ACME enclosures");
for (file, format) in [("edited.json", "json"), ("edited.solidcraft", "container")] {
let path = dir.join(file);
run(&mut s, "file.save_as", json!({"path": path, "format": format}));
let mut reopened = Session::default();
run(&mut reopened, "doc.open", json!({"path": path}));
assert_eq!(serde_json::to_value(&reopened.doc.metadata).unwrap(), expected, "{format}");
}
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_design_without_properties_saves_as_before() {
let mut s = Session::default();
run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10}));
let before = solidcraft_io::write_design(&s.doc);
run(&mut s, "document.metadata.set", json!({"key": "author", "value": "Jane"}));
run(&mut s, "document.metadata.remove", json!({"key": "author"}));
assert_eq!(solidcraft_io::write_design(&s.doc), before, "byte for byte");
assert!(!String::from_utf8_lossy(&before).contains("\"metadata\""));
}
#[test]
fn exports_carry_the_properties_and_never_other_tools_keys() {
// `file.export` hands the design's properties to the writers; the mapping itself is
// tested in solidcraft-io.
let dir = scratch("export");
let mut s = Session::default();
run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10}));
run(
&mut s,
"document.metadata.set",
json!({"values": {
"project": "ACME enclosures", "author": "Jane Doe", "organization": "ACME", "license": "CC-BY-4.0",
"description": "Vented case\nfor a Pi", "part_number": "ACME-1042", "com.acme.secret": {"token": "SECRET-VALUE"},
}}),
);
let text = |s: &mut Session, name: &str| {
let path = dir.join(name);
run(s, "file.export", json!({"path": path}));
std::fs::read(&path).unwrap()
};
let step = String::from_utf8(text(&mut s, "part.step")).unwrap();
assert!(step.contains("FILE_DESCRIPTION(('Vented case for a Pi'),'2;1');"), "{}", &step[..400]);
assert!(step.contains("('Jane Doe'),('ACME')"), "{}", &step[..400]);
let iges = String::from_utf8(text(&mut s, "part.igs")).unwrap();
assert!(iges.contains("8HJane Doe") && iges.contains("4HACME"), "{}", &iges[..600]);
// 3MF model metadata is checked where it is written (solidcraft-io); here: it exports.
assert!(!text(&mut s, "part.3mf").is_empty());
for out in [step.as_bytes(), iges.as_bytes()] {
let found = |needle: &str| out.windows(needle.len()).any(|w| w == needle.as_bytes());
assert!(!found("SECRET-VALUE") && !found("com.acme"), "another tool's data is never exported");
}
// An assembly's STEP gets the same header.
run(&mut s, "component.create", json!({}));
assert!(!s.doc.occurrences.is_empty());
let assembly = String::from_utf8(text(&mut s, "assembly.step")).unwrap();
assert!(assembly.contains("('Jane Doe'),('ACME')"));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn changing_design_properties_does_not_evaluate_the_model_again() {
let mut s = Session::default();
run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10}));
s.evaluations = 0;
let revision = s.revision;
run(&mut s, "document.metadata.set", json!({"values": {"author": "Jane", "com.acme.tool": {"id": 7}}}));
run(&mut s, "document.metadata.remove", json!({"key": "com.acme.tool"}));
run(&mut s, "edit.undo", json!({}));
run(&mut s, "edit.redo", json!({}));
assert_eq!(s.evaluations, 0, "design properties change no geometry");
assert!(s.revision > revision, "the views still see each change");
assert_eq!(s.model.state().bodies.len(), 1, "the model is kept as it was");
assert_eq!(s.doc.metadata.author(), Some("Jane"));
// Anything else still evaluates.
run(&mut s, "solid.box", json!({"length": 5, "width": 5, "height": 5}));
assert!(s.evaluations > 0);
}
#[test]
fn opening_a_design_that_differs_only_in_its_properties_refreshes_it() {
// Two revisions of one assembly, B held on A by a rigid joint. The open session's B was
// moved off the joint and never solved since; the file is the same design with another
// author. Opening it is no property edit: the new session's joints are solved.
let dir = scratch("revision");
let mut s = Session::default();
for (name, x) in [("A", 0), ("B", 20)] {
run(&mut s, "component.activate", json!({"component": "root"}));
run(&mut s, "component.create", json!({"name": name}));
run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10, "corner": [x, 0, 0]}));
}
let placement =
|s: &Session, name: &str| s.doc.find_component(name).and_then(|c| s.doc.occurrence_of(c)).map(|o| (o.id, o.transform)).unwrap();
let a = placement(&s, "A").0;
run(&mut s, "occurrence.ground", json!({"occurrence": a, "grounded": true}));
run(&mut s, "joint.create", json!({"type": "rigid", "a": {"face": [5, 5, 10]}, "b": {"face": [25, 5, 0]}}));
let (b, solved) = placement(&s, "B");
let mut unsolved = (*s.doc).clone();
unsolved.name = "Bracket".into();
if let Some(o) = unsolved.occurrences.iter_mut().find(|o| o.id == b) {
o.transform[3][0] += 3.0;
}
let mut s = Session::new(unsolved.clone());
let mut revision_c = unsolved;
revision_c.metadata.set(Owner::Design, "author", json!("Jane")).unwrap();
let path = dir.join("bracket-rev-c.json");
std::fs::write(&path, revision_c.to_json()).unwrap();
let (read, _) = solidcraft_io::read_design_file(path.to_str().unwrap(), None::<fn(solidcraft_io::DesignPreview)>).unwrap();
assert!(read.differs_only_in_part_properties(&s.doc), "the two revisions differ only in their properties");
run(&mut s, "doc.open", json!({"path": path}));
assert_eq!(s.doc.metadata.author(), Some("Jane"));
let opened = s.doc.occurrences.iter().find(|o| o.id == b).map(|o| o.transform).unwrap();
let off = opened.iter().flatten().zip(solved.iter().flatten()).map(|(p, q)| (p - q).abs()).fold(0.0, f64::max);
assert!(off < 1e-6, "the opened design's joint is solved: B is {off} mm off it");
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn every_key_the_design_took_before_is_still_taken() {
let mut s = Session::default();
let keys = ["project", "part_number", "revision", "author", "organization", "description", "license"];
let values: Map<String, Value> = keys.iter().map(|k| (k.to_string(), json!(format!("{k} text")))).collect();
let r = run(&mut s, "document.metadata.set", json!({ "values": values }));
assert_eq!(r["changed"].as_array().map(Vec::len), Some(keys.len()), "{r}");
let properties = run(&mut s, "document.metadata", json!({}))["properties"].clone();
for k in keys {
assert_eq!(properties[k], format!("{k} text"), "{k}");
}
assert_eq!(properties.as_object().map(Map::len), Some(keys.len()), "{properties}");
let refused = s.execute("document.metadata.set", &json!({"key": "colour", "value": "red"})).unwrap_err().to_string();
assert!(refused.contains("`colour` is not a design property: SolidCraft's are project, part_number,"), "{refused}");
}
#[test]
fn inspect_lists_the_metadata() {
let mut s = Session::default();
assert_eq!(run(&mut s, "document.inspect", json!({}))["metadata"], json!({}));
run(&mut s, "document.metadata.set", json!({"key": "revision", "value": "C"}));
assert_eq!(run(&mut s, "document.inspect", json!({}))["metadata"], json!({"revision": "C"}));
}
}