@wix/himalaya-cli 0.1135.0 → 0.1137.0

package/guides/base44-app-context.md

@@ -0,0 +1,222 @@
+# Base44 app context — `himi base44 analyze`
+
+`himi base44 analyze` turns a [Base44](https://base44.com) app into an **app book**: one folder
+holding a machine-readable `book.json`, an agent-readable `BOOK.md`, the app's project source and
+screenshots. It is the Base44 counterpart of `himi site analyze` (see `himi docs wix-business-context`),
+and it exists so the coding agent building a Himi app from a Base44 app reads the app's real
+entities, schemas, backend functions and routes instead of guessing them from the rendered site.
+
+It is **read-only**. Every call it makes is a GET, and it never writes to the Base44 app.
+
+## Quick start
+
+```bash
+# Visitor pass — no sign-in. What any browser sees at the published URL.
+himi base44 analyze --url https://<tenant>.base44.app --out .himi/base44-book
+
+# Owner pass — you are signed in as the app's owner or an editor.
+himi base44 login
+himi base44 whoami
+himi base44 analyze --app-id <24-hex app id> --url https://<tenant>.base44.app --out .himi/base44-book
+
+# Print the book itself on stdout (for a script or an agent)
+himi base44 analyze --url https://<tenant>.base44.app --json
+```
+
+Read `BOOK.md` first, then `book.json` for detail. The default folder is `.himi/base44-book/`.
+It sits inside `.himi/`, so `himi push` never archives it as app source.
+
+## The two passes
+
+| | Visitor pass | Owner pass |
+|---|---|---|
+| Needs | `--url` | `--app-id` **and** a Base44 session |
+| Identity | app id, name, description, favicon, theme colour, language from the published page | plus the app's name and description from its app record |
+| Routes | router paths found in a self-hosted bundle (a Base44-hosted app loads its pages at run time, so usually none) | path → page component → entities it reads, from the source router |
+| Look | screenshots + colours from the Playwright crawl (the same crawl `site analyze` uses) | same, when `--url` is also given |
+| Entities | — | every entity: JSON schema, field types, required fields, row- and field-level access rules, up to `--sample` redacted rows |
+| Functions | — | every backend function: name, entry file, `http` (it serves requests itself) or `invoke`, HTTP methods it branches on, scheduled automations |
+| Agents, connectors | — | agent names, descriptions and tools; connector **types, scopes and status only** |
+| Secrets | — | secret **names** only |
+| Auth | — | visibility (public / private / workspace) and enabled sign-in providers |
+| Source | — | the project files under `<out>/source/`, filtered (below) |
+
+**The owner pass is never inferred.** A URL-only run stays a visitor pass even when you are signed
+in and the published page names its app id. Only an explicit `--app-id` asks for the owner pass,
+and without a session that is refused with exit code 2 before anything is read.
+
+**Nothing is fatal.** When a chapter cannot be read, the run still writes the book and lists the
+chapter in `gaps[]` with the reason. Common reasons: a refused read (your role can view the app but
+not edit it), no browser for the crawl, or an app id the published page does not carry. This is how
+a viewer's run looks: the visitor pass plus whatever the role could read, with every refused chapter
+listed in `gaps[]`.
+
+## Signing in
+
+| 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 |
+| 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 |
+
+`BASE44_ACCESS_TOKEN` wins over a stored session. `himi base44 whoami` says which one is in effect
+(`source: "env" | "session"`), who it belongs to and when it expires. It never prints the token.
+`himi base44 logout` deletes the stored session. A stored session that has expired is refreshed
+once, automatically, with its refresh token. The environment token is used exactly as given.
+`BASE44_API_URL` points every call at another Base44 API host (the default is
+`https://app.base44.com`).
+
+The session is a user credential. It never goes into the repo or the book.
+
+## Options
+
+| Flag | Meaning |
+|---|---|
+| `--url <https://…>` | The published app. Runs the visitor pass. |
+| `--app-id <id>` | The app id (24 hex characters, as in `app.base44.com/apps/<id>`). Runs the owner pass. |
+| `--out <dir>` | Book folder. Default `.himi/base44-book`. It must be new, a previous app book (whose `source/` and `screenshots/` are replaced), or free of `book.json`, `BOOK.md`, `source/` and `screenshots/`. Anything else is refused rather than overwritten. |
+| `--sample <n>` | Sample rows per entity, 0–100. Default 5. `--sample 0` reads no rows. |
+| `--json` | Print the book on stdout instead of the summary. |
+| `--no-browser` | Skip the Playwright crawl (recorded as a `look` gap). |
+
+The MCP server (`himi mcp`) exposes the same collector as the tool `himi_base44_analyze`
+(`url`, `appId`, `out`, `sample`). It returns the book as `structuredContent`. Toward Base44 it is
+read-only, but it writes the book folder, so it is not annotated read-only to the host.
+
+## The book (`book.json`, schema v1)
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "kind": "base44-app-book",
+  "generatedAt": "2026-09-30T12:00:00.000Z",
+  "mode": "owner",                       // or "visitor"
+  "input": { "url": "https://fixit.base44.app/", "appId": "68c0…cdef", "sample": 5 },
+  "identity": { "appId": "68c0…cdef", "appIdSource": "input", "name": "FixIt Tracker",
+                "faviconUrl": "…/favicon.png", "colors": { "theme-color": "#4f46e5" }, "lang": "en" },
+  "routes": [
+    { "path": "/", "component": "Dashboard", "file": "src/pages/Dashboard.jsx",
+      "entities": ["Job"], "source": "project-files" }
+  ],
+  "entities": [
+    { "name": "Job", "fields": [{ "name": "status", "type": "string", "required": true,
+                                  "enum": ["open", "done"] }],
+      "required": ["title", "status"], "schema": { /* the JSON Schema, verbatim */ },
+      "rls": { "read": { "created_by": "{{user.email}}" }, "delete": false },
+      "sampleRows": [{ "title": "Fix phone", "created_by": "[redacted-email]" }],
+      "file": "base44/entities/Job.jsonc", "source": "project-files" }
+  ],
+  "functions": [
+    { "name": "sendReport", "sourcePath": "base44/functions/sendReport/entry.ts", "kind": "http",
+      "methods": ["POST"], "invoke": "base44.functions.invoke(\"sendReport\", payload)",
+      "automations": [{ "name": "weekly", "type": "scheduled", "schedule": "0 9 * * 1" }] }
+  ],
+  "agents": [{ "name": "job_helper", "tools": [{ "entity": "Job", "operations": ["read"] }] }],
+  "connectors": [{ "type": "gmail", "scopes": ["…/gmail.send"], "status": "active" }],
+  "secrets": { "names": ["STRIPE_KEY"] },
+  "auth": { "visibility": "private", "requiresLogin": true, "providers": ["email-password", "google"] },
+  "look": { "pages": [ /* the crawl's pages + screenshots */ ], "theme": { "colors": {}, "fonts": {} } },
+  "source": { "root": "source", "files": 42, "denied": [".env.local"],
+              "secretFlagged": [{ "path": "src/api/keys.js", "reason": "a GitHub token" }] },
+  "gaps": [{ "chapter": "look", "reason": "playwright_not_installed: …" }]
+}
+```
+
+Every fact carries a `source`: `published-spa` (any visitor could see it), `project-files` (the
+app's own project files) or `rest` (the owner-authenticated API). Treat an operation with no rule as
+**open**: the Base44 CLI's own local server allows an operation whose rule is missing, `null` or
+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()`,
+`.filter({…})`, `.get(id)`, and the writes (`create`, `update`, `delete`) that the entity's rules do
+not forbid outright.
+
+## What is deliberately never collected
+
+- **Secret values.** Only secret names are read. The secrets listing returns a map, and its values
+  are dropped the moment it arrives.
+- **Connector tokens and account details.** A connector is its type, scopes and status. The
+  connected account's email and any other key are dropped field by field, not filtered afterwards.
+- **Your session.** It stays in `~/.himi/base44/` or the environment and appears in no output.
+- **People's contact details in sample rows.** Emails and phone numbers are replaced with
+  `[redacted-email]` / `[redacted-phone]`. A column whose name says credential (`password`,
+  `token`, `api_key`, `secret`, `session`, …) loses its value outright, and every token-shaped
+  string (JWTs, Base44 workspace keys, GitHub/Slack/AWS/Stripe/Google keys, bearer headers, private
+  keys) becomes `[redacted-token]`.
+- **Credential files in the source.** The project files pass through the same deny-list and secret
+  scan `himi push` uses for its source archive, and the scan is widened by every token shape listed
+  above. Dotenv files, key material, `.git`, `node_modules` and build output are dropped (listed in
+  `source.denied`). A file whose *content* looks like a credential (a hardcoded `sk_live_…` in a
+  function, say) is named in `source.secretFlagged` with the reason, and its bytes are never
+  written.
+- **A copy of the app.** See below.
+
+As a last check, the writer scans the serialized book and `BOOK.md` again, and refuses to write
+either if anything token-shaped survived redaction.
+
+## What Base44 exposes
+
+This section records what the collector relies on. It was read from the source of the official
+Base44 CLI (`base44` on npm, v0.1.24, MIT), not guessed.
+
+**Project layout.** An app is a Vite + React SPA plus a `base44/` folder. `base44/config.jsonc`
+names the resource directories, each relative to `base44/`. Their defaults are `entities/`,
+`functions/`, `agents/`, `connectors/` and `auth/`, and each holds `.json` or `.jsonc` files:
+
+| Path | Holds |
+|---|---|
+| `base44/entities/<Name>.jsonc` | a JSON Schema object with `name`, `properties`, `required`, `rls` (`read`, `create`, `update`, `delete`, `write`). Each rule is `true`, `false` or a condition such as `{ "created_by": "{{user.email}}" }`. Fields may carry their own `rls`. |
+| `base44/functions/<name>/function.jsonc` | `name`, `entry` (relative to that folder), `automations` (scheduled or entity-triggered). A zero-config function is just `functions/<name>/entry.{js,ts}`. Functions run on Deno. |
+| `base44/agents/<name>.jsonc` | `name`, `description`, `instructions`, `tool_configs` (`entity_name` + `allowed_operations`, or `function_name`) |
+| `base44/connectors/<type>.jsonc` | `type` (`gmail`, `slack`, …) and `scopes` |
+| `base44/auth/*.jsonc` | `enableUsernamePassword`, `enableGoogleLogin`, `enableMicrosoftLogin`, `enableFacebookLogin`, `enableAppleLogin`, `enableSSOLogin`, … |
+
+Apps built in the Base44 editor before that layout keep entities at the project root
+(`entities/*.json`) and one file per function (`functions/<name>.js`). The collector reads both
+places. Pages are routed either by a React Router tree (`<Route path=… element={<Page/>}>`) or by
+Base44's page registry (`PAGES = { Name: Component }`, routed at `/<Name>`, with the `mainPage` at
+`/`).
+
+**API.** Everything is under `https://app.base44.com` (or `BASE44_API_URL`) and authenticated with
+`Authorization: Bearer <access token>`:
+
+| Request | Returns | Used for |
+|---|---|---|
+| `GET /api/apps/<id>` | `name`, `user_description`, `public_settings` (`public_without_login`, `private_with_login`, `workspace_with_login`), `auth_config` | identity, auth |
+| `GET /api/apps/<id>/eject` | the project as a tarball | source, entities, functions, agents, connectors, routes |
+| `GET /api/apps/<id>/backend-functions` | `{ functions: [{ name, entry, files, automations }] }` | functions the download lacks (their `files` are not copied) |
+| `GET /api/apps/<id>/agent-configs` | `{ items: [agent config], total }` | agents the download lacks |
+| `GET /api/apps/<id>/external-auth/list` | `{ integrations: [{ integration_type, status, scopes, user_email }] }` | connectors (`user_email` dropped) |
+| `GET /api/apps/<id>/secrets` | a name → value map | secret **names** |
+| `GET /api/apps/<id>/entities/<Name>?limit=<n>` | rows | sample rows |
+
+There is no read endpoint for entity schemas (the CLI only pushes them), so schemas come from the
+downloaded project alone. When the download is refused, the entities chapter is a gap.
+
+**Why the collector does not run `base44 eject`.** `eject` downloads the code with
+`GET /api/apps/<id>/eject`. It then creates a **new app** named "<name> Copy" (`POST /api/apps`),
+writes that new app's id into the download, and offers to deploy it. That is a write to your Base44
+account. The collector makes the same download request and stops there.
+
+**Sign-in.** Base44 uses the OAuth 2.0 device flow for its CLI. `POST /oauth/device/code` with
+`client_id: base44_cli` returns a user code and a verification URL. `POST /oauth/token`
+(`grant_type=urn:ietf:params:oauth:grant-type:device_code`) is polled until the user approves.
+`POST /oauth/token` with `grant_type=refresh_token` renews a session, and `GET /oauth/userinfo`
+names the user. The Base44 CLI keeps its own session in `~/.base44/auth/auth.json`. himi keeps its
+own, and reads the Base44 CLI's only on `--from-base44-cli`.
+
+**Published apps.** An app published on `<tenant>.base44.app` is served by Base44's platform shell.
+Its HTML carries the app's identity: `og:site_name`, description, favicon, `theme-color`, and the
+app id on the Base44 badge tag (`<script data-app-id="<id>" …>`). The app's own page code loads at
+run time, so the visitor pass usually finds **no routes** there and says so in `gaps[]`. The owner
+pass reads them from the source router instead. A self-hosted build of an ejected app is a plain
+Vite bundle: the app id is baked in (`VITE_BASE44_APP_ID`) and the router's `path` strings survive
+minification, so the visitor pass finds both. The visitor pass reads the HTML and up to four of its
+same-origin scripts, through the same SSRF- and DNS-rebinding-guarded fetch `himi site analyze`
+uses. A third-party script tag is never followed.
+
+## Not in scope
+
+- Generating the Himi app from the book. That is the agent's job.
+- Writing anything back to the Base44 app.

package/guides/designing-himi-screens.md

@@ -281,7 +281,7 @@ Concrete patterns lifted from real usage:
 - **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
 - **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
-- **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **Never put a bare `divider()` inside an HStack**: it is a horizontal rule on every surface, and on web and Android it claims the row's full width and squeezes its siblings (a stat row's `12` wraps to `1`/`2`); only iOS draws a thin vertical line. For a stats row, separate the columns with `spacer()`s or spacing instead. Use a **centered caption** instead: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
+- **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **Never put a bare `divider()` inside an HStack for a row that must render on Android**: iOS and web draw it as a thin vertical rule the height of the row, but Android still draws a horizontal rule that claims the row's full width and squeezes its siblings (a stat row's `12` wraps to `1`/`2`). For a stats row, separate the columns with `spacer()`s or spacing instead. Use a **centered caption** instead: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
 
 > **Intrinsic-fill controls grab the row.** `Button` and `TextField` have an intrinsic FILL, so the next four idioms are about NOT letting that surprise you (they were the papercuts every off-repo app hit):
 

package/guides/himi-mcp.md

@@ -77,6 +77,7 @@ runs a session with it.
 | `himi_login` | Open a browser window where the user signs in to Wix, so publishing works with no terminal. It returns the sign-in link at once; call it again to see whether the sign-in finished. |
 | `himi_push` | Publish a **draft**: private to the owner, viewable by preview link and in Himi Player, not live. |
 | `himi_share`, `himi_preview_links` | Share links for a published release. |
+| `himi_base44_analyze` | Read a Base44 app into an app book (read-only) and return it as structured content — `himi docs base44-app-context`. |
 
 Each tool acts on the agent's workspace folder unless it is given a `dir`.
 

package/guides/index.json

@@ -208,6 +208,12 @@
       "category": "Wix SDK",
       "file": "wix-business-context.md"
     },
+    {
+      "id": "base44-app-context",
+      "title": "Base44 app context (himi base44 analyze)",
+      "category": "CLI & Loop",
+      "file": "base44-app-context.md"
+    },
     {
       "id": "headless-business-to-himi-app",
       "title": "From Wix Headless / Back Office → a native Himi app",

package/guides/recipe-dynamic-list.md

@@ -43,7 +43,7 @@ State holds the **normalized rows** plus the display strings for every screen st
 Actions are `load` (kicked at boot) and `retry`; a `search` action filters in-worker.
 
 ```ts
-import { defineService } from "@himalaya/state";
+import { defineService } from "@wix/himalaya/state";
 
 interface Row {              // FLAT strings/booleans only — see "Normalize" below
   id: string; name: string; price: string; initial: string;

package/guides/recipe-form-submit.md

@@ -83,8 +83,8 @@ see [tier-5-add-a-screen.md](../tier-5-add-a-screen.md#cross-field-validation).
 ## 2. The worker: validate in `submit`, return the outcome as state
 
 ```ts
-import { defineService } from "@himalaya/state";
-import { createDraftPost, type WixDraftPostWrite } from "@himalaya/wix-blog";
+import { defineService } from "@wix/himalaya/state";
+import { createDraftPost, type WixDraftPostWrite } from "@wix/himalaya/wix-blog";
 
 interface FormState {
   title: string; body: string;              // prefill values (edit mode / echo after save)

package/guides/recipe-voice-journal.md

@@ -6,10 +6,10 @@ processing. A background build must declare `audio_record_background`; web and m
 foreground capture only.
 
 ```ts
-import { startSession, stopSession, listSegments } from "@himalaya/audio-record";
-import * as speech from "@himalaya/speech";
-import * as diarization from "@himalaya/speaker-diarization";
-import { upsert } from "@himalaya/local-db";
+import { startSession, stopSession, listSegments } from "@wix/himalaya/audio-record";
+import * as speech from "@wix/himalaya/speech";
+import * as diarization from "@wix/himalaya/speaker-diarization";
+import { upsert } from "@wix/himalaya/local-db";
 
 export async function beginVoiceJournal() {
   const session = await startSession({ mode: "foreground", chunkSeconds: 30 });

package/guides/tier-5-add-a-screen.md

@@ -129,7 +129,17 @@ one object either way.
 > the two in step. Until that divergence list is empty, defensive reducers
 > (`String(p?.value ?? p?.text ?? "")`) remain the safe way to read a payload.
 
-So a text-input reducer is `setDraft: (s, { value }) => ({ ...s, draft: value })`, bound with `onChange: { actionId: "tier5.notes.setDraft" }`.
+So a text-input reducer is `setDraft: (s, p) => ({ ...s, draft: String(p?.value ?? "") })`, bound with `onChange: { actionId: "tier5.notes.setDraft" }`.
+
+**The payload argument can be absent.** A host calls the reducer with one merged object when
+`params`/`args` carry anything, and with **no argument at all** when both are empty — so the
+second parameter is `undefined`, not `{}`. A device always injects `{ value }` for the controls in
+the table, but `himi test` does not always have a value to type: a field whose legal value it
+cannot read off the app (a `Slider`, `Stepper`, `Toggle`, `DatePicker`, or a text field with no
+seeded word to borrow) is dispatched **with no payload**, exactly as an argument-less button is.
+Destructuring in the signature — `(s, { value }) => …` — then throws `Cannot destructure property
+'value' of 'undefined'`, and the crawl reports it against your reducer. Read through `p?.` (or
+default the parameter, `(s, { value } = {}) => …`) and every reducer survives both callers.
 
 **Per-row actions carry `$item` fields.** In a bound list/grid, `$item.<field>` substitutes into an action's `params` per row — so a per-row delete is `action: { actionId: "tier5.notes.remove", params: { id: "$item.id" } }`, and the reducer reads `remove: (s, { id }) => …`. (`$item` also substitutes into any prop string, e.g. `text: "$item.title"`.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1135.0",
+  "version": "0.1137.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "708ea7531c66305a8eece0a6f7cffeefca465601cdfac12eb39a0f14"
+  "falconPackageHash": "db47ced7662fdcbd6e6edb639fb12fb7131e5dd21f79ca0ce73e4fe3"
 }