local-expo-build 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to `local-expo-build` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-06-28
+
+### Added
+
+- **Doctor as a setup wizard.** `doctor` now chains interactive auto-fixes for the
+  most common blockers: missing `expo.android.package`, missing EAS link
+  (`eas init`), missing `eas.json` (`eas build:configure`), and missing keystore
+  setup. Each step is gated on the previous outcome and the check rows are
+  mutated in place so the exit code reflects the post-fix state.
+- **Dynamic config (`app.config.{js,ts,cjs,mjs}`) support.** `doctor`'s
+  `Android package` and `EAS project linked` checks now read the resolved
+  Expo config via `npx expo config --json --type public`, falling back to
+  `app.json` for static projects. Per-process cache keeps the cost down.
+- **`keystore rehydrate --move` flag.** Deletes the source `.jks` after a
+  successful copy into `android/app/` (default is to leave the source as a
+  prebuild-survivable backup).
+- **Root `.jks` backup for `keystore create` / `keystore import`.** Both
+  providers now also place the `.jks` at project root (gitignored via `*.jks`).
+  Closes the data-loss hole where `expo prebuild --clean` would leave a
+  freshly-generated keystore with no recoverable source.
+- **Single-script orchestrator (`scripts/build.js`).** Replaces the long
+  `&&`-chained npm scripts with a single Node entry point. `package.json` now
+  carries `"build:android:apk": "node scripts/build.js apk"` instead of a
+  multi-step shell pipeline. Prints numbered progress and a total time.
+- **Build artifact path + size printed at the end of every build.** Runner
+  mode and scaffold mode both surface the absolute path so you always know
+  where the APK / AAB landed.
+- **Subtle contextual disclaimers** ("Local build · saves an EAS cloud build
+  credit · first run is slowest ~5 min") at the top of `build`, `init`, and
+  the build orchestrator. One dim line, not repeated mid-pipeline.
+- **`keystore import` auto-detects matching `credentials.json`.** When the
+  user points at a `.jks` and a `credentials.json` exists describing the
+  same file (matched by absolute path OR sha1 content hash), the password +
+  alias prompts are skipped and the values are reused. Falls back to the
+  full prompt flow when no match — so this is purely an opt-in shortcut.
+- **`--dry-run` honored by `build android`** (runner mode) and the scaffolded
+  `scripts/build.js` orchestrator. Prints every step's command + cwd without
+  executing them. Useful for screenshots, sanity-checking the pipeline order,
+  and CI plan-mode.
+- **Pre-flight `doctor` in `init`.** `npx local-expo-build init` now runs
+  `doctor` first and only proceeds with scaffolding once the environment is
+  healthy. Use `--no-doctor` to skip.
+- **Keystore `rehydrate` provider.** New `keystore rehydrate` subcommand (also
+  surfaced in the `keystore setup` picker when applicable) binds an existing
+  `credentials.json` + `.jks` pair to `keystore.properties` and copies the
+  `.jks` into `android/app/`. No password re-entry.
+- **`credentials.json` scaffolder.** `ensureKeystore` now writes/maintains
+  `credentials.json` at project root from the same source as
+  `keystore.properties`, and gitignores it.
+- **Build artifact path printed at the end of every build.** Both runner mode
+  and scaffolded `npm run build:android:*` now print the absolute path and size
+  of the produced APK / AAB.
+- **`.jks` recovery in `setup-signing`.** If `expo prebuild --clean` wipes
+  `android/app/<storeFile>`, the build chain restores it from a stable source
+  (`credentials.json` keystorePath, `credentials/android/`, project root)
+  before invoking Gradle. Both `src/core/setupSigning.ts` and
+  `templates/scripts/setup-signing.js` carry the recovery.
+- New doctor checks: `Android package (app.json)` (critical), `EAS project
+  linked` (yellow when half-linked), `keystore.properties`, `Signing keystore
+  (.jks)`, `credentials.json (EAS)`. Suggestions block prints a numbered
+  remediation list when anything is missing.
+
+### Changed
+
+- `keystore setup` picker now lists `Rehydrate from credentials.json` as the
+  top, recommended option whenever a complete `credentials.json` + `.jks` are
+  on disk.
+- `fetchKeystoreFromEas` pre-flights both `expo.extra.eas.projectId` and
+  `eas.json` and offers to run `eas init` / `eas build:configure` interactively
+  before launching the EAS credentials menu.
+- `.gitignore` entries created by `init` / `keystore setup` now include
+  `credentials.json` alongside `keystore.properties` and `*.jks`.
+
+### Fixed
+
+- Builds failing with `validateSigningRelease > Keystore file not found` after
+  `expo prebuild --clean` (or after accepting the "android project is malformed
+  — reinitialize?" prompt). The keystore is now restored from a stable source
+  before Gradle runs.
+- Cryptic "credentials command failed" from `keystore fetch` on projects
+  without `eas.json` or a linked EAS project. Replaced with a guided
+  pre-flight.
+- `templates/scripts/build.js` orchestrator was passing `shell: false` to
+  `execSync` on Unix, which is undefined behavior. Now omits the option so
+  Node uses the platform default (`/bin/sh` on Unix, `cmd.exe` on Windows).
+  Fully cross-platform.
+
+## [0.1.0]
+
+Initial release. Local Expo Android APK/AAB pipeline with `prebuild`, Gradle
+wrapper pinning, version bump, signing config injection, Gradle build, and EAS
+versionCode sync.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil Dhawan
+
+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.

package/README.md

@@ -0,0 +1,372 @@
+# local-expo-build
+
+> One-stop CLI for **local** Expo Android APK / AAB builds. Bypass EAS cloud builds, keep full control of signing, and stop waiting in queues.
+
+[![npm version](https://img.shields.io/npm/v/local-expo-build.svg)](https://www.npmjs.com/package/local-expo-build)
+[![npm downloads](https://img.shields.io/npm/dm/local-expo-build.svg)](https://www.npmjs.com/package/local-expo-build)
+[![license](https://img.shields.io/npm/l/local-expo-build.svg)](https://github.com/nikhild64/local-expo-build/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/local-expo-build.svg)](https://nodejs.org/)
+
+`local-expo-build` automates the painful parts of running `expo prebuild` + `gradlew bundleRelease` yourself:
+
+- Detects your Expo SDK and pins the Gradle wrapper to a version that actually works (e.g. SDK 55 → Gradle 8.13, working around the `expo-manifests` `components.release` bug).
+- Bumps your app version and pulls the next `versionCode` from EAS so Play Store ingest doesn't reject the upload.
+- Injects a release `signingConfig` into the generated `android/app/build.gradle` from a `keystore.properties` you control.
+- Scaffolds `credentials.json` from the same source so EAS submit / cloud builds can reuse your local JKS.
+- Restores your `.jks` into `android/app/` if `expo prebuild --clean` wipes it (no more `validateSigningRelease > Keystore file not found`).
+- Runs `gradlew assembleRelease` / `bundleRelease` and prints the absolute path + size of the produced artifact.
+- Pushes the new `versionCode` back to EAS via GraphQL so `eas build` / `eas submit` stay in sync.
+
+**`doctor` is a setup wizard, not just a health check.** It detects missing pieces (`expo.android.package`, EAS link, `eas.json`, keystore) and offers to fix each one interactively — `eas init`, `eas build:configure`, keystore picker (with one-prompt `rehydrate` from `credentials.json` when possible), all chained.
+
+![local-expo-build init: doctor pre-flight + scaffolding in one command](https://raw.githubusercontent.com/nikhild64/local-expo-build/main/assets/screenshots/setup_init.png)
+
+Two modes:
+
+- **Scaffold** _(recommended)_ — `npx local-expo-build init` drops reusable, committable scripts into your project; you run `npm run build:android:aab` from then on.
+- **Runner** — `npx local-expo-build build android --aab`; one command, no files touched in your repo.
+
+## Install
+
+```bash
+npm i -g local-expo-build
+# or use it ad hoc
+npx local-expo-build --help
+```
+
+## Quick start (recommended — scaffold mode)
+
+```bash
+cd <your-expo-project>
+npx local-expo-build init
+```
+
+`init` runs `doctor` first as a pre-flight, walks you through any missing setup (EAS link, `eas.json`, keystore), then drops the build scripts and adds the `build:android:apk` / `build:android:aab` entries to your `package.json`. Then:
+
+```bash
+npm run build:android:aab     # release AAB → android/app/build/outputs/bundle/release/app-release.aab
+npm run build:android:apk     # release APK → android/app/build/outputs/apk/release/app-release.apk
+```
+
+After the build finishes, the absolute path + size of the artifact is printed at the very end so you always know where it landed.
+
+Skip the pre-flight in CI: `npx local-expo-build init --no-doctor --no-keystore`.
+
+### Alternative — runner mode (no scaffold)
+
+```bash
+npx local-expo-build doctor                 # env + setup wizard
+npx local-expo-build build android --aab    # full pipeline → .aab
+```
+
+Useful if you don't want any files committed to your repo and prefer to drive the whole pipeline from a single CLI call each time.
+
+## Commands
+
+```text
+local-expo-build init [--force] [--no-keystore] [--no-doctor]
+                                            Scaffold scripts + package.json entries
+                                            (runs `doctor` first by default)
+
+local-expo-build build android [--apk|--aab] [--profile <name>]
+                               [--clean] [--no-bump] [--no-sync] [--no-prebuild]
+                                            Run the full pipeline → .aab|.apk
+
+local-expo-build doctor                     Env check + interactive auto-fix wizard
+                                            (eas init → eas build:configure →
+                                             keystore setup)
+
+local-expo-build keystore setup             Interactive picker:
+                                            rehydrate | existing | generate | EAS
+local-expo-build keystore import            Register an existing .jks
+local-expo-build keystore create            Generate a new keystore via keytool
+local-expo-build keystore fetch             Open `eas credentials` to download a .jks
+local-expo-build keystore rehydrate [--move]
+                                            Bind credentials.json + .jks into
+                                            keystore.properties (no password re-entry).
+                                            --move deletes the source .jks after copy.
+```
+
+Global flags: `--cwd <path>`, `--verbose`, `--dry-run`.
+
+> **Dry-run** is wired into `build android` and the scaffolded orchestrator. Use it to preview the full pipeline (great for screenshots, sanity checks, CI plan-mode):
+>
+> ```bash
+> npx local-expo-build --dry-run build android --aab    # runner mode
+> npm run build:android:aab -- --dry-run                # scaffold mode (or: node scripts/build.js aab --dry-run)
+> ```
+
+![Dry-run output: the full 7-step build pipeline with no side effects](https://raw.githubusercontent.com/nikhild64/local-expo-build/main/assets/screenshots/dryrun-build.png)
+
+## How it compares
+
+|  | `eas build` (cloud) | `npx expo run:android` | `local-expo-build` |
+| --- | --- | --- | --- |
+| Runs locally | No | Yes | **Yes** |
+| Produces a signed release `.aab` / `.apk` | Yes | No (debug) | **Yes** |
+| Manages release `signingConfig` for you | Yes | No | **Yes** |
+| Bumps `versionCode` from EAS automatically | Yes | No | **Yes** |
+| Wait in cloud queue | Sometimes | Never | Never |
+| Works offline | No | Yes | **Yes** (after first prebuild) |
+| Needs `eas-cli` | Yes | No | Optional (only for version sync / EAS keystore) |
+
+If you're happy with cloud builds, use `eas build`. This CLI is for teams who want the EAS workflow (managed signing, synced `versionCode`) but the speed and control of building on their own machine.
+
+## Keystore sources
+
+When `keystore setup` runs (or when `doctor` / `init` prompt for it), you'll see one of these. **Rehydrate** appears at the top conditionally — only when a complete `credentials.json` + `.jks` are already on disk:
+
+| Source | What happens |
+| --- | --- |
+| **Rehydrate** | Reads `credentials.json` + the `.jks` it points at, copies the `.jks` into `android/app/<basename>`, writes `keystore.properties`. **No password re-entry.** Ideal after `keystore fetch`. |
+| **Existing .jks** | You point to a file + provide alias/passwords. Copied into `android/app/`. If a matching `credentials.json` is on disk (same path or same content hash), the password prompts are skipped — values reused automatically. |
+| **Generate new** | Wizard runs `keytool -genkeypair` with sane defaults (RSA 2048, 10000d). |
+| **EAS** | Opens `eas credentials` so you can download the project's current keystore from EAS. |
+
+In every case, after the keystore is registered the CLI also writes a matching `credentials.json` at the project root and adds `keystore.properties`, `*.jks`, and `credentials.json` to `.gitignore`.
+
+## Bringing your own keystore (EAS-managed flow)
+
+The lowest-friction path from a brand-new clone to a buildable project when your team already has a keystore on EAS. This is what `doctor` will walk you through.
+
+### 1. Fetch the keystore via EAS CLI
+
+```bash
+npx local-expo-build keystore fetch
+# Pre-flight: if eas.json or projectId is missing, we'll offer
+# to run `eas init` / `eas build:configure` before launching EAS.
+```
+
+EAS opens its interactive menu. Pick:
+
+```text
+✔ Which build profile do you want to configure?  ›  production
+✔ What do you want to do?                        ›  Keystore: Manage everything needed to build your project
+✔ What do you want to do?                        ›  Download existing keystore
+✔ Display sensitive information?                  ›  Yes
+✔ Go back
+✔ What do you want to do?                        ›  credentials.json: Upload/Download credentials …
+✔ What do you want to do?                        ›  Download credentials from EAS to credentials.json
+✔ What do you want to do?                        ›  Exit
+```
+
+You now have:
+
+- `<scope>__<project>.jks` at project root (from "Download existing keystore"),
+- `credentials.json` at project root with all four required fields,
+- `credentials/android/keystore.jks` (the file `credentials.json` actually references).
+
+### 2. Bind everything in one step
+
+```bash
+npx local-expo-build keystore rehydrate
+```
+
+That copies the `.jks` referenced by `credentials.json` into `android/app/<basename>` and writes `keystore.properties` using the passwords already in `credentials.json` — **no re-typing**.
+
+```text
+✓ Copied credentials/android/keystore.jks → android/app/keystore.jks
+✓ keystore.properties written from credentials.json (alias=6805615551f1…)
+✓ Wrote credentials.json (keystorePath=android/app/keystore.jks)
+```
+
+### 3. Build
+
+```bash
+npm run build:android:aab        # scaffold mode
+# or
+npx local-expo-build build android --aab   # runner mode
+```
+
+> Tip: you can skip step 2 entirely — `doctor` detects the rehydrate state automatically and offers the same one-prompt fix inline.
+
+## Files this CLI creates / touches
+
+| Path | Purpose | Gitignored? |
+| --- | --- | --- |
+| `keystore.properties` (root) | Gradle release `signingConfig` source of truth: `storeFile`, `storePassword`, `keyAlias`, `keyPassword` | Yes (auto) |
+| `credentials.json` (root) | EAS submit/cloud's local-credential pointer. Kept in sync with `keystore.properties`. | Yes (auto) |
+| `android/app/<storeFile>` | The actual `.jks` that Gradle reads | Yes (`*.jks`, auto) |
+| `eas.json` (root) | EAS build profile config (created by `eas build:configure`) | No — commit it |
+| `app.json` → `expo.extra.eas.projectId` | EAS link (written by `eas init`) | No — commit it |
+| `app.json` → `expo.android.package` | Android applicationId | No — commit it |
+| `scripts/build.js` | (Scaffold mode only) single orchestrator entry point — what `npm run build:android:*` actually calls | No — commit it |
+| `scripts/{pin-gradle,bump-version,setup-signing,sync-eas-version,print-artifact}.js` | (Scaffold mode only) per-step modules orchestrated by `build.js`; edit any one to customize that step for your project | No — commit them |
+
+> **Security:** `keystore.properties` and `credentials.json` both contain plaintext keystore passwords. The CLI gitignores them automatically. **Don't commit them. Don't paste them into chat.** If you need them in CI, base64-encode and inject via secrets.
+
+## Multi-SDK support
+
+`local-expo-build` carries a small table of Gradle wrapper versions per SDK in [`src/core/pinGradle.ts`](src/core/pinGradle.ts):
+
+```ts
+export const GRADLE_PIN: Record<number, string | null> = {
+  50: null,
+  51: null,
+  52: null,
+  53: null,
+  54: null,
+  55: '8.13',   // expo-manifests components.release workaround
+  56: null,
+};
+```
+
+If your SDK isn't pinned, `pinGradle` is a no-op. Add a row + open a PR if a future SDK needs one.
+
+## Requirements
+
+- Node ≥ 18
+- JDK 17 (recommended for Expo SDK 55)
+- Android SDK + `ANDROID_HOME` env var
+- `keytool` on `PATH` (ships with the JDK)
+- `eas-cli` is **optional** — only needed for EAS version sync, EAS keystore fetch, or doctor's `eas init` / `eas build:configure` auto-fixes
+
+Run `local-expo-build doctor` to verify all of the above.
+
+## How it works (pipeline)
+
+```text
+expo prebuild --platform android
+  → pin Gradle wrapper            (src/core/pinGradle.ts)
+  → bump version + EAS code       (src/core/bumpVersion.ts)
+  → ensure keystore               (src/core/keystore/*)
+  → restore .jks into android/app (src/core/setupSigning.ts → ensureKeystoreInAndroidApp)
+  → inject release signing        (src/core/setupSigning.ts)
+  → write/sync credentials.json   (src/core/writeCredentialsJson.ts)
+  → gradlew {assemble|bundle}Release
+  → sync versionCode to EAS       (src/core/syncEasVersion.ts)
+  → print artifact path + size    (templates/scripts/print-artifact.js)
+```
+
+The scaffolded `scripts/*.js` files mirror the same logic so they're vendorable and editable per-project.
+
+### Doctor's auto-fix chain
+
+```text
+expo.android.package (app.json or app.config.*)  → prompt + write to app.json
+EAS link (expo.extra.eas.projectId)              → offer `eas init`
+eas.json                                          → offer `eas build:configure --platform android`
+keystore.properties                               → offer keystore picker
+                                                     ├─ credentials.json + .jks present  → rehydrate (no password re-entry)
+                                                     └─ else                              → existing | generate | EAS
+```
+
+Each accepted step re-runs the affected checks in place. If everything ends up green, doctor exits 0; otherwise the remaining items are printed under **Suggested next steps to complete setup**.
+
+Dynamic configs (`app.config.{js,ts,cjs,mjs}`) are supported: doctor shells out to `npx expo config --json --type public` and reads the resolved config. If the Expo CLI fails to resolve (e.g. you haven't `npm install`ed yet), the affected rows show a yellow warning instead of pretending. Auto-writes still target `app.json` only — we don't modify dynamic config files.
+
+`init` runs the entire doctor chain as its pre-flight before scaffolding. Pass `--no-doctor` to skip.
+
+Your `package.json` ends up with just two added lines, both pointing at the orchestrator:
+
+```json
+{
+  "scripts": {
+    "build:android:apk": "node scripts/build.js apk",
+    "build:android:aab": "node scripts/build.js aab"
+  }
+}
+```
+
+The orchestrator (`scripts/build.js`) prints numbered progress (`▸ [3/7] bump version`, etc.) and a final total time. EAS version sync is treated as non-fatal — if your EAS login expires, the build still succeeds and you get a single warning line instead of a hard fail.
+
+## Troubleshooting
+
+### `validateSigningRelease > Keystore file '…/android/app/keystore.jks' not found`
+
+This happens when `expo prebuild --clean` (or the "android project is malformed — reinitialize?" prompt) wipes `android/` between keystore setup and the Gradle build. The pipeline restores it automatically as of v0.2.0 — make sure your scaffolded `scripts/setup-signing.js` is up to date:
+
+```bash
+npx local-expo-build init --force
+```
+
+If the recovery itself fails, you'll get a clear list of paths it tried; the fix is usually:
+
+```bash
+npx local-expo-build keystore rehydrate     # if you have credentials.json
+# or
+npx local-expo-build keystore import <path-to-jks>
+```
+
+### `eas credentials failed: Command failed with exit code 1`
+
+`eas credentials` refuses to start without `eas.json` and a linked `expo.extra.eas.projectId`. v0.2.0 pre-flights both and offers to run `eas init` / `eas build:configure` interactively. If you skipped those prompts, run them manually:
+
+```bash
+eas init
+eas build:configure --platform android
+```
+
+Then re-run `npx local-expo-build keystore fetch`.
+
+### `Missing expo.android.package in app.json`
+
+Doctor catches this as a critical check and offers to write it for you with a sensible default derived from `expo.slug` or `expo.ios.bundleIdentifier`. If you're using `app.config.{js,ts}`, doctor can't statically write to it — add the field by hand:
+
+```json
+{
+  "expo": {
+    "android": {
+      "package": "com.yourcompany.yourapp"
+    }
+  }
+}
+```
+
+### "The android project is malformed, would you like to clear and reinitialize?"
+
+This is `expo prebuild` detecting that our injected `signingConfigs.release` block doesn't match what it would generate fresh. Accepting it is safe — the build chain re-injects signing and the recovery step puts the `.jks` back before Gradle runs.
+
+### `expo CLI (in project) not found` in doctor
+
+You haven't installed deps in the target Expo project yet. Run `npm install` (or `pnpm install` / `yarn`) in the project root.
+
+### Build artifact is signed but Play Console rejects it
+
+Two common causes:
+
+1. **`versionCode` already used.** The `--no-sync` flag suppresses pushing the new `versionCode` back to EAS — if you used it and Play sees the same code as a previous upload, it'll reject. Don't pass `--no-sync` unless you're managing versions manually.
+2. **Different keystore than the one originally registered.** Play Store requires the *same* keystore for all updates to a published app. Use `keystore fetch` + `keystore rehydrate` to get back the original.
+
+## Testing the CLI locally in another Expo app
+
+Three iteration loops, fastest to most-realistic:
+
+```bash
+# 1. npm link — fastest dev loop
+cd local-expo-build && npm run build && npm link
+cd ../my-test-app && npm link local-expo-build
+# now changes in local-expo-build (with `npm run dev` watching) are picked up
+# on the next `npx local-expo-build ...` call from my-test-app.
+
+# 2. npm pack — exactly what end users will install
+cd local-expo-build && npm run build && npm pack
+cd ../my-test-app && npm i ../local-expo-build/local-expo-build-0.2.0.tgz
+
+# 3. Direct invocation — no install at all
+cd local-expo-build && npm run build
+node /abs/path/local-expo-build/bin/local-expo-build.js doctor --cwd /abs/path/my-test-app
+```
+
+## Roadmap
+
+- [ ] iOS local builds
+- [ ] Auto-update `GRADLE_PIN` table from a hosted manifest
+- [ ] Symbol upload (`mapping.txt` → Play Console / Sentry)
+- [ ] CI presets (`init --ci` that scaffolds a GitHub Actions / GitLab CI workflow with base64-encoded secrets)
+
+## Contributing
+
+PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, code layout, and conventions.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE) © Nikhil Dhawan
+
+---
+
+**Not affiliated with Expo or Google.** "Expo" and "EAS" are trademarks of 650 Industries, Inc. This project consumes EAS's public APIs (`api.expo.dev/graphql`, `eas-cli`) but is independently maintained.

package/bin/local-expo-build.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/cli.js');

package/dist/cli.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const kleur_1 = __importDefault(require("kleur"));
+const build_1 = require("./commands/build");
+const init_1 = require("./commands/init");
+const keystore_1 = require("./commands/keystore");
+const doctor_1 = require("./commands/doctor");
+const pkg = require('../package.json');
+const program = new commander_1.Command();
+program
+    .name('local-expo-build')
+    .description('Local Expo Android build CLI — bypasses EAS cloud builds. ' +
+    'Prebuild, pin Gradle, bump version, sign with your JKS, run gradlew, sync EAS.')
+    .version(pkg.version)
+    .option('--cwd <path>', 'project directory (default: process.cwd())')
+    .option('--verbose', 'verbose logging')
+    .option('--dry-run', 'print actions without executing destructive steps');
+(0, build_1.registerBuildCommand)(program);
+(0, init_1.registerInitCommand)(program);
+(0, keystore_1.registerKeystoreCommand)(program);
+(0, doctor_1.registerDoctorCommand)(program);
+program
+    .parseAsync(process.argv)
+    .catch((err) => {
+    console.error(kleur_1.default.red('\nlocal-expo-build failed:'));
+    console.error(err?.stack || err?.message || err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;AAAA,yCAAoC;AACpC,kDAA0B;AAC1B,4CAAwD;AACxD,0CAAsD;AACtD,kDAA8D;AAC9D,8CAA0D;AAE1D,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEvC,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,kBAAkB,CAAC;KACxB,WAAW,CACV,4DAA4D;IAC1D,gFAAgF,CACnF;KACA,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;KACpB,MAAM,CAAC,cAAc,EAAE,4CAA4C,CAAC;KACpE,MAAM,CAAC,WAAW,EAAE,iBAAiB,CAAC;KACtC,MAAM,CAAC,WAAW,EAAE,mDAAmD,CAAC,CAAC;AAE5E,IAAA,4BAAoB,EAAC,OAAO,CAAC,CAAC;AAC9B,IAAA,0BAAmB,EAAC,OAAO,CAAC,CAAC;AAC7B,IAAA,kCAAuB,EAAC,OAAO,CAAC,CAAC;AACjC,IAAA,8BAAqB,EAAC,OAAO,CAAC,CAAC;AAE/B,OAAO;KACJ,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC;KACxB,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACb,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,IAAI,GAAG,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;IACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/commands/build.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBuildCommand = registerBuildCommand;
+const fs_1 = __importDefault(require("fs"));
+const ctx_1 = require("../util/ctx");
+const log_1 = require("../util/log");
+const sdkDetect_1 = require("../core/sdkDetect");
+const prebuild_1 = require("../core/prebuild");
+const pinGradle_1 = require("../core/pinGradle");
+const bumpVersion_1 = require("../core/bumpVersion");
+const setupSigning_1 = require("../core/setupSigning");
+const gradleRun_1 = require("../core/gradleRun");
+const syncEasVersion_1 = require("../core/syncEasVersion");
+const keystore_1 = require("../core/keystore");
+function registerBuildCommand(program) {
+    const build = program.command('build').description('Build commands');
+    build
+        .command('android')
+        .description('Build a local Android APK or AAB')
+        .option('--apk', 'build APK (assembleRelease)')
+        .option('--aab', 'build AAB (bundleRelease) — default')
+        .option('--profile <profile>', 'EAS profile for versionCode fetch', 'production')
+        .option('--clean', 'pass --clean to expo prebuild')
+        .option('--no-bump', 'skip version bump')
+        .option('--no-sync', 'skip EAS versionCode sync after build')
+        .option('--no-prebuild', 'skip expo prebuild step')
+        .action(async (opts, cmd) => {
+        const ctx = (0, ctx_1.getCtx)(cmd);
+        const task = opts.apk ? 'assembleRelease' : 'bundleRelease';
+        const kind = task === 'bundleRelease' ? 'AAB' : 'APK';
+        log_1.log.step(`local-expo-build android (${kind})`);
+        log_1.log.dim('Local build · runs on your machine · saves an EAS cloud build credit');
+        log_1.log.dim(`cwd: ${ctx.cwd}`);
+        if (ctx.dryRun) {
+            log_1.log.warn('DRY RUN — no files modified, no Gradle build executed.');
+        }
+        const sdk = (0, sdkDetect_1.detectExpoSdk)(ctx.cwd);
+        log_1.log.ok(`Detected Expo SDK ${sdk.major} (${sdk.raw})`);
+        if (opts.prebuild !== false) {
+            log_1.log.step('1/6 expo prebuild');
+            if (ctx.dryRun) {
+                log_1.log.dim(`[dry-run] would run: expo prebuild --platform android${opts.clean ? ' --clean' : ''}`);
+            }
+            else {
+                await (0, prebuild_1.prebuild)({ cwd: ctx.cwd, clean: Boolean(opts.clean) });
+            }
+        }
+        else {
+            log_1.log.dim('Skipping prebuild (--no-prebuild)');
+        }
+        log_1.log.step('2/6 pin Gradle wrapper');
+        if (ctx.dryRun) {
+            log_1.log.dim(`[dry-run] would pin Gradle wrapper for SDK ${sdk.major} (see src/core/pinGradle.ts)`);
+        }
+        else {
+            (0, pinGradle_1.pinGradle)({ cwd: ctx.cwd, sdk: sdk.major });
+        }
+        if (opts.bump !== false) {
+            log_1.log.step('3/6 bump version');
+            if (ctx.dryRun) {
+                log_1.log.dim(`[dry-run] would fetch next versionCode from EAS (profile=${opts.profile}) and write app.json + build.gradle`);
+            }
+            else {
+                (0, bumpVersion_1.bumpVersion)({ cwd: ctx.cwd, profile: opts.profile });
+            }
+        }
+        else {
+            log_1.log.dim('Skipping version bump (--no-bump)');
+        }
+        log_1.log.step('4/6 ensure keystore + inject signing config');
+        if (ctx.dryRun) {
+            log_1.log.dim('[dry-run] would ensure keystore.properties + .jks present, then inject release signingConfig into build.gradle');
+        }
+        else {
+            await (0, keystore_1.ensureKeystore)(ctx.cwd);
+            (0, setupSigning_1.setupSigning)({ cwd: ctx.cwd });
+        }
+        log_1.log.step(`5/6 gradle ${task}`);
+        let artifact = '';
+        if (ctx.dryRun) {
+            const isWin = process.platform === 'win32';
+            const wrapper = isWin ? 'gradlew.bat' : './gradlew';
+            log_1.log.dim(`[dry-run] would run (cwd=android/): ${wrapper} ${task}`);
+        }
+        else {
+            artifact = await (0, gradleRun_1.gradleRun)({ cwd: ctx.cwd, task });
+        }
+        if (opts.sync !== false) {
+            log_1.log.step('6/6 sync EAS versionCode');
+            if (ctx.dryRun) {
+                log_1.log.dim('[dry-run] would POST new versionCode to api.expo.dev/graphql (non-fatal on failure)');
+            }
+            else {
+                try {
+                    await (0, syncEasVersion_1.syncEasVersion)({ cwd: ctx.cwd });
+                }
+                catch (err) {
+                    log_1.log.warn(`EAS sync failed (non-fatal): ${err?.message || err}`);
+                }
+            }
+        }
+        else {
+            log_1.log.dim('Skipping EAS sync (--no-sync)');
+        }
+        log_1.log.step('Done');
+        if (ctx.dryRun) {
+            log_1.log.ok(`DRY RUN complete — 6 steps shown for ${kind}. Re-run without --dry-run to actually build.`);
+        }
+        else if (fs_1.default.existsSync(artifact)) {
+            const sizeMb = (fs_1.default.statSync(artifact).size / 1024 / 1024).toFixed(2);
+            log_1.log.ok(`Build complete (${kind}, ${sizeMb} MB):\n  ${artifact}`);
+        }
+        else {
+            log_1.log.warn(`Build finished but artifact not found at ${artifact}`);
+        }
+    });
+}
+//# sourceMappingURL=build.js.map

package/dist/commands/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"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"}