@wix/himalaya-cli 0.1432.0 → 0.1433.0

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,10 +89,14 @@ 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`
@@ -112,15 +116,21 @@ 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 |
@@ -129,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.
 
@@ -151,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 |
 |---|---|
@@ -187,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
 

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/package.json

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