@livx.cc/appwrap 0.42.3 → 0.43.0

package/src/cli.ts

@@ -2,16 +2,17 @@
 /**
  * appwrap CLI v0 — scaffold a native wrapper around a built PWA.
  *
- *   appwrap init [--config <path>] [--out native]   # from the PWA project dir
+ *   appwrap init [--config <path>] [--out native] [--ci]   # from the PWA project dir; --ci also scaffolds GH Actions workflows
  *   appwrap sync [--config <path>] [--out native]   # re-copy PWA dist into the wrapper
  *
  * Config (TS preferred, JSON fallback) — probed in order: appwrap.config.ts → .js → appwrap.json.
  * Shape: { id, name, version, entry?, backgroundColor?, statusBarStyle?, pwaDist }. See config.ts.
  */
 import { execFileSync, spawn } from 'child_process';
+import { createHash } from 'crypto';
 import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { networkInterfaces, tmpdir } from 'os';
-import { dirname, join, resolve } from 'path';
+import { delimiter as pathDelimiter, dirname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -21,6 +22,10 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
 import { unknownConfigKeys } from './config';
+import { createHash } from 'crypto';
+import { buildInfoPlist, buildMacEntitlements, deriveDesktopConfig, parseMacProfile, resolveCargoPath, stampTauriConf } from './desktop';
+import type { DesktopShellConfig } from './desktop';
+import { APPLE_ICON_GRID_SCALE, makeDockRuntimeIcon } from './icon';
 import {
   androidScreenOrientation,
   applyBuildNumberFlag,
@@ -43,6 +48,8 @@ interface ExecError extends Error {
   stdout?: string | Buffer;
   stderr?: string | Buffer;
   status?: number | null;
+  signal?: string | null;
+  code?: string | number | null;
 }
 const asExecError = (e: unknown): ExecError => (e ?? {}) as ExecError;
 /** Combined stdout+stderr captured on an exec failure (empty string when none). */
@@ -50,6 +57,12 @@ const execErrText = (e: unknown): string => {
   const err = asExecError(e);
   return `${err.stdout ?? ''}${err.stderr ?? ''}`;
 };
+/** True when an exec failed because OUR process-level `timeout:` killed it (SIGTERM / ETIMEDOUT) —
+ * the signature of a child that hung silently, as a wedged CoreDeviceService makes devicectl do. */
+const isTimeoutKill = (e: unknown): boolean => {
+  const err = asExecError(e);
+  return err.signal === 'SIGTERM' || err.code === 'ETIMEDOUT' || /ETIMEDOUT/.test(String(err.message ?? ''));
+};
 
 /**
  * Resolved monotonic build number (iOS CFBundleVersion / Android versionCode). Thin env wrapper over
@@ -90,6 +103,9 @@ function resolveAssetRoot(rel: string): string {
 }
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
+/** Desktop (Tauri chassis) template — phase-0, macOS-only. Its own generated wrapper (`native-desktop/`)
+ * is disposable, like `native/`; the template stays canonical (edit here, regenerate propagates). */
+const DESKTOP_TEMPLATE_DIR = resolveAssetRoot('runtime-desktop');
 
 /** This CLI's own published version — used to pin the `bunx @livx.cc/appwrap@^x.y.z` invocations the
  * emitted workflow runs. Pinning to THIS version's floor means CI fails LOUDLY ("version not found")
@@ -1122,8 +1138,15 @@ function findMaskableSource(cwd: string, cfg: AppwrapConfig): string | null {
 /** Square-resize/probe abstraction over `sips` (macOS) or ImageMagick (`magick` v7 / `convert` v6),
  * so icon generation works on Linux/CI too — not just macOS. Returns null if neither tool is present. */
 function imageRasterizer(): { width: (src: string) => number; resize: (src: string, px: number, dest: string) => void } | null {
+  // Probe by RUNNING the tool, not by PATH lookup. `which`/`Bun.which` both consult process.env.PATH,
+  // which can be undefined under some Bun launch contexts (observed: PATH unset yet `sips` still execs
+  // fine via the OS default path) → PATH-based detection returned false and silently shipped the
+  // NativeScript template icon. execFileSync resolves + runs the binary the same way the actual
+  // resize/probe calls below do, so detection and invocation always agree. ENOENT = absent; any other
+  // failure (e.g. bad flag, nonzero exit) means the binary IS present.
   const has = (cmd: string) => {
-    try { execFileSync('which', [cmd], { stdio: 'ignore' }); return true; } catch { return false; }
+    try { execFileSync(cmd, ['--version'], { stdio: 'ignore' }); return true; }
+    catch (e) { return (e as { code?: string }).code !== 'ENOENT'; }
   };
   if (has('sips')) {
     return {
@@ -1414,22 +1437,25 @@ export function isFrameworkRepo(root: string): boolean {
   return existsSync(join(root, 'packages/appwrap-cli/src/cli.ts'));
 }
 
-/** Emit CI scaffolding (GH Actions → git repo root, fastlane → native/).
+/** Emit CI scaffolding (GH Actions → git repo root ONLY with --ci, fastlane → native/).
+ * Writing `.github/workflows` into a consumer repo is a repo-level side effect (it can shadow or
+ * clash with the project's own CI), so it is OPT-IN via `appwrap init --ci` — never implicit.
  * GH workflows are never overwritten (users may customize them). The fastlane lane IS appwrap-managed
  * (the release recipe, not for hand-editing — see AGENTS.md), so it is RE-EMITTED on `--force` to keep
  * the recipe current after a framework upgrade; without --force it's still first-time-only. */
-function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force = false): void {
+function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force = false, withWorkflows = false): void {
   if (!existsSync(CI_TEMPLATE_DIR)) return;
   const repoRoot = gitRoot(cwd);
   // GitHub only reads `.github/workflows` at the REPO ROOT — in a monorepo, writing it under the
   // package cwd (e.g. packages/app/.github) is dead config and regenerates a stray workflow each init.
   // [from, to, overwritable]
   const targets: Array<[string, string, boolean]> = [[join(CI_TEMPLATE_DIR, 'fastlane'), join(outDir, 'fastlane'), force]];
-  // …but if the repo root IS the appwrap framework itself (in-repo example), DON'T scaffold consumer
-  // workflows into the framework's .github — that's the stray-workflow-each-init bug.
-  if (isFrameworkRepo(repoRoot)) {
+  // Even with --ci: if the repo root IS the appwrap framework itself (in-repo example), DON'T scaffold
+  // consumer workflows into the framework's .github — that's the stray-workflow-each-init bug.
+  const scaffoldWorkflows = withWorkflows && !isFrameworkRepo(repoRoot);
+  if (withWorkflows && !scaffoldWorkflows) {
     console.log('  ci   ← GH Actions scaffold skipped (inside the appwrap framework repo — manages its own CI)');
-  } else {
+  } else if (scaffoldWorkflows) {
     targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows'), false]);
   }
   for (const [from, to, overwrite] of targets) {
@@ -1439,7 +1465,7 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
   // Pin the emitted workflow's `bunx @livx.cc/appwrap@^x.y.z` to THIS CLI's version floor, so a CI run
   // using a freshly-emitted workflow can't silently resolve an older published build that lacks the
   // `init`/`release` commands (it would 404 loudly instead). Idempotent: re-init finds no placeholder.
-  if (!isFrameworkRepo(repoRoot)) {
+  if (scaffoldWorkflows) {
     const wf = join(repoRoot, '.github/workflows/appwrap-release-ios.yml');
     if (existsSync(wf)) writeFileSync(wf, readFileSync(wf, 'utf8').replaceAll('__APPWRAP_VERSION__', CLI_VERSION));
   }
@@ -1454,9 +1480,9 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
       .replaceAll('__TEAM_ID__', cfg.teamId ?? '');
     writeFileSync(p, stamped);
   }
-  const ci = isFrameworkRepo(repoRoot)
-    ? '  ci   ← fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers'
-    : '  ci   ← GH Actions (.github/workflows) + fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers';
+  const ci = scaffoldWorkflows
+    ? '  ci   ← GH Actions (.github/workflows) + fastlane (native/fastlane, signing stamped) — see secrets contract in workflow headers'
+    : '  ci   ← fastlane (native/fastlane, signing stamped) — GH Actions workflows are opt-in: `appwrap init --ci`';
   console.log(ci);
 }
 
@@ -1577,7 +1603,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
   regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
-  copyCiTemplates(cwd, outDir, cfg, 'force' in flags); // GH workflows: first-time only; fastlane lane: re-emit on --force
+  copyCiTemplates(cwd, outDir, cfg, 'force' in flags, 'ci' in flags); // GH workflows: opt-in (--ci), first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
   applyOverrides(cwd, outDir, cfg); // escape hatch — last, so custom native code wins
   stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
@@ -1670,10 +1696,11 @@ function openInspector(cfg: AppwrapConfig, flags: Record<string, string>, platfo
  */
 async function dev(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
+  if (platform === 'desktop') return devDesktop(cwd, flags);
   const sim = 'sim' in flags || positionals[1] === 'sim';
   const wantDebug = 'debug' in flags;
   if (platform !== 'ios' && platform !== 'android') {
-    console.error('Usage: appwrap dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--device <id|ip[:port]>] [--url <devserver>|--port <p>]');
+    console.error('Usage: appwrap dev <ios|android|desktop> [--sim] [--detached] [--debug] [--wifi] [--device <id|ip[:port]>] [--url <devserver>|--port <p>]');
     process.exit(1);
   }
   const cfg = await loadConfig(cwd, flags);
@@ -1929,10 +1956,423 @@ async function watchAndSync(cwd: string, flags: Record<string, string>, outDir:
  * Android signing comes from env (APPWRAP_ANDROID_KEYSTORE[_PASSWORD|_ALIAS|_ALIAS_PASSWORD]) — secrets
  * never live in the appwrap config. iOS distribution signing/upload is the fastlane release lane's job (the
  * cicd templates); `--release` here just builds the Release config for the device. */
+// ─────────────────────────────── desktop (Tauri chassis) lane ────────────────────────────────
+// Phase-0, macOS-only. Mirrors the managed-CNG model of the mobile lanes but far leaner: copy the
+// `runtime-desktop/` template into the app's disposable `native-desktop/`, stamp the app's identity +
+// window shape (shell_config.json, embedded into the Rust binary) and Tauri config (tauri.conf.json),
+// stage the built web dist, then `cargo run`/`build`. The template is canonical; `native-desktop/` is
+// gitignored + regenerated each run (framework edits propagate — same contract as `native/`).
+
+/** Fail clearly on non-macOS — the desktop chassis is macOS-only for phase-0 (osascript dialogs/
+ * notifications, `open`, the app-data path are all macOS). */
+function ensureDesktopMacOS(): void {
+  if (process.platform !== 'darwin') {
+    console.error(`✖ appwrap desktop is macOS-only for now (phase-0). Detected platform: ${process.platform}.`);
+    process.exit(1);
+  }
+}
+
+/** Skip the heavy/generated dirs when copying the desktop template (Rust build output + Tauri codegen +
+ * deps): they regenerate, and `target/` alone is GBs. Matches RELATIVE to the template root. */
+function desktopCopyFilter(src: string): boolean {
+  const rel = src.slice(DESKTOP_TEMPLATE_DIR.length);
+  return !/(^|\/)(target|gen|node_modules)(\/|$)/.test(rel);
+}
+
+/** Copy the desktop template into `native-desktop/` and stamp it from the config: the Rust-read
+ * `shell_config.json` (identity + window), `tauri.conf.json` (productName/version/identifier +
+ * frontendDist), and the staged web dist (`native-desktop/dist`, referenced as `../dist`). */
+function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, pushSigned = false): void {
+  if (!existsSync(DESKTOP_TEMPLATE_DIR)) {
+    console.error(`✖ Desktop template not found at ${DESKTOP_TEMPLATE_DIR}`);
+    process.exit(1);
+  }
+  const srcTauri = join(outDir, 'src-tauri');
+  mkdirSync(outDir, { recursive: true });
+  cpSync(DESKTOP_TEMPLATE_DIR, outDir, { recursive: true, force: true, filter: desktopCopyFilter });
+
+  // Stage the built web dist INTO the wrapper (mirrors mobile copyPwa) so frontendDist is a stable
+  // relative path independent of where the app project sits.
+  const dist = resolve(cwd, cfg.pwaDist);
+  if (!existsSync(dist)) {
+    console.error(`✖ Web dist not found at ${dist} — build the PWA first (or check pwaDist).`);
+    process.exit(1);
+  }
+  const stagedDist = join(outDir, 'dist');
+  rmSync(stagedDist, { recursive: true, force: true });
+  cpSync(dist, stagedDist, { recursive: true, force: true });
+
+  const shell = deriveDesktopConfig(cfg);
+  shell.pushSigned = pushSigned;
+  // Resolve the handlers path to ABSOLUTE (against the app root): the shell binary runs from a
+  // different cwd, and for `build desktop` the .app runs from wherever it's installed — an absolute
+  // path is the only one that stays valid. The handler file is NOT copied into the wrapper/.app; the
+  // app dir (with its node_modules) must remain present at runtime (documented in the config type).
+  if (shell.handlers) {
+    const abs = resolve(cwd, shell.handlers);
+    if (!existsSync(abs)) {
+      console.warn(`⚠ desktop.handlers points to a missing file (${abs}) — the sidecar will not spawn.`);
+    }
+    shell.handlers = abs;
+    // Stamp the ABSOLUTE Bun binary the sidecar must be spawned with: the CLI itself runs under bun,
+    // so process.execPath IS the exact runtime the app was built with. A GUI-launched .app inherits
+    // the launchd PATH (no ~/.bun/bin), so the Rust shell can't rely on a bare `bun` lookup.
+    shell.handlersRuntime = process.execPath;
+  }
+  writeFileSync(join(srcTauri, 'shell_config.json'), JSON.stringify(shell, null, 2) + '\n');
+
+  const tauriConfPath = join(srcTauri, 'tauri.conf.json');
+  const template = JSON.parse(readFileSync(tauriConfPath, 'utf8')) as Record<string, unknown>;
+  const stamped = stampTauriConf(template, shell, '../dist'); // relative to src-tauri/
+  writeFileSync(tauriConfPath, JSON.stringify(stamped, null, 2) + '\n');
+
+  stampDesktopRuntimeIcon(cwd, cfg, join(srcTauri, 'icons', 'icon.png'));
+}
+
+/** Stamp the Tauri RUNTIME icon (`src-tauri/icons/icon.png`, embedded via `generate_context!`) from
+ * the app's real icon — else it OVERRIDES the bundle icns/Assets.car in cmd+tab/Dock with the template
+ * placeholder square. Downscale to 512 via sips → round the macOS app-icon corners + ensure RGBA (our
+ * dependency-free codec) → write. On any failure, keep the template placeholder (Tauri needs *some*
+ * RGBA icon.png to compile) and warn — never fail the build over an icon. */
+function stampDesktopRuntimeIcon(cwd: string, cfg: AppwrapConfig, destPng: string): void {
+  const source = findIconSource(cwd, cfg);
+  if (!source) return; // no cfg.icon / manifest icon → keep template placeholder
+  const tmpPng = join(tmpdir(), `appwrap-desktop-icon-${Date.now()}.png`);
+  try {
+    // Artwork at Apple's icon-grid fraction of the canvas, then pad — full-bleed runtime icons
+    // render visibly larger than bundle-masked Dock neighbors (no OS-applied margin/mask).
+    const art = Math.round(512 * APPLE_ICON_GRID_SCALE);
+    execFileSync('sips', ['-s', 'format', 'png', '-z', String(art), String(art), source, '--out', tmpPng], { stdio: 'ignore' });
+    writeFileSync(destPng, makeDockRuntimeIcon(readFileSync(tmpPng), 512));
+    console.log(`  desktop runtime icon ← ${source} (${art}² rounded on 512² canvas)`);
+  } catch (e: unknown) {
+    console.warn(`⚠ desktop runtime icon stamp failed (${e instanceof Error ? e.message : String(e)}) — keeping placeholder`);
+  } finally {
+    rmSync(tmpPng, { force: true });
+  }
+}
+
+/** Shared target dir for the desktop crate — reuse the template's warm `target/` so a stamped copy
+ * builds incrementally (~seconds) instead of a ~4-min cold compile of the Tauri dep tree. */
+/** Resolve a spawnable `cargo` (bin + PATH-augmented env) for the desktop lane. rustup installs into
+ * `~/.cargo/bin`, which a GUI/login shell often lacks on PATH → a bare spawn throws a raw ENOENT. We
+ * append it when the binary lives there, else fail with an actionable install/source message. */
+function desktopCargo(): { bin: string; env: NodeJS.ProcessEnv } {
+  const home = process.env.HOME ?? '';
+  const res = resolveCargoPath({
+    path: process.env.PATH ?? '',
+    home,
+    delimiter: pathDelimiter,
+    hasCargo: (dir) => existsSync(join(dir, 'cargo')),
+  });
+  if (!res.found) {
+    console.error(
+      `✖ cargo not found on PATH${home ? ` (and no ${home}/.cargo/bin/cargo)` : ''}.\n` +
+        `  Install the Rust toolchain via rustup:  https://rustup.rs\n` +
+        `  If it's already installed, add it to this shell:  source "$HOME/.cargo/env"`
+    );
+    process.exit(1);
+  }
+  if (res.augmented) console.log(`  cargo ← ${home}/.cargo/bin (appended to PATH; not in your shell's PATH)`);
+  return {
+    bin: res.bin,
+    env: { ...process.env, PATH: res.path, CARGO_TARGET_DIR: join(DESKTOP_TEMPLATE_DIR, 'src-tauri/target') },
+  };
+}
+
+/** `appwrap dev desktop` — stamp the wrapper + `cargo run` (launches the window; blocks until closed). */
+async function devDesktop(cwd: string, flags: Record<string, string>): Promise<void> {
+  ensureDesktopMacOS();
+  const cfg = await loadConfig(cwd, flags);
+  const outDir = resolve(cwd, flags.out ?? 'native-desktop');
+  buildWebIfBundled(cwd, cfg, flags);
+  regenerateDesktop(cwd, cfg, outDir);
+  const { bin, env } = desktopCargo();
+  console.log(`▶ cargo run  (appwrap desktop shell — ${cfg.name})`);
+  execFileSync(bin, ['run'], { cwd: join(outDir, 'src-tauri'), stdio: 'inherit', env });
+}
+
+/** Generate `AppIcon.icns` from the app's icon PNG via `sips` + `iconutil` (macOS-only, like the whole
+ * desktop lane). Returns the icns basename, or null when no icon source / tooling — skip gracefully. */
+function generateMacIcns(cwd: string, cfg: AppwrapConfig, resourcesDir: string): string | null {
+  const source = findIconSource(cwd, cfg);
+  if (!source) return null;
+  const iconset = join(tmpdir(), `appwrap-icns-${Date.now()}.iconset`);
+  mkdirSync(iconset, { recursive: true });
+  try {
+    for (const px of [16, 32, 128, 256, 512]) {
+      execFileSync('sips', ['-z', String(px), String(px), source, '--out', join(iconset, `icon_${px}x${px}.png`)], { stdio: 'ignore' });
+      execFileSync('sips', ['-z', String(px * 2), String(px * 2), source, '--out', join(iconset, `icon_${px}x${px}@2x.png`)], { stdio: 'ignore' });
+    }
+    execFileSync('iconutil', ['-c', 'icns', iconset, '-o', join(resourcesDir, 'AppIcon.icns')], { stdio: 'ignore' });
+    return 'AppIcon.icns';
+  } catch (e: unknown) {
+    console.warn(`⚠ icns generation failed (${e instanceof Error ? e.message : String(e)}) — .app ships without an icon`);
+    return null;
+  } finally {
+    rmSync(iconset, { recursive: true, force: true });
+  }
+}
+
+/** Compile a Tahoe-native `Assets.car` (+ its own `AppIcon.icns`) from the app's icon via `actool`,
+ * into `resourcesDir`. macOS 26 (Tahoe) resolves a bundle's Finder/Dock icon through
+ * `CFBundleIconName` + `Assets.car`, NOT the legacy top-level `.icns`. Returns the asset icon name
+ * (`AppIcon`) on success, or null when there's no icon / `xcrun`/`actool` is unavailable or fails —
+ * caller then keeps the iconutil `.icns` path (fine pre-26; Tahoe Finder icon may look generic). */
+function compileMacAssetsCar(cwd: string, cfg: AppwrapConfig, resourcesDir: string): string | null {
+  const source = findIconSource(cwd, cfg);
+  if (!source) return null;
+  const work = join(tmpdir(), `appwrap-actool-${Date.now()}`);
+  const xcassets = join(work, 'Assets.xcassets');
+  const iconset = join(xcassets, 'AppIcon.appiconset');
+  try {
+    mkdirSync(iconset, { recursive: true });
+    // 10 macOS reps: 16/32/128/256/512 pt at @1x and @2x.
+    const reps = [16, 32, 128, 256, 512].flatMap((pt) => [
+      { pt, scale: 1, px: pt },
+      { pt, scale: 2, px: pt * 2 },
+    ]);
+    const images = reps.map(({ pt, scale, px }) => {
+      const filename = `icon_${pt}x${pt}@${scale}x.png`;
+      execFileSync('sips', ['-s', 'format', 'png', '-z', String(px), String(px), source, '--out', join(iconset, filename)], { stdio: 'ignore' });
+      return { idiom: 'mac', size: `${pt}x${pt}`, scale: `${scale}x`, filename };
+    });
+    writeFileSync(join(iconset, 'Contents.json'), JSON.stringify({ images, info: { version: 1, author: 'appwrap' } }, null, 2));
+    writeFileSync(join(xcassets, 'Contents.json'), JSON.stringify({ info: { version: 1, author: 'appwrap' } }, null, 2));
+
+    const partialPlist = join(work, 'partial.plist');
+    execFileSync('xcrun', ['actool', xcassets,
+      '--compile', resourcesDir,
+      '--platform', 'macosx',
+      '--target-device', 'mac',
+      '--minimum-deployment-target', '11.0',
+      '--app-icon', 'AppIcon',
+      '--output-partial-info-plist', partialPlist,
+    ], { stdio: 'ignore' });
+
+    if (!existsSync(join(resourcesDir, 'Assets.car'))) throw new Error('actool produced no Assets.car');
+    return 'AppIcon';
+  } catch (e: unknown) {
+    console.warn(`⚠ actool Assets.car compile skipped (${e instanceof Error ? e.message : String(e)}) — Tahoe Finder icon may look generic; legacy .icns kept`);
+    return null;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** Resolved macOS signing lane. `identity` is the cert SHA-1 hash (fed to codesign — unambiguous,
+ * unlike a CN which can collide); `cn` is kept for logging; `kind` records the cert class. The
+ * aps-environment is NOT derived from `kind` — it comes from the provisioning profile itself. */
+interface MacSigning { identity: string; cn: string; kind: 'developer-id' | 'development'; teamId: string }
+
+/** A matched macOS profile + its own aps-environment entitlement. */
+interface MacProfileMatch { path: string; apsEnvironment?: string }
+
+/** Resolve a real code-signing identity for the desktop lane. Team precedence mirrors stampTeamId:
+ * non-placeholder cfg.teamId → $APPWRAP_TEAM_ID → none (adhoc). Identity preference within the team:
+ * "Developer ID Application" (direct distribution) → "Apple Development" (local/dev). The CN of a
+ * dev cert does NOT carry the team id — match via the certificate's OU field. Returns null (→ adhoc
+ * fallback) when no team is set or no identity of either class belongs to it. */
+function resolveMacSigning(cfg: AppwrapConfig): MacSigning | null {
+  const teamId = (!cfg.teamId || /YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId))
+    ? process.env.APPWRAP_TEAM_ID?.trim() || null
+    : cfg.teamId;
+  if (!teamId) return null;
+  let listing = '';
+  try {
+    listing = execFileSync('security', ['find-identity', '-v', '-p', 'codesigning'], { encoding: 'utf8' });
+  } catch { return null; }
+  // find-identity -v lines: `  1) <40-hex-SHA1> "<CN>"`. Capture BOTH — codesign is fed the hash.
+  const entries = [...listing.matchAll(/\b([0-9A-F]{40})\s+"([^"]+)"/g)].map((m) => ({ hash: m[1], cn: m[2] }));
+  const teamOf = (cn: string): string | null => {
+    try {
+      const pem = execFileSync('security', ['find-certificate', '-c', cn, '-p'], { encoding: 'utf8' });
+      const subject = execFileSync('openssl', ['x509', '-noout', '-subject'], { input: pem, encoding: 'utf8' });
+      return subject.match(/OU\s*=\s*([A-Z0-9]{10})/)?.[1] ?? null;
+    } catch { return null; }
+  };
+  for (const prefix of ['Developer ID Application', 'Apple Development'] as const) {
+    const match = entries.find((e) => e.cn.startsWith(prefix) && teamOf(e.cn) === teamId);
+    if (match) return { identity: match.hash, cn: match.cn, kind: prefix === 'Developer ID Application' ? 'developer-id' : 'development', teamId };
+  }
+  return null;
+}
+
+/** Find an installed, unexpired macOS provisioning profile for `<teamId>.<bundleId>`. macOS profiles
+ * are `.provisionprofile` (same CMS envelope as iOS `.mobileprovision`; findProvisioningProfiles only
+ * scans the latter, so this is the mac twin). Returns the file path, or null (→ sign without the
+ * restricted push entitlement — a restricted entitlement with no embedded profile kills the app at
+ * launch, which is strictly worse than a signed app without push). */
+function findMacProvisionProfile(teamId: string, bundleId: string, signingCertHash?: string): MacProfileMatch | null {
+  const dirs = [
+    join(process.env.HOME ?? '', 'Library/MobileDevice/Provisioning Profiles'),
+    join(process.env.HOME ?? '', 'Library/Developer/Xcode/UserData/Provisioning Profiles'),
+  ];
+  const wanted = signingCertHash?.toUpperCase();
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    let files: string[] = [];
+    try { files = readdirSync(dir).filter((f) => f.endsWith('.provisionprofile')); } catch { continue; }
+    for (const f of files) {
+      try {
+        const raw = execFileSync('security', ['cms', '-D', '-i', join(dir, f)],
+          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const info = parseMacProfile(raw);
+        const { teamId: team, appId, expiration } = info;
+        if (team !== teamId || !appId) continue;
+        if (expiration && Date.parse(expiration) < Date.now()) continue;
+        const profBundle = appId.startsWith(team + '.') ? appId.slice(team.length + 1) : appId;
+        if (profBundle !== bundleId && profBundle !== '*') continue;
+        // The chosen signing cert MUST be one the profile authorizes (DER SHA-1 == find-identity hash),
+        // else codesign succeeds but the app launch is rejected. Mismatch → warn + keep scanning.
+        if (wanted) {
+          const authorized = info.certificates.some(
+            (b64) => createHash('sha1').update(Buffer.from(b64, 'base64')).digest('hex').toUpperCase() === wanted,
+          );
+          if (!authorized) {
+            console.log(`  ⚠ profile ${f} does not authorize the chosen signing certificate — skipping`);
+            continue;
+          }
+        }
+        return { path: join(dir, f), apsEnvironment: info.apsEnvironment };
+      } catch { /* skip unreadable profile */ }
+    }
+  }
+  return null;
+}
+
+/** Assemble a double-clickable `<Name>.app` around the built shell binary. The Info.plist's
+ * CFBundleURLTypes is what registers `urlScheme` with LaunchServices — a bare binary can't receive
+ * `<scheme>://…` opens (tauri-plugin-deep-link needs the bundle). Signed with a real identity +
+ * entitlements + embedded profile when teamId resolves (resolveMacSigning); ad-hoc otherwise. */
+function assembleMacApp(cwd: string, cfg: AppwrapConfig, shell: DesktopShellConfig, outDir: string, binary: string,
+  lane?: { signing: MacSigning | null; profile: MacProfileMatch | null }): string {
+  const appDir = join(outDir, 'dist-app', `${shell.name}.app`);
+  const macosDir = join(appDir, 'Contents/MacOS');
+  const resourcesDir = join(appDir, 'Contents/Resources');
+  rmSync(appDir, { recursive: true, force: true });
+  mkdirSync(macosDir, { recursive: true });
+  mkdirSync(resourcesDir, { recursive: true });
+  cpSync(binary, join(macosDir, shell.name));
+  const iconFile = generateMacIcns(cwd, cfg, resourcesDir) ?? undefined;
+  // Also compile a Tahoe-native Assets.car (macOS 26 reads CFBundleIconName/Assets.car, not the .icns).
+  // actool emits its own AppIcon.icns alongside — let it replace the iconutil one when present.
+  const iconName = compileMacAssetsCar(cwd, cfg, resourcesDir) ?? undefined;
+  writeFileSync(join(appDir, 'Contents/Info.plist'), buildInfoPlist(shell, shell.name, iconFile, iconName));
+  const signing = lane ? lane.signing : resolveMacSigning(cfg);
+  if (signing) {
+    // Signed lane: real identity; when an installed macOS profile matches, embed it and claim the
+    // push entitlement (restricted → only launches profile-backed). Developer ID gets the hardened
+    // runtime (notarization prerequisite; harmless otherwise).
+    const profile = lane ? lane.profile : findMacProvisionProfile(signing.teamId, shell.identifier, signing.identity);
+    if (profile) cpSync(profile.path, join(appDir, 'Contents/embedded.provisionprofile'));
+    else console.log(`  ⓘ no macOS provisioning profile installed for ${signing.teamId}.${shell.identifier} — signing without entitlements (cert only)`);
+    // aps-environment comes from the PROFILE's own entitlement, not the cert kind — a Developer ID cert
+    // paired with a development profile must claim `development`, or the app is killed at launch.
+    const aps = profile?.apsEnvironment;
+    if (profile && aps !== 'development' && aps !== 'production') {
+      console.log(`  ⓘ profile has no aps-environment entitlement — signing without push`);
+    }
+    const args = ['--force', '--deep', '-s', signing.identity];
+    // Entitlements ONLY when a profile backs them: application-identifier/team-identifier are
+    // RESTRICTED — claiming them without an embedded profile makes macOS refuse to launch the app
+    // ("can't be opened"). No profile → plain cert signature (launches fine, no push).
+    if (profile) {
+      const entitlements = buildMacEntitlements({
+        teamId: signing.teamId,
+        bundleId: shell.identifier,
+        apsEnvironment: aps === 'development' || aps === 'production' ? aps : undefined,
+      });
+      const entFile = join(outDir, 'dist-app', `${shell.name}.entitlements`);
+      writeFileSync(entFile, entitlements);
+      args.push('--entitlements', entFile);
+    }
+    if (signing.kind === 'developer-id') args.push('--options', 'runtime', '--timestamp');
+    console.log(`▶ codesign (${signing.cn} [${signing.identity}]${profile ? ', profile embedded' : ''})`);
+    execFileSync('codesign', [...args, appDir], { stdio: 'inherit' });
+  } else {
+    // Ad-hoc sign so Gatekeeper/LaunchServices treat the bundle as intact on this machine.
+    // Only flag a skip when a REAL team was requested (placeholder teamId = signing never asked for).
+    const requested = process.env.APPWRAP_TEAM_ID?.trim() || (cfg.teamId && !/YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId) ? cfg.teamId : '');
+    if (requested) console.log(`  ⓘ signed lane skipped — no Developer ID / Apple Development identity for team ${requested}; ad-hoc signing`);
+    execFileSync('codesign', ['--force', '--deep', '-s', '-', appDir], { stdio: 'inherit' });
+  }
+  return appDir;
+}
+
+/** Opt-in notarization (env `APPWRAP_NOTARIZE=1`, off by default). Requires the Developer ID signed
+ * lane — assembleMacApp already signs it with `--options runtime --timestamp` (hardened runtime +
+ * secure timestamp, both notarization prerequisites; no get-task-allow is ever claimed). Credentials:
+ * `APPWRAP_NOTARY_KEYCHAIN_PROFILE` (a `notarytool store-credentials` profile) or an ASC API key —
+ * `APPWRAP_NOTARY_KEY_ID` + `APPWRAP_NOTARY_ISSUER` (+ optional `APPWRAP_NOTARY_KEY` p8 path,
+ * default ~/.appstoreconnect/private_keys/AuthKey_<id>.p8). */
+function notarizeMacApp(appDir: string, signing: MacSigning | null): void {
+  if (process.env.APPWRAP_NOTARIZE !== '1') return;
+  if (!signing || signing.kind !== 'developer-id') {
+    console.error(`✖ APPWRAP_NOTARIZE=1 needs a Developer ID signed .app (current lane: ${signing ? signing.kind : 'ad-hoc'}) — install a "Developer ID Application" identity for the team and rebuild`);
+    process.exit(1);
+  }
+  const kcProfile = process.env.APPWRAP_NOTARY_KEYCHAIN_PROFILE?.trim();
+  const keyId = process.env.APPWRAP_NOTARY_KEY_ID?.trim();
+  const issuer = process.env.APPWRAP_NOTARY_ISSUER?.trim();
+  const keyPath = process.env.APPWRAP_NOTARY_KEY?.trim()
+    || (keyId ? join(process.env.HOME ?? '', `.appstoreconnect/private_keys/AuthKey_${keyId}.p8`) : '');
+  let auth: string[];
+  if (kcProfile) auth = ['--keychain-profile', kcProfile];
+  else if (keyId && issuer) {
+    if (!existsSync(keyPath)) {
+      console.error(`✖ notarization: ASC API key file not found at ${keyPath} (set APPWRAP_NOTARY_KEY to the .p8 path)`);
+      process.exit(1);
+    }
+    auth = ['--key', keyPath, '--key-id', keyId, '--issuer', issuer];
+  } else {
+    console.error('✖ APPWRAP_NOTARIZE=1 but no credentials — set APPWRAP_NOTARY_KEY_ID + APPWRAP_NOTARY_ISSUER (ASC API key) or APPWRAP_NOTARY_KEYCHAIN_PROFILE (notarytool store-credentials)');
+    process.exit(1);
+  }
+  const zip = `${appDir}.notarize.zip`;
+  rmSync(zip, { force: true });
+  execFileSync('ditto', ['-c', '-k', '--keepParent', appDir, zip], { stdio: 'inherit' });
+  console.log('▶ notarytool submit --wait  (Apple-side processing — can take several minutes)');
+  try {
+    execFileSync('xcrun', ['notarytool', 'submit', zip, ...auth, '--wait'], { stdio: 'inherit' });
+    execFileSync('xcrun', ['stapler', 'staple', appDir], { stdio: 'inherit' });
+  } finally {
+    rmSync(zip, { force: true });
+  }
+  console.log(`✓ Notarized + stapled: ${appDir}`);
+}
+
+/** `appwrap build desktop` — stamp the wrapper, `cargo build --release`, then assemble the `.app`. */
+async function buildDesktop(cwd: string, flags: Record<string, string>): Promise<void> {
+  ensureDesktopMacOS();
+  const cfg = await loadConfig(cwd, flags);
+  const outDir = resolve(cwd, flags.out ?? 'native-desktop');
+  buildWebIfBundled(cwd, cfg, flags);
+  // Resolve the signing lane BEFORE regeneration: shell_config.json is embedded at compile time,
+  // and the Rust shell's push capability must only claim 'native' when the .app really ships the
+  // profile-backed aps-environment entitlement (signed lane + installed macOS profile).
+  const signing = resolveMacSigning(cfg);
+  const shellCfg = deriveDesktopConfig(cfg);
+  const profile = signing ? findMacProvisionProfile(signing.teamId, shellCfg.identifier, signing.identity) : null;
+  // Only let the Rust shell claim NATIVE push when the app will actually ship a profile-backed
+  // aps-environment entitlement (profile matched AND it carries the entitlement).
+  const nativePush = !!(signing && profile && (profile.apsEnvironment === 'development' || profile.apsEnvironment === 'production'));
+  regenerateDesktop(cwd, cfg, outDir, nativePush);
+  const { bin, env } = desktopCargo();
+  console.log(`▶ cargo build --release  (appwrap desktop shell — ${cfg.name})`);
+  execFileSync(bin, ['build', '--release'], { cwd: join(outDir, 'src-tauri'), stdio: 'inherit', env });
+  const binary = join(DESKTOP_TEMPLATE_DIR, 'src-tauri/target/release/appwrap-desktop-shell');
+  console.log(`✓ Desktop binary: ${binary}`);
+  const appDir = assembleMacApp(cwd, cfg, shellCfg, outDir, binary, { signing, profile });
+  console.log(`✓ App bundle: ${appDir}`);
+  notarizeMacApp(appDir, signing);
+}
+
 async function build(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
+  if (platform === 'desktop') return buildDesktop(cwd, flags);
   if (platform !== 'ios' && platform !== 'android') {
-    console.error('Usage: appwrap build <ios|android> [--release] [--aab] [--config <path>] [--out native]');
+    console.error('Usage: appwrap build <ios|android|desktop> [--release] [--aab] [--config <path>] [--out native]');
     process.exit(1);
   }
   const outDir = resolve(cwd, flags.out ?? 'native');
@@ -2688,9 +3128,7 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   const force = 'force' in flags || 'f' in flags;
   const fp = buildFingerprint(cwd, cfg, flags);
   const cache = readBuildCache(outDir, 'ios');
-  const existingIpa = existsSync(ipaDir)
-    ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa'))
-    : undefined;
+  const existingIpa = newestIpa(ipaDir);
   const fingerprintMatch = !force && existingIpa && cache?.fingerprint === fp && cache?.artifactPath === join(ipaDir, existingIpa);
   // --resume also accepts a missing cache file (e.g. after a manual Xcode build or first run),
   // but ONLY when the fingerprint matches what's currently on disk — never skips a needed build.
@@ -2709,24 +3147,45 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       if (sc.provision) nsArgs.push('--provision', sc.provision);
     } catch { /* no sidecar → automatic signing */ }
     console.log(`▶ ns ${nsArgs.join(' ')}  (debug: keep-awake + inspector on)${force ? '  [--force: skipping cache]' : ''}`);
+    const buildStart = Date.now();
     try {
       execFileSync('ns', nsArgs, { cwd: outDir, stdio: 'inherit' });
     } catch (e) {
-      // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
-      console.error(
-        '\n✖ Device build failed — if the errors above mention signing:\n' +
-          `  • "Failed Registering Bundle Identifier … not available" → the App ID "${cfg.id}" is already\n` +
-          '    registered to another team (e.g. a prior free-team build). Change `id` in appwrap.config to a\n' +
-          '    unique string and re-deploy.\n' +
-          '  • "profile doesn\'t include the … entitlement" (e.g. HealthKit) → that capability needs a PAID\n' +
-          '    team (Individual). A free Personal Team can\'t hold it — switch teamId or drop the module.\n' +
-          '  • "No Account for Team" → sign that Apple ID into Xcode → Settings → Accounts first.'
-      );
-      process.exit(1);
+      // exportArchive is the ACCOUNT-GATED step: with special entitlements (e.g. Associated Domains)
+      // automatic-signing export must (re)provision via App Store Connect, which needs a live Xcode
+      // account session — one Xcode 26 keeps silently dropping. The ARCHIVE itself signs fine from
+      // locally cached profiles. So when a fresh signed .app exists in the xcarchive, resign it with
+      // a local Xcode-managed dev profile + pack the ipa ourselves — no account, no network.
+      const archiveApp = join(ipaDir, 'native.xcarchive/Products/Applications/native.app');
+      let resigned = false;
+      if (existsSync(archiveApp) && statSync(archiveApp).mtimeMs >= buildStart) {
+        console.error('\n⚠ Export failed but the archive is built + signed — resigning from the archive with a local dev profile (no Apple account session needed)…');
+        try {
+          resigned = resignArchiveIpa(archiveApp, join(ipaDir, 'native.ipa'), cfg, device.id);
+        } catch (fe) {
+          console.error(`  resign fallback failed: ${fe instanceof Error ? fe.message : fe}`);
+        }
+      }
+      if (!resigned) {
+        // The xcodebuild dump above is cryptic; surface the signing failures we actually hit most.
+        console.error(
+          '\n✖ Device build failed — if the errors above mention signing:\n' +
+            `  • "Failed Registering Bundle Identifier … not available" → the App ID "${cfg.id}" is already\n` +
+            '    registered to another team (e.g. a prior free-team build). Change `id` in appwrap.config to a\n' +
+            '    unique string and re-deploy.\n' +
+            '  • "profile doesn\'t include the … entitlement" (e.g. HealthKit) → that capability needs a PAID\n' +
+            '    team (Individual). A free Personal Team can\'t hold it — switch teamId or drop the module.\n' +
+            '  • "No Account for Team" → sign that Apple ID into Xcode → Settings → Accounts first.\n' +
+            '  • "requires a provisioning profile with the … feature" → the resign fallback above needs a\n' +
+            '    LOCAL dev profile carrying that capability: build the app once from Xcode on this Mac\n' +
+            '    (auto-signing mints + caches the profile for ~1 year), then re-run `appwrap deploy ios`.'
+        );
+        process.exit(1);
+      }
     }
   }
 
-  const builtIpa = existsSync(ipaDir) ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa')) : undefined;
+  const builtIpa = newestIpa(ipaDir);
   const ipa = builtIpa;
   if (!ipa) { console.error(`✖ No .ipa produced in ${ipaDir}`); process.exit(1); }
   const ipaPath = join(ipaDir, ipa);
@@ -2741,8 +3200,12 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   const installTimeout = wireless ? '120' : '25';
   // Capture (not inherit) so we can recognize specific failures; echo it for visibility. Wrapped so a
   // LOCKED device waits-and-retries. --timeout lets one attempt tolerate a brief locked/unavailable window.
+  // BELT + SUSPENDERS on hangs: devicectl's own `--timeout` only covers device-side waits. A wedged
+  // CoreDeviceService makes devicectl hang BEFORE that — silently, with zero output — so without a
+  // process-level `timeout:` the exec blocks forever and the self-heal below never fires.
+  const hardTimeoutMs = (Number(installTimeout) + 35) * 1000;
   const runDevicectlInstall = (): string => withUnlockRetry('Install', () =>
-    execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', installTimeout, '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+    execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', installTimeout, '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'], timeout: hardTimeoutMs })
   );
   try {
     process.stdout.write(runDevicectlInstall());
@@ -2761,8 +3224,9 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
           '  (A paid Apple Developer account removes this limit.)'
       );
       process.exit(1);
-    } else if (/Command timeout|got stuck|could not be reached|Unable to connect to device/.test(log)) {
-      // devicectl/CoreDevice is stuck (connection hang, NOT a lock). Usual cause: a pegged
+    } else if (isTimeoutKill(e) || /Command timeout|got stuck|could not be reached|Unable to connect to device/.test(log)) {
+      // devicectl/CoreDevice is stuck — either it SAID so, or our process-level timeout had to kill a
+      // silent zero-output hang (the wedged-CoreDeviceService signature). Usual cause: a pegged
       // CoreDeviceService daemon. SELF-HEAL: kill it (auto-respawns clean) and retry devicectl once —
       // this is the fix a human otherwise applies by hand, and it's the ONLY path that works for a
       // wireless-only device (usbmux is USB-only).
@@ -2809,7 +3273,7 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       // old serverUrl) despite a correct new build — masquerading as a build/cache bug. (A reinstall
       // over the top does NOT replace a running process; this avoids the manual uninstall dance.)
       withUnlockRetry('Launch', () =>
-        execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--terminate-existing', '--timeout', installTimeout, '--device', device.id, cfg.id], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+        execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--terminate-existing', '--timeout', installTimeout, '--device', device.id, cfg.id], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'], timeout: hardTimeoutMs })
       );
     } catch {
       console.error('⚠ Launch failed (still locked after waiting). The app is installed — unlock and tap it, or re-run.');
@@ -2825,7 +3289,7 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
  * fails (the caller then prints the re-plug / brew-install remedy). */
 function usbmuxInstall(ipaPath: string): boolean {
   try {
-    const out = execFileSync('ideviceinstaller', ['install', ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] });
+    const out = execFileSync('ideviceinstaller', ['install', ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'], timeout: 300_000 });
     process.stdout.write(out);
     return /Complete|Installed/i.test(out);
   } catch (e: unknown) {
@@ -2834,18 +3298,125 @@ function usbmuxInstall(ipaPath: string): boolean {
   }
 }
 
+/** Newest .ipa in a build dir by mtime — NOT the first directory entry: an export names its ipa after
+ * the app (e.g. Blank.ipa) while the resign fallback writes native.ipa, and a stale one from a prior
+ * run can coexist with (and alphabetically precede) the fresh artifact. */
+function newestIpa(ipaDir: string): string | undefined {
+  if (!existsSync(ipaDir)) return undefined;
+  return readdirSync(ipaDir)
+    .filter((f) => f.endsWith('.ipa'))
+    .map((f) => ({ f, mtime: statSync(join(ipaDir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)[0]?.f;
+}
+
+/** Resign the archive's .app with a LOCAL Xcode-managed development profile and pack it into an ipa —
+ * the no-account fallback for when `xcodebuild -exportArchive` fails (its automatic signing needs a
+ * live Xcode account session; manual export refuses Xcode-managed profiles, so exportArchive is a
+ * dead end both ways without one). Profile requirements: matches team+bundle id, development
+ * (get-task-allow), unexpired, carries every configured entitlement key, includes the target device,
+ * and lists a signing cert that is actually in the login keychain. Gotcha encoded here: the ipa MUST
+ * be packed with `zip` — `ditto -c -k` stores macOS xattrs as `._*` AppleDouble entries, which
+ * on-device installd rejects as "a signed resource has been added" (0xe8008017).
+ * Returns true on success (ipa written to `ipaOut`); false → caller prints the manual remedies. */
+function resignArchiveIpa(archiveApp: string, ipaOut: string, cfg: AppwrapConfig, coreDeviceId: string): boolean {
+  if (existsSync(join(archiveApp, 'PlugIns'))) {
+    console.error('  ✖ app has extensions (PlugIns/) — per-extension resigning is not supported; use the TestFlight lane.');
+    return false;
+  }
+  const requiredEnts = Object.keys(cfg.iosEntitlements ?? {});
+  const hwUdid = libimobiledeviceUdid()?.udid ?? null; // hardware UDID (≠ devicectl id); null → skip device check
+  if (!hwUdid) console.error(`  ⚠ can't read the device hardware UDID (idevice_id) — picking a profile without verifying it covers device ${coreDeviceId}.`);
+
+  // Signing certs actually present in the keychain, by SHA-1 (uppercase hex).
+  const keychainCerts = new Set(
+    [...execFileSync('security', ['find-identity', '-v', '-p', 'codesigning'], { encoding: 'utf8' })
+      .matchAll(/\b([0-9A-F]{40})\b/g)].map((m) => m[1])
+  );
+
+  const profileDirs = [
+    join(process.env.HOME ?? '', 'Library/Developer/Xcode/UserData/Provisioning Profiles'),
+    join(process.env.HOME ?? '', 'Library/MobileDevice/Provisioning Profiles'),
+  ];
+  let best: { path: string; raw: string; team: string; certSha1: string; expires: number; name: string } | null = null;
+  for (const dir of profileDirs) {
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((f) => f.endsWith('.mobileprovision'))) {
+      const path = join(dir, f);
+      let raw: string;
+      try { raw = execFileSync('security', ['cms', '-D', '-i', path], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }); }
+      catch { continue; }
+      const appId = raw.match(/<key>application-identifier<\/key>\s*<string>([A-Z0-9]+)\.([^<]+)<\/string>/);
+      if (!appId || appId[2] !== cfg.id) continue;
+      if (cfg.teamId && appId[1] !== cfg.teamId) continue;
+      if (!/<key>get-task-allow<\/key>\s*<true\/>/.test(raw)) continue; // development profile only
+      const exp = raw.match(/<key>ExpirationDate<\/key>\s*<date>([^<]+)<\/date>/);
+      const expires = exp ? Date.parse(exp[1]) : 0;
+      if (expires < Date.now()) continue;
+      if (!requiredEnts.every((k) => raw.includes(`<key>${k}</key>`))) continue;
+      if (hwUdid && !raw.includes(`<string>${hwUdid}</string>`)) continue;
+      // First profile cert that is also in the keychain (profiles list several historical certs).
+      const certsBlock = raw.split('<key>DeveloperCertificates</key>')[1]?.split('</array>')[0] ?? '';
+      const certSha1 = [...certsBlock.matchAll(/<data>([\s\S]*?)<\/data>/g)]
+        .map((m) => createHash('sha1').update(Buffer.from(m[1].replace(/\s+/g, ''), 'base64')).digest('hex').toUpperCase())
+        .find((h) => keychainCerts.has(h));
+      if (!certSha1) continue;
+      const name = raw.match(/<key>Name<\/key>\s*<string>([^<]+)<\/string>/)?.[1] ?? f;
+      if (!best || expires > best.expires) best = { path, raw, team: appId[1], certSha1, expires, name };
+    }
+  }
+  if (!best) {
+    console.error(`  ✖ no local development profile matches ${cfg.id}${requiredEnts.length ? ` with [${requiredEnts.join(', ')}]` : ''} for this device.`);
+    return false;
+  }
+  console.error(`  ↻ using profile "${best.name}" (expires ${new Date(best.expires).toISOString().slice(0, 10)}) + keychain cert ${best.certSha1.slice(0, 8)}…`);
+
+  // Stage Payload/, swap in the profile, sign with entitlements derived from config + profile.
+  const staging = join(tmpdir(), `appwrap-resign-${process.pid}`);
+  rmSync(staging, { recursive: true, force: true });
+  const stagedApp = join(staging, 'Payload/native.app');
+  mkdirSync(join(staging, 'Payload'), { recursive: true });
+  cpSync(archiveApp, stagedApp, { recursive: true });
+  cpSync(best.path, join(stagedApp, 'embedded.mobileprovision'));
+  const plistValue = (v: unknown): string => Array.isArray(v)
+    ? `<array>${v.map((x) => `<string>${x}</string>`).join('')}</array>`
+    : typeof v === 'boolean' ? (v ? '<true/>' : '<false/>') : `<string>${String(v)}</string>`;
+  const entPlist = join(staging, 'entitlements.plist');
+  writeFileSync(entPlist,
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n' +
+    '<plist version="1.0">\n<dict>\n' +
+    `\t<key>application-identifier</key><string>${best.team}.${cfg.id}</string>\n` +
+    `\t<key>com.apple.developer.team-identifier</key><string>${best.team}</string>\n` +
+    '\t<key>get-task-allow</key><true/>\n' +
+    `\t<key>keychain-access-groups</key><array><string>${best.team}.*</string></array>\n` +
+    Object.entries(cfg.iosEntitlements ?? {}).map(([k, v]) => `\t<key>${k}</key>${plistValue(v)}\n`).join('') +
+    '</dict>\n</plist>\n');
+  // Nested code first (sealed into the app signature), then the app itself with the entitlements.
+  const frameworksDir = join(stagedApp, 'Frameworks');
+  const nested = existsSync(frameworksDir) ? readdirSync(frameworksDir).filter((f) => /\.(framework|dylib)$/.test(f)) : [];
+  for (const f of nested) execFileSync('codesign', ['-f', '-s', best.certSha1, '--timestamp=none', join(frameworksDir, f)], { stdio: 'pipe' });
+  execFileSync('codesign', ['-f', '-s', best.certSha1, '--timestamp=none', '--entitlements', entPlist, stagedApp], { stdio: 'pipe' });
+  execFileSync('codesign', ['--verify', '--deep', '--strict', stagedApp], { stdio: 'pipe' });
+  rmSync(ipaOut, { force: true });
+  execFileSync('zip', ['-qry', ipaOut, 'Payload'], { cwd: staging, stdio: 'pipe' }); // zip, NOT ditto — see docblock
+  rmSync(staging, { recursive: true, force: true });
+  console.error(`  ✓ resigned ipa ready: ${ipaOut}`);
+  return true;
+}
+
 /** Apple's `CoreDeviceService` daemon intermittently pegs a CPU core at 100% and wedges the device
  * tunnel — `devicectl` then hangs until its timeout (worse on a wireless/localNetwork target). Killing
- * it is the documented remedy: launchd auto-respawns it clean. Best-effort; returns true if we
- * signalled a matching process (pkill exits non-zero → throws → false when nothing matched). */
+ * it is the documented remedy: launchd auto-respawns it clean. `remotepairingd` (also user-owned)
+ * holds the pairing side of the same tunnel and wedges WITH it — kill both; restarting only one is
+ * not enough to recover a wedged stack. Returns true if either kill matched a process. */
 function killStuckCoreDeviceService(): boolean {
-  try {
-    execFileSync('pkill', ['-9', '-f', 'CoreDeviceService.xpc'], { stdio: 'ignore' });
-    sleepSync(4000); // let launchd respawn it + re-establish the tunnel before we retry
-    return true;
-  } catch {
-    return false;
+  let matched = false;
+  for (const pattern of ['CoreDeviceService.xpc', 'remotepairingd']) {
+    try { execFileSync('pkill', ['-9', '-f', pattern], { stdio: 'ignore' }); matched = true; }
+    catch { /* pkill exits non-zero when nothing matched */ }
   }
+  if (matched) sleepSync(4000); // let launchd respawn them + re-establish the tunnel before we retry
+  return matched;
 }
 
 /** Run a devicectl op; if it fails because the device is LOCKED (or transiently unavailable), prompt
@@ -2859,9 +3430,10 @@ function withUnlockRetry<T>(label: string, run: () => T, tries = 40, delayMs = 3
     } catch (e: unknown) {
       const log = execErrText(e);
       if (/maximum number of installed apps|MIInstallerErrorDomain error 13|ApplicationVerificationFailed/.test(log)) throw e;
-      // devicectl/CoreDevice tunnel STUCK (it switches to a [wired] path and hangs) is NOT a lock —
-      // retrying as "waiting for unlock" is pointless + misleading. Re-throw so the caller can fall back.
-      if (/Command timeout|got stuck|could not be reached|Unable to connect to device/.test(log)) throw e;
+      // devicectl/CoreDevice tunnel STUCK (it switches to a [wired] path and hangs, or hangs silently
+      // until our process-level timeout kills it) is NOT a lock — retrying as "waiting for unlock" is
+      // pointless + misleading. Re-throw so the caller can self-heal / fall back.
+      if (isTimeoutKill(e) || /Command timeout|got stuck|could not be reached|Unable to connect to device/.test(log)) throw e;
       if (i >= tries) throw e;
       if (i === 0) process.stdout.write(`\n🔒 ${label}: device unavailable — unlock your iPhone. Waiting (auto-retries every ${delayMs / 1000}s, up to ${Math.round((tries * delayMs) / 1000)}s)…\n`);
       else process.stdout.write(`  …waiting for unlock (${i}/${tries})\n`);
@@ -3057,10 +3629,11 @@ async function main(): Promise<void> {
         '  Android wireless: --wifi flips a USB device to wireless adb (unplug + keep going); thereafter the\n' +
         '       device is auto-discovered via mDNS — plain `dev android` finds it with NO flag (iOS parity).\n' +
         '       --device <ip[:port]> `adb connect`s an already-paired one.\n\n' +
-        '  dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--url <devserver>|--port <p>]\n' +
+        '  dev <ios|android|desktop> [--sim] [--detached] [--debug] [--wifi] [--url <devserver>|--port <p>]\n' +
         '       live-dev: ANDROID device → ns run livesync (true on-device HMR) + re-stage on save;\n' +
         '       iOS device → deploy + rebuild/reinstall on save. --sim = ns run/HMR on emulator;\n' +
         '       --url/--port = web HMR from a dev server inside the WebView; --detached = install & exit.\n' +
+        '       desktop → macOS Tauri shell (cargo run) speaking appwrap protocol v1 (phase-0, macOS-only).\n' +
         '  deploy <ios|android> [--no-launch] [--no-web-build] [-f]   (clean ship-once: build → install → launch → exit)\n' +
         '  publish <ios|android> [prod]              (beta: TestFlight / Play internal. prod: App Store / Play production)\n' +
         '  build <ios|android> [--release] [--aab]   (store artifact only — no install/upload)\n' +