declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts

@@ -3,56 +3,31 @@ import { getEnvironment } from 'sdk-environment';
 
 /**
  * .what = the secret ssm parameters this service manages via declastruct.
- * .why = these params were migrated off terraform (provision/aws/product/parameter-store.tf,
- *        now a forget). declastruct-aws owns them. every param is a real secret, so each is a
- *        DeclaredAwsSsmParameterSecure (write-only): the plan role reads metadata only
- *        (DescribeParameters + ListTagsForResource — no GetParameter, no kms:Decrypt), and the
- *        value is never read back.
- * .note = adoption supplies NO `value`: the live values were seeded once by terraform and live
- *         only in aws. a value-less secret is write-only KEEP, so plan reports KEEP for extant
- *         params and never rewrites them. a CREATE at plan means the name does not match a live
- *         param — stop and fix. (a value-less secret that is ABSENT throws on apply, per
- *         declastruct-aws setSsmParameterSecure. only prep + prod apply this wish — there is no
- *         aws-test-declastruct job — so the params are declared for every tier without a
- *         conditional, and the absent-throw never triggers in test.)
- * .scope = only the db-role credentials the service + migrations use are managed here. any
- *          service-specific secrets (third-party api keys, etc) are declared alongside these by
- *          the service that owns them. legacy param names with zero consumers are left unmanaged
- *          (terraform forgets them, no delete touches the live values) and can be pruned from aws
- *          once confirmed unreferenced everywhere.
+ * .why = declastruct-aws owns them, off terraform (provision/aws/product/parameter-store.tf is a
+ *        forget). each is a write-only DeclaredAwsSsmParameterSecure: plan reads metadata only and
+ *        never the value.
+ * .note = no `value` is supplied: plan KEEPs an extant param and never rewrites it. a value-less
+ *         param that is ABSENT throws on apply (declastruct-aws setSsmParameterSecure). only prep
+ *         and prod apply this wish, so test never meets that throw.
+ * .scope = the db-role credentials only. a service declares its own other secrets beside these.
  */
 
 /**
- * .what = the conformed environment this wish runs in (access ∈ test | prep | prod).
- * .why = resolved once, as a module global, via sdk-environment's getEnvironment (reads the
- *        ACCESS envar). the wish speaks the org-standard access vocab everywhere it can.
+ * .what = the environment this wish runs in.
+ * .why = `config` NAMES each param (the segment sdk-config derives); `access` TAGS it. the two may
+ *        differ (ACCESS=prep CONFIG=prod is legal), and the app reads the params of its config.
  */
-const { access } = getEnvironment.static();
-
-/**
- * .what = the access as it is SPELLED in the live SSM param NAMES — a legacy slug.
- * .why = terraform seeded these params under var.environment, where the prep account carried the
- *        legacy `dev` slug (see define.infrastructure-dev-vs-application-prep). the live param
- *        names contain that literal string, so the dotted namespace casts prep→dev. test/prod are
- *        unchanged. (tags do NOT cast — they conform to the access vocab; see `secret` below.)
- * .note = this is NOT the lambda-fleet slug bridge `sdkAwsLambdaEnvAccessAncient`, which collapses
- *        BOTH test and prep to `dev`. here test keeps its own name, because this casts a literal
- *        legacy SSM param string, not a fleet slug — a deliberately narrower cast, not a drifted copy.
- */
-const accessSlug = access === 'prep' ? 'dev' : access;
+const { access, config } = getEnvironment.static();
 
 /**
  * .what = declare a secret ssm parameter for adoption (write-only, default key).
- * .why = every param here is a secret whose value already lives in aws; we supply no `value` so
- *        plan KEEPs the extant value and never reads or rewrites it. keyId=null selects the
- *        account default aws/ssm key (what terraform used, no kms_key_id). tags conform to the
- *        org access vocab (`prep`, not the legacy `dev`), so the first apply reconciles the live
- *        `environment` tag from dev→prep (a metadata-only change, no value write).
+ * .why = the value already lives in aws, so plan KEEPs it and never reads or rewrites it.
+ *        keyId=null selects the account default aws/ssm key.
  */
 const secret = (input: { name: string }): DeclaredAwsSsmParameterSecure =>
   DeclaredAwsSsmParameterSecure.as({
     name: input.name,
-    keyId: null, // default aws/ssm key (matches the terraform resources)
+    keyId: null, // default aws/ssm key
     description: null,
     tags: {
       app: '@declapract{variable.organizationName}',
@@ -64,43 +39,22 @@ const secret = (input: { name: string }): DeclaredAwsSsmParameterSecure =>
 
 /**
  * .what = the full set of secret ssm parameters this wish declares.
- * .why = the db-role credentials the service + migrations use. declared for every access —
- *        no per-tier conditional. only prep + prod ever APPLY this wish (there is no
- *        aws-test-declastruct provision job — see .github/workflows/provision.yml), so the
- *        value-less-absent throw on apply cannot trigger in test. test sources its non-sensitive
- *        db creds straight from config/test.json and never reconciles these params.
- * .note = the two cicd credentials are pinned in the prod plan role's iam policy as SLASH paths
- *         with NO tier segment — `parameter/<star>/svc-<star>/database/role/cicd/for-plan/<star>`
- *         and `.../for-apply/<star>`. that pin's arn needs literal `/` separators after
- *         `parameter/`, so a dotted name cannot match it and the plan role gets ciphertext or a
- *         denial, forever. it omits a tier segment on purpose: the aws ACCOUNT separates prep
- *         from prod, never the name. so the for-plan name MUST stay byte-identical to the pin.
- *         the crud credential is pinned by NO policy, so it keeps the dotted
- *         `${org}.${project}.${accessSlug}` name that config/${env}.json matches — hence the
- *         three names differ in shape by design, not by accident.
- * .note = `<star>` stands in for the literal `*` wildcard of that arn, and must stay a stand-in.
- *         a literal `*` written immediately before a `/` closes this comment mid-prose, so every
- *         character after it is read as code and the file no longer parses — which breaks
- *         `pnpm fix` in every repo that adopts this template, with no repair available to them
- *         (declapract apply restores these bytes). see #613.
+ * .why = each name is the one sdk-config derives for a bare `$.at(aws::param)` placeholder in
+ *        config/{env}.json: `/{org}/{project}/{config}/{keyPath}`. the provision declares exactly
+ *        the names the app reads.
+ * .note = @declapract:review — a param whose value still sits only at a prior name has no value
+ *         here, and its first apply throws at the absent param. copy each value to its derived
+ *         name first (see provision/aws/readme.md, "copy params to the derived names").
  */
 export const getAllParameters = (input: {
-  accessSlug: string | null;
+  choice: string | null;
 }): DeclaredAwsSsmParameterSecure[] => {
-  // dotted namespace that prefixes the env-scoped crud param name
-  // keep in sync with terraform local.parameter_store_namespace + config/${env}.json
-  const slug = input.accessSlug ?? accessSlug;
-  const namespace = `@declapract{variable.organizationName}.@declapract{variable.projectName}.${slug}`;
+  // the derived namespace: org, project, then the config slug as the segment
+  const namespace = `/@declapract{variable.organizationName}/@declapract{variable.projectName}/${input.choice ?? config}`;
 
   return [
-    // crud: dotted + tier-scoped, matched by config/${env}.json; no policy pins it
-    secret({ name: `${namespace}.database.role.crud.password` }),
-    // cicd: SLASH path, NO tier segment — byte-identical to the prod plan role's iam pin
-    secret({
-      name: `/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-plan/password`,
-    }),
-    secret({
-      name: `/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-apply/password`,
-    }),
+    secret({ name: `${namespace}/database.role.crud.password` }),
+    secret({ name: `${namespace}/database.role.cicd.for-plan.password` }),
+    secret({ name: `${namespace}/database.role.cicd.for-apply.password` }),
   ];
 };

package/dist/practices/persist-with-rds/best-practice/provision/aws/resources.ts

@@ -27,4 +27,4 @@ export const getProviders = async (): Promise<DeclastructProvider[]> => [
 ];
 
 export const getResources = async (): Promise<DomainEntity<any>[]> =>
-  getAllParameters({ accessSlug: null });
+  getAllParameters({ choice: null });

package/dist/practices/persist-with-rds/best-practice/provision/docker/testdb/build-image.dockerfile.declapract.ts

@@ -0,0 +1,37 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+const POSTGRES_PIN_LINE = /^FROM postgres:\S+$/m;
+
+/**
+ * .what = the declared image, with the repo's own postgres pin kept in place of the template's
+ * .why = each repo pins the testdb to its own livedb's major, and the majors differ across the
+ *        fleet. an exact compare would move every testdb onto the template's pin, which lands
+ *        some ahead of their livedb — the skew where a suite passes on sql the livedb rejects.
+ *        check-engine-skew.sh guards that the pin never leads the livedb (#664)
+ */
+const asDeclaredWithPinFound = (input: {
+  declared: string;
+  found: string | null;
+}): string => {
+  const pinFound = input.found?.match(POSTGRES_PIN_LINE)?.[0];
+  if (!pinFound) return input.declared;
+  return input.declared.replace(POSTGRES_PIN_LINE, pinFound);
+};
+
+export const check: FileCheckFunction = (contents, context) => {
+  const expected = asDeclaredWithPinFound({
+    declared: context.declaredFileContents!,
+    found: contents,
+  });
+  if (contents === expected) return; // the image matches, whatever postgres major it pins
+  throw new Error(
+    'best practice violated: build-image.dockerfile must match the template, with any `FROM postgres:<version>` pin',
+  );
+};
+
+export const fix: FileFixFunction = (contents, context) => ({
+  contents: asDeclaredWithPinFound({
+    declared: context.declaredFileContents!,
+    found: contents,
+  }),
+});

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