Crate Development

Add to root Cargo.toml:

[workspace]
members = [
    # ... existing members
    "crates/{crate-name}",
]

4. Create src/lib.rs

//! foodshare-{crate-name}: Brief description
//!
//! This crate provides ...

mod error;

pub use error::Error;

Adding a New Binary Crate

1. Create binary directory

mkdir -p bins/{binary-name}/src

2. Create Cargo.toml

[package]
name = "{binary-name}"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
rust-version.workspace = true
description = "Brief description of the binary"

[[bin]]
name = "{binary-name}"
path = "src/main.rs"

[dependencies]
clap = { workspace = true }
foodshare-core = { path = "../../crates/core" }
foodshare-{crate} = { path = "../../crates/{crate}" }

3. Create src/main.rs

use clap::Parser;

#[derive(Parser)]
#[command(name = "{binary-name}", about = "Brief description")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(clap::Subcommand)]
enum Commands {
    /// Description of command
    SomeCommand {
        /// Description of arg
        #[arg(short, long)]
        flag: bool,
    },
}

fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Commands::SomeCommand { flag } => {
            // implementation
        }
    }
    Ok(())
}

Error Pattern

Every crate should define its own error type:

// src/error.rs
use thiserror::Error;

#[derive(Error, Debug)]
pub enum Error {
    #[error("E{code}: {message}")]
    Structured {
        code: u16,
        message: String,
    },

    #[error(transparent)]
    Io(#[from] std::io::Error),
}

Trait Pattern

Expose functionality through traits for testability:

pub trait Scanner: Send + Sync {
    fn scan(&self, path: &Path) -> Result<Vec<Finding>>;
}

pub struct SecretScanner { /* ... */ }

impl Scanner for SecretScanner {
    fn scan(&self, path: &Path) -> Result<Vec<Finding>> {
        // implementation
    }
}

Verification

# Verify workspace builds
cargo check --workspace --all-targets

# Run new crate's tests
cargo test -p foodshare-{crate-name}

# Lint
cargo clippy -p foodshare-{crate-name} -- -D warnings

</essential_principles>

<success_criteria> New crate is correct when:

• Registered in workspace.members
• Uses workspace.dependencies for shared deps
• Has error type with structured error codes
• Has lib.rs (library) or main.rs (binary)
• Builds with cargo check --workspace
• Tests pass with cargo test -p {crate}
• Clippy clean </success_criteria>