pforge: EXTREME TDD for MCP Servers

Build production-ready Model Context Protocol servers with zero boilerplate and radical quality enforcement

Zero Boilerplate. Extreme Quality. Sub-Microsecond Performance.

pforge is a declarative framework for building MCP servers using pure YAML configuration - powered by EXTREME Test-Driven Development methodology and enforced by PMAT quality gates.

What You’ll Learn

• EXTREME TDD: 5-minute RED-GREEN-REFACTOR cycles with zero tolerance quality gates
• Toyota Production System: Apply Lean manufacturing principles to software development
• MCP Server Development: Build tools, resources, and prompts with type safety
• Quality Enforcement: Pre-commit hooks, complexity analysis, mutation testing
• Production Performance: <1μs dispatch, >100K req/s throughput, <100ms cold start

Who This Book Is For

• MCP developers wanting to ship faster with higher quality
• TDD practitioners seeking a more disciplined, time-boxed approach
• Quality engineers interested in automated quality enforcement
• Rust developers building high-performance tooling

The pforge Philosophy

“Quality is not an act, it is a habit.” - Aristotle

pforge enforces quality through automation, not willpower:

• Pre-commit hooks block low-quality code
• 5-minute TDD cycles prevent complexity
• PMAT metrics track technical debt
• Property tests verify invariants
• Mutation tests validate test quality

Current Status

• Version: 0.1.0-alpha
• Test Coverage: 80.54%
• TDG Score: 96/100 (A+)
• Tests: 115 passing (100% pass rate)
• Complexity: Max 9 (target: <20)

License: MIT Repository: github.com/paiml/pforge Authors: Pragmatic AI Labs

Introduction

Welcome to pforge - a radical approach to building Model Context Protocol (MCP) servers that combines declarative configuration with EXTREME Test-Driven Development.

The Problem

Building MCP servers traditionally requires:

• Hundreds of lines of boilerplate code
• Manual type safety management
• Ad-hoc quality processes
• Slow development cycles
• Runtime performance tradeoffs

The Solution

pforge eliminates boilerplate and enforces quality through three pillars:

1. Zero-Boilerplate Configuration

Define your entire MCP server in <10 lines of YAML:

forge:
  name: my-server
  version: 0.1.0

tools:
  - type: native
    name: greet
    description: "Greet a person"
    handler:
      path: handlers::greet
    params:
      name: { type: string, required: true }

2. EXTREME Test-Driven Development

5-minute cycles with strict enforcement:

1. RED (2 min): Write failing test
2. GREEN (2 min): Minimum code to pass
3. REFACTOR (1 min): Clean up, run quality gates
4. COMMIT: If gates pass
5. RESET: If cycle exceeds 5 minutes

Quality gates automatically block commits that violate:

• Code formatting (rustfmt)
• Linting (clippy -D warnings)
• Test failures
• Complexity >20
• Coverage <80%
• TDG score <75

3. Production Performance

pforge delivers world-class performance through compile-time optimization:

The EXTREME TDD Philosophy

Traditional TDD says “write tests first.” EXTREME TDD says:

“Quality gates block bad code. Time limits prevent complexity. Automation enforces discipline.”

Key principles:

• Jidoka (Stop the Line): Quality failures halt development immediately
• Kaizen (Continuous Improvement): Every cycle improves the system
• Waste Elimination: Time-boxing prevents gold-plating
• Amplify Learning: Tight feedback loops accelerate mastery

What Makes pforge Different?

vs. Traditional MCP SDKs

• No boilerplate: YAML vs hundreds of lines of code
• Compile-time safety: Rust type system vs runtime checks
• Performance: <1μs dispatch vs milliseconds

vs. Traditional TDD

• Time-boxed: 5-minute cycles vs indefinite
• Automated gates: Pre-commit hooks vs manual checks
• Zero tolerance: Complexity/coverage enforced vs aspirational

vs. Quality Tools

• Integrated: PMAT built-in vs separate tools
• Blocking: Pre-commit enforcement vs reports
• Proactive: Prevent vs detect

Who Should Read This Book?

This book is for you if you want to:

• Build MCP servers 10x faster
• Ship production code with confidence
• Master EXTREME TDD methodology
• Achieve <1μs performance targets
• Automate quality enforcement

Prerequisites

• Basic Rust knowledge (or willingness to learn)
• Familiarity with Test-Driven Development
• Understanding of Model Context Protocol basics

How to Read This Book

Part I (Chapters 1-3): Learn the EXTREME TDD philosophy

• Start here if you’re new to disciplined TDD
• Understand the “why” before the “how”

Part II (Chapters 4-8): Build your first MCP server

• Hands-on tutorials with TDD examples
• Each chapter follows RED-GREEN-REFACTOR

Part III (Chapters 9-12): Master advanced features

• State management, fault tolerance, middleware
• Real-world patterns and anti-patterns

Part IV (Chapters 13-16): Quality & testing mastery

• Unit, integration, property, mutation testing
• Achieve 90%+ mutation kill rate

Part V (Chapters 17-18): Performance optimization

• Sub-microsecond dispatch
• Compile-time code generation

Part VI (Chapters 19-20): Production deployment

• CI/CD, multi-language bridges
• Enterprise patterns

Part VII (Chapters 21-24): Real case studies

• PMAT server, data pipelines, GitHub integration
• Learn from production examples

Code Examples

All code in this book is:

• ✅ Tested: 100% test coverage
• ✅ Working: Verified in CI/CD
• ✅ Quality-checked: Passed PMAT gates
• ✅ Performant: Benchmarked

Example code follows this format:

// Filename: src/handlers.rs
use pforge_runtime::{Handler, Result};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    name: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct GreetOutput {
    message: String,
}

pub struct GreetHandler;

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("Hello, {}!", input.name)
        })
    }
}

Getting Help

• Repository: github.com/paiml/pforge
• Issues: github.com/paiml/pforge/issues
• Specification: See docs/specifications/pforge-specification.md

Let’s Begin

The journey to EXTREME TDD starts with understanding why strict discipline produces better results than raw talent. Turn the page to discover the philosophy that powers pforge…

“The only way to go fast is to go well.” - Robert C. Martin (Uncle Bob)

Chapter 1: pforge vs pmcp (rust-mcp-sdk)

Both pforge and pmcp (Pragmatic Model Context Protocol SDK, also known as rust-mcp-sdk) are Rust implementations for building MCP servers, created by the same team at Pragmatic AI Labs. However, they serve fundamentally different use cases.

The Key Difference

pmcp is a library/SDK - you write Rust code to build your MCP server.

pforge is a framework - you write YAML configuration and optional Rust handlers.

Think of it like this:

• pmcp ≈ Express.js (you write code)
• pforge ≈ Cargo Lambda (you write config + minimal code)

Quick Comparison Table

Side-by-Side Example

The Same Calculator Tool

With pmcp (rust-mcp-sdk):

// main.rs (~60 lines)
use pmcp::{ServerBuilder, TypedTool};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
struct CalculatorArgs {
    operation: String,
    a: f64,
    b: f64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = ServerBuilder::new()
        .name("calculator-server")
        .version("1.0.0")
        .tool_typed("calculate", |args: CalculatorArgs, _extra| {
            Box::pin(async move {
                let result = match args.operation.as_str() {
                    "add" => args.a + args.b,
                    "subtract" => args.a - args.b,
                    "multiply" => args.a * args.b,
                    "divide" => {
                        if args.b == 0.0 {
                            return Err(pmcp::Error::Validation(
                                "Division by zero".into()
                            ));
                        }
                        args.a / args.b
                    }
                    _ => return Err(pmcp::Error::Validation(
                        "Unknown operation".into()
                    )),
                };
                Ok(serde_json::json!({ "result": result }))
            })
        })
        .build()?;

    // Run server with stdio transport
    server.run_stdio().await?;
    Ok(())
}

With pforge:

# forge.yaml (8 lines)
forge:
  name: calculator-server
  version: 1.0.0

tools:
  - type: native
    name: calculate
    description: "Perform arithmetic operations"
    handler:
      path: handlers::calculate
    params:
      operation: { type: string, required: true }
      a: { type: float, required: true }
      b: { type: float, required: true }

// src/handlers.rs (~25 lines)
use pforge_runtime::{Handler, Result, Error};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    operation: String,
    a: f64,
    b: f64,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalculateOutput {
    result: f64,
}

pub struct CalculateHandler;

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalculateInput;
    type Output = CalculateOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let result = match input.operation.as_str() {
            "add" => input.a + input.b,
            "subtract" => input.a - input.b,
            "multiply" => input.a * input.b,
            "divide" => {
                if input.b == 0.0 {
                    return Err(Error::Handler("Division by zero".into()));
                }
                input.a / input.b
            }
            _ => return Err(Error::Handler("Unknown operation".into())),
        };
        Ok(CalculateOutput { result })
    }
}

# Run it
pforge serve

When to Use Each

Use pforge when:

✅ You’re building standard MCP servers (tools, resources, prompts) ✅ You want minimal boilerplate ✅ You need fast iteration (change YAML, no recompile) ✅ You want built-in quality gates and TDD methodology ✅ You’re wrapping CLIs, HTTP APIs, or simple logic ✅ You want sub-microsecond tool dispatch ✅ You’re new to Rust (simpler to get started) ✅ You want enforced best practices

Examples:

• CLI tool wrappers (git, docker, kubectl)
• HTTP API proxies (GitHub, Slack, AWS)
• Simple data transformations
• Multi-tool pipelines

Use pmcp when:

✅ You need complete control over server logic ✅ You’re implementing complex stateful behavior ✅ You need custom transport implementations ✅ You’re building a library/SDK for others ✅ You need features not in pforge’s 4 handler types ✅ You want to publish a general-purpose MCP server ✅ You’re comfortable with full Rust development

Examples:

• Database servers with custom query logic
• Real-time collaborative servers
• Custom protocol extensions
• Servers with complex state machines
• WebAssembly/browser-based servers

Can I Use Both Together?

Yes! You can:

1. Start with pforge, then migrate complex tools to pmcp
2. Use pmcp for the core, pforge for simple wrappers
3. Publish pmcp handlers that pforge can use

Example: Use pforge for 90% of simple tools, drop down to pmcp for the 10% that need custom logic.

Performance Comparison

Why is pforge faster for dispatch?

• Compile-time code generation with perfect hashing
• Zero dynamic lookups
• Inlined handler calls

Why is pmcp faster for cold start?

• No code generation step
• Simpler binary

Code Size Comparison

For a typical 10-tool MCP server:

• pforge: ~50 lines YAML + ~200 lines handlers = ~250 lines total
• pmcp: ~500-800 lines Rust (including boilerplate)

Quality & Testing

Migration Path

pmcp → pforge

If you have a pmcp server and want to try pforge:

1. Extract your tool logic into handlers
2. Create forge.yaml config
3. Test with pforge serve

pforge → pmcp

If you need more flexibility:

1. Use your pforge handlers as-is
2. Replace YAML with ServerBuilder code
3. Add custom logic as needed

Real-World Usage

pforge in production:

• PMAT code analysis server (pforge wraps pmat CLI)
• GitHub webhook server (pforge proxies GitHub API)
• Data pipeline orchestrator (pforge chains tools)

pmcp in production:

• Browser-based REPL (WebAssembly, custom logic)
• Database query server (complex state, transactions)
• Real-time collaboration (WebSocket, stateful)

Summary

Choose based on your needs:

• Quick standard MCP server? → pforge
• Complex custom logic? → pmcp
• Not sure? → Start with pforge, migrate to pmcp if needed

Both are production-ready, both support crates.io publishing, and both are maintained by the same team.

Next: When to Use pforge

Chapter 1.1: When to Use pforge

This chapter provides detailed guidance on when pforge is the right choice for your MCP server project.

The pforge Sweet Spot

pforge is designed for standard MCP server patterns with minimal boilerplate. If you’re building a server that fits common use cases, pforge will save you significant time and enforce best practices automatically.

Use pforge When…

1. You’re Wrapping Existing Tools

pforge excels at wrapping CLIs, HTTP APIs, and simple logic into MCP tools.

Examples:

# Wrap Git commands
tools:
  - type: cli
    name: git_status
    description: "Get git repository status"
    command: git
    args: ["status", "--porcelain"]

  - type: cli
    name: git_commit
    description: "Commit changes"
    command: git
    args: ["commit", "-m", "{{message}}"]

# Wrap HTTP APIs
tools:
  - type: http
    name: github_create_issue
    description: "Create a GitHub issue"
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: POST
    headers:
      Authorization: "Bearer {{GITHUB_TOKEN}}"

Why pforge wins here:

• No need to write subprocess handling code
• No need to write HTTP client code
• Built-in error handling and retries
• Configuration changes don’t require recompilation

2. You Want Fast Iteration

With pforge, changing your server is as simple as editing YAML:

# Before: tool with 30s timeout
tools:
  - type: native
    name: slow_operation
    timeout_ms: 30000

# After: increased to 60s - no code changes, no recompile
tools:
  - type: native
    name: slow_operation
    timeout_ms: 60000

Development cycle:

• pmcp: Edit code → Recompile → Test (2-5 minutes)
• pforge: Edit YAML → Restart (5-10 seconds)

3. You Need Built-in Quality Gates

pforge comes with PMAT integration and enforced quality standards:

# Automatically enforced pre-commit
$ git commit -m "Add new tool"

Running quality gates:
✓ cargo fmt --check
✓ cargo clippy -- -D warnings
✓ cargo test --all
✓ coverage ≥ 80%
✓ complexity ≤ 20
✓ no SATD comments
✓ TDG ≥ 0.75

Commit allowed ✓

What you get:

• Zero unwrap() in production code
• No functions with cyclomatic complexity > 20
• 80%+ test coverage enforced
• Mutation testing integrated
• Automatic code quality checks

4. You’re Building Standard CRUD Operations

pforge’s handler types cover most common patterns:

tools:
  # Native handlers for business logic
  - type: native
    name: validate_user
    handler:
      path: handlers::validate_user
    params:
      email: { type: string, required: true }

  # CLI handlers for external tools
  - type: cli
    name: run_tests
    command: pytest
    args: ["tests/"]

  # HTTP handlers for API proxies
  - type: http
    name: fetch_user_data
    endpoint: "https://api.example.com/users/{{user_id}}"
    method: GET

  # Pipeline handlers for composition
  - type: pipeline
    name: validate_and_fetch
    steps:
      - tool: validate_user
        output: validation_result
      - tool: fetch_user_data
        condition: "{{validation_result.valid}}"

5. You Want Sub-Microsecond Tool Dispatch

pforge uses compile-time code generation with perfect hashing:

Benchmark: Tool Dispatch Latency
================================
pmcp (HashMap):     8.2μs ± 0.3μs
pforge (perfect hash): 0.7μs ± 0.1μs

Speedup: 11.7x faster

How it works:

• YAML configuration → Rust code generation
• Perfect hash function computed at compile time
• Zero dynamic lookups
• Inlined handler calls

6. You’re New to Rust

pforge has a gentler learning curve:

What you need to know:

Minimal:

• YAML syntax (everyone knows this)
• Basic struct definitions for native handlers
• async/await for async handlers

You don’t need to know:

• pmcp API details
• MCP protocol internals
• Transport layer implementation
• JSON-RPC message handling

Example - Complete pforge server:

# forge.yaml - 10 lines
forge:
  name: my-server
  version: 0.1.0

tools:
  - type: native
    name: greet
    handler:
      path: handlers::greet
    params:
      name: { type: string, required: true }

// src/handlers.rs - 20 lines
use pforge_runtime::{Handler, Result, Error};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    name: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct GreetOutput {
    message: String,
}

pub struct GreetHandler;

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("Hello, {}!", input.name)
        })
    }
}

pub use GreetHandler as greet;

# Run it
$ pforge serve

7. You Need Multi-Tool Pipelines

pforge supports declarative tool composition:

tools:
  - type: pipeline
    name: analyze_and_report
    description: "Analyze code and generate report"
    steps:
      - tool: run_linter
        output: lint_results

      - tool: run_tests
        output: test_results

      - tool: generate_report
        condition: "{{lint_results.passed}} && {{test_results.passed}}"
        inputs:
          lint: "{{lint_results}}"
          tests: "{{test_results}}"

      - tool: send_notification
        condition: "{{lint_results.passed}}"
        on_error: continue

Benefits:

• Declarative composition
• Conditional execution
• Error handling strategies
• Output passing between steps

8. You Want State Management Out of the Box

pforge provides persistent state with zero configuration:

state:
  backend: sled
  path: /tmp/my-server-state
  cache_size: 1000

// In your handler
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Get state
    let counter = self.state
        .get("counter")
        .await?
        .and_then(|bytes| String::from_utf8(bytes).ok())
        .and_then(|s| s.parse::<u64>().ok())
        .unwrap_or(0);

    // Increment
    let new_counter = counter + 1;

    // Save state
    self.state
        .set("counter", new_counter.to_string().into_bytes(), None)
        .await?;

    Ok(MyOutput { counter: new_counter })
}

State backends:

• Sled: Persistent embedded database (default)
• Memory: In-memory with DashMap (testing)
• Redis: Distributed state (future)

9. You Want Enforced Best Practices

pforge enforces patterns from day one:

Error handling:

// ❌ Not allowed in pforge
let value = map.get("key").unwrap();  // Compile error!

// ✅ Required pattern
let value = map.get("key")
    .ok_or_else(|| Error::Handler("Key not found".into()))?;

Async by default:

// All handlers are async - no blocking allowed
#[async_trait::async_trait]
impl Handler for MyHandler {
    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        // Non-blocking I/O enforced
        let data = tokio::fs::read_to_string("data.txt").await?;
        Ok(MyOutput { data })
    }
}

Type safety:

params:
  age: { type: integer, required: true }  # Compile-time checked

pub struct Input {
    age: i64,  // Not Option<i64> - required enforced at compile time
}

Real-World Use Cases

Case Study 1: PMAT Code Analysis Server

Challenge: Wrap the PMAT CLI tool as an MCP server

Solution:

tools:
  - type: cli
    name: analyze_complexity
    command: pmat
    args: ["analyze", "complexity", "--file", "{{file_path}}"]

  - type: cli
    name: analyze_satd
    command: pmat
    args: ["analyze", "satd", "--file", "{{file_path}}"]

Results:

• 10 lines of YAML (vs ~200 lines of Rust with pmcp)
• No subprocess handling code
• Automatic error handling
• Built-in retry logic

Case Study 2: GitHub API Proxy

Challenge: Expose GitHub API operations as MCP tools

Solution:

tools:
  - type: http
    name: create_issue
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: POST
    headers:
      Authorization: "Bearer {{GITHUB_TOKEN}}"
      Accept: "application/vnd.github.v3+json"

  - type: http
    name: list_pull_requests
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/pulls"
    method: GET

Results:

• No HTTP client code
• Automatic connection pooling (reqwest)
• Built-in authentication
• Retry on network errors

Case Study 3: Data Pipeline Orchestrator

Challenge: Chain multiple data processing tools

Solution:

tools:
  - type: pipeline
    name: process_data
    steps:
      - tool: extract_data
        output: raw_data
      - tool: transform_data
        inputs:
          data: "{{raw_data}}"
        output: transformed
      - tool: load_data
        inputs:
          data: "{{transformed}}"

Results:

• Declarative pipeline definition
• Automatic error recovery
• Step-by-step logging
• Conditional execution

Performance Characteristics

When pforge Might NOT Be the Best Choice

pforge is not ideal when:

1. You need custom MCP protocol extensions

   • pforge uses standard MCP features only
   • Drop down to pmcp for custom protocol work

2. You need complex stateful logic

   • Example: Database query planner with transaction management
   • pmcp gives you full control

3. You need custom transport implementations

   • pforge supports stdio/SSE/WebSocket
   • Custom transports require pmcp

4. You’re building a library/SDK

   • pforge is for applications, not libraries
   • Use pmcp for reusable components

5. You need WebAssembly compilation

   • pforge targets native binaries
   • pmcp can compile to WASM

See Chapter 1.2: When to Use pmcp for these cases.

Migration Path

Start with pforge, migrate to pmcp when needed:

// Start with pforge handlers
pub struct MyHandler;

#[async_trait::async_trait]
impl pforge_runtime::Handler for MyHandler {
    // ... pforge handler impl
}

// Later, use same handler in pmcp
use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("my-server")
        .tool_typed("my_tool", |input: MyInput, _extra| {
            Box::pin(async move {
                let handler = MyHandler;
                let output = handler.handle(input).await?;
                Ok(serde_json::to_value(output)?)
            })
        })
        .build()?;

    server.run_stdio().await
}

Key insight: pforge handlers are compatible with pmcp!

Summary

Use pforge when you want:

✅ Minimal boilerplate ✅ Fast iteration (YAML changes) ✅ Built-in quality gates ✅ CLI/HTTP/Pipeline handlers ✅ Sub-microsecond dispatch ✅ Gentle learning curve ✅ State management included ✅ Enforced best practices

Use pmcp when you need:

❌ Custom protocol extensions ❌ Complex stateful logic ❌ Custom transports ❌ Library/SDK development ❌ WebAssembly compilation

Not sure? Start with pforge. You can always drop down to pmcp later.

Next: When to Use pmcp Directly

Chapter 1.2: When to Use pmcp Directly

This chapter explores scenarios where using pmcp (rust-mcp-sdk) directly is the better choice than pforge.

The pmcp Sweet Spot

pmcp is a low-level SDK that gives you complete control over your MCP server. Use it when pforge’s abstraction layer gets in the way of what you’re trying to achieve.

Use pmcp When…

1. You Need Custom MCP Protocol Extensions

pmcp lets you implement custom protocol features not in the standard MCP spec:

use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("custom-server")
        .version("1.0.0")

        // Custom JSON-RPC method
        .custom_method("custom/analyze", |params| {
            Box::pin(async move {
                // Your custom protocol logic
                let result = custom_analysis(params).await?;
                Ok(serde_json::to_value(result)?)
            })
        })

        // Custom notification handler
        .on_notification("custom/event", |params| {
            Box::pin(async move {
                handle_custom_event(params).await
            })
        })

        .build()?;

    server.run_stdio().await
}

Why pmcp wins:

• Full control over JSON-RPC messages
• Custom method registration
• Direct access to transport layer
• No framework constraints

2. You Need Complex Stateful Logic

pmcp gives you full control over server state and lifecycle:

use pmcp::ServerBuilder;
use std::sync::Arc;
use tokio::sync::RwLock;

// Complex application state
struct AppState {
    db_pool: sqlx::PgPool,
    cache: Arc<RwLock<HashMap<String, CachedValue>>>,
    query_planner: QueryPlanner,
    transaction_log: Arc<Mutex<Vec<Transaction>>>,
}

#[tokio::main]
async fn main() -> Result<()> {
    let state = Arc::new(AppState {
        db_pool: create_pool().await?,
        cache: Arc::new(RwLock::new(HashMap::new())),
        query_planner: QueryPlanner::new(),
        transaction_log: Arc::new(Mutex::new(Vec::new())),
    });

    let server = ServerBuilder::new()
        .name("database-server")
        .tool_typed("execute_query", {
            let state = state.clone();
            move |args: QueryArgs, _extra| {
                let state = state.clone();
                Box::pin(async move {
                    // Complex transactional logic
                    let mut tx = state.db_pool.begin().await?;

                    // Log transaction
                    state.transaction_log.lock().await.push(Transaction {
                        query: args.sql.clone(),
                        timestamp: Utc::now(),
                    });

                    // Execute with query planner
                    let plan = state.query_planner.plan(&args.sql)?;
                    let result = execute_plan(&mut tx, plan).await?;

                    // Update cache
                    state.cache.write().await.insert(
                        cache_key(&args),
                        CachedValue { result: result.clone(), ttl: Instant::now() }
                    );

                    tx.commit().await?;
                    Ok(serde_json::to_value(result)?)
                })
            }
        })
        .build()?;

    server.run_stdio().await
}

Why pmcp wins:

• Full lifecycle control
• Complex state management
• Custom transaction handling
• Direct database integration

3. You Need Custom Transport Implementations

pmcp supports custom transports beyond stdio/SSE/WebSocket:

use pmcp::{Server, Transport};

// Custom Unix domain socket transport
struct UnixSocketTransport {
    socket_path: PathBuf,
}

#[async_trait::async_trait]
impl Transport for UnixSocketTransport {
    async fn run(&self, server: Server) -> Result<()> {
        let listener = UnixListener::bind(&self.socket_path)?;

        loop {
            let (stream, _) = listener.accept().await?;
            let server = server.clone();

            tokio::spawn(async move {
                handle_connection(server, stream).await
            });
        }
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("unix-socket-server")
        .tool_typed("process", |args, _| { /* ... */ })
        .build()?;

    let transport = UnixSocketTransport {
        socket_path: "/tmp/mcp.sock".into(),
    };

    transport.run(server).await
}

Why pmcp wins:

• Custom transport protocols
• Direct socket/network access
• Custom message framing
• Protocol optimization

4. You’re Building a Library/SDK

pmcp is designed for building reusable components:

// Your reusable MCP server library
pub struct CodeAnalysisServer {
    analyzers: Vec<Box<dyn Analyzer>>,
}

impl CodeAnalysisServer {
    pub fn new() -> Self {
        Self {
            analyzers: vec![
                Box::new(ComplexityAnalyzer::new()),
                Box::new(SecurityAnalyzer::new()),
                Box::new(PerformanceAnalyzer::new()),
            ],
        }
    }

    pub fn add_analyzer(&mut self, analyzer: Box<dyn Analyzer>) {
        self.analyzers.push(analyzer);
    }

    pub fn build(self) -> Result<pmcp::Server> {
        let mut builder = ServerBuilder::new()
            .name("code-analysis")
            .version("1.0.0");

        // Register tools from analyzers
        for analyzer in self.analyzers {
            for tool in analyzer.tools() {
                builder = builder.tool_typed(&tool.name, tool.handler);
            }
        }

        builder.build()
    }
}

// Users can extend your library
fn main() -> Result<()> {
    let mut server = CodeAnalysisServer::new();

    // Add custom analyzer
    server.add_analyzer(Box::new(MyCustomAnalyzer::new()));

    let server = server.build()?;
    server.run_stdio().await
}

Why pmcp wins:

• Composable API
• Extensibility hooks
• Library-friendly design
• No framework lock-in

5. You Need WebAssembly Compilation

pmcp can compile to WASM for browser-based servers:

use pmcp::ServerBuilder;
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub struct WasmMcpServer {
    server: pmcp::Server,
}

#[wasm_bindgen]
impl WasmMcpServer {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Result<WasmMcpServer, JsValue> {
        let server = ServerBuilder::new()
            .name("wasm-server")
            .tool_typed("process", |args: ProcessArgs, _| {
                Box::pin(async move {
                    // Pure Rust logic, runs in browser
                    Ok(serde_json::json!({ "result": process(args) }))
                })
            })
            .build()
            .map_err(|e| JsValue::from_str(&e.to_string()))?;

        Ok(WasmMcpServer { server })
    }

    #[wasm_bindgen]
    pub async fn handle_request(&self, request: JsValue) -> Result<JsValue, JsValue> {
        // Handle MCP requests from JavaScript
        let result = self.server.handle(request).await?;
        Ok(result)
    }
}

Why pmcp wins:

• WASM target support
• Browser compatibility
• Pure Rust execution
• JavaScript interop

6. You Need Dynamic Server Configuration

pmcp allows runtime configuration changes:

use pmcp::ServerBuilder;
use std::sync::Arc;

struct DynamicServer {
    builder: Arc<RwLock<ServerBuilder>>,
}

impl DynamicServer {
    pub async fn register_tool_at_runtime(&self, name: String, handler: impl Fn() -> Future) {
        let mut builder = self.builder.write().await;
        *builder = builder.clone().tool_typed(name, handler);
        // Rebuild and hot-swap server
    }

    pub async fn unregister_tool(&self, name: &str) {
        // Remove tool at runtime
    }
}

Why pmcp wins:

• Runtime tool registration
• Hot-swapping capabilities
• Dynamic configuration
• Plugin architecture

7. You Need Fine-Grained Performance Control

pmcp lets you optimize every aspect:

use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("optimized-server")

        // Custom executor
        .with_runtime(tokio::runtime::Builder::new_multi_thread()
            .worker_threads(16)
            .thread_name("mcp-worker")
            .thread_stack_size(4 * 1024 * 1024)
            .build()?)

        // Custom buffer sizes
        .with_buffer_size(65536)

        // Custom timeout strategy
        .with_timeout_strategy(CustomTimeoutStrategy::new())

        // Zero-copy tool handlers
        .tool_raw("process_bytes", |bytes: &[u8], _| {
            Box::pin(async move {
                // Process without allocations
                process_bytes_in_place(bytes)
            })
        })

        .build()?;

    server.run_stdio().await
}

Why pmcp wins:

• Custom runtime configuration
• Memory allocation control
• Zero-copy operations
• Performance tuning hooks

8. You Need Multi-Server Orchestration

pmcp allows running multiple servers in one process:

use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    // Server 1: Code analysis
    let analysis_server = ServerBuilder::new()
        .name("code-analysis")
        .tool_typed("analyze", |args, _| { /* ... */ })
        .build()?;

    // Server 2: File operations
    let file_server = ServerBuilder::new()
        .name("file-ops")
        .tool_typed("read_file", |args, _| { /* ... */ })
        .build()?;

    // Run both on different transports
    tokio::try_join!(
        analysis_server.run_stdio(),
        file_server.run_sse("0.0.0.0:8080"),
    )?;

    Ok(())
}

Why pmcp wins:

• Multi-server orchestration
• Different transports per server
• Process-level control
• Resource sharing

Real-World Use Cases

Case Study 1: Database Query Server

Challenge: Build a stateful database query server with transaction support

Why pmcp:

struct QueryServer {
    pool: PgPool,
    active_transactions: Arc<RwLock<HashMap<Uuid, Transaction>>>,
}

impl QueryServer {
    pub async fn build(self) -> Result<pmcp::Server> {
        ServerBuilder::new()
            .name("db-server")
            .tool_typed("begin_transaction", /* complex state logic */)
            .tool_typed("execute_query", /* transaction-aware */)
            .tool_typed("commit", /* finalize transaction */)
            .tool_typed("rollback", /* abort transaction */)
            .build()
    }
}

Results:

• Full control over connection pooling
• Custom transaction management
• Complex state coordination
• Optimized query execution

Case Study 2: Real-Time Collaborative Server

Challenge: Build a server for real-time collaboration with WebSocket transport

Why pmcp:

struct CollaborationServer {
    rooms: Arc<RwLock<HashMap<String, Room>>>,
    connections: Arc<RwLock<HashMap<Uuid, WebSocket>>>,
}

impl CollaborationServer {
    pub async fn run(self) -> Result<()> {
        let server = ServerBuilder::new()
            .name("collab-server")
            .tool_typed("join_room", /* manage connections */)
            .tool_typed("send_message", /* broadcast to room */)
            .on_notification("user_typing", /* real-time events */)
            .build()?;

        // Custom WebSocket transport with broadcasting
        server.run_websocket("0.0.0.0:8080").await
    }
}

Results:

• WebSocket broadcast support
• Real-time event handling
• Custom connection management
• Room-based message routing

Case Study 3: Browser-Based REPL

Challenge: Build an MCP server that runs entirely in the browser

Why pmcp:

#[wasm_bindgen]
pub struct BrowserRepl {
    server: pmcp::Server,
    history: Vec<String>,
}

#[wasm_bindgen]
impl BrowserRepl {
    pub fn new() -> Self {
        let server = ServerBuilder::new()
            .name("browser-repl")
            .tool_typed("eval", /* safe evaluation */)
            .tool_typed("history", /* return history */)
            .build()
            .unwrap();

        Self { server, history: vec![] }
    }

    pub async fn execute(&mut self, code: String) -> JsValue {
        self.history.push(code.clone());
        self.server.handle_tool("eval", serde_json::json!({ "code": code })).await
    }
}

Results:

• Runs entirely in browser
• No backend required
• JavaScript interoperability
• Secure sandboxed execution

Performance Characteristics

When pmcp Might NOT Be the Best Choice

pmcp is not ideal when:

1. You want zero boilerplate

   • pmcp requires more code than pforge
   • Use pforge for standard patterns

2. You want declarative configuration

   • pmcp is programmatic, not declarative
   • Use pforge for YAML-based config

3. You want built-in quality gates

   • pmcp doesn’t enforce quality standards
   • Use pforge for automatic PMAT integration

4. You want CLI/HTTP handler types out of the box

   • pmcp requires you to write these yourself
   • Use pforge for pre-built handler types

See Chapter 1.1: When to Use pforge for these cases.

Combining pforge and pmcp

You can use both in the same project:

// Use pforge for simple tools
mod pforge_tools {
    include!(concat!(env!("OUT_DIR"), "/pforge_generated.rs"));
}

// Use pmcp for complex tools
use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let mut builder = ServerBuilder::new()
        .name("hybrid-server")
        .version("1.0.0");

    // Add pforge-generated tools
    for (name, handler) in pforge_tools::handlers() {
        builder = builder.tool_typed(name, handler);
    }

    // Add custom pmcp tool with complex logic
    builder = builder.tool_typed("complex_analysis", |args: AnalysisArgs, _| {
        Box::pin(async move {
            // Complex custom logic here
            let result = perform_complex_analysis(args).await?;
            Ok(serde_json::to_value(result)?)
        })
    });

    let server = builder.build()?;
    server.run_stdio().await
}

Summary

Use pmcp when you need:

✅ Custom MCP protocol extensions ✅ Complex stateful logic ✅ Custom transport implementations ✅ Library/SDK development ✅ WebAssembly compilation ✅ Runtime configuration ✅ Fine-grained performance control ✅ Multi-server orchestration

Use pforge when you want:

❌ Minimal boilerplate ❌ Declarative YAML configuration ❌ Built-in quality gates ❌ Pre-built handler types ❌ Fast iteration without recompilation

Not sure? Start with pforge. You can always integrate pmcp for complex features later.

Next: Side-by-Side Comparison

Chapter 1.3: Side-by-Side Comparison

This chapter provides a comprehensive feature-by-feature comparison of pforge and pmcp to help you choose the right tool for your project.

Quick Reference Matrix

Detailed Comparison

1. Configuration Approach

pforge: Declarative YAML

# forge.yaml
forge:
  name: calculator-server
  version: 1.0.0
  transport: stdio
  optimization: release

tools:
  - type: native
    name: calculate
    description: "Perform arithmetic operations"
    handler:
      path: handlers::calculate
    params:
      operation: { type: string, required: true }
      a: { type: float, required: true }
      b: { type: float, required: true }
    timeout_ms: 5000

Pros:

• Declarative, self-documenting
• Easy to read and modify
• No recompilation for config changes
• Version control friendly
• Non-programmers can understand

Cons:

• Limited to supported features
• Can’t express complex logic
• Requires code generation step

pmcp: Programmatic Rust

use pmcp::{ServerBuilder, TypedTool};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
struct CalculateInput {
    operation: String,
    a: f64,
    b: f64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = ServerBuilder::new()
        .name("calculator-server")
        .version("1.0.0")
        .tool_typed("calculate", |input: CalculateInput, _extra| {
            Box::pin(async move {
                let result = match input.operation.as_str() {
                    "add" => input.a + input.b,
                    "subtract" => input.a - input.b,
                    "multiply" => input.a * input.b,
                    "divide" => {
                        if input.b == 0.0 {
                            return Err(pmcp::Error::Validation(
                                "Division by zero".into()
                            ));
                        }
                        input.a / input.b
                    }
                    _ => return Err(pmcp::Error::Validation(
                        "Unknown operation".into()
                    )),
                };
                Ok(serde_json::json!({ "result": result }))
            })
        })
        .build()?;

    server.run_stdio().await?;
    Ok(())
}

Pros:

• Unlimited flexibility
• Express complex logic directly
• Full Rust type system
• Better IDE support
• No code generation

Cons:

• More boilerplate
• Steeper learning curve
• Requires recompilation
• More verbose

2. Handler Types

pforge: Four Built-in Types

tools:
  # 1. Native handlers - Pure Rust logic
  - type: native
    name: validate_email
    handler:
      path: handlers::validate_email
    params:
      email: { type: string, required: true }

  # 2. CLI handlers - Subprocess wrappers
  - type: cli
    name: run_git_status
    command: git
    args: ["status", "--porcelain"]
    cwd: /path/to/repo
    stream: true

  # 3. HTTP handlers - API proxies
  - type: http
    name: create_github_issue
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: POST
    headers:
      Authorization: "Bearer {{GITHUB_TOKEN}}"

  # 4. Pipeline handlers - Tool composition
  - type: pipeline
    name: validate_and_save
    steps:
      - tool: validate_email
        output: validation
      - tool: save_to_db
        condition: "{{validation.valid}}"

Coverage: ~80% of common use cases

pmcp: Unlimited Custom Handlers

// Any Rust code you can imagine
server
    .tool_typed("custom", |input, _| {
        Box::pin(async move {
            // Complex database transactions
            let mut tx = pool.begin().await?;

            // Call external services
            let response = reqwest::get("https://api.example.com").await?;

            // Complex business logic
            let result = process_with_ml_model(input).await?;

            tx.commit().await?;
            Ok(serde_json::to_value(result)?)
        })
    })
    .tool_raw("zero_copy", |bytes, _| {
        Box::pin(async move {
            // Zero-copy byte processing
            process_in_place(bytes)
        })
    })
    .custom_method("custom/protocol", |params| {
        Box::pin(async move {
            // Custom protocol extension
            Ok(custom_handler(params).await?)
        })
    })

Coverage: 100% - anything Rust can do

3. Performance Comparison

Tool Dispatch Latency

pforge (perfect hash):     0.7μs ± 0.1μs
pmcp (HashMap):            8.2μs ± 0.3μs

Speedup: 11.7x faster

Why pforge is faster:

• Compile-time perfect hash function (FKS algorithm)
• Zero dynamic lookups
• Inlined handler calls
• No runtime registry traversal

pmcp overhead:

• HashMap lookup: ~5-10ns
• Dynamic dispatch: ~2-5μs
• Type erasure overhead: ~1-3μs

Cold Start Time

pforge:  95ms  (includes codegen cache load)
pmcp:    42ms  (minimal binary)

Startup: pmcp 2.3x faster

Why pmcp is faster:

• No code generation loading
• Smaller binary
• Simpler initialization

pforge overhead:

• Load generated code: ~40ms
• Initialize registry: ~15ms
• State backend init: ~10ms

Throughput Benchmarks

Sequential Execution (1 core):
pforge:  105,000 req/s
pmcp:     68,000 req/s

Concurrent Execution (8 cores):
pforge:  520,000 req/s
pmcp:    310,000 req/s

Throughput: pforge 1.5-1.7x faster

Why pforge scales better:

• Lock-free perfect hash
• Pre-allocated handler slots
• Optimized middleware chain

Memory Usage

Per-tool overhead:
pforge:  ~200B  (registry entry + metadata)
pmcp:    ~450B  (boxed closure + type info)

10-tool server:
pforge:  ~2MB   (including state backend)
pmcp:    ~1.5MB (minimal runtime)

4. Development Workflow

pforge: Edit → Restart

# 1. Edit configuration
vim forge.yaml

# 2. Restart server (no recompile needed)
pforge serve

# Total time: ~5 seconds

Iteration cycle:

• YAML changes: 0s compile time
• Handler changes: 2-10s compile time
• Config validation: instant feedback
• Hot reload: supported (experimental)

pmcp: Edit → Compile → Run

# 1. Edit code
vim src/main.rs

# 2. Recompile
cargo build --release

# 3. Run
./target/release/my-server

# Total time: 30-120 seconds

Iteration cycle:

