declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/practices/persist-with-rds/provision-testdb-access.declapract.integration.test.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps #563: the shipped provision:testdb chain sets ACCESS=test on every inner
+ *         provision:schema:* call, so a freshly-stamped repo can derive access and provision its
+ *         local testdb without a hand-edit.
+ * .why  = each schema call invokes sql-schema-control → getConfig() → getEnvironment.static(); with
+ *         no ACCESS in a local shell (no aws account alias / NODE_ENV that fits), every access parser
+ *         fails and it throws `could not derive access`. the local testdb always provisions the
+ *         `test` access, so ACCESS=test is a constant here, not the cicd `${{ inputs.access }}`
+ *         interpolation the live-db path uses.
+ * .teeth = drop an `ACCESS=test` from any inner schema call in best-practice/package.json and the
+ *          "no bare schema call" assertion reddens (a bare `&& npm run provision:schema:` reappears).
+ * .note = the subject is the shipped TEMPLATE (best-practice/package.json, a CONTAINS check), read
+ *         from __dirname. this file sits at the practice ROOT, so declapract never emits it.
+ */
+describe('persist-with-rds provision:testdb access', () => {
+  given('the shipped best-practice package.json', () => {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, 'best-practice/package.json'), 'utf8'),
+    );
+    const provisionTestdb: string = pkg.scripts['provision:testdb'];
+
+    when('the provision:testdb chain is read', () => {
+      then('each inner schema call carries ACCESS=test', () => {
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:plan',
+        );
+        expect(provisionTestdb).toContain(
+          'ACCESS=test npm run provision:schema:apply',
+        );
+      });
+
+      then('no inner schema call runs without ACCESS (would throw could-not-derive)', () => {
+        // a bare `&& npm run provision:schema:` (not preceded by ACCESS=test) throws
+        // `could not derive access` in a local shell — the #563 defect
+        expect(provisionTestdb).not.toMatch(/&&\s*npm run provision:schema:/);
+      });
+
+      then('the emitted provision:testdb chain matches snapshot', () => {
+        // snapshot the shipped chain contract itself, so a reword that keeps the
+        // ACCESS=test tokens green (a re-ordered &&, a dropped command) reddens a vibecheck
+        expect(provisionTestdb).toMatchSnapshot('provision:testdb chain');
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/ssm-param-names.declapract.integration.test.ts

@@ -0,0 +1,154 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+import { getModuleExportsFromTsSource } from '../../utils/getModuleExportsFromTsSource';
+
+/**
+ * .what = clamps that the provision wish declares each db credential at the exact ssm name that
+ *         config's bare `$.at(aws::param)` placeholder derives: `/{org}/{project}/{config}/{keyPath}`.
+ * .why  = sdk-config >= 0.3.0 derives a bare placeholder's ssm name as
+ *         `/${org}/${repo}/${choice}/${keyPath}`, where `choice` is the CONFIG slug. config/*.json
+ *         ships the bare form for all three passwords, so the wish must declare those same three
+ *         names, or the provision manages params the app never reads while the app reads params no
+ *         wish declares (#637). this supersedes the #591 clamp, which pinned the slash cicd form
+ *         with no config segment; the plan role's iam pin now allows the derived form (seed S4).
+ * .teeth = restore any dotted, config-segment-free, or access-keyed name in resources.parameters.ts,
+ *          or drop a bare placeholder from config/prep.json, and the names-equal-config case reddens.
+ *          read the config segment from `access` in place of `config` and the ACCESS=prep
+ *          CONFIG=prod case reddens.
+ * .note = INTEGRATION by rule.forbid.unit.remote-boundaries: it reads template files off disk. the
+ *         template imports declastruct-aws + sdk-environment, which this repo does not install, so
+ *         it is transpiled and run against a require stub — the clamp reads what the real source
+ *         returns, never a text fragment.
+ */
+
+const paramsPath = join(
+  __dirname,
+  'best-practice/provision/aws/resources.parameters.ts',
+);
+const configPath = (env: string) =>
+  join(__dirname, `best-practice/config/${env}.json`);
+
+const ORG = '@declapract{variable.organizationName}';
+const PROJECT = '@declapract{variable.projectName}';
+
+/**
+ * .what = transpile resources.parameters.ts and run getAllParameters under a stubbed environment
+ * .why  = the wish reads `getEnvironment.static()` at module load; a stub per (access, config) pair
+ *         proves which axis names the config segment and which tags it
+ */
+const runGetAllParameters = (input: {
+  src: string;
+  access: string;
+  config: string;
+}): { name: string; tags: Record<string, string> }[] => {
+  const requireStub = (id: string): unknown => {
+    if (id === 'declastruct-aws')
+      return { DeclaredAwsSsmParameterSecure: { as: (x: unknown) => x } };
+    if (id === 'sdk-environment')
+      return {
+        getEnvironment: {
+          static: () => ({ access: input.access, config: input.config }),
+        },
+      };
+    throw new Error(`unexpected require in template: ${id}`);
+  };
+  const { getAllParameters } = getModuleExportsFromTsSource<{
+    getAllParameters: (input: {
+      choice: string | null;
+    }) => { name: string; tags: Record<string, string> }[];
+  }>({ source: input.src, requireStub });
+  return getAllParameters!({ choice: null });
+};
+
+/**
+ * .what = list the dotted key paths whose value is the bare `$.at(aws::param)` placeholder
+ * .why  = each such leaf is a param sdk-config derives a name for, so the wish owes a declaration
+ */
+const getAllBareParamKeyPaths = (input: {
+  value: unknown;
+  prefix: string[];
+}): string[] => {
+  if (input.value === '$.at(aws::param)') return [input.prefix.join('.')];
+  if (!input.value || typeof input.value !== 'object') return [];
+  return Object.entries(input.value as Record<string, unknown>).flatMap(
+    ([key, child]) =>
+      getAllBareParamKeyPaths({ value: child, prefix: [...input.prefix, key] }),
+  );
+};
+
+describe('persist-with-rds ssm param names are the sdk-config derived names (#637)', () => {
+  const scene = useBeforeAll(() => ({
+    src: readFileSync(paramsPath, 'utf8'),
+    prep: JSON.parse(readFileSync(configPath('prep'), 'utf8')),
+    prod: JSON.parse(readFileSync(configPath('prod'), 'utf8')),
+  }));
+
+  given('[case1] the wish run with ACCESS=prep CONFIG=prep', () => {
+    when('[t0] getAllParameters is called with no choice override', () => {
+      const run = useBeforeAll(() => ({
+        params: runGetAllParameters({ src: scene.src, access: 'prep', config: 'prep' }),
+      }));
+
+      then('it declares the three derived names under /{org}/{project}/prep/', () => {
+        expect(run.params.map((p) => p.name)).toEqual([
+          `/${ORG}/${PROJECT}/prep/database.role.crud.password`,
+          `/${ORG}/${PROJECT}/prep/database.role.cicd.for-plan.password`,
+          `/${ORG}/${PROJECT}/prep/database.role.cicd.for-apply.password`,
+        ]);
+      });
+
+      then('the declared names equal the names config/prep.json derives', () => {
+        const derived = getAllBareParamKeyPaths({ value: scene.prep, prefix: [] })
+          .map((keyPath) => `/${ORG}/${PROJECT}/prep/${keyPath}`)
+          .sort();
+        expect(run.params.map((p) => p.name).sort()).toEqual(derived);
+      });
+
+      then('no name carries the legacy `dev` slug or a dotted org.project namespace', () => {
+        for (const { name } of run.params) {
+          expect(name).not.toContain('/dev/');
+          expect(name).not.toContain(`${ORG}.${PROJECT}`);
+        }
+      });
+
+      then('the declared names match snapshot', () => {
+        expect(run.params.map((p) => p.name)).toMatchSnapshot();
+      });
+    });
+  });
+
+  given('[case2] the wish run with ACCESS=prod CONFIG=prod', () => {
+    when('[t0] getAllParameters is called', () => {
+      then('the declared names equal the names config/prod.json derives', () => {
+        const params = runGetAllParameters({
+          src: scene.src,
+          access: 'prod',
+          config: 'prod',
+        });
+        const derived = getAllBareParamKeyPaths({ value: scene.prod, prefix: [] })
+          .map((keyPath) => `/${ORG}/${PROJECT}/prod/${keyPath}`)
+          .sort();
+        expect(params.map((p) => p.name).sort()).toEqual(derived);
+      });
+    });
+  });
+
+  given('[case3] the wish run with ACCESS=prep CONFIG=prod (a legal pair)', () => {
+    when('[t0] getAllParameters is called', () => {
+      const run = useBeforeAll(() => ({
+        params: runGetAllParameters({ src: scene.src, access: 'prep', config: 'prod' }),
+      }));
+
+      then('the config slug names the config segment, so the names read prod', () => {
+        expect(run.params).toHaveLength(3);
+        for (const { name } of run.params) expect(name).toContain(`/${PROJECT}/prod/`);
+      });
+
+      then('the access tags each param', () => {
+        for (const { tags } of run.params) expect(tags.environment).toEqual('prep');
+      });
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/testdb-per-worktree.declapract.integration.test.ts

@@ -0,0 +1,332 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, useBeforeAll } from 'test-fns';
+
+import { getTestdbIdentity } from './best-practice/src/.test/assets/database/getTestdbIdentity';
+import { getTestdbPort } from './best-practice/src/.test/assets/database/getTestdbPort';
+
+/**
+ * .what = proves each worktree of a repo gets a testdb of its own (#674): its own compose
+ *         project, container, and host port, while ci and a main checkout keep port 7821
+ * .why = two worktrees that share one testdb read and clobber each other's rows, and a
+ *        `start:testdb` in one stops the other's db mid-run
+ * .teeth = drop the worktree branch from getTestdbIdentity and case2 reddens; route a compose
+ *          command around compose.sh, or pin the compose port, and case5 reddens; read the port
+ *          straight off the config in a reader, or import a testdb test asset from a prod path,
+ *          and case5 reddens
+ * .note = getTestdbIdentity and getTestdbPort are test assets (`src/.test/assets/database/`): the
+ *         app never imports them, it reads the TESTDB_PORT the test harness declares
+ * .note = INTEGRATION by `rule.forbid.unit.remote-boundaries`: it runs git and bash in temp repos
+ */
+
+jest.setTimeout(5 * 60 * 1000);
+
+const BEST_PRACTICE_DIR = join(__dirname, 'best-practice');
+const REPO_NODE_MODULES = join(__dirname, '../../../node_modules');
+const PORT_DECLARED = 7821;
+const ENV_LOCAL = { ...process.env, CI: '' };
+
+/**
+ * .what = run git in a dir, with an author so a commit needs no global config
+ */
+const runGit = (input: { cwd: string; args: string[] }): string =>
+  execFileSync(
+    'git',
+    [
+      '-c',
+      'user.name=surfer',
+      '-c',
+      'user.email=surfer@example.com',
+      ...input.args,
+    ],
+    { cwd: input.cwd, encoding: 'utf8' },
+  );
+
+/**
+ * .what = a temp repo with one commit, plus two linked worktrees of it
+ */
+const genRepoWithWorktrees = (input: {
+  slug: string;
+  files: Record<string, string>;
+}): { main: string; worktreeA: string; worktreeB: string } => {
+  const root = genTempDir({ slug: input.slug });
+  const main = join(root, 'main');
+  mkdirSync(main, { recursive: true });
+  Object.entries(input.files).forEach(([path, source]) => {
+    mkdirSync(join(main, path, '..'), { recursive: true });
+    writeFileSync(join(main, path), source);
+  });
+  runGit({ cwd: main, args: ['init', '-q', '-b', 'main'] });
+  runGit({ cwd: main, args: ['add', '-A'] });
+  runGit({ cwd: main, args: ['commit', '-q', '--allow-empty', '-m', 'init'] });
+  const worktreeA = join(root, 'worktree-a');
+  const worktreeB = join(root, 'worktree-b');
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'a', worktreeA] });
+  runGit({ cwd: main, args: ['worktree', 'add', '-q', '-b', 'b', worktreeB] });
+  return { main, worktreeA, worktreeB };
+};
+
+describe('persist-with-rds testdb per worktree (#674)', () => {
+  given('[case1] a main checkout', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-main', files: {} }),
+    );
+
+    then('it keeps the declared port and no suffix, as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.main, env: ENV_LOCAL },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case2] two linked worktrees of one repo', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-linked',
+        files: {},
+      });
+      return {
+        a: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        aAgain: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: ENV_LOCAL },
+        ),
+        b: getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeB, env: ENV_LOCAL },
+        ),
+      };
+    });
+
+    then('each derives a suffix of its own', () => {
+      expect(scene.a.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.b.suffix).toMatch(/^-[0-9a-f]{6}$/);
+      expect(scene.a.suffix).not.toEqual(scene.b.suffix);
+    });
+
+    then('each binds a port of its own, never the declared one', () => {
+      [scene.a.port, scene.b.port].forEach((port) => {
+        expect(port).toBeGreaterThan(PORT_DECLARED);
+        expect(port).toBeLessThan(PORT_DECLARED + 1000);
+      });
+      expect(scene.a.port).not.toEqual(scene.b.port);
+    });
+
+    then('a worktree lands on the same identity every time', () => {
+      expect(scene.aAgain).toEqual(scene.a);
+    });
+  });
+
+  given('[case3] a linked worktree in ci', () => {
+    const repo = useBeforeAll(async () =>
+      genRepoWithWorktrees({ slug: 'testdb-per-worktree-ci', files: {} }),
+    );
+
+    then('it keeps the declared port, so ci behaves as before', () => {
+      expect(
+        getTestdbIdentity(
+          { portDeclared: PORT_DECLARED },
+          { cwd: repo.worktreeA, env: { ...process.env, CI: 'true' } },
+        ),
+      ).toEqual({ suffix: '', port: PORT_DECLARED });
+    });
+  });
+
+  given('[case4] a reader asks for its port', () => {
+    then('an access other than test keeps its declared port', () => {
+      expect(getTestdbPort({ access: 'prep', portDeclared: 5432 })).toEqual(
+        5432,
+      );
+    });
+
+    then('test access dials the identity this checkout derives', () => {
+      expect(
+        getTestdbPort({ access: 'test', portDeclared: PORT_DECLARED }),
+      ).toEqual(getTestdbIdentity({ portDeclared: PORT_DECLARED }).port);
+    });
+  });
+
+  given('[case5] the shipped templates', () => {
+    const read = (path: string) =>
+      readFileSync(join(BEST_PRACTICE_DIR, path), 'utf8');
+
+    then('the compose project, container, and port take the derived values', () => {
+      const compose = read('provision/docker/testdb/docker-compose.yml');
+      expect(compose).toContain(
+        'name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain(
+        'container_name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}',
+      );
+      expect(compose).toContain('- ${TESTDB_PORT:-7821}:5432');
+      expect(compose).not.toContain('- 7821:5432');
+    });
+
+    then('every compose command goes through compose.sh', () => {
+      const commands: string[] = Object.values(
+        JSON.parse(read('package.json')).scripts,
+      );
+      expect(
+        commands.filter((command) => command.includes('docker compose')),
+      ).toEqual([]);
+      expect(
+        commands.filter((command) =>
+          command.includes('bash provision/docker/testdb/compose.sh'),
+        ).length,
+      ).toBeGreaterThanOrEqual(4);
+    });
+
+    then('the app dials the TESTDB_PORT override, never the test asset', () => {
+      const factory = read('src/utils/database/getOneDatabaseConnection.ts');
+      expect(factory).toContain('getOneDatabasePort({');
+      expect(factory).not.toContain('getTestdbPort');
+      expect(factory).not.toContain('.test/');
+    });
+
+    then('the schema provisioner dials getTestdbPort, from the test assets', () => {
+      const config = read('provision/schema/connection.config.js');
+      expect(config).toContain('getTestdbPort({');
+      expect(config).toContain(
+        "require('../../src/.test/assets/database/getTestdbPort')",
+      );
+    });
+
+    then('no prod path under src/ imports a testdb test asset', () => {
+      const prodImporters = readdirSync(join(BEST_PRACTICE_DIR, 'src/utils'), {
+        recursive: true,
+      })
+        .map((entry) => entry.toString())
+        .filter((path) => path.endsWith('.ts') && !path.endsWith('.test.ts'))
+        .filter((path) =>
+          /getTestdb(Port|Identity)|\.test\/assets/.test(
+            read(join('src/utils', path)),
+          ),
+        );
+      expect(prodImporters).toEqual([]);
+    });
+  });
+
+  given('[case6] compose.sh, run in a linked worktree', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts': readFileSync(
+            join(BEST_PRACTICE_DIR, 'src/.test/assets/database/getTestdbIdentity.ts'),
+            'utf8',
+          ),
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports what compose would have received
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(
+        join(bin, 'docker'),
+        '#!/usr/bin/env bash\necho "suffix=$TESTDB_SUFFIX port=$TESTDB_PORT args=$*"\n',
+      );
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      const identity = getTestdbIdentity(
+        { portDeclared: PORT_DECLARED },
+        { cwd: repo.worktreeA, env: ENV_LOCAL },
+      );
+      return { result, identity, worktree: realpathSync(repo.worktreeA) };
+    });
+
+    then('it exits 0', () => {
+      expect(scene.result.stderr).toEqual('');
+      expect(scene.result.status).toEqual(0);
+    });
+
+    then('docker compose receives the worktree identity and the args', () => {
+      expect(scene.result.stdout.trim()).toEqual(
+        `suffix=${scene.identity.suffix} port=${scene.identity.port} args=compose -f ${scene.worktree}/provision/docker/testdb/docker-compose.yml up -d`,
+      );
+    });
+  });
+
+  given('[case7] compose.sh, where the identity util yields a malformed port', () => {
+    const scene = useBeforeAll(async () => {
+      const repo = genRepoWithWorktrees({
+        slug: 'testdb-per-worktree-compose-malformed',
+        files: {
+          'src/.test/assets/database/getTestdbIdentity.ts':
+            "export const getTestdbIdentity = (_input: { portDeclared: number }) => ({ suffix: '-abc123', port: Number.NaN });\n",
+          'config/test.json': JSON.stringify({
+            database: { tunnel: { local: { host: 'localhost', port: 7821 } } },
+          }),
+          'provision/docker/testdb/docker-compose.yml': 'services: {}\n',
+        },
+      });
+      copyFileSync(
+        join(BEST_PRACTICE_DIR, 'provision/docker/testdb/compose.sh'),
+        join(repo.worktreeA, 'provision/docker/testdb/compose.sh'),
+      );
+      symlinkSync(REPO_NODE_MODULES, join(repo.worktreeA, 'node_modules'));
+
+      // a docker stand-in that reports any call it receives
+      const bin = join(repo.worktreeA, '.bin');
+      mkdirSync(bin);
+      writeFileSync(join(bin, 'docker'), '#!/usr/bin/env bash\necho "docker called"\n');
+      chmodSync(join(bin, 'docker'), 0o755);
+
+      const result = spawnSync(
+        'bash',
+        ['provision/docker/testdb/compose.sh', 'up', '-d'],
+        {
+          cwd: repo.worktreeA,
+          encoding: 'utf8',
+          env: { ...ENV_LOCAL, PATH: `${bin}:${process.env.PATH}` },
+        },
+      );
+      return { result };
+    });
+
+    then('it halts with exit 1 and names the malformed identity', () => {
+      expect(scene.result.status).toEqual(1);
+      expect(scene.result.stderr).toContain(
+        "💥 MalfunctionError: getTestdbIdentity yielded '-abc123 NaN'",
+      );
+    });
+
+    then('docker compose is never called', () => {
+      expect(scene.result.stdout).not.toContain('docker called');
+    });
+  });
+});

