declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/practices/runtime-schemas/bad-practices/joi/src/<star><star>/<star>.ts.declapract.ts

@@ -4,15 +4,56 @@ import type { FileCheckFunction, FileFixFunction } from 'declapract';
  * .what = detects joi imports in source files
  * .why = joi should be replaced with zod for better typescript integration
  */
+// the review marker's stable phrase: a file that holds it was rewritten by this fix
+const REVIEW_MARKER_PHRASE = 'auto-migrated to zod';
+
+// the narrowed uuid shape a prior run of this fix emitted for a bare joi `.uuid()` (#629)
+const NARROWED_UUID_PATTERN = /z\.string\(\)\.uuid\(\s*\)/;
+
 export const check: FileCheckFunction = (contents) => {
   // match if file imports from joi
   if (contents?.includes("from 'joi'")) return;
   if (contents?.includes('from "joi"')) return;
 
+  // match a file this fix already rewrote, which still holds the narrowed uuid map (#629 backfill)
+  if (
+    contents?.includes(REVIEW_MARKER_PHRASE) &&
+    NARROWED_UUID_PATTERN.test(contents)
+  )
+    return;
+
   // no match
   throw new Error('does not import from joi');
 };
 
+/**
+ * .what = the zod call that carries a joi string-uuid's semantics, from its option text.
+ * .why  = joi's bare `.uuid()` checks the 8-4-4-4-12 layout only, so its faithful zod map is
+ *         `z.guid()`; `z.uuid()` adds the version + variant nibbles and rejects ids joi accepted
+ *         (#629). only a version option earns the strict form: a sole `uuidv4` maps to
+ *         `z.uuidv4()`, a sole other version to `z.uuid({ version })`, a set to `z.uuid()`.
+ */
+const asZodUuidCall = (input: { options: string | null }): string => {
+  const versions = Array.from(new Set(input.options?.match(/uuidv\d/g) ?? []));
+  if (versions.length === 0) return 'z.guid()';
+  if (versions.length > 1) return 'z.uuid()';
+  if (versions[0] === 'uuidv4') return 'z.uuidv4()';
+  return `z.uuid({ version: '${versions[0]!.replace('uuid', '')}' })`;
+};
+
+/**
+ * .what = rewrite each `z.string().uuid(…)` / `z.string().guid(…)` to the call that keeps joi's
+ *         semantics.
+ * .why  = applied after the `Joi.*` → `z.*` map, and on a backfill pass over a file this fix
+ *         already rewrote; a deliberate `z.uuid()` an author wrote by hand is never touched.
+ */
+const withUuidSemanticsKept = (input: { contents: string }): string =>
+  input.contents.replace(
+    /z\.string\(\)\.(?:uuid|guid)\(\s*(\{[^}]*\})?\s*\)/g,
+    (_match, options: string | undefined) =>
+      asZodUuidCall({ options: options ?? null }),
+  );
+
 /**
  * .what = a loud marker prepended to every rewritten file, so the three SILENT semantic
  *         changes this mechanical rewrite makes become visible to the consumer.
@@ -23,13 +64,16 @@ export const check: FileCheckFunction = (contents) => {
  *        once each point is verified by hand.
  */
 const reviewMarker = `/**
- * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ * @declapract:review — auto-migrated to zod; VERIFY these semantics by hand:
  *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
  *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
  *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
  *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
  *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
  *    use \`z.coerce.date()\` where the input arrives as a string.
+ *  - number coercion: the prior \`.number()\` coerced numeric strings; \`z.number()\` rejects a
+ *    string. use \`z.coerce.number()\` where the input arrives as a string (e.g. a db-hydrated
+ *    numeric or bigint column).
  * delete this marker once each point is verified.
  */
 `;
