feat: Complete GPUI desktop application migration

.cargo/config.toml

@@ -44,7 +44,7 @@ linker = "riscv64-linux-gnu-gcc"
 # Build configuration
 [build]
 # Default target for builds
-target = "x86_64-unknown-linux-gnu"
+# target = "x86_64-unknown-linux-gnu"
 
 # Cross-compilation settings (commented out - let cross-rs handle Docker images)
 # The cross-rs tool automatically manages Docker images for cross-compilation

.claude/commands/scaffold-crate.md

@@ -0,0 +1,59 @@
+---
+description: Generate Rust crate scaffold with tests, types, and docs
+argument-hint: <crate-name>
+---
+# Scaffold Crate: $ARGUMENTS
+
+1. Create crate directory: `crates/terraphim_$ARGUMENTS/`
+
+2. **Generate Core Files:**
+
+```
+crates/terraphim_$ARGUMENTS/
+├── Cargo.toml          # Crate manifest
+├── src/
+│   ├── lib.rs          # Main library entry
+│   ├── error.rs        # Error types (thiserror)
+│   ├── types.rs        # Type definitions
+│   └── tests.rs        # Unit tests module
+└── README.md           # Crate documentation
+```
+
+3. **Cargo.toml Template:**
+- Edition 2024
+- Workspace dependencies inheritance
+- Feature flags for optional functionality
+- Dev dependencies for testing
+
+4. **Library Template (lib.rs):**
+- Module declarations with rustdoc
+- Public API exports
+- Error type re-exports
+- `#[cfg(test)]` test module
+
+5. **Error Handling (error.rs):**
+- Custom error enum with `thiserror`
+- `Result<T>` type alias
+- Error conversion traits
+
+6. **Test Template (tests.rs):**
+- `#[tokio::test]` for async tests
+- Integration test structure
+- No mocks - real implementations only
+- Feature-gated live tests with `#[ignore]`
+
+7. **Documentation:**
+- Crate-level rustdoc in `lib.rs`
+- README.md with:
+  - Crate overview
+  - Usage examples
+  - Configuration options
+  - API reference link
+
+8. **Workspace Integration:**
+- Add to `Cargo.toml` workspace members
+- Update dependent crates if needed
+
+9. **Git Integration:**
+- Stage all files: `git add crates/terraphim_$ARGUMENTS/`
+- Create feature branch: `git checkout -b feature/$ARGUMENTS`

.docs/phase1-research-gpui-desktop-test-health.md

