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

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

@@ -18,13 +18,14 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 |---|---|
 | `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). |
+| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per `compose.bake.yml`, writes `.env.lock` (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved) and `.env.shas` (locally-built `tree-<hash>` tags). `--mode ci` hard-requires `x-registry-cache` in the bake file. |
 | `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. |
-| `image_refs.py` | Image-reference collection — `collect_repo_references(root, …globs)` enumerates every reference across compose `x-image-ref` services, bake `x-base-images` (pydantic-validated), Dockerfile `FROM`, Dockerfile `COPY --from=` (slash-bearing captures only, so build-stage names are skipped), and yaml `image:` line scans; the Dockerfile and yaml globs are `None`-able to skip those sources (consumer mirroring scans declarations only, policing scans everything); plus build-arg stripping, `unpinned_references(root)` (every slash-bearing reference must carry a tag, a digest, or a trailing `${build-arg}` suffix — consumer CIs fail on its result), `version_coupling_violations(root, couplings)` (each `VersionCoupling` names a pyproject-declared version and the `VersionSite` regexes that must restate it — bake `x-base-images` values or raw file text — so non-derivable couplings like uv `required-version` ↔ uv-base-image tag can't drift silently; the mechanism lives here, the registry in consumer repos' preflight), and remote digest resolution via `imagetools inspect`. `run_build()` consumes the two structural collectors; consumer repos' mirroring tooling consumes the repo scan. |
+| `context_sha.py` | `compute_service_shas(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. |
+| `documents.py` | `BakeDocument` + `parse_bake(path)` — the typed bake-file model every consumer of bake data goes through (build, up, down, generate-score, the reference collectors). A field validator enforces at parse time that every `x-base-images` value is `path:tag` or `path@digest` (a `${…}` hole or a bare path is a validation error, killing the silent-unpinned `FROM` → `:latest` failure mode). `digest_pinned(reference)` is the shared tail test. |
+| `image_refs.py` | Image-reference collection, split by source. `declared_references(root)` enumerates bake `x-base-images` declarations (parsed and validated via `BakeDocument`) — the single source consumer mirroring consumes. `stray_references(root, …globs)` scans Dockerfile `FROM`, Dockerfile `COPY --from=` (slash-bearing captures only, so build-stage names are skipped), and yaml `image:` lines — hand-written literal refs that bypass the declaration system; `unpinned_references(root)` polices exactly those strays (every slash-bearing reference must carry a tag, a digest, or a trailing `${build-arg}` suffix — consumer CIs fail on its result). `bake_base_image_refs(bake: BakeDocument)` adapts declarations to `ImageReference` pairs; `version_coupling_violations(root, couplings)` (each `VersionCoupling` names a pyproject-declared version and the `VersionSite` regexes that must restate it — bake `x-base-images` values or raw file text — so non-derivable couplings like uv `required-version` ↔ uv-base-image tag can't drift silently; the mechanism lives here, the registry in consumer repos' preflight) is unchanged. Remote digest resolution goes through `imagetools inspect`. Compose files are parsed by nothing in this package. |
 
 ## Constraints
 
@@ -32,14 +33,14 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 **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` 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.
+**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 `${…_IMAGE:?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.** 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` (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.lock` (required in every repo, checked in) — third-party and base-image pins, written by `build`: one `NAME=path:tag@sha256:…` entry per bake declaration. `up`/`down` refuse without it; consumers satisfy it with a committed lock filling the `${…_IMAGE:?err}` holes.
 - `.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).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.14
+Version: 0.1.16
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE

docker_devkit-0.1.16/plan.md

