@livx.cc/appwrap 0.43.0 → 0.46.2

package/src/cli.ts

@@ -1064,6 +1064,17 @@ function stampAndroidAppName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   if (existsSync(manifest)) {
     let src = readFileSync(manifest, 'utf8');
     if (cfg.urlScheme) src = src.replace(/android:scheme="[^"]*"/, `android:scheme="${cfg.urlScheme}"`);
+    // Extra OAuth redirect schemes (e.g. Google's `com.googleusercontent.apps.<client>`) as additional
+    // BROWSABLE <data> on the deep-link filter, so the Custom Tab redirect re-enters the app instead of
+    // web-searching an unhandled scheme. Idempotent marker → re-sync-safe. See config.oauthRedirectSchemes.
+    {
+      const extra = (cfg.oauthRedirectSchemes ?? []).filter(Boolean);
+      const body = extra.map((s) => `\n\t\t\t<data android:scheme="${esc(s)}" />`).join('') + (extra.length ? '\n\t\t\t' : '');
+      src = src.replace(
+        /<!-- appwrap:oauth-redirect-schemes -->[\s\S]*?<!-- \/appwrap:oauth-redirect-schemes -->/,
+        `<!-- appwrap:oauth-redirect-schemes -->${body}<!-- /appwrap:oauth-redirect-schemes -->`
+      );
+    }
     // Supported orientation (config > manifest) on the main <activity>. Skipped when unset → keep
     // the template default (free); 'any' removes the attribute, so re-sync stays idempotent.
     if (cfg.orientation) src = stampAndroidOrientation(src, androidScreenOrientation(cfg.orientation));
@@ -1979,6 +1990,30 @@ function desktopCopyFilter(src: string): boolean {
   return !/(^|\/)(target|gen|node_modules)(\/|$)/.test(rel);
 }
 
+/** Resolve a `desktop.server.command` to an absolute path: an absolute/relative path is resolved
+ * against the app root; a bare name is looked up on `path` (build-time PATH). Falls back to the bare
+ * name (the Rust shell will surface the spawn ENOENT) when it's nowhere. */
+function resolveServerCommand(command: string, cwd: string, path: string): string {
+  if (command.includes('/')) return resolve(cwd, command);
+  for (const dir of path.split(pathDelimiter).filter(Boolean)) {
+    const abs = join(dir, command);
+    if (existsSync(abs)) return abs;
+  }
+  return command;
+}
+
+/** The bundled splash shown while a local-server app boots (before the shell navigates to the live
+ * server). A dependency-free, theme-neutral holding page. */
+function desktopSplashHtml(name: string): string {
+  const safe = name.replace(/</g, '&lt;').replace(/&/g, '&amp;');
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${safe}</title>
+<style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;
+flex-direction:column;gap:20px;background:#0b0b0f;color:#e5e5e5;font:14px -apple-system,system-ui,sans-serif}
+.s{width:34px;height:34px;border:3px solid #333;border-top-color:#888;border-radius:50%;animation:r .8s linear infinite}
+@keyframes r{to{transform:rotate(360deg)}}#e{color:#f87171;max-width:70%;text-align:center;line-height:1.5}</style>
+</head><body><div class="s" id="spin"></div><div id="m">Starting ${safe}…</div><div id="e"></div></body></html>`;
+}
+
 /** 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`). */
@@ -1990,20 +2025,45 @@ function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, push
   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 });
+  // `native-desktop/` is generated + disposable (regenerated from the template on every build) — mark
+  // the whole tree git-invisible so a consuming repo never commits generated native code (incl. the
+  // copied `crates/` + `src-tauri/`). A self-ignoring `*` .gitignore works regardless of the app's root
+  // .gitignore; mirrors the mobile lane's disposable-`native/` convention. Written AFTER cpSync so it wins.
+  writeFileSync(join(outDir, '.gitignore'), '*\n');
 
   const shell = deriveDesktopConfig(cfg);
   shell.pushSigned = pushSigned;
