@underpostnet/cyberia 3.3.0 → 3.3.73

package/Dockerfile

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=production
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -26,10 +26,22 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all; rm -rf /var/cache/dnf; \
     npm cache clean --force
 
+
+# The builder's own `underpost clone` calls below run on this same CLI, and the runtime stage
+# inherits it through `COPY --from=builder /usr/local/`.
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version; \
+    # The staged package must be the pinned release: a drift here would ship a CLI the
+    # deployment manifests were not built against.
+    underpost --version | grep -Fq "${UNDERPOST_VERSION}"
+
 WORKDIR /home/dd
 
 # Comma-separated instance codes to provision (backup dir + optional saga).
@@ -38,7 +50,7 @@ WORKDIR /home/dd
 # `--build-arg INSTANCE_CODES=...`. Declared as an ARG (not a marker-wrapped
 # shell string) so the value is clean — a `/** … */` literal in the shell would
 # glob-expand in the `for` loop below.
-ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST"
+ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST,TEST"
 
 RUN --mount=type=secret,id=github_username \
     # --mount=type=secret,id=github_token \
@@ -83,7 +95,7 @@ RUN --mount=type=secret,id=github_username \
     cd /home/dd/engine; \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia production; \
+    node bin app load --env production --args deploy-id=dd-cyberia; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     # --- build the client bundle (assets are now in place) --------------------
     cd /home/dd/engine; \
@@ -136,11 +148,15 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
-    # underpost persists its global env at $(npm root -g)/underpost/.env; the
-    # non-root runtime user must be able to write it (fixes EACCES on start).
-    chown -R dd:dd /usr/local/lib/node_modules/underpost
+    # underpost persists its global env and container state under
+    # `$(npm root -g)/underpost` (getUnderpostRootPath). That path is a STORE directory, not
+    # the CLI package tree: the staged package installs under its own package name, and
+    # `underpost start --build` re-links the bin at the pulled checkout without moving the
+    # store (src/server/runtime/start.js#linkRuntimeCli). Create it here — the non-root
+    # runtime user cannot mkdir inside /usr/local itself (EACCES on the first state write).
+    mkdir -p "$(npm root -g)/underpost" && chown -R dd:dd "$(npm root -g)/underpost"
 
 # Copy ONLY the scrubbed runtime tree — no .git, no token, no caches.
 COPY --from=builder --chown=dd:dd /home/dd/engine /home/dd/engine

package/Dockerfile.dev

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=development
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -26,10 +26,22 @@ RUN set -eux; \
     curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
       | tar -xJ -C /usr/local --strip-components=1; \
     node --version; npm --version; \
-    npm install -g underpost@${UNDERPOST_VERSION}; \
     dnf clean all; rm -rf /var/cache/dnf; \
     npm cache clean --force
 
+
+# The builder's own `underpost clone` calls below run on this same CLI, and the runtime stage
+# inherits it through `COPY --from=builder /usr/local/`.
+COPY underpost-cli.tgz /tmp/underpost-cli.tgz
+RUN set -eux; \
+    npm install -g /tmp/underpost-cli.tgz --omit=dev; \
+    rm -f /tmp/underpost-cli.tgz; \
+    npm cache clean --force; \
+    underpost --version; \
+    # The staged package must be the pinned release: a drift here would ship a CLI the
+    # deployment manifests were not built against.
+    underpost --version | grep -Fq "${UNDERPOST_VERSION}"
+
 WORKDIR /home/dd
 
 # Comma-separated instance codes to provision (backup dir + optional saga).
@@ -38,7 +50,7 @@ WORKDIR /home/dd
 # `--build-arg INSTANCE_CODES=...`. Declared as an ARG (not a marker-wrapped
 # shell string) so the value is clean — a `/** … */` literal in the shell would
 # glob-expand in the `for` loop below.
-ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST"
+ARG INSTANCE_CODES="amethyst-strata-expansion,FOREST,TEST"
 
 RUN --mount=type=secret,id=github_username \
     # --mount=type=secret,id=github_token \
@@ -83,7 +95,7 @@ RUN --mount=type=secret,id=github_username \
     cd /home/dd/engine; \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia development; \
+    node bin app load --env development --args deploy-id=dd-cyberia; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     # --- build the client bundle (assets are now in place) --------------------
     cd /home/dd/engine; \
