declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/tests-node/best-practice/jest.integration.prepare.ts

@@ -0,0 +1,33 @@
+import autopruneSetup from 'test-fns/autoprune.setup.jest';
+
+import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
+
+/**
+ * .what = jest globalSetup for the integration suite — runs once, in the main process, before
+ *         jest forks its workers.
+ * .why =
+ *   - COMPOSES two setups that both need this one hook: the livedb wake (resume the shared
+ *     aurora-serverless cluster so the first query does not cold-start past the timeout) and
+ *     test-fns autoprune (mint this run's id BEFORE the first fork, so genTempDir dirs are
+ *     reclaimed). jest allows ONE globalSetup, so a service that needs both must compose them
+ *     here rather than pick one — a bare `globalSetup: 'test-fns/autoprune.setup.jest'` (the
+ *     shipped default) leaves the db un-woken, and a bare wake setup drops autoprune (every dir
+ *     stamped, none reclaimed — the #590 half-wired state).
+ *   - the wake runs FIRST (best-effort, self-gated on a declared db tunnel — a no-op for a
+ *     service that reaches no cluster), THEN autoprune mints the run id.
+ *   - `globalConfig` is FORWARDED to autoprune unchanged: test-fns reads its `globalTeardown`
+ *     slot to detect the half-wired state, and a dropped/defaulted arg would falsely accuse a
+ *     correctly-wired consumer (see test-fns autoprune.setup.jest .note).
+ * .note = `useWakeOfLivedb` is imported by RELATIVE path, never the `@src` alias — a globalSetup is
+ *         loaded by node's plain require BEFORE jest's moduleNameMapper exists, so `@src` here
+ *         fails with `Cannot find module` and kills the run at startup (the same trap test-fns'
+ *         own autoprune.setup.jest documents).
+ */
+// biome-ignore lint/style/noDefaultExport: jest globalSetup api requires default export
+export default async (globalConfig: { globalTeardown?: string | null }): Promise<void> => {
+  // the wake TARGET is always the prep cluster: a test-access AND a prep-access suite both fan out
+  // to the shared prep peer fleet (define.invariant.test-and-prep-reach-prep-peers), so 'prep' is
+  // the one cluster either access reaches; only prod is self-contained and never woken.
+  await useWakeOfLivedb({ env: 'prep' });
+  await autopruneSetup(globalConfig);
+};

package/dist/practices/tests-node/best-practice/jest.unit.config.ts

@@ -38,6 +38,13 @@ const config: Config = {
   ],
   setupFilesAfterEnv: ['./jest.unit.env.ts'],
 
+  // reclaim every temp dir genTempDir made this run (test-fns autoprune; needs test-fns >=1.16,
+  // the floor is 1.17). jest needs BOTH keys -- globalSetup stamps the run, globalTeardown reclaims
+  // its dirs. one key without the other stamps and never reclaims, a half-wired state test-fns itself
+  // detects + reports at runtime.
+  globalSetup: 'test-fns/autoprune.setup.jest',
+  globalTeardown: 'test-fns/autoprune.teardown.jest',
+
   // use 50% of threads to leave headroom for other processes
   maxWorkers: '50%', // https://stackoverflow.com/questions/71287710/why-does-jest-run-faster-with-maxworkers-50
 };

package/dist/practices/tests-node/best-practice/jest.unit.env.ts

@@ -3,8 +3,9 @@ import { join } from 'node:path';
 import util from 'node:util';
 
 import { jest } from '@jest/globals';
+import { ConstraintError } from 'helpful-errors';
 
