@underpostnet/cyberia 3.2.80

package/src/client-builder/client-dev-server.js

@@ -0,0 +1,88 @@
+/**
+ * Module for creating a client-side development server
+ * @module src/client-builder/client-dev-server.js
+ * @namespace clientDevServer
+ */
+import fs from 'fs-extra';
+import nodemon from 'nodemon';
+import dotenv from 'dotenv';
+import { shellExec } from '../server/process.js';
+import { loggerFactory } from '../server/logger.js';
+import Underpost from '../index.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @function createClientDevServer
+ * @description Creates a client-side development server.
+ * @memberof clientDevServer
+ * @param {string} deployId - The deployment ID.
+ * @param {string} subConf - The sub-configuration.
+ * @param {string} host - The host.
+ * @param {string} path - The path.
+ * @returns {void}
+ * @memberof clientDevServer
+ */
+const createClientDevServer = async (
+  deployId = process.argv[2] || 'dd-default',
+  subConf = process.argv[3] || '',
+  host = process.argv[4] || 'default.net',
+  path = process.argv[5] || '/',
+) => {
+  const devClientEnvPath = `./engine-private/conf/${deployId}/.env.${process.env.NODE_ENV}.${subConf}-dev-client`;
+  if (fs.existsSync(devClientEnvPath)) dotenv.config({ path: devClientEnvPath, override: true });
+
+  await Underpost.repo.client(deployId, `${subConf}-dev-client`.trim(), host, path);
+
+  shellExec(`node src/server ${deployId} ${subConf}-dev-client`.trim(), {
+    async: true,
+  });
+
+  // https://github.com/remy/nodemon/blob/main/doc/events.md
+
+  // States
+  // start - child process has started
+  // crash - child process has crashed (nodemon will not emit exit)
+  // exit - child process has cleanly exited (ie. no crash)
+  // restart([ array of files triggering the restart ]) - child process has restarted
+  // config:update - nodemon's config has changed
+
+  if (fs.existsSync(`/tmp/client.build.json`)) fs.removeSync(`/tmp/client.build.json`);
+
+  let buildPathScope = [];
+
+  const nodemonOptions = {
+    script: './src/client.build',
+    args: [`${deployId}`, `${subConf}-dev-client`, `${host}`, `${path}`],
+    watch: 'src/client',
+  };
+  logger.info('nodemon option', { nodemonOptions });
+  nodemon(nodemonOptions)
+    .on('start', function (...args) {
+      logger.info(args, 'nodemon started');
+    })
+    .on('restart', function (...args) {
+      logger.info(args, 'nodemon restart');
+      const eventPath = args[0][0];
+      const indexPath = buildPathScope.findIndex((buildObjScope) => buildObjScope.path === eventPath);
+      const buildObj = {
+        timestamp: new Date().getTime(),
+        path: eventPath,
+      };
+      if (indexPath > -1) {
+        buildPathScope[indexPath].timestamp = buildObj.timestamp;
+      } else buildPathScope.push(buildObj);
+      setTimeout(() => {
+        buildPathScope = buildPathScope.filter((buildObjScope) => buildObjScope.timestamp !== buildObj.timestamp);
+      }, 2500);
+      const buildPathScopeBuild = buildPathScope.map((o) => o.path);
+      logger.info('buildPathScopeBuild', buildPathScopeBuild);
+      fs.writeFileSync(`/tmp/client.build.json`, JSON.stringify(buildPathScopeBuild, null, 4));
+    })
+    .on('crash', function (error) {
+      if (error) logger.error(error, error.message || 'nodemon crash');
+      else logger.error('nodemon process crashed');
+    });
+};
+
+export { createClientDevServer };

package/src/client-builder/client-formatted.js

