declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/pnpm/bad-practices/stale-patched-dependency/package.json.declapract.ts

@@ -0,0 +1,74 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+import { getAllStalePatchKeys } from '../../../../utils/getAllStalePatchKeys';
+import { getFileTextOrNull } from '../../../../utils/getFileTextOrNull';
+
+const PRACTICE = 'pnpm/stale-patched-dependency';
+
+/**
+ * .what = the repo's pnpm lockfile, or null when it has none
+ */
+const getLockfile = (input: { root: string }): string | null =>
+  getFileTextOrNull({ root: input.root, relativePath: 'pnpm-lock.yaml' });
+
+/**
+ * .what = detects a package.json whose `pnpm.patchedDependencies` pins a version the lockfile no
+ *         longer resolves (#680)
+ * .why  = such a patch applies to no install: pnpm warns on it (under `allowUnusedPatches`) or
+ *         refuses the install (without it). the patch is dead weight a human must retire by hand
+ * .note = bad-practice semantics: a RETURN means detected, a THROW means not detected
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents) throw new Error('does not match bad practice');
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const keys = getAllStalePatchKeys({
+    patchedDependencies: packageJSON.pnpm?.patchedDependencies ?? {},
+    lockfile: getLockfile({ root: context.getProjectRootDirectory() }),
+  });
+  if (keys.length) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = drops each stale patch key, and an empty map or pnpm block left behind
+ * .why  = the patch file itself is deleted by the `patches/` declaration beside this one
+ * .note = a fixed point: once the stale keys are gone, the check no longer detects the pattern
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return {};
+  const packageJSON = asPackageJSON({ contents }, { practice: PRACTICE });
+  const patchedDependencies: Record<string, string> =
+    packageJSON.pnpm?.patchedDependencies ?? {};
+  const keysStale = getAllStalePatchKeys({
+    patchedDependencies,
+    lockfile: getLockfile({ root: context.getProjectRootDirectory() }),
+  });
+  if (!keysStale.length) return { contents };
+
+  // the map without the stale keys
+  const patchedKept = Object.fromEntries(
+    Object.entries(patchedDependencies).filter(
+      ([key]) => !keysStale.includes(key),
+    ),
+  );
+
+  // an empty map is dropped, and so is an empty pnpm block
+  const pnpmKept = {
+    ...packageJSON.pnpm,
+    patchedDependencies: Object.keys(patchedKept).length
+      ? patchedKept
+      : undefined,
+  };
+  const pnpmHasKeys = Object.values(pnpmKept).some(
+    (value) => value !== undefined,
+  );
+
+  return {
+    contents: `${JSON.stringify(
+      { ...packageJSON, pnpm: pnpmHasKeys ? pnpmKept : undefined },
+      null,
+      2,
+    )}\n`,
+  };
+};

package/dist/practices/pnpm/bad-practices/stale-patched-dependency/patches/<star>.patch.declapract.ts

@@ -0,0 +1,41 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import path from 'node:path';
+import { getAllStalePatchKeys } from '../../../../../utils/getAllStalePatchKeys';
+import { getFileTextOrNull } from '../../../../../utils/getFileTextOrNull';
+
+/**
+ * .what = the `pnpm.patchedDependencies` key a patch file stands for, from its path
+ * .why  = pnpm names a patch `<name>@<version>.patch`, with a scope slash encoded as `__`
+ */
+const asPatchKey = (input: { relativeFilePath: string }): string =>
+  path
+    .basename(input.relativeFilePath)
+    .replace(/\.patch$/, '')
+    .replace(/^(@[^_]+)__/, '$1/');
+
+/**
+ * .what = detects a patch file whose pinned version the lockfile no longer resolves (#680)
+ * .why  = the patch applies to no install; its key is retired by the package.json declaration
+ *         beside this one, and the file goes with it
+ * .note = bad-practice semantics: a RETURN means detected, a THROW means not detected
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (contents === null) throw new Error('does not match bad practice');
+  const lockfile = getFileTextOrNull({
+    root: context.getProjectRootDirectory(),
+    relativePath: 'pnpm-lock.yaml',
+  });
+  const key = asPatchKey({ relativeFilePath: context.relativeFilePath });
+  const keysStale = getAllStalePatchKeys({
+    patchedDependencies: { [key]: context.relativeFilePath },
+    lockfile,
+  });
+  if (keysStale.length) return; // bad practice detected
+  throw new Error('does not match bad practice');
+};
+
+/**
+ * .what = deletes the stale patch file
+ */
+export const fix: FileFixFunction = () => ({ contents: null });

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

