dbcrust: Instructions file for Codex

AGENTS.md - Development Guide for DBCrust

This file provides guidance for agentic coding tools working with the DBCrust codebase.

Build/Lint/Test Commands

mise.toml uses the project-scoped Mr Boxington Cargo wrapper and requires mise 2026.8.16+. Run mise install first and run Cargo through mise — mise run <task> or mise exec -- cargo … — so non-interactive agents also use the shared Rust build cache; a bare ~/.cargo/bin/cargo bypasses it. If mise isn't installed, use the committed wrapper ./bin/mise the same way (./bin/mise run test). Use mbx doctor to diagnose cache setup; mise run cache:stats / mise run cache:gc inspect and trim the cache.

Core Build Commands

# Install pinned development tools
mise install

# Build the project (development)
mise run build:dev

# Build optimized release version
mise run build

# Slim build (standard preset: PostgreSQL, MySQL, SQLite) and the feature matrix
mise run build:slim
mise run check:features

# Desktop app (GPUI Kit): run / release build / backend tests
mise run gui:dev
mise run gui:build
mise run gui:test       # dbcrust-gui-core, no GPUI needed

# Build Python package (development)
mise run py:dev

# Build Python wheel
mise run py:build

# Install Python package
pip install -e ./python

Testing Commands

# Run all tests
mise run test

# Run tests with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run tests for specific module
cargo test --lib module_name

# Run Python interface tests (pure-Python Django toolkit suite)
mise run py:test

Linting and Formatting

# Format code
mise run fmt

# Lint with clippy (critical issues only)
mise run lint

# Run the standard validation suite
mise run check

# Git hooks are managed by hk (config: hk.pkl)
hk check --all

Code Style Guidelines

General Principles

• Modular Design: Single responsibility per module
• Async/Await: Use throughout for database operations
• Error Handling: Use thiserror for custom error types with user-friendly messages
• User Interaction: MANDATORY - Use inquire crate for ALL user prompts (Select, Confirm, Text, MultiSelect)
• NEVER use manual stdin/stdout prompting or println! for interactive input