@@ -0,0 +1,170 @@
+/**
+ * Module for formatting client-side code using esbuild for import rewriting and minification.
+ * @module src/server/client-formatted.js
+ * @namespace clientFormatted
+ */
+
+'use strict';
+
+import * as esbuild from 'esbuild';
+import fs from 'fs-extra';
+import * as path from 'path';
+
+/**
+ * Escapes a string for safe use inside a RegExp.
+ * @param {string} s - The string to escape.
+ * @returns {string} The escaped string.
+ * @memberof clientFormatted
+ */
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Formats a source code string by removing 'html`' and 'css`' tagged template prefixes.
+ * Used for SSR VM execution where the full esbuild pipeline is not needed.
+ * @param {string} src - The source code string.
+ * @returns {string} The formatted source code.
+ * @memberof clientFormatted
+ */
+const srcFormatted = (src) => src.replace(/(?<=[\s({[,;=+!?:^])(html|css)`/g, '`');
+
+const resolveBrowserImportPath = (basePrefix, relativePath) => {
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(basePrefix)) {
+    return new URL(relativePath, basePrefix.endsWith('/') ? basePrefix : `${basePrefix}/`).toString();
+  }
+  return path.posix.normalize(`${basePrefix}${relativePath}`);
+};
+
+/**
+ * Converts a JavaScript object into a string that can be embedded in client-side code
+ * and parsed back into an object (e.g., 'JSON.parse(`{...}`)').
+ * Escapes backticks and template expression markers for safe template literal embedding.
+ * @param {*} data - The data to be stringified.
+ * @returns {string} A string representing the code to parse the JSON data.
+ * @memberof clientFormatted
+ */
+const JSONweb = (data) => {
+  const json = JSON.stringify(data).replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+  return 'JSON.parse(`' + json + '`)';
+};
+
+/**
+ * Creates an esbuild plugin that rewrites import paths for browser consumption.
+ * Handles dist library imports, relative imports, and marks all remaining imports as external.
+ * @param {object} options
+ * @param {Array<object>} [options.dists=[]] - Distribution objects with import_name and import_name_build.
+ * @param {string} options.proxyPath - The proxy path for the application.
+ * @param {string} [options.basePath=''] - The base path for the module type (e.g., 'components', 'services').
+ * @param {string} [options.module=''] - The module/component name for relative import resolution.
+ * @param {string} [options.baseHost=''] - The base host URL.
+ * @returns {import('esbuild').Plugin}
+ * @memberof clientFormatted
+ */
+const importRewritePlugin = ({
+  dists = [],
+  proxyPath,
+  basePath = '',
+  module = '',
+  baseHost = '',
+  externalizeBareImports = true,
+}) => ({
+  name: 'import-rewrite',
+  setup(build) {
+    const prefix = `${baseHost}${proxyPath !== '/' ? `${proxyPath}/` : '/'}`;
+
+    // Rewrite dist library imports (e.g., '@neodrag/vanilla' → '/proxyPath/dist/@neodrag-vanilla/index.js')
+    if (dists) {
+      for (const dist of dists) {
+        if (!dist.import_name) continue;
+        const filter = new RegExp(`^${escapeRegExp(dist.import_name)}$`);
+        build.onResolve({ filter }, () => ({
+          path: `${baseHost}${proxyPath !== '/' ? proxyPath : ''}${dist.import_name_build}`,
+          external: true,
+        }));
+      }
+    }
+
+    // Rewrite app-relative imports to absolute paths based on proxy path and module.
+    // Do not touch node_modules relative imports so esbuild can bundle package internals.
+    build.onResolve({ filter: /^\.\.?\// }, (args) => {
+      const normalizedImporter = (args.importer || '').replace(/\\/g, '/');
+      if (!normalizedImporter.includes('/src/client/')) {
+        return;
+      }
+
+      // Extract the path relative to /src/client/
+      // Handle cases where the path might have duplicates or be in various formats
+      const srcClientIndex = normalizedImporter.lastIndexOf('/src/client/');
+      if (srcClientIndex === -1) {
+        return;
+      }
+      const importerFromClientRoot = normalizedImporter.substring(srcClientIndex + '/src/client/'.length);
+      const importerDir = path.posix.dirname(importerFromClientRoot);
+      const resolvedFromClientRoot = path.posix.normalize(path.posix.join(importerDir, args.path));
+      const result = resolveBrowserImportPath(prefix, resolvedFromClientRoot);
+
+      return {
+        path: result,
+        external: true,
+      };
+    });
+
+    // For client app modules we externalize bare imports; for SW builds we let esbuild bundle them.
+    build.onResolve({ filter: /.*/ }, (args) => {
+      if (args.kind === 'entry-point') return;
+      if (!externalizeBareImports) return;
+      return { path: args.path, external: true };
+    });
+  },
+});
+
+/**
+ * Transforms a JavaScript source file using esbuild with import path rewriting,
+ * tagged template stripping, and optional minification.
+ * Replaces the previous srcFormatted + componentFormatted/viewFormatted + UglifyJS pipeline.
+ * @param {string} srcPath - Path to the source file.
+ * @param {object} options
+ * @param {Array<object>} [options.dists=[]] - Distribution objects with import names.
+ * @param {string} options.proxyPath - The proxy path for the application.
+ * @param {string} [options.basePath=''] - Base path for the module type (e.g., 'components', 'services').
+ * @param {string} [options.module=''] - Module name for relative import resolution.
+ * @param {string} [options.baseHost=''] - Base host URL.
+ * @param {boolean} [options.minify=false] - Whether to minify the output.
+ * @returns {Promise<string>} The transformed source code.
+ * @memberof clientFormatted
+ */
+const transformClientJs = async (
+  srcPath,
+  {
+    dists = [],
+    proxyPath,
+    basePath = '',
+    module = '',
+    baseHost = '',
+    minify: shouldMinify = false,
+    externalizeBareImports = true,
+  } = {},
+) => {
+  const src = fs.readFileSync(srcPath, 'utf8');
+  const stripped = srcFormatted(src);
+
+  const result = await esbuild.build({
+    stdin: {
+      contents: stripped,
+      loader: 'js',
+      resolveDir: path.dirname(path.resolve(srcPath)),
+      sourcefile: srcPath,
+    },
+    bundle: true,
+    write: false,
+    format: 'esm',
+    platform: 'browser',
+    target: 'esnext',
+    minify: shouldMinify,
+    logLevel: 'warning',
+    plugins: [importRewritePlugin({ dists, proxyPath, basePath, module, baseHost, externalizeBareImports })],
+  });
+
+  return result.outputFiles[0].text;
+};
+
+export { srcFormatted, JSONweb, transformClientJs };

package/src/client-builder/client-icons.js

@@ -0,0 +1,108 @@
+/**
+ * Module for building client-side icons
+ * @module src/client-builder/client-icons.js
+ * @namespace clientIcons
+ */
+import { favicons } from 'favicons';
+import { loggerFactory } from '../server/logger.js';
+import fs from 'fs-extra';
+import { getCapVariableName } from '../client/components/core/CommonJs.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * @function buildIcons
+ * @description Builds icons for a client-side application.
+ * @memberof clientIcons
+ * @param {Object} metadata - The metadata for the client-side application.
+ * @param {string} metadata.title - The title of the client-side application.
+ * @param {string} metadata.description - The description of the client-side application.
+ * @param {string} metadata.keywords - The keywords for the client-side application.
+ * @param {string} metadata.author - The author of the client-side application.
+ * @param {string} metadata.thumbnail - The thumbnail of the client-side application.
+ * @param {string} metadata.themeColor - The theme color of the client-side application.
+ * @param {string} metadata.baseBuildIconReference - The base build icon reference for the client-side application.
+ * @returns {Promise<void>}
+ */
+const buildIcons = async ({
+  publicClientId,
+  metadata: { title, description, keywords, author, thumbnail, themeColor, baseBuildIconReference },
+}) => {
+  const source = baseBuildIconReference
+    ? baseBuildIconReference
+    : `src/client/public/${publicClientId}/assets/logo/base-icon.png`; // Source image(s). `string`, `buffer` or array of `string`
+
+  const configuration = {
+    path: '/', // Path for overriding default icons path. `string`
+    appName: title ? title : null, // Your application's name. `string`
+    appShortName: title ? title : null, // Your application's short_name. `string`. Optional. If not set, appName will be used
+    appDescription: description ? description : null, // Your application's description. `string`
+    developerName: author ? author : null, // Your (or your developer's) name. `string`
+    developerURL: author ? author : null, // Your (or your developer's) URL. `string`
+    cacheBustingQueryParam: null, // Query parameter added to all URLs that acts as a cache busting system. `string | null`
+    dir: 'auto', // Primary text direction for name, short_name, and description
+    lang: 'en-US', // Primary language for name and short_name
+    background: themeColor ? themeColor : '#fff', // Background colour for flattened icons. `string`
+    theme_color: themeColor ? themeColor : '#fff', // Theme color user for example in Android's task switcher. `string`
+    appleStatusBarStyle: 'black-translucent', // Style for Apple status bar: "black-translucent", "default", "black". `string`
+    display: 'standalone', // Preferred display mode: "fullscreen", "standalone", "minimal-ui" or "browser". `string`
+    orientation: 'any', // Default orientation: "any", "natural", "portrait" or "landscape". `string`
+    scope: '/', // set of URLs that the browser considers within your app
+    start_url: '/?homescreen=1', // Start URL when launching the application from a device. `string`
+    preferRelatedApplications: false, // Should the browser prompt the user to install the native companion app. `boolean`
+    relatedApplications: undefined, // Information about the native companion apps. This will only be used if `preferRelatedApplications` is `true`. `Array<{ id: string, url: string, platform: string }>`
+    version: '1.0', // Your application's version string. `string`
+    pixel_art: false, // Keeps pixels "sharp" when scaling up, for pixel art.  Only supported in offline mode.
+    loadManifestWithCredentials: true, // Browsers don't send cookies when fetching a manifest, enable this to fix that. `boolean`
+    manifestMaskable: true, // Maskable source image(s) for manifest.json. "true" to use default source. More information at https://web.dev/maskable-icon/. `boolean`, `string`, `buffer` or array of `string`
+    icons: {
+      // Platform Options:
+      // - offset - offset in percentage
+      // - background:
+      //   * false - use default
+      //   * true - force use default, e.g. set background for Android icons
+      //   * color - set background for the specified icons
+      //
+      android: true, // Create Android homescreen icon. `boolean` or `{ offset, background }` or an array of sources
+      appleIcon: true, // Create Apple touch icons. `boolean` or `{ offset, background }` or an array of sources
+      appleStartup: true, // Create Apple startup images. `boolean` or `{ offset, background }` or an array of sources
+      favicons: true, // Create regular favicons. `boolean` or `{ offset, background }` or an array of sources
+      windows: true, // Create Windows 8 tile icons. `boolean` or `{ offset, background }` or an array of sources
+      yandex: true, // Create Yandex browser icon. `boolean` or `{ offset, background }` or an array of sources
+    },
+    shortcuts: [
+      // Your applications's Shortcuts (see: https://developer.mozilla.org/docs/Web/Manifest/shortcuts)
+      // Array of shortcut objects:
+      // {
+      //   name: 'View your Inbox', // The name of the shortcut. `string`
+      //   short_name: 'inbox', // optionally, falls back to name. `string`
+      //   description: 'View your inbox messages', // optionally, not used in any implemention yet. `string`
+      //   url: '/inbox', // The URL this shortcut should lead to. `string`
+      //   icon: 'test/inbox_shortcut.png', // source image(s) for that shortcut. `string`, `buffer` or array of `string`
+      // },
+      // more shortcuts objects
+    ],
+  };
+
+  try {
+    const response = await favicons(source, configuration);
+
+    // console.log(response.images); // Array of { name: string, contents: <buffer> }
+    // console.log(response.files); // Array of { name: string, contents: <string> }
+    // console.log(response.html); // Array of strings (html elements)
+
+    for (const image of response.images)
+      fs.writeFileSync(`./src/client/public/${publicClientId}/${image.name}`, image.contents);
+
+    for (const file of response.files)
+      fs.writeFileSync(`./src/client/public/${publicClientId}/${file.name}`, file.contents, 'utf8');
+
+    const ssrPath = `./src/client/ssr/head/Pwa${getCapVariableName(publicClientId)}.js`;
+    if (!fs.existsSync(ssrPath))
+      fs.writeFileSync(ssrPath, 'SrrComponent = () => html`' + response.html.join(`\n`) + '`;', 'utf8');
+  } catch (error) {
+    logger.error(error.message); // Error description e.g. "An unknown error has occurred"
+  }
+};
+
+export { buildIcons };

package/src/client-builder/ssr.js

@@ -0,0 +1,124 @@
+/**
+ * Module for managing server side rendering
+ * @module src/client-builder/ssr.js
+ * @namespace ServerSideRendering
+ */
+
+import fs from 'fs-extra';
+import vm from 'node:vm';
+
+import Underpost from '../index.js';
+
+import { srcFormatted, JSONweb } from './client-formatted.js';
+import { loggerFactory } from '../server/logger.js';
+import { getRootDirectory } from '../server/process.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Creates a server-side rendering component function from a given file path.
+ * It reads the component file, formats it, and executes it in a sandboxed Node.js VM context to extract the component.
+ * @param {string} [componentPath='./src/client/ssr/RootDocument.js'] - The path to the SSR component file.
+ * @returns {Promise<Function>} A promise that resolves to the SSR component function.
+ * @memberof ServerSideRendering
+ */
+const ssrFactory = async (componentPath = `./src/client/ssr/RootDocument.js`) => {
+  const context = { SrrComponent: () => {}, npm_package_version: Underpost.version };
+  vm.createContext(context);
+  vm.runInContext(await srcFormatted(fs.readFileSync(componentPath, 'utf8')), context);
+  return context.SrrComponent;
+};
+
+/**
+ * Sanitizes an HTML string by adding a nonce to all script and style tags for Content Security Policy (CSP).
+ * The nonce is retrieved from `res.locals.nonce`.
+ * @param {object} res - The Express response object.
+ * @param {object} req - The Express request object.
+ * @param {string} html - The HTML string to sanitize.
+ * @returns {string} The sanitized HTML string with nonces.
+ * @memberof ServerSideRendering
+ */
+const sanitizeHtml = (res, req, html) => {
+  const nonce = res.locals.nonce;
+
+  return html
+    .replace(/<script(?=\s|>)/gi, `<script nonce="${nonce}"`)
+    .replace(/<style(?=\s|>)/gi, `<style nonce="${nonce}"`);
+};
+
+/**
+ * Factory function to create Express middleware for handling 404 and 500 errors.
+ * It generates server-side rendered HTML for these error pages. If static error pages exist, it redirects to them.
+ * @param {object} options - The options for creating the middleware.
+ * @param {object} options.app - The Express app instance.
+ * @param {string} options.directory - The directory for the instance's static files.
+ * @param {string} options.rootHostPath - The root path for the host's public files.
+ * @param {string} options.path - The base path for the instance.
+ * @returns {Promise<{error500: Function, error400: Function}>} A promise that resolves to an object containing the 500 and 404 error handling middleware.
+ * @memberof ServerSideRendering
+ */
+const ssrMiddlewareFactory = async ({ app, directory, rootHostPath, path }) => {
+  const Render = await ssrFactory();
+  const ssrPath = path === '/' ? path : `${path}/`;
+
+  // Build default html src for 404 and 500
+
+  const defaultHtmlSrc404 = Render({
+    title: '404 Not Found',
+    ssrPath,
+    ssrHeadComponents: '',
+    ssrBodyComponents: (await ssrFactory(`./src/client/ssr/body/404.js`))(),
+    renderPayload: {
+      apiBasePath: process.env.BASE_API,
+      version: Underpost.version,
+    },
+    renderApi: {
+      JSONweb,
+    },
+  });
+  const path404 = `${directory ? directory : `${getRootDirectory()}${rootHostPath}`}/404/index.html`;
+  const page404 = fs.existsSync(path404) ? `${path === '/' ? '' : path}/404` : undefined;
+
+  const defaultHtmlSrc500 = Render({
+    title: '500 Server Error',
+    ssrPath,
+    ssrHeadComponents: '',
+    ssrBodyComponents: (await ssrFactory(`./src/client/ssr/body/500.js`))(),
+    renderPayload: {
+      apiBasePath: process.env.BASE_API,
+      version: Underpost.version,
+    },
+    renderApi: {
+      JSONweb,
+    },
+  });
+  const path500 = `${directory ? directory : `${getRootDirectory()}${rootHostPath}`}/500/index.html`;
+  const page500 = fs.existsSync(path500) ? `${path === '/' ? '' : path}/500` : undefined;
+
+  return {
+    error500: function (err, req, res, next) {
+      logger.error(err, err.stack);
+      if (page500) return res.status(500).redirect(page500);
+      else {
+        res.set('Content-Type', 'text/html');
+        return res.status(500).send(sanitizeHtml(res, req, defaultHtmlSrc500));
+      }
+    },
+    error400: function (req, res, next) {
+      // if /<path>/home redirect to /<path>
+      const homeRedirectPath = `${path === '/' ? '' : path}/home`;
+      if (req.url.startsWith(homeRedirectPath)) {
+        const redirectUrl = req.url.replace('/home', '');
+        return res.redirect(redirectUrl.startsWith('/') ? redirectUrl : `/${redirectUrl}`);
+      }
+
+      if (page404) return res.status(404).redirect(page404);
+      else {
+        res.set('Content-Type', 'text/html');
+        return res.status(404).send(sanitizeHtml(res, req, defaultHtmlSrc404));
+      }
+    },
+  };
+};
+
+export { ssrMiddlewareFactory, ssrFactory, sanitizeHtml };

package/src/client.build.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// https://nodejs.org/api
+// https://expressjs.com/en/4x/api.html
+
+import { loggerFactory } from './server/logger.js';
+import { Config } from './server/conf.js';
+import { ProcessController } from './server/process.js';
+import { clientLiveBuild } from './client-builder/client-build-live.js';
+
+await Config.build();
+
+const logger = loggerFactory(import.meta);
+
+await logger.setUpInfo();
+
+await clientLiveBuild();

package/src/client.dev.js

@@ -0,0 +1,21 @@
+'use strict';
+
+// https://nodejs.org/api
+// https://expressjs.com/en/4x/api.html
+
+import { loggerFactory } from './server/logger.js';
+import { ProcessController } from './server/process.js';
+import { Config, buildClientStaticConf } from './server/conf.js';
+import { createClientDevServer } from './client-builder/client-dev-server.js';
+
+const logger = loggerFactory(import.meta);
+
+await logger.setUpInfo();
+
+await buildClientStaticConf({ devProxy: process.argv[6] === 'proxy' });
+
+await Config.build();
+
+await createClientDevServer();
+
+ProcessController.init(logger);