@superblocksteam/sdk 2.0.123-next.0 → 2.0.124-next.0

package/src/cli-replacement/post-upgrade-lockfile-strip.mts

@@ -0,0 +1,296 @@
+/**
+ * Post-CLI-upgrade lockfile normalization for the dev-server pod's globally
+ * installed Superblocks CLI.
+ *
+ * npm honors `resolved` URLs verbatim, so a tarball whose bundled lockfile
+ * entries point at `registry.npmjs.org` keeps fetching from public npm even
+ * after we've written a private `.npmrc`. This module strips those URLs
+ * post-upgrade so subsequent installs re-resolve through the active registry.
+ *
+ * The walk from the resolved `superblocks` binary up to the CLI package root
+ * is bounded so a misconfigured layout can never mutate arbitrary lockfiles
+ * on the filesystem.
+ *
+ * All failures are logged and swallowed — a failed post-strip must not crash
+ * the pod after a working upgrade. The next dev startup repeats the strip
+ * idempotently.
+ */
+
+import * as child_process from "node:child_process";
+import fs from "node:fs/promises";
+import * as path from "node:path";
+import { promisify } from "node:util";
+
+import {
+  stripResolvedFromLockfile,
+  stripResolvedFromLockfilePath,
+} from "@superblocksteam/vite-plugin-file-sync/npm-registry";
+
+import { getErrorMeta, type Logger } from "../telemetry/logging.js";
+
+const exec = promisify(child_process.exec);
+
+const LOG_PREFIX = "[post-upgrade-lockfile-strip]";
+
+/**
+ * Upper bound on the post-upgrade strip. The I/O is local and small, but the
+ * CLI install can live on a network-mounted prefix (custom `npm prefix`,
+ * Volta cache, etc.) where a hung `fs.realpath` or `fs.readFile` would
+ * otherwise extend `cliUpgradePromise` and block dev-server startup. A
+ * timeout keeps the boot path bounded; the underlying I/O is left to settle
+ * in the background since every step is idempotent and individually error-
+ * swallowing.
+ */
+const STRIP_TIMEOUT_MS = 5_000;
+
+/**
+ * Upper bound on `package.json` lookups when walking up from the resolved
+ * `superblocks` binary. The expected path depth is 3 levels
+ * (`<prefix>/lib/node_modules/@superblocksteam/cli/bin/run.js` ->
+ *  `<prefix>/lib/node_modules/@superblocksteam/cli`); 8 leaves headroom for
+ * non-standard layouts (Volta, nvm, custom prefixes) without ever climbing
+ * out of the install tree.
+ */
+const MAX_PACKAGE_ROOT_WALK_DEPTH = 8;
+
+// Both names are valid CLI install roots: `cli-ephemeral` is the alias used
+// for snapshot builds (see the alias detection in `version-detection.ts`),
+// and either may appear in the global install depending on which channel the
+// pod was provisioned against.
+const CLI_PACKAGE_NAMES = new Set<string>([
+  "@superblocksteam/cli",
+  "@superblocksteam/cli-ephemeral",
+]);
+
+/**
+ * Injectable subset of `child_process.exec` so tests can stub the
+ * `which`/`where` lookup without spawning a real subprocess.
+ */
+export type WhichRunner = (binary: string) => Promise<string>;
+
+const defaultWhichRunner: WhichRunner = async (binary) => {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  const { stdout } = await exec(`${cmd} ${binary}`);
+  return stdout;
+};
+
+/**
+ * Discovers the absolute path of the `@superblocksteam/cli` install root
+ * (the directory containing the CLI's `package.json`), or returns `undefined`
+ * if discovery fails. Discovery failures are non-fatal — the caller logs and
+ * skips the strip rather than aborting.
+ */
+export async function findGlobalCliInstallDir(
+  logger: Logger,
+  whichRunner: WhichRunner = defaultWhichRunner,
+): Promise<string | undefined> {
+  let binStdout: string;
+  try {
+    binStdout = await whichRunner("superblocks");
+  } catch (error) {
+    logger.warn(
+      `${LOG_PREFIX} which/where superblocks failed; skipping strip`,
+      {
+        ...getErrorMeta(error),
+      },
+    );
+    return undefined;
+  }
+
+  // `which`/`where` may emit multiple lines (e.g. shim + real path on
+  // Windows). The first line wins; matches the existing pattern in
+  // `version-detection.ts`.
+  const binPath = binStdout.trim().split(/\r?\n/)[0]?.trim();
+  if (!binPath) {
+    logger.warn(
+      `${LOG_PREFIX} superblocks binary not found in PATH; skipping strip`,
+    );
+    return undefined;
+  }
+
+  let realBinPath: string;
+  try {
+    realBinPath = await fs.realpath(binPath);
+  } catch (error) {
+    logger.warn(
+      `${LOG_PREFIX} realpath failed for superblocks binary; skipping strip`,
+      {
+        binPath,
+        ...getErrorMeta(error),
+      },
+    );
+    return undefined;
+  }
+
+  let dir = path.dirname(realBinPath);
+  for (let i = 0; i < MAX_PACKAGE_ROOT_WALK_DEPTH; i++) {
+    const candidate = path.join(dir, "package.json");
+    let raw: string;
+    try {
+      raw = await fs.readFile(candidate, "utf-8");
+    } catch (error: unknown) {
+      const code = (error as NodeJS.ErrnoException | undefined)?.code;
+      if (code === "ENOENT") {
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+          break;
+        }
+        dir = parent;
+        continue;
+      }
+      logger.warn(
+        `${LOG_PREFIX} failed to read candidate package.json; skipping strip`,
+        {
+          candidate,
+          code,
+          ...getErrorMeta(error),
+        },
+      );
+      return undefined;
+    }
+
+    let parsed: { name?: unknown } | undefined;
+    try {
+      parsed = JSON.parse(raw) as { name?: unknown };
+    } catch (error) {
+      logger.warn(
+        `${LOG_PREFIX} candidate package.json is not valid JSON; skipping strip`,
+        {
+          candidate,
+          ...getErrorMeta(error),
+        },
+      );
+      return undefined;
+    }
+
+    if (typeof parsed.name === "string" && CLI_PACKAGE_NAMES.has(parsed.name)) {
+      return dir;
+    }
+
+    // Found a `package.json` that isn't the CLI's — keep walking up. Some
+    // layouts (oclif's update channel) nest the binary under a wrapper
+    // package; we don't want to bail on the first unrelated manifest.
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  logger.warn(
+    `${LOG_PREFIX} could not locate @superblocksteam/cli install root; skipping strip`,
+    {
+      startedAt: realBinPath,
+    },
+  );
+  return undefined;
+}
+
+export interface StripUpgradedCliLockfilesOptions {
+  /**
+   * Pre-resolved install root. If omitted, `findGlobalCliInstallDir` is used.
+   * Tests pass this directly to avoid stubbing `which`.
+   */
+  installDir?: string;
+  whichRunner?: WhichRunner;
+  /**
+   * Override the strip timeout (ms). Tests use a tight value to exercise the
+   * timeout branch without sleeping for the real bound.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Strips public-host `resolved` URLs from every lockfile under the global
+ * CLI install that the auto-upgrade could have refreshed. Returns the
+ * resolved install root on success, or `undefined` when discovery failed.
+ *
+ * Non-fatal: every individual strip already swallows lockfile-level errors
+ * (logged in `stripResolvedFromLockfilePath`); this wrapper additionally
+ * swallows discovery failures and any unexpected throw from the inner
+ * helpers so a successful upgrade is never demoted to a crash by a post-step
+ * problem.
+ */
+export async function stripUpgradedCliLockfiles(
+  logger: Logger,
+  options: StripUpgradedCliLockfilesOptions = {},
+): Promise<{ installDir?: string }> {
+  const installDir =
+    options.installDir ??
+    (await findGlobalCliInstallDir(logger, options.whichRunner));
+  if (!installDir) {
+    return {};
+  }
+
+  const timeoutMs = options.timeoutMs ?? STRIP_TIMEOUT_MS;
+  const start = Date.now();
+  // The hidden lockfile listing the CLI itself lives two levels up from
+  // installDir under the npm-global layout
+  // (<prefix>/lib/node_modules/.package-lock.json).
+  const globalHiddenLockfile = path.join(
+    path.dirname(path.dirname(installDir)),
+    ".package-lock.json",
+  );
+
+  const STRIP_TIMED_OUT = Symbol("STRIP_TIMED_OUT");
+  let timeoutHandle: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<typeof STRIP_TIMED_OUT>((resolve) => {
+    timeoutHandle = setTimeout(() => resolve(STRIP_TIMED_OUT), timeoutMs);
+  });
+  try {
+    const stripWork = Promise.all([
+      stripResolvedFromLockfile(installDir),
+      stripResolvedFromLockfilePath(globalHiddenLockfile),
+    ]);
+    const outcome = await Promise.race([stripWork, timeoutPromise]);
+    if (outcome === STRIP_TIMED_OUT) {
+      logger.warn(
+        `${LOG_PREFIX} strip exceeded timeout; continuing without waiting`,
+        {
+          installDir,
+          timeoutMs,
+          elapsedMs: Date.now() - start,
+        },
+      );
+      // We're abandoning `stripWork` after the timeout won the race. The
+      // inner helpers swallow per-file errors, but their atomic `writeFile`
+      // / `rename` calls can still throw (EACCES, EXDEV, ENOSPC, …) — and
+      // with no subscriber left on `stripWork`, a late rejection would
+      // surface as an unhandled rejection and crash the pod under Node's
+      // default policy. Attach a tail handler to keep the post-step
+      // non-fatal even when the timeout path is taken.
+      stripWork.catch((error) => {
+        logger.warn(
+          `${LOG_PREFIX} background strip rejected after timeout; ignoring`,
+          {
+            ...getErrorMeta(error),
+            installDir,
+          },
+        );
+      });
+    } else {
+      logger.info(
+        `${LOG_PREFIX} stripped resolved URLs from upgraded CLI lockfiles`,
+        {
+          installDir,
+          elapsedMs: Date.now() - start,
+        },
+      );
+    }
+  } catch (error) {
+    // The lower-level helpers already swallow per-file errors; this catches
+    // any unexpected throw so a post-step problem never surfaces as a failed
+    // upgrade.
+    logger.warn(`${LOG_PREFIX} unexpected error during strip; continuing`, {
+      ...getErrorMeta(error),
+      installDir,
+      elapsedMs: Date.now() - start,
+    });
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  return { installDir };
+}