feat(adaptation-project): Add Fragment enhancement

.changeset/loud-insects-tease.md

@@ -0,0 +1,7 @@
+---
+'@sap-ux-private/preview-middleware-client': minor
+'@sap-ux/preview-middleware': minor
+'@sap-ux/adp-tooling': minor
+---
+
+Enhancing the preview-middleware with new functionality such as adding an XML Fragment (creating "addXML" change).

packages/adp-tooling/.eslintignore

@@ -1,2 +1,2 @@
 test/fixtures
-dist
+dist

packages/adp-tooling/README.md

@@ -1,12 +1,17 @@
 #  `@sap-ux/adp-tooling`
 
-Module containing different tooling modules helpful when working with SAP UI5 adaptation projects.
+A module containing different tooling modules helpful when working with SAP UI5 adaptation projects.
 
-## preview
+## Submodules
+
+### preview
 The submodule preview contains functionality allowing to preview adaptation projects. It is not a standalone UI5 middleware but designed to be integrated into the `@sap-ux/preview-middleware.`.
 
-## writer
+### writer
 The submodule writer contains functionality to generate the core project structure of an SAP UI5 adaptation project. It is not a standalone generator but designed to be integrated into `@sap-ux/create` or any kind of yeoman generator.
 
-## base
-The submodule contains functionality required in different scenarios, e.g. prompting for generation or when initializing the preview.
+### base
+The submodule contains functionality required in different scenarios, e.g. prompting for generation or when initializing the preview.
+
+## Templates
+The templates folder contains ejs templates to be used for the generation of new adaptation projects as well as to generate artifacts in existing adaptation projects.

packages/adp-tooling/jest.config.js

@@ -1,2 +1,2 @@
 const config = require('../../jest.base');
-module.exports = config;
+module.exports = config;

packages/adp-tooling/package.json

@@ -39,6 +39,7 @@
         "@sap-ux/logger": "workspace:*",
         "@sap-ux/system-access": "workspace:*",
         "@sap-ux/ui5-config": "workspace:*",
+        "sanitize-filename": "1.6.3",
         "ejs": "3.1.9",
         "mem-fs": "2.1.0",
         "mem-fs-editor": "9.4.0",

packages/adp-tooling/src/preview/adp-preview.ts

@@ -1,11 +1,21 @@
-import type { ToolsLogger } from '@sap-ux/logger';
+import express from 'express';
 import { ZipFile } from 'yazl';
-import type { AdpPreviewConfig, DescriptorVariant } from '../types';
-import type { NextFunction, Request, Response } from 'express';
-import type { MergedAppDescriptor } from '@sap-ux/axios-extension';
 import type { ReaderCollection } from '@ui5/fs';
+import type { MiddlewareUtils } from '@ui5/server';
+import type { NextFunction, Request, Response, Router, RequestHandler } from 'express';
+
+import type { ToolsLogger } from '@sap-ux/logger';
 import type { UI5FlexLayer } from '@sap-ux/project-access';
 import { createAbapServiceProvider } from '@sap-ux/system-access';
+import type { MergedAppDescriptor } from '@sap-ux/axios-extension';
+
+import RoutesHandler from './routes-handler';
+import type { AdpPreviewConfig, DescriptorVariant } from '../types';
+
+export const enum ApiRoutes {
+    FRAGMENT = '/adp/api/fragment',
+    CONTROLLER = '/adp/api/controller'
+}
 
 /**
  * Create a buffer based on the given zip file object.
@@ -36,6 +46,10 @@ export class AdpPreview {
      * Merged descriptor variant with reference app manifest
      */
     private mergedDescriptor: MergedAppDescriptor;
+    /**
+     * Routes handler class to handle API requests
+     */
+    private routesHandler: RoutesHandler;
 
     /**
      * @returns merged manifest.
@@ -72,13 +86,17 @@ export class AdpPreview {
      *
      * @param config adp config
      * @param project reference to the root of the project
+     * @param util middleware utilities provided by the UI5 CLI
      * @param logger logger instance
      */
     constructor(
         private readonly config: AdpPreviewConfig,
         private readonly project: ReaderCollection,
+        private readonly util: MiddlewareUtils,
         private readonly logger: ToolsLogger
-    ) {}
+    ) {
+        this.routesHandler = new RoutesHandler(project, util, logger);
+    }
 
     /**
      * Fetch all required configurations from the backend and initialize all configurations.
@@ -131,4 +149,17 @@ export class AdpPreview {
             }
         }
     }
+
+    /**
+     * Add additional APIs to the router that are required for adaptation projects only.
+     *
+     * @param router router that is to be enhanced with the API
+     */
+    addApis(router: Router): void {
+        /**
+         * FRAGMENT Routes
+         */
+        router.get(ApiRoutes.FRAGMENT, this.routesHandler.handleReadAllFragments as RequestHandler);
+        router.post(ApiRoutes.FRAGMENT, express.json(), this.routesHandler.handleWriteFragment as RequestHandler);
+    }
 }

packages/adp-tooling/src/preview/routes-handler.ts

