docker-devkit 0.1.15__tar.gz → 0.1.17__tar.gz

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/AGENTS.md

@@ -18,35 +18,34 @@ 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` (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). |
+| `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). `--mode ci` hard-requires `x-registry-cache` in the manifest. |
+| `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 `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). 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. |
+| `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), `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). |
 | `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(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. |
+| `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 (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. |
+| `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. |
 
 ## Constraints
 
 ### Lifecycle declaration contract
 
-**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`).
+**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 an image 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 lock 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 `${…_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.
+**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. The image lock is required unconditionally, no knob; consumers pin stock images via `${…_IMAGE:?err}` holes filled by a committed lock. An image manifest present under either resolved name 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 manifest remains the build/up contract: SHA injection and `--build` acceptance key on the manifest existing, and `build` always reads the resolved manifest. `up`/`down` pass `--project-directory` (the invocation root) explicitly, so compose files living in nested trees (`stack/generated/compose/`, overlays) anchor their relative paths at the repo root instead of the first `-f` file's directory. 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`.
+**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 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 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.
+- `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.
 - 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.
+`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.
 
 ### Package split rationale
 

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.15
+Version: 0.1.17
 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.15 → docker_devkit-0.1.17}/README.md

@@ -1,8 +1,8 @@
 # docker-devkit
 
-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`.
+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 + `workloads/images.yml`) declares its file layers and gets multi-file assembly, per-service SHA injection, and `workloads/images.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 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 declaration contract.
+See [`AGENTS.md`](./AGENTS.md) for the file/layout conventions the commands assume (`workloads/images.yml` + `workloads/images.lock` — with the legacy root `compose.bake.yml` + `.env.lock` pair still resolved — and `PUBLIC_URL` / `AUTH_MODE` in `.env`) and the declaration contract.
 
 ## Setup
 
@@ -19,12 +19,12 @@ From a stack repo's root:
 ```bash
 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 --build              # build images locally first (requires workloads/images.yml)
 uv run up --gpu none           # override GPU auto-detection
 uv run down                    # docker compose down
 uv run down -v                 # also remove named volumes
-uv run build                   # cross-build all images per compose.bake.yml
-uv run build --lock-only       # refresh .env.lock without building
+uv run build                   # cross-build all images per workloads/images.yml
+uv run build --lock-only       # refresh the image lock without building
 uv run generate-score          # regenerate Score compose/k8s manifests per [tool.docker-devkit.generate-score]
 uv run generate-score --local  # local-cluster variant (local storage class, gitignored output)
 ```

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/plan.md

@@ -1,18 +1,22 @@
 # One home for third-party image declarations; docker-devkit stops parsing compose
 
-Status note for pickup: the docker-devkit half is DONE — redesign executed in
-`2a1fe90` (compose parsing deleted, `declared_references`/`stray_references`
-split, `BakeDocument` base-images validator, typed bake plumbing through
-build/up/down/generate-score, ci-mode registry-cache guard). pytest 77 green,
-ruff + basedpyright clean — the checkpoint's intentional failures are gone.
-Still pending, in order: operator push + tag-ledger release of this repo;
-release-devkit 0.1.11 (`mirror_images.py` → `declared_references`); the
-placeframe PR; capture-tool renames. No consumer repo has been touched yet.
-
-Note on release numbering: the plan projects 0.1.15, but the local tag ledger
-sits at docker-devkit-v0.1.11 with the lifecycle rewrite also unreleased —
-patch-auto will compute the real number at publish time, and the placeframe
-repin must use whatever ships, not the projection.
+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-0.1.15 → docker_devkit-0.1.17}/pyproject.toml

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

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/src/docker_devkit/build_docker.py

@@ -13,9 +13,10 @@ 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, resolve_remote_digest
+from .lifecycle import require_manifest, resolve_lock
 from .modes import parse_env_file
 
 
@@ -25,9 +26,6 @@ class Settings(BaseSettings):
 
 settings = Settings.model_validate({})
 
-LOCK_FILE = Path(".env.lock")
-ENV_SHAS_FILE = Path(".env.shas")
-DEFAULT_BAKE_FILE = Path("compose.bake.yml")
 METADATA_PATH = Path("metadata.json")
 
 Mode = Literal["local", "ci"]
