@lynxship/cli 0.1.3 → 0.1.6

package/README.md

@@ -97,12 +97,27 @@ Progress percentages are shown only when LynxShip has a real measurement. Long
 Rspeedy, Gradle and Xcode operations remain visible in the event journal until
 their completion checkpoint is known; no timer-based percentage is invented.
 
+### Project-safe Android signing
+
+LynxShip does not require every project to contain a LynxShip-specific signing
+helper. During a real Android build it creates a temporary Gradle init script,
+passes it with Gradle's `--init-script` option, and removes it when the build
+finishes. The script reads only the already configured machine credentials and
+uses the Android Components `finalizeDsl` hook to configure the standard
+`release` build type. The project's Gradle files are left unchanged.
+
+This supports normal Android Gradle Plugin application projects using either
+Groovy or Kotlin DSL. Projects with custom flavor tasks, non-standard signing
+plugins, or no Android `release` build type must expose their signing contract
+explicitly; LynxShip fails with a clear diagnostic rather than producing an
+unverified artifact.
+
 ## Main commands
 
 ```text
 init                 Initialize or link a project
 doctor               Check the local toolchain and project
-dev                  Run the Rspeedy development server
+dev                  Run Rspeedy dev with Lynx Explorer QR/HMR
 preview              Preview the production bundle locally
 build create         Build, sign and upload an artifact
 build list           List build jobs
@@ -118,7 +133,8 @@ logs                 Stream native logs
 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
+storage configure   Configure Cloudflare R2
+android host init   Create a minimal official Lynx Android host
 android configure   Configure Android signing
 store configure      Configure store submission credentials
 ```
@@ -155,6 +171,51 @@ command-line tools with `sdkmanager`, accept the required licenses, set
 `android/gradlew` is executable. macOS can build both Android and iOS; Windows
 and Linux can build Android only.
 
