declapract-typescript-ehmpathy 0.49.7 → 0.49.9

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

@@ -15,36 +15,42 @@ concurrency:
   cancel-in-progress: true #  cancel workflows for non-latest commits
 
 jobs:
-  aws-test:
+  aws-test-terraform:
     uses: ./.github/workflows/.terraform.yml
+    # prep omits github-environment: the ahbode-prep-oidc role trusts any branch
+    # (repo-scoped sub), so no env claim is needed — only prod gates on environment.
     with:
       working-directory: provision/aws/environments/test
-      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
-  aws-prep:
+  aws-prep-terraform:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/prep
-      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
-  aws-prod:
+  aws-prod-terraform:
     uses: ./.github/workflows/.terraform.yml
     with:
       working-directory: provision/aws/environments/prod
-      github-environment: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
 
   github:
     uses: ./.github/workflows/.declastruct.yml
     with:
       wish-path: provision/github.repo/resources.ts
-      github-environment: prod
+      scope: github
+      access: prod # github repo settings are inherently a prod resource
+      github-environment-apply: prod
       creds-github-app-owner: ${{ github.repository_owner }}
       creds-github-app-id: ${{ vars.DECLASTRUCT_GITHUB_CONFORMER_APP_ID }}
     secrets:
@@ -52,17 +58,44 @@ jobs:
 
   sql-schema-prep:
     uses: ./.github/workflows/.sql-schema-control.yml
+    # prep omits github-environment (repo-scoped oidc role, any branch, no env claim)
     with:
       stage: prep
-      github-environment: prep
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
 
   sql-schema-prod:
     uses: ./.github/workflows/.sql-schema-control.yml
     with:
       stage: prod
-      github-environment: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
       allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
       creds-aws-region: us-east-1
-      creds-aws-role-arn: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}
+
+  aws-prep-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    # prep omits github-environment (repo-scoped oidc role, any branch, no env claim)
+    with:
+      wish-path: provision/aws/resources.ts
+      scope: aws
+      access: prep
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PREP_OIDC_ROLE_ARN }}
+
+  aws-prod-declastruct:
+    uses: ./.github/workflows/.declastruct.yml
+    with:
+      wish-path: provision/aws/resources.ts
+      scope: aws
+      access: prod
+      github-environment-plan: production-on-else-plan
+      github-environment-apply: production-on-main # tags cut from main; carries the tag v* deploy policy
+      allow-apply: ${{ startsWith(github.ref, 'refs/tags/') }} # only apply to prod on tags
+      creds-aws-region: us-east-1
+      creds-aws-role-arn-plan: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_PLAN_ROLE_ARN }}
+      creds-aws-role-arn-apply: ${{ vars.CREDS_CICD_AWS_PROD_OIDC_APPLY_ROLE_ARN }}

package/dist/practices/cicd-service/best-practice/package.json

@@ -1,7 +1,7 @@
 {
   "devDependencies": {
     "declastruct": "@declapract{check.minVersion('1.9.1')}",
-    "declastruct-aws": "@declapract{check.minVersion('1.5.0')}",
+    "declastruct-aws": "@declapract{check.minVersion('1.9.0')}",
     "declastruct-unix-network": "@declapract{check.minVersion('1.0.5')}"
   }
 }

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

