commit d2861a957ae13fafff602eb910d08d2c17272117 Author: Jesús Pérez Date: Sat Nov 15 22:43:00 2025 +0000 init repo diff --git a/README.md b/README.md new file mode 100644 index 0000000..49d5fd5 --- /dev/null +++ b/README.md @@ -0,0 +1,510 @@ +![SYNTAXIS Logo](imgs/syntax_logo_a.svg) + +# SYNTAXIS + +> **Systematic Orchestration, Perfectly Arranged** + +**SYNTAXIS** is a production-grade project orchestration platform that brings systematic arrangement to modern software workflows. Like its namesake from ancient Greek (σύνταξις - arrangement, composition), SYNTAXIS transforms chaotic project management into perfectly ordered processes. + +**Core Philosophy**: *Every task has its perfect place in the syntax of your workflow.* + +## 🎯 What Is SYNTAXIS? + +SYNTAXIS is designed for developers and teams who demand: + +- **Systematic Orchestration**: Structured projects with clear phases and transitions +- **Production-Grade Quality**: 691+ tests, zero unsafe code, 100% documented +- **Multiple Interfaces**: Choose your workflow—CLI, TUI, Dashboard, or REST API +- **Scalable Persistence**: From local SQLite to distributed SurrealDB +- **VAPORA Ready**: Official SST foundation for AI agent orchestration +- **Zero Compromises**: Rust-built, fully tested, production-ready from day one + +Perfect for individual developers managing side projects, development teams scaling workflows, and enterprises orchestrating mission-critical systems. + +--- + +## ⚡ Quick Start + +Get started with SYNTAXIS in 30 seconds: + +```bash +# Install via Cargo +cargo install syntaxis + +# Initialize a new project +syntaxis init my-project + +# Start orchestrating +syntaxis orchestrate +``` + +**Choose your interface based on your workflow:** + +- **CLI** (`syntaxis`) — Perfect for automation, CI/CD, scripting +- **TUI** (`syntaxis tui`) — Vim-style navigation, keyboard-driven focus +- **Dashboard** (`syntaxis-dashboard`) — Web-based team visibility +- **REST API** (`syntaxis-api`) — Integration and custom workflows + +--- + +## 🏆 Key Strengths + +### Production-Grade Quality +✅ **691+ Automated Tests** — Every feature tested, every edge case covered +✅ **Zero Unsafe Code** — `#![forbid(unsafe_code)]` enforced +✅ **100% Documented** — All public APIs documented with rustdoc +✅ **Zero Technical Debt** — No shortcuts, no compromises + +### Scalable Architecture +- **Start Simple**: SQLite (local, zero config) +- **Scale Seamlessly**: SurrealDB (team-ready, distributed) +- **Deploy Anywhere**: Docker, Kubernetes, cloud-native ready + +### Feature-Rich Yet Simple +- **Systematic Phases**: Create → Develop → Publish → Archive +- **Task Management**: Priority, type, state tracking with audit trails +- **Real-Time Updates**: WebSocket support across all interfaces +- **Configuration-Driven**: All settings via TOML, no hardcoding + +--- + +## 📦 Components + +### syntaxis-core (10K+ lines) +Core business logic for: +- **Projects**: Create, manage, and organize projects +- **Phases**: Project lifecycle phases (create → devel → publish → archive) +- **Tasks**: Work items with priority, type, and state tracking +- **Tracking**: Full state change history and audit trail +- **Templates**: Auto-generate project structures +- **Checklists**: Phase-based progress validation + +### syntaxis-api (3.3K+ lines) +REST API server with: +- RESTful endpoints for all operations +- WebSocket support for real-time updates +- Authentication & authorization +- Rate limiting & metrics +- TLS support +- JSON request/response + +### syntaxis-tui (5.3K+ lines) +Terminal User Interface: +- Ratatui-based interactive UI +- Vim-style keyboard navigation (hjkl) +- Real-time task management +- Multi-screen navigation +- SSH-friendly (works over remote connections) + +### syntaxis-dashboard (1.4K+ lines) +Web Dashboard: +- Modern responsive design +- Mouse & keyboard support +- Advanced filtering & analytics +- Mobile-friendly layout +- Leptos-based (WASM) + +### syntaxis-cli +Command-line tool: +- `syntaxis` binary for scripting and automation +- Full CLI coverage with structured subcommands +- Integration with shell workflows and CI/CD pipelines + +### syntaxis-vapora +VAPORA adapter: +- Integrates syntaxis-core into VAPORA SST +- Handles orchestration coordination +- Agent integration hooks + +## 💾 Database Support + +syntaxis supports **both SurrealDB 2.3 and SQLite** via configuration: + +### SurrealDB 2.3 (Modern, Multi-Backend) +- ✅ Embedded in-memory mode (development, testing) +- ✅ Embedded file-based mode (RocksDB persistence) +- ✅ Server mode (integration testing, multiple clients) +- ✅ Docker deployment (reproducible setup) +- ✅ Kubernetes deployment (enterprise production) +- **Quick Setup**: `cp configs/database-surrealdb.toml configs/database.toml && surreal start --bind 127.0.0.1:8000 memory` + +### SQLite (Default, Recommended) +- ✅ Default configuration (no setup needed) +- ✅ Local file-based persistence +- ✅ Async pooled connections +- ✅ Zero external dependencies +- **Quick Setup**: `cargo run -p syntaxis-cli` (uses SQLite by default) + +### Switching Databases +```bash +# Use SurrealDB +cp configs/database-surrealdb.toml configs/database.toml + +# Use SQLite (default) +cp configs/database-default.toml configs/database.toml +``` + +**For detailed setup instructions:** +- SurrealDB: See [SURREALDB_QUICK_START.md](./SURREALDB_QUICK_START.md) +- SurrealDB Production: See [SURREALDB_SETUP_GUIDE.md](./SURREALDB_SETUP_GUIDE.md) +- SurrealDB Configuration: See [configs/database-surrealdb.toml](./configs/database-surrealdb.toml) + +--- + +## 🎯 Who Uses SYNTAXIS? + +### Individual Developers +**Your Personal Workflow Composer** + +SYNTAXIS brings systematic order to your projects. No more scattered TODOs, forgotten tasks, or chaotic sprints. Every task has its place in the syntax of your workflow. + +```bash +syntaxis init my-project +syntaxis tui # Beautiful terminal UI +``` + +### Development Teams +**Team Orchestration, Systematically Arranged** + +Stop fighting with Jira. Stop settling for Trello. SYNTAXIS provides just enough structure for clarity, with just enough flexibility for creativity. + +- Shared projects with real-time collaboration +- Phase-based workflow management +- Complete audit trails for accountability + +### Enterprises +**Enterprise Orchestration Without Enterprise Complexity** + +Production-grade doesn't mean complicated. SYNTAXIS scales to thousands of tasks without losing the systematic simplicity at its core. + +- SurrealDB + Kubernetes = Infinite scale +- Comprehensive security and audit features +- Multi-team support and RBAC + +### VAPORA Ecosystem +**The Systematic Foundation for AI Orchestration** + +SYNTAXIS provides the structured task layer that VAPORA agents need to orchestrate intelligently. Task states trigger agents. Agents update tasks. The cycle continues, systematically. + +```rust +// VAPORA agents can now orchestrate via SYNTAXIS +agent.on_task_state_change(|task| { + // Perform intelligent actions based on task state +}).await; +``` + +--- + +## 🚀 Installation + +### One-Command Installation (Recommended) + +Install everything with a single command - the installer handles all dependencies: + +```bash +curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash +``` + +This installs: +- ✅ Rust toolchain via rustup bootstrap (if needed) +- ✅ NuShell via Rust compilation (if needed) +- ✅ Just task runner via Rust compilation (if needed) +- ✅ All binaries: `syntaxis`, `syntaxis-tui`, `syntaxis-dashboard`, `syntaxis-api` +- ✅ Configuration files to `~/.config/syntaxis/` +- ✅ Environment setup + +**Installation takes 15-30 minutes** (mostly cargo build time on first install). + +#### How It Works: Bootstrap Compiler + +The installer uses Rust's **bootstrap compiler architecture** to avoid circular dependencies: + +1. **Download pre-compiled Rust** (100MB) via `curl https://sh.rustup.rs | bash` + - Works on any system (no compilation needed for bootstrap) +2. **Use Rust to compile everything else** (NuShell, Just, workspace binaries) + - Once Rust exists, we can compile any Rust source code +3. **Deploy & configure** all components automatically + +**Why this works:** Only the first compiler (Rust) is pre-compiled. Everything else is built from source using that compiler. No circular dependency! + +**For detailed explanation:** See [BOOTSTRAP_EXPLAINED.md](./BOOTSTRAP_EXPLAINED.md) and [BOOTSTRAP_DIAGRAMS.md](./BOOTSTRAP_DIAGRAMS.md). + +#### Installation Options + +```bash +# Unattended mode (no prompts) +bash install.sh --unattended + +# Install to custom directory +bash install.sh --prefix /opt/workspace + +# Only deploy configs (binaries already installed) +bash install.sh --config-only + +# See what would be installed without making changes +bash install.sh --dry-run + +# Full help +bash install.sh --help +``` + +After installation, reload your shell: +```bash +source ~/.bashrc # or ~/.zshrc, ~/.config/fish/config.fish +``` + +Then verify installation: +```bash +syntaxis --help +syntaxis-tui --version +which syntaxis-dashboard +``` + +### Manual Installation (Developers) + +For development or advanced installation: + +#### Prerequisites +- Rust 1.75+ +- Cargo +- NuShell (for scripts) + +#### Build +```bash +cd /Users/Akasha/Development/syntaxis +cargo build --workspace +``` + +#### Test +```bash +cargo test --workspace +``` + +#### Run API Server +```bash +cargo run -p syntaxis-api +# Server runs on http://localhost:3001 +``` + +#### Run Terminal UI +```bash +cargo run -p syntaxis-tui +``` + +#### Run Web Dashboard +```bash +cargo run -p syntaxis-dashboard +# Dashboard on http://localhost:3000 +``` + +#### Run CLI +```bash +cargo run -p syntaxis-cli -- --help +``` + +## 📋 Commands + +All available via `just`: + +```bash +just check # cargo check +just test # cargo test +just fmt # cargo fmt +just lint # cargo clippy +just check-all # Full verification +just audit # Security audit +just doc # Generate docs + +just run-api # Start API server +just run-tui # Start TUI +just run-dashboard # Start web dashboard +just run-cli --help # Run CLI +``` + +## 🏗️ Architecture + +``` +syntaxis/ (MONOREPO ROOT) +│ +├── shared/ (Reusable libraries) +│ ├── rust-api/ +│ ├── rust-tui/ +│ └── rust/ (Config, utilities) +│ +├── syntaxis/ (Main project) +│ ├── crates/ +│ │ ├── syntaxis-core/ (Core library) +│ │ ├── syntaxis-api/ (REST server) +│ │ ├── syntaxis-tui/ (Terminal UI) +│ │ ├── syntaxis-dashboard/ (Web dashboard) +│ │ ├── syntaxis-cli/ (CLI tool) +│ │ └── syntaxis-vapora/ (VAPORA adapter) +│ │ +│ ├── docs/ +│ ├── templates/ +│ ├── scripts/ +│ └── README.md +│ +├── .coder/ (Project tracking) +├── .claude/ (Guidelines & rules) +├── Cargo.toml (Workspace root) +├── Justfile (Build recipes) +└── README.md (This file) +``` + +## 🔌 VAPORA Integration + +syntaxis is designed as the **foundation for VAPORA SST**. + +### How VAPORA Uses It + +1. **Project Management**: Defines projects, phases, tasks +2. **Task State**: Tracks task progress and state changes +3. **Orchestration**: VAPORA orchestrator triggers agents based on pending tasks +4. **Automation**: Agents update task states → VAPORA reacts + +### Setup in VAPORA + +```toml +# vapora/vapora-sst/Cargo.toml +[dependencies] +syntaxis-core = { path = "../../Development/core/core/crates/syntaxis-core" } +``` + +```rust +// vapora/vapora-sst/src/orchestrator.rs +use workspace_core::*; + +impl VaporaOrchestrator { + async fn process_pending_tasks(&self, project_id: &str) -> Result<()> { + let tasks = self.workspace_api.get_pending_tasks(project_id).await?; + + for task in tasks { + // Trigger agents, update state, etc. + } + + Ok(()) + } +} +``` + +## 📚 Documentation + +### Installation & Bootstrap +- **[BOOTSTRAP_EXPLAINED.md](./BOOTSTRAP_EXPLAINED.md)** - Complete explanation of how Rust bootstrap compiler works, why we use it, and how it enables one-command installation +- **[BOOTSTRAP_DIAGRAMS.md](./BOOTSTRAP_DIAGRAMS.md)** - Visual diagrams and flowcharts explaining the bootstrap process +- **[INSTALLATION_GUIDE.md](./INSTALLATION_GUIDE.md)** - Step-by-step installation and post-install setup +- **[CONFIGURATION_GUIDE.md](./CONFIGURATION_GUIDE.md)** - Configuration options and customization + +### Project Documentation +- **[Architecture](./core/docs/ARCHITECTURE.md)** - System design +- **[API Reference](./core/docs/API.md)** - REST endpoints +- **[CLI Guide](./core/docs/CLI.md)** - Command-line usage +- **[VAPORA Integration](./core/docs/VAPORA_INTEGRATION.md)** - VAPORA setup +- **[Quick Start](./core/docs/QUICK_START.md)** - Getting started + +## ✅ Code Quality + +- ✅ **No unsafe code** - `#![forbid(unsafe_code)]` +- ✅ **No unwrap()** - Proper error handling with `Result` +- ✅ **100% documented** - All public APIs documented with rustdoc +- ✅ **100+ tests** - Comprehensive test coverage +- ✅ **Idiomatic Rust** - Following language best practices +- ✅ **Formatted & linted** - `cargo fmt` & `cargo clippy` compliant + +--- + +## 💡 Why SYNTAXIS? + +### vs. Jira +Jira is complex, expensive, and overwhelming. SYNTAXIS is systematic, affordable, and clarity-focused. Perfect for 90% of teams who don't need enterprise complexity. + +### vs. GitHub Projects +GitHub Projects is basic and locked into GitHub. SYNTAXIS is rich, standalone, and fully orchestration-capable. For serious project management. + +### vs. Linear +Linear is beautiful but proprietary and SaaS-only. SYNTAXIS is open source with self-hosting options and true multi-interface flexibility. + +### vs. Asana/Monday.com +These tools are generic and business-focused. SYNTAXIS is developer-first, technically excellent, and systematically designed. + +### Unique Advantages +1. **Multi-Interface Excellence**: CLI + TUI + Dashboard + REST API +2. **Production-Grade Quality**: 691+ tests, zero unsafe code, 100% documented +3. **Systematic Philosophy**: Based on arrangement/composition principles +4. **Database Flexibility**: Switch SQLite ↔ SurrealDB via config change +5. **VAPORA Ready**: Official AI orchestration foundation +6. **No Vendor Lock-in**: Open source, self-hosted, your data + +--- + +## 🎯 Project Status + +- ✅ **Phase 1-12**: Core functionality complete (691+ tests) +- ✅ **Fully Renamed**: All references updated to syntaxis +- ✅ **Multi-Interface**: CLI, TUI, Dashboard, and REST API operational +- ✅ **Production-Ready**: Beta status, ready for real-world use +- 🔜 **Coming Soon**: VAPORA integration enhancements, advanced features + +## 📝 Guidelines + +All code follows the guidelines in `.claude/`: + +- **PROJECT_RULES.md** - Architecture & design principles +- **CODE_STANDARDS.md** - Build, test, verification +- **DEVELOPMENT.md** - Workflow & patterns +- **projec_best_practices.md** - Configuration-driven design + +When syntaxis rules are finalized, custom `.claude/SYNTAXIS.md` will be added. + +## 🤝 Contributing + +All contributions must: + +- ✅ Pass `cargo check --workspace` +- ✅ Pass `cargo test --workspace` +- ✅ Pass `cargo clippy --all-targets` +- ✅ Pass `cargo fmt --all` +- ✅ Include tests for new features +- ✅ Include documentation + +## 📄 License + +MIT OR Apache-2.0 + +## 📖 Learn More + +### Documentation +- [Architecture Guide](./core/docs/ARCHITECTURE.md) — System design and patterns +- [API Reference](./core/docs/API.md) — REST endpoint documentation +- [CLI Guide](./core/docs/CLI.md) — Command-line usage +- [VAPORA Integration](./core/docs/VAPORA_INTEGRATION.md) — AI orchestration setup + +### Development +- [Building from Source](./core/HOWTO-BUILD.md) — Compilation and releases +- [Configuration Guide](./core/HOWTO-CONFIG.md) — TOML setup and customization +- [Contributing Guidelines](./CONTRIBUTING.md) — How to contribute + +--- + +## 🔗 Links + +- **Website**: https://syntaxis.dev +- **GitHub**: https://github.com/syntaxis +- **Documentation**: [Complete Guide](./core/docs/ARCHITECTURE.md) +- **Root directory**: `/Users/Akasha/Development/syntaxis` +- **Brand Identity**: [SYNTAXIS Brand Guide](./difusion/SYNTAXIS_BRAND_IDENTITY.md) + +--- + +**Status**: Production Ready (Beta) ✅ +**Last Updated**: 2025-11-15 +**Framework Version**: 0.1.0 +**Test Coverage**: 691+ tests (all passing) ✅ +**Code Quality**: Zero unsafe code, 100% documented, zero warnings ✅ + +--- + +**SYNTAXIS** — Where systematic meets orchestration. +Built in Rust. Tested rigorously. Designed for clarity. Ready for production. + e \ No newline at end of file diff --git a/imgs/syntax_logo_a.svg b/imgs/syntax_logo_a.svg new file mode 100644 index 0000000..8ac1e03 --- /dev/null +++ b/imgs/syntax_logo_a.svg @@ -0,0 +1,214 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + SYNTAXIS + + + Systematic Orchestration +