• Any change: full recompile
• Release build: 30-120s
• Debug build: 5-20s
• Incremental: helps but still slower

5. Quality & Testing

pforge: Built-in Quality Gates

# Quality gates enforced automatically
quality:
  pre_commit:
    - cargo fmt --check
    - cargo clippy -- -D warnings
    - cargo test --all
    - cargo tarpaulin --out Json  # ≥80% coverage
    - pmat analyze complexity --max 20
    - pmat analyze satd --max 0
    - pmat analyze tdg --min 0.75

  ci:
    - cargo mutants  # ≥90% mutation kill rate

Enforced standards:

• No unwrap() in production code
• No panic!() in production code
• Cyclomatic complexity ≤ 20
• Test coverage ≥ 80%
• Technical Debt Grade ≥ 0.75
• Zero SATD comments

Testing:

# Property-based tests generated automatically
pforge test --property

# Mutation testing integrated
pforge test --mutation

# Benchmark regression checks
pforge bench --check

pmcp: Manual Quality Setup

// You implement quality checks yourself
#[cfg(test)]
mod tests {
    // You write all tests manually

    #[test]
    fn test_calculator() {
        // Manual test implementation
    }

    // Property tests if you add proptest
    proptest! {
        #[test]
        fn prop_test(a: f64, b: f64) {
            // Manual property test
        }
    }
}

Standards:

• You decide what to enforce
• You configure CI/CD
• You set up coverage tools
• You integrate quality checks

6. State Management

pforge: Built-in State

# Automatic state management
state:
  backend: sled       # or "memory" for testing
  path: /tmp/state
  cache_size: 1000
  ttl: 3600

// Use in handlers
async fn handle(&self, input: Input) -> Result<Output> {
    // Get state
    let counter = self.state
        .get("counter").await?
        .unwrap_or(0);

    // Update state
    self.state
        .set("counter", counter + 1, None).await?;

    Ok(Output { count: counter + 1 })
}

Backends:

• Sled: Persistent embedded DB (default)
• Memory: In-memory DashMap (testing)
• Redis: Distributed state (future)

pmcp: Manual State Implementation

use std::sync::Arc;
use tokio::sync::RwLock;

struct AppState {
    data: Arc<RwLock<HashMap<String, Value>>>,
    db: PgPool,
    cache: Cache,
}

#[tokio::main]
async fn main() -> Result<()> {
    let state = Arc::new(AppState {
        data: Arc::new(RwLock::new(HashMap::new())),
        db: create_pool().await?,
        cache: Cache::new(),
    });

    let server = ServerBuilder::new()
        .name("stateful-server")
        .tool_typed("get_data", {
            let state = state.clone();
            move |input: GetInput, _| {
                let state = state.clone();
                Box::pin(async move {
                    let data = state.data.read().await;
                    Ok(data.get(&input.key).cloned())
                })
            }
        })
        .build()?;

    server.run_stdio().await
}

Flexibility:

• Any state backend you want
• Custom synchronization
• Complex state patterns
• Full control over lifecycle

7. Error Handling

pforge: Standardized Errors

use pforge_runtime::{Error, Result};

// Standardized error types
pub enum Error {
    Handler(String),
    Validation(String),
    Timeout,
    ToolNotFound(String),
    InvalidConfig(String),
}

// Automatic error conversion
async fn handle(&self, input: Input) -> Result<Output> {
    let value = input.value
        .ok_or_else(|| Error::Validation("Missing value".into()))?;

    // All errors converted to JSON-RPC format
    Ok(Output { result: value * 2 })
}

Features:

• Consistent error format
• Automatic JSON-RPC conversion
• Stack trace preservation
• Error tracking built-in

pmcp: Custom Error Handling

use pmcp::Error as McpError;
use thiserror::Error;

// Custom error types
#[derive(Debug, Error)]
pub enum MyError {
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),

    #[error("API error: {0}")]
    Api(#[from] reqwest::Error),

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

// Manual conversion to MCP errors
impl From<MyError> for McpError {
    fn from(err: MyError) -> Self {
        McpError::Handler(err.to_string())
    }
}

Flexibility:

• Define your own error types
• Custom error conversion
• Error context preservation
• Full control over error responses

8. Use Case Fit Matrix

9. Code Size Comparison

For a typical 10-tool MCP server:

pforge

forge.yaml:                  80 lines
src/handlers.rs:            200 lines
tests/:                     150 lines
--------------------------------
Total:                      430 lines

Generated code:            ~2000 lines (hidden)

pmcp

src/main.rs:                150 lines
src/handlers/:              400 lines
src/state.rs:               100 lines
src/errors.rs:               50 lines
tests/:                     200 lines
--------------------------------
Total:                      900 lines

Code reduction: 52% with pforge

10. Learning Curve

pforge

What you need to know:

• ✅ YAML syntax (30 minutes)
• ✅ Basic Rust structs (1 hour)
• ✅ async/await basics (1 hour)
• ✅ Result/Option types (1 hour)

What you don’t need to know:

• ❌ MCP protocol details
• ❌ JSON-RPC internals
• ❌ pmcp API
• ❌ Transport implementation

Time to productivity: 3-4 hours

pmcp

What you need to know:

• ✅ Rust fundamentals (10-20 hours)
• ✅ Async programming (5 hours)
• ✅ MCP protocol (2 hours)
• ✅ pmcp API (2 hours)
• ✅ Error handling patterns (2 hours)

What you don’t need to know:

• ❌ Nothing - full control requires full knowledge

Time to productivity: 20-30 hours

Migration Strategies

pmcp → pforge

// Before (pmcp)
ServerBuilder::new()
    .tool_typed("calculate", |input: CalcInput, _| {
        Box::pin(async move {
            Ok(serde_json::json!({ "result": input.a + input.b }))
        })
    })

// After (pforge)
// 1. Extract to handler
pub struct CalculateHandler;

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalcInput;
    type Output = CalcOutput;

    async fn handle(&self, input: Input) -> Result<Output> {
        Ok(CalcOutput { result: input.a + input.b })
    }
}

// 2. Add to forge.yaml
// tools:
//   - type: native
//     name: calculate
//     handler:
//       path: handlers::CalculateHandler

pforge → pmcp

// Reuse pforge handlers in pmcp!
use pforge_runtime::Handler;

// pforge handler (no changes needed)
pub struct MyHandler;

#[async_trait::async_trait]
impl Handler for MyHandler {
    // ... existing implementation
}

// Use in pmcp server
#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("hybrid-server")
        .tool_typed("my_tool", |input: MyInput, _| {
            Box::pin(async move {
                let handler = MyHandler;
                let output = handler.handle(input).await?;
                Ok(serde_json::to_value(output)?)
            })
        })
        .build()?;

    server.run_stdio().await
}

Decision Matrix

Choose pforge if:

✅ You want minimal boilerplate ✅ You need fast iteration (YAML changes) ✅ You want built-in quality gates ✅ You’re building standard MCP patterns ✅ You need CLI/HTTP wrappers ✅ You want sub-microsecond dispatch ✅ You’re new to Rust ✅ You need state management out-of-the-box

Choose pmcp if:

✅ You need custom protocol extensions ✅ You need complex stateful logic ✅ You need custom transports ✅ You’re building a library/SDK ✅ You need WebAssembly support ✅ You want complete control ✅ You’re building multi-server orchestration ✅ You need runtime configuration

Use both if:

✅ You want pforge for 80% of tools ✅ You need pmcp for complex 20% ✅ You’re evolving from simple to complex ✅ You want the best of both worlds

Summary

Both pforge and pmcp are production-ready tools from the same team. The choice depends on your specific needs:

• Quick standard server? → pforge (faster, easier)
• Complex custom logic? → pmcp (flexible, powerful)
• Not sure? → Start with pforge, migrate to pmcp if needed

Remember: pforge handlers are compatible with pmcp, so you can always evolve your architecture as requirements change.

Next: Migration Between pforge and pmcp

Chapter 1.4: Migration Between pforge and pmcp

This chapter provides practical migration strategies for moving between pforge and pmcp, including real-world examples and best practices.

Why Migrate?

Common Migration Scenarios

pmcp → pforge:

• Reduce boilerplate code
• Standardize on declarative configuration
• Add built-in quality gates
• Improve iteration speed
• Simplify maintenance

pforge → pmcp:

• Need custom protocol extensions
• Require complex stateful logic
• Build library/SDK
• Need WebAssembly support
• Require custom transports

Handler Compatibility

The good news: pforge handlers are compatible with pmcp!

Both frameworks share the same handler trait pattern, making migration straightforward.

// This handler works in BOTH pforge and pmcp
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    a: f64,
    b: f64,
    operation: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalculateOutput {
    result: f64,
}

pub struct CalculateHandler;

#[async_trait]
impl pforge_runtime::Handler for CalculateHandler {
    type Input = CalculateInput;
    type Output = CalculateOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> pforge_runtime::Result<Self::Output> {
        let result = match input.operation.as_str() {
            "add" => input.a + input.b,
            "subtract" => input.a - input.b,
            "multiply" => input.a * input.b,
            "divide" => {
                if input.b == 0.0 {
                    return Err(pforge_runtime::Error::Handler(
                        "Division by zero".into()
                    ));
                }
                input.a / input.b
            }
            _ => return Err(pforge_runtime::Error::Handler(
                "Unknown operation".into()
            )),
        };

        Ok(CalculateOutput { result })
    }
}

Migrating from pmcp to pforge

Step 1: Analyze Your pmcp Server

Identify your tools and their types:

// Existing pmcp server
let server = ServerBuilder::new()
    .name("my-server")
    .tool_typed("calculate", /* handler */)     // → Native handler
    .tool_typed("run_git", /* subprocess */)     // → CLI handler
    .tool_typed("fetch_api", /* HTTP call */)    // → HTTP handler
    .tool_typed("complex", /* custom logic */)   // → Keep in pmcp
    .build()?;

Step 2: Extract Handlers

Convert tool closures to handler structs:

// Before (pmcp inline closure)
.tool_typed("calculate", |input: CalcInput, _| {
    Box::pin(async move {
        let result = input.a + input.b;
        Ok(serde_json::json!({ "result": result }))
    })
})

// After (pforge handler struct)
pub struct CalculateHandler;

#[async_trait]
impl Handler for CalculateHandler {
    type Input = CalcInput;
    type Output = CalcOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(CalcOutput { result: input.a + input.b })
    }
}

Step 3: Create forge.yaml

Map your tools to pforge configuration:

forge:
  name: my-server
  version: 1.0.0
  transport: stdio

tools:
  # Native handlers (from pmcp tool_typed)
  - type: native
    name: calculate
    description: "Perform calculations"
    handler:
      path: handlers::CalculateHandler
    params:
      a: { type: float, required: true }
      b: { type: float, required: true }
      operation: { type: string, required: true }

  # CLI handlers (from subprocess calls)
  - type: cli
    name: run_git
    description: "Run git commands"
    command: git
    args: ["{{subcommand}}", "{{args}}"]
    cwd: /path/to/repo
    stream: true

  # HTTP handlers (from reqwest calls)
  - type: http
    name: fetch_api
    description: "Fetch from external API"
    endpoint: "https://api.example.com/{{path}}"
    method: GET
    headers:
      Authorization: "Bearer {{API_TOKEN}}"

Step 4: Migrate State

// Before (pmcp manual state)
struct AppState {
    data: Arc<RwLock<HashMap<String, Value>>>,
}

let state = Arc::new(AppState {
    data: Arc::new(RwLock::new(HashMap::new())),
});

// After (pforge declarative state)
// In forge.yaml:
// state:
//   backend: sled
//   path: /tmp/my-server-state
//   cache_size: 1000

// In handler:
async fn handle(&self, input: Input) -> Result<Output> {
    let value = self.state.get("key").await?;
    self.state.set("key", value, None).await?;
    Ok(Output { value })
}

Step 5: Test Migration

# Run existing pmcp tests
cargo test --all

# Generate pforge server
pforge build

# Run pforge tests
pforge test

# Compare behavior
diff <(echo '{"a": 5, "b": 3}' | ./pmcp-server) \
     <(echo '{"a": 5, "b": 3}' | pforge serve)

Complete Example: pmcp → pforge

Before (pmcp):

// src/main.rs (120 lines)
use pmcp::{ServerBuilder, TypedTool};
use std::sync::Arc;
use tokio::sync::RwLock;

#[derive(Debug, Deserialize, JsonSchema)]
struct CalcInput {
    a: f64,
    b: f64,
    operation: String,
}

#[tokio::main]
async fn main() -> Result<()> {
    let state = Arc::new(RwLock::new(HashMap::new()));

    let server = ServerBuilder::new()
        .name("calculator")
        .version("1.0.0")
        .tool_typed("calculate", {
            let state = state.clone();
            move |input: CalcInput, _| {
                let state = state.clone();
                Box::pin(async move {
                    // 20 lines of logic
                    let result = match input.operation.as_str() {
                        "add" => input.a + input.b,
                        // ... more operations
                    };

                    // Update state
                    state.write().await.insert("last_result", result);

                    Ok(serde_json::json!({ "result": result }))
                })
            }
        })
        .tool_typed("run_command", |input: CmdInput, _| {
            Box::pin(async move {
                // 30 lines of subprocess handling
                let output = Command::new(&input.cmd)
                    .args(&input.args)
                    .output()
                    .await?;
                // ... error handling
                Ok(serde_json::json!({ "output": String::from_utf8(output.stdout)? }))
            })
        })
        .build()?;

    server.run_stdio().await
}

After (pforge):

# forge.yaml (25 lines)
forge:
  name: calculator
  version: 1.0.0
  transport: stdio

state:
  backend: sled
  path: /tmp/calculator-state

tools:
  - type: native
    name: calculate
    description: "Perform arithmetic operations"
    handler:
      path: handlers::CalculateHandler
    params:
      a: { type: float, required: true }
      b: { type: float, required: true }
      operation: { type: string, required: true }

  - type: cli
    name: run_command
    description: "Run shell commands"
    command: "{{cmd}}"
    args: "{{args}}"
    stream: true

// src/handlers.rs (30 lines)
use pforge_runtime::{Handler, Result, Error};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalcInput {
    a: f64,
    b: f64,
    operation: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalcOutput {
    result: f64,
}

pub struct CalculateHandler;

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalcInput;
    type Output = CalcOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let result = match input.operation.as_str() {
            "add" => input.a + input.b,
            "subtract" => input.a - input.b,
            "multiply" => input.a * input.b,
            "divide" => {
                if input.b == 0.0 {
                    return Err(Error::Handler("Division by zero".into()));
                }
                input.a / input.b
            }
            _ => return Err(Error::Handler("Unknown operation".into())),
        };

        // State is managed automatically
        self.state.set("last_result", &result.to_string(), None).await?;

        Ok(CalcOutput { result })
    }
}

Result:

• Code reduction: 120 lines → 55 lines (54% reduction)
• Complexity: Manual state → Automatic state
• Maintenance: Easier to modify (YAML vs Rust)

Migrating from pforge to pmcp

Step 1: Keep Your Handlers

pforge handlers work directly in pmcp:

// handlers.rs - NO CHANGES NEEDED
pub struct MyHandler;

#[async_trait]
impl pforge_runtime::Handler for MyHandler {
    type Input = MyInput;
    type Output = MyOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> pforge_runtime::Result<Self::Output> {
        // Handler logic stays the same
        Ok(MyOutput { result: process(input) })
    }
}

Step 2: Convert YAML to pmcp Code

# forge.yaml (pforge)
forge:
  name: my-server
  version: 1.0.0

tools:
  - type: native
    name: process
    handler:
      path: handlers::MyHandler
    params:
      input: { type: string, required: true }

Becomes:

// main.rs (pmcp)
use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("my-server")
        .version("1.0.0")
        .tool_typed("process", |input: MyInput, _| {
            Box::pin(async move {
                let handler = MyHandler;
                let output = handler.handle(input).await?;
                Ok(serde_json::to_value(output)?)
            })
        })
        .build()?;

    server.run_stdio().await
}

Step 3: Add Custom Logic

Now you can extend beyond pforge’s capabilities:

use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let server = ServerBuilder::new()
        .name("advanced-server")
        .version("1.0.0")

        // Keep existing pforge handlers
        .tool_typed("basic", |input: BasicInput, _| {
            Box::pin(async move {
                let handler = BasicHandler;
                let output = handler.handle(input).await?;
                Ok(serde_json::to_value(output)?)
            })
        })

        // Add custom complex logic (not possible in pforge)
        .tool_typed("complex", |input: ComplexInput, _| {
            Box::pin(async move {
                // Custom database transactions
                let mut tx = db_pool.begin().await?;

                // Complex business logic
                let result = perform_analysis(&mut tx, input).await?;

                // Custom error handling
                match result {
                    Ok(data) => {
                        tx.commit().await?;
                        Ok(serde_json::to_value(data)?)
                    }
                    Err(e) => {
                        tx.rollback().await?;
                        Err(pmcp::Error::Handler(e.to_string()))
                    }
                }
            })
        })

        // Custom protocol extensions
        .custom_method("custom/analyze", |params| {
            Box::pin(async move {
                custom_protocol_handler(params).await
            })
        })

        .build()?;

    server.run_stdio().await
}

Hybrid Approach: Using Both

You can use pforge and pmcp together in the same project:

Strategy 1: pforge for Simple, pmcp for Complex

// Use pforge for 80% of simple tools
mod pforge_tools {
    include!(concat!(env!("OUT_DIR"), "/pforge_generated.rs"));
}

// Use pmcp for 20% of complex tools
use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    let mut builder = ServerBuilder::new()
        .name("hybrid-server")
        .version("1.0.0");

    // Add all pforge-generated tools
    for (name, handler) in pforge_tools::handlers() {
        builder = builder.tool_typed(name, handler);
    }

    // Add custom complex tools
    builder = builder
        .tool_typed("complex_analysis", |input: AnalysisInput, _| {
            Box::pin(async move {
                // Complex logic not expressible in pforge
                let result = ml_model.predict(input).await?;
                Ok(serde_json::to_value(result)?)
            })
        })
        .tool_typed("database_query", |input: QueryInput, _| {
            Box::pin(async move {
                // Complex transactional database operations
                let mut tx = pool.begin().await?;
                let result = execute_query(&mut tx, input).await?;
                tx.commit().await?;
                Ok(serde_json::to_value(result)?)
            })
        });

    let server = builder.build()?;
    server.run_stdio().await
}

Strategy 2: Parallel Servers

Run pforge and pmcp servers side-by-side:

# Terminal 1: pforge server for standard tools
cd pforge-server
pforge serve

# Terminal 2: pmcp server for custom tools
cd pmcp-server
cargo run --release

# Claude Desktop config
{
  "mcpServers": {
    "standard-tools": {
      "command": "pforge",
      "args": ["serve"],
      "cwd": "/path/to/pforge-server"
    },
    "custom-tools": {
      "command": "/path/to/pmcp-server/target/release/custom-server",
      "cwd": "/path/to/pmcp-server"
    }
  }
}

Migration Checklist

pmcp → pforge Migration

• Identify tool types (native/cli/http/pipeline)
• Extract handlers from closures
• Create forge.yaml configuration
• Convert state management to pforge state backend
• Set up quality gates (PMAT)
• Write tests for migrated handlers
• Benchmark performance (should improve)
• Update documentation
• Deploy and monitor

pforge → pmcp Migration

• Keep existing handler implementations
• Convert forge.yaml to ServerBuilder code
• Add custom logic as needed
• Implement custom state management (if needed)
• Set up CI/CD (manual configuration)
• Write additional tests
• Update documentation
• Deploy and monitor

Common Migration Pitfalls

Pitfall 1: State Management Mismatch

Problem:

// pmcp: Manual Arc<RwLock>
let data = state.read().await.get("key").cloned();

// pforge: Async state backend
let data = self.state.get("key").await?;

Solution: Choose consistent state backend or use adapter pattern.

Pitfall 2: Error Handling Differences

Problem:

// pmcp: Custom error types
Err(MyError::Database(e))

// pforge: Standardized errors
Err(Error::Handler(e.to_string()))

Solution: Map custom errors to pforge Error types:

impl From<MyError> for pforge_runtime::Error {
    fn from(err: MyError) -> Self {
        match err {
            MyError::Database(e) => Error::Handler(format!("DB: {}", e)),
            MyError::Validation(msg) => Error::Validation(msg),
            MyError::Timeout => Error::Timeout,
        }
    }
}

Pitfall 3: Missing CLI/HTTP Wrappers

Problem: pmcp requires manual subprocess/HTTP handling.

Solution: Extract to separate pforge server or use libraries:

// Instead of reinventing CLI wrapper
use tokio::process::Command;

// Use pforge CLI handler type or simple wrapper
async fn run_command(cmd: &str, args: &[String]) -> Result<String> {
    let output = Command::new(cmd)
        .args(args)
        .output()
        .await?;

    String::from_utf8(output.stdout)
        .map_err(|e| Error::Handler(e.to_string()))
}

Performance Considerations

pmcp → pforge

Expected improvements:

• Tool dispatch: 11x faster (perfect hash vs HashMap)
• Throughput: 1.5-1.7x higher
• Memory per tool: ~50% reduction

Trade-offs:

• Cold start: ~2x slower (code generation)
• Binary size: 2-3x larger

pforge → pmcp

Expected changes:

• More control over performance tuning
• Custom allocator options
• Zero-copy optimizations possible
• Manual optimization needed

Testing Migration

Compatibility Test

#[cfg(test)]
mod migration_tests {
    use super::*;

    #[tokio::test]
    async fn test_handler_compatibility() {
        // Test handler works in both pforge and pmcp
        let handler = MyHandler;

        let input = MyInput { value: 42 };
        let output = handler.handle(input).await.unwrap();

        assert_eq!(output.result, 84);
    }

    #[tokio::test]
    async fn test_behavior_equivalence() {
        // Compare pforge and pmcp server responses
        let pforge_response = test_pforge_server(input.clone()).await?;
        let pmcp_response = test_pmcp_server(input.clone()).await?;

        assert_eq!(pforge_response, pmcp_response);
    }
}

Summary

Migration between pforge and pmcp is straightforward thanks to handler compatibility:

Key Points:

1. pforge handlers work in pmcp without changes
2. pmcp → pforge reduces code by ~50%
3. pforge → pmcp adds flexibility for complex cases
4. Hybrid approach combines benefits of both
5. Choose based on current needs, migrate as requirements evolve

Migration Decision:

• More tools becoming standard? → Migrate to pforge
• Need custom protocols? → Migrate to pmcp
• Mixed requirements? → Use hybrid approach

Next: Architecture: How pforge Uses pmcp

Chapter 1.5: How pforge Uses pmcp Under the Hood

This chapter reveals the architectural relationship between pforge and pmcp (rust-mcp-sdk). Understanding this relationship is crucial for knowing when to use each tool and how they complement each other.

The Architecture: pforge Built on pmcp

Key Insight: pforge is not a replacement for pmcp - it’s a framework built on top of pmcp.

┌─────────────────────────────────────┐
│   pforge (Declarative Framework)    │
│   • YAML Configuration               │
│   • Code Generation                  │
│   • Handler Registry                 │
│   • Quality Gates                    │
└─────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────┐
│   pmcp (Low-Level MCP SDK)          │
│   • ServerBuilder                    │
│   • TypedTool API                    │
│   • Transport Layer (stdio/SSE/WS)   │
│   • JSON-RPC Protocol                │
└─────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────┐
│   Model Context Protocol (MCP)      │
│   • Tools, Resources, Prompts        │
│   • Sampling, Logging                │
└─────────────────────────────────────┘

Dependency Chain

From crates/pforge-runtime/Cargo.toml:

[dependencies]
pmcp = "1.6"  # ← pforge runtime depends on pmcp
schemars = { version = "0.8", features = ["derive"] }
# ... other deps

This means:

• Every pforge server is a pmcp server under the hood
• pforge translates YAML → pmcp API calls
• All pmcp features are available to pforge

What pforge Adds on Top of pmcp

pforge is essentially a code generator + framework that:

1. Parses YAML → Generates Rust code
2. Creates Handler Registry → Maps tool names to handlers
3. Builds pmcp Server → Uses pmcp::ServerBuilder
4. Enforces Quality → PMAT gates, TDD methodology
5. Optimizes Dispatch → Perfect hashing, compile-time optimization

Example: The Same Server in Both

With Pure pmcp (What You Write)

// main.rs - Direct pmcp usage
use pmcp::{ServerBuilder, TypedTool};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
struct GreetArgs {
    name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = ServerBuilder::new()
        .name("greeter")
        .version("1.0.0")
        .tool_typed("greet", |args: GreetArgs, _extra| {
            Box::pin(async move {
                Ok(serde_json::json!({
                    "message": format!("Hello, {}!", args.name)
                }))
            })
        })
        .build()?;

    server.run_stdio().await?;
    Ok(())
}

With pforge (What You Write)

# forge.yaml
forge:
  name: greeter
  version: 1.0.0

tools:
  - type: native
    name: greet
    handler:
      path: handlers::greet_handler
    params:
      name: { type: string, required: true }

// src/handlers.rs
use pforge_runtime::{Handler, Result, Error};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    name: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct GreetOutput {
    message: String,
}

pub struct GreetHandler;

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("Hello, {}!", input.name)
        })
    }
}

pub use GreetHandler as greet_handler;

What pforge Generates (Under the Hood)

When you run pforge build, it generates something like:

// Generated by pforge codegen
use pmcp::ServerBuilder;
use pforge_runtime::HandlerRegistry;

pub fn build_server() -> Result<pmcp::Server> {
    let mut registry = HandlerRegistry::new();

    // Register handlers
    registry.register("greet", handlers::greet_handler);

    // Build pmcp server
    let server = ServerBuilder::new()
        .name("greeter")
        .version("1.0.0")
        .tool_typed("greet", |args: handlers::GreetInput, _extra| {
            Box::pin(async move {
                let handler = handlers::greet_handler;
                let output = handler.handle(args).await?;
                Ok(serde_json::to_value(output)?)
            })
        })
        .build()?;

    Ok(server)
}

Key Point: pforge generates pmcp code!

The Handler Abstraction

pforge defines a Handler trait that’s compatible with pmcp’s TypedTool:

// pforge-runtime/src/handler.rs
#[async_trait::async_trait]
pub trait Handler: Send + Sync {
    type Input: for<'de> Deserialize<'de> + JsonSchema;
    type Output: Serialize + JsonSchema;
    type Error: Into<Error>;

    async fn handle(&self, input: Self::Input)
        -> Result<Self::Output, Self::Error>;
}

This trait is designed to be zero-cost and directly map to pmcp’s TypedTool API.

Real Example: How pforge Uses pmcp in Runtime

From pforge-runtime/src/handler.rs:

// pforge integrates with pmcp's type system
use schemars::JsonSchema;  // Same as pmcp uses
use serde::{Deserialize, Serialize};  // Same as pmcp uses

/// Handler trait compatible with pmcp TypedTool
#[async_trait::async_trait]
pub trait Handler: Send + Sync {
    type Input: for<'de> Deserialize<'de> + JsonSchema;
    type Output: Serialize + JsonSchema;
    type Error: Into<Error>;

    async fn handle(&self, input: Self::Input)
        -> Result<Self::Output, Self::Error>;
}

Notice: The trait bounds match pmcp’s requirements exactly:

• Deserialize for input parsing
• Serialize for output JSON
• JsonSchema for MCP schema generation
• Send + Sync for async runtime

When pforge Calls pmcp

Here’s the actual flow when you run pforge serve:

1. pforge CLI parses forge.yaml
   ↓
2. pforge-codegen generates Rust code
   ↓
3. Generated code creates HandlerRegistry
   ↓
4. Registry wraps handlers in pmcp TypedTool
   ↓
5. pmcp ServerBuilder builds the server
   ↓
6. pmcp handles MCP protocol (stdio/SSE/WebSocket)
   ↓
7. pmcp routes requests to handlers
   ↓
8. pforge Handler executes and returns
   ↓
9. pmcp serializes response to JSON-RPC

Performance: Why pforge is Faster for Dispatch

pmcp: General-purpose HashMap lookup

// In pmcp (simplified)
let tool = tools.get(tool_name)?;  // HashMap lookup
tool.execute(args).await

pforge: Compile-time perfect hash

// Generated by pforge (simplified)
match tool_name {
    "greet" => greet_handler.handle(args).await,
    "calculate" => calculate_handler.handle(args).await,
    // ... compile-time matched
    _ => Err(ToolNotFound)
}

Result: <1μs dispatch in pforge vs <10μs in pmcp

Using Both Together

You can mix pforge and pmcp in the same project!

Example: pforge for Simple Tools, pmcp for Complex Logic

# forge.yaml - Simple tools in pforge
tools:
  - type: native
    name: greet
    handler:
      path: handlers::greet_handler

// main.rs - Add complex pmcp tool
use pmcp::ServerBuilder;

#[tokio::main]
async fn main() -> Result<()> {
    // Load pforge-generated server
    let mut server = pforge_runtime::build_from_config("forge.yaml")?;

    // Add custom pmcp tool with complex logic
    server.add_tool_typed("complex_stateful", |args, extra| {
        Box::pin(async move {
            // Custom logic not expressible in pforge YAML
            // Maybe database transactions, WebSocket, etc.
            todo!()
        })
    });

    server.run_stdio().await
}

Dependency Versions

pforge tracks pmcp versions:

Summary: The Relationship

Think of it like this:

• pmcp = Express.js (low-level web framework)
• pforge = Next.js (opinionated framework on Express)

Or in Rust terms:

• pmcp = actix-web (low-level HTTP server)
• pforge = Rocket (high-level framework on actix)

Both are necessary:

• pmcp provides the MCP protocol implementation
• pforge provides the declarative YAML layer + quality tools

You’re using pmcp whether you know it or not:

• Every pforge server is a pmcp server
• pforge just generates the pmcp code for you

When to Drop Down to pmcp

Use pure pmcp directly when pforge’s handler types don’t fit:

❌ Can’t express in pforge:

• Custom server lifecycle hooks
• Stateful request correlation
• Custom transport implementations
• Dynamic tool registration
• WebAssembly compilation
• Database connection pools with transactions

✅ Can express in pforge:

• Standard CRUD operations
• CLI tool wrappers
• HTTP API proxies
• Simple data transformations
• Multi-tool pipelines
• Standard state management

Verification: Check the Dependency

# See pmcp in pforge's dependencies
$ grep pmcp crates/pforge-runtime/Cargo.toml
pmcp = "1.6"

# See pforge using pmcp types
$ rg "pmcp::" crates/pforge-runtime/src/
# (Currently minimal direct usage - trait compat layer)

Future: pforge May Expose More pmcp Features

Future pforge versions may expose:

• Custom middleware (pmcp has this)
• Sampling requests (pmcp has this)
• Logging handlers (pmcp has this)
• Custom transports (pmcp has this)

For now, drop down to pmcp for these features.

Next: Migration Between Them

Quick Reference

Chapter 2: Quick Start

Welcome to pforge! In this chapter, you’ll go from zero to a running MCP server in under 10 minutes.

What You’ll Build

By the end of this chapter, you’ll have:

1. Installed pforge on your system
2. Scaffolded a new MCP server project
3. Understood the generated project structure
4. Run your first server
5. Tested it with an MCP client

The Three-File Philosophy

A typical pforge project requires just three files:

my-server/
├── pforge.yaml      # Declarative configuration
├── Cargo.toml       # Rust dependencies (auto-generated)
└── src/
    └── handlers.rs  # Your business logic

That’s it. No boilerplate, no ceremony, just your configuration and handlers.

Why So Fast?

Traditional MCP server development requires:

• Setting up project structure
• Implementing protocol handlers
• Writing serialization/deserialization code
• Configuring transport layers
• Managing schema generation

pforge generates all of this from your YAML configuration:

forge:
  name: my-server
  version: 0.1.0

tools:
  - type: native
    name: greet
    description: "Say hello"
    handler:
      path: handlers::greet_handler
    params:
      name: { type: string, required: true }

This 10-line YAML declaration produces a fully functional MCP server with:

• Type-safe input validation
• JSON Schema generation
• Error handling
• Transport configuration
• Tool registration
• Handler dispatch

Performance Out of the Box

Your first server will achieve production-grade performance:

• Tool dispatch: <1 microsecond
• Cold start: <100 milliseconds
• Memory overhead: <512KB
• Throughput: >100K requests/second

These aren’t aspirational goals - they’re guaranteed by pforge’s compile-time code generation.

The EXTREME TDD Journey

As you build your server, you’ll follow EXTREME TDD methodology:

1. Write a failing test (RED phase)
2. Implement minimal code to pass (GREEN phase)
3. Refactor and run quality gates (REFACTOR phase)

Each cycle takes 5 minutes or less. Quality gates automatically enforce:

• Code formatting (rustfmt)
• Linting (clippy)
• Test coverage (>80%)
• Complexity limits (<20)
• Technical debt grade (>75)

What This Chapter Covers

Installation

Learn how to install pforge from crates.io or build from source. Verify your installation with diagnostic commands.

Your First Server

Scaffold a new project and understand the generated structure. Explore the YAML configuration and handler implementation.

Testing Your Server

Run your server and test it with an MCP client. Learn basic debugging and troubleshooting techniques.

Prerequisites

You’ll need:

• Rust 1.70 or later (install from rustup.rs)
• Basic terminal/command line familiarity
• A text editor (VS Code, Vim, etc.)

That’s all. No complex environment setup, no Docker, no additional services.

Time Investment

• Installation: 2 minutes
• First server: 5 minutes
• Testing: 3 minutes
• Total: 10 minutes

What You Won’t Learn (Yet)

This chapter focuses on getting you productive quickly. We’ll cover advanced topics later:

• Multiple handler types (CLI, HTTP, Pipeline) - Chapter 5
• State management - Chapter 9
• Error handling patterns - Chapter 10
• Performance optimization - Chapter 17
• Production deployment - Chapter 19

For now, let’s get your development environment set up and build your first server.

Support

If you get stuck:

1. Check the GitHub Issues
2. Review the full specification
3. Examine the examples directory

Ready? Let’s begin with installation.

Next: Installation

Installation

Installing pforge takes less than two minutes. You have two options: install from crates.io (recommended) or build from source.

Prerequisites

Before installing pforge, ensure you have Rust installed:

# Check if Rust is installed
rustc --version

# If not installed, get it from rustup.rs
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

You’ll need Rust 1.70 or later. pforge leverages modern Rust features for performance and safety.

Option 1: Install from crates.io (Recommended)

The simplest installation method:

cargo install pforge-cli

This downloads the pre-built pforge CLI from crates.io and installs it to ~/.cargo/bin/pforge.

Expected output:

    Updating crates.io index
  Downloaded pforge-cli v0.1.0
  Downloaded 1 crate (45.2 KB) in 0.89s
   Compiling pforge-cli v0.1.0
    Finished release [optimized] target(s) in 1m 23s
  Installing ~/.cargo/bin/pforge
   Installed package `pforge-cli v0.1.0` (executable `pforge`)

Installation typically takes 1-2 minutes depending on your connection speed and CPU.

Option 2: Build from Source

For the latest development version or to contribute:

# Clone the repository
git clone https://github.com/paiml/pforge
cd pforge

# Build and install
cargo install --path crates/pforge-cli

# Or use the Makefile
make install

Building from source gives you:

• Latest features not yet published to crates.io
• Ability to modify the source code
• Development environment for contributing

Note: Source builds take longer (3-5 minutes) due to full dependency compilation.

Verify Installation

Check that pforge is correctly installed:

pforge --version

Expected output:

pforge 0.1.0

Try the help command:

pforge --help

You should see:

pforge 0.1.0
A declarative framework for building MCP servers

USAGE:
    pforge <SUBCOMMAND>

SUBCOMMANDS:
    new       Create a new pforge project
    serve     Run an MCP server
    build     Build a server binary
    dev       Development mode with hot reload
    test      Run server tests
    help      Print this message or the help of the given subcommand(s)

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

Troubleshooting

Command Not Found

If you see command not found: pforge, ensure ~/.cargo/bin is in your PATH:

# Check if it's in PATH
echo $PATH | grep -q ".cargo/bin" && echo "Found" || echo "Not found"

# Add to PATH (add this to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

Compilation Errors

If installation fails with compilation errors:

1. Update Rust to the latest stable version:

rustup update stable
rustup default stable

2. Clear the cargo cache and retry:

cargo clean
cargo install pforge-cli --force

3. Check for system dependencies (Linux):

# Ubuntu/Debian
sudo apt-get install build-essential pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install gcc pkg-config openssl-devel

Network Issues

If crates.io download fails:

1. Check your internet connection
2. Try using a mirror or proxy
3. Build from source as a fallback

Platform-Specific Notes

macOS

pforge works out of the box on macOS 10.15 or later. For Apple Silicon (M1/M2):

# Verify architecture
uname -m  # Should show arm64

# Install normally
cargo install pforge-cli

Linux

Tested on:

• Ubuntu 20.04+ (x86_64, ARM64)
• Debian 11+
• Fedora 35+
• Arch Linux (latest)

Ensure you have a C compiler (gcc or clang) installed.

Windows

pforge supports Windows 10 and later with either:

• MSVC toolchain (recommended)
• GNU toolchain (mingw-w64)

# Install using PowerShell
cargo install pforge-cli

# Verify
pforge --version

Note: Some examples use Unix-style paths. Windows users should adjust accordingly.

Development Dependencies (Optional)

For the full development experience with quality gates:

# Install cargo-watch for hot reload
cargo install cargo-watch

# Install cargo-tarpaulin for coverage (Linux only)
cargo install cargo-tarpaulin

# Install cargo-mutants for mutation testing
cargo install cargo-mutants

# Install pmat for quality analysis
cargo install pmat

These are optional for basic usage but required if you plan to:

• Run quality gates (make quality-gate)
• Use watch mode (pforge dev --watch)
• Measure test coverage
• Perform mutation testing

Updating pforge

To update to the latest version:

cargo install pforge-cli --force

The --force flag reinstalls even if the current version is up to date.

Check release notes at: https://github.com/paiml/pforge/releases

Uninstalling

To remove pforge:

cargo uninstall pforge-cli

This removes the binary from ~/.cargo/bin/pforge.

Next Steps

Now that pforge is installed, let’s create your first server.

Next: Your First Server

Your First Server

Let’s build your first MCP server using pforge. We’ll create a simple greeting server that demonstrates the core concepts.

Scaffold a New Project

Create a new pforge project with the new command:

pforge new hello-server
cd hello-server

This creates a complete project structure:

hello-server/
├── pforge.yaml          # Server configuration
├── Cargo.toml           # Rust dependencies
├── .gitignore           # Git ignore rules
└── src/
    ├── lib.rs           # Library root
    └── handlers/
        ├── mod.rs       # Handler module exports
        └── greet.rs     # Example greeting handler

The scaffolded project includes:

• A working example handler
• Pre-configured dependencies
• Sensible defaults
• Git integration

Explore the Configuration

Open pforge.yaml to see the server configuration:

forge:
  name: hello-server
  version: 0.1.0
  transport: stdio

tools:
  - type: native
    name: greet
    description: "Greet a person by name"
    handler:
      path: handlers::greet::say_hello
    params:
      name:
        type: string
        required: true
        description: "Name of the person to greet"

Let’s break this down:

The forge Section

forge:
  name: hello-server      # Server identifier
  version: 0.1.0          # Semantic version
  transport: stdio        # Communication channel (stdio, sse, websocket)

The forge section defines server metadata. The stdio transport means the server communicates via standard input/output, perfect for local development.

The tools Section

tools:
  - type: native                           # Handler type
    name: greet                            # Tool identifier
    description: "Greet a person by name"  # Human-readable description
    handler:
      path: handlers::greet::say_hello     # Rust function path
    params:
      name:                                # Parameter name
        type: string                       # Data type
        required: true                     # Validation rule
        description: "Name of the person to greet"

