@wix/himalaya-cli 0.838.0 → 0.839.0

package/guides/cms-collections.md

@@ -84,8 +84,9 @@ An adopted `wixId` declaration is **optional for reads**. A worker may call
 read even when `config.ts` has no `cms` block; declaring it records the expected
 schema for humans and `himi validate`, but does not grant or enable that read.
 
-`himi cms query` labels every collection on the site `owned`, `adopted`, or
-`foreign`, so the blast radius is visible before you run anything.
+`himi cms query --all` labels every collection on the site `owned`, `adopted`, or
+`foreign`, so the blast radius is visible before you run anything. (Without `--all`
+it reads only the ids you declare — see [below](#himi-cms-query--read-only).)
 
 ### `site analyze --apply` adopts, it never claims
 
@@ -275,7 +276,8 @@ boots as — an unauthenticated visitor — rather than as one it has no way to
 export WIX_SITE_ID=<msid>          # or pass --site <msid> to every command
 
 himi validate                      # offline: prefix, field types, displayField, seed keys, permissions
-himi cms query                     # READ-ONLY: what exists, who owns it, where it drifts
+himi cms query --all               # READ-ONLY: what the SITE has, including collections you never declared
+himi cms query                     # READ-ONLY: just your declared ids — what exists, who owns it, where it drifts
 himi cms create                    # provision the owned collections (idempotent)
 himi cms seed                      # fill the EMPTY owned collections from `seed:`
 himi push --draft                  # ship the content package; does NOT touch the site
@@ -287,13 +289,67 @@ publishing a release is exactly the surprise this design avoids.
 
 ### `himi cms query` — read-only
 
-Every collection on the site, labeled `owned` / `adopted` / `foreign`, with item
-counts for the declared ones and a `drift` list: declared-but-missing collections,
-missing fields, undeclared extra fields, and type mismatches. Run it first, and run
-it after `create` to confirm.
+**By default it reads only the ids you declared.** One targeted `GET` per declared
+collection, and the report says so with `siteScanned: false`. You get item counts and
+a `drift` list: declared-but-missing collections, missing fields, undeclared extra
+fields, and type mismatches. Run it first, and run it after `create` to confirm.
 
-Item counts are fetched only for *declared* collections — a site inventory doesn't
-fan out a query per foreign collection.
+The default never lists the site, so it cannot show you a collection you did not
+declare — **including one this app owns**. A leftover `himi_<app>_*` from a renamed
+declaration is labeled `owned` when the scan finds it, but only `--all` looks.
+
+The default stays off the site-wide list on purpose: that list is ~1MB and 46–60s on
+a real site (194 collections on one test site) and its socket gets reset mid-transfer,
+while the per-id reads it actually needs are ~3KB each.
+
+#### `--all` — scan the site and discover what to adopt
+
+`himi cms query --all --site <msid>` additionally lists the whole site and describes
+every **foreign** collection — one this app neither owns nor declares:
+
+```json
+{
+  "siteScanned": true,
+  "foreign": {
+    "count": 31,
+    "collections": [
+      { "id": "QaRecipes", "displayName": "Recipes", "readRole": "ANYONE", "itemCount": null,
+        "fields": [ { "key": "title", "type": "TEXT" }, { "key": "cookMinutes", "type": "NUMBER" } ] }
+    ],
+    "truncated": 6
+  }
+}
+```
+
+That is enough to write the adopted declaration without a second call: `wixId` is the
+`id`, and the `fields` carry the keys **and** the types a declaration must mirror (Wix
+cannot retype a field in place, so a wrong type is a refusal, not a warning). A field
+with no `type` is one the site did not report a type for — read that collection directly
+before declaring it, rather than guessing; the scan will not invent one for you.
+
+- **It works with no `cms` block at all.** Discovering what to declare is precisely the
+  case where nothing is declared yet, so `--all` is the one flag for which a missing
+  `cms` block is *not* "nothing to do".
+- **Foreign collections are never item-counted** (`itemCount: null`). A row count is one
+  query each, and fanning that across a whole site is the cost this scan must not pay.
+  Declare or adopt the collection and the count arrives with the next `himi cms query`.
+- **Only the first 25 are described.** `foreign.count` is how many the scan listed and
+  `foreign.truncated` says how many of those went undescribed, so a short list is never
+  mistaken for a short site. For the full per-collection picture — field types,
+  read/write roles and sample rows — use
+  [`himi site analyze --site <msid>`](wix-business-context.md).
+- **`foreign.count` is not a site census.** `GET /data/v2/collections` is paged and this
+  scan reads one page. When Wix reports a total larger than that page,
+  `unlistedCollections` says how many the listing left out; when Wix reports no total,
+  neither field can tell you, so treat `foreign.count` as "foreign collections in what we
+  listed" and use `site analyze` if you need certainty about a very large site.
+
+**The scan is owner-scoped, and there is no tokenless alternative.** It needs
+`--site <msid>` (or `WIX_SITE_ID`) and owner auth via `wix token`, because enumerating
+collections is `GET /data/v2/collections`, which requires the *Manage Data
+Collections* scope. A visitor/anonymous token can read the **items** of an
+`ANYONE`-read collection whose id you already have, but it can never list collections —
+so no CLI work can make the tokenless path discover them.
 
 ### `himi cms create` — additive and idempotent
 

package/guides/wix-site-to-himi-app.md

@@ -184,7 +184,9 @@ images stay as `static.wixstatic.com` URLs in descriptors — do not vendor
 
 ### 4. CMS, verticals, forms, pages
 
-- **CMS the site already has** — `himi cms query`, then **adopt** with `wixId` in
+- **CMS the site already has** — `himi cms query --all --site <msid>` (owner-scoped;
+  it is the only door that reveals a collection id you do not already know), then
+  **adopt** with `wixId` in
   `config.ts` (`himi docs cms-collections`). Read-only. Never seed or alter a
   collection you did not create. Create `himi_<appSlug>_*` only for storage the
   site does not have.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.838.0",
+  "version": "0.839.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": [
@@ -63,5 +63,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "9fd823cad2c263e2917b872794458e3c97e9ffc0040e182088a08fa5"
+  "falconPackageHash": "5de4fef57d6c6e87d57791a1f1af4e7bd241ef8902a4fbb3292442a0"
 }