crates-docs: Instructions file for Codex

AGENTS.md

This file provides comprehensive guidance to agents when working with code in this repository.

CI/CD Workflow & Code Gates

Project Structure

• Rust Edition: 2021
• Default Features: server, stdio, macros, cache-memory, logging, api-key
• Optional Features: cache-redis, tls, auth, hyper-server, sse, streamable-http

Build Commands

# Standard build
cargo build

# Build with all features
cargo build --all-features

# Build with specific feature
cargo build --features cache-redis

# Release build
cargo build --release

Code Quality Gates (Must Pass Before Merge)

1. Formatting Check

cargo fmt -- --check

• Checks if code is properly formatted
• Use cargo fmt to auto-fix formatting issues

2. Clippy Linting

# Check without optional features
cargo clippy --all-targets -- -D warnings

# Check with all features (required - feature-gated code)
cargo clippy --all-features --all-targets -- -D warnings

Critical: Run both commands because Redis/auth code is feature-gated and checked separately.

• -D warnings treats all warnings as errors
• --all-targets includes lib, bins, tests, benches

3. Security Audit

cargo install cargo-audit
cargo audit

Testing Commands

Test Target Structure

Tests are split across THREE targets (not one suite):

# Unit tests (primary - new code goes here)
cargo test --test unit

# Legacy unit tests
cargo test --test unit_tests

# Integration tests
cargo test --test integration_tests

# E2E tests
cargo test --test e2e

Running Single Tests

Important: Use the correct target when running a single test:

# Correct: specify --test unit
cargo test --test unit test_oauth_config_github

# Correct: for tools_docs tests
cargo test --test unit test_lookup_crate_tool_execute_markdown

# Incorrect: will search all targets and may fail
cargo test test_oauth_config_github

Feature-Gated Testing

# Test with Redis cache (only when Redis is available)
cargo test --features cache-redis

# Test unit with Redis feature
cargo test --test unit --features cache-redis

# Test all features
cargo test --all-features