docker-devkit 0.3.0.dev113__tar.gz → 0.4.0__tar.gz

docker_devkit-0.4.0/.github/workflows/integrate.yml

@@ -0,0 +1,24 @@
+name: Integrate
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [dev]
+
+concurrency:
+  group: integrate-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  preflight:
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/preflight.yml@66df38b08b8209b587de1c140b720d835ed8a3c3
+
+  update-pr-draft-release:
+    needs: [preflight]
+    permissions:
+      contents: write
+      packages: read
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/update-pr-draft-release.yml@66df38b08b8209b587de1c140b720d835ed8a3c3

docker_devkit-0.4.0/.github/workflows/merge-gate.yml

@@ -0,0 +1,18 @@
+name: Merge gate
+
+on:
+  pull_request:
+    branches: [dev]
+    types: [labeled]
+
+concurrency:
+  group: merge-gate-${{ github.event.pull_request.number }}
+
+permissions:
+  contents: read
+
+jobs:
+  merge-gate:
+    uses: outernet-foundation/github-actions-toolkit/.github/workflows/merge-gate.yml@66df38b08b8209b587de1c140b720d835ed8a3c3
+    secrets:
+      merge-bot-private-key: ${{ secrets.MERGE_BOT_APP_PRIVATE_KEY }}

docker_devkit-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches: [main, dev]
+
+concurrency:
+  group: release-${{ github.ref }}
+
+permissions:
+  contents: read
+
+jobs:
+  prerelease:
+    if: github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: outernet-foundation/github-actions-toolkit/.github/actions/release@66df38b08b8209b587de1c140b720d835ed8a3c3
+        with:
+          channel: dev
+
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: outernet-foundation/github-actions-toolkit/.github/actions/release@66df38b08b8209b587de1c140b720d835ed8a3c3
+        with:
+          channel: stable

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/AGENTS.md

