@superblocksteam/sdk 2.0.123 → 2.0.124-next.0

package/src/dev-utils/dev-server-metrics.mts

@@ -16,6 +16,62 @@ import { isTelemetryInitialized } from "@superblocksteam/telemetry";
 
 import { getMeter } from "../telemetry/index.js";
 
+/**
+ * Allowlist of npm/pnpm error codes the classifier can attach to a
+ * `DependencyInstallError`. Used to BOUND the `npm_error_code` metric label:
+ * the classifier's unknown-branch extracts the code via a `(\S+)` regex, so an
+ * unexpected, malformed, or registry-injected token must never become a new
+ * time series. Any code outside this set maps to `"other"`; pnpm's variable
+ * `ERR_PNPM_FETCH_<status>` collapses to a single bucket.
+ */
+const KNOWN_NPM_ERROR_CODES = new Set<string>([
+  // dependency-graph conflicts (the repro)
+  "ERESOLVE",
+  "ETARGET",
+  "EPEERINVALID",
+  // not in registry
+  "E404",
+  // auth
+  "E401",
+  "E403",
+  "EAUTH",
+  "EAUTHIP",
+  "EAUTHUNKNOWN",
+  "EOTP",
+  // network / unreachable
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENETUNREACH",
+  "ETIMEDOUT",
+  "ESOCKETTIMEDOUT",
+  // tls
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "CERT_HAS_EXPIRED",
+  "CERT_NOT_YET_VALID",
+  "CERT_UNTRUSTED",
+  "UNABLE_TO_GET_ISSUER_CERT",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  // pnpm
+  "ERR_PNPM_META_FETCH_FAIL",
+  "ERR_PNPM_FETCH", // collapsed bucket for ERR_PNPM_FETCH_<status>
+]);
+
+/**
+ * Normalize an npm/pnpm error code into a bounded metric-label value. Known
+ * codes pass through (keeping the diagnostic facet); everything else collapses
+ * to `"other"` (or `"none"` when absent) so the
+ * `dev_server_initial_install_failure_total` series count stays bounded.
+ */
+export function normalizeNpmErrorCodeTag(code: string | undefined): string {
+  if (!code) return "none";
+  const collapsed = /^ERR_PNPM_FETCH_\d+$/.test(code) ? "ERR_PNPM_FETCH" : code;
+  return KNOWN_NPM_ERROR_CODES.has(collapsed) ? collapsed : "other";
+}
+
 /** Dev-server endpoints that produce per-request metrics. */
 export type DevServerEndpoint =
   | "_sb_health"
@@ -246,6 +302,46 @@ class DevServerMetrics {
         .record(durationMs);
     });
   }
+
+  /**
+   * Records a degraded startup caused by a failed initial dependency install.
+   *
+   * All tags are low-cardinality:
+   *   - `category`  is a closed enum from DependencyInstallError (safe).
+   *   - `npm_error_code` is a bounded npm error code string (e.g. "E401",
+   *     "ERESOLVE") or `"none"` when absent.
+   *   - `has_any_registry_configured` is a boolean string (`"true"` /
+   *     `"false"`) or `"unknown"` when the tri-state is undefined.
+   *
+   * Do NOT pass raw package names, registry hostnames, or rawError — those
+   * are high-cardinality or contain customer-infra identifiers.
+   */
+  recordInitialInstallFailure({
+    category,
+    npmErrorCode,
+    hasAnyRegistryConfigured,
+  }: {
+    category: string;
+    npmErrorCode?: string;
+    hasAnyRegistryConfigured?: boolean;
+  }): void {
+    const labels = {
+      category,
+      npm_error_code: normalizeNpmErrorCodeTag(npmErrorCode),
+      has_any_registry_configured:
+        hasAnyRegistryConfigured === undefined
+          ? "unknown"
+          : String(hasAnyRegistryConfigured),
+    };
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_initial_install_failure_total", {
+          description:
+            "Count of degraded dev-server startups caused by a failed initial dependency install.",
+        })
+        .add(1, labels);
+    });
+  }
 }
 
 /** Process-wide dev-server metrics singleton. */

