@akanjs/cli 2.4.0-rc.8 → 2.4.0-rc.9

package/index.js

@@ -776,6 +776,13 @@ var normalizeStringList = (values) => {
   const normalized = values?.map((value) => value.trim()).filter(Boolean) ?? [];
   return normalized.length > 0 ? [...new Set(normalized)] : undefined;
 };
+var sanitizeAppIdSegment = (value) => {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  if (!cleaned)
+    return "app";
+  return /^[a-z]/.test(cleaned) ? cleaned : `app${cleaned}`;
+};
+var deriveDefaultAppId = (orgName, appName) => `com.${sanitizeAppIdSegment(orgName)}.${sanitizeAppIdSegment(appName)}`;
 var normalizeDeepLinkDomain = (domain) => {
   const normalized = domain.trim();
   if (!normalized)
@@ -816,6 +823,7 @@ class AkanAppConfig {
   i18n;
   publicEnv;
   mobile;
+  hasMobileConfig;
   secrets;
   baseDevEnv;
   libs;
@@ -846,6 +854,7 @@ class AkanAppConfig {
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = config?.publicEnv ?? [];
     this.secrets = config?.secrets ?? [];
+    this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
@@ -856,7 +865,7 @@ class AkanAppConfig {
       ...rawMobile
     } = mobile ?? {};
     const appName = rawMobile.appName ?? this.app.name;
-    const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
+    const appId = rawMobile.appId ?? deriveDefaultAppId(this.baseDevEnv.repoName, this.app.name);
     const version = rawMobile.version ?? "0.0.1";
     const buildNum = rawMobile.buildNum ?? 1;
     const defaultTargetName = this.#defaultMobileTargetName(rawTargets);
@@ -4322,6 +4331,8 @@ var BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
+var BUILDER_RECOVERY_BASE_DELAY_MS = 2000;
+var BUILDER_RECOVERY_MAX_DELAY_MS = 60000;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var NON_SOURCE_EXT_RE = /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
 var SERVER_SUFFIXES = [".service.ts", ".document.ts"];
@@ -4398,6 +4409,43 @@ var mergeBackendRestartReasons = (current, next) => ({
 });
 var shouldReplaceLastGoodMessage = (current, next) => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
 var shouldQueueBuildStatusReplay = (backendReady, pendingReplayCount) => !backendReady || pendingReplayCount > 0;
+var hasBuildFailureForGeneration = (statusByPhase, generation) => {
+  if (typeof generation !== "number")
+    return false;
+  for (const status of statusByPhase.values()) {
+    if (!status.ok && status.generation === generation)
+      return true;
+  }
+  return false;
+};
+var mergeDevPlans = (current, next) => {
+  if (!current)
+    return next;
+  if (!next)
+    return current;
+  const reasonByFile = { ...current.reasonByFile };
+  for (const [file, reasons] of Object.entries(next.reasonByFile)) {
+    reasonByFile[file] = [...new Set([...reasonByFile[file] ?? [], ...reasons])].sort();
+  }
+  return {
+    generation: Math.max(current.generation, next.generation),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generatedFiles: [...new Set([...current.generatedFiles, ...next.generatedFiles])].sort(),
+    roles: [...new Set([...current.roles, ...next.roles])].sort(),
+    actions: [...new Set([...current.actions, ...next.actions])].sort(),
+    reasonByFile
+  };
+};
+var mergeInvalidateMessages = (current, next) => {
+  const generation = Math.max(generationValue(current.generation), generationValue(next.generation));
+  return {
+    type: "invalidate",
+    kinds: [...new Set([...current.kinds, ...next.kinds])].sort(),
+    files: [...new Set([...current.files, ...next.files])].sort(),
+    generation: generation >= 0 ? generation : undefined,
+    devPlan: mergeDevPlans(current.devPlan, next.devPlan)
+  };
+};
 var buildStatusReplaySequence = (pendingReplay, latestByPhase) => [...pendingReplay, ...latestByPhase.values()];
 
 class BackendImportGraph {
@@ -4520,8 +4568,12 @@ class AkanAppHost {
   #restartTimer = null;
   #backendRecoveryTimer = null;
   #backendRecoveryAttempts = 0;
+  #backendGaveUp = false;
   #backendLifecycleState = "stopped";
   #pendingRestartReason = null;
+  #pendingRecycle = null;
+  #builderRecoveryTimer = null;
+  #builderRecoveryAttempts = 0;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
   #backendStderrTail = [];
@@ -4559,6 +4611,10 @@ class AkanAppHost {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
     }
+    if (this.#builderRecoveryTimer) {
+      clearTimeout(this.#builderRecoveryTimer);
+      this.#builderRecoveryTimer = null;
+    }
     await this.#stopBackend();
     this.#stopBuilder();
     return this;
@@ -4574,6 +4630,7 @@ class AkanAppHost {
   }
   #startBackend(startStatus = null) {
     this.#backendStartStatus = startStatus;
+    this.#backendGaveUp = false;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
     this.#backendStderrTail = [];
@@ -4765,7 +4822,8 @@ class AkanAppHost {
     if (this.#backendRecoveryTimer || this.#backend)
       return;
     if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
-      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for an edit or a green build to retry.`;
+      this.#backendGaveUp = true;
       this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
       this.logger.error(`[backend-recovery] ${message}`);
       if (this.#backendStderrTail.length > 0) {
@@ -4812,6 +4870,7 @@ ${this.#backendStderrTail.join(`
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
+      this.#reviveBackendAfterGreenBuild(message.data);
       return;
     }
     if (message.type === "pages-updated")
@@ -4826,19 +4885,25 @@ ${this.#backendStderrTail.join(`
   }
   async#handleInvalidate(message) {
     this.#logDevPlan(message);
-    if (shouldRestartDevHostByDevPlan(message)) {
-      try {
-        await this.#restartDevHost(message);
-      } catch (err) {
-        this.#recordDevHostRestartFailure(message, err, "Config");
+    const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
+    const pending = this.#pendingRecycle;
+    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || pending && message.kinds.includes("code")) {
+      const refreshConfig = wantsDevHostRestart || (pending?.refreshConfig ?? false);
+      const merged = pending ? mergeInvalidateMessages(pending.message, message) : message;
+      const generation = message.devPlan?.generation ?? message.generation;
+      if (hasBuildFailureForGeneration(this.#buildStatusByPhase, generation)) {
+        this.#deferRecycle(merged, { refreshConfig, generation });
+        return;
       }
-      return;
-    }
-    if (shouldRestartBuilderByDevPlan(message)) {
+      this.#pendingRecycle = null;
       try {
-        await this.#restartDevChildren(message);
+        if (refreshConfig)
+          await this.#restartDevHost(merged);
+        else
+          await this.#restartDevChildren(merged);
       } catch (err) {
-        this.#recordDevHostRestartFailure(message, err, "Runtime metadata");
+        this.#recordDevHostRestartFailure(merged, err, refreshConfig ? "Config" : "Runtime metadata");
+        this.#resurrectDevChildren(merged);
       }
       return;
     }
@@ -4848,6 +4913,70 @@ ${this.#backendStderrTail.join(`
     }
     this.#sendToBackend(message);
   }
+  #deferRecycle(message, { refreshConfig, generation }) {
+    this.#pendingRecycle = { message, refreshConfig };
+    const kind = refreshConfig ? "Config" : "Runtime metadata";
+    this.logger.warn(`[dev-host] ${kind.toLowerCase()} restart deferred generation=${generation ?? "(unknown)"}; keeping the running dev server until the build error is fixed`);
+    const status = {
+      generation: generation ?? this.#nextBackendBuildStatusGeneration(),
+      phase: "scan",
+      ok: false,
+      files: message.files,
+      message: `${kind} change is on hold while the build is failing; it will apply automatically once the error is fixed.`
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+  }
+  #resurrectDevChildren(message) {
+    const generation = message.devPlan?.generation ?? message.generation;
+    if (!this.#backend)
+      this.#startBackend({ generation, files: message.files });
+    this.#scheduleBuilderRecovery({ generation, files: message.files });
+  }
+  #scheduleBuilderRecovery(reason) {
+    if (this.#builderRecoveryTimer || this.#builder)
+      return;
+    const attempt = this.#builderRecoveryAttempts;
+    const delay = Math.min(BUILDER_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BUILDER_RECOVERY_MAX_DELAY_MS);
+    this.#builderRecoveryAttempts = attempt + 1;
+    this.logger.warn(`[builder-recovery] builder is down; retrying start in ${delay}ms (attempt ${this.#builderRecoveryAttempts})`);
+    this.#builderRecoveryTimer = setTimeout(() => {
+      this.#builderRecoveryTimer = null;
+      if (this.#builder)
+        return;
+      this.#recoverBuilder(reason);
+    }, delay);
+  }
+  async#recoverBuilder(reason) {
+    try {
+      await this.#startBuilder();
+    } catch (err) {
+      this.logger.warn(`[builder-recovery] builder start failed: ${err instanceof Error ? err.message : String(err)}`);
+      this.#scheduleBuilderRecovery(reason);
+      return;
+    }
+    this.#builderRecoveryAttempts = 0;
+    this.logger.info("[builder-recovery] builder recovered");
+    const status = {
+      generation: reason.generation ?? this.#nextBackendBuildStatusGeneration(),
+      phase: "scan",
+      ok: true,
+      files: reason.files,
+      message: "Builder recovered"
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+    if (!this.#backend && !this.#backendRecoveryTimer) {
+      this.#startBackend({ generation: reason.generation, files: reason.files });
+    }
+  }
+  #reviveBackendAfterGreenBuild(status) {
+    if (!status.ok || !this.#backendGaveUp || this.#backend || this.#backendRecoveryTimer)
+      return;
+    this.logger.info(`[backend-recovery] build went green (generation=${status.generation}); retrying backend`);
+    this.#backendRecoveryAttempts = 0;
+    this.#startBackend({ generation: status.generation, files: status.files });
+  }
   async#restartDevChildren(message) {
     const generation = message.devPlan?.generation ?? message.generation;
     this.logger.warn(`[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`);
@@ -4868,6 +4997,11 @@ ${this.#backendStderrTail.join(`
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
     }
+    if (this.#builderRecoveryTimer) {
+      clearTimeout(this.#builderRecoveryTimer);
+      this.#builderRecoveryTimer = null;
+    }
+    this.#builderRecoveryAttempts = 0;
     this.#pendingRestartReason = null;
     this.#lastGoodFrontend = {};
     this.#buildStatusByPhase.clear();
@@ -4905,7 +5039,7 @@ ${this.#backendStderrTail.join(`
       phase: "scan",
       ok: false,
       files: message.files,
-      message: `${kind} change requires restarting \`akan start\` to apply: ${detail}`
+      message: `${kind} change failed to apply; recovering the dev server automatically: ${detail}`
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
@@ -14075,6 +14209,7 @@ var resolveMobilePath = (target, pathname) => {
 };
 var targetHtmlFilename = (target) => target.basePath?.replace(/^\/+|\/+$/g, "") ? `${target.basePath.replace(/^\/+|\/+$/g, "")}.html` : "index.html";
 // pkgs/@akanjs/devkit/capacitorApp.ts
+var SWIFTUICORE_MIN_IOS_MAJOR = 18;
 var iosNativeBlockedEnvKeys = new Set([
   "AR",
   "AS",
@@ -14112,17 +14247,56 @@ async function writeRootCapacitorConfig(appRoot, content) {
   await clearRootCapacitorConfigs(appRoot);
   await Bun.write(path42.join(appRoot, "capacitor.config.json"), content);
 }
-var getLocalIP = () => {
-  const interfaces = os.networkInterfaces();
-  for (const iface of Object.values(interfaces)) {
-    if (!iface)
-      continue;
-    for (const alias of iface) {
-      if (alias.family === "IPv4" && !alias.internal)
-        return alias.address;
+var virtualInterfacePrefixes = [
+  "bridge",
+  "utun",
+  "llw",
+  "awdl",
+  "ap",
+  "vmnet",
+  "vnic",
+  "tap",
+  "tun",
+  "docker",
+  "veth",
+  "vboxnet",
+  "gif",
+  "stf"
+];
+var physicalInterfacePrefixes = ["en", "eth", "wlan", "wlp", "enp", "eno", "wlo"];
+var isPrivateLanIpv4 = (address) => {
+  if (address.startsWith("10.") || address.startsWith("192.168."))
+    return true;
+  const secondOctet = Number(address.match(/^172\.(\d+)\./)?.[1]);
+  return Number.isFinite(secondOctet) && secondOctet >= 16 && secondOctet <= 31;
+};
+var scoreDevHostCandidate = (name, address) => {
+  const lowerName = name.toLowerCase();
+  let score = 0;
+  if (address.startsWith("169.254."))
+    score -= 1000;
+  if (virtualInterfacePrefixes.some((prefix) => lowerName.startsWith(prefix)))
+    score -= 100;
+  else if (physicalInterfacePrefixes.some((prefix) => lowerName.startsWith(prefix)))
+    score += 100;
+  if (isPrivateLanIpv4(address))
+    score += 10;
+  return score;
+};
+var selectLocalDevHost = (interfaces, { override } = {}) => {
+  const candidates = [];
+  for (const [name, aliases] of Object.entries(interfaces)) {
+    for (const alias of aliases ?? []) {
+      if (alias.family !== "IPv4" || alias.internal)
+        continue;
+      candidates.push({ name, address: alias.address });
     }
   }
-  return "127.0.0.1";
+  const trimmedOverride = override?.trim();
+  if (trimmedOverride)
+    return { host: trimmedOverride, source: "override", candidates };
+  const [best] = [...candidates].sort((a, b) => scoreDevHostCandidate(b.name, b.address) - scoreDevHostCandidate(a.name, a.address) || a.name.localeCompare(b.name) || a.address.localeCompare(b.address));
+  return best ? { host: best.address, source: "detected", candidates } : { host: "127.0.0.1", source: "loopback", candidates };
 };
 var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var asString = (value) => typeof value === "string" ? value : undefined;
@@ -14142,6 +14316,30 @@ var dedupeIosRunTargets = (targets) => {
   }
   return [...byKey.values()];
 };
+var formatSimctlRuntime = (key) => {
+  if (!key)
+    return;
+  if (/^(iOS|watchOS|tvOS|visionOS)\s+[\d.]+$/i.test(key))
+    return key;
+  const match = key.match(/(iOS|watchOS|tvOS|visionOS)-(\d+)(?:-(\d+))?/i);
+  if (!match)
+    return;
+  return `${match[1]} ${match[2]}${match[3] ? `.${match[3]}` : ""}`;
+};
+var parseIosRuntimeMajor = (runtime) => {
+  const major = runtime?.match(/(\d+)/)?.[1];
+  if (major === undefined)
+    return;
+  const parsed = Number.parseInt(major, 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+};
+var iosRunTargetRank = (target) => {
+  const state = target.state?.toLowerCase() ?? "";
+  const ready = state.includes("booted") || state.includes("connected") || state.includes("available") ? 1000 : 0;
+  const device = target.kind === "device" ? 500 : 0;
+  return ready + device + (parseIosRuntimeMajor(target.runtime) ?? 0);
+};
+var sortIosRunTargets = (targets) => [...targets].sort((a, b) => iosRunTargetRank(b) - iosRunTargetRank(a) || a.name.localeCompare(b.name));
 function walkRecords(value, visit) {
   if (Array.isArray(value)) {
     for (const item of value)
@@ -14194,21 +14392,38 @@ function parseSimctlDevices(output) {
   try {
     const json = JSON.parse(output);
     const devices = json.devices ?? {};
-    return Object.values(devices).flat().filter(isRecord2).flatMap((device) => {
-      const id = firstString(device.udid, device.UDID, device.identifier);
-      const name = firstString(device.name, device.displayName);
-      const isAvailable = device.isAvailable !== false && device.availabilityError === undefined;
-      if (!id || !name || !isAvailable)
-        return [];
-      return [{ id, name, kind: "simulator", state: asString(device.state) }];
+    return Object.entries(devices).flatMap(([runtimeKey, list]) => {
+      const runtime = formatSimctlRuntime(runtimeKey);
+      return (Array.isArray(list) ? list : []).filter(isRecord2).flatMap((device) => {
+        const id = firstString(device.udid, device.UDID, device.identifier);
+        const name = firstString(device.name, device.displayName);
+        const isAvailable = device.isAvailable !== false && device.availabilityError === undefined;
+        if (!id || !name || !isAvailable)
+          return [];
+        return [
+          {
+            id,
+            name,
+            kind: "simulator",
+            state: asString(device.state),
+            runtime: runtime ?? formatSimctlRuntime(asString(device.runtimeIdentifier))
+          }
+        ];
+      });
     });
   } catch {
     const targets = [];
+    let runtime;
     for (const line of output.split(/\r?\n/)) {
+      const header = line.match(/^--\s*(.+?)\s*--\s*$/);
+      if (header) {
+        runtime = formatSimctlRuntime(header[1]);
+        continue;
+      }
       const match = line.match(/^\s*(.+?)\s+\(([0-9A-Fa-f-]{20,})\)\s+\(([^)]+)\)/);
       if (!match)
         continue;
-      targets.push({ id: match[2], name: match[1].trim(), kind: "simulator", state: match[3] });
+      targets.push({ id: match[2], name: match[1].trim(), kind: "simulator", state: match[3], runtime });
     }
     return targets;
   }
@@ -14243,6 +14458,13 @@ function buildIosNativeRunCommand({
 }
 function classifyIosRunFailure(log) {
   const lower = log.toLowerCase();
+  if (lower.includes("swiftuicore") && (lower.includes("library not loaded") || lower.includes("library missing") || lower.includes("dyld"))) {
+    return {
+      kind: "simulator-runtime",
+      title: "App crashed loading SwiftUICore \u2014 the iOS runtime is too old.",
+      detail: `The build links SwiftUICore, which only exists on iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+. Rerun on an iOS ${SWIFTUICORE_MIN_IOS_MAJOR} or newer simulator/device (pass --device to pick one non-interactively).`
+    };
+  }
   if (lower.includes("unknown argument: '-index-store-path'") || lower.includes("compiler was not recognized")) {
     return {
       kind: "compiler-toolchain",
@@ -14340,6 +14562,21 @@ function formatIosRunFailureMessage(input2) {
 function sanitizeIosNativeRunEnv(env) {
   return Object.fromEntries(Object.entries(env).filter(([key]) => !iosNativeBlockedEnvKeys.has(key)));
 }
+var PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp"
+];
+var placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+var isPlaceholderAppId = (appId) => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized)
+    return true;
+  if (PLACEHOLDER_APP_IDS.includes(normalized))
+    return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};
 var androidReleaseSigningKeys = [
   "MYAPP_RELEASE_STORE_FILE",
   "MYAPP_RELEASE_STORE_PASSWORD",
@@ -14588,23 +14825,37 @@ class CapacitorApp {
     await this.#runIosPhysicalDevice({ operation, env, runTarget, noAllowProvisioningUpdates });
   }
   async#selectIosRunTarget(deviceId) {
-    const targets = await this.#loadIosRunTargets();
+    const targets = sortIosRunTargets(await this.#loadIosRunTargets());
     if (deviceId) {
-      const found = targets.find((target) => target.id === deviceId);
-      if (!found)
-        throw new Error(`iOS run target '${deviceId}' was not found.`);
+      const needle = deviceId.toLowerCase();
+      const found = targets.find((target) => target.id === deviceId) ?? targets.find((target) => target.name.toLowerCase() === needle) ?? targets.find((target) => target.name.toLowerCase().includes(needle) || target.id.toLowerCase().includes(needle) || (target.runtime?.toLowerCase().includes(needle) ?? false));
+      if (!found) {
+        const available = targets.map((t) => `${t.name}${t.runtime ? ` (${t.runtime})` : ""}`).join(", ") || "none";
+        throw new Error(`iOS run target '${deviceId}' was not found. Available: ${available}`);
+      }
+      this.#warnIfLegacySimulatorRuntime(found);
       return found;
     }
     if (targets.length === 0) {
       throw new Error("No iOS run targets found. Open Simulator or connect an iPhone, then retry.");
     }
-    return await select2({
+    const selected = await select2({
       message: "Select iOS run target",
       choices: targets.map((target) => ({
-        name: `[${target.kind}] ${target.name}${target.state ? ` (${target.state})` : ""}`,
+        name: `[${target.kind}] ${target.name}${target.runtime ? ` \u2014 ${target.runtime}` : ""}${target.state ? ` (${target.state})` : ""}`,
         value: target
       }))
     });
+    this.#warnIfLegacySimulatorRuntime(selected);
+    return selected;
+  }
+  #warnIfLegacySimulatorRuntime(target) {
+    if (target.kind !== "simulator")
+      return;
+    const major = parseIosRuntimeMajor(target.runtime);
+    if (major === undefined || major >= SWIFTUICORE_MIN_IOS_MAJOR)
+      return;
+    this.app.logger.warn(`Selected simulator runs ${target.runtime ?? "an older iOS"}. Recent SDK builds link SwiftUICore and require iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+; if the app crashes at launch with a "Library not loaded: SwiftUICore" dyld error, pick an iOS ${SWIFTUICORE_MIN_IOS_MAJOR}+ simulator instead.`);
   }
   async#loadIosRunTargets() {
     const devices = await this.#loadPhysicalIosDevices();
@@ -14851,7 +15102,13 @@ ${error.message}`;
   }
   async#writeCapacitorConfig({ operation }, commandEnv) {
     await mkdir11(this.targetRoot, { recursive: true });
-    const localIp = operation === "local" ? getLocalIP() : undefined;
+    let localIp;
+    if (operation === "local") {
+      const override = commandEnv.AKAN_PUBLIC_CLIENT_HOST ?? process.env.AKAN_PUBLIC_CLIENT_HOST;
+      const resolution = selectLocalDevHost(os.networkInterfaces(), { override });
+      localIp = resolution.host;
+      this.#logDevHostResolution(resolution, commandEnv);
+    }
     const config = materializeCapacitorConfig(this.target, {
       operation,
       localIp,
@@ -14862,6 +15119,17 @@ ${error.message}`;
     await Bun.write(path42.join(this.targetRoot, "capacitor.config.json"), content);
     return content;
   }
+  #logDevHostResolution(resolution, commandEnv) {
+    this.app.log(`Mobile live-reload server: ${this.#localCsrUrl(resolution.host, commandEnv)}`);
+    if (resolution.source === "override")
+      return;
+    const suspicious = resolution.host === "127.0.0.1" || resolution.host.startsWith("169.254.");
+    const alternatives = resolution.candidates.filter((candidate) => candidate.address !== resolution.host);
+    if (!suspicious && alternatives.length === 0)
+      return;
+    const alternativeText = alternatives.length ? ` Other interfaces: ${alternatives.map((candidate) => `${candidate.address} (${candidate.name})`).join(", ")}.` : "";
+    this.app.logger.warn(`A physical device must reach ${resolution.host} on your LAN.${suspicious ? " That address looks non-routable." : ""}${alternativeText} If the device shows a blank screen, pin the right one with AKAN_PUBLIC_CLIENT_HOST=<ip>.`);
+  }
   async#prepareTargetAssets() {
     if (!this.target.assets)
       return;
@@ -17536,6 +17804,7 @@ try {
     operation = "local",
     env = "local",
     target,
+    device,
     regenerate = false,
     noAllowProvisioningUpdates = false
   } = {}) {
@@ -17544,7 +17813,7 @@ try {
       await this.#buildMobileCsr(app, env);
     await this.#runMobileTargets(targets, async (mobileTarget2) => {
       const capacitorApp2 = new CapacitorApp(app, mobileTarget2.config);
-      await capacitorApp2.runIos({ operation, env, regenerate, noAllowProvisioningUpdates });
+      await capacitorApp2.runIos({ operation, env, regenerate, noAllowProvisioningUpdates, iosDeviceId: device });
       if (open)
         await capacitorApp2.openIos();
     });
@@ -17935,6 +18204,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     env = "local",
     write = true,
     target,
+    device,
     regenerate = false,
     noAllowProvisioningUpdates = false
   } = {}) {
@@ -17947,6 +18217,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
       operation,
       env,
       target,
+      device,
       regenerate,
       noAllowProvisioningUpdates
     });
@@ -18081,7 +18352,10 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
   }).option("open", Boolean, { desc: "open ios simulator", default: false }).option("release", Boolean, { desc: "release mode", default: false }).option("write", Boolean, { desc: "write code generation", default: true }).option("regenerate", Boolean, { flag: "g", desc: "delete and regenerate native project", default: false }).option("noAllowProvisioningUpdates", Boolean, {
     desc: "disable automatic iOS provisioning updates for physical devices",
     default: false
-  }).exec(async function(app, target2, env, open, release, write, regenerate, noAllowProvisioningUpdates) {
+  }).option("device", String, {
+    desc: "run target to select non-interactively: udid, device name, or runtime (e.g. 'iPhone 16' or 'iOS 18')",
+    default: ""
+  }).exec(async function(app, target2, env, open, release, write, regenerate, noAllowProvisioningUpdates, device) {
     await this.applicationScript.startIos(app, {
       target: target2,
       env: asMobileEnv(env),
@@ -18089,7 +18363,8 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
       operation: release ? "release" : "local",
       write,
       regenerate,
-      noAllowProvisioningUpdates
+      noAllowProvisioningUpdates,
+      device: device || undefined
     });
   }),
   startAndroid: target({ short: true, desc: "Start Android app in emulator or device" }).with(App).option("target", String, mobileTargetOption).option("env", String, {
@@ -21450,10 +21725,49 @@ class ContextRunner extends runner("context") {
     });
     return format === "json" ? jsonText(context) : AkanContextAnalyzer.renderMarkdown(context, { module });
   }
-  async doctor(workspace, { format = "text", strict = false } = {}) {
+  async doctor(workspace, {
+    format = "text",
+    strict = false,
+    ios = false
+  } = {}) {
+    if (ios)
+      return await this.#doctorIos(workspace, format);
     const result = await AkanContextAnalyzer.doctor(workspace, { strict });
     return format === "json" ? jsonText(result) : renderDoctorText(result);
   }
+  async#doctorIos(workspace, format) {
+    const appNames = await workspace.getApps();
+    const diagnostics = [];
+    for (const appName of appNames) {
+      const app = AppExecutor.from(workspace, appName);
+      const config = await app.getConfig();
+      if (!config.hasMobileConfig)
+        continue;
+      for (const { name, config: target } of await getMobileTargets(app)) {
+        if (!isPlaceholderAppId(target.appId))
+          continue;
+        diagnostics.push({
+          severity: "warning",
+          code: "mobile-appid-placeholder",
+          path: `apps/${appName}/akan.config.ts`,
+          message: `Mobile target '${name}' uses placeholder bundle id '${target.appId}'. Apple's developer portal almost always already claims it, so signing to a physical device fails with "cannot be registered to your development team". Set a unique mobile.appId (reverse-DNS of your org).`
+        });
+      }
+    }
+    const status = diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed";
+    if (format === "json")
+      return jsonText({ schemaVersion: 1, kind: "ios", status, diagnostics });
+    const lines = [`Akan iOS diagnostics for ${workspace.repoName}`];
+    if (diagnostics.length === 0)
+      lines.push("  No mobile configuration issues found.");
+    else
+      for (const diagnostic of diagnostics) {
+        lines.push(`  [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);
+        lines.push(`    ${diagnostic.path}`);
+      }
+    return lines.join(`
+`);
+  }
   async getGuidelineResource(name) {
     return await Prompter.getInstruction(name);
   }
@@ -21850,8 +22164,11 @@ class ContextCommand extends command("context", [ContextScript], ({ public: targ
     desc: "output format",
     default: "text",
     enum: ["text", "json"]
-  }).option("strict", Boolean, { desc: "treat recommended conventions as errors", default: false }).with(Workspace).exec(async function(format, strict, workspace) {
-    await this.contextScript.doctor(workspace, { format, strict });
+  }).option("strict", Boolean, { desc: "treat recommended conventions as errors", default: false }).option("ios", Boolean, {
+    desc: "report iOS/mobile config diagnostics (placeholder bundle ids, etc.)",
+    default: false
+  }).with(Workspace).exec(async function(format, strict, ios, workspace) {
+    await this.contextScript.doctor(workspace, { format, strict, ios });
   }),
   mcpInstall: target({ desc: "Install the Akan MCP server config for Cursor, Claude Code, and Codex" }).arg("target", String, { desc: "cursor, claude, codex, or all", nullable: true }).option("force", Boolean, { desc: "overwrite an existing Akan MCP server entry", default: false }).option("mode", String, {
     desc: "MCP permission mode",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.4.0-rc.8",
+  "version": "2.4.0-rc.9",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.0-rc.8",
+    "akanjs": "2.4.0-rc.9",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",