diff --git a/.gitignore b/.gitignore index 4b86a52..539f8c9 100644 --- a/.gitignore +++ b/.gitignore @@ -3,11 +3,13 @@ OLD # Generated by Cargo # will have compiled files and executables debug/ -target/ +target +distribution /dist/ # Claude Code session files .coder/ +.claude # Generated documentation /target/doc/ diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index fccf490..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,424 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Quick Start Commands - -### Build & Verification -```bash -just check-all # Complete verification: fmt + lint + check + test + audit -just check # cargo check --all -just build # cargo build --all -just build-release # cargo build --release -``` - -### Testing -```bash -just test # All library tests (632+ tests) -just test-all # Library + integration tests -just test-verbose # Tests with output and logging -just test-watch # Continuous testing on file changes -cargo test -p # Test specific crate (e.g., cargo test -p syntaxis-core) -``` - -### Code Quality -```bash -just fmt # Format code (cargo fmt) -just lint # Lint with clippy -just lint-pedantic # Lint with pedantic warnings -just audit # Security audit -``` - -### Running Applications -```bash -just run-cli [ARGS] # Run syntaxis CLI tool -just run-tui # Run TUI application -just run-api # Run REST API server (port 3000) with Leptos dashboard -just dev-dashboard # Dev server for Leptos dashboard (port 8080, proxies API) -just build-dashboard # Build Leptos WASM dashboard -just check-dashboard-tools # Check if dashboard prerequisites installed -``` - -### Installation with Presets - -Enhanced installer with intelligent preset selection and optional provctl integration: - -```bash -# Simple local installation (default) -nu scripts/provisioning/install-with-presets.nu - -# Install with specific preset -nu scripts/provisioning/install-with-presets.nu --preset dev -nu scripts/provisioning/install-with-presets.nu --preset staging -nu scripts/provisioning/install-with-presets.nu --preset production - -# Interactive mode (will ask questions) -nu scripts/provisioning/install-with-presets.nu --interactive - -# Generate configuration file -nu scripts/provisioning/install-with-presets.nu --preset dev --generate-config > my-install.toml - -# Install from configuration file -nu scripts/provisioning/install-with-presets.nu --config my-install.toml - -# Detect provctl availability -nu scripts/provisioning/detect-provctl.nu --verbose - -# Manage services with provctl -nu scripts/provisioning/provctl-services.nu list local -nu scripts/provisioning/provctl-services.nu deploy dev -nu scripts/provisioning/provctl-services.nu start surrealdb -nu scripts/provisioning/provctl-services.nu status -``` - -**Installation Presets:** - -| Preset | Use Case | Database | Services | provctl | -|--------|----------|----------|----------|---------| -| `local` | Solo development | SQLite | None | ❌ Not needed | -| `dev` | Full-stack dev | SurrealDB (server) | API, Dashboard, NATS | ✅ Recommended | -| `staging` | CI/CD, teams | SurrealDB (docker) | All + monitoring | ✅ Recommended | -| `production` | Enterprise | SurrealDB (K8s) | All + HA | ❌ K8s manages | - -**Configuration:** -- All presets defined in `configs/installation.toml` -- Service definitions in `configs/provisioning/services/` -- Documentation in `docs/INSTALLATION_CONTEXTS.md` - -**Features:** -- ✅ Automatic provctl detection and optional integration -- ✅ Declarative configuration files -- ✅ Service management (start, stop, status, deploy) -- ✅ Interactive guided installation -- ✅ Graceful fallback when provctl unavailable -- ✅ Health checks for services - -## Architecture Overview - -**syntaxis** is a standalone, production-grade project management platform with multi-interface support. It's designed as the foundation for VAPORA SST (Software Specification & Tasks). - -### Core Components - -| Component | Location | Purpose | Tests | Status | -|-----------|----------|---------|-------|--------| -| **syntaxis-core** | `core/crates/syntaxis-core` | Core library: projects, phases, tasks, SurrealDB + SQLite persistence | 179 | ✅ Active | -| **syntaxis-cli** | `core/crates/syntaxis-cli` | Command-line interface via clap | - | ✅ Active | -| **syntaxis-tui** | `core/crates/syntaxis-tui` | Terminal UI via ratatui, vim-style navigation | 10 | ✅ Active | -| **dashboard-client** | `core/crates/client/` | Leptos WASM CSR dashboard (modern, recommended) | - | ✅ Active | -| **dashboard-shared** | `core/crates/dashboard-shared` | Shared types for dashboard | 4 | ✅ Active | -| **syntaxis-api** | `core/crates/syntaxis-api` | REST API server via axum, serves dashboard | - | ✅ Active | -| **syntaxis-dashboard** | `core/crates/wrks/dashboard` | DEPRECATED: Old web dashboard (legacy server) | 52 | ⚠️ Deprecated | -| **syntaxis-vapora** | `core/crates/syntaxis-vapora` | VAPORA orchestration adapter | 57 | ✅ Active | - -### Shared Libraries - -| Component | Location | Tests | Status | -|-----------|----------|-------|--------| -| **shared-api-lib** | `shared/rust-api/shared-api-lib` | REST API utilities | 93 | ✅ Active | -| **rust-tui** | `shared/rust-tui` | TUI utilities (ratatui helpers) | 262 | ✅ Active | -| **tools-shared** | `shared/rust` | Configuration, utilities, helpers | 33 | ✅ Active | - -### Workspace Structure -``` -syntaxis/ (MONOREPO ROOT) -├── shared/ # Reusable libraries -│ ├── rust-api/ # REST API library -│ ├── rust-tui/ # TUI utilities -│ └── rust/ # Config, utilities -├── syntaxis/ # Main project (6+ crates) -│ ├── crates/ # Individual crates -│ ├── docs/ # Architecture docs -│ ├── scripts/ # NuShell build scripts -│ └── Cargo.toml -├── .coder/ # Project tracking (NEVER REMOVE) -├── .claude/ # Development guidelines -├── Justfile # Build recipes -├── Cargo.toml # Root workspace -└── README.md -``` - -## Key Architectural Patterns - -### Module Organization (syntaxis-core example) -```rust -mod error; // Error types (thiserror) -mod types; // Domain types (Project, Task, Phase) -mod config; // Configuration (TOML + Serde) -mod persistence; // Database layer (SQLite + sqlx) -mod phase; // Phase management -mod phase_actions; // Phase state transitions -mod phase_enhanced; // Extended phase logic -mod audit; // Change tracking & audit trail -mod checklist; // Phase-based checklists -mod templates; // Project templates -mod tools; // Tool management -mod security; // Security utilities -#[cfg(test)] mod tests { ... } // Comprehensive tests -``` - -### Error Handling Pattern -All modules use `thiserror` for custom error types with `Result` returns: -```rust -use thiserror::Error; - -#[derive(Error, Debug)] -pub enum WorkspaceError { - #[error("IO error: {0}")] - Io(#[from] std::io::Error), - #[error("Database error: {0}")] - Database(String), -} - -pub type Result = std::result::Result; -``` - -### Configuration-Driven Design -- All settings via TOML + Serde (no hardcoded values) -- `find-config` NuShell utility discovers config files in order: - 1. `.syntaxis/{filename}` - 2. `.project/{filename}` - 3. `.coder/{filename}` - 4. Current directory - -### Database Layer (SurrealDB 2.3 + SQLite Support) -- **SurrealDB 2.3**: Modern multi-backend database (embedded & server modes) - - Supports embedded in-memory, file-based (RocksDB), and server modes - - Feature-gated optional dependency: enable with `surrealdb` feature - - Type-safe async operations with `Database` trait abstraction - - 40+ database operations fully implemented - - Configuration: `configs/database-surrealdb.toml` -- **SQLite (Default)**: File-based relational database - - Async runtime (tokio + sqlx) with Connection pooling - - Prepared statements for security & performance - - Configuration: `configs/database-default.toml` -- **Trait-Based Design**: Single `Database` trait enables multiple implementations - - `SqliteDatabase` for SQLite backend - - `SurrealDatabase` for SurrealDB backend - - Runtime selection via configuration file -- Located in `syntaxis-core/src/persistence/` module with surrealdb_impl.rs - -### Multi-Interface Design -- **CLI**: Command-line via clap with structured arguments -- **TUI**: Terminal UI via ratatui with vim-style keybindings (hjkl) -- **Dashboard**: Web UI via Leptos (CSR WASM client) -- **API**: REST endpoints via axum with Tower middleware - -## Code Quality Standards - -### Mandatory Requirements -✅ **No unsafe code** - `#![forbid(unsafe_code)]` enforced -✅ **No unwrap()** - Use `Result` with `?` operator -✅ **100% documented** - All public APIs have rustdoc -✅ **691+ tests** - Minimum 15 tests per module (all passing) -✅ **Formatted** - Passes `cargo fmt --all` -✅ **Linted** - Passes `cargo clippy --all-targets` (zero warnings) -✅ **Audited** - Passes `cargo audit` -✅ **SurrealDB 2.3** - Production-ready multi-backend database support - -### Pre-Commit Checklist -- [ ] `cargo fmt --all` (code formatted) -- [ ] `cargo clippy --all-targets` (zero warnings) -- [ ] `cargo test --workspace` (all 691+ tests pass) -- [ ] `cargo audit` (no vulnerabilities) -- [ ] Rustdoc for all public items -- [ ] No unsafe code -- [ ] No unwrap() in production code -- [ ] SurrealDB configuration tested (if using) - -## Important Guidelines - -### Never -- Remove `.coder` directory (contains project lifecycle tracking) -- Use `unsafe` code -- Use `unwrap()` in production code -- Hardcode configuration values -- Simplify code when bugs are found - -### Always -- Format, lint, test, and document code -- **Fix bugs completely** - don't simplify code when issues arise -- Use proper error handling with `Result` -- Document public APIs with rustdoc -- Write tests first (TDD approach) -- Use idiomatic Rust patterns - -## Development Workflow - -### For Bug Fixes -1. Locate the bug using provided error context -2. Write failing test demonstrating the issue -3. Fix the bug completely (don't simplify) -4. Ensure all 632+ tests pass -5. Verify lint, format, and audit pass - -### For New Features -1. Plan module structure following existing patterns -2. Write tests first (TDD) -3. Implement feature with proper error handling -4. Document public APIs with rustdoc -5. Run full verification: `just check-all` - -### For Refactoring -1. Keep all tests passing during refactoring -2. Extract common patterns into utilities -3. Use configuration for flexibility -4. Maintain backwards compatibility where possible -5. Update documentation - -## Infrastructure & Scripts - -NuShell scripts in `scripts/` handle infrastructure: - -- `install-cli.nu` - Auto-discover and install binaries -- `manifest.nu` - Track installed binaries -- `common/find-config.nu` - Configuration discovery utility - -Example: `nu scripts/install-cli.nu all` installs all workspace binaries. - -## VAPORA Integration - -syntaxis is designed as the foundation for VAPORA SST (Software Specification & Tasks): - -**Key concepts for VAPORA integration**: -- **Project**: Top-level container (id, name, metadata) -- **Phase**: Project lifecycle stages (create, devel, publish, archive) -- **Task**: Work items with state tracking and audit trail -- **Audit**: Full change history enabling state rollback - -**VAPORA uses syntaxis for**: -- Project and task definitions -- Task state tracking -- Phase-based orchestration -- Agent triggering based on pending tasks -- Enterprise-grade change tracking - -## SurrealDB 2.3 Integration - -**syntaxis now fully supports SurrealDB 2.3** as an alternative database backend. - -### Deployment Options - -| Mode | Best For | Configuration | -|------|----------|---------------| -| **In-Memory** | Development, unit tests, CI/CD | `url = "mem://"` | -| **File-Based** | Local development with persistence | `url = "file:///path/to/db"` | -| **Server Mode** | Integration testing, multiple clients | `surreal start --bind 127.0.0.1:8000 memory` | -| **Docker** | Development teams, reproducible setup | `docker-compose.surrealdb.yml` | -| **Kubernetes** | Production, enterprise deployment | `k8s/` manifests | - -### Quick Start - -**Switch to SurrealDB**: -```bash -cp configs/database-surrealdb.toml configs/database.toml -surreal start --bind 127.0.0.1:8000 memory -cargo run -p syntaxis-cli -``` - -**Switch back to SQLite**: -```bash -cp configs/database-default.toml configs/database.toml -cargo run -p syntaxis-cli -``` - -### SurrealDB Implementation Details - -- **Location**: `syntaxis-core/src/persistence/surrealdb_impl.rs` (800+ lines) -- **Operations**: 40+ database methods fully implemented -- **Feature**: Optional, enabled by default via `surrealdb` Cargo feature -- **API**: Modern JSON binding pattern with `bind(json!({"key": value}))` -- **Tests**: 4 implementations (1 passing, 3 ignored for embedded mode sync) -- **Integration Tests**: 16 server-mode tests in `tests/integration_surrealdb.rs` - -### Configuration Files - -- **`configs/database-default.toml`**: SQLite configuration (recommended default) -- **`configs/database-surrealdb.toml`**: SurrealDB configuration with all options documented -- **Environment Variables**: Support for `SURREALDB_PASSWORD` and other secrets - -### Documentation - -- **SURREALDB_QUICK_START.md**: Get started in 5 minutes -- **SURREALDB_SETUP_GUIDE.md**: Complete setup for local, Docker, Kubernetes -- **SURREALDB_2_3_MIGRATION.md**: Detailed migration information and API changes -- **DEPENDENCIES.md**: SurrealDB 2.3 in Tier 1 (critical dependencies) - -### Key Architecture Decisions - -1. **Trait-Based Abstraction**: Single `Database` trait with multiple implementations -2. **Runtime Selection**: Database backend chosen via configuration, not compile-time -3. **Feature-Gated**: SurrealDB is optional - can build without it if needed -4. **Type Safety**: All operations use Rust's type system for compile-time safety -5. **Async Throughout**: All database operations are async with tokio runtime - -## Performance Considerations - -### Database Performance - -**SurrealDB 2.3**: -- Connection pooling for efficient resource use -- Type-safe queries prevent SQL injection -- Embedded mode offers near-memory speeds -- Server mode supports clustering for scalability - -**SQLite**: -- Connection pooling via SQLitePool -- Batch operations for multiple updates -- Indexed queries for common lookups -- SQLite pragmas for WAL mode and cache - -### API Performance -- Tower middleware for compression -- Rate limiting and request/response caching -- Async/await throughout (tokio runtime) -- Minimal allocations in hot paths - -### TUI Performance -- Efficient terminal drawing via ratatui -- Minimal redraws (only changed regions) -- Async task loading with progress indicators - -## Related Documentation - -- **README.md** - Project overview and quick start -- **.claude/PROJECT_RULES.md** - Architecture principles and standards -- **.claude/CODE_STANDARDS.md** - Build, test, and verification guidelines -- **.claude/DEVELOPMENT.md** - Development workflow and patterns -- **core/docs/ARCHITECTURE.md** - Detailed system design -- **scripts/README.md** - Infrastructure scripts documentation - -## Current Status - -- ✅ **Phase 1-12**: Core functionality complete (173+ tests in syntaxis-core) -- ✅ **Multi-interface**: CLI, TUI, Dashboard all operational -- ⚠️ **syntaxis-api**: REST API in progress (37 compilation errors) -- 🔜 **syntaxis-vapora**: VAPORA adapter planned -- ✅ **Tests**: 632+ tests passing across 8 crates -- ✅ **Production-ready**: Beta status, final integration pending - -## Quick Troubleshooting - -```bash -# Compilation clean rebuild -cargo clean && cargo check --workspace - -# Test failures with logging -RUST_LOG=debug cargo test -- --nocapture - -# Serial test execution (single-threaded) -cargo test -- --test-threads=1 - -# Reset SQLite databases -rm -f data/*.db && cargo test --workspace - -# Performance profiling -cargo flamegraph -cargo bench -``` - ---- - -**Last Updated**: 2025-11-15 -**Rust Edition**: 2021 (MSRV 1.75+) -**Total Tests**: 632+ passing -**Lines of Code**: 10K+ (syntaxis-core alone) diff --git a/provctl-config.toml b/config/provctl-config.toml similarity index 100% rename from provctl-config.toml rename to config/provctl-config.toml diff --git a/provctl-config.txt b/config/provctl-config.txt similarity index 100% rename from provctl-config.txt rename to config/provctl-config.txt diff --git a/provctl/installer-settings.toml b/config/provctl/installer-settings.toml similarity index 100% rename from provctl/installer-settings.toml rename to config/provctl/installer-settings.toml diff --git a/provctl/provctl-config.toml b/config/provctl/provctl-config.toml similarity index 100% rename from provctl/provctl-config.toml rename to config/provctl/provctl-config.toml diff --git a/provctl/provisioning-config.yaml b/config/provctl/provisioning-config.yaml similarity index 100% rename from provctl/provisioning-config.yaml rename to config/provctl/provisioning-config.yaml diff --git a/provctl/scripts/export-config.nu b/config/provctl/scripts/export-config.nu similarity index 100% rename from provctl/scripts/export-config.nu rename to config/provctl/scripts/export-config.nu diff --git a/provctl/templates/installer-settings-toml-j2.j2 b/config/provctl/templates/installer-settings-toml-j2.j2 similarity index 100% rename from provctl/templates/installer-settings-toml-j2.j2 rename to config/provctl/templates/installer-settings-toml-j2.j2 diff --git a/provctl/templates/provctl-config-toml-j2.j2 b/config/provctl/templates/provctl-config-toml-j2.j2 similarity index 100% rename from provctl/templates/provctl-config-toml-j2.j2 rename to config/provctl/templates/provctl-config-toml-j2.j2 diff --git a/provctl/templates/provisioning-config-yaml-j2.j2 b/config/provctl/templates/provisioning-config-yaml-j2.j2 similarity index 100% rename from provctl/templates/provisioning-config-yaml-j2.j2 rename to config/provctl/templates/provisioning-config-yaml-j2.j2 diff --git a/provisioning-config.txt b/config/provisioning-config.txt similarity index 100% rename from provisioning-config.txt rename to config/provisioning-config.txt diff --git a/provisioning-config.yaml b/config/provisioning-config.yaml similarity index 100% rename from provisioning-config.yaml rename to config/provisioning-config.yaml diff --git a/json b/config/syntaxis_config.json similarity index 100% rename from json rename to config/syntaxis_config.json diff --git a/docker/Dockerfile b/deploy/docker/Dockerfile similarity index 100% rename from docker/Dockerfile rename to deploy/docker/Dockerfile diff --git a/docker/docker-compose.yml b/deploy/docker/docker-compose.yml similarity index 100% rename from docker/docker-compose.yml rename to deploy/docker/docker-compose.yml diff --git a/kubernetes/00-namespace.yaml b/deploy/kubernetes/00-namespace.yaml similarity index 100% rename from kubernetes/00-namespace.yaml rename to deploy/kubernetes/00-namespace.yaml diff --git a/kubernetes/10-nats-deployment.yaml b/deploy/kubernetes/10-nats-deployment.yaml similarity index 100% rename from kubernetes/10-nats-deployment.yaml rename to deploy/kubernetes/10-nats-deployment.yaml diff --git a/kubernetes/20-api-deployment.yaml b/deploy/kubernetes/20-api-deployment.yaml similarity index 100% rename from kubernetes/20-api-deployment.yaml rename to deploy/kubernetes/20-api-deployment.yaml diff --git a/install.sh b/install/install.sh similarity index 100% rename from install.sh rename to install/install.sh diff --git a/installer-settings.toml b/install/installer-settings.toml similarity index 100% rename from installer-settings.toml rename to install/installer-settings.toml diff --git a/installer-settings.txt b/install/installer-settings.txt similarity index 100% rename from installer-settings.txt rename to install/installer-settings.txt