@lynxship/cli 0.1.6 → 0.1.7

package/README.md

@@ -120,6 +120,7 @@ doctor               Check the local toolchain and project
 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
@@ -143,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

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/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: [] };
+}

package/dist/index.js

@@ -25,6 +25,8 @@ 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";
+import { guidanceForError } from "./guidance.js";
+import { buildLynxBundle } from "./bundle-build.js";
 const rawArgs = process.argv.slice(2);
 const args = [...rawArgs];
 const ui = createCliUi(rawArgs);
@@ -178,9 +180,134 @@ async function loadState() {
     return { state, repository, builds, submissions };
 }
 async function saveState(state, repository, builds, submissions) {
-    state.builds = builds.list();
-    state.submissions = submissions.list();
-    await repository.write(state);
+    const next = stateSaveQueue.then(async () => {
+        state.builds = builds.list();
+        state.submissions = submissions.list();
+        await repository.write(state);
+    });
+    stateSaveQueue = next.catch(() => undefined);
+    await next;
+}
+let stateSaveQueue = Promise.resolve();
+async function executeBuild(options, showResult = true) {
+    const { config, profile, platform, skipUpload, wait, local, state, repository, builds, submissions, progress: sharedProgress, progressPrefix, onProgress, onEvent, skipBundleBuild, } = options;
+    await requireAutolinkReady(root, platform);
+    const runtime = await inspectRuntimeFingerprint(root, platform, config);
+    const job = await builds.create({
+        projectId: configuredProjectId(config),
+        organizationId: "local_org",
+        platform,
+        profile,
+        sourceHash: createHash("sha256").update(root).digest("hex"),
+        runtimeVersion: runtime.value,
+        runtimeInputs: runtime.inputs,
+    });
+    ui.info(`Using profile: ${profile} · platform: ${platform}`);
+    const ownsProgress = !sharedProgress;
+    const progress = sharedProgress ??
+        ui.progress(platform === "android" ? "Android build" : "iOS build");
+    const prefix = progressPrefix ? `${progressPrefix} · ` : "";
+    const reportEvent = (message) => {
+        if (onEvent)
+            onEvent(message);
+        else
+            progress.event(`${prefix}${message}`);
+    };
+    const reportProgress = (value, label) => {
+        if (onProgress)
+            onProgress(value, label);
+        else
+            progress.update(value, label ? `${prefix}${label}` : undefined);
+    };
+    try {
+        reportProgress(undefined, "Preparing build pipeline…");
+        if (wait) {
+            if (platform === "android" && !isSupportedAndroidPlatform() && !local)
+                assert(false, "ANDROID_PLATFORM_UNSUPPORTED", "Android builds are supported only on Linux, macOS and Windows.");
+            const realAndroid = platform === "android" &&
+                isSupportedAndroidPlatform() &&
+                (await hasAndroidHost(root));
+            const realIos = platform === "ios" && hasIosHost(root, config.build?.[profile]);
+            if (platform === "ios" && !realIos && !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 && !local)
+                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,
+                    profile: config.build?.[profile] ?? {},
+                    uploadArtifacts: !skipUpload,
+                    skipBundleBuild,
+                    quiet: json,
+                    onEvent: reportEvent,
+                    onProgress: reportProgress,
+                });
+            }
+            else if (realIos) {
+                await runRealIosBuild(job, {
+                    root,
+                    profile: config.build?.[profile] ?? {},
+                    uploadArtifacts: !skipUpload,
+                    skipBundleBuild,
+                    quiet: json,
+                    onEvent: reportEvent,
+                    onProgress: reportProgress,
+                });
+            }
+            else {
+                await builds.run(job.id);
+            }
+        }
+        reportProgress(100);
+        await saveState(state, repository, builds, submissions);
+    }
+    catch (error) {
+        await saveState(state, repository, builds, submissions);
+        if (error instanceof Error) {
+            Object.assign(error, { buildId: job.id });
+        }
+        throw error;
+    }
+    finally {
+        if (ownsProgress)
+            progress.stop();
+    }
+    const result = builds.get(job.id);
+    if (showResult) {
+        printValue(result, {
+            title: `${platform === "android" ? "Android" : "iOS"} build result`,
+            rows: [
+                { label: "Build ID", value: result.id, valueColor: "purple" },
+                { label: "Platform", value: result.platform, valueColor: "blue" },
+                { label: "Profile", value: result.profile, valueColor: "text" },
+                {
+                    label: "Status",
+                    value: result.state,
+                    valueColor: result.state === "success" ? "green" : "yellow",
+                },
+            ],
+            done: result.state === "success"
+                ? "Build complete. Run lynxship submit to publish."
+                : "Build queued.",
+        });
+        if (result.state === "success" && result.artifact?.url)
+            ui.downloadArtifact(result.artifact.url, result.artifact.expiresAt);
+    }
+    return result;
+}
+async function buildSharedLynxBundle() {
+    const progress = ui.progress("Shared Lynx bundle");
+    try {
+        progress.update(undefined, "Building Lynx bundle once for Android and iOS…");
+        await buildLynxBundle(root, {
+            quiet: json,
+            onOutput: (message) => progress.event(message),
+        });
+        progress.update(100, "Shared Lynx bundle ready");
+    }
+    finally {
+        progress.stop();
+    }
 }
 async function initSelfHost() {
     const directory = join(root, ".lynxship");
@@ -239,6 +366,7 @@ Commands:
   build status <id>       Show one build job
   build cancel <id>       Cancel a build job
   build retry <id>        Retry a failed build job
+  build all               Build Android and iOS on macOS
   submit                  Submit the latest successful build
   update                  Upload and publish a signed OTA update
   update rollback         Roll back an OTA channel to a previous release
@@ -251,7 +379,7 @@ Commands:
   store configure         Configure Google Play or App Store Connect submission
 
 Build options:
-  --platform <p>          Target android or ios (default: android)
+  --platform <p>          Target android, ios or all for build (default: android)
   --profile <name>        Build profile (default: production)
   --no-wait               Queue the build without executing it locally
   --no-upload              Keep the signed artifact local and skip R2 (CI verification)
@@ -578,7 +706,7 @@ async function main() {
                 name: "package-manager-lockfile",
                 ok: Boolean(lockfile),
                 status: lockfile ? "pass" : "fail",
-                value: lockfile ?? "missing · fix: npm install or pnpm install",
+                value: lockfile ?? "missing · fix: pnpm install (or npm install)",
             },
             {
                 name: "lynxship.json",
@@ -602,7 +730,7 @@ async function main() {
                         status: androidHost ? "pass" : "fail",
                         value: androidHost
                             ? "Gradle host found"
-                            : "missing · add an Android host with android/gradlew",
+                            : "missing · fix: lynxship android host init --application-id com.example.myapp",
                     },
                 ]
                 : []),
