declapract-typescript-ehmpathy 0.47.67 → 0.47.69

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

@@ -15,18 +15,18 @@
 #   - Any time you need to ensure the database is ready before proceeding
 #
 # Usage:
-#   STAGE=dev ./.agent/repo=.this/skills/use.rds.capacity.sh
+#   ACCESS=prep ./.agent/repo=.this/skills/use.rds.capacity.sh
 #
 # Prerequisites:
-#   - STAGE environment variable must be set
+#   - ACCESS environment variable must be set
 #   - AWS credentials configured with SSM access
 #   - sudo access (for /etc/hosts modification via vpc tunnel)
 #   - pg_isready command available (postgresql-client)
 #
 set -eo pipefail
 
-# failfast if STAGE is not declared
-[[ -z "${STAGE:-}" ]] && echo "STAGE is not set" && exit 1
+# failfast if ACCESS is not declared
+[[ -z "${ACCESS:-}" ]] && echo "ACCESS is not set" && exit 1
 
 set -u
 

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

@@ -63,7 +63,7 @@ jobs:
           fail-on-cache-miss: true
 
       - name: deploy
-        run: STAGE=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy
+        run: ACCESS=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy
 
   assure:
     runs-on: ubuntu-24.04
@@ -92,10 +92,10 @@ jobs:
 
       - name: vpc:tunnel:open
         if: inputs.needs-vpn-for-acceptance
-        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
+        run: ACCESS=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: test:acceptance
-        run: STAGE=${{ inputs.stage }} npm run test:acceptance
+        run: ACCESS=${{ inputs.stage }} npm run test:acceptance
 
       - name: alarm on failure
         env:
@@ -132,4 +132,4 @@ jobs:
           fail-on-cache-miss: true
 
       - name: prune
-        run: STAGE=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy:prune
+        run: ACCESS=${{ inputs.stage }} DEPLOYER_NAME=$GITHUB_ACTOR npm run deploy:prune

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

@@ -60,10 +60,10 @@ jobs:
           aws-region: ${{ inputs.creds-aws-region }}
 
       - name: vpc:tunnel:open
-        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
+        run: ACCESS=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: plan
-        run: STAGE=${{ inputs.stage }} npm run provision:schema:plan | tee ./plan.log
+        run: ACCESS=${{ inputs.stage }} npm run provision:schema:plan | tee ./plan.log
 
       - name: evaluate plan
         id: evaluate-plan
@@ -115,7 +115,7 @@ jobs:
           aws-region: ${{ inputs.creds-aws-region }}
 
       - name: vpc:tunnel:open
-        run: STAGE=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
+        run: ACCESS=${{ inputs.stage }} .agent/repo=.this/skills/use.vpc.tunnel.ts
 
       - name: apply
-        run: STAGE=${{ inputs.stage }} npm run provision:schema:apply
+        run: ACCESS=${{ inputs.stage }} npm run provision:schema:apply

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

@@ -53,7 +53,7 @@ jobs:
   sql-schema-dev:
     uses: ./.github/workflows/.sql-schema-control.yml
     with:
-      stage: dev
+      stage: prep
       github-environment: dev
       creds-aws-region: us-east-1
       creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_DEV_OIDC_ROLE_ARN }}

package/dist/practices/commands/best-practice/src/contract/commands/sayHello.ts

@@ -15,5 +15,5 @@ const command = asCommand(
   async () => console.log('hello world'),
 );
 
-// STAGE=prod npx tsx src/contract/commands/sayHello.ts
+// ACCESS=prod npx tsx src/contract/commands/sayHello.ts
 if (require.main === module) void command({});

package/dist/practices/config/bad-practices/old-config-with-paramstore-dep/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "config-with-paramstore": "@declapract{check.minVersion('0.0.0')}"
+  }
+}

package/dist/practices/config/bad-practices/old-config-with-paramstore-dep/package.json.declapract.ts

@@ -0,0 +1,18 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const packageJSON = JSON.parse(contents);
+  const updatedPackageJSON = {
+    ...packageJSON,
+    dependencies: {
+      ...packageJSON.dependencies,
+      'config-with-paramstore': undefined,
+    },
+  };
+  return {
+    contents: JSON.stringify(updatedPackageJSON, null, 2),
+  };
+};

package/dist/practices/config/bad-practices/old-config-with-paramstore-dts/nontyped_modules/config-with-paramstore.d.ts.declapract.ts

@@ -0,0 +1,8 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  // delete the file - sdk-config replaces config-with-paramstore
+  return { contents: null };
+};

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

@@ -0,0 +1,18 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move config/dev.json → config/prep.json and update access: dev → prep
+  let fixed = contents;
+  if (fixed) {
+    fixed = fixed.replace(/"access":\s*"dev"/, '"access": "prep"');
+  }
+  return {
+    contents: fixed ?? null,
+    relativeFilePath: context.relativeFilePath.replace(
+      /^config\/dev\.json$/,
+      'config/prep.json',
+    ),
+  };
+};

package/dist/practices/config/bad-practices/old-parameterstorenamespace-key/config/prep.json