@@ -69,11 +113,15 @@ export const fix: FileFixFunction = (contents) => {
     // transform .required() → remove (zod is required by default)
     .replace(/\.required\(\)/g, '');
 
+  // keep joi's uuid semantics: a bare `.uuid()` is a layout check, so `z.guid()` (#629). this also
+  // backfills the narrowed `z.string().uuid()` a prior run of this fix left in a marker file
+  const withUuids = withUuidSemanticsKept({ contents: transformed });
+
   // prepend the review marker once, so the silent semantic guesses are loud (idempotent: the
   // check no longer fires post-rewrite, and a second pass would find the marker already present)
-  const updated = transformed.includes('@declapract:review')
-    ? transformed
-    : reviewMarker + transformed;
+  const updated = withUuids.includes('@declapract:review')
+    ? withUuids
+    : reviewMarker + withUuids;
 
   return { contents: updated };
 };

package/dist/practices/runtime-schemas/best-practice/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "zod": "@declapract{check.minVersion('3.24.0')}"
+    "zod": "@declapract{check.minVersion('4.0.0')}"
   }
 }

package/dist/practices/runtime-schemas/best-practice/package.json.declapract.ts

@@ -1,3 +1,124 @@
-import { FileCheckType } from 'declapract';
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
 
-export const check = FileCheckType.CONTAINS;
+import { asPackageJSON } from '../../../utils/asPackageJSON';
+import { isVersionBelowFloor } from '../../../utils/isVersionBelowFloor';
+import { ZOD_VERSION_PINNED } from '../../../utils/zodVersionPinned';
+
+const PRACTICE = 'runtime-schemas';
+
+/**
+ * .what = the zod floor; matches the `config` practice's floor so the two declarers agree (#624).
+ */
+const ZOD_FLOOR = '4.0.0';
+
+/**
+ * .what = whether the repo depends on sdk-aws-lambda, whose exact zod pin sets the one zod copy.
+ */
+const isOnSdkAwsLambda = (input: {
+  packageJSON: Record<string, any>;
+}): boolean =>
+  Boolean(
+    input.packageJSON.dependencies?.['sdk-aws-lambda'] ??
+      input.packageJSON.devDependencies?.['sdk-aws-lambda'],
+  );
+
+/**
+ * .what = the zod floor + the single-identity override, read from the keys pnpm actually reads.
+ * .why  = a `minVersion` template reads `dependencies` alone, so a `pnpm.overrides.zod` below the
+ *         floor read green while pnpm installed the lower copy (#624). and a repo on sdk-aws-lambda
+ *         that holds its own zod beside the sdk's exact pin resolves two zod copies, which drives
+ *         tsc out of memory (#545). so this check reads both keys, and requires
+ *         `pnpm.overrides.zod` at the sdk's exact pin wherever sdk-aws-lambda is present.
+ * .note = the override is declared by a check + fix rather than a `@declapract{…}` template, since
+ *         declapract 0.13.26 writes the literal template expression into a repo whose `pnpm` key
+ *         is absent (F26).
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) return;
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+
+  // the direct zod must be present, at or above the floor
+  const zodDeclared: string | undefined = packageJSON.dependencies?.zod;
+  if (
+    !zodDeclared ||
+    isVersionBelowFloor({ version: zodDeclared, floor: ZOD_FLOOR })
+  )
+    throw new ConstraintError(
+      `[${PRACTICE}] dependencies.zod must be >= ${ZOD_FLOOR} — run \`declapract apply\` to raise it`,
+      { found: zodDeclared ?? null, required: ZOD_FLOOR },
+    );
+
+  // the override pnpm reads must not undercut the floor either
+  const zodOverride: string | undefined = packageJSON.pnpm?.overrides?.zod;
+  if (
+    zodOverride &&
+    isVersionBelowFloor({ version: zodOverride, floor: ZOD_FLOOR })
+  )
+    throw new ConstraintError(
+      `[${PRACTICE}] pnpm.overrides.zod (${zodOverride}) undercuts the zod floor ${ZOD_FLOOR}; pnpm installs the override — run \`declapract apply\` to raise it`,
+      { found: zodOverride, required: ZOD_FLOOR },
+    );
+
+  // on sdk-aws-lambda, one zod copy: the override AND the direct dep name the sdk's exact pin
+  if (
+    isOnSdkAwsLambda({ packageJSON }) &&
+    (zodOverride !== ZOD_VERSION_PINNED || zodDeclared !== ZOD_VERSION_PINNED)
+  )
+    throw new ConstraintError(
+      `[${PRACTICE}] pnpm.overrides.zod and dependencies.zod must both be ${ZOD_VERSION_PINNED} (the zod sdk-aws-lambda pins), so one zod copy resolves — run \`declapract apply\` to set them`,
+      {
+        found: { override: zodOverride ?? null, dependency: zodDeclared },
+        required: ZOD_VERSION_PINNED,
+      },
+    );
+};
+
+/**
+ * .what = raise a below-floor zod to the pinned version, and on sdk-aws-lambda set the
+ *         `pnpm.overrides.zod` single-identity pin; every other key is kept.
+ * .why  = the check above names what pnpm will install; this fix makes it true with one version
+ *         constant shared with the joi fixer (#654), so the direct pin and the override agree.
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+
+  // raise the direct zod when absent or below the floor; a higher adopter choice is kept, except
+  // on sdk-aws-lambda: there the override forces the pin anyway, so a higher direct zod would only
+  // misstate the installed copy — and pnpm's override-undercuts-dependency would raise the override
+  // to it, which this fix would lower again, on every apply
+  const zodDeclared: string | undefined = packageJSON.dependencies?.zod;
+  const zodDirect =
+    isOnSdkAwsLambda({ packageJSON }) ||
+    !zodDeclared ||
+    isVersionBelowFloor({ version: zodDeclared, floor: ZOD_FLOOR })
+      ? ZOD_VERSION_PINNED
+      : zodDeclared;
+
+  // the override: the exact pin on sdk-aws-lambda; elsewhere, an undercut override is raised
+  const zodOverride: string | undefined = packageJSON.pnpm?.overrides?.zod;
+  const zodOverrideDesired = isOnSdkAwsLambda({ packageJSON })
+    ? ZOD_VERSION_PINNED
+    : zodOverride &&
+        isVersionBelowFloor({ version: zodOverride, floor: ZOD_FLOOR })
+      ? zodDirect
+      : zodOverride;
+
+  const updated = {
+    ...packageJSON,
+    dependencies: { ...packageJSON.dependencies, zod: zodDirect },
+    ...(zodOverrideDesired
+      ? {
+          pnpm: {
+            ...packageJSON.pnpm,
+            overrides: {
+              ...packageJSON.pnpm?.overrides,
+              zod: zodOverrideDesired,
+            },
+          },
+        }
+      : {}),
+  };
+  return { contents: JSON.stringify(updated, null, 2) };
+};

package/dist/practices/serverless/.declapract.integration.test.ts

@@ -1,8 +1,10 @@
 import fs from 'fs/promises';
-import { readFileSync } from 'node:fs';
+import { execSync, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import { executeApply } from 'declapract';
+import { MalfunctionError } from 'helpful-errors';
 import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
 
 jest.setTimeout(180_000);
@@ -67,6 +69,148 @@ describe('serverless practice — the dual-publish deploy split (north-star clam
       then('deploy:prune also prunes the contemp -prep- fleet (the B1 leak clamp)', () => {
         expect(scene.scripts['deploy:prune']).toContain('--stage prep');
       });
+
+      then('the ancient release refuses a dirty tree before it builds, so COMMIT names the shipped code (#668)', () => {
+        const ancient = scene.scripts['deploy:release:ancient']!;
+        expect(ancient).toContain('npm run deploy:assure:committed');
+        expect(ancient.indexOf('npm run deploy:assure:committed')).toBeLessThan(
+          ancient.indexOf('npm run build'),
+        );
+        expect(scene.scripts['deploy:assure:committed']).toContain(
+          'git status --porcelain',
+        );
+      });
+    });
+
+    when('[t1] the dirty-tree guard runs in a real git repo (#668)', () => {
+      const runGuard = (input: { dirty: boolean }) => {
+        const repo = genTempDir({ slug: `declapract-serverless-dirty-${input.dirty}` });
+        execSync('git init -q && git -c user.email=t@example.com -c user.name=t commit -q --allow-empty -m init', { cwd: repo });
+        if (input.dirty) writeFileSync(path.join(repo, 'edit.ts'), 'export {};\n');
+        const result = spawnSync('sh', ['-c', scene.scripts['deploy:assure:committed']!], {
+          cwd: repo,
+          encoding: 'utf-8',
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('a clean tree passes', () => {
+        expect(runGuard({ dirty: false }).status).toEqual(0);
+      });
+
+      then('a dirty tree exits 2 and says why', () => {
+        const result = runGuard({ dirty: true });
+        expect(result.status).toEqual(2);
+        expect(result.output).toContain('uncommitted');
+      });
+    });
+
+    when('[t2] the runtime gate is read (#553)', () => {
+      then('the ancient release loads the built artifact on the deploy runtime before it ships', () => {
+        const ancient = scene.scripts['deploy:release:ancient']!;
+        expect(ancient.indexOf('npm run build')).toBeLessThan(
+          ancient.indexOf('npm run test:runtime'),
+        );
+        expect(ancient.indexOf('npm run test:runtime')).toBeLessThan(
+          ancient.indexOf('sls deploy'),
+        );
+      });
+    });
+
+    when('[t3] the runtime gate runs against a fake docker (#553)', () => {
+      /**
+       * .what = run `test:runtime` in a temp repo with a fake `docker` first on PATH
+       * .why  = proves the preflight + the image the gate picks, with no daemon in this suite.
+       *         the fake prints its args on `run`, and answers `info` per `daemon`.
+       */
+      const runGate = (input: { daemon: boolean; runtime: string | null }) => {
+        const repo = genTempDir({
+          slug: `declapract-serverless-runtime-${input.daemon}-${input.runtime}`,
+        });
+        mkdirSync(path.join(repo, 'bin'));
+        writeFileSync(
+          path.join(repo, 'bin', 'docker'),
+          `#!/bin/sh\nif [ "$1" = info ]; then exit ${input.daemon ? 0 : 1}; fi\necho "docker $*"\n`,
+          { mode: 0o755 },
+        );
+        writeFileSync(
+          path.join(repo, 'serverless.yml'),
+          input.runtime ? `provider:\n  runtime: ${input.runtime}\n` : 'provider:\n',
+        );
+        const result = spawnSync('sh', ['-c', scene.scripts['test:runtime']!], {
+          cwd: repo,
+          encoding: 'utf-8',
+          env: { ...process.env, PATH: `${path.join(repo, 'bin')}:${process.env.PATH}` },
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('it runs the artifact in the lambda image of the serverless.yml major', () => {
+        const result = runGate({ daemon: true, runtime: 'nodejs20.x' });
+        expect(result.status).toEqual(0);
+        expect(result.output).toContain('public.ecr.aws/lambda/nodejs:20');
+        expect(result.output).toContain('/.artifact/contents:/var/task:ro');
+      });
+
+      then('no docker daemon exits 2 and names docker, never a fallback to the host node', () => {
+        const result = runGate({ daemon: false, runtime: 'nodejs20.x' });
+        expect(result.status).toEqual(2);
+        expect(result.output).toContain('docker');
+        expect(result.output).not.toContain('docker run');
+      });
+
+      then('a serverless.yml with no runtime fails before docker runs', () => {
+        const result = runGate({ daemon: true, runtime: null });
+        expect(result.status).not.toEqual(0);
+        expect(result.output).not.toContain('docker run');
+      });
+    });
+
+    when('[t4] the in-container load procedure runs over a built artifact (#553)', () => {
+      /**
+       * .what = run the in-container load procedure with the host node, over a temp artifact
+       * .why  = the image is a fake above; this proves the procedure itself loads every handler
+       *         and fails loud on one that cannot parse
+       */
+      const runLoad = (input: { handlers: Record<string, string> }) => {
+        const artifact = genTempDir({
+          slug: `declapract-serverless-load-${Object.keys(input.handlers).length}`,
+        });
+        mkdirSync(path.join(artifact, 'dist/contract/handlers/nested'), { recursive: true });
+        Object.entries(input.handlers).forEach(([name, source]) =>
+          writeFileSync(path.join(artifact, 'dist/contract/handlers', name), source),
+        );
+        // the load procedure is the single-quoted `node -e '<procedure>'` tail of `test:runtime`
+        const loadProcedure =
+          / -e '(?<procedure>.+)'$/.exec(scene.scripts['test:runtime'] ?? '')?.groups?.procedure ??
+          MalfunctionError.throw('test:runtime holds no `-e` load procedure', {
+            command: scene.scripts['test:runtime'] ?? null,
+          });
+        const result = spawnSync('node', ['-e', loadProcedure], {
+          cwd: artifact,
+          encoding: 'utf-8',
+        });
+        return { status: result.status, output: `${result.stdout}${result.stderr}` };
+      };
+
+      then('every handler, nested ones too, loads', () => {
+        const result = runLoad({
+          handlers: {
+            'getWidget.js': 'exports.handler = async () => ({});\n',
+            'nested/setWidget.js': 'exports.handler = async () => ({});\n',
+          },
+        });
+        expect(result.status).toEqual(0);
+        expect(result.output).toContain('2 handlers load on node');
+      });
+
+      then('a handler that cannot parse fails the gate', () => {
+        const result = runLoad({
+          handlers: { 'broken.js': 'exports.handler = ;\n' },
+        });
+        expect(result.status).not.toEqual(0);
+        expect(result.output).toContain('SyntaxError');
+      });
     });
   });
 
