@lynxship/cli 0.1.4 → 0.1.7

package/README.md

@@ -117,9 +117,10 @@ unverified artifact.
 ```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 all            Build Android and iOS on a macOS host
 build list           List build jobs
 build status <id>    Inspect one build job
 build cancel <id>    Cancel a build job
@@ -133,7 +134,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
 ```
@@ -142,6 +144,47 @@ Use `lynxship --help` or `lynxship <command> --help` for the complete option
 list. `--json`, `--quiet`, `--no-color` and `--non-interactive` are available
 for automation.
 
+### Actionable error guidance
+
+Recoverable errors print a `Next steps` section with the exact commands to
+run. For example, a pure LynxJS project without a native Android host reports
+the two supported paths instead of stopping at a generic Gradle error:
+
+```text
+x This project has no Android Gradle host...
+
+Next steps
+  1. lynxship dev
+  2. lynxship android host init --application-id com.example.myapp
+  3. lynxship doctor --platform android
+  4. lynxship build --platform android --profile production
+```
+
+`lynxship dev` is for Lynx Explorer and live QR/HMR development. The Android
+host command creates the native Gradle project needed for a real APK/AAB.
+`--local` remains a contract-test mode and never creates a fake artifact.
+
+To build both native platforms in one local workflow, use the multi-platform
+selector:
+
+```bash
+lynxship build --platform all --profile production
+# equivalent convenience form:
+lynxship build all --profile production
+```
+
+This builds Android and iOS concurrently after one shared Lynx bundle step.
+Their jobs, progress events and artifacts remain isolated. A real local `all`
+build requires macOS, an Android host, an iOS Xcode host and the corresponding
+signing setup. Windows and Linux can still run
+`lynxship build --platform android`; use a macOS CI worker for the iOS half.
+`--local` can exercise both contract paths without creating APK or IPA files.
+
+The same guidance covers missing R2 or signing setup, Android SDK tools,
+Autolink/codegen, iOS Xcode/CocoaPods, device tools, store credentials and
+OTA compatibility. In automation, use `--json`; failures include a
+machine-readable `nextSteps` array and optional `note` field.
+
 ## OTA rollback
 
 ```bash
@@ -170,6 +213,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

@@ -4,6 +4,7 @@ interface AndroidBuildOptions {
     root: string;
     profile: BuildProfile;
     uploadArtifacts?: boolean;
+    skipBundleBuild?: boolean;
     quiet?: boolean;
     onStep?: (message: string) => void;
     onEvent?: (message: string) => void;

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,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"}
+{"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,CA+JnB"}

package/dist/android-build.js

@@ -8,18 +8,8 @@ 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, packageManagerScriptCommand, runProcess, } from "./process-runner.js";
-async function projectBuildCommand(root) {
-    try {
-        const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
-        if (packageJson.scripts?.["build:mobile"])
-            return ["run", "build:mobile"];
-    }
-    catch {
-        // The package manager will report the useful project error below.
-    }
-    return ["run", "build"];
-}
+import { commandExists, executableExists, runProcess, } from "./process-runner.js";
+import { buildLynxBundle } from "./bundle-build.js";
 async function signingEnvironment(root) {
     const android = (await loadCredentials(root)).android;
     const values = {
@@ -220,13 +210,16 @@ export async function runRealAndroidBuild(job, options) {
             message: "rspeedy:build",
             at: new Date().toISOString(),
         });
-        step("Building Lynx bundle with Rspeedy…");
-        const packageManager = packageManagerScriptCommand(options.root, (await projectBuildCommand(options.root))[1] ?? "build");
-        await runProcess(packageManager.command, packageManager.args, {
-            cwd: options.root,
-            env: environment,
-            ...processOptions,
-        });
+        if (options.skipBundleBuild) {
+            step("Using shared Lynx bundle", 20);
+        }
+        else {
+            step("Building Lynx bundle with Rspeedy…");
+            await buildLynxBundle(options.root, {
+                env: environment,
+                ...processOptions,
+            });
+        }
         step("Rspeedy bundle ready", 20);
         transitionBuild(job, "queued", "Android build queued locally");
         step("Build queued…");

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/bundle-build.d.ts

@@ -0,0 +1,7 @@
+export interface BundleBuildOptions {
+    env?: NodeJS.ProcessEnv;
+    quiet?: boolean;
+    onOutput?: (line: string) => void;
+}
+export declare function buildLynxBundle(root: string, options?: BundleBuildOptions): Promise<void>;
+//# sourceMappingURL=bundle-build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-build.d.ts","sourceRoot":"","sources":["../src/bundle-build.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAcD,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/bundle-build.js

@@ -0,0 +1,24 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { packageManagerScriptCommand, runProcess } from "./process-runner.js";
+async function resolveBundleScript(root) {
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        if (manifest.scripts?.["build:mobile"])
+            return "build:mobile";
+    }
+    catch {
+        // The package manager will report the useful project error below.
+    }
+    return "build";
+}
+export async function buildLynxBundle(root, options = {}) {
+    const script = await resolveBundleScript(root);
+    const packageManager = packageManagerScriptCommand(root, script);
+    await runProcess(packageManager.command, packageManager.args, {
+        cwd: root,
+        env: options.env,
+        quiet: options.quiet,
+        onOutput: options.onOutput,
+    });
+}

package/dist/guidance.d.ts

@@ -0,0 +1,6 @@
+export interface CliGuidance {
+    commands: string[];
+    note?: string;
+}
+export declare function guidanceForError(error: unknown): CliGuidance;
+//# sourceMappingURL=guidance.d.ts.map

package/dist/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoQD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAiG5D"}

package/dist/guidance.js

@@ -0,0 +1,354 @@
+const guidance = {
+    CLI_PROJECT_REQUIRED: {
+        commands: ["lynxship init", "lynxship doctor"],
+        note: "Run them from the project directory or add --project-dir <path>.",
+    },
+    CLI_PROJECT_ID_REQUIRED: {
+        commands: ["lynxship init", "lynxship doctor"],
+    },
+    CLI_R2_REQUIRED: {
+        commands: ["lynxship storage configure", "lynxship doctor"],
+    },
+    CLI_R2_ACCOUNT_ID: {
+        commands: ["lynxship storage configure"],
+        note: "Use the 32-character Cloudflare account ID.",
+    },
+    CLI_R2_BUCKET: {
+        commands: ["lynxship storage configure"],
+        note: "Use a lowercase R2 bucket name with no spaces or underscores.",
+    },
+    CLI_R2_ENDPOINT: {
+        commands: ["lynxship storage configure"],
+        note: "Use the HTTPS S3 endpoint for the same Cloudflare account.",
+    },
+    CLI_R2_EXPIRY: {
+        commands: ["lynxship storage configure"],
+        note: "Choose a download lifetime between 1 second and 7 days.",
+    },
+    CLI_R2_CREDENTIALS: {
+        commands: ["lynxship storage configure", "lynxship doctor"],
+    },
+    BUILD_SIGNING_REQUIRED: {
+        commands: [
+            "lynxship android configure",
+            "lynxship doctor --platform android",
+        ],
+        note: "An existing .jks/.keystore is supported; production builds need a real release key.",
+    },
+    LYNXSHIP_KEYSTORE_PATH: {
+        commands: ["lynxship android configure"],
+    },
+    LYNXSHIP_KEY_ALIAS: {
+        commands: ["lynxship android configure"],
+    },
+    LYNXSHIP_KEYSTORE_PASSWORD: {
+        commands: ["lynxship android configure"],
+    },
+    LYNXSHIP_KEY_PASSWORD: {
+        commands: ["lynxship android configure"],
+    },
+    ANDROID_HOST_REQUIRED: {
+        commands: [
+            "lynxship dev",
+            "lynxship android host init --application-id com.example.myapp",
+            "lynxship doctor --platform android",
+            "lynxship build --platform android --profile production",
+        ],
+        note: "Use dev for Lynx Explorer. The host init path is required for a real APK/AAB; --local is only a contract test.",
+    },
+    ANDROID_HOST_EXISTS: {
+        commands: ["lynxship doctor --platform android"],
+        note: "Review the existing android/ host instead of overwriting it.",
+    },
+    ANDROID_APPLICATION_ID_INVALID: {
+        commands: ["lynxship android host init --application-id com.example.myapp"],
+        note: "Use a reverse-domain Android application ID, for example com.company.app.",
+    },
+    ANDROID_PLATFORM_UNSUPPORTED: {
+        commands: ["lynxship doctor --platform android"],
+        note: "Android builds run on Windows, macOS or Linux. Use macOS for iOS builds.",
+    },
+    BUILD_ALL_MACOS_REQUIRED: {
+        commands: [
+            "lynxship build --platform android --profile production",
+            "lynxship build --platform all --profile production --no-upload",
+        ],
+        note: "Run the all-platform command on a macOS machine or macOS CI worker; the second command is for CI verification.",
+    },
+    ANDROID_APKSIGNER_REQUIRED: {
+        commands: [
+            "lynxship doctor --platform android",
+            'sdkmanager "build-tools;latest"',
+        ],
+        note: "Ensure Android SDK Build Tools are installed and available through ANDROID_HOME or ANDROID_SDK_ROOT.",
+    },
+    ANDROID_JARSIGNER_REQUIRED: {
+        commands: ["lynxship doctor --platform android", "java -version"],
+        note: "Install JDK 17 or newer and make sure jarsigner is on PATH.",
+    },
+    ANDROID_ADB_REQUIRED: {
+        commands: ["lynxship doctor --platform android", "adb devices"],
+        note: "Install Android SDK Platform-Tools and connect or start a device.",
+    },
+    LYNX_BUNDLE_MISSING: {
+        commands: ["lynxship dev", "lynxship build --platform android"],
+        note: "Build the Lynx bundle with the project's configured package manager.",
+    },
+    IOS_HOST_REQUIRED: {
+        commands: [
+            "lynxship dev",
+            "lynxship ios host init --bundle-identifier com.example.myapp",
+            "lynxship doctor --platform ios",
+            "lynxship build --platform ios --profile production",
+        ],
+        note: "Use dev for Lynx Explorer. A real IPA requires macOS, Xcode and an iOS host.",
+    },
+    IOS_HOST_EXISTS: {
+        commands: ["lynxship doctor --platform ios"],
+        note: "Review the existing ios/ host instead of overwriting it.",
+    },
+    IOS_BUNDLE_IDENTIFIER_INVALID: {
+        commands: ["lynxship ios host init --bundle-identifier com.example.myapp"],
+        note: "Use a reverse-domain bundle identifier, for example com.company.app.",
+    },
+    IOS_MACOS_REQUIRED: {
+        commands: ["lynxship doctor --platform ios"],
+        note: "Run real iOS commands on macOS. Windows and Linux cannot produce an IPA.",
+    },
+    IOS_XCODE_REQUIRED: {
+        commands: ["xcode-select --install", "lynxship doctor --platform ios"],
+        note: "Install Xcode from the Mac App Store and select its command-line tools.",
+    },
+    IOS_XCRUN_REQUIRED: {
+        commands: ["xcode-select --install", "lynxship doctor --platform ios"],
+    },
+    IOS_COCOAPODS_REQUIRED: {
+        commands: ["brew install cocoapods", "lynxship build --platform ios"],
+        note: "CocoaPods is required when the iOS host contains a Podfile.",
+    },
+    IOS_PROJECT_REQUIRED: {
+        commands: [
+            "lynxship ios host init --bundle-identifier com.example.myapp",
+            "lynxship doctor --platform ios",
+        ],
+    },
+    IOS_SCHEME_REQUIRED: {
+        commands: ["lynxship inspect", "lynxship doctor --platform ios"],
+        note: "Set build.<profile>.ios.scheme in lynxship.json.",
+    },
+    IOS_EXPORT_OPTIONS_REQUIRED: {
+        commands: [
+            "lynxship ios host init --bundle-identifier com.example.myapp",
+            "lynxship doctor --platform ios",
+        ],
+        note: "Set build.<profile>.ios.exportOptionsPlist to a valid export options file.",
+    },
+    IOS_DEVICE_REQUIRED: {
+        commands: [
+            "xcrun devicectl list devices",
+            "lynxship run --platform ios --device <device-id>",
+        ],
+    },
+    IOS_DEVICE_LOGS_UNSUPPORTED: {
+        commands: [
+            "xcrun simctl list devices",
+            "lynxship logs --platform ios --device <simulator-id>",
+        ],
+    },
+    DEVICE_ARTIFACT_REQUIRED: {
+        commands: [
+            "lynxship build --platform android --profile production",
+            "lynxship run --platform android --artifact <path-to-apk>",
+        ],
+    },
+    LYNX_CODEGEN_SCRIPT_REQUIRED: {
+        commands: [
+            "lynxship autolink check --platform android",
+            "lynxship autolink codegen --library-dir <native-library>",
+        ],
+        note: "The native library must expose its official codegen script.",
+    },
+    LYNX_AUTOLINK_ANDROID_REQUIRED: {
+        commands: [
+            "lynxship autolink check --platform android",
+            "lynxship autolink codegen --library-dir <native-library>",
+        ],
+    },
+    LYNX_AUTOLINK_IOS_REQUIRED: {
+        commands: [
+            "lynxship autolink check --platform ios",
+            "lynxship autolink codegen --library-dir <native-library>",
+        ],
+    },
+    OTA_HOST_INTEGRATION_REQUIRED: {
+        commands: [
+            "lynxship ota doctor --platform android",
+            "lynxship ota doctor --platform ios",
+        ],
+        note: "Integrate the LynxShip OTA client in the native host before publishing updates.",
+    },
+    OTA_NATIVE_CHANGE_REQUIRED: {
+        commands: [
+            "lynxship ota doctor --platform android",
+            "lynxship build --platform android --profile production",
+            "lynxship update --platform android --bundle dist/main.lynx.bundle",
+        ],
+        note: "Native changes require a new compatible binary before an OTA release.",
+    },
+    OTA_BUNDLE_REQUIRED: {
+        commands: [
+            "lynxship build --platform android --profile production",
+            "lynxship update --platform android --bundle dist/main.lynx.bundle",
+        ],
+    },
+    BUILD_REQUIRED: {
+        commands: ["lynxship build --platform android --profile production"],
+    },
+    STORE_ARTIFACT_REQUIRED: {
+        commands: [
+            "lynxship build --platform android --profile production",
+            "lynxship submit --platform android --latest",
+        ],
+    },
+    STORE_SUBMISSION_REQUIRED: {
+        commands: [
+            "lynxship store configure --platform android",
+            "lynxship submit --platform android --latest",
+        ],
+    },
+    RELEASE_NOT_FOUND: {
+        commands: [
+            "lynxship update --platform android",
+            "lynxship update rollback --help",
+        ],
+    },
+    ROLLBACK_RELEASE_REQUIRED: {
+        commands: [
+            'lynxship update rollback --platform android --release-id <release-id> --reason "reason"',
+        ],
+    },
+    ROLLBACK_REASON_REQUIRED: {
+        commands: [
+            'lynxship update rollback --platform android --release-id <release-id> --reason "reason"',
+        ],
+    },
+    CLI_INTERACTIVE_REQUIRED: {
+        commands: ["lynxship <command>"],
+        note: "Run without --non-interactive, or provide the documented CI environment variables.",
+    },
+    PROFILE_NOT_FOUND: {
+        commands: ["lynxship inspect", "lynxship build --profile production"],
+        note: "Use a profile declared under build in lynxship.json.",
+    },
+    PLATFORM_INVALID: {
+        commands: [
+            "lynxship build --platform android",
+            "lynxship build --platform ios",
+            "lynxship build --platform all",
+        ],
+    },
+    IOS_SIGNATURE_INVALID: {
+        commands: [
+            "lynxship doctor --platform ios",
+            "lynxship build --platform ios --profile production",
+        ],
+        note: "Check the Apple certificate, provisioning profile, team and export options.",
+    },
+};
+export function guidanceForError(error) {
+    const code = error.code;
+    if (typeof code === "string" && guidance[code])
+        return guidance[code];
+    if (typeof code === "string") {
+        if (code.startsWith("SUBMISSION_") || code.startsWith("AUTH_")) {
+            return {
+                commands: [
+                    "lynxship store configure --platform android",
+                    "lynxship submit --platform android --latest",
+                ],
+                note: "Check the provider credentials and required account permissions.",
+            };
+        }
+        if (code.startsWith("OTA_")) {
+            return {
+                commands: [
+                    "lynxship ota doctor --platform android",
+                    "lynxship update --platform android --bundle dist/main.lynx.bundle",
+                ],
+            };
+        }
+        if (code.startsWith("CONFIG_")) {
+            return {
+                commands: ["lynxship init", "lynxship doctor"],
+            };
+        }
+        if (code.startsWith("BUILD_")) {
+            return {
+                commands: [
+                    "lynxship doctor --platform android",
+                    "lynxship build --platform android --profile production",
+                ],
+                note: "Inspect the first failed build event before retrying.",
+            };
+        }
+        if (code.startsWith("STORE_")) {
+            return {
+                commands: [
+                    "lynxship store configure --platform android",
+                    "lynxship submit --platform android --latest",
+                ],
+            };
+        }
+        if (code.startsWith("IOS_")) {
+            return {
+                commands: [
+                    "lynxship doctor --platform ios",
+                    "lynxship build --platform ios --profile production",
+                ],
+            };
+        }
+        if (code.startsWith("ANDROID_")) {
+            return {
+                commands: [
+                    "lynxship doctor --platform android",
+                    "lynxship build --platform android --profile production",
+                ],
+            };
+        }
+        if (code.startsWith("CLI_")) {
+            return { commands: ["lynxship --help"] };
+        }
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (/pnpm|npm|yarn|corepack|not recognized|not found/i.test(message)) {
+        return {
+            commands: ["corepack enable", "pnpm install", "lynxship doctor"],
+            note: "Use the package manager selected by the project's lockfile.",
+        };
+    }
+    if (/ENOENT|no such file or directory/i.test(message)) {
+        return {
+            commands: ["lynxship init", "lynxship doctor"],
+            note: "Check that the project directory and required configuration files exist.",
+        };
+    }
+    if (/gradle|gradlew|android sdk|build tools/i.test(message)) {
+        return {
+            commands: [
+                "lynxship doctor --platform android",
+                "lynxship build --platform android --profile production",
+            ],
+            note: "Check JDK 17, Android SDK, Build Tools and the project Gradle wrapper.",
+        };
+    }
+    if (/xcode|xcrun|cocoapods|pod install/i.test(message)) {
+        return {
+            commands: [
+                "lynxship doctor --platform ios",
+                "lynxship build --platform ios",
+            ],
+            note: "Check macOS, Xcode command-line tools and CocoaPods.",
+        };
+    }
+    return { commands: [] };
+}