declapract-typescript-ehmpathy 0.49.13 → 0.49.15

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/check-engine-skew.integration.test.ts

@@ -0,0 +1,115 @@
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+import { spawnSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * .what = run the skew check, against a testdb pin and a supplied livedb version, or the livedb
+ */
+const runSkewCheck = (input: {
+  testdbPin: string | null;
+  livedbVersion: string | null;
+}): { status: number | null; stdout: string; stderr: string } => {
+  const dockerfileArgs = (() => {
+    if (input.testdbPin === null) return [];
+    const dockerfile = join(
+      genTempDir({ slug: 'check-engine-skew' }),
+      'build-image.dockerfile',
+    );
+    writeFileSync(dockerfile, `${input.testdbPin}\n`);
+    return ['--dockerfile', dockerfile];
+  })();
+  const result = spawnSync(
+    'bash',
+    [
+      join(__dirname, 'check-engine-skew.sh'),
+      ...dockerfileArgs,
+      ...(input.livedbVersion === null
+        ? []
+        : ['--livedb-version', input.livedbVersion]),
+    ],
+    { encoding: 'utf-8', env: process.env },
+  );
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+};
+
+describe('check-engine-skew', () => {
+  given('[case1] the testdb leads the livedb', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it halts', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:17.11',
+          livedbVersion: '13.23',
+        }),
+      );
+
+      then('it exits 2 and names both fixes', () => {
+        expect(result.status).toEqual(2);
+        expect(result.stderr).toContain('✋ ConstraintError');
+        expect(result.stderr).toContain('pin the testdb to postgres 13');
+      });
+    });
+  });
+
+  given('[case2] the testdb trails the livedb', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it passes with a warn', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:13.20',
+          livedbVersion: '17.11',
+        }),
+      );
+
+      then('it exits 0 and emits a github warn', () => {
+        expect(result.status).toEqual(0);
+        expect(result.stdout).toContain('::warning title=engine skew::');
+      });
+    });
+  });
+
+  given('[case3] the majors match', () => {
+    when('[t0] the check runs', () => {
+      const result = useThen('it passes', async () =>
+        runSkewCheck({
+          testdbPin: 'FROM postgres:17.11',
+          livedbVersion: '17.7',
+        }),
+      );
+
+      then('it exits 0 with no warn', () => {
+        expect(result.status).toEqual(0);
+        expect(result.stdout).toContain('majors match');
+        expect(result.stdout).not.toContain('::warning');
+      });
+    });
+  });
+
+  // the gate: the one case that reads the livedb through aws. it needs rds:DescribeDBClusters on
+  // the livedb's account, and with no grant it fails loud on the MalfunctionError, which names it
+  given('[case4] the livedb, read through aws', () => {
+    when('[t0] the check runs against this repo testdb pin', () => {
+      const result = useThen('the read completes', async () =>
+        runSkewCheck({ testdbPin: null, livedbVersion: null }),
+      );
+
+      then('the read succeeds, never a malfunction', () => {
+        expect(result.stderr).not.toContain('💥 MalfunctionError');
+        expect(result.status).not.toEqual(1);
+      });
+
+      then('the testdb does not lead the livedb', () => {
+        expect(result.stderr).not.toContain('✋ ConstraintError');
+        expect(result.status).toEqual(0);
+      });
+
+      then('it reports the version the livedb returned', () => {
+        expect(result.stdout).toMatch(/livedb: postgres \d+(\.\d+)*\n/);
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/check-engine-skew.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = compare the testdb's postgres major against the livedb's.
+#         halt when the testdb leads; warn when it trails
+#
+# .why  = the suite runs against the testdb alone. a testdb ahead of the
+#         livedb can pass on a feature the livedb rejects — a false green
+#         that ships. a testdb behind the livedb is the safe skew: the newer
+#         major accepts near all of the older one's sql
+#
+# .note = the livedb is the cluster config/test.json names, read with the
+#         aws access the integration suite already holds. the integration
+#         suite runs this check against the livedb, so a testdb that leads
+#         it fails the suite
+#
+# usage:
+#   bash provision/docker/testdb/check-engine-skew.sh
+#   bash provision/docker/testdb/check-engine-skew.sh --livedb-version 13.23
+#   bash provision/docker/testdb/check-engine-skew.sh --dockerfile path/to/build-image.dockerfile
+#   bash provision/docker/testdb/check-engine-skew.sh --declared-version 17.11
+#
+# options:
+#   --livedb-version    the livedb's engine version; skips the aws read when given
+#   --declared-version  the engine version the infrastructure declares; when
+#                       given, a halt names how the skew arrived and prints the
+#                       one fix for it. absent, the halt prints both fixes
+#   --dockerfile        the testdb image (default: beside this file)
+#   --config            the config that names the livedb (default: config/test.json)
+#   --help, -h          print this block and exit
+#
+#   the livedb read names the aws cluster from the config's tunnel
+#
+# guarantee:
+#   - exit 0 = majors match, or the testdb trails the livedb (a warn)
+#   - exit 1 = malfunction (the config names no cluster, the aws read failed or returned no version, the dockerfile is unreadable or has no postgres pin)
+#   - exit 2 = constraint (the testdb leads the livedb, or an arg is absent or malformed)
+######################################################################
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCKERFILE="$SELF_DIR/build-image.dockerfile"
+CONFIG="$SELF_DIR/../../../config/test.json"
+LIVEDB_VERSION=""
+DECLARED_VERSION=""
+
+# fail on a flag given with no value, or with the next flag where its value was owed
+require_value() {
+  local flag="" value=""
+  local pair
+  for pair in "$@"; do
+    case "$pair" in
+      flag=*) flag="${pair#flag=}" ;;
+      value=*) value="${pair#value=}" ;;
+    esac
+  done
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "✋ ConstraintError: $flag needs a value" >&2
+    echo "   └─ fix: see $0 --help" >&2
+    exit 2
+  fi
+}
+
+# parse named args
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h) sed -n '3,/^######/{/^######/!p;}' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    --livedb-version) require_value flag="$1" value="${2:-}"; LIVEDB_VERSION="$2"; shift 2 ;;
+    --declared-version) require_value flag="$1" value="${2:-}"; DECLARED_VERSION="$2"; shift 2 ;;
+    --dockerfile) require_value flag="$1" value="${2:-}"; DOCKERFILE="$2"; shift 2 ;;
+    --config) require_value flag="$1" value="${2:-}"; CONFIG="$2"; shift 2 ;;
+    *)
+      echo "✋ ConstraintError: unknown arg '$1'" >&2
+      echo "   └─ fix: see $0 --help" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# fail on a dockerfile the grep cannot read, so a read failure never reads as an absent pin
+if [[ ! -f "$DOCKERFILE" || ! -r "$DOCKERFILE" ]]; then
+  echo "💥 MalfunctionError: cannot read the testdb dockerfile at $DOCKERFILE" >&2
+  echo "   └─ fix: pass --dockerfile with a readable path, or restore build-image.dockerfile beside this file" >&2
+  exit 1
+fi
+
+# read the testdb major from its image pin; the grep exits 1 on no match, which the guard below reports
+TESTDB_MAJOR="$(grep -oE '^FROM postgres:[0-9]+' "$DOCKERFILE" | grep -oE '[0-9]+$' || true)"
+if [[ -z "$TESTDB_MAJOR" ]]; then
+  echo "💥 MalfunctionError: no 'FROM postgres:<major>' pin found in $DOCKERFILE" >&2
+  echo "   └─ fix: pin a major, like 'FROM postgres:17.11', or pass --dockerfile with the testdb image" >&2
+  exit 1
+fi
+
+# reject a supplied version that is not a postgres version
+VERSION_SHAPE='^[0-9]+(\.[0-9]+)*$'
+for supplied in "$LIVEDB_VERSION" "$DECLARED_VERSION"; do
+  if [[ -n "$supplied" && ! "$supplied" =~ $VERSION_SHAPE ]]; then
+    echo "✋ ConstraintError: '$supplied' is not a postgres version" >&2
+    echo "   └─ fix: pass a version like 17.11 or 17" >&2
+    exit 2
+  fi
+done
+
+# read the livedb version, unless supplied
+if [[ -z "$LIVEDB_VERSION" ]]; then
+  CLUSTER="$(jq -r '.database.tunnel.cluster.name // empty' "$CONFIG" || true)"
+  if [[ -z "$CLUSTER" ]]; then
+    echo "💥 MalfunctionError: no cluster name at .database.tunnel.cluster.name in $CONFIG" >&2
+    echo "   └─ fix: the file must exist, parse as json, and name the aws cluster the tunnel reaches" >&2
+    exit 1
+  fi
+  if ! LIVEDB_VERSION="$(aws rds describe-db-clusters \
+    --db-cluster-identifier "$CLUSTER" \
+    --query 'DBClusters[0].EngineVersion' \
+    --output text)"; then
+    echo "💥 MalfunctionError: could not read the engine version of cluster '$CLUSTER'" >&2
+    echo "   └─ fix: the caller needs aws auth with rds:DescribeDBClusters on the livedb's account" >&2
+    exit 1
+  fi
+  if [[ ! "$LIVEDB_VERSION" =~ $VERSION_SHAPE ]]; then
+    echo "💥 MalfunctionError: cluster '$CLUSTER' reported engine version '$LIVEDB_VERSION', which is not a postgres version" >&2
+    exit 1
+  fi
+fi
+
+# the livedb major: its version up to the first dot (17.11 → 17)
+LIVEDB_MAJOR="${LIVEDB_VERSION%%.*}"
+
+# report the two engines
+echo "🔭 engine skew"
+echo "   ├─ testdb: postgres $TESTDB_MAJOR ($DOCKERFILE)"
+echo "   └─ livedb: postgres $LIVEDB_VERSION"
+
+# halt when the testdb leads the livedb
+if (( TESTDB_MAJOR > LIVEDB_MAJOR )); then
+  echo "✋ ConstraintError: the testdb (postgres $TESTDB_MAJOR) leads the livedb (postgres $LIVEDB_MAJOR)" >&2
+  echo "   ├─ why: a green suite here can rest on a postgres $TESTDB_MAJOR feature the livedb rejects" >&2
+
+  # name the arrival when the declared target is known
+  DECLARED_MAJOR="${DECLARED_VERSION%%.*}"
+  if [[ -n "$DECLARED_MAJOR" ]] && (( DECLARED_MAJOR > LIVEDB_MAJOR )); then
+    echo "   ├─ how: the livedb sits below its declared target $DECLARED_MAJOR — a flip was reverted, or has not yet applied" >&2
+    echo "   └─ fix: pin the testdb to postgres $LIVEDB_MAJOR until the flip holds. do not re-flip a reverted livedb from here" >&2
+    exit 2
+  fi
+  if [[ -n "$DECLARED_MAJOR" ]]; then
+    echo "   ├─ how: the livedb matches its declared target $DECLARED_MAJOR — the testdb pin moved ahead of the flip" >&2
+    echo "   └─ fix: declare postgres $TESTDB_MAJOR in the infrastructure, then merge after the livedb reads it" >&2
+    exit 2
+  fi
+
+  echo "   └─ fix: one of two, by how the skew arrived" >&2
+  echo "      ├─ the pin moved before the flip: merge after the livedb reads postgres $TESTDB_MAJOR" >&2
+  echo "      └─ the livedb fell back:          pin the testdb to postgres $LIVEDB_MAJOR until the flip holds" >&2
+  exit 2
+fi
+
+# warn when the testdb trails the livedb
+if (( TESTDB_MAJOR < LIVEDB_MAJOR )); then
+  echo ""
+  echo "::warning title=engine skew::testdb postgres $TESTDB_MAJOR trails the livedb's postgres $LIVEDB_MAJOR. safe, but bump the pin on the next declapract upgrade"
+  exit 0
+fi
+
+echo "✨ majors match"

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/compose.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = run docker compose on this checkout's testdb
+#
+# .why  = two worktrees of one repo must never share one testdb. this
+#         wrapper exports the compose project suffix and the host port
+#         that getTestdbIdentity derives for this checkout, so the
+#         compose file, the app, and the schema provisioner all agree
+#
+# usage:
+#   bash provision/docker/testdb/compose.sh up -d
+#   bash provision/docker/testdb/compose.sh down
+#
+# guarantee:
+#   - ci and a main checkout keep the port config/test.json declares
+#   - a linked worktree gets its own project, container, and port
+#   - every arg passes through to docker compose unchanged
+######################################################################
+set -euo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(git -C "$SELF_DIR" rev-parse --show-toplevel)"
+
+# derive this checkout's identity from the one util every port reader shares
+IDENTITY="$(cd "$ROOT_DIR" && node -r esbuild-register -e "
+  const { getTestdbIdentity } = require('./src/.test/assets/database/getTestdbIdentity');
+  const portDeclared = require('./config/test.json').database.tunnel.local.port;
+  const identity = getTestdbIdentity({ portDeclared });
+  process.stdout.write(identity.suffix + ' ' + identity.port);
+")"
+
+# halt on an identity that is not "<suffix> <port>", so compose never binds a malformed port
+if [[ ! "$IDENTITY" =~ ^[^\ ]*\ [0-9]+$ ]]; then
+  echo "💥 MalfunctionError: getTestdbIdentity yielded '$IDENTITY', not '<suffix> <port>'" >&2
+  echo "   └─ fix: check src/.test/assets/database/getTestdbIdentity.ts and config/test.json database.tunnel.local.port" >&2
+  exit 1
+fi
+
+# split "<suffix> <port>" at its one space: the suffix before it, the port after it
+export TESTDB_SUFFIX="${IDENTITY% *}"
+export TESTDB_PORT="${IDENTITY#* }"
+
+exec docker compose -f "$SELF_DIR/docker-compose.yml" "$@"

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/docker-compose.yml