@@ -0,0 +1,106 @@
+# Research Document: GPUI Desktop Test/Build Health
+
+## 1. Problem Restatement and Scope
+`cargo test -p terraphim_desktop_gpui` currently fails to compile and therefore cannot be used to confirm that the GPUI desktop crate is healthy.
+
+Observed failure modes (from a local `cargo test -p terraphim_desktop_gpui` run):
+- The test suite references public API items that do not exist (e.g., `terraphim_desktop_gpui::components`, `terraphim_desktop_gpui::rolegraph`, `views::search::SearchComponent`).
+- There is at least one hard syntax error in a test file (`crates/terraphim_desktop_gpui/tests/ui_test_runner.rs`) that prevents compilation.
+- Some tests import `ContextManager` from `terraphim_service::context`, but the service module appears to expose `TerraphimContextManager` (or a differently named type), causing unresolved import errors.
+
+IN SCOPE
+- Restoring a consistent contract between `crates/terraphim_desktop_gpui` public exports and the tests under `crates/terraphim_desktop_gpui/tests`.
+- Fixing compile errors in tests and crate exports so `cargo test -p terraphim_desktop_gpui` compiles and runs.
+- Determining which tests are “current” vs “legacy”, and adding clear gating (feature flags or module organization) so the test suite reflects the intended product state.
+
+OUT OF SCOPE
+- Implementing new GPUI features unrelated to test/build health.
+- Large-scale refactors of GPUI UI/UX.
+- Changing behavior of backend services beyond what’s required for API compatibility.
+
+## 2. User & Business Outcomes
+- Engineers can run a single command (`cargo test -p terraphim_desktop_gpui`) to verify GPUI desktop health.
+- Reduced uncertainty: the test suite reflects the current architecture (GPUI views + state modules), not a previously drafted component framework.
+- Faster iteration: fewer “paper tests” that fail due to stale imports and missing exports.
+
+## 3. System Elements and Dependencies
+Key elements involved in the failure:
+
+- `crates/terraphim_desktop_gpui/src/lib.rs`
+  - Defines the crate’s public module surface.
+  - Currently has `pub mod components;` commented out, which makes `terraphim_desktop_gpui::components` missing at the crate root.
+
+- `crates/terraphim_desktop_gpui/src/components/mod.rs`
+  - Exists and defines a “reusable components” architecture.
+  - Many submodules and re-exports are commented out (e.g., `testing`, `knowledge_graph`, `kg_search_modal`, etc.).
+  - This suggests the components system is intentionally disabled or partially incomplete.
+
+- `crates/terraphim_desktop_gpui/src/views/search/mod.rs`
+  - Provides GPUI-native view types like `SearchView`, and exports `SearchInput`, `SearchResults`, `TermChips`.
+  - Does NOT provide `SearchComponent`/`SearchComponentConfig` referenced by tests.
+
+- `crates/terraphim_desktop_gpui/tests/*.rs`
+  - Many tests reference the disabled “components” and other types that aren’t exported.
+  - At least one file contains a syntax error (type parameter parsing error) that blocks compilation.
+
+- `crates/terraphim_service/src/context.rs`
+  - Provides a context manager type named `TerraphimContextManager`.
+  - Some GPUI desktop tests expect `ContextManager` to exist in this module.
+
+External dependencies impacting build/test:
+- `gpui`, `gpui-component`, macOS platform integration crates.
+
+## 4. Constraints and Their Implications
+- Must compile and run on macOS (darwin).
+  - Many GPUI dependencies are platform-specific; tests should avoid requiring a full UI runtime unless explicitly intended.
+
+- “No mocks in tests” constraint.
+  - Tests that define `MockServiceRegistry` (seen in `crates/terraphim_desktop_gpui/tests/ui_integration_tests.rs`) are likely non-compliant with repository policy.
+  - We need to clarify whether this policy applies to this crate’s tests, or if these tests should be refactored to use real in-memory implementations.
+
+- Keep scope disciplined.
+  - The fastest path to “everything works correctly” is to ensure the crate exports and the test suite align with the current architecture, not to resurrect an entire legacy component system.
+
+- Stability vs breadth.
+  - Re-enabling `components` wholesale may balloon compile surface and introduce more failures.
+  - Feature-gating legacy components/tests may reduce blast radius while still letting the main crate test suite pass.
+
+## 5. Risks, Unknowns, and Assumptions
+UNKNOWNS
+- Which test files are authoritative for current GPUI desktop behavior vs experimental/legacy.
+- Why `components` was disabled in `src/lib.rs` (performance? compile breakages? ongoing migration?).
+- Whether the repository intends `ContextManager` to be a stable alias for `TerraphimContextManager`.
+- Whether CI expects these tests to run, or if they are local-only.
+
+ASSUMPTIONS
+- Primary health check is `cargo test -p terraphim_desktop_gpui` on macOS.
+- The “current” GPUI UI implementation is the `views/*` + `state/*` path, and the “reusable components” subsystem is not yet productized.
+
+RISKS
+- Re-enabling the components system could introduce cascading compile failures and slow builds.
+- Disabling tests without agreement could reduce coverage and hide regressions.
+- Renaming or aliasing service APIs (e.g., `ContextManager`) may affect other crates.
+
+De-risking steps (information gathering, not implementation):
+- Categorize tests into: (a) compile + logic tests for current code, (b) legacy components tests, (c) experimental visual/UI runner code.
+- Decide “definition of done” for ‘everything works’ (tests pass, build passes, app launches).
+
+## 6. Context Complexity vs. Simplicity Opportunities
+Current complexity drivers:
+- Two parallel architectures appear present:
+  - GPUI-aligned `views/*` + `state/*`.
+  - A legacy/experimental `components/*` system that is partially disabled.
+- Tests seem written against both (or against an earlier shape), creating broken contracts.
+
+Simplicity opportunities:
+- Establish one explicit public API surface for the crate (current GPUI views + state), and gate legacy components behind a feature flag.
+- Make tests mirror that same split:
+  - Default tests validate current architecture.
+  - Legacy tests run only under an opt-in feature.
+
+## 7. Questions for Human Reviewer
+1. What is the definition of “everything works correctly” here: `cargo test` only, or also `cargo run -p terraphim_desktop_gpui` (manual UI smoke test)?
+2. Should the `components/*` subsystem be considered legacy/experimental (feature-gated), or should it be restored as a first-class API?
+3. Is it acceptable to move/feature-gate tests that currently rely on `MockServiceRegistry` given the “never use mocks” rule?
+4. Do we want to preserve the older `ContextManager` name as an alias in `terraphim_service::context`, or should tests be updated to the new type name?
+5. Which subset of tests must pass to declare GPUI desktop “green” (unit/integration only, or also visual runners)?

.docs/phase1.5-quality-gpui-desktop-test-health.md

