declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/deploy-database-gerunds.declapract.integration.test.ts.snap

@@ -0,0 +1,102 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds deploy.database.sh gerund-free given: the shipped deploy.database.sh when: the template body is read then: the emitted deploy.database.sh matches snapshot: deploy.database.sh 1`] = `
+"#####################################################
+## 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/cicd-service/declarations/practices/persist-with-rds/__snapshots__/provision-testdb-access.declapract.integration.test.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds provision:testdb access given: the shipped best-practice package.json when: the provision:testdb chain is read then: the emitted provision:testdb chain matches snapshot: provision:testdb chain 1`] = `"npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && ACCESS=test npm run provision:schema:plan && ACCESS=test npm run provision:schema:apply && ACCESS=test npm run provision:schema:plan"`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/ssm-cicd-param-names.declapract.integration.test.ts.snap

@@ -0,0 +1,10 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`persist-with-rds ssm cicd param names are slash-path, tierless given: [case1] the two cicd credentials when: [t0] resources.parameters.ts is read then: the emitted cicd + crud param-name lines match snapshot: ssm cicd + crud param names 1`] = `
+[
+  "*         with NO tier segment — \`parameter/<star>/svc-<star>/database/role/cicd/for-plan/<star>\`",
+  "secret({ name: \`\${namespace}.database.role.crud.password\` }),",
+  "name: \`/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-plan/password\`,",
+  "name: \`/@declapract{variable.organizationName}/@declapract{variable.projectName}/database/role/cicd/for-apply/password\`,",
+]
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/__snapshots__/testdb-preflight-failloud.declapract.integration.test.ts.snap

@@ -0,0 +1,30 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`testdb preflight fails loud (#589) given: the shipped wait-for-postgres preflight probe when: [t4] the shipped probe is vibechecked as a whole then: the emitted wait-for-postgres.sh matches snapshot: wait-for-postgres.sh preflight probe 1`] = `
+"#!/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/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/provision/schema/sql/init/database.sql.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/provision/schema/sql/init/extensions.sql.declapract.ts

@@ -0,0 +1,13 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+// for this one, we want to move the file, not just delete it, since it may have had customizations
+export const fix: FileFixFunction = (_, context) => {
+  return {
+    relativeFilePath: context.relativeFilePath.replace(
+      '/extensions.sql',
+      '/.extensions.sql',
+    ),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/provision/schema/sql/init/schema.sql.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/provision/schema/sql/init/user.cicd.sql.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/provision/schema/sql/init/user.datalakedb.sql.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/non-prefixed-manual-init-sqls/readme.md

@@ -0,0 +1,5 @@
+we have several files that are not automatically managed by `sql-schema-control` and must be applied manually with superuser privileges
+
+to make the distinction between these and the files that _are_ managed by `sql-schema-control`, we've adopted the convention that the ones that need to be applied manually with `superuser` privs are prefixed with a `.`
+
+this practice checks for the case where we didn't have the prefix - and fixes it by prefixing the files for us

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-config-file-names/codegen.sql.yml.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-dev-config-location/config/dev.json.declapract.ts

@@ -0,0 +1,33 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+import { asPrepConfigPath } from '../../../../../utils/asPrepConfigPath';
+import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToPrep';
+
+export const check = FileCheckType.EXISTS;
+
+/**
+ * .what = rewrite the rds password placeholder `"__CHANG3_ME__"` to the aws-param reference.
+ * .why  = the rds config twin adds this one transform the config twin lacks; a named op keeps the
+ *         declarer's `fix` a what-not-how read (rule.require.named-transformers).
+ */
+const withAwsParamPlaceholder = (input: { contents: string }): string =>
+  input.contents.replace(/"__CHANG3_ME__"/g, '"$.at(aws::param)"');
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
+  // both halves are shared utils (one source for both declarers): migrateDevConfigToPrep
+  // owns the content migration, asPrepConfigPath owns the relocate. this declarer adds the
+  // rds-only aws-param placeholder rewrite on top.
+  const updatedContents = contents
+    ? withAwsParamPlaceholder({
+        contents: migrateDevConfigToPrep({ contents }),
+      })
+    : contents;
+
+  return {
+    contents: updatedContents ?? null,
+    relativeFilePath: asPrepConfigPath({
+      relativeFilePath: context.relativeFilePath,
+    }),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-dir/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration_test_db` to `provision/docker/testdb`

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-dir/provision/docker/integration_test_db/<star><star>/<star>.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice
+
+export const fix: FileFixFunction = async (contents, { relativeFilePath }) => {
+  // Move from integration_test_db to testdb
+  const newPath = relativeFilePath.replace(
+    'provision/docker/integration_test_db',
+    'provision/docker/testdb',
+  );
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-hyphen-dir/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration-test-db` to `provision/docker/testdb`

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-hyphen-dir/provision/docker/integration-test-db/<star><star>/<star>.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice
+
+export const fix: FileFixFunction = async (contents, { relativeFilePath }) => {
+  // Move from integration-test-db to testdb
+  const newPath = relativeFilePath.replace(
+    'provision/docker/integration-test-db',
+    'provision/docker/testdb',
+  );
+  return {
+    contents,
+    relativeFilePath: newPath,
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/.declapract.readme.md

@@ -0,0 +1 @@
+we switched from `provision/docker/integration-test-db` to `provision/docker/testdb` - this detects old paths in package.json scripts

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/package.json

@@ -0,0 +1,8 @@
+{
+  "scripts": {
+    "provision:testdb:docker:prepare": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:up": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:await": "@declapract{check.contains('integration-test-db')}",
+    "provision:testdb:docker:down": "@declapract{check.contains('integration-test-db')}"
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-integration-test-db-paths/package.json.declapract.ts

@@ -0,0 +1,10 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents }; // do nothing if no contents
+  // Replace integration-test-db with testdb in all paths
+  const fixed = contents.replace(/integration-test-db/g, 'testdb');
+  return { contents: fixed };
+};

package/dist/.test/assets/cicd-service/declarations/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/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts

@@ -0,0 +1,22 @@
+import { FileCheckType, type 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/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/old-param-placeholder/config/<star>.json.declapract.ts

@@ -0,0 +1,14 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('__PARAM__')) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  return {
+    contents: contents.replace(/"__PARAM__"/g, '"$.at(aws::param)"'),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/.declapract.readme.md

@@ -0,0 +1 @@
+provision/schema/entities -> provision/schema/domain

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/provision/schema/entities/<star>.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (_, context) => {
+  return {
+    relativeFilePath: context.relativeFilePath.replace(
+      /provision\/schema\/entities\//g,
+      'provision/schema/domain/',
+    ),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/schema-entities-dir/provision/schema/sql/entities.yml.declapract.ts

@@ -0,0 +1,13 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (_, context) => {
+  return {
+    // rename file to "domain.yml"
+    relativeFilePath: context.relativeFilePath.replace(
+      /entities\.yml$/,
+      'domain.yml',
+    ),
+  };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.declapract.integration.test.ts

@@ -0,0 +1,88 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the terraform-parameters forget, run through the REAL
+ *   declapract apply pipeline against a genTempDir clone of a consumer repo.
+ * .why = the bad-practice fix must rewrite every `resource "aws_ssm_parameter"` into
+ *   a `removed{}` forget block (never a destroy), and drop the `data` seed-reads —
+ *   so terraform lets go of the params without loss of the live value. the
+ *   go-forward declastruct wish declares its own names separately; the OLD names
+ *   here are simply orphaned (forgotten from terraform, not adopted by declastruct).
+ * .note = the terraform file is snapshotted in full (before AND after) so a reviewer
+ *   can eyeball the exact end-state, per rule.require.declapract-integration-tests.
+ */
+describe('terraform-parameters forget', () => {
+  given(
+    '[case1] a repo with terraform-managed ssm params',
+    () => {
+      const tempDir = genTempDir({
+        slug: 'declapract-terraform-parameters',
+        clone: './src/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm',
+        symlink: [{ at: 'src', to: 'src' }],
+      });
+
+      const tfPath = 'provision/aws/product/parameter-store.tf';
+      const read = (relativePath: string) =>
+        fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+      const applyForget = () =>
+        executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'persist-with-rds',
+          file: tfPath,
+        });
+
+      when('[t0] the migration input (before any fix)', () => {
+        then('the terraform input matches snapshot', async () => {
+          expect(await read(tfPath)).toMatchSnapshot(
+            'parameter-store.tf — before',
+          );
+        });
+      });
+
+      when('[t1] the bad-practice forget fix is applied', () => {
+        useThen('forget the terraform params', async () => applyForget());
+
+        then(
+          'the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot',
+          async () => {
+            const tf = await read(tfPath);
+            expect(tf).not.toContain('resource "aws_ssm_parameter"');
+            expect(tf).not.toContain('data "aws_ssm_parameter"');
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_database_role_crud_password',
+            );
+            expect(tf).toContain(
+              'from = aws_ssm_parameter.secret_twilio_authToken',
+            );
+            expect(tf).toContain('destroy = false');
+            // full content, for the reviewer's eye
+            expect(tf).toMatchSnapshot('parameter-store.tf — after');
+          },
+        );
+      });
+
+      when('[t2] the forget fix is applied a second time (idempotency)', () => {
+        // capture the post-first-forget state, apply again, capture again — assert
+        // zero change. the forget regex must not re-match its own removed{} output
+        // (per rule.require.idempotent-fixes).
+        const passes = useThen(
+          'a second forget over its own output',
+          async () => {
+            const before = await read(tfPath); // post-first-forget
+            await applyForget(); // second apply
+            const after = await read(tfPath);
+            return { before, after };
+          },
+        );
+
+        then('the second forget is a no-op', () => {
+          expect(passes.after).toEqual(passes.before);
+        });
+      });
+    },
+  );
+});

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.declare.yml

@@ -0,0 +1,4 @@
+declare:
+  examples: src/examples
+  practices: src/practices
+  use-cases: src/useCases.yml

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/declapract.use.yml

@@ -0,0 +1,18 @@
+declarations: './'
+useCase: lambda-service-with-rds
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  databaseName: 'testdb'
+  databaseUserName:
+    cicdUser: 'testdb_cicd'
+    serviceUser: 'testdb_service'
+  databaseTunnelHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  databaseClusterHost:
+    prep: 'localhost'
+    prod: 'localhost'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/.test/assets/demo-repo-with-terraform-ssm/provision/aws/product/parameter-store.tf

@@ -0,0 +1,23 @@
+data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,44 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t0] the migration input (before any fix) then: the terraform input matches snapshot: parameter-store.tf — before 1`] = `
+"data "aws_ssm_parameter" "legacy_admin_password" {
+  name            = "\${local.parameter_store_namespace}.database.admin.password"
+  count           = var.environment == "prod" ? 1 : 0
+  with_decryption = true
+}
+resource "aws_ssm_parameter" "secret_database_role_crud_password" {
+  name  = "\${local.parameter_store_namespace}.database.role.crud.password"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+resource "aws_ssm_parameter" "secret_twilio_authToken" {
+  name  = "\${local.parameter_store_namespace}.twilio.authToken"
+  type  = "SecureString"
+  value = "__IGNORED__"
+  tags  = local.tags
+  lifecycle {
+    ignore_changes = [value]
+  }
+}
+"
+`;
+
+exports[`terraform-parameters forget given: [case1] a repo with terraform-managed ssm params when: [t1] the bad-practice forget fix is applied then: the terraform file holds only removed{} forget blocks (no resource/data blocks) and matches snapshot: parameter-store.tf — after 1`] = `
+"removed {
+  from = aws_ssm_parameter.secret_database_role_crud_password
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+removed {
+  from = aws_ssm_parameter.secret_twilio_authToken
+  lifecycle {
+    destroy = false # forget from state; keep the live param
+  }
+}
+"
+`;

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/terraform-parameters/provision/aws/product/parameter-store.tf.declapract.ts

@@ -0,0 +1,55 @@
+import { type FileCheckFunction, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = terraform must not manage SSM parameters — they belong to declastruct-aws
+ *   now (provision/aws/resources.parameters.ts).
+ * .why = terraform managed these via the `__IGNORED__` + `ignore_changes = [value]`
+ *   workaround, which hid drift and forced the secret through terraform state. the
+ *   real values live ONLY in aws (seeded once), so a plain resource-block delete
+ *   would issue DeleteParameter = permanent loss. the fix instead rewrites each
+ *   `resource "aws_ssm_parameter"` into a `removed{}` forget block (`destroy = false`)
+ *   — terraform drops it from state and preserves the live value. requires terraform
+ *   >= 1.7 for the `removed{}` block.
+ *
+ * .pair = this bad-practice removes terraform's ownership; the best-practice
+ *   provision/aws/resources.parameters.ts declares the declastruct owner (value-less
+ *   write-only KEEP — it adopts the live values terraform seeded). declare the wish
+ *   BEFORE this forget lands so declastruct owns every param first.
+ */
+
+// bad practice detected while terraform still declares an ssm parameter resource.
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('resource "aws_ssm_parameter"')) return; // detected
+  throw new Error(
+    'no terraform-managed ssm parameter resources; not the terraform-parameters bad practice',
+  );
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+
+  // drop the `data "aws_ssm_parameter"` reads — they existed only to seed values
+  // that declastruct-aws now owns.
+  const withoutDataReads = contents.replace(
+    /data\s+"aws_ssm_parameter"\s+"\w+"\s*\{[\s\S]*?\n\}\n?/g,
+    '',
+  );
+
+  // rewrite each `resource "aws_ssm_parameter" "<label>" { ... }` into a forget
+  // block. `[\s\S]*?\n\}` stops at the first column-0 `}` (the block close); the
+  // indented `  }` of a nested lifecycle block never matches, so the nest is safe.
+  const withForgetBlocks = withoutDataReads.replace(
+    /resource\s+"aws_ssm_parameter"\s+"(\w+)"\s*\{[\s\S]*?\n\}/g,
+    (_match, label) =>
+      [
+        `removed {`,
+        `  from = aws_ssm_parameter.${label}`,
+        `  lifecycle {`,
+        `    destroy = false # forget from state; keep the live param`,
+        `  }`,
+        `}`,
+      ].join('\n'),
+  );
+
+  return { contents: withForgetBlocks };
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/.declapract.readme.md

@@ -0,0 +1 @@
+withDatabaseConnection -> withDatabaseContext, per procedure-fns pattern

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/bad-practices/with-connection-in-input/src/utils/database/withDatabaseConnection.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS; // if a file exists with this path pattern, then it's bad practice