@@ -147,8 +291,9 @@ describe('serverless practice — the dual-publish deploy split (north-star clam
  *         fixed point.
  * .note = INTEGRATION: reads the filesystem + runs executeApply against a temp clone. no credential,
  *         no network. the fixture lives under a `.test` dot-dir (excluded from tsconfig/jest globs),
- *         and mounts THIS repo's real `src` via the `src`→`src` symlink so declapract resolves the
- *         serverless practice from source.
+ *         and mounts THIS repo's real `src` at `declarations` (never at `src`) so declapract resolves
+ *         the serverless practice from source while the demo repo's own `src` stays empty — a `src`
+ *         mount would make every `src/**` wildcard declaration scan the whole library.
  * .teeth = the env-block trio proves the CHAIN ORDER: withConnectionReuse anchors the legacy
  *          NODE_ENV form and MUST run before withNodeEnvProduction rewrites that value to
  *          `production`. so the presence of the connection-reuse flag beside a `NODE_ENV: production`
@@ -161,7 +306,7 @@ describe('serverless practice — the real executeApply pipeline (r001.b1)', ()
     const tempDir = genTempDir({
       slug: 'declapract-serverless-fix',
       clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
-      symlink: [{ at: 'src', to: 'src' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const ymlPath = 'serverless.yml';
@@ -227,4 +372,72 @@ describe('serverless practice — the real executeApply pipeline (r001.b1)', ()
       });
     });
   });
+
+  given('[case2] a consumer whose .nvmrc pins node 20 (#552)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-nvmrc',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const read = () => fs.readFile(path.join(tempDir, 'serverless.yml'), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'serverless',
+        file: 'serverless.yml',
+      });
+
+    when('[t1] the serverless fix is applied', () => {
+      useThen('pin .nvmrc, then apply', async () => {
+        await fs.writeFile(path.join(tempDir, '.nvmrc'), 'v20.11.1\n');
+        await applyFix();
+      });
+
+      then('the runtime follows .nvmrc, not the template major', async () => {
+        const yml = await read();
+        expect(yml).toContain('runtime: nodejs20.x');
+        expect(yml).not.toContain('nodejs22.x');
+        expect(yml).not.toContain('nodejs14.x');
+      });
+
+      then('a second apply is a no-op (the CONTAINS check passes on the derived runtime)', async () => {
+        const before = await read();
+        await applyFix();
+        expect(await read()).toEqual(before);
+      });
+    });
+  });
+
+  given('[case3] a consumer whose .nvmrc names an alias, not a major (#552)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-serverless-nvmrc-alias',
+      clone: './src/practices/serverless/.test/assets/demo-repo-with-serverless',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+
+    when('[t1] the serverless fix is applied', () => {
+      const result = useThen('pin .nvmrc to an alias, then apply', async () => {
+        await fs.writeFile(path.join(tempDir, '.nvmrc'), 'lts/*\n');
+        const error = await executeApply({
+          config: path.join(tempDir, 'declapract.use.yml'),
+          practice: 'serverless',
+          file: 'serverless.yml',
+        }).then(
+          () => null,
+          (thrown: unknown) => thrown,
+        );
+        const yml = await fs.readFile(path.join(tempDir, 'serverless.yml'), 'utf-8');
+        return { error, yml };
+      });
+
+      then('the apply fails loud and names .nvmrc, rather than guess a major', () => {
+        expect(result.error).toBeInstanceOf(Error);
+        expect((result.error as Error).message).toContain('.nvmrc');
+      });
+
+      then('the runtime line is left as found', () => {
+        expect(result.yml).toContain('nodejs14.x');
+      });
+    });
+  });
 });

