view release on metacpan or  search on metacpan

CLAUDE.md  view on Meta::CPAN

**Configuration Cascade:**
- Loads `.dozorc` from: `$HOME` → git top dir → current dir → command line
- Single-value options (e.g., `-I`, `-N`) override earlier values
- Repeatable options (e.g., `-E`, `-V`, `-P`, `-O`) accumulate

**Live Container Lifecycle:**
- Container name format: `<image_name>.<mount_directory>`
- States handled: not-exist → create, running → exec/attach, exited → start, paused → unpause
- With command args: uses `docker exec`, without: uses `docker attach`

**Environment Variable Inheritance:**
- Auto-inherits: `LANG`, `TZ`, proxy settings, terminal settings, AI API keys
- Sets in container: `DOZO_RUNNING_ON_DOCKER=1`, `XLATE_RUNNING_ON_DOCKER=1`

### Testing Strategy

- **t/00_compile.t** - Basic compilation check
- **t/03_dozo.t** - Unit tests for dozo script functionality
  - Uses temp directories to isolate from real `.dozorc` files
  - Tests option parsing, `.dozorc` loading, and error handling
  - Uses `-n` (dryrun) to avoid actual Docker execution
- **xt/author/docker_dozo.t** - Integration tests requiring Docker
  - Tests live container lifecycle (create, exec, start, kill)
  - Tests dryrun mode output

**Dryrun Mode (`-n`):**
- Shows docker commands without executing them
- Useful for testing and debugging
- Used in t/03_dozo.t to avoid Docker dependency during installation

## Important Context

### Dependencies

**Runtime:**
- Perl 5.24+ (for the module wrapper)
- Bash 4.3+ (for the main script)
- Docker (runtime requirement, not checked by tests)
- Getopt::Long::Bash 0.6.0+ (provides `getoptlong.sh`)

**Development:**
- Minilla (build tool)
- Test::More (testing)
- Module::Build::Tiny (build backend)

### Documentation Synchronization

POD documentation exists in two places but is kept in sync by release hooks:
- **Source of truth:** `script/dozo` (embedded POD)
- **Copy:** `lib/App/dozo.pm` (auto-generated during release)

When modifying documentation, edit only `script/dozo`. The `minil release` command will sync it to `lib/App/dozo.pm`.

### Version Management

Version is stored in both:
- `lib/App/dozo.pm` - Perl module version (`our $VERSION = "X.Y"`)
- `script/dozo` - POD version section (`=head1 VERSION\n\nVersion X.Y`)

Release hooks keep these synchronized. When updating version, update `lib/App/dozo.pm` first.

### Relationship to App::Greple::xlate

While Dôzo was originally developed as part of App::Greple::xlate for Docker-based translation workflows, it's designed to work standalone. The `getoptlong.sh` script is provided by the `Getopt::Long::Bash` CPAN package, which is installed as a depe...

This allows Dôzo to be used independently as a general-purpose Docker runner.