@raven-js/soar 🦅

Surgical precision deployment - Zero-dependency deployment tool for modern JavaScript applications

Soar provides surgical precision deployment capabilities for any artifact to any target. Built with zero external dependencies and leveraging modern Node.js primitives, it offers the sharp tools needed to deploy static sites, scripts, and binaries with the intelligence and efficiency ravens are known for.

Quick Start

# Install
npm install -D @raven-js/soar

# Deploy static site to Cloudflare Workers (no config needed!)
npx soar deploy --static ./dist --cloudflare-workers my-app

# Or use a config file
npx soar deploy raven.soar.js

# Plan deployment first (dry-run)
npx soar plan --static ./dist --cf-workers my-app --verbose

Artifact Types

Soar is tech-agnostic and can deploy any type of build output:

🗂️ Static Sites

Deploy pre-built static files (HTML, CSS, JS, assets).

Perfect for:

• Fledge SSG output (fledge build)
• React/Vue/Angular builds (npm run build)
• Vite/Webpack/Parcel bundles
• Jekyll/Hugo/Gatsby sites
• Any static file collection

Example:

// raven.soar.js
export default {
  artifact: {
    type: "static",
    path: "./dist",
    exclude: ["*.map", "node_modules/**"],
  },
  target: {
    name: "cloudflare-workers",
    scriptName: "my-site",
  },
};

📦 Script Bundles (Coming Soon)

Deploy server-side JavaScript applications and functions.

Perfect for:

• Node.js applications
• Serverless functions
• API endpoints
• Background workers

🔧 Binary Artifacts (Coming Soon)

Deploy compiled binaries and executables.

Perfect for:

• Go/Rust/C++ applications
• Container images
• System services
• CLI tools

Deployment Targets

☁️ Cloudflare Workers (Current)

Deploy static sites using Cloudflare Workers Static Assets.

Features:

• ✅ Free tier friendly - 100,000 requests/day
• ✅ Global CDN - 300+ edge locations
• ✅ Custom domains - Bring your own domain
• ✅ HTTPS by default - Automatic SSL certificates
• ✅ Zero config - Works out of the box

Setup:

1. Get API token: Cloudflare Dashboard → My Profile → API Tokens
2. Set environment variables:

   export CF_API_TOKEN="your-api-token"
   export CF_ACCOUNT_ID="your-account-id"

3. Deploy:

   npx soar deploy --static ./dist --cf-workers my-site

🌊 AWS S3 + CloudFront (Coming Soon)

Deploy to AWS with global CDN distribution.

🐙 DigitalOcean (Coming Soon)

Deploy to Spaces (static) and Droplets (servers).

🚀 Custom VPS (Coming Soon)

Deploy to any Linux server via SSH.

CLI Usage

Soar follows Unix philosophy with multiple input methods:

🔧 Flag-Based (No Config File)

# Static to Cloudflare Workers
soar deploy --static ./dist --cloudflare-workers my-app

# With custom settings
soar deploy --static ./dist --cf-workers my-app \
  --cf-account $CF_ACCOUNT_ID \
  --cf-token $CF_API_TOKEN

📄 Config File

# Default config
soar deploy

# Specific config file
soar deploy raven.soar.js

# Named export (environments)
soar deploy raven.soar.js:production

🔄 Piped Input (Unix Style)

# Generate config dynamically
echo "export default {
  artifact: { type: 'static', path: './dist' },
  target: { name: 'cloudflare-workers', scriptName: 'my-app' }
}" | soar deploy

📋 Planning (Dry-Run)

# Plan deployment without executing
soar plan --static ./dist --cf-workers my-app --verbose

# Plan with config file
soar plan raven.soar.js:staging

Configuration

Basic Config

// raven.soar.js
export default {
  artifact: {
    type: "static",
    path: "./dist",
  },
  target: {
    name: "cloudflare-workers",
    scriptName: "my-production-site",
    accountId: process.env.CF_ACCOUNT_ID,
    apiToken: process.env.CF_API_TOKEN,
    compatibilityDate: "2024-01-01",
  },
};

Multi-Environment Config

