declapract-typescript-ehmpathy 0.49.14 → 0.50.0

package/dist/.test/assets/git/declarations/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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/docker-compose.yml

@@ -0,0 +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}${TESTDB_SUFFIX:-}
+    command: postgres -c 'max_connections=500'
+    ports:
+      - ${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 @declapract{variable.databaseName}']
+      interval: 5s
+      timeout: 5s
+      retries: 5

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/init/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!readme.md

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/init/readme.md

@@ -0,0 +1,3 @@
+all .sql files in this dir will be executed against db on load
+
+WARNING: if any of the files here cause an error when run, then the container will never be created, silently!

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/wait-for-postgres.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+set -eu
+# wait until postgres is really available
+maxcounter=45
+
+echo "waiting for postgres server to begin accepting connections..."
+counter=1
+# pass the secret via PGPASSWORD, not inline in the connection string (which leaks it to `ps`)
+export PGPASSWORD="${POSTGRES_PASSWORD:-}"
+# capture the probe's stderr so the real cause (bad password, port conflict, image build failure)
+# surfaces on timeout, rather than one hardcoded diagnosis that reads the same for every cause
+lasterr=""
+while true; do
+    # fold the capture into the if-condition so `set -e` does not exit on the expected
+    # connect failures while postgres warms up; lasterr still holds the last stderr
+    if lasterr=$(psql "dbname=${POSTGRES_DB:-} host=localhost user=postgres port=5432" -c '\l' 2>&1); then break; fi
+    sleep 1
+    counter=`expr $counter + 1`
+    if [ $counter -gt $maxcounter ]; then
+        >&2 echo "postgres did not accept connections after ${maxcounter}s; the last psql error was:"
+        >&2 echo "$lasterr"
+        exit 1
+    fi;
+done
+echo "connected to postgres instance successfully"

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

@@ -0,0 +1,36 @@
+/**
+ * .what = database credentials for sql-schema-control
+ * .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();
+
+  // select the cicd grant to connect as; default to for-apply (full/write access).
+  // the plan job opts down to the readonly for-plan grant via GRANT=plan.
+  const grant = process.env.GRANT === 'plan' ? 'for-plan' : 'for-apply';
+  const role = config.database.role.cicd[grant];
+
+  const credentials = {
+    host: config.database.tunnel.local.host,
+    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,
+    password: role.password,
+  };
+  return credentials;
+};
+
+module.exports = {
+  promiseConfig: promiseSchemaControlCredentials,
+};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/control.yml

@@ -0,0 +1,7 @@
+language: postgres
+dialect: 17
+connection: ./connection.config.js
+strict: true
+definitions:
+  - ./sql/init.yml
+  - ./sql/domain.yml

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/deploy.database.sh

@@ -0,0 +1,97 @@
+#####################################################
+## initialize the database in a live cluster
+## - in other words, it does all of the things that docker does for us when we spin up a cluster without the db already
+## - i.e.,
+##    - create the database
+##    - install the extensions
+##    - creates the schema
+##    - creates the cicd user
+##    - grants the cicd user ownership of the db
+## - note:
+##   - requires pg admin access
+##   - requires _you_ to change the passwords in prod manually
+##
+## usage example:
+## ```sh
+## ./provision/schema/deploy.database.sh prep $(op item get ahbodedb.prep.postgres --fields label=password --format json | jq -r .value)
+## ```
+#####################################################
+
+set -eu
+
+# check that the human has defined the environment that they want this key created for correctly
+ENVIRONMENT="${1:-}";
+if [ "$ENVIRONMENT" != "prod" ] && [ "$ENVIRONMENT" != "prep" ]; then
+  echo "\nerror: environment, the first argument, must be specified as either 'prod' or 'prep'. you specified '$ENVIRONMENT'";
+  exit 2;
+fi
+
+# check that the human is authed into correct account
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account');
+EXPECTED_AWS_ACCOUNT_ID=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.awsAccountId.prod}" || echo "@declapract{variable.awsAccountId.prep}");
+if [ "$AWS_ACCOUNT_ID" != "$EXPECTED_AWS_ACCOUNT_ID" ]; then
+  echo "\nerror: the AWS_ACCOUNT that you are signed into is not correct for the environment you specified. you are authed into account '$AWS_ACCOUNT_ID' but the correct account id for '$ENVIRONMENT' is '$EXPECTED_AWS_ACCOUNT_ID'";
+  exit 2;
+fi
+
+# check that pg admin password was specified
+POSTGRES_ADMIN_PASSWORD="${2:-}"
+if [ -z "${POSTGRES_ADMIN_PASSWORD:-}" ]; then
+  echo "\nerror: POSTGRES_ADMIN_PASSWORD must be defined as second arg";
+  exit 2;
+fi;
+
+# check that the cicd password was provisioned, if in prod, since this is used to create the cicd user
+# note: this reads the legacy DOTTED param name (`....database.role.cicd.password`), a live consumer
+#       distinct from the slash-path plan/apply secrets. it is the prod cicd-user bootstrap credential
+#       and stays alive on purpose — do not prune it as an unreferenced legacy param.
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_PASSWORD=$(aws ssm get-parameter --name "@declapract{variable.organizationName}.@declapract{variable.projectName}.$ENVIRONMENT.database.role.cicd.password" --with-decryption --output text --query Parameter.Value)
+  if [ -z "${CICD_USER_PASSWORD:-}" ]; then
+    echo "\nerror: CICD_USER_PASSWORD must be provisioned with terraform before you run this"
+    exit 2;
+  fi;
+  if [ "$CICD_USER_PASSWORD" = "__IGNORED__" ] || [ "$CICD_USER_PASSWORD" = "__CHANG3_ME__" ]; then
+    echo "\nerror: CICD_USER_PASSWORD must be set to a value other than the default placeholder"
+    exit 2;
+  fi;
+fi;
+
+
+# define the postgres connection string
+CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseTunnelHost.prod}" || echo "@declapract{variable.databaseTunnelHost.prep}");
+CLUSTER_CONNECTION_STRING=postgresql://postgres:$POSTGRES_ADMIN_PASSWORD@$CLUSTER_HOST:5432
+ROOT_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/postgres
+SVC_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/@declapract{variable.databaseName}
+
+# define path to the init sqls
+SRC_PATH=$(readlink --canonicalize "$0");
+SRC_DIR=$(dirname $SRC_PATH);
+INIT_SQLS_DIR=$SRC_DIR/sql/init;
+
+# run the create database command on root db
+echo "\n 🔨 create the database..."
+psql $ROOT_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.database.sql
+
+echo "\n 🔨 install the extensions..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.extensions.sql
+
+echo "\n 🔨 create the schema..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.schema.sql
+
+if [ "$ENVIRONMENT" = "prod" ]; then
+  echo "\n 🔨 grant reads to the datalakedb user..." # only in prod env; we dont want prep's test data in our datalake
+  psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.user.datalakedb.sql
+fi;
+
+echo "\n 🔨 create the cicd user..."
+CICD_USER_CREATE_SQL_PATH=$INIT_SQLS_DIR/.user.cicd.sql
+if [ "$ENVIRONMENT" = "prod" ]; then
+  CICD_USER_CREATE_SQL_PATH_TEMP=$CICD_USER_CREATE_SQL_PATH.tmp # in prod, we must create a temp file which will have the actual password we'll use to create the cicd user
+  cat $CICD_USER_CREATE_SQL_PATH | sed "s/__CHANG3_ME__/${CICD_USER_PASSWORD}/" > $CICD_USER_CREATE_SQL_PATH_TEMP # create the temp file w/ the actual password
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH_TEMP # run the temp create sql w/ the actual password
+  rm $CICD_USER_CREATE_SQL_PATH_TEMP # remove the temp file, so the password doesn't get checked in
+else
+  psql $SVC_DB_CONNECTION_STRING -f $CICD_USER_CREATE_SQL_PATH # otherwise, we can run the file directly. no password replacement required
+fi
+echo "\n 🎉 done"

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.database.sql

@@ -0,0 +1,10 @@
+/**
+ * this command creates the database that the service will use
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a db to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE DATABASE @declapract{variable.databaseName};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql

@@ -0,0 +1,16 @@
+/**
+ * postgres databases use extensions to increase functionality
+ * - we have a minimum set of extensions that are required for sql-schema-generator
+ * - services may also include their own extensions if they want additional functionality
+ * - this is not managed by sql-schema-control
+ *   - requires superuser privileges, cicd user only has db_owner privileges
+ * - this is applied
+ *   - automatically for integration-test db (through `provision/docker/.../init/` directory, with files cp'd by npm provision scripts)
+ *   - by the deployment script for live deployments
+ */
+
+-- extensions required for all sql-schema-generator resources:
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- extensions required for custom use cases in this service:

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

@@ -0,0 +1,46 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+const grabCreateExtensionLinesFromContents = (contents: string) =>
+  contents
+    .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${EXAMPLE_LINE}`,
+    };
+
+  // if the file does exist, then find all the custom create extension lines
+  const requiredCreateExtensionLines = grabCreateExtensionLinesFromContents(
+    context.declaredFileContents!,
+  );
+  const foundCreateExtensionLines =
+    grabCreateExtensionLinesFromContents(contents);
+  const foundCustomCreateExtensionLines = foundCreateExtensionLines.filter(
+    (foundCreateExtensionLine) =>
+      !requiredCreateExtensionLines.some((requiredCreateExtensionLine) =>
+        foundCreateExtensionLine.includes(requiredCreateExtensionLine),
+      ), // 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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.schema.sql

@@ -0,0 +1,11 @@
+/**
+ * this command creates the schema that the service + sql-schema-control will use
+ * - this command must be run inside of the database that was created for this service
+ * - this creates a schema with the same name as the database
+ * - this not managed by sql-schema-control
+ *   - sql-schema-control needs a schema to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+*/
+CREATE SCHEMA @declapract{variable.databaseName};

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.cicd.sql

@@ -0,0 +1,14 @@
+/**
+ * creates a cicd user, with total control over the database and the schema, to be used by sql-schema-control
+ * - full control required since it'll be managing all resources for this db
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a user to run _under_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE USER @declapract{variable.databaseUserName.cicdUser} WITH PASSWORD '__CHANG3_ME__'; -- create cicd user
+ALTER DATABASE @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the database
+ALTER SCHEMA @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the schema, too
+ALTER USER @declapract{variable.databaseUserName.cicdUser} WITH CREATEROLE; -- allow the cicd user to create other users

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.datalakedb.sql

@@ -0,0 +1,12 @@
+/**
+ * grants read access to `datalakedb_federated_query_reader` so that we can query this db from redshift
+ * - this not managed by sql-schema-control
+ *   - since it does not apply in integration test environment (since that user wont exist there)
+ * - this is applied
+ *   - by the deployment script for live deployments
+ */
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+GRANT SELECT ON ALL TABLES IN SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT ON TABLES TO datalakedb_federated_query_reader;
+
+-- don't forget to hop into the datalakedb and add the ext_@declapract{variable.databaseName}

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/default_transaction_isolation.sql

@@ -0,0 +1,6 @@
+/**
+ * we want `read-committed` as the default txn isolation level on our databases
+ * - its _required_ to support high concurrency operations for the upserts generated by `sql-schema-generator`
+ * - this is done automatically by sql-schema-control under the cicd user
+ */
+ALTER DATABASE @declapract{variable.databaseName} SET DEFAULT_TRANSACTION_ISOLATION TO 'read committed';

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init/user.service.sql

@@ -0,0 +1,16 @@
+/**
+ * the service user has maximally restricted permissions
+ * - this is the user that the service will be using to interact with the database
+ * - insert only, baby!
+ */
+CREATE USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__CHANG3_ME__';
+-- ALTER USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__actual_password__';
+
+-- grant usage
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO @declapract{variable.databaseUserName.serviceUser};
+
+-- grant specific privileges to resources in the schema, for all created now and onward (i.e., all)
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT, INSERT, UPDATE ON TABLES TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT EXECUTE ON FUNCTIONS TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT USAGE, SELECT ON SEQUENCES TO @declapract{variable.databaseUserName.serviceUser};
+

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

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

package/dist/.test/assets/git/declarations/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // contains since the user may have exclusions in that "for" object

package/dist/.test/assets/git/declarations/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/.test/assets/git/declarations/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/.test/assets/git/declarations/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+/** .what = the two oidc grant scopes config can be read under. */
+export type Grant = 'plan' | 'apply';
+
+/**
+ * .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 under apply; optional under plan
+  const secret = <T extends z.ZodTypeAny>(
+    schema: T,
+  ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
+    // 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;
+
+  return z.object({
+    organization: z.string(),
+    project: z.string(),
+    environment: z.object({
+      access: z.enum(['test', 'prep', 'prod']),
+    }),
+    aws: z.object({
+      account: z.string(),
+      namespace: z.string(),
+    }),
+    database: z.object({
+      target: z.object({
+        database: z.string(),
+        schema: z.string(),
+      }),
+      role: z.object({
+        cicd: z.object({
+          // 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(),
+            password: secret(z.string()),
+          }),
+        }),
+        crud: z.object({
+          username: z.string(),
+          password: secret(z.string()),
+        }),
+      }),
+      tunnel: z.object({
+        bastion: z.object({ exid: z.string() }).optional(),
+        cluster: z.object({ name: z.string() }).optional(),
+        local: z.object({
+          host: z.string(),
+          port: z.number(),
+        }),
+        lambda: z
+          .object({
+            host: z.string(),
+            port: z.number(),
+          })
+          .nullable(),
+      }),
+    }),
+  });
+};
+
+/** .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; the default `apply` carries no `| undefined` */
+export type Config<TGrant extends Grant = 'apply'> = z.infer<
+  (typeof schema)[TGrant]
+>;

package/dist/.test/assets/git/declarations/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',
+        );
+      });
+    });
+  });
+});