@@ -1,3 +1,7 @@
 {
-  "packageManager": "pnpm@10.34.5"
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "allowUnusedPatches": true,
+    "ignorePatchFailures": true
+  }
 }

package/dist/practices/pnpm/best-practice/package.json.declapract.ts

@@ -13,5 +13,12 @@ import { FileCheckType } from 'declapract';
  * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
  *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
  *         the org bumps the blessed version, this pin bumps and every consumer follows.
+ * .what = also declares `pnpm.allowUnusedPatches` + `pnpm.ignorePatchFailures` (#680).
+ * .why  = a patch pins one exact version; the next upgrade orphans it, and pnpm then refuses the
+ *         whole install (`ERR_PNPM_UNUSED_PATCH`, `ERR_PNPM_PATCH_FAILED`). both keys turn that
+ *         refusal into a warn, so patch-then-upgrade never halts an install. a repo with no patch
+ *         gets them too, so its first patch is already safe to upgrade past. the CONTAINS fix
+ *         deep-merges, so a repo's other `pnpm.*` keys (overrides, patchedDependencies, the build
+ *         allowlist) are kept.
  */
 export const check = FileCheckType.CONTAINS;

package/dist/practices/pnpm/stale-patched-dependency.declapract.integration.test.ts

@@ -0,0 +1,82 @@
+import fs from 'fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { genTempRepoWithDeclarationsOutside } from '../../utils/genTempRepoWithDeclarationsOutside';
+
+// executeApply evaluates the whole practice, so widen the jest budget
+jest.setTimeout(180_000);
+
+/**
+ * .what = pipeline test for the pnpm patch settings + the stale-patched-dependency bad practice (#680)
+ * .why  = only executeApply proves declapract merges `allowUnusedPatches` + `ignorePatchFailures`
+ *         into a repo's extant `pnpm` field (its other keys kept), reads the repo's lockfile to
+ *         judge a patch stale, drops the stale key, and deletes the stale patch file — and that a
+ *         second apply is a no-op
+ */
+describe('pnpm — a stale patch never blocks an install', () => {
+  given('[case1] a repo with one patch the lockfile moved past and one it still resolves', () => {
+    const tempDir = genTempRepoWithDeclarationsOutside({
+      slug: 'pnpm-stale-patch',
+      clone: './src/practices/pnpm/.test/assets/repo-stale-patch',
+      declarations: './src/.test/assets/pnpm/declarations',
+      symlink: [{ at: 'node_modules', to: 'node_modules' }],
+    });
+    const stalePatch = 'patches/rhachet-roles-ehmpathy@1.39.1.patch';
+    const keptPatch = 'patches/type-fns@1.21.3.patch';
+
+    const state = useBeforeAll(async () => {
+      const config = path.join(tempDir, 'declapract.use.yml');
+      const read = () =>
+        fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+      const before = await read();
+      await executeApply({ config });
+      const after1 = await read();
+      const exists1 = {
+        stale: existsSync(path.join(tempDir, stalePatch)),
+        kept: existsSync(path.join(tempDir, keptPatch)),
+      };
+      await executeApply({ config });
+      const after2 = await read();
+      return { before, after1, after2, exists1 };
+    }, 170_000);
+
+    when('[t0] the pnpm practice is applied', () => {
+      then('pnpm declares allowUnusedPatches + ignorePatchFailures', () => {
+        const pnpm = JSON.parse(state.after1).pnpm;
+        expect(pnpm.allowUnusedPatches).toEqual(true);
+        expect(pnpm.ignorePatchFailures).toEqual(true);
+      });
+
+      then("the repo's other pnpm keys are kept", () => {
+        const pnpm = JSON.parse(state.after1).pnpm;
+        expect(pnpm.overrides).toEqual({ 'react-refresh': '0.14.2' });
+      });
+
+      then('the stale patch key is retired, the resolved one kept', () => {
+        const patched = JSON.parse(state.after1).pnpm.patchedDependencies;
+        expect(patched).toEqual({
+          'type-fns@1.21.3': 'patches/type-fns@1.21.3.patch',
+        });
+      });
+
+      then('the stale patch file is deleted, the resolved one kept', () => {
+        expect(state.exists1).toEqual({ stale: false, kept: true });
+      });
+
+      then('the before + after contents match snapshot', () => {
+        expect(state.before).toMatchSnapshot('package.json — before');
+        expect(state.after1).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t1] the practice is applied a second time', () => {
+      then('the second apply is a no-op', () => {
+        expect(state.after2).toEqual(state.after1);
+      });
+    });
+  });
+});

package/dist/practices/provision-github/.test/assets/demo-repo-implicit-privacy/declapract.declare.yml

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

package/dist/practices/provision-github/.test/assets/demo-repo-implicit-privacy/declapract.use.yml

@@ -0,0 +1,5 @@
+declarations: './'
+useCase: npm-package
+variables:
+  organizationName: 'test-org'
+  projectName: 'test-project'

package/dist/practices/provision-github/.test/assets/demo-repo-implicit-privacy/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "test-project",
+  "description": "a demo repo whose visibility is implicit",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "declastruct": "1.9.2",
+    "declastruct-github": "1.8.0",
+    "sdk-logs": "0.9.2"
+  }
+}

