@wix/himalaya-cli 0.1433.0 → 0.1435.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/guides/himi-mcp.md

@@ -52,6 +52,7 @@ business from an idea to a preview and has the tools to do it. In a Claude Code
 ```text
 /plugin marketplace add https://apps.wix.com/_api/himi-serve/.claude-plugin/marketplace.json
 /plugin install himi@wix-himi
+/plugin install himi-studio@wix-himi   # optional: the Himi Studio pane (below)
 ```
 
 The marketplace hands the plugin out as a zip archive, which needs Claude Code 2.1.224 or later;
@@ -129,6 +130,30 @@ worker-backed flow, open the same URL in your regular browser.
 When `himi studio` has written the build board, the preview also serves it at `/__himi/studio/` on
 the same origin, and `himi_preview_start` returns that URL as `board`.
 
+### Himi Studio: the app beside the chat in Claude Code
+
+`himi-studio` is the marketplace's second, optional plugin, a Claude Code *mod*. It adds a pane
+beside the conversation with four views:
+
+- **Now:** the screen being worked on, in a phone frame, with the live build's state and what the
+  last rebuild changed.
+- **Screens:** every rendered screen.
+- **Checks:** the journey step, and validate, test, the UX audit and the last push.
+- **Activity:** the progress postcards.
+
+When the last rebuild failed, a band above the prompt says so and offers **Fix it**. The agent gets
+two tools: `studio_focus` shows you the screen it just changed, and `studio_snapshot` reads the
+status.
+
+```
+/plugin install himi-studio@wix-himi
+```
+
+The pane shows screenshots, not the live app: a mod cannot host a web page. For the interactive
+app, use its **Open live preview** button or the `himi-preview` launch configuration. The pane reads
+only what the CLI already writes under `.himi/` (the board's `state.json` and its screenshots). It
+opens by itself in an app folder; elsewhere, run `/himi <app folder>`.
+
 To see the app **on your phone**, `himi_push` publishes a draft and returns a link that opens it in
 Himi Player.
 

package/guides/skill.md

@@ -74,6 +74,7 @@ A build takes most of an hour. An owner who sees nothing for that long assumes n
 - **Give them a board to leave open.** When the installed CLI lists `studio`, run `himi studio` once, right after that first picture, and tell the owner it is there (a current `himi init` has already made the board; this opens it). It opens a local page in their browser that fills itself in — every screen as it renders, the journey step and your latest postcard, each check as it runs — so they can watch between your messages. It is a view of your local work, not the preview of step 7.
 - **Let them click around while you work — the live preview runs from init on.** A current `himi init` started it (`watch.url` in its output); if it isn't running (`--remote`, CI), start it once step 4's startup preflight says the app may boot locally, when the installed CLI's `himi run` accepts `--watch`: run `himi run --watch --content <dir> &` at once and leave it running until the handover; do not wait for a `reminder` to ask. Give the owner its url, and open it only after the preflight. `himi run --watch` serves the app on this machine, opens it in their browser when you start it yourself (no `--browser` flag — that is a different mode, and `--watch` refuses it; the one init starts opens nothing), and repaints that tab every time you save — and the board frames the same live app. Once the app is bound to their site, the watch preview shows that site's live data, fetched by their own browser as an anonymous visitor. It is a local preview of your working copy, never the owner-private preview, and a save that does not build leaves the last good version on screen while you fix it.
 - **Inside a coding agent, prefer the `himi_*` tools.** When your tool list has them (`himi init` configures the `himi` MCP server for Claude Code, Cursor, Codex and VS Code), call them instead of shelling out: `himi_render` hands you the PNG to show, and `himi_preview_start` returns the live preview's URL. Open that URL in your own built-in browser — Claude Code desktop: start the `himi-preview` launch configuration; Cursor: its Browser tool; Codex in the ChatGPT desktop app: its Browser; VS Code: the integrated browser — so the owner watches the app take shape beside the chat.
+- **When the Himi Studio pane is open, show the work there.** In Claude Code, a tool list with `mcp__himi-studio__studio_focus` means the owner has the Himi Studio pane beside the chat. It shows each screen as it renders, the live build and every check, and it keeps itself current. Right after you change or render a screen, call `studio_focus` with its screen id rather than pasting the picture into the chat. For the build status, read `studio_snapshot` rather than re-running status commands. Postcards still go in the chat and the journal. Without the pane, in Claude Code you may offer it once: `/plugin install himi-studio@wix-himi`.
 - **Hand over the story too.** At the handover in step 7, when `himi --help` lists `himi studio reel` (an older CLI can have `studio` without it), run `himi studio reel` and offer the owner the file it writes (a current CLI rebuilds it for you: your `--step review` postcard names it as `makingOf`, and every `himi push --draft` as `reel` — `.himi/making-of.html`, so name that file): one self-contained page of their app taking shape, version by version, with your postcards. It shows how the app was built; it is never a substitute for the preview URL, and it carries the same sample-data captions the postcards did.
 
 ## Approval gates

package/package.json

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