forgedock 1.30.0 → 1.32.0

package/bin/lean/sequence.test.mjs

@@ -5,10 +5,10 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber } from "./sequence.mjs";
+import { sequenceCollisions, journalProblems, snapshotLane, verifyRenumber, numberOnlyChange, renumberLane, resolveSequenceConflicts } from "./sequence.mjs";
 import { sequencePrompt, sequenceSyncNote } from "./prompts.mjs";
 
 const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
@@ -109,4 +109,265 @@ describe("sequence-numbered migrations at hand-off (#4322)", () => {
     assert.match(sequenceSyncNote(["db/drizzle/meta/_journal.json"]), /do not text-merge/);
     assert.match(sequenceSyncNote(["db/drizzle/0007_usage.sql"]), /Renumber the lane's files/);
   });
+
+  /** A base commit with `baseFiles`, a lane commit adding `laneFiles`, then `laterBase` on main; returns the repo on the lane. */
+  const twoCommits = (baseFiles, laneFiles, laterBase = null) => {
+    const d = tmpDir("seq-");
+    sh(d, "init", "-q", "-b", "main");
+    put(d, baseFiles); commit(d, "base");
+    sh(d, "checkout", "-qb", "lane");
+    put(d, laneFiles); commit(d, "lane");
+    if (laterBase) { sh(d, "checkout", "-q", "main"); put(d, laterBase); commit(d, "later base"); sh(d, "checkout", "-q", "lane"); }
+    return d;
+  };
+
+  it("date and issue-number filename prefixes are not sequence numbers (#4343)", async () => {
+    const d = twoCommits(
+      { "blog/2026-10-05-first.md": "a\n", "news/20261005-a.md": "a\n", "docs/4322-a.md": "a\n", "docs2/2447-a.md": "a\n", "docs2/4160-b.md": "b\n" },
+      { "blog/2026-10-20-second.md": "b\n", "news/20261020-b.md": "b\n", "docs/4322-b.md": "b\n", "docs2/4160-c.md": "c\n" },
+    );
+    assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+    assert.deepEqual(await snapshotLane({ git: gitIn(d), base: "main" }).then((s) => s.map((f) => f.path).sort()), ["docs/4322-b.md", "docs2/4160-c.md"]);
+    assert.equal(sequenceSyncNote(["blog/2026-10-05-first.md"]), "");
+    assert.equal(sequenceSyncNote(["news/20261005-a.md"]), "");
+  });
+
+  it("real series still collide: SQL, Python, drizzle with a single base migration plus journal (#4343)", async () => {
+    const d = twoCommits(
+      {
+        "db/0006_a.sql": "a\n", "db/0007_other.sql": "o\n",
+        "app/migrations/0001_initial.py": "i\n", "app/migrations/0002_x.py": "x\n", "app/migrations/__init__.py": "",
+        "drizzle/0000_init.sql": "CREATE TABLE t (id int);\n", "drizzle/meta/_journal.json": journal("0000_init"),
+      },
+      { "db/0007_usage.sql": "u\n", "app/migrations/0002_y.py": "y\n", "drizzle/0000_x.sql": "CREATE TABLE x (id int);\n", "drizzle/meta/0000_snapshot.json": '{"id":"lane0"}\n' },
+      { "drizzle/meta/0000_snapshot.json": '{"id":"s0"}\n' },
+    );
+    const c = await sequenceCollisions({ git: gitIn(d), base: "main" });
+    assert.deepEqual(c.map((x) => [x.lane, x.base, x.next]).sort((a, b) => a[0].localeCompare(b[0])), [
+      ["app/migrations/0002_y.py", ["app/migrations/0002_x.py"], "0003"],
+      ["db/0007_usage.sql", ["db/0007_other.sql"], "0008"],
+      ["drizzle/0000_x.sql", ["drizzle/0000_init.sql"], "0001"],
+      ["drizzle/meta/0000_snapshot.json", ["drizzle/meta/0000_snapshot.json"], "0001"],
+    ]);
+  });
+});
+
+describe("deterministic renumber (#4386)", () => {
+  /** main gets `baseFiles`, the lane (from main) adds `laneFiles`, then main gets `laterBase`; returns the repo on the lane. */
+  const repo = (baseFiles, laneFiles, laterBase) => {
+    const d = tmpDir("seq4386-");
+    sh(d, "init", "-q", "-b", "main");
+    put(d, baseFiles); commit(d, "base");
+    sh(d, "checkout", "-qb", "lane");
+    put(d, laneFiles); commit(d, "lane");
+    sh(d, "checkout", "-q", "main"); put(d, laterBase); commit(d, "later base");
+    sh(d, "checkout", "-q", "lane");
+    return d;
+  };
+  const show = (d, p) => sh(d, "show", `HEAD:${p}`);
+  const snap = (id, prevId, tables = { t: 1 }) => `${JSON.stringify({ version: "7", id, prevId, tables }, null, 2)}\n`;
+  const NCLT_SQL = "INSERT INTO adapters (name) VALUES ('nclt');\n";
+  /** base 0048; the lane adds a data-only 0049_nclt; then the base takes 0049-0051. */
+  const drizzle = ({ laneTables = { t: 1 } } = {}) => repo(
+    { "db/0048_init.sql": "CREATE TABLE t (id int);\n", "db/meta/_journal.json": journal("0048_init"), "db/meta/0048_snapshot.json": snap("s48", "s47") },
+    { "db/0049_nclt.sql": NCLT_SQL, "db/meta/_journal.json": journal("0048_init", "0049_nclt"), "db/meta/0049_snapshot.json": snap("lane49", "s48", laneTables) },
+    {
+      "db/0049_a.sql": "a;\n", "db/0050_b.sql": "b;\n", "db/0051_c.sql": "CREATE TABLE u (id int);\n",
+      "db/meta/_journal.json": journal("0048_init", "0049_a", "0050_b", "0051_c"),
+      "db/meta/0049_snapshot.json": snap("s49", "s48"), "db/meta/0050_snapshot.json": snap("s50", "s49"), "db/meta/0051_snapshot.json": snap("s51", "s50", { t: 1, u: 1 }),
+    },
+  );
+
+  it("verifyRenumber accepts an ADR whose only change is its own heading number, and an index row change (#4386)", async () => {
+    const adr = (body) => repo(
+      { "docs/adr/0015-a.md": "# 0015. A\n", "docs/adr/0016-b.md": "# 0016. B\n", "docs/adr/README.md": "| 0015 | A |\n| 0016 | B |\n" },
+      { "docs/adr/0017-nclt.md": "# 0017. NCLT adapter\n\nWe adopt 0017-style adapters.\n", "docs/adr/README.md": "| 0015 | A |\n| 0016 | B |\n| 0017 | [NCLT](0017-nclt.md) |\n" },
+      { "docs/adr/0017-other.md": "# 0017. Other\n", "docs/adr/README.md": "| 0015 | A |\n| 0016 | B |\n| 0017 | Other |\n" },
+    );
+    for (const [body, ok] of [["We adopt 0017-style adapters.", true], ["We adopt other adapters.", false]]) {
+      const d = adr();
+      const before = await snapshotLane({ git: gitIn(d), base: "main" });
+      try { sh(d, "merge", "--no-edit", "main"); } catch { /* README conflict: resolved below */ }
+      sh(d, "mv", "-f", "docs/adr/0017-nclt.md", "docs/adr/0018-nclt.md");
+      put(d, { "docs/adr/0018-nclt.md": `# 0018. NCLT adapter\n\n${body}\n`, "docs/adr/README.md": "| 0015 | A |\n| 0016 | B |\n| 0017 | Other |\n| 0018 | [NCLT](0018-nclt.md) |\n" });
+      commit(d, "renumber");
+      const v = await verifyRenumber({ git: gitIn(d), base: "main", before });
+      assert.equal(v.ok, ok, v.problems.join("; "));
+      if (!ok) assert.match(v.problems.join("\n"), /docs\/adr\/0017-nclt\.md: content changed/);
+    }
+  });
+
+  it("base takes 0049-0051 while the lane holds 0049: renumberLane moves it to 0052, clones the tip snapshot, appends the journal, and the lane merges", async () => {
+    const d = drizzle();
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    const r = await renumberLane({ git: gitIn(d), base: "main", cwd: d, uuid: () => "fresh-id" });
+    assert.deepEqual(r.moves, [{ from: "db/0049_nclt.sql", to: "db/0052_nclt.sql" }]);
+    assert.equal(r.commit, sh(d, "rev-parse", "HEAD").trim());
+    assert.equal(show(d, "db/0052_nclt.sql"), NCLT_SQL, "SQL byte-identical");
+    assert.ok(!existsSync(join(d, "db/0049_nclt.sql")));
+    assert.equal(show(d, "db/meta/0049_snapshot.json"), snap("s49", "s48"), "base snapshot restored at the shared path");
+    const base51 = JSON.parse(show(d, "db/meta/0051_snapshot.json")), mine = JSON.parse(show(d, "db/meta/0052_snapshot.json"));
+    assert.deepEqual(mine, { ...base51, id: "fresh-id", prevId: "s51" });
+    const j = JSON.parse(show(d, "db/meta/_journal.json"));
+    const baseJ = JSON.parse(sh(d, "show", "main:db/meta/_journal.json"));
+    assert.deepEqual(j.entries.slice(0, 4), baseJ.entries);
+    assert.deepEqual(j.entries[4], { idx: 4, tag: "0052_nclt", when: 1001 });
+    assert.deepEqual(j.entries.map((e) => e.idx), [0, 1, 2, 3, 4]);
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+    assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+    assert.deepEqual(await verifyRenumber({ git: gitIn(d), base: "main", before, moves: r.moves }), { ok: true, problems: [] });
+    sh(d, "checkout", "-q", "main");
+    sh(d, "merge", "--no-edit", "lane"); // the lane merges into its base without conflicts
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+  });
+
+  it("references to the old basename are rewritten repo-wide (a link from another ADR, a code comment) and the index keeps both rows", async () => {
+    const d = repo(
+      { "docs/adr/0015-a.md": "# 0015. A\n", "docs/adr/0016-b.md": "# 0016. B\n", "docs/adr/0017-c.md": "# 0017. C\n", "docs/adr/0018-d.md": "# 0018. D\n", "docs/adr/README.md": "# ADRs\n\n- 0018 D\n", "src/x.ts": "export const x = 1;\n" },
+      { "docs/adr/0019-nclt.md": "# 0019. NCLT\n\nSupersedes nothing.\n", "docs/adr/0015-a.md": "# 0015. A\n\nSee [NCLT](0019-nclt.md).\n", "docs/adr/README.md": "# ADRs\n\n- 0018 D\n- [0019 NCLT](0019-nclt.md)\n", "src/x.ts": "// docs/adr/0019-nclt.md\nexport const x = 1;\n" },
+      { "docs/adr/0019-other.md": "# 0019. Other\n", "docs/adr/README.md": "# ADRs\n\n- 0018 D\n- 0019 Other\n" },
+    );
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    const r = await renumberLane({ git: gitIn(d), base: "main", cwd: d });
+    assert.deepEqual(r.moves, [{ from: "docs/adr/0019-nclt.md", to: "docs/adr/0020-nclt.md" }]);
+    assert.equal(show(d, "docs/adr/0020-nclt.md"), "# 0020. NCLT\n\nSupersedes nothing.\n");
+    assert.equal(show(d, "docs/adr/0015-a.md"), "# 0015. A\n\nSee [NCLT](0020-nclt.md).\n");
+    assert.equal(show(d, "src/x.ts"), "// docs/adr/0020-nclt.md\nexport const x = 1;\n");
+    const idx = show(d, "docs/adr/README.md");
+    assert.match(idx, /0019 Other/);
+    assert.match(idx, /\(0020-nclt\.md\)/);
+    assert.doesNotMatch(idx, /<<<<<<<|0019-nclt/);
+    assert.equal(sh(d, "status", "--porcelain").trim(), "");
+    assert.deepEqual(await verifyRenumber({ git: gitIn(d), base: "main", before, moves: r.moves }), { ok: true, problems: [] });
+  });
+
+  it("falls back (unsupported, branch unchanged) for a schema-changing migration without regenerate or a .py migration; a regenerate command fills the snapshot", async () => {
+    let d = drizzle({ laneTables: { t: 1, nclt: 1 } });
+    let head = sh(d, "rev-parse", "HEAD");
+    let r = await renumberLane({ git: gitIn(d), base: "main", cwd: d });
+    assert.match(r.unsupported, /schema-changing migration db\/0049_nclt\.sql needs lean\.sequence\.regenerate/);
+    assert.equal(sh(d, "rev-parse", "HEAD"), head);
+    assert.equal(sh(d, "status", "--porcelain").trim(), "");
+    const calls = [];
+    r = await renumberLane({ git: gitIn(d), base: "main", cwd: d, regenerate: "pnpm db:generate", run: async (cmd, o) => { calls.push(cmd); writeFileSync(join(o.cwd, "db/meta/0052_snapshot.json"), snap("gen", "s51", { t: 1, u: 1, nclt: 1 })); } });
+    assert.ok(r.ok, r.unsupported);
+    assert.deepEqual(calls, ["pnpm db:generate"]);
+    assert.equal(JSON.parse(show(d, "db/meta/0052_snapshot.json")).id, "gen");
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+    d = repo({ "app/migrations/0001_initial.py": "i\n", "app/migrations/0002_x.py": "x\n" }, { "app/migrations/0003_y.py": "y\n" }, { "app/migrations/0003_z.py": "z\n" });
+    head = sh(d, "rev-parse", "HEAD");
+    r = await renumberLane({ git: gitIn(d), base: "main", cwd: d });
+    assert.match(r.unsupported, /app\/migrations\/0003_y\.py: no deterministic renumber for \.py migrations/);
+    assert.equal(sh(d, "rev-parse", "HEAD"), head);
+  });
+
+  it("resolveSequenceConflicts takes the base side for journal/snapshot conflicts, then renumberLane from the pre-merge head gives a valid chain; another conflicted file is unsupported", async () => {
+    let d = drizzle();
+    const pre = sh(d, "rev-parse", "HEAD").trim();
+    assert.throws(() => sh(d, "merge", "--no-edit", "main"));
+    const files = sh(d, "diff", "--name-only", "--diff-filter=U").trim().split("\n");
+    assert.deepEqual(files.sort(), ["db/meta/0049_snapshot.json", "db/meta/_journal.json"]);
+    assert.deepEqual(await resolveSequenceConflicts({ git: gitIn(d), files }), { ok: true });
+    assert.ok(!existsSync(join(d, ".git", "MERGE_HEAD")), "merge committed");
+    const r = await renumberLane({ git: gitIn(d), base: "main", cwd: d, laneRef: pre, uuid: () => "u52" });
+    assert.deepEqual(r.moves, [{ from: "db/0049_nclt.sql", to: "db/0052_nclt.sql" }]);
+    assert.deepEqual(JSON.parse(show(d, "db/meta/_journal.json")).entries.map((e) => e.tag), ["0048_init", "0049_a", "0050_b", "0051_c", "0052_nclt"]);
+    assert.equal(JSON.parse(show(d, "db/meta/0052_snapshot.json")).prevId, "s51");
+    assert.deepEqual(await journalProblems({ git: gitIn(d), dirs: ["db"] }), []);
+    d = repo({ "db/0001_a.sql": "a\n", "db/0002_b.sql": "b\n", "db/meta/_journal.json": journal("0001_a", "0002_b"), "src/a.ts": "1\n" },
+      { "db/0003_c.sql": "c\n", "db/meta/_journal.json": journal("0001_a", "0002_b", "0003_c"), "src/a.ts": "2\n" },
+      { "db/0003_d.sql": "d\n", "db/meta/_journal.json": journal("0001_a", "0002_b", "0003_d"), "src/a.ts": "3\n" });
+    assert.throws(() => sh(d, "merge", "--no-edit", "main"));
+    const f2 = sh(d, "diff", "--name-only", "--diff-filter=U").trim().split("\n");
+    assert.deepEqual(await resolveSequenceConflicts({ git: gitIn(d), files: f2 }), { unsupported: "non-sequence conflict: src/a.ts" });
+    assert.ok(readFileSync(join(d, "src/a.ts"), "utf8").includes("<<<<<<<"), "left for the builder");
+  });
+
+  it("#4465: a numbered file both sides edited, or one outside a series, is not a sequence conflict: unsupported, the lane's edit kept for the builder", async () => {
+    const conflict = async (base, lane, later, file) => {
+      const d = repo(base, lane, later);
+      assert.throws(() => sh(d, "merge", "--no-edit", "main"));
+      const files = sh(d, "diff", "--name-only", "--diff-filter=U").trim().split("\n");
+      assert.deepEqual(files, [file]);
+      assert.deepEqual(await resolveSequenceConflicts({ git: gitIn(d), files }), { unsupported: `non-sequence conflict: ${file}` });
+      assert.ok(existsSync(join(d, ".git", "MERGE_HEAD")), "merge not committed");
+      assert.match(readFileSync(join(d, file), "utf8"), /<<<<<<<[\s\S]*LANE[\s\S]*BASE/, "lane side still present");
+    };
+    // both edit an existing NNN- source file (no series)
+    await conflict({ "src/404-page.tsx": "a\nb\nc\n" }, { "src/404-page.tsx": "a\nLANE\nc\n" }, { "src/404-page.tsx": "a\nBASE\nc\n" }, "src/404-page.tsx");
+    // both edit an ADR inside a real series: renumberLane only restores lane-added files
+    const adrs = { "docs/adr/0001-one.md": "# 1. One\n", "docs/adr/0002-two.md": "# 2. Two\nx\n", "docs/adr/0003-three.md": "# 3. Three\n" };
+    await conflict(adrs, { "docs/adr/0002-two.md": "# 2. Two\nLANE\n" }, { "docs/adr/0002-two.md": "# 2. Two\nBASE\n" }, "docs/adr/0002-two.md");
+    // both add the same numbered name in a directory without a series
+    await conflict({ "src/a.ts": "1\n" }, { "src/500_error.html": "LANE\n" }, { "src/500_error.html": "BASE\n" }, "src/500_error.html");
+  });
+});
+
+describe("sequence-numbered documents: two siblings each add an ADR (#4385)", () => {
+  const INDEX = "# ADRs\n\n- [0001](0001-one.md)\n- [0002](0002-two.md)\n- [0003](0003-three.md)\n";
+  /** main: docs/adr/0001..0003 + README index; the lane adds 0004-b.md; main then merges a sibling's 0004-a.md. */
+  function adrFixture() {
+    const d = tmpDir("seq-adr-");
+    sh(d, "init", "-q", "-b", "main");
+    put(d, { "docs/adr/0001-one.md": "# 1. One\n", "docs/adr/0002-two.md": "# 2. Two\n", "docs/adr/0003-three.md": "# 3. Three\n", "docs/adr/README.md": INDEX });
+    commit(d, "init");
+    sh(d, "checkout", "-qb", "lane");
+    put(d, { "docs/adr/0004-b.md": "# 4. Use B\n\nStatus: accepted (ADR 0004)\n", "docs/adr/README.md": `${INDEX}- [0004](0004-b.md)\n` });
+    commit(d, "lane adr");
+    sh(d, "checkout", "-q", "main");
+    put(d, { "docs/adr/0004-a.md": "# 4. Use A\n", "docs/adr/README.md": `${INDEX}- [0004](0004-a.md)\n` });
+    commit(d, "sibling adr");
+    sh(d, "checkout", "-q", "lane");
+    return d;
+  }
+  /** The builder: merge the base (the index conflicts), rename to 0005, fix its own title, write the index. */
+  function renumberAdr(d, { title = "# 5. Use B\n\nStatus: accepted (ADR 0005)\n", index = `${INDEX}- [0004](0004-a.md)\n- [0005](0005-b.md)\n` } = {}) {
+    try { sh(d, "merge", "--no-edit", "main"); } catch { /* README.md conflicts: written below */ }
+    sh(d, "mv", "docs/adr/0004-b.md", "docs/adr/0005-b.md");
+    put(d, { "docs/adr/0005-b.md": title, "docs/adr/README.md": index });
+    commit(d, "renumber adr");
+  }
+
+  it("the lane's ADR collides with the sibling's 0004 and moves to 0005", async () => {
+    const d = adrFixture();
+    const c = await sequenceCollisions({ git: gitIn(d), base: "main" });
+    assert.deepEqual(c.map((x) => [x.lane, x.base, x.next]), [["docs/adr/0004-b.md", ["docs/adr/0004-a.md"], "0005"]]);
+  });
+
+  it("a renumber that changes only the ADR's own number and lists both in the index verifies: distinct numbers, index correct", async () => {
+    const d = adrFixture();
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    renumberAdr(d);
+    const v = await verifyRenumber({ git: gitIn(d), base: "main", before });
+    assert.deepEqual(v, { ok: true, problems: [] });
+    assert.deepEqual(await sequenceCollisions({ git: gitIn(d), base: "main" }), []);
+  });
+
+  it("an index still linking the old name, or a body change beyond the number, fails verification", async () => {
+    const d = adrFixture();
+    const before = await snapshotLane({ git: gitIn(d), base: "main" });
+    renumberAdr(d, { index: `${INDEX}- [0004](0004-a.md)\n- [0004](0004-b.md)\n` });
+    const v = await verifyRenumber({ git: gitIn(d), base: "main", before });
+    assert.equal(v.ok, false);
+    assert.ok(v.problems.some((p) => /docs\/adr\/README\.md: still references 0004-b/.test(p)), v.problems.join("\n"));
+    const d2 = adrFixture();
+    const before2 = await snapshotLane({ git: gitIn(d2), base: "main" });
+    renumberAdr(d2, { title: "# 5. Use C instead\n\nStatus: accepted (ADR 0005)\n" });
+    const v2 = await verifyRenumber({ git: gitIn(d2), base: "main", before: before2 });
+    assert.equal(v2.ok, false);
+    assert.ok(v2.problems.some((p) => /0004-b\.md: content changed/.test(p)), v2.problems.join("\n"));
+  });
+
+  it("numberOnlyChange accepts padded and unpadded own-number edits only", () => {
+    assert.equal(numberOnlyChange("# 16. X (0016)\nsee 160 and 16x\n", "# 17. X (0017)\nsee 160 and 16x\n", "0016", "0017"), true);
+    assert.equal(numberOnlyChange("# 16. X\n", "# 17. Y\n", "0016", "0017"), false);
+    assert.equal(numberOnlyChange("CREATE TABLE t;\n", "CREATE TABLE t;\n", "0007", "0008"), true);
+    assert.equal(numberOnlyChange("a\n", "b\n", null, "0008"), false);
+  });
+
+  it("the renumber prompt names numbered documents and the series index", () => {
+    const p = sequencePrompt([{ dir: "docs/adr", number: "0004", lane: "docs/adr/0004-b.md", base: ["docs/adr/0004-a.md"], next: "0005" }], "staging");
+    assert.match(p, /ADR/);
+    assert.match(p, /series index/);
+  });
 });