@@ -0,0 +1,145 @@
+# One home for third-party image declarations; docker-devkit stops parsing compose
+
+Status note for pickup: COMPLETE. Shipped: docker-devkit 0.1.15, release-devkit
+0.1.11 (both on PyPI). placeframe `dev`: `f2c94d16` (declarations conversion +
+generate-score port completion), `33ddfb26` (score artifacts), `e0bcd9f8`
+(prose) — preflight green. capture-tool `dev`: `ef7660d` (renames + repin),
+`6025c5e` (prose) — lock round-trip stable, rig render green. All four repos
+need operator pushes. Resolved during execution: the fluent-bit declaration key
+is `SEAWEEDFS_AUDIT_IMAGE` (the plan's `FLUENT_BIT_IMAGE` never matched the
+actual compose hole — holes stayed textually unchanged); stale `DOTNET_*`
+declarations and `PYTHON_BASE`/`ZED_BASE` lock entries were pruned in placeframe
+(zero consumers); `INITIALIZE_S3_IMAGE` (consumed by scripts/sweep_postprocess)
+was promoted to a declaration; the generate-score console-script collision was
+resolved by completing the port (config table in placeframe pyproject,
+duplicate module deleted); capture-tool's bake file is `compose.bake.yml`, not
+the `compose.zed.bake.yml` this plan named. NEXT: make-it-sing's own plan.md
+resumes — flip its committed Stage 3 checkpoint (`6b4120c`) from
+`ARG UV_BASE_DIGEST` + `FROM mirror/…${UV_BASE_DIGEST}` to
+`ARG UV_BASE_IMAGE` + `FROM ${UV_BASE_IMAGE}`, repin docker-devkit >=0.1.15.
+
+## Why this initiative exists
+
+docker-devkit parses consumer compose files for exactly one purpose: discovering
+`x-image-ref` labels (declarations of externally-pulled images) so `run_build`
+can digest-lock them and `mirror-images` can mirror them. That single need dragged
+in a pile of wrong-shaped machinery:
+
+- Compose's YAML dialect tags (`!reset`) require PyYAML constructor registration,
+  and PyYAML's constructor API is untyped — a type-checker fight with no clean
+  resolution (the only surviving form was a suppression-boundary debate).
+- The include-following logic in `run_build` serves zero org repos (the only
+  compose include anywhere is make-it-sing's `oci://` one, which contributes
+  nothing and was skipped anyway).
+- Two declaration mechanisms exist for one need: `x-image-ref` labels in compose
+  (placeframe: fluent-bit, cloudbeaver, keycloak, ngrok) and `x-base-images` in
+  the bake file (placeframe: loki, alloy, grafana, and every Dockerfile base).
+- The `_DIGEST` suffix lock shape (`image: path${X_DIGEST:?err}` in compose,
+  lock `X_DIGEST=@sha256:…`) authors the mirror path TWICE — bake declaration +
+  compose image line — a drift exposure (path drift fails loud at pull; tags
+  cannot drift, but the duplication is authored).
+- The Dockerfile suffix form (`FROM path${X_DIGEST}`) has a silent-unpinned
+  failure mode: an empty arg yields a tagless `FROM path`, and Docker silently
+  pulls `:latest`.
+
+## The design
+
+- **Single declaration home**: bake `x-base-images`. Keys use the `_IMAGE`
+  convention (`UV_BASE_IMAGE`, `KEYCLOAK_IMAGE`, …). One authored string
+  (`path:tag`) per third-party image, anywhere in the org.
+- **run_build single-emits** one lock entry per declaration:
+  `NAME=path:tag@sha256:…`. No dual shapes, no suffix entries.
+- **Compose image lines** are pure holes: `image: "${KEYCLOAK_IMAGE:?err}"`.
+- **Dockerfiles** use `ARG NAME` + `FROM ${NAME}`. An empty arg is a hard parse
+  error — this fixes the silent-`:latest` foot-gun.
+- **BakeDocument gains a field validator**: every `base_images` value must be
+  `path:tag` or `path@digest`. The declarations half of `unpinned_references`
+  moves to parse time (enforced on every command run, not a CI-only scan).
+- **`collect_repo_references` splits**: `declared_references(root)` (bake
+  declarations only — what mirror-images consumes) and a stray-ref scan
+  (Dockerfile `FROM`/`COPY --from` literals + score yaml `image:` lines — what
+  `unpinned_references` polices; it survives with that narrow job of catching
+  hand-written literal refs that bypass the declaration system).
+- **`version_coupling_violations` is unchanged** — it guards a genuinely
+  non-derivable agreement (pyproject `tool.uv.required-version` ↔ image tag; the
+  tag carries suffixes like `-python3.13-trixie-slim` that pyproject doesn't
+  hold). Two authored truths that must agree is a different problem from one
+  truth scattered; the check is correct, keep it.
+
+## Changes
+
+### docker-devkit (this repo) — release 0.1.15
+
+- `image_refs.py`: delete `compose_image_refs`, `ComposeDialectLoader`, both
+  `add_constructor` registrations, and the compose branch of
+  `collect_repo_references`; implement the `declared_references` / stray-scan
+  split. `bake_base_image_refs` and `version_coupling_violations` stay.
+- `documents.py`: add the `base_images` field validator.
+- `build_docker.py`: delete the third-party `x-image-ref` resolution block;
+  single-emit lock entries from `x-base-images`; wire all bake consumption
+  through `parse_bake`/`BakeDocument` (typed access replaces dict plumbing —
+  including `compute_service_shas(repo_root, bake: BakeDocument)` and
+  `compute_default_targets(bake: BakeDocument, …)` signatures, with `up.py`,
+  `down.py`, `score_generate.py` parsing at their call sites); loud guard:
+  `--mode ci` requires `x-registry-cache`.
+- Tests: delete the compose-dialect tests; add validator + split-function tests;
+  existing fixtures via `BakeDocument.model_validate`.
+- `types-pyyaml` stays as a dev dependency (it types `parse_bake`'s PyYAML
+  surface; with the dialect code gone, zero suppressions are needed anywhere).
+- AGENTS.md: update the `image_refs.py` row and any compose-parsing references
+  (separate prose commit from the code).
+- Release via the normal tag-ledger flow; operator push (App token cannot push).
+
+### release-devkit — next patch (0.1.11)
+
+- `mirror_images.py`: switch from
+  `collect_repo_references(Path.cwd(), dockerfile_glob=None)` to
+  `declared_references(root)` — same refs, declarations-only source.
+
+### placeframe — one PR
+
+- `compose.bake.yml`: add declarations for the 4 `x-image-ref` services
+  (`CLOUDBEAVER_IMAGE`, `KEYCLOAK_IMAGE`, `FLUENT_BIT_IMAGE`, `NGROK_IMAGE`,
+  values = today's label strings); rename every existing `_DIGEST` declaration
+  key to the `_IMAGE` convention; `x-base-args` keys follow the renames.
+- `compose.yml`: delete the 4 labels (their image lines are textually unchanged —
+  they were already `${X_IMAGE:?err}` holes); flip loki×2 / alloy / grafana from
+  `path${X_DIGEST:?err}` to `${X_IMAGE:?err}`; inventory every `${…_IMAGE}` hole
+  (at minimum `SEAWEEDFS_AUDIT_IMAGE`) and ensure a declaration exists for each.
+- Dockerfiles: convert every base `FROM` to `ARG NAME` + `FROM ${NAME}`.
+- Version-coupling site registry (consumer preflight): rename `base_image` site
+  names to the new declaration keys — locate the registry during execution.
+- Regenerate `.env.lock` (`uv run build --lock-only`); preflight green; repin
+  docker-devkit `>=0.1.15`.
+- AGENTS.md mentions of `x-image-ref` updated (separate prose commit).
+
+### capture-tool
+
+- 3 Dockerfiles + `compose.zed.bake.yml` `x-base-args` key renames; regen
+  `.env.lock`; repin docker-devkit.
+
+### make-it-sing — NOT this initiative
+
+Its own `plan.md` resumes AFTER this one lands (its Stage 3/5 consume the new
+pattern). Its committed Stage 3 checkpoint (`6b4120c`) still carries the suffix
+form (`ARG UV_BASE_DIGEST` + `FROM mirror/…${UV_BASE_DIGEST}`) — flip to
+`ARG UV_BASE_IMAGE` + `FROM ${UV_BASE_IMAGE}` when resuming that plan.
+
+## Ordering
+
+docker-devkit 0.1.15 → release-devkit 0.1.11 → placeframe PR → capture-tool.
+All releases are operator pushes; the sandbox App token has Contents:read only.
+
+## Verification
+
+- docker-devkit: pytest + ruff + basedpyright all green (the checkpoint's known
+  failures must be gone — their absence is the proof the deletion was complete).
+- placeframe / capture-tool: `uv run build --lock-only` round-trip, preflight
+  battery, `docker compose config` render.
+
+## Deliberately out of scope
+
+- Score yaml scanning changes.
+- Renaming the `x-base-images` key itself (it now covers runtime images too —
+  placeframe's loki already made that de facto; note it in a bake-file comment).
+- make-it-sing CI stages (owned by its own plan).

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

@@ -1,6 +1,6 @@
 [project]
 name = "docker-devkit"
-version = "0.1.14"
+version = "0.1.16"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
@@ -13,7 +13,12 @@ dependencies = [
 ]
 
 [dependency-groups]
-dev = ["basedpyright>=1.39.10", "ruff>=0.14.11", "pytest>=8.0.0"]
+dev = [
+    "basedpyright>=1.39.10",
+    "ruff>=0.14.11",
+    "pytest>=8.0.0",
+    "types-pyyaml>=6.0.12.20260906",
+]
 
 [build-system]
 requires = ["hatchling"]

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

@@ -9,13 +9,13 @@ from subprocess import CalledProcessError
 from typing import Annotated, Any, Literal
 
 import typer
-import yaml
 from bashrun.bash import bash, bash_output
 from .detect_gpu import GPU_TYPES, Gpu, detect_gpu
+from .documents import BakeDocument, digest_pinned, parse_bake
 from pydantic_settings import BaseSettings
 
 from .context_sha import compute_service_shas
-from .image_refs import bake_base_image_refs, compose_service_refs, resolve_remote_digest
+from .image_refs import bake_base_image_refs, resolve_remote_digest
 from .modes import parse_env_file
 
 
@@ -27,7 +27,6 @@ settings = Settings.model_validate({})
 
 LOCK_FILE = Path(".env.lock")
 ENV_SHAS_FILE = Path(".env.shas")
-COMPOSE_FILE = Path("compose.yml")
 DEFAULT_BAKE_FILE = Path("compose.bake.yml")
 METADATA_PATH = Path("metadata.json")
 
@@ -75,29 +74,26 @@ def run_build(
     no_cache: bool = False,
     targets_opt: list[str] | None = None,
 ) -> None:
-    service_shas = compute_service_shas(Path.cwd(), DEFAULT_BAKE_FILE)
+    bake = parse_bake(DEFAULT_BAKE_FILE)
+
+    service_shas = compute_service_shas(Path.cwd(), bake)
     os.environ.update(service_shas)
 
-    # Tags of the images built this run — the local analog of .env.lock's pulled digests
+    # Write .env.shas with the locally-built image tags
     ENV_SHAS_FILE.write_text(
         "".join(f"{key}={value}\n" for key, value in sorted(service_shas.items())), 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 {}
-    )
-    for include in compose_data.pop("include", []):
-        include_path = COMPOSE_FILE.parent / (include if isinstance(include, str) else include["path"])
-        included: dict[str, Any] = yaml.safe_load(include_path.read_text(encoding="utf-8"))
-        compose_data.setdefault("services", {}).update(included.get("services", {}))
+    # Load any existing lock
     lock_data = parse_env_file(LOCK_FILE) if LOCK_FILE.exists() else {}
 
     # TOOD: Create separate commands for ci and local modes so typer can do this validation instead of us
     if mode == "ci" and gpu == "auto":
         raise typer.BadParameter("In CI mode, --gpu cannot be 'auto'; specify 'cuda' or 'rocm'.")
 
+    if mode == "ci" and bake.registry_cache is None:
+        raise typer.BadParameter("In CI mode, the bake file must declare x-registry-cache.")
+
     if gpu_only and gpu not in GPU_TYPES:
         raise typer.BadParameter("--gpu-only requires a concrete gpu (cuda or rocm), not 'auto' or 'none'.")
 
@@ -109,28 +105,18 @@ def run_build(
     if gpu == "auto" and not lock_only:
         gpu = detect_gpu()
 
-    # Resolve base image external dependencies
-    for occurrence in [ref for ref in bake_base_image_refs(bake_data) if upgrade or ref.name not in lock_data]:
-        lock_data[occurrence.name] = (
-            f"@{'' if '$' in occurrence.reference else resolve_remote_digest(occurrence.reference)}"
-        )
-
-    # Resolve third-party image external dependencies. x-image-ref marks services whose image
-    # is sourced externally (vs. built from a bake file), so it's the right discriminator
-    # regardless of how many bake files exist.
-    third_party_images: dict[str, str] = {
-        occurrence.name.upper().replace("-", "_") + "_IMAGE": occurrence.reference
-        for occurrence in compose_service_refs(compose_data)
-    }
-
-    # Re-resolve when explicitly requested, when unseen, or when the image name in compose.yml
-    # changed from what's in the lock file (e.g. postgres:16-alpine → postgis/postgres:16-3.4-alpine)
-    for image, ref in {
-        image: ref
-        for image, ref in third_party_images.items()
-        if upgrade or image not in lock_data or not lock_data[image].startswith(ref + "@")
-    }.items():
-        lock_data[image] = f"{ref}@{'' if '$' in ref else resolve_remote_digest(ref)}"
+    # One lock entry per declared third-party image: NAME=path:tag@sha256:…
+    for occurrence in bake_base_image_refs(bake):
+        if digest_pinned(occurrence.reference):
+            lock_data[occurrence.name] = occurrence.reference
+            continue
+        if (
+            not upgrade
+            and occurrence.name in lock_data
+            and lock_data[occurrence.name].startswith(occurrence.reference + "@")
+        ):
+            continue
+        lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(occurrence.reference)}"
 
     # Update main lock file
     LOCK_FILE.write_text(
@@ -149,17 +135,17 @@ def run_build(
 
     # Determine bake targets
     if targets_opt:
-        unknown = set(targets_opt) - set(bake_data["services"])
+        unknown = set(targets_opt) - set(bake.services)
         if unknown:
-            raise typer.BadParameter(f"Unknown targets: {unknown}. Available: {sorted(bake_data['services'])}")
-        targets = [t for t in bake_data["services"] if t in set(targets_opt)]
+            raise typer.BadParameter(f"Unknown targets: {unknown}. Available: {sorted(bake.services)}")
+        targets = [t for t in bake.services if t in set(targets_opt)]
     else:
-        targets = compute_default_targets(bake_data, gpu, gpu_only)
+        targets = compute_default_targets(bake, gpu, gpu_only)
 
     # Configure registry caches in CI mode
     if mode == "ci":
         for target in targets:
-            target_cache = f"{bake_data['x-registry-cache']}:{target}"
+            target_cache = f"{bake.registry_cache}:{target}"
             command_arguments.append(
                 f"--set {target}.cache-to+=type=registry,ref={target_cache},mode=max,image-manifest=true,oci-mediatypes=true"
             )
@@ -178,8 +164,7 @@ def run_build(
         else:
             raise RuntimeError(f"Unsupported host architecture: {machine}")
         for target in targets:
-            target_platforms = bake_data["services"][target].get("build", {}).get("platforms", [])
-            if len(target_platforms) > 1:
+            if len(bake.services[target].build.platforms) > 1:
                 command_arguments.append(f"--set {target}.platform={host_platform}")
 
     # Load or push images based on mode
@@ -253,11 +238,9 @@ def _check_gc_limits(min_gb: int = 60):
 # Services without build.tags (e.g. neural-networks-base-*) stay out too: they are
 # build-only dependencies pulled in via additional_contexts, and bake rejects a
 # tagless target under --push.
-def compute_default_targets(bake_data: dict[str, Any], gpu: Gpu, gpu_only: bool = False) -> list[str]:
-    cross_compile_targets: set[str] = set(bake_data.get("x-cross-compile-targets", []))
-    tagged_services = [
-        service for service, config in bake_data["services"].items() if config.get("build", {}).get("tags")
-    ]
+def compute_default_targets(bake: BakeDocument, gpu: Gpu, gpu_only: bool = False) -> list[str]:
+    cross_compile_targets: set[str] = set(bake.cross_compile_targets)
+    tagged_services = [service for service, config in bake.services.items() if config.build.tags]
     if gpu_only:
         return [
             service

{docker_devkit-0.1.14 → docker_devkit-0.1.16}/src/docker_devkit/context_sha.py

@@ -3,23 +3,20 @@ from __future__ import annotations
 from pathlib import Path, PurePosixPath
 from tempfile import TemporaryDirectory
 
-from typing import Any
-
 import pathspec
-import yaml
 from bashrun.bash import bash, bash_output
 
+from .documents import BakeDocument
+
 
-def compute_service_shas(repo_root: Path, bake_file: Path) -> dict[str, str]:
+def compute_service_shas(repo_root: Path, bake: BakeDocument) -> dict[str, str]:
     repo_root = repo_root.resolve()
 
-    bake_data: dict[str, Any] = yaml.safe_load(bake_file.read_text(encoding="utf-8"))
     service_dirs: set[str] = set()
-    for config in bake_data["services"].values():
-        build: dict[str, Any] = config.get("build", {})
-        if not build.get("tags"):
+    for config in bake.services.values():
+        if not config.build.tags:
             continue
-        service_dirs.add(str(PurePosixPath(build.get("dockerfile", "")).parent))
+        service_dirs.add(str(PurePosixPath(config.build.dockerfile).parent))
 
     tree_entries = bash_output("git ls-tree -r HEAD", cwd=repo_root).splitlines()
 

docker_devkit-0.1.16/src/docker_devkit/documents.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TypeVar
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+DECLARED_REFERENCE_PATTERN = re.compile(
+    r"^(?P<path>[^:@\s$]+)(?::(?P<tag>[^@\s$]+))?(?:@(?P<digest>sha256:[a-f0-9]{64}))?$"
+)
+DIGEST_TAIL_PATTERN = re.compile(r"@sha256:[a-f0-9]{64}$")
+
+
+class BakeBuild(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    context: str = "."
+    dockerfile: str
+    target: str | None = None
+    platforms: list[str] = Field(default_factory=list)
+    args: dict[str, str] = Field(default_factory=dict)
+    tags: list[str] = Field(default_factory=list)
+    additional_contexts: dict[str, str] = Field(default_factory=dict)
+
+
+class BakeService(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    build: BakeBuild
+
+
+class BakeDocument(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    base_images: dict[str, str] = Field(default_factory=dict, alias="x-base-images")
+    base_args: dict[str, str] = Field(default_factory=dict, alias="x-base-args")
+    registry_cache: str | None = Field(default=None, alias="x-registry-cache")
+    cross_compile_targets: list[str] = Field(default_factory=list, alias="x-cross-compile-targets")
+    services: dict[str, BakeService] = Field(default_factory=dict)
+
+    @field_validator("base_images")
+    @classmethod
+    def _require_tag_or_digest(cls, base_images: dict[str, str]) -> dict[str, str]:
+        for name, reference in base_images.items():
+            match = DECLARED_REFERENCE_PATTERN.fullmatch(reference)
+            if match is None or not (match.group("tag") or match.group("digest")):
+                raise ValueError(f"x-base-images.{name}: {reference!r} must be 'path:tag' or 'path@digest'")
+        return base_images
+
+
+def digest_pinned(reference: str) -> bool:
+    return DIGEST_TAIL_PATTERN.search(reference) is not None
+
+
+def parse_bake(path: Path) -> BakeDocument:
+    loader = yaml.SafeLoader(path.read_text(encoding="utf-8"))
+    try:
+        return BakeDocument.model_validate(loader.get_single_data())
+    finally:
+        loader.dispose()

{docker_devkit-0.1.14 → docker_devkit-0.1.16}/src/docker_devkit/down.py

@@ -7,6 +7,7 @@ from bashrun.bash import bash_handoff
 from .detect_gpu import Gpu, detect_gpu
 
 from .context_sha import compute_service_shas
+from .documents import parse_bake
 from .lifecycle import BAKE_FILE, enforce_bake_declaration, expand_compose_files, load_lifecycle_config
 from .modes import resolve_auth_mode
 
@@ -36,7 +37,7 @@ def down(
     resolve_auth_mode(ENV_FILE)
 
     if BAKE_FILE.exists():
-        os.environ.update(compute_service_shas(Path.cwd(), BAKE_FILE))
+        os.environ.update(compute_service_shas(Path.cwd(), parse_bake(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)

{docker_devkit-0.1.14 → docker_devkit-0.1.16}/src/docker_devkit/image_refs.py

@@ -8,9 +8,10 @@ from dataclasses import dataclass
 from itertools import starmap
 from pathlib import Path
 
-import yaml
 from bashrun.bash import bash_output
-from pydantic import BaseModel, ConfigDict, Field, RootModel
+from pydantic import RootModel
+
+from .documents import BakeDocument, parse_bake
 
 BUILD_ARG_PATTERN = re.compile(r"\$\{[A-Za-z0-9_]+\}")
 FROM_PATTERN = re.compile(r"^FROM\s+(?:--platform=\S+\s+)?(\S+)", re.MULTILINE)
@@ -20,24 +21,6 @@ DIGEST_PATTERN = re.compile(r"^Digest:\s+(sha256:[a-f0-9]+)", re.MULTILINE)
 MISSING_VERSION = "<missing>"
 
 
-class ComposeService(BaseModel):
-    model_config = ConfigDict(extra="ignore")
-
-    image_ref: str | None = Field(default=None, alias="x-image-ref")
-
-
-class ComposeDocument(BaseModel):
-    model_config = ConfigDict(extra="ignore")
-
-    services: dict[str, ComposeService] = Field(default_factory=dict)
-
-
-class BakeDocument(BaseModel):
-    model_config = ConfigDict(extra="ignore")
-
-    base_images: dict[str, str] = Field(default_factory=dict, alias="x-base-images")
-
-
 type TomlValue = (
     str
     | int
@@ -79,7 +62,7 @@ class VersionCoupling:
 def unpinned_references(root: Path) -> list[str]:
     return [
         occurrence.reference
-        for occurrence in collect_repo_references(root)
+        for occurrence in stray_references(root)
         if "/" in (reference := strip_build_args(occurrence.reference))
         and not BUILD_ARG_PATTERN.search(occurrence.reference)
         and ":" not in (tail := reference[reference.rfind("/") + 1 :])
@@ -87,48 +70,32 @@ def unpinned_references(root: Path) -> list[str]:
     ]
 
 
-def collect_repo_references(
+def declared_references(root: Path, bake_glob: str = "compose*.bake.yml") -> list[ImageReference]:
+    return [reference for path in sorted(root.glob(bake_glob)) for reference in bake_base_image_refs(parse_bake(path))]
+
+
+def stray_references(
     root: Path,
-    compose_glob: str = "compose*.yml",
-    bake_glob: str = "compose*.bake.yml",
-    dockerfile_glob: str | None = "docker/*/Dockerfile*",
-    image_glob: str | None = "score/*.yaml",
+    dockerfile_glob: str = "docker/*/Dockerfile*",
+    image_glob: str = "score/*.yaml",
 ) -> list[ImageReference]:
     return (
         [
-            reference
-            for path in sorted(root.glob(compose_glob))
-            for reference in compose_service_refs(_load_yaml_document(path))
+            ImageReference("", match.group(1))
+            for path in sorted(root.glob(dockerfile_glob))
+            for match in FROM_PATTERN.finditer(path.read_text(encoding="utf-8"))
         ]
         + [
-            reference
-            for path in sorted(root.glob(bake_glob))
-            for reference in bake_base_image_refs(_load_yaml_document(path))
+            ImageReference("", match.group(1))
+            for path in sorted(root.glob(dockerfile_glob))
+            for match in COPY_FROM_PATTERN.finditer(path.read_text(encoding="utf-8"))
+            if "/" in match.group(1)
+        ]
+        + [
+            ImageReference("", match.group(1))
+            for path in sorted(root.glob(image_glob))
+            for match in IMAGE_LINE_PATTERN.finditer(path.read_text(encoding="utf-8"))
         ]
-        + (
-            [
-                ImageReference("", match.group(1))
-                for path in sorted(root.glob(dockerfile_glob))
-                for match in FROM_PATTERN.finditer(path.read_text(encoding="utf-8"))
-            ]
-            + [
-                ImageReference("", match.group(1))
-                for path in sorted(root.glob(dockerfile_glob))
-                for match in COPY_FROM_PATTERN.finditer(path.read_text(encoding="utf-8"))
-                if "/" in match.group(1)
-            ]
-            if dockerfile_glob
-            else []
-        )
-        + (
-            [
-                ImageReference("", match.group(1))
-                for path in sorted(root.glob(image_glob))
-                for match in IMAGE_LINE_PATTERN.finditer(path.read_text(encoding="utf-8"))
-            ]
-            if image_glob
-            else []
-        )
     )
 
 
@@ -153,14 +120,6 @@ def resolve_remote_digest(reference: str) -> str:
     return match.group(1)
 
 
-def compose_service_refs(document: object) -> list[ImageReference]:
-    return [
-        ImageReference(service_name, service.image_ref)
-        for service_name, service in ComposeDocument.model_validate(document).services.items()
-        if service.image_ref is not None
-    ]
-
-
 def strip_build_args(reference: str) -> str:
     return BUILD_ARG_PATTERN.sub("", reference).strip()
 
@@ -183,7 +142,7 @@ def _site_version(path: Path, site: VersionSite) -> str:
         haystack = next(
             (
                 reference.reference
-                for reference in bake_base_image_refs(_load_yaml_document(path))
+                for reference in bake_base_image_refs(parse_bake(path))
                 if reference.name == site.base_image
             ),
             "",
@@ -194,9 +153,5 @@ def _site_version(path: Path, site: VersionSite) -> str:
     return match.group(1) if match else MISSING_VERSION
 
 
-def bake_base_image_refs(document: object) -> list[ImageReference]:
-    return list(starmap(ImageReference, BakeDocument.model_validate(document).base_images.items()))
-
-
-def _load_yaml_document(path: Path) -> object:
-    return yaml.safe_load(path.read_text(encoding="utf-8"))
+def bake_base_image_refs(document: BakeDocument) -> list[ImageReference]:
+    return list(starmap(ImageReference, document.base_images.items()))