@wix/himalaya-cli 0.1466.0 → 0.1467.0

package/dist/cli.mjs

@@ -185850,7 +185850,8 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "from-base44-cli",
   "no-browser",
   "refresh-wix",
-  "empty-app-ok"
+  "empty-app-ok",
+  "aab"
 ]);
 var SHELL_ENUM = SHELL_NAMES2.join("|");
 var SWITCH_FLAGS = new Set([...BOOLEAN_FLAGS].filter((name) => name !== "deep"));
@@ -186355,7 +186356,7 @@ var USAGE2 = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                              minBinaryVersion \u2014 all named in the output.
   himi dist [--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>]
             [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo]
-            [--android-signing qa-keystore|wix-keystore|debug]
+            [--android-signing qa-keystore|wix-keystore|debug] [--aab]
             [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan]
                                            build an INSTALLABLE QA binary (signed IPA / APK) on
                                            the Wix Job Service Mac pool and hand back an install
@@ -186390,6 +186391,13 @@ var USAGE2 = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            wix-keystore (the pool's own Wix key, when the machine
                                            carries one \u2014 fails loudly if not), or debug (the old
                                            per-machine key; QA must uninstall first).
+                                           --aab builds an Android App Bundle (.aab) instead of
+                                           an APK, to upload to Google Play yourself: you get a
+                                           download link and its sha256, and no install link or
+                                           QR (a bundle does not install on a device). Android
+                                           only. Signed with the Wix production key (wix-keystore,
+                                           the upload key Branded apps use); any other
+                                           --android-signing is refused. The default stays an APK.
                                            --borrow-ios-id is an
                                            iOS-only interim: sign under an internal enterprise id the
                                            pool already has a profile for (e.g. ent.wix.time.dev); the
@@ -186836,7 +186844,7 @@ var COMMANDS2 = [
   { name: "patch", summary: 'change ONE item of a published app \u2014 a screen descriptor, a Tier-5 bundle, tokens, or the app-config baseline \u2014 from a RAW FILE, with no content package and no build. The low-level door: it does not lint your package, because there is no package here; `himi push --only <selector>` is the same edit with the full build + lint gate and is what to reach for when the package is in hand. Derives a new release from the app\'s current LIVE release, or from `--from-release <id>`. An explicit `--draft` or `--live` is REQUIRED \u2014 a patch has no default blast radius \u2014 and `--notes` is required with `--live` on a screen or app-config patch, because off-repo `gitSha` is "dev" and the ledger notes are then the only durable record of bytes that correspond to no commit. A branch does not merge: activating one derived from an older release reverts every item the patch does not move, so that case is refused until `--accept-regressions`. A bundle patch must repoint a screen (`--for-screen`) or the bytes land under a manifest key nothing reads. It cannot ADD a screen (screens are git-only, RFC 0012), never claims a slug \u2014 the app must already be published \u2014 and carries no attestation, source archive, assets, icon or minBinaryVersion, each named in the output.', required: "screen <id> --file <descriptor.json> [--bundle <sha256|none>] | bundle --file <bundle.js> (--for-screen <id>[,<id>] | --no-rebind) | tokens --file <tokens.json> | app-config --file <app-config.json> ; (--draft|--live) --app <a> [--from-release <id>] [--accept-regressions] [--label <n>] [--notes <t>] [--force] [--allow-binary-gap] [--target <t>] (--control-token)" },
   { name: "flags", summary: "read and change the app's OPERATIONAL flags (RFC 0013) \u2014 `list` prints what the DEVICE door serves, `set <key> --definition` creates or replaces one, `ramp <key>` moves its rollout share or kills it, `rm <key>` deletes it and echoes the definition back so the removal is reversible. Every write is followed by a read of the same door the device uses, and the answer is reported as `servedNow`: flags are stored in the app's git-committed flags.json, so a control plane with no checkout accepts a write it will never serve.", required: "list|set|ramp|rm [<key>] [--definition <json|@file>] [--percent 0-100] [--enabled true|false] [--app <a>] (--control-token)" },
   { name: "visibility", summary: "read (no value) or set whether the public registry (/v1/apps + the Himi Player picker) LISTS the app. `public` lists it for everyone; `unlisted` hides it from listings while direct reads by app id \u2014 deep links, previews \u2014 keep working. App from --app or the content dir. Setting it needs no republish.", required: "[public|unlisted] [--app <a>] [--content <dir>] (--control-token)" },
-  { name: "dist", summary: "build an INSTALLABLE QA binary (signed IPA / APK) on the Wix Job Service Mac pool and return an install link \u2014 the serve plane brokers the job, the pool builds it. WAITS for the build by default (~4 min) and prints the install link; `--no-wait` returns a jobId immediately instead. Omitting `--release` builds whatever is LIVE for the app. A named draft is refused unless `--allow-draft` makes that exceptional build explicit. `status <jobId>` / `watch <jobId>` / `list --app <a>` / `cancel <jobId>` inspect and stop builds (`watch` reports up front whether the job mints its own signing identity or borrows one, so a doomed iOS build is cancellable in seconds rather than after the archive). Off-repo, name a target \u2014 `--target wix` for a self-serve Wix login or `--target bo` for the internal employee path (the in-repo default is a local dev plane that isn't reachable off-repo); self-serve callers may build their OWN apps under a tighter budget (2 in flight / 5 per 24h), while a manage-only owner-role credential is refused. `--shell` picks the native host to sign into (branded-lite | owner-lite | brandy | base44 | player | demo-app) and defaults to the content package's himalaya.content.json `shell` (templates carry the one they were written for), else branded-lite. The per-app shells ADD the release's declared capabilities to the binary, while Himi Player and demo-app refuse a release declaring one they lack; `--plan` previews it without building; `brandy` is the site shell \u2014 the customer's own website as native-framed tabs. `--signing` defaults to `wix-managed` \u2014 the Wix Apple account mints a per-app signing identity for the build, so the caller provisions no Apple credentials of their own; `--signing byo --site <id>` reuses an existing customer ad-hoc profile and certificate for iOS; requires an owned site and a completed personal signing binding. `--android-signing` is the Android counterpart and a SEPARATE axis (a keystore, not an Apple account): `qa-keystore` (default \u2014 the repo's committed QA key, identical on every pool machine, so a build installs over the previous one), `wix-keystore` (the Wix key the pool machine carries; the build FAILS naming the paths searched if it carries none, rather than quietly signing with something else), or `debug` (the old per-machine key \u2014 QA must uninstall any previous build first). NOT the normal way to ship: screens, Tier-5 bundles, tokens and app-config all go over the air with `himi push` in seconds \u2014 a binary trip is only needed for a NATIVE delta (a new SDUI component, a new declared capability/entitlement, a new bundle id, or a minBinaryVersion floor bump). Refuses to build an app whose launcher icon is missing, a placeholder, or one a store would reject \u2014 the one thing a binary carries that no later OTA push can fix; `--force` builds anyway", required: "[--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>] [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo] [--site <id>] [--android-signing qa-keystore|wix-keystore|debug] [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan] | status <jobId> [--target <t>] | watch <jobId> [--target <t>] [--interval <ms>] | list --app <a> [--target <t>] | cancel <jobId> [--target <t>]" },
+  { name: "dist", summary: "build an INSTALLABLE QA binary (signed IPA / APK) on the Wix Job Service Mac pool and return an install link \u2014 the serve plane brokers the job, the pool builds it. WAITS for the build by default (~4 min) and prints the install link; `--no-wait` returns a jobId immediately instead. Omitting `--release` builds whatever is LIVE for the app. A named draft is refused unless `--allow-draft` makes that exceptional build explicit. `status <jobId>` / `watch <jobId>` / `list --app <a>` / `cancel <jobId>` inspect and stop builds (`watch` reports up front whether the job mints its own signing identity or borrows one, so a doomed iOS build is cancellable in seconds rather than after the archive). Off-repo, name a target \u2014 `--target wix` for a self-serve Wix login or `--target bo` for the internal employee path (the in-repo default is a local dev plane that isn't reachable off-repo); self-serve callers may build their OWN apps under a tighter budget (2 in flight / 5 per 24h), while a manage-only owner-role credential is refused. `--shell` picks the native host to sign into (branded-lite | owner-lite | brandy | base44 | player | demo-app) and defaults to the content package's himalaya.content.json `shell` (templates carry the one they were written for), else branded-lite. The per-app shells ADD the release's declared capabilities to the binary, while Himi Player and demo-app refuse a release declaring one they lack; `--plan` previews it without building; `brandy` is the site shell \u2014 the customer's own website as native-framed tabs. `--signing` defaults to `wix-managed` \u2014 the Wix Apple account mints a per-app signing identity for the build, so the caller provisions no Apple credentials of their own; `--signing byo --site <id>` reuses an existing customer ad-hoc profile and certificate for iOS; requires an owned site and a completed personal signing binding. `--android-signing` is the Android counterpart and a SEPARATE axis (a keystore, not an Apple account): `qa-keystore` (default \u2014 the repo's committed QA key, identical on every pool machine, so a build installs over the previous one), `wix-keystore` (the Wix key the pool machine carries; the build FAILS naming the paths searched if it carries none, rather than quietly signing with something else), or `debug` (the old per-machine key \u2014 QA must uninstall any previous build first). `--aab` builds an Android App Bundle (.aab) for the owner to upload to Google Play instead of an APK \u2014 a download link and sha256, no install link (a bundle does not install on a device); Android only, signed with the Wix production key (`wix-keystore`, the upload key Branded apps use) \u2014 any other `--android-signing` is refused, and it is limited to internal callers (a self-serve caller gets 403 android_format_not_allowed). NOT the normal way to ship: screens, Tier-5 bundles, tokens and app-config all go over the air with `himi push` in seconds \u2014 a binary trip is only needed for a NATIVE delta (a new SDUI component, a new declared capability/entitlement, a new bundle id, or a minBinaryVersion floor bump). Refuses to build an app whose launcher icon is missing, a placeholder, or one a store would reject \u2014 the one thing a binary carries that no later OTA push can fix; `--force` builds anyway", required: "[--app <a>] [--platform ios,android] [--release <id>] [--allow-draft] [--target <t>] [--shell branded-lite|owner-lite|brandy|base44|player|demo-app] [--signing wix-managed|byo] [--site <id>] [--android-signing qa-keystore|wix-keystore|debug] [--aab] [--borrow-ios-id <bundleId>] [--no-wait] [--force] [--plan] | status <jobId> [--target <t>] | watch <jobId> [--target <t>] [--interval <ms>] | list --app <a> [--target <t>] | cancel <jobId> [--target <t>]" },
   { name: "testflight", summary: 'build, sign and upload an app to TestFlight (internal testers \u2014 no Beta App Review), then WAIT until App Store Connect finishes processing it. Sugar for `store upload --track testflight`. Prompts first: a build number is consumed permanently on a real Apple account and cannot be reused \u2014 `--yes` for CI, `--dry-run` to see the plan without touching anything. The wait is the real check, not a nicety: fastlane prints "Successfully uploaded" for a binary App Store Connect then rejects in processing, and a rejected binary leaves NO build record at all (the reason is emailed). Public App Store review is deliberately NOT automatable here \u2014 `--track appstore` is refused; use /submit-ios-app when you mean to go public', required: "<app> [--track testflight|internal] [--profile <name>] [--yes] [--dry-run] [--skip-build] [--no-wait] [--json]" },
   { name: "store", summary: "the App Store Connect group behind `testflight`. `preflight <app>` checks readiness offline (icon, entitlements, encryption flag, version, store.config ids, listing + review record); `upload <app>` is what `testflight` runs; `status <app>` reads live build + processing state. `--profile` selects WHICH App Store Connect account: an app built for a Wix customer ships under the CUSTOMER's Apple team (Apple guideline 4.2.6 forbids an app-generation service submitting on a client's behalf), declared per-app as ios.credentialProfile in store.config.yaml and resolved from ~/.himalaya/store-credentials/<name>.json \u2014 the .p8 itself never enters the repo. `iap draft|plan|apply|status|connect|screenshots` registers an app owner's digital products as in-app purchases (non-consumables, or consumable price tiers): draft reads the Wix catalog and writes the manifest, plan and status only read, apply is the one App Store mutation boundary, connect readies the Wix site to sell them (purchases app, In-App Purchase key, appleIAP provider, product mappings; --preview-tag routes only its Serve calls to a deploy preview), screenshots renders each product's purchase screen from the app (--content) as a bound iPhone shows it to a signed-in member and names the 1290\xD72796 PNG as the item's App Review screenshot, and none of them builds, signs or needs a checkout (`himi docs iap-products`)", required: "preflight <app> [--profile <n>] | upload <app> [--track <t>] [--profile <n>] [--yes] [--dry-run] | status <app> [--profile <n>] | iap draft --site <msid> --profile <n> --apple-app <id> --bundle <id> --base-territory <t> --out <f> [--territories <a,b>] [--locale <l>] [--mode per-item|tiers] [--merge <f>] [--report <f>] [--json] | iap plan --manifest <f> --profile <n> --out <f> [--json] | iap apply --plan <f> --profile <n> --out <f> [--yes] [--limit <n>] [--json] | iap status --manifest <f> --profile <n> [--out <f>] [--json] | iap connect --manifest <f> --profile <n> [--iap-key <AuthKey.p8> --iap-key-id <id>] [--content <dir>] [--preview-tag dp-<tag>] [--dry-run] [--yes] [--out <f>] [--json] | iap screenshots --manifest <f> --content <dir> [--profile <n>] [--out-dir <d>] [--only <id,\u2026>] [--force] [--dry-run] [--json]" },
   { name: "guide", summary: "print the Himalaya overview + headless dev loop + available topics (offline)", required: "[--json]" },
@@ -193474,6 +193482,11 @@ ${label3}`);
           };
           render("  Himi Player", player);
           if (job.status !== "SUCCESS") return;
+          if (job.platform === "android" && job.androidFormat === "aab") {
+            io2.log("  android bundle");
+            io2.log("  QR omitted (an .aab is uploaded to Google Play; it does not install on a device)");
+            return;
+          }
           const shortUrl = `${origin.replace(/\/+$/, "")}/v1/dist/${encodeURIComponent(jobId)}/install`;
           const artifact = links[String(job.platform)];
           const installUrl = typeof artifact?.url === "string" ? artifact.url : void 0;
@@ -193753,7 +193766,10 @@ ${label3}`);
             // keystore on Android" — the normal combination — with one command.
             // flags["android-signing"], NOT flags.androidSigning: parseFlags does no kebab→camel
             // conversion, so the camel form reads undefined and the flag is a silent no-op.
-            ...str10(flags["android-signing"]) ? { androidSigning: str10(flags["android-signing"]) } : {}
+            ...str10(flags["android-signing"]) ? { androidSigning: str10(flags["android-signing"]) } : {},
+            // A Play bundle instead of an APK. The plane validates it (Android only, link destination,
+            // a stable key) so every caller of the route gets the same refusal.
+            ...flags.aab === true ? { androidFormat: "aab" } : {}
           }, { wixAuthorization });
         } catch (e2) {
           return distUnreachable(e2);
@@ -193830,10 +193846,11 @@ ${label3}`);
             done.push(rec);
             if (!flags.json) {
               const artifact = rec.artifact;
+              const isAab = rec.platform === "android" && rec.androidFormat === "aab";
               const installUrl = rec.platform === "ios" ? artifact?.installPageUrl : artifact?.downloadUrl ?? artifact?.installLink;
               const handoff = rec.customerAppStore;
               const handoffText = typeof handoff?.status === "string" ? `  testflight ${handoff.status}${handoff.error ? ` (${handoff.error})` : ""}` : "";
-              io2.log(`  ${rec.platform}  ${rec.status}${handoffText}${installUrl ? `  install \u2192 ${installUrl}` : ""}`);
+              io2.log(`  ${rec.platform}  ${rec.status}${handoffText}${installUrl ? isAab ? `  .aab for Google Play (not installable) \u2192 ${installUrl}` : `  install \u2192 ${installUrl}` : ""}`);
               if (artifact?.caveat) io2.log(`  \u26A0 ${artifact.caveat}`);
             }
           }

package/guides/qa-builds.md

@@ -1026,6 +1026,81 @@ that block off the first Android `himi dist` run to settle the question with a m
 than an assumption, the way the iOS identities were settled on 2026-07-27 after two wrong
 diagnoses.
 
+### An Android App Bundle for Google Play — `--aab`
+
+An APK installs on a device. Google Play wants an **Android App Bundle** (`.aab`) for a new app,
+and a bundle installs on nothing. `--aab` builds the bundle instead, for an owner who downloads the
+Wix-built binary and uploads it to Play Console themselves:
+
+```sh
+himi login --dpx --target bo        # an INTERNAL caller: self-serve callers get 403 (see below)
+himi dist --app <app> --platform android --aab --wait --target bo
+```
+
+- **What you get:** `artifact.downloadUrl` (presigned, 7 days) and `artifact.sha256`. No
+  `installLink`, no `installPageUrl`, no QR, and `GET /v1/dist/<jobId>/install` answers 404 for it —
+  a link that hands a phone a file it cannot open is worse than none. The record carries
+  `androidFormat: "aab"`.
+- **Android only.** The default stays an APK, and iOS is untouched. It travels as
+  `androidFormat: "aab"` on `POST /v1/admin/dist` (every `/v1/owner/dist` caller is self-serve, so
+  that route always answers `403 android_format_not_allowed`), and reaches the pool as
+  `DIST_ANDROID_FORMAT=aab` in the `command` blob (see
+  [why](#why-the-jobs-parameters-ride-in-command-not-envvars)). Refusals, all typed 400s before
+  any pool time is spent: `invalid_android_format` (anything but `apk` / `aab`),
+  `android_format_requires_link` (any destination but `link`), `android_format_requires_android`
+  (an iOS-only build, where the flag would be dropped in silence), and
+  `android_format_requires_wix_keystore` (any `--android-signing` other than `wix-keystore`), and
+  `android_format_shell_unsupported` (the `owner-lite` shell, whose gradle build refuses a store
+  bundle without a real Firebase config and customer identity). A mixed `--platform ios,android`
+  applies it to the Android leg only.
+- **How the pool builds it.** `run-dist` runs store-release's `bundleRelease` task
+  (`bundleReleaseArgs` / `bundleReleaseEnv`, the same task the Play lane runs) with **AGP injected
+  signing**, with the **Wix production key** (`wix-keystore`: `~/.signing/oneapp-production.keystore`,
+  alias `WixOne`), resolved by `resolveAndroidSigner` and verified there. The pool refuses any
+  other signer for a bundle — a pool-side `DIST_ANDROID_KEYSTORE` included. The keystore path and alias are `-P` flags; the passwords ride in the environment as
+  `ORG_GRADLE_PROJECT_android.injected.signing.{store,key}.password`, never in argv. `jarsigner
+  -verify` must say `jar verified.` before anything is uploaded. The seed gate and the binary-size
+  budget run on the `.aab` as they do on an APK. `DIST_ANDROID_BUNDLE_TASK` overrides the task
+  (`DIST_ANDROID_TASK` stays the APK one), and `DIST_ANDROID_FLAVOR` picks among flavored bundles.
+  Only the task's own gradle module is searched, so a sibling module's stale bundle is never taken.
+  An **ambiguous** choice fails the build instead of guessing: the bundle's applicationId becomes
+  the app's permanent Play package.
+- **What it skips, and why.** `apksigner` and the re-sign step (a bundle is JAR-signed at build
+  time, and the injected config overrides any `signingConfig`); the 16 KB check (its ZIP half is about an installed APK,
+  which Play generates; its ELF half reads the APK `lib/` layout — Play checks alignment on
+  upload); and `--reuse-artifact` (that is an APK).
+- **Version skew.** The pool runs the release's own `run-dist`, and one older than `--aab` ignores
+  `DIST_ANDROID_FORMAT` and builds an APK. So the pool reports what it built (`androidFormat` on
+  the result callback, the `androidSigningUsed` pattern), and serve-control turns a `SUCCESS` that
+  does not say `aab` into **`FAILURE`** with `android_format_not_built: …`, recording
+  `androidFormat: "apk"`, and drops the artifact link. The verdict is read from that error on every
+  read, so a status refresh that races the callback cannot bring back `SUCCESS`. **An old runner
+  never signs with the Wix key:** for a bundle the plane dispatches `DIST_ANDROID_SIGNING=qa-keystore`,
+  and the new run-dist overrides it with `wix-keystore`, derived from `DIST_ANDROID_FORMAT=aab`. A
+  run-dist older than `--aab` therefore signs an ordinary QA APK, never an installable APK carrying
+  the Wix production certificate. The QA key is named rather than left out, because a named key
+  outranks a pool machine's `DIST_ANDROID_USE_WIX_KEYSTORE=1`. A bundle must also report `androidSigningUsed: "wix-keystore"`; one signed
+  with any other key, or that reports none, fails as `android_format_wrong_signer` with its link
+  dropped. Rebuild from a release published on a newer commit. The other direction fails too: an
+  APK job whose pool reports a bundle is `android_format_not_requested`, with its link dropped. A
+  brokered job reads the format from its OWN parameters only, so a machine with
+  `DIST_ANDROID_FORMAT=aab` in its environment no longer turns an APK job into a bundle; the check
+  stays for a runner older than that rule. A later delivery that passes every check (a retry on a
+  clean machine) clears the verdict.
+
+**Why the Wix production key, and only for a bundle.** There are two Android keys: the committed
+QA keystore and the Wix production key (WixOne). WixOne is the Play **upload** key every Branded
+app's bundle carries (`mobile-apps-engine` refuses any other certificate for a Play build), with
+Play App Signing on, so Google re-signs what users install. An `.aab` therefore signs with it —
+only its `WixOne` entry of `oneapp-production.keystore`: the alias is pinned for a bundle, whatever
+alias the pool's signing files name. Because the first upload binds a Play listing to that key for good, a **self-serve** caller
+gets no bundle at all (`403 android_format_not_allowed`): `--aab` is for internal callers until a
+Containers store build checks the app, its owner and its package name. A self-serve **APK** with
+`wix-keystore` keeps `403 android_signing_not_allowed`, unchanged. For the owner, the Play listing is bound to the WixOne upload certificate, so later
+updates come from Wix builds too; leaving Wix needs an upload-key reset through Play Console
+support. A pool machine without the key fails the build, naming the paths it searched, rather than
+signing with another key.
+
 ### The iOS lane lives in one shared place
 
 `fastlane dist` runs with `cwd = <app>/ios`, so it needs `<app>/ios/fastlane/Fastfile`. That file is
@@ -1118,6 +1193,9 @@ baking the live asset.
   or `DIST_ANDROID_USE_WIX_KEYSTORE=1` names one, and a named key wins — `apksigner` replaces the
   signature block — because the job record is written at dispatch and would otherwise name a key
   that is not on the binary.
+- **Android, `--aab`** → a **presigned `.aab` download URL** and its sha256, and **no install
+  link**: a bundle is uploaded to Google Play, it does not install on a device. See
+  [the App Bundle section](#an-android-app-bundle-for-google-play----aab).
 - **How Android picks up the branding.** `prepare:customer` writes an **xcconfig** for iOS (bundle
   id + display name) but on Android only tokens, the icon drawable and a colour XML. Android's
   `applicationId` and app label come from the **contract JSON itself**, read at gradle-configure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1466.0",
+  "version": "0.1467.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "45c573391083ede76066e2c3b621e23db07135b7ad8781d653f59629"
+  "falconPackageHash": "7882aee1b35bad5d711c75125239b98cc49d21ee40dff33a6fda8b6b"
 }