"Ecosystem & Tooling"

Ecosystem & Tooling

Note: This page describes the intended developer experience. The crates/vox-cli binary implements a subset of commands today (build, check, test, run, bundle; fmt / install fail until wired; lsp). Authoritative current flags: ref-cli.md.

Vox ships with a complete development toolchain: compiler, bundler, test runner, formatter, package manager, and language server — converging on the vox CLI as the primary entry point.

CLI Commands

vox build

Compile a .vox file to Rust and TypeScript:

# Basic build
vox build app.vox -o dist

Watch mode and other flags may land later; use vox build --help and ref-cli.md for what the binary exposes now.

Typical output layout (minimal CLI) — filenames vary by program; Rust lands under target/generated/:

dist/
├── backend/      # Generated Rust (Axum server)
│   ├── src/
│   │   └── main.rs
│   └── Cargo.toml
└── frontend/     # Generated TypeScript (React)
    ├── src/
    │   └── App.tsx
    └── package.json

vox bundle

Ship a single statically-linked binary containing frontend + backend + SQLite:

# Release build targeting Linux
vox bundle app.vox --release --target x86_64-unknown-linux-musl

# Debug build (default)
vox bundle app.vox

vox test

Run @test decorated functions:

vox test tests.vox

This compiles the test functions to Rust #[test] blocks and runs them with cargo test.

vox fmt

Minimal binary today: vox fmt exits with an error until vox-fmt matches the current AST. Formatting work lives in the vox-fmt crate.

vox fmt app.vox

See ref-cli.md.

vox lsp

Launch the Language Server Protocol server:

vox lsp

See Language Server below for details.

Package management (vox add / vox sync / vox pm)

vox install is removed (no CLI subcommand). Use vox add, vox lock, vox sync, and vox pm per reference/cli.md; see the full mapping in pm-migration-2026.md.

vox vendor

Offline trees: use vox pm vendor. Populate .vox_modules/dl/ with vox sync first.

Language Server (LSP)

The vox-lsp crate provides IDE support via the Language Server Protocol.

Current Features

FeatureStatus
Syntax error diagnostics✅ Implemented
Type error diagnostics✅ Implemented
Go to Definition🔜 Planned
Completion🔜 Planned
Hover info🔜 Planned

Setup

  1. Build the LSP server:

    cargo build --release -p vox-lsp

  2. Configure your editor:

    VS Code (with the vox-vscode extension or manual configuration):

    "vox.lsp.serverPath": "/path/to/target/release/vox-lsp"

The LSP server integrates the full compiler pipeline — when you save a file, it re-runs the lexer, parser, and type checker to provide real-time diagnostics.

Package Manager (vox-pm)

The Vox package manager uses a Content-Addressable Store (CAS) backed by libSQL/Turso.

How It Works

store(data) → SHA3-256 hash
get(hash)   → data

All artifacts are stored by their content hash:

  • Deterministic — same content always produces the same hash
  • Deduplication — identical artifacts share a single stored copy
  • Integrity — content can be verified against its hash at any time

Database Backends

ModeUse Case
Remote (Turso)Production — cloud-hosted database
Local SQLiteDevelopment — local file storage
In-MemoryTesting — ephemeral database
Embedded ReplicaHybrid — local cache with cloud sync

The package manager includes a de Bruijn indexing normalizer that strips identifier names from AST nodes and replaces bound variables with positional indices. This enables detection of semantically identical code regardless of naming differences.

bind_name(namespace, name, hash)    # Map a name to content
lookup_name(namespace, name) → hash # Resolve a name to content
search_code_snippets(query, limit)  # Vector-similarity search

Agent Memory

The store also manages agent memory for AI-powered features:

recall_async(agent, type, limit, min_importance)  # Query with relevance filtering

Installation

# Linux / macOS
./scripts/install.sh          # End-user install
./scripts/install.sh --dev    # Full contributor setup
./scripts/install.sh plan     # JSON install plan (CI/tooling)

# Windows (PowerShell)
.\scripts\install.ps1         # End-user install
.\scripts\install.ps1 -Dev    # Full contributor setup
.\scripts\install.ps1 plan    # JSON install plan (CI/tooling)

Manual

Prerequisites: Rust >= 1.75, Node.js >= 18, C compiler (gcc/clang/MSVC). Full workspace + Turso crates: clang on Linux/macOS; clang-cl (LLVM) on Windows — see docs/src/how-to-setup.md.

cargo install --locked --path crates/vox-cli

Note: Node.js and npm are required at runtime for vox bundle and vox run (frontend scaffolding). Copy .env.example to .env to configure optional API keys.

Development

Building

cargo build --workspace

Testing

cargo test --workspace

Linting

cargo fmt --all -- --check    # Format check
cargo clippy --workspace      # Lint check

Next Steps