playcademy 0.18.0 → 0.18.2

package/dist/index.js

@@ -2176,13 +2176,10 @@ function buildQueueImportStatements(queueHandlers) {
   if (queueHandlers.length === 0) {
     return "// No queue handlers";
   }
-  return [
-    "import { createQueueRouter, registerQueueIngressRoute } from './entry/queue'",
-    ...queueHandlers.map((handler, index2) => {
-      const normalizedFile = handler.file.replace(/^server\//, "").replace(/\\/g, "/");
-      return `import queueHandler${index2} from '@game-server/${normalizedFile}'`;
-    })
-  ].join("\n");
+  return queueHandlers.map((handler, index2) => {
+    const normalizedFile = handler.file.replace(/^server\//, "").replace(/\\/g, "/");
+    return `import queueHandler${index2} from '@game-server/${normalizedFile}'`;
+  }).join("\n");
 }
 function buildQueueHandlerCode(queueHandlers) {
   if (queueHandlers.length === 0) {
@@ -4017,7 +4014,7 @@ import { existsSync as existsSync9, mkdirSync as mkdirSync2, readFileSync as rea
 import { join as join13 } from "node:path";
 
 // src/version.ts
-var cliVersion = false ? "0.0.0-dev" : "0.18.0";
+var cliVersion = false ? "0.0.0-dev" : "0.18.2";
 
 // src/lib/init/database.ts
 var drizzleConfigTemplate = loadTemplateString("database/drizzle-config.ts");
@@ -6381,8 +6378,8 @@ async function registerCustomRoutes(app, routes) {
 }
 
 // src/lib/dev/server.ts
-import { mkdir as mkdir4 } from "fs/promises";
-import { join as join29 } from "path";
+import { mkdir as mkdir5 } from "fs/promises";
+import { join as join30 } from "path";
 import { Log, LogLevel, Miniflare } from "miniflare";
 
 // ../edge-play/src/constants.ts
@@ -6484,7 +6481,12 @@ Stop the other server or specify a different port with --port <number>.`
 }
 
 // src/lib/deploy/bundle.ts
-import { existsSync as existsSync22, readFileSync as readFileSync13 } from "node:fs";
+import { join as join29, relative as relative4 } from "node:path";
+
+// src/lib/deploy/backend-runtime.ts
+import { existsSync as existsSync22 } from "node:fs";
+import { copyFile, mkdir as mkdir4, readFile as readFile4, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
+import { tmpdir as tmpdir3 } from "node:os";
 import { join as join28 } from "node:path";
 
 // ../utils/src/path.ts
@@ -6740,56 +6742,33 @@ function getMonorepoRoot() {
 var isCompiledBinary = typeof IS_COMPILED_BINARY !== "undefined" && IS_COMPILED_BINARY;
 
 // src/lib/build/plugins.ts
+var TEXT_LOADER_PATTERNS = [
+  /edge-play\/src\/stub-entry\.ts$/,
+  /edge-play\/src\/routes\/root\.html$/,
+  /templates\/sample-route\.ts$/
+];
 function textLoaderPlugin() {
   return {
     name: "text-loader",
     setup(build3) {
-      build3.onLoad({ filter: /edge-play\/src\/entry\.ts$/ }, async (args) => {
-        const fs2 = await import("fs/promises");
-        const text5 = await fs2.readFile(args.path, "utf8");
-        return {
-          contents: `export default ${JSON.stringify(text5)}`,
-          loader: "js"
-        };
-      });
-      build3.onLoad({ filter: /edge-play\/src\/stub-entry\.ts$/ }, async (args) => {
-        const fs2 = await import("fs/promises");
-        const text5 = await fs2.readFile(args.path, "utf8");
-        return {
-          contents: `export default ${JSON.stringify(text5)}`,
-          loader: "js"
-        };
-      });
-      build3.onLoad({ filter: /edge-play\/src\/routes\/root\.html$/ }, async (args) => {
-        const fs2 = await import("fs/promises");
-        const text5 = await fs2.readFile(args.path, "utf8");
-        return {
-          contents: `export default ${JSON.stringify(text5)}`,
-          loader: "js"
-        };
-      });
-      build3.onLoad({ filter: /templates\/sample-route\.ts$/ }, async (args) => {
-        const fs2 = await import("fs/promises");
-        const text5 = await fs2.readFile(args.path, "utf8");
-        return {
-          contents: `export default ${JSON.stringify(text5)}`,
-          loader: "js"
-        };
-      });
+      for (const filter of TEXT_LOADER_PATTERNS) {
+        build3.onLoad({ filter }, async (args) => {
+          const fs2 = await import("fs/promises");
+          const text5 = await fs2.readFile(args.path, "utf8");
+          return {
+            contents: `export default ${JSON.stringify(text5)}`,
+            loader: "js"
+          };
+        });
+      }
     }
   };
 }
 
-// src/lib/deploy/extract-sources.ts
+// src/lib/build/embed.ts
 import { existsSync as existsSync21, mkdirSync as mkdirSync8, writeFileSync as writeFileSync13 } from "node:fs";
 import { dirname as dirname6, join as join27 } from "node:path";
-
-// src/lib/deploy/embedded-sources.ts
-var EMBEDDED_SOURCES = null;
-
-// src/lib/deploy/extract-sources.ts
-var EXTRACTION_MARKER = ".embedded-sources.ok";
-function writeTree(baseDir, files) {
+function writeFileTree(baseDir, files) {
   for (const [relativePath, content] of Object.entries(files)) {
     const fullPath = join27(baseDir, relativePath);
     const dir = dirname6(fullPath);
@@ -6799,27 +6778,225 @@ function writeTree(baseDir, files) {
     writeFileSync13(fullPath, content);
   }
 }
-var cachedPaths = null;
-function extractEmbeddedSources() {
-  if (cachedPaths) {
-    return cachedPaths;
+function createBundleExtractor(options) {
+  const { name, cacheSubdir, getBundle } = options;
+  const marker = `.${name}.ok`;
+  let cachedDir = null;
+  return () => {
+    if (cachedDir) {
+      return cachedDir;
+    }
+    const bundle = getBundle();
+    if (!bundle) {
+      throw new Error(`${name}: embedded bundle is null (not available in dev mode)`);
+    }
+    const dir = join27(cacheVersionDir(cliVersion), cacheSubdir);
+    const markerPath = join27(dir, marker);
+    if (!existsSync21(markerPath)) {
+      mkdirSync8(dir, { recursive: true });
+      writeFileTree(dir, bundle);
+      writeFileSync13(markerPath, `${cliVersion}
+`, "utf8");
+    }
+    cachedDir = dir;
+    return dir;
+  };
+}
+
+// src/lib/deploy/embedded-runtime.ts
+var EMBEDDED_BACKEND_RUNTIME = null;
+
+// src/lib/deploy/extract-runtime.ts
+var extractEmbeddedBackendRuntime = createBundleExtractor({
+  name: "embedded-backend-runtime",
+  cacheSubdir: "backend-runtime",
+  getBundle: () => EMBEDDED_BACKEND_RUNTIME
+});
+
+// src/lib/deploy/backend-runtime.ts
+var BACKEND_RUNTIME_ENTRY = "index.js";
+var BACKEND_RUNTIME_POLYFILLS = "polyfills.js";
+var BACKEND_RUNTIME_MANIFEST = "manifest.json";
+var DEV_RUNTIME_CACHE_DIR = "backend-runtime-dev";
+function createNodePolyfillAliases(polyfillsPath) {
+  return {
+    fs: polyfillsPath,
+    "fs/promises": polyfillsPath,
+    path: polyfillsPath,
+    os: polyfillsPath,
+    process: polyfillsPath,
+    "node:fs": polyfillsPath,
+    "node:fs/promises": polyfillsPath,
+    "node:path": polyfillsPath,
+    "node:os": polyfillsPath,
+    "node:process": polyfillsPath
+  };
+}
+var WORKSPACE_SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".cjs"];
+var RUNTIME_SOURCE_DIRS = [
+  "packages/edge-play/src",
+  "packages/sdk/src",
+  "packages/constants/src",
+  "packages/timeback/src",
+  "packages/types/src",
+  "packages/utils/src",
+  "packages/cloudflare/src",
+  "packages/logger/src"
+];
+async function getPackageVersion2(monorepoRoot, packageName) {
+  try {
+    const packageJson = JSON.parse(
+      await readFile4(join28(monorepoRoot, "packages", packageName, "package.json"), "utf8")
+    );
+    return packageJson.version ?? "0.0.0-dev";
+  } catch {
+    return "0.0.0-dev";
+  }
+}
+async function computeRuntimeInputFingerprint(monorepoRoot, sdkVersion) {
+  const entries = await Promise.all(
+    RUNTIME_SOURCE_DIRS.map(async (dir) => [
+      dir,
+      await hashDirectory(join28(monorepoRoot, dir), ["ts", "js", "json", "html"])
+    ])
+  );
+  return hashContent({ ...Object.fromEntries(entries), sdkVersion });
+}
+async function getRuntimeBuildMetadata(monorepoRoot) {
+  const [cliVersion2, sdkVersion] = await Promise.all([
+    getPackageVersion2(monorepoRoot, "cli"),
+    getPackageVersion2(monorepoRoot, "sdk")
+  ]);
+  const inputFingerprint = await computeRuntimeInputFingerprint(monorepoRoot, sdkVersion);
+  return {
+    cliVersion: cliVersion2,
+    sdkVersion,
+    runtimeBuildId: inputFingerprint.slice(0, 12),
+    inputFingerprint,
+    entry: BACKEND_RUNTIME_ENTRY,
+    polyfills: BACKEND_RUNTIME_POLYFILLS
+  };
+}
+function resolveWorkspaceSourceImport(monorepoRoot, specifier) {
+  if (!specifier.startsWith("@playcademy/")) {
+    return null;
   }
-  if (!EMBEDDED_SOURCES) {
-    throw new Error("extractEmbeddedSources called but EMBEDDED_SOURCES is null (dev mode)");
+  const pathParts = specifier.slice("@playcademy/".length).split("/");
+  const packageName = pathParts.shift();
+  if (!packageName) {
+    return null;
   }
-  const cacheRoot = cacheVersionDir(cliVersion);
-  const edgePlaySrc = join27(cacheRoot, "edge-play", "src");
-  const constantsSrc = join27(cacheRoot, "constants", "src");
-  const markerPath = join27(cacheRoot, EXTRACTION_MARKER);
-  if (!existsSync21(markerPath)) {
-    mkdirSync8(cacheRoot, { recursive: true });
-    writeTree(edgePlaySrc, EMBEDDED_SOURCES.edgePlay);
-    writeTree(constantsSrc, EMBEDDED_SOURCES.constants);
-    writeFileSync13(markerPath, `${cliVersion}
-`, "utf8");
+  const basePath = join28(monorepoRoot, "packages", packageName, "src");
+  const targetPath = pathParts.length > 0 ? join28(basePath, ...pathParts) : join28(basePath, "index");
+  for (const extension of WORKSPACE_SOURCE_EXTENSIONS) {
+    const withExtension = `${targetPath}${extension}`;
+    if (existsSync22(withExtension)) {
+      return withExtension;
+    }
+  }
+  for (const extension of WORKSPACE_SOURCE_EXTENSIONS) {
+    const indexPath = join28(targetPath, `index${extension}`);
+    if (existsSync22(indexPath)) {
+      return indexPath;
+    }
   }
-  cachedPaths = { edgePlaySrc, constantsSrc };
-  return cachedPaths;
+  return null;
+}
+function createWorkspaceSourceResolverPlugin(monorepoRoot) {
+  return {
+    name: "playcademy-workspace-source-resolver",
+    setup(build3) {
+      build3.onResolve({ filter: /^@playcademy\// }, (args) => {
+        const resolved = resolveWorkspaceSourceImport(monorepoRoot, args.path);
+        return resolved ? { path: resolved } : null;
+      });
+    }
+  };
+}
+async function writeRuntimeManifest(outdir, manifest) {
+  await writeFile4(
+    join28(outdir, BACKEND_RUNTIME_MANIFEST),
+    `${JSON.stringify(manifest, null, 2)}
+`,
+    "utf8"
+  );
+}
+async function buildBackendRuntime(outdir) {
+  const monorepoRoot = getMonorepoRoot();
+  const manifest = await getRuntimeBuildMetadata(monorepoRoot);
+  const runtimeEntry = join28(monorepoRoot, "packages", "edge-play", "src", "entry", "index.ts");
+  const polyfillsEntry = join28(monorepoRoot, "packages", "edge-play", "src", "polyfills.js");
+  const esbuild4 = await import("esbuild");
+  await rm2(outdir, { recursive: true, force: true });
+  await mkdir4(outdir, { recursive: true });
+  await esbuild4.build({
+    entryPoints: [runtimeEntry],
+    outfile: join28(outdir, BACKEND_RUNTIME_ENTRY),
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    write: true,
+    sourcemap: false,
+    minify: false,
+    logLevel: "error",
+    alias: createNodePolyfillAliases(polyfillsEntry),
+    plugins: [textLoaderPlugin(), createWorkspaceSourceResolverPlugin(monorepoRoot)],
+    define: {
+      PLAYCADEMY_RUNTIME_CLI_VERSION: JSON.stringify(manifest.cliVersion),
+      PLAYCADEMY_RUNTIME_SDK_VERSION: JSON.stringify(manifest.sdkVersion),
+      PLAYCADEMY_RUNTIME_BUILD_ID: JSON.stringify(manifest.runtimeBuildId)
+    }
+  });
+  await copyFile(polyfillsEntry, join28(outdir, BACKEND_RUNTIME_POLYFILLS));
+  await writeRuntimeManifest(outdir, manifest);
+  return manifest;
+}
+async function ensureDevBackendRuntime() {
+  const monorepoRoot = getMonorepoRoot();
+  const manifest = await getRuntimeBuildMetadata(monorepoRoot);
+  const runtimeDir = join28(
+    tmpdir3(),
+    DEV_RUNTIME_CACHE_DIR,
+    manifest.cliVersion,
+    manifest.inputFingerprint
+  );
+  if (!existsSync22(join28(runtimeDir, BACKEND_RUNTIME_MANIFEST))) {
+    await buildBackendRuntime(runtimeDir);
+  }
+  return runtimeDir;
+}
+async function readRuntimeManifest(runtimeDir) {
+  const content = await readFile4(join28(runtimeDir, BACKEND_RUNTIME_MANIFEST), "utf8");
+  return JSON.parse(content);
+}
+async function resolveBackendRuntimePaths() {
+  const workspace = getWorkspace();
+  const workspaceNodeModules = join28(workspace, "node_modules");
+  if (isCompiledBinary) {
+    const runtimeDir2 = extractEmbeddedBackendRuntime();
+    const manifest2 = await readRuntimeManifest(runtimeDir2);
+    const cliDepsRoot = join28(workspace, ".playcademy", "node_modules");
+    return {
+      runtimeDir: runtimeDir2,
+      runtimeEntry: join28(runtimeDir2, manifest2.entry),
+      polyfillsEntry: join28(runtimeDir2, manifest2.polyfills),
+      workspaceNodeModules,
+      cliDepsRoot,
+      manifest: manifest2
+    };
+  }
+  const monorepoRoot = getMonorepoRoot();
+  const runtimeDir = await ensureDevBackendRuntime();
+  const manifest = await readRuntimeManifest(runtimeDir);
+  return {
+    runtimeDir,
+    runtimeEntry: join28(runtimeDir, manifest.entry),
+    polyfillsEntry: join28(runtimeDir, manifest.polyfills),
+    workspaceNodeModules,
+    cliDepsRoot: monorepoRoot,
+    manifest
+  };
 }
 
 // src/lib/deploy/bundle.ts
@@ -6827,153 +7004,134 @@ async function discoverCustomRoutes(config) {
   const workspace = getWorkspace();
   const customRoutesConfig = config.integrations?.customRoutes;
   const customRoutesDir = typeof customRoutesConfig === "object" && customRoutesConfig.directory || DEFAULT_API_ROUTES_DIRECTORY;
-  const customRoutes = await discoverRoutes(join28(workspace, customRoutesDir));
+  const customRoutes = await discoverRoutes(join29(workspace, customRoutesDir));
   const customRouteData = customRoutes.map((r) => ({
     path: r.path,
     file: r.file,
-    // Use relative path (e.g., 'server/api/test.ts'), not absolute
+    // relative path (e.g., 'server/api/test.ts'), not absolute
     methods: r.methods
   }));
   return { customRouteData, customRoutesDir };
 }
-function resolveEmbeddedSourcePaths() {
-  const workspace = getWorkspace();
-  if (isCompiledBinary) {
-    const { edgePlaySrc: edgePlaySrc2, constantsSrc } = extractEmbeddedSources();
-    const constantsEntry2 = join28(constantsSrc, "index.ts");
-    const workspaceNodeModules2 = join28(workspace, "node_modules");
-    const playcademyNodeModules = join28(workspace, ".playcademy", "node_modules");
-    return {
-      isBuiltPackage: true,
-      edgePlaySrc: edgePlaySrc2,
-      constantsEntry: constantsEntry2,
-      workspaceNodeModules: workspaceNodeModules2,
-      cliDepsRoot: playcademyNodeModules
-    };
+function getForbiddenImportMessage(specifier) {
+  if (specifier === "@playcademy/sdk/server") {
+    return "Use `c.get('sdk')` instead of importing the server SDK directly.";
   }
-  const distDir = new URL(".", import.meta.url).pathname;
-  const embeddedEdgeSrc = join28(distDir, "edge-play", "src");
-  const isBuiltPackage = existsSync22(embeddedEdgeSrc);
-  const monorepoRoot = getMonorepoRoot();
-  const monorepoEdgeSrc = join28(monorepoRoot, "packages/edge-play/src");
-  const edgePlaySrc = isBuiltPackage ? embeddedEdgeSrc : monorepoEdgeSrc;
-  const cliPackageRoot = isBuiltPackage ? join28(distDir, "../../..") : join28(monorepoRoot, "packages/cli");
-  const cliDepsRoot = isBuiltPackage ? join28(cliPackageRoot, "node_modules") : monorepoRoot;
-  const workspaceNodeModules = join28(workspace, "node_modules");
-  const constantsEntry = isBuiltPackage ? join28(embeddedEdgeSrc, "..", "..", "constants", "src", "index.ts") : join28(monorepoRoot, "packages", "constants", "src", "index.ts");
+  if (specifier.startsWith("@playcademy/edge-play")) {
+    return "Built-in backend runtime helpers are internal to the CLI-owned runtime.";
+  }
+  return "CLI-owned backend runtime packages are not available to game backend code.";
+}
+function createForbiddenRuntimeImportsPlugin(workspace) {
   return {
-    isBuiltPackage,
-    edgePlaySrc,
-    constantsEntry,
-    workspaceNodeModules,
-    cliDepsRoot
+    name: "forbidden-backend-runtime-imports",
+    setup(build3) {
+      build3.onResolve(
+        {
+          filter: /^@playcademy\/(?:sdk\/server|edge-play(?:\/.*)?|constants(?:\/.*)?)$/
+        },
+        (args) => {
+          if (!args.importer) {
+            return null;
+          }
+          const importerPath = relative4(workspace, args.importer).replace(/\\/g, "/");
+          return {
+            errors: [
+              {
+                text: `Unsupported backend import "${args.path}" in ${importerPath}. ${getForbiddenImportMessage(args.path)} Use \`Context\`, \`c.env\`, \`c.get('sdk')\`, and \`c.get('playcademyUser')\` instead.`
+              }
+            ]
+          };
+        }
+      );
+    }
   };
 }
 function createEsbuildConfig(entryCode, paths, bundleConfig, customRoutesDir, options) {
   const workspace = getWorkspace();
-  const { edgePlaySrc, constantsEntry, workspaceNodeModules, cliDepsRoot } = paths;
+  const { runtimeEntry, polyfillsEntry, workspaceNodeModules, cliDepsRoot } = paths;
   return {
-    // ──── Input Configuration ────
+    // ──── Input: generated entry code, not a real file ────
+    // resolveDir = workspace so that bare specifiers in the generated code
+    // (e.g. '@game-api/save.ts') resolve relative to the user's project root.
     stdin: {
       contents: entryCode,
-      // Generated entry code with custom route imports
-      resolveDir: edgePlaySrc,
-      // Resolve relative imports from edge-play/src
+      resolveDir: workspace,
       loader: "ts"
-      // Treat input as TypeScript
     },
-    // ──── Output Configuration ────
+    // ──── Output configuration ────
     bundle: true,
-    // Bundle all dependencies into single file
     format: "esm",
-    // Output ES modules (required for Cloudflare Workers)
+    // Cloudflare Workers require ES modules
     platform: "browser",
-    // Workers use browser APIs, not Node.js
+    // Workers run in a browser-like environment, not Node.js
     target: "es2022",
-    // Modern JavaScript for Workers runtime
     write: false,
-    // Return code as string (don't write to disk)
+    // Return code as a string; the caller writes/uploads it
     sourcemap: options.sourcemap ? "inline" : false,
     minify: options.minify || false,
-    logLevel: "error",
-    // Only show errors (suppress warnings)
-    // ──── Module Resolution ────
-    // Tell esbuild where to find node_modules for bare imports
-    // Dev:       workspace node_modules + monorepo root (hoisted deps)
-    // Published: workspace node_modules + same (user's project)
-    // Binary:    workspace node_modules + .playcademy/node_modules (hono lives there)
+    logLevel: "silent",
+    // errors propagate as thrown exceptions; we don't want esbuild double-printing to stderr
+    // ──── Module resolution ────
+    // esbuild searches nodePaths in order for bare specifiers.
+    // workspaceNodeModules: game project's own deps (hono, etc. if user installed them)
+    // cliDepsRoot:          CLI-managed deps (.playcademy/node_modules in binary mode,
+    //                       monorepo root in dev mode) — where hono, @hono/node-server live
     nodePaths: [workspaceNodeModules, cliDepsRoot],
-    // ──── Build-time Constants ────
-    // Inject the Playcademy config as a global constant
-    // Code can access it via: const config = PLAYCADEMY_CONFIG
+    // ──── Build-time constants ────
+    // PLAYCADEMY_CONFIG is accessed as a global in the generated entry code and in
+    // the sealed runtime itself (passed to createBaseApp). It carries integrations
+    // config, route metadata, queue metadata, etc.
     define: {
       PLAYCADEMY_CONFIG: JSON.stringify(bundleConfig)
     },
-    // ──── Import Aliases ────
     alias: {
-      // ┌─ Workspace-only package resolution ─────────────────────────────┐
-      // │ @playcademy/constants is a workspace package that users don't   │
-      // │ install. We embed it in dist/ and alias imports to point there. │
-      // └─────────────────────────────────────────────────────────────────┘
-      "@playcademy/constants": constantsEntry,
-      // ┌─ Workspace-only edge-play package ──────────────────────────────┐
-      // │ @playcademy/edge-play is used in generated entry code for auth  │
-      // │ middleware. It's embedded in dist/ like constants.              │
-      // └─────────────────────────────────────────────────────────────────┘
-      "@playcademy/edge-play": edgePlaySrc,
-      // ┌─ User's custom routes ──────────────────────────────────────────┐
-      // │ @game-api is a virtual module that maps to the user's API dir.  │
-      // │ Example: import * as route from '@game-api/hello.ts'            │
-      // │ Resolves to: /user-project/server/api/hello.ts                  │
-      // └─────────────────────────────────────────────────────────────────┘
-      "@game-api": join28(workspace, customRoutesDir),
-      // ┌─ User's server lib directory ───────────────────────────────────┐
-      // │ @game-server is a virtual module for server utilities/config    │
-      // │ Example: import { getAuth } from '@game-server/lib/auth'        │
-      // │ Resolves to: /user-project/server/lib/auth.ts                   │
-      // └─────────────────────────────────────────────────────────────────┘
-      "@game-server": join28(workspace, "server"),
-      // ┌─ Node.js polyfills for Cloudflare Workers ──────────────────────┐
-      // │ Workers don't have fs, path, os, etc. Redirect to polyfills     │
-      // │ that throw helpful errors if user code tries to use them.       │
-      // └─────────────────────────────────────────────────────────────────┘
-      fs: join28(edgePlaySrc, "polyfills.js"),
-      "fs/promises": join28(edgePlaySrc, "polyfills.js"),
-      path: join28(edgePlaySrc, "polyfills.js"),
-      os: join28(edgePlaySrc, "polyfills.js"),
-      process: join28(edgePlaySrc, "polyfills.js")
+      // ┌─ Sealed backend runtime ────────────────────────────────────────────┐
+      // │ The pre-bundled artifact: edge-play + sdk/server + all internal     │
+      // │ @playcademy/* deps, zero external imports remaining. This alias     │
+      // │ is what enforces version isolation — game node_modules are ignored. │
+      // └─────────────────────────────────────────────────────────────────────┘
+      "@playcademy/backend-runtime": runtimeEntry,
+      // ┌─ Game's custom route files ─────────────────────────────────────────┐
+      // │ @game-api is a virtual module pointing to the game's API directory. │
+      // │ Example: import * as route from '@game-api/save.ts'                 │
+      // │ Resolves to: /user-project/server/api/save.ts                       │
+      // └─────────────────────────────────────────────────────────────────────┘
+      "@game-api": join29(workspace, customRoutesDir),
+      // ┌─ Game's server library directory ───────────────────────────────────┐
+      // │ @game-server is a virtual module for server-side utilities.         │
+      // │ Example: import { getAuth } from '@game-server/lib/auth'            │
+      // │ Resolves to: /user-project/server/lib/auth.ts                       │
+      // └─────────────────────────────────────────────────────────────────────┘
+      "@game-server": join29(workspace, "server"),
+      // ┌─ Node.js polyfills for Cloudflare Workers ──────────────────────────┐
+      // │ Workers don't have fs, path, os, process, etc. Redirect them to a   │
+      // │ polyfills stub bundled into the sealed runtime that throws a clear  │
+      // │ error if user code actually calls them at runtime.                  │
+      // └─────────────────────────────────────────────────────────────────────┘
+      ...createNodePolyfillAliases(polyfillsEntry)
     },
-    // ──── Build Plugins ────
-    plugins: [textLoaderPlugin()],
-    // Support Bun's 'with { type: "text" }' imports
-    // ──── External Dependencies ────
+    plugins: [createForbiddenRuntimeImportsPlugin(workspace)],
     external: []
-    // Bundle everything (no externals for Workers)
+    // Bundle everything — no externals allowed in Workers
   };
 }
