docker-devkit 0.1.19__tar.gz → 0.1.21__tar.gz

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/.github/workflows/release.yml

@@ -28,4 +28,4 @@ jobs:
       - uses: astral-sh/setup-uv@v7
 
       - name: Publish
-        run: uvx --from release-devkit==0.1.14 publish-stable --config release-devkit.json
+        run: uvx --from release-devkit==0.1.20 publish-stable --config release-devkit.yaml

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/AGENTS.md

@@ -2,15 +2,15 @@
 
 ## What this is
 
-`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in `[tool.docker-devkit.lifecycle]` so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
+`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in the `lifecycle:` section of `docker-devkit.yaml` so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
 
-The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI (`bashrun>=0.1.0`; git-source pins only in scratch branches testing unreleased changes). The repo and package renamed twice on the way here — `stack-lifecycle` → `stack-toolkit` (2026-09-20, before any publish) and `stack-toolkit` → `docker-devkit` (2026-09-21, member of the `-devkit` family). The PyPI identity is fresh: `docker-devkit` starts its own tag ledger at `0.1.0`; the terminal `stack-toolkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
+The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI — `bashrun` (shell-outs), `packaging` (`requires` specifier parsing), `pathspec`, `pydantic`/`pydantic-settings`, `pyyaml` (score-document parsing), `strictyaml` (config loading), `typer` (CLIs) — git-source pins only in scratch branches testing unreleased changes. The repo and package renamed twice on the way here — `stack-lifecycle` → `stack-toolkit` (2026-09-20, before any publish) and `stack-toolkit` → `docker-devkit` (2026-09-21, member of the `-devkit` family). The PyPI identity is fresh: `docker-devkit` starts its own tag ledger at `0.1.0`; the terminal `stack-toolkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
 
-Config surfaces org-wide follow one law (its home is release-devkit's `AGENTS.md`): config names its owning devkit and lives beside the unit it describes — project-dep devkits configure via `[tool.<devkit>.*]` pyproject tables, uvx-isolated devkits via one root `<devkit>.json` per repo. This repo's `[tool.docker-devkit.lifecycle]` tables in consumers are an instance; this repo itself is published by root `release-devkit.json`.
+Config surfaces org-wide follow one law (its home is release-devkit's `AGENTS.md`): config lives beside the unit whose facts it carries; consumption model and config location are independent axes. Every devkit configures via one root `<devkit>.yaml` per repo — except python-devkit (pyproject `[tool.python-devkit.*]` tables, its subject being the Python workspace) and unity-devkit (JSON, read by C# inside Unity, which ships no YAML parser). A docker-devkit consumer declares a root `docker-devkit.yaml` whose schema (`config.DockerDevkitConfig`, strictyaml-loaded, `extra="forbid"` on every model) carries a required `requires` version stamp plus optional `lifecycle` / `mirror` / `generate-score` sections; `config.load_config` self-checks the installed docker-devkit version against `requires` and refuses loudly outside the range (the `0.0.0.dev0` dev sentinel bypasses the check, not the field). Strictyaml preserves all scalars as strings (no implicit typing) and rejects duplicate keys and flow-style collections, so empty collections are expressed by omitting the key, not by `[]`/`{}`. This repo itself is published by root `release-devkit.yaml`.
 
 ## Release flow
 
-Publishing rides `release.yml`, triggered by a successful CI run on a `main` push: the machinery — release-devkit's `publish-stable` (an inlined, version-pinned `uvx` step in the publish job, keeping OIDC identity local), never a project dependency (docker-devkit sits inside its own dependency graph; a project-level release-devkit edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (publisher bound to `release.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `docker-devkit-v*` tags are the version ledger (declared `major_minor` line in `release-devkit.json`, patch-auto within the line). While pre-1.0, breaking changes ride the normal patch flow without a bump; from 1.0 on, API-breaking changes ship with a manually bumped `major_minor` — patch-auto assumes additive changes.
+Publishing rides `release.yml`, triggered by a successful CI run on a `main` push: the machinery — release-devkit's `publish-stable` (an inlined, version-pinned `uvx` step in the publish job, keeping OIDC identity local), never a project dependency (docker-devkit sits inside its own dependency graph; a project-level release-devkit edge is a resolver cycle) — computes the plan from the tag ledger and path-diff, patches the version ephemerally, and publishes to PyPI under OIDC trusted publishing (publisher bound to `release.yml`, no environment). The committed `pyproject.toml` version is permanently the `0.0.0.dev0` sentinel; the `docker-devkit-v*` tags are the version ledger (declared `major_minor` line in `release-devkit.yaml`, patch-auto within the line). While pre-1.0, breaking changes ride the normal patch flow without a bump; from 1.0 on, API-breaking changes ship with a manually bumped `major_minor` — patch-auto assumes additive changes.
 
 ## Shape
 
@@ -21,14 +21,15 @@ 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`, `--allow-upstream-fallback`. |
 | `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). `--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). |
+| `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). |
 | `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. 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` (`[tool.docker-devkit.mirror]`, key `prefix`), `load_mirror_config()` (walks `tool → docker-devkit → mirror`, `None` when 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". |
+| `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". |
 
 ## Constraints
 
@@ -36,16 +37,16 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 **Context.** A repo that authors its own stack builds its own images and assembles a multi-file compose graph (e.g. `compose.yml` + `compose.postgres.yml` + a GPU layer + `compose.dev.yml`), injecting per-service `${*_SHA}` image tags and 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. 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.
+**Constraint.** `up`/`down` assemble the graph from the `lifecycle:` section of the consumer's root `docker-devkit.yaml` — 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 section → 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 section, 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 lock.
+**Consequences.** placeframe's shape lives in placeframe's `docker-devkit.yaml`, not in this package: a `lifecycle` section with `files` = `compose.yml`, `compose.postgres.yml`, `compose.{gpu}.yml` (in layering order) and `dev_file` = `compose.dev.yml`. A consumer repo with no repo-local runtime graph (a builds-only repo) omits the `lifecycle` section; `up`/`down` on such a repo hits `enforce_bake_declaration` (manifest present, no lifecycle) — the honest signal there is no stack to bring up.
 
 ### 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.
-- 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).
+- the compose layers declared in the `lifecycle:` section of `docker-devkit.yaml` — 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.
 
 `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.
@@ -54,7 +55,7 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 **Context.** 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).
 
