@wix/himalaya-cli 0.1430.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

@@ -4,7 +4,7 @@ This page takes an agent from a [Base44](https://base44.com) app to a running Hi
 uses that app's backend, with the himi CLI alone:
 
 ```
-himi base44 analyze  →  himi init --template base44-starter  →  one list + detail per entity  →  himi test  →  himi run / Himi Player
+himi base44 analyze  →  himi init --template base44-starter  →  himi base44 adopt  →  one list + detail per entity  →  himi test  →  himi run / Himi Player
 ```
 
 The Base44 app keeps its data, its users and its backend functions. The Himi app is a native UI
@@ -81,6 +81,35 @@ himi run --content .                         # web preview — the Tasks tab lis
 If your app has no `Task` entity, the Tasks tab shows its error state with Base44's own message.
 That is expected: you are about to replace it.
 
+### Declare the entities the app uses
+
+Turn the book's entities and functions into an adopted declaration, then wire it into `config.ts`:
+
+```bash
+himi base44 adopt --content . --book ../.himi/base44-book --write   # the book step 1 wrote, one level up → base44-entities.ts (never overwrites)
+```
+
+```ts
+import { base44Entities, base44Functions } from "./base44-entities.js";
+// …
+base44: { appId: "<id>", 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
 
 Write `.himi/screen-plan.md` before editing code. For each entity in `book.entities`:
@@ -267,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/base44-entities.md

@@ -0,0 +1,150 @@
+# Base44 entities and functions (declare, lint, adopt, query)
+
+A Himi app on [Base44](https://base44.com) names the entities and backend functions it depends on
+in `config.ts`. With that declaration, `himi validate` lints it, `himi base44 adopt` writes it from
+a book, and `himi base44 entities query` reports row counts and schema drift against the live app.
+
+This is the Base44 sibling of [`cms-collections`](cms-collections.md) (`himi docs cms-collections`).
+It reuses the same ideas (owned versus adopted, an offline lint, a read-only drift report) but not
+the same block: Base44 field types, access rules and naming differ from Wix Data.
+
+> **Read-only in this release.** Nothing here writes to a Base44 app. Creating schemas, seeding
+> rows and deploying functions come next (see [Coming next](#coming-next)).
+
+## The block
+
+```ts
+import { defineApp } from "@wix/himalaya/core";
+import { base44Entities, base44Functions } from "./base44-entities.js";
+
+export default defineApp({
+  // …
+  capabilities: ["base44"],
+  base44: {
+    appId: "69725232345f461f64ad1623",
+    entities: [
+      ...base44Entities,                       // ADOPTED: the Base44 app's own entities
+      { name: "Note", fields: [{ key: "body", type: "string" }], seed: [{ body: "Hello" }] }, // OWNED
+    ],
+    functions: [...base44Functions, { name: "importCsv" }],
+  },
+});
+```
+
+Each entity is one of two kinds:
+
+| Kind | Declared by | Physical entity | himi may |
+|---|---|---|---|
+| **Owned** | `name: "Note"` (alphanumeric) | `Himi<AppPascal>Note`. For app `todo` that is `HimiTodoNote`, and for `video-courses` it is `HimiVideoCoursesNote` | create, seed (coming next) |
+| **Adopted** | `base44Name: "Customer"` | `Customer`, verbatim | read only |
+
+Base44 entity names are alphanumeric only, so the CMS `himi_<app>_` prefix cannot be used. The
+owned prefix is `Himi` plus the app slug in PascalCase, where each `[a-z0-9]+` run is capitalized.
+
+With no separator available, two himi apps bound to the **same** Base44 app can have overlapping
+prefixes (`todo` → `HimiTodo`, `todo-list` → `HimiTodoList`). Give apps that share one Base44 app
+slugs that are not prefixes of each other.
+
+An entity's fields are JSON Schema properties:
+
+```ts
+{ key: "status", type: "string", enum: ["open", "done"], default: "open" }
+{ key: "due", type: "string", format: "date-time" }
+{ key: "tags", type: "array", items: { type: "string" } }
+{ key: "notes", type: "string", rls: { read: { user_condition: { role: "admin" } } } }
+```
+
+- `type`: one of `string`, `number`, `integer`, `boolean`, `array` or `object`.
+- `format` (strings only): one of `date`, `date-time`, `time`, `email`, `uri`, `uuid`, `file` or `richtext`.
+- Entity- and field-level `rls` is the Base44 rule, verbatim. himi does not reinterpret it.
+- Do not declare the built-in fields (`id`, `created_date`, `updated_date`, `created_by`,
+  `created_by_id`). Base44 adds them to every row.
+
+A function is owned (`name`, with its source under `base44/functions/<name>/`) or adopted
+(`base44Name`, an existing backend function that is invoked only).
+
+The types are exported from `@wix/himalaya/core` (`@himalaya/core` in this repo):
+`Base44EntitySpec`, `Base44FieldSpec` and `Base44FunctionSpec`.
+
+## The lint
+
+`defineApp` throws on the first error, so a bad block fails at load time, just as a bad `appId`
+does. `himi validate` and `himi push` report every finding with `pass: "base44"`, beside the
+`pass: "cms"` findings, and `--strict` promotes warnings to errors. Each finding carries a stable
+`ruleCode`:
+
+| `ruleCode` | Severity | Fires when |
+|---|---|---|
+| `entity-name-invalid` | error | the `name` or `base44Name` is not alphanumeric (starting with a letter) |
+| `entity-owned-and-adopted` | error | the entity has both `name` and `base44Name` |
+| `entity-neither-owned-nor-adopted` | error | the entity has neither |
+| `entity-duplicate` | error | two declarations resolve to one physical entity |
+| `adopted-in-owned-namespace` | error | a `base44Name` starts with the app's own `Himi<AppPascal>` prefix |
+| `field-builtin` | error | a built-in field is declared |
+| `field-duplicate` | error | a field key appears twice |
+| `field-type-unsupported` | error | a field `type` (or an array's `items.type`) is not in the list above |
+| `field-format-invalid` | error | a `format` is unsupported or set on a non-string field |
+| `display-field-unknown` | error | `displayField` names no field |
+| `required-unknown` | error | `required` names an undeclared field |
+| `seed-on-adopted` | error | an adopted entity declares `seed`. himi never writes to entities it does not own |
+| `seed-key-unknown` | error | a seed row sets an undeclared field |
+| `function-name-invalid` | error | a function name is not letters, digits, `-` or `_` |
+| `function-owned-and-adopted` / `function-neither-owned-nor-adopted` | error | as for entities |
+| `function-duplicate` | error | a function is declared twice |
+| `shape-invalid` | error | a list or entry has the wrong JSON shape |
+| `read-rule-user-scoped` | warning | `rls.read` names the signed-in user (`{{user.…}}`), so a signed-out viewer sees an empty list |
+
+## `himi base44 adopt`: write the declaration from a book
+
+```bash
+himi base44 analyze --app-id <id>                  # → .himi/base44-book/book.json
+himi base44 adopt                                  # print base44-entities.ts
+himi base44 adopt --write                          # write it next to config.ts
+himi base44 adopt --entities Job,Customer --json   # a subset, as JSON
+```
+
+`adopt` maps each book entity to `{ base44Name, title, fields, required, rls }` and each function
+to `{ base44Name }`. It drops a field it cannot declare (such as a `$ref` type or a built-in) and
+lists it under `skipped[]` with the reason, so nothing disappears silently. The module exports
+`base44Entities` and `base44Functions`, each one `satisfies` its spec type, and passes the lint
+with zero errors.
+
+`adopt` never edits `config.ts`, because a generated module is reviewable and an edit to
+hand-written TypeScript is not. It also never overwrites an existing file (`code:
+"adopt_target_exists"`). Add one line to `config.ts` yourself.
+
+## `himi base44 entities query`: drift and counts (read-only)
+
+```bash
+himi base44 entities query --content .        # needs `himi base44 login` (or BASE44_ACCESS_TOKEN)
+himi base44 entities query --all              # also name the foreign entities
+```
+
+For each declared entity it reports:
+
+- `ownership`: `owned` or `adopted`;
+- `rows`: counted by paging `GET …/entities/<E>?fields=id&limit=500`, up to 5000 rows. Past that
+  cap it reports `capped: true`, and `rows` is a floor. Base44 lists have no total;
+- `drift` against the live schema: `missing`, `missing-field`, `extra-field` or `type-mismatch`
+  (the same vocabulary as `himi cms query`). It also reports an informational `rls-mismatch` when
+  the declared `rls` differs from the live one.
+
+`foreign` lists the live entities the config does not declare. It is a count by default and the
+names with `--all`.
+
+Base44 has no REST read for entity schemas, so the live schemas come from the project download
+(the read half of `base44 eject`, the same request `himi base44 analyze` makes). This needs an
+owner or editor session. When that read fails, the report says `sourceRead: "unavailable"` (with
+`code: "source_unavailable"`), computes no drift, and still counts rows. Every call the command
+makes is a `GET`.
+
+Failure codes are listed in [`himi-json-output`](himi-json-output.md#himi-base44-entities-codes).
+
+## Coming next
+
+- **Provisioning**: `create`, `seed` and `functions deploy` for owned entities and functions. It
+  consumes `diffEntityFields` and the `Base44QueryReport`. Base44's schema write is a destructive
+  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

@@ -219,6 +219,36 @@ redirects, invalid data, source changes and disk errors remain failures.
   and the original failure is preserved if writing the failure manifest also fails
   (exit 1).
 
+## `himi base44 entities` codes
+
+Covers `himi base44 adopt` and `himi base44 entities query` (#4557,
+[base44-entities](base44-entities.md)). Failures print `ok: false` and `code` on stderr.
+
+- `book_unreadable`: `adopt` could not read `<book>/book.json`, or it is not a Base44 app
+  book. Run `himi base44 analyze --app-id <id>` first (exit 1).
+- `unknown_entity`: `adopt --entities` names an entity the book does not have; `known` lists
+  the book's entities (exit 2).
+- `adopt_target_exists`: `adopt --write` refused to overwrite an existing file; `path` names
+  it (exit 1).
+- `adopt_lint_errors`: the generated declaration would fail `himi validate`; `issues[]`
+  carries each `ruleCode`. Adopt only emits what the lint accepts, so this means a bug in
+  `adopt` (exit 1).
+- `unknown_subcommand`: `himi base44 entities` was given no subcommand, or one other than
+  `query` (exit 2).
+- `config_unloadable`: `entities query` could not load `config.ts` (exit 1).
+- `invalid_config`: the `base44` block has lint errors; `issues[]` carries each one's
+  `ruleCode` (exit 1). `himi validate` reports the same findings with `pass: "base44"`.
+- `not_signed_in`: `entities query` needs a Base44 session: `himi base44 login`, or
+  `BASE44_ACCESS_TOKEN` (exit 2).
+
+Two codes ride on a **successful** envelope (`ok: true`, stdout, exit 0), so a consumer can
+branch on them without parsing prose:
+
+- `no_base44_block`: the config has no `base44` block, so there was nothing to query.
+  `declared` is `0`, matching `himi cms query`.
+- `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.
+
 ## 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/index.json

@@ -270,6 +270,12 @@
       "category": "CLI & Loop",
       "file": "base44-app-to-himi-app.md"
     },
+    {
+      "id": "base44-entities",
+      "title": "Base44 entities and functions (declare, lint, adopt, query)",
+      "category": "CLI & Loop",
+      "file": "base44-entities.md"
+    },
     {
       "id": "headless-business-to-himi-app",
       "title": "From Wix Headless / Back Office → a native Himi app",

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.1430.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": "7f9838f10c2acf3e1a2aabd52dd46d599859dcea9918ccec616e277b"
+  "falconPackageHash": "796dbf6642a176106f5ab3335bbab9788c281db7f264524e0c7fb8e3"
 }