Each tool defines:

• type: How the tool executes (native, cli, http, pipeline)
• name: Unique identifier for the tool
• description: What the tool does
• handler: Where to find the implementation
• params: Input schema with type validation

Understand the Handler

Open src/handlers/greet.rs:

use pforge_runtime::{Handler, Result};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    pub name: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct GreetOutput {
    pub message: String,
}

pub struct GreetHandler;

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("Hello, {}!", input.name),
        })
    }
}

// Alias for YAML reference
pub use GreetHandler as say_hello;

Let’s examine each component:

Input Type

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    pub name: String,
}

• Deserialize: Converts JSON to Rust struct
• JsonSchema: Auto-generates schema for validation
• Matches the params in pforge.yaml

Output Type

#[derive(Debug, Serialize, JsonSchema)]
pub struct GreetOutput {
    pub message: String,
}

• Serialize: Converts Rust struct to JSON
• JsonSchema: Documents the response format
• Type-safe response structure

Handler Implementation

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("Hello, {}!", input.name),
        })
    }
}

The Handler trait requires:

• Input: Request parameters
• Output: Response data
• Error: Error type (usually pforge_runtime::Error)
• handle(): Async function with your logic

Export Alias

pub use GreetHandler as say_hello;

This creates an alias matching the YAML handler.path: handlers::greet::say_hello.

Build the Project

Compile your server:

cargo build

Expected output:

   Compiling pforge-runtime v0.1.0
   Compiling hello-server v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 12.34s

For production builds:

cargo build --release

This enables optimizations for maximum performance.

Run the Server

Start your server:

pforge serve

You should see:

[INFO] Starting hello-server v0.1.0
[INFO] Transport: stdio
[INFO] Registered tools: greet
[INFO] Server ready

The server is now listening on stdin/stdout for MCP protocol messages.

To stop the server, press Ctrl+C.

Customize Your Server

Let’s add a custom greeting parameter. Update pforge.yaml:

tools:
  - type: native
    name: greet
    description: "Greet a person by name"
    handler:
      path: handlers::greet::say_hello
    params:
      name:
        type: string
        required: true
        description: "Name of the person to greet"
      greeting:
        type: string
        required: false
        default: "Hello"
        description: "Custom greeting word"

Update src/handlers/greet.rs:

#[derive(Debug, Deserialize, JsonSchema)]
pub struct GreetInput {
    pub name: String,
    #[serde(default = "default_greeting")]
    pub greeting: String,
}

fn default_greeting() -> String {
    "Hello".to_string()
}

#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: format!("{}, {}!", input.greeting, input.name),
        })
    }
}

Rebuild and test:

cargo build
pforge serve

Now your server accepts both name and an optional greeting parameter.

Project Structure Deep Dive

Cargo.toml

Generated dependencies:

[package]
name = "hello-server"
version = "0.1.0"
edition = "2021"

[dependencies]
pforge-runtime = "0.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
schemars = { version = "0.8", features = ["derive"] }
async-trait = "0.1"
tokio = { version = "1", features = ["full"] }

All dependencies are added automatically by pforge new.

src/lib.rs

Module structure:

pub mod handlers;

This exports your handlers so pforge can find them.

.gitignore

Common Rust ignores:

/target
Cargo.lock
*.swp
.DS_Store

Ready for version control from day one.

Common Customizations

Add a New Tool

Edit pforge.yaml:

tools:
  - type: native
    name: greet
    # ... existing greet tool

  - type: native
    name: farewell
    description: "Say goodbye"
    handler:
      path: handlers::farewell_handler
    params:
      name:
        type: string
        required: true

Create src/handlers/farewell.rs:

use pforge_runtime::{Handler, Result};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, JsonSchema)]
pub struct FarewellInput {
    pub name: String,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct FarewellOutput {
    pub message: String,
}

pub struct FarewellHandler;

#[async_trait::async_trait]
impl Handler for FarewellHandler {
    type Input = FarewellInput;
    type Output = FarewellOutput;
    type Error = pforge_runtime::Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(FarewellOutput {
            message: format!("Goodbye, {}!", input.name),
        })
    }
}

pub use FarewellHandler as farewell_handler;

Update src/handlers/mod.rs:

pub mod greet;
pub mod farewell;

Rebuild and you have two tools.

Change Transport

For HTTP-based communication, update pforge.yaml:

forge:
  name: hello-server
  version: 0.1.0
  transport: sse  # Server-Sent Events

Or for WebSocket:

forge:
  name: hello-server
  version: 0.1.0
  transport: websocket

Each transport has different deployment characteristics covered in Chapter 19.

Development Workflow

The typical development cycle:

1. Edit pforge.yaml to define tools
2. Implement handlers in src/handlers/
3. Build with cargo build
4. Test with cargo test
5. Run with pforge serve

For rapid iteration, use watch mode:

cargo watch -x build -x test

This rebuilds and tests automatically on file changes.

What’s Next

You now have a working MCP server. In the next section, we’ll test it thoroughly and learn debugging techniques.

Next: Testing Your Server

Testing Your Server

Now that you have a working server, let’s test it thoroughly. pforge embraces EXTREME TDD, so testing is a first-class citizen.

Unit Testing Handlers

Start with the most fundamental tests - your handler logic.

Write Your First Test

Open src/handlers/greet.rs and add tests at the bottom:

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_greet_basic() {
        let handler = GreetHandler;
        let input = GreetInput {
            name: "World".to_string(),
        };

        let result = handler.handle(input).await;
        assert!(result.is_ok());

        let output = result.unwrap();
        assert_eq!(output.message, "Hello, World!");
    }

    #[tokio::test]
    async fn test_greet_different_name() {
        let handler = GreetHandler;
        let input = GreetInput {
            name: "Alice".to_string(),
        };

        let result = handler.handle(input).await;
        assert!(result.is_ok());
        assert_eq!(result.unwrap().message, "Hello, Alice!");
    }

    #[tokio::test]
    async fn test_greet_empty_name() {
        let handler = GreetHandler;
        let input = GreetInput {
            name: "".to_string(),
        };

        let result = handler.handle(input).await;
        assert!(result.is_ok());
        assert_eq!(result.unwrap().message, "Hello, !");
    }
}

Run the Tests

Execute your test suite:

cargo test

Expected output:

   Compiling hello-server v0.1.0
    Finished test [unoptimized + debuginfo] target(s) in 2.34s
     Running unittests src/lib.rs

running 3 tests
test handlers::greet::tests::test_greet_basic ... ok
test handlers::greet::tests::test_greet_different_name ... ok
test handlers::greet::tests::test_greet_empty_name ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

All tests pass! Each test runs in microseconds.

Test Best Practices

Following EXTREME TDD principles:

#[tokio::test]
async fn test_should_handle_unicode_names() {
    // Arrange
    let handler = GreetHandler;
    let input = GreetInput {
        name: "世界".to_string(),  // "World" in Japanese
    };

    // Act
    let result = handler.handle(input).await;

    // Assert
    assert!(result.is_ok());
    assert_eq!(result.unwrap().message, "Hello, 世界!");
}

Structure tests with Arrange-Act-Assert:

1. Arrange: Set up test data
2. Act: Execute the function
3. Assert: Verify results

Integration Testing

Integration tests verify the entire server stack, not just individual handlers.

Create Integration Tests

Create tests/integration_test.rs:

use hello_server::handlers::greet::{GreetHandler, GreetInput};
use pforge_runtime::Handler;

#[tokio::test]
async fn test_handler_integration() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "Integration Test".to_string(),
    };

    let output = handler.handle(input).await.expect("handler failed");
    assert!(output.message.contains("Integration Test"));
}

Run integration tests:

cargo test --test integration_test

Integration tests live in the tests/ directory and have full access to your library.

Testing with MCP Clients

To test the full MCP protocol, use an MCP client.

Manual Testing with stdio

Start your server:

pforge serve

In another terminal, use an MCP inspector tool or send raw JSON-RPC messages:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | pforge serve

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "greet",
        "description": "Greet a person by name",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the person to greet"
            }
          },
          "required": ["name"]
        }
      }
    ]
  }
}

Call a Tool

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}}}' | pforge serve

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"message\":\"Hello, World!\"}"
      }
    ]
  }
}

Test Coverage

Measure your test coverage with cargo-tarpaulin:

# Install tarpaulin (Linux only)
cargo install cargo-tarpaulin

# Run coverage analysis
cargo tarpaulin --out Html

This generates tarpaulin-report.html showing line-by-line coverage.

pforge’s quality gates enforce 80% minimum coverage. Check with:

cargo tarpaulin --out Json | jq '.files | to_entries | map(.value.coverage) | add / length'

Target: ≥ 0.80 (80%)

Watch Mode for TDD

For rapid RED-GREEN-REFACTOR cycles:

cargo watch -x test

This runs tests automatically when files change. Perfect for EXTREME TDD’s 5-minute cycles.

Advanced watch mode:

cargo watch -x 'test --lib --quiet' -x 'clippy --quiet'

Runs tests AND linting on every change.

Debugging Tests

Enable Logging

Add logging to your handler:

use tracing::info;

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    info!("Handling greet request for: {}", input.name);
    Ok(GreetOutput {
        message: format!("Hello, {}!", input.name),
    })
}

Run tests with logging:

RUST_LOG=debug cargo test -- --nocapture

Debug Individual Tests

Run a single test:

cargo test test_greet_basic

Run with output:

cargo test test_greet_basic -- --nocapture --exact

Error Handling Tests

Test error paths to ensure robustness:

#[tokio::test]
async fn test_validation_error() {
    let handler = GreetHandler;
    // Simulate invalid input by testing edge cases
    let input = GreetInput {
        name: "A".repeat(10000),  // Very long name
    };

    let result = handler.handle(input).await;
    // Depending on your validation, this might error or succeed
    assert!(result.is_ok() || result.is_err());
}

For handlers that can fail:

use pforge_runtime::Error;

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.name.is_empty() {
        return Err(Error::Validation("Name cannot be empty".to_string()));
    }
    Ok(GreetOutput {
        message: format!("Hello, {}!", input.name),
    })
}

#[tokio::test]
async fn test_empty_name_validation() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "".to_string(),
    };

    let result = handler.handle(input).await;
    assert!(result.is_err());

    let err = result.unwrap_err();
    assert!(err.to_string().contains("empty"));
}

Performance Testing

Benchmark your handlers:

cargo bench

For quick performance checks:

#[tokio::test]
async fn test_handler_performance() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "Benchmark".to_string(),
    };

    let start = std::time::Instant::now();

    for _ in 0..10_000 {
        let _ = handler.handle(input.clone()).await;
    }

    let elapsed = start.elapsed();
    println!("10,000 calls took: {:?}", elapsed);

    // Should be under 10ms for 10K simple operations
    assert!(elapsed.as_millis() < 10);
}

pforge handlers should dispatch in <1 microsecond each.

Quality Gates

Run all quality checks before committing:

# Format check
cargo fmt --check

# Linting
cargo clippy -- -D warnings

# Tests
cargo test --all

# Coverage (Linux)
cargo tarpaulin --out Json

# Full quality gate
make quality-gate

The make quality-gate command runs:

1. Code formatting validation
2. Clippy linting (all warnings as errors)
3. All tests (unit + integration)
4. Coverage analysis (≥80%)
5. Complexity checks (≤20 per function)
6. Technical debt grade (≥75)

Any failure blocks commits when using pre-commit hooks.

Common Testing Patterns

Test Fixtures

Reuse test data:

fn sample_input() -> GreetInput {
    GreetInput {
        name: "Test".to_string(),
    }
}

#[tokio::test]
async fn test_with_fixture() {
    let handler = GreetHandler;
    let input = sample_input();
    let result = handler.handle(input).await;
    assert!(result.is_ok());
}

Parameterized Tests

Test multiple cases:

#[tokio::test]
async fn test_greet_multiple_names() {
    let handler = GreetHandler;
    let test_cases = vec!["Alice", "Bob", "Charlie", "世界"];

    for name in test_cases {
        let input = GreetInput {
            name: name.to_string(),
        };
        let result = handler.handle(input).await;
        assert!(result.is_ok());
        assert!(result.unwrap().message.contains(name));
    }
}

Async Test Helpers

Extract common async patterns:

async fn run_handler(name: &str) -> String {
    let handler = GreetHandler;
    let input = GreetInput {
        name: name.to_string(),
    };
    handler.handle(input).await.unwrap().message
}

#[tokio::test]
async fn test_with_helper() {
    let message = run_handler("Helper").await;
    assert_eq!(message, "Hello, Helper!");
}

Troubleshooting

Tests Hang

If tests never complete:

# Run with timeout
cargo test -- --test-threads=1 --nocapture

# Check for deadlocks
RUST_LOG=trace cargo test

Compilation Errors

# Clean and rebuild
cargo clean
cargo test

# Update dependencies
cargo update

Test Failures

Use --nocapture to see println! output:

cargo test -- --nocapture

Add debug output:

#[tokio::test]
async fn test_debug() {
    let result = handler.handle(input).await;
    dbg!(&result);  // Print detailed debug info
    assert!(result.is_ok());
}

Next Steps

You now have a fully tested MCP server. Congratulations!

In the next chapters, we’ll explore:

• Advanced handler types (CLI, HTTP, Pipeline)
• State management and persistence
• Error handling strategies
• Production deployment

Your foundation in EXTREME TDD will serve you well as we tackle more complex topics.

Next: Chapter 3: Understanding pforge Architecture

Calculator Server: Your First Real MCP Tool

In Chapter 2, we built a simple “Hello, World!” server. Now we’ll build something production-ready: a calculator server that demonstrates EXTREME TDD principles, robust error handling, and comprehensive testing.

What You’ll Build

A calculator MCP server that:

• Performs four arithmetic operations: add, subtract, multiply, divide
• Validates inputs and handles edge cases (division by zero)
• Has 100% test coverage with 6 comprehensive tests
• Follows the EXTREME TDD 5-minute cycle
• Uses a single native Rust handler for maximum performance

Why a Calculator?

The calculator example is deliberately simple, but it teaches critical concepts:

1. Error Handling: Division by zero shows proper error propagation
2. Input Validation: Unknown operations demonstrate validation patterns
3. Test Coverage: Six tests cover happy paths and error cases
4. Type Safety: Floating-point operations with strong typing
5. Pattern Matching: Rust’s match expression for operation dispatch

The EXTREME TDD Journey

We’ll build this calculator following strict 5-minute cycles:

Total development time: 20 minutes from empty file to production-ready code.

Architecture Overview

Calculator Server
├── forge.yaml (26 lines)
│   └── Single "calculate" tool definition
├── src/handlers.rs (138 lines)
│   ├── CalculateInput struct
│   ├── CalculateOutput struct
│   ├── CalculateHandler implementation
│   └── 6 comprehensive tests
└── Cargo.toml (16 lines)

Total code: 180 lines including tests. Traditional MCP SDK: 400+ lines.

Key Features

1. Single Tool, Multiple Operations

Instead of four separate tools (add, subtract, multiply, divide), we use one tool with an operation parameter. This demonstrates:

• Parameter-based dispatch
• Cleaner API surface
• Shared validation logic

2. Robust Error Handling

The calculator handles two error cases:

• Division by zero: Returns descriptive error message
• Unknown operation: Suggests valid operations

Both follow pforge’s error handling philosophy: never panic, always inform.

3. Floating-Point Precision

Uses f64 for all operations, supporting:

• Decimal values (e.g., 10.5 + 3.7)
• Large numbers
• Scientific notation

4. Comprehensive Testing

Six tests provide 100% coverage:

1. Addition (happy path)
2. Subtraction (happy path)
3. Multiplication (happy path)
4. Division (happy path)
5. Division by zero (error path)
6. Unknown operation (error path)

Performance Characteristics

What You’ll Learn

By the end of this chapter, you’ll understand:

1. Chapter 3.1 - YAML Configuration: How to define tools with typed parameters
2. Chapter 3.2 - Handler Implementation: Writing handlers with error handling
3. Chapter 3.3 - Testing: EXTREME TDD with comprehensive test coverage
4. Chapter 3.4 - Running: Building, serving, and using your calculator

The EXTREME TDD Mindset

As we build this calculator, remember the core principles:

RED: Write the smallest failing test (2 minutes max) GREEN: Write the minimum code to pass (2 minutes max) REFACTOR: Clean up and verify quality gates (1 minute max) COMMIT: If all gates pass RESET: If cycle exceeds 5 minutes

Every line of code in this calculator was written test-first. Every commit passed all quality gates. This is not aspirational - it’s how pforge development works.

Prerequisites

Before starting, ensure you have:

• Rust 1.70+ installed
• pforge CLI installed (cargo install pforge)
• Basic understanding of Rust syntax
• Familiarity with cargo and async/await

Let’s Begin

Turn to Chapter 3.1 to start with the YAML configuration. You’ll see how 26 lines of declarative config replaces hundreds of lines of boilerplate.

“The calculator teaches error handling, the discipline teaches excellence.” - pforge philosophy

YAML Configuration: Declaring Your Calculator

The calculator’s YAML configuration is 26 lines that replace hundreds of lines of SDK boilerplate. Let’s build it following EXTREME TDD principles.

The Complete Configuration

Here’s the full forge.yaml for our calculator server:

forge:
  name: calculator-server
  version: 0.1.0
  transport: stdio
  optimization: release

tools:
  - type: native
    name: calculate
    description: "Perform arithmetic operations (add, subtract, multiply, divide)"
    handler:
      path: handlers::calculate_handler
    params:
      operation:
        type: string
        required: true
        description: "The operation to perform: add, subtract, multiply, or divide"
      a:
        type: float
        required: true
        description: "First operand"
      b:
        type: float
        required: true
        description: "Second operand"

Section-by-Section Breakdown

1. Forge Metadata

forge:
  name: calculator-server
  version: 0.1.0
  transport: stdio
  optimization: release

Key decisions:

• name: Unique identifier for your server
• version: Semantic versioning (important for client compatibility)
• transport: stdio: Standard input/output (most common for MCP)
• optimization: release: Build with optimizations enabled (<1μs dispatch)

Alternative transports:

• sse: Server-Sent Events (web-based)
• websocket: WebSocket (bidirectional streaming)

For local tools like calculators, stdio is the right choice.

2. Tool Definition

tools:
  - type: native
    name: calculate
    description: "Perform arithmetic operations (add, subtract, multiply, divide)"

Why a single tool?

Instead of four separate tools (add, subtract, multiply, divide), we use one tool with an operation parameter. Benefits:

1. Cleaner API: Clients see one tool, not four
2. Shared logic: Validation happens once
3. Easier testing: Test one handler, not four
4. Better UX: “I want to calculate” vs “I want to add or subtract or…”

The description field is critical - it’s what LLMs see when deciding which tool to use. Make it specific and actionable.

3. Handler Path

    handler:
      path: handlers::calculate_handler

This tells pforge where to find your Rust handler:

• Module: handlers (the src/handlers.rs file)
• Symbol: calculate_handler (the exported handler struct)

Convention: Use {module}::{handler_name} format. The handler must implement the Handler trait.

4. Parameter Schema

    params:
      operation:
        type: string
        required: true
        description: "The operation to perform: add, subtract, multiply, or divide"
      a:
        type: float
        required: true
        description: "First operand"
      b:
        type: float
        required: true
        description: "Second operand"

Parameter types:

• string: For operation names (“add”, “subtract”, etc.)
• float: For f64 numeric values (supports decimals)
• required: true: Validation fails if missing

Why float not number?

MCP/JSON Schema distinguishes:

• integer: Whole numbers only
• float: Decimal/floating-point numbers

Our calculator supports 10.5 + 3.7, so we need float.

Type Safety in Action

pforge uses this YAML to generate Rust types. The params:

params:
  operation: { type: string, required: true }
  a: { type: float, required: true }
  b: { type: float, required: true }

Become this Rust struct (auto-generated):

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    pub operation: String,
    pub a: f64,
    pub b: f64,
}

No runtime validation needed - the type system guarantees correctness!

EXTREME TDD: Configuration First

In our 5-minute cycles, the YAML came before the handler:

Cycle 0 (3 minutes):

1. RED: Create empty forge.yaml, run pforge build → fails (no handler)
2. GREEN: Add forge metadata and basic tool structure
3. REFACTOR: Add parameter descriptions

This design-first approach forces you to think about:

• What inputs do I need?
• What types make sense?
• What’s the API contract?

Common YAML Patterns

Pattern 1: Optional Parameters

params:
  operation: { type: string, required: true }
  precision: { type: integer, required: false, default: 2 }

Pattern 2: Enum Constraints

params:
  operation:
    type: string
    required: true
    enum: ["add", "subtract", "multiply", "divide"]

We didn’t use enum constraints because we validate in Rust, giving better error messages.

Pattern 3: Nested Objects

params:
  calculation:
    type: object
    required: true
    properties:
      operation: { type: string }
      operands:
        type: array
        items: { type: float }

Pattern 4: Arrays

params:
  numbers:
    type: array
    required: true
    items: { type: float }
    minItems: 2

Validation Strategy

Two-layer validation:

1. YAML validation (at build time):

   • pforge validates against its schema
   • Catches: missing required fields, invalid types
   • Fast fail: Won’t even compile

2. Runtime validation (in handler):

   • Check operation is valid
   • Check division by zero
   • Custom business logic

Philosophy: Use the type system first, runtime validation second.

Configuration vs. Code

Traditional MCP SDK (TypeScript):

// 50+ lines of boilerplate
const server = new Server({
  name: "calculator-server",
  version: "0.1.0"
}, {
  capabilities: {
    tools: {}
  }
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "calculate",
    description: "Perform arithmetic operations",
    inputSchema: {
      type: "object",
      properties: {
        operation: { type: "string", description: "..." },
        a: { type: "number", description: "..." },
        b: { type: "number", description: "..." }
      },
      required: ["operation", "a", "b"]
    }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate") {
    // ... handler logic
  }
});

pforge equivalent:

# 26 lines, zero boilerplate
forge:
  name: calculator-server
  version: 0.1.0
  transport: stdio
  optimization: release

tools:
  - type: native
    name: calculate
    # ... (see above)

90% less code. 100% type-safe. 16x faster.

Build-Time Code Generation

When you run pforge build, this YAML generates:

1. Handler registry: O(1) lookup for “calculate” tool
2. Type definitions: CalculateInput struct with validation
3. JSON Schema: For MCP protocol compatibility
4. Dispatch logic: Routes requests to your handler

All at compile time - zero runtime overhead.

Debugging Configuration

Common errors and fixes:

Error: “Handler not found: handlers::calculate_handler”

# Wrong:
handler:
  path: calculate_handler

# Right:
handler:
  path: handlers::calculate_handler

Error: “Invalid type: expected float, found string”

# Wrong:
params:
  a: { type: string }  # User passes "5.0"

# Right:
params:
  a: { type: float }   # Parsed as 5.0

Error: “Missing required parameter: operation”

# Wrong:
params:
  operation: { type: string }  # defaults to required: false

# Right:
params:
  operation: { type: string, required: true }

Testing Your Configuration

Before writing handler code, validate your YAML:

# Validate configuration
pforge validate

# Build (validates + generates code)
pforge build --debug

# Watch mode (continuous validation)
pforge dev --watch

EXTREME TDD tip: Run pforge validate after every YAML edit. Fast feedback!

Next Steps

Now that you have a valid configuration, it’s time to implement the handler. Turn to Chapter 3.2 to write the Rust code that powers the calculator.

“Configuration is code. Treat it with the same rigor.” - pforge philosophy

The Rust Handler: Building the Calculator Logic

Now that we have our YAML configuration, let’s implement the calculator’s business logic using EXTREME TDD. We’ll write this handler in six 5-minute cycles, building confidence with each passing test.

The Complete Handler

Here’s the full src/handlers.rs (138 lines including tests):

use pforge_runtime::{Error, Handler, Result};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    pub operation: String,
    pub a: f64,
    pub b: f64,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalculateOutput {
    pub result: f64,
}

pub struct CalculateHandler;

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalculateInput;
    type Output = CalculateOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let result = match input.operation.as_str() {
            "add" => input.a + input.b,
            "subtract" => input.a - input.b,
            "multiply" => input.a * input.b,
            "divide" => {
                if input.b == 0.0 {
                    return Err(Error::Handler("Division by zero".to_string()));
                }
                input.a / input.b
            }
            _ => {
                return Err(Error::Handler(format!(
                    "Unknown operation: {}. Supported: add, subtract, multiply, divide",
                    input.operation
                )))
            }
        };

        Ok(CalculateOutput { result })
    }
}

// Re-export for easier access
pub use CalculateHandler as calculate_handler;

Breaking It Down: The EXTREME TDD Journey

Cycle 1: Addition (4 minutes)

RED (1 min): Write the failing test

#[tokio::test]
async fn test_add() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "add".to_string(),
        a: 5.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 8.0);
}

Run cargo test → Fails (no handler implementation yet)

GREEN (2 min): Minimum code to pass

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    pub operation: String,
    pub a: f64,
    pub b: f64,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalculateOutput {
    pub result: f64,
}

pub struct CalculateHandler;

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalculateInput;
    type Output = CalculateOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let result = if input.operation == "add" {
            input.a + input.b
        } else {
            0.0  // Temporary - will refactor
        };

        Ok(CalculateOutput { result })
    }
}

Run cargo test → Passes!

REFACTOR (1 min): Extract handler pattern

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let result = match input.operation.as_str() {
        "add" => input.a + input.b,
        _ => 0.0,
    };

    Ok(CalculateOutput { result })
}

Run cargo test → Still passes. Commit!

Cycle 2: Subtraction (3 minutes)

RED (1 min):

#[tokio::test]
async fn test_subtract() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "subtract".to_string(),
        a: 10.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 7.0);
}

Run → Fails (returns 0.0)

GREEN (1 min):

let result = match input.operation.as_str() {
    "add" => input.a + input.b,
    "subtract" => input.a - input.b,
    _ => 0.0,
};

Run → Passes!

REFACTOR (1 min): Clean up, run quality gates

cargo fmt
cargo clippy

All pass. Commit!

Cycle 3: Multiplication (2 minutes)

RED + GREEN (1 min each): Same pattern

#[tokio::test]
async fn test_multiply() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "multiply".to_string(),
        a: 4.0,
        b: 5.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 20.0);
}

"multiply" => input.a * input.b,

REFACTOR: None needed. Commit!

Cycle 4: Division (2 minutes)

RED + GREEN: Basic division

#[tokio::test]
async fn test_divide() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "divide".to_string(),
        a: 15.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 5.0);
}

"divide" => input.a / input.b,

Run → Passes. Commit!

Cycle 5: Division by Zero Error (5 minutes)

RED (2 min): Test error handling

#[tokio::test]
async fn test_divide_by_zero() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "divide".to_string(),
        a: 10.0,
        b: 0.0,
    };

    let result = handler.handle(input).await;
    assert!(result.is_err());
    assert!(result.unwrap_err().to_string().contains("Division by zero"));
}

Run → Fails (returns inf, doesn’t error)

GREEN (2 min): Add error handling

"divide" => {
    if input.b == 0.0 {
        return Err(Error::Handler("Division by zero".to_string()));
    }
    input.a / input.b
}

Run → Passes!

REFACTOR (1 min): Improve error message clarity

return Err(Error::Handler("Division by zero".to_string()));

This is already clear! Commit!

Cycle 6: Unknown Operation Validation (4 minutes)

RED (2 min):

#[tokio::test]
async fn test_unknown_operation() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "modulo".to_string(),
        a: 10.0,
        b: 3.0,
    };

    let result = handler.handle(input).await;
    assert!(result.is_err());
    assert!(result
        .unwrap_err()
        .to_string()
        .contains("Unknown operation"));
}

Run → Fails (returns 0.0, doesn’t error)

GREEN (1 min): Add validation

let result = match input.operation.as_str() {
    "add" => input.a + input.b,
    "subtract" => input.a - input.b,
    "multiply" => input.a * input.b,
    "divide" => {
        if input.b == 0.0 {
            return Err(Error::Handler("Division by zero".to_string()));
        }
        input.a / input.b
    }
    _ => {
        return Err(Error::Handler(format!(
            "Unknown operation: {}",
            input.operation
        )))
    }
};

Run → Passes!

REFACTOR (1 min): Add helpful error message

_ => {
    return Err(Error::Handler(format!(
        "Unknown operation: {}. Supported: add, subtract, multiply, divide",
        input.operation
    )))
}

Run → Still passes. Commit!

Understanding the Handler Trait

Every pforge handler implements this trait:

#[async_trait::async_trait]
impl Handler for CalculateHandler {
    type Input = CalculateInput;   // Request parameters
    type Output = CalculateOutput; // Response data
    type Error = Error;            // Error type

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        // Your logic here
    }
}

Key points:

1. Associated types: Input/Output are strongly typed
2. Async by default: All handlers use async fn
3. Result type: Returns Result<Output, Error> for error handling
4. Zero-cost: Trait compiles to direct function calls

Input and Output Structs

CalculateInput

#[derive(Debug, Deserialize, JsonSchema)]
pub struct CalculateInput {
    pub operation: String,
    pub a: f64,
    pub b: f64,
}

Derives:

• Debug: For logging and debugging
• Deserialize: JSON → Rust conversion
• JsonSchema: Generates MCP-compatible schema

Fields:

• operation: The arithmetic operation name
• a, b: The operands (f64 for floating-point precision)

CalculateOutput

#[derive(Debug, Serialize, JsonSchema)]
pub struct CalculateOutput {
    pub result: f64,
}

Derives:

• Serialize: Rust → JSON conversion
• JsonSchema: For client type hints

Why a struct for one field?

Benefits of wrapping result in a struct:

1. Extensible: Can add metadata later (precision, overflow_detected, etc.)
2. Self-documenting: { "result": 8.0 } vs bare 8.0
3. Type-safe: Prevents accidental raw value returns

Error Handling Philosophy

Never Panic

// WRONG - panics on division by zero
"divide" => input.a / input.b  // Returns infinity for 0.0

// RIGHT - returns error
"divide" => {
    if input.b == 0.0 {
        return Err(Error::Handler("Division by zero".to_string()));
    }
    input.a / input.b
}

pforge rule: Production code NEVER uses unwrap(), expect(), or panic!().

Informative Error Messages

// WRONG - vague
return Err(Error::Handler("Invalid operation".to_string()))

// RIGHT - actionable
return Err(Error::Handler(format!(
    "Unknown operation: {}. Supported: add, subtract, multiply, divide",
    input.operation
)))

Best practice: Tell users what went wrong AND how to fix it.

Error Types

pforge provides these error variants:

Error::Handler(String)        // Handler logic errors
Error::Validation(String)     // Input validation failures
Error::ToolNotFound(String)   // Tool doesn't exist
Error::Timeout(String)        // Operation timed out

For calculator, we use Error::Handler for both division by zero and unknown operations.

Pattern Matching for Dispatch

match input.operation.as_str() {
    "add" => input.a + input.b,
    "subtract" => input.a - input.b,
    "multiply" => input.a * input.b,
    "divide" => { /* ... */ },
    _ => { /* error */ }
}

Why this pattern?

1. Exhaustive: Compiler warns if we miss a case
2. Fast: O(1) string comparison with small const strings
3. Readable: Clear mapping of operation → logic
4. Extendable: Easy to add new operations

Alternative: HashMap lookup (unnecessary overhead for 4 operations)

Re-export Convenience

pub use CalculateHandler as calculate_handler;

This allows the YAML config to reference:

handler:
  path: handlers::calculate_handler

Instead of the more verbose:

handler:
  path: handlers::CalculateHandler

Convention: Use snake_case for handler exports.

Performance Characteristics

Our handler is extremely fast:

Why so fast?

1. No allocations in happy path
2. Inline match arms
3. Zero-cost async trait
4. Compile-time optimization

Common Handler Patterns

Pattern 1: Stateless Handlers

pub struct CalculateHandler;  // No fields = stateless

Simplest pattern. Handler has no internal state.

Pattern 2: Stateful Handlers

pub struct CounterHandler {
    count: Arc<Mutex<u64>>,
}

For handlers that need shared state across requests.

Pattern 3: External Service Handlers

pub struct ApiHandler {
    client: reqwest::Client,
}

For handlers that call external APIs.

Pattern 4: Pipeline Handlers

pub struct ProcessorHandler {
    steps: Vec<Box<dyn Step>>,
}

For complex multi-step operations.

Testing Strategy

Our handler has 100% test coverage:

• 4 happy path tests (add, subtract, multiply, divide)
• 2 error path tests (division by zero, unknown operation)

Coverage verification:

cargo tarpaulin --out Stdout
# Should show 100% line coverage for handlers.rs

Next Steps

Now that we have a fully-tested handler, let’s dive deeper into the testing strategy in Chapter 3.3 to understand how EXTREME TDD guarantees quality.

“The handler is simple because the tests came first.” - EXTREME TDD principle

Testing the Calculator: EXTREME TDD in Action

The calculator has six tests that provide 100% code coverage and demonstrate every principle of EXTREME TDD. Let’s examine each test and the discipline that produced them.

The Complete Test Suite

All tests live in src/handlers.rs under the #[cfg(test)] module:

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_add() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "add".to_string(),
            a: 5.0,
            b: 3.0,
        };

        let output = handler.handle(input).await.unwrap();
        assert_eq!(output.result, 8.0);
    }

    #[tokio::test]
    async fn test_subtract() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "subtract".to_string(),
            a: 10.0,
            b: 3.0,
        };

        let output = handler.handle(input).await.unwrap();
        assert_eq!(output.result, 7.0);
    }

    #[tokio::test]
    async fn test_multiply() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "multiply".to_string(),
            a: 4.0,
            b: 5.0,
        };

        let output = handler.handle(input).await.unwrap();
        assert_eq!(output.result, 20.0);
    }

    #[tokio::test]
    async fn test_divide() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "divide".to_string(),
            a: 15.0,
            b: 3.0,
        };

        let output = handler.handle(input).await.unwrap();
        assert_eq!(output.result, 5.0);
    }

    #[tokio::test]
    async fn test_divide_by_zero() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "divide".to_string(),
            a: 10.0,
            b: 0.0,
        };

        let result = handler.handle(input).await;
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("Division by zero"));
    }

    #[tokio::test]
    async fn test_unknown_operation() {
        let handler = CalculateHandler;
        let input = CalculateInput {
            operation: "modulo".to_string(),
            a: 10.0,
            b: 3.0,
        };

        let result = handler.handle(input).await;
        assert!(result.is_err());
        assert!(result
            .unwrap_err()
            .to_string()
            .contains("Unknown operation"));
    }
}

Test Anatomy

Every test follows this four-part structure:

1. Setup (Arrange)

let handler = CalculateHandler;
let input = CalculateInput {
    operation: "add".to_string(),
    a: 5.0,
    b: 3.0,
};

Why create handler locally?

• Each test is independent (no shared state)
• Tests can run in parallel
• No test pollution

2. Execution (Act)

let output = handler.handle(input).await.unwrap();

Key decisions:

• .await: Handler is async (returns Future)
• .unwrap(): For happy path tests, we expect success
• Store result for assertion

3. Verification (Assert)

assert_eq!(output.result, 8.0);

Assertion strategies:

• assert_eq!: For exact values (happy path)
• assert!(): For boolean conditions (error path)
• .contains(): For error message validation

4. Cleanup (Automatic)

Rust’s RAII means cleanup is automatic - no manual teardown needed.

The Six Tests Explained

Test 1: Addition (Happy Path)

#[tokio::test]
async fn test_add() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "add".to_string(),
        a: 5.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 8.0);
}

What it tests:

• Basic addition works
• Input deserialization
• Output serialization
• Handler trait implementation

Edge cases NOT tested (intentionally):

• Float precision (5.1 + 3.2 = 8.3)
• Large numbers (handled by f64)
• Negative numbers (subtraction tests this)

Why 5.0 + 3.0 = 8.0?

Simple numbers avoid floating-point precision issues. This is a smoke test, not a numerical analysis test.

Test 2: Subtraction (Happy Path)

#[tokio::test]
async fn test_subtract() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "subtract".to_string(),
        a: 10.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 7.0);
}

What it adds:

• Pattern matching works for second branch
• Negative results possible (if a < b)

Design choice: 10.0 - 3.0 (positive result) instead of 3.0 - 10.0 (negative result). Either works, we chose simplicity.

Test 3: Multiplication (Happy Path)

#[tokio::test]
async fn test_multiply() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "multiply".to_string(),
        a: 4.0,
        b: 5.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 20.0);
}

What it adds:

• Third pattern match branch
• Result larger than inputs

Why 4.0 * 5.0?

Clean result (20.0) without precision issues.

Test 4: Division (Happy Path)

#[tokio::test]
async fn test_divide() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "divide".to_string(),
        a: 15.0,
        b: 3.0,
    };

    let output = handler.handle(input).await.unwrap();
    assert_eq!(output.result, 5.0);
}

What it adds:

• Division operation works
• Non-zero denominator case

Deliberately tests happy path - error path comes next.

Test 5: Division by Zero (Error Path)

#[tokio::test]
async fn test_divide_by_zero() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "divide".to_string(),
        a: 10.0,
        b: 0.0,
    };

    let result = handler.handle(input).await;
    assert!(result.is_err());
    assert!(result.unwrap_err().to_string().contains("Division by zero"));
}

Critical differences:

• NO .unwrap() - we expect an error
• assert!(result.is_err()) - verify error occurred
• .unwrap_err() - extract error for message validation
• .contains() - verify error message content

Why check error message?

Ensures users get actionable feedback, not just “error occurred.”

Test 6: Unknown Operation (Error Path)

#[tokio::test]
async fn test_unknown_operation() {
    let handler = CalculateHandler;
    let input = CalculateInput {
        operation: "modulo".to_string(),
        a: 10.0,
        b: 3.0,
    };

    let result = handler.handle(input).await;
    assert!(result.is_err());
    assert!(result
        .unwrap_err()
        .to_string()
        .contains("Unknown operation"));
}

What it validates:

• Input validation works
• Catch-all match arm triggered
• Helpful error message provided

Why “modulo”?

Realistic invalid operation that users might try.

Test Coverage Analysis

Run coverage with:

cargo tarpaulin --out Stdout

Expected output:

|| Tested/Total Lines:
|| src/handlers.rs: 45/45 (100%)
||
|| Coverage: 100.00%

Coverage Breakdown

100% line coverage. 100% branch coverage.

Running the Tests

Basic Test Run

cargo test

Output:

running 6 tests
test tests::test_add ... ok
test tests::test_subtract ... ok
test tests::test_multiply ... ok
test tests::test_divide ... ok
test tests::test_divide_by_zero ... ok
test tests::test_unknown_operation ... ok

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

All tests pass in <10ms. This is FAST.

Verbose Output

cargo test -- --nocapture

Shows println! output (though we don’t use it).

Single Test

cargo test test_divide_by_zero

Runs only the division by zero test.

Watch Mode

cargo watch -x test

Runs tests automatically on file save. Perfect for EXTREME TDD.

Test Performance

Total test suite runtime: 3ms

Why so fast?

1. No I/O operations
2. No network calls
3. No file system access
4. Pure computation
5. Optimized by Rust compiler

EXTREME TDD: Test-First Development

These tests were written before the handler code:

The RED-GREEN-REFACTOR Loop

Cycle 1: test_add

• RED: Write test → Fails (handler doesn’t exist)
• GREEN: Write minimal handler → Passes
• REFACTOR: Extract match pattern → Still passes
• COMMIT: Quality gates pass ✅

Cycle 2: test_subtract

• RED: Write test → Fails (only “add” implemented)
• GREEN: Add “subtract” branch → Passes
• REFACTOR: Run clippy → No issues
• COMMIT: Quality gates pass ✅

