# Sandcage

Rust CLI project for managing Docker-based development environments.

## Project structure

- `crates/sandcage/` — Main CLI binary (Cargo workspace member)
- `crates/sandcage-test/` — Integration/functional tests (not exported)
- `images/` — Base Dockerfile, fragments, and per-service entrypoint scripts
- `templates/` — Project templates for `sandcage init`
- `scripts/` — Python scripts for tooling, deployment, and automation
- `docs/` — Documentation

## Python / uv

This is **not** a Python project. The `pyproject.toml` and uv setup exist to provide a
managed Python environment for tooling: deploy scripts, data processing, automation recipes,
CI helpers, and any ad-hoc scripting that skills or plugins need.

Run Python scripts via uv:

```sh
uv run scripts/some_script.py
uv run python -c "..."
```

Add dependencies as needed:

```sh
uv add <package>
uv add --dev <package>
```

## Just commands

Project tasks are run via `just`. Run `just` to see all available recipes.

When asked to "export", use:

```sh
just export-dry   # preview locally
just export       # push to public repo
```

Configuration: `scripts/export.toml` (excluded paths, asset overlay directory).
Public-facing assets (README, etc.): `scripts/export_assets/`.

## Testing

There is no CI pipeline. Do not plan or implement CI-based builds, test matrices, or
CI config files unless explicitly asked.

After finishing a feature implementation, run `just test-functional` (requires Docker +
built images) at least once before reporting the work as done. If images need rebuilding
first, use `just test-functional-full`. This catches regressions that unit tests miss —
like container launch, TTY attach, and mount behavior.

## Conventions

See `CONVENTION.md` for commit message format (gitmoji).