@botlr/cli 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { SectionSourceScope, SectionManifest, SectionSourceFileInput, SectionSourceScopeSummary, SectionSourceSummary, SectionFieldSchema, SectionSchemaField, SectionFormBuilderNode, SectionSchema, SectionSchemaFormat, 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";
@@ -348,16 +348,32 @@ interface SchemaPushPreview {
     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, formats?: {
+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, then one line per non-empty direction. The `kept` line is
- * always printed, with "none" when nothing survives.
+ * 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;
 
@@ -453,6 +469,13 @@ interface InitResult {
  */
 declare function initSections(config: ResolvedConfig, options?: InitOptions): Promise<InitResult[]>;
 
+/**
+ * `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[];
@@ -476,7 +499,7 @@ interface SchemaPullResult {
 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. */
+    /** 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
@@ -491,18 +514,29 @@ interface SchemaPushResult {
     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. */
+    /** 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;
 }
-/** 409: the dashboard's schema is in the other format and `--force` was not given. */
+/**
+ * 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;
-    constructor(sectionName: string, currentFormat: string, newFormat: string, message?: 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 {
@@ -512,4 +546,4 @@ declare class SchemaRejected extends Error {
 /** 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 };
+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

@@ -848,15 +848,20 @@ function diffSchemaKeys(current, next) {
     kept: [...nextKeys].filter((k) => currentKeys.has(k)).sort()
   };
 }
-function previewSchemaPush(name, current, next, formats = {}) {
-  return {
-    name,
-    current,
-    currentFormat: formats.currentFormat ?? schemaFormat2(current),
-    next,
-    nextFormat: formats.nextFormat ?? schemaFormat2(next),
-    diff: diffSchemaKeys(current, next)
+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"}`;
@@ -865,14 +870,21 @@ function formatName(format) {
   return format ?? "unknown";
 }
 function formatSchemaDiff(preview) {
-  const { diff } = preview;
-  const 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")})`;
+  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(`  - removed  ${diff.removed.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 (preview.currentFormat && preview.nextFormat && preview.currentFormat !== preview.nextFormat) {
-    lines.push(`  the formats differ: the push needs --force to replace ${preview.currentFormat} with ${preview.nextFormat}`);
+  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");
@@ -1126,7 +1138,11 @@ async function initSections(config, options = {}) {
 }
 
 // src/commands/schema.ts
-import { BotlrError, BotlrSchemaFormatConflictError, botlrErrorMessage } from "@botlr/sdk";
+import {
+  BotlrError,
+  BotlrSchemaFormatConflictError,
+  botlrErrorMessage
+} from "@botlr/sdk";
 function isNotFound(error) {
   return error instanceof BotlrError && error.status === 404;
 }
@@ -1158,16 +1174,18 @@ async function pullSchemas(config, options) {
   return results;
 }
 var SchemaFormatConflict = class extends Error {
-  constructor(sectionName, currentFormat, newFormat, message) {
+  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) {
@@ -1194,13 +1212,17 @@ async function pushSchema(config, options) {
     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 preview = previewSchemaPush(name, current.schema, next, { currentFormat: current.format });
+  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: options.force ?? false });
+    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));
@@ -1218,6 +1240,9 @@ async function pushSchema(config, options) {
     changed: response.changed,
     previousFormat: response.previousFormat,
     format: response.definition.format,
+    mode: response.mode,
+    added: response.added,
+    dashboardOnly: response.dashboardOnly,
     types
   };
 }
@@ -1245,10 +1270,12 @@ export {
   computeStatus,
   deriveManifests,
   diffSchemaKeys,
+  expectedPushMode,
   findConfigFile,
   formatDriftWarning,
   formatManifest,
   formatSchemaDiff,
+  formatsDiffer,
   generatePropsSource,
   hasRegistry,
   importPathFor,