@lynxship/cli 0.1.11 → 0.1.12

package/README.md

@@ -25,6 +25,33 @@ npx @lynxship/cli doctor --project-dir ./my-lynx-app
 
 The package exposes the `lynxship` executable.
 
+## Vue Lynx projects
+
+LynxShip supports projects created with the official Vue Lynx scaffold. Vue
+Lynx is integrated through the project's Rspeedy configuration, so LynxShip
+does not swap plugins or mutate `lynx.config.*`; it invokes the project's
+package-manager `build` script and then passes the generated Lynx bundle to
+the selected native or non-native target pipeline.
+
+```bash
+npm create vue-lynx@latest my-vue-lynx-app
+cd my-vue-lynx-app
+npm install
+npx @lynxship/cli@latest init
+npx @lynxship/cli@latest doctor
+npx @lynxship/cli@latest build --platform android --profile production
+```
+
+For iOS Simulator on macOS:
+
+```bash
+npx @lynxship/cli@latest build --platform ios --simulator --no-upload
+```
+
+The CLI generator itself creates ReactLynx templates by default. Use the
+official `create-vue-lynx` scaffold when Vue is required, then add LynxShip to
+that existing project with `init`.
+
 ## Requirements
 
 - Node.js 22 or 24 LTS, or Node.js 26 Current; Node.js 24 LTS is the
@@ -386,6 +413,18 @@ 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.
 
+For an iOS Simulator build, use the dedicated simulator profile:
+
+```bash
+lynxship doctor --project-dir ./my-lynx-app --platform ios --profile simulator
+lynxship build --project-dir ./my-lynx-app --platform ios --simulator --profile simulator --no-upload
+```
+
+This uses Xcode's `iphonesimulator` SDK, boots an available Simulator, creates
+and installs a local `.app`, and does not require a physical iPhone, Apple
+Distribution certificate, provisioning profile or R2 upload. Use the
+production profile only for a signed device IPA.
+
 Run the complete first-use diagnosis before building:
 
 ```bash

package/dist/config.d.ts

@@ -9,6 +9,7 @@ export interface BuildProfile {
     ios?: {
         configuration?: string;
         distribution?: string;
+        simulator?: boolean;
         workspace?: string;
         project?: string;
         scheme?: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,GAAG,CAAC,EAAE;QACJ,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE;YAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,cAAc,EAAE,cAU5B,CAAC;AAaF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,EACf,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,cAAc,CAyChB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,OAAO,CAAC,cAAc,CAAC,CAazB;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,IAAI,SAAe,GAClB,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAIjC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAOrD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,GAAG,CAAC,EAAE;QACJ,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,aAAa,GAAG,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE;QACP,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE;YAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,cAAc,EAAE,cAsB5B,CAAC;AAaF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,EACf,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,cAAc,CAyChB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,EAAE,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,OAAO,CAAC,cAAc,CAAC,CAazB;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,cAAc,EACtB,IAAI,SAAe,GAClB,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAejC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAOrD"}

package/dist/config.js

@@ -4,6 +4,18 @@ import { assert } from "@lynxship/contracts";
 export const DEFAULT_CONFIG = {
     runtimeVersion: { policy: "fingerprint" },
     build: {
+        development: {
+            distribution: "development",
+            channel: "development",
+            environment: "development",
+            ios: { configuration: "Debug" },
+        },
+        simulator: {
+            distribution: "development",
+            channel: "development",
+            environment: "development",
+            ios: { configuration: "Debug", simulator: true },
+        },
         production: {
             distribution: "store",
             channel: "production",
@@ -52,9 +64,20 @@ export async function loadConfig(root, options = {}) {
     }
 }
 export function resolveProfile(config, name = "production") {
-    const profile = config.build?.[name];
+    const profile = config.build?.[name] ?? DEFAULT_CONFIG.build?.[name];
     assert(profile, "PROFILE_NOT_FOUND", `Build profile '${name}' was not found`);
-    return { name, ...profile };
+    const inherited = DEFAULT_CONFIG.build?.[name] ?? {};
+    const productionIos = config.build?.production?.ios ?? {};
+    return {
+        name,
+        ...inherited,
+        ...profile,
+        ios: {
+            ...(inherited.ios ?? {}),
+            ...(name !== "production" ? productionIos : {}),
+            ...(profile.ios ?? {}),
+        },
+    };
 }
 export function platformValue(value) {
     assert(["android", "ios", "harmony", "web", "desktop"].includes(value), "PLATFORM_INVALID", "Platform must be android, ios, harmony, web or desktop");

package/dist/guidance.d.ts

@@ -1,6 +1,11 @@
 export interface CliGuidance {
     commands: string[];
     note?: string;
+    environment?: string;
 }
-export declare function guidanceForError(error: unknown): CliGuidance;
+export interface GuidanceContext {
+    args?: readonly string[];
+    hostPlatform?: NodeJS.Platform;
+}
+export declare function guidanceForError(error: unknown, context?: GuidanceContext): CliGuidance;
 //# sourceMappingURL=guidance.d.ts.map

package/dist/guidance.d.ts.map

@@ -1 +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;AAiXD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAiG5D"}
+{"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;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAChC;AAumBD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,eAAoB,GAC5B,WAAW,CAEb"}

package/dist/guidance.js

@@ -223,6 +223,35 @@ const guidance = {
         ],
         note: "The iOS doctor checks macOS, Xcode, xcrun, CocoaPods, Xcode settings, Apple signing identities, provisioning and export options without printing certificate contents.",
     },
+    IOS_SIMULATOR_PLATFORM: {
+        commands: [
+            "lynxship doctor --platform ios --profile simulator",
+            "lynxship build --platform ios --simulator --profile simulator --no-upload",
+        ],
+        note: "The iOS Simulator target is selected with --platform ios; Android, Web and Desktop targets cannot use this flag.",
+    },
+    IOS_SIMULATOR_RUNTIME_REQUIRED: {
+        commands: [
+            "xcode-select --install",
+            "lynxship doctor --platform ios --profile simulator",
+            "lynxship build --platform ios --simulator --profile simulator --no-upload",
+        ],
+        note: "Install an iOS Simulator runtime in Xcode > Settings > Components, then rerun the doctor.",
+    },
+    IOS_SIMULATOR_ARTIFACT_MISSING: {
+        commands: [
+            "lynxship doctor --platform ios --profile simulator",
+            "lynxship build --platform ios --simulator --profile simulator --no-upload",
+        ],
+        note: "The simulator build must produce an .app under DerivedData before it can be installed.",
+    },
+    IOS_SIMULATOR_UPLOAD_BLOCKED: {
+        commands: [
+            "lynxship build --platform ios --simulator --profile simulator --no-upload",
+            "lynxship build --platform ios --profile production",
+        ],
+        note: "Simulator .app artifacts stay local; use a signed production device build for R2 upload and distribution.",
+    },
     IOS_COCOAPODS_REQUIRED: {
         commands: ["brew install cocoapods", "lynxship build --platform ios"],
         note: "CocoaPods is required when the iOS host contains a Podfile.",
@@ -234,15 +263,20 @@ const guidance = {
         ],
     },
     IOS_SCHEME_REQUIRED: {
-        commands: ["lynxship inspect", "lynxship doctor --platform ios"],
+        commands: [
+            "lynxship inspect",
+            "lynxship doctor --platform ios --profile simulator",
+            "lynxship doctor --platform ios --profile production",
+        ],
         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",
+            "lynxship build --platform ios --simulator --profile simulator --no-upload",
         ],
-        note: "Set build.<profile>.ios.exportOptionsPlist to a valid export options file.",
+        note: "Set build.<profile>.ios.exportOptionsPlist for a device IPA; simulator .app builds do not require export options.",
     },
     IOS_DEVICE_REQUIRED: {
         commands: [
@@ -364,7 +398,7 @@ const guidance = {
         note: "Lynx Trace and Recorder are operated from Lynx DevTool Desktop after the native -dev runtime is integrated.",
     },
 };
-export function guidanceForError(error) {
+function guidanceForErrorBase(error) {
     const code = error.code;
     if (typeof code === "string" && guidance[code])
         return guidance[code];
@@ -461,3 +495,96 @@ export function guidanceForError(error) {
     }
     return { commands: [] };
 }
+function argumentValue(args, name) {
+    const index = args.indexOf(name);
+    if (index >= 0)
+        return args[index + 1];
+    const inline = args.find((value) => value.startsWith(`${name}=`));
+    return inline?.slice(name.length + 1);
+}
+function targetFromCode(code) {
+    if (!code)
+        return undefined;
+    if (code.startsWith("ANDROID_"))
+        return "android";
+    if (code.startsWith("IOS_"))
+        return "ios";
+    if (code.startsWith("HARMONY_"))
+        return "harmony";
+    if (code.startsWith("WEB_"))
+        return "web";
+    if (code.startsWith("DESKTOP_"))
+        return "desktop";
+    if (code === "BUILD_ALL_MACOS_REQUIRED")
+        return "all";
+    return undefined;
+}
+function targetFromCommand(command) {
+    const match = command.match(/--platform\s+(android|ios|harmony|web|desktop|all)/);
+    return match?.[1];
+}
+function targetCommand(platform, simulator, action) {
+    if (platform === "all")
+        return action === "doctor"
+            ? "lynxship doctor --platform android"
+            : "lynxship build --platform all --profile production";
+    if (platform === "ios" && simulator) {
+        return action === "doctor"
+            ? "lynxship doctor --platform ios --profile simulator"
+            : "lynxship build --platform ios --simulator --profile simulator --no-upload";
+    }
+    if (action === "doctor")
+        return `lynxship doctor --platform ${platform}`;
+    return `lynxship build --platform ${platform} --profile production`;
+}
+function adaptGuidance(guidance, error, context) {
+    const code = error.code;
+    const errorCode = typeof code === "string" ? code : undefined;
+    const args = context.args ?? [];
+    const requested = argumentValue(args, "--platform");
+    const target = requested ?? targetFromCode(errorCode);
+    const simulator = args.includes("--simulator");
+    let commands = guidance.commands;
+    // Generic errors must preserve the platform the developer actually asked
+    // for. The old fallback to Android was misleading for iOS/Web/Desktop jobs.
+    if (target &&
+        errorCode !== "BUILD_ALL_MACOS_REQUIRED" &&
+        ["BUILD_", "PROFILE_NOT_FOUND"].some((prefix) => errorCode?.startsWith(prefix))) {
+        commands = [
+            targetCommand(target, target === "ios" && simulator, "doctor"),
+            targetCommand(target, target === "ios" && simulator, "build"),
+        ];
+    }
+    const hostPlatform = context.hostPlatform ?? process.platform;
+    const macOnly = hostPlatform !== "darwin";
+    let requiredEnvironment;
+    commands = commands.map((command) => {
+        const commandTarget = targetFromCommand(command);
+        const isIosCommand = commandTarget === "ios" ||
+            command.includes("ios host") ||
+            command.startsWith("xcode-select") ||
+            command.startsWith("xcrun ") ||
+            command.startsWith("brew ");
+        const isAllCommand = commandTarget === "all";
+        if (macOnly && isIosCommand) {
+            requiredEnvironment = "macOS or a macOS CI runner";
+            return command;
+        }
+        if (macOnly && isAllCommand) {
+            requiredEnvironment = "macOS or a macOS CI runner";
+            return command;
+        }
+        return command;
+    });
+    const notes = guidance.note ? [guidance.note] : [];
+    if (requiredEnvironment)
+        notes.push("These commands must be run on macOS or a macOS CI runner; Android remains supported on Windows, macOS and Linux.");
+    return {
+        commands,
+        note: notes.length > 0 ? notes.join(" ") : undefined,
+        environment: requiredEnvironment,
+    };
+}
+export function guidanceForError(error, context = {}) {
+    return adaptGuidance(guidanceForErrorBase(error), error, context);
+}

package/dist/index.js

@@ -150,6 +150,12 @@ function mobilePlatformValue(value) {
 async function renderConfigurationFooter() {
     if (!ui.interactive || ui.options.quiet)
         return;
+    if (rawArgs[0] === "inspect")
+        return;
+    const profileIndex = rawArgs.indexOf("--profile");
+    const simulatorProfile = profileIndex >= 0 && rawArgs[profileIndex + 1] === "simulator";
+    if (rawArgs.includes("--simulator") || simulatorProfile)
+        return;
     const status = await readConfigurationStatus();
     const ready = status.r2 && status.android;
     if (ready)
@@ -203,14 +209,19 @@ async function saveState(state, repository, builds, submissions) {
 }
 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;
+    const { config, profile, platform, skipUpload, wait, local, state, repository, builds, submissions, progress: sharedProgress, progressPrefix, onProgress, onEvent, skipBundleBuild, simulator = false, simulatorDevice, } = options;
     if (wait && !local)
         await ensureNativeHostForBuild(platform, profile, config);
+    // Host initialization can write lynxship.json (for example, the generated
+    // iOS scheme). Always read it again before resolving the build profile so a
+    // first build uses the host that was just created in the same invocation.
+    const effectiveConfig = wait && !local ? await loadConfig(root) : config;
     if (platform === "android" || platform === "ios")
         await requireAutolinkReady(root, platform);
-    const runtime = await inspectRuntimeFingerprint(root, platform, config);
+    const runtime = await inspectRuntimeFingerprint(root, platform, effectiveConfig);
+    const resolvedBuildProfile = resolveProfile(effectiveConfig, profile);
     const job = await builds.create({
-        projectId: configuredProjectId(config),
+        projectId: configuredProjectId(effectiveConfig),
         organizationId: "local_org",
         platform,
         profile,
@@ -243,7 +254,8 @@ async function executeBuild(options, showResult = true) {
             const realAndroid = platform === "android" &&
                 isSupportedAndroidPlatform() &&
                 (await hasAndroidHost(root));
-            const realIos = platform === "ios" && hasIosHost(root, resolveProfile(config, profile));
+            const realIos = platform === "ios" &&
+                hasIosHost(root, resolveProfile(effectiveConfig, profile));
             if (platform === "ios" && !realIos && !local)
                 assert(false, "IOS_HOST_REQUIRED", "A macOS Xcode host is required for a real iOS build. Run `lynxship ios host init --bundle-identifier <id>` or pass --bundle-identifier <id> to build.");
             if (platform === "android" && !realAndroid && !local)
@@ -253,7 +265,7 @@ async function executeBuild(options, showResult = true) {
                 assert(toolchain.ok, "ANDROID_TOOLCHAIN_REQUIRED", `Android toolchain is not ready: ${formatAndroidToolchainFailure(toolchain)}`);
                 await runRealAndroidBuild(job, {
                     root,
-                    profile: config.build?.[profile] ?? {},
+                    profile: resolvedBuildProfile,
                     uploadArtifacts: !skipUpload,
                     skipBundleBuild,
                     quiet: json,
@@ -262,11 +274,13 @@ async function executeBuild(options, showResult = true) {
                 });
             }
             else if (realIos) {
-                const toolchain = await inspectIosToolchain(root, resolveProfile(config, profile));
+                const toolchain = await inspectIosToolchain(root, resolveProfile(effectiveConfig, profile), simulator ? "simulator" : "device");
                 assert(toolchain.ok, "IOS_TOOLCHAIN_REQUIRED", `iOS toolchain is not ready: ${formatIosToolchainFailure(toolchain)}`);
                 await runRealIosBuild(job, {
                     root,
-                    profile: config.build?.[profile] ?? {},
+                    profile: resolvedBuildProfile,
+                    simulator,
+                    simulatorDevice,
                     uploadArtifacts: !skipUpload,
                     skipBundleBuild,
                     quiet: json,
@@ -277,7 +291,7 @@ async function executeBuild(options, showResult = true) {
             else if (!local && platform === "web") {
                 await runRealWebBuild(job, {
                     root,
-                    profile: resolveProfile(config, profile),
+                    profile: resolveProfile(effectiveConfig, profile),
                     uploadArtifacts: !skipUpload,
                     skipBundleBuild,
                     quiet: json,
@@ -288,7 +302,7 @@ async function executeBuild(options, showResult = true) {
             else if (!local && platform === "harmony") {
                 await runRealHarmonyBuild(job, {
                     root,
-                    profile: resolveProfile(config, profile),
+                    profile: resolveProfile(effectiveConfig, profile),
                     uploadArtifacts: !skipUpload,
                     skipBundleBuild,
                     quiet: json,
@@ -299,7 +313,7 @@ async function executeBuild(options, showResult = true) {
             else if (!local && platform === "desktop") {
                 await runRealDesktopBuild(job, {
                     root,
-                    profile: resolveProfile(config, profile),
+                    profile: resolveProfile(effectiveConfig, profile),
                     uploadArtifacts: !skipUpload,
                     allowUnsigned: options.allowUnsigned,
                     skipBundleBuild,
@@ -440,9 +454,11 @@ Commands:
 
 Build options:
   --platform <p>          Target android, ios, harmony, web, desktop or all (default: android)
-  --profile <name>        Build profile (default: production)
+  --profile <name>        Build profile (default: production; simulator uses simulator)
   --no-wait               Queue the build without executing it locally
   --no-upload              Keep the artifact local and skip R2 (CI verification)
+  --simulator             Build and install an iOS Simulator .app locally
+  --device <id>           Select the iOS Simulator device for a simulator build
   --allow-unsigned         Allow an unsigned Desktop artifact only with --no-upload (local tests)
   --local                 Use the contract-only build path for tests
 
@@ -488,7 +504,7 @@ Global options:
   --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
+  --simulator             Build/install an iOS .app or install one with simctl
   --help                  Show this complete command reference
 
 Node support: Node 22/24 LTS or Node 26 Current. Use Node 24 LTS for production.`;
