docker-devkit 0.1.23.dev36667933546__tar.gz → 0.1.24__tar.gz

docker_devkit-0.1.24/.github/actions/setup-release-devkit/action.yml

@@ -0,0 +1,11 @@
+name: setup-release-devkit
+description: Install release-devkit at the pinned commit into RUNNER_TEMP
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      env:
+        RELEASE_DEVKIT_COMMIT: edb355edaf2a2f793ea59eca2d9a5ae80b39f2c2
+      run: |
+        git clone https://github.com/outernet-foundation/release-devkit.git "$RUNNER_TEMP/release-devkit"
+        git -C "$RUNNER_TEMP/release-devkit" checkout "$RELEASE_DEVKIT_COMMIT"

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

@@ -0,0 +1,56 @@
+name: Integrate
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [dev]
+
+concurrency:
+  group: integrate-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint-workflows:
+    runs-on: ubuntu-latest
+    steps:
+      - &checkout
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+      - &uv-restore
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          save-cache: "false"
+      - &setup-release-devkit
+        uses: ./.github/actions/setup-release-devkit
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev lint-workflows
+
+  preflight:
+    needs: [lint-workflows]
+    runs-on: ubuntu-latest
+    steps:
+      - *checkout
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          save-cache: "true"
+      - run: uv run preflight-python
+
+  validate-release-plan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          # Perform a full clone, required for tags
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+      - *uv-restore
+      - *setup-release-devkit
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev validate-release-plan

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

@@ -0,0 +1,41 @@
+name: Merge gate
+
+on:
+  pull_request:
+    branches: [dev]
+    types: [labeled]
+  workflow_run:
+    workflows: [Integrate]
+    types: [completed]
+
+concurrency:
+  group: merge-gate-${{ github.event.pull_request.number || github.event.workflow_run.head_branch }}
+
+permissions:
+  contents: read
+
+jobs:
+  merge-gate:
+    if: github.event.label.name == 'ready-to-merge' || (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}
+          # Perform a full clone, required so merge-gate can validate that this PR is a fast forward from dev
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          save-cache: "false"
+      - uses: ./.github/actions/setup-release-devkit
+      - uses: actions/create-github-app-token@v3
+        id: mint
+        with:
+          app-id: ${{ vars.MERGE_BOT_APP_ID }}
+          private-key: ${{ secrets.MERGE_BOT_APP_PRIVATE_KEY }}
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev merge-gate
+        env:
+          GITHUB_TOKEN: ${{ steps.mint.outputs.token }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.workflow_run.head_sha }}

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

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    branches: [main, dev]
+
+concurrency:
+  group: release-${{ github.ref }}
+
+permissions:
+  contents: read
+
+jobs:
+  publish-prerelease:
+    if: github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # Perform a full clone, required for tags
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+      - &uv-restore
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          save-cache: "false"
+      - &setup-release-devkit
+        uses: ./.github/actions/setup-release-devkit
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev publish-prerelease
+
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # Perform a full clone, required for tags
+          fetch-depth: 0
+          fetch-tags: true
+          # Persist credentials so that the release command can push release tags
+          persist-credentials: true
+      - *uv-restore
+      - *setup-release-devkit
+      - run: uv run --project "$RUNNER_TEMP/release-devkit" --locked --no-dev release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/AGENTS.md

@@ -2,19 +2,19 @@
 
 ## 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 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.
+`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror`, `generate-score`, `docker-build-matrix` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). 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`. The PyPI identity starts its own version tags 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.
+The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI — `bashrun` (shell-outs), `ci-devkit` (builds-shelf push for CI lock artifacts), `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.
 
