@underpostnet/cyberia 3.2.90 → 3.3.73

package/src/runtime/engine-cyberia/docker-compose.yml

@@ -4,36 +4,6 @@
 # (MongoDB + Valkey + IPFS), then the Cyberia content-authority engine and its
 # per-instance server/client tiers, fronted by an nginx reverse proxy.
 #
-# Canonical location (custom docker-compose workflow):
-#   engine-private/conf/dd-cyberia/docker-compose/cyberia/
-#     ├── docker-compose.yml     (this file — the ENTIRE stack, single source)
-#     ├── compose.env            (working env-file, used as-is — not generated)
-#     ├── nginx.conf             (custom per-variant sub-path routing)
-#     └── mongodb/entrypoint.sh  (replica-set bootstrap)
-# All bind mounts below are relative to this directory: the CLI runs compose with
-# `--project-directory` pinned here (see src/cli/docker-compose.js).
-#
-# Multi-instance: one engine-cyberia (content + asset authority) feeds three
-# cyberia-server + three cyberia-client tiers, one per conf.instances.json
-# multiInstance variant (amethyst-strata-expansion "/", FOREST "/FOREST",
-# TEST "/TEST"). This custom workflow owns nginx.conf and the services below;
-# keep both in sync when its instance topology changes.
-#
-# Startup is a strict health-gated chain: the stable gateway starts after the
-# engine, then each server/client pipeline advances independently:
-#   mongodb + valkey -> engine runtime -> proxy -> 3x server -> 3x client
-#
-# Architecture boundaries (see CLAUDE.md "Cyberia architecture boundaries"):
-#   engine-cyberia  — content, validation, persistence, gRPC(:50051)+REST(:4005)
-#                     data services, asset metadata. The authority layer.
-#   cyberia-server  — authoritative real-time simulation / tick processing (Go).
-#   cyberia-client  — rendering, input, prediction, presentation (WASM bundle).
-#
-# Usage:
-#   underpost docker-compose --up --deploy-id dd-cyberia --docker-compose-id cyberia
-#   (or the docker:cyberia:* npm scripts). The engine-cyberia image bakes the
-#   dd-cyberia build at image-build time, so no private-repo credentials are
-#   required at container start.
 
 name: dd-cyberia
 
@@ -165,7 +135,7 @@ services:
   # server starts but rejects connections until seeded). Serves REST/WS on 4005
   # and the engine gRPC data service on 50051.
   engine-cyberia-runtime:
-    image: ${ENGINE_CYBERIA_IMAGE:-underpost/engine-cyberia-dev}:${ENGINE_CYBERIA_TAG:-v3.2.90}
+    image: ${ENGINE_CYBERIA_IMAGE:-underpost/engine-cyberia-dev}:${ENGINE_CYBERIA_TAG:-v3.3.73}
     container_name: dd-cyberia-engine
     command:
       - /bin/sh
@@ -220,7 +190,7 @@ services:
   # gateway on host port 8081, so one port can route every instance path.
 
   cyberia-server-runtime:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.90}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server
     environment:
       INSTANCE_CODE: amethyst-strata-expansion
@@ -232,6 +202,14 @@ services:
       STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
       APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
       LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+      CYBERIA_DISABLE_CONNECTION_LIMITS: ${CYBERIA_DISABLE_CONNECTION_LIMITS:-}
+      CYBERIA_MAX_CONNECTIONS: ${CYBERIA_MAX_CONNECTIONS:-}
+      CYBERIA_MAX_CONNECTIONS_PER_IP: ${CYBERIA_MAX_CONNECTIONS_PER_IP:-}
+      CYBERIA_CONNECT_RATE_PER_IP: ${CYBERIA_CONNECT_RATE_PER_IP:-}
+      CYBERIA_CONNECT_BURST_PER_IP: ${CYBERIA_CONNECT_BURST_PER_IP:-}
+      CYBERIA_MESSAGE_RATE: ${CYBERIA_MESSAGE_RATE:-}
+      CYBERIA_MESSAGE_BURST: ${CYBERIA_MESSAGE_BURST:-}
+      CYBERIA_MAX_STRIKES: ${CYBERIA_MAX_STRIKES:-}
     networks:
       - dd-cyberia-internal
     expose:
@@ -248,7 +226,7 @@ services:
     restart: unless-stopped
 
   cyberia-server-forest:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.90}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server-forest
     environment:
       INSTANCE_CODE: FOREST
@@ -260,6 +238,14 @@ services:
       STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
       APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
       LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+      CYBERIA_DISABLE_CONNECTION_LIMITS: ${CYBERIA_DISABLE_CONNECTION_LIMITS:-}
+      CYBERIA_MAX_CONNECTIONS: ${CYBERIA_MAX_CONNECTIONS:-}
+      CYBERIA_MAX_CONNECTIONS_PER_IP: ${CYBERIA_MAX_CONNECTIONS_PER_IP:-}
+      CYBERIA_CONNECT_RATE_PER_IP: ${CYBERIA_CONNECT_RATE_PER_IP:-}
+      CYBERIA_CONNECT_BURST_PER_IP: ${CYBERIA_CONNECT_BURST_PER_IP:-}
+      CYBERIA_MESSAGE_RATE: ${CYBERIA_MESSAGE_RATE:-}
+      CYBERIA_MESSAGE_BURST: ${CYBERIA_MESSAGE_BURST:-}
+      CYBERIA_MAX_STRIKES: ${CYBERIA_MAX_STRIKES:-}
     networks:
       - dd-cyberia-internal
     expose:
@@ -276,7 +262,7 @@ services:
     restart: unless-stopped
 
   cyberia-server-test:
-    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.2.90}
+    image: ${CYBERIA_SERVER_IMAGE:-underpost/cyberia-server-dev}:${CYBERIA_SERVER_TAG:-v3.3.73}
     container_name: dd-cyberia-server-test
     environment:
       INSTANCE_CODE: TEST
@@ -288,6 +274,14 @@ services:
       STATIC_DIR: ${CYBERIA_SERVER_STATIC_DIR:-/home/dd/engine/cyberia-server/public}
       APP_ENV: ${CYBERIA_SERVER_APP_ENV:-development}
       LOG_LEVEL: ${CYBERIA_SERVER_LOG_LEVEL:-}
+      CYBERIA_DISABLE_CONNECTION_LIMITS: ${CYBERIA_DISABLE_CONNECTION_LIMITS:-}
+      CYBERIA_MAX_CONNECTIONS: ${CYBERIA_MAX_CONNECTIONS:-}
+      CYBERIA_MAX_CONNECTIONS_PER_IP: ${CYBERIA_MAX_CONNECTIONS_PER_IP:-}
+      CYBERIA_CONNECT_RATE_PER_IP: ${CYBERIA_CONNECT_RATE_PER_IP:-}
+      CYBERIA_CONNECT_BURST_PER_IP: ${CYBERIA_CONNECT_BURST_PER_IP:-}
+      CYBERIA_MESSAGE_RATE: ${CYBERIA_MESSAGE_RATE:-}
+      CYBERIA_MESSAGE_BURST: ${CYBERIA_MESSAGE_BURST:-}
+      CYBERIA_MAX_STRIKES: ${CYBERIA_MAX_STRIKES:-}
     networks:
       - dd-cyberia-internal
     expose:
@@ -315,7 +309,7 @@ services:
   #   cyberia-server-test   -> cyberia-client-test
 
   cyberia-client-runtime:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.90}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client
     environment:
       CYBERIA_PORT: '8081'
@@ -340,7 +334,7 @@ services:
     restart: unless-stopped
 
   cyberia-client-forest:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.90}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client-forest
     environment:
       CYBERIA_PORT: '8081'
@@ -365,7 +359,7 @@ services:
     restart: unless-stopped
 
   cyberia-client-test:
-    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.2.90}
+    image: ${CYBERIA_CLIENT_IMAGE:-underpost/cyberia-client-dev}:${CYBERIA_CLIENT_TAG:-v3.3.73}
     container_name: dd-cyberia-client-test
     environment:
       CYBERIA_PORT: '8081'

