declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -1,16 +1,193 @@
-import { FileCheckType } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+
+import { asPackageJSON } from '../../../utils/asPackageJSON';
 
 /**
- * .what = the expo half of the tests triad: the jest-expo transform stack that
- *         replaces node's `@swc/jest`.
- * .why  = an expo app's tests must transform react-native + expo ESM through
- *         babel-preset-expo (metro's transform), which jest-expo wires up. these deps
- *         track the installed expo SDK major (jest-expo 54 pairs with expo 54), so the
- *         floors are minima, not pins — a repo on a newer SDK bumps them.
- *
- * .caveat = these versions are SDK-coupled and un-validatable without a live expo repo;
- *           the emit is proven at the declapract-emit bar (the integration test), the
- *           live jest-expo run is proven against a real expo repo per the wisher's
- *           accepted validation bar for this fork.
+ * .what = the expo half of the tests triad: the jest-expo transform stack that replaces
+ *         node's `@swc/jest`. this check GATES the SDK-coupled majors on the repo's OWN
+ *         expo + react majors, rather than floor them at a fixed baseline.
+ * .why  = jest-expo's preset pokes react internals of the SDK it targets. a fixed
+ *         `minVersion('54.0.0')` floor forces jest-expo 54 (a react-19-era preset) onto an
+ *         expo-51 / react-18 repo, and every unit suite throws
+ *         `TypeError: Object.defineProperty called on non-object` at jest-expo's preset setup
+ *         (#584 / defect D1). the two crashing deps each track a major 1:1:
+ *           - jest-expo major  == expo major  (jest-expo 54 pairs with expo 54)
+ *           - react-test-renderer major == react major (rtr ships lockstep with react)
+ *         so the gate reads the repo's OWN expo + react majors and requires a match — which
+ *         holds jest-expo at 51 on an expo-51 repo and at 54 on an expo-54 repo, with no
+ *         version table to rot as new SDKs ship.
+ * .note = @babel/core + babel-preset-expo + isomorphic-fetch stay MINIMA (not the crash; each a
+ *         plain floor the pre-gate template already declared). babel-preset-expo also tracks the
+ *         SDK, but backward-compatibly; its floor is left as a residual — see .deliver/584.md.
+ * .note = a repo with no `expo` dep is not an expo repo in a gate-able state; the check passes
+ *         (returns) rather than flags, so a non-expo package.json is never falsely reddened.
  */
