declapract-typescript-ehmpathy 0.40.0 → 0.41.0

package/dist/practices/cicd-common/best-practice/.github/workflows/.test.yml

@@ -36,7 +36,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -57,7 +57,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -78,7 +78,7 @@ jobs:
       - name: set node version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: set terraform version
         uses: hashicorp/setup-terraform@v3
@@ -102,7 +102,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -123,7 +123,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -144,7 +144,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -168,8 +168,11 @@ jobs:
             && echo 'wrong aws account' && exit 1 \
             || echo 'correct aws account';
 
-      - name: provision:integration-test-db
-        run: npm run provision:integration-test-db --if-present
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:dev
+        run: npm run start:livedb:dev --if-present
 
       - name: test:integration
         run: THOROUGH=true npm run test:integration
@@ -184,7 +187,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: get node-modules from cache
         uses: actions/cache/restore@v4
@@ -208,8 +211,11 @@ jobs:
             && echo 'wrong aws account' && exit 1 \
             || echo 'correct aws account';
 
-      - name: provision:integration-test-db
-        run: npm run provision:integration-test-db --if-present
+      - name: start:testdb
+        run: npm run start:testdb --if-present
+
+      - name: start:livedb:dev
+        run: npm run start:livedb:dev --if-present
 
       - name: test:acceptance:locally
         run: npm run test:acceptance:locally

package/dist/practices/cicd-common/best-practice/.github/workflows/release.yml

@@ -9,9 +9,9 @@ jobs:
   release-please:
     runs-on: ubuntu-24.04
     steps:
-      - uses: google-github-actions/release-please-action@v3
+      - uses: google-github-actions/release-please-action@v3.7.6 # https://github.com/googleapis/release-please-action/issues/840
         with:
           token: ${{ secrets.RELEASE_PLEASE_GITHUB_TOKEN }}
           release-type: node
-          pull-request-title-pattern: 'chore(release): v${version} 🎉'
+          pull-request-title-pattern: "chore(release): v${version} 🎉"
           changelog-path: changelog.md

package/dist/practices/cicd-common/best-practice/.github/workflows/review.yml

@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   pullreq-title:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: test:pullreq:title
         uses: amannn/action-semantic-pull-request@v5

package/dist/practices/cicd-service/best-practice/.agent/repo=.this/skills/use.rds.capacity.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# SKILL: use.rds.capacity
+#
+# Ensures the RDS database has capacity and is ready to accept connections.
+#
+# What it does:
+#   1. Opens a VPC tunnel to the database cluster (via use.vpc.tunnel)
+#   2. Extracts the database host and port from the tunnel configuration
+#   3. Polls the database until it responds (waking serverless RDS if paused)
+#
+# When to use:
+#   - Before running tests or migrations that need database access
+#   - When a serverless RDS instance may be paused and needs to be awakened
+#   - Any time you need to ensure the database is ready before proceeding
+#
+# Usage:
+#   STAGE=dev ./.agent/repo=.this/skills/use.rds.capacity.sh
+#
+# Prerequisites:
+#   - STAGE environment variable must be set
+#   - AWS credentials configured with SSM access
+#   - sudo access (for /etc/hosts modification via vpc tunnel)
+#   - pg_isready command available (postgresql-client)
+#
+set -eo pipefail
+
+# failfast if STAGE is not declared
+[[ -z "${STAGE:-}" ]] && echo "STAGE is not set" && exit 1
+
+set -u
+
+# ensure the dev tunnel is awake
+.agent/repo=.this/skills/use.vpc.tunnel.ts
+
+# ping until available
+npx declastruct plan --wish .agent/repo=.this/skills/use.vpc.tunnel.ts --into .temp/tunnel.plan.json
+DB_HOST=$(jq -r '.changes[] | select(.forResource.class == "DeclaredUnixHostAlias") | .state.desired.from' .temp/tunnel.plan.json)
+DB_PORT=$(jq -r '.changes[] | select(.forResource.class == "DeclaredAwsVpcTunnel") | .state.desired.from.port' .temp/tunnel.plan.json)
+
+# await for the database to have capacity (awakens serverless rds if paused)
+echo "Awaiting database capacity at $DB_HOST:$DB_PORT..."
+timeout 180 bash -c "until pg_isready -h $DB_HOST -p $DB_PORT; do sleep 5; done"
+echo "Database is ready"
+

package/dist/practices/cicd-service/best-practice/.agent/repo=.this/skills/use.vpc.tunnel.ts

@@ -0,0 +1,79 @@
+#!/bin/bash
+//bin/true && exec npx declastruct apply --plan yolo --wish "$0"
+//
+// SKILL: use.vpc.tunnel
+//
+// Opens a secure VPC tunnel to the ahbodedb database cluster via AWS SSM.
+//
+// What it does:
+//   1. Creates an SSM tunnel through the vpc-main-bastion to the database cluster
+//   2. Binds the tunnel to localhost:$port
+//   3. Adds a /etc/hosts alias so the database can be reached via a friendly hostname
+//
+// When to use:
+//   - Before acceptance tests that need remote database access
+//   - When you need to connect to the database locally
+//   - Any time local code needs to reach an RDS cluster in the VPC
+//
+// Usage:
+//   Direct execution:  ./.agent/repo=.this/skills/use.vpc.tunnel.ts
+//   Via declastruct:   npx declastruct apply --plan yolo --wish .agent/repo=.this/skills/use.vpc.tunnel.ts
+//
+// Prerequisites:
+//   - AWS credentials configured with SSM access
+//   - sudo access (for /etc/hosts modification), if not already set
+//
+// Why via declastruct:
+//   Declastruct enables declarative instructions — you specify *what* you want
+//   (a tunnel, a host alias) rather than *how* to get it (spawn ssm-proxy, edit
+//   /etc/hosts, track PIDs, cleanup, etc...). The runtime diffs current vs desired state
+//   and applies only necessary changes. This makes skills more intuitive and
+//   maintainable, as well as idempotent and safe to run repeatedly.
+//
+import { DeclastructProvider } from 'declastruct';
+import {
+  DeclaredAwsVpcTunnel,
+  getDeclastructAwsProvider,
+} from 'declastruct-aws';
+import {
+  DeclaredUnixHostAlias,
+  getDeclastructUnixNetworkProvider,
+} from 'declastruct-unix-network';
+
+import { getConfig } from '../../../src/utils/config/getConfig';
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  await getDeclastructAwsProvider({}, { log: console }),
+  await getDeclastructUnixNetworkProvider({}, { log: console }),
+];
+
+export const getResources = async () => {
+  // grab the config
+  const config = await getConfig();
+
+  // open the tunnel
+  const tunnel = DeclaredAwsVpcTunnel.as({
+    via: {
+      mechanism: 'aws.ssm',
+      bastion: { exid: 'vpc-main-bastion' },
+    },
+    into: {
+      cluster: { name: 'ahbodedb' },
+    },
+    from: {
+      host: 'localhost',
+      port: config.database.tunnel.local.port,
+    },
+    status: 'OPEN',
+  });
+
+  // bind the host alias
+  const hostAlias = DeclaredUnixHostAlias.as({
+    via: '/etc/hosts',
+    from: config.database.tunnel.local.host,
+    into: '127.0.0.1',
+  });
+
+  // instruct to set each
+  return [tunnel, hostAlias];
+};

package/dist/practices/cicd-service/best-practice/.github/workflows/.deploy-sls.yml

@@ -5,11 +5,11 @@ on:
     inputs:
       stage:
         type: string
-        description: 'the stage to deploy to'
+        description: "the stage to deploy to"
         required: true
       github-environment:
         type: string
-        description: 'the github environment that the apply step will be executed in'
+        description: "the github environment that the apply step will be executed in"
         required: true
       aws-region:
         type: string
@@ -31,9 +31,6 @@ on:
       aws-secret-access-key:
         required: true
         description: required credentials to authenticate with aws provider and state persistance
-      open-vpn-config:
-        required: false
-        description: complete openvpn config required to enter the vpn, if needed
       pagerduty-integration-key:
         required: false
         description: enables sending pagerduty alarms on failure
@@ -52,7 +49,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: configure aws credentials
         uses: aws-actions/configure-aws-credentials@v1
@@ -92,7 +89,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: configure aws credentials
         uses: aws-actions/configure-aws-credentials@v1
@@ -119,40 +116,20 @@ jobs:
         if: steps.cache.outputs.cache-hit != 'true'
         run: npm ci --ignore-scripts --prefer-offline --no-audit
 
-      - name: vpn:prepare
+      - name: vpc:tunnel:open
         if: inputs.needs-vpn-for-acceptance
-        run: |
-          sudo apt update \
-          && sudo apt-get install openvpn openvpn-systemd-resolved \
-          && mkdir ~/.vpn \
-          && echo "${{ secrets.open-vpn-config }}" | base64 -d > ~/.vpn/vpn.connection.ovpn
-
-      - name: vpn:connect
-        if: inputs.needs-vpn-for-acceptance
-        run: |
-          # create the log file, so that we have permissions to read it
-          touch openvpn.log
-
-          # start openvpn in the background
-          sudo openvpn --config ~/.vpn/vpn.connection.ovpn --daemon --log openvpn.log
-
-          # wait until we've confirmed that it successfully connected; https://superuser.com/a/900134/425694
-          ( tail -f -n0 openvpn.log & ) | grep -q "Initialization Sequence Completed"
+        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: test:acceptance
         run: STAGE=${{ inputs.stage }} npm run test:acceptance
 
-      - name: vpn:disconnect
-        if: inputs.needs-vpn-for-acceptance
-        run: sudo killall openvpn
-
       - name: alarm on failure
         env:
           PAGERDUTY_INTEGRATION_KEY: ${{ secrets.pagerduty-integration-key }}
         if: failure() && env.PAGERDUTY_INTEGRATION_KEY
         uses: Entle/action-pagerduty-alert@0.2.0 # https://github.com/marketplace/actions/pagerduty-alert
         with:
-          pagerduty-integration-key: '${{ secrets.pagerduty-integration-key }}'
+          pagerduty-integration-key: "${{ secrets.pagerduty-integration-key }}"
           pagerduty-dedup-key: github_workflow_failed
 
   prune:
@@ -165,7 +142,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: configure aws credentials
         uses: aws-actions/configure-aws-credentials@v1

package/dist/practices/cicd-service/best-practice/.github/workflows/.sql-schema-control.yml

@@ -5,14 +5,14 @@ on:
     inputs:
       stage:
         type: string
-        description: 'the stage to execute against'
+        description: "the stage to execute against"
         required: true
       github-environment:
         type: string
-        description: 'the github environment that the apply step will be executed in'
+        description: "the github environment that the apply step will be executed in"
       allow-apply:
         type: boolean
-        description: 'whether the apply step is enabled. defaults to true on main'
+        description: "whether the apply step is enabled. defaults to true on main"
         default: ${{ github.ref == 'refs/heads/main' }}
       aws-region:
         type: string
@@ -27,9 +27,6 @@ on:
       aws-secret-access-key:
         required: true
         description: required credentials to authenticate with aws provider for db credentials
-      open-vpn-config:
-        required: true
-        description: complete openvpn config required to enter the vpn
 
 jobs:
   install:
@@ -47,7 +44,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: node-modules cache get
         uses: actions/cache/restore@v4
@@ -74,23 +71,8 @@ jobs:
             && echo 'wrong aws account' && exit 1 \
             || echo 'correct aws account';
 
-      - name: vpn:prepare
-        run: |
-          sudo apt update \
-          && sudo apt-get install openvpn openvpn-systemd-resolved \
-          && mkdir ~/.vpn \
-          && echo "${{ secrets.open-vpn-config }}" | base64 -d > ~/.vpn/vpn.connection.ovpn
-
-      - name: vpn:connect
-        run: |
-          # create the log file, so that we have permissions to read it
-          touch openvpn.log
-
-          # start openvpn in the background
-          sudo openvpn --config ~/.vpn/vpn.connection.ovpn --daemon --log openvpn.log
-
-          # wait until we've confirmed that it successfully connected; https://superuser.com/a/900134/425694
-          ( tail -f -n0 openvpn.log & ) | grep -q "Initialization Sequence Completed"
+      - name: vpc:tunnel:open
+        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: plan
         run: STAGE=${{ inputs.stage }} npm run provision:schema:plan | tee ./plan.log
@@ -101,7 +83,7 @@ jobs:
           # check that there was not a connection error
           if grep "connect ETIMEDOUT" ./plan.log
           then
-            echo "🛑 connection timed out, could not execute plan. is vpn working?"
+            echo "🛑 connection timed out, could not execute plan. is vpc tunnel working?"
             exit 1
           fi
 
@@ -116,9 +98,6 @@ jobs:
       - name: has changes planned?
         run: echo "${{ steps.evaluate-plan.outputs.has-changes-planned }}"
 
-      - name: vpn:disconnect
-        run: sudo killall openvpn
-
   apply:
     runs-on: ubuntu-24.04
     environment: ${{ inputs.github-environment }}
@@ -131,7 +110,7 @@ jobs:
       - name: set node-version
         uses: actions/setup-node@v3
         with:
-          node-version-file: '.nvmrc'
+          node-version-file: ".nvmrc"
 
       - name: node-modules cache get
         uses: actions/cache/restore@v4
@@ -158,26 +137,8 @@ jobs:
             && echo 'wrong aws account' && exit 1 \
             || echo 'correct aws account';
 
-      - name: vpn:prepare
-        run: |
-          sudo apt update \
-          && sudo apt-get install openvpn openvpn-systemd-resolved \
-          && mkdir ~/.vpn \
-          && echo "${{ secrets.open-vpn-config }}" | base64 -d > ~/.vpn/vpn.connection.ovpn
-
-      - name: vpn:connect
-        run: |
-          # create the log file, so that we have permissions to read it
-          touch openvpn.log
-
-          # start openvpn in the background
-          sudo openvpn --config ~/.vpn/vpn.connection.ovpn --daemon --log openvpn.log
-
-          # wait until we've confirmed that it successfully connected; https://superuser.com/a/900134/425694
-          ( tail -f -n0 openvpn.log & ) | grep -q "Initialization Sequence Completed"
+      - name: vpc:tunnel:open
+        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: apply
         run: STAGE=${{ inputs.stage }} npm run provision:schema:apply
-
-      - name: vpn:disconnect
-        run: sudo killall openvpn

package/dist/practices/cicd-service/best-practice/.github/workflows/.terraform.yml

@@ -5,13 +5,13 @@ on:
     inputs:
       working-directory:
         type: string
-        description: 'the directory from within which to execute terraform commands'
+        description: "the directory from within which to execute terraform commands"
       github-environment:
         type: string
-        description: 'the github environment that the apply step will be executed in'
+        description: "the github environment that the apply step will be executed in"
       allow-apply:
         type: boolean
-        description: 'whether the apply step is enabled. defaults to true on main'
+        description: "whether the apply step is enabled. defaults to true on main"
         default: ${{ github.ref == 'refs/heads/main' }}
       aws-region:
         type: string
@@ -32,7 +32,7 @@ on:
 
 jobs:
   plan:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     defaults:
       run:
         working-directory: ${{ inputs.working-directory }}
@@ -85,7 +85,7 @@ jobs:
         run: echo "${{ steps.evaluate-plan.outputs.has-changes-planned }}"
 
   apply:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     environment: ${{ inputs.github-environment }}
     needs: plan
     if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}

package/dist/practices/cicd-service/best-practice/.github/workflows/provision.yml

@@ -67,7 +67,6 @@ jobs:
     secrets:
       aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
-      open-vpn-config: ${{ secrets.DEV_OPEN_VPN_CONFIG }}
 
   sql-schema-prod:
     uses: ./.github/workflows/.sql-schema-control.yml
@@ -80,4 +79,3 @@ jobs:
     secrets:
       aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
       aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
-      open-vpn-config: ${{ secrets.PROD_OPEN_VPN_CONFIG }}

package/dist/practices/cicd-service/best-practice/package.json

@@ -0,0 +1,7 @@
+{
+  "devDependencies": {
+    "declastruct": "@declapract{check.minVersion('1.3.0')}",
+    "declastruct-aws": "@declapract{check.minVersion('1.0.3')}",
+    "declastruct-unix-network": "@declapract{check.minVersion('1.0.0')}"
+  }
+}

package/dist/practices/cicd-service/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/practices/domain/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
-    "domain-objects": "@declapract{check.minVersion('0.29.1')}",
+    "domain-objects": "@declapract{check.minVersion('0.31.0')}",
     "joi": "@declapract{check.minVersion('17.4.0')}",
-    "type-fns": "@declapract{check.minVersion('1.17.0')}"
+    "type-fns": "@declapract{check.minVersion('1.21.0')}"
   }
 }

package/dist/practices/git/best-practice/.gitignore.declapract.ts

@@ -11,6 +11,7 @@ const expectedIgnores = [
   '.terraform',
   '.terraform.lock',
   '.yalc',
+  '.temp',
   'coverage',
   'dist',
   'node_modules',

package/dist/practices/package-json-order/best-practice/package.json.declapract.ts

@@ -38,15 +38,17 @@ export const desiredRelativeKeyOrder = {
     'build:clean',
     'build:compile',
     'build',
-    'provision:docker:clear',
-    'provision:docker:prepare',
-    'provision:docker:up',
-    'provision:docker:await',
-    'provision:docker:down',
     'provision:schema:plan',
     'provision:schema:apply',
     'provision:schema:sync',
-    'provision:integration-test-db',
+    'provision:testdb:docker:clear',
+    'provision:testdb:docker:prepare',
+    'provision:testdb:docker:up',
+    'provision:testdb:docker:await',
+    'provision:testdb:docker:down',
+    'provision:testdb',
+    'start:testdb',
+    'start:livedb:dev',
     'test:commits',
     'test:types',
     'test:format:prettier',

package/dist/practices/persist-with-dynamodb/best-practice/package.json

@@ -7,9 +7,10 @@
   },
   "scripts": {
     "generate:dao:dynamodb": "npx dynamodb-dao-generator generate && npm run fix:format",
-    "provision:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
-    "provision:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down",
-    "provision:dynamodb:schema": "terraform -chdir=provision/aws/environments/test apply -auto-approve",
-    "provision:integration-test-db": "npm run provision:docker:up && npm run provision:dynamodb:schema"
+    "provision:testdb:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:testdb:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down",
+    "provision:testdb:dynamodb:schema": "terraform -chdir=provision/aws/environments/test apply -auto-approve",
+    "provision:testdb": "npm run provision:testdb:docker:up && npm run provision:testdb:dynamodb:schema",
+    "start:testdb": "npm run provision:testdb"
   }
 }

package/dist/practices/persist-with-rds/bad-practices/old-packagejson-script-names/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "provision:docker:clear": "docker rm -f $(docker ps -a -f 'publish=7821' -q) 2>/dev/null || true && echo 'ensured port is available 👍'",
+    "provision:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/integration-test-db/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/integration-test-db/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/integration-test-db/init/user.cicd.sql",
+    "provision:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:docker:await": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
+    "provision:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down"
+  }
+}

package/dist/practices/persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts

@@ -0,0 +1,22 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // do nothing if no contents
+  const packageJSON = JSON.parse(contents);
+  const updatedPackageJSON = {
+    ...packageJSON,
+    scripts: {
+      ...packageJSON.scripts,
+      'provision:docker:clear': undefined,
+      'provision:docker:prepare': undefined,
+      'provision:docker:up': undefined,
+      'provision:docker:await': undefined,
+      'provision:docker:down': undefined,
+    },
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/config/dev.json

@@ -1,20 +1,28 @@
 {
   "database": {
-    "admin": {
-      "host": "@declapract{variable.databaseClusterHost.dev}",
-      "port": 5432,
+    "target": {
       "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.cicdUser}",
-      "password": "__CHANG3_ME__"
+      "schema": "@declapract{variable.databaseName}"
     },
-    "service": {
-      "host": "@declapract{variable.databaseClusterHost.dev}",
-      "port": 5432,
-      "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.serviceUser}",
-      "password": "__CHANG3_ME__"
+    "role": {
+      "cicd": {
+        "username": "@declapract{variable.databaseUserName.cicdUser}",
+        "password": "__CHANG3_ME__"
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "__CHANG3_ME__"
+      }
+    },
+    "tunnel": {
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.dev}",
+        "port": 15432
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.dev}",
+        "port": 5432
+      }
     }
   }
 }

package/dist/practices/persist-with-rds/best-practice/config/prod.json

@@ -1,20 +1,28 @@
 {
   "database": {
-    "admin": {
-      "host": "@declapract{variable.databaseClusterHost.prod}",
-      "port": 5432,
+    "target": {
       "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.cicdUser}",
-      "password": "__PARAM__"
+      "schema": "@declapract{variable.databaseName}"
     },
-    "service": {
-      "host": "@declapract{variable.databaseClusterHost.prod}",
-      "port": 5432,
-      "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.serviceUser}",
-      "password": "__PARAM__"
+    "role": {
+      "cicd": {
+        "username": "@declapract{variable.databaseUserName.cicdUser}",
+        "password": "__PARAM__"
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "__PARAM__"
+      }
+    },
+    "tunnel": {
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.prod}",
+        "port": 15433
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.prod}",
+        "port": 5432
+      }
     }
   }
 }

package/dist/practices/persist-with-rds/best-practice/config/prod.json.declapract.ts

@@ -1,3 +1,15 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, FileFixFunction } from 'declapract';
 
 export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
+
+  return {
+    contents: JSON.stringify(
+      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
+      null,
+      2,
+    ),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/config/test.json

@@ -1,20 +1,25 @@
 {
   "database": {
-    "admin": {
-      "host": "localhost",
-      "port": 7821,
+    "target": {
       "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.cicdUser}",
-      "password": "__CHANG3_ME__"
+      "schema": "@declapract{variable.databaseName}"
     },
-    "service": {
-      "host": "localhost",
-      "port": 7821,
-      "database": "@declapract{variable.databaseName}",
-      "schema": "@declapract{variable.databaseName}",
-      "username": "@declapract{variable.databaseUserName.serviceUser}",
-      "password": "__CHANG3_ME__"
+    "role": {
+      "cicd": {
+        "username": "@declapract{variable.databaseUserName.cicdUser}",
+        "password": "__CHANG3_ME__"
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "__CHANG3_ME__"
+      }
+    },
+    "tunnel": {
+      "local": {
+        "host": "localhost",
+        "port": 7821
+      },
+      "lambda": null
     }
   }
 }

package/dist/practices/persist-with-rds/best-practice/config/test.json.declapract.ts

@@ -1,3 +1,15 @@
-import { FileCheckType } from 'declapract';
+import { FileCheckType, FileFixFunction } from 'declapract';
 
 export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
+
+  return {
+    contents: JSON.stringify(
+      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
+      null,
+      2,
+    ),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/package.json

@@ -16,14 +16,16 @@
     "generate:dao:postgres": "npx sql-dao-generator generate && npm run fix:format",
     "generate:schema": "npx sql-schema-generator generate -c codegen.sql.schema.yml && npm run fix:format",
     "generate:types-from-sql": "npx sql-code-generator generate -c codegen.sql.types.yml && npm run fix:format",
-    "provision:docker:clear": "docker rm -f $(docker ps -a -f 'publish=7821' -q) 2>/dev/null || true && echo 'ensured port is available 👍'",
-    "provision:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/integration-test-db/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/integration-test-db/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/integration-test-db/init/user.cicd.sql",
-    "provision:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
-    "provision:docker:await": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
-    "provision:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down",
     "provision:schema:plan": "npx sql-schema-control plan -c provision/schema/control.yml",
     "provision:schema:apply": "npx sql-schema-control apply -c provision/schema/control.yml",
     "provision:schema:sync": "npx sql-schema-control sync -c provision/schema/control.yml",
-    "provision:integration-test-db": "npm run provision:docker:clear && npm run provision:docker:prepare && npm run provision:docker:up && npm run provision:docker:await && npm run provision:schema:plan && npm run provision:schema:apply && npm run provision:schema:plan"
+    "provision:testdb:docker:clear": "docker rm -f $(docker ps -a -f 'publish=7821' -q) 2>/dev/null || true && echo 'ensured port is available 👍'",
+    "provision:testdb:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/integration-test-db/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/integration-test-db/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/integration-test-db/init/user.cicd.sql",
+    "provision:testdb:docker:up": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:testdb:docker:await": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
+    "provision:testdb:docker:down": "docker compose -f ./provision/docker/integration-test-db/docker-compose.yml down",
+    "provision:testdb": "npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && npm run provision:schema:plan && npm run provision:schema:apply && npm run provision:schema:plan",
+    "start:testdb": "npm run provision:testdb",
+    "start:livedb:dev": "echo 'will ping the database until assured its not asleep' && STAGE=dev .agent/repo=.this/skills/use.rds.capacity.sh"
   }
 }

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

@@ -4,20 +4,19 @@ const configInstance = new Config();
 const getConfig = async () =>
   configInstance.get(process.env.STAGE || undefined);
 
-const promiseSchemaControlConfig = async () => {
+const promiseSchemaControlCredentials = async () => {
   const config = await getConfig();
-  const dbConfig = config.database.admin; // NOTE: schema control must have DDL privileges
-  const schemaControlConfig = {
-    host: dbConfig.host,
-    port: dbConfig.port,
-    database: dbConfig.schema, // i.e., db = schema
-    schema: dbConfig.schema,
-    username: dbConfig.username,
-    password: dbConfig.password,
+  const credentials = {
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    database: config.database.target.database, // i.e., db = schema
+    schema: config.database.target.schema,
+    username: config.database.role.cicd.username,
+    password: config.database.role.cicd.password,
   };
-  return schemaControlConfig;
+  return credentials;
 };
 
 module.exports = {
-  promiseConfig: promiseSchemaControlConfig,
+  promiseConfig: promiseSchemaControlCredentials,
 };

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

@@ -54,7 +54,7 @@ fi;
 
 
 # define the postgres connecition string
-CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseClusterHost.prod}" || echo "@declapract{variable.databaseClusterHost.dev}");
+CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseTunnelHost.prod}" || echo "@declapract{variable.databaseTunnelHost.dev}");
 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}

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

@@ -0,0 +1,26 @@
+  database: {
+    target: {
+      database: string;
+      schema: string;
+    };
+    role: {
+      cicd: {
+        username: string;
+        password: string;
+      };
+      crud: {
+        username: string;
+        password: string;
+      };
+    };
+    tunnel: {
+      local: {
+        host: string;
+        port: number;
+      };
+      lambda: {
+        host: string;
+        port: number;
+      } | null;
+    };
+  };

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

@@ -0,0 +1,39 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+export const check = FileCheckType.CONTAINS; // practice must contain this
+
+const variantsToReplace = [
+  `
+  database: {
+    service: {
+      host: string;
+      port: number;
+      database: string;
+      schema: string;
+      username: string;
+      password: string;
+    };
+  };
+  `.trim(),
+];
+
+export const fix: FileFixFunction = (contents, context) => {
+  // if no contents yet, can't fix
+  if (!contents) return { contents };
+
+  // otherwise, try and fix with one of the variants we support
+  const desiredContents = variantsToReplace.reduce(
+    (contentsNow, thisVariant) =>
+      contentsNow?.replace(
+        thisVariant,
+        context.declaredFileContents?.trim() ??
+          UnexpectedCodePathError.throw(
+            'expected to have declared best practice but found null',
+            { context },
+          ),
+      ),
+    contents,
+  );
+  return { contents: desiredContents };
+};

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

@@ -1,6 +1,8 @@
+import { HelpfulError, UnexpectedCodePathError } from 'helpful-errors';
 import pg, { Client, QueryResult, QueryResultRow } from 'pg';
 
 import { getConfig } from '../config/getConfig';
+import { environment } from '../environment';
 
 // https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
 pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
@@ -14,7 +16,7 @@ export interface DatabaseConnection {
   end: () => Promise<void>;
 }
 
-export class DatabaseQueryError extends Error {
+export class DatabaseQueryError extends HelpfulError {
   constructor({
     sql,
     values,
@@ -33,27 +35,46 @@ sql:
 values:
   ${JSON.stringify(values)}
     `.trim();
-    super(message);
+    super(message, { sql, values, cause: caught });
   }
 }
 
 export const getDatabaseConnection = async (): Promise<DatabaseConnection> => {
   const config = await getConfig();
-  const dbConfig = config.database.service;
+  const target = config.database.target;
+  const role = config.database.role.crud;
+
+  // determine which tunnel to use based on environment.server
+  const tunnel =
+    environment.server === 'AWS:LAMBDA'
+      ? config.database.tunnel.lambda
+      : config.database.tunnel.local;
+
+  // ensure tunnel is defined for the requested server
+  if (!tunnel) {
+    throw new UnexpectedCodePathError(
+      `Database tunnel not configured for environment.server + env.access`,
+      { environment },
+    );
+  }
+
+  // instantiate the client
   const client = new Client({
-    host: dbConfig.host,
-    user: dbConfig.username,
-    password: dbConfig.password,
-    database: dbConfig.schema,
-    port: dbConfig.port,
+    host: tunnel.host,
+    port: tunnel.port,
+    user: role.username,
+    password: role.password,
+    database: target.database,
   });
   await client.connect();
-  await client.query(`SET search_path TO ${dbConfig.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
+  await client.query(`SET search_path TO ${target.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
   const dbConnection = {
     query: ({ sql, values }: { sql: string; values?: (string | number)[] }) =>
       client.query(sql, values),
     end: () => client.end(),
   };
+
+  // declare our interface
   return {
     query: (args: { sql: string; values?: any[] }) =>
       dbConnection.query(args).catch((error) => {

package/dist/practices/provision-github/best-practice/package.json

@@ -1,6 +1,6 @@
 {
   "devDependencies": {
-    "declastruct": "@declapract{check.minVersion('1.1.7')}",
-    "declastruct-github": "@declapract{check.minVersion('1.1.1')}"
+    "declastruct": "@declapract{check.minVersion('1.3.0')}",
+    "declastruct-github": "@declapract{check.minVersion('1.0.3')}"
   }
 }

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

@@ -4,7 +4,7 @@
     "jest": "@declapract{check.minVersion('29.3.1')}",
     "test-fns": "@declapract{check.minVersion('1.4.2')}",
     "ts-jest": "@declapract{check.minVersion('29.4.5')}",
-    "ts-node": "@declapract{check.minVersion('10.9.2')}",
+    "tsx": "@declapract{check.minVersion('4.20.6')}",
     "core-js": "@declapract{check.minVersion('3.26.1')}",
     "@babel/core": "@declapract{check.minVersion('7.28.5')}",
     "@babel/preset-env": "@declapract{check.minVersion('7.28.5')}",

package/dist/practices/typescript/best-practice/tsconfig.build.json

@@ -4,13 +4,14 @@
     "rootDir": "src"
   },
   "include": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "nontyped_modules/**/*.d.ts"
   ],
   "exclude": [
-    "**/*.test.(ts|js)", // all explicitly .test files are dev only assets too
-    "**/.test/**/*.(ts|js)",
-    "src/**/.scratch/**/*.(ts|js)",
-    "src/**/__test_utils__/**/*.(ts|js)",
-    "src/**/__test_assets__/**/*.(ts|js)"
+    "**/*.test.ts", // all explicitly .test files are dev only assets too
+    "**/*.test.js",
+    "**/.test/**/*",
+    "**/.scratch/**/*",
+    "**/__test*__/**/*" // todo: deprecate this pattern in favor of .test
   ]
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -44,7 +44,7 @@
     "domain-objects": "0.29.2",
     "expect": "29.4.2",
     "flat": "5.0.2",
-    "helpful-errors": "1.3.8",
+    "helpful-errors": "1.5.3",
     "simple-log-methods": "0.5.0"
   },
   "peerDependencies": {