@wix/himalaya-cli 0.1037.0 → 0.1038.0

package/guides/headless-loop.md

@@ -220,6 +220,13 @@ and every worker `_nav` directive is harvested, and each baked target is booted
 params the source sends — the input a real router push delivers. Detail screens stop being
 tested input-less; findings from edge boots arrive as errors tagged `edge:<source>`.
 
+It also lists what the app **writes to Wix** — `writes[]` in `--json`, a `Writes to Wix`
+section in the report: per screen and action, every call that is not a proven read and every
+native write verb (member signup, payment), none of them sent anywhere. With a `## Data access`
+table in `SPEC.md` (`Screen` + `Wix writes` columns), each write the table does not approve is a
+`write-not-approved` warning. Reconcile that list with the owner-approved matrix before
+publishing; see `himi docs himi-test` → "Writes to Wix".
+
 The run ends with a **gap ledger**: every place the crawl is blind or unproven, each paired
 with the himi command or source edit that closes it — empty lists that gate row taps ("declare
 cms seed rows / add a net-mocks rule"), actions whose effect never reaches observable state,

package/guides/himi-test.md

@@ -91,7 +91,9 @@ in order, ending in a rendered result — add a short screen-local journey to `h
 ```
 
 Every step must name a worker action already declared by that screen; `expectText` is
-mandatory and is checked against the final resolved render tree. Keep cross-screen
+mandatory and is checked against the final resolved render tree. A detail screen that loads
+nothing without an id takes an optional `"input": { "id": "svc-0001" }` — the screen input a nav
+edge would hand it — so the journey boots the way a real tap into it would. Keep cross-screen
 navigation in the ordinary edge pass, which boots the destination with real source
 parameters. Pair dynamic journeys with app-specific `dev/net-mocks.json` fixtures.
 
@@ -229,6 +231,69 @@ went unproven, it names the gap and pairs it with a himi command or a source edi
 derived from what actually ran, never homework. Assembly:
 `tools/himi-cli/src/coverage.ts`.
 
+## Writes to Wix
+
+Every run lists what the app **writes** to the Wix site, per screen and action — the inventory an
+owner-approved plan is checked against. `writes[]` in `--json`, and a `Writes to Wix` section in the
+pretty report:
+
+```jsonc
+"writes": [
+  { "screen": "himi_blog_post", "action": "tier5.himiBlogPost.like", "via": "wix", "method": "POST", "path": "/blog/v3/posts/post-0001/like" },
+  { "screen": "himi_time", "action": "tier5.himiBookingTime.register", "via": "native", "capability": "himi.wix.registerDirect", "kind": "member-signup", "what": "creates a site member" },
+  { "screen": "himi_time", "action": "tier5.himiBookingTime.bookSelected", "via": "wix", "method": "POST", "path": "/ecom/v1/checkouts" }
+],
+"unreachedWrites": [
+  { "screen": "himi_time", "action": "unreached", "via": "native", "capability": "capability.wix_cashier.proceedToPayment", "kind": "payment" }
+]
+```
+
+- **What counts as a write.** Any Wix call that is not a *proven read* — a read is `GET`, or a `POST`
+  whose last path segment is `/query`, `/search`, `/list*`, `/get*`, `/count`, `/aggregate`,
+  `/facets` or `/connections` (the same classifier `--record` uses to decide what it may send to the
+  live site). Plus the native verbs that change the site without the REST transport: member signup
+  (`himi.wix.registerDirect` — or the same verb under another `<ns>.wix` namespace), password
+  reset (`himi.wix.resetPassword`) and payment
+  (`capability.wix_cashier.proceedToPayment`). Sign-in and sign-out open a session and are not writes.
+- **Nothing is sent.** The crawl's transport is hermetic and the host answers native verbs itself; a
+  write is recorded as *attempted*, which is exactly what the worker would send on a device.
+- **Every axis feeds it** — boot, each tap, deep chains, journeys, nav-edge boots and the
+  capability-success pass.
+- **Reach.** A write behind a form or a selection (type an email and a password, then register; pick
+  a slot, then book) is only reached by `--deep` or a typed journey — a single tap from a fresh boot
+  is refused by the worker's own validation. Native write verbs the screen's bundle names but the
+  crawl never reached are listed under `unreachedWrites`, so a signup or a payment is still in front
+  of you. REST writes get no such static pass: their paths are built at run time.
+
+### Checking the writes against the approved plan
+
+Put the owner-approved data-access matrix in `SPEC.md` (or `MOBILE-UX.md`) as a table under a
+`## Data access` heading with a `Screen` column and a `Wix writes` column — other columns are yours:
+
+```markdown
+## Data access
+| Screen | Role | Reads | Wix writes | Prohibited |
+| --- | --- | --- | --- | --- |
+| himi_blog_post | visitor | posts, comments | none | like, comment |
+| himi_time | visitor | services, slots | `bookSelected`, `POST /bookings/v2/bookings` | signup, payment |
+| * | visitor | published content | none | |
+```
+
+A `Wix writes` cell is `none` (or empty, `-`, `read-only`), or a comma list naming each approved
+write by its **action** (`bookSelected` or `tier5.himiBookingTime.bookSelected`), its **endpoint**
+(`POST /bookings/v2/bookings` — exact, with `*` for one path segment such as an id:
+`POST /blog/v3/posts/*/like`), its **capability** (`registerDirect`) or its
+**kind** (`payment`, `signup`). Prose such as "create a booking" approves nothing: it cannot say
+whether the checkout and the payment after it were approved. A `*` row covers every screen without
+its own row. Several rows for one screen (one per role) are combined.
+
+Each write the table does not approve — including an `unreachedWrites` entry — is a
+`write-not-approved` **warning** (warning so a naming slip never fails a run; silence a deliberate
+one in `himi-test.json` like any other finding). With no filled table the writes are listed and
+the report says nothing checked them. **Before publishing**, reconcile the list with the approved
+plan: remove the action, or trim the screen (`himi template trim`), for every write the owner did
+not approve.
+
 ## How agents should use it
 
 **build → test → close the top gap → repeat.** No setup, no session, no simulator, no

package/guides/sdk-reference.json

@@ -16760,7 +16760,7 @@
         "name": "ConversationMessage",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface ConversationMessage {\n  id?: string;\n  content?: string;\n  role?: MessageRole;\n  createdDate?: string;\n  status?: MessageStatus;\n  /** Files the owner attached to this turn, as the service stored them. */\n  attachments?: Attachment[];\n  /** Client tools this assistant turn asks the CALLER to run — see `FunctionCall`. */\n  functionCalls?: FunctionCall[];\n}"
+        "decl": "export interface ConversationMessage {\n  id?: string;\n  content?: string;\n  role?: MessageRole;\n  createdDate?: string;\n  status?: MessageStatus;\n  /** Files the owner attached to this turn, as the service stored them. */\n  attachments?: Attachment[];\n  /** Client tools this assistant turn asks the CALLER to run — see `FunctionCall`. */\n  functionCalls?: FunctionCall[];\n  /** What the owner attached to this turn — a mentioned product, contact,\n   *  page — stored by the service BESIDE the text rather than inside it. The\n   *  transcript echoes them back under this key (the `wix.genie.v1` message\n   *  entity's `references`), which is the only way a reloaded conversation\n   *  can still say what a turn was about. */\n  references?: MessageReference[];\n}"
       },
       {
         "name": "Attachment",
@@ -16792,6 +16792,18 @@
         "jsdoc": "/** The answer to one `FunctionCall`. Note the wire spells the flag `success`. */",
         "decl": "export interface FunctionCallResult {\n  id?: string;\n  name?: string;\n  /** Text for the model — the error text when `success` is false. */\n  content?: string;\n  success?: boolean;\n  /** A JSON-ENCODED object carrying the tool's structured answer. */\n  widgetResponse?: string;\n}"
       },
