declapract-typescript-ehmpathy 0.49.2 → 0.49.4

package/dist/getVariables.ts

@@ -10,7 +10,7 @@ export const getServiceVariables = createGetVariables({
   infrastructureNamespaceId: 'abcde12345',
   slackWebhookUrl: 'https://...',
   awsAccountId: {
-    dev: '123abc',
+    prep: '123abc',
     prod: '456def',
   },
 });
@@ -18,9 +18,13 @@ export const getServiceVariables = createGetVariables({
 export const getRdsVariables = createGetVariables({
   databaseName: 'awesomethingdb',
   databaseClusterHost: {
-    dev: 'awesomesdb.cluster-abc123.us-east-1.rds.amazonaws.com',
+    prep: 'awesomesdb.cluster-abc123.us-east-1.rds.amazonaws.com',
     prod: 'awesomesdb.cluster-def456.us-east-1.rds.amazonaws.com',
   },
+  databaseTunnelHost: {
+    prep: 'aws.ssmproxy.awesomesdb.prep',
+    prod: 'aws.ssmproxy.awesomesdb.prod',
+  },
   databaseUserName: {
     serviceUser: 'svc_awesome_thing_user',
     cicdUser: 'awesomethingdb_cicd',

package/dist/practices/cicd-app-react-native-expo/best-practice/.github/workflows/.deploy-expo.yml

@@ -5,7 +5,7 @@ on:
     inputs:
       stage:
         type: string
-        description: "the stage of infrastructure to deploy against (e.g., prod, dev)"
+        description: "the stage of infrastructure to deploy against (e.g., prod, prep)"
         required: true
       build:
         type: string

package/dist/practices/cicd-app-react-native-expo/best-practice/.github/workflows/deploy.yml

@@ -13,10 +13,10 @@ on:
         description: 'which stage do you want to deploy to?'
         type: choice
         options:
-          - dev
+          - prep
           - prod
         required: true
-        default: 'dev'
+        default: 'prep'
       thoroughly:
         description: 'should we run tests before this deployment?'
         type: choice
@@ -36,22 +36,22 @@ jobs:
     if: github.event_name != 'workflow_dispatch' || github.event.inputs.thoroughly == 'true'
     with:
       creds-aws-region: us-east-1
-      creds-aws-role-arn: arn:aws:iam::@declapract{variable.awsAccountId.dev}:role/@declapract{variable.projectName}-github-actions-dev
+      creds-aws-role-arn: arn:aws:iam::@declapract{variable.awsAccountId.prep}:role/@declapract{variable.projectName}-github-actions-prep
     secrets: inherit # keyrack firewall in .test.yml filters to declared keys
 
-  dev:
+  prep:
     uses: ./.github/workflows/.deploy-expo.yml
     needs: [test]
     # dont deploy on merge to main by default, since builds are expensive
     if: |
-      ((github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch' && false) || github.event.inputs.stage == 'dev') &&
+      ((github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch' && false) || github.event.inputs.stage == 'prep') &&
       always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
     with:
-      stage: dev
+      stage: prep
       build: development
-      github-environment: dev
+      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: arn:aws:iam::@declapract{variable.awsAccountId.dev}:role/@declapract{variable.projectName}-github-actions-dev
+      creds-aws-role-arn: arn:aws:iam::@declapract{variable.awsAccountId.prep}:role/@declapract{variable.projectName}-github-actions-prep
     secrets:
       expo-token: ${{ secrets.EXPO_TOKEN }}
 

package/dist/practices/cicd-app-react-native-expo/best-practice/.github/workflows/test.yml

@@ -17,7 +17,7 @@ jobs:
     uses: ./.github/workflows/.test.yml
     with:
       aws-region: us-east-1
-      aws-account-id: '@declapract{variable.awsAccountId.dev}'
+      aws-account-id: '@declapract{variable.awsAccountId.prep}'
     secrets:
-      aws-access-key-id: ${{ secrets.DEV_AWS_ACCESS_KEY_ID }}
-      aws-secret-access-key: ${{ secrets.DEV_AWS_SECRET_ACCESS_KEY }}
+      aws-access-key-id: ${{ secrets.PREP_AWS_ACCESS_KEY_ID }}
+      aws-secret-access-key: ${{ secrets.PREP_AWS_SECRET_ACCESS_KEY }}

package/dist/practices/cicd-app-react-native-expo/best-practice/package.json

@@ -12,28 +12,28 @@
   },
   "scripts": {
     "start:hot:proxy": "npx local-ssl-proxy --source 3447 --target 8081",
-    "start:hot:dev": "STAGE=dev npx expo start --clear --dev-client",
-    "start:hot:dev:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.dev}:@declapract{variable.app.web.port.hot}'",
-    "start:hot:dev:proxy": "npm run start:hot:dev:link && npm run start:hot:proxy",
+    "start:hot:prep": "STAGE=prep npx expo start --clear --dev-client",
+    "start:hot:prep:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prep}:@declapract{variable.app.web.port.hot}'",
+    "start:hot:prep:proxy": "npm run start:hot:prep:link && npm run start:hot:proxy",
     "start:hot:prod": "STAGE=prod npx expo start --clear --dev-client",
     "start:hot:prod:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prod}:@declapract{variable.app.web.port.hot}'",
     "start:hot:prod:proxy": "npm run start:hot:prod:link && npm run start:hot:proxy",
     "start:cold:proxy": "npx local-ssl-proxy --source 3449 --target 3000",
-    "start:cold:dev": "npm run build:web && npx serve dist --single",
-    "start:cold:dev:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.dev}:@declapract{variable.app.web.port.cold}'",
-    "start:cold:dev:proxy": "echo npm run start:cold:dev:link && npm run start:cold:proxy",
+    "start:cold:prep": "npm run build:web && npx serve dist --single",
+    "start:cold:prep:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prep}:@declapract{variable.app.web.port.cold}'",
+    "start:cold:prep:proxy": "echo npm run start:cold:prep:link && npm run start:cold:proxy",
     "start:cold:prod": "npm run build:web && npx serve dist --single",
     "start:cold:prod:link": "echo '🚀 https://localhost.@declapract{variable.app.web.domain.prod}:@declapract{variable.app.web.port.cold}'",
     "register:device:apple:info": "echo 'learn more here https://docs.expo.dev/build/internal-distribution/'",
     "register:device:apple:inclusions:rebuild:prod": "npx eas build --platform ios --clear-cache",
-    "register:device:apple:inclusions:rebuild:dev": "npx eas build --profile development --platform ios --clear-cache",
+    "register:device:apple:inclusions:rebuild:prep": "npx eas build --profile development --platform ios --clear-cache",
     "register:device:apple:add": "echo 'register an apple device to allow it to install internal builds' && eas device:create && npm run register:device:apple:inclusions:rebuild",
     "register:device:apple:list": "eas device:list",
     "register:device:apple:delete": "eas device:delete",
     "register:device:apple:rename": "eas device:rename",
     "register:profile:apple:list": "echo 'see list here https://developer.apple.com/account/resources/profiles/list'",
-    "build:dev:ios": "eas build --profile development --platform ios --non-interactive",
-    "build:dev:android": "eas build --profile development --platform android --non-interactive",
+    "build:prep:ios": "eas build --profile development --platform ios --non-interactive",
+    "build:prep:android": "eas build --profile development --platform android --non-interactive",
     "build:web": "npx expo export --platform web",
     "deploy:prod:ios:metadata": "eas metadata:push",
     "deploy:prod": "echo 'use github actions'",

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

@@ -226,8 +226,8 @@ jobs:
       - name: start:testdb
         run: npm run start:testdb --if-present
 
-      - name: start:livedb:dev
-        run: npm run start:livedb:dev --if-present
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
 
       - name: build
         run: npm run build
@@ -310,8 +310,8 @@ jobs:
       - name: start:testdb
         run: npm run start:testdb --if-present
 
-      - name: start:livedb:dev
-        run: npm run start:livedb:dev --if-present
+      - name: start:livedb:prep
+        run: npm run start:livedb:prep --if-present
 
       - name: build
         run: npm run build

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

@@ -21,5 +21,5 @@ jobs:
     uses: ./.github/workflows/.test.yml
     with:
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }} # use aws auth via oidc, if this repo supplies it
+      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

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

@@ -18,7 +18,7 @@ jobs:
     uses: ./.github/workflows/.test.yml
     with:
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }} # use aws auth via oidc, if this repo supplies it
+      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
 
   publish:

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

@@ -30,7 +30,7 @@ set -eo pipefail
 
 set -u
 
-# ensure the dev tunnel is awake
+# ensure the prep tunnel is awake
 .agent/repo=.this/skills/use.vpc.tunnel.ts
 
 # ping until available

package/dist/practices/cicd-service/best-practice/.declapract.readme.md

@@ -1,4 +1,4 @@
 flows:
 - test on every commit
-- deploy to dev every commit on master
+- deploy to prep every commit on master
 - deploy to prod every v* tagged commit on master

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

@@ -40,7 +40,7 @@ jobs:
     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_DEV_OIDC_ROLE_ARN }} # use aws auth via oidc, if this repo supplies it
+      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
 
   dev:
@@ -51,9 +51,9 @@ jobs:
       always() && (needs.test.result == 'success' || needs.test.result == 'skipped')
     with:
       stage: dev
-      github-environment: dev
+      github-environment: prep # github environment stays as prep (where secrets/vars live)
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }}
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
   prod:
     uses: ./.github/workflows/.deploy-sls.yml

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

@@ -19,17 +19,17 @@ jobs:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/test
-      github-environment: dev
+      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }}
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
-  aws-dev:
+  aws-prep:
     uses: ./.github/workflows/.terraform.yml
     with:
-      working-directory: provision/aws/environments/dev
-      github-environment: dev
+      working-directory: provision/aws/environments/prep
+      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }}
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
   aws-prod:
     uses: ./.github/workflows/.terraform.yml
@@ -50,13 +50,13 @@ jobs:
     secrets:
       creds-github-app-private-key: ${{ secrets.DECLASTRUCT_GITHUB_CONFORMER_APP_PRIVATE_KEY }}
 
-  sql-schema-dev:
+  sql-schema-prep:
     uses: ./.github/workflows/.sql-schema-control.yml
     with:
       stage: prep
-      github-environment: dev
+      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }}
+      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
   sql-schema-prod:
     uses: ./.github/workflows/.sql-schema-control.yml

package/dist/practices/config/bad-practices/configs-contain-wrong-account-id/config/prod.json.declapract.ts

@@ -4,6 +4,6 @@ import { getServiceVariables } from '../../../../../getVariables';
 
 export const check: FileCheckFunction = (contents, context) => {
   const { awsAccountId } = getServiceVariables(context);
-  if (!contents?.includes(awsAccountId.dev))
-    throw new Error('does not contain aws dev account id');
+  if (!contents?.includes(awsAccountId.prep))
+    throw new Error('does not contain aws prep account id');
 };

package/dist/practices/config/bad-practices/divergent-config-shapes/.declapract.readme.md

