declapract-typescript-ehmpathy 0.49.11 → 0.49.13

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

@@ -0,0 +1,154 @@
+name: .sql-schema-control
+
+on:
+  workflow_call:
+    inputs:
+      access:
+        type: string
+        description: "the access to execute with (test | prep | prod)"
+        required: true
+      github-environment-plan:
+        type: string
+        description: "github environment for the plan job"
+      github-environment-apply:
+        type: string
+        description: "github environment for the apply job"
+      allow-apply:
+        type: boolean
+        description: "whether the apply step is enabled. defaults to true on main"
+        default: ${{ github.ref == 'refs/heads/main' }}
+      creds-aws-region:
+        type: string
+        description: creds for aws, specifies the region
+        required: true
+      creds-aws-role-arn-plan:
+        type: string
+        description: "oidc role arn for the plan job (readonly)"
+        required: true
+      creds-aws-role-arn-apply:
+        type: string
+        description: "oidc role arn for the apply job"
+        required: true
+
+permissions:
+  id-token: write # required for oidc
+  contents: read
+
+jobs:
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  plan:
+    runs-on: ubuntu-24.04
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-plan }}
+      deployment: false
+    needs: [install]
+    # opt into the readonly plan grant for every step in this job (tunnel + plan
+    # both call getConfig): under plan the oidc role can read only the for-plan
+    # db credential, so config must select it and tolerate the denied secrets.
+    env:
+      GRANT: plan
+    outputs:
+      has-changes-planned: ${{ steps.evaluate-plan.outputs.has-changes-planned }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: node-modules cache get
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+          fail-on-cache-miss: true
+
+      - name: get aws auth
+        if: ${{ inputs.creds-aws-role-arn-plan }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn-plan }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      # register the ghlitch operator role so `rhx use.vpc.tunnel` resolves
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      - name: vpc:tunnel:open
+        run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
+
+      - name: plan
+        run: |
+          set -o pipefail
+          ACCESS=${{ inputs.access }} npm run provision:schema:plan | tee ./plan.log
+
+      - name: evaluate plan
+        id: evaluate-plan
+        run: |
+          # check that there was not a connection error
+          if grep "connect ETIMEDOUT" ./plan.log
+          then
+            echo "🛑 connection timed out, could not execute plan. is vpc tunnel working?"
+            exit 1
+          fi
+
+          # check whether it said there were required changes
+          if grep "Everything is up to date" ./plan.log
+          then
+            echo "has-changes-planned=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has-changes-planned=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: has changes planned?
+        run: echo "${{ steps.evaluate-plan.outputs.has-changes-planned }}"
+
+  apply:
+    runs-on: ubuntu-24.04
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
+    needs: [install, plan]
+    if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: set node-version
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: ".nvmrc"
+
+      - name: node-modules cache get
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+          fail-on-cache-miss: true
+
+      - name: get aws auth
+        if: ${{ inputs.creds-aws-role-arn-apply }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn-apply }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      # register the ghlitch operator role so `rhx use.vpc.tunnel` resolves
+      - name: prepare:rhachet
+        run: npm run prepare:rhachet --if-present
+
+      - name: vpc:tunnel:open
+        run: npx rhx use.vpc.tunnel --env ${{ inputs.access }}
+
+      - name: apply
+        run: ACCESS=${{ inputs.access }} npm run provision:schema:apply

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

@@ -0,0 +1,118 @@
+name: .terraform
+
+on:
+  workflow_call:
+    inputs:
+      working-directory:
+        type: string
+        description: "the directory from within which to execute terraform commands"
+      github-environment-plan:
+        type: string
+        description: "github environment for the plan job"
+      github-environment-apply:
+        type: string
+        description: "github environment for the apply job"
+      allow-apply:
+        type: boolean
+        description: "whether the apply step is enabled. defaults to true on main"
+        default: ${{ github.ref == 'refs/heads/main' }}
+      creds-aws-region:
+        description: "creds for aws, specifies the region"
+        required: true
+        type: string
+      creds-aws-role-arn-plan:
+        description: "oidc role arn for the plan job (readonly)"
+        required: true
+        type: string
+      creds-aws-role-arn-apply:
+        description: "oidc role arn for the apply job"
+        required: true
+        type: string
+
+permissions:
+  id-token: write # required for oidc
+  contents: read
+
+jobs:
+  plan:
+    runs-on: ubuntu-24.04
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so a plan
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-plan }}
+      deployment: false
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+    outputs:
+      has-changes-planned: ${{ steps.evaluate-plan.outputs.has-changes-planned }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: get aws auth
+        if: ${{ inputs.creds-aws-role-arn-plan }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn-plan }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      - name: setup terraform
+        uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
+
+      - name: terraform init
+        run: terraform init
+
+      - name: terraform validate
+        run: terraform validate
+
+      - name: terraform plan
+        id: plan
+        run: terraform plan -detailed-exitcode | tee ./plan.log
+
+      - name: evaluate plan
+        id: evaluate-plan
+        run: |
+          if grep "infrastructure matches the configuration" ./plan.log
+          then
+            echo "has-changes-planned=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has-changes-planned=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: has changes planned?
+        run: echo "${{ steps.evaluate-plan.outputs.has-changes-planned }}"
+
+  apply:
+    runs-on: ubuntu-24.04
+    environment:
+      # deployment: false keeps the built-in gate but suppresses the auto-Deployment, so the apply
+      # run posts no "deployed to <env>" status to the PR timeline. the environment is ALWAYS
+      # declared — for prep and prod alike.
+      name: ${{ inputs.github-environment-apply }}
+      deployment: false
+    needs: plan
+    if: ${{ inputs.allow-apply == true && needs.plan.outputs.has-changes-planned == 'true' }}
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: get aws auth
+        if: ${{ inputs.creds-aws-role-arn-apply }}
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
+        with:
+          role-to-assume: ${{ inputs.creds-aws-role-arn-apply }}
+          aws-region: ${{ inputs.creds-aws-region }}
+
+      - name: setup terraform
+        uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3
+
+      - name: terraform init
+        run: terraform init
+
+      - name: terraform apply
+        run: terraform apply -auto-approve

package/dist/.test/assets/cicd-service/declarations/practices/cicd-service/best-practice/.github/workflows/deploy.yml

@@ -0,0 +1,77 @@
+name: deploy
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  workflow_dispatch:
+    inputs:
+      access:
+        description: "which access do you want to deploy with?"
+        type: choice
+        options:
+          - prep
+          - prod
+        required: true
+        default: "prep"
+      thoroughly:
+        description: "should we run tests before this deployment?"
+        type: choice
+        required: true
+        default: "true"
+        options:
+          - "true"
+          - "false"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/.test.yml
+    if: github.event_name != 'workflow_dispatch' || github.event.inputs.thoroughly == 'true'
+    with:
+      creds-aws-region: us-east-1
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }} # use aws auth via oidc, if this repo supplies it
+    secrets: inherit # keyrack firewall in .test.yml filters to declared keys
+
+  prep:
+    uses: ./.github/workflows/.deploy-sls.yml
+    needs: [test]
+    if: |
+      ((github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch') || github.event.inputs.access == 'prep') &&
+      always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
+    # github-environment is ALWAYS declared — for prep as well as prod. deployment:false (in
+    # .deploy-sls.yml) keeps the gate (required reviewers, oidc claim) and suppresses the
+    # PR-timeline Deployment spam, so prep declares its environment without the noise.
+    with:
+      access: prep
+      github-environment-apply: preparation
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  prod:
+    uses: ./.github/workflows/.deploy-sls.yml
+    if: |
+      ((startsWith(github.ref, 'refs/tags/') && github.event_name != 'workflow_dispatch') || github.event.inputs.access == 'prod') &&
+      always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
+    needs: [test]
+    with:
+      access: prod
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+    secrets:
+      # .deploy-sls.yml declares AND uses this secret to page on a failed prod deploy/acceptance.
+      # omit it and the alarm step's `if: env.PAGERDUTY_INTEGRATION_KEY` is false, so the step is
+      # SKIPPED silently and prod alerts are dead. the callee marks it `required: false`, so github
+      # never errors on the omission — this pass-through is what keeps the alert live.
+      pagerduty-integration-key: ${{ secrets.PAGERDUTY_INTEGRATION_KEY }}

package/dist/.test/assets/cicd-service/declarations/practices/cicd-service/best-practice/.github/workflows/deploy.yml.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = validates deploy.yml matches the template exactly
+ * .why = secrets: inherit passes all secrets to .test.yml; firewall handles key filter at runtime
+ */
+export const check = FileCheckType.EQUALS;
+
+/**
+ * .what = replaces deploy.yml with the template content
+ * .why = ensures caller workflow has secrets: inherit for firewall
+ */
+export const fix: FileFixFunction = async (_contents, context) => {
+  return { contents: context.declaredFileContents ?? '' };
+};

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

@@ -0,0 +1,110 @@
+name: provision
+
+on:
+  push:
+    tags:
+      - v*
+    branches:
+      - "main"
+      - "master"
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+permissions:
+  id-token: write # required for oidc; a called workflow cannot exceed its caller's grant
+  contents: read
+
+jobs:
+  aws-test-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/test
+      github-environment-plan: preparation
+      github-environment-apply: preparation
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  aws-prep-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  aws-prod-terraform:
+    uses: ./.github/workflows/.terraform.yml
+    with:
+      working-directory: provision/aws/environments/prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
+      allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  github:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/github.repo/resources.ts
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply
+      creds-github-app-owner: ${{ github.repository_owner }}
+      creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
+    secrets:
+      creds-github-app-private-key: ${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}
+
+  sql-schema-prep:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      access: prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  sql-schema-prod:
+    uses: ./.github/workflows/.sql-schema-control.yml
+    with:
+      access: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
+      allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  aws-prep-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/aws/resources.ts
+      scope: aws
+      access: prep
+      github-environment-plan: preparation
+      github-environment-apply: preparation
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  aws-prod-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/aws/resources.ts
+      scope: aws
+      access: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: ${{ (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) && 'production-on-main' || 'production-on-else-apply' }} # main/tag => on-main; else => on-else-apply (actor_id-gated writer)
+      allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}

package/dist/.test/assets/cicd-service/declarations/practices/cicd-service/best-practice/.github/workflows/provision.yml.declapract.ts

@@ -0,0 +1,74 @@
+import { FileCheckType, type FileContentsFunction } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
+
+import { readFile } from '../../../../../utils/readFile';
+
+/**
+ * .what = declare the service provision workflow, with the 4 rds-coupled jobs
+ *         (`sql-schema-{prep,prod}`, `aws-{prep,prod}-declastruct`) included only when the
+ *         `persist-with-rds` practice is in play for the project.
+ * .why  = those 4 jobs reference files `persist-with-rds` owns — its schema + daos (the
+ *         `.sql-schema-control.yml` callee) and its `provision/aws/resources.ts` wish (the
+ *         declastruct callee). a service WITHOUT rds (`lambda-service`,
+ *         `lambda-service-with-dynamodb`) ships none of them, so those jobs fail its own
+ *         provision workflow — D28/#573, live on 2 of 3 service usecases. a branch on
+ *         `context.projectPractices` lets one practice serve all three usecases
+ *         (`rule.avoid.runtime-forks`), and CONTAINS (not EQUALS) keeps a narrow
+ *         `--practice cicd-service` apply from a strip of an rds repo's own jobs — the additive
+ *         usecase-delta EQUALS hazard named in that rule's caveat table.
+ * .note = the 4 rds jobs are the contiguous tail after the generic `github` job, so a split on
+ *         the first rds job header (`sql-schema-prep:`) truncates the whole rds block cleanly.
+ */
+
+// the header of the first rds-coupled job; the 4 rds jobs are the contiguous tail after it
+export const RDS_JOBS_ANCHOR = '\n\n  sql-schema-prep:';
+
+/**
+ * .what = the text before the first rds-job header — the generic-jobs prefix.
+ * .why  = names the positional truncation as one intent, so `withoutRdsJobs` reads what-not-how
+ *         rather than an inline positional `split(...)[0]` a reader must mentally simulate
+ *         (`rule.forbid.inline-decode-friction`).
+ */
+const asPrefixBeforeRdsJobs = (input: { contents: string }): string =>
+  input.contents.split(RDS_JOBS_ANCHOR)[0]!;
+
+/**
+ * .what = drop the 4 rds-coupled jobs — the contiguous tail after the generic `github` job — by a
+ *         truncation at the first rds job header. returns the generic-jobs prefix, newline-terminated.
+ * .why  = names the strip as one intent so the orchestrator reads what-not-how, rather than an inline
+ *         positional `split(...)[0]` a reader must mentally simulate (`rule.forbid.inline-decode-friction`).
+ * .note = the anchor is a text boundary, not a structural parse. a miss (a re-indent, a comment added
+ *         mid-block, a re-order of the rds block) throws loudly rather than fails OPEN — a bare
+ *         `split(...)[0]` on a missed anchor returns the WHOLE superset, so a non-rds consumer would
+ *         silently inherit all 4 rds jobs and CONTAINS would still pass (a superset holds the declared
+ *         prefix). that silent re-ship is the exact D28 break this strip exists to close, so a load
+ *         anchor miss must fail LOUD (`rule.forbid.failhide` / `rule.require.failfast`).
+ */
+export const withoutRdsJobs = (input: { contents: string }): string => {
+  // fail loud if the anchor is absent — never truncate to the whole superset on a miss. this is a
+  // server-side malfunction (this practice's own template shape changed, not a consumer input), so a
+  // MalfunctionError (exit 1) carries the who-fixes semantic — a retried/automated caller can
+  // machine-distinguish a transient malfunction from a caller constraint (exit 2), consistent with
+  // the failures this same round converts to ConstraintError elsewhere
+  // (`rule.require.failloud` / `rule.require.exit-code-semantics`)
+  if (!input.contents.includes(RDS_JOBS_ANCHOR))
+    throw new MalfunctionError(
+      `could not find the rds-jobs anchor ('${RDS_JOBS_ANCHOR}') in provision.yml — the template shape changed; a non-rds strip cannot proceed without re-ship of the rds jobs`,
+    );
+
+  return `${asPrefixBeforeRdsJobs({ contents: input.contents })}\n`;
+};
+
+export const contents: FileContentsFunction = async (context) => {
+  // grab the superset — the full workflow, rds jobs included
+  const contentsSuperset = await readFile({
+    filePath: `${__dirname}/provision.yml`,
+  });
+
+  // keep every job for an rds service; drop the rds tail for a non-rds one
+  return context.projectPractices.includes('persist-with-rds')
+    ? contentsSuperset
+    : withoutRdsJobs({ contents: contentsSuperset });
+};
+
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/cicd-service/declarations/practices/cicd-service/best-practice/package.json

@@ -0,0 +1,7 @@
+{
+  "devDependencies": {
+    "declastruct": "@declapract{check.minVersion('1.9.2')}",
+    "declastruct-aws": "@declapract{check.minVersion('1.11.0')}",
+    "declastruct-unix-network": "@declapract{check.minVersion('1.1.0')}"
+  }
+}

package/dist/.test/assets/cicd-service/declarations/practices/cicd-service/insync-grep.declapract.integration.test.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps the two peer apply-gate greps in cicd-service to the LITERAL in-sync marker
+ *         each tool actually emits, so the has-changes-planned=false fast path stays live — the same
+ *         guard #561 added for cicd-common/.declastruct.yml, extended to its two untested peers.
+ * .why  = an apply-gate greps the tool's plan log for an "in sync / no changes" phrase to skip a
+ *         redundant apply. if the grep string drifts from the tool's real output (the #561 failure:
+ *         a capital-E grep vs a lowercase marker), the fast path silently dies — every plan falls to
+ *         has-changes-planned=true and apply always runs. it fails SAFE (over-gates, a redundant
+ *         idempotent apply), so no alarm ever fires; a clamp tied to the tool's real output is the
+ *         only guard that catches such a drift.
+ * .verified = both markers match the tool's real output as of this clamp:
+ *         - sql-schema-control emits `Everything is up to date 🎉` (capital E) — displayPlans.ts:28
+ *           + src/contract/__snapshots__/cli.acceptance.test.ts.snap.
+ *         - terraform emits `No changes. Your infrastructure matches the configuration.` — the
+ *           standard `terraform plan` no-change line.
+ * .teeth = drift either grep (e.g. lowercase the sql marker, or reword the terraform phrase) and the
+ *          assertion for that grep reddens.
+ * .note = the subject is the shipped TEMPLATE, read from __dirname/best-practice. this file sits at
+ *         the practice ROOT, so declapract never emits it (per the #583 relocation convention).
+ */
+describe('cicd-service apply-gate in-sync greps', () => {
+  given('the shipped .sql-schema-control.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.sql-schema-control.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // sql-schema-control emits this literal phrase (capital E); the workflow must match it verbatim
+      const marker = 'Everything is up to date';
+
+      then('it greps the marker sql-schema-control actually emits', () => {
+        expect(yml).toContain(`grep "${marker}" ./plan.log`);
+      });
+
+      // the emitted grep line is the caller-faced contract: snapshot it so a reword that keeps
+      // the marker token green reddens a vibecheck.
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep "') && line.includes('./plan.log'));
+        expect(grepLine?.trim()).toMatchSnapshot('sql-schema-control apply-gate grep');
+      });
+    });
+  });
+
+  given('the shipped .terraform.yml', () => {
+    const yml = readFileSync(
+      join(__dirname, 'best-practice/.github/workflows/.terraform.yml'),
+      'utf8',
+    );
+
+    when('the apply-gate grep is read', () => {
+      // terraform emits `No changes. Your infrastructure matches the configuration.` on a clean plan
+      const marker = 'infrastructure matches the configuration';
+
+      then('it greps the marker terraform actually emits', () => {
+        expect(yml).toContain(`grep "${marker}" ./plan.log`);
+      });
+
+      // the emitted grep line is the caller-faced contract: snapshot it so a reword that keeps
+      // the marker token green reddens a vibecheck.
+      then('the emitted apply-gate grep line matches snapshot', () => {
+        const grepLine = yml
+          .split('\n')
+          .find((line) => line.includes('grep "') && line.includes('./plan.log'));
+        expect(grepLine?.trim()).toMatchSnapshot('terraform apply-gate grep');
+      });
+    });
+  });
+});