package/src/dev-utils/dev-server-metrics.test.mts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+
+import { normalizeNpmErrorCodeTag } from "./dev-server-metrics.mjs";
+
+describe("normalizeNpmErrorCodeTag (metric cardinality bound)", () => {
+  it("passes through known npm codes", () => {
+    expect(normalizeNpmErrorCodeTag("ERESOLVE")).toBe("ERESOLVE");
+    expect(normalizeNpmErrorCodeTag("E404")).toBe("E404");
+    expect(normalizeNpmErrorCodeTag("E401")).toBe("E401");
+    expect(normalizeNpmErrorCodeTag("ENOTFOUND")).toBe("ENOTFOUND");
+    expect(normalizeNpmErrorCodeTag("CERT_HAS_EXPIRED")).toBe(
+      "CERT_HAS_EXPIRED",
+    );
+  });
+
+  it("collapses variable pnpm fetch codes into one bucket", () => {
+    expect(normalizeNpmErrorCodeTag("ERR_PNPM_FETCH_404")).toBe(
+      "ERR_PNPM_FETCH",
+    );
+    expect(normalizeNpmErrorCodeTag("ERR_PNPM_FETCH_500")).toBe(
+      "ERR_PNPM_FETCH",
+    );
+    expect(normalizeNpmErrorCodeTag("ERR_PNPM_META_FETCH_FAIL")).toBe(
+      "ERR_PNPM_META_FETCH_FAIL",
+    );
+  });
+
+  it("maps unknown / arbitrary / injected tokens to 'other' (cardinality guard)", () => {
+    expect(normalizeNpmErrorCodeTag("EWEIRD")).toBe("other");
+    expect(normalizeNpmErrorCodeTag("some-random-token")).toBe("other");
+    expect(normalizeNpmErrorCodeTag("`;rm -rf /#")).toBe("other");
+  });
+
+  it("maps an absent code to 'none'", () => {
+    expect(normalizeNpmErrorCodeTag(undefined)).toBe("none");
+    expect(normalizeNpmErrorCodeTag("")).toBe("none");
+  });
+});

package/src/dev-utils/dev-server.mts

@@ -14,6 +14,7 @@ import type { HmrOptions, Plugin, UserConfig } from "vite";
 import type { ViteDevServer } from "vite";
 import tsconfigPaths from "vite-tsconfig-paths";
 
+import type { ServerError } from "@superblocksteam/library-shared/types";
 import {
   JwtVerifier,
   SUPERBLOCKS_LIVE_GIT_BRANCH,
@@ -430,6 +431,14 @@ interface CreateDevServerOptions {
    * responding before the full server takes over.
    */
   warmActivationStart?: number;
+  /**
+   * Server-side errors (e.g. dependency-install failures) to surface to the UI
+   * via `/_sb_connect` and `/_sb_status`. Optional and read at request time, so
+   * the caller can mutate the referenced object after `createDevServer` returns
+   * and have later requests reflect the change. Treated as `{ serverErrors: [] }`
+   * when absent.
+   */
+  devServerStatus?: { serverErrors: ServerError[] };
 }
 
 let httpServer: http.Server;
@@ -472,6 +481,19 @@ function attachUpgradeMetricsListener(server: http.Server): void {
   });
 }
 
