mandrel 2.77.0 → 2.79.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +2 -3
  3. package/.agents/audit-checklists/architecture.md +1 -0
  4. package/.agents/audit-checklists/clean-code.md +1 -0
  5. package/.agents/audit-checklists/devops.md +4 -1
  6. package/.agents/audit-checklists/security.md +1 -1
  7. package/.agents/docs/configuration.md +1 -1
  8. package/.agents/schemas/agentrc.schema.json +1 -1
  9. package/.agents/scripts/bootstrap.js +87 -16
  10. package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
  11. package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
  12. package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
  13. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
  14. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  15. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  16. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  17. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  18. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  20. package/.agents/scripts/lib/config/explain.js +2 -1
  21. package/.agents/scripts/lib/config-settings-schema.js +2 -1
  22. package/.agents/scripts/lib/findings/severity.js +33 -6
  23. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  24. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  25. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  26. package/.agents/scripts/lib/test-run-credit.js +46 -17
  27. package/.agents/workflows/audit-architecture.md +20 -4
  28. package/.agents/workflows/audit-baselines.md +3 -3
  29. package/.agents/workflows/audit-clean-code.md +17 -1
  30. package/.agents/workflows/audit-devops.md +58 -14
  31. package/.agents/workflows/audit-exceptions.md +3 -2
  32. package/.agents/workflows/audit-performance.md +22 -0
  33. package/.agents/workflows/audit-quality.md +30 -0
  34. package/.agents/workflows/audit-security.md +23 -8
  35. package/.agents/workflows/audit-to-stories.md +9 -6
  36. package/.agents/workflows/helpers/audit-lens-core.md +53 -8
  37. package/README.md +13 -1
  38. package/docs/CHANGELOG.md +22 -0
  39. package/lib/cli/registry.js +85 -12
  40. package/lib/cli/uninstall.js +34 -18
  41. package/lib/cli/update.js +37 -6
  42. package/lib/migrations/index.js +2 -0
  43. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  44. package/package.json +1 -1
@@ -43,19 +43,66 @@ with its config-driven target set; navigability always evaluates the whole
43
43
  route tree regardless of the fence). Those lenses state their deviation in
44
44
  their own Scope section; every other lens follows the rule above verbatim.
45
45
 
46
+ ## Ecosystem detection & the absent-vs-inapplicable rule {#ecosystem-detection}
47
+
48
+ A lens's Step 0 instruments are ecosystem-specific, so detect the ecosystems
49
+ from repo-observable manifests **before** running any rung:
50
+
51
+ | Ecosystem | Detected by |
52
+ | --- | --- |
53
+ | JS / TS | `package.json` |
54
+ | Python | `pyproject.toml`, `setup.cfg`, `requirements*.txt` |
55
+ | Go | `go.mod` |
56
+ | Rust | `Cargo.toml` |
57
+ | CI — GitHub Actions | `.github/workflows/*.yml` / `*.yaml` |
58
+ | CI — Google Cloud Build | `cloudbuild*.yaml` |
59
+ | CI — GitLab CI | `.gitlab-ci.yml` |
60
+ | CI — Azure Pipelines | `azure-pipelines.yml` |
61
+
62
+ Run the rung for **every** detected ecosystem — a polyglot repo gets more than
63
+ one — and name the detected set in the Executive Summary. Then:
64
+
65
+ - **Absent is a gap.** A scanner for a **detected** ecosystem that is not
66
+ installed is a gap: record it as a Low-severity `Standardization` finding
67
+ (recommend adopting it) and fall through to the next rung or a manual read.
68
+ - **Inapplicable is never a finding.** A scanner for an ecosystem that is
69
+ **not detected** is inapplicable — skip it silently. It is never a finding,
70
+ not even a Low one (`actionlint` on a repo with no `.github/workflows/` is
71
+ inapplicable, not missing).
72
+ - **Non-JS fallback.** Where a lens's JS rung reads a Mandrel-shipped script
73
+ or a committed `baselines/*.json` file that does not exist in the consumer,
74
+ measure with the ecosystem's own instrument instead of reporting the missing
75
+ script or baseline:
76
+
77
+ | Dimension | Python | Go | Rust |
78
+ | --- | --- | --- | --- |
79
+ | Complexity / MI | `radon cc -s -a`, `radon mi -s` | `gocyclo` | `cargo clippy` (cognitive_complexity) |
80
+ | Dead code | `vulture` | `staticcheck` (U1000) | `cargo +nightly udeps`, rustc dead_code warnings |
81
+ | Duplication | `pylint --disable=all --enable=duplicate-code`, or `jscpd` | `jscpd` | `jscpd` |
82
+ | Import graph / cycles | `pydeps --show-cycles`, `import-linter` (`lint-imports`) | `go vet`, `go list -deps` | `cargo modules` |
83
+ | Coverage | `coverage report` / `pytest --cov` (coverage.py, pytest-cov) | `go test -cover` | `cargo llvm-cov`, `cargo tarpaulin` |
84
+ | Dependency CVEs | `pip-audit` | `govulncheck` | `cargo audit` |
85
+ | Profiling | `py-spy record`, `python -m cProfile` | `go test -cpuprofile`, `pprof` | `cargo flamegraph` |
86
+
46
87
  ## Report envelope & finding-block skeleton {#report-envelope}
