docker-devkit 0.1.10__tar.gz → 0.1.12__tar.gz

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/.github/workflows/release.yml

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

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/AGENTS.md

@@ -8,17 +8,18 @@ The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all depe
 
 ## Release flow
 
-Publishing rides `release.yml`, triggered by a successful CI run on a `main` push: the machinery — release-devkit's `publish-packages` (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 (first release `0.1.0`, patch-auto thereafter). API-breaking changes ship with a manually bumped version — 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 `publish-config.json`, patch-auto within the line). API-breaking changes ship with a manually bumped `major_minor` — patch-auto assumes additive changes.
 
 ## Shape
 
-Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:app`, `build` → `build_docker.py:app`. All accept `--help`.
+Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:app`, `build` → `build_docker.py:app`, `generate-score` → `score_generate.py:app`. All accept `--help`.
 
 | Module | Role |
 |---|---|
 | `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--no-dev`, `--compose-file`. |
 | `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`, `--compose-file`. |
 | `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per `compose.bake.yml`, writes `.env.lock` (third-party pulled digests) and `.env.shas` (locally-built `tree-<hash>` tags). |
+| `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `score/` sources: `${ALL_CAPS}` placeholder expansion into tempdir-rendered workload copies, idempotent `score-compose`/`score-k8s` init (state preserved across runs), and a determinism suite (document sort, state-path normalisation, 0644 modes, LF newlines). Consumer policy — workloads, provisioners, patch templates, output paths, storage classes, publishes, tool versions — is declared in the consumer's root `pyproject.toml` under `[tool.docker-devkit.generate-score]` (`ScoreConfig`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
 | `detect_gpu.py` | `detect_gpu()` → `cuda`/`rocm`/`none` from host devices; the `Gpu` literal. |
 | `modes.py` | `resolve_auth_mode()` — validates `PUBLIC_URL` + `AUTH_MODE` from `.env`, rejecting `keycloak` over cleartext `http://`. |
 | `context_sha.py` | `compute_service_shas()` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. |

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.10
+Version: 0.1.12
 Summary: Docker-stack lifecycle commands (up/down/build) with a native/consumer split
 License-File: LICENSE
 License-File: NOTICE

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/README.md

@@ -24,6 +24,8 @@ uv run down                    # docker compose down
 uv run down -v                 # also remove named volumes
 uv run build                   # cross-build all images per compose.bake.yml
 uv run build --lock-only       # refresh .env.lock without building
