morphe-builder 0.1.0__tar.gz

morphe_builder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikel Villota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

morphe_builder-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: morphe-builder
+Version: 0.1.0
+Summary: Build verified Morphe-patched Android APKs and modules
+Author: Mikel Villota
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/Villoh/morphe-builder#readme
+Project-URL: Issues, https://github.com/Villoh/morphe-builder/issues
+Project-URL: Repository, https://github.com/Villoh/morphe-builder
+Keywords: android,apk,morphe,patcher,revanced
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: apkutils2==1.0.0
+Requires-Dist: gplaydl==0.0.0
+Dynamic: license-file
+
+<!-- markdownlint-disable MD013 -->
+
+<div align="center">
+
+# Morphe Builder
+
+**Verified Morphe-patched Android builds from stock Google Play splits, configured in one TOML file.**
+
+[![Daily verified update](https://img.shields.io/github/actions/workflow/status/Villoh/morphe-builder/daily-update.yml?branch=main&style=for-the-badge&label=Daily%20update&labelColor=000000&logo=githubactions&logoColor=white)](https://github.com/Villoh/morphe-builder/actions/workflows/daily-update.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-FFFFFF?style=for-the-badge&labelColor=000000&logo=python&logoColor=white)](https://www.python.org/)
+[![Java](https://img.shields.io/badge/java-21%2B-FFFFFF?style=for-the-badge&labelColor=000000&logo=openjdk&logoColor=white)](https://openjdk.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge&label=managed%20with&labelColor=000000&color=261230)](https://docs.astral.sh/uv/)
+
+</div>
+
+---
+
+Morphe Builder downloads stock APK splits from Google Play, verifies their integrity and signing certificate, merges them, patches them with the [Morphe](https://github.com/MorpheApp/morphe-desktop) CLI, signs the result, and packages non-root APKs plus deterministic Magisk/KernelSU modules.
+
+Every app, architecture, patch source, and tool version is declared in a single TOML file, so a fork can build its own release matrix in CI without touching Python code. Nothing untrusted is published: downloads stay in a temporary directory until manifest coverage, hashes, package identity, version, ABI, and signer all pass, and each published set carries deterministic provenance.
+
+Google Play delivery uses [`gplaydl`](https://github.com/Villoh/gplaydl) (branch `integration`), with verified `direct`, `archive`, APKMirror, and Uptodown fallbacks.
+
+## Requirements
+
+| Requirement | Version | Notes |
+| --- | --- | --- |
+| [`Python`](https://www.python.org/) | 3.11–3.13 | 3.11 minimum for standard-library `tomllib` |
+| [`Java`](https://openjdk.org/) | 21+ | Required by Morphe CLI, APKEditor, and uber-apk-signer |
+| [`uv`](https://docs.astral.sh/uv/) | latest | Only for development installs from source |
+
+Windows and Linux are supported. See [`docs/security.md`](docs/security.md) for platform limits.
+
+## Features
+
+- **Verified downloads**: Google manifest coverage, safe paths, sizes, SHA-256 hashes, package identity, version, split requirements, ABI, and signing certificate are all checked before publication.
+- **Signer pinning**: YouTube and YouTube Music require known Google signers; any app can pin its own `expected-signer` SHA-256.
+- **Provider fallback**: fixed order `google-play → direct → archive → apkmirror → uptodown`; integrity failures stay terminal instead of falling through to a later provider.
+- **Config-driven matrix**: apps, architectures, densities, patch sets, and module output live in TOML; no hardcoded app registry.
+- **Per-app toolchains**: each app can override Morphe CLI version, patch source, and patch version, resolved and cached per `owner/repo@tag`.
+- **Pinned, hashed tooling**: Morphe CLI, patches, APKEditor, and uber-apk-signer are resolved to exact tags with recorded asset hashes in `toolchain-provenance.json`.
+- **Non-root APKs and modules**: deterministic Magisk/KernelSU modules that install matching stock, survive reboots, and receive updates from the Magisk app.
+- **Reproducible provenance**: `provenance.json`, `build-summary.json`, `release-manifest.json`, and `CHANGELOG.md` record every source, version, and hash.
+- **Atomic publication**: existing output is never overwritten; a failed job removes its temporary set and publishes nothing.
+- **Verified CI releases**: daily update checks resolve upstream versions, skip unchanged builds, verify every artifact, and attach GitHub artifact attestations.
+- **Secret-safe by design**: no committed credentials, no cached tokens or APK payloads, redacted error output.
+
+## Installation
+
+Morphe Builder pins a reviewed `gplaydl` fork commit. PyPI cannot encode VCS dependency sources, and the unrelated upstream `gplaydl` package is incompatible, so install both packages in one resolver transaction.
+
+Global tool install:
+
+```bash
+uv tool install \
+  --with "gplaydl @ git+https://github.com/Villoh/gplaydl.git@de7dfba240b09bc986523c1637ac672b0c295980" \
+  morphe-builder
+```
+
+Into an existing environment:
+
+```bash
+python -m pip install \
+  morphe-builder \
+  "gplaydl @ git+https://github.com/Villoh/gplaydl.git@de7dfba240b09bc986523c1637ac672b0c295980"
+```
+
+Do not install `morphe-builder` without the pinned override: its `gplaydl==0.0.0` package requirement deliberately fails closed instead of selecting the incompatible PyPI distribution.
+
+Development install from source:
+
+```bash
+git clone https://github.com/Villoh/morphe-builder
+cd morphe-builder
+uv sync
+uv run morphe-builder --help
+```
+
+## Quick start
+
+```bash
+morphe-builder auth --arch arm64
+morphe-builder tools
+MORPHE_KEYSTORE_PASSWORD=secret morphe-builder build morphe.toml \
+  --keystore /path/outside/repository/builder.p12 \
+  --output build
+```
+
+`auth` stores Google Play credentials outside the repository, `tools` fetches and hashes the pinned Java toolchain, and `build` produces the full configured matrix from [`morphe.toml`](morphe.toml).
+
+### Google Play access
+
+Set these two together to download directly from Google's servers through the [`gplaydl`](https://github.com/Villoh/gplaydl) fork. This is the recommended setup: it is the only reliable path from CI runners, and it avoids the shared anonymous dispenser entirely.
+
+| Variable | Value |
+| --- | --- |
+| `GPLAYDL_ACCOUNT_EMAIL` | Google account email used for Play authentication. |
+| `GPLAYDL_AAS_TOKEN` | Persistent AAS token for that account. Must start with `aas_et/`. |
+
+A value starting with `g.a` is a temporary bearer token, not an AAS token, and is rejected. Both variables are required together; a partial configuration fails instead of silently falling back. Treat the token as a password: use a dedicated account, keep it only in environment variables or GitHub Environment secrets, and never place it in TOML, argv, or committed files. Changing the account password invalidates it.
+
+<details>
+<summary><b>How to generate an AAS token with <code>gplaydl</code></b></summary>
+
+`gplaydl aastoken` prints a Google account AAS token. Credentials and tokens are used in memory only; no `credentials.txt` or `token.txt` file is created.
+
+**OAuth mode (recommended)**
+
+```bash
+gplaydl aastoken --oauth
+```
+
+Get the required one-time `oauth_token`:
+
+1. Open Google [EmbeddedSetup](https://accounts.google.com/EmbeddedSetup).
+2. Sign in and select **I agree**.
+3. The page may stay frozen or loading forever. This is expected; the cookie is normally already available.
+4. Open browser developer tools (<kbd>F12</kbd>).
+5. In Chrome or Edge, open **Application › Cookies › `https://accounts.google.com`**.
+6. Copy the value of the `oauth_token` cookie. It starts with `oauth2_4/`.
+7. Run `gplaydl aastoken --oauth`, enter the same email, then paste the token. Both inputs are handled interactively and the token is hidden.
+
+The `oauth_token` is short-lived and single-use. The resulting AAS token is printed to the console.
+
+**Password or app-password mode**
+
+```bash
+# Interactive: asks for email and hides password input
+gplaydl aastoken
+
+# Arguments: convenient, but password remains in shell history
+gplaydl aastoken user@example.com password
+```
+
+Google commonly rejects both account passwords and 16-character app passwords with `BadAuthentication`. Keep 2-Step Verification enabled and use OAuth mode instead.
+
+</details>
+
+Without these variables, `gplaydl` falls back to the public anonymous dispenser, which is frequently blocked from datacenter IP ranges. In that case the builder continues through the verified APKMirror and Uptodown fallbacks declared in your configuration.
+
+### Other environment variables
+
+| Variable | Used by | Purpose |
+| --- | --- | --- |
+| `MORPHE_KEYSTORE_PASSWORD` | `build` | Signing keystore password. Required; never accepted in argv. |
+| `MORPHE_DISPENSER_URL` | `auth`, `download` | Custom anonymous dispenser, used only when no Google account is configured. |
+| `MORPHE_MODULE_VERSION_CODE` | `build` | Monotonic module `versionCode`. CI passes the workflow run number. |
+| `GITHUB_TOKEN` | `tools`, `build`, `list-patches` | Authenticates GitHub API calls. Never sent to asset downloads. |
+| `HTTP_PROXY`, `HTTPS_PROXY` | `build` | Proxy for provider downloads. |
+| `XDG_CACHE_HOME`, `LOCALAPPDATA` | all cached commands | Override the default cache root. |
+
+## Configuration
+
+Everything a fork needs to change lives in [`morphe.toml`](morphe.toml). No Python code has to be touched to build a different set of apps.
+
+The file has one `[toolchain]` table with the default Morphe CLI and patch sources, then one ordered `[[apps]]` entry per app:
+
+```toml
+[toolchain]
+morphe-source = "MorpheApp/morphe-desktop"
+morphe-version = "latest"
+patches-source = "MorpheApp/morphe-patches"
+patches-version = "latest"
+
+[[apps]]
+package = "com.google.android.youtube"
+name = "YouTube"
+slug = "youtube"
+patched-package = "app.morphe.android.youtube"
+version = "auto"
+build-mode = "apk"
+arch = "arm64-v8a"
+density = "xxhdpi"
+include-patches = ["GmsCore support", "SponsorBlock"]
+exclude-patches = []
+
+[apps.patch-options."SponsorBlock"]
+toast-on-connection-error = true
+
+[apps.google-play]
+profile = "D2"
+country = "US"
+
+[apps.fallbacks]
+apkmirror = ["https://www.apkmirror.com/apk/google-inc/youtube/"]
+```
+
+Only `package` and `name` are required. Everything else has a documented default:
+
+| Setting | Required | Default when omitted |
+| --- | :---: | --- |
+| `package` | yes | Validated Android package name. |
+| `name` | yes | Display name used in release notes and modules. |
+| `slug` | no | `package` with dots replaced by hyphens. Controls output, cache, and module names; must be unique. |
+| `patched-package` | no | No package change is expected after patching. Set it when patches rename the package. |
+| `version` | no | `auto`: highest version supported by every selected patch. Also accepts `latest` or an exact version name. |
+| `version-code` | no | Resolved from the version name. Requires an explicit `version`; `auto` and `latest` are rejected with it. |
+| `build-mode` | no | `apk`: non-root APK only. Use `module` or `both` for Magisk/KernelSU modules. |
+| `arch` | no | `arm64-v8a`. Also `arm-v7a`, `all`, or `both` (two independent jobs). |
+| `density` | no | The profile's only available density split is selected automatically. |
+| `include-patches` | no | Empty: the patch bundle's default selection is used. |
+| `exclude-patches` | no | Empty: nothing is removed from the selection. |
+| `exclusive-patches` | no | Unset. When set, only these patches apply; cannot be combined with include/exclude. |
+| `patch-options` | no | Patch defaults. Scalar values only, never shell-interpolated. Every option must belong to a selected patch. |
+| `expected-signer` | no | Unpinned: a valid provider-served signer is accepted and logged as `unpinned signer accepted`. YouTube and YouTube Music always enforce built-in Google signer pins. |
+| `google-play.profile` | no | `gplaydl` picks a profile. Leave unset with `arch = "both"`, since one profile cannot cover both ABIs. |
+| `google-play.country` | no | `gplaydl` account region. |
+| `google-play.proxy` | no | Direct connection. |
+| `google-play.dispenser` | no | `MORPHE_DISPENSER_URL`, or the built-in public dispenser. |
+| `fallbacks.*` | no | Empty: Google Play is the only source, so a Play failure fails the job. |
+| `patches-source`, `patches-version`, `cli-source`, `morphe-version` | no | The `[toolchain]` values. |
+
+The `[toolchain]` table itself is optional; omitting it uses `MorpheApp/morphe-desktop` and `MorpheApp/morphe-patches` at `latest`.
+
+Parsing is strict: unknown keys, duplicate packages, duplicate slugs, unsupported values, and conflicting patch selections are all rejected before any download starts. Run `morphe-builder list-patches morphe.toml` to see which version each app will resolve to before committing a change.
+
+For CI-built releases, declare at least one `fallbacks` entry per app. Anonymous Google Play access is unreliable from hosted runners, and a verified APKMirror or Uptodown source keeps the build working without credentials.
+
+Full field reference, version-resolution order, and fallback URL rules: [`docs/configuration.md`](docs/configuration.md).
+
+## Usage
+
+| Command | Purpose |
+| --- | --- |
+| `auth` | Authenticate against Google Play and cache the session outside the repository. |
+| `download` | Download and verify one package's splits into an output directory. |
+| `tools` | Resolve, download, and hash the pinned Java toolchain. |
+| `list-patches` | Show patch-compatible versions for the configured apps. |
+| `build` | Run the full configured matrix: download, merge, patch, sign, verify, package. |
+| `verify` | Re-verify an existing split set against a package, architecture, and version. |
+| `clean` | Remove the disposable work cache only; trusted sets and tools are preserved. |
+
+```bash
+morphe-builder download com.example.app --arch arm64 --output downloads
+morphe-builder list-patches morphe.toml
+morphe-builder verify trusted/splits com.google.android.youtube \
+  --arch arm64 --version-name 21.04.223
+```
+
+All commands accept `--json` (progress on stderr, machine-readable result on stdout). `--arch both` runs independent ARM64 and ARMv7 jobs. Keystore passwords come from `MORPHE_KEYSTORE_PASSWORD`, never argv. Exit codes are stable per failure category.
+
+Full reference, exit-code table, and cache semantics: [`docs/cli.md`](docs/cli.md).
+
+## Documentation
+
+| Topic | Document |
+| --- | --- |
+| CLI reference and exit codes | [`docs/cli.md`](docs/cli.md) |
+| TOML configuration and version resolution | [`docs/configuration.md`](docs/configuration.md) |
+| Toolchain cache, pins, and checksums | [`docs/toolchain.md`](docs/toolchain.md) |
+| Google Play delivery and integrity checks | [`docs/google-play-integrity.md`](docs/google-play-integrity.md) |
+| Provider fallback order | [`docs/providers.md`](docs/providers.md) |
+| Split selection and merge policy | [`docs/merge.md`](docs/merge.md) |
+| Signed APK build flow | [`docs/build.md`](docs/build.md) |
+| Magisk/KernelSU module format | [`docs/modules.md`](docs/modules.md) |
+| Threat model and platform limits | [`docs/security.md`](docs/security.md) |
+| CI, release verification, and publication | [`docs/releases.md`](docs/releases.md) |
+| Third-party licenses | [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) |
+| Repository rules for contributors and agents | [`docs/rules/README.md`](docs/rules/README.md) |
+| Active roadmap | [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md) |
+| Completed milestones and evidence | [`docs/roadmap/COMPLETED.md`](docs/roadmap/COMPLETED.md) |
+
+## License
+
+Morphe Builder is released under the [MIT License](LICENSE). Downloaded Morphe tooling remains separately licensed under GPL-3.0 and is not bundled in the Python distribution. See [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md).
+
+## Credits
+
+- [`MorpheApp/morphe-desktop`](https://github.com/MorpheApp/morphe-desktop) and [`MorpheApp/morphe-patches`](https://github.com/MorpheApp/morphe-patches): the patching CLI and patch bundles this builder orchestrates. Morphe does the patching; this project only prepares verified stock input and packages the output.
+- [`j-hc/revanced-magisk-module`](https://github.com/j-hc/revanced-magisk-module): prior art for the Magisk/KernelSU module approach and CI build matrix. Reviewed as design context under GPL-3.0; no code is copied. See [`docs/modules.md`](docs/modules.md).
+- [`REAndroid/APKEditor`](https://github.com/REAndroid/APKEditor) and [`patrickfav/uber-apk-signer`](https://github.com/patrickfav/uber-apk-signer): split merge and APK signing tools.
+- [ReVanced](https://revanced.app/): the patch ecosystem Morphe builds on; ReVanced-compatible patch bundles can be selected per app via `patches-source`.

morphe_builder-0.1.0/README.md

@@ -0,0 +1,272 @@
+<!-- markdownlint-disable MD013 -->
+
+<div align="center">
+
+# Morphe Builder
+
+**Verified Morphe-patched Android builds from stock Google Play splits, configured in one TOML file.**
+
+[![Daily verified update](https://img.shields.io/github/actions/workflow/status/Villoh/morphe-builder/daily-update.yml?branch=main&style=for-the-badge&label=Daily%20update&labelColor=000000&logo=githubactions&logoColor=white)](https://github.com/Villoh/morphe-builder/actions/workflows/daily-update.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-FFFFFF?style=for-the-badge&labelColor=000000&logo=python&logoColor=white)](https://www.python.org/)
+[![Java](https://img.shields.io/badge/java-21%2B-FFFFFF?style=for-the-badge&labelColor=000000&logo=openjdk&logoColor=white)](https://openjdk.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge&label=managed%20with&labelColor=000000&color=261230)](https://docs.astral.sh/uv/)
+
+</div>
+
+---
+
+Morphe Builder downloads stock APK splits from Google Play, verifies their integrity and signing certificate, merges them, patches them with the [Morphe](https://github.com/MorpheApp/morphe-desktop) CLI, signs the result, and packages non-root APKs plus deterministic Magisk/KernelSU modules.
+
+Every app, architecture, patch source, and tool version is declared in a single TOML file, so a fork can build its own release matrix in CI without touching Python code. Nothing untrusted is published: downloads stay in a temporary directory until manifest coverage, hashes, package identity, version, ABI, and signer all pass, and each published set carries deterministic provenance.
+
+Google Play delivery uses [`gplaydl`](https://github.com/Villoh/gplaydl) (branch `integration`), with verified `direct`, `archive`, APKMirror, and Uptodown fallbacks.
+
+## Requirements
+
+| Requirement | Version | Notes |
+| --- | --- | --- |
+| [`Python`](https://www.python.org/) | 3.11–3.13 | 3.11 minimum for standard-library `tomllib` |
+| [`Java`](https://openjdk.org/) | 21+ | Required by Morphe CLI, APKEditor, and uber-apk-signer |
+| [`uv`](https://docs.astral.sh/uv/) | latest | Only for development installs from source |
+
+Windows and Linux are supported. See [`docs/security.md`](docs/security.md) for platform limits.
+
+## Features
+
+- **Verified downloads**: Google manifest coverage, safe paths, sizes, SHA-256 hashes, package identity, version, split requirements, ABI, and signing certificate are all checked before publication.
+- **Signer pinning**: YouTube and YouTube Music require known Google signers; any app can pin its own `expected-signer` SHA-256.
+- **Provider fallback**: fixed order `google-play → direct → archive → apkmirror → uptodown`; integrity failures stay terminal instead of falling through to a later provider.
+- **Config-driven matrix**: apps, architectures, densities, patch sets, and module output live in TOML; no hardcoded app registry.
+- **Per-app toolchains**: each app can override Morphe CLI version, patch source, and patch version, resolved and cached per `owner/repo@tag`.
+- **Pinned, hashed tooling**: Morphe CLI, patches, APKEditor, and uber-apk-signer are resolved to exact tags with recorded asset hashes in `toolchain-provenance.json`.
+- **Non-root APKs and modules**: deterministic Magisk/KernelSU modules that install matching stock, survive reboots, and receive updates from the Magisk app.
+- **Reproducible provenance**: `provenance.json`, `build-summary.json`, `release-manifest.json`, and `CHANGELOG.md` record every source, version, and hash.
+- **Atomic publication**: existing output is never overwritten; a failed job removes its temporary set and publishes nothing.
+- **Verified CI releases**: daily update checks resolve upstream versions, skip unchanged builds, verify every artifact, and attach GitHub artifact attestations.
+- **Secret-safe by design**: no committed credentials, no cached tokens or APK payloads, redacted error output.
+
+## Installation
+
+Morphe Builder pins a reviewed `gplaydl` fork commit. PyPI cannot encode VCS dependency sources, and the unrelated upstream `gplaydl` package is incompatible, so install both packages in one resolver transaction.
+
+Global tool install:
+
+```bash
+uv tool install \
+  --with "gplaydl @ git+https://github.com/Villoh/gplaydl.git@de7dfba240b09bc986523c1637ac672b0c295980" \
+  morphe-builder
+```
+
+Into an existing environment:
+
+```bash
+python -m pip install \
+  morphe-builder \
+  "gplaydl @ git+https://github.com/Villoh/gplaydl.git@de7dfba240b09bc986523c1637ac672b0c295980"
+```
+
+Do not install `morphe-builder` without the pinned override: its `gplaydl==0.0.0` package requirement deliberately fails closed instead of selecting the incompatible PyPI distribution.
+
+Development install from source:
+
+```bash
+git clone https://github.com/Villoh/morphe-builder
+cd morphe-builder
+uv sync
+uv run morphe-builder --help
+```
+
+## Quick start
+
+```bash
+morphe-builder auth --arch arm64
+morphe-builder tools
+MORPHE_KEYSTORE_PASSWORD=secret morphe-builder build morphe.toml \
+  --keystore /path/outside/repository/builder.p12 \
+  --output build
+```
+
+`auth` stores Google Play credentials outside the repository, `tools` fetches and hashes the pinned Java toolchain, and `build` produces the full configured matrix from [`morphe.toml`](morphe.toml).
+
+### Google Play access
+
+Set these two together to download directly from Google's servers through the [`gplaydl`](https://github.com/Villoh/gplaydl) fork. This is the recommended setup: it is the only reliable path from CI runners, and it avoids the shared anonymous dispenser entirely.
+
+| Variable | Value |
+| --- | --- |
+| `GPLAYDL_ACCOUNT_EMAIL` | Google account email used for Play authentication. |
+| `GPLAYDL_AAS_TOKEN` | Persistent AAS token for that account. Must start with `aas_et/`. |
+
+A value starting with `g.a` is a temporary bearer token, not an AAS token, and is rejected. Both variables are required together; a partial configuration fails instead of silently falling back. Treat the token as a password: use a dedicated account, keep it only in environment variables or GitHub Environment secrets, and never place it in TOML, argv, or committed files. Changing the account password invalidates it.
+
+<details>
+<summary><b>How to generate an AAS token with <code>gplaydl</code></b></summary>
+
+`gplaydl aastoken` prints a Google account AAS token. Credentials and tokens are used in memory only; no `credentials.txt` or `token.txt` file is created.
+
+**OAuth mode (recommended)**
+
+```bash
+gplaydl aastoken --oauth
+```
+
+Get the required one-time `oauth_token`:
+
+1. Open Google [EmbeddedSetup](https://accounts.google.com/EmbeddedSetup).
+2. Sign in and select **I agree**.
+3. The page may stay frozen or loading forever. This is expected; the cookie is normally already available.
+4. Open browser developer tools (<kbd>F12</kbd>).
+5. In Chrome or Edge, open **Application › Cookies › `https://accounts.google.com`**.
+6. Copy the value of the `oauth_token` cookie. It starts with `oauth2_4/`.
+7. Run `gplaydl aastoken --oauth`, enter the same email, then paste the token. Both inputs are handled interactively and the token is hidden.
+
+The `oauth_token` is short-lived and single-use. The resulting AAS token is printed to the console.
+
+**Password or app-password mode**
+
+```bash
+# Interactive: asks for email and hides password input
+gplaydl aastoken
+
+# Arguments: convenient, but password remains in shell history
+gplaydl aastoken user@example.com password
+```
+
+Google commonly rejects both account passwords and 16-character app passwords with `BadAuthentication`. Keep 2-Step Verification enabled and use OAuth mode instead.
+
+</details>
+
+Without these variables, `gplaydl` falls back to the public anonymous dispenser, which is frequently blocked from datacenter IP ranges. In that case the builder continues through the verified APKMirror and Uptodown fallbacks declared in your configuration.
+
+### Other environment variables
+
+| Variable | Used by | Purpose |
+| --- | --- | --- |
+| `MORPHE_KEYSTORE_PASSWORD` | `build` | Signing keystore password. Required; never accepted in argv. |
+| `MORPHE_DISPENSER_URL` | `auth`, `download` | Custom anonymous dispenser, used only when no Google account is configured. |
+| `MORPHE_MODULE_VERSION_CODE` | `build` | Monotonic module `versionCode`. CI passes the workflow run number. |
+| `GITHUB_TOKEN` | `tools`, `build`, `list-patches` | Authenticates GitHub API calls. Never sent to asset downloads. |
+| `HTTP_PROXY`, `HTTPS_PROXY` | `build` | Proxy for provider downloads. |
+| `XDG_CACHE_HOME`, `LOCALAPPDATA` | all cached commands | Override the default cache root. |
+
+## Configuration
+
+Everything a fork needs to change lives in [`morphe.toml`](morphe.toml). No Python code has to be touched to build a different set of apps.
+
+The file has one `[toolchain]` table with the default Morphe CLI and patch sources, then one ordered `[[apps]]` entry per app:
+
+```toml
+[toolchain]
+morphe-source = "MorpheApp/morphe-desktop"
+morphe-version = "latest"
+patches-source = "MorpheApp/morphe-patches"
+patches-version = "latest"
+
+[[apps]]
+package = "com.google.android.youtube"
+name = "YouTube"
+slug = "youtube"
+patched-package = "app.morphe.android.youtube"
+version = "auto"
+build-mode = "apk"
+arch = "arm64-v8a"
+density = "xxhdpi"
+include-patches = ["GmsCore support", "SponsorBlock"]
+exclude-patches = []
+
+[apps.patch-options."SponsorBlock"]
+toast-on-connection-error = true
+
+[apps.google-play]
+profile = "D2"
+country = "US"
+
+[apps.fallbacks]
+apkmirror = ["https://www.apkmirror.com/apk/google-inc/youtube/"]
+```
+
+Only `package` and `name` are required. Everything else has a documented default:
+
+| Setting | Required | Default when omitted |
+| --- | :---: | --- |
+| `package` | yes | Validated Android package name. |
+| `name` | yes | Display name used in release notes and modules. |
+| `slug` | no | `package` with dots replaced by hyphens. Controls output, cache, and module names; must be unique. |
+| `patched-package` | no | No package change is expected after patching. Set it when patches rename the package. |
+| `version` | no | `auto`: highest version supported by every selected patch. Also accepts `latest` or an exact version name. |
+| `version-code` | no | Resolved from the version name. Requires an explicit `version`; `auto` and `latest` are rejected with it. |
+| `build-mode` | no | `apk`: non-root APK only. Use `module` or `both` for Magisk/KernelSU modules. |
+| `arch` | no | `arm64-v8a`. Also `arm-v7a`, `all`, or `both` (two independent jobs). |
+| `density` | no | The profile's only available density split is selected automatically. |
+| `include-patches` | no | Empty: the patch bundle's default selection is used. |
+| `exclude-patches` | no | Empty: nothing is removed from the selection. |
+| `exclusive-patches` | no | Unset. When set, only these patches apply; cannot be combined with include/exclude. |
+| `patch-options` | no | Patch defaults. Scalar values only, never shell-interpolated. Every option must belong to a selected patch. |
+| `expected-signer` | no | Unpinned: a valid provider-served signer is accepted and logged as `unpinned signer accepted`. YouTube and YouTube Music always enforce built-in Google signer pins. |
+| `google-play.profile` | no | `gplaydl` picks a profile. Leave unset with `arch = "both"`, since one profile cannot cover both ABIs. |
+| `google-play.country` | no | `gplaydl` account region. |
+| `google-play.proxy` | no | Direct connection. |
+| `google-play.dispenser` | no | `MORPHE_DISPENSER_URL`, or the built-in public dispenser. |
+| `fallbacks.*` | no | Empty: Google Play is the only source, so a Play failure fails the job. |
+| `patches-source`, `patches-version`, `cli-source`, `morphe-version` | no | The `[toolchain]` values. |
+
+The `[toolchain]` table itself is optional; omitting it uses `MorpheApp/morphe-desktop` and `MorpheApp/morphe-patches` at `latest`.
+
+Parsing is strict: unknown keys, duplicate packages, duplicate slugs, unsupported values, and conflicting patch selections are all rejected before any download starts. Run `morphe-builder list-patches morphe.toml` to see which version each app will resolve to before committing a change.
+
+For CI-built releases, declare at least one `fallbacks` entry per app. Anonymous Google Play access is unreliable from hosted runners, and a verified APKMirror or Uptodown source keeps the build working without credentials.
+
+Full field reference, version-resolution order, and fallback URL rules: [`docs/configuration.md`](docs/configuration.md).
+
+## Usage
+
+| Command | Purpose |
+| --- | --- |
+| `auth` | Authenticate against Google Play and cache the session outside the repository. |
+| `download` | Download and verify one package's splits into an output directory. |
+| `tools` | Resolve, download, and hash the pinned Java toolchain. |
+| `list-patches` | Show patch-compatible versions for the configured apps. |
+| `build` | Run the full configured matrix: download, merge, patch, sign, verify, package. |
+| `verify` | Re-verify an existing split set against a package, architecture, and version. |
+| `clean` | Remove the disposable work cache only; trusted sets and tools are preserved. |
+
+```bash
+morphe-builder download com.example.app --arch arm64 --output downloads
+morphe-builder list-patches morphe.toml
+morphe-builder verify trusted/splits com.google.android.youtube \
+  --arch arm64 --version-name 21.04.223
+```
+
+All commands accept `--json` (progress on stderr, machine-readable result on stdout). `--arch both` runs independent ARM64 and ARMv7 jobs. Keystore passwords come from `MORPHE_KEYSTORE_PASSWORD`, never argv. Exit codes are stable per failure category.
+
+Full reference, exit-code table, and cache semantics: [`docs/cli.md`](docs/cli.md).
+
+## Documentation
+
+| Topic | Document |
+| --- | --- |
+| CLI reference and exit codes | [`docs/cli.md`](docs/cli.md) |
+| TOML configuration and version resolution | [`docs/configuration.md`](docs/configuration.md) |
+| Toolchain cache, pins, and checksums | [`docs/toolchain.md`](docs/toolchain.md) |
+| Google Play delivery and integrity checks | [`docs/google-play-integrity.md`](docs/google-play-integrity.md) |
+| Provider fallback order | [`docs/providers.md`](docs/providers.md) |
+| Split selection and merge policy | [`docs/merge.md`](docs/merge.md) |
+| Signed APK build flow | [`docs/build.md`](docs/build.md) |
+| Magisk/KernelSU module format | [`docs/modules.md`](docs/modules.md) |
+| Threat model and platform limits | [`docs/security.md`](docs/security.md) |
+| CI, release verification, and publication | [`docs/releases.md`](docs/releases.md) |
+| Third-party licenses | [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) |
+| Repository rules for contributors and agents | [`docs/rules/README.md`](docs/rules/README.md) |
+| Active roadmap | [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md) |
+| Completed milestones and evidence | [`docs/roadmap/COMPLETED.md`](docs/roadmap/COMPLETED.md) |
+
+## License
+
+Morphe Builder is released under the [MIT License](LICENSE). Downloaded Morphe tooling remains separately licensed under GPL-3.0 and is not bundled in the Python distribution. See [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md).
+
+## Credits
+
+- [`MorpheApp/morphe-desktop`](https://github.com/MorpheApp/morphe-desktop) and [`MorpheApp/morphe-patches`](https://github.com/MorpheApp/morphe-patches): the patching CLI and patch bundles this builder orchestrates. Morphe does the patching; this project only prepares verified stock input and packages the output.
+- [`j-hc/revanced-magisk-module`](https://github.com/j-hc/revanced-magisk-module): prior art for the Magisk/KernelSU module approach and CI build matrix. Reviewed as design context under GPL-3.0; no code is copied. See [`docs/modules.md`](docs/modules.md).
+- [`REAndroid/APKEditor`](https://github.com/REAndroid/APKEditor) and [`patrickfav/uber-apk-signer`](https://github.com/patrickfav/uber-apk-signer): split merge and APK signing tools.
+- [ReVanced](https://revanced.app/): the patch ecosystem Morphe builds on; ReVanced-compatible patch bundles can be selected per app via `patches-source`.

morphe_builder-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "morphe-builder"
+version = "0.1.0"
+description = "Build verified Morphe-patched Android APKs and modules"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mikel Villota" }]
+requires-python = ">=3.11,<3.14"
+keywords = ["android", "apk", "morphe", "patcher", "revanced"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Operating System :: Microsoft :: Windows",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+  "apkutils2==1.0.0",
+  # PyPI cannot encode reviewed VCS sources. Version 0.0.0 prevents pip from
+  # silently substituting the incompatible upstream gplaydl distribution.
+  "gplaydl==0.0.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/Villoh/morphe-builder#readme"
+Issues = "https://github.com/Villoh/morphe-builder/issues"
+Repository = "https://github.com/Villoh/morphe-builder"
+
+[project.scripts]
+morphe-builder = "morphe_builder:main"
+
+[tool.uv]
+# Quarantine new releases before dependency resolution admits them.
+exclude-newer = "3 days"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["morphe_builder"]
+
+[tool.uv.sources]
+gplaydl = { git = "https://github.com/Villoh/gplaydl.git", rev = "de7dfba240b09bc986523c1637ac672b0c295980" }

morphe_builder-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+