-**Constraint.** The mirror is declared, not inferred: `[tool.docker-devkit.mirror]` with `prefix` in the consumer's root pyproject. Absent table → all mirror behavior off; `up`/`build` behave exactly as they did before it existed. Under the table:
+**Constraint.** 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; `up`/`build` behave exactly as they did before it existed. Under the section:
 
 - `build` resolves lock digests for mirror-prefixed declarations against the upstream reference (prefix stripped, tag/digest tail preserved) and records them 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.

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/PKG-INFO

@@ -1,13 +1,15 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.19
+Version: 0.1.21
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.13
 Requires-Dist: bashrun>=0.1.0
+Requires-Dist: packaging>=24.1
 Requires-Dist: pathspec>=1.0.4
 Requires-Dist: pydantic-settings>=2.9.1
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: strictyaml>=1.7.3
 Requires-Dist: typer>=0.17.4

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/README.md

@@ -1,6 +1,6 @@
 # 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 + `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.
+Docker-stack lifecycle commands — `up`, `down`, `build` — with the compose assembly declared per repo in the `lifecycle:` section of `docker-devkit.yaml`. 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 omits the `lifecycle` section (single-file default) 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 (`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.
 
@@ -27,11 +27,11 @@ uv run down -v                 # also remove named volumes
 uv run build                   # cross-build all images per workloads/images.yml
 uv run build --lock-only       # refresh the image lock without building
 uv run mirror                  # populate the org mirror namespace from mirror-prefixed declarations (CI)
-uv run generate-score          # regenerate Score compose/k8s manifests per [tool.docker-devkit.generate-score]
+uv run generate-score          # regenerate Score compose/k8s manifests per the generate-score: section of docker-devkit.yaml
 uv run generate-score --local  # local-cluster variant (local storage class, gitignored output)
 ```
 
-Repos that consume third-party images through the org mirror namespace declare `[tool.docker-devkit.mirror]` (`prefix = "ghcr.io/outernet-foundation/mirror"`); `up` then fails closed on any lock entry not mirrored yet, and `build` resolves lock digests against upstream. See the "Mirror namespace and upstream fallback" section in [`AGENTS.md`](./AGENTS.md).
+Repos that consume third-party images through the org mirror namespace declare a `mirror:` section in `docker-devkit.yaml` (`prefix: ghcr.io/outernet-foundation/mirror`); `up` then fails closed on any lock entry not mirrored yet, and `build` resolves lock digests against upstream. See the "Mirror namespace and upstream fallback" section in [`AGENTS.md`](./AGENTS.md).
 
 ## Consuming from another repo
 

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/pyproject.toml

@@ -1,15 +1,17 @@
 [project]
 name = "docker-devkit"
-version = "0.1.19"
+version = "0.1.21"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",
+    "packaging>=24.1",
+    "pathspec>=1.0.4",
     "pydantic>=2.11.7",
     "pydantic-settings>=2.9.1",
-    "typer>=0.17.4",
     "pyyaml>=6.0",
-    "pathspec>=1.0.4",
+    "strictyaml>=1.7.3",
+    "typer>=0.17.4",
 ]
 
 [dependency-groups]
@@ -18,6 +20,7 @@ dev = [
     "ruff>=0.14.11",
     "pytest>=8.0.0",
     "types-pyyaml>=6.0.12.20260906",
+    "types-strictyaml>=1.7.3.3",
 ]
 
 [build-system]

docker_devkit-0.1.21/release-devkit.yaml