+## Pure Lynx projects and Lynx Explorer
+
+A standard Rspeedy project can be developed without a native Android host:
+
+```bash
+lynxship dev --project-dir ./my-lynx-app
+```
+
+Rspeedy serves the development bundle and prints the QR code. Scan it with the
+official Lynx Explorer app; edits to the Lynx source are then reflected live.
+This is the supported path for projects containing `src/` and `lynx.config.*`
+but no `android/` directory.
+
+Production APK/AAB builds require a native Android host. The host is the
+Android application that initializes Lynx, creates `LynxView`, loads the bundle
+and contains the Gradle wrapper. `lynxship build` detects that requirement and
+fails clearly when `android/gradlew` is absent; `--local` only tests LynxShip's
+contract state machine and never fabricates an APK.
+
+To create a minimal host for a pure project:
+
+```bash
+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.
+
+For a pure project that targets iOS, create the native Xcode/CocoaPods host
+with:
+
+```bash
+lynxship ios host init --bundle-identifier com.example.myapp
+```
+
+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
+archiving. Xcode, CocoaPods and real Apple signing credentials are still
+required for a signed IPA; the CLI never fabricates them.
+
 ## Package layout
 
 The CLI is backed by the public `@lynxship/*` runtime packages in this

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

@@ -1 +1 @@
-{"version":3,"file":"android-build.d.ts","sourceRoot":"","sources":["../src/android-build.ts"],"names":[],"mappings":"AAWA,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,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;AAoID,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,CAyJnB"}
+{"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,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;AA0LD,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"}

package/dist/android-build.js

@@ -1,6 +1,7 @@
-import { access, copyFile, cp, mkdir, readFile, readdir, } from "node:fs/promises";
+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 { join } from "node:path";
 import { assert, sha256 } from "@lynxship/contracts";
 import { transitionBuild } from "@lynxship/build-orchestrator";
@@ -33,6 +34,56 @@ async function signingEnvironment(root) {
     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");
@@ -161,6 +212,7 @@ export async function runRealAndroidBuild(job, options) {
         quiet: options.quiet ?? false,
         onOutput: options.onEvent,
     };
+    let signingInitDirectory;
     try {
         transitionBuild(job, "uploading_source", "local Android source prepared");
         job.logs.push({
@@ -189,7 +241,10 @@ export async function runRealAndroidBuild(job, options) {
         step("Android host synchronized", 40);
         transitionBuild(job, "building", `Gradle ${artifact.task}`);
         step(`Running real Gradle task ${artifact.task}…`);
-        const gradleArgs = [artifact.task];
+        step("Applying temporary LynxShip Android signing adapter…");
+        const signingInitScript = await createSigningInitScript();
+        signingInitDirectory = signingInitScript.directory;
+        const gradleArgs = ["--init-script", signingInitScript.file, artifact.task];
         if (process.env.CI)
             gradleArgs.push("--stacktrace");
         await runProcess(wrapper, gradleArgs, {
@@ -258,4 +313,8 @@ export async function runRealAndroidBuild(job, options) {
         });
         throw error;
     }
+    finally {
+        if (signingInitDirectory)
+            await rm(signingInitDirectory, { recursive: true, force: true });
+    }
 }

package/dist/android-host.d.ts

@@ -0,0 +1,12 @@
+export interface AndroidHostOptions {
+    applicationId: string;
+    appName: string;
+}
+export interface AndroidHostResult {
+    directory: string;
+    applicationId: string;
+    packageName: string;
+}
+export declare function initializeAndroidHost(root: string, options: AndroidHostOptions): Promise<AndroidHostResult>;
+export declare function suggestedAndroidApplicationId(root: string): string;
+//# sourceMappingURL=android-host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"android-host.d.ts","sourceRoot":"","sources":["../src/android-host.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AA2BD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA6D5B;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlE"}

package/dist/android-host.js

@@ -0,0 +1,70 @@
+import { access, chmod, cp, mkdir, readFile, rename, writeFile, } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join } from "node:path";
+import { assert } from "@lynxship/contracts";
+const templateRoot = fileURLToPath(new URL("../templates/android-host/", import.meta.url));
+function packagePath(packageName) {
+    return packageName.split(".").join("/");
+}
+function validateApplicationId(applicationId) {
+    assert(/^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/.test(applicationId), "ANDROID_APPLICATION_ID_INVALID", "Android application ID must contain at least two dot-separated Java package segments, for example com.example.myapp.");
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeAppName(value) {
+    return value.replace(/[^a-zA-Z0-9 ._-]/g, "").trim() || "Lynx App";
+}
+export async function initializeAndroidHost(root, options) {
+    validateApplicationId(options.applicationId);
+    const android = join(root, "android");
+    assert(!(await exists(android)), "ANDROID_HOST_EXISTS", `The Android host already exists at ${android}. LynxShip will not overwrite it.`);
+    const packageName = options.applicationId;
+    const packageDirectory = join(android, "app", "src", "main", "java", packagePath(packageName));
+    await cp(templateRoot, android, { recursive: true, force: false });
+    await mkdir(dirname(packageDirectory), { recursive: true });
+    await rename(join(android, "app", "src", "main", "java", "template"), packageDirectory);
+    const replacements = {
+        __APPLICATION_ID__: options.applicationId,
+        __PACKAGE_NAME__: packageName,
+        __APP_NAME__: safeAppName(options.appName),
+    };
+    const textFiles = [
+        "build.gradle",
+        "settings.gradle",
+        "gradle.properties",
+        "app/build.gradle",
+        "app/src/main/AndroidManifest.xml",
+        "app/src/main/res/values/strings.xml",
+        "app/src/main/res/values/themes.xml",
+        "app/src/main/java/__PACKAGE_PATH__/LynxShipApplication.java",
+        "app/src/main/java/__PACKAGE_PATH__/MainActivity.java",
+        "app/src/main/java/__PACKAGE_PATH__/ProjectTemplateProvider.java",
+    ];
+    for (const relativeFile of textFiles) {
+        const target = join(android, relativeFile.replace("__PACKAGE_PATH__", packagePath(packageName)));
+        let content = await readFile(target, "utf8");
+        for (const [placeholder, value] of Object.entries(replacements))
+            content = content.replaceAll(placeholder, value);
+        await writeFile(target, content, "utf8");
+    }
+    if (process.platform !== "win32")
+        await chmod(join(android, "gradlew"), 0o755);
+    return {
+        directory: android,
+        applicationId: options.applicationId,
+        packageName,
+    };
+}
+export function suggestedAndroidApplicationId(root) {
+    const project = basename(root)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return `com.example.${project || "lynxapp"}`;
+}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { BuildOrchestrator } from "@lynxship/build-orchestrator";
 import { JsonRepository } from "@lynxship/db";
 import { assert, createId, sha256, } from "@lynxship/contracts";
@@ -10,6 +10,8 @@ import { createSigningKey, signManifest, } from "@lynxship/signing";
 import { AppStoreConnectApiProvider, GooglePlayApiProvider, SubmissionService, } from "@lynxship/submit";
 import { DEFAULT_CONFIG, loadConfig, platformValue, } from "./config.js";
 import { hasAndroidHost, isSupportedAndroidPlatform, runRealAndroidBuild, } from "./android-build.js";
+import { initializeAndroidHost, suggestedAndroidApplicationId, } from "./android-host.js";
+import { initializeIosHost, suggestedIosBundleIdentifier } from "./ios-host.js";
 import { hasIosHost, runRealIosBuild } from "./ios-build.js";
 import { configureAndroid, configureAppStoreConnect, configureGooglePlay, configureR2, } from "./configure.js";
 import { fetchOtaPublicKey, publishOtaRelease, rollbackOtaRelease, submitRealArtifact, } from "./remote.js";
@@ -21,6 +23,7 @@ import { inspectAutolink, requireAutolinkReady } from "./autolink.js";
 import { assertCompatibleBinaryBuild, inspectRuntimeFingerprint, } from "./runtime-fingerprint.js";
 import { inspectOtaHost } from "./ota-doctor.js";
 import { otaAssetName, otaAssetPaths } from "./ota-assets.js";
+import { prompt } from "./prompt.js";
 import { commandExists, packageManagerCommand, runProcess, runRspeedy, } from "./process-runner.js";
 const rawArgs = process.argv.slice(2);
 const args = [...rawArgs];
@@ -52,6 +55,10 @@ function flag(name, fallback = null) {
     const index = args.indexOf(name);
     return index >= 0 ? (args[index + 1] ?? "true") : fallback;
 }
+async function assertInteractivePrompt(label, fallback, optionName) {
+    assert(ui.interactive, "CLI_INTERACTIVE_REQUIRED", `Pass ${label.toLowerCase()} with ${optionName} in non-interactive mode.`);
+    return prompt(label, fallback);
+}
 function printValue(value, view) {
     if (json) {
         console.log(JSON.stringify(typeof value === "string" ? { result: value } : value));
@@ -218,7 +225,7 @@ function helpText() {
 Commands:
   init                    Initialize or link a LynxShip project
   doctor                  Check the local toolchain and project
-  dev                     Run the project's Rspeedy development server
+  dev                     Run Rspeedy dev with Lynx Explorer QR/HMR
   preview                 Preview the production Lynx bundle locally
   inspect                 Inspect Rspeedy/Rspack configuration
   profile                 Build with Rspack profiling enabled
@@ -238,6 +245,8 @@ Commands:
   rollback                Alias for update rollback
   self-host init          Generate local self-host credentials
   storage configure       Configure Cloudflare R2 and encrypted R2 credentials
+  android host init       Create a minimal official Lynx Android host
+  ios host init           Create a minimal official Lynx iOS/Xcode host
   android configure       Configure or generate encrypted Android signing credentials
   store configure         Configure Google Play or App Store Connect submission
 
@@ -286,6 +295,8 @@ Global options:
   --banner                Show the Braille LynxShip logo in a TTY
   --project-dir <path>    Use a LynxShip project from any working directory
   --project-id <id>       Project ID used by init
+  --application-id <id>   Android package/application ID for host init
+  --bundle-identifier <id> iOS bundle identifier for host init
   --library-dir <path>    Native library directory for autolink codegen
   --simulator             Install an iOS .app on a simulator with simctl
   --help                  Show this complete command reference
@@ -365,6 +376,9 @@ async function runRspeedyCommand(subcommand, environment) {
     await initializeBuildProject();
     const forwarded = forwardedToolArgs(args);
     ui.info(`Running local Rspeedy ${subcommand}…`);
+    if (subcommand === "dev") {
+        ui.info("Lynx Explorer mode: no Android or iOS native host is required. Scan the QR code printed by Rspeedy; source changes reload automatically.");
+    }
     await runRspeedy(root, subcommand, forwarded, {
         env: environment,
         quiet: json,
@@ -780,9 +794,88 @@ async function main() {
         });
         return;
     }
+    if (command === "ios") {
+        const subcommand = args.shift() ?? "host";
+        assert(subcommand === "host" && (args.shift() ?? "init") === "init", "CLI_IOS_HOST_COMMAND", "Use `lynxship ios host init` to create an iOS host.");
+        await initializeBuildProject();
+        const suggestedId = suggestedIosBundleIdentifier(root);
+        const bundleIdentifier = flag("--bundle-identifier") ??
+            (await assertInteractivePrompt("iOS bundle identifier", suggestedId, "--bundle-identifier"));
+        const result = await initializeIosHost(root, {
+            bundleIdentifier,
+            appName: basename(root),
+        });
+        ui.success(`iOS host created: ${result.directory}`);
+        printValue({
+            status: "created",
+            platform: "ios",
+            directory: result.directory,
+            bundleIdentifier: result.bundleIdentifier,
+            project: result.project,
+            scheme: result.scheme,
+            configUpdated: result.configUpdated,
+        }, {
+            title: "iOS host",
+            rows: [
+                {
+                    label: "Bundle identifier",
+                    value: result.bundleIdentifier,
+                    valueColor: "blue",
+                },
+                {
+                    label: "Xcode project",
+                    value: result.project,
+                    valueColor: "green",
+                },
+                { label: "Scheme", value: result.scheme, valueColor: "purple" },
+                {
+                    label: "CocoaPods",
+                    value: "Run pod install on macOS before the first build",
+                    valueColor: "yellow",
+                },
+            ],
+            done: "iOS host is ready. Run lynxship doctor --platform ios on macOS.",
+        });
+        return;
+    }
     if (command === "android") {
+        const subcommand = args.shift() ?? "configure";
+        if (subcommand === "host") {
+            assert((args.shift() ?? "init") === "init", "CLI_ANDROID_HOST_COMMAND", "Use `lynxship android host init` to create an Android host.");
+            await initializeBuildProject();
+            const suggestedId = suggestedAndroidApplicationId(root);
+            const applicationId = flag("--application-id") ??
+                (await assertInteractivePrompt("Android application ID", suggestedId, "--application-id"));
+            const result = await initializeAndroidHost(root, {
+                applicationId,
+                appName: basename(root),
+            });
+            ui.success(`Android host created: ${result.directory}`);
+            printValue({
+                status: "created",
+                platform: "android",
+                directory: result.directory,
+                applicationId: result.applicationId,
+            }, {
+                title: "Android host",
+                rows: [
+                    {
+                        label: "Application ID",
+                        value: result.applicationId,
+                        valueColor: "blue",
+                    },
+                    {
+                        label: "Gradle wrapper",
+                        value: join(result.directory, "gradlew"),
+                        valueColor: "green",
+                    },
+                ],
+                done: "Android host is ready. Run lynxship doctor, then lynxship build.",
+            });
+            return;
+        }
         assert(ui.interactive, "CLI_INTERACTIVE_REQUIRED", "Run `lynxship android configure` in an interactive terminal");
-        assert((args.shift() ?? "configure") === "configure", "CLI_ANDROID_COMMAND", "Only android configure is available");
+        assert(subcommand === "configure", "CLI_ANDROID_COMMAND", "Only android configure is available");
         ui.info("Configuring Android signing. Secret fields will stay invisible…");
         const result = await configureAndroid(root);
         ui.success(result.generated
@@ -1174,7 +1267,7 @@ async function main() {
             if (platform === "ios" && !realIos && !args.includes("--local"))
                 assert(false, "IOS_HOST_REQUIRED", "A macOS Xcode host is required for a real iOS build. No local fake iOS build is created.");
             if (platform === "android" && !realAndroid && !args.includes("--local"))
-                assert(false, "ANDROID_HOST_REQUIRED", "A real Android build requires an Android Gradle host. Add android/gradlew and the native Lynx host, or use --local for contract tests.");
+                assert(false, "ANDROID_HOST_REQUIRED", "This project has no Android Gradle host. For live development, run `lynxship dev` and scan the QR code with Lynx Explorer; for an APK/AAB, integrate the official Lynx Android host under `android/` (including android/gradlew). `--local` is only for contract tests and does not create an APK.");
             if (realAndroid) {
                 await runRealAndroidBuild(job, {
                     root,

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

@@ -1 +1 @@
-{"version":3,"file":"ios-build.d.ts","sourceRoot":"","sources":["../src/ios-build.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,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;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAcxE;AA0BD,wBAAsB,eAAe,CACnC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAmMnB"}
+{"version":3,"file":"ios-build.d.ts","sourceRoot":"","sources":["../src/ios-build.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAShD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,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;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAcxE;AAsDD,wBAAsB,eAAe,CACnC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAqMnB"}

package/dist/ios-build.js

@@ -23,8 +23,15 @@ export function hasIosHost(root, profile) {
 }
 function findProject(root, profile) {
     const configured = profile.ios?.workspace ?? profile.ios?.project;
-    if (configured)
-        return resolve(root, configured);
+    if (configured) {
+        const configuredPath = resolve(root, configured);
+        if (configuredPath.endsWith(".xcodeproj")) {
+            const workspace = configuredPath.replace(/\.xcodeproj$/, ".xcworkspace");
+            if (existsSync(workspace))
+                return workspace;
+        }
+        return configuredPath;
+    }
     for (const directory of ["ios", "macos"]) {
         try {
             const candidate = readdirSync(join(root, directory)).find((name) => name.endsWith(".xcworkspace") || name.endsWith(".xcodeproj"));
@@ -37,6 +44,19 @@ function findProject(root, profile) {
     }
     throw new Error("No Xcode workspace or project found under ios/ or macos/");
 }
+async function installCocoaPods(root, quiet, onEvent) {
+    const iosDirectory = join(root, "ios");
+    const podfile = join(iosDirectory, "Podfile");
+    if (!existsSync(podfile))
+        return;
+    assert(commandExists("pod"), "IOS_COCOAPODS_REQUIRED", "CocoaPods was not found. Install CocoaPods on macOS, then rerun the build.");
+    onEvent?.("Installing iOS CocoaPods dependencies…");
+    await runProcess("pod", ["install"], {
+        cwd: iosDirectory,
+        quiet,
+        onOutput: onEvent,
+    });
+}
 async function findIpa(directory) {
     const files = await readdir(directory, { withFileTypes: true });
     const ipa = files.find((file) => file.isFile() && file.name.endsWith(".ipa"));
@@ -50,6 +70,8 @@ export async function runRealIosBuild(job, options) {
     assert(commandExists("xcrun"), "IOS_XCRUN_REQUIRED", "xcrun was not found. Install Xcode command-line tools.");
     const project = findProject(options.root, options.profile);
     assert(existsSync(project), "IOS_PROJECT_REQUIRED", `Configured Xcode project was not found: ${project}`);
+    await installCocoaPods(options.root, options.quiet, options.onEvent);
+    const resolvedProject = findProject(options.root, options.profile);
     const ios = options.profile.ios ?? {};
     const scheme = ios.scheme;
     assert(scheme, "IOS_SCHEME_REQUIRED", "Configure build.<profile>.ios.scheme in lynxship.json");
@@ -57,7 +79,7 @@ export async function runRealIosBuild(job, options) {
     assert(exportOptions, "IOS_EXPORT_OPTIONS_REQUIRED", "Configure build.<profile>.ios.exportOptionsPlist for a signed IPA export");
     const exportOptionsPath = resolve(options.root, exportOptions);
     assert(existsSync(exportOptionsPath), "IOS_EXPORT_OPTIONS_REQUIRED", `Export options file was not found: ${exportOptionsPath}`);
-    const projectFlag = project.endsWith(".xcworkspace")
+    const projectFlag = resolvedProject.endsWith(".xcworkspace")
         ? "-workspace"
         : "-project";
     const configuration = ios.configuration ?? "Release";
@@ -92,7 +114,7 @@ export async function runRealIosBuild(job, options) {
         step("Preparing Xcode archive…", 10);
         await runProcess("xcodebuild", [
             projectFlag,
-            project,
+            resolvedProject,
             "-scheme",
             scheme,
             "-configuration",

package/dist/ios-host.d.ts

@@ -0,0 +1,17 @@
+export interface IosHostOptions {
+    bundleIdentifier: string;
+    appName: string;
+}
+export interface IosHostResult {
+    directory: string;
+    targetName: string;
+    bundleIdentifier: string;
+    project: string;
+    scheme: string;
+    exportOptionsPlist: string;
+    bundleScript: string;
+    configUpdated: boolean;
+}
+export declare function initializeIosHost(root: string, options: IosHostOptions): Promise<IosHostResult>;
+export declare function suggestedIosBundleIdentifier(root: string): string;
+//# sourceMappingURL=ios-host.d.ts.map

package/dist/ios-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ios-host.d.ts","sourceRoot":"","sources":["../src/ios-host.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;CACxB;AAoED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjE"}

package/dist/ios-host.js

@@ -0,0 +1,93 @@
+import { access, cp, readdir, readFile, rename, writeFile, } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { basename, join } from "node:path";
+import { assert } from "@lynxship/contracts";
+const templateRoot = fileURLToPath(new URL("../templates/ios-host/", import.meta.url));
+function validateBundleIdentifier(bundleIdentifier) {
+    assert(/^[a-zA-Z][a-zA-Z0-9-]*(\.[a-zA-Z][a-zA-Z0-9-]*)+$/.test(bundleIdentifier), "IOS_BUNDLE_IDENTIFIER_INVALID", "iOS bundle identifier must contain at least two dot-separated segments, for example com.example.myapp.");
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function targetName(value) {
+    const words = value.match(/[a-zA-Z0-9]+/g) ?? [];
+    const result = words
+        .map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+        .join("");
+    if (result && /^[A-Za-z]/.test(result))
+        return result;
+    return `LynxShip${result || "App"}`;
+}
+async function textFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await textFiles(path)));
+        else if ([".h", ".m", ".plist", ".pbxproj", ".swift", ".rb", ".mjs"].some((extension) => entry.name.endsWith(extension)) ||
+            entry.name === "Podfile")
+            files.push(path);
+    }
+    return files;
+}
+async function updateProjectConfig(root, result) {
+    const configPath = join(root, "lynxship.json");
+    if (!(await exists(configPath)))
+        return false;
+    const config = JSON.parse(await readFile(configPath, "utf8"));
+    config.build ??= {};
+    config.build.production ??= {};
+    config.build.production.ios = {
+        ...config.build.production.ios,
+        project: `ios/${result.targetName}.xcodeproj`,
+        scheme: result.scheme,
+        configuration: "Release",
+        exportOptionsPlist: "ios/ExportOptions.plist",
+        bundleScript: "ios/sync-bundle.mjs",
+    };
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return true;
+}
+export async function initializeIosHost(root, options) {
+    validateBundleIdentifier(options.bundleIdentifier);
+    const ios = join(root, "ios");
+    assert(!(await exists(ios)), "IOS_HOST_EXISTS", `The iOS host already exists at ${ios}. LynxShip will not overwrite it.`);
+    const scheme = targetName(options.appName);
+    await cp(templateRoot, ios, { recursive: true, force: false });
+    await rename(join(ios, "__IOS_TARGET_NAME__"), join(ios, scheme));
+    await rename(join(ios, "__IOS_TARGET_NAME__.xcodeproj"), join(ios, `${scheme}.xcodeproj`));
+    await rename(join(ios, scheme, "Hello-Lynx-Bridging-Header.h"), join(ios, scheme, `${scheme}-Bridging-Header.h`));
+    const files = await textFiles(ios);
+    for (const file of files) {
+        let content = await readFile(file, "utf8");
+        content = content
+            .replaceAll("test.Hello-Lynx", options.bundleIdentifier)
+            .replaceAll("Hello-Lynx", scheme);
+        await writeFile(file, content, "utf8");
+    }
+    const project = `ios/${scheme}.xcodeproj`;
+    const result = {
+        directory: ios,
+        targetName: scheme,
+        bundleIdentifier: options.bundleIdentifier,
+        project,
+        scheme,
+        exportOptionsPlist: "ios/ExportOptions.plist",
+        bundleScript: "ios/sync-bundle.mjs",
+    };
+    const configUpdated = await updateProjectConfig(root, result);
+    return { ...result, configUpdated };
+}
+export function suggestedIosBundleIdentifier(root) {
+    const project = basename(root)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return `com.example.${project || "lynxapp"}`;
+}