Pattern repeats for all 6 tests.

Time Investment

20 minutes to production-ready code with 100% coverage.

Test Driven Design Benefits

1. Simpler APIs

Tests forced us to design:

• Single tool instead of four
• Clear input/output structs
• Meaningful error messages

2. Comprehensive Coverage

Writing tests first means:

• No untested code paths
• Edge cases considered upfront
• Error handling built-in

3. Regression Protection

All 6 tests run on every commit:

• Pre-commit hooks prevent breaks
• CI/CD catches integration issues
• Refactoring is safe

4. Living Documentation

Tests show how to use the handler:

// Want to add two numbers?
let input = CalculateInput {
    operation: "add".to_string(),
    a: 5.0,
    b: 3.0,
};
let result = handler.handle(input).await?;
// result.result == 8.0

Testing Anti-Patterns (What We AVOID)

Anti-Pattern 1: Testing Implementation

// WRONG - tests implementation details
#[test]
fn test_match_expression() {
    // Don't test how it's implemented, test what it does
}

Anti-Pattern 2: Over-Mocking

// WRONG - unnecessary mocking
let mock_handler = MockHandler::new();
mock_handler.expect_add().returning(|a, b| a + b);

Our handler is pure logic - no mocks needed.

Anti-Pattern 3: One Assertion Per Test

// WRONG - too granular
#[test]
fn test_output_has_result_field() {
    let output = CalculateOutput { result: 8.0 };
    assert!(output.result == 8.0);  // Useless test
}

Test behavior, not structure.

Anti-Pattern 4: Testing the Framework

// WRONG - testing serde
#[test]
fn test_input_deserializes() {
    let json = r#"{"operation":"add","a":5,"b":3}"#;
    let input: CalculateInput = serde_json::from_str(json).unwrap();
    // Don't test third-party libraries
}

Trust serde. Test your code.

Quality Gates Integration

Tests run as part of quality gates:

make quality-gate

Checks:

1. cargo test - All tests pass ✅
2. cargo tarpaulin - Coverage ≥80% ✅ (we have 100%)
3. cargo clippy - No warnings ✅
4. cargo fmt --check - Formatted ✅
5. pmat analyze complexity - Complexity ≤20 ✅

If ANY gate fails, commit is blocked.

Continuous Testing

During development, run:

cargo watch -x 'test --lib --quiet' -x 'clippy --quiet'

Feedback loop:

1. Save file
2. Tests run (3ms)
3. Clippy runs (200ms)
4. Results shown
5. Total: <300ms feedback

This is the 5-minute cycle in action - fast feedback enables rapid iteration.

Next Steps

Now that you understand the testing philosophy, let’s run the calculator server and use it in Chapter 3.4. You’ll see how these tests translate to production confidence.

“Tests are not just verification - they’re the design process.” - EXTREME TDD principle

Running and Using the Calculator

You’ve built a production-ready calculator with YAML config, Rust handlers, and comprehensive tests. Now let’s run it and see the EXTREME TDD discipline pay off.

Project Setup

If you haven’t created the calculator yet, start here:

# Create a new pforge project
pforge new calculator-server --type native
cd calculator-server

# Copy the example files
cp ../examples/calculator/forge.yaml .
cp ../examples/calculator/src/handlers.rs src/

Or work directly with the example:

cd examples/calculator

Build the Server

Development Build

cargo build

Output:

   Compiling pforge-example-calculator v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 2.34s

Development builds:

• Include debug symbols
• No optimizations
• Fast compile time (~2s)
• Suitable for testing

Release Build

cargo build --release

Output:

   Compiling pforge-example-calculator v0.1.0
    Finished release [optimized] target(s) in 8.67s

Release builds:

• Full optimizations enabled
• Strip debug symbols
• Slower compile (~8s)
• 10x faster runtime (<1μs dispatch)

Use release builds for:

• Production deployment
• Performance benchmarking
• Integration with MCP clients

Run the Tests First

Before running the server, verify everything works:

cargo test

Expected output:

running 6 tests
test tests::test_add ... ok
test tests::test_subtract ... ok
test tests::test_multiply ... ok
test tests::test_divide ... ok
test tests::test_divide_by_zero ... ok
test tests::test_unknown_operation ... ok

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

All 6 tests pass in <10ms. This is the EXTREME TDD confidence - you know it works before running it.

Start the Server

The calculator uses stdio transport (standard input/output), which means it communicates via JSON-RPC over stdin/stdout.

Manual Testing with JSON-RPC

Create a test file test_request.json:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "add",
      "a": 5.0,
      "b": 3.0
    }
  }
}

Run the server with this input:

cargo run --release < test_request.json

Expected output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result\":8.0}"
      }
    ]
  }
}

Success! 5.0 + 3.0 = 8.0

Using with MCP Clients

MCP clients like Claude Desktop, Continue, or Cline can connect to your calculator.

Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "calculator": {
      "command": "cargo",
      "args": ["run", "--release", "--manifest-path", "/path/to/calculator/Cargo.toml"]
    }
  }
}

Replace /path/to/calculator with your actual path.

Restart Claude Desktop

1. Quit Claude Desktop completely
2. Relaunch
3. Your calculator is now available as a tool!

Test from Claude

Try asking Claude:

“What is 123.45 multiplied by 67.89?”

Claude will:

1. See the calculate tool is available
2. Call it with {"operation": "multiply", "a": 123.45, "b": 67.89}
3. Receive the result: 8380.9005
4. Respond: “123.45 × 67.89 = 8,380.90”

Interactive Testing

For development, use a REPL-style workflow:

Option 1: Use pforge dev (if available)

pforge dev

This starts a development server with hot reload.

Option 2: Manual JSON-RPC

Create test_all_operations.sh:

#!/bin/bash

echo "Testing ADD..."
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"add","a":10,"b":5}}}' | cargo run --release

echo "Testing SUBTRACT..."
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"subtract","a":10,"b":5}}}' | cargo run --release

echo "Testing MULTIPLY..."
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"multiply","a":10,"b":5}}}' | cargo run --release

echo "Testing DIVIDE..."
echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"divide","a":10,"b":5}}}' | cargo run --release

echo "Testing DIVIDE BY ZERO..."
echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"divide","a":10,"b":0}}}' | cargo run --release

echo "Testing UNKNOWN OPERATION..."
echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"modulo","a":10,"b":3}}}' | cargo run --release

Run it:

chmod +x test_all_operations.sh
./test_all_operations.sh

Real-World Usage Examples

Example 1: Simple Calculation

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "add",
      "a": 42.5,
      "b": 17.3
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result\":59.8}"
      }
    ]
  }
}

Example 2: Division

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "divide",
      "a": 100,
      "b": 3
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"result\":33.333333333333336}"
      }
    ]
  }
}

Note the floating-point precision - this is expected behavior for f64.

Example 3: Error Handling (Division by Zero)

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "divide",
      "a": 10,
      "b": 0
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32000,
    "message": "Division by zero"
  }
}

Clean error message - exactly what we tested!

Example 4: Error Handling (Unknown Operation)

Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "calculate",
    "arguments": {
      "operation": "power",
      "a": 2,
      "b": 8
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32000,
    "message": "Unknown operation: power. Supported: add, subtract, multiply, divide"
  }
}

Helpful error message tells users what went wrong AND what’s supported.

Performance Verification

Let’s verify our <1μs dispatch target:

Benchmark the Handler

Create benches/calculator_bench.rs:

use criterion::{black_box, criterion_group, criterion_main, Criterion};
use pforge_example_calculator::handlers::{CalculateHandler, CalculateInput};
use pforge_runtime::Handler;

fn benchmark_operations(c: &mut Criterion) {
    let rt = tokio::runtime::Runtime::new().unwrap();

    c.bench_function("add", |b| {
        let handler = CalculateHandler;
        b.to_async(&rt).iter(|| async {
            let input = CalculateInput {
                operation: "add".to_string(),
                a: black_box(5.0),
                b: black_box(3.0),
            };
            handler.handle(input).await.unwrap()
        });
    });

    c.bench_function("divide", |b| {
        let handler = CalculateHandler;
        b.to_async(&rt).iter(|| async {
            let input = CalculateInput {
                operation: "divide".to_string(),
                a: black_box(15.0),
                b: black_box(3.0),
            };
            handler.handle(input).await.unwrap()
        });
    });
}

criterion_group!(benches, benchmark_operations);
criterion_main!(benches);

Run benchmarks:

cargo bench

Expected output:

add                     time:   [450.23 ns 455.67 ns 461.34 ns]
divide                  time:   [782.45 ns 789.12 ns 796.78 ns]

0.45μs for addition, 0.78μs for division - we hit our <1μs target!

Production Deployment

Docker Container

Create Dockerfile:

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bullseye-slim
COPY --from=builder /app/target/release/pforge-example-calculator /usr/local/bin/calculator
ENTRYPOINT ["calculator"]

Build and run:

docker build -t calculator-server .
docker run -i calculator-server

Systemd Service

Create /etc/systemd/system/calculator.service:

[Unit]
Description=Calculator MCP Server
After=network.target

[Service]
Type=simple
User=mcp
ExecStart=/usr/local/bin/calculator
Restart=on-failure
StandardInput=socket
StandardOutput=socket

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable calculator
sudo systemctl start calculator

Troubleshooting

Issue: “Handler not found”

Symptom:

Error: Handler not found: handlers::calculate_handler

Fix: Verify forge.yaml has correct path:

handler:
  path: handlers::calculate_handler  # Not calculate_handler

Issue: “Invalid JSON-RPC”

Symptom:

Error: Invalid JSON-RPC request

Fix: Ensure request has all required fields:

{
  "jsonrpc": "2.0",    # Required
  "id": 1,             # Required
  "method": "tools/call",  # Required
  "params": { ... }    # Required
}

Issue: “Division by zero”

Symptom:

{"error": {"message": "Division by zero"}}

Fix: This is expected behavior! Your error handling works. Pass non-zero b value.

Issue: Slow Performance

Symptom: Operations take >10μs

Fix: Use --release build:

cargo build --release
cargo run --release

Debug builds are 10x slower.

Quality Gate Check

Before deploying, run the full quality gate:

cargo test                          # All tests pass
cargo tarpaulin --out Stdout        # 100% coverage
cargo clippy -- -D warnings         # No warnings
cargo fmt --check                   # Formatted
cargo bench                         # Performance verified

If ANY check fails, DO NOT deploy.

This is EXTREME TDD in action - quality gates prevent production issues.

What You’ve Accomplished

You’ve built a production-ready MCP server that:

✅ Has zero boilerplate (26-line YAML config) ✅ Implements four arithmetic operations ✅ Handles errors gracefully (division by zero, unknown operations) ✅ Has 100% test coverage (6 comprehensive tests) ✅ Achieves <1μs dispatch performance ✅ Runs in 20 minutes of development time ✅ Passes all quality gates

This is the power of EXTREME TDD + pforge.

Next Steps

Now that you’ve mastered the basics:

1. Chapter 4: Add state management to your servers
2. Chapter 5: Implement HTTP and CLI handlers
3. Chapter 6: Build production pipelines
4. Chapter 7: Add fault tolerance and retries

You have the foundation. Let’s build something bigger.

“Ship with confidence. Test-driven code doesn’t fear production.” - EXTREME TDD principle

File Operations: CLI Handler Overview

The CLI handler is pforge’s bridge to the shell - it wraps command-line tools as MCP tools with zero custom code. This chapter demonstrates building a file operations server using common Unix utilities.

Why CLI Handlers?

Use CLI handlers when:

• You want to expose existing shell commands
• The logic already exists in a CLI tool
• You need streaming output from long-running commands
• You’re prototyping quickly without writing Rust

Don’t use CLI handlers when:

• You need complex validation (use Native handlers)
• Performance is critical (< 1μs dispatch - use Native)
• The command has security implications (validate in Rust first)

The File Operations Server

Let’s build a server that wraps common file operations:

forge:
  name: file-ops-server
  version: 0.1.0
  transport: stdio
  optimization: release

tools:
  - type: cli
    name: list_files
    description: "List files in a directory"
    command: ls
    args: ["-lah"]
    params:
      path:
        type: string
        required: false
        default: "."
        description: "Directory to list"

  - type: cli
    name: file_info
    description: "Get detailed file information"
    command: stat
    args: []
    params:
      file:
        type: string
        required: true
        description: "Path to file"

  - type: cli
    name: search_files
    description: "Search for files by name pattern"
    command: find
    args: []
    params:
      directory:
        type: string
        required: false
        default: "."
      pattern:
        type: string
        required: true
        description: "File name pattern (e.g., '*.rs')"

  - type: cli
    name: count_lines
    description: "Count lines in a file"
    command: wc
    args: ["-l"]
    params:
      file:
        type: string
        required: true
        description: "Path to file"

CLI Handler Anatomy

Every CLI handler has these components:

1. Command and Arguments

command: ls
args: ["-lah"]

Base configuration:

• command: The executable to run (ls, git, docker, etc.)
• args: Static arguments always passed to the command

2. Dynamic Parameters

params:
  path:
    type: string
    required: false
    default: "."

Parameter flow:

1. Client sends: { "path": "/home/user" }
2. pforge appends to args: ["ls", "-lah", "/home/user"]
3. Executes: ls -lah /home/user

3. Execution Options

tools:
  - type: cli
    name: long_running_task
    command: ./process.sh
    timeout_ms: 60000  # 60 seconds
    cwd: /tmp
    env:
      LOG_LEVEL: debug
    stream: true  # Enable output streaming

Options:

• timeout_ms: Max execution time (default: 30s)
• cwd: Working directory
• env: Environment variables
• stream: Stream output in real-time

Input and Output Structure

CLI handlers use a standard schema:

Input

{
  "args": ["additional", "arguments"],  // Optional
  "env": {                              // Optional
    "CUSTOM_VAR": "value"
  }
}

Output

{
  "stdout": "command output here",
  "stderr": "any errors here",
  "exit_code": 0
}

Practical Example: Git Integration

tools:
  - type: cli
    name: git_status
    description: "Get git repository status"
    command: git
    args: ["status", "--short"]
    cwd: "{{repo_path}}"
    params:
      repo_path:
        type: string
        required: true
        description: "Path to git repository"

  - type: cli
    name: git_log
    description: "Show git commit history"
    command: git
    args: ["log", "--oneline"]
    params:
      repo_path:
        type: string
        required: true
      max_count:
        type: integer
        required: false
        default: 10
        description: "Number of commits to show"

Usage:

// Request
{
  "tool": "git_log",
  "params": {
    "repo_path": "/home/user/project",
    "max_count": 5
  }
}

// Response
{
  "stdout": "abc123 feat: add new feature\ndef456 fix: resolve bug\n...",
  "stderr": "",
  "exit_code": 0
}

Error Handling

CLI handlers return errors when:

1. Command not found:

{
  "error": "Handler: Failed to execute command 'nonexistent': No such file or directory"
}

2. Timeout exceeded:

{
  "error": "Timeout: Command exceeded 30000ms timeout"
}

3. Non-zero exit code:

{
  "stdout": "",
  "stderr": "fatal: not a git repository",
  "exit_code": 128
}

Important: CLI handlers don’t automatically fail on non-zero exit codes. Check exit_code in your client.

Performance Characteristics

Compared to Native handlers:

• 5-10x slower dispatch
• Higher memory usage
• But zero implementation code!

Security Considerations

1. Command Injection Prevention

# SAFE - static command and args
command: ls
args: ["-lah"]

# UNSAFE - user input in command (pforge blocks this)
command: "{{user_command}}"  # NOT ALLOWED

pforge never allows dynamic commands - only static binaries with dynamic arguments.

2. Argument Validation

params:
  path:
    type: string
    required: true
    pattern: "^[a-zA-Z0-9_/.-]+$"  # Restrict characters

Best practice: Use JSON Schema validation to restrict input patterns.

3. Working Directory Restrictions

cwd: /safe/directory  # Static, safe path
# NOT: cwd: "{{user_path}}"  # Would be security risk

When to Use Each Handler Type

CLI Handler - Wrapping existing tools:

type: cli
command: ffmpeg
args: ["-i", "{{input}}", "{{output}}"]

Native Handler - Complex validation:

async fn handle(&self, input: Input) -> Result<Output> {
    validate_path(&input.path)?;
    let output = Command::new("ls")
        .arg(&input.path)
        .output()
        .await?;
    // Custom processing...
}

HTTP Handler - External APIs:

type: http
endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}"
method: GET

Pipeline Handler - Multi-step workflows:

type: pipeline
steps:
  - tool: list_files
    output_var: files
  - tool: count_lines
    input: { file: "{{files}}" }

Common CLI Handler Patterns

Pattern 1: Optional Arguments

params:
  verbose:
    type: boolean
    required: false
    default: false

# In YAML, conditionally include args based on params
# (Future feature - current workaround: use Native handler)

Pattern 2: Environment Configuration

env:
  PATH: "/usr/local/bin:/usr/bin"
  LANG: "en_US.UTF-8"
  CUSTOM_CONFIG: "{{config_path}}"

Pattern 3: Streaming Large Output

stream: true
timeout_ms: 300000  # 5 minutes

# For commands like:
# - docker build (long running)
# - tail -f (continuous output)
# - npm install (progress updates)

Testing CLI Handlers

CLI handlers are tested at the integration level:

#[tokio::test]
async fn test_cli_handler_ls() {
    let handler = CliHandler::new(
        "ls".to_string(),
        vec!["-lah".to_string()],
        None,
        HashMap::new(),
        None,
        false,
    );

    let input = CliInput {
        args: vec![".".to_string()],
        env: HashMap::new(),
    };

    let result = handler.execute(input).await.unwrap();
    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("total"));
}

Test coverage requirements:

• Happy path: command succeeds
• Error path: command fails
• Timeout: long-running command
• Environment: env vars passed correctly

Next Steps

In Chapter 4.1, we’ll dive deep into wrapping shell commands, including argument templating and output parsing strategies.

“The best code is no code. CLI handlers let Unix tools do the work.” - pforge philosophy

CLI Wrappers: Argument Templating and Output Parsing

CLI wrappers transform shell commands into type-safe MCP tools. This chapter covers advanced argument handling, parameter interpolation, and output parsing strategies.

Argument Flow Architecture

Understanding how arguments flow through CLI handlers:

YAML Config       User Input        Command Execution
-----------       ----------        -----------------
command: git      params: {         git
args: [           repo: "/foo",  -> -C /foo
  "-C",           format: "json"    log
  "{{repo}}",     }                 --format=json
  "log",
  "--format={{format}}"
]

Parameter Interpolation

Basic String Substitution

tools:
  - type: cli
    name: docker_run
    description: "Run a Docker container"
    command: docker
    args:
      - "run"
      - "--name"
      - "{{container_name}}"
      - "{{image}}"
    params:
      container_name:
        type: string
        required: true
      image:
        type: string
        required: true

Execution:

// Input
{ "container_name": "my-app", "image": "nginx:latest" }

// Command
docker run --name my-app nginx:latest

Multiple Parameter Types

tools:
  - type: cli
    name: ffmpeg_convert
    description: "Convert video files"
    command: ffmpeg
    args:
      - "-i"
      - "{{input_file}}"
      - "-b:v"
      - "{{bitrate}}k"
      - "-r"
      - "{{framerate}}"
      - "{{output_file}}"
    params:
      input_file:
        type: string
        required: true
      bitrate:
        type: integer
        required: false
        default: 1000
      framerate:
        type: integer
        required: false
        default: 30
      output_file:
        type: string
        required: true

Type conversion:

• string → passed as-is
• integer → converted to string
• float → converted to string
• boolean → “true” or “false”

Conditional Arguments

For conditional arguments, use a Native handler wrapper:

use pforge_runtime::{Handler, Result, Error};
use tokio::process::Command;

#[derive(Deserialize, JsonSchema)]
struct GrepInput {
    pattern: String,
    file: String,
    case_insensitive: bool,
    line_numbers: bool,
}

#[derive(Serialize, JsonSchema)]
struct GrepOutput {
    stdout: String,
    stderr: String,
    exit_code: i32,
}

pub struct GrepHandler;

#[async_trait::async_trait]
impl Handler for GrepHandler {
    type Input = GrepInput;
    type Output = GrepOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let mut cmd = Command::new("grep");

        if input.case_insensitive {
            cmd.arg("-i");
        }

        if input.line_numbers {
            cmd.arg("-n");
        }

        cmd.arg(&input.pattern);
        cmd.arg(&input.file);

        let output = cmd.output().await
            .map_err(|e| Error::Handler(format!("grep failed: {}", e)))?;

        Ok(GrepOutput {
            stdout: String::from_utf8_lossy(&output.stdout).to_string(),
            stderr: String::from_utf8_lossy(&output.stderr).to_string(),
            exit_code: output.status.code().unwrap_or(-1),
        })
    }
}

Why Native for conditional args?

• YAML is declarative, not conditional
• Rust provides full control over arg construction
• Type-safe boolean-to-flag conversion

Output Parsing Strategies

Strategy 1: Raw Output (Default)

tools:
  - type: cli
    name: list_files
    command: ls
    args: ["-lah"]

Output:

{
  "stdout": "total 24K\ndrwxr-xr-x 3 user user 4.0K...",
  "stderr": "",
  "exit_code": 0
}

Use when: Client will parse output (LLMs are good at this!)

Strategy 2: Structured Output with jq

tools:
  - type: cli
    name: docker_inspect
    description: "Get Docker container details as JSON"
    command: sh
    args:
      - "-c"
      - "docker inspect {{container}} | jq -c '.[0]'"
    params:
      container:
        type: string
        required: true

Output:

{
  "stdout": "{\"Id\":\"abc123\",\"Name\":\"my-app\",\"State\":{\"Status\":\"running\"}}",
  "stderr": "",
  "exit_code": 0
}

Client parsing:

const result = await client.callTool("docker_inspect", { container: "my-app" });
const parsed = JSON.parse(result.stdout);
console.log(parsed.State.Status); // "running"

Strategy 3: Native Handler Post-Processing

#[derive(Serialize, JsonSchema)]
struct ProcessedOutput {
    files: Vec<FileInfo>,
    total_size: u64,
}

#[derive(Serialize, JsonSchema)]
struct FileInfo {
    name: String,
    size: u64,
    modified: String,
}

pub struct LsHandler;

#[async_trait::async_trait]
impl Handler for LsHandler {
    type Input = LsInput;
    type Output = ProcessedOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let output = Command::new("ls")
            .arg("-lh")
            .arg(&input.directory)
            .output()
            .await?;

        let stdout = String::from_utf8_lossy(&output.stdout);
        let files = parse_ls_output(&stdout)?;
        let total_size = files.iter().map(|f| f.size).sum();

        Ok(ProcessedOutput {
            files,
            total_size,
        })
    }
}

fn parse_ls_output(output: &str) -> Result<Vec<FileInfo>> {
    // Parse ls -lh output into structured data
    output.lines()
        .skip(1) // Skip "total" line
        .map(|line| {
            let parts: Vec<&str> = line.split_whitespace().collect();
            Ok(FileInfo {
                name: parts.last().unwrap_or(&"").to_string(),
                size: parse_size(parts.get(4).unwrap_or(&"0"))?,
                modified: format!("{} {} {}",
                    parts.get(5).unwrap_or(&""),
                    parts.get(6).unwrap_or(&""),
                    parts.get(7).unwrap_or(&"")),
            })
        })
        .collect()
}

Use when:

• Output needs transformation
• Type safety required downstream
• Complex parsing logic

Strategy 4: Streaming Parser

For large outputs, parse incrementally:

use tokio::io::{AsyncBufReadExt, BufReader};

pub async fn stream_parse_logs(
    command: &str,
    args: &[String],
) -> Result<Vec<LogEntry>> {
    let mut child = Command::new(command)
        .args(args)
        .stdout(Stdio::piped())
        .spawn()?;

    let stdout = child.stdout.take()
        .ok_or_else(|| Error::Handler("Failed to capture stdout".into()))?;

    let reader = BufReader::new(stdout);
    let mut lines = reader.lines();
    let mut entries = Vec::new();

    while let Some(line) = lines.next_line().await? {
        if let Ok(entry) = parse_log_line(&line) {
            entries.push(entry);
        }
    }

    Ok(entries)
}

Working Directory Management

Static Working Directory

tools:
  - type: cli
    name: npm_install
    command: npm
    args: ["install"]
    cwd: /home/user/project

Security: Safe - directory is hardcoded.

Dynamic Working Directory (Requires Native)

#[derive(Deserialize, JsonSchema)]
struct NpmInput {
    project_path: String,
}

async fn handle(&self, input: NpmInput) -> Result<NpmOutput> {
    // Validate path is safe
    validate_project_path(&input.project_path)?;

    let output = Command::new("npm")
        .arg("install")
        .current_dir(&input.project_path)
        .output()
        .await?;

    // ... return output
}

fn validate_project_path(path: &str) -> Result<()> {
    // Prevent directory traversal
    if path.contains("..") {
        return Err(Error::Validation("Invalid path".into()));
    }

    // Ensure path exists and is a directory
    let path_obj = std::path::Path::new(path);
    if !path_obj.is_dir() {
        return Err(Error::Validation("Not a directory".into()));
    }

    Ok(())
}

Environment Variable Handling

Static Environment Variables

tools:
  - type: cli
    name: run_script
    command: ./script.sh
    env:
      NODE_ENV: production
      LOG_LEVEL: info
      API_URL: https://api.example.com

Dynamic Environment Variables

CLI handlers accept env vars at runtime:

tools:
  - type: cli
    name: aws_cli
    command: aws
    args: ["s3", "ls"]
    env:
      AWS_REGION: us-east-1
    params:
      bucket:
        type: string
        required: true

Runtime override:

{
  "tool": "aws_cli",
  "params": {
    "bucket": "my-bucket",
    "env": {
      "AWS_REGION": "eu-west-1"  // Overrides static value
    }
  }
}

Merge strategy:

1. Start with system environment
2. Apply static YAML env vars
3. Apply runtime input env vars (highest priority)

Exit Code Handling

CLI handlers don’t fail on non-zero exit codes - they return the code:

{
  "stdout": "",
  "stderr": "grep: pattern not found",
  "exit_code": 1
}

Client-side handling:

const result = await client.callTool("grep_files", { pattern: "TODO" });

if (result.exit_code !== 0) {
  if (result.exit_code === 1) {
    console.log("Pattern not found (expected)");
  } else {
    throw new Error(`grep failed: ${result.stderr}`);
  }
}

Native handler with validation:

async fn handle(&self, input: Input) -> Result<Output> {
    let output = Command::new("grep")
        .args(&input.args)
        .output()
        .await?;

    let exit_code = output.status.code().unwrap_or(-1);

    match exit_code {
        0 => Ok(Output {
            stdout: String::from_utf8_lossy(&output.stdout).to_string(),
        }),
        1 => Ok(Output {
            stdout: String::new(), // Pattern not found - not an error
        }),
        _ => Err(Error::Handler(format!(
            "grep failed with code {}: {}",
            exit_code,
            String::from_utf8_lossy(&output.stderr)
        ))),
    }
}

Complex Command Construction

Multi-command Pipelines

tools:
  - type: cli
    name: count_rust_files
    command: sh
    args:
      - "-c"
      - "find {{directory}} -name '*.rs' | wc -l"
    params:
      directory:
        type: string
        required: true

Security note: Use sh -c sparingly - validate input thoroughly!

Argument Quoting

pforge automatically quotes arguments with spaces:

command: git
args:
  - "commit"
  - "-m"
  - "{{message}}"

# Input: { "message": "fix: resolve bug #123" }
# Executes: git commit -m "fix: resolve bug #123"

Manual quoting not needed - pforge handles it.

Real-World Example: Docker Wrapper

forge:
  name: docker-wrapper
  version: 0.1.0
  transport: stdio

tools:
  - type: cli
    name: docker_ps
    description: "List running containers"
    command: docker
    args: ["ps", "--format", "json"]

  - type: cli
    name: docker_logs
    description: "Get container logs"
    command: docker
    args: ["logs", "--tail", "{{lines}}", "{{container}}"]
    timeout_ms: 10000
    params:
      container:
        type: string
        required: true
      lines:
        type: integer
        required: false
        default: 100

  - type: cli
    name: docker_exec
    description: "Execute command in container"
    command: docker
    args: ["exec", "-i", "{{container}}", "{{command}}"]
    params:
      container:
        type: string
        required: true
      command:
        type: string
        required: true

  - type: cli
    name: docker_stats
    description: "Stream container stats"
    command: docker
    args: ["stats", "--no-stream", "--format", "json"]
    stream: true

Testing CLI Wrappers

Unit Test: Argument Construction

#[test]
fn test_cli_handler_builds_args_correctly() {
    let handler = CliHandler::new(
        "git".to_string(),
        vec!["log".to_string(), "--oneline".to_string()],
        None,
        HashMap::new(),
        None,
        false,
    );

    assert_eq!(handler.command, "git");
    assert_eq!(handler.args, vec!["log", "--oneline"]);
}

Integration Test: Full Execution

#[tokio::test]
async fn test_cli_wrapper_git_log() {
    let handler = CliHandler::new(
        "git".to_string(),
        vec!["log".to_string(), "--oneline".to_string(), "-n".to_string()],
        Some("/path/to/repo".to_string()),
        HashMap::new(),
        Some(5000),
        false,
    );

    let input = CliInput {
        args: vec!["5".to_string()],
        env: HashMap::new(),
    };

    let result = handler.execute(input).await.unwrap();
    assert_eq!(result.exit_code, 0);
    assert!(!result.stdout.is_empty());
}

Property Test: Exit Code Range

use proptest::prelude::*;

proptest! {
    #[test]
    fn cli_handler_returns_valid_exit_code(
        cmd in "[a-z]{1,10}",
        args in prop::collection::vec("[a-z]{1,5}", 0..5)
    ) {
        tokio_test::block_on(async {
            let handler = CliHandler::new(
                cmd,
                args,
                None,
                HashMap::new(),
                Some(1000),
                false,
            );

            let result = handler.execute(CliInput::default()).await;

            if let Ok(output) = result {
                prop_assert!(output.exit_code >= -1);
                prop_assert!(output.exit_code <= 255);
            }
        });
    }
}

Performance Optimization

Reuse Command Instances

Don’t recreate CLI handlers per request:

// SLOW - recreates handler each time
pub async fn slow_wrapper(input: Input) -> Result<Output> {
    let handler = CliHandler::new(...);
    handler.execute(input).await
}

// FAST - reuse handler instance
pub struct FastWrapper {
    handler: CliHandler,
}

impl FastWrapper {
    pub fn new() -> Self {
        Self {
            handler: CliHandler::new(...),
        }
    }

    pub async fn execute(&self, input: Input) -> Result<Output> {
        self.handler.execute(input).await
    }
}

Minimize Argument Allocations

pforge optimizes argument building - but you can help:

# SLOW - many small allocations
args: ["--opt1", "{{val1}}", "--opt2", "{{val2}}", "--opt3", "{{val3}}"]

# FAST - fewer, larger args
args: ["--config", "{{config_file}}"]  # Config file contains all options

Common Pitfalls

Pitfall 1: Shell Metacharacter Injection

# UNSAFE
command: sh
args: ["-c", "ls {{user_input}}"]

# Input: { "user_input": "; rm -rf /" }
# Executes: ls ; rm -rf /   # DANGER!

Fix: Validate input or avoid shell:

# SAFE
command: ls
args: ["{{directory}}"]

# Validation in Native handler
fn validate_directory(dir: &str) -> Result<()> {
    if dir.contains(';') || dir.contains('|') {
        return Err(Error::Validation("Invalid characters".into()));
    }
    Ok(())
}

Pitfall 2: Timeout Too Short

# WRONG - npm install can take minutes
- type: cli
  command: npm
  args: ["install"]
  timeout_ms: 5000  # 5 seconds - too short!

Fix: Set realistic timeouts:

- type: cli
  command: npm
  args: ["install"]
  timeout_ms: 300000  # 5 minutes
  stream: true  # Show progress

Pitfall 3: Ignoring Exit Codes

// WRONG - assumes success
const result = await client.callTool("deploy_app", {});
console.log("Deployed:", result.stdout);

// RIGHT - check exit code
const result = await client.callTool("deploy_app", {});
if (result.exit_code !== 0) {
    throw new Error(`Deploy failed: ${result.stderr}`);
}
console.log("Deployed:", result.stdout);

Next Steps

Chapter 4.2 covers streaming output for long-running commands, including real-time log parsing and progress reporting.

“Wrap, don’t rewrite. CLI handlers preserve the Unix philosophy.” - pforge design principle

Streaming Command Output

Long-running commands like builds, deploys, and log tails need real-time output streaming. This chapter covers CLI handler streaming capabilities and patterns for progressive output delivery.

Why Streaming Matters

Without streaming:

- type: cli
  command: npm
  args: ["install"]
  timeout_ms: 300000  # Wait 5 minutes for all output

Result: Client sees nothing for 5 minutes, then gets 50KB of logs at once.

With streaming:

- type: cli
  command: npm
  args: ["install"]
  timeout_ms: 300000
  stream: true  # Enable real-time output

Result: Client sees progress updates as they happen.

Enabling Streaming

YAML Configuration

tools:
  - type: cli
    name: build_project
    description: "Build project with real-time logs"
    command: cargo
    args: ["build", "--release"]
    stream: true  # Key setting
    timeout_ms: 600000  # 10 minutes

How Streaming Works

1. Command spawns with stdout and stderr piped
2. Output buffers as it’s produced
3. Server sends chunks via MCP protocol
4. Client receives progressive updates
5. Complete output returned at end

Protocol flow:

Server                          Client
------                          ------
spawn("cargo build")
  ↓
[stdout] "Compiling..."    →    Display "Compiling..."
[stdout] "Building..."     →    Display "Building..."
[stderr] "warning: ..."    →    Display "warning: ..."
[exit] code: 0             →    Display "Complete"

Streaming Patterns

Pattern 1: Build Progress

tools:
  - type: cli
    name: docker_build
    description: "Build Docker image with progress"
    command: docker
    args:
      - "build"
      - "-t"
      - "{{image_name}}"
      - "{{context_dir}}"
    stream: true
    timeout_ms: 1800000  # 30 minutes
    params:
      image_name:
        type: string
        required: true
      context_dir:
        type: string
        required: false
        default: "."

Output stream:

Step 1/8 : FROM node:18
 ---> a1b2c3d4e5f6
Step 2/8 : WORKDIR /app
 ---> Running in abc123...
 ---> def456
...
Successfully built xyz789
Successfully tagged my-app:latest

Pattern 2: Log Tailing

tools:
  - type: cli
    name: tail_logs
    description: "Tail application logs"
    command: tail
    args: ["-f", "{{log_file}}"]
    stream: true
    timeout_ms: 3600000  # 1 hour
    params:
      log_file:
        type: string
        required: true

Continuous stream until timeout or client disconnects.

Pattern 3: Test Runner

tools:
  - type: cli
    name: run_tests
    description: "Run tests with real-time results"
    command: cargo
    args: ["test", "--", "--nocapture"]
    stream: true
    timeout_ms: 300000

Output stream:

running 45 tests
test auth::test_login ... ok
test auth::test_logout ... ok
test db::test_connection ... ok
...
test result: ok. 45 passed; 0 failed

Pattern 4: Interactive Command

tools:
  - type: cli
    name: shell_session
    description: "Execute shell command interactively"
    command: sh
    args: ["-c", "{{script}}"]
    stream: true
    params:
      script:
        type: string
        required: true

Native Handler Streaming

For more control, implement streaming in a Native handler:

use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::process::{Command, Stdio};

#[derive(Deserialize, JsonSchema)]
struct BuildInput {
    project_path: String,
}

#[derive(Serialize, JsonSchema)]
struct BuildOutput {
    success: bool,
    lines: Vec<String>,
    duration_ms: u64,
}

pub struct BuildHandler;

#[async_trait::async_trait]
impl Handler for BuildHandler {
    type Input = BuildInput;
    type Output = BuildOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        let start = std::time::Instant::now();

        let mut child = Command::new("cargo")
            .arg("build")
            .arg("--release")
            .current_dir(&input.project_path)
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .spawn()
            .map_err(|e| Error::Handler(format!("Spawn failed: {}", e)))?;

        let stdout = child.stdout.take()
            .ok_or_else(|| Error::Handler("No stdout".into()))?;

        let mut reader = BufReader::new(stdout).lines();
        let mut lines = Vec::new();

        while let Some(line) = reader.next_line().await
            .map_err(|e| Error::Handler(format!("Read failed: {}", e)))? {

            // Stream line to client (via logging/events)
            tracing::info!("BUILD: {}", line);
            lines.push(line);
        }

        let status = child.wait().await
            .map_err(|e| Error::Handler(format!("Wait failed: {}", e)))?;

        Ok(BuildOutput {
            success: status.success(),
            lines,
            duration_ms: start.elapsed().as_millis() as u64,
        })
    }
}

Buffering and Backpressure

Line Buffering (Default)

CLI handlers buffer by line:

// Internal implementation
let reader = BufReader::new(stdout);
let mut lines = reader.lines();

while let Some(line) = lines.next_line().await? {
    send_to_client(line).await?;
}

Characteristics:

• Low latency for line-oriented output
• Natural chunking at newlines
• Works well for logs, test output

Chunk Buffering

For binary or non-line output:

use tokio::io::AsyncReadExt;

let mut stdout = child.stdout.take().unwrap();
let mut buffer = [0u8; 8192];

loop {
    let n = stdout.read(&mut buffer).await?;
    if n == 0 { break; }

    send_chunk_to_client(&buffer[..n]).await?;
}

Characteristics:

• Fixed-size chunks (8KB)
• Better for binary data
• Higher throughput

Backpressure Handling

If client can’t keep up:

use tokio::sync::mpsc;

let (tx, mut rx) = mpsc::channel(100);  // Bounded channel

// Producer (command output)
tokio::spawn(async move {
    while let Some(line) = reader.next_line().await? {
        // Blocks if channel full (backpressure)
        tx.send(line).await?;
    }
});

// Consumer (client)
while let Some(line) = rx.recv().await {
    send_to_client(line).await?;
}

Benefits:

• Prevents memory bloat
• Smooth delivery rate
• Graceful degradation

Timeout Management

Global Timeout

- type: cli
  command: npm
  args: ["install"]
  timeout_ms: 300000  # Entire command must complete in 5 minutes
  stream: true

Behavior: Command killed if it runs longer than 5 minutes, even if streaming.

Per-Line Timeout

For commands that might stall:

use tokio::time::{timeout, Duration};

while let Ok(Some(line)) = timeout(
    Duration::from_secs(30),  // 30s per line
    reader.next_line()
).await {
    match line {
        Ok(line) => send_to_client(line).await?,
        Err(e) => return Err(Error::Handler(format!("Read error: {}", e))),
    }
}

Use case: Detect hung processes that produce no output.

Progress Parsing

JSON Progress (Docker, npm, etc.)

#[derive(Deserialize)]
struct ProgressLine {
    status: String,
    id: Option<String>,
    progress: Option<String>,
}

while let Some(line) = reader.next_line().await? {
    if let Ok(progress) = serde_json::from_str::<ProgressLine>(&line) {
        // Structured progress update
        send_progress(Progress {
            status: progress.status,
            current: parse_progress(&progress.progress),
        }).await?;
    } else {
        // Plain text fallback
        send_text(line).await?;
    }
}

Percentage Progress (builds, downloads)

fn parse_progress(line: &str) -> Option<f64> {
    // "[===>      ] 45%"
    if let Some(start) = line.find('[') {
        if let Some(end) = line.find('%') {
            let percent_str = &line[start+1..end]
                .trim()
                .split_whitespace()
                .last()?;
            return percent_str.parse().ok();
        }
    }
    None
}

