runeforge 25.8.0

# 🔥 Runeforge - Part of Rune* Ecosystem

[![Crates.io](https://img.shields.io/crates/v/runeforge)](https://crates.io/crates/runeforge)
[![Documentation](https://docs.rs/runeforge/badge.svg)](https://docs.rs/runeforge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![SBOM](https://img.shields.io/badge/SBOM-✓-green)](https://github.com/rune-ecosystem/forge/releases/latest)
[![Cosign](https://img.shields.io/badge/Cosign-✓-blue)](https://github.com/rune-ecosystem/forge)

**Blueprint to optimal stack JSON converter**

Runeforge v3 is a CLI tool that takes a Blueprint (requirements specification) and returns an optimal technology stack as JSON. The generated `plan.json` can be directly passed to RuneWeave v2 and later versions.

## Features

- ✅ Blueprint YAML/JSON → Optimal Stack JSON
- ✅ Deterministic plan generation with seeds
- ✅ Schema validation with JSON Schema
- ✅ Cost, latency, and compliance constraints
- ✅ Rust 2021 Edition, MSRV 1.80
- ✅ Ready for Rust 2025 Edition migration

## Installation

```bash
cargo install --path .
```

## Usage

### Basic Usage

```bash
runeforge plan -f blueprint.yaml --seed 42 --out plan.json
```

### CLI Options

```bash
runeforge plan \
  -f blueprint.yaml        # Required: Blueprint file (YAML or JSON)
  --seed 42                # Optional: Deterministic seed (default: 42)
  --out plan.json          # Optional: Output file (default: stdout)
  --strict                 # Optional: Enable strict schema validation
```

### Exit Codes

| Code | Meaning |
|------|---------|
| 0    | Success |
| 1    | Blueprint schema validation failed |
| 2    | Stack schema validation failed |
| 3    | No stack matches constraints |

## Blueprint Schema

```yaml
project_name: "my-app"
goals: 
  - "high-performance"
  - "low-cost"

constraints:
  monthly_cost_usd_max: 100.0
  coldstart_ms_max: 50.0
  persistence: "both"  # kv | sql | both
  region_allow:
    - "us-east-1"
    - "eu-west-1"
  compliance:
    - "audit-log"
    - "sbom"

traffic_profile:
  rps_peak: 1000.0
  global: true
  latency_sensitive: false

prefs:  # Optional preferences
  frontend: ["SvelteKit", "Next.js"]
  backend: ["Actix Web 4", "Axum"]
  database: ["PlanetScale"]
  ai: ["RuneSage", "OpenAI"]

single_language_mode: "rust"  # rust | go | ts | null
```

## Generated Stack Schema

```json
{
  "decisions": [
    {
      "topic": "backend",
      "choice": "Actix Web 4.11",
      "reasons": ["最高 RPS", "Tokio 1.47 安定"],
      "alternatives": ["Axum"]
    }
  ],
  "stack": {
    "language": "Rust",
    "frontend": "SvelteKit 2",
    "backend": "Actix Web 4.11",
    "database": "PlanetScale Boost",
    "cache": "Cloudflare KV",
    "queue": "NATS JetStream 0.37",
    "auth": "Passkeys(OIDC)",
    "payments": "RuneVault → Stripe",
    "ai": ["RuneSage", "OpenAI GPT-4o"],
    "infra": "Terraform + Cloudflare Workers",
    "ci_cd": "GitHub Actions"
  },
  "estimated": {
    "monthly_cost_usd": 110.0
  },
  "slo": {
    "availability_pct": 99.95,
    "p95_ms": {
      "read": 800.0,
      "write": 1200.0
    }
  },
  "risk": [
    {
      "id": "r1",
      "desc": "Workers で TCP 制限",
      "mitigation": "`connect()` API 経由で HTTP 化"
    }
  ]
}
```

## Examples

The repository includes three test cases:

### Baseline (Low Cost)
```bash
runeforge plan -f examples/baseline.yaml --seed 42
```

### Latency Optimized
```bash
runeforge plan -f examples/latency.yaml --seed 42
```

### Compliance Heavy
```bash
runeforge plan -f examples/compliance.yaml --seed 42
```

## Selection Algorithm

1. **Normalize** - Fill in Blueprint defaults
2. **Filter** - Remove candidates that don't meet constraints
3. **Score** - Calculate weighted scores:
   - Quality: 30%
   - SLO: 25% 
   - Cost: 20%
   - Security: 15%
   - Operations: 10%
4. **Select** - Choose highest scoring candidates
5. **Validate** - Ensure output matches schema

## Development

### Prerequisites

- Rust 1.80+
- Standard development tools

### Build

```bash
cargo build --release
```

### Test

```bash
cargo test
```

### Run Examples

```bash
# Test baseline scenario
cargo run -- plan -f examples/baseline.yaml --seed 42

# Test with strict validation  
cargo run -- plan -f examples/latency.yaml --seed 42 --strict

# Output to file
cargo run -- plan -f examples/compliance.yaml --seed 42 --out output.json
```

## Architecture

```
src/
├── main.rs       # CLI interface (clap)
├── selector.rs   # Stack selection logic  
├── schema.rs     # Schema validation & types
└── util.rs       # Utilities (hash, random, etc.)

resources/
└── rules.yaml    # Candidate definitions & weights

schemas/
├── blueprint.schema.json
└── stack.schema.json

examples/
├── baseline.yaml      # Low cost scenario
├── latency.yaml       # Ultra-low latency
└── compliance.yaml    # Enterprise compliance
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure `cargo test` passes
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) for details.

## Changelog

### v3.0.0 (2025-08-06)
- Initial release
- Blueprint → Stack JSON conversion
- Deterministic selection with seeds
- Schema validation support
- Rust 2021 Edition, MSRV 1.80