47
88
 
48
89
  Each lens writes exactly one structured Markdown report to
49
90
  `{{auditOutputDir}}/audit-<lens>-results.md` (the lens preamble names its own
50
- path). The report MUST include every section its lens template mandates — write
51
- `_No findings._` rather than omitting a section — and always an
91
+ path). A dispatched run gets the anchor substituted; on a manual
92
+ `/audit-<lens>` invocation it renders the literal string `{{auditOutputDir}}`.
93
+ Treat that literal as `<project.paths.tempRoot>/audits` — **`temp/audits` by
94
+ default** — and write the report there, mirroring the `{{changedFiles}}`
95
+ manual-run rule above. The report MUST include every section its lens
96
+ template mandates — write `_No findings._` rather than omitting a section — and
97
+ always an
52
98
  `## Executive Summary` and a `## Detailed Findings` section. The Executive
53
99
  Summary carries the self-cross-check `kept <k> / dropped <d>` line
54
100
  ([below](#self-cross-check)) and, beside it, the machine-readable severity
55
101
  tally ([below](#severity-tally)).
56
102
 
57
- Every finding under `## Detailed Findings` uses the shared 7-field skeleton
58
- below. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
103
+ Every finding under `## Detailed Findings` uses the shared 6-field skeleton
104
+ below, ordered by severity — Critical, High, Medium, Low, then Info — so a
105
+ reader that stops early, or a truncated read, still sees the worst first. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
59
106
  `Baseline MUST`, a `Route / Door` + `Persona(s)` pair, an `Evidence` tag) and
60
107
  may **relabel** the two normalized axes — `Severity` ↔ `Impact`, `Dimension` ↔
61
108
  `Category` ↔ `Type` — as its preamble declares; the parser
@@ -73,8 +120,8 @@ Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
73
120
 
74
121
  ## Detailed Findings
75
122
 
76
- [For every finding, use the following strict structure. Lead each title with
77
- the primary file the finding lives in:]
123
+ [For every finding, in descending severity order, use the following strict
124
+ structure. Lead each title with the primary file the finding lives in:]
78
125
 
79
126
  ### `path/to/primary-file.ext` — [Short title of the issue]
80
127
 
@@ -86,8 +133,6 @@ the primary file the finding lives in:]
86
133
  - **Acceptance signal:** [the command or observable that proves this finding is
87
134
  remediated — e.g. a grep that now returns empty, an added regression test, or
88
135
  a re-run of this lens]
89
- - **Agent Prompt:**
90
- `[A copy-pasteable, highly specific prompt to execute this remediation independently]`
91
136
  ```
92
137
 
93
138
  ## Severity scale {#severity-scale}
package/README.md CHANGED
@@ -70,6 +70,16 @@ explicit `npx mandrel sync` above is the belt-and-suspenders step for
70
70
  `--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
71
71
  time to confirm the install is healthy.
72
72
 
73
+ Bootstrap also writes a guarded `prepare` script that regenerates both
74
+ `.claude/` projections — `.claude/commands/` (from `.agents/workflows/`) and
75
+ `.claude/agents/` (from `.agents/agents/`). Both are generated and
76
+ gitignored; never commit them. The guard makes `prepare` exit 0 without
77
+ writing anything when `.agents/scripts/` is absent, so a manifest-only
78
+ container layer (`COPY package.json package-lock.json ./` then `npm ci`)
79
+ installs cleanly; once `.agents/` is present it runs both projections.
80
+ Existing installs pick up the guard and the `.claude/agents/` ignore entry
81
+ through the `mandrel update` migration.
82
+
73
83
  > **pnpm users — hoist mandrel's runtime deps.** The materialized
74
84
  > `./.agents/scripts/*.js` run from your project root and resolve their
75
85
  > third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
@@ -143,7 +153,9 @@ npx mandrel update
143
153
  - `--install-cmd "<cmd>"` — override the auto-detected install command. The
144
154
  package manager is normally detected from your lockfile
145
155
  (`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
146
- otherwise `npm install …`), so an override is rarely needed. When you do
156
+ otherwise `npm install …`), and it keeps your current pin style: an exact
157
+ pin installs with `--save-exact` (`--exact` on yarn), a tilde pin as
158
+ `mandrel@~<target>`, so an override is rarely needed. When you do
147
159
  pass one, a `{target}` placeholder is substituted with the resolved newest
148
160
  version — e.g. `--install-cmd "pnpm add -D mandrel@{target} -w"` —
149
161
  so the override can still consume the auto-probed version. The registry
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,28 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.78.0...mandrel-v2.79.0) (2026-10-09)
19
+
20
+
21
+ ### Added
22
+
23
+ * audit lenses: ecosystem-detected Step 0 rungs for Python and non-GitHub CI, and a stated manual output path ([#5583](https://github.com/dsj1984/mandrel/issues/5583)) ([#5586](https://github.com/dsj1984/mandrel/issues/5586)) ([3c5bf96](https://github.com/dsj1984/mandrel/commit/3c5bf9673b413800deca87e6fc30b956b10154c8))
24
+ * bootstrap: container-safe prepare hook and a gitignored .claude/agents/ projection ([#5581](https://github.com/dsj1984/mandrel/issues/5581)) ([#5590](https://github.com/dsj1984/mandrel/issues/5590)) ([96c4b20](https://github.com/dsj1984/mandrel/commit/96c4b2024724805122ab2b4d3f046cac8b3f7852))
25
+ * bootstrap: skip Projects V2 board creation non-interactively, and continue when project creation is declined ([#5584](https://github.com/dsj1984/mandrel/issues/5584)) ([#5587](https://github.com/dsj1984/mandrel/issues/5587)) ([14db7d3](https://github.com/dsj1984/mandrel/commit/14db7d33a017a314a98d7be2f344988da7e2ef3b))
26
+ * close and doctor honor project.commands.test instead of hardcoding npm test ([#5582](https://github.com/dsj1984/mandrel/issues/5582)) ([#5588](https://github.com/dsj1984/mandrel/issues/5588)) ([7849cf2](https://github.com/dsj1984/mandrel/commit/7849cf2945837631167241d6c30979433f9dcfea))
27
+
28
+
29
+ ### Fixed
30
+
31
+ * mandrel update preserves the consumer's exact or tilde pin instead of loosening it to a caret ([#5580](https://github.com/dsj1984/mandrel/issues/5580)) ([#5585](https://github.com/dsj1984/mandrel/issues/5585)) ([443c10a](https://github.com/dsj1984/mandrel/commit/443c10a2c0a7a2e6c7597b4196e9f3cb58440d23))
32
+
33
+ ## [2.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.77.0...mandrel-v2.78.0) (2026-10-09)
34
+
35
+
36
+ ### Added
37
+
38
+ * audit findings: drop the Agent Prompt field and carry Acceptance signal and Recommendation through to Stories and plan seeds ([#5569](https://github.com/dsj1984/mandrel/issues/5569)) ([#5570](https://github.com/dsj1984/mandrel/issues/5570)) ([0ac754d](https://github.com/dsj1984/mandrel/commit/0ac754d4897e8cb16bd7c5bfcf4034efcd039f3d))
39
+
18
40
  ## [2.77.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.76.0...mandrel-v2.77.0) (2026-10-08)
19
41
 
20
42
 
@@ -860,9 +860,18 @@ function probeConfiguredDriver(command, runner, projectRoot) {
860
860
  /** The runner whose green full run deposits the close `test` credit itself. */
861
861
  const MANDREL_TEST_RUNNER = 'run-tests.js';
862
862
 
863
- /** Deposits the credit whatever `npm test` resolves to. */
864
- const TEST_CREDIT_DEPOSIT_COMMAND =
865
- 'node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test';
863
+ /** The close `test` gate's command when `project.commands.test` is unset. */
864
+ const DEFAULT_TEST_COMMAND = 'npm test';
865
+
866
+ /**
867
+ * The deposit command that works on any runner, wrapping `command`.
868
+ *
869
+ * @param {string} command
870
+ * @returns {string}
871
+ */
872
+ function testCreditDepositCommand(command) {
873
+ return `node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- ${command}`;
874
+ }
866
875
 
867
876
  /** The capture close's `coverage-capture` gate finds fresh, per digest § 5. */
868
877
  const COVERAGE_CAPTURE_COMMAND =
@@ -872,7 +881,13 @@ const COVERAGE_CAPTURE_COMMAND =
872
881
  const STORY_HANDOFF_COMMAND =
873
882
  'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
874
883
 
875
- const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
884
+ /**
885
+ * @param {string} command
886
+ * @returns {string}
887
+ */
888
+ function testCreditRemedy(command) {
889
+ return `run the suite through the depositor instead of bare \`${command}\`: ${testCreditDepositCommand(command)}`;
890
+ }
876
891
 
877
892
  const PRE_PUSH_REMEDY =
878
893
  'wrap each hook gate in `node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate <typecheck|lint> -- <command>` so the push deposits the credit close reads';
@@ -881,8 +896,8 @@ const PRE_PUSH_REMEDY =
881
896
  const HOOK_GATE_RE = /\b(typecheck|tsc|lint|eslint|biome)\b/;
882
897
 
883
898
  /**
884
- * Read from `package.json`, not `project.commands.test`: the close gate's argv
885
- * is the literal `npm test`.
899
+ * Consulted only while `project.commands.test` is unset — then the close
900
+ * gate's argv is `npm test`, which runs `scripts.test`.
886
901
  *
887
902
  * @param {string} projectRoot
888
903
  * @param {typeof fs.readFileSync} readFileImpl
@@ -930,23 +945,80 @@ function isCrapEnabled(projectRoot, readFileImpl) {
930
945
  return enabled;
931
946
  }
932
947
 
948
+ /**
949
+ * `project.commands.test` from `.agentrc.json` overlaid by
950
+ * `.agentrc.local.json` — the command close's `test` gate spawns. Read without
951
+ * `resolveConfig()` (built-ins only), like {@link isCrapEnabled}.
952
+ *
953
+ * @param {string} projectRoot
954
+ * @param {typeof fs.readFileSync} readFileImpl
955
+ * @returns {string|null} The configured command, or null when unset/default.
956
+ */
957
+ function configuredTestCommand(projectRoot, readFileImpl) {
958
+ let command = null;
959
+ for (const file of ['.agentrc.json', '.agentrc.local.json']) {
960
+ const value = readJsonSafe(path.join(projectRoot, file), {
961
+ readFileSync: readFileImpl,
962
+ })?.project?.commands?.test;
963
+ if (typeof value === 'string' && value.trim().length > 0) {
964
+ command = value.trim();
965
+ }
966
+ }
967
+ return command === DEFAULT_TEST_COMMAND ? null : command;
968
+ }
969
+
970
+ /**
971
+ * A configured `project.commands.test` is what close spawns, so the analysis
972
+ * is of that command, never of `scripts.test`.
973
+ *
974
+ * @param {string} command
975
+ * @returns {{ detail: string, remedy?: string }}
976
+ */
977
+ function describeConfiguredTestCommand(command) {
978
+ const lead = `\`project.commands.test\` sets close's \`test\` gate to \`${command}\``;
979
+ if (command.includes(MANDREL_TEST_RUNNER)) {
980
+ return {
981
+ detail: `${lead}, which reaches mandrel's runner — a green full run on a story branch deposits the close \`test\` credit itself`,
982
+ };
983
+ }
984
+ const remedy = testCreditRemedy(command);
985
+ return {
986
+ detail: `${lead}, which deposits no close \`test\` credit by itself — ${remedy}`,
987
+ remedy,
988
+ };
989
+ }
990
+
933
991
  /**
934
992
  * Which depositor digest § 5 selects, stated with its exact command.
935
993
  *
936
- * @param {{ scripts: Record<string, string>, crapEnabled: boolean }} probe
994
+ * @param {{ scripts: Record<string, string>, crapEnabled: boolean, testCommand: string|null }} probe
937
995
  * @returns {{ detail: string, remedy?: string }}
938
996
  */
939
- function describeCreditedRun({ scripts, crapEnabled }) {
997
+ function describeCreditedRun({ scripts, crapEnabled, testCommand }) {
940
998
  if (crapEnabled && scriptNamed(scripts, 'test:coverage') !== null) {
941
999
  return {
942
1000
  detail: `the CRAP gate is enabled and \`test:coverage\` exists, so close registers \`coverage-capture\` and the credited run is the coverage capture: \`${COVERAGE_CAPTURE_COMMAND}\` — its fresh stamp lets close's capture skip the suite`,
943
1001
  };
944
1002
  }
1003
+ return testCommand !== null
1004
+ ? describeConfiguredTestCommand(testCommand)
1005
+ : describeNpmTestScript(scripts);
1006
+ }
1007
+
1008
+ /**
1009
+ * With `project.commands.test` unset close spawns `npm test`, so the analysis
1010
+ * is of `scripts.test`.
1011
+ *
1012
+ * @param {Record<string, string>} scripts
1013
+ * @returns {{ detail: string, remedy?: string }}
1014
+ */
1015
+ function describeNpmTestScript(scripts) {
1016
+ const remedy = testCreditRemedy(DEFAULT_TEST_COMMAND);
945
1017
  const script = scriptNamed(scripts, 'test');
946
1018
  if (script === null) {
947
1019
  return {
948
- detail: `no \`test\` script in package.json — close still spawns \`npm test\`, so ${TEST_CREDIT_REMEDY}`,
949
- remedy: TEST_CREDIT_REMEDY,
1020
+ detail: `no \`test\` script in package.json — close still spawns \`npm test\`, so ${remedy}`,
1021
+ remedy,
950
1022
  };
951
1023
  }
952
1024
  if (script.includes(MANDREL_TEST_RUNNER)) {
@@ -955,8 +1027,8 @@ function describeCreditedRun({ scripts, crapEnabled }) {
955
1027
  };
956
1028
  }
957
1029
  return {
958
- detail: `\`npm test\` → \`${script}\` is this project's own runner and never reaches \`${MANDREL_TEST_RUNNER}\`, so it deposits no close \`test\` credit and prints nothing — ${TEST_CREDIT_REMEDY}`,
959
- remedy: TEST_CREDIT_REMEDY,
1030
+ detail: `\`npm test\` → \`${script}\` is this project's own runner and never reaches \`${MANDREL_TEST_RUNNER}\`, so it deposits no close \`test\` credit and prints nothing — ${remedy}`,
1031
+ remedy,
960
1032
  };
961
1033
  }
962
1034
 
@@ -1020,6 +1092,7 @@ function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
1020
1092
  describeCreditedRun({
1021
1093
  scripts: readProjectScripts(root, readFile),
1022
1094
  crapEnabled: isCrapEnabled(root, readFile),
1095
+ testCommand: configuredTestCommand(root, readFile),
1023
1096
  }),
1024
1097
  describePrePushHook(root, readFile),
1025
1098
  ];
@@ -20,6 +20,8 @@ import {
20
20
  import {
21
21
  BOOTSTRAP_COMMAND,
22
22
  GITIGNORE_BLOCKS,
23
+ LEGACY_PREPARE_COMMAND,
24
+ PREPARE_COMMAND,
23
25
  SYNC_COMMAND,
24
26
  SYSTEM_PROMPT_AGENTS_MD,
25
27
  SYSTEM_PROMPT_BLOCK,
@@ -297,6 +299,33 @@ function revertGitignore(projectRoot, fsImpl) {
297
299
  return { kind: 'reverted', target: rel, detail };
298
300
  }
299
301
 
302
+ /** Every `prepare` value bootstrap writes whole: guarded, legacy pair, bare sync. */
303
+ const BOOTSTRAP_PREPARE_FORMS = new Set([
304
+ PREPARE_COMMAND,
305
+ LEGACY_PREPARE_COMMAND,
306
+ SYNC_COMMAND,
307
+ ]);
308
+
309
+ /**
310
+ * Strip the framework part of a `prepare`: a whole bootstrap-written form
311
+ * goes entirely; an operator command with the sync appended via ` && ` loses
312
+ * just that fragment. `next === ''` means delete the key, never write `""`.
313
+ *
314
+ * @param {unknown} prepare
315
+ * @returns {{ changed: boolean, next: string }}
316
+ */
317
+ function stripPrepare(prepare) {
318
+ if (typeof prepare !== 'string' || !prepare.includes(SYNC_COMMAND)) {
319
+ return { changed: false, next: '' };
320
+ }
321
+ if (BOOTSTRAP_PREPARE_FORMS.has(prepare)) return { changed: true, next: '' };
322
+ const next = prepare
323
+ .replace(` && ${SYNC_COMMAND}`, '')
324
+ .replace(`${SYNC_COMMAND} && `, '')
325
+ .trim();
326
+ return { changed: next !== prepare, next };
327
+ }
328
+
300
329
  /**
301
330
  * @param {string} projectRoot
302
331
  * @param {typeof fs} fsImpl
@@ -319,27 +348,14 @@ function revertPackageJson(projectRoot, fsImpl) {
319
348
  removed.push(name);
320
349
  }
321
350
  }
322
- // `prepare` is either the bare sync command or an operator command with it
323
- // appended via ` && `; strip just the fragment, never write `""`.
324
- const prepare = pkg.scripts.prepare;
325
- if (typeof prepare === 'string' && prepare.includes(SYNC_COMMAND)) {
326
- if (prepare === SYNC_COMMAND) {
351
+ const prepare = stripPrepare(pkg.scripts.prepare);
352
+ if (prepare.changed) {
353
+ if (prepare.next === '') {
327
354
  delete pkg.scripts.prepare;
328
- removed.push('prepare');
329
355
  } else {
330
- const stripped = prepare
331
- .replace(` && ${SYNC_COMMAND}`, '')
332
- .replace(`${SYNC_COMMAND} && `, '')
333
- .trim();
334
- if (stripped !== prepare) {
335
- if (stripped === '') {
336
- delete pkg.scripts.prepare;
337
- } else {
338
- pkg.scripts.prepare = stripped;
339
- }
340
- removed.push('prepare');
341
- }
356
+ pkg.scripts.prepare = prepare.next;
342
357
  }
358
+ removed.push('prepare');
343
359
  }
344
360
  if (removed.length === 0) {
345
361
  return { kind: 'skipped', target: rel, detail: 'no framework scripts' };
package/lib/cli/update.js CHANGED
@@ -22,6 +22,7 @@ import { defaultResolvePackageRoot } from './sync.js';
22
22
  import { isStale } from './version-check.js';
23
23
  import {
24
24
  compareVersions,
25
+ resolveConsumerPinSpec,
25
26
  resolveConsumerPinVersion,
26
27
  } from './version-helpers.js';
27
28
 
@@ -196,22 +197,43 @@ function probePackageManager(cwd, fs = nodeFs) {
196
197
  return detectPackageManagerWithWorkspace(cwd, exists);
197
198
  }
198
199
 
200
+ /**
201
+ * The save flag and spec that keep the consumer's pin style: an exact pin
202
+ * gains the manager's save-exact flag, a tilde rides in the spec (which all
203
+ * three managers record as-is), and caret or unknown keeps the bare spec.
204
+ *
205
+ * @param {string} target
206
+ * @param {'pnpm' | 'yarn' | 'npm'} packageManager
207
+ * @param {'^' | '~' | '' | null} pinOperator
208
+ * @returns {{ exact: string, spec: string }}
209
+ */
210
+ function pinPreservingSpec(target, packageManager, pinOperator) {
211
+ const exactFlag = packageManager === 'yarn' ? '--exact' : '--save-exact';
212
+ return {
213
+ exact: pinOperator === '' ? ` ${exactFlag}` : '',
214
+ spec: `${PACKAGE_NAME}@${pinOperator === '~' ? '~' : ''}${target}`,
215
+ };
216
+ }
217
+
199
218
  /**
200
219
  * The install command. An `--install-cmd` override is used verbatim except
201
- * that `{target}` is replaced with the resolved semver.
220
+ * that `{target}` is replaced with the resolved semver. Otherwise the
221
+ * consumer's current pin operator decides the save style: exact keeps an
222
+ * exact pin, tilde keeps a tilde, and caret or unknown keeps today's form.
202
223
  *
203
224
  * @param {string} target
204
225
  * @param {string} [override]
205
226
  * @param {{
206
227
  * packageManager?: 'pnpm' | 'yarn' | 'npm',
207
228
  * workspaceRoot?: boolean,
229
+ * pinOperator?: '^' | '~' | '' | null,
208
230
  * }} [detected]
209
231
  * @returns {string}
210
232
  */
211
233
  export function resolveInstallCmd(
212
234
  target,
213
235
  override,
214
- { packageManager = 'npm', workspaceRoot = false } = {},
236
+ { packageManager = 'npm', workspaceRoot = false, pinOperator = null } = {},
215
237
  ) {
216
238
  const trimmed = String(override ?? '').trim();
217
239
  if (trimmed.length > 0) {
@@ -219,13 +241,18 @@ export function resolveInstallCmd(
219
241
  ? trimmed.replaceAll('{target}', target)
220
242
  : trimmed;
221
243
  }
244
+ const { exact, spec } = pinPreservingSpec(
245
+ target,
246
+ packageManager,
247
+ pinOperator,
248
+ );
222
249
  if (packageManager === 'pnpm') {
223
- return `pnpm add -D ${PACKAGE_NAME}@${target}${workspaceRoot ? ' -w' : ''}`;
250
+ return `pnpm add -D${exact} ${spec}${workspaceRoot ? ' -w' : ''}`;
224
251
  }
225
252
  if (packageManager === 'yarn') {
226
- return `yarn add -D ${PACKAGE_NAME}@${target}`;
253
+ return `yarn add -D${exact} ${spec}`;
227
254
  }
228
- return `npm install ${PACKAGE_NAME}@${target}`;
255
+ return `npm install${exact} ${spec}`;
229
256
  }
230
257
 
231
258
  const LOCKFILE_BY_PACKAGE_MANAGER = {
@@ -461,7 +488,11 @@ export function defaultNpmUpdate(
461
488
  } = {},
462
489
  ) {
463
490
  const detected = detectPackageManager(cwd, fs);
464
- const cmd = resolveInstallCmd(target, installCmd, detected);
491
+ const pinOperator = resolveConsumerPinSpec(cwd, fs)?.operator ?? null;
492
+ const cmd = resolveInstallCmd(target, installCmd, {
493
+ ...detected,
494
+ pinOperator,
495
+ });
465
496
  const repairHint =
466
497
  `\n → If node_modules looks wrong, run \`${repairInstallCommand(detected.packageManager)}\`` +
467
498
  ' to restore it to a consistent state.';
@@ -18,6 +18,7 @@ import { retireAuditResultsAutoFile } from './steps/2.60.0-retire-audit-results-
18
18
  import { baselineMergeQueueShape } from './steps/2.63.0-baseline-merge-queue-shape.js';
19
19
  import { foldClaudeMdIntoAgentsMdStep } from './steps/2.65.0-fold-claude-md-into-agents-md.js';
20
20
  import { retireAuditLedger } from './steps/2.70.0-retire-audit-ledger.js';
21
+ import { containerSafeProjections } from './steps/2.79.0-container-safe-projections.js';
21
22
  import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
22
23
 
23
24
  /**
@@ -44,6 +45,7 @@ export const migrations = [
44
45
  baselineMergeQueueShape,
45
46
  foldClaudeMdIntoAgentsMdStep,
46
47
  retireAuditLedger,
48
+ containerSafeProjections,
47
49
  ];
48
50
 
49
51
  export { compareVersions };
@@ -0,0 +1,91 @@
1
+ // lib/migrations/steps/2.79.0-container-safe-projections.js
2
+ /**
3
+ * Bring an existing consumer's bootstrap footprint to the container-safe
4
+ * shape: upgrade the legacy unguarded `prepare` to the guarded
5
+ * form, and add the `.claude/agents/` ignore entry. Reuses the bootstrap's own
6
+ * helpers so a migrated tree matches a fresh bootstrap byte for byte. An
7
+ * operator-customised `prepare` is never touched.
8
+ */
9
+
10
+ import nodeFs from 'node:fs';
11
+ import path from 'node:path';
12
+
13
+ import {
14
+ ensureGitignore,
15
+ ensurePrepareScript,
16
+ GITIGNORE_BLOCKS,
17
+ LEGACY_PREPARE_COMMAND,
18
+ } from '../../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
19
+
20
+ /**
21
+ * @param {string} root
22
+ * @param {typeof nodeFs} fsImpl
23
+ * @returns {{ pkgPath: string, pkg: object | null }}
24
+ */
25
+ function readPackageJson(root, fsImpl) {
26
+ const pkgPath = path.join(root, 'package.json');
27
+ if (!fsImpl.existsSync(pkgPath)) return { pkgPath, pkg: null };
28
+ try {
29
+ return { pkgPath, pkg: JSON.parse(fsImpl.readFileSync(pkgPath, 'utf8')) };
30
+ } catch {
31
+ return { pkgPath, pkg: null };
32
+ }
33
+ }
34
+
35
+ /**
36
+ * @param {string} root
37
+ * @param {typeof nodeFs} fsImpl
38
+ * @returns {boolean}
39
+ */
40
+ function hasLegacyPrepare(root, fsImpl) {
41
+ const { pkg } = readPackageJson(root, fsImpl);
42
+ return pkg?.scripts?.prepare === LEGACY_PREPARE_COMMAND;
43
+ }
44
+
45
+ /**
46
+ * @param {string} root
47
+ * @param {typeof nodeFs} fsImpl
48
+ * @returns {boolean}
49
+ */
50
+ function lacksAgentsIgnore(root, fsImpl) {
51
+ const target = path.join(root, '.gitignore');
52
+ const body = fsImpl.existsSync(target)
53
+ ? fsImpl.readFileSync(target, 'utf8')
54
+ : '';
55
+ return !GITIGNORE_BLOCKS.agents.pattern.test(body);
56
+ }
57
+
58
+ export const containerSafeProjections = {
59
+ version: '2.79.0',
60
+ description:
61
+ 'guard the bootstrap `prepare` so a manifest-only container `npm ci` ' +
62
+ 'skips the projections, and gitignore the generated .claude/agents/ ' +
63
+ '(Story #5581)',
64
+ /**
65
+ * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
66
+ * @param {typeof nodeFs} [fsImpl]
67
+ * @returns {boolean}
68
+ */
69
+ detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
70
+ const root = ctx?.projectRoot ?? process.cwd();
71
+ return hasLegacyPrepare(root, fsImpl) || lacksAgentsIgnore(root, fsImpl);
72
+ },
73
+ /**
74
+ * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
75
+ * @param {typeof nodeFs} [fsImpl]
76
+ * @returns {void}
77
+ */
78
+ apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
79
+ const root = ctx?.projectRoot ?? process.cwd();
80
+ if (hasLegacyPrepare(root, fsImpl)) {
81
+ const { pkgPath, pkg } = readPackageJson(root, fsImpl);
82
+ ensurePrepareScript(pkg.scripts);
83
+ fsImpl.writeFileSync(
84
+ pkgPath,
85
+ `${JSON.stringify(pkg, null, 2)}\n`,
86
+ 'utf8',
87
+ );
88
+ }
89
+ ensureGitignore({ projectRoot: root, fsImpl }, ['agents']);
90
+ },
91
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.77.0",
3
+ "version": "2.79.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",