Developer Setup

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• setup.sh
• Cargo.toml
• rustfmt.toml
• specs/001-create-a-comprehensive/tasks.md
• specs/002-implement-tdd-green/plan.md

This guide provides comprehensive instructions for setting up a local development environment for caro, a Rust-based CLI tool that converts natural language into safe POSIX shell commands. The project emphasizes a security-first approach, high performance, and a strict Test-Driven Development (TDD) workflow. Following these steps will ensure your environment is correctly configured for contributing to the project.

The setup process involves installing prerequisites, cloning the repository, building the project, and running verification checks to ensure all components are functioning correctly. The project is built with Rust 1.75+ and leverages a modular architecture with a library-first design.

Sources: CONTRIBUTING.md:3-7, specs/001-create-a-comprehensive/plan.md:30-35, specs/002-implement-tdd-green/plan.md:21

Prerequisites

Before setting up the caro development environment, you must have the following tools installed.

Tool	Minimum Version	Description
Rust	1.75+	The core programming language and toolchain.
Git	-	Version control system for cloning the repository.
cargo-watch	-	(Optional) Recommended for continuous test feedback.
cargo-audit	-	(Optional) Recommended for security auditing.

Sources: CONTRIBUTING.md:304-309, specs/001-create-a-comprehensive/plan.md:37, specs/001-create-a-comprehensive/tasks.md:14

You can install the optional but recommended tools using Cargo:

cargo install cargo-watch
cargo install cargo-audit

Sources: CONTRIBUTING.md:318-319

Initial Environment Setup

The initial setup involves cloning the repository, building the project from the source, and running the test suite to confirm a working environment.

This diagram illustrates the developer setup workflow.

1. Fork and Clone the Repository:
   First, create a fork of the wildcard/caro repository on GitHub. Then, clone your fork to your local machine.

   git clone https://github.com/YOUR_USERNAME/caro.git
   cd caro
   

   Sources: CONTRIBUTING.md:312-314

2. Ensure Rust Environment is Loaded:
   Verify that cargo is available in your shell's path. If not, you may need to source your Cargo environment file.

   # Verify cargo is available
   which cargo
   
   # If not found, load Rust environment
   . "$HOME/.cargo/env"
   

   Sources: CONTRIBUTING.md:315-320

3. Build the Project:
   Compile the project to ensure all dependencies are fetched and the code builds successfully.

   cargo build
   

   Sources: CONTRIBUTING.md:321-323

4. Run the Test Suite:
   Execute the full test suite to confirm that your local setup is correct and all tests pass.

   cargo test
   

   Sources: CONTRIBUTING.md:324-326

Project Dependencies

The caro project relies on a set of high-quality Rust crates for its functionality. Dependencies are managed in Cargo.toml and are chosen to be actively maintained and secure.

Sources: CONTRIBUTING.md:200-206, Cargo.toml:23-44

The following table summarizes the key dependencies:

Crate	Version	Category	Description
clap	4.4+	CLI	A powerful command-line argument parser.
tokio	1.x	Async Runtime	Provides the asynchronous runtime for I/O operations.
serde	1.x	Serialization	Framework for serializing and deserializing Rust data structures.
reqwest	-	HTTP Client	An ergonomic, asynchronous HTTP Client.
anyhow	1.x	Error Handling	Flexible error handling for application-level code.
thiserror	1.x	Error Handling	Crate for creating custom, typed errors in libraries.
tracing	0.1	Logging	A framework for instrumenting Rust programs to collect structured, event-based diagnostic information.
directories	5.0	Platform	Provides platform-specific standard paths (e.g., XDG).
toml	0.8	Configuration	A parser for the TOML configuration format.
hf-hub	-	Model Management	Client for interacting with the Hugging Face Hub.

Sources: Cargo.toml:23-44, specs/001-create-a-comprehensive/tasks.md:13, specs/002-implement-tdd-green/plan.md:22, exports/session-logs/2025-10-03-phase3.txt

Code Standards and Quality

The project enforces strict code standards to maintain quality, consistency, and security. All contributions must adhere to these standards.

Formatting (rustfmt)

Code formatting is managed by rustfmt using the configuration in rustfmt.toml. This ensures a consistent style across the entire codebase.

Key formatting rules include:

• max_width = 100: Lines are limited to 100 columns.
• edition = "2021": Uses idioms from the Rust 2021 edition.
• reorder_imports = true: Automatically sorts use statements.

Sources: rustfmt.toml:1-3, CONTRIBUTING.md:353-363

You can check and apply formatting with these commands:

# Check formatting without changing files
cargo fmt --check

# Format all code
cargo fmt --all

Sources: CONTRIBUTING.md:357-360

Linting (clippy)

The project uses clippy to enforce idiomatic Rust and catch common mistakes. All Clippy warnings are treated as errors.

# Run linter
cargo clippy -- -D warnings

Sources: CONTRIBUTING.md:365-368, specs/001-create-a-comprehensive/tasks.md:16

Security Auditing (cargo-audit)

To maintain a minimal and secure dependency tree, cargo audit is used to check for known security vulnerabilities.

# Run security audit
cargo audit

Sources: CONTRIBUTING.md:204, CONTRIBUTING.md:465-467

Development Workflow

caro follows a strict Test-Driven Development (TDD) and spec-driven design methodology. All new functionality must begin with a failing test that defines the desired behavior.

Sources: CONTRIBUTING.md:333-335, specs/002-implement-tdd-green/plan.md:55

This diagram shows the Red-Green-Refactor cycle used in the project.

Continuous Feedback

For instant feedback during development, cargo-watch is recommended to automatically run tests on file changes.

# Start test watcher
. "$HOME/.cargo/env" && cargo watch -x test

Sources: CONTRIBUTING.md:342-345

Specification-Driven Development

Features are designed and documented in the specs/ directory before implementation. This includes API contracts, data models, and user-facing scenarios. Developers must review the relevant specification before writing code.

Sources: CONTRIBUTING.md:347-351, specs/006-intelligent-prompt-generation/spec.md:1

Verifying Your Setup

After completing the initial setup, run the full validation suite to ensure your environment is correctly configured.

Command	Description
cargo fmt --check	Checks for code formatting issues.
cargo clippy -- -D warnings	Runs the linter and treats all warnings as errors.
cargo test	Executes the entire test suite.
cargo audit	Scans for security vulnerabilities in dependencies.
make check	A convenience command that runs format, lint, and test checks.

Sources: CONTRIBUTING.md:328-331, CONTRIBUTING.md:465-467

If all checks pass without errors, your development environment is ready for contributing to caro.

Summary

Setting up a developer environment for caro involves installing Rust, cloning the repository, and verifying the build with a comprehensive suite of tests and quality checks. The project's adherence to strict TDD, code formatting, and security standards is central to its development philosophy. By following this guide, contributors can ensure their setup is aligned with the project's requirements for producing safe, high-quality code.