package/dist/practices/provision-github/__snapshots__/implicit-package-privacy.declapract.integration.test.ts.snap

@@ -0,0 +1,36 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`provision-github implicit-package-privacy given: [case1] a repo whose package.json omits private when: [t0] the input, before any fix then: package.json has no private key: package.json — before 1`] = `
+"{
+  "name": "test-project",
+  "description": "a demo repo whose visibility is implicit",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "declastruct": "1.9.2",
+    "declastruct-github": "1.8.0",
+    "sdk-logs": "0.9.2"
+  }
+}
+"
+`;
+
+exports[`provision-github implicit-package-privacy given: [case1] a repo whose package.json omits private when: [t1] apply runs then: package.json declares private: true, before version: package.json — after 1`] = `
+"{
+  "name": "test-project",
+  "description": "a demo repo whose visibility is implicit",
+  "private": true,
+  "version": "1.0.0",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "declastruct": "1.9.2",
+    "declastruct-github": "1.8.0",
+    "sdk-logs": "0.9.2"
+  }
+}
+"
+`;

package/dist/practices/provision-github/bad-practices/implicit-package-privacy/package.json.declapract.ts

@@ -0,0 +1,73 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { asPackageJSON } from '../../../../utils/asPackageJSON';
+
+const PRACTICE = 'provision-github';
+
+/**
+ * .what = the root keys `private` sits after, per package-json-order, in their relative order
+ * .why = the fix inserts `private` where package-json-order wants it, so the two practices converge
+ */
+const KEYS_BEFORE_PRIVATE = ['name', 'author', 'description'];
+
+/**
+ * .what = whether a package.json declares its visibility explicitly, as a boolean `private`
+ * .why = provision-github derives repo visibility from `private`, and fails closed: only an
+ *        explicit `"private": false` makes a repo public. an absent or non-boolean key leaves the
+ *        visibility implicit, so the key must always be explicit, in sync with the repo
+ */
+const isPrivacyExplicit = (input: { pkg: Record<string, unknown> }): boolean =>
+  typeof input.pkg.private === 'boolean';
+
+/**
+ * .what = the package.json, with `"private": true` set where `private` was not an explicit boolean
+ * .note = an extant non-boolean value is replaced in place; an absent key is inserted before
+ *         `version`, else after the last of name/author/description, else first. no other key moves
+ */
+export const asPackageJsonWithPrivacyExplicit = (input: {
+  pkg: Record<string, unknown>;
+}): Record<string, unknown> => {
+  // an explicit boolean is the owner's choice; never touch it
+  if (isPrivacyExplicit({ pkg: input.pkg })) return input.pkg;
+
+  // a present, non-boolean value is replaced where it sits
+  const keys = Object.keys(input.pkg);
+  if (keys.includes('private')) return { ...input.pkg, private: true };
+  // an absent key is inserted where package-json-order places it
+  const indexVersion = keys.indexOf('version');
+  const indexAfterLead = Math.max(
+    ...KEYS_BEFORE_PRIVATE.map((key) => keys.indexOf(key)),
+  );
+  const indexInsert = indexVersion >= 0 ? indexVersion : indexAfterLead + 1;
+  const keysOrdered = [
+    ...keys.slice(0, indexInsert),
+    'private',
+    ...keys.slice(indexInsert),
+  ];
+  return Object.fromEntries(
+    keysOrdered.map((key) => [key, key === 'private' ? true : input.pkg[key]]),
+  );
+};
+
+/**
+ * .what = detects a package.json whose `private` is absent or not a boolean
+ * .note = bad-practice semantics: return = detected (fix runs); throw = not detected (skip)
+ */
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('no package.json; no privacy to declare');
+  const pkg = asPackageJSON({ contents }, { practice: PRACTICE });
+  if (isPrivacyExplicit({ pkg }))
+    throw new Error('package.json declares private explicitly');
+};
+
+/**
+ * .what = backfills `"private": true` where visibility is implicit; keeps 2-space json and an
+ *         end-of-file newline
+ */
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+  const pkg = asPackageJSON({ contents }, { practice: PRACTICE });
+  return {
+    contents: `${JSON.stringify(asPackageJsonWithPrivacyExplicit({ pkg }), null, 2)}\n`,
+  };
+};

