@botlr/cli 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @botlr/cli
 
+## 0.3.0
+
+### Minor Changes
+
+- `botlr schema pull` and `botlr schema push`: the explicit way to resolve props schema drift in either direction. A code push still never changes the schema.
+
+  - `botlr schema pull <name...>` (or `--all` for every manifest in `sectionsDir`) fetches the section definition's props schema from the dashboard and writes it as `schema` into `<name>.botlr.json`, in the CLI's fixed key order and in whichever format the dashboard has (field DSL or FormBuilder). It says "unchanged" when the manifest already holds the same schema, and regenerates `<name>.props.ts` afterwards unless `--no-types` or `"types": false`.
+  - `botlr schema push <name> [--force] [--yes]` reads `schema` from the manifest (an error when it is missing), fetches the dashboard's current schema, prints both formats and a diff of the field keys (added, removed, kept; node names for FormBuilder schemas), asks for confirmation unless `--yes`, then replaces the dashboard's schema (needs `BOTLR_PAT`). When the two schemas are in different formats the server answers 409 and the CLI prints both formats and says to rerun with `--force`; a 422 (not an object of fields, or the definition is not project-scoped) prints the server's message. A successful push regenerates the props file.
+  - The drift warning of `push` and `sections status` now names both commands: `botlr schema pull <name>` to take the dashboard's schema, `botlr schema push <name>` to send the code's. A manifest `schema` in the FormBuilder format now takes part in the drift comparison too (by node names), since `schema pull` can write one.
+  - `@botlr/sdk`: `client.sections.getSchema(name)` (site token, `GET /api/sections/{name}/schema`) and `client.sections.putSchema(name, { schema, force })` (personal token, `PUT /api/sections/{name}/schema`), with the `SectionSchemaFormat`, `SectionSchemaGetResponse`, `SectionSchemaPutBody` and `SectionSchemaPutResponse` types, `schemaFormat(schema)`, `SectionDefinition.format`, `BotlrSchemaFormatConflictError` (the 409 with `currentFormat` and `newFormat`) and `botlrErrorMessage(error)` to read a server's `detail` message. `SectionManifest.schema` is typed as `SectionSchema` (either format).
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.5.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Prop types from the dashboard's schema, and a warning when the code and the dashboard disagree about the props.
+
+  - `pull` writes `<name>.props.ts` next to the manifest: `export interface <ExportName>Props { ... }` generated from the section definition's props schema as the dashboard stores it (`definition.schema` in the pull response), in both the field DSL and the older FormBuilder format. `required: true` makes a property non-optional; a `select` with plain or `{ value }` options becomes a union of literals; asset and reference types become `string | Record<string, unknown>`; types the CLI does not know become `unknown`. The file carries a "generated, do not edit" header and is left alone when its text is unchanged. `--no-types` on a pull, or `"types": false` in `botlr.config.json`, turns it off.
+  - `push` and `sections status` warn when the manifest has a `schema` object (the props the code expects, field DSL only) and its keys differ from the definition's schema on the server: props the code expects that the dashboard does not define, and props the dashboard defines that the code does not list. The warning only reports; the dashboard owns the schema. The manifest's `schema` is otherwise a seed for `push --create`.
+  - `sections init` fills `schema` from the zod object a component's `XDefinition.schema` points at when it can read it (field names, a best-effort type, `required` unless optional or defaulted); otherwise it leaves `schema` out.
+  - `@botlr/sdk`: `SectionManifest.schema`, the `SectionSchemaField`, `SectionFieldSchema`, `SectionFormBuilderNode`, `SectionFormBuilderSchema` and `SectionSchema` types, and the `isFieldSchema` / `isFormBuilderSchema` guards. `SectionDefinition.schema` is typed as `SectionSchema | Record<string, unknown>`.
+
+- Pull writes manifests in a fixed key order and keeps the section registry up to date.
+
+  - `<name>.botlr.json` is always written as 2-space JSON with `section`, `framework`, `entry`, `exportName`, `files`, `title`, `description`, `category`, `icon`, `dependencies`, then unknown keys alphabetically (`dependencies` lists `npm` before `internal`, nested objects sorted). The server stores manifests as jsonb, which forgets key order, so a pull right after a push no longer shows up as a change in git. A pull also leaves the manifest file alone when it already holds the same data.
+  - After a pull, when `publisher-section-registry.ts` (or the file named by the new `registryFile` config key, relative to `sectionsDir`) exists, the CLI adds `import { <exportName> } from "./<entry>";` after the last import and `"<name>": <exportName>,` as the last registry entry, keeping existing entries and formatting. Already-registered sections leave the file untouched; `--no-registry` skips the step; a missing registry prints a one-line notice.
+  - `sections init` reads the registry from `registryFile` too.
+  - The lock stays one entry per section name per app (documented; `--dir` shares it). `pulledAt` is now kept when the same scope, version and hash land again, so re-pulling does not rewrite the lock.
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.4.0
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -17,38 +17,184 @@ pnpm add -D @botlr/cli
   "baseUrl": "https://api.botlr.io",
   "appId": "00000000-0000-0000-0000-000000000000",
   "framework": "react-next",
