@remkoj/optimizely-cms-cli 5.2.0 → 5.3.0

package/dist/index.js

@@ -3,11 +3,12 @@ import dotenv from 'dotenv';
 import { expand } from 'dotenv-expand';
 import path from 'node:path';
 import fs from 'node:fs';
-import { getCmsIntegrationApiConfigFromEnvironment, createClient, OptiCmsVersion, IntegrationApi, ContentRoots } from '@remkoj/optimizely-cms-api';
+import { getCmsIntegrationApiConfigFromEnvironment, createClient, ContentBaseType, OptiCmsVersion, PropertyDataType, ContentRoots } from '@remkoj/optimizely-cms-api';
 import yargs from 'yargs';
 import chalk from 'chalk';
 import figures from 'figures';
 import Table from 'cli-table3';
+import { diff } from 'deep-object-diff';
 import fsAsync from 'node:fs/promises';
 import { input, select, confirm } from '@inquirer/prompts';
 
@@ -79,7 +80,7 @@ function createOptiCmsApp(scriptName, version, epilogue, envFiles, projectDir) {
             console.error(msg + "\n");
         if (error)
             console.error(`[${chalk.bold(error.name ?? 'Error')}]: ${error.message ?? ''}\n`);
-        args.showHelp("error");
+        //args.showHelp("error")
     });
 }
 function isDemanded(value) {
@@ -138,79 +139,6 @@ function createCmsClient(args) {
     return client;
 }
 
-const StylesPushCommand = {
-    command: "styles:push",
-    describe: "Push Visual Builder style definitions into the CMS (create/replace)",
-    builder: (yargs) => {
-        yargs.option('excludeTemplates', { alias: 'e', description: "Exclude these templates", string: true, type: 'array', demandOption: false, default: [] });
-        yargs.option("templates", { alias: 't', description: "Select only these templates", string: true, type: 'array', demandOption: false, default: [] });
-        return yargs;
-    },
-    handler: async (args) => {
-        const { _config: cfg, excludeTemplates, templates, ...opts } = parseArgs(args);
-        const client = createCmsClient(args);
-        if (client.runtimeCmsVersion == OptiCmsVersion.CMS12) {
-            process.stdout.write(chalk.gray(`${figures.cross} Styles are not supported on CMS12\n`));
-            return;
-        }
-        process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Pushing (create/replace) DisplayStyles into Optimizely CMS\n`));
-        const styleDefinitionFiles = await glob("./**/*.opti-style.json", {
-            cwd: opts.components
-        });
-        const results = (await Promise.all(styleDefinitionFiles.map(async (styleDefinitionFile) => {
-            const filePath = path.normalize(path.join(opts.components, styleDefinitionFile));
-            const styleDefinition = tryReadJsonFile(filePath, cfg.debug);
-            const styleKey = styleDefinition.key;
-            if (!styleKey) {
-                process.stderr.write(chalk.redBright(`${chalk.bold(figures.cross)} The style definition in ${path.relative(opts.path, filePath)} does not have a key defined\n`));
-                return undefined;
-            }
-            if (excludeTemplates.includes(styleKey))
-                return undefined; // Skip excluded styles
-            if (templates.length > 0 && !templates.includes(styleKey))
-                return undefined; // Only include defined styles, if any
-            if (cfg.debug)
-                process.stdout.write(chalk.gray(`${figures.arrowRight} Pushing: ${styleKey}\n`));
-            const newTemplate = await client.displayTemplates.displayTemplatesPut(styleKey, styleDefinition);
-            return newTemplate;
-        }))).filter(isNotNullOrUndefined);
-        const styles = new Table({
-            head: [
-                chalk.yellow(chalk.bold("Name")),
-                chalk.yellow(chalk.bold("Key")),
-                chalk.yellow(chalk.bold("Default")),
-                chalk.yellow(chalk.bold("Target"))
-            ],
-            colWidths: [31, 20, 9, 20],
-            colAligns: ["left", "left", "center", "left"]
-        });
-        results.forEach(tpl => {
-            styles.push([
-                tpl.displayName,
-                tpl.key,
-                tpl.isDefault ? figures.tick : figures.cross,
-                tpl.contentType ? `${tpl.contentType} (C)` : tpl.baseType ? `${tpl.baseType} (B)` : `${tpl.nodeType} (N)`
-            ]);
-        });
-        process.stdout.write(styles.toString() + "\n");
-        process.stdout.write(chalk.green(chalk.bold(figures.tick + " Done")) + "\n");
-    }
-};
-function tryReadJsonFile(filePath, debug = false) {
-    try {
-        if (debug)
-            process.stdout.write(chalk.gray(`${figures.arrowRight} Reading style definition from ${filePath}\n`));
-        return JSON.parse(fs.readFileSync(filePath, { encoding: 'utf-8' }));
-    }
-    catch (e) {
-        process.stderr.write(chalk.redBright(`${chalk.bold(figures.cross)} Error while reading ${filePath}\n`));
-    }
-    return undefined;
-}
-function isNotNullOrUndefined(i) {
-    return i ? true : false;
-}
-
 const ContentTypesArgsDefaults = {
     excludeBaseTypes: [],
     excludeTypes: ['folder', 'media', 'image', 'video'],
@@ -250,7 +178,7 @@ async function getContentTypes(client, args, pageSize = 100, allowSystem = false
         process.stdout.write(chalk.gray(`${figures.arrowRight} Fetched ${results.length} Content-Types from Optimizely CMS\n`));
         process.stdout.write(chalk.gray(`${figures.arrowRight} Filtering Content-Types based upon arguments\n`));
     }
-    const validBaseTypes = getEnumOptions(IntegrationApi.ContentBaseType).map(x => x.toLowerCase());
+    const validBaseTypes = getEnumOptions(ContentBaseType).map(x => x.toLowerCase());
     if (cfg.debug)
         process.stdout.write(`Allowing base types: ${validBaseTypes.join(', ')}\n`);
     const allContentTypes = all ?
@@ -409,6 +337,269 @@ async function getStyleFilePath(definition, opts) {
     throw new Error(`Unable to resolve the target for the DisplayTemplate: ${definition.key}`);
 }
 
+function normalizeMergePatch(value, omitKeys, requiredKeys = [], requiredSource) {
+    if (value === undefined || value === null)
+        return null;
+    if (Array.isArray(value))
+        return value.map(item => normalizeMergePatch(item, omitKeys));
+    if (typeof value !== 'object')
+        return value;
+    const output = Object.entries(value).reduce((acc, [key, entry]) => {
+        if (!omitKeys.includes(key))
+            acc[key] = normalizeMergePatch(entry, omitKeys);
+        return acc;
+    }, {});
+    const withRequiredKeys = requiredKeys.reduce((acc, key) => {
+        if (requiredSource && !Object.keys(acc).includes(key))
+            acc[key] = requiredSource[key];
+        return acc;
+    }, output);
+    return withRequiredKeys;
+}
+/**
+ * Computes a JSON Merge Patch (RFC 7396) that transforms `currentValue` into `newValue`.
+ *
+ * The resulting patch can be sent directly as the request body of an `application/merge-patch+json`
+ * request. Changed and added properties are included with their new value; removed properties are
+ * included with a `null` value (as required by RFC 7396); unchanged properties are omitted entirely.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7396
+ *
+ * @example Basic usage
+ * ```ts
+ * const current = { name: 'Alice', age: 30, role: 'user' }
+ * const updated = { name: 'Alice', age: 31 }
+ *
+ * generatePatch(current, updated)
+ * // => { age: 31, role: null }
+ * //   `age` is replaced, `role` is removed (null), `name` is unchanged (omitted)
+ * ```
+ *
+ * @example Excluding keys from the patch
+ * ```ts
+ * const current = { id: '123', name: 'Alice', version: 1 }
+ * const updated = { id: '123', name: 'Bob',   version: 2 }
+ *
+ * generatePatch(current, updated, { readonlyFields: ['id', 'version'] })
+ * // => { name: 'Bob' }
+ * //   `id` and `version` are excluded even though they are present in the diff
+ * ```
+ *
+ * @example Always include required fields
+ * ```ts
+ * const current = { id: '123', name: 'Alice', version: 1 }
+ * const updated = { id: '123', name: 'Alice', version: 2 }
+ *
+ * generatePatch(current, updated, { requiredFields: ['id'] })
+ * // => { id: '123', version: 2 }
+ * //   `id` is included even though it did not change
+ * ```
+ *
+ * @example Nested objects
+ * ```ts
+ * const current = { address: { city: 'Amsterdam', zip: '1000AA' } }
+ * const updated = { address: { city: 'Utrecht' } }
+ *
+ * generatePatch(current, updated)
+ * // => { address: { city: 'Utrecht', zip: null } }
+ * ```
+ *
+ * @param currentValue - The current state of the resource.
+ * @param newValue     - The desired state of the resource.
+ * @param options      - Optional configuration.
+ * @param options.readonlyFields - Keys that should never appear in the generated patch,
+ *                           regardless of whether they changed.
+ * @param options.requiredFields - Keys that should always appear in the generated patch,
+ *                           using values from `newValue`.
+ * @returns A {@link MergePatch} object ready to be serialised as an `application/merge-patch+json` body.
+ */
+function generatePatch(currentValue, newValue, options = {}) {
+    const requiredKeys = options.requiredFields ?? [];
+    const omitKeys = (options.readonlyFields ?? []).filter(key => !requiredKeys.includes(key));
+    const patch = diff(currentValue, newValue);
+    return normalizeMergePatch(patch, omitKeys, requiredKeys, newValue);
+}
+/**
+ * Extracts all field paths from a {@link MergePatch} as dot-separated strings.
+ * Nested objects are flattened recursively; leaf values (including `null`) produce a path entry.
+ *
+ * @example
+ * ```ts
+ * getPatchFields({ a: { b: 0 }, c: 'value' })
+ * // => ['a.b', 'c']
+ * ```
+ *
+ * @param patch  - The merge patch to extract fields from.
+ * @param prefix - Internal prefix used during recursion; omit when calling directly.
+ * @returns An array of dot-separated field path strings.
+ */
+function getPatchFields(patch, prefix = '') {
+    return Object.entries(patch).flatMap(([key, value]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        return typeof value === 'object' && value !== null && !Array.isArray(value)
+            ? getPatchFields(value, path)
+            : [path];
+    });
+}
+
+/**
+ * CLI command that synchronizes local `.opti-style.json` definitions with Optimizely CMS.
+ *
+ * Existing styles are patched, missing styles are created, and command options allow
+ * selecting or excluding template keys during the push.
+ */
+const StylesPushCommand = {
+    command: 'styles:push',
+    describe: 'Push Visual Builder style definitions into the CMS (create/patch)',
+    builder: (yargs) => {
+        yargs.option('excludeTemplates', {
+            alias: 'e',
+            description: 'Exclude these templates',
+            string: true,
+            type: 'array',
+            demandOption: false,
+            default: [],
+        });
+        yargs.option('templates', {
+            alias: 't',
+            description: 'Select only these templates',
+            string: true,
+            type: 'array',
+            demandOption: false,
+            default: [],
+        });
+        return yargs;
+    },
+    handler: async (args) => {
+        const { _config: { debug = false }, excludeTemplates, templates, ...opts } = parseArgs(args);
+        const client = createCmsClient(args);
+        if (client.runtimeCmsVersion == OptiCmsVersion.CMS12) {
+            process.stdout.write(chalk.gray(`${figures.cross} Styles are not supported on CMS12\n`));
+            return;
+        }
+        const { styles: displayTemplates } = await getStyles(client, {
+            // Defaults
+            all: true,
+            baseTypes: [],
+            excludeBaseTypes: [],
+            excludeNodeTypes: [],
+            excludeTemplates: [],
+            excludeTypes: [],
+            nodes: [],
+            templates: [],
+            templateTypes: [],
+            types: [],
+            // Arguments from this method
+            ...args,
+        }, 50);
+        process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Pushing (create/patch) DisplayStyles into Optimizely CMS\n`));
+        // Listing all style files
+        const styleDefinitionFiles = await glob('./**/*.opti-style.json', {
+            cwd: opts.components,
+        });
+        // Helper function to read the files from disk
+        function readStyleFile(styleDefinitionFile) {
+            const filePath = path.normalize(path.join(opts.components, styleDefinitionFile));
+            const styleDefinition = tryReadJsonFile(filePath, debug);
+            return styleDefinition ? {
+                styleKey: styleDefinition.key,
+                styleDefinition,
+                styleFile: filePath
+            } : undefined;
+        }
+        // Helper function to filter the files read from disk
+        function filterStyleDefinition(data) {
+            if (!data || !data.styleKey)
+                return false;
+            const { styleKey } = data;
+            if (excludeTemplates.includes(styleKey)) {
+                if (debug)
+                    process.stdout.write(chalk.gray(`${figures.arrowRight} Skipping ${styleKey} - explicitly excluded\n`));
+                return false;
+            }
+            // Skip if there a selectin and this template is not in it
+            if (templates.length > 0 && !templates.includes(styleKey)) {
+                if (debug)
+                    process.stdout.write(chalk.gray(`${figures.arrowRight} Skipping ${styleKey} - not in selected list of templates\n`));
+                return false; // Only include defined styles, if any
+            }
+            return true;
+        }
+        // Processing each file
+        const results = await Promise.allSettled(styleDefinitionFiles
+            .map(readStyleFile)
+            .filter(filterStyleDefinition)
+            .map(async ({ styleKey, styleDefinition, styleFile }) => {
+            const displayTemplate = displayTemplates.find(dt => dt.key === styleKey);
+            // Confirm we're including
+            process.stdout.write(chalk.yellowBright(`${figures.arrowRight} ${displayTemplate ? 'Updating' : 'Creating'} ${styleKey}\n`));
+            if (debug)
+                process.stdout.write(chalk.gray(`${figures.arrowRight} from ${styleFile || 'unknown source'}\n`));
+            // Patch or create the template
+            const newTemplate = await (displayTemplate ? (async () => {
+                const patch = generatePatch(displayTemplate, styleDefinition, {
+                    readonlyFields: ['key', 'created', 'createdBy', 'lastModified', 'lastModifiedBy'],
+                });
+                if (!path || Object.entries(patch).length === 0)
+                    return displayTemplate;
+                // @ts-expect-error: We're expecting an error here due to the CMS Logic not matching 
+                // the OpenAPI Specification.
+                return client.displayTemplates.displayTemplatesPatch(styleKey, patch);
+            })() : client.displayTemplates.displayTemplatesCreate(displayTemplate));
+            // Validate the result
+            const unpatchedFields = generatePatch(newTemplate, styleDefinition, {
+                readonlyFields: ['key', 'created', 'createdBy', 'lastModified', 'lastModifiedBy']
+            });
+            if (unpatchedFields && Object.entries(unpatchedFields).length > 0)
+                throw new Error(`Creating/patching of displayTemplate failed, the following fields failed: ${getPatchFields(unpatchedFields).join('; ')}`);
+            // Return the template after Create/Patch
+            return newTemplate;
+        }));
+        const styles = new Table({
+            head: [
+                chalk.yellow(chalk.bold('Name')),
+                chalk.yellow(chalk.bold('Key')),
+                chalk.yellow(chalk.bold('Default')),
+                chalk.yellow(chalk.bold('Target')),
+            ],
+            colWidths: [31, 20, 9, 20],
+            colAligns: ['left', 'left', 'center', 'left'],
+        });
+        results.forEach((result) => {
+            if (result.status === 'fulfilled') {
+                const tpl = result.value;
+                styles.push([
+                    tpl.displayName,
+                    tpl.key,
+                    tpl.isDefault ? figures.tick : figures.cross,
+                    tpl.contentType
+                        ? `${tpl.contentType} (C)`
+                        : tpl.baseType
+                            ? `${tpl.baseType} (B)`
+                            : `${tpl.nodeType} (N)`,
+                ]);
+            }
+            else {
+                const error = result.reason;
+                process.stderr.write(`Error creating/updating style: ${error}`);
+            }
+        });
+        process.stdout.write(styles.toString() + '\n');
+        process.stdout.write(chalk.green(chalk.bold(figures.tick + ' Done')) + '\n');
+    },
+};
+function tryReadJsonFile(filePath, debug = false) {
+    try {
+        if (debug)
+            process.stdout.write(chalk.gray(`${figures.arrowRight} Reading style definition from ${filePath}\n`));
+        return JSON.parse(fs.readFileSync(filePath, { encoding: 'utf-8' }));
+    }
+    catch (e) {
+        process.stderr.write(chalk.redBright(`${chalk.bold(figures.cross)} Error while reading ${filePath}\n`));
+    }
+    return undefined;
+}
+
 const StylesListCommand = {
     command: "styles:list",
     describe: "List Visual Builder style definitions from the CMS",
@@ -864,7 +1055,7 @@ const TypesPullCommand = {
 
 const TypesPushCommand = {
     command: "types:push",
-    describe: "Push content type definition into Optimizely CMS (create / replace)",
+    describe: "Push content type definition into Optimizely CMS (create / patch)",
     builder: (yargs) => {
         yargs.option('force', { alias: 'f', description: "Overwrite existing files", boolean: true, type: 'boolean', demandOption: false, default: false });
         yargs.option('excludeTypes', { alias: 'ect', description: "Exclude these content types", string: true, type: 'array', demandOption: false, default: [] });
@@ -877,7 +1068,7 @@ const TypesPushCommand = {
         const { _config: cfg, components: basePath, excludeBaseTypes, excludeTypes, baseTypes, types, force } = parseArgs(args);
         const client = createClient(cfg);
         // Find all type files
-        process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Pushing (create/replace) Content Types into Optimizely CMS\n`));
+        process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Pushing (create/patch) Content Types into Optimizely CMS\n`));
         const typeDefinitionFiles = await glob("./**/*.opti-type.json", { cwd: basePath });
         // Read & filter all identified type files
         const typeDefinitions = typeDefinitionFiles.map(file => {
@@ -907,7 +1098,7 @@ const TypesPushCommand = {
                 delete outType.features;
             if (outType.usage)
                 delete outType.usage;
-            return client.contentTypes.contentTypesPut(outType.key, outType, force)
+            return client.contentTypes.contentTypesPatch(outType.key, outType, force)
                 .then(ct => { return { key: type.definition.key, type: ct, file: type.file }; })
                 .catch(e => { return { key: type.definition.key, type: type.definition, file: type.file, error: e }; });
         }));
@@ -1090,11 +1281,11 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
         const propName = isConflict ? `${contentType.key}${propKey}: ${propKey}` : propKey;
         // Write the property
         switch (propType) {
-            case IntegrationApi.PropertyDataType.ARRAY:
+            case PropertyDataType.ARRAY:
                 {
                     const typeData = typeProps[propKey];
                     switch (typeData.items.type) {
-                        case IntegrationApi.PropertyDataType.INTEGER:
+                        case PropertyDataType.INTEGER:
                             if (typeData.format == 'categorization') {
                                 //fragmentFields.push(`${propName} { Id, Name, Description }`)
                                 console.warn(chalk.redBright(`❗ Property ${propName} is a 'categorization', this is not supported. If you need to use this property, add it manually into the generated files`));
@@ -1102,16 +1293,16 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
                             else
                                 fragmentFields.push(propName);
                             break;
-                        case IntegrationApi.PropertyDataType.STRING:
+                        case PropertyDataType.STRING:
                             fragmentFields.push(propName);
                             break;
-                        case IntegrationApi.PropertyDataType.CONTENT:
+                        case PropertyDataType.CONTENT:
                             if (contentType.baseType == 'page' || contentType.baseType == 'experience')
                                 fragmentFields.push(`${propName} { ...${forCms12 ? 'PageIContentListItem' : 'BlockData'} }`);
                             else
                                 fragmentFields.push(`${propName} { ...IContentListItem }`);
                             break;
-                        case IntegrationApi.PropertyDataType.COMPONENT:
+                        case PropertyDataType.COMPONENT:
                             const componentType = typeData.items.contentType.split(':').pop();
                             switch (componentType) {
                                 case 'link':
@@ -1126,7 +1317,7 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
                                     }
                             }
                             break;
-                        case IntegrationApi.PropertyDataType.CONTENT_REFERENCE:
+                        case PropertyDataType.CONTENT_REFERENCE:
                             fragmentFields.push(`${propName} { ...ReferenceData }`);
                             break;
                         default:
@@ -1135,7 +1326,7 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
                     }
                     break;
                 }
-            case IntegrationApi.PropertyDataType.STRING: {
+            case PropertyDataType.STRING: {
                 const propDetails = typeProps[propKey];
                 switch (propDetails.format ?? "") {
                     case 'html':
@@ -1153,13 +1344,13 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
                 }
                 break;
             }
-            case IntegrationApi.PropertyDataType.URL:
+            case PropertyDataType.URL:
                 fragmentFields.push(forCms12 ? propName : `${propName} { ...LinkData }`);
                 break;
-            case IntegrationApi.PropertyDataType.CONTENT_REFERENCE:
+            case PropertyDataType.CONTENT_REFERENCE:
                 fragmentFields.push(`${propName} { ...ReferenceData }`);
                 break;
-            case IntegrationApi.PropertyDataType.COMPONENT: {
+            case PropertyDataType.COMPONENT: {
                 const componentType = typeProps[propKey].contentType.split(':').pop();
                 if (componentType == "link") {
                     fragmentFields.push(`${propName} { ...LinkItemData }`);
@@ -1171,10 +1362,10 @@ function renderProperties(contentType, generatedProps = [], forCms12 = false) {
                 }
                 break;
             }
-            case IntegrationApi.PropertyDataType.BINARY:
+            case PropertyDataType.BINARY:
                 fragmentFields.push(propName);
                 break;
-            case IntegrationApi.PropertyDataType.CONTENT:
+            case PropertyDataType.CONTENT:
                 fragmentFields.push(`${propName} { ...${forCms12 ? 'PageIContentListItem' : 'BlockData'} }`);
                 break;
             default:
@@ -2169,7 +2360,7 @@ const commands = [
     CmsVersionCommand
 ];
 
-var version = "5.2.0";
+var version = "5.3.0";
 var name = "opti-cms";
 var APP = {
 	version: version,