playcademy 0.13.1 → 0.13.3

package/dist/constants.d.ts

@@ -72,8 +72,6 @@ declare const CLI_FILES: {
     readonly AUTH_STORE: "auth.json";
     /** Games deployment info store */
     readonly GAMES_STORE: "games.json";
-    /** Dev server PID file */
-    readonly DEV_SERVER_PID: "dev-server.pid";
     /** Initial database file (before miniflare) */
     readonly INITIAL_DATABASE: "initial.sqlite";
 };

package/dist/constants.js

@@ -35,8 +35,6 @@ var CLI_FILES = {
   AUTH_STORE: "auth.json",
   /** Games deployment info store */
   GAMES_STORE: "games.json",
-  /** Dev server PID file */
-  DEV_SERVER_PID: "dev-server.pid",
   /** Initial database file (before miniflare) */
   INITIAL_DATABASE: "initial.sqlite"
 };

package/dist/db.js

@@ -39,8 +39,6 @@ var CLI_FILES = {
   AUTH_STORE: "auth.json",
   /** Games deployment info store */
   GAMES_STORE: "games.json",
-  /** Dev server PID file */
-  DEV_SERVER_PID: "dev-server.pid",
   /** Initial database file (before miniflare) */
   INITIAL_DATABASE: "initial.sqlite"
 };

package/dist/index.js

@@ -2145,8 +2145,6 @@ var init_paths = __esm({
       AUTH_STORE: "auth.json",
       /** Games deployment info store */
       GAMES_STORE: "games.json",
-      /** Dev server PID file */
-      DEV_SERVER_PID: "dev-server.pid",
       /** Initial database file (before miniflare) */
       INITIAL_DATABASE: "initial.sqlite"
     };
@@ -3726,7 +3724,7 @@ import { program } from "commander";
 
 // src/commands/init/index.ts
 import { execSync as execSync3 } from "child_process";
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
 import { resolve as resolve10 } from "path";
 
 // ../../node_modules/@inquirer/core/dist/esm/lib/errors.js
@@ -5441,7 +5439,6 @@ import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { bold as bold3, cyan as cyan2 } from "colorette";
 
 // src/lib/init/scaffold.ts
-init_src();
 init_constants2();
 init_core();
 init_loader2();
@@ -5454,21 +5451,15 @@ var playcademyGitignoreTemplate = loadTemplateString("playcademy-gitignore");
 async function scaffoldApiDirectory(apiDirectory, sampleRoutes) {
   const apiPath = resolve6(getWorkspace(), apiDirectory);
   const samplePath = join9(apiPath, "sample");
-  await runStep(
-    "Scaffolding API directory",
-    async () => {
-      if (!existsSync8(apiPath)) {
-        mkdirSync3(apiPath, { recursive: true });
-      }
-      if (!existsSync8(samplePath)) {
-        mkdirSync3(samplePath, { recursive: true });
-      }
-      for (const route of sampleRoutes) {
-        writeFileSync3(join9(samplePath, route.filename), route.template, "utf-8");
-      }
-    },
-    "API directory scaffolded"
-  );
+  if (!existsSync8(apiPath)) {
+    mkdirSync3(apiPath, { recursive: true });
+  }
+  if (!existsSync8(samplePath)) {
+    mkdirSync3(samplePath, { recursive: true });
+  }
+  for (const route of sampleRoutes) {
+    writeFileSync3(join9(samplePath, route.filename), route.template, "utf-8");
+  }
 }
 function validateApiDirectoryDoesNotExist(value) {
   const dirPath = resolve6(getWorkspace(), value.trim());
@@ -5486,7 +5477,8 @@ function ensurePlaycademyGitignore() {
   const gitignorePath = join9(playcademyDir, ".gitignore");
   writeFileSync3(gitignorePath, playcademyGitignoreTemplate);
 }
-async function scaffoldIntegrations(customRoutes, database, kv, gameName) {
+async function scaffoldIntegrations(gameName, options) {
+  const { customRoutes, database, kv } = options;
   ensurePlaycademyGitignore();
   if (customRoutes) {
     const sampleRoutes = [
@@ -7570,58 +7562,10 @@ function displayRegisteredRoutes(integrations, customRoutes = []) {
   }
 }
 
-// src/lib/dev/pid.ts
-init_constants2();
-init_core();
-import { existsSync as existsSync15, readFileSync as readFileSync4, unlinkSync as unlinkSync2 } from "fs";
-import { mkdir as mkdir4, unlink, writeFile as writeFile4 } from "fs/promises";
-import { join as join15 } from "path";
-function getDevServerPidPath() {
-  return join15(getWorkspace(), CLI_DIRECTORIES.WORKSPACE, CLI_FILES.DEV_SERVER_PID);
-}
-async function createDevServerPidFile() {
-  const pidPath = getDevServerPidFile();
-  const pidDir = join15(getWorkspace(), CLI_DIRECTORIES.WORKSPACE);
-  await mkdir4(pidDir, { recursive: true });
-  await writeFile4(pidPath, process.pid.toString());
-}
-async function removeDevServerPidFile() {
-  const pidPath = getDevServerPidFile();
-  if (existsSync15(pidPath)) {
-    await unlink(pidPath);
-  }
-}
-function isDevServerRunning() {
-  const pidPath = getDevServerPidFile();
-  if (!existsSync15(pidPath)) {
-    return false;
-  }
-  try {
-    const pid = parseInt(readFileSync4(pidPath, "utf8").trim(), 10);
-    if (process.platform === "win32") {
-      return true;
-    } else {
-      try {
-        process.kill(pid, 0);
-        return true;
-      } catch {
-        unlinkSync2(pidPath);
-        return false;
-      }
-    }
-  } catch {
-    unlinkSync2(pidPath);
-    return false;
-  }
-}
-function getDevServerPidFile() {
-  return getDevServerPidPath();
-}
-
 // src/lib/dev/reload.ts
 init_constants2();
 init_core();
-import { join as join16, relative as relative3 } from "path";
+import { join as join15, relative as relative3 } from "path";
 import chokidar from "chokidar";
 import { bold as bold4, cyan as cyan3, dim as dim6, green as green3 } from "colorette";
 function formatTime() {
@@ -7638,9 +7582,9 @@ function startHotReload(onReload, options = {}) {
   const customRoutesConfig = options.config?.integrations?.customRoutes;
   const customRoutesDir = typeof customRoutesConfig === "object" && customRoutesConfig.directory || DEFAULT_API_ROUTES_DIRECTORY;
   const watchPaths = [
-    join16(workspace, customRoutesDir),
-    join16(workspace, "playcademy.config.js"),
-    join16(workspace, "playcademy.config.json")
+    join15(workspace, customRoutesDir),
+    join15(workspace, "playcademy.config.js"),
+    join15(workspace, "playcademy.config.json")
   ];
   const watcher = chokidar.watch(watchPaths, {
     persistent: true,
@@ -7681,18 +7625,134 @@ function startHotReload(onReload, options = {}) {
 
 // src/lib/dev/server.ts
 init_src2();
+import { mkdir as mkdir4 } from "fs/promises";
+import { join as join17 } from "path";
+import { Miniflare } from "miniflare";
+
+// ../utils/src/port.ts
+import { existsSync as existsSync15, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { createServer as createServer2 } from "node:net";
+import { homedir as homedir3 } from "node:os";
+import { join as join16 } from "node:path";
+async function isPortAvailableOnHost(port, host) {
+  return new Promise((resolve11) => {
+    const server = createServer2();
+    server.once("error", () => {
+      resolve11(false);
+    });
+    server.once("listening", () => {
+      server.close();
+      resolve11(true);
+    });
+    server.listen(port, host);
+  });
+}
+async function findAvailablePort(startPort = 4321) {
+  const allInterfacesAvailable = await isPortAvailableOnHost(startPort, "0.0.0.0");
+  const ipv6Available = await isPortAvailableOnHost(startPort, "::1");
+  if (allInterfacesAvailable && ipv6Available) {
+    return startPort;
+  }
+  return findAvailablePort(startPort + 1);
+}
+function getRegistryPath() {
+  const home = homedir3();
+  const dir = join16(home, ".playcademy");
+  if (!existsSync15(dir)) {
+    mkdirSync4(dir, { recursive: true });
+  }
+  return join16(dir, ".proc");
+}
+function readRegistry() {
+  const registryPath = getRegistryPath();
+  if (!existsSync15(registryPath)) {
+    return {};
+  }
+  try {
+    const content = readFileSync4(registryPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+function writeRegistry(registry) {
+  const registryPath = getRegistryPath();
+  writeFileSync4(registryPath, JSON.stringify(registry, null, 2), "utf-8");
+}
+function getServerKey(type, port) {
+  return `${type}-${port}`;
+}
+function writeServerInfo(type, info) {
+  const registry = readRegistry();
+  const key = getServerKey(type, info.port);
+  registry[key] = info;
+  writeRegistry(registry);
+}
+function readServerInfo(type, projectRoot) {
+  const registry = readRegistry();
+  const servers = Object.entries(registry).filter(([key]) => key.startsWith(`${type}-`)).map(([, info]) => info);
+  if (servers.length === 0) {
+    return null;
+  }
+  if (projectRoot) {
+    const match = servers.find((s) => s.projectRoot === projectRoot);
+    return match || null;
+  }
+  return servers[0] || null;
+}
+function isServerRunning(type, projectRoot) {
+  const info = readServerInfo(type, projectRoot);
+  if (!info) {
+    return false;
+  }
+  try {
+    if (process.platform === "win32") {
+      return true;
+    } else {
+      process.kill(info.pid, 0);
+      return true;
+    }
+  } catch {
+    cleanupServerInfo(type, projectRoot);
+    return false;
+  }
+}
+function cleanupServerInfo(type, projectRoot, pid) {
+  const registry = readRegistry();
+  const keysToRemove = [];
+  for (const [key, info] of Object.entries(registry)) {
+    if (key.startsWith(`${type}-`)) {
+      let matches = true;
+      if (projectRoot && info.projectRoot !== projectRoot) {
+        matches = false;
+      }
+      if (pid !== void 0 && info.pid !== pid) {
+        matches = false;
+      }
+      if (matches) {
+        keysToRemove.push(key);
+      }
+    }
+  }
+  for (const key of keysToRemove) {
+    delete registry[key];
+  }
+  if (keysToRemove.length > 0) {
+    writeRegistry(registry);
+  }
+}
+
+// src/lib/dev/server.ts
 init_constants2();
 init_loader();
 init_core();
-import { mkdir as mkdir5 } from "fs/promises";
-import { join as join17 } from "path";
-import { Miniflare } from "miniflare";
 async function startDevServer(options) {
   const {
-    port,
+    port: preferredPort,
     config: providedConfig,
     platformUrl = process.env.PLAYCADEMY_BASE_URL || "http://localhost:5174"
   } = options;
+  const port = await findAvailablePort(preferredPort);
   const config = providedConfig ?? await loadConfig();
   const hasSandboxTimebackCreds = !!process.env.TIMEBACK_API_CLIENT_ID;
   const devConfig = config.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
@@ -7727,12 +7787,13 @@ async function startDevServer(options) {
   if (hasDatabase) {
     await initializeDatabase(mf);
   }
+  await writeBackendServerInfo(port);
   return mf;
 }
 async function ensureDatabaseDirectory() {
   const dbDir = join17(getWorkspace(), CLI_DIRECTORIES.DATABASE);
   try {
-    await mkdir5(dbDir, { recursive: true });
+    await mkdir4(dbDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create database directory: ${getErrorMessage(error)}`);
   }
@@ -7741,7 +7802,7 @@ async function ensureDatabaseDirectory() {
 async function ensureKvDirectory() {
   const kvDir = join17(getWorkspace(), CLI_DIRECTORIES.KV);
   try {
-    await mkdir5(kvDir, { recursive: true });
+    await mkdir4(kvDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create KV directory: ${getErrorMessage(error)}`);
   }
@@ -7750,7 +7811,15 @@ async function ensureKvDirectory() {
 async function initializeDatabase(mf) {
   const d1 = await mf.getD1Database("DB");
   await d1.exec("SELECT 1");
-  await createDevServerPidFile();
+}
+async function writeBackendServerInfo(port) {
+  writeServerInfo("backend", {
+    pid: process.pid,
+    port,
+    url: `http://localhost:${port}/api`,
+    startedAt: Date.now(),
+    projectRoot: getWorkspace()
+  });
 }
 
 // src/lib/timeback/cleanup.ts
@@ -7816,7 +7885,7 @@ function displayResourcesStatus(resources, logger2) {
 }
 
 // src/commands/init/config.ts
-import { writeFileSync as writeFileSync4 } from "fs";
+import { writeFileSync as writeFileSync5 } from "fs";
 import { resolve as resolve9 } from "path";
 init_file_loader();
 init_constants2();
@@ -7868,7 +7937,7 @@ var configCommand = new Command("config").description("Create playcademy.config
       emoji: gameInfo.emoji,
       timeback: timebackConfig ?? void 0
     });
-    writeFileSync4(resolve9(getWorkspace(), configFileName), configContent, "utf-8");
+    writeFileSync5(resolve9(getWorkspace(), configFileName), configContent, "utf-8");
     displayConfigSuccess(!!timebackConfig);
   } catch (error) {
     logger.newLine();
@@ -7934,27 +8003,35 @@ var initCommand = new Command2("init").description("Initialize a playcademy.conf
       kv,
       customRoutes
     } = await promptForIntegrations();
-    let depsAdded = false;
-    const hasPackageJsonFile = hasPackageJson();
-    if (hasPackageJsonFile) {
-      logger.newLine();
-      const sdkAdded = await addPlaycademySdk();
-      if (sdkAdded) depsAdded = true;
-    }
-    if (customRoutes || database) {
-      logger.newLine();
-      const scaffoldDepsAdded = await scaffoldIntegrations(
-        customRoutes,
-        database,
-        kv,
-        gameInfo.name
-      );
-      if (scaffoldDepsAdded) depsAdded = true;
-    }
-    if (depsAdded) {
-      logger.newLine();
-      await installDependencies();
-    }
+    logger.newLine();
+    await runStep(
+      "Setting up project",
+      async () => {
+        let depsAdded = false;
+        const hasPackageJsonFile = hasPackageJson();
+        if (hasPackageJsonFile) {
+          const sdkAdded = await addPlaycademySdk();
+          if (sdkAdded) depsAdded = true;
+        }
+        if (customRoutes || database) {
+          const scaffoldOptions = { customRoutes, database, kv };
+          const scaffoldDepsAdded = await scaffoldIntegrations(
+            gameInfo.name,
+            scaffoldOptions
+          );
+          if (scaffoldDepsAdded) depsAdded = true;
+        }
+        if (depsAdded) {
+          const pm = detectPackageManager(getWorkspace());
+          const installCmd = getInstallCommand(pm);
+          execSync3(installCmd, {
+            cwd: getWorkspace(),
+            stdio: ["ignore", "ignore", "ignore"]
+          });
+        }
+      },
+      "Project configured"
+    );
     logger.newLine();
     const configContent = configFormat === "js" ? generateJsConfig({
       name: gameInfo.name,
@@ -7973,7 +8050,7 @@ var initCommand = new Command2("init").description("Initialize a playcademy.conf
       kv: kv ?? void 0,
       timeback: timebackConfig ?? void 0
     });
-    writeFileSync5(resolve10(getWorkspace(), configFileName), configContent, "utf-8");
+    writeFileSync6(resolve10(getWorkspace(), configFileName), configContent, "utf-8");
     displaySuccessMessage({
       configFileName,
       apiDirectory: customRoutes?.directory ?? null,
@@ -7995,20 +8072,9 @@ async function addPlaycademySdk() {
   }
   if (!pkg.dependencies) pkg.dependencies = {};
   pkg.dependencies["@playcademy/sdk"] = "latest";
-  writeFileSync5(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  writeFileSync6(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
   return true;
 }
-async function installDependencies() {
-  const pm = detectPackageManager(getWorkspace());
-  const installCmd = getInstallCommand(pm);
-  await runStep(
-    "Installing dependencies...",
-    async () => {
-      execSync3(installCmd, { cwd: getWorkspace(), stdio: ["ignore", "ignore", "ignore"] });
-    },
-    "Dependencies installed"
-  );
-}
 initCommand.addCommand(configCommand);
 
 // src/commands/login.ts
@@ -8596,7 +8662,43 @@ var getStatusCommand = new Command11("status").description("Check your developer
 
 // src/commands/dev/server.ts
 import { blueBright as blueBright4, underline as underline2 } from "colorette";
+function setupCleanupHandlers(workspace, getServer) {
+  let isShuttingDown = false;
+  const cleanup = () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    cleanupServerInfo("backend", workspace, process.pid);
+    const server = getServer();
+    if (server) {
+      server.dispose().then(() => process.exit(0)).catch(() => process.exit(1));
+    } else {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+async function setupServerHotReload(serverRef, port, workspace, config, loggerEnabled) {
+  return startHotReload(
+    async () => {
+      if (serverRef.current) {
+        await serverRef.current.dispose();
+      }
+      const newConfig = await loadConfig();
+      serverRef.current = await startDevServer({
+        port,
+        config: newConfig,
+        logger: loggerEnabled
+      });
+      await discoverRoutes(getCustomRoutesDirectory(workspace, newConfig));
+    },
+    { config }
+  );
+}
 async function runDevServer(options) {
+  const workspace = getWorkspace();
+  const serverRef = { current: null };
+  setupCleanupHandlers(workspace, () => serverRef.current);
   try {
     logger.newLine();
     const config = await loadConfig();
@@ -8614,52 +8716,27 @@ async function runDevServer(options) {
       return;
     }
     const port = parseInt(options.port, 10);
-    let server = await startDevServer({
+    const server = await startDevServer({
       port,
       config,
       logger: options.logger !== false
     });
-    const hotReload = options.reload !== false;
+    serverRef.current = server;
     logger.success(`Game API started: ${blueBright4(underline2(`http://localhost:${port}/api`))}`);
     logger.newLine();
-    const workspace = getWorkspace();
     const customRoutesDir = getCustomRoutesDirectory(workspace, config);
-    let customRoutes = await discoverRoutes(customRoutesDir);
+    const customRoutes = await discoverRoutes(customRoutesDir);
     displayRegisteredRoutes(config.integrations, customRoutes);
     logger.newLine();
-    if (hotReload) {
-      startHotReload(
-        async () => {
-          await server.dispose();
-          clearModuleCache();
-          const newConfig = await loadConfig();
-          server = await startDevServer({
-            port,
-            config: newConfig,
-            logger: options.logger !== false
-          });
-          const newCustomRoutesDir = getCustomRoutesDirectory(workspace, newConfig);
-          customRoutes = await discoverRoutes(newCustomRoutesDir);
-        },
-        { config }
-      );
+    if (options.reload !== false) {
+      await setupServerHotReload(serverRef, port, workspace, config, options.logger !== false);
     }
     logger.remark(`Press ${underline2("ctrl+c")} to stop`);
     logger.newLine();
-    process.on("SIGINT", async () => {
-      await removeDevServerPidFile();
-      process.exit(0);
-    });
-    process.on("SIGTERM", async () => {
-      await removeDevServerPidFile();
-      process.exit(0);
-    });
   } catch (error) {
     logAndExit(error, logger, { prefix: "Failed to start dev server" });
   }
 }
-function clearModuleCache() {
-}
 
 // src/commands/dev/index.ts
 var devCommand = new Command12("dev").description("Start local backend development server").option("-p, --port <port>", "Backend server port", String(DEFAULT_PORTS.BACKEND)).option("--no-reload", "Disable hot reload").option("--no-logger", "Disable HTTP request logging").action(runDevServer);
@@ -8771,7 +8848,7 @@ async function runDbDiff() {
 // src/commands/db/init.ts
 init_file_loader();
 init_constants2();
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync7 } from "fs";
 import { input as input6 } from "@inquirer/prompts";
 async function runDbInit() {
   try {
@@ -8828,7 +8905,7 @@ async function runDbInit() {
           );
         }
       }
-      writeFileSync6(configFile.path, updatedContent, "utf-8");
+      writeFileSync7(configFile.path, updatedContent, "utf-8");
       logger.success(`Updated ${configFile.path.split("/").pop()}`);
     }
     logger.newLine();
@@ -8850,12 +8927,12 @@ async function runDbInit() {
 // src/commands/db/reset.ts
 init_src2();
 init_src();
-init_constants2();
 import { spawn } from "child_process";
 import { existsSync as existsSync16, rmSync as rmSync2 } from "fs";
 import { join as join18 } from "path";
 import { confirm as confirm6 } from "@inquirer/prompts";
 import { Miniflare as Miniflare2 } from "miniflare";
+init_constants2();
 async function runDbReset() {
   try {
     const workspace = getWorkspace();
@@ -8868,7 +8945,7 @@ async function runDbReset() {
       return;
     }
     logger.newLine();
-    if (isDevServerRunning()) {
+    if (isServerRunning("backend", workspace)) {
       logger.admonition("warning", "Stop Dev Server First", [
         "The development server must be stopped before resetting the database.",
         "Stop the server (Ctrl+C) and run this command again to ensure a clean reset."
@@ -10590,7 +10667,7 @@ import { Command as Command27 } from "commander";
 // src/commands/debug/bundle.ts
 init_src();
 init_constants2();
-import { writeFileSync as writeFileSync7 } from "fs";
+import { writeFileSync as writeFileSync8 } from "fs";
 import { join as join28 } from "path";
 import { Command as Command26 } from "commander";
 var bundleCommand = new Command26("bundle").description("Bundle and inspect the game backend worker code (for debugging)").option("-o, --output <path>", "Output file path", CLI_DEFAULT_OUTPUTS.WORKER_BUNDLE).option("--minify", "Minify the output").option("--sourcemap", "Include source maps").action(async (options) => {
@@ -10622,7 +10699,7 @@ var bundleCommand = new Command26("bundle").description("Bundle and inspect the
       (result) => `Bundled ${formatSize(result.code.length)}`
     );
     const outputPath = join28(workspace, options.output);
-    writeFileSync7(outputPath, bundle.code, "utf-8");
+    writeFileSync8(outputPath, bundle.code, "utf-8");
     logger.success(`Bundle saved to ${options.output}`);
     logger.newLine();
     logger.highlight("Bundle Analysis");
@@ -10700,7 +10777,6 @@ export {
   compareIntegrationKeys,
   confirmDeploymentPlan,
   createClient,
-  createDevServerPidFile,
   deployBackendIfNeeded,
   deployExternalGame,
   deployGameBackend,
@@ -10739,7 +10815,6 @@ export {
   getCustomRoutesSize,
   getDeployedGame,
   getDeploymentId,
-  getDevServerPidPath,
   getDrizzleKitApiExports,
   getEnvironment,
   getErrorMessage,
@@ -10773,7 +10848,6 @@ export {
   importTypescriptDefault,
   importTypescriptFile,
   integrationChangeDetectors,
-  isDevServerRunning,
   listProfiles,
   loadAuthStore,
   loadConfig,
@@ -10791,7 +10865,6 @@ export {
   promptForTimeBackIntegration,
   registerCustomRoutes,
   removeDeployedGame,
-  removeDevServerPidFile,
   removeProfile,
   reportCancellation,
   reportDeploymentSuccess,

package/dist/templates/playcademy-gitignore.template

@@ -1,4 +1,3 @@
 *.zip
-*.pid
 db
 kv

package/dist/utils.js

@@ -303,16 +303,6 @@ var CLI_DIRECTORIES = {
   /** KV storage directory within workspace */
   KV: join(WORKSPACE_NAME, "kv")
 };
-var CLI_FILES = {
-  /** Auth store file in user config directory */
-  AUTH_STORE: "auth.json",
-  /** Games deployment info store */
-  GAMES_STORE: "games.json",
-  /** Dev server PID file */
-  DEV_SERVER_PID: "dev-server.pid",
-  /** Initial database file (before miniflare) */
-  INITIAL_DATABASE: "initial.sqlite"
-};
 
 // src/constants/timeback.ts
 var CONFIG_FILE_NAMES = [
@@ -567,10 +557,70 @@ function processConfigVariables(config) {
 }
 
 // src/lib/dev/server.ts
-import { mkdir as mkdir3 } from "fs/promises";
+import { mkdir as mkdir2 } from "fs/promises";
 import { join as join7 } from "path";
 import { Miniflare } from "miniflare";
 
+// ../utils/src/port.ts
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+async function isPortAvailableOnHost(port, host) {
+  return new Promise((resolve4) => {
+    const server = createServer();
+    server.once("error", () => {
+      resolve4(false);
+    });
+    server.once("listening", () => {
+      server.close();
+      resolve4(true);
+    });
+    server.listen(port, host);
+  });
+}
+async function findAvailablePort(startPort = 4321) {
+  const allInterfacesAvailable = await isPortAvailableOnHost(startPort, "0.0.0.0");
+  const ipv6Available = await isPortAvailableOnHost(startPort, "::1");
+  if (allInterfacesAvailable && ipv6Available) {
+    return startPort;
+  }
+  return findAvailablePort(startPort + 1);
+}
+function getRegistryPath() {
+  const home = homedir();
+  const dir = join2(home, ".playcademy");
+  if (!existsSync2(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return join2(dir, ".proc");
+}
+function readRegistry() {
+  const registryPath = getRegistryPath();
+  if (!existsSync2(registryPath)) {
+    return {};
+  }
+  try {
+    const content = readFileSync(registryPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+function writeRegistry(registry) {
+  const registryPath = getRegistryPath();
+  writeFileSync(registryPath, JSON.stringify(registry, null, 2), "utf-8");
+}
+function getServerKey(type, port) {
+  return `${type}-${port}`;
+}
+function writeServerInfo(type, info) {
+  const registry = readRegistry();
+  const key = getServerKey(type, info.port);
+  registry[key] = info;
+  writeRegistry(registry);
+}
+
 // src/lib/core/client.ts
 import { PlaycademyClient } from "@playcademy/sdk";
 
@@ -816,7 +866,7 @@ var CROSS_MARK = String.fromCodePoint(10006);
 init_package_json();
 
 // src/lib/templates/loader.ts
-import { existsSync as existsSync2, readFileSync } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname3, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 var currentDir = dirname3(fileURLToPath(import.meta.url));
@@ -829,8 +879,8 @@ function loadTemplateString(filename) {
     resolve3(currentDir, "templates", name)
   ]);
   for (const candidate of candidatePaths) {
-    if (existsSync2(candidate)) {
-      return readFileSync(candidate, "utf-8");
+    if (existsSync3(candidate)) {
+      return readFileSync2(candidate, "utf-8");
     }
   }
   throw new Error(`Template not found: ${filename}. Searched: ${candidatePaths.join(", ")}`);
@@ -839,12 +889,12 @@ function loadTemplateString(filename) {
 // src/lib/core/import.ts
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { pathToFileURL } from "url";
 import * as esbuild from "esbuild";
 async function importTypescriptFile(filePath, bundleOptions) {
-  const tempDir = mkdtempSync(join2(tmpdir(), "playcademy-import-"));
-  const outFile = join2(tempDir, "bundle.mjs");
+  const tempDir = mkdtempSync(join3(tmpdir(), "playcademy-import-"));
+  const outFile = join3(tempDir, "bundle.mjs");
   try {
     await esbuild.build({
       entryPoints: [filePath],
@@ -872,8 +922,8 @@ async function importTypescriptDefault(filePath, bundleOptions) {
 }
 
 // src/lib/deploy/bundle.ts
-import { existsSync as existsSync3 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync4 } from "fs";
+import { join as join5 } from "path";
 
 // ../edge-play/src/entry.ts
 var entry_default = "/**\n * Game Backend Entry Point\n *\n * This file is the main entry point for deployed game backends.\n * It creates a Hono app and registers all enabled integration routes.\n *\n * Bundled with esbuild and deployed to Cloudflare Workers (or AWS Lambda).\n * Config is injected at build time via esbuild's `define` option.\n */\n\nimport { Hono } from 'hono'\nimport { cors } from 'hono/cors'\n\nimport { PlaycademyClient } from '@playcademy/sdk/server'\n\nimport { ENV_VARS } from './constants'\nimport { registerBuiltinRoutes } from './register-routes'\n\nimport type { PlaycademyConfig } from '@playcademy/sdk/server'\nimport type { HonoEnv } from './types'\n\n/**\n * Config injected at build time by esbuild\n *\n * The `declare const` tells TypeScript \"this exists at runtime, trust me.\"\n * During bundling, esbuild's `define` option does literal text replacement:\n *\n * Example bundling:\n *   Source:  if (PLAYCADEMY_CONFIG.integrations.timeback) { ... }\n *   Define:  { 'PLAYCADEMY_CONFIG': JSON.stringify({ integrations: { timeback: {...} } }) }\n *   Output:  if ({\"integrations\":{\"timeback\":{...}}}.integrations.timeback) { ... }\n *\n * This enables tree-shaking: if timeback is not configured, those code paths are removed.\n * The bundled Worker only includes the routes that are actually enabled.\n */\ndeclare const PLAYCADEMY_CONFIG: PlaycademyConfig & {\n    customRoutes?: Array<{ path: string; file: string }>\n}\n\n// XXX: Polyfill process global for SDK compatibility\n// SDK code may reference process.env without importing it\n// @ts-expect-error - Adding global for Worker environment\nglobalThis.process = {\n    env: {}, // Populated per-request from Worker env bindings\n    cwd: () => '/',\n}\n\nconst app = new Hono<HonoEnv>()\n\n// TODO: Harden CORS in production - restrict to trusted origins:\n// - Game's assetBundleBase (for hosted games)\n// - Game's externalUrl (for external games)\n// - Platform frontend domains (hub.playcademy.com, hub.dev.playcademy.net)\n// This would require passing game metadata through env bindings during deployment\napp.use(\n    '*',\n    cors({\n        origin: '*', // Permissive for now\n        allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],\n        allowHeaders: ['Content-Type', 'Authorization'],\n    }),\n)\n\nlet sdkPromise: Promise<PlaycademyClient> | null = null\n\napp.use('*', async (c, next) => {\n    // Populate process.env from Worker bindings for SDK compatibility\n    globalThis.process.env = {\n        [ENV_VARS.PLAYCADEMY_API_KEY]: c.env.PLAYCADEMY_API_KEY,\n        [ENV_VARS.GAME_ID]: c.env.GAME_ID,\n        [ENV_VARS.PLAYCADEMY_BASE_URL]: c.env.PLAYCADEMY_BASE_URL,\n    }\n\n    // Set config for all routes\n    c.set('config', PLAYCADEMY_CONFIG)\n    c.set('customRoutes', PLAYCADEMY_CONFIG.customRoutes || [])\n\n    await next()\n})\n\n// Initialize SDK lazily on first request\napp.use('*', async (c, next) => {\n    if (!sdkPromise) {\n        sdkPromise = PlaycademyClient.init({\n            apiKey: c.env[ENV_VARS.PLAYCADEMY_API_KEY],\n            gameId: c.env[ENV_VARS.GAME_ID],\n            baseUrl: c.env[ENV_VARS.PLAYCADEMY_BASE_URL],\n            config: PLAYCADEMY_CONFIG,\n        })\n    }\n\n    c.set('sdk', await sdkPromise)\n    await next()\n})\n\n/**\n * Register built-in integration routes based on enabled integrations\n *\n * This function conditionally imports and registers routes like:\n * - POST /api/integrations/timeback/end-activity (if timeback enabled)\n * - GET /api/health (always included)\n *\n * Uses dynamic imports for tree-shaking: if an integration is not enabled,\n * its route code is completely removed from the bundle.\n */\nawait registerBuiltinRoutes(app, PLAYCADEMY_CONFIG.integrations)\n\nexport default app\n";
@@ -1129,7 +1179,7 @@ function textLoaderPlugin() {
 init_file_loader();
 import { mkdir, writeFile } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { join as join3, relative } from "path";
+import { join as join4, relative } from "path";
 
 // src/lib/deploy/hash.ts
 import { createHash } from "crypto";
@@ -1148,7 +1198,7 @@ async function discoverRoutes(apiDir) {
   const routes = await Promise.all(
     files.map(async (file) => {
       const routePath = filePathToRoutePath(file);
-      const absolutePath = join3(apiDir, file);
+      const absolutePath = join4(apiDir, file);
       const relativePath = relative(getWorkspace(), absolutePath);
       const methods = await detectExportedMethods(absolutePath);
       return {
@@ -1208,10 +1258,10 @@ async function transpileRoute(filePath) {
   if (!result.outputFiles?.[0]) {
     throw new Error("Transpilation failed: no output");
   }
-  const tempDir = join3(tmpdir2(), "playcademy-dev");
+  const tempDir = join4(tmpdir2(), "playcademy-dev");
   await mkdir(tempDir, { recursive: true });
   const hash = hashContent(filePath).slice(0, 12);
-  const jsPath = join3(tempDir, `${hash}.mjs`);
+  const jsPath = join4(tempDir, `${hash}.mjs`);
   await writeFile(jsPath, result.outputFiles[0].text);
   return jsPath;
 }
@@ -1222,7 +1272,7 @@ 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(join4(workspace, customRoutesDir));
+  const customRoutes = await discoverRoutes(join5(workspace, customRoutesDir));
   const customRouteData = customRoutes.map((r) => ({
     path: r.path,
     file: r.file,
@@ -1234,15 +1284,15 @@ async function discoverCustomRoutes(config) {
 function resolveEmbeddedSourcePaths() {
   const workspace = getWorkspace();
   const distDir = new URL(".", import.meta.url).pathname;
-  const embeddedEdgeSrc = join4(distDir, "edge-play", "src");
-  const isBuiltPackage = existsSync3(embeddedEdgeSrc);
+  const embeddedEdgeSrc = join5(distDir, "edge-play", "src");
+  const isBuiltPackage = existsSync4(embeddedEdgeSrc);
   const monorepoRoot = getMonorepoRoot();
-  const monorepoEdgeSrc = join4(monorepoRoot, "packages/edge-play/src");
+  const monorepoEdgeSrc = join5(monorepoRoot, "packages/edge-play/src");
   const edgePlaySrc = isBuiltPackage ? embeddedEdgeSrc : monorepoEdgeSrc;
-  const cliPackageRoot = isBuiltPackage ? join4(distDir, "../../..") : join4(monorepoRoot, "packages/cli");
-  const cliNodeModules = isBuiltPackage ? join4(cliPackageRoot, "node_modules") : monorepoRoot;
-  const workspaceNodeModules = join4(workspace, "node_modules");
-  const constantsEntry = isBuiltPackage ? join4(embeddedEdgeSrc, "..", "..", "constants", "src", "index.ts") : join4(monorepoRoot, "packages", "constants", "src", "index.ts");
+  const cliPackageRoot = isBuiltPackage ? join5(distDir, "../../..") : join5(monorepoRoot, "packages/cli");
+  const cliNodeModules = isBuiltPackage ? join5(cliPackageRoot, "node_modules") : monorepoRoot;
+  const workspaceNodeModules = join5(workspace, "node_modules");
+  const constantsEntry = isBuiltPackage ? join5(embeddedEdgeSrc, "..", "..", "constants", "src", "index.ts") : join5(monorepoRoot, "packages", "constants", "src", "index.ts");
   return {
     isBuiltPackage,
     edgePlaySrc,
@@ -1302,16 +1352,16 @@ function createEsbuildConfig(entryCode, paths, bundleConfig, customRoutesDir, op
       // │ Example: import * as route from '@game-api/hello.ts'            │
       // │ Resolves to: /user-project/server/api/hello.ts                  │
       // └─────────────────────────────────────────────────────────────────┘
-      "@game-api": join4(workspace, customRoutesDir),
+      "@game-api": join5(workspace, customRoutesDir),
       // ┌─ 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: join4(edgePlaySrc, "polyfills.js"),
-      "fs/promises": join4(edgePlaySrc, "polyfills.js"),
-      path: join4(edgePlaySrc, "polyfills.js"),
-      os: join4(edgePlaySrc, "polyfills.js"),
-      process: join4(edgePlaySrc, "polyfills.js")
+      fs: join5(edgePlaySrc, "polyfills.js"),
+      "fs/promises": join5(edgePlaySrc, "polyfills.js"),
+      path: join5(edgePlaySrc, "polyfills.js"),
+      os: join5(edgePlaySrc, "polyfills.js"),
+      process: join5(edgePlaySrc, "polyfills.js")
     },
     // ──── Build Plugins ────
     plugins: [textLoaderPlugin()],
@@ -1378,8 +1428,8 @@ import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { bold as bold3, cyan as cyan2 } from "colorette";
 
 // src/lib/init/database.ts
-import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { join as join6 } from "path";
 var drizzleConfigTemplate = loadTemplateString("database/drizzle-config.ts");
 var dbSchemaUsersTemplate = loadTemplateString("database/db-schema-users.ts");
 var dbSchemaScoresTemplate = loadTemplateString("database/db-schema-scores.ts");
@@ -1390,9 +1440,9 @@ var packageTemplate = loadTemplateString("database/package.json");
 var rootGitignoreTemplate = loadTemplateString("gitignore");
 function hasDatabaseSetup() {
   const workspace = getWorkspace();
-  const drizzleConfigPath = join5(workspace, "drizzle.config.ts");
-  const drizzleConfigJsPath = join5(workspace, "drizzle.config.js");
-  return existsSync4(drizzleConfigPath) || existsSync4(drizzleConfigJsPath);
+  const drizzleConfigPath = join6(workspace, "drizzle.config.ts");
+  const drizzleConfigJsPath = join6(workspace, "drizzle.config.js");
+  return existsSync5(drizzleConfigPath) || existsSync5(drizzleConfigJsPath);
 }
 
 // src/lib/init/scaffold.ts
@@ -1409,29 +1459,14 @@ function hasKVSetup(config) {
   return !!config.integrations?.kv;
 }
 
-// src/lib/dev/pid.ts
-import { mkdir as mkdir2, unlink, writeFile as writeFile2 } from "fs/promises";
-import { join as join6 } from "path";
-function getDevServerPidPath() {
-  return join6(getWorkspace(), CLI_DIRECTORIES.WORKSPACE, CLI_FILES.DEV_SERVER_PID);
-}
-async function createDevServerPidFile() {
-  const pidPath = getDevServerPidFile();
-  const pidDir = join6(getWorkspace(), CLI_DIRECTORIES.WORKSPACE);
-  await mkdir2(pidDir, { recursive: true });
-  await writeFile2(pidPath, process.pid.toString());
-}
-function getDevServerPidFile() {
-  return getDevServerPidPath();
-}
-
 // src/lib/dev/server.ts
 async function startDevServer(options) {
   const {
-    port,
+    port: preferredPort,
     config: providedConfig,
     platformUrl = process.env.PLAYCADEMY_BASE_URL || "http://localhost:5174"
   } = options;
+  const port = await findAvailablePort(preferredPort);
   const config = providedConfig ?? await loadConfig();
   const hasSandboxTimebackCreds = !!process.env.TIMEBACK_API_CLIENT_ID;
   const devConfig = config.integrations?.timeback && !hasSandboxTimebackCreds ? { ...config, integrations: { ...config.integrations, timeback: void 0 } } : config;
@@ -1466,12 +1501,13 @@ async function startDevServer(options) {
   if (hasDatabase) {
     await initializeDatabase(mf);
   }
+  await writeBackendServerInfo(port);
   return mf;
 }
 async function ensureDatabaseDirectory() {
   const dbDir = join7(getWorkspace(), CLI_DIRECTORIES.DATABASE);
   try {
-    await mkdir3(dbDir, { recursive: true });
+    await mkdir2(dbDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create database directory: ${getErrorMessage(error)}`);
   }
@@ -1480,7 +1516,7 @@ async function ensureDatabaseDirectory() {
 async function ensureKvDirectory() {
   const kvDir = join7(getWorkspace(), CLI_DIRECTORIES.KV);
   try {
-    await mkdir3(kvDir, { recursive: true });
+    await mkdir2(kvDir, { recursive: true });
   } catch (error) {
     throw new Error(`Failed to create KV directory: ${getErrorMessage(error)}`);
   }
@@ -1489,7 +1525,15 @@ async function ensureKvDirectory() {
 async function initializeDatabase(mf) {
   const d1 = await mf.getD1Database("DB");
   await d1.exec("SELECT 1");
-  await createDevServerPidFile();
+}
+async function writeBackendServerInfo(port) {
+  writeServerInfo("backend", {
+    pid: process.pid,
+    port,
+    url: `http://localhost:${port}/api`,
+    startedAt: Date.now(),
+    projectRoot: getWorkspace()
+  });
 }
 
 // src/lib/dev/reload.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "playcademy",
-    "version": "0.13.1",
+    "version": "0.13.3",
     "type": "module",
     "module": "./dist/index.js",
     "main": "./dist/index.js",
@@ -40,7 +40,7 @@
     },
     "dependencies": {
         "@inquirer/prompts": "^7.8.6",
-        "@playcademy/sdk": "0.1.5",
+        "@playcademy/sdk": "0.1.6",
         "better-sqlite3": "^12.4.1",
         "chokidar": "^4.0.3",
         "colorette": "^2.0.20",