@wix/himalaya-cli 0.1431.0 → 0.1433.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

@@ -61,8 +61,8 @@ whose `Task` entity anyone may read and write:
 
 | Tab | Screen | Worker | Pattern it shows |
 |---|---|---|---|
-| Tasks | `b44_tasks` | `tasks` | list, create, bulk-create, update, delete; loading / empty / error / ready; pull to refresh |
-| (pushed) | `b44_task` | `task` | read one row by its id (a nav param), edit, delete then go back |
+| Tasks | `b44_tasks` | `b44-task-list` | **generated** by `himi base44 screens`: list, create, delete; loading / empty / error / ready; pull to refresh |
+| (pushed) | `b44_task` | `b44-task` | **generated**: read one row by its id (a nav param), edit, delete then go back |
 | Functions | `b44_functions` | `functions` | `functions.invoke(name, payload)` with the reply and the error painted |
 | Account | `b44_account` | `account` | Native Google sign-in (requires tenant app-link associations), email + password and emailed-code sign-in, register, reset, profile, sign out |
 
@@ -89,27 +89,48 @@ Turn the book's entities and functions into an adopted declaration, then wire it
 himi base44 adopt --content . --book ../.himi/base44-book --write   # the book step 1 wrote, one level up → base44-entities.ts (never overwrites)
 ```
 
+The starter's `config.ts` declares the sample `Task` as a local `const base44Entities = [...]`.
+Delete that declaration, then import yours in its place (keeping both fails with "Identifier
+'base44Entities' has already been declared"):
+
 ```ts
 import { base44Entities, base44Functions } from "./base44-entities.js";
 // …
-base44: { appId: "<id>", entities: base44Entities, functions: base44Functions },
+base44: { appId: base44AppId, entities: base44Entities, functions: base44Functions },
 ```
 
 `himi validate` then lints the declaration (`pass: "base44"`), and `himi base44 entities query`
 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
 
+`himi base44 screens` (step 4) applies the rules below for you, so this step is about choosing
+**what to declare**: which entities, in what order (with up to three entities each gets a tab; with
+four or more, the first two get tabs and the rest go under More), which fields and which `rls`. The rules describe what the generator emits. Read them to predict the result, and to
+know what to customise afterwards.
+
 Write `.himi/screen-plan.md` before editing code. For each entity in `book.entities`:
 
 1. **Decide whether it gets a tab.** An entity that a top-level route reads (`routes[].entities`)
    and that a user browses gets a tab. A child entity (one whose rows only make sense under a
    parent, such as `OrderItem` under `Order`) gets a section on the parent's detail screen
    instead. Keep to 3–5 tabs. Account always takes one when the app is not public (step 5).
-2. **Pick the list row.** The title is the first `required` string field, preferring one named
-   `title`, `name` or `label`. The subtitle is one or two short fields (a status `enum`, a date, a
-   number). Never put a long text field in a row.
+2. **Pick the list row.** The title is the entity's `displayField` if it declares one, else the
+   first `required` string field, preferring one named `title`, `name` or `label`. The subtitle is
+   one or two short fields (a status `enum`, a date, a number). Never put a long text field in a
+   row.
 3. **Pick the detail and form fields** from each field's JSON Schema type:
 
 | Field (`type` / `format` / `enum`) | Detail shows | Form control |
@@ -118,20 +139,28 @@ Write `.himi/screen-plan.md` before editing code. For each entity in `book.entit
 | `string` + long text (`description`, `notes`, `body`, …) | `Text` with `maxLines` | `TextField` with `multilineMaxLines` |
 | `string` + `enum` | `Badge` / `Text` | `SegmentedControl` (≤ 4 values) or `Picker` |
 | `string` + `format: date` / `date-time` | formatted `Text` | `DatePicker` |
