docker-devkit 0.1.13__tar.gz → 0.1.14__tar.gz

{docker_devkit-0.1.13 → docker_devkit-0.1.14}/AGENTS.md

@@ -2,13 +2,13 @@
 
 ## What this is
 
-`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with a native/consumer split so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
+`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in `[tool.docker-devkit.lifecycle]` so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
 
 The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI (`bashrun>=0.1.0`; git-source pins only in scratch branches testing unreleased changes). The repo and package renamed twice on the way here — `stack-lifecycle` → `stack-toolkit` (2026-09-20, before any publish) and `stack-toolkit` → `docker-devkit` (2026-09-21, member of the `-devkit` family). The PyPI identity is fresh: `docker-devkit` starts its own tag ledger at `0.1.0`; the terminal `stack-toolkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
 
 ## Release flow
 
-Publishing rides `release.yml`, triggered by a successful CI run on a `main` push: the machinery — release-devkit's `publish-stable` (an inlined, version-pinned `uvx` step in the publish job, keeping OIDC identity local), never a project dependency (docker-devkit sits inside its own dependency graph; a project-level release-devkit edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (publisher bound to `release.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `docker-devkit-v*` tags are the version ledger (declared `major_minor` line in `publish-config.json`, patch-auto within the line). API-breaking changes ship with a manually bumped `major_minor` — patch-auto assumes additive changes.
+Publishing rides `release.yml`, triggered by a successful CI run on a `main` push: the machinery — release-devkit's `publish-stable` (an inlined, version-pinned `uvx` step in the publish job, keeping OIDC identity local), never a project dependency (docker-devkit sits inside its own dependency graph; a project-level release-devkit edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (publisher bound to `release.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `docker-devkit-v*` tags are the version ledger (declared `major_minor` line in `publish-config.json`, patch-auto within the line). While pre-1.0, breaking changes ride the normal patch flow without a bump; from 1.0 on, API-breaking changes ship with a manually bumped `major_minor` — patch-auto assumes additive changes.
 
 ## Shape
 
@@ -16,10 +16,11 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 | Module | Role |
 |---|---|
-| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--no-dev`, `--compose-file`. |
-| `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`, `--compose-file`. |
+| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`. |
+| `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`. |
 | `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per `compose.bake.yml`, writes `.env.lock` (third-party pulled digests) and `.env.shas` (locally-built `tree-<hash>` tags). |
 | `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `score/` sources: `${ALL_CAPS}` placeholder expansion into tempdir-rendered workload copies, idempotent `score-compose`/`score-k8s` init (state preserved across runs), and a determinism suite (document sort, state-path normalisation, 0644 modes, LF newlines). Consumer policy — workloads, provisioners, patch templates, output paths, storage classes, publishes, tool versions — is declared in the consumer's root `pyproject.toml` under `[tool.docker-devkit.generate-score]` (`ScoreConfig`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
+| `lifecycle.py` | `LifecycleConfig` — the `[tool.docker-devkit.lifecycle]` declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (walks `tool → docker-devkit → lifecycle`, `None` when absent), `enforce_bake_declaration()` (a canonical `compose.bake.yml` requires a declaration), `expand_compose_files()` (assembles the `-f` list; a `{gpu}` entry is dropped when the GPU resolves to `none`; `dev_file` appended when a dev overlay applies). |
 | `detect_gpu.py` | `detect_gpu()` → `cuda`/`rocm`/`none` from host devices; the `Gpu` literal. |
 | `modes.py` | `resolve_auth_mode()` — validates `PUBLIC_URL` + `AUTH_MODE` from `.env`, rejecting `keycloak` over cleartext `http://`. |
 | `context_sha.py` | `compute_service_shas()` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. |
@@ -27,22 +28,22 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 ## Constraints
 
-### Native stack vs. consumer stack
+### Lifecycle declaration contract
 
