@superblocksteam/sdk 2.0.151 → 2.0.152-next.0

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

@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { devServerMetrics as DevServerMetricsSingleton } from "./dev-server-metrics.mjs";
+
+/**
+ * Dependency-failure counter emission tests.
+ *
+ * These assert on what the COUNTER receives, not on what the recorder method
+ * was called with. That distinction is the whole point of this file: an earlier
+ * revision of `recordUpgradeFailure` accepted an `outcome` argument and passed
+ * it down, but the shared `recordDependencyFailure` helper rebuilt its own
+ * `labels` object from a fixed destructure — so `outcome` was silently dropped
+ * on the way to `counter.add()`. A test that spies on `recordUpgradeFailure`
+ * passes against that bug; only a test that listens at the meter boundary
+ * catches it.
+ *
+ * The fake meter is captured at `getMeter()`, mirroring
+ * `dev-server-metrics.boot.test.mts`. The only substitutions are the two
+ * telemetry-bootstrap boundaries the module depends on
+ * (`isTelemetryInitialized`, `getMeter`).
+ */
+
+type Add = { name: string; value: number; attrs: Record<string, unknown> };
+
+const h = vi.hoisted((): { adds: Add[]; telemetryUp: boolean } => ({
+  adds: [],
+  telemetryUp: true,
+}));
+
+vi.mock("@superblocksteam/telemetry", () => ({
+  isTelemetryInitialized: () => h.telemetryUp,
+}));
+
+vi.mock("../telemetry/index.js", () => ({
+  getMeter: () => ({
+    createCounter: (name: string) => ({
+      add: (value: number, attrs: Record<string, unknown>) =>
+        h.adds.push({ name, value, attrs }),
+    }),
+    createHistogram: () => ({ record: () => {} }),
+  }),
+}));
+
+const addsFor = (name: string) => h.adds.filter((a) => a.name === name);
+const UPGRADE_COUNTER = "dev_server_auto_upgrade_failure_total";
+const INSTALL_COUNTER = "dev_server_initial_install_failure_total";
+
+describe("devServerMetrics dependency-failure counters", () => {
+  let devServerMetrics: typeof DevServerMetricsSingleton;
+
+  beforeEach(async () => {
+    h.adds = [];
+    h.telemetryUp = true;
+    vi.resetModules();
+    ({ devServerMetrics } = await import("./dev-server-metrics.mjs"));
+  });
+
+  it("puts `outcome` on the auto-upgrade counter the exporter actually sees", () => {
+    devServerMetrics.recordUpgradeFailure({
+      category: "unknown",
+      npmErrorCode: "ETARGET",
+      hasAnyRegistryConfigured: true,
+      outcome: "exit",
+    });
+
+    const upgrades = addsFor(UPGRADE_COUNTER);
+    expect(upgrades).toHaveLength(1);
+    expect(upgrades[0].value).toBe(1);
+    expect(upgrades[0].attrs).toEqual({
+      category: "unknown",
+      npm_error_code: "ETARGET",
+      has_any_registry_configured: "true",
+      outcome: "exit",
+    });
+  });
+
+  it("distinguishes the degrade outcome from the exit outcome on the counter", () => {
+    devServerMetrics.recordUpgradeFailure({
+      category: "registry_unreachable",
+      outcome: "degrade",
+    });
+
+    const upgrades = addsFor(UPGRADE_COUNTER);
+    expect(upgrades).toHaveLength(1);
+    expect(upgrades[0].attrs).toMatchObject({ outcome: "degrade" });
+  });
+
+  it("omits `outcome` entirely when the caller did not supply one", () => {
+    // A missing outcome must not mint an `outcome: undefined` facet — an
+    // undefined attribute value is not the same series as no attribute.
+    devServerMetrics.recordUpgradeFailure({ category: "tls_failed" });
+
+    const upgrades = addsFor(UPGRADE_COUNTER);
+    expect(upgrades).toHaveLength(1);
+    expect(upgrades[0].attrs).not.toHaveProperty("outcome");
+  });
+
+  it("keeps the initial-install counter's label set unchanged (no `outcome`)", () => {
+    // The install path has no exit/degrade split, so adding an empty `outcome`
+    // facet there would split the existing series for no diagnostic gain.
+    devServerMetrics.recordInitialInstallFailure({
+      category: "dependency_conflict",
+      npmErrorCode: "ERESOLVE",
+      hasAnyRegistryConfigured: false,
+    });
+
+    const installs = addsFor(INSTALL_COUNTER);
+    expect(installs).toHaveLength(1);
+    expect(installs[0].attrs).toEqual({
+      category: "dependency_conflict",
+      npm_error_code: "ERESOLVE",
+      has_any_registry_configured: "false",
+    });
+  });
+
+  it("still bounds npm_error_code and has_any_registry_configured with `outcome` present", () => {
+    devServerMetrics.recordUpgradeFailure({
+      category: "unknown",
+      npmErrorCode: "`;rm -rf /#",
+      outcome: "exit",
+    });
+
+    const upgrades = addsFor(UPGRADE_COUNTER);
+    expect(upgrades[0].attrs).toEqual({
+      category: "unknown",
+      npm_error_code: "other",
+      has_any_registry_configured: "unknown",
+      outcome: "exit",
+    });
+  });
+
+  it("replays a buffered upgrade failure with its `outcome` intact", () => {
+    // The exit path records while telemetry may still be down; the label has to
+    // survive the buffer round-trip, not just the direct call.
+    h.telemetryUp = false;
+    devServerMetrics.recordUpgradeFailure({
+      category: "unknown",
+      outcome: "exit",
+    });
+    expect(addsFor(UPGRADE_COUNTER)).toHaveLength(0);
+
+    h.telemetryUp = true;
+    devServerMetrics.flush();
+
+    const upgrades = addsFor(UPGRADE_COUNTER);
+    expect(upgrades).toHaveLength(1);
+    expect(upgrades[0].attrs).toMatchObject({ outcome: "exit" });
+  });
+});

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

