Allow loading RTA plugins for adaptation projects

packages/adp-tooling/.babelrc.json

@@ -0,0 +1,16 @@
+{
+    "ignore": [
+        "**/*.d.ts"
+    ],
+    "presets": [
+        "@babel/preset-env",
+        [
+            "transform-ui5",
+            {
+                "overridesToOverride": true
+            }
+        ],
+        "@babel/preset-typescript"
+    ],
+    "sourceMaps": true
+}

packages/adp-tooling/.eslintignore

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

packages/adp-tooling/.eslintrc.js

@@ -3,5 +3,9 @@ module.exports = {
     parserOptions: {
         project: './tsconfig.eslint.json',
         tsconfigRootDir: __dirname
+    },
+    rules: {
+        // ui5 modules are not available in file system
+        'import/no-unresolved': ['error', { ignore: ['^sap/'] }]
     }
 };

packages/adp-tooling/README.md

@@ -1,12 +1,23 @@
 #  `@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
+#### preview/client
+This is a special module that is transpiled separately to run in the browser as part of the UI5 RTA overlay. Any communication with the middleware middleware (server) code is done via http.
+
+### 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.
+
+## Development
+The standard `src` folder except the subfolder `src/preview/client` is transpiled into the dist folder. Additionally, the sources from `src/preview/client` are transpiled using babel into UI5 compatible client sources that can be used in previews to extend the runtime adaption with additional plugins. 
+
+## 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,14 @@
 const config = require('../../jest.base');
-module.exports = config;
+config.coveragePathIgnorePatterns = ['src/preview/client'];
+config.moduleNameMapper = {
+    '^sap/(.+)$': `<rootDir>/test/__mock__/sap/$1.ts`
+};
+config.transform = {
+    '^.+\\.ts$': [
+        'ts-jest',
+        {
+            tsConfig: 'tsconfig.jest.json'
+        }
+    ]
+};
+module.exports = config;

packages/adp-tooling/package.json

@@ -14,7 +14,9 @@
     "author": "@SAP/ux-tools-team",
     "main": "dist/index.js",
     "scripts": {
-        "build": "tsc --build",
+        "build": "pnpm build:server && pnpm build:client",
+        "build:server": "tsc --build",
+        "build:client": "tsc --noEmit --project src/preview/client/tsconfig.json && babel --extensions .ts ./src/preview/client -d ./dist/preview/client",
         "watch": "tsc --watch",
         "clean": "rimraf --glob dist test/test-output coverage *.tsbuildinfo",
         "format": "prettier --write '**/*.{js,json,ts,yaml,yml}' --ignore-path ../../.prettierignore",
@@ -46,6 +48,7 @@
         "yazl": "2.5.1"
     },
     "devDependencies": {
+        "@babel/cli": "7.22.10",
         "@sap-ux/project-access": "workspace:*",
         "@sap-ux/store": "workspace:*",
         "@types/ejs": "3.1.0",
@@ -55,6 +58,7 @@
         "@types/prompts": "2.0.14",
         "@types/supertest": "2.0.12",
         "@types/yazl": "2.4.2",
+        "babel-preset-transform-ui5": "7.2.4",
         "dotenv": "16.0.0",
         "express": "4.18.2",
         "nock": "13.2.1",
@@ -64,5 +68,6 @@
     "engines": {
         "pnpm": ">=6.26.1 < 7.0.0 || >=7.1.0",
         "node": ">= 14.16.0 < 15.0.0 || >=16.1.0 < 17.0.0 || >=18.0.0 < 19.0.0"
-    }
+    },
+    "browserslist": "defaults"
 }

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

@@ -1,11 +1,12 @@
 import type { ToolsLogger } from '@sap-ux/logger';
 import { ZipFile } from 'yazl';
 import type { AdpPreviewConfig, DescriptorVariant } from '../types';
-import type { NextFunction, Request, Response } from 'express';
+import type { NextFunction, Request, RequestHandler, Response, Router } from 'express';
 import type { MergedAppDescriptor } from '@sap-ux/axios-extension';
 import type { ReaderCollection } from '@ui5/fs';
 import type { UI5FlexLayer } from '@sap-ux/project-access';
 import { createAbapServiceProvider } from '@sap-ux/system-access';
