@wix/himalaya-cli 0.1433.0 → 0.1434.0

package/guides/base44-app-context.md

@@ -55,7 +55,7 @@ listed in `gaps[]`.
 
 | Mode | How | Stored where |
 |---|---|---|
-| Interactive | `himi base44 login` runs Base44's device sign-in. You approve a code in the browser, and only read access (`apps:read`) is asked for | `~/.himi/base44/session.json`, mode 0600 |
+| Interactive | `himi base44 login` runs Base44's device sign-in. You approve a code in the browser, and only read access (`apps:read`) is asked for. `--write` also asks for `apps:write`, which only the provisioning verbs need ([base44-entities](base44-entities.md#provisioning-create-seed-deploy)) | `~/.himi/base44/session.json`, mode 0600 |
 | Reuse the Base44 CLI's session | `himi base44 login --from-base44-cli` imports what `npx base44 login` stored | the same file |
 | CI | `BASE44_ACCESS_TOKEN=<token>` in the environment | nowhere, it is read from the environment |
 

package/guides/base44-entities.md

@@ -1,4 +1,4 @@
-# Base44 entities and functions (declare, lint, adopt, query)
+# Base44 entities and functions (declare, lint, adopt, query, provision)
 
 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
@@ -8,8 +8,9 @@ This is the Base44 sibling of [`cms-collections`](cms-collections.md) (`himi doc
 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)).
+> **Writes are separate and deliberate.** `adopt`, `query` and the lint never write to a Base44
+> app. Creating schemas, seeding rows and deploying functions are their own verbs. Each one prints
+> a plan and writes only with `--yes` (see [Provisioning](#provisioning-create-seed-deploy)).
 
 ## The block
 
@@ -35,7 +36,7 @@ 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) |
+| **Owned** | `name: "Note"` (alphanumeric) | `Himi<AppPascal>Note`. For app `todo` that is `HimiTodoNote`, and for `video-courses` it is `HimiVideoCoursesNote` | create, seed |
 | **Adopted** | `base44Name: "Customer"` | `Customer`, verbatim | read only |
 
 Base44 entity names are alphanumeric only, so the CMS `himi_<app>_` prefix cannot be used. The
@@ -140,10 +141,119 @@ makes is a `GET`.
 
 Failure codes are listed in [`himi-json-output`](himi-json-output.md#himi-base44-entities-codes).
 
+## Provisioning: create, seed, deploy
+
+```bash
+himi base44 login --write                     # once: a session with apps:read apps:write
+himi base44 entities create --app todo        # the plan: create / update / unchanged / refused per entity
+himi base44 entities create --app todo --yes  # send it
+himi base44 entities seed --app todo --yes    # fill EMPTY owned entities
+himi base44 functions deploy --app todo --yes # ship owned functions
+```
+
+`--app <slug>` resolves to `apps/<slug>/`, and `--content <dir>` points anywhere. Without `--yes`
+each verb makes only reads and sends no write.
+
+**Base44's schema write is a destructive full-set sync.** `PUT /api/apps/<id>/entity-schemas`
+with `{ entityNameToSchema }` **deletes every entity the body leaves out**, along with its rows.
+Base44 has no read for schemas. So `entities create` downloads the live project (the same eject
+read as `query`) and builds the body from every entity in it:
+
+- Owned entities are built from `config.ts`.
+- Every other entity is passed through as the exact schema object the download holds. It is never
+  rebuilt, renamed, changed or dropped.
+
+A **live** entity counts as owned only if `base44-provisioned.json`, beside `config.ts`, records
+that this app provisioned it. `entities create` keeps that file up to date. **Commit it** like a
+lockfile, so every machine and CI agrees on what the app owns. A bare prefix is not enough on its
+own. If app `todo` (`HimiTodo…`) declares `ListNote`, that names the entity app `todo-list` owns
+as `Note` (`HimiTodoListNote`). So:
+
+- A declared entity that already exists but is not in the file is refused with
+  `owned_entity_unclaimed`. If it really is this app's, record it in the file; otherwise rename the
+  declaration.
+- An undeclared entity in the namespace that the file does not list is left untouched and listed
+  in `warnings`.
+- When a sync's outcome is uncertain (a lost reply, a 5xx, a reply with no `deleted[]`),
+  `entities create` re-reads the app and records only the creates that are live, and keeps every
+  name the file already held. If that re-read fails too, nothing new is recorded, and the next run
+  refuses the entity with `owned_entity_unclaimed`, which you fix by recording it by hand.
+- `entities seed` only writes entities the file lists.
+
+If any entity file in the download fails to parse, or the source walk drops it (a symlink, a
+denied name), the snapshot counts as unreadable. A sync without that file would delete the
+entity.
+
+```mermaid
+flowchart TD
+  A[entities create] --> Y{--yes?}
+  Y -- yes --> S{token has apps:write?}
+  S -- no --> R1[write_scope_missing<br/>no request]
+  S -- yes --> C
+  Y -- no --> C["GET …/eject → every live entity, verbatim"]
+  C -- failed --> R2[schema_snapshot_unavailable]
+  C -- no entities, no --empty-app-ok --> R3[schema_snapshot_empty]
+  C --> P["plan: foreign as-is + owned from config"]
+  P -- a foreign entity missing or altered --> R4[would_delete_foreign_entity]
+  P -- owned entity / field dropped, no --allow-destructive --> R5[owned_*_removal_needs_flag]
+  P -- no --yes --> D[print the plan, exit 0]
+  P -- --yes --> H[re-read the eject, re-plan]
+  H -- plan differs --> R6[snapshot_changed]
+  H -- same --> I["one PUT …/entity-schemas"]
+  I -- deleted[] names an entity the plan kept --> R7[foreign_entity_deleted]
+  I --> K[created / updated / unchanged]
+```
+
+Every refusal except the last one happens before the `PUT`.
+
+- `--allow-destructive` lets an **owned** entity or field be removed. It only reaches entities this
+  app provisioned, never another app's.
+- `--apply-permissions` writes a changed owned `rls` (entity- or field-level). Without it the live
+  rules are kept and the difference is reported as `permissions` drift. A rule the declaration
+  does not state never clears a live one.
+- `--empty-app-ok` accepts a download with no entities. An empty app cannot be told apart from a
+  failed read, so this has to be opted into.
+
+Because this is a full-set sync, an entity added in the Base44 builder between the plan and the
+`PUT` is caught by the re-read (`snapshot_changed`). Whether the eject download always reflects
+builder edits that were never exported is not yet proven against a live app. Before the first
+live `--yes`, check it on a throwaway app: add an entity in the builder and confirm `entities
+create` lists it.
+
+**`entities seed`** checks each owned entity with `GET …/entities/<E>?limit=1`:
+
+- An empty entity gets one `POST …/entities/<E>/bulk` with its rows.
+- An entity that already has rows is skipped with `skipped: "not-empty"`.
+- An adopted entity is never read or written.
+
+Rows from `base44-seed.json` take precedence over `config.ts` `seed`. Only declared keys are sent,
+so a row cannot set `id` or `created_by`. `--ai` writes placeholder rows to `base44-seed.json`
+offline and returns an `agentPrompt` for the agent to rewrite them, exactly like `himi cms seed
+--ai`.
+
+**`functions deploy`** reads each owned function from `base44/functions/<name>/`. The entry file is
+`entry.ts` or `entry.js`, or the one `function.jsonc`'s `entry` names. The folder is read with
+`himi push`'s own walk: symlinks are never followed, the deny-list applies, and the secret scan
+runs. Anything those flag refuses the deploy with `function_source_unsafe`. Each function is sent
+with
+one `PUT …/backend-functions/<name>` and body `{ entry, files, automations? }`. It never uses the
+bulk `PUT …/backend-functions`, which deletes the functions it omits, and never sends `DELETE`.
+
+Owned functions keep their plain `name`, so every deploy adds a `.himi-owned` marker file naming
+the app. A deployed function with a declared name that lacks this app's marker is refused with
+`function_name_taken` and nothing is deployed. That covers a function built in the builder,
+another himi app's function, or a listing that returns no files. A listing with no `functions`
+array is refused outright and is never read as "nothing deployed".
+
+**Scope.** The default `himi base44 login` stays `apps:read`, so the analyzer and `query` keep
+least privilege. `--yes` on any of these verbs needs a token whose `scope` claim includes
+`apps:write`. A token whose claims cannot be read (an opaque `BASE44_ACCESS_TOKEN`) is refused
+rather than guessed.
+
+Failure codes are listed in
+[`himi-json-output`](himi-json-output.md#himi-base44-entities--functions-provisioning-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.

package/guides/himi-json-output.md

@@ -6,7 +6,7 @@ repurposed when human wording changes. New codes may be added; consumers must
 handle an unknown code as a failure, without parsing prose.
 
 **Rollout:** this contract is enforced for **`himi push`**, including `--only`,
-first, for **`himi store iap connect`**, and for **`himi site member-app`**. Other subcommands still have legacy failures without codes and are a
+first, for **`himi store iap connect`**, for **`himi site member-app`**, and for the **`himi base44`** entity and function verbs. Other subcommands still have legacy failures without codes and are a
 follow-up migration. This is an additive change: existing `error`, `errors`,
 `message`, `hint`, status, body, and gate-specific fields stay as they were.
 Some legacy envelopes have no singular `error` or `hint`; consumers must not
@@ -234,7 +234,7 @@ Covers `himi base44 adopt` and `himi base44 entities query` (#4557,
   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).
+  `query`, `create` or `seed` (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"`.
@@ -249,6 +249,70 @@ 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 entities | functions` provisioning codes
+
+Covers `himi base44 entities create`, `himi base44 entities seed` and `himi base44 functions
+deploy` (#4558, [base44-entities](base44-entities.md#provisioning-create-seed-deploy)). Failures
+print `ok: false` and `code` on stderr. Every code below that refuses a write does so **before**
+the write request is sent.
+
+- `invalid_usage`: an unknown `functions` subcommand, a bare `--only`, `--only` on `entities
+  create` (always a full-set sync), an `--app` with no `apps/<slug>/config.ts`, or nothing to
+  deploy (no owned function, or `--only` matched none) (exit 2).
+- `unknown_subcommand`: `himi base44 entities` was given no subcommand, or one other than `query`,
+  `create` or `seed` (exit 2).
+- `config_unloadable`: `config.ts` could not be loaded (exit 1).
+- `invalid_config`: the `base44` block has lint errors; `issues[]` carries each `ruleCode` (exit 1).
+- `no_app_id`: the config has no `base44` block, or no `base44.appId` (exit 1).
+- `not_signed_in`: there is no session and no `BASE44_ACCESS_TOKEN`. Run `himi base44 login
+  --write` (exit 2).
+- `write_scope_missing`: `--yes` was given, but the token's `scope` claim lacks `apps:write` or
+  cannot be read. Nothing is sent, not even a read. Run `himi base44 login --write` (exit 2).
+- `schema_snapshot_unavailable`: the project download (`GET …/eject`) failed, or one of its entity
+  files does not parse or was dropped by the source walk. The current entity set is unknown, and
+  a sync without that file would delete the entity (exit 1).
+- `schema_snapshot_empty`: the download has no entity schemas. That cannot be told apart from a
+  failed read, so the run refuses unless `--empty-app-ok` is passed (exit 1).
+- `would_delete_foreign_entity`: the sync body would omit or alter an entity himi does not own.
+  The guard, which should never trip (exit 1).
+- `owned_entity_removal_needs_flag`: an entity this app provisioned (recorded in
+  `base44-provisioned.json`) is no longer declared. Dropping it deletes its rows; pass
+  `--allow-destructive`. An entity in the namespace that this app never provisioned is left
+  untouched and only warned about (exit 1).
+- `owned_field_removal_needs_flag`: an owned entity lost a declared field. Pass
+  `--allow-destructive` (exit 1).
+- `owned_entity_unclaimed`: a declared owned entity already exists on the app, but
+  `base44-provisioned.json` does not record this app provisioning it, so it may belong to another
+  himi app whose slug shares the prefix. If it is this app's, record it in that file; otherwise
+  rename the declaration (exit 1).
+- `snapshot_changed`: the entities changed between the plan and the re-read just before the
+  `PUT`. Nothing was sent; re-run (exit 1).
+- `ledger_unreadable`: `base44-provisioned.json` exists but is not a JSON object (a merge
+  conflict, say). himi will not rewrite it from scratch, because that would drop other app ids'
+  records, so fix the file. The same code means the sync was sent but the file could not be
+  written afterwards; `error` names the entities to record by hand (exit 1).
+- `foreign_entity_deleted`: after the `PUT`, Base44's `deleted[]` named an entity the plan did not
+  drop on purpose; `foreignDeleted` lists them. Defence in depth: the guard should make this
+  unreachable (exit 1).
+- `nothing_to_seed`: `seed` found no owned entity (adopted ones are never seeded), or `--ai`
+  had none to write (exit 1).
+- `seed_incomplete`: one or more owned entities were not seeded because they are missing from
+  the app, unrecorded in `base44-provisioned.json` (`skipped: "unclaimed"`), or their rows could
+  not be read; `skipped[]` names each one. Not-empty entities are
+  skipped (`skipped: "not-empty"`) without failing (exit 1).
+- `seed_file_invalid`: `base44-seed.json` is not a JSON object keyed by entity name, one of
+  its entries is not an array of row objects, or a row has no declared field left once undeclared
+  keys are dropped (a blank record would make the entity non-empty for good) (exit 1).
+- `function_name_taken`: a declared function name is already deployed and does not carry this
+  app's `.himi-owned` marker. Nothing was deployed (exit 1).
+- `function_source_missing`: an owned function has no `base44/functions/<name>/` folder or no
+  entry file (exit 1).
+- `function_source_unsafe`: the function folder contains a symlink or a denied path, the secret
+  scan flags a file, or the folder is over the file or byte cap. Nothing is uploaded (exit 1).
+- `request_failed`: any other refused request, or a reply himi cannot read. That includes a sync
+  response with no `deleted[]` and a function listing with no `functions` array. `status` and
+  `serverError` are included when the server answered (exit 1).
+
 ## `himi base44 screens` codes
 
 `himi base44 screens` (#4560, [base44-app-to-himi-app](base44-app-to-himi-app.md)) generates one

package/package.json

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