package/dist/.test/assets/git/declarations/practices/persist-with-rds/testdb-preflight-failloud.declapract.integration.test.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the testdb preflight probe (#589) to fail LOUD, not hide
+ * .why  = the prior probe swallowed psql stderr (`> /dev/null 2>&1`), printed one
+ *         hardcoded diagnosis regardless of the true cause, and passed the secret
+ *         inline in the connection string (which leaks it to `ps`). so a bad
+ *         password, a port conflict, and an image build failure all read the same,
+ *         and the real cause never surfaced on timeout.
+ * .teeth = revert the fix (restore `> /dev/null 2>&1` + the inline password + the
+ *          single hardcoded line) and each `then` below goes red.
+ * .note  = a `.declapract.test.ts` at the practice ROOT is a UNIT-test marker — it is
+ *          not loaded as a declaration nor copied to a consumer. it anchors on
+ *          __dirname (not process.cwd()) so it reads the shipped template directly.
+ */
+
+const source = readFileSync(
+  join(
+    __dirname,
+    'best-practice/provision/docker/testdb/wait-for-postgres.sh',
+  ),
+  'utf8',
+);
+
+describe('testdb preflight fails loud (#589)', () => {
+  given('the shipped wait-for-postgres preflight probe', () => {
+    when('[t0] it runs the psql probe', () => {
+      then('it does not swallow the probe stderr to /dev/null', () => {
+        expect(source).not.toContain('/dev/null');
+      });
+
+      then('it captures the probe stderr for surfacing on timeout', () => {
+        expect(source).toContain('lasterr=$(psql');
+        expect(source).toContain('2>&1');
+      });
+    });
+
+    when('[t1] the probe fails past the timeout', () => {
+      then('it echoes the captured last error to stderr', () => {
+        expect(source).toContain('>&2 echo "$lasterr"');
+      });
+
+      then('it no longer prints only the one hardcoded diagnosis', () => {
+        expect(source).not.toContain('postgres too long');
+      });
+    });
+
+    when('[t2] it authenticates to postgres', () => {
+      then('it passes the secret via PGPASSWORD, not inline in the connstring', () => {
+        // the secret rides PGPASSWORD (never the connstring, which leaks to `ps`), and
+        // the env read uses the safe-default form per rule.require.safe-shell-vars
+        expect(source).toContain('export PGPASSWORD="${POSTGRES_PASSWORD:-}"');
+        expect(source).not.toContain('password=$POSTGRES_PASSWORD');
+      });
+    });
+
+    when('[t3] a consumer shell runs it under nounset', () => {
+      then('it opens with set -eu so an unset env fails loud, not silent', () => {
+        expect(source).toContain('set -eu');
+      });
+
+      then('it reads every optional env var with the ${VAR:-} default form', () => {
+        // no bare "$VAR" env read survives: under set -u a bare read is an unbound-variable
+        // crash; the :- default keeps a loud, correct connect attempt instead
+        expect(source).not.toContain('"$POSTGRES_PASSWORD"');
+        expect(source).not.toContain('dbname=$POSTGRES_DB ');
+        expect(source).toContain('${POSTGRES_DB:-}');
+      });
+    });
+
+    when('[t4] the shipped probe is vibechecked as a whole', () => {
+      then('the emitted wait-for-postgres.sh matches snapshot', () => {
+        // snapshot the whole shipped probe so a reword that keeps the pinned tokens green
+        // (a reshaped psql invocation, a rephrased echo, a moved PGPASSWORD export) reddens a
+        // vibecheck in review — the tokens above prove presence, this proves the exact text
+        // (rule.require.contract-snapshot-exhaustiveness)
+        expect(source).toMatchSnapshot('wait-for-postgres.sh preflight probe');
+      });
+    });
+  });
+});