From 5336cde0de852ad42b06a598b9ff663a754597c6 Mon Sep 17 00:00:00 2001 From: forbes Date: Tue, 3 Mar 2026 13:42:20 -0600 Subject: [PATCH] docs: update CLAUDE.md with current repository context MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update project overview: five addon modules, KCSDK C++ layer - Add KCSDK C++ architecture section (SDK/, IPanelProvider, ThemeEngine, etc.) - Update repository structure tree (SDK/, datums, gears, reference/ for archived addons) - Update addon load order: sdk(0) → solver(10) → gears(40) → datums(45) → silo(60) - Update deferred init: Create core now only handles kc_format + update checker - Add detailed Gears, Datums, Solver addon module descriptions - Update Silo section to reflect self-contained deferred setup - Replace ztools/quicknav references with datums/gears/sdk throughout - Update submodules table (remove archived, add gears/datums) - Update commit scopes list - Update known issues (remove stale ztools references, add archived addons note) - Point editing context and origin APIs to kindred_sdk wrappers --- CLAUDE.md | 132 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 35 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 584bc7119a..3607076450 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ ## 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 is a fork of FreeCAD 1.0+ that adds integrated tooling for professional engineering workflows. It ships a context-aware UI system, five addon modules (SDK, Gears, Datums, Silo, Solver), a KCSDK C++ extension layer, 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 @@ -33,6 +33,14 @@ create/ │ ├── App/ Core application (C++) │ ├── Base/ Base classes, type system, persistence (C++) │ ├── Gui/ GUI framework (C++) +│ │ ├── SDK/ KCSDK C++ library (Kindred feature) +│ │ │ ├── bindings/ pybind11 module (kcsdk.so) +│ │ │ ├── IPanelProvider.h Dock panel interface +│ │ │ ├── IToolbarProvider.h Toolbar interface +│ │ │ ├── IMenuProvider.h Menu interface +│ │ │ ├── SDKRegistry.h Provider registry +│ │ │ ├── ThemeEngine.h Runtime theme token access +│ │ │ └── WidgetBridge.h Qt widget creation bridge │ │ ├── EditingContext.h Editing context resolver (Kindred feature) │ │ ├── BreadcrumbToolBar.h Breadcrumb navigation widget (Kindred feature) │ │ ├── FileOrigin.h Abstract origin interface (Kindred feature) @@ -44,20 +52,30 @@ create/ │ │ └── PreferencePacks/ Preference configurations (build-time generated) │ ├── Mod/ FreeCAD modules (PartDesign, Assembly, Sketcher, etc.) │ │ └── Create/ Kindred Create module +│ │ ├── App/ C++ app-side module (AppCreate) +│ │ ├── Gui/ C++ GUI-side module (AppCreateGui) │ │ ├── Init.py Console bootstrap — loads addons -│ │ ├── InitGui.py GUI bootstrap — loads addons, Silo setup, update checker +│ │ ├── InitGui.py GUI bootstrap — loads addons, kc_format, update checker │ │ ├── addon_loader.py Manifest-driven loader with dependency resolution -│ │ └── kc_format.py .kc file format preservation +│ │ ├── kc_format.py .kc file format preservation +│ │ ├── silo_document.py .kc tree building observer +│ │ ├── silo_tree.py Silo metadata tree builder +│ │ ├── silo_objects.py Silo tree FeaturePython objects +│ │ ├── silo_viewers.py Silo tree MDI viewers +│ │ └── silo_viewproviders.py Silo tree ViewProvider icons │ └── 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) +│ ├── gears/ [submodule] Parametric gear workbench (priority 40) +│ ├── datums/ [submodule] Unified datum creator (priority 45) │ ├── silo/ [submodule] PLM workbench (priority 60) -│ ├── solver/ [submodule] Assembly solver research (GNN-based) -│ └── quicknav/ [submodule] Navigation addon +│ └── solver/ [submodule] Assembly solver research (priority 10) +├── reference/ Archived addons (not built) +│ ├── ztools/ Archived — commands migrated to datums + core +│ └── quicknav/ Archived — navigation addon ├── docs/ mdBook documentation + architecture docs ├── tests/ C++ unit tests (GoogleTest) ├── package/ Packaging (debian/, rattler-build/) @@ -110,6 +128,19 @@ if (obj->isDerivedFrom(type)) { ... } 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. +### KCSDK C++ Layer + +The `src/Gui/SDK/` directory provides a C++ shared library (`libKCSDK`) with pybind11 bindings (`kcsdk` Python module). This is the stable C++ API for Kindred features: + +- **`IPanelProvider`** — interface for registering dock panels +- **`IToolbarProvider`** — interface for toolbar registration +- **`IMenuProvider`** — interface for menu registration +- **`SDKRegistry`** — central registry for all providers +- **`ThemeEngine`** — runtime access to Catppuccin Mocha theme tokens +- **`WidgetBridge`** — Qt widget creation from Python factories + +Python addons access these through `kindred_sdk.*` wrappers (e.g., `kindred_sdk.register_dock_panel()` routes through `kcsdk.register_panel()` + `kcsdk.create_panel()`). Do not use `kcsdk` directly from addons — always use `kindred_sdk`. + ### 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. @@ -122,42 +153,49 @@ The `EditingContextResolver` singleton (`src/Gui/EditingContext.h/.cpp`) drives 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 +Python API (prefer `kindred_sdk` wrappers over direct `FreeCADGui` calls): +- `kindred_sdk.register_context()` — register a new context +- `kindred_sdk.register_overlay()` — conditional toolbar overlay +- `kindred_sdk.inject_commands()` — add commands to existing contexts +- `kindred_sdk.current_context()` — query active context +- `kindred_sdk.refresh_context()` — force re-evaluation ### Addon Loading -Addons in `mods/` are loaded by `src/Mod/Create/addon_loader.py`. Each addon provides a `package.xml` with `` extensions declaring version bounds, load priority, and dependencies. The loader resolves via topological sort: **sdk** (0) -> **ztools** (50) -> **silo** (60). +Addons in `mods/` are loaded by `src/Mod/Create/addon_loader.py`. Each addon provides a `package.xml` at the mod root with `` extensions declaring version bounds, load priority, and dependencies. The loader discovers manifests, validates version bounds, and resolves load order via topological sort on dependencies, breaking ties by `(load_priority, name)`. -A `` tag in `package.xml` is required for `InitGui.py` to be loaded, even if no actual workbench is registered. +Current load order: **sdk** (0) → **solver** (10) → **gears** (40) → **datums** (45) → **silo** (60). + +A `` tag in `package.xml` is required for `InitGui.py` to be loaded, even if no actual workbench is registered. The `` element within `` specifies where `Init.py`/`InitGui.py` live relative to the mod root (e.g., `freecad` for silo, `datums` for datums, `./` for sdk). ### Deferred Initialization -GUI setup uses `QTimer.singleShot` with staggered delays: +GUI setup uses `QTimer.singleShot` with staggered delays. Create core (`src/Mod/Create/InitGui.py`) handles: - 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 +Each addon manages its own deferred setup in its `InitGui.py`. For example, Silo (`mods/silo/InitGui.py`) defers: +- 500ms: kindred:// URL handler +- 600ms: Document observer for .kc tree building +- 2000ms: Auth dock panel (via `kindred_sdk.register_dock_panel`) +- 2500ms: Silo overlay context +- 3000ms: First-start settings check +- 4000ms: Activity dock panel (via `kindred_sdk.register_dock_panel`) + ### 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`). +Origins are registered via `kindred_sdk.register_origin()`. Query functions (`list_origins`, `active_origin`, `get_origin`, `set_active_origin`) route through the `kcsdk` C++ module. + ## 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/gears` | `git.kindred-systems.com/kindred/gears` | `main` | Parametric gear generation workbench | +| `mods/datums` | `git.kindred-systems.com/kindred/datums` | `main` | Unified datum creator (plane, axis, point) | | `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 | @@ -176,29 +214,53 @@ Initialize all submodules: `git submodule update --init --recursive` ## Key Addon Modules -### ztools (`mods/ztools/`) +### SDK (`mods/sdk/`) -Command provider (NOT a workbench). Injects tools into PartDesign, Assembly, and Spreadsheet contexts via `_ZToolsManipulator` (WorkbenchManipulator) and `injectEditingCommands()`. +Stable API contract for addons. Python package `kindred_sdk` wraps the KCSDK C++ module, providing: +- **Editing contexts:** `register_context()`, `register_overlay()`, `inject_commands()`, `refresh_context()` +- **Origins:** `register_origin()`, `unregister_origin()`, `list_origins()`, `active_origin()` +- **Dock panels:** `register_dock_panel(object_name, title, factory, area, delay_ms)` +- **Commands:** `register_command(cmd_id, classname, pixmap, tooltip)` +- **Theme:** `get_theme_tokens()`, `load_palette()` (Catppuccin Mocha YAML palette) +- **Toolbars/Menus:** `register_toolbar()`, `register_menu()` +- **Version:** `create_version()`, `freecad_version()` -Commands: `ZTools_DatumCreator`, `ZTools_EnhancedPocket`, `ZTools_RotatedLinearPattern`, `ZTools_AssemblyLinearPattern`, `ZTools_AssemblyPolarPattern`, spreadsheet formatting (Bold, Italic, Underline, alignment, colors, QuickAlias). +Addons should use `kindred_sdk.*` instead of `FreeCADGui.*` internals where possible. -Source: `mods/ztools/ztools/ztools/commands/` (note the double `ztools` nesting). +### Gears (`mods/gears/`) + +Parametric gear workbench. Provides `GearWorkbench` with gear generation and analysis tools. Code lives in `freecad/gears/` (workbench) and `pygears/` (computational library). Priority 40, depends on SDK. + +### Datums (`mods/datums/`) + +Unified datum creator that replaces the three stock PartDesign datum commands (Plane, Line, Point) with a single `Create_DatumCreator` command. Features: +- 16 smart creation modes (7 plane, 4 axis, 5 point) +- Auto-detection engine: selects best mode from geometry selection +- Mode override combo for manual selection +- Dynamic parameter UI (offset, angle, position, XYZ) +- Edit panel with real-time parameter updates via AttachExtension +- Injected into `partdesign.body` and `partdesign.feature` contexts via SDK + +Source: `mods/datums/datums/` (command.py, core.py, panel.py, detection.py, edit_panel.py). Priority 45, depends on SDK. ### 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. +Structure: root-level `package.xml`/`Init.py`/`InitGui.py`, workbench code in `freecad/`, client library in `silo-client/`. All deferred setup (origin, overlay, dock panels, document observer) is self-contained in `mods/silo/InitGui.py`. -### SDK (`mods/sdk/`) +Silo origin detection: `silo_origin.py:ownsDocument()` checks for `SiloItemId`/`SiloPartNumber` properties on the active document. Origin registered via `kindred_sdk.register_origin()`. -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. +### Solver (`mods/solver/`) + +Assembly solver research addon (GNN-based). Pure Python, priority 10. Provides `KindredSolverBackend` for experimental assembly constraint solving. ## 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`) +- Runtime access: `kindred_sdk.get_theme_tokens()` returns palette dict; C++ side via `ThemeEngine` in `src/Gui/SDK/` - Default preferences: `src/Gui/PreferencePacks/KindredCreate/KindredCreate.cfg` ## Git Conventions @@ -226,7 +288,7 @@ type(scope): lowercase imperative description | `art:` | Icons, theme, visual assets | | `refactor:` | Code restructuring | -Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `ztools`, `silo`, `breadcrumb`, `gui`, `assembly`, `ci`, `theme`, `quicknav`, or omitted. +Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `datums`, `silo`, `gears`, `sdk`, `breadcrumb`, `gui`, `assembly`, `ci`, `theme`, or omitted. ### PR Workflow @@ -254,7 +316,7 @@ Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `ztools`, `silo`, `b | `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/COMPONENTS.md` | Feature inventory (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 | @@ -278,8 +340,8 @@ 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 +2. **No unit tests** for 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 +4. **`Silo_BOM` requires Silo-tracked document** — unregistered documents show a warning with no registration path +5. **QSS edits** — only edit `src/Gui/Stylesheets/KindredCreate.qss`; the PreferencePacks copy is auto-generated +6. **Archived addons** — `reference/ztools/` and `reference/quicknav/` are archived source for reference only; they are not built or loaded -- 2.49.1