@@ -0,0 +1,87 @@
+# Document Quality Evaluation Report
+
+## Metadata
+- **Document**: `.docs/phase1-research-gpui-desktop-test-health.md`
+- **Type**: Phase 1 Research
+- **Evaluated**: 2026-01-19
+
+## Decision: GO
+
+**Average Score**: 4.0 / 5.0
+**Blocking Dimensions**: None
+
+## Dimension Scores
+
+| Dimension | Score | Status |
+|-----------|-------|--------|
+| Syntactic | 4/5 | Pass |
+| Semantic | 4/5 | Pass |
+| Pragmatic | 4/5 | Pass |
+| Social | 3/5 | Pass |
+| Physical | 5/5 | Pass |
+| Empirical | 4/5 | Pass |
+
+## Detailed Findings
+
+### Syntactic Quality (4/5)
+**Strengths:**
+- Clear IN/OUT scope separation (Section 1).
+- Consistent referencing of concrete files and symbols (Sections 3, 5).
+
+**Weaknesses:**
+- Some terms are used informally (e.g., “legacy”, “experimental”) without a crisp definition of each bucket (Section 6).
+
+**Suggested Revisions:**
+- [ ] Add explicit definitions for “current”, “legacy”, and “experimental” tests/modules.
+
+### Semantic Quality (4/5)
+**Strengths:**
+- Accurately reflects observed errors: missing crate exports, syntax error, service type mismatch (Sections 1, 3).
+
+**Weaknesses:**
+- The exact cause of the `ui_test_runner.rs` parse error isn’t described beyond the compiler output.
+
+**Suggested Revisions:**
+- [ ] Add a short note in Section 1 naming the likely local cause (broken generics bounds / missing `>` in a where clause) without proposing a fix.
+
+### Pragmatic Quality (4/5)
+**Strengths:**
+- Provides actionable next investigative steps and reviewer questions (Sections 5, 7).
+
+**Weaknesses:**
+- “No mocks in tests” conflict is identified but not scoped into a decision path (Section 4).
+
+**Suggested Revisions:**
+- [ ] Add a decision fork stating: either rewrite those tests to use real in-memory services, or feature-gate them as non-conforming until refactored.
+
+### Social Quality (3/5)
+**Strengths:**
+- Explicit reviewer questions reduce ambiguity (Section 7).
+
+**Weaknesses:**
+- Stakeholder intent around the components system is unknown; different readers may infer different priorities (Sections 3, 6).
+
+**Suggested Revisions:**
+- [ ] Add a one-line “decision needed” statement: whether `components` is part of the supported API for the next release.
+
+### Physical Quality (5/5)
+**Strengths:**
+- Follows the expected template and is easy to navigate.
+
+### Empirical Quality (4/5)
+**Strengths:**
+- Reasonable density; sections are scannable and not overly verbose.
+
+**Weaknesses:**
+- Section 3 could be slightly more tabular for readability.
+
+**Suggested Revisions:**
+- [ ] Optional: convert Section 3 into a small table.
+
+## Revision Checklist
+- [ ] Define “current/legacy/experimental” buckets explicitly.
+- [ ] Add a short semantic note about the nature of the `ui_test_runner.rs` parse error.
+- [ ] Add an explicit decision fork for the “no mocks” constraint in tests.
+
+## Next Steps
+- Proceed to Phase 2 (Design) once you approve the research document’s scope and the decision points in Section 7.

.docs/phase2-design-gpui-desktop-test-health.md

