@superblocksteam/sdk 2.0.130-next.2 → 2.0.130-next.4

package/src/cli-replacement/disk-space.mts

@@ -0,0 +1,216 @@
+import nodeFs from "node:fs/promises";
+import path from "node:path";
+
+/** Minimal logger surface so this helper stays decoupled from the winston
+ *  instance threaded through `dev.mts` (and trivially fakeable in tests). */
+export interface ReclaimLogger {
+  info: (message: string, meta?: unknown) => void;
+  warn: (message: string, meta?: unknown) => void;
+}
+
+export interface DiskSpace {
+  totalBytes: number;
+  freeBytes: number;
+  usedBytes: number;
+  /** Whole-number percent of the volume in use (0–100). */
+  percentUsed: number;
+}
+
+/** ENOSPC ("no space left on device") signature. npm surfaces a disk-full
+ *  failure as a structured `code: "ENOSPC"` (under `--json`), a raw
+ *  `errno -28`, or the kernel string — match all three. Centralised here (the
+ *  disk domain) so both the install classifier and the recovery escalation
+ *  gate agree on what "still out of space" means. */
+export const DISK_FULL_PATTERN =
+  /\bENOSPC\b|no space left on device|\berrno -28\b/i;
+
+/** The error shape `util.promisify(exec)` rejects with (stdout/stderr/message
+ *  preserved separately). */
+export interface ExecLikeFailure {
+  stdout?: string;
+  stderr?: string;
+  message?: string;
+}
+
+/** True when an exec-style failure looks like a disk-full (ENOSPC) error. */
+export function isDiskFullError(failure: ExecLikeFailure): boolean {
+  const text = `${failure.stdout ?? ""}\n${failure.stderr ?? ""}\n${failure.message ?? ""}`;
+  return DISK_FULL_PATTERN.test(text);
+}
+
+/** Best-effort `df` for the filesystem backing `dir`. Returns `undefined` if
+ *  the path can't be statfs'd (missing dir, unsupported platform) — callers
+ *  treat disk telemetry as advisory and must never fail an install over it. */
+export async function getDiskSpace(
+  dir: string,
+): Promise<DiskSpace | undefined> {
+  try {
+    const s = await nodeFs.statfs(dir);
+    const totalBytes = s.blocks * s.bsize;
+    // `bavail` = blocks free to an unprivileged process — the number that
+    // actually governs whether npm can keep writing (vs `bfree`, which counts
+    // root-reserved blocks the install can't touch).
+    const freeBytes = s.bavail * s.bsize;
+    const usedBytes = Math.max(0, totalBytes - freeBytes);
+    const percentUsed =
+      totalBytes > 0 ? Math.round((usedBytes / totalBytes) * 100) : 0;
+    return { totalBytes, freeBytes, usedBytes, percentUsed };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Regenerable artifacts that are safe to delete to recover from an ENOSPC:
+ *  every entry is rebuilt on the next dev-server start / Vite optimize pass.
+ *  This list MUST NOT contain source files, app config, or user drafts —
+ *  reclaim is composition-agnostic (delete whatever exists) precisely because
+ *  it only ever touches throwaway build output. `node_modules` is deliberately
+ *  excluded here and gated behind `includeNodeModules` (tier 2). */
+export const RECLAIMABLE_ARTIFACTS: readonly string[] = [
+  ".turbo",
+  ".vite",
+  "build",
+  "dist",
+  "node_modules/.cache",
+  "node_modules/.vite",
+];
+
+export interface ReclaimResult {
+  /** Bytes reclaimed, measured as the increase in filesystem free space across
+   *  the deletions (a `statfs` delta). O(1) — deliberately NOT a directory walk:
+   *  sizing a real `node_modules` (50k–200k files) on an already-ENOSPC volume
+   *  could block recovery for minutes just to produce an advisory number. */
+  bytesFreed: number;
+  /** cwd-relative paths that existed and were deleted (for telemetry). */
+  removed: string[];
+}
+
+export interface ReclaimOptions {
+  /** Also remove `node_modules` — the tier-2 lever. After an ENOSPC mid-
+   *  install the tree is half-written anyway, so a clean reinstall is the
+   *  correct recovery AND it collapses the "old tree + new tree" 2× peak that
+   *  the private-registry validation install otherwise holds on the volume. */
+  includeNodeModules?: boolean;
+}
+
+/** Cheap, non-recursive existence check (single `stat`, no tree walk). */
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await nodeFs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Delete regenerable build artifacts under `cwd` to recover space after an
+ *  ENOSPC. Strictly scoped to `cwd`, best-effort (a failure on one target
+ *  never aborts the rest), and safe to call unconditionally.
+ *
+ *  NOTE: `cwd` is always the Superblocks-managed app directory (the live-edit
+ *  PVC mount). The bare `build`/`dist` entries in `RECLAIMABLE_ARTIFACTS` are
+ *  only safe under that invariant; never call this against an arbitrary or
+ *  user-supplied path. */
+export async function reclaimDiskSpace(
+  cwd: string,
+  logger: ReclaimLogger,
+  options: ReclaimOptions = {},
+): Promise<ReclaimResult> {
+  const targets = [...RECLAIMABLE_ARTIFACTS];
+  if (options.includeNodeModules) targets.push("node_modules");
+
+  const before = await getDiskSpace(cwd);
+  const removed: string[] = [];
+
+  for (const rel of targets) {
+    const abs = path.join(cwd, rel);
+    if (!(await pathExists(abs))) continue; // nothing to reclaim
+    try {
+      await nodeFs.rm(abs, { recursive: true, force: true });
+      removed.push(rel);
+    } catch (err) {
+      logger.warn(`Could not reclaim ${rel} during disk recovery`, {
+        error: String(err),
+      });
+    }
+  }
+
+  const after = await getDiskSpace(cwd);
+  const bytesFreed =
+    before && after ? Math.max(0, after.freeBytes - before.freeBytes) : 0;
+
+  return { bytesFreed, removed };
+}
+
+export interface DiskRecoveryResult {
+  recovered: boolean;
+  /** The error from the final failed install attempt, when recovery failed —
+   *  so the caller can reclassify it for the most accurate surfaced error. */
+  lastError?: unknown;
+}
+
+/** Recover from an ENOSPC install failure by reclaiming disk space in
+ *  escalating tiers and retrying the install after each:
+ *
+ *    Tier 1 — regenerable build caches only (cheap, non-destructive).
+ *    Tier 2 — also `node_modules` (a clean reinstall: collapses the
+ *             "old tree + new tree" 2× peak and discards the half-written
+ *             tree the ENOSPC left behind).
+ *
+ *  `runInstall` re-runs the exact same install the caller already attempted.
+ *  Returns `{ recovered: true }` as soon as a retry succeeds; otherwise
+ *  `{ recovered: false, lastError }` so the caller surfaces an honest
+ *  disk_full error. Every tier's `df` + freed bytes are logged so a future
+ *  ENOSPC documents its own volume composition — the only way to inspect a
+ *  live-edit PVC that `reclaimPolicy: Delete` destroys at teardown. */
+export async function recoverFromDiskFull(
+  cwd: string,
+  runInstall: () => Promise<unknown>,
+  logger: ReclaimLogger,
+): Promise<DiskRecoveryResult> {
+  logger.warn(
+    `Package install hit ENOSPC; attempting disk recovery [marker=DEV_SERVER_DISK_RECOVERY] cwd=${cwd}`,
+    { disk: await getDiskSpace(cwd) },
+  );
+
+  const tiers: { name: string; options: ReclaimOptions }[] = [
+    { name: "caches", options: {} },
+    { name: "node_modules", options: { includeNodeModules: true } },
+  ];
+
+  let lastError: unknown;
+  for (const tier of tiers) {
+    const { bytesFreed, removed } = await reclaimDiskSpace(
+      cwd,
+      logger,
+      tier.options,
+    );
+    logger.info(
+      `Disk recovery tier '${tier.name}' freed ${bytesFreed} bytes [marker=DEV_SERVER_DISK_RECOVERY removed=${removed.join("|") || "nothing"}]`,
+      { disk: await getDiskSpace(cwd), removed, bytesFreed },
+    );
+    try {
+      await runInstall();
+      logger.info(
+        `Package install succeeded after disk recovery tier '${tier.name}'`,
+      );
+      return { recovered: true };
+    } catch (err) {
+      lastError = err;
+      // Only escalate to the next (more destructive) tier if we are STILL out
+      // of space. A non-ENOSPC failure means the disk problem is resolved and a
+      // different error surfaced (e.g. a registry/dependency error now that the
+      // caches are gone); escalating would delete a usable node_modules for no
+      // reason and leave the app worse off. Stop and surface this error.
+      if (!isDiskFullError(err as ExecLikeFailure)) {
+        logger.warn(
+          `Disk recovery retry after tier '${tier.name}' failed with a non-ENOSPC error; not escalating [marker=DEV_SERVER_DISK_RECOVERY]`,
+          { error: String(err) },
+        );
+        break;
+      }
+    }
+  }
+
+  return { recovered: false, lastError };
+}

package/src/cli-replacement/disk-space.test.mts

@@ -0,0 +1,246 @@
+import nodeFs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  getDiskSpace,
+  reclaimDiskSpace,
+  recoverFromDiskFull,
+} from "./disk-space.mjs";
+
+const silentLogger = { info: vi.fn(), warn: vi.fn() };
+
+async function writeFile(p: string, bytes: number): Promise<void> {
+  await nodeFs.mkdir(path.dirname(p), { recursive: true });
+  await nodeFs.writeFile(p, Buffer.alloc(bytes, "x"));
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await nodeFs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe("reclaimDiskSpace", () => {
+  let cwd: string;
+
+  beforeEach(async () => {
+    cwd = await nodeFs.mkdtemp(path.join(os.tmpdir(), "reclaim-test-"));
+  });
+
+  afterEach(async () => {
+    await nodeFs.rm(cwd, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it("deletes regenerable build artifacts, leaving source and node_modules intact", async () => {
+    await writeFile(path.join(cwd, ".vite", "deps", "chunk.js"), 1000);
+    await writeFile(path.join(cwd, "dist", "bundle.js"), 500);
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+    await writeFile(path.join(cwd, "src", "App.tsx"), 42);
+
+    const result = await reclaimDiskSpace(cwd, silentLogger);
+
+    // Regenerable artifacts are gone…
+    expect(await exists(path.join(cwd, ".vite"))).toBe(false);
+    expect(await exists(path.join(cwd, "dist"))).toBe(false);
+    // …source and the dependency tree survive by default.
+    expect(await exists(path.join(cwd, "src", "App.tsx"))).toBe(true);
+    expect(await exists(path.join(cwd, "node_modules"))).toBe(true);
+
+    expect(result.removed).toContain(".vite");
+    expect(result.removed).toContain("dist");
+    expect(result.removed).not.toContain("node_modules");
+    expect(result.bytesFreed).toBeGreaterThanOrEqual(0);
+  });
+
+  it("removes node_modules too when includeNodeModules is set (the tier-2 lever)", async () => {
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+    await writeFile(path.join(cwd, "src", "App.tsx"), 42);
+
+    const result = await reclaimDiskSpace(cwd, silentLogger, {
+      includeNodeModules: true,
+    });
+
+    expect(await exists(path.join(cwd, "node_modules"))).toBe(false);
+    expect(await exists(path.join(cwd, "src", "App.tsx"))).toBe(true);
+    expect(result.removed).toContain("node_modules");
+  });
+
+  it("reports bytesFreed as the statfs free-space delta (no directory walk)", async () => {
+    await writeFile(path.join(cwd, ".vite", "dep.js"), 100);
+    const baseStatfs = {
+      type: 0,
+      bsize: 4096,
+      blocks: 1000,
+      bfree: 200,
+      bavail: 100,
+      files: 0,
+      ffree: 0,
+    };
+    const statfsSpy = vi
+      .spyOn(nodeFs, "statfs")
+      .mockResolvedValueOnce({ ...baseStatfs, bavail: 100 }) // before
+      .mockResolvedValueOnce({ ...baseStatfs, bavail: 150 }); // after
+
+    const result = await reclaimDiskSpace(cwd, silentLogger);
+
+    expect(result.removed).toContain(".vite");
+    expect(result.bytesFreed).toBe((150 - 100) * 4096);
+    statfsSpy.mockRestore();
+  });
+
+  it("warns and skips a target whose deletion fails, still removing the others", async () => {
+    await writeFile(path.join(cwd, ".vite", "dep.js"), 100);
+    await writeFile(path.join(cwd, "dist", "bundle.js"), 100);
+    const warn = vi.fn();
+    const rmSpy = vi.spyOn(nodeFs, "rm").mockImplementation((async (
+      p: Parameters<typeof nodeFs.rm>[0],
+    ) => {
+      if (String(p).endsWith(".vite")) throw new Error("EBUSY");
+    }) as typeof nodeFs.rm);
+
+    const result = await reclaimDiskSpace(cwd, { info: vi.fn(), warn });
+
+    expect(result.removed).toContain("dist");
+    expect(result.removed).not.toContain(".vite");
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(".vite"),
+      expect.objectContaining({ error: expect.any(String) }),
+    );
+    rmSpy.mockRestore();
+  });
+
+  it("preserves the npm debug log dir (.superblocks/logs) so the ENOSPC autopsy survives recovery", async () => {
+    // installPackages points NPM_CONFIG_LOGS_DIR at <app>/.superblocks/logs, so
+    // on an ENOSPC this holds npm's debug log of the failure we're diagnosing.
+    await writeFile(
+      path.join(cwd, ".superblocks", "logs", "2026-06-15-debug-0.log"),
+      500,
+    );
+    await writeFile(path.join(cwd, ".vite", "dep.js"), 100);
+
+    const result = await reclaimDiskSpace(cwd, silentLogger, {
+      includeNodeModules: true,
+    });
+
+    expect(await exists(path.join(cwd, ".superblocks", "logs"))).toBe(true);
+    expect(result.removed).not.toContain(".superblocks/logs");
+    // Regenerable caches are still reclaimed.
+    expect(result.removed).toContain(".vite");
+  });
+
+  it("is a no-op (no throw, nothing removed) when there are no regenerable artifacts", async () => {
+    await writeFile(path.join(cwd, "src", "App.tsx"), 42);
+
+    const result = await reclaimDiskSpace(cwd, silentLogger);
+
+    expect(result.removed).toEqual([]);
+    expect(await exists(path.join(cwd, "src", "App.tsx"))).toBe(true);
+  });
+});
+
+describe("recoverFromDiskFull", () => {
+  let cwd: string;
+
+  beforeEach(async () => {
+    cwd = await nodeFs.mkdtemp(path.join(os.tmpdir(), "recover-test-"));
+  });
+
+  afterEach(async () => {
+    await nodeFs.rm(cwd, { recursive: true, force: true });
+    vi.clearAllMocks();
+  });
+
+  it("recovers at tier 1 (caches) without touching node_modules when the retry then succeeds", async () => {
+    await writeFile(path.join(cwd, ".vite", "dep.js"), 1000);
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+
+    const runInstall = vi
+      .fn<() => Promise<string>>()
+      .mockResolvedValueOnce("ok");
+
+    const result = await recoverFromDiskFull(cwd, runInstall, silentLogger);
+
+    expect(result.recovered).toBe(true);
+    // Tier 1 ran (caches cleared)…
+    expect(await exists(path.join(cwd, ".vite"))).toBe(false);
+    // …but tier 2 was never reached, so the dependency tree is preserved.
+    expect(await exists(path.join(cwd, "node_modules"))).toBe(true);
+    expect(runInstall).toHaveBeenCalledTimes(1);
+  });
+
+  it("escalates to tier 2 (node_modules) and recovers when the clean reinstall succeeds", async () => {
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+
+    const runInstall = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("ENOSPC again"))
+      .mockResolvedValueOnce("ok");
+
+    const result = await recoverFromDiskFull(cwd, runInstall, silentLogger);
+
+    expect(result.recovered).toBe(true);
+    expect(await exists(path.join(cwd, "node_modules"))).toBe(false);
+    expect(runInstall).toHaveBeenCalledTimes(2);
+  });
+
+  it("does NOT escalate to tier 2 (preserves node_modules) when the tier-1 retry fails for a non-ENOSPC reason", async () => {
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+    const resolveError = new Error(
+      "npm error code ERESOLVE\nunable to resolve dependency tree",
+    );
+    const runInstall = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(resolveError);
+
+    const result = await recoverFromDiskFull(cwd, runInstall, silentLogger);
+
+    expect(result.recovered).toBe(false);
+    expect(result.lastError).toBe(resolveError);
+    // The disk wasn't the problem on retry, so node_modules must be preserved
+    // rather than destroyed by a needless tier-2 clean reinstall.
+    expect(await exists(path.join(cwd, "node_modules"))).toBe(true);
+    expect(runInstall).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports failure with the last error when even a clean reinstall can't fit", async () => {
+    await writeFile(path.join(cwd, "node_modules", "react", "index.js"), 2000);
+    const finalError = new Error("ENOSPC: no space left on device");
+
+    const runInstall = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("ENOSPC 1"))
+      .mockRejectedValueOnce(finalError);
+
+    const result = await recoverFromDiskFull(cwd, runInstall, silentLogger);
+
+    expect(result.recovered).toBe(false);
+    expect(result.lastError).toBe(finalError);
+    expect(runInstall).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("getDiskSpace", () => {
+  it("returns numeric totals with a sane percentUsed for a real directory", async () => {
+    const space = await getDiskSpace(os.tmpdir());
+    expect(space).toBeDefined();
+    expect(space!.totalBytes).toBeGreaterThan(0);
+    expect(space!.freeBytes).toBeGreaterThanOrEqual(0);
+    expect(space!.usedBytes).toBeGreaterThanOrEqual(0);
+    expect(space!.percentUsed).toBeGreaterThanOrEqual(0);
+    expect(space!.percentUsed).toBeLessThanOrEqual(100);
+  });
+
+  it("returns undefined for a path that cannot be statfs'd", async () => {
+    const space = await getDiskSpace(
+      path.join(os.tmpdir(), "definitely-does-not-exist-xyz", "nested"),
+    );
+    expect(space).toBeUndefined();
+  });
+});

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

@@ -407,6 +407,26 @@ class DevServerMetrics {
         .add(1, labels);
     });
   }
+
+  /**
+   * Records an ENOSPC disk-recovery attempt and its outcome. Lets dashboards
+   * and alerts answer "how often is the live-edit PVC filling up, and is
+   * recovery actually rescuing the install?" without depending on log
+   * ingestion (the PVC is destroyed at teardown, so logs can be lost).
+   *
+   * `recovered` is the only label — bounded cardinality (true/false).
+   */
+  recordDiskRecovery({ recovered }: { recovered: boolean }): void {
+    const labels = { recovered: String(recovered) };
+    this.record(() => {
+      getMeter()
+        .createCounter("dev_server_disk_recovery_total", {
+          description:
+            "Count of ENOSPC disk-recovery attempts during the dev-server initial install, labeled by whether a retry succeeded.",
+        })
+        .add(1, labels);
+    });
+  }
 }
 
 /** Process-wide dev-server metrics singleton. */