@@ -1,18 +1,19 @@
 version: '3'
+name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-} # one compose project per worktree; see compose.sh
 services:
   postgres:
     build:
       context: .
       dockerfile: build-image.dockerfile
-    container_name: @declapract{variable.databaseName}
+    container_name: @declapract{variable.databaseName}${TESTDB_SUFFIX:-}
     command: postgres -c 'max_connections=500'
     ports:
-      - 7821:5432
+      - ${TESTDB_PORT:-7821}:5432
     environment:
       POSTGRES_PASSWORD: a-secure-password # default user is `postgres`
       POSTGRES_DB: @declapract{variable.databaseName} # creates the database for us automatically
     healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U postgres -d homeservicesdb']
+      test: ['CMD-SHELL', 'pg_isready -U postgres -d @declapract{variable.databaseName}']
       interval: 5s
       timeout: 5s
       retries: 5

package/dist/practices/persist-with-rds/best-practice/provision/schema/connection.config.js

@@ -3,7 +3,11 @@
  * .why = reuses app's getConfig for consistent config resolution
  */
 require('esbuild-register');
+const { getEnvironment } = require('sdk-environment');
 const { getConfig } = require('../../src/utils/config/getConfig');
+const {
+  getTestdbPort,
+} = require('../../src/.test/assets/database/getTestdbPort');
 
 const promiseSchemaControlCredentials = async () => {
   const config = await getConfig();
@@ -15,7 +19,10 @@ const promiseSchemaControlCredentials = async () => {
 
   const credentials = {
     host: config.database.tunnel.local.host,
-    port: config.database.tunnel.local.port,
+    port: getTestdbPort({
+      access: getEnvironment.static().access,
+      portDeclared: config.database.tunnel.local.port,
+    }), // a worktree's testdb binds a port of its own; see getTestdbIdentity
     database: config.database.target.database,
     schema: config.database.target.schema,
     username: role.username,

package/dist/practices/persist-with-rds/best-practice/provision/schema/control.yml

@@ -1,5 +1,5 @@
 language: postgres
-dialect: 10.7
+dialect: 17
 connection: ./connection.config.js
 strict: true
 definitions:

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql.declapract.ts

@@ -5,13 +5,16 @@ const grabCreateExtensionLinesFromContents = (contents: string) =>
     .split('\n')
     .filter((line) => line.startsWith('CREATE EXTENSION IF NOT EXISTS'));
 
+// an example line, written with a fresh file, that shows how the file can be extended
+const EXAMPLE_LINE = '-- CREATE EXTENSION IF NOT EXISTS ...';
+
 export const check = FileCheckType.CONTAINS;
 
 export const fix: FileFixFunction = (contents, context) => {
   // if the file doesn't exist, create what we want to see - with an additional example of how it can be extended
   if (!contents)
     return {
-      contents: `${context.declaredFileContents!.trim()}\n-- CREATE EXTENSION IF NOT EXISTS ...`,
+      contents: `${context.declaredFileContents!.trim()}\n${EXAMPLE_LINE}`,
     };
 
   // if the file does exist, then find all the custom create extension lines
@@ -27,11 +30,17 @@ export const fix: FileFixFunction = (contents, context) => {
       ), // if this found create-extension statement is not a required one, then its custom
   );
 
+  // keep the example line where present, so a second fix over the fresh file is a no-op (#536)
+  const exampleLinesKept = contents.split('\n').includes(EXAMPLE_LINE)
+    ? [EXAMPLE_LINE]
+    : [];
+
   // and set the contents equal to what we want to see + their custom ones
   return {
     contents: [
       context.declaredFileContents!.trim(),
       ...foundCustomCreateExtensionLines,
+      ...exampleLinesKept,
     ].join('\n'),
   };
 };

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml

@@ -1,9 +1,9 @@
 - type: change
-  id: init_default_txn_isolation
+  exid: init_default_txn_isolation
   author: declapract
   path: ./init/default_transaction_isolation.sql
 
 - type: change
-  id: init_service_user
+  exid: init_service_user
   author: declapract
   path: ./init/user.service.sql

package/dist/practices/persist-with-rds/best-practice/src/.test/assets/database/getTestdbIdentity.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+/**
+ * .what = read one value from git, in a dir
+ */
+const getGitValue = (input: { cwd: string; args: string[] }): string =>
+  execFileSync('git', input.args, { cwd: input.cwd, encoding: 'utf8' }).trim();
+
+/**
+ * .what = this checkout's testdb identity: the suffix of its compose project and container, and
+ *         the host port it binds
+ * .why = two worktrees of one repo must never share one testdb, or an integration run in one
+ *        reads or clobbers the rows of another, and a `start:testdb` in one stops the other's db
+ * .note = ci and a main checkout keep the declared port and no suffix, so both behave as before.
+ *         only a linked worktree derives its own, from a hash of its toplevel path, so the same
+ *         worktree always lands on the same port
+ * .note = the port offset spans 999 slots, so two linked worktrees can draw one port (~1 in 999
+ *         per pair). that collision is loud, never shared: the suffix differs, so each worktree
+ *         names its own compose project and volume, and docker refuses the second bind with
+ *         `port is already allocated`. stop one worktree's testdb to start the other's
+ */
+export const getTestdbIdentity = (
+  input: { portDeclared: number },
+  context: { cwd: string; env: NodeJS.ProcessEnv } = {
+    cwd: process.cwd(),
+    env: process.env,
+  },
+): { suffix: string; port: number } => {
+  // ci runs one checkout per job, so it keeps the declared port
+  if (context.env.CI) return { suffix: '', port: input.portDeclared };
+
+  // a main checkout keeps the declared port; only a linked worktree has a git dir of its own
+  const gitDir = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--absolute-git-dir'],
+  });
+  const gitDirCommon = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+  });
+  if (gitDir === gitDirCommon) return { suffix: '', port: input.portDeclared };
+
+  // derive the suffix and the port from the worktree's toplevel path
+  const toplevel = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--show-toplevel'],
+  });
+  const hash = createHash('sha256').update(toplevel).digest('hex');
+  const offset = 1 + (Number.parseInt(hash.slice(0, 8), 16) % 999);
+  return { suffix: `-${hash.slice(0, 6)}`, port: input.portDeclared + offset };
+};

package/dist/practices/persist-with-rds/best-practice/src/.test/assets/database/getTestdbPort.ts

@@ -0,0 +1,17 @@
+import { getTestdbIdentity } from './getTestdbIdentity';
+
+/**
+ * .what = the host port this checkout's testdb binds, for an access
+ * .why = the test harness and the schema provisioner ask here, so the compose file, the jest env
+ *        (which hands the port to the app via TESTDB_PORT), and the provisioner of one worktree
+ *        all agree on one port
+ * .note = only `test` access reaches the local testdb; any other access keeps its declared port
+ * .note = a test asset: the app never imports it. the app reads TESTDB_PORT via getOneDatabasePort
+ */
+export const getTestdbPort = (input: {
+  access: string;
+  portDeclared: number;
+}): number => {
+  if (input.access !== 'test') return input.portDeclared;
+  return getTestdbIdentity({ portDeclared: input.portDeclared }).port;
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -4,34 +4,16 @@ import { z } from 'zod';
 export type Grant = 'plan' | 'apply';
 
 /**
- * .what = get the config schema for a given oidc grant.
- * .why = the prod plan job's oidc role is DENIED every ssm secret except the
- *        for-plan db credential. under grant=plan the
- *        eagerly-read getConfig() cannot read for-apply's password (or any other
- *        secret); sdk-config substitutes undefined for each denied param, so those
- *        must be .optional() to tolerate the miss. grant=apply (the default — apply
- *        job, cloud runtime, local dev, tests) keeps every secret REQUIRED, so its
- *        inferred type carries no `| undefined` and needs no guards at consumers.
- * .note = grant is a per-schema arg, NOT read from env here; getConfig picks which
- *         schema to parse with at call time (see getConfig.ts).
+ * .what = the config schema for one grant: `plan` marks the secrets its role may not read optional
+ * .why = see "config grants" in the persist-with-rds practice readme
  */
 const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
-  // required by default; optional only under grant=plan. generic on the LITERAL
-  // TGrant so each schema infers monomorphically (all-required for apply,
-  // reader-denied-optional for plan) instead of the widened union.
+  // required under apply; optional under plan
   const secret = <T extends z.ZodTypeAny>(
     schema: T,
   ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
-    // as-cast — why types miss: TS cannot relate a conditional return type
-    //   (`TGrant extends 'plan' ? … : …`) to a runtime `grant === 'plan'`
-    //   ternary; the two are unrelated to the checker, so the ternary widens to
-    //   `ZodOptional<T> | T` and does not fit the declared conditional return.
-    // correct type: the value IS `ZodOptional<T>` when TGrant='plan' and `T`
-    //   otherwise — exactly the declared return; the runtime branch matches the
-    //   type branch one-to-one, so the assertion is sound.
-    // removal path: TS learns to relate a conditional return type to a runtime
-    //   discriminant check (microsoft/TypeScript#33912), or the caller splits
-    //   into two monomorphic overloads that never share this body.
+    // as-cast: the runtime branch matches the conditional type one-to-one.
+    // removal path: microsoft/TypeScript#33912, or two monomorphic overloads
     (grant === 'plan' ? schema.optional() : schema) as TGrant extends 'plan'
       ? z.ZodOptional<T>
       : T;
@@ -53,13 +35,7 @@ const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
       }),
       role: z.object({
         cicd: z.object({
-          // for-plan and for-apply may map to DIFFERENT db users (e.g. a readonly
-          // user for-plan), so each carries its own username. names mirror the prod
-          // oidc roles (for-plan / for-apply) that read them.
-          // .note: only for-apply's PASSWORD is reader-denied under grant=plan; the
-          // username is a readable static, so the object is always present. mark the
-          // password itself as the secret (a secret() on the whole object would never
-          // tolerate the miss — the present object still validates its required password).
+          // each grant role may map to its own db user; only for-apply's password is a secret
           'for-plan': z.object({ username: z.string(), password: z.string() }),
           'for-apply': z.object({
             username: z.string(),
@@ -89,22 +65,13 @@ const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
   });
 };
 
-/**
- * .what = one schema per grant. apply = every secret required (the default);
- *         plan = the reader-denied secrets optional.
- * .why = getConfig picks which to parse with by grant (see getConfig.ts).
- */
+/** .what = one schema per grant; getConfig picks one at call time */
 export const schema = {
   apply: getOneSchema('apply'),
   plan: getOneSchema('plan'),
 } as const;
 
-/**
- * .what = the config type for a grant, default apply.
- * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
- *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
- *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
- */
+/** .what = the config type for a grant; the default `apply` carries no `| undefined` */
 export type Config<TGrant extends Grant = 'apply'> = z.infer<
   (typeof schema)[TGrant]
 >;

package/dist/practices/persist-with-rds/best-practice/src/utils/database/asDatabaseClientSsl.test.ts

@@ -0,0 +1,82 @@
+import { ConstraintError, UnexpectedCodePathError } from 'helpful-errors';
+import { getError, given, then, when } from 'test-fns';
+
+import type { PeerCertificate } from 'node:tls';
+import { asDatabaseClientSsl } from './asDatabaseClientSsl';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+const CLUSTER_ENDPOINT = 'surfdb.cluster-abc123.us-east-1.rds.amazonaws.com';
+
+/**
+ * .what = a peer certificate shaped as the one an aurora cluster presents
+ * .why = checkServerIdentity reads only the subject and the subject alt names
+ */
+const certOfCluster = {
+  subject: { CN: CLUSTER_ENDPOINT },
+  subjectaltname: `DNS:${CLUSTER_ENDPOINT}`,
+} as PeerCertificate; // note: a partial cert; checkServerIdentity reads only these two fields
+
+describe('asDatabaseClientSsl', () => {
+  given('[case1] no cluster endpoint declared (the local testdb)', () => {
+    when('[t0] the ssl options are derived', () => {
+      then('the client connects plain', () => {
+        expect(asDatabaseClientSsl({ clusterEndpoint: null })).toEqual(false);
+      });
+    });
+  });
+
+  given('[case2] a us-east-1 cluster endpoint declared', () => {
+    const ssl =
+      asDatabaseClientSsl({ clusterEndpoint: CLUSTER_ENDPOINT }) ||
+      UnexpectedCodePathError.throw(
+        'a declared cluster endpoint must yield ssl options, never a plain connect',
+        { clusterEndpoint: CLUSTER_ENDPOINT },
+      );
+
+    when('[t0] the ssl options are derived', () => {
+      then('the chain is verified against the rds roots', () => {
+        expect(ssl.rejectUnauthorized).toEqual(true);
+        expect(ssl.ca).toEqual(RDS_CA_BUNDLE_US_EAST_1);
+      });
+    });
+
+    when('[t1] the dialed host is a local tunnel alias', () => {
+      then('the name check passes against the cluster endpoint', () => {
+        expect(
+          ssl.checkServerIdentity!('aws.ssmproxy.surfdb.prep', certOfCluster),
+        ).toEqual(undefined);
+      });
+    });
+
+    when('[t2] the certificate names a different host', () => {
+      then('the name check rejects it', () => {
+        const certOfImpostor = {
+          subject: { CN: 'impostor.example.com' },
+          subjectaltname: 'DNS:impostor.example.com',
+        } as PeerCertificate; // note: a partial cert; checkServerIdentity reads only these two fields
+        // node's Error lives in another realm than jest's, so assert on the message
+        expect(
+          ssl.checkServerIdentity!(CLUSTER_ENDPOINT, certOfImpostor)?.message,
+        ).toContain(`Host: ${CLUSTER_ENDPOINT}. is not in the cert's altnames`);
+      });
+    });
+  });
+
+  given('[case3] a cluster endpoint outside us-east-1', () => {
+    when('[t0] the ssl options are derived', () => {
+      then('it fails loud, with a hint to add that region bundle', async () => {
+        const error = await getError(async () =>
+          asDatabaseClientSsl({
+            clusterEndpoint:
+              'surfdb.cluster-abc123.eu-west-2.rds.amazonaws.com',
+          }),
+        );
+        expect(error).toBeInstanceOf(ConstraintError);
+        expect(error.message).toContain('not in us-east-1');
+        expect(JSON.stringify(error)).toContain(
+          'truststore.pki.rds.amazonaws.com',
+        );
+      });
+    });
+  });
+});