@superblocksteam/sdk 2.0.123 → 2.0.124-next.1

package/src/cli-replacement/home-npmrc.test.mts

@@ -0,0 +1,757 @@
+/**
+ * Tests for the CLI-startup `~/.superblocks/npmrc` writer.
+ *
+ * Strategy: stand up a tmpdir as a fake `$HOME` and a fake
+ * `NpmRegistryClient` whose `getConfig()` returns the canned response
+ * under test. Asserts cover the four state transitions plus the 0o400
+ * mode bit.
+ */
+
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import * as npmRegistry from "@superblocksteam/vite-plugin-file-sync/npm-registry";
+import type {
+  NpmRegistryClient,
+  NpmRegistryFetchResult,
+} from "@superblocksteam/vite-plugin-file-sync/npm-registry";
+
+// Wrap the real npm-registry module but make `snapshotInitialNpmrc` a spy
+// that delegates to the genuine implementation by default. Only the
+// APPS-4428 failure test overrides it (to simulate a silent EXDEV-class
+// snapshot failure) so the userconfig-preservation guard can be exercised
+// without crossing filesystems; every other test keeps the real
+// hardlink-backed snapshot behaviour.
+vi.mock("@superblocksteam/vite-plugin-file-sync/npm-registry", async () => {
+  const actual = await vi.importActual<typeof npmRegistry>(
+    "@superblocksteam/vite-plugin-file-sync/npm-registry",
+  );
+  return {
+    ...actual,
+    snapshotInitialNpmrc: vi.fn(actual.snapshotInitialNpmrc),
+  };
+});
+
+import type { Logger } from "../telemetry/logging.js";
+import {
+  HOME_NPMRC_MODE,
+  superblocksLogsPath,
+  superblocksNpmrcBackupPath,
+  superblocksNpmrcPath,
+  syncHomeNpmrc,
+} from "./home-npmrc.mjs";
+
+/** Typed handle to the mocked snapshot fn (delegates to the real impl by
+ * default; overridden only in the failure test). */
+const snapshotInitialNpmrcMock = vi.mocked(npmRegistry.snapshotInitialNpmrc);
+
+/** Resolves the userconfig path under the test's tmpdir `homeDir`. Keeps
+ * the test free of an inline literal so a future relocation only touches
+ * `superblocksNpmrcPath`. */
+function npmrcPath(homeDir: string): string {
+  return superblocksNpmrcPath(homeDir);
+}
+
+type LoggerMock = {
+  info: ReturnType<typeof vi.fn>;
+  warn: ReturnType<typeof vi.fn>;
+  error: ReturnType<typeof vi.fn>;
+  debug: ReturnType<typeof vi.fn>;
+};
+
+function makeLogger(): LoggerMock {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+}
+
+function asLogger(mock: LoggerMock): Logger {
+  return mock as unknown as Logger;
+}
+
+/**
+ * Minimal stub that satisfies the `NpmRegistryClient` shape
+ * `syncHomeNpmrc` actually exercises (only `getConfig`). Casting through
+ * `as unknown as NpmRegistryClient` keeps the wider class surface from
+ * forcing test churn.
+ */
+function makeClient(impl: () => Promise<NpmRegistryFetchResult>): {
+  client: NpmRegistryClient;
+  getConfig: ReturnType<typeof vi.fn>;
+} {
+  const getConfig = vi.fn(impl);
+  const client = {
+    getConfig,
+  } as unknown as NpmRegistryClient;
+  return { client, getConfig };
+}
+
+const CONFIGURED: NpmRegistryFetchResult = {
+  source: "configured",
+  config: {
+    configured: true,
+    default: {
+      url: "https://artifactory.example.com/api/npm/npm/",
+      token: "test-token-abc",
+    },
+  },
+};
+
+const STALE: NpmRegistryFetchResult = {
+  source: "stale",
+  config: {
+    configured: true,
+    default: {
+      url: "https://artifactory.example.com/api/npm/npm/",
+      token: "test-token-abc",
+    },
+  },
+};
+
+const NOT_CONFIGURED: NpmRegistryFetchResult = {
+  source: "not-configured",
+  config: { configured: false },
+};
+
+const UNREACHABLE: NpmRegistryFetchResult = {
+  source: "unreachable",
+  config: { configured: false },
+};
+
+describe("syncHomeNpmrc", () => {
+  let homeDir: string;
+
+  beforeEach(async () => {
+    homeDir = await mkdtemp(path.join(os.tmpdir(), "home-npmrc-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(homeDir, { recursive: true, force: true });
+    // `mockReset` (not `mockClear`) so the `mockImplementationOnce` queue
+    // is also drained. With `mockClear` a queued one-time impl from a
+    // test that never invoked the spy (e.g. an early throw) would leak
+    // into the next test and produce a hard-to-diagnose cascade failure.
+    // In vitest 4 `mockReset` restores the implementation passed to
+    // `vi.fn(impl)` — the real `snapshotInitialNpmrc` — so subsequent
+    // tests keep delegating to the genuine hardlink-backed snapshot.
+    snapshotInitialNpmrcMock.mockReset();
+  });
+
+  describe("configured → write", () => {
+    it("writes ~/.superblocks/npmrc with the registry config at mode 0o400", async () => {
+      const { client } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      expect(result.source).toBe("configured");
+      expect(result.path).toBe(npmrcPath(homeDir));
+
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain(
+        "registry=https://artifactory.example.com/api/npm/npm/",
+      );
+      expect(content).toContain(
+        "//artifactory.example.com/api/npm/npm/:_authToken=test-token-abc",
+      );
+
+      const stats = await stat(npmrcPath(homeDir));
+      // mask off the file-type bits; only mode matters.
+      expect(stats.mode & 0o777).toBe(HOME_NPMRC_MODE);
+    });
+
+    it("creates the ~/.superblocks parent dir when absent (local CLI cold start)", async () => {
+      // Pods have /home/node/.superblocks created at image build, but a
+      // developer running `superblocks dev` against a fresh $HOME may
+      // not. `syncHomeNpmrc` must `mkdir -p` before writing or the
+      // atomic-rename inside `writeNpmrc` fails ENOENT.
+      const { client } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+
+      await expect(
+        stat(path.join(homeDir, ".superblocks")),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      const dirStats = await stat(path.join(homeDir, ".superblocks"));
+      expect(dirStats.isDirectory()).toBe(true);
+      const fileStats = await stat(npmrcPath(homeDir));
+      expect(fileStats.mode & 0o777).toBe(HOME_NPMRC_MODE);
+    });
+
+    it("treats `stale` (last-known-good) the same as `configured`", async () => {
+      const { client } = makeClient(async () => STALE);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      expect(result.source).toBe("stale");
+      const stats = await stat(npmrcPath(homeDir));
+      expect(stats.mode & 0o777).toBe(HOME_NPMRC_MODE);
+    });
+
+    it("overwrites a 0o400 file from a previous sync", async () => {
+      // The whole point of the atomic-rename pattern is that the target
+      // file's mode does not block subsequent re-writes. Regression test
+      // for that claim — switching away from atomic rename would EACCES.
+      const { client } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      const second = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(second.outcome).toBe("written");
+      const stats = await stat(npmrcPath(homeDir));
+      expect(stats.mode & 0o777).toBe(HOME_NPMRC_MODE);
+    });
+
+    it("overwrites an image-baked default with the server config when set, but preserves the @superblocksteam scope and its auth", async () => {
+      // EE pods ship with `/home/node/.superblocks/npmrc` pre-populated
+      // with a GHPR scope mapping + token. When the runtime org
+      // configures its own private registry:
+      //   - The server-fetched default registry wins over any baked
+      //     default (none here, but the assertion pins that
+      //     `registry=…artifactory…` line lands).
+      //   - The baked `@superblocksteam:registry=…npm.pkg.github.com/`
+      //     scope mapping must SURVIVE (it's in `PRESERVE_NPMRC_SCOPES`
+      //     so `@superblocksteam/*` packages keep flowing through GHPR).
+      //   - And its matching `//npm.pkg.github.com/:_authToken=…` line
+      //     must survive with it — otherwise every `@superblocksteam/*`
+      //     install 401s against GHPR (APPS-4300). The earlier shape of
+      //     this test asserted the auth line was dropped, which was the
+      //     bug.
+      const baked =
+        "//npm.pkg.github.com/:_authToken=ghpr-baked\n" +
+        "@superblocksteam:registry=https://npm.pkg.github.com/\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), baked, { mode: 0o600 });
+
+      const { client } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain(
+        "registry=https://artifactory.example.com/api/npm/npm/",
+      );
+      expect(content).toContain(
+        "@superblocksteam:registry=https://npm.pkg.github.com/",
+      );
+      expect(content).toContain("//npm.pkg.github.com/:_authToken=ghpr-baked");
+    });
+  });
+
+  describe("not-configured → restore image-default (or remove if no backup)", () => {
+    it("restores the image-default userconfig from the backup captured on a prior configured boot (APPS-4328)", async () => {
+      // Simulates the lifecycle gpoulios-sb flagged on PR #19621:
+      //   1. Org is configured → syncHomeNpmrc writes private-registry
+      //      lines AND captures the image-baked baseline to
+      //      ~/.superblocks/npmrc.default via hardlink.
+      //   2. Org is deconfigured → syncHomeNpmrc must restore the
+      //      baseline so subsequent npm/pnpm pinned at the userconfig
+      //      do not keep resolving through the previous org's registry.
+      const baked =
+        "//npm.pkg.github.com/:_authToken=ghpr-baked\n" +
+        "@superblocksteam:registry=https://npm.pkg.github.com/\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), baked, { mode: 0o600 });
+
+      // Step 1: configured → rewrite + snapshot.
+      const configuredClient = makeClient(async () => CONFIGURED).client;
+      await syncHomeNpmrc({
+        npmRegistryClient: configuredClient,
+        logger: asLogger(makeLogger()),
+        homeDir,
+      });
+      const rewritten = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(rewritten).toContain(
+        "registry=https://artifactory.example.com/api/npm/npm/",
+      );
+      expect(rewritten).not.toBe(baked);
+      expect(await readFile(superblocksNpmrcBackupPath(homeDir), "utf-8")).toBe(
+        baked,
+      );
+
+      // Step 2: not-configured → restore image-default.
+      const notConfiguredClient = makeClient(async () => NOT_CONFIGURED).client;
+      const logger = makeLogger();
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: notConfiguredClient,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("restored-not-configured");
+      const restored = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(restored).toBe(baked);
+      expect(restored).not.toContain(
+        "registry=https://artifactory.example.com/api/npm/npm/",
+      );
+    });
+
+    it("removes the Superblocks-owned userconfig when no backup exists and the org has been deconfigured", async () => {
+      // Cold-boot case: a Superblocks-owned userconfig is on disk from
+      // a previous run (or a manual smoke test) but no .npmrc.default
+      // backup is alongside it. Leaving the file in place would let
+      // long-lived npm/pnpm subprocesses pinned at the userconfig
+      // continue resolving through a stale registry. Remove it
+      // instead so the next install falls through to public npm.
+      const stale =
+        "registry=https://artifactory.example.com/api/npm/npm/\n" +
+        "//artifactory.example.com/api/npm/npm/:_authToken=stale\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), stale, { mode: 0o600 });
+      await expect(
+        stat(superblocksNpmrcBackupPath(homeDir)),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+
+      const { client } = makeClient(async () => NOT_CONFIGURED);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("restored-not-configured");
+      await expect(stat(npmrcPath(homeDir))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+
+    it("fails closed on snapshot failure: skips the managed rewrite AND preserves the baked file on later deconfigure (APPS-4428)", async () => {
+      // The hole: `snapshotInitialNpmrc` is best-effort and can fail
+      // silently (e.g. EXDEV when ~/.superblocks/ and the backup straddle
+      // filesystems). When that happens, a real baked-in userconfig
+      // exists with NO restore baseline.
+      //
+      // PR #19690 first try only guarded the unlink on the deconfigure
+      // path, but still let `writeNpmrc` rewrite the file with the
+      // managed private-registry content. gpoulios-sb caught that this
+      // leaves a stale Artifactory token + registry on disk after the
+      // org is deconfigured — the exact stale-userconfig leak the
+      // restore path is supposed to avoid.
+      //
+      // Fix: fail closed on the snapshot-failed branch. The configured
+      // sync refuses to overwrite the baked userconfig, so the
+      // deconfigure path inherits an unchanged baked file (which the
+      // snapshot-failure guard then correctly leaves in place).
+      const baked =
+        "//npm.pkg.github.com/:_authToken=ghpr-baked\n" +
+        "@superblocksteam:registry=https://npm.pkg.github.com/\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), baked, { mode: 0o600 });
+
+      // Step 1: configured → snapshot fails silently. The managed
+      // rewrite MUST be skipped; the baked content survives untouched.
+      snapshotInitialNpmrcMock.mockImplementationOnce(async () => "failed");
+      const configuredClient = makeClient(async () => CONFIGURED).client;
+      const configuredLogger = makeLogger();
+      const rewriteResult = await syncHomeNpmrc({
+        npmRegistryClient: configuredClient,
+        logger: asLogger(configuredLogger),
+        homeDir,
+      });
+
+      expect(rewriteResult.outcome).toBe("skipped-snapshot-failed");
+      expect(snapshotInitialNpmrcMock).toHaveBeenCalledWith(
+        npmrcPath(homeDir),
+        superblocksNpmrcBackupPath(homeDir),
+      );
+      await expect(
+        snapshotInitialNpmrcMock.mock.results[0]?.value,
+      ).resolves.toBe("failed");
+      // The userconfig is still the baked content — no Artifactory
+      // registry/token, no managed lines.
+      const preserved = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(preserved).toBe(baked);
+      expect(preserved).not.toContain("artifactory.example.com");
+      // And no backup exists (the snapshot failed).
+      await expect(
+        stat(superblocksNpmrcBackupPath(homeDir)),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+      // The refusal to overwrite is surfaced as a warn for telemetry.
+      expect(configuredLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("userconfig snapshot failed"),
+        expect.objectContaining({
+          path: npmrcPath(homeDir),
+          source: "configured",
+        }),
+      );
+
+      // Step 2: not-configured. With no backup and a recorded snapshot
+      // failure, the userconfig (still the baked content) must survive.
+      // The deconfigure path's destructive unlink is the original
+      // APPS-4328 hole; the snapshot-failure guard withholds it here and
+      // returns the dedicated `skipped-snapshot-failed` outcome — NOT
+      // `restored-not-configured`, since nothing was restored or removed.
+      const notConfiguredClient = makeClient(async () => NOT_CONFIGURED).client;
+      const deconfigureLogger = makeLogger();
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: notConfiguredClient,
+        logger: asLogger(deconfigureLogger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("skipped-snapshot-failed");
+      const survived = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(survived).toBe(baked);
+      expect(deconfigureLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("userconfig snapshot failed earlier"),
+        expect.objectContaining({ path: npmrcPath(homeDir) }),
+      );
+      // And no spurious "restored image-default" info to confuse the
+      // operator — the warn above already explains the leave-in-place.
+      expect(deconfigureLogger.info).not.toHaveBeenCalled();
+    });
+
+    it("does not create ~/.superblocks/npmrc when the file does not exist", async () => {
+      const { client } = makeClient(async () => NOT_CONFIGURED);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("restored-not-configured");
+      await expect(stat(npmrcPath(homeDir))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+
+    it("captures the image-baked userconfig as .npmrc.default on the first configured write", async () => {
+      // Regression guard for the capture half of APPS-4328: the
+      // hardlink must land BEFORE writeNpmrc rewrites the userconfig
+      // or the backup will hold the rewritten (private-registry)
+      // content instead of the image baseline. Verified by checking
+      // that the captured file equals the original baked content
+      // byte-for-byte AFTER the configured rewrite has happened.
+      const baked =
+        "//npm.pkg.github.com/:_authToken=ghpr-baked\n" +
+        "@superblocksteam:registry=https://npm.pkg.github.com/\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), baked, { mode: 0o600 });
+
+      const { client } = makeClient(async () => CONFIGURED);
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(makeLogger()),
+        homeDir,
+      });
+
+      const captured = await readFile(
+        superblocksNpmrcBackupPath(homeDir),
+        "utf-8",
+      );
+      expect(captured).toBe(baked);
+    });
+  });
+
+  describe("unreachable → leave file alone", () => {
+    it("does NOT delete the userconfig when the server is unreachable with cold cache", async () => {
+      // A cold cache + transient outage at startup must not punch a hole
+      // in the userconfig right before the CLI auto-upgrade runs. The
+      // client surfaces `source: "unreachable"` precisely so we can
+      // branch here.
+      const { client, getConfig } = makeClient(async () => CONFIGURED);
+      const logger = makeLogger();
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      const before = await readFile(npmrcPath(homeDir), "utf-8");
+
+      getConfig.mockResolvedValueOnce(UNREACHABLE);
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("skipped-unreachable");
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("registry server unreachable"),
+        expect.objectContaining({
+          path: npmrcPath(homeDir),
+        }),
+      );
+      const after = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(after).toBe(before);
+    });
+
+    it("does not create ~/.superblocks/npmrc when the server is unreachable and no file exists", async () => {
+      const { client } = makeClient(async () => UNREACHABLE);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("skipped-unreachable");
+      await expect(stat(npmrcPath(homeDir))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // APPS-4368: ignore-scripts policy baked into ~/.npmrc
+  // -------------------------------------------------------------------------
+
+  describe("ignore-scripts policy (APPS-4368)", () => {
+    const NOT_CONFIGURED_SCRIPTS_OFF: NpmRegistryFetchResult = {
+      source: "not-configured",
+      config: { configured: false, allowInstallScripts: false },
+    };
+
+    const CONFIGURED_SCRIPTS_OFF: NpmRegistryFetchResult = {
+      source: "configured",
+      config: {
+        configured: true,
+        default: {
+          url: "https://artifactory.example.com/api/npm/npm/",
+          token: "test-token-abc",
+        },
+        allowInstallScripts: false,
+      },
+    };
+
+    it("writes a policy-only userconfig when not-configured + allowInstallScripts=false", async () => {
+      const { client } = makeClient(async () => NOT_CONFIGURED_SCRIPTS_OFF);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain("ignore-scripts=true");
+      const stats = await stat(npmrcPath(homeDir));
+      expect(stats.mode & 0o777).toBe(HOME_NPMRC_MODE);
+    });
+
+    it("includes ignore-scripts=true alongside registry lines when configured + policy=false", async () => {
+      const { client } = makeClient(async () => CONFIGURED_SCRIPTS_OFF);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain("ignore-scripts=true");
+      expect(content).toContain(
+        "registry=https://artifactory.example.com/api/npm/npm/",
+      );
+    });
+
+    it("cleans up the policy-only userconfig after flipping to scripts-allowed", async () => {
+      const { client, getConfig } = makeClient(
+        async () => NOT_CONFIGURED_SCRIPTS_OFF,
+      );
+      const logger = makeLogger();
+      // First sync: policy-only write
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain("ignore-scripts=true");
+
+      // Flip to not-configured + scripts allowed → restore removes the
+      // policy-only file (no backup exists since we never went through
+      // the configured path, and unlinkTargetWhenBackupMissing is true).
+      getConfig.mockResolvedValueOnce(NOT_CONFIGURED);
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      expect(result.outcome).toBe("restored-not-configured");
+      await expect(stat(npmrcPath(homeDir))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+
+    it("cleans up after repeated policy syncs then flip (no poisoned backup)", async () => {
+      // Regression: on the second sync with policy=false the write path
+      // must NOT snapshot the policy file as the backup baseline.
+      // Otherwise a later flip to scripts-allowed restores the policy
+      // content (both target and backup are identical) → no-op, leaving
+      // ignore-scripts=true in place permanently.
+      const { client, getConfig } = makeClient(
+        async () => NOT_CONFIGURED_SCRIPTS_OFF,
+      );
+      const logger = makeLogger();
+
+      // Two consecutive syncs with scripts off.
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      expect(await readFile(npmrcPath(homeDir), "utf-8")).toContain(
+        "ignore-scripts=true",
+      );
+      // Backup must NOT exist (we never went through the configured path).
+      await expect(
+        stat(superblocksNpmrcBackupPath(homeDir)),
+      ).rejects.toMatchObject({ code: "ENOENT" });
+
+      // Flip: scripts allowed → file must be removed.
+      getConfig.mockResolvedValueOnce(NOT_CONFIGURED);
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+      expect(result.outcome).toBe("restored-not-configured");
+      await expect(stat(npmrcPath(homeDir))).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    });
+
+    it("writes the policy-only userconfig even when a pre-existing file is present (Superblocks-owned dir)", async () => {
+      // The userconfig now lives in ~/.superblocks/npmrc (a Superblocks-
+      // owned directory), so there is no foreign-file guard — the writer
+      // always owns the file.
+      const existingContent = "registry=https://registry.npmjs.org/\n";
+      await mkdir(path.join(homeDir, ".superblocks"), { recursive: true });
+      await writeFile(npmrcPath(homeDir), existingContent, {
+        mode: 0o600,
+      });
+      const { client } = makeClient(async () => NOT_CONFIGURED_SCRIPTS_OFF);
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("written");
+      const content = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(content).toContain("ignore-scripts=true");
+    });
+  });
+
+  describe("error handling", () => {
+    it("returns outcome 'error' and logs a warn when the client throws", async () => {
+      // RBAC denial / malformed-request branches surface as throws from
+      // `NpmRegistryClient`. Dev-server startup must not crash on those
+      // — log + leave the userconfig untouched.
+      const seedLogger = makeLogger();
+      const { client: seedClient } = makeClient(async () => CONFIGURED);
+      await syncHomeNpmrc({
+        npmRegistryClient: seedClient,
+        logger: asLogger(seedLogger),
+        homeDir,
+      });
+      const before = await readFile(npmrcPath(homeDir), "utf-8");
+
+      const { client } = makeClient(async () => {
+        throw new Error("HTTP 403 from npm-registry endpoint");
+      });
+      const logger = makeLogger();
+
+      const result = await syncHomeNpmrc({
+        npmRegistryClient: client,
+        logger: asLogger(logger),
+        homeDir,
+      });
+
+      expect(result.outcome).toBe("error");
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining("client.getConfig() failed"),
+        expect.objectContaining({
+          path: npmrcPath(homeDir),
+        }),
+      );
+      const after = await readFile(npmrcPath(homeDir), "utf-8");
+      expect(after).toBe(before);
+    });
+  });
+
+  describe("superblocksNpmrcPath helper", () => {
+    it("returns <homeDir>/.superblocks/npmrc", () => {
+      expect(superblocksNpmrcPath(homeDir)).toBe(
+        path.join(homeDir, ".superblocks", "npmrc"),
+      );
+    });
+
+    it("falls back to os.homedir() when no argument is provided", () => {
+      expect(superblocksNpmrcPath()).toBe(
+        path.join(os.homedir(), ".superblocks", "npmrc"),
+      );
+    });
+  });
+
+  describe("superblocksLogsPath helper", () => {
+    it("returns <appDir>/.superblocks/logs (app-based, not home-based)", () => {
+      expect(superblocksLogsPath("/srv/app")).toBe(
+        path.join("/srv/app", ".superblocks", "logs"),
+      );
+    });
+  });
+});