// raven.soar.js
const base = {
  artifact: { type: "static", path: "./dist" },
};

export default {
  ...base,
  target: {
    name: "cloudflare-workers",
    scriptName: "my-site-dev",
  },
};

export const production = {
  ...base,
  target: {
    name: "cloudflare-workers",
    scriptName: "my-site-prod",
    dispatchNamespace: "production",
  },
};

export const staging = {
  ...base,
  target: {
    name: "cloudflare-workers",
    scriptName: "my-site-staging",
  },
};

Advanced Static Config

// raven.soar.js
export default {
  artifact: {
    type: "static",
    path: "./dist",
    exclude: [
      "*.map", // Source maps
      "*.md", // Markdown files
      "node_modules/**", // Dependencies
      ".env*", // Environment files
    ],
  },
  target: {
    name: "cloudflare-workers",
    scriptName: "my-optimized-site",
    compatibilityDate: "2024-01-01",
  },
};

Programmatic API

import { deploy, plan } from "@raven-js/soar";

// Deploy with config object
const result = await deploy({
  artifact: { type: "static", path: "./dist" },
  target: { name: "cloudflare-workers", scriptName: "my-app" },
});

console.log(`✅ Deployed to: ${result.url}`);

// Plan deployment (dry-run)
const deploymentPlan = await plan("./raven.soar.js");
console.log(`📊 Files: ${deploymentPlan.artifact.manifest.fileCount}`);
console.log(
  `📦 Size: ${Math.round(deploymentPlan.artifact.manifest.totalSize / 1024)}KB`
);

// Deploy with named export
const prodResult = await deploy("./raven.soar.js", "production");

Integration with Fledge

Soar works seamlessly with Fledge static site generator:

// raven.fledge.js
export default {
  server: "http://localhost:3000",
  routes: ["/", "/about", "/contact"],
  output: "./dist",
  discover: true,
};

// raven.soar.js
export default {
  artifact: {
    type: "static",
    path: "./dist", // Fledge output directory
  },
  target: {
    name: "cloudflare-workers",
    scriptName: "my-fledge-site",
  },
};

# Build and deploy pipeline
fledge static && soar deploy

Environment Variables

# Cloudflare Workers
CF_API_TOKEN="your-cloudflare-api-token"
CF_ACCOUNT_ID="your-cloudflare-account-id"

# Debug mode
DEBUG=1  # Show detailed error information

Commands

# Deployment
soar deploy [config] [options]     # Deploy artifact to target
soar plan [config] [options]       # Plan deployment (dry-run)

# Information
soar version                       # Show version
soar help [command]               # Show help

# Coming Soon
soar validate [config]            # Validate configuration
soar list [--provider <name>]     # List deployed resources
soar show <resource-name>         # Show resource details
soar destroy <resource-name>      # Destroy specific resource

Roadmap

🚀 Next Release (v0.5)

• Script deployment - Deploy Node.js functions to serverless platforms
• AWS S3 + CloudFront - Static site deployment with global CDN
• Binary deployment - Deploy compiled applications to VPS

🌟 Future Releases

• DigitalOcean integration - Spaces and Droplets support
• Custom VPS deployment - SSH-based deployment to any Linux server
• Docker container deployment - Container registry and orchestration
• Resource management - List, inspect, and destroy deployed resources
• Rollback capabilities - Quick rollback to previous deployments
• Deployment analytics - Performance and usage insights

Philosophy

Soar embodies the RavenJS CODEX principles:

• 🎯 Surgical Precision - Minimal, focused, efficient deployments
• ⚡ Zero Dependencies - No supply chain vulnerabilities
• 🔧 Platform Mastery - Built on Node.js primitives and native APIs
• 🧠 Algorithm Over Patches - Clean solutions, not quick fixes
• 📐 Lean Architecture - One file per concept, testable functions

Examples

See the examples/ directory for complete deployment examples:

• Static Site - Complete Cloudflare Workers deployment
• Script Bundle (Coming Soon) - Serverless function deployment
• Binary Application (Coming Soon) - VPS deployment example

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT - see LICENSE file for details.