Feat/create command for variants configuration

.changeset/little-ties-cry.md

@@ -0,0 +1,6 @@
+---
+'@sap-ux/app-config-writer': patch
+'@sap-ux/create': patch
+---
+
+Introduce create command to add Configuration for Variants Creation.

packages/app-config-writer/package.json

@@ -29,6 +29,7 @@
         "!dist/**/*.map"
     ],
     "dependencies": {
+        "@sap-ux/preview-middleware": "workspace:*",
         "@sap-ux/axios-extension": "workspace:*",
         "@sap-ux/btp-utils": "workspace:*",
         "@sap-ux/logger": "workspace:*",

packages/app-config-writer/src/index.ts

@@ -1,3 +1,4 @@
 export { getSmartLinksTargetFromPrompt, promptInboundNavigationConfig, validateText } from './prompt';
 export { generateSmartLinksConfig } from './smartlinks-config';
 export { generateInboundNavigationConfig } from './navigation-config';
+export { generateVariantsConfig } from './variants-config';

packages/app-config-writer/src/types/index.ts

@@ -1,2 +1,3 @@
 export * from './smartLinks';
+export * from './variantsConfig';
 export * from './navigation';

packages/app-config-writer/src/types/variantsConfig.ts

@@ -0,0 +1,16 @@
+import type { MiddlewareConfig as PreviewConfig } from '@sap-ux/preview-middleware';
+
+export type FioriToolsDeprecatedPreviewConfig = {
+    component: string;
+    libs?: boolean;
+    ui5Theme?: string;
+};
+
+export type PreviewConfigOptions = FioriToolsDeprecatedPreviewConfig | PreviewConfig;
+
+export enum MiddlewareConfigs {
+    FioriToolsPreview = 'fiori-tools-preview',
+    PreviewMiddleware = 'preview-middleware',
+    ReloadMiddleware = 'reload-middleware',
+    FioriToolsAppreload = 'fiori-tools-appreload'
+}

packages/app-config-writer/src/variants-config/generateVariantsConfig.ts

@@ -0,0 +1,26 @@
+import { create } from 'mem-fs-editor';
+import { create as createStorage } from 'mem-fs';
+import { updateMiddlewares } from './ui5-yaml';
+import { addVariantsManagementScript } from './package-json';
+import type { Editor } from 'mem-fs-editor';
+import type { ToolsLogger } from '@sap-ux/logger';
+
+/**
+ * Add variants configuration to an app or project.
+ *
+ * @param basePath - the base path where the package.json and ui5.yaml is
+ * @param logger - logger
+ * @param fs - the memfs editor instance
+ * @returns Promise<Editor> - memfs editor instance with updated files
+ */
+export async function generateVariantsConfig(basePath: string, logger?: ToolsLogger, fs?: Editor): Promise<Editor> {
+    if (!fs) {
+        fs = create(createStorage());
+    }
+    await addVariantsManagementScript(fs, basePath, logger).catch((error) => {
+        logger?.error(`Script 'start-variants-management' cannot be written to package.json. ${error.message}.`);
+        return fs;
+    });
+    await updateMiddlewares(fs, basePath, logger);
+    return fs;
+}

packages/app-config-writer/src/variants-config/index.ts

@@ -0,0 +1 @@
+export * from './generateVariantsConfig';

packages/app-config-writer/src/variants-config/package-json.ts

@@ -0,0 +1,48 @@
+import { join } from 'path';
+import { getSapClientFromPackageJson, getUI5UrlParameters, getRTAUrl } from './utils';
+import type { Editor } from 'mem-fs-editor';
+import type { Package } from '@sap-ux/project-access';
+import type { ToolsLogger } from '@sap-ux/logger';
+
+/**
+ * Add the start-variants-management script to the package.json.
+ *
+ * @param fs - mem-fs reference to be used for file access
+ * @param basePath - path to application root, where package.json is
+ * @param logger - logger
+ * @returns Promise<void> - rejects in case variants management script can't be added to package.json
+ */
+export async function addVariantsManagementScript(fs: Editor, basePath: string, logger?: ToolsLogger): Promise<void> {
+    const packageJsonPath = join(basePath, 'package.json');
+    const packageJson = fs.readJSON(packageJsonPath) as Package | undefined;
+
+    if (!packageJson) {
+        return Promise.reject(new Error(`File 'package.json' not found at ${basePath}`));
+    }
+
+    if (packageJson?.scripts?.['start-variants-management']) {
+        return Promise.reject(new Error(`Script already exists.`));
+    }
+
+    if (!packageJson.scripts) {
+        logger?.warn(`File 'package.json' does not contain a script section. Script section added.`);
+        packageJson.scripts = {};
+    }
+
+    const urlParameters: Record<string, string> = {};
+    const sapClient = getSapClientFromPackageJson(packageJson.scripts);
+    if (sapClient) {
+        urlParameters['sap-client'] = sapClient;
+    }
+
+    const url = await getRTAUrl(basePath, getUI5UrlParameters(urlParameters));
+
+    if (!url) {
+        return Promise.reject(new Error(`No RTA editor specified in ui5.yaml.`));
+    }
+
+    packageJson.scripts['start-variants-management'] = `fiori run --open "${url}"`;
+    fs.writeJSON(packageJsonPath, packageJson);
+    logger?.debug(`Script 'start-variants-management' written to 'package.json'.`);
+    return Promise.resolve();
+}

packages/app-config-writer/src/variants-config/ui5-yaml.ts

@@ -0,0 +1,91 @@
+import { join } from 'path';
+import { MiddlewareConfigs } from '../types';
+import { FileName, type Package, readUi5Yaml } from '@sap-ux/project-access';
+import type { Editor } from 'mem-fs-editor';
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { PreviewConfigOptions } from '../types';
+import type { CustomMiddleware, FioriAppReloadConfig, UI5Config } from '@sap-ux/ui5-config';
+import { getPreviewMiddleware } from './utils';
+
+/**
+ * Gets the reload middleware form the provided yamlConfig.
+ * The middleware can either be named 'fiori-tools-appreload' or 'reload-middleware'.
+ * If the middleware is found, a delay of 300ms will be inserted.
+ *
+ * @param yamlConfig - the yaml configuration to use
+ * @returns reload middleware configuration if found or undefined
+ */
+export async function getEnhancedReloadMiddleware(
+    yamlConfig: UI5Config
+): Promise<CustomMiddleware<FioriAppReloadConfig> | undefined> {
+    const reloadMiddleware =
+        yamlConfig.findCustomMiddleware<FioriAppReloadConfig>(MiddlewareConfigs.FioriToolsAppreload) ??
+        yamlConfig.findCustomMiddleware<FioriAppReloadConfig>(MiddlewareConfigs.ReloadMiddleware);
+    if (!reloadMiddleware) {
+        return undefined;
+    }
+    if (!reloadMiddleware?.configuration?.delay) {
+        reloadMiddleware.configuration = { ...reloadMiddleware.configuration, delay: 300 };
+    }
+    return reloadMiddleware;
+}
+
+/**
+ * Creates a preview middleware configuration based on the presence of the @sap/ux-ui5-tooling dependency.
+ *
+ * @param fs - mem-fs reference to be used for file access
+ * @param basePath - path to project root, where package.json and ui5.yaml is
+ * @returns 'fiori-tools-preview' or 'preview-middleware' configuration
+ */
+export function createPreviewMiddlewareConfig(fs: Editor, basePath: string): CustomMiddleware<PreviewConfigOptions> {
+    const packageJsonPath = join(basePath, 'package.json');
+    const packageJson = fs.readJSON(packageJsonPath) as Package | undefined;
+    return {
+        name: packageJson?.devDependencies?.['@sap/ux-ui5-tooling']
+            ? MiddlewareConfigs.FioriToolsPreview
+            : MiddlewareConfigs.PreviewMiddleware,
+        afterMiddleware: 'compression'
+    } as CustomMiddleware<PreviewConfigOptions>;
+}
+
+/**
+ * Checks the project for ui5.yaml files and reads out the configuration to update the preview and reload middlewares.
+ * If a reload middleware exists, then a delay of 300ms will be inserted and the preview middleware will be set afterward.
+ *
+ * @param fs - mem-fs reference to be used for file access
+ * @param basePath - path to project root, where package.json and ui5.yaml is
+ * @param logger - logger
+ */
+export async function updateMiddlewares(fs: Editor, basePath: string, logger?: ToolsLogger): Promise<void> {
+    const ui5Yamls = [FileName.Ui5Yaml, FileName.Ui5MockYaml, FileName.Ui5LocalYaml];
+    for (const ui5Yaml of ui5Yamls) {
+        let ui5YamlConfig: UI5Config;
+
+        try {
+            ui5YamlConfig = await readUi5Yaml(basePath, ui5Yaml);
+        } catch (error) {
+            logger?.debug((error as Error).message);
+            continue;
+        }
+
+        let previewMiddleware = await getPreviewMiddleware(ui5YamlConfig);
+
+        if (!previewMiddleware) {
+            logger?.warn(`No preview middleware found in ${ui5Yaml}. Preview middleware will be added.`);
+            previewMiddleware = createPreviewMiddlewareConfig(fs, basePath);
+        }
+
+        const reloadMiddleware = await getEnhancedReloadMiddleware(ui5YamlConfig);
+
+        if (reloadMiddleware) {
+            previewMiddleware.afterMiddleware = reloadMiddleware.name;
+            ui5YamlConfig.updateCustomMiddleware(reloadMiddleware);
+            logger?.debug(`Updated reload middleware in ${ui5Yaml}.`);
+        }
+
+        ui5YamlConfig.updateCustomMiddleware(previewMiddleware);
+        const yamlPath = join(basePath, ui5Yaml);
+        fs.write(yamlPath, ui5YamlConfig.toString());
+        logger?.debug(`Updated preview middleware in ${ui5Yaml}.`);
+    }
+}

packages/app-config-writer/src/variants-config/utils.ts

@@ -0,0 +1,139 @@
+import { FileName, readUi5Yaml } from '@sap-ux/project-access';
+import { MiddlewareConfigs } from '../types';
+import { stringify } from 'querystring';
+import type { Package } from '@sap-ux/project-access';
+import type { CustomMiddleware, UI5Config } from '@sap-ux/ui5-config';
+import type { PreviewConfigOptions, FioriToolsDeprecatedPreviewConfig } from '../types';
+
+/**
+ * Gets the preview middleware form the yamlConfig or provided path.
+ * The middleware can either be named 'fiori-tools-preview' or 'preview-middleware'.
+ *
+ * @param yamlConfig - the yaml configuration to use; if not provided, the file will be read with the provided basePath and filename
+ * @param basePath - path to project root, where ui5.yaml is located
+ * @param filename - name of the ui5 yaml file to read from basePath; default is 'ui5.yaml'
+ * @returns preview middleware configuration if found or undefined
+ * @throws {Error} if filename is not found at basePath
+ * @throws {Error} if basePath and yamlConfig are undefined
+ */
+export async function getPreviewMiddleware(
+    yamlConfig?: UI5Config,
+    basePath?: string,
+    filename: string = FileName.Ui5Yaml
+): Promise<CustomMiddleware<PreviewConfigOptions> | undefined> {
+    if (!basePath && !yamlConfig) {
+        throw new Error('Either base path or yaml config must be provided');
+    }
+    yamlConfig = yamlConfig ?? (await readUi5Yaml(basePath!, filename));
+    return (
+        yamlConfig.findCustomMiddleware<PreviewConfigOptions>(MiddlewareConfigs.FioriToolsPreview) ??
+        yamlConfig.findCustomMiddleware<PreviewConfigOptions>(MiddlewareConfigs.PreviewMiddleware)
+    );
+}
+
+/**
+ * Type guard to check if the given configuration is a deprecated preview middleware configuration.
+ *
+ * @param configuration preview middleware configuration
+ * @returns true, if a preview middleware configuration is deprecated
+ */
+function isFioriToolsDeprecatedPreviewConfig(
+    configuration: PreviewConfigOptions | undefined
+): configuration is FioriToolsDeprecatedPreviewConfig {
+    return (configuration as FioriToolsDeprecatedPreviewConfig)?.component !== undefined;
+}
+
+/**
+ * Extracts sap client string from existing scripts in package.json.
+ *
+ * @param scripts - script section of the package.json
+ * @returns sap client
+ */
+export function getSapClientFromPackageJson(scripts: Package['scripts']): string | undefined {
+    for (const value of Object.values(scripts!)) {
+        const match = value?.match(/sap-client=(\d{3})/);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Returns the UI5 url parameters.
+ * This is needed for the UI5 run time adaptation.
+ *
+ * @param overwritingParams - parameters to be overwritten
+ * @returns - UI5 url parameters
+ */
+export function getUI5UrlParameters(overwritingParams: Record<string, string> = {}): string {
+    const parameters: Record<string, string> = {
+        'fiori-tools-rta-mode': 'true',
+        'sap-ui-rta-skip-flex-validation': 'true',
+        'sap-ui-xx-condense-changes': 'true'
+    };
+    return stringify(Object.assign(parameters, overwritingParams));
+}
+
+/**
+ * Returns the RTA mount point of the preview middleware configuration from the ui5.yaml file, if given.
+ *
+ * @param previewMiddlewareConfig - configuration of the preview middleware
+ * @returns - RTA mount point or undefined
+ */
+function getRTAMountPoint(previewMiddlewareConfig: PreviewConfigOptions | undefined): string | undefined {
+    if (!isFioriToolsDeprecatedPreviewConfig(previewMiddlewareConfig) && previewMiddlewareConfig?.rta?.editors) {
+        const editors = previewMiddlewareConfig.rta.editors;
+        for (const editor of editors) {
+            if (!('developerMode' in editor)) {
+                return editor.path;
+            }
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Returns the intent of the preview middleware configuration from the ui5.yaml file, if given.
+ *
+ * @param previewMiddlewareConfig - configuration of the preview middleware
+ * @returns - preview intent or undefined
+ */
+function getRTAIntent(previewMiddlewareConfig: PreviewConfigOptions | undefined): string | undefined {
+    if (isFioriToolsDeprecatedPreviewConfig(previewMiddlewareConfig)) {
+        return undefined;
+    }
+    const intent = previewMiddlewareConfig?.flp?.intent;
+    return intent ? `#${intent.object}-${intent.action}` : undefined;
+}
+
+/**
+ * Returns the url for variants management in RTA mode.
+ * The url consist of a specified mount point and intent given from the ui5.yaml file as well as parameters for the RTA mode.
+ *
+ * @param basePath - path to project root, where package.json and ui5.yaml is located
+ * @param query - query to create fragment
+ * @returns - review url parameters
+ */
+export async function getRTAUrl(basePath: string, query: string): Promise<string | undefined> {
+    let previewMiddleware: CustomMiddleware<PreviewConfigOptions> | undefined;
+    try {
+        previewMiddleware = await getPreviewMiddleware(undefined, basePath);
+    } catch (error) {
+        //todo: what to do in case there is no ui5.yaml file? try FileName.Ui5MockYaml or FileName.Ui5LocalYaml as fallback?
+        return undefined;
+    }
+
+    if (
+        previewMiddleware?.name === MiddlewareConfigs.PreviewMiddleware &&
+        !getRTAMountPoint(previewMiddleware?.configuration)
+    ) {
+        return undefined;
+    }
+    const mountPoint = getRTAMountPoint(previewMiddleware?.configuration) ?? '/preview.html';
+    const intent = getRTAIntent(previewMiddleware?.configuration) ?? '#app-preview';
+
+    return isFioriToolsDeprecatedPreviewConfig(previewMiddleware?.configuration)
+        ? `${mountPoint}?${query}#preview-app`
+        : `${mountPoint}?${query}${intent}`;
+}

packages/app-config-writer/test/fixtures/variants-config/deprecated-config/package.json

@@ -0,0 +1,9 @@
+{
+    "name": "v2-lrop-0909",
+    "description": "An SAP Fiori application.",
+    "scripts": {
+        "start-variants-management": "fiori run --open \"preview.html?fiori-tools-rta-mode=true&sap-ui-rta-skip-flex-validation=true&sap-ui-xx-condense-changes=true&sap-client=500#app-preview\""
+    },
+    "sapux": true,
+    "sapuxLayer": "VENDOR"
+}

packages/app-config-writer/test/fixtures/variants-config/deprecated-config/ui5.yaml

@@ -0,0 +1,11 @@
+specVersion: "3.1"
+metadata:
+  name: v2lrop0909
+type: application
+server:
+  customMiddleware:
+    - name: fiori-tools-preview
+      afterMiddleware: compression
+      configuration:
+        component: v2lrop0909
+        ui5Theme: sap_horizon

packages/app-config-writer/test/fixtures/variants-config/fiori-tools-config/package.json

@@ -0,0 +1,9 @@
+{
+    "name": "test-app",
+    "description": "An SAP Fiori application.",
+    "scripts": {
+        "start": "fiori run --open \"test/flpSandbox.html?sap-client=500#test-app\""
+    },
+    "sapux": true,
+    "sapuxLayer": "VENDOR"
+}

packages/app-config-writer/test/fixtures/variants-config/fiori-tools-config/ui5-local.yaml

@@ -0,0 +1,10 @@
+specVersion: "3.1"
+metadata:
+  name: fiori-tools-config
+type: application
+server:
+  customMiddleware:
+    - name: fiori-tools-appreload
+      afterMiddleware: compression
+    - name: fiori-tools-preview
+      afterMiddleware: compression