@@ -0,0 +1,8 @@
+requires: ">=0.1"
+ci_workflow: ci.yml
+packages:
+  docker-devkit:
+    path: .
+    major_minor: "0.1"
+    registries:
+      pypi: docker-devkit

docker_devkit-0.1.21/src/docker_devkit/config.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from packaging.specifiers import SpecifierSet
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from strictyaml import load as load_strict_yaml
+
+DEFAULT_CONFIG_PATH = Path("docker-devkit.yaml")
+DEV_SENTINEL = "0.0.0.dev0"
+
+
+class LifecycleConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    files: list[str] = Field(default_factory=list)
+    dev_file: str | None = None
+
+
+class MirrorConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prefix: str
+
+    @field_validator("prefix")
+    @classmethod
+    def _require_bare_prefix(cls, prefix: str) -> str:
+        if not prefix or prefix.endswith("/"):
+            raise ValueError("mirror prefix must be non-empty and carry no trailing slash")
+        return prefix
+
+
+class ScoreConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    workloads: list[str]
+    project_name: str
+    cloud_storage_class: str
+    local_storage_class: str
+    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("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)
+    k8s_provisioners: list[str] = Field(default_factory=list)
+    publishes: list[str] = Field(default_factory=list)
+    score_k8s_version: str = "0.15.0"
+    score_compose_version: str = "0.42.0"
+
+
+class DockerDevkitConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    requires: str
+    lifecycle: LifecycleConfig | None = None
+    mirror: MirrorConfig | None = None
+    generate_score: ScoreConfig | None = Field(default=None, alias="generate-score")
+
+    @field_validator("requires")
+    @classmethod
+    def _validate_requires(cls, value: str) -> str:
+        if not value:
+            raise ValueError("requires must be a non-empty PEP 440 specifier; use '>=0.0' for no constraint")
+        SpecifierSet(value)
+        return value
+
+
+def load_config(root: Path) -> DockerDevkitConfig | None:
+    path = root / DEFAULT_CONFIG_PATH
+    if not path.exists():
+        return None
+    config = DockerDevkitConfig.model_validate(load_strict_yaml(path.read_text(encoding="utf-8")).data)
+    installed = importlib.metadata.version("docker-devkit")
+    if installed == DEV_SENTINEL:
+        return config
+    if not SpecifierSet(config.requires).contains(installed, prereleases=True):
+        raise SystemExit(f"docker-devkit {installed} does not satisfy requires={config.requires!r}")
+    return config

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/src/docker_devkit/lifecycle.py

@@ -1,10 +1,8 @@
 from __future__ import annotations
 
-import tomllib
 from pathlib import Path
 
-from pydantic import BaseModel, ConfigDict, Field
-
+from .config import LifecycleConfig, load_config
 from .detect_gpu import Gpu
 
 DEFAULT_COMPOSE_FILE = Path("compose.yml")
@@ -17,22 +15,9 @@ MANIFEST_LOCK_PAIR = {"images.yml": "images.lock", "compose.bake.yml": ".env.loc
 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)
+    config = load_config(root)
+    return config.lifecycle if config is not None else None
 
 
 def resolve_manifest(root: Path) -> Path | None:
@@ -56,7 +41,7 @@ def resolve_lock(root: Path, manifest: Path | None) -> 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):
         raise RuntimeError(
-            "image manifest present without [tool.docker-devkit.lifecycle]; declare the table or rename the file"
+            "image manifest present without a lifecycle section in docker-devkit.yaml; declare the section or rename the file"
         )
 
 

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/src/docker_devkit/mirror.py

@@ -3,13 +3,12 @@ from __future__ import annotations
 import os
 import shlex
 import tempfile
-import tomllib
 from pathlib import Path
 
 import typer
 from bashrun.bash import bash, bash_check
-from pydantic import BaseModel, ConfigDict, field_validator
 
