Use pnpm with the tracked lockfiles. Native modules require local Android/iOS
builds. Generated android/ and ios/ directories are ignored; keep permanent
changes in app configuration, config plugins and modules.
| Component | Repository pin or requirement |
|---|---|
| Node / pnpm | 24.20.0 / 10.34.5 |
| Expo / React Native / React | 58.0.24 / 0.88.1 / 19.3.0 |
| Java | Temurin 17.0.20.1+1; CI notation 17.0.20+101 |
| Android SDK / Build Tools | Compile API 37 with 37.0.0, target API 36 |
| Gradle / Android Gradle Plugin | 9.4.1 / 9.2.1 |
| Android NDK / CMake | 27.1.12297006 / 3.22.1 |
| iOS | Mac with full Xcode and CocoaPods; deployment target iOS 18.4 |
The manifests, lockfiles and config plugins own package and native dependency
versions. CI uses Xcode 27.1. Local .tools/ helpers are optional and absent from
a fresh clone. Configure JAVA_HOME, ANDROID_HOME and PATH for your installed tools.
Run from the repository root:
pnpm install --frozen-lockfile
pnpm run runtime:install
pnpm run quality:installThe root, runtime, quality tools and individual lab projects use separate lockfiles. Install each lab in its own directory before running its tests. Frozen installs preserve the reviewed graph, patches and package-resolution policy. Do not replace lockfiles or bypass policy to make installation succeed.
Install the SDK components above and make adb available. Start an emulator or
connect a development device:
pnpm run prebuild:android
pnpm run androidThe Debug app needs Metro. For an unsigned standalone ARM64 build:
pnpm run prebuild:android
cd android
./gradlew assembleRelease --no-daemon -PreactNativeArchitectures=arm64-v8a
cd ..On Windows, use gradlew.bat. The output is
android/app/build/outputs/apk/release/app-release-unsigned.apk. It embeds
JavaScript and must be signed before installation. Local Android builds do not
require EAS or an Expo account; Gradle and package registries remain dependencies.
Select full Xcode and generate the native project:
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
pnpm run prebuild:ios
cd ios
pod install
cd ..Run CocoaPods from ios/: the autolinker resolves
Podfile.properties.json relative to its working directory. App configuration
builds the selected native dependencies from source and applies tracked codec
patches and notice guards. Keep those hooks intact.
For a physical iPhone, pair it with Xcode, enable Developer Mode and select a
development team for the Hypergolic target in ios/Hypergolic.xcworkspace.
Then run:
pnpm exec expo run:ios --deviceKeep Metro running and reachable from the phone for a Debug build. The normal app requires a physical iPhone for protected identity storage. Public-identity Simulator fixtures have separate entry points and cannot prove physical key protection or OS authentication. See the native harnesses.
pnpm run check
pnpm run export:android
pnpm run export:ioscheck runs TypeScript, pinned-SDK compatibility and Expo Doctor, React Doctor, aislop and dependency audits
for the root, runtime and quality-tool lockfiles. High/critical audit findings
block the gate. A successful export is a JavaScript bundle, not an installable
native build. Report each result and any blocked or skipped stage separately.
Both final React Doctor and aislop scores must reach 100/100 without hiding findings. The standard local React Doctor command disables telemetry and its scoring service; clean local diagnostics do not provide a numeric score. CI obtains numeric scores and audits all ten lockfiles. See the patch and exception record.
check does not run every behavioral test. Run the suites relevant to the change,
for example:
pnpm run test:shell
pnpm run test:security
pnpm run test:storage
pnpm run test:capabilities
pnpm run test:signer
pnpm run test:qualityThe root manifest also defines query, subscriptions, resources, uploads, identity, links, routing, presentation and Outbox suites. Browser runtime checks use:
pnpm --dir runtime exec playwright install chromium webkit
pnpm run runtime:testNative harnesses require the prerequisites and explicit targets in their local READMEs. Inspect their documented effects before running them. Use fresh evidence directories and disposable test identities. Keep private evidence out of Git. Native/config-plugin changes need regeneration and compilation on each affected platform, plus focused boundary tests. Compiles, browser tests and Simulator results do not close full native device acceptance.
See Android release candidates for the production variant, permanent signing-key setup, verified APK packaging and draft GitHub workflow.
On macOS or Linux, install Android Build Tools 36.0.0 alongside 37.0.0. The tester command uses 36.0.0 for alignment, signing and verification. Supply an existing signing keystore outside this checkout:
export HYPERGOLIC_KEYSTORE_PATH="/absolute/private/path/hypergolic-tester.jks"
pnpm run build:tester --check
pnpm run build:testerSet HYPERGOLIC_KEY_ALIAS if the keystore contains multiple keys. Password entry
is interactive. --check verifies configuration and tool availability without
building or unlocking the key. --help describes the supported options. Do not
run concurrent Android prebuild or Gradle jobs while this command owns the build.
Each successful run creates a new directory under .tools/tester-apks/ with the
signed ARM64 Release APK, SHA256SUMS and a build.json receipt. The command
verifies app identity, version, permissions, signature and alignment. It does not
create a signing key, increment versions, install, upload or run the full quality
and acceptance gates.
Keep the app ID and signing key stable for updates; increment
expo.android.versionCode before distribution. Cold-launch the exact signed APK
with Metro stopped and verify the intended workflow before sharing. Preserve
identity-bearing installations and their data. Packaging is separate from product
and security acceptance. Run pnpm run test:tester for the packaging command's
controlled contract tests.
Keep native patches, immutable upstream pins, packaged license originals and source/notice guards with their owning implementation. Changing a codec or native dependency needs actual native regeneration; exporting JavaScript is insufficient. The dependency notices and patch record explain current bindings and remaining review.
The checked-in workflow runs on pushes, pull requests and manual dispatch. It checks shared behavior separately from quality/audits, builds both JavaScript exports, compiles unsigned Android and iPhoneOS Release products, and checks the runtime plus all seven independently locked labs. Browser and conformance coverage vary by lab; see their manifests.
The README’s Tests badge combines the shared, runtime and seven lab jobs on
main. The score badges read a completed measurement for that commit from
the public Actions checks. The linked run lists each measurement and rerun. A
complete scan can report a score below 100. An incomplete scan shows
unavailable. CI requires both scores to reach 100, zero findings and a clean
audit for every lockfile. To run the same scans locally after installing the
root, runtime and quality dependencies, use a fresh evidence file outside the
checkout.
node scripts/run-quality.mjs "$PWD" "$(mktemp -d)/quality.json"The iOS compile selects the xcode-27 preview runner and verifies Xcode 27.1 and
SDK 27.1 before compiling the unsigned iPhoneOS Release build. Final iOS
acceptance also requires the signed-device journeys in the test plan.