package/src/runtime/express/Express.js

@@ -12,18 +12,19 @@ import swaggerUi from 'swagger-ui-express';
 import compression from 'compression';
 import { createServer } from 'http';
 
-import { loggerFactory, loggerMiddleware } from '../../server/logger.js';
+import { loggerFactory, loggerMiddleware } from '../../server/ops/logger.js';
 import { getCapVariableName, newInstance } from '../../client/components/core/CommonJs.js';
 import { MailerProvider } from '../../mailer/MailerProvider.js';
 import { DataBaseProviderService } from '../../db/DataBaseProvider.js';
-import { createPeerServer } from '../../server/peer.js';
-import { createValkeyConnection } from '../../server/valkey.js';
-import { applySecurity, authMiddlewareFactory } from '../../server/auth.js';
+import { createPeerServer } from '../../server/network/peer.js';
+import { createValkeyConnection } from '../../db/valkey/Valkey.js';
+import { applySecurity, authMiddlewareFactory } from '../../server/security/auth.js';
 import { ssrMiddlewareFactory } from '../../client-builder/ssr.js';
 import { buildSwaggerUiOptions } from '../../client-builder/client-build-docs.js';
 
-import { shellExec } from '../../server/process.js';
-import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/conf.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { devProxyHostFactory, isDevProxyContext, isTlsDevProxy } from '../../server/runtime/conf.js';
+import { metricsPathFactory } from '../../server/ops/monitoring.js';
 
 import Underpost from '../../index.js';
 
@@ -113,8 +114,9 @@ class ExpressService {
       return next();
     });
 
