@livx.cc/appwrap 0.28.2 → 0.29.0

package/package.json

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

package/src/cli.ts

@@ -24,6 +24,7 @@ import {
   androidScreenOrientation,
   iosOrientations,
   mergeManifest,
+  resolveBuildNumber,
   stampAndroidOrientation,
   stampAndroidQueries,
   stampPlistBackgroundTasks,
@@ -45,31 +46,15 @@ const execErrText = (e: unknown): string => {
   return `${err.stdout ?? ''}${err.stderr ?? ''}`;
 };
 
-/** Marketing version → a monotonic integer build (0.2.1 → 201; 1.4.12 → 10412). Stable & increasing
- * across semver bumps so store re-uploads are always accepted without a manual bump. */
-function deriveBuild(version: string): number {
-  const [maj = 0, min = 0, patch = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
-  return maj * 10000 + min * 100 + patch;
-}
-
 /**
- * Resolved monotonic build number (iOS CFBundleVersion / Android versionCode).
- * Precedence: `APPWRAP_BUILD_NUMBER` env (CI run #) > explicit `cfg.buildNumber` > derived from version.
- * The env override means CI gets a monotonic, collision-free build number for free — no per-app config
- * plumbing — which is the whole point: the derived default is CONSTANT per version, so repeat uploads
- * of the same marketing version would 409 ("build already exists") without it.
+ * Resolved monotonic build number (iOS CFBundleVersion / Android versionCode). Thin env wrapper over
+ * the pure `resolveBuildNumber` (in derive.ts, where it unit-tests). Precedence: `APPWRAP_BUILD_NUMBER`
+ * env (CI run #) > explicit numeric `cfg.buildNumber` > named strategy ('timestamp'|'epoch') > derived
+ * from version. The env override gives CI a monotonic, collision-free build for free; the derived
+ * default is CONSTANT per version, so repeat uploads of one marketing version would 409 without it.
  */
 function buildNumberOf(cfg: AppwrapConfig): number {
-  const env = process.env.APPWRAP_BUILD_NUMBER;
-  if (env != null && env !== '') {
-    const n = parseInt(env, 10);
-    if (!Number.isNaN(n)) return n;
-  }
-  if (cfg.buildNumber != null) {
-    const n = parseInt(String(cfg.buildNumber), 10);
-    if (!Number.isNaN(n)) return n;
-  }
-  return deriveBuild(cfg.version);
+  return resolveBuildNumber(cfg, process.env.APPWRAP_BUILD_NUMBER);
 }
 
 const IOS_PERMISSION_KEYS: Record<string, string[]> = {

package/src/config.ts

@@ -113,8 +113,12 @@ export interface AppwrapConfig {
   >;
   /** Monotonic build identifier. Stores reject a re-upload unless this is HIGHER than the last:
    * iOS `CFBundleVersion`, Android `versionCode` (the marketing `version` stays the user-facing
-   * string). Default: an integer derived from `version` (0.2.1 → 201). Set explicitly from a CI
-   * run number for fleet builds of the same marketing version. */
+   * string). Default: an integer derived from `version` (0.2.1 → 201). Set an explicit number from a
+   * CI run for fleet builds of one marketing version, OR a named strategy string (resolved by the
+   * framework so it can't drift across branches):
+   *   - `'timestamp'` — YYMMDDHHMM UTC (e.g. 2606221405). iOS-ONLY: exceeds Android's versionCode cap.
+   *   - `'epoch'` — unix seconds. Android-safe.
+   * (`APPWRAP_BUILD_NUMBER` env always wins; an unknown string falls back to the derived default.) */
   buildNumber?: string | number;
   /** iOS export-compliance. `ITSAppUsesNonExemptEncryption` — stamped `false` by default (skips the
    * per-upload prompt). Set `true` only if the app uses non-exempt encryption. */

package/src/derive.ts

@@ -47,6 +47,56 @@ export function mergeManifest<
   return cfg;
 }
 
+/** Marketing version → a monotonic integer build (0.2.1 → 201; 1.4.12 → 10412). Stable & increasing
+ * across semver bumps so store re-uploads are always accepted without a manual bump. */
+export function deriveBuild(version: string): number {
+  const [maj = 0, min = 0, patch = 0] = version.split('.').map((n) => parseInt(n, 10) || 0);
+  return maj * 10000 + min * 100 + patch;
+}
+
+/** Named build-number strategies. Live ONCE here so apps opt into a name instead of copying the
+ * stamping logic into their config (which drifts across branches). All return a single integer.
+ *  - `timestamp`: human-readable YYMMDDHHMM (UTC), e.g. 2026-06-22 14:05 → 2606221405. ≈2.6e9, ≤ the
+ *    iOS CFBundleVersion UInt32 cap (4294967295) until ~2042 — but it EXCEEDS Android versionCode's
+ *    2.1e9 cap, so this strategy is iOS-ONLY.
+ *  - `epoch`: unix seconds (Math.floor(Date.now()/1000)), ≈1.78e9 — Android-safe. */
+const BUILD_STRATEGIES: Record<string, (now: Date) => number> = {
+  timestamp: (now) => {
+    const p = (n: number) => String(n).padStart(2, '0');
+    const yy = now.getUTCFullYear() % 100;
+    return Number(
+      `${p(yy)}${p(now.getUTCMonth() + 1)}${p(now.getUTCDate())}${p(now.getUTCHours())}${p(now.getUTCMinutes())}`
+    );
+  },
+  epoch: (now) => Math.floor(now.getTime() / 1000),
+};
+
+/**
+ * Resolve the monotonic build number (iOS CFBundleVersion / Android versionCode). Pure: the CLI
+ * passes the `APPWRAP_BUILD_NUMBER` env value in (no process.env read here, so it unit-tests).
+ * Precedence: env (CI run #) > explicit numeric `buildNumber` > named strategy > derived from version.
+ * An unrecognized strategy string falls back to `deriveBuild` (never crashes).
+ */
+export function resolveBuildNumber(
+  cfg: { version: string; buildNumber?: string | number },
+  envBuildNumber?: string,
+  now: Date = new Date()
+): number {
+  if (envBuildNumber != null && envBuildNumber !== '') {
+    const n = parseInt(envBuildNumber, 10);
+    if (!Number.isNaN(n)) return n;
+  }
+  if (cfg.buildNumber != null) {
+    // A numeric value (number or numeric string) is the literal build number.
+    const n = parseInt(String(cfg.buildNumber), 10);
+    if (!Number.isNaN(n)) return n;
+    // Non-numeric → a strategy NAME. Map it, or fall back to deriveBuild for an unknown string.
+    const strategy = BUILD_STRATEGIES[String(cfg.buildNumber).trim()];
+    if (strategy) return strategy(now);
+  }
+  return deriveBuild(cfg.version);
+}
+
 /**
  * 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

package/templates/ci/fastlane/Fastfile

@@ -46,7 +46,13 @@ platform :ios do
 
     # 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.
-    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: false, wait_processing_timeout_duration: 1800)
+    # APPWRAP_TF_WAIT_TIMEOUT (seconds) tunes the wait: real builds can exceed 30 min under Apple
+    # processing load and crash the lane (BuildWatcher exceeded) — default to 1h, raise it if needed.
+    # Guard BOTH unset (nil) and empty/blank env: nil.to_i and "".to_i are 0, which would crash the
+    # lane instantly (BuildWatcher exceeded '0'). Only a positive integer overrides the 3600 default.
+    tf_wait_env = ENV['APPWRAP_TF_WAIT_TIMEOUT'].to_s.strip
+    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
 end