@wix/himalaya-cli 0.997.0 → 0.999.0

package/guides/getting-started.md

@@ -247,6 +247,49 @@ the complete decision order and examples.
   instead — the mode a CI container can satisfy. Wix employees can use `--dpx`.)
   Everything up to the push runs locally.
 
+## Optional push notifications
+
+Interactive `himi init my-app` offers **Set up now / Later — continue building** after
+creating the project, with or without a template. Missing credentials or failed setup do not
+fail app creation. Use `--no-push-setup` to defer deliberately. Non-interactive runs,
+`--json`, and `init --yes` do not prompt or configure push unless `--push-setup` is
+explicitly supplied. Never combine `--push-setup` and `--no-push-setup`.
+
+Resume when the customer has a Wix site and the required keys:
+
+```sh
+himi login --browser --target wix
+wix login
+himi notify setup --content ./my-app --target wix
+himi notify status --content ./my-app --target wix --refresh --json
+```
+
+**Browser login alone is not sufficient for site authorization today.** Setup and status
+also use the Wix CLI account credential; use the same customer account for both logins.
+The CLI verifies app ownership and site access. A new app can be claimed as part of confirmed
+setup. Existing public bindings are reused and the prompts collect missing values.
+
+Supply the APNs key by local file path, its Key ID, Apple Team ID, bundle ID and environment;
+align the Android application ID with Firebase. The current wizard requires APNs input and
+has no separate Android-only mode. For automatic Apple signing, choose that option or use
+`--apple-signing` with a separate App Store Connect key file, Key ID and Issuer ID.
+Review the public plan before confirmation; agents use `--yes` only for authorized setup.
+Keys are transmitted to the authenticated backend for Branded/Ping custody, not copied into
+project settings or output. Enter Later to defer and continue building.
+
+`notify status` is read-only and needs no key files; `--refresh` checks providers live.
+Backend readiness does not prove notification delivery. This setup does not rewrite native
+configuration, select a Ping family, build a binary, register a device or send a notification.
+Continue building and publishing app content. Customer iOS push testing through `himi dist`
+is blocked until the hosted build service supports customer signing keys; the current Wix-managed QA
+binary cannot test the customer's saved push configuration. After an uncertain setup response, inspect status before
+retrying; the CLI does not automatically repeat provisioning.
+
+Full inputs, script flags and status meanings: `himi docs push-cli-onboarding`
+(https://apps.wix.com/_api/himi-serve/docs/push-cli-onboarding.md). The guide is bundled with the public npm package
+and is also served at that public URL. No repository access is required. This is notification setup; `himi push` publishes
+app content. Existing `notify send|tokens|doctor` commands use the local notification server.
+
 ## Shipping — over the air by default, a binary only for a native delta
 
 `himi push` → `himi promote` ships screens, Tier-5 bundles, tokens and app-config in **seconds**,
@@ -268,10 +311,16 @@ Tier-5 bundle, plus tokens, app-config and the icon — so a fresh install paint
 iOS returns an **https install page** whose button carries the `itms-services:` URL (chat clients
 won't linkify that scheme, so the page is what you share); open it in Safari on the device.
 
-**iOS signing needs nothing from you.** The pool MINTS a provisioning profile for the app's own
+**Wix-managed QA signing needs no customer signing files.** The pool MINTS a provisioning profile for the app's own
 bundle id per job — there is no profile to pre-provision and nothing to borrow. `--borrow-ios-id
 <bundleId>` still exists as an escape hatch (the binary then installs under *that* id, which is
 fine for QA and wrong for anything else), but it is rarely what you want.
+For customer push credentials, the binary's Apple team, bundle ID and APNs environment must
+match the saved delivery configuration. The current self-serve `himi dist` path uses Wix's
+Apple team and a `com.wix.himi.<app>` bundle ID, so its QA binary cannot test customer iOS
+push. `--signing byo` is not supported. Testing through `himi dist` must wait for the hosted build service
+to support customer signing keys. Notification setup can verify backend configuration now,
+but does not make a matching customer-signed build available.
 
 **Android signing needs nothing either.** `--android-signing` defaults to `qa-keystore` — the
 repo's committed QA key, identical on every pool machine, so a new build installs *over* the last

package/guides/headless-loop.md

@@ -198,6 +198,16 @@ with `himi ux record --content . --platform ios|android --status passed|failed|u
 actually drove; an unavailable platform drove nothing, so it takes no checks and needs its reason
 recorded, not guessed.
 
+**Record last, right before you push.** A UX record is bound to the exact release content it was
+taken against, and `himi push` refuses a draft whose record describes different content — so
+any edit after recording (a screen, a token, a worker) means recording again. And that only works
+if the build is reproducible: **a worker's initial state must be deterministic.** The build boots
+each worker and hashes its initial state into the release, so a `defineService` state computed
+from `Date.now()`, `new Date()` or `Math.random()` makes every build of unchanged source a
+different release, and no record can ever match the push. `himi validate` warns about it
+(`initial-state`, naming the worker and service); fix it by computing those values in an action
+— for example one the screen's `onAppear` dispatches — instead of in the initial state.
+
 Report v2 sharpens all of it: a worker throw carries `in tier5-src/<screen>/index.ts:<line>`
 (mapped through the bundle's sourcemap — fix it without grepping), the ledger lists worker
 functions **no axis ever executed** with their source lines (usually the error branch you

package/guides/index.json

@@ -279,6 +279,12 @@
       "title": "QA builds — an installable IPA/APK + install link",
       "category": "CLI & Loop",
       "file": "qa-builds.md"
+    },
+    {
+      "id": "push-cli-onboarding",
+      "title": "Push notifications — optional setup and readiness checks",
+      "category": "CLI & Loop",
+      "file": "push-cli-onboarding.md"
     }
   ],
   "componentReferenceFile": "component-reference.json",

package/guides/mobile-ux.md

@@ -137,6 +137,15 @@ driving a native shell, record the result—not an assumption—with `himi ux re
 is required for `passed`/`failed` and names what you actually drove; an unavailable platform drove
 nothing, so it takes no checks and needs a `--reason` instead.
 
+Record last, immediately before `himi push`. The record is bound to the exact release content it
+was taken against, and the push refuses a draft whose record describes different content, so any
+edit after recording means recording again. That only works when the build is reproducible, so
+**a worker's boot-time initial state must be deterministic**: the build hashes each worker's
+initial state into the release, and a `defineService` state computed from `Date.now()`,
+`new Date()` or `Math.random()` makes every build of unchanged source a different release that no
+record can match. `himi validate` names such a worker as an `initial-state` warning. Compute those
+values in an action (for example one the screen's `onAppear` dispatches) instead.
+
 `himi render --width`/`--device` writes into the same `.himi/ux-audit.json`, appending the width it
 rendered. That is what the width marker below reads first, so rendering the screen at two widths is
 itself the evidence — see the strict audit contract.

package/guides/push-cli-onboarding.md

@@ -0,0 +1,101 @@
+# Customer push setup with the Himi CLI
+
+Create an app with `himi init liftgear`. In a terminal, Himi offers **Set up now** or
+**Later — continue building** after the scaffold is created. A skipped or failed push
+setup does not fail app creation. This works with and without a template.
+
+- `--no-push-setup` records a deliberate deferral.
+- Non-interactive runs, `--json`, and `init --yes` do not prompt or provision push.
+- `--push-setup` explicitly requests the setup flow after creation.
+- Resume with `himi notify setup --content ./liftgear --target wix`.
+
+## Authentication
+
+The existing server requires two different credentials on both setup and status:
+
+1. A Himi owner control token, obtained through `himi login --browser --target wix`
+   or the supported Wix login flow.
+2. A Wix account credential obtained through the Wix CLI (`wix login`, then Himi
+   invokes `wix token`). Use the same customer account as the Himi app owner.
+
+**Browser login alone is not sufficient for site authorization today.** The command
+reports `wix_account_token_required` before opening key files or making setup requests
+when the second credential is unavailable. It does not substitute an employee credential
+or bypass site ownership. A browser-only site-authorization exchange is separate backend
+work; this CLI does not implement one. Customers can continue building while setup is deferred.
+
+## Configure now
+
+Interactive setup asks for missing site/native identifiers and paths to local key files.
+Choose push only, or push plus automatic Apple signing. Enter `Later` at any question
+to defer. The CLI displays the public setup plan before asking for confirmation.
+
+For an agent or script, supply the values and approve the displayed plan with `--yes`:
+
+```sh
+himi notify setup --content ./liftgear --target wix \
+  --site <metaSiteId> \
+  --ios-bundle-id com.examplecustomer.liftgear \
+  --android-package-name com.examplecustomer.liftgear.android \
+  --apns-key-file /private/path/AuthKey.p8 \
+  --apns-key-id <keyId> --apple-team-id <teamId> \
+  --apns-environment production --yes --json
+```
+
+The APNs environment must match the signed app. The Android package must match its
+Firebase client configuration; it need not equal the iOS bundle ID. Existing public
+bindings come from `provisioning.json`; flags override them. Keep the build configuration
+aligned with the selections. This command does not rewrite `config.ts` or build a binary.
+
+To also request Apple signing resources, add `--apple-signing`, `--asc-key-file`,
+`--asc-key-id`, and `--asc-issuer-id`. The App Store Connect key is separate from the
+APNs delivery key. The CLI calls the existing server provisioning flow; it does not
+create certificates directly or select a signing method for `himi dist`.
+
+The CLI verifies app ownership and site access before sending keys. A new app claim
+requires the same setup confirmation and is checked again after claiming. The server
+then performs Branded registration, push credential provisioning and Ping verification,
+plus Apple signing if requested.
+
+Keys are read from local files and sent to the selected, authenticated serve endpoint.
+Branded/Ping retain the credentials needed for their operations. The CLI does not copy
+keys or key-file paths into project configuration, onboarding records, or output.
+Public selections and deferral progress live under `.himi/push-onboarding.json`, excluded
+from published source archives. A local record never proves backend readiness.
+
+## Read status
+
+```sh
+himi notify status --content ./liftgear --target wix --json
+himi notify status --content ./liftgear --target wix --refresh --json
+```
+
+Status is read-only and needs no Apple key files. `--refresh` requests live provider
+checks. The output separates the saved setup state, backend configuration readiness,
+Apple signing readiness, native build, Himi routing and device delivery. A server that
+cannot provide live verification is reported as `live_verification_unavailable`.
+
+A setup response of HTTP 202 may mean `needs_attention`, not a running background job.
+After a timeout the CLI reads status once and reports an uncertain submission; it never
+repeats the provisioning POST automatically. Inspect status before retrying.
+
+After setup, continue normal app development, validation, publish/preview/promote and
+native distribution. Native push configuration, member authentication, device-token
+registration and a delivery/tap test are still required. This command does not enable
+native capabilities, choose a Ping family, send notifications or verify phone delivery.
+
+**Customer iOS push testing through `himi dist` is not available yet.** The current
+Wix-managed QA build uses Wix's Apple team and a `com.wix.himi.<app>` bundle ID, which
+do not match the customer's saved push configuration. `--signing byo` is unsupported.
+Testing through `himi dist` must wait for the hosted build service to support customer signing keys.
+Backend setup and verification can proceed now; they do not prove device delivery.
+
+`himi notify send|tokens|doctor` keep their existing local admin-server behavior; they
+are separate from the backend `setup|status` commands.
+
+If ownership cannot be verified, stderr includes a `push_ownership_check_failed` event
+with the failing check (`list_apps` or `app_role`), endpoint path and HTTP status.
+It excludes credentials, query parameters and response bodies. A `404` does not prove
+that the app is missing: serve can hide a route when its origin guard rejects the request.
+The CLI sends the pinned issuer's `Origin` on the collaborator read; the server still
+validates the owner token and checks the app's ownership record.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.997.0",
+  "version": "0.999.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": [
@@ -65,5 +65,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "1da0e386b23642ce946cc95fbb56bb7988c6100b680fe7dbaf954a99"
+  "falconPackageHash": "de163f6ec65faccc12fd53126da8881f844db6397df503835561454a"
 }