+from .config import MirrorConfig, load_config
 from .image_refs import ImageReference, declared_references
 
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
@@ -17,25 +16,12 @@ app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 CRANE_VERSION = "v0.22.1"
 
 
-class MirrorConfig(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    prefix: str
-
-    @field_validator("prefix")
-    @classmethod
-    def _require_bare_prefix(cls, prefix: str) -> str:
-        if not prefix or prefix.endswith("/"):
-            raise ValueError("mirror prefix must be non-empty and carry no trailing slash")
-        return prefix
-
-
 @app.command()
 def mirror() -> None:
     root = Path.cwd()
     config = load_mirror_config(root)
     if config is None:
-        raise RuntimeError("[tool.docker-devkit.mirror] with 'prefix' is required to mirror")
+        raise RuntimeError("a mirror section with 'prefix' is required in docker-devkit.yaml to mirror")
 
     targets = mirror_targets(root, config.prefix)
     print(f"Install crane {CRANE_VERSION}")
@@ -52,14 +38,8 @@ def mirror() -> None:
 
 
 def load_mirror_config(root: Path) -> MirrorConfig | 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("mirror")
-    if section is None:
-        return None
-    return MirrorConfig.model_validate(section)
+    config = load_config(root)
+    return config.mirror if config is not None else None
 
 
 def is_mirrored(reference: str, prefix: str) -> bool:

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/src/docker_devkit/score_generate.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import os
 import re
 import shlex
-import tomllib
 from collections.abc import Generator
 from contextlib import contextmanager
 from pathlib import Path
@@ -13,11 +12,11 @@ from typing import Annotated, Literal
 import typer
 import yaml
 from bashrun.bash import bash
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict
 
+from .config import ScoreConfig, load_config
 from .context_sha import compute_service_shas
 from .documents import parse_bake
-from .image_refs import TomlDocument, TomlValue
 
 # Placeholders in the workload files are ALL-CAPS, so this cannot collide with Score's own
 # lowercase dotted ${resources.db.host} references.
@@ -40,30 +39,6 @@ class ManifestDocument(BaseModel):
     metadata: ManifestMetadata | None = None
 
 
-class ScoreConfig(BaseModel):
-    model_config = ConfigDict(extra="forbid")
-
-    workloads: list[str]
-    project_name: str
-    cloud_storage_class: str
-    local_storage_class: str
-    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("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)
-    k8s_provisioners: list[str] = Field(default_factory=list)
-    publishes: list[str] = Field(default_factory=list)
-    score_k8s_version: str = "0.15.0"
-    score_compose_version: str = "0.42.0"
-
-
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 
@@ -82,16 +57,10 @@ def cli(
 
 
 def load_score_config(root: Path) -> ScoreConfig:
-    value: TomlValue = TomlDocument.model_validate(
-        tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
-    ).root
-    for component in ("tool", "docker-devkit", "generate-score"):
-        if not isinstance(value, dict) or component not in value:
-            raise RuntimeError(
-                f"[tool.docker-devkit.generate-score] is missing at {component} in {root / 'pyproject.toml'}"
-            )
-        value = value[component]
-    return ScoreConfig.model_validate(value)
+    config = load_config(root)
+    if config is None or config.generate_score is None:
+        raise RuntimeError("a generate-score section is required in docker-devkit.yaml")
+    return config.generate_score
 
 
 def generate(config: ScoreConfig, target: Target = "both", local: bool = False) -> None:

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/src/docker_devkit/up.py

@@ -57,7 +57,7 @@ def up(
     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]")
+        raise RuntimeError("--dev requires a dev_file in the lifecycle section of docker-devkit.yaml")
 
     if not ENV_FILE.exists():
         raise RuntimeError("No .env file found; create one first (e.g., copy .env.example)")

docker_devkit-0.1.21/tests/test_config.py

@@ -0,0 +1,151 @@
+import importlib.metadata
+from pathlib import Path
+
+import pytest
+import yaml
+from pydantic import ValidationError
+
+from docker_devkit.config import DEV_SENTINEL, load_config
+
+
+def write_config(tmp_path: Path, payload: dict[str, object]) -> None:
+    (tmp_path / "docker-devkit.yaml").write_text(
+        yaml.safe_dump(payload, default_flow_style=False, sort_keys=False), encoding="utf-8"
+    )
+
+
+def test_load_config_returns_none_when_file_absent(tmp_path: Path) -> None:
+    assert load_config(tmp_path) is None
+
+
+def test_requires_omitted_is_required(tmp_path: Path) -> None:
+    write_config(tmp_path, {"lifecycle": {"files": ["compose.yml"]}})
+
+    with pytest.raises(ValidationError, match="requires"):
+        load_config(tmp_path)
+
+
+def test_requires_empty_string_rejected(tmp_path: Path) -> None:
+    write_config(tmp_path, {"requires": ""})
+
+    with pytest.raises(ValidationError, match="requires"):
+        load_config(tmp_path)
+
+
+def test_requires_invalid_specifier_rejected(tmp_path: Path) -> None:
+    write_config(tmp_path, {"requires": "not-a-specifier"})
+
+    with pytest.raises(ValidationError, match="requires"):
+        load_config(tmp_path)
+
+
+def _version_dev_sentinel(_name: str) -> str:
+    return DEV_SENTINEL
+
+
+def _version_0_1_18(_name: str) -> str:
+    return "0.1.18"
+
+
+def _version_0_1_19_dev5(_name: str) -> str:
+    return "0.1.19.dev5"
+
+
+def _version_0_1_17(_name: str) -> str:
+    return "0.1.17"
+
+
+def test_requires_dev_sentinel_skips_check(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(importlib.metadata, "version", _version_dev_sentinel)
+    write_config(tmp_path, {"requires": ">=0.1.18"})
+
+    config = load_config(tmp_path)
+    assert config is not None
+
+    assert config.requires == ">=0.1.18"
+
+
+def test_requires_in_range_loads(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(importlib.metadata, "version", _version_0_1_18)
+    write_config(tmp_path, {"requires": ">=0.1.18"})
+
+    config = load_config(tmp_path)
+    assert config is not None
+
+    assert config.requires == ">=0.1.18"
+
+
+def test_requires_dev_channel_prerelease_satisfies(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(importlib.metadata, "version", _version_0_1_19_dev5)
+    write_config(tmp_path, {"requires": ">=0.1.18"})
+
+    config = load_config(tmp_path)
+    assert config is not None
+
+    assert config.requires == ">=0.1.18"
+
+
+def test_requires_out_of_range_refuses(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(importlib.metadata, "version", _version_0_1_17)
+    write_config(tmp_path, {"requires": ">=0.1.18"})
+
+    with pytest.raises(SystemExit, match="does not satisfy requires"):
+        load_config(tmp_path)
+
+
+def test_load_config_rejects_duplicate_keys(tmp_path: Path) -> None:
+    (tmp_path / "docker-devkit.yaml").write_text('requires: ">=0.1"\nrequires: ">=0.2"\n', encoding="utf-8")
+
+    with pytest.raises(Exception, match=r"Duplicate key"):
+        load_config(tmp_path)
+
+
+def test_load_config_rejects_unknown_top_level_keys(tmp_path: Path) -> None:
+    write_config(tmp_path, {"requires": ">=0.1", "lifecycle_prefix": "ghcr.io/x/mirror"})
+
+    with pytest.raises(ValidationError, match="Extra inputs are not permitted"):
+        load_config(tmp_path)
+
+
+def test_load_config_loads_lifecycle_and_mirror(tmp_path: Path) -> None:
+    write_config(
+        tmp_path,
+        {
+            "requires": ">=0.1",
+            "lifecycle": {"files": ["compose.yml", "compose.{gpu}.yml"], "dev_file": "compose.dev.yml"},
+            "mirror": {"prefix": "ghcr.io/outernet-foundation/mirror"},
+        },
+    )
+
+    config = load_config(tmp_path)
+    assert config is not None
+
+    assert config.lifecycle is not None
+    assert config.lifecycle.files == ["compose.yml", "compose.{gpu}.yml"]
+    assert config.lifecycle.dev_file == "compose.dev.yml"
+    assert config.mirror is not None
+    assert config.mirror.prefix == "ghcr.io/outernet-foundation/mirror"
+    assert config.generate_score is None
+
+
+def test_load_config_loads_generate_score_section(tmp_path: Path) -> None:
+    write_config(
+        tmp_path,
+        {
+            "requires": ">=0.1",
+            "generate-score": {
+                "workloads": ["api.yaml"],
+                "project_name": "placeframe",
+                "cloud_storage_class": "hcloud-volumes",
+                "local_storage_class": "local-path",
+            },
+        },
+    )
+
+    config = load_config(tmp_path)
+    assert config is not None
+
+    assert config.generate_score is not None
+    assert config.generate_score.workloads == ["api.yaml"]
+    assert config.generate_score.project_name == "placeframe"
+    assert config.lifecycle is None

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/tests/test_lifecycle.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import pytest
+import yaml
 from pydantic import ValidationError
 from docker_devkit.lifecycle import (
     LifecycleConfig,
@@ -12,18 +13,25 @@ from docker_devkit.lifecycle import (
 )
 
 
-def _write_pyproject(root: Path, lifecycle_toml: str) -> None:
-    content = f"[project]\nname = 'stack'\n\n{lifecycle_toml}"
-    (root / "pyproject.toml").write_text(content, encoding="utf-8")
+def _write_config(root: Path, sections: dict[str, object] | None = None) -> None:
+    payload: dict[str, object] = {"requires": ">=0.0"}
+    if sections is not None:
+        payload.update(sections)
+    (root / "docker-devkit.yaml").write_text(
+        yaml.safe_dump(payload, default_flow_style=False, sort_keys=False), encoding="utf-8"
+    )
 
 
 class TestLoadLifecycleConfig:
-    def test_loads_declared_table(self, tmp_path: Path):
-        _write_pyproject(
+    def test_loads_declared_files_and_dev_file(self, tmp_path: Path):
+        _write_config(
             tmp_path,
-            "[tool.docker-devkit.lifecycle]\n"
-            'files = ["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"]\n'
-            'dev_file = "compose.dev.yml"\n',
+            {
+                "lifecycle": {
+                    "files": ["compose.yml", "compose.postgres.yml", "compose.{gpu}.yml"],
+                    "dev_file": "compose.dev.yml",
+                }
+            },
         )
 
         config = load_lifecycle_config(tmp_path)
@@ -33,34 +41,36 @@ class TestLoadLifecycleConfig:
             dev_file="compose.dev.yml",
         )
 
-    def test_bare_table_defaults_to_empty(self, tmp_path: Path):
-        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\n")
+    def test_dev_file_defaults_to_none_when_only_files_declared(self, tmp_path: Path):
+        _write_config(tmp_path, {"lifecycle": {"files": ["compose.yml"]}})
 
         config = load_lifecycle_config(tmp_path)
 
-        assert config == LifecycleConfig()
+        assert config == LifecycleConfig(files=["compose.yml"])
 
-    def test_absent_table_returns_none(self, tmp_path: Path):
-        _write_pyproject(tmp_path, "[tool.docker-devkit.generate-score]\nworkloads = []\n")
+    def test_files_defaults_to_empty_when_only_dev_file_declared(self, tmp_path: Path):
+        _write_config(tmp_path, {"lifecycle": {"dev_file": "compose.dev.yml"}})
 
-        assert load_lifecycle_config(tmp_path) is None
+        config = load_lifecycle_config(tmp_path)
+
+        assert config == LifecycleConfig(dev_file="compose.dev.yml")
 
-    def test_absent_tool_section_returns_none(self, tmp_path: Path):
-        _write_pyproject(tmp_path, "")
+    def test_absent_section_returns_none(self, tmp_path: Path):
+        _write_config(tmp_path, {"mirror": {"prefix": "ghcr.io/x/mirror"}})
 
         assert load_lifecycle_config(tmp_path) is None
 
-    def test_missing_pyproject_returns_none(self, tmp_path: Path):
+    def test_missing_config_returns_none(self, tmp_path: Path):
         assert load_lifecycle_config(tmp_path) is None
 
     def test_rejects_unknown_keys(self, tmp_path: Path):
-        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\nfiles = []\nbogus = true\n")
+        _write_config(tmp_path, {"lifecycle": {"files": ["compose.yml"], "bogus": "true"}})
 
         with pytest.raises(ValidationError):
             load_lifecycle_config(tmp_path)
 
-    def test_rejects_non_string_entries(self, tmp_path: Path):
-        _write_pyproject(tmp_path, "[tool.docker-devkit.lifecycle]\nfiles = [1]\n")
+    def test_rejects_scalar_files(self, tmp_path: Path):
+        _write_config(tmp_path, {"lifecycle": {"files": "compose.yml"}})
 
         with pytest.raises(ValidationError):
             load_lifecycle_config(tmp_path)

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/tests/test_mirror.py

@@ -3,6 +3,7 @@ import tempfile
 from pathlib import Path
 
 import pytest
+import yaml
 from pydantic import ValidationError
 from typer.testing import CliRunner
 
@@ -42,6 +43,15 @@ LOCKED_ERROR = (
 runner = CliRunner()
 
 
+def _write_config(root: Path, sections: dict[str, object] | None = None) -> None:
+    payload: dict[str, object] = {"requires": ">=0.0"}
+    if sections is not None:
+        payload.update(sections)
+    (root / "docker-devkit.yaml").write_text(
+        yaml.safe_dump(payload, default_flow_style=False, sort_keys=False), encoding="utf-8"
+    )
+
+
 class SelectiveExistence:
     def __init__(self, present: str) -> None:
         self.present = present
@@ -139,32 +149,26 @@ class TestInversion:
 
 class TestLoadMirrorConfig:
     def test_loads_declared_prefix(self, tmp_path: Path):
-        (tmp_path / "pyproject.toml").write_text(
-            f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n", encoding="utf-8"
-        )
+        _write_config(tmp_path, {"mirror": {"prefix": MIRROR_PREFIX}})
 
         assert mirror.load_mirror_config(tmp_path) == MirrorConfig(prefix=MIRROR_PREFIX)
 
-    def test_absent_table_returns_none(self, tmp_path: Path):
-        (tmp_path / "pyproject.toml").write_text("[tool.docker-devkit.lifecycle]\nfiles = []\n", encoding="utf-8")
+    def test_absent_section_returns_none(self, tmp_path: Path):
+        _write_config(tmp_path, {"lifecycle": {"files": ["compose.yml"]}})
 
         assert mirror.load_mirror_config(tmp_path) is None
 
-    def test_missing_pyproject_returns_none(self, tmp_path: Path):
+    def test_missing_config_returns_none(self, tmp_path: Path):
         assert mirror.load_mirror_config(tmp_path) is None
 
     def test_rejects_unknown_keys(self, tmp_path: Path):
-        (tmp_path / "pyproject.toml").write_text(
-            "[tool.docker-devkit.mirror]\nprefix = 'ghcr.io/x/mirror'\nbogus = true\n", encoding="utf-8"
-        )
+        _write_config(tmp_path, {"mirror": {"prefix": "ghcr.io/x/mirror", "bogus": "true"}})
 
         with pytest.raises(ValidationError):
             mirror.load_mirror_config(tmp_path)
 
     def test_rejects_trailing_slash_prefix(self, tmp_path: Path):
-        (tmp_path / "pyproject.toml").write_text(
-            "[tool.docker-devkit.mirror]\nprefix = 'ghcr.io/x/mirror/'\n", encoding="utf-8"
-        )
+        _write_config(tmp_path, {"mirror": {"prefix": "ghcr.io/x/mirror/"}})
 
         with pytest.raises(ValidationError):
             mirror.load_mirror_config(tmp_path)
@@ -251,9 +255,7 @@ class TestWriteFallbackOverlay:
 
 class TestMirrorVerb:
     def _write_tree(self, tmp_path: Path) -> None:
-        (tmp_path / "pyproject.toml").write_text(
-            f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n", encoding="utf-8"
-        )
+        _write_config(tmp_path, {"mirror": {"prefix": MIRROR_PREFIX}})
         (tmp_path / "workloads").mkdir()
         (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
 
@@ -281,14 +283,14 @@ class TestMirrorVerb:
 
 
 class TestUpstreamAwareLockResolution:
-    def _write_tree(self, tmp_path: Path, *, mirror_table: bool) -> None:
-        table = f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n" if mirror_table else ""
-        (tmp_path / "pyproject.toml").write_text(f"[project]\nname = 'stack'\n\n{table}", encoding="utf-8")
+    def _write_tree(self, tmp_path: Path, *, mirror: bool) -> None:
+        if mirror:
+            _write_config(tmp_path, {"mirror": {"prefix": MIRROR_PREFIX}})
         (tmp_path / "workloads").mkdir()
         (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
 
     def test_resolves_mirror_declarations_against_upstream(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
-        self._write_tree(tmp_path, mirror_table=True)
+        self._write_tree(tmp_path, mirror=True)
         monkeypatch.chdir(tmp_path)
         recorder = DigestRecorder()
         monkeypatch.setattr(build_docker, "resolve_remote_digest", recorder.resolve)
@@ -305,7 +307,7 @@ class TestUpstreamAwareLockResolution:
         assert f"UV_IMAGE={MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15@{FAKE_DIGEST}" in lock
 
     def test_without_table_inspects_the_declared_reference(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
-        self._write_tree(tmp_path, mirror_table=False)
+        self._write_tree(tmp_path, mirror=False)
         monkeypatch.chdir(tmp_path)
         recorder = DigestRecorder()
         monkeypatch.setattr(build_docker, "resolve_remote_digest", recorder.resolve)
@@ -321,10 +323,7 @@ class TestUpstreamAwareLockResolution:
 
 class TestBakeConsumesEnvOverlay:
     def _write_tree(self, tmp_path: Path) -> None:
-        (tmp_path / "pyproject.toml").write_text(
-            f"[project]\nname = 'stack'\n\n[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n",
-            encoding="utf-8",
-        )
+        _write_config(tmp_path, {"mirror": {"prefix": MIRROR_PREFIX}})
         (tmp_path / "workloads").mkdir()
         (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
 

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/tests/test_score_generate.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import pytest
+import yaml
 from pydantic import ValidationError
 
 from docker_devkit.score_generate import (
@@ -13,6 +14,14 @@ from docker_devkit.score_generate import (
 )
 
 
+def _write_config(root: Path, sections: dict[str, object]) -> None:
+    payload: dict[str, object] = {"requires": ">=0.0"}
+    payload.update(sections)
+    (root / "docker-devkit.yaml").write_text(
+        yaml.safe_dump(payload, default_flow_style=False, sort_keys=False), encoding="utf-8"
+    )
+
+
 def make_config(**overrides: str | list[str]) -> ScoreConfig:
     values: dict[str, str | list[str]] = {
         "workloads": ["api.yaml", "gateway.yaml"],
@@ -93,15 +102,18 @@ def test_write_normalises_file_mode(tmp_path: Path) -> None:
     assert path.read_text(encoding="utf-8") == "content\n"
 
 
-def test_load_score_config_reads_consumer_table(tmp_path: Path) -> None:
-    (tmp_path / "pyproject.toml").write_text(
-        "[tool.docker-devkit.generate-score]\n"
-        'workloads = ["api.yaml"]\n'
-        'project_name = "placeframe"\n'
-        'cloud_storage_class = "hcloud-volumes"\n'
-        'local_storage_class = "local-path"\n'
-        'publishes = ["8000:api:8000"]\n',
-        encoding="utf-8",
+def test_load_score_config_reads_consumer_section(tmp_path: Path) -> None:
+    _write_config(
+        tmp_path,
+        {
+            "generate-score": {
+                "workloads": ["api.yaml"],
+                "project_name": "placeframe",
+                "cloud_storage_class": "hcloud-volumes",
+                "local_storage_class": "local-path",
+                "publishes": ["8000:api:8000"],
+            }
+        },
     )
 
     config = load_score_config(tmp_path)
@@ -118,9 +130,7 @@ def test_load_score_config_reads_consumer_table(tmp_path: Path) -> None:
     assert config.score_compose_version == "0.42.0"
 
 
-def test_load_score_config_missing_table_raises(tmp_path: Path) -> None:
-    (tmp_path / "pyproject.toml").write_text('[project]\nname = "consumer"\n', encoding="utf-8")
-
+def test_load_score_config_missing_section_raises(tmp_path: Path) -> None:
     with pytest.raises(RuntimeError, match="generate-score"):
         load_score_config(tmp_path)
 

{docker_devkit-0.1.19 → docker_devkit-0.1.21}/uv.lock

@@ -56,10 +56,12 @@ version = "0.0.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "bashrun" },
+    { name = "packaging" },
     { name = "pathspec" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
     { name = "pyyaml" },
+    { name = "strictyaml" },
     { name = "typer" },
 ]
 
@@ -69,15 +71,18 @@ dev = [
     { name = "pytest" },
     { name = "ruff" },
     { name = "types-pyyaml" },
+    { name = "types-strictyaml" },
 ]
 
 [package.metadata]
 requires-dist = [
     { name = "bashrun", specifier = ">=0.1.0" },
+    { name = "packaging", specifier = ">=24.1" },
     { name = "pathspec", specifier = ">=1.0.4" },
     { name = "pydantic", specifier = ">=2.11.7" },
     { name = "pydantic-settings", specifier = ">=2.9.1" },
     { name = "pyyaml", specifier = ">=6.0" },
+    { name = "strictyaml", specifier = ">=1.7.3" },
     { name = "typer", specifier = ">=0.17.4" },
 ]
 
@@ -87,6 +92,7 @@ dev = [
     { name = "pytest", specifier = ">=8.0.0" },
     { name = "ruff", specifier = ">=0.14.11" },
     { name = "types-pyyaml", specifier = ">=6.0.12.20260906" },
+    { name = "types-strictyaml", specifier = ">=1.7.3.3" },
 ]
 
 [[package]]
@@ -272,6 +278,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
 ]
 
+[[package]]
+name = "python-dateutil"
+version = "2.9.0.post0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/c0/0c8b6ad9f17a802ee498c46e004a0eb49bc148f2fd230864601a86dcf6db/python-dateutil-2.9.0.post0.tar.gz", hash = "sha256:37dd54208da7e1cd875388217d5e00ebd4179249f90fb72437e91a35459a0ad3", size = 342432, upload-time = "2024-03-01T18:36:20.211Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
+]
+
 [[package]]
 name = "python-dotenv"
 version = "1.2.2"
@@ -364,6 +382,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
 ]
 
+[[package]]
+name = "six"
+version = "1.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
+[[package]]
+name = "strictyaml"
+version = "1.7.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "python-dateutil" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/08/efd28d49162ce89c2ad61a88bd80e11fb77bc9f6c145402589112d38f8af/strictyaml-1.7.3.tar.gz", hash = "sha256:22f854a5fcab42b5ddba8030a0e4be51ca89af0267961c8d6cfa86395586c407", size = 115206, upload-time = "2023-03-10T12:50:27.062Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/96/7c/a81ef5ef10978dd073a854e0fa93b5d8021d0594b639cc8f6453c3c78a1d/strictyaml-1.7.3-py3-none-any.whl", hash = "sha256:fb5c8a4edb43bebb765959e420f9b3978d7f1af88c80606c03fb420888f5d1c7", size = 123917, upload-time = "2023-03-10T12:50:17.242Z" },
+]
+
 [[package]]
 name = "typer"
 version = "0.26.8"
@@ -388,6 +427,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/15/c0/fc0644b7ddcfb969e95845837143cb5173ddd6e06ee4ba5fc493cd9329b7/types_pyyaml-6.0.12.20260906-py3-none-any.whl", hash = "sha256:bca893ff0d51df5c9053137d5d0e6ccd36e939a196356f1d5c16372422f5137b", size = 21282, upload-time = "2026-09-06T06:35:34.372Z" },
 ]
 
+[[package]]
+name = "types-strictyaml"
+version = "1.7.3.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "strictyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2b/81/50a74541bb5526033909fda5f343b3fc57c88b7a07fd7ff1eaa9eda98c65/types_strictyaml-1.7.3.3.tar.gz", hash = "sha256:61aeb8a13f44fd15cc348e34fac002f5a9b6189f258d2c7acfe79abccc22d57d", size = 46683, upload-time = "2026-09-12T14:57:49.605Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/ef/c3b4a95c43b615f8f61a1f6c3b4ca23a1cade47e15c209b2e9a3c9a863db/types_strictyaml-1.7.3.3-py3-none-any.whl", hash = "sha256:21f5eefb69dd274a72bc1946c51ceeb2f73031dcc2495072dc88f645a0d9888b", size = 67467, upload-time = "2026-09-12T14:57:48.123Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.16.0"

docker_devkit-0.1.19/release-devkit.json

@@ -1,13 +0,0 @@
-{
-  "packages": [
-    {
-      "name": "docker-devkit",
-      "path": ".",
-      "major_minor": "0.1",
-      "registries": {
-        "pypi": "docker-devkit"
-      }
-    }
-  ],
-  "ci_workflow": "ci.yml"
-}