-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`.
+Config follows the org law (home: release-devkit's `AGENTS.md`): this is a root-`docker-devkit.yaml` devkit. The 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).
 
 ## Release flow
 
-Publishing rides `ci-cd.yml` via inlined `uvx --from release-devkit==${{ env.RELEASE_DEVKIT_VERSION }}` steps, version-pinned in the workflow `env:` (see release-devkit's `AGENTS.md`), never a project dependency (docker-devkit sits inside its own dependency graph; a project-level release-devkit edge is a resolver cycle), under OIDC trusted publishing (publisher bound to `ci-cd.yml`, `release` 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.
+release-devkit's `AGENTS.md` owns the three-workflow contract; this repo follows it unchanged. Repo-specific facts: release-devkit is never a project dependency (docker-devkit sits inside its own dependency graph; a project-level edge is a resolver cycle), and from 1.0 on API-breaking changes ship with a manually bumped `major_minor` (pre-1.0, breaking changes ride the patch flow; patch-auto assumes additive changes).
 
 ## Mirror consumption
 
-Consumers with docker images (placeframe, capture-tool) run `mirror` via the docker-devkit PyPI dependency — inline in their `mirror` job (checkout + `setup-uv` + ghcr login + `uv run mirror`), version-sourced by the consumer's `uv.lock`. The job carries `permissions: { contents: read, packages: write }` + `env: GITHUB_TOKEN` (ghcr login for `crane copy`). Pure-Python devkits have no `mirror` job.
+Consumers with docker images (placeframe, capture-tool) run `mirror` via the docker-devkit PyPI dependency — inline in their `mirror-images` job (checkout + `setup-uv` + ghcr login + `uv run mirror`), version-sourced by the consumer's `uv.lock`. The job carries `permissions: { contents: read, packages: write }` + `env: GITHUB_TOKEN` (ghcr login for `crane copy`). Pure-Python devkits have no `mirror-images` job.
 
 ## Shape
 
@@ -36,47 +36,39 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 | `image_refs.py` | Image-reference collection, split by source. `declared_references(root)` enumerates bake `x-base-images` declarations from `workloads/images.yml` and the legacy `compose*.bake.yml` names (parsed and validated via `BakeDocument`) — the single source consumer mirroring consumes. `stray_references(root, …globs)` scans Dockerfile `FROM`, Dockerfile `COPY --from=` (slash-bearing captures only, so build-stage names are skipped), and yaml `image:` lines — hand-written literal refs that bypass the declaration system — across the `workloads/` and `docker/` Dockerfile trees and the `stack/score/` + `score/` source trees; `unpinned_references(root)` polices exactly those strays (every slash-bearing reference must carry a tag, a digest, or a trailing `${build-arg}` suffix — consumer CIs fail on its result). `bake_base_image_refs(bake: BakeDocument)` adapts declarations to `ImageReference` pairs; `version_coupling_violations(root, couplings)` (each `VersionCoupling` names a pyproject-declared version and the `VersionSite` regexes that must restate it — bake `x-base-images` values or raw file text — so non-derivable couplings like uv `required-version` ↔ uv-base-image tag can't drift silently; the mechanism lives here, the registry in consumer repos' preflight) is unchanged. Remote digest resolution goes through `imagetools inspect`. Compose files are parsed by nothing in this package. |
 | `mirror.py` | The mirror namespace's config, inversion, and verbs. `MirrorConfig` (model in `config.py`, the `mirror:` section, key `prefix`), `load_mirror_config()` (reads the `mirror:` section via `config.load_config`, `None` when the section or file is absent), `is_mirrored`/`upstream_ref` (prefix inversion preserving the `:tag@sha256:…` tail), `reference_exists` (imagetools existence probe honoring docker config creds), `mirror_targets` (declared refs filtered by prefix, sorted), the `mirror` verb (crane install + per-target `crane copy`), and `up`'s fallback helpers (`upstream_fallback`, `write_fallback_overlay`). Constraints in "Mirror namespace and upstream fallback". |
 
-## Constraints
+## Lifecycle declaration contract
 
-### Lifecycle declaration contract
+`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 (a repo with no repo-local runtime graph omits the section and hits `enforce_bake_declaration`).
 
-**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`).
+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`.
 