@@ -0,0 +1,3 @@
+{
+  "parameterStoreNamespace": "@declapract{check.minVersion('0.0.0')}"
+}

package/dist/practices/config/bad-practices/old-parameterstorenamespace-key/config/prep.json.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const config = JSON.parse(contents);
+  const { parameterStoreNamespace: _, ...rest } = config;
+  return {
+    contents: JSON.stringify(rest, null, 2),
+  };
+};

package/dist/practices/config/bad-practices/old-parameterstorenamespace-key/config/prod.json

@@ -0,0 +1,3 @@
+{
+  "parameterStoreNamespace": "@declapract{check.minVersion('0.0.0')}"
+}

package/dist/practices/config/bad-practices/old-parameterstorenamespace-key/config/prod.json.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const config = JSON.parse(contents);
+  const { parameterStoreNamespace: _, ...rest } = config;
+  return {
+    contents: JSON.stringify(rest, null, 2),
+  };
+};

package/dist/practices/config/best-practice/config/{dev.json → prep.json}

@@ -1,9 +1,8 @@
 {
-  "parameterStoreNamespace": "@declapract{variable.organizationName}.@declapract{variable.projectName}.dev",
   "organization": "@declapract{variable.organizationName}",
   "project": "@declapract{variable.projectName}",
   "environment": {
-    "access": "dev"
+    "access": "prep"
   },
   "aws": {
     "account": "@declapract{variable.awsAccountId.dev}",

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

@@ -1,5 +1,4 @@
 {
-  "parameterStoreNamespace": "@declapract{variable.organizationName}.@declapract{variable.projectName}.prod",
   "organization": "@declapract{variable.organizationName}",
   "project": "@declapract{variable.projectName}",
   "environment": {

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

@@ -1,5 +1,4 @@
 {
-  "parameterStoreNamespace": "@declapract{variable.organizationName}.@declapract{variable.projectName}.test",
   "organization": "@declapract{variable.organizationName}",
   "project": "@declapract{variable.projectName}",
   "environment": {

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

@@ -1,5 +1,7 @@
 {
   "dependencies": {
-    "config-with-paramstore": "@declapract{check.minVersion('1.1.1')}"
+    "sdk-config": "@declapract{check.minVersion('0.1.1')}",
+    "simple-in-memory-cache": "@declapract{check.minVersion('0.4.0')}",
+    "zod": "@declapract{check.minVersion('4.0.0')}"
   }
 }

package/dist/practices/config/best-practice/src/utils/config/Config.ts

@@ -2,7 +2,7 @@ export interface Config {
   organization: string;
   project: string;
   environment: {
-    access: 'test' | 'dev' | 'prod';
+    access: 'test' | 'prep' | 'prod';
   };
   aws: {
     account: string;

package/dist/practices/config/best-practice/src/utils/config/config.schema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+export const schema = z.object({
+  organization: z.string(),
+  project: z.string(),
+  environment: z.object({
+    access: z.enum(['test', 'prep', 'prod']),
+  }),
+  aws: z.object({
+    account: z.string(),
+    namespace: z.string(),
+  }),
+});
+
+export type Config = z.infer<typeof schema>;

package/dist/practices/config/best-practice/src/utils/config/getConfig.ts

@@ -1,9 +1,19 @@
-// export a default instance of the config object
-import ConfigCache from 'config-with-paramstore';
+import {
+  genGetConfig,
+  genSdkConfigSupplierAwsParameterStore,
+} from 'sdk-config';
+import { createCache } from 'simple-in-memory-cache';
 
-import { getEnvironment } from '../environment';
-import type { Config } from './Config';
+import { envStatic } from '../environment';
+import { schema } from './config.schema';
 
-export const configInstance = new ConfigCache();
-export const getConfig = async (): Promise<Config> =>
-  configInstance.get((await getEnvironment()).config);
+export const getConfig = genGetConfig({
+  schema,
+  statics: 'config/*.json',
+  cache: createCache({ expiration: { minutes: 5 } }),
+  suppliers: [genSdkConfigSupplierAwsParameterStore()],
+  environment: {
+    config: envStatic.config,
+    server: envStatic.server,
+  },
+});

package/dist/practices/environments/bad-practices/old-stage-enum/src/<star><star>/<star>.ts.declapract.ts

@@ -0,0 +1,37 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('does not match bad practice');
+
+  // check for Stage enum usage
+  if (
+    contents.includes('Stage.PRODUCTION') ||
+    contents.includes('Stage.DEVELOPMENT') ||
+    contents.includes('Stage.TEST')
+  )
+    return; // bad practice detected
+
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  let fixed = contents
+    // replace enum values with string literals
+    .replace(/Stage\.PRODUCTION/g, "'prod'")
+    .replace(/Stage\.DEVELOPMENT/g, "'prep'")
+    .replace(/Stage\.TEST/g, "'test'")
+    // remove Stage import if no longer used
+    .replace(/import\s*\{\s*Stage\s*\}\s*from\s*['"][^'"]+['"];\n?/g, '')
+    .replace(
+      /import\s*\{\s*([^}]*),\s*Stage\s*\}\s*from/g,
+      'import { $1 } from',
+    )
+    .replace(
+      /import\s*\{\s*Stage\s*,\s*([^}]*)\}\s*from/g,
+      'import { $1 } from',
+    );
+
+  return { contents: fixed };
+};

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

@@ -1,7 +1,5 @@
 {
   "dependencies": {
-    "@aws-sdk/client-iam": "@declapract{check.minVersion('3.940.0')}",
-    "with-simple-cache": "@declapract{check.minVersion('0.15.1')}",
-    "simple-in-memory-cache": "@declapract{check.minVersion('0.4.0')}"
+    "sdk-environment": "@declapract{check.minVersion('0.1.3')}"
   }
 }

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

@@ -1,166 +1,8 @@
-import {
-  IAMClient,
-  ListAccountAliasesCommand,
-  type ListAccountAliasesCommandOutput,
-} from '@aws-sdk/client-iam';
-import { UnexpectedCodePathError } from 'helpful-errors';
-import { createCache } from 'simple-in-memory-cache';
-import { createIsOfEnum, type Literalize } from 'type-fns';
-import { withSimpleCache } from 'with-simple-cache';
+import { getEnvironment } from 'sdk-environment';
 
-import { log } from './logger';
+export { getEnvironment };
 
-export enum ConfigChoice {
-  PRODUCTION = 'prod',
-  DEVELOPMENT = 'dev',
-  TEST = 'test',
-}
-export const isOfConfigChoice = createIsOfEnum(ConfigChoice);
+export const envStatic = getEnvironment.static();
 
-export enum Access {
-  PRODUCTION = 'prod',
-  DEVELOPMENT = 'dev',
-}
-export const isOfAccess = createIsOfEnum(Access);
-
-export enum Stage { // todo: deprecate stage
-  PRODUCTION = 'prod',
-  DEVELOPMENT = 'dev',
-  TEST = 'test',
-}
-export const isOfStage = createIsOfEnum(Stage);
-
-/**
- * ensure that the server is on UTC timezone
- *
- * why?
- * - non UTC timezone usage causes consistency problems and takes a while to track down
- * - by warning and correcting if the server the code runs on in is not in UTC, we avoid these issues
- * - instead, users should push down converting from UTC into the users TZ as far as possible
- */
-const TIMEZONE = process.env.TZ;
-if (TIMEZONE !== 'UTC') {
-  log.debug(
-    'env.TZ is not set to UTC. this can cause issues. updating this on your behalf',
-    { found: TIMEZONE, desire: 'UTC' },
-  );
-  process.env.TZ = 'UTC';
-}
-
-/**
- * this allows us to infer what the stage should be in environments that do not have STAGE specified
- * - e.g., when running locally
- * - e.g., when running tests
- */
-const inferStageFromNodeEnv = () => {
-  const nodeEnv = process.env.NODE_ENV; // default to test if not defined
-  if (!nodeEnv) throw new Error('process.env.NODE_ENV must be defined');
-  if (nodeEnv === 'production') return Stage.PRODUCTION;
-  if (nodeEnv === 'development') return Stage.DEVELOPMENT;
-  if (nodeEnv === 'test') return Stage.TEST;
-  throw new Error(`unexpected nodeEnv '${nodeEnv}'`);
-};
-
-/**
- * a method that exposes relevant environmental variables in a standard way
- */
-export const getStage = (): Stage => {
-  const stage = process.env.STAGE ?? inferStageFromNodeEnv(); // figure it out from NODE_ENV if not explicitly defined
-  if (!stage) throw new Error('process.env.STAGE must be defined');
-  if (!isOfStage(stage)) throw new Error(`invalid stage defined '${stage}'`);
-  return stage;
-};
-export const stage: Stage = getStage(); // todo: deprecate
-
-// export service client stage // todo: deprecate
-export const serviceClientStage =
-  stage === Stage.PRODUCTION ? Stage.PRODUCTION : Stage.DEVELOPMENT; // i.e., if its prod, hit prod. otherwise, dev
-
-/**
- * .what = infer access (prod/dev) from curernt credentials
- *
- * .why?
- * - allows detection of the access grain we are currently authenticated into, if authenticated
- * - account aliases typically contain the environment (e.g., 'ahbode-dev', 'ahbode-prod')
- */
-export const inferAccess = withSimpleCache(
-  async (): Promise<Access | null> => {
-    // skip aws api calls if no credentials are configured
-    if (!process.env.AWS_PROFILE && !process.env.AWS_ACCESS_KEY_ID) return null;
-
-    // grab the alias of the current account
-    const iam = new IAMClient({});
-    const response: ListAccountAliasesCommandOutput = await iam.send(
-      new ListAccountAliasesCommand({}),
-    );
-
-    // infer access from alias
-    const alias = response.AccountAliases?.[0];
-    if (alias?.includes('prod')) return Access.PRODUCTION;
-    if (alias?.includes('dev')) return Access.DEVELOPMENT;
-    throw new Error(`Could not infer access from account alias '${alias}'`);
-  },
-  { cache: createCache() },
-);
-
-/**
- * infer stage from access (prod/dev)
- *
- * logic:
- * - if NODE_ENV === 'test', return test (test environment always uses test config)
- * - otherwise, defer to access from AWS credentials
- */
-const inferConfigChoice = async (): Promise<ConfigChoice> => {
-  // grab some facts
-  const access = await inferAccess();
-  const envarNode = process.env.NODE_ENV;
-  const envarConfig = process.env.CONFIG ?? process.env.STAGE; // fallback to stage as alias to config choice
-
-  // if access is against prod, then must use prod config; no exceptions
-  if (access === Access.PRODUCTION) return ConfigChoice.PRODUCTION;
-
-  // if access is against prep and asked for dev, then use dev config
-  if (access === Access.DEVELOPMENT && envarConfig === 'dev')
-    return ConfigChoice.DEVELOPMENT;
-
-  // if access is against prep and asked for test, then use test config
-  if (access === Access.DEVELOPMENT && envarNode === 'test')
-    return ConfigChoice.TEST;
-
-  // if access is against prep and not asked for test, then must use dev config
-  if (access === Access.DEVELOPMENT) return ConfigChoice.DEVELOPMENT;
-
-  // otherwise, unsupported
-  throw new UnexpectedCodePathError(
-    'Could not infer config choice: NODE_ENV is not test and no valid access could be determined',
-    { access, envarNode, envarConfig },
-  );
-};
-
-// export the v3 environmental variables
-export interface Environment {
-  /**
-   * .what = the choice of config to execute against
-   */
-  config: Literalize<ConfigChoice>;
-
-  /**
-   * .what = the resources accessible from this environment, if any
-   */
-  access: Literalize<Access> | null;
-
-  /**
-   * .what = the server that hosts this environment
-   */
-  server: 'CICD' | 'AWS:LAMBDA' | 'LOCAL';
-}
-export const getEnvironment = async (): Promise<Environment> => ({
-  config: await inferConfigChoice(),
-  access: await inferAccess(),
-  server: (() => {
-    if (process.env.CI) return 'CICD' as const;
-    if (process.env.LAMBDA_TASK_ROOT) return 'AWS:LAMBDA' as const;
-    return 'LOCAL' as const; // default to local
-  })(),
-  // region: // todo
-});
+export const stage = envStatic.access === 'prep' ? 'dev' : envStatic.access;
+export const serviceClientStage = stage === 'prod' ? 'prod' : 'dev';

package/dist/practices/persist-with-dynamodb/best-practice/jest.integration.env.ts

@@ -1,5 +1,7 @@
+import { stage } from './src/utils/environment';
+
 /**
  * specify that dynamodb should use the local dynamodb database, if running in test env
  */
-if (stage === Stage.TEST)
+if (stage === 'test')
   process.env.USE_CUSTOM_DYNAMODB_ENDPOINT = 'http://localhost:7337';

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

@@ -0,0 +1,19 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // move config/dev.json → config/prep.json and update .dev → .prep references
+  const updatedContents = contents
+    ?.replace(/\.dev\b/g, '.prep')
+    .replace(/"access":\s*"dev"/, '"access": "prep"')
+    .replace(/"__CHANG3_ME__"/g, '"$.at(aws::param)"');
+
+  return {
+    contents: updatedContents ?? null,
+    relativeFilePath: context.relativeFilePath.replace(
+      /^config\/dev\.json$/,
+      'config/prep.json',
+    ),
+  };
+};

package/dist/practices/persist-with-rds/bad-practices/old-param-placeholder/config/<star>.json.declapract.ts

@@ -0,0 +1,14 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (contents?.includes('__PARAM__')) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  return {
+    contents: contents.replace(/"__PARAM__"/g, '"$.at(aws::param)"'),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/config/{dev.json → prep.json}

@@ -7,20 +7,20 @@
     "role": {
       "cicd": {
         "username": "@declapract{variable.databaseUserName.cicdUser}",
-        "password": "__CHANG3_ME__"
+        "password": "$.at(aws::param)"
       },
       "crud": {
         "username": "@declapract{variable.databaseUserName.serviceUser}",
-        "password": "__CHANG3_ME__"
+        "password": "$.at(aws::param)"
       }
     },
     "tunnel": {
       "local": {
-        "host": "@declapract{variable.databaseTunnelHost.dev}",
+        "host": "@declapract{variable.databaseTunnelHost.prep}",
         "port": 15432
       },
       "lambda": {
-        "host": "@declapract{variable.databaseClusterHost.dev}",
+        "host": "@declapract{variable.databaseClusterHost.prep}",
         "port": 5432
       }
     }

package/dist/practices/persist-with-rds/best-practice/config/prod.json

@@ -7,11 +7,11 @@
     "role": {
       "cicd": {
         "username": "@declapract{variable.databaseUserName.cicdUser}",
-        "password": "__PARAM__"
+        "password": "$.at(aws::param)"
       },
       "crud": {
         "username": "@declapract{variable.databaseUserName.serviceUser}",
-        "password": "__PARAM__"
+        "password": "$.at(aws::param)"
       }
     },
     "tunnel": {

package/dist/practices/persist-with-rds/best-practice/package.json

@@ -25,6 +25,6 @@
     "provision:testdb:docker:down": "docker compose -f ./provision/docker/testdb/docker-compose.yml down",
     "provision:testdb": "npm run provision:testdb:docker:clear && npm run provision:testdb:docker:prepare && npm run provision:testdb:docker:up && npm run provision:testdb:docker:await && npm run provision:schema:plan && npm run provision:schema:apply && npm run provision:schema:plan",
     "start:testdb": "npm run provision:testdb",
-    "start:livedb:dev": "echo 'will ping the database until assured its not asleep' && STAGE=dev .agent/repo=.this/skills/use.rds.capacity.sh"
+    "start:livedb:prep": "echo 'will ping the database until assured its not asleep' && ACCESS=prep .agent/repo=.this/skills/use.rds.capacity.sh"
   }
 }

package/dist/practices/persist-with-rds/best-practice/provision/schema/connection.config.js

@@ -1,15 +1,16 @@
-const Config = require('config-with-paramstore').default;
-
-const configInstance = new Config();
-const getConfig = async () =>
-  configInstance.get(process.env.STAGE || undefined);
+/**
+ * .what = database credentials for sql-schema-control
+ * .why = reuses app's getConfig for consistent config resolution
+ */
+require('esbuild-register');
+const { getConfig } = require('../../src/utils/config/getConfig');
 
 const promiseSchemaControlCredentials = async () => {
   const config = await getConfig();
   const credentials = {
     host: config.database.tunnel.local.host,
     port: config.database.tunnel.local.port,
-    database: config.database.target.database, // i.e., db = schema
+    database: config.database.target.database,
     schema: config.database.target.schema,
     username: config.database.role.cicd.username,
     password: config.database.role.cicd.password,

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+export const schema = z.object({
+  organization: z.string(),
+  project: z.string(),
+  environment: z.object({
+    access: z.enum(['test', 'prep', 'prod']),
+  }),
+  aws: z.object({
+    account: z.string(),
+    namespace: z.string(),
+  }),
+  database: z.object({
+    target: z.object({
+      database: z.string(),
+      schema: z.string(),
+    }),
+    role: z.object({
+      cicd: z.object({
+        username: z.string(),
+        password: z.string(),
+      }),
+      crud: z.object({
+        username: z.string(),
+        password: z.string(),
+      }),
+    }),
+    tunnel: z.object({
+      local: z.object({
+        host: z.string(),
+        port: z.number(),
+      }),
+      lambda: z
+        .object({
+          host: z.string(),
+          port: z.number(),
+        })
+        .nullable(),
+    }),
+  }),
+});
+
+export type Config = z.infer<typeof schema>;

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts.declapract.ts

@@ -0,0 +1,47 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+const databaseSchema = `  database: z.object({
+    target: z.object({
+      database: z.string(),
+      schema: z.string(),
+    }),
+    role: z.object({
+      cicd: z.object({
+        username: z.string(),
+        password: z.string(),
+      }),
+      crud: z.object({
+        username: z.string(),
+        password: z.string(),
+      }),
+    }),
+    tunnel: z.object({
+      local: z.object({
+        host: z.string(),
+        port: z.number(),
+      }),
+      lambda: z
+        .object({
+          host: z.string(),
+          port: z.number(),
+        })
+        .nullable(),
+    }),
+  }),`;
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // if database schema already present, return as-is
+  if (contents.includes('database: z.object(')) return { contents };
+
+  // add database schema before the close of the main object
+  const fixed = contents.replace(
+    /(\s*)\}\);(\s*\n\s*export type Config)/,
+    `$1${databaseSchema}\n});$2`,
+  );
+
+  return { contents: fixed };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getDatabaseConnection.ts

@@ -47,7 +47,7 @@ export const getDatabaseConnection = async (): Promise<DatabaseConnection> => {
 
   // determine which tunnel to use based on environment.server
   const tunnel =
-    environment.server === 'AWS:LAMBDA'
+    environment.server === 'cloud@aws.lambda'
       ? config.database.tunnel.lambda
       : config.database.tunnel.local;
 

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

@@ -5,11 +5,11 @@
     "if-env": "@declapract{check.minVersion('1.0.4')}"
   },
   "scripts": {
-    "deploy:prune": "npx sls prune -n 7 --stage $STAGE",
-    "deploy:release": "npm run build && sls deploy --verbose --stage $STAGE",
+    "deploy:prune": "SLS_STAGE=$(if [ \"$ACCESS\" = 'prep' ]; then echo 'dev'; else echo \"$ACCESS\"; fi) && export COMMIT=$(npx sdk-environment get commit) && npx sls prune -n 7 --stage $SLS_STAGE",
+    "deploy:release": "SLS_STAGE=$(if [ \"$ACCESS\" = 'prep' ]; then echo 'dev'; else echo \"$ACCESS\"; fi) && export COMMIT=$(npx sdk-environment get commit) && npm run build && sls deploy --verbose --stage $SLS_STAGE",
     "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:dev": "STAGE=dev npm run deploy:release",
-    "deploy:prod": "STAGE=prod npm run deploy:release && npm run deploy:send-notification",
-    "deploy": "if-env STAGE=prod && npm run deploy:prod && exit 0 || if-env STAGE=dev && npm run deploy:dev && exit 0 || echo '🛑 invalid STAGE, must be prod or dev' && exit 1"
+    "deploy:prep": "ACCESS=prep npm run deploy:release",
+    "deploy:prod": "ACCESS=prod npm run deploy:release && npm run deploy:send-notification",
+    "deploy": "if-env ACCESS=prod && npm run deploy:prod && exit 0 || if-env ACCESS=prep && npm run deploy:prep && exit 0 || echo '🛑 invalid ACCESS, must be prod or prep' && exit 1"
   }
 }

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

@@ -1,11 +1,18 @@
 service: @declapract{variable.projectName}
 
+variablesResolutionMode: 20210326
+
 package:
   artifact: .artifact/contents.zip
 
 plugins:
   - serverless-prune-plugin
 
+custom:
+  accessByStage:
+    dev: prep
+    prod: prod
+
 provider:
   name: aws
   runtime: nodejs22.x
@@ -19,7 +26,8 @@ provider:
   environment:
     TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
     NODE_ENV: production # deploy with production optimizations of all resources, to make `dev` and `prod` stage deployments equivalent functionally (i.e., the same code paths in dev and prod)
-    STAGE: ${self:provider.stage} # deploy specifying which stage we're targeting, to enable targeting the correct config + resources (e.g., hit dev db -vs- prod db)
+    ACCESS: ${self:custom.accessByStage.${opt:stage}, 'prep'} # sdk-environment access tier, to target the correct config + resources (e.g., hit dev db -vs- prod db)
+    COMMIT: ${env:COMMIT} # sdk-environment commit slug, must be set by deploy command
     AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
   deploymentBucket: serverless-deployment-@declapract{variable.infrastructureNamespaceId}-${self:provider.stage}
   vpc:
@@ -35,7 +43,9 @@ provider:
       Action: 'ssm:DescribeParameters'
       Resource: '*'
     - Effect: 'Allow'
-      Action: 'ssm:GetParameters'
+      Action:
+        - ssm:GetParameter
+        - ssm:GetParameters
       Resource: arn:aws:ssm:${aws:region}:${aws:accountId}:parameter/*
     - Effect: 'Allow'
       Action: 'kms:Decrypt'
@@ -110,8 +120,8 @@ provider:
         - athena:GetQueryExecution
         - athena:GetQueryResults
       Resource: '*'
-    # allow inferring access from account alias
+    # allow access inference from account name
     - Effect: Allow
       Action:
-        - iam:ListAccountAliases
+        - account:GetAccountInformation
       Resource: '*'

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

@@ -3,16 +3,23 @@ import { FileCheckType } from 'declapract';
 
 export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)
 
-const listAccountAliasesPolicy = `    # allow inferring access from account alias
+const accessInferencePolicy = `    # allow access inference from account name
     - Effect: Allow
       Action:
-        - iam:ListAccountAliases
+        - account:GetAccountInformation
       Resource: '*'`;
 
+const accessByStageCustom = `custom:
+  accessByStage:
+    dev: prep
+    prod: prod
+
+`;
+
 export const fix: FileFixFunction = (contents) => {
-  if (!contents) return { contents }; // do nothing if file dne; // TODO: update to provision file from declared contents
+  if (!contents) return { contents }; // do nothing if file dne
   let fixed = contents
-    .replace(/runtime: nodejs\d\d.x/, 'runtime: nodejs16.x')
+    .replace(/runtime: nodejs\d\d.x/, 'runtime: nodejs22.x')
     .replace(/ {2}- serverless-offline .*\n/, '') // a plugin we no longer use (never used it, no need to have it)
     .replace(/ {2}- serverless-pseudo-parameters .*\n/, '') // a plugin we no longer use (serverless supports variables natively now)
     .replace(/#\{AWS::Region\}/g, '${aws:region}') // use the serverless native variables, instead of the pseudo-parameters format
@@ -43,15 +50,58 @@ export const fix: FileFixFunction = (contents) => {
       '  timeout: 60 # default timeout to 1min, for resilience against increased cold start times; individual functions can override this', // bump the timeout
     );
 
-  // Append ListAccountAliases policy if not already present
-  if (!fixed.includes('iam:ListAccountAliases')) {
+  // add variablesResolutionMode after service line if not present
+  if (!fixed.includes('variablesResolutionMode:')) {
+    fixed = fixed.replace(
+      /^(service: [a-zA-Z0-9-]+)\n/m,
+      '$1\n\nvariablesResolutionMode: 20210326\n',
+    );
+  }
+
+  // add custom accessByStage block before provider if not present
+  if (!fixed.includes('accessByStage:')) {
+    fixed = fixed.replace(/\nprovider:/, `\n${accessByStageCustom}provider:`);
+  }
+
+  // replace STAGE env var with ACCESS + COMMIT pattern
+  if (
+    fixed.includes('STAGE: ${self:provider.stage}') &&
+    !fixed.includes('ACCESS:')
+  ) {
+    fixed = fixed.replace(
+      /STAGE: \$\{self:provider\.stage\}[^\n]*/,
+      "ACCESS: ${self:custom.accessByStage.${opt:stage}, 'prep'} # sdk-environment access tier, to target the correct config + resources (e.g., hit dev db -vs- prod db)\n    COMMIT: ${env:COMMIT} # sdk-environment commit slug, must be set by deploy command",
+    );
+  }
+
+  // replace old iam:ListAccountAliases with account:GetAccountInformation
+  if (fixed.includes('iam:ListAccountAliases')) {
+    fixed = fixed.replace(
+      /# allow inferring access from account alias\n\s+- Effect: Allow\n\s+Action:\n\s+- iam:ListAccountAliases\n\s+Resource: '\*'/,
+      accessInferencePolicy.trim(),
+    );
+  }
+
+  // add account:GetAccountInformation policy if not present
+  if (!fixed.includes('account:GetAccountInformation')) {
     if (/iamRoleStatements:\s*\n/.test(fixed)) {
       fixed = fixed.replace(
         /iamRoleStatements:\s*\n/,
-        `iamRoleStatements:\n${listAccountAliasesPolicy}\n`,
+        `iamRoleStatements:\n${accessInferencePolicy}\n`,
       );
     }
   }
 
+  // add ssm:GetParameter to SSM permissions if only GetParameters exists
+  if (
+    fixed.includes('ssm:GetParameters') &&
+    !fixed.includes('ssm:GetParameter\n')
+  ) {
+    fixed = fixed.replace(
+      /Action: 'ssm:GetParameters'/,
+      'Action:\n        - ssm:GetParameter\n        - ssm:GetParameters',
+    );
+  }
+
   return { contents: fixed };
 };

