winx-code-agent: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

Winx is a Rust 2021 MCP server for shell and coding-agent workflows. The binary entry point is src/main.rs; library exports live in src/lib.rs. src/server.rs is the MCP-service facade, with catalog/schema, handler, principal isolation, session, Task, dispatch, and tests under src/server/; hardened HTTP transport lives in src/http_server.rs, and typed secret/config parsing in src/config.rs. Tool facades live under src/tools/; BashCommand and FileWriteOrEdit are split into focused submodules. Terminal and persistence logic belongs under src/state/, reusable parsing/path/repository/safety helpers under src/utils/, and audited libc calls exclusively under src/os.rs (the crate otherwise denies unsafe code). Integration tests live in tests/, Criterion benchmarks in benches/, cargo-fuzz targets in fuzz/, model assets in assets/, and pinned CI/release automation in .github/workflows/.

Build, Test, and Development Commands

justfile wraps the commands below; run just --list to see every recipe. just check runs formatting, host clippy, the Windows target lint, the test suite, and the MSRV check, and is the gate before any commit. just install-hooks points Git at .githooks/, whose pre-commit hook runs formatting and host clippy and whose commit-msg hook enforces Conventional Commit subjects. The toolchain is pinned in rust-toolchain.toml; bump it deliberately in its own commit, since new clippy lints land with each stable release.

• cargo check --all-features --locked performs a fast compile check with the committed lockfile.
• WINX_EMBEDDED=1 cargo run --release starts an in-process development server without sibling daemons.
• cargo build --release --locked --bins produces the complete optimized Unix bundle; run ./target/release/winx-code-agent afterward.
• cargo fmt --all -- --check verifies formatting; run cargo fmt --all to apply it.
• cargo clippy --all-targets --all-features --locked -- -D warnings runs the enforced lint suite.
• cargo test --all-features --locked runs the full normal test suite.
• cargo test --features loom --lib loom_ runs the opt-in concurrency model checks.
• cargo +1.90.0 check --all-features --locked verifies the declared MSRV.
• cargo package --locked verifies the crates.io package.
• cargo bench --bench performance --locked --no-run compiles the benchmark suite.
• cargo deny --all-features check and cargo audit --deny warnings enforce dependency policy.
• cargo +nightly fuzz build compiles all cargo-fuzz targets.