@@ -50,7 +48,7 @@ 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 compose.bake.yml)."),
+        typer.Option("--targets", "-t", help="Build only these services (from the image manifest)."),
     ] = None,
 ) -> None:
     run_build(
@@ -74,18 +72,17 @@ def run_build(
     no_cache: bool = False,
     targets_opt: list[str] | None = None,
 ) -> None:
-    bake = parse_bake(DEFAULT_BAKE_FILE)
+    root = Path.cwd()
+    manifest = require_manifest(root)
+    lock_file = resolve_lock(root, manifest)
 
-    service_shas = compute_service_shas(Path.cwd(), bake)
-    os.environ.update(service_shas)
+    bake = parse_bake(manifest)
 
-    # 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"
-    )
+    service_shas = compute_service_shas(root, bake)
+    os.environ.update(service_shas)
 
     # Load any existing lock
-    lock_data = parse_env_file(LOCK_FILE) if LOCK_FILE.exists() else {}
+    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":
@@ -119,7 +116,7 @@ def run_build(
         lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(occurrence.reference)}"
 
     # Update main lock file
-    LOCK_FILE.write_text(
+    lock_file.write_text(
         "# Generated by lock.py\n" + "\n".join(f"{key}={value}" for key, value in sorted(lock_data.items())) + "\n",
         encoding="utf-8",
     )
@@ -183,7 +180,7 @@ def run_build(
     # Bake images
     command = [
         "docker buildx bake",
-        f"-f {DEFAULT_BAKE_FILE}",
+        f"-f {manifest}",
         f"--metadata-file {METADATA_PATH}",
         "--progress auto",
         "--provenance=false",

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/src/docker_devkit/context_sha.py

@@ -18,6 +18,8 @@ def compute_service_shas(repo_root: Path, bake: BakeDocument) -> dict[str, str]:
             continue
         service_dirs.add(str(PurePosixPath(config.build.dockerfile).parent))
 
+    workload_root = _workload_root(service_dirs)
+
     tree_entries = bash_output("git ls-tree -r HEAD", cwd=repo_root).splitlines()
 
     dockerignore = repo_root / ".dockerignore"
@@ -31,12 +33,12 @@ def compute_service_shas(repo_root: Path, bake: BakeDocument) -> dict[str, str]:
         mode, _type, obj_hash = meta.split()
         allowed_entries.append((mode, obj_hash, path))
 
-    docker_prefix = "docker/"
+    workload_prefix = workload_root.as_posix() + "/" if workload_root is not None else None
     shared_entries: list[tuple[str, str, str]] = []
     per_service: dict[str, list[tuple[str, str, str]]] = {d: [] for d in service_dirs}
 
     for mode, obj_hash, path in allowed_entries:
-        if path.startswith(docker_prefix):
+        if workload_prefix is not None and path.startswith(workload_prefix):
             for service_dir in service_dirs:
                 if path.startswith(service_dir + "/"):
                     per_service[service_dir].append((mode, obj_hash, path))
@@ -57,3 +59,15 @@ def compute_service_shas(repo_root: Path, bake: BakeDocument) -> dict[str, str]:
         result[PurePosixPath(service_dir).name.upper().replace("-", "_") + "_SHA"] = f"tree-{tree_hash}"
 
     return result
+
+
+def _workload_root(service_dirs: set[str]) -> PurePosixPath | None:
+    # The workload tree root is the single top-level directory containing every tagged
+    # service. Files under it that belong to no tagged service are excluded from every
+    # SHA: they are workload-tree content, not shared build context.
+    tops = {PurePosixPath(service_dir).parts[0] for service_dir in service_dirs if PurePosixPath(service_dir).parts}
+    if not tops:
+        return None
+    if len(tops) > 1:
+        raise RuntimeError(f"Bake services span multiple top-level directories: {sorted(tops)}")
+    return PurePosixPath(next(iter(tops)))

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/src/docker_devkit/down.py

@@ -8,11 +8,16 @@ 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 .lifecycle import (
+    enforce_bake_declaration,
+    expand_compose_files,
+    load_lifecycle_config,
+    resolve_lock,
+    resolve_manifest,
+)
 from .modes import resolve_auth_mode
 
 ENV_FILE = Path(".env")
-LOCK_FILE = Path(".env.lock")
 
 app = typer.Typer(add_completion=False)
 
@@ -22,22 +27,27 @@ 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)
+    root = Path.cwd()
+    config = load_lifecycle_config(root)
+    enforce_bake_declaration(root, config)
+    manifest = resolve_manifest(root)
+    lock_file = resolve_lock(root, manifest)
 
     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 not lock_file.exists():
+        raise RuntimeError(
+            f"No image lock at {lock_file}; 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(), parse_bake(BAKE_FILE)))
+    if manifest is not None:
+        os.environ.update(compute_service_shas(root, parse_bake(manifest)))
 
     # 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)
@@ -48,9 +58,10 @@ def down(
     command = (
         "docker compose "
         f"{files_args} "
+        f"--project-directory {root} "
         "--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} "
+        f"--env-file {lock_file} "
         "down --remove-orphans"
     )
 

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/src/docker_devkit/image_refs.py

@@ -70,30 +70,39 @@ def unpinned_references(root: Path) -> list[str]:
     ]
 
 
-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 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 stray_references(
     root: Path,
-    dockerfile_glob: str = "docker/*/Dockerfile*",
-    image_glob: str = "score/*.yaml",
+    dockerfile_globs: tuple[str, ...] = ("workloads/*/Dockerfile*", "docker/*/Dockerfile*"),
+    image_globs: tuple[str, ...] = ("stack/score/*.yaml", "score/*.yaml"),
 ) -> list[ImageReference]:
+    dockerfile_paths = [path for dockerfile_glob in dockerfile_globs for path in sorted(root.glob(dockerfile_glob))]
+    image_paths = [path for image_glob in image_globs for path in sorted(root.glob(image_glob))]
     return (
         [
             ImageReference("", match.group(1))
-            for path in sorted(root.glob(dockerfile_glob))
+            for path in dockerfile_paths
             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 path in dockerfile_paths
             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 path in image_paths
             for match in IMAGE_LINE_PATTERN.finditer(path.read_text(encoding="utf-8"))
         ]
     )

docker_devkit-0.1.17/src/docker_devkit/lifecycle.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+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"))
+
+
+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 resolve_manifest(root: Path) -> Path | None:
+    return next((root / candidate for candidate in MANIFEST_CANDIDATES if (root / candidate).exists()), 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")
+    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 enforce_bake_declaration(root: Path, config: LifecycleConfig | None) -> None:
+    if config is None and any((root / candidate).exists() for candidate in MANIFEST_CANDIDATES):
+        raise RuntimeError(
+            "image manifest 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.15 → docker_devkit-0.1.17}/src/docker_devkit/score_generate.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 import re
+import shlex
 import tomllib
 from collections.abc import Generator
 from contextlib import contextmanager
@@ -46,14 +47,14 @@ class ScoreConfig(BaseModel):
     project_name: str
     cloud_storage_class: str
     local_storage_class: str
-    score_dir: Path = Path("score")
-    bake_file: Path = Path("compose.bake.yml")
-    compose_output: Path = Path("compose.yaml")
-    k8s_output: Path = Path("deploy") / "manifests.yaml"
+    score_dir: Path = Path("stack/score")
+    bake_file: Path = Path("workloads/images.yml")
+    compose_output: Path = Path("stack/generated/compose/compose.yaml")
+    k8s_output: Path = Path("stack/generated/k8s/manifests.yaml")
     # --local writes here instead of the committed k8s output; consumers gitignore this path so a
     # local-only storage class cannot reach the artifact their cluster deploys.
-    k8s_local_output: Path = Path("manifests.yaml")
-    k8s_state: Path = Path(".score-k8s")
+    k8s_local_output: Path = Path("stack/generated/k8s/manifests.local.yaml")
+    k8s_state: Path = Path("stack/generated/k8s/.score-k8s")
     storage_class_var: str = "SCORE_STORAGE_CLASS"
     compose_provisioners: list[str] = Field(default_factory=list)
     compose_patch_templates: list[str] = Field(default_factory=list)
@@ -94,16 +95,17 @@ def load_score_config(root: Path) -> ScoreConfig:
 
 
 def generate(config: ScoreConfig, target: Target = "both", local: bool = False) -> None:
+    root = Path.cwd()
     # The same call up, build, and preflight make, so every image tag is a pure function of
     # committed source rather than a hand-typed value.
-    os.environ.update(compute_service_shas(Path.cwd(), parse_bake(config.bake_file)))
+    os.environ.update(compute_service_shas(root, parse_bake(config.bake_file)))
     os.environ[config.storage_class_var] = config.local_storage_class if local else config.cloud_storage_class
 
     if target in ("both", "compose"):
-        _generate_compose(config)
+        _generate_compose(root, config)
 
     if target in ("both", "k8s"):
-        _generate_k8s(config, config.k8s_local_output if local else config.k8s_output)
+        _generate_k8s(root, config, config.k8s_local_output if local else config.k8s_output)
 
 
 def ensure_score_tools(config: ScoreConfig, bin_dir: Path) -> None:
@@ -116,46 +118,73 @@ def ensure_score_tools(config: ScoreConfig, bin_dir: Path) -> None:
         Path(archive).unlink()
 
 
-def _generate_compose(config: ScoreConfig) -> None:
+def _generate_compose(root: Path, config: ScoreConfig) -> None:
+    # score-compose keeps its state directory inside score_dir; the consumer gitignores it.
     _init_state(
         f"score-compose init --project {config.project_name} --no-sample",
         config.compose_provisioners,
         config.compose_patch_templates,
-        config.score_dir,
+        source_dir=root / config.score_dir,
+        working_dir=root / config.score_dir,
     )
 
+    (root / config.compose_output).parent.mkdir(parents=True, exist_ok=True)
     publishes = "".join(f" --publish {publish}" for publish in config.publishes)
-    with _rendered_workloads(config) as workloads:
+    with _rendered_workloads(root, config) as workloads:
         bash(
-            f"score-compose generate {workloads} --output {config.compose_output.as_posix()}{publishes}",
-            cwd=config.score_dir,
+            f"score-compose generate {workloads} --output {(root / config.compose_output).as_posix()}{publishes}",
+            cwd=root / config.score_dir,
         )
 
 
-def _generate_k8s(config: ScoreConfig, output: Path) -> None:
-    _init_state("score-k8s init --no-sample", config.k8s_provisioners, [], config.score_dir)
+def _generate_k8s(root: Path, config: ScoreConfig, output: Path) -> None:
+    # score-k8s writes its state directory to the .score-k8s of its cwd; running it from the
+    # generated k8s home keeps the committed state file in the generated tier while the
+    # provisioners still resolve from the authored score sources.
+    state_dir = root / config.k8s_state
+    _init_state(
+        "score-k8s init --no-sample",
+        config.k8s_provisioners,
+        [],
+        source_dir=root / config.score_dir,
+        working_dir=state_dir.parent,
+    )
 
-    (config.score_dir / output).parent.mkdir(parents=True, exist_ok=True)
+    output_path = root / output
+    output_path.parent.mkdir(parents=True, exist_ok=True)
 
-    with _rendered_workloads(config) as workloads:
-        bash(f"score-k8s generate {workloads} --output {output.as_posix()}", cwd=config.score_dir)
+    with _rendered_workloads(root, config) as workloads:
+        bash(f"score-k8s generate {workloads} --output {output_path.as_posix()}", cwd=state_dir.parent)
 
-    sort_documents(config.score_dir / output)
-    normalise_state_paths(config, config.score_dir / config.k8s_state / "state.yaml")
+    sort_documents(output_path)
+    normalise_state_paths(config, state_dir / "state.yaml")
 
 
-def _init_state(command: str, provisioners: list[str], patch_templates: list[str], score_dir: Path) -> None:
+def _init_state(
+    command: str,
+    provisioners: list[str],
+    patch_templates: list[str],
+    *,
+    source_dir: Path,
+    working_dir: Path,
+) -> None:
     # init is idempotent over an existing state directory: it rewrites the provisioner copies
     # without disturbing state. The state must survive, because score-k8s mints a random uid per
     # workload on first add and emits it as the app.kubernetes.io/instance label — discarding it
     # would change the generated manifests on every run.
-    flags = "".join(f" --provisioners ./{name}" for name in provisioners)
-    flags += "".join(f" --patch-templates ./{name}" for name in patch_templates)
-    bash(f"{command}{flags}", cwd=score_dir)
+    # Provisioner and template paths are passed relative to the working directory so no
+    # absolute machine path can reach a committed state file.
+    flags = "".join(
+        f" --provisioners {shlex.quote(os.path.relpath(source_dir / name, working_dir))}" for name in provisioners
+    )
+    flags += "".join(
+        f" --patch-templates {shlex.quote(os.path.relpath(source_dir / name, working_dir))}" for name in patch_templates
+    )
+    bash(f"{command}{flags}", cwd=working_dir)
 
 
 @contextmanager
-def _rendered_workloads(config: ScoreConfig) -> Generator[str]:
+def _rendered_workloads(root: Path, config: ScoreConfig) -> Generator[str]:
     # Workload files are Score spec documents, not Go templates, so they cannot read the
     # environment the way the provisioner files can. Expanding ${API_SHA} into a rendered copy
     # keeps one mechanism across both halves.
@@ -163,7 +192,7 @@ def _rendered_workloads(config: ScoreConfig) -> Generator[str]:
         directory = Path(temporary_directory)
 
         for name in config.workloads:
-            source = (config.score_dir / name).read_text(encoding="utf-8")
+            source = (root / config.score_dir / name).read_text(encoding="utf-8")
             (directory / name).write_text(expand_placeholders(source, name, config.bake_file), "utf-8")
 
         yield " ".join((directory / name).as_posix() for name in config.workloads)

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/src/docker_devkit/up.py

@@ -9,11 +9,16 @@ from .detect_gpu import Gpu, detect_gpu
 from .build_docker import run_build
 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 .lifecycle import (
+    enforce_bake_declaration,
+    expand_compose_files,
+    load_lifecycle_config,
+    resolve_lock,
+    resolve_manifest,
+)
 from .modes import resolve_auth_mode
 
 ENV_FILE = Path(".env")
-LOCK_FILE = Path(".env.lock")
 
 app = typer.Typer(add_completion=False)
 
@@ -37,8 +42,11 @@ def up(
         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)
+    root = Path.cwd()
+    config = load_lifecycle_config(root)
+    enforce_bake_declaration(root, config)
+    manifest = resolve_manifest(root)
+    lock_file = resolve_lock(root, manifest)
 
     if dev and (config is None or config.dev_file is None):
         raise RuntimeError("--dev requires a dev_file in [tool.docker-devkit.lifecycle]")
@@ -46,11 +54,13 @@ def up(
     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 not lock_file.exists():
+        raise RuntimeError(
+            f"No image lock at {lock_file}; 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 build and manifest is None:
+        raise typer.BadParameter("--build requires an image manifest (workloads/images.yml)")
 
     if gpu == "auto":
         gpu = detect_gpu()
@@ -60,8 +70,8 @@ def up(
     if build:
         run_build(gpu=gpu)
 
-    if BAKE_FILE.exists():
-        os.environ.update(compute_service_shas(Path.cwd(), parse_bake(BAKE_FILE)))
+    if manifest is not None:
+        os.environ.update(compute_service_shas(root, parse_bake(manifest)))
 
     compose_files = expand_compose_files(config, gpu, include_dev=dev)
     if not compose_files:
@@ -69,7 +79,7 @@ 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}--env-file .env --env-file {LOCK_FILE}"
+    compose_args = f"{files_args} {profile_flag}--project-directory {root} --env-file .env --env-file {lock_file}"
 
     up_command = f"docker compose {compose_args} up"
     if not build:

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/tests/test_context_sha.py

@@ -3,26 +3,26 @@ from pathlib import Path
 
 import pytest
 from docker_devkit.context_sha import compute_service_shas
-from docker_devkit.documents import parse_bake
+from docker_devkit.documents import BakeDocument, parse_bake
 
 BAKE_CONTENT = """\
 services:
   app:
     build:
       context: .
-      dockerfile: docker/app/Dockerfile
+      dockerfile: workloads/app/Dockerfile
       tags:
         - "registry/app:${APP_SHA}"
   worker:
     build:
       context: .
-      dockerfile: docker/worker/Dockerfile
+      dockerfile: workloads/worker/Dockerfile
       tags:
         - "registry/worker:${WORKER_SHA}"
   base:
     build:
       context: .
-      dockerfile: docker/base/Dockerfile
+      dockerfile: workloads/base/Dockerfile
 """
 
 
@@ -40,71 +40,92 @@ def _commit_all(path: Path) -> None:
 @pytest.fixture()
 def repo(tmp_path: Path) -> Path:
     _init_repo(tmp_path)
-    (tmp_path / ".dockerignore").write_text("*\n!docker/\n!packages/\n")
-    (tmp_path / "docker" / "app").mkdir(parents=True)
-    (tmp_path / "docker" / "app" / "main.py").write_text("print('hello')")
-    (tmp_path / "docker" / "worker").mkdir(parents=True)
-    (tmp_path / "docker" / "worker" / "run.py").write_text("print('work')")
+    (tmp_path / ".dockerignore").write_text("*\n!workloads/\n!packages/\n")
+    (tmp_path / "workloads" / "app").mkdir(parents=True)
+    (tmp_path / "workloads" / "app" / "main.py").write_text("print('hello')")
+    (tmp_path / "workloads" / "worker").mkdir(parents=True)
+    (tmp_path / "workloads" / "worker" / "run.py").write_text("print('work')")
     (tmp_path / "packages").mkdir()
     (tmp_path / "packages" / "lib.py").write_text("x = 1")
     (tmp_path / "README.md").write_text("ignored")
-    bake_file = tmp_path / "compose.bake.yml"
-    bake_file.write_text(BAKE_CONTENT)
+    manifest = tmp_path / "workloads" / "images.yml"
+    manifest.write_text(BAKE_CONTENT)
     _commit_all(tmp_path)
     return tmp_path
 
 
 class TestComputeServiceShas:
     def test_should_return_deterministic_hashes(self, repo: Path):
-        shas1 = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
-        shas2 = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas1 = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
+        shas2 = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
         assert shas1 == shas2
 
     def test_should_have_tree_prefix(self, repo: Path):
-        shas = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
         for sha in shas.values():
             assert sha.startswith("tree-")
 
     def test_should_return_only_tagged_services(self, repo: Path):
-        shas = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
         assert set(shas.keys()) == {"APP_SHA", "WORKER_SHA"}
 
     def test_should_change_only_affected_service_when_service_file_changes(self, repo: Path):
-        shas_before = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_before = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
-        (repo / "docker" / "app" / "main.py").write_text("print('changed')")
+        (repo / "workloads" / "app" / "main.py").write_text("print('changed')")
         _commit_all(repo)
 
-        shas_after = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_after = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
         assert shas_before["APP_SHA"] != shas_after["APP_SHA"]
         assert shas_before["WORKER_SHA"] == shas_after["WORKER_SHA"]
 
     def test_should_change_all_services_when_shared_file_changes(self, repo: Path):
-        shas_before = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_before = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
         (repo / "packages" / "lib.py").write_text("x = 2")
         _commit_all(repo)
 
-        shas_after = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_after = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
         assert shas_before["APP_SHA"] != shas_after["APP_SHA"]
         assert shas_before["WORKER_SHA"] != shas_after["WORKER_SHA"]
 
     def test_should_not_change_when_ignored_file_changes(self, repo: Path):
-        shas_before = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_before = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
         (repo / "README.md").write_text("changed readme")
         _commit_all(repo)
 
-        shas_after = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_after = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
+        assert shas_before == shas_after
+
+    def test_should_not_change_when_untagged_workload_file_changes(self, repo: Path):
+        shas_before = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
+
+        (repo / "workloads" / "loki").mkdir()
+        (repo / "workloads" / "loki" / "config.yaml").write_text("unused by tagged services")
+        _commit_all(repo)
+
+        shas_after = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
         assert shas_before == shas_after
 
     def test_should_not_change_from_uncommitted_edits(self, repo: Path):
-        shas_before = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_before = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
 
-        (repo / "docker" / "app" / "main.py").write_text("print('uncommitted')")
+        (repo / "workloads" / "app" / "main.py").write_text("print('uncommitted')")
 
-        shas_after = compute_service_shas(repo, parse_bake(repo / "compose.bake.yml"))
+        shas_after = compute_service_shas(repo, parse_bake(repo / "workloads" / "images.yml"))
         assert shas_before == shas_after
+
+    def test_should_raise_when_services_span_multiple_top_level_dirs(self, repo: Path):
+        bake = BakeDocument.model_validate({
+            "services": {
+                "app": {"build": {"dockerfile": "workloads/app/Dockerfile", "tags": ["registry/app:latest"]}},
+                "worker": {"build": {"dockerfile": "other/worker/Dockerfile", "tags": ["registry/worker:latest"]}},
+            }
+        })
+
+        with pytest.raises(RuntimeError, match="multiple top-level"):
+            compute_service_shas(repo, bake)

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/tests/test_image_refs.py

@@ -59,14 +59,21 @@ class TestBakeBaseImageRefs:
 
 
 class TestDeclaredReferences:
-    def test_should_yield_bake_declarations(self, tmp_path: Path):
+    def test_should_yield_images_manifest_declarations(self, tmp_path: Path):
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text(
+            "x-base-images:\n  ALPINE_IMAGE: alpine:3.20\n", encoding="utf-8"
+        )
+        assert declared_references(tmp_path) == [ImageReference("ALPINE_IMAGE", "alpine:3.20")]
+
+    def test_should_yield_legacy_bake_declarations(self, tmp_path: Path):
         (tmp_path / "compose.bake.yml").write_text("x-base-images:\n  ALPINE_IMAGE: alpine:3.20\n", encoding="utf-8")
         assert declared_references(tmp_path) == [ImageReference("ALPINE_IMAGE", "alpine:3.20")]
 
     def test_should_return_empty_for_empty_tree(self, tmp_path: Path):
         assert declared_references(tmp_path) == []
 
-    def test_should_scan_only_bake_files(self, tmp_path: Path):
+    def test_should_scan_only_manifests(self, tmp_path: Path):
         (tmp_path / "compose.yml").write_text(
             "services:\n  minio:\n    x-image-ref: docker.io/minio/minio:latest\n", encoding="utf-8"
         )
@@ -82,16 +89,32 @@ class TestDeclaredReferences:
 
 
 class TestStrayReferences:
-    def test_should_collect_dockerfile_and_score_sources(self, tmp_path: Path):
-        docker_directory = tmp_path / "docker" / "api"
-        docker_directory.mkdir(parents=True)
-        (docker_directory / "Dockerfile").write_text(
+    def test_should_collect_workload_and_score_sources(self, tmp_path: Path):
+        workloads_directory = tmp_path / "workloads" / "api"
+        workloads_directory.mkdir(parents=True)
+        (workloads_directory / "Dockerfile").write_text(
             "FROM --platform=linux/amd64 python:3.13-slim AS base\n"
             "COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/\n"
             "COPY --from=base /x /y\n"
             "RUN pip install x\n",
             encoding="utf-8",
         )
+        score_directory = tmp_path / "stack" / "score"
+        score_directory.mkdir(parents=True)
+        (score_directory / "app.provisioners.yaml").write_text(
+            "containers:\n  - name: keycloak\n    image: quay.io/keycloak/keycloak:26.3.5@sha256:abc\n",
+            encoding="utf-8",
+        )
+        assert stray_references(tmp_path) == [
+            ImageReference("", "python:3.13-slim"),
+            ImageReference("", "ghcr.io/astral-sh/uv:latest"),
+            ImageReference("", "quay.io/keycloak/keycloak:26.3.5@sha256:abc"),
+        ]
+
+    def test_should_collect_legacy_layout_sources(self, tmp_path: Path):
+        docker_directory = tmp_path / "docker" / "api"
+        docker_directory.mkdir(parents=True)
+        (docker_directory / "Dockerfile").write_text("FROM python:3.13-slim\n", encoding="utf-8")
         score_directory = tmp_path / "score"
         score_directory.mkdir()
         (score_directory / "app.provisioners.yaml").write_text(
@@ -100,7 +123,6 @@ class TestStrayReferences:
         )
         assert stray_references(tmp_path) == [
             ImageReference("", "python:3.13-slim"),
-            ImageReference("", "ghcr.io/astral-sh/uv:latest"),
             ImageReference("", "quay.io/keycloak/keycloak:26.3.5@sha256:abc"),
         ]
 
@@ -118,7 +140,7 @@ class TestStripBuildArgs:
 
 class TestUnpinnedReferences:
     def test_should_return_empty_when_everything_is_pinned(self, tmp_path: Path):
-        docker_directory = tmp_path / "docker" / "api"
+        docker_directory = tmp_path / "workloads" / "api"
         docker_directory.mkdir(parents=True)
         (docker_directory / "Dockerfile").write_text(
             "FROM ghcr.io/outernet-foundation/mirror/ghcr.io/astral-sh/uv${UV_BASE_DIGEST}\n"
@@ -130,7 +152,7 @@ class TestUnpinnedReferences:
         assert unpinned_references(tmp_path) == []
 
     def test_should_flag_slash_refs_without_tag_digest_or_arg(self, tmp_path: Path):
-        docker_directory = tmp_path / "docker" / "api"
+        docker_directory = tmp_path / "workloads" / "api"
         docker_directory.mkdir(parents=True)
         (docker_directory / "Dockerfile").write_text(
             "FROM ghcr.io/outernet-foundation/mirror/docker.io/library/caddy\n", encoding="utf-8"
@@ -138,7 +160,7 @@ class TestUnpinnedReferences:
         assert unpinned_references(tmp_path) == ["ghcr.io/outernet-foundation/mirror/docker.io/library/caddy"]
 
     def test_should_ignore_stage_names_and_arg_only_refs(self, tmp_path: Path):
-        docker_directory = tmp_path / "docker" / "api"
+        docker_directory = tmp_path / "workloads" / "api"
         docker_directory.mkdir(parents=True)
         (docker_directory / "Dockerfile").write_text(
             "FROM neural-networks-base AS dev\nCOPY --from=build /x /y\n", encoding="utf-8"

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/tests/test_lifecycle.py

@@ -7,6 +7,8 @@ from docker_devkit.lifecycle import (
     enforce_bake_declaration,
     expand_compose_files,
     load_lifecycle_config,
+    resolve_lock,
+    resolve_manifest,
 )
 
 
@@ -101,15 +103,65 @@ class TestExpandComposeFiles:
         assert expand_compose_files(None, "cuda", include_dev=True) == [Path("compose.yml")]
 
 
+class TestResolveManifest:
+    def test_prefers_images_manifest(self, tmp_path: Path):
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text("", encoding="utf-8")
+        (tmp_path / "compose.bake.yml").write_text("", encoding="utf-8")
+
+        assert resolve_manifest(tmp_path) == tmp_path / "workloads" / "images.yml"
+
+    def test_falls_back_to_legacy_bake_file(self, tmp_path: Path):
+        (tmp_path / "compose.bake.yml").write_text("", encoding="utf-8")
+
+        assert resolve_manifest(tmp_path) == tmp_path / "compose.bake.yml"
+
+    def test_returns_none_without_manifest(self, tmp_path: Path):
+        assert resolve_manifest(tmp_path) is None
+
+
+class TestResolveLock:
+    def test_images_manifest_pairs_with_images_lock(self, tmp_path: Path):
+        manifest = tmp_path / "workloads" / "images.yml"
+
+        assert resolve_lock(tmp_path, manifest) == tmp_path / "workloads" / "images.lock"
+
+    def test_legacy_manifest_pairs_with_legacy_lock(self, tmp_path: Path):
+        manifest = tmp_path / "compose.bake.yml"
+
+        assert resolve_lock(tmp_path, manifest) == tmp_path / ".env.lock"
+
+    def test_without_manifest_prefers_existing_lock(self, tmp_path: Path):
+        (tmp_path / ".env.lock").write_text("", encoding="utf-8")
+
+        assert resolve_lock(tmp_path, None) == tmp_path / ".env.lock"
+
+    def test_without_manifest_defaults_to_images_lock(self, tmp_path: Path):
+        assert resolve_lock(tmp_path, None) == tmp_path / "workloads" / "images.lock"
+
+
 class TestEnforceBakeDeclaration:
+    def test_accepts_images_manifest_with_declaration(self, tmp_path: Path):
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text("", encoding="utf-8")
+
+        enforce_bake_declaration(tmp_path, LifecycleConfig())
+
     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):
+    def test_accepts_missing_manifest_without_declaration(self, tmp_path: Path):
         enforce_bake_declaration(tmp_path, None)
 
+    def test_rejects_images_manifest_without_declaration(self, tmp_path: Path):
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text("", encoding="utf-8")
+
+        with pytest.raises(RuntimeError, match="lifecycle"):
+            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")
 

{docker_devkit-0.1.15 → docker_devkit-0.1.17}/tests/test_score_generate.py

@@ -109,8 +109,11 @@ def test_load_score_config_reads_consumer_table(tmp_path: Path) -> None:
     assert config.workloads == ["api.yaml"]
     assert config.project_name == "placeframe"
     assert config.publishes == ["8000:api:8000"]
-    assert config.compose_output == Path("compose.yaml")
-    assert config.k8s_output == Path("deploy") / "manifests.yaml"
+    assert config.score_dir == Path("stack/score")
+    assert config.bake_file == Path("workloads/images.yml")
+    assert config.compose_output == Path("stack/generated/compose/compose.yaml")
+    assert config.k8s_output == Path("stack/generated/k8s/manifests.yaml")
+    assert config.k8s_state == Path("stack/generated/k8s/.score-k8s")
     assert config.score_k8s_version == "0.15.0"
     assert config.score_compose_version == "0.42.0"
 

docker_devkit-0.1.15/src/docker_devkit/lifecycle.py

@@ -1,46 +0,0 @@
-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