declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/tests-node/livedb-wake-branches.declapract.integration.test.ts

@@ -0,0 +1,227 @@
+import { readFileSync } from 'node:fs';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import ts from 'typescript';
+
+/**
+ * .what = executes the REAL shipped `useWakeOfLivedb` template through its deterministic
+ *         decide-gate branches, with every boundary (fs, child_process, env) injected — so
+ *         the wake's actual logic runs, not a source-text pin of it.
+ * .why  = `livedb-wake-globalsetup.declapract.integration.test.ts` pins the wake by SOURCE TEXT
+ *         (it `.toContain`s `process.env.CI`, `=== 'prod'`, `.database?.tunnel`, …). a logic
+ *         bug that keeps those tokens — an inverted gate, a swallowed timeout, a classifier that
+ *         rethrows every failure — sails through every pin green. the decide-steps are pure
+ *         state decisions (ci-skip, prod-skip, tunnel present/absent, parse-failure throw) and
+ *         the failure classifier is a pure allowlist, so they run for real here with no live
+ *         infra — the repo's own `runTargetSlug`/`probeTestDb` pattern.
+ * .the-invariant = each gate lets the wake through ONLY when it should: not-ci ∧ not-prod ∧
+ *         reaches-cluster. a config the consumer authored but the setup cannot parse throws
+ *         (never a silent false). a wake-command failure is tolerated loud; a non-child-process
+ *         error is rethrown.
+ * .teeth = invert any gate in the template (drop the ci return, the prod return, the tunnel
+ *          gate) and the matched case reddens — a caller reaches the cluster it must not, or
+ *          skips one it must. drop the parse-failure throw and the malformed-config case
+ *          reddens. widen the classifier to rethrow-none and the non-child-process case reddens.
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it reads the shipped template off
+ *         the filesystem. no network, no real subprocess — the child_process boundary is stubbed,
+ *         so the deployed cluster is never touched. 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/useWakeOfLivedb.ts`;
+
+/**
+ * .what = transpile the template to CommonJS + execute its sole export with every boundary
+ *         stubbed, then report what crossed each boundary (the exec calls, the stderr warns).
+ * .why  = the template imports `node:fs`, `node:child_process`, `node:path`, `helpful-errors`;
+ *         a require-stub feeds each a controlled fake so the real decide-logic runs against
+ *         inputs this test dictates, and the boundary effects are observed rather than performed.
+ */
+const runUseWakeOfLivedb = async (input: {
+  env: 'test' | 'prep' | 'prod' | null;
+  ci: boolean;
+  configText: string | null; // null = the config file is absent
+  wakeThrows?: unknown; // when set, the stubbed execSync throws this
+}): Promise<{ execCalls: string[]; stderr: string[] }> => {
+  const source = readFileSync(SOURCE_PATH, 'utf8');
+  const transpiled = ts.transpileModule(source, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+    },
+  }).outputText;
+
+  const execCalls: string[] = [];
+  const stderr: string[] = [];
+
+  class FakeConstraintError extends Error {
+    public readonly cause: unknown;
+    constructor(message: string, meta?: { cause?: unknown }) {
+      super(message);
+      this.name = 'ConstraintError';
+      this.cause = meta?.cause;
+    }
+  }
+
+  const requireStub = (id: string): unknown => {
+    if (id === 'node:child_process')
+      return {
+        execSync: (cmd: string): void => {
+          execCalls.push(cmd);
+          if (input.wakeThrows !== undefined) throw input.wakeThrows;
+        },
+      };
+    if (id === 'node:fs')
+      return {
+        existsSync: (): boolean => input.configText !== null,
+        readFileSync: (): string => input.configText ?? '',
+      };
+    if (id === 'node:path')
+      return { join: (...parts: string[]): string => parts.join('/') };
+    if (id === 'helpful-errors') return { ConstraintError: FakeConstraintError };
+    return {};
+  };
+
+  const moduleExports: Record<
+    string,
+    (i: { env: 'test' | 'prep' | 'prod' | null }) => Promise<void>
+  > = {};
+
+  // control the two process globals the template reads, and capture its stderr warns
+  const priorCi = process.env.CI;
+  if (input.ci) process.env.CI = '1';
+  else delete process.env.CI;
+  const priorWrite = process.stderr.write.bind(process.stderr);
+  (process.stderr as unknown as { write: (s: string) => boolean }).write = (
+    s: string,
+  ): boolean => {
+    stderr.push(s);
+    return true;
+  };
+
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function('exports', 'require', transpiled)(moduleExports, requireStub);
+    await moduleExports.useWakeOfLivedb!({ env: input.env });
+  } finally {
+    (process.stderr as unknown as { write: (s: string) => boolean }).write =
+      priorWrite as never;
+    if (priorCi === undefined) delete process.env.CI;
+    else process.env.CI = priorCi;
+  }
+
+  return { execCalls, stderr };
+};
+
+const TUNNEL_CONFIG = '{"database":{"tunnel":{"lambda":{"host":"x"}}}}';
+
+describe('the useWakeOfLivedb decide-gate runs its real branches (executed, no live infra)', () => {
+  given('a service that reaches the shared cluster (config declares a db tunnel)', () => {
+    when('the caller is not in ci and targets prep', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the cluster via the rhx skill for that access', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the target access is null (defaults to prep)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: null, ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it wakes the prep cluster by default', () => {
+        expect(state.execCalls).toEqual(['rhx use.rds.capacity --env prep']);
+      });
+    });
+
+    when('the run is in ci', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: true, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (ci wakes via the dedicated workflow step)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('the target access is prod', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prod', ci: false, configText: TUNNEL_CONFIG }),
+      );
+      then('it does NOT wake (prod never scales to 0)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a service that reaches no shared cluster', () => {
+    when('its config is absent', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: null }),
+      );
+      then('it does NOT wake (no known cluster)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+
+    when('its config declares no db tunnel', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({ env: 'prep', ci: false, configText: '{"database":{}}' }),
+      );
+      then('it does NOT wake (no reaches-cluster signal)', () => {
+        expect(state.execCalls).toEqual([]);
+      });
+    });
+  });
+
+  given('a config the consumer authored but the setup cannot parse', () => {
+    when('the wake gate reads it', () => {
+      then('it throws a ConstraintError that names the parse failure (never a silent false)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: '{ not: valid json',
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe('ConstraintError');
+        expect((error as Error).message).toContain('could not parse');
+      });
+    });
+  });
+
+  given('the wake command fails', () => {
+    when('it fails with a child-process shape (a non-zero exit)', () => {
+      const state = useBeforeAll(() =>
+        runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: { status: 1 },
+        }),
+      );
+      then('it tolerates the failure (non-fatal) and warns loud to stderr', () => {
+        expect(state.stderr.length).toBe(1);
+      });
+      then('the wake-failure warn matches snapshot', () => {
+        expect(state.stderr[0]).toMatchSnapshot('useWakeOfLivedb wake-failure warn');
+      });
+    });
+
+    when('it fails with a NON-child-process shape (a code malfunction)', () => {
+      then('it rethrows, never warns it away (rule.forbid.failhide)', async () => {
+        const error = await runUseWakeOfLivedb({
+          env: 'prep',
+          ci: false,
+          configText: TUNNEL_CONFIG,
+          wakeThrows: new Error('a real bug in this module'),
+        }).catch((caught: unknown) => caught);
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).message).toBe('a real bug in this module');
+      });
+    });
+  });
+});

