@botlr/cli 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @botlr/cli
 
+## 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,10 +17,17 @@ 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
 }
 ```
 
+`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
 `BOTLR_PAT` (personal access token with `write:sections`, for push).
 `BOTLR_BASE_URL`, `BOTLR_APP_ID`, `BOTLR_FRAMEWORK` and `BOTLR_SECTIONS_DIR`
@@ -29,7 +36,7 @@ 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]
@@ -39,16 +46,112 @@ botlr sections init           [--force] [--dry-run]
 - `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.
+
+## 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 in the field DSL (the same shape the
+dashboard stores): the props the code expects. The CLI never writes it to
+the server's definition except as the seed for `push --create`. On `push`
+and `sections status` it 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: edit it there, or update 'schema' in hero.botlr.json
+```
+
+The warning changes nothing; fix the schema in the dashboard, pull to
+refresh `<name>.props.ts`, and update the manifest's `schema` (or drop it)
+when the code catches up.
+
+## 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.