+
+  // Stage the frontendDist INTO the wrapper (mirrors mobile copyPwa) so it's a stable relative path
+  // independent of where the app project sits. Local-server apps (`desktop.server`) have no meaningful
+  // web dist — the window loads the live server — so we stage a tiny bundled SPLASH instead (shown
+  // while the server boots, then the shell navigates away from it).
+  const stagedDist = join(outDir, 'dist');
+  rmSync(stagedDist, { recursive: true, force: true });
+  if (shell.server) {
+    mkdirSync(stagedDist, { recursive: true });
+    writeFileSync(join(stagedDist, 'index.html'), desktopSplashHtml(shell.name));
+  } else {
+    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);
+    }
+    cpSync(dist, stagedDist, { recursive: true, force: true });
+  }
+
+  // Local-server mode: resolve `command` (bare name → PATH lookup) and `cwd` to ABSOLUTE, and stamp
+  // the build-time PATH — a GUI-launched .app inherits the minimal launchd PATH (no ~/.bun/bin), so
+  // a bare-name spawn (or a child that itself shells out to `bun`/`node`) would fail there.
+  if (shell.server) {
+    const s = shell.server;
+    s.cwd = s.cwd ? resolve(cwd, s.cwd) : cwd;
+    s.command = resolveServerCommand(s.command, cwd, process.env.PATH ?? '');
+    s.path = process.env.PATH ?? '';
+    if (!existsSync(s.command)) {
+      console.warn(`⚠ desktop.server.command not found (${s.command}) — the server will fail to spawn at launch.`);
+    }
+  }
   // 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
@@ -2347,7 +2407,9 @@ async function buildDesktop(cwd: string, flags: Record<string, string>): Promise
   ensureDesktopMacOS();
   const cfg = await loadConfig(cwd, flags);
   const outDir = resolve(cwd, flags.out ?? 'native-desktop');
-  buildWebIfBundled(cwd, cfg, flags);
+  // Local-server apps load the live server, not a bundled web build — skip it (regenerateDesktop
+  // stages a boot splash for them). Otherwise build/stage the PWA as usual.
+  if (!cfg.desktop?.server) 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).
@@ -3524,10 +3586,21 @@ async function logs(cwd: string, flags: Record<string, string>, positionals: str
   console.log(`▶ watching web logs from ${cfg.id} on ${device.name} (pull every 3s) — Ctrl-C to stop.`);
   console.log('  [appwrap-web] = forwarded WebView console/errors. (--once = snapshot, --native = OS firehose.)');
   let shown = 0;
+  // Self-terminate when orphaned: if our controlling session dies, macOS reparents us to launchd and
+  // this loop would otherwise poll `devicectl` FOREVER — every stale session stacking load until
+  // CoreDeviceService pins a core at 100%. NOTE: `process.ppid` is cached at startup and does NOT
+  // update on reparent, so probe the ORIGINAL parent's liveness with signal 0 (throws once it's gone);
+  // also stop on a broken stdout pipe (consumer gone).
+  const parentPid = process.ppid;
+  const orphaned = (): boolean => { try { process.kill(parentPid, 0); return false; } catch { return true; } };
   for (;;) {
+    if (orphaned()) break; // original parent gone → we've been reparented → stop
     const all = pull();
     if (all.length < shown) shown = 0; // app relaunched → file reset; reprint
-    if (all.length > shown) { process.stdout.write(all.slice(shown)); shown = all.length; }
+    if (all.length > shown) {
+      try { process.stdout.write(all.slice(shown)); } catch { break; } // pipe closed → consumer gone
+      shown = all.length;
+    }
     try { execFileSync('sleep', ['3']); } catch { break; }
   }
 }

package/src/config.ts

