unity-devkit 0.1.13__tar.gz → 0.1.14__tar.gz

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/.github/workflows/release.yml

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

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/AGENTS.md

@@ -2,13 +2,13 @@
 
 ## What this is
 
-`unity-devkit` is the Unity build toolkit: project discovery, local builds, CI builds, license activation, the `install` command (download-or-build then install onto a device), and the ORAS cache/setup helpers those need. Consumer repositories install this package from PyPI and get the same Unity CI and install flow — paired with the reusable `unity-build.yml` GitHub Actions workflow hosted in this repo's `.github/workflows/`, which invokes only this package's entry points inside the caller's checkout.
+`unity-devkit` is the Unity build toolkit: the root project catalog, local builds, CI builds, license activation, the `install` command (download-or-build then install onto a device), and the ORAS cache/setup helpers those need. Consumer repositories install this package from PyPI and get the same Unity CI and install flow — paired with the reusable `unity-build.yml` GitHub Actions workflow hosted in this repo's `.github/workflows/`, which invokes only this package's entry points inside the caller's checkout.
 
 The repo and package renamed from `unity-buildkit` to `unity-devkit` (2026-09-21, member of the `-devkit` family; before that `placeframe-unity` → `unity-buildkit` on extraction). The PyPI identity is fresh: `unity-devkit` starts its own tag ledger at `0.1.0`; the terminal `unity-buildkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
 
 ## 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 (unity-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 `unity-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.
