@biffo/cli 0.217.7 → 0.218.0

package/_skeletons/plugin-template/scripts/check-destructive-plan.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * CI runner for the destructive-plan guard (issue #387).
+ *
+ * Reads a `terraform show -json` plan and refuses it when it would destroy
+ * stateful infrastructure without an `Infra-Destroy:` trailer authorising it.
+ *
+ * Runs in the **Plan** job, before Apply, so a refusal costs nothing: no
+ * infrastructure has been touched when it fires. Apply runs with
+ * `--auto-approve`, so this is the only point at which a human decision can
+ * still be required.
+ *
+ * No dependencies, so it runs on bare node without a pnpm install — see
+ * destructive-plan.mjs for why.
+ *
+ * Usage: node check-destructive-plan.mjs <plan.json>
+ */
+
+import { execFileSync } from 'node:child_process'
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { DESTROY_TRAILER, checkDestructivePlan } from './destructive-plan.mjs'
+
+const BOLD = ''
+const DIM = ''
+const RED = ''
+const OFF = ''
+
+/**
+ * Commit messages this deploy is carrying.
+ *
+ * A push build has no PR body, so the commit message is the only place an
+ * author can speak to CI. `github.event.before` bounds it to what this push
+ * actually added; on a first push or a force-push it is all-zeroes, and then
+ * the tip commit alone is the honest answer rather than the entire history —
+ * an `Infra-Destroy:` trailer from six months ago must not authorise today.
+ */
+function pushCommitMessages() {
+  const before = process.env.GITHUB_EVENT_BEFORE
+  const head = process.env.GITHUB_SHA || 'HEAD'
+  const args =
+    before && !/^0+$/.test(before)
+      ? ['log', '--format=%B', `${before}..${head}`]
+      : ['log', '--format=%B', '-1']
+  try {
+    return execFileSync('git', args, { encoding: 'utf8' })
+  } catch {
+    // A shallow clone may not contain `before`. Fall back to the tip rather
+    // than treating an unreadable range as "no trailer", which would block a
+    // legitimately authorised deploy.
+    try {
+      return execFileSync('git', ['log', '--format=%B', '-1'], { encoding: 'utf8' })
+    } catch {
+      return ''
+    }
+  }
+}
+
+function main() {
+  const planPath = process.argv[2]
+  if (!planPath) {
+    console.error('Usage: check-destructive-plan.mjs <plan.json>')
+    process.exit(2)
+  }
+  if (!existsSync(planPath)) {
+    // Fail closed. A missing plan means the guard cannot see what is about to
+    // be applied, which is not the same as there being nothing to see.
+    console.error(`::error::Plan file ${planPath} not found — refusing to apply unexamined.`)
+    process.exit(2)
+  }
+
+  let plan
+  try {
+    plan = JSON.parse(readFileSync(planPath, 'utf8'))
+  } catch (err) {
+    console.error(`::error::Could not parse ${planPath}: ${err.message}`)
+    process.exit(2)
+  }
+
+  const result = checkDestructivePlan(plan, pushCommitMessages())
+
+  if (result.destructive.length === 0) {
+    console.log('✓ destructive-plan guard: no stateful resource is destroyed by this plan.')
+    return
+  }
+
+  const lines = result.destructive.map(
+    (c) => `    ${c.address} ${DIM}(${c.replacement ? 'replaced' : 'destroyed'})${OFF}`,
+  )
+
+  if (!result.blocked) {
+    console.log(
+      `⚠ destructive-plan guard: allowed by ${DESTROY_TRAILER}: ${result.acknowledgedReason}\n` +
+        lines.join('\n'),
+    )
+    summarise(result.destructive, result.acknowledgedReason)
+    return
+  }
+
+  console.error(`
+${RED}${BOLD}✗ This plan destroys stateful infrastructure.${OFF}
+
+${lines.join('\n')}
+
+${BOLD}Why this is blocked${OFF}
+  These resources hold data no re-apply can recreate — rows, users, objects.
+  Everything else Terraform rebuilds from this repo; these it cannot, because
+  nothing in this repo contains the data. Apply runs with --auto-approve, so
+  without this check the destroy would happen with nobody having seen the plan.
+
+  A ${BOLD}replacement${OFF} destroys the original just as surely as a delete, and most
+  incidents of this kind are replacements: an attribute that forces one changed
+  somewhere far from the resource itself.
+
+${BOLD}If it is deliberate${OFF}
+  Say so in the commit message and this passes:
+
+    ${DIM}${DESTROY_TRAILER}: <what is destroyed, and why that is acceptable>${OFF}
+
+  Take a backup first if the data matters — in dev and staging there may be no
+  final snapshot to fall back on.
+`)
+  process.exit(1)
+}
+
+/** Record an authorised destroy in the job summary, so it is visible without
+ * reading the log — the log being exactly what nobody reads. */
+function summarise(destructive, reason) {
+  const path = process.env.GITHUB_STEP_SUMMARY
+  if (!path) return
+  const rows = destructive.map(
+    (c) => `- \`${c.address}\` (${c.replacement ? 'replaced' : 'destroyed'})`,
+  )
+  appendFileSync(
+    path,
+    `### ⚠️ Destructive plan authorised\n\n${destructive.length} stateful resource(s) will be destroyed:\n\n` +
+      `${rows.join('\n')}\n\n**${DESTROY_TRAILER}:** ${reason || ''}\n`,
+  )
+}
+
+main()

package/_skeletons/plugin-template/scripts/destructive-plan.mjs

@@ -0,0 +1,128 @@
+/**
+ * Decide whether a Terraform plan destroys stateful infrastructure (issue #387).
+ *
+ * ## Why this exists
+ *
+ * `deploy-infra.yml` runs `terraform apply -auto-approve`. Nobody reads the
+ * plan. A user-pool replacement or a database rebuild reads as an ordinary
+ * `-/+ resource` line among dozens, and the deploy reports success either way.
+ *
+ * The exposure is not theoretical. Three attributes on `aws_db_instance` —
+ * `identifier`, `db_name`, `username` — are derived from `project_name` and
+ * force **replacement**, and in dev and staging `deletion_protection` is false.
+ * So renaming the project, a plausible and innocuous-looking edit, plans a
+ * destroy of the database, and CI applies it with nobody having seen the plan.
+ *
+ * A Cognito pool replacement of exactly this shape landed unattended during the
+ * 0.50.0 upgrade. It was intended and documented; nothing about the mechanism
+ * required it to be.
+ *
+ * ## Why plain .mjs rather than TypeScript
+ *
+ * This runs in the **Plan** job, which sets up Terraform and AWS credentials
+ * and nothing else — no pnpm, no node_modules. Adding a dependency install to
+ * three jobs to run one guard is a poor trade, so the guard has no
+ * dependencies and runs on bare node.
+ *
+ * It is still tested: `cli/src/lib/destructive-plan.test.ts` imports this file
+ * directly, the same arrangement `packaged-root-assets.mjs` already uses. The
+ * logic has one home, not two.
+ */
+
+/**
+ * Resource types whose destruction loses data that no re-apply can recreate.
+ *
+ * Deliberately a small, explicit list rather than a heuristic. A guard that
+ * fires on everything gets its acknowledgement trailer added by reflex, and
+ * then it protects nothing — so it fires only where a human really should stop.
+ *
+ * Everything absent from this list is configuration: Terraform rebuilds a
+ * Lambda, a security group or an IAM role from this repo. Nothing in this repo
+ * contains the rows.
+ */
+export const STATEFUL_RESOURCE_TYPES = [
+  // The data itself.
+  'aws_db_instance',
+  'aws_rds_cluster',
+  'aws_rds_cluster_instance',
+  'aws_dynamodb_table',
+  'aws_efs_file_system',
+  'aws_elasticache_cluster',
+  'aws_elasticache_replication_group',
+  // Identities. Replacing a pool deletes every user and every `sub` with it,
+  // orphaning anything keyed on cognito_sub (ADR-0012).
+  'aws_cognito_user_pool',
+  // Objects. A bucket destroy takes its contents; for state and media buckets
+  // that is the entire point of the bucket.
+  'aws_s3_bucket',
+  // Delegation. A hosted zone's NS assignment is not in this repo — AWS
+  // assigns it at creation and the registrar is told about it out of band.
+  // Replacing the zone issues new nameservers, so recovery is a registrar
+  // change plus propagation, not a re-apply. The zone's records ARE
+  // Terraform-managed and would come back; the delegation is what would not.
+  //
+  // aws_acm_certificate was considered and rejected: a replacement re-issues
+  // and DNS-validates automatically while the zone underneath it stands, so
+  // it passes the same test that keeps this list small — Terraform rebuilds
+  // it from this repo, unattended.
+  'aws_route53_zone',
+]
+
+/**
+ * Trailer, on its own line in a commit message, authorising this plan's
+ * destructive changes. Mirrors `Core-Divergence:` — deliberate, and recorded in
+ * history rather than argued about afterwards.
+ */
+export const DESTROY_TRAILER = 'Infra-Destroy'
+
+/**
+ * Extract the reason from an `Infra-Destroy:` trailer, or null.
+ *
+ * Anchored per line, and comment lines are dropped, for the same reason
+ * `Core-Divergence:` is: the words appearing inside prose are not an
+ * authorisation to delete a database.
+ */
+export function parseDestroyTrailer(commitMessage) {
+  const body = String(commitMessage || '')
+    .split('\n')
+    .filter((line) => !line.trimStart().startsWith('#'))
+    .join('\n')
+  const match = /^Infra-Destroy:[ \t]*(\S.*?)[ \t]*$/m.exec(body)
+  return match ? match[1] : null
+}
+
+/**
+ * Classify a `terraform show -json` plan.
+ *
+ * `replace` counts as destruction: Terraform encodes it as
+ * `["delete","create"]` (or the reverse under create_before_destroy), and a
+ * replacement destroys the original exactly as surely as a bare delete. Most
+ * incidents in this class ARE replacements — nobody runs `terraform destroy` by
+ * accident; they change an attribute that forces one, far from the resource.
+ */
+export function checkDestructivePlan(
+  plan,
+  commitMessage = '',
+  statefulTypes = STATEFUL_RESOURCE_TYPES,
+) {
+  const types = new Set(statefulTypes)
+  const destructive = []
+
+  for (const change of (plan && plan.resource_changes) || []) {
+    const actions = (change.change && change.change.actions) || []
+    if (!actions.includes('delete')) continue
+    if (!types.has(change.type)) continue
+    destructive.push({
+      address: change.address,
+      type: change.type,
+      replacement: actions.includes('create'),
+    })
+  }
+
+  const acknowledgedReason = parseDestroyTrailer(commitMessage)
+  return {
+    destructive,
+    acknowledgedReason,
+    blocked: destructive.length > 0 && acknowledgedReason === null,
+  }
+}

package/_skeletons/sibling-template/.github/workflows/deploy.yml

@@ -85,8 +85,12 @@ jobs:
           EOF
       - run: terraform init -input=false -backend-config=backend.hcl
         timeout-minutes: 10
-      - run: terraform apply -input=false -auto-approve
-        timeout-minutes: 45
+      # Plan to a FILE so the guard below reads the plan that is actually
+      # applied. Variables belong here rather than on the apply: a saved plan
+      # has them baked in, and `terraform apply tfplan` takes no -var at all.
+      - name: Plan
+        run: terraform plan -input=false -no-color -out=tfplan
+        timeout-minutes: 20
         env:
           TF_VAR_project_name: ${{ vars.PROJECT_NAME }}
           TF_VAR_environment: ${{ needs.resolve-environment.outputs.environment }}
@@ -100,6 +104,25 @@ jobs:
           # variables.tf. Re-run this workflow (workflow_dispatch) once
           # that PR merges and this var is set, to add the bucket policy.
           TF_VAR_parent_cloudfront_distribution_arn: ${{ vars.PARENT_CLOUDFRONT_DISTRIBUTION_ARN || '' }}
+      # Refuse a plan that destroys stateful infrastructure without an
+      # `Infra-Destroy:` trailer authorising it (#387, reach fixed by #1123).
+      # Apply is --auto-approve and nobody reads the plan, so this is the only
+      # point at which a human decision can still be required — and it costs
+      # nothing when it fires, because no infrastructure has been touched yet.
+      #
+      # Runs on bare `node`: the script has no dependencies precisely so it can
+      # execute in a Terraform job that installs no JS toolchain. $GITHUB_WORKSPACE
+      # because this job's default working-directory is `infra/`.
+      - name: Destructive-plan guard
+        run: |
+          terraform show -json tfplan > plan.json
+          node "$GITHUB_WORKSPACE/scripts/check-destructive-plan.mjs" plan.json
+        env:
+          GITHUB_EVENT_BEFORE: ${{ github.event.before }}
+      # Applies the plan just checked, not a fresh one — a re-plan here could
+      # differ from what the guard saw.
+      - run: terraform apply -input=false -auto-approve tfplan
+        timeout-minutes: 45
       - name: Export outputs to GitHub Actions variables
         env:
           GH_TOKEN: ${{ secrets.SIBLING_GITHUB_TOKEN }}

package/_skeletons/sibling-template/scripts/check-destructive-plan.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * CI runner for the destructive-plan guard (issue #387).
+ *
+ * Reads a `terraform show -json` plan and refuses it when it would destroy
+ * stateful infrastructure without an `Infra-Destroy:` trailer authorising it.
+ *
+ * Runs in the **Plan** job, before Apply, so a refusal costs nothing: no
+ * infrastructure has been touched when it fires. Apply runs with
+ * `--auto-approve`, so this is the only point at which a human decision can
+ * still be required.
+ *
+ * No dependencies, so it runs on bare node without a pnpm install — see
+ * destructive-plan.mjs for why.
+ *
+ * Usage: node check-destructive-plan.mjs <plan.json>
+ */
+
+import { execFileSync } from 'node:child_process'
+import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { DESTROY_TRAILER, checkDestructivePlan } from './destructive-plan.mjs'
+
+const BOLD = ''
+const DIM = ''
+const RED = ''
+const OFF = ''
+
+/**
+ * Commit messages this deploy is carrying.
+ *
+ * A push build has no PR body, so the commit message is the only place an
+ * author can speak to CI. `github.event.before` bounds it to what this push
+ * actually added; on a first push or a force-push it is all-zeroes, and then
+ * the tip commit alone is the honest answer rather than the entire history —
+ * an `Infra-Destroy:` trailer from six months ago must not authorise today.
+ */
+function pushCommitMessages() {
+  const before = process.env.GITHUB_EVENT_BEFORE
+  const head = process.env.GITHUB_SHA || 'HEAD'
+  const args =
+    before && !/^0+$/.test(before)
+      ? ['log', '--format=%B', `${before}..${head}`]
+      : ['log', '--format=%B', '-1']
+  try {
+    return execFileSync('git', args, { encoding: 'utf8' })
+  } catch {
+    // A shallow clone may not contain `before`. Fall back to the tip rather
+    // than treating an unreadable range as "no trailer", which would block a
+    // legitimately authorised deploy.
+    try {
+      return execFileSync('git', ['log', '--format=%B', '-1'], { encoding: 'utf8' })
+    } catch {
+      return ''
+    }
+  }
+}
+
+function main() {
+  const planPath = process.argv[2]
+  if (!planPath) {
+    console.error('Usage: check-destructive-plan.mjs <plan.json>')
+    process.exit(2)
+  }
+  if (!existsSync(planPath)) {
+    // Fail closed. A missing plan means the guard cannot see what is about to
+    // be applied, which is not the same as there being nothing to see.
+    console.error(`::error::Plan file ${planPath} not found — refusing to apply unexamined.`)
+    process.exit(2)
+  }
+
+  let plan
+  try {
+    plan = JSON.parse(readFileSync(planPath, 'utf8'))
+  } catch (err) {
+    console.error(`::error::Could not parse ${planPath}: ${err.message}`)
+    process.exit(2)
+  }
+
+  const result = checkDestructivePlan(plan, pushCommitMessages())
+
+  if (result.destructive.length === 0) {
+    console.log('✓ destructive-plan guard: no stateful resource is destroyed by this plan.')
+    return
+  }
+
+  const lines = result.destructive.map(
+    (c) => `    ${c.address} ${DIM}(${c.replacement ? 'replaced' : 'destroyed'})${OFF}`,
+  )
+
+  if (!result.blocked) {
+    console.log(
+      `⚠ destructive-plan guard: allowed by ${DESTROY_TRAILER}: ${result.acknowledgedReason}\n` +
+        lines.join('\n'),
+    )
+    summarise(result.destructive, result.acknowledgedReason)
+    return
+  }
+
+  console.error(`
+${RED}${BOLD}✗ This plan destroys stateful infrastructure.${OFF}
+
+${lines.join('\n')}
+
+${BOLD}Why this is blocked${OFF}
+  These resources hold data no re-apply can recreate — rows, users, objects.
+  Everything else Terraform rebuilds from this repo; these it cannot, because
+  nothing in this repo contains the data. Apply runs with --auto-approve, so
+  without this check the destroy would happen with nobody having seen the plan.
+
+  A ${BOLD}replacement${OFF} destroys the original just as surely as a delete, and most
+  incidents of this kind are replacements: an attribute that forces one changed
+  somewhere far from the resource itself.
+
+${BOLD}If it is deliberate${OFF}
+  Say so in the commit message and this passes:
+
+    ${DIM}${DESTROY_TRAILER}: <what is destroyed, and why that is acceptable>${OFF}
+
+  Take a backup first if the data matters — in dev and staging there may be no
+  final snapshot to fall back on.
+`)
+  process.exit(1)
+}
+
+/** Record an authorised destroy in the job summary, so it is visible without
+ * reading the log — the log being exactly what nobody reads. */
+function summarise(destructive, reason) {
+  const path = process.env.GITHUB_STEP_SUMMARY
+  if (!path) return
+  const rows = destructive.map(
+    (c) => `- \`${c.address}\` (${c.replacement ? 'replaced' : 'destroyed'})`,
+  )
+  appendFileSync(
+    path,
+    `### ⚠️ Destructive plan authorised\n\n${destructive.length} stateful resource(s) will be destroyed:\n\n` +
+      `${rows.join('\n')}\n\n**${DESTROY_TRAILER}:** ${reason || ''}\n`,
+  )
+}
+
+main()

package/_skeletons/sibling-template/scripts/destructive-plan.mjs

@@ -0,0 +1,128 @@
+/**
+ * Decide whether a Terraform plan destroys stateful infrastructure (issue #387).
+ *
+ * ## Why this exists
+ *
+ * `deploy-infra.yml` runs `terraform apply -auto-approve`. Nobody reads the
+ * plan. A user-pool replacement or a database rebuild reads as an ordinary
+ * `-/+ resource` line among dozens, and the deploy reports success either way.
+ *
+ * The exposure is not theoretical. Three attributes on `aws_db_instance` —
+ * `identifier`, `db_name`, `username` — are derived from `project_name` and
+ * force **replacement**, and in dev and staging `deletion_protection` is false.
+ * So renaming the project, a plausible and innocuous-looking edit, plans a
+ * destroy of the database, and CI applies it with nobody having seen the plan.
+ *
+ * A Cognito pool replacement of exactly this shape landed unattended during the
+ * 0.50.0 upgrade. It was intended and documented; nothing about the mechanism
+ * required it to be.
+ *
+ * ## Why plain .mjs rather than TypeScript
+ *
+ * This runs in the **Plan** job, which sets up Terraform and AWS credentials
+ * and nothing else — no pnpm, no node_modules. Adding a dependency install to
+ * three jobs to run one guard is a poor trade, so the guard has no
+ * dependencies and runs on bare node.
+ *
+ * It is still tested: `cli/src/lib/destructive-plan.test.ts` imports this file
+ * directly, the same arrangement `packaged-root-assets.mjs` already uses. The
+ * logic has one home, not two.
+ */
+
+/**
+ * Resource types whose destruction loses data that no re-apply can recreate.
+ *
+ * Deliberately a small, explicit list rather than a heuristic. A guard that
+ * fires on everything gets its acknowledgement trailer added by reflex, and
+ * then it protects nothing — so it fires only where a human really should stop.
+ *
+ * Everything absent from this list is configuration: Terraform rebuilds a
+ * Lambda, a security group or an IAM role from this repo. Nothing in this repo
+ * contains the rows.
+ */
+export const STATEFUL_RESOURCE_TYPES = [
+  // The data itself.
+  'aws_db_instance',
+  'aws_rds_cluster',
+  'aws_rds_cluster_instance',
+  'aws_dynamodb_table',
+  'aws_efs_file_system',
+  'aws_elasticache_cluster',
+  'aws_elasticache_replication_group',
+  // Identities. Replacing a pool deletes every user and every `sub` with it,
+  // orphaning anything keyed on cognito_sub (ADR-0012).
+  'aws_cognito_user_pool',
+  // Objects. A bucket destroy takes its contents; for state and media buckets
+  // that is the entire point of the bucket.
+  'aws_s3_bucket',
+  // Delegation. A hosted zone's NS assignment is not in this repo — AWS
+  // assigns it at creation and the registrar is told about it out of band.
+  // Replacing the zone issues new nameservers, so recovery is a registrar
+  // change plus propagation, not a re-apply. The zone's records ARE
+  // Terraform-managed and would come back; the delegation is what would not.
+  //
+  // aws_acm_certificate was considered and rejected: a replacement re-issues
+  // and DNS-validates automatically while the zone underneath it stands, so
+  // it passes the same test that keeps this list small — Terraform rebuilds
+  // it from this repo, unattended.
+  'aws_route53_zone',
+]
+
+/**
+ * Trailer, on its own line in a commit message, authorising this plan's
+ * destructive changes. Mirrors `Core-Divergence:` — deliberate, and recorded in
+ * history rather than argued about afterwards.
+ */
+export const DESTROY_TRAILER = 'Infra-Destroy'
+
+/**
+ * Extract the reason from an `Infra-Destroy:` trailer, or null.
+ *
+ * Anchored per line, and comment lines are dropped, for the same reason
+ * `Core-Divergence:` is: the words appearing inside prose are not an
+ * authorisation to delete a database.
+ */
+export function parseDestroyTrailer(commitMessage) {
+  const body = String(commitMessage || '')
+    .split('\n')
+    .filter((line) => !line.trimStart().startsWith('#'))
+    .join('\n')
+  const match = /^Infra-Destroy:[ \t]*(\S.*?)[ \t]*$/m.exec(body)
+  return match ? match[1] : null
+}
+
+/**
+ * Classify a `terraform show -json` plan.
+ *
+ * `replace` counts as destruction: Terraform encodes it as
+ * `["delete","create"]` (or the reverse under create_before_destroy), and a
+ * replacement destroys the original exactly as surely as a bare delete. Most
+ * incidents in this class ARE replacements — nobody runs `terraform destroy` by
+ * accident; they change an attribute that forces one, far from the resource.
+ */
+export function checkDestructivePlan(
+  plan,
+  commitMessage = '',
+  statefulTypes = STATEFUL_RESOURCE_TYPES,
+) {
+  const types = new Set(statefulTypes)
+  const destructive = []
+
+  for (const change of (plan && plan.resource_changes) || []) {
+    const actions = (change.change && change.change.actions) || []
+    if (!actions.includes('delete')) continue
+    if (!types.has(change.type)) continue
+    destructive.push({
+      address: change.address,
+      type: change.type,
+      replacement: actions.includes('create'),
+    })
+  }
+
+  const acknowledgedReason = parseDestroyTrailer(commitMessage)
+  return {
+    destructive,
+    acknowledgedReason,
+    blocked: destructive.length > 0 && acknowledgedReason === null,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.217.7",
+  "version": "0.218.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",