mandrel 2.2.0 → 2.3.0

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.2.0...mandrel-v2.3.0) (2026-07-17)
+
+
+### Fixed
+
+* **test:** resolve Windows drive-letter path bug in quality-preview test ([#4614](https://github.com/dsj1984/mandrel/issues/4614)) ([a7da94d](https://github.com/dsj1984/mandrel/commit/a7da94d1c4a83b9b721e632e468bb34df07465dd))
+* **update:** make post-install bin re-exec pnpm/layout-agnostic ([#4613](https://github.com/dsj1984/mandrel/issues/4613)) ([#4616](https://github.com/dsj1984/mandrel/issues/4616)) ([82dc5a2](https://github.com/dsj1984/mandrel/commit/82dc5a2e9ce662f9b9c0c7880ea684fd370a507f))
+
 ## [2.2.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.1.0...mandrel-v2.2.0) (2026-07-17)
 
 

package/lib/cli/update.js

@@ -36,7 +36,9 @@
  * ## Re-exec of post-install phases (Story #4034)
  *
  * Steps 4–6 execute as **child processes spawned from the newly-installed
- * binary** (`<cwd>/node_modules/.bin/mandrel`) rather than in the running
+ * bin script** (`node <cwd>/node_modules/mandrel/bin/mandrel.js`; Story #4613
+ * resolves the script layout-agnostically rather than via the `.bin` shim)
+ * rather than in the running
  * process. Node cannot hot-swap a `require`d module mid-process, so without
  * re-exec, the still-running old binary's `runSync`/`runMigrations`/`runDoctor`
  * code would materialise the old payload even though the package on disk has
@@ -120,11 +122,12 @@
  * resolved semver string — see `lib/install-cmd-parser.js` for the shared
  * tokenize-and-spawn rationale this module reuses (no duplicated workaround).
  *
- * The `spawnPhase` default (Story #4034) similarly uses `shell: true` only on
- * Windows: the new binary resolves from `node_modules/.bin/mandrel` (a fixed,
- * non-operator-supplied path) and the per-phase argv vector is a constant
- * fixed list (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`,
- * `['doctor']`) with no injection risk regardless of the shell flag.
+ * The `spawnPhase` default (Story #4034) does **not** use the win32 shell flag:
+ * it spawns `process.execPath` (node) against the resolved `bin/mandrel.js`
+ * script (Story #4613), so it never touches a `.cmd` shim and needs no
+ * shell on any platform. The per-phase argv vector is a constant fixed list
+ * (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`, `['doctor']`) with
+ * no operator-supplied data.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -674,29 +677,55 @@ function parseChangelogSections(raw) {
 }
 
 /**
- * Resolve the path to the `mandrel` binary inside `node_modules/.bin/` for the
- * given project root. On Windows the binary is a `.cmd` shim; on POSIX it is a
- * plain executable. The resolved path is used as the target for the post-install
- * phase re-exec (Story #4034).
+ * Resolve the newly-installed `mandrel` bin **script**
+ * (`<packageRoot>/bin/mandrel.js`) from the consumer project root. This is the
+ * target for the post-install phase re-exec (Story #4034), spawned via
+ * `process.execPath` (node) rather than executed directly — see
+ * {@link defaultSpawnPhase}.
+ *
+ * It deliberately does **not** return the `node_modules/.bin/mandrel` shim.
+ * That shim only works because npm chmods the bin target `+x` at install time:
+ * `bin/mandrel.js` ships non-executable in the published tarball, and pnpm
+ * symlinks `.bin/mandrel` straight at it, so spawning the shim directly fails
+ * with `EACCES` under pnpm (Story #4613). Spawning node against the resolved
+ * `.js` script removes the dependency on the exec bit, the shebang, and the
+ * Windows `.cmd` shim entirely.
+ *
+ * Resolution reuses the same consumer-anchored resolver
+ * (`defaultResolvePackageRoot`) that {@link resolveCurrentVersionForUpdate}
+ * uses, so it points at the consumer's install rather than a copy hoisted next
+ * to this CLI module. The `mandrel` package directory is version-invariant
+ * (`node_modules/mandrel/`), so resolving it before the in-place `npm-update`
+ * step still yields the directory whose `bin/mandrel.js` the install overwrites.
  *
  * @param {string} projectRoot - Absolute path to the consumer project.
- * @returns {string} Absolute path to the new binary.
+ * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts] - test
+ *   seam for the `node_modules` resolution; defaults to the real
+ *   `defaultResolvePackageRoot` from `sync.js`.
+ * @returns {string} Absolute path to the new bin script.
  */
-export function resolveNewBinPath(projectRoot) {
-  const binName = process.platform === 'win32' ? 'mandrel.cmd' : 'mandrel';
-  return path.join(projectRoot, 'node_modules', '.bin', binName);
+export function resolveNewBinScriptPath(
+  projectRoot,
+  { resolvePackageRoot = defaultResolvePackageRoot } = {},
+) {
+  const packageRoot = resolvePackageRoot(projectRoot);
+  return path.join(packageRoot, 'bin', 'mandrel.js');
 }
 
 /**
  * Default `spawnPhase` seam (Story #4034): spawn a post-install phase from the
- * newly-installed `mandrel` binary and stream its stdout/stderr through the
+ * newly-installed `mandrel` bin script and stream its stdout/stderr through the
  * parent's write sinks. Each phase runs as an isolated child process so the
  * newly-installed module code (not the currently-loaded old module) executes.
  *
- * The spawn uses `shell: true` only on Windows where the binary is a `.cmd`
- * shim (CVE-2024-27980 parity). The argv vector is a fixed constant list
- * per phase — no operator-supplied data enters the vector, so the shell flag
- * carries no injection risk (security-baseline § Output & Rendering).
+ * The child is spawned as `process.execPath <binScript> <phase> …` — node run
+ * against the resolved `bin/mandrel.js` (see {@link resolveNewBinScriptPath}).
+ * Spawning node against a plain `.js` file removes any dependency on the bin's
+ * exec bit, its shebang, or a Windows `.cmd` shim, so **no** `shell` flag is
+ * needed on any platform (this is the pnpm/layout-agnostic fix, Story #4613,
+ * that retired the former win32-only `shell: true` branch). The argv vector is
+ * a fixed constant list per phase — no operator-supplied data enters it
+ * (security-baseline § Output & Rendering).
  *
  * Throws when the child exits non-zero so the orchestrator can surface the
  * failure to the operator.
@@ -709,7 +738,8 @@ export function resolveNewBinPath(projectRoot) {
  *   write: (s: string) => void,
  *   writeErr: (s: string) => void,
  *   spawnFn?: typeof spawnSync,
- * }} opts
+ * }} opts - `binPath` is the resolved bin **script** path (not the
+ *   `node_modules/.bin` shim); it becomes node's first argv entry.
  * @returns {{ ok: boolean, stdout: string, stderr: string }}
  */
 export function defaultSpawnPhase(
@@ -718,10 +748,9 @@ export function defaultSpawnPhase(
   { binPath, cwd, write, writeErr, spawnFn = spawnSync },
 ) {
   const argv = [phase, ...args];
-  const r = spawnFn(binPath, argv, {
+  const r = spawnFn(process.execPath, [binPath, ...argv], {
     cwd,
     encoding: 'utf8',
-    shell: process.platform === 'win32',
   });
   const stdout = typeof r.stdout === 'string' ? r.stdout : '';
   const stderr = typeof r.stderr === 'string' ? r.stderr : '';
@@ -980,7 +1009,7 @@ async function resolveDrift(checkDrift) {
  *   npmUpdate: ((version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>) | undefined,
  *   spawnPhase: ((phase: string, args: string[], opts: object) => { ok: boolean } | Promise<{ ok: boolean }>) | undefined,
  *   surfaceChangelog: ((version: string) => unknown | Promise<unknown>) | undefined,
- *   binPath: string,
+ *   resolveBinScript: (projectRoot: string) => string,
  *   projectRoot: string,
  *   write: (s: string) => void,
  *   writeErr: (s: string) => void,
@@ -995,7 +1024,7 @@ async function executePlan({
   npmUpdate,
   spawnPhase,
   surfaceChangelog,
-  binPath,
+  resolveBinScript,
   projectRoot,
   write,
   writeErr,
@@ -1004,6 +1033,17 @@ async function executePlan({
   const stepsRun = [];
   let doctorOk = true;
 
+  // Resolve the new bin script lazily and once, on the first spawn phase.
+  // Deferring it past the `npm-update` step means (a) a missing `npmUpdate`
+  // seam surfaces its own clear error first, and (b) resolution reflects the
+  // just-installed package. The `mandrel` package directory is version-stable,
+  // so resolving after the in-place bump yields the same directory either way.
+  let binPath;
+  const binScript = () => {
+    if (binPath === undefined) binPath = resolveBinScript(projectRoot);
+    return binPath;
+  };
+
   for (const step of steps) {
     if (step.kind === 'npm-update') {
       // Bump the dependency. The lockfile change is left STAGED on disk; this
@@ -1024,7 +1064,7 @@ async function executePlan({
     // package's module code — not the old loaded module — executes.
     // eslint-disable-next-line no-await-in-loop
     const result = await spawnPhase(step.phase, step.args, {
-      binPath,
+      binPath: binScript(),
       cwd: projectRoot,
       write,
       writeErr,
@@ -1080,6 +1120,7 @@ async function executePlan({
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
  *   cwd?: () => string,
+ *   resolveBinScript?: (projectRoot: string) => string,
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
@@ -1102,6 +1143,7 @@ export async function runUpdate({
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
   cwd = () => process.cwd(),
+  resolveBinScript = resolveNewBinScriptPath,
 } = {}) {
   const dryRun = argv.includes('--dry-run');
   const installCmd = parseInstallCmdFlag(argv);
@@ -1176,7 +1218,6 @@ export async function runUpdate({
 
   // --- resynced / updated: execute the phase plan ---------------------------
   const projectRoot = cwd();
-  const binPath = resolveNewBinPath(projectRoot);
 
   if (plan.action === 'resynced') {
     write(
@@ -1193,7 +1234,7 @@ export async function runUpdate({
     npmUpdate,
     spawnPhase,
     surfaceChangelog,
-    binPath,
+    resolveBinScript,
     projectRoot,
     write,
     writeErr,
@@ -1251,8 +1292,9 @@ export async function runUpdate({
  *     through the shared `runInstallCommand` helper — no git mutation;
  *     lockfile left staged.
  *   - `spawnPhase` is wired to `defaultSpawnPhase`, which spawns each
- *     post-install phase (sync, sync-commands, migrate, doctor) from the
- *     newly-installed binary (`node_modules/.bin/mandrel`). This is the
+ *     post-install phase (sync, sync-commands, migrate, doctor) as
+ *     `node <packageRoot>/bin/mandrel.js …` (Story #4613 — the resolved bin
+ *     script, not the `node_modules/.bin` shim). This is the
  *     Story #4034 fix: the new bin loads the new package's module code and
  *     resolves paths against the new install dir, so these phases can never
  *     observe the old payload.
@@ -1289,6 +1331,7 @@ export async function runUpdate({
  *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
  *   cwd?: () => string,
+ *   resolveBinScript?: (projectRoot: string) => string,
  *   checkDrift?: () => (boolean | Promise<boolean>),
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
@@ -1313,6 +1356,7 @@ export default async function run(argv = [], deps = {}) {
     exit = (code) => process.exit(code),
     log,
     cwd,
+    resolveBinScript,
     checkDrift,
   } = deps;
 
@@ -1323,11 +1367,13 @@ export default async function run(argv = [], deps = {}) {
   const current =
     deps.currentVersion ?? resolveCurrentVersionForUpdate(cwdFn(), fs);
 
-  // The production spawnPhase: spawn each post-install phase from
-  // node_modules/.bin/mandrel (the newly-installed binary). This is the sole
-  // post-install execution path (No-Shim — Story #4182 retired the in-process
-  // runSync/runMigrations/runDoctor seam set). spawnFn is injectable so tests
-  // can stub the spawn boundary without running a real child process.
+  // The production spawnPhase: spawn each post-install phase as
+  // `node <packageRoot>/bin/mandrel.js …` (the newly-installed bin script,
+  // resolved layout-agnostically per Story #4613 — not the node_modules/.bin
+  // shim). This is the sole post-install execution path (No-Shim — Story #4182
+  // retired the in-process runSync/runMigrations/runDoctor seam set). spawnFn
+  // is injectable so tests can stub the spawn boundary without running a real
+  // child process.
   const productionSpawnPhase = (phase, args, opts) =>
     defaultSpawnPhase(phase, args, {
       ...opts,
@@ -1370,5 +1416,8 @@ export default async function run(argv = [], deps = {}) {
     writeErr,
     exit,
     cwd: cwdFn,
+    // Pass through undefined in production so runUpdate applies its default
+    // resolver (resolveNewBinScriptPath); tests inject a stub for a fake root.
+    resolveBinScript,
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",