-  "sectionsDir": "components/sections"
+  "sectionsDir": "components/sections",
+  "registryFile": "publisher-section-registry.ts",
+  "types": true
 }
 ```
 
-Environment: `BOTLR_API_KEY` (site token, for pull/list/status) and
-`BOTLR_PAT` (personal access token with `write:sections`, for push).
+`registryFile` is optional and relative to `sectionsDir`; it names the
+component registry `pull` keeps up to date and `sections init` reads.
+`types` (default true) makes `pull` write `<name>.props.ts` from the
+definition's props schema; `false` turns it off for the app.
+
+Environment: `BOTLR_API_KEY` (site token, for pull/list/status and `schema
+pull`) and `BOTLR_PAT` (personal access token with `write:sections`, for
+`push` and `schema push`).
 `BOTLR_BASE_URL`, `BOTLR_APP_ID`, `BOTLR_FRAMEWORK` and `BOTLR_SECTIONS_DIR`
 override the file; `--framework` and `--dir` override both.
 
 ## Commands
 
 ```
-botlr pull <name...> | --all  [--framework react-next] [--dir components/sections] [--version N] [--shared] [--force]
+botlr pull <name...> | --all  [--framework react-next] [--dir components/sections] [--version N] [--shared] [--force] [--no-registry] [--no-types]
 botlr push <name>             [-m msg] [--shared] [--create] [--force]
 botlr sections list
 botlr sections status [name...] [--offline]
 botlr sections init           [--force] [--dry-run]
+botlr schema pull <name...> | --all  [--no-types]
+botlr schema push <name>      [--force] [-y, --yes] [--no-types]
 ```
 
 - `pull` writes every file of the section under `sectionsDir`, plus
   `<name>.botlr.json` (the manifest, never holding version or hash) and the
   lock entry in `.botlr/sections.lock.json`. A section whose local files
-  changed since the last pull is skipped unless `--force`.
+  changed since the last pull is skipped unless `--force`. When the registry
+  file exists, `pull` also adds `import { <exportName> } from "./<entry>";`
+  and `"<name>": <exportName>,` to it, keeping what is there; a section that
+  is already registered leaves the file untouched, and `--no-registry` skips
+  this step. Without a registry file the pull prints a one-line notice.
+  A pull also writes `<name>.props.ts` from the definition's props schema
+  (see "Prop types" below) unless `--no-types` or `"types": false`.
 - `push` reads the manifest and its files, hashes them, and pushes with
   `baseVersion` from the lock so a stale checkout gets a conflict instead of
   overwriting someone's version. `--force` omits `baseVersion`. `--create`
-  adds the section definition when the dashboard does not know it yet.
+  adds the section definition when the dashboard does not know it yet,
+  seeded with the manifest's `schema` when it has one. After the push the
+  CLI warns when the manifest's `schema` and the definition's schema list
+  different props (see "Schema drift" below).
 - `sections status` compares the local content hash with the lock and the
   server's latest: `clean`, `modified`, `behind`, `diverged`, or
-  `untracked` for a manifest with no lock entry.
+  `untracked` for a manifest with no lock entry. For manifests that carry a
+  `schema`, it also fetches the definition and prints the drift warning
+  (not with `--offline`).
 - `sections init` derives first manifests from a satellite app's
   `publisher-section-registry.ts` and the `XDefinition` exports next to each
-  component. Review them, then `botlr push <name> --create` per section.
+  component. When the definition's `schema` points at a `z.object({...})`
+  in the same file, the manifest gets a `schema` with the field names and a
+  best-effort type (`z.string()` → `text`, `z.number()` → `number`,
+  `z.boolean()` → `boolean`, `z.enum([...])` → `select` with options,
+  `z.array(...)` → `array`, `z.object`/`z.record` → `json`,
+  `z.union([z.string(), z.any()])` → `asset`; `required` unless
+  `.optional()`, `.nullable()` or `.default(...)`). Fields it cannot read are
+  left out, and so is `schema` when nothing could be read. Review them, then
+  `botlr push <name> --create` per section.
+- `schema pull` copies the dashboard's props schema into the manifest's
+  `schema`; `schema push` sends the manifest's `schema` to the dashboard.
+  These are the only commands that change a definition's schema; see
+  "Schema drift" below.
+
+## Prop types
+
+The dashboard owns a section definition's props schema. `pull` turns it
+into TypeScript so a component does not have to repeat it in zod:
+
+```ts
+// components/sections/hero.props.ts (generated, do not edit)
+export interface HeroProps {
+  /** Heading */
+  heading: string;
+  subheading?: string;
+  alignment?: "left" | "center" | "right";
+  image?: string | Record<string, unknown>;
+}
+```
+
+The interface is named after the manifest's `exportName` (else a
+PascalCase of the slug) plus `Props`. Field types map as follows: text,
+textarea, markdown, richtext, string, email, tel, url, icon, color, date,
+datetime → `string`; number, integer, currency → `number`; boolean →
+`boolean`; select → a union of the option values (`options` as plain values
+or `{ value }` objects), else `string`, and an array of that with
+`multiple`; multiselect, tags → `string[]`; array, list, repeater →
+`unknown[]`; json, jsonb, object → `Record<string, unknown>`; asset,
+asset-picker-*, media, document, page, reference, relation,
+entity_reference, app_instance, forum_thread → `string | Record<string,
+unknown>`; anything else → `unknown`. `required: true` makes the property
+non-optional. The older FormBuilder format (`{ nodes: [...] }`) is walked
+the same way, with groups flattened and repeater items typed from their
+`fields`. A definition without fields yields `Record<string, unknown>`. The
+file is rewritten only when its text changes. Import the type in the
+component:
+
+```ts
+import type { HeroProps } from "./hero.props";
+export function Hero(props: HeroProps) { ... }
+```
+
+## Schema drift
+
+A manifest may carry a `schema` object (normally the field DSL, the same
+shape the dashboard stores): the props the code expects. A code `push`
+never writes it to the server's definition except as the seed for
+`push --create`. On `push` and `sections status` the CLI compares that
+object's keys with the definition's schema and warns:
+
+```
+warning: props schema of 'hero' differs between the code and the dashboard
+  the code expects props the dashboard does not define: ctaLink
+  the dashboard defines props the code does not list: image
+  the dashboard owns the schema; a code push never changes it. To resolve:
+    botlr schema pull hero   takes the dashboard's schema into hero.botlr.json
+    botlr schema push hero   sends the code's schema to the dashboard
+```
+
+The warning changes nothing. Resolve it in one of two directions:
+
+```bash
+botlr schema pull hero          # the dashboard is right: copy its schema into hero.botlr.json
+botlr schema push hero          # the code is right: replace the dashboard's schema with the manifest's
+```
+
+`schema pull <name...>` (or `--all` for every manifest in `sectionsDir`)
+fetches the definition's props schema and writes it as `schema` into
+`<name>.botlr.json`, in the fixed key order and in whichever format the
+dashboard has. It prints `schema unchanged` when the manifest already says
+the same, and regenerates `<name>.props.ts` afterwards unless `--no-types`
+(or `"types": false`). A section the app has no definition for is skipped
+with a notice.
+
+`schema push <name>` reads `schema` from the manifest (an error when it is
+missing), fetches the dashboard's current schema and prints the formats and
+a diff of the field keys, then asks before sending (`--yes` skips the
+question, and is required when there is no terminal):
+
+```
+schema of 'hero': dashboard has field-dsl (2 fields), code has field-dsl (3 fields)
+  + added    ctaLink, subheading
+  - removed  image
+  = kept     heading
+replace the dashboard's schema of 'hero' with the code's? [y/N]
+```
+
+For a FormBuilder schema (`{ nodes: [...] }`) the keys are the node names.
+When the dashboard's schema and the manifest's are in different formats the
+server refuses with 409; the CLI prints both formats and says to rerun with
+`--force`, which replaces the schema whatever its format. A 422 (the
+`schema` is not an object of field definitions, or the definition is not
+project-scoped and the template has to be installed into the project first)
+prints the server's message. After a successful push the CLI regenerates
+`<name>.props.ts` from the stored schema. `schema push` needs `BOTLR_PAT`,
+like `push`.
+
+## Manifest format
+
+The CLI always writes `<name>.botlr.json` the same way: 2-space JSON with
+the keys `section`, `framework`, `entry`, `exportName`, `files`, `title`,
+`description`, `category`, `icon`, `dependencies`, `schema` in that order,
+then any other keys alphabetically; inside `dependencies`, `npm` before `internal`,
+with package names sorted. The server stores manifests as jsonb and does not
+keep key order, so this normalization is what makes a pull right after a
+push produce no diff. A pull leaves a manifest file alone when the local
+file already says the same thing, whatever its formatting.
+
+## The lock file
+
+`.botlr/sections.lock.json` has one entry per section name for the whole
+app, next to `botlr.config.json`. It is not keyed by directory: `--dir`
+points a command at another sections directory but records into the same
+lock, so a section name means one thing per app. `pulledAt` is when the
+recorded version first landed locally; pulling the same version again keeps
+it, so a no-op pull does not touch the lock file either.
 
 Commit the manifests and the lock file; keep `BOTLR_PAT` out of the repo.