@wix/himalaya-cli 0.1527.0 → 0.1528.0

package/guides/himi-json-output.md

@@ -399,3 +399,48 @@ generated files for entities no longer declared. They are never deleted.
 - Migrate failure envelopes in subcommands other than `push`, keeping this contract.
 - Review/reword human messages separately; no message rewrite is part of this change.
 - Review exit-code conventions separately; no exit code changes are part of this change.
+
+
+## IAP setup and mapping controls
+
+`himi store iap check --json` (also local MCP `himi_iap_status`) returns one read-only
+report. Its top-level `code` is `ok` or `setup_incomplete`; exit status is 0 or 1. The report
+contains `checks` and per-product `items[].checks`. Each check has an `id`, `state`
+(`ok`, `missing`, `blocked`), stable `code`, and human-readable `fix`.
+
+The setup checker uses the stable code vocabulary below. Consumers branch on
+codes, never the fix text. Codes include:
+
+- Registration/key: `purchases_app_missing`, `purchases_app_mismatch`, `iap_key_missing`.
+- Provider/access: `provider_check_unavailable`, `provider_not_connected`, `apple_access_blocked`,
+  `apple_app_mismatch`, `setup_read_failed`.
+- Mappings: `mapping_missing`, `mapping_inactive`, `mapping_type_mismatch`, `mapping_conflict`,
+  `mapping_visibility_unverified`, `mapping_not_visible`.
+- Apple readiness: `apple_product_missing`, `apple_product_not_ready`, `review_screenshot_missing`,
+  `apple_readiness_blocked`.
+- Vertical: `sale_disabled`, `item_unsupported`, `vertical_check_unavailable`.
+- Binding: `config_binding_missing`, `config_binding_conflict`, `build_binding_unverified`,
+  `build_binding_conflict`.
+- Notifications: `notification_check_unavailable`, `notification_url_mismatch`.
+
+`ok: false` with `setup_incomplete` can contain successful findings too; a failed read does not
+suppress the remaining checks. Unavailable provider/notification reads are blocked evidence,
+not evidence of an absent configuration.
+
+`himi store iap mappings` lists without writes. Changes require both `--product` (Catalog mapping
+id) and `--active true|false`, plus confirmation. Missing confirmation is
+`confirmation_required`; malformed inputs are `invalid_usage`. Catalog errors preserve the
+existing managed failure codes. `--profile` remains the explicit legacy Apple mode for the
+provisioning commands; `--managed` is optional when no profile is supplied. `--no-submit` on
+managed apply still uploads the review screenshot but skips submit-for-review.
+
+A managed-only manifest used with explicit legacy `--profile` mode returns
+`credentials_unavailable` before reading any profile or key, with guidance to add
+`target.profile` and `target.teamId` or continue through Catalog. Apple products whose setup
+is complete remain configured while their review submission progresses; an ok setup finding
+is not App Store approval.
+
+Apple provisioning commands (`draft`, `plan`, `apply`, `status`, `screenshots`) reject explicit
+legacy `--profile` combined with Catalog registration/route selectors as `invalid_usage`,
+before reading inputs or credentials. `connect` retains its intentional legacy profile plus
+Catalog mapping route and registration check.

package/guides/himi-mcp.md

@@ -4,6 +4,47 @@
 Claude Code, Cursor, Codex, VS Code — calls them as tools instead of remembering commands. Every
 tool runs the same `himi` command you would type, on the app folder already on your disk.
 
