@lenne.tech/cli 1.42.0 → 1.44.0

package/build/lib/adopt-upstream-build-allowlist.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adoptUpstreamBuildAllowlist = adoptUpstreamBuildAllowlist;
+const js_yaml_1 = require("js-yaml");
+const fs_utils_1 = require("./fs-utils");
+const hoist_workspace_pnpm_config_1 = require("./hoist-workspace-pnpm-config");
+/**
+ * Carry the framework's build-script allowlist into a project that has just
+ * vendored it.
+ *
+ * `allowBuilds` decides which packages may run install scripts. pnpm 11 does not
+ * treat an unlisted one as "deny" — it ABORTS the install with
+ * `ERR_PNPM_IGNORED_BUILDS` and writes a `set this to true or false` placeholder
+ * into the workspace file. So a single missing entry is not a hardening gap; it
+ * is a project that cannot be installed at all, on the very first
+ * `lt fullstack init`, before anyone has written a line of code.
+ *
+ * Vendoring is exactly where that gap opens. The conversion resolves the core's
+ * import closure into DIRECT dependencies — `import('bullmq')` in
+ * core-cron-jobs.service.ts becomes a real `bullmq` dep, which pulls
+ * `msgpackr` → `msgpackr-extract`, a package with an install script. nest-server
+ * knows about it and lists it. The project does not, and cannot: nest-server's
+ * `pnpm-workspace.yaml` is not part of its npm tarball — `files` ships `dist`,
+ * `src`, `bin` and the docs, never a repo-root config file — so nothing
+ * downstream can read it. Until now the only bridge was a
+ * human copying entries into nest-server-starter by hand — and that bridge has
+ * already been observed to rot: `@scarf/scarf` sat at `true` in the starter while
+ * the framework denied it, for long enough that the drift shipped.
+ *
+ * Deliberately additive. A key the project has already decided is left exactly as
+ * it is, including an explicit `false`: the project is the more specific context,
+ * and silently flipping its decision to match the framework would be a worse bug
+ * than the one this fixes. Only genuinely absent keys are taken over — together
+ * with the comment that explains them, because an entry like
+ * `'msgpackr-extract': false` reads as dead weight without it and gets deleted by
+ * the next person who runs `pnpm why`.
+ *
+ * @returns the keys actually adopted, for the caller to report.
+ */
+function adoptUpstreamBuildAllowlist(options) {
+    var _a;
+    const { dest, filesystem, upstreamWorkspaceYaml } = options;
+    if (!upstreamWorkspaceYaml)
+        return [];
+    const upstream = parseYamlObject(upstreamWorkspaceYaml);
+    const upstreamAllow = asStringBoolMap(upstream === null || upstream === void 0 ? void 0 : upstream.allowBuilds);
+    if (Object.keys(upstreamAllow).length === 0)
+        return [];
+    // Never write through a symlinked project: with `--api-link` it points at the
+    // user's own nest-server-starter checkout, and this would edit their repo. The
+    // same guard already protects `hoistWorkspacePnpmConfig` and
+    // `removeNestedLockfiles`; these two libs were the odd ones out.
+    if ((0, fs_utils_1.isSymlink)(dest))
+        return [];
+    const destPath = `${dest}/pnpm-workspace.yaml`;
+    // No file to extend means no pnpm settings of the project's own. Writing one
+    // here would invent a workspace root the scaffolding did not ask for, so the
+    // absence is respected rather than filled in.
+    if (!filesystem.exists(destPath))
+        return [];
+    const destRaw = (_a = filesystem.read(destPath)) !== null && _a !== void 0 ? _a : '';
+    const destWs = parseYamlObject(destRaw);
+    if (!destWs)
+        return [];
+    // The project's map is read RAW, not through `asStringBoolMap`. Narrowing it to
+    // booleans first was a live deny-bypass with no attacker involved: js-yaml 4
+    // uses the YAML 1.2 core schema, so `esbuild: no` and `esbuild: off` parse as
+    // STRINGS. A maintainer writing `no` to mean "deny" was read as "no opinion",
+    // upstream's `true` was adopted, and the original entry was dropped from the
+    // rewritten map as well. Same for `'false'`, for an empty value (null), and for
+    // pnpm's own `set this to true or false` placeholder — all five verified.
+    //
+    // `Object.create(null)` and `hasOwnProperty.call`: with a plain object,
+    // `'constructor' in map` is true via the prototype, so eight real package names
+    // ('constructor', 'toString', 'valueOf', …) would be treated as already decided
+    // and silently never adopted — the ERR_PNPM_IGNORED_BUILDS abort this whole
+    // function exists to prevent.
+    const merged = Object.assign(Object.create(null), asRawMap(destWs.allowBuilds));
+    const adopted = [];
+    for (const [pkg, value] of Object.entries(upstreamAllow)) {
+        // ANY existing key is a decision, whatever shape YAML gave it.
+        if (Object.prototype.hasOwnProperty.call(merged, pkg))
+            continue;
+        merged[pkg] = value;
+        adopted.push(pkg);
+    }
+    if (adopted.length === 0)
+        return [];
+    destWs.allowBuilds = Object.fromEntries(Object.entries(merged).sort(([a], [b]) => a.localeCompare(b)));
+    // The project's own annotations win where both files comment the same key; the
+    // upstream ones fill in only for the keys just adopted, which by definition the
+    // project had nothing to say about.
+    const comments = (0, hoist_workspace_pnpm_config_1.extractKeyComments)(destRaw);
+    for (const [key, block] of (0, hoist_workspace_pnpm_config_1.extractKeyComments)(upstreamWorkspaceYaml)) {
+        if (!comments.has(key))
+            comments.set(key, block);
+    }
+    filesystem.write(destPath, (0, hoist_workspace_pnpm_config_1.reattachKeyComments)((0, js_yaml_1.dump)(destWs, { lineWidth: -1, sortKeys: false }), comments));
+    return adopted;
+}
+/** The value as a plain key/value map, or an empty one — no narrowing of values. */
+function asRawMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+/**
+ * Narrow an unknown value to a `{ pkg: boolean }` map, dropping other shapes.
+ *
+ * Used for the UPSTREAM side only. There, dropping a non-boolean is right — we
+ * adopt only decisions we understand. On the DEST side it is the opposite: see
+ * the comment at the merge above.
+ */
+function asStringBoolMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (typeof v === 'boolean')
+            out[key] = v;
+    }
+    return out;
+}
+/** Parse YAML into a plain object, or null on empty/malformed/non-object input. */
+function parseYamlObject(raw) {
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = (0, js_yaml_1.load)(raw);
+    }
+    catch (_a) {
+        // Malformed upstream YAML must not take the conversion down with it — the
+        // vendored project is still usable, it just does not inherit the allowlist.
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    return parsed;
+}

