@botlr/cli 0.2.0 → 0.3.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 } from '@botlr/sdk';
 
 declare const CONFIG_FILE = "botlr.config.json";
 declare const DEFAULT_FRAMEWORK = "react-next";
@@ -308,17 +308,59 @@ 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;
+}
+/** 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?: {
     needPersonalToken?: boolean;
@@ -411,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_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 };
+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 };

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,53 @@ 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 previewSchemaPush(name, current, next, formats = {}) {
+  return {
+    name,
+    current,
+    currentFormat: formats.currentFormat ?? schemaFormat2(current),
+    next,
+    nextFormat: formats.nextFormat ?? schemaFormat2(next),
+    diff: diffSchemaKeys(current, next)
+  };
+}
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+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 lines = [header];
+  if (diff.added.length) lines.push(`  + added    ${diff.added.join(", ")}`);
+  if (diff.removed.length) lines.push(`  - 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 (!diff.added.length && !diff.removed.length) lines.push("  the field keys match; only field settings may change");
   return lines.join("\n");
 }
 
@@ -1078,6 +1124,103 @@ 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) {
+    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.name = "SchemaFormatConflict";
+  }
+  sectionName;
+  currentFormat;
+  newFormat;
+};
+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 preview = previewSchemaPush(name, current.schema, next, { currentFormat: current.format });
+  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 });
+  } 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,
+    types
+  };
+}
 export {
   CONFIG_FILE,
   ConfigError,
@@ -1091,6 +1234,8 @@ export {
   ManifestError,
   PROPS_SUFFIX,
   REGISTRY_FILE,
+  SchemaFormatConflict,
+  SchemaRejected,
   addRegistryEntry,
   clientFor,
   collectDslFields,
@@ -1099,9 +1244,11 @@ export {
   compareSchemas,
   computeStatus,
   deriveManifests,
+  diffSchemaKeys,
   findConfigFile,
   formatDriftWarning,
   formatManifest,
+  formatSchemaDiff,
   generatePropsSource,
   hasRegistry,
   importPathFor,
@@ -1121,9 +1268,12 @@ export {
   parseRegistry,
   parseZodSchema,
   pascalCase,
+  previewSchemaPush,
   propsInterfaceName,
   propsPath,
+  pullSchemas,
   pullSections,
+  pushSchema,
   pushSection,
   readConfigFile,
   readLock,
@@ -1134,6 +1284,7 @@ export {
   remoteForLock,
   safeJoin,
   schemaFieldNames,
+  schemaKeys,
   sectionStatuses,
   tsTypeForField,
   updateLock,