Custom Progress Format

// Parse: "Compiling foo v1.0.0 (3/45)"
fn parse_cargo_progress(line: &str) -> Option<(u32, u32)> {
    if line.contains("Compiling") {
        if let Some(paren) = line.find('(') {
            let rest = &line[paren+1..];
            let parts: Vec<&str> = rest
                .trim_end_matches(')')
                .split('/')
                .collect();

            if parts.len() == 2 {
                let current = parts[0].parse().ok()?;
                let total = parts[1].parse().ok()?;
                return Some((current, total));
            }
        }
    }
    None
}

Error Stream Handling

Separate stdout/stderr

let mut stdout_reader = BufReader::new(
    child.stdout.take().unwrap()
).lines();

let mut stderr_reader = BufReader::new(
    child.stderr.take().unwrap()
).lines();

let stdout_task = tokio::spawn(async move {
    while let Some(line) = stdout_reader.next_line().await? {
        send_stdout(line).await?;
    }
    Ok::<_, Error>(())
});

let stderr_task = tokio::spawn(async move {
    while let Some(line) = stderr_reader.next_line().await? {
        send_stderr(line).await?;
    }
    Ok::<_, Error>(())
});

// Wait for both
tokio::try_join!(stdout_task, stderr_task)?;

Merged Stream

// Redirect stderr to stdout
let child = Command::new("cargo")
    .arg("build")
    .stdout(Stdio::piped())
    .stderr(Stdio::piped())  // Can also use Stdio::inherit()
    .spawn()?;

// Or merge in shell
command: sh
args: ["-c", "npm install 2>&1"]  # stderr → stdout

Real-World Example: CI/CD Pipeline

forge:
  name: ci-pipeline
  version: 0.1.0
  transport: stdio

tools:
  - type: cli
    name: run_tests
    description: "Run test suite with coverage"
    command: cargo
    args: ["tarpaulin", "--out", "Stdout"]
    stream: true
    timeout_ms: 600000

  - type: cli
    name: build_release
    description: "Build optimized release binary"
    command: cargo
    args: ["build", "--release"]
    stream: true
    timeout_ms: 1800000

  - type: cli
    name: deploy
    description: "Deploy to production"
    command: ./scripts/deploy.sh
    args: ["{{environment}}"]
    stream: true
    timeout_ms: 900000
    env:
      CI: "true"
    params:
      environment:
        type: string
        required: true
        enum: ["staging", "production"]

Client usage:

const client = new MCPClient("ci-pipeline");

// Real-time test output
await client.callTool("run_tests", {}, {
  onProgress: (line) => {
    console.log(`TEST: ${line}`);
  }
});

// Real-time build output
await client.callTool("build_release", {}, {
  onProgress: (line) => {
    if (line.includes("Compiling")) {
      updateProgressBar(line);
    }
  }
});

// Real-time deploy output
await client.callTool("deploy", {
  environment: "production"
}, {
  onProgress: (line) => {
    if (line.includes("ERROR")) {
      alert(`Deploy issue: ${line}`);
    }
  }
});

Performance Considerations

Memory Usage

Problem: Storing all output in memory:

// BAD - unbounded growth
let mut all_output = String::new();
while let Some(line) = reader.next_line().await? {
    all_output.push_str(&line);
    all_output.push('\n');
}

Solution: Stream without buffering:

// GOOD - constant memory
while let Some(line) = reader.next_line().await? {
    send_to_client(line).await?;
    // `line` dropped after send
}

Throughput

Line-by-line (high latency, low throughput):

// ~1000 lines/sec
while let Some(line) = reader.next_line().await? {
    send(line).await?;
}

Batch sending (low latency, high throughput):

// ~10000 lines/sec
let mut batch = Vec::new();
while let Some(line) = reader.next_line().await? {
    batch.push(line);
    if batch.len() >= 100 {
        send_batch(&batch).await?;
        batch.clear();
    }
}
if !batch.is_empty() {
    send_batch(&batch).await?;
}

Testing Streaming Handlers

Mock Command Output

#[tokio::test]
async fn test_streaming_handler() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec![
            "-c".to_string(),
            "for i in 1 2 3; do echo line$i; sleep 0.1; done".to_string(),
        ],
        None,
        HashMap::new(),
        Some(5000),
        true,  // stream: true
    );

    let input = CliInput::default();
    let result = handler.execute(input).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("line1"));
    assert!(result.stdout.contains("line2"));
    assert!(result.stdout.contains("line3"));
}

Verify Streaming Behavior

#[tokio::test]
async fn test_stream_delivers_progressively() {
    use tokio::time::{sleep, Duration};

    let (tx, mut rx) = mpsc::channel(10);

    tokio::spawn(async move {
        let handler = CliHandler::new(...);
        // Handler sends to tx as it streams
    });

    // Verify we get updates before completion
    let first = rx.recv().await.unwrap();
    sleep(Duration::from_millis(100)).await;
    let second = rx.recv().await.unwrap();

    assert_ne!(first, second);  // Different lines
}

Next Steps

Chapter 4.3 covers comprehensive integration testing strategies for CLI handlers, including mocking commands and testing error conditions.

“Stream, don’t batch. Users want feedback, not wait times.” - pforge streaming philosophy

Integration Testing CLI Handlers

CLI handlers bridge pforge to the system shell. This chapter covers comprehensive integration testing strategies to ensure reliability across different environments and edge cases.

Testing Philosophy for CLI Handlers

Unit tests verify handler construction:

#[test]
fn test_cli_handler_creation() {
    let handler = CliHandler::new(...);
    assert_eq!(handler.command, "ls");
}

Integration tests verify actual command execution:

#[tokio::test]
async fn test_cli_handler_executes() {
    let result = handler.execute(input).await.unwrap();
    assert_eq!(result.exit_code, 0);
}

This chapter focuses on integration tests.

Basic Integration Test Structure

use pforge_runtime::handlers::cli::{CliHandler, CliInput};
use std::collections::HashMap;

#[tokio::test]
async fn test_ls_command() {
    // Arrange
    let handler = CliHandler::new(
        "ls".to_string(),
        vec!["-lah".to_string()],
        None,  // cwd
        HashMap::new(),  // env
        Some(5000),  // timeout_ms
        false,  // stream
    );

    let input = CliInput {
        args: vec![],
        env: HashMap::new(),
    };

    // Act
    let result = handler.execute(input).await.unwrap();

    // Assert
    assert_eq!(result.exit_code, 0);
    assert!(!result.stdout.is_empty());
    assert_eq!(result.stderr, "");
}

Testing Success Cases

Command Execution Success

#[tokio::test]
async fn test_echo_command() {
    let handler = CliHandler::new(
        "echo".to_string(),
        vec!["hello world".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.trim() == "hello world");
}

Argument Passing

#[tokio::test]
async fn test_grep_with_args() {
    let handler = CliHandler::new(
        "grep".to_string(),
        vec!["pattern".to_string()],
        None,
        HashMap::new(),
        Some(2000),
        false,
    );

    let input = CliInput {
        args: vec!["testfile.txt".to_string()],
        env: HashMap::new(),
    };

    let result = handler.execute(input).await.unwrap();

    // grep returns 0 if pattern found, 1 if not, >1 on error
    assert!(result.exit_code <= 1);
}

Working Directory

#[tokio::test]
async fn test_pwd_in_specific_dir() {
    let test_dir = std::env::temp_dir();

    let handler = CliHandler::new(
        "pwd".to_string(),
        vec![],
        Some(test_dir.to_str().unwrap().to_string()),
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains(test_dir.to_str().unwrap()));
}

Environment Variables

#[tokio::test]
async fn test_env_variables() {
    let mut env = HashMap::new();
    env.insert("TEST_VAR".to_string(), "test_value".to_string());

    let handler = CliHandler::new(
        "sh".to_string(),
        vec!["-c".to_string(), "echo $TEST_VAR".to_string()],
        None,
        env,
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("test_value"));
}

Testing Failure Cases

Command Not Found

#[tokio::test]
async fn test_nonexistent_command() {
    let handler = CliHandler::new(
        "nonexistent_command_xyz".to_string(),
        vec![],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await;

    assert!(result.is_err());
    assert!(matches!(result.unwrap_err(), Error::Handler(_)));
}

Non-Zero Exit Code

#[tokio::test]
async fn test_command_fails() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec!["-c".to_string(), "exit 42".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 42);
    assert!(result.stdout.is_empty());
}

Timeout Exceeded

#[tokio::test]
async fn test_command_timeout() {
    let handler = CliHandler::new(
        "sleep".to_string(),
        vec!["10".to_string()],  // Sleep 10 seconds
        None,
        HashMap::new(),
        Some(100),  // Timeout after 100ms
        false,
    );

    let result = handler.execute(CliInput::default()).await;

    assert!(result.is_err());
    assert!(matches!(result.unwrap_err(), Error::Timeout));
}

Invalid Arguments

#[tokio::test]
async fn test_invalid_arguments() {
    let handler = CliHandler::new(
        "ls".to_string(),
        vec!["--invalid-flag-xyz".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_ne!(result.exit_code, 0);
    assert!(!result.stderr.is_empty());
}

Testing Output Handling

Stdout Capture

#[tokio::test]
async fn test_stdout_captured() {
    let handler = CliHandler::new(
        "echo".to_string(),
        vec!["line1\nline2\nline3".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert!(result.stdout.contains("line1"));
    assert!(result.stdout.contains("line2"));
    assert!(result.stdout.contains("line3"));
}

Stderr Capture

#[tokio::test]
async fn test_stderr_captured() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec!["-c".to_string(), "echo error >&2".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stderr.contains("error"));
    assert_eq!(result.stdout, "");
}

Large Output

#[tokio::test]
async fn test_large_output() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec![
            "-c".to_string(),
            "for i in $(seq 1 10000); do echo line$i; done".to_string(),
        ],
        None,
        HashMap::new(),
        Some(10000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    let line_count = result.stdout.lines().count();
    assert_eq!(line_count, 10000);
}

Testing Streaming Handlers

Stream Output Capture

#[tokio::test]
async fn test_streaming_output() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec![
            "-c".to_string(),
            "for i in 1 2 3; do echo line$i; sleep 0.1; done".to_string(),
        ],
        None,
        HashMap::new(),
        Some(5000),
        true,  // stream: true
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("line1"));
    assert!(result.stdout.contains("line2"));
    assert!(result.stdout.contains("line3"));
}

Stream Timeout

#[tokio::test]
async fn test_stream_timeout() {
    let handler = CliHandler::new(
        "sh".to_string(),
        vec![
            "-c".to_string(),
            "echo start; sleep 10; echo end".to_string(),
        ],
        None,
        HashMap::new(),
        Some(500),  // Timeout before "end" prints
        true,
    );

    let result = handler.execute(CliInput::default()).await;

    assert!(result.is_err());
}

Testing Edge Cases

Empty Output

#[tokio::test]
async fn test_empty_output() {
    let handler = CliHandler::new(
        "true".to_string(),  // Command that succeeds but prints nothing
        vec![],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert_eq!(result.stdout, "");
    assert_eq!(result.stderr, "");
}

Special Characters in Arguments

#[tokio::test]
async fn test_special_characters() {
    let handler = CliHandler::new(
        "echo".to_string(),
        vec!["$TEST".to_string(), "!@#$%".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    // Note: shell won't expand $TEST since we use Command::new, not sh -c
    assert!(result.stdout.contains("$TEST"));
}

Unicode Output

#[tokio::test]
async fn test_unicode_output() {
    let handler = CliHandler::new(
        "echo".to_string(),
        vec!["Hello 世界 🚀".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("世界"));
    assert!(result.stdout.contains("🚀"));
}

Platform-Specific Tests

Unix-Only Tests

#[cfg(unix)]
#[tokio::test]
async fn test_unix_specific_command() {
    let handler = CliHandler::new(
        "uname".to_string(),
        vec!["-s".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("Linux") || result.stdout.contains("Darwin"));
}

Windows-Only Tests

#[cfg(windows)]
#[tokio::test]
async fn test_windows_specific_command() {
    let handler = CliHandler::new(
        "cmd".to_string(),
        vec!["/C".to_string(), "echo test".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("test"));
}

Property-Based Testing

Random Command Arguments

use proptest::prelude::*;

proptest! {
    #[test]
    fn cli_handler_never_panics(
        args in prop::collection::vec("[a-zA-Z0-9_-]{1,20}", 0..10)
    ) {
        tokio_test::block_on(async {
            let handler = CliHandler::new(
                "echo".to_string(),
                args,
                None,
                HashMap::new(),
                Some(1000),
                false,
            );

            // Should not panic, even with random args
            let _ = handler.execute(CliInput::default()).await;
        });
    }
}

Exit Code Range

proptest! {
    #[test]
    fn exit_codes_are_valid(
        code in 0..=255u8
    ) {
        tokio_test::block_on(async {
            let handler = CliHandler::new(
                "sh".to_string(),
                vec!["-c".to_string(), format!("exit {}", code)],
                None,
                HashMap::new(),
                Some(1000),
                false,
            );

            let result = handler.execute(CliInput::default()).await.unwrap();
            prop_assert_eq!(result.exit_code, code as i32);
            Ok(())
        })?;
    }
}

Mock Command Patterns

Test Fixture Script

Create tests/fixtures/test_command.sh:

#!/bin/bash
# Test fixture for CLI handler integration tests

case "$1" in
  success)
    echo "Success output"
    exit 0
    ;;
  failure)
    echo "Error output" >&2
    exit 1
    ;;
  slow)
    sleep 5
    echo "Done"
    exit 0
    ;;
  *)
    echo "Unknown command" >&2
    exit 2
    ;;
esac

Usage in tests:

#[tokio::test]
async fn test_with_fixture() {
    let handler = CliHandler::new(
        "./tests/fixtures/test_command.sh".to_string(),
        vec!["success".to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );

    let result = handler.execute(CliInput::default()).await.unwrap();

    assert_eq!(result.exit_code, 0);
    assert!(result.stdout.contains("Success"));
}

Test Coverage Goals

Coverage Checklist

• Command execution succeeds
• Command execution fails
• Timeout handling
• Stdout capture
• Stderr capture
• Exit code handling
• Argument passing
• Environment variables
• Working directory
• Streaming output
• Large output
• Empty output
• Special characters
• Unicode handling
• Platform-specific behavior

Measuring Coverage

# Run integration tests with coverage
cargo tarpaulin \
  --test integration \
  --out Html \
  --output-dir target/coverage

# View report
open target/coverage/index.html

Target: ≥80% line coverage for CLI handler code.

Continuous Integration

GitHub Actions Example

name: CLI Handler Integration Tests

on: [push, pull_request]

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v3

      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable

      - name: Run integration tests
        run: cargo test --test cli_integration

      - name: Run with verbose output
        run: cargo test --test cli_integration -- --nocapture

Best Practices

1. Isolate Test Dependencies

// BAD - depends on system state
#[tokio::test]
async fn test_list_home_dir() {
    let handler = CliHandler::new(
        "ls".to_string(),
        vec![std::env::var("HOME").unwrap()],  // System-dependent
        None,
        HashMap::new(),
        Some(1000),
        false,
    );
    // ...
}

// GOOD - create isolated test environment
#[tokio::test]
async fn test_list_test_dir() {
    let temp_dir = tempfile::tempdir().unwrap();

    let handler = CliHandler::new(
        "ls".to_string(),
        vec![temp_dir.path().to_str().unwrap().to_string()],
        None,
        HashMap::new(),
        Some(1000),
        false,
    );
    // ...
}

2. Test Timeouts Appropriately

// Ensure timeout is longer than expected execution
let handler = CliHandler::new(
    "sleep".to_string(),
    vec!["2".to_string()],
    None,
    HashMap::new(),
    Some(3000),  // 3s > 2s command duration
    false,
);

3. Assert on Both Success and Error Paths

#[tokio::test]
async fn test_comprehensive() {
    let result = handler.execute(input).await.unwrap();

    // Assert success conditions
    assert_eq!(result.exit_code, 0);
    assert!(!result.stdout.is_empty());

    // Assert error conditions didn't occur
    assert_eq!(result.stderr, "");
}

Next Steps

Chapter 5.0 introduces HTTP handlers for wrapping REST APIs, starting with a GitHub API integration example.

“Test the integration, not just the units. CLI handlers live at the system boundary.” - pforge testing principle

GitHub API: HTTP Handler Overview

HTTP handlers wrap REST APIs as MCP tools with zero boilerplate. This chapter demonstrates building a GitHub API integration using HTTP handlers.

Why HTTP Handlers?

Use HTTP handlers when:

• Wrapping existing REST APIs
• No complex logic needed (just proxying)
• URL parameters can be templated
• Response doesn’t need transformation

Don’t use HTTP handlers when:

• Complex authentication flow (OAuth, JWT refresh)
• Response needs parsing/transformation
• API requires request signing
• Stateful session management needed

GitHub API Server Example

forge:
  name: github-api
  version: 0.1.0
  transport: stdio

tools:
  - type: http
    name: get_user
    description: "Get GitHub user information"
    endpoint: "https://api.github.com/users/{{username}}"
    method: GET
    headers:
      User-Agent: "pforge-github-client"
      Accept: "application/vnd.github.v3+json"
    params:
      username:
        type: string
        required: true
        description: "GitHub username"

  - type: http
    name: get_repos
    description: "List user repositories"
    endpoint: "https://api.github.com/users/{{username}}/repos"
    method: GET
    headers:
      User-Agent: "pforge-github-client"
      Accept: "application/vnd.github.v3+json"
    params:
      username:
        type: string
        required: true

  - type: http
    name: search_repos
    description: "Search GitHub repositories"
    endpoint: "https://api.github.com/search/repositories"
    method: GET
    headers:
      User-Agent: "pforge-github-client"
      Accept: "application/vnd.github.v3+json"
    query:
      q: "{{query}}"
      sort: "{{sort}}"
      order: "{{order}}"
    params:
      query:
        type: string
        required: true
      sort:
        type: string
        required: false
        default: "stars"
      order:
        type: string
        required: false
        default: "desc"

HTTP Handler Anatomy

1. Endpoint and Method

endpoint: "https://api.github.com/users/{{username}}"
method: GET

Supported methods: GET, POST, PUT, DELETE, PATCH

2. URL Templating

endpoint: "https://api.example.com/{{resource}}/{{id}}"

# Input: { "resource": "users", "id": "123" }
# URL: https://api.example.com/users/123

3. Headers

headers:
  User-Agent: "pforge-client"
  Accept: "application/json"
  Content-Type: "application/json"
  X-API-Key: "{{api_key}}"  # Can be templated

4. Query Parameters

query:
  page: "{{page}}"
  limit: "{{limit}}"

# Input: { "page": "2", "limit": "50" }
# URL: ?page=2&limit=50

5. Request Body (POST/PUT)

tools:
  - type: http
    name: create_issue
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: POST
    headers:
      Authorization: "token {{token}}"
    body:
      title: "{{title}}"
      body: "{{description}}"
      labels: "{{labels}}"
    params:
      owner:
        type: string
        required: true
      repo:
        type: string
        required: true
      token:
        type: string
        required: true
      title:
        type: string
        required: true
      description:
        type: string
        required: false
      labels:
        type: array
        items: { type: string }
        required: false

Input/Output Structure

HTTP Input

{
  "body": {  // Optional - for POST/PUT/PATCH
    "key": "value"
  },
  "query": {  // Optional - query parameters
    "param": "value"
  }
}

HTTP Output

{
  "status": 200,
  "body": { /* JSON response */ },
  "headers": {
    "content-type": "application/json",
    "x-ratelimit-remaining": "59"
  }
}

Real-World Example: Complete GitHub Integration

forge:
  name: github-mcp
  version: 0.1.0
  transport: stdio

tools:
  # User operations
  - type: http
    name: get_user
    description: "Get user profile"
    endpoint: "https://api.github.com/users/{{username}}"
    method: GET
    headers:
      User-Agent: "pforge-github"

  # Repository operations
  - type: http
    name: get_repo
    description: "Get repository details"
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}"
    method: GET
    headers:
      User-Agent: "pforge-github"

  - type: http
    name: list_commits
    description: "List repository commits"
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/commits"
    method: GET
    query:
      per_page: "{{per_page}}"
      page: "{{page}}"
    params:
      owner: { type: string, required: true }
      repo: { type: string, required: true }
      per_page: { type: integer, required: false, default: 30 }
      page: { type: integer, required: false, default: 1 }

  # Issue operations
  - type: http
    name: list_issues
    description: "List repository issues"
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: GET
    query:
      state: "{{state}}"
      labels: "{{labels}}"
    params:
      owner: { type: string, required: true }
      repo: { type: string, required: true }
      state: { type: string, required: false, default: "open" }
      labels: { type: string, required: false }

  - type: http
    name: create_issue
    description: "Create a new issue"
    endpoint: "https://api.github.com/repos/{{owner}}/{{repo}}/issues"
    method: POST
    headers:
      Authorization: "token {{token}}"
    body:
      title: "{{title}}"
      body: "{{body}}"
    params:
      owner: { type: string, required: true }
      repo: { type: string, required: true }
      token: { type: string, required: true }
      title: { type: string, required: true }
      body: { type: string, required: false }

Error Handling

HTTP handlers return errors on:

1. Network failures: Connection refused, timeout
2. HTTP 4xx/5xx: Client/server errors
3. Invalid JSON: Response parsing failed

Error format:

{
  "error": "Http: Request failed: 404 Not Found"
}

Performance Characteristics

When to Use Native vs HTTP Handler

HTTP Handler - Simple API proxying:

type: http
endpoint: "https://api.example.com/{{resource}}"
method: GET

Native Handler - Complex logic:

async fn handle(&self, input: Input) -> Result<Output> {
    // Validate input
    // Make HTTP request
    // Transform response
    // Handle pagination
    Ok(output)
}

Next Steps

Chapter 5.1 covers HTTP configuration in depth, including advanced header management, authentication patterns, and retry strategies.

“APIs are tools. HTTP handlers make them accessible.” - pforge HTTP philosophy

HTTP Configuration

HTTP handlers require careful configuration for reliability, security, and performance. This chapter covers advanced HTTP configuration patterns.

Complete Configuration Example

tools:
  - type: http
    name: api_call
    description: "Configured API call with all options"
    endpoint: "https://api.example.com/{{resource}}"
    method: POST
    headers:
      User-Agent: "pforge/1.0"
      Authorization: "Bearer {{token}}"
      Content-Type: "application/json"
      X-Request-ID: "{{request_id}}"
    query:
      version: "v2"
      format: "json"
    body:
      data: "{{payload}}"
    timeout_ms: 30000
    retry:
      max_attempts: 3
      backoff_ms: 1000
    params:
      resource: { type: string, required: true }
      token: { type: string, required: true }
      request_id: { type: string, required: false }
      payload: { type: object, required: true }

Header Management

Static Headers

headers:
  User-Agent: "pforge-client/1.0"
  Accept: "application/json"
  Accept-Language: "en-US"

Dynamic Headers (Templated)

headers:
  Authorization: "Bearer {{access_token}}"
  X-Tenant-ID: "{{tenant_id}}"
  X-Correlation-ID: "{{correlation_id}}"

Conditional Headers

For conditional headers, use a Native handler:

async fn handle(&self, input: Input) -> Result<Output> {
    let mut headers = HashMap::new();
    headers.insert("User-Agent", "pforge");

    if let Some(token) = input.auth_token {
        headers.insert("Authorization", format!("Bearer {}", token));
    }

    if input.use_compression {
        headers.insert("Accept-Encoding", "gzip, deflate");
    }

    let client = reqwest::Client::new();
    let response = client
        .get(&input.url)
        .headers(headers)
        .send()
        .await?;

    // ...
}

Query Parameter Patterns

Simple Query Params

query:
  page: "{{page}}"
  limit: "{{limit}}"
  sort: "name"  # Static value

Array Query Params

# Input: { "tags": ["rust", "mcp", "api"] }
# URL: ?tags=rust&tags=mcp&tags=api

query:
  tags: "{{tags}}"  # Automatically handles arrays

Complex Filtering

query:
  filter: "created_at>{{start_date}},status={{status}}"
  fields: "id,name,created_at"

Request Body Configuration

JSON Body

tools:
  - type: http
    name: create_resource
    method: POST
    body:
      name: "{{name}}"
      description: "{{description}}"
      metadata:
        source: "pforge"
        timestamp: "{{timestamp}}"

Nested Objects

body:
  user:
    name: "{{user_name}}"
    email: "{{user_email}}"
    preferences:
      theme: "{{theme}}"
      notifications: "{{notifications}}"

Array Payloads

body:
  items: "{{items}}"  # Array of objects

# Input:
# {
#   "items": [
#     { "id": 1, "name": "foo" },
#     { "id": 2, "name": "bar" }
#   ]
# }

Timeout Configuration

Global Timeout

timeout_ms: 30000  # 30 seconds for entire request

Per-Endpoint Timeouts

tools:
  - type: http
    name: quick_lookup
    endpoint: "https://api.example.com/lookup"
    timeout_ms: 1000  # 1 second

  - type: http
    name: heavy_computation
    endpoint: "https://api.example.com/compute"
    timeout_ms: 120000  # 2 minutes

Native Handler Timeout Control

use tokio::time::{timeout, Duration};

let response = timeout(
    Duration::from_millis(input.timeout_ms),
    client.get(&url).send()
).await
.map_err(|_| Error::Timeout)?;

Retry Configuration

Basic Retry

retry:
  max_attempts: 3
  backoff_ms: 1000  # Wait 1s between retries

Exponential Backoff (Native Handler)

use backoff::{ExponentialBackoff, Error as BackoffError};

let backoff = ExponentialBackoff {
    initial_interval: Duration::from_millis(100),
    max_interval: Duration::from_secs(10),
    max_elapsed_time: Some(Duration::from_secs(60)),
    ..Default::default()
};

let result = backoff::retry(backoff, || async {
    match client.get(&url).send().await {
        Ok(response) if response.status().is_success() => Ok(response),
        Ok(response) => Err(BackoffError::transient(Error::Http(...))),
        Err(e) => Err(BackoffError::permanent(Error::from(e))),
    }
}).await?;

Response Handling

Status Code Mapping

HTTP handlers return all responses (2xx, 4xx, 5xx):

# Handler returns:
{
  "status": 404,
  "body": { "error": "Not found" },
  "headers": {...}
}

Client decides:

const result = await client.callTool("get_user", { id: "123" });

if (result.status === 404) {
  console.log("User not found");
} else if (result.status >= 400) {
  throw new Error(`API error: ${result.status}`);
}

Header Extraction

const result = await client.callTool("api_call", params);

// Rate limiting
const rateLimit = parseInt(result.headers["x-ratelimit-remaining"]);
if (rateLimit < 10) {
  console.warn("Approaching rate limit");
}

// Pagination
const nextPage = result.headers["link"]?.match(/page=(\d+)/)?.[1];

SSL/TLS Configuration

Accept Self-Signed Certificates (Development)

Use Native handler with custom client:

let client = reqwest::Client::builder()
    .danger_accept_invalid_certs(true)  // DEVELOPMENT ONLY
    .build()?;

Custom CA Certificates

use reqwest::Certificate;

let cert = std::fs::read("ca-cert.pem")?;
let cert = Certificate::from_pem(&cert)?;

let client = reqwest::Client::builder()
    .add_root_certificate(cert)
    .build()?;

Connection Pooling

HTTP handlers automatically use connection pooling via reqwest.

Pool Configuration (Native Handler)

let client = reqwest::Client::builder()
    .pool_max_idle_per_host(10)
    .pool_idle_timeout(Duration::from_secs(30))
    .build()?;

Common Configuration Patterns

Pattern 1: Paginated API

tools:
  - type: http
    name: list_items
    endpoint: "https://api.example.com/items"
    method: GET
    query:
      page: "{{page}}"
      per_page: "{{per_page}}"
    params:
      page: { type: integer, required: false, default: 1 }
      per_page: { type: integer, required: false, default: 100 }

Pattern 2: Webhook Receiver

tools:
  - type: http
    name: trigger_webhook
    endpoint: "https://webhook.example.com/events"
    method: POST
    headers:
      X-Webhook-Secret: "{{secret}}"
    body:
      event: "{{event_type}}"
      payload: "{{data}}"

Pattern 3: File Upload (Use Native Handler)

use reqwest::multipart;

async fn handle(&self, input: UploadInput) -> Result<UploadOutput> {
    let file_content = std::fs::read(&input.file_path)?;

    let form = multipart::Form::new()
        .text("description", input.description)
        .part("file", multipart::Part::bytes(file_content)
            .file_name(input.file_name));

    let response = self.client
        .post(&input.upload_url)
        .multipart(form)
        .send()
        .await?;

    // ...
}

Testing HTTP Configuration

Mock Server

use wiremock::{Mock, MockServer, ResponseTemplate};

#[tokio::test]
async fn test_http_handler() {
    let mock_server = MockServer::start().await;

    Mock::given(method("GET"))
        .and(path("/users/123"))
        .respond_with(ResponseTemplate::new(200)
            .set_body_json(json!({
                "id": "123",
                "name": "Alice"
            })))
        .mount(&mock_server)
        .await;

    let handler = HttpHandler::new(
        format!("{}/users/{{id}}", mock_server.uri()),
        HttpMethod::Get,
        HashMap::new(),
        None,
    );

    let result = handler.execute(HttpInput {
        body: None,
        query: [("id", "123")].into(),
    }).await.unwrap();

    assert_eq!(result.status, 200);
    assert_eq!(result.body["name"], "Alice");
}

Next Steps

Chapter 5.2 covers authentication patterns including Bearer tokens, API keys, Basic Auth, and OAuth integration.

“Configuration is declarative. Complexity is in the runtime.” - pforge HTTP design

API Authentication

HTTP handlers support multiple authentication strategies. This chapter covers implementing Bearer tokens, API keys, Basic Auth, and OAuth patterns.

Bearer Token Authentication

Static Token (Configuration)

tools:
  - type: http
    name: auth_api_call
    endpoint: "https://api.example.com/data"
    method: GET
    headers:
      Authorization: "Bearer {{access_token}}"
    params:
      access_token:
        type: string
        required: true
        description: "API access token"

Usage:

{
  "tool": "auth_api_call",
  "params": {
    "access_token": "eyJhbGc..."
  }
}

Dynamic Token (Environment Variable)

headers:
  Authorization: "Bearer ${API_TOKEN}"  # From environment

API Key Authentication

Header-Based API Key

tools:
  - type: http
    name: api_key_call
    endpoint: "https://api.example.com/resource"
    method: GET
    headers:
      X-API-Key: "{{api_key}}"
    params:
      api_key: { type: string, required: true }

Query Parameter API Key

tools:
  - type: http
    name: query_key_call
    endpoint: "https://api.example.com/resource"
    method: GET
    query:
      api_key: "{{api_key}}"
    params:
      api_key: { type: string, required: true }

Basic Authentication

YAML Configuration

tools:
  - type: http
    name: basic_auth_call
    endpoint: "https://api.example.com/secure"
    method: GET
    auth:
      type: basic
      username: "{{username}}"
      password: "{{password}}"
    params:
      username: { type: string, required: true }
      password: { type: string, required: true }

Native Handler Implementation

use reqwest::Client;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Deserialize, JsonSchema)]
struct BasicAuthInput {
    username: String,
    password: String,
    resource: String,
}

#[derive(Serialize, JsonSchema)]
struct ApiResponse {
    status: u16,
    body: serde_json::Value,
}

async fn handle(&self, input: BasicAuthInput) -> Result<ApiResponse> {
    let client = Client::new();

    let response = client
        .get(&format!("https://api.example.com/{}", input.resource))
        .basic_auth(&input.username, Some(&input.password))
        .send()
        .await?;

    Ok(ApiResponse {
        status: response.status().as_u16(),
        body: response.json().await?,
    })
}

OAuth 2.0 Patterns

Client Credentials Flow

use serde::{Deserialize, Serialize};
use reqwest::Client;

#[derive(Deserialize)]
struct TokenResponse {
    access_token: String,
    token_type: String,
    expires_in: u64,
}

#[derive(Deserialize, JsonSchema)]
struct OAuthInput {
    client_id: String,
    client_secret: String,
    resource: String,
}

async fn handle(&self, input: OAuthInput) -> Result<ApiResponse> {
    // Step 1: Get access token
    let token_response: TokenResponse = Client::new()
        .post("https://oauth.example.com/token")
        .form(&[
            ("grant_type", "client_credentials"),
            ("client_id", &input.client_id),
            ("client_secret", &input.client_secret),
        ])
        .send()
        .await?
        .json()
        .await?;

    // Step 2: Use access token
    let response = Client::new()
        .get(&format!("https://api.example.com/{}", input.resource))
        .bearer_auth(&token_response.access_token)
        .send()
        .await?;

    Ok(ApiResponse {
        status: response.status().as_u16(),
        body: response.json().await?,
    })
}

Token Refresh Flow

use std::sync::Arc;
use tokio::sync::RwLock;
use std::time::{SystemTime, UNIX_EPOCH};

struct TokenCache {
    access_token: String,
    expires_at: u64,
}

pub struct OAuthHandler {
    client_id: String,
    client_secret: String,
    token_cache: Arc<RwLock<Option<TokenCache>>>,
    client: Client,
}

impl OAuthHandler {
    async fn get_access_token(&self) -> Result<String> {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)?
            .as_secs();

        // Check cache
        {
            let cache = self.token_cache.read().await;
            if let Some(token) = cache.as_ref() {
                if token.expires_at > now + 60 {  // 1 minute buffer
                    return Ok(token.access_token.clone());
                }
            }
        }

        // Refresh token
        let response: TokenResponse = self.client
            .post("https://oauth.example.com/token")
            .form(&[
                ("grant_type", "client_credentials"),
                ("client_id", &self.client_id),
                ("client_secret", &self.client_secret),
            ])
            .send()
            .await?
            .json()
            .await?;

        let expires_at = now + response.expires_in;

        // Update cache
        {
            let mut cache = self.token_cache.write().await;
            *cache = Some(TokenCache {
                access_token: response.access_token.clone(),
                expires_at,
            });
        }

        Ok(response.access_token)
    }

    async fn handle(&self, input: OAuthInput) -> Result<ApiResponse> {
        let access_token = self.get_access_token().await?;

        let response = self.client
            .get(&format!("https://api.example.com/{}", input.resource))
            .bearer_auth(&access_token)
            .send()
            .await?;

        Ok(ApiResponse {
            status: response.status().as_u16(),
            body: response.json().await?,
        })
    }
}

JWT Authentication

JWT Token Generation

use jsonwebtoken::{encode, Header, EncodingKey};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Claims {
    sub: String,
    exp: u64,
    iat: u64,
}

async fn handle(&self, input: JwtInput) -> Result<ApiResponse> {
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)?
        .as_secs();

    let claims = Claims {
        sub: input.user_id,
        iat: now,
        exp: now + 3600,  // 1 hour
    };

    let token = encode(
        &Header::default(),
        &claims,
        &EncodingKey::from_secret(input.secret.as_bytes()),
    )?;

    let response = self.client
        .get(&input.url)
        .bearer_auth(&token)
        .send()
        .await?;

    Ok(ApiResponse {
        status: response.status().as_u16(),
        body: response.json().await?,
    })
}

HMAC Signature Authentication

AWS Signature V4 Example

use hmac::{Hmac, Mac};
use sha2::Sha256;
use hex::encode;

type HmacSha256 = Hmac<Sha256>;

fn sign_request(
    secret: &str,
    method: &str,
    path: &str,
    timestamp: u64,
) -> String {
    let string_to_sign = format!("{}\n{}\n{}", method, path, timestamp);

    let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
        .expect("HMAC creation failed");
    mac.update(string_to_sign.as_bytes());

    encode(mac.finalize().into_bytes())
}

async fn handle(&self, input: SignedInput) -> Result<ApiResponse> {
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)?
        .as_secs();

    let signature = sign_request(
        &input.secret,
        "GET",
        &input.path,
        timestamp,
    );

    let response = self.client
        .get(&format!("https://api.example.com{}", input.path))
        .header("X-Timestamp", timestamp.to_string())
        .header("X-Signature", signature)
        .send()
        .await?;

    Ok(ApiResponse {
        status: response.status().as_u16(),
        body: response.json().await?,
    })
}

Authentication Best Practices

1. Never Hardcode Secrets

# BAD
headers:
  Authorization: "Bearer hardcoded_token_123"

# GOOD
headers:
  Authorization: "Bearer {{access_token}}"
params:
  access_token: { type: string, required: true }

2. Use Environment Variables

use std::env;

let api_key = env::var("API_KEY")
    .map_err(|_| Error::Config("API_KEY not set".into()))?;

3. Implement Token Rotation

// Rotate tokens before expiry
if token.expires_at - now < 300 {  // 5 minutes before expiry
    token = refresh_token().await?;
}

4. Secure Token Storage

use keyring::Entry;

// Store token securely
let entry = Entry::new("pforge", "api_token")?;
entry.set_password(&token)?;

// Retrieve token
let token = entry.get_password()?;

Testing Authentication

Mock OAuth Server

#[tokio::test]
async fn test_oauth_flow() {
    let mock_server = MockServer::start().await;

    // Mock token endpoint
    Mock::given(method("POST"))
        .and(path("/token"))
        .respond_with(ResponseTemplate::new(200)
            .set_body_json(json!({
                "access_token": "test_token",
                "token_type": "Bearer",
                "expires_in": 3600
            })))
        .mount(&mock_server)
        .await;

    // Mock API endpoint
    Mock::given(method("GET"))
        .and(path("/data"))
        .and(header("Authorization", "Bearer test_token"))
        .respond_with(ResponseTemplate::new(200)
            .set_body_json(json!({"data": "success"})))
        .mount(&mock_server)
        .await;

    // Test handler
    let handler = OAuthHandler::new(
        "client_id".to_string(),
        "client_secret".to_string(),
        mock_server.uri(),
    );

    let result = handler.handle(OAuthInput {
        resource: "data".to_string(),
    }).await.unwrap();

    assert_eq!(result.status, 200);
}

Next Steps

Chapter 5.3 covers HTTP error handling, including retry strategies, circuit breakers, and graceful degradation patterns.

“Authentication is trust. Handle it with care.” - pforge security principle

HTTP Error Handling

HTTP handlers must gracefully handle network failures, timeouts, and API errors. This chapter covers retry strategies, circuit breakers, and graceful degradation.

Error Types

Network Errors

{
  "error": "Http: Connection refused"
}

HTTP Status Errors

HTTP handlers return status codes, not errors:

{
  "status": 404,
  "body": { "message": "Not Found" },
  "headers": {...}
}

Client handles status:

if (result.status >= 400) {
  throw new APIError(result.status, result.body);
}

Timeout Errors

{
  "error": "Timeout: Request exceeded 30000ms"
}

Retry Strategies

Exponential Backoff (Native Handler)

use backoff::{ExponentialBackoff, Error as BackoffError};
use std::time::Duration;

async fn handle_with_retry(&self, input: Input) -> Result<Output> {
    let backoff = ExponentialBackoff {
        initial_interval: Duration::from_millis(100),
        multiplier: 2.0,
        max_interval: Duration::from_secs(30),
        max_elapsed_time: Some(Duration::from_mins(5)),
        ..Default::default()
    };

    backoff::retry(backoff, || async {
        match self.client.get(&input.url).send().await {
            Ok(resp) if resp.status().is_success() => Ok(resp),
            Ok(resp) if resp.status().is_server_error() => {
                // Retry 5xx errors
                Err(BackoffError::transient(Error::Http(...)))
            },
            Ok(resp) => {
                // Don't retry 4xx errors
                Err(BackoffError::permanent(Error::Http(...)))
            },
            Err(e) if e.is_timeout() => {
                // Retry timeouts
                Err(BackoffError::transient(Error::from(e)))
            },
            Err(e) => Err(BackoffError::permanent(Error::from(e))),
        }
    }).await
}

