@remkoj/optimizely-cms-cli 6.0.0-rc.1 → 6.0.0-rc.4

package/dist/index.js

@@ -1,16 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Developer Utitility providing helpers for common tasks to building a
+ * frontend application that uses Optimizely CMS/Graph as content repository.
+ * 
+ * License: Apache 2
+ * Copyright (c) 2023-2026 - Remko Jantzen
+ */
+
 import { globSync, glob, globIterate } from 'glob';
 import { config } from 'dotenv';
 import { expand } from 'dotenv-expand';
 import path from 'node:path';
 import fs from 'node:fs';
-import { readPartialEnvConfig, createClient, OptiCmsVersion, ContentRoots } from '@remkoj/optimizely-cms-api';
+import { readPartialEnvConfig, createClient, ContentRoots } from '@remkoj/optimizely-cms-api';
 import yargs from 'yargs';
 import chalk from 'chalk';
 import figures from 'figures';
 import Table from 'cli-table3';
 import slugify from '@sindresorhus/slugify';
 import { diff } from 'deep-object-diff';
-import fsAsync from 'node:fs/promises';
+import fs$1 from 'node:fs/promises';
 import { input, select, confirm } from '@inquirer/prompts';
 import createDeepMerge from '@fastify/deepmerge';
 import { Ajv } from 'ajv';
@@ -209,10 +218,12 @@ function getStyleFilePathsSync(displayTemplate, contentBaseType = '_Component',
             target = displayTemplate.nodeType;
             break;
         case 'component':
-            const baseType = contentBaseType;
-            target = displayTemplate.contentType;
-            groupPath = path.join(keyToSlug(baseType, { stripLeadingUnderscore: true }), keyToSlug(displayTemplate.contentType, { stripLeadingGroup: true }));
-            break;
+            {
+                const baseType = contentBaseType;
+                target = displayTemplate.contentType;
+                groupPath = path.join(keyToSlug(baseType, { stripLeadingUnderscore: true }), keyToSlug(displayTemplate.contentType, { stripLeadingGroup: true }));
+                break;
+            }
         default:
             throw new Error(`Unsupported DisplayTemplate target for ${displayTemplate.key}`);
     }