package/build/lib/fail-run.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failRun = failRun;
+/**
+ * Mark the current command run as failed.
+ *
+ * A gluegun command signals failure by printing and returning, and a bare
+ * `return` leaves the process at exit code 0. So a scaffold that died halfway
+ * reported SUCCESS to every caller that checks `$?` — a CI job, a wrapper
+ * script, an agent. That is not theoretical: a `lt fullstack init` whose
+ * `pnpm install` aborted on a native build script printed a red spinner and
+ * still exited 0, and the half-built workspace was only noticed later, by hand.
+ *
+ * Call it immediately before every `return` on an error path:
+ *
+ *     failRun(toolbox);
+ *     return;
+ *
+ * **`process.exitCode`, not `process.exit()`** — the latter can truncate
+ * buffered output, including the spinner's own failure message, which is the one
+ * line the operator actually needs.
+ *
+ * **Guarded by `fromGluegunMenu`**, like the CLI's other exit-code call sites
+ * (`dev test`, `dev tunnel`, `tools ocr`, `workspace-integration`): inside the
+ * interactive `lt` menu a command is one step of a longer session, and failing
+ * the whole session because one step errored is the same over-reach in reverse.
+ *
+ * Shared rather than redeclared per command: `fullstack init` delegates to
+ * `add-api` / `add-app` inside an existing workspace, so all three have to agree
+ * on the contract or the exit code depends on which directory the user happened
+ * to be standing in — which was exactly the state before this helper existed.
+ */
+function failRun(toolbox) {
+    var _a, _b;
+    if (!((_b = (_a = toolbox.parameters) === null || _a === void 0 ? void 0 : _a.options) === null || _b === void 0 ? void 0 : _b.fromGluegunMenu)) {
+        process.exitCode = 1;
+    }
+}