package/dist/practices/tests-node/livedb-wake-prepare.declapract.integration.test.ts

@@ -0,0 +1,112 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #598: the two node suite configs COMPOSE the livedb wake with autoprune in ONE
+ *         globalSetup, in the right order, forward globalConfig -- and useWakeOfLivedb self-gates
+ *         so a service that reaches no cluster is a no-op.
+ * .why  = a gateway/fan-out service owns no db but invokes peers that query the shared prep
+ *         aurora-serverless cluster; at min-capacity 0 the cluster auto-pauses, so the first query
+ *         cold-starts past the 90s timeout and flakes the suite. the fix wakes the cluster before
+ *         the suite runs. jest allows ONE globalSetup, so the wake must COMPOSE with test-fns
+ *         autoprune (which also needs that hook) -- never REPLACE it. the trap the downstream
+ *         hand-fix fell into: `globalSetup: './jest.acceptance.prepare.ts'` that called only
+ *         the wake, a silent drop of autoprune (the #590 half-wired state). this clamp forbids
+ *         that: the composite must reach BOTH, wake FIRST, and forward globalConfig to autoprune
+ *         (test-fns reads its globalTeardown slot; a dropped arg falsely accuses a wired consumer).
+ * .teeth = drop the useWakeOfLivedb call, the autoprune forward, or the order from a composite and
+ *          the matched case reddens; weaken a useWakeOfLivedb self-gate (CI / prod / tunnel) and its
+ *          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`). that is why a source-text clamp lives here
+ *         rather than collocated: it spans SEVERAL files, so it is not a single-file clamp.
+ */
+
+// 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');
+
+const composites = [
+  { config: 'jest.integration.config.ts', setup: 'jest.integration.prepare.ts' },
+  { config: 'jest.acceptance.config.ts', setup: 'jest.acceptance.prepare.ts' },
+];
+
+describe('#598 livedb-wake composite globalSetup', () => {
+  for (const { config, setup } of composites) {
+    given(`[case] ${setup}`, () => {
+      const setupContents = read(setup);
+      const configContents = read(config);
+
+      when('[t0] the config is read', () => {
+        then(`it points globalSetup at ./${setup}`, () => {
+          expect(configContents).toContain(`globalSetup: './${setup}'`);
+        });
+      });
+
+      when('[t1] the composite globalSetup is read', () => {
+        then('it imports useWakeOfLivedb by RELATIVE path (not the @src alias)', () => {
+          // a globalSetup loads before jest moduleNameMapper, so @src fails at startup
+          expect(setupContents).toContain("from './src/.test/useWakeOfLivedb'");
+        });
+
+        then('it awaits useWakeOfLivedb (resume the cluster)', () => {
+          expect(setupContents).toContain('await useWakeOfLivedb(');
+        });
+
+        then('it forwards globalConfig to the autoprune setup', () => {
+          expect(setupContents).toContain('await autopruneSetup(globalConfig)');
+        });
+
+        then('it wakes BEFORE autoprune mints the run id (order)', () => {
+          const wakeAt = setupContents.indexOf('await useWakeOfLivedb(');
+          const pruneAt = setupContents.indexOf('await autopruneSetup(');
+          expect(wakeAt).toBeGreaterThanOrEqual(0);
+          expect(pruneAt).toBeGreaterThan(wakeAt);
+        });
+      });
+    });
+  }
+
+  given('[case] useWakeOfLivedb.ts self-gates', () => {
+    const wakeContents = read('src/.test/useWakeOfLivedb.ts');
+
+    when('[t0] the wake util is read', () => {
+      then('it skips in ci (ci wakes via the dedicated workflow step)', () => {
+        expect(wakeContents).toContain('process.env.CI');
+      });
+
+      then('it skips prod (prod never scales to 0)', () => {
+        expect(wakeContents).toContain("=== 'prod'");
+      });
+
+      then('it gates on a declared db tunnel (the reaches-cluster signal)', () => {
+        expect(wakeContents).toContain('.database?.tunnel');
+      });
+
+      then('it wakes via the rhx use.rds.capacity skill', () => {
+        expect(wakeContents).toContain('rhx use.rds.capacity --env');
+      });
+
+      then('a present-but-unparseable config fails loud, never a silent false (rule.forbid.failhide)', () => {
+        // a config the consumer authored but the setup cannot parse is a real defect, not "no
+        // cluster" — it throws a ConstraintError that names the file, rather than a silent false
+        // that conflates a broken config with an absent tunnel.
+        // teeth: silent-false the catch (drop the throw) and both substrings vanish → reddens.
+        expect(wakeContents).toContain('ConstraintError');
+        expect(wakeContents).toContain('could not parse');
+      });
+
+      then('the read-parse-decide is a named transformer, not inline in the wake (rule.require.named-transformers)', () => {
+        // the neighbor-config read + tunnel decision is one named intent, so the wake orchestrator
+        // reads what-not-how. teeth: inline the parse back into useWakeOfLivedb and this reddens.
+        expect(wakeContents).toContain('asReachesSharedClusterFromConfig');
+      });
+    });
+  });
+});

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', '');