package/dist/practices/provision-github/best-practice/.declapract.readme.md

@@ -5,3 +5,15 @@ provisions github repository settings and environments via declastruct-github-sd
 | variable | description | example |
 |----------|-------------|---------|
 | `reviewers.users` | github usernames for production deployment reviewers | `['whodisio', 'ehmpathy']` |
+
+## repo visibility fails closed
+
+- the repo provisions **private** unless `package.json` declares `"private": false`. an absent key,
+  a `null`, a string, or any other value provisions it private
+- `package.json` always declares `private` as an explicit boolean. where it is absent or not a
+  boolean, the `implicit-package-privacy` fix backfills `"private": true`. an explicit `true` or
+  `false` is never touched
+- a repo meant to be public declares `"private": false`, by hand, when its owner is ready to
+  publish that domain. no practice sets it on the owner's behalf
+- `"private": true` also makes `npm publish` refuse. a package published to npm declares
+  `"private": false`

package/dist/practices/provision-github/best-practice/provision/github.repo/resources.ts

@@ -45,11 +45,8 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     owner: '@declapract{variable.organizationName}',
     name: '@declapract{variable.projectName}',
     description: pkg.description ?? null,
-    visibility: pkg.private === true ? 'private' : 'public',
-    private: pkg.private ?? false, // todo: why do we have to specify this twice?
+    visibility: pkg.private === false ? 'public' : 'private', // fail closed: public only via an explicit `"private": false`
     homepage: pkg.homepage ?? null,
-
-    // things we haven't changed from the defaults
     archived: false,
   });
 
