@botlr/cli 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SectionSourceScope, SectionManifest, SectionSourceFileInput, SectionSourceScopeSummary, SectionSourceSummary, SectionFieldSchema, SectionSchemaField, SectionFormBuilderNode, BotlrClient } from '@botlr/sdk';
+import { SectionSourceScope, SectionManifest, SectionSourceFileInput, SectionSourceScopeSummary, SectionSourceSummary, SectionFieldSchema, SectionSchemaField, SectionFormBuilderNode, SectionSchema, SectionSchemaFormat, BotlrClient, SectionSchemaPushMode } from '@botlr/sdk';
 
 declare const CONFIG_FILE = "botlr.config.json";
 declare const DEFAULT_FRAMEWORK = "react-next";
@@ -308,17 +308,75 @@ interface SchemaDrift {
     /** Props the dashboard defines that the code does not list. */
     missingInCode: string[];
 }
-/** The manifest's `schema` when it is a field DSL object, else null. */
-declare function manifestSchema(manifest: SectionManifest): Record<string, unknown> | null;
+/** 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 (field DSL) and the definition's
- * schema (either format). Null when the manifest has no schema object or
- * the keys match.
+ * 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, pointing at the dashboard. */
+/** 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;
+    /** Whether `--force` was given. */
+    force: boolean;
+    /** What the server is expected to do with this push. */
+    expected: ExpectedPushMode;
+}
+/**
+ * - `replaced`: same format, or `--force`
+ * - `merged`: field-DSL fields at a FormBuilder schema; the server adds nodes and keeps the rest
+ * - `conflict`: a FormBuilder schema at a field-DSL one; the server answers 409 without `--force`
+ */
+type ExpectedPushMode = "replaced" | "merged" | "conflict";
+/** True when both formats are known and differ. */
+declare function formatsDiffer(preview: Pick<SchemaPushPreview, "currentFormat" | "nextFormat">): boolean;
+declare function expectedPushMode(preview: Pick<SchemaPushPreview, "currentFormat" | "nextFormat" | "force">): ExpectedPushMode;
+/** The preview for a push, with formats detected from the schemas unless given. */
+declare function previewSchemaPush(name: string, current: unknown, next: unknown, options?: {
+    currentFormat?: SectionSchemaFormat | null;
+    nextFormat?: SectionSchemaFormat | null;
+    force?: boolean;
+}): SchemaPushPreview;
+/**
+ * The diff as the CLI prints it: one header line with both formats and
+ * field counts (and, for a merge, what the server will do), then one line
+ * per non-empty direction. The `kept` line is always printed, with "none"
+ * when nothing survives. In a merge the dashboard's extra nodes are kept,
+ * so that line says so instead of "removed".
+ */
+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?: {
     needPersonalToken?: boolean;
@@ -411,4 +469,81 @@ interface InitResult {
  */
 declare function initSections(config: ResolvedConfig, options?: InitOptions): Promise<InitResult[]>;
 
-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, type SectionStatus, type SectionStatusRow, type SectionsLock, type StatusInput, addRegistryEntry, clientFor, collectDslFields, collectFields, collectFormBuilderFields, compareSchemas, computeStatus, deriveManifests, findConfigFile, formatDriftWarning, formatManifest, generatePropsSource, hasRegistry, importPathFor, initSections, listManifests, listSections, loadConfig, lockPath, manifestPath, manifestSchema, manifestsEqual, nextLockEntry, normalizeManifest, optionUnion, parseDefinition, parseImports, parseRegistry, parseZodSchema, pascalCase, propsInterfaceName, propsPath, pullSections, pushSection, readConfigFile, readLock, readManifest, readNpmVersions, readSectionFiles, registerSection, remoteForLock, safeJoin, schemaFieldNames, sectionStatuses, tsTypeForField, updateLock, validateManifest, writeLock, writeManifest, writeManifestIfChanged, writePropsTypes, writeSectionFiles, zodFieldToSchemaField };
+/**
+ * `botlr schema pull` and `botlr schema push`: the explicit way to resolve
+ * drift between the manifest's `schema` (what the code expects) and the
+ * dashboard's definition schema. A source push never touches the schema;
+ * these two commands do, in the direction the user picks.
+ */
+
+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 outright whatever the formats, instead of merging into a FormBuilder schema. */
+    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 nothing had to change. */
+    changed?: boolean;
+    previousFormat?: string;
+    format?: string;
+    /** What the server did: replaced the schema, or merged the code's fields into a FormBuilder schema. */
+    mode?: SectionSchemaPushMode;
+    /** Field names that became new nodes (`merged`). */
+    added?: string[];
+    /** Node names only the dashboard defines, kept (`merged`). */
+    dashboardOnly?: string[];
+    types?: PropsTypesUpdate;
+}
+/**
+ * A FormBuilder schema pushed at a field-DSL definition without `--force`:
+ * raised before anything is sent when the formats are known (then `preview`
+ * is set), or from the server's 409.
+ */
+declare class SchemaFormatConflict extends Error {
+    readonly sectionName: string;
+    readonly currentFormat: string;
+    readonly newFormat: string;
+    readonly preview?: SchemaPushPreview | undefined;
+    constructor(sectionName: string, currentFormat: string, newFormat: string, message?: string, preview?: SchemaPushPreview | undefined);
+}
+/** 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 ExpectedPushMode, 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, expectedPushMode, findConfigFile, formatDriftWarning, formatManifest, formatSchemaDiff, formatsDiffer, 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 };

package/dist/index.js

@@ -805,15 +805,15 @@ async function writePropsTypes(sectionsDir, manifest, schema) {
 }
 
 // src/drift.ts
-import { isFieldSchema as isFieldSchema2 } from "@botlr/sdk";
+import { schemaFormat } from "@botlr/sdk";
 function manifestSchema(manifest) {
   const schema = manifest.schema;
-  return isFieldSchema2(schema) ? schema : null;
+  return schemaFormat(schema) ? schema : null;
 }
 function compareSchemas(manifest, definitionSchema) {
   const code = manifestSchema(manifest);
   if (!code) return null;
-  const codeKeys = new Set(Object.keys(code).filter((k) => code[k] && typeof code[k] === "object"));
+  const codeKeys = new Set(schemaFieldNames(code));
   const dashboardKeys = new Set(schemaFieldNames(definitionSchema));
   const missingInDashboard = [...codeKeys].filter((k) => !dashboardKeys.has(k)).sort();
   const missingInCode = [...dashboardKeys].filter((k) => !codeKeys.has(k)).sort();
@@ -828,7 +828,65 @@ function formatDriftWarning(name, drift) {
   if (drift.missingInCode.length) {
     lines.push(`  the dashboard defines props the code does not list: ${drift.missingInCode.join(", ")}`);
   }
-  lines.push(`  the dashboard owns the schema: edit it there, or update 'schema' in ${name}.botlr.json`);
+  lines.push(`  the dashboard owns the schema; a code push never changes it. To resolve:`);
+  lines.push(`    botlr schema pull ${name}   takes the dashboard's schema into ${name}.botlr.json`);
+  lines.push(`    botlr schema push ${name}   sends the code's schema to the dashboard`);
+  return lines.join("\n");
+}
+
+// src/schema-diff.ts
+import { schemaFormat as schemaFormat2 } from "@botlr/sdk";
+function schemaKeys(schema) {
+  return [...new Set(schemaFieldNames(schema))];
+}
+function diffSchemaKeys(current, next) {
+  const currentKeys = new Set(schemaKeys(current));
+  const nextKeys = new Set(schemaKeys(next));
+  return {
+    added: [...nextKeys].filter((k) => !currentKeys.has(k)).sort(),
+    removed: [...currentKeys].filter((k) => !nextKeys.has(k)).sort(),
+    kept: [...nextKeys].filter((k) => currentKeys.has(k)).sort()
+  };
+}
+function formatsDiffer(preview) {
+  return !!preview.currentFormat && !!preview.nextFormat && preview.currentFormat !== preview.nextFormat;
+}
+function expectedPushMode(preview) {
+  if (preview.force || !formatsDiffer(preview)) return "replaced";
+  return preview.currentFormat === "form-builder" && preview.nextFormat === "field-dsl" ? "merged" : "conflict";
+}
+function previewSchemaPush(name, current, next, options = {}) {
+  const formats = {
+    currentFormat: options.currentFormat ?? schemaFormat2(current),
+    nextFormat: options.nextFormat ?? schemaFormat2(next),
+    force: options.force ?? false
+  };
+  return { name, current, next, diff: diffSchemaKeys(current, next), ...formats, expected: expectedPushMode(formats) };
+}
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function formatName(format) {
+  return format ?? "unknown";
+}
+function formatSchemaDiff(preview) {
+  const { diff, expected } = preview;
+  let header = `schema of '${preview.name}': dashboard has ${formatName(preview.currentFormat)} (${plural(schemaKeys(preview.current).length, "field")}), code has ${formatName(preview.nextFormat)} (${plural(schemaKeys(preview.next).length, "field")})`;
+  if (expected === "merged") {
+    header += ": the server will add the missing fields as FormBuilder nodes and keep the dashboard's (format kept; --force would replace it)";
+  }
+  const lines = [header];
+  if (diff.added.length) lines.push(`  + added    ${diff.added.join(", ")}`);
+  if (diff.removed.length) {
+    lines.push(expected === "merged" ? `  ~ dashboard only, kept  ${diff.removed.join(", ")}` : `  - removed  ${diff.removed.join(", ")}`);
+  }
+  lines.push(`  = kept     ${diff.kept.length ? diff.kept.join(", ") : "none"}`);
+  if (formatsDiffer(preview) && expected !== "merged") {
+    lines.push(
+      preview.force ? `  the formats differ: replacing ${preview.currentFormat} with ${preview.nextFormat} (--force)` : `  the formats differ: the push needs --force to replace ${preview.currentFormat} with ${preview.nextFormat}`
+    );
+  }
+  if (!diff.added.length && !diff.removed.length) lines.push("  the field keys match; only field settings may change");
   return lines.join("\n");
 }
 
@@ -1078,6 +1136,116 @@ async function initSections(config, options = {}) {
   }
   return results;
 }
+
+// src/commands/schema.ts
+import {
+  BotlrError,
+  BotlrSchemaFormatConflictError,
+  botlrErrorMessage
+} from "@botlr/sdk";
+function isNotFound(error) {
+  return error instanceof BotlrError && error.status === 404;
+}
+async function pullSchemas(config, options) {
+  const client = clientFor(config);
+  const names = options.all ? await listManifests(config.sectionsDir) : options.names;
+  const results = [];
+  for (const name of names) {
+    let manifest;
+    try {
+      manifest = await readManifest(config.sectionsDir, name);
+    } catch (error) {
+      results.push({ name, changed: false, file: "", error: error.message });
+      continue;
+    }
+    let definition;
+    try {
+      definition = (await client.sections.getSchema(name)).definition;
+    } catch (error) {
+      if (!isNotFound(error)) throw error;
+      results.push({ name, changed: false, file: "", error: `the app has no section type '${name}' (botlr push ${name} --create adds one)` });
+      continue;
+    }
+    const updated = { ...manifest, schema: definition.schema };
+    const written = await writeManifestIfChanged(config.sectionsDir, name, updated);
+    const types = config.types && !options.noTypes ? await writePropsTypes(config.sectionsDir, manifest, definition.schema) : void 0;
+    results.push({ name, changed: written.changed, file: written.file, format: definition.format, types });
+  }
+  return results;
+}
+var SchemaFormatConflict = class extends Error {
+  constructor(sectionName, currentFormat, newFormat, message, preview) {
+    super(message ?? `the schema of '${sectionName}' is stored as ${currentFormat}, the manifest's is ${newFormat}`);
+    this.sectionName = sectionName;
+    this.currentFormat = currentFormat;
+    this.newFormat = newFormat;
+    this.preview = preview;
+    this.name = "SchemaFormatConflict";
+  }
+  sectionName;
+  currentFormat;
+  newFormat;
+  preview;
+};
+var SchemaRejected = class extends Error {
+  constructor(sectionName, message) {
+    super(message);
+    this.sectionName = sectionName;
+    this.name = "SchemaRejected";
+  }
+  sectionName;
+};
+async function pushSchema(config, options) {
+  const client = clientFor(config, { needPersonalToken: true });
+  const { name } = options;
+  const manifest = await readManifest(config.sectionsDir, name);
+  const next = manifest.schema;
+  if (!next || typeof next !== "object" || Array.isArray(next)) {
+    throw new ManifestError(
+      `${name}.botlr.json has no 'schema' object to push; add one, or run 'botlr schema pull ${name}' to take the dashboard's`
+    );
+  }
+  let current;
+  try {
+    current = (await client.sections.getSchema(name)).definition;
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+    throw new ManifestError(`the app has no section type '${name}'; push the code first with 'botlr push ${name} --create'`);
+  }
+  const force = options.force ?? false;
+  const preview = previewSchemaPush(name, current.schema, next, { currentFormat: current.format, force });
+  if (preview.expected === "conflict") {
+    throw new SchemaFormatConflict(name, preview.currentFormat, preview.nextFormat, void 0, preview);
+  }
+  if (options.confirm && !await options.confirm(preview)) {
+    return { name, preview, pushed: false };
+  }
+  let response;
+  try {
+    response = await client.sections.putSchema(name, { schema: next, force });
+  } catch (error) {
+    if (error instanceof BotlrSchemaFormatConflictError) {
+      throw new SchemaFormatConflict(name, error.currentFormat, error.newFormat, botlrErrorMessage(error));
+    }
+    if (error instanceof BotlrError && error.status === 422) {
+      throw new SchemaRejected(name, botlrErrorMessage(error) ?? "the server rejected the schema (422)");
+    }
+    throw error;
+  }
+  const types = config.types && !options.noTypes ? await writePropsTypes(config.sectionsDir, manifest, response.definition.schema) : void 0;
+  return {
+    name,
+    preview,
+    pushed: true,
+    changed: response.changed,
+    previousFormat: response.previousFormat,
+    format: response.definition.format,
+    mode: response.mode,
+    added: response.added,
+    dashboardOnly: response.dashboardOnly,
+    types
+  };
+}
 export {
   CONFIG_FILE,
   ConfigError,
@@ -1091,6 +1259,8 @@ export {
   ManifestError,
   PROPS_SUFFIX,
   REGISTRY_FILE,
+  SchemaFormatConflict,
+  SchemaRejected,
   addRegistryEntry,
   clientFor,
   collectDslFields,
@@ -1099,9 +1269,13 @@ export {
   compareSchemas,
   computeStatus,
   deriveManifests,
+  diffSchemaKeys,
+  expectedPushMode,
   findConfigFile,
   formatDriftWarning,
   formatManifest,
+  formatSchemaDiff,
+  formatsDiffer,
   generatePropsSource,
   hasRegistry,
   importPathFor,
@@ -1121,9 +1295,12 @@ export {
   parseRegistry,
   parseZodSchema,
   pascalCase,
+  previewSchemaPush,
   propsInterfaceName,
   propsPath,
+  pullSchemas,
   pullSections,
+  pushSchema,
   pushSection,
   readConfigFile,
   readLock,
@@ -1134,6 +1311,7 @@ export {
   remoteForLock,
   safeJoin,
   schemaFieldNames,
+  schemaKeys,
   sectionStatuses,
   tsTypeForField,
   updateLock,