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

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

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

just fmt                # Format code (cargo fmt)
just lint               # Lint with clippy
just lint-pedantic      # Lint with pedantic warnings
just audit              # Security audit

Running Applications

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:

# 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
rust-tui	shared/rust-tui	TUI utilities (ratatui helpers)	262
tools-shared	shared/rust	Configuration, utilities, helpers	33

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)

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:

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:

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:

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

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