@@ -10,7 +10,7 @@ Config follows the org law (home: github-actions-toolkit's `AGENTS.md`): this is
 
 ## Release flow
 
-github-actions-toolkit's `AGENTS.md` owns the three-workflow contract; this repo follows it unchanged. Repo-specific facts: github-actions-toolkit is never a project dependency (docker-devkit sits inside its own dependency graph; a project-level edge is a resolver cycle), and from 1.0 on API-breaking changes ship with a manually bumped `major_minor` (pre-1.0, breaking changes ride the patch flow; patch-auto assumes additive changes).
+github-actions-toolkit's `AGENTS.md` owns the consumer workflow contract; this repo follows it unchanged. Repo-specific facts: github-actions-toolkit is never a project dependency (docker-devkit sits inside its own dependency graph; a project-level edge is a resolver cycle), and from 1.0 on API-breaking changes ship with a manually bumped `major_minor` (pre-1.0, breaking changes ride the patch flow; patch-auto assumes additive changes).
 
 ## Mirror consumption
 
@@ -22,19 +22,19 @@ 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`, `--dev`, `--allow-upstream-fallback`. |
+| `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 the resolved image manifest, writing the paired lock (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved; mirror-prefixed declarations resolve their digest against the upstream reference). `--push` is the CI shape (push images + registry caches + digest-manifest shelving) and hard-requires `x-registry-cache`; the flag order mirrors the binding's run line (`--push`, `--targets`, `--gpu`), and `--targets` accepts both repeated flags and one space-joined value. Push mode reads its registry facts from the neutral `REGISTRY`/`REGISTRY_TOKEN`/`REGISTRY_USERNAME` environment — no `GITHUB_*` reads. |
+| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME={prefix}/{ref}@sha256:…` entry per upstream-native `x-base-images` declaration, the mirror-prefixed form derived from `mirror.prefix`; `@digest`-pinned declarations pass through unresolved; digests resolve against the upstream reference). `--push` is the CI shape (push images + registry caches + digest-manifest shelving) and hard-requires `x-registry-cache`; the flag order mirrors the binding's run line (`--push`, `--targets`, `--gpu`), and `--targets` accepts both repeated flags and one space-joined value. Push mode reads its registry facts from the neutral `REGISTRY`/`REGISTRY_TOKEN`/`REGISTRY_USERNAME` environment — no `GITHUB_*` reads. |
 | `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `stack/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 `docker-devkit.yaml` under `generate-score:` (`ScoreConfig`, model in `config.py`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). Output and state paths resolve against the repo root: the compose half runs in `score_dir` (its `.score-compose` state stays there, gitignored), the k8s half runs in the configured `k8s_state` parent so the committed `.score-k8s` state lands in the generated tier. `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
 | `config.py` | `DockerDevkitConfig` — the root `docker-devkit.yaml` schema: a required `requires` PEP 440 specifier plus optional `lifecycle` / `mirror` / `generate-score` sections, `extra="forbid"` on every model. `load_config(root)` is the single strictyaml entry point: parses the file (returns `None` when absent — the no-config → single-file-default path for `up`/`down`), then self-checks the installed docker-devkit version against `requires` (refuses loudly outside range; the `0.0.0.dev0` dev sentinel bypasses the check, not the field). The section models (`LifecycleConfig`, `MirrorConfig`, `ScoreConfig`) live here; `load_lifecycle_config` / `load_mirror_config` / `load_score_config` in their modules are thin wrappers over it. |
-| `lifecycle.py` | `LifecycleConfig` (model in `config.py`) — the `lifecycle:` section declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (reads the `lifecycle:` section via `config.load_config`, `None` when the section or file is absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`, with the legacy root `compose.bake.yml` + `.env.lock` pair still resolved so repos can upgrade before moving files), `enforce_bake_declaration()` (a manifest under either name 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). |
+| `lifecycle.py` | `LifecycleConfig` (model in `config.py`) — the `lifecycle:` section declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (reads the `lifecycle:` section via `config.load_config`, `None` when the section or file is absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`), `enforce_bake_declaration()` (a manifest 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. |
 | `matrix.py` | `docker-build-matrix` — emit the CI build leg list as a bare JSON array on stdout (the binding's getter pipes it through its `matrix` verb, which composes the envelope and guards the empty case): one entry per variant × cohort cell, `targets` = that cell's explicitly-buildable services with dependents grouped with the base their `additional_contexts: target:` references pull in (one leg builds a whole dependency-closure group in a single bake invocation). The leg schema — `targets` (space-joined), `variant` (`common`/`cuda`/`rocm`, from the service-name suffix) — is named contract with the binding; renaming a key breaks its fanout YAML. The cross-compile cohort (services in `x-cross-compile-targets` or declaring `platforms:`) gets its own legs — per-arch builds are the QEMU-slow ones and parallelize away from native builds; a group spanning cohort membership is a loud error. Tagless services never become explicit targets (bake rejects a tagless target under `--push`) — they ride as in-invocation dependencies; a group spanning gpu variants is a loud error. |
 | `modes.py` | `resolve_auth_mode()` — validates `PUBLIC_URL` + `AUTH_MODE` from `.env`, rejecting `keycloak` over cleartext `http://`. |
 | `context_sha.py` | `compute_service_shas(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. The workload-tree root is derived as the single top-level directory containing every tagged service's Dockerfile (a bake graph spanning several top-level directories is a loud error); files under it that belong to no tagged service are excluded from every SHA rather than shared into all of them. |
 | `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 from `workloads/images.yml` and the legacy `compose*.bake.yml` names (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 — across the `workloads/` and `docker/` Dockerfile trees and the `stack/score/` + `score/` source trees; `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. |
-| `mirror.py` | The mirror namespace's config, inversion, and verbs. `MirrorConfig` (model in `config.py`, the `mirror:` section, key `prefix`), `load_mirror_config()` (reads the `mirror:` section via `config.load_config`, `None` when the section or file is absent), `is_mirrored`/`upstream_ref` (prefix inversion preserving the `:tag@sha256:…` tail), `reference_exists` (imagetools existence probe honoring docker config creds), `mirror_targets` (declared refs filtered by prefix, sorted), the `mirror` verb (crane install + per-target `crane copy`), and `up`'s fallback helpers (`upstream_fallback`, `write_fallback_overlay`). Constraints in "Mirror namespace and upstream fallback". |
+| `image_refs.py` | Image-reference collection, split by source. `declared_references(root)` enumerates bake `x-base-images` declarations from `workloads/images.yml` (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 — across the `workloads/` and `docker/` Dockerfile trees and the `stack/score/` + `score/` source trees; `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. |
+| `mirror.py` | The mirror namespace's config, injection, and verbs. `MirrorConfig` (model in `config.py`, the `mirror:` section, key `prefix`), `load_mirror_config()` (reads the `mirror:` section via `config.load_config`, `None` when the section or file is absent), `mirrored_ref` (prefix injection with the double-prefix guard), `reference_exists` (imagetools existence probe honoring docker config creds), `enforce_mirrored` (`up`'s fail-closed probe over lock values), and the `mirror` verb (crane install + one `crane copy {ref} {prefix}/{ref}` per declared reference). Constraints in "Mirror namespace". |
 
 ## Lifecycle declaration contract
 
@@ -47,23 +47,22 @@ placeframe's shape lives in placeframe's `docker-devkit.yaml`, not in this packa
 ## 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://`.
-- `workloads/images.lock` (required in every repo, checked in) — third-party and base-image pins, written by `build`: one `NAME=path:tag@sha256:…` entry per manifest declaration. `up`/`down` refuse without it; consumers satisfy it with a committed lock filling the `${…_IMAGE:?err}` holes. The legacy name `.env.lock` resolves while the manifest still carries its legacy name; the lock always sits beside its manifest as the resolved pair.
-- `workloads/images.yml` (where a local build graph exists, required) — the image manifest and 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`. The legacy root name `compose.bake.yml` resolves identically. `build` reads exactly one manifest: the first of `workloads/images.yml`, `compose.bake.yml` that exists. `buildx bake` resolves the manifest's relative paths against its invocation cwd, so `build` always invokes from the repo root.
+- `workloads/images.lock` (required in every repo, checked in) — third-party and base-image pins, written by `build`: one `NAME={prefix}/{ref}@sha256:…` entry per manifest declaration. `up`/`down` refuse without it; consumers satisfy it with a committed lock filling the `${…_IMAGE:?err}` holes. The lock sits beside its manifest as the resolved pair.
+- `workloads/images.yml` (where a local build graph exists, required) — the image manifest and 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`. `build` reads exactly one manifest: `workloads/images.yml`. `buildx bake` resolves the manifest's relative paths against its invocation cwd, so `build` always invokes from the repo root.
 - the compose layers declared in the `lifecycle:` section of `docker-devkit.yaml`; 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.
 
 `build` injects the `tree-<hash>` tags of locally-built images into the environment rather than writing them anywhere; `up`/`down` do the same via `compute_service_shas`. The lock stays a pure third-party pin file — a CI invariant forbids built-image digests in the committed, reviewed lock.
 
-## Mirror namespace and upstream fallback
+## Mirror namespace
 
 Third-party images are consumed through an org-owned mirror namespace (`ghcr.io/outernet-foundation/mirror/<upstream-host>/<path>…`) instead of pulling upstream registries directly: manifests at upstream get GC'd, and an upstream yank once broke external cloners — digest pins alone don't save you when the manifest is gone. Durability for strangers beats upstream egress: strangers, CI, and prod always pull the mirror. Populating it is CI's job, single writer — engineers never push to the org namespace, and error text must never teach them to (no "run this populate command" hints).
 
-The mirror is declared, not inferred: the `mirror:` section with `prefix` in the consumer's root `docker-devkit.yaml`. Absent section → all mirror behavior off. Under the section:
+Declarations are upstream-native and the mirror-prefixed form is derived: `x-base-images` values spell the upstream reference, and the `mirror:` section's `prefix` in the consumer's root `docker-devkit.yaml` is the single place the namespace is named. `mirrored_ref(reference, prefix)` is the only join — it injects the prefix and rejects an already-prefixed reference (the double-prefix guard: drift toward the namespace is a loud error, never a silent skip). Declaring `x-base-images` with no `mirror:` section is a hard `build` error; the `mirror` verb requires the section outright. Under the section:
 
-- `build` resolves lock digests for mirror-prefixed declarations against the upstream reference (prefix stripped, tag/digest tail preserved) and records it under the mirror name. Valid because `crane copy` produces byte-identical manifests — upstream and mirror digests are the same digest; a manifest re-wrap (`docker buildx imagetools`-shaped tooling) would change the top-level digest and break lock equality. This makes declare → re-lock walkable before CI has mirrored anything; lock lines are never hand-authored.
-- `up` fails closed: after lock resolution it probes each mirror-prefixed lock entry; a missing mirror image is a hard `RuntimeError`, not a warning — people ignore warnings, and warnings are errors someone was too lazy to fix. The only escape is the per-run `--allow-upstream-fallback` flag. Under the flag, missing entries become digest-preserving address substitutions (same bytes from the upstream host), printed as plain statements — the operator asked for fallback, the run reports what it did. The rewrite is authoritative on both consumption paths: an appended `--env-file` overlay (compose's later env files win) plus `os.environ` before `build`'s bake (shell env wins over env files; `run_build` re-applies the overlay after its own lock update so bake is never clobbered). CI never passes the flag — the mirror job runs before anything needs the images.
-- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints — it needs nothing from any runner floor.
-- Non-mirror lock entries (e.g. `placeframe/*` publishes) are not probed and keep failing naturally at pull. There is no config-level ban on the flag: an air-gap fails closed anyway (no route to upstream — the pull dies with or without it).
+- `build` resolves lock digests against the upstream reference and records each entry under the derived mirror name (`NAME={prefix}/{ref}@sha256:…`). Valid because `crane copy` produces byte-identical manifests — upstream and mirror digests are the same digest; a manifest re-wrap (`docker buildx imagetools`-shaped tooling) would change the top-level digest and break lock equality. This makes declare → re-lock walkable before CI has mirrored anything; lock lines are never hand-authored.
+- `up` fails closed: it probes every lock entry (each is mirror-prefixed by construction); a missing mirror image is a hard `RuntimeError`, not a warning — people ignore warnings, and warnings are errors someone was too lazy to fix. There is no escape flag: a missing entry means the declaring change has not been through CI's mirror job yet, and the fix is to let it run. CI ordering never wants the escape — the mirror job runs before anything needs the images.
+- The `mirror` verb (crane install from a pinned release, one `crane copy {ref} {prefix}/{ref}` per declared reference, count footer) uses bashrun + plain prints — it needs nothing from any runner floor. Every declared reference is a target; nothing is filtered by prefix, so a drifted declaration cannot silently mirror zero.
 
 The build-artifact-registry edge exists for the builds shelf: a `build --push` run distills bake's `--metadata-file` into a digest manifest (`target → {ref, digest, tags[]}` JSON) and pushes it through build-artifact-registry's `push_build` — one **shard** per matrix leg, tagged `sha-{full}-{key}` where the key is the sha256-8 of the leg's sorted targets (legs run in parallel, so a shared tag would be last-writer-wins; the pull side enumerates a SHA's shards and merges, and consumption only ever runs after every leg finished). The shelf root comes from the neutral `REGISTRY` environment and the SHA from the checkout HEAD (`git rev-parse HEAD`), stamping the certified PR head the release channels query back at; the keying law is stated in github-actions-toolkit's `AGENTS.md`. `workloads/images.lock` stays in source control (the stapler that consumed the shelf copy is gone). ORAS CLI knowledge lives only in build-artifact-registry (org law); local builds (no `--push`) never touch the shelf.
 

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/PKG-INFO

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

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-devkit"
-version = "0.3.0.dev113"
+version = "0.4.0"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/release-devkit.yaml

@@ -1,6 +1,6 @@
 packages:
   docker-devkit:
     path: .
-    major_minor: "0.3"
+    major_minor: "0.4"
     registry: pypi
     identity: docker-devkit

docker_devkit-0.4.0/scripts/preflight.py

@@ -0,0 +1,3 @@
+from bashrun.bash import bash
+
+bash("uv run --locked preflight-python")

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/src/docker_devkit/build_docker.py

@@ -14,6 +14,7 @@ import typer
 from bashrun.bash import bash, bash_output
 from build_artifact_registry.builds import push_build
 from build_artifact_registry.setup_oras import install_oras
+from .config import MirrorConfig
 from .detect_gpu import GPU_TYPES, Gpu, detect_gpu
 from .documents import BakeDocument, digest_pinned, parse_bake
 from pydantic_settings import BaseSettings
@@ -21,7 +22,7 @@ from .context_sha import compute_service_shas
 
 from .image_refs import bake_base_image_refs, resolve_remote_digest
 from .lifecycle import require_manifest, resolve_lock
-from .mirror import is_mirrored, load_mirror_config, upstream_ref
+from .mirror import load_mirror_config, mirrored_ref
 from .modes import parse_env_file
 
 
@@ -85,11 +86,10 @@ def run_build(
     lock_only: bool = False,
     gpu_only: bool = False,
     no_cache: bool = False,
-    env_overlay: dict[str, str] | None = None,
 ) -> None:
     root = Path.cwd()
     manifest = require_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
     mirror_config = load_mirror_config(root)
 
     bake = parse_bake(manifest)
@@ -117,24 +117,7 @@ def run_build(
     if gpu == "auto" and not lock_only:
         gpu = detect_gpu()
 
-    # One lock entry per declared third-party image: NAME=path:tag@sha256:…
-    # Mirror-prefixed declarations resolve their digest against upstream (crane copies
-    # are byte-identical, so the digest is valid under both names) and record it under
-    # the mirror name — declaring and re-locking works before CI has mirrored anything.
-    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
-        inspect_target = occurrence.reference
-        if mirror_config is not None and is_mirrored(occurrence.reference, mirror_config.prefix):
-            inspect_target = upstream_ref(occurrence.reference, mirror_config.prefix)
-        lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(inspect_target)}"
+    update_lock_entries(bake, mirror_config, lock_data, upgrade=upgrade)
 
     # Update main lock file
     lock_file.write_text(
@@ -147,8 +130,6 @@ def run_build(
 
     # Update environment with external dependency image digests
     os.environ.update(lock_data)
-    if env_overlay:
-        os.environ.update(env_overlay)
 
     # Build command arguments
     command_arguments: list[str] = []
@@ -226,6 +207,31 @@ def run_build(
         push_image_digests(shelf, sha, baked_images, targets)
 
 
+# One lock entry per declared third-party image: NAME={prefix}/{ref}@sha256:… — the
+# mirror-prefixed form is derived from the mirror prefix, the digest resolves against
+# the upstream reference (crane copies are byte-identical, so the digest is valid
+# under both names) and records under the mirror name.
+def update_lock_entries(
+    bake: BakeDocument,
+    mirror_config: MirrorConfig | None,
+    lock_data: dict[str, str],
+    *,
+    upgrade: bool,
+) -> None:
+    if not bake.base_images:
+        return
+    if mirror_config is None:
+        raise RuntimeError("x-base-images declared without a mirror section in docker-devkit.yaml")
+    for occurrence in bake_base_image_refs(bake):
+        lock_base = mirrored_ref(occurrence.reference, mirror_config.prefix)
+        if digest_pinned(occurrence.reference):
+            lock_data[occurrence.name] = lock_base
+            continue
+        if not upgrade and occurrence.name in lock_data and lock_data[occurrence.name].startswith(lock_base + "@"):
+            continue
+        lock_data[occurrence.name] = f"{lock_base}@{resolve_remote_digest(occurrence.reference)}"
+
+
 def leg_key(targets: list[str]) -> str:
     return hashlib.sha256(",".join(sorted(targets)).encode("utf-8")).hexdigest()[:8]
 

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/src/docker_devkit/down.py

@@ -31,7 +31,7 @@ def down(
     config = load_lifecycle_config(root)
     enforce_bake_declaration(root, config)
     manifest = resolve_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
 
     if not ENV_FILE.exists():
         raise RuntimeError("No .env file found")

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/src/docker_devkit/image_refs.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-import datetime
+import datetime as dt
 import re
 import shlex
 import tomllib
@@ -12,6 +12,7 @@ from bashrun.bash import bash_output
 from pydantic import RootModel
 
 from .documents import BakeDocument, parse_bake
+from .lifecycle import MANIFEST_PATH
 
 BUILD_ARG_PATTERN = re.compile(r"\$\{[A-Za-z0-9_]+\}")
 FROM_PATTERN = re.compile(r"^FROM\s+(?:--platform=\S+\s+)?(\S+)", re.MULTILINE)
@@ -21,17 +22,7 @@ DIGEST_PATTERN = re.compile(r"^Digest:\s+(sha256:[a-f0-9]+)", re.MULTILINE)
 MISSING_VERSION = "<missing>"
 
 
-type TomlValue = (
-    str
-    | int
-    | float
-    | bool
-    | datetime.datetime
-    | datetime.date
-    | datetime.time
-    | list[TomlValue]
-    | dict[str, TomlValue]
-)
+type TomlValue = str | int | float | bool | dt.datetime | dt.date | dt.time | list[TomlValue] | dict[str, TomlValue]
 
 
 class TomlDocument(RootModel[TomlValue]):
@@ -70,15 +61,11 @@ def unpinned_references(root: Path) -> list[str]:
     ]
 
 
-def declared_references(
-    root: Path, bake_globs: tuple[str, ...] = ("workloads/images.yml", "compose*.bake.yml")
-) -> list[ImageReference]:
-    return [
-        reference
-        for bake_glob in bake_globs
-        for path in sorted(root.glob(bake_glob))
-        for reference in bake_base_image_refs(parse_bake(path))
-    ]
+def declared_references(root: Path) -> list[ImageReference]:
+    manifest = root / MANIFEST_PATH
+    if not manifest.exists():
+        return []
+    return bake_base_image_refs(parse_bake(manifest))
 
 
 def stray_references(

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/src/docker_devkit/lifecycle.py

@@ -8,11 +8,9 @@ from .detect_gpu import Gpu
 DEFAULT_COMPOSE_FILE = Path("compose.yml")
 GPU_PLACEHOLDER = "{gpu}"
 
-# The image manifest and its lock are a named pair living in the same directory. The
-# legacy names keep resolving so a repo can upgrade the devkit before moving its files.
-MANIFEST_CANDIDATES = (Path("workloads/images.yml"), Path("compose.bake.yml"))
-MANIFEST_LOCK_PAIR = {"images.yml": "images.lock", "compose.bake.yml": ".env.lock"}
-LOCK_CANDIDATES = (Path("workloads/images.lock"), Path(".env.lock"))
+# The image manifest and its lock are a named pair living in the same directory.
+MANIFEST_PATH = Path("workloads/images.yml")
+LOCK_PATH = Path("workloads/images.lock")
 
 
 def load_lifecycle_config(root: Path) -> LifecycleConfig | None:
@@ -21,27 +19,25 @@ def load_lifecycle_config(root: Path) -> LifecycleConfig | None:
 
 
 def resolve_manifest(root: Path) -> Path | None:
-    return next((root / candidate for candidate in MANIFEST_CANDIDATES if (root / candidate).exists()), None)
+    manifest = root / MANIFEST_PATH
+    return manifest if manifest.exists() else None
 
 
 def require_manifest(root: Path) -> Path:
     manifest = resolve_manifest(root)
     if manifest is None:
-        raise RuntimeError(f"No image manifest found; {MANIFEST_CANDIDATES[0]} is the canonical name")
+        raise RuntimeError(f"No image manifest at {MANIFEST_PATH}")
     return manifest
 
 
-def resolve_lock(root: Path, manifest: Path | None) -> Path:
-    if manifest is not None:
-        return manifest.parent / MANIFEST_LOCK_PAIR[manifest.name]
-    existing = next((root / candidate for candidate in LOCK_CANDIDATES if (root / candidate).exists()), None)
-    return existing if existing is not None else root / LOCK_CANDIDATES[0]
+def resolve_lock(root: Path) -> Path:
+    return root / LOCK_PATH
 
 
 def enforce_bake_declaration(root: Path, config: LifecycleConfig | None) -> None:
-    if config is None and any((root / candidate).exists() for candidate in MANIFEST_CANDIDATES):
+    if config is None and (root / MANIFEST_PATH).exists():
         raise RuntimeError(
-            "image manifest present without a lifecycle section in docker-devkit.yaml; declare the section or rename the file"
+            "image manifest present without a lifecycle section in docker-devkit.yaml; declare the section"
         )
 
 

docker_devkit-0.4.0/src/docker_devkit/mirror.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+import typer
+from bashrun.bash import bash, bash_check
+
+from .config import MirrorConfig, load_config
+from .image_refs import declared_references
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+CRANE_VERSION = "v0.22.1"
+
+
+@app.command()
+def mirror() -> None:
+    root = Path.cwd()
+    config = load_mirror_config(root)
+    if config is None:
+        raise RuntimeError("a mirror section with 'prefix' is required in docker-devkit.yaml to mirror")
+
+    targets = sorted(declared_references(root), key=lambda occurrence: occurrence.reference)
+    print(f"Install crane {CRANE_VERSION}")
+    sudo = "sudo " if os.geteuid() != 0 else ""
+    archive = "go-containerregistry_Linux_x86_64.tar.gz"
+    bash(f"curl -fsSLO https://github.com/google/go-containerregistry/releases/download/{CRANE_VERSION}/{archive}")
+    bash(f"{sudo}tar -xzf {archive} -C /usr/local/bin crane")
+    Path(archive).unlink()
+    for target in targets:
+        destination = mirrored_ref(target.reference, config.prefix)
+        print(f"Mirror {target.reference} -> {destination}")
+        bash(f"crane copy {target.reference} {destination}")
+    print(f"Mirrored images: {len(targets)}")
+
+
+def load_mirror_config(root: Path) -> MirrorConfig | None:
+    config = load_config(root)
+    return config.mirror if config is not None else None
+
+
+def mirrored_ref(reference: str, prefix: str) -> str:
+    if reference.startswith(f"{prefix}/"):
+        raise RuntimeError(
+            f"x-base-images values are upstream-native; {reference} already carries the mirror prefix {prefix}"
+        )
+    return f"{prefix}/{reference}"
+
+
+def reference_exists(reference: str) -> bool:
+    return bash_check(f"docker buildx imagetools inspect {shlex.quote(reference)}")
+
+
+def enforce_mirrored(lock_data: dict[str, str]) -> None:
+    for value in sorted(lock_data.values()):
+        if reference_exists(value):
+            continue
+        reference, _, digest = value.rpartition("@")
+        raise RuntimeError(
+            f"Image {reference or value} (digest {digest or 'unknown'}) is not mirrored yet; "
+            "the CI mirror job populates it when the declaring change runs"
+        )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

{docker_devkit-0.3.0.dev113 → docker_devkit-0.4.0}/src/docker_devkit/up.py

@@ -16,7 +16,7 @@ from .lifecycle import (
     resolve_lock,
     resolve_manifest,
 )
-from .mirror import load_mirror_config, upstream_fallback, write_fallback_overlay
+from .mirror import enforce_mirrored, load_mirror_config
 from .modes import parse_env_file, resolve_auth_mode
 
 ENV_FILE = Path(".env")
@@ -42,19 +42,12 @@ def up(
         "--dev",
         help="Layer the declared dev overlay (compose.dev.yml shape) over the production stack for bind-mount/debug bring-up.",
     ),
-    allow_upstream_fallback: Annotated[
-        bool,
-        typer.Option(
-            "--allow-upstream-fallback",
-            help="Pull unmirrored lock entries from upstream at the same digest instead of failing closed.",
-        ),
-    ] = False,
 ) -> None:
     root = Path.cwd()
     config = load_lifecycle_config(root)
     enforce_bake_declaration(root, config)
     manifest = resolve_manifest(root)
-    lock_file = resolve_lock(root, manifest)
+    lock_file = resolve_lock(root)
 
     if dev and (config is None or config.dev_file is None):
         raise RuntimeError("--dev requires a dev_file in the lifecycle section of docker-devkit.yaml")
@@ -75,21 +68,12 @@ def up(
 
     auth_mode = resolve_auth_mode(ENV_FILE)
 
-    substitutions: dict[str, str] = {}
-    fallback_overlay: Path | None = None
     mirror_config = load_mirror_config(root)
     if mirror_config is not None:
-        substitutions = upstream_fallback(
-            parse_env_file(lock_file), mirror_config.prefix, allow_upstream_fallback=allow_upstream_fallback
-        )
-        if substitutions:
-            for name, upstream in sorted(substitutions.items()):
-                print(f"Falling back to upstream for {name}: {upstream}", flush=True)
-            os.environ.update(substitutions)
-            fallback_overlay = write_fallback_overlay(substitutions)
+        enforce_mirrored(parse_env_file(lock_file))
 
     if build:
-        run_build(gpu=gpu, env_overlay=substitutions)
+        run_build(gpu=gpu)
 
     if manifest is not None:
         os.environ.update(compute_service_shas(root, parse_bake(manifest)))
@@ -101,8 +85,6 @@ def 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}--project-directory {root} --env-file .env --env-file {lock_file}"
-    if fallback_overlay is not None:
-        compose_args += f" --env-file {fallback_overlay}"
 
     up_command = f"docker compose {compose_args} up"
     if not build: