|
|
|
|
@@ -0,0 +1,285 @@
|
|
|
|
|
# CLAUDE.md — Developer Context for Kindred Create
|
|
|
|
|
|
|
|
|
|
## Project Overview
|
|
|
|
|
|
|
|
|
|
Kindred Create is a fork of FreeCAD 1.0+ that adds integrated tooling for professional engineering workflows. It ships a context-aware UI system, two addon command sets (ztools and Silo), a Catppuccin Mocha dark theme, and a pluggable file origin layer on top of FreeCAD's parametric modeling core.
|
|
|
|
|
|
|
|
|
|
- **Kindred Create version:** 0.1.5
|
|
|
|
|
- **FreeCAD base version:** 1.2.0
|
|
|
|
|
- **License:** LGPL-2.1-or-later
|
|
|
|
|
- **Repository:** `git.kindred-systems.com/kindred/create` (Gitea)
|
|
|
|
|
- **Main branch:** `main`
|
|
|
|
|
|
|
|
|
|
## Quick Start
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
|
|
|
|
|
cd create
|
|
|
|
|
pixi run configure # CMake configure (debug by default)
|
|
|
|
|
pixi run build # Build
|
|
|
|
|
pixi run install # Install to build dir
|
|
|
|
|
pixi run freecad # Launch
|
|
|
|
|
pixi run test # Run C++ tests (ctest)
|
|
|
|
|
pixi run test-kindred # Run Python/Kindred tests
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Build variants: append `-debug` or `-release` (e.g., `pixi run build-release`). See `CMakePresets.json` for platform-specific presets (Linux x86_64/aarch64, macOS Intel/ARM, Windows x64).
|
|
|
|
|
|
|
|
|
|
## Repository Structure
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
create/
|
|
|
|
|
├── src/
|
|
|
|
|
│ ├── App/ Core application (C++)
|
|
|
|
|
│ ├── Base/ Base classes, type system, persistence (C++)
|
|
|
|
|
│ ├── Gui/ GUI framework (C++)
|
|
|
|
|
│ │ ├── EditingContext.h Editing context resolver (Kindred feature)
|
|
|
|
|
│ │ ├── BreadcrumbToolBar.h Breadcrumb navigation widget (Kindred feature)
|
|
|
|
|
│ │ ├── FileOrigin.h Abstract origin interface (Kindred feature)
|
|
|
|
|
│ │ ├── OriginManager.h Origin lifecycle management
|
|
|
|
|
│ │ ├── CommandOrigin.cpp Origin_Commit/Pull/Push/Info/BOM commands
|
|
|
|
|
│ │ ├── ApplicationPy.h All FreeCADGui.* Python bindings
|
|
|
|
|
│ │ ├── Application.h App signals (fastsignals)
|
|
|
|
|
│ │ ├── Stylesheets/ QSS theme files
|
|
|
|
|
│ │ └── PreferencePacks/ Preference configurations (build-time generated)
|
|
|
|
|
│ ├── Mod/ FreeCAD modules (PartDesign, Assembly, Sketcher, etc.)
|
|
|
|
|
│ │ └── Create/ Kindred Create module
|
|
|
|
|
│ │ ├── Init.py Console bootstrap — loads addons
|
|
|
|
|
│ │ ├── InitGui.py GUI bootstrap — loads addons, Silo setup, update checker
|
|
|
|
|
│ │ ├── addon_loader.py Manifest-driven loader with dependency resolution
|
|
|
|
|
│ │ └── kc_format.py .kc file format preservation
|
|
|
|
|
│ └── 3rdParty/ Vendored dependencies
|
|
|
|
|
│ ├── OndselSolver/ [submodule] Assembly constraint solver (forked)
|
|
|
|
|
│ ├── FastSignals/ Signal/slot library (NOT Boost)
|
|
|
|
|
│ └── GSL/ [submodule] Microsoft Guidelines Support Library
|
|
|
|
|
├── mods/ Kindred addon modules
|
|
|
|
|
│ ├── sdk/ Addon SDK — stable API contract (priority 0)
|
|
|
|
|
│ ├── ztools/ [submodule] Command provider (priority 50)
|
|
|
|
|
│ ├── silo/ [submodule] PLM workbench (priority 60)
|
|
|
|
|
│ ├── solver/ [submodule] Assembly solver research (GNN-based)
|
|
|
|
|
│ └── quicknav/ [submodule] Navigation addon
|
|
|
|
|
├── docs/ mdBook documentation + architecture docs
|
|
|
|
|
├── tests/ C++ unit tests (GoogleTest)
|
|
|
|
|
├── package/ Packaging (debian/, rattler-build/)
|
|
|
|
|
├── resources/ Branding, icons, desktop integration
|
|
|
|
|
├── cMake/ CMake helper modules
|
|
|
|
|
├── .gitea/workflows/ CI/CD pipelines
|
|
|
|
|
├── CMakeLists.txt Root build configuration (CMake 3.22.0+)
|
|
|
|
|
├── CMakePresets.json Platform build presets
|
|
|
|
|
└── pixi.toml Pixi environment and build tasks
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Build System
|
|
|
|
|
|
|
|
|
|
- **Primary:** CMake 3.22.0+ with Ninja generator
|
|
|
|
|
- **Environment:** [Pixi](https://pixi.sh) (conda-forge) manages all dependencies
|
|
|
|
|
- **Key deps:** Qt 6.8.x, Python 3.11.x, OpenCASCADE 7.8.x, PySide6, Boost, VTK, SMESH
|
|
|
|
|
- **Presets:** `conda-linux-debug`, `conda-linux-release`, `conda-macos-debug`, `conda-macos-release`, `conda-windows-debug`, `conda-windows-release`
|
|
|
|
|
- **Tasks summary:**
|
|
|
|
|
|
|
|
|
|
| Task | Description |
|
|
|
|
|
|------|-------------|
|
|
|
|
|
| `pixi run configure` | CMake configure (debug) |
|
|
|
|
|
| `pixi run build` | Build (debug) |
|
|
|
|
|
| `pixi run install` | Install to build dir |
|
|
|
|
|
| `pixi run freecad` | Launch FreeCAD |
|
|
|
|
|
| `pixi run test` | C++ tests via ctest |
|
|
|
|
|
| `pixi run test-kindred` | Python/Kindred test suite |
|
|
|
|
|
|
|
|
|
|
## Architecture Patterns
|
|
|
|
|
|
|
|
|
|
### Signals — Use FastSignals, NOT Boost
|
|
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
|
#include <fastsignals/signal.h>
|
|
|
|
|
// See src/Gui/Application.h:121-155 for signal declarations
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
All signals in `src/Gui/` use `fastsignals::signal`. Never use Boost.Signals2.
|
|
|
|
|
|
|
|
|
|
### Type Checking Across Modules
|
|
|
|
|
|
|
|
|
|
Avoid header dependencies between `src/Gui/` and `src/Mod/` by using runtime type checks:
|
|
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
|
auto type = Base::Type::fromName("Sketcher::SketchObject");
|
|
|
|
|
if (obj->isDerivedFrom(type)) { ... }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Python Bindings
|
|
|
|
|
|
|
|
|
|
All `FreeCADGui.*` functions go in `src/Gui/ApplicationPy.h` and `src/Gui/ApplicationPy.cpp`. Use `METH_VARARGS` only (no `METH_KEYWORDS` in this file). Do not create separate files for new Python bindings.
|
|
|
|
|
|
|
|
|
|
### Toolbar Visibility
|
|
|
|
|
|
|
|
|
|
Use `ToolBarItem::DefaultVisibility::Unavailable` to hide toolbars by default, then `ToolBarManager::setState(ForceAvailable)` to show them contextually. This pattern is proven by the Sketcher module.
|
|
|
|
|
|
|
|
|
|
The `appendToolbar` Python API accepts an optional 3rd argument: `"Visible"`, `"Hidden"`, or `"Unavailable"`.
|
|
|
|
|
|
|
|
|
|
### Editing Context System
|
|
|
|
|
|
|
|
|
|
The `EditingContextResolver` singleton (`src/Gui/EditingContext.h/.cpp`) drives the context-aware UI. It evaluates registered context definitions in priority order and activates the matching one, setting toolbar visibility and updating the `BreadcrumbToolBar`.
|
|
|
|
|
|
|
|
|
|
Built-in contexts: `sketcher.edit`, `assembly.edit`, `partdesign.feature`, `partdesign.body`, `assembly.idle`, `spreadsheet`, `empty_document`, `no_document`.
|
|
|
|
|
|
|
|
|
|
Python API:
|
|
|
|
|
- `FreeCADGui.registerEditingContext()` — register a new context
|
|
|
|
|
- `FreeCADGui.registerEditingOverlay()` — conditional toolbar overlay
|
|
|
|
|
- `FreeCADGui.injectEditingCommands()` — add commands to existing contexts
|
|
|
|
|
- `FreeCADGui.currentEditingContext()` — query active context
|
|
|
|
|
- `FreeCADGui.refreshEditingContext()` — force re-evaluation
|
|
|
|
|
|
|
|
|
|
### Addon Loading
|
|
|
|
|
|
|
|
|
|
Addons in `mods/` are loaded by `src/Mod/Create/addon_loader.py`. Each addon provides a `package.xml` with `<kindred>` extensions declaring version bounds, load priority, and dependencies. The loader resolves via topological sort: **sdk** (0) -> **ztools** (50) -> **silo** (60).
|
|
|
|
|
|
|
|
|
|
A `<workbench>` tag in `package.xml` is required for `InitGui.py` to be loaded, even if no actual workbench is registered.
|
|
|
|
|
|
|
|
|
|
### Deferred Initialization
|
|
|
|
|
|
|
|
|
|
GUI setup uses `QTimer.singleShot` with staggered delays:
|
|
|
|
|
- 500ms: `.kc` file format registration
|
|
|
|
|
- 1500ms: Silo origin registration
|
|
|
|
|
- 2000ms: Auth dock + ztools commands
|
|
|
|
|
- 2500ms: Silo overlay
|
|
|
|
|
- 3000ms: Silo first-start check
|
|
|
|
|
- 4000ms: Activity panel
|
|
|
|
|
- 10000ms: Update checker
|
|
|
|
|
|
|
|
|
|
### Unified Origin System
|
|
|
|
|
|
|
|
|
|
File operations (New, Open, Save, Commit, Pull, Push) are abstracted behind `FileOrigin` (`src/Gui/FileOrigin.h`). `LocalFileOrigin` handles local files; `SiloOrigin` (`mods/silo/freecad/silo_origin.py`) backs Silo-tracked documents. The active origin is selected automatically based on document properties (`SiloItemId`, `SiloPartNumber`).
|
|
|
|
|
|
|
|
|
|
## Submodules
|
|
|
|
|
|
|
|
|
|
| Path | Repository | Branch | Purpose |
|
|
|
|
|
|------|------------|--------|---------|
|
|
|
|
|
| `mods/ztools` | `git.kindred-systems.com/forbes/ztools` | `main` | Extended PartDesign/Assembly/Spreadsheet tools |
|
|
|
|
|
| `mods/silo` | `git.kindred-systems.com/kindred/silo-mod` | `main` | PLM workbench (includes silo-client submodule) |
|
|
|
|
|
| `mods/solver` | `git.kindred-systems.com/kindred/solver` | `main` | Assembly solver research (GNN-based) |
|
|
|
|
|
| `mods/quicknav` | `git.kindred-systems.com/kindred/quicknav` | — | Navigation addon |
|
|
|
|
|
| `src/3rdParty/OndselSolver` | `git.kindred-systems.com/kindred/solver` | — | Constraint solver (forked with NR fix) |
|
|
|
|
|
| `src/3rdParty/GSL` | `github.com/microsoft/GSL` | — | Guidelines Support Library |
|
|
|
|
|
| `src/Mod/AddonManager` | `github.com/FreeCAD/AddonManager` | — | FreeCAD addon manager |
|
|
|
|
|
| `tests/lib` | `github.com/google/googletest` | — | C++ test framework |
|
|
|
|
|
|
|
|
|
|
Update a submodule:
|
|
|
|
|
```bash
|
|
|
|
|
cd mods/silo
|
|
|
|
|
git checkout main && git pull
|
|
|
|
|
cd ../..
|
|
|
|
|
git add mods/silo
|
|
|
|
|
git commit -m "chore: update silo submodule"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Initialize all submodules: `git submodule update --init --recursive`
|
|
|
|
|
|
|
|
|
|
## Key Addon Modules
|
|
|
|
|
|
|
|
|
|
### ztools (`mods/ztools/`)
|
|
|
|
|
|
|
|
|
|
Command provider (NOT a workbench). Injects tools into PartDesign, Assembly, and Spreadsheet contexts via `_ZToolsManipulator` (WorkbenchManipulator) and `injectEditingCommands()`.
|
|
|
|
|
|
|
|
|
|
Commands: `ZTools_DatumCreator`, `ZTools_EnhancedPocket`, `ZTools_RotatedLinearPattern`, `ZTools_AssemblyLinearPattern`, `ZTools_AssemblyPolarPattern`, spreadsheet formatting (Bold, Italic, Underline, alignment, colors, QuickAlias).
|
|
|
|
|
|
|
|
|
|
Source: `mods/ztools/ztools/ztools/commands/` (note the double `ztools` nesting).
|
|
|
|
|
|
|
|
|
|
### Silo (`mods/silo/`)
|
|
|
|
|
|
|
|
|
|
PLM workbench with 14 commands for parts lifecycle management. Go REST API server + PostgreSQL + MinIO backend. FreeCAD client communicates via shared `silo-client` submodule.
|
|
|
|
|
|
|
|
|
|
Silo origin detection: `silo_origin.py:ownsDocument()` checks for `SiloItemId`/`SiloPartNumber` properties on the active document.
|
|
|
|
|
|
|
|
|
|
### SDK (`mods/sdk/`)
|
|
|
|
|
|
|
|
|
|
Stable API contract for addons. Provides wrappers for editing contexts, theme tokens (Catppuccin Mocha YAML palette), FileOrigin registration, and deferred dock panels. Addons should use `kindred_sdk.*` instead of `FreeCADGui.*` internals where possible.
|
|
|
|
|
|
|
|
|
|
## Theme
|
|
|
|
|
|
|
|
|
|
- **Canonical source:** `src/Gui/Stylesheets/KindredCreate.qss`
|
|
|
|
|
- The PreferencePacks copy at `src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss` is **generated at build time** via `configure_file()`. Only edit the Stylesheets copy.
|
|
|
|
|
- Color palette: Catppuccin Mocha (26 colors + 14 semantic roles, defined in `mods/sdk/kindred_sdk/palettes/catppuccin-mocha.yaml`)
|
|
|
|
|
- Default preferences: `src/Gui/PreferencePacks/KindredCreate/KindredCreate.cfg`
|
|
|
|
|
|
|
|
|
|
## Git Conventions
|
|
|
|
|
|
|
|
|
|
### Branch Names
|
|
|
|
|
|
|
|
|
|
`type/kebab-case-description`
|
|
|
|
|
|
|
|
|
|
Types: `feat/`, `fix/`, `chore/`, `docs/`, `refactor/`, `art/`
|
|
|
|
|
|
|
|
|
|
### Commit Messages
|
|
|
|
|
|
|
|
|
|
[Conventional Commits](https://www.conventionalcommits.org/):
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
type(scope): lowercase imperative description
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
| Prefix | Purpose |
|
|
|
|
|
|--------|---------|
|
|
|
|
|
| `feat:` | New feature |
|
|
|
|
|
| `fix:` | Bug fix |
|
|
|
|
|
| `chore:` | Maintenance, dependencies |
|
|
|
|
|
| `docs:` | Documentation only |
|
|
|
|
|
| `art:` | Icons, theme, visual assets |
|
|
|
|
|
| `refactor:` | Code restructuring |
|
|
|
|
|
|
|
|
|
|
Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `ztools`, `silo`, `breadcrumb`, `gui`, `assembly`, `ci`, `theme`, `quicknav`, or omitted.
|
|
|
|
|
|
|
|
|
|
### PR Workflow
|
|
|
|
|
|
|
|
|
|
1. Create a branch from `main`: `git checkout -b feat/my-feature main`
|
|
|
|
|
2. Commit with conventional commit messages
|
|
|
|
|
3. Push and open a PR against `main` via Gitea (or `tea pulls create`)
|
|
|
|
|
4. CI runs automatically on PRs
|
|
|
|
|
|
|
|
|
|
### Code Style
|
|
|
|
|
|
|
|
|
|
- **C++:** clang-format (`.clang-format`), clang-tidy (`.clang-tidy`)
|
|
|
|
|
- **Python:** black (100-char line length), pylint (`.pylintrc`)
|
|
|
|
|
- **Pre-commit hooks:** `pre-commit install` (runs clang-format, black, trailing-whitespace, etc.)
|
|
|
|
|
|
|
|
|
|
## CI/CD
|
|
|
|
|
|
|
|
|
|
- **Build:** `.gitea/workflows/build.yml` — runs on pushes to `main` and on PRs
|
|
|
|
|
- **Release:** `.gitea/workflows/release.yml` — triggered by `v*` tags, builds AppImage and .deb
|
|
|
|
|
- **Platform:** Currently Linux x86_64 only in CI; other platforms have presets but no runners yet
|
|
|
|
|
|
|
|
|
|
## Documentation
|
|
|
|
|
|
|
|
|
|
| Document | Content |
|
|
|
|
|
|----------|---------|
|
|
|
|
|
| `README.md` | Project overview, installation, usage |
|
|
|
|
|
| `CONTRIBUTING.md` | Branch workflow, commit conventions, code style |
|
|
|
|
|
| `docs/ARCHITECTURE.md` | Bootstrap flow, addon lifecycle, source layout |
|
|
|
|
|
| `docs/COMPONENTS.md` | Feature inventory (ztools, Silo, origin, theme, icons) |
|
|
|
|
|
| `docs/KNOWN_ISSUES.md` | Known issues, incomplete features, next steps |
|
|
|
|
|
| `docs/INTEGRATION_PLAN.md` | 5-layer architecture, phase status |
|
|
|
|
|
| `docs/CI_CD.md` | Build and release workflows |
|
|
|
|
|
| `docs/KC_SPECIFICATION.md` | .kc file format specification |
|
|
|
|
|
| `docs/UPSTREAM.md` | FreeCAD upstream merge strategy |
|
|
|
|
|
| `docs/INTER_SOLVER.md` | Assembly solver integration |
|
|
|
|
|
| `docs/BOM_MERGE.md` | BOM-Assembly bridge specification |
|
|
|
|
|
|
|
|
|
|
The `docs/src/` directory contains an mdBook site with detailed guides organized by topic (architecture, development, guide, reference, silo-server, solver).
|
|
|
|
|
|
|
|
|
|
## Issue Tracker
|
|
|
|
|
|
|
|
|
|
Issues are tracked on Gitea at `git.kindred-systems.com/kindred/create/issues`. Use the `tea` CLI for local interaction:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
tea issues # List open issues
|
|
|
|
|
tea issues 123 # View issue #123 details
|
|
|
|
|
tea pulls create # Create a PR
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Known Issues and Pitfalls
|
|
|
|
|
|
|
|
|
|
1. **Silo auth not production-hardened** — LDAP/OIDC backends are coded but need infrastructure deployment
|
|
|
|
|
2. **No unit tests** for ztools/Silo FreeCAD commands or Go backend
|
|
|
|
|
3. **Assembly solver datum handling is minimal** — joints referencing datum planes/points may produce incorrect placement
|
|
|
|
|
4. **PartDesign menu insertion fragility** — `_ZToolsPartDesignManipulator.modifyMenuBar()` inserts after `PartDesign_Boolean`; upstream renames break silently
|
|
|
|
|
5. **`Silo_BOM` requires Silo-tracked document** — unregistered documents show a warning with no registration path
|
|
|
|
|
6. **QSS edits** — only edit `src/Gui/Stylesheets/KindredCreate.qss`; the PreferencePacks copy is auto-generated
|