-export const check = FileCheckType.CONTAINS;
+
+const BABEL_CORE_MIN = { major: 7, minor: 24, patch: 0 };
+const BABEL_PRESET_EXPO_MIN = { major: 12, minor: 0, patch: 0 };
+const ISOMORPHIC_FETCH_MIN = { major: 3, minor: 0, patch: 0 };
+
+interface SemverTriple {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** parse the leading `major.minor.patch` out of a semver range (`^54.0.0`, `~19.1.2`, `>=3.0.0`). */
+const parseVersionTriple = (range: string | undefined): SemverTriple | null => {
+  if (!range) return null;
+  const match = range.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+};
+
+const majorOf = (range: string | undefined): number | null =>
+  parseVersionTriple(range)?.major ?? null;
+
+const meetsMinimum = (
+  range: string | undefined,
+  min: SemverTriple,
+): boolean => {
+  const found = parseVersionTriple(range);
+  if (!found) return false;
+  if (found.major !== min.major) return found.major > min.major;
+  if (found.minor !== min.minor) return found.minor > min.minor;
+  return found.patch >= min.patch;
+};
+
+/** the subset of a package.json this declaration reads + rewrites (dep maps), typed rather than `any`. */
+interface PackageJSON {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+const getAllDeps = (packageJSON: PackageJSON): Record<string, string> => ({
+  ...(packageJSON.dependencies ?? {}),
+  ...(packageJSON.devDependencies ?? {}),
+});
+
+export const check: FileCheckFunction = (contents) => {
+  // no file → no gate to enforce; a best-practice check passes (returns) when clean
+  if (!contents) return;
+
+  const packageJSON: PackageJSON = asPackageJSON(
+    { contents },
+    {
+      practice: 'tests-expo',
+    },
+  );
+  const deps = getAllDeps(packageJSON);
+
+  // a repo with no `expo` dep is not an expo repo in a gate-able state — do not flag it
+  const expoMajor = majorOf(deps.expo);
+  if (expoMajor === null) return;
+
+  // jest-expo major must MATCH the repo's expo major (jest-expo tracks the SDK 1:1)
+  const jestExpoMajor = majorOf(deps['jest-expo']);
+  if (jestExpoMajor !== expoMajor)
+    throw new ConstraintError(
+      `jest-expo major (${jestExpoMajor}) must match the repo's expo major (${expoMajor}) — run \`declapract apply\` to pin jest-expo to ^${expoMajor}.0.0`,
+      { found: jestExpoMajor, required: expoMajor, dep: 'jest-expo' },
+    );
+
+  // react-test-renderer major must MATCH the repo's react major (rtr ships lockstep with react)
+  const reactMajor = majorOf(deps.react);
+  if (reactMajor !== null) {
+    const rtrMajor = majorOf(deps['react-test-renderer']);
+    if (rtrMajor !== reactMajor)
+      throw new ConstraintError(
+        `react-test-renderer major (${rtrMajor}) must match the repo's react major (${reactMajor}) — run \`declapract apply\` to pin react-test-renderer to ^${reactMajor}.0.0`,
+        { found: rtrMajor, required: reactMajor, dep: 'react-test-renderer' },
+      );
+  }
+
+  // @babel/core + babel-preset-expo + isomorphic-fetch stay MINIMA (not the crash; a plain
+  // floor, exactly as the pre-gate template declared each of the three)
+  if (!meetsMinimum(deps['@babel/core'], BABEL_CORE_MIN))
+    throw new ConstraintError(
+      '@babel/core must be >= 7.24.0 — run `declapract apply` to raise it',
+      {
+        found: deps['@babel/core'] ?? null,
+        required: '7.24.0',
+        dep: '@babel/core',
+      },
+    );
+  if (!meetsMinimum(deps['babel-preset-expo'], BABEL_PRESET_EXPO_MIN))
+    throw new ConstraintError(
+      'babel-preset-expo must be >= 12.0.0 — run `declapract apply` to raise it',
+      {
+        found: deps['babel-preset-expo'] ?? null,
+        required: '12.0.0',
+        dep: 'babel-preset-expo',
+      },
+    );
+  if (!meetsMinimum(deps['isomorphic-fetch'], ISOMORPHIC_FETCH_MIN))
+    throw new ConstraintError(
+      'isomorphic-fetch must be >= 3.0.0 — run `declapract apply` to raise it',
+      {
+        found: deps['isomorphic-fetch'] ?? null,
+        required: '3.0.0',
+        dep: 'isomorphic-fetch',
+      },
+    );
+
+  // all gates satisfied
+  return;
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  const packageJSON: PackageJSON = asPackageJSON(
+    { contents },
+    {
+      practice: 'tests-expo',
+    },
+  );
+  const deps = getAllDeps(packageJSON);
+  const expoMajor = majorOf(deps.expo);
+
+  // no expo dep → not a gate-able expo repo; leave untouched
+  if (expoMajor === null) return { contents };
+
+  const devDependencies = { ...(packageJSON.devDependencies ?? {}) };
+  const dependencies = { ...(packageJSON.dependencies ?? {}) };
+
+  // jest-expo + react-test-renderer are test-time deps that belong in devDependencies ALONE. pin
+  // them there AND delete any copy under `dependencies` — else the merged getAllDeps check (dev
+  // wins) reads green while npm installs ONE version and a stale `dependencies` copy at a conflicting
+  // major can win at install time (the two-section version conflict r006.b1 forbids). the sibling
+  // dep declarations (logs/leveled-term, rhachet/prod-deps) strip from both sections for the same reason.
+  devDependencies['jest-expo'] = `^${expoMajor}.0.0`;
+  delete dependencies['jest-expo'];
+
+  // pin react-test-renderer to the repo's react major, when a react dep is present
+  const reactMajor = majorOf(deps.react);
+  if (reactMajor !== null) {
+    devDependencies['react-test-renderer'] = `^${reactMajor}.0.0`;
+    delete dependencies['react-test-renderer'];
+  }
+
+  // raise @babel/core + babel-preset-expo + isomorphic-fetch to their minima when below
+  if (!meetsMinimum(deps['@babel/core'], BABEL_CORE_MIN))
+    devDependencies['@babel/core'] = '^7.24.0';
+  if (!meetsMinimum(deps['babel-preset-expo'], BABEL_PRESET_EXPO_MIN))
+    devDependencies['babel-preset-expo'] = '^12.0.0';
+  if (!meetsMinimum(deps['isomorphic-fetch'], ISOMORPHIC_FETCH_MIN))
+    devDependencies['isomorphic-fetch'] = '^3.0.0';
+
+  // preserve each section's presence: rewrite `dependencies` ONLY when the manifest already declared
+  // one (so a repo with no prod deps never gains an empty `dependencies: {}` it did not have).
+  const result: PackageJSON = { ...packageJSON, devDependencies };
+  if (packageJSON.dependencies) result.dependencies = dependencies;
+
+  return {
+    contents: JSON.stringify(result, null, 2),
+  };
+};

package/dist/practices/tests-expo/package.json.declapract.integration.test.ts

@@ -0,0 +1,94 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation)
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the tests-expo jest-expo/rtr SDK-major gate (#584 / defect D1).
+ * .why  = the unit test proves the check/fix in isolation; only the real executeApply pipeline
+ *         proves declapract WIRES the declaration to `package.json` and reaches a fixed point on
+ *         a re-run. the crash this gate prevents is a react-19-era jest-expo (54) held onto an
+ *         expo-51 / react-18 repo — every unit suite throws at jest-expo's preset setup — so the
+ *         gate must hold jest-expo at the repo's OWN expo major (51), never bump it to 54.
+ * .note = scoped `practice: 'tests-expo'` — the declaration reads only `contents`, never
+ *         `context.projectPractices`, so a practice scope is safe (no usecase-aware branch goes
+ *         dark) and isolates the apply to tests-expo's package.json declaration alone.
+ */
+describe('tests-expo package.json — pipeline gate on the repo expo/react major', () => {
+  given('[case1] an expo-51 / react-18 repo seeded with a react-19-era jest-expo 54 the gate aligns down to the expo major (51)', () => {
+    const tempDir = genTempDir({
+      slug: 'tests-expo-major-gate',
+      clone: './src/.test/assets/expo-migration/repo-app-protools-shaped',
+      symlink: [
+        { at: 'declarations', to: './src/.test/assets/expo-migration/declarations' },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const pkgPath = () => path.join(tempDir, 'package.json');
+    const readPkg = () => fs.readFile(pkgPath(), 'utf-8');
+
+    const state = useBeforeAll(async () => {
+      // seed the crash shape: a react-19-era jest-expo/rtr on an expo-51 / react-18 repo
+      const seeded = {
+        ...JSON.parse(await readPkg()),
+        devDependencies: {
+          ...JSON.parse(await readPkg()).devDependencies,
+          expo: '~51.0.0',
+          react: '18.2.0',
+          'jest-expo': '^54.0.0',
+          'react-test-renderer': '^19.0.0',
+          'babel-preset-expo': '^12.0.0',
+          'isomorphic-fetch': '^3.0.0',
+        },
+      };
+      await fs.writeFile(pkgPath(), `${JSON.stringify(seeded, null, 2)}\n`);
+      const pkgBefore = await readPkg();
+
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter1 = await readPkg();
+      await executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'tests-expo',
+        file: 'package.json',
+      });
+      const pkgAfter2 = await readPkg();
+
+      return { pkgBefore, pkgAfter1, pkgAfter2 };
+    }, 170_000);
+
+    when('[t0] the tests-expo gate is applied to the seeded package.json', () => {
+      then('jest-expo is held at the repo expo major (51), not bumped to 54', () => {
+        expect(JSON.parse(state.pkgBefore).devDependencies['jest-expo']).toEqual(
+          '^54.0.0',
+        );
+        expect(JSON.parse(state.pkgAfter1).devDependencies['jest-expo']).toEqual(
+          '^51.0.0',
+        );
+      });
+
+      then('react-test-renderer is held at the repo react major (18), not 19', () => {
+        expect(
+          JSON.parse(state.pkgAfter1).devDependencies['react-test-renderer'],
+        ).toEqual('^18.0.0');
+      });
+
+      then('before + after match snapshot', () => {
+        expect(state.pkgBefore).toMatchSnapshot('package.json — before');
+        expect(state.pkgAfter1).toMatchSnapshot('package.json — after gate');
+      });
+
+      then('a second apply is a fixed point (the gate holds)', () => {
+        expect(state.pkgAfter2).toEqual(state.pkgAfter1);
+      });
+    });
+  });
+});

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

@@ -0,0 +1,6 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`the useWakeOfLivedb decide-gate runs its real branches (executed, no live infra) given: the wake command fails when: it fails with a child-process shape (a non-zero exit) then: the wake-failure warn matches snapshot: useWakeOfLivedb wake-failure warn 1`] = `
+"useWakeOfLivedb: 'rhx use.rds.capacity --env prep' failed (non-fatal): {"status":1}
+"
+`;

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

@@ -32,6 +32,14 @@ const config: Config = {
   testMatch: ['**/*.acceptance.test.ts', '!**/.agent/.cache/**', '!**/.yalc/**'],
   setupFilesAfterEnv: ['./jest.acceptance.env.ts'],
 
+  // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
+  // one without the other stamps and never reclaims. the globalSetup COMPOSES the livedb wake
+  // (resume the shared aurora-serverless cluster before the first query) with autoprune's setup,
+  // and forwards globalConfig to it — a bare 'test-fns/autoprune.setup.jest' would leave the db
+  // un-woken.
+  globalSetup: './jest.acceptance.prepare.ts',
+  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.acceptance.env.ts

@@ -1,9 +1,11 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import util from 'node:util';
 
 import { jest } from '@jest/globals';
-import { keyrack } from 'rhachet/keyrack';
+import { ConstraintError } from 'helpful-errors';
+
+import { useKeyrack } from './src/.test/useKeyrack';
 
 jest.setTimeout(90000); // we're calling downstream apis
 
@@ -15,32 +17,20 @@ 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?');
-
-/**
- * .what = verify that the env has sufficient auth to run the tests if aws is used; otherwise, fail fast
- * .why =
- *   - prevent time wasted waiting on tests to fail due to lack of credentials
- *   - prevent time wasted debugging tests which are failing due to hard-to-read missed credential errors
- */
-const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
-const requiresAwsAuth =
-  existsSync(declapractUsePath) &&
-  readFileSync(declapractUsePath, 'utf8').includes('awsAccountId');
-if (
-  requiresAwsAuth &&
-  !(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID)
-)
-  throw new Error(
-    'no aws credentials present. please authenticate with aws to run acceptance tests',
+  throw new ConstraintError(
+    'no package.json found in cwd — run the acceptance suite from the git root',
+    { cwd: process.cwd() },
   );
 
 /**
- * .what = source credentials from keyrack for test env
+ * .what = source credentials from keyrack for the target tier and export them for the aws-sdk-v2
+ *         lambda caller, in one call.
  * .why =
- *   - auto-inject keys into process.env
- *   - fail fast with helpful error if keyrack locked or keys absent
+ *   - a cloud acceptance run targets a deployed tier (e.g. prep), derived from ACCESS; default to the
+ *     lowest-privilege `test` when unset, so a PR / local in-process run stays on test creds.
+ *   - useKeyrack is the org convention: it sources keyrack (sets AWS_PROFILE), sets ACCESS, and — for
+ *     an aws consumer — exports the sso profile's static creds so aws-sdk-v2 auths against the target
+ *     (keyrack.source alone sets only AWS_PROFILE, which v2 cannot use). #586.
+ *   - `strict` fails fast with a helpful error if keyrack is locked or a key is absent.
  */
-const keyrackYmlPath = join(process.cwd(), '.agent/keyrack.yml');
-if (existsSync(keyrackYmlPath))
-  keyrack.source({ env: 'test', owner: 'ehmpath', mode: 'strict' });
+useKeyrack({ env: (process.env.ACCESS ?? 'test') as 'test' | 'prep' | 'prod', mode: 'strict' });

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

@@ -0,0 +1,36 @@
+import autopruneSetup from 'test-fns/autoprune.setup.jest';
+
+import { useWakeOfLivedb } from './src/.test/useWakeOfLivedb';
+
+/**
+ * .what = jest globalSetup for the acceptance 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 acceptance suites invoke deployed lambdas that proxy to peers which query the shared
+ *     cluster; a paused cluster cold-starts past the timeout and flakes the quote suites. wake
+ *     it once here (not per-file — env setup runs per worker), so the first real query lands warm.
+ *   - 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.integration.config.ts

@@ -32,6 +32,14 @@ const config: Config = {
   testMatch: ['**/*.integration.test.ts', '!**/.agent/.cache/**', '!**/.yalc/**'],
   setupFilesAfterEnv: ['./jest.integration.env.ts'],
 
+  // reclaim every temp dir genTempDir made this run (test-fns autoprune). jest needs BOTH keys;
+  // one without the other stamps and never reclaims. the globalSetup COMPOSES the livedb wake
+  // (resume the shared aurora-serverless cluster before the first query) with autoprune's setup,
+  // and forwards globalConfig to it — a bare 'test-fns/autoprune.setup.jest' would leave the db
+  // un-woken.
+  globalSetup: './jest.integration.prepare.ts',
+  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.integration.env.db.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = verify the local testdb is reachable, via a `SELECT 1` preflight, before a suite runs.
+ * .why  = this preflight runs at jest-setup load, so its error is the first output a surfer reads
+ *         when the testdb is unreachable. the prior form redirected psql's stderr to `/dev/null` and
+ *         threw one hardcoded cause ("did you forget to start:testdb?"), so EVERY cause -- an absent
+ *         psql binary, a bad password, an unapplied schema, a 3s timeout -- collapsed into a message
+ *         that named only the likeliest and pointed away from the rest (a swallowed error). this
+ *         surfaces psql's own words instead. it is split out of `jest.integration.env.ts` (a
+ *         jest-setup module whose logic cannot be unit-tested in place) so the failure path is a pure
+ *         fn with the `exec` boundary injected, and both the real-stderr path and the empty-stderr
+ *         path are clamped + snapped.
+ * .note = PGPASSWORD rides in `env`, never in the command args. node puts the failed command verbatim
+ *         onto the thrown error's message, so a password passed as an arg would reach any log that
+ *         prints that error. the args are an argv array (no shell), so a config value with shell
+ *         metacharacters cannot be interpreted either (no injection).
+ * .note = a failed preflight is CALLER-must-fix (a local testdb the human starts), so it throws a
+ *         ConstraintError (exit 2) that NAMES the fix and PRESERVES psql's stderr on the chain -- a
+ *         consumer can tell "not started" from "bad password" from "psql absent"
+ *         (a caller-must-fix ConstraintError, exit 2).
+ */
+export const probeTestDb = (
+  input: {
+    host: string;
+    port: number | string;
+    username: string;
+    password: string;
+    database: string;
+  },
+  context: { exec?: typeof execFileSync } = {},
+): void => {
+  const exec = context.exec ?? execFileSync;
+
+  try {
+    exec(
+      'psql',
+      [
+        '-h',
+        String(input.host),
+        '-p',
+        String(input.port),
+        '-U',
+        input.username,
+        '-d',
+        input.database,
+        '-c',
+        'SELECT 1',
+      ],
+      {
+        timeout: 3000,
+        // stdout ignored (the SELECT 1 result is noise); stderr piped so psql's words reach the human
+        stdio: ['ignore', 'ignore', 'pipe'],
+        env: { ...process.env, PGPASSWORD: input.password },
+      },
+    );
+  } catch (error) {
+    // surface what psql actually said; a bare catch collapses every cause into one guess
+    const said =
+      error && typeof error === 'object' && 'stderr' in error
+        ? String((error as { stderr?: Buffer }).stderr ?? '').trim()
+        : '';
+    // psql SPOKE => it reached the server, so the container is UP and the fault is auth/schema, NOT
+    // a down container -- `start:testdb` is already what the surfer ran to get here, so it is the
+    // wrong first move for a bad password / unapplied schema. name the credential + schema check,
+    // and keep the start command only as the container-down fallback. the SILENT decline (no stderr:
+    // absent psql / timeout) is the one cause that actually points at a down container.
+    const fix = said
+      ? [
+          'fix: psql reached the server, so the container is UP -- the fault is likely auth or schema:',
+          '  - check the crud user + password in config/test.json match what the testdb was seeded with',
+          "  - check this service's schema was applied to the testdb",
+          '  - only if the container is in fact down, run `npm run start:testdb`',
+        ].join('\n')
+      : 'fix: run `npm run start:testdb`';
+    throw new ConstraintError(
+      [
+        `cant connect to the testdb at ${input.host}:${input.port}`,
+        '',
+        'psql said:',
+        `  ${said || '(no stderr -- psql may be absent from PATH, or the call timed out)'}`,
+        '',
+        fix,
+      ].join('\n'),
+      { cause: error },
+    );
+  }
+};

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

@@ -1,10 +1,12 @@
-import { execSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import util from 'node:util';
 
 import { jest } from '@jest/globals';
-import { keyrack } from 'rhachet/keyrack';
+import { ConstraintError } from 'helpful-errors';
+
+import { useKeyrack } from './src/.test/useKeyrack';
+import { useWakeOfTestdb } from './src/.test/useWakeOfTestdb';
 
 jest.setTimeout(90000); // since we're calling downstream apis
 
@@ -16,7 +18,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 integration suite from the git root',
+    { cwd: process.cwd() },
+  );
 
 /**
  * sanity check that unit tests are only run the 'test' environment
@@ -30,79 +35,26 @@ if (
     (process.env.CONFIG && process.env.CONFIG !== 'test')) &&
   process.env.I_KNOW_THE_RISKS !== 'true'
 )
-  throw new Error(`integration.test config must be 'test'`);
-
-/**
- * .what = source aws profile from keyrack if available
- * .why = keyrack manages which profile to use per environment
- */
-const keyrackYmlPath = join(process.cwd(), '.agent/keyrack.yml');
-if (existsSync(keyrackYmlPath) && !process.env.CI)
-  keyrack.source({ env: 'test', owner: 'ehmpath', mode: 'lenient' });
+  throw new ConstraintError(
+    `integration.test config must be 'test' — set NODE_ENV=test and CONFIG=test (or I_KNOW_THE_RISKS=true to override)`,
+    { nodeEnv: process.env.NODE_ENV ?? null, config: process.env.CONFIG ?? null },
+  );
 
 /**
- * .what = export aws credentials from sso profile if aws is required
- * .why = aws sdk v2 doesn't handle sso_session profiles natively
+ * .what = source credentials from keyrack for the test tier and export them for the aws-sdk-v2
+ *         lambda caller, in one call.
+ * .why = useKeyrack is the org convention: it sources keyrack (sets AWS_PROFILE) and — for an aws
+ *        consumer — exports the sso profile's static creds so aws-sdk-v2 auths against the target
+ *        (aws-sdk v2 cannot use an sso profile, and prefers AWS_PROFILE over static creds when both
+ *        are set, so the shared guard removes AWS_PROFILE after the splice). #586.
  */
-const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
-const declapractUseContent = existsSync(declapractUsePath)
-  ? readFileSync(declapractUsePath, 'utf8')
-  : '';
-const requiresAwsAuth = declapractUseContent.includes('awsAccountId');
-if (requiresAwsAuth && !process.env.AWS_ACCESS_KEY_ID && !process.env.CI) {
-  const awsSsoProfile = process.env.AWS_PROFILE;
-  if (!awsSsoProfile)
-    throw new Error(
-      'AWS_PROFILE not set. keyrack.source() should have set it.',
-    );
-  try {
-    const credOutput = execSync(
-      `aws configure export-credentials --profile ${awsSsoProfile} --format env`,
-      { encoding: 'utf8', timeout: 10000 },
-    );
-    // parse and set env vars from output like "export AWS_ACCESS_KEY_ID=..."
-    credOutput.split('\n').forEach((line) => {
-      const match = line.match(/^export\s+(\w+)=(.*)$/);
-      if (match) process.env[match[1]!] = match[2]!;
-    });
-  } catch {
-    throw new Error(
-      `failed to export aws credentials from sso profile '${awsSsoProfile}'. run: aws sso login --profile ${awsSsoProfile}`,
-    );
-  }
-}
+useKeyrack({ env: 'test' });
 
 /**
- * .what = verify that the testdb has been provisioned if a databaseUserName is declared
- * .why =
- *   - prevent time wasted waiting on tests to fail due to missing testdb
- *   - prevent confusing "password authentication failed" errors when testdb isn't running or was provisioned for a different repo
+ * .what = preflight the LOCAL testdb when this service declares its own db (databaseUserName).
+ * .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; useWakeOfTestdb fails loud and names
+ *        the fix. it is the LOCAL own-db half; the shared prep cluster its peers query is woken by
+ *        useWakeOfLivedb in globalSetup (define.invariant.test-and-prep-reach-prep-peers).
  */
-const requiresTestDb = declapractUseContent.includes('databaseUserName');
-if (requiresTestDb) {
-  const testConfigPath = join(process.cwd(), 'config', 'test.json');
-  if (!existsSync(testConfigPath))
-    throw new Error(
-      'config/test.json not found but serviceUser is declared in declapract.use.yml',
-    );
-  const testConfig = JSON.parse(readFileSync(testConfigPath, 'utf8'));
-  if (
-    !testConfig.database?.tunnel?.local ||
-    !testConfig.database?.role?.crud ||
-    !testConfig.database?.target?.database
-  )
-    throw new Error(
-      'config/test.json database.tunnel.local, database?.role?.crud, or database?.target?.database not found but expected',
-    );
-  try {
-    execSync(
-      `PGPASSWORD="${testConfig.database.role.crud.password}" psql -h ${testConfig.database.tunnel.local.host} -p ${testConfig.database.tunnel.local.port} -U ${testConfig.database.role.crud.username} -d ${testConfig.database.target.database} -c "SELECT 1" > /dev/null 2>&1`,
-      { timeout: 3000 },
-    );
-  } catch (error) {
-    throw new Error(
-      `did you forget to \`npm run start:testdb\`? cant connect to database`,
-      { cause: error },
-    );
-  }
-}
+useWakeOfTestdb();