@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/runtime/wp/Wp.js

@@ -13,8 +13,8 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { shellExec } from '../../server/process.js';
-import { loggerFactory } from '../../server/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { Lampp } from '../lampp/Lampp.js';
 import Underpost from '../../index.js';
 
@@ -141,14 +141,7 @@ class WpService {
       ({ freshInstall } = WpService.provisionFresh({ host, siteRoot: wpDir, db, wp, subDir }));
     }
 
-    // Ensure git is initialized and linked to the backup repository.
-    // Mark the directory as safe before git operations — the site root is owned
-    // by daemon:daemon (Apache) and git 2.35+ refuses to run in directories owned
-    // by a different user unless explicitly declared safe.
-    if (repository) {
-      shellExec(`git config --global --add safe.directory "${wpDir}"`);
-      Underpost.repo.initLocalRepo({ path: wpDir, origin: repository });
-    }
+    if (repository) Underpost.repo.initLocalRepo({ path: wpDir, origin: repository });
 
     // Write a root .htaccess that rewrites / → /subDir/ when running in subdirectory mode
     if (subDir) {
@@ -187,9 +180,9 @@ class WpService {
   }
 
   /**
-   * Clone mode — clones `repository` into `siteRoot` if not present, then
-   * verifies `wp-config.php` exists.  If it is missing the site root is wiped
-   * and a fresh WordPress install is performed (requires `db` config).
+   * Clone mode — materializes `siteRoot` from `repository` via
+   * {@link UnderpostRepository.provisionSiteRoot}, then verifies `wp-config.php` exists.
+   * An unreachable remote or a checkout without `wp-config.php` falls back to a fresh install.
    * @param {object} opts
    * @param {string}      opts.host       - Virtual-host name (for logging).
    * @param {string}      opts.siteRoot   - Absolute path where the site should live.
@@ -197,37 +190,11 @@ class WpService {
    * @param {object|null} [opts.db]       - MariaDB config used as fallback for fresh install.
    */
   static provisionClone({ host, siteRoot, repository, db, wp, subDir = '' }) {
-    if (!process.env.GITHUB_TOKEN && repository && repository.startsWith('https://github.com/')) {
-      logger.warn(`${host}: GITHUB_TOKEN not set — git operations will fail for private repositories`);
-    }
-
-    // Step 0 — verify the remote repository is reachable; fall back to fresh install if not.
-    // repository.js isRemoteRepo handles token injection internally.
-    const repoAccessible = Underpost.repo.isRemoteRepo(repository);
-    logger.info(`${host}: remote accessible = ${repoAccessible} (${repository})`);
-    if (!repoAccessible) {
-      logger.warn(`${host}: remote repository not accessible (${repository}) — running fresh install`);
-      return WpService.provisionFresh({ host, siteRoot, db, wp, subDir });
-    }
+    const { accessible } = Underpost.repo.provisionSiteRoot({ host, siteRoot, repository });
+    if (!accessible) return WpService.provisionFresh({ host, siteRoot, db, wp, subDir });
 
-    // Step 1 — clone if the directory does not exist yet
-    if (!fs.existsSync(siteRoot)) {
-      logger.info(`${host}: cloning ${repository} → ${siteRoot}`);
-      const cloneUrl = Underpost.repo.resolveAuthUrl(repository);
-      const tmp = `${siteRoot}.tmp`;
-      if (fs.existsSync(tmp)) shellExec(`sudo rm -rf "${tmp}"`);
-      shellExec(`git clone "${cloneUrl}" "${tmp}"`);
-      shellExec(`sudo mv "${tmp}" "${siteRoot}"`);
-      shellExec(`sudo chmod -R 755 "${siteRoot}"`);
-      shellExec(`sudo chown -R daemon:daemon "${siteRoot}"`);
-    } else {
-      logger.info(`${host}: repo already present at ${siteRoot}`);
-    }
-
-    // Step 2 — verify wp-config.php; if missing, wipe and do a fresh install.
-    // initLocalRepo is NOT called here — createApp always calls it after provisionClone
-    // returns (whether clone or fallback path) so we avoid a double-init and ensure
-    // safe.directory is declared before git runs.
+    // A checkout without wp-config.php is not a WordPress site: discard it and install fresh.
+    // initLocalRepo is left to createApp so both provisioning paths converge on one call.
     if (!fs.existsSync(path.join(siteRoot, 'wp-config.php'))) {
       logger.warn(`${host}: wp-config.php not found — wiping site root and running fresh install`);
       shellExec(`sudo rm -rf "${siteRoot}"`);
@@ -515,10 +482,9 @@ Thumbs.db
     const repoName = repository.split('/').pop().split('.')[0];
 
     logger.info(`${host}: persisting site to repository`);
-    shellExec(
-      `cd "${siteRoot}" && git add -A && git commit -m "wp provision ${host} $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
-      { silentOnError: true },
-    );
+    shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp provision ${host} $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, {
+      silentOnError: true,
+    });
     shellExec(`cd "${siteRoot}" && underpost push . ${githubOrg}/${repoName} -f`);
     logger.info(`${host}: initial commit pushed to ${githubOrg}/${repoName}`);
   }
@@ -630,7 +596,9 @@ if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROT
 
     // MariaDB export is handled by the shared db.js backup flow — no duplicate dump here.
     if (fs.existsSync(path.join(siteRoot, '.git'))) {
-      shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp backup $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, { silentOnError: true });
+      shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp backup $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, {
+        silentOnError: true,
+      });
       shellExec(`cd "${siteRoot}" && underpost push . ${githubOrg}/${repository.split('/').pop().split('.')[0]}`);
       logger.info(`backup: git push done for ${siteRoot}`);
     } else {

package/src/server/{catalog.js → build/catalog.js}

@@ -8,9 +8,9 @@
  * deploy id resolve to the empty catalog — nothing else breaks.
  *
  * Each product catalog default-exports the uniform shape documented in
- * {@link module:src/server/catalog-cyberia}.
+ * {@link module:src/projects/cyberia/catalog-cyberia.js}.
  *
- * @module src/server/catalog.js
+ * @module src/server/build/catalog.js
  * @namespace Catalog
  */
 
@@ -18,7 +18,13 @@ import fs from 'fs-extra';
 import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 
-/** Empty product catalog returned for deploy ids without a dedicated module. */
+/**
+ * Empty product catalog returned for deploy ids without a dedicated module.
+ *
+ * The `package*` fields are the deploy's package manifest contract, read by
+ * {@link module:src/server/build/package.js}: a deploy id with no catalog gets the engine
+ * manifest under its own identity, and one with a catalog adds exactly what it declares here.
+ */
 const EMPTY_CATALOG = {
   sourceMoves: [],
   privateConfPaths: [],
@@ -28,6 +34,10 @@ const EMPTY_CATALOG = {
   copies: [],
   keywords: [],
   description: '',
+  packageName: '',
+  packageBin: {},
+  packageDependencies: {},
+  packageScripts: {},
 };
 
 /**
@@ -44,7 +54,7 @@ const loadDeployCatalog = async (deployId) => {
   const suffix = (deployId ?? '').split('dd-')[1];
   if (!suffix) return EMPTY_CATALOG;
   if (fs.existsSync(`./src/projects/${suffix}/catalog-${suffix}.js`)) {
-    const mod = await import(`../projects/${suffix}/catalog-${suffix}.js`);
+    const mod = await import(`../../projects/${suffix}/catalog-${suffix}.js`);
     return { ...EMPTY_CATALOG, ...(mod.default ?? {}) };
   }
   return EMPTY_CATALOG;
@@ -63,7 +73,7 @@ const loadProductCatalogs = async () => {
   const catalogs = [];
   for (const file of await fs.readdir('./src/projects')) {
     if (file === 'underpost') continue;
-    const mod = await import(`../projects/${file}/catalog-${file}.js`);
+    const mod = await import(`../../projects/${file}/catalog-${file}.js`);
     if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
   }
   return catalogs;

package/src/server/build/coverage.js

@@ -0,0 +1,188 @@
+/**
+ * The coverage HTML reports as build artifacts: which reports a deploy declares, where a run
+ * leaves each, where an assembled deploy artifact carries them, and what is published when
+ * one was not carried.
+ *
+ * A deploy declares its reports in `conf.server.json` under `docs.coverage`, one entry per
+ * report it publishes at `/docs/coverage/<id>`:
+ *
+ * - `{ id, label, suite }` — a test tier selection run by `node bin test <suite>`, whose HTML
+ *   report the runner writes under `coverage/<key>` (see `coverageReportKey`). A deploy shows
+ *   the run it names, never the last run a host happened to make.
+ * - `{ id, label, path }` — a report another tree produces on its own (Hardhat's Solidity
+ *   coverage), read from that tree's `coverage/` output.
+ *
+ * Reports are produced by the test stage and bundled into the deploy artifact under
+ * {@link COVERAGE_BUNDLE_DIRECTORY}. A workload container only ever copies them: running a
+ * test runner inside a pod costs minutes of the build phase, needs the dev dependency tree,
+ * and — because a suite's expected non-zero exits latch the runtime status contract —
+ * publishes a false `error` to the deployment monitor.
+ *
+ * @module src/server/build/coverage.js
+ * @namespace UnderpostCoverage
+ */
+
+import fs from 'fs-extra';
+import { UNDERPOST_TESTING, coverageReportKey } from './testing.js';
+
+/**
+ * @constant COVERAGE_BUNDLE_DIRECTORY
+ * @description Path, relative to a source tree root, under which an assembled deploy
+ * artifact carries each report as `<id>/`. Deliberately not under `coverage/`, which every
+ * engine `.gitignore` excludes, so the bundled artifact is publishable source rather than a
+ * local run's output.
+ * @memberof UnderpostCoverage
+ */
+const COVERAGE_BUNDLE_DIRECTORY = 'docs/coverage';
+
+const normalizeRoot = (root) => `${root ?? ''}`.replace(/\/+$/, '');
+
+/**
+ * @method coverageReportsFactory
+ * @description The reports a deploy's `docs` conf declares, validated: every entry names an
+ * id and exactly one source, and no two entries publish under the same id.
+ * @param {object} [docs] - The `docs` block of one `conf.server.json` route.
+ * @returns {Array<{id: string, label: string, suite?: string, path?: string}>} Declared reports.
+ * @throws {Error} When an entry is malformed or an id repeats.
+ * @memberof UnderpostCoverage
+ */
+const coverageReportsFactory = (docs = {}) => {
+  const reports = docs.coverage ?? [];
+  const ids = new Set();
+  for (const report of reports) {
+    const { id, suite, path } = report;
+    if (!id || !/^[a-z0-9-]+$/.test(id)) throw new Error(`[coverage] report id must be a slug, got '${id}'`);
+    if (ids.has(id)) throw new Error(`[coverage] report id '${id}' is declared twice`);
+    if (!suite === !path) throw new Error(`[coverage] report '${id}' needs exactly one of 'suite' or 'path'`);
+    ids.add(id);
+  }
+  return reports.map(({ id, label = id, suite, path }) => ({ id, label, suite, path }));
+};
+
+/**
+ * @method deployCoverageReports
+ * @description Every report a deploy declares across its routes, once each: two routes may
+ * publish the same report, never the same id with different sources.
+ * @param {object} confServer - A parsed `conf.server.json`.
+ * @returns {Array<{id: string, label: string, suite?: string, path?: string}>} Declared reports.
+ * @throws {Error} When an id is declared with two different sources.
+ * @memberof UnderpostCoverage
+ */
+const deployCoverageReports = (confServer) => {
+  const reports = new Map();
+  for (const routes of Object.values(confServer)) {
+    for (const { docs } of Object.values(routes)) {
+      for (const report of coverageReportsFactory(docs)) {
+        const known = reports.get(report.id);
+        if (known && (known.suite !== report.suite || known.path !== report.path))
+          throw new Error(`[coverage] report id '${report.id}' is declared with two different sources`);
+        reports.set(report.id, report);
+      }
+    }
+  }
+  return [...reports.values()];
+};
+
+/**
+ * @method coverageReportCandidates
+ * @description Every place one report can live, most local first: the output of the run
+ * that produces it, then the bundled artifact a deploy artifact carries.
+ * @param {{id: string, suite?: string, path?: string}} report - A declared report.
+ * @returns {string[]} Candidate report directories.
+ * @memberof UnderpostCoverage
+ */
+const coverageReportCandidates = ({ id, suite, path }) => {
+  const bundled = `${COVERAGE_BUNDLE_DIRECTORY}/${id}`;
+  if (suite) return [`${UNDERPOST_TESTING.coverageDirectory}/${coverageReportKey(suite)}`, bundled];
+  const coverage = `${normalizeRoot(path)}/${UNDERPOST_TESTING.coverageDirectory}`;
+  return [`${coverage}/html`, `${coverage}/lcov-report`, coverage, bundled];
+};
+
+/**
+ * @method resolveCoverageReportPath
+ * @description First candidate that actually carries an HTML index. A directory holding
+ * only `lcov.info` is not a report and is not published.
+ * @param {{id: string, suite?: string, path?: string}} report - A declared report.
+ * @returns {string|undefined} Report directory, or undefined when none is available.
+ * @memberof UnderpostCoverage
+ */
+const resolveCoverageReportPath = (report) =>
+  coverageReportCandidates(report).find((candidate) => fs.existsSync(`${candidate}/index.html`));
+
+/**
+ * @method coverageReportCommand
+ * @description The command that produces a report, for the operator who finds it missing.
+ * @param {{suite?: string, path?: string}} report - A declared report.
+ * @returns {string} Shell command.
+ * @memberof UnderpostCoverage
+ */
+const coverageReportCommand = ({ suite, path }) =>
+  suite ? `node bin test ${suite}` : `npm run coverage --prefix ${normalizeRoot(path)}`;
+
+/**
+ * @method bundleCoverageReports
+ * @description Copies each declared report into `toRoot`'s bundle directory, so the
+ * assembled artifact carries it into every container started from that source.
+ * @param {Array<{id: string, suite?: string, path?: string}>} reports - Declared reports.
+ * @param {string} toRoot - Assembled artifact root.
+ * @returns {Array<{id: string, bundled: boolean, from?: string, to: string}>} What was bundled, and where.
+ * @memberof UnderpostCoverage
+ */
+const bundleCoverageReports = (reports, toRoot) =>
+  reports.map((report) => {
+    const to = `${normalizeRoot(toRoot)}/${COVERAGE_BUNDLE_DIRECTORY}/${report.id}`;
+    const from = resolveCoverageReportPath(report);
+    if (!from) return { id: report.id, bundled: false, to };
+    fs.emptyDirSync(to);
+    fs.copySync(from, to);
+    return { id: report.id, bundled: true, from, to };
+  });
+
+/**
+ * @method coverageUnavailablePage
+ * @description The page served where a report was expected but none was bundled. A static
+ * document, never an invitation to generate one at runtime.
+ * @param {{id: string, suite?: string, path?: string}} report - The missing report.
+ * @returns {string} HTML document.
+ * @memberof UnderpostCoverage
+ */
+const coverageUnavailablePage = (report) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Coverage report unavailable</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             font: 16px/1.6 system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
+      main { max-width: 34rem; padding: 2rem; }
+      h1 { font-size: 1.25rem; margin: 0 0 .75rem; }
+      p { margin: 0 0 .75rem; opacity: .8; }
+      code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Coverage report unavailable</h1>
+      <p>This build carried no <code>${report.id}</code> coverage report. The report is generated
+      by the test stage and bundled into the deploy artifact under
+      <code>${COVERAGE_BUNDLE_DIRECTORY}/${report.id}</code>.</p>
+      <p>Run <code>${coverageReportCommand(report)}</code> in the build environment, then assemble
+      and publish the artifact again.</p>
+    </main>
+  </body>
+</html>
+`;
+
+export {
+  COVERAGE_BUNDLE_DIRECTORY,
+  bundleCoverageReports,
+  coverageReportCandidates,
+  coverageReportCommand,
+  coverageReportsFactory,
+  coverageUnavailablePage,
+  deployCoverageReports,
+  resolveCoverageReportPath,
+};