+      {
+        "name": "MessageReference",
+        "kind": "interface",
+        "jsdoc": "/** One reference riding on a user turn (`messageReferences` on the persist\n *  call, `references` on the stored message).\n *\n *  Field meanings are the chat-service's own, from the\n *  `@wix/ambassador-genie-chat-service-v1-no-entity` `MessageReference` type the\n *  native Aria app sends: `data` is the context handed to the model, `source`\n *  a low-cardinality feature tag, and `type` how a client renders it\n *  (\"inline\" | \"global\" | \"hidden\"). Build a mention's with `mentionReference`\n *  rather than by hand, so the one shape the service is known to accept is\n *  spelled in one place. */",
+        "decl": "export interface MessageReference {\n  id?: string;\n  /** Shown to the owner (a chip label). */\n  label?: string;\n  /** The context the assistant receives — for a mention, a JSON string\n   *  `{\"id\":…,\"type\":…}` naming the item and its category. */\n  data?: string;\n  /** Feature tag, e.g. \"mention\". */\n  source?: string;\n  /** Render scope, e.g. \"global\" — a chip above the text, not a token in it. */\n  type?: string;\n}"
+      },
+      {
+        "name": "mentionReference",
+        "kind": "function",
+        "jsdoc": "/** A mention of one item, in the exact shape the native Aria app sends: a\n *  `global` reference (a chip, not a token in the text) whose `data` names the\n *  item and the category it came from.\n *\n *  `category` is the category's ENGLISH label (\"Products\", \"Contacts\") — it is\n *  what the model reads, so it is not localized. Newlines in the label are\n *  folded to spaces; `JSON.stringify` does the escaping the native client does\n *  by hand. */",
+        "decl": "export function mentionReference(item: { id: string; title: string }, category: string): MessageReference;"
+      },
       {
         "name": "AssistantConfig",
         "kind": "interface",
@@ -16850,7 +16862,7 @@
         "name": "SendMessageOptions",
         "kind": "interface",
         "jsdoc": "/** Optional wire flags on `sendMessage`. `communicationMode` /\n *  `enableRealtimeEvents` were in the original captured payload; only POLLING is\n *  verified end-to-end. The rest were added from the 2026-09-19 re-capture. */",
-        "decl": "export interface SendMessageOptions {\n  communicationMode?: CommunicationMode;\n  enableRealtimeEvents?: boolean;\n  metadata?: UserMessageMetadata;\n  /** The dashboard sends `true`. Optional: verified to answer either way. */\n  enforceAccountScopedConversations?: boolean;\n  /** Tag the turn with the same origin the conversation was created under. */\n  origin?: string;\n  /** Files already UPLOADED (see `createFileUpload`) to store with the turn.\n   *  Rides step 1 only — the trigger names the stored turn, which carries them. */\n  attachments?: Attachment[];\n}"
+        "decl": "export interface SendMessageOptions {\n  communicationMode?: CommunicationMode;\n  enableRealtimeEvents?: boolean;\n  metadata?: UserMessageMetadata;\n  /** The dashboard sends `true`. Optional: verified to answer either way. */\n  enforceAccountScopedConversations?: boolean;\n  /** Tag the turn with the same origin the conversation was created under. */\n  origin?: string;\n  /** References stored WITH the turn (step 1 only — the trigger names a turn\n   *  that already carries them). Omitted, the persist call sends `[]`, which is\n   *  what it always sent. */\n  messageReferences?: MessageReference[];\n  /** Files already UPLOADED (see `createFileUpload`) to store with the turn.\n   *  Rides step 1 only — the trigger names the stored turn, which carries them. */\n  attachments?: Attachment[];\n}"
       },
       {
         "name": "ConversationUserMessageResponse",
@@ -16930,6 +16942,66 @@
         "jsdoc": "/** Fetch the messages of a conversation (poll after sendMessage). */",
         "decl": "export function getConversationMessages(conversationId: string): Promise<GetConversationMessagesResponse>;"
       },
