@superblocksteam/sdk 2.0.115-next.1 → 2.0.115

package/src/cli-replacement/dev.mts

@@ -58,6 +58,13 @@ import {
   ensureRemoteHasDefaultBranch,
   getGitErrorFields,
 } from "./git-repo-setup.mjs";
+import {
+  didPackageJsonSnapshotChange,
+  packageJsonSnapshot,
+  packageJsonSnapshotDiagnostic,
+  type PackageJsonSnapshot,
+  restoreManagedPackageDependencies,
+} from "./package-json-snapshot.mjs";
 import { getCurrentCliVersion } from "./version-detection.js";
 
 const exec = promisify(child_process.exec);
@@ -296,6 +303,15 @@ export async function dev(options: {
 
   /** Pre-existing HTTP server from warm standby mode (avoids port gap on transition). */
   existingServer?: HttpServer;
+
+  /** Force package installation when the caller has detected dependency drift. */
+  forcePackageInstall?: boolean;
+
+  /** Package snapshot before S3 workspace restore; used to refresh forced install after DBFS sync. */
+  packageJsonSnapshotBeforeRestore?: PackageJsonSnapshot | null;
+
+  /** Restore managed warm-template package pins after DBFS download in S3 warm restore flow. */
+  normalizeManagedPackageDependencies?: boolean;
 }) {
   const {
     cwd,
@@ -566,6 +582,9 @@ export async function dev(options: {
             }
 
             let hasPackageChanged = false;
+            let packageJsonRequiresInstall = false;
+            const hasPackageJsonSnapshotBeforeRestore =
+              options.packageJsonSnapshotBeforeRestore !== undefined;
 
             const packageJsonBefore = await readPkgJson(cwd);
 
@@ -576,6 +595,17 @@ export async function dev(options: {
                 );
 
                 await syncService!.downloadDirectory();
+                if (
+                  options.normalizeManagedPackageDependencies &&
+                  (await restoreManagedPackageDependencies(
+                    cwd,
+                    packageJsonBefore,
+                  ))
+                ) {
+                  logger.info(
+                    "Restored managed package dependencies to the warm template versions after DBFS download",
+                  );
+                }
                 span.end();
               });
             }
@@ -814,16 +844,73 @@ export async function dev(options: {
 
             const packageJsonAfter = await readPkgJson(cwd);
 
+            let packageJsonSnapshotBefore: PackageJsonSnapshot | null = null;
+            let packageJsonSnapshotAfter: PackageJsonSnapshot | null = null;
+            let packageJsonInstallBaselineSnapshot: PackageJsonSnapshot | null =
+              null;
+
             if (packageJsonBefore && packageJsonAfter) {
               hasPackageChanged =
                 JSON.stringify(packageJsonBefore, null, 2) !==
                 JSON.stringify(packageJsonAfter, null, 2);
             } else if (packageJsonAfter) {
               hasPackageChanged = true;
+            }
+
+            if (packageJsonBefore) {
+              packageJsonSnapshotBefore =
+                packageJsonSnapshot(packageJsonBefore);
+            }
+            if (packageJsonAfter) {
+              packageJsonSnapshotAfter = packageJsonSnapshot(packageJsonAfter);
+            }
+
+            packageJsonInstallBaselineSnapshot =
+              hasPackageJsonSnapshotBeforeRestore
+                ? (options.packageJsonSnapshotBeforeRestore ?? null)
+                : packageJsonSnapshotBefore;
+            if (packageJsonAfter) {
+              packageJsonRequiresInstall = didPackageJsonSnapshotChange(
+                packageJsonInstallBaselineSnapshot,
+                packageJsonSnapshotAfter,
+              );
+            }
+            if (!packageJsonBefore && packageJsonRequiresInstall) {
               logger.info("package.json was created, installing packages…");
             }
+            const forcePackageInstallRequested = !!options.forcePackageInstall;
+            let forcePackageInstall = forcePackageInstallRequested;
+            if (
+              forcePackageInstallRequested &&
+              hasPackageJsonSnapshotBeforeRestore
+            ) {
+              forcePackageInstall = packageJsonRequiresInstall;
+            }
+
+            logger.info("Package install decision", {
+              packageJsonBeforePresent: !!packageJsonBefore,
+              packageJsonAfterPresent: !!packageJsonAfter,
+              hasPackageChanged,
+              packageJsonRequiresInstall,
+              forcePackageInstall,
+              forcePackageInstallRequested,
+              upgradePromiseCount: upgradePromises.length,
+              packageJsonSnapshotBefore: packageJsonSnapshotDiagnostic(
+                packageJsonSnapshotBefore,
+              ),
+              packageJsonInstallBaselineSnapshot: packageJsonSnapshotDiagnostic(
+                packageJsonInstallBaselineSnapshot,
+              ),
+              packageJsonSnapshotAfter: packageJsonSnapshotDiagnostic(
+                packageJsonSnapshotAfter,
+              ),
+            });
 
-            if (hasPackageChanged || upgradePromises.length > 0) {
+            if (
+              packageJsonRequiresInstall ||
+              upgradePromises.length > 0 ||
+              forcePackageInstall
+            ) {
               logger.info("Installing packages…");
               await tracer.startActiveSpan("installPackages", async (span) => {
                 try {
@@ -842,7 +929,9 @@ export async function dev(options: {
               );
             }
 
-            if (hasPackageChanged || uploadFirst) {
+            const shouldUploadPackageState =
+              hasPackageChanged || forcePackageInstall;
+            if (shouldUploadPackageState || uploadFirst) {
               logger.info(
                 `Uploading local files to branch '${activeDbfsBranchName}' on server before starting`,
               );

package/src/cli-replacement/package-json-snapshot.mts

@@ -0,0 +1,328 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import { join } from "node:path";
+
+export const SUPERBLOCKS_LIBRARY_PACKAGE = "@superblocksteam/library";
+export const SUPERBLOCKS_SDK_API_PACKAGE = "@superblocksteam/sdk-api";
+
+export const MANAGED_PACKAGE_DEPENDENCIES = [
+  SUPERBLOCKS_LIBRARY_PACKAGE,
+  SUPERBLOCKS_SDK_API_PACKAGE,
+] as const;
+
+export const PACKAGE_DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+
+const PACKAGE_INSTALL_METADATA_FIELDS = [
+  "dependenciesMeta",
+  "devEngines",
+  "engines",
+  "overrides",
+  "packageManager",
+  "peerDependenciesMeta",
+  "pnpm",
+  "resolutions",
+  "workspaces",
+] as const;
+
+const PACKAGE_BUNDLE_DEPENDENCIES_FIELDS = [
+  "bundleDependencies",
+  "bundledDependencies",
+] as const;
+
+export type PackageJsonSnapshot = {
+  value: string;
+  diagnostic: {
+    sha256: string;
+    bytes: number;
+  };
+};
+
+export type PackageJsonSnapshotReadResult = {
+  packageJson: unknown | null;
+  snapshot: PackageJsonSnapshot | null;
+};
+
+export function packageJsonSnapshot(packageJson: unknown): PackageJsonSnapshot {
+  const packageJsonObject = packageJsonRecord(packageJson);
+  const normalized = PACKAGE_DEPENDENCY_FIELDS.reduce<Record<string, unknown>>(
+    (acc, field) => {
+      const dependencies = packageJsonObject
+        ? dependencyMap(packageJsonObject, field)
+        : undefined;
+      if (dependencies) {
+        acc[field] = dependencies;
+      }
+      return acc;
+    },
+    {},
+  );
+  if (packageJsonObject) {
+    const bundleDependenciesField = PACKAGE_BUNDLE_DEPENDENCIES_FIELDS.find(
+      (field) => Object.prototype.hasOwnProperty.call(packageJsonObject, field),
+    );
+    if (bundleDependenciesField) {
+      normalized.bundleDependencies =
+        packageJsonObject[bundleDependenciesField];
+    }
+
+    for (const field of PACKAGE_INSTALL_METADATA_FIELDS) {
+      if (Object.prototype.hasOwnProperty.call(packageJsonObject, field)) {
+        normalized[field] = packageJsonObject[field];
+      }
+    }
+  }
+  const value = stableStringify(normalized);
+
+  return {
+    value,
+    diagnostic: {
+      sha256: createHash("sha256").update(value).digest("hex"),
+      bytes: Buffer.byteLength(value),
+    },
+  };
+}
+
+export function didPackageJsonSnapshotChange(
+  before: PackageJsonSnapshot | null,
+  after: PackageJsonSnapshot | null,
+): boolean {
+  if (before?.value === after?.value) {
+    return false;
+  }
+
+  // If restore removes package.json, there is no manifest to install from.
+  // Treat that as no install work instead of forcing an install that cannot
+  // converge until DBFS or another source recreates the manifest.
+  return after !== null;
+}
+
+export function packageJsonSnapshotDiagnostic(
+  snapshot: PackageJsonSnapshot | null,
+): { present: boolean; sha256?: string; bytes?: number } {
+  if (snapshot === null) {
+    return { present: false };
+  }
+
+  return {
+    present: true,
+    ...snapshot.diagnostic,
+  };
+}
+
+type PackageJsonObject = Record<string, unknown>;
+type PackageDependencySpec = { field: string; value: unknown };
+
+function stableStringify(value: unknown): string {
+  return stableStringifyValue(value) ?? "null";
+}
+
+function stableStringifyValue(value: unknown): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.map((item) => stableStringifyValue(item) ?? "null");
+    return `[${items.join(",")}]`;
+  }
+
+  if (value && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    const entries = Object.keys(object)
+      .sort()
+      .flatMap((key) => {
+        const serializedValue = stableStringifyValue(object[key]);
+        return serializedValue === undefined
+          ? []
+          : [`${JSON.stringify(key)}:${serializedValue}`];
+      });
+    return `{${entries.join(",")}}`;
+  }
+
+  const serialized = JSON.stringify(value);
+  return serialized === undefined ? undefined : serialized;
+}
+
+function packageJsonRecord(packageJson: unknown): PackageJsonObject | null {
+  if (
+    !packageJson ||
+    typeof packageJson !== "object" ||
+    Array.isArray(packageJson)
+  ) {
+    return null;
+  }
+
+  return packageJson as PackageJsonObject;
+}
+
+function dependencyMap(
+  packageJson: PackageJsonObject,
+  field: string,
+): Record<string, unknown> | undefined {
+  const dependencies = packageJson[field];
+  if (
+    dependencies &&
+    typeof dependencies === "object" &&
+    !Array.isArray(dependencies)
+  ) {
+    return dependencies as Record<string, unknown>;
+  }
+
+  return undefined;
+}
+
+function packageDependencySpecs(
+  packageJson: PackageJsonObject,
+  packageName: string,
+): PackageDependencySpec[] {
+  return PACKAGE_DEPENDENCY_FIELDS.flatMap((field) => {
+    const dependencies = dependencyMap(packageJson, field);
+    if (
+      dependencies &&
+      Object.prototype.hasOwnProperty.call(dependencies, packageName)
+    ) {
+      return [{ field, value: dependencies[packageName] }];
+    }
+
+    return [];
+  });
+}
+
+function dependencySpecEquals(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+async function readPackageJson(cwd: string): Promise<unknown | null> {
+  return (await readPackageJsonFile(cwd))?.packageJson ?? null;
+}
+
+async function readPackageJsonFile(
+  cwd: string,
+): Promise<{ packageJson: unknown; source: string } | null> {
+  try {
+    const source = await fs.readFile(join(cwd, "package.json"), "utf-8");
+    return {
+      packageJson: JSON.parse(source),
+      source,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function detectJsonIndent(source: string): number | string {
+  return source.match(/\n([ \t]+)"/)?.[1] ?? 2;
+}
+
+function hasFinalNewline(source: string): boolean {
+  return source.endsWith("\n");
+}
+
+export async function readPackageJsonSnapshot(
+  cwd: string,
+): Promise<PackageJsonSnapshot | null> {
+  const packageJson = await readPackageJson(cwd);
+  if (!packageJson) {
+    return null;
+  }
+  return packageJsonSnapshot(packageJson);
+}
+
+export async function readPackageJsonSnapshotWithSource(
+  cwd: string,
+): Promise<PackageJsonSnapshotReadResult> {
+  const packageJson = await readPackageJson(cwd);
+  return {
+    packageJson,
+    snapshot: packageJson ? packageJsonSnapshot(packageJson) : null,
+  };
+}
+
+export async function restoreManagedPackageDependencies(
+  cwd: string,
+  warmPackageJson: unknown | null,
+): Promise<boolean> {
+  const warmPackageJsonObject = packageJsonRecord(warmPackageJson);
+  if (!warmPackageJsonObject) {
+    return false;
+  }
+
+  const restoredPackageJsonFile = await readPackageJsonFile(cwd);
+  if (!restoredPackageJsonFile) {
+    return false;
+  }
+
+  const restoredPackageJson = packageJsonRecord(
+    restoredPackageJsonFile.packageJson,
+  );
+  if (!restoredPackageJson) {
+    return false;
+  }
+  const restoredPackageJsonSource = restoredPackageJsonFile.source;
+
+  let changed = false;
+  for (const packageName of MANAGED_PACKAGE_DEPENDENCIES) {
+    const [warmPackageSpec] = packageDependencySpecs(
+      warmPackageJsonObject,
+      packageName,
+    );
+    if (!warmPackageSpec) {
+      continue;
+    }
+
+    const restoredPackageSpecs = packageDependencySpecs(
+      restoredPackageJson,
+      packageName,
+    );
+    if (
+      restoredPackageSpecs.length === 1 &&
+      restoredPackageSpecs[0].field === warmPackageSpec.field &&
+      dependencySpecEquals(restoredPackageSpecs[0].value, warmPackageSpec.value)
+    ) {
+      continue;
+    }
+
+    if (
+      restoredPackageSpecs.length === 1 &&
+      restoredPackageSpecs[0].field === warmPackageSpec.field
+    ) {
+      dependencyMap(restoredPackageJson, warmPackageSpec.field)![packageName] =
+        warmPackageSpec.value;
+    } else {
+      for (const field of PACKAGE_DEPENDENCY_FIELDS) {
+        delete dependencyMap(restoredPackageJson, field)?.[packageName];
+      }
+
+      let dependencies = dependencyMap(
+        restoredPackageJson,
+        warmPackageSpec.field,
+      );
+      if (!dependencies) {
+        dependencies = {};
+        restoredPackageJson[warmPackageSpec.field] = dependencies;
+      }
+      dependencies[packageName] = warmPackageSpec.value;
+    }
+    changed = true;
+  }
+
+  if (!changed) {
+    return false;
+  }
+
+  await fs.writeFile(
+    join(cwd, "package.json"),
+    JSON.stringify(
+      restoredPackageJson,
+      null,
+      detectJsonIndent(restoredPackageJsonSource),
+    ) + (hasFinalNewline(restoredPackageJsonSource) ? "\n" : ""),
+  );
+
+  return true;
+}

package/src/cli-replacement/package-json-snapshot.test.mts

@@ -0,0 +1,250 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  didPackageJsonSnapshotChange,
+  packageJsonSnapshot,
+  readPackageJsonSnapshotWithSource,
+  restoreManagedPackageDependencies,
+} from "./package-json-snapshot.mjs";
+
+describe("packageJsonSnapshot", () => {
+  it("is stable for object key order changes", () => {
+    const before = packageJsonSnapshot({
+      dependencies: {
+        "@superblocksteam/library": "2.0.0",
+        react: "19.0.0",
+      },
+      scripts: {
+        dev: "vite",
+        build: "vite build",
+      },
+    });
+
+    const after = packageJsonSnapshot({
+      scripts: {
+        build: "vite build",
+        dev: "vite",
+      },
+      dependencies: {
+        react: "19.0.0",
+        "@superblocksteam/library": "2.0.0",
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(false);
+    expect(before.diagnostic.sha256).toBe(after.diagnostic.sha256);
+  });
+
+  it("detects dependency version changes", () => {
+    const before = packageJsonSnapshot({
+      dependencies: {
+        "@superblocksteam/library": "1.0.0",
+      },
+    });
+    const after = packageJsonSnapshot({
+      dependencies: {
+        "@superblocksteam/library": "2.0.0",
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(true);
+  });
+
+  it("ignores non-dependency package metadata", () => {
+    const before = packageJsonSnapshot({
+      name: "warm-template",
+      version: "1.0.0",
+      scripts: {
+        dev: "vite",
+      },
+      dependencies: {
+        react: "19.0.0",
+      },
+    });
+    const after = packageJsonSnapshot({
+      name: "restored-app",
+      version: "2.0.0",
+      scripts: {
+        dev: "vite --host 0.0.0.0",
+      },
+      dependencies: {
+        react: "19.0.0",
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(false);
+  });
+
+  it("detects install-relevant package metadata changes", () => {
+    const basePackageJson = {
+      dependencies: {
+        react: "19.0.0",
+      },
+      overrides: {
+        lodash: "4.17.20",
+      },
+      pnpm: {
+        overrides: {
+          axios: "1.12.0",
+        },
+      },
+    };
+
+    const before = packageJsonSnapshot(basePackageJson);
+    const after = packageJsonSnapshot({
+      ...basePackageJson,
+      overrides: {
+        lodash: "4.17.21",
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(true);
+  });
+
+  it("detects package-manager-specific install metadata changes", () => {
+    const before = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+      },
+      pnpm: {
+        overrides: {
+          axios: "1.12.0",
+        },
+      },
+    });
+
+    const after = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+      },
+      pnpm: {
+        overrides: {
+          axios: "1.13.2",
+        },
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(true);
+  });
+
+  it("detects devEngines package manager changes", () => {
+    const before = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+      },
+      devEngines: {
+        packageManager: {
+          name: "npm",
+          version: "10.0.0",
+        },
+      },
+    });
+
+    const after = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+      },
+      devEngines: {
+        packageManager: {
+          name: "pnpm",
+          version: "10.0.0",
+        },
+      },
+    });
+
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(true);
+  });
+
+  it("omits undefined object values when serializing snapshots", () => {
+    const before = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+        removed: undefined,
+      },
+      pnpm: {
+        onlyBuiltDependencies: ["esbuild", undefined],
+        overrides: undefined,
+      },
+    });
+    const after = packageJsonSnapshot({
+      dependencies: {
+        react: "19.0.0",
+      },
+      pnpm: {
+        onlyBuiltDependencies: ["esbuild", null],
+      },
+    });
+
+    expect(before.value).not.toContain("undefined");
+    expect(didPackageJsonSnapshotChange(before, after)).toBe(false);
+  });
+
+  it("matches read-pkg bundle dependency alias normalization", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "pkg-json-"));
+
+    try {
+      await fs.writeFile(
+        path.join(tmpDir, "package.json"),
+        JSON.stringify({
+          name: "test-app",
+          version: "1.0.0",
+          dependencies: {
+            react: "19.0.0",
+          },
+          bundledDependencies: ["react"],
+        }),
+      );
+
+      const before = await readPackageJsonSnapshotWithSource(tmpDir);
+      const { readPackage } = await import("read-pkg");
+      const after = packageJsonSnapshot(await readPackage({ cwd: tmpDir }));
+
+      expect(didPackageJsonSnapshotChange(before.snapshot, after)).toBe(false);
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("restoreManagedPackageDependencies", () => {
+  it("preserves the restored package.json indentation when rewriting managed packages", async () => {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "pkg-json-"));
+
+    try {
+      await fs.writeFile(
+        path.join(tmpDir, "package.json"),
+        JSON.stringify(
+          {
+            name: "restored-app",
+            dependencies: {
+              "@superblocksteam/library": "1.0.0",
+              react: "19.0.0",
+            },
+          },
+          null,
+          4,
+        ) + "\n",
+      );
+
+      await restoreManagedPackageDependencies(tmpDir, {
+        dependencies: {
+          "@superblocksteam/library": "2.0.0",
+        },
+      });
+
+      const restored = await fs.readFile(
+        path.join(tmpDir, "package.json"),
+        "utf-8",
+      );
+      expect(restored).toContain('\n    "dependencies"');
+      expect(restored).toContain('\n        "@superblocksteam/library"');
+      expect(restored.endsWith("\n")).toBe(true);
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+});