package/dist/practices/tests/best-practice/jest.integration.env.ts

@@ -27,29 +27,50 @@ if (!existsSync(join(process.cwd(), 'package.json')))
  */
 if (
   (process.env.NODE_ENV !== 'test' ||
-    (process.env.STAGE && process.env.STAGE !== 'test')) &&
-  process.env.I_KNOW_WHAT_IM_DOING !== 'true'
+    (process.env.CONFIG && process.env.CONFIG !== 'test')) &&
+  process.env.I_KNOW_THE_RISKS !== 'true'
 )
-  throw new Error(`integration.test is not targeting stage 'test'`);
+  throw new Error(`integration.test config must be 'test'`);
 
 /**
- * .what = verify that the env has sufficient auth to run the tests if aws is used; otherwise, fail fast
- * .why =
- *   - prevent time wasted waiting on tests to fail due to lack of credentials
- *   - prevent time wasted debugging tests which are failing due to hard-to-read missed credential errors
+ * .what = source aws profile from keyrack if available
+ * .why = keyrack manages which profile to use per environment
+ */
+const keyrackYmlPath = join(process.cwd(), '.agent/keyrack.yml');
+if (existsSync(keyrackYmlPath) && !process.env.CI)
+  keyrack.source({ env: 'test', owner: 'ehmpath', mode: 'lenient' });
+
+/**
+ * .what = export aws credentials from sso profile if aws is required
+ * .why = aws sdk v2 doesn't handle sso_session profiles natively
  */
 const declapractUsePath = join(process.cwd(), 'declapract.use.yml');
 const declapractUseContent = existsSync(declapractUsePath)
   ? readFileSync(declapractUsePath, 'utf8')
   : '';
 const requiresAwsAuth = declapractUseContent.includes('awsAccountId');
