mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-08-21 14:23:26 +00:00
4359b4bfe9
Pin the server and UI client to the installed beta runtime and reject mismatched CLI versions before shared-service startup. Delegate proven shared-service shutdown to Service.stop while retaining CodeNomad lease, peer, registration, endpoint, and process-identity checks. Adopt native Forms and the client/solid data reducer for live messages, tools, permissions, and input forms. Propagate internal stream generations into authoritative reconnect reconciliation and replace directory-wide session scans with native project cursor pagination. Fail worktree deletion when session evacuation fails and deduplicate canonical workspace folders instead of exposing non-isolated duplicate instances. Update migration notes and CI coverage for the reviewed contract. Validated with server/UI/Electron typechecks, 244 UI partition tests, 122 Electron native tests, 248 server tests plus 3 platform skips (the sole Windows cleanup race passed in isolation), UI/server/Electron builds, Tauri cargo check --locked, and git diff --check.
176 lines
5.6 KiB
Markdown
176 lines
5.6 KiB
Markdown
# CodeNomad - Project Summary
|
|
|
|
## Current Status
|
|
|
|
The MVP and multi-instance milestones are complete. Current architecture and implementation details live in the documents indexed below.
|
|
|
|
## What We've Created
|
|
|
|
Development documentation for the CodeNomad desktop application.
|
|
|
|
## Directory Structure
|
|
|
|
```text
|
|
packages/server/ Fastify control API and shared OpenCode service
|
|
packages/ui/ SolidJS UI and native Promise clients
|
|
packages/electron-app Electron host
|
|
packages/tauri-app/ Tauri host
|
|
dev-docs/ Development documentation
|
|
```
|
|
|
|
## Documentation Overview
|
|
|
|
### 1. Architecture (architecture.md)
|
|
|
|
**What it covers:**
|
|
|
|
- High-level system design
|
|
- Component layers (Main process, Renderer, Communication)
|
|
- State management approach
|
|
- Tab hierarchy (Instance tabs → Session tabs)
|
|
- Data flow for key operations
|
|
- Technology stack decisions
|
|
- Security considerations
|
|
|
|
**Key sections:**
|
|
|
|
- Component architecture diagram
|
|
- Instance/Session state structures
|
|
- Communication patterns (HTTP, SSE)
|
|
- Error handling strategies
|
|
- Performance considerations
|
|
|
|
### 2. User Interface (user-interface.md)
|
|
|
|
**What it covers:**
|
|
|
|
- Complete UI layout specifications
|
|
- Visual design for every component
|
|
- Interaction patterns
|
|
- Keyboard shortcuts
|
|
- Accessibility requirements
|
|
- Empty states and error states
|
|
- Modal designs
|
|
|
|
**Key sections:**
|
|
|
|
- Detailed layout wireframes (ASCII art)
|
|
- Component-by-component specifications
|
|
- Message rendering formats
|
|
- Control bar designs
|
|
- Modal/overlay specifications
|
|
- Color schemes and typography
|
|
|
|
### 3. Technical Implementation (technical-implementation.md)
|
|
|
|
**What it covers:**
|
|
|
|
- Technology stack details
|
|
- Project file structure
|
|
- State management patterns
|
|
- Shared OpenCode service and location ownership
|
|
- Native `@opencode-ai/client` integration
|
|
- `/api/events` multiplexing
|
|
- IPC communication
|
|
- Error handling strategies
|
|
- Performance optimizations
|
|
|
|
**Key sections:**
|
|
|
|
- Complete project structure
|
|
- TypeScript interfaces
|
|
- Hardened shared-service proof and location lifecycle
|
|
- Native Promise client management
|
|
- Message rendering implementation
|
|
- Build and packaging config
|
|
|
|
## Key Design Decisions
|
|
|
|
### 1. Two-Level Tabs
|
|
|
|
- **Level 1**: Instance tabs (one per project folder)
|
|
- **Level 2**: Session tabs (multiple per instance)
|
|
- Allows working on multiple projects with multiple conversations each
|
|
|
|
### 2. Shared Service Management
|
|
|
|
- CodeNomad server discovers or launches one service through its hardened lifecycle; production does not call `Service.ensure`/`Service.stop` directly
|
|
- Workspace folders become validated native locations
|
|
- UI traffic stays behind the CodeNomad proxy
|
|
- Shutdown transfers proof to a live peer or stops only the exact proven daemon when no peer remains
|
|
|
|
### 3. One Shared Service, Location-Scoped Clients
|
|
|
|
- One proven shared endpoint serves all workspace locations
|
|
- UI clients route through `/workspaces/:id/instance/api/*`
|
|
- Server-side directory and session ownership prevents cross-contamination
|
|
|
|
### 4. SolidJS for Reactivity
|
|
|
|
- Fine-grained reactivity for SSE updates
|
|
- No re-render cascades
|
|
- Better performance for real-time updates
|
|
- Smaller bundle size than React
|
|
|
|
### 5. No Virtual Scrolling or Performance Optimization in MVP
|
|
|
|
- Start with simple list rendering
|
|
- Don't optimize for large sessions initially
|
|
- Focus on functionality, not performance
|
|
- Add optimizations in post-MVP phases if needed
|
|
- Reduces initial complexity and speeds up development
|
|
|
|
### 6. Messages and Tool Calls Inline
|
|
|
|
- All activity shows in main message stream
|
|
- Tool calls expandable/collapsible
|
|
- File changes visible inline
|
|
- Single timeline view
|
|
|
|
## Implementation Guidelines
|
|
|
|
### Code Standards:
|
|
|
|
- TypeScript for everything
|
|
- No `any` types
|
|
- Descriptive variable names
|
|
- Comments for complex logic
|
|
- Error handling on all async operations
|
|
- Loading states for all network calls
|
|
|
|
### Testing Approach:
|
|
|
|
- Manual testing at each step
|
|
- Test on minimum window size (800x600)
|
|
- Test error cases
|
|
- Test edge cases (long text, special chars)
|
|
- Keyboard navigation verification
|
|
|
|
## Useful References
|
|
|
|
### Within This Project:
|
|
|
|
- `README.md` - Project overview and getting started
|
|
- `dev-docs/architecture.md` - System design
|
|
- `dev-docs/user-interface.md` - UI specifications
|
|
- `dev-docs/technical-implementation.md` - Implementation details
|
|
|
|
### External:
|
|
|
|
- OpenCode server API: https://opencode.ai/docs/server/
|
|
- Electron docs: https://electronjs.org/docs
|
|
- SolidJS docs: https://solidjs.com
|
|
- Kobalte UI: https://kobalte.dev
|
|
|
|
## Current OpenCode Baseline
|
|
|
|
- Experimental protocol client: server, UI, and the runtime `opencode2` CLI use the exact version pinned in the server package; every upgrade reviews release notes, current documentation, installed declarations, and proxy/API parity
|
|
- Service: one shared endpoint managed by CodeNomad's lease-locked process-proof lifecycle
|
|
- Workspaces: native locations/directories
|
|
- Database: V2 always uses `~/.local/share/opencode2/opencode.db`, separate from V1
|
|
- Events: volatile native stream with authoritative reconnect reconciliation
|
|
- Proxy: explicit method/path allowlist; upstream additions are not automatic
|
|
- Shell and instructions: native session APIs, separate from PTY management
|
|
- PTYs: location-scoped native entries in Status, refreshed on PTY events/reconnect with metadata, title updates, and ownership-checked removal; current installed declarations have no output/read/stream or separate stop API, so output and distinct stop are unavailable and removal stops a running PTY
|
|
- Legacy plugin/background processes: `packages/opencode-plugin` and server plugin/background-process paths remain deleted
|
|
- Git mutations and Yolo: CodeNomad-owned
|