misc: initial commit

CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`pgx` is a CLI tool for managing project-scoped PostgreSQL instances running in Docker containers. Each project gets its own isolated Postgres instance, managed through a `pgx.toml` configuration file.
+
+## Core Architecture
+
+### Project-Oriented Design
+
+- Each project has a `pgx.toml` file at its root that defines the Postgres configuration
+- The project name is derived from the directory containing `pgx.toml`
+- Each project gets its own Docker container
+- State is tracked separately per instance to detect configuration drift
+
+### Configuration Management
+
+The `pgx.toml` file stores:
+- `postgres_version`: PostgreSQL version to use
+- `database_name`: Name of the database
+- `user_name`: Database user
+- `password`: Database password
+- `port`: Host port to bind (auto-selected from available ports)
+
+Values are auto-populated during `pgx init` with sensible defaults or random values where appropriate.
+
+### State Tracking
+
+The tool maintains separate state for each instance to detect configuration drift, such as:
+- Container's actual Postgres version vs. config file version
+- Running container state vs. expected state
+- Port conflicts or changes
+
+## Key Dependencies
+
+- **clap** (with derive feature): CLI argument parsing and command structure
+- **toml**: Parsing and serializing `pgx.toml` configuration files
+- **bollard**: Docker daemon interaction for container lifecycle management
+- **tokio** (with full feature set): Async runtime for Docker operations
+- **tracing** + **tracing-subscriber**: Structured logging throughout the application
+- **serde**: Serialization/deserialization for config and state
+- **miette** (with fancy feature): Enhanced error reporting
+- **prodash** (to be added): Terminal progress bars for long-running operations
+
+## Development Commands
+
+### Building
+```bash
+cargo build
+cargo build --release
+```
+
+### Running
+```bash
+cargo run -- <command>
+# Example: cargo run -- init
+```
+
+### Testing
+```bash
+cargo test
+cargo test <test_name>  # Run specific test
+```
+
+### Linting
+```bash
+cargo clippy
+cargo clippy -- -W clippy::all
+```
+
+### Formatting
+```bash
+cargo fmt
+cargo fmt -- --check  # Check without modifying
+```
+
+## Command Structure
+
+The CLI follows this pattern:
+```
+pgx <command> [options]
+```
+
+Key commands to implement:
+- `pgx init`: Create pgx.toml with auto-populated configuration
+- `pgx start`: Start the Postgres container for current project
+- `pgx stop`: Stop the running container
+- `pgx status`: Show instance status and detect drift
+- `pgx destroy`: Remove container and clean up
+
+## Implementation Notes
+
+### Port Selection
+
+Port assignment should scan for available ports on the system rather than using fixed defaults to avoid conflicts.
+
+### Docker Container Naming
+
+Container names should be deterministic based on project name to allow easy identification and prevent duplicates.
+
+### Error Handling
+
+Use `miette` for user-facing errors with context. Docker operations and file I/O are the primary error sources.
+
+### Async Operations
+
+Docker operations via `bollard` are async. Use `tokio` runtime with `#[tokio::main]` on the main function.