gh-geoffjay-claude-plugins-plugins-rust-tokio-expert/commands/tokio-scaffold.md

name, description

name	description
tokio-scaffold	Scaffold new Tokio projects with proper structure and best practices

Tokio Scaffold Command

This command scaffolds new Tokio-based Rust projects with modern structure, proper dependencies, error handling patterns, tracing infrastructure, and testing setup.

Arguments

• $1 - Project name (required)
• $2 - Project type: http-server, grpc-server, tcp-server, cli, or library (optional, defaults to library)

Usage

/rust-tokio-expert:tokio-scaffold my-service http-server
/rust-tokio-expert:tokio-scaffold my-cli cli
/rust-tokio-expert:tokio-scaffold my-lib library

Workflow

1. Validate Arguments

   • Check that project name is provided
   • Validate project type if provided
   • Ensure target directory doesn't already exist

2. Invoke Agent

   • Use Task tool with subagent_type="rust-tokio-expert:tokio-pro"
   • Pass project name and type to the agent

3. Agent Instructions

   The agent should create a complete project structure based on the type:

   For HTTP Server Projects

   Create:

   • Cargo.toml with dependencies:

     • tokio with full features
     • axum for HTTP framework
     • tower and tower-http for middleware
     • serde and serde_json for serialization
     • tracing and tracing-subscriber for logging
     • anyhow and thiserror for error handling
     • sqlx (optional) for database
     • config for configuration management

   • src/main.rs with:

     • Runtime setup with tracing
     • Router configuration
     • Graceful shutdown handling
     • Health check endpoints

   • src/handlers/mod.rs with example HTTP handlers

   • src/error.rs with custom error types

   • src/config.rs with configuration loading

   • src/telemetry.rs with tracing setup

   • tests/integration_test.rs with API integration tests

   • .env.example with configuration template

   • README.md with usage instructions

   For gRPC Server Projects

   Create:

   • Cargo.toml with:

     • tokio with full features
     • tonic and tonic-build
     • prost for protobuf
     • tower for middleware
     • tracing infrastructure
     • error handling crates

   • proto/service.proto with example service definition

   • build.rs for proto compilation

   • src/main.rs with gRPC server setup

   • src/service.rs with service implementation

   • src/error.rs with error types

   • tests/integration_test.rs

   For TCP Server Projects

   Create:

   • Cargo.toml with:

     • tokio with io-util, net features
     • tokio-util with codec
     • bytes for buffer management
     • tracing infrastructure

   • src/main.rs with TCP server setup

   • src/protocol.rs with protocol definition

   • src/handler.rs with connection handler

   • tests/integration_test.rs

   For CLI Projects

   Create:

   • Cargo.toml with:

     • tokio with full features
     • clap for argument parsing
     • anyhow for error handling
     • tracing-subscriber for logging

   • src/main.rs with CLI setup

   • src/commands/mod.rs with command structure

   • src/config.rs with configuration

   • tests/cli_test.rs

   For Library Projects

   Create:

   • Cargo.toml with:

     • tokio as optional dependency
     • async-trait
     • thiserror for errors

   • src/lib.rs with library structure

   • tests/lib_test.rs with comprehensive tests

   • examples/basic.rs with usage example

   • README.md with API documentation

4. Common Files for All Types

   • .gitignore with Rust-specific ignores
   • Cargo.toml with proper metadata
   • rustfmt.toml with formatting rules
   • clippy.toml with linting configuration (if needed)

5. Initialize Testing

   For all project types:

   • Add #[tokio::test] examples
   • Include timeout tests
   • Add mock/test utilities
   • Set up test helpers

6. Documentation

   Generate README.md with:

   • Project description
   • Requirements
   • Installation instructions
   • Usage examples
   • Development setup
   • Testing instructions
   • Contributing guidelines

7. Verification

   After scaffolding:

   • Run cargo check to verify compilation
   • Run cargo test to verify tests
   • Report any issues found

Example Cargo.toml Template (HTTP Server)

[package]
name = "{{project_name}}"
version = "0.1.0"
edition = "2021"

[dependencies]
tokio = { version = "1", features = ["full"] }
axum = "0.7"
tower = "0.4"
tower-http = { version = "0.5", features = ["trace", "compression-gzip"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
anyhow = "1"
thiserror = "1"
config = "0.14"

[dev-dependencies]
tokio-test = "0.4"

Example Main Template (HTTP Server)

use axum::{Router, routing::get};
use std::net::SocketAddr;
use tower_http::trace::TraceLayer;

mod handlers;
mod error;
mod config;
mod telemetry;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize telemetry
    telemetry::init()?;

    // Load configuration
    let config = config::load()?;

    // Create router
    let app = Router::new()
        .route("/health", get(handlers::health_check))
        .route("/api/v1/users", get(handlers::list_users))
        .layer(TraceLayer::new_for_http());

    // Start server
    let addr = SocketAddr::from(([0, 0, 0, 0], config.port));
    tracing::info!("Starting server on {}", addr);

    let listener = tokio::net::TcpListener::bind(addr).await?;
    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown_signal())
        .await?;

    Ok(())
}

async fn shutdown_signal() {
    tokio::signal::ctrl_c()
        .await
        .expect("failed to install CTRL+C signal handler");
}

Best Practices

The scaffolded project should follow these best practices:

1. Error Handling: Use thiserror for domain errors, anyhow for application errors
2. Configuration: Use environment variables with sensible defaults
3. Logging: Use tracing with structured logging
4. Testing: Include both unit and integration tests
5. Documentation: Generate comprehensive README with examples
6. Security: Include basic security headers and validation
7. Performance: Configure runtime appropriately for workload type
8. Observability: Include metrics and health check endpoints

Notes

• Always use the latest stable versions of dependencies
• Include comments explaining key architectural decisions
• Provide both simple and advanced usage examples
• Generate projects that compile and pass tests out of the box
• Follow Rust API guidelines and naming conventions