@@ -96,13 +93,13 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
   const branchMainProtection = DeclaredGithubBranchProtection.as({
     branch: branchMain,
 
-    enforceAdmins: true, // yes, even admins need to follow this (note: they can still take the time to go and change the settings temporarily for the exceptions)
-    allowsDeletions: false, // dont allow the `main` branch to be deleted
-    allowsForcePushes: false, // dont allow `main` branch to be force pushed to
-    requireLinearHistory: false, //  # no ugly merge commits, woo! 🎉
+    enforceAdmins: true, // admins too; an exception means a deliberate settings change
+    allowsDeletions: false,
+    allowsForcePushes: false,
+    requireLinearHistory: false, // squash-only merges (repoConfig) already keep history linear
 
     requiredStatusChecks: {
-      strict: true, // branch must be up to date. otherwise, we dont know if it will really pass once it is merged
+      strict: true, // the branch must be up to date, so a green check holds after the merge
       contexts: [
         'suite / install / pnpm',
         'suite / enshard',
@@ -113,11 +110,11 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
         'suite / test-unit',
         'suite / test-integration',
         'suite / test-acceptance-locally',
-        'pullreq-title', // "review / pullreq-title",
+        'pullreq-title',
       ],
     },
 
-    // things we haven't changed from the defaults
+    // github's defaults, declared so drift shows in a plan
     allowForkSyncing: false,
     blockCreations: false,
     lockBranch: false,
@@ -129,7 +126,9 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
 
   // ref the releasers team
   const teamReleasers = RefByUnique.as<typeof DeclaredGithubTeam>({
-    org: RefByUnique.as<typeof DeclaredGithubOrg>({ login: '@declapract{variable.organizationName}' }),
+    org: RefByUnique.as<typeof DeclaredGithubOrg>({
+      login: '@declapract{variable.organizationName}',
+    }),
     slug: 'releasers',
   });
 
@@ -157,11 +156,7 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
     reviewers: null, // no approval required — PR merge is the gate
     waitTimer: null, // no delay
     deploymentBranchPolicy: {
-      // accept both the main branch and `v*` release tags: prod deploys are
-      // triggered by a release tag cut from main (see protect-release-tags
-      // ruleset below), so the ref gate must admit that tag. a branch-only
-      // policy would have the environment reject the tag-triggered deploy.
-      // (requires declastruct-github >=1.7.2 for tag-target customPatterns.)
+      // admit `v*` tags beside main: a prod deploy is triggered by a release tag cut from main
       customPatterns: [
         { name: 'main', target: 'branch' },
         { name: 'v*', target: 'tag' },
@@ -171,26 +166,19 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
   });
 
   // declare environment for adhoc production apply from a non-main branch
-  // .why = github env "required reviewers" is Enterprise-only; on a private repo
-  //        under the Free/Pro/Team plan the api returns 422 for BOTH team and user
-  //        reviewers. so this env carries NO protection rule — the human gate lives
-  //        in aws via an `actor_id` allowlist on this env's sts trust statement
-  //        (declared org-wide in aws.auth). do NOT add `reviewers` here (it will 422 on apply).
-  //        this is a SEPARATE env from production-on-else-plan on purpose: its name is the oidc
-  //        `sub` anchor for the actor_id-gated WRITER role, so a readonly plan job (anchored to
-  //        -plan) cannot assume the writer role. do NOT collapse the two.
+  // .why = its name is the oidc `sub` anchor of the WRITER role, gated in aws by an `actor_id`
+  //        allowlist. do NOT merge it with production-on-else-plan, or a plan job could write
   const envProductionOnElseApply = DeclaredGithubEnvironment.as({
     repo,
     name: 'production-on-else-apply',
-    reviewers: null, // gate is the aws actor_id allowlist, not a github reviewer
+    reviewers: null, // do NOT add reviewers: off enterprise plans, a private repo's api returns 422
     waitTimer: null,
     deploymentBranchPolicy: null, // any branch
     preventSelfReview: false,
   });
 
   // declare environment for production plan from any branch (readonly, no approval)
-  // .why = a SEPARATE env from production-on-else-apply on purpose: its name is the oidc `sub`
-  //        anchor for the READONLY plan role, so a plan job cannot assume the writer role.
+  // .why = its name is the oidc `sub` anchor of the READONLY plan role
   const envProductionOnElsePlan = DeclaredGithubEnvironment.as({
     repo,
     name: 'production-on-else-plan',
@@ -201,9 +189,7 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
   });
 
   // restrict who may cut `v*` release tags to the rhelease app only
-  // .why = prod apply is gated on a release tag cut from main; if anyone could push a
-  //        `v*` tag, that gate is bypassable. this ruleset blocks create/move/delete of
-  //        `v*` tags for everyone except the rhelease app (the github half of the oidc guarantee)
+  // .why = prod apply is gated on a release tag; a tag anyone could push is no gate
   const rulesetReleaseTags = DeclaredGithubRepoRuleset.as({
     repo,
     name: 'protect-release-tags',
@@ -225,8 +211,7 @@ export const getResources = async (): Promise<DomainEntity<any>[]> => {
       refNameExclude: [],
     },
 
-    // enforce release-tag immutability: only the bypass actor may create, move, or delete
-    // matched tags. a released `v1.2.3` must never be re-pointed or removed once cut
+    // a cut release tag is immutable: only the bypass actor may create, move, or delete it
     rules: [{ type: 'creation' }, { type: 'update' }, { type: 'deletion' }],
   });
 

package/dist/practices/provision-github/implicit-package-privacy.declapract.integration.test.ts

@@ -0,0 +1,68 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = proves through the real apply pipeline that a package.json with an implicit `private`
+ *         gains an explicit `"private": true`, and that a second apply is a no-op
+ * .why = provision-github fails closed on repo visibility; the key must always be explicit, so the
+ *        visibility a repo provisions with is the visibility its package.json declares
+ * .teeth = let the fix skip an absent key and [t1] stays without `private`
+ */
+jest.setTimeout(5 * 60 * 1000);
+
+describe('provision-github implicit-package-privacy', () => {
+  given('[case1] a repo whose package.json omits private', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-provision-github-implicit-privacy',
+      clone:
+        './src/practices/provision-github/.test/assets/demo-repo-implicit-privacy',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const read = () => fs.readFile(path.join(tempDir, 'package.json'), 'utf-8');
+    const apply = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'provision-github',
+        file: 'package.json',
+      });
+
+    when('[t0] the input, before any fix', () => {
+      then('package.json has no private key', async () => {
+        const before = await read();
+        expect(JSON.parse(before)).not.toHaveProperty('private');
+        expect(before).toMatchSnapshot('package.json — before');
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      useThen('apply the declarations', async () => apply());
+
+      then('package.json declares private: true, before version', async () => {
+        const after = await read();
+        const pkg = JSON.parse(after);
+        expect(pkg.private).toEqual(true);
+        const keys = Object.keys(pkg);
+        expect(keys.indexOf('private')).toEqual(keys.indexOf('version') - 1);
+        expect(pkg.scripts).toEqual({ build: 'tsc' });
+        expect(after.endsWith('}\n')).toEqual(true);
+        expect(after).toMatchSnapshot('package.json — after');
+      });
+    });
+
+    when('[t2] apply runs a second time', () => {
+      const scene = useThen('apply again', async () => {
+        const before = await read();
+        await apply();
+        const after = await read();
+        return { before, after };
+      });
+
+      then('package.json is a fixed point', () => {
+        expect(scene.after).toEqual(scene.before);
+      });
+    });
+  });
+});

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

@@ -24,7 +24,7 @@ describe('rhachet/prod-deps relocation', () => {
     const tempDir = genTempDir({
       slug: 'declapract-rhachet-prod-deps',
       clone: './src/practices/rhachet/bad-practices/prod-deps/.test/assets/demo-repo-with-rhachet-prod-deps',
-      symlink: [{ at: 'src', to: 'src' }],
+      symlink: [{ at: 'declarations', to: 'src' }],
     });
 
     const pkgPath = 'package.json';
@@ -56,7 +56,7 @@ describe('rhachet/prod-deps relocation', () => {
           expect(pkg.dependencies?.['rhachet']).toBeUndefined();
           expect(pkg.dependencies?.['rhachet-brains-anthropic']).toBeUndefined();
           // and now sit in dev deps (the -brains- match is the D26 proof)
-          expect(pkg.devDependencies['rhachet']).toEqual('1.47.5');
+          expect(pkg.devDependencies['rhachet']).toEqual('1.49.2');
           expect(pkg.devDependencies['rhachet-brains-anthropic']).toEqual(
             '0.4.3',
           );
@@ -88,7 +88,7 @@ describe('rhachet/prod-deps relocation', () => {
       });
 
       then('the relocated + retained deps survive the re-apply', () => {
-        expect(pkg.devDependencies['rhachet']).toEqual('1.47.5');
+        expect(pkg.devDependencies['rhachet']).toEqual('1.49.2');
         expect(pkg.devDependencies['rhachet-brains-anthropic']).toEqual('0.4.3');
         expect(pkg.dependencies.uuid).toEqual('9.0.0');
         expect(pkg.devDependencies.jest).toEqual('29.3.1');

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/.agent/repo=.this/role=any/boot.yml

@@ -5,3 +5,5 @@ briefs:
     - briefs/my-own-brief.md
   ref:
     - briefs/my-own-deep-variant.md
+    # the old practice shape put this declared glob under ref; the fix moves it to not (#689)
+    - briefs/domain.terms/term=*._.choice.reason.md

package/dist/practices/rhachet/.test/assets/demo-repo-with-consumer-boot/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/rhachet/.test/assets/repo-keyrack-extant/.agent/keyrack.yml

@@ -0,0 +1,9 @@
+org: ehmpathy
+extends:
+  - .agent/repo=ehmpathy/role=mechanic/keyrack.yml
+env.prod: null
+env.prep:
+  - OPENROUTER_API_KEY
+env.test:
+  # the local aws login, from before is-optional-if-has
+  - AWS_PROFILE

package/dist/practices/rhachet/.test/assets/repo-keyrack-extant/declapract.use.node.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/rhachet/declarations
+# .why  = the same repo with no aws practice: the keyrack.yml is left alone
+declarations: 'declarations/declapract.declare.yml'
+useCase: rhachet-node

package/dist/practices/rhachet/.test/assets/repo-keyrack-extant/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/rhachet/declarations
+# .why  = an aws repo whose keyrack.yml holds a bare AWS_PROFILE (#491)
+declarations: 'declarations/declapract.declare.yml'
+useCase: rhachet-aws

package/dist/practices/rhachet/.test/assets/repo-keyrack-extant/package.json

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

package/dist/practices/rhachet/.test/assets/repo-self-linked/declapract.use.yml

@@ -0,0 +1,4 @@
+# .note = declarations dir is symlinked by the test to src/.test/assets/rhachet/declarations
+# .why  = a rhachet roles package that self-links its roles via `link:.` (#520)
+declarations: 'declarations/declapract.declare.yml'
+useCase: rhachet-node