@@ -414,6 +414,15 @@ class DevServerMetrics {
    *   - `npm_error_code` is a bounded npm error code string (e.g. "E401",
    *     "ERESOLVE") or `"none"` when absent.
    *   - `has_any_registry_configured` is `"true"` / `"false"` / `"unknown"`.
+   *   - `outcome`, when the caller supplies one, is a closed enum owned by that
+   *     caller (see `recordUpgradeFailure`).
+   *
+   * Every label a caller passes must be destructured here AND placed into
+   * `labels`. This helper is the only thing that reaches `counter.add`, so a
+   * field accepted by a public wrapper but omitted here is silently dropped on
+   * the way to the exporter — and TypeScript cannot catch it, because `labels`
+   * is a typed variable rather than a fresh object literal at the call site.
+   * That is exactly how `outcome` went missing.
    *
    * Do NOT pass raw package names, registry hostnames, or rawError — those are
    * high-cardinality or contain customer-infra identifiers.
@@ -425,10 +434,12 @@ class DevServerMetrics {
       category,
       npmErrorCode,
       hasAnyRegistryConfigured,
+      outcome,
     }: {
       category: string;
       npmErrorCode?: string;
       hasAnyRegistryConfigured?: boolean;
+      outcome?: string;
     },
   ): void {
     const labels = {
@@ -438,6 +449,11 @@ class DevServerMetrics {
         hasAnyRegistryConfigured === undefined
           ? "unknown"
           : String(hasAnyRegistryConfigured),
+      // Spread conditionally rather than assigning `outcome` directly: the
+      // initial-install counter has no exit/degrade split, and emitting an
+      // `outcome: undefined` attribute there would fork its existing series
+      // for no diagnostic gain.
+      ...(outcome === undefined ? {} : { outcome }),
     };
     this.record(() => {
       getMeter().createCounter(counterName, { description }).add(1, labels);
@@ -463,10 +479,18 @@ class DevServerMetrics {
     category: string;
     npmErrorCode?: string;
     hasAnyRegistryConfigured?: boolean;
+    /**
+     * What the failure did to this process: `degrade` kept the current version
+     * running, `exit` terminated so the sandbox is replaced. Without this the
+     * two outcomes are indistinguishable, so a crash-loop of exiting pods looks
+     * identical to a fleet of pods quietly serving the older version.
+     * Low-cardinality: a closed two-value enum.
+     */
+    outcome?: "degrade" | "exit";
   }): void {
     this.recordDependencyFailure(
       "dev_server_auto_upgrade_failure_total",
-      "Count of degraded dev-server startups where a best-effort CLI/library auto-upgrade failed and the pod kept the current version.",
+      "Count of dev-server startups where a best-effort CLI/library auto-upgrade failed, labelled by outcome: `degrade` (kept the current version) or `exit` (terminated so the sandbox is replaced).",
       labels,
     );
   }

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

@@ -90,6 +90,36 @@ export function getDevServerTracer() {
   return getTracer();
 }
 
+/**
+ * Every `/_sb_*` control endpoint, keyed by its low-cardinality metrics label.
+ * The request path is always `/` + the label.
+ *
+ * The value is why the endpoint must answer even when Vite is not up, which
+ * exempts it from the "hold the request until Vite is initialized" middleware,
+ * or null when the endpoint is held like ordinary traffic. Typed as an
+ * exhaustive `Record` over `DevServerEndpoint`, so an endpoint cannot be added
+ * without declaring its hold behavior. Both `endpointForUrl` and
+ * `isDevServerControlPath` read this table, so the metrics label and the
+ * exemption cannot drift apart.
+ */
+const DEV_SERVER_ENDPOINTS: Readonly<Record<DevServerEndpoint, string | null>> =
+  {
+    _sb_activate: null,
+    _sb_activity: "idle-reaper poll; reads the activity tracker, not Vite",
+    _sb_connect: "carries the Vite init failure the editor surfaces",
+    _sb_disconnect: "teardown has to work when Vite never came up",
+    _sb_health:
+      "the editor gates page load on it; holding it hides the failure",
+    _sb_persist: "archives the workspace off disk; never touches Vite",
+    _sb_ready: null,
+    _sb_status: "reports serverErrors, which only matter once Vite failed",
+    _sb_update_token: null,
+  };
+
+function isDevServerEndpoint(label: string): label is DevServerEndpoint {
+  return Object.hasOwn(DEV_SERVER_ENDPOINTS, label);
+}
+
 /**
  * Maps a dev-server request URL onto a low-cardinality endpoint label for
  * metrics. Returns undefined for non-`/_sb_*` URLs (Vite-proxied traffic).
@@ -99,28 +129,22 @@ function endpointForUrl(
 ): DevServerEndpoint | undefined {
   if (!url) return undefined;
   const path = url.split("?", 1)[0];
-  switch (path) {
-    case "/_sb_health":
-      return "_sb_health";
-    case "/_sb_connect":
-      return "_sb_connect";
-    case "/_sb_activate":
-      return "_sb_activate";
-    case "/_sb_disconnect":
-      return "_sb_disconnect";
-    case "/_sb_status":
-      return "_sb_status";
-    case "/_sb_activity":
-      return "_sb_activity";
-    case "/_sb_update_token":
-      return "_sb_update_token";
-    case "/_sb_persist":
-      return "_sb_persist";
-    case "/_sb_ready":
-      return "_sb_ready";
-    default:
-      return undefined;
-  }
+  if (!path.startsWith("/")) return undefined;
+  const label = path.slice(1);
+  return isDevServerEndpoint(label) ? label : undefined;
+}
+
+/**
+ * True when a request must be answered even if Vite never initialized, so the
+ * hold middleware lets it through. `DEV_SERVER_ENDPOINTS` says which endpoints
+ * qualify and why.
+ *
+ * Compares the path, not the raw URL: the editor polls `/_sb_health?t=<epoch>`
+ * with a cache-buster, so a raw-URL comparison drops that poll into the hold.
+ */
+export function isDevServerControlPath(url: string | undefined): boolean {
+  const endpoint = endpointForUrl(url);
+  return endpoint !== undefined && DEV_SERVER_ENDPOINTS[endpoint] !== null;
 }
 
 /**
@@ -911,13 +935,7 @@ export async function createDevServer({
     res.setHeader("Cache-Control", "no-store, max-age=0");
     res.setHeader("x-csb-no-sw-proxy", "1");
 
-    if (
-      req.url === "/_sb_connect" ||
-      req.url === "/_sb_disconnect" ||
-      req.url === "/_sb_health" ||
-      req.url === "/_sb_status" ||
-      req.url === "/_sb_activity"
-    ) {
+    if (isDevServerControlPath(req.url)) {
       return next();
     }
 
@@ -1441,6 +1459,10 @@ export async function createDevServer({
           featureFlags?.inPlaceTemplateRestartEnabled(),
           "SUPERBLOCKS_DEV_SERVER_IN_PLACE_TEMPLATE_RESTART_ENABLED",
         ),
+        autoCommitCheckpointsToGitEnabled: flagOrEnv(
+          featureFlags?.removeManualCommitsEnabled(),
+          "SUPERBLOCKS_REMOVE_MANUAL_COMMITS_ENABLED",
+        ),
       },
     });
     // Note: vitePromise itself gets a no-op .catch() at its construction site
@@ -1517,6 +1539,7 @@ async function startVite({
   features: {
     enableSessionRecording: boolean;
     inPlaceTemplateRestartEnabled: boolean;
+    autoCommitCheckpointsToGitEnabled: boolean;
   };
   prepareInPlaceRestart: (options?: { flipRestart?: true }) => Promise<void>;
 }): Promise<{

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

@@ -10,6 +10,7 @@ import {
   buildStatusPayload,
   DEV_SERVER_BOOT_ID,
   DEV_SERVER_STARTED_AT,
+  isDevServerControlPath,
 } from "./dev-server.mjs";
 
 describe("buildStatusPayload", () => {
@@ -90,3 +91,44 @@ describe("buildHealthResponse", () => {
     expect(health.startedAt).toBe(DEV_SERVER_STARTED_AT);
   });
 });
+
+describe("isDevServerControlPath", () => {
+  it.each([
+    "/_sb_connect",
+    "/_sb_disconnect",
+    "/_sb_health",
+    "/_sb_status",
+    "/_sb_activity",
+    "/_sb_persist",
+  ])("treats %s as a control path", (url) => {
+    expect(isDevServerControlPath(url)).toBe(true);
+  });
+
+  it.each(["/_sb_activate", "/_sb_ready", "/_sb_update_token"])(
+    "leaves %s subject to the vite hold",
+    (url) => {
+      expect(isDevServerControlPath(url)).toBe(false);
+    },
+  );
+
+  it("treats a control path carrying a query string as a control path", () => {
+    expect(isDevServerControlPath("/_sb_health?t=1785959985730")).toBe(true);
+    expect(isDevServerControlPath("/_sb_connect?foo=bar&baz=1")).toBe(true);
+    expect(isDevServerControlPath("/_sb_persist?t=1")).toBe(true);
+  });
+
+  it("does not claim vite-proxied traffic", () => {
+    expect(isDevServerControlPath("/src/main.tsx")).toBe(false);
+    expect(isDevServerControlPath("/_sb_healthcheck")).toBe(false);
+    expect(isDevServerControlPath("/_sb_health/extra")).toBe(false);
+    expect(isDevServerControlPath(undefined)).toBe(false);
+  });
+
+  // The lookup is by object key, so Object.prototype members must not match.
+  it.each(["/toString", "/constructor", "/hasOwnProperty", "/__proto__"])(
+    "does not treat %s as a control path",
+    (url) => {
+      expect(isDevServerControlPath(url)).toBe(false);
+    },
+  );
+});

package/src/dev-utils/fatal-exit.mts

@@ -25,9 +25,10 @@
  * `handler=containerExit` line for the same exit. A signal kill / OOM emits only
  * the `containerExit` line (no JS handler ran); a JS crash where shutdown exits
  * first with code 0 emits only the JS-handler line (the supervisor sees a clean
- * exit). So a raw `count(event=dev_server_fatal_exit)` over-counts the double
- * case: deduplicate by pod within a short time window for a true unique-crash
- * count.
+ * exit). A deliberate startup exit emits `handler=startupFailure` from the child
+ * plus the supervisor's `containerExit` line, i.e. the same double shape. So a
+ * raw `count(event=dev_server_fatal_exit)` over-counts the double case:
+ * deduplicate by pod within a short time window for a true unique-crash count.
  *
  * Signal-kill field note: for a signal kill the cold parent emits
  * `exit_code=null signal=SIGKILL` (Node's `child.on("exit")` gives a null code +
@@ -49,11 +50,24 @@
  *                                           and the warm entrypoint shell emit this
  *                                           value. They cannot import this module,
  *                                           so they repeat the same string.
+ *   startupFailure                          `dev()` decided at startup that it
+ *                                           cannot serve (sync/lock/setup failure,
+ *                                           or a dependency upgrade that may have
+ *                                           tainted the live tree in a disposable
+ *                                           sandbox) and is exiting deliberately.
+ *                                           No JS error handler is involved; the
+ *                                           adjacent `[dev-server] Startup failed
+ *                                           during …` line names the stage.
+ *
+ * Adding a VALUE here (as `startupFailure` was) needs no change in the two
+ * emitters that cannot import this module — they each emit their own fixed
+ * value. Only adding a FIELD does; see the SYNC note on `buildFatalExitLog`.
  */
 type FatalExitHandler =
   | "uncaughtException"
   | "unhandledRejection"
-  | "containerExit";
+  | "containerExit"
+  | "startupFailure";
 
 /** Fixed token so a log-based metric or a log search can pick out these lines. */
 export const FATAL_EXIT_EVENT = "dev_server_fatal_exit";

package/src/extract-api-integrations.mts

@@ -1,5 +1,8 @@
 export {
+  extractApiIntegrations,
   extractIntegrationIdsFromSource,
   extractIntegrationsFromSource,
+  resolveRelativeImportPath,
+  type ExtractApiIntegrationsResult,
   type IntegrationInfo,
 } from "@superblocksteam/vite-plugin-file-sync/extract-api-integrations";

package/src/flag.test.ts

@@ -41,6 +41,27 @@ describe("flagOrEnv", () => {
   });
 });
 
+describe("FeatureFlags.removeManualCommitsEnabled", () => {
+  it("defaults to false when the flag is absent", () => {
+    const flags = new FeatureFlags({});
+    expect(flags.removeManualCommitsEnabled()).toBe(false);
+  });
+
+  it("returns true when the flag is enabled", () => {
+    const flags = new FeatureFlags({
+      "superblocks.remove-manual-commits.enabled": true,
+    });
+    expect(flags.removeManualCommitsEnabled()).toBe(true);
+  });
+
+  it("returns false when the flag is explicitly disabled", () => {
+    const flags = new FeatureFlags({
+      "superblocks.remove-manual-commits.enabled": false,
+    });
+    expect(flags.removeManualCommitsEnabled()).toBe(false);
+  });
+});
+
 describe("FeatureFlags.inPlaceTemplateRestartEnabled", () => {
   it("defaults to false when the flag is absent", () => {
     const flags = new FeatureFlags({});

package/src/flag.ts

@@ -59,6 +59,14 @@ export class FeatureFlags {
     return this.flags["superblocks.dev-server.memory-metrics.enabled"] ?? false;
   }
 
+  /**
+   * Gates the unified version history work. While off, autosave keeps its
+   * original fixed-window cadence so dev servers behave exactly as before.
+   */
+  removeManualCommitsEnabled(): boolean {
+    return this.flags["superblocks.remove-manual-commits.enabled"] ?? false;
+  }
+
   /**
    * Gates the in-place dev-server process restart after a v2->v3 template
    * flip. When enabled (and a restart supervisor is present), the

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   type UpdateOrgBillingUsageLimitRequest,
   type UpdateUserBillingUsageLimitRequest,
   type UserCreditLimit,
+  type UsageGroupRow,
   type UsageRecordRow,
 } from "./client.js";
 

package/src/types/common.ts

@@ -20,6 +20,7 @@ export interface FlagBootstrap {
   "superblocks.dev-server.memory-metrics.enabled"?: boolean;
   "superblocks.dev-server.in-place-template-restart.enabled"?: boolean;
   "superblocks.deploy.include-dot-superblocks"?: boolean;
+  "superblocks.remove-manual-commits.enabled"?: boolean;
 }
 
 export interface TokenConfig {

package/src/vite-plugin-generate-api-build-manifest.mts

@@ -17,6 +17,7 @@ import {
 
 import { collectSdkApisFromRegistry } from "./collect-sdk-apis.mjs";
 import { getLogger } from "./telemetry/logging.js";
+import type { Logger } from "./telemetry/logging.js";
 
 const BUILD_MANIFEST_SUFFIX = path.join(
   "lib",
@@ -35,6 +36,32 @@ function isBuildManifestModule(id: string): boolean {
   );
 }
 
+/**
+ * Emits a structured WARN when the logger supports it, falling back to a
+ * plain `warn` with just the human-readable message otherwise.
+ * `warnStructured` is optional on the `Logger` type (future/alternate
+ * implementations may omit it), so calling it with `?.` alone would let an
+ * auth-relevant warning disappear silently on such a logger. Both call
+ * sites in this plugin route through here instead of duplicating the
+ * fallback branch.
+ *
+ * `message` must be the plain, uncolored text — it becomes the OTel log
+ * body when `warnStructured` is available, and ANSI escapes have no place
+ * in a structured body. Coloring is applied only in the console-facing
+ * fallback branch below.
+ */
+function warnStructured(
+  logger: Logger,
+  message: string,
+  attributes: Record<string, string | number | boolean>,
+): void {
+  if (logger.warnStructured) {
+    logger.warnStructured(message, attributes);
+  } else {
+    logger.warn(yellow(message));
+  }
+}
+
 /**
  * Vite plugin that generates a build manifest for the application.
  *
@@ -108,10 +135,53 @@ export function generateApiBuildManifestPlugin(root: string) {
       );
 
       const sdkApis = sdkApiEnabled
-        ? await collectSdkApisFromRegistry(root, {
-            pathExists: (p) => fs.pathExists(p),
-            readFile: (p, enc) => fs.readFile(p, enc),
-          })
+        ? await collectSdkApisFromRegistry(
+            root,
+            {
+              pathExists: (p) => fs.pathExists(p),
+              readFile: (p, enc) => fs.readFile(p, enc),
+              realpath: (p) => fs.realpath(p),
+            },
+            {
+              onUnresolvedIntegrations: (
+                apiName,
+                entryPoint,
+                unresolvedKeys,
+              ) => {
+                warnStructured(
+                  logger,
+                  `[superblocks] Could not resolve integration(s) ${unresolvedKeys
+                    .map((k) => `"${k}"`)
+                    .join(
+                      ", ",
+                    )} declared in ${entryPoint} (API "${apiName}") — check-auth may be skipped for this API in deployed/preview mode. Declare the integration or its ID in the same file.`,
+                  {
+                    // Bounded/numeric only — api name, entry point, and the
+                    // unresolved keys themselves are free-form text and stay
+                    // in the message body (searchable, not faceted) to keep
+                    // OTel log attribute cardinality low. See the
+                    // `LogAttributes` doc comment in ./telemetry/logging.ts.
+                    "sdk.integrations.unresolved_count": unresolvedKeys.length,
+                  },
+                );
+              },
+              onExtractionError: (apiName, entryPoint, error) => {
+                const errorMessage =
+                  error instanceof Error ? error.message : String(error);
+                warnStructured(
+                  logger,
+                  `[superblocks] Failed to extract integrations from ${entryPoint} (API "${apiName}"): ${errorMessage} — check-auth may be skipped for this API in deployed/preview mode.`,
+                  {
+                    // Bounded constant only — api name, entry point, and the
+                    // raw error message are free-form text and stay in the
+                    // message body. See the `LogAttributes` doc comment in
+                    // ./telemetry/logging.ts.
+                    "sdk.extraction.error_category": "read_or_extract_failed",
+                  },
+                );
+              },
+            },
+          )
         : {};
 
       manifestCode = `export default ${JSON.stringify({