@wix/himalaya-cli 0.1430.0 → 0.1431.0

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,24 @@ 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`).
+
 ## 3. Plan the screens from the book
 
 Write `.himi/screen-plan.md` before editing code. For each entity in `book.entities`:

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

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1430.0",
+  "version": "0.1431.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": "cb6ae1657ee30165de2fe500a05d3f531ee3a61071976c6db531172e"
 }