@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

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

@@ -13,12 +13,19 @@ import {
   NON_SB_ORG_UPDATE_ERROR,
   traceFunction,
 } from "@superblocksteam/shared";
+import {
+  bucketNpmRegistryHost,
+  redactNpmRegistryHostsFromText,
+} from "@superblocksteam/telemetry";
 import type { LockService } from "@superblocksteam/vite-plugin-file-sync/lock-service";
+import { classifyNpmExecStderr } from "@superblocksteam/vite-plugin-file-sync/npm-error-parser";
 
 import type { ResponseMeta } from "../socket/handlers.js";
 import { getTracer } from "../telemetry/index.js";
 import { getErrorMeta, getLogger } from "../telemetry/logging.js";
 import type { ApplicationConfigWithTokenConfigAndUserInfo } from "../types/common.js";
+import { superblocksLogsPath, superblocksNpmrcPath } from "./home-npmrc.mjs";
+import { stripUpgradedCliLockfiles } from "./post-upgrade-lockfile-strip.mjs";
 import {
   getCurrentCliVersion,
   clearCliVersionCache,
@@ -26,6 +33,70 @@ import {
 
 export const AUTO_UPGRADE_EXIT_CODE = 99;
 
+/**
+ * Build the argument vector for the global CLI auto-upgrade install.
+ * Extracted so the build path can be tested without driving an exec
+ * subprocess.
+ *
+ * `--audit=false` is npm-only. Userconfig pinning lives in the spawned
+ * subprocess env (`NPM_CONFIG_USERCONFIG`) rather than a CLI flag,
+ * because pnpm does not accept `--userconfig` (open issue
+ * pnpm/pnpm#6036) but does honor the env var through its npm-config
+ * compatibility layer. Using the env var means a single mechanism
+ * works for both agents.
+ */
+export function buildGlobalInstallArgs(
+  pm: { agent: DetectResult["agent"] },
+  packageName: string,
+): string[] {
+  const installArgs = ["--fund=false", "--save-exact"];
+  if (pm.agent === "npm") {
+    installArgs.push("--audit=false");
+  }
+  installArgs.push("--force");
+  installArgs.push(packageName);
+  return installArgs;
+}
+
+/**
+ * Build the env overlay for a Superblocks-spawned npm/pnpm subprocess.
+ * Pins both `NPM_CONFIG_USERCONFIG` (npm + pnpm <= 10) and
+ * `PNPM_CONFIG_USERCONFIG` (pnpm 11+) so the install reads its
+ * registry/auth lines from the Superblocks-owned `~/.superblocks/npmrc`
+ * instead of the default `~/.npmrc`.
+ *
+ * Why both: pnpm 11 stopped recognising `npm_config_*` env vars (the
+ * @pnpm/npm-conf compatibility layer was tightened) and now requires
+ * `pnpm_config_*` for its config keys. pnpm <= 10 honors only the
+ * `npm_config_*` form; npm has always honored only the `npm_config_*`
+ * form. Setting both is harmless on the agent that ignores one of
+ * them. Verified by `userconfig-env.integration.test.mts` against both
+ * pnpm 10 and pnpm 11 binaries.
+ *
+ * The CLI-flag alternative (`--userconfig=` for npm,
+ * `--config.userconfig=` for pnpm) would require branching on the
+ * agent at every call site; the env-overlay approach is uniform.
+ */
+export function buildInstallEnv(
+  userconfigPath: string,
+  logsDir?: string,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return {
+    ...baseEnv,
+    NPM_CONFIG_USERCONFIG: userconfigPath,
+    PNPM_CONFIG_USERCONFIG: userconfigPath,
+    // Route npm's per-run debug log to `<app>/.superblocks/logs` so a
+    // failed install in the live-edit pod leaves a collectable log in a
+    // predictable place. npm writes `<logs-dir>/<ts>-debug-0.log` on every
+    // run (pruned to `logs-max`, default 10) and creates the dir if it is
+    // missing. pnpm has no equivalent logs-dir config and ignores this var
+    // (npm-only by design — see `superblocksLogsPath`). Only set when a
+    // logs dir is supplied so callers that don't opt in are unaffected.
+    ...(logsDir ? { NPM_CONFIG_LOGS_DIR: logsDir } : {}),
+  };
+}
+
 const exec = promisify(child_process.exec);
 const logger = getLogger();
 const tracer = getTracer();
@@ -105,17 +176,17 @@ async function upgradeCliWithPackageManager(
   pm: DetectResult,
   targetVersion: string,
   alias?: string,
+  hasAnyRegistryConfigured?: boolean,
+  // Directory npm should drop its per-run debug log into (the app's
+  // `.superblocks/logs`). Optional so callers/tests that don't care keep
+  // npm's default `_logs` location.
+  logsDir?: string,
 ): Promise<void> {
   const packageName = alias
     ? `@superblocksteam/cli@npm:${alias}@${targetVersion}`
     : `@superblocksteam/cli@${targetVersion}`;
 
-  const installArgs = ["--fund=false", "--save-exact"];
-  if (pm.agent === "npm") {
-    installArgs.push("--audit=false");
-  }
-  installArgs.push("--force");
-  installArgs.push(packageName);
+  const installArgs = buildGlobalInstallArgs({ agent: pm.agent }, packageName);
 
   const installCommand = resolveCommand(pm.agent, "global", installArgs);
 
@@ -132,13 +203,84 @@ async function upgradeCliWithPackageManager(
     resolver = resolve;
     rejecter = reject;
   });
+  // Capture stderr alongside the streaming logger.warn so that, on failure,
+  // we can pattern-match the npm error code (APPS-4324) and emit a structured
+  // NpmInstallBlocked diagnostic before rejecting. The k8s crash-loop log
+  // then carries the reason code rather than just "Failed to upgrade".
+  let stderrBuffer = "";
   const cp = child_process.exec(
     `${command} ${args.join(" ")}`,
     {
       cwd: process.cwd(),
+      // Point the package manager at the Superblocks-owned userconfig so
+      // the global install resolves through whatever registry config
+      // `syncHomeNpmrc` materialised at startup, without touching the
+      // developer's `~/.npmrc`. Works for both npm and pnpm. `logsDir`
+      // also routes npm's debug log into the app's `.superblocks/logs`.
+      env: buildInstallEnv(superblocksNpmrcPath(), logsDir),
     },
     (error) => {
       if (error) {
+        // `child_process.exec` aggregates stderr on the rejected error (capped
+        // by `maxBuffer`); fall back to it when our `stderr.on('data', …)`
+        // listener missed the chunks — a subprocess that fails fast can emit
+        // and exit before the listener attaches, leaving `stderrBuffer` empty
+        // and dropping the structured diagnostic this PR exists to guarantee.
+        const errStderr = (error as { stderr?: unknown }).stderr;
+        const stderrText =
+          stderrBuffer || (typeof errStderr === "string" ? errStderr : "");
+        const blocked = classifyNpmExecStderr(stderrText, {
+          requestedPackages: [{ name: packageName }],
+          hasAnyRegistryConfigured,
+        });
+        if (blocked) {
+          // Structured fields are grep-able from the message body because
+          // the local logger contract limits the meta arg to
+          // `{ error: { kind, message, stack } }`. The encoding mirrors the
+          // `errorId=...` convention in `dev.mts` so operator alerts and
+          // log drains can key on `reason=...`. Logged ahead of the legacy
+          // "Failed to upgrade" line so the diagnostic still surfaces if a
+          // downstream sink truncates further lines.
+          // Pass the raw host through `bucketNpmRegistryHost` so this log
+          // emits a bounded enum (`public_npm` | `private` | `unknown`)
+          // instead of a customer's private registry hostname. Operational
+          // logs are a shared destination; raw hosts there leak customer
+          // infra identifiers and create unbounded log facets. This mirrors
+          // APPS-4189 (PR #19622) which bucketed the same field for llmobs
+          // tags via the same helper.
+          //
+          // `summary` is npm-emitted free text (first non-code error line —
+          // "401 Unauthorized - GET https://...", "self-signed certificate
+          // in chain", etc.). The phrasing carries diagnostic value beyond
+          // the structured `reason` / `subreason` / `npmErrorCode` facets
+          // (CA-bundle hints, proxy hints), but it also still echoes the
+          // raw URL/host from the npm stderr line. Redact URLs and bare
+          // hostnames before logging so this shared operational sink
+          // doesn't leak customer registry hostnames (APPS-4381 PR #19634
+          // re-review).
+          //
+          // We also omit the meta arg here: `getErrorMeta(blocked)` would
+          // synthesize `{ error: { kind, message, stack } }` from the
+          // `NpmInstallBlocked` instance, and the constructor builds
+          // `message` as `"npm install blocked (...) against ${host} [code]"`
+          // — same host leak, different field. The structured body fields
+          // above already convey the kind (`reason` + `subreason` +
+          // `npmErrorCode`) without the hostname, so the meta arg has no
+          // signal to add.
+          const sanitizedSummary = redactNpmRegistryHostsFromText(
+            blocked.summary ?? "",
+          );
+          logger.error(
+            `[npm-install-blocked] reason=${blocked.reason}` +
+              ` subreason=${blocked.subreason ?? "n/a"}` +
+              ` npmErrorCode=${blocked.npmErrorCode ?? "unknown"}` +
+              ` registryHost=${bucketNpmRegistryHost(blocked.registryHost)}` +
+              ` httpStatus=${blocked.httpStatus ?? "n/a"}` +
+              ` hasAnyRegistryConfigured=${blocked.hasAnyRegistryConfigured ?? "unknown"}` +
+              ` packages=${JSON.stringify(blocked.packages)}` +
+              ` summary=${JSON.stringify(sanitizedSummary)}`,
+          );
+        }
         logger.error(`Failed to upgrade packages to ${targetVersion}`);
         rejecter(error);
       } else {
@@ -150,6 +292,7 @@ async function upgradeCliWithPackageManager(
     logger.info(data);
   });
   cp.stderr?.on("data", (data) => {
+    stderrBuffer += String(data);
     logger.warn(data);
   });
 
@@ -182,6 +325,12 @@ export async function checkVersionsAndWritePackageJson(
   config: ApplicationConfigWithTokenConfigAndUserInfo,
   forceUpgrade: boolean = false,
   skipCliUpgrade: boolean = false,
+  // App working directory, used to route the CLI-upgrade install's npm
+  // debug log into `<app>/.superblocks/logs`. Defaults to `process.cwd()`
+  // (the dev-server's cwd === app root) so existing callers/tests are
+  // unaffected; `dev()` passes its `cwd` explicitly for consistency with
+  // the startup install.
+  appDir: string = process.cwd(),
 ): Promise<{
   cliUpdated: boolean;
   upgradePromises: Promise<void>[];
@@ -269,6 +418,16 @@ export async function checkVersionsAndWritePackageJson(
         return;
       }
 
+      // Failure-mode contrast with AppShell's per-app install path: AppShell
+      // routes exec failures through `classifyNpmExecError` and emits a
+      // structured `NpmInstallBlocked` diagnostic. The auto-upgrade subprocess
+      // below does NOT route through that classifier — it `exec`s
+      // `npm install -g @superblocksteam/cli@...` directly. A perimeter block
+      // (ECONNREFUSED) surfaces here as a generic `Error` caught by the outer
+      // try/catch (`hasFailedToUpgrade = true` → release lock → `process.exit`),
+      // which Kubernetes restarts. The operator sees a visible crash-loop with
+      // "Error upgrading packages" rather than a silent fallback. For symmetry
+      // with the install path, wrap the upgrade exec in the same classifier.
       try {
         if (
           !skipCliUpgrade &&
@@ -291,7 +450,6 @@ export async function checkVersionsAndWritePackageJson(
               });
               if (!oclifUpgradeSucceeded) {
                 logger.info(`Falling back to package manager upgrade for CLI`);
-                // Fall back to package manager upgrade
                 await traceFunction({
                   name: "upgradePackageWithPackageManager - cli",
                   tracer,
@@ -300,11 +458,25 @@ export async function checkVersionsAndWritePackageJson(
                       packageManager,
                       targetVersions.cli,
                       currentCliInfo.alias,
+                      undefined,
+                      superblocksLogsPath(appDir),
                     );
                   },
                 });
                 cliUpdated = true;
               }
+              // The freshly fetched tarball may ship bundled lockfiles with
+              // stale public-host `resolved` URLs; strip them so the next
+              // install does not bypass the active registry. Non-fatal — a
+              // failed post-step must not crash the pod after a working
+              // upgrade.
+              await traceFunction({
+                name: "stripUpgradedCliLockfiles",
+                tracer,
+                fn: async () => {
+                  await stripUpgradedCliLockfiles(logger);
+                },
+              });
             },
           });
           upgradePromises.push(cliUpgradePromise);

package/src/cli-replacement/dependency-install-classifier.mts

@@ -0,0 +1,118 @@
+import type { DependencyInstallError } from "@superblocksteam/library-shared/types";
+import {
+  classifyNpmExecStderr,
+  parseNpmJsonDiagnostic,
+  parseNpmJsonError,
+  scrubSecrets,
+  type NpmInstallBlocked,
+  type NpmInstallBlockedReason,
+  type ParseContext,
+} from "@superblocksteam/vite-plugin-file-sync/npm-registry";
+
+/** Marker thrown by the INITIAL verification install so the dev.mts catch can
+ *  degrade by ORIGIN (never on classifiability). Carries the classified error. */
+export class InitialInstallFailed extends Error {
+  readonly serverError: DependencyInstallError;
+  constructor(serverError: DependencyInstallError) {
+    super(`initial dependency install failed (${serverError.category})`);
+    this.name = "InitialInstallFailed";
+    this.serverError = serverError;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export interface ExecFailure {
+  stdout?: string;
+  stderr?: string;
+  message?: string;
+}
+
+const REASON_TO_CATEGORY: Record<
+  NpmInstallBlockedReason,
+  DependencyInstallError["category"]
+> = {
+  not_in_registry: "not_in_registry",
+  registry_auth_failed: "registry_auth_failed",
+  registry_unreachable: "registry_unreachable",
+  tls_failed: "tls_failed",
+};
+
+const DEP_CONFLICT_CODES = /\b(ERESOLVE|ETARGET|EPEERINVALID)\b/;
+
+/** Best-effort: pull package specs out of an ERESOLVE/ETARGET `--json` detail. */
+export function parseDependencyConflict(
+  text: string,
+): { name: string; version?: string }[] {
+  const out: { name: string; version?: string }[] = [];
+  const re =
+    /(?:Found:|peer|resolve)\s+(@?[\w./-]+)@("?[^",\s]+"?|undefined)/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[1];
+    const version = m[2] === "undefined" ? undefined : m[2].replace(/"/g, "");
+    if (!out.some((p) => p.name === name)) out.push({ name, version });
+  }
+  return out;
+}
+
+function fromBlocked(
+  b: NpmInstallBlocked,
+  rawError: string,
+): DependencyInstallError {
+  return {
+    type: "dev-server/dependency-install",
+    timestamp: new Date().toISOString(),
+    category: REASON_TO_CATEGORY[b.reason],
+    subreason: b.subreason,
+    packages: b.packages.map((name) => ({ name })),
+    registryHost: b.registryHost,
+    npmErrorCode: b.npmErrorCode,
+    hasAnyRegistryConfigured: b.hasAnyRegistryConfigured,
+    rawError,
+  };
+}
+
+/** Always returns a DependencyInstallError (never null). */
+export function classifyInitialInstallError(
+  failure: ExecFailure,
+  ctx: ParseContext,
+): DependencyInstallError {
+  const stdout = failure.stdout ?? "";
+  const stderr = failure.stderr ?? "";
+  // Use `||` (not `??`) so an empty `stderr` ("" — the default on L:stderr, and
+  // common under `--json`) falls through to the exec rejection's `.message`
+  // ("Command failed: …") instead of yielding a blank rawError / Details panel.
+  const rawError = scrubSecrets(
+    parseNpmJsonDiagnostic(stdout) || stderr || failure.message || "",
+  );
+
+  const blockedFromJson = parseNpmJsonError(stdout, ctx);
+  if (blockedFromJson) return fromBlocked(blockedFromJson, rawError);
+
+  const combined = `${stdout}\n${stderr}`;
+  const codeMatch = combined.match(DEP_CONFLICT_CODES);
+  if (codeMatch) {
+    return {
+      type: "dev-server/dependency-install",
+      timestamp: new Date().toISOString(),
+      category: "dependency_conflict",
+      packages: parseDependencyConflict(combined),
+      npmErrorCode: codeMatch[1],
+      hasAnyRegistryConfigured: ctx.hasAnyRegistryConfigured,
+      rawError,
+    };
+  }
+
+  const blockedFromStderr = classifyNpmExecStderr(stderr, ctx);
+  if (blockedFromStderr) return fromBlocked(blockedFromStderr, rawError);
+
+  const unknownCode = combined.match(/npm (?:error|ERR!) code (\S+)/)?.[1];
+  return {
+    type: "dev-server/dependency-install",
+    timestamp: new Date().toISOString(),
+    category: "unknown",
+    npmErrorCode: unknownCode,
+    hasAnyRegistryConfigured: ctx.hasAnyRegistryConfigured,
+    rawError,
+  };
+}

package/src/cli-replacement/dependency-install-classifier.test.mts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+
+import {
+  InitialInstallFailed,
+  classifyInitialInstallError,
+} from "./dependency-install-classifier.mjs";
+
+const ERESOLVE_JSON = JSON.stringify({
+  error: {
+    code: "ERESOLVE",
+    summary: "unable to resolve dependency tree",
+    detail:
+      'Found: react-router@undefined\nCould not resolve dependency:\npeer react-router@">=6.4" from @superblocksteam/library@2.0.0-SNAPSHOT',
+  },
+});
+
+describe("classifyInitialInstallError", () => {
+  it("classifies ERESOLVE as dependency_conflict and extracts packages", () => {
+    const e = classifyInitialInstallError(
+      {
+        stdout: ERESOLVE_JSON,
+        stderr: "npm error code ERESOLVE",
+        message: "Command failed",
+      },
+      { hasAnyRegistryConfigured: true, requestedPackages: [] },
+    );
+    expect(e.type).toBe("dev-server/dependency-install");
+    expect(e.category).toBe("dependency_conflict");
+    expect(e.npmErrorCode).toBe("ERESOLVE");
+    expect(e.packages?.some((p) => p.name === "react-router")).toBe(true);
+    expect(e.rawError.length).toBeGreaterThan(0);
+  });
+
+  it("maps an E404 registry block to not_in_registry", () => {
+    const E404 = JSON.stringify({
+      error: {
+        code: "E404",
+        summary: "Not Found - GET https://reg.corp/foo",
+        detail: "'foo@1.0.0' is not in this registry.",
+      },
+    });
+    const e = classifyInitialInstallError(
+      { stdout: E404, stderr: "", message: "x" },
+      { hasAnyRegistryConfigured: true, requestedPackages: [{ name: "foo" }] },
+    );
+    expect(e.category).toBe("not_in_registry");
+    expect(e.registryHost).toBe("reg.corp");
+  });
+
+  it("falls back to unknown for an unmapped code (still a DependencyInstallError)", () => {
+    const e = classifyInitialInstallError(
+      {
+        stdout: "not json",
+        stderr: "npm error code EWEIRD\nsomething broke",
+        message: "x",
+      },
+      {},
+    );
+    expect(e.category).toBe("unknown");
+    expect(e.rawError).toContain("EWEIRD");
+  });
+
+  it("InitialInstallFailed carries the classified error", () => {
+    const se = classifyInitialInstallError(
+      { stdout: ERESOLVE_JSON, stderr: "", message: "x" },
+      {},
+    );
+    const marker = new InitialInstallFailed(se);
+    expect(marker).toBeInstanceOf(Error);
+    expect(marker.serverError).toBe(se);
+  });
+});