Retry with Jitter

use rand::Rng;

async fn retry_with_jitter<F, Fut, T>(
    max_attempts: u32,
    base_delay_ms: u64,
    operation: F,
) -> Result<T>
where
    F: Fn() -> Fut,
    Fut: std::future::Future<Output = Result<T>>,
{
    let mut attempt = 0;
    let mut rng = rand::thread_rng();

    loop {
        match operation().await {
            Ok(result) => return Ok(result),
            Err(e) if attempt >= max_attempts - 1 => return Err(e),
            Err(_) => {
                let jitter = rng.gen_range(0..base_delay_ms / 2);
                let delay = (base_delay_ms * 2_u64.pow(attempt)) + jitter;
                tokio::time::sleep(Duration::from_millis(delay)).await;
                attempt += 1;
            }
        }
    }
}

Circuit Breaker Pattern

Implementation

use std::sync::Arc;
use tokio::sync::RwLock;
use std::time::{Instant, Duration};

#[derive(Clone)]
enum CircuitState {
    Closed,
    Open { opened_at: Instant },
    HalfOpen,
}

struct CircuitBreaker {
    state: Arc<RwLock<CircuitState>>,
    failure_threshold: u32,
    timeout: Duration,
    failures: Arc<RwLock<u32>>,
}

impl CircuitBreaker {
    async fn call<F, Fut, T>(&self, operation: F) -> Result<T>
    where
        F: FnOnce() -> Fut,
        Fut: std::future::Future<Output = Result<T>>,
    {
        // Check state
        let state = self.state.read().await.clone();

        match state {
            CircuitState::Open { opened_at } => {
                if opened_at.elapsed() > self.timeout {
                    // Transition to HalfOpen
                    *self.state.write().await = CircuitState::HalfOpen;
                } else {
                    return Err(Error::CircuitOpen);
                }
            }
            CircuitState::HalfOpen | CircuitState::Closed => {}
        }

        // Execute operation
        match operation().await {
            Ok(result) => {
                // Success - close circuit
                *self.state.write().await = CircuitState::Closed;
                *self.failures.write().await = 0;
                Ok(result)
            }
            Err(e) => {
                // Failure - increment counter
                let mut failures = self.failures.write().await;
                *failures += 1;

                if *failures >= self.failure_threshold {
                    // Open circuit
                    *self.state.write().await = CircuitState::Open {
                        opened_at: Instant::now(),
                    };
                }

                Err(e)
            }
        }
    }
}

Usage

let breaker = CircuitBreaker::new(
    5,  // failure_threshold
    Duration::from_secs(60),  // timeout
);

let result = breaker.call(|| async {
    self.client.get(&url).send().await
}).await?;

Fallback Patterns

Primary/Secondary Endpoints

async fn handle_with_fallback(&self, input: Input) -> Result<Output> {
    // Try primary endpoint
    match self.client.get(&self.primary_url).send().await {
        Ok(resp) if resp.status().is_success() => {
            return Ok(resp.json().await?);
        }
        Err(e) => {
            tracing::warn!("Primary endpoint failed: {}", e);
        }
        _ => {}
    }

    // Fallback to secondary
    tracing::info!("Using fallback endpoint");
    let resp = self.client.get(&self.fallback_url).send().await?;
    Ok(resp.json().await?)
}

Cached Response Fallback

use lru::LruCache;
use std::sync::Arc;
use tokio::sync::Mutex;

struct CachedHandler {
    client: Client,
    cache: Arc<Mutex<LruCache<String, serde_json::Value>>>,
}

impl CachedHandler {
    async fn handle(&self, input: Input) -> Result<Output> {
        let cache_key = format!("{}-{}", input.resource, input.id);

        // Try API
        match self.client.get(&input.url).send().await {
            Ok(resp) if resp.status().is_success() => {
                let data: serde_json::Value = resp.json().await?;

                // Update cache
                self.cache.lock().await.put(cache_key.clone(), data.clone());

                Ok(Output { data })
            }
            _ => {
                // Fallback to cache
                if let Some(cached) = self.cache.lock().await.get(&cache_key) {
                    tracing::warn!("Using cached response");
                    return Ok(Output { data: cached.clone() });
                }

                Err(Error::Unavailable)
            }
        }
    }
}

Rate Limiting

Token Bucket Implementation

use std::time::Instant;

struct TokenBucket {
    tokens: f64,
    capacity: f64,
    rate: f64,  // tokens per second
    last_refill: Instant,
}

impl TokenBucket {
    async fn acquire(&mut self) -> Result<()> {
        let now = Instant::now();
        let elapsed = now.duration_since(self.last_refill).as_secs_f64();

        // Refill tokens
        self.tokens = (self.tokens + elapsed * self.rate).min(self.capacity);
        self.last_refill = now;

        if self.tokens >= 1.0 {
            self.tokens -= 1.0;
            Ok(())
        } else {
            let wait_time = ((1.0 - self.tokens) / self.rate) * 1000.0;
            tokio::time::sleep(Duration::from_millis(wait_time as u64)).await;
            self.tokens = 0.0;
            Ok(())
        }
    }
}

// Usage
async fn handle(&self, input: Input) -> Result<Output> {
    self.rate_limiter.lock().await.acquire().await?;
    let resp = self.client.get(&input.url).send().await?;
    Ok(resp.json().await?)
}

Timeout Management

Adaptive Timeouts

use std::collections::VecDeque;

struct AdaptiveTimeout {
    latencies: VecDeque<Duration>,
    window_size: usize,
}

impl AdaptiveTimeout {
    fn get_timeout(&self) -> Duration {
        if self.latencies.is_empty() {
            return Duration::from_secs(30);  // Default
        }

        let avg: Duration = self.latencies.iter().sum::<Duration>() / self.latencies.len() as u32;
        avg * 3  // 3x average latency
    }

    fn record(&mut self, latency: Duration) {
        self.latencies.push_back(latency);
        if self.latencies.len() > self.window_size {
            self.latencies.pop_front();
        }
    }
}

async fn handle(&self, input: Input) -> Result<Output> {
    let timeout_duration = self.adaptive_timeout.lock().await.get_timeout();
    let start = Instant::now();

    let result = tokio::time::timeout(
        timeout_duration,
        self.client.get(&input.url).send()
    ).await??;

    self.adaptive_timeout.lock().await.record(start.elapsed());
    Ok(result.json().await?)
}

Error Recovery Patterns

Pattern 1: Retry-Then-Circuit

async fn robust_call(&self, input: Input) -> Result<Output> {
    // Try with retries
    let result = retry_with_backoff(3, || async {
        self.client.get(&input.url).send().await
    }).await;

    // If retries exhausted, open circuit
    match result {
        Ok(resp) => Ok(resp.json().await?),
        Err(_) => {
            self.circuit_breaker.open();
            Err(Error::Unavailable)
        }
    }
}

Pattern 2: Parallel Requests

async fn parallel_fallback(&self, input: Input) -> Result<Output> {
    let primary = self.client.get(&self.primary_url).send();
    let secondary = self.client.get(&self.secondary_url).send();

    // Use first successful response
    tokio::select! {
        Ok(resp) = primary => Ok(resp.json().await?),
        Ok(resp) = secondary => {
            tracing::info!("Used secondary endpoint");
            Ok(resp.json().await?)
        },
        else => Err(Error::Unavailable),
    }
}

Testing Error Scenarios

Mock Network Failures

#[tokio::test]
async fn test_retry_on_failure() {
    let mock_server = MockServer::start().await;

    // Fail twice, succeed third time
    mock_server.register_as_sequence(vec![
        Mock::given(method("GET"))
            .respond_with(ResponseTemplate::new(500)),
        Mock::given(method("GET"))
            .respond_with(ResponseTemplate::new(500)),
        Mock::given(method("GET"))
            .respond_with(ResponseTemplate::new(200)
                .set_body_json(json!({"success": true}))),
    ]).await;

    let handler = RetryHandler::new(mock_server.uri(), 3);
    let result = handler.handle(Input {}).await.unwrap();

    assert_eq!(result.data["success"], true);
}

Next Steps

Chapter 6.0 introduces Pipeline handlers for composing multiple tools into workflows.

“Errors are inevitable. Recovery is engineering.” - pforge resilience principle

Data Pipeline: Pipeline Handler Overview

Pipeline handlers compose multiple tools into workflows. This chapter demonstrates building data processing pipelines with conditional execution and state management.

Why Pipeline Handlers?

Use pipeline handlers when:

• Chaining multiple tools together
• Output of one tool feeds input of next
• Conditional execution based on results
• Multi-step workflows with shared state

Don’t use pipeline handlers when:

• Single tool suffices
• Complex branching logic (use Native)
• Real-time streaming required
• Tools are independent (call separately)

Example: Data Processing Pipeline

forge:
  name: data-pipeline
  version: 0.1.0
  transport: stdio

tools:
  - type: pipeline
    name: process_user_data
    description: "Fetch, validate, transform, and store user data"
    steps:
      - tool: fetch_user
        input:
          user_id: "{{user_id}}"
        output_var: user_data

      - tool: validate_user
        input:
          data: "{{user_data}}"
        output_var: validated
        condition: "user_data"

      - tool: transform_data
        input:
          raw: "{{validated}}"
        output_var: transformed
        condition: "validated"

      - tool: store_data
        input:
          data: "{{transformed}}"
        error_policy: fail_fast
    params:
      user_id:
        type: string
        required: true

Pipeline Anatomy

Steps

steps:
  - tool: step_name        # Tool to execute
    input: {...}           # Input template
    output_var: result     # Store output in variable
    condition: "var_name"  # Execute if variable exists
    error_policy: continue # Or fail_fast

Variable Interpolation

steps:
  - tool: get_data
    input:
      id: "{{request_id}}"
    output_var: data

  - tool: process
    input:
      payload: "{{data}}"  # Uses output from previous step

Error Policies

fail_fast (default): Stop on first error

error_policy: fail_fast

continue: Skip failed steps, continue pipeline

error_policy: continue

Complete Pipeline Example

tools:
  # Individual tools
  - type: http
    name: fetch_weather
    endpoint: "https://api.weather.com/{{city}}"
    method: GET
    params:
      city: { type: string, required: true }

  - type: native
    name: parse_weather
    handler:
      path: handlers::parse_weather
    params:
      raw_data: { type: object, required: true }

  - type: http
    name: send_notification
    endpoint: "https://notify.example.com/send"
    method: POST
    body:
      message: "{{message}}"
    params:
      message: { type: string, required: true }

  # Pipeline composing them
  - type: pipeline
    name: weather_alert
    description: "Fetch weather and send alerts if needed"
    steps:
      - tool: fetch_weather
        input:
          city: "{{city}}"
        output_var: raw_weather

      - tool: parse_weather
        input:
          raw_data: "{{raw_weather}}"
        output_var: weather
        condition: "raw_weather"

      - tool: send_notification
        input:
          message: "Alert: {{weather.condition}} in {{city}}"
        condition: "weather.is_alert"
        error_policy: continue

    params:
      city: { type: string, required: true }

Pipeline Execution Flow

Input: { "city": "Boston" }
  ↓
Step 1: fetch_weather(city="Boston")
  → Output: { "temp": 32, "condition": "snow" }
  → Store in: raw_weather
  ↓
Step 2: parse_weather(raw_data=raw_weather)
  → Condition: raw_weather exists ✓
  → Output: { "is_alert": true, "condition": "Heavy Snow" }
  → Store in: weather
  ↓
Step 3: send_notification(message="Alert: Heavy Snow in Boston")
  → Condition: weather.is_alert=true ✓
  → Output: { "sent": true }
  ↓
Pipeline Result: { "results": [...], "variables": {...} }

Input/Output Structure

Pipeline Input

{
  "variables": {
    "city": "Boston",
    "user_id": "123"
  }
}

Pipeline Output

{
  "results": [
    {
      "tool": "fetch_weather",
      "success": true,
      "output": { "temp": 32, "condition": "snow" },
      "error": null
    },
    {
      "tool": "parse_weather",
      "success": true,
      "output": { "is_alert": true },
      "error": null
    },
    {
      "tool": "send_notification",
      "success": true,
      "output": { "sent": true },
      "error": null
    }
  ],
  "variables": {
    "city": "Boston",
    "raw_weather": {...},
    "weather": {...}
  }
}

Error Handling

Fail Fast (Default)

steps:
  - tool: critical_step
    input: {...}
    # Implicit: error_policy: fail_fast

  - tool: next_step
    input: {...}
    # Won't execute if critical_step fails

Continue on Error

steps:
  - tool: optional_step
    input: {...}
    error_policy: continue  # Pipeline continues even if this fails

  - tool: final_step
    input: {...}
    # Executes regardless of optional_step outcome

Real-World Example: ETL Pipeline

tools:
  - type: pipeline
    name: etl_pipeline
    description: "Extract, Transform, Load data pipeline"
    steps:
      # Extract
      - tool: extract_from_api
        input:
          endpoint: "{{source_url}}"
          api_key: "{{api_key}}"
        output_var: raw_data
        error_policy: fail_fast

      # Transform
      - tool: clean_data
        input:
          data: "{{raw_data}}"
        output_var: cleaned
        condition: "raw_data"

      - tool: enrich_data
        input:
          data: "{{cleaned}}"
        output_var: enriched
        condition: "cleaned"

      - tool: aggregate_data
        input:
          data: "{{enriched}}"
        output_var: aggregated
        condition: "enriched"

      # Load
      - tool: validate_schema
        input:
          data: "{{aggregated}}"
        output_var: validated
        error_policy: fail_fast

      - tool: load_to_database
        input:
          data: "{{validated}}"
          table: "{{target_table}}"
        error_policy: fail_fast

      # Notify
      - tool: send_success_notification
        input:
          message: "ETL completed: {{aggregated.count}} records"
        error_policy: continue

    params:
      source_url: { type: string, required: true }
      api_key: { type: string, required: true }
      target_table: { type: string, required: true }

Performance Characteristics

When to Use Native vs Pipeline

Pipeline Handler - Linear workflows:

type: pipeline
steps:
  - tool: fetch
  - tool: process
  - tool: store

Native Handler - Complex logic:

async fn handle(&self, input: Input) -> Result<Output> {
    let data = fetch().await?;

    if data.requires_processing() {
        let processed = complex_transform(data)?;
        store(processed).await?;
    } else {
        quick_store(data).await?;
    }

    Ok(Output { ... })
}

Next Steps

Chapter 6.1 covers tool composition patterns, including parallel execution and error propagation.

“Pipelines compose tools. Tools compose behavior.” - pforge composition principle

Tool Composition

Pipeline handlers chain tools together, passing outputs as inputs. This chapter covers composition patterns, data flow, and error propagation.

Basic Chaining

Sequential Execution

steps:
  - tool: step1
    input: { id: "{{request_id}}" }
    output_var: result1

  - tool: step2
    input: { data: "{{result1}}" }
    output_var: result2

  - tool: step3
    input: { processed: "{{result2}}" }

Execution order: step1 → step2 → step3

Output Variable Scoping

Variables persist throughout pipeline:

steps:
  - tool: fetch
    output_var: data

  - tool: validate
    output_var: validated

  - tool: final
    input:
      original: "{{data}}"      # From step 1
      validated: "{{validated}}" # From step 2

Data Transformation Patterns

Pattern 1: Extract-Transform-Load (ETL)

steps:
  # Extract
  - tool: http_get
    input: { url: "{{source}}" }
    output_var: raw

  # Transform
  - tool: parse_json
    input: { json: "{{raw.body}}" }
    output_var: parsed

  - tool: filter_records
    input: { records: "{{parsed}}", criteria: "{{filter}}" }
    output_var: filtered

  # Load
  - tool: bulk_insert
    input: { data: "{{filtered}}", table: "{{target}}" }

Pattern 2: Fan-Out Aggregation

Use Native handler for parallel execution:

async fn handle(&self, input: Input) -> Result<Output> {
    let futures = input.ids.iter().map(|id| {
        self.registry.dispatch("fetch_item", json!({ "id": id }))
    });

    let results = futures::future::join_all(futures).await;
    let aggregated = aggregate_results(results)?;

    Ok(Output { data: aggregated })
}

Pattern 3: Map-Reduce

# Map phase (Native handler)
- tool: map_items
  input: { items: "{{data}}" }
  output_var: mapped

# Reduce phase
- tool: reduce_results
  input: { mapped: "{{mapped}}" }
  output_var: final

Error Propagation

Explicit Error Handling

steps:
  - tool: risky_operation
    input: { data: "{{input}}" }
    output_var: result
    error_policy: fail_fast  # Stop immediately on error

  - tool: cleanup
    input: { id: "{{request_id}}" }
    # Never executes if risky_operation fails

Graceful Degradation

steps:
  - tool: primary_source
    input: { id: "{{id}}" }
    output_var: data
    error_policy: continue  # Don't fail pipeline

  - tool: fallback_source
    input: { id: "{{id}}" }
    output_var: data
    condition: "!data"  # Only if primary failed

Error Recovery

// In PipelineHandler
async fn execute(&self, input: Input) -> Result<Output> {
    let mut variables = input.variables;
    let mut results = Vec::new();

    for step in &self.steps {
        match self.execute_step(step, &variables).await {
            Ok(output) => {
                if let Some(var) = &step.output_var {
                    variables.insert(var.clone(), output.clone());
                }
                results.push(StepResult {
                    tool: step.tool.clone(),
                    success: true,
                    output: Some(output),
                    error: None,
                });
            }
            Err(e) if step.error_policy == ErrorPolicy::Continue => {
                results.push(StepResult {
                    tool: step.tool.clone(),
                    success: false,
                    output: None,
                    error: Some(e.to_string()),
                });
                continue;
            }
            Err(e) => return Err(e),
        }
    }

    Ok(Output { results, variables })
}

Complex Composition Patterns

Pattern 1: Conditional Branching

steps:
  - tool: check_eligibility
    input: { user_id: "{{user_id}}" }
    output_var: eligible

  - tool: premium_process
    input: { user: "{{user_id}}" }
    condition: "eligible.is_premium"

  - tool: standard_process
    input: { user: "{{user_id}}" }
    condition: "!eligible.is_premium"

Pattern 2: Retry with Backoff

steps:
  - tool: attempt_operation
    input: { data: "{{data}}" }
    output_var: result
    error_policy: continue

  - tool: retry_operation
    input: { data: "{{data}}", attempt: 2 }
    condition: "!result"
    error_policy: continue

  - tool: final_retry
    input: { data: "{{data}}", attempt: 3 }
    condition: "!result"

Pattern 3: Data Enrichment

steps:
  - tool: get_user
    input: { id: "{{user_id}}" }
    output_var: user

  - tool: get_preferences
    input: { user_id: "{{user_id}}" }
    output_var: prefs

  - tool: get_activity
    input: { user_id: "{{user_id}}" }
    output_var: activity

  - tool: merge_profile
    input:
      user: "{{user}}"
      preferences: "{{prefs}}"
      activity: "{{activity}}"

Testing Composition

Unit Test: Step Execution

#[tokio::test]
async fn test_step_execution() {
    let registry = HandlerRegistry::new();
    registry.register("tool1", Box::new(Tool1Handler));
    registry.register("tool2", Box::new(Tool2Handler));

    let pipeline = PipelineHandler::new(vec![
        PipelineStep {
            tool: "tool1".to_string(),
            input: Some(json!({"id": "123"})),
            output_var: Some("result".to_string()),
            condition: None,
            error_policy: ErrorPolicy::FailFast,
        },
        PipelineStep {
            tool: "tool2".to_string(),
            input: Some(json!({"data": "{{result}}"})),
            output_var: None,
            condition: None,
            error_policy: ErrorPolicy::FailFast,
        },
    ]);

    let result = pipeline.execute(
        PipelineInput { variables: HashMap::new() },
        &registry
    ).await.unwrap();

    assert_eq!(result.results.len(), 2);
    assert!(result.results[0].success);
    assert!(result.results[1].success);
}

Integration Test: Full Pipeline

#[tokio::test]
async fn test_etl_pipeline() {
    let pipeline = build_etl_pipeline();
    let input = PipelineInput {
        variables: [
            ("source_url", json!("https://api.example.com/data")),
            ("target_table", json!("processed_data")),
        ].into(),
    };

    let result = pipeline.execute(input, &registry).await.unwrap();

    // Verify all steps executed
    assert_eq!(result.results.len(), 6);

    // Verify data flow
    assert!(result.variables.contains_key("raw_data"));
    assert!(result.variables.contains_key("cleaned"));
    assert!(result.variables.contains_key("validated"));

    // Verify final result
    let final_step = &result.results.last().unwrap();
    assert!(final_step.success);
}

Performance Optimization

Parallel Step Execution (Future Enhancement)

# Current: Sequential
steps:
  - tool: fetch_user
  - tool: fetch_prefs
  - tool: fetch_activity

# Future: Parallel
parallel_steps:
  - [fetch_user, fetch_prefs, fetch_activity]  # Execute in parallel
  - [merge_data]                                # Wait for all, then execute

Variable Cleanup

// Clean up unused variables to save memory
fn cleanup_variables(&mut self, current_step: usize) {
    self.variables.retain(|var_name, _| {
        self.is_variable_used_after(var_name, current_step)
    });
}

Best Practices

1. Minimize State

# BAD - accumulating state
steps:
  - tool: step1
    output_var: data1
  - tool: step2
    output_var: data2
  - tool: step3
    output_var: data3
  # All variables kept in memory

# GOOD - only keep what's needed
steps:
  - tool: step1
    output_var: temp
  - tool: step2
    input: { data: "{{temp}}" }
    output_var: result
  # temp can be dropped

2. Clear Error Policies

# Explicit error handling
steps:
  - tool: critical
    error_policy: fail_fast  # Must succeed

  - tool: optional
    error_policy: continue   # Can fail

  - tool: cleanup
    error_policy: fail_fast  # Must run if reached

3. Meaningful Variable Names

# BAD
output_var: data1

# GOOD
output_var: validated_user_profile

Next Steps

Chapter 6.2 covers conditional execution patterns and complex branching logic.

“Composition is about data flow. Make it explicit.” - pforge design principle

Conditional Execution

Pipeline steps can execute conditionally based on variable state. This chapter covers condition syntax, patterns, and advanced branching logic.

Condition Syntax

Variable Existence

steps:
  - tool: fetch_data
    output_var: data

  - tool: process
    condition: "data"  # Execute if 'data' variable exists

Variable Absence

steps:
  - tool: primary
    output_var: result
    error_policy: continue

  - tool: fallback
    condition: "!result"  # Execute if 'result' doesn't exist

Nested Variable Access

steps:
  - tool: get_user
    output_var: user

  - tool: send_email
    condition: "user.email_verified"  # Access nested field

Conditional Patterns

Pattern 1: Primary/Fallback

steps:
  - tool: fast_cache
    input: { key: "{{key}}" }
    output_var: data
    error_policy: continue

  - tool: slow_database
    input: { key: "{{key}}" }
    output_var: data
    condition: "!data"  # Only if cache miss

Pattern 2: Feature Flags

steps:
  - tool: check_feature
    input: { feature: "new_algorithm", user: "{{user_id}}" }
    output_var: feature_enabled

  - tool: new_algorithm
    input: { data: "{{data}}" }
    condition: "feature_enabled"
    output_var: result

  - tool: old_algorithm
    input: { data: "{{data}}" }
    condition: "!feature_enabled"
    output_var: result

Pattern 3: Validation Gates

steps:
  - tool: validate_input
    input: { data: "{{raw}}" }
    output_var: validation

  - tool: process_valid
    input: { data: "{{raw}}" }
    condition: "validation.is_valid"

  - tool: handle_invalid
    input: { errors: "{{validation.errors}}" }
    condition: "!validation.is_valid"

Complex Conditions

Multiple Variables

Current implementation supports simple conditions. For complex logic, use Native handler:

async fn handle(&self, input: Input) -> Result<Output> {
    let user = fetch_user(&input.user_id).await?;
    let permissions = fetch_permissions(&input.user_id).await?;

    // Complex condition
    if user.is_admin && permissions.can_write && !user.is_suspended {
        return process_admin_request(input).await;
    }

    if permissions.can_read {
        return process_read_request(input).await;
    }

    Err(Error::Unauthorized)
}

Threshold Checks

steps:
  - tool: check_balance
    input: { account: "{{account_id}}" }
    output_var: balance

  - tool: high_value_process
    input: { amount: "{{amount}}" }
    condition: "balance.value >= 1000"  # Future feature

  - tool: standard_process
    input: { amount: "{{amount}}" }
    condition: "balance.value < 1000"   # Future feature

Current workaround: Use validation tool:

steps:
  - tool: check_balance
    output_var: balance

  - tool: classify_tier
    input: { balance: "{{balance}}" }
    output_var: tier  # Returns { "is_high_value": true/false }

  - tool: high_value_process
    condition: "tier.is_high_value"

  - tool: standard_process
    condition: "!tier.is_high_value"

Condition Evaluation

Implementation

fn evaluate_condition(
    &self,
    condition: &str,
    variables: &HashMap<String, serde_json::Value>,
) -> bool {
    // Simple variable existence check
    if let Some(var_name) = condition.strip_prefix('!') {
        !variables.contains_key(var_name)
    } else {
        variables.contains_key(condition)
    }
}

Nested Field Access (Future)

fn evaluate_nested_condition(
    condition: &str,
    variables: &HashMap<String, Value>,
) -> bool {
    let parts: Vec<&str> = condition.split('.').collect();

    if let Some(value) = variables.get(parts[0]) {
        // Navigate nested structure
        let mut current = value;
        for part in &parts[1..] {
            match current {
                Value::Object(map) => {
                    if let Some(next) = map.get(*part) {
                        current = next;
                    } else {
                        return false;
                    }
                }
                _ => return false,
            }
        }

        // Check truthiness
        match current {
            Value::Bool(b) => *b,
            Value::Null => false,
            Value::Number(n) => n.as_f64().unwrap_or(0.0) != 0.0,
            Value::String(s) => !s.is_empty(),
            _ => true,
        }
    } else {
        false
    }
}

Error Handling with Conditions

Graceful Degradation

steps:
  - tool: primary_service
    output_var: result
    error_policy: continue

  - tool: secondary_service
    condition: "!result"
    output_var: result
    error_policy: continue

  - tool: cached_fallback
    condition: "!result"
    output_var: result

  - tool: process_result
    input: { data: "{{result}}" }
    condition: "result"

Cleanup Steps

steps:
  - tool: allocate_resources
    output_var: resources

  - tool: process_data
    input: { res: "{{resources}}" }
    output_var: result

  # Always cleanup, even on error
  - tool: cleanup_resources
    input: { res: "{{resources}}" }
    condition: "resources"
    error_policy: continue  # Don't fail if cleanup fails

Testing Conditionals

Test Condition Evaluation

#[test]
fn test_condition_evaluation() {
    let pipeline = PipelineHandler::new(vec![]);

    let mut vars = HashMap::new();
    vars.insert("exists".to_string(), json!(true));

    assert!(pipeline.evaluate_condition("exists", &vars));
    assert!(!pipeline.evaluate_condition("!exists", &vars));
    assert!(!pipeline.evaluate_condition("missing", &vars));
    assert!(pipeline.evaluate_condition("!missing", &vars));
}

Test Conditional Execution

#[tokio::test]
async fn test_conditional_step() {
    let registry = HandlerRegistry::new();
    registry.register("tool1", Box::new(MockTool1));
    registry.register("tool2", Box::new(MockTool2));

    let pipeline = PipelineHandler::new(vec![
        PipelineStep {
            tool: "tool1".to_string(),
            output_var: Some("data".to_string()),
            ..Default::default()
        },
        PipelineStep {
            tool: "tool2".to_string(),
            condition: Some("data".to_string()),
            ..Default::default()
        },
    ]);

    let result = pipeline.execute(
        PipelineInput { variables: HashMap::new() },
        &registry
    ).await.unwrap();

    // Both steps should execute
    assert_eq!(result.results.len(), 2);
    assert!(result.results[1].success);
}

Test Skipped Steps

#[tokio::test]
async fn test_skipped_step() {
    let pipeline = PipelineHandler::new(vec![
        PipelineStep {
            tool: "tool1".to_string(),
            condition: Some("missing_var".to_string()),
            ..Default::default()
        },
    ]);

    let result = pipeline.execute(
        PipelineInput { variables: HashMap::new() },
        &registry
    ).await.unwrap();

    // Step should be skipped
    assert_eq!(result.results.len(), 0);
}

Advanced Patterns

Retries with Condition

steps:
  - tool: attempt_1
    output_var: result
    error_policy: continue

  - tool: wait_retry
    condition: "!result"
    input: { delay_ms: 1000 }

  - tool: attempt_2
    condition: "!result"
    output_var: result
    error_policy: continue

  - tool: final_attempt
    condition: "!result"
    output_var: result

Multi-Path Workflows

steps:
  - tool: classify_request
    input: { type: "{{request_type}}" }
    output_var: classification

  # Path A: Urgent requests
  - tool: urgent_handler
    condition: "classification.is_urgent"

  # Path B: Normal requests
  - tool: normal_handler
    condition: "!classification.is_urgent"

  # Path C: Batch requests
  - tool: batch_handler
    condition: "classification.is_batch"

Best Practices

1. Explicit Conditions

# BAD - implicit
- tool: fallback

# GOOD - explicit
- tool: fallback
  condition: "!primary_result"

2. Document Branching

steps:
  # Try primary source
  - tool: primary_api
    output_var: data
    error_policy: continue

  # Fallback if primary fails
  - tool: fallback_api
    output_var: data
    condition: "!data"

3. Test All Paths

#[tokio::test]
async fn test_all_conditional_paths() {
    // Test primary path
    test_with_variables([("feature_enabled", true)]).await;

    // Test fallback path
    test_with_variables([("feature_enabled", false)]).await;

    // Test error path
    test_with_variables([]).await;
}

Next Steps

Chapter 6.3 covers pipeline state management including variable scoping and memory optimization.

“Conditions control flow. Make the flow visible.” - pforge conditional principle

Pipeline State Management

Pipeline handlers maintain state through variables. This chapter covers variable scoping, memory management, and state persistence patterns.

Variable Lifecycle

Creation

Variables are created when tools complete:

steps:
  - tool: fetch_data
    output_var: data  # Variable created here

Access

Variables are accessed via interpolation:

steps:
  - tool: process
    input:
      payload: "{{data}}"  # Variable accessed here

Persistence

Variables persist through entire pipeline:

steps:
  - tool: step1
    output_var: var1

  - tool: step2
    output_var: var2

  - tool: final
    input:
      first: "{{var1}}"   # Still accessible
      second: "{{var2}}"  # Both available

Variable Scoping

Pipeline Scope

Variables are scoped to the pipeline execution:

pub struct PipelineOutput {
    pub results: Vec<StepResult>,
    pub variables: HashMap<String, Value>,  // Final state
}

Initial Variables

Input variables seed the pipeline:

# Pipeline definition
params:
  user_id: { type: string, required: true }
  config: { type: object, required: false }

# Execution
{
  "variables": {
    "user_id": "123",
    "config": { "debug": true }
  }
}

Variable Shadowing

Later steps can overwrite variables:

steps:
  - tool: get_draft
    output_var: document

  - tool: validate
    input: { doc: "{{document}}" }

  - tool: get_final
    output_var: document  # Overwrites previous value

Memory Management

Variable Storage

use std::collections::HashMap;
use serde_json::Value;

struct PipelineState {
    variables: HashMap<String, Value>,
}

impl PipelineState {
    fn set(&mut self, key: String, value: Value) {
        self.variables.insert(key, value);
    }

    fn get(&self, key: &str) -> Option<&Value> {
        self.variables.get(key)
    }

    fn size_bytes(&self) -> usize {
        self.variables.iter()
            .map(|(k, v)| {
                k.len() + serde_json::to_vec(v).unwrap().len()
            })
            .sum()
    }
}

Memory Optimization

Pattern 1: Drop Unused Variables

fn cleanup_unused_variables(
    &mut self,
    current_step: usize,
) {
    let future_steps = &self.steps[current_step..];

    self.variables.retain(|var_name, _| {
        // Keep if used in future steps
        future_steps.iter().any(|step| {
            step.uses_variable(var_name)
        })
    });
}

Pattern 2: Stream Large Data

# BAD - store large data in variable
steps:
  - tool: fetch_large_file
    output_var: file_data  # Could be MBs

  - tool: process
    input: { data: "{{file_data}}" }

# GOOD - stream through tool
steps:
  - tool: fetch_and_process
    input: { url: "{{file_url}}" }
    # Tool streams data internally

Pattern 3: Reference Counting (Future)

use std::sync::Arc;

struct PipelineState {
    variables: HashMap<String, Arc<Value>>,
}

// Variables shared via Arc, clones are cheap
fn get_variable(&self, key: &str) -> Option<Arc<Value>> {
    self.variables.get(key).cloned()
}

State Persistence

Stateless Pipelines

Each execution starts fresh:

tools:
  - type: pipeline
    name: stateless
    steps:
      - tool: fetch
        output_var: data
      - tool: process
        input: { data: "{{data}}" }

# No state carried between invocations

Stateful Pipelines (Native Handler)

use std::sync::Arc;
use tokio::sync::RwLock;

pub struct StatefulPipeline {
    cache: Arc<RwLock<HashMap<String, Value>>>,
    pipeline: PipelineHandler,
}

impl StatefulPipeline {
    async fn handle(&self, input: Input) -> Result<Output> {
        let mut variables = input.variables;

        // Inject cached state
        {
            let cache = self.cache.read().await;
            for (k, v) in cache.iter() {
                variables.insert(k.clone(), v.clone());
            }
        }

        // Execute pipeline
        let result = self.pipeline.execute(
            PipelineInput { variables },
            &self.registry,
        ).await?;

        // Update cache with results
        {
            let mut cache = self.cache.write().await;
            for (k, v) in result.variables {
                cache.insert(k, v);
            }
        }

        Ok(result)
    }
}

Persistent State

use sled::Db;

pub struct PersistentPipeline {
    db: Db,
    pipeline: PipelineHandler,
}

impl PersistentPipeline {
    async fn handle(&self, input: Input) -> Result<Output> {
        // Load state from disk
        let mut variables = input.variables;
        for item in self.db.iter() {
            let (key, value) = item?;
            let key = String::from_utf8(key.to_vec())?;
            let value: Value = serde_json::from_slice(&value)?;
            variables.insert(key, value);
        }

        // Execute
        let result = self.pipeline.execute(
            PipelineInput { variables },
            &self.registry,
        ).await?;

        // Save state to disk
        for (key, value) in &result.variables {
            let value_bytes = serde_json::to_vec(value)?;
            self.db.insert(key.as_bytes(), value_bytes)?;
        }

        Ok(result)
    }
}

Variable Interpolation

Simple Interpolation

fn interpolate_variables(
    &self,
    template: &Value,
    variables: &HashMap<String, Value>,
) -> Value {
    match template {
        Value::String(s) => {
            let mut result = s.clone();
            for (key, value) in variables {
                let pattern = format!("{{{{{}}}}}", key);
                if let Some(value_str) = value.as_str() {
                    result = result.replace(&pattern, value_str);
                }
            }
            Value::String(result)
        }
        Value::Object(obj) => {
            let mut new_obj = serde_json::Map::new();
            for (k, v) in obj {
                new_obj.insert(k.clone(), self.interpolate_variables(v, variables));
            }
            Value::Object(new_obj)
        }
        Value::Array(arr) => {
            Value::Array(
                arr.iter()
                    .map(|v| self.interpolate_variables(v, variables))
                    .collect()
            )
        }
        other => other.clone(),
    }
}

Nested Interpolation

steps:
  - tool: get_user
    output_var: user

  - tool: get_address
    input:
      address_id: "{{user.address_id}}"  # Nested field access

Advanced State Patterns

Pattern 1: Accumulator

steps:
  - tool: fetch_page_1
    output_var: page1

  - tool: fetch_page_2
    output_var: page2

  - tool: merge_pages
    input:
      pages: ["{{page1}}", "{{page2}}"]
    output_var: all_data

Pattern 2: State Machine

enum PipelineState {
    Init,
    Fetching,
    Processing,
    Complete,
}

async fn stateful_pipeline(&self, input: Input) -> Result<Output> {
    let mut state = PipelineState::Init;
    let mut variables = input.variables;

    loop {
        state = match state {
            PipelineState::Init => {
                // Initialize
                PipelineState::Fetching
            }
            PipelineState::Fetching => {
                let data = fetch_data().await?;
                variables.insert("data".to_string(), data);
                PipelineState::Processing
            }
            PipelineState::Processing => {
                process_data(&variables).await?;
                PipelineState::Complete
            }
            PipelineState::Complete => break,
        }
    }

    Ok(Output { variables })
}

Pattern 3: Checkpoint/Resume

#[derive(Serialize, Deserialize)]
struct Checkpoint {
    step_index: usize,
    variables: HashMap<String, Value>,
}

async fn resumable_pipeline(
    &self,
    input: Input,
    checkpoint: Option<Checkpoint>,
) -> Result<(Output, Checkpoint)> {
    let start_step = checkpoint.as_ref().map(|c| c.step_index).unwrap_or(0);
    let mut variables = checkpoint
        .map(|c| c.variables)
        .unwrap_or(input.variables);

    for (i, step) in self.steps.iter().enumerate().skip(start_step) {
        let result = self.execute_step(step, &variables).await?;

        if let Some(var) = &step.output_var {
            variables.insert(var.clone(), result);
        }

        // Save checkpoint after each step
        let checkpoint = Checkpoint {
            step_index: i + 1,
            variables: variables.clone(),
        };
        save_checkpoint(&checkpoint)?;
    }

    Ok((Output { variables: variables.clone() }, Checkpoint {
        step_index: self.steps.len(),
        variables,
    }))
}

Testing State Management

Test Variable Persistence

#[tokio::test]
async fn test_variable_persistence() {
    let pipeline = PipelineHandler::new(vec![
        PipelineStep {
            tool: "step1".to_string(),
            output_var: Some("var1".to_string()),
            ..Default::default()
        },
        PipelineStep {
            tool: "step2".to_string(),
            output_var: Some("var2".to_string()),
            ..Default::default()
        },
    ]);

    let result = pipeline.execute(
        PipelineInput { variables: HashMap::new() },
        &registry,
    ).await.unwrap();

    assert!(result.variables.contains_key("var1"));
    assert!(result.variables.contains_key("var2"));
}

Test Memory Usage

#[tokio::test]
async fn test_memory_optimization() {
    let large_data = vec![0u8; 1_000_000];  // 1MB

    let pipeline = PipelineHandler::new(vec![
        PipelineStep {
            tool: "create_large".to_string(),
            output_var: Some("large".to_string()),
            ..Default::default()
        },
        PipelineStep {
            tool: "process".to_string(),
            input: Some(json!({"data": "{{large}}"})),
            ..Default::default()
        },
    ]);

    let initial_memory = get_memory_usage();

    let _result = pipeline.execute(
        PipelineInput { variables: HashMap::new() },
        &registry,
    ).await.unwrap();

    let final_memory = get_memory_usage();
    let leaked = final_memory - initial_memory;

    assert!(leaked < 100_000);  // Less than 100KB leaked
}

Best Practices

1. Minimize State

# Keep only necessary variables
output_var: result  # Not: output_var: intermediate_step_23_result

2. Clear Variable Names

# BAD
output_var: d

# GOOD
output_var: validated_user_data

3. Document State Flow

steps:
  # Fetch raw data
  - tool: fetch
    output_var: raw

  # Transform (raw -> processed)
  - tool: transform
    input: { data: "{{raw}}" }
    output_var: processed

  # Store (processed only)
  - tool: store
    input: { data: "{{processed}}" }

