@lynxship/cli 0.1.20 → 0.1.21

package/README.md

@@ -11,6 +11,33 @@ expiring download URL with a compact terminal QR code.
 > native hosts; HarmonyOS requires the official Hvigor/DevEco host; Web and
 > Desktop require the project's official Rspeedy/Lynxtron configuration.
 
+## Sparkling-compatible app configuration
+
+Projects may use the official Sparkling-style `app.config.ts` (or its JavaScript
+variants) as the single Lynx build entrypoint:
+
+```ts
+import { defineConfig } from "@lynx-js/rspeedy";
+
+export default {
+  lynxConfig: defineConfig({
+    source: { entry: { main: "./src/pages/main/index.tsx" } },
+    environments: { lynx: {} },
+  }),
+  appName: "My Lynx app",
+  platform: { android: { packageName: "com.example.myapp" } },
+  paths: { android: "android/app/src/main/assets" },
+};
+```
+
+When `lynxship build` finds this file, it loads it only for the explicit build
+operation, validates its routes/plugins and safe project-relative paths, then
+calls the installed project's `createRspeedy` API with `lynxConfig`. Android
+and iOS host generation also reuses the declared identifiers, name, icon and
+asset paths. `lynxship.json` remains the place for LynxShip profiles, signing,
+OTA and cloud settings; projects with a normal `lynx.config.*` keep their
+existing package-manager build workflow.
+
 ## Install
 
 ```bash
@@ -25,6 +52,35 @@ npx @lynxship/cli@latest doctor --project-dir ./my-lynx-app
 
 The package exposes the `lynxship` executable.
 
+## Automatic i18n setup
+
+For a Lynx project using i18next, the CLI can perform the repeatable setup in
+one explicit, reviewable command:
+
+```bash
+npx @lynxship/cli@latest init
+npx @lynxship/cli@latest i18n setup --dry-run
+npx @lynxship/cli@latest i18n setup
+```
+
+The setup command detects the entry file and JSON locale catalog, installs
+`@lynxship/i18n`, a compatible i18next major, the LynxShip device-storage
+bridge and only the FormatJS polyfills needed by detected `Intl.*` usage. It
+generates `src/lynxship/i18n-polyfills.ts` with static imports in dependency
+order and adds one import to the detected entry file. Use `--intl all` when a
+library accesses Intl dynamically, `--locales en,fr,ar` to override locale
+discovery, or `--entry src/index.tsx` when the entry file is non-standard. The
+command fails rather than guessing an ambiguous entry file.
+
+The adapter restores the last resolved language automatically when the host
+exposes `LynxShipDeviceStorage` (Android, iOS or another linked Lynx host), or
+browser `localStorage` on Web. The lookup is local and best-effort; no network
+request is made and a missing host bridge does not prevent the app from
+starting. Projects with their own storage can inject the `persistence.storage`
+contract. `--no-persistence` skips installation of the device-storage bridge.
+Generated polyfills are static and recorded in the project lockfile: npm
+cannot be downloaded silently from an application bundle at runtime.
+
 ## Plugin ecosystem
 
 Install a community plugin as a normal project dependency, list it in
@@ -273,7 +329,7 @@ autolink check       Check Lynx native-library wiring
 autolink codegen     Run native-module codegen
 ota doctor           Check native OTA host integration
 storage configure   Configure Cloudflare R2
-android host init   Create a minimal official Lynx Android host
+android host init   Create an official Lynx Android host baseline
 android configure   Configure Android signing
 store configure      Configure store submission credentials
 ```
@@ -491,9 +547,12 @@ lynxship android host init --application-id com.example.myapp
 
 This command never overwrites an existing `android/` directory. It creates a
 real Gradle application with the official Lynx Android dependencies,