@@ -136,11 +148,15 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
-    # underpost persists its global env at $(npm root -g)/underpost/.env; the
-    # non-root runtime user must be able to write it (fixes EACCES on start).
-    chown -R dd:dd /usr/local/lib/node_modules/underpost
+    # underpost persists its global env and container state under
+    # `$(npm root -g)/underpost` (getUnderpostRootPath). That path is a STORE directory, not
+    # the CLI package tree: the staged package installs under its own package name, and
+    # `underpost start --build` re-links the bin at the pulled checkout without moving the
+    # store (src/server/runtime/start.js#linkRuntimeCli). Create it here — the non-root
+    # runtime user cannot mkdir inside /usr/local itself (EACCES on the first state write).
+    mkdir -p "$(npm root -g)/underpost" && chown -R dd:dd "$(npm root -g)/underpost"
 
 # Copy ONLY the scrubbed runtime tree — no .git, no token, no caches.
 COPY --from=builder --chown=dd:dd /home/dd/engine /home/dd/engine

package/Dockerfile.test

@@ -6,7 +6,7 @@
 # Stage 1 — builder: clone the private deploy, build it, then scrub secrets.
 # ---------------------------------------------------------------------------
 FROM rockylinux/rockylinux:9 AS builder
-ARG UNDERPOST_VERSION=3.3.0
+ARG UNDERPOST_VERSION=3.3.73
 # Pin Node to an exact patch: dnf's nodejs:24 module lags (24.14.1) while
 # underpost's dependencies require >=24.15.0, so install the official binary.
 ARG NODE_VERSION=24.15.0
@@ -14,7 +14,7 @@ ENV NODE_ENV=development
 
 RUN set -eux; \
     # `sudo` is required because underpost's build steps shell out to
-    # `sudo cp`/`sudo rm` (src/server/start.js); the build runs as root so sudo
+    # `sudo cp`/`sudo rm` (src/server/runtime/start.js); the build runs as root so sudo
     # is just a passthrough, but the binary must exist.
     dnf install -y git openssl tar xz sudo; \
     arch="$(uname -m)"; \
@@ -71,7 +71,7 @@ RUN --mount=type=secret,id=github_token \
     \
     # --- install deps + env, then replay build-safe itc provisioning ----------
     npm install; \
-    node bin env dd-cyberia development; \
+    node bin app load --env development --args deploy-id=dd-cyberia; \
     node bin fs --pull --recursive --deploy-id dd-cyberia --storage-file-path './engine-private/conf/dd-cyberia/storage.engine-cyberia.json'; \
     ( cd /home/dd/engine/hardhat && npm install --include=dev ); \
     ( cd /home/dd/engine && underpost clone underpostnet/cyberia-server ); \
@@ -140,7 +140,7 @@ COPY --from=builder /usr/local/ /usr/local/
 RUN dnf install -y libstdc++ git sudo && dnf clean all && rm -rf /var/cache/dnf && \
     useradd --create-home --home-dir /home/dd --shell /usr/sbin/nologin dd && \
     # The runtime runs as `dd`, but `underpost start --build` shells out to `sudo cp`/`sudo rm`
-    # (src/server/start.js). Grant passwordless sudo so those succeed without a TTY/password.
+    # (src/server/runtime/start.js). Grant passwordless sudo so those succeed without a TTY/password.
     printf 'dd ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/dd && chmod 0440 /etc/sudoers.d/dd && \
     # underpost persists its global env at $(npm root -g)/underpost/.env; the
     # non-root runtime user must be able to write it (fixes EACCES on start).

package/README.md

@@ -8,9 +8,29 @@
 
 _Stackable Rendering Layers as a Unified Tokenized Reality_
 