+## Apple in-app purchases
+
+The local server exposes typed tools using the same IAP command implementations through
+Catalog, with the site's owner authentication and server-held Apple keys. No tool accepts a
+local Apple profile, key path, or private key. Supply the assigned `catalogRoute`; the Apple
+provisioning tools also require the registered `purchasesApp` id.
+
+| Tool | Operation | Confirmation |
+| --- | --- | --- |
+| `himi_iap_status` | Combined setup check: coded `ok`, `missing`, or `blocked` findings and fixes. Optional `dir`, built `plist`, and `visitorClient` provide binding and app-visibility evidence. | Read-only |
+| `himi_iap_draft` | Read Wix items and Apple pricing; write a draft manifest. | No server writes |
+| `himi_iap_plan` | Read Apple state; write a sealed plan for review. | No server writes |
+| `himi_iap_apply` | Create/update products, have Catalog generate review screenshots, and by default submit for review. `noSubmit: true` skips submission. | `confirm: true` after user approval |
+| `himi_iap_connect` | Preview registration, provider connection, mappings and optional config binding. Apply the reviewed setup with `confirm: true`. | Dry run by default |
+| `himi_iap_mappings` | List mappings; supply `product` and `active` to turn one on/off. | Updates require `confirm: true` |
+
+Draft/plan write local artifacts, so their MCP `readOnlyHint` is false. Mapping tools also
+use false because they can update a mapping. Every tool that can replace files or external
+state advertises `destructiveHint: true`, including mixed tools whose default is a list or dry
+run. The host must obtain its own user consent; a model-supplied `confirm` is not proof of it.
+
+Catalog generates review screenshots on the server; MCP has no local screenshot capture tool.
+Managed plan/apply never read or upload local images.
+
+IAP paths, including references inside a manifest/plan, always stay inside the
+trusted workspace root. `HIMI_WORKSPACE` takes precedence; otherwise the host's workspace root
+(or the server's working directory) is the boundary. Absolute paths, parent traversal and
+symlinks that leave that boundary are refused before invoking the command. The hosted connector does
+not gain these local tools.
+
+Status never treats an unverified provider or Apple notification destination as ready. The
+current provider contract lacks a read-only readiness method, and notification-destination
+verification is not yet wired into the checker, so it reports `provider_check_unavailable` and
+`notification_check_unavailable`. Managed connect can reuse a purchase key stored on the server;
+if it is missing, it reports the onboarding blocker instead of opening a local key. See
+[IAP products](iap-products.md#one-setup-check-and-mapping-controls).
+
+Owner Wix authentication is separate from the publishing token minted by
+`himi_login`. IAP uses the owner's Wix CLI session (`wix login`); that prerequisite is not
+satisfied by signing in for draft publishing alone.
+
 ## Set it up
 
 **Nothing to do for a new app.** `himi init` (and `himi agent-init` in an existing app) writes the

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. 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
+and it runs anywhere `himi` is installed. Catalog provisioning with the site's existing
+Branded Apple connection is the default. `--profile` explicitly selects legacy local-key mode. It does not run during an app build or
 a customer checkout.
 
 It registers one-time **non-consumables**, and **consumable price tiers** for large
@@ -17,10 +17,10 @@ catalogs. Subscriptions are refused before anything reaches Apple.
 
 - **The Apple app record already exists.** This command never creates apps or accounts,
   and never accepts agreements.
-- **You have an App Store Connect API key for the account that owns the app.** Managing
+- **For explicit legacy mode, an App Store Connect API key for the account that owns the app.** Managing
   in-app purchases needs the **Admin** or **App Manager** role (or Account Holder). A
   user's role in the web UI does not grant it to a key.
-- **You have a credential profile for that key** at
+- **For explicit legacy mode, a credential profile for that key** at
   `~/.himalaya/store-credentials/<name>.json`. It holds identifiers plus a path to the
   `.p8`, never the key itself:
 
@@ -35,16 +35,27 @@ These key and profile prerequisites apply to direct Apple mode. There is **no am
 
 ## Managed provisioning through Catalog
 
-`plan`, `apply`, and `status` accept `--managed --purchases-app <registration-id>`.
+Provisioning commands use managed mode when `--profile` is absent; `--managed`
+remains an optional explicit spelling. `draft`, `plan`, `apply`, and `status`
+read Apple through Catalog with `--purchases-app <registration-id>`. Wix catalog reads,
+registration, provider connection, and mapping writes keep their existing owner-scoped services.
 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.
+Catalog refusal never falls back to direct Apple mode. For `draft`, `plan`, `apply`, `status`
+and `screenshots`, `--profile` also cannot be combined with explicit `--purchases-app` or
+`--catalog-route` selectors: choose one mode. Legacy `connect` intentionally accepts a Catalog
+route for its Wix mappings and an optional registration id to verify. Existing manifests retain their
+`target.profile` and `target.teamId` fields for compatibility; new managed drafts omit them.
+Those fields do not select managed credentials or identify a managed plan. Legacy mode still
+requires both fields to match its explicit profile. A managed-only target returns
+`credentials_unavailable` with instructions to use Catalog or add the matching legacy identity
+before any profile or key is read.
 
 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
+Managed Catalog and purchases setup calls require the owner’s Wix user session. Standalone
+Wix catalog reads and explicit legacy profile mode retain account API-key authentication.
+There is no default route. 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.
 
@@ -61,12 +72,18 @@ send the requested amount, currency, territory and `EXACT`/`AT_LEAST` rule, neve
 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.
+For the setup check, an Apple product whose metadata is complete remains configured while its
+submission is waiting for review, in review, or waiting on an app version. This reports completed
+setup, not Apple approval; Catalog readiness blockers still prevent an ok finding.
+
+Managed apply finishes each configured item by asking Catalog to generate its App Review screenshot and, by
+default, calling Catalog's Product `submit-for-review`. Pass `--no-submit` to provision and generate
+the screenshot on the server without submitting for review. Catalog generates the image from the first
+localization's display name. Managed plan and apply ignore local `reviewScreenshot` paths:
+no image is read, rendered, or uploaded from the agent's machine. An already complete
+screenshot is reused without replacement. Local capture is available only through the
+explicit legacy `screenshots --profile` workflow. Older managed plans that sealed a local
+image are refused before requests; generate and review a new plan for server generation.
 
 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`,
@@ -88,6 +105,52 @@ mapping reports `catalog_mapping_missing`; create/reconcile mappings with `conne
 managed submission. Other per-item failures include `catalog_screenshot_upload_failed` and
 `catalog_submit_blocked` (see [JSON codes](himi-json-output.md)).
 
+## One setup check and mapping controls
+
+`check` combines the registration, stored purchase key, Catalog mappings, Apple product and
+screenshot readiness, vertical sales rules, app visibility, and source/build binding in one
+read-only report. Unlike `connect --dry-run`, it never reports the payment provider as planned
+and counts that as readiness. Every finding carries `state: "ok" | "missing" | "blocked"`, a
+stable `code`, and a `fix`; overall `code` is `ok` or `setup_incomplete` (exit 0 or 1).
+
+```sh
+himi store iap check --manifest ./iap-products.json --catalog-route <assigned-prefix> \
+  --content . --plist /path/to/Built.app/Info.plist --visitor-client <headless-client-id> --json
+himi store iap mappings --site <msid> --purchases-app <registration-id> --catalog-route <assigned-prefix> --json
+himi store iap mappings --site <msid> --purchases-app <registration-id> --catalog-route <assigned-prefix> \
+  --product <catalog-mapping-id> --active false --yes --json
+```
+
+`check` discovers the registration for the manifest's bundle on its site. An optional
+`--purchases-app` must agree. `--content` inspects the authored config without executing it;
+`--plist` checks the built Apple binding using macOS `plutil`; `--visitor-client` checks Serve
+mapping visibility with a fresh anonymous visitor, not the owner's token. Missing evidence
+stays blocked. A visitor check does not prove a particular signed-in member's checkout.
+
+The current wix-iap contract exposes provider connection but no read-only provider-readiness
+method, so `provider_check_unavailable` asks for verification in payment settings. Apple exposes notification URL attributes on its App resource, but this checker does not yet
+compare them with a verified purchases-service destination. `notification_check_unavailable`
+therefore asks for App Store Connect verification. These blockers prevent an unproven all-ready verdict. The checker is
+shared with local MCP; it does not add a Serve GET route for these unavailable reads.
+
+Mapping lists make no writes. On/off updates require confirmation and send only `active`
+with Catalog's current revision, preserving the SKU, item identity, and metadata.
+
+Managed `connect` never opens an Apple key on the Mac. It reuses an In-App Purchase key
+already stored by purchases. If there is none, it reports `apple_key_missing`; an App Store
+Connect API key is a different credential and cannot replace it. The purchases contract
+supports encrypted key writes but not reading a key back, and Branded does not currently
+provide a dedicated In-App Purchase key bridge. Provisioning that missing server key remains
+a backend prerequisite. Explicit legacy `--profile` plus `--iap-key` remains available for
+owner-driven onboarding. Supplying local key flags in managed mode is refused.
+
+For a managed draft, pass the Catalog registration and route:
+
+```sh
+himi store iap draft --site <msid> --purchases-app <registration-id> --catalog-route <assigned-prefix> \
+  --apple-app <apple-id> --bundle <bundle-id> --base-territory USA --out ./iap-products.json
+```
+
 ## Drafting the manifest from your Wix catalog
 
 You don't have to write the manifest by hand. `draft` reads the site's whole catalog —
@@ -95,7 +158,7 @@ every page of Wix Stores (Catalog V3 or V1), Online Programs and Pricing Plans
 a manifest of everything that can be sold:
 
 ```bash
-himi store iap draft --site <msid> --profile fit-club-owner --apple-app 6450000001 \
+himi store iap draft --site <msid> --purchases-app <registration-id> --catalog-route <assigned-prefix> --apple-app 6450000001 \
   --bundle com.example.fitclub --base-territory USA --territories USA,CAN --out ./iap-products.json
 ```
 
@@ -210,7 +273,9 @@ Rules, all checked locally before any request:
   used twice, including a Wix entity mapped both directly and through a tier.
 - **Unknown keys are refused, at every level.** So is any string that looks like a key or a token.
 
-## The workflow
+## Legacy workflow with a local profile
+
+These examples explicitly select local-key mode. The managed examples above need no local Apple key.
 
 ```bash
 himi store iap draft  --site <msid> --profile fit-club-owner --apple-app 6450000001 --bundle com.example.fitclub --base-territory USA --out ./iap-products.json
@@ -294,9 +359,9 @@ hosts only ever get the file's bytes, never the API key's token.
   the result. A refused image (`FAILED`) fails the step with Apple's reason. An image still
   processing (`UPLOAD_COMPLETE`) counts as uploaded.
 
-### Making the review screenshots: `screenshots`
+### Legacy local review screenshots: `screenshots --profile`
 
-`himi store iap screenshots --manifest <file> --content <app dir> [--profile <name>]` makes each
+`himi store iap screenshots --manifest <file> --content <app dir> --profile <name>` makes each
 product's review screenshot from the app's own purchase screen, so nobody has to take them on a phone:
 
 **One-time setup.** The screenshots are taken in a headless Chromium on your machine, so no phone,
@@ -327,12 +392,11 @@ before rendering anything and says so (`browser_unavailable`). A `--dry-run` doe
    (the largest-iPhone App Store size). It then sets each item's `reviewScreenshot` to that file,
    leaving the rest of the manifest as it was.
 
-**Apple's price** comes from App Store Connect when you pass `--profile`, a read-only call. Otherwise it is
-the manifest's `exact` amount. An `atLeast` item that Apple has no price for yet is skipped: run `apply`
+**Apple's price** is read directly from App Store Connect with the explicit legacy `--profile`. If Apple has no observed price, the manifest's `exact` amount can be used. An `atLeast` item that Apple has no price for yet is skipped: run `apply`
 first. A price tier has no single purchase screen and is skipped too.
 
 **Other options:**
-- With `--profile`, a product that is live or in review keeps its screenshot: changing it there is a
+- A product that is live or in review keeps its screenshot: changing it there is a
   conflict anyway.
 - An item that already names a screenshot is kept unless you pass `--force`.
 - `--only <productId,…>` limits the run; an id the manifest doesn't have is reported.
@@ -418,7 +482,8 @@ In order:
    app platform-wide: if another app holds it (another site's, or another account's), that is a
    `bundle_registered_elsewhere` conflict. Only that registration's owner can remove it; `connect`
    never does.
-2. **The In-App Purchase key.** It stores `--iap-key` / `--iap-key-id` once, server-side. This is
+2. **The In-App Purchase key.** Managed mode reuses the server key, or reports `apple_key_missing`.
+   Legacy `--profile` mode stores `--iap-key` / `--iap-key-id` once, server-side. This is
    an App Store Connect **In-App Purchase** key (Users and Access → Integrations → In-App
    Purchase), not the App Store Connect API key `--profile` names; the service rejects that kind.
    The issuer comes from the profile. Skipped when a key is already stored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1527.0",
+  "version": "0.1528.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": "7d4595824e3745b02e52e9cc9c3d3b444992162a8b5792733b07a811"
+  "falconPackageHash": "977ce0e45046b28615366bb368c7ceb90d7a1f9404024a58bee20404"
 }