@@ -1,5 +1,6 @@
 {
   "dependencies": {
+    "sdk-aws-s3": "@declapract{check.minVersion('0.1.1')}",
     "sdk-config": "@declapract{check.minVersion('0.1.1')}",
     "zod": "@declapract{check.minVersion('4.0.0')}"
   }

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

@@ -1,6 +1,17 @@
 import { z } from 'zod';
 
-export const schema = z.object({
+/** .what = the two oidc grant scopes config can be read under. */
+export type Grant = 'plan' | 'apply';
+
+/**
+ * .what = the base config shape, before any grant-scoped secrets are added.
+ * .why = this base template carries no reader-denied secrets, so plan and apply
+ *        infer the same schema. services that add secrets (e.g. api keys, db
+ *        credentials) should make each reader-denied secret grant-aware via a
+ *        secret() helper so the prod plan job's oidc role tolerates the miss —
+ *        see the persist-with-rds config.schema.ts for the full pattern.
+ */
+const base = z.object({
   organization: z.string(),
   project: z.string(),
   environment: z.object({
@@ -12,4 +23,22 @@ export const schema = z.object({
   }),
 });
 
-export type Config = z.infer<typeof schema>;
+/**
+ * .what = one schema per grant. apply = the default (every secret required);
+ *         plan = the reader-denied secrets optional.
+ * .why = getConfig picks which to parse with by grant (see getConfig.ts).
+ */
+export const schema = {
+  apply: base,
+  plan: base,
+} as const;
+
+/**
+ * .what = the config type for a grant, default apply.
+ * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
+ *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
+ *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
+ */
+export type Config<TGrant extends Grant = 'apply'> = z.infer<
+  (typeof schema)[TGrant]
+>;

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

@@ -1,3 +1,4 @@
+import { sdkAwsS3 } from 'sdk-aws-s3';
 import type { DirectoryToPersistTo } from 'simple-on-disk-cache';
 import { isPresent } from 'type-fns';
 
@@ -20,14 +21,22 @@ export const getProjectBucket = async (): Promise<string> => {
  * .what = gets the project's default cache directory, based on config
  */
 export const getCacheDirectory = async (
-  input: {
-    scope?: string;
-  } = {},
-): Promise<DirectoryToPersistTo> => ({
-  s3: {
-    bucket: await getProjectBucket(),
-    prefix: ['purpose=cache', input.scope ? `scope=${input.scope}` : undefined]
-      .filter(isPresent)
-      .join('/'),
-  },
-});
+  input: { scope?: string } = {},
+): Promise<DirectoryToPersistTo> => {
+  // build the s3 uri prefix from the project bucket + cache scope
+  const bucket = await getProjectBucket();
+  const prefix = [
+    'purpose=cache',
+    input.scope ? `scope=${input.scope}` : undefined,
+  ]
+    .filter(isPresent)
+    .join('/');
+
+  // persist to s3 via the sdk-aws-s3 cloud adapter
+  return {
+    cloud: {
+      path: `s3://${bucket}/${prefix}`,
+      via: sdkAwsS3,
+    },
+  };
+};

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

@@ -5,15 +5,46 @@ import {
 import { createCache } from 'simple-in-memory-cache';
 
 import { envStatic } from '../environment';
-import { schema } from './config.schema';
+import { type Config, type Grant, schema } from './config.schema';
 
-export const getConfig = genGetConfig({
-  schema,
-  statics: 'config/*.json',
-  cache: createCache({ expiration: { minutes: 5 } }),
+// one loader per grant. both read the same config/*.json + suppliers; they differ
+// only in which schema arbitrates the reader-denied secrets (see config.schema.ts).
+// caches are separate so a plan miss never poisons the apply cache.
+const common = {
+  statics: 'config/*.json' as const,
   suppliers: [genSdkConfigSupplierAwsParameterStore()],
   environment: {
     config: envStatic.config,
     server: envStatic.server,
   },
-});
+};
+const loaders = {
+  apply: genGetConfig({
+    ...common,
+    schema: schema.apply,
+    cache: createCache({ expiration: { minutes: 5 } }),
+  }),
+  plan: genGetConfig({
+    ...common,
+    schema: schema.plan,
+    cache: createCache({ expiration: { minutes: 5 } }),
+  }),
+} as const;
+
+/**
+ * .what = load the config, scoped to an oidc grant (default apply).
+ * .why = default 'apply' returns the fully-required Config, so ordinary consumers
+ *        get no `| undefined` in their config type. the plan job opts into 'plan'
+ *        (which tolerates the reader-denied secrets) either explicitly via
+ *        { grant: 'plan' } or implicitly via the GRANT=plan env — the latter lets
+ *        the ghlitch vpc tunnel (which calls getConfig() with no args) pick the
+ *        plan scope at runtime without a code change.
+ */
+export function getConfig<TGrant extends Grant = 'apply'>(input?: {
+  grant?: TGrant;
+}): Promise<Config<TGrant>> {
+  const grant = (input?.grant ??
+    (process.env.GRANT === 'plan' ? 'plan' : 'apply')) as TGrant;
+
+  return loaders[grant]() as Promise<Config<TGrant>>;
+}