-    // Metrics endpoint
-    app.get(`${path === '/' ? '' : path}/metrics`, async (req, res) => {
+    // Metrics endpoint. The route is shared with the Prometheus scrape config
+    // so a target can never point at a path this server does not serve.
+    app.get(metricsPathFactory(path), async (req, res) => {
       res.set('Content-Type', promRegister.contentType);
       return res.end(await promRegister.metrics());
     });
@@ -163,19 +165,22 @@ class ExpressService {
     // Create HTTP server for regular instances (required for WebSockets)
     const server = createServer({}, app);
 
-    if (!apiBaseHost) {
-      // Swagger path definition
-      const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
-      const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
-
-      // Flag swagger requests before security middleware
-      if (fs.existsSync(swaggerJsonPath)) {
-        app.use(swaggerPath, (req, res, next) => {
-          res.locals.isSwagger = true;
-          next();
-        });
-      }
+    // Swagger path definition. The UI is served by every instance that renders the
+    // client, so a split client/API deployment keeps `api-docs` same-origin with the
+    // page that frames it.
+    const swaggerJsonPath = `./public/${host}${path === '/' ? path : `${path}/`}swagger-output.json`;
+    const swaggerPath = `${path === '/' ? `/api-docs` : `${path}/api-docs`}`;
+    const swaggerEnabled = fs.existsSync(swaggerJsonPath);
+
+    // Flag swagger requests before security middleware
+    if (swaggerEnabled) {
+      app.use(swaggerPath, (req, res, next) => {
+        res.locals.isSwagger = true;
+        next();
+      });
+    }
 
+    if (!apiBaseHost) {
       // Security and CORS — must run before swagger-ui so CSP headers are included in swagger responses
       if (process.env.NODE_ENV === 'development' && useLocalSsl)
         origins = origins.map((origin) => origin.replace('http', 'https'));
@@ -184,13 +189,6 @@ class ExpressService {
         origin: origins,
       });
 
-      // Swagger UI setup (after security middleware so responses carry correct CSP headers)
-      if (fs.existsSync(swaggerJsonPath)) {
-        const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
-        const swaggerUiOptions = await buildSwaggerUiOptions();
-        app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc, swaggerUiOptions));
-      }
-
       // Database and Valkey connections
       if (db && apis) await DataBaseProviderService.load({ apis, host, path, db });
 
@@ -261,6 +259,13 @@ class ExpressService {
       }
     }
 
+    // Swagger UI setup (after security middleware so responses carry correct CSP headers)
+    if (swaggerEnabled) {
+      const swaggerDoc = JSON.parse(fs.readFileSync(swaggerJsonPath, 'utf8'));
+      const swaggerUiOptions = await buildSwaggerUiOptions();
+      app.use(swaggerPath, swaggerUi.serve, swaggerUi.setup(swaggerDoc, swaggerUiOptions));
+    }
+
     // SSR middleware loading
     const ssr = await ssrMiddlewareFactory({ app, directory, rootHostPath, path });
     for (const [_, ssrMiddleware] of Object.entries(ssr)) app.use(ssrMiddleware);

package/src/runtime/lampp/Lampp.js

@@ -6,8 +6,9 @@
  */
 
 import fs from 'fs-extra';
-import { getRootDirectory, shellCd, shellExec } from '../../server/process.js';
-import { loggerFactory } from '../../server/logger.js';
+import { getRootDirectory, shellCd, shellExec } from '../../server/runtime/process.js';
+import { loggerFactory } from '../../server/ops/logger.js';
+import Underpost from '../../index.js';
 
 const logger = loggerFactory(import.meta);
 
@@ -71,12 +72,8 @@ class LamppService {
    * @memberof LamppService
    */
   async initService(options = { daemon: false }) {
-    let cmd;
-
-    // 1. Write the current virtual host router configuration
     fs.writeFileSync(`/opt/lampp/etc/extra/httpd-vhosts.conf`, this.router || '', 'utf8');
 
-    // 2. Ensure the vhosts file is included in the main httpd.conf
     const httpdConfPath = `/opt/lampp/etc/httpd.conf`;
     fs.writeFileSync(
       httpdConfPath,
@@ -86,12 +83,9 @@ class LamppService {
       'utf8',
     );
 
-    // 3. Stop the service before making port changes
-    cmd = `sudo /opt/lampp/lampp stop`;
-    shellExec(cmd);
+    shellExec(`sudo /opt/lampp/lampp stop`);
 
-    // 4. Comment out default port Listen directives (80 and 443) to prevent conflicts
-    // Modify httpd.conf (port 80)
+    // Every vhost declares its own Listen, so the stock 80/443 directives would double-bind.
     if (!fs.readFileSync(httpdConfPath, 'utf8').match(/# Listen 80/))
       fs.writeFileSync(
         httpdConfPath,
@@ -99,7 +93,6 @@ class LamppService {
         'utf8',
       );
 
-    // Modify httpd-ssl.conf (port 443)
     const httpdSslConfPath = `/opt/lampp/etc/extra/httpd-ssl.conf`;
     if (fs.existsSync(httpdSslConfPath) && !fs.readFileSync(httpdSslConfPath, 'utf8').match(/# Listen 443/))
       fs.writeFileSync(
@@ -108,7 +101,8 @@ class LamppService {
         'utf8',
       );
 
-    // 5. Modify the lampp startup script to bypass port checking for 80 and 443
+    // The startup script aborts when 80/443 are already held by the ingress proxy; short-circuit
+    // its probes so the service still comes up behind one.
     const lamppScriptPath = `/opt/lampp/lampp`;
     if (!fs.readFileSync(lamppScriptPath, 'utf8').match(/testport 443 && false/))
       fs.writeFileSync(
@@ -123,9 +117,7 @@ class LamppService {
         'utf8',
       );
 
-    // 6. Start the service
-    cmd = `sudo /opt/lampp/lampp start`;
-    shellExec(cmd);
+    shellExec(`sudo /opt/lampp/lampp start`);
   }
 
   /**
@@ -217,13 +209,15 @@ class LamppService {
    * @param {string} options.path - The base path for error documents (e.g., '/app').
    * @param {string} [options.directory] - Optional absolute path to the document root.
    * @param {string} [options.rootHostPath] - Relative path from the root directory to the document root, used if `directory` is not provided.
+   * @param {string} [options.repository] - Repository backing the document root. Each conf route
+   *   declares its own, so one host serves as many repositories as it has routes.
    * @param {boolean} [options.redirect] - If true, enables RewriteEngine for redirection.
    * @param {string} [options.redirectTarget] - The target URL for redirection.
    * @param {boolean} [options.resetRouter] - If true, clears the existing router configuration before appending the new one.
    * @returns {{disabled: boolean}} An object indicating if the service is disabled.
    * @memberof LamppService
    */
-  createApp({ port, host, path, directory, rootHostPath, redirect, redirectTarget, resetRouter }) {
+  createApp({ port, host, path, directory, rootHostPath, repository, redirect, redirectTarget, resetRouter }) {
     if (!this.enabled()) return { disabled: true };
 
     if (!this.ports.includes(port)) this.ports.push(port);
@@ -231,7 +225,17 @@ class LamppService {
 
     const documentRoot = directory ? directory : `${getRootDirectory()}${rootHostPath}`;
 
-    // Append the new VirtualHost configuration
+    if (repository) {
+      const { accessible } = Underpost.repo.provisionSiteRoot({ host, siteRoot: documentRoot, repository });
+      // The checkout keeps its `.git` so the backup pipeline can commit and push it back; the
+      // vhost below denies it over HTTP.
+      if (accessible) Underpost.repo.initLocalRepo({ path: documentRoot, origin: repository });
+      // The vhost is still emitted, so the host answers rather than vanishing from the router —
+      // but Apache cannot stat a DocumentRoot that was never created and turns every request into
+      // a blanket 403. Named here, because that 403 carries nothing pointing back at this step.
+      else logger.error(`${host}: ${documentRoot} not provisioned — this vhost will answer 403 until it is`);
+    }
+
     this.appendRouter(`
 Listen ${port}
 
@@ -305,55 +309,3 @@ Listen ${port}
 const Lampp = new LamppService();
 
 export { Lampp };
-
-// -- helper info --
-
-// ERR too many redirects:
-// Check: SELECT * FROM database.wp_options where option_name = 'siteurl' or option_name = 'home';
-// Check: wp-config.php
-// if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
-//   $_SERVER['HTTPS'] = 'on';
-// }
-// For plugins:
-// define( 'FS_METHOD', 'direct' );
-
-// ErrorDocument 404 /custom_404.html
-// ErrorDocument 500 /custom_50x.html
-// ErrorDocument 502 /custom_50x.html
-// ErrorDocument 503 /custom_50x.html
-// ErrorDocument 504 /custom_50x.html
-
-// Respond When Error Pages are Directly Requested
-
-// <Files "custom_404.html">
-//     <If "-z %{ENV:REDIRECT_STATUS}">
-//         RedirectMatch 404 ^/custom_404.html$
-//     </If>
-// </Files>
-
-// <Files "custom_50x.html">
-//     <If "-z %{ENV:REDIRECT_STATUS}">
-//         RedirectMatch 404 ^/custom_50x.html$
-//     </If>
-// </Files>
-
-// Add www or https with htaccess rewrite
-
-// Options +FollowSymLinks
-// RewriteEngine On
-// RewriteCond %{HTTP_HOST} ^example.com [NC]
-// RewriteRule ^(.*)$ http://example.com/$1 [R=301,L]
-
-// Redirect http to https with htaccess rewrite
-
-// RewriteEngine On
-// RewriteCond %{SERVER_PORT} 80
-// RewriteRule ^(.*)$ https://www.example.com/$1 [R,L]
-
-// Redirect to HTTPS with www subdomain
-
-// RewriteEngine On
-// RewriteCond %{HTTPS} off [OR]
-// RewriteCond %{HTTP_HOST} ^www\. [NC]
-// RewriteCond %{HTTP_HOST} ^(?:www\.)?(.+)$ [NC]
-// RewriteRule ^ https://%1%{REQUEST_URI} [L,NE,R=301]

package/src/runtime/nginx/Nginx.js

@@ -9,7 +9,7 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { loggerFactory } from '../../server/logger.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 
 const logger = loggerFactory(import.meta);
 

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;