-function loadEntryTemplate(paths) {
-  const entryPath = paths ? join28(paths.edgePlaySrc, "entry.ts") : join28(getMonorepoRoot(), "packages", "edge-play", "src", "entry.ts");
-  return readFileSync13(entryPath, "utf8");
-}
 async function bundleBackend(config, options = {}) {
   const esbuild4 = await import("esbuild");
   const { customRouteData, customRoutesDir } = await discoverCustomRoutes(config);
   const queueHandlers = discoverQueueHandlers();
   validateQueueHandlersConfig(config, queueHandlers);
-  const paths = resolveEmbeddedSourcePaths();
-  const entryTemplate = loadEntryTemplate(paths);
+  const paths = await resolveBackendRuntimePaths();
   const bundleConfig = {
     ...config,
     __routeMetadata: customRouteData,
     __queueMetadata: queueHandlers
   };
-  const hasAuth = Boolean(config.integrations?.auth);
   const entryCode = generateEntryCode(
     customRouteData,
     customRoutesDir,
     queueHandlers,
-    hasAuth,
-    entryTemplate
+    Boolean(config.integrations?.auth)
   );
   const buildConfig = createEsbuildConfig(
     entryCode,
@@ -6986,9 +7144,8 @@ async function bundleBackend(config, options = {}) {
   if (!result.outputFiles?.[0]) {
     throw new Error("Backend bundling failed: no output");
   }
-  const code = result.outputFiles[0].text;
   return {
-    code,
+    code: result.outputFiles[0].text,
     config,
     customRoutes: customRouteData
   };
@@ -6996,50 +7153,69 @@ async function bundleBackend(config, options = {}) {
 function buildCustomRouteImportStatements(customRoutes, customRoutesDir) {
   const normalizedRoutesDir = customRoutesDir.replace(/\\/g, "/").replace(/\/+/g, "/");
   const customRoutesPrefix = normalizedRoutesDir.endsWith("/") ? normalizedRoutesDir : `${normalizedRoutesDir}/`;
-  return customRoutes.map((route, i) => {
+  return customRoutes.map((route, index2) => {
     const normalizedFile = route.file.replace(/\\/g, "/").replace(/\/+/g, "/");
     const importPath = normalizedFile.startsWith(customRoutesPrefix) ? normalizedFile.slice(customRoutesPrefix.length) : normalizedFile;
-    return `import * as customRoute${i} from '@game-api/${importPath}'`;
+    return `import * as customRoute${index2} from '@game-api/${importPath}'`;
   }).join("\n");
 }
-function generateEntryCode(customRoutes, customRoutesDir, queueHandlers, hasAuth, entryTemplateInput = loadEntryTemplate()) {
-  const importStatements = customRoutes.length > 0 ? buildCustomRouteImportStatements(customRoutes, customRoutesDir) : "// No custom routes";
-  const queueImportStatements = buildQueueImportStatements(queueHandlers);
-  const withCustomRouteImports = entryTemplateInput.replace(
-    "// \u26A0\uFE0F BUILD_MARKER: CUSTOM_ROUTE_IMPORTS \u26A0\uFE0F",
-    importStatements
-  );
-  const withImports = withCustomRouteImports.replace(
-    "// \u26A0\uFE0F BUILD_MARKER: QUEUE_HANDLER_IMPORTS \u26A0\uFE0F",
-    queueImportStatements
-  );
-  const registrationStatements = customRoutes.length > 0 ? customRoutes.flatMap((route, i) => {
-    const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"];
-    return methods.map((method) => {
-      const methodLower = method.toLowerCase();
-      return `if (customRoute${i}.${method}) app.${methodLower}('${route.path}', customRoute${i}.${method})`;
-    });
-  }) : [];
-  const registrationCode = registrationStatements.length > 0 ? ["// Custom routes", ...registrationStatements, ""].join("\n") : "// No custom routes\n";
-  const withRoutes = withImports.replace("// \u26A0\uFE0F BUILD_MARKER: CUSTOM_ROUTES \u26A0\uFE0F", registrationCode);
-  const queueHandlerCode = buildQueueHandlerCode(queueHandlers);
-  const withQueueHandlers = withRoutes.replace(
-    "// \u26A0\uFE0F BUILD_MARKER: QUEUE_HANDLER \u26A0\uFE0F",
-    queueHandlerCode
-  );
-  const exportCode = buildWorkerExportCode(queueHandlers);
-  const withExport = withQueueHandlers.replace("// \u26A0\uFE0F BUILD_MARKER: WORKER_EXPORT \u26A0\uFE0F", exportCode);
-  const sessionMiddlewareStatements = hasAuth ? [
-    "import { createSessionMiddleware } from '@playcademy/edge-play'",
-    "import { getAuth } from '@game-server/lib/auth'",
-    "app.use('*', createSessionMiddleware(getAuth))"
-  ] : [];
-  const sessionMiddlewareCode = sessionMiddlewareStatements.join("\n");
-  const result = withExport.replace(
-    "// \u26A0\uFE0F BUILD_MARKER: SESSION_MIDDLEWARE \u26A0\uFE0F",
-    sessionMiddlewareCode
+function buildCustomRouteModuleCode(customRoutes) {
+  if (customRoutes.length === 0) {
+    return "const __customRoutes = []";
+  }
+  return [
+    "const __customRoutes = [",
+    ...customRoutes.map(
+      (route, index2) => `    { path: ${JSON.stringify(route.path)}, module: customRoute${index2} },`
+    ),
+    "]"
+  ].join("\n");
+}
+function generateEntryCode(customRoutes, customRoutesDir, queueHandlers, hasAuth = false) {
+  const runtimeImports = [
+    "createBaseApp",
+    "registerBuiltinRoutes",
+    "registerCustomRouteModules",
+    "registerTerminalHandlers"
+  ];
+  if (hasAuth) {
+    runtimeImports.push("createSessionMiddleware");
+  }
+  if (queueHandlers.length > 0) {
+    runtimeImports.push("createQueueRouter", "registerQueueIngressRoute");
+  }
+  const importBlocks = [
+    `import { ${runtimeImports.join(", ")} } from '@playcademy/backend-runtime'`
+  ];
+  if (hasAuth) {
+    importBlocks.push("import { getAuth } from '@game-server/lib/auth'");
+  }
+  if (customRoutes.length > 0) {
+    importBlocks.push(buildCustomRouteImportStatements(customRoutes, customRoutesDir));
+  }
+  if (queueHandlers.length > 0) {
+    importBlocks.push(buildQueueImportStatements(queueHandlers));
+  }
+  const body = [
+    "// PLAYCADEMY_CONFIG is injected at bundle time via esbuild define",
+    "const app = createBaseApp(PLAYCADEMY_CONFIG)",
+    ""
+  ];
+  if (hasAuth) {
+    body.push("app.use('*', createSessionMiddleware(getAuth))", "");
+  }
+  body.push(
+    "await registerBuiltinRoutes(app, PLAYCADEMY_CONFIG.integrations)",
+    "",
+    buildCustomRouteModuleCode(customRoutes),
+    "registerCustomRouteModules(app, __customRoutes)",
+    "",
+    buildQueueHandlerCode(queueHandlers),
+    "registerTerminalHandlers(app)",
+    "",
+    buildWorkerExportCode(queueHandlers)
   );
-  return result;
+  return [...importBlocks, "", ...body].join("\n");
 }
 
 // src/lib/dev/server.ts
@@ -7159,9 +7335,9 @@ async function startDevServer(options) {
   return { server: mf, port };
 }
 async function ensureDatabaseDirectory() {
-  const dbDir = join29(getWorkspace(), CLI_DIRECTORIES.DATABASE);
+  const dbDir = join30(getWorkspace(), CLI_DIRECTORIES.DATABASE);
   try {
-    await mkdir4(dbDir, { recursive: true });
+    await mkdir5(dbDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create database directory: ${getErrorMessage(error)}`, {
       cause: error
@@ -7170,9 +7346,9 @@ async function ensureDatabaseDirectory() {
   return dbDir;
 }
 async function ensureKvDirectory() {
-  const kvDir = join29(getWorkspace(), CLI_DIRECTORIES.KV);
+  const kvDir = join30(getWorkspace(), CLI_DIRECTORIES.KV);
   try {
-    await mkdir4(kvDir, { recursive: true });
+    await mkdir5(kvDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create KV directory: ${getErrorMessage(error)}`, {
       cause: error
@@ -7181,9 +7357,9 @@ async function ensureKvDirectory() {
   return kvDir;
 }
 async function ensureBucketDirectory() {
-  const bucketDir = join29(getWorkspace(), CLI_DIRECTORIES.BUCKET);
+  const bucketDir = join30(getWorkspace(), CLI_DIRECTORIES.BUCKET);
   try {
-    await mkdir4(bucketDir, { recursive: true });
+    await mkdir5(bucketDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create bucket directory: ${getErrorMessage(error)}`, {
       cause: error
@@ -7554,13 +7730,13 @@ import { confirm as confirm6, input as input3, select as select5 } from "@inquir
 
 // src/lib/deploy/build-discovery.ts
 init_file_loader();
-import { join as join30, relative as relative4 } from "path";
+import { join as join31, relative as relative5 } from "path";
 function findSingleBuildZip() {
   const workspace = getWorkspace();
-  const playcademyDir = join30(workspace, CLI_DIRECTORIES.WORKSPACE);
+  const playcademyDir = join31(workspace, CLI_DIRECTORIES.WORKSPACE);
   const zipFiles = findFilesByExtension(playcademyDir, "zip");
   if (zipFiles.length === 1) {
-    return zipFiles[0] ? relative4(workspace, zipFiles[0]) : null;
+    return zipFiles[0] ? relative5(workspace, zipFiles[0]) : null;
   }
   return null;
 }
@@ -7568,12 +7744,12 @@ function findSingleBuildZip() {
 // src/lib/deploy/schema.ts
 import { existsSync as existsSync24 } from "fs";
 import { createRequire } from "module";
-import { join as join32 } from "path";
+import { join as join33 } from "path";
 
 // src/lib/deploy/migrations.ts
 import { existsSync as existsSync23 } from "fs";
-import { readFile as readFile4 } from "fs/promises";
-import { join as join31 } from "path";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join32 } from "path";
 import { bold as bold8 } from "colorette";
 
 // src/lib/deploy/utils.ts
@@ -7595,25 +7771,25 @@ function getDeploymentId(gameSlug) {
 }
 
 // src/lib/deploy/migrations.ts
-var DB_RELATIVE_CANDIDATES = ["migrations", join31("..", "migrations"), "drizzle"];
-var ROOT_RELATIVE_CANDIDATES = [join31("db", "migrations"), "drizzle"];
+var DB_RELATIVE_CANDIDATES = ["migrations", join32("..", "migrations"), "drizzle"];
+var ROOT_RELATIVE_CANDIDATES = [join32("db", "migrations"), "drizzle"];
 var META_DIR = "meta";
 var JOURNAL_FILE = "_journal.json";
 var STATEMENT_BREAKPOINT_RE = /--> statement-breakpoint/g;
 async function getMigrationsDirectory() {
   const workspace = getWorkspace();
   const dbDirectory = await getDatabaseDirectory();
-  const dbDirAbs = join31(workspace, dbDirectory);
+  const dbDirAbs = join32(workspace, dbDirectory);
   for (const candidate of DB_RELATIVE_CANDIDATES) {
-    const candidateAbs = join31(dbDirAbs, candidate);
-    const journalPath = join31(candidateAbs, META_DIR, JOURNAL_FILE);
+    const candidateAbs = join32(dbDirAbs, candidate);
+    const journalPath = join32(candidateAbs, META_DIR, JOURNAL_FILE);
     if (existsSync23(journalPath)) {
       return candidateAbs;
     }
   }
   for (const candidate of ROOT_RELATIVE_CANDIDATES) {
-    const candidateAbs = join31(workspace, candidate);
-    const journalPath = join31(candidateAbs, META_DIR, JOURNAL_FILE);
+    const candidateAbs = join32(workspace, candidate);
+    const journalPath = join32(candidateAbs, META_DIR, JOURNAL_FILE);
     if (existsSync23(journalPath)) {
       return candidateAbs;
     }
@@ -7643,9 +7819,9 @@ async function readMigrationJournal() {
   if (!migrationsDir) {
     return null;
   }
-  const journalPath = join31(migrationsDir, META_DIR, JOURNAL_FILE);
+  const journalPath = join32(migrationsDir, META_DIR, JOURNAL_FILE);
   try {
-    const raw = await readFile4(journalPath, "utf8");
+    const raw = await readFile5(journalPath, "utf8");
     const journal = JSON.parse(raw);
     if (!Array.isArray(journal.entries)) {
       logger.warn("Migration journal has no entries array");
@@ -7689,14 +7865,14 @@ async function getUnappliedMigrations(lastAppliedTag) {
   }
   const results = [];
   for (const entry of unapplied) {
-    const sqlPath = join31(migrationsDir, `${entry.tag}.sql`);
+    const sqlPath = join32(migrationsDir, `${entry.tag}.sql`);
     if (!existsSync23(sqlPath)) {
       throw new Error(
         `Migration file not found: ${sqlPath}
 The journal references migration "${entry.tag}" but the .sql file is missing.`
       );
     }
-    const raw = await readFile4(sqlPath, "utf8");
+    const raw = await readFile5(sqlPath, "utf8");
     const sql2 = raw.replace(STATEMENT_BREAKPOINT_RE, "").trim();
     results.push({ tag: entry.tag, sql: sql2 });
   }
@@ -7800,7 +7976,7 @@ async function loadAndValidateMigrations(workspace) {
 // src/lib/deploy/schema.ts
 function getDrizzleKitApiExports() {
   try {
-    const projectRequire = createRequire(join32(process.cwd(), "package.json"));
+    const projectRequire = createRequire(join33(process.cwd(), "package.json"));
     return projectRequire("drizzle-kit/api");
   } catch {
     const cliRequire = createRequire(import.meta.url);
@@ -7810,7 +7986,7 @@ function getDrizzleKitApiExports() {
 async function getPushSchemaInfo(previousSchemaSnapshot) {
   const workspace = getWorkspace();
   const dbDirectory = await getDatabaseDirectory();
-  const schemaPath = join32(workspace, dbDirectory, SCHEMA_SUBDIRECTORY, DB_FILES.SCHEMA_INDEX);
+  const schemaPath = join33(workspace, dbDirectory, SCHEMA_SUBDIRECTORY, DB_FILES.SCHEMA_INDEX);
   if (!existsSync24(schemaPath)) {
     return null;
   }
@@ -8293,7 +8469,7 @@ function logDeploymentPlanDebug(plan, context2) {
 
 // src/lib/deploy/preparation.ts
 import { stat } from "node:fs/promises";
-import { join as join33 } from "node:path";
+import { join as join34 } from "node:path";
 
 // ../data/src/domains/game/helpers.ts
 function isHostedGame(game) {
@@ -8906,8 +9082,8 @@ async function bundleAndHash(context2) {
     const bundle = await bundleBackend(context2.fullConfig);
     const bundleHash = hashContent(bundle.code);
     const [serverSize, dbSize] = await Promise.all([
-      getDirectorySize(join33(context2.projectPath, SERVER_ROOT_DIRECTORY)),
-      getDirectorySize(join33(context2.projectPath, DEFAULT_DATABASE_DIRECTORY))
+      getDirectorySize(join34(context2.projectPath, SERVER_ROOT_DIRECTORY)),
+      getDirectorySize(join34(context2.projectPath, DEFAULT_DATABASE_DIRECTORY))
     ]);
     context2.currentBackendBundle = bundle;
     context2.currentBackendBundleHash = bundleHash;
@@ -9082,8 +9258,8 @@ function hasOptionalFieldsMissing(missing) {
 
 // src/lib/deploy/steps.ts
 import { existsSync as existsSync26 } from "fs";
-import { readFile as readFile5 } from "fs/promises";
-import { basename as basename2, join as join34, resolve as resolve11 } from "path";
+import { readFile as readFile6 } from "fs/promises";
+import { basename as basename2, join as join35, resolve as resolve11 } from "path";
 
 // src/lib/deploy/stub.ts
 import * as esbuild3 from "esbuild";
@@ -9129,7 +9305,7 @@ function prepareGameMetadata(config) {
 async function prepareBuildFile(buildPath) {
   const resolvedPath = resolve11(buildPath);
   if (resolvedPath.endsWith(".zip") && existsSync26(resolvedPath)) {
-    const buffer = await readFile5(resolvedPath);
+    const buffer = await readFile6(resolvedPath);
     const uint8Array = new Uint8Array(buffer);
     const blob = new Blob([uint8Array], { type: "application/zip" });
     return new File([blob], basename2(resolvedPath), { type: "application/zip" });
@@ -9305,8 +9481,8 @@ async function deployGame(context2, shouldUploadBuild, shouldDeployBackend) {
       schema: deploymentPrep.schemaInfo || void 0
     };
     const [serverSize, dbSize] = await Promise.all([
-      getDirectorySize(join34(context2.projectPath, SERVER_ROOT_DIRECTORY)),
-      getDirectorySize(join34(context2.projectPath, DEFAULT_DATABASE_DIRECTORY))
+      getDirectorySize(join35(context2.projectPath, SERVER_ROOT_DIRECTORY)),
+      getDirectorySize(join35(context2.projectPath, DEFAULT_DATABASE_DIRECTORY))
     ]);
     const isMigrateMode = Boolean(deploymentPrep.schemaInfo?.migrationTag);
     backendMetadata = {
@@ -9368,7 +9544,7 @@ async function deployGame(context2, shouldUploadBuild, shouldDeployBackend) {
 
 // src/lib/db/path.ts
 import { copyFileSync, existsSync as existsSync27, mkdirSync as mkdirSync9, readdirSync as readdirSync4, unlinkSync } from "fs";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 var DB_DIRECTORY = CLI_DIRECTORIES.DATABASE;
 var INITIAL_DB_NAME = CLI_FILES.INITIAL_DATABASE;
 function ensureDirectoryExists(dir) {
@@ -9377,7 +9553,7 @@ function ensureDirectoryExists(dir) {
   }
 }
 function findMiniflareDatabase(dbDir) {
-  const miniflareDir = join35(dbDir, MINIFLARE_D1_DIRECTORY);
+  const miniflareDir = join36(dbDir, MINIFLARE_D1_DIRECTORY);
   if (!existsSync27(miniflareDir)) {
     return null;
   }
@@ -9385,7 +9561,7 @@ function findMiniflareDatabase(dbDir) {
   if (sqliteFiles.length === 0) {
     return null;
   }
-  return join35(miniflareDir, sqliteFiles[0]);
+  return join36(miniflareDir, sqliteFiles[0]);
 }
 function migrateInitialDbToTarget(initialPath, targetPath) {
   if (!existsSync27(initialPath)) {
@@ -9395,7 +9571,7 @@ function migrateInitialDbToTarget(initialPath, targetPath) {
   unlinkSync(initialPath);
 }
 function getDevDbPath() {
-  const initialDbPath = join35(DB_DIRECTORY, INITIAL_DB_NAME);
+  const initialDbPath = join36(DB_DIRECTORY, INITIAL_DB_NAME);
   ensureDirectoryExists(DB_DIRECTORY);
   const miniflareDbPath = findMiniflareDatabase(DB_DIRECTORY);
   if (miniflareDbPath) {
@@ -9634,10 +9810,10 @@ async function bundleSeedWorker(seedFilePath, projectPath) {
 // src/lib/db/reset.ts
 import { execSync as execSync7 } from "child_process";
 import { rmSync as rmSync3 } from "fs";
-import { join as join36 } from "path";
+import { join as join37 } from "path";
 async function resetDatabase(workspace, mf, options = { debug: false }) {
   const { debug } = options;
-  const dbDir = join36(workspace, CLI_DIRECTORIES.DATABASE);
+  const dbDir = join37(workspace, CLI_DIRECTORIES.DATABASE);
   await runStep(
     "Resetting database...",
     async () => {
@@ -10080,14 +10256,14 @@ function getCallbackUrl() {
 }
 
 // src/lib/bucket/bulk.ts
-import { readFileSync as readFileSync14 } from "fs";
+import { readFileSync as readFileSync13 } from "fs";
 import { dim as dim9 } from "colorette";
 
 // src/lib/bucket/collect.ts
 import { readdirSync as readdirSync5, statSync as statSync3 } from "fs";
-import { join as join37, relative as relative5, sep as sep2 } from "path";
+import { join as join38, relative as relative6, sep as sep2 } from "path";
 function shouldSkipFile(filePath, baseDir, gitignorePatterns) {
-  const relativePath = relative5(baseDir, filePath);
+  const relativePath = relative6(baseDir, filePath);
   const pathParts = relativePath.split(sep2);
   const alwaysSkip = BUCKET_ALWAYS_SKIP;
   for (const part of pathParts) {
@@ -10102,7 +10278,7 @@ function collectFiles(directory, baseDir, gitignorePatterns) {
   try {
     const entries = readdirSync5(directory, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join37(directory, entry.name);
+      const fullPath = join38(directory, entry.name);
       if (!shouldSkipFile(fullPath, baseDir, gitignorePatterns)) {
         if (entry.isDirectory()) {
           files.push(...collectFiles(fullPath, baseDir, gitignorePatterns));
@@ -10110,7 +10286,7 @@ function collectFiles(directory, baseDir, gitignorePatterns) {
           const stats = statSync3(fullPath);
           files.push({
             absolutePath: fullPath,
-            relativePath: relative5(baseDir, fullPath),
+            relativePath: relative6(baseDir, fullPath),
             size: stats.size
           });
         }
@@ -10208,7 +10384,7 @@ async function uploadFilesRemote(files, gameSlug, prefix, uploadFn) {
     `Uploading ${files.length} files ${dim9(`[${formatBytes(totalSize)}]`)}`,
     async () => {
       for (const file of files) {
-        const fileBuffer = readFileSync14(file.absolutePath);
+        const fileBuffer = readFileSync13(file.absolutePath);
         const contentType = getContentType(file.absolutePath);
         const key = getBucketKey(file.relativePath, prefix);
         await uploadFn(gameSlug, key, fileBuffer, contentType);
@@ -10224,7 +10400,7 @@ async function uploadFilesLocal(files, prefix, uploadFn) {
     `Uploading ${files.length} files ${dim9(`[${formatBytes(totalSize)}]`)}`,
     async () => {
       for (const file of files) {
-        const fileBuffer = readFileSync14(file.absolutePath);
+        const fileBuffer = readFileSync13(file.absolutePath);
         const contentType = getContentType(file.absolutePath);
         const key = getBucketKey(file.relativePath, prefix);
         await uploadFn(key, new Uint8Array(fileBuffer).buffer, contentType);
@@ -11019,6 +11195,39 @@ function normalizeVersion(version) {
   }
   return trimmed.replace(/^[vV]/, "");
 }
+function parseVersion(v) {
+  const [version, ...pre] = v.split("-");
+  const parts = version.split(".").map(Number);
+  if (parts.some((n) => Number.isNaN(n))) {
+    return null;
+  }
+  return { parts, prerelease: pre.length > 0 ? pre.join("-") : null };
+}
+function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) {
+    return 0;
+  }
+  const maxLen = Math.max(va.parts.length, vb.parts.length);
+  for (let i = 0; i < maxLen; i++) {
+    const pa = va.parts[i] ?? 0;
+    const pb = vb.parts[i] ?? 0;
+    if (pa > pb) {
+      return 1;
+    }
+    if (pa < pb) {
+      return -1;
+    }
+  }
+  if (!va.prerelease && vb.prerelease) {
+    return 1;
+  }
+  if (va.prerelease && !vb.prerelease) {
+    return -1;
+  }
+  return 0;
+}
 async function fetchLatestVersion() {
   const response = await fetch(LATEST_VERSION_URL);
   if (!response.ok) {
@@ -11055,6 +11264,7 @@ export {
   collectBulkFiles,
   collectFiles,
   compareIntegrationKeys,
+  compareVersions,
   computeSecretsDiff,
   computeSecretsHashes,
   confirmDeploymentPlan,