+import { join } from 'path';
 
 /**
  * Create a buffer based on the given zip file object.
@@ -54,7 +55,8 @@ export class AdpPreview {
     get resources() {
         if (this.mergedDescriptor) {
             const resources = {
-                [this.mergedDescriptor.name]: this.mergedDescriptor.url
+                [this.mergedDescriptor.name]: this.mergedDescriptor.url,
+                [this.extensionScript.namespace]: this.extensionScript.namespace.split('.').join('/')
             };
             this.mergedDescriptor.asyncHints.libs.forEach((lib) => {
                 if (lib.url?.url) {
@@ -67,6 +69,17 @@ export class AdpPreview {
         }
     }
 
+    /**
+     * @returns an object with all information about the provided RTA extension script.
+     */
+    get extensionScript() {
+        return {
+            local: join(__dirname, 'client'),
+            namespace: 'adp.extension',
+            module: 'index'
+        };
+    }
+
     /**
      * Constructor taking the config and a logger as input.
      *
@@ -131,4 +144,23 @@ 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 {
+        router.get('/adp/api/fragment', (async (_req: Request, res: Response) => {
+            const files = await this.project.byGlob('/**/changes/**/*.fragment.xml');
+            try {
+                const names = files.map((file) => file.getPath());
+                res.status(200).contentType('application/json').send(JSON.stringify(names));
+                this.logger.debug(`Read fragments${JSON.stringify(names)}`);
+            } catch (error) {
+                this.logger.warn(error.message);
+                res.status(500);
+            }
+        }) as RequestHandler);
+    }
 }

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

@@ -0,0 +1,5 @@
+import type RuntimeAuthoring from 'sap/ui/rta/RuntimeAuthoring';
+
+export default (_rta: RuntimeAuthoring) => {
+    // add code to load custom plugins here
+};

packages/adp-tooling/src/preview/client/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../../tsconfig.json",
+    "include": [".", "../../../../../types/sapui5"],
+    "compilerOptions": {
+        "rootDir": ".",
+        "module": "es6",
+        "lib": ["ES2020", "dom"],
+        "allowJs": true
+    }
+}

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/test/unit/preview/adp-preview.test.ts

@@ -85,6 +85,7 @@ describe('AdaptationProject', () => {
             await adp.init(JSON.parse(descriptorVariant));
             expect(adp.descriptor).toEqual(mockMergedDescriptor);
             expect(adp.resources).toEqual({
+                'adp.extension': 'adp/extension',
                 'sap.reuse.lib': '/sap/reuse/lib',
                 'the.original.app': mockMergedDescriptor.url
             });
@@ -106,7 +107,7 @@ describe('AdaptationProject', () => {
         });
     });
     describe('proxy', () => {
-        let server!: SuperTest<Test>;
+        let server: SuperTest<Test>;
         const next = jest.fn().mockImplementation((_req, res) => res.status(200).send());
         beforeAll(async () => {
             const adp = new AdpPreview(
@@ -132,7 +133,7 @@ describe('AdaptationProject', () => {
             app.get(`${mockMergedDescriptor.url}/original.file`, next);
             app.use((req) => fail(`${req.path} should have been intercepted.`));
 
-            server = await supertest(app);
+            server = supertest(app);
         });
 
         test('/manifest.json', async () => {
@@ -161,4 +162,37 @@ describe('AdaptationProject', () => {
             expect(next).toBeCalled();
         });
     });
+    describe('addApis', () => {
+        let server!: SuperTest<Test>;
+        beforeAll(async () => {
+            const adp = new AdpPreview(
+                {
+                    target: {
+                        url: backend
+                    }
+                },
+                mockProject as unknown as ReaderCollection,
+                logger
+            );
+
+            const app = express();
+            adp.addApis(app);
+            server = await supertest(app);
+        });
+
+        test('/adp/api/fragment', async () => {
+            const expectedNames = ['/changes/fragments/my.fragment.xml', '/changes/other/path/other.fragment.xml'];
+            mockProject.byGlob.mockResolvedValueOnce([
+                {
+                    getPath: () => expectedNames[0]
+                },
+                {
+                    getPath: () => expectedNames[1]
+                }
+            ]);
+            const response = await server.get('/adp/api/fragment').expect(200);
+            const names = JSON.parse(response.text);
+            expect(names).toEqual(expectedNames);
+        });
+    });
 });

packages/adp-tooling/tsconfig.eslint.json

@@ -1,4 +1,5 @@
 {
     "extends": "./tsconfig.json",
-    "include": ["src", "test", ".eslintrc.js"]
+    "include": ["src", "test", ".eslintrc.js"],
+    "exclude": []
 }

packages/adp-tooling/tsconfig.jest.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": [
+        "../../types/ui5.d.ts",
+        "../../types/mem-fs-editor.d.ts",
+        "../../types/sapui5",
+        "src"
+    ]
+}

packages/adp-tooling/tsconfig.json

@@ -5,6 +5,9 @@
         "../../types/mem-fs-editor.d.ts",
         "src"
     ],