package/dist/practices/serverless/.test/assets/demo-repo-with-serverless/declapract.declare.yml

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

package/dist/practices/serverless/__snapshots__/divergentStageGuard.declapract.integration.test.ts.snap

@@ -3,13 +3,15 @@
 exports[`divergent-stage guard — the shipped templates cannot re-split the stage/access axis given: [case4] the deploy-command ACCESS fall-through when: [t0] every deploy command that derives SLS_STAGE is read then: the shipped deploy commands match snapshot (a reworded message reddens): serverless deploy commands 1`] = `
 {
   "deploy": "if [ "\${ACCESS:-}" = 'prod' ]; then npm run deploy:prod; elif [ "\${ACCESS:-}" = 'prep' ]; then npm run deploy:prep; else echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi",
+  "deploy:assure:committed": "if [ -n "$(git status --porcelain)" ]; then echo '🛑 uncommitted changes: deploy ships the committed tree only, so COMMIT names the code that runs; commit or stash, then retry' && git status --short && exit 2; fi",
   "deploy:prep": "ACCESS=prep npm run deploy:release",
   "deploy:prod": "ACCESS=prod npm run deploy:release:ancient && npm run deploy:send-notification",
-  "deploy:prune": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npx sls prune -n 7 --stage "\${SLS_STAGE:-}" && if [ "\${ACCESS:-}" = 'prep' ]; then npx sls prune -n 7 --stage prep; fi",
+  "deploy:prune": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && sls prune -n 7 --stage "\${SLS_STAGE:-}" && if [ "\${ACCESS:-}" = 'prep' ]; then sls prune -n 7 --stage prep; fi",
   "deploy:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
-  "deploy:release:ancient": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npm run build && sls deploy --verbose --stage "\${SLS_STAGE:-}"",
-  "deploy:release:contemp": "export COMMIT=$(npx sdk-environment get commit) && if [ "\${ACCESS:-}" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
+  "deploy:release:ancient": "if [ "\${ACCESS:-}" != 'prep' ] && [ "\${ACCESS:-}" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && npm run deploy:assure:committed && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ "\${ACCESS:-}" = 'prep' ] && echo 'dev' || echo "\${ACCESS:-}") && npm run build && npm run test:runtime && sls deploy --verbose --stage "\${SLS_STAGE:-}"",
+  "deploy:release:contemp": "export COMMIT=$(sdk-environment get commit) && if [ "\${ACCESS:-}" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
   "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data "{\\"text\\":\\"$([ -z "\${DEPLOYER_NAME:-}" ] && git config user.name || echo "\${DEPLOYER_NAME:-}") has deployed $npm_package_name@v$npm_package_version:
 https://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\"}" @declapract{variable.slackWebhookUrl}",
+  "test:runtime": "docker info > /dev/null 2>&1 || { echo '🛑 docker absent: test:runtime loads the built artifact on the deploy runtime, in the lambda image; start the docker daemon, then retry' && exit 2; } && LAMBDA_NODE_MAJOR=$(node -p "require('fs').readFileSync('serverless.yml', 'utf8').match(/runtime: nodejs([0-9]+)[.]x/)[1]") && docker run --rm -e ACCESS -e COMMIT -v "$PWD/.artifact/contents:/var/task:ro" -w /var/task --entrypoint node public.ecr.aws/lambda/nodejs:\${LAMBDA_NODE_MAJOR} -e 'const fs = require("fs"), p = require("path"); const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(p.join(d, e.name)) : e.name.endsWith(".js") ? [p.join(d, e.name)] : [])); const files = walk("dist/contract/handlers"); if (!files.length) throw new Error("no handlers in dist/contract/handlers"); files.forEach((f) => require(p.join(process.cwd(), f))); console.log("✔ " + files.length + " handlers load on node " + process.versions.node);'",
 }
 `;

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