+uv run generate-score          # regenerate Score compose/k8s manifests per [tool.docker-devkit.generate-score]
+uv run generate-score --local  # local-cluster variant (local storage class, gitignored output)
 ```
 
 ## Consuming from another repo

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/publish-config.json

@@ -3,6 +3,7 @@
     {
       "name": "docker-devkit",
       "path": ".",
+      "major_minor": "0.1",
       "feeds": { "pypi": "docker-devkit" }
     }
   ],

{docker_devkit-0.1.10 → docker_devkit-0.1.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-devkit"
-version = "0.1.10"
+version = "0.1.12"
 description = "Docker-stack lifecycle commands (up/down/build) with a native/consumer split"
 requires-python = ">=3.13"
 dependencies = [
@@ -23,6 +23,7 @@ build-backend = "hatchling.build"
 up = "docker_devkit.up:app"
 down = "docker_devkit.down:app"
 build = "docker_devkit.build_docker:app"
+generate-score = "docker_devkit.score_generate:app"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/docker_devkit"]

docker_devkit-0.1.12/src/docker_devkit/score_generate.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Annotated, Literal
+
+import typer
+import yaml
+from bashrun.bash import bash
+from pydantic import BaseModel, ConfigDict, Field
+
+from .context_sha import compute_service_shas
+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.
+PLACEHOLDER = re.compile(r"\$\{([A-Z][A-Z0-9_]*)\}")
+
+Target = Literal["both", "compose", "k8s"]
+
+
+class ManifestMetadata(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    namespace: str = ""
+    name: str = ""
+
+
+class ManifestDocument(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    kind: str = ""
+    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("score")
+    bake_file: Path = Path("compose.bake.yml")
+    compose_output: Path = Path("compose.yaml")
+    k8s_output: Path = Path("deploy") / "manifests.yaml"
+    # --local writes here instead of the committed k8s output; consumers gitignore this path so a
+    # local-only storage class cannot reach the artifact their cluster deploys.
+    k8s_local_output: Path = Path("manifests.yaml")
+    k8s_state: Path = Path(".score-k8s")
+    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)
+
+
+@app.command()
+def cli(
+    target: Annotated[Target, typer.Option(help="Which Score artifact to generate.")] = "both",
+    local: Annotated[
+        bool,
+        typer.Option(
+            "--local",
+            help="Generate for a local cluster: local storage class, written to the configured local output path.",
+        ),
+    ] = False,
+) -> None:
+    generate(load_score_config(Path.cwd()), target, local)
+
+
+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)
+
+
+def generate(config: ScoreConfig, target: Target = "both", local: bool = False) -> None:
+    # The same call up, build, and preflight make, so every image tag is a pure function of
+    # committed source rather than a hand-typed value.
+    os.environ.update(compute_service_shas(Path.cwd(), config.bake_file))
+    os.environ[config.storage_class_var] = config.local_storage_class if local else config.cloud_storage_class
+
+    if target in ("both", "compose"):
+        _generate_compose(config)
+
+    if target in ("both", "k8s"):
+        _generate_k8s(config, config.k8s_local_output if local else config.k8s_output)
+
+
+def ensure_score_tools(config: ScoreConfig, bin_dir: Path) -> None:
+    # Fetched as release binaries rather than `go install`: score-spec tags without a leading v
+    # (0.15.0, not v0.15.0), which is not a resolvable Go module version.
+    for tool, version in (("score-k8s", config.score_k8s_version), ("score-compose", config.score_compose_version)):
+        archive = f"{tool}_{version}_linux_amd64.tar.gz"
+        bash(f"curl -fsSLO https://github.com/score-spec/{tool}/releases/download/{version}/{archive}")
+        bash(f"tar -xzf {archive} -C {bin_dir} {tool}")
+        Path(archive).unlink()
+
+
+def _generate_compose(config: ScoreConfig) -> None:
+    _init_state(
+        f"score-compose init --project {config.project_name} --no-sample",
+        config.compose_provisioners,
+        config.compose_patch_templates,
+        config.score_dir,
+    )
+
+    publishes = "".join(f" --publish {publish}" for publish in config.publishes)
+    with _rendered_workloads(config) as workloads:
+        bash(
+            f"score-compose generate {workloads} --output {config.compose_output.as_posix()}{publishes}",
+            cwd=config.score_dir,
+        )
+
+
+def _generate_k8s(config: ScoreConfig, output: Path) -> None:
+    _init_state("score-k8s init --no-sample", config.k8s_provisioners, [], config.score_dir)
+
+    (config.score_dir / output).parent.mkdir(parents=True, exist_ok=True)
+
+    with _rendered_workloads(config) as workloads:
+        bash(f"score-k8s generate {workloads} --output {output.as_posix()}", cwd=config.score_dir)
+
+    sort_documents(config.score_dir / output)
+    normalise_state_paths(config, config.score_dir / config.k8s_state / "state.yaml")
+
+
+def _init_state(command: str, provisioners: list[str], patch_templates: list[str], score_dir: Path) -> None:
+    # init is idempotent over an existing state directory: it rewrites the provisioner copies
+    # without disturbing state. The state must survive, because score-k8s mints a random uid per
+    # workload on first add and emits it as the app.kubernetes.io/instance label — discarding it
+    # would change the generated manifests on every run.
+    flags = "".join(f" --provisioners ./{name}" for name in provisioners)
+    flags += "".join(f" --patch-templates ./{name}" for name in patch_templates)
+    bash(f"{command}{flags}", cwd=score_dir)
+
+
+@contextmanager
+def _rendered_workloads(config: ScoreConfig) -> Generator[str]:
+    # Workload files are Score spec documents, not Go templates, so they cannot read the
+    # environment the way the provisioner files can. Expanding ${API_SHA} into a rendered copy
+    # keeps one mechanism across both halves.
+    with TemporaryDirectory() as temporary_directory:
+        directory = Path(temporary_directory)
+
+        for name in config.workloads:
+            source = (config.score_dir / name).read_text(encoding="utf-8")
+            (directory / name).write_text(expand_placeholders(source, name, config.bake_file), "utf-8")
+
+        yield " ".join((directory / name).as_posix() for name in config.workloads)
+
+
+def expand_placeholders(text: str, name: str, bake_file: Path) -> str:
+    parts: list[str] = []
+    index = 0
+    for match in PLACEHOLDER.finditer(text):
+        parts.append(text[index : match.start()])
+        parts.append(_placeholder_value(match.group(1), name, bake_file))
+        index = match.end()
+    parts.append(text[index:])
+    return "".join(parts)
+
+
+def _placeholder_value(variable: str, name: str, bake_file: Path) -> str:
+    value = os.environ.get(variable)
+    if not value:
+        raise SystemExit(f"{name}: ${{{variable}}} is not set. Is it a service in {bake_file}?")
+    return value
+
+
+def normalise_state_paths(config: ScoreConfig, path: Path) -> None:
+    # score-k8s records the absolute path each workload was read from. Ours are rendered into a
+    # per-run temporary directory, so the recorded path — and therefore the committed state file —
+    # would differ on every run and on every machine. The field is provenance only; the workloads
+    # are passed explicitly on each generate, so reducing it to the bare filename is safe and makes
+    # the state reproducible.
+    text = path.read_text(encoding="utf-8")
+    for name in config.workloads:
+        text = re.sub(rf"(?m)^(\s*file:\s*).*/{re.escape(name)}$", rf"\g<1>{name}", text)
+    write_generated_file(path, text)
+
+
+def sort_documents(path: Path) -> None:
+    # score-k8s emits workloads in Go map order, which is randomised, so two runs otherwise
+    # produce the same documents in a different sequence. Documents are parsed only to derive the
+    # sort key and re-emitted as their original text, so Score's formatting is preserved.
+    documents = [block for block in re.split(r"(?m)^---$\n", path.read_text(encoding="utf-8")) if block.strip()]
+    ordered = [block for _, block in sorted(enumerate(documents), key=_document_sort_key)]
+    write_generated_file(path, "".join(f"---\n{block}" for block in ordered))
+
+
+def _document_sort_key(item: tuple[int, str]) -> tuple[str, str, str, int]:
+    index, block = item
+    document = ManifestDocument.model_validate(yaml.safe_load(block) or {})
+    metadata = document.metadata or ManifestMetadata()
+    return (document.kind, metadata.namespace, metadata.name, index)
+
+
+def write_generated_file(path: Path, text: str) -> None:
+    # newline="" suppresses the platform translation Python applies by default. Without it a
+    # Windows run rewrites every line ending as CRLF while git stores LF, so the regenerated file
+    # differs from the committed one on content that never changed and the staleness gate can
+    # never pass.
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(text)
+
+    # score-k8s writes its state file executable. Git records the mode, so on Linux that alone
+    # shows up as a diff and fails the staleness gate — invisibly on Windows, where core.fileMode
+    # is false and the bit is never tracked. These are data files; normalise them to 0644.
+    path.chmod(0o644)

docker_devkit-0.1.12/tests/test_score_generate.py

@@ -0,0 +1,133 @@
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from docker_devkit.score_generate import (
+    ScoreConfig,
+    expand_placeholders,
+    normalise_state_paths,
+    sort_documents,
+    write_generated_file,
+    load_score_config,
+)
+
+
+def make_config(**overrides: str | list[str]) -> ScoreConfig:
+    values: dict[str, str | list[str]] = {
+        "workloads": ["api.yaml", "gateway.yaml"],
+        "project_name": "example",
+        "cloud_storage_class": "cloud-volumes",
+        "local_storage_class": "local-path",
+    }
+    values.update(overrides)
+    return ScoreConfig.model_validate(values)
+
+
+def test_expand_substitutes_uppercase_placeholders(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("API_SHA", "tree-abc")
+    expanded = expand_placeholders("image: registry/app:${API_SHA}", "api.yaml", Path("compose.bake.yml"))
+    assert expanded == "image: registry/app:tree-abc"
+
+
+def test_expand_leaves_score_resource_references(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("API_SHA", "tree-abc")
+    text = "host: ${resources.db.host}"
+    assert expand_placeholders(text, "api.yaml", Path("compose.bake.yml")) == text
+
+
+def test_expand_exits_on_missing_placeholder(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("API_SHA", raising=False)
+    with pytest.raises(SystemExit, match="API_SHA"):
+        expand_placeholders("image: registry/app:${API_SHA}", "api.yaml", Path("compose.bake.yml"))
+
+
+def test_sort_documents_orders_by_kind_then_namespace(tmp_path: Path) -> None:
+    path = tmp_path / "manifests.yaml"
+    service_zeta = "apiVersion: v1\nkind: Service\nmetadata:\n  name: b\n  namespace: zeta\n"
+    config_map = "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: a\n  namespace: zeta\n"
+    service_alpha = "apiVersion: v1\nkind: Service\nmetadata:\n  name: z\n  namespace: alpha\n"
+    deployment = "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: c\n  namespace: alpha\n"
+    path.write_text(f"{service_zeta}---\n{config_map}---\n{service_alpha}---\n{deployment}", encoding="utf-8")
+
+    sort_documents(path)
+
+    assert path.read_text(encoding="utf-8") == (
+        f"---\n{config_map}---\n{deployment}---\n{service_alpha}---\n{service_zeta}"
+    )
+
+
+def test_sort_documents_ignores_empty_blocks(tmp_path: Path) -> None:
+    path = tmp_path / "manifests.yaml"
+    document = "apiVersion: v1\nkind: Namespace\n"
+    path.write_text(f"{document}---\n\n---\n", encoding="utf-8")
+
+    sort_documents(path)
+
+    assert path.read_text(encoding="utf-8") == f"---\n{document}"
+
+
+def test_normalise_state_paths_reduces_rendered_paths_to_filenames(tmp_path: Path) -> None:
+    state = tmp_path / "state.yaml"
+    state.write_text(
+        "workloads:\n- name: api\n  file: /tmp/tmp1234/api.yaml\n- name: gateway\n  file: /tmp/tmp1234/gateway.yaml\n",
+        encoding="utf-8",
+    )
+
+    normalise_state_paths(make_config(), state)
+
+    text = state.read_text(encoding="utf-8")
+    assert "file: api.yaml" in text
+    assert "file: gateway.yaml" in text
+    assert "/tmp/tmp1234" not in text
+
+
+def test_write_normalises_file_mode(tmp_path: Path) -> None:
+    path = tmp_path / "state.yaml"
+    path.write_text("placeholder", encoding="utf-8")
+    path.chmod(0o755)
+
+    write_generated_file(path, "content\n")
+
+    assert path.stat().st_mode & 0o777 == 0o644
+    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",
+    )
+
+    config = load_score_config(tmp_path)
+
+    assert config.workloads == ["api.yaml"]
+    assert config.project_name == "placeframe"
+    assert config.publishes == ["8000:api:8000"]
+    assert config.compose_output == Path("compose.yaml")
+    assert config.k8s_output == Path("deploy") / "manifests.yaml"
+    assert config.score_k8s_version == "0.15.0"
+    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")
+
+    with pytest.raises(RuntimeError, match="generate-score"):
+        load_score_config(tmp_path)
+
+
+def test_score_config_rejects_unknown_keys() -> None:
+    with pytest.raises(ValidationError):
+        ScoreConfig.model_validate({
+            "workloads": ["api.yaml"],
+            "project_name": "example",
+            "cloud_storage_class": "cloud-volumes",
+            "local_storage_class": "local-path",
+            "publication": ["8000:api:8000"],
+        })