package/bin/lean/toolchain.mjs

@@ -7,9 +7,9 @@
  * A repo without pins gets nothing: no shim dir, no env, no warning.
  */
 import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { join, delimiter, resolve } from "node:path";
+import { join, delimiter, resolve, dirname, isAbsolute } from "node:path";
 
 const PMS = ["pnpm", "yarn", "npm"];
 const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
@@ -145,16 +145,50 @@ export function which(name, pathStr = process.env.PATH ?? "", exclude = []) {
 const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
 const HEADER = "#!/bin/sh\n# forgedock lane toolchain shim (#4163): pinned by the target repo; do not edit.\nexport COREPACK_ENABLE_DOWNLOAD_PROMPT=0 COREPACK_ENABLE_STRICT=0\n";
 
+/** npx package spec and package name for a pin: yarn >= 2 is published as @yarnpkg/cli-dist; the npm "yarn" package is 1.x only. */
+function npxPackage(pm) {
+  const name = pm.name === "yarn" && Number(pm.version.split(".")[0]) >= 2 ? "@yarnpkg/cli-dist" : pm.name;
+  return { name, spec: `${name}@${pm.version}` };
+}
+
+/** Bin names the npx-launched shims exec for a pin (pnpx runs `pnpm dlx`, so it reuses pnpm). */
+const pinBins = (pm) => (pm.name === "npm" ? ["npm", "npx"] : [pm.name]);
+
+/**
+ * Resolve the pinned manager's real binaries once per lane (#4348): `npx -y -p <pkg>@<ver> -c 'command -v <bin>'`, which
+ * reuses npx's cache or fetches once. A path is kept only when it is an absolute executable file and its package's
+ * `package.json` (`<.bin>/../<pkg>/package.json`) has exactly the pinned version. Returns {bin: absPath}; a failed bin is
+ * omitted (its shim falls back to npx). Never throws.
+ */
+export function resolvePinnedBins(pm, { npx = null, path = process.env.PATH ?? "", run = (f, a, o) => execFileSync(f, a, o) } = {}) {
+  const out = {};
+  if (!npx || !pm || !PMS.includes(pm.name) || !VERSION_RE.test(pm.version)) return out;
+  const pkg = npxPackage(pm);
+  for (const bin of pinBins(pm)) {
+    try {
+      const p = String(run(npx, ["-y", "-p", pkg.spec, "-c", `command -v ${bin}`], { env: { ...process.env, PATH: path }, timeout: 120000, stdio: ["ignore", "pipe", "ignore"] }) ?? "").trim().split("\n").pop().trim();
+      if (!p || !isAbsolute(p) || !statSync(p).isFile()) continue;
+      accessSync(p, constants.X_OK);
+      const meta = JSON.parse(readFileSync(join(dirname(p), "..", ...pkg.name.split("/"), "package.json"), "utf8"));
+      if (meta?.version === pm.version) out[bin] = p;
+    } catch { /* unresolved: the shim falls back to npx */ }
+  }
+  return out;
+}
+
 /**
  * Shim scripts {name: content} for the pinned manager: `corepack <pm>@<ver>` when corepack is on the host PATH, else
  * `npx -y`. Absolute paths are resolved here, so a shim never re-enters the shim dir. Returns {} when neither exists.
+ * `bins` ({bin: absPath} from resolvePinnedBins) makes an npx shim exec that binary directly while it exists, keeping the
+ * npx line as the fallback (#4348).
  */
-export function shimScripts(pm, { corepack = null, npx = null } = {}) {
+export function shimScripts(pm, { corepack = null, npx = null, bins = {} } = {}) {
   if (!pm || !PMS.includes(pm.name) || !VERSION_RE.test(pm.version)) return {};
   const at = `${pm.name}@${pm.version}`;
   const out = {};
+  const direct = (bin, extra = "") => (bins?.[bin] ? `if [ -x ${q(bins[bin])} ]; then exec ${q(bins[bin])}${extra} "$@"; fi\n` : "");
   if (pm.name === "npm") {
-    if (npx) { out.npm = `${HEADER}exec ${q(npx)} -y ${q(at)} "$@"\n`; out.npx = `${HEADER}exec ${q(npx)} -y -p ${q(at)} npx "$@"\n`; }
+    if (npx) { out.npm = `${HEADER}${direct("npm")}exec ${q(npx)} -y ${q(at)} "$@"\n`; out.npx = `${HEADER}${direct("npx")}exec ${q(npx)} -y -p ${q(at)} npx "$@"\n`; }
     return out;
   }
   if (corepack) {
@@ -163,10 +197,9 @@ export function shimScripts(pm, { corepack = null, npx = null } = {}) {
     return out;
   }
   if (!npx) return out;
-  // yarn >= 2 is published as @yarnpkg/cli-dist; the npm "yarn" package is 1.x only.
-  const pkg = pm.name === "yarn" && Number(pm.version.split(".")[0]) >= 2 ? `@yarnpkg/cli-dist@${pm.version}` : at;
-  out[pm.name] = `${HEADER}exec ${q(npx)} -y -p ${q(pkg)} ${pm.name} "$@"\n`;
-  if (pm.name === "pnpm") out.pnpx = `${HEADER}exec ${q(npx)} -y -p ${q(pkg)} pnpm dlx "$@"\n`;
+  const pkg = npxPackage(pm).spec;
+  out[pm.name] = `${HEADER}${direct(pm.name)}exec ${q(npx)} -y -p ${q(pkg)} ${pm.name} "$@"\n`;
+  if (pm.name === "pnpm") out.pnpx = `${HEADER}${direct("pnpm", " dlx")}exec ${q(npx)} -y -p ${q(pkg)} pnpm dlx "$@"\n`;
   return out;
 }
 
@@ -186,16 +219,26 @@ async function writeShimFile(p, content) { await writeFile(p, content); await ch
 
 /**
  * Write executable (0755) shims for the pinned manager into `binDir`; launchers are resolved from `path` with `binDir`
- * excluded. Returns the shim names written ([] when neither corepack nor npx is on `path`).
+ * excluded. When npx is the launcher, `resolveBins` runs once to find the pinned binaries (#4348). Returns
+ * {names, unresolved}: the shim names written ([] when neither corepack nor npx is on `path`) and the bins left on npx.
  */
-export async function writeShims(binDir, pm, { path = process.env.PATH ?? "", find = which, writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }) } = {}) {
-  const scripts = shimScripts(pm, { corepack: find("corepack", path, [binDir]), npx: find("npx", path, [binDir]) });
-  if (!Object.keys(scripts).length) return [];
+async function writeShimSet(binDir, pm, { path = process.env.PATH ?? "", find = which, writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }), resolveBins = resolvePinnedBins } = {}) {
+  const corepack = find("corepack", path, [binDir]), npx = find("npx", path, [binDir]);
+  let bins = {}, unresolved = [];
+  // npx launches the shims for an npm pin, and for pnpm/yarn only without corepack (shimScripts).
+  if (npx && pm && PMS.includes(pm.name) && VERSION_RE.test(pm.version) && (pm.name === "npm" || !corepack)) {
+    try { bins = (await resolveBins(pm, { npx, path })) ?? {}; } catch { bins = {}; }
+    unresolved = pinBins(pm).filter((b) => !bins[b]);
+  }
+  const scripts = shimScripts(pm, { corepack, npx, bins });
+  if (!Object.keys(scripts).length) return { names: [], unresolved: [] };
   await mkdirp(binDir);
   for (const [name, content] of Object.entries(scripts)) await writeShim(join(binDir, name), content);
-  return Object.keys(scripts);
+  return { names: Object.keys(scripts), unresolved };
 }
 
+export async function writeShims(binDir, pm, opts = {}) { return (await writeShimSet(binDir, pm, opts)).names; }
+
 /** Short pin text for prompts and decisions, e.g. "pnpm@10.4.1 (package.json packageManager), node 20 (.nvmrc)"; null when nothing is pinned. */
 export function summary(pins) {
   const parts = [...(pins?.pm ? [`${pins.pm.name}@${pins.pm.version} (${pins.pm.source})`] : []), ...(pins?.node ? [`node ${pins.node.spec} (${pins.node.source})`] : [])];
@@ -208,7 +251,7 @@ export function summary(pins) {
  *   env is null and shims empty without a usable pm pin; summary is null when nothing is pinned: the caller changes nothing.
  */
 export async function prepareToolchain({ dir, binDir, override = null, read, basePath = process.env.PATH ?? "",
-  writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }), find = which, hostNode = () => hostNodeVersion(basePath) } = {}) {
+  writeShim = writeShimFile, mkdirp = (d) => mkdir(d, { recursive: true }), find = which, resolveBins = resolvePinnedBins, hostNode = () => hostNodeVersion(basePath) } = {}) {
   const pins = await detectPins(dir, { override, ...(read ? { read } : {}) });
   const out = { pins, env: null, shims: [], summary: null, warning: null, notes: [...pins.notes] };
   if (pins.node) {
@@ -219,7 +262,9 @@ export async function prepareToolchain({ dir, binDir, override = null, read, bas
   const pm = pins.pm;
   let effective = pins;
   if (pm && binDir) {
-    out.shims = await writeShims(binDir, pm, { path: basePath, find, writeShim, mkdirp });
+    const set = await writeShimSet(binDir, pm, { path: basePath, find, writeShim, mkdirp, resolveBins });
+    out.shims = set.names;
+    if (set.unresolved.length) out.notes.push(`Toolchain: could not resolve ${set.unresolved.join(", ")} for ${pm.name}@${pm.version} once; its shim launches through npx on every call`);
     if (out.shims.length) out.env = toolchainEnv(binDir, basePath);
     else { out.notes.push(`Toolchain: ${pm.name}@${pm.version} is pinned but neither corepack nor npx is on PATH; the host ${pm.name} is used`); effective = { ...pins, pm: null }; }
   }

package/bin/lean/toolchain.test.mjs

@@ -2,11 +2,12 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync, statSync } from "node:fs";
+import { writeFileSync, mkdirSync, chmodSync, existsSync, readFileSync, statSync, rmSync } from "node:fs";
 import { join, delimiter } from "node:path";
 import { execFileSync } from "node:child_process";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { detectPins, parsePackageManager, nodeSatisfies, nodeWarning, shimScripts, prepareToolchain, toolchainEnv, writeShims, summary } from "./toolchain.mjs";
+import { detectPins, parsePackageManager, nodeSatisfies, nodeWarning, shimScripts, prepareToolchain, toolchainEnv, writeShims, summary, resolvePinnedBins, which } from "./toolchain.mjs";
+import { writeHeavyShims } from "./heavy.mjs";
 
 const tmp = (p) => tmpDir(p);
 const repo = (files) => {
@@ -28,6 +29,8 @@ const fakeHost = ({ corepack = true } = {}) => {
   return d;
 };
 const sysPath = process.env.PATH ?? "";
+// Hosts whose node ships corepack next to npx (e.g. CI's Node 24) would take the corepack branch: npx-only lanes see npx alone.
+const npxOnly = (n, p, ex) => (n === "corepack" ? null : which(n, p, ex));
 
 describe("toolchain pins (#4163)", () => {
   it("parsePackageManager accepts pm@x.y.z (with a +sha suffix) and nothing else", () => {
@@ -96,7 +99,7 @@ describe("toolchain pins (#4163)", () => {
       assert.equal(execFileSync("sh", ["-c", "pnpm --version"], { env: { ...process.env, PATH: basePath } }).toString().trim(), "11.0.0", "the host pnpm is the wrong one");
       const d = repo({ "package.json": { name: "x", packageManager: "pnpm@10.4.1+sha512.ff" } });
       const binDir = join(tmp("tc-run-"), "toolchain", "bin");
-      const tc = await prepareToolchain({ dir: d, binDir, basePath, hostNode: () => "v20.0.0" });
+      const tc = await prepareToolchain({ dir: d, binDir, basePath, find: corepack ? which : npxOnly, hostNode: () => "v20.0.0" });
       assert.ok(tc.env && tc.env.PATH.startsWith(binDir + delimiter), "shim dir first on PATH");
       assert.equal(tc.summary, "pnpm@10.4.1 (package.json packageManager)");
       const env = { ...process.env, ...tc.env };
@@ -151,4 +154,118 @@ describe("toolchain pins (#4163)", () => {
     assert.equal(summary({ pm: null, node: null }), null);
     assert.equal(nodeWarning({ spec: "1", source: ".nvmrc" }) !== null, true, "defaults to process.version");
   });
+
+  /**
+   * A host with only npx (no corepack) whose fake npx emulates the npx cache: `-y -p <pkg>@<v> -c 'command -v <bin>'`
+   * installs `<cache>/<pkg>@<v>/node_modules/<pkg>` (package.json version `installed`, default the requested one) with
+   * executable `.bin/<bin>` files printing that version, and prints the bin path; `-y [-p <pkg>@<v>] <bin|pkg@v> args`
+   * runs the bin. Every call is logged to `<host>/npx.log`. `fail` makes resolution exit 1.
+   */
+  const npxHost = ({ installed = null, fail = false } = {}) => {
+    const d = tmp("tc-npx-");
+    exe(d, "npx", [
+      `echo "$*" >> '${join(d, "npx.log")}'`,
+      'shift',
+      'if [ "$1" = "-p" ]; then spec="$2"; shift 2; else spec="$1"; shift; set -- "${spec%@*}" "$@"; fi',
+      'name="${spec%@*}"; ver="${spec##*@}"',
+      installed ? `iv='${installed}'` : 'iv="$ver"',
+      `root='${join(d, "cache")}'/"$spec"/node_modules`,
+      'mkdir -p "$root/$name" "$root/.bin"',
+      'printf \'{"name":"%s","version":"%s"}\' "$name" "$iv" > "$root/$name/package.json"',
+      'for b in pnpm yarn npm npx; do printf \'#!/bin/sh\\necho %s\\n\' "$iv" > "$root/.bin/$b"; chmod 755 "$root/.bin/$b"; done',
+      `if [ "$1" = "-c" ]; then ${fail ? "exit 1" : 'echo "$root/.bin/${2#command -v }"; exit 0'}; fi`,
+      'b="$1"; shift; exec "$root/.bin/$b" "$@"',
+    ].join("\n"));
+    return d;
+  };
+  const npxCalls = (host) => (existsSync(join(host, "npx.log")) ? readFileSync(join(host, "npx.log"), "utf8").trim().split("\n").filter(Boolean) : []);
+  const pinRepo = (pm) => repo({ "package.json": { name: "x", packageManager: pm } });
+  const shimRun = (tc, cmd) => execFileSync("sh", ["-c", cmd], { env: { ...process.env, ...tc.env } }).toString().trim();
+
+  it("#4348: a pnpm pin is resolved once at lane setup; the shim execs that binary with no npx call", async () => {
+    const host = npxHost();
+    const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+    const tc = await prepareToolchain({ dir: pinRepo("pnpm@10.4.1"), binDir, basePath: `${host}${delimiter}${sysPath}`, find: npxOnly, hostNode: () => "v20.0.0" });
+    assert.deepEqual(tc.shims, ["pnpm", "pnpx"]);
+    assert.deepEqual(tc.notes, []);
+    assert.equal(npxCalls(host).length, 1, "one resolution call");
+    assert.match(npxCalls(host)[0], /^-y -p pnpm@10\.4\.1 -c command -v pnpm$/);
+    const shim = readFileSync(join(binDir, "pnpm"), "utf8");
+    assert.match(shim, /if \[ -x '[^']*pnpm@10\.4\.1\/node_modules\/\.bin\/pnpm' \]; then exec '[^']*\/\.bin\/pnpm' "\$@"; fi\nexec '[^']*npx' -y -p 'pnpm@10\.4\.1' pnpm "\$@"/);
+    assert.match(readFileSync(join(binDir, "pnpx"), "utf8"), /then exec '[^']*\/\.bin\/pnpm' dlx "\$@"; fi/);
+    for (let i = 0; i < 3; i++) assert.equal(shimRun(tc, "pnpm --version"), "10.4.1");
+    assert.equal(npxCalls(host).length, 1, "shim calls never go through npx");
+  });
+
+  it("#4348: resolution failure keeps today's npx shim and the pinned version", async () => {
+    const host = npxHost({ fail: true });
+    const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+    const tc = await prepareToolchain({ dir: pinRepo("pnpm@10.4.1"), binDir, basePath: `${host}${delimiter}${sysPath}`, find: npxOnly, hostNode: () => "v20.0.0" });
+    const npx = join(host, "npx");
+    assert.deepEqual(readFileSync(join(binDir, "pnpm"), "utf8"), shimScripts({ name: "pnpm", version: "10.4.1" }, { npx }).pnpm, "byte-identical to the unresolved form");
+    assert.match(tc.notes.join("\n"), /could not resolve pnpm for pnpm@10\.4\.1 once; its shim launches through npx/);
+    assert.equal(shimRun(tc, "pnpm --version"), "10.4.1");
+    // a launcher that does not exist fails fast and leaves the same fallback
+    assert.deepEqual(resolvePinnedBins({ name: "pnpm", version: "10.4.1" }, { npx: join(host, "missing-npx") }), {});
+  });
+
+  it("#4348: a cached binary of another version is never used", async () => {
+    const host = npxHost({ installed: "10.0.0" });
+    assert.deepEqual(resolvePinnedBins({ name: "pnpm", version: "10.4.1" }, { npx: join(host, "npx"), path: `${host}${delimiter}${sysPath}` }), {});
+    const run = () => "/abs/.bin/pnpm\n";
+    assert.deepEqual(resolvePinnedBins({ name: "pnpm", version: "10.4.1" }, { npx: "/h/npx", run }), {}, "a path without a matching package.json is rejected");
+    assert.deepEqual(resolvePinnedBins({ name: "pnpm", version: "10.4.1" }, { npx: "/h/npx", run: () => "relative/pnpm" }), {});
+  });
+
+  it("#4348: a resolved binary removed mid-lane falls back to npx", async () => {
+    const host = npxHost();
+    const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+    const tc = await prepareToolchain({ dir: pinRepo("pnpm@10.4.1"), binDir, basePath: `${host}${delimiter}${sysPath}`, find: npxOnly, hostNode: () => "v20.0.0" });
+    const real = /then exec '([^']+)'/.exec(readFileSync(join(binDir, "pnpm"), "utf8"))[1];
+    rmSync(real);
+    assert.equal(shimRun(tc, "pnpm --version"), "10.4.1");
+    assert.equal(npxCalls(host).length, 2, "the fallback went through npx");
+  });
+
+  for (const [pin, bins, pkg] of [["yarn@4.1.0", ["yarn"], "@yarnpkg/cli-dist@4.1.0"], ["yarn@1.22.19", ["yarn"], "yarn@1.22.19"], ["npm@10.2.0", ["npm", "npx"], "npm@10.2.0"]]) {
+    it(`#4348: ${pin} resolves ${bins.join(" and ")} from ${pkg}`, async () => {
+      const host = npxHost();
+      const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+      const tc = await prepareToolchain({ dir: pinRepo(pin), binDir, basePath: `${host}${delimiter}${sysPath}`, find: npxOnly, hostNode: () => "v20.0.0" });
+      assert.deepEqual(tc.shims, bins);
+      assert.deepEqual(tc.notes, []);
+      assert.deepEqual(npxCalls(host), bins.map((b) => `-y -p ${pkg} -c command -v ${b}`));
+      const ver = pin.split("@")[1];
+      for (const b of bins) {
+        assert.match(readFileSync(join(binDir, b), "utf8"), new RegExp(`then exec '[^']*/node_modules/\\.bin/${b}' "\\$@"; fi\\n`));
+        assert.equal(shimRun(tc, `${b} --version`), ver);
+      }
+      assert.equal(npxCalls(host).length, bins.length, "no npx call per shim invocation");
+    });
+  }
+
+  it("#4348: an npm pin is resolved even when corepack is on the host (its shims always launch through npx)", async () => {
+    const host = npxHost();
+    const binDir = join(tmp("tc-run-"), "toolchain", "bin");
+    const find = (n, p, ex) => (n === "corepack" ? "/h/corepack" : which(n, p, ex));
+    const tc = await prepareToolchain({ dir: pinRepo("npm@10.2.0"), binDir, basePath: `${host}${delimiter}${sysPath}`, find, hostNode: () => "v20.0.0" });
+    assert.deepEqual(npxCalls(host), ["-y -p npm@10.2.0 -c command -v npm", "-y -p npm@10.2.0 -c command -v npx"]);
+    assert.match(readFileSync(join(binDir, "npm"), "utf8"), /then exec '[^']*\/node_modules\/\.bin\/npm' "\$@"; fi\n/);
+    assert.equal(shimRun(tc, "npm --version"), "10.2.0");
+    assert.equal(npxCalls(host).length, 2, "no npx call per shim invocation");
+  });
+
+  it("#4348: corepack hosts are not resolved; the heavy shim still wraps the toolchain shim", async () => {
+    let calls = 0;
+    const resolveBins = () => { calls++; return {}; };
+    const cp = await prepareToolchain({ dir: pinRepo("pnpm@10.4.1"), binDir: join(tmp("tc-run-"), "bin"), basePath: fakeHost(), resolveBins, hostNode: () => "v20.0.0" });
+    assert.equal(calls, 0);
+    assert.deepEqual(cp.notes, []);
+    const host = npxHost();
+    const root = tmp("tc-run-"), binDir = join(root, "toolchain", "bin"), heavyBin = join(root, "heavy", "bin");
+    const tc = await prepareToolchain({ dir: pinRepo("pnpm@10.4.1"), binDir, basePath: `${host}${delimiter}${sysPath}`, find: npxOnly, hostNode: () => "v20.0.0" });
+    const names = await writeHeavyShims(heavyBin, { path: tc.env.PATH });
+    assert.ok(names.includes("pnpm"));
+    assert.match(readFileSync(join(heavyBin, "pnpm"), "utf8"), new RegExp(`run --name 'pnpm' -- '${join(binDir, "pnpm")}' "\\$@"`));
+  });
 });