-`LynxEnv`, `LynxView`, a bundle loader and a Gradle wrapper. Replace the example
-application ID before a store release and add any project-specific native
-modules, permissions, services and OTA integration explicitly.
+`LynxEnv`, `LynxView`, a bundle loader and a Gradle wrapper. The generated
+Activity also provides lifecycle-aware loading/error feedback, tap-to-retry,
+the official `onFirstScreen` readiness signal and explicit `LynxView.destroy()`
+cleanup. Replace the example application ID before a store release and add
+any project-specific native modules, permissions, services and OTA integration
+explicitly.
 
 For a pure project that targets iOS, create the native Xcode/CocoaPods host
 with:
@@ -518,7 +577,9 @@ preview only; provide the project icon for an IPA or store release.
 The command refuses to overwrite an existing `ios/` directory and creates a
 Swift host based on Lynx's official integration shape: `LynxEnv`, `LynxView`,
 `LynxTemplateProvider`, `Podfile`, `ExportOptions.plist` and a bundle sync
-script. On macOS, `lynxship build --platform ios` installs CocoaPods before
+script. The generated view also provides adaptive full-screen layout,
+lifecycle-aware loading/error feedback, tap-to-retry and first-screen
+readiness. On macOS, `lynxship build --platform ios` installs CocoaPods before
 archiving. Xcode, CocoaPods and real Apple signing credentials are still
 required for a signed IPA; the CLI never fabricates them.
 

package/dist/android/signing.d.ts

@@ -0,0 +1,16 @@
+import type { BuildProfile } from "../config.js";
+export declare function signingEnvironment(root: string): Promise<NodeJS.ProcessEnv>;
+export declare function createSigningInitScript(): Promise<{
+    directory: string;
+    file: string;
+}>;
+export declare function verifySignedArtifact(root: string, artifactPath: string, options: {
+    quiet: boolean;
+    onOutput?: (line: string) => void;
+}): Promise<void>;
+export declare function androidTool(name: string): string | undefined;
+export declare function artifactDetails(root: string, profile: BuildProfile): {
+    task: string;
+    path: string;
+};
+//# sourceMappingURL=signing.d.ts.map

package/dist/android/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../../src/android/signing.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAQjD,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAoB5B;AAED,wBAAsB,uBAAuB,IAAI,OAAO,CAAC;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAiDD;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC7D,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAyB5D;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAkChC"}

package/dist/android/signing.js