-if (
-  requiresAwsAuth &&
-  !(process.env.AWS_PROFILE || process.env.AWS_ACCESS_KEY_ID)
-)
-  throw new Error(
-    'no aws credentials present. please authenticate with aws to run integration tests',
-  );
+if (requiresAwsAuth && !process.env.AWS_ACCESS_KEY_ID && !process.env.CI) {
+  const awsSsoProfile = process.env.AWS_PROFILE;
+  if (!awsSsoProfile)
+    throw new Error(
+      'AWS_PROFILE not set. keyrack.source() should have set it.',
+    );
+  try {
+    const credOutput = execSync(
+      `aws configure export-credentials --profile ${awsSsoProfile} --format env`,
+      { encoding: 'utf8', timeout: 10000 },
+    );
+    // parse and set env vars from output like "export AWS_ACCESS_KEY_ID=..."
+    credOutput.split('\n').forEach((line) => {
+      const match = line.match(/^export\s+(\w+)=(.*)$/);
+      if (match) process.env[match[1]!] = match[2]!;
+    });
+  } catch {
+    throw new Error(
+      `failed to export aws credentials from sso profile '${awsSsoProfile}'. run: aws sso login --profile ${awsSsoProfile}`,
+    );
+  }
+}
 
 /**
  * .what = verify that the testdb has been provisioned if a databaseUserName is declared
@@ -85,13 +106,3 @@ if (requiresTestDb) {
     );
   }
 }
-
-/**
- * .what = source credentials from keyrack for test env
- * .why =
- *   - auto-inject keys into process.env
- *   - fail fast with helpful error if keyrack locked or keys absent
- */
-const keyrackYmlPath = join(process.cwd(), '.agent/keyrack.yml');
-if (existsSync(keyrackYmlPath))
-  keyrack.source({ env: 'test', owner: 'ehmpath', mode: 'strict' });

