Skip to content

ruvnet/ruv.io

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

4 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

@ruv.io/* - Comprehensive Rust-to-NPM Wrapper Ecosystem

License: MIT Crates: 110 NPM Packages: 110

🎯 Project Overview

This monorepo contains a comprehensive ecosystem of 110 NPM packages that wrap Rust crates from crates.io/users/ruvnet using napi-rs. Each package provides high-performance Node.js bindings to powerful Rust libraries spanning AI/ML, blockchain, quantum computing, neural networks, temporal systems, and more.

πŸš€ Key Features

  • 110 High-Performance Packages: Every Rust crate wrapped with native Node.js bindings
  • Zero-Copy Operations: Leverage Rust's memory safety with JavaScript convenience
  • Cross-Platform Support: Works on Linux, macOS, Windows (x64, ARM64)
  • TypeScript First: Full TypeScript definitions for all packages
  • WASM Fallback: WebAssembly builds for unsupported platforms
  • MCP Protocol Support: Model Context Protocol integration for AI agents
  • CLI Tools: Command-line interfaces for development and operations
  • Swarm Orchestration: Multi-agent coordination using claude-flow and agentdb

πŸ“‹ SPARC Specification

S - Specification

1.1 Project Scope

Transform 110 Rust crates into production-ready NPM packages using napi-rs, providing:

  • Native Node.js bindings for maximum performance
  • TypeScript definitions for type safety
  • Comprehensive documentation and examples
  • Automated CI/CD pipelines
  • Cross-platform binary distribution

1.2 Architecture Categories

The 110 crates are organized into 16 major categories:

Category Count Description
AI/ML Systems 8 AIMDS, DAA, Veritas-Nexus, Goalie
Swarm Orchestration 16 RUV-Swarm, Code-Mesh, Synaptic systems
CLI Tools 9 Command-line interfaces for all major systems
WASM Bindings 8 WebAssembly-ready packages
MCP Protocol 5 Model Context Protocol servers and clients
Blockchain/Crypto 16 QuDAG, Claude Market, Quantum-resistant crypto
Quantum Computing 16 QVM Scheduler, ML-KEM/ML-DSA implementations
Neural Networks 17 RUV-FANN, Micro-networks, Neuro-divergent
Temporal Systems 14 Time dilation, Strange loops, Consciousness models
Mathematical 5 Geometric Langlands, Sublinear solvers
Trading/Finance 12 Neural Trader suite (backtesting, execution, portfolio)
Computer Vision 3 OpenCV bindings and WASM support
Dev Tools 7 CUDA transpiler, Jujutsu VCS, Parser utilities
Type Systems 3 Lean theorem prover, Dependent types
Networking 4 P2P, BitChat, QuDAG network layer
Databases 3 AgentDB, DHT, Persistence layers

1.3 Technical Requirements

Core Technology Stack
  • Build System: napi-rs with @napi-rs/cli
  • Language: Rust (stable) + TypeScript
  • Package Manager: npm/pnpm with workspaces
  • CI/CD: GitHub Actions with multi-platform builds
  • Testing: Jest + Rust cargo test
  • Documentation: TypeDoc + mdBook
Platform Support Matrix
β”œβ”€β”€ Node.js: >= 16.x
β”œβ”€β”€ Platforms:
β”‚   β”œβ”€β”€ linux-x64-gnu
β”‚   β”œβ”€β”€ linux-x64-musl
β”‚   β”œβ”€β”€ linux-arm64-gnu
β”‚   β”œβ”€β”€ darwin-x64
β”‚   β”œβ”€β”€ darwin-arm64
β”‚   β”œβ”€β”€ win32-x64-msvc
β”‚   └── wasm32 (fallback)
β”œβ”€β”€ Rust: >= 1.70
└── TypeScript: >= 5.0

1.4 Package Naming Convention

All packages follow the naming pattern: @ruv.io/{crate-name}

Examples:

  • @ruv.io/ruv-fann β†’ Neural network library
  • @ruv.io/qudag β†’ Quantum-resistant DAG platform
  • @ruv.io/temporal-compare β†’ Temporal prediction benchmarking
  • @ruv.io/geometric-langlands β†’ Mathematical framework

1.5 Success Criteria

  • All 110 crates have corresponding NPM packages
  • 95%+ test coverage across all packages
  • Cross-platform binaries for 7+ platforms
  • < 10ms overhead for native bindings
  • Complete TypeScript definitions
  • Automated CI/CD with release automation
  • Comprehensive documentation (API + guides)
  • Working examples for each package

P - Pseudocode

2.1 Package Structure Template

@ruv.io/{crate-name}/
β”œβ”€β”€ Cargo.toml              # Rust crate configuration
β”œβ”€β”€ package.json            # NPM package configuration
β”œβ”€β”€ build.rs                # napi-rs build script
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ lib.rs              # Rust source (napi bindings)
β”‚   └── index.ts            # TypeScript exports
β”œβ”€β”€ __test__/
β”‚   β”œβ”€β”€ index.spec.ts       # Jest tests
β”‚   └── integration.test.ts # Integration tests
β”œβ”€β”€ examples/
β”‚   β”œβ”€β”€ basic.js            # JavaScript example
β”‚   └── advanced.ts         # TypeScript example
β”œβ”€β”€ docs/
β”‚   └── API.md              # API documentation
β”œβ”€β”€ .github/
β”‚   └── workflows/
β”‚       β”œβ”€β”€ build.yml       # Build workflow
β”‚       └── release.yml     # Release workflow
└── README.md               # Package README

2.2 Build Process Flow

// High-level pseudocode for napi-rs wrapper

#[napi]
pub struct RustStruct {
  inner: Arc<Mutex<OriginalRustType>>,
}

#[napi]
impl RustStruct {
  #[napi(constructor)]
  pub fn new(config: JsObject) -> Result<Self> {
    // 1. Parse JS config to Rust types
    let rust_config = parse_js_config(config)?;

    // 2. Initialize Rust struct
    let inner = OriginalRustType::new(rust_config)?;

    // 3. Wrap in Arc<Mutex> for thread safety
    Ok(Self {
      inner: Arc::new(Mutex::new(inner))
    })
  }

  #[napi]
  pub async fn process(&self, input: Buffer) -> Result<Buffer> {
    // 1. Convert JS Buffer to Rust bytes
    let data = input.as_ref();

    // 2. Process in Rust (async)
    let result = self.inner.lock().unwrap()
      .process(data)
      .await?;

    // 3. Convert back to JS Buffer
    Ok(Buffer::from(result))
  }
}

2.3 Orchestration Pseudocode (claude-flow)

// Agent orchestration using claude-flow and agentdb

import { AgentSwarm, AgentDB } from '@ruv.io/ruv-swarm-core'
import { ClaudeFlow } from 'claude-flow'
import { E2BSandbox } from '@e2b/sdk'

async function orchestratePackageBuilds() {
  // 1. Initialize agent database
  const agentdb = new AgentDB({
    connection: 'sqlite://agents.db',
    vectorStore: 'chroma'
  })

  // 2. Load all 110 crate specifications
  const crates = await loadCrateSpecs('/plans/*.md')

  // 3. Create agent swarm
  const swarm = new ClaudeFlow({
    agents: crates.map(crate => ({
      id: `builder-${crate.name}`,
      role: 'package-builder',
      capabilities: ['rust', 'napi', 'typescript'],
      context: crate
    })),
    coordination: 'hierarchical',
    memory: agentdb
  })

  // 4. Build dependency graph
  const graph = buildDependencyGraph(crates)

  // 5. Execute build swarm
  for (const batch of graph.topologicalBatches()) {
    await Promise.all(batch.map(async (crate) => {
      // Create E2B sandbox for isolated build
      const sandbox = await E2BSandbox.create({
        template: 'rust-napi-builder',
        envVars: {
          OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY
        }
      })

      // Execute build agent
      const agent = swarm.getAgent(`builder-${crate.name}`)
      const result = await agent.execute({
        task: 'build-napi-package',
        sandbox,
        spec: crate
      })

      // Store results in agentdb
      await agentdb.store({
        agent: agent.id,
        result,
        artifacts: result.binaries
      })

      await sandbox.close()
    }))
  }

  // 6. Generate summary report
  return swarm.generateReport()
}

A - Architecture

3.1 System Architecture Diagram

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     @ruv.io NPM Ecosystem                        β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                                                                   β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚              Claude Flow Orchestration                  β”‚   β”‚
β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚   β”‚
β”‚  β”‚  β”‚  Agent Swarm Manager                             β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - 110 Builder Agents (1 per crate)             β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - Dependency Resolution                          β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - Parallel Build Coordination                    β”‚   β”‚   β”‚
β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚   β”‚
β”‚  β”‚                          ↓                               β”‚   β”‚
β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚   β”‚
β”‚  β”‚  β”‚  AgentDB (Memory & Coordination)                 β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - Build State                                    β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - Dependency Graph                               β”‚   β”‚   β”‚
β”‚  β”‚  β”‚  - Artifact Registry                              β”‚   β”‚   β”‚
β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚                            ↓                                     β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚           E2B Sandbox Cluster (via OpenRouter)          β”‚   β”‚
β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”       β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚   β”‚
β”‚  β”‚  β”‚Sandbox1β”‚  β”‚Sandbox2β”‚  β”‚Sandbox3β”‚  ...  β”‚Sandbox β”‚   β”‚   β”‚
β”‚  β”‚  β”‚rust    β”‚  β”‚rust    β”‚  β”‚rust    β”‚       β”‚  110   β”‚   β”‚   β”‚
β”‚  β”‚  β”‚+ napi  β”‚  β”‚+ napi  β”‚  β”‚+ napi  β”‚       β”‚+ napi  β”‚   β”‚   β”‚
β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜       β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚                            ↓                                     β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚                  Build Pipeline                          β”‚   β”‚
β”‚  β”‚                                                           β”‚   β”‚
β”‚  β”‚  For each crate:                                         β”‚   β”‚
β”‚  β”‚  1. Parse Cargo.toml β†’ Extract metadata                 β”‚   β”‚
β”‚  β”‚  2. Generate napi bindings β†’ lib.rs                     β”‚   β”‚
β”‚  β”‚  3. Generate TypeScript defs β†’ index.d.ts               β”‚   β”‚
β”‚  β”‚  4. Build native binaries β†’ .node files                 β”‚   β”‚
β”‚  β”‚  5. Run tests β†’ cargo test + jest                       β”‚   β”‚
β”‚  β”‚  6. Generate docs β†’ API.md                              β”‚   β”‚
β”‚  β”‚  7. Package β†’ @ruv.io/{name}@{version}.tgz             β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚                            ↓                                     β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚            Distribution & Registry                       β”‚   β”‚
β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚   β”‚
β”‚  β”‚  β”‚   NPM.js     β”‚  β”‚  GitHub      β”‚  β”‚  Documentationβ”‚  β”‚   β”‚
β”‚  β”‚  β”‚   Registry   β”‚  β”‚  Releases    β”‚  β”‚  Site         β”‚  β”‚   β”‚
β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

3.2 Package Architecture Layers

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚          Layer 4: Application Layer              β”‚
β”‚  User Code (JavaScript/TypeScript/WASM)         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚          Layer 3: NPM Package Layer              β”‚
β”‚  @ruv.io/* packages with TypeScript bindings    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚          Layer 2: NAPI Bridge Layer              β”‚
β”‚  napi-rs FFI bindings (zero-copy transfers)     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚          Layer 1: Rust Core Layer                β”‚
β”‚  Original Rust crates (110 packages)            β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

3.3 Dependency Resolution Strategy

Build Order Algorithm:

  1. Parse all 110 Cargo.toml files
  2. Build directed acyclic graph (DAG) of dependencies
  3. Topological sort to determine build order
  4. Group independent crates into parallel batches
  5. Execute batches sequentially, crates in parallel

Example Dependency Chains:

Core Libraries (Batch 1):
  - aimds-core
  - daa-prime-core
  - ruv-swarm-core
  - micro_core
  - nt-core

Derived Libraries (Batch 2):
  - aimds-detection β†’ aimds-core
  - aimds-analysis β†’ aimds-core + aimds-detection
  - ruv-swarm-agents β†’ ruv-swarm-core
  - ruv-swarm-ml β†’ ruv-swarm-core

CLI Tools (Batch 3):
  - daa-cli β†’ daa-orchestrator
  - qudag-cli β†’ qudag-protocol
  - code-mesh-cli β†’ code-mesh-core

WASM Bindings (Batch 4):
  - ruv-swarm-wasm β†’ ruv-swarm-core
  - code-mesh-wasm β†’ code-mesh-core
  - qudag-wasm β†’ qudag-protocol

3.4 Cross-Platform Binary Strategy

Each package will include platform-specific binaries:

{
  "name": "@ruv.io/package-name",
  "version": "1.0.0",
  "napi": {
    "name": "package-name",
    "triples": {
      "defaults": true,
      "additional": [
        "x86_64-unknown-linux-musl",
        "aarch64-unknown-linux-gnu",
        "armv7-unknown-linux-gnueabihf",
        "aarch64-apple-darwin",
        "x86_64-apple-darwin",
        "x86_64-pc-windows-msvc",
        "i686-pc-windows-msvc",
        "aarch64-pc-windows-msvc",
        "wasm32-wasi"
      ]
    }
  },
  "optionalDependencies": {
    "@ruv.io/package-name-linux-x64-gnu": "1.0.0",
    "@ruv.io/package-name-linux-x64-musl": "1.0.0",
    "@ruv.io/package-name-linux-arm64-gnu": "1.0.0",
    "@ruv.io/package-name-darwin-x64": "1.0.0",
    "@ruv.io/package-name-darwin-arm64": "1.0.0",
    "@ruv.io/package-name-win32-x64-msvc": "1.0.0",
    "@ruv.io/package-name-wasm32": "1.0.0"
  }
}

R - Refinement

4.1 Performance Optimization

Zero-Copy Data Transfer:

// Avoid copying large buffers between Rust and JS
#[napi]
pub fn process_buffer(#[napi(external)] buffer: External<Vec<u8>>) -> Result<External<Vec<u8>>> {
  // Process buffer in-place without copying
  let mut data = buffer.clone();
  // ... process data ...
  Ok(External::new(data))
}

Async Processing:

// Use tokio for async I/O operations
#[napi]
pub async fn fetch_data(url: String) -> Result<Buffer> {
  let response = reqwest::get(&url).await?;
  let bytes = response.bytes().await?;
  Ok(Buffer::from(bytes.to_vec()))
}

Thread Pool Management:

// Share thread pools across instances
lazy_static! {
  static ref THREAD_POOL: ThreadPool = ThreadPoolBuilder::new()
    .num_threads(num_cpus::get())
    .build()
    .unwrap();
}

4.2 Error Handling Strategy

Rust β†’ JS Error Conversion:

use napi::Error as NapiError;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum CustomError {
  #[error("Network error: {0}")]
  Network(#[from] reqwest::Error),

  #[error("Parse error: {0}")]
  Parse(String),

  #[error("Invalid state: {0}")]
  InvalidState(String),
}

impl From<CustomError> for NapiError {
  fn from(err: CustomError) -> Self {
    NapiError::from_reason(err.to_string())
  }
}

TypeScript Error Types:

export class RuvNetworkError extends Error {
  constructor(message: string, public code: string) {
    super(message)
    this.name = 'RuvNetworkError'
  }
}

export class RuvParseError extends Error {
  constructor(message: string, public input: string) {
    super(message)
    this.name = 'RuvParseError'
  }
}

4.3 Testing Strategy

Multi-Level Testing:

1. Unit Tests (Rust)
   - cargo test for Rust logic
   - Test pure Rust functions

2. Integration Tests (Rust)
   - Test napi bindings
   - Verify JS ↔ Rust conversion

3. E2E Tests (JavaScript/TypeScript)
   - Jest for Node.js tests
   - Test actual NPM package usage
   - Performance benchmarks

4. Cross-Platform Tests
   - Test on all target platforms
   - GitHub Actions matrix builds

5. Fuzzing (for critical packages)
   - cargo fuzz for parsing/crypto
   - AFL++ for binary formats

4.4 Documentation Standards

Each package includes:

  1. README.md: Quick start, installation, basic usage
  2. API.md: Complete API reference with TypeScript signatures
  3. EXAMPLES.md: Code examples for common use cases
  4. ARCHITECTURE.md: Internal design and architecture
  5. CHANGELOG.md: Version history and breaking changes
  6. MIGRATION.md: Migration guides between major versions

Auto-Generated Docs:

  • TypeScript definitions β†’ TypeDoc
  • Rust code β†’ rustdoc
  • Examples β†’ Extracted from tests

C - Completion

5.1 Implementation Phases

Phase 1: Infrastructure Setup (Weeks 1-2)

  • Set up monorepo structure with pnpm workspaces
  • Configure napi-rs build system
  • Set up GitHub Actions CI/CD
  • Configure agentdb and claude-flow orchestration
  • Set up E2B sandbox templates
  • Create package templates and generators

Phase 2: Core Packages (Weeks 3-6)

  • Build foundational packages (15 core libraries)
    • ruv-fann, ruv-swarm-core, aimds-core, etc.
  • Set up cross-platform builds
  • Create comprehensive tests
  • Generate documentation

Phase 3: Extended Packages (Weeks 7-12)

  • Build dependent packages (50 libraries)
    • All *-cli, *-wasm, specialized tools
  • Set up package interdependencies
  • Performance optimization
  • Integration testing

Phase 4: Specialized Packages (Weeks 13-16)

  • Build domain-specific packages (45 libraries)
    • Trading suite, quantum computing, temporal systems
  • Advanced features and optimizations
  • Security audits
  • Performance benchmarks

Phase 5: Release & Distribution (Weeks 17-18)

  • Final testing and QA
  • Security audits
  • Performance benchmarks
  • Release all 110 packages to NPM
  • Publish documentation site
  • Announce release

5.2 Deliverables

Code Deliverables:

  • 110 NPM packages published to @ruv.io/* namespace
  • Source code in GitHub monorepo
  • Pre-built binaries for 7+ platforms
  • WASM fallback builds

Documentation Deliverables:

  • Main documentation site (docs.ruv.io)
  • API reference for all 110 packages
  • 200+ code examples
  • Migration guides
  • Architecture documentation

Infrastructure Deliverables:

  • Automated CI/CD pipelines
  • Package publishing automation
  • Dependency management system
  • Performance monitoring dashboard

Support Deliverables:

  • GitHub Issues templates
  • Contributing guidelines
  • Security policy
  • Code of conduct

5.3 Quality Gates

Each package must pass:

βœ… Build Quality:

  • Compiles on all target platforms
  • Zero compiler warnings
  • Passes all lint checks (clippy, eslint)

βœ… Test Quality:

  • 95%+ code coverage
  • All unit tests pass
  • All integration tests pass
  • Performance benchmarks meet targets

βœ… Documentation Quality:

  • API documentation complete
  • Examples provided
  • README comprehensive
  • TypeScript definitions accurate

βœ… Security Quality:

  • No known vulnerabilities
  • Dependency audit clean
  • Security policy documented

βœ… Performance Quality:

  • < 10ms NAPI overhead
  • Memory leak free
  • Thread safe

5.4 Success Metrics

Technical Metrics:

  • All 110 packages published: 0/110 βœ—
  • Test coverage: Target 95%
  • Platform support: 7+ platforms
  • Bundle size: < 5MB per package (avg)
  • Load time: < 100ms per package

Community Metrics:

  • NPM weekly downloads: Target 10K+
  • GitHub stars: Target 5K+
  • Active contributors: Target 50+
  • Issues resolved: Target < 48h response

Business Metrics:

  • Documentation site traffic: Target 100K/month
  • Package adoption rate: Target 20% YoY growth
  • Support tickets: Target < 5% of downloads

πŸ—οΈ Project Structure

ruv.io/
β”œβ”€β”€ README.md                          # This file
β”œβ”€β”€ ARCHITECTURE.md                    # Overall architecture
β”œβ”€β”€ CONTRIBUTING.md                    # Contribution guidelines
β”œβ”€β”€ LICENSE                            # MIT License
β”œβ”€β”€ package.json                       # Root package.json (workspace)
β”œβ”€β”€ pnpm-workspace.yaml               # pnpm workspace config
β”œβ”€β”€ tsconfig.json                      # Root TypeScript config
β”œβ”€β”€ .github/
β”‚   β”œβ”€β”€ workflows/
β”‚   β”‚   β”œβ”€β”€ ci.yml                    # Continuous integration
β”‚   β”‚   β”œβ”€β”€ release.yml               # Release automation
β”‚   β”‚   β”œβ”€β”€ test.yml                  # Test suite
β”‚   β”‚   └── publish.yml               # NPM publishing
β”‚   └── ISSUE_TEMPLATE/
β”‚       β”œβ”€β”€ bug_report.md
β”‚       └── feature_request.md
β”œβ”€β”€ packages/                          # All 110 NPM packages
β”‚   β”œβ”€β”€ agentic-jujutsu/
β”‚   β”œβ”€β”€ agentic-payments/
β”‚   β”œβ”€β”€ aimds-analysis/
β”‚   └── ... (107 more packages)
β”œβ”€β”€ plans/                             # Detailed implementation plans
β”‚   β”œβ”€β”€ 00-overview.md
β”‚   β”œβ”€β”€ 01-agentic-jujutsu.md
β”‚   β”œβ”€β”€ 02-agentic-payments.md
β”‚   └── ... (108 more plan files)
β”œβ”€β”€ scripts/                           # Build and automation scripts
β”‚   β”œβ”€β”€ bootstrap.sh                  # Initial setup
β”‚   β”œβ”€β”€ build-all.sh                  # Build all packages
β”‚   β”œβ”€β”€ test-all.sh                   # Test all packages
β”‚   β”œβ”€β”€ publish-all.sh                # Publish to NPM
β”‚   └── orchestrate.ts                # Claude-flow orchestration
β”œβ”€β”€ docs/                              # Documentation
β”‚   β”œβ”€β”€ getting-started.md
β”‚   β”œβ”€β”€ api-reference/
β”‚   β”œβ”€β”€ examples/
β”‚   └── architecture/
β”œβ”€β”€ tools/                             # Development tools
β”‚   β”œβ”€β”€ template-generator/           # Package template generator
β”‚   β”œβ”€β”€ dependency-analyzer/          # Dependency graph tools
β”‚   └── performance-monitor/          # Performance tracking
└── e2b/                              # E2B sandbox configurations
    β”œβ”€β”€ rust-napi-builder.Dockerfile
    └── sandbox-config.json

πŸš€ Quick Start

Prerequisites

# Install Node.js >= 16
nvm install 16

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install pnpm
npm install -g pnpm

# Install napi-rs CLI
npm install -g @napi-rs/cli

Setup

# Clone repository
git clone https://github.com/ruvnet/ruv.io.git
cd ruv.io

# Install dependencies
pnpm install

# Bootstrap all packages (run once)
./scripts/bootstrap.sh

Build Individual Package

# Build a single package
cd packages/ruv-fann
pnpm build

# Run tests
pnpm test

# Publish to NPM
pnpm publish

Build All Packages (with Orchestration)

# Using claude-flow orchestration
pnpm orchestrate:build

# Traditional sequential build
pnpm build:all

# Parallel build (faster)
pnpm build:parallel

πŸ€– Agent Orchestration

Claude Flow Integration

The project uses claude-flow for coordinating the build process across all 110 packages:

// scripts/orchestrate.ts
import { ClaudeFlow } from 'claude-flow'
import { AgentDB } from '@ruv.io/nt-agentdb-client'

const flow = new ClaudeFlow({
  agents: 110, // One per package
  coordination: 'hierarchical',
  memory: new AgentDB({
    uri: 'sqlite://agents.db'
  }),
  sandbox: {
    provider: 'e2b',
    apiKey: process.env.OPENROUTER_API_KEY
  }
})

await flow.execute('build-all-packages')

AgentDB Integration

AgentDB stores build state, dependencies, and coordination data:

import { AgentDB } from '@ruv.io/nt-agentdb-client'

const db = new AgentDB({
  connection: 'sqlite://agents.db',
  vectorStore: 'chroma'
})

// Store build results
await db.store({
  agent: 'builder-ruv-fann',
  result: buildResult,
  artifacts: ['ruv-fann.node', 'index.d.ts']
})

// Query dependencies
const deps = await db.query({
  package: 'ruv-swarm-ml',
  type: 'dependencies'
})

E2B Sandbox Strategy

Each package builds in an isolated E2B sandbox:

import { E2BSandbox } from '@e2b/sdk'

const sandbox = await E2BSandbox.create({
  template: 'rust-napi-builder',
  envVars: {
    OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
    CARGO_TARGET_DIR: '/tmp/target'
  },
  timeout: 3600 // 1 hour per package
})

// Execute build
await sandbox.process.start({
  cmd: 'cargo build --release'
})

// Download artifacts
const artifacts = await sandbox.downloadDir('./target/release')

πŸ“¦ Package Categories

AI/ML Systems (8 packages)

  • @ruv.io/aimds-core - AI Manipulation Defense System core
  • @ruv.io/aimds-detection - AIMDS detection layer
  • @ruv.io/aimds-analysis - AIMDS analysis layer
  • @ruv.io/aimds-response - AIMDS response layer
  • @ruv.io/daa-ai - DAA AI integration layer
  • @ruv.io/goalie - AI research assistant with GOAP planning
  • @ruv.io/veritas-nexus - Multi-modal lie detection system
  • @ruv.io/kimi-expert-analyzer - Expert analysis for Kimi-K2

Swarm Orchestration (16 packages)

  • @ruv.io/ruv-swarm-core - Core orchestration
  • @ruv.io/ruv-swarm-agents - Specialized agents
  • @ruv.io/ruv-swarm-cli - CLI for swarm management
  • @ruv.io/ruv-swarm-ml - ML integration
  • @ruv.io/code-mesh-core - Distributed swarm intelligence
  • ... (11 more packages)

Neural Networks (17 packages)

  • @ruv.io/ruv-fann - Fast Artificial Neural Network
  • @ruv.io/neuro-divergent - Neural forecasting library
  • @ruv.io/micro_core - Semantic Cartan Matrix implementation
  • @ruv.io/micro_cartan_attn - Cartan matrix attention
  • ... (13 more packages)

Trading/Finance (12 packages)

  • @ruv.io/nt-core - Neural Trader core
  • @ruv.io/nt-backtesting - Backtesting engine
  • @ruv.io/nt-execution - Order execution
  • @ruv.io/nt-portfolio - Portfolio management
  • ... (8 more packages)

Blockchain/Crypto (16 packages)

  • @ruv.io/qudag - Quantum-resistant DAG platform
  • @ruv.io/qudag-crypto - Quantum-resistant cryptography
  • @ruv.io/qudag-exchange - Token exchange
  • @ruv.io/claude_market - P2P Claude API token marketplace
  • ... (12 more packages)

[See /plans directory for complete package list]


πŸ“š Documentation

  • Getting Started: /docs/getting-started.md
  • API Reference: /docs/api-reference/
  • Examples: /docs/examples/
  • Architecture: /docs/architecture/
  • Individual Plans: /plans/*.md (110 detailed plans)

πŸ§ͺ Testing

# Run all tests
pnpm test:all

# Test specific package
cd packages/ruv-fann
pnpm test

# Run benchmarks
pnpm bench

# Coverage report
pnpm coverage

πŸ”’ Security

Security is a top priority. Please see SECURITY.md for:

  • Security policy
  • Vulnerability reporting
  • Audit results
  • Dependency scanning

🀝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

  • Code of conduct
  • Development workflow
  • Coding standards
  • Pull request process

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.


πŸ™ Acknowledgments

  • napi-rs - Amazing Rust ↔ Node.js FFI framework
  • Anthropic - Claude Flow orchestration
  • E2B - Sandbox infrastructure
  • crates.io - Rust package registry

πŸ“ž Contact


Status: 🚧 Planning Phase - Implementation starts [DATE]

Progress: 0/110 packages completed (0%)

Last Updated: 2025-11-13

About

One Library to Rule them all. npm @ruv.io/

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published