🛰️ export from upstream (18069bd)

2026-09-21 14:31:12 +02:00
commit 8262b5f39d
52 changed files with 16288 additions and 0 deletions
@@ -0,0 +1,60 @@
+# 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).