@sitecore-content-sdk/content 1.5.0-canary.5

package/dist/esm/tools/codegen/utils.js

@@ -0,0 +1,373 @@
+/* eslint-disable jsdoc/require-jsdoc */
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import * as ts from 'typescript';
+import { debug } from '@sitecore-content-sdk/core';
+import { isBuiltin } from 'module';
+/**
+ * Parse the generated component-map file and return all referenced modules
+ * per map entry (handles both single identifiers and spread objects).
+ * @param {string} appRoot path to the JSS app root
+ * @param {string} componentMapPath path to the component map file
+ * @returns map of component names and their respective import strings
+ */
+export let resolveComponentImportFiles = _resolveComponentImportFiles;
+/**
+ * Reads the named exports from a TypeScript file.
+ * @param {ExtractedFile} filePath absolute path to a .ts/.tsx file
+ * @returns {string[]} list of named exports found in the file
+ */
+export let readNamedExports = _readNamedExports;
+/**
+ * Sends the extracted code to the specified target URL.
+ * @param {object} params - The parameters object.
+ * @param {ExtractedFile} params.file - The file to be sent.
+ * @param {string} params.token - The access token for authentication.
+ * @param {string} params.targetUrl - The target URL to send the file to.
+ * @param {Record<string, unknown>} [params.extraLabels] - Additional labels to include in the payload.
+ * @returns {Promise<string | null>} - The path of the sent file or null if sending failed.
+ */
+export let sendCode = _sendCode;
+export const utilsUnitMocks = {
+    set xmCloudDeploy(mockImpl) {
+        utils.xmCloudDeploy = mockImpl;
+    },
+    get xmCloudDeploy() {
+        return _xmCloudDeploy;
+    },
+    set resolveComponentImportFiles(mockImpl) {
+        resolveComponentImportFiles = mockImpl;
+    },
+    get resolveComponentImportFiles() {
+        return _resolveComponentImportFiles;
+    },
+    set readNamedExports(mockImpl) {
+        readNamedExports = mockImpl;
+    },
+    get readNamedExports() {
+        return _readNamedExports;
+    },
+    set sendCode(mockImpl) {
+        sendCode = mockImpl;
+    },
+    get sendCode() {
+        return _sendCode;
+    },
+};
+/**
+ * Type of file to be sent to the mesh endpoint
+ */
+export var ExtractedFileType;
+(function (ExtractedFileType) {
+    ExtractedFileType["Component"] = "component";
+    ExtractedFileType["Variant"] = "variant";
+    ExtractedFileType["Json"] = "json";
+    ExtractedFileType["PackageJson"] = "package.json";
+})(ExtractedFileType || (ExtractedFileType = {}));
+export const utils = {
+    xmCloudDeploy: (...args) => _xmCloudDeploy(...args),
+};
+export const _xmCloudDeploy = () => !!process.env.SITECORE && !!process.env.SITECORE_BUILD;
+// workaround, Vercel does not have variables that are only accessible at build time
+const vercelDeploy = () => !!process.env.VERCEL && !process.env.VERCEL_REGION;
+const netlifyDeploy = () => !!process.env.NETLIFY && !!process.env.BUILD_ID;
+/**
+ * Validates if the current operation is done in Vercel, Netlify or XMCloud
+ * deploy context
+ * @returns {boolean} - true if in deploy context, false otherwise
+ */
+export function validateDeployContext() {
+    return _xmCloudDeploy() || vercelDeploy() || netlifyDeploy();
+}
+/*
+ * Load and parse the tsconfig.json file from the specified app path.
+ */
+function loadCompilerOptions(appPathAbs) {
+    const configPath = ts.findConfigFile(appPathAbs, ts.sys.fileExists, 'tsconfig.json');
+    if (!configPath) {
+        // Sane defaults if no tsconfig exists
+        return {
+            jsx: ts.JsxEmit.Preserve,
+            allowJs: true,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            target: ts.ScriptTarget.ES2020,
+            baseUrl: appPathAbs,
+            noEmit: true,
+        };
+    }
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error) {
+        throw new Error(`Error reading tsconfig at ${configPath}: ${configFile.error.messageText}`);
+    }
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath));
+    // Merge with a few safe fallbacks/overrides
+    return Object.assign({ jsx: ts.JsxEmit.Preserve, allowJs: true, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.NodeNext, target: ts.ScriptTarget.ES2020, baseUrl: appPathAbs, noEmit: true }, parsed.options);
+}
+/*
+ * Resolve a module specifier using tsconfig options (fast, no Program needed).
+ */
+function resolveWithTs(spec, fromFile, options) {
+    var _a, _b;
+    const host = {
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        directoryExists: ts.sys.directoryExists,
+        getCurrentDirectory: ts.sys.getCurrentDirectory,
+        getDirectories: ts.sys.getDirectories,
+        realpath: ts.sys.realpath,
+    };
+    const result = ts.resolveModuleName(spec, fromFile, options, host);
+    return (_b = (_a = result.resolvedModule) === null || _a === void 0 ? void 0 : _a.resolvedFileName) !== null && _b !== void 0 ? _b : null;
+}
+function _resolveComponentImportFiles(appRoot, componentMapPath = './.sitecore/component-map.ts') {
+    const appPath = path.isAbsolute(appRoot) ? appRoot : path.resolve(process.cwd(), appRoot);
+    const mapPath = path.isAbsolute(componentMapPath)
+        ? componentMapPath
+        : path.resolve(appPath, componentMapPath);
+    if (!fs.existsSync(mapPath)) {
+        throw new ReferenceError(`Failed to find file ${mapPath}`);
+    }
+    // 1) Load tsconfig (simple + safe). Use appPath as baseUrl fallback.
+    const compilerOptions = loadCompilerOptions(appPath);
+    // Read & parse the map file to an AST (SourceFile)
+    const mapText = fs.readFileSync(mapPath, 'utf8');
+    const source = ts.createSourceFile(mapPath, mapText, ts.ScriptTarget.Latest, true);
+    const getFileType = (absPath) => {
+        const base = path.basename(absPath); // "PromoBlock.extra.tsx"
+        const name = base.replace(/\.[^.]+$/, ''); // "PromoBlock.extra"
+        return name.includes('.') ? ExtractedFileType.Variant : ExtractedFileType.Component;
+    };
+    // 1) Collect import (import %importString% from %importModule%) strings
+    const componentMapImports = new Map();
+    source.forEachChild((node) => {
+        if (ts.isImportDeclaration(node) && node.importClause) {
+            const importString = node.importClause.getText();
+            const importModule = node.moduleSpecifier.text;
+            componentMapImports.set(importString, importModule);
+        }
+    });
+    // 2) Find the map literal: new Map([...]) and collect entries
+    //    Also capture subsequent mutations: <mapIdent>.set('Key', Value)
+    const results = [];
+    const mapIdentifiers = new Set(); // all identifiers bound to the Map we care about
+    // Given an import and an expression (identifier or object literal with spreads),
+    // resolve the module(s) to absolute file paths and append normalized entries to `results`.
+    const resolveAndRecordEntry = (importStringsEntry, mapEntry) => {
+        // small guard to record a resolved path if valid
+        const recordIfValid = (spec) => {
+            // ignore Node built-ins and node: protocol up front
+            if (isBuiltin(spec) || isNodeProtocol(spec))
+                return;
+            const fileAbs = resolveWithTs(spec, mapPath, compilerOptions);
+            if (!fileAbs)
+                return;
+            // ignore node_modules and *.d.ts after resolution
+            if (inNodeModules(fileAbs) || isDeclarationFile(fileAbs))
+                return;
+            results.push({
+                componentKey: importStringsEntry,
+                filePath: toPosixPath(fileAbs),
+                fileType: getFileType(fileAbs),
+            });
+        };
+        // Helper to find the matching import statement for a given component/module name
+        const getImportPathForModule = (componentModuleName) => {
+            let result = componentMapImports.get(componentModuleName);
+            if (!result) {
+                for (const key of componentMapImports.keys()) {
+                    const matcher = new RegExp(`\\b(${componentModuleName})\\b`);
+                    if (key.match(matcher) !== null) {
+                        return componentMapImports.get(key);
+                    }
+                }
+                return null;
+            }
+            return result;
+        };
+        // Case A: ['Key', Identifier]
+        if (ts.isIdentifier(mapEntry)) {
+            const componentEntryName = mapEntry.text;
+            const importPathString = getImportPathForModule(componentEntryName);
+            if (!importPathString)
+                return;
+            recordIfValid(importPathString);
+            return;
+        }
+        // Case B: ['Key', { ...A, ...B, ...C }]
+        if (ts.isObjectLiteralExpression(mapEntry)) {
+            mapEntry.properties.forEach((prop) => {
+                if (ts.isSpreadAssignment(prop) && ts.isIdentifier(prop.expression)) {
+                    const componentEntryName = prop.expression.text;
+                    const importPathString = getImportPathForModule(componentEntryName);
+                    if (!importPathString)
+                        return;
+                    recordIfValid(importPathString);
+                }
+            });
+        }
+    };
+    // Walk the `new Map([...])` array literal and feed each ['Key', Value] into
+    // `resolveAndRecordEntry` (only when the key is a string literal).
+    const collectArrayEntries = (arrayArg) => {
+        arrayArg.elements.forEach((el) => {
+            if (ts.isArrayLiteralExpression(el)) {
+                const [keyNode, valNode] = el.elements;
+                if (keyNode && valNode && ts.isStringLiteral(keyNode)) {
+                    resolveAndRecordEntry(keyNode.text, valNode);
+                }
+            }
+        });
+    };
+    // If this `new Map([...])` is bound to a variable (via decl or assignment),
+    // record the identifier name so we can catch later `<id>.set(...)` mutations.
+    const captureMapIdentifier = (node) => {
+        // const m = new Map([...])
+        const parent = node.parent;
+        // Variable declaration with initializer new Map(...)
+        if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+            mapIdentifiers.add(parent.name.text);
+            return;
+        }
+        // Assignment: m = new Map([...])
+        if (parent &&
+            ts.isBinaryExpression(parent) &&
+            parent.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isIdentifier(parent.left)) {
+            mapIdentifiers.add(parent.left.text);
+            return;
+        }
+        // Exported variable declaration: export const componentMap = new Map([...])
+        if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+            mapIdentifiers.add(parent.name.text);
+            return;
+        }
+    };
+    const traverseAst = (node) => {
+        var _a;
+        // A) Initial literal: new Map([...])
+        if (ts.isNewExpression(node) &&
+            node.expression.getText(source) === 'Map' &&
+            node.arguments &&
+            node.arguments.length > 0) {
+            const firstArg = node.arguments[0];
+            if (ts.isArrayLiteralExpression(firstArg)) {
+                collectArrayEntries(firstArg);
+            }
+            captureMapIdentifier(node);
+        }
+        // B) Mutations: <mapIdent>.set('Key', Value)
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === 'set') {
+            const target = node.expression.expression;
+            if (ts.isIdentifier(target) && mapIdentifiers.has(target.text)) {
+                const [keyArg, valArg] = (_a = node.arguments) !== null && _a !== void 0 ? _a : [];
+                if (keyArg && ts.isStringLiteral(keyArg) && valArg) {
+                    resolveAndRecordEntry(keyArg.text, valArg);
+                }
+            }
+        }
+        ts.forEachChild(node, traverseAst);
+    };
+    ts.forEachChild(source, traverseAst);
+    return results.filter((r) => !isDeclarationFile(r.filePath));
+}
+function _readNamedExports(filePath) {
+    const code = fs.readFileSync(filePath, 'utf8');
+    const sf = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
+    const names = new Set();
+    const visit = (node) => {
+        var _a, _b;
+        // export const X = ...
+        if (ts.isVariableStatement(node) &&
+            ((_a = node.modifiers) === null || _a === void 0 ? void 0 : _a.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))) {
+            node.declarationList.declarations.forEach((d) => {
+                if (ts.isIdentifier(d.name))
+                    names.add(d.name.text);
+            });
+        }
+        // export function X() {}
+        if (ts.isFunctionDeclaration(node) &&
+            ((_b = node.modifiers) === null || _b === void 0 ? void 0 : _b.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) &&
+            node.name) {
+            names.add(node.name.text);
+        }
+        // export { A, B as C }
+        if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+            node.exportClause.elements.forEach((e) => names.add(e.name.text));
+        }
+        // export default ...
+        if (ts.isExportAssignment(node)) {
+            names.add('Default');
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sf, visit);
+    return Array.from(names);
+}
+async function _sendCode({ file, token, targetUrl, }) {
+    const apiEndpoint = `${targetUrl}/mesh/push/api/v1/contentsdk/code/extracted`;
+    if (!fs.existsSync(file.path)) {
+        console.error(chalk.red(`File not found: ${file.path}`));
+        return null;
+    }
+    const code = fs.readFileSync(file.path);
+    // Merge base labels with any extra labels (variants, componentName, etc.)
+    const labels = Object.assign({ type: file.type }, (file.labels || {}));
+    try {
+        const response = await fetch(apiEndpoint, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                EnvironmentId: 'ContentSDK',
+                name: file.name,
+                content: code.toString(),
+                labels,
+            }),
+        });
+        if (!response.ok) {
+            console.error(chalk.red(`Failed to send extracted code from ${file.path}: ${response.statusText}`));
+            debug.http('Error details: %o', {
+                status: response.status,
+                text: await response.text(),
+                url: response.url,
+                headers: response.headers,
+            });
+            return null;
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Fetch request to send extracted code from ${file.path} failed: ${JSON.stringify(error)}`));
+        return null;
+    }
+    return file.path;
+}
+const NODE_PROTOCOL = 'node:';
+function isNodeProtocol(specifier) {
+    return specifier.startsWith(NODE_PROTOCOL);
+}
+function isDeclarationFile(p) {
+    return p.endsWith('.d.ts');
+}
+function inNodeModules(p) {
+    return p.replace(/\\/g, '/').includes('/node_modules/');
+}
+// Normalize path separators to POSIX-style "/" for cross-platform consistency.
+export function toPosixPath(p) {
+    if (/^\\\\\?\\/.test(p))
+        return p;
+    return p.replace(/\\/g, '/');
+}
+export const stripExtension = (p) => p.replace(/\.(tsx?|jsx?|mjs|cjs)$/, '');
+// Convert an absolute file path into an relative module specifier (POSIX)
+export const getRelativeImportPath = (absFile, appPath) => {
+    let rel = toPosixPath(path.relative(appPath, absFile));
+    return stripExtension(rel);
+};
+// Determine if a specifier is bare/aliased (i.e., not relative "./" or "../" and not absolute "/").
+export const isNodeModuleImport = (name) => !name.startsWith('./') && !name.startsWith('../') && !name.startsWith('/');

package/dist/esm/tools/generate-map.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/tools/generateSites.js

@@ -0,0 +1,52 @@
+import path from 'path';
+import chalk from 'chalk';
+import fs from 'fs';
+import { ensurePathExists } from '@sitecore-content-sdk/core/tools';
+import { SiteInfoService } from '../site';
+import { createGraphQLClientFactory } from '../client';
+import debug from '../debug';
+const DEFAULT_SITES_DIST_PATH = '.sitecore/sites.json';
+/**
+ * Generates site information and writes it to a specified destination path.
+ * @param {GenerateSitesConfig} config - The configuration for generating site info.
+ * @returns {Promise<Function>} - A promise that resolves to an asynchronous function that fetches site information and writes it to a file.
+ * @public
+ */
+export const generateSites = ({ scConfig: deprecatedScConfig, destinationPath, } = {}) => {
+    return async ({ scConfig } = {}) => {
+        const config = deprecatedScConfig !== null && deprecatedScConfig !== void 0 ? deprecatedScConfig : scConfig;
+        if (!config) {
+            throw new Error('Sitecore configuration is required to be provided');
+        }
+        let sites = [];
+        const sitesFilePath = path.resolve(destinationPath !== null && destinationPath !== void 0 ? destinationPath : DEFAULT_SITES_DIST_PATH);
+        debug.multisite(config.multisite.enabled
+            ? 'Multisite Enabled: Generating site information'
+            : 'Multisite Disabled');
+        if (config.multisite.enabled) {
+            try {
+                const siteInfoService = new SiteInfoService({
+                    clientFactory: createGraphQLClientFactory({
+                        api: config.api,
+                        retries: config.retries.count,
+                        retryStrategy: config.retries.retryStrategy,
+                    }),
+                });
+                sites = await siteInfoService.fetchSiteInfo();
+            }
+            catch (error) {
+                console.error(chalk.red('Error fetching site information'));
+                throw error;
+            }
+        }
+        // Add default site to the list
+        const defaultSite = {
+            name: config.defaultSite,
+            hostName: '*',
+            language: config.defaultLanguage,
+        };
+        sites.unshift(defaultSite);
+        ensurePathExists(sitesFilePath);
+        fs.writeFileSync(sitesFilePath, JSON.stringify(sites, null, 2), { encoding: 'utf8' });
+    };
+};

package/dist/esm/tools/index.js

@@ -0,0 +1,6 @@
+export { generateSites } from './generateSites';
+export { scaffoldComponent } from './scaffold';
+export { extractFiles } from './codegen/extract-files';
+export { writeImportMap, defaultMapTemplate as defaultImportMapTemplate, } from './codegen/import-map';
+export { getComponentSpec, getComponentSpecUrl } from './codegen/component-generation';
+export * from './templating';

package/dist/esm/tools/scaffold.js

@@ -0,0 +1,54 @@
+import fs from 'fs';
+import chalk from 'chalk';
+import path from 'path';
+/**
+ * Force to use `crlf` line endings, we are using `crlf` across the project.
+ * Replace: `lf` (\n), `cr` (\r)
+ * @param {string} content
+ */
+export function editLineEndings(content) {
+    return content.replace(/\r|\n/gm, '\r\n');
+}
+/**
+ * Creates a file relative to the specified path if the file doesn't exist.
+ * Creates directories as needed.
+ * Does not overwrite existing files.
+ * @param {string} filePath - the file path
+ * @param {string} fileContent - the file content
+ * @returns {string} the file path if the file was created, otherwise null
+ */
+export function scaffoldFile(filePath, fileContent) {
+    const outputDir = path.dirname(filePath);
+    if (fs.existsSync(filePath)) {
+        console.log(chalk.red(`Skipping creating ${filePath}; already exists.`));
+        return null;
+    }
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.writeFileSync(filePath, editLineEndings(fileContent), 'utf8');
+    console.log(chalk.green(`File ${filePath} has been scaffolded.`));
+    return filePath;
+}
+/**
+ * Scaffolds a new component based on the provided template.
+ * @param {string} outputFolderPath - The file path where the component will be created.
+ * @param {string} componentName - The name of the component to be created.
+ * @param {string} templateName - The name of the template to use for scaffolding. If not provided, defaults to 'byoc' if `byoc` is true, otherwise 'default'.
+ * @param {ScaffoldTemplate[]} templates - An array of template objects, each containing a name, a template function, and a getNextSteps function.
+ * @throws Will throw an error if the specified template is not found.
+ * @internal
+ */
+export function scaffoldComponent(outputFolderPath, componentName, templateName, templates) {
+    const template = templates.find((t) => t.name === templateName);
+    if (!template) {
+        throw new Error(`Template ${templateName} not found.`);
+    }
+    const outputFilePath = path.join(outputFolderPath, `${componentName}.${template.fileExtension}`);
+    const componentOutputPath = scaffoldFile(outputFilePath, template.generateTemplate(componentName));
+    if (componentOutputPath) {
+        const nextSteps = [];
+        nextSteps.push(chalk.green(`
+    Scaffolding of ${componentName} complete.
+    Next steps:`), ...(template.getNextSteps ? template.getNextSteps(componentOutputPath) : []));
+        console.log(nextSteps.join('\n'));
+    }
+}

package/dist/esm/tools/templating/components.js

@@ -0,0 +1,59 @@
+import * as glob from 'glob';
+/**
+ * @public
+ */
+export let getComponentList = _getComponentList;
+export const componentUnitMocks = {
+    set getComponentList(mockImplementation) {
+        getComponentList = mockImplementation;
+    },
+    get getComponentList() {
+        return _getComponentList;
+    },
+};
+const componentNamePattern = /^[\/]*(.+[\/\\])*(.+)\.[jt]sx?$/;
+const componentPathPattern = /^([\/]*.+[\/\\].+)\..+$/;
+/**
+ * Get list of components from @var path
+ * Returns a list of components in the following format:
+ * {
+ *  path: 'path/to/component',
+ *  componentName: 'ComponentName',
+ *  moduleName: 'ComponentName'
+ * }
+ * @param {string[]} paths paths to search
+ * @param {string[]} [exclude] paths and glob patterns to exclude from final result
+ * @param {boolean} [includeVariants] whether to include variant components
+ */
+function _getComponentList(paths, exclude, includeVariants) {
+    const components = paths.reduce((result, path) => {
+        const globPath = glob.hasMagic(path, { magicalBraces: true }) || path.match(componentNamePattern)
+            ? path
+            : path.replace(/\/$/, '').concat('/**/*.{js,jsx,ts,tsx}');
+        return result.concat(...glob
+            .sync(globPath, { ignore: exclude, nodir: true })
+            .filter((path) => path.match(componentNamePattern))
+            .map((filePath) => {
+            const name = filePath.match(componentNamePattern)[2];
+            return {
+                filePath,
+                importPath: filePath.match(componentPathPattern)[1].replace(/\\/g, '/'), // use forward slashes for consistency
+                componentName: name,
+                moduleName: name.replace(/[^\w]+/g, ''),
+            };
+        }));
+    }, []);
+    return includeVariants
+        ? components
+        : components.filter((component) => !component.componentName.includes('.'));
+}
+/**
+ * Filters components by their detected type.
+ * @param {ComponentFileWithType[]} components - Array of components with types
+ * @param {ComponentType[]} allowedTypes - Array of allowed component types to filter by
+ * @returns {ComponentFileWithType[]} Filtered array containing only components matching allowed types
+ * @internal
+ */
+export function filterComponentsByType(components, allowedTypes) {
+    return components.filter((component) => allowedTypes.includes(component.componentType));
+}

package/dist/esm/tools/templating/index.js

@@ -0,0 +1 @@
+export { getComponentList, filterComponentsByType, } from './components';

package/editing.d.ts

@@ -0,0 +1 @@
+export * from './types/editing/index';

package/i18n.d.ts

@@ -0,0 +1 @@
+export * from './types/i18n/index';

package/layout.d.ts

@@ -0,0 +1 @@
+export * from './types/layout/index';

package/media.d.ts

@@ -0,0 +1 @@
+export * from './types/media/index';