@wix/himalaya-cli 0.1431.0 → 0.1432.0

package/guides/base44-app-context.md

@@ -108,7 +108,7 @@ read-only, but it writes the book folder, so it is not annotated read-only to th
   ],
   "functions": [
     { "name": "sendReport", "sourcePath": "base44/functions/sendReport/entry.ts", "kind": "http",
-      "methods": ["POST"], "invoke": "base44.functions.invoke(\"sendReport\", payload)",
+      "methods": ["POST"], "invoke": "functions.invoke(\"sendReport\", payload)",
       "automations": [{ "name": "weekly", "type": "scheduled", "schedule": "0 9 * * 1" }] }
   ],
   "agents": [{ "name": "job_helper", "tools": [{ "entity": "Job", "operations": ["read"] }] }],
@@ -128,7 +128,7 @@ app's own project files) or `rest` (the owner-authenticated API). Treat an opera
 empty.
 
 `BOOK.md` is the same content, summarised for an agent. For each entity it lists the worker calls
-the Himi app would make through the `@himalaya/base44` capability: `base44.entities.<Name>.list()`,
+the Himi app would make through the `@himalaya/base44` capability: `entities("<Name>").list()`,
 `.filter({…})`, `.get(id)`, and the writes (`create`, `update`, `delete`) that the entity's rules do
 not forbid outright.
 

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

@@ -99,6 +99,17 @@ base44: { appId: "<id>", entities: base44Entities, functions: base44Functions },
 reports row counts and schema drift against the live app. See
 [`base44-entities`](base44-entities.md) (`himi docs base44-entities`).
 
+Then generate typed handles from the declaration, and import them in the workers instead of
+spelling entity names:
+
+```bash
+himi base44 types --content .     # → tier5-src/_shared/base44-entities.ts (commit it)
+```
+
+A field typo on a typed row (`row.titel`) is then a `himi validate` type error rather than a blank
+cell on device. Re-run it after editing the block — `himi validate` reports `base44-types-stale`
+until you do. See [`base44-sdk`](base44-sdk.md#typed-rows).
+
 ## 3. Plan the screens from the book
 
 Write `.himi/screen-plan.md` before editing code. For each entity in `book.entities`:
@@ -285,8 +296,14 @@ himi run --content .                         # web preview against the live Base
 ```
 
 `himi test` crawls every action against the real workers with hermetic transport, so it proves
-the wiring, not your data. Its gap ledger names what the hermetic crawl could not reach (rows that
-only exist on the live app, for instance). Close a gap with the remedy it names, or accept it.
+the wiring, not your data. Base44 reads are served from rows you already have: an owned entity's
+`seed:` rows in the `base44.entities` block, then an adopted entity's redacted `sampleRows` from
+`.himi/base44-book/book.json` in the content directory (copy the book in, or re-run analyze with
+`--out .himi/base44-book`). So a list screen crawls populated, its row actions get a row to act on,
+and a typo'd entity name fails loudly instead of rendering empty. Writes and `functions.invoke` are
+refused in the crawl by design, so their error paths are what it exercises. With no seed and no
+book, a declared Base44 read answers nothing and the list crawls empty, as before. Its gap ledger
+names what the hermetic crawl could not reach (rows that only exist on the live app, for instance). Close a gap with the remedy it names, or accept it.
 Then drive the real flow in `himi run`: list, create, edit, delete a row of each entity, and
 sign in when the app is not public.
 

package/guides/himi-test.md

@@ -201,6 +201,16 @@ assembles it from four layers in priority order, **none of which touches the wir
 4. **offline reject** — the floor that always exists; see the failure UI head-on
    (`--offline`).
 
+**Base44 apps have a fifth, beside these.** Base44 reads are `capability.base44.*` calls on the
+host bus, not HTTP, so the layers above never see them. The crawl serves them from the
+`base44.entities` block's `seed:` rows (owned entities, keyed by the physical `Himi<App><Name>`),
+then from `.himi/base44-book/book.json`'s redacted `sampleRows` (adopted entities, keyed by the
+Base44 name). `list` honours `sort` / `skip` / `limit` / `fields`, `filter` matches top-level
+equality only, `get` finds by `id`. An entity neither knows is an error (`http_404`) naming it,
+never `[]`; writes and `functions.invoke` are refused by design. The transport line says
+`+ base44 (N entities …)` when the layer is on. With neither seed nor book it is off, and a
+declared Base44 read answers `null` (the SDK's empty list) as it always did. `--offline` strips it.
+
 **Need your site's real shapes?** `himi test --record` refreshes layer 1 from live reads —
 `load()` and `onAppear` **only**, read-path-only by construction (GET and read-shaped POST;
 every write refused at the transport) — then crawls hermetically on what it froze. Explicit

package/guides/sdk-reference.json

@@ -468,14 +468,14 @@
       {
         "name": "EntityHandle",
         "kind": "interface",
-        "jsdoc": "",
-        "decl": "export interface EntityHandle {\n  list(opts?: ListOptions): Promise<Base44Row[]>;\n  filter(query: JsonObject, opts?: ListOptions): Promise<Base44Row[]>;\n  get(id: string): Promise<Base44Row>;\n  create(data: JsonObject): Promise<Base44Row>;\n  update(id: string, patch: JsonObject): Promise<Base44Row>;\n  delete(id: string): Promise<void>;\n  bulkCreate(rows: JsonObject[]): Promise<Base44Row[]>;\n}"
+        "jsdoc": "/**\n * One entity's verbs. `T` is the row shape: `Base44Row` (untyped) unless the caller names one,\n * e.g. a row type generated by `himi base44 types`. A row type must be a type alias, not an\n * `interface` — only an alias satisfies `Base44Row`'s `JsonObject` index signature.\n */",
+        "decl": "export interface EntityHandle<T extends Base44Row = Base44Row> {\n  list(opts?: ListOptions): Promise<T[]>;\n  filter(query: JsonObject, opts?: ListOptions): Promise<T[]>;\n  get(id: string): Promise<T>;\n  create(data: Partial<T>): Promise<T>;\n  update(id: string, patch: Partial<T>): Promise<T>;\n  delete(id: string): Promise<void>;\n  bulkCreate(rows: Partial<T>[]): Promise<T[]>;\n}"
       },
       {
         "name": "entities",
         "kind": "function",
-        "jsdoc": "/** Typed access to one entity of the configured Base44 app, e.g. `entities(\"Task\").list()`. */",
-        "decl": "export function entities(name: string): EntityHandle;"
+        "jsdoc": "/**\n * Typed access to one entity of the configured Base44 app, e.g. `entities(\"Task\").list()`.\n * Pass a row type to type the rows: `entities<TaskRow>(\"Task\")`. Types only — runtime is identical.\n */",
+        "decl": "export function entities<T extends Base44Row = Base44Row>(name: string): EntityHandle<T>;"
       },
       {
         "name": "functions",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1431.0",
+  "version": "0.1432.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": "cb6ae1657ee30165de2fe500a05d3f531ee3a61071976c6db531172e"
+  "falconPackageHash": "796dbf6642a176106f5ab3335bbab9788c281db7f264524e0c7fb8e3"
 }