declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/tests-node/testdb-preflight-branches.declapract.integration.test.ts

@@ -0,0 +1,203 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = executes the REAL shipped `useWakeOfTestdb` template through its deterministic
+ *         decide-gate branches, with every boundary (fs, path, helpful-errors, probeTestDb)
+ *         injected — so the preflight's actual logic runs, not a source-text pin of it.
+ * .why  = a source-text pin (`.toContain('databaseUserName')`, `.toContain('config/test.json')`)
+ *         sails green past a logic bug that keeps the tokens — an inverted own-db gate, a probe
+ *         called before the config check, a validation that omits a key. the decide-steps are pure
+ *         state decisions (owns-db yes/no, config present/absent, config complete/incomplete) so
+ *         they run for real here with no live db — the probeTestDb boundary is stubbed, so no psql
+ *         subprocess is spawned and no local testdb is touched.
+ * .the-invariant = the preflight fires ONLY when the service owns a db AND its config is complete;
+ *         a service that owns no db is a no-op; an own-db service with an absent or incomplete
+ *         config fails LOUD (a ConstraintError that names the fix), never a silent skip.
+ * .teeth = invert the own-db gate and the no-db case reddens (a probe fires where it must not).
+ *          drop the absent-config throw and that case reddens. drop a key from the completeness
+ *          check and the incomplete-config case reddens. mis-map a probe arg and the complete case
+ *          reddens (the probe receives the wrong host/port/role).
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped template off
+ *         the filesystem. no network, no real subprocess — the probeTestDb boundary is stubbed. it
+ *         sits at the PRACTICE ROOT (not under `best-practice/`), because declapract's compile
+ *         strips `.declapract.test.ts` (+ `.snap`) but NOT `.declapract.integration.test.ts` — so an
+ *         integration clamp collocated inside `best-practice/` would SHIP to a consumer and apply as
+ *         an EQUALS template until ehmpathy/declapract#109 lands. the practice-root home keeps it out
+ *         of the emission set while it still clamps the shipped template by path
+ *         (`rule.require.declapract-integration-tests`).
+ */
+
+const SOURCE_PATH = `${__dirname}/best-practice/src/.test/useWakeOfTestdb.ts`;
+
+const COMPLETE_CONFIG = JSON.stringify({
+  database: {
+    tunnel: { local: { host: 'localhost', port: 5432 } },
+    role: { crud: { username: 'svc_x_crud', password: 'pw' } },
+    target: { database: 'svc_x_testdb' },
+  },
+});
+
+type ProbeArgs = {
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  database: string;
+};
+
+/**
+ * .what = transpile the template to CommonJS + execute its sole export with every boundary
+ *         stubbed, then report what crossed the probe boundary (the probeTestDb calls).
+ * .why  = the template imports `node:fs`, `node:path`, `helpful-errors`, and the neighbor
+ *         `../../jest.integration.env.db` probe; a require-stub feeds each a controlled fake so the
+ *         real decide-logic runs against inputs this test dictates, and the probe is observed
+ *         rather than performed (no psql subprocess, no local db).
+ */
+const runUseWakeOfTestdb = (input: {
+  declapractUse: string | null; // null = the declapract.use.yml file is absent
+  testConfig: string | null; // null = the config/test.json file is absent
+}): { probeCalls: ProbeArgs[] } => {
+  const source = readFileSync(SOURCE_PATH, 'utf8');
+  const transpiled = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+    },
+  }).outputText;
+
+  const probeCalls: ProbeArgs[] = [];
+
+  class FakeConstraintError extends Error {
+    public readonly meta: unknown;
+    constructor(message: string, meta?: unknown) {
+      super(message);
+      this.name = 'ConstraintError';
+      this.meta = meta;
+    }
+  }
+
+  // decide which file a path refers to by its tail — the template joins cwd with a fixed name
+  const asFileKey = (p: string): 'use' | 'config' | 'other' => {
+    if (p.endsWith('declapract.use.yml')) return 'use';
+    if (p.endsWith('test.json')) return 'config';
+    return 'other';
+  };
+  const contentFor = (key: 'use' | 'config'): string | null =>
+    key === 'use' ? input.declapractUse : input.testConfig;
+
+  const requireStub = (id: string): unknown => {
+    if (id === 'node:fs')
+      return {
+        existsSync: (p: string): boolean => {
+          const key = asFileKey(p);
+          return key !== 'other' && contentFor(key) !== null;
+        },
+        readFileSync: (p: string): string => {
+          const key = asFileKey(p);
+          return (key !== 'other' && contentFor(key)) || '';
+        },
+      };
+    if (id === 'node:path')
+      return { join: (...parts: string[]): string => parts.join('/') };
+    if (id === 'helpful-errors') return { ConstraintError: FakeConstraintError };
+    if (id === '../../jest.integration.env.db')
+      return {
+        probeTestDb: (args: ProbeArgs): void => {
+          probeCalls.push(args);
+        },
+      };
+    return {};
+  };
+
+  const moduleExports: Record<string, () => void> = {};
+
+  // eslint-disable-next-line no-new-func
+  new Function('exports', 'require', transpiled)(moduleExports, requireStub);
+  moduleExports.useWakeOfTestdb!();
+
+  return { probeCalls };
+};
+
+describe('the useWakeOfTestdb decide-gate runs its real branches (executed, no live db)', () => {
+  given('a service that owns no db (declapract.use.yml declares no databaseUserName)', () => {
+    when('the gate reads the declaration', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfTestdb({
+          declapractUse: 'useCase: lambda-service\n',
+          testConfig: COMPLETE_CONFIG,
+        }),
+      );
+      then('it is a no-op (the testdb is never preflighted)', () => {
+        expect(state.probeCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a service that owns a db (declapract.use.yml declares a databaseUserName)', () => {
+    const OWN_DB_USE = 'databaseUserName: svc-x-crud\n';
+
+    when('its config/test.json is complete', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfTestdb({
+          declapractUse: OWN_DB_USE,
+          testConfig: COMPLETE_CONFIG,
+        }),
+      );
+      then('it preflights the testdb with the config tunnel + role', () => {
+        expect(state.probeCalls).toEqual([
+          {
+            host: 'localhost',
+            port: 5432,
+            username: 'svc_x_crud',
+            password: 'pw',
+            database: 'svc_x_testdb',
+          },
+        ]);
+      });
+    });
+
+    when('its config/test.json is absent', () => {
+      then('it throws a ConstraintError that names config/test.json (never a silent skip)', () => {
+        const error = (() => {
+          try {
+            runUseWakeOfTestdb({ declapractUse: OWN_DB_USE, testConfig: null });
+            return null;
+          } catch (caught) {
+            return caught;
+          }
+        })();
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('config/test.json');
+      });
+    });
+
+    when('its config/test.json lacks an expected key (no role.crud)', () => {
+      then('it throws a ConstraintError that names the missing keys', () => {
+        const incomplete = JSON.stringify({
+          database: {
+            tunnel: { local: { host: 'localhost', port: 5432 } },
+            target: { database: 'svc_x_testdb' },
+          },
+        });
+        const error = (() => {
+          try {
+            runUseWakeOfTestdb({
+              declapractUse: OWN_DB_USE,
+              testConfig: incomplete,
+            });
+            return null;
+          } catch (caught) {
+            return caught;
+          }
+        })();
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('lacks an expected key');
+      });
+    });
+  });
+});

package/dist/practices/tests-node/testdb-preflight-env.declapract.integration.test.ts

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the WIRING half of the testdb preflight: `jest.integration.env.ts` imports
+ *         `useWakeOfTestdb` by RELATIVE path and calls it, so an own-db suite preflights its local
+ *         testdb before the first query.
+ * .why  = the collocated `useWakeOfTestdb.ts.declapract.integration.test.ts` proves the helper's
+ *         LOGIC in isolation; it cannot see whether the env still CALLS it. drop the call from the
+ *         env and every logic test stays green while the preflight silently vanishes — the exact
+ *         silent-regression this pins shut. this is the testdb-env counterpart to
+ *         `livedb-wake-prepare.declapract.integration.test.ts`, which pins the livedb wake into
+ *         the prepare composite.
+ * .teeth = drop the `useWakeOfTestdb` import or its call from `jest.integration.env.ts` and the
+ *          matched case reddens. swap the relative import for the `@src` alias (which fails at
+ *          startup, before jest's moduleNameMapper exists) and the relative-path case reddens.
+ * .note = subject is the shipped TEMPLATE text, read as a string. this file sits at the PRACTICE
+ *         root (not under `best-practice/`), so declapract's loader — which walks only
+ *         `best-practice/` for templates — never reads it as a declaration and never copies it to a
+ *         consumer (`define.declapract-test-files`).
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different
+// cwd, and a repo-root-relative path under process.cwd() would then miss the tree (vacuous green).
+const P = join(__dirname, 'best-practice');
+const read = (rel: string): string => readFileSync(join(P, rel), 'utf8');
+
+describe('testdb preflight is wired into the integration env', () => {
+  given('[case] jest.integration.env.ts', () => {
+    const envContents = read('jest.integration.env.ts');
+
+    when('[t0] the env is read', () => {
+      then('it imports useWakeOfTestdb by RELATIVE path (not the @src alias)', () => {
+        // a jest env loads before some resolvers settle; the shipped code uses the relative path
+        expect(envContents).toContain("from './src/.test/useWakeOfTestdb'");
+      });
+
+      then('it calls useWakeOfTestdb (preflight the local testdb)', () => {
+        expect(envContents).toContain('useWakeOfTestdb(');
+      });
+    });
+  });
+
+  given('[case] useWakeOfTestdb.ts self-gates', () => {
+    const helperContents = read('src/.test/useWakeOfTestdb.ts');
+
+    when('[t0] the preflight util is read', () => {
+      then('it gates on a declared databaseUserName (the own-db signal)', () => {
+        expect(helperContents).toContain('databaseUserName');
+      });
+
+      then('an own-db service with no config/test.json fails loud (never a silent skip)', () => {
+        // teeth: silent-skip the absent config (drop the throw) and both substrings vanish → reddens.
+        expect(helperContents).toContain('ConstraintError');
+        expect(helperContents).toContain('config/test.json');
+      });
+
+      then('it preflights via the probeTestDb boundary', () => {
+        expect(helperContents).toContain('probeTestDb(');
+      });
+    });
+  });
+});

package/dist/practices/tests-service/.test/assets/demo-repo-service/declapract.use.yml

@@ -0,0 +1,5 @@
+declarations: 'declarations/declapract.declare.yml'
+useCase: service-tests
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'

package/dist/practices/tests-service/.test/assets/demo-repo-service/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/tests-service/__snapshots__/package.json.declapract.integration.test.ts.snap

@@ -0,0 +1,26 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`tests-service package.json — the #598 wake-command gate, end to end given: [case1] a consumer that reaches the shared cluster (tunnel declared) when: [t0] the tests-service package.json declaration is applied then: the emitted package.json matches snapshot: package.json — tunnel consumer (wake command emitted) 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "devDependencies": {
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  },
+  "scripts": {
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
+  }
+}
+"
+`;
+
+exports[`tests-service package.json — the #598 wake-command gate, end to end given: [case2] a consumer that reaches NO cluster (no tunnel declared) when: [t0] the tests-service package.json declaration is applied then: the emitted package.json matches snapshot (the stripped shape): package.json — no-tunnel consumer (wake command stripped) 1`] = `
+"{
+  "name": "test-project",
+  "version": "1.0.0",
+  "devDependencies": {
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  }
+}
+"
+`;

package/dist/practices/tests-service/asFunctionNameFromTestFileName.ts

@@ -0,0 +1,7 @@
+import { basename } from 'node:path';
+
+export const asFunctionNameFromTestFileName = (input: {
+  relativeFilePath: string;
+}): string =>
+  // the function name = the test file's basename, minus the acceptance-test extension
+  basename(input.relativeFilePath).replace('.acceptance.test.ts', '');

package/dist/practices/tests-service/best-practice/.declapract.readme.md

@@ -0,0 +1,68 @@
+# tests-service
+
+the acceptance-test layer for a lambda service — blackbox tests that invoke a deployed (or local)
+lambda fleet through its real contract.
+
+## acceptance targets the contemp fleet
+
+a service that dual-publishes (see the `serverless` + `environments` practices) ships its fleet
+under BOTH slugs through the ancient→contemp transition: `-dev-` (ancient) and `-prep-`/`-prod-`
+(contemp) — the SAME artifact under two names. so its own acceptance suite proves ONE fleet, the
+contemp one: a run against contemp proves the deployed code, and the ancient slug is an alias for
+inbound callers still on the old name, never a second target for the self-acceptance gate.
+
+contemp is the service's own access-tier slug — `-prep-` at prep, `-prod-` at prod — so a single
+access-keyed run covers every tier the deploy job ships. there is no per-fleet fan-out and no
+per-tier skip.
+
+the reusable primitive lives in the `environments` practice, one procedure per file:
+`src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts` — `sdkAwsLambdaEnvAccessContemp()` emits the
+access direct (`-prep-` at prep, `-prod-` at prod). its ancient sibling
+`sdkAwsLambdaEnvAccessAncient()` (emits the `-dev-` slug below prod) serves OUTBOUND calls to
+unmigrated peers, not the self-acceptance suite.
+
+the composition atop that primitive is per-service (a service wraps `invokeLambdaForTesting` once,
+at a local seam, so the contemp-slug target lands in one place rather than at every call site):
+
+```ts
+// blackbox/lambdaTestMethods.ts — a per-service seam onto simple-lambda-testing-methods
+import { invokeLambdaForTesting as invokeLambdaForTestingRaw } from 'simple-lambda-testing-methods';
+import { sdkAwsLambdaEnvAccessContemp } from '../src/access/sdks/sdkAwsLambdaEnvAccessContemp';
+
+export const invokeLambdaForTesting: typeof invokeLambdaForTestingRaw = (input) =>
+  invokeLambdaForTestingRaw({ ...input, stage: sdkAwsLambdaEnvAccessContemp() });
+```
+
+each blackbox test imports `invokeLambdaForTesting` from that seam, and one package command runs the
+suite against the contemp fleet:
+
+```jsonc
+"test:acceptance": "set -eu && npm run test:acceptance:jest"
+```
+
+## why the seam is per-service, not a shipped template
+
+the seam is composition, not a primitive: a given service re-exports its own extra test operations
+through it (an apigateway-event builder, a graphql event builder), and its blackbox tree shape
+varies. so the practice ships the reusable primitive (the `EnvAccess` helper) and documents this
+composition, rather than a one-shape-fits-all seam file. lift the seam to a shipped template only
+once two or more services share the identical composition (`rule.prefer.wet-over-dry`).
+
+## the PR acceptance gate runs in-process; the deployed-fleet run is post-deploy
+
+the shared `.test.yml` PR gate (cicd-common) runs its acceptance shards IN-PROCESS (`LOCALLY=true`),
+because a PR has no deployed lambda to invoke. a service that publishes only dev/prep (no `test`
+fleet) would otherwise target `svc-<name>-test-*` — a slug that does not exist — and 404 on every
+call, so the PR gate would regress to all-404 the moment the suite is non-empty. the in-process
+default lets a fleetless service inherit a green PR gate out of the box, with no hand-patch. the
+acceptance run against a DEPLOYED fleet is a separate post-deploy grain (`.deploy-sls.yml`'s
+`assure` job), which invokes the real deployed lambda.
+
+## the CI acceptance gate runs contemp only
+
+`.deploy-sls.yml`'s `assure` job runs `ACCESS=${{ inputs.access }} npm run test:acceptance` ONCE —
+against the contemp fleet the same job just deployed. contemp maps to the deployed access at
+both prep and prod, so one run covers every tier this job ships. the ancient slug is proven by
+identity: dual-publish deploys the SAME artifact under the `-dev-` name, so a green contemp run is
+a green ancient run. the self-acceptance gate never invokes the ancient fleet — that slug exists
+for inbound callers still on the old name, an alias, never a second target to test.

package/dist/practices/tests-service/best-practice/blackbox/lambdas/<star>.acceptance.test.ts.declapract.ts

@@ -1,31 +1,56 @@
 import type { FileCheckFunction } from 'declapract';
-import expect from 'expect';
+import { ConstraintError } from 'helpful-errors';
 
-import { defineFunctionNameFromTestFileName } from '../../../defineFunctionNameFromTestFileName';
+import { asFunctionNameFromTestFileName } from '../../../asFunctionNameFromTestFileName';
 
 export const check: FileCheckFunction = (contents, context) => {
   if (!contents)
-    throw new Error('expected at least one lambda acceptance test');
+    throw new ConstraintError(
+      'expected at least one lambda acceptance test; add a `describe` block that invokes the lambda',
+      { relativeFilePath: context.relativeFilePath },
+    );
 
-  // check that each import was found
+  // check that each import was found.
+  // D52: this check no longer MANDATES `import { stage } from '.../environment'`. that line was
+  // break-by-conformance: it forced 88 blackbox files onto the legacy `dev`-slug axis to build a
+  // target fleet name no peer publishes below prod. a consumer may still import what it needs, but
+  // the practice must not require the exact token the north-star exists to retire. the fleet-
+  // name rewrite (dev↔prep) is the collapse-coupled half (D52b) and is out of this check.
+  //
+  // .note = the match below is literal, not semantic. it holds by construction on the file the
+  // practice itself stamps, but a consumer's own import-sorter may later wrap a line, merge it with
+  // a co-specifier import, or swap the quote style — any of which trips a cryptic `Expected imports`
+  // throw against a functionally-equivalent file. the literal match is deliberate (both lines dodge
+  // a typical print-width wrap), and a lenient regex/ast match is a tracked follow-on; this comment
+  // is the durable disclosure, so the brittleness is legible in-code, not only in the route yield
+  // (i015 r10 §3).
   const expectedImports = [
     "import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';",
-    "import { stage } from '../../src/utils/environment';",
     "import { locally } from '../environment';",
   ];
   const missedImports = expectedImports.filter(
     (expectedImport) => !contents.includes(expectedImport),
   );
   if (missedImports.length)
-    throw new Error(
+    throw new ConstraintError(
       `
 ${`- Expected imports ${['', ...expectedImports].join('\n  - ')}`}
       `.trim(),
+      { relativeFilePath: context.relativeFilePath, missedImports },
     );
 
-  const expectedTestName = defineFunctionNameFromTestFileName({ context });
+  const expectedTestName = asFunctionNameFromTestFileName({
+    relativeFilePath: context.relativeFilePath,
+  });
   const expectedDescribe = `
 describe('${expectedTestName}', () => {
   `.trim();
-  expect(contents).toContain(expectedDescribe);
+  // route the describe-name mismatch through a ConstraintError, same as the paths above —
+  // a bare `expect(...).toContain(...)` throws jest's raw ANSI+middle-dot diff, which snapshots
+  // as terminal noise (rule.forbid.snapshot-visual-blemishes). name the derived describe plainly.
+  if (!contents.includes(expectedDescribe))
+    throw new ConstraintError(
+      `expected a \`describe\` block that names the derived function: ${expectedDescribe}`,
+      { relativeFilePath: context.relativeFilePath, expectedTestName },
+    );
 };

package/dist/practices/tests-service/best-practice/package.json

@@ -1,5 +1,8 @@
 {
   "devDependencies": {
-    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.4.2')}"
+    "simple-lambda-testing-methods": "@declapract{check.minVersion('0.5.1')}"
+  },
+  "scripts": {
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
   }
 }

package/dist/practices/tests-service/best-practice/package.json.declapract.ts

@@ -1,3 +1,101 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { existsSync } from 'node:fs';
+import { readFile } from '../../../utils/readFile';
+
+/**
+ * .what = declare the tests-service package.json, with the `start:livedb:prep` wake command
+ *         included only when this service REACHES the shared aurora-serverless cluster —
+ *         signalled by a `database.tunnel` block in its own `config/prep.json`.
+ * .why  = the cicd-common test workflow already runs `npm run start:livedb:prep --if-present`
+ *         in both the integration + acceptance shards, but the command lived ONLY in
+ *         persist-with-rds — so a gateway/fan-out service (owns no db, but invokes peers that
+ *         query the shared cluster) never got it, the `--if-present` step no-op'd, and the
+ *         min-capacity-0 prep cluster was never woken in ci (#598). tests-service covers the
+ *         whole lambda-service set (gateways AND rds services), so it is the common-denominator
+ *         home for the wake. but a lambda-service that reaches NO cluster (no tunnel) must NOT
+ *         get it — else its `--if-present` step would fire `rhx use.rds.capacity` against a
+ *         cluster it does not use and could FAIL the job (the step has no swallow). so the emit
+ *         is self-gated on the tunnel: the same signal `useWakeOfLivedb` uses locally.
+ * .note = the discriminant is the CONSUMER's `config/prep.json`, not `context.projectPractices` —
+ *         a gateway declares its tunnel in config, not via a db-ownership practice. so this reads
+ *         the neighbor file via `getProjectRootDirectory()`, the check-context escape hatch.
+ * .note = persist-with-rds ALSO declares this command; both emit the IDENTICAL line, so an rds
+ *         service converges on one entry (the multi-declarer convergence pattern, as with the
+ *         repo-root .gitignore). additive by design — this does not touch persist-with-rds.
+ */
+
+/**
+ * .what = read whether the consumer declares a db tunnel in its config/<env>.json.
+ * .why  = the tunnel is the signal a service reaches the shared cluster (owns the db, or invokes
+ *         peers that query it). names the neighbor-read as one intent rather than an inline
+ *         positional decode (rule.forbid.inline-decode-friction).
+ * .note = an ABSENT config is benign — a service that declares no config/<env>.json reaches no
+ *         known cluster, so it returns false and gets no wake command (a false-negative just omits
+ *         a latency nicety, never breaks a suite; contrast the RUNTIME useWakeOfLivedb, likewise soft
+ *         on absence). but a PRESENT-yet-unparseable config is NOT benign: it means the consumer
+ *         authored a config the build cannot read, so a silent `return false` would conflate a
+ *         broken config with an absent tunnel (`rule.forbid.failhide`). so absence returns false
+ *         and a parse failure rethrows with context, naming the file to repair.
+ */
+const readReachesSharedCluster = async (input: {
+  projectRoot: string;
+  env: 'prep';
+}): Promise<boolean> => {
+  const configPath = `${input.projectRoot}/config/${input.env}.json`;
+  if (!existsSync(configPath)) return false; // no config = no known cluster (benign)
+  const raw = await readFile({ filePath: configPath });
+  try {
+    return !!JSON.parse(raw)?.database?.tunnel;
+  } catch (cause) {
+    // a non-Error throw is unexpected here; rethrow it verbatim rather than reclassify it
+    if (!(cause instanceof Error)) throw cause;
+    // a config the consumer authored but the build cannot parse is a real defect, not "no
+    // cluster" — a caller-must-fix condition, so throw a ConstraintError (exit 2) that NAMES the
+    // file, to match asPackageJSON's own class for the identical malformed-JSON case, so a
+    // consumer can machine-distinguish "my config is broken" from a server malfunction (never a
+    // silent false — `rule.forbid.failhide` / `rule.require.exit-code-semantics`)
+    throw new ConstraintError(
+      `tests-service: could not parse ${configPath} as JSON — fix the malformed config so the wake-command gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = return the package.json without the `start:livedb:prep` wake command; a `scripts` block
+ *         the strip leaves empty is removed too.
+ * .why  = names the tunnel-gated strip as one intent, so `contents` reads what-not-how rather than
+ *         an inline mutate-then-count-then-delete sequence a reader must simulate
+ *         (`rule.forbid.inline-decode-friction`). pure over a fresh clone of `pkg`, so the caller's
+ *         object is untouched and the leaf is independently testable.
+ */
+const withoutWakeCommand = (input: {
+  pkg: Record<string, any>;
+}): Record<string, any> => {
+  const pkg = { ...input.pkg, scripts: { ...input.pkg.scripts } };
+  delete pkg.scripts['start:livedb:prep'];
+  if (Object.keys(pkg.scripts).length === 0) delete pkg.scripts;
+  return pkg;
+};
+
+export const contents: FileContentsFunction = async (context) => {
+  // the superset: the package.json with the wake command included
+  const superset = JSON.parse(
+    await readFile({ filePath: `${__dirname}/package.json` }),
+  );
+
+  // keep the wake command when this service reaches the shared cluster; strip it otherwise
+  const reachesSharedCluster = await readReachesSharedCluster({
+    projectRoot: context.getProjectRootDirectory(),
+    env: 'prep',
+  });
+  const emitted = reachesSharedCluster
+    ? superset
+    : withoutWakeCommand({ pkg: superset });
+
+  return `${JSON.stringify(emitted, null, 2)}\n`;
+};
 
 export const check = FileCheckType.CONTAINS;