@@ -0,0 +1,131 @@
+import { chmod, mkdtemp, writeFile } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assert } from "@lynxship/contracts";
+import { loadCredentials } from "../secure-store.js";
+import { commandExists, executableExists, runProcess, } from "../process-runner.js";
+export async function signingEnvironment(root) {
+    const android = (await loadCredentials(root)).android;
+    const values = {
+        LYNXSHIP_KEYSTORE_PATH: process.env.LYNXSHIP_KEYSTORE_PATH ?? android?.keystorePath,
+        LYNXSHIP_KEY_ALIAS: process.env.LYNXSHIP_KEY_ALIAS ?? android?.keyAlias,
+        LYNXSHIP_KEYSTORE_PASSWORD: process.env.LYNXSHIP_KEYSTORE_PASSWORD ?? android?.keystorePassword,
+        LYNXSHIP_KEY_PASSWORD: process.env.LYNXSHIP_KEY_PASSWORD ?? android?.keyPassword,
+    };
+    const missing = Object.entries(values)
+        .filter(([, value]) => !value)
+        .map(([name]) => name);
+    assert(missing.length === 0, "BUILD_SIGNING_REQUIRED", `Signed Android builds require configuration. Missing: ${missing.join(", ")}. Run \`lynxship android configure\`.`);
+    return { ...process.env, ...values };
+}
+export async function createSigningInitScript() {
+    const directory = await mkdtemp(join(tmpdir(), "lynxship-gradle-"));
+    const file = join(directory, "android-signing.init.gradle");
+    const script = `
+def keystorePath = System.getenv("LYNXSHIP_KEYSTORE_PATH")
+def keyAlias = System.getenv("LYNXSHIP_KEY_ALIAS")
+def keystorePassword = System.getenv("LYNXSHIP_KEYSTORE_PASSWORD")
+def keyPassword = System.getenv("LYNXSHIP_KEY_PASSWORD")
+
+gradle.allprojects { project ->
+    project.plugins.withId("com.android.application") {
+        def configureSigning = { android ->
+            def signing = android.signingConfigs.findByName("release")
+            if (signing == null) {
+                signing = android.signingConfigs.create("lynxshipRelease")
+            }
+            signing.storeFile = project.file(keystorePath)
+            signing.storePassword = keystorePassword
+            signing.keyAlias = keyAlias
+            signing.keyPassword = keyPassword
+
+            def release = android.buildTypes.findByName("release")
+            if (release == null) {
+                throw new GradleException(
+                    "LynxShip requires an Android release build type"
+                )
+            }
+            release.signingConfig = signing
+            project.logger.lifecycle(
+                "[LynxShip] Applied machine signing credentials to \${project.path}:release"
+            )
+        }
+
+        def androidComponents = project.extensions.findByName("androidComponents")
+        if (androidComponents != null) {
+            androidComponents.finalizeDsl { android ->
+                configureSigning(android)
+            }
+        } else {
+            project.afterEvaluate {
+                configureSigning(project.extensions.findByName("android"))
+            }
+        }
+    }
+}
+`;
+    await writeFile(file, script, "utf8");
+    await chmod(file, 0o600).catch(() => undefined);
+    return { directory, file };
+}
+export async function verifySignedArtifact(root, artifactPath, options) {
+    if (artifactPath.endsWith(".apk")) {
+        const apksigner = androidTool("apksigner");
+        assert(apksigner, "ANDROID_APKSIGNER_REQUIRED", "apksigner was not found in PATH. Install the Android SDK Build Tools.");
+        await runProcess(apksigner, ["verify", "--verbose", artifactPath], {
+            cwd: root,
+            ...options,
+        });
+        return;
+    }
+    const jarsigner = commandExists("jarsigner") ? "jarsigner" : undefined;
+    assert(jarsigner, "ANDROID_JARSIGNER_REQUIRED", "jarsigner was not found in PATH. Install JDK 17.");
+    await runProcess(jarsigner, ["-verify", "-verbose", "-certs", artifactPath], {
+        cwd: root,
+        ...options,
+    });
+}
+export function androidTool(name) {
+    if (commandExists(name)) {
+        if (process.platform !== "win32")
+            return name;
+        try {
+            return execFileSync("where.exe", [name], { encoding: "utf8" })
+                .split(/\r?\n/)
+                .map((value) => value.trim())
+                .find(Boolean);
+        }
+        catch {
+            return name;
+        }
+    }
+    const sdk = process.env.ANDROID_SDK_ROOT ?? process.env.ANDROID_HOME ?? undefined;
+    if (!sdk)
+        return undefined;
+    const executable = process.platform === "win32" ? `${name}.bat` : name;
+    try {
+        return readdirSync(join(sdk, "build-tools"))
+            .sort()
+            .reverse()
+            .map((version) => join(sdk, "build-tools", version, executable))
+            .find((candidate) => executableExists(candidate));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function artifactDetails(root, profile) {
+    const artifact = profile.android?.artifact ?? "apk";
+    assert(artifact === "apk" || artifact === "aab", "BUILD_ARTIFACT_INVALID", "Android artifact must be apk or aab");
+    return artifact === "aab"
+        ? {
+            task: "bundleRelease",
+            path: join(root, "android", "app", "build", "outputs", "bundle", "release", "app-release.aab"),
+        }
+        : {
+            task: "assembleRelease",
+            path: join(root, "android", "app", "build", "outputs", "apk", "release", "app-release.apk"),
+        };
+}

package/dist/android/types.d.ts

@@ -0,0 +1,12 @@
+import type { BuildProfile } from "../config.js";
+export interface AndroidBuildOptions {
+    root: string;
+    profile: BuildProfile;
+    uploadArtifacts?: boolean;
+    skipBundleBuild?: boolean;
+    quiet?: boolean;
+    onStep?: (message: string) => void;
+    onEvent?: (message: string) => void;
+    onProgress?: (value?: number, label?: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/android/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/android/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD"}

package/dist/android/types.js

@@ -0,0 +1 @@
+export {};

package/dist/android-build.d.ts

@@ -1,15 +1,5 @@
 import { type BuildJob } from "@lynxship/contracts";
-import type { BuildProfile } from "./config.js";
-interface AndroidBuildOptions {
-    root: string;
-    profile: BuildProfile;
-    uploadArtifacts?: boolean;
-    skipBundleBuild?: boolean;
-    quiet?: boolean;
-    onStep?: (message: string) => void;
-    onEvent?: (message: string) => void;
-    onProgress?: (value?: number, label?: string) => void;
-}
+import type { AndroidBuildOptions } from "./android/types.js";
 export declare function hasAndroidHost(root: string): Promise<boolean>;
 export declare function isSupportedAndroidPlatform(): boolean;
 /**
@@ -19,7 +9,8 @@ export declare function isSupportedAndroidPlatform(): boolean;
  * project to carry a helper script. Rspeedy writes bundles and static assets
  * to `dist`, while the Lynx Android host reads them from `app/src/main/assets`.
  */
-export declare function syncLynxAssets(root: string): Promise<string[]>;
+export declare function syncLynxAssets(root: string, options?: {
+    destination?: string;
+}): Promise<string[]>;
 export declare function runRealAndroidBuild(job: BuildJob, options: AndroidBuildOptions): Promise<BuildJob>;
-export {};
 //# sourceMappingURL=android-build.d.ts.map

package/dist/android-build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"android-build.d.ts","sourceRoot":"","sources":["../src/android-build.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAWhD,UAAU,mBAAmB;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AA8KD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa7D;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsCpE;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAgKnB"}
+{"version":3,"file":"android-build.d.ts","sourceRoot":"","sources":["../src/android-build.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAQpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAa7D;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACrC,OAAO,CAAC,MAAM,EAAE,CAAC,CAwCnB;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAuKnB"}

package/dist/android-build.js

@@ -1,138 +1,14 @@
-import { access, chmod, copyFile, cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile, } from "node:fs/promises";
-import { execFileSync } from "node:child_process";
-import { constants as fsConstants, existsSync, readdirSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { access, copyFile, cp, mkdir, readFile, readdir, rm, } from "node:fs/promises";
+import { constants as fsConstants, existsSync } from "node:fs";
 import { join } from "node:path";
 import { assert, sha256 } from "@lynxship/contracts";
 import { transitionBuild } from "@lynxship/build-orchestrator";
 import { loadR2, uploadR2Artifact } from "./r2.js";
-import { loadCredentials } from "./secure-store.js";
 import { nativeArtifactName } from "./artifact-name.js";
-import { commandExists, executableExists, runProcess, } from "./process-runner.js";
+import { runProcess } from "./process-runner.js";
 import { buildLynxBundle } from "./bundle-build.js";
-async function signingEnvironment(root) {
-    const android = (await loadCredentials(root)).android;
-    const values = {
-        LYNXSHIP_KEYSTORE_PATH: process.env.LYNXSHIP_KEYSTORE_PATH ?? android?.keystorePath,
-        LYNXSHIP_KEY_ALIAS: process.env.LYNXSHIP_KEY_ALIAS ?? android?.keyAlias,
-        LYNXSHIP_KEYSTORE_PASSWORD: process.env.LYNXSHIP_KEYSTORE_PASSWORD ?? android?.keystorePassword,
-        LYNXSHIP_KEY_PASSWORD: process.env.LYNXSHIP_KEY_PASSWORD ?? android?.keyPassword,
-    };
-    const missing = Object.entries(values)
-        .filter(([, value]) => !value)
-        .map(([name]) => name);
-    assert(missing.length === 0, "BUILD_SIGNING_REQUIRED", `Signed Android builds require configuration. Missing: ${missing.join(", ")}. Run \`lynxship android configure\`.`);
-    return { ...process.env, ...values };
-}
-async function createSigningInitScript() {
-    const directory = await mkdtemp(join(tmpdir(), "lynxship-gradle-"));
-    const file = join(directory, "android-signing.init.gradle");
-    const script = `
-def keystorePath = System.getenv("LYNXSHIP_KEYSTORE_PATH")
-def keyAlias = System.getenv("LYNXSHIP_KEY_ALIAS")
-def keystorePassword = System.getenv("LYNXSHIP_KEYSTORE_PASSWORD")
-def keyPassword = System.getenv("LYNXSHIP_KEY_PASSWORD")
-
-gradle.allprojects { project ->
-    project.plugins.withId("com.android.application") {
-        def configureSigning = { android ->
-            def signing = android.signingConfigs.findByName("release")
-            if (signing == null) {
-                signing = android.signingConfigs.create("lynxshipRelease")
-            }
-            signing.storeFile = project.file(keystorePath)
-            signing.storePassword = keystorePassword
-            signing.keyAlias = keyAlias
-            signing.keyPassword = keyPassword
-
-            def release = android.buildTypes.findByName("release")
-            if (release == null) {
-                throw new GradleException(
-                    "LynxShip requires an Android release build type"
-                )
-            }
-            release.signingConfig = signing
-            project.logger.lifecycle(
-                "[LynxShip] Applied machine signing credentials to \${project.path}:release"
-            )
-        }
-
-        def androidComponents = project.extensions.findByName("androidComponents")
-        if (androidComponents != null) {
-            androidComponents.finalizeDsl { android ->
-                configureSigning(android)
-            }
-        } else {
-            project.afterEvaluate {
-                configureSigning(project.extensions.findByName("android"))
-            }
-        }
-    }
-}
-`;
-    await writeFile(file, script, "utf8");
-    await chmod(file, 0o600).catch(() => undefined);
-    return { directory, file };
-}
-async function verifySignedArtifact(root, artifactPath, options) {
-    if (artifactPath.endsWith(".apk")) {
-        const apksigner = androidTool("apksigner");
-        assert(apksigner, "ANDROID_APKSIGNER_REQUIRED", "apksigner was not found in PATH. Install the Android SDK Build Tools.");
-        await runProcess(apksigner, ["verify", "--verbose", artifactPath], {
-            cwd: root,
-            ...options,
-        });
-        return;
-    }
-    const jarsigner = commandExists("jarsigner") ? "jarsigner" : undefined;
-    assert(jarsigner, "ANDROID_JARSIGNER_REQUIRED", "jarsigner was not found in PATH. Install JDK 17.");
-    await runProcess(jarsigner, ["-verify", "-verbose", "-certs", artifactPath], {
-        cwd: root,
-        ...options,
-    });
-}
-function androidTool(name) {
-    if (commandExists(name)) {
-        if (process.platform !== "win32")
-            return name;
-        try {
-            return execFileSync("where.exe", [name], { encoding: "utf8" })
-                .split(/\r?\n/)
-                .map((value) => value.trim())
-                .find(Boolean);
-        }
-        catch {
-            return name;
-        }
-    }
-    const sdk = process.env.ANDROID_SDK_ROOT ?? process.env.ANDROID_HOME ?? undefined;
-    if (!sdk)
-        return undefined;
-    const executable = process.platform === "win32" ? `${name}.bat` : name;
-    try {
-        return readdirSync(join(sdk, "build-tools"))
-            .sort()
-            .reverse()
-            .map((version) => join(sdk, "build-tools", version, executable))
-            .find((candidate) => executableExists(candidate));
-    }
-    catch {
-        return undefined;
-    }
-}
-function artifactDetails(root, profile) {
-    const artifact = profile.android?.artifact ?? "apk";
-    assert(artifact === "apk" || artifact === "aab", "BUILD_ARTIFACT_INVALID", "Android artifact must be apk or aab");
-    return artifact === "aab"
-        ? {
-            task: "bundleRelease",
-            path: join(root, "android", "app", "build", "outputs", "bundle", "release", "app-release.aab"),
-        }
-        : {
-            task: "assembleRelease",
-            path: join(root, "android", "app", "build", "outputs", "apk", "release", "app-release.apk"),
-        };
-}
+import { loadAppConfig, resolveAppConfigAssetPath } from "./app-config.js";
+import { artifactDetails, createSigningInitScript, signingEnvironment, verifySignedArtifact, } from "./android/signing.js";
 export function hasAndroidHost(root) {
     if (!isSupportedAndroidPlatform())
         return Promise.resolve(false);
@@ -151,9 +27,10 @@ export function isSupportedAndroidPlatform() {
  * project to carry a helper script. Rspeedy writes bundles and static assets
  * to `dist`, while the Lynx Android host reads them from `app/src/main/assets`.
  */
-export async function syncLynxAssets(root) {
+export async function syncLynxAssets(root, options = {}) {
     const distRoot = join(root, "dist");
-    const assetsRoot = join(root, "android", "app", "src", "main", "assets");
+    const assetsRoot = options.destination ??
+        join(root, "android", "app", "src", "main", "assets");
     let entries;
     try {
         entries = await readdir(distRoot, { withFileTypes: true });
@@ -228,9 +105,13 @@ export async function runRealAndroidBuild(job, options) {
         step("Checking Android SDK and Gradle toolchain…");
         transitionBuild(job, "installing_dependencies", "syncing Lynx bundle into Android assets");
         step("Syncing bundle into the Android host…");
-        const copiedAssets = await syncLynxAssets(options.root);
+        const appConfig = await loadAppConfig(options.root);
+        const assetsRoot = resolveAppConfigAssetPath(options.root, appConfig, "android", "android/app/src/main/assets");
+        const copiedAssets = await syncLynxAssets(options.root, {
+            destination: assetsRoot,
+        });
         for (const name of copiedAssets) {
-            options.onEvent?.(`Synced dist/${name} -> android/app/src/main/assets/${name}`);
+            options.onEvent?.(`Synced dist/${name} -> ${assetsRoot}/${name}`);
         }
         step("Android host synchronized", 40);
         transitionBuild(job, "building", `Gradle ${artifact.task}`);

package/dist/android-toolchain/inspection.d.ts

@@ -0,0 +1,3 @@
+import type { AndroidToolchainReport } from "./types.js";
+export declare function inspectAndroidToolchain(root: string): Promise<AndroidToolchainReport>;
+//# sourceMappingURL=inspection.d.ts.map

package/dist/android-toolchain/inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.d.ts","sourceRoot":"","sources":["../../src/android-toolchain/inspection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,YAAY,CAAC;AAczE,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sBAAsB,CAAC,CA2LjC"}

package/dist/android-toolchain/inspection.js

@@ -0,0 +1,122 @@
+import { platform } from "node:os";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { commandExists, executableExists } from "../process-runner.js";
+import { check, compareVersions, javaCandidates, javaVersion, readAndroidInputs, requiredGradleForAgp, requiredJavaForAgp, sdkCandidates, sdkManagerPath, sdkExecutable, } from "./probes.js";
+export async function inspectAndroidToolchain(root) {
+    const inputs = readAndroidInputs(root);
+    const checks = [];
+    const wrapper = join(root, "android", platform() === "win32" ? "gradlew.bat" : "gradlew");
+    const wrapperExists = existsSync(wrapper) &&
+        (platform() === "win32" || executableExists(wrapper));
+    checks.push(check("gradle-wrapper", wrapperExists ? "pass" : "fail", wrapperExists
+        ? inputs.gradleVersion
+            ? `Gradle ${inputs.gradleVersion}`
+            : "found · version unknown"
+        : "missing", wrapperExists
+        ? undefined
+        : "lynxship android host init --application-id com.example.myapp"));
+    const minimumGradle = requiredGradleForAgp(inputs.agpVersion);
+    const gradleCompatible = Boolean(inputs.gradleVersion &&
+        minimumGradle &&
+        compareVersions(inputs.gradleVersion, minimumGradle) >= 0);
+    const gradleStatus = !inputs.gradleVersion || !inputs.agpVersion
+        ? "warn"
+        : gradleCompatible
+            ? "pass"
+            : "fail";
+    checks.push(check("agp-gradle-compatibility", gradleStatus, inputs.agpVersion && inputs.gradleVersion
+        ? `AGP ${inputs.agpVersion} · Gradle ${inputs.gradleVersion}${minimumGradle ? ` · minimum Gradle ${minimumGradle}` : ""}`
+        : "AGP or wrapper version not detected", gradleStatus === "fail" && minimumGradle
+        ? `Update the project wrapper to Gradle ${minimumGradle}; do not use a global Gradle installation`
+        : undefined));
+    const requiredJava = requiredJavaForAgp(inputs.agpVersion);
+    let detectedJava;
+    let javaPath;
+    for (const candidate of javaCandidates()) {
+        const version = await javaVersion(candidate, root);
+        if (version !== undefined) {
+            detectedJava = version;
+            javaPath = candidate;
+            break;
+        }
+    }
+    const javaStatus = detectedJava === undefined
+        ? "fail"
+        : detectedJava >= requiredJava
+            ? "pass"
+            : "fail";
+    checks.push(check("java", javaStatus, detectedJava === undefined
+        ? "missing"
+        : `JDK ${detectedJava}${javaPath === "java" ? " · PATH" : ""}`, javaStatus === "fail"
+        ? `Install/configure JDK ${requiredJava} and set JAVA_HOME, then run lynxship doctor --platform android`
+        : undefined));
+    const sdkPath = sdkCandidates().find((candidate) => existsSync(candidate));
+    const compileSdk = inputs.compileSdk;
+    const buildTools = inputs.buildToolsVersion;
+    const platformPackage = compileSdk
+        ? `platforms;android-${compileSdk}`
+        : undefined;
+    const buildToolsPackage = buildTools
+        ? `build-tools;${buildTools}`
+        : undefined;
+    const missingPackages = [
+        platformPackage &&
+            sdkPath &&
+            !existsSync(join(sdkPath, "platforms", `android-${compileSdk}`))
+            ? platformPackage
+            : undefined,
+        buildTools &&
+            sdkPath &&
+            !existsSync(join(sdkPath, "build-tools", buildTools))
+            ? buildToolsPackage
+            : undefined,
+    ].filter((value) => Boolean(value));
+    const sdkStatus = !sdkPath
+        ? "fail"
+        : missingPackages.length
+            ? "fail"
+            : "pass";
+    checks.push(check("android-sdk", sdkStatus, !sdkPath
+        ? "missing · set ANDROID_HOME or ANDROID_SDK_ROOT"
+        : missingPackages.length
+            ? `missing: ${missingPackages.join(", ")}`
+            : sdkPath, sdkStatus === "fail"
+        ? "Install Android Studio or the Android command-line tools, then run lynxship doctor --platform android --fix"
+        : undefined));
+    const manager = sdkPath ? sdkManagerPath(sdkPath) : undefined;
+    checks.push(check("sdkmanager", manager ? "pass" : sdkPath ? "warn" : "fail", manager
+        ? "available"
+        : sdkPath
+            ? "missing · use Android Studio SDK Manager"
+            : "unavailable until Android SDK is installed", manager && missingPackages.length
+        ? `sdkmanager ${missingPackages.map((value) => `"${value}"`).join(" ")}`
+        : undefined));
+    const adb = sdkPath ? sdkExecutable(sdkPath, "adb") : undefined;
+    checks.push(check("adb", adb || commandExists("adb") ? "pass" : "warn", adb || commandExists("adb")
+        ? "Android Platform-Tools available"
+        : "missing · required for lynxship run/logs", !adb && !commandExists("adb")
+        ? "Install Android SDK Platform-Tools, then run adb devices"
+        : undefined));
+    const apksigner = sdkPath ? sdkExecutable(sdkPath, "apksigner") : undefined;
+    checks.push(check("apksigner", apksigner || commandExists("apksigner") ? "pass" : "warn", apksigner || commandExists("apksigner")
+        ? "Android Build Tools available"
+        : "missing · required to verify APK signatures", !apksigner && !commandExists("apksigner")
+        ? "Install Android SDK Build Tools, then run lynxship doctor --platform android"
+        : undefined));
+    checks.push(check("android-sdk-licenses", sdkPath && existsSync(join(sdkPath, "licenses")) ? "pass" : "warn", sdkPath && existsSync(join(sdkPath, "licenses"))
+        ? "license directory found"
+        : "not verified", sdkPath ? "sdkmanager --licenses" : undefined));
+    const failures = checks.filter((item) => item.status === "fail");
+    return {
+        ok: failures.length === 0,
+        checks,
+        sdkPath,
+        compileSdk,
+        buildToolsVersion: buildTools,
+        agpVersion: inputs.agpVersion,
+        gradleVersion: inputs.gradleVersion,
+        javaVersion: detectedJava,
+        sdkPackages: missingPackages,
+    };
+}

package/dist/android-toolchain/probes.d.ts

@@ -0,0 +1,23 @@
+import type { ToolchainCheck, ToolchainCheckStatus } from "./types.js";
+interface AndroidProjectInputs {
+    agpVersion?: string;
+    compileSdk?: number;
+    buildToolsVersion?: string;
+    gradleVersion?: string;
+}
+export declare function readProjectFiles(root: string): string;
+export declare function readWrapperVersion(root: string): string | undefined;
+export declare function readAndroidInputs(root: string): AndroidProjectInputs;
+export declare function versionParts(version: string): number[];
+export declare function compareVersions(left: string, right: string): number;
+export declare function requiredGradleForAgp(agp?: string): string | undefined;
+export declare function requiredJavaForAgp(agp?: string): number;
+export declare function sdkCandidates(): string[];
+export declare function sdkExecutable(sdkPath: string, name: string): string | undefined;
+export declare function readDirectories(directory: string): string[];
+export declare function sdkManagerPath(sdkPath: string): string | undefined;
+export declare function javaVersion(javaPath: string, cwd: string): Promise<number | undefined>;
+export declare function javaCandidates(): string[];
+export declare function check(name: string, status: ToolchainCheckStatus, value: string, fix?: string): ToolchainCheck;
+export {};
+//# sourceMappingURL=probes.d.ts.map

package/dist/android-toolchain/probes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probes.d.ts","sourceRoot":"","sources":["../../src/android-toolchain/probes.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvE,UAAU,oBAAoB;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2BD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAcrD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAanE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAqBpE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAEtD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQnE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKrE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAkBxC;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAM3D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAelE;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU7B;AAED,wBAAgB,cAAc,IAAI,MAAM,EAAE,CA0DzC;AAED,wBAAgB,KAAK,CACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,oBAAoB,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,cAAc,CAEhB"}