Merge pull request #40 from ryanfowler/agents

Add an AGENTS.md file

Author: ryanfowler

.gitignore

@@ -1,3 +1,6 @@
+/.claude
+/CLAUDE.md
+
 /target
 /Cargo.lock
 

AGENTS.md

@@ -0,0 +1,43 @@
+# async-sqlite
+
+This file provides guidance to AI agents when working with code in this repository. Keep this file updated after making changes.
+
+## Project Overview
+
+async-sqlite is a Rust library providing an asynchronous, runtime-agnostic wrapper around SQLite via `rusqlite`. It works with any async runtime (tokio, async-std, etc.) by using background threads internally rather than depending on a specific runtime.
+
+## Build Commands
+
+```bash
+cargo build                    # Build the library
+cargo test                     # Run all tests
+cargo fmt --all -- --check     # Check formatting
+cargo clippy -- -D warnings    # Lint (CI treats all warnings as errors)
+```
+
+To run a single test:
+```bash
+cargo test <test_name>         # e.g., cargo test test_blocking_client
+```
+
+The minimum supported Rust version is 1.92.0.
+
+## Architecture
+
+The library has three core types in `src/`:
+
+- **Client** (`client.rs`): Wraps a single SQLite connection. Spawns a background `std::thread` that receives commands (closures) via a `crossbeam_channel`. Results are returned through `futures_channel::oneshot`. This design makes it runtime-agnostic. Client is cheaply cloneable.
+
+- **Pool** (`pool.rs`): Manages multiple `Client` instances with round-robin selection via an atomic counter. Provides the same API as Client plus `conn_for_each()` for executing on all connections. Defaults to CPU-count connections.
+
+- **Error** (`error.rs`): Non-exhaustive enum wrapping `rusqlite::Error`, channel errors, and pragma failures.
+
+All database operations use a closure-based API (e.g., `conn(|conn| { ... })`) to avoid lifetime issues with the cross-thread boundary. Both blocking and async variants exist for all operations.
+
+## Features
+
+All Cargo features are pass-through to `rusqlite`. The `bundled` feature (default) bundles SQLite. The library re-exports `rusqlite` for downstream use.
+
+## Testing
+
+Tests in `tests/tests.rs` use a `async_test!` macro that generates two variants of each async test: one running on tokio and one on async-std. This ensures runtime compatibility. Tests use `tempfile` for temporary database files.