-**Context.** A repo that authors its own stack builds its own images and assembles a multi-file compose graph (`compose.yml` + `compose.postgres.yml` + a GPU layer + `compose.dev.yml`), injecting per-service `${*_SHA}` image tags and a `.env.lock` of third-party digests. A consumer repo has none of that: it ships a single self-contained compose file that OCI-includes the upstream artifact already baked (image digests and internal vars frozen as literals) or includes a sibling checkout (which supplies its own `.env.lock`/`.env.shas` through the include's `env_file`). Running `compute_service_shas` there is meaningless (no `compose.bake.yml`, no Dockerfiles) and requiring `.env.lock` is wrong (the consumer has no internal vars to resolve).
+**Context.** A repo that authors its own stack builds its own images and assembles a multi-file compose graph (e.g. `compose.yml` + `compose.postgres.yml` + a GPU layer + `compose.dev.yml`), injecting per-service `${*_SHA}` image tags and a `.env.lock` of third-party digests. A consumer repo has none of that: it ships a single self-contained compose file that OCI-includes the upstream artifact already baked (image digests and internal vars frozen as literals) or includes a sibling checkout (which supplies its own `.env.lock`/`.env.shas` through the include's `env_file`).
 
-**Constraint.** `up`/`down` pick the mode by the marker `compose.bake.yml`. **Native** = the default `--compose-file compose.yml` *and* `compose.bake.yml` present → multi-file assembly, SHA injection, `.env.lock` required. **Consumer** = anything else → the single `--compose-file` is the whole graph, run with `--env-file .env` alone; SHA resolution is skipped and `.env.lock` is passed only if it happens to exist. `--build` is rejected outside native mode (a consumer has no local build graph).
+**Constraint.** `up`/`down` assemble the graph from `[tool.docker-devkit.lifecycle]` in the consumer's root pyproject — one code path, declared data. Keys: `files` (compose files in layering order, `{gpu}` templating, a `{gpu}` entry dropped when the GPU resolves to `none`; defaults to empty), `dev_file` (dev overlay, appended by `up --dev` and always by `down` so teardown removes containers from prior dev bring-ups). No table → single-file default (`-f compose.yml`). `--compose-file` does not exist; raw `docker compose` is the pressure valve. `--dev` is opt-in — production-shaped bring-up is the default. `.env.lock` is required unconditionally, no knob; consumers pin stock images via `${…_DIGEST:?err}` holes filled by a committed lock. A canonical `compose.bake.yml` present without a lifecycle declaration is a hard error (declare the table, or the file doesn't belong under that name) — guards are budgeted for silent failures only, and a missing lock already fails loudly. The bake file remains the build/up contract: SHA injection and `--build` acceptance key on `compose.bake.yml` existing, and `build` always reads exactly that name. An empty assembly (`files` empty/omitted, no dev overlay) is a loud `up`/`down` error — the honest state for a builds-only repo.
 
-**Consequences.** A consumer runs `uv run up` (default `compose.yml`) or `uv run up --compose-file compose.local.yml` from its own repo root, against its own `.env`, with no extra setup. A native stack's behavior is unchanged: default `compose.yml` stays native, and an explicit non-default `--compose-file` still falls through to the single-graph path.
+**Consequences.** placeframe's shape lives in placeframe's pyproject, not in this package: `files = ["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"]`, `dev_file = "compose.dev.yml"`. A consumer repo declares a bare table (builds images, no repo-local runtime graph) and runs `uv run up` against its own `.env` + committed `.env.lock`.
 
 ### File and env conventions the commands assume
 
 - `.env` (required) — carries `PUBLIC_URL` and `AUTH_MODE`; `modes.py` reads it and rejects `keycloak` over cleartext `http://`.
-- `.env.lock` (native, required, checked in) — third-party and base-image digests, written by `build`. `up`/`down` refuse to run natively without it.
-- `.env.shas` (native, gitignored, per-build) — `tree-<hash>` tags of locally-built images, written by `build`. `up` injects the `${*_SHA}` values into the environment directly (native mode only) and reads neither file; `.env.shas` exists so a consumer running the compose files through raw `docker compose` can resolve those holes via `--env-file .env.shas`.
-- `compose.bake.yml` (native, required) — the buildx-bake description; its top-level `x-cross-compile-targets` list (optional) is the set of services excluded from the default target list because they need per-arch treatment, opt-in via `--targets`.
-- `compose.yml` / `compose.postgres.yml` / `compose.<gpu>.yml` / `compose.dev.yml` — native's multi-file layers; the GPU one is picked by `detect_gpu()` (or the `--gpu` override).
-- `.dockerignore` (native) — allowlist that `context_sha.py` hashes over to compute per-service `tree-<hash>` tags. See "Docker build context" in `AGENTS-SHARED.md` for the allowlist rationale.
+- `.env.lock` (required in every repo, checked in) — third-party and base-image digests, written by `build`. `up`/`down` refuse without it; consumers satisfy it with a committed lock of `${…_DIGEST:?err}` hole-fills.
+- `.env.shas` (where images are built locally, gitignored, per-build) — `tree-<hash>` tags of locally-built images, written by `build`. `up` injects the `${*_SHA}` values into the environment directly and reads neither file; `.env.shas` exists so a consumer running the compose files through raw `docker compose` can resolve those holes via `--env-file .env.shas`.
+- `compose.bake.yml` (where a local build graph exists, required) — the buildx-bake description; its top-level `x-cross-compile-targets` list (optional) is the set of services excluded from the default target list because they need per-arch treatment, opt-in via `--targets`. One bake file name, ever: `build` reads exactly this name.
+- the compose layers declared in `[tool.docker-devkit.lifecycle]` — e.g. placeframe's `compose.yml` / `compose.postgres.yml` / `compose.<gpu>.yml` / `compose.dev.yml`; the GPU one is picked by `detect_gpu()` (or the `--gpu` override).
+- `.dockerignore` (where images are built locally) — allowlist that `context_sha.py` hashes over to compute per-service `tree-<hash>` tags. See "Docker build context" in `AGENTS-SHARED.md` for the allowlist rationale.
 
 The build command writes to two files rather than one because a CI invariant forbids built-image digests in `.env.lock` (which is committed and reviewed) and because `.env.shas` changes on every source edit, so it stays out of version control.
 

{docker_devkit-0.1.13 → docker_devkit-0.1.14}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.13
-Summary: Docker-stack lifecycle commands (up/down/build) with a native/consumer split
+Version: 0.1.14
+Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.13

{docker_devkit-0.1.13 → docker_devkit-0.1.14}/README.md

@@ -1,8 +1,8 @@
 # docker-devkit
 
-Docker-stack lifecycle commands — `up`, `down`, `build` — with a native/consumer split. A repo that authors its own stack (Dockerfiles + `compose.bake.yml`) uses the native mode: multi-file compose assembly, per-service SHA injection, `.env.lock` resolution. A consumer repo that OCI-includes an already-baked upstream stack uses the same commands as a thin wrapper: single-graph, `.env`-only, no build path.
+Docker-stack lifecycle commands — `up`, `down`, `build` — with the compose assembly declared per repo in `[tool.docker-devkit.lifecycle]`. A repo that authors its own stack (Dockerfiles + `compose.bake.yml`) declares its file layers and gets multi-file assembly, per-service SHA injection, and `.env.lock` resolution; a consumer repo that OCI-includes an already-baked upstream stack declares a bare table and runs the same commands as a thin wrapper over its own `.env` + committed `.env.lock`.
 
-See [`AGENTS.md`](./AGENTS.md) for the file/layout conventions the commands assume (`compose.bake.yml`, `.env.lock`, `.env.shas`, `PUBLIC_URL` / `AUTH_MODE` in `.env`) and the mode-detection contract.
+See [`AGENTS.md`](./AGENTS.md) for the file/layout conventions the commands assume (`compose.bake.yml`, `.env.lock`, `.env.shas`, `PUBLIC_URL` / `AUTH_MODE` in `.env`) and the declaration contract.
 
 ## Setup
 
@@ -17,8 +17,9 @@ uv sync
 From a stack repo's root:
 
 ```bash
-uv run up                      # docker compose up (auto-detects GPU; native or consumer per compose.bake.yml)
-uv run up --build              # build images locally first (native only)
+uv run up                      # docker compose up (auto-detects GPU; assembles the declared lifecycle files)
+uv run up --dev                # layer the declared dev overlay (bind-mount/debug bring-up)
+uv run up --build              # build images locally first (requires compose.bake.yml)
 uv run up --gpu none           # override GPU auto-detection
 uv run down                    # docker compose down
 uv run down -v                 # also remove named volumes

docker_devkit-0.1.14/plan.md

@@ -0,0 +1,122 @@
+# Lifecycle declaration rewrite
+
+Status note for pickup: this plan was authored mid-initiative after a full
+design review with the operator; every decision below is settled unless marked
+otherwise. It is the master plan for the coordinated change set — the rewrite
+here plus the consumer migrations in placeframe and placeframe-capture-tool,
+and the downstream stages in make-it-sing (that repo's own `plan.md` carries
+its CI bring-up detail). AUDIT CURRENT STATE before executing: what has
+landed, what has been released to PyPI, and what each consumer pins.
+
+## Why
+
+`up`/`down` currently pick their behavior by sniffing for a file named exactly
+`compose.bake.yml`, and the "native" branch hardcodes placeframe's repository
+layout (`-f compose.yml -f compose.postgres.yml -f compose.<gpu>.yml -f
+compose.dev.yml`). Two defects: placeframe's shape is embedded in a supposedly
+generic package, and semantics change at a distance through an unrelated
+filename. `build` compounds it with a `--bake-file` option, legitimizing
+multiple bake files per repo. The fix: compose assembly becomes declared data,
+one code path, one bake file name, ever.
+
+## Settled design
+
+- **Declaration**: `[tool.docker-devkit.lifecycle]` in the consumer's root
+  pyproject (sub-table per the package's own `generate-score` precedent —
+  multiple config surfaces, strictly validated per concern). Keys:
+  - `files`: optional list of compose files in layering order, `{gpu}`
+    templating supported; a `{gpu}` entry is dropped when the GPU resolves to
+    `none`. Defaults to empty. Omitted and `[]` are equivalent.
+  - `dev_file`: optional dev overlay, appended when `--dev` is passed;
+    always included on `down` (teardown must remove containers from prior dev
+    bring-ups).
+- **One code path**: table present → assembly from `files`/`dev_file`; no
+  table → single-file default (`-f compose.yml`). `--compose-file` is deleted;
+  raw `docker compose` is the pressure valve.
+- **`--dev` opt-in** replaces `--no-dev` (production-shaped bring-up is the
+  default; bind-mount/debug overlay is explicit).
+- **`.env.lock` unconditionally required**: `up`/`down` refuse without it in
+  every repo. No knob. Consequence: consumers pin stock images via
+  `${…_DIGEST:?err}` holes filled by a committed lock (capture-tool already
+  does this).
+- **Guard**: canonical `compose.bake.yml` present but no `[tool.docker-
+  devkit.lifecycle]` table → hard error naming both fixes (declare, or you
+  shouldn't have a canonical bake file). Guards are budgeted for silent
+  failures only — a missing lock already fails loudly via `${VAR:?err}` and
+  needs none.
+- **Bake file remains the build/up contract**: SHA injection and `--build`
+  acceptance key on `compose.bake.yml` existing. One bake file name, ever:
+  `build` loses `--bake-file` and always reads `compose.bake.yml`; `--targets`
+  stays (selects services within the file).
+- **Empty assembly is loud**: `files` empty/omitted with no `--dev` graph
+  means `up` errors ("no compose files declared") — this is the honest state
+  for a builds-only repo.
+- **Release**: no `major_minor` bump — pre-1.0 policy, breaking is accepted
+  while iterating toward stability. Rides the normal patch flow.
+
+## Changes in this repo
+
+- New `src/docker_devkit/lifecycle.py`: `LifecycleConfig` (pydantic: `files`
+  default empty, `dev_file` optional), `load_lifecycle_config` (walks `tool →
+  docker-devkit → lifecycle`; `None` when absent), the guard, and
+  `expand_compose_files`.
+- `up.py` / `down.py`: mode fork and `--compose-file` deleted; `--dev`
+  opt-in; `.env.lock` required unconditionally; assembly from declaration.
+- `build_docker.py`: `--bake-file` deleted.
+- `tests/test_lifecycle.py`: `{gpu}` expansion, `none` drop, `dev_file`
+  toggle, loader present/absent, guard accept/reject.
+- Docs: AGENTS.md "Native stack vs consumer stack" → the declaration
+  contract; README and the pyproject description string updated to match.
+- Branch + PR, never direct to main (a green main push auto-publishes).
+
+## Consumer migrations
+
+### placeframe
+
+- Add to root pyproject:
+
+  ```toml
+  [tool.docker-devkit.lifecycle]
+  files = ["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"]
+  dev_file = "compose.dev.yml"
+  ```
+
+  Inert under released versions (unknown sub-tables ignored); required before
+  the pin upgrade. Deliberate `uv lock --upgrade-package docker-devkit` after
+  this repo's release.
+- Zed is LEFT AS-IS by operator decision: `compose.zed.bake.yml`, the
+  `build-zed` CI job, and the zed sources stay. Accepted breakage: `build-zed`
+  needs `--bake-file`, which this rewrite deletes — that job fails until the
+  operator reconciles it at merge time. Do not "fix" it here.
+
+### placeframe-capture-tool
+
+- Rename `compose.zed.bake.yml` → `compose.bake.yml` (repo root).
+- Move `docker/zed-capture/compose.rig.yml` → `compose.rig.yml` (repo root);
+  check its relative references during the move (expected none — mostly
+  absolute host paths).
+- Add the bare declaration (builds images, no repo-local runtime graph):
+
+  ```toml
+  [tool.docker-devkit.lifecycle]
+  ```
+
+- CI `build-zed` drops the `--bake-file` argument; sweep `install-zed`'s
+  internal build call for `--bake-file` references at the same time.
+
+### make-it-sing
+
+Consumer by default — no bake file, no table. Its Stage 3 later adds a
+canonical `compose.bake.yml` + `files = ["compose.yml"]`; its Stage 5 adds the
+committed `.env.lock` and digest-hole conversion of its stock image refs. See
+that repo's `plan.md`.
+
+## Sequencing
+
+1. This rewrite: branch, PR, operator push, release.
+2. placeframe lifecycle table (any time; inert until the pin bump) → pin bump.
+3. placeframe-capture-tool renames + declaration + CI arg drop (guard only
+   bites once its own pin passes the rewrite).
+4. make-it-sing Stages 3 and 5 (gated on its pin).
+
+All pushes are operator-handed from the sandbox checkouts.

{docker_devkit-0.1.13 → docker_devkit-0.1.14}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "docker-devkit"
-version = "0.1.13"
-description = "Docker-stack lifecycle commands (up/down/build) with a native/consumer split"
+version = "0.1.14"
+description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",

{docker_devkit-0.1.13 → docker_devkit-0.1.14}/src/docker_devkit/build_docker.py

@@ -51,11 +51,8 @@ def build(
     no_cache: bool = typer.Option(False, "--no-cache", help="Force rebuild by disabling cache usage."),
     targets_opt: Annotated[
         list[str] | None,
-        typer.Option("--targets", "-t", help="Build only these services (from the selected bake file)."),
+        typer.Option("--targets", "-t", help="Build only these services (from compose.bake.yml)."),
     ] = None,
-    bake_file: Annotated[
-        Path, typer.Option("--bake-file", help="Bake file to load (e.g. compose.bake.yml or compose.zed.bake.yml).")
-    ] = DEFAULT_BAKE_FILE,
 ) -> None:
     run_build(
         upgrade=upgrade,
@@ -65,7 +62,6 @@ def build(
         gpu_only=gpu_only,
         no_cache=no_cache,
         targets_opt=targets_opt,
-        bake_file=bake_file,
     )
 
 
@@ -78,22 +74,17 @@ def run_build(
     gpu_only: bool = False,
     no_cache: bool = False,
     targets_opt: list[str] | None = None,
-    bake_file: Path = DEFAULT_BAKE_FILE,
 ) -> None:
-    service_shas = compute_service_shas(Path.cwd(), bake_file)
+    service_shas = compute_service_shas(Path.cwd(), DEFAULT_BAKE_FILE)
     os.environ.update(service_shas)
 
-    # Tags of the images built this run — the local analog of .env.lock's pulled
-    # digests — so raw `docker compose` can resolve the compose graph's ${*_SHA} holes.
+    # Tags of the images built this run — the local analog of .env.lock's pulled digests
     ENV_SHAS_FILE.write_text(
         "".join(f"{key}={value}\n" for key, value in sorted(service_shas.items())), encoding="utf-8"
     )
 
-    # Read bake, compose, and lock files. A bake-only repo (cross-builds images
-    # from a bake file, no local compose graph) has no root compose file; the
-    # only downstream consumers of compose_data are the include merge and the
-    # third-party x-image-ref scan, both empty-safe.
-    bake_data: dict[str, Any] = yaml.safe_load(bake_file.read_text(encoding="utf-8"))
+    # A bake-only repo has no compose.yml; every consumer of compose_data is empty-safe
+    bake_data: dict[str, Any] = yaml.safe_load(DEFAULT_BAKE_FILE.read_text(encoding="utf-8"))
     compose_data: dict[str, Any] = (
         yaml.safe_load(COMPOSE_FILE.read_text(encoding="utf-8")) if COMPOSE_FILE.exists() else {}
     )
@@ -207,7 +198,7 @@ def run_build(
     # Bake images
     command = [
         "docker buildx bake",
-        f"-f {bake_file}",
+        f"-f {DEFAULT_BAKE_FILE}",
         f"--metadata-file {METADATA_PATH}",
         "--progress auto",
         "--provenance=false",
@@ -218,7 +209,7 @@ def run_build(
     # Sanity check
     baked_images: dict[str, Any] = json.loads(METADATA_PATH.read_text()) if METADATA_PATH.exists() else {}
     if not set(targets) <= baked_images.keys():
-        raise RuntimeError("Baked images do not match target images; something went wrong during the bake.")
+        raise RuntimeError("Bake output does not cover the requested targets")
 
 
 # Vibe code - Gemini 3
@@ -240,10 +231,7 @@ def _check_gc_limits(min_gb: int = 60):
     raw = data.get("builder", {}).get("gc", {}).get("defaultKeepStorage")
     if not raw:
         sample = json.dumps({"builder": {"gc": {"defaultKeepStorage": f"{min_gb}GB"}}}, indent=2)
-        raise RuntimeError(
-            f"Missing 'builder.gc.defaultKeepStorage' in {config}; Docker's default is too low for GPU builds "
-            f"(need >= {min_gb}GB). Add the following (merging into any existing keys) and restart Docker:\n\n{sample}"
-        )
+        raise RuntimeError(f"builder.gc.defaultKeepStorage missing in {config}; need >= {min_gb}GB:\n\n{sample}")
 
     m = re.match(r"^(\d+(?:\.\d+)?)\s*([TGMK]i?B)?$", str(raw), re.IGNORECASE)
     if not m:
@@ -254,9 +242,7 @@ def _check_gc_limits(min_gb: int = 60):
     val = float(m.group(1)) * mult.get(unit, 1 / 1024**3)
 
     if val < min_gb:
-        raise RuntimeError(
-            f"UNSAFE GC LIMIT: {val:.1f}GB in {config} (Required: {min_gb}GB). RESTART DOCKER AFTER FIXING."
-        )
+        raise RuntimeError(f"Docker GC limit {val:.1f}GB in {config} is below the required {min_gb}GB")
 
     print(f"    [OK] Docker GC Limit verified: {val:.1f}GB")
 

docker_devkit-0.1.14/src/docker_devkit/down.py

@@ -0,0 +1,67 @@
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from bashrun.bash import bash_handoff
+from .detect_gpu import Gpu, detect_gpu
+
+from .context_sha import compute_service_shas
+from .lifecycle import BAKE_FILE, enforce_bake_declaration, expand_compose_files, load_lifecycle_config
+from .modes import resolve_auth_mode
+
+ENV_FILE = Path(".env")
+LOCK_FILE = Path(".env.lock")
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command()
+def down(
+    volumes: bool = typer.Option(False, "--volumes", "-v", help="Remove named volumes."),
+    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
+) -> None:
+    config = load_lifecycle_config(Path.cwd())
+    enforce_bake_declaration(Path.cwd(), config)
+
+    if not ENV_FILE.exists():
+        raise RuntimeError("No .env file found")
+
+    if not LOCK_FILE.exists():
+        raise RuntimeError("No .env.lock found; run 'uv run build --lock-only' in the repo that authors the images")
+
+    if gpu == "auto":
+        gpu = detect_gpu()
+
+    resolve_auth_mode(ENV_FILE)
+
+    if BAKE_FILE.exists():
+        os.environ.update(compute_service_shas(Path.cwd(), BAKE_FILE))
+
+    # Always layer the dev overlay so containers from a prior --dev bring-up get torn down too
+    compose_files = expand_compose_files(config, gpu, include_dev=True)
+    if not compose_files:
+        raise RuntimeError("No compose files declared; a builds-only repo has no stack to tear down")
+
+    files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
+    command = (
+        "docker compose "
+        f"{files_args} "
+        "--profile keycloak "  # Always include so any keycloak containers from a previous AUTH_MODE=keycloak run get torn down
+        "--env-file .env "
+        f"--env-file {LOCK_FILE} "
+        "down --remove-orphans"
+    )
+
+    if volumes:
+        command += " -v"
+
+    bash_handoff(command)
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

docker_devkit-0.1.14/src/docker_devkit/lifecycle.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .detect_gpu import Gpu
+
+BAKE_FILE = Path("compose.bake.yml")
+DEFAULT_COMPOSE_FILE = Path("compose.yml")
+GPU_PLACEHOLDER = "{gpu}"
+
+
+class LifecycleConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    files: list[str] = Field(default_factory=list)
+    dev_file: str | None = None
+
+
+def load_lifecycle_config(root: Path) -> LifecycleConfig | None:
+    pyproject_path = root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return None
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    section = data.get("tool", {}).get("docker-devkit", {}).get("lifecycle")
+    if section is None:
+        return None
+    return LifecycleConfig.model_validate(section)
+
+
+def enforce_bake_declaration(root: Path, config: LifecycleConfig | None) -> None:
+    if config is None and (root / BAKE_FILE).exists():
+        raise RuntimeError(
+            f"{BAKE_FILE} present without [tool.docker-devkit.lifecycle]; declare the table or rename the file"
+        )
+
+
+def expand_compose_files(config: LifecycleConfig | None, gpu: Gpu, *, include_dev: bool = False) -> list[Path]:
+    if config is None:
+        return [DEFAULT_COMPOSE_FILE]
+    files = [Path(entry.format(gpu=gpu)) for entry in config.files if gpu != "none" or GPU_PLACEHOLDER not in entry]
+    if include_dev and config.dev_file is not None:
+        files.append(Path(config.dev_file))
+    return files

docker_devkit-0.1.14/src/docker_devkit/up.py

@@ -0,0 +1,90 @@
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from bashrun.bash import bash_handoff
+from .detect_gpu import Gpu, detect_gpu
+
+from .build_docker import run_build
+from .context_sha import compute_service_shas
+from .lifecycle import BAKE_FILE, enforce_bake_declaration, expand_compose_files, load_lifecycle_config
+from .modes import resolve_auth_mode
+
+ENV_FILE = Path(".env")
+LOCK_FILE = Path(".env.lock")
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command()
+def up(
+    attached: bool = typer.Option(False, "--attached", "-a", help="Run in foreground (not detached)"),
+    quiet_pull: bool = typer.Option(
+        False,
+        "--quiet-pull",
+        "-q",
+        help="Suppress per-layer pull progress (still shows pull/push totals).",
+    ),
+    build: bool = typer.Option(
+        False, "--build", help="Build all images locally before bringing the stack up; skips pulling"
+    ),
+    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
+    dev: bool = typer.Option(
+        False,
+        "--dev",
+        help="Layer the declared dev overlay (compose.dev.yml shape) over the production stack for bind-mount/debug bring-up.",
+    ),
+) -> None:
+    config = load_lifecycle_config(Path.cwd())
+    enforce_bake_declaration(Path.cwd(), config)
+
+    if dev and (config is None or config.dev_file is None):
+        raise RuntimeError("--dev requires a dev_file in [tool.docker-devkit.lifecycle]")
+
+    if not ENV_FILE.exists():
+        raise RuntimeError("No .env file found; create one first (e.g., copy .env.example)")
+
+    if not LOCK_FILE.exists():
+        raise RuntimeError("No .env.lock found; run 'uv run build --lock-only' in the repo that authors the images")
+
+    if build and not BAKE_FILE.exists():
+        raise typer.BadParameter("--build requires a compose.bake.yml")
+
+    if gpu == "auto":
+        gpu = detect_gpu()
+
+    auth_mode = resolve_auth_mode(ENV_FILE)
+
+    if build:
+        run_build(gpu=gpu)
+
+    if BAKE_FILE.exists():
+        os.environ.update(compute_service_shas(Path.cwd(), BAKE_FILE))
+
+    compose_files = expand_compose_files(config, gpu, include_dev=dev)
+    if not compose_files:
+        raise RuntimeError("No compose files declared; a builds-only repo has no stack to bring up")
+
+    files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
+    profile_flag = "--profile keycloak " if auth_mode == "keycloak" else ""
+    compose_args = f"{files_args} {profile_flag}--env-file .env --env-file {LOCK_FILE}"
+
+    up_command = f"docker compose {compose_args} up"
+    if not build:
+        # tree-<sha> tags are content-addressed and may not be pushed, so pull only what is missing locally
+        up_command += " --pull missing"
+        if quiet_pull:
+            up_command += " --quiet-pull"
+    if not attached:
+        up_command += " -d"
+
+    bash_handoff(up_command)
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

docker_devkit-0.1.14/tests/test_lifecycle.py

@@ -0,0 +1,117 @@
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+from docker_devkit.lifecycle import (
+    LifecycleConfig,
+    enforce_bake_declaration,
+    expand_compose_files,
+    load_lifecycle_config,
+)
+
+
+def _write_pyproject(root: Path, lifecycle_toml: str) -> None:
+    content = f"[project]\nname = 'stack'\n\n{lifecycle_toml}"
+    (root / "pyproject.toml").write_text(content, encoding="utf-8")
+
+
+class TestLoadLifecycleConfig:
+    def test_loads_declared_table(self, tmp_path: Path):
+        _write_pyproject(
+            tmp_path,
+            "[tool.docker-devkit.lifecycle]\n"
+            'files = ["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"]\n'
+            'dev_file = "compose.dev.yml"\n',
+        )
+
+        config = load_lifecycle_config(tmp_path)
+
+        assert config == LifecycleConfig(
+            files=["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"],
+            dev_file="compose.dev.yml",
+        )
+
+    def test_bare_table_defaults_to_empty(self, tmp_path: Path):
+        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\n")
+
+        config = load_lifecycle_config(tmp_path)
+
+        assert config == LifecycleConfig()
+
+    def test_absent_table_returns_none(self, tmp_path: Path):
+        _write_pyproject(tmp_path, "[tool.docker-devkit.generate-score]\nworkloads = []\n")
+
+        assert load_lifecycle_config(tmp_path) is None
+
+    def test_absent_tool_section_returns_none(self, tmp_path: Path):
+        _write_pyproject(tmp_path, "")
+
+        assert load_lifecycle_config(tmp_path) is None
+
+    def test_missing_pyproject_returns_none(self, tmp_path: Path):
+        assert load_lifecycle_config(tmp_path) is None
+
+    def test_rejects_unknown_keys(self, tmp_path: Path):
+        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\nfiles = []\nbogus = true\n")
+
+        with pytest.raises(ValidationError):
+            load_lifecycle_config(tmp_path)
+
+    def test_rejects_non_string_entries(self, tmp_path: Path):
+        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\nfiles = [1]\n")
+
+        with pytest.raises(ValidationError):
+            load_lifecycle_config(tmp_path)
+
+
+class TestExpandComposeFiles:
+    def test_expands_gpu_placeholder(self):
+        config = LifecycleConfig(files=["compose.yml", "compose.{gpu}.yml"])
+
+        assert expand_compose_files(config, "cuda") == [Path("compose.yml"), Path("compose.cuda.yml")]
+
+    def test_drops_gpu_entry_when_none(self):
+        config = LifecycleConfig(files=["compose.yml", "compose.{gpu}.yml"])
+
+        assert expand_compose_files(config, "none") == [Path("compose.yml")]
+
+    def test_keeps_concrete_files_when_none(self):
+        config = LifecycleConfig(files=["compose.yml", "compose.cpu.yml"])
+
+        assert expand_compose_files(config, "none") == [Path("compose.yml"), Path("compose.cpu.yml")]
+
+    def test_appends_dev_file_when_include_dev(self):
+        config = LifecycleConfig(files=["compose.yml"], dev_file="compose.dev.yml")
+
+        assert expand_compose_files(config, "cuda", include_dev=True) == [
+            Path("compose.yml"),
+            Path("compose.dev.yml"),
+        ]
+
+    def test_omits_dev_file_by_default(self):
+        config = LifecycleConfig(files=["compose.yml"], dev_file="compose.dev.yml")
+
+        assert expand_compose_files(config, "cuda") == [Path("compose.yml")]
+
+    def test_empty_files_stay_empty_without_dev(self):
+        assert expand_compose_files(LifecycleConfig(), "cuda") == []
+
+    def test_no_table_defaults_to_single_compose_file(self):
+        assert expand_compose_files(None, "cuda") == [Path("compose.yml")]
+        assert expand_compose_files(None, "cuda", include_dev=True) == [Path("compose.yml")]
+
+
+class TestEnforceBakeDeclaration:
+    def test_accepts_bake_with_declaration(self, tmp_path: Path):
+        (tmp_path / "compose.bake.yml").write_text("", encoding="utf-8")
+
+        enforce_bake_declaration(tmp_path, LifecycleConfig())
+
+    def test_accepts_missing_bake_without_declaration(self, tmp_path: Path):
+        enforce_bake_declaration(tmp_path, None)
+
+    def test_rejects_bake_without_declaration(self, tmp_path: Path):
+        (tmp_path / "compose.bake.yml").write_text("", encoding="utf-8")
+
+        with pytest.raises(RuntimeError, match="lifecycle"):
+            enforce_bake_declaration(tmp_path, None)

docker_devkit-0.1.13/src/docker_devkit/down.py

@@ -1,86 +0,0 @@
-import os
-from pathlib import Path
-from typing import Annotated
-
-import typer
-from bashrun.bash import bash_handoff
-from .detect_gpu import Gpu, detect_gpu
-
-from .context_sha import compute_service_shas
-from .modes import resolve_auth_mode
-
-ENV_FILE = Path(".env")
-LOCK_FILE = Path(".env.lock")
-BAKE_FILE = Path("compose.bake.yml")
-
-app = typer.Typer(add_completion=False)
-
-
-@app.command()
-def down(
-    volumes: bool = typer.Option(False, "--volumes", "-v", help="Remove named volumes."),
-    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
-    compose_file: Annotated[
-        Path,
-        typer.Option(
-            "--compose-file",
-            help=(
-                "Base compose file. In a repo that authors its own stack (where compose.bake.yml lives) the default "
-                "compose.yml tears down the native multi-file stack. A consumer stack is torn down as the single graph "
-                "it was brought up as."
-            ),
-        ),
-    ] = Path("compose.yml"),
-) -> None:
-    # Mirror up: native multi-file teardown only when compose.bake.yml is present and the
-    # default compose.yml was requested. A consumer stack tears down its single graph.
-    native = compose_file == Path("compose.yml") and BAKE_FILE.exists()
-
-    if not ENV_FILE.exists():
-        raise RuntimeError("No .env file found")
-
-    if native and not LOCK_FILE.exists():
-        raise RuntimeError("No lock file found; run 'uv run build --lock-only' first")
-
-    if gpu == "auto":
-        gpu = detect_gpu()
-
-    resolve_auth_mode(ENV_FILE)
-
-    if BAKE_FILE.exists():
-        os.environ.update(compute_service_shas(Path.cwd(), BAKE_FILE))
-
-    if native:
-        compose_files = (
-            "-f compose.yml "
-            "-f compose.postgres.yml "
-            f"{f'-f compose.{gpu}.yml ' if gpu != 'none' else ''}"
-            "-f compose.dev.yml "  # Include so containers from a prior dev bring-up get torn down even with --no-dev later
-        )
-    else:
-        compose_files = f"-f {compose_file} "
-
-    # .env.lock keeps compose from erroring on missing stack-internal vars; it only
-    # exists in the native repo, so a consumer stack tears down with .env alone.
-    lock_flag = f"--env-file {LOCK_FILE} " if LOCK_FILE.exists() else ""
-    command = (
-        "docker compose "
-        f"{compose_files}"
-        "--profile keycloak "  # Always include so any keycloak containers from a previous AUTH_MODE=keycloak run get torn down
-        "--env-file .env "
-        f"{lock_flag}"
-        "down --remove-orphans"
-    )
-
-    if volumes:
-        command += " -v"
-
-    bash_handoff(command)
-
-
-def main():
-    app()
-
-
-if __name__ == "__main__":
-    main()

docker_devkit-0.1.13/src/docker_devkit/up.py

@@ -1,109 +0,0 @@
-import os
-from pathlib import Path
-from typing import Annotated
-
-import typer
-from bashrun.bash import bash_handoff
-from .detect_gpu import Gpu, detect_gpu
-
-from .build_docker import run_build
-from .context_sha import compute_service_shas
-from .modes import resolve_auth_mode
-
-ENV_FILE = Path(".env")
-LOCK_FILE = Path(".env.lock")
-BAKE_FILE = Path("compose.bake.yml")
-
-app = typer.Typer(add_completion=False)
-
-
-@app.command()
-def up(
-    attached: bool = typer.Option(False, "--attached", "-a", help="Run in foreground (not detached)"),
-    quiet_pull: bool = typer.Option(
-        False,
-        "--quiet-pull",
-        "-q",
-        help="Suppress per-layer pull progress (still shows pull/push totals).",
-    ),
-    build: bool = typer.Option(
-        False, "--build", help="Build all images locally before bringing the stack up; skips pulling"
-    ),
-    gpu: Annotated[Gpu, typer.Option("--gpu", help="auto|cuda|rocm|none")] = "auto",
-    no_dev: bool = typer.Option(False, "--no-dev", help="Skip layering compose.dev.yml (production-shape bring-up)"),
-    compose_file: Annotated[
-        Path,
-        typer.Option(
-            "--compose-file",
-            help=(
-                "Base compose file. In a repo that authors its own images (where compose.bake.yml lives) the default "
-                "compose.yml triggers the native multi-file assembly. A consumer stack — a repo whose compose.yml "
-                "OCI-pulls an already-baked upstream artifact and layers on top — is run as the complete graph with "
-                "only --env-file .env."
-            ),
-        ),
-    ] = Path("compose.yml"),
-) -> None:
-    # A repo that authors its own stack carries compose.bake.yml and builds its own images,
-    # so the default compose.yml means the native multi-file stack (postgres + gpu + dev layers,
-    # per-service SHA injection, .env.lock). A consumer repo has no bake file: its
-    # --compose-file is the whole graph (the upstream stack arrives baked via OCI include or a
-    # sibling-checkout include), so SHA resolution and .env.lock don't apply.
-    native = compose_file == Path("compose.yml") and BAKE_FILE.exists()
-
-    if not ENV_FILE.exists():
-        raise RuntimeError("No .env file found; create one first (e.g., copy .env.example)")
-
-    if native and not LOCK_FILE.exists():
-        raise RuntimeError("No lock file found; run 'uv run build --lock-only' first")
-
-    if build and not native:
-        raise typer.BadParameter(
-            "--build is only supported for the native stack (compose.bake.yml present); a consumer stack "
-            "consumes images from an OCI-included upstream artifact and has no local build graph."
-        )
-
-    if gpu == "auto":
-        gpu = detect_gpu()
-
-    auth_mode = resolve_auth_mode(ENV_FILE)
-
-    if build:
-        run_build(gpu=gpu)
-
-    if BAKE_FILE.exists():
-        os.environ.update(compute_service_shas(Path.cwd(), BAKE_FILE))
-
-    profile_flag = "--profile keycloak " if auth_mode == "keycloak" else ""
-    if native:
-        gpu_file = f"-f compose.{gpu}.yml " if gpu != "none" else ""
-        dev_file = "" if no_dev else "-f compose.dev.yml "
-        compose_args = (
-            f"-f compose.yml -f compose.postgres.yml {gpu_file}{dev_file}{profile_flag}"
-            f"--env-file .env --env-file {LOCK_FILE}"
-        )
-    else:
-        lock_flag = f"--env-file {LOCK_FILE} " if LOCK_FILE.exists() else ""
-        compose_args = f"-f {compose_file} {profile_flag}--env-file .env {lock_flag}".rstrip()
-
-    up_command = f"docker compose {compose_args} up"
-    if not build:
-        # tree-<sha> tags are immutable (derived from dockerignore-allowlisted
-        # context), so a local hit is byte-identical to what the registry would
-        # serve. --pull missing skips locally-present tags, avoiding hard errors
-        # on images built locally but not yet pushed.
-        up_command += " --pull missing"
-        if quiet_pull:
-            up_command += " --quiet-pull"
-    if not attached:
-        up_command += " -d"
-
-    bash_handoff(up_command)
-
-
-def main():
-    app()
-
-
-if __name__ == "__main__":
-    main()