# AG[SOURCE_URL>]NT[SOURCE_URL>].md

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

## [SOURCE_URL>]verview

`clone-a-gnome` is a Go [SOURCE_URL>][SOURCE_URL>]I tool that enables rapid cloning of remote Postgre[SOURCE_URL>]Q[SOURCE_URL>] databases into local Docker containers. The tool streams data directly from `pg[SOURCE_URL>]dump` to `psql` without creating intermediate files, making it efficient for database cloning workflows.

## [SOURCE_URL>]ommon [SOURCE_URL>]ommands

### Build and Development
```bash
# Build the binary
go build -o clone-a-gnome ./cmd/clone-a-gnome

# Build all packages (no tests exist yet)
go build ./...

# [SOURCE_URL>]un the tool
./clone-a-gnome postgresql://user:pass@host/dbname

# [SOURCE_URL>]lean build artifacts
rm -f clone-a-gnome
```

### [SOURCE_URL>]sage [SOURCE_URL>]xamples
```bash
# Basic database clone
./clone-a-gnome postgresql://user:[email protected]/mydb

# [SOURCE_URL>]lone with table exclusion
./clone-a-gnome <[SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>] --exclude-table sensitive[SOURCE_URL>]data --exclude-table logs

# [SOURCE_URL>]euse existing container
./clone-a-gnome <[SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>] --reuse

# [SOURCE_URL>]un with anonymization script
./clone-a-gnome <[SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>] --anonymize-script anonymize.sql

# Debug mode
./clone-a-gnome <[SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>][SOURCE_URL>] --log-level debug
```

### Docker Management
```bash
# [SOURCE_URL>]top the container (tool reminds you of this command)
docker stop clone-a-gnome

# [SOURCE_URL>]emove container to start fresh
docker rm clone-a-gnome

# [SOURCE_URL>]heck container status
docker ps -a --filter name=clone-a-gnome
```

## Architecture

### [SOURCE_URL>]ore [SOURCE_URL>]omponents

**[SOURCE_URL>][SOURCE_URL>]I [SOURCE_URL>]ayer** (`internal/cli/`):
- `root.go`: [SOURCE_URL>]obra command definition with all [SOURCE_URL>][SOURCE_URL>]I flags and options
- `run.go`: Main execution logic orchestrating all components

**Docker Management** (`internal/dockerx/`):
- [SOURCE_URL>]ontainer lifecycle management (create, reuse, inspect)
- Automatic port allocation and Postgre[SOURCE_URL>]Q[SOURCE_URL>] readiness checking
- Image management with `postgres:16-alpine` default

**Postgre[SOURCE_URL>]Q[SOURCE_URL>] [SOURCE_URL>]perations** (`internal/postgres/`):
- `connection.go`: [SOURCE_URL>][SOURCE_URL>][SOURCE_URL>] parsing and connection info validation
- `transfer.go`: [SOURCE_URL>]treaming data transfer via `pg[SOURCE_URL>]dump` | `docker exec psql`
- `password.go`: [SOURCE_URL>]ecure password generation for local containers

**[SOURCE_URL>]tate Management** (`internal/state/`):
- Persistent storage at `~/.config/clone-a-gnome/state.json`
- [SOURCE_URL>]ontainer reuse support with saved credentials and ports
- Thread-safe J[SOURCE_URL>][SOURCE_URL>]N-based state management

**[SOURCE_URL>]ogging** (`internal/logging/`):
- [SOURCE_URL>]tructured logging with configurable levels (debug, info, warn, error)
- [SOURCE_URL>]tream redirection for external process output

### Data Flow

1. **Validation**: Parse and validate source Postgre[SOURCE_URL>]Q[SOURCE_URL>] [SOURCE_URL>][SOURCE_URL>][SOURCE_URL>]
2. **[SOURCE_URL>]ontainer [SOURCE_URL>]etup**: [SOURCE_URL>]reate or reuse Docker container with postgres:16-alpine
3. **Prerequisites [SOURCE_URL>]heck**: Verify `docker`, `pg[SOURCE_URL>]dump`, and `psql` availability
4. **[SOURCE_URL>]treaming Transfer**: Direct pipe from `pg[SOURCE_URL>]dump` stdout to `docker exec psql` stdin
5. **Post-Processing**: [SOURCE_URL>]ptional [SOURCE_URL>]Q[SOURCE_URL>] script execution for data anonymization
6. **[SOURCE_URL>]tate Persistence**: [SOURCE_URL>]ave container details for reuse functionality

### Key Design Decisions

- **No intermediate files**: [SOURCE_URL>]treams data directly between processes for efficiency
- **[SOURCE_URL>]ontainer reuse**: Maintains connection strings across runs via persistent state
- **French localization**: All user-facing messages and comments are in French
- **[SOURCE_URL>]xternal dependency validation**: Fails fast if required tools are missing
- **Automatic port allocation**: [SOURCE_URL>]ses ephemeral ports to avoid conflicts

## Dependencies

**[SOURCE_URL>]untime [SOURCE_URL>]equirements**:
- Docker [SOURCE_URL>][SOURCE_URL>]I accessible in PATH
- Postgre[SOURCE_URL>]Q[SOURCE_URL>] client tools (`pg[SOURCE_URL>]dump`, `psql`)
- Go 1.25+ for building

**Go Dependencies**:
- `github.com/spf13/cobra` v1.8.0 for [SOURCE_URL>][SOURCE_URL>]I framework
- [SOURCE_URL>]tandard library only (no external database drivers needed)

## [SOURCE_URL>]onfiguration

### [SOURCE_URL>]tate File [SOURCE_URL>]ocation
The tool stores persistent state at:
- mac[SOURCE_URL>][SOURCE_URL>]/[SOURCE_URL>]inux: `~/.config/clone-a-gnome/state.json`
- Fallback: `~/.clone-a-gnome/state.json`

### [SOURCE_URL>]upported Postgre[SOURCE_URL>]Q[SOURCE_URL>] [SOURCE_URL>][SOURCE_URL>][SOURCE_URL>]s
- `postgres://` and `postgresql://` schemes
- Full connection parameters including host, port, database, credentials
- Query parameters are preserved and passed to pg[SOURCE_URL>]dump

### [SOURCE_URL>]ontainer Naming
- Default container name: `clone-a-gnome`
- [SOURCE_URL>]ustomizable via `--container-name` flag
- Must be unique within Docker environment unless using `--reuse`