@livx.cc/appwrap 0.36.1 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.36.1",
+  "version": "0.37.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

@@ -87,6 +87,12 @@ function resolveAssetRoot(rel: string): string {
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
 
+/** 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")
+ * until that version is published, instead of bunx silently resolving an older published build that
+ * lacks `release`/`init` flags. package.json sits one level above src/ (published) or the monorepo dir. */
+const CLI_VERSION: string = (await import(resolve(import.meta.dir, '..', 'package.json'), { with: { type: 'json' } })).default.version;
+
 // Load the capability manifest VALUES from the resolved runtime (pure data — safe outside NativeScript).
 // Top-level await resolves before any command dispatches at the bottom of this file.
 const { MODULES, OPTIONAL_GROUPS } = (await import(
@@ -959,23 +965,34 @@ 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/). Never overwrites. */
-function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig): void {
+/** Emit CI scaffolding (GH Actions → git repo root, fastlane → native/).
+ * 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 {
   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.
-  const targets: Array<[string, string]> = [[join(CI_TEMPLATE_DIR, 'fastlane'), join(outDir, 'fastlane')]];
+  // [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)) {
     console.log('  ci   ← GH Actions scaffold skipped (inside the appwrap framework repo — manages its own CI)');
   } else {
-    targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows')]);
+    targets.unshift([join(CI_TEMPLATE_DIR, 'github/workflows'), join(repoRoot, '.github/workflows'), false]);
   }
-  for (const [from, to] of targets) {
+  for (const [from, to, overwrite] of targets) {
     mkdirSync(to, { recursive: true });
-    cpSync(from, to, { recursive: true, force: false, errorOnExist: false });
+    cpSync(from, to, { recursive: true, force: overwrite, errorOnExist: false });
+  }
+  // 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)) {
+    const wf = join(repoRoot, '.github/workflows/appwrap-release-ios.yml');
+    if (existsSync(wf)) writeFileSync(wf, readFileSync(wf, 'utf8').replaceAll('__APPWRAP_VERSION__', CLI_VERSION));
   }
   // Stamp the app id + team into the emitted fastlane (signing needs them; the templates ship
   // `__APP_ID__`/`__TEAM_ID__` placeholders). Idempotent: re-init finds no placeholders → no-op.
@@ -1060,7 +1077,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); // first-time scaffold (never overwrites)
+  copyCiTemplates(cwd, outDir, cfg, 'force' in flags); // GH workflows: 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
   stampVersionManifest(outDir, cfg); // provenance — also marks the dir appwrap-managed
@@ -1176,6 +1193,84 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
   }
 }
 
+/** `appwrap release ios` — the ONE build+sign+upload-to-TestFlight command, identical locally and in CI.
+ *
+ * It re-stamps the config + PWA (`sync`) and then delegates the full archive/sign/upload to the emitted
+ * fastlane lane (`native/fastlane` `:beta`) — the SINGLE source of truth for the iOS release recipe (the
+ * lane runs `ns prepare ios --release` → match signing → build_app → upload_to_testflight). CI is a thin
+ * wrapper that just calls this. Keeping the recipe in fastlane (not duplicated in TS) means local and CI
+ * run byte-identical steps.
+ *
+ * Knobs (all optional; mirror the workflow):
+ *   --server-url <url>   override loader:'server' serverUrl for this release (lab vs prod backend)
+ *   --env <name>         convenience: resolve serverUrl from cfg.envs[name] when present (see config)
+ *   --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> {
+  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' +
+      '  (Android: `appwrap build android --release --aab` then `fastlane android beta`.)');
+    process.exit(1);
+  }
+  const cfg = await loadConfig(cwd, flags);
+  const outDir = resolve(cwd, flags.out ?? 'native');
+  if (!existsSync(outDir)) {
+    console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first (CI must \`init\`, native/ is gitignored).`);
+    process.exit(1);
+  }
+  const fastfile = join(outDir, 'fastlane', 'Fastfile');
+  if (!existsSync(fastfile)) {
+    console.error(`✖ No fastlane lane at ${fastfile} — run \`appwrap init\` to emit it (it carries the release recipe).`);
+    process.exit(1);
+  }
+
+  // Optional backend-url override for loader:'server' apps (lab vs prod). --server-url wins; else
+  // --env resolves from cfg.envs[name] when the consumer config declares it.
+  let serverUrl = flags['server-url'] || undefined;
+  if (!serverUrl && flags.env) {
+    serverUrl = (cfg as { envs?: Record<string, string> }).envs?.[flags.env];
+    if (!serverUrl) {
+      console.error(`✖ --env ${flags.env} given but cfg.envs[${flags.env}] is not set in the config.`);
+      process.exit(1);
+    }
+  }
+  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'];
+  }
+
+  // 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(`▶ fastlane ios beta  (cwd: ${outDir}/fastlane → native/)${env.APPWRAP_BUILD_NUMBER ? `  build #${env.APPWRAP_BUILD_NUMBER}` : ''}`);
+  try {
+    execFileSync('fastlane', ['ios', 'beta'], { cwd: outDir, stdio: 'inherit', env });
+  } catch {
+    console.error('\n✖ 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).');
+}
+
 interface AppleTeam { teamId: string; name: string; email?: string; paid: boolean }
 interface DeviceInfo { id: string; name: string; model: string; transport: string }
 
@@ -1712,13 +1807,17 @@ async function main(): Promise<void> {
     case 'deploy':
       await deploy(cwd, flags, positionals);
       break;
+    case 'release':
+      await release(cwd, flags, positionals);
+      break;
     case 'logs':
       await logs(cwd, flags, positionals);
       break;
     default:
-      console.log('Usage: appwrap <init|sync|dev|build|deploy|logs> [--config <path>] [--out native]\n' +
+      console.log('Usage: appwrap <init|sync|dev|build|deploy|release|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' +
         '  logs ios [--once] [--native]   dev [--url <url> | --port <p>]');
       process.exit(command ? 1 : 0);
   }

package/templates/ci/fastlane/Fastfile

@@ -6,6 +6,36 @@ default_platform(:ios)
 APP_ID = '__APP_ID__'.freeze
 TEAM_ID = '__TEAM_ID__'.freeze
 
+# Run `ns prepare` (which shells out to `pod install`) with a SANITIZED gem env.
+#
+# Why: fastlane runs under its own Ruby and exports GEM_HOME/GEM_PATH into every child process. On a
+# Mac, NativeScript's `pod` is the system one (`/usr/local/bin/pod`, shebang-pinned to Ruby 2.6, whose
+# CocoaPods lives in /Library/Ruby/Gems/2.6.0). The inherited GEM_HOME redirects its gem lookup to
+# fastlane's Ruby dir → `can't find gem cocoapods (Gem::GemNotFoundException)` → NS prints
+# `'arch install' command failed` (exit 127). Interactively `pod` works because no GEM_HOME is set.
+#
+# Fix: only when the active `pod` is that system-Ruby-2.6 binary, drop the leaked GEM_* vars so it
+# falls back to its own default gem dir. CI runners use a self-managed Ruby (setup-ruby) whose `pod`
+# is NOT the system 2.6 one, so the env is left untouched there — no behavior change on CI.
+def appwrap_prepare_ios
+  prepare = "cd '#{File.expand_path('..', __dir__)}' && ns prepare ios --release"
+  pod = `command -v pod`.strip
+  system_pod = !pod.empty? && File.exist?(pod) &&
+               File.read(pod, 256).include?('Ruby.framework/Versions/2.6')
+  unless system_pod
+    sh(prepare)
+    return
+  end
+  leaked = %w[GEM_HOME GEM_PATH RUBYLIB RUBYOPT BUNDLE_GEMFILE BUNDLE_BIN_PATH]
+  saved = {}
+  leaked.each { |k| saved[k] = ENV[k]; ENV.delete(k) }
+  begin
+    sh(prepare)
+  ensure
+    saved.each { |k, v| ENV[k] = v unless v.nil? }
+  end
+end
+
 platform :ios do
   desc 'Build the NativeScript wrapper and upload to TestFlight'
   lane :beta do
@@ -23,7 +53,8 @@ platform :ios do
           git_url: ENV['MATCH_GIT_URL'], api_key: api_key)
 
     # NativeScript prepares the Xcode project inside the wrapper dir (native/ = parent of fastlane/).
-    sh("cd '#{File.expand_path('..', __dir__)}' && ns prepare ios --release")
+    # 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).

package/templates/ci/github/workflows/appwrap-release-ios.yml

@@ -34,7 +34,13 @@ jobs:
       - run: bun install && bun run build
       # Pin global tools — unpinned installs can grab a breaking release mid-flight. Bump deliberately.
       - run: npm i -g nativescript@9.0.6
-      - run: bunx @livx.cc/appwrap init # native/ is generated (gitignored) — regenerate it fresh in CI
+      # bunx is PINNED to the appwrap version that emitted this workflow (stamped at `init`). Pinning is
+      # load-bearing: an UNPINNED `bunx @livx.cc/appwrap` resolves to whatever is currently published,
+      # which may pre-date the `init`/`release` commands and would silently run old code + exit 1 with a
+      # confusing usage dump. With the pin, CI fails LOUDLY ("No matching version") until that version is
+      # published to the @livx.cc registry. PUBLISH-ORDERING: publish the appwrap CLI BEFORE the first CI
+      # run that uses a freshly-emitted workflow.
+      - run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ init # native/ is generated (gitignored) — regenerate it fresh in CI
       - working-directory: native
         run: npm install
       - uses: ruby/setup-ruby@v1
@@ -47,14 +53,15 @@ jobs:
           chmod 600 ~/.ssh/match_deploy_key
           printf 'Host github.com\n  IdentityFile ~/.ssh/match_deploy_key\n  IdentitiesOnly yes\n' >> ~/.ssh/config
           ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
+      # Single source of truth: the SAME command a developer runs locally. It re-stamps native/ and
+      # delegates the full archive/sign/upload to the emitted fastlane lane — no fastlane logic here.
       - name: Build & upload to TestFlight
-        working-directory: native
         env:
           MATCH_GIT_URL: ${{ secrets.MATCH_GIT_URL }}
           MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
           ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
           ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
           ASC_KEY_P8: ${{ secrets.ASC_KEY_P8 }}
-        run: fastlane ios beta
+        run: bunx @livx.cc/appwrap@^__APPWRAP_VERSION__ release ios
 
   # Production promotion is a manual gate: promote the TestFlight build in App Store Connect.