-| `string` + `format: email` / `uri` | `Text`, tap opens mail / URL | `TextField` with `keyboard: "email"` / `"url"` |
+| `string` + `format: email` / `uri` | `Text` (the generator does not make it tappable yet) | `TextField` with `keyboard: "email"` / `"url"` |
 | `string` holding an image URL (`image`, `photo`, `avatar`, `*_url`) | `Image` | read-only, see [file upload](#what-the-sdk-cannot-do) |
 | `number` / `integer` | `Text` (with unit) | `Stepper` (small ranges) or numeric `TextField` |
 | `boolean` | `Badge` or `Text` | `Toggle` |
-| `array` of strings | `FilterChips` / `ChipsInput` (read-only) | `ChipsInput` |
-| `object` / nested `array` of objects | a sub-section of rows | none at first. Edit it on the web app |
+| `array` of strings | comma-joined `Text` | `ChipsInput` |
+| `object` / nested `array` of objects | its JSON as `Text` (a sub-section of rows is yours to build) | none. Edit it on the web app |
 | built-ins `id`, `created_date`, `updated_date`, `created_by` | "Created …" metadata row | never editable |
 
 4. **Respect the entity's rules.** `rls` (and field-level `rls`) decide what the signed-in user
-   may do. Offer only the writes `BOOK.md` lists for the entity. An operation whose rule is
-   `false` gets no button. A rule that is a condition (`{ "created_by": "{{user.email}}" }`)
-   means the write only works for a signed-in user, on their own rows, so it belongs behind
-   sign-in (step 5). A denied call still fails with Base44's message, and every screen must paint
-   that error rather than swallow it.
+   may do. Declare the `rls` `BOOK.md` lists for the entity. The generator gates each write
+   control on its operation's rule (falling back to the entity-level `write` rule):
+
+   | Rule | Control |
+   |---|---|
+   | `false`, or absent | not emitted at all |
+   | `true` | always shown |
+   | exactly `{ "created_by": "{{user.email}}" }` or `{ "created_by_id": "{{user.id}}" }` | shown only on the signed-in user's own rows |
+   | any other condition | shown only when signed in |
+
+   A field whose field-level `rls.write` is not `true` is read-only in the form. The gate is
+   advisory: a denied call still fails with Base44's message, and every screen paints that error
+   rather than swallowing it.
 5. **Use the sample rows** (`sampleRows`, already redacted) to size rows and choose the subtitle,
    never as data the app ships.
 
@@ -140,22 +169,48 @@ Compose each screen with [`designing-himi-screens`](designing-himi-screens.md)
 
 ## 4. Build one list + detail per entity
 
-Copy the Task pair and rename it. For an entity `Project`:
+Declare the entity, then generate its screens:
+
+```bash
+himi base44 adopt --content . --book ../.himi/base44-book --write   # or declare by hand (step 2)
+himi base44 screens --content . --json
+```
+
+For each entity in `config.ts` `base44.entities`, `himi base44 screens` writes a list screen
+(`b44_<plural>`, e.g. `b44_projects`) and a detail screen (`b44_<name>`, e.g. `b44_project`):
+
+- `tier5-src/_shared/b44-<entity>-plan.ts`: the plan (row title and subtitle, facts, form
+  controls, write gates) the rules in step 3 produce. The list, the detail and the descriptors all
+  read it, so this is the file to customise.
+- `tier5-src/b44-<entity>-list/index.ts` and `tier5-src/b44-<entity>/index.ts`: one-line worker
+  entries over the template's shared engine (`_shared/entity-list.ts`, `_shared/entity-detail.ts`).
+  Each entity gets its own bundle and service, so two entity tabs never share state.
+- `dev/entities.generated.ts` and `config.entities.generated.ts`: the screen registrations and the
+  `linkableScreens` / `tabBar` items. `dev/index.ts` and `config.ts` already import them.
+
+The first three entities in config order get a tab, in front of Functions and Account. With more,
+the last entity slot becomes a generated `b44_more` screen listing the rest, so the bar never has
+more than five items. Ids pluralise naively (`Category` → `b44_categories`, `Person` →
+`b44_persons`); give the entity a `title` for the visible name. Two entities that would share an id
+are refused with `code: "entity_id_collision"`.
+
+Re-running is safe. Each generated file starts with
+`// @generated by himi base44 screens — sha256:<hash>`:
+
+- an unchanged config reports every file `unchanged` and writes nothing;
+- a generated file you edited by hand (its body no longer matches the hash) is reported
+  `skipped-edited` and left alone, and the command still exits 0. Pass `--force` to overwrite it;
+- files for an entity you removed from `config.ts` are reported in `orphaned[]` and never deleted.
+
+`--dry-run` reports the same outcomes without writing. Failures carry a top-level `code`
+(`no_entities_block`, `entity_id_collision`, `content_dir_not_base44_starter`), per
+[`himi-json-output`](himi-json-output.md). The generator never calls Base44.
 
-- `tier5-src/projects/index.ts` from `tier5-src/tasks/index.ts`. Set `ENTITY = "Project"`, the
-  service name (`b44Projects`), and `toRow()` for the fields you chose. Keep the structure:
-  module-eval `load()`, the `latestList` sequence that drops stale replies, the `pendingWrites`
-  guard, and `derive()` producing the `hide*` flags.
-- `tier5-src/project/index.ts` from `tier5-src/task/index.ts`. `inputId()` reads the row id from
-  the nav param, `get(id)` loads it, and `remove` returns `navigate(…, { presentation: "back" })`
-  from the action the host dispatched.
-- In `dev/index.ts`, a `projects()` and a `project()` builder (copy `tasks()` and `task()`), each
-  bound with `bundle: "<worker dir>"` and `declaredCapabilities: ["base44"]`. Register both in
-  `screens.exact` and the tab root in `seed.screens`.
-- In `config.ts`, a `linkableScreens` entry for each (the detail with `paramKeys: ["id"]` and its
-  list as `parentScreenId`) and a `tabBar` item for the list.
+To change a screen beyond what the plan expresses (a filtered list, a child section, a custom
+action), edit its generated entry or plan. The edit makes the file `skipped-edited`, so the
+generator leaves it alone from then on.
 
-The calls a worker makes, all on `entities("<Name>")`:
+The calls the engine makes (and a customised worker can make), all on `entities("<Name>")`:
 
 | Need | Call |
 |---|---|
@@ -176,7 +231,9 @@ Rules that keep it correct:
   `$item.openLabel`. `himi validate` flags this as an error.
 - **Every write re-lists**, and a failed write keeps the list on screen with the error above it.
   Only a failed *first* list is the error state.
-- Remove `tasks` / `task` once your own entities replace them, and change `homeScreenId`.
+- Replace the sample `Task` declaration with your own entities and re-run `himi base44 screens`.
+  The home screen is the first entity's list. The generator reports the sample's files as
+  `orphaned`; delete them by hand.
 
 ## 5. Auth: the Account tab
 
@@ -285,8 +342,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/base44-entities.md

@@ -147,4 +147,3 @@ Failure codes are listed in [`himi-json-output`](himi-json-output.md#himi-base44
   full-set sync, which is why it is a separate, deliberate step.
 - **Typed clients and hermetic test data**: `entities<"X">()` typed from the declaration, with
   `seed` rows as mocks.
-- **Generated screens**: list and detail screens per declared entity.

package/guides/himi-json-output.md

@@ -249,6 +249,24 @@ branch on them without parsing prose:
 - `source_unavailable`: the project download (the eject read) failed, so no drift was
   computed. Row counts still ran; `sourceRead` is `"unavailable"` and `sourceError` says why.
 
+## `himi base44 screens` codes
+
+`himi base44 screens` (#4560, [base44-app-to-himi-app](base44-app-to-himi-app.md)) generates one
+list + detail screen per declared `base44.entities` entity. Failures print `ok: false` and `code`
+on stderr (exit 1):
+
+- `content_dir_not_base44_starter`: the directory lacks the shared engine the generated files
+  import (`missing[]` names the files). Scaffold with `himi init --template base44-starter`.
+- `no_entities_block`: `config.ts` declares no `base44.entities`, so there is nothing to generate.
+- `entity_id_collision`: two entities would generate the same screen id (or one would shadow
+  `b44_functions` / `b44_account` / `b44_more`); `entity`, `screenId` and `with` name the clash.
+- `config_unloadable` / `invalid_config`: as for `himi base44 entities` above.
+
+On success (`ok: true`, stdout, exit 0) `files[]` gives every generated path with its `outcome`:
+`written`, `unchanged`, or `skipped-edited` (the file was edited by hand and was left alone; pass
+`--force` to overwrite it). A skipped file is not a failure. `orphaned[]`, when present, lists
+generated files for entities no longer declared. They are never deleted.
+
 ## Follow-ups
 
 - Migrate failure envelopes in subcommands other than `push`, keeping this contract.

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.1433.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": "f0352e9dd51208b098564413b02976840565ff1539e321ae4ea327f5"
 }