mandrel 1.69.0 → 1.70.0

package/lib/cli/registry.js

@@ -371,7 +371,14 @@ function runRuntimeDeps({
   return {
     ok: false,
     detail: `missing: ${missing.join(', ')}`,
-    remedy: `Run \`npm install\` in the repository root to install missing packages: ${missing.join(', ')}`,
+    remedy:
+      'The framework runtime deps are not resolvable from the consumer root, ' +
+      'where the materialized .agents/scripts/*.js run. npm and yarn hoist ' +
+      "them automatically — run the installer if you haven't. pnpm's default " +
+      'isolated layout does NOT hoist transitive deps to the top level: add ' +
+      '`shamefully-hoist=true` (or a scoped `public-hoist-pattern[]` for ' +
+      'each dep) to your `.npmrc` and reinstall. ' +
+      `Missing: ${missing.join(', ')}`,
   };
 }
 
@@ -457,6 +464,39 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
 // from sync.js) are imported from `lib/cli/sync.js` at the top of this file
 // (Story #4048 B3 — no mirror copies).
 
+/**
+ * Decide whether a single materialized payload file has drifted from its
+ * package-payload source.
+ *
+ * Size short-circuit (Story #4193): when the injected `fsImpl` exposes
+ * `statSync`, a `statSync(src).size !== statSync(dest).size` mismatch is
+ * sufficient proof of drift, so it returns `true` on two `stat` syscalls
+ * **without reading either file's contents** — the overwhelmingly common
+ * drift shape after a stale `sync` is a size change. Equal sizes do not
+ * guarantee equal content, so an equal-size pair falls through to the
+ * `readFileSync` + `Buffer.equals` byte comparison. The short-circuit is
+ * opt-in on `statSync` being present; a seam that omits it (e.g. a legacy
+ * test double) transparently uses the byte-read path, preserving the prior
+ * behaviour exactly.
+ *
+ * Security: returns only a boolean — it never surfaces file contents to the
+ * caller (security baseline §5 — Data Leakage & Logging).
+ *
+ * @param {string} src - absolute path to the package-payload file
+ * @param {string} dest - absolute path to the materialized file
+ * @param {{ readFileSync: Function, statSync?: Function }} fsImpl
+ * @returns {boolean} `true` when the files differ
+ */
+function payloadFileDrifted(src, dest, fsImpl) {
+  if (
+    typeof fsImpl.statSync === 'function' &&
+    fsImpl.statSync(src).size !== fsImpl.statSync(dest).size
+  ) {
+    return true;
+  }
+  return !fsImpl.readFileSync(src).equals(fsImpl.readFileSync(dest));
+}
+
 /**
  * Compare the consumer's materialized `./.agents/<f>` bytes against the
  * installed package payload (`node_modules/mandrel/.agents/<f>`),
@@ -469,16 +509,21 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
  * §5 — Data Leakage & Logging). The comparison is short-circuiting and never
  * accumulates file contents.
  *
+ * Performance: per-file drift is decided by `payloadFileDrifted`, which gates
+ * the byte read behind a cheap `statSync` size comparison (Story #4193) so a
+ * size-changed file — the common drift shape after a stale `sync` — reports
+ * without reading either file's contents.
+ *
  * Injectable seams (used by tests so no real filesystem or package is needed):
  * - `cwd()` — replaces `process.cwd`.
  * - `fsImpl` — replaces the `node:fs` surface (`existsSync`, `readdirSync`,
- *   `readFileSync`).
+ *   `readFileSync`, and optionally `statSync` for the size short-circuit).
  * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution;
  *   throws when the package is not installed.
  *
  * @param {{
  *   cwd?: () => string,
- *   fsImpl?: { existsSync: (p: string) => boolean, readdirSync: Function, readFileSync: Function },
+ *   fsImpl?: { existsSync: (p: string) => boolean, readdirSync: Function, readFileSync: Function, statSync?: Function },
  *   resolvePackageRoot?: (fromDir: string) => string,
  * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -534,10 +579,8 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
       };
     }
 
-    const srcBytes = fsImpl.readFileSync(src);
-    const destBytes = fsImpl.readFileSync(dest);
     comparedCount += 1;
-    if (!srcBytes.equals(destBytes)) {
+    if (payloadFileDrifted(src, dest, fsImpl)) {
       return {
         ok: false,
         detail: `${relLabel} differs from the installed package payload`,