Skip to content

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

16.5 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/clipboard.rs` and `cmd/script.rs`:
//! `timeline.copy`, `timeline.paste`, `timeline.add` and `timeline.export_script` (#12502).
//!
//! The handlers read their parameters from the raw JSON, so each key here reads as its handler
//! reads it and fails with the handler's message; where a reader is shared with the handler
//! (`copy_keys`, `component_path_form`, `step_params`) the type calls it. Whether a feature, a
//! component or a file exists stays the handler's to check. A key the handler refuses when it is
//! left out (`features`, `feature`) is optional in the type and required in the schema, so that the
//! handler's message, not the check's "is required", is what a caller sees. A call with several
//! problems may get a different one first in strict than with the check off (the check goes key by
//! key, the handlers in their own order).

use std::borrow::Cow;

use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Map, Value, json};
use solidcore_record::Vec3;

use super::check::whole;
use super::component_link::ComponentRef;
use super::motion::require;
use super::types::not_blank_pattern;
use crate::EngineError;
use crate::params;

/// The most features one `timeline.copy` lists, as the handler reads them.
const MAX_COPY: usize = 1000;
/// The most occurrence ids in a `component_path`, as the handler reads them.
const MAX_PATH: usize = 64;

/// The message of a handler's refusal, to pass on as it is.
fn handler_message(e: EngineError) -> String {
    match e {
        EngineError::BadParams { msg, .. } => whole(msg),
        other => whole(other),
    }
}

// ---- timeline.copy ----

/// The features `timeline.copy` lists: one name, or a list of names and ids, in any mix.
#[derive(Clone, Debug, PartialEq)]
pub struct FeatureKeys(pub Vec<Value>);

impl<'de> Deserialize<'de> for FeatureKeys {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let wrapped = json!({ "features": Value::deserialize(d)? });
        crate::cmd::copy_keys(&wrapped).map(|keys| FeatureKeys(keys.to_vec())).map_err(|e| D::Error::custom(handler_message(e)))
    }
}

impl JsonSchema for FeatureKeys {
    fn schema_name() -> Cow<'static, str> {
        "FeatureKeys".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        let key = json!({"anyOf": [{"type": "string"}, {"type": "integer", "minimum": 0}]});
        json_schema!({
            "description": "Features by name or id: one name, or a list of names and ids in any mix.",
            "anyOf": [
                {"type": "string"},
                {"type": "array", "items": key, "minItems": 1, "maxItems": MAX_COPY}
            ]
        })
    }
}

/// Copy features to the session's clipboard, and a snapshot of them for pasting into another
/// design. The features stay where they are; the clipboard replaces what was copied before. Not an
/// undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = features_required)]
pub struct CopyParams {
    // Optional in the type and required in the schema (`features_required`).
    /// The features to copy, by name or id: one name, or 1 to 1000 names and ids. Pasted in
    /// timeline order whatever the order given.
    #[serde(default, deserialize_with = "features", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "FeatureKeys")]
    pub features: Option<FeatureKeys>,
}

/// `features`, with the handler's message for anything else, `null` and an empty list included.
fn features<'de, D: Deserializer<'de>>(d: D) -> Result<Option<FeatureKeys>, D::Error> {
    FeatureKeys::deserialize(d).map(Some)
}

fn features_required(schema: &mut Schema) {
    require(schema, "features");
}

/// What `timeline.copy` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CopyResult {
    /// The names of the features copied, in timeline order.
    pub copied: Vec<String>,
    /// 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>,
}

// ---- timeline.paste ----

/// A `translate` as `timeline.paste` reads it: `[x, y, z]` or `{x, y, z}` of numbers in mm, each
/// under 1e9 in size.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct PasteTranslation(pub Vec3);

impl<'de> Deserialize<'de> for PasteTranslation {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        params::vec3(&Value::deserialize(d)?).map(PasteTranslation).ok_or_else(|| D::Error::custom(whole("`translate` must be [x, y, z]")))
    }
}

impl JsonSchema for PasteTranslation {
    fn schema_name() -> Cow<'static, str> {
        "PasteTranslation".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        let c = json!({"type": "number", "exclusiveMinimum": -1e9, "exclusiveMaximum": 1e9});
        json_schema!({
            "description": "A distance in mm, as [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"]}
            ]
        })
    }
}

/// A `component_path` as `timeline.paste` reads it: 0 to 64 occurrence ids.
#[derive(Clone, Debug, PartialEq)]
pub struct PastePath(pub Vec<u64>);

impl<'de> Deserialize<'de> for PastePath {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        crate::cmd::component_path_form(&Value::deserialize(d)?)
            .map(PastePath)
            .ok_or_else(|| D::Error::custom(whole("`component_path` must list 0..64 occurrence ids")))
    }
}

impl JsonSchema for PastePath {
    fn schema_name() -> Cow<'static, str> {
        "PastePath".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "The occurrence ids from the top of the design down to a placement.",
            "type": "array",
            "items": {"type": "integer", "minimum": 0},
            "maxItems": MAX_PATH
        })
    }
}

fn paste_component<'de, D: Deserializer<'de>>(d: D) -> Result<Option<ComponentRef>, D::Error> {
    match Value::deserialize(d)? {
        Value::Number(n) => Ok(Some(ComponentRef(n.to_string()))),
        Value::String(s) => Ok(Some(ComponentRef(s))),
        _ => Err(D::Error::custom(whole("`component` must be a component id or name"))),
    }
}

fn paste_path<'de, D: Deserializer<'de>>(d: D) -> Result<Option<PastePath>, D::Error> {
    PastePath::deserialize(d).map(Some)
}

fn paste_translate<'de, D: Deserializer<'de>>(d: D) -> Result<Option<PasteTranslation>, D::Error> {
    PasteTranslation::deserialize(d).map(Some)
}

/// `from_design` is true or false; `null` is refused, as the handler does.
fn from_design<'de, D: Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
    match Value::deserialize(d)? {
        Value::Bool(b) => Ok(Some(b)),
        _ => Err(D::Error::custom(whole("`from_design` must be true or false"))),
    }
}

/// Paste the copied features as independent copies at the timeline marker: sketches get their own
/// dimension parameters, features their own names, and references inside the copied set point at
/// the copies. Body transfers are left out. One undo step. With `from_design`, only sketch
/// features are pasted, from the snapshot another design's copy left. Every key reads the same
/// either way.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct PasteParams {
    /// Move the copies' geometry by this much, in mm. Default: not moved.
    #[serde(default, deserialize_with = "paste_translate", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PasteTranslation")]
    pub translate: Option<PasteTranslation>,
    /// The component the copies go into, by id or name. Default: the active one.
    #[serde(default, deserialize_with = "paste_component", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "ComponentRef")]
    pub component: Option<ComponentRef>,
    /// The placement of that component the copies are authored in, as occurrence ids. Default: the
    /// active placement for the active component, else the component's only placement.
    #[serde(default, deserialize_with = "paste_path", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "PastePath")]
    pub component_path: Option<PastePath>,
    /// True pastes the sketch features of the clipboard snapshot of another design, with their
    /// parameters. Default: false, the features copied in this design.
    #[serde(default, deserialize_with = "from_design", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "bool")]
    pub from_design: Option<bool>,
}

/// A feature a paste made.
#[derive(Debug, Serialize, JsonSchema)]
pub struct Pasted {
    /// The new feature, by id.
    pub id: u64,
    /// Its name.
    pub name: String,
    /// The name of the feature it is a copy of.
    pub from: String,
}

/// A pasted feature that did not rebuild.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PasteError {
    /// The pasted feature, by id.
    pub feature: u64,
    /// Why it did not rebuild.
    pub error: String,
}

/// What `timeline.paste` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct PasteResult {
    /// The features made, in timeline order.
    pub pasted: Vec<Pasted>,
    /// The pasted features that did not rebuild.
    pub errors: Vec<PasteError>,
    /// What the paste left out or kept (body transfers, external face attachments).
    pub notices: Vec<String>,
    /// 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>,
}

// ---- timeline.add ----

/// The `feature` of `timeline.add`: an object, as a design file or `timeline.inspect` holds a
/// feature.
#[derive(Clone, Debug, PartialEq)]
pub struct RecordedFeature(pub Map<String, Value>);

impl<'de> Deserialize<'de> for RecordedFeature {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::Object(o) => Ok(RecordedFeature(o)),
            _ => Err(D::Error::custom(whole("`feature` must be a feature object, as a design file or timeline.inspect has it"))),
        }
    }
}

impl JsonSchema for RecordedFeature {
    fn schema_name() -> Cow<'static, str> {
        "RecordedFeature".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "A feature as the design file and timeline.inspect hold it: {type, name?, id?, …}. \
                The name is kept even when another feature has it; the id is kept, and refused when another \
                feature has it. Whether the rest is a feature is the command's to check.",
            "type": "object"
        })
    }
}

/// The model parameters of `timeline.add`: read by the handler's own reader.
#[derive(Clone, Debug)]
pub struct StepParams(pub Vec<solidcraft_doc::Param>);

impl<'de> Deserialize<'de> for StepParams {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        let value = Value::deserialize(d)?;
        crate::cmd::step_params("timeline.add", Some(&value)).map(StepParams).map_err(|e| D::Error::custom(handler_message(e)))
    }
}

impl JsonSchema for StepParams {
    fn schema_name() -> Cow<'static, str> {
        "StepParams".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        let text = json!({"type": ["string", "null"]});
        json_schema!({
            "description": "Model parameters the feature's sketch dimensions use.",
            "type": "array",
            "maxItems": solidcraft_sketch::MAX_CONSTRAINTS,
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "The parameter's name."},
                    "expression": {
                        "description": "Its value: a number or an expression that is not blank.",
                        "anyOf": [{"type": "string", "pattern": not_blank_pattern()}, {"type": "number"}]
                    },
                    "unit": text.clone(),
                    "comment": text
                },
                "required": ["name", "expression"]
            }
        })
    }
}

fn recorded<'de, D: Deserializer<'de>>(d: D) -> Result<Option<RecordedFeature>, D::Error> {
    RecordedFeature::deserialize(d).map(Some)
}

fn feature_required(schema: &mut Schema) {
    require(schema, "feature");
}

/// Append one recorded feature to the timeline, as the design file holds it, so every feature
/// kind replays exactly: the same ids, names, parameter names and stored edge and face names (the
/// steps `timeline.export_script` writes). It goes at the timeline marker. One undo step.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields, transform = feature_required)]
pub struct AddParams {
    // Optional in the type and required in the schema (`feature_required`).
    /// The feature, as a design file or `timeline.inspect` has it.
    #[serde(default, deserialize_with = "recorded", skip_serializing_if = "Option::is_none")]
    #[schemars(with = "RecordedFeature")]
    pub feature: Option<RecordedFeature>,
    /// The model parameters its sketch dimensions use, each {name, expression, unit?, comment?}.
    /// Default: none.
    #[serde(default)]
    #[schemars(with = "StepParams")]
    pub params: Option<StepParams>,
}

/// What `timeline.add` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct AddResult {
    /// The new feature, by id.
    pub feature: u64,
    /// Its name.
    pub name: String,
    /// Why it did not build, or null.
    pub error: Option<String>,
    /// A warning from building it, or null.
    pub warning: Option<String>,
    /// 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>,
}

// ---- timeline.export_script ----

fn script_path<'de, D: Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::String(s) => Ok(Some(s)),
        _ => Err(D::Error::custom(whole("`path` must be a file path"))),
    }
}

/// Write the design's history as a command script that rebuilds it (`solidcraft-cli eval` and
/// `run` replay it): one step per setting and feature, and a list of what the script leaves out.
/// A design with components or joints is refused for now. The design is not changed.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ExportScriptParams {
    /// A file to write the script to, as JSON. Default: none, the script is only returned.
    #[serde(default, deserialize_with = "script_path", skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
}

/// One step of a command script.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ScriptStep {
    /// The command the step runs.
    pub command: String,
    /// Its parameters.
    pub params: Value,
}

/// Where a script came from and how to replay it. Fields stay in alphabetical order: a script file
/// is written from this type, and its keys have always been sorted.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ScriptAbout {
    /// The design's name.
    pub design: String,
    /// The design file format the `timeline.add` steps hold features in.
    pub format: String,
    /// How to replay the script.
    pub replay: String,
    /// The version of SolidCraft that wrote it.
    pub version: String,
}

/// A command script. Fields stay in alphabetical order (see [`ScriptAbout`]).
#[derive(Debug, Serialize, JsonSchema)]
pub struct Script {
    pub about: ScriptAbout,
    /// The steps that rebuild the design on an empty one.
    #[schemars(with = "Vec<ScriptStep>")]
    pub commands: Vec<Value>,
}

/// What `timeline.export_script` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ExportScriptResult {
    /// What the script leaves out (appearances, folders, views, configurations, print-face
    /// assignments…).
    pub omitted: Vec<String>,
    /// The file written, or null.
    pub path: Option<String>,
    /// The script.
    pub script: Script,
    /// How many steps it has.
    pub steps: usize,
    /// 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>,
}

#[cfg(test)]
#[path = "timeline_clipboard_tests.rs"]
mod tests;