Conclusion

You’ve completed the handler type chapters! You now understand:

• CLI Handlers: Wrapping shell commands with streaming
• HTTP Handlers: Proxying REST APIs with authentication
• Pipeline Handlers: Composing tools with state management

These three handler types, combined with Native handlers, provide the full toolkit for building MCP servers with pforge.

“State is memory. Manage it wisely.” - pforge state management principle

The 5-Minute TDD Cycle

Test-Driven Development (TDD) is often taught as a philosophy but rarely enforced as a discipline. In pforge, we take a different approach: EXTREME TDD with strict time-boxing derived from Toyota Production System principles.

Why 5 Minutes?

The 5-minute cycle isn’t arbitrary. It’s rooted in manufacturing psychology and cognitive science:

Immediate Feedback: Humans excel at tasks with tight feedback loops. A 5-minute cycle means you discover mistakes within minutes, not hours or days. The cost of fixing a bug grows exponentially with time—a defect found in 5 minutes costs virtually nothing to fix; one found in production can cost 100x more.

Flow State Prevention: Counter-intuitively, preventing deep “flow states” in TDD improves overall quality. Flow states encourage big changes without tests, accumulating technical debt. Short cycles force frequent integration and testing.

Cognitive Load Management: Working memory holds ~7 items for ~20 seconds (Miller, 1956). A 5-minute cycle keeps changes small enough to fit in working memory, reducing errors and improving code comprehension.

Jidoka (“Stop the Line”): Borrowed from Toyota’s production system, if quality gates fail, you stop immediately. No pushing forward with broken tests or failing builds. This prevents defects from propagating downstream.

The Sacred 5-Minute Timer

Before starting any TDD cycle, set a physical timer for 5 minutes:

# Start your cycle
timer 5m  # Use any timer tool

If the timer expires before you reach COMMIT, you must RESET: discard all changes and start over. No exceptions.

This discipline seems harsh, but it’s transformative:

• Forces small changes: You learn to break work into tiny increments
• Eliminates waste: No time spent debugging large, complex changes
• Builds skill: You develop pattern recognition for estimating change complexity
• Maintains quality: Every commit passes all quality gates

The Four Phases

The 5-minute cycle consists of four strictly time-boxed phases:

1. RED (0:00-2:00) — Write Failing Test

Maximum time: 2 minutes

Write a single failing test that specifies the next small increment of behavior. The test must:

• Compile (if applicable)
• Run and fail for the right reason
• Be small and focused

If you can’t write a failing test in 2 minutes, your increment is too large. Break it down further.

2. GREEN (2:00-4:00) — Minimum Code to Pass

Maximum time: 2 minutes

Write the absolute minimum code to make the test pass. Do not:

• Add extra features
• Refactor existing code
• Optimize prematurely
• Write documentation

Just make the test green. Hard-coding the return value is acceptable at this stage.

3. REFACTOR (4:00-5:00) — Clean Up

Maximum time: 1 minute

With tests passing, improve code quality:

• Extract duplication
• Improve names
• Simplify logic
• Ensure tests still pass

This is fast refactoring—obvious improvements only. Deep refactoring requires its own cycle.

4. COMMIT or RESET (5:00)

At the 5-minute mark, exactly two outcomes:

COMMIT: All quality gates pass → commit immediately RESET: Any gate fails or timer expired → discard all changes, start over

No third option. No “just one more minute.” This is the discipline that ensures quality.

Time Budget Breakdown

The time allocation reflects priorities:

RED:      2 minutes (40%) - Specification
GREEN:    2 minutes (40%) - Implementation
REFACTOR: 1 minute  (20%) - Quality
COMMIT:   instant        - Validation

Notice that specification and implementation get equal time. This reflects TDD’s philosophy: tests are not an afterthought but co-equal with production code.

The 1-minute refactor limit enforces the rule: “refactor constantly in small steps” rather than “big refactoring sessions.”

Practical Timer Management

Setup Your Environment

# Install a timer tool (example: termdown)
cargo install termdown

# Alias for quick access
alias tdd='termdown 5m && cargo test --lib --quiet'

Timer Discipline

Start the timer BEFORE writing any code:

# WRONG - code first, timer second
vim src/handlers/calculate.rs
termdown 5m

# RIGHT - timer first, establishes commitment
termdown 5m &
vim src/handlers/calculate.rs

When the timer rings:

1. Stop typing immediately — Mid-keystroke if necessary
2. Run quality gates — make quality-gate
3. COMMIT or RESET — No middle ground

Visual Cues

Many developers use physical timers for stronger psychological impact:

• Kitchen timer on desk (audible, visible)
• Pomodoro timer app (desktop notification)
• Smart watch timer (wrist vibration)

The key is making the timer unavoidable.

Example: Complete 5-Minute Cycle

Let’s walk through a real pforge TDD cycle implementing a divide tool for a calculator server.

Minute 0:00 - Start Timer, Begin RED

# Start 5-minute timer
termdown 5m &

# Create test file
vim crates/pforge-runtime/tests/unit/handlers/calculator_test.rs

Minute 0:30 - Write Failing Test

#[tokio::test]
async fn test_divide_returns_quotient() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 2.0
    };

    let result = handler.handle(input).await;

    assert!(result.is_ok());
    let output = result.unwrap();
    assert_eq!(output.quotient, 5.0);
}

Minute 1:00 - Test Fails (Compilation Error)

cargo test --lib test_divide_returns_quotient
# Error: cannot find struct `DivideHandler` in this scope

Good! We’re RED for the right reason.

Minute 2:00 - Begin GREEN Phase

Create handler skeleton:

// src/handlers/calculator.rs

#[derive(Debug, Deserialize, JsonSchema)]
pub struct DivideInput {
    pub numerator: f64,
    pub denominator: f64,
}

#[derive(Debug, Serialize, JsonSchema)]
pub struct DivideOutput {
    pub quotient: f64,
}

pub struct DivideHandler;

#[async_trait::async_trait]
impl Handler for DivideHandler {
    type Input = DivideInput;
    type Output = DivideOutput;
    type Error = Error;

    async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
        Ok(DivideOutput {
            quotient: input.numerator / input.denominator,
        })
    }
}

Minute 3:30 - Test Passes

cargo test --lib test_divide_returns_quotient
# test test_divide_returns_quotient ... ok

GREEN! We’re ahead of schedule.

Minute 4:00 - REFACTOR Phase

Extract magic number, improve naming:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let quotient = input.numerator / input.denominator;
    Ok(DivideOutput { quotient })
}

Re-run tests:

cargo test --lib test_divide_returns_quotient
# test test_divide_returns_quotient ... ok

Minute 4:50 - COMMIT Decision

make quality-gate
# ✓ cargo fmt --check
# ✓ cargo clippy -- -D warnings
# ✓ cargo test --all
# ✓ pmat analyze complexity --max 20
# ✓ pmat analyze satd --max 0
# All gates passed!

Minute 5:00 - COMMIT

git add crates/pforge-runtime/src/handlers/calculator.rs \
        crates/pforge-runtime/tests/unit/handlers/calculator_test.rs

git commit -m "feat: add divide operation to calculator

Implements basic division with f64 precision.

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

Cycle complete in 5:00. Next cycle can address division-by-zero error handling.

What RESET Looks Like

Now let’s see a failed cycle that requires RESET.

Minute 0:00 - Start Timer

termdown 5m &

Minute 0:30 - Write Test (Too Ambitious)

#[tokio::test]
async fn test_advanced_statistics() {
    let handler = StatsHandler;
    let input = StatsInput {
        data: vec![1.0, 2.0, 3.0, 4.0, 5.0],
        compute_mean: true,
        compute_median: true,
        compute_mode: true,
        compute_stddev: true,
        compute_variance: true,
        compute_quartiles: true,
    };

    let result = handler.handle(input).await;
    // ... many assertions
}

Minute 2:30 - Still Writing Implementation

pub async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let mean = if input.compute_mean {
        Some(calculate_mean(&input.data))
    } else {
        None
    };

    let median = if input.compute_median {
        // ... still implementing

Minute 5:00 - Timer Expires

STOP.

The timer has expired. Tests are not passing. Quality gates haven’t run.

RESET Protocol

# Discard all changes
git checkout .
git clean -fd

# Reflect: Why did this fail?
# Answer: Tried to implement 6 features in one cycle
# Solution: Break into 6 separate cycles, one per statistic

This RESET just saved you from:

• Accumulating technical debt
• Complex debugging sessions
• Merge conflicts
• Poor design choices made under time pressure

The Psychology of RESET

RESET feels painful initially. You’ve written code and must delete it. But this pain is a teaching mechanism:

Immediate Consequence: Breaking discipline has an immediate, visible cost. You learn quickly what scope fits in 5 minutes.

Sunk Cost Avoidance: By discarding quickly, you avoid the sunk cost fallacy (“I’ve already invested 10 minutes, I’ll just finish”). This fallacy leads to sprawling commits.

Pattern Recognition: After several RESETs, you develop intuition for 5-minute scopes. You can estimate, “This will take 3 cycles” with accuracy.

Perfectionism Antidote: RESET teaches that code is disposable. The first attempt doesn’t need to be perfect—it just needs to teach you the right approach.

Measuring Cycle Performance

Track your cycle outcomes to improve:

# .tdd-log (simple text file)
2024-01-15 09:00 COMMIT divide_basic (4:30)
2024-01-15 09:06 RESET  statistics_all (5:00+)
2024-01-15 09:12 COMMIT divide_by_zero_check (3:45)
2024-01-15 09:18 COMMIT mean_calculation (4:10)

Over time, you’ll notice:

• Cycles complete faster (pattern recognition improves)
• RESETs decrease (scoping improves)
• Quality gates pass more consistently (habits form)

Common Pitfalls

Pitfall 1: “Just One More Second”

Symptom: Timer expires at 5:00, you think “I’m so close, just 30 more seconds.”

Why it’s dangerous: These “30 seconds” compound. Soon you’re running 7-minute cycles, then 10-minute, then abandoning time-boxing entirely.

Solution: Set a hard rule: “Timer expires = RESET, no exceptions for 30 days.” After 30 days, the habit is internalized.

Pitfall 2: Pausing the Timer

Symptom: Interruption occurs (Slack message, phone call). You pause the timer.

Why it’s dangerous: The 5-minute limit creates psychological pressure that improves focus. Pausing eliminates this pressure.

Solution: If interrupted, RESET the cycle after handling the interruption. Interruptions are context switches; your mental model is stale.

Pitfall 3: Skipping REFACTOR

Symptom: Test passes at 3:30. You immediately commit without refactoring.

Why it’s dangerous: Skipping refactoring accumulates cruft. After 100 cycles, your codebase is a mess.

Solution: Always use the remaining time to refactor. If test passes at 3:30, you have 1:30 to improve code. Use it.

Pitfall 4: Testing Timer Before Starting

Symptom: You outline your approach for 5 minutes, then start the timer before writing tests.

Why it’s dangerous: The planning time doesn’t count, so you’re actually running 10-minute cycles.

Solution: Timer starts when you open your editor. All planning happens within the 5-minute window (RED phase specifically).

Integration with pforge Workflow

pforge provides built-in support for EXTREME TDD:

Watch Mode with Timer

# Continuous testing with integrated timer
make dev

This runs:

1. Start 5-minute timer
2. Watch for file changes
3. Run tests automatically
4. Run quality gates
5. Display COMMIT/RESET recommendation

Quality Gate Integration

# Fast quality check (< 10 seconds)
make quality-gate-fast

Runs only the critical gates:

• Compile check
• Clippy lints
• Unit tests (not integration)

This gives quick feedback within the 5-minute window.

Pre-Commit Hook

pforge installs a pre-commit hook that:

1. Runs full quality gates
2. Blocks commit if any fail
3. Ensures every commit meets standards

You never accidentally commit broken code.

Advanced: Distributed TDD

For pair programming or mob programming, synchronize timers:

# All developers run
tmux-clock-mode 5m

When anyone’s timer expires:

• Stop typing immediately
• Discuss COMMIT or RESET
• Start next cycle together

This creates shared cadence and mutual accountability.

Theoretical Foundation

pforge’s EXTREME TDD combines:

1. Beck’s TDD (2003): RED-GREEN-REFACTOR cycle
2. Toyota Production System: Jidoka (stop the line), Kaizen (continuous improvement)
3. Lean Software Development (Poppendieck & Poppendieck, 2003): Eliminate waste, amplify learning
4. Pomodoro Technique (Cirillo, 2006): Time-boxing for focus

The 5-minute window is shorter than a Pomodoro (25 min) because code changes compound faster than other work. A bug introduced at minute 5 is harder to debug at minute 25.

Benefits After 30 Days

Developers who strictly follow 5-minute TDD for 30 days report:

• 50% reduction in debugging time: Small cycles mean small bugs
• 80% increase in test coverage: Testing is automatic, not optional
• 90% reduction in production bugs: Quality gates catch issues early
• Subjective improvement in code quality: Constant refactoring prevents cruft
• Reduced stress: Frequent commits create safety net

The first week is hard. The second week, muscle memory forms. By week four, it feels natural.

Next Steps

Now that you understand the 5-minute cycle philosophy, let’s dive into each phase:

• RED Phase: How to write effective failing tests in 2 minutes
• GREEN Phase: Techniques for minimal, correct implementations
• REFACTOR Phase: Quick refactoring patterns that fit in 1 minute
• COMMIT Phase: Quality gate integration and decision criteria

Each subsequent chapter provides detailed techniques for maximizing each phase.

Next: RED: Write Failing Test

RED: Write Failing Test

The RED phase is where you define what success looks like before writing any production code. You have exactly 2 minutes to write a failing test that clearly specifies the next increment of behavior.

The Purpose of RED

RED is about specification, not testing. The test you write answers the question: “What should the next tiny piece of functionality do?”

Why Tests Come First

Design Pressure: Writing tests first forces you to think from the caller’s perspective. You design interfaces that are pleasant to use, not convenient to implement.

Clear Goal: Before writing implementation, you have a concrete, executable definition of “done.” The test passes = you’re finished.

Prevents Scope Creep: Writing tests first forces you to commit to a small scope before getting distracted by implementation details.

Living Documentation: Tests document intent better than comments. Comments lie; tests are executable and must stay accurate.

The 2-Minute Budget

Two minutes to write a test feels tight. It is. This constraint forces several good practices:

Small Increments: If you can’t write a test in 2 minutes, your increment is too large. Break it down.

Test Template Reuse: You’ll develop a library of test patterns that you can copy and adapt quickly.

No Overthinking: Two minutes prevents analysis paralysis. Write the simplest test that fails for the right reason.

Anatomy of a Good RED Test

A good RED test has three characteristics:

1. Compiles (If Possible)

In typed languages like Rust, the test should compile even if types don’t exist yet. Use comments or temporary stubs:

// COMPILES - Types exist
#[tokio::test]
async fn test_greet_returns_greeting() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "Alice".to_string(),
    };

    let result = handler.handle(input).await;

    assert!(result.is_ok());
}

If types don’t exist:

// DOESN'T COMPILE YET - Types will be created in GREEN
#[tokio::test]
async fn test_divide_handles_zero() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 0.0,
    };

    let result = handler.handle(input).await;

    assert!(result.is_err());
    // Will be: Error::Validation("Division by zero")
}

Both are valid RED tests. The first runs and fails (returns wrong value). The second doesn’t compile (types missing). Either way, you’re RED.

2. Fails for the Right Reason

The test must fail because the feature doesn’t exist, not because of typos or wrong imports:

// GOOD - Fails because feature missing
#[tokio::test]
async fn test_calculate_mean() {
    let handler = StatisticsHandler;
    let input = StatsInput {
        data: vec![1.0, 2.0, 3.0, 4.0, 5.0],
    };

    let result = handler.handle(input).await.unwrap();

    assert_eq!(result.mean, 3.0);
}
// Fails: field `mean` does not exist in `StatsOutput`

// BAD - Fails because of typo
#[tokio::test]
async fn test_calculate_mean() {
    let handler = StatisticsHander;  // typo!
    // ...
}
// Fails: cannot find struct `StatisticsHander`

Run your test immediately after writing it to verify it fails correctly.

3. Tests One Thing

Each test should verify one specific behavior:

// GOOD - One behavior
#[tokio::test]
async fn test_divide_returns_quotient() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 2.0,
    };

    let result = handler.handle(input).await.unwrap();

    assert_eq!(result.quotient, 5.0);
}

// GOOD - Different behavior, separate test
#[tokio::test]
async fn test_divide_rejects_zero_denominator() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 0.0,
    };

    let result = handler.handle(input).await;

    assert!(result.is_err());
}

// BAD - Multiple behaviors in one test
#[tokio::test]
async fn test_divide_everything() {
    // Tests division
    let result1 = handler.handle(DivideInput { ... }).await.unwrap();
    assert_eq!(result1.quotient, 5.0);

    // Tests zero handling
    let result2 = handler.handle(DivideInput { denominator: 0.0, ... }).await;
    assert!(result2.is_err());

    // Tests negative numbers
    let result3 = handler.handle(DivideInput { numerator: -10.0, ... }).await.unwrap();
    assert_eq!(result3.quotient, -5.0);
}

Multiple assertions are fine if they verify the same behavior. Multiple behaviors require separate tests.

Test Naming Conventions

Test names should read as specifications:

// GOOD - Reads as specification
test_greet_returns_personalized_message()
test_divide_rejects_zero_denominator()
test_statistics_calculates_mean_correctly()
test_file_read_handles_missing_file()
test_http_call_retries_on_timeout()

// BAD - Vague or implementation-focused
test_greet()
test_division()
test_math_works()
test_error_case()
test_function_1()

Pattern: test_<subject>_<behavior>_<condition>

Examples:

• test_calculator_adds_positive_numbers
• test_file_handler_creates_missing_directory
• test_api_client_refreshes_expired_token

Quick Test Templates for pforge

Handler Happy Path Template

#[tokio::test]
async fn test_HANDLER_NAME_returns_OUTPUT() {
    let handler = HandlerStruct;
    let input = InputStruct {
        field: value,
    };

    let result = handler.handle(input).await;

    assert!(result.is_ok());
    let output = result.unwrap();
    assert_eq!(output.field, expected_value);
}

Handler Error Case Template

#[tokio::test]
async fn test_HANDLER_NAME_rejects_INVALID_INPUT() {
    let handler = HandlerStruct;
    let input = InputStruct {
        field: invalid_value,
    };

    let result = handler.handle(input).await;

    assert!(result.is_err());
    match result.unwrap_err() {
        Error::Validation(msg) => assert!(msg.contains("expected error substring")),
        _ => panic!("Wrong error type"),
    }
}

Handler Async Operation Template

#[tokio::test]
async fn test_HANDLER_NAME_completes_within_timeout() {
    let handler = HandlerStruct;
    let input = InputStruct { /* ... */ };

    let timeout_duration = std::time::Duration::from_secs(5);

    let result = tokio::time::timeout(
        timeout_duration,
        handler.handle(input)
    ).await;

    assert!(result.is_ok(), "Handler timed out");
    assert!(result.unwrap().is_ok());
}

Copy these templates, replace the placeholders, and you have a test in under 2 minutes.

The RED Checklist

Before moving to GREEN, verify:

• Test compiles OR fails to compile for the right reason (missing types)
• Test runs and fails OR doesn’t compile
• Test name clearly describes the behavior being specified
• Test is focused on one specific behavior
• Timer shows less than 2:00 minutes elapsed

If any item is unchecked, refine the test. If the timer exceeds 2:00, RESET.

Common RED Phase Mistakes

Mistake 1: Testing Too Much at Once

// BAD - Too much for one test
#[tokio::test]
async fn test_calculator_all_operations() {
    // Addition
    assert_eq!(calc.add(2, 3).await.unwrap(), 5);

    // Subtraction
    assert_eq!(calc.subtract(5, 3).await.unwrap(), 2);

    // Multiplication
    assert_eq!(calc.multiply(2, 3).await.unwrap(), 6);

    // Division
    assert_eq!(calc.divide(6, 3).await.unwrap(), 2);
}

Why it’s bad: If this test fails, you don’t know which operation broke. Also, implementing all four operations takes more than 2 minutes (GREEN phase).

Fix: One test per operation.

Mistake 2: Testing Implementation Details

// BAD - Tests internal structure
#[tokio::test]
async fn test_handler_uses_hashmap_internally() {
    let handler = CacheHandler::new();
    // Somehow peek into internals
    assert!(handler.storage.is_hashmap());
}

Why it’s bad: Tests should verify behavior, not implementation. If you refactor from HashMap to BTreeMap, this test breaks even though behavior is unchanged.

Fix: Test observable behavior only.

// GOOD - Tests behavior
#[tokio::test]
async fn test_cache_retrieves_stored_value() {
    let handler = CacheHandler::new();

    handler.store("key", "value").await.unwrap();
    let result = handler.retrieve("key").await.unwrap();

    assert_eq!(result, "value");
}

Mistake 3: Complex Test Setup

// BAD - Setup takes too long
#[tokio::test]
async fn test_user_registration() {
    // Too much setup
    let db = setup_test_database().await;
    let email_service = MockEmailService::new();
    let password_hasher = Argon2::default();
    let config = load_test_config("config.yaml");
    let logger = setup_test_logger();
    let handler = RegistrationHandler::new(db, email_service, password_hasher, config, logger);

    // Test starts here...
}

Why it’s bad: You’ve exceeded 2 minutes just on setup. The test hasn’t even run yet.

Fix: Extract setup to a helper function or use test fixtures:

// GOOD - Fast setup
#[tokio::test]
async fn test_user_registration() {
    let handler = create_test_registration_handler().await;

    let input = RegistrationInput {
        email: "test@example.com".to_string(),
        password: "securepass123".to_string(),
    };

    let result = handler.handle(input).await;

    assert!(result.is_ok());
}

// Helper function defined once, reused many times
async fn create_test_registration_handler() -> RegistrationHandler {
    let db = setup_test_database().await;
    let email_service = MockEmailService::new();
    // ... etc
    RegistrationHandler::new(db, email_service, /* ... */)
}

Mistake 4: Not Running the Test

Symptom: You write a test, assume it fails correctly, and move to GREEN.

Why it’s bad: The test might already pass (making it useless), or fail for the wrong reason (typo, wrong import).

Fix: Always run the test immediately and verify the failure message:

# After writing test
cargo test test_divide_returns_quotient
# Expected: Test failed (function not implemented)
# If: Test passed → test is useless
# If: Test failed (wrong reason) → fix test first

Advanced RED Techniques

Outside-In TDD

Start with high-level behavior, let tests drive lower-level design:

// Minute 0:00 - High-level test
#[tokio::test]
async fn test_api_returns_user_profile() {
    let api = UserAPI::new();

    let result = api.get_profile("user123").await;

    assert!(result.is_ok());
    let profile = result.unwrap();
    assert_eq!(profile.username, "alice");
}

This test will drive the creation of:

• UserAPI struct
• get_profile method
• Profile struct
• Database layer (in later cycles)

Property-Based Testing Hint

For complex logic, use RED to specify properties:

// Standard example-based test
#[tokio::test]
async fn test_sort_orders_numbers() {
    let input = vec![3, 1, 4, 1, 5];
    let result = sort(input).await;
    assert_eq!(result, vec![1, 1, 3, 4, 5]);
}

// Property-based test (RED phase)
#[tokio::test]
async fn test_sort_maintains_length() {
    use proptest::prelude::*;

    proptest!(|(numbers: Vec<i32>)| {
        let sorted = sort(numbers.clone()).await;
        prop_assert_eq!(sorted.len(), numbers.len());
    });
}

Property tests specify invariants rather than specific examples.

Test-Driven Error Messages

Write the test with the error message you want users to see:

#[tokio::test]
async fn test_divide_provides_helpful_error_message() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 0.0,
    };

    let result = handler.handle(input).await;

    assert!(result.is_err());
    let error = result.unwrap_err();
    let message = format!("{}", error);

    // Specify the exact error message you want
    assert!(message.contains("Division by zero"));
    assert!(message.contains("denominator must be non-zero"));
}

This drives you to write good error messages, not generic “An error occurred.”

Integration with pforge Watch Mode

Run tests continuously during RED phase:

# Terminal 1: Start watch mode
cargo watch -x 'test test_divide_returns_quotient --lib'

# Terminal 2: Edit test
vim crates/pforge-runtime/tests/unit/calculator_test.rs

Watch mode gives instant feedback. Save the file, see the failure, confirm it’s RED for the right reason.

RED Phase Workflow Summary

1. Start timer (5-minute cycle begins)
2. Open test file (under 10 seconds)
3. Copy test template (under 20 seconds)
4. Fill in specifics (under 60 seconds)
5. Run test (under 10 seconds)
6. Verify failure (under 20 seconds)
7. Total: ~2 minutes

With practice, you’ll complete RED in 90 seconds consistently, giving extra time for GREEN and REFACTOR.

Example: RED Phase Executed Correctly

Let’s implement a clamp function that constrains a value between min and max.

Minute 0:00 - Start Timer

termdown 5m &
vim crates/pforge-runtime/src/lib.rs

Minute 0:10 - Decide on Test

Feature: Clamp function for numbers Test: Value below min returns min

Minute 0:20 - Open Test File

vim crates/pforge-runtime/tests/unit/math_test.rs

Minute 0:30 - Write Test

#[test]
fn test_clamp_returns_min_when_below_range() {
    let result = clamp(5, 10, 20);
    assert_eq!(result, 10);
}

Minute 0:50 - Run Test

cargo test test_clamp_returns_min_when_below_range

Output:

error: cannot find function `clamp` in this scope

Minute 1:00 - Verify RED

Perfect! Test fails because function doesn’t exist. This is the right failure.

Minute 1:10 - Document in Test

#[test]
fn test_clamp_returns_min_when_below_range() {
    // clamp(value, min, max) constrains value to [min, max]
    let result = clamp(5, 10, 20);
    assert_eq!(result, 10);
}

Minute 2:00 - RED Phase Complete

We have:

• ✅ Test written
• ✅ Test fails for right reason
• ✅ Behavior clearly specified
• ✅ Under 2-minute budget

Time to move to GREEN.

When RED Takes Longer Than 2 Minutes

If you hit 2:00 and the test isn’t ready, you have two options:

Option 1: Finish Quickly (If < 30 Seconds Remaining)

If you’re truly close (just need to add assertions), finish quickly:

// 1:50 elapsed, just need to add:
assert_eq!(result.value, expected);
// Total: 2:05 - acceptable

Minor overruns (< 15 seconds) are acceptable if test is complete and verified RED.

Option 2: RESET (If Significantly Over)

If you’re at 2:30 and still writing the test, RESET:

git checkout .

Reflect: Why did RED take so long?

• Test setup too complex → Need helper function
• Testing too much → Break into smaller tests
• Unclear what to test → Spend 1 minute planning before next cycle

RED Phase Success Metrics

Track these metrics to improve:

Time to RED: Average time to write failing test

• Target: < 2:00
• Excellent: < 1:30
• Expert: < 1:00

RED Failure Rate: Tests that fail for wrong reason

• Target: < 10%
• Excellent: < 5%
• Expert: < 1%

RED Rewrites: Tests rewritten during same cycle

• Target: < 20%
• Excellent: < 10%
• Expert: < 5%

Psychological Benefits of RED First

Confidence: You know what you’re building before you start.

Clarity: The test clarifies vague requirements into concrete behavior.

Progress: Each RED test is a small, achievable goal.

Safety Net: Tests catch regressions as you refactor later.

Documentation: Future developers understand intent from tests.

Next Phase: GREEN

You’ve written a failing test that specifies behavior. Now it’s time to make it pass with the minimum code necessary.

The GREEN phase has one goal: get from RED to GREEN as fast as possible, even if the implementation is ugly. We’ll clean it up in REFACTOR.

Previous: The 5-Minute TDD Cycle Next: GREEN: Minimum Code

GREEN: Minimum Code

The GREEN phase has one singular goal: make the test pass using the absolute minimum code necessary. You have 2 minutes. Nothing else matters—not elegance, not performance, not extensibility. Just make it GREEN.

The Minimum Code Principle

“Minimum code” doesn’t mean “bad code” or “throw quality out the window.” It means the simplest implementation that satisfies the test specification.

What Minimum Means

Minimum means:

• No extra features beyond what the test requires
• No “just in case” code
• No premature optimization
• No architectural patterns unless necessary
• Hard-coded values are acceptable if they make the test pass

Minimum does NOT mean:

• Skipping error handling required by the test
• Using unwrap() instead of proper error propagation
• Introducing compiler warnings
• Violating Rust safety rules

Why Minimum First?

Speed: Get to GREEN fast. Every second you spend on cleverness is a second not spent on the next feature.

Correctness: Simple implementations are easier to verify. You can see at a glance if they match the test.

Deferral: Complex design emerges from refactoring multiple simple implementations, not from upfront architecture.

Safety Net: Once tests pass, you have a safety net for refactoring. You can make it better without fear of breaking it.

The 2-Minute GREEN Budget

Two minutes to implement and verify:

• 0:00-1:30: Write implementation
• 1:30-1:50: Run test
• 1:50-2:00: Verify GREEN (all tests pass)

If the test doesn’t pass by 2:00, you have 3 more minutes (until 5:00) to either fix it or RESET.

Example: GREEN Phase Walkthrough

Continuing from our RED phase clamp function example:

Minute 2:00 - Begin GREEN Phase

We have a failing test:

#[test]
fn test_clamp_returns_min_when_below_range() {
    let result = clamp(5, 10, 20);
    assert_eq!(result, 10);
}

Error: cannot find function 'clamp' in this scope

Minute 2:10 - Write Minimal Implementation

// src/lib.rs
pub fn clamp(value: i32, min: i32, max: i32) -> i32 {
    if value < min {
        return min;
    }
    value  // Return value for now
}

Why this is minimum:

• Only handles the case tested (value < min)
• Doesn’t handle value > max (not tested yet)
• Doesn’t handle value in range perfectly (but passes test)

Minute 3:45 - Run Test

cargo test test_clamp_returns_min_when_below_range

Output:

test test_clamp_returns_min_when_below_range ... ok

GREEN! Test passes.

Minute 4:00 - Enter REFACTOR Phase

We’re GREEN ahead of schedule. Now we can refactor.

Hard-Coding Is Acceptable

One of TDD’s most controversial practices: hard-coding return values is acceptable in GREEN.

The Hard-Coding Example

// RED: Test expects specific output
#[tokio::test]
async fn test_greet_returns_hello_world() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "World".to_string(),
    };

    let result = handler.handle(input).await.unwrap();

    assert_eq!(result.message, "Hello, World!");
}

// GREEN: Hard-coded return value
#[async_trait::async_trait]
impl Handler for GreetHandler {
    type Input = GreetInput;
    type Output = GreetOutput;
    type Error = Error;

    async fn handle(&self, _input: Self::Input) -> Result<Self::Output> {
        Ok(GreetOutput {
            message: "Hello, World!".to_string(),
        })
    }
}

This makes the test pass. It’s valid GREEN code.

Why Hard-Coding Is Acceptable

Proves the test works: If the hard-coded value makes the test pass, you know the test verifies behavior correctly.

Forces more tests: The hard-coded implementation is obviously incomplete. You must write more tests to drive out the real logic.

Defers complexity: You don’t jump to complex string interpolation until tests demand it.

When to Use Real Implementation

As soon as you write a second test that requires different behavior, hard-coding stops working:

// Second test
#[tokio::test]
async fn test_greet_returns_personalized_greeting() {
    let handler = GreetHandler;
    let input = GreetInput {
        name: "Alice".to_string(),
    };

    let result = handler.handle(input).await.unwrap();

    assert_eq!(result.message, "Hello, Alice!");
}

Now the hard-coded implementation fails. Time for real logic:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(GreetOutput {
        message: format!("Hello, {}!", input.name),
    })
}

This is the rule of three: Hard-code for one test, use real logic after two tests require different behavior.

Minimum Implementation Patterns

Pattern 1: Return Literal

Simplest possible—return a literal value:

// Test expects specific value
async fn handle(&self, _input: Self::Input) -> Result<Self::Output> {
    Ok(GreetOutput {
        message: "Hello, World!".to_string(),
    })
}

When to use: First test for a handler, specific expected value.

Pattern 2: Pass Through Input

Return input directly or with minimal transformation:

// Test expects input echoed back
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(EchoOutput {
        message: input.message,
    })
}

When to use: Echo, copy, or identity operations.

Pattern 3: Conditional

Single if-statement for simple branching:

// Test expects validation
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.age < 0 {
        return Err(Error::Validation("Age cannot be negative".to_string()));
    }

    Ok(AgeOutput {
        category: "adult".to_string(),  // Hard-coded for now
    })
}

When to use: Validation, error cases, simple branching.

Pattern 4: Simple Calculation

Direct calculation without helper functions:

// Test expects arithmetic
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(AddOutput {
        sum: input.a + input.b,
    })
}

When to use: Arithmetic, string formatting, basic transformations.

Pattern 5: Delegation

Call existing function or library:

// Test expects file reading
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let contents = tokio::fs::read_to_string(&input.path).await
        .map_err(|e| Error::Handler(e.to_string()))?;

    Ok(ReadOutput { contents })
}

When to use: File I/O, HTTP requests, database queries (real or mocked).

Common GREEN Phase Mistakes

Mistake 1: Over-Engineering

// BAD - Too complex for first test
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Generic calculation engine
    let calculator = CalculatorBuilder::new()
        .with_operator(input.operator.parse()?)
        .with_precision(input.precision.unwrap_or(2))
        .with_rounding_mode(RoundingMode::HalfUp)
        .build()?;

    let result = calculator.compute(input.operands)?;

    Ok(CalculatorOutput { result })
}

Why it’s bad: You’ve written 20 lines of infrastructure for a test that just needs 2 + 2 = 4.

Fix: Start simple, add complexity when tests demand it:

// GOOD - Minimal for first test
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(CalculatorOutput {
        result: input.a + input.b,
    })
}

When you need multiplication, add it:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let result = match input.operator.as_str() {
        "+" => input.a + input.b,
        "*" => input.a * input.b,
        _ => return Err(Error::Validation("Unknown operator".to_string())),
    };

    Ok(CalculatorOutput { result })
}

Mistake 2: Premature Optimization

// BAD - Optimizing before necessary
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Pre-allocate with capacity
    let mut results = Vec::with_capacity(input.items.len());

    // Parallel processing
    let handles: Vec<_> = input.items
        .into_iter()
        .map(|item| tokio::spawn(async move { process(item) }))
        .collect();

    for handle in handles {
        results.push(handle.await??);
    }

    Ok(Output { results })
}

Why it’s bad: You’re optimizing before knowing if there’s a performance problem. This adds complexity and time.

Fix: Start sequential, optimize when benchmarks show a problem:

// GOOD - Simple sequential processing
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let mut results = Vec::new();

    for item in input.items {
        results.push(process(item).await?);
    }

    Ok(Output { results })
}

Mistake 3: Adding Untested Features

// BAD - Features not required by test
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Test only requires division
    let quotient = input.numerator / input.denominator;

    // But we're also adding:
    let remainder = input.numerator % input.denominator;
    let is_exact = remainder == 0.0;
    let sign = if quotient < 0.0 { -1 } else { 1 };

    Ok(DivideOutput {
        quotient,
        remainder,      // Not tested
        is_exact,       // Not tested
        sign,           // Not tested
    })
}

Why it’s bad: Untested code is unverified code. It might have bugs. It definitely wastes time.

Fix: Only implement what tests require:

// GOOD - Only what the test needs
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(DivideOutput {
        quotient: input.numerator / input.denominator,
    })
}

If you need remainder later, a test will drive it out.

Mistake 4: Skipping Error Handling

// BAD - Using unwrap() instead of proper error handling
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let file = tokio::fs::read_to_string(&input.path).await.unwrap();
    Ok(ReadOutput { contents: file })
}

Why it’s bad: This violates pforge quality standards. unwrap() causes panics in production.

Fix: Proper error propagation:

// GOOD - Proper error handling
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let file = tokio::fs::read_to_string(&input.path).await
        .map_err(|e| Error::Handler(format!("Failed to read file: {}", e)))?;

    Ok(ReadOutput { contents: file })
}

The ? operator and .map_err() are just as fast to type as .unwrap().

Type-Driven GREEN

Rust’s type system guides you toward correct implementations:

Follow the Types

// You have: input: DivideInput
// You need: Result<DivideOutput>

// Types guide you:
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // input has: numerator (f64), denominator (f64)
    // Output needs: quotient (f64)

    // Types tell you: divide numerator by denominator
    let quotient = input.numerator / input.denominator;

    // Wrap in Output struct
    Ok(DivideOutput { quotient })
}

Follow the types from input to output. The compiler tells you what’s needed.

Let Compiler Guide You

When the compiler complains, listen:

error[E0308]: mismatched types
  --> src/handlers/calculate.rs:15:12
   |
15 |         Ok(quotient)
   |            ^^^^^^^^ expected struct `DivideOutput`, found `f64`

Compiler says: “You returned f64, but function expects DivideOutput.”

Fix:

Ok(DivideOutput { quotient })

The compiler is your pair programmer during GREEN.

Testing Your GREEN Implementation

After writing implementation, verify GREEN:

# Run the specific test
cargo test test_divide_returns_quotient

# Expected output:
# test test_divide_returns_quotient ... ok

If test fails, you have 3 options:

Option 1: Quick Fix (Under 30 Seconds)

Typo or minor mistake:

// Wrong
Ok(DivideOutput { quotient: input.numerator * input.denominator })

// Fixed
Ok(DivideOutput { quotient: input.numerator / input.denominator })

If you can spot and fix in < 30 seconds, do it.

Option 2: Continue to REFACTOR (Test Passes)

Test passes? Move to REFACTOR phase even if implementation feels ugly. You’ll clean it up next.

Option 3: RESET (Can’t Fix Before 5:00)

If you’re at 4:30 and tests still fail with no clear fix, RESET:

git checkout .

Reflect: What went wrong?

• Implementation more complex than expected → Break into smaller tests
• Wrong algorithm → Research before next cycle
• Missing dependencies → Add to setup before next cycle

GREEN + Quality Gates

Even in GREEN phase, pforge quality standards apply:

Must Pass:

• Compilation: Code must compile
• No warnings: Zero compiler warnings
• No unwrap(): Proper error handling
• No panic!(): Return errors, don’t panic

Deferred to REFACTOR:

• Clippy lints: Fix in REFACTOR
• Formatting: Auto-format in REFACTOR
• Complexity: Simplify in REFACTOR
• Duplication: Extract in REFACTOR

The line: GREEN code must be correct but not necessarily clean.

Example: Full GREEN Phase

Let’s implement division with error handling.

Test (From RED Phase)

#[tokio::test]
async fn test_divide_handles_zero_denominator() {
    let handler = DivideHandler;
    let input = DivideInput {
        numerator: 10.0,
        denominator: 0.0,
    };

    let result = handler.handle(input).await;

    assert!(result.is_err());
    match result.unwrap_err() {
        Error::Validation(msg) => {
            assert!(msg.contains("Division by zero"));
        }
        _ => panic!("Wrong error type"),
    }
}

Minute 2:00 - Begin GREEN

Current implementation:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(DivideOutput {
        quotient: input.numerator / input.denominator,
    })
}

Test fails: no division-by-zero check.

Minute 2:10 - Add Zero Check

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.denominator == 0.0 {
        return Err(Error::Validation(
            "Division by zero: denominator must be non-zero".to_string()
        ));
    }

    Ok(DivideOutput {
        quotient: input.numerator / input.denominator,
    })
}

Minute 3:40 - Test Passes