@@ -1,6 +1,6 @@
 the following places should have the shape of the config defined identically:
 - `config/test.json`
-- `config/dev.json`
+- `config/prep.json`
 - `config/prod.json`
 
 this check complains if one of them does not look like the others

package/dist/practices/config/bad-practices/divergent-config-shapes/config/{dev.json.declapract.ts → prep.json.declapract.ts}

@@ -16,18 +16,18 @@ export const check: FileCheckFunction = async (contents, context) => {
   const flattenedTestConfigKeys = Object.keys(flatten(testConfigObject));
 
   // grab the found keys
-  const devConfigObject = JSON.parse(contents);
-  const flattenedDevConfigKeys = Object.keys(flatten(devConfigObject));
+  const prepConfigObject = JSON.parse(contents);
+  const flattenedPrepConfigKeys = Object.keys(flatten(prepConfigObject));
 
   // determine which keys are not matched
-  const keysInTestButNotInDev = flattenedTestConfigKeys.filter(
-    (key) => !flattenedDevConfigKeys.includes(key),
+  const keysInTestButNotInPrep = flattenedTestConfigKeys.filter(
+    (key) => !flattenedPrepConfigKeys.includes(key),
   );
-  const keysInDevButNotInTest = flattenedDevConfigKeys.filter(
+  const keysInPrepButNotInTest = flattenedPrepConfigKeys.filter(
     (key) => !flattenedTestConfigKeys.includes(key),
   );
-  if (keysInTestButNotInDev.length) return; // matches bad practice
-  if (keysInDevButNotInTest.length) return; // matches bad practice
+  if (keysInTestButNotInPrep.length) return; // matches bad practice
+  if (keysInPrepButNotInTest.length) return; // matches bad practice
 
   // otherwise, does not match a bad practice
   throw new Error('its fine');

package/dist/practices/config/bad-practices/old-dev-config-location/config/dev.json.declapract.ts

@@ -4,9 +4,12 @@ export const check = FileCheckType.EXISTS;
 
 export const fix: FileFixFunction = (contents, context) => {
   // move config/dev.json → config/prep.json and update access: dev → prep
+  // also update .dev hostnames to .prep (e.g., bastion.dev.example.com → bastion.prep.example.com)
   let fixed = contents;
   if (fixed) {
-    fixed = fixed.replace(/"access":\s*"dev"/, '"access": "prep"');
+    fixed = fixed
+      .replace(/\.dev\b/g, '.prep')
+      .replace(/"access":\s*"dev"/, '"access": "prep"');
   }
   return {
     contents: fixed ?? null,

package/dist/practices/config/best-practice/config/prep.json

@@ -5,7 +5,7 @@
     "access": "prep"
   },
   "aws": {
-    "account": "@declapract{variable.awsAccountId.dev}",
+    "account": "@declapract{variable.awsAccountId.prep}",
     "namespace": "@declapract{variable.infrastructureNamespaceId}"
   }
 }

package/dist/practices/config/best-practice/config/test.json

@@ -5,7 +5,7 @@
     "access": "test"
   },
   "aws": {
-    "account": "@declapract{variable.awsAccountId.dev}",
+    "account": "@declapract{variable.awsAccountId.prep}",
     "namespace": "@declapract{variable.infrastructureNamespaceId}"
   }
 }

package/dist/practices/environments/bad-practices/old-dev-scripts/package.json.declapract.ts

@@ -0,0 +1,57 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects package.json scripts with `:dev` as a segment
+ * .why = standardizing on `prep` over `dev` for pre-production environment naming
+ *
+ * matches both `:dev` at end (deploy:dev) and `:dev:` in middle (build:dev:ios)
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('fine, does not match bad practice');
+  const parsedContents = JSON.parse(contents);
+  const scripts = parsedContents.scripts ?? {};
+
+  // check if any script name contains :dev as a segment (either :dev at end or :dev: in middle)
+  const devScripts = Object.keys(scripts).filter(
+    (key) => key.endsWith(':dev') || key.includes(':dev:'),
+  );
+  if (devScripts.length > 0) return; // matches bad practice
+
+  throw new Error('fine, no scripts with :dev segment');
+};
+
+/**
+ * .what = renames scripts from `:dev` segment to `:prep` segment
+ * .why = standardizing on `prep` over `dev` for pre-production environment naming
+ *
+ * handles both `:dev` at end (deploy:dev) and `:dev:` in middle (build:dev:ios)
+ *
+ * .note = only renames script NAMES, not VALUES. script values may still reference
+ *         `--stage dev` for infrastructure naming (cloudformation stacks stay named
+ *         `$service-dev`). the serverless package.json handles this via SLS_STAGE
+ *         mapping. see brief: define.infrastructure-dev-vs-application-prep.md
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return {};
+  const parsedContents = JSON.parse(contents);
+  const scripts = parsedContents.scripts ?? {};
+
+  // find scripts with :dev segment and create renamed versions
+  const updatedScripts = { ...scripts };
+  for (const [key, value] of Object.entries(scripts)) {
+    if (key.endsWith(':dev') || key.includes(':dev:')) {
+      // replace :dev: in middle and :dev at end with :prep
+      const newKey = key.replace(/:dev:/g, ':prep:').replace(/:dev$/, ':prep');
+      updatedScripts[newKey] = value; // add :prep version
+      updatedScripts[key] = undefined; // remove :dev version
+    }
+  }
+
+  return {
+    contents: JSON.stringify(
+      { ...parsedContents, scripts: updatedScripts },
+      null,
+      2,
+    ),
+  };
+};

package/dist/practices/environments/best-practice/.declapract.readme.md

@@ -4,7 +4,7 @@ a critical part of an application's environment is which stage it is running in
 
 ehmpathy recognizes three standard stages in which applications run throughout their development cycle
 - `prod` stage - a deployed production stack in which application that the business depends on run, affecting real customers
-- `dev` stage - a deployed developer-only stack in which applications can run and interact with each other for testing
+- `prep` stage - a deployed pre-production stack in which applications can run and interact with each other for testing
 - `test` stage - an ephemeral, primarily local, developer-only stack in which developers run local code against for testing
 
 this information is expected to be defined in the runtime environment through the following environmental variables

package/dist/practices/environments/best-practice/src/utils/environment.ts

@@ -4,5 +4,5 @@ export { getEnvironment };
 
 export const envStatic = getEnvironment.static();
 
-export const stage = envStatic.access === 'prep' ? 'dev' : envStatic.access;
-export const serviceClientStage = stage === 'prod' ? 'prod' : 'dev';
+export const stage = envStatic.access;
+export const serviceClientStage = stage === 'prod' ? 'prod' : 'prep';

package/dist/practices/husky/best-practice/.husky/check.timestamps.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# .what = block commit of files that embed a timestamp (T?HH:MM:SS{tz})
+# .why  = timestamps in snapshots permadrift — they change every run, so the
+#         snapshot can never be "correct" twice; mask them to keep it stable
+# .how  = scan staged files (except .ts/.sh) for the pattern; halt with a
+#         constraint error (exit 2) if any are found
+
+# fail fast on errors and unbound vars (safe here: scan pipelines end in `head`
+# so a no-match grep does not abort, and all vars are assigned before use)
+set -eu
+
+# the timestamp pattern: optional lead T, HH:MM:SS, optional timezone (Z, ±HH:MM, ±HHMM)
+TIMESTAMP_PATTERN='T?[0-9][0-9]:[0-9][0-9]:[0-9][0-9](Z|[+-][0-9][0-9]:?[0-9][0-9])?'
+
+# collect staged files (added/copied/modified); skip deletions
+staged=$(git diff --cached --name-only --diff-filter=ACM)
+
+# scan each staged file for a raw timestamp
+# note: the here-doc feeds the loop in the current shell (no pipe subshell),
+#       so `exit 2` halts the commit directly and a clean pass falls through
+while IFS= read -r file; do
+  # skip empty lines
+  [ -n "$file" ] || continue
+
+  # skip exempt code files (.ts and .sh legitimately carry time logic)
+  case "$file" in
+    *.ts | *.sh) continue ;;
+  esac
+
+  # read the staged content; fail loud if git cannot read the staged blob
+  # (2>&1 captures git's error into the var so the halt message can surface it)
+  if ! content=$(git show ":$file" 2>&1); then
+    printf '💥 check.timestamps: failed to read staged content for %s\n' "$file" >&2
+    printf '   └─ %s\n' "$content" >&2
+    exit 1
+  fi
+
+  # halt if the staged content embeds a raw timestamp
+  match=$(printf '%s\n' "$content" | grep -nIE "$TIMESTAMP_PATTERN" | head -n 1)
+  if [ -n "$match" ]; then
+    printf '✋ timestamps are forbidden in snapshots. mask them to prevent permadrift\n'
+    printf '   └─ %s:%s\n' "$file" "$match"
+    exit 2
+  fi
+done <<EOF
+$staged
+EOF

package/dist/practices/husky/best-practice/.husky/pre-commit

@@ -6,3 +6,5 @@ fi
 . "$(dirname -- "$0")/_/husky.sh"
 
 . "$(dirname -- "$0")/check.yalc.sh"
+
+. "$(dirname -- "$0")/check.timestamps.sh"

package/dist/practices/husky/check.timestamps.play.declapract.integration.test.ts

@@ -0,0 +1,148 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = integration test for the check.timestamps husky guard
+ * .why = proves the guard halts commits of files that embed a timestamp
+ *        (except .ts/.sh) with exit 2, and allows clean/exempt files with exit 0
+ * .how = build a temp git repo, stage fixtures, spawn the guard, assert exit code
+ */
+
+// the guard under test (the distributed best-practice template)
+const guardPath = path.join(
+  __dirname,
+  'best-practice/.husky/check.timestamps.sh',
+);
+
+// build a fresh temp git repo with the given files staged
+const genStagedRepo = (files: Record<string, string>): string => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'check-timestamps-'));
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  for (const [name, content] of Object.entries(files)) {
+    const full = path.join(dir, name);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+    execFileSync('git', ['add', '--', name], { cwd: dir });
+  }
+  return dir;
+};
+
+// spawn the guard against a repo; return its exit code + stdout
+const runGuard = (dir: string): { code: number | null; stdout: string } => {
+  const res = spawnSync('bash', [guardPath], { cwd: dir, encoding: 'utf-8' });
+  return { code: res.status, stdout: res.stdout };
+};
+
+describe('check.timestamps guard', () => {
+  given('[case1] a non-code file with an iso timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'snapshot.json': '{ "createdAt": "2026-06-25T14:30:00Z" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it halts with exit 2', () => {
+        expect(result.code).toEqual(2);
+      });
+      then('it prints the verbatim constraint message', () => {
+        expect(result.stdout).toContain(
+          'timestamps are forbidden in snapshots. mask them to prevent permadrift',
+        );
+      });
+      then('it names the matched file', () => {
+        expect(result.stdout).toContain('snapshot.json');
+      });
+      then('it renders the matched file:line:content detail line', () => {
+        // locks the exact halt-output shape: tree-prefixed detail line
+        expect(result.stdout).toContain(
+          '   └─ snapshot.json:1:{ "createdAt": "2026-06-25T14:30:00Z" }',
+        );
+      });
+    });
+  });
+
+  given('[case2] a non-code file with a bare time (no lead T)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'doc.md': 'released at 14:30:00 today\n' });
+      const result = runGuard(dir);
+
+      then('it halts with exit 2 (optional T prefix matches bare time)', () => {
+        expect(result.code).toEqual(2);
+      });
+    });
+  });
+
+  given('[case3] a .ts file with a timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'time.ts': "const t = '14:30:00';\n" });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (.ts is exempt)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case4] a .sh file with a timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'log.sh': "echo 'at 14:30:00Z'\n" });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (.sh is exempt)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case5] a clean non-code file with no timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'notes.md': 'hello world, no times here\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case6] a non-code file with only a date (no time)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'dated.md': 'shipped on 2026-06-25\n' });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (date alone does not match)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+
+  given('[case7] a non-code file with a timezone-offset timestamp', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'rec.yml': 'when: 2026-06-25T14:30:00+05:00\n',
+      });
+      const result = runGuard(dir);
+
+      then('it halts with exit 2 (offset tz form matches)', () => {
+        expect(result.code).toEqual(2);
+      });
+    });
+  });
+
+  given('[case8] a snapshot with a masked timestamp placeholder', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({
+        'render.test.ts.snap': '{ "createdAt": "[timestamp]" }\n',
+      });
+      const result = runGuard(dir);
+
+      then('it allows the commit with exit 0 (mask remedy is committable)', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+});