devsurface 0.3.0 → 0.4.0

package/dist/cli/index.js

@@ -1485,14 +1485,6 @@ async function scanCommand(cwd = process.cwd()) {
 // src/cli/commands/start.ts
 import pc5 from "picocolors";
 
-// src/server/index.ts
-import { promises as fs17 } from "fs";
-import path13 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { createAdaptorServer } from "@hono/node-server";
-import { serveStatic } from "@hono/node-server/serve-static";
-import { Hono } from "hono";
-
 // node_modules/open/index.js
 import process7 from "process";
 import { Buffer as Buffer2 } from "buffer";
@@ -2007,6 +1999,14 @@ defineLazyProperty(apps, "browser", () => "browser");
 defineLazyProperty(apps, "browserPrivate", () => "browserPrivate");
 var open_default = open;
 
+// src/server/index.ts
+import { promises as fs19 } from "fs";
+import path15 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { createAdaptorServer } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+
 // src/core/process/manager.ts
 import { EventEmitter } from "events";
 import spawn3 from "cross-spawn";
@@ -2149,12 +2149,244 @@ var ProcessManager = class extends EventEmitter {
   }
 };
 
-// src/server/routes/api.ts
-import { constants as constants2, existsSync } from "fs";
+// src/core/hub/registry.ts
+import { createHash } from "crypto";
+import { promises as fs17 } from "fs";
+import os3 from "os";
+import path13 from "path";
+
+// src/core/hub/workspaceRoots.ts
 import { promises as fs16 } from "fs";
 import path12 from "path";