@@ -0,0 +1,81 @@
+# Design & Implementation Plan: Restore GPUI Desktop Test/Build Health
+
+## 1. Summary of Target Behavior
+After this change:
+- `cargo test -p terraphim_desktop_gpui` compiles and runs successfully on macOS.
+- The default test suite validates the *current* GPUI architecture (`views/*` + `state/*` + `search_service`, etc.).
+- Legacy/experimental tests and benchmark code that target the disabled `components/*` subsystem do not block default test runs.
+
+## 2. Key Invariants and Acceptance Criteria
+Invariants
+- No changes to end-user behavior are required to reach “green tests”; focus is build/test correctness.
+- Default test command must be stable: no optional features required, no manual steps.
+- Avoid introducing or expanding mock-based testing; tests should use real in-memory types where feasible.
+
+Acceptance Criteria
+- `cargo test -p terraphim_desktop_gpui` exits 0.
+- `cargo test -p terraphim_desktop_gpui --tests` exits 0.
+- `cargo build -p terraphim_desktop_gpui` exits 0.
+
+## 3. High-Level Design and Boundaries
+Boundary decision: split the crate/test surface into two explicit layers.
+
+- “Current GPUI App Surface” (default)
+  - Crate exports: `app`, `views`, `state`, `search_service`, `slash_command`, `markdown`, etc.
+  - Tests: should import these modules and exercise real behavior.
+
+- “Legacy Reusable Components” (opt-in)
+  - Crate exports: `components` (and its dependent submodules) behind a feature flag, OR kept internal.
+  - Tests: any tests that reference `terraphim_desktop_gpui::components::*` are moved behind the same feature, or are rewritten to use the current surface.
+
+We do NOT attempt to fully revive all commented-out submodules in `crates/terraphim_desktop_gpui/src/components/mod.rs` unless explicitly required.
+
+## 4. File/Module-Level Change Plan
+
+| File/Module | Action | Before | After | Dependencies |
+|---|---|---|---|---|
+| `crates/terraphim_desktop_gpui/src/lib.rs` | Modify | `components` disabled at crate root | Add feature-gated export: `#[cfg(feature = "legacy-components")] pub mod components;` (or keep disabled and gate tests) | Cargo features |
+| `crates/terraphim_desktop_gpui/Cargo.toml` | Modify | No explicit test/legacy feature split | Add `legacy-components` feature; optionally add `legacy-benches` feature | Cargo features |
+| `crates/terraphim_desktop_gpui/tests/ui_test_runner.rs` | Fix | Syntax error prevents compilation | Fix the generics/where-clause syntax so tests compile | Rust syntax |
+| `crates/terraphim_desktop_gpui/tests/*components*_tests.rs` | Modify | Imports `terraphim_desktop_gpui::components` (missing) | Either (A) gate entire file with `#![cfg(feature = "legacy-components")]` or (B) rewrite tests to current surface | Feature gating decision |
+| `crates/terraphim_desktop_gpui/tests/*journey*test*.rs` | Modify | Imports `ContextManager` from `terraphim_service::context` (missing) | Update imports to `TerraphimContextManager` OR add a compatibility `pub type ContextManager = TerraphimContextManager;` in `terraphim_service::context` | Cross-crate API |
+| `crates/terraphim_desktop_gpui/benches/*` | Modify | Bench files contain compile errors; benches might be built by some workflows | Gate benches behind feature OR fix them; ensure default `cargo test` not impacted | Criterion, types |
+
+## 5. Step-by-Step Implementation Sequence
+1. Establish intended “default surface” and “legacy surface” in code via Cargo features.
+2. Fix the hard syntax error in `crates/terraphim_desktop_gpui/tests/ui_test_runner.rs` so the test crate can compile.
+3. Resolve the `ContextManager` naming mismatch:
+   - Preferred: add a backward-compatible alias in `crates/terraphim_service/src/context.rs`.
+   - Alternative: update all tests to the new type name.
+4. Make `components` tests non-blocking:
+   - Option A (fastest, smallest blast radius): gate those tests behind `legacy-components`.
+   - Option B (more coverage now): re-export `components` from crate root and ensure minimal required submodules compile; gate the rest.
+5. Resolve `views::search::SearchComponent` mismatches:
+   - Either gate tests that reference `SearchComponent`, or update them to use `SearchView` (current API).
+6. Run verification commands:
+   - `cargo build -p terraphim_desktop_gpui`
+   - `cargo test -p terraphim_desktop_gpui`
+   - If legacy tests are kept: `cargo test -p terraphim_desktop_gpui --features legacy-components` (optional).
+
+## 6. Testing & Verification Strategy
+
+| Acceptance Criteria | Test Type | Test Location |
+|---|---|---|
+| `cargo test -p terraphim_desktop_gpui` passes | Build + integration | `crates/terraphim_desktop_gpui/tests/*.rs` (default set) |
+| Current search view compiles and links | Build | `crates/terraphim_desktop_gpui/src/views/search/mod.rs` |
+| Context flow tests use correct service type | Integration | `crates/terraphim_desktop_gpui/tests/complete_user_journey_test.rs`, `crates/terraphim_desktop_gpui/tests/end_to_end_flow_test.rs` |
+| Legacy components tests do not block default run | Build gate | `#![cfg(feature = "legacy-components")]` on legacy files |
+
+## 7. Risk & Complexity Review
+
+| Risk | Mitigation | Residual Risk |
+|---|---|---|
+| Feature-gating hides tests | Keep an explicit opt-in `legacy-components` test run documented; add CI later if desired | Some drift possible |
+| Re-exporting `components` increases compile surface | Prefer gating tests first; only re-export when needed | Potential new compile errors |
+| “No mocks in tests” conflict | Refactor mock registry tests to use real in-memory registry implementations OR gate them as legacy | May require more work to keep coverage |
+| Cross-crate alias impacts others | Use a type alias only; avoid behavior change | Low |
+
+## 8. Open Questions / Decisions for Human Review
+1. Should `components` be restored as a supported API now, or treated as `legacy-components` feature-only?
+2. Are we allowed to add `pub type ContextManager = TerraphimContextManager;` for backwards compatibility in `crates/terraphim_service/src/context.rs`?
+3. For “everything works”: is passing `cargo test -p terraphim_desktop_gpui` sufficient, or do you also want a manual `cargo run -p terraphim_desktop_gpui` smoke test?