@@ -230,7 +241,7 @@ function getStyleFilePathsSync(displayTemplate, contentBaseType = '_Component',
     };
 }
 async function getStyleFilePaths(definition, opts) {
-    let defintionBaseType = undefined;
+    let defintionBaseType;
     if (definition.contentType && !opts.contentBaseType && opts.client) {
         const contentType = await opts.client.contentTypesGet({ path: { key: definition.contentType } }).catch(() => undefined);
         defintionBaseType = contentType?.baseType;
@@ -340,7 +351,7 @@ function isFolder(contentType) {
  * Test if the provided content type is a system type
  *
  * @param     contentType     The ContentType to test
- * @returns   `true` if the ContentType is a folder, `false` otherwise
+ * @returns   `true` if the ContentType is a system type, `false` otherwise
  * @see {@link IntegrationApi.ContentType}
  */
 function isSystemType(contentType) {
@@ -348,12 +359,30 @@ function isSystemType(contentType) {
         return false;
     return contentType.source === 'system';
 }
+/**
+ * Type guard that returns `true` when `toTest` is a non-empty array.
+ *
+ * @param toTest The value to inspect.
+ * @returns `true` when `toTest` is an `Array` with at least one element.
+ */
 function isNonEmptyArray(toTest) {
     return Array.isArray(toTest) && toTest.length > 0;
 }
+/**
+ * Type guard that returns `true` when `toTest` is `null`, `undefined`, or an empty array.
+ *
+ * @param toTest The value to inspect.
+ * @returns `true` when `toTest` is `null` or an `Array` with no elements.
+ */
 function isEmptyArray(toTest) {
     return toTest === null || !Array.isArray(toTest) || toTest.length === 0;
 }
+/**
+ * Type guard that returns `true` when `toTest` is neither `null` nor `undefined`.
+ *
+ * @param toTest The value to inspect.
+ * @returns `true` when `toTest` is a defined, non-null value of type `T`.
+ */
 function isDefined(toTest) {
     return toTest !== null && toTest !== undefined;
 }
@@ -441,25 +470,28 @@ async function* getAllContentTypes(client, debug = false, pageSize = 25) {
     process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Pulling Content Types from Optimizely CMS\n`));
     let requestPageSize = pageSize;
     let requestPageIndex = 0;
-    let totalItemCount = 0;
-    let totalPages = 0;
+    let totalItemCount;
+    let totalPages;
     do {
-        const resultsPage = await client.contentTypesList({ query: { pageIndex: requestPageIndex, pageSize: requestPageSize } }).catch((_) => {
+        const resultsPage = await client.contentTypesList({ query: { pageIndex: requestPageIndex, pageSize: requestPageSize } }).catch(() => {
             return {
                 items: [],
                 totalItemCount: 0,
+                totalCount: 0,
                 pageIndex: requestPageIndex,
                 pageSize: requestPageSize
             };
         });
+        console.log(resultsPage);
         // Calculate fields for next page
-        totalItemCount = resultsPage.totalItemCount ?? 0;
+        //@ts-expect-error  There's a difference between the SaaS & PaaS API, hence we're ignoring the next line
+        totalItemCount = resultsPage.totalItemCount ?? resultsPage.totalCount ?? 0;
         requestPageSize = resultsPage.pageSize;
         requestPageIndex = resultsPage.pageIndex + 1;
         totalPages = Math.ceil(totalItemCount / requestPageSize);
         // Debug output
         if (debug)
-            process.stdout.write(chalk.gray(`${figures.arrowRight} Fetched contentTypes page ${requestPageIndex} of ${totalPages} (${requestPageSize} items per page)\n`));
+            process.stdout.write(chalk.gray(`${figures.arrowRight} Fetched contentTypes page ${requestPageIndex} of ${totalPages} (${requestPageSize} items per page, ${totalItemCount} items available)\n`));
         // Yield items
         for (const contentType of (resultsPage.items ?? [])) {
             yield contentType;
@@ -543,10 +575,10 @@ async function getStyles(client, args, pageSize = 25) {
 async function* getAllStyles(client, debug = false, pageSize = 5) {
     let requestPageSize = pageSize;
     let requestPageIndex = 0;
-    let totalItemCount = 0;
-    let totalPages = 0;
+    let totalItemCount;
+    let totalPages;
     do {
-        const resultsPage = await client.displayTemplatesList({ query: { pageIndex: requestPageIndex, pageSize: requestPageSize } }).catch((_) => {
+        const resultsPage = await client.displayTemplatesList({ query: { pageIndex: requestPageIndex, pageSize: requestPageSize } }).catch(() => {
             return {
                 items: [],
                 totalItemCount: 0,
@@ -555,13 +587,14 @@ async function* getAllStyles(client, debug = false, pageSize = 5) {
             };
         });
         // Calculate fields for next page
-        totalItemCount = resultsPage.totalItemCount ?? 0;
+        //@ts-expect-error Difference between PaaS & SaaS
+        totalItemCount = resultsPage.totalItemCount ?? resultsPage.totalCount ?? 0;
         requestPageSize = resultsPage.pageSize;
         requestPageIndex = resultsPage.pageIndex + 1;
         totalPages = Math.ceil(totalItemCount / requestPageSize);
         // Debug output
         if (debug)
-            process.stdout.write(chalk.gray(`${figures.arrowRight} Fetched displayTemplates page ${requestPageIndex} of ${totalPages} (${requestPageSize} items per page)\n`));
+            process.stdout.write(chalk.gray(`${figures.arrowRight} Fetched displayTemplates page ${requestPageIndex} of ${totalPages} (${requestPageSize} items per page, ${totalItemCount} items available)\n`));
         // Yield items
         for (const displayTemplate of (resultsPage.items ?? [])) {
             yield displayTemplate;
@@ -624,7 +657,7 @@ async function toTypeFilesList(displayTemplates, client, basePath) {
     return new TypeFilesList();
 }
 
-function normalizeMergePatch(value, omitKeys, requiredKeys = [], requiredSource) {
+function normalizeMergePatch(value, omitKeys, requiredKeys = [], requiredSource, atomicKeys = []) {
     if (value === undefined || value === null)
         return null;
     if (Array.isArray(value))
@@ -632,8 +665,15 @@ function normalizeMergePatch(value, omitKeys, requiredKeys = [], requiredSource)
     if (typeof value !== 'object')
         return value;
     const output = Object.entries(value).reduce((acc, [key, entry]) => {
-        if (!omitKeys.includes(key))
-            acc[key] = normalizeMergePatch(entry, omitKeys);
+        if (!omitKeys.includes(key)) {
+            if (atomicKeys.includes(key) && requiredSource !== undefined) {
+                // Include the full value from newValue verbatim — do not recurse into the diff
+                acc[key] = requiredSource[key];
+            }
+            else {
+                acc[key] = normalizeMergePatch(entry, omitKeys);
+            }
+        }
         return acc;
     }, {});
     const withRequiredKeys = requiredKeys.reduce((acc, key) => {
@@ -698,13 +738,18 @@ function normalizeMergePatch(value, omitKeys, requiredKeys = [], requiredSource)
  *                           regardless of whether they changed.
  * @param options.requiredFields - Keys that should always appear in the generated patch,
  *                           using values from `newValue`.
+ * @param options.atomicFields  - Keys whose values are always included verbatim when they
+ *                           change, rather than being recursively patched. Use for
+ *                           record- or dictionary-typed properties (e.g.
+ *                           `{ [key: string]: SomeObject }`) and arrays of objects.
  * @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 atomicKeys = (options.atomicFields ?? []);
     const patch = diff(currentValue, newValue);
-    return normalizeMergePatch(patch, omitKeys, requiredKeys, newValue);
+    return normalizeMergePatch(patch, omitKeys, requiredKeys, newValue, atomicKeys);
 }
 /**
  * Extracts all field paths from a {@link MergePatch} as dot-separated strings.
@@ -776,18 +821,17 @@ const StylesPushCommand = {
             // Create / Replace the current template
             const newTemplate = await (currentTemplate ? (async () => {
                 const patch = generatePatch(currentTemplate, styleDefinition, {
-                    readonlyFields: ['key', 'created', 'lastModified', 'createdBy', 'lastModifiedBy']
+                    readonlyFields: ['key', 'created', 'lastModified', 'createdBy', 'lastModifiedBy'],
+                    atomicFields: ['settings']
                 });
                 if (!path || Object.entries(patch).length === 0)
                     return currentTemplate;
-                // @ts-expect-error There's a mis-match between the logic in the CMS and the contents of the 
-                // OpenAPI Spec file.
                 return client.displayTemplatesPatch({ path: { key: styleKey }, body: patch });
             })() :
                 client.displayTemplatesCreate({ body: styleDefinition }));
-            const missedFields = generatePatch(newTemplate, currentTemplate, {
+            const missedFields = newTemplate ? generatePatch(newTemplate, currentTemplate, {
                 readonlyFields: ['key', 'created', 'lastModified', 'createdBy', 'lastModifiedBy']
-            });
+            }) : undefined;
             if (missedFields && Object.keys(missedFields).length > 0)
                 throw new Error(`The Display template ${styleKey} failed to update properties: ${getPatchFields(missedFields).join('; ')}`);
             return newTemplate;
@@ -804,16 +848,21 @@ const StylesPushCommand = {
         });
         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)`
-                ]);
+                if (isDefined(result.value)) {
+                    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 {
+                    process.stderr.write(`DisplayTemplate pushed without errors, but no result was returned.\n`);
+                }
             }
             else {
-                process.stderr.write(`Error processing DisplayTemplate: ${result.reason}\n`);
+                process.stderr.write(`Error processing DisplayTemplate: ${result.reason ?? "n"}\n`);
             }
         });
         process.stdout.write(styles.toString() + "\n");
@@ -826,7 +875,7 @@ function tryReadJsonFile(filePath, debug = false) {
             process.stdout.write(chalk.gray(`${figures.arrowRight} Reading style definition from ${filePath}\n`));
         return JSON.parse(fs.readFileSync(filePath, { encoding: 'utf-8' }));
     }
-    catch (e) {
+    catch {
         process.stderr.write(chalk.redBright(`${chalk.bold(figures.cross)} Error while reading ${filePath}\n`));
     }
     return undefined;
@@ -837,10 +886,6 @@ const StylesListCommand = {
     describe: "List Visual Builder style definitions from the CMS",
     handler: async (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 { all: results } = await getStyles(client, { ...args, excludeBaseTypes: [], excludeNodeTypes: [], excludeTemplates: [], excludeTypes: [], baseTypes: [], nodes: [], templates: [], types: [], templateTypes: [], all: false });
         const styles = new Table({
             head: [
@@ -893,7 +938,7 @@ const StylesPullCommand = {
             const displayTemplateGroup = styleFiles.get(groupIdentifier);
             for (const { file: filePath, data: displayTemplate } of (displayTemplateGroup?.templates || [])) {
                 // Write JSON to disk
-                var updatedJson = await createDisplayTemplateFile(displayTemplate, filePath, force, cfg.debug);
+                const updatedJson = await createDisplayTemplateFile(displayTemplate, filePath, force, cfg.debug);
                 if (updatedJson)
                     updatedTemplates.push(displayTemplate.key);
             }
@@ -940,7 +985,7 @@ async function createDisplayTemplateFile(displayTemplate, filePath, force = fals
 async function createDisplayTemplateHelper(typeFile, typeFileId, force = false, debug = false) {
     const prefix = '//not-modified - Remove this line when making change to prevent it from being updated by the CLI tools';
     const { filePath: typeFilePath, templates } = typeFile;
-    const shouldWrite = await fsAsync.readFile(typeFilePath, { encoding: "utf-8" }).then(data => data.startsWith('//not-modified')).catch((e) => {
+    const shouldWrite = await fs$1.readFile(typeFilePath, { encoding: "utf-8" }).then(data => data.startsWith('//not-modified')).catch((e) => {
         if (e?.code === 'ENOENT')
             return true;
         if (debug)
@@ -1004,7 +1049,7 @@ export function is${t.data.key}Props(props?: ${typeId}LayoutProps | null) : prop
 }`);
         });
     }
-    void await fsAsync.writeFile(typeFilePath, prefix + "\n" + imports.join("\n") + "\n\n" + typeContents.join("\n"));
+    void await fs$1.writeFile(typeFilePath, prefix + "\n" + imports.join("\n") + "\n\n" + typeContents.join("\n"));
     return true;
 }
 
@@ -1132,12 +1177,12 @@ const StylesDeleteCommand = {
             // Remove style file
             if (args.withStyleFile) {
                 process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Removing *.opti-style.json file for ${displayTemplate.displayName} [${displayTemplate.key}]\n`));
-                await fsAsync.rm(styleFilePath, { force: false, recursive: false, maxRetries: 1 }).catch((e) => {
+                await fs$1.rm(styleFilePath, { force: false, recursive: false, maxRetries: 1 }).catch((e) => {
                     if (e?.code === 'ENOENT') // The file can't be deleted as it does not exist - that's the desired state
                         return;
                     throw e;
                 });
-                await fsAsync.rmdir(itemPath, { recursive: false, maxRetries: 1 }).catch((e) => {
+                await fs$1.rmdir(itemPath, { recursive: false, maxRetries: 1 }).catch((e) => {
                     if (e?.code === 'ENOTEMPTY') {
                         process.stdout.write(chalk.yellowBright(`${figures.warning} The folder is not empty, please remove ${itemPath} manually if needed\n`));
                         return;
@@ -1153,12 +1198,12 @@ const StylesDeleteCommand = {
                 process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Removing/updating displayTemplates.ts file for ${displayTemplate.displayName} [${displayTemplate.key}]\n`));
                 const remainingTemplates = styleHelpers[targetType].templates.filter(x => !keysToDelete.includes(x.key));
                 if (remainingTemplates.length === 0) {
-                    await fsAsync.rm(styleHelpers[targetType].filePath, { force: false, recursive: false, maxRetries: 1 }).catch((e) => {
+                    await fs$1.rm(styleHelpers[targetType].filePath, { force: false, recursive: false, maxRetries: 1 }).catch((e) => {
                         if (e?.code === 'ENOENT') // The file can't be deleted as it does not exist - that's the desired state
                             return;
                         throw e;
                     });
-                    await fsAsync.rmdir(typesPath, { recursive: false, maxRetries: 1 }).catch((e) => {
+                    await fs$1.rmdir(typesPath, { recursive: false, maxRetries: 1 }).catch((e) => {
                         if (e?.code === 'ENOTEMPTY') {
                             process.stdout.write(chalk.yellowBright(`${figures.warning} The folder is not empty, please remove ${typesPath} manually if needed\n`));
                             return;
@@ -1716,10 +1761,11 @@ ${varName}.getMetaData = async (contentLink, locale, client) => {
 
 export default ${varName}`,
     // Template for all experience component types
-    experience: (contentType, varName, displayTemplate) => `import { type OptimizelyNextPage as CmsComponent } from "@remkoj/optimizely-cms-nextjs";
+    experience: (contentType, varName, displayTemplate) => `import 'server-only'
+import { type OptimizelyNextPage as CmsComponent } from "@remkoj/optimizely-cms-nextjs";
 import { ExperienceDataFragmentDoc, get${contentType.key}DataDocument, type get${contentType.key}DataQuery } from '@/gql/graphql'
 import { getFragmentData } from '@/gql/fragment-masking'
-import { OptimizelyComposition, isNode, CmsEditable } from "@remkoj/optimizely-cms-react/rsc";${displayTemplate ? `
+import { OptimizelyComposition, isNode, CmsEditable, type ServerContext } from "@remkoj/optimizely-cms-react/rsc";${displayTemplate ? `
 import { ${displayTemplate} } from "./displayTemplates";` : ''}
 import { getSdk } from "@/gql/client"
 
@@ -1735,7 +1781,7 @@ import { getSdk } from "@/gql/client"
  * [Documentation: Customizing queries](https://github.com/remkoj/optimizely-dxp-clients/blob/main/packages/optimizely-graph-functions/docs/customizing_queries.md)
  */
 export const ${varName} : CmsComponent<get${contentType.key}DataQuery${displayTemplate ? ', ' + displayTemplate : ''}> = ({ data${displayTemplate ? ', layoutProps' : ''}, ctx }) => {
-  if (ctx) ctx.editableContentIsExperience = true
+  if (ctx) (ctx as ServerContext).setEditableContentIsExperience(true)
   const composition = getFragmentData(ExperienceDataFragmentDoc, data).composition
   const componentName = '${contentType.displayName}'
   const componentInfo = '${contentType.description?.replaceAll("'", "\\'") ?? ''}'
@@ -1915,8 +1961,8 @@ const NextJsFactoryCommand = {
         // Build factory / component structure
         const componentFactoryDefintions = new Map();
         components.forEach(component => {
-            const componentDir = path.dirname(path.join(...component));
-            path.basename(path.join(...component));
+            const componentDir = path.dirname(path.posix.join(...component));
+            // const componentFile = path.basename(path.posix.join(...component));
             // Determine component target
             const componentKey = getComponentKey(component, basePath);
             let componentVariant = (component.length > 1 ? component.at(component.length - 1) ?? 'default' : 'default').replace('index', 'default');
@@ -2050,12 +2096,12 @@ function shouldWriteFactory(factoryFile, force = false, debug = false) {
 function processName(input) {
     if (input == ROOT_FACTORY_KEY)
         return "Cms";
-    const nameSegements = input.split(/[-\_]/g);
+    const nameSegements = input.split(/[-_]/g);
     return nameSegements.map(ucFirst).join('');
 }
 function generateFactory(factoryInfo, factoryKey) {
     // Get the factory name
-    const factoryName = factoryKey.split(path.sep).map(processName).join("") + "Factory";
+    const factoryName = factoryKey.split(path.posix.sep).map(processName).join("") + "Factory";
     // Get the components and sub-factories, sorted by key to minimize changes between runs
     const components = [...factoryInfo.entries].sort((a, b) => { return a.key < b.key ? -1 : a.key > b.key ? 1 : 0; });
     const subFactories = [...factoryInfo.subfactories].sort((a, b) => { return a.key < b.key ? -1 : a.key > b.key ? 1 : 0; });
@@ -2371,12 +2417,12 @@ const SchemaDownloadCommand = {
         const fullSchemaDir = path.normalize(path.join(projectPath, schemaDir));
         const relativeSchemaDir = path.relative(projectPath, fullSchemaDir);
         process.stdout.write(`\n${figures.arrowRight} Validating schema folder ${relativeSchemaDir}\n`);
-        const schemaDirInfo = await fsAsync.stat(fullSchemaDir).catch((e) => { if (e.code == 'ENOENT')
+        const schemaDirInfo = await fs$1.stat(fullSchemaDir).catch((e) => { if (e.code == 'ENOENT')
             return undefined;
         else
             throw e; });
         if (!schemaDirInfo) {
-            await fsAsync.mkdir(fullSchemaDir, { recursive: true });
+            await fs$1.mkdir(fullSchemaDir, { recursive: true });
         }
         else if (!schemaDirInfo.isDirectory()) {
             process.stderr.write(chalk.redBright(chalk.bold(`${figures.cross} [Error] The schema directory exists, but is not a directory (${relativeSchemaDir})\n`)));
@@ -2389,7 +2435,7 @@ const SchemaDownloadCommand = {
             const schemaFile = path.normalize(path.join(fullSchemaDir, `${schema.title.toLowerCase()}.schema.json`));
             const relativePath = path.relative(projectPath, schemaFile);
             try {
-                await fsAsync.writeFile(schemaFile, JSON.stringify(schema.schema, undefined, 2), {
+                await fs$1.writeFile(schemaFile, JSON.stringify(schema.schema, undefined, 2), {
                     encoding: "utf-8",
                     flag: force ? 'w' : 'wx'
                 });
@@ -2639,7 +2685,7 @@ const MigrateCommand = {
         const operations = [];
         for (const file of files) {
             const fullPath = path.join(componentsPath, file);
-            const pathInfo = await fsAsync.stat(fullPath);
+            const pathInfo = await fs$1.stat(fullPath);
             if (pathInfo.isDirectory()) { // We only need to rename directories
                 const dirName = path.basename(fullPath);
                 const dirParent = path.dirname(fullPath);
@@ -2662,13 +2708,260 @@ const MigrateCommand = {
             }
         }
         for (const operation of operations) {
-            void await fsAsync.rename(operation.from, operation.to);
+            void await fs$1.rename(operation.from, operation.to);
         }
         NextJsFactoryCommand.handler(args);
     }
 };
 
-var version = "6.0.0-rc.1";
+const SECTION_START = '<!-- @remkoj/optimizely-packages:start -->';
+const SECTION_END = '<!-- @remkoj/optimizely-packages:end -->';
+const ProjectAiCommand = {
+    command: 'project:ai',
+    describe: 'Create or update AI assistant configuration files (AGENTS.md, CLAUDE.md, GitHub Copilot, Cursor) so installed @remkoj package documentation is available to the model',
+    builder: (yargs) => {
+        yargs.option('force', {
+            alias: 'f',
+            description: 'Overwrite existing files entirely instead of merging into existing content',
+            boolean: true,
+            type: 'boolean',
+            demandOption: false,
+            default: false,
+        });
+        yargs.option('tools', {
+            alias: 't',
+            description: 'AI tools to configure',
+            array: true,
+            type: 'string',
+            choices: ['agents', 'claude', 'copilot', 'cursor'],
+            demandOption: false,
+            default: ['agents', 'claude', 'copilot', 'cursor'],
+        });
+        return yargs;
+    },
+    handler: async (args) => {
+        const projectPath = path.isAbsolute(args.path)
+            ? args.path
+            : path.normalize(path.join(process.cwd(), args.path));
+        const force = args.force ?? false;
+        const tools = args.tools ?? ['agents', 'claude', 'copilot', 'cursor'];
+        // Discover installed @remkoj packages that include AGENTS.md
+        process.stdout.write(`\n${figures.arrowRight} Scanning for @remkoj packages with AGENTS.md\n`);
+        const packages = await findRemkojPackages(projectPath);
+        if (packages.length === 0) {
+            process.stderr.write(chalk.yellowBright(`\n${figures.warning} No @remkoj packages with AGENTS.md found in node_modules — run \`npm install\` first.\n`));
+            return;
+        }
+        for (const pkg of packages) {
+            process.stdout.write(`  ${chalk.greenBright(figures.tick)} ${chalk.bold(pkg.name)}\n`);
+        }
+        if (tools.includes('agents')) {
+            process.stdout.write(`\n${figures.arrowRight} Updating AGENTS.md\n`);
+            await updateWithSectionMarkers(path.join(projectPath, 'AGENTS.md'), buildAgentsMdSection(packages, projectPath), buildAgentsMdPreamble(), force, projectPath);
+        }
+        if (tools.includes('claude')) {
+            process.stdout.write(`\n${figures.arrowRight} Writing CLAUDE.md\n`);
+            await writeNewFileOnly(path.join(projectPath, 'CLAUDE.md'), `# CLAUDE.md\n\nSee [AGENTS.md](./AGENTS.md) for guidance on working with the Optimizely DXP packages in this project.\n`, force, projectPath);
+        }
+        if (tools.includes('copilot')) {
+            process.stdout.write(`\n${figures.arrowRight} Updating GitHub Copilot instruction files\n`);
+            await updateCopilotInstructions(projectPath, packages);
+        }
+        if (tools.includes('cursor')) {
+            process.stdout.write(`\n${figures.arrowRight} Writing Cursor rules\n`);
+            const rulesDir = path.join(projectPath, '.cursor', 'rules');
+            await ensureDir(rulesDir);
+            await writeCursorRules(path.join(rulesDir, 'optimizely-packages.mdc'), packages, projectPath);
+        }
+        process.stdout.write(`\n${chalk.greenBright(chalk.bold(figures.tick))} AI assistant configuration updated successfully\n`);
+    },
+};
+// ── Helpers ───────────────────────────────────────────────────────────────────
+async function findRemkojPackages(projectPath) {
+    const scopeDir = path.join(projectPath, 'node_modules', '@remkoj');
+    const packages = [];
+    try {
+        const dirs = await fs$1.readdir(scopeDir);
+        for (const dir of dirs) {
+            const agentsPath = path.join(scopeDir, dir, 'AGENTS.md');
+            try {
+                await fs$1.access(agentsPath);
+                packages.push({ name: `@remkoj/${dir}`, agentsPath });
+            }
+            catch {
+                // Package has no AGENTS.md — skip silently
+            }
+        }
+    }
+    catch {
+        // @remkoj scope directory not found in node_modules
+    }
+    return packages;
+}
+function wrapSection(content) {
+    return `${SECTION_START}\n${content}\n${SECTION_END}`;
+}
+function buildReferenceList(packages, projectPath) {
+    return packages
+        .map((pkg) => {
+        const rel = path.relative(projectPath, pkg.agentsPath).replace(/\\/g, '/');
+        return `- [\`${pkg.name}\`](${rel})`;
+    })
+        .join('\n');
+}
+function buildAgentsMdPreamble() {
+    return `# AI Agent Documentation — Optimizely DXP Packages
+
+The section below is auto-generated by \`opti-cms project:ai\`. Re-run after installing or upgrading \`@remkoj\` packages.
+
+`;
+}
+function buildAgentsMdSection(packages, projectPath) {
+    return `The following \`@remkoj\` packages are installed. Read their \`AGENTS.md\` for documentation:\n\n${buildReferenceList(packages, projectPath)}`;
+}
+/**
+ * Creates or updates the auto-generated section delimited by SECTION_START/SECTION_END markers.
+ *
+ * - File absent: creates it with preamble + section.
+ * - File present with markers: replaces the section in-place.
+ * - File present without markers: appends the section (preserves existing content).
+ * - force=true: always replaces the entire file with preamble + section.
+ */
+async function updateWithSectionMarkers(filePath, sectionContent, preamble, force, projectPath) {
+    const rel = path.relative(projectPath, filePath);
+    const section = wrapSection(sectionContent);
+    let existing;
+    try {
+        existing = await fs$1.readFile(filePath, 'utf-8');
+    }
+    catch {
+        // File does not exist — will be created
+    }
+    if (!existing || force) {
+        await fs$1.writeFile(filePath, preamble + section + '\n', 'utf-8');
+        process.stdout.write(`  ${chalk.greenBright(figures.tick)} ${existing ? 'Replaced' : 'Created'} ${rel}\n`);
+        return;
+    }
+    if (existing.includes(SECTION_START) && existing.includes(SECTION_END)) {
+        const before = existing.slice(0, existing.indexOf(SECTION_START));
+        const after = existing.slice(existing.indexOf(SECTION_END) + SECTION_END.length);
+        await fs$1.writeFile(filePath, before + section + after, 'utf-8');
+        process.stdout.write(`  ${chalk.greenBright(figures.tick)} Updated section in ${rel}\n`);
+    }
+    else {
+        await fs$1.writeFile(filePath, existing.trimEnd() + '\n\n' + section + '\n', 'utf-8');
+        process.stdout.write(`  ${chalk.greenBright(figures.tick)} Appended section to ${rel}\n`);
+    }
+}
+/**
+ * Writes a file only when it does not already exist.
+ * When force=true the file is always (re)written.
+ */
+async function writeNewFileOnly(filePath, content, force, projectPath) {
+    const rel = path.relative(projectPath, filePath);
+    let exists = false;
+    try {
+        await fs$1.access(filePath);
+        exists = true;
+    }
+    catch {
+        // File does not exist
+    }
+    if (exists && !force) {
+        process.stdout.write(`  ${chalk.yellowBright(figures.info)} ${rel} already exists — use --force to overwrite\n`);
+        return;
+    }
+    await fs$1.writeFile(filePath, content, 'utf-8');
+    process.stdout.write(`  ${chalk.greenBright(figures.tick)} ${exists ? 'Replaced' : 'Created'} ${rel}\n`);
+}
+/**
+ * Writes one `.vscode/instructions/remkoj-<name>.instructions.md` file per package,
+ * each containing a `#file:` reference to the package's AGENTS.md in node_modules.
+ * VS Code Copilot resolves `#file:` references at query time, so content stays
+ * current after a package upgrade without re-running this command.
+ *
+ * Also removes the deprecated `github.copilot.chat.codeGeneration.instructions`
+ * key from `.vscode/settings.json` if it was written by a previous run.
+ */
+async function updateCopilotInstructions(projectPath, packages) {
+    const instructionsDir = path.join(projectPath, '.vscode', 'instructions');
+    await ensureDir(instructionsDir);
+    // Remove stale remkoj instruction files from previous runs
+    const FILE_PREFIX = 'remkoj-';
+    try {
+        const existing = await fs$1.readdir(instructionsDir);
+        for (const f of existing) {
+            if (f.startsWith(FILE_PREFIX) && f.endsWith('.instructions.md')) {
+                await fs$1.unlink(path.join(instructionsDir, f));
+            }
+        }
+    }
+    catch {
+        // Directory unreadable — ignore
+    }
+    // Write one instruction file per package using a #file: reference
+    for (const pkg of packages) {
+        const safeName = pkg.name.replace('@remkoj/', '');
+        const filePath = path.join(instructionsDir, `${FILE_PREFIX}${safeName}.instructions.md`);
+        const ref = path.relative(projectPath, pkg.agentsPath).replace(/\\/g, '/');
+        const content = `---\napplyTo: "**"\n---\n\n#file:${ref}\n`;
+        await fs$1.writeFile(filePath, content, 'utf-8');
+        process.stdout.write(`  ${chalk.greenBright(figures.tick)} Wrote ${path.relative(projectPath, filePath)}\n`);
+    }
+    // Clean up the deprecated settings key written by previous versions of this command
+    await removeDeprecatedCopilotSetting(projectPath);
+}
+async function removeDeprecatedCopilotSetting(projectPath) {
+    const settingsFile = path.join(projectPath, '.vscode', 'settings.json');
+    let settings;
+    try {
+        settings = JSON.parse(await fs$1.readFile(settingsFile, 'utf-8'));
+    }
+    catch {
+        return; // File absent or invalid — nothing to clean up
+    }
+    const key = 'github.copilot.chat.codeGeneration.instructions';
+    if (!(key in settings))
+        return;
+    const remaining = settings[key].filter((e) => !e.file?.startsWith('node_modules/@remkoj/'));
+    if (remaining.length === 0) {
+        delete settings[key];
+    }
+    else {
+        settings[key] = remaining;
+    }
+    await fs$1.writeFile(settingsFile, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    process.stdout.write(`  ${chalk.greenBright(figures.tick)} Removed deprecated setting from ${path.relative(projectPath, settingsFile)}\n`);
+}
+/** Writes the Cursor rules file with a reference list; always regenerated since it is fully derived from node_modules. */
+async function writeCursorRules(filePath, packages, projectPath) {
+    const rel = path.relative(projectPath, filePath);
+    let exists = false;
+    try {
+        await fs$1.access(filePath);
+        exists = true;
+    }
+    catch {
+        // File does not exist
+    }
+    const list = buildReferenceList(packages, projectPath);
+    const content = [
+        '---',
+        'description: Documentation for @remkoj Optimizely DXP packages installed in this project',
+        'alwaysApply: true',
+        '---',
+        '',
+        wrapSection(`The following \`@remkoj\` packages are installed. Read their \`AGENTS.md\` for documentation:\n\n${list}`),
+        '',
+    ].join('\n');
+    await fs$1.writeFile(filePath, content, 'utf-8');
+    process.stdout.write(`  ${chalk.greenBright(figures.tick)} ${exists ? 'Updated' : 'Created'} ${rel}\n`);
+}
+async function ensureDir(dirPath) {
+    await fs$1.mkdir(dirPath, { recursive: true });
+}
+
+var version = "6.0.0-rc.4";
 var name = "opti-cms";
 var APP = {
 	version: version,
@@ -2685,14 +2978,6 @@ const CmsVersionCommand = {
         const client = createCmsClient(args);
         if (client.debug)
             process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Reading version information Optimizely CMS\n`));
-        const versionInfo = await client.getInstanceInfo().catch((error) => {
-            switch (error.message) {
-                case "fetch failed":
-                    throw new Error("Unable to connect to Optimizely CMS, please verify that the CMS URL is correct");
-                default:
-                    throw error;
-            }
-        });
         const info = new Table({
             head: [
                 chalk.yellow(chalk.bold("Component")),
@@ -2701,14 +2986,10 @@ const CmsVersionCommand = {
             colWidths: [30, 60],
             colAligns: ["left", "left"]
         });
-        info.push(["Base URL", versionInfo.baseUrl ?? client.cmsUrl.href]);
+        info.push(["Base URL", client.cmsUrl.href]);
         info.push(["Client API", client.apiVersion]);
-        info.push(["Service API", versionInfo.apiVersion]);
-        info.push(["CMS Build", versionInfo.cmsVersion]);
-        info.push(["Service Build", versionInfo.serviceVersion]);
         info.push(["SDK", APP.version]);
         process.stdout.write(info.toString() + "\n");
-        process.stdout.write(chalk.yellowBright(`${figures.arrowRight} Optimizely CMS Status: ${versionInfo.status}\n`));
         process.stdout.write(chalk.green(chalk.bold(figures.tick + " Done")) + "\n");
     }
 };
@@ -2765,7 +3046,7 @@ const CmsResetCommand = {
         });
         if (!didRemoveCustomProperties) {
             const ctUrl = new URL('/ui/EPiServer.Cms.UI.Admin/default#/ContentTypes', client.cmsUrl);
-            process.stdout.write(`${chalk.redBright(figures.cross)} Custom properties on the \"Blank Section\" and \"Blank Experience\" Content Types must be removed manually, please remove and restart command.\n`);
+            process.stdout.write(`${chalk.redBright(figures.cross)} Custom properties on the "Blank Section" and "Blank Experience" Content Types must be removed manually, please remove and restart command.\n`);
             process.stdout.write(`  ${figures.arrowRight} Content Type manager: ${ctUrl}\n`);
             process.exit(1);
         }
@@ -2799,7 +3080,7 @@ async function deleteContentItem(client, key, onlyChildren = false) {
     const children = await getContentItemChildren(client, key);
     let hasError = false;
     let removedCount = 0;
-    for (let child of children.items)
+    for (const child of children.items)
         if (child.key) {
             removedCount = removedCount + await deleteContentItem(client, child.key).catch(e => {
                 console.error(e);
@@ -2807,7 +3088,7 @@ async function deleteContentItem(client, key, onlyChildren = false) {
                 return 0;
             });
         }
-    for (let child of children.assets)
+    for (const child of children.assets)
         if (child.key) {
             removedCount = removedCount + await deleteContentItem(client, child.key).catch(e => {
                 console.error(e);
@@ -2826,7 +3107,7 @@ async function deleteContentItem(client, key, onlyChildren = false) {
             process.stderr.write(chalk.redBright(`  ${figures.cross}The ContentItem ${key} is a reserved item, skipping deletion\n`));
         return removedCount;
     }
-    const deleteResult = await client.contentDelete({ path: { key }, headers: { "cms-permanent-delete": true } }).then(r => r.key).catch((e) => {
+    const deleteResult = await client.contentDelete({ path: { key }, headers: { "cms-permanent-delete": true } }).then(r => r ? r.key : key).catch((e) => {
         if (e.status == 404)
             return key;
         throw e;
@@ -2850,7 +3131,6 @@ async function resetSystemTypes(client) {
         const newType = await client.contentTypesPatch({
             path: { key: systemType },
             body: {
-                key: systemType,
                 properties: {}
             }
         }).catch((e) => e.status == 404 ? undefined : null);
@@ -2862,7 +3142,7 @@ async function resetSystemTypes(client) {
 async function removeContentTypes(client) {
     const contentTypes = await getAllTypes(client);
     let removedCount = 0;
-    for (let contentType of contentTypes.filter(item => item.source == '' && !reservedTypes.includes(item.key))) {
+    for (const contentType of contentTypes.filter(item => item.source == '' && !reservedTypes.includes(item.key))) {
         if (client.debug)
             process.stdout.write(`  ${chalk.blueBright(figures.arrowRight)} Removing content type ${contentType.displayName} (${contentType.key})\n`);
         const result = await client.contentTypesDelete({ path: { key: contentType.key } }).catch((e) => {
@@ -2903,7 +3183,7 @@ async function getAllTemplates(client, batchSize = 100) {
         }
         throw e;
     });
-    const totalItemCount = items.totalItemCount ?? items.items?.length ?? 0;
+    const totalItemCount = items.totalCount ?? items.totalItemCount ?? items.items?.length ?? 0;
     const pageSize = items.pageSize ?? items.items?.length ?? 0;
     const actualItems = items.items ?? [];
     const pageCount = Math.ceil(totalItemCount / pageSize);
@@ -2933,7 +3213,7 @@ async function getAllTypes(client, batchSize = 100) {
         }
         throw e;
     });
-    const totalItemCount = items.totalItemCount ?? items.items?.length ?? 0;
+    const totalItemCount = items.totalCount ?? items.totalItemCount ?? items.items?.length ?? 0;
     const pageSize = items.pageSize ?? items.items?.length ?? 0;
     const actualItems = items.items ?? [];
     const pageCount = Math.ceil(totalItemCount / pageSize);
@@ -2963,7 +3243,7 @@ async function getAllAssets(client, parentKey, batchSize = 100) {
         }
         throw e;
     });
-    const totalItemCount = items.totalItemCount ?? items.items?.length ?? 0;
+    const totalItemCount = items.totalCount ?? items.totalItemCount ?? items.items?.length ?? 0;
     const pageSize = items.pageSize ?? items.items?.length ?? 0;
     const actualItems = items.items ?? [];
     const pageCount = Math.ceil(totalItemCount / pageSize);
@@ -2993,7 +3273,7 @@ async function getAllItems(client, parentKey, batchSize = 100) {
         }
         throw e;
     });
-    const totalItemCount = items.totalItemCount ?? items.items?.length ?? 0;
+    const totalItemCount = items.totalCount ?? items.totalItemCount ?? items.items?.length ?? 0;
     const pageSize = items.pageSize ?? items.items?.length ?? 0;
     const actualItems = items.items ?? [];
     const pageCount = Math.ceil(totalItemCount / pageSize);
@@ -3034,7 +3314,8 @@ const commands = [
     StylesDeleteCommand,
     TypesPullCommand,
     TypesPushCommand,
-    MigrateCommand
+    MigrateCommand,
+    ProjectAiCommand,
 ];
 
 async function main() {