+    "exclude": [
+        "src/preview/client"
+      ],
     "compilerOptions": {
         "rootDir": "src",
         "outDir": "dist"

packages/preview-middleware/package.json

@@ -17,7 +17,7 @@
         "start:fixture": "ui5 serve --config test/fixtures/simple-app/ui5.yaml",
         "build": "tsc --build",
         "watch": "tsc --watch",
-        "clean": "rimraf dist test/test-output coverage *.tsbuildinfo",
+        "clean": "rimraf --glob dist test/test-output coverage *.tsbuildinfo",
         "format": "prettier --write '**/*.{js,json,ts,yaml,yml}' --ignore-path ../../.prettierignore",
         "lint": "eslint . --ext .ts",
         "lint:fix": "eslint . --ext .ts --fix",

packages/preview-middleware/src/base/flp.ts

@@ -67,6 +67,7 @@ export interface TemplateConfig {
     flex?: {
         layer: UI5FlexLayer;
         developerMode: boolean;
+        pluginModule?: string;
     };
     locateReuseLibsScript?: string;
 }
@@ -155,6 +156,7 @@ export class FlpSandbox {
                 if (this.config.rta?.layer) {
                     config.flex = {
                         layer: this.config.rta?.layer,
+                        pluginModule: this.config.rta?.pluginModule,
                         developerMode: fioriToolsRtaMode === 'forAdaptation'
                     };
                 } else {

packages/preview-middleware/src/types/index.ts

@@ -30,6 +30,10 @@ export interface FlpConfig {
     intent: Intent;
     rta?: {
         layer?: UI5FlexLayer;
+        /**
+         * Optional UI5 module exporting as default a function that adds RTA plugins
+         */
+        pluginModule?: string;
     };
     /**
      * Optional: if set to true then a locate-reuse-libs script will be attached to the html

packages/preview-middleware/src/ui5/middleware.ts

@@ -6,6 +6,7 @@ import type { AdpPreviewConfig } from '@sap-ux/adp-tooling';
 import type { Config } from '../types';
 import { AdpPreview } from '@sap-ux/adp-tooling';
 import type { ReaderCollection } from '@ui5/fs';
+import { static as serveStatic } from 'express';
 
 /**
  * Initialize the preview for an adaptation project.
@@ -20,9 +21,20 @@ async function initAdp(rootProject: ReaderCollection, config: AdpPreviewConfig,
     if (appVariant) {
         const adp = new AdpPreview(config, rootProject, logger);
         const layer = await adp.init(JSON.parse(await appVariant.getString()));
-        flp.config.rta = { layer };
+        flp.config.rta = {
+            layer,
+            pluginModule: `${adp.extensionScript.namespace.replace('.', '/')}/${adp.extensionScript.module}`
+        };
+
+        const ns = adp.extensionScript.namespace.split('.');
+        const path = flp.config.path.split('/');
+        path.pop();
+        ns.forEach((segment) => path.push(segment));
+
         await flp.init(adp.descriptor.manifest, adp.descriptor.name, adp.resources);
         flp.router.use(adp.descriptor.url, adp.proxy.bind(adp) as RequestHandler);
+        flp.router.use(path.join('/'), serveStatic(adp.extensionScript.local));
+        adp.addApis(flp.router);
     } else {
         throw new Error('ADP configured but no manifest.appdescr_variant found.');
     }

packages/preview-middleware/templates/flp/sandbox.html

@@ -63,7 +63,7 @@
                 sap.ushell.Container.getServiceAsync('AppLifeCycle').then((serviceInstance) => {
                     serviceInstance.attachAppLoaded((event) => {
                         var oView = event.getParameter('componentInstance');
-                        sap.ui.require(["sap/ui/rta/api/startAdaptation"], async function (startAdaptation) {
+                        sap.ui.require(["sap/ui/rta/api/startAdaptation"<% if (locals.flex?.pluginModule) { %>, "<%- flex.pluginModule %>"<% } %>], async function (startAdaptation<% if (locals.flex?.pluginModule) { %>, loadPlugin<% } %>) {
                             var options = {
                                 rootControl: oView,
                                 validateAppVersion: false,
@@ -72,7 +72,7 @@
                                     developerMode: <%- flex.developerMode %>
 								}
                             };
-                            await startAdaptation(options);
+                            await startAdaptation(options<% if (locals.flex?.pluginModule) { %>, loadPlugin<% } %>);
                         });
                     })
                 });