underpost 3.1.2 → 3.2.0

package/src/server/client-build-docs.js

@@ -332,56 +332,17 @@ const buildApiDocs = async ({
  * @param {string} options.path - The base path for the documentation
  * @param {Object} options.metadata - Metadata for the documentation
  * @param {string} options.publicClientId - Client ID used to resolve the tutorials/references directory
+ * @param {Object} options.docs - Documentation config from server conf
+ * @param {string} options.docs.jsJsonPath - Path to the JSDoc JSON config file
  */
-const buildJsDocs = async ({ host, path, metadata = {}, publicClientId }) => {
+const buildJsDocs = async ({ host, path, metadata = {}, publicClientId, docs }) => {
   const logger = loggerFactory(import.meta);
 
-  // Detect custom jsdoc.<deployId>.json by matching host against deploy server configs
-  let customJsDocPath = '';
-  const privateConfBase = `./engine-private/conf`;
-  if (fs.existsSync(privateConfBase)) {
-    for (const deployId of fs.readdirSync(privateConfBase)) {
-      const candidatePath = `./jsdoc.${deployId}.json`;
-      if (!fs.existsSync(candidatePath)) continue;
-
-      // Check if this deployId's server config contains the current host
-      const serverConfPath = `${privateConfBase}/${deployId}/conf.server.json`;
-      if (fs.existsSync(serverConfPath)) {
-        try {
-          const serverConf = JSON.parse(fs.readFileSync(serverConfPath, 'utf8'));
-          if (serverConf[host]) {
-            customJsDocPath = candidatePath;
-            logger.info('detected custom jsdoc config', { deployId, host, path: candidatePath });
-            break;
-          }
-        } catch (e) {
-          // skip invalid JSON
-        }
-      }
-
-      // Fallback: also check dev server configs
-      if (!customJsDocPath) {
-        const devConfFiles = fs
-          .readdirSync(`${privateConfBase}/${deployId}`)
-          .filter((f) => f.match(/^conf\.server\.dev\..*\.json$/));
-        for (const devFile of devConfFiles) {
-          try {
-            const devConf = JSON.parse(fs.readFileSync(`${privateConfBase}/${deployId}/${devFile}`, 'utf8'));
-            if (devConf[host]) {
-              customJsDocPath = candidatePath;
-              logger.info('detected custom jsdoc config (dev)', { deployId, host, path: candidatePath });
-              break;
-            }
-          } catch (e) {
-            // skip invalid JSON
-          }
-        }
-      }
-      if (customJsDocPath) break;
-    }
+  const jsDocSourcePath = docs.jsJsonPath;
+  if (!fs.existsSync(jsDocSourcePath)) {
+    logger.warn('jsdoc config not found, skipping', jsDocSourcePath);
+    return;
   }
-
-  const jsDocSourcePath = customJsDocPath || `./jsdoc.json`;
   const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
   logger.info('using jsdoc config', jsDocSourcePath);
 
@@ -391,22 +352,14 @@ const buildJsDocs = async ({ host, path, metadata = {}, publicClientId }) => {
 
   const tutorialsPath = `./src/client/public/${publicClientId}/docs/references`;
 
-  // Auto-prepare hardhat references when jsdoc config includes hardhat source files
-  const includesHardhat =
-    jsDocsConfig.source &&
-    Array.isArray(jsDocsConfig.source.include) &&
-    jsDocsConfig.source.include.some((p) => p.includes('hardhat/'));
-  if (includesHardhat && fs.existsSync(`./hardhat`)) {
+  if (Array.isArray(docs.references) && docs.references.length > 0) {
     fs.mkdirSync(tutorialsPath, { recursive: true });
-    const hardhatReadmePath = `./hardhat/README.md`;
-    const hardhatWhitePaperPath = `./hardhat/WHITE-PAPER.md`;
-    if (fs.existsSync(hardhatReadmePath)) {
-      fs.copySync(hardhatReadmePath, `${tutorialsPath}/Hardhat Module.md`);
-      logger.info('copied hardhat README.md to tutorials references');
-    }
-    if (fs.existsSync(hardhatWhitePaperPath)) {
-      fs.copySync(hardhatWhitePaperPath, `${tutorialsPath}/White Paper.md`);
-      logger.info('copied hardhat WHITE-PAPER.md to tutorials references');
+    for (const refPath of docs.references) {
+      if (fs.existsSync(refPath)) {
+        const fileName = refPath.split('/').pop();
+        fs.copySync(refPath, `${tutorialsPath}/${fileName}`);
+        logger.info('copied reference to tutorials', refPath);
+      }
     }
   }
 
@@ -420,10 +373,10 @@ const buildJsDocs = async ({ host, path, metadata = {}, publicClientId }) => {
     delete jsDocsConfig.opts.tutorials;
   }
 
-  fs.writeFileSync(`./jsdoc.json`, JSON.stringify(jsDocsConfig, null, 4), 'utf8');
+  fs.writeFileSync(jsDocSourcePath, JSON.stringify(jsDocsConfig, null, 4), 'utf8');
   logger.warn('build jsdoc view', jsDocsConfig.opts.destination);
 
-  shellExec(`npm run docs`, { silent: true });
+  shellExec(`npx jsdoc -c ${jsDocSourcePath}`, { silent: true });
 };
 
 /**
@@ -433,58 +386,44 @@ const buildJsDocs = async ({ host, path, metadata = {}, publicClientId }) => {
  * @param {Object} options - Coverage build options
  * @param {string} options.host - The hostname for the coverage
  * @param {string} options.path - The base path for the coverage
+ * @param {Object} options.docs - Documentation config from server conf
+ * @param {string} options.docs.coveragePath - Directory where to run npm run coverage
  */
-const buildCoverage = async ({ host, path }) => {
+const buildCoverage = async ({ host, path, docs }) => {
   const logger = loggerFactory(import.meta);
-  const jsDocsConfig = JSON.parse(fs.readFileSync(`./jsdoc.json`, 'utf8'));
-
-  if (!fs.existsSync(`./coverage`)) {
-    shellExec(`npm test`);
-  }
-
-  const coverageBuildPath = `${jsDocsConfig.opts.destination}coverage`;
-  fs.mkdirSync(coverageBuildPath, { recursive: true });
-  fs.copySync(`./coverage`, coverageBuildPath);
-
-  logger.warn('build coverage', coverageBuildPath);
+  const jsDocSourcePath = docs.jsJsonPath;
+  const jsDocsConfig = JSON.parse(fs.readFileSync(jsDocSourcePath, 'utf8'));
+  const coveragePath = docs.coveragePath;
+  const coverageOutputDir = docs.coverageOutputDir || 'coverage';
 
-  // Include hardhat coverage for cyberia-related builds
-  const hardhatCoveragePath = `./hardhat/coverage`;
-  if (fs.existsSync(hardhatCoveragePath) && fs.readdirSync(hardhatCoveragePath).length > 0) {
-    const hardhatCoverageBuildPath = `${jsDocsConfig.opts.destination}hardhat-coverage`;
-    fs.mkdirSync(hardhatCoverageBuildPath, { recursive: true });
-    fs.copySync(hardhatCoveragePath, hardhatCoverageBuildPath);
-    logger.warn('build hardhat coverage', hardhatCoverageBuildPath);
-  } else if (fs.existsSync(`./hardhat/package.json`)) {
-    // Attempt to generate hardhat coverage if the hardhat project exists
-    try {
-      const hardhatPkg = JSON.parse(fs.readFileSync(`./hardhat/package.json`, 'utf8'));
-      if (hardhatPkg.scripts && hardhatPkg.scripts.coverage) {
-        logger.info('generating hardhat coverage report');
-        shellExec(`cd ./hardhat && npx hardhat coverage`, { silent: true });
-        if (fs.existsSync(hardhatCoveragePath) && fs.readdirSync(hardhatCoveragePath).length > 0) {
-          const hardhatCoverageBuildPath = `${jsDocsConfig.opts.destination}hardhat-coverage`;
-          fs.mkdirSync(hardhatCoverageBuildPath, { recursive: true });
-          fs.copySync(hardhatCoveragePath, hardhatCoverageBuildPath);
-          logger.warn('build hardhat coverage (generated)', hardhatCoverageBuildPath);
-        }
+  const coverageOutputPath = `${coveragePath}/coverage`;
+  if (!fs.existsSync(coverageOutputPath)) {
+    const pkgPath = `${coveragePath}/package.json`;
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.scripts && pkg.scripts.coverage) {
+        logger.info('generating coverage report', coveragePath);
+        shellExec(`cd ${coveragePath} && npm run coverage`, { silent: true });
+      } else if (pkg.scripts && pkg.scripts.test) {
+        logger.info('generating coverage via test', coveragePath);
+        shellExec(`cd ${coveragePath} && npm test`, { silent: true });
       }
-    } catch (e) {
-      logger.warn('hardhat coverage generation skipped', e.message);
     }
   }
 
-  // Copy hardhat README and WHITE-PAPER as markdown docs
-  const docsDestBase = jsDocsConfig.opts.destination;
-  const hardhatReadmePath = `./hardhat/README.md`;
-  const hardhatWhitePaperPath = `./hardhat/WHITE-PAPER.md`;
-  if (fs.existsSync(hardhatReadmePath)) {
-    fs.copySync(hardhatReadmePath, `${docsDestBase}hardhat-README.md`);
-    logger.info('copied hardhat README.md to docs');
-  }
-  if (fs.existsSync(hardhatWhitePaperPath)) {
-    fs.copySync(hardhatWhitePaperPath, `${docsDestBase}hardhat-WHITE-PAPER.md`);
-    logger.info('copied hardhat WHITE-PAPER.md to docs');
+  if (fs.existsSync(coverageOutputPath) && fs.readdirSync(coverageOutputPath).length > 0) {
+    const coverageBuildPath = `${jsDocsConfig.opts.destination}${coverageOutputDir}`;
+    fs.mkdirSync(coverageBuildPath, { recursive: true });
+    // Hardhat 3 outputs HTML to coverage/html/; Hardhat 2 / c8 output directly to coverage/
+    const coverageHtmlSubdir = `${coverageOutputPath}/html`;
+    if (fs.existsSync(coverageHtmlSubdir) && fs.existsSync(`${coverageHtmlSubdir}/index.html`)) {
+      fs.copySync(coverageHtmlSubdir, coverageBuildPath);
+    } else {
+      fs.copySync(coverageOutputPath, coverageBuildPath);
+    }
+    logger.warn('build coverage', coverageBuildPath);
+  } else {
+    logger.warn('no coverage output found, skipping', coverageOutputPath);
   }
 };
 
@@ -501,6 +440,7 @@ const buildCoverage = async ({ host, path }) => {
  * @param {string} options.publicClientId - Client ID for the public documentation
  * @param {string} options.rootClientPath - Root path for client files
  * @param {Object} options.packageData - Package.json data
+ * @param {Object} options.docs - Documentation config from server conf
  */
 const buildDocs = async ({
   host,
@@ -511,9 +451,10 @@ const buildDocs = async ({
   publicClientId,
   rootClientPath,
   packageData,
+  docs,
 }) => {
-  await buildJsDocs({ host, path, metadata, publicClientId });
-  await buildCoverage({ host, path });
+  await buildJsDocs({ host, path, metadata, publicClientId, docs });
+  await buildCoverage({ host, path, docs });
   await buildApiDocs({
     host,
     path,

package/src/server/client-build.js

@@ -7,7 +7,7 @@
 'use strict';
 
 import fs from 'fs-extra';
-import { srcFormatted, componentFormatted, viewFormatted, JSONweb } from './client-formatted.js';
+import { transformClientJs, JSONweb } from './client-formatted.js';
 import { loggerFactory } from './logger.js';
 import {
   getCapVariableName,
@@ -16,7 +16,6 @@ import {
   uniqueArray,
 } from '../client/components/core/CommonJs.js';
 import { readConfJson } from './conf.js';
-import UglifyJS from 'uglify-js';
 import { minify } from 'html-minifier-terser';
 import AdmZip from 'adm-zip';
 import * as dir from 'path';
@@ -230,16 +229,28 @@ const defaultSitemapXsl = `<?xml version="1.0" encoding="UTF-8"?>
  * @function buildClient
  * @memberof clientBuild
  * @param {Object} options - Options for the build process.
+ * @param {string} options.deployId - The deployment ID for which to build the client.
  * @param {Array} options.liveClientBuildPaths - List of paths to build incrementally.
  * @param {Array} options.instances - List of instances to build.
  * @param {boolean} options.buildZip - Whether to create zip files of the builds.
+ * @param {boolean} options.fullBuild - Whether to perform a full build.
+ * @param {boolean} options.iconsBuild - Whether to build icons.
  * @returns {Promise<void>} - Promise that resolves when the build is complete.
  * @throws {Error} - If the build fails.
  * @memberof clientBuild
  */
-const buildClient = async (options = { liveClientBuildPaths: [], instances: [], buildZip: false }) => {
+const buildClient = async (
+  options = {
+    deployId: '',
+    liveClientBuildPaths: [],
+    instances: [],
+    buildZip: false,
+    fullBuild: false,
+    iconsBuild: false,
+  },
+) => {
   const logger = loggerFactory(import.meta);
-  const deployId = process.env.DEPLOY_ID;
+  const deployId = options.deployId || process.env.DEPLOY_ID;
   const confClient = readConfJson(deployId, 'client');
   const confServer = readConfJson(deployId, 'server', { loadReplicas: true });
   const confSSR = readConfJson(deployId, 'ssr');
@@ -305,7 +316,8 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
         shellExec(`cd /home/dd && git clone https://github.com/designmodo/html-website-templates.git`);
       if (!fs.existsSync(`${rootClientPath}/index.php`)) {
         fs.copySync(`/home/dd/html-website-templates/${publicClientId.split('-publicClientId-')[1]}`, rootClientPath);
-        shellExec(`cd ${rootClientPath} && git init && git add . && git commit -m "Base template implementation"`);
+        Underpost.repo.initLocalRepo({ path: rootClientPath });
+        shellExec(`cd ${rootClientPath} && git add . && git commit -m "Base template implementation"`);
         // git remote add origin git@github.com:<username>/<repo>.git
         fs.writeFileSync(`${rootClientPath}/.git/.htaccess`, `Deny from all`, 'utf8');
       }
@@ -373,17 +385,14 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
         client,
         directory,
         disabledRebuild,
-        minifyBuild,
         db,
         redirect,
         apis,
-        iconsBuild,
-        docsBuild,
         apiBaseProxyPath,
         apiBaseHost,
         ttiLoadTimeLimit,
         singleReplica,
-        offlineBuild,
+        docs,
       } = confServer[host][path];
       if (singleReplica) continue;
       if (!confClient[client]) confClient[client] = {};
@@ -397,9 +406,10 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
       const rootClientPath = directory ? directory : `${publicPath}/${host}${path}`;
       const port = newInstance(currentPort);
       const publicClientId = publicRef ? publicRef : client;
-      const fullBuildEnabled = !confServer[host][path].liteBuild && !enableLiveRebuild;
+      const fullBuildEnabled = options.fullBuild && !enableLiveRebuild;
       // const baseHost = process.env.NODE_ENV === 'production' ? `https://${host}` : `http://localhost:${port}`;
       const baseHost = process.env.NODE_ENV === 'production' ? `https://${host}` : ``;
+      const minifyBuild = process.env.NODE_ENV === 'production';
       // ''; // process.env.NODE_ENV === 'production' ? `https://${host}` : ``;
       currentPort++;
 
@@ -421,7 +431,7 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
           rootClientPath,
           acmeChallengeFullPath,
           publicClientId,
-          iconsBuild,
+          iconsBuild: options.iconsBuild,
           metadata,
           publicCopyNonExistingFiles,
         });
@@ -437,19 +447,15 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
 
             if (enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath)) continue;
 
-            const jsSrc = componentFormatted(
-              await srcFormatted(fs.readFileSync(jsSrcPath, 'utf8')),
-              module,
+            const jsSrc = await transformClientJs(jsSrcPath, {
               dists,
-              path,
-              'components',
+              proxyPath: path,
+              basePath: 'components',
+              module,
               baseHost,
-            );
-            fs.writeFileSync(
-              jsPublicPath,
-              minifyBuild || process.env.NODE_ENV === 'production' ? UglifyJS.minify(jsSrc).code : jsSrc,
-              'utf8',
-            );
+              minify: minifyBuild,
+            });
+            fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
           }
         }
 
@@ -463,19 +469,15 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
             const jsPublicPath = `${rootClientPath}/services/${module}/${module}.service.js`;
             if (enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath)) continue;
 
-            let jsSrc = componentFormatted(
-              await srcFormatted(fs.readFileSync(jsSrcPath, 'utf8')),
-              module,
+            const jsSrc = await transformClientJs(jsSrcPath, {
               dists,
-              path,
-              'services',
+              proxyPath: path,
+              basePath: 'services',
+              module,
               baseHost,
-            );
-            fs.writeFileSync(
-              jsPublicPath,
-              minifyBuild || process.env.NODE_ENV === 'production' ? UglifyJS.minify(jsSrc).code : jsSrc,
-              'utf8',
-            );
+              minify: minifyBuild,
+            });
+            fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
           }
         }
 
@@ -485,19 +487,15 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
             const jsPublicPath = `${rootClientPath}/services/${module}/${module}.management.js`;
             if (enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath)) continue;
 
-            const jsSrc = componentFormatted(
-              await srcFormatted(fs.readFileSync(jsSrcPath, 'utf8')),
-              module,
+            const jsSrc = await transformClientJs(jsSrcPath, {
               dists,
-              path,
-              'services',
+              proxyPath: path,
+              basePath: 'services',
+              module,
               baseHost,
-            );
-            fs.writeFileSync(
-              jsPublicPath,
-              minifyBuild || process.env.NODE_ENV === 'production' ? UglifyJS.minify(jsSrc).code : jsSrc,
-              'utf8',
-            );
+              minify: minifyBuild,
+            });
+            fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
           }
         }
       }
@@ -515,13 +513,9 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
         const jsPublicPath = `${rootClientPath}/sw.js`;
 
         if (!(enableLiveRebuild && !options.liveClientBuildPaths.find((p) => p.srcBuildPath === jsSrcPath))) {
-          const jsSrc = viewFormatted(await srcFormatted(fs.readFileSync(jsSrcPath, 'utf8')), dists, path, baseHost);
+          const jsSrc = await transformClientJs(jsSrcPath, { dists, proxyPath: path, baseHost, minify: minifyBuild });
 
-          fs.writeFileSync(
-            jsPublicPath,
-            minifyBuild || process.env.NODE_ENV === 'production' ? UglifyJS.minify(jsSrc).code : jsSrc,
-            'utf8',
-          );
+          fs.writeFileSync(jsPublicPath, jsSrc, 'utf8');
         }
 
         if (
@@ -541,18 +535,14 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
 
             logger.info('View build', buildPath);
 
-            const jsSrc = viewFormatted(
-              await srcFormatted(fs.readFileSync(`./src/client/${view.client}.index.js`, 'utf8')),
+            const jsSrc = await transformClientJs(`./src/client/${view.client}.index.js`, {
               dists,
-              path,
+              proxyPath: path,
               baseHost,
-            );
+              minify: minifyBuild,
+            });
 
-            fs.writeFileSync(
-              `${buildPath}${buildId}.js`,
-              minifyBuild || process.env.NODE_ENV === 'production' ? UglifyJS.minify(jsSrc).code : jsSrc,
-              'utf8',
-            );
+            fs.writeFileSync(`${buildPath}${buildId}.js`, jsSrc, 'utf8');
             const title = metadata.title ? metadata.title : title;
 
             const canonicalURL = `https://${host}${path}${
@@ -689,7 +679,7 @@ const buildClient = async (options = { liveClientBuildPaths: [], instances: [],
 
             fs.writeFileSync(
               `${buildPath}index.html`,
-              minifyBuild || process.env.NODE_ENV === 'production'
+              minifyBuild
                 ? await minify(htmlSrc, {
                     minifyCSS: true,
                     minifyJS: true,
@@ -739,7 +729,7 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
         );
       }
 
-      if (fullBuildEnabled && !enableLiveRebuild && docsBuild) {
+      if (fullBuildEnabled && docs) {
         await buildDocs({
           host,
           path,
@@ -749,13 +739,14 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
           publicClientId,
           rootClientPath,
           packageData,
+          docs,
         });
       }
 
       if (client) {
         let PRE_CACHED_RESOURCES = [];
 
-        if (views && offlineBuild && fs.existsSync(`${rootClientPath}/sw.js`)) {
+        if (views && fs.existsSync(`${rootClientPath}/sw.js`)) {
           PRE_CACHED_RESOURCES = await fs.readdir(rootClientPath, { recursive: true });
           PRE_CACHED_RESOURCES = views
             .map((view) => `${path === '/' ? '' : path}${view.path}`)
@@ -774,7 +765,7 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
               const htmlSrc = Render({
                 title: page.title,
                 ssrPath,
-                ssrHeadComponents: '',
+                ssrHeadComponents: '<base target="_top">',
                 ssrBodyComponents: SsrComponent(),
                 renderPayload: {
                   apiBaseProxyPath,
@@ -802,7 +793,7 @@ Sitemap: ${sitemapBaseUrl}/sitemap.xml`,
 
               fs.writeFileSync(
                 buildHtmlPath,
-                minifyBuild || process.env.NODE_ENV === 'production'
+                minifyBuild
                   ? await minify(htmlSrc, {
                       minifyCSS: true,
                       minifyJS: true,