package/dist/practices/tests/best-practice/jest.unit.env.ts

@@ -4,6 +4,8 @@ import util from 'node:util';
 
 import { jest } from '@jest/globals';
 
+import { stage } from './src/utils/environment';
+
 // mock that getConfig just returns plaintext test env config in unit tests
 jest.mock('./src/utils/config/getConfig', () => ({
   getConfig: jest.fn().mockImplementation(() => require('./config/test.json')),
@@ -13,7 +15,7 @@ jest.mock('./src/utils/config/getConfig', () => ({
 util.inspect.defaultOptions.depth = 5;
 
 /**
- * .what = verify that we're running from a valid project directory; otherwise, fail fast
+ * .what = verify that we're at a valid project directory; otherwise, fail fast
  * .why = prevent confusion and hard-to-debug errors from running tests in the wrong directory
  */
 if (!existsSync(join(process.cwd(), 'package.json')))
@@ -23,11 +25,8 @@ if (!existsSync(join(process.cwd(), 'package.json')))
  * sanity check that unit tests are only run the 'test' environment
  *
  * usecases
- * - prevent polluting prod state with test data
- * - prevent executing financially impacting mutations
+ * - prevent prod state pollution with test data
+ * - prevent financial mutations
  */
-if (
-  (process.env.NODE_ENV !== 'test' || process.env.STAGE) &&
-  process.env.I_KNOW_WHAT_IM_DOING !== 'true'
-)
-  throw new Error(`unit.test is not targeting stage 'test'`);
+if (stage !== 'test' && process.env.I_KNOW_THE_RISKS !== 'true')
+  throw new Error(`unit-test does not target stage 'test'`);

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

@@ -10,10 +10,10 @@
     "@swc/jest": "@declapract{check.minVersion('0.2.39')}"
   },
   "scripts": {
-    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -z \"${THOROUGH:-}\" ] && echo '--changedSince=main') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
-    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -z \"${THOROUGH:-}\" ] && echo '--changedSince=main') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
-    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
     "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
-    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')"
+    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')"
   }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "declapract-typescript-ehmpathy",
   "author": "ehmpathy",
   "description": "declapract best practices declarations for typescript",
-  "version": "0.47.67",
+  "version": "0.47.69",
   "license": "MIT",
   "main": "src/index.js",
   "repository": "ehmpathy/declapract-typescript-ehmpathy",
@@ -33,11 +33,11 @@
     "test:lint:biome": "npm run biome:nested:hide && biome check --diagnostic-level=error; EXIT=$?; npm run biome:nested:restore; exit $EXIT",
     "test:lint:biome:all": "npm run biome:nested:hide && biome check; EXIT=$?; npm run biome:nested:restore; exit $EXIT",
     "test:lint": "npm run test:lint:biome && npm run test:lint:deps",
-    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -z \"${THOROUGH:-}\" ] && echo '--changedSince=main') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
-    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -z \"${THOROUGH:-}\" ] && echo '--changedSince=main') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
-    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
+    "test:unit": "set -eu && jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:integration": "set -eu && jest -c ./jest.integration.config.ts --forceExit --verbose --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${THOROUGH:-}\" != \"true\" ] && echo '--changedSince=main') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
+    "test:acceptance:locally": "set -eu && npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
     "test": "set -eu && npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally && npm run test:validate",
-    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ -n \"${RESNAP:-}\" ] && echo '--updateSnapshot')",
+    "test:acceptance": "set -eu && npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests $([ -n \"${CI:-}\" ] && echo '--ci') $([ \"${RESNAP:-}\" = \"true\" ] && echo '--updateSnapshot')",
     "prepush": "npm run test && npm run build",
     "prepublish": "npm run build",
     "preversion": "npm run prepush",
@@ -75,12 +75,12 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.41.1",
+    "rhachet": "1.41.10",
     "rhachet-brains-anthropic": "0.4.1",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.27.5",
-    "rhachet-roles-bhuild": "0.21.1",
-    "rhachet-roles-ehmpathy": "1.35.0",
+    "rhachet-roles-bhrain": "0.27.6",
+    "rhachet-roles-bhuild": "0.21.9",
+    "rhachet-roles-ehmpathy": "1.35.5",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",
     "type-fns": "1.21.2",

package/dist/practices/config/best-practice/nontyped_modules/config-with-paramstore.d.ts

@@ -1 +0,0 @@
-declare module 'config-with-paramstore';