declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/practices/cicd-service/provision.yml.declapract.integration.test.ts

@@ -0,0 +1,182 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+// executeApply is slow (full usecase evaluation), so widen the jest budget
+jest.setTimeout(180_000); // 3 minutes
+
+/**
+ * .what = end-to-end proof of the D28 provision.yml rds-jobs gate, run through the REAL declapract
+ *   apply pipeline against a genTempDir consumer. per `rule.require.declapract-integration-tests`, a
+ *   `contents` fn that GENERATES a file from another source (the superset) is REQUIRED to carry a
+ *   pipeline test — a unit test of the exported `contents`/`withoutRdsJobs` never exercises the
+ *   glob→file match, the `projectPractices` derivation through a real usecase, nor the emitted file a
+ *   consumer actually receives.
+ * .why = the declaration branches on `context.projectPractices.includes('persist-with-rds')`. only a
+ *   real apply proves declapract (1) matches the declaration to `.github/workflows/provision.yml`,
+ *   (2) derives `projectPractices` from the resolved usecase (present for `lambda-service-with-rds`,
+ *   absent for `lambda-service`), (3) CREATES the absent best-practice file, and (4) emits the
+ *   superset for an rds consumer vs the narrowed workflow (4 rds jobs stripped) for a non-rds one —
+ *   the exact D28/#573 end-state the gate exists to deliver.
+ * .note = the apply is scoped by `file` ONLY, never by `practice`. a `--practice cicd-service` filter
+ *   narrows `projectPractices` to `['cicd-service']` (getDesiredPractices), which would strip
+ *   `persist-with-rds` from the derivation and silence the rds branch. file-only keeps every usecase
+ *   practice in `projectPractices` while it applies just the provision.yml plan.
+ * .note = because the apply is file-only (no `--practice` filter), declapract compiles EVERY practice
+ *   under the config's `practices:` dir. pointed at the real `src/practices` (~40 practices) that
+ *   blew the jest hook timeout, so the fixture symlinks a lean `declarations/` MIRROR that carries
+ *   only cicd-service + a persist-with-rds name-marker — the exact pattern the environments
+ *   old-stage-enum pipeline test uses. the mirror is the `src/.test/assets/cicd-service/declarations`
+ *   symlink below; the demo-repo's use.yml points its `declarations:` at it.
+ * .note = the emitted file is snapshotted in full (both usecases) plus the source superset, so a
+ *   reviewer eyeballs the exact strip diff, per `rule.require.declapract-integration-tests`.
+ */
+
+const FIXTURE = './src/practices/cicd-service/.test/assets/demo-repo-service';
+const DECLARATIONS_MIRROR = './src/.test/assets/cicd-service/declarations';
+const PROVISION_PATH = '.github/workflows/provision.yml';
+const SOURCE_SUPERSET =
+  'src/practices/cicd-service/best-practice/.github/workflows/provision.yml';
+
+const RDS_JOBS = [
+  'sql-schema-prep:',
+  'sql-schema-prod:',
+  'aws-prep-declastruct:',
+  'aws-prod-declastruct:',
+];
+const GENERIC_JOBS = [
+  'github:',
+  'aws-test-terraform:',
+  'aws-prep-terraform:',
+  'aws-prod-terraform:',
+];
+
+describe('provision.yml — the D28 rds-jobs gate, end to end', () => {
+  given('[case1] an rds-usecase consumer (lambda-service-with-rds)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-cicd-service-provision-rds',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const exists = async (rel: string): Promise<boolean> =>
+      fs
+        .access(path.join(tempDir, rel))
+        .then(() => true)
+        .catch(() => false);
+    const applyProvision = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.rds.yml'),
+        file: PROVISION_PATH,
+      });
+
+    const state = useBeforeAll(async () => {
+      const before = await exists(PROVISION_PATH);
+      await applyProvision();
+      const after1 = await read(PROVISION_PATH);
+      await applyProvision(); // second apply — prove a fixed point
+      const after2 = await read(PROVISION_PATH);
+      return { before, after1, after2 };
+    }, 170_000);
+
+    when('[t0] before any apply', () => {
+      then('the consumer has no provision.yml yet', () => {
+        expect(state.before).toBe(false);
+      });
+    });
+
+    when('[t1] the cicd-service provision declaration is applied', () => {
+      then('the created file holds ALL 4 rds jobs', () => {
+        for (const job of RDS_JOBS) expect(state.after1).toContain(job);
+      });
+
+      then('the generic jobs are present too', () => {
+        for (const job of GENERIC_JOBS) expect(state.after1).toContain(job);
+      });
+
+      then('the emitted rds workflow matches snapshot', () => {
+        expect(state.after1).toMatchSnapshot(
+          'provision.yml — rds usecase (emitted superset)',
+        );
+      });
+    });
+
+    when('[t2] the declaration is applied a second time', () => {
+      then('the second apply is a no-op (idempotent)', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
+
+  given('[case2] a non-rds consumer (lambda-service)', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-cicd-service-provision-nords',
+      clone: FIXTURE,
+      symlink: [
+        { at: 'declarations', to: DECLARATIONS_MIRROR },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const read = (rel: string) => fs.readFile(path.join(tempDir, rel), 'utf-8');
+    const applyProvision = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.nords.yml'),
+        file: PROVISION_PATH,
+      });
+
+    const state = useBeforeAll(async () => {
+      await applyProvision();
+      const after1 = await read(PROVISION_PATH);
+      await applyProvision(); // second apply — prove a fixed point
+      const after2 = await read(PROVISION_PATH);
+      return { after1, after2 };
+    }, 170_000);
+
+    when('[t0] the cicd-service provision declaration is applied', () => {
+      then('the emitted workflow STRIPS all 4 rds jobs', () => {
+        for (const job of RDS_JOBS) expect(state.after1).not.toContain(job);
+      });
+
+      then('the generic jobs survive the strip', () => {
+        for (const job of GENERIC_JOBS) expect(state.after1).toContain(job);
+      });
+
+      then(
+        'the emitted narrowed workflow matches snapshot (the strip diff a reviewer eyeballs)',
+        () => {
+          expect(state.after1).toMatchSnapshot(
+            'provision.yml — non-rds usecase (emitted, narrowed)',
+          );
+        },
+      );
+    });
+
+    when('[t1] the declaration is applied a second time', () => {
+      then('the second apply is a no-op (idempotent)', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
+
+  given('[case3] the shipped source superset the strip acts on', () => {
+    // the strip's INPUT — snapshotted as the "before" a reviewer diffs the narrowed emit against,
+    // since a fresh consumer starts with NO provision.yml (case1/case2 [t0] prove the absence).
+    when('[t0] the practice ships its provision.yml superset', () => {
+      then('the source superset holds all 4 rds jobs + matches snapshot', async () => {
+        const superset = await fs.readFile(SOURCE_SUPERSET, 'utf-8');
+        for (const job of RDS_JOBS) expect(superset).toContain(job);
+        for (const job of GENERIC_JOBS) expect(superset).toContain(job);
+        expect(superset).toMatchSnapshot(
+          'provision.yml — source superset (before strip)',
+        );
+      });
+    });
+  });
+});

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

@@ -1,6 +1,6 @@
 {
   "dependencies": {
-    "visualogic": "@declapract{check.minVersion('1.3.2')}",
-    "@ehmpathy/as-command": "@declapract{check.minVersion('1.0.1')}"
+    "visualogic": "@declapract{check.minVersion('1.3.3')}",
+    "@ehmpathy/as-command": "@declapract{check.minVersion('1.0.5')}"
   }
 }

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

@@ -1,14 +1,15 @@
 import { asCommand } from '@ehmpathy/as-command';
 import { getResourceNameFromFileName } from 'visualogic';
 
-import { stage } from '../../utils/environment';
+import { access } from '../../utils/environment';
 import { log } from '../../utils/logger';
 import { COMMANDS_OUTPUT_DIRECTORY } from './__tmp__/directory';
 
 const command = asCommand(
   {
     name: getResourceNameFromFileName(__filename),
-    stage,
+    stage: access, // as-command names this field `stage`; it takes the access
+
     dir: COMMANDS_OUTPUT_DIRECTORY,
     log,
   },

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

@@ -0,0 +1,116 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the `old-dev-config-location` relocate + tier-migrate, run
+ *         through the REAL declapract apply pipeline against a genTempDir clone of a consumer
+ *         repo (the blocker.1 / row-4 clamp).
+ * .why  = the fix both RELOCATES `config/dev.json` → `config/prep.json` (a `relativeFilePath`
+ *         rewrite) AND TRANSFORMS the content via `migrateDevConfigToPrep`. per
+ *         `rule.require.declapract-integration-tests`, 'relocate a file' and 'transform blocks'
+ *         are each rows that REQUIRE a pipeline test — a unit test of the exported `fix` never
+ *         exercises the glob→file match or the `relativeFilePath` rewrite. this is that test.
+ * .note = the config file is snapshotted in full (before AND after) so a reviewer can eyeball
+ *         the exact end-state.
+ * .teeth = the input holds `"access": "dev"` — the ONE unambiguous tier token, migrated to
+ *          `prep` — plus four host values that must each survive byte-for-byte: a `://` URL
+ *          `https://auth.myapp.dev`, a mid-dotted bare host `bastion.dev.example.com`, a
+ *          terminal bare host `aws.ssmproxy.mydb.dev`, and a foreign public host
+ *          `api.dev.paypal.com`. a `.dev` label is axis-ambiguous WHEREVER it sits, so per
+ *          guard #3 (a rewrite that cannot verify its output must not guess) NO host is
+ *          rewritten. the after-state proves the tier migrate, all four hosts preserved, the
+ *          relocation, and that NO `@declapract:review` bytes ever enter the emitted config.
+ */
+describe('config — old-dev-config-location relocate + tier-migrate (row-4 clamp)', () => {
+  given('[case1] a repo with a config/dev.json to migrate', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-config-old-dev-config-location',
+      clone: './src/practices/config/.test/assets/demo-repo-with-dev-config',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const devPath = 'config/dev.json';
+    const prepPath = 'config/prep.json';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const exists = async (relativePath: string): Promise<boolean> =>
+      fs
+        .access(path.join(tempDir, relativePath))
+        .then(() => true)
+        .catch(() => false);
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'config',
+        file: devPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('config/dev.json holds the dev tier + matches snapshot', async () => {
+        const before = await read(devPath);
+        expect(before).toContain('"access": "dev"');
+        expect(before).toMatchSnapshot('config/dev.json — before');
+      });
+    });
+
+    when('[t1] the relocate + migrate fix is applied', () => {
+      useThen('migrate the dev config', async () => applyMigrate());
+
+      then(
+        'config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot',
+        async () => {
+          // the relocation landed: the new path exists, the old path is unlinked
+          expect(await exists(prepPath)).toBe(true);
+          expect(await exists(devPath)).toBe(false);
+
+          const after = await read(prepPath);
+          // the access itself is the one unambiguous token → migrated
+          expect(after).toContain('"access": "prep"');
+          expect(after).not.toContain('"access": "dev"');
+          // EVERY host survives byte-for-byte. the util runs on the CONSUMER's real config, whose
+          // host values are the consumer's own — a `.dev` label is axis-ambiguous WHEREVER it sits,
+          // so per guard #3 (a rewrite that cannot verify its output must not guess) NO host is
+          // rewritten.
+          expect(after).toContain('bastion.dev.example.com');
+          expect(after).toContain('aws.ssmproxy.mydb.dev');
+          expect(after).toContain('https://auth.myapp.dev');
+          // the FOREIGN public host is the decisive corruption case: a mid-dotted `dev` that is a
+          // foreign host's own label must survive byte-for-byte. teeth: the prior mid-dotted
+          // rewrite turned this into `api.prep.paypal.com`, a silent public-endpoint corruption
+          // (i013 r7.b1) surfaced only by a human read of the apply diff.
+          expect(after).toContain('api.dev.paypal.com');
+          expect(after).not.toContain('api.prep.paypal.com');
+          // no host was flipped to `.prep`, so no wrong-tier value ever enters the config
+          expect(after).not.toContain('bastion.prep.example.com');
+          expect(after).not.toContain('aws.ssmproxy.mydb.prep');
+          // the migration never emits a value it cannot verify — no marker bytes in config
+          expect(after).not.toContain('@declapract:review');
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('config/prep.json — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // config/dev.json is gone after the first relocate, so the EXISTS check no longer
+      // fires and no fix runs — config/prep.json must be untouched (per
+      // rule.require.idempotent-fixes).
+      const passes = useThen(
+        'a second apply over the already-migrated repo',
+        async () => {
+          const before = await read(prepPath);
+          await applyMigrate();
+          const after = await read(prepPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/config/.test/assets/demo-repo-with-dev-config/config/dev.json

@@ -0,0 +1,17 @@
+{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}

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

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

package/dist/practices/config/.test/assets/demo-repo-with-dev-config/declapract.use.yml

@@ -0,0 +1,9 @@
+declarations: './'
+useCase: lambda-service
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'
+  infrastructureNamespaceId: 'test'
+  awsAccountId:
+    prep: '123456789012'
+    prod: '123456789012'

package/dist/practices/config/.test/assets/demo-repo-with-dev-config/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/config/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,43 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`config — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] a repo with a config/dev.json to migrate when: [t0] the migration input (before any fix) then: config/dev.json holds the dev tier + matches snapshot: config/dev.json — before 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "dev"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;
+
+exports[`config — old-dev-config-location relocate + tier-migrate (row-4 clamp) given: [case1] a repo with a config/dev.json to migrate when: [t1] the relocate + migrate fix is applied then: config/prep.json now holds the migrated content + config/dev.json is gone + matches snapshot: config/prep.json — after 1`] = `
+"{
+  "organization": "test-org",
+  "project": "test-project",
+  "environment": {
+    "access": "prep"
+  },
+  "database": {
+    "host": "bastion.dev.example.com",
+    "tunnel": "aws.ssmproxy.mydb.dev"
+  },
+  "upstream": {
+    "paypal": "api.dev.paypal.com"
+  },
+  "auth": {
+    "callbackUrl": "https://auth.myapp.dev"
+  }
+}
+"
+`;

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prep.json.declapract.ts

@@ -7,9 +7,9 @@ export const check: FileCheckFunction = async (contents, context) => {
   if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
 
   // grab the desired keys
-  const testConfigJsonContents = await readFile(
-    `${context.getProjectRootDirectory()}/config/test.json`,
-  );
+  const testConfigJsonContents = await readFile({
+    filePath: `${context.getProjectRootDirectory()}/config/test.json`,
+  });
   if (!testConfigJsonContents)
     throw new Error('can only check if test file exists');
   const testConfigObject = JSON.parse(testConfigJsonContents);

package/dist/practices/config/bad-practices/divergent-config-shapes/config/prod.json.declapract.ts

@@ -7,9 +7,9 @@ export const check: FileCheckFunction = async (contents, context) => {
   if (!contents) throw new Error('its fine'); // ... yeah, i know, todo: eliminate this weird "throw an error if its fine" pattern
 
   // grab the desired keys
-  const testConfigJsonContents = await readFile(
-    `${context.getProjectRootDirectory()}/config/test.json`,
-  );
+  const testConfigJsonContents = await readFile({
+    filePath: `${context.getProjectRootDirectory()}/config/test.json`,
+  });
   if (!testConfigJsonContents)
     throw new Error('can only check if test file exists');
   const testConfigObject = JSON.parse(testConfigJsonContents);

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

@@ -1,21 +1,19 @@
 import { FileCheckType, type FileFixFunction } from 'declapract';
 
+import { asPrepConfigPath } from '../../../../../utils/asPrepConfigPath';
+import { migrateDevConfigToPrep } from '../../../../../utils/migrateDevConfigToPrep';
+
 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(/\.dev\b/g, '.prep')
-      .replace(/"access":\s*"dev"/, '"access": "prep"');
-  }
+  // move config/dev.json → config/prep.json and migrate the tier tokens (dev → prep).
+  // both halves are shared utils, one source for both declarers: migrateDevConfigToPrep
+  // owns the content migration, asPrepConfigPath owns the relocate.
+  const fixed = contents ? migrateDevConfigToPrep({ contents }) : contents;
   return {
     contents: fixed ?? null,
-    relativeFilePath: context.relativeFilePath.replace(
-      /^config\/dev\.json$/,
-      'config/prep.json',
-    ),
+    relativeFilePath: asPrepConfigPath({
+      relativeFilePath: context.relativeFilePath,
+    }),
   };
 };

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

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

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

@@ -39,12 +39,31 @@ const loaders = {
  *        { 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.
+ * .name = `getConfig` is the org-canonical re-export of sdk-config's `genGetConfig`, called
+ *         `getConfig()` at every consumer site (the ghlitch vpc tunnel among them). it is an
+ *         external-package contract name, so it is exempt from the get-set-gen One/All cardinality
+ *         rule — a rename to `getOneConfig` breaks every consumer + diverges from sdk-config vocab.
  */
-export function getConfig<TGrant extends Grant = 'apply'>(input?: {
-  grant?: TGrant;
-}): Promise<Config<TGrant>> {
-  const grant = (input?.grant ??
+export const getConfig = <TGrant extends Grant = 'apply'>(
+  input: { grant: TGrant | null } = { grant: null },
+): Promise<Config<TGrant>> => {
+  // as-cast — why types miss: the runtime fallback yields the string literal
+  //   'plan' | 'apply', but the compiler cannot prove that value equals the
+  //   caller's free type parameter TGrant, so it stays `string`, not `TGrant`.
+  // correct type: the resolved value IS the caller's TGrant (a caller who omits
+  //   `grant` gets the default 'apply', which is TGrant's default).
+  // removal path: a `genGetConfig` overload keyed by the grant literal (or a
+  //   distributive conditional over TGrant) lets ts infer TGrant from the input
+  //   and drops this assertion.
+  const grant = (input.grant ??
     (process.env.GRANT === 'plan' ? 'plan' : 'apply')) as TGrant;
 
+  // as-cast — why types miss: `loaders` is a fixed { apply, plan } map keyed by
+  //   the literal grants; a lookup by the free TGrant loses the per-key return
+  //   type, so ts widens the result to the union of both loaders' returns.
+  // correct type: `Promise<Config<TGrant>>` — the loader at key TGrant returns
+  //   exactly the config for that grant.
+  // removal path: same as above — a per-grant overload or a distributive
+  //   conditional narrows the map lookup per-key and drops this assertion.
   return loaders[grant]() as Promise<Config<TGrant>>;
-}
+};

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

@@ -0,0 +1,33 @@
+import { sdkAwsS3 } from 'sdk-aws-s3';
+import type { DirectoryToPersistTo } from 'simple-on-disk-cache';
+import { isPresent } from 'type-fns';
+
+import { getOneProjectBucket } from './getOneProjectBucket';
+
+/**
+ * .what = casts a cache scope into its s3 uri prefix path
+ * .why = keeps the 'purpose=cache[/scope=<scope>]' pattern in one named place
+ */
+const asCachePrefix = (input: { scope: string | null }): string =>
+  ['purpose=cache', input.scope ? `scope=${input.scope}` : undefined]
+    .filter(isPresent)
+    .join('/');
+
+/**
+ * .what = gets the project's default cache directory, based on config
+ */
+export const getOneCacheDirectory = async (
+  input: { scope: string | null },
+): Promise<DirectoryToPersistTo> => {
+  // get the project bucket, then the scoped cache prefix
+  const bucket = await getOneProjectBucket();
+  const prefix = asCachePrefix({ scope: input.scope });
+
+  // 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/getOneProjectBucket.ts

@@ -0,0 +1,22 @@
+import { getConfig } from './getConfig';
+
+/**
+ * .what = casts config coordinates into the project's s3 bucket name
+ * .why = keeps the '<project>-<namespace>-<access>' pattern in one named place
+ */
+const asProjectBucketName = (input: {
+  config: Awaited<ReturnType<typeof getConfig>>;
+}): string =>
+  [
+    input.config.project,
+    input.config.aws.namespace,
+    input.config.environment.access,
+  ].join('-');
+
+/**
+ * .what = gets the project's default s3 bucket, based on config
+ */
+export const getOneProjectBucket = async (): Promise<string> => {
+  const config = await getConfig();
+  return asProjectBucketName({ config });
+};

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

@@ -1,3 +1,9 @@
-// this is a placeholder file, so that the declared acceptance test file passes typescript type checking. for this practice, we only check that the file exists
-export const stage = 'placeholder' as any;
-export const Stage = 'placeholder' as any;
+// note = a placeholder boundary. this practice only checks that the file EXISTS (it never
+//        checks its contents); the `environments` practice is the sole real declarer of
+//        `src/utils/environment.ts` and supplies the typed exports. this stub exists solely so
+//        the declared acceptance test file type-checks in a consumer that has `config` but not
+//        yet `environments`. removal path = when a consumer converges the `environments`
+//        practice, its real file overwrites this stub. the exports are typed `string` — no cast:
+//        the real `access` export is a tier string, so `string` is the honest widened type here
+//        and needs no `as`.
+export const access: string = 'placeholder';

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

@@ -1,3 +1,11 @@
 import { FileCheckType } from 'declapract';
 
+/**
+ * .what = an EXISTS-only check on `src/utils/environment.ts`.
+ * .why = the `environments` practice, not `config`, authors the real `environment.ts`. this
+ *        practice only asserts the file is present. under BEST_PRACTICE purpose an EXISTS check
+ *        resolves `fix: null` (see declapract's getFileCheckDeclaration), so the peer template's
+ *        `as any` placeholder body is never written to a consumer — the contents are structurally
+ *        unreachable. safe to leave until the tracked CONTAINS-over-real-exports cleanup lands (D55).
+ */
 export const check = FileCheckType.EXISTS;