unity-devkit 0.1.0__tar.gz

unity_devkit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run basedpyright

unity_devkit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+
+jobs:
+  publish:
+    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' && github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+
+      # Workaround: fetch-tags is broken with shallow clones
+      - run: git fetch --tags origin
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Publish
+        run: uvx --from release-kit==0.1.0 publish-packages --config publish-config.json

unity_devkit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+.ruff_cache/
+.pytest_cache/
+bookmark.md

unity_devkit-0.1.0/AGENTS.md

@@ -0,0 +1,53 @@
+# unity-devkit
+
+## 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 a reusable `unity-build.yml` GitHub Actions workflow (housed in consumer repos today) that invokes only this package's entry points.
+
+The repo and package renamed from `unity-devkit` to `unity-devkit` (2026-09-21, member of the `-devkit` family; before that `placeframe-unity` → `unity-devkit` on extraction). The PyPI identity is fresh: `unity-devkit` starts its own tag ledger at `0.1.0`; the terminal `unity-devkit` 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-kit, invoked uvx-isolated, never a project dependency (unity-devkit sits inside its own dependency graph; a project-level release-kit 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 (first release `0.1.0`, patch-auto thereafter). API-breaking changes ship with a manually bumped version — patch-auto assumes additive changes.
+
+## Shape
+
+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>`, matching a discovered `unity-build.json` manifest. 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`). |
+| `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). |
+| `unity-license-tag` | `license_restore.py` | Print the license cache tag (CI pins it via `LICENSE_CACHE_TAG`). |
+| `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), `git_tags.py` (generic git-tag helpers), `cache.py` (ORAS restore/save), `ci_step.py` (GitHub Actions `::group::` step wrapper), `setup.py` / `setup_oras.py` (CI runner provisioning), `third-party/dotnet-install.sh` (vendored — see its sibling README for provenance).
+
+## Constraints
+
+**Every Unity invocation goes through `unity.run_unity_batchmode`, which does not trust the editor's exit code.** Unity exits 0 while reporting fatal package-manager errors (unresolvable dependencies, invalid package.json versions) only in the editor log — a resolver failure therefore surfaces as a stale `packages-lock.json` and nothing else. The runner streams the log live through `tee` into a captured file and afterwards scans it for `QUIET_FAILURE_SIGNATURES`; a match fails the invocation with the matched log block regardless of exit code. New Unity verbs must call the runner rather than invoking the editor directly, and newly discovered silent-failure log lines get added to the signature tuple. Exit-code strictness is per-verb: build/test verbs fail on non-zero (`strict_exit=True`, the default), while `lock-unity` passes `strict_exit=False` — it judges resolution, not compilation, so a project whose scripts fail to compile (resolution already done, lock written) produces a warning, not a failure. `-runTests` invocations pass `auto_quit=False` (the test runner owns exit timing).
+
+**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 manifest-driven, not catalog-driven.** The Unity commands discover projects by scanning the working-directory tree for `unity-build.json` manifest files (pruning `Library`, `Temp`, `obj`, `Build`, `node_modules`, `.git`, and dot-directories). A manifest marks its directory as an opted-in Unity project; the project name is the directory name; the manifest carries only intent the project cannot otherwise express (`builds`, `execute_methods`, `package`, `grant_permissions`, `tag_prefix` — schema in `projects.py`). 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, and the commands run unchanged in any repo containing manifests. Discovery anchors at the current working directory — run commands from the repo root.
+
+**`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 consumer-side `unity-build.yml` stays free of repo-specific values.
+
+**Entry-point names are the workflow contract.** Consumer `unity-build.yml` workflows invoke `unity-matrix`, `unity-license-tag`, `activate-unity-license`, and `build-unity` by name via `uv run`. Consumers pin the workflow by ref and this package by git revision 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 git-referencing consumers — prepo's `sync` verb — the same way pubpkg imports `ci_step`/`setup`. Their signatures and miss behavior are contract, not internals. The `SystemExit`-raising wrappers (`find_unity_editor`, `read_editor_version`) exist for unity-devkit's own CLI paths and delegate to the core helpers.
+
+**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.
+
+**`dotnet-install.sh` is vendored, not downloaded.** Downloading it via curl inside CI containers is unreliable (timeouts) — the same reason `actions/setup-dotnet` bundles it. It ships as package data inside `src/unity_devkit/third-party/` and is resolved `__file__`-relative, which works in editable installs, wheels, and git checkouts alike.
+
+**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.
+
+## See also
+
+- [`bashrun`](https://github.com/outernet-foundation/bashrun) — the shell-exec helpers this package uses everywhere (`bash`, `bash_output`, `bash_check`, `bash_handoff`).
+- `README.md` — human-facing setup, command catalog, and consumer install snippet.

unity_devkit-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

unity_devkit-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

unity_devkit-0.1.0/NOTICE

@@ -0,0 +1 @@
+Copyright 2026 Tyler Hatch

unity_devkit-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: unity-devkit
+Version: 0.1.0
+Summary: Unity project discovery, build, license, and CI tooling
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.13
+Requires-Dist: bashrun>=0.1.0
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: typer>=0.17.4

unity_devkit-0.1.0/README.md

@@ -0,0 +1,47 @@
+# unity-devkit
+
+Unity project discovery, local builds, CI builds, license activation, and the shared CI helpers those need. Consumers scan the working-directory tree for `unity-build.json` manifests to enumerate their Unity projects; the commands here (`compile-unity`, `install`, `build-unity`, `unity-matrix`, license helpers) work unchanged in any repo containing manifests. Paired with the reusable [`unity-build.yml`](https://github.com/outernet-foundation/unity-devkit/blob/main/.github/workflows/unity-build.yml) GitHub Actions workflow (once the workflow lands here — until then, workflow YAML lives in consumer repos).
+
+## Setup
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+```
+
+## Commands
+
+Run from a repo root containing one or more `unity-build.json` manifests.
+
+| `uv run <name>` | What it does |
+|---|---|
+| `compile-unity --project <name> --build <target>` | Local Unity build (APK or platform binary) suitable for `adb install`. |
+| `install --project <name>` | Download the latest CI artifact and `adb install` (or launch, for `linux64`); with `--build`, compile locally first. |
+| `lock-unity` | Lock Unity package versions. |
+| `test-unity --project <name>` | Run editmode / playmode tests. |
+| `activate-unity-license` | Activate the Unity Editor license (locally or with `--oras-push`). |
+| `unity-license-tag` | Print the license cache tag. |
+| `unity-matrix` | Emit the CI build matrix (CI-only; two `key=value` lines for `$GITHUB_OUTPUT`). |
+| `build-unity` | CI build with library-cache restore/save and version stamping (CI-only). |
+
+Every command accepts `--help`.
+
+## Consuming from another repo
+
+Install from PyPI:
+
+```toml
+[project]
+dependencies = ["unity-devkit>=0.1.0"]
+```
+
+Then `uv run compile-unity`, `uv run install`, etc. work from that repo against its own `unity-build.json` projects. 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
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+```

unity_devkit-0.1.0/publish-config.json

@@ -0,0 +1,11 @@
+{
+  "packages": [
+    {
+      "name": "unity-devkit",
+      "path": ".",
+      "feeds": { "pypi": "unity-devkit" }
+    }
+  ],
+  "ci_workflow": "ci.yml",
+  "mirror_prefix": "ghcr.io/outernet-foundation/mirror"
+}

unity_devkit-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "unity-devkit"
+version = "0.1.0"
+description = "Unity project discovery, build, license, and CI tooling"
+requires-python = ">=3.13"
+dependencies = [
+    "bashrun>=0.1.0",
+    "typer>=0.17.4",
+    "pydantic>=2.11.7",
+    "pydantic-settings>=2.9.1",
+]
+
+[dependency-groups]
+dev = ["basedpyright>=1.39.10", "ruff>=0.14.11"]
+
+[project.scripts]
+activate-unity-license = "unity_devkit.license:activate_app"
+build-unity = "unity_devkit.build_unity:app"
+compile-unity = "unity_devkit.compile_unity:app"
+install = "unity_devkit.install:app"
+lock-unity = "unity_devkit.lock_unity:app"
+test-unity = "unity_devkit.test_unity:app"
+unity-license-tag = "unity_devkit.license_restore:tag_app"
+unity-matrix = "unity_devkit.matrix:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/unity_devkit"]
+include = ["src/unity_devkit/py.typed", "src/unity_devkit/third-party/**"]
+
+[tool.uv.sources]
+
+[tool.basedpyright]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "strict"
+include = ["src"]

unity_devkit-0.1.0/ruff.toml

@@ -0,0 +1,95 @@
+target-version = "py313"
+line-length = 120
+preview = true
+
+[lint]
+select = ["ALL"]
+ignore = [
+    # ── Permanent ─────────────────────────────────────────────────────────
+    # Type annotations — basedpyright strict mode handles this
+    "ANN",
+    # No docstrings, no copyright headers
+    "D",
+    "DOC",
+    "CPY",
+    # TODO/FIXME comment formatting
+    "TD",
+    "FIX",
+    # Exception message ergonomics — literal-indirection and custom-class churn without benefit
+    "EM101",
+    "EM102",
+    "TRY003",
+    # Class attribute names never conflict with builtins via self.x
+    "A003",
+    # Function-size counters — C901 already covers structural complexity
+    "PLR0911",
+    "PLR0912",
+    "PLR0913",
+    "PLR0914",
+    "PLR0915",
+    "PLR0917",
+    # Typer's Option/Argument in argument defaults is typer's standard API pattern
+    "B008",
+    # Boolean parameters read fine as keyword-only flags here
+    "FBT001",
+    "FBT002",
+    "FBT003",
+    # Relative imports are the intra-package convention
+    "TID252",
+    # Formatter-owned; enforced by `ruff format`
+    "COM812",
+    "I001",
+    # Magic values in comparisons are readable in this CLI
+    "PLR2004",
+    # The formatter owns wrapping; long string literals and URLs stay on one line
+    "E501",
+    # src-layout tests need no __init__.py
+    "INP001",
+    # Runtime-used typing imports stay at module level
+    "TC001",
+    "TC002",
+    "TC003",
+    # Small literal tuples read fine in membership tests
+    "PLR6201",
+
+    # ── Deferred to PLE-248 — Enforce the deferred ruff rules
+    # https://linear.app/plerionplatforms/issue/PLE-248
+    # Mirrors placeframe's root ruff.toml transitional Ticket-N blocks; lifting
+    # a rule here should happen alongside lifting it from placeframe's ruff.toml.
+    "TC006",    # move import into TYPE_CHECKING block (quoted annotation) — Ticket 1
+    "UP015",    # unnecessary open mode parameters — Ticket 1
+    "FURB101",  # read-text can replace open+read — Ticket 2
+    "FURB103",  # write-text can replace open+write — Ticket 2
+    "FURB113",  # use list.extend instead of repeated append — Ticket 2
+    "PLW1514",  # open/read_text without explicit encoding — Ticket 2
+    "PTH101",   # os.chmod → Path.chmod — Ticket 2
+    "PTH112",   # os.path.isdir → Path.is_dir — Ticket 2
+    "PTH118",   # os.path.join → Path / — Ticket 2
+    "PTH123",   # open() → Path.open() — Ticket 2
+    "RET504",   # unnecessary assignment before return — Ticket 2
+    "RET505",   # unnecessary else after return — Ticket 2
+    "RUF005",   # consider spread operator instead of concatenation — Ticket 2
+    "SIM102",   # collapsible if statements — Ticket 2
+    "SIM115",   # use context manager for opening files — Ticket 2
+    "SIM117",   # use single with statement for multiple context managers — Ticket 2
+    "B904",     # raise ... from inside except — Ticket 8
+    "BLE001",   # blind except Exception — Ticket 8
+    "TRY300",   # try/except/return — move return into else — Ticket 8
+    "C901",     # function too complex — Ticket 9
+    "PLC0415",  # import not at top level — Ticket 9
+    "PLW0603",  # global statement — Ticket 9
+    "PLW2901",  # loop variable overwritten — Ticket 9
+    "PTH201",   # do not pass "." explicitly to Path — Ticket 2
+    "S103",     # bad-file-permissions (0o755 on executable) — Ticket 9
+    "S108",     # hardcoded temp file / directory — Ticket 9
+    "S404",     # suspicious subprocess import — Ticket 9
+    "S603",     # subprocess call with non-literal — Ticket 9
+    "S607",     # start-process-with-partial-path — Ticket 9
+
+    # ── Deferred to PLE-336 — Replace print() with structured logging
+    # https://linear.app/plerionplatforms/issue/PLE-336
+    "T201",     # print found
+]
+
+[lint.flake8-builtins]
+ignorelist = ["id", "map"]

unity_devkit-0.1.0/src/unity_devkit/build_unity.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+
+import typer
+from pydantic_settings import BaseSettings
+
+from .cache import restore, save
+from .ci_step import ci_step
+from .license_restore import restore_license
+from .setup import configure_git, install_dotnet
+from .setup_oras import install_oras
+from .unity import prepare_unity_project, resolve_unity_build, run_unity_batchmode
+from .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)
+
+
+@app.command()
+def main(
+    project: str = typer.Option(help="Project name"),
+    project_path: Path = typer.Option(help="Path to Unity project"),
+    platform: str = typer.Option(help="Target platform"),
+    cache_key: str = typer.Option(help="Cache key prefix"),
+    run_number: int = typer.Option(0, help="CI run number"),
+    branch: str = typer.Option("dev", help="Git branch name"),
+    registry: str = typer.Option(help="OCI registry path"),
+    build_env: str = typer.Option(
+        "", help="Newline-separated KEY=VALUE pairs injected into the Unity build process environment"
+    ),
+) -> None:
+    for line in build_env.splitlines():
+        entry = line.strip()
+        if not entry:
+            continue
+        key, separator, value = entry.partition("=")
+        if not separator:
+            raise SystemExit(f"Invalid --build-env entry (expected KEY=VALUE): {entry!r}")
+        os.environ[key.strip()] = value.strip()
+
+    with ci_step("Setup"):
+        configure_git(settings.github_workspace)
+        install_dotnet("8.0")
+        install_oras()
+        restore_license()
+
+    branch_slug = branch.replace("/", "-")
+    tag = f"{cache_key}-{platform}-{branch_slug}"
+    fallback_branch = "dev"
+    fallback_tags = [f"{cache_key}-{platform}-{fallback_branch}"] if branch_slug != fallback_branch else None
+
+    with ci_step("Restore library cache"):
+        restore(registry, "unity-library", tag, Path("."), fallback_tags=fallback_tags)
+
+    with ci_step("Prepare build"):
+        project_config, build_flag, execute_method = resolve_unity_build(project, platform)
+        unity_project_path = project_config.path
+
+    with ci_step("Prepare project"):
+        prepare_unity_project(unity_project_path)
+
+    with ci_step(f"Build {unity_project_path.name} [{platform}]"):
+        tag_prefix = project_config.tag_prefix
+        if tag_prefix:
+            version = get_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}))
+            print(f"Wrote version {full_version} (bundleVersionCode={run_number}) to {version_file}")
+
+        run_unity_batchmode(unity_project_path, f"{build_flag} -executeMethod {execute_method}", nographics=False)
+
+    with ci_step("Save library cache"):
+        # PackageCache (~1.6 GiB) is redundant with the shared UPM cache at ~/.cache/Unity/upm/
+        package_cache = project_path / "Library" / "PackageCache"
+        if package_cache.exists():
+            shutil.rmtree(package_cache)
+
+        save(registry, "unity-library", tag, Path("."), [f"{project_path}/Library/"])
+
+    with ci_step("Collect build artifacts"):
+        build_directory = project_path / "Build"
+        if build_directory.is_dir():
+            artifact_directory = Path("/tmp/unity-builds")
+            artifact_directory.mkdir(parents=True, exist_ok=True)
+            if platform == "linux64":
+                shutil.copytree(build_directory, artifact_directory, dirs_exist_ok=True)
+            else:
+                for file in build_directory.rglob("*"):
+                    if file.suffix in {".apk", ".exe"}:
+                        shutil.copy2(file, artifact_directory / file.name)