@@ -30,8 +30,8 @@ a contemp→prod 404 is therefore unreachable, because the `sdkAwsLambdaEnvAcces
 target helper resolves against the CALLER's OWN `access`, not a fixed `-prep-` string. a prod-access
 caller resolves BOTH `Ancient` and `Contemp` to `prod` (there is no dev/prep split at prod), so it
 always addresses the published `-prod-` fleet. the `-prep-` slug is only ever emitted by a
-`prep`-access caller, which addresses `prep`-tier peers — never a prod service. a `prep`-access
-caller that reaches a prod service is a cross-tier call, which is not a supported pattern and is not
+`prep`-access caller, which addresses the `-prep-` peers its `prep` access reaches — never a prod
+service. a `prep`-access caller that reaches a prod service is a cross-access call, which is not a supported pattern and is not
 what dual-publish covers. so prod's ancient-only publish leaves no cross-service call uncovered.
 
 the north-star of the fix-lambdas wish is to retire the `stage` axis entirely; this dual-publish is

package/dist/practices/serverless/best-practice/package.json

@@ -1,13 +1,14 @@
 {
   "devDependencies": {
     "serverless": "@declapract{check.minVersion('2.57.0')}",
-    "serverless-prune-plugin": "@declapract{check.minVersion('2.0.2')}",
-    "if-env": "@declapract{check.minVersion('1.0.4')}"
+    "serverless-prune-plugin": "@declapract{check.minVersion('2.0.2')}"
   },
   "scripts": {
-    "deploy:prune": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npx sls prune -n 7 --stage \"${SLS_STAGE:-}\" && if [ \"${ACCESS:-}\" = 'prep' ]; then npx sls prune -n 7 --stage prep; fi",
-    "deploy:release:ancient": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(npx sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npm run build && sls deploy --verbose --stage \"${SLS_STAGE:-}\"",
-    "deploy:release:contemp": "export COMMIT=$(npx sdk-environment get commit) && if [ \"${ACCESS:-}\" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
+    "deploy:prune": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && sls prune -n 7 --stage \"${SLS_STAGE:-}\" && if [ \"${ACCESS:-}\" = 'prep' ]; then sls prune -n 7 --stage prep; fi",
+    "deploy:assure:committed": "if [ -n \"$(git status --porcelain)\" ]; then echo '🛑 uncommitted changes: deploy ships the committed tree only, so COMMIT names the code that runs; commit or stash, then retry' && git status --short && exit 2; fi",
+    "deploy:release:ancient": "if [ \"${ACCESS:-}\" != 'prep' ] && [ \"${ACCESS:-}\" != 'prod' ]; then echo '🛑 invalid ACCESS, must be prod or prep' && exit 2; fi && npm run deploy:assure:committed && export COMMIT=$(sdk-environment get commit) && export SLS_STAGE=$([ \"${ACCESS:-}\" = 'prep' ] && echo 'dev' || echo \"${ACCESS:-}\") && npm run build && npm run test:runtime && sls deploy --verbose --stage \"${SLS_STAGE:-}\"",
+    "test:runtime": "docker info > /dev/null 2>&1 || { echo '🛑 docker absent: test:runtime loads the built artifact on the deploy runtime, in the lambda image; start the docker daemon, then retry' && exit 2; } && LAMBDA_NODE_MAJOR=$(node -p \"require('fs').readFileSync('serverless.yml', 'utf8').match(/runtime: nodejs([0-9]+)[.]x/)[1]\") && docker run --rm -e ACCESS -e COMMIT -v \"$PWD/.artifact/contents:/var/task:ro\" -w /var/task --entrypoint node public.ecr.aws/lambda/nodejs:${LAMBDA_NODE_MAJOR} -e 'const fs = require(\"fs\"), p = require(\"path\"); const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(p.join(d, e.name)) : e.name.endsWith(\".js\") ? [p.join(d, e.name)] : [])); const files = walk(\"dist/contract/handlers\"); if (!files.length) throw new Error(\"no handlers in dist/contract/handlers\"); files.forEach((f) => require(p.join(process.cwd(), f))); console.log(\"✔ \" + files.length + \" handlers load on node \" + process.versions.node);'",
+    "deploy:release:contemp": "export COMMIT=$(sdk-environment get commit) && if [ \"${ACCESS:-}\" = 'prep' ]; then sls deploy --verbose --stage prep; else echo '🛑 skip contemp dual-publish: ACCESS is not prep (contemp publishes the -prep- fleet only)'; fi",
     "deploy:release": "npm run deploy:release:ancient && npm run deploy:release:contemp",
     "deploy:send-notification": "curl -X POST -H 'Content-type: application/json' --data \"{\\\"text\\\":\\\"$([ -z \"${DEPLOYER_NAME:-}\" ] && git config user.name || echo \"${DEPLOYER_NAME:-}\") has deployed $npm_package_name@v$npm_package_version:\nhttps://github.com/@declapract{variable.organizationName}/$npm_package_name/tree/v$npm_package_version\\\"}\" @declapract{variable.slackWebhookUrl}",
     "deploy:prep": "ACCESS=prep npm run deploy:release",

package/dist/practices/serverless/best-practice/serverless.yml

@@ -27,7 +27,7 @@ provider:
   stage: ${opt:stage}
   stackTags:
     app: @declapract{variable.organizationName}
-    environment: ${self:custom.access} # the ACCESS tier (test|prep|prod), NOT the deploy stage slug — a -dev-fleet stack is still access=prep, so a `stage`-valued tag would read as the two-word lie the access axis retired; matches the ACCESS env var below
+    environment: ${self:custom.access} # the access (test|prep|prod), NOT the deploy stage slug — a -dev-fleet stack is still access=prep, so a `stage`-valued tag would read as the two-word lie the access axis retired; matches the ACCESS env var below
     product: ${self:service}
   environment:
     TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success