@@ -89,6 +89,42 @@ export interface AppwrapConfig {
      * the app dir, so `build desktop` apps must keep their repo (+ node_modules) around at runtime —
      * embedding the handler file into the `.app` is out of scope for phase-0. macOS-only. */
     handlers?: string;
+    /** Local-server mode: boot a command that serves the app locally, then load it LIVE in the window
+     * (instead of the bundled `pwaDist`). The shell shows a bundled splash, spawns `command` (+`args`)
+     * in a background thread, polls `http://localhost:<port><healthPath>` until it answers, then
+     * navigates the window there; on window-close it kills the child so the stack never outlives the
+     * shell. Use for a desktop app that IS a local dev/server stack (e.g. `para-chat`). Absent → the
+     * desktop lane loads the bundled `pwaDist` as usual. The CLI resolves `command` (when a bare name)
+     * and `cwd` to absolute paths at stamp time (a GUI-launched .app inherits the minimal launchd PATH,
+     * so a bare `bun`/PATH lookup would fail). `build desktop` apps must keep the server (+ its repo)
+     * present at runtime — bundling the server INTO the .app is a future phase. macOS-only. */
+    server?: {
+      /** Command to spawn (argv[0]). A bare name is PATH-resolved at stamp time; an absolute path is used as-is. */
+      command: string;
+      /** Extra arguments passed to the command. */
+      args?: string[];
+      /** Working directory to spawn in (default: the app project root). */
+      cwd?: string;
+      /** How the shell learns the URL to load. Provide EXACTLY ONE:
+       *  - `urlMarker` (preferred for servers that print their address, e.g. vite/para-chat): the shell
+       *    pipes the server's stdout and, on the first line CONTAINING this marker, extracts the first
+       *    `http(s)://…` token and loads it. This tracks whatever port the server auto-picked — no
+       *    hardcoded port, no mismatch. e.g. `"Frontend:"` matches `Frontend:  https://localhost:5050`.
+       *  - `port` (+ optional `https`) for a silent server on a KNOWN fixed port: the shell TCP-polls
+       *    `localhost:<port>` and loads `<http|https>://localhost:<port>`. */
+      urlMarker?: string;
+      /** Fixed port the server listens on (used only when `urlMarker` is absent). */
+      port?: number;
+      /** Load over https in fixed-`port` mode (default false = http). Ignored in `urlMarker` mode (the
+       * captured URL carries its own scheme). The server's TLS cert CA must be trusted by the system
+       * keychain and its SANs cover `localhost`/`127.0.0.1`, or the WebView shows a cert error. */
+      https?: boolean;
+      /** Health path polled for readiness (default `/`). Ready = any HTTP response (even 4xx/5xx). */
+      healthPath?: string;
+      /** Max ms to wait for the port before showing an error in the splash (default 120000 — a first-run
+       * production build can be slow). */
+      readyTimeoutMs?: number;
+    };
   };
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
@@ -105,6 +141,15 @@ export interface AppwrapConfig {
    * `<package android:name="..."/>`. For scheme probes prefer `queryUrlSchemes` (cross-platform).
    * No-op when absent. */
   queryPackages?: string[];
+  /** Extra custom URL schemes the system browser (Android Chrome Custom Tabs) may redirect back to
+   * during `kit.oauth` flows — e.g. Google's reversed iOS-client id scheme
+   * `com.googleusercontent.apps.<client>`. On Android the Custom Tab does NOT auto-close; the provider
+   * redirect re-enters the app only via a manifest deep-link intent-filter, so each OAuth redirect
+   * scheme MUST be registered as a BROWSABLE VIEW `<data>` on the main activity — otherwise the
+   * redirect has no handler and the browser web-searches it (lands on google.com). These stamp as
+   * additional `<data android:scheme="..."/>` siblings of `urlScheme`'s deep-link filter. iOS needs no
+   * equivalent — ASWebAuthenticationSession intercepts the callbackScheme directly. No-op when absent. */
+  oauthRedirectSchemes?: string[];
   /** App icon source (≥512px square png). Defaults to the largest icon in the PWA manifest. */
   icon?: string;
   /** Optional centered logo for the iOS launch splash — a TRANSPARENT-background png (a wordmark or
@@ -281,7 +326,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
-  'iosEntitlements', 'neutralizeServiceWorker', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',

package/src/desktop.ts

@@ -44,6 +44,31 @@ export interface DesktopShellConfig {
    * ~/.bun/bin, so a bare `bun` spawn fails. The Rust shell falls back to `bun` when this is
    * missing/nonexistent. */
   handlersRuntime: string;
+  /** True when `modules` includes 'media' → the .app carries an NSMicrophoneUsageDescription so
+   * `getUserMedia` (voice mode) can pass macOS TCC. The WebKit-layer grant (popup_mac) is
+   * unconditional; this only adds the OS usage string an app that actually uses the mic needs. */
+  microphone: boolean;
+  /** Local-server mode. When present the Rust shell boots `command` (+`args`) in a background thread,
+   * polls `http://localhost:<port><healthPath>` until it answers, then navigates the window there
+   * (instead of the bundled dist); it kills the child on window-close. Absent → bundled-PWA load.
+   * `command`/`cwd` are resolved to ABSOLUTE by the CLI (see `regenerateDesktop`) because a
+   * GUI-launched .app has the minimal launchd PATH (no ~/.bun/bin). Empty when the app isn't a
+   * local-server app. */
+  server?: {
+    command: string;
+    args: string[];
+    cwd: string;
+    /** Stdout marker → capture the URL the server prints (dynamic port). '' when using fixed `port`. */
+    urlMarker: string;
+    /** Fixed port (used only when `urlMarker` is ''). 0 when unused. */
+    port: number;
+    https: boolean;
+    healthPath: string;
+    readyTimeoutMs: number;
+    /** PATH the child is spawned with — the CLI stamps its own (build-time) PATH so a GUI launch can
+     * still resolve neighbouring tools (bun, node) the launchd PATH omits. */
+    path: string;
+  };
 }
 
 /** Resolve the desktop shell config from an appwrap config: identity + `urlScheme` come from the
@@ -65,6 +90,21 @@ export function deriveDesktopConfig(cfg: AppwrapConfig): DesktopShellConfig {
     handlers: d.handlers ?? '',
     pushSigned: false, // stamped by the CLI when a signing identity + macOS profile resolve — see buildDesktop
     handlersRuntime: '', // stamped by the CLI (process.execPath) when handlers is set — see regenerateDesktop
+    microphone: (cfg.modules ?? []).includes('media'),
+    // `command`/`cwd`/`path` are resolved to absolute by the CLI (regenerateDesktop); carried as authored here.
+    server: d.server
+      ? {
+          command: d.server.command,
+          args: d.server.args ?? [],
+          cwd: d.server.cwd ?? '',
+          urlMarker: d.server.urlMarker ?? '',
+          port: d.server.port ?? 0,
+          https: d.server.https ?? false,
+          healthPath: d.server.healthPath ?? '/',
+          readyTimeoutMs: d.server.readyTimeoutMs ?? 120_000,
+          path: '',
+        }
+      : undefined,
   };
 }
 
@@ -134,6 +174,13 @@ export function buildInfoPlist(
 	<key>CFBundleIconName</key>
 	<string>${xmlEscape(iconName)}</string>`
     : '';
+  // NSMicrophoneUsageDescription: required for getUserMedia (voice mode) to pass macOS TCC — without
+  // it the OS silently denies mic access (no prompt). Added only when the app declares the `media` module.
+  const mic = shell.microphone
+    ? `
+	<key>NSMicrophoneUsageDescription</key>
+	<string>${xmlEscape(shell.name)} uses the microphone for voice input.</string>`
+    : '';
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -153,7 +200,7 @@ export function buildInfoPlist(
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>NSHighResolutionCapable</key>
-	<true/>${icon}${iconAsset}${urlTypes}
+	<true/>${icon}${iconAsset}${mic}${urlTypes}
 </dict>
 </plist>
 `;