syntaxis/CLAUDE.md

# 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 <crate>   # 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<T>` 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<T> = std::result::Result<T, WorkspaceError>;
```

### 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<T>` 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<T>`
- 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)