@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

package/src/cli-replacement/automatic-upgrades.test.ts

@@ -8,11 +8,18 @@
  * @superblocksteam/library pin matches the target version.
  */
 
+import { EventEmitter } from "node:events";
 import fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 
 import { describe, it, expect, beforeEach, vi } from "vitest";
 
-import { checkVersionsAndWritePackageJson } from "./automatic-upgrades.js";
+import {
+  buildGlobalInstallArgs,
+  buildInstallEnv,
+  checkVersionsAndWritePackageJson,
+} from "./automatic-upgrades.js";
 
 // ---------------------------------------------------------------------------
 // Mocks
@@ -27,6 +34,10 @@ vi.mock("node:fs/promises", () => ({
 
 vi.mock("node:child_process", () => ({
   exec: vi.fn(),
+  // `execFile` is exported so `promisify(execFile)` in npm-registry.ts (loaded
+  // transitively via `@superblocksteam/vite-plugin-file-sync/npm-error-parser`)
+  // doesn't crash at module load. This test never invokes it.
+  execFile: vi.fn(),
 }));
 
 const upgradeWithPackageManagerCalls: unknown[] = [];
@@ -50,13 +61,28 @@ vi.mock("./version-detection.js", () => ({
   clearCliVersionCache: vi.fn(),
 }));
 
+// `vi.mock` calls are hoisted to the top of the module, so any factory must
+// either declare its mocks inline OR use `vi.hoisted()` to hoist the mock
+// fns alongside the mock registration. The latter lets us reuse the mocks
+// inside test bodies (e.g. `.mockReturnValue(...)`).
+const { stripUpgradedCliLockfilesMock, loggerMock } = vi.hoisted(() => {
+  return {
+    stripUpgradedCliLockfilesMock: vi.fn(async () => ({})),
+    loggerMock: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+  };
+});
+
+vi.mock("./post-upgrade-lockfile-strip.mjs", () => ({
+  stripUpgradedCliLockfiles: stripUpgradedCliLockfilesMock,
+}));
+
 vi.mock("../telemetry/logging.js", () => ({
-  getLogger: () => ({
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    debug: vi.fn(),
-  }),
+  getLogger: () => loggerMock,
   getErrorMeta: vi.fn(() => ({})),
 }));
 
@@ -66,8 +92,18 @@ vi.mock("../telemetry/index.js", () => ({
   }),
 }));
 
-vi.mock("@superblocksteam/shared", async () => {
+// Use `importOriginal` so transitive consumers of `@superblocksteam/shared`
+// (e.g. `@superblocksteam/telemetry`'s policy module pulled in by the
+// `bucketNpmRegistryHost` import added in this file's source under test for
+// APPS-4381) see every real export (`DeploymentTypeEnum`, etc.), while still
+// letting the test override the two symbols `automatic-upgrades.ts` itself
+// consumes. The factory return type is `any` because `NON_SB_ORG_UPDATE_ERROR`
+// is a string-literal type in the real module that our test override can't
+// satisfy structurally; `vi.mock`'s value-level behaviour is unaffected.
+vi.mock("@superblocksteam/shared", async (importOriginal) => {
+  const actual = (await importOriginal()) as Record<string, unknown>;
   return {
+    ...actual,
     NON_SB_ORG_UPDATE_ERROR: "non_sb_org_update_error",
     // traceFunction in tests is a passthrough — we just want the fn to run.
     traceFunction: async ({ fn }: { fn: () => Promise<unknown> }) => {
@@ -102,6 +138,8 @@ const mockConfig: Parameters<typeof checkVersionsAndWritePackageJson>[1] = {
 beforeEach(() => {
   vi.clearAllMocks();
   upgradeWithPackageManagerCalls.length = 0;
+  // Restore default mock return values after `clearAllMocks` resets them.
+  stripUpgradedCliLockfilesMock.mockImplementation(async () => ({}));
 
   // Mock global fetch used by getRemoteVersions
   global.fetch = vi.fn(async () => ({
@@ -340,6 +378,398 @@ describe("checkVersionsAndWritePackageJson", () => {
       );
     });
 
+    // -----------------------------------------------------------------
+    // APPS-4324: classifyNpmExecStderr wiring for `upgradeCliWithPackageManager`
+    //
+    // The CLI auto-upgrade pod's npm fallback exec used to surface a
+    // perimeter-block (air-gapped customer with public-npm egress denied)
+    // as a generic `"Failed to upgrade packages"` log, leaving the operator
+    // no signal as to whether the cause was a transient registry blip, a
+    // bad auth token, or a missing package. These tests pin the structured
+    // log emitted just before the upgrade promise rejects.
+    //
+    // Note on flow: `checkVersionsAndWritePackageJson` returns the upgrade
+    // promise to its caller (`dev.mts` joins it via `Promise.all` against
+    // the local install). The rejection is therefore observed by awaiting
+    // `result.upgradePromises[0]`, not by the outer try/catch inside this
+    // function (which only catches sync errors during the package.json
+    // read/write block).
+    // -----------------------------------------------------------------
+
+    /** Build a fake ChildProcess that emits the supplied stderr (once,
+     * asynchronously so the caller has time to register `.on("data")`),
+     * then fires the exec callback with `cbError`. Passing an array emits
+     * one `data` event per element — exercise the stderr-buffer accumulation
+     * path against split chunks (real npm output arrives multi-chunk).
+     *
+     * Pass `{ skipEmit: true, errorStderr: "..." }` to model the fast-fail
+     * race the Bugbot finding flagged: the subprocess exits before our
+     * `cp.stderr.on('data', …)` listener attaches, so `stderrBuffer` is
+     * empty and only `error.stderr` (which the exec wrapper aggregates
+     * internally) carries the npm output. The classifier must fall back to
+     * that — otherwise the structured `[npm-install-blocked]` line goes
+     * missing on exactly the failure mode this PR exists to diagnose. */
+    async function mockNpmFallbackExec(
+      stderr: string | string[],
+      cbError: Error,
+      opts: { skipEmit?: boolean; errorStderr?: string } = {},
+    ) {
+      const stdout = new EventEmitter();
+      const stderrEmitter = new EventEmitter();
+      const chunks = Array.isArray(stderr) ? stderr : [stderr];
+      // The exec call we care about is the third positional invocation
+      // (after `which superblocks` for upgradeCliWithOclif and the oclif
+      // `update` subprocess). Make `which` succeed (returns a path) and
+      // `superblocks update` return "not updatable" so the package-manager
+      // fallback path runs.
+      const { exec } = await import("node:child_process");
+      const execMock = vi.mocked(exec);
+      execMock.mockImplementation(((
+        cmd: string,
+        ...rest: unknown[]
+      ): unknown => {
+        const cb = (
+          typeof rest[rest.length - 1] === "function"
+            ? rest[rest.length - 1]
+            : undefined
+        ) as ((err: Error | null, result?: unknown) => void) | undefined;
+        // Promisified consumers (upgradeCliWithOclif) destructure `{stdout,
+        // stderr}` from the awaited result. Real Node has a
+        // `util.promisify.custom` symbol that produces that shape; our vi.fn
+        // mock doesn't, so we pass the destructured object as the callback's
+        // single value-arg (default promisify behaviour resolves to that).
+        if (cmd === "which superblocks" || cmd === "where superblocks") {
+          cb?.(null, { stdout: "/usr/local/bin/superblocks\n", stderr: "" });
+          return {};
+        }
+        if (cmd.includes("superblocks update")) {
+          // Make oclif report "not updatable" so the fallback fires.
+          cb?.(null, { stdout: "this version is not updatable\n", stderr: "" });
+          return {};
+        }
+        // The npm install fallback uses the callback-style API directly (not
+        // promisified), so the callback signature is just (error). Schedule
+        // the stderr emit + callback so the caller has time to register
+        // listeners on cp.stdout/cp.stderr.
+        const errArg: Error & { stderr?: string } = cbError;
+        if (opts.errorStderr !== undefined) errArg.stderr = opts.errorStderr;
+        queueMicrotask(() => {
+          if (!opts.skipEmit) {
+            for (const chunk of chunks) {
+              if (chunk) stderrEmitter.emit("data", chunk);
+            }
+          }
+          cb?.(errArg);
+        });
+        return { stdout, stderr: stderrEmitter };
+      }) as unknown as Parameters<typeof execMock.mockImplementation>[0]);
+    }
+
+    async function runAndAwaitUpgrade() {
+      const result = await checkVersionsAndWritePackageJson(
+        mockLockService,
+        mockConfig,
+        false,
+        false,
+      );
+      // The CLI upgrade promise was pushed to upgradePromises and is the
+      // promise that rejects when the npm fallback fails. The caller in
+      // dev.mts joins it via Promise.all; here we await it directly so the
+      // test can assert on rejection + log shape.
+      await Promise.all(result.upgradePromises);
+    }
+
+    it("APPS-4324: logs NpmInstallBlocked with reason=registry_unreachable on ECONNREFUSED stderr", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code ECONNREFUSED",
+          "npm error errno ECONNREFUSED",
+          "npm error network request to https://registry.npmjs.org/@superblocksteam%2fcli failed, reason: connect ECONNREFUSED 127.0.0.1:443",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      // The structured log line fires before the rejection so the operator
+      // sees the reason code in the crash-loop output. Reason is encoded
+      // into the message body — no meta arg is passed, because the
+      // `NpmInstallBlocked` instance's `Error.message` carries the raw
+      // registry host (APPS-4381 round-2 review).
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /\[npm-install-blocked\] reason=registry_unreachable/,
+        ),
+      );
+
+      // Pin the relative ordering: the structured `[npm-install-blocked]`
+      // line MUST precede the legacy `Failed to upgrade packages` line so a
+      // downstream sink that truncates after the first error still surfaces
+      // the reason code (see the comment in automatic-upgrades.ts beside the
+      // blocked-log emit).
+      const blockedIdx = loggerMock.error.mock.calls.findIndex(
+        (c) =>
+          typeof c[0] === "string" && c[0].includes("[npm-install-blocked]"),
+      );
+      const failedIdx = loggerMock.error.mock.calls.findIndex(
+        (c) => typeof c[0] === "string" && c[0].includes("Failed to upgrade"),
+      );
+      expect(blockedIdx).toBeGreaterThanOrEqual(0);
+      expect(failedIdx).toBeGreaterThan(blockedIdx);
+    });
+
+    it("APPS-4324: logs reason=registry_auth_failed on E401 stderr", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code E401",
+          "npm error 401 Unauthorized - GET https://npm.private.example.com/@superblocksteam%2fcli",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /\[npm-install-blocked\] reason=registry_auth_failed/,
+        ),
+      );
+    });
+
+    it("APPS-4381: buckets a private registry host so the structured registryHost facet is `private`, not the raw hostname", async () => {
+      // Regression for review feedback on PR #19634: the structured
+      // auto-upgrade log used to emit `registryHost=${blocked.registryHost ?? "unknown"}`
+      // verbatim. That made the customer's private registry hostname a
+      // structured log facet — unbounded cardinality in shared operational
+      // log indexes and a leak of customer infra identifiers across the
+      // `registryHost` dimension. The fix passes the value through
+      // `bucketNpmRegistryHost` (the same helper PR #19622 wired for llmobs
+      // tags) so this field emits a bounded enum (`public_npm` | `private`
+      // | `unknown`).
+      //
+      // Scope note: the `summary=...` free-text field is also redacted of
+      // URLs / bare hostnames before logging (round-2 review feedback on
+      // PR #19634) — see the `does not appear anywhere` regression test
+      // below. The structured-facet bucketing pinned here is the
+      // `registryHost=` field only.
+      const privateHost = "customer.jfrog.io";
+      await mockNpmFallbackExec(
+        [
+          "npm error code E401",
+          `npm error 401 Unauthorized - GET https://${privateHost}/@superblocksteam%2fcli`,
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      const blockedCall = loggerMock.error.mock.calls.find(
+        (c) =>
+          typeof c[0] === "string" && c[0].includes("[npm-install-blocked]"),
+      );
+      expect(blockedCall).toBeDefined();
+      const message = blockedCall![0] as string;
+      // The structured `registryHost=` facet is bucketed to `private`...
+      expect(message).toMatch(/registryHost=private(\s|$)/);
+      // ...and the raw hostname does NOT appear as the facet value (would
+      // regress if a future refactor reverted the bucketing call).
+      expect(message).not.toMatch(
+        new RegExp(`registryHost=${privateHost.replace(/\./g, "\\.")}`),
+      );
+    });
+
+    it("APPS-4381: buckets registry.npmjs.org as public_npm", async () => {
+      // Pin the other side of the bucket so a future refactor that breaks
+      // the public-vs-private split also breaks this test.
+      await mockNpmFallbackExec(
+        [
+          "npm error code ECONNREFUSED",
+          "npm error network request to https://registry.npmjs.org/@superblocksteam%2fcli failed",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      const blockedCall = loggerMock.error.mock.calls.find(
+        (c) =>
+          typeof c[0] === "string" && c[0].includes("[npm-install-blocked]"),
+      );
+      expect(blockedCall).toBeDefined();
+      expect(blockedCall![0] as string).toMatch(
+        /registryHost=public_npm(\s|$)/,
+      );
+    });
+
+    it("APPS-4381: a private registry host does not appear anywhere in the emitted [npm-install-blocked] log call (round-2 review feedback)", async () => {
+      // George's round-2 feedback on PR #19634: the `registryHost=` facet is
+      // bucketed, but `summary=${JSON.stringify(blocked.summary)}` still
+      // echoed the raw URL/host from the npm stderr line. The meta arg
+      // (`getErrorMeta(blocked)`) was a second leak channel because
+      // `NpmInstallBlocked.message` is `"... against ${host} [code]"` —
+      // `getErrorMeta` synthesizes meta from that message + the stack that
+      // embeds it.
+      //
+      // This test uses a unique sentinel host that no other fixture in this
+      // file references, then asserts the host substring does not appear in
+      // ANY argument of the structured logger call — message body, any meta
+      // arg, any stack — anywhere. This is the "private host does not
+      // appear anywhere in the emitted auto-upgrade log line" regression
+      // George asked for.
+      //
+      // Mock-faithfulness note: this test does NOT rely on the
+      // `getErrorMeta` mock returning a realistic shape; the fix omits the
+      // meta arg entirely at the `[npm-install-blocked]` call site, so a
+      // `() => ({})` stub would no longer mask a regression of the meta
+      // path. To guard a future refactor that re-adds a meta arg with the
+      // raw `NpmInstallBlocked`, we assert the call has exactly one arg
+      // below.
+      const privateHost = "registry-leak-sentinel.acme-corp.internal";
+      await mockNpmFallbackExec(
+        [
+          "npm error code E401",
+          `npm error 401 Unauthorized - GET https://${privateHost}:4873/@superblocksteam%2fcli`,
+          `npm error request to https://${privateHost}/foo failed, reason: getaddrinfo ENOTFOUND ${privateHost}`,
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      const blockedCall = loggerMock.error.mock.calls.find(
+        (c) =>
+          typeof c[0] === "string" && c[0].includes("[npm-install-blocked]"),
+      );
+      expect(blockedCall).toBeDefined();
+
+      // Stringify the entire call tuple so we catch the host whether it
+      // leaks through the message body, a (future) meta arg's
+      // `error.message`, a stack, or any other field a future refactor
+      // might add. `acme-corp.internal` is checked separately so a
+      // host-only redaction (one token) that left the suffix would also
+      // trip the test.
+      const serialized = JSON.stringify(blockedCall);
+      expect(serialized).not.toContain(privateHost);
+      expect(serialized).not.toContain("acme-corp.internal");
+
+      // No meta arg today; pin that so any future code that re-introduces
+      // `getErrorMeta(blocked)` (or any other host-bearing payload) is
+      // forced through this regression test.
+      expect(blockedCall!.length).toBe(1);
+
+      // Spot-check that the bucket tokens replaced the host (the diagnostic
+      // shape of the npm phrasing is preserved even after redaction).
+      const message = blockedCall![0] as string;
+      expect(message).toMatch(/summary=/);
+      expect(message).toContain("<private>");
+    });
+
+    it("APPS-4324: logs reason=not_in_registry on E404 stderr", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code E404",
+          "npm error 404 Not Found - GET https://npm.private.example.com/@superblocksteam%2fcli - Not found",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringMatching(/\[npm-install-blocked\] reason=not_in_registry/),
+      );
+    });
+
+    it("APPS-4324: falls through to the existing generic error path for ERESOLVE (no false-positive)", async () => {
+      await mockNpmFallbackExec(
+        [
+          "npm error code ERESOLVE",
+          "npm error ERESOLVE unable to resolve dependency tree",
+        ].join("\n"),
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      // The classifier returns null for ERESOLVE — no structured log fires.
+      expect(loggerMock.error).not.toHaveBeenCalledWith(
+        expect.stringContaining("[npm-install-blocked]"),
+      );
+      // The existing generic per-failure log still fires so the operator
+      // still sees something in the crash-loop output.
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to upgrade packages"),
+      );
+    });
+
+    it("APPS-4324: falls back to error.stderr when stderrBuffer is empty (fast-fail race)", async () => {
+      // Bugbot finding on the APPS-4324 branch: a subprocess that fails fast
+      // can emit and exit before our `cp.stderr.on('data', …)` listener
+      // attaches, leaving `stderrBuffer` empty. The exec wrapper still
+      // aggregates the output onto `error.stderr`, so the classifier must
+      // read that as the fallback or the structured diagnostic this PR
+      // exists to guarantee goes missing exactly when it's needed most.
+      const errWithStderr: Error & { stderr?: string } = new Error(
+        "Command failed: pnpm install ...",
+      );
+      await mockNpmFallbackExec("", errWithStderr, {
+        skipEmit: true,
+        errorStderr: [
+          "npm error code ECONNREFUSED",
+          "npm error network request to https://registry.npmjs.org/foo failed",
+        ].join("\n"),
+      });
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /\[npm-install-blocked\] reason=registry_unreachable/,
+        ),
+      );
+    });
+
+    it("APPS-4324: accumulates stderr across multiple chunks before classifying", async () => {
+      // Real `cp.stderr` emits multiple `data` events; the OS pipe buffer
+      // can split the npm output mid-line. Emit two chunks that bisect the
+      // `npm error code ECONNREFUSED` line so the classifier only succeeds
+      // if `automatic-upgrades.ts` concatenates the buffer instead of
+      // matching per-chunk.
+      await mockNpmFallbackExec(
+        [
+          "npm error code ECONNR",
+          "EFUSED\nnpm error network request to https://registry.npmjs.org/foo failed",
+        ],
+        new Error("Command failed: pnpm install ..."),
+      );
+
+      await expect(runAndAwaitUpgrade()).rejects.toThrow(
+        /Command failed: pnpm install/,
+      );
+
+      expect(loggerMock.error).toHaveBeenCalledWith(
+        expect.stringMatching(
+          /\[npm-install-blocked\] reason=registry_unreachable/,
+        ),
+      );
+    });
+
     it("leaves sdk-api alone when the server response omits sdkApi (older deployment)", async () => {
       global.fetch = vi.fn(async () => ({
         ok: true,
@@ -376,4 +806,96 @@ describe("checkVersionsAndWritePackageJson", () => {
       );
     });
   });
+
+  // -----------------------------------------------------------------------
+  // Argv + env plumbing for the CLI auto-upgrade.
+  //
+  // Userconfig pinning lives in the spawned subprocess env
+  // (`NPM_CONFIG_USERCONFIG`) rather than a CLI flag. `--userconfig=…`
+  // is npm-only — pnpm rejects it (pnpm/pnpm#6036). The env var route
+  // works for both via @pnpm/npm-conf's userconfig recognition.
+  //
+  // Build path is exercised against the pure-function helpers so the
+  // assertions don't have to drive the exec subprocess machinery.
+  // -----------------------------------------------------------------------
+
+  describe("buildGlobalInstallArgs", () => {
+    const PACKAGE_NAME = "@superblocksteam/cli@2.1.0";
+
+    it("returns the npm baseline argv (no --userconfig)", () => {
+      const args = buildGlobalInstallArgs({ agent: "npm" }, PACKAGE_NAME);
+
+      expect(args).toContain("--fund=false");
+      expect(args).toContain("--save-exact");
+      expect(args).toContain("--audit=false");
+      expect(args).toContain("--force");
+      expect(args).toContain(PACKAGE_NAME);
+      // Userconfig is plumbed via env, not flag (pnpm/pnpm#6036).
+      expect(args.some((a) => a.startsWith("--userconfig="))).toBe(false);
+    });
+
+    it("returns the pnpm baseline argv (drops npm-only --audit=false, no --userconfig)", () => {
+      const args = buildGlobalInstallArgs({ agent: "pnpm" }, PACKAGE_NAME);
+
+      expect(args).toContain("--fund=false");
+      expect(args).toContain("--save-exact");
+      expect(args).not.toContain("--audit=false");
+      expect(args).toContain("--force");
+      expect(args).toContain(PACKAGE_NAME);
+      // Same: pnpm rejects --userconfig (pnpm/pnpm#6036), so the env
+      // var route is the only mechanism.
+      expect(args.some((a) => a.startsWith("--userconfig="))).toBe(false);
+    });
+  });
+
+  describe("buildInstallEnv", () => {
+    const USERCONFIG_PATH = path.join(os.homedir(), ".superblocks", "npmrc");
+
+    it("sets NPM_CONFIG_USERCONFIG (npm + pnpm <= 10)", () => {
+      const env = buildInstallEnv(USERCONFIG_PATH);
+
+      expect(env.NPM_CONFIG_USERCONFIG).toBe(USERCONFIG_PATH);
+    });
+
+    it("sets PNPM_CONFIG_USERCONFIG (pnpm 11+)", () => {
+      // pnpm 11 stopped honouring `NPM_CONFIG_USERCONFIG`. Both env
+      // vars must be set so a single overlay works across npm, pnpm
+      // <= 10, and pnpm 11+. See `userconfig-env.integration.test.mts`
+      // for the regression guard against the pnpm 11 contract change.
+      const env = buildInstallEnv(USERCONFIG_PATH);
+
+      expect(env.PNPM_CONFIG_USERCONFIG).toBe(USERCONFIG_PATH);
+    });
+
+    it("accepts a custom base env (for callers scrubbing inherited config)", () => {
+      // The base-env override lets callers pre-scrub `npm_config_*`
+      // inherited from a parent pnpm/npm process, then layer the
+      // userconfig pin on top. `logsDir` (2nd arg) is omitted here.
+      const env = buildInstallEnv(USERCONFIG_PATH, undefined, {
+        PATH: "/custom/path",
+        HOME: "/custom/home",
+      });
+
+      expect(env.PATH).toBe("/custom/path");
+      expect(env.HOME).toBe("/custom/home");
+      expect(env.NPM_CONFIG_USERCONFIG).toBe(USERCONFIG_PATH);
+      expect(env.PNPM_CONFIG_USERCONFIG).toBe(USERCONFIG_PATH);
+    });
+
+    it("routes npm's debug log via NPM_CONFIG_LOGS_DIR when a logs dir is given", () => {
+      // The live-edit pod points npm's `logs-dir` at
+      // `<app>/.superblocks/logs` so a failed install leaves a collectable
+      // debug log in a predictable place.
+      const logsDir = path.join("/srv/app", ".superblocks", "logs");
+      const env = buildInstallEnv(USERCONFIG_PATH, logsDir, {});
+
+      expect(env.NPM_CONFIG_LOGS_DIR).toBe(logsDir);
+    });
+
+    it("omits NPM_CONFIG_LOGS_DIR when no logs dir is given (keeps npm's default _logs)", () => {
+      const env = buildInstallEnv(USERCONFIG_PATH, undefined, {});
+
+      expect(env.NPM_CONFIG_LOGS_DIR).toBeUndefined();
+    });
+  });
 });