-[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.org/package/cyberia)
+</div>
+
+<!-- Tech stack -->
+<div align="center">
+
+<a target="_top" href='https://download.rockylinux.org/pub/rocky/9/'><img alt='rockylinux' src='https://img.shields.io/badge/Rocky Linux v9.8-100000?style=flat&logo=rockylinux&logoColor=white&labelColor=10b981&color=727273'/></a> <a target="_top" href='https://www.npmjs.com/package/npm?activeTab=versions'><img alt='npm' src='https://img.shields.io/badge/npm v11.6.2-100000?style=flat&logo=npm&logoColor=white&labelColor=CB3837&color=727273'/></a> <a target="_top" href='https://nodejs.org/download/release'><img alt='nodedotjs' src='https://img.shields.io/badge/node v24.15.0-100000?style=flat&logo=nodedotjs&logoColor=white&labelColor=5FA04E&color=727273'/></a> <a target="_top" href='https://pgp.mongodb.com/'><img alt='mongodb' src='https://img.shields.io/badge/mongodb_server v7.0-100000?style=flat&logo=mongodb&logoColor=white&labelColor=47A248&color=727273'/></a>
 
 </div>
+
+<!-- CI/CD and health -->
+<div align="center">
+
+[![Node.js CI](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/docker-image.engine-cyberia.ci.yml?branch=main&label=Node.js%20CI)](https://github.com/underpostnet/engine-cyberia/actions/workflows/docker-image.engine-cyberia.ci.yml) [![Test](https://img.shields.io/github/actions/workflow/status/underpostnet/engine-cyberia/coverall.cyberia.ci.yml?branch=main&label=Test)](https://github.com/underpostnet/engine-cyberia/actions/workflows/coverall.cyberia.ci.yml) [![Coverage Status](https://coveralls.io/repos/github/underpostnet/engine-cyberia/badge.svg?branch=main)](https://coveralls.io/github/underpostnet/engine-cyberia?branch=main) [![Socket Badge](https://socket.dev/api/badge/npm/package/cyberia/3.3.73)](https://socket.dev/npm/package/cyberia/overview/3.3.73)
+
+</div>
+
+<!-- Distribution and package -->
+<div align="center">
+
+[![Version](https://img.shields.io/npm/v/cyberia.svg)](https://www.npmjs.com/package/cyberia) [![Downloads](https://img.shields.io/npm/dm/cyberia.svg)](https://www.npmjs.com/package/cyberia) [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/cyberia/badge)](https://www.jsdelivr.com/package/npm/cyberia) [![License](https://img.shields.io/npm/l/cyberia.svg)](https://www.npmjs.com/package/cyberia)
+
+</div>
+
 Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
 toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
 runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.

package/bin/build.js

@@ -2,22 +2,26 @@
 
 import { Command } from 'commander';
 import fs from 'fs-extra';
-import dotenv from 'dotenv';
-import { loggerFactory } from '../src/server/logger.js';
+import { loggerFactory } from '../src/server/ops/logger.js';
 import { getCapVariableName } from '../src/client/components/core/CommonJs.js';
 import {
   getPathsSSR,
-  resolveDeployList,
   syncPrivateConf,
   syncDeployIdSources,
   buildTemplate,
   updatePrivateEngineTestRepo,
-} from '../src/server/conf.js';
-import { loadDeployCatalog } from '../src/server/catalog.js';
+} from '../src/server/runtime/conf.js';
+import { resolveDeployList } from '../src/server/network/router.js';
+import { loadDeployCatalog } from '../src/server/build/catalog.js';
+import { buildProductPackageJson, productPackageOptionsFactory } from '../src/server/build/package.js';
+import { COVERAGE_BUNDLE_DIRECTORY, bundleCoverageReport } from '../src/server/build/coverage.js';
+import { shellExec } from '../src/server/runtime/process.js';
 import Underpost from '../src/index.js';
 
-const baseConfPath = './engine-private/conf/dd-cron/.env.production';
-if (fs.existsSync(baseConfPath)) dotenv.config({ path: baseConfPath, override: true });
+// The host environment this entrypoint publishes with, read through the domain that owns it
+// rather than from a path: the durable source is one file per scope, and naming the pre-split
+// file here left the build with no credentials at all once that file was retired.
+for (const [key, value] of Object.entries(Underpost.host.read())) process.env[key] = value;
 
 const logger = loggerFactory(import.meta);
 
@@ -30,7 +34,7 @@ const basePath = '../pwa-microservices-template';
  * @param {string} confName - A concrete deploy id (e.g. `dd-prototype`).
  */
 const buildDeployTemplate = async (confName) => {
-  const repoName = `engine-${confName.split('dd-')[1]}`;
+  const repoName = Underpost.repo.engineRepoFactory(confName);
   const catalog = await loadDeployCatalog(confName);
 
   if (catalog.sourceMoves.length) {
@@ -107,34 +111,28 @@ const buildDeployTemplate = async (confName) => {
   if (!fs.existsSync(`${basePath}/.github/workflows`))
     fs.mkdirSync(`${basePath}/.github/workflows`, { recursive: true });
 
-  const originPackageJson = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
-  const packageJson = JSON.parse(fs.readFileSync(`${basePath}/package.json`, 'utf8'));
-  packageJson.name = repoName.replace('engine-', '');
+  const sourcePackageJson = JSON.parse(fs.readFileSync(`./package.json`, 'utf8'));
+  const basePackageJson = JSON.parse(fs.readFileSync(`${basePath}/package.json`, 'utf8'));
+
+  // A packaged path may be a nested project with its own installed tree; the
+  // product resolves dependencies from its own lockfile, never from a copy.
+  const copyTemplatePaths = () => {
+    for (const path of catalog.templatePaths)
+      fs.copySync(`.${path}`, `${basePath}${path}`, {
+        filter: (src) => !src.split('/').includes('node_modules'),
+      });
+  };
+
+  // The manifest a product publishes is its catalog's declaration, resolved the same way for
+  // every product: only the files a product places in the template are its own business.
+  const packageOptions = productPackageOptionsFactory({ catalog, underpostVersion: Underpost.version });
 
   switch (confName) {
     case 'dd-cyberia': {
-      const { CyberiaDependencies, DOCKER_SCRIPTS } = await import(
-        `../src/api/cyberia-server-defaults/cyberia-server-defaults.js`
-      );
-      fs.copyFileSync(`./bin/cyberia.js`, `${basePath}/bin/cyberia.js`);
       fs.copyFileSync(
         `./.github/workflows/publish.cyberia.ci.yml`,
         `${basePath}/.github/workflows/publish.cyberia.ci.yml`,
       );
-      if (packageJson.bin) delete packageJson.bin.underpost;
-      if (!packageJson.bin) packageJson.bin = {};
-      packageJson.bin.cyberia = 'bin/index.js';
-      packageJson.keywords = catalog.keywords;
-      packageJson.description = catalog.description;
-      packageJson.dependencies = {
-        underpost: '^' + Underpost.version.replace('v', ''),
-        'adm-zip': '^0.6.0',
-        ...CyberiaDependencies,
-      };
-      packageJson.scripts = {
-        ...packageJson.scripts,
-        ...DOCKER_SCRIPTS,
-      };
       fs.writeFileSync(`${basePath}/bin/index.js`, fs.readFileSync(`./bin/cyberia.js`, 'utf8'), 'utf8');
       // Canonical Cyberia doc; engine-cyberia/README.md is a generated copy — never hand-edited.
       fs.writeFileSync(
@@ -142,20 +140,23 @@ const buildDeployTemplate = async (confName) => {
         fs.readFileSync(`./src/client/public/cyberia-docs/CYBERIA.md`, 'utf8'),
         'utf8',
       );
-      fs.copySync(`./hardhat`, `${basePath}/hardhat`);
-      for (const path of catalog.templatePaths) fs.copySync(`.${path}`, `${basePath}${path}`);
+      copyTemplatePaths();
       break;
     }
     default:
-      for (const path of catalog.templatePaths) fs.copySync(`.${path}`, `${basePath}${path}`);
+      copyTemplatePaths();
       break;
   }
 
-  fs.writeFileSync(
-    `${basePath}/package.json`,
-    JSON.stringify(packageJson, null, 4).replaceAll('pwa-microservices-template', repoName),
-    'utf8',
-  );
+  const packageJson = buildProductPackageJson({
+    basePackageJson,
+    sourcePackageJson,
+    catalog,
+    confName,
+    repositoryName: repoName,
+    ...packageOptions,
+  });
+  fs.writeFileSync(`${basePath}/package.json`, JSON.stringify(packageJson, null, 4), 'utf8');
   if (fs.existsSync(`./deploy/${confName}`))
     fs.copySync(`./deploy/${confName}`, `${basePath}/deploy/${confName}`, {
       overwrite: true,
@@ -219,18 +220,36 @@ const buildDeployTemplate = async (confName) => {
   }
 };
 
+/**
+ * Carries this build stage's coverage HTML report into the assembled template, so every
+ * container started from the published source serves the report instead of generating one.
+ */
+const bundleDeployCoverage = () => {
+  const { bundled, from, to } = bundleCoverageReport('.', basePath);
+  if (bundled) return void logger.info('Build coverage artifact', { from, to });
+  logger.warn('No coverage report to bundle; the deploy will publish the unavailable page', {
+    hint: 'node bin/build <deploy-id> --coverage',
+    to,
+  });
+};
+
 const program = new Command();
 
 program
   .name('build')
   .description('Assemble deploy id public templates and sync their private configuration repos.')
-  .argument('<conf-name>', 'Deploy id, comma-separated list, or the "dd" meta id (fans out via dd.router).')
+  .argument('<conf-name>', 'Deploy id, comma-separated list, or the "dd" meta id (fans out via dd.routes).')
   .argument('[env]', 'Environment label (informational; kept for CI invocation compatibility).')
   .option('--conf', 'Sync each deploy id private configuration repo and exit (no template assembly).')
   .option(
     '--no-template-rebuild',
     'Skip the from-scratch base template reconstruction before assembly (assemble onto the existing template).',
   )
+  .option(
+    '--coverage',
+    `Run the test suite to refresh ./coverage before assembly, so the artifact carries a current ${COVERAGE_BUNDLE_DIRECTORY} report.`,
+    false,
+  )
   .option(
     '--update-private',
     'After assembling each deploy id, publish it to its private test source repo (underpostnet/engine-test-<id>) for isolated test deploys.',
@@ -248,12 +267,18 @@ program
       return;
     }
 
-    // Reconstruct the base template from 0 before assembly so no src from a previous
-    // build run leaks into this one. Opt out with --no-template-rebuild.
-    if (options.templateRebuild) await buildTemplate({ toPath: basePath });
+    // Tests run here, in the build stage, and exactly once: the artifact carries the report so
+    // no container ever has to produce its own. Refreshing is opt-in because a template
+    // assembly is not otherwise a test run.
+    if (options.coverage) shellExec(`npm run test:coverage`);
 
     for (const deployId of deployList) {
+      // Reconstruct the base template from 0 before each deploy id so neither a previous
+      // build run nor the deploy id assembled before this one leaks into it. Opt out with
+      // --no-template-rebuild.
+      if (options.templateRebuild) await buildTemplate({ toPath: basePath });
       await buildDeployTemplate(deployId);
+      bundleDeployCoverage();
       // Publish the just-assembled tree to the deploy id's private test repo so a
       // pod started with `--private-test-repo` clones this work-in-progress source.
       if (options.updatePrivate) await updatePrivateEngineTestRepo(deployId);

package/bin/build.template.js

@@ -3,8 +3,8 @@
 import { Command } from 'commander';
 import fs from 'fs-extra';
 import dotenv from 'dotenv';
-import { loggerFactory } from '../src/server/logger.js';
-import { buildTemplate, updatePrivateTemplateRepo } from '../src/server/conf.js';
+import { loggerFactory } from '../src/server/ops/logger.js';
+import { buildTemplate, updatePrivateTemplateRepo } from '../src/server/runtime/conf.js';
 
 if (fs.existsSync('./engine-private/conf/dd-cron/.env.production'))
   dotenv.config({ path: `./engine-private/conf/dd-cron/.env.production`, override: true });
@@ -20,10 +20,15 @@ program
   .argument('[src-path]', 'Engine source root to sync from.', './')
   .argument('[to-path]', 'Template output path.', '../pwa-microservices-template')
   .option('--update-private', 'Update private template repository', false)
+  .option('--no-clone', 'Fail instead of cloning when the template checkout is missing or foreign.')
   .action(async (srcPath, toPath, options) => {
     try {
       if (options.updatePrivate) return await updatePrivateTemplateRepo();
-      await buildTemplate({ srcPath: srcPath.replaceAll(`'`, ''), toPath: toPath.replaceAll(`'`, '') });
+      await buildTemplate({
+        srcPath: srcPath.replaceAll(`'`, ''),
+        toPath: toPath.replaceAll(`'`, ''),
+        noClone: options.clone === false,
+      });
     } catch (error) {
       logger.error(error, error.stack);
       process.exit(1);