SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
CONTRIBUTING.md for outside contributors; README status and a Contributing section
bherbruck2ea99556212e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000000..f7f0c9b0d3--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,153 @@+# Contributing to SolveCraft++SolveCraft is an open-source parametric 3D CAD app written in pure Rust, in the style of+Autodesk Fusion. You sketch on a plane, constrain the sketch, turn profiles into solids, and+change a parameter to watch the timeline rebuild. It runs as a desktop app (Windows, Linux), in+the browser (wasm + WebGPU/WebGL2), headless from a CLI, and as an MCP server that AI agents can+model with.++Help is welcome, whether that's a one-line fix or owning a whole area. This page covers how to+build it, how the code is laid out, the few rules that aren't negotiable, and where help is+needed most.++## Get it running (about 10 minutes on a fast machine)++You need stable Rust 1.90 or newer. For the web+build you also need `rustup target add wasm32-unknown-unknown` and [`trunk`](https://trunkrs.dev).++```sh+git clone https://github.com/bherbruck/solvecraft && cd solvecraft+cargo run --release -p solvecraft -- --sample # desktop app with a sample part+cargo test --workspace --release # unit, engine and UI-scenario tests+cargo xtask ci # everything a PR must pass (see below)+```++Web: `cd apps/solvecraft-web && trunk serve --release`, then open the printed URL (`?sample`+opens the sample part, `?webgl` forces WebGL2). Saving and opening files in the browser needs+HTTPS or localhost, because it uses the Origin Private File System.++Windows from Linux: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solvecraft`.++## How the code is laid out++The [README](README.md#architecture) has the layer table. The short version:++- `crates/geom`: vectors, planes, meshes, measures.+- `crates/sketch`: our own constraint solver, plus profile finding.+- `crates/kernel`: the B-rep kernel boundary. It wraps [truck](https://github.com/ricosjp/truck),+ and it's the only crate allowed to touch truck. Fillets, chamfers, shell/offset, Delete Face,+ Split Face, STEP/IGES read and write, and face provenance are our own code here. Patched+ copies of three truck crates live in `vendor/` and are excluded from our fmt/clippy rules.+- `crates/doc`: the document. It holds parameters and expressions, the feature timeline and its+ incremental rebuild, components and occurrences, joints, appearances, and persistent naming.+- `crates/io`: design files and mesh formats (3MF, STL, OBJ).+- `crates/engine`: the session and the command registry. **Everything the user can do is a+ command**, and the toolbar, dialogs, scripts, CLI, control channel and MCP all run the same+ commands.+- `crates/ui-egui`: the desktop/web front end (egui + wgpu). It's swappable; nothing below it+ depends on egui.+- `crates/mcp`, `apps/solvecraft`, `apps/solvecraft-cli`, `apps/solvecraft-web`.++`cargo xtask layers` fails the build if a lower layer depends on a higher one.++## Rules that aren't negotiable++1. **Clean-room.** We observe Fusion as a black box: its UI, how parts it builds measure, and+ what it does with a given input. We never copy Autodesk code, icons, artwork, help text,+ tooltips, templates or materials, and we never commit files Fusion produced. Command ids are+ our own (`solid.fillet`, not Fusion's internal names).+2. **No GPL/LGPL/AGPL code, not even reading it.** That rules out OpenCASCADE, FreeCAD+ (including planegcs), SolveSpace, CadQuery/OCP, LibreCAD and QCAD. SolveCraft is+ MIT OR Apache-2.0, and its solver and blends are written from the maths. Permissive+ dependencies are fine. Note which one you're adding and why in the PR.+3. **Every asset is original or openly licensed and has a row in+ [ATTRIBUTION.md](ATTRIBUTION.md).** Icons are drawn in code (`crates/ui-egui/src/icons.rs`).+ `cargo xtask assets` enforces this.+4. **Never crash.** People trust a CAD app with their work.+ - Non-test code never uses `unwrap`, `expect`, `panic!` or indexing on input-derived data.+ There's no `unsafe`, and clippy denies it.+ - An unsupported case returns an error ("not supported yet: …"); it never panics.+ - Every call into truck goes through `solvecraft_kernel::guard`.+ - Every crash fix comes with a regression test.+5. **Everything is a command, with a test.** A new feature means a `CommandSpec` in+ `crates/engine/src/cmd/`, engine tests that measure the result (volume, area,+ face/edge/vertex counts against a value you can derive), and for UI work a scenario (below).++[AGENTS.md](AGENTS.md) has the long form of these rules. It's written for AI agents, but it's+the most complete description of the house style.++## Tests++| What | Where | Run |+|---|---|---|+| Unit and engine tests | next to the code, or `*_tests.rs` files | `cargo test --workspace --release` |+| UI scenarios | `crates/ui-egui/tests/scenarios/*.json` | part of `cargo test` |+| Fusion oracle | `cargo xtask oracle` | needs the local oracle data (see below) |++**UI scenarios** drive the real app headless: start a tool, click a plane or a sketch point,+press keys, then assert on the result.++```json+[+ {"start": "sketch.create"},+ {"click": {"plane": "XY"}},+ {"start": "sketch.rectangle.two_point"},+ {"click": {"sketch": [0, 0]}},+ {"click": {"sketch": [40, 30]}},+ {"expect": {"errors": 0}}+]+```++A new `.json` file in that folder is picked up automatically. To record a bug before it's fixed,+put `{"pending": "why"}` in the scenario, and remove it in the PR that fixes the bug.++**Release mode matters.** CI runs the tests with `--release`. truck has debug-only assertions+that can fail on valid geometry, so if a test fails only in debug, say so in the PR.++**The Fusion oracle** is a set of 76 reference parts, each built in Fusion from a recipe.+SolveCraft rebuilds the same recipe and compares volume, area and topology counts with Fusion's+measurements; [docs/oracle.md](docs/oracle.md) has the current results. The recipes and+measurements live outside the repo (`plan/`, gitignored), because they come from a Fusion+install. If you work on geometry and want to check against it, ask in an issue.++## Sending a change++1. Work is tracked in [GitHub issues](https://github.com/bherbruck/solvecraft/issues), labelled+ by area (`area:kernel`, `area:sketch`, `area:doc`, `area:ui`, `area:infra`). Before starting,+ comment on the issue so it gets the `in progress` label and two people don't build the same+ thing. For anything bigger than a bug fix that has no issue yet, open one first.+2. Branch from `main` and keep the PR to one topic.+3. Run `cargo xtask ci` before pushing. It runs fmt, clippy (`-D warnings`), the tests in+ release mode, the asset and layer checks, and the wasm build check. A PR has to pass it.+4. Reference the issue (`Fixes #12`). In the PR, say what you tested and how. For geometry work, include the measured numbers (and+ the expected ones).++Much of SolveCraft so far was written by AI coding agents (Claude) working in parallel, each+owning one area, with a human setting direction and reporting bugs. Their working notes are in+[AGENTS.md](AGENTS.md). Human contributors are just as welcome. Use whatever tools you like, as+long as the change meets the rules above.++## Where help is wanted most++See the [`help wanted`](https://github.com/bherbruck/solvecraft/labels/help%20wanted) and+[`good first issue`](https://github.com/bherbruck/solvecraft/labels/good%20first%20issue) labels.+In order of how much they'd help users:++1. **Fillet and blend robustness.** Fillets are our own code (truck has no fillet operation).+ Constant, variable-radius and chord fillets work, and so do corners where fillets of+ different radii meet, including three rounds meeting at a vertex. Next are setback corners, fillets along curved edges between curved+ faces, and fillets that consume neighbouring faces.+2. **Boolean robustness.** A random-design fuzzer currently gets about half of its designs+ through without a kernel error. Each failing seed is a reproducible bug.+3. **Y-up / Z-up.** SolveCraft is Z-up only, so most STEP files (from SolidWorks, Onshape, or+ Fusion's default) open lying on their backs. Fusion solves this with a "default modeling+ orientation" preference.+4. **Imported appearances.** Colours from STEP files are lost when a feature changes the+ imported body. They should become design appearances on import.+5. **Drawings, CAM and mesh tools.** These are out of scope for now (see+ [ROADMAP.md](ROADMAP.md)), but anyone who wants to own one is welcome.++## Licence++By contributing you agree that your contribution is licensed as MIT OR Apache-2.0, like the rest+of SolveCraft. SolveCraft isn't affiliated with Autodesk. Fusion is a trademark of Autodesk, Inc.diff --git a/README.md b/README.mdindex baacc57d9e..7a66b91ca1 100644--- a/README.md+++ b/README.md@@ -8,9 +8,11 @@ storytold "craft" family.-**Status: early (milestone M0 done, M1 in progress).** See [ROADMAP.md](ROADMAP.md),-[docs/parity.md](docs/parity.md) (command parity with Fusion's Design workspace) and-[docs/oracle.md](docs/oracle.md) (parts built in Fusion, rebuilt and measured in SolveCraft).+**Status: early but usable for simple parts.** 76 of 76 reference parts built in Fusion+rebuild in SolveCraft with the same volume, area and topology ([docs/oracle.md](docs/oracle.md));+command parity with Fusion's Design workspace is tracked in [docs/parity.md](docs/parity.md).+Open work and known bugs are in [GitHub issues](https://github.com/bherbruck/solvecraft/issues),+and help is welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).## What works@@ -98,6 +100,11 @@ configuration and an example session: [docs/mcp.md](docs/mcp.md).| L5 | `ui-egui`, `mcp` | the swappable desktop front end; the MCP server (headless or bridged to the app) || apps | `solvecraft`, `solvecraft-cli` | desktop app, headless CLI |+## Contributing++See [CONTRIBUTING.md](CONTRIBUTING.md): how to build and test, the code map, the clean-room+and licence rules, and where help is wanted most.+## LicenceMIT OR Apache-2.0, at your option. SolveCraft is not affiliated with Autodesk; Fusion is a