@superblocksteam/sdk 2.0.115 → 2.0.116-next.1

package/src/cli-replacement/dev.mts

@@ -58,6 +58,7 @@ import {
   ensureRemoteHasDefaultBranch,
   getGitErrorFields,
 } from "./git-repo-setup.mjs";
+import { normalizeWorkspaceProtocolForNpm } from "./normalize-workspace-protocol.js";
 import {
   didPackageJsonSnapshotChange,
   packageJsonSnapshot,
@@ -205,6 +206,45 @@ async function readPkgJson(cwd: string) {
   }
 }
 
+async function normalizePackageJsonForNpm(cwd: string, logger: Logger) {
+  const packageJsonPath = path.join(cwd, "package.json");
+  let raw: string;
+  try {
+    raw = await nodeFs.readFile(packageJsonPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw err;
+    }
+    return;
+  }
+  let parsed: ReturnType<typeof JSON.parse>;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    logger.warn(
+      `Could not parse package.json at ${packageJsonPath} for workspace-protocol normalization: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return;
+  }
+
+  const result = normalizeWorkspaceProtocolForNpm(parsed);
+  if (!result.changed) return;
+
+  for (const warning of result.warnings) {
+    logger.warn(warning);
+  }
+  try {
+    await nodeFs.writeFile(
+      packageJsonPath,
+      `${JSON.stringify(result.packageJson, null, 2)}\n`,
+    );
+  } catch (err) {
+    throw new Error(
+      `Failed to write normalized package.json at ${packageJsonPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 async function installPackages(cwd: string, logger: Logger) {
   try {
     const pm = await detect({
@@ -224,6 +264,13 @@ async function installPackages(cwd: string, logger: Logger) {
       return;
     }
 
+    if (pm.agent === "npm") {
+      // npm rejects pnpm's `workspace:` protocol with EUNSUPPORTEDPROTOCOL,
+      // crash-looping the SABS dev-server pod. Strip the prefix so npm can
+      // resolve a published version instead.
+      await normalizePackageJsonForNpm(cwd, logger);
+    }
+
     const installCommand = resolveCommand(
       pm.agent,
       "install",
@@ -482,11 +529,11 @@ export async function dev(options: {
               );
             }
 
-            const [localContents, serverHash, currentUser] =
-              await tracer.startActiveSpan("fetchInitInfo", async (span) => {
+            const [serverHash, currentUser] = await tracer.startActiveSpan(
+              "fetchUserAndServerHash",
+              async (span) => {
                 try {
-                  const results = await Promise.all([
-                    sdk.hashLocalDirectory(cwd),
+                  return await Promise.all([
                     getDraftOrLiveEditHash(
                       sdk,
                       applicationConfig.id,
@@ -495,11 +542,15 @@ export async function dev(options: {
                     ),
                     sdk.fetchCurrentUser(),
                   ]);
-                  return results;
                 } finally {
                   span.end();
                 }
-              });
+              },
+            );
+
+            logger.info(
+              `[dev-startup] Fetched server hash for branch '${activeDbfsBranchName}'`,
+            );
 
             gitUserName = currentUser.user.name;
             gitUserEmail = currentUser.user.email;
@@ -558,60 +609,19 @@ export async function dev(options: {
               },
             );
 
-            const isSynced = localContents.hash === serverHash;
-
-            if (isSynced) {
-              logger.info(
-                `Local files are in sync with the server on branch '${activeDbfsBranchName}', local hash: ${localContents.hash}, server hash: ${serverHash}`,
-              );
-            } else {
-              logger.info(
-                `Local files are out of sync with the server on branch '${activeDbfsBranchName}', local hash: ${localContents.hash}, server hash: ${serverHash}`,
-              );
-            }
-
-            if (!(downloadFirst || uploadFirst)) {
-              throw new Error(
-                "You must choose --download-first or --upload-first to use the dev command",
-              );
-            }
-            if (downloadFirst && uploadFirst) {
-              throw new Error(
-                "Choose either --download-first or --upload-first",
-              );
-            }
-
-            let hasPackageChanged = false;
-            let packageJsonRequiresInstall = false;
-            const hasPackageJsonSnapshotBeforeRestore =
-              options.packageJsonSnapshotBeforeRestore !== undefined;
-
-            const packageJsonBefore = await readPkgJson(cwd);
-
-            if (downloadFirst && !isSynced) {
-              await tracer.startActiveSpan("downloadFirst", async (span) => {
-                logger.info(
-                  `Starting download of branch '${activeDbfsBranchName}'`,
-                );
-
-                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();
-              });
-            }
+            logger.info(
+              `[dev-startup] Starting git sync (${downloadFirst ? "download" : "upload"}-first) on branch '${activeDbfsBranchName}'`,
+            );
 
-            // Git sync step — runs after DBFS download, before version check.
-            // Best-effort: never blocks startup on failure.
+            // Git sync step — runs before DBFS download so the working tree can
+            // be reconciled with remotes/branches first; DBFS download then
+            // overwrites app files with server state (source of truth). The
+            // .git directory is not managed by DBFS. Best-effort: never blocks
+            // startup on failure.
+            let devStartupGitOutcome:
+              | "skipped_no_remote"
+              | "bootstrap_failed"
+              | "completed" = "skipped_no_remote";
             await tracer.startActiveSpan("gitSync", async (gitSpan) => {
               try {
                 const bootstrappedGitService = await bootstrapGitService({
@@ -625,6 +635,7 @@ export async function dev(options: {
                 });
 
                 if (!bootstrappedGitService) {
+                  devStartupGitOutcome = "skipped_no_remote";
                   logger.info("[git] startup git sync skipped", {
                     gitCategory: "setup",
                     gitOperation: "bootstrap",
@@ -633,104 +644,11 @@ export async function dev(options: {
                     applicationId: applicationConfig.id,
                     workDir: cwd,
                   });
-
-                  // In CSB mode, schedule a background retry loop. The app's
-                  // git config may not be persisted yet at claim time (e.g. git
-                  // was connected moments before the CSB was assigned). Without
-                  // this, the CSB runs its entire lifetime without git — meaning
-                  // changes are only in DBFS and are lost if the CSB recycles.
-                  if (lockType === LockType.CSB) {
-                    const GIT_RETRY_DELAY_MS = 30_000;
-                    const GIT_RETRY_MAX_ATTEMPTS = 10;
-                    const scheduleRetry = (attempt: number): void => {
-                      if (attempt > GIT_RETRY_MAX_ATTEMPTS) {
-                        logger.info(
-                          "[git] background bootstrap retry exhausted, giving up",
-                          {
-                            gitCategory: "setup",
-                            gitOperation: "background-retry",
-                            gitOutcome: "exhausted",
-                            gitAttempt: attempt - 1,
-                            applicationId: applicationConfig.id,
-                          },
-                        );
-                        return;
-                      }
-                      const timer = setTimeout(() => {
-                        void (async () => {
-                          if (gitService) return;
-                          try {
-                            const svc = await bootstrapGitService({
-                              sdk,
-                              applicationId: applicationConfig.id,
-                              cwd,
-                              logger,
-                              userName: gitUserName,
-                              userEmail: gitUserEmail,
-                              superblocksBaseUrl:
-                                tokenConfig.superblocksBaseUrl,
-                            });
-                            if (!svc) {
-                              scheduleRetry(attempt + 1);
-                              return;
-                            }
-
-                            gitService = svc;
-
-                            try {
-                              await fetchAndEnsureLiveBranch(
-                                svc,
-                                "Git background retry fetch failed",
-                              );
-                            } catch {
-                              // non-fatal
-                            }
-
-                            activeDbfsBranchName =
-                              await ensureRuntimeDbfsBranchConsistency({
-                                sdk,
-                                applicationConfig,
-                                logger,
-                                lockService,
-                                syncService,
-                                currentBranchName: activeDbfsBranchName,
-                              });
-
-                            logger.info(
-                              "[git] background bootstrap retry succeeded",
-                              {
-                                gitCategory: "setup",
-                                gitOperation: "background-retry",
-                                gitOutcome: "success",
-                                gitAttempt: attempt,
-                                applicationId: applicationConfig.id,
-                              },
-                            );
-                          } catch (err) {
-                            logger.warn(
-                              "[git] background bootstrap retry failed",
-                              {
-                                gitCategory: "setup",
-                                gitOperation: "background-retry",
-                                gitOutcome: "failed",
-                                gitAttempt: attempt,
-                                applicationId: applicationConfig.id,
-                                ...getGitErrorFields(err),
-                              },
-                            );
-                            scheduleRetry(attempt + 1);
-                          }
-                        })();
-                      }, GIT_RETRY_DELAY_MS);
-                      timer.unref();
-                    };
-                    scheduleRetry(1);
-                  }
-
                   gitSpan.end();
                   return;
                 }
 
+                devStartupGitOutcome = "completed";
                 gitService = bootstrappedGitService;
 
                 // At this point the local repo is usable for status(),
@@ -774,6 +692,7 @@ export async function dev(options: {
                 }
               } catch (gitError) {
                 // Init/configure/ensureGitRepo failed — repo is not usable
+                devStartupGitOutcome = "bootstrap_failed";
                 gitService = undefined;
                 logger.warn(
                   "[git] startup git setup failed, continuing without git",
@@ -798,6 +717,93 @@ export async function dev(options: {
               }
             });
 
+            logger.info(
+              `[dev-startup] Git sync complete (outcome=${devStartupGitOutcome})`,
+            );
+
+            const localContents = await tracer.startActiveSpan(
+              "hashLocalDirectory",
+              async (span) => {
+                try {
+                  return await sdk.hashLocalDirectory(cwd);
+                } finally {
+                  span.end();
+                }
+              },
+            );
+
+            const isSynced = localContents.hash === serverHash;
+
+            logger.info(
+              `[dev-startup] Local directory ${isSynced ? "in sync" : "out of sync"} with server`,
+            );
+
+            if (!(downloadFirst || uploadFirst)) {
+              throw new Error(
+                "You must choose --download-first or --upload-first to use the dev command",
+              );
+            }
+            if (downloadFirst && uploadFirst) {
+              throw new Error(
+                "Choose either --download-first or --upload-first",
+              );
+            }
+
+            let hasPackageChanged = false;
+            let packageJsonRequiresInstall = false;
+            const hasPackageJsonSnapshotBeforeRestore =
+              options.packageJsonSnapshotBeforeRestore !== undefined;
+
+            const packageJsonBefore = await readPkgJson(cwd);
+
+            if (downloadFirst && !isSynced) {
+              await tracer.startActiveSpan("downloadFirst", async (span) => {
+                logger.info(
+                  `Starting download of branch '${activeDbfsBranchName}'`,
+                );
+
+                await syncService!.downloadDirectory();
+                logger.info("[dev-startup] DBFS download complete");
+                try {
+                  const postDownloadLocalContents =
+                    await tracer.startActiveSpan(
+                      "hashLocalDirectoryAfterDbfsDownload",
+                      async (hashSpan) => {
+                        try {
+                          return await sdk.hashLocalDirectory(cwd);
+                        } finally {
+                          hashSpan.end();
+                        }
+                      },
+                    );
+                  const hashMatchesServer =
+                    postDownloadLocalContents.hash === serverHash;
+                  logger.info(
+                    `[dev-startup] Post-download hash ${hashMatchesServer ? "matches" : "does not match"} server`,
+                  );
+                } catch (hashError) {
+                  logger.warn(
+                    "[dev-startup] Failed to compute post-download hash",
+                    getErrorMeta(hashError),
+                  );
+                }
+                if (
+                  options.normalizeManagedPackageDependencies &&
+                  (await restoreManagedPackageDependencies(
+                    cwd,
+                    packageJsonBefore,
+                  ))
+                ) {
+                  logger.info(
+                    "Restored managed package dependencies to the warm template versions after DBFS download",
+                  );
+                }
+                span.end();
+              });
+            } else if (downloadFirst && isSynced) {
+              logger.info("[dev-startup] Skipping download, already in sync");
+            }
+
             let hasCliUpdated = false;
             let upgradePromises: Promise<void>[] = [];
             const forceUpgrade =
@@ -1413,23 +1419,10 @@ async function ensureLiveBranchCheckedOutAfterFetch(
   // If remote live branch exists, initialize/switch local live branch from it.
   // This handles fresh repos where HEAD is unborn before first fetch.
   if (await canResolveRef(git, `origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`)) {
-    try {
-      await git.checkoutOrCreate(
-        SUPERBLOCKS_LIVE_GIT_BRANCH,
-        `origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`,
-      );
-    } catch {
-      // Pre-warmed CSBs download DBFS files before git is set up, leaving
-      // untracked working tree files that collide with the branch contents.
-      // Force-checkout is safe here — the files are identical.
-      await git.raw([
-        "checkout",
-        "-f",
-        "-B",
-        SUPERBLOCKS_LIVE_GIT_BRANCH,
-        `origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`,
-      ]);
-    }
+    await git.checkoutOrCreate(
+      SUPERBLOCKS_LIVE_GIT_BRANCH,
+      `origin/${SUPERBLOCKS_LIVE_GIT_BRANCH}`,
+    );
     return;
   }
 

package/src/cli-replacement/normalize-workspace-protocol.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest";
+
+import { normalizeWorkspaceProtocolForNpm } from "./normalize-workspace-protocol.js";
+
+describe("normalizeWorkspaceProtocolForNpm", () => {
+  it("returns unchanged when no workspace: deps are present", () => {
+    const pkg = {
+      dependencies: { react: "^18.0.0", "@superblocksteam/library": "2.5.0" },
+      devDependencies: { vitest: "^1.0.0" },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(false);
+    expect(result.warnings).toHaveLength(0);
+    expect(result.packageJson).toEqual(pkg);
+  });
+
+  it("strips workspace: prefix from dependencies and reports a warning per dep", () => {
+    const pkg = {
+      dependencies: {
+        "@superblocksteam/library": "workspace:*",
+        "@superblocksteam/sdk-api": "workspace:*",
+        react: "^18.0.0",
+      },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(true);
+    expect(result.packageJson.dependencies).toEqual({
+      "@superblocksteam/library": "*",
+      "@superblocksteam/sdk-api": "*",
+      react: "^18.0.0",
+    });
+    expect(result.warnings).toHaveLength(2);
+    expect(result.warnings.join(" ")).toContain("@superblocksteam/library");
+    expect(result.warnings.join(" ")).toContain("@superblocksteam/sdk-api");
+  });
+
+  it("preserves the version range after the workspace: prefix", () => {
+    const pkg = {
+      dependencies: {
+        a: "workspace:^1.2.3",
+        b: "workspace:~2.0.0",
+        c: "workspace:1.0.0",
+      },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(true);
+    expect(result.packageJson.dependencies).toEqual({
+      a: "^1.2.3",
+      b: "~2.0.0",
+      c: "1.0.0",
+    });
+  });
+
+  it("normalizes across all dependency buckets (devDependencies, optionalDependencies, peerDependencies)", () => {
+    const pkg = {
+      dependencies: { a: "workspace:*" },
+      devDependencies: { b: "workspace:*" },
+      optionalDependencies: { c: "workspace:*" },
+      peerDependencies: { d: "workspace:*" },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(true);
+    expect(result.packageJson.dependencies?.a).toBe("*");
+    expect(result.packageJson.devDependencies?.b).toBe("*");
+    expect(result.packageJson.optionalDependencies?.c).toBe("*");
+    expect(result.packageJson.peerDependencies?.d).toBe("*");
+  });
+
+  it("does not touch values that merely contain the substring 'workspace' but don't use the protocol", () => {
+    const pkg = {
+      dependencies: {
+        "some-workspace-tool": "1.0.0",
+        a: "git+ssh://git@github.com/foo/workspace.git",
+      },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(false);
+    expect(result.packageJson).toEqual(pkg);
+  });
+
+  it("does not mutate the input object", () => {
+    const pkg = {
+      dependencies: { a: "workspace:*" },
+    };
+    const original = JSON.parse(JSON.stringify(pkg));
+    normalizeWorkspaceProtocolForNpm(pkg);
+    expect(pkg).toEqual(original);
+  });
+
+  it("handles a package.json with no dependency buckets", () => {
+    const pkg = { name: "test", version: "1.0.0" };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(false);
+    expect(result.warnings).toHaveLength(0);
+    expect(result.packageJson).toEqual(pkg);
+  });
+
+  it("bare workspace: (no version after colon) falls back to *", () => {
+    const pkg = { dependencies: { a: "workspace:" } };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(true);
+    expect(result.packageJson.dependencies?.a).toBe("*");
+  });
+
+  it("operator-only forms (workspace:^ and workspace:~) preserve the operator as-is", () => {
+    const pkg = {
+      dependencies: { a: "workspace:^", b: "workspace:~" },
+    };
+    const result = normalizeWorkspaceProtocolForNpm(pkg);
+
+    expect(result.changed).toBe(true);
+    expect(result.packageJson.dependencies?.a).toBe("^");
+    expect(result.packageJson.dependencies?.b).toBe("~");
+  });
+});

package/src/cli-replacement/normalize-workspace-protocol.ts

@@ -0,0 +1,64 @@
+// pnpm's `workspace:` protocol is not understood by npm — `npm install` rejects
+// it with EUNSUPPORTEDPROTOCOL. In the SABS dev-server pod the user app's
+// package.json can arrive with `workspace:*` deps (build-time rewrite was
+// missed, DBFS row predates the rewrite, etc.) and the install crash-loops the
+// pod with no useful signal. This helper strips the `workspace:` prefix so npm
+// can resolve a published version. It runs in the cloud pod only — local dev
+// uses pnpm and needs the protocol intact for workspace linking.
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  [key: string]: unknown;
+};
+
+const DEPENDENCY_BUCKETS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+] as const;
+
+const WORKSPACE_PROTOCOL = "workspace:";
+
+export interface NormalizeResult {
+  changed: boolean;
+  warnings: string[];
+  packageJson: PackageJson;
+}
+
+export function normalizeWorkspaceProtocolForNpm(
+  packageJson: PackageJson,
+): NormalizeResult {
+  const next: PackageJson = { ...packageJson };
+  const warnings: string[] = [];
+  let changed = false;
+
+  for (const bucket of DEPENDENCY_BUCKETS) {
+    const deps = packageJson[bucket];
+    if (!deps) continue;
+
+    const nextDeps: Record<string, string> = {};
+    for (const [name, value] of Object.entries(deps)) {
+      if (typeof value === "string" && value.startsWith(WORKSPACE_PROTOCOL)) {
+        const stripped = value.slice(WORKSPACE_PROTOCOL.length) || "*";
+        nextDeps[name] = stripped;
+        changed = true;
+        warnings.push(
+          // For @superblocksteam/sdk-api this falls back to the latest published
+          // non-ephemeral package. To pin an ephemeral version, fix the upstream
+          // rewrite path (scripts/setup-template.sh) so workspace:* never ships
+          // to the pod.
+          `Stripped pnpm "workspace:" protocol from ${bucket}.${name} (was "${value}", now "${stripped}") so npm install can resolve it.`,
+        );
+      } else {
+        nextDeps[name] = String(value);
+      }
+    }
+    next[bucket] = nextDeps;
+  }
+
+  return { changed, warnings, packageJson: next };
+}

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

@@ -532,6 +532,9 @@ export async function createDevServer({
         logger.error(
           `Application ID header mismatch, expected ${resourceConfig!.id}, received ${req.headers["x-superblocks-application-id"]}`,
         );
+        logger.info(
+          `[dev-server-runtime] _sb_connect application mismatch: expected ${resourceConfig!.id}, got ${req.headers["x-superblocks-application-id"]}`,
+        );
         res.status(401).send(
           JSON.stringify({
             error: `Application ID header mismatch. Expected ${resourceConfig!.id}, received ${req.headers["x-superblocks-application-id"]}`,
@@ -551,6 +554,9 @@ export async function createDevServer({
         logger.error(
           `Dev server expects branch ${currentBranch}, but received ${incomingBranch}. Check your current branch with 'git branch' and try again.`,
         );
+        logger.info(
+          `[dev-server-runtime] _sb_connect branch mismatch: expected ${currentBranch}, got ${incomingBranch}`,
+        );
         res.status(401).send(
           JSON.stringify({
             error: `Dev server expects branch ${currentBranch}, but received ${incomingBranch}. Check your current branch with 'git branch' and try again.`,