@livx.cc/appwrap 0.37.0 → 0.38.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/shell/config.ts

@@ -40,6 +40,11 @@ export const SHELL_CONFIG = {
    * fights the app:// handler / remote-update detection). On by default; set false to opt out and keep
    * the SW (e.g. for in-WebView web-push). See `serviceWorkerGuardJs`. */
   neutralizeServiceWorker: true,
+  /** iOS App-Bound Domains (from `appwrap.json.appBoundDomains`). When non-empty the shell sets
+   * `WKWebViewConfiguration.limitsNavigationsToAppBoundDomains = true` — Apple's gate for running a
+   * service worker in the WKWebView (the same hosts are stamped to Info.plist `WKAppBoundDomains`).
+   * RESTRICTS the WebView to these domains, so only for single-origin apps. Empty = no restriction. */
+  appBoundDomains: [] as string[],
   /** Open external-origin navigations (`<a>` to another origin, incl. `target="_blank"`, and
    * `window.open(...)`) in the OS default browser (Safari / Chrome) instead of inside the shell
    * WebView — regular-native-app behavior. Same-origin SPA navigation is untouched. Off by default.

package/runtime/app/shell/custom-webview.ios.ts

@@ -180,6 +180,10 @@ export class CustomWebView extends WebView {
     config.allowsPictureInPictureMediaPlayback = true;
     config.mediaTypesRequiringUserActionForPlayback = 0; // WKAudiovisualMediaTypeNone
     config.websiteDataStore = WKWebsiteDataStore.defaultDataStore();
+    // Apple's hard requirement for a service worker in a WKWebView: restrict navigation to the
+    // declared app-bound domains (also stamped to Info.plist WKAppBoundDomains). Only set when
+    // configured — otherwise the WebView stays unrestricted (default behavior).
+    if (SHELL_CONFIG.appBoundDomains?.length) config.limitsNavigationsToAppBoundDomains = true;
 
     // Env hints + framework globals (backend origin) + a getUserMedia guard for UNDECLARED capabilities
     // (must reject in JS before WebKit's native capture path — see mediaCaptureGuardJs) + native-feel

package/src/cli.ts

@@ -22,11 +22,13 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 import type { AppwrapConfig } from './config';
 import {
   androidScreenOrientation,
+  applyBuildNumberFlag,
   iosOrientations,
   mergeManifest,
   resolveBuildNumber,
   stampAndroidOrientation,
   stampAndroidQueries,
+  stampAppBoundDomains,
   stampPlistBackgroundTasks,
   stampPlistOrientations,
   stampPrivacyTracking,
@@ -409,6 +411,7 @@ export const SHELL_CONFIG = {
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
   devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
   neutralizeServiceWorker: ${JSON.stringify(cfg.neutralizeServiceWorker ?? true)},
+  appBoundDomains: ${JSON.stringify(cfg.appBoundDomains ?? [])},
   openNewWindowsInBrowser: ${JSON.stringify(cfg.openNewWindowsInBrowser ?? false)},
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
@@ -447,6 +450,11 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   const bgActive = req.activeOptionalGroups.includes('backgroundTask');
   src = stampPlistBackgroundTasks(src, bgActive ? cfg.backgroundTasks : undefined);
 
+  // iOS App-Bound Domains — gate for a WKWebView service worker (paired with
+  // limitsNavigationsToAppBoundDomains in the shell config). Idempotent both ways: empty/undefined
+  // strips the WKAppBoundDomains key, so it no-ops when the field is absent.
+  src = stampAppBoundDomains(src, cfg.appBoundDomains);
+
   // Permission usage strings + URL scheme + export-compliance — idempotent: strip stamped block, re-add
   src = src.replace(/\s*<!-- appwrap:begin -->[\s\S]*?<!-- appwrap:end -->/g, '');
   const extras: string[] = [];
@@ -525,6 +533,20 @@ function stampTeamId(outDir: string, cfg: AppwrapConfig, ctx?: { cwd: string; co
   writeFileSync(xcconfig, src);
 }
 
+/** Stamp TARGETED_DEVICE_FAMILY into build.xcconfig from cfg.targetedDevices. `'iphone'` → `1`
+ * (iPhone-only → UIDeviceFamily=[1], so the App Store doesn't require iPad screenshots);
+ * `'universal'`/unset → `1,2` (NativeScript's default). Idempotent: replaces any prior value. */
+function stampDeviceFamily(outDir: string, cfg: AppwrapConfig): void {
+  const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
+  if (!existsSync(xcconfig)) return;
+  const value = cfg.targetedDevices === 'iphone' ? '1' : '1,2';
+  let src = readFileSync(xcconfig, 'utf8');
+  src = /TARGETED_DEVICE_FAMILY\s*=/.test(src)
+    ? src.replace(/TARGETED_DEVICE_FAMILY\s*=\s*[^;\n]*;?/, `TARGETED_DEVICE_FAMILY = ${value};`)
+    : src + `\nTARGETED_DEVICE_FAMILY = ${value};\n`;
+  writeFileSync(xcconfig, src);
+}
+
 /** Wire a StoreKit config file for LOCAL iOS IAP testing (no App Store Connect needed).
  * NativeScript copies App_Resources/iOS/* into the generated project and adds it as a file
  * reference — but it never points the scheme at it, so StoreKit has no catalog. We (1) drop the
@@ -1036,6 +1058,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   stampNativeScriptConfig(outDir, cfg);
   stampIOSDisplayName(outDir, cfg, req);
   stampTeamId(outDir, cfg, { cwd, configPath: resolveConfigPath(cwd, opts.flags ?? {}) });
+  stampDeviceFamily(outDir, cfg);
   stampAndroidAppName(outDir, cfg, req);
   stampAndroidVersion(outDir, cfg);
   stampAndroidGradleDeps(outDir, req.androidGradleDeps);
@@ -1158,6 +1181,14 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
     console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first`);
     process.exit(1);
   }
+  // --build-number → process.env.APPWRAP_BUILD_NUMBER before sync() stamps the plist/gradle (same
+  // mechanism `release` uses). Env-var path still honored by sync()'s buildNumberOf when no flag.
+  try {
+    applyBuildNumberFlag(flags['build-number']);
+  } catch (e) {
+    console.error(`✖ ${(e as Error).message}`);
+    process.exit(1);
+  }
   // Make sure the wrapper reflects the latest config + PWA before compiling (also validates the config).
   await sync(cwd, flags);
 
@@ -1207,11 +1238,18 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
  *   --build-number <n>   set the store CFBundleVersion (sets APPWRAP_BUILD_NUMBER for the lane)
  *
  * Signing/ASC config is read from env by the lane (ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_P8 /
- * MATCH_GIT_URL / MATCH_PASSWORD) — secrets never live in appwrap.config. */
-async function release(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
+ * MATCH_GIT_URL / MATCH_PASSWORD) — secrets never live in appwrap.config.
+ *
+ * `appwrap submit ios` reuses this same body with `lane: 'release'` → fastlane `:release`
+ * (`upload_to_app_store`): a binary-only App Store production promote. Metadata/screenshots stay in
+ * ASC; pass `--submit-for-review` to also submit the build for review. */
+async function release(cwd: string, flags: Record<string, string>, positionals: string[], lane: 'beta' | 'release' = 'beta'): Promise<void> {
+  const submit = lane === 'release';
+  const cmd = submit ? 'submit' : 'release';
   const platform = positionals[0];
   if (platform !== 'ios') {
-    console.error('Usage: appwrap release ios [--server-url <url>] [--env <name>] [--build-number <n>] [--config <path>] [--out native]\n' +
+    console.error(`Usage: appwrap ${cmd} ios [--server-url <url>] [--env <name>] [--build-number <n>]` +
+      (submit ? ' [--submit-for-review]' : '') + ' [--config <path>] [--out native]\n' +
       '  (Android: `appwrap build android --release --aab` then `fastlane android beta`.)');
     process.exit(1);
   }
@@ -1239,36 +1277,42 @@ async function release(cwd: string, flags: Record<string, string>, positionals:
   }
   const stampCfg = serverUrl ? { ...cfg, loader: 'server' as const, serverUrl } : cfg;
 
-  // Build number: explicit flag → APPWRAP_BUILD_NUMBER (which the CLI's stamping already honors and
-  // wins over the derived default). In CI the workflow sets APPWRAP_BUILD_NUMBER itself.
-  const env = { ...process.env };
-  if (flags['build-number']) {
-    if (!/^\d+$/.test(flags['build-number'])) {
-      console.error(`✖ --build-number must be a positive integer (got "${flags['build-number']}").`);
-      process.exit(1);
-    }
-    env.APPWRAP_BUILD_NUMBER = flags['build-number'];
+  // Build number: explicit flag → APPWRAP_BUILD_NUMBER. Stamping (sync → stampIOSDisplayName →
+  // buildNumberOf) reads process.env.APPWRAP_BUILD_NUMBER, and sync() runs BEFORE fastlane archives
+  // the (already-stamped) Info.plist — so the flag must land on process.env *here*, before sync(),
+  // not only on the child env. In CI the workflow sets APPWRAP_BUILD_NUMBER itself (env path).
+  try {
+    applyBuildNumberFlag(flags['build-number']);
+  } catch (e) {
+    console.error(`✖ ${(e as Error).message}`);
+    process.exit(1);
   }
+  const env = { ...process.env };
+  // `submit ios --submit-for-review` → also submit the binary for App Store review (the lane defaults
+  // to a safe binary-only promote). The flag is boolean (presence = '' via parseArgs).
+  if (submit && 'submit-for-review' in flags) env.APPWRAP_SUBMIT_FOR_REVIEW = 'true';
 
   // Re-stamp config + copy the latest PWA into native/ so the lane archives current sources. (The lane
   // also runs `ns prepare ios --release`; sync here makes the wrapper config/PWA authoritative first.)
   await sync(cwd, flags);
   if (serverUrl) {
     stampShellConfig(outDir, stampCfg);
-    console.log(`✓ Release loader → ${serverUrl}${flags.env ? ` (env: ${flags.env})` : ''}`);
+    console.log(`✓ ${submit ? 'Submit' : 'Release'} loader → ${serverUrl}${flags.env ? ` (env: ${flags.env})` : ''}`);
   }
 
-  console.log(`▶ fastlane ios beta  (cwd: ${outDir}/fastlane → native/)${env.APPWRAP_BUILD_NUMBER ? `  build #${env.APPWRAP_BUILD_NUMBER}` : ''}`);
+  console.log(`▶ fastlane ios ${lane}  (cwd: ${outDir}/fastlane → native/)${env.APPWRAP_BUILD_NUMBER ? `  build #${env.APPWRAP_BUILD_NUMBER}` : ''}`);
   try {
-    execFileSync('fastlane', ['ios', 'beta'], { cwd: outDir, stdio: 'inherit', env });
+    execFileSync('fastlane', ['ios', lane], { cwd: outDir, stdio: 'inherit', env });
   } catch {
-    console.error('\n✖ TestFlight release failed. Common causes:\n' +
+    console.error(`\n✖ ${submit ? 'App Store submit' : 'TestFlight release'} failed. Common causes:\n` +
       '  • Missing ASC/match env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8 (base64), MATCH_GIT_URL, MATCH_PASSWORD.\n' +
       '  • Certs/profiles not seeded — run `fastlane match appstore` once against MATCH_GIT_URL.\n' +
       '  • CFBundleVersion already used for this marketing version → pass a higher --build-number.');
     process.exit(1);
   }
-  console.log('✓ Uploaded to TestFlight (App Store Connect processing — check the build list / wait for the email).');
+  console.log(submit
+    ? `✓ Binary promoted to the App Store (production)${env.APPWRAP_SUBMIT_FOR_REVIEW === 'true' ? ' and submitted for review' : ' — submit for review in App Store Connect (or pass --submit-for-review)'}.`
+    : '✓ Uploaded to TestFlight (App Store Connect processing — check the build list / wait for the email).');
 }
 
 interface AppleTeam { teamId: string; name: string; email?: string; paid: boolean }
@@ -1808,16 +1852,20 @@ async function main(): Promise<void> {
       await deploy(cwd, flags, positionals);
       break;
     case 'release':
-      await release(cwd, flags, positionals);
+      await release(cwd, flags, positionals, 'beta');
+      break;
+    case 'submit':
+      await release(cwd, flags, positionals, 'release');
       break;
     case 'logs':
       await logs(cwd, flags, positionals);
       break;
     default:
-      console.log('Usage: appwrap <init|sync|dev|build|deploy|release|logs> [--config <path>] [--out native]\n' +
+      console.log('Usage: appwrap <init|sync|dev|build|deploy|release|submit|logs> [--config <path>] [--out native]\n' +
         '  config: appwrap.config.ts (preferred) → .js → appwrap.json\n' +
         '  build <ios|android> [--release] [--aab]   deploy ios [--device <id|name>] [--no-launch]\n' +
         '  release ios [--server-url <url>] [--env <name>] [--build-number <n>]  (build+sign+upload to TestFlight)\n' +
+        '  submit ios [--build-number <n>] [--submit-for-review]  (promote the binary to the App Store; metadata stays in ASC)\n' +
         '  logs ios [--once] [--native]   dev [--url <url> | --port <p>]');
       process.exit(command ? 1 : 0);
   }

package/src/config.ts

@@ -34,6 +34,11 @@ export interface AppwrapConfig {
    * axis; `any` (default) leaves rotation free (sans upside-down on iOS). Stamped into iOS
    * `UISupportedInterfaceOrientations` (+ `~ipad`) and Android `android:screenOrientation`. */
   orientation?: 'portrait' | 'landscape' | 'any';
+  /** iOS targeted device family. `'iphone'` builds an iPhone-only app (TARGETED_DEVICE_FAMILY=1 →
+   * UIDeviceFamily=[1]); `'universal'` (default — NativeScript's behavior) targets iPhone + iPad,
+   * which makes the App Store require a full iPad screenshot set. Set `'iphone'` for a phone-only
+   * app to avoid that requirement. iOS-only; no-op on Android. */
+  targetedDevices?: 'iphone' | 'universal';
   /** Android only (experimental). When true, the WebView draws genuinely edge-to-edge UNDER the
    * transparent system bars (NS `androidOverflowEdge='dont-apply'`) and the real safe-area insets
    * are injected as `--saie-*` CSS vars + native `env(safe-area-inset-*)`, so a multi-theme PWA
@@ -92,6 +97,15 @@ export interface AppwrapConfig {
    * for in-WebView web-push as a fallback. NOTE: keeping the SW is the only way to get web push; native
    * push is the separate `push` lane (APNs/FCM) and does NOT need a SW. */
   neutralizeServiceWorker?: boolean;
+  /** iOS App-Bound Domains — the hosts (no scheme, max 10 per Apple) the WebView may navigate to.
+   * Setting this stamps `WKAppBoundDomains` into Info.plist AND sets
+   * `WKWebViewConfiguration.limitsNavigationsToAppBoundDomains = true`, which is Apple's HARD
+   * requirement for a service worker to run inside a WKWebView. Pair with `neutralizeServiceWorker:false`
+   * to actually enable a SW (this flag is the iOS gate; Android's SW is a separate lane).
+   * TRADEOFF: `limitsNavigationsToAppBoundDomains` RESTRICTS the WebView to exactly these domains —
+   * any navigation/OAuth/redirect to another domain breaks. Only for single-origin apps. Empty/unset =
+   * no change to current behavior (no Info.plist key, no nav restriction). */
+  appBoundDomains?: string[];
   /** Hand navigations that LEAVE the app's own origin to the OS default browser (Safari / Chrome)
    * instead of replacing the shell WebView — so external links and `window.open(...)`/`target="_blank"`
    * behave like a regular native app (open in the system browser) rather than navigating away inside

package/src/derive.ts

@@ -97,6 +97,26 @@ export function resolveBuildNumber(
   return deriveBuild(cfg.version);
 }
 
+/**
+ * Apply a `--build-number` CLI flag to the env so stamping picks it up. The stamping chain
+ * (sync → stampIOSDisplayName/gradle → buildNumberOf → resolveBuildNumber) reads
+ * `APPWRAP_BUILD_NUMBER` off the env, and stamping runs BEFORE the native build/archive — so the
+ * flag must land on the env *before* sync(), not only on a child process env copy.
+ * Returns the validated build-number string (set on `env`), or undefined if no flag was given.
+ * Throws on a non-positive-integer flag so the caller can print + exit.
+ */
+export function applyBuildNumberFlag(
+  flag: string | undefined,
+  env: { APPWRAP_BUILD_NUMBER?: string } = process.env
+): string | undefined {
+  if (flag == null || flag === '') return undefined;
+  if (!/^\d+$/.test(flag)) {
+    throw new Error(`--build-number must be a positive integer (got "${flag}").`);
+  }
+  env.APPWRAP_BUILD_NUMBER = flag;
+  return flag;
+}
+
 /**
  * Collapse a PWA web-manifest `orientation` value to our three states. The manifest spec allows
  * `portrait`/`landscape` plus the `-primary`/`-secondary`/`*-up`/`natural` variants — we don't model
@@ -208,6 +228,27 @@ export function stampPlistBackgroundTasks(src: string, ids: string[] | undefined
   return src;
 }
 
+/**
+ * Stamp (or strip) `WKAppBoundDomains` in an Info.plist string — Apple's gate for running a service
+ * worker inside a WKWebView (paired with `limitsNavigationsToAppBoundDomains` on the config). Pure +
+ * idempotent: rewrites an `appwrap:appbound` marker block (added before `</dict>`), so a re-sync never
+ * duplicates. `domains` empty/undefined → strips the block entirely (no key = current behavior). Apple
+ * caps the array at 10; we stamp what's given. Mirrors `stampPlistOrientations` (pure string transform).
+ */
+export function stampAppBoundDomains(src: string, domains: string[] | undefined): string {
+  src = src.replace(/\s*<!-- appwrap:appbound -->[\s\S]*?<!-- \/appwrap:appbound -->/g, '');
+  const list = (domains ?? []).filter(Boolean);
+  if (list.length) {
+    const items = list.map((d) => `    <string>${d}</string>`).join('\n');
+    const block =
+      `  <!-- appwrap:appbound -->\n` +
+      `  <key>WKAppBoundDomains</key>\n  <array>\n${items}\n  </array>\n` +
+      `  <!-- /appwrap:appbound -->`;
+    src = src.replace(/<\/dict>\s*<\/plist>\s*$/, `${block}\n</dict>\n</plist>\n`);
+  }
+  return src;
+}
+
 /**
  * Stamp the App Tracking Transparency declarations into PrivacyInfo.xcprivacy. Rewrites the two
  * tracking keys IN PLACE (the template ships them, so we never restructure the doc — we only flip

package/templates/ci/fastlane/Fastfile

@@ -36,44 +36,72 @@ def appwrap_prepare_ios
   end
 end
 
-platform :ios do
-  desc 'Build the NativeScript wrapper and upload to TestFlight'
-  lane :beta do
-    setup_ci # on CI: provisions a temporary unlocked keychain so codesign can use the match cert
+# Shared archive-and-sign sequence for BOTH the TestFlight (:beta) and App Store (:release) lanes.
+# Returns the ASC API-key object so each lane can reuse it for its final upload step — the lanes
+# differ ONLY in that final step (upload_to_testflight vs upload_to_app_store). Keep the recipe here,
+# not duplicated per-lane.
+def appwrap_archive_and_sign_ios
+  setup_ci # on CI: provisions a temporary unlocked keychain so codesign can use the match cert
 
-    api_key = app_store_connect_api_key(
-      key_id: ENV['ASC_KEY_ID'],
-      issuer_id: ENV['ASC_ISSUER_ID'],
-      key_content: ENV['ASC_KEY_P8'],
-      is_key_content_base64: true
-    )
+  api_key = app_store_connect_api_key(
+    key_id: ENV['ASC_KEY_ID'],
+    issuer_id: ENV['ASC_ISSUER_ID'],
+    key_content: ENV['ASC_KEY_P8'],
+    is_key_content_base64: true
+  )
 
-    # readonly: certs/profiles must be seeded once via `fastlane match appstore` (see workflow header).
-    match(type: 'appstore', readonly: true, app_identifier: APP_ID,
-          git_url: ENV['MATCH_GIT_URL'], api_key: api_key)
-
-    # NativeScript prepares the Xcode project inside the wrapper dir (native/ = parent of fastlane/).
-    # Wrapped to sanitize the gem env so the system `pod` can find CocoaPods (see appwrap_prepare_ios).
-    appwrap_prepare_ios
-
-    # NS defaults the project to automatic signing → archive can't find a profile. Pin manual signing
-    # to the match-provided App Store profile (name exported by match into ENV).
-    profile = ENV["sigh_#{APP_ID}_appstore_profile-name"] || "match AppStore #{APP_ID}"
-    update_code_signing_settings(
-      use_automatic_signing: false,
-      path: 'platforms/ios/native.xcodeproj',
-      team_id: TEAM_ID,
-      bundle_identifier: APP_ID,
-      code_sign_identity: 'Apple Distribution',
-      profile_name: profile
-    )
+  # readonly: certs/profiles must be seeded once via `fastlane match appstore` (see workflow header).
+  match(type: 'appstore', readonly: true, app_identifier: APP_ID,
+        git_url: ENV['MATCH_GIT_URL'], api_key: api_key)
 
-    build_app(
-      workspace: 'platforms/ios/native.xcworkspace',
-      scheme: 'native',
-      export_method: 'app-store',
-      export_options: { provisioningProfiles: { APP_ID => profile } }
-    )
+  # NativeScript prepares the Xcode project inside the wrapper dir (native/ = parent of fastlane/).
+  # Wrapped to sanitize the gem env so the system `pod` can find CocoaPods (see appwrap_prepare_ios).
+  appwrap_prepare_ios
+
+  # NS defaults the project to automatic signing → archive can't find a profile. Pin manual signing
+  # to the match-provided App Store profile (name exported by match into ENV).
+  profile = ENV["sigh_#{APP_ID}_appstore_profile-name"] || "match AppStore #{APP_ID}"
+  update_code_signing_settings(
+    use_automatic_signing: false,
+    path: 'platforms/ios/native.xcodeproj',
+    team_id: TEAM_ID,
+    bundle_identifier: APP_ID,
+    code_sign_identity: 'Apple Distribution',
+    profile_name: profile
+  )
+
+  build_app(
+    workspace: 'platforms/ios/native.xcworkspace',
+    scheme: 'native',
+    export_method: 'app-store',
+    export_options: { provisioningProfiles: { APP_ID => profile } }
+  )
+
+  api_key
+end
+
+# Restore the login keychain as the system default and drop fastlane's temp keychain. `setup_ci`/`match`
+# create `fastlane_tmp_keychain` and point the default keychain at it; if a lane dies mid-run before
+# fastlane's own teardown, that stray keychain is left as the DEFAULT — so macOS (com.apple.iCloudHelper
+# etc.) keeps prompting for its password forever. CI runners are ephemeral so this is a no-op there;
+# locally it prevents the recurring keychain prompt. Best-effort: never fail the lane on cleanup.
+def appwrap_keychain_cleanup
+  login = File.expand_path('~/Library/Keychains/login.keychain-db')
+  return unless File.exist?(login)
+  sh("security default-keychain -s '#{login}'", error_callback: ->(_) {})
+  sh('security delete-keychain ~/Library/Keychains/fastlane_tmp_keychain-db 2>/dev/null || true',
+     error_callback: ->(_) {})
+rescue StandardError => e
+  UI.message("keychain cleanup skipped: #{e}")
+end
+
+platform :ios do
+  after_all { appwrap_keychain_cleanup }
+  error { |_lane, _exception| appwrap_keychain_cleanup }
+
+  desc 'Build the NativeScript wrapper and upload to TestFlight'
+  lane :beta do
+    api_key = appwrap_archive_and_sign_ios
 
     # Wait for App Store Connect to finish processing and FAIL if it doesn't — Apple can accept the
     # upload yet silently drop the build (e.g. an out-of-range CFBundleVersion). skip:true hides that.
@@ -85,6 +113,26 @@ platform :ios do
     tf_wait_timeout = tf_wait_env.to_i > 0 ? tf_wait_env.to_i : 3600
     upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: false, wait_processing_timeout_duration: tf_wait_timeout)
   end
+
+  desc 'Build the NativeScript wrapper and promote the binary to the App Store (production).'
+  lane :release do
+    api_key = appwrap_archive_and_sign_ios
+
+    # Binary-only promote: the listing/metadata/screenshots/IAP stay in App Store Connect — this lane
+    # only ships the signed binary. SAFE by default: no review submit, no automatic release, headless
+    # (force: true → no HTML preview). Set APPWRAP_SUBMIT_FOR_REVIEW=true to also submit for review.
+    # Guard BOTH unset (nil) and blank env the same way as APPWRAP_TF_WAIT_TIMEOUT above.
+    submit_for_review = ENV['APPWRAP_SUBMIT_FOR_REVIEW'].to_s.strip.downcase == 'true'
+    upload_to_app_store(
+      api_key: api_key,
+      submit_for_review: submit_for_review,
+      automatic_release: false,
+      skip_metadata: true,
+      skip_screenshots: true,
+      precheck_include_in_app_purchases: false,
+      force: true
+    )
+  end
 end
 
 platform :android do