+/**
+ * Merges the live `serverErrors` list onto a status/health payload returned by
+ * `/_sb_connect` and `/_sb_status`. `devServerStatus` is optional and may omit
+ * `serverErrors`; both cases yield an empty array so the UI always receives a
+ * well-formed `serverErrors` field.
+ */
+export function buildStatusPayload<T extends object>(
+  base: T,
+  devServerStatus?: { serverErrors?: ServerError[] },
+): T & { serverErrors: ServerError[] } {
+  return { ...base, serverErrors: devServerStatus?.serverErrors ?? [] };
+}
+
 // The "Dev Server" is a long-running HTTP server that manages the Vite server
 export async function createDevServer({
   root,
@@ -490,6 +512,7 @@ export async function createDevServer({
   superblocksBaseUrl: explicitBaseUrl,
   existingServer,
   warmActivationStart,
+  devServerStatus,
 }: CreateDevServerOptions) {
   const logger = getLogger(loggerOverride);
   if (httpServer) {
@@ -818,16 +841,32 @@ export async function createDevServer({
     // Wait for it to be ready before responding.
     try {
       await vitePromise;
-      res.send(JSON.stringify(healthResponse));
+      res.send(
+        JSON.stringify(buildStatusPayload(healthResponse, devServerStatus)),
+      );
     } catch (e) {
       logger.error(
         "Vite server failed to initialize",
         getErrorMeta(e as Error),
       );
       res.locals.sbFailureType = "vite_init";
+      // Carry `devServerStatus.serverErrors` onto the failure body too.
+      // The 200 path uses `buildStatusPayload` to surface startup errors
+      // (e.g. dependency-install failures) to the editor's readiness path;
+      // doing the same here means a Vite-init failure that also recorded
+      // an install failure doesn't silently drop the install context from
+      // the wire — any consumer that inspects the non-ok body still sees
+      // a well-formed `serverErrors` array alongside the generic `error`.
       res
         .status(500)
-        .send(JSON.stringify({ error: "Dev server failed to initialize" }));
+        .send(
+          JSON.stringify(
+            buildStatusPayload(
+              { error: "Dev server failed to initialize" },
+              devServerStatus,
+            ),
+          ),
+        );
     }
   });
 
@@ -883,13 +922,14 @@ export async function createDevServer({
   app.get("/_sb_status", authHandler, async (_req, res) => {
     res.setHeader("Content-Type", "application/json");
     if (lockService?.isLocked) {
-      res.send({
-        connectedUsers: lockService.connectedUsers,
-      });
+      res.send(
+        buildStatusPayload(
+          { connectedUsers: lockService.connectedUsers },
+          devServerStatus,
+        ),
+      );
     } else {
-      res.send({
-        connectedUsers: [],
-      });
+      res.send(buildStatusPayload({ connectedUsers: [] }, devServerStatus));
     }
   });
 

package/src/dev-utils/dev-server.status.test.mts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import type { ServerError } from "@superblocksteam/library-shared/types";
+
+// Static import so the slow `dev-server.mjs` module graph (vite, react plugin,
+// workspace deps) loads during file evaluation rather than inside each test,
+// where the cold-import cost easily exceeds the default 5s test timeout.
+import { buildStatusPayload } from "./dev-server.mjs";
+
+describe("buildStatusPayload", () => {
+  it("merges serverErrors from devServerStatus onto the base payload", () => {
+    const installError: ServerError = {
+      type: "dev-server/dependency-install",
+      timestamp: "2026-05-29T00:00:00.000Z",
+      category: "not_in_registry",
+      packages: [{ name: "left-pad" }],
+      rawError: "boom",
+    };
+
+    expect(
+      buildStatusPayload(
+        { connectedUsers: ["a@example.com"] },
+        { serverErrors: [installError] },
+      ),
+    ).toEqual({
+      connectedUsers: ["a@example.com"],
+      serverErrors: [installError],
+    });
+  });
+
+  it("preserves all base fields while adding serverErrors", () => {
+    expect(
+      buildStatusPayload(
+        { status: "healthy", applicationId: "app-1", cliVersion: "1.2.3" },
+        { serverErrors: [] },
+      ),
+    ).toEqual({
+      status: "healthy",
+      applicationId: "app-1",
+      cliVersion: "1.2.3",
+      serverErrors: [],
+    });
+  });
+
+  it("yields an empty serverErrors array when devServerStatus is absent", () => {
+    expect(buildStatusPayload({ connectedUsers: [] })).toEqual({
+      connectedUsers: [],
+      serverErrors: [],
+    });
+  });
+
+  it("yields an empty serverErrors array when devServerStatus.serverErrors is absent", () => {
+    expect(buildStatusPayload({ connectedUsers: [] }, {})).toEqual({
+      connectedUsers: [],
+      serverErrors: [],
+    });
+  });
+});

package/src/dev-utils/token-manager.ts

@@ -2,8 +2,44 @@ import { EventEmitter } from "node:events";
 
 import type { ITokenManager, TokenUpdateEvent } from "@superblocksteam/util";
 
+/**
+ * Holds the active bearer credential and notifies subscribers on change.
+ *
+ * Two access patterns are intentionally supported and serve distinct roles:
+ *
+ *   - `updateToken(t)` writes the current token AND emits `tokenUpdated`.
+ *     The event stream is the **refresh channel**: subscribers (e.g.
+ *     `AutoConnectingRpcClient`, `AiService`) react to changes (e.g. tear
+ *     down a socket and reconnect with the new credential).
+ *
+ *   - `getCurrentToken()` returns the most recently set token, or
+ *     `undefined` if none. This is the **seed channel**: consumers that
+ *     need a bearer credential at construction time read it directly.
+ *     Without this, a consumer whose listener is attached *after* a prior
+ *     `updateToken()` would silently observe nothing — Node `EventEmitter`
+ *     has no replay. Closes the cold-start gap for `NpmRegistryClient`
+ *     when the CLI primes the manager from `tokenConfig.token` at startup.
+ *
+ * Events are deliberately NOT auto-replayed on `on(...)`: a fresh
+ * subscriber receives only future emissions. Auto-replay would make a
+ * late-attached refresh handler (e.g. one that closes and reconnects a
+ * socket) fire on what is conceptually a seed read, producing spurious
+ * tear-down/reconnect churn.
+ *
+ * The current implementation does not surface a `clearToken()` API.
+ * Today's lifecycle never needs one — a process holds at most one user's
+ * credentials and exits when they log out. Add one if/when a multi-tenant
+ * or in-process re-auth path requires it.
+ */
 export class TokenManager extends EventEmitter implements ITokenManager {
+  private currentToken: string | undefined;
+
   updateToken(newToken: string): void {
+    this.currentToken = newToken;
     this.emit("tokenUpdated", { token: newToken } as TokenUpdateEvent);
   }
+
+  getCurrentToken(): string | undefined {
+    return this.currentToken;
+  }
 }

package/src/telemetry/local-obs.ts

@@ -25,7 +25,7 @@
 
 import { DeploymentTypeEnum } from "@superblocksteam/shared";
 
-const DEFAULT_LOCAL_OTEL_ENDPOINT = "http://localhost:24318";
+const DEFAULT_LOCAL_OTEL_ENDPOINT = "http://localhost:4318";
 const DEFAULT_ML_APP_NAME = "superblocks-ai-code-gen";
 
 export interface LocalObsConfig {

package/src/telemetry/util.ts

@@ -9,7 +9,7 @@ export const SERVICE_NAME = "sdk-dev-server";
  * 1. SUPERBLOCKS_OTEL_COLLECTOR_URL env var (for local obs mode)
  * 2. Superblocks API endpoint derived from base URL
  *
- * When SUPERBLOCKS_OTEL_COLLECTOR_URL is set (e.g., http://localhost:24318),
+ * When SUPERBLOCKS_OTEL_COLLECTOR_URL is set (e.g., http://localhost:4318),
  * telemetry is sent directly to the local OTEL collector.
  *
  * Note: This returns the BASE URL. The telemetry library appends /v1/traces,

package/src/types/scoped-jwt-token-payload.ts

@@ -9,4 +9,5 @@ export interface SuperblocksScopedJwtPayload {
   dir_hash?: string;
   user_email: string;
   user_type: string;
+  app_engine_version?: "1.0" | "2.0";
 }

package/src/version-control.mts

@@ -511,13 +511,15 @@ export async function writeResourceToDisk(
         getApiRepresentation(featureFlags, backendConfig);
 
       // Write the API file(s)
+      const apiPromises: Array<Promise<void>> = [];
       const apiInfo = await writeBackendApi(
         resource,
         backendDirName,
-        [],
+        apiPromises,
         apiRepresentation,
         existingFilePaths,
       );
+      await Promise.all(apiPromises);
       if (apiRepresentation.extractLargeSourceFiles) {
         backendConfig.sourceFiles = apiInfo.sourceFiles;
       }
@@ -696,7 +698,6 @@ async function writeV1ApplicationToDisk(
     }
   }
 
-  const appApis: Record<string, ApiInfo> = {};
   if (resource.apis && resource.apis.length) {
     for (const api of resource.apis as ApiWrapper[]) {
       const apiInfo = await writeAppApi(
@@ -719,11 +720,12 @@ async function writeV1ApplicationToDisk(
         newApplicationConfig.apis[apiId] = apiInfo.name;
       }
     }
-    await Promise.all(apiPromises);
   }
-  if (apiRepresentation.extractLargeSourceFiles) {
-    newApplicationConfig.appApis = appApis;
-  } else if (!newApplicationConfig.apis) {
+  await Promise.all(apiPromises);
+  if (
+    !apiRepresentation.extractLargeSourceFiles &&
+    !newApplicationConfig.apis
+  ) {
     // Make sure there is an empty object even if there are no APIs
     newApplicationConfig.apis = {};
   }