-**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 `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.
+`--quiet-pull` suppresses compose's per-layer progress (CUDA images carry hundreds of layers) while still surfacing pull totals. `--gpu auto` resolves to `cuda`/`rocm`/`none` from host devices and selects the matching `compose.<gpu>.yml`; override only to reproduce a CI environment or test the CPU-only path.
 
-### File and env conventions the commands assume
+## 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 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).
+- the compose layers declared in the `lifecycle:` section of `docker-devkit.yaml`; the GPU one is picked by `detect_gpu()` (or the `--gpu` override).
 - `.dockerignore` (where images are built locally) — allowlist that `context_sha.py` hashes over to compute per-service `tree-<hash>` tags. See "Docker build context" in `AGENTS-SHARED.md` for the allowlist rationale.
 
 `build` injects the `tree-<hash>` tags of locally-built images into the environment rather than writing them anywhere; `up`/`down` do the same via `compute_service_shas`. The lock stays a pure third-party pin file — a CI invariant forbids built-image digests in the committed, reviewed lock.
 
-### Mirror namespace and upstream fallback
+## Mirror namespace and upstream fallback
 
-**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).
+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: 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:
+The mirror is declared, not inferred: the `mirror:` section with `prefix` in the consumer's root `docker-devkit.yaml`. Absent section → all mirror behavior off. Under the section:
 
-- `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.
+- `build` resolves lock digests for mirror-prefixed declarations against the upstream reference (prefix stripped, tag/digest tail preserved) and records it under the mirror name. Valid because `crane copy` produces byte-identical manifests — upstream and mirror digests are the same digest; a manifest re-wrap (`docker buildx imagetools`-shaped tooling) would change the top-level digest and break lock equality. This makes declare → re-lock walkable before CI has mirrored anything; lock lines are never hand-authored.
 - `up` fails closed: after lock resolution it probes each mirror-prefixed lock entry; a missing mirror image is a hard `RuntimeError`, not a warning — people ignore warnings, and warnings are errors someone was too lazy to fix. The only escape is the per-run `--allow-upstream-fallback` flag. Under the flag, missing entries become digest-preserving address substitutions (same bytes from the upstream host), printed as plain statements — the operator asked for fallback, the run reports what it did. The rewrite is authoritative on both consumption paths: an appended `--env-file` overlay (compose's later env files win) plus `os.environ` before `build`'s bake (shell env wins over env files; `run_build` re-applies the overlay after its own lock update so bake is never clobbered). CI never passes the flag — the mirror job runs before anything needs the images.
-- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints, deliberately not ci-devkit's `ci_step`: docker-devkit and ci-devkit are siblings in the dependency DAG and the mirror verb is the only thing that would ever draw that edge. Zero new dependencies is a hard rule.
-
-**Consequences.** Non-mirror lock entries (e.g. `placeframe/*` publishes) are not probed and keep failing naturally at pull. There is no config-level ban on the flag: an air-gap fails closed anyway (no route to upstream — the pull dies with or without it).
+- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints, deliberately not ci-devkit's `ci_step` — it needs nothing from the floor.
+- Non-mirror lock entries (e.g. `placeframe/*` publishes) are not probed and keep failing naturally at pull. There is no config-level ban on the flag: an air-gap fails closed anyway (no route to upstream — the pull dies with or without it).
 
-### Package split rationale
+The ci-devkit edge exists for the builds shelf: a CI `build` run pushes the resolved `workloads/images.lock` to the repo's builds registry (`--builds-registry` + `--lock-project` + `--run-number`) through ci-devkit's `push_build` — one `images-lock`-platform artifact tagged `run-{N}` per run, the exact lock the run baked with, consumed by release-devkit's release stapler. ORAS CLI knowledge lives only in ci-devkit (org law); local builds (`--mode local`, no `--builds-registry`) never touch it.
 
-Lifecycle (`up`/`down`/`build`) and codegen (client generation, datamodel generation, workspace locking) have disjoint dependency surfaces. Bundling them would force a consumer that only brings a stack up to install `sqlacodegen`, `psycopg`, `datamodel-code-generator`. Keeping the lifecycle in its own small package lets consumers git-reference just this without dragging the codegen surface behind it.
-
-### `--quiet-pull` logging and GPU auto-detection
-
-`--quiet-pull` suppresses compose's per-layer progress (CUDA images carry hundreds of layers) while still surfacing pull totals. `--gpu auto` resolves to `cuda`/`rocm`/`none` from host devices and selects the matching `compose.<gpu>.yml`; override only to reproduce a CI environment or test the CPU-only path.
+Lifecycle stays a separate package from codegen (client generation, datamodel generation, workspace locking) because their dependency surfaces are disjoint — bundling them would force a consumer that only brings a stack up to install `sqlacodegen`, `psycopg`, `datamodel-code-generator`.
 
 ## See also
 
-- `README.md` — human-facing setup and usage.
 - [`bashrun`](https://github.com/outernet-foundation/bashrun) — the guardrailed subprocess wrapper the lifecycle commands shell out through.

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.23.dev36667933546
+Version: 0.1.24
 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: ci-devkit==0.1.15.dev36756330648
 Requires-Dist: packaging>=24.1
 Requires-Dist: pathspec>=1.0.4
 Requires-Dist: pydantic-settings>=2.9.1

docker_devkit-0.1.24/README.md

@@ -0,0 +1,3 @@
+# docker-devkit
+
+Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror`, `generate-score` — driven by a per-repo `docker-devkit.yaml`. Agent-facing documentation lives in [`AGENTS.md`](./AGENTS.md).

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "docker-devkit"
-version = "0.1.23.dev36667933546"
+version = "0.1.24"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",
+    "ci-devkit==0.1.15.dev36756330648",
     "packaging>=24.1",
     "pathspec>=1.0.4",
     "pydantic>=2.11.7",

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/release-devkit.yaml

@@ -1,5 +1,4 @@
-requires: ">=0.1"
-ci_workflow: ci-cd.yml
+ci_workflow: release.yml
 packages:
   docker-devkit:
     path: .

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/src/docker_devkit/build_docker.py

@@ -10,6 +10,7 @@ from typing import Annotated, Any, Literal
 
 import typer
 from bashrun.bash import bash, bash_output
+from ci_devkit.builds import push_build
 from .detect_gpu import GPU_TYPES, Gpu, detect_gpu
 from .documents import BakeDocument, digest_pinned, parse_bake
 from pydantic_settings import BaseSettings
@@ -31,6 +32,7 @@ METADATA_PATH = Path("metadata.json")
 
 Mode = Literal["local", "ci"]
 
+IMAGES_LOCK_PLATFORM = "images-lock"
 
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
@@ -51,6 +53,17 @@ def build(
         list[str] | None,
         typer.Option("--targets", "-t", help="Build only these services (from the image manifest)."),
     ] = None,
+    builds_registry: Annotated[
+        str | None,
+        typer.Option("--builds-registry", help="OCI registry path to push the resolved lock to (CI build artifacts)."),
+    ] = None,
+    lock_project: Annotated[
+        str | None,
+        typer.Option("--lock-project", help="Project component of the lock's builds-shelf address (CI only)."),
+    ] = None,
+    run_number: Annotated[
+        int, typer.Option("--run-number", help="CI run number baked into the lock's builds-shelf tag.")
+    ] = 0,
 ) -> None:
     run_build(
         upgrade=upgrade,
@@ -60,6 +73,9 @@ def build(
         gpu_only=gpu_only,
         no_cache=no_cache,
         targets_opt=targets_opt,
+        builds_registry=builds_registry,
+        lock_project=lock_project,
+        run_number=run_number,
     )
 
 
@@ -73,6 +89,9 @@ def run_build(
     no_cache: bool = False,
     targets_opt: list[str] | None = None,
     env_overlay: dict[str, str] | None = None,
+    builds_registry: str | None = None,
+    lock_project: str | None = None,
+    run_number: int = 0,
 ) -> None:
     root = Path.cwd()
     manifest = require_manifest(root)
@@ -204,6 +223,23 @@ def run_build(
     if not set(targets) <= baked_images.keys():
         raise RuntimeError("Bake output does not cover the requested targets")
 
+    push_images_lock(builds_registry, lock_project, run_number, lock_file)
+
+
+def push_images_lock(builds_registry: str | None, lock_project: str | None, run_number: int, lock_file: Path) -> None:
+    if builds_registry is None:
+        return
+    if not lock_project or run_number <= 0:
+        raise typer.BadParameter("--builds-registry requires --lock-project and a positive --run-number")
+    push_build(
+        builds_registry,
+        lock_project,
+        IMAGES_LOCK_PLATFORM,
+        f"run-{run_number}",
+        lock_file.parent,
+        [lock_file.name],
+    )
+
 
 # Vibe code - Gemini 3
 def _check_gc_limits(min_gb: int = 60):

{docker_devkit-0.1.23.dev36667933546 → docker_devkit-0.1.24}/uv.lock

@@ -43,16 +43,16 @@ wheels = [
 
 [[package]]
 name = "ci-devkit"
-version = "0.1.14"
+version = "0.1.15.dev36756330648"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bashrun" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/22/25/dc42c65e6147eb64477eae4f410b26d630f03f46c3d3bdcdab374df28081/ci_devkit-0.1.14.tar.gz", hash = "sha256:f8b45fa995bba626edda29c191883224173155a39137da5a1bc67f09ad28d337", size = 51204, upload-time = "2026-09-30T04:06:27.581Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5c/1e/fdad4f4fd539491f8ddeaf45e349801b274e9f7a8b00f768c6e83df1b97d/ci_devkit-0.1.15.dev36756330648.tar.gz", hash = "sha256:55b497b377a5e10e85c773b57897e4d1f883129b45567d1ecb581c02a18eabe4", size = 53675, upload-time = "2026-09-30T18:10:54.868Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4f/08/56cafd065e2d00ad90d450867282d79469bc4c7c9eefa1dc11dcf84e0c96/ci_devkit-0.1.14-py3-none-any.whl", hash = "sha256:64b74d797a040d8d57735eda30dbb59844d0de9c64e53dd24e9769d10bc34e18", size = 25689, upload-time = "2026-09-30T04:06:26.522Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/1e/9f81e475c3cc65febb1e9013caf13dd20b393275c785713a7a85498dfcbc/ci_devkit-0.1.15.dev36756330648-py3-none-any.whl", hash = "sha256:4189adc38d182591cabef7e06321ae1105cdb9fb915f38d90d352a3f277630aa", size = 28208, upload-time = "2026-09-30T18:10:54.044Z" },
 ]
 
 [[package]]
@@ -70,6 +70,7 @@ version = "0.0.0.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "bashrun" },
+    { name = "ci-devkit" },
     { name = "packaging" },
     { name = "pathspec" },
     { name = "pydantic" },
@@ -92,6 +93,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "bashrun", specifier = ">=0.1.0" },
+    { name = "ci-devkit", specifier = "==0.1.15.dev36756330648" },
     { name = "packaging", specifier = ">=24.1" },
     { name = "pathspec", specifier = ">=1.0.4" },
     { name = "pydantic", specifier = ">=2.11.7" },

docker_devkit-0.1.23.dev36667933546/.github/workflows/ci-cd.yml

@@ -1,98 +0,0 @@
-name: CI/CD
-
-on:
-  workflow_dispatch:
-  push:
-    branches: [main, dev]
-  pull_request:
-    branches: [dev]
-
-# Cancel superseded runs on the same branch, except main — where publish-stable
-# must never die mid-release (overlapping release merges queue instead).
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
-
-permissions:
-  contents: read
-
-env:
-  RELEASE_DEVKIT_VERSION: 0.1.25
-
-jobs:
-  check:
-    if: github.ref != 'refs/heads/main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          persist-credentials: false
-      - uses: astral-sh/setup-uv@v7
-        with:
-          enable-cache: true
-      - run: uv run preflight-python
-      - shell: bash
-        run: uvx --from release-devkit==${{ env.RELEASE_DEVKIT_VERSION }} publish-stable --dry-run
-
-  ensure-release-pr:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    env:
-      GH_TOKEN: ${{ github.token }}
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          persist-credentials: false
-      - uses: astral-sh/setup-uv@v7
-      - shell: bash
-        run: uvx --from release-devkit==${{ env.RELEASE_DEVKIT_VERSION }} ensure-release-pr
-
-  publish-stable:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    environment: release
-    permissions:
-      contents: write
-      id-token: write
-    env:
-      GH_TOKEN: ${{ github.token }}
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          ref: main
-          fetch-depth: 0
-          fetch-tags: true
-      - uses: astral-sh/setup-uv@v7
-      - shell: bash
-        run: uvx --from release-devkit==${{ env.RELEASE_DEVKIT_VERSION }} publish-stable
-        env:
-          NPM_CONFIG_LOGLEVEL: verbose
-
-  publish-dev:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
-    needs: [check]
-    runs-on: ubuntu-latest
-    environment: release
-    permissions:
-      contents: read
-      id-token: write
-    env:
-      GH_TOKEN: ${{ github.token }}
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          persist-credentials: false
-      - uses: astral-sh/setup-uv@v7
-      - shell: bash
-        run: uvx --from release-devkit==${{ env.RELEASE_DEVKIT_VERSION }} publish-dev
-        env:
-          NPM_CONFIG_LOGLEVEL: verbose

docker_devkit-0.1.23.dev36667933546/README.md

@@ -1,54 +0,0 @@
-# docker-devkit
-
-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.
-
-## Setup
-
-Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
-
-```bash
-uv sync
-```
-
-## Usage
-
-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 workloads/images.yml)
-uv run up --gpu none           # override GPU auto-detection
-uv run up --allow-upstream-fallback  # per-run escape: pull unmirrored lock entries from upstream at the same digest
-uv run down                    # docker compose down
-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 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 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
-
-Install from PyPI and use its entry points:
-
-```toml
-[project]
-dependencies = ["docker-devkit>=0.1.0"]
-```
-
-`bashrun` resolves transitively from PyPI. To test an unreleased change, pin the repo at a git ref in a scratch branch instead (`docker-devkit = { git = "…", rev = "<sha>" }` under `[tool.uv.sources]`) and drop the pin when the release lands.
-
-## Development
-
-```bash
-uv run ruff check .
-uv run ruff format --check .
-uv run basedpyright
-uv run pytest
-```