@botlr/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @botlr/cli
 
+## 0.4.0
+
+### Minor Changes
+
+- `botlr schema push` follows the server's merge behaviour for FormBuilder schemas instead of asking for `--force`.
+
+  - Field-DSL `schema` in the manifest pushed at a definition whose dashboard schema is in the FormBuilder format is merged by the server: a node per field the dashboard lacks, every existing node kept with its id, label and settings, nothing removed. The CLI's diff header says so (`the server will add the missing fields as FormBuilder nodes and keep the dashboard's (format kept; --force would replace it)`), lists the dashboard's extra nodes as "dashboard only, kept", asks as before, and then prints what the server did: `merged schema of <name> (form-builder): added ...; kept ...`, plus `the dashboard also defines: ... (not in the code)` when the dashboard has nodes the code does not declare. Same format: `replaced schema of <name>`. `changed: false`: `nothing to change`.
+  - A FormBuilder `schema` pushed at a field-DSL definition still needs `--force`: the CLI stops right after the diff with the hint, without asking or sending anything (the server would answer 409). `--force` replaces the schema outright whatever the formats, and the question says which format replaces which.
+  - `@botlr/sdk`: `SectionSchemaPutResponse` gains `mode: "replaced" | "merged"` (the `SectionSchemaPushMode` type), `added` and `dashboardOnly`.
+
+### Patch Changes
+
+- Updated dependencies
+  - @botlr/sdk@0.6.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -168,9 +168,26 @@ 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
+What the server does depends on the two formats:
+
+- Same format: the schema is replaced.
+- Field DSL in the manifest, FormBuilder in the dashboard (the common case
+  for sections configured in the dashboard first): the server **merges**. It
+  adds a FormBuilder node per field the dashboard lacks, built like the
+  dashboard's own "Convert to FormBuilder", keeps every existing node with
+  its id, label and settings, only sets `required: true` where the code
+  requires it, and removes nothing. The diff header says so, the dashboard's
+  extra nodes are listed as "dashboard only, kept", and the result line
+  reads `merged schema of hero (form-builder): added ctaLink, subheading;
+  kept heading`, followed by `the dashboard also defines: image (not in the
+  code)` when the dashboard has nodes the code does not declare.
+- FormBuilder in the manifest, field DSL in the dashboard: the CLI prints
+  the diff and both formats and stops with a hint to rerun with `--force`,
+  without asking or sending anything (the server would refuse with 409).
+
+`--force` replaces the schema outright whatever the formats, and the
+question says which format replaces which. When nothing had to change the
+result line says `nothing to change`. 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

package/dist/cli.js

@@ -1096,7 +1096,11 @@ async function initSections(config, options = {}) {
 }
 
 // src/commands/schema.ts
-import { BotlrError, BotlrSchemaFormatConflictError, botlrErrorMessage } from "@botlr/sdk";
+import {
+  BotlrError,
+  BotlrSchemaFormatConflictError,
+  botlrErrorMessage
+} from "@botlr/sdk";
 
 // src/schema-diff.ts
 import { schemaFormat as schemaFormat2 } from "@botlr/sdk";
@@ -1112,15 +1116,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"}`;
@@ -1129,14 +1138,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");
@@ -1174,16 +1190,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) {
@@ -1210,13 +1228,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));
@@ -1234,6 +1256,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
   };
 }
@@ -1280,6 +1305,7 @@ async function run(action) {
   pull first, or push --force to overwrite`);
     }
     if (error instanceof SchemaFormatConflict) {
+      if (error.preview) console.log(formatSchemaDiff(error.preview));
       fail(
         `${error.message}
   dashboard: ${error.currentFormat}
@@ -1443,16 +1469,17 @@ async function confirmOnTerminal(preview) {
   if (!process.stdin.isTTY) {
     fail(`not a terminal: rerun with --yes to push the schema of '${preview.name}' without asking`);
   }
+  const question = preview.expected === "merged" ? `merge the code's fields into the dashboard's ${preview.currentFormat} schema of '${preview.name}'? [y/N] ` : preview.force && preview.currentFormat !== preview.nextFormat ? `replace the dashboard's ${preview.currentFormat} schema of '${preview.name}' with the code's ${preview.nextFormat} schema? [y/N] ` : `replace the dashboard's schema of '${preview.name}' with the code's? [y/N] `;
   const rl = createInterface({ input: process.stdin, output: process.stderr });
   try {
-    const answer = await rl.question(`replace the dashboard's schema of '${preview.name}' with the code's? [y/N] `);
+    const answer = await rl.question(question);
     return /^y(es)?$/i.test(answer.trim());
   } finally {
     rl.close();
   }
 }
 withCommon(
-  schema.command("push <name>").description("send the manifest's 'schema' to the dashboard as the definition's props schema (needs BOTLR_PAT)").option("--force", "replace the schema even when the dashboard's is in the other format").option("-y, --yes", "push without asking").option("--no-types", "do not write <name>.props.ts afterwards")
+  schema.command("push <name>").description("send the manifest's 'schema' to the dashboard as the definition's props schema (needs BOTLR_PAT)").option("--force", "replace the schema outright, instead of merging the code's fields into a FormBuilder schema").option("-y, --yes", "push without asking").option("--no-types", "do not write <name>.props.ts afterwards")
 ).action(
   (name, opts) => run(async () => {
     const config = await loadConfig(process.cwd(), overrides(opts));
@@ -1470,8 +1497,15 @@ withCommon(
       return;
     }
     const formats = result.previousFormat && result.format && result.previousFormat !== result.format ? ` (${result.previousFormat} -> ${result.format})` : result.format ? ` (${result.format})` : "";
-    if (result.changed) console.log(`pushed schema of ${result.name}${formats}`);
-    else console.log(`schema of ${result.name} already matches, nothing changed${formats}`);
+    if (!result.changed) console.log(`schema of ${result.name}: nothing to change${formats}`);
+    else if (result.mode === "merged") {
+      const added = result.added?.length ? `added ${result.added.join(", ")}` : "added nothing";
+      const kept = result.preview.diff.kept.length ? `; kept ${result.preview.diff.kept.join(", ")}` : "";
+      console.log(`merged schema of ${result.name}${formats}: ${added}${kept}`);
+    } else console.log(`replaced schema of ${result.name}${formats}`);
+    if (result.dashboardOnly?.length) {
+      console.log(`      the dashboard also defines: ${result.dashboardOnly.join(", ")} (not in the code)`);
+    }
     if (result.types?.changed) console.log(`      types: wrote ${result.types.interfaceName} to ${path7.relative(process.cwd(), result.types.file)}`);
   })
 );