+function isWithinRoot7(root, target) {
+  const relative = path12.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path12.isAbsolute(relative);
+}
+async function configuredWorkspaceRoots() {
+  const raw = process.env.DEVSURFACE_WORKSPACE_ROOTS;
+  if (!raw) {
+    return [];
+  }
+  const roots = [];
+  for (const entry of raw.split(",")) {
+    const trimmed = entry.trim();
+    if (!trimmed) {
+      continue;
+    }
+    try {
+      roots.push(await fs16.realpath(path12.resolve(trimmed)));
+    } catch {
+    }
+  }
+  return roots;
+}
+async function assertWithinWorkspaceRoots(targetPath) {
+  const roots = await configuredWorkspaceRoots();
+  if (roots.length === 0) {
+    return;
+  }
+  for (const root of roots) {
+    if (isWithinRoot7(root, targetPath)) {
+      return;
+    }
+  }
+  throw new Error("Path must be inside a configured workspace root.");
+}
+
+// src/core/hub/registry.ts
+function workspaceId(realPath) {
+  const base = path13.basename(realPath).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 32) || "workspace";
+  const hash = createHash("sha256").update(realPath).digest("hex").slice(0, 6);
+  return `${base}-${hash}`;
+}
+function defaultDataDir() {
+  return process.env.DEVSURFACE_DATA_DIR ?? path13.join(os3.homedir(), ".devsurface");
+}
+async function readPackageName(dirPath) {
+  try {
+    const raw = JSON.parse(await fs17.readFile(path13.join(dirPath, "package.json"), "utf8"));
+    return typeof raw?.name === "string" && raw.name.length > 0 ? raw.name : null;
+  } catch {
+    return null;
+  }
+}
+var WorkspaceRegistry = class {
+  filePath;
+  seeded = false;
+  constructor(dataDir) {
+    const dir = dataDir ?? defaultDataDir();
+    this.filePath = path13.join(dir, "workspaces.json");
+  }
+  async list() {
+    await this.seedFromEnv();
+    return await this.read();
+  }
+  async add(dirPath) {
+    const realDir = await this.resolveDir(dirPath);
+    await assertWithinWorkspaceRoots(realDir);
+    const entries = await this.read();
+    const existing = entries.find((entry2) => entry2.path === realDir);
+    if (existing) {
+      return existing;
+    }
+    const name = await readPackageName(realDir) ?? path13.basename(realDir);
+    const entry = {
+      id: workspaceId(realDir),
+      name,
+      path: realDir,
+      addedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    entries.push(entry);
+    await this.write(entries);
+    return entry;
+  }
+  async remove(id) {
+    const entries = await this.read();
+    const filtered = entries.filter((entry) => entry.id !== id);
+    if (filtered.length === entries.length) {
+      return false;
+    }
+    await this.write(filtered);
+    return true;
+  }
+  async findByPath(dirPath) {
+    try {
+      const realDir = await fs17.realpath(path13.resolve(dirPath));
+      const entries = await this.read();
+      return entries.find((entry) => entry.path === realDir) ?? null;
+    } catch {
+      return null;
+    }
+  }
+  async resolve(id) {
+    const entries = await this.read();
+    const entry = entries.find((item) => item.id === id);
+    if (!entry) {
+      return null;
+    }
+    try {
+      const realDir = await this.resolveDir(entry.path);
+      await assertWithinWorkspaceRoots(realDir);
+      if (realDir !== entry.path) {
+        const updated = { ...entry, path: realDir };
+        await this.write(entries.map((item) => item.id === id ? updated : item));
+        return updated;
+      }
+      return entry;
+    } catch {
+      await this.remove(id);
+      return null;
+    }
+  }
+  async resolveDir(dirPath) {
+    const resolved = path13.resolve(dirPath);
+    const realDir = await fs17.realpath(resolved);
+    const stat = await fs17.stat(realDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`${dirPath} is not a directory.`);
+    }
+    return realDir;
+  }
+  async read() {
+    try {
+      const content = await fs17.readFile(this.filePath, "utf8");
+      const parsed = JSON.parse(content);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  async write(entries) {
+    await fs17.mkdir(path13.dirname(this.filePath), { recursive: true });
+    await fs17.writeFile(this.filePath, JSON.stringify(entries, null, 2) + "\n", "utf8");
+  }
+  async seedFromEnv() {
+    if (this.seeded) {
+      return;
+    }
+    this.seeded = true;
+    const seedValue = process.env.DEVSURFACE_WORKSPACES;
+    if (!seedValue) {
+      return;
+    }
+    const paths = seedValue.split(",").map((p) => p.trim()).filter(Boolean);
+    for (const p of paths) {
+      try {
+        await this.add(p);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/core/hub/runtime.ts
+var Hub = class {
+  registry;
+  runtimes = /* @__PURE__ */ new Map();
+  cleanupInstalled = false;
+  constructor(options) {
+    this.registry = new WorkspaceRegistry(options?.dataDir);
+  }
+  get(id) {
+    return this.runtimes.get(id) ?? null;
+  }
+  ensure(entry) {
+    const existing = this.runtimes.get(entry.id);
+    if (existing) {
+      return existing;
+    }
+    const runtime = {
+      id: entry.id,
+      root: entry.path,
+      processManager: new ProcessManager(),
+      dockerController: new DockerComposeController(entry.path)
+    };
+    this.runtimes.set(entry.id, runtime);
+    return runtime;
+  }
+  async listSummaries() {
+    const entries = await this.registry.list();
+    return entries.map((entry) => {
+      const runtime = this.runtimes.get(entry.id);
+      const running = runtime ? runtime.processManager.list().filter((p) => p.status === "running").length : 0;
+      return {
+        id: entry.id,
+        name: entry.name,
+        path: entry.path,
+        addedAt: entry.addedAt,
+        runningProcesses: running
+      };
+    });
+  }
+  killAll() {
+    for (const runtime of this.runtimes.values()) {
+      runtime.processManager.killAll();
+    }
+  }
+  attachCleanupHandlers() {
+    if (this.cleanupInstalled) {
+      return;
+    }
+    this.cleanupInstalled = true;
+    process.once("exit", () => {
+      this.killAll();
+    });
+    process.once("SIGINT", () => {
+      this.killAll();
+      process.exit(130);
+    });
+  }
+};
+
+// src/server/routes/api.ts
+import { constants as constants2, existsSync } from "fs";
+import { promises as fs18 } from "fs";
+import path14 from "path";
 import spawn4 from "cross-spawn";
 
+// src/version.ts
+var DEV_SURFACE_VERSION = "0.4.0";
+
 // src/server/localAccess.ts
 var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
 function hostnameFromHostHeader(host) {
@@ -2194,6 +2426,130 @@ function isSameOrigin(requestUrl, origin) {
   }
 }
 
+// src/server/listenConfig.ts
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_PORT = 4567;
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
+var CONTAINER_HOSTS = /* @__PURE__ */ new Set(["0.0.0.0", "::"]);
+function resolveHost() {
+  const envHost = process.env.DEVSURFACE_HOST;
+  if (!envHost) {
+    return DEFAULT_HOST;
+  }
+  if (LOOPBACK_HOSTS.has(envHost)) {
+    return envHost;
+  }
+  if (CONTAINER_HOSTS.has(envHost) && process.env.DEVSURFACE_CONTAINER === "true") {
+    return envHost;
+  }
+  if (CONTAINER_HOSTS.has(envHost)) {
+    throw new Error(
+      "All-interface DevSurface binding is only allowed when DEVSURFACE_CONTAINER=true. DevSurface binds to 127.0.0.1 on bare metal."
+    );
+  }
+  throw new Error("DEVSURFACE_HOST must be a loopback host, or 0.0.0.0 inside a container.");
+}
+var listenHost = DEFAULT_HOST;
+function setListenHost(host) {
+  listenHost = host;
+}
+function getListenHost() {
+  return listenHost;
+}
+function normalizeRemoteAddress(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return null;
+  }
+  if (raw.startsWith("::ffff:")) {
+    return raw.slice("::ffff:".length);
+  }
+  return raw;
+}
+function isLoopbackRemoteAddress(raw) {
+  const address = normalizeRemoteAddress(raw);
+  if (!address) {
+    return false;
+  }
+  if (address === "::1" || address === "127.0.0.1") {
+    return true;
+  }
+  return address.startsWith("127.");
+}
+function parseIpv4(address) {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = parts.map((part) => Number(part));
+  if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+    return null;
+  }
+  return octets;
+}
+function isPrivateRemoteAddress(raw) {
+  const address = normalizeRemoteAddress(raw);
+  if (!address) {
+    return false;
+  }
+  if (isLoopbackRemoteAddress(address)) {
+    return true;
+  }
+  if (address.startsWith("fe80:")) {
+    return true;
+  }
+  const ipv4 = parseIpv4(address);
+  if (!ipv4) {
+    return false;
+  }
+  const [a, b] = ipv4;
+  if (a === 10) {
+    return true;
+  }
+  if (a === 192 && b === 168) {
+    return true;
+  }
+  if (a === 172 && b >= 16 && b <= 31) {
+    return true;
+  }
+  return false;
+}
+function isAllowedRemoteAddress(raw, host) {
+  if (host === "0.0.0.0" || host === "::") {
+    return isPrivateRemoteAddress(raw);
+  }
+  return isLoopbackRemoteAddress(raw);
+}
+function isAllowedClientConnection(raw, host = getListenHost()) {
+  if (raw === void 0) {
+    return true;
+  }
+  return isAllowedRemoteAddress(raw, host);
+}
+function initializeListenHost() {
+  const host = resolveHost();
+  setListenHost(host);
+  return host;
+}
+
+// src/server/accessControl.ts
+function remoteAddressFromRequest(request) {
+  return request?.socket?.remoteAddress;
+}
+function createApiAccessMiddleware() {
+  return async (context, next) => {
+    const host = context.req.header("host") ?? new URL(context.req.url).host;
+    if (!isAllowedLocalHostHeader(host)) {
+      return context.json({ error: "Non-local host rejected." }, 403);
+    }
+    const env = context.env;
+    const remoteAddress = remoteAddressFromRequest(env?.incoming);
+    if (!isAllowedClientConnection(remoteAddress, getListenHost())) {
+      return context.json({ error: "Remote client rejected." }, 403);
+    }
+    await next();
+  };
+}
+
 // src/server/mutationToken.ts
 import { randomBytes, timingSafeEqual } from "crypto";
 function createMutationToken() {
@@ -2215,9 +2571,9 @@ function isAllowedTerminalCommand(command) {
 }
 
 // src/server/routes/api.ts
-function isWithinRoot7(root, target) {
-  const relative = path12.relative(path12.resolve(root), path12.resolve(target));
-  return relative === "" || !relative.startsWith("..") && !path12.isAbsolute(relative);
+function isWithinRoot8(root, target) {
+  const relative = path14.relative(path14.resolve(root), path14.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path14.isAbsolute(relative);
 }
 function isAllowedMutationOrigin(requestUrl, origin) {
   if (origin === null) {
@@ -2225,6 +2581,23 @@ function isAllowedMutationOrigin(requestUrl, origin) {
   }
   return isAllowedLocalOrigin(origin) && isSameOrigin(requestUrl, origin);
 }
+function registerMutationGuard(app, mutationToken) {
+  app.use("/api/*", createApiAccessMiddleware());
+  app.use("/api/*", async (context, next) => {
+    if (context.req.method === "GET" || context.req.method === "HEAD") {
+      await next();
+      return;
+    }
+    const origin = context.req.header("origin") ?? null;
+    const secFetchSite = context.req.header("sec-fetch-site") ?? null;
+    const intent = context.req.header("x-devsurface-intent") ?? null;
+    const token = context.req.header("x-devsurface-token") ?? null;
+    if (!hasMutationIntent(intent) || !hasValidMutationToken(token, mutationToken) || isCrossSiteFetch(secFetchSite) || !isAllowedMutationOrigin(context.req.url, origin)) {
+      return context.json({ error: "Cross-origin mutation rejected." }, 403);
+    }
+    await next();
+  });
+}
 function isCrossSiteFetch(secFetchSite) {
   return secFetchSite === "cross-site";
 }
@@ -2232,35 +2605,35 @@ function hasMutationIntent(intent) {
   return intent === "dashboard";
 }
 async function realPathWithinRoot(root, target) {
-  if (!isWithinRoot7(root, target)) {
+  if (!isWithinRoot8(root, target)) {
     return false;
   }
   try {
-    const [realRoot, realTarget] = await Promise.all([fs16.realpath(root), fs16.realpath(target)]);
-    return isWithinRoot7(realRoot, realTarget);
+    const [realRoot, realTarget] = await Promise.all([fs18.realpath(root), fs18.realpath(target)]);
+    return isWithinRoot8(realRoot, realTarget);
   } catch {
     return false;
   }
 }
 async function writableDestinationWithinRoot(root, destination) {
-  if (!isWithinRoot7(root, destination)) {
+  if (!isWithinRoot8(root, destination)) {
     return false;
   }
   try {
     const [realRoot, realParent] = await Promise.all([
-      fs16.realpath(root),
-      fs16.realpath(path12.dirname(destination))
+      fs18.realpath(root),
+      fs18.realpath(path14.dirname(destination))
     ]);
-    return isWithinRoot7(realRoot, realParent);
+    return isWithinRoot8(realRoot, realParent);
   } catch {
     return false;
   }
 }
 async function copyFileExclusive(source, destination) {
-  const content = await fs16.readFile(source);
+  const content = await fs18.readFile(source);
   let handle2 = null;
   try {
-    handle2 = await fs16.open(
+    handle2 = await fs18.open(
       destination,
       constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY,
       384
@@ -2287,15 +2660,15 @@ function resolveCommandPromptExecutable() {
   return process.env.ComSpec ?? "cmd.exe";
 }
 function findExecutable(command) {
-  if (path12.isAbsolute(command)) {
+  if (path14.isAbsolute(command)) {
     return existsSync(command) ? command : null;
   }
   const pathValue = process.env.PATH ?? "";
-  for (const directory of pathValue.split(path12.delimiter)) {
+  for (const directory of pathValue.split(path14.delimiter)) {
     if (directory.length === 0) {
       continue;
     }
-    const candidate = path12.join(directory, command);
+    const candidate = path14.join(directory, command);
     if (existsSync(candidate)) {
       return candidate;
     }
@@ -2361,93 +2734,74 @@ function openTerminalAt(root) {
   }
   return launchDetached(terminal.command, terminal.args, root);
 }
-function registerApiRoutes(app, options) {
-  const dockerController = options.dockerController ?? new DockerComposeController(options.projectRoot);
-  app.get("/api/session", (context) => {
-    return context.json({ token: options.mutationToken });
-  });
-  app.use("/api/*", async (context, next) => {
-    const host = context.req.header("host") ?? new URL(context.req.url).host;
-    if (!isAllowedLocalHostHeader(host)) {
-      return context.json({ error: "Non-local host rejected." }, 403);
+function handleDockerError(error, context) {
+  if (error instanceof DockerOperationError) {
+    if (error.code === "compose-not-found" || error.code === "service-not-found") {
+      return context.json({ error: error.message, code: error.code }, 404);
     }
-    if (context.req.method !== "GET" && context.req.method !== "HEAD") {
-      const origin = context.req.header("origin") ?? null;
-      const secFetchSite = context.req.header("sec-fetch-site") ?? null;
-      const intent = context.req.header("x-devsurface-intent") ?? null;
-      const token = context.req.header("x-devsurface-token") ?? null;
-      if (!hasMutationIntent(intent) || !hasValidMutationToken(token, options.mutationToken) || isCrossSiteFetch(secFetchSite) || !isAllowedMutationOrigin(context.req.url, origin)) {
-        return context.json({ error: "Cross-origin mutation rejected." }, 403);
-      }
+    if (error.code === "docker-not-installed" || error.code === "docker-not-running") {
+      return context.json({ error: error.message, code: error.code }, 503);
     }
-    await next();
-  });
-  app.get("/api/project", async (context) => {
-    return context.json(await scanProject(options.projectRoot));
+    return context.json({ error: error.message, code: error.code }, 502);
+  }
+  throw error;
+}
+function registerWorkspaceRoutes(app, resolveWorkspace) {
+  app.get("/api/workspaces/:id/project", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return context.json(await scanProject(ws.root));
   });
-  app.get("/api/health", async (context) => {
-    return context.json(await runDoctor(options.projectRoot));
+  app.get("/api/workspaces/:id/health", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return context.json(await runDoctor(ws.root));
   });
-  app.get("/api/processes", (context) => {
-    return context.json(options.processManager.list());
+  app.get("/api/workspaces/:id/processes", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return context.json(ws.processManager.list());
   });
-  app.get("/api/logs", (context) => {
-    return context.json(options.processManager.listLogs());
+  app.get("/api/workspaces/:id/logs", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    return context.json(ws.processManager.listLogs());
   });
-  app.get("/api/docker/:service/logs", async (context) => {
+  app.get("/api/workspaces/:id/docker/:service/logs", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const service = decodeURIComponent(context.req.param("service"));
     try {
-      return context.json(await dockerController.logs(service));
+      return context.json(await ws.dockerController.logs(service));
     } catch (error) {
-      if (error instanceof DockerOperationError) {
-        if (error.code === "compose-not-found" || error.code === "service-not-found") {
-          return context.json({ error: error.message, code: error.code }, 404);
-        }
-        if (error.code === "docker-not-installed" || error.code === "docker-not-running") {
-          return context.json({ error: error.message, code: error.code }, 503);
-        }
-        return context.json({ error: error.message, code: error.code }, 502);
-      }
-      throw error;
+      return handleDockerError(error, context);
     }
   });
-  app.post("/api/docker/:service/start", async (context) => {
+  app.post("/api/workspaces/:id/docker/:service/start", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const service = decodeURIComponent(context.req.param("service"));
     try {
-      return context.json(await dockerController.start(service));
+      return context.json(await ws.dockerController.start(service));
     } catch (error) {
-      if (error instanceof DockerOperationError) {
-        if (error.code === "compose-not-found" || error.code === "service-not-found") {
-          return context.json({ error: error.message, code: error.code }, 404);
-        }
-        if (error.code === "docker-not-installed" || error.code === "docker-not-running") {
-          return context.json({ error: error.message, code: error.code }, 503);
-        }
-        return context.json({ error: error.message, code: error.code }, 502);
-      }
-      throw error;
+      return handleDockerError(error, context);
     }
   });
-  app.post("/api/docker/:service/stop", async (context) => {
+  app.post("/api/workspaces/:id/docker/:service/stop", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const service = decodeURIComponent(context.req.param("service"));
     try {
-      return context.json(await dockerController.stop(service));
+      return context.json(await ws.dockerController.stop(service));
     } catch (error) {
-      if (error instanceof DockerOperationError) {
-        if (error.code === "compose-not-found" || error.code === "service-not-found") {
-          return context.json({ error: error.message, code: error.code }, 404);
-        }
-        if (error.code === "docker-not-installed" || error.code === "docker-not-running") {
-          return context.json({ error: error.message, code: error.code }, 503);
-        }
-        return context.json({ error: error.message, code: error.code }, 502);
-      }
-      throw error;
+      return handleDockerError(error, context);
     }
   });
-  app.post("/api/run/:script", async (context) => {
+  app.post("/api/workspaces/:id/run/:script", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const script = decodeURIComponent(context.req.param("script"));
-    const scan = await scanProject(options.projectRoot);
+    const scan = await scanProject(ws.root);
     const packageScript = scan.scripts[script];
     if (packageScript === void 0) {
       return context.json({ error: `Script "${script}" was not found.` }, 404);
@@ -2456,36 +2810,35 @@ function registerApiRoutes(app, options) {
       return context.json({ error: "Refusing to run dangerous script." }, 403);
     }
     const command = await resolvePackageRunCommand({
-      cwd: options.projectRoot,
+      cwd: ws.root,
       packageManager: scan.packageManager,
       script
     });
     if (command === null) {
       return context.json({ error: "Package manager executable was not found." }, 503);
     }
-    const processInfo = options.processManager.start({
-      cwd: options.projectRoot,
+    const processInfo = ws.processManager.start({
+      cwd: ws.root,
       script,
       command: command.command,
       args: command.args,
       displayCommand: command.displayCommand
     });
-    return context.json({
-      ...processInfo,
-      packageScript
-    });
+    return context.json({ ...processInfo, packageScript });
   });
-  app.post("/api/install", async (context) => {
-    const scan = await scanProject(options.projectRoot);
+  app.post("/api/workspaces/:id/install", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    const scan = await scanProject(ws.root);
     const command = await resolvePackageInstallCommand({
-      cwd: options.projectRoot,
+      cwd: ws.root,
       packageManager: scan.packageManager
     });
     if (command === null) {
       return context.json({ error: "Package manager executable was not found." }, 503);
     }
-    const processInfo = options.processManager.start({
-      cwd: options.projectRoot,
+    const processInfo = ws.processManager.start({
+      cwd: ws.root,
       script: "install",
       command: command.command,
       args: command.args,
@@ -2493,9 +2846,11 @@ function registerApiRoutes(app, options) {
     });
     return context.json(processInfo);
   });
-  app.post("/api/commands/:name", async (context) => {
+  app.post("/api/workspaces/:id/commands/:name", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const name = decodeURIComponent(context.req.param("name"));
-    const scan = await scanProject(options.projectRoot);
+    const scan = await scanProject(ws.root);
     const configuredCommand = scan.config?.config.commands?.[name] ?? null;
     if (configuredCommand === null) {
       return context.json({ error: `Configured command "${name}" was not found.` }, 404);
@@ -2503,7 +2858,7 @@ function registerApiRoutes(app, options) {
     if (isDangerousCommand(configuredCommand)) {
       return context.json({ error: "Refusing to run dangerous command." }, 403);
     }
-    const resolvedCommand = await resolveConfiguredCommand(options.projectRoot, configuredCommand);
+    const resolvedCommand = await resolveConfiguredCommand(ws.root, configuredCommand);
     if (resolvedCommand === null) {
       return context.json(
         {
@@ -2512,43 +2867,48 @@ function registerApiRoutes(app, options) {
         400
       );
     }
-    const processInfo = options.processManager.start({
-      cwd: options.projectRoot,
+    const processInfo = ws.processManager.start({
+      cwd: ws.root,
       script: name,
       command: resolvedCommand.command,
       args: resolvedCommand.args,
       displayCommand: resolvedCommand.displayCommand
     });
-    return context.json({
-      ...processInfo,
-      configuredCommand
-    });
+    return context.json({ ...processInfo, configuredCommand });
   });
-  app.post("/api/open/folder", async (context) => {
-    await open_default(options.projectRoot);
+  app.post("/api/workspaces/:id/open/folder", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    await open_default(ws.root);
     return context.json({ opened: true, target: "folder" });
   });
-  app.post("/api/open/package", async (context) => {
-    const packagePath = path12.join(options.projectRoot, "package.json");
-    if (!await realPathWithinRoot(options.projectRoot, packagePath)) {
+  app.post("/api/workspaces/:id/open/package", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    const packagePath = path14.join(ws.root, "package.json");
+    if (!await realPathWithinRoot(ws.root, packagePath)) {
       return context.json({ error: "package.json was not found inside the project root." }, 404);
     }
     await open_default(packagePath);
     return context.json({ opened: true, target: "package" });
   });
-  app.post("/api/open/terminal", (context) => {
-    const opened = openTerminalAt(options.projectRoot);
+  app.post("/api/workspaces/:id/open/terminal", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    const opened = openTerminalAt(ws.root);
     return context.json({ opened, target: "terminal" }, opened ? 200 : 501);
   });
-  app.post("/api/env/copy", async (context) => {
-    const scan = await scanProject(options.projectRoot);
+  app.post("/api/workspaces/:id/env/copy", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
+    const scan = await scanProject(ws.root);
     const examplePath = scan.env?.examplePath ?? null;
     const localPath = scan.env?.localPath ?? null;
     if (examplePath === null) {
       return context.json({ error: ".env.example was not found." }, 404);
     }
-    const destination = localPath ?? path12.join(options.projectRoot, scan.config?.config.env?.local ?? ".env");
-    if (!await realPathWithinRoot(options.projectRoot, examplePath) || !await writableDestinationWithinRoot(options.projectRoot, destination)) {
+    const destination = localPath ?? path14.join(ws.root, scan.config?.config.env?.local ?? ".env");
+    if (!await realPathWithinRoot(ws.root, examplePath) || !await writableDestinationWithinRoot(ws.root, destination)) {
       return context.json({ error: "Refusing to copy env files outside the project root." }, 400);
     }
     const copyResult = await copyFileExclusive(examplePath, destination);
@@ -2557,12 +2917,79 @@ function registerApiRoutes(app, options) {
     }
     return context.json({ copied: true });
   });
-  app.delete("/api/run/:pid", (context) => {
+  app.delete("/api/workspaces/:id/run/:pid", async (context) => {
+    const ws = await resolveWorkspace(context.req.param("id"));
+    if (!ws) return context.json({ error: "Workspace not found." }, 404);
     const pid = decodeURIComponent(context.req.param("pid"));
-    const stopped = options.processManager.stop(pid);
+    const stopped = ws.processManager.stop(pid);
     return context.json({ stopped });
   });
 }
+function registerHubApiRoutes(app, options) {
+  const { hub } = options;
+  registerMutationGuard(app, options.mutationToken);
+  async function resolveWorkspace(id) {
+    const entry = await hub.registry.resolve(id);
+    if (!entry) return null;
+    const runtime = hub.ensure(entry);
+    return {
+      root: runtime.root,
+      processManager: runtime.processManager,
+      dockerController: runtime.dockerController
+    };
+  }
+  app.get("/api/session", (context) => {
+    return context.json({ token: options.mutationToken });
+  });
+  app.get("/api/hub/status", (context) => {
+    return context.json({ status: "running", version: DEV_SURFACE_VERSION });
+  });
+  app.get("/api/workspaces", async (context) => {
+    return context.json(await hub.listSummaries());
+  });
+  app.post("/api/workspaces", async (context) => {
+    const body = await context.req.json().catch(() => null);
+    if (!body?.path) {
+      return context.json({ error: "path is required." }, 400);
+    }
+    try {
+      const entry = await hub.registry.add(body.path);
+      return context.json(entry, 201);
+    } catch (error) {
+      return context.json({ error: error instanceof Error ? error.message : "Invalid path." }, 400);
+    }
+  });
+  app.delete("/api/workspaces/:id", async (context) => {
+    const id = context.req.param("id");
+    const runtime = hub.get(id);
+    if (runtime) {
+      runtime.processManager.killAll();
+    }
+    const removed = await hub.registry.remove(id);
+    return context.json({ removed }, removed ? 200 : 404);
+  });
+  registerWorkspaceRoutes(app, resolveWorkspace);
+  app.get("/api/project", async (context) => {
+    const entries = await hub.registry.list();
+    if (entries.length === 0) return context.json({ error: "No workspaces registered." }, 404);
+    return context.json(await scanProject(hub.ensure(entries[0]).root));
+  });
+  app.get("/api/health", async (context) => {
+    const entries = await hub.registry.list();
+    if (entries.length === 0) return context.json({ error: "No workspaces registered." }, 404);
+    return context.json(await runDoctor(hub.ensure(entries[0]).root));
+  });
+  app.get("/api/processes", async (context) => {
+    const entries = await hub.registry.list();
+    if (entries.length === 0) return context.json([]);
+    return context.json(hub.ensure(entries[0]).processManager.list());
+  });
+  app.get("/api/logs", async (context) => {
+    const entries = await hub.registry.list();
+    if (entries.length === 0) return context.json([]);
+    return context.json(hub.ensure(entries[0]).processManager.listLogs());
+  });
+}
 
 // src/server/routes/ws.ts
 import { WebSocket, WebSocketServer } from "ws";
@@ -2570,6 +2997,9 @@ function isAllowedWebSocketRequest(request) {
   const origin = request.headers.origin;
   const host = request.headers.host;
   const secFetchSite = request.headers["sec-fetch-site"];
+  if (!isAllowedClientConnection(remoteAddressFromRequest(request), getListenHost())) {
+    return false;
+  }
   if (typeof host !== "string" || !isAllowedLocalHostHeader(host)) {
     return false;
   }
@@ -2588,32 +3018,63 @@ function isAllowedWebSocketRequest(request) {
     return false;
   }
 }
-function setupWebSocket(server, processManager) {
+function workspaceIdFromUrl(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url, "http://localhost");
+    return parsed.searchParams.get("workspace");
+  } catch {
+    return null;
+  }
+}
+function setupHubWebSocket(server, hub) {
   const wss = new WebSocketServer({
     server,
     path: "/ws",
     verifyClient: (info) => isAllowedWebSocketRequest(info.req)
   });
-  function broadcast(payload) {
+  const clientWorkspaces = /* @__PURE__ */ new WeakMap();
+  const attachedManagers = /* @__PURE__ */ new Set();
+  function attachManager(workspaceId2, processManager) {
+    if (attachedManagers.has(workspaceId2)) {
+      return;
+    }
+    attachedManagers.add(workspaceId2);
+    processManager.on("log", (event) => {
+      broadcastToWorkspace(workspaceId2, { type: "log", event });
+    });
+    processManager.on("process", (processInfo) => {
+      broadcastToWorkspace(workspaceId2, { type: "process", process: processInfo });
+    });
+  }
+  function broadcastToWorkspace(workspaceId2, payload) {
     const serialized = JSON.stringify(payload);
     for (const client of wss.clients) {
-      if (client.readyState === WebSocket.OPEN) {
+      if (client.readyState === WebSocket.OPEN && clientWorkspaces.get(client) === workspaceId2) {
         client.send(serialized);
       }
     }
   }
-  processManager.on("log", (event) => {
-    broadcast({ type: "log", event });
-  });
-  processManager.on("process", (processInfo) => {
-    broadcast({ type: "process", process: processInfo });
-  });
-  wss.on("connection", (socket) => {
+  wss.on("connection", async (socket, request) => {
+    const workspaceId2 = workspaceIdFromUrl(request.url);
+    if (!workspaceId2) {
+      socket.close(4e3, "Missing workspace query parameter.");
+      return;
+    }
+    const entry = await hub.registry.resolve(workspaceId2);
+    if (!entry) {
+      socket.close(4004, "Workspace not found.");
+      return;
+    }
+    const runtime = hub.ensure(entry);
+    clientWorkspaces.set(socket, workspaceId2);
+    attachManager(workspaceId2, runtime.processManager);
     socket.send(
       JSON.stringify({
         type: "hello",
-        processes: processManager.list(),
-        logs: processManager.listLogs()
+        workspace: workspaceId2,
+        processes: runtime.processManager.list(),
+        logs: runtime.processManager.listLogs()
       })
     );
   });
@@ -2621,51 +3082,44 @@ function setupWebSocket(server, processManager) {
 }
 
 // src/server/index.ts
-var HOST = "127.0.0.1";
-var DEFAULT_PORT = 4567;
-function assertLocalHost(host) {
-  if (host !== HOST) {
-    throw new Error("DevSurface must bind only to 127.0.0.1.");
-  }
-}
 async function fileExists(filePath) {
   try {
-    await fs17.access(filePath);
+    await fs19.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function findWebDistDir() {
-  const moduleDir = path13.dirname(fileURLToPath2(import.meta.url));
+  const moduleDir = path15.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path13.join(moduleDir, "..", "web", "dist"),
-    path13.join(moduleDir, "..", "..", "src", "web", "dist"),
-    path13.join(moduleDir, "web", "dist")
+    path15.join(moduleDir, "..", "web", "dist"),
+    path15.join(moduleDir, "..", "..", "src", "web", "dist"),
+    path15.join(moduleDir, "web", "dist")
   ];
   for (const candidate of candidates) {
-    if (await fileExists(path13.join(candidate, "index.html"))) {
+    if (await fileExists(path15.join(candidate, "index.html"))) {
       return candidate;
     }
   }
   return null;
 }
-function toListenError(error, port) {
+function toListenError(error, host, port) {
   const code = error instanceof Error ? error.code : void 0;
   if (code === "EADDRINUSE") {
     return new Error(
-      `Port ${port} is already in use on ${HOST}. Stop the other process or run DevSurface with --port ${port + 1}.`,
+      `Port ${port} is already in use on ${host}. Stop the other process or run DevSurface with --port ${port + 1}.`,
       { cause: error }
     );
   }
   if (code === "EACCES") {
-    return new Error(`DevSurface does not have permission to bind to ${HOST}:${port}.`, {
+    return new Error(`DevSurface does not have permission to bind to ${host}:${port}.`, {
       cause: error
     });
   }
   return error instanceof Error ? error : new Error(String(error));
 }
-async function listenOnLocalHost(server, wss, port) {
+async function listenOnHost(server, wss, host, port) {
   await new Promise((resolve, reject) => {
     let settled = false;
     const cleanup = () => {
@@ -2674,17 +3128,13 @@ async function listenOnLocalHost(server, wss, port) {
       wss.off("error", onError);
     };
     const onError = (error) => {
-      if (settled) {
-        return;
-      }
+      if (settled) return;
       settled = true;
       cleanup();
-      reject(toListenError(error, port));
+      reject(toListenError(error, host, port));
     };
     const onListening = () => {
-      if (settled) {
-        return;
-      }
+      if (settled) return;
       settled = true;
       cleanup();
       resolve();
@@ -2692,7 +3142,7 @@ async function listenOnLocalHost(server, wss, port) {
     wss.once("error", onError);
     server.once("error", onError);
     server.once("listening", onListening);
-    server.listen(port, HOST);
+    server.listen(port, host);
   });
 }
 async function closeWebSocketServer(wss) {
@@ -2714,18 +3164,13 @@ async function closeHttpServer(server) {
     });
   });
 }
-async function createApp(options) {
-  const app = new Hono();
-  registerApiRoutes(app, {
-    ...options,
-    mutationToken: options.mutationToken ?? createMutationToken()
-  });
+async function mountWebUi(app) {
   const webDistDir = await findWebDistDir();
   if (webDistDir !== null) {
     app.use("/assets/*", serveStatic({ root: webDistDir }));
     app.get("/favicon.svg", serveStatic({ root: webDistDir }));
     app.get("*", async (context) => {
-      const html = await fs17.readFile(path13.join(webDistDir, "index.html"), "utf8");
+      const html = await fs19.readFile(path15.join(webDistDir, "index.html"), "utf8");
       return context.html(html);
     });
   } else {
@@ -2737,46 +3182,96 @@ async function createApp(options) {
       )
     );
   }
+}
+async function createHubApp(options) {
+  const app = new Hono();
+  registerHubApiRoutes(app, {
+    hub: options.hub,
+    mutationToken: options.mutationToken ?? createMutationToken()
+  });
+  await mountWebUi(app);
   return app;
 }
-async function startDevSurfaceServer(options) {
-  assertLocalHost(HOST);
+async function startHubServer(options) {
+  const host = initializeListenHost();
   const port = options.port ?? DEFAULT_PORT;
-  const processManager = new ProcessManager();
-  processManager.attachCleanupHandlers();
-  const app = await createApp({
-    projectRoot: options.projectRoot,
-    processManager
-  });
+  const hub = new Hub({ dataDir: options.dataDir });
+  hub.attachCleanupHandlers();
+  if (options.initialWorkspace) {
+    await hub.registry.add(options.initialWorkspace);
+  }
+  const mutationToken = createMutationToken();
+  const app = await createHubApp({ hub, mutationToken });
   const server = createAdaptorServer({
     fetch: app.fetch,
-    hostname: HOST
+    hostname: host
   });
-  const wss = setupWebSocket(server, processManager);
-  await listenOnLocalHost(server, wss, port);
-  processManager.attachCleanupHandlers();
-  const url = `http://${HOST}:${port}`;
+  const wss = setupHubWebSocket(server, hub);
+  await listenOnHost(server, wss, host, port);
+  const url = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}`;
   if (options.openBrowser !== false) {
-    await open_default(url);
+    const entries = await hub.registry.list();
+    const deepLink = entries.length > 0 ? `${url}/?workspace=${entries[0].id}` : url;
+    await open_default(deepLink);
   }
+  const dummyProcessManager = new ProcessManager();
   return {
     url,
     port,
-    processManager,
+    host,
+    hub,
+    processManager: dummyProcessManager,
     close: async () => {
-      processManager.killAll();
+      hub.killAll();
       await closeWebSocketServer(wss);
       await closeHttpServer(server);
     }
   };
 }
 
-// src/version.ts
-var DEV_SURFACE_VERSION = "0.3.0";
+// src/cli/hub/client.ts
+async function isHubRunning(port = DEFAULT_PORT) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/hub/status`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function registerWorkspaceRemotely(dirPath, port = DEFAULT_PORT) {
+  try {
+    const sessionResponse = await fetch(`http://127.0.0.1:${port}/api/session`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (!sessionResponse.ok) return null;
+    const session = await sessionResponse.json();
+    const response = await fetch(`http://127.0.0.1:${port}/api/workspaces`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-DevSurface-Intent": "dashboard",
+        "X-DevSurface-Token": session.token
+      },
+      body: JSON.stringify({ path: dirPath }),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+function dashboardUrl(workspaceId2, port = DEFAULT_PORT, host = DEFAULT_HOST) {
+  const displayHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+  return `http://${displayHost}:${port}/?workspace=${workspaceId2}`;
+}
 
 // src/cli/commands/start.ts
 async function startCommand(options) {
   const cwd = options.cwd ?? process.cwd();
+  const port = options.port ?? 4567;
   console.log(pc5.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
   console.log("Scanning project...\n");
   const scan = await scanProject(cwd);
@@ -2789,13 +3284,87 @@ async function startCommand(options) {
       console.log(`  ${marker} ${item.title}`);
     }
   }
-  const server = await startDevSurfaceServer({
-    projectRoot: cwd,
+  if (await isHubRunning(port)) {
+    console.log("\nHub already running. Registering workspace...");
+    const registered = await registerWorkspaceRemotely(cwd, port);
+    if (registered) {
+      const url = dashboardUrl(registered.id, port);
+      console.log(`Workspace ${pc5.cyan(registered.name)} attached.`);
+      console.log(`Dashboard -> ${pc5.cyan(url)}`);
+      if (options.openBrowser !== false) {
+        await open_default(url);
+      }
+      return;
+    }
+    console.log("Could not register with running hub. Starting a new instance...");
+  }
+  const server = await startHubServer({
+    port,
+    openBrowser: options.openBrowser,
+    initialWorkspace: cwd
+  });
+  console.log(`
+Dashboard running at -> ${pc5.cyan(server.url)}`);
+}
+
+// src/cli/commands/serve.ts
+import pc6 from "picocolors";
+async function serveCommand(options) {
+  console.log(pc6.bold(`DevSurface Hub v${DEV_SURFACE_VERSION}`));
+  console.log("Starting hub server...\n");
+  const server = await startHubServer({
     port: options.port,
     openBrowser: options.openBrowser
   });
+  const summaries = await server.hub.listSummaries();
+  if (summaries.length > 0) {
+    console.log(`Registered workspaces: ${summaries.length}`);
+    for (const ws of summaries) {
+      console.log(`  ${pc6.cyan(ws.name)} -> ${ws.path}`);
+    }
+  } else {
+    console.log(
+      "No workspaces registered yet. Use `devsurface workspace add` or `npx devsurface` inside a project."
+    );
+  }
   console.log(`
-Dashboard running at -> ${pc5.cyan(server.url)}`);
+Hub running at -> ${pc6.cyan(server.url)}`);
+}
+
+// src/cli/commands/workspace.ts
+import path16 from "path";
+import pc7 from "picocolors";
+async function workspaceAddCommand(dirPath) {
+  const registry = new WorkspaceRegistry();
+  const target = path16.resolve(dirPath ?? process.cwd());
+  const entry = await registry.add(target);
+  console.log(`Added workspace ${pc7.cyan(entry.name)} (${entry.id}) -> ${entry.path}`);
+}
+async function workspaceListCommand() {
+  const registry = new WorkspaceRegistry();
+  const entries = await registry.list();
+  if (entries.length === 0) {
+    console.log(
+      "No workspaces registered. Run `devsurface workspace add` or `npx devsurface` inside a project."
+    );
+    return;
+  }
+  console.log(`${entries.length} workspace${entries.length === 1 ? "" : "s"}:
+`);
+  for (const entry of entries) {
+    console.log(`  ${pc7.cyan(entry.name)} (${entry.id})`);
+    console.log(`    ${entry.path}`);
+  }
+}
+async function workspaceRemoveCommand(id) {
+  const registry = new WorkspaceRegistry();
+  const removed = await registry.remove(id);
+  if (removed) {
+    console.log(`Removed workspace ${pc7.cyan(id)}.`);
+  } else {
+    console.error(`Workspace "${id}" not found.`);
+    process.exitCode = 1;
+  }
 }
 
 // src/cli/index.ts
@@ -2823,6 +3392,24 @@ program.name("devsurface").description("Turn any Node.js repository into a local
     })
   );
 });
+program.command("serve").description("Start the DevSurface hub server (multi-workspace mode).").option("-p, --port <port>", "hub port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
+  handle(
+    serveCommand({
+      port: options.port,
+      openBrowser: options.open
+    })
+  );
+});
+var workspace = program.command("workspace").description("Manage registered workspaces.");
+workspace.command("add [path]").description("Register a project directory with the hub.").action((dirPath) => {
+  handle(workspaceAddCommand(dirPath));
+});
+workspace.command("list").description("List all registered workspaces.").action(() => {
+  handle(workspaceListCommand());
+});
+workspace.command("remove <id>").description("Remove a workspace from the hub registry.").action((id) => {
+  handle(workspaceRemoveCommand(id));
+});
 program.command("scan").description("Print detected project info.").action(() => {
   handle(scanCommand(process.cwd()));
 });