-import { stage } from './src/utils/environment';
+import { access } from './src/utils/environment';
 
 // mock that getConfig just returns plaintext test env config in unit tests
 jest.mock('./src/utils/config/getConfig', () => ({
@@ -19,7 +20,10 @@ util.inspect.defaultOptions.depth = 5;
  * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
  */
 if (!existsSync(join(process.cwd(), 'package.json')))
-  throw new Error('no package.json found in cwd. are you @gitroot?');
+  throw new ConstraintError(
+    'no package.json found in cwd — run the unit suite from the git root',
+    { cwd: process.cwd() },
+  );
 
 /**
  * sanity check that unit tests are only run the 'test' environment
@@ -28,5 +32,8 @@ if (!existsSync(join(process.cwd(), 'package.json')))
  * - prevent prod state pollution with test data
  * - prevent financial mutations
  */
-if (stage !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
-  throw new Error(`unit-test does not target stage 'test'`);
+if (access !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new ConstraintError(
+    `unit tests must target the 'test' tier — set I_KNOW_THE_RISKS=true to override`,
+    { access },
+  );

package/dist/practices/tests-node/best-practice/jest.unit.env.ts.declapract.ts

@@ -14,7 +14,9 @@ import { readFile } from '../../../utils/readFile';
  */
 export const contents: FileContentsFunction = async (context) => {
   // grab the superset of best practices content
-  const contentsSuperset = await readFile(`${__dirname}/jest.unit.env.ts`);
+  const contentsSuperset = await readFile({
+    filePath: `${__dirname}/jest.unit.env.ts`,
+  });
 
   // remove the config mock block when the config practice is absent — immutable const, no reassign
   const contents = context.projectPractices.includes('config')

package/dist/practices/tests-node/best-practice/src/.test/useKeyrack.ts

@@ -0,0 +1,211 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+import { keyrack } from 'rhachet/keyrack';
+
+/**
+ * .what = parse the `export KEY=VALUE` lines of `aws ... export-credentials --format env` into a
+ *         `{ KEY: VALUE }` record.
+ * .why  = names the line-parse as one pure transform, so `exportAwsCredentialsFromSsoProfile` reads
+ *         what-not-how rather than an inline positional `match[1]!`/`match[2]!` decode a reader must
+ *         simulate. pure + boundary-free, so it is testable without the exec stub.
+ */
+const asCredentialsRecordFromExportLines = (input: {
+  output: string;
+}): Record<string, string> =>
+  Object.fromEntries(
+    input.output
+      .split('\n')
+      .map((line) => line.match(/^export\s+(\w+)=(.*)$/))
+      .filter((match): match is RegExpMatchArray => match !== null)
+      .map((match) => [match[1]!, match[2]!] as const),
+  );
+
+// an sso refresh is network-bound (identity-provider round-trip); a slow-but-valid refresh must not
+// read as a dead login. bound it generously, and name the budget so it is not a silent magic number.
+const SSO_EXPORT_TIMEOUT_MS = 30000;
+
+/**
+ * .what = export the aws credentials of an sso profile into a `{ KEY: VALUE }` record, via
+ *         `aws configure export-credentials --format env`.
+ * .why  = aws sdk v2 (used by simple-lambda-testing-methods, the blackbox lambda caller) cannot
+ *         derive an sso profile from AWS_PROFILE alone — it needs static creds in env. this is the
+ *         pure, injectable core of that export. it is a pure fn with the `exec` boundary injected,
+ *         so the failure path AND the all-clear path are both clamped + snapped.
+ * .note = a failed export is CALLER-must-fix (a stale/absent sso login), so it throws a
+ *         `ConstraintError` (exit 2) that NAMES the fix and PRESERVES the real cause on the chain —
+ *         a consumer can machine-distinguish "not logged in" from a malfunction a retry would fix
+ *         (a caller-must-fix ConstraintError, exit 2, over a server malfunction). the profile is passed as an
+ *         argv element, never interpolated into a shell string, so a profile with shell
+ *         metacharacters cannot be interpreted (no injection).
+ */
+export const exportAwsCredentialsFromSsoProfile = (
+  input: { profile: string },
+  context: { exec?: typeof execFileSync } = {},
+): Record<string, string> => {
+  const exec = context.exec ?? execFileSync;
+
+  // shell out to the aws cli for the profile's static creds; a failure here is caller-must-fix.
+  // an iife keeps the result a const (no `let` reassignment across the try) per immutable-vars.
+  const credOutput = ((): string => {
+    try {
+      // note = `as string` at an external boundary (node child_process types). with
+      //        `encoding: 'utf8'` execFileSync returns a string, but its overloads widen
+      //        to `string | Buffer` when the options object is passed as a variable rather
+      //        than an inline literal. correct type = `string`. removal path = pass the
+      //        options as an inline literal, or when @types/node narrows the dynamic-options
+      //        overload to honor a string `encoding` value.
+      return exec(
+        'aws',
+        [
+          'configure',
+          'export-credentials',
+          '--profile',
+          input.profile,
+          '--format',
+          'env',
+        ],
+        { encoding: 'utf8', timeout: SSO_EXPORT_TIMEOUT_MS },
+      ) as string;
+    } catch (error) {
+      throw new ConstraintError(
+        `failed to export aws credentials from sso profile '${input.profile}'. run: aws sso login --profile ${input.profile}`,
+        { cause: error },
+      );
+    }
+  })();
+
+  // parse the `export KEY=VALUE` lines into a record the caller can splice into process.env
+  return asCredentialsRecordFromExportLines({ output: credOutput });
+};
+
+/**
+ * .what = splice the sso profile's static creds into `env` and REMOVE AWS_PROFILE, so an aws-sdk v2
+ *         caller authenticates against the target.
+ * .why  = aws-sdk v2 (simple-lambda-testing-methods, the blackbox lambda caller) prefers AWS_PROFILE
+ *         over static env creds when both are present, and cannot derive an sso profile from
+ *         AWS_PROFILE alone. keyrack.source sets only AWS_PROFILE, so v2 auths against no target.
+ *         a splice of static creds AND a removal of AWS_PROFILE makes both v2 and v3 use them. this
+ *         is the single practice-owned guard for that v2 boundary, so every repo that invokes lambdas
+ *         in tests inherits it rather than rediscovers it after an opaque credential failure. it is
+ *         shared by BOTH jest envs (acceptance + integration) via useKeyrack -- the v2 gap is guarded once.
+ * .note = `env` is injected so the splice + the AWS_PROFILE removal are clamped without a real
+ *         process.env mutation; the caller passes process.env. `exportCreds` is injected too, so the
+ *         whole path is a pure fn with both boundaries mockable.
+ * .note = the splice is scoped to an `AWS_`-prefixed allowlist, never every key the cli emits. `aws
+ *         configure export-credentials --format env` emits only `AWS_*` creds today; the allowlist
+ *         keeps a future cli line, a proxy banner, or a nested-util var out of the shared process
+ *         env (no hidden side effect on an unrelated key). the AWS_PROFILE removal is DELIBERATE and must
+ *         persist for the suite lifetime — v2 prefers AWS_PROFILE over static creds, so a "restore"
+ *         would reintroduce the exact auth-against-no-target bug this guard exists to close; it is
+ *         scoped to the injected `env`, so a test clamps it without a real process.env edit.
+ */
+const AWS_CRED_KEY_PREFIX = 'AWS_';
+export const spliceAwsStaticCredsIntoEnv = (
+  input: { profile: string },
+  context: {
+    env: NodeJS.ProcessEnv;
+    exportCreds?: typeof exportAwsCredentialsFromSsoProfile;
+  },
+): void => {
+  const exportCreds = context.exportCreds ?? exportAwsCredentialsFromSsoProfile;
+
+  // splice ONLY the `AWS_`-prefixed creds — never an arbitrary key the cli happens to emit
+  const creds = exportCreds({ profile: input.profile });
+  for (const [key, value] of Object.entries(creds))
+    if (key.startsWith(AWS_CRED_KEY_PREFIX)) context.env[key] = value;
+
+  // v2 prefers AWS_PROFILE over static creds when both are set, so remove it now that creds are spliced
+  delete context.env.AWS_PROFILE;
+};
+
+/**
+ * .what = read the sso profile from `env.AWS_PROFILE`, or throw a ConstraintError that NAMES the fix.
+ * .why  = both aws jest envs need an sso profile, which keyrack.source sets from the consumer's
+ *         `.agent/keyrack.yml`. when that manifest never declares AWS_PROFILE, keyrack sets no key
+ *         and this guard fires — so the error must name the exact key to add, not blame
+ *         keyrack.source (which did its job). the #564 gap: the practice cannot ship the consumer's
+ *         keyrack.yml (it is a gitignored, consumer-local file), so it instead tells the consumer
+ *         precisely what to declare, and every aws consumer inherits that one coherent guard+message
+ *         (an error that names the fix) rather than re-derive it from an opaque credential miss.
+ * .note = caller-must-fix (the manifest lacks a key), so a ConstraintError (exit 2). `env` is
+ *         injected so both the present and absent paths are clamped without a real process.env read;
+ *         the caller passes process.env.
+ */
+export const getOneAwsSsoProfileFromEnv = (
+  input: Record<string, never>,
+  context: { env: NodeJS.ProcessEnv },
+): string => {
+  const profile = context.env.AWS_PROFILE;
+  if (!profile)
+    throw new ConstraintError(
+      'AWS_PROFILE not set. declare it in .agent/keyrack.yml (under env.test, and env.all so every tier sources it), so keyrack.source() can set it.',
+    );
+  return profile;
+};
+
+/**
+ * .what = source aws credentials from keyrack for the target tier and export them to `process.env`
+ *         in ONE call — the single entrypoint both jest envs use for credential setup.
+ * .why  = a jest env must not hand-roll the keyrack.source -> set ACCESS -> aws-sdk-v2 export
+ *         sequence inline; that spreads one concern across every env and drifts between them. this is
+ *         the org `useKeyrack` convention (svc-jobs / svc-notifications), so a consumer reads one
+ *         line rather than re-derives the sequence. it composes the injectable leaves above, so this
+ *         repo's test-coverage standard holds — the failure + all-clear paths stay clamped, unlike a
+ *         verbatim inline port.
+ * .how  =
+ *   1. skip in CI (credentials arrive from secrets, not keyrack)
+ *   2. skip if the consumer declares no `.agent/keyrack.yml`
+ *   3. keyrack.source for the tier (sets AWS_PROFILE)
+ *   4. set ACCESS for sdk-environment when the tier is not `test`
+ *   5. if static creds are already present, clear AWS_PROFILE so the sdk prefers them, and return
+ *   6. else, when the consumer requires aws auth, export the sso profile's static creds via the
+ *      shared v2 guard
+ * .note = `mode` defaults to `lenient` (the org useKeyrack default); the acceptance env passes
+ *         `strict` to keep its fail-fast-on-locked-key behavior.
+ */
+export const useKeyrack = (input?: {
+  env?: 'test' | 'prep' | 'prod';
+  owner?: string;
+  mode?: 'strict' | 'lenient';
+}): void => {
+  const env =
+    input?.env ?? ((process.env.ACCESS ?? 'test') as 'test' | 'prep' | 'prod');
+  const owner = input?.owner ?? 'ehmpath';
+  const mode = input?.mode ?? 'lenient';
+
+  // skip in CI — credentials arrive from secrets, not from a local keyrack
+  if (process.env.CI) return;
+
+  // skip if the consumer declares no keyrack manifest
+  const keyrackYmlPath = join(process.cwd(), '.agent/keyrack.yml');
+  if (!existsSync(keyrackYmlPath)) return;
+
+  // source the tier's aws profile from keyrack (sets AWS_PROFILE)
+  keyrack.source({ env, owner, mode });
+
+  // set ACCESS for sdk-environment when the tier is not the default `test`
+  if (env !== 'test') process.env.ACCESS = env;
+
+  // only aws consumers need the v2 static-cred export
+  const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
+  const requiresAwsAuth =
+    existsSync(declapractUsePath) &&
+    readFileSync(declapractUsePath, 'utf8').includes('awsAccountId');
+  if (!requiresAwsAuth) return;
+
+  // static creds already present (e.g. exported in the shell) — clear AWS_PROFILE so the sdk prefers
+  // the static creds (v2 prefers AWS_PROFILE over static creds when both are set), then return
+  if (process.env.AWS_ACCESS_KEY_ID) {
+    delete process.env.AWS_PROFILE;
+    delete process.env.AWS_DEFAULT_PROFILE;
+    return;
+  }
+
+  // read the sso profile keyrack.source set (throws an error that NAMES the keyrack fix if absent, #564),
+  // then splice its static creds into process.env for the aws-sdk-v2 lambda caller
+  const awsSsoProfile = getOneAwsSsoProfileFromEnv({}, { env: process.env });
+  spliceAwsStaticCredsIntoEnv({ profile: awsSsoProfile }, { env: process.env });
+};

package/dist/practices/tests-node/best-practice/src/.test/useWakeOfLivedb.ts

@@ -0,0 +1,181 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = wake the shared aurora-serverless cluster before a suite runs, when this
+ *         service reaches it — whether it OWNS the db or only invokes peers that do.
+ * .why =
+ *   - the non-prod cluster is aurora-serverless-v2 at min-capacity 0, so it auto-pauses
+ *     when idle; the first downstream query after a pause cold-starts past the 90s test
+ *     timeout and flakes the suite (svc-gateway hit this on mAddCrewMember + the quote suites)
+ *   - a gateway/fan-out service owns NO db of its own, so a db-ownership signal misses it.
+ *     the signal that it REACHES the shared cluster is a tunnel declared in its config —
+ *     `config/prep.json`'s `database.tunnel`. that is the self-gate: a tunnel means a query
+ *     lands on the cluster (direct or via a peer), so wake it; no tunnel means no-op.
+ *   - `rhx use.rds.capacity` opens an ssm tunnel to the cluster and waits for it to accept
+ *     connections, which resumes it for every consumer (incl. deployed lambdas), not just
+ *     the local caller
+ *   - best-effort: a warm db, absent tunnel alias, or absent skill must NEVER break the
+ *     suite, so a wake failure is surfaced loud to stderr (not swallowed) and the suite
+ *     proceeds — a wake is a latency nicety, not a correctness gate; the suite's own
+ *     assertions are the gate
+ *   - ci is skipped: creds arrive via oidc and the local ssm-tunnel path is unavailable there,
+ *     so ci wakes via the dedicated `start:livedb:prep` workflow step instead
+ * .note = this is the LIVEDB half of a suite's db needs — the shared prep cluster its peers query.
+ *         it RESUMES a paused cluster. its pair, `useWakeOfTestdb`, is the LOCAL own-db half: it
+ *         only PREFLIGHTS the local testdb (it cannot start it, so it fails loud with a `start:testdb`
+ *         fix). the two form a symmetric pair; the name reads "wake" for symmetry, the act differs.
+ *         the wake fires for prep OR test access, per define.invariant.test-and-prep-reach-prep-peers.
+ */
+export const useWakeOfLivedb = async (
+  input: { env: 'test' | 'prep' | 'prod' | null },
+): Promise<void> => {
+  // in ci, the wake runs as a dedicated workflow step (local ssm-tunnel path is unavailable)
+  if (process.env.CI) return;
+
+  // prod never scales to 0, so it never needs a wake; default the target to prep
+  const env = input.env ?? 'prep';
+  if (env === 'prod') return;
+
+  // gate on a declared db tunnel: it is the signal this service reaches the shared cluster,
+  // whether it owns the db (persist-with-rds) or only invokes peers that query it (a gateway).
+  // absent config = no cluster to wake; a malformed config fails loud (names the file), never silent.
+  if (!asReachesSharedClusterFromConfig({ env })) return;
+
+  // the wake blocks suite start on a local run, so its budget is consumer-bounded: a generous
+  // default (a cold aurora-serverless-v2 resume can exceed 60s), overridable DOWN via
+  // LIVEDB_WAKE_TIMEOUT_MS so a consumer can fail fast on a hung tunnel rather than wait the full cap
+  const timeoutMs = Number(process.env.LIVEDB_WAKE_TIMEOUT_MS) || 180000;
+
+  // best-effort wake: a wake-command failure (a non-zero exit, a timeout kill, an absent binary) is
+  // non-fatal — a warm db or absent skill must not break the suite. but an error that bears no
+  // child-process shape is a malfunction in this module's own logic, so rethrow it (rule.forbid.failhide):
+  // the catch tolerates only the allowlisted wake failures and surfaces the rest.
+  try {
+    wakeSharedCluster({ env, timeoutMs });
+  } catch (error) {
+    if (!isWakeCommandFailure({ error })) throw error;
+    // a non-Error failure shape (e.g. a child-process `{ status, signal }` object) must read
+    // legibly on stderr: `String({...})` yields the useless `[object Object]`, so serialize it.
+    const message =
+      error instanceof Error ? error.message : JSON.stringify(error);
+    warnWakeFailed({ env, message });
+  }
+};
+
+/**
+ * .what = read the raw text of this service's `config/<env>.json`, or null when absent.
+ * .why  = a communicator leaf: the sole filesystem i/o of the wake gate, named so the
+ *         orchestrator composes it rather than embeds an inline `existsSync`/`readFileSync`.
+ * .note = an absent config is benign (a service that declares none reaches no known cluster),
+ *         so absence returns null and the pure decide-step below folds it to false. this leaf
+ *         performs i/o only; it never parses or decides.
+ */
+const readConfigText = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): string | null => {
+  const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+  if (!existsSync(configPath)) return null;
+  return readFileSync(configPath, 'utf8');
+};
+
+/**
+ * .what = decide, from raw config text, whether this service reaches the shared cluster.
+ * .why  = a pure transformer leaf: no i/o, deterministic. a `database.tunnel` in the config =
+ *         a query lands on the cluster (direct or via a peer), so the service reaches it.
+ *         the one fact — does this service reach the cluster — has one shape here, read off
+ *         the same `database.tunnel` signal everywhere, so two readers cannot drift.
+ */
+const asReachesSharedClusterFromConfigText = (input: {
+  text: string;
+}): boolean => {
+  return !!JSON.parse(input.text)?.database?.tunnel;
+};
+
+/**
+ * .what = compose the config read + tunnel decision into a single what-not-how signal.
+ * .why  = the composer of the two leaves above, so `useWakeOfLivedb` reads one intent rather than
+ *         an inline read-parse-decode a reader must simulate.
+ * .note = an absent config folds to false (no known cluster → no wake). but a present-yet-
+ *         unparseable config is NOT benign: it means the consumer authored a config the setup
+ *         cannot read, so a silent `false` would conflate a broken config with an absent tunnel.
+ *         so a parse failure throws a ConstraintError (caller-must-fix, exit 2) that names the
+ *         file + the fix, rather than a raw engine SyntaxError with no file and no remediation.
+ */
+const asReachesSharedClusterFromConfig = (input: {
+  env: 'test' | 'prep' | 'prod';
+}): boolean => {
+  const text = readConfigText({ env: input.env });
+  if (text === null) return false; // no config = no known cluster (benign)
+  try {
+    return asReachesSharedClusterFromConfigText({ text });
+  } catch (cause) {
+    // allowlist the ONLY error the parse-decide leaf can throw — a SyntaxError on malformed json.
+    // an error of any other shape is a malfunction in this module's own logic, not a config the
+    // consumer mis-authored, so surface it unwrapped rather than relabel it a parse failure
+    // (rule.forbid.failhide: a catch allowlists its expected errors and rethrows the rest).
+    if (!(cause instanceof SyntaxError)) throw cause;
+    // a config the consumer authored but the setup cannot parse is a real defect, not "no cluster" —
+    // throw with the path so a malformed config names the file to repair (never a silent false)
+    const configPath = join(process.cwd(), 'config', `${input.env}.json`);
+    throw new ConstraintError(
+      `useWakeOfLivedb: could not parse ${configPath} as JSON — fix the malformed config so the wake gate can read its database.tunnel signal`,
+      { cause },
+    );
+  }
+};
+
+/**
+ * .what = wake the shared cluster by an ssm tunnel that resumes it for every consumer.
+ * .why  = a communicator leaf: the sole subprocess i/o of the wake, named so the orchestrator
+ *         composes it rather than embeds an inline `execSync`. `rhx use.rds.capacity` opens the
+ *         tunnel and waits for the cluster to accept connections, which resumes it (incl. for
+ *         deployed lambdas), not just the local caller.
+ */
+const wakeSharedCluster = (input: {
+  env: 'test' | 'prep' | 'prod';
+  timeoutMs: number;
+}): void => {
+  execSync(`rhx use.rds.capacity --env ${input.env}`, {
+    stdio: 'inherit',
+    timeout: input.timeoutMs,
+  });
+};
+
+/**
+ * .what = surface a wake failure loud to stderr, non-fatal.
+ * .why  = a communicator leaf: the failure sink of the wake, named so the orchestrator composes
+ *         it rather than embeds an inline `process.stderr.write`. a real wake failure — a
+ *         miswired command, an absent skill, a broken rhx binary — must be visible, never hidden;
+ *         the suite proceeds and a downstream cold-start timeout flake is the likely symptom.
+ */
+const warnWakeFailed = (input: {
+  env: 'test' | 'prep' | 'prod';
+  message: string;
+}): void => {
+  process.stderr.write(
+    `useWakeOfLivedb: 'rhx use.rds.capacity --env ${input.env}' failed (non-fatal): ${input.message}\n`,
+  );
+};
+
+/**
+ * .what = decide whether an error is a wake-command failure (safe to tolerate) vs a code malfunction.
+ * .why  = a pure transformer leaf: the allowlist `rule.forbid.failhide` demands. an execSync failure
+ *         bears a child-process shape — a numeric `status` (a non-zero exit), a string `signal` (a
+ *         timeout kill), or a string `code` (`ENOENT` for an absent binary, `ETIMEDOUT` for the cap).
+ *         those are the wake failures the suite intends to tolerate. an error with none of that shape
+ *         is a genuine malfunction in this module's own logic, so the catch rethrows it, never warns
+ *         it away — a best-effort op still distinguishes the failures it ignores from the ones it must not.
+ */
+const isWakeCommandFailure = (input: { error: unknown }): boolean => {
+  const error = input.error;
+  if (!error || typeof error !== 'object') return false;
+  const shape = error as { status?: unknown; signal?: unknown; code?: unknown };
+  if (typeof shape.status === 'number') return true; // child exited non-zero
+  if (typeof shape.signal === 'string') return true; // child killed by a signal (a timeout)
+  if (typeof shape.code === 'string') return true; // ENOENT (absent binary), ETIMEDOUT (cap hit)
+  return false;
+};

package/dist/practices/tests-node/best-practice/src/.test/useWakeOfTestdb.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { ConstraintError } from 'helpful-errors';
+
+import { probeTestDb } from '../../jest.integration.env.db';
+
+/**
+ * .what = preflight the LOCAL testdb before a suite runs, when this service declares its own db.
+ * .why =
+ *   - prevent time wasted on a suite that fails deep in a query because the local testdb was never
+ *     provisioned, or was provisioned for a DIFFERENT repo (an opaque "password authentication
+ *     failed" surfaced far from its cause).
+ *   - the gate is a declared db: a `databaseUserName` in `declapract.use.yml` is the signal this
+ *     service OWNS a db (persist-with-rds), so it needs a local testdb. a service that declares none
+ *     is a no-op here.
+ *   - the check fails LOUD and CALLER-must-fix (a local testdb the human starts) via a ConstraintError
+ *     that names the fix — `probeTestDb` surfaces psql's own stderr so the consumer can tell "not
+ *     started" from "bad password" from "psql absent" (never a swallowed error).
+ * .note = this is the LOCAL own-db counterpart to `useWakeOfLivedb` (the shared prep cluster wake).
+ *         the two form a symmetric pair, but differ in one honest way: `useWakeOfLivedb` RESUMES a
+ *         paused cluster; this one only PREFLIGHTS the local testdb — it cannot start it, so it fails
+ *         loud with the `start:testdb` fix rather than resume it. the name reads "wake" for symmetry
+ *         with its pair; the act is a readiness preflight.
+ * .note = the LIVEDB half of a suite's db needs — the shared prep cluster its peers query — is woken
+ *         separately by `useWakeOfLivedb` in globalSetup, per
+ *         `define.invariant.test-and-prep-reach-prep-peers` (both test and prep access reach prep).
+ */
+export const useWakeOfTestdb = (): void => {
+  // gate: does this service own a db? a declared databaseUserName in declapract.use.yml is the signal.
+  const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
+  const declapractUseContent = existsSync(declapractUsePath)
+    ? readFileSync(declapractUsePath, 'utf8')
+    : '';
+  const requiresTestDb = declapractUseContent.includes('databaseUserName');
+  if (!requiresTestDb) return;
+
+  // an own-db service without config/test.json cannot preflight — name the fix (author the config)
+  const testConfigPath = join(process.cwd(), 'config', 'test.json');
+  if (!existsSync(testConfigPath))
+    throw new ConstraintError(
+      'config/test.json not found but a databaseUserName is declared in declapract.use.yml — author config/test.json with the testdb tunnel + role',
+      { testConfigPath },
+    );
+
+  // a present-but-incomplete config fails loud, and names the exact keys the preflight needs
+  const testConfig = JSON.parse(readFileSync(testConfigPath, 'utf8'));
+  if (
+    !testConfig.database?.tunnel?.local ||
+    !testConfig.database?.role?.crud ||
+    !testConfig.database?.target?.database
+  )
+    throw new ConstraintError(
+      'config/test.json lacks an expected key — declare database.tunnel.local, database.role.crud, and database.target.database',
+      {
+        hasTunnelLocal: !!testConfig.database?.tunnel?.local,
+        hasRoleCrud: !!testConfig.database?.role?.crud,
+        hasTargetDatabase: !!testConfig.database?.target?.database,
+      },
+    );
+
+  // preflight the testdb; probeTestDb surfaces psql's own stderr on failure (never a swallowed
+  // error) and passes PGPASSWORD via env, never the command args
+  probeTestDb({
+    host: testConfig.database.tunnel.local.host,
+    port: testConfig.database.tunnel.local.port,
+    username: testConfig.database.role.crud.username,
+    password: testConfig.database.role.crud.password,
+    database: testConfig.database.target.database,
+  });
+};