@@ -508,7 +524,7 @@ async function looksLikeLynxProject() {
             ...packageJson.dependencies,
             ...packageJson.devDependencies,
         };
-        return (Object.keys(dependencies).some((name) => name.startsWith("@lynx-js/")) ||
+        return (Object.keys(dependencies).some((name) => name.startsWith("@lynx-js/") || name === "vue-lynx") ||
             Object.values(packageJson.scripts ?? {}).some((script) => script.includes("rspeedy")));
     }
     catch {
@@ -885,12 +901,7 @@ async function main() {
         const nativeCredentialStore = !credentialStore.includes("owner-only");
         const androidHost = doctorPlatform === "android" ? await hasAndroidHost(root) : false;
         const doctorProfileName = flag("--profile", "production");
-        const doctorProfile = config.build?.[doctorProfileName]
-            ? resolveProfile(config, doctorProfileName)
-            : {
-                name: doctorProfileName,
-                ...(DEFAULT_CONFIG.build?.production ?? {}),
-            };
+        const doctorProfile = resolveProfile(config, doctorProfileName);
         const targetToolchain = doctorPlatform === "web"
             ? await inspectWebTarget(root, doctorProfile)
             : doctorPlatform === "harmony"
@@ -904,7 +915,9 @@ async function main() {
             ? await inspectAndroidToolchain(root)
             : undefined;
         const iosToolchain = doctorPlatform === "ios"
-            ? await inspectIosToolchain(root, doctorProfile)
+            ? await inspectIosToolchain(root, doctorProfile, doctorProfile.ios?.simulator || doctorProfileName === "simulator"
+                ? "simulator"
+                : "device")
             : undefined;
         if (androidToolchain && args.includes("--fix")) {
             await fixAndroidToolchain(root, androidToolchain, (message) => confirm(message), (line) => ui.info(line));
@@ -988,11 +1001,19 @@ async function main() {
                     }))),
             {
                 name: "cloudflare-r2",
-                ok: configuration.r2,
-                status: configuration.r2 ? "pass" : "fail",
-                value: configuration.r2
-                    ? "configured"
-                    : "missing · fix: lynxship storage configure",
+                ok: doctorPlatform === "ios" && doctorProfile.ios?.simulator
+                    ? true
+                    : configuration.r2,
+                status: doctorPlatform === "ios" && doctorProfile.ios?.simulator
+                    ? "pass"
+                    : configuration.r2
+                        ? "pass"
+                        : "fail",
+                value: doctorPlatform === "ios" && doctorProfile.ios?.simulator
+                    ? "not required for iOS Simulator"
+                    : configuration.r2
+                        ? "configured"
+                        : "missing · fix: lynxship storage configure",
             },
             ...(doctorPlatform === "android"
                 ? [
@@ -1619,7 +1640,9 @@ async function main() {
     const platformArgument = flag("--platform", "android");
     const buildAll = subcommand === "all" || platformArgument === "all";
     const platform = buildAll ? "android" : platformValue(platformArgument);
-    const skipUpload = args.includes("--no-upload");
+    const simulator = args.includes("--simulator");
+    const skipUpload = args.includes("--no-upload") || simulator;
+    assert(!simulator || platformArgument === "ios", "IOS_SIMULATOR_PLATFORM", "The --simulator option is only available with --platform ios.");
     const allowUnsigned = args.includes("--allow-unsigned");
     assert(!allowUnsigned || skipUpload, "CLI_UNSIGNED_UPLOAD_BLOCKED", "--allow-unsigned is only available with --no-upload and can never upload an unsigned Desktop artifact.");
     await requireOperationalConfiguration(platform, { requireR2: !skipUpload });
@@ -1646,7 +1669,8 @@ async function main() {
     }
     assert(subcommand === "create" || buildAll, "CLI_BUILD_COMMAND", `Unknown build command: ${subcommand}`);
     const config = await loadConfig(root);
-    const profile = flag("--profile", "production");
+    const profile = flag("--profile", simulator ? "simulator" : "production");
+    const simulatorDevice = flag("--device") ?? undefined;
     const wait = !args.includes("--no-wait");
     const local = args.includes("--local");
     const platforms = buildAll
@@ -1666,6 +1690,8 @@ async function main() {
             allowUnsigned,
             wait,
             local,
+            simulator,
+            simulatorDevice,
             state,
             repository,
             builds,
@@ -1695,6 +1721,8 @@ async function main() {
         allowUnsigned,
         wait,
         local,
+        simulator,
+        simulatorDevice,
         state,
         repository,
         builds,
@@ -1781,7 +1809,7 @@ void main()
     .catch((error) => {
     const message = error instanceof Error ? error.message : "Unknown error";
     const code = error.code ?? "CLI_ERROR";
-    const nextSteps = guidanceForError(error);
+    const nextSteps = guidanceForError(error, { args: rawArgs });
     if (json) {
         console.log(JSON.stringify({
             error: message,
@@ -1790,6 +1818,9 @@ void main()
                 ? {
                     nextSteps: nextSteps.commands,
                     ...(nextSteps.note ? { note: nextSteps.note } : {}),
+                    ...(nextSteps.environment
+                        ? { environment: nextSteps.environment }
+                        : {}),
                 }
                 : {}),
         }));

package/dist/ios-build.d.ts

@@ -4,6 +4,8 @@ interface IosBuildOptions {
     root: string;
     profile: BuildProfile;
     uploadArtifacts?: boolean;
+    simulator?: boolean;
+    simulatorDevice?: string;
     skipBundleBuild?: boolean;
     quiet?: boolean;
     onEvent?: (message: 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;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"}
+{"version":3,"file":"ios-build.d.ts","sourceRoot":"","sources":["../src/ios-build.ts"],"names":[],"mappings":"AAIA,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,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,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;AAwRD,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,CAwMnB"}

package/dist/ios-build.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { copyFile, mkdir, readdir, readFile } from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -5,8 +6,177 @@ 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, runProcess } from "./process-runner.js";
+import { captureProcess, commandExists, runProcess } from "./process-runner.js";
 import { buildLynxBundle } from "./bundle-build.js";
+async function listSimulatorDevices(root, filter) {
+    const result = await captureProcess("xcrun", ["simctl", "list", "devices", filter, "--json"], { cwd: root });
+    if (result.code !== 0)
+        return [];
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return Object.values(parsed.devices ?? {}).flat();
+    }
+    catch {
+        return [];
+    }
+}
+async function selectSimulatorDevice(root, requested) {
+    if (requested)
+        return requested;
+    const booted = (await listSimulatorDevices(root, "booted"))[0];
+    if (booted)
+        return booted.udid;
+    const available = (await listSimulatorDevices(root, "available")).find((device) => device.isAvailable !== false);
+    assert(available, "IOS_SIMULATOR_RUNTIME_REQUIRED", "No available iOS Simulator device was found. Install an iOS Simulator runtime in Xcode, then rerun the build.");
+    return available.udid;
+}
+async function ensureSimulatorBooted(root, device, onEvent, quiet) {
+    const booted = (await listSimulatorDevices(root, "booted")).some((entry) => entry.udid === device);
+    if (!booted) {
+        onEvent?.(`Booting iOS Simulator ${device}…`);
+        await runProcess("xcrun", ["simctl", "boot", device], {
+            cwd: root,
+            quiet,
+            onOutput: onEvent,
+        });
+    }
+    await runProcess("xcrun", ["simctl", "bootstatus", device, "-b"], {
+        cwd: root,
+        quiet,
+        onOutput: onEvent,
+    });
+}
+async function findSimulatorApp(root, derivedData, configuration, scheme) {
+    const products = join(derivedData, "Build", "Products", `${configuration}-iphonesimulator`);
+    const expected = join(products, `${scheme}.app`);
+    if (existsSync(expected))
+        return expected;
+    const entries = await readdir(products, { withFileTypes: true }).catch(() => []);
+    const app = entries.find((entry) => entry.isDirectory() && entry.name.endsWith(".app"));
+    assert(app, "IOS_SIMULATOR_ARTIFACT_MISSING", `Xcode did not produce a Simulator .app under ${products}`);
+    return join(products, app.name);
+}
+async function hashDirectory(directory) {
+    const hash = createHash("sha256");
+    let size = 0;
+    async function visit(current, relative) {
+        const entries = await readdir(current, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            const entryRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            const entryPath = join(current, entry.name);
+            if (entry.isDirectory()) {
+                hash.update(`dir:${entryRelative}\n`);
+                await visit(entryPath, entryRelative);
+            }
+            else {
+                const content = await readFile(entryPath);
+                size += content.length;
+                hash.update(`file:${entryRelative}:${content.length}\n`);
+                hash.update(content.toString("latin1"), "latin1");
+            }
+        }
+    }
+    await visit(directory, "");
+    return { hash: hash.digest("hex"), size };
+}
+async function runRealIosSimulatorBuild(job, options) {
+    assert(process.platform === "darwin", "IOS_MACOS_REQUIRED", "iOS Simulator builds require macOS with Xcode");
+    assert(commandExists("xcodebuild"), "IOS_XCODE_REQUIRED", "xcodebuild was not found. Install Xcode and select its command-line tools.");
+    assert(commandExists("xcrun"), "IOS_XCRUN_REQUIRED", "xcrun was not found. Install Xcode command-line tools.");
+    const project = findProject(options.root, options.profile);
+    const ios = options.profile.ios ?? {};
+    assert(ios.scheme, "IOS_SCHEME_REQUIRED", "Configure ios.scheme in the selected Simulator build profile");
+    const projectFlag = project.endsWith(".xcworkspace")
+        ? "-workspace"
+        : "-project";
+    const configuration = ios.configuration ?? "Debug";
+    const device = await selectSimulatorDevice(options.root, options.simulatorDevice);
+    await installCocoaPods(options.root, options.quiet, options.onEvent);
+    const directory = join(options.root, ".lynxship", "ios", job.id, "simulator");
+    const derivedData = join(directory, "derived-data");
+    const step = (message, progress) => {
+        options.onEvent?.(message);
+        options.onProgress?.(progress, message);
+    };
+    try {
+        assert(options.uploadArtifacts !== true, "IOS_SIMULATOR_UPLOAD_BLOCKED", "iOS Simulator .app builds stay local. Use --no-upload; simulator artifacts are not store artifacts.");
+        await mkdir(directory, { recursive: true });
+        transitionBuild(job, "uploading_source", "iOS Simulator source prepared");
+        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)], {
+                cwd: options.root,
+                quiet: options.quiet,
+                onOutput: options.onEvent,
+            });
+        }
+        transitionBuild(job, "queued", "iOS Simulator build queued locally");
+        transitionBuild(job, "provisioning", "iOS Simulator destination selected");
+        transitionBuild(job, "installing_dependencies", "iOS Simulator dependencies ready");
+        await ensureSimulatorBooted(options.root, device, options.onEvent, options.quiet);
+        step("Building iOS Simulator .app…", 15);
+        transitionBuild(job, "building", "iOS Simulator build started");
+        await runProcess("xcodebuild", [
+            projectFlag,
+            project,
+            "-scheme",
+            ios.scheme,
+            "-configuration",
+            configuration,
+            "-sdk",
+            "iphonesimulator",
+            "-destination",
+            `id=${device}`,
+            "-derivedDataPath",
+            derivedData,
+            "CODE_SIGNING_ALLOWED=NO",
+            "CODE_SIGNING_REQUIRED=NO",
+            "build",
+        ], { cwd: options.root, quiet: options.quiet, onOutput: options.onEvent });
+        const appPath = await findSimulatorApp(options.root, derivedData, configuration, ios.scheme);
+        step("Installing .app in iOS Simulator…", 75);
+        await runProcess("xcrun", ["simctl", "install", device, appPath], {
+            cwd: options.root,
+            quiet: options.quiet,
+            onOutput: options.onEvent,
+        });
+        const artifact = await hashDirectory(appPath);
+        const artifactName = nativeArtifactName("app");
+        job.attempts += 1;
+        job.artifact = {
+            name: artifactName,
+            hash: artifact.hash,
+            path: appPath,
+            size: artifact.size,
+            contentType: "application/octet-stream",
+        };
+        transitionBuild(job, "signing", "Simulator app verification completed");
+        transitionBuild(job, "uploading_artifacts", "Simulator app collected locally");
+        step(`Simulator app ready: ${artifactName}`, 100);
+        return transitionBuild(job, "success", "iOS Simulator app created");
+    }
+    catch (error) {
+        if (!["success", "failed", "canceled", "timed_out"].includes(job.state))
+            transitionBuild(job, "failed", error instanceof Error ? error.message : "iOS Simulator build failed");
+        job.logs.push({
+            level: "error",
+            message: error instanceof Error ? error.message : "iOS Simulator build failed",
+            at: new Date().toISOString(),
+        });
+        throw error;
+    }
+}
 export function hasIosHost(root, profile) {
     if (process.platform !== "darwin")
         return false;
@@ -66,6 +236,8 @@ async function findIpa(directory) {
     return join(directory, ipa.name);
 }
 export async function runRealIosBuild(job, options) {
+    if (options.simulator)
+        return runRealIosSimulatorBuild(job, options);
     assert(process.platform === "darwin", "IOS_MACOS_REQUIRED", "iOS builds require macOS with Xcode");
     assert(commandExists("xcodebuild"), "IOS_XCODE_REQUIRED", "xcodebuild was not found. Install Xcode and select its command-line tools.");
     assert(commandExists("xcrun"), "IOS_XCRUN_REQUIRED", "xcrun was not found. Install Xcode command-line tools.");

package/dist/ios-toolchain.d.ts

@@ -14,6 +14,7 @@ export interface IosToolchainReport {
     scheme?: string;
     automaticSigning: boolean;
 }
-export declare function inspectIosToolchain(root: string, profile: BuildProfile): Promise<IosToolchainReport>;
+export type IosBuildTarget = "device" | "simulator";
+export declare function inspectIosToolchain(root: string, profile: BuildProfile, target?: IosBuildTarget): Promise<IosToolchainReport>;
 export declare function formatIosToolchainFailure(report: IosToolchainReport): string;
 //# sourceMappingURL=ios-toolchain.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ios-toolchain.d.ts","sourceRoot":"","sources":["../src/ios-toolchain.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAoKD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,kBAAkB,CAAC,CA4T7B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQ5E"}
+{"version":3,"file":"ios-toolchain.d.ts","sourceRoot":"","sources":["../src/ios-toolchain.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,CAAC;AAuKpD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,cAAyB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CA2W7B;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQ5E"}

package/dist/ios-toolchain.js

@@ -86,10 +86,11 @@ async function hasValidProvisioningProfile(root, bundleIdentifier) {
     }
     return false;
 }
-async function probeProject(root, context, profile) {
+async function probeProject(root, context, profile, target) {
     if (!context.path || !context.scheme || !commandExists("xcodebuild"))
         return context;
-    const configuration = profile.ios?.configuration ?? "Release";
+    const configuration = profile.ios?.configuration ??
+        (target === "simulator" ? "Debug" : "Release");
     const settings = await captureProcess("xcodebuild", [
         context.flag,
         context.path,
@@ -124,16 +125,19 @@ async function probeCommand(command, args, cwd) {
         return false;
     }
 }
-export async function inspectIosToolchain(root, profile) {
+export async function inspectIosToolchain(root, profile, target = "device") {
     const checks = [];
     const isMac = platform() === "darwin";
     const host = findHost(root, profile);
     const hostExists = Boolean(host && existsSync(host));
     const scheme = profile.ios?.scheme;
+    const simulator = target === "simulator";
     const exportOptions = profile.ios?.exportOptionsPlist
         ? resolve(root, profile.ios.exportOptionsPlist)
         : undefined;
-    checks.push(check("ios-platform", isMac ? "pass" : "fail", isMac ? "macOS" : `${platform()} · macOS is required for an IPA`, isMac
+    checks.push(check("ios-platform", isMac ? "pass" : "fail", isMac
+        ? "macOS"
+        : `${platform()} · macOS is required for an iOS ${simulator ? "Simulator app" : "IPA"}`, isMac
         ? undefined
         : "Run the iOS build on a macOS machine or macOS CI runner"));
     if (!isMac) {
@@ -168,12 +172,12 @@ export async function inspectIosToolchain(root, profile) {
     checks.push(check("ios-host", hostExists ? "pass" : "fail", hostExists ? host : "Xcode project or workspace not found", hostExists
         ? undefined
         : "lynxship ios host init --bundle-identifier com.example.myapp"));
-    checks.push(check("ios-scheme", scheme ? "pass" : "fail", scheme ?? "missing from the production build profile", scheme ? undefined : "Set build.production.ios.scheme in lynxship.json"));
+    checks.push(check("ios-scheme", scheme ? "pass" : "fail", scheme ?? "missing from the selected build profile", scheme ? undefined : "Set ios.scheme in the selected build profile"));
     const context = await probeProject(root, {
         path: hostExists ? host : undefined,
         flag: host ? projectFlag(host) : "-project",
         scheme,
-    }, profile);
+    }, profile, target);
     const settingsOutput = context.settings
         ? commandOutput(context.settings)
         : "";
@@ -190,29 +194,40 @@ export async function inspectIosToolchain(root, profile) {
         : "Open the project in Xcode and verify the scheme is shared and buildable"));
     const automaticSigning = setting(settingsOutput, "CODE_SIGN_STYLE") === "Automatic";
     const team = setting(settingsOutput, "DEVELOPMENT_TEAM");
-    checks.push(check("apple-team", context.settings?.code !== 0 || !context.settings
-        ? "warn"
-        : team
-            ? "pass"
-            : "fail", team ?? "team not resolved from Xcode build settings", team
+    checks.push(check("apple-team", simulator
+        ? "pass"
+        : context.settings?.code !== 0 || !context.settings
+            ? "warn"
+            : team
+                ? "pass"
+                : "fail", simulator
+        ? "not required for iOS Simulator"
+        : (team ?? "team not resolved from Xcode build settings"), simulator || team
         ? undefined
         : "Select the Apple Developer Team in Xcode Signing & Capabilities"));
     const distribution = profile.distribution ?? profile.ios?.distribution ?? "store";
-    const identityResult = await (commandExists("security")
-        ? captureProcess("security", ["find-identity", "-v", "-p", "codesigning"], {
-            cwd: root,
-        })
-        : undefined);
+    const identityResult = simulator
+        ? undefined
+        : await (commandExists("security")
+            ? captureProcess("security", ["find-identity", "-v", "-p", "codesigning"], {
+                cwd: root,
+            })
+            : undefined);
     const identityOutput = identityResult ? commandOutput(identityResult) : "";
     const identityCount = Number(identityOutput.match(/(\d+) valid identities found/)?.[1] ?? 0);
     const requiredIdentity = distribution === "store" ? "Apple Distribution" : "Apple Development";
-    checks.push(check("apple-signing-identity", identityCount === 0 || !identityOutput.includes(requiredIdentity)
-        ? "fail"
-        : "pass", identityCount === 0
-        ? "no valid code-signing identity found"
-        : identityOutput.includes(requiredIdentity)
-            ? `${requiredIdentity} identity available`
-            : `${requiredIdentity} identity not found`, identityCount > 0 && identityOutput.includes(requiredIdentity)
+    checks.push(check("apple-signing-identity", simulator
+        ? "pass"
+        : identityCount === 0 || !identityOutput.includes(requiredIdentity)
+            ? "fail"
+            : "pass", simulator
+        ? "not required for iOS Simulator"
+        : identityCount === 0
+            ? "no valid code-signing identity found"
+            : identityOutput.includes(requiredIdentity)
+                ? `${requiredIdentity} identity available`
+                : `${requiredIdentity} identity not found`, simulator ||
+        (identityCount > 0 && identityOutput.includes(requiredIdentity))
         ? undefined
         : "Install or select the Apple certificate in Xcode Settings > Accounts, then rerun doctor"));
     const podfile = join(root, "ios", "Podfile");
@@ -241,40 +256,49 @@ export async function inspectIosToolchain(root, profile) {
         "development",
         "enterprise",
     ]);
-    checks.push(check("export-options", !exportOptions
-        ? "fail"
-        : !existsSync(exportOptions)
+    checks.push(check("export-options", simulator
+        ? "pass"
+        : !exportOptions
             ? "fail"
-            : !exportMethod || !supportedExportMethods.has(exportMethod)
+            : !existsSync(exportOptions)
                 ? "fail"
-                : "pass", !exportOptions
-        ? "missing from the production build profile"
-        : !existsSync(exportOptions)
-            ? `${exportOptions} not found`
-            : exportMethod && supportedExportMethods.has(exportMethod)
-                ? `method: ${exportMethod}`
-                : "method missing or invalid for an iOS export", exportOptions &&
-        existsSync(exportOptions) &&
-        exportMethod &&
-        supportedExportMethods.has(exportMethod)
+                : !exportMethod || !supportedExportMethods.has(exportMethod)
+                    ? "fail"
+                    : "pass", simulator
+        ? "not required for iOS Simulator"
+        : !exportOptions
+            ? "missing from the production build profile"
+            : !existsSync(exportOptions)
+                ? `${exportOptions} not found`
+                : exportMethod && supportedExportMethods.has(exportMethod)
+                    ? `method: ${exportMethod}`
+                    : "method missing or invalid for an iOS export", simulator ||
+        (exportOptions &&
+            existsSync(exportOptions) &&
+            exportMethod &&
+            supportedExportMethods.has(exportMethod))
         ? undefined
         : "Set build.production.ios.exportOptionsPlist to a valid ExportOptions.plist"));
     const manualProvisioning = setting(settingsOutput, "CODE_SIGN_STYLE") === "Manual" ||
         exportOptionsContent?.includes("<key>provisioningProfiles</key>") === true;
     const profilesAvailable = await hasValidProvisioningProfile(root, setting(settingsOutput, "PRODUCT_BUNDLE_IDENTIFIER"));
-    checks.push(check("ios-provisioning", manualProvisioning && !profilesAvailable
-        ? "fail"
-        : automaticSigning && !profilesAvailable
-            ? "warn"
-            : "pass", manualProvisioning && !profilesAvailable
-        ? "manual signing selected but no local provisioning profile was found"
-        : automaticSigning && !profilesAvailable
-            ? "Xcode-managed provisioning will be requested during the build"
-            : profilesAvailable
-                ? "local provisioning profile available"
-                : "not required by the detected signing mode", manualProvisioning && !profilesAvailable
-        ? "Download a matching .mobileprovision/.provisionprofile from Apple Developer and install it in Xcode"
-        : undefined));
+    checks.push(check("ios-provisioning", simulator
+        ? "pass"
+        : manualProvisioning && !profilesAvailable
+            ? "fail"
+            : automaticSigning && !profilesAvailable
+                ? "warn"
+                : "pass", simulator
+        ? "not required for iOS Simulator"
+        : manualProvisioning && !profilesAvailable
+            ? "manual signing selected but no local provisioning profile was found"
+            : automaticSigning && !profilesAvailable
+                ? "Xcode-managed provisioning will be requested during the build"
+                : profilesAvailable
+                    ? "local provisioning profile available"
+                    : "not required by the detected signing mode", simulator || !(manualProvisioning && !profilesAvailable)
+        ? undefined
+        : "Download a matching .mobileprovision/.provisionprofile from Apple Developer and install it in Xcode"));
     const simctlAvailable = await probeCommand("xcrun", ["--find", "simctl"], root);
     const devicectlAvailable = await probeCommand("xcrun", ["--find", "devicectl"], root);
     checks.push(check("ios-device-tools", simctlAvailable || devicectlAvailable ? "pass" : "warn", simctlAvailable && devicectlAvailable
@@ -286,6 +310,18 @@ export async function inspectIosToolchain(root, profile) {
                 : "simctl and devicectl unavailable", simctlAvailable || devicectlAvailable
         ? undefined
         : "Install the full Xcode toolchain, then rerun lynxship doctor --platform ios"));
+    if (simulator) {
+        const runtimeResult = await (commandExists("xcrun")
+            ? captureProcess("xcrun", ["simctl", "list", "runtimes"], { cwd: root })
+            : undefined);
+        const runtimeOutput = runtimeResult ? commandOutput(runtimeResult) : "";
+        const hasRuntime = /iOS\s+[0-9]/.test(runtimeOutput);
+        checks.push(check("ios-simulator-runtime", hasRuntime ? "pass" : "fail", hasRuntime
+            ? "iOS Simulator runtime available"
+            : "no iOS Simulator runtime found", hasRuntime
+            ? undefined
+            : "Open Xcode > Settings > Components and install an iOS Simulator runtime"));
+    }
     const failures = checks.filter((item) => item.status === "fail");
     return {
         ok: failures.length === 0,

package/dist/ui/components.d.ts

@@ -33,7 +33,7 @@ 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 nextSteps(commands: string[], note?: string, environment?: string): void;
 export declare function downloadArtifact(url: string, expiresAt?: string, enabled?: boolean): void;
 export declare function devServerQr(url: 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;AA6CD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAoBnD;AA6BD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,cAAc,CAuEhB;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;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI,CAK7D"}
+{"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;AA6BD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,cAAc,CAuEhB;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,CACvB,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,UAAO,GACb,IAAI,CAQN;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,UAAO,GAAG,IAAI,CAK7D"}

package/dist/ui/components.js

@@ -265,10 +265,12 @@ 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) {
+export function nextSteps(commands, note, environment) {
     if (commands.length === 0)
         return;
     console.error(`\n${c.yellow("Next steps")}`);
+    if (environment)
+        console.error(`  ${c.muted(`Run on ${environment}:`)}`);
     commands.forEach((command, index) => {
         console.error(`  ${c.muted(`${index + 1}.`)} ${c.teal(command)}`);
     });

package/dist/ui/index.js

@@ -43,7 +43,7 @@ export class CliUi {
     nextSteps(guidance) {
         if (this.options.json || this.options.quiet)
             return;
-        nextSteps(guidance.commands, guidance.note);
+        nextSteps(guidance.commands, guidance.note, guidance.environment);
     }
     summary(title, rows) {
         if (this.interactive)

package/package.json

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