package/build/lib/heal-check-wrapper.js

@@ -1,24 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.healCheckWrapper = healCheckWrapper;
+exports.resolveCopySet = resolveCopySet;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const path_1 = require("path");
 /** Marker value for the report-driven check wrapper. */
 const WRAPPER = 'node scripts/check.mjs';
+/** Where the wrapper and its imports live inside a project. */
+const SCRIPTS_DIR = 'scripts';
 /**
- * Idempotently install the report-driven `check.mjs` wrapper into a project.
+ * Idempotently install the report-driven check wrapper — and every module it
+ * imports — into a project.
  *
- * Copies the bundled canonical wrapper to `<root>/scripts/check.mjs` and rewrites
- * the root `package.json` so that `check` runs the wrapper while the original
- * chain is preserved as `check:raw`. A no-op once already wired (so it is safe to
- * run on every `lt fullstack update`).
+ * Copies the bundled wrapper to `<root>/scripts/check.mjs`, copies its whole
+ * relative-import closure alongside it under the names the wrapper imports them
+ * by, and rewrites the root `package.json` so that `check` runs the wrapper
+ * while the original chain is preserved as `check:raw`. A no-op once already
+ * wired (so it is safe to run on every `lt fullstack update`).
  *
  * `lt fullstack init` already ships the wrapper via the template clone; this is
  * the MIGRATION path that brings it into pre-existing projects.
  *
+ * The copy set moves ATOMICALLY: if any member must be skipped, none are
+ * written. A partial update would leave `check.mjs` and a sibling on different
+ * versions, and the project's `check` then dies on an import mismatch before
+ * running a single step.
+ *
  * @param projectRoot Absolute path to the (workspace) project root.
- * @param assetPath   Absolute path to the bundled canonical `check.mjs`.
+ * @param assetPath   Absolute path to the bundled wrapper. Its DIRECTORY is
+ *                    also probed: every module the wrapper imports relatively
+ *                    (transitively) is shipped from there. The asset always
+ *                    lands as `scripts/check.mjs` regardless of its own name.
  * @returns The list of changed file paths (relative to `projectRoot`); empty when nothing changed.
  */
 function healCheckWrapper(projectRoot, assetPath) {
@@ -39,22 +52,35 @@ function healCheckWrapper(projectRoot, assetPath) {
     if (!scripts || typeof scripts.check !== 'string') {
         return changed;
     }
-    // 1. Ensure scripts/check.mjs exists and matches the bundled canonical version.
-    // GUARD: never overwrite a check.mjs with UNCOMMITTED local modifications —
-    // that would silently destroy work that exists nowhere else. A committed
-    // divergence is overwritten (recoverable via `git diff`/history, and the
-    // canonical wrapper is the supported version); an uncommitted one is kept and
-    // reported via the 'scripts/check.mjs (skipped: uncommitted changes)' entry.
-    const targetScript = (0, path_1.join)(projectRoot, 'scripts', 'check.mjs');
-    const bundled = (0, fs_1.readFileSync)(assetPath, 'utf8');
-    if (!(0, fs_1.existsSync)(targetScript) || (0, fs_1.readFileSync)(targetScript, 'utf8') !== bundled) {
-        if ((0, fs_1.existsSync)(targetScript) && hasUncommittedChanges(projectRoot, 'scripts/check.mjs')) {
-            changed.push('scripts/check.mjs (skipped: uncommitted changes — commit or discard them, then re-run)');
-        }
-        else {
-            (0, fs_1.mkdirSync)((0, path_1.dirname)(targetScript), { recursive: true });
-            (0, fs_1.copyFileSync)(assetPath, targetScript);
-            changed.push('scripts/check.mjs');
+    // 1. Ensure the wrapper — and everything it imports — exists in the project
+    // and matches the canonical version.
+    //
+    // The set is derived from the wrapper's own import statements rather than a
+    // hard-coded name: the wrapper grew a sibling (`build-test-gate.mjs`, which
+    // serialises the CPU-heavy build against the API e2e suite), and copying only
+    // `check.mjs` installs a file whose very first import resolves to nothing —
+    // the project's `check` then dies with ERR_MODULE_NOT_FOUND before running a
+    // single step. Deriving it from the imports (not from "every .mjs in the
+    // directory") keeps the next sibling free of changes here while making sure a
+    // stray file in the asset dir never claims a path in the project's scripts/.
+    const copies = resolveCopySet(assetPath);
+    // Decide EVERY member before writing ANY of them — see the atomicity note in
+    // the doc block above.
+    const plans = copies.map((copy) => planCopy(projectRoot, copy));
+    const blocked = plans.filter((p) => p.action === 'skip');
+    if (blocked.length > 0) {
+        // One entry for the whole set: the set is what could not be updated, and
+        // naming only the blocking member would suggest the others did land.
+        const names = blocked.map((p) => p.rel).join(', ');
+        changed.push(`${copies.map((c) => c.rel).join(' + ')} (skipped: uncommitted changes in ${names} — commit or discard them, then re-run)`);
+    }
+    else {
+        for (const plan of plans) {
+            if (plan.action === 'up-to-date') {
+                continue;
+            }
+            writeCopy(projectRoot, plan);
+            changed.push(plan.rel);
         }
     }
     // 2. Wire package.json: `check` runs the wrapper; the original chain becomes `check:raw`.
@@ -69,11 +95,57 @@ function healCheckWrapper(projectRoot, assetPath) {
     return changed;
 }
 /**
- * True when `relPath` has UNCOMMITTED modifications in the project's git tree.
- * Overwriting such a file would destroy work that exists nowhere else — a
- * committed file is recoverable via git, an uncommitted edit is not. Non-git
- * projects (or git errors) return false: there the overwrite is the only way
- * to distribute fixes, and `git` cannot protect what it does not track.
+ * The wrapper plus the transitive closure of its relative imports.
+ *
+ * Matches both quote styles: the bundled `.mjs` files are formatted by the
+ * consuming project's formatter, not by this repo's, so their quote style is
+ * not ours to assume.
+ */
+function resolveCopySet(assetPath) {
+    const assetDir = (0, path_1.dirname)(assetPath);
+    // Regular files only — a directory named `*.mjs` would otherwise reach
+    // copyFileSync and abort the whole migration with EISDIR.
+    const available = new Set((0, fs_1.readdirSync)(assetDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name));
+    const copies = [{ rel: `${SCRIPTS_DIR}/check.mjs`, source: assetPath }];
+    // Keyed by target rel, NOT by source basename: the asset lands as
+    // `scripts/check.mjs` whatever it is called, so a `check.mjs` sitting beside a
+    // differently-named asset must not claim that same path a second time.
+    const claimed = new Set(copies.map((c) => c.rel));
+    const queue = [assetPath];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const file = queue.shift();
+        if (visited.has(file)) {
+            continue;
+        }
+        visited.add(file);
+        let source;
+        try {
+            source = (0, fs_1.readFileSync)(file, 'utf8');
+        }
+        catch (_a) {
+            continue;
+        }
+        for (const match of source.matchAll(/\bfrom\s+['"]\.\/([^'"/]+)['"]/g)) {
+            const name = match[1];
+            const rel = `${SCRIPTS_DIR}/${name}`;
+            if (claimed.has(rel) || !available.has(name)) {
+                continue;
+            }
+            claimed.add(rel);
+            const resolved = (0, path_1.join)(assetDir, name);
+            copies.push({ rel, source: resolved });
+            queue.push(resolved);
+        }
+    }
+    return copies;
+}
+/**
+ * True when the TRACKED `relPath` has uncommitted modifications. Overwriting
+ * such a file would destroy work that exists nowhere else. Only meaningful for
+ * a tracked path — see `isTracked`.
  */
 function hasUncommittedChanges(projectRoot, relPath) {
     try {
@@ -87,3 +159,93 @@ function hasUncommittedChanges(projectRoot, relPath) {
         return false;
     }
 }
+/** True when `target` is a symlink (checked without following it). */
+function isSymlink(target) {
+    try {
+        return (0, fs_1.lstatSync)(target).isSymbolicLink();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * True when git tracks `relPath`, i.e. it holds a recoverable copy.
+ *
+ * An empty `git status --porcelain` alone does NOT establish that: it is also
+ * empty for an ignored file, and for a path in a directory git knows nothing
+ * about. Those are precisely the cases where an overwrite is unrecoverable.
+ */
+function isTracked(projectRoot, relPath) {
+    try {
+        (0, child_process_1.execFileSync)('git', ['-C', projectRoot, 'ls-files', '--error-unmatch', '--', relPath], {
+            stdio: 'ignore',
+        });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/** Decide what should happen to one copy target, without touching the disk. */
+function planCopy(projectRoot, copy) {
+    const target = (0, path_1.join)(projectRoot, copy.rel);
+    const plan = Object.assign(Object.assign({}, copy), { action: 'write', backup: false });
+    if (!(0, fs_1.existsSync)(target)) {
+        return plan;
+    }
+    // A symlink here resolves OUTSIDE the project, and git reports the (unchanged)
+    // link blob as clean, so the guard below cannot see it. Writing would silently
+    // modify a file somewhere else entirely.
+    if (isSymlink(target)) {
+        plan.action = 'skip';
+        return plan;
+    }
+    if ((0, fs_1.readFileSync)(target, 'utf8') === (0, fs_1.readFileSync)(copy.source, 'utf8')) {
+        plan.action = 'up-to-date';
+        return plan;
+    }
+    // A TRACKED file whose working copy diverges carries edits that exist nowhere
+    // else — never overwrite it. A tracked-and-clean file is safe to replace
+    // (git can restore it). Anything git does not track is not recoverable at
+    // all, so it gets a `.bak` instead of a refusal: refusing would be the worse
+    // outcome, because the wrapper's OWN previous output is untracked until the
+    // user commits it, and a refusal there permanently blocks the update.
+    if (isTracked(projectRoot, copy.rel)) {
+        if (hasUncommittedChanges(projectRoot, copy.rel)) {
+            plan.action = 'skip';
+        }
+        return plan;
+    }
+    plan.backup = true;
+    return plan;
+}
+/** Write one planned copy, backing up an unversioned target first. */
+function writeCopy(projectRoot, plan) {
+    const target = (0, path_1.join)(projectRoot, plan.rel);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true });
+    if (plan.backup && (0, fs_1.existsSync)(target)) {
+        const backup = `${target}.bak`;
+        // Keep the FIRST backup — a later run must not overwrite the original with
+        // an already-generated copy.
+        if (!(0, fs_1.existsSync)(backup)) {
+            (0, fs_1.copyFileSync)(target, backup);
+        }
+    }
+    // temp + rename so an interrupted run can never leave a half-written wrapper.
+    const tmp = `${target}.lt-tmp-${process.pid}`;
+    try {
+        (0, fs_1.copyFileSync)(plan.source, tmp);
+        (0, fs_1.renameSync)(tmp, target);
+    }
+    catch (error) {
+        try {
+            if ((0, fs_1.existsSync)(tmp)) {
+                (0, fs_1.unlinkSync)(tmp);
+            }
+        }
+        catch (_a) {
+            /* best effort */
+        }
+        throw error;
+    }
+}

package/build/lib/hoist-workspace-pnpm-config.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractKeyComments = extractKeyComments;
+exports.reattachKeyComments = reattachKeyComments;
 exports.hoistPackageManager = hoistPackageManager;
 exports.hoistWorkspacePnpmConfig = hoistWorkspacePnpmConfig;
 const js_yaml_1 = require("js-yaml");
@@ -35,11 +37,162 @@ const OBJECT_FIELDS = ['overrides', 'allowBuilds'];
 const ARRAY_FIELDS = ['onlyBuiltDependencies', 'ignoredOptionalDependencies', 'minimumReleaseAgeExclude'];
 /** Objects whose values are arrays to be unioned, not replaced. */
 const NESTED_ARRAY_FIELDS = ['auditConfig'];
+/** The union of all three, in declaration order. Declared here, with its inputs,
+ * because the comment-carrying helpers below default their `fields` parameter to it. */
+const WORKSPACE_SCOPED_PNPM_FIELDS = [...OBJECT_FIELDS, ...ARRAY_FIELDS, ...NESTED_ARRAY_FIELDS];
+/**
+ * Separator for the composite map key.
+ *
+ * `\0` rather than a space, because a YAML mapping key may legally contain
+ * spaces — `overrides` selectors like `minimatch@>=5.0.0 <10.2.6` do — and a
+ * space would let two different (field, key) pairs collide on one entry,
+ * silently attaching one entry's reasoning to another's. Written as an escape
+ * rather than a literal control character: a raw NUL in the source makes git
+ * treat this file as binary, which costs every future reviewer the diff.
+ */
+const KEY_SEPARATOR = '\0';
+/**
+ * Control characters that must never survive into an emitted YAML comment.
+ *
+ * Everything below U+0020 except TAB (U+0009) and LF (U+000A) — CR included,
+ * deliberately: it is the one that reads as whitespace and parses as a line
+ * break. LF cannot appear here (the harvest splits on it) and TAB is harmless.
+ */
+const CONTROL_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F]/;
+const commentKey = (field, key) => `${field}${KEY_SEPARATOR}${key}`;
+/**
+ * Comment blocks attached to the entries of each top-level mapping in `raw`.
+ *
+ * Only contiguous `#` lines DIRECTLY above an entry are taken, and a blank line
+ * ends the block — a comment separated from a key by an empty line belongs to the
+ * section, not to that key, and re-attaching it would silently move a section
+ * header onto whichever entry happened to come first.
+ */
+function extractKeyComments(raw, fields = WORKSPACE_SCOPED_PNPM_FIELDS) {
+    const out = new Map();
+    if (!raw)
+        return out;
+    const lines = raw.split('\n');
+    let field = null;
+    let fieldIndent = 0;
+    let pending = [];
+    for (const line of lines) {
+        const topLevel = /^([A-Za-z_][\w-]*):\s*$/.exec(line);
+        if (topLevel) {
+            field = fields.includes(topLevel[1]) ? topLevel[1] : null;
+            fieldIndent = 0;
+            pending = [];
+            continue;
+        }
+        if (field === null)
+            continue;
+        if (/^\s*$/.test(line)) {
+            pending = [];
+            continue;
+        }
+        const indent = line.search(/\S/);
+        // Back at column 0 → the mapping is over (a new top-level key or a list item).
+        if (indent === 0) {
+            field = null;
+            pending = [];
+            continue;
+        }
+        if (/^\s*#/.test(line)) {
+            // A bare CR is NOT a line break to `String.split('\n')` but IS one to every
+            // YAML parser. So a comment containing one is re-emitted verbatim, and
+            // everything after the CR becomes real YAML at a column of its author's
+            // choosing. Verified against pnpm 11: a comment carrying
+            // `\r  left-pad: 9.9.9` installs as a workspace-wide `overrides` entry —
+            // an arbitrary version force in every generated project — while the line
+            // still renders as an ordinary comment in editors and diffs.
+            //
+            // Dropping the whole block is the right response rather than sanitising it:
+            // a rationale nobody can read is worth less than the risk of guessing what
+            // the author meant.
+            if (CONTROL_CHARS.test(line)) {
+                pending = [];
+                continue;
+            }
+            pending.push(line.trimStart());
+            continue;
+        }
+        const entry = /^\s*((?:'[^']*')|(?:"[^"]*")|(?:[^\s:#][^:]*?))\s*:/.exec(line);
+        if (!entry) {
+            pending = [];
+            continue;
+        }
+        // Nested deeper than the first entry level (e.g. `auditConfig.ignoreGhsas`
+        // items) — the block belongs to the inner key, which this pass does not carry.
+        if (fieldIndent === 0)
+            fieldIndent = indent;
+        if (indent === fieldIndent && pending.length) {
+            out.set(commentKey(field, unquoteYamlKey(entry[1])), pending.join('\n'));
+        }
+        pending = [];
+    }
+    return out;
+}
+/**
+ * Put the harvested comment blocks back above their keys in dumped YAML.
+ *
+ * A key whose comment is already present is left alone, so re-running the hoist
+ * over an already-annotated file is idempotent rather than stuttering.
+ */
+function reattachKeyComments(yaml, comments, fields = WORKSPACE_SCOPED_PNPM_FIELDS) {
+    var _a;
+    if (comments.size === 0)
+        return yaml;
+    const lines = yaml.split('\n');
+    const out = [];
+    let field = null;
+    let fieldIndent = 0;
+    for (const line of lines) {
+        const topLevel = /^([A-Za-z_][\w-]*):\s*$/.exec(line);
+        if (topLevel) {
+            field = fields.includes(topLevel[1]) ? topLevel[1] : null;
+            fieldIndent = 0;
+            out.push(line);
+            continue;
+        }
+        if (field !== null && !/^\s*$/.test(line)) {
+            const indent = line.search(/\S/);
+            if (indent === 0) {
+                field = null;
+            }
+            else {
+                const entry = /^\s*((?:'[^']*')|(?:"[^"]*")|(?:[^\s:#][^:]*?))\s*:/.exec(line);
+                if (entry) {
+                    if (fieldIndent === 0)
+                        fieldIndent = indent;
+                    if (indent === fieldIndent) {
+                        const block = comments.get(commentKey(field, unquoteYamlKey(entry[1])));
+                        // `out[out.length - 1]`, not `.at(-1)`: this project's tsconfig lib
+                        // predates ES2022.
+                        const already = ((_a = out[out.length - 1]) !== null && _a !== void 0 ? _a : '').trim().startsWith('#');
+                        // Second gate on purpose: harvest is one source of blocks today, and a
+                        // control character reaching the emitted file is the whole exploit.
+                        if (block && !already && !CONTROL_CHARS.test(block)) {
+                            const pad = ' '.repeat(indent);
+                            out.push(...block.split('\n').map((l) => `${pad}${l}`));
+                        }
+                    }
+                }
+            }
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+/** `'msgpackr-extract'` / `"foo"` / `foo` all denote the same mapping key. */
+function unquoteYamlKey(raw) {
+    const trimmed = raw.trim();
+    const quoted = /^(['"])([\s\S]*)\1$/.exec(trimmed);
+    return quoted ? quoted[2] : trimmed;
+}
 /** Provenance note written above a hoisted `auditConfig` — see `annotateAuditConfig`. */
 const AUDIT_CONFIG_NOTE = '# Hoisted from the sub-projects by the lt CLI. These advisory suppressions now\n' +
     '# apply to EVERY package in this workspace, not just the one that justified\n' +
     '# them — review before adding, and drop entries once the advisory is fixed.';
-const WORKSPACE_SCOPED_PNPM_FIELDS = [...OBJECT_FIELDS, ...ARRAY_FIELDS, ...NESTED_ARRAY_FIELDS];
 const isArrayField = (field) => ARRAY_FIELDS.includes(field);
 const isNestedArrayField = (field) => NESTED_ARRAY_FIELDS.includes(field);
 /**
@@ -157,13 +310,18 @@ function hoistPackageManager(options) {
  * @param options.subProjects Sub-project dirs relative to projectDir
  */
 function hoistWorkspacePnpmConfig(options) {
-    var _a;
+    var _a, _b;
     const { filesystem, projectDir, subProjects } = options;
     const rootWsPath = `${projectDir}/pnpm-workspace.yaml`;
     // The root pnpm-workspace.yaml is the destination. It normally exists (the
     // lt-monorepo clone ships one declaring `packages:`); start from it so
     // `packages:` and any root-owned settings are preserved.
     const rootWs = (_a = readYaml(filesystem, rootWsPath)) !== null && _a !== void 0 ? _a : {};
+    // Why the reasons are harvested rather than regenerated: they are prose written
+    // by whoever added the entry, and no rule can reconstruct them. The root's own
+    // comments are collected FIRST so that where two sources annotate the same key,
+    // the root's wording wins — it is the file a maintainer of THIS workspace edits.
+    const comments = extractKeyComments((_b = filesystem.read(rootWsPath)) !== null && _b !== void 0 ? _b : '');
     let rootChanged = false;
     for (const subDir of subProjects) {
         const subPath = `${projectDir}/${subDir}`;
@@ -176,7 +334,7 @@ function hoistWorkspacePnpmConfig(options) {
         if (hoistFromSubPackageJson({ filesystem, rootWs, subPath })) {
             rootChanged = true;
         }
-        if (hoistFromSubWorkspaceYaml({ filesystem, rootWs, subPath })) {
+        if (hoistFromSubWorkspaceYaml({ comments, filesystem, rootWs, subPath })) {
             rootChanged = true;
         }
     }
@@ -184,7 +342,8 @@ function hoistWorkspacePnpmConfig(options) {
         // Keep allowBuilds (pnpm 11) and onlyBuiltDependencies (pnpm 10) in sync so
         // the build-script allowlist survives regardless of which key pnpm reads.
         syncBuildAllowlists(rootWs);
-        filesystem.write(rootWsPath, annotateAuditConfig((0, js_yaml_1.dump)(rootWs, { lineWidth: -1, sortKeys: false })));
+        const dumped = (0, js_yaml_1.dump)(rootWs, { lineWidth: -1, sortKeys: false });
+        filesystem.write(rootWsPath, annotateAuditConfig(reattachKeyComments(dumped, comments)));
     }
 }
 /**
@@ -264,13 +423,22 @@ function hoistFromSubPackageJson(options) {
 }
 /** Source 2: the sub-project's pnpm-workspace.yaml. */
 function hoistFromSubWorkspaceYaml(options) {
-    const { filesystem, rootWs, subPath } = options;
+    var _a;
+    const { comments, filesystem, rootWs, subPath } = options;
     const subWsPath = `${subPath}/pnpm-workspace.yaml`;
     if (!filesystem.exists(subWsPath))
         return false;
+    const raw = (_a = filesystem.read(subWsPath)) !== null && _a !== void 0 ? _a : '';
     const ws = readYaml(filesystem, subWsPath);
     if (!ws)
         return false;
+    // Harvest BEFORE hoisting: this file is about to be deleted (or stripped of
+    // exactly these keys), and with it the only copy of the reasoning. An entry
+    // already annotated by the root keeps the root's wording.
+    for (const [key, block] of extractKeyComments(raw)) {
+        if (!comments.has(key))
+            comments.set(key, block);
+    }
     if (!hoistFields(rootWs, ws))
         return false;
     // A settings-only file (no `packages:`) exists solely to carry these