declapract-typescript-ehmpathy 0.49.10 → 0.49.12

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.config.ts

@@ -0,0 +1,7 @@
+/**
+ * @jest-config-loader esbuild-register
+ */
+import config from './jest.unit.config';
+
+// eslint-disable-next-line import/no-default-export
+export default config;

package/dist/practices/{tests → 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

@@ -0,0 +1,60 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import util from 'node:util';
+
+import { jest } from '@jest/globals';
+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
+
+// set console.log to not truncate nested objects
+util.inspect.defaultOptions.depth = 5;
+
+/**
+ * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
+ */
+if (!existsSync(join(process.cwd(), 'package.json')))
+  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
+ *
+ * usecases
+ * - prevent polluting prod state with test data
+ * - prevent executing financially impacting mutations
+ */
+if (
+  (process.env.NODE_ENV !== 'test' ||
+    (process.env.CONFIG && process.env.CONFIG !== 'test')) &&
+  process.env.I_KNOW_THE_RISKS !== 'true'
+)
+  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 = 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.
+ */
+useKeyrack({ env: 'test' });
+
+/**
+ * .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).
+ */
+useWakeOfTestdb();

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 → 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 → 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

@@ -0,0 +1,41 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+
+import type { FileContentsFunction } from 'declapract';
+import { FileCheckType } from 'declapract';
+
+import { readFile } from '../../../utils/readFile';
+
+/**
+ * .what = declare the jest unit-env file, with the config mock block included only when the
+ *         `config` practice is in play for the project.
+ * .why  = the mock stubs `getConfig` to return plaintext test config; a project WITHOUT the
+ *         `config` practice has no such module to mock, so the stub would reference a file that is
+ *         absent. a branch on `context.projectPractices` lets one practice serve both.
+ */
+export const contents: FileContentsFunction = async (context) => {
+  // grab the superset of best practices content
+  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')
+    ? contentsSuperset
+    : contentsSuperset.replace(
+        `// mock that getConfig just returns plaintext test env config in unit tests
+jest.mock('./src/utils/config/getConfig', () => ({
+  getConfig: jest.fn().mockImplementation(() => require('./config/test.json')),
+}));
+
+`,
+        '',
+      );
+
+  // return the narrowed contents
+  return contents;
+};
+
+/**
+ * check that they're contained in the file
+ */
+export const check: FileCheckType = FileCheckType.CONTAINS;

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

@@ -0,0 +1,6 @@
+{
+  "devDependencies": {
+    "@swc/core": "@declapract{check.minVersion('1.15.3')}",
+    "@swc/jest": "@declapract{check.minVersion('0.2.39')}"
+  }
+}

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

@@ -0,0 +1,10 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = the node half of the tests triad: the `@swc/jest` transform deps that the
+ *         node jest configs use.
+ * .why  = node unit/integration/acceptance jest configs transform via `@swc/jest`
+ *         (fast, node-target). the expo half transforms via jest-expo/babel instead,
+ *         so these deps are node-only. CONTAINS, so a repo may add more.
+ */
+export const check = FileCheckType.CONTAINS;

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 });
+};