+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 (unity-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 `unity-devkit-v*` tags are the version ledger (declared `major_minor` line in `publish-config.json`, patch-auto within the line). While pre-1.0, breaking changes ride the current `0.1` patch line; a `major_minor` bump is reserved for the eventual 1.0.0 stabilization release.
 
 ## Shape
 
@@ -16,8 +16,8 @@ One flat module per concern under `src/unity_devkit/`:
 
 | `uv run` command | Module | Notes |
 |---|---|---|
-| `compile-unity` | `compile_unity.py` | Local Unity build (APK or platform binary, suitable for `adb install`). Required flags: `--project <name>` and `--build <target>`, where the project's `unity-build.json` declares `builds` and `execute_methods`. Streams the editor log, prints output paths under `<project>/Build/`. |
-| `install` | `install.py` | Install a Unity build onto an `adb`-connected device or launch a linux executable. Default: download the latest GitHub Actions artifact for `(project, target)` on the current branch (overridable with `--branch` / `--run`), cache it under `~/.unity-devkit/builds/{run_id}/`, `adb install` the APK (or `bash_handoff` the linux64 executable). With `--build` / `-B`, skips the artifact fetch and calls `compile-unity` locally instead, funneling the produced APK / executable through the same install path. Honours the manifest's `package` (for pre-install uninstall) and `grant_permissions` (post-install `adb shell pm grant`). |
+| `compile-unity` | `compile_unity.py` | Local Unity build (APK or platform binary, suitable for `adb install`). Required flags: `--project <name>` and `--build <target>`, where the project's `unity-devkit.json` catalog entry declares `builds` and `execute_methods`. Streams the editor log, prints output paths under `<project>/Build/`. |
+| `install` | `install.py` | Install a Unity build onto an `adb`-connected device or launch a linux executable. Default: download the latest GitHub Actions artifact for `(project, target)` on the current branch (overridable with `--branch` / `--run`), cache it under `~/.unity-devkit/builds/{run_id}/`, `adb install` the APK (or `bash_handoff` the linux64 executable). With `--build` / `-B`, skips the artifact fetch and calls `compile-unity` locally instead, funneling the produced APK / executable through the same install path. Honours the catalog entry's `package` (for pre-install uninstall) and `grant_permissions` (post-install `adb shell pm grant`). |
 | `lock-unity` | `lock_unity.py` | Lock Unity package versions for reproducible builds. |
 | `test-unity` | `test_unity.py` | Run Unity editmode / playmode tests. |
 | `activate-unity-license` | `license.py` | Activate the Unity Editor license (locally or with `--oras-push` for the CI cache). |
@@ -25,7 +25,7 @@ One flat module per concern under `src/unity_devkit/`:
 | `unity-matrix` | `matrix.py` | Emit the CI build matrix (CI-only). |
 | `build-unity` | `build_unity.py` | CI build with library cache restore/save and version stamping (CI-only; assumes `GITHUB_WORKSPACE`, OCI registry, runner environment). |
 
-Supporting modules: `projects.py` (manifest schema + discovery), `unity.py` (editor lookup, platform configs, batchmode command, shared Unity runner). The CI-floor modules (step wrapper, runner provisioning, ORAS artifact cache, git-tag helpers) live in [`ci-devkit`](https://github.com/outernet-foundation/ci-devkit) (a runtime dependency); unity-devkit owns only Unity concerns.
+Supporting modules: `projects.py` (catalog schema + loader, and the pruned tree walk that is cross-repo API), `unity.py` (editor lookup, platform configs, batchmode command, shared Unity runner). The CI-floor modules (step wrapper, runner provisioning, ORAS artifact cache) live in [`ci-devkit`](https://github.com/outernet-foundation/ci-devkit) (a runtime dependency); unity-devkit owns only Unity concerns.
 
 ## Constraints
 
@@ -33,15 +33,15 @@ Supporting modules: `projects.py` (manifest schema + discovery), `unity.py` (edi
 
 **Every runtime dependency must be PyPI-resolvable.** This package publishes to and is consumed from PyPI, and a registry consumer resolves the whole graph transitively by name — any dependency that is not on PyPI breaks every consumer's install. [`bashrun`](https://github.com/outernet-foundation/bashrun) is on PyPI like the rest; git-source pins are a scratch-branch-only vehicle for testing unreleased changes.
 
-**Unity project discovery is structural, with `unity-build.json` as an optional intent overlay.** The Unity commands discover projects by scanning the working-directory tree for `ProjectSettings/ProjectVersion.txt` (pruning `Library`, `Temp`, `obj`, `Build`, `node_modules`, `.git`, and dot-directories) — the marker Unity itself writes, so existence needs no opt-in file. The project name is the directory name. A `unity-build.json` manifest beside it carries only intent the project cannot otherwise express (`builds`, `execute_methods`, `package`, `grant_permissions`, `tag_prefix` — schema in `projects.py`); it is required by the verbs that consume those fields (`compile-unity`, `build-unity`, `install`, `unity-matrix` — which fail with pointers to the missing manifest fields) and ignored by the path-only verbs (`lock-unity`, `test-unity`). A manifest found in a directory without the structural marker is a hard error — a misconfigured manifest must fail loud, not silently skip. There is no central catalog: a project's build identity lives inside the project, so it travels with the project if it moves between repositories. Discovery anchors at the current working directory — run commands from the repo root. Vendored or nested projects that should not be touched are kept out of all-projects verbs (`lock-unity`, `test-unity` without `--project`) by the prune list or by passing `--project` explicitly.
+**Unity projects are declared in a root catalog.** `unity-devkit.json` at the repo root maps stable project names to entries (`path`, `builds`, `execute_methods`, `package`, `grant_permissions`, `tag_prefix` — schema in `projects.py`). Every verb resolves `--project` through the catalog, the path-only ones (`lock-unity`, `test-unity`) included — absence from the catalog is the exclusion mechanism: a project not listed is never touched, so vendored or nested projects need no prune list. Names are catalog keys, decoupled from directory names; they are the workflow contract (`matrix.project-name`, artifact names, `--project` everywhere). `ProjectSettings/ProjectVersion.txt` inside each entry's project remains the editor-version truth, read per entry; an entry whose path lacks the marker fails at load, as does a missing or empty catalog. Run commands from the repo root — catalog paths are repo-relative. The per-project `unity-build.json` manifests and the structural marker walk are gone from the verbs; the pruned walk (`projects.directories_containing`) remains as cross-repo API.
 
-**`unity-matrix` prints `$GITHUB_OUTPUT`-format lines, not bare JSON.** Its stdout is two `key=value` lines — `matrix=<JSON with an include array>` and `license-image=<unityci/editor tag>` — so the workflow step is exactly `uv run --no-sync unity-matrix >> "$GITHUB_OUTPUT"` with no shell logic. Each matrix entry carries an `editor-image` tag composed from the project's `ProjectSettings/ProjectVersion.txt` editor version, the platform's unityci module, and the `UNITYCI_IMAGE_REVISION` constant in `unity.py`; `license-image` uses the highest discovered editor version with the `linux-il2cpp` module. Nothing else pins an editor version: upgrading a project's editor in `ProjectVersion.txt` automatically switches its CI container, and the hosted `unity-build.yml` stays free of repo-specific values.
+**`unity-matrix` prints `$GITHUB_OUTPUT`-format lines, not bare JSON.** Its stdout is two `key=value` lines — `matrix=<JSON with an include array>` and `license-image=<unityci/editor tag>` — so the workflow step is exactly `uv run --no-sync unity-matrix >> "$GITHUB_OUTPUT"` with no shell logic. Each matrix entry carries an `editor-image` tag composed from the project's `ProjectSettings/ProjectVersion.txt` editor version, the platform's unityci module, and the `UNITYCI_IMAGE_REVISION` constant in `unity.py`; `license-image` uses the highest cataloged editor version with the `linux-il2cpp` module. Nothing else pins an editor version: upgrading a project's editor in `ProjectVersion.txt` automatically switches its CI container, and the hosted `unity-build.yml` stays free of repo-specific values.
 
 **Entry-point names are the workflow contract.** The hosted `unity-build.yml` invokes `unity-matrix`, `unity-license-tag`, `activate-unity-license`, and `build-unity` by name via `uv run` in the caller's checkout (the caller's venv supplies this package). Consumers pin the workflow by pushed SHA and the package by PyPI version independently; the two pins stay compatible as long as the entry-point names and flags hold, so treat those as a public API.
 
 **The environment-lookup helpers are cross-repo Python API.** `unity.find_editor_for_version` (editor ladder: `unity-editor` on PATH → `/opt/unity/<version>` → `~/Unity/Hub/Editor/<version>`; raises `ValueError` listing every searched path on a miss), `unity.editor_version` (`ProjectVersion.txt` parse; `None` for a missing file or unparseable content), and `projects.directories_containing` (+ `PRUNE_DIRECTORIES`) are imported by registry consumers — prepo's `sync` verb. Their signatures and miss behavior are contract, not internals. The `SystemExit`-raising wrapper `read_editor_version` exists for unity-devkit's own CLI paths and delegates to the core helper; `unity_batchmode_command` consumes the `ValueError`-raising `find_editor_for_version` and `read_editor_version` directly, so a missing editor surfaces as the raw `ValueError`.
 
-**Version stamping is opt-in via `tag_prefix`.** `build-unity` writes `.build-version.json` (consumed by the project's build `executeMethod`) only when the project's manifest declares `tag_prefix`; the version is the latest `<tag_prefix>-v*` git tag plus a run-number suffix. Projects without the field build unversioned. Consumer repos that release keep their own name→prefix map on their side — the two must agree for projects that release.
+**Version stamping is opt-in via `tag_prefix`.** `build-unity` writes `.build-version.json` (consumed by the project's build `executeMethod`) only when the project's catalog entry declares `tag_prefix`; the version is the latest `<tag_prefix>-v*` git tag (a local bashrun query — the version-ledger primitives live in release-devkit and are not imported here) plus a run-number suffix. Projects without the field build unversioned. The catalog's `tag_prefix` and the same package's `tag_prefix` in the repo's `release-devkit.json` are two spellings of one fact — they must agree for projects that release.
 
 **The ORAS cache media type identifies the wrapper package, not the consuming repo.** `cache.save()` pushes with `application/vnd.unity-devkit.cache.v1+zstd`. Restore doesn't filter on media type, so older manifests carrying a different vendor prefix still pull, but new pushes always carry this one — the identifier tracks the tool that wrote the cache, not the project whose bytes are inside it.
 

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: unity-devkit
-Version: 0.1.13
-Summary: Unity project discovery, build, license, and CI tooling
+Version: 0.1.14
+Summary: Unity build, license, and CI tooling
 License-File: LICENSE
 License-File: NOTICE
 Requires-Python: >=3.13

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/README.md

@@ -1,6 +1,6 @@
 # unity-devkit
 
-Unity project discovery, local builds, CI builds, license activation, and the shared CI helpers those need. Projects are discovered structurally: any directory containing `ProjectSettings/ProjectVersion.txt` (the marker Unity itself writes) is a project; a `unity-build.json` manifest beside it optionally declares build intent (`builds`, `execute_methods`, `package`, `grant_permissions`, `tag_prefix`). Path-only commands (`lock-unity`, `test-unity`) work on any discovered project; build commands require the manifest's fields. Paired with the reusable [`unity-build.yml`](https://github.com/outernet-foundation/unity-devkit/blob/main/.github/workflows/unity-build.yml) GitHub Actions workflow hosted here — consumers call it cross-repo pinned to a pushed SHA with `secrets: inherit`.
+Unity build, license, and CI tooling. Projects are declared in a root `unity-devkit.json` catalog: each entry maps a stable project name to its path plus optional build intent (`builds`, `execute_methods`, `package`, `grant_permissions`, `tag_prefix`). Every command resolves projects through the catalog — absence from the catalog is the exclusion mechanism — and `ProjectSettings/ProjectVersion.txt` inside each project remains the editor-version truth. Paired with the reusable [`unity-build.yml`](https://github.com/outernet-foundation/unity-devkit/blob/main/.github/workflows/unity-build.yml) GitHub Actions workflow hosted here — consumers call it cross-repo pinned to a pushed SHA with `secrets: inherit`.
 
 ## Setup
 
@@ -12,7 +12,7 @@ uv sync
 
 ## Commands
 
-Run from a repo root containing one or more Unity projects (directories with `ProjectSettings/ProjectVersion.txt`).
+Run from a repo root with a `unity-devkit.json` catalog declaring its Unity projects.
 
 | `uv run <name>` | What it does |
 |---|---|
@@ -36,7 +36,7 @@ Install from PyPI:
 dependencies = ["unity-devkit>=0.1.0"]
 ```
 
-Then `uv run compile-unity`, `uv run install`, etc. work from that repo against its own Unity projects (add a `unity-build.json` where build intent is needed). To test an unreleased change, pin the repo at a git ref in a scratch branch instead (`unity-devkit = { git = "…", rev = "<sha>" }` under `[tool.uv.sources]`) and drop the pin when the release lands.
+Then `uv run compile-unity`, `uv run install`, etc. work from that repo against its own Unity projects — declare them in a root `unity-devkit.json` catalog (entries need `builds` + `execute_methods` where build intent is needed). To test an unreleased change, pin the repo at a git ref in a scratch branch instead (`unity-devkit = { git = "…", rev = "<sha>" }` under `[tool.uv.sources]`) and drop the pin when the release lands.
 
 ## Development
 

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/publish-config.json

@@ -7,6 +7,5 @@
       "feeds": { "pypi": "unity-devkit" }
     }
   ],
-  "ci_workflow": "ci.yml",
-  "mirror_prefix": "ghcr.io/outernet-foundation/mirror"
+  "ci_workflow": "ci.yml"
 }

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "unity-devkit"
-version = "0.1.13"
-description = "Unity project discovery, build, license, and CI tooling"
+version = "0.1.14"
+description = "Unity build, license, and CI tooling"
 requires-python = ">=3.13"
 dependencies = [
     "bashrun>=0.1.0",

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/build_unity.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Annotated
 
 import typer
+from bashrun.bash import bash_output
 from pydantic_settings import BaseSettings
 
 from ci_devkit.cache import restore, save
@@ -15,15 +16,12 @@ from .license_restore import restore_license
 from ci_devkit.setup import configure_git, install_dotnet
 from ci_devkit.setup_oras import install_oras
 from .unity import prepare_unity_project, resolve_unity_build, run_unity_batchmode
-from ci_devkit.git_tags import get_latest_tag_version
 
 
 class Settings(BaseSettings):
     github_workspace: str
 
 
-settings = Settings.model_validate({})
-
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 
@@ -40,6 +38,8 @@ def main(
         str, typer.Option(help="Newline-separated KEY=VALUE pairs injected into the Unity build process environment")
     ] = "",
 ) -> None:
+    settings = Settings.model_validate({})
+
     for line in build_env.splitlines():
         entry = line.strip()
         if not entry:
@@ -66,14 +66,18 @@ def main(
     with ci_step("Prepare build"):
         project_config, build_flag, execute_method = resolve_unity_build(project, platform)
         unity_project_path = project_config.path
+        if unity_project_path.resolve() != project_path.resolve():
+            raise SystemExit(
+                f"--project-path {project_path} does not match catalog entry '{project}' at {unity_project_path}"
+            )
 
     with ci_step("Prepare project"):
         prepare_unity_project(unity_project_path)
 
-    with ci_step(f"Build {unity_project_path.name} [{platform}]"):
+    with ci_step(f"Build {project} [{platform}]"):
         tag_prefix = project_config.tag_prefix
         if tag_prefix:
-            version = get_latest_tag_version(f"{tag_prefix}-v") or "0.0.0"
+            version = latest_tag_version(f"{tag_prefix}-v") or "0.0.0"
             full_version = f"{version}-dev+{run_number}" if branch != "main" else f"{version}+{run_number}"
             version_file = unity_project_path / ".build-version.json"
             version_file.write_text(json.dumps({"version": full_version, "runNumber": run_number}))
@@ -100,3 +104,10 @@ def main(
                 for file in build_directory.rglob("*"):
                     if file.suffix in {".apk", ".exe"}:
                         shutil.copy2(file, artifact_directory / file.name)
+
+
+def latest_tag_version(prefix: str) -> str | None:
+    output = bash_output(f'git tag --list "{prefix}*" --sort=-v:refname').strip()
+    if not output:
+        return None
+    return output.splitlines()[0][len(prefix) :]

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/compile_unity.py

@@ -10,9 +10,7 @@ app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 @app.command()
 def compile_unity(
-    project: Annotated[
-        str, typer.Option(help="Unity project name (directory containing ProjectSettings/ProjectVersion.txt)")
-    ],
+    project: Annotated[str, typer.Option(help="Unity project name (catalog key in unity-devkit.json)")],
     build: Annotated[str, typer.Option(help="Build target from the project's builds list (e.g. android-mobile)")],
 ) -> None:
     for artifact in build_unity_project(project, build):

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/install.py

@@ -9,7 +9,7 @@ import typer
 from bashrun.bash import bash, bash_check, bash_handoff, bash_output
 
 from .compile_unity import build_unity_project
-from .projects import load_unity_projects
+from .projects import load_catalog
 
 INSTALLABLE_TARGETS = {"android-mobile", "magicleap", "linux64"}
 ADB_TARGETS = {"android-mobile", "magicleap"}
@@ -37,7 +37,7 @@ def main(
             "--no-grant-permissions",
             help=(
                 "Skip the post-install `adb shell pm grant` calls listed under `grant_permissions` "
-                "for the project in its unity-build.json manifest. Permissions are granted by default."
+                "for the project's entry in unity-devkit.json. Permissions are granted by default."
             ),
         ),
     ] = False,
@@ -53,7 +53,7 @@ def main(
         ),
     ] = False,
 ) -> None:
-    projects = load_unity_projects()
+    projects = load_catalog()
 
     project_name = next((name for name in projects if name.lower() == project.lower()), None)
     if project_name is None:
@@ -156,7 +156,7 @@ def main(
         if permissions and not no_grant_permissions:
             if not package:
                 raise typer.BadParameter(
-                    f"{project_name} has grant_permissions but no 'package' field in unity-build.json"
+                    f"{project_name} has grant_permissions but no 'package' field in its unity-devkit.json entry"
                 )
             for permission in permissions:
                 print(f"Granting {permission} to {package}")

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/lock_unity.py

@@ -2,7 +2,7 @@ from typing import Annotated
 
 import typer
 
-from .projects import load_unity_projects
+from .projects import load_catalog
 from .unity import prepare_unity_project, run_unity_batchmode
 
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
@@ -10,7 +10,7 @@ app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 @app.command()
 def lock_unity(project: Annotated[str | None, typer.Option(help="Limit to a specific project.")] = None) -> None:
-    config = load_unity_projects()
+    config = load_catalog()
 
     if project is not None and project not in config:
         raise typer.BadParameter(f"Unknown project '{project}'. Valid: {', '.join(config)}")

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/matrix.py

@@ -1,12 +1,12 @@
 import json
 from pathlib import Path
 
-from .projects import load_unity_projects
+from .projects import load_catalog
 from .unity import LICENSE_MODULE, PLATFORM_CONFIGS, UNITYCI_IMAGE_REVISION, read_editor_version
 
 
 def main() -> None:
-    projects = load_unity_projects()
+    projects = load_catalog()
     matrix: list[dict[str, str]] = []
     editor_versions: set[str] = set()
 
@@ -28,7 +28,7 @@ def main() -> None:
 
     if not editor_versions:
         raise SystemExit(
-            "No projects with builds declared — unity-matrix needs at least one unity-build.json with a 'builds' list"
+            "No projects with builds declared — unity-matrix needs at least one unity-devkit.json entry with a 'builds' list"
         )
     license_version = max(editor_versions)
     print(f"matrix={json.dumps({'include': matrix})}")

unity_devkit-0.1.14/src/unity_devkit/projects.py

@@ -0,0 +1,59 @@
+import os
+from collections.abc import Iterator
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, field_validator
+
+CATALOG_FILENAME = "unity-devkit.json"
+PROJECT_MARKER = Path("ProjectSettings") / "ProjectVersion.txt"
+PRUNE_DIRECTORIES = {".git", "Library", "Temp", "obj", "Build", "node_modules", "__pycache__"}
+
+
+class CatalogEntry(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: Path
+    builds: list[str] | None = None
+    execute_methods: dict[str, str] | None = None
+    package: str | None = None
+    grant_permissions: list[str] = Field(default_factory=list)
+    tag_prefix: str | None = None
+
+    @field_validator("path")
+    @classmethod
+    def anchor_relative_path(cls, value: Path) -> Path:
+        return value if value.is_absolute() else Path.cwd() / value
+
+
+CATALOG_ADAPTER = TypeAdapter(dict[str, CatalogEntry])
+
+
+def load_catalog() -> dict[str, CatalogEntry]:
+    catalog_path = Path.cwd() / CATALOG_FILENAME
+    if not catalog_path.is_file():
+        raise SystemExit(
+            f"No {CATALOG_FILENAME} catalog at {catalog_path} — declare Unity projects as catalog entries at the repo root"
+        )
+
+    catalog = CATALOG_ADAPTER.validate_json(catalog_path.read_text(encoding="utf-8"))
+    if not catalog:
+        raise SystemExit(f"{catalog_path} declares no projects — at least one catalog entry is required")
+
+    for name, entry in catalog.items():
+        if not (entry.path / PROJECT_MARKER).is_file():
+            raise SystemExit(
+                f"Catalog entry '{name}' points at {entry.path}, which is not a Unity project: missing {PROJECT_MARKER}"
+            )
+    return catalog
+
+
+def visible_directories(root: Path) -> Iterator[Path]:
+    for directory, subdirectories, _filenames in os.walk(root):
+        subdirectories[:] = sorted(
+            name for name in subdirectories if name not in PRUNE_DIRECTORIES and not name.startswith(".")
+        )
+        yield Path(directory)
+
+
+def directories_containing(root: Path, filename: str) -> list[Path]:
+    return [directory for directory in visible_directories(root) if (directory / filename).is_file()]

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/test_unity.py

@@ -5,7 +5,7 @@ from typing import Annotated
 
 import typer
 
-from .projects import load_unity_projects
+from .projects import load_catalog
 from .unity import run_unity_batchmode
 
 app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
@@ -13,15 +13,13 @@ app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
 
 @app.command()
 def main(
-    project: Annotated[
-        str, typer.Option(help="Unity project name (directory containing ProjectSettings/ProjectVersion.txt)")
-    ],
+    project: Annotated[str, typer.Option(help="Unity project name (catalog key in unity-devkit.json)")],
     test_platform: Annotated[str, typer.Option(help="Unity test platform (EditMode or PlayMode)")] = "EditMode",
     results: Annotated[Path, typer.Option(help="Output path for NUnit XML results")] = Path(
         "artifacts/unity-test-results.xml"
     ),
 ) -> None:
-    projects = load_unity_projects()
+    projects = load_catalog()
     if project not in projects:
         raise SystemExit(f"Unknown project '{project}'. Valid: {', '.join(projects)}")
 

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/src/unity_devkit/unity.py

@@ -6,7 +6,7 @@ from typing import TypedDict
 
 from bashrun.bash import CalledProcessError, bash, bash_pipe
 
-from .projects import UnityProject, load_unity_projects
+from .projects import CatalogEntry, load_catalog
 
 
 class PlatformConfig(TypedDict):
@@ -134,8 +134,8 @@ def editor_version(project_path: Path) -> str | None:
     return None
 
 
-def resolve_unity_build(project: str, build: str) -> tuple[UnityProject, str, str]:
-    projects = load_unity_projects()
+def resolve_unity_build(project: str, build: str) -> tuple[CatalogEntry, str, str]:
+    projects = load_catalog()
     if project not in projects:
         raise SystemExit(f"Unknown project '{project}'. Valid: {', '.join(projects)}")
 
@@ -143,7 +143,7 @@ def resolve_unity_build(project: str, build: str) -> tuple[UnityProject, str, st
     valid_builds = project_config.builds or []
     if not valid_builds:
         raise SystemExit(
-            f"Project '{project}' declares no builds — add a unity-build.json with a 'builds' list to {project_config.path}"
+            f"Project '{project}' declares no builds — add a 'builds' list to its entry in unity-devkit.json"
         )
     if build not in valid_builds:
         raise SystemExit(f"Unknown build '{build}' for project '{project}'. Valid: {', '.join(valid_builds)}")
@@ -151,7 +151,7 @@ def resolve_unity_build(project: str, build: str) -> tuple[UnityProject, str, st
     execute_method = (project_config.execute_methods or {}).get(build)
     if not execute_method:
         raise SystemExit(
-            f"No execute method for '{build}' — declare 'execute_methods' in {project_config.path / 'unity-build.json'}"
+            f"No execute method for '{build}' — declare it under 'execute_methods' for '{project}' in unity-devkit.json"
         )
 
     if build not in PLATFORM_CONFIGS:

unity_devkit-0.1.14/tests/test_latest_tag_version.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+import pytest
+from bashrun.bash import bash
+
+from unity_devkit.build_unity import latest_tag_version
+
+
+def test_latest_tag_version_returns_newest_version_sorted(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    bash("git init -q")
+    bash("git config user.email test@example.com")
+    bash("git config user.name test")
+    bash("git commit --allow-empty -m init -q")
+    for version in ("0.1.2", "0.1.9", "0.1.10"):
+        bash(f"git tag thing-v{version}")
+
+    assert latest_tag_version("thing-v") == "0.1.10"
+    assert latest_tag_version("absent-v") is None

unity_devkit-0.1.14/tests/test_matrix.py

@@ -0,0 +1,46 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from unity_devkit import matrix
+
+
+def write_repository(tmp_path: Path, entry: dict[str, object]) -> None:
+    project = tmp_path / "apps" / "Tool"
+    (project / "ProjectSettings").mkdir(parents=True)
+    (project / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
+    (tmp_path / "unity-devkit.json").write_text(json.dumps({"tool": entry}))
+
+
+def test_matrix_emits_entries_from_catalog(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    write_repository(
+        tmp_path, {"path": "apps/Tool", "builds": ["linux64"], "execute_methods": {"linux64": "Tool.Build"}}
+    )
+    monkeypatch.chdir(tmp_path)
+
+    matrix.main()
+
+    lines = capsys.readouterr().out.splitlines()
+    include = json.loads(lines[0][len("matrix=") :])["include"]
+    assert include == [
+        {
+            "project": str(Path("apps") / "Tool"),
+            "project-name": "tool",
+            "cache-key": "tool",
+            "platform": "linux64",
+            "module": "linux-il2cpp",
+            "editor-image": "unityci/editor:6000.0.66f1-linux-il2cpp-3",
+        }
+    ]
+    assert lines[1] == "license-image=unityci/editor:6000.0.66f1-linux-il2cpp-3"
+
+
+def test_matrix_fails_without_builds(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "apps/Tool"})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="No projects with builds declared"):
+        matrix.main()

unity_devkit-0.1.14/tests/test_projects.py

@@ -0,0 +1,90 @@
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from unity_devkit.projects import directories_containing, load_catalog
+
+
+def write_catalog(root: Path, catalog: dict[str, object]) -> Path:
+    catalog_path = root / "unity-devkit.json"
+    catalog_path.write_text(json.dumps(catalog))
+    return catalog_path
+
+
+def create_unity_project(root: Path, relative: str) -> Path:
+    project = root / relative
+    (project / "ProjectSettings").mkdir(parents=True)
+    (project / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
+    return project
+
+
+def test_catalog_entry_loads_with_intent_fields(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    create_unity_project(tmp_path, "Alpha")
+    write_catalog(tmp_path, {"Alpha": {"path": "Alpha", "builds": ["linux64"], "tag_prefix": "alpha"}})
+    monkeypatch.chdir(tmp_path)
+
+    projects = load_catalog()
+
+    assert set(projects) == {"Alpha"}
+    assert projects["Alpha"].path == Path.cwd() / "Alpha"
+    assert projects["Alpha"].builds == ["linux64"]
+    assert projects["Alpha"].tag_prefix == "alpha"
+    assert projects["Alpha"].grant_permissions == []
+
+
+def test_catalog_name_is_decoupled_from_directory_name(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    create_unity_project(tmp_path, "apps/capture-tool")
+    write_catalog(tmp_path, {"capture": {"path": "apps/capture-tool"}})
+    monkeypatch.chdir(tmp_path)
+
+    projects = load_catalog()
+
+    assert set(projects) == {"capture"}
+    assert projects["capture"].path == Path.cwd() / "apps" / "capture-tool"
+
+
+def test_missing_catalog_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match=r"No unity-devkit\.json catalog"):
+        load_catalog()
+
+
+def test_empty_catalog_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_catalog(tmp_path, {})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="declares no projects"):
+        load_catalog()
+
+
+def test_entry_outside_unity_project_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    (tmp_path / "not-a-project").mkdir()
+    write_catalog(tmp_path, {"broken": {"path": "not-a-project"}})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="not a Unity project"):
+        load_catalog()
+
+
+def test_unknown_entry_key_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    create_unity_project(tmp_path, "Alpha")
+    write_catalog(tmp_path, {"Alpha": {"path": "Alpha", "unity-build": True}})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(ValidationError):
+        load_catalog()
+
+
+def test_directories_containing_honors_prune_list(tmp_path: Path) -> None:
+    vendored = tmp_path / "vendor" / "Library" / "SomeProject"
+    (vendored / "ProjectSettings").mkdir(parents=True)
+    (vendored / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
+    real = create_unity_project(tmp_path, "Real")
+
+    settings_directories = directories_containing(tmp_path, "ProjectVersion.txt")
+
+    assert real / "ProjectSettings" in settings_directories
+    assert vendored / "ProjectSettings" not in settings_directories

unity_devkit-0.1.14/tests/test_resolve.py

@@ -0,0 +1,56 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from unity_devkit.unity import resolve_unity_build
+
+
+def write_repository(tmp_path: Path, entry: dict[str, object]) -> None:
+    project = tmp_path / "Tool"
+    (project / "ProjectSettings").mkdir(parents=True)
+    (project / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
+    (tmp_path / "unity-devkit.json").write_text(json.dumps({"tool": entry}))
+
+
+def test_unknown_project_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "Tool", "builds": ["linux64"], "execute_methods": {"linux64": "Tool.Build"}})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="Unknown project 'nope'"):
+        resolve_unity_build("nope", "linux64")
+
+
+def test_project_without_builds_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "Tool"})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="declares no builds"):
+        resolve_unity_build("tool", "linux64")
+
+
+def test_unknown_build_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "Tool", "builds": ["linux64"], "execute_methods": {"linux64": "Tool.Build"}})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="Unknown build 'win64'"):
+        resolve_unity_build("tool", "win64")
+
+
+def test_missing_execute_method_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "Tool", "builds": ["linux64"]})
+    monkeypatch.chdir(tmp_path)
+
+    with pytest.raises(SystemExit, match="No execute method"):
+        resolve_unity_build("tool", "linux64")
+
+
+def test_resolve_returns_platform_config(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    write_repository(tmp_path, {"path": "Tool", "builds": ["linux64"], "execute_methods": {"linux64": "Tool.Build"}})
+    monkeypatch.chdir(tmp_path)
+
+    project_config, build_flag, execute_method = resolve_unity_build("tool", "linux64")
+
+    assert project_config.path == Path.cwd() / "Tool"
+    assert build_flag == "-buildTarget StandaloneLinux64"
+    assert execute_method == "Tool.Build"

{unity_devkit-0.1.13 → unity_devkit-0.1.14}/uv.lock

@@ -34,25 +34,25 @@ wheels = [
 
 [[package]]
 name = "bashrun"
-version = "0.1.2"
+version = "0.1.9"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/2d/7b/ad8a6956d6b739ad504775680d8f115c29e5b58fe4c7de414c481555ddda/bashrun-0.1.2.tar.gz", hash = "sha256:f0473aad601645e656f4e6ab7721597d92c771a0b316a3ea86d02a678038493c", size = 22172, upload-time = "2026-09-22T01:41:07.558Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/61/cd/ce0a41f08e1392c9bb4ecfa9533973ce537e339c691df22acffe71860d13/bashrun-0.1.9.tar.gz", hash = "sha256:693c8b13c3576b969c28a22cebc6b39da9957de647a49d7faa36b0843feec29a", size = 22266, upload-time = "2026-09-24T02:05:10.783Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/de/4a/b232f90df0829fae33b0b7d28b0771df9e30f31557799d183c25be4f6bdb/bashrun-0.1.2-py3-none-any.whl", hash = "sha256:d16244f9c1f59a271d7f5b7b20bd3bc2007ee12cfa6b2b9e4476237728699048", size = 7499, upload-time = "2026-09-22T01:41:06.643Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/28/ab9f3a6739d62a39827ab86015e4f44d0c0dbf2f4c171f185185ecec28cc/bashrun-0.1.9-py3-none-any.whl", hash = "sha256:abd34396256184e0f9ac7e0f45659269f3f83bcf6ad22ebec862a197e9d6d3eb", size = 7500, upload-time = "2026-09-24T02:05:09.795Z" },
 ]
 
 [[package]]
 name = "ci-devkit"
-version = "0.1.0"
+version = "0.1.10"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bashrun" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/9c/58/e0c1f17fbcf6e7adcc4192d5d0a4300be2b0d0ffd055ff746f0116ad587a/ci_devkit-0.1.0.tar.gz", hash = "sha256:ac1a463effe9a2760ea6d18301d6938c6a47d07cee9d8e14bae0c2d20ab0f377", size = 38920, upload-time = "2026-09-21T22:54:14.99Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bc/19/ca0addca3fc9fdf9a9e6ac11cd8e1e831b1ea1daccda875f1350ee3d0f1d/ci_devkit-0.1.10.tar.gz", hash = "sha256:733afdf59fd94d16e9d47291c85a34e827867560e624dc41daf77848e85c1b6d", size = 40879, upload-time = "2026-09-24T02:05:32.107Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c3/b3/ee5474174a4d8e9626eb0cbac234ea99908ed3988cc8b807fc8f4a2680a6/ci_devkit-0.1.0-py3-none-any.whl", hash = "sha256:3df3faf0821ffc1c32403f0af5b6b1ceb312d4912cae5b58aaf97b20c251874d", size = 26289, upload-time = "2026-09-21T22:54:13.759Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/44/33904ce3984eab322b000687f072adf26aa213e809d3952df913c8f8d1df/ci_devkit-0.1.10-py3-none-any.whl", hash = "sha256:f0194348742cf7d13cec75204784bdcccbdf08f51f458706c04840f0e8739709", size = 26245, upload-time = "2026-09-24T02:05:30.928Z" },
 ]
 
 [[package]]

unity_devkit-0.1.13/src/unity_devkit/projects.py

@@ -1,68 +0,0 @@
-import json
-import os
-from collections.abc import Iterator
-from pathlib import Path
-
-from pydantic import BaseModel
-
-MANIFEST_FILENAME = "unity-build.json"
-PROJECT_MARKER = Path("ProjectSettings") / "ProjectVersion.txt"
-PRUNE_DIRECTORIES = {".git", "Library", "Temp", "obj", "Build", "node_modules", "__pycache__"}
-
-
-class UnityBuildManifest(BaseModel, extra="forbid"):
-    builds: list[str] | None = None
-    execute_methods: dict[str, str] | None = None
-    package: str | None = None
-    grant_permissions: list[str] = []
-    tag_prefix: str | None = None
-
-
-class UnityProject(UnityBuildManifest):
-    path: Path
-
-
-def load_unity_projects() -> dict[str, UnityProject]:
-    root = Path.cwd()
-    project_directories = {directory.resolve() for directory in unity_project_directories(root)}
-    manifest_directories = {directory.resolve() for directory in directories_containing(root, MANIFEST_FILENAME)}
-
-    projects: dict[str, UnityProject] = {}
-    for project_path in sorted(project_directories | manifest_directories):
-        if project_path not in project_directories:
-            raise SystemExit(
-                f"{project_path / MANIFEST_FILENAME} is not inside a Unity project: missing {PROJECT_MARKER}"
-            )
-
-        manifest_path = project_path / MANIFEST_FILENAME
-        if manifest_path.exists():
-            manifest = UnityBuildManifest(**json.loads(manifest_path.read_text()))
-        else:
-            manifest = UnityBuildManifest()
-
-        name = project_path.name
-        if name in projects:
-            raise SystemExit(f"Duplicate Unity project name '{name}': {projects[name].path} and {project_path}")
-        projects[name] = UnityProject(path=project_path, **manifest.model_dump())
-
-    if not projects:
-        raise SystemExit(
-            f"No Unity projects found under {root} — a project is a directory containing {PROJECT_MARKER}. Run from the repo root"
-        )
-    return projects
-
-
-def visible_directories(root: Path) -> Iterator[Path]:
-    for directory, subdirectories, _filenames in os.walk(root):
-        subdirectories[:] = sorted(
-            name for name in subdirectories if name not in PRUNE_DIRECTORIES and not name.startswith(".")
-        )
-        yield Path(directory)
-
-
-def unity_project_directories(root: Path) -> list[Path]:
-    return [directory for directory in visible_directories(root) if (directory / PROJECT_MARKER).is_file()]
-
-
-def directories_containing(root: Path, filename: str) -> list[Path]:
-    return [directory for directory in visible_directories(root) if (directory / filename).is_file()]

unity_devkit-0.1.13/tests/test_projects.py

@@ -1,74 +0,0 @@
-import json
-from pathlib import Path
-
-import pytest
-
-from unity_devkit.projects import load_unity_projects
-
-
-def create_unity_project(root: Path, name: str, manifest: dict[str, object] | None = None) -> Path:
-    project = root / name
-    (project / "ProjectSettings").mkdir(parents=True)
-    (project / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
-    if manifest is not None:
-        (project / "unity-build.json").write_text(json.dumps(manifest))
-    return project
-
-
-def test_structural_project_without_manifest(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    create_unity_project(tmp_path, "Alpha")
-    monkeypatch.chdir(tmp_path)
-
-    projects = load_unity_projects()
-
-    assert set(projects) == {"Alpha"}
-    assert projects["Alpha"].path == tmp_path.resolve() / "Alpha"
-    assert projects["Alpha"].builds is None
-
-
-def test_manifest_overlays_structural_project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    create_unity_project(tmp_path, "Alpha", {"builds": ["linux64"], "tag_prefix": "alpha"})
-    monkeypatch.chdir(tmp_path)
-
-    projects = load_unity_projects()
-
-    assert projects["Alpha"].builds == ["linux64"]
-    assert projects["Alpha"].tag_prefix == "alpha"
-
-
-def test_stray_manifest_outside_unity_project_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    stray = tmp_path / "Beta"
-    stray.mkdir()
-    (stray / "unity-build.json").write_text("{}")
-    monkeypatch.chdir(tmp_path)
-
-    with pytest.raises(SystemExit, match="not inside a Unity project"):
-        load_unity_projects()
-
-
-def test_no_projects_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.chdir(tmp_path)
-
-    with pytest.raises(SystemExit, match="No Unity projects found"):
-        load_unity_projects()
-
-
-def test_duplicate_project_names_fail(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    create_unity_project(tmp_path / "site-a", "Alpha")
-    create_unity_project(tmp_path / "site-b", "Alpha")
-    monkeypatch.chdir(tmp_path)
-
-    with pytest.raises(SystemExit, match="Duplicate Unity project name"):
-        load_unity_projects()
-
-
-def test_pruned_directories_are_skipped(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
-    vendored = tmp_path / "vendor" / "Library" / "SomeProject"
-    (vendored / "ProjectSettings").mkdir(parents=True)
-    (vendored / "ProjectSettings" / "ProjectVersion.txt").write_text("m_EditorVersion: 6000.0.66f1\n")
-    create_unity_project(tmp_path, "Real")
-    monkeypatch.chdir(tmp_path)
-
-    projects = load_unity_projects()
-
-    assert set(projects) == {"Real"}