+      {
+        "name": "ItemsPaginationMode",
+        "kind": "type",
+        "jsdoc": "/** How a provider pages its items. Any other value, or none, means unpaged:\n *  `providersOf` reports it as \"NONE\" and such a provider is asked for one\n *  page with no paging block. */",
+        "decl": "export type ItemsPaginationMode = \"CURSOR\" | \"OFFSET\" | \"UNKNOWN_PAGINATION_MODE\";"
+      },
+      {
+        "name": "ItemsSelectionProvider",
+        "kind": "interface",
+        "jsdoc": "/** An installed item provider. Only the fields a picker needs are typed. */",
+        "decl": "export interface ItemsSelectionProvider {\n  /** The handle `queryItems` is addressed by. */\n  key?: string;\n  appId?: string;\n  contentData?: { providerName?: string; iconKey?: string; title?: string };\n  paginationMode?: ItemsPaginationMode | string;\n}"
+      },
+      {
+        "name": "ListInstalledProvidersResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ListInstalledProvidersResponse { providers?: ItemsSelectionProvider[] }"
+      },
+      {
+        "name": "ItemsSelectionItem",
+        "kind": "interface",
+        "jsdoc": "/** One item a provider returned. */",
+        "decl": "export interface ItemsSelectionItem {\n  id?: string;\n  name?: string;\n  description?: string;\n  image?: { url?: string };\n  /** Additional information, e.g. a price. */\n  note?: string;\n}"
+      },
+      {
+        "name": "QueryItemsResponse",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface QueryItemsResponse {\n  items?: ItemsSelectionItem[];\n  pagingMetadata?: { hasNext?: boolean; cursors?: { next?: string } };\n}"
+      },
+      {
+        "name": "ItemsQuery",
+        "kind": "interface",
+        "jsdoc": "/** The query `queryItems` sends. Set `cursorPaging` OR `paging` to match the\n *  provider's `paginationMode`, or neither for an unpaged provider. */",
+        "decl": "export interface ItemsQuery {\n  search?: string;\n  paging?: { limit: number; offset?: number };\n  cursorPaging?: { limit: number; cursor?: string };\n}"
+      },
+      {
+        "name": "listInstalledProviders",
+        "kind": "function",
+        "jsdoc": "/** The item providers installed on the CURRENT site — the categories a mention\n *  picker offers. The site is the one whose signed instance authorizes the\n *  call, so a caller that can switch business must re-list after a switch. */",
+        "decl": "export function listInstalledProviders(): Promise<ListInstalledProvidersResponse>;"
+      },
+      {
+        "name": "queryItems",
+        "kind": "function",
+        "jsdoc": "/** Query one provider's items. `providerKey` is a provider's `key`, never its\n *  display name. */",
+        "decl": "export function queryItems(providerKey: string, query: ItemsQuery = {}): Promise<QueryItemsResponse>;"
+      },
+      {
+        "name": "providersOf",
+        "kind": "function",
+        "jsdoc": "/** The provider list from a `listInstalledProviders` response, with every\n *  entry that has no key or no name dropped — neither can be offered or\n *  queried. */",
+        "decl": "export function providersOf(res: ListInstalledProvidersResponse | null | undefined): Array<{ key: string; name: string; paging: \"CURSOR\" | \"OFFSET\" | \"NONE\" }>;"
+      },
+      {
+        "name": "itemsOf",
+        "kind": "function",
+        "jsdoc": "/** The items from a `queryItems` response, with every entry that has no id or\n *  no name dropped — an item with neither cannot be referenced or shown. */",
+        "decl": "export function itemsOf(res: QueryItemsResponse | null | undefined): Array<{ id: string; title: string; subtitle: string; imageUrl: string }>;"
+      },
       {
         "name": "messagesOf",
         "kind": "function",

package/guides/trim-a-template.md

@@ -70,6 +70,11 @@ footer's target; both are listed under `implicit`. It prints one JSON report and
   sit in `.himi/trim-backup/`, which is deleted once the trim validates (and kept under
   `--force`). A failure while *writing* the trim (a worker directory it cannot move, say) is
   always put back, `--force` or not — `--force` keeps a finished trim, never a half-done one.
+  A validate failure is only blamed on the trim if the trim caused it: the untrimmed app is
+  validated too, and when every error was already there (a font `site analyze --apply` wrote
+  that the catalog lacks, say) the trim is kept, exits `0`, and lists those errors under
+  `preExistingErrors` ("trimmed; N errors were already present before trim: …"). Any error the
+  trim introduced still puts everything back, and is named under `introducedErrors`.
 
 **Links between screens.** A kept screen that opens a removed one (a `himi.open` whose
 `screenId` is a literal) would be a dead tap, so by default the trim is **refused** — and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1037.0",
+  "version": "0.1038.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": "e35236017e826d4e25212e7448f29f8004d84cec687b348a8231366e"
+  "falconPackageHash": "9cdd57a20df8f0a031d3306a62fee19f8378bdacaa6701a74ba4bb59"
 }