@@ -612,7 +740,7 @@ async function main() {
                 status: configuration.r2 ? "pass" : "fail",
                 value: configuration.r2
                     ? "configured"
-                    : "run lynxship storage configure",
+                    : "missing · fix: lynxship storage configure",
             },
             {
                 name: doctorPlatform === "android" ? "android-signing" : "ios-host",
@@ -627,10 +755,10 @@ async function main() {
                 value: doctorPlatform === "android"
                     ? configuration.android
                         ? "configured"
-                        : "run lynxship android configure"
+                        : "missing · fix: lynxship android configure"
                     : process.platform === "darwin" && hasIosHost(root)
                         ? "Xcode host found"
-                        : "missing · fix: use macOS with Xcode",
+                        : "missing · fix: use macOS, then lynxship ios host init --bundle-identifier com.example.myapp",
             },
             {
                 name: `lynx-autolink-${doctorPlatform}`,
@@ -1213,7 +1341,9 @@ async function main() {
     }
     assert(command === "build", "CLI_COMMAND", `Unknown command: ${command}`);
     const subcommand = args[0] && !args[0].startsWith("--") ? args.shift() : "create";
-    const platform = platformValue(flag("--platform", "android"));
+    const platformArgument = flag("--platform", "android");
+    const buildAll = subcommand === "all" || platformArgument === "all";
+    const platform = buildAll ? "android" : platformValue(platformArgument);
     const skipUpload = args.includes("--no-upload");
     await requireOperationalConfiguration(platform, { requireR2: !skipUpload });
     if (subcommand === "list") {
@@ -1237,90 +1367,114 @@ async function main() {
         printValue(job);
         return;
     }
-    assert(subcommand === "create", "CLI_BUILD_COMMAND", `Unknown build command: ${subcommand}`);
+    assert(subcommand === "create" || buildAll, "CLI_BUILD_COMMAND", `Unknown build command: ${subcommand}`);
     const config = await loadConfig(root);
     const profile = flag("--profile", "production");
-    await requireAutolinkReady(root, platform);
-    const runtime = await inspectRuntimeFingerprint(root, platform, config);
-    const job = await builds.create({
-        projectId: configuredProjectId(config),
-        organizationId: "local_org",
-        platform,
-        profile,
-        sourceHash: createHash("sha256").update(root).digest("hex"),
-        runtimeVersion: runtime.value,
-        runtimeInputs: runtime.inputs,
-    });
-    ui.info(`Using profile: ${profile} · platform: ${platform}`);
-    const progress = ui.progress("Build execution");
-    try {
-        progress.update(undefined, "Preparing build pipeline…");
-        if (!args.includes("--no-wait")) {
-            if (platform === "android" &&
-                !isSupportedAndroidPlatform() &&
-                !args.includes("--local"))
-                assert(false, "ANDROID_PLATFORM_UNSUPPORTED", "Android builds are supported only on Linux, macOS and Windows.");
-            const realAndroid = platform === "android" &&
-                isSupportedAndroidPlatform() &&
-                (await hasAndroidHost(root));
-            const realIos = platform === "ios" && hasIosHost(root, config.build?.[profile]);
-            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", "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,
-                    profile: config.build?.[profile] ?? {},
-                    uploadArtifacts: !skipUpload,
-                    quiet: json,
-                    onEvent: (message) => progress.event(message),
-                    onProgress: (value, label) => progress.update(value, label),
-                });
-            }
-            else if (realIos) {
-                await runRealIosBuild(job, {
-                    root,
-                    profile: config.build?.[profile] ?? {},
-                    uploadArtifacts: !skipUpload,
-                    quiet: json,
-                    onEvent: (message) => progress.event(message),
-                    onProgress: (value, label) => progress.update(value, label),
-                });
-            }
-            else {
-                await builds.run(job.id);
-            }
-        }
-        progress.update(100);
-        await saveState(state, repository, builds, submissions);
-    }
-    catch (error) {
-        await saveState(state, repository, builds, submissions);
-        throw error;
+    const wait = !args.includes("--no-wait");
+    const local = args.includes("--local");
+    const platforms = buildAll ? ["android", "ios"] : [platform];
+    if (buildAll && wait && !local) {
+        assert(process.platform === "darwin", "BUILD_ALL_MACOS_REQUIRED", "A real build for both Android and iOS requires macOS locally. Use `lynxship build --platform android` on Windows/Linux, or run this command on a macOS CI worker.");
+        assert(await hasAndroidHost(root), "ANDROID_HOST_REQUIRED", "The Android host is required for `lynxship build --platform all`.");
+        assert(hasIosHost(root, config.build?.[profile]), "IOS_HOST_REQUIRED", "The iOS Xcode host is required for `lynxship build --platform all`.");
     }
-    finally {
-        progress.stop();
+    if (!buildAll) {
+        await executeBuild({
+            config,
+            profile,
+            platform,
+            skipUpload,
+            wait,
+            local,
+            state,
+            repository,
+            builds,
+            submissions,
+        });
+        return;
     }
-    const result = builds.get(job.id);
-    printValue(result, {
-        title: "Build result",
-        rows: [
-            { label: "Build ID", value: result.id, valueColor: "purple" },
-            { label: "Platform", value: result.platform, valueColor: "blue" },
-            { label: "Profile", value: result.profile, valueColor: "text" },
-            {
-                label: "Status",
-                value: result.state,
-                valueColor: result.state === "success" ? "green" : "yellow",
-            },
-        ],
-        done: result.state === "success"
-            ? "Build complete. Run lynxship submit to publish."
-            : "Build queued.",
+    if (buildAll && wait && !local)
+        await buildSharedLynxBundle();
+    const progress = ui.progress("Android + iOS build");
+    const progressValues = {
+        android: 0,
+        ios: 0,
+    };
+    const progressLabels = {
+        android: "Starting Android build…",
+        ios: "Starting iOS build…",
+    };
+    const platformName = (target) => target === "android" ? "Android" : "iOS";
+    const outcomes = await Promise.allSettled(platforms.map((target) => executeBuild({
+        config,
+        profile,
+        platform: target,
+        skipUpload,
+        wait,
+        local,
+        state,
+        repository,
+        builds,
+        submissions,
+        progress,
+        progressPrefix: platformName(target),
+        skipBundleBuild: wait && !local,
+        onEvent: (message) => progress.event(`${platformName(target)} · ${message}`),
+        onProgress: (value, label) => {
+            if (value !== undefined)
+                progressValues[target] = value;
+            if (label)
+                progressLabels[target] = label;
+            const average = (progressValues.android + progressValues.ios) / platforms.length;
+            progress.update(average, `${platformName(target)} · ${progressLabels[target]}`);
+        },
+    }, false)));
+    progress.update(100, "Android and iOS builds finished");
+    progress.stop();
+    const summaryBuilds = outcomes.map((outcome, index) => {
+        if (outcome.status === "fulfilled")
+            return outcome.value;
+        const error = outcome.reason;
+        const buildId = error && typeof error === "object" && "buildId" in error
+            ? String(error.buildId)
+            : undefined;
+        const job = buildId ? builds.jobs.get(buildId) : undefined;
+        return (job ?? {
+            platform: platforms[index] ?? "android",
+            state: "failed",
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+    const failed = summaryBuilds.some((result) => result.state === "failed");
+    printValue({
+        status: failed
+            ? "failed"
+            : summaryBuilds.every((result) => result.state === "success")
+                ? "success"
+                : "queued",
+        builds: summaryBuilds,
+    }, {
+        title: "Build all result",
+        rows: summaryBuilds.map((result) => ({
+            label: platformName(result.platform),
+            value: `${result.state}${"id" in result ? ` · ${result.id}` : ""}`,
+            valueColor: result.state === "success"
+                ? "green"
+                : result.state === "failed"
+                    ? "red"
+                    : "yellow",
+        })),
+        done: failed
+            ? "At least one platform build failed. Review its events and retry that platform."
+            : "Android and iOS build jobs completed. Submit each successful artifact separately.",
     });
-    if (result.state === "success" && result.artifact?.url)
-        ui.downloadArtifact(result.artifact.url, result.artifact.expiresAt);
+    for (const result of summaryBuilds)
+        if (result.state === "success" &&
+            "artifact" in result &&
+            result.artifact?.url)
+            ui.downloadArtifact(result.artifact.url, result.artifact.expiresAt);
+    if (failed)
+        process.exitCode = 5;
 }
 function exitCode(error) {
     const code = error.code;
@@ -1341,14 +1495,23 @@ function exitCode(error) {
 void main()
     .catch((error) => {
     const message = error instanceof Error ? error.message : "Unknown error";
+    const code = error.code ?? "CLI_ERROR";
+    const nextSteps = guidanceForError(error);
     if (json) {
         console.log(JSON.stringify({
             error: message,
-            code: error.code ?? "CLI_ERROR",
+            code,
+            ...(nextSteps.commands.length > 0
+                ? {
+                    nextSteps: nextSteps.commands,
+                    ...(nextSteps.note ? { note: nextSteps.note } : {}),
+                }
+                : {}),
         }));
     }
     else {
         ui.error(message);
+        ui.nextSteps(nextSteps);
     }
     process.exitCode = exitCode(error);
 })

package/dist/ios-build.d.ts

@@ -4,6 +4,7 @@ interface IosBuildOptions {
     root: string;
     profile: BuildProfile;
     uploadArtifacts?: boolean;
+    skipBundleBuild?: boolean;
     quiet?: boolean;
     onEvent?: (message: string) => void;
     onProgress?: (value?: number, label?: string) => void;

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;AAsDD,wBAAsB,eAAe,CACnC,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAqMnB"}
+{"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;AAMhD,UAAU,eAAe;IACvB,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,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,CAuMnB"}

package/dist/ios-build.js

@@ -5,7 +5,8 @@ import { assert, sha256 } from "@lynxship/contracts";
 import { transitionBuild } from "@lynxship/build-orchestrator";
 import { loadR2, uploadR2Artifact } from "./r2.js";
 import { nativeArtifactName } from "./artifact-name.js";
-import { commandExists, packageManagerScriptCommand, runProcess, } from "./process-runner.js";
+import { commandExists, runProcess } from "./process-runner.js";
+import { buildLynxBundle } from "./bundle-build.js";
 export function hasIosHost(root, profile) {
     if (process.platform !== "darwin")
         return false;
@@ -96,13 +97,16 @@ export async function runRealIosBuild(job, options) {
             await loadR2(options.root);
         await mkdir(archiveDirectory, { recursive: true });
         transitionBuild(job, "uploading_source", "iOS source prepared");
-        step("Building Lynx bundle with Rspeedy…", 5);
-        const packageManager = packageManagerScriptCommand(options.root, "build");
-        await runProcess(packageManager.command, packageManager.args, {
-            cwd: options.root,
-            quiet: options.quiet,
-            onOutput: options.onEvent,
-        });
+        if (options.skipBundleBuild) {
+            step("Using shared Lynx bundle", 5);
+        }
+        else {
+            step("Building Lynx bundle with Rspeedy…", 5);
+            await buildLynxBundle(options.root, {
+                quiet: options.quiet,
+                onOutput: options.onEvent,
+            });
+        }
         if (ios.bundleScript) {
             step("Syncing bundle into the iOS host…", 8);
             await runProcess(process.execPath, [resolve(options.root, ios.bundleScript)], {

package/dist/ui/components.d.ts

@@ -18,6 +18,7 @@ export interface ProgressHandle {
     update(value?: number, label?: string): void;
     stop(): void;
 }
+export declare function formatEvent(message: string): string;
 export declare function createProgress(label: string, enabled: boolean): ProgressHandle;
 export interface SpinnerHandle {
     succeed(message: string): void;
@@ -32,5 +33,6 @@ export declare const pill: {
     error: (text: string) => string;
 };
 export declare function finalLine(message: string, success?: boolean): void;
+export declare function nextSteps(commands: string[], note?: string): void;
 export declare function downloadArtifact(url: string, expiresAt?: string, enabled?: boolean): void;
 //# sourceMappingURL=components.d.ts.map

package/dist/ui/components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/ui/components.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,eAAO,MAAM,GAAG;qBACG,MAAM,GAAG,IAAI;kBAGhB,MAAM,GAAG,IAAI;mBAGZ,MAAM,GAAG,IAAI;kBAGd,MAAM,GAAG,IAAI;mBAGZ,MAAM,GAAG,IAAI;CAG7B,CAAC;AAgBF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CA6C9D;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,IAAI,IAAI,CAAC;CACd;AA2FD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,cAAc,CA8DhB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,CA2BlE;AAYD,eAAO,MAAM,IAAI;oBACC,MAAM;iBACT,MAAM;iBACN,MAAM;kBACL,MAAM;CACrB,CAAC;AAEF,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI,CAE/D;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,UAAO,GACb,IAAI,CAQN"}
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/ui/components.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED,eAAO,MAAM,GAAG;qBACG,MAAM,GAAG,IAAI;kBAGhB,MAAM,GAAG,IAAI;mBAGZ,MAAM,GAAG,IAAI;kBAGd,MAAM,GAAG,IAAI;mBAGZ,MAAM,GAAG,IAAI;CAG7B,CAAC;AAgBF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CA6C9D;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,IAAI,IAAI,CAAC;CACd;AA6CD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoBnD;AAyBD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,cAAc,CAkEhB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,aAAa,CA2BlE;AAYD,eAAO,MAAM,IAAI;oBACC,MAAM;iBACT,MAAM;iBACN,MAAM;kBACL,MAAM;CACrB,CAAC;AAEF,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI,CAE/D;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAOjE;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,UAAO,GACb,IAAI,CAQN"}

package/dist/ui/components.js

@@ -10,13 +10,13 @@ export function sectionHeader(title) {
 }
 export const log = {
     success(message) {
-        console.log(`  ${c.teal("[OK]  ")} ${c.text(message)}`);
+        console.log(`  ${c.green("◆")} ${c.text(message)}`);
     },
     warn(message) {
-        console.log(`  ${c.yellow("[WARN]")} ${c.yellow(message)}`);
+        console.log(`  ${c.yellow("!")} ${c.yellow(message)}`);
     },
     error(message) {
-        console.error(`  ${c.red("[ERROR]")} ${c.red(message)}`);
+        console.error(`  ${c.red("x")} ${c.red(message)}`);
     },
     info(message) {
         console.log(`  ${c.muted(message)}`);
@@ -105,7 +105,7 @@ function eventTone(message) {
         return "step";
     return "output";
 }
-function formatEvent(message) {
+export function formatEvent(message) {
     const colors = {
         command: c.blue,
         step: c.teal,
@@ -115,17 +115,16 @@ function formatEvent(message) {
         output: c.text,
     };
     const tone = eventTone(message);
-    const tag = {
-        command: "[CMD]",
-        step: "[STEP]",
-        success: "[OK]",
-        warning: "[WARN]",
-        error: "[ERROR]",
-        output: "[LOG]",
-    }[tone];
     const normalized = message.trim().replace(/^\$\s*/, "");
-    const rail = supportsUnicode() ? "│" : "|";
-    return `  ${colors[tone](rail)} ${colors[tone](tag.padEnd(7))} ${colors[tone](normalized)}`;
+    const marker = {
+        command: supportsUnicode() ? "➜" : ">",
+        step: "-",
+        success: supportsUnicode() ? "◆" : "*",
+        warning: "!",
+        error: "x",
+        output: supportsUnicode() ? "│" : "|",
+    }[tone];
+    return `  ${colors[tone](marker)} ${colors[tone](normalized)}`;
 }
 const activeAnimations = new Set();
 let cleanupHooksInstalled = false;
@@ -162,6 +161,7 @@ export function createProgress(label, enabled) {
     let spinnerIndex = 0;
     let currentValue = 0;
     let hasMeasuredValue = false;
+    let previousTone;
     const formatPercent = (value) => `${value.toFixed(2).replace(/\.?0+$/, "")}%`;
     const bar = new cliProgress.SingleBar({
         format: `  {spinner} {stage} ${c.teal("{bar}")} ${c.muted("{percent}")}`,
@@ -191,9 +191,13 @@ export function createProgress(label, enabled) {
     const logEvent = (message) => {
         if (!bar.isActive)
             return;
+        const tone = eventTone(message);
         bar.stop();
+        if (tone === "output" && previousTone === "output")
+            console.log();
         console.log(formatEvent(message));
         bar.start(100, currentValue, payload(currentLabel));
+        previousTone = tone;
     };
     return {
         event: logEvent,
@@ -228,11 +232,11 @@ export function spin(text, enabled) {
     const untrack = trackAnimation(() => spinner.stop());
     return {
         succeed: (message) => {
-            spinner.succeed(`${c.teal("[OK]")} ${c.text(message)}`);
+            spinner.succeed(`${c.green("◆")} ${c.text(message)}`);
             untrack();
         },
         fail: (message) => {
-            spinner.fail(`${c.red("[ERROR]")} ${c.red(message)}`);
+            spinner.fail(`${c.red("x")} ${c.red(message)}`);
             untrack();
         },
         stop: () => {
@@ -255,6 +259,16 @@ export const pill = {
 export function finalLine(message, success = true) {
     console.log(`\n${success ? c.brand("◆") : c.red("◆")} ${c.text(message)}`);
 }
+export function nextSteps(commands, note) {
+    if (commands.length === 0)
+        return;
+    console.error(`\n${c.yellow("Next steps")}`);
+    commands.forEach((command, index) => {
+        console.error(`  ${c.muted(`${index + 1}.`)} ${c.teal(command)}`);
+    });
+    if (note)
+        console.error(`  ${c.muted(note)}`);
+}
 export function downloadArtifact(url, expiresAt, enabled = true) {
     if (!enabled)
         return;

package/dist/ui/index.d.ts

@@ -1,5 +1,6 @@
 import { type BoxRow, type ProgressHandle, type SpinnerHandle } from "./components.js";
 import { terminalOptions, type TerminalOptions } from "./terminal.js";
+import type { CliGuidance } from "../guidance.js";
 export declare class CliUi {
     readonly options: TerminalOptions;
     readonly interactive: boolean;
@@ -11,6 +12,7 @@ export declare class CliUi {
     info(message: string): void;
     debug(message: string): void;
     error(message: string): void;
+    nextSteps(guidance: CliGuidance): void;
     summary(title: string, rows: BoxRow[]): void;
     configurationStatus(rows: BoxRow[]): void;
     progress(label: string): ProgressHandle;
@@ -20,5 +22,5 @@ export declare class CliUi {
 }
 export declare function createCliUi(args: string[]): CliUi;
 export { terminalOptions };
-export type { BoxRow, TerminalOptions };
+export type { BoxRow, ProgressHandle, TerminalOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAEL,eAAe,EACf,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB,qBAAa,KAAK;IAChB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,IAAI,EAAE,MAAM,EAAE;IAU1B,MAAM,IAAI,IAAI;IAId,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAI5C,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKzC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAIvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAIpC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI;IAI3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;CAGxD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAEjD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAEL,eAAe,EACf,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,qBAAa,KAAK;IAChB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,IAAI,EAAE,MAAM,EAAE;IAU1B,MAAM,IAAI,IAAI;IAId,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI3B,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI9B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,SAAS,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI;IAKtC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAI5C,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKzC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAIvC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;IAIpC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI;IAI3C,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;CAGxD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAEjD;AAED,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/ui/index.js

@@ -1,4 +1,4 @@
-import { finalLine, log, sectionHeader, summaryBox, createProgress, spin, downloadArtifact, } from "./components.js";
+import { finalLine, log, sectionHeader, summaryBox, nextSteps, createProgress, spin, downloadArtifact, } from "./components.js";
 import { printBanner } from "./logo.js";
 import { setColors } from "./state.js";
 import { isInteractive, terminalOptions, } from "./terminal.js";
@@ -40,6 +40,11 @@ export class CliUi {
         if (!this.options.json)
             log.error(message);
     }
+    nextSteps(guidance) {
+        if (this.options.json || this.options.quiet)
+            return;
+        nextSteps(guidance.commands, guidance.note);
+    }
     summary(title, rows) {
         if (this.interactive)
             summaryBox(title, rows);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxship/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Build, sign, store, submit and update LynxJS applications from the terminal.",
   "type": "module",
   "license": "MIT",
@@ -70,9 +70,9 @@
     "qrcode-terminal": "0.12.0",
     "@lynxship/build-orchestrator": "0.1.0",
     "@lynxship/contracts": "0.1.0",
+    "@lynxship/signing": "0.1.0",
     "@lynxship/submit": "0.1.0",
-    "@lynxship/db": "0.1.0",
-    "@lynxship/signing": "0.1.0"
+    "@lynxship/db": "0.1.0"
   },
   "devDependencies": {
     "@types/cli-progress": "3.11.6",