zmerlynn/manifold-csg / .claude/skills/update-upstream
update-upstream
VerifiedBump the manifold3d pin, add FFI + safe wrappers for new upstream C API functions, bump versions, open a PR
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
SKILL.md
View on GitHub---
name: update-upstream
description: Bump the manifold3d pin, add FFI + safe wrappers for new upstream C API functions, bump versions, open a PR
user-invocable: true
---
# Update upstream
Guided workflow for picking up upstream manifold3d changes: bump the pin,
audit carry-patches, bind new C API, add safe wrappers, bump versions,
open a PR. The user still makes API shape decisions for new wrappers;
this skill handles the mechanical parts.
## Arguments
- No arguments: bump to current upstream master HEAD
- A commit SHA, tag, or branch name: bump to that ref instead (e.g., `v3.5.0`, `abc123def`)
## Steps
Work through these in order. Stop and surface any decision to the user.
### 1. Clean working tree, new branch
```
git status # must be clean on main
git checkout main && git pull
git checkout -b update-upstream-<ref>
```
### 2. Determine the target ref
- If the user gave a ref, use it directly.
- Otherwise, query upstream master HEAD: `gh api repos/elalish/manifold/git/refs/heads/master --jq '.object.sha'`
- Show the user: current pin (from `MANIFOLD_VERSION` in `crates/manifold-csg-sys/build.rs`), the target, and a one-line commit summary of what's between them: `gh api repos/elalish/manifold/compare/<current>...<target> --jq '{ahead_by: .ahead_by, commits: [.commits[] | {sha: .sha[0:8], message: (.commit.message | split("\n")[0])}]}'`
- Confirm before proceeding.
- **Check shim coverage.** Before committing to the target, verify `wasm-cxx-shim` supports it. Look at the latest shim release's `MANIFOLD_GIT_TAG` default (in the helper at `cmake/WasmCxxShimManifold.cmake`, or in the release notes). If the target SHA is past the shim's tested pin, flag it: either pick a target the shim already supports, or be ready to cfg-gate any new C API on `not(all(target_arch = "wasm32", target_os = "unknown"))` (the wasm-uu lane will fall back to the shim's tested pin via `wasm_cxx_shim_add_manifold()`'s default). Mismatch without gating produces wasm-uu link failures — see CLAUDE.md "Versioning" section.
### 3. Update the pin
Edit `MANIFOLD_VERSION` in `crates/manifold-csg-sys/build.rs`. The constant accepts tags, branches, or commit SHAs — prefer SHAs for reproducibility (commit on master) or tags for tagged releases.
Then update `pinnedSrc` in `flake.nix` to match: set `version` to the new pin (without the `v`) and `hash` to the output of `nix flake prefetch github:elalish/manifold/v<version>`. The flake reads `MANIFOLD_VERSION` from build.rs and asserts `pinnedSrc` matches, so a missed update fails at `nix develop`. Check it with `nix develop -c true`. Do NOT wait for nixpkgs: if the locked nixpkgs ships a different manifold, the `nix-offline` lane builds the pinned tag itself (slower, still correct). Do not run `nix flake update` in the bump PR either. Once `nixos-unstable` ships the new version, `.github/workflows/flake-lock.yml` opens that PR on its own. The flake only follows `vX.Y.Z` tag pins; a SHA pin needs the fallback changed to fetch by `rev`.
### 4. Carry-patch audit
For each patch in `crates/manifold-csg-sys/patches/`:
- Check if the referenced upstream PR has been merged (`gh api repos/elalish/manifold/pulls/<N>`).
- If merged AND included in the new pin, the patch can be removed — propose deletion to the user and remove if they agree.
- Run `cargo clean -p manifold-csg-sys && cargo build -p manifold-csg-sys`. If any patch fails to apply, stop and surface the conflict — the user needs to either update the patch or drop it.
### 5. Clean build and test
```
cargo clean -p manifold-csg-sys
cargo test --features nalgebra
```
Any test failure stops the flow. Common causes: upstream changed behavior (e.g., numerical differences from deterministic math changes), signature changes (will show as compile errors), or carry-patch conflicts.
### 6. Diff the C header against our FFI bindings
The built C header is at `target/debug/build/manifold-csg-sys-*/out/manifold-src/bindings/c/include/manifold/manifoldc.h`. Find it and extract every `manifold_*` function declaration, compare against `pub fn manifold_*` in `crates/manifold-csg-sys/src/lib.rs`.
Also look for new types (structs, enums, opaque handles) in `bindings/c/include/manifold/types.h`.
Report:
- **New functions** (present in header, missing from sys crate) — grouped by category (memory management, allocation, ray casting, etc.)
- **Changed signatures** (present in both but different) — these are breaking upstream changes that need attention
- **Removed functions** (in sys crate, missing from header) — should be deleted from our FFI
### 7. Decide what to bind (user choice)
Show the list of new functions to the user. Ask which to bind in this PR. Some guidelines:
- Standalone features (e.g., ray casting) — usually yes
- Allocation/destruct helpers for new types — bind along with the feature they support
- Deeply specialized accessors — may defer if no clear safe API maps to them
- Internal size queries — bind but mark as internal
If the user says "bind everything new," proceed without individual approval.
### 8. Add FFI declarations
In `crates/manifold-csg-sys/src/lib.rs`:
- Add any new opaque handle types (e.g., `pub struct ManifoldXyzVec { _private: [u8; 0] }`).
- Add any new value types with `#[repr(C)]`.
- Add new size/alloc/destruct/delete functions in their respective sections.
- Add new operational functions in a logical section (or create a new section with a `// ── <Name> ──` header).
Match the upstream C header signature exactly. Use `*const` for read-only pointers where the C uses non-const but we can tell the function is read-only.
### 9. Add safe wrappers
For each new function, write a safe wrapper method or free function in the appropriate `crates/manifold-csg/src/` file. If the new functionality deserves its own module (like ray casting did), create it and register in `lib.rs`.
Follow existing patterns:
- Allocate with `manifold_alloc_*`, call the FFI, delete the allocation, return a new wrapper.
- For methods returning multiple values, define a value-type struct in the safe crate with `[f64; 3]` arrays for 3D vectors.
- Safety comments: every `unsafe` block gets a `// SAFETY: ...` explaining the invariant.
- `#[must_use]` on pure transforms returning `Self`.
- Link to upstream docs in the doc comment if the semantics are non-obvious.
### 10. Add tests
New tests go in `crates/manifold-csg/tests/integration.rs`. Cover:
- Happy path (does the feature work?)
- Edge case (empty input, miss, degenerate geometry)
- Any invariants (e.g., unit-length normals, non-negative distances)
Run `cargo test --features nalgebra` and `cargo clippy --all-targets --features nalgebra -- -D warnings`.
### 11. Update API_COVERAGE.md
Add rows for new wrappers. Update the summary if present (but prefer prose over hardcoded counts — see CLAUDE.md).
### 12. Bump versions
Per CLAUDE.md versioning policy:
- `manifold-csg-sys`: patch bump (e.g., `3.4.103` → `3.4.104`) since upstream contents changed. If the upstream major.minor changed (new manifold3d release), update major.minor accordingly.
- `manifold-csg` (workspace version): patch bump for additive changes, minor for breaking.
- `manifold-csg`'s `manifold-csg-sys` dep: update to new sys version.
- `manifold3d-sys` and `manifold3d` share their canonical counterparts' versions via `=` pins; update those pins.
### 13. Commit and open PR
One commit. Commit message explains:
- New pin SHA or tag
- Any carry-patches added or removed
- New bindings added
- Version bumps
Use `/pr` skill or `gh pr create` directly. Show the user the draft before posting — the `feedback_no_public_posts` rule applies.
### 14. (Optional) publish
If the user wants to publish after the PR merges, invoke `/publish`.
## Rules
- Do NOT invoke this skill on a dirty working tree.
- Do NOT skip the clean rebuild — it's what confirms the new pin actually works.
- Do NOT bind functions blindly — judgment about what deserves a safe wrapper is part of the job.
- Surface any upstream API breakage loudly — it's easy to miss and expensive to ship.
- All rules from CLAUDE.md apply (no hard-wrap in PR descriptions, no Claude session links in commits, show PR drafts before posting, etc.).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |