@wix/himalaya-cli 0.1494.0 → 0.1495.0

package/guides/himi-json-output.md

@@ -48,6 +48,7 @@ keeps its existing fields and adds the code:
 | `ux_evidence_unreadable` | The UX evidence artifact cannot be read. |
 | `lint_errors` | Build/lint validation found errors. |
 | `depth_budget_exceeded` | A screen or a bound list/grid row template nests deeper, or has more components, than the depth budget (`depth-budget` validator pass), or any of its JSON — props, modifiers, `input`, action `args` — nests past the raw-JSON ceiling of 256 levels. Each `issues[]` entry with `pass: "depth-budget"` carries the JSON `path` of the deepest node (the tree root for a node count, the first value past the ceiling for raw JSON), the `limit` and the `actual` value. Takes precedence over `lint_errors`, and `--force` does not override it: content over the budget overflows the renderer's stack on devices already in the field. Flatten the layout and push again. `himi patch screen` refuses an over-deep raw descriptor with the same code, before any network request, and `himi pack` / `himi template publish` refuse with it even under `--force`. |
+| `one_app_readiness_failed` | Reserved legacy refusal code. One App migration readiness is now advisory: publish and promotion report structured warnings instead. Other independent release checks may still refuse a push. |
 | `control_token_expired` | The selected control token has expired. |
 | `app_source_contains_secrets` | Source archiving detected a possible credential. |
 | `app_source_too_large` | The encoded source archive exceeds its limit. |
@@ -123,6 +124,7 @@ An invalid manifest fails with `manifest_invalid`, like the other `store iap` co
 | `apple_key_missing` | No In-App Purchase key was given and the app has none stored. |
 | `invalid_usage` | The flags are incomplete or malformed (for example `--iap-key` without `--iap-key-id`). Nothing was read or written. |
 | `iap_key_unreadable` | `--iap-key` is missing, unreadable, inside the repository, or not a PEM private key. Nothing was written. |
+| `catalog_route_unavailable` | Catalog needs an explicit valid gateway prefix via `--catalog-route` or `HIMI_IAP_CATALOG_ROUTE`. Nothing was written. |
 | `provider_route_unavailable` | The Serve target has no IAP routes, so the appleIAP provider was not connected. |
 | `manifest_invalid` | `--manifest` is not a valid IAP manifest; `problems` lists why. Nothing was read or written. |
 | `credentials_unavailable` | The `--profile` App Store Connect credentials could not be resolved. Nothing was read or written. |
@@ -133,13 +135,43 @@ An invalid manifest fails with `manifest_invalid`, like the other `store iap` co
 | `sku_in_use` | The Apple product is already mapped to another Wix item; left as it is. |
 | `mapping_unsupported` | The purchase flow cannot map this item yet (a vertical other than Online Programs, Wix Stores or one-time Pricing Plans, a price tier, or an item declared as a consumable). |
 | `no_purchases_app` | A step did not run because the site has no purchases app for the bundle. |
-| `request_failed` | A purchases-service call failed for another reason; the original message is preserved. |
+| `request_failed` | A Purchases or Catalog call failed for another reason; the original message is preserved. |
 | `setup_incomplete` | Steps are only planned (a dry run) or otherwise not yet in place. |
 | `confirmation_required` | Writes were planned, but there was no terminal to ask and no `--yes`. Nothing was written. |
 | `config_conflict` | The backend setup is complete, but the app's config names a different purchases app, site or bundle. |
 | `config_not_applied` | `--content` was given, but the binding is not in its `config.ts` (no config file, a dynamic or symlinked config, an edit `himi validate` rolled back, or no validator); the `config` report or `note` says what to add by hand. |
 | `connect_failed` | An otherwise unclassified error stopped connect (for example an unreadable manifest, or a failed `--out` write). The original message is preserved. |
 
+## Managed `himi store iap plan|apply|status` codes
+
+Managed mode uses the site's Catalog connection and never falls back to `--profile`.
+New failure paths preserve existing error text and exit codes and add a typed code.
+
+| Code | Meaning |
+|---|---|
+| `catalog_route_unavailable` | No assigned gateway prefix was supplied, or the prefix is invalid. |
+| `catalog_capability_missing` | Catalog has no endpoint for the requested operation. `endpoint` names it. Review screenshots use the managed upload endpoint. |
+| `catalog_mapping_missing` | No unique Catalog Product maps this SKU; submission was not sent. Create/reconcile the mapping first. |
+| `catalog_screenshot_upload_failed` | Wix Media upload failed or returned a URL outside `https://static.wixstatic.com/media/…`; the image was not sent to Catalog. |
+| `catalog_submit_blocked` | Submission returned blockers. Per-item `catalogReview` carries Product.review, readiness and blockers (`NOT_READY`, `NO_SUBMITTABLE_VERSION`, `UNSUPPORTED_PRODUCT_TYPE`); `REVIEW_SCREENSHOT_MISSING` is a readiness blocker under `NOT_READY`. |
+| `catalog_write_outcome_unknown` | A screenshot or submission write may have landed; readback did not prove completion. No blind resend. Inspect/rerun later. |
+| `catalog_request_failed` | A managed Catalog request or other unclassified managed command operation failed. |
+| `invalid_usage` | A managed flag is malformed, required flags are missing, or `--profile` was combined with `--managed`. |
+| `confirmation_required` | Apply requires confirmation; no write was sent. |
+| `apply_incomplete` | Apply produced a result with incomplete or failed items (stdout, exit 1). |
+
+Existing `manifest_invalid` and provisioning codes (`target`, `access`, `plan`, `account`,
+`drift`) retain their meanings. Managed apply compares site and purchases-app identity;
+a different identity is `account` before writes. Status retains its existing status codes. Per-item managed apply failures carry
+`items[].provisioning.code` inside the existing top-level `apply_incomplete` envelope. Review
+read failures in managed status carry the same per-item codes inside `status_incomplete`,
+while preserving the other items. Managed step failures also include `steps[].code`. Mapping
+preflight reuses the existing `sku_in_use`, `mapping_conflict`, `mapping_inactive`,
+`mapping_type_mismatch` and `mapping_unsupported` codes; these refuse the affected item
+before its Apple writes and never fix/reactivate a mapping. Managed
+status exposes `catalogReview.review` and `catalogReview.readiness.blockers`. Empty gateway
+404s are not automatically retried; an owner reruns after rollout.
+
 ## `himi template publish` codes
 
 `template publish` is still mostly legacy. It carries one code so far, on the path that sends the
@@ -223,8 +255,10 @@ redirects, invalid data, source changes and disk errors remain failures.
 
 Failures print `ok: false` and a top-level `code` on stderr. The validator reads
 authored header choices from `settings.topBarSettings`, falls back to the legacy
-`settings.showCartIconInTopBar` / `showChatIconInTopBar` values, and treats a
-choice that is absent from both locations as false.
+`settings.showCartIconInTopBar` / `showChatIconInTopBar` values, and also checks
+hashed platform-enriched top-bar definitions. An absent authored choice is false,
+but an enriched button definition still needs a target action or an explicit
+unresolved migration finding.
 
 - `invalid_usage`: required options are missing, duplicated, or malformed (exit 2).
 - `evidence_invalid`: the evidence manifest or `raw-structure.json` is missing,
@@ -232,9 +266,17 @@ choice that is absent from both locations as false.
   file does not match that hash (exit 1).
 - `config_uninspectable`: the target `config.ts` cannot be read or the relevant
   `navigation.topBarDefault.actions` cannot be inspected (exit 1).
-- `topbar_coverage_failed`: an authored cart/chat control has no matching action
+- `topbar_coverage_failed`: a source top-bar control has no matching action
   with a non-empty `onTap.actionId` (exit 1).
 
+## `himi one-app coverage` codes
+
+- `invalid_usage`: the mode or required paths are missing (exit 2).
+- `evidence_invalid`: collected evidence cannot be read or fails its manifest hash (exit 1).
+- `coverage_drift`: a requirement disappeared or `check` found new requirements not
+  recorded in `ONE-APP-COVERAGE.json` (exit 1).
+- `coverage_unverified`: `verify` found unresolved, failed, or stale requirement checks (exit 1).
+
 ## `himi base44 entities` codes
 
 Covers `himi base44 adopt` and `himi base44 entities query` (#4557,

package/guides/iap-products.md

@@ -6,8 +6,8 @@ initial price and explicit territories. It then exports a Wix→Apple mapping fo
 backend import.
 
 It is an administration workflow, not a build: it never builds, signs or bumps a version,
-and it runs anywhere `himi` is installed. An owner needs only a credential profile, plus
-either a manifest or a Wix site for `draft` to read. It does not run during an app build or
+and it runs anywhere `himi` is installed. Choose an explicit local credential profile, or
+managed Catalog provisioning with the site's existing Branded Apple connection. It does not run during an app build or
 a customer checkout.
 
 It registers one-time **non-consumables**, and **consumable price tiers** for large
@@ -31,8 +31,62 @@ catalogs. Subscriptions are refused before anything reaches Apple.
   The profile and the key must both live outside the repository. That is checked after
   resolving symlinks. The profile's `team` must equal the manifest's `teamId`.
 
-There is **no ambient fallback**. `--profile` is required, and exported `ASC_*` variables
-are never used to decide which account to write to.
+These key and profile prerequisites apply to direct Apple mode. There is **no ambient fallback**: direct mode requires `--profile`, and exported `ASC_*` variables never select the account. Managed mode below uses no local `.p8`.
+
+## Managed provisioning through Catalog
+
+`plan`, `apply`, and `status` accept `--managed --purchases-app <registration-id>`.
+They use the manifest's Wix site and the site's existing Branded Apple connection. No local
+credential profile or `.p8` is opened. `--profile` and `--managed` cannot be combined, and a
+Catalog refusal never falls back to direct Apple mode. Existing manifests retain their
+`target.profile` and `target.teamId` fields for compatibility; those fields do not select
+managed credentials or identify a managed plan.
+
+Supply the assigned Catalog gateway prefix, including its
+version segment, through `--catalog-route <assigned-prefix>` or `HIMI_IAP_CATALOG_ROUTE`.
+There is no default. During rollout some gateway nodes can return an empty 404. The CLI
+does not retry it automatically; the owner reruns. Reads are safe to rerun, and writes
+read state before creating resources.
+
+```sh
+himi store iap plan --managed --purchases-app <registration-id> --catalog-route <assigned-prefix> --manifest ./iap-products.json --out ./iap-plan.json
+himi store iap apply --managed --purchases-app <registration-id> --catalog-route <assigned-prefix> --plan ./iap-plan.json --out ./iap-result.json --yes
+himi store iap status --managed --purchases-app <registration-id> --catalog-route <assigned-prefix> --manifest ./iap-products.json --json
+```
+
+A managed plan records `{ mode: "managed", siteId, purchasesAppId }`; apply refuses a
+different site or registration before writing. Catalog verifies the Apple app and bundle
+on the server. Localization upsert creates the editable version when necessary. Price writes
+send the requested amount, currency, territory and `EXACT`/`AT_LEAST` rule, never a client-selected
+price-point id. Catalog reports `APPLIED` or `ALREADY_APPLIED`. Existing product locks,
+read-before-write checks, plan review, confirmation and local apply locking still apply.
+
+Managed apply finishes each configured item by uploading its App Review screenshot and calling
+Catalog's Product `submit-for-review`. Without `reviewScreenshot`, Catalog generates an image
+from the first localization's display name; no `imageUrl` is sent. If the manifest names a PNG
+or JPEG, the CLI uploads the checked bytes to the site's Wix Media and sends its
+`https://static.wixstatic.com/media/…` URL. An already complete screenshot is **reused**,
+even when a different image is requested; the CLI never replaces it.
+
+Before any managed apply writes for an item, Catalog must have one active mapping for its
+expected Wix item, SKU and type. Conflicts use the existing connect codes (`sku_in_use`,
+`mapping_conflict`, `mapping_inactive`, `mapping_type_mismatch`, `mapping_unsupported`) and
+leave the mapping unchanged.
+
+Submission sends the desired localizations, base price (amount/currency/territory/rule), and
+territories after metadata, price and availability writes succeed. Each item's `catalogReview`
+contains Product.review, readiness and submission blockers: `NOT_READY`, `NO_SUBMITTABLE_VERSION`
+or `UNSUPPORTED_PRODUCT_TYPE`. A missing screenshot is the readiness blocker
+`REVIEW_SCREENSHOT_MISSING` underneath `NOT_READY`. `status --managed` reads Product.review and
+readiness blockers without submitting or uploading anything. Review acceptance and approval
+remain Apple's decisions; `WAITING_FOR_APP_VERSION` still needs an app-version submission.
+
+An unknown screenshot or submit write outcome is read back before further action; it is never
+blindly resent. If that read cannot prove completion, the item reports
+`catalog_write_outcome_unknown` and the owner reruns after inspecting the state. A missing Catalog
+mapping reports `catalog_mapping_missing`; create/reconcile mappings with `connect` before
+managed submission. Other per-item failures include `catalog_screenshot_upload_failed` and
+`catalog_submit_blocked` (see [JSON codes](himi-json-output.md)).
 
 ## Drafting the manifest from your Wix catalog
 
@@ -158,7 +212,7 @@ himi store iap plan   --manifest ./iap-products.json --profile fit-club-owner --
 himi store iap apply  --plan ./iap-plan.json --profile fit-club-owner --out ./iap-result.json
 himi store iap status --manifest ./iap-products.json --profile fit-club-owner --json
 himi store iap screenshots --manifest ./iap-products.json --content . --profile fit-club-owner
-himi store iap connect --manifest ./iap-products.json --profile fit-club-owner \
+himi store iap connect --manifest ./iap-products.json --profile fit-club-owner --catalog-route <assigned-prefix> \
   --iap-key ~/keys/SubscriptionKey_ABCD123456.p8 --iap-key-id ABCD123456 --content . --dry-run
 ```
 
@@ -345,8 +399,13 @@ a live status check identifies it. Wix order and charge amounts are not changed
 `connect` makes the manifest's Wix site ready to sell those products, from the same manifest,
 as the site owner (your Wix login, like `draft`). To run it against a Serve deploy preview, pass
 `--preview-tag dp-<tag>` (or set `HIMI_SERVE_PREVIEW_TAG`). Only the Serve calls (the appleIAP
-provider connection) are routed to the preview; the purchases service and App Store Connect are
-called as usual. In order:
+provider connection) are routed to the preview; Purchases and Catalog are called directly.
+Mapping calls require `--catalog-route <assigned-prefix>` or `HIMI_IAP_CATALOG_ROUTE`; no default
+is supplied. The migration depends on catalyst-server #24707 removing Purchases ProductsApi.
+For an existing app, migrate its mappings into Catalog with their original SKU, type and active
+state before running `connect`. Catalog is this command's mapping source; an empty Catalog is
+not evidence that the app had no legacy mappings. This command is not the legacy-data migration.
+In order:
 
 1. **The purchases app.** It reads the site's apps and reuses the one for the manifest's bundle
    id. Only when the site has none does it register one. A bundle id belongs to one purchases
@@ -361,7 +420,7 @@ called as usual. In order:
    (`ConnectProviderAccount`). Reported as `provider_route_unavailable` only when the Serve target
    has no IAP routes; a refusal from the service behind it is `request_failed`. There is no read
    of the provider's state, so a rerun connects it again (the call is safe to repeat).
-4. **One mapping per Wix item → Apple product.** Online Programs map by program id, Wix Stores
+4. **One mapping per Wix item → Apple product, through Catalog `listProducts` / `createProduct`.** Online Programs map by program id, Wix Stores
    digital products by product id, and one-time unlimited Pricing Plans by plan id (the ids the
    purchase flow looks up), all only as non-consumables. A plan is mapped only when the site reads it
    as one-time unlimited (one payment, valid until cancelled); a recurring, time-limited or archived
@@ -369,7 +428,7 @@ called as usual. In order:
    are skipped with `mapping_unsupported`. An item already mapped to another
    product (`mapping_conflict`), a mapping of another product type (`mapping_type_mismatch`), an
    inactive mapping (`mapping_inactive`), or an Apple product mapped to another item
-   (`sku_in_use`) is reported and left exactly as it is.
+   (`sku_in_use`, including Catalog's `STORE_PRODUCT_ID_IN_USE` refusal) is reported and left exactly as it is.
 5. **The app's config.** With `--content <dir>`, it records `wixIap: { purchasesAppId }` (and the
    `iap` capability) in the package's `config.ts`, keeping everything else byte for byte. The edit
    is backed up under `.himi/store-iap-backup/`, checked with `himi validate`, and rolled back if it

package/guides/one-app-to-himi-app.md

@@ -67,6 +67,9 @@ settings or claiming coverage.
 An unavailable supporting runtime view is recorded as `runtime_context_unavailable`
 with its platform and typed failure code; that enriched file is absent. Continue
 from authored intent and mark the platform behavior as unverified in the report.
+`coverage verify` cannot pass while either platform runtime view is missing, and
+`validate-topbar` reports an evidence error when collection recorded an unavailable
+runtime context. These checks report the gap; they do not block promotion.
 Authorization, invalid responses, source changes and evidence-write failures still
 stop collection. Never infer unrestricted access from a missing runtime view.
 
@@ -121,12 +124,15 @@ Apply these interpretation rules:
   end-user access policy. Never expose protected content beneath a visual gate.
 - Exclude `ntt.*` definitions and placements from coverage. Preserve configured
   header/top-bar intent; do not add unconfigured drawer or header surfaces.
-- Before publishing, run the migration-only authored-control check:
+- Before publishing, run the migration-only top-bar coverage check:
   `himi one-app validate-topbar --evidence-dir .himi/one-app --content .`.
-  It reads each screen's `raw-structure.json` header settings and checks that
-  `navigation.topBarDefault.actions` has a matching tappable action for every
-  authored cart/chat control. It does not use the iOS/Android enriched views to
-  infer visibility, access, or membership rules. This check is specific to this
+  It verifies the collected raw and platform-enriched evidence hashes, then checks
+  authored cart/chat settings and the resolved platform top-bar button definitions
+  against tappable `navigation.topBarDefault.actions` or mapped
+  `ScreenDescriptor.topBar.actions` when a screen replaces the default. A dynamic
+  bar that cannot be inspected is reported as unverified. Platform definitions establish
+  a feature to account for; they do not alone prove visibility or access for every
+  visitor or member. Resolve those rules separately. This check is specific to this
   migration workflow; it does not change the behavior of `himi validate`.
 - For each configured Detailed header, import and call the shared
   `detailedHeader` builder from `@wix/himalaya/screens`. Do not recreate its
@@ -227,6 +233,75 @@ placement and interaction, record supported, adapted, conditional or unresolved
 status, the implementation and evidence, and intentional prompt-driven differences.
 Track dangling/unreachable relationships and unknown source context explicitly.
 
+Run `himi one-app coverage init --evidence-dir .himi/one-app --content .` to
+create `ONE-APP-COVERAGE.json` from the verified source graph. After edits or a
+CLI upgrade, run `coverage sync` and review new rows; `coverage check` fails when
+the file is absent or source requirements have appeared, disappeared or changed.
+Rows cover source graph warnings as well as routes and controls. This is an
+inventory of migration obligations, not proof that their target actions work.
+
+Map each row to a target screen and, for interactions or top-bar controls, a
+target control. Set its `status` to `supported`, `adapted`, `conditional`, or
+`unresolved`. For an adaptation, cite the user's instruction and explain the
+change. Each resolved row needs a `verification` record using the required check
+ID for its kind (`route-walkthrough`, `visual-comparison`, `behavior-crawl`,
+`topbar-control`, `access-state`, or `source-resolution`), a safe relative path to
+a JSON check record, and the exact release payload SHA-256 in `releaseHash`.
+The JSON file's `checks[]` must contain a passed record with that requirement ID,
+check ID, release hash, target mapping, and a relative `artifact` path to the
+actual screenshot, test output, or walkthrough record. Multiple rows may share
+one file, but each needs its own passed check record. Keep private evidence under
+`.himi/` so it is excluded from the app source archive.
+
+For example, one entry in the referenced JSON file is:
+
+```json
+{"checks":[{"requirementId":"<row-id>","check":"route-walkthrough","releaseHash":"<64-hex-sha256>","status":"passed","target":{"screenId":"home"},"artifact":".himi/one-app/screens/home-compact.png"}]}
+```
+
+The artifact must exist. Review the actual route and state shown in it before
+recording a pass; a valid record is an index to the check, not a substitute for it.
+
+After publishing a draft, build a QA APK pinned to that draft release with
+`himi dist --platform android --release <draft-id> --allow-draft`. Install
+and walk through every requirement on the device. Save
+`.himi/one-app/native-proof.json` with the distribution job ID, the APK SHA-256
+reported by `himi dist status`, the exact release hash, and one passed check per
+requirement. Each check points to a local screenshot or walkthrough artifact:
+
+```json
+{"jobId":"qa-job-id","artifactSha256":"<apk-sha256>","releaseHash":"<release-sha256>","checks":[{"requirementId":"<row-id>","status":"passed","artifact":".himi/one-app/device/home.png"}]}
+```
+
+The verification command checks every source requirement against this record.
+The hosted release service also checks that the job succeeded for this app and
+release, that the recorded APK hash matches its build artifact, and that the
+claimed release hash matches the published payload. It does not rerun `himi test`
+or inspect device screenshots; those results are supplied by the publisher.
+Keep the device artifacts for review. A check record alone cannot show whether a
+screen looks or behaves correctly.
+`himi one-app coverage verify --evidence-dir .himi/one-app --content .
+--release-hash <sha256>` reports every unresolved or stale row. `himi push`
+checks local coverage and the top bar for a marked migration and warns when
+either is incomplete. A partial push warns because its derived release may
+inherit screens the local checks did not cover. These One App warnings do not
+prevent a live push, activation, promotion, Play bundle, or customer TestFlight
+build. Other release rules still apply.
+
+The hosted release service remembers One App provenance in a separate enrollment
+record after the first marked full release, so it cannot overwrite the owner's
+visibility setting. It returns `warnings` with code `one_app_readiness_unverified`
+for every enrolled or marked release because publisher-supplied checks are not an
+independent hosted verification receipt. An unmarked
+replacement or partial release is warned, and a partial release loses its prior
+ready claim. A draft may be republished under the same release ID after checks
+pass: the content stays immutable while its `oneAppMigration` readiness metadata,
+matching `himi test` attestation, and QA APK job binding are updated. The server
+checks their internal consistency and QA job binding, then stores `ready: false`
+because it cannot rerun `himi test` or inspect the linked screenshots or native
+walkthrough. Review that evidence before claiming production readiness. A warning
+is advisory; it is not a readiness approval.
+
 For each mapping gap, inspect current components, SDKs and portable examples;
 implement app-local sections, workers, action adapters or compositions where
 possible. Reuse verified live-data logic while retaining the original inline