@@ -0,0 +1,115 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import sanitize from 'sanitize-filename';
+import type { ReaderCollection } from '@ui5/fs';
+import type { ToolsLogger } from '@sap-ux/logger';
+import type { MiddlewareUtils } from '@ui5/server';
+import type { NextFunction, Request, Response } from 'express';
+
+import { FolderNames, TemplateFileName, HttpStatusCodes } from '../types';
+
+interface WriteFragmentBody {
+    fragmentName: string;
+}
+
+/**
+ * @description Handles API Routes
+ */
+export default class RoutesHandler {
+    /**
+     * Constructor taking project as input.
+     *
+     * @param project Reference to the root of the project
+     * @param util middleware utilities provided by the UI5 CLI
+     * @param logger Logger instance
+     */
+    constructor(
+        private readonly project: ReaderCollection,
+        private readonly util: MiddlewareUtils,
+        private readonly logger: ToolsLogger
+    ) {}
+
+    /**
+     * Handler for reading all fragment files from the workspace.
+     *
+     * @param _ Request
+     * @param res Response
+     * @param next Next Function
+     */
+    public handleReadAllFragments = async (_: Request, res: Response, next: NextFunction) => {
+        try {
+            const files = await this.project.byGlob('/**/changes/**/*.fragment.xml');
+
+            if (!files || files.length === 0) {
+                res.status(HttpStatusCodes.OK)
+                    .contentType('application/json')
+                    .send({ fragments: [], message: `No fragments found in the project workspace.` });
+                return;
+            }
+
+            const fragments = files.map((f) => ({
+                fragmentName: f.getName()
+            }));
+
+            res.status(HttpStatusCodes.OK)
+                .contentType('application/json')
+                .send({
+                    fragments,
+                    message: `${fragments.length} fragments found in the project workspace.`
+                });
+            this.logger.debug(`Read fragments ${JSON.stringify(fragments)}`);
+        } catch (e) {
+            this.logger.error(e.message);
+            res.status(HttpStatusCodes.INTERNAL_SERVER_ERROR).send({ message: e.message });
+            next(e);
+        }
+    };
+
+    /**
+     * Handler for writing a fragment file to the workspace.
+     *
+     * @param req Request
+     * @param res Response
+     * @param next Next Function
+     */
+    public handleWriteFragment = async (req: Request, res: Response, next: NextFunction) => {
+        try {
+            const data = req.body as WriteFragmentBody;
+
+            const fragmentName = sanitize(data.fragmentName);
+
+            const sourcePath = this.util.getProject().getSourcePath();
+
+            if (fragmentName) {
+                const fullPath = path.join(sourcePath, FolderNames.Changes, FolderNames.Fragments);
+                const filePath = path.join(fullPath, `${fragmentName}.fragment.xml`);
+
+                if (!fs.existsSync(fullPath)) {
+                    fs.mkdirSync(fullPath);
+                }
+
+                if (fs.existsSync(filePath)) {
+                    res.status(HttpStatusCodes.CONFLICT).send(`Fragment with name "${fragmentName}" already exists`);
+                    this.logger.debug(`XML Fragment with name "${fragmentName}" was created`);
+                    return;
+                }
+
+                // Copy the template XML Fragment to the project's workspace
+                const fragmentTemplatePath = path.join(__dirname, '../../templates/rta', TemplateFileName.Fragment);
+                fs.copyFileSync(fragmentTemplatePath, filePath);
+
+                const message = 'XML Fragment created';
+                res.status(HttpStatusCodes.CREATED).send(message);
+                this.logger.debug(`XML Fragment with name "${fragmentName}" was created`);
+            } else {
+                res.status(HttpStatusCodes.BAD_REQUEST).send('Fragment name was not provided!');
+                this.logger.debug('Bad request. Fragment name was not provided!');
+            }
+        } catch (e) {
+            const sanitizedMsg = sanitize(e.message);
+            this.logger.error(sanitizedMsg);
+            res.status(HttpStatusCodes.INTERNAL_SERVER_ERROR).send(sanitizedMsg);
+            next(e);
+        }
+    };
+}

packages/adp-tooling/src/types.ts

@@ -39,3 +39,44 @@ export interface AdpWriterConfig {
         description?: string;
     };
 }
+
+export interface ManifestAppdescr {
+    fileName: string;
+    layer: string;
+    fileType: string;
+    reference: string;
+    id: string;
+    namespace: string;
+    version: string;
+    content: Content[];
+}
+
+export interface Content {
+    changeType: string;
+    content: object;
+    texts?: object;
+}
+
+export const enum FolderNames {
+    Changes = 'changes',
+    Fragments = 'fragments'
+}
+
+export const enum TemplateFileName {
+    Fragment = 'fragment.xml'
+}
+
+export const enum HttpStatusCodes {
+    OK = 200,
+    CREATED = 201,
+    NO_CONTENT = 204,
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    METHOD_NOT_ALLOWED = 405,
+    CONFLICT = 409,
+    INTERNAL_SERVER_ERROR = 500,
+    NOT_IMPLEMETED = 501,
+    SERVICE_UNAVAILABLE = 503
+}

packages/adp-tooling/src/writer/index.ts

@@ -39,7 +39,7 @@ export async function generate(basePath: string, config: AdpWriterConfig, fs?: E
     if (!fs) {
         fs = create(createStorage());
     }
-    const tmplPath = join(__dirname, '../../templates');
+    const tmplPath = join(__dirname, '../../templates/project');
     const fullConfig = setDefaults(config);
 
     fs.copyTpl(join(tmplPath, '**/*.*'), join(basePath), fullConfig, undefined, {

packages/adp-tooling/templates/rta/fragment.xml

@@ -0,0 +1,4 @@
+<!-- Use stable and unique IDs!-->
+<core:FragmentDefinition xmlns:core='sap.ui.core' xmlns='sap.m'>
+    <!--  add your xml here -->
+</core:FragmentDefinition>