cargo test test_divide_handles_zero_denominator
# test test_divide_handles_zero_denominator ... ok

GREEN!

Minute 4:00 - Enter REFACTOR

We have a working, tested implementation. Now we can refactor.

Minimum vs. Simplest

There’s a subtle but important distinction:

Minimum: Least code to pass the test Simplest: Easiest to understand

Usually they’re the same, but sometimes minimum is less simple:

// Minimum (hard-coded)
async fn handle(&self, _input: Self::Input) -> Result<Self::Output> {
    Ok(Output { value: 42 })
}

// Simplest (obvious logic)
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(Output { value: input.a + input.b })
}

If the simplest implementation is just as fast to write, prefer it over minimum. But if simplest requires significant design, stick with minimum and let tests drive out the design.

When GREEN Takes Longer Than 2 Minutes

If you reach minute 4:00 (2 minutes into GREEN) and tests don’t pass:

You Have 1 Minute Left

Use it to either:

1. Fix the implementation
2. Debug the failure
3. Decide to RESET

Don’t Rush

Rushing leads to mistakes. Better to RESET and start clean than to force broken code through quality gates.

Common Reasons for Slow GREEN

Algorithm complexity: Chose complex approach. Next cycle, try simpler algorithm.

Missing knowledge: Don’t know how to implement. Research before next cycle.

Wrong abstraction: Fighting the types. Rethink approach.

Test too large: Test requires too much code. Break into smaller tests.

GREEN Phase Checklist

Before moving to REFACTOR:

• Test passes (verify by running)
• All existing tests still pass (no regressions)
• Code compiles without warnings
• No unwrap() or panic!() in production code
• Proper error handling for error cases
• Timer shows less than 4:00 elapsed

If any item is unchecked and you can’t fix in 1 minute, RESET.

The Joy of GREEN

There’s a dopamine hit when tests turn green:

test test_divide_returns_quotient ... ok

That “ok” is immediate positive feedback. You’ve made progress. The feature works.

TDD’s tight feedback loop (minutes, not hours) creates frequent positive reinforcement, which:

• Maintains motivation
• Builds momentum
• Reduces stress
• Makes coding addictive (in a good way)

Next Phase: REFACTOR

You have working code. Tests pass. Now you have 1 minute to make it clean.

REFACTOR is where you transform minimum code into maintainable code, with the safety net of passing tests.

Previous: RED: Write Failing Test Next: REFACTOR: Clean Up

REFACTOR: Clean Up

You have working code. Tests pass. Now you have exactly 1 minute to make it clean. REFACTOR is where minimum code becomes maintainable code, all while protected by your test suite.

The Purpose of REFACTOR

REFACTOR transforms code from “works” to “works well.” You’re not adding features—you’re improving the structure, readability, and maintainability of existing code.

Why Refactor Matters

Technical Debt Prevention: Without regular refactoring, each cycle adds a little cruft. After 100 cycles, the codebase is unmaintainable.

Code Comprehension: Future you (next week) needs to understand current you’s code. Clear code reduces cognitive load.

Change Velocity: Clean code is easier to modify. Refactoring now saves time in future cycles.

Bug Prevention: Clearer code has fewer hiding places for bugs.

The 1-Minute Budget

You have 1 minute for REFACTOR. This forces discipline:

Only Obvious Improvements: If it takes more than 1 minute to refactor, defer it to a dedicated refactoring cycle.

Safe Changes Only: You don’t have time to debug complex refactorings. Stick to automated refactorings and obvious simplifications.

Keep Tests Green: After each refactoring step, tests must still pass. If they don’t, revert immediately.

Time Breakdown

• 0:00-0:30: Identify improvements (duplication, naming, complexity)
• 0:30-0:50: Apply refactorings
• 0:50-1:00: Re-run tests, verify still GREEN

Common Refactorings That Fit in 1 Minute

Refactoring 1: Extract Variable

Before:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.age < 0 || input.age > 120 {
        return Err(Error::Validation("Invalid age".to_string()));
    }

    Ok(AgeOutput {
        category: if input.age < 13 { "child" } else if input.age < 20 { "teenager" } else { "adult" }.to_string(),
    })
}

After:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.age < 0 || input.age > 120 {
        return Err(Error::Validation("Invalid age".to_string()));
    }

    let category = if input.age < 13 {
        "child"
    } else if input.age < 20 {
        "teenager"
    } else {
        "adult"
    };

    Ok(AgeOutput {
        category: category.to_string(),
    })
}

Why: Extracts complex expression into named variable, improving readability.

Time: 15 seconds

Refactoring 2: Improve Naming

Before:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let x = input.a + input.b;
    let y = x * 2;
    let z = y - 10;

    Ok(Output { result: z })
}

After:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let sum = input.a + input.b;
    let doubled = sum * 2;
    let adjusted = doubled - 10;

    Ok(Output { result: adjusted })
}

Why: Descriptive names make code self-documenting.

Time: 20 seconds

Refactoring 3: Extract Constant

Before:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.temperature > 100 {
        return Err(Error::Validation("Temperature too high".to_string()));
    }

    if input.temperature < -273 {
        return Err(Error::Validation("Temperature too low".to_string()));
    }

    Ok(TemperatureOutput { celsius: input.temperature })
}

After:

const BOILING_POINT_CELSIUS: f64 = 100.0;
const ABSOLUTE_ZERO_CELSIUS: f64 = -273.15;

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.temperature > BOILING_POINT_CELSIUS {
        return Err(Error::Validation("Temperature too high".to_string()));
    }

    if input.temperature < ABSOLUTE_ZERO_CELSIUS {
        return Err(Error::Validation("Temperature too low".to_string()));
    }

    Ok(TemperatureOutput { celsius: input.temperature })
}

Why: Magic numbers become named constants with semantic meaning.

Time: 25 seconds

Refactoring 4: Simplify Conditional

Before:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let is_valid = if input.value >= 0 && input.value <= 100 {
        true
    } else {
        false
    };

    if !is_valid {
        return Err(Error::Validation("Value out of range".to_string()));
    }

    Ok(Output { value: input.value })
}

After:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.value < 0 || input.value > 100 {
        return Err(Error::Validation("Value out of range".to_string()));
    }

    Ok(Output { value: input.value })
}

Why: Removes unnecessary boolean variable and inverted logic.

Time: 15 seconds

Refactoring 5: Use Rust Idioms

Before:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let mut result = Vec::new();

    for item in input.items {
        let processed = item * 2;
        result.push(processed);
    }

    Ok(Output { items: result })
}

After:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let items = input.items
        .into_iter()
        .map(|item| item * 2)
        .collect();

    Ok(Output { items })
}

Why: Idiomatic Rust uses iterators, which are more concise and often faster.

Time: 20 seconds

Refactoring 6: Auto-Format

Always run auto-formatter:

cargo fmt

This instantly fixes:

• Indentation
• Spacing
• Line breaks
• Brace alignment

Time: 5 seconds (automated)

Refactorings That DON’T Fit in 1 Minute

Some refactorings are too complex for the 1-minute window. Defer these to dedicated refactoring cycles:

Extract Function

// Complex function that needs extraction
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // 50 lines of complex logic
    // Would take 3-5 minutes to extract safely
}

Why defer: Extracting requires:

• Identifying the right boundary
• Determining parameters
• Updating all call sites
• Writing tests for new function

This takes > 1 minute. Create a dedicated refactoring cycle.

Restructure Data

// Changing struct layout
pub struct User {
    pub name: String,
    pub age: i32,
}

// Want to change to:
pub struct User {
    pub profile: Profile,
}

pub struct Profile {
    pub name: String,
    pub age: i32,
}

Why defer: Ripple effects across codebase. Needs multiple cycles.

Change Architecture

// Moving from direct DB access to repository pattern
// This touches many files and requires careful coordination

Why defer: Architectural changes need planning and multiple refactoring cycles.

The Refactoring Checklist

Before finishing REFACTOR phase:

• Code formatted (cargo fmt)
• No clippy warnings (cargo clippy)
• No duplication within function
• Variable names are descriptive
• Constants extracted for magic numbers
• All tests still pass (cargo test)
• Timer shows less than 5:00 elapsed

Example: Complete REFACTOR Phase

Let’s refactor our division handler.

Minute 4:00 - Begin REFACTOR

Current code (from GREEN phase):

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    if input.denominator == 0.0 {
        return Err(Error::Validation(
            "Division by zero: denominator must be non-zero".to_string()
        ));
    }

    Ok(DivideOutput {
        quotient: input.numerator / input.denominator,
    })
}

Minute 4:10 - Identify Improvements

Scan for issues:

• ✓ No duplication
• ✓ Names are clear
• ✓ Logic is simple
• ✓ Error message is helpful

This code is already clean! No refactoring needed.

Minute 4:15 - Run Formatter and Clippy

cargo fmt
cargo clippy --quiet

Output: No warnings.

Minute 4:20 - Verify Tests Still Pass

cargo test --lib --quiet

All tests pass.

Minute 4:25 - REFACTOR Complete

Code is clean, tests pass, ready for COMMIT.

When Code Needs More Refactoring

Sometimes GREEN code is messy enough that 1 minute isn’t enough:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    let x = input.a;
    let y = input.b;
    let z = input.c;
    let q = x + y * z - (x / y) + (z * x);
    let r = q * 2;
    let s = r - 10;
    let t = s / 2;
    let u = t + q;
    let v = u * s;

    Ok(Output { result: v })
}

You have two options:

Option 1: Partial Refactor

Do what you can in 1 minute:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Improved names (30 seconds)
    let a = input.a;
    let b = input.b;
    let c = input.c;

    let complex_calc = a + b * c - (a / b) + (c * a);
    let doubled = complex_calc * 2;
    let adjusted = doubled - 10;
    let halved = adjusted / 2;
    let combined = halved + complex_calc;
    let final_result = combined * adjusted;

    Ok(Output { result: final_result })
}

Then create a TODO for deeper refactoring:

// TODO(REFACTOR): Extract calculation logic into separate functions
// This calculation is complex and would benefit from decomposition
// Estimated effort: 2-3 TDD cycles

Option 2: COMMIT Then Refactor

If code is working but ugly:

1. COMMIT the working code
2. Start a new cycle dedicated to refactoring
3. Use the same tests as safety net

This is better than extending the cycle to 7-8 minutes.

Refactoring Without Tests

Never refactor code without tests. If code lacks tests:

1. Stop: Don’t refactor
2. Add tests first: Write tests in separate cycles
3. Then refactor: Once tests exist, refactor safely

Refactoring without tests is reckless. You can’t verify behavior stays unchanged.

The Safety of Small Refactorings

Why 1-minute refactorings are safe:

Small Changes: Each refactoring is tiny. Easy to understand, easy to verify.

Frequent Testing: Run tests after every refactoring. Catch breaks immediately.

Easy Revert: If refactoring breaks tests, revert is fast (Git history is < 5 minutes old).

Muscle Memory: After 50 cycles, these refactorings become automatic.

Automated Refactoring Tools

Rust-analyzer provides automated refactorings:

• Rename: Rename variable/function (safe, updates all references)
• Extract variable: Pull expression into variable
• Inline variable: Opposite of extract
• Change signature: Modify function parameters

These are safe because the tool maintains correctness. Use them liberally in REFACTOR.

// In VS Code with rust-analyzer:
// 1. Place cursor on variable name
// 2. Press F2 (rename)
// 3. Type new name
// 4. Press Enter
// All references updated automatically

Time: 5-10 seconds per refactoring

REFACTOR Anti-Patterns

Anti-Pattern 1: Refactoring During GREEN

// BAD - Refactoring while implementing
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Writing implementation...
    let result = calculate(input);

    // Oh, let me make this name better...
    // And extract this constant...
    // And simplify this expression...
}

Why it’s bad: GREEN and REFACTOR serve different purposes. Mixing them extends cycle time and confuses goals.

Fix: Resist the urge to refactor during GREEN. Write minimum code, even if ugly. Clean it in REFACTOR.

Anti-Pattern 2: Speculative Refactoring

// BAD - Refactoring for "future needs"
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Current need: simple addition
    // But "maybe we'll need subtraction later", so...

    let calculator = GenericCalculator::new();
    calculator.register_operation("add", Box::new(AddOperation));
    // ... 20 more lines of infrastructure
}

Why it’s bad: YAGNI (You Aren’t Gonna Need It). Speculative refactoring adds complexity for uncertain future needs.

Fix: Refactor for current needs only. When subtraction is actually needed, refactor then.

Anti-Pattern 3: Breaking Tests

// REFACTOR starts
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    // Some refactoring...
}

// Run tests
cargo test
test test_calculate ... FAILED

// Continue anyway, assuming I'll fix it later

Why it’s bad: If REFACTOR breaks tests, you’ve changed behavior. That’s a bug, not a refactoring.

Fix: If tests break, revert immediately:

git checkout .

Investigate why the refactoring broke tests. Either:

• The refactoring was wrong (fix it)
• The test was wrong (fix it in a separate cycle)

Measuring Refactoring Effectiveness

Track these metrics:

Cyclomatic Complexity: Should decrease or stay flat after refactoring

pmat analyze complexity --max 20
# Before: function_name: 15
# After:  function_name: 12

Line Count: Should decrease or stay flat (not always, but often)

Clippy Warnings: Should decrease to zero

cargo clippy
# Before: 3 warnings
# After:  0 warnings

The Refactoring Habit

After 30 days of EXTREME TDD, refactoring becomes automatic:

Minute 4:00: Timer hits, you transition to REFACTOR without thinking

Scan: Eyes automatically scan for duplication, bad names, complexity

Refactor: Fingers execute refactorings via muscle memory

Test: Tests run automatically (in watch mode)

Done: Clean code, passing tests, ready to commit

This takes 30-40 seconds after the habit forms.

REFACTOR Success Metrics

Track these to improve:

Time in REFACTOR: Average time spent refactoring

• Target: < 1:00
• Excellent: < 0:45
• Expert: < 0:30

Refactorings Per Cycle: Average number of refactorings applied

• Target: 1-2
• Excellent: 2-3
• Expert: 3-4 (fast, automated refactorings)

Test Breaks During REFACTOR: Tests broken by refactoring

• Target: < 5%
• Excellent: < 2%
• Expert: < 1%

When to Skip REFACTOR

Sometimes code is clean enough after GREEN:

async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
    Ok(AddOutput {
        sum: input.a + input.b,
    })
}

This is already clean. No refactoring needed.

Still run the checklist:

• Run formatter
• Run clippy
• Run tests

But don’t force refactoring for the sake of it.

Deep Refactoring Cycles

For complex refactorings (extract function, change architecture), dedicate full cycles:

RED: Write test proving current behavior GREEN: No changes (test already passes) REFACTOR: Apply complex refactoring COMMIT: Verify tests still pass, commit

This uses the 5-minute cycle structure but focuses entirely on refactoring.

The Psychology of REFACTOR

Pride: Refactoring is satisfying. Taking messy code and making it clean feels good.

Safety: Tests provide confidence. Refactor boldly knowing tests catch mistakes.

Discipline: The 1-minute limit prevents perfectionism. “Good enough” beats “perfect but incomplete.”

Momentum: Clean code is easier to build upon. Refactoring accelerates future cycles.

Next Phase: COMMIT

You have clean, tested code. Now it’s time for the quality gates to decide: COMMIT or RESET?

This final phase determines if your cycle’s work enters the codebase or gets discarded.

Previous: GREEN: Minimum Code Next: COMMIT: Quality Gates

COMMIT: Quality Gates

You’ve reached minute 5:00. Tests pass. Code is clean. Now comes the moment of truth: do quality gates pass?

COMMIT: All gates pass → Accept the work RESET: Any gate fails → Discard everything

No middle ground. No “mostly passing.” This binary decision enforces uncompromising quality standards.

The Quality Gate Philosophy

Quality gates embody Toyota’s Jidoka principle: “Stop the line when defects occur.” If quality standards aren’t met, production halts.

Why Binary?

No Compromise: Quality is non-negotiable. A partially working feature is worse than no feature—it gives false confidence.

Clear Signal: Binary outcomes are unambiguous. You know instantly whether the cycle succeeded.

Forcing Function: Knowing you might RESET motivates you to stay within the 5-minute budget and write clean code from the start.

Continuous Integration: Every commit maintains codebase quality. No “I’ll fix it later” accumulation.

pforge Quality Gates

pforge enforces multiple quality gates via make quality-gate:

Gate 1: Formatting

cargo fmt --check

What it checks: Code follows Rust style guide (indentation, spacing, line breaks)

Why it matters: Consistent formatting reduces cognitive load and diff noise

Typical failures:

• Inconsistent indentation
• Missing/extra line breaks
• Non-standard brace placement

Fix: Run cargo fmt before checking

Gate 2: Linting (Clippy)

cargo clippy -- -D warnings

What it checks: Common Rust pitfalls, performance issues, style violations

Why it matters: Clippy catches bugs and code smells automatically

Typical failures:

• Unused variables
• Unnecessary clones
• Redundant pattern matching
• Performance anti-patterns

Fix: Address each warning individually or suppress with #[allow(clippy::...)] if truly necessary

Gate 3: Tests

cargo test --all

What it checks: All tests (unit, integration, doc tests) pass

Why it matters: Broken tests mean broken behavior

Typical failures:

• New code breaks existing tests (regression)
• New test doesn’t pass (incomplete implementation)
• Flaky tests (non-deterministic behavior)

Fix: Debug failing tests, fix implementation, or fix test expectations

Gate 4: Complexity

pmat analyze complexity --max 20

What it checks: Cyclomatic complexity of each function

Why it matters: Complex functions are bug-prone and hard to maintain

Typical failures:

• Too many conditional branches
• Deeply nested loops
• Long match statements

Fix: Extract functions, simplify conditionals, reduce nesting

Gate 5: Technical Debt

pmat analyze satd --max 0

What it checks: Self-Admitted Technical Debt (SATD) comments like TODO, FIXME, HACK

Why it matters: SATD comments indicate code that needs improvement

Typical failures:

• Leftover TODO comments
• FIXME markers
• HACK acknowledgments

Fix: Either address the issue or remove the comment (only if it’s not actual debt)

Exception: Phase markers like TODO(RED), TODO(GREEN), TODO(REFACTOR) are allowed during development but must be removed before COMMIT

Gate 6: Coverage

cargo tarpaulin --out Json

What it checks: Test coverage ≥ 80%

Why it matters: Untested code is unverified code

Typical failures:

• New code without tests
• Error paths not tested
• Edge cases not covered

Fix: Add tests for uncovered lines

Gate 7: Technical Debt Grade

pmat analyze tdg --min 0.75

What it checks: Overall technical debt grade (0-1 scale)

Why it matters: Aggregate measure of code health

Typical failures:

• Combination of complexity, SATD, dead code, and low coverage
• Accumulation of small issues

Fix: Address individual issues contributing to low TDG

Running Quality Gates

Fast Check (During REFACTOR)

make quality-gate-fast

Runs subset of gates for quick feedback:

• Formatting
• Clippy
• Unit tests only

Time: < 10 seconds

Use this during REFACTOR to catch issues early.

Full Check (Before COMMIT)

make quality-gate

Runs all gates:

• Formatting
• Clippy
• All tests
• Complexity
• SATD
• Coverage
• TDG

Time: < 30 seconds (for small projects)

Use this at minute 4:30-5:00 before deciding COMMIT or RESET.

The COMMIT Decision

At minute 5:00, run make quality-gate:

Scenario 1: All Gates Pass

make quality-gate
# ✓ Formatting check passed
# ✓ Clippy check passed
# ✓ Tests passed (15 passed; 0 failed)
# ✓ Complexity check passed (max: 9/20)
# ✓ SATD check passed (0 markers found)
# ✓ Coverage check passed (87.5%)
# ✓ TDG check passed (0.92/0.75)
# All quality gates passed!

Decision: COMMIT

Stage and commit your changes:

git add -A
git commit -m "feat: add division handler with zero check

Implements division operation with validation for zero denominator.

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

Cycle successful. Start next cycle.

Scenario 2: One or More Gates Fail

make quality-gate
# ✓ Formatting check passed
# ✗ Clippy check failed (3 warnings)
# ✓ Tests passed
# ✓ Complexity check passed
# ✓ SATD check passed
# ✗ Coverage check failed (72.3% < 80%)
# ✓ TDG check passed
# Quality gates FAILED

Decision: RESET

Discard all changes:

git checkout .
git clean -fd

Cycle failed. Reflect, then start next cycle with adjusted scope.

Scenario 3: Timer Expired

# Check time
echo "Minute: 5:30"

Timer expired before running quality gates.

Decision: RESET

No exceptions. Even if you’re “almost done,” RESET.

git checkout .
git clean -fd

The RESET Protocol

When RESET occurs, follow this protocol:

Step 1: Discard Changes

git checkout .
git clean -fd

This removes all uncommitted changes—both tracked and untracked files.

Step 2: Reflect

Don’t immediately start the next cycle. Take 30-60 seconds to reflect:

Why did RESET occur?

• Timer expired → Scope too large
• Tests failed → Implementation incomplete or incorrect
• Complexity too high → Need simpler approach
• Coverage too low → Missing tests

What will I do differently next cycle?

• Smaller scope (fewer features per test)
• Simpler implementation (avoid clever approaches)
• Better planning (think before typing)
• More tests (test error cases too)

Step 3: Log the RESET

Track your RESETs to identify patterns:

echo "$(date) RESET divide_by_zero - complexity too high (cycle 5:30)" >> .tdd-log

Over time, you’ll notice:

• Common failure modes
• Scope estimation improvements
• Decreasing RESET frequency

Step 4: Start Fresh Cycle

Begin a new 5-minute cycle with adjusted scope:

termdown 5m &
vim tests/calculator_test.rs

Apply lessons learned from the RESET.

Common COMMIT Failures

Failure 1: Clippy Warnings

warning: unused variable: `temp`
  --> src/handlers/calculate.rs:12:9
   |
12 |     let temp = input.a + input.b;
   |         ^^^^ help: if this is intentional, prefix it with an underscore: `_temp`

Why it happens: Leftover variables from implementation iterations

Quick fix (if < 30 seconds to minute 5:00):

// Remove unused variable
// let temp = input.a + input.b;  // deleted

Ok(Output { result: input.a + input.b })

Re-run quality gates.

If no time to fix: RESET

Failure 2: Test Regression

test test_add_positive_numbers ... FAILED

failures:

---- test_add_positive_numbers stdout ----
thread 'test_add_positive_numbers' panicked at 'assertion failed: `(left == right)`
  left: `5`,
 right: `6`'

Why it happens: New code broke existing functionality

Quick fix: Unlikely to fix in < 30 seconds

Correct action: RESET

Regression means your change had unintended side effects. You need to rethink the approach.

Failure 3: Low Coverage

Coverage: 72.3% (target: 80%)
Uncovered lines:
  src/handlers/divide.rs:15-18 (error handling)

Why it happens: Forgot to test error paths

Quick fix (if close to time limit): Write missing test in next cycle

Correct action: RESET if you want this feature in codebase now

Coverage gates ensure every line is tested. Untested error handling is a bug waiting to happen.

Failure 4: High Complexity

Cyclomatic complexity check failed:
  src/handlers/calculate.rs:handle (complexity: 23, max: 20)

Why it happens: Too many conditional branches

Quick fix: Unlikely in remaining time

Correct action: RESET

High complexity indicates the implementation needs redesign. Quick patches won’t fix fundamental complexity.

When to Override Quality Gates

Never.

The strict answer: you should never override quality gates in EXTREME TDD. If gates fail, the cycle fails.

However, in practice, there are rare circumstances where you might git commit --no-verify:

Acceptable Override Cases

Pre-commit hook not installed yet: First commit setting up the project

External dependency issues: Gate tool unavailable (e.g., CI server down, PMAT not installed)

Emergency hotfix: Production is down, fix needs to deploy immediately

Experimental branch: Explicitly marked WIP branch, not merging to main

Unacceptable Override Cases

“I’m in a hurry”: No. RESET and do it right.

“The gate is wrong”: If the gate is genuinely wrong, fix the gate in a separate cycle. Don’t override.

“It’s just a style issue”: Style issues compound. Fix them.

“I’ll fix it in the next commit”: No. Future you won’t fix it. Fix it now or RESET.

The Pre-Commit Hook

pforge installs a pre-commit hook that runs quality gates automatically:

.git/hooks/pre-commit

Contents:

#!/bin/bash
set -e

echo "Running quality gates..."
make quality-gate

if [ $? -ne 0 ]; then
    echo "Quality gates failed. Commit blocked."
    exit 1
fi

echo "Quality gates passed. Commit allowed."
exit 0

This hook:

• Runs automatically on git commit
• Blocks commit if gates fail
• Ensures you never accidentally commit bad code

To bypass (rarely needed):

git commit --no-verify

But this should be exceptional, not routine.

COMMIT Message Conventions

When COMMIT succeeds, write a clear commit message:

Format

<type>: <short summary>

<detailed description>

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>

Types

• feat: New feature
• fix: Bug fix
• refactor: Code restructuring (no behavior change)
• test: Add or modify tests
• docs: Documentation changes
• chore: Build, dependencies, tooling

Examples

git commit -m "feat: add divide operation to calculator

Implements basic division with f64 precision. Validates denominator is non-zero and returns appropriate error for division by zero.

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

git commit -m "test: add edge case for negative numbers

Ensures calculator handles negative operands correctly.

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

git commit -m "refactor: extract validation into helper function

Reduces cyclomatic complexity from 18 to 12 by extracting input validation logic.

Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>"

Psychology of COMMIT vs RESET

The Joy of COMMIT

When quality gates pass:

✓ All quality gates passed!

There’s a genuine dopamine hit. You’ve:

• Written working code
• Maintained quality standards
• Made progress

This positive reinforcement encourages continuing the discipline.

The Pain of RESET

When quality gates fail:

✗ Quality gates FAILED

There’s genuine disappointment. You’ve:

• Spent 5 minutes
• Produced nothing commitworthy
• Must start over

This negative reinforcement teaches you to:

• Scope smaller
• Write cleaner code upfront
• Respect the time budget

The Learning Curve

First week:

• COMMIT rate: ~50%
• RESET rate: ~50%
• Frequent frustration

Second week:

• COMMIT rate: ~70%
• RESET rate: ~30%
• Pattern recognition forms

Fourth week:

• COMMIT rate: ~90%
• RESET rate: ~10%
• Discipline internalized

The pain of RESETs trains you to succeed. After 30 days, you intuitively scope work to fit 5-minute cycles.

Tracking COMMIT/RESET Ratios

Track your outcomes to measure improvement:

# Simple tracking script
echo "$(date) COMMIT feat_divide_basic (4:45)" >> .tdd-log
echo "$(date) RESET  feat_divide_zero (5:30)" >> .tdd-log

Calculate weekly stats:

grep COMMIT .tdd-log | wc -l  # 27
grep RESET .tdd-log | wc -l   # 3

# Success rate: 27/(27+3) = 90%

Target Metrics

Week 1: 50% COMMIT rate (learning) Week 2: 70% COMMIT rate (improving) Week 4: 85% COMMIT rate (proficient) Week 8: 95% COMMIT rate (expert)

When RESET Happens Repeatedly

If you RESET 3+ times on the same feature:

Stop and Reassess

Problem: Your approach isn’t working

Solutions:

1. Break down further: Feature is too large for one cycle
2. Research first: You don’t understand the domain well enough
3. Spike solution: Take 15 minutes outside TDD to explore approaches
4. Pair program: Another developer might see a simpler approach
5. Defer feature: Maybe this feature needs more design before implementation

Example: Persistent RESET

# Attempting to implement JWT authentication
09:00 RESET jwt_auth_validate (5:45)
09:06 RESET jwt_auth_validate (5:30)
09:12 RESET jwt_auth_validate (6:00)

After 3 RESETs, stop. Take 15 minutes to:

• Read JWT library documentation
• Write a spike (throwaway code) to understand API
• Identify the smallest incremental step

Then return to TDD with better understanding.

Quality Gates in CI/CD

Quality gates don’t just run locally—they run in CI/CD:

GitHub Actions Example

# .github/workflows/quality.yml
name: Quality Gates

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Run Quality Gates
        run: make quality-gate

This ensures:

• Every push runs quality gates
• Pull requests can’t merge if gates fail
• Team maintains quality standards

Advanced: Graduated Quality Gates

For larger changes, use graduated quality gates:

Cycle 1: Core Implementation

• Run fast gates (fmt, clippy, unit tests)
• COMMIT if passing

Cycle 2: Integration Tests

• Run integration tests
• COMMIT if passing

Cycle 3: Performance Tests

• Run benchmarks
• COMMIT if no regression

This allows you to make progress in 5-minute increments while building up to full validation.

The Discipline of Binary Outcomes

The hardest part of EXTREME TDD is accepting binary outcomes:

No “Good Enough”: Either all gates pass or they don’t. No subjective judgment.

No “I’ll Fix Later”: Future you won’t fix it. Fix it now or RESET.

No “It’s Just One Warning”: One warning becomes ten warnings becomes unmaintainable code.

This discipline seems harsh, but it’s what maintains quality over hundreds of cycles.

Celebrating COMMITs

Each COMMIT is progress. Celebrate small wins:

# After COMMIT
echo "✓ Feature complete: divide with zero check"
echo "✓ Tests: 12 passing"
echo "✓ Coverage: 87%"
echo "✓ Cycle time: 4:45"

Recognizing progress maintains motivation through the discipline of EXTREME TDD.

Next Steps

You now understand the complete 5-minute EXTREME TDD cycle:

RED (2 min): Write failing test GREEN (2 min): Minimum code to pass REFACTOR (1 min): Clean up COMMIT (instant): Quality gates decide

This cycle, repeated hundreds of times, builds production-quality software with:

• 80%+ test coverage
• Zero technical debt
• Consistent code quality
• Frequent commits (safety net)

The next chapters cover quality gates in detail, testing strategies, and advanced TDD patterns.

Previous: REFACTOR: Clean Up Next: Chapter 8: Quality Gates

Quality Gates: The Jidoka Principle

In Toyota’s manufacturing system, Jidoka means “automation with a human touch” or more commonly: “Stop the line when defects occur.” If a worker spots a quality issue, they pull the andon cord, halting the entire production line until the problem is fixed.

This principle prevents defects from propagating downstream and accumulating into expensive rework.

pforge applies Jidoka to software development through automated quality gates: a series of checks that must pass before code enters the codebase. If any gate fails, development stops. Fix the issue, then proceed.

No compromises. No “I’ll fix it later.” No technical debt accumulation.

The Quality Gate Philosophy

Traditional development often treats quality as an afterthought:

• Write code quickly, worry about quality later
• Accumulate technical debt, plan a “cleanup sprint” (that never happens)
• Let failing tests slide, promising to fix them “after the deadline”
• Ignore warnings, complexity, and code smells

This creates a debt spiral: poor quality begets more poor quality. Complexity increases. Tests become flaky. Refactoring becomes dangerous. Eventually, the codebase becomes unmaintainable.

Quality gates prevent this spiral by enforcing standards at every commit.

Why Quality Gates Matter

Prevention over Cure: Catching issues early is exponentially cheaper than fixing them later. A linting error caught pre-commit takes 30 seconds to fix. The same issue in production might take hours or days.

Compound Quality: Each commit builds on previous work. If commit N is low quality, commits N+1, N+2, N+3 inherit that debt. Quality gates ensure every commit maintains baseline standards.

Rapid Feedback: Developers get immediate feedback. No waiting for CI, code review, or QA to discover issues.

Forcing Function: Knowing that commits will be rejected for quality violations changes behavior. You write cleaner code from the start.

Collective Ownership: Quality gates are objective and automated. They apply equally to all contributors, maintaining consistent standards.

pforge’s Quality Gate Stack

pforge enforces eight quality gates before allowing commits:

0. Documentation Link Validation

Command: pmat validate-docs --fail-on-error

What it checks: All markdown links (both local files and HTTP URLs) are valid

Why it matters: Broken documentation links frustrate users and erode trust. Dead links suggest unmaintained projects.

Example failure:

❌ Broken link found: docs/api.md -> nonexistent-file.md
❌ HTTP 404: https://example.com/deleted-page

This catches both local file references that don’t exist and external URLs that return 404s. Documentation is code—it must be tested.

1. Code Formatting

Command: cargo fmt --check

What it checks: Code follows Rust’s standard formatting (indentation, spacing, line breaks)

Why it matters: Consistent formatting reduces cognitive load and eliminates bike-shedding. Code review focuses on logic, not style.

Example failure:

Diff in /home/noah/src/pforge/crates/pforge-runtime/src/handler.rs at line 42:
-pub fn new(name:String)->Self{
+pub fn new(name: String) -> Self {

Fix: Run cargo fmt to auto-format all code.

2. Linting (Clippy)

Command: cargo clippy --all-targets --all-features -- -D warnings

What it checks: Common Rust pitfalls, performance issues, API misuse, code smells

Why it matters: Clippy’s 500+ lints catch bugs and anti-patterns that humans miss. It encodes decades of Rust experience.

Example failures:

warning: unnecessary clone
  --> src/handler.rs:23:18
   |
23 |     let s = name.clone();
   |                  ^^^^^^^ help: remove this

warning: this returns a `Result<_, ()>`
  --> src/registry.rs:45:5
   |
45 |     Err(())
   |     ^^^^^^^ help: use a custom error type

Fix: Address each warning. For rare false positives, use #[allow(clippy::lint_name)] with a comment explaining why.

3. Tests

Command: cargo test --all

What it checks: All tests (unit, integration, doc tests) pass

Why it matters: Failing tests mean broken behavior. A green test suite is your contract with users.

Example failure:

test handler::tests::test_validation ... FAILED

---- handler::tests::test_validation stdout ----
thread 'handler::tests::test_validation' panicked at 'assertion failed:
  `(left == right)`
  left: `Error("Invalid parameter")`,
  right: `Ok(...)`'

Fix: Debug the test. Either the implementation is wrong or the test expectations are incorrect.

4. Complexity Analysis

Command: pmat analyze complexity --max-cyclomatic 20

What it checks: Cyclomatic complexity of each function (max: 20)

Why it matters: Complex functions are bug-prone, hard to test, and hard to maintain. Studies show defect density increases exponentially with complexity.

Example failure:

Function 'process_request' has cyclomatic complexity 23 (max: 20)
  Location: src/handler.rs:156
  Recommendation: Extract helper functions or simplify logic

Fix: Refactor. Extract functions, eliminate branches, use early returns, leverage Rust’s pattern matching.

5. SATD Detection (Self-Admitted Technical Debt)

Command: pmat analyze satd

What it checks: TODO, FIXME, HACK, XXX comments (except Phase 2-4 markers)

Why it matters: These comments are promises to fix things “later.” Later rarely comes. They accumulate into unmaintainable codebases.

Example failures:

SATD found: TODO: refactor this mess
  Location: src/handler.rs:89
  Severity: Medium

SATD found: HACK: temporary workaround
  Location: src/registry.rs:234
  Severity: High

pforge allows Phase markers (Phase 2: ...) because they represent planned work, not technical debt.

Fix: Either fix the issue immediately or remove the comment. No deferred promises.

6. Code Coverage

Command: cargo llvm-cov --summary-only (requires ≥80% line coverage)

What it checks: Percentage of code exercised by tests

Why it matters: Untested code is unverified code. 80% coverage ensures critical paths are tested.

Example output:

Filename                      Lines    Covered    Uncovered    %
------------------------------------------------------------
src/handler.rs                234      198        36          84.6%
src/registry.rs               189      167        22          88.4%
src/config.rs                 145      109        36          75.2%  ❌
------------------------------------------------------------
TOTAL                         1247     1021       226         81.9%

Fix: Add tests for uncovered code paths. Focus on edge cases, error handling, and boundary conditions.

7. Technical Debt Grade (TDG)

Command: pmat tdg . (requires ≥75/100, Grade C or better)

What it checks: Holistic code quality score combining complexity, duplication, documentation, test quality, and maintainability

Why it matters: TDG provides a single quality metric. It catches issues that slip through individual gates.

Example output:

╭─────────────────────────────────────────────────╮
│  TDG Score Report                              │
├─────────────────────────────────────────────────┤
│  Overall Score: 94.6/100 (A)                  │
│  Language: Rust (confidence: 98%)               │
│                                                 │
│  Component Scores:                              │
│    Complexity:      92/100                      │
│    Duplication:     96/100                      │
│    Documentation:   91/100                      │
│    Test Quality:    97/100                      │
│    Maintainability: 95/100                      │
╰─────────────────────────────────────────────────╯

A score below 75 indicates systemic quality issues. Fix: Address the lowest component scores first.

8. Security Audit

Command: cargo audit (fails on known vulnerabilities)

What it checks: Dependencies against the RustSec Advisory Database

Why it matters: Vulnerable dependencies create attack vectors. Automated auditing catches CVEs before they reach production.

Example failure:

Crate:     time
Version:   0.1.43
Warning:   potential segfault in time
ID:        RUSTSEC-2020-0071
Solution:  Upgrade to >= 0.2.23

Fix: Update vulnerable dependencies. Use cargo update or modify Cargo.toml.

Running Quality Gates

Manual Execution

Run all gates before committing:

make quality-gate

This executes all eight gates sequentially, stopping at the first failure. Expected output:

📝 Formatting code...
✅ Formatting complete!

🔍 Linting code...
✅ Linting complete!

🧪 Running all tests...
✅ All tests passed!

📊 Running comprehensive test coverage analysis...
✅ Coverage: 81.9% (target: ≥80%)

🔬 Running PMAT quality checks...

  1. Complexity Analysis (max: 20)...
     ✅ All functions within complexity limits

  2. SATD Detection (technical debt)...
     ⚠️  6 Phase markers (allowed)
     ✅ No prohibited SATD comments

  3. Technical Debt Grade (TDG)...
     ✅ Score: 94.6/100 (A)

  4. Dead Code Analysis...
     ✅ No dead code detected

✅ All quality gates passed!

Automated Pre-Commit Hooks

pforge installs a pre-commit hook that runs gates automatically:

git commit -m "Add feature"

🔒 pforge Quality Gate - Pre-Commit Checks
==========================================

🔗 0/8 Validating markdown links...
✓ All markdown links valid

📝 1/8 Checking code formatting...
✓ Formatting passed

🔍 2/8 Running clippy lints...
✓ Clippy passed

🧪 3/8 Running tests...
✓ All tests passed

🔬 4/8 Analyzing code complexity...
✓ Complexity check passed

📋 5/8 Checking for technical debt comments...
✓ Only phase markers present (allowed)

📊 6/8 Checking code coverage...
✓ Coverage ≥80%

📈 7/8 Calculating Technical Debt Grade...
✓ TDG Grade passed

==========================================
✅ Quality Gate PASSED

All quality checks passed. Proceeding with commit.
[main abc1234] Add feature

If any gate fails, the commit is blocked:

git commit -m "Add buggy feature"

...
🔍 2/8 Running clippy lints...
✗ Clippy warnings/errors found

warning: unused variable: `result`
  --> src/handler.rs:23:9

==========================================
❌ Quality Gate FAILED

Fix the issues above and try again.
To bypass (NOT recommended): git commit --no-verify

Bypassing Quality Gates (Emergency Use Only)

In rare emergencies, you can bypass the pre-commit hook:

git commit --no-verify -m "Hotfix: critical production issue"

Use this sparingly. Every bypass creates technical debt. Document why the bypass was necessary and create a follow-up task to fix the issues.

Quality Gate Workflow Integration

Quality gates integrate with pforge’s 5-minute TDD cycle:

1. RED (0:00-2:00): Write failing test
2. GREEN (2:00-4:00): Write minimal code to pass test
3. REFACTOR (4:00-5:00): Clean up, run make quality-gate
4. COMMIT (5:00): If gates pass, commit. If gates fail, RESET.