@underpostnet/cyberia 3.3.73 → 3.3.77

package/test/unit/gateway-pod-fetch.test.js

@@ -0,0 +1,95 @@
+'use strict';
+
+import { expect } from 'chai';
+import shell from 'shelljs';
+import { vi } from 'vitest';
+import { gatewayPodFetch, parseRawHttpResponse } from '../../src/server/network/underpost-gateway.js';
+
+describe('gateway pod fetch', () => {
+  let commands;
+  let answer;
+
+  beforeEach(() => {
+    commands = [];
+    answer = (command) =>
+      command.includes('| nc ') ? 'HTTP/1.1 502 Bad Gateway\r\nServer: nginx\r\n\r\n<h1>maintenance</h1>\n' : '';
+    vi.spyOn(shell, 'exec').mockImplementation((command) => {
+      commands.push(command);
+      const stdout = answer(command);
+      return { code: 0, stdout, stderr: '', toString: () => stdout };
+    });
+  });
+
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reads the status and the body of an error response off the socket', () => {
+    // Regression: busybox wget discards the body of any non-2xx answer, so the fallback
+    // document — delivered with an upstream-failure status by definition — never
+    // matched, and the probe polled every attempt against a correct edge.
+    const result = gatewayPodFetch({ namespace: 'default', host: 'www.bymyelectrics.com', path: '/' });
+    expect(result).to.deep.equal({ status: '502', body: '<h1>maintenance</h1>\n' });
+    expect(commands.length).to.equal(1);
+    expect(commands[0]).to.include(
+      "printf 'GET / HTTP/1.0\\r\\nHost: www.bymyelectrics.com\\r\\n\\r\\n' | nc -w 10 127.0.0.1 80",
+    );
+  });
+
+  it('falls back to the wget pair for the status where nc is absent', () => {
+    answer = (command) => (command.includes('wget -S') ? 'HTTP/1.1 503 Service Unavailable\n' : '');
+    const result = gatewayPodFetch({ namespace: 'default', host: 'healthcare.nexodev.org' });
+    expect(result.status).to.equal('503');
+    expect(commands.length).to.equal(3);
+  });
+
+  it('parses a raw response byte for byte after the first blank line', () => {
+    expect(parseRawHttpResponse('')).to.deep.equal({ status: '', body: '' });
+    expect(parseRawHttpResponse('HTTP/1.0 200 OK\r\nX: y\r\n\r\n')).to.deep.equal({ status: '200', body: '' });
+    expect(parseRawHttpResponse('HTTP/1.1 504 Gateway Time-out\n\nline\n\nmore')).to.deep.equal({
+      status: '504',
+      body: 'line\n\nmore',
+    });
+  });
+});
+
+describe('gateway fetch', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  const mock = (answer) => {
+    const commands = [];
+    vi.spyOn(shell, 'exec').mockImplementation((command) => {
+      commands.push(command);
+      const stdout = answer(command);
+      return { code: 0, stdout, stderr: '', toString: () => stdout };
+    });
+    return commands;
+  };
+
+  it('asks the gateway Service from this host with curl, keeping the error body', async () => {
+    const { gatewayFetch } = await import('../../src/server/network/underpost-gateway.js');
+    const commands = mock((command) => {
+      if (command.includes('kubectl get svc underpost-gateway-service')) return '10.96.151.82\n';
+      if (command.startsWith('curl ')) return 'HTTP/1.1 502 Bad Gateway\r\nServer: nginx\r\n\r\n<h1>maintenance</h1>\n';
+      return '';
+    });
+    const result = gatewayFetch({ namespace: 'default', host: 'healthcare.nexodev.org', path: '/' });
+    expect(result).to.deep.equal({ status: '502', body: '<h1>maintenance</h1>\n', via: 'host' });
+    expect(commands.find((command) => command.startsWith('curl '))).to.include(
+      "-H 'Host: healthcare.nexodev.org' http://10.96.151.82:80/",
+    );
+    expect(commands.some((command) => command.includes('kubectl exec'))).to.equal(false);
+  });
+
+  it('falls back to the pod when the Service cannot be reached from here', async () => {
+    const { gatewayFetch } = await import('../../src/server/network/underpost-gateway.js');
+    mock((command) => {
+      if (command.includes('kubectl get svc underpost-gateway-service')) return '10.96.151.82\n';
+      if (command.includes('| nc ')) return 'HTTP/1.1 503 Service Unavailable\r\n\r\nbody';
+      return '';
+    });
+    expect(gatewayFetch({ namespace: 'default', host: 'healthcare.nexodev.org' })).to.deep.equal({
+      status: '503',
+      body: 'body',
+      via: 'pod',
+    });
+  });
+});

package/test/unit/letsencrypt-issuer.test.js

@@ -0,0 +1,101 @@
+'use strict';
+
+import { expect } from 'chai';
+import { load as yamlLoad } from 'js-yaml';
+import shell from 'shelljs';
+import { vi } from 'vitest';
+import UnderpostCluster from '../../src/cli/cluster.js';
+import UnderpostDeploy, { LETSENCRYPT_ISSUER_MANIFEST, LETSENCRYPT_ISSUER_NAME } from '../../src/cli/deploy.js';
+
+describe("Let's Encrypt issuer for the ingress stack in use", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  describe('acmeSolverFactory', () => {
+    it('answers through the Gateway API whenever its data plane is installed', () => {
+      // The `cluster` runner installs the issuer in an invocation that carries no stack
+      // flag, so the decision has to come from the cluster, not from the flags.
+      const presence = { contour: false, gateway: true };
+      expect(UnderpostCluster.API.acmeSolverFactory({ options: {}, presence })).to.equal('gateway');
+      expect(UnderpostCluster.API.acmeSolverFactory({ options: { gatewayApi: true }, presence })).to.equal('gateway');
+      expect(
+        UnderpostCluster.API.acmeSolverFactory({
+          options: { gatewayApi: true },
+          presence: { contour: true, gateway: false },
+        }),
+      ).to.equal('gateway');
+    });
+
+    it('keeps the Contour Ingress solver only where nothing else carries the challenge', () => {
+      expect(
+        UnderpostCluster.API.acmeSolverFactory({ options: {}, presence: { contour: true, gateway: false } }),
+      ).to.equal('ingress');
+      expect(
+        UnderpostCluster.API.acmeSolverFactory({
+          options: { contour: true },
+          presence: { contour: false, gateway: true },
+        }),
+      ).to.equal('ingress');
+    });
+  });
+
+  describe('letsEncryptIssuerYamlFactory', () => {
+    it('keeps the account from the base manifest and swaps in the Gateway solver', () => {
+      const base = yamlLoad(
+        UnderpostDeploy.API.letsEncryptIssuerYamlFactory({ solver: 'ingress', basePath: LETSENCRYPT_ISSUER_MANIFEST }),
+      );
+      const issuer = yamlLoad(
+        UnderpostDeploy.API.letsEncryptIssuerYamlFactory({
+          solver: 'gateway',
+          parentRefs: [
+            { name: 'dd-core-production', namespace: 'default' },
+            { name: 'dd-prototype-production', namespace: 'default' },
+          ],
+        }),
+      );
+      expect(issuer.kind).to.equal('ClusterIssuer');
+      expect(issuer.metadata.name).to.equal(LETSENCRYPT_ISSUER_NAME);
+      expect(issuer.spec.acme.email).to.equal(base.spec.acme.email);
+      expect(issuer.spec.acme.server).to.equal(base.spec.acme.server);
+      expect(issuer.spec.acme.privateKeySecretRef).to.deep.equal(base.spec.acme.privateKeySecretRef);
+      expect(issuer.spec.acme.solvers).to.deep.equal([
+        {
+          http01: {
+            gatewayHTTPRoute: {
+              parentRefs: [
+                { name: 'dd-core-production', namespace: 'default', kind: 'Gateway' },
+                { name: 'dd-prototype-production', namespace: 'default', kind: 'Gateway' },
+              ],
+            },
+          },
+        },
+      ]);
+      expect(base.spec.acme.solvers).to.deep.equal([{ http01: { ingress: { class: 'contour' } } }]);
+    });
+
+    it('refuses a Gateway solver with nothing to attach the challenge route to', () => {
+      expect(() => UnderpostDeploy.API.letsEncryptIssuerYamlFactory({ solver: 'gateway', parentRefs: [] })).to.throw(
+        /parentRef/,
+      );
+    });
+  });
+
+  describe('acmeGatewayParentRefsFactory', () => {
+    it('unions the live Gateways with the routed deploys, once each, sorted', () => {
+      vi.spyOn(shell, 'exec').mockImplementation((command) => {
+        const stdout = command.startsWith('kubectl get gateway')
+          ? 'gateway.gateway.networking.k8s.io/dd-core-production\ngateway.gateway.networking.k8s.io/other-production\n'
+          : '';
+        return { code: 0, stdout, stderr: '', toString: () => stdout };
+      });
+      vi.spyOn(UnderpostDeploy.API, 'gatewayNameFactory').mockImplementation(
+        ({ deployId, env }) => `${deployId}-${env}`,
+      );
+      const refs = UnderpostDeploy.API.acmeGatewayParentRefsFactory({ namespace: 'default', env: 'production' });
+      const names = refs.map(({ name }) => name);
+      expect(names).to.include('dd-core-production');
+      expect(names).to.include('other-production');
+      expect(names).to.deep.equal([...new Set(names)].sort());
+      expect(refs.every(({ namespace }) => namespace === 'default')).to.equal(true);
+    });
+  });
+});

package/test/unit/logger-redaction.test.js

@@ -21,6 +21,35 @@ const renderLog = (message, metadata) => {
 };
 
 describe('central logger redaction', () => {
+  it('filters a credential a service reports next to its name, with no delimiter between them', () => {
+    // Regression: `Invalid api_key 4778…` reached the terminal in full. Every rule matched on a
+    // delimiter — `=`, `:`, a flag — and an error message carries none, so the pair went through.
+    expect(redactSensitiveText('Invalid api_key 477826957851424')).to.equal('Invalid api_key [REDACTED]');
+    expect(redactSensitiveText('Invalid api_secret 8kQvN2mLp0XyZ_abc')).to.equal('Invalid api_secret [REDACTED]');
+    expect(redactSensitiveText('CLOUDINARY_API_KEY 477826957851424')).to.equal('CLOUDINARY_API_KEY [REDACTED]');
+  });
+
+  it('leaves prose and identifiers that merely follow a sensitive word', () => {
+    // The name of a thing is not the thing: redacting the next word of every sentence would cost
+    // more legibility than it buys protection, so the value has to be shaped like a credential.
+    for (const kept of [
+      'token verification failed',
+      'password changed successfully',
+      'authorization required for this route',
+      'api_secret mismatch',
+      'Target pod: dd-cyberia-production-blue-5b7c67bb8f-kwhz7 | Pod status: Running',
+    ])
+      expect(redactSensitiveText(kept), kept).to.equal(kept);
+  });
+
+  it('reaches a credential that a non-sensitive word precedes', () => {
+    // The scan looks ahead rather than consuming: matching `Invalid api_key` as a pair of its own
+    // would advance past the real one behind it.
+    const rendered = renderLog('cloudinary rejected: Invalid api_key 477826957851424');
+    expect(rendered).to.include('[REDACTED]');
+    expect(rendered).to.not.include('477826957851424');
+  });
+
   it('filters common secret forms from free-form messages', () => {
     const rawToken = `ghp_${'A'.repeat(30)}`;
     const input = [

package/test/unit/package.test.js

@@ -14,6 +14,7 @@ import {
   deployPackagePathFactory,
   productDevDependenciesFactory,
   productPackageOptionsFactory,
+  publishedProductPackageJson,
   stagePackageArchive,
   syncDeployPackages,
 } from '../../src/server/build/package.js';
@@ -38,7 +39,7 @@ describe('generated product package dependencies', () => {
         },
         productDependencies: {
           'runtime-shared': '3.0.0',
-          underpost: '^3.3.0',
+          nodemailer: '^10.0.0',
         },
         productDevDependencies: {
           'product-dev-only': '4.0.0',
@@ -72,7 +73,7 @@ describe('generated product package dependencies', () => {
       },
       catalog: { description: 'Cyberia CLI', keywords: ['cyberia'] },
       confName: 'dd-cyberia',
-      customDependencies: { underpost: '^3.3.0' },
+      customDependencies: { nodemailer: '^10.0.0' },
       customScripts: { build: 'node bin client' },
       customBin: { cyberia: 'bin/index.js' },
     });
@@ -82,7 +83,7 @@ describe('generated product package dependencies', () => {
       description: 'Cyberia CLI',
       keywords: ['cyberia'],
       bin: { cyberia: 'bin/index.js' },
-      dependencies: { underpost: '^3.3.0' },
+      dependencies: { nodemailer: '^10.0.0' },
       devDependencies: { express: '5.2.1', vitest: '4.1.11' },
       scripts: { test: 'node bin test', build: 'node bin client' },
     });
@@ -265,25 +266,78 @@ describe('generated deploy package manifests', () => {
 });
 
 describe('product manifest overrides read the catalog', () => {
-  it('carries the published engine CLI alongside the catalog pins', () => {
-    expect(
-      productPackageOptionsFactory({
-        catalog: {
-          packageDependencies: { ethers: '~6.16.0' },
-          packageBin: { cyberia: 'bin/index.js' },
-          packageScripts: { 'docker:up': 'node bin docker-compose --up' },
-        },
-        underpostVersion: 'v3.3.0',
-      }),
-    ).to.deep.equal({
-      customDependencies: { underpost: '^3.3.0', ethers: '~6.16.0' },
+  it('carries the engine runtime dependencies alongside the catalog pins', () => {
+    // Regression: the product depended on the published `underpost` package instead, which
+    // installed a second engine whose nested `nodemailer` `src/` could not resolve, while the
+    // hoistable copy survived only as a dev entry a production install omits.
+    const options = productPackageOptionsFactory({
+      catalog: {
+        packageDependencies: { ethers: '~6.16.0' },
+        packageBin: { cyberia: 'bin/index.js' },
+        packageScripts: { 'docker:up': 'node bin docker-compose --up' },
+      },
+      engineDependencies: { express: '^5.2.1', nodemailer: '^10.0.0' },
+    });
+
+    expect(options).to.deep.equal({
+      customDependencies: { express: '^5.2.1', nodemailer: '^10.0.0', ethers: '~6.16.0' },
       customScripts: { 'docker:up': 'node bin docker-compose --up' },
       customBin: { cyberia: 'bin/index.js' },
     });
+    expect(options.customDependencies).to.not.have.property('underpost');
+  });
+
+  it('lets a catalog pin override the engine version of the same dependency', () => {
+    expect(
+      productPackageOptionsFactory({
+        catalog: { packageDependencies: { sharp: '^0.35.3' } },
+        engineDependencies: { sharp: '^0.34.0' },
+      }).customDependencies,
+    ).to.deep.equal({ sharp: '^0.35.3' });
   });
 
   it('leaves the base template manifest alone for a catalog that declares no package', () => {
-    expect(productPackageOptionsFactory({ catalog: {}, underpostVersion: 'v3.3.0' })).to.deep.equal({});
+    expect(productPackageOptionsFactory({ catalog: {}, engineDependencies: { express: '^5.2.1' } })).to.deep.equal({});
+  });
+});
+
+describe('the manifest a product publishes to npm', () => {
+  it('trades the engine runtime set for the published CLI and the catalog pins', () => {
+    const published = publishedProductPackageJson({
+      packageJson: {
+        name: 'cyberia',
+        version: '3.3.73',
+        dependencies: { express: '^5.2.1', nodemailer: '^10.0.0', sharp: '^0.35.3' },
+        devDependencies: { vitest: '5.0.0' },
+      },
+      catalog: { packageDependencies: { sharp: '^0.35.3', ethers: '~6.16.0' } },
+    });
+
+    expect(published.dependencies).to.deep.equal({ underpost: '^3.3.73', sharp: '^0.35.3', ethers: '~6.16.0' });
+    expect(published.devDependencies).to.deep.equal({
+      express: '^5.2.1',
+      nodemailer: '^10.0.0',
+      vitest: '5.0.0',
+    });
+    expect(published.name).to.equal('cyberia');
+  });
+
+  it('pins the engine CLI at the version it is given, tag stripped', () => {
+    expect(
+      publishedProductPackageJson({ packageJson: { version: '3.3.73' }, underpostVersion: 'v4.0.0' }).dependencies,
+    ).to.deep.equal({ underpost: '^4.0.0' });
+  });
+
+  it('refuses a manifest it cannot pin the engine CLI from', () => {
+    expect(() => publishedProductPackageJson()).to.throw('packageJson');
+    expect(() => publishedProductPackageJson({ packageJson: { name: 'cyberia' } })).to.throw('version');
+  });
+
+  it('leaves the repository manifest as the checkout installs from', () => {
+    const packageJson = { version: '1.0.0', dependencies: { express: '^5.2.1' } };
+    publishedProductPackageJson({ packageJson });
+
+    expect(packageJson).to.deep.equal({ version: '1.0.0', dependencies: { express: '^5.2.1' } });
   });
 });
 

package/test/unit/prepare-host.test.js

@@ -81,7 +81,12 @@ describe('a node installs the deploy own package manifest', () => {
     try {
       const emitted = run(`install_deploy_dependencies ${root} dd-absent`).trim().split('\n');
       expect(emitted[0]).to.equal(`Install dependencies :: sudo -n -- /bin/bash -lc cd ${root} && npm install`);
-      expect(emitted[1]).to.include(`Link underpost CLI :: sudo -n -- /bin/bash -lc cd ${root} && npm link --force`);
+      // The link is a symlink onto the checkout's entrypoint, and a restored checkout can leave
+      // that file without its executable mode, so the link step restores it before linking.
+      expect(emitted[1]).to.include(
+        `Link underpost CLI :: sudo -n -- /bin/bash -lc cd ${root} && chmod +x ./bin/index.js && npm link --force`,
+      );
+      expect(emitted[1]).to.include('test -x ./bin/index.js');
     } finally {
       fs.removeSync(root);
     }
@@ -297,3 +302,81 @@ describe('prepare_host brings a node up in an order it can recover from', () =>
     expect(emitted.at(-1)).to.include('node bin host load');
   });
 });
+
+const cyberiaDeployScript = path.join(deployRoot, 'dd-cyberia/sync-deploy.sh');
+
+describe.skipIf(!fs.existsSync(cyberiaDeployScript))('a pod lands its private configuration at engine-private', () => {
+  const source = fs.existsSync(cyberiaDeployScript) ? fs.readFileSync(cyberiaDeployScript, 'utf8') : '';
+
+  it('names the pod conf repository once and derives the directory the clone lands in', () => {
+    expect(source).to.match(/^POD_SRC_PRIVATE_REPO="\$\{POD_SRC_PRIVATE_REPO:-[^"]+\}"$/m);
+    expect(source).to.include('underpost clone ${POD_SRC_PRIVATE_REPO}');
+    expect(source).to.include('POD_SRC_PRIVATE_DIR="${POD_SRC_PRIVATE_REPO##*/}"');
+    expect(source).to.include('sudo mv ./${POD_SRC_PRIVATE_DIR} ./engine-private');
+  });
+
+  it('clears the destination first, so the checkout replaces engine-private instead of nesting in it', () => {
+    const cleared = source.indexOf('sudo rm -rf ./engine-private');
+    const moved = source.indexOf('sudo mv ./${POD_SRC_PRIVATE_DIR} ./engine-private');
+    expect(cleared).to.be.greaterThan(-1);
+    expect(cleared).to.be.lessThan(moved);
+  });
+});
+
+// Every script under deploy/ is the same shape on purpose: one entry point, one constants block,
+// and no value repeated across files. A second shape is how the drift starts, so it is asserted
+// here rather than left to review.
+describe.skipIf(!shipsDeployIds)('every deploy script is written to one shape', () => {
+  const libDirectory = path.join(deployRoot, 'lib');
+  const scripts = fs
+    .readdirSync(deployRoot)
+    .filter((entry) => fs.statSync(path.join(deployRoot, entry)).isDirectory() && entry !== 'lib')
+    .flatMap((directory) =>
+      fs
+        .readdirSync(path.join(deployRoot, directory))
+        .filter((file) => file.endsWith('.sh'))
+        .map((file) => ({
+          id: `${directory}/${file}`,
+          source: fs.readFileSync(path.join(deployRoot, directory, file), 'utf8'),
+        })),
+    );
+  const libraries = fs
+    .readdirSync(libDirectory)
+    .filter((file) => file.endsWith('.sh'))
+    .map((file) => ({ id: `lib/${file}`, source: fs.readFileSync(path.join(libDirectory, file), 'utf8') }));
+
+  it('opens and closes every entry point the same way', () => {
+    expect(scripts).to.not.be.empty;
+    for (const { id, source } of scripts) {
+      expect(source.startsWith('#!/bin/bash\nset -euo pipefail\n'), id).to.equal(true);
+      expect(source, id).to.include('source "$SCRIPT_DIR/../lib/github-actions-logging.sh"');
+      expect(source.trimEnd().endsWith('main "$@"'), id).to.equal(true);
+    }
+  });
+
+  it('leaves the shared values to lib/config.sh, so no script carries a copy', () => {
+    // The engine root, the ingress node, the fleet's node names, the ssh key and the WordPress
+    // image were each pasted into a dozen scripts before this.
+    for (const { id, source } of scripts) {
+      expect(source, id).to.not.match(/^ENGINE_ROOT=/m);
+      expect(source, id).to.not.match(/^INGRESS_NODE=/m);
+      expect(source, id).to.not.include('/home/dd/engine');
+      expect(source, id).to.not.include('hp-envy');
+      expect(source, id).to.not.include('underpost/wp:');
+    }
+  });
+
+  it('states its deploy id once and reads it back from there', () => {
+    // A fleet-level script names no deploy of its own; one that names a deploy declares it.
+    for (const { id, source } of scripts.filter(({ source: text }) => /dd-[a-z0-9]/.test(text))) {
+      expect(source, id).to.match(/^DEPLOY_ID=dd-[a-z0-9-]+$/m);
+      const belowDeclaration = source.slice(source.indexOf('\n', source.search(/^DEPLOY_ID=/m)));
+      expect(belowDeclaration, id).to.not.match(/dd-[a-z0-9]/);
+    }
+  });
+
+  it('carries no library shebang and no trailing whitespace anywhere', () => {
+    for (const { id, source } of libraries) expect(source.startsWith('#!'), id).to.equal(false);
+    for (const { id, source } of [...scripts, ...libraries]) expect(source, id).to.not.match(/[ \t]+$/m);
+  });
+});

package/test/unit/release-bump.test.js

@@ -307,7 +307,9 @@ describe('release pipeline commands', () => {
         commands = [];
         const { triggerCmd } = await UnderpostRelease.API.ci(deployId, 'fixture message');
         expect(triggerCmd, deployId).to.include('/engine-cyberia');
-        expect(commands, deployId).to.include('node bin/build dd-cyberia');
+        // `--coverage`: the published source must carry the reports the deploy declares, or
+        // every pod started from it serves the unavailable page.
+        expect(commands, deployId).to.include('node bin/build dd-cyberia --coverage');
       }
     });
 

package/test/unit/start-options.test.js

@@ -37,6 +37,18 @@ describe('start receives every flag its command registers', () => {
     expect(buildContract).to.include('{ force: Underpost.state.isInsideContainer() }');
   });
 
+  it('withdraws the ephemeral engine-private clone once a production container is serving', () => {
+    // Regression: the domain-split withdraw passed `force: false` to every domain, and only
+    // `host clean --force` removes `engine-private` — the clone outlived the boot in the pod.
+    const runStart = source.indexOf('async run(');
+    const withdraw = source.slice(
+      source.indexOf('for (const domain of', runStart),
+      source.indexOf('setTimeout', runStart),
+    );
+    expect(withdraw).to.include('[Underpost.secret, Underpost.host, Underpost.app]');
+    expect(withdraw).to.include('force: domain === Underpost.host');
+  });
+
   it('runs the container in one phase, with no re-entry through the global CLI', () => {
     // The pod's own bootstrap replaces the checkout and links the CLI before `start` is
     // invoked, so re-execing `underpost start` here only pulled and installed a second time.

package/test/unit/test-tiers.test.js

@@ -6,10 +6,12 @@ import {
   TEST_TIERS,
   UNDERPOST_TESTING,
   coverageIncludeFactory,
+  coverageReportKey,
   coverageThresholdFactory,
   resolveTestSelection,
   testProjectsFactory,
   testSuiteNames,
+  vitestProjectSelector,
 } from '../../src/server/build/testing.js';
 
 // The table declares every tier the platform ships. A product build slices the
@@ -191,3 +193,28 @@ describe('coverage scope', () => {
     expect(() => coverageIncludeFactory(['--project', 'not-a-tier'])).to.throw(/unknown suite/);
   });
 });
+
+describe('coverage report directory', () => {
+  it('names the report after the suites the selection spans', () => {
+    expect(coverageReportKey('unit,infra,app')).to.equal('unit-infra-app');
+    expect(coverageReportKey('cyberia')).to.equal('cyberia');
+    expect(coverageReportKey('infra:1-security,infra:2-network')).to.equal('infra');
+  });
+
+  it('names every Vitest suite for a full run and none for a delegated one', () => {
+    expect(coverageReportKey('')).to.equal(coverageReportKey('all'));
+    expect(coverageReportKey('all').split('-')).to.have.members([
+      ...new Set(TEST_TIERS.filter(({ delegate }) => !delegate).map(({ name }) => name.split(':')[0])),
+    ]);
+    expect(coverageReportKey('contracts')).to.equal('');
+  });
+
+  // A deploy names its report by suite and the runner is handed the same tiers as
+  // `--project` flags; both must land on one directory.
+  it('agrees between a suite selector and the projects the runner was handed', () => {
+    const { projects } = resolveTestSelection('unit,infra,app');
+    const argv = ['npx', 'vitest', 'run', ...projects.flatMap((project) => ['--project', project]), '--coverage'];
+    expect(coverageReportKey(vitestProjectSelector(argv))).to.equal(coverageReportKey('unit,infra,app'));
+    expect(vitestProjectSelector(['--project=cyberia'])).to.equal('cyberia');
+  });
+});