declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/.declapract.readme.md

@@ -0,0 +1,58 @@
+we use:
+- postgres database
+  - provisioned by aws rds aurora when in prep and prod env
+  - provisioned by docker when in test env
+- sql-schema-control to manage sql schema
+- sql-dao-generator to generate the sql-schemas + daos
+
+## required variables
+
+| variable | description | example |
+|----------|-------------|---------|
+| `databaseTunnelHost.{prep,prod}` | ssm proxy host for database tunnel | `aws.ssmproxy.ahbodedb.prep` |
+| `databaseClusterHost.{prep,prod}` | rds cluster endpoint | `ahbodedb.cluster-xxx.us-east-1.rds.amazonaws.com` |
+
+## ssm parameters
+
+terraform provisions these ssm parameters for database credentials:
+
+| parameter name | description | environments |
+|----------------|-------------|--------------|
+| `{namespace}.database.role.cicd.password` | password for cicd database user | prep, prod |
+| `{namespace}.database.role.crud.password` | password for crud database user | prep, prod |
+
+legacy parameters (kept for backwards compatibility):
+- `{namespace}.database.admin.password`
+- `{namespace}.database.service.password`
+
+## a stateful store gets an alias, never a copy, across the dual-publish transition
+
+the `serverless` + `environments` practices dual-publish each lambda fleet under both slugs
+(`-dev-` ancient, `-prep-` contemp) through the `-dev-`→`-prep-` slug transition. a stateless lambda
+is safe under two names. a stateful store is not.
+
+this RDS cluster (and its SSM credential params, its S3 buckets, its SQS queues) stays one store
+reached by two pointers — a Route53 CNAME, an SSM pointer, or an ARN — never two clusters.
+
+a second `-prep-` RDS cluster is never stood up to satisfy dual-publish. two independent clusters
+form a write-`-dev-`/read-`-prep-` split: the ancient fleet writes one, the contemp fleet reads the
+other, and the divergence stays silent until data is absent. the alias points at the one cluster.
+
+no data migration is needed: the runtime DB path resolves `config.database.tunnel.lambda.host` (see
+`src/utils/database/getOneDatabaseConnection.ts`), an access-keyed config value
+(`databaseClusterHost.{prep,prod}`) with no deploy-slug token, so a CNAME re-points the one live
+cluster with zero data moved. which alias mechanism to use is unsettled; the invariant "one store, two
+pointers" holds regardless.
+
+## the provision workflow's rds jobs are gated behind this practice (D28)
+
+`cicd-service`'s `provision.yml` carries 4 rds-coupled jobs — `sql-schema-{prep,prod}` (the
+`.sql-schema-control.yml` callee, driven by this practice's schema + daos) and
+`aws-{prep,prod}-declastruct` (the `provision/aws/resources.ts` wish this practice ships). the gate
+lives in `cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts`: a usecase-aware
+`contents` fn emits those 4 jobs **only** when `persist-with-rds` is in the resolved practice set, so
+a service **without** rds (`lambda-service`, `lambda-service-with-dynamodb`) does not inherit a
+`provision` workflow that references files it lacks. it uses `CONTAINS`, not `EQUALS`, so a narrow
+`declapract fix --practice cicd-service` cannot strip an rds repo's own jobs (the additive-delta
+EQUALS hazard). if you add a new rds-coupled provision job, add it to that gate the same way — a
+caller that names a callee this practice supplies must be reconciled against this practice's presence.

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/codegen.sql.dao.yml

@@ -0,0 +1,18 @@
+language: postgres
+dialect: 10.7
+generates:
+  daos:
+    to: src/access/daos
+    using:
+      log: src/utils/logger#log
+      DatabaseConnection: src/utils/database/getOneDatabaseConnection#DatabaseConnection
+  schema:
+    config: codegen.sql.schema.yml
+  control:
+    config: provision/schema/control.yml
+  code:
+    config: codegen.sql.types.yml
+for:
+  objects:
+    search:
+      - 'src/domain.objects/*.ts'

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/codegen.sql.dao.yml.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/codegen.sql.schema.yml

@@ -0,0 +1,6 @@
+language: postgres
+dialect: 10.7
+declarations: provision/schema/domain/index.ts
+generates:
+  sql:
+    to: provision/schema/sql

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/codegen.sql.types.yml

@@ -0,0 +1,16 @@
+language: postgres
+dialect: 10.7
+resources: # where to find your tables, functions, views, procedures
+  - 'provision/schema/sql/tables/**/*.sql'
+  - 'provision/schema/sql/views/**/*.sql'
+  - 'provision/schema/sql/functions/**/*.sql'
+queries: # where to find your queries (each file must `export const query = `...`);
+  - 'src/access/daos/**/*.ts'
+  - '!src/access/daos/**/index.ts'
+  - '!src/access/daos/**/castFromDatabaseObject.ts'
+  - '!src/access/daos/**/findByRef.ts'
+  - '!src/**/*.test.ts'
+  - '!src/**/*.test.integration.ts'
+generates: # where to output the generated code
+  types: src/access/daos/.generated/types.ts
+  queryFunctions: src/access/daos/.generated/queryFunctions.ts

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/config/prep.json

@@ -0,0 +1,36 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "$.at(aws::param)"
+      }
+    },
+    "tunnel": {
+      "bastion": "vpc-main-bastion",
+      "cluster": "@declapract{variable.databaseName}",
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.prep}",
+        "port": 15432
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.prep}",
+        "port": 5432
+      }
+    }
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/config/prep.json.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type 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/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/config/prod.json

@@ -0,0 +1,36 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "$.at(aws::param)"
+        }
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "$.at(aws::param)"
+      }
+    },
+    "tunnel": {
+      "bastion": "vpc-main-bastion",
+      "cluster": "@declapract{variable.databaseName}",
+      "local": {
+        "host": "@declapract{variable.databaseTunnelHost.prod}",
+        "port": 15433
+      },
+      "lambda": {
+        "host": "@declapract{variable.databaseClusterHost.prod}",
+        "port": 5432
+      }
+    }
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/config/prod.json.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type 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/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/config/test.json

@@ -0,0 +1,33 @@
+{
+  "database": {
+    "target": {
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}"
+    },
+    "role": {
+      "cicd": {
+        "for-plan": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "__CHANG3_ME__"
+        },
+        "for-apply": {
+          "username": "@declapract{variable.databaseUserName.cicdUser}",
+          "password": "__CHANG3_ME__"
+        }
+      },
+      "crud": {
+        "username": "@declapract{variable.databaseUserName.serviceUser}",
+        "password": "__CHANG3_ME__"
+      }
+    },
+    "tunnel": {
+      "bastion": "vpc-main-bastion",
+      "cluster": "@declapract{variable.databaseName}",
+      "local": {
+        "host": "localhost",
+        "port": 7821
+      },
+      "lambda": null
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+import { FileCheckType, type 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/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/package.json

@@ -0,0 +1,30 @@
+{
+  "dependencies": {
+    "pg": "@declapract{check.minVersion('8.3.0')}",
+    "yesql": "@declapract{check.minVersion('3.2.2')}"
+  },
+  "devDependencies": {
+    "sql-code-generator": "@declapract{check.minVersion('0.10.2')}",
+    "sql-dao-generator": "@declapract{check.minVersion('0.13.1')}",
+    "sql-schema-control": "@declapract{check.minVersion('1.8.1')}",
+    "sql-schema-generator": "@declapract{check.minVersion('0.26.1')}",
+    "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
+    "@types/pg": "@declapract{check.minVersion('8.6.1')}"
+  },
+  "scripts": {
+    "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: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:testdb:docker:clear": "for port in $(docker compose -f ./provision/docker/testdb/docker-compose.yml config --format json | jq -r '.services[].ports[]?.published'); do docker rm -f $(docker ps -a -f \"publish=$port\" -q) 2>/dev/null || true; done && echo 'ensured ports are available 👍'",
+    "provision:testdb:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/testdb/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/testdb/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/testdb/init/user.cicd.sql",
+    "provision:testdb:docker:up": "docker compose -f ./provision/docker/testdb/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:testdb:docker:await": "docker compose -f ./provision/docker/testdb/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
+    "provision:testdb:docker:down": "docker compose -f ./provision/docker/testdb/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 && ACCESS=test npm run provision:schema:plan && ACCESS=test npm run provision:schema:apply && ACCESS=test npm run provision:schema:plan",
+    "start:testdb": "npm run provision:testdb",
+    "start:livedb:prep": "rhx use.rds.capacity --env prep"
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/package.json.declapract.ts

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

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/aws/readme.md

@@ -0,0 +1,79 @@
+# provision / aws
+
+the declastruct-aws wish for this service's aws resources.
+
+- `resources.ts` — the wish entrypoint (providers + `getResources`).
+- `resources.parameters.ts` — the secret SSM parameters, adopted from terraform.
+- `product/parameter-store.tf` — the terraform FORGET blocks (transitional).
+
+## why declastruct-aws, not terraform
+
+terraform managed these secrets with the `__IGNORED__` + `ignore_changes = [value]`
+workaround: the value was written once at seed, then terraform pretended it never
+drifted. that hides real drift and forces the secret through terraform state.
+
+`DeclaredAwsSsmParameterSecure` is **write-only by contract**:
+
+| phase | reads value? | kms | api |
+| ----- | ------------ | --- | --- |
+| plan  | never        | no kms:Decrypt | DescribeParameters (metadata only) |
+| apply | only when a value is supplied | kms:Encrypt | PutParameter |
+
+## adoption by absence (no seed machinery)
+
+the go-forward params ALREADY hold their values in aws — terraform seeded them once,
+and the values live only there. so the wish supplies **no `value`**: a value-less
+secret is write-only KEEP. plan reports KEEP for every extant param and never reads or
+rewrites it. there is no value to "move" or "seed" — adoption is pure KEEP.
+
+- a **CREATE at plan** means the declared name does not match a live param → STOP and
+  fix the name.
+- a value-less secret that is **ABSENT** throws on apply (declastruct-aws
+  `setSsmParameterSecure`). the wish declares the db-role creds for every tier with no
+  per-tier conditional; only prep + prod apply it (there is no `aws-test-declastruct`
+  provision job), so the absent-throw never triggers in test.
+
+## iam boundary (the two oidc roles)
+
+the prod oidc plan/apply split (see `.github/workflows/.declastruct.yml`, the aws-auth
+path) maps onto the write-only contract exactly:
+
+- **plan role** (`CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN`): `ssm:DescribeParameters` +
+  `ssm:ListTagsForResource` only. NO `ssm:GetParameter`, NO `kms:Decrypt` — it
+  reconciles metadata. its ONE decrypt exception is the
+  `/{org}/{project}/database/role/cicd/for-plan/password` credential — a SLASH path with
+  no tier segment, byte-identical to the arn the policy pins.
+- **apply role** (`CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN`): `ssm:PutParameter` +
+  `kms:Encrypt` (default `aws/ssm` key) + the tag write perms. never needs decrypt.
+
+the param **name** is the join point: config's reader, the oidc iam policy, and the
+declared `name` must be byte-identical. do NOT reshape the path.
+
+## the prep→dev name cast
+
+terraform seeded these params under `var.environment`, where the prep account carries
+the legacy `dev` label (see `define.infrastructure-dev-vs-application-prep`). the live
+CRUD param name contains that literal `dev`, so `resources.parameters.ts` casts the
+dotted crud namespace prep→dev. the two cicd names do NOT cast — they are slash paths
+with no tier segment at all (the aws ACCOUNT separates prep from prod, and the plan
+role's iam pin omits a tier), so they stay byte-identical across every tier. tags do
+NOT cast either — they conform to the access vocab (`prep`), so the first apply
+reconciles the live `environment` tag dev→prep (a metadata-only change, no value write).
+
+## order of operations (once per env — prep, then prod)
+
+the handoff is lossless because terraform forgets the param without a destroy of the
+live value. run ONCE per env, in order:
+
+1. apply the `terraform-parameters` bad-practice (`declapract fix`) — it rewrites every
+   `resource "aws_ssm_parameter"` in `product/parameter-store.tf` into a `removed{}`
+   forget block (`destroy = false`) and drops the `data` reads. requires terraform
+   >= 1.7 (bump `versions.tf#required_version` if below).
+2. `terraform apply` (the `aws-*-terraform` provision jobs) — terraform drops the
+   params from state; live values untouched. 🚩 if the plan shows any
+   `DeleteParameter`, STOP — the forget is wrong.
+3. declastruct plan/apply the wish (the `aws-*-declastruct` provision jobs) — plan
+   shows KEEP for every param (no decrypt). a CREATE means a name mismatch → STOP.
+
+after both land in every env, the `removed{}` blocks (and this transitional tf file)
+can be pruned in a follow-up.

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/aws/resources.parameters.ts

@@ -0,0 +1,106 @@
+import { DeclaredAwsSsmParameterSecure } from 'declastruct-aws';
+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.
+ */
+
+/**
+ * .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.
+ */
+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;
+
+/**
+ * .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).
+ */
+const secret = (input: { name: string }): DeclaredAwsSsmParameterSecure =>
+  DeclaredAwsSsmParameterSecure.as({
+    name: input.name,
+    keyId: null, // default aws/ssm key (matches the terraform resources)
+    description: null,
+    tags: {
+      app: '@declapract{variable.organizationName}',
+      environment: access,
+      product: '@declapract{variable.projectName}',
+    },
+    // no `value` → write-only KEEP: adopt the live value, never read or rewrite it
+  });
+
+/**
+ * .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.
+ */
+export const getAllParameters = (input: {
+  accessSlug: 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}`;
+
+  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`,
+    }),
+  ];
+};

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/aws/resources.ts

@@ -0,0 +1,30 @@
+import type { DeclastructProvider } from 'declastruct';
+import { getDeclastructAwsProvider } from 'declastruct-aws';
+import type { DomainEntity } from 'domain-objects';
+import { genLogMethods } from 'sdk-logs';
+
+import { getAllParameters } from './resources.parameters';
+
+/**
+ * .what = the declastruct wish for this service's aws resources.
+ * .why = declastruct-aws owns the ssm parameters that terraform now forgets (see
+ *        provision/aws/product/parameter-store.tf). the plan role reconciles secrets
+ *        without any ssm:GetParameter or kms:Decrypt; apply writes via PutParameter +
+ *        kms:Encrypt.
+ * .name = `getProviders` + `getResources` are declastruct's REQUIRED wish entrypoint names, so
+ *         both are exempt from the get-set-gen One/All cardinality rule (a `getAll*` rename makes
+ *         declastruct find no entrypoint — the wish dies). external-framework contract names.
+ */
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  await getDeclastructAwsProvider(
+    {},
+    {
+      // MUST be an sdk-logs logger — the DAOs read log._.level via as-procedure
+      log: genLogMethods(),
+    },
+  ),
+];
+
+export const getResources = async (): Promise<DomainEntity<any>[]> =>
+  getAllParameters({ accessSlug: null });

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/build-image.dockerfile

@@ -0,0 +1,7 @@
+FROM postgres:13.20
+
+COPY init/ /docker-entrypoint-initdb.d/
+
+ADD wait-for-postgres.sh /root/
+RUN chmod +x /root/wait-for-postgres.sh
+

package/dist/.test/assets/cicd-service/declarations/practices/persist-with-rds/best-practice/provision/docker/testdb/docker-compose.yml

@@ -0,0 +1,18 @@
+version: '3'
+services:
+  postgres:
+    build:
+      context: .
+      dockerfile: build-image.dockerfile
+    container_name: @declapract{variable.databaseName}
+    command: postgres -c 'max_connections=500'
+    ports:
+      - 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']
+      interval: 5s
+      timeout: 5s
+      retries: 5

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

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

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

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

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * .what = database credentials for sql-schema-control
+ * .why = reuses app's getConfig for consistent config resolution
+ */
+require('esbuild-register');
+const { getConfig } = require('../../src/utils/config/getConfig');
+
+const promiseSchemaControlCredentials = async () => {
+  const config = await getConfig();
+
+  // select the cicd grant to connect as; default to for-apply (full/write access).
+  // the plan job opts down to the readonly for-plan grant via GRANT=plan.
+  const grant = process.env.GRANT === 'plan' ? 'for-plan' : 'for-apply';
+  const role = config.database.role.cicd[grant];
+
+  const credentials = {
+    host: config.database.tunnel.local.host,
+    port: config.database.tunnel.local.port,
+    database: config.database.target.database,
+    schema: config.database.target.schema,
+    username: role.username,
+    password: role.password,
+  };
+  return credentials;
+};
+
+module.exports = {
+  promiseConfig: promiseSchemaControlCredentials,
+};

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

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