@botlr/cli 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -1,14 +1,19 @@
-import { SectionSourceScope, SectionManifest, SectionSourceFileInput, SectionSourceScopeSummary, SectionSourceSummary, BotlrClient } from '@botlr/sdk';
+import { SectionSourceScope, SectionManifest, SectionSourceFileInput, SectionSourceScopeSummary, SectionSourceSummary, SectionFieldSchema, SectionSchemaField, SectionFormBuilderNode, SectionSchema, SectionSchemaFormat, BotlrClient } from '@botlr/sdk';
 
 declare const CONFIG_FILE = "botlr.config.json";
 declare const DEFAULT_FRAMEWORK = "react-next";
 declare const DEFAULT_SECTIONS_DIR = "components/sections";
+declare const DEFAULT_REGISTRY_FILE = "publisher-section-registry.ts";
 /** `botlr.config.json` */
 interface BotlrCliConfigFile {
     baseUrl?: string;
     appId?: string;
     framework?: string;
     sectionsDir?: string;
+    /** Registry file `pull` keeps up to date, relative to `sectionsDir`. Default `publisher-section-registry.ts`. */
+    registryFile?: string;
+    /** Write `<name>.props.ts` after a pull. Default true; `false` turns it off (`--no-types` does per call). */
+    types?: boolean;
 }
 interface ResolvedConfig {
     /** Directory holding `botlr.config.json` (or the cwd when there is none). Paths resolve against it. */
@@ -19,6 +24,10 @@ interface ResolvedConfig {
     framework: string;
     /** Absolute path of the sections directory. */
     sectionsDir: string;
+    /** Absolute path of the registry file (`sectionsDir/publisher-section-registry.ts` by default); it may not exist. */
+    registryFile: string;
+    /** Whether `pull` writes `<name>.props.ts` from the definition's schema. */
+    types: boolean;
     /** Site token, `BOTLR_API_KEY`. */
     apiKey: string | undefined;
     /** Personal access token, `BOTLR_PAT`. */
@@ -52,11 +61,25 @@ interface LockEntry {
     framework: string;
     version: number;
     contentHash: string;
-    /** ISO timestamp of the pull or push that wrote the entry. */
+    /**
+     * ISO timestamp of the pull or push that first put this version here. A
+     * pull that lands the same scope, version and hash again keeps it, so
+     * re-pulling does not touch the lock file.
+     */
     pulledAt: string;
 }
-/** `.botlr/sections.lock.json`: one entry per section name. */
+/**
+ * `.botlr/sections.lock.json`: one entry per section name, for the whole
+ * app. The lock is not keyed by directory: `--dir` points a command at
+ * another sections directory but still records into this one lock, so a
+ * section name means one thing per app whichever directory holds it.
+ */
 type SectionsLock = Record<string, LockEntry>;
+/**
+ * The entry to record after a pull or push: `fresh` with the previous
+ * `pulledAt` kept when scope, framework, version and hash are unchanged.
+ */
+declare function nextLockEntry(previous: LockEntry | undefined, fresh: LockEntry): LockEntry;
 declare function lockPath(root: string): string;
 declare function readLock(root: string): Promise<SectionsLock>;
 declare function writeLock(root: string, lock: SectionsLock): Promise<void>;
@@ -71,8 +94,32 @@ declare function manifestPath(sectionsDir: string, name: string): string;
 declare function listManifests(sectionsDir: string): Promise<string[]>;
 declare function readManifest(sectionsDir: string, name: string): Promise<SectionManifest>;
 declare function validateManifest(value: unknown, where?: string): SectionManifest;
-/** Write `<name>.botlr.json` without any pull state. */
+/** Top-level manifest keys in the order the CLI writes them; anything else follows alphabetically. */
+declare const MANIFEST_KEY_ORDER: readonly ["section", "framework", "entry", "exportName", "files", "title", "description", "category", "icon", "dependencies", "schema"];
+/**
+ * The manifest with pull state removed and keys in a fixed order: the known
+ * keys first (`MANIFEST_KEY_ORDER`), then unknown keys alphabetically;
+ * `dependencies` lists `npm` before `internal`, and every nested object is
+ * sorted alphabetically. Arrays keep their order. The server stores
+ * manifests as jsonb, which forgets key order, so this is what makes a pull
+ * after a push write the same bytes.
+ */
+declare function normalizeManifest(manifest: SectionManifest): SectionManifest;
+/** The exact text `writeManifest` writes: normalized, 2-space JSON, trailing newline. */
+declare function formatManifest(manifest: SectionManifest): string;
+/** True when two manifests hold the same data, whatever their key order or formatting. */
+declare function manifestsEqual(a: SectionManifest, b: SectionManifest): boolean;
+/** Write `<name>.botlr.json` without any pull state, in the CLI's fixed key order. */
 declare function writeManifest(sectionsDir: string, name: string, manifest: SectionManifest): Promise<string>;
+/**
+ * Like `writeManifest`, but leaves the file alone when it already holds the
+ * same manifest (compared after normalization, so a hand-formatted file that
+ * says the same thing is not rewritten). Returns whether the file changed.
+ */
+declare function writeManifestIfChanged(sectionsDir: string, name: string, manifest: SectionManifest): Promise<{
+    file: string;
+    changed: boolean;
+}>;
 /** The files a manifest lists, read from `sectionsDir`, in manifest order. */
 declare function readSectionFiles(sectionsDir: string, manifest: SectionManifest): Promise<SectionSourceFileInput[]>;
 /** Write pulled files under `sectionsDir`, creating sub-directories. */
@@ -99,6 +146,7 @@ declare function computeStatus({ localHash, lock, remote }: StatusInput): Sectio
 /** The server summary that corresponds to a lock entry's scope. */
 declare function remoteForLock(summary: SectionSourceSummary | undefined, lock: LockEntry | undefined): SectionSourceScopeSummary | null | undefined;
 
+/** @deprecated use `DEFAULT_REGISTRY_FILE` from config; the path is configurable as `registryFile`. */
 declare const REGISTRY_FILE = "publisher-section-registry.ts";
 interface RegistryEntry {
     slug: string;
@@ -114,9 +162,24 @@ interface DefinitionMeta {
     category?: string;
     description?: string;
     icon?: string;
+    /** The identifier `schema:` refers to, for example `HeroSchema`. */
+    schemaName?: string;
 }
 /** Scalar fields of an `export const XDefinition = { ... }` block, when the file has one. */
 declare function parseDefinition(source: string): DefinitionMeta | null;
+/**
+ * A best-effort field DSL entry for one zod expression, or null when the
+ * expression is not one the CLI understands. `.optional()`, `.nullable()`,
+ * `.nullish()` and `.default(...)` make the field optional; anything else is
+ * required.
+ */
+declare function zodFieldToSchemaField(expr: string): SectionSchemaField | null;
+/**
+ * The field DSL for `export const <schemaName> = z.object({ ... })` in a
+ * component source, from the fields the CLI can read; null when the schema
+ * is not found or no field could be read.
+ */
+declare function parseZodSchema(source: string, schemaName: string): SectionFieldSchema | null;
 /** Module specifiers a source file imports, split into relative and package imports. */
 declare function parseImports(source: string): {
     internal: string[];
@@ -132,12 +195,171 @@ interface DeriveOptions {
     framework: string;
     /** npm dependency ranges to record, usually from the app's package.json. */
     npmVersions?: Record<string, string>;
+    /** Registry file to read; `sectionsDir/publisher-section-registry.ts` by default. */
+    registryFile?: string;
 }
 /** One manifest per registry entry whose component file exists. */
 declare function deriveManifests(sectionsDir: string, options: DeriveOptions): Promise<DerivedManifest[]>;
 /** `dependencies` + `devDependencies` of the nearest package.json above `dir`, for version ranges. */
 declare function readNpmVersions(dir: string): Promise<Record<string, string>>;
-declare function hasRegistry(sectionsDir: string): Promise<boolean>;
+/** Whether the registry file exists (`sectionsDir/publisher-section-registry.ts`, or `registryFile` when given). */
+declare function hasRegistry(sectionsDir: string, registryFile?: string): Promise<boolean>;
+
+interface RegistryAddition {
+    slug: string;
+    exportName: string;
+    /** Module specifier to import from, for example `./markdown`. */
+    importPath: string;
+}
+interface RegistryEditResult {
+    source: string;
+    /** True when an import or a map entry was appended. */
+    changed: boolean;
+    addedImport: boolean;
+    addedEntry: boolean;
+}
+/** `./markdown` for a registry at `sectionsDir` and an entry `markdown.tsx`; `./parts/x` for `parts/x.tsx`. */
+declare function importPathFor(registryFile: string, entryFile: string): string;
+/**
+ * Return `source` with `import { exportName } from "importPath";` added after
+ * the last import and `slug: exportName,` added as the last entry of the
+ * registry object. Each is skipped when it is already there. Quote style,
+ * semicolons, indentation and trailing commas follow the surrounding code.
+ */
+declare function addRegistryEntry(source: string, addition: RegistryAddition): RegistryEditResult;
+interface RegistryUpdate {
+    /** Absolute path of the registry file. */
+    file: string;
+    /** False when nothing was added or the registry could not be updated. */
+    changed: boolean;
+    addedImport?: boolean;
+    addedEntry?: boolean;
+    /** Why nothing was written, for the user. */
+    notice?: string;
+}
+/**
+ * Add the pulled section to the registry file, when there is one. Returns a
+ * notice instead of throwing when the registry is missing or the manifest has
+ * no `exportName`, since a pull should still succeed.
+ */
+declare function registerSection(sectionsDir: string, registryFile: string, manifest: SectionManifest): Promise<RegistryUpdate>;
+
+declare const PROPS_SUFFIX = ".props.ts";
+/** One property of the generated interface. */
+interface PropField {
+    name: string;
+    /** TypeScript type text. */
+    type: string;
+    required: boolean;
+    /** Doc comment lines (label, help text), without the comment markers. */
+    doc: string[];
+}
+/** The union of a select's option values, or null when the options are not plain values or `{ value }` objects. */
+declare function optionUnion(options: unknown): string | null;
+/** The TypeScript type for one field of the field DSL (or a FormBuilder field node, given its field type). */
+declare function tsTypeForField(field: {
+    type?: unknown;
+    options?: unknown;
+    multiple?: unknown;
+    fields?: unknown;
+}): string;
+/** Properties for the field DSL, in schema order. Non-object values are skipped. */
+declare function collectDslFields(schema: Record<string, unknown>): PropField[];
+/** Properties for the FormBuilder format: field and repeater nodes, with groups flattened. */
+declare function collectFormBuilderFields(nodes: SectionFormBuilderNode[]): PropField[];
+/** Properties for a definition schema in either format; empty for anything else. */
+declare function collectFields(schema: unknown): PropField[];
+/** The property names a definition schema defines, in either format. */
+declare function schemaFieldNames(schema: unknown): string[];
+/** `hero-banner` or `forum_new_thread` → `HeroBanner` / `ForumNewThread`. */
+declare function pascalCase(slug: string): string;
+/** `<ExportName>Props`, from the manifest's `exportName` or a PascalCase of the slug. */
+declare function propsInterfaceName(manifest: Pick<SectionManifest, "section" | "exportName">): string;
+interface GenerateOptions {
+    /** Section slug, named in the header comment. */
+    section: string;
+    interfaceName: string;
+}
+/** The full text of `<name>.props.ts` for a definition schema. */
+declare function generatePropsSource(schema: unknown, options: GenerateOptions): string;
+declare function propsPath(sectionsDir: string, name: string): string;
+interface PropsTypesUpdate {
+    file: string;
+    interfaceName: string;
+    /** False when the file already held the generated text. */
+    changed: boolean;
+}
+/**
+ * Write `<name>.props.ts` for a section, leaving the file alone when its
+ * text is already what would be generated.
+ */
+declare function writePropsTypes(sectionsDir: string, manifest: SectionManifest, schema: unknown): Promise<PropsTypesUpdate>;
+
+/**
+ * Schema drift: the props a section's code expects (the manifest's optional
+ * `schema`, field DSL only) against the props the dashboard defines (the
+ * section definition's schema from the server). The CLI only reports the
+ * difference; the dashboard owns the definition's schema.
+ */
+
+interface SchemaDrift {
+    /** Props the code lists that the dashboard does not define. */
+    missingInDashboard: string[];
+    /** Props the dashboard defines that the code does not list. */
+    missingInCode: string[];
+}
+/** The manifest's `schema` when it is a schema object in either format, else null. */
+declare function manifestSchema(manifest: SectionManifest): SectionSchema | null;
+/**
+ * Key difference between the code's schema and the definition's schema
+ * (either format on either side; FormBuilder schemas contribute their node
+ * names). Null when the manifest has no schema object or the keys match.
+ */
+declare function compareSchemas(manifest: SectionManifest, definitionSchema: unknown): SchemaDrift | null;
+/** The warning text for a drift, one line per direction, naming the two commands that resolve it. */
+declare function formatDriftWarning(name: string, drift: SchemaDrift): string;
+
+/**
+ * Field-key diff between two props schemas, for `botlr schema push` to show
+ * before it replaces the dashboard's schema with the code's. Field DSL keys
+ * are the object's keys; FormBuilder schemas contribute their node names
+ * (groups flattened), so the two formats can be compared with each other.
+ */
+
+interface SchemaKeyDiff {
+    /** Keys the new schema has that the current one lacks. */
+    added: string[];
+    /** Keys the current schema has that the new one lacks. */
+    removed: string[];
+    /** Keys both have. */
+    kept: string[];
+}
+/** The field keys of a schema in either format, in schema order and without duplicates. */
+declare function schemaKeys(schema: unknown): string[];
+/** Keys added, removed and kept going from `current` to `next`; each list sorted. */
+declare function diffSchemaKeys(current: unknown, next: unknown): SchemaKeyDiff;
+interface SchemaPushPreview {
+    name: string;
+    /** The dashboard's current schema. */
+    current: unknown;
+    /** Its format as the server reports it, else as detected. */
+    currentFormat: SectionSchemaFormat | null;
+    /** The manifest's schema, about to replace it. */
+    next: unknown;
+    nextFormat: SectionSchemaFormat | null;
+    diff: SchemaKeyDiff;
+}
+/** The preview for a push, with formats detected from the schemas unless given. */
+declare function previewSchemaPush(name: string, current: unknown, next: unknown, formats?: {
+    currentFormat?: SectionSchemaFormat | null;
+    nextFormat?: SectionSchemaFormat | null;
+}): SchemaPushPreview;
+/**
+ * The diff as the CLI prints it: one header line with both formats and
+ * field counts, then one line per non-empty direction. The `kept` line is
+ * always printed, with "none" when nothing survives.
+ */
+declare function formatSchemaDiff(preview: SchemaPushPreview): string;
 
 /** A client from the resolved config. `needPersonalToken` makes a missing `BOTLR_PAT` an error up front. */
 declare function clientFor(config: ResolvedConfig, options?: {
@@ -153,6 +375,10 @@ interface PullOptions {
     shared?: boolean;
     /** Overwrite local files that changed since the last pull. */
     force?: boolean;
+    /** Leave the registry file alone. */
+    noRegistry?: boolean;
+    /** Do not write `<name>.props.ts`; also off when the config says `types: false`. */
+    noTypes?: boolean;
 }
 interface PullResult {
     name: string;
@@ -161,6 +387,14 @@ interface PullResult {
     files: string[];
     /** Set when the section was skipped instead of written. */
     skipped?: string;
+    /** Whether `<name>.botlr.json` changed; false when the local manifest already said the same. */
+    manifestChanged?: boolean;
+    /** What happened to the registry file; absent for skipped sections and with `noRegistry`. */
+    registry?: RegistryUpdate;
+    /** What happened to `<name>.props.ts`; absent when types are off or the section has no definition. */
+    types?: PropsTypesUpdate;
+    /** Why no prop types were written, when they were expected. */
+    typesNotice?: string;
 }
 declare function pullSections(config: ResolvedConfig, options: PullOptions): Promise<PullResult[]>;
 
@@ -178,6 +412,8 @@ interface PushResult {
     scope: SectionSourceScope;
     version: number;
     contentHash: string;
+    /** Set when the manifest's `schema` and the definition's schema list different props. */
+    drift?: SchemaDrift;
 }
 declare function pushSection(config: ResolvedConfig, options: PushOptions): Promise<PushResult>;
 
@@ -190,6 +426,8 @@ interface SectionStatusRow {
     remote: number | null;
     scope: string;
     detail?: string;
+    /** Set when the manifest's `schema` and the dashboard's definition list different props (not offline). */
+    drift?: SchemaDrift;
 }
 declare function sectionStatuses(config: ResolvedConfig, options?: {
     names?: string[];
@@ -215,4 +453,63 @@ interface InitResult {
  */
 declare function initSections(config: ResolvedConfig, options?: InitOptions): Promise<InitResult[]>;
 
-export { type BotlrCliConfigFile, CONFIG_FILE, ConfigError, type ConfigOverrides, DEFAULT_FRAMEWORK, DEFAULT_SECTIONS_DIR, type DefinitionMeta, type DeriveOptions, type DerivedManifest, type InitOptions, type InitResult, LOCK_DIR, LOCK_FILE, type LockEntry, MANIFEST_SUFFIX, ManifestError, type PullOptions, type PullResult, type PushOptions, type PushResult, REGISTRY_FILE, type RegistryEntry, type ResolvedConfig, type SectionStatus, type SectionStatusRow, type SectionsLock, type StatusInput, clientFor, computeStatus, deriveManifests, findConfigFile, hasRegistry, initSections, listManifests, listSections, loadConfig, lockPath, manifestPath, parseDefinition, parseImports, parseRegistry, pullSections, pushSection, readConfigFile, readLock, readManifest, readNpmVersions, readSectionFiles, remoteForLock, safeJoin, sectionStatuses, updateLock, validateManifest, writeLock, writeManifest, writeSectionFiles };
+interface SchemaPullOptions {
+    /** Section names; empty with `all: true` means every manifest in the sections directory. */
+    names: string[];
+    all?: boolean;
+    /** Do not write `<name>.props.ts`; also off when the config says `types: false`. */
+    noTypes?: boolean;
+}
+interface SchemaPullResult {
+    name: string;
+    /** Whether `<name>.botlr.json` changed; false when its `schema` already equalled the dashboard's. */
+    changed: boolean;
+    /** The manifest file. */
+    file: string;
+    format?: string;
+    /** What happened to `<name>.props.ts`; absent when types are off or the pull failed. */
+    types?: PropsTypesUpdate;
+    /** Why nothing was written: no manifest, or no section type of that name in the app. */
+    error?: string;
+}
+/** Copy the dashboard's schema into each manifest's `schema`, then regenerate the prop types. */
+declare function pullSchemas(config: ResolvedConfig, options: SchemaPullOptions): Promise<SchemaPullResult[]>;
+interface SchemaPushOptions {
+    name: string;
+    /** Replace the schema even when the dashboard's is in the other format. */
+    force?: boolean;
+    /**
+     * Asked once with the preview before anything is sent; return false to
+     * stop. Omit to push without asking (`--yes`).
+     */
+    confirm?: (preview: SchemaPushPreview) => Promise<boolean> | boolean;
+    /** Do not write `<name>.props.ts` afterwards; also off when the config says `types: false`. */
+    noTypes?: boolean;
+}
+interface SchemaPushResult {
+    name: string;
+    preview: SchemaPushPreview;
+    /** False when `confirm` said no; nothing was sent. */
+    pushed: boolean;
+    /** From the server: false when the stored schema already equalled the manifest's. */
+    changed?: boolean;
+    previousFormat?: string;
+    format?: string;
+    types?: PropsTypesUpdate;
+}
+/** 409: the dashboard's schema is in the other format and `--force` was not given. */
+declare class SchemaFormatConflict extends Error {
+    readonly sectionName: string;
+    readonly currentFormat: string;
+    readonly newFormat: string;
+    constructor(sectionName: string, currentFormat: string, newFormat: string, message?: string);
+}
+/** 422: the server refused the schema (not an object of fields, or the definition is not project-scoped). */
+declare class SchemaRejected extends Error {
+    readonly sectionName: string;
+    constructor(sectionName: string, message: string);
+}
+/** Send the manifest's `schema` to the dashboard, after showing the diff and asking. */
+declare function pushSchema(config: ResolvedConfig, options: SchemaPushOptions): Promise<SchemaPushResult>;
+
+export { type BotlrCliConfigFile, CONFIG_FILE, ConfigError, type ConfigOverrides, DEFAULT_FRAMEWORK, DEFAULT_REGISTRY_FILE, DEFAULT_SECTIONS_DIR, type DefinitionMeta, type DeriveOptions, type DerivedManifest, type GenerateOptions, type InitOptions, type InitResult, LOCK_DIR, LOCK_FILE, type LockEntry, MANIFEST_KEY_ORDER, MANIFEST_SUFFIX, ManifestError, PROPS_SUFFIX, type PropField, type PropsTypesUpdate, type PullOptions, type PullResult, type PushOptions, type PushResult, REGISTRY_FILE, type RegistryAddition, type RegistryEditResult, type RegistryEntry, type RegistryUpdate, type ResolvedConfig, type SchemaDrift, SchemaFormatConflict, type SchemaKeyDiff, type SchemaPullOptions, type SchemaPullResult, type SchemaPushOptions, type SchemaPushPreview, type SchemaPushResult, SchemaRejected, type SectionStatus, type SectionStatusRow, type SectionsLock, type StatusInput, addRegistryEntry, clientFor, collectDslFields, collectFields, collectFormBuilderFields, compareSchemas, computeStatus, deriveManifests, diffSchemaKeys, findConfigFile, formatDriftWarning, formatManifest, formatSchemaDiff, generatePropsSource, hasRegistry, importPathFor, initSections, listManifests, listSections, loadConfig, lockPath, manifestPath, manifestSchema, manifestsEqual, nextLockEntry, normalizeManifest, optionUnion, parseDefinition, parseImports, parseRegistry, parseZodSchema, pascalCase, previewSchemaPush, propsInterfaceName, propsPath, pullSchemas, pullSections, pushSchema, pushSection, readConfigFile, readLock, readManifest, readNpmVersions, readSectionFiles, registerSection, remoteForLock, safeJoin, schemaFieldNames, schemaKeys, sectionStatuses, tsTypeForField, updateLock, validateManifest, writeLock, writeManifest, writeManifestIfChanged, writePropsTypes, writeSectionFiles, zodFieldToSchemaField };