devsurface 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,1763 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/cli/commands/doctor.ts
+import pc from "picocolors";
+
+// src/core/doctor/index.ts
+import { promises as fs9 } from "fs";
+import path9 from "path";
+
+// src/core/scanner/index.ts
+import { promises as fs8 } from "fs";
+import path8 from "path";
+
+// src/core/config/load.ts
+import { promises as fs } from "fs";
+import path from "path";
+
+// src/core/config/defaults.ts
+var CONFIG_FILE_NAME = "devsurface.config.json";
+var defaultConfig = {
+  name: "My App",
+  description: "Local developer control panel",
+  commands: {
+    install: "npm install",
+    dev: "npm run dev",
+    build: "npm run build",
+    test: "npm test",
+    lint: "npm run lint"
+  },
+  groups: {
+    Setup: ["install"],
+    Development: ["dev"],
+    Quality: ["test", "lint"],
+    Build: ["build"]
+  },
+  ports: [3e3],
+  env: {
+    example: ".env.example",
+    local: ".env"
+  },
+  services: {
+    docker: true
+  },
+  docs: ""
+};
+
+// src/core/config/load.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toStringRecord(value, warnings, label) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!isRecord(value)) {
+    warnings.push(`${label} must be an object.`);
+    return void 0;
+  }
+  const record = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      record[key] = raw;
+    } else {
+      warnings.push(`${label}.${key} must be a string.`);
+    }
+  }
+  return record;
+}
+function toGroups(value, warnings) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!isRecord(value)) {
+    warnings.push("groups must be an object.");
+    return void 0;
+  }
+  const groups = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (Array.isArray(raw) && raw.every((entry) => typeof entry === "string")) {
+      groups[key] = raw;
+    } else {
+      warnings.push(`groups.${key} must be an array of command names.`);
+    }
+  }
+  return groups;
+}
+function toPorts(value, warnings) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    warnings.push("ports must be an array of numbers.");
+    return void 0;
+  }
+  const ports = value.filter(
+    (port) => Number.isInteger(port) && port > 0 && port < 65536
+  );
+  if (ports.length !== value.length) {
+    warnings.push("ports may only contain integers between 1 and 65535.");
+  }
+  return ports;
+}
+function validateConfig(raw) {
+  const warnings = [];
+  if (!isRecord(raw)) {
+    return { config: {}, warnings: ["devsurface.config.json must contain a JSON object."] };
+  }
+  const env = isRecord(raw.env) ? {
+    example: typeof raw.env.example === "string" ? raw.env.example : void 0,
+    local: typeof raw.env.local === "string" ? raw.env.local : void 0
+  } : void 0;
+  if (raw.env !== void 0 && !isRecord(raw.env)) {
+    warnings.push("env must be an object.");
+  }
+  const services = isRecord(raw.services) ? {
+    docker: typeof raw.services.docker === "boolean" ? raw.services.docker : void 0
+  } : void 0;
+  if (raw.services !== void 0 && !isRecord(raw.services)) {
+    warnings.push("services must be an object.");
+  }
+  return {
+    config: {
+      name: typeof raw.name === "string" ? raw.name : void 0,
+      description: typeof raw.description === "string" ? raw.description : void 0,
+      commands: toStringRecord(raw.commands, warnings, "commands"),
+      groups: toGroups(raw.groups, warnings),
+      ports: toPorts(raw.ports, warnings),
+      env,
+      services,
+      docs: typeof raw.docs === "string" ? raw.docs : void 0
+    },
+    warnings
+  };
+}
+async function loadConfig(root) {
+  const configPath = path.join(root, CONFIG_FILE_NAME);
+  try {
+    const content = await fs.readFile(configPath, "utf8");
+    const parsed = JSON.parse(content);
+    const { config, warnings } = validateConfig(parsed);
+    return { path: configPath, config, warnings };
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+    if (code === "ENOENT") {
+      return null;
+    }
+    if (error instanceof SyntaxError) {
+      return {
+        path: configPath,
+        config: {},
+        warnings: [`${CONFIG_FILE_NAME} contains invalid JSON.`]
+      };
+    }
+    return null;
+  }
+}
+
+// src/core/scanner/docker.ts
+import { promises as fs3 } from "fs";
+import os from "os";
+import path3 from "path";
+import spawn from "cross-spawn";
+import { parse as parseYaml } from "yaml";
+
+// src/core/process/executable.ts
+import { constants } from "fs";
+import { promises as fs2 } from "fs";
+import path2 from "path";
+function isWithinRoot(root, target) {
+  const resolvedRoot = path2.resolve(root);
+  const resolvedTarget = path2.resolve(target);
+  const relative = path2.relative(resolvedRoot, resolvedTarget);
+  return relative === "" || !relative.startsWith("..") && !path2.isAbsolute(relative);
+}
+function pathEntries(pathValue) {
+  return pathValue.split(path2.delimiter).map((entry) => entry.trim().replace(/^"|"$/g, "")).filter((entry) => entry.length > 0);
+}
+function hasPathSeparator(command) {
+  return command.includes("/") || command.includes("\\");
+}
+function executableNames(command) {
+  if (process.platform !== "win32" || path2.extname(command)) {
+    return [command];
+  }
+  const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").map((extension) => extension.trim().toLowerCase()).filter(Boolean);
+  return extensions.map((extension) => `${command}${extension}`);
+}
+async function executableOutsideRoot(root, candidate) {
+  if (isWithinRoot(root, candidate)) {
+    return null;
+  }
+  try {
+    const [realRoot, realCandidate] = await Promise.all([
+      fs2.realpath(root),
+      fs2.realpath(candidate)
+    ]);
+    if (isWithinRoot(realRoot, realCandidate)) {
+      return null;
+    }
+    await fs2.access(realCandidate, constants.X_OK);
+    return realCandidate;
+  } catch {
+    return null;
+  }
+}
+async function resolveExecutableOutsideRoot(root, command) {
+  if (path2.isAbsolute(command) || hasPathSeparator(command)) {
+    return await executableOutsideRoot(root, path2.resolve(command));
+  }
+  for (const entry of pathEntries(process.env.PATH ?? "")) {
+    const directory = path2.resolve(entry);
+    if (isWithinRoot(root, directory)) {
+      continue;
+    }
+    for (const executableName of executableNames(command)) {
+      const executable = await executableOutsideRoot(root, path2.join(directory, executableName));
+      if (executable !== null) {
+        return executable;
+      }
+    }
+  }
+  return null;
+}
+
+// src/core/scanner/docker.ts
+var COMPOSE_FILES = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"];
+async function fileExists(filePath) {
+  try {
+    await fs3.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getComposeFiles(root) {
+  const checks = await Promise.all(
+    COMPOSE_FILES.map(async (file) => {
+      const filePath = path3.join(root, file);
+      return await fileExists(filePath) ? filePath : null;
+    })
+  );
+  return checks.filter((filePath) => filePath !== null);
+}
+async function extractServices(composePath) {
+  try {
+    const content = await fs3.readFile(composePath, "utf8");
+    const parsed = parseYaml(content);
+    if (typeof parsed === "object" && parsed !== null && "services" in parsed && typeof parsed.services === "object" && parsed.services !== null) {
+      return Object.keys(parsed.services);
+    }
+  } catch {
+    return [];
+  }
+  return [];
+}
+function isWithinRoot2(root, target) {
+  const relative = path3.relative(path3.resolve(root), path3.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path3.isAbsolute(relative);
+}
+function dockerCommandCwd(root) {
+  const candidates = [os.homedir(), os.tmpdir(), path3.parse(path3.resolve(root)).root];
+  return candidates.find((candidate) => !isWithinRoot2(root, candidate)) ?? os.homedir();
+}
+async function runDockerCommand(root, args, timeoutMs = 2500) {
+  const dockerExecutable = await resolveExecutableOutsideRoot(root, "docker");
+  if (dockerExecutable === null) {
+    return { code: null, stdout: "", stderr: "" };
+  }
+  return await new Promise((resolve) => {
+    const child = spawn(dockerExecutable, args, {
+      cwd: dockerCommandCwd(root),
+      windowsHide: true
+    });
+    let settled = false;
+    let stdout = "";
+    let stderr = "";
+    const timeout = setTimeout(() => {
+      settled = true;
+      child.kill();
+      resolve({ code: null, stdout, stderr });
+    }, timeoutMs);
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", () => {
+      clearTimeout(timeout);
+      if (!settled) {
+        settled = true;
+        resolve({ code: null, stdout, stderr });
+      }
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      if (!settled) {
+        settled = true;
+        resolve({ code, stdout, stderr });
+      }
+    });
+  });
+}
+async function isDockerRunning(root) {
+  const result = await runDockerCommand(root, ["info"]);
+  return result.code === 0;
+}
+function parseComposePs(output) {
+  const statuses = /* @__PURE__ */ new Map();
+  const compactOutput = output.trim();
+  if (!compactOutput) {
+    return statuses;
+  }
+  try {
+    const parsed = JSON.parse(compactOutput);
+    const rows2 = Array.isArray(parsed) ? parsed : [parsed];
+    for (const row of rows2) {
+      addComposeStatusRow(statuses, row);
+    }
+    return statuses;
+  } catch {
+  }
+  const rows = compactOutput.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  for (const row of rows) {
+    try {
+      const parsed = JSON.parse(row);
+      addComposeStatusRow(statuses, parsed);
+    } catch {
+      return statuses;
+    }
+  }
+  return statuses;
+}
+function addComposeStatusRow(statuses, row) {
+  if (typeof row !== "object" || row === null) {
+    return;
+  }
+  const record = row;
+  if (typeof record.Service !== "string") {
+    return;
+  }
+  const state = typeof record.State === "string" ? record.State.toLowerCase() : "";
+  statuses.set(record.Service, {
+    name: record.Service,
+    status: state === "running" ? "running" : state ? "stopped" : "unknown",
+    containerId: typeof record.ID === "string" && record.ID.length > 0 ? record.ID : null
+  });
+}
+async function getServiceStatuses(root, serviceNames, dockerRunning) {
+  if (serviceNames.length === 0) {
+    return [];
+  }
+  if (!dockerRunning) {
+    return serviceNames.map((service) => ({
+      name: service,
+      status: "unknown",
+      containerId: null
+    }));
+  }
+  const ps = await runDockerCommand(root, [
+    "compose",
+    "--project-directory",
+    root,
+    "ps",
+    "--format",
+    "json"
+  ]);
+  const statuses = ps.code === 0 ? parseComposePs(ps.stdout) : /* @__PURE__ */ new Map();
+  return serviceNames.map(
+    (service) => statuses.get(service) ?? {
+      name: service,
+      status: "stopped",
+      containerId: null
+    }
+  );
+}
+async function detectDocker(root) {
+  const composeFiles = await getComposeFiles(root);
+  if (composeFiles.length === 0) {
+    return null;
+  }
+  const serviceLists = await Promise.all(
+    composeFiles.map((composeFile) => extractServices(composeFile))
+  );
+  const serviceNames = Array.from(new Set(serviceLists.flat()));
+  const dockerRunning = await isDockerRunning(root);
+  return {
+    composeFiles,
+    services: await getServiceStatuses(root, serviceNames, dockerRunning),
+    dockerRunning
+  };
+}
+
+// src/core/scanner/env.ts
+import { promises as fs4 } from "fs";
+import path4 from "path";
+async function readIfPresent(filePath) {
+  try {
+    return await fs4.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function resolveInsideRoot(root, configuredPath) {
+  const resolvedRoot = path4.resolve(root);
+  const resolvedPath = path4.resolve(resolvedRoot, configuredPath);
+  const relative = path4.relative(resolvedRoot, resolvedPath);
+  const insideRoot = relative === "" || !relative.startsWith("..") && !path4.isAbsolute(relative);
+  return insideRoot ? resolvedPath : null;
+}
+async function resolveExistingInsideRoot(root, configuredPath) {
+  const candidate = resolveInsideRoot(root, configuredPath);
+  if (candidate === null) {
+    return null;
+  }
+  try {
+    const [realRoot, realCandidate] = await Promise.all([
+      fs4.realpath(root),
+      fs4.realpath(candidate)
+    ]);
+    const relative = path4.relative(realRoot, realCandidate);
+    const insideRoot = relative === "" || !relative.startsWith("..") && !path4.isAbsolute(relative);
+    return insideRoot ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+function parseEnvKeys(content) {
+  const keys = [];
+  const emptyKeys = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const normalized = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const separator = normalized.indexOf("=");
+    if (separator <= 0) {
+      continue;
+    }
+    const key = normalized.slice(0, separator).trim();
+    const value = normalized.slice(separator + 1).trim();
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      keys.push(key);
+      if (value.length === 0 || value === '""' || value === "''") {
+        emptyKeys.push(key);
+      }
+    }
+  }
+  return { keys: Array.from(new Set(keys)), emptyKeys: Array.from(new Set(emptyKeys)) };
+}
+async function detectEnv(root, config) {
+  const exampleName = config?.env?.example ?? ".env.example";
+  const localName = config?.env?.local ?? ".env";
+  const [examplePath, localPath] = await Promise.all([
+    resolveExistingInsideRoot(root, exampleName),
+    resolveExistingInsideRoot(root, localName)
+  ]);
+  const [exampleContent, localContent] = await Promise.all([
+    examplePath === null ? null : readIfPresent(examplePath),
+    localPath === null ? null : readIfPresent(localPath)
+  ]);
+  if (exampleContent === null && localContent === null) {
+    return null;
+  }
+  const example = exampleContent === null ? { keys: [], emptyKeys: [] } : parseEnvKeys(exampleContent);
+  const local = localContent === null ? { keys: [], emptyKeys: [] } : parseEnvKeys(localContent);
+  const localKeySet = new Set(local.keys);
+  const localEmptySet = new Set(local.emptyKeys);
+  const missingKeys = example.keys.filter((key) => !localKeySet.has(key));
+  const emptyKeys = local.keys.filter((key) => localEmptySet.has(key));
+  return {
+    examplePath: exampleContent === null ? null : examplePath,
+    localPath: localContent === null ? null : localPath,
+    hasExample: exampleContent !== null,
+    hasLocal: localContent !== null,
+    exampleKeys: example.keys,
+    localKeys: local.keys,
+    missingKeys,
+    emptyKeys,
+    keys: example.keys.map((key) => ({
+      key,
+      present: localKeySet.has(key),
+      empty: localEmptySet.has(key)
+    }))
+  };
+}
+
+// src/core/scanner/framework.ts
+var frameworkPackages = [
+  { packageName: "next", label: "Next.js" },
+  { packageName: "vite", label: "Vite" },
+  { packageName: "express", label: "Express" },
+  { packageName: "fastify", label: "Fastify" },
+  { packageName: "@nestjs/core", label: "NestJS" },
+  { packageName: "@remix-run/react", label: "Remix" },
+  { packageName: "prisma", label: "Prisma" }
+];
+function detectFramework(packageJson) {
+  if (packageJson === null) {
+    return null;
+  }
+  const dependencies = {
+    ...packageJson.data.dependencies,
+    ...packageJson.data.devDependencies,
+    ...packageJson.data.optionalDependencies,
+    ...packageJson.data.peerDependencies
+  };
+  const detected = frameworkPackages.filter((framework) => dependencies[framework.packageName] !== void 0).map((framework) => framework.label);
+  if (detected.length === 0) {
+    return {
+      type: "Node.js",
+      detected: ["Node.js"]
+    };
+  }
+  return {
+    type: ["Node.js", ...detected].join(" / "),
+    detected
+  };
+}
+
+// src/core/scanner/git.ts
+import { promises as fs5 } from "fs";
+import path5 from "path";
+function isWithinRoot3(root, target) {
+  const resolvedRoot = path5.resolve(root);
+  const resolvedTarget = path5.resolve(target);
+  const relative = path5.relative(resolvedRoot, resolvedTarget);
+  return relative === "" || !relative.startsWith("..") && !path5.isAbsolute(relative);
+}
+async function resolveGitDirectory(root) {
+  const gitPath = path5.join(root, ".git");
+  try {
+    const stat = await fs5.stat(gitPath);
+    if (stat.isDirectory()) {
+      return gitPath;
+    }
+    if (stat.isFile()) {
+      const content = await fs5.readFile(gitPath, "utf8");
+      const match = content.match(/^gitdir:\s*(.+)\s*$/m);
+      if (match) {
+        const gitDir = match[1].trim();
+        const resolvedGitDir = path5.isAbsolute(gitDir) ? path5.resolve(gitDir) : path5.resolve(root, gitDir);
+        if (!isWithinRoot3(root, resolvedGitDir)) {
+          return null;
+        }
+        const [realRoot, realGitDir] = await Promise.all([
+          fs5.realpath(root),
+          fs5.realpath(resolvedGitDir)
+        ]);
+        return isWithinRoot3(realRoot, realGitDir) ? resolvedGitDir : null;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function detectGit(root) {
+  const gitRoot = await resolveGitDirectory(root);
+  if (gitRoot === null) {
+    return null;
+  }
+  try {
+    const head = await fs5.readFile(path5.join(gitRoot, "HEAD"), "utf8");
+    const refMatch = head.match(/^ref:\s+refs\/heads\/(.+)\s*$/);
+    return {
+      root: gitRoot,
+      branch: refMatch ? refMatch[1] : head.trim().slice(0, 12)
+    };
+  } catch {
+    return {
+      root: gitRoot,
+      branch: null
+    };
+  }
+}
+
+// src/core/scanner/packageManager.ts
+import { promises as fs6 } from "fs";
+import path6 from "path";
+var lockFiles = [
+  { file: "pnpm-lock.yaml", manager: "pnpm" },
+  { file: "yarn.lock", manager: "yarn" },
+  { file: "bun.lockb", manager: "bun" },
+  { file: "bun.lock", manager: "bun" },
+  { file: "package-lock.json", manager: "npm" }
+];
+async function exists(filePath) {
+  try {
+    await fs6.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function detectPackageManager(root) {
+  for (const lockFile of lockFiles) {
+    if (await exists(path6.join(root, lockFile.file))) {
+      return lockFile.manager;
+    }
+  }
+  return null;
+}
+
+// src/core/scanner/packageJson.ts
+import { promises as fs7 } from "fs";
+import path7 from "path";
+async function readPackageJson(root) {
+  const packageJsonPath = path7.join(root, "package.json");
+  try {
+    const content = await fs7.readFile(packageJsonPath, "utf8");
+    const data = JSON.parse(content);
+    return { path: packageJsonPath, data };
+  } catch {
+    return null;
+  }
+}
+
+// src/core/scanner/ports.ts
+import net from "net";
+function uniquePorts(ports) {
+  return Array.from(
+    new Set(ports.filter((port) => Number.isInteger(port) && port > 0 && port < 65536))
+  );
+}
+function inferPortsFromScripts(scripts) {
+  const ports = [];
+  for (const command of Object.values(scripts)) {
+    const patterns = [
+      /(?:--port|-p)\s+(\d{2,5})/g,
+      /\bPORT=(\d{2,5})\b/g,
+      /localhost:(\d{2,5})/g,
+      /127\.0\.0\.1:(\d{2,5})/g
+    ];
+    for (const pattern of patterns) {
+      for (const match of command.matchAll(pattern)) {
+        ports.push(Number(match[1]));
+      }
+    }
+  }
+  return uniquePorts(ports);
+}
+function defaultPortsForFramework(framework) {
+  if (framework === null) {
+    return [];
+  }
+  const ports = [];
+  if (framework.detected.includes("Next.js") || framework.detected.includes("Express")) {
+    ports.push(3e3);
+  }
+  if (framework.detected.includes("Vite")) {
+    ports.push(5173);
+  }
+  if (framework.detected.includes("Prisma")) {
+    ports.push(5555);
+  }
+  return uniquePorts(ports);
+}
+async function probePort(port) {
+  return await new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => {
+      resolve({ port, inUse: true });
+    });
+    server.once("listening", () => {
+      server.close(() => {
+        resolve({ port, inUse: false });
+      });
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+async function detectPorts(ports) {
+  const normalized = uniquePorts(ports);
+  if (normalized.length === 0) {
+    return null;
+  }
+  return await Promise.all(normalized.map((port) => probePort(port)));
+}
+
+// src/core/scanner/scripts.ts
+function extractScripts(packageJson) {
+  if (!packageJson?.data.scripts || typeof packageJson.data.scripts !== "object" || Array.isArray(packageJson.data.scripts)) {
+    return null;
+  }
+  return Object.fromEntries(
+    Object.entries(packageJson.data.scripts).filter((entry) => {
+      const [, command] = entry;
+      return typeof command === "string";
+    })
+  );
+}
+
+// src/core/scanner/index.ts
+async function findFirstFile(root, candidates) {
+  for (const candidate of candidates) {
+    const filePath = path8.join(root, candidate);
+    try {
+      const stat = await fs8.stat(filePath);
+      if (stat.isFile()) {
+        return { path: filePath, exists: true };
+      }
+    } catch {
+    }
+  }
+  return { path: null, exists: false };
+}
+function configuredPorts(configPorts) {
+  return Array.isArray(configPorts) ? configPorts : [];
+}
+async function scanProject(root = process.cwd()) {
+  const config = await loadConfig(root);
+  const packageJson = await readPackageJson(root);
+  const scripts = extractScripts(packageJson) ?? {};
+  const framework = detectFramework(packageJson);
+  const portsToProbe = [
+    ...configuredPorts(config?.config.ports),
+    ...inferPortsFromScripts(scripts),
+    ...defaultPortsForFramework(framework)
+  ];
+  const [packageManager, env, docker, git, ports, readme, license] = await Promise.all([
+    detectPackageManager(root),
+    detectEnv(root, config?.config),
+    detectDocker(root),
+    detectGit(root),
+    detectPorts(portsToProbe),
+    findFirstFile(root, ["README.md", "README"]),
+    findFirstFile(root, ["LICENSE", "LICENSE.md", "COPYING"])
+  ]);
+  return {
+    root,
+    projectName: config?.config.name ?? packageJson?.data.name ?? path8.basename(root),
+    packageJson,
+    packageManager: packageManager ?? (packageJson ? "npm" : null),
+    scripts,
+    env,
+    docker,
+    git,
+    framework,
+    ports: ports ?? [],
+    readme,
+    license,
+    config
+  };
+}
+
+// src/core/doctor/index.ts
+async function pathExists(filePath) {
+  try {
+    await fs9.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readIfPresent2(filePath) {
+  if (filePath === null) {
+    return null;
+  }
+  try {
+    return await fs9.readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+function extractReadmeScriptReferences(readmeContent) {
+  const references = /* @__PURE__ */ new Set();
+  const commandRegexes = [
+    /\bnpm\s+run\s+([A-Za-z0-9:_-]+)/g,
+    /\bpnpm\s+run\s+([A-Za-z0-9:_-]+)/g,
+    /\bbun\s+run\s+([A-Za-z0-9:_-]+)/g,
+    /\byarn\s+run\s+([A-Za-z0-9:_-]+)/g,
+    /\bnpm\s+(test|start|build)\b/g,
+    /\bpnpm\s+(test|start|build)\b/g,
+    /\byarn\s+(test|start|build)\b/g,
+    /\bbun\s+(test|start|build)\b/g
+  ];
+  for (const regex of commandRegexes) {
+    for (const match of readmeContent.matchAll(regex)) {
+      references.add(match[1]);
+    }
+  }
+  return Array.from(references);
+}
+function warning(id, severity, title, message, target) {
+  return { id, severity, title, message, target };
+}
+async function runDoctor(root = process.cwd(), scan) {
+  const result = scan ?? await scanProject(root);
+  const warnings = [];
+  for (const configWarning of result.config?.warnings ?? []) {
+    warnings.push(
+      warning("config-warning", "warning", "Config warning", configWarning, result.config?.path)
+    );
+  }
+  if (result.packageJson === null) {
+    warnings.push(
+      warning(
+        "missing-package-json",
+        "error",
+        "No package.json",
+        "This directory is not a Node.js project."
+      )
+    );
+    return warnings;
+  }
+  if (!await pathExists(path9.join(root, "node_modules", ".bin"))) {
+    warnings.push(
+      warning(
+        "missing-node-modules",
+        "warning",
+        "Dependencies are not installed",
+        "node_modules/.bin is missing. Run the project install command before starting scripts."
+      )
+    );
+  }
+  if (result.env?.hasExample && !result.env.hasLocal) {
+    warnings.push(
+      warning(
+        "missing-env",
+        "error",
+        ".env is missing",
+        ".env.example exists, but the local .env file is missing.",
+        result.env.examplePath ?? void 0
+      )
+    );
+  }
+  if (result.env && result.env.missingKeys.length > 0 && result.env.hasLocal) {
+    warnings.push(
+      warning(
+        "missing-env-keys",
+        "warning",
+        "Environment keys are missing",
+        `Missing keys: ${result.env.missingKeys.join(", ")}. Values are intentionally hidden.`
+      )
+    );
+  }
+  if (result.env && result.env.emptyKeys.length > 0) {
+    warnings.push(
+      warning(
+        "empty-env-keys",
+        "info",
+        "Environment keys are empty",
+        `Empty keys: ${result.env.emptyKeys.join(", ")}. Values are intentionally hidden.`
+      )
+    );
+  }
+  const missingReadme = !result.readme.exists;
+  if (missingReadme) {
+    warnings.push(
+      warning("missing-readme", "warning", "No README", "No README.md or README file was found.")
+    );
+  } else {
+    const readme = await readIfPresent2(result.readme.path);
+    if (readme !== null) {
+      const references = extractReadmeScriptReferences(readme);
+      const missingScripts = references.filter((script) => result.scripts[script] === void 0);
+      if (missingScripts.length > 0) {
+        warnings.push(
+          warning(
+            "readme-script-mismatch",
+            "warning",
+            "README references missing scripts",
+            `README mentions scripts not present in package.json: ${missingScripts.join(", ")}.`
+          )
+        );
+      }
+    }
+  }
+  for (const port of result.ports.filter((probe) => probe.inUse)) {
+    warnings.push(
+      warning(
+        `port-${port.port}-in-use`,
+        "error",
+        `Port ${port.port} is already in use`,
+        `Something is already bound to 127.0.0.1:${port.port}.`
+      )
+    );
+  }
+  if (result.docker && result.docker.dockerRunning === false) {
+    warnings.push(
+      warning(
+        "docker-not-running",
+        "warning",
+        "Docker Compose found but Docker is not running",
+        "A compose file exists, but the Docker daemon did not answer docker info."
+      )
+    );
+  }
+  if (result.scripts.test === void 0) {
+    warnings.push(
+      warning(
+        "missing-test-script",
+        "warning",
+        "No test script",
+        "package.json does not define a test script."
+      )
+    );
+  }
+  if (result.scripts.build === void 0) {
+    warnings.push(
+      warning(
+        "missing-build-script",
+        "warning",
+        "No build script",
+        "package.json does not define a build script."
+      )
+    );
+  }
+  if (!result.license.exists) {
+    warnings.push(warning("missing-license", "info", "No LICENSE", "No LICENSE file was found."));
+  }
+  return warnings;
+}
+
+// src/cli/commands/doctor.ts
+function colorSeverity(severity) {
+  if (severity === "error") {
+    return pc.red("error");
+  }
+  if (severity === "warning") {
+    return pc.yellow("warning");
+  }
+  return pc.cyan("info");
+}
+async function doctorCommand(cwd = process.cwd()) {
+  const warnings = await runDoctor(cwd);
+  if (warnings.length === 0) {
+    console.log(pc.green("No health warnings found."));
+    return;
+  }
+  for (const item of warnings) {
+    console.log(`${colorSeverity(item.severity)} ${pc.bold(item.title)}`);
+    console.log(`  ${item.message}`);
+  }
+}
+
+// src/cli/commands/init.ts
+import { promises as fs10 } from "fs";
+import path10 from "path";
+import pc2 from "picocolors";
+async function initCommand(cwd = process.cwd()) {
+  const configPath = path10.join(cwd, CONFIG_FILE_NAME);
+  try {
+    await fs10.access(configPath);
+    console.log(pc2.yellow(`${CONFIG_FILE_NAME} already exists.`));
+    return;
+  } catch {
+    await fs10.writeFile(configPath, `${JSON.stringify(defaultConfig, null, 2)}
+`, "utf8");
+    console.log(pc2.green(`Created ${CONFIG_FILE_NAME}.`));
+  }
+}
+
+// src/cli/commands/run.ts
+import pc3 from "picocolors";
+
+// src/core/process/runner.ts
+import spawn2 from "cross-spawn";
+function getPackageRunCommand(packageManager, script) {
+  const manager = packageManager ?? "npm";
+  const args = ["run", script];
+  return {
+    command: manager,
+    args,
+    displayCommand: `${manager} ${args.join(" ")}`
+  };
+}
+async function resolvePackageRunCommand(options) {
+  const runCommand2 = getPackageRunCommand(options.packageManager, options.script);
+  const executable = await resolveExecutableOutsideRoot(options.cwd, runCommand2.command);
+  if (executable === null) {
+    return null;
+  }
+  return {
+    ...runCommand2,
+    command: executable
+  };
+}
+function getPackageInstallCommand(packageManager) {
+  const manager = packageManager ?? "npm";
+  if (manager === "npm") {
+    return {
+      command: manager,
+      args: ["ci"],
+      displayCommand: "npm ci"
+    };
+  }
+  if (manager === "pnpm") {
+    return {
+      command: manager,
+      args: ["install", "--frozen-lockfile"],
+      displayCommand: "pnpm install --frozen-lockfile"
+    };
+  }
+  if (manager === "yarn") {
+    return {
+      command: manager,
+      args: ["install", "--frozen-lockfile"],
+      displayCommand: "yarn install --frozen-lockfile"
+    };
+  }
+  return {
+    command: manager,
+    args: ["install"],
+    displayCommand: "bun install"
+  };
+}
+async function resolvePackageInstallCommand(options) {
+  const installCommand = getPackageInstallCommand(options.packageManager);
+  const executable = await resolveExecutableOutsideRoot(options.cwd, installCommand.command);
+  if (executable === null) {
+    return null;
+  }
+  return {
+    ...installCommand,
+    command: executable
+  };
+}
+async function runPackageScriptToTerminal(options) {
+  const runCommand2 = await resolvePackageRunCommand(options);
+  if (runCommand2 === null) {
+    return 1;
+  }
+  return await new Promise((resolve) => {
+    const child = spawn2(runCommand2.command, runCommand2.args, {
+      cwd: options.cwd,
+      stdio: "inherit",
+      windowsHide: true
+    });
+    child.on("error", () => {
+      resolve(1);
+    });
+    child.on("close", (code) => {
+      resolve(code ?? 1);
+    });
+  });
+}
+
+// src/cli/commands/run.ts
+async function runCommand(script, cwd = process.cwd()) {
+  const scan = await scanProject(cwd);
+  if (scan.packageJson === null) {
+    console.error(pc3.red("No package.json was found in this directory."));
+    process.exitCode = 1;
+    return;
+  }
+  if (scan.scripts[script] === void 0) {
+    console.error(pc3.red(`Script "${script}" was not found in package.json.`));
+    process.exitCode = 1;
+    return;
+  }
+  const exitCode = await runPackageScriptToTerminal({
+    cwd,
+    packageManager: scan.packageManager,
+    script
+  });
+  process.exitCode = exitCode;
+}
+
+// src/cli/commands/scan.ts
+import pc4 from "picocolors";
+function formatList(values) {
+  return values.length > 0 ? values.join(", ") : "none";
+}
+function printScanResult(scan) {
+  console.log(pc4.bold(`Project:   ${scan.projectName}`));
+  console.log(`Type:      ${scan.framework?.type ?? "Unknown"}`);
+  console.log(`Manager:   ${scan.packageManager ?? "unknown"}`);
+  console.log(`Scripts:   ${formatList(Object.keys(scan.scripts))}`);
+  console.log(`Git:       ${scan.git?.branch ?? "not detected"}`);
+  console.log(`README:    ${scan.readme.exists ? "found" : "missing"}`);
+  console.log(`LICENSE:   ${scan.license.exists ? "found" : "missing"}`);
+  if (scan.env !== null) {
+    console.log(`Env:       ${scan.env.hasLocal ? ".env found" : ".env missing"}`);
+  }
+  if (scan.ports.length > 0) {
+    const ports = scan.ports.map((port) => `${port.port}${port.inUse ? " in use" : " free"}`);
+    console.log(`Ports:     ${ports.join(", ")}`);
+  }
+  if (scan.docker !== null) {
+    console.log(
+      `Docker:    compose found (${formatList(scan.docker.services.map((service) => service.name))})`
+    );
+  }
+}
+async function scanCommand(cwd = process.cwd()) {
+  printScanResult(await scanProject(cwd));
+}
+
+// src/cli/commands/start.ts
+import pc5 from "picocolors";
+
+// src/server/index.ts
+import { promises as fs12 } from "fs";
+import path12 from "path";
+import { fileURLToPath } from "url";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import open2 from "open";
+
+// src/core/process/manager.ts
+import { EventEmitter } from "events";
+import spawn3 from "cross-spawn";
+var ProcessManager = class extends EventEmitter {
+  processes = /* @__PURE__ */ new Map();
+  logs = [];
+  cleanupInstalled = false;
+  start(options) {
+    const child = spawn3(options.command, options.args, {
+      cwd: options.cwd,
+      shell: options.shell ?? false,
+      windowsHide: true
+    });
+    const pid = String(child.pid ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`);
+    const record = {
+      child,
+      pid,
+      script: options.script,
+      command: options.displayCommand,
+      status: "running",
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      endedAt: null,
+      exitCode: null
+    };
+    this.processes.set(pid, record);
+    this.emitSystem(record, `Started ${options.displayCommand}`);
+    child.stdout?.on("data", (chunk) => {
+      this.emitLog(record, "stdout", chunk.toString());
+    });
+    child.stderr?.on("data", (chunk) => {
+      this.emitLog(record, "stderr", chunk.toString());
+    });
+    child.on("error", (error) => {
+      record.status = "failed";
+      record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.emitLog(record, "system", error.message);
+      this.emit("process", this.snapshot(record));
+    });
+    child.on("close", (code) => {
+      if (record.status === "stopped") {
+        record.exitCode = code;
+      } else {
+        record.status = code === 0 ? "exited" : "failed";
+        record.exitCode = code;
+      }
+      record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+      this.emitSystem(record, `Exited with code ${code ?? "unknown"}`);
+      this.emit("process", this.snapshot(record));
+    });
+    this.emit("process", this.snapshot(record));
+    return this.snapshot(record);
+  }
+  stop(pid) {
+    const record = this.processes.get(pid);
+    if (!record || record.status !== "running") {
+      return false;
+    }
+    record.status = "stopped";
+    record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+    record.child.kill();
+    this.emitSystem(record, "Stopped by DevSurface");
+    this.emit("process", this.snapshot(record));
+    return true;
+  }
+  list() {
+    return Array.from(this.processes.values()).map((record) => this.snapshot(record));
+  }
+  listLogs() {
+    return [...this.logs];
+  }
+  killAll() {
+    for (const record of this.processes.values()) {
+      if (record.status === "running") {
+        record.status = "stopped";
+        record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+        record.child.kill();
+      }
+    }
+  }
+  attachCleanupHandlers() {
+    if (this.cleanupInstalled) {
+      return;
+    }
+    this.cleanupInstalled = true;
+    process.once("exit", () => {
+      this.killAll();
+    });
+    process.once("SIGINT", () => {
+      this.killAll();
+      process.exit(130);
+    });
+  }
+  emitLog(record, stream, message) {
+    const event = {
+      pid: record.pid,
+      script: record.script,
+      stream,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.logs.push(event);
+    if (this.logs.length > 1e3) {
+      this.logs.splice(0, this.logs.length - 1e3);
+    }
+    this.emit("log", event);
+  }
+  emitSystem(record, message) {
+    this.emitLog(record, "system", message);
+  }
+  snapshot(record) {
+    return {
+      pid: record.pid,
+      script: record.script,
+      command: record.command,
+      status: record.status,
+      startedAt: record.startedAt,
+      endedAt: record.endedAt,
+      exitCode: record.exitCode
+    };
+  }
+};
+
+// src/server/routes/api.ts
+import { constants as constants2, existsSync } from "fs";
+import { promises as fs11 } from "fs";
+import path11 from "path";
+import spawn4 from "cross-spawn";
+import open from "open";
+
+// src/server/localAccess.ts
+var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
+function hostnameFromHostHeader(host) {
+  const trimmed = host.trim().toLowerCase();
+  if (trimmed.length === 0) {
+    return null;
+  }
+  if (trimmed.startsWith("[")) {
+    const end = trimmed.indexOf("]");
+    return end > 0 ? trimmed.slice(1, end) : null;
+  }
+  return trimmed.split(":")[0] ?? null;
+}
+function isAllowedLocalHostHeader(host) {
+  if (typeof host !== "string") {
+    return false;
+  }
+  const hostname = hostnameFromHostHeader(host);
+  return hostname !== null && LOCAL_HOSTNAMES.has(hostname);
+}
+function isAllowedLocalOrigin(origin) {
+  if (origin === null) {
+    return true;
+  }
+  try {
+    const url = new URL(origin);
+    return (url.protocol === "http:" || url.protocol === "https:") && LOCAL_HOSTNAMES.has(url.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+function isSameOrigin(requestUrl, origin) {
+  try {
+    return new URL(requestUrl).origin === new URL(origin).origin;
+  } catch {
+    return false;
+  }
+}
+
+// src/server/routes/api.ts
+function isWithinRoot4(root, target) {
+  const relative = path11.relative(path11.resolve(root), path11.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path11.isAbsolute(relative);
+}
+function isAllowedMutationOrigin(requestUrl, origin) {
+  if (origin === null) {
+    return true;
+  }
+  return isAllowedLocalOrigin(origin) && isSameOrigin(requestUrl, origin);
+}
+function isCrossSiteFetch(secFetchSite) {
+  return secFetchSite === "cross-site";
+}
+function hasMutationIntent(intent) {
+  return intent === "dashboard";
+}
+async function realPathWithinRoot(root, target) {
+  if (!isWithinRoot4(root, target)) {
+    return false;
+  }
+  try {
+    const [realRoot, realTarget] = await Promise.all([fs11.realpath(root), fs11.realpath(target)]);
+    return isWithinRoot4(realRoot, realTarget);
+  } catch {
+    return false;
+  }
+}
+async function writableDestinationWithinRoot(root, destination) {
+  if (!isWithinRoot4(root, destination)) {
+    return false;
+  }
+  try {
+    const [realRoot, realParent] = await Promise.all([
+      fs11.realpath(root),
+      fs11.realpath(path11.dirname(destination))
+    ]);
+    return isWithinRoot4(realRoot, realParent);
+  } catch {
+    return false;
+  }
+}
+async function copyFileExclusive(source, destination) {
+  const content = await fs11.readFile(source);
+  let handle2 = null;
+  try {
+    handle2 = await fs11.open(
+      destination,
+      constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY,
+      384
+    );
+    await handle2.writeFile(content);
+    return "copied";
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
+    if (code === "EEXIST") {
+      return "exists";
+    }
+    throw error;
+  } finally {
+    await handle2?.close();
+  }
+}
+function quotePowerShellString(value) {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+function quotePosixString(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function resolveCommandPromptExecutable() {
+  return process.env.ComSpec ?? "cmd.exe";
+}
+function findExecutable(command) {
+  if (path11.isAbsolute(command)) {
+    return existsSync(command) ? command : null;
+  }
+  const pathValue = process.env.PATH ?? "";
+  for (const directory of pathValue.split(path11.delimiter)) {
+    if (directory.length === 0) {
+      continue;
+    }
+    const candidate = path11.join(directory, command);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function launchDetached(command, args, root) {
+  const child = spawn4(command, args, {
+    cwd: root,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: process.platform === "win32"
+  });
+  child.on("error", () => void 0);
+  child.unref();
+  return true;
+}
+function openTerminalAt(root) {
+  if (process.platform === "win32") {
+    return launchDetached(
+      resolveCommandPromptExecutable(),
+      [
+        "/d",
+        "/c",
+        "start",
+        '""',
+        "/D",
+        root,
+        "powershell.exe",
+        "-NoExit",
+        "-NoLogo",
+        "-Command",
+        `Set-Location -LiteralPath ${quotePowerShellString(root)}`
+      ],
+      root
+    );
+  }
+  if (process.platform === "darwin") {
+    return launchDetached("open", ["-a", "Terminal", root], root);
+  }
+  const configuredTerminal = process.env.TERMINAL;
+  if (configuredTerminal !== void 0 && findExecutable(configuredTerminal) !== null) {
+    return launchDetached(configuredTerminal, [], root);
+  }
+  const linuxTerminals = [
+    { command: "x-terminal-emulator", args: [] },
+    { command: "gnome-terminal", args: ["--working-directory", root] },
+    { command: "konsole", args: ["--workdir", root] },
+    { command: "xfce4-terminal", args: ["--working-directory", root] },
+    {
+      command: "xterm",
+      args: [
+        "-e",
+        "sh",
+        "-lc",
+        `cd ${quotePosixString(root)} && exec ${quotePosixString(process.env.SHELL ?? "sh")}`
+      ]
+    }
+  ];
+  const terminal = linuxTerminals.find((candidate) => findExecutable(candidate.command) !== null);
+  if (terminal === void 0) {
+    return false;
+  }
+  return launchDetached(terminal.command, terminal.args, root);
+}
+function registerApiRoutes(app, options) {
+  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);
+    }
+    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;
+      if (!hasMutationIntent(intent) || isCrossSiteFetch(secFetchSite) || !isAllowedMutationOrigin(context.req.url, origin)) {
+        return context.json({ error: "Cross-origin mutation rejected." }, 403);
+      }
+    }
+    await next();
+  });
+  app.get("/api/project", async (context) => {
+    return context.json(await scanProject(options.projectRoot));
+  });
+  app.get("/api/health", async (context) => {
+    return context.json(await runDoctor(options.projectRoot));
+  });
+  app.get("/api/processes", (context) => {
+    return context.json(options.processManager.list());
+  });
+  app.post("/api/run/:script", async (context) => {
+    const script = decodeURIComponent(context.req.param("script"));
+    const scan = await scanProject(options.projectRoot);
+    const packageScript = scan.scripts[script];
+    if (packageScript === void 0) {
+      return context.json({ error: `Script "${script}" was not found.` }, 404);
+    }
+    const command = await resolvePackageRunCommand({
+      cwd: options.projectRoot,
+      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,
+      script,
+      command: command.command,
+      args: command.args,
+      displayCommand: command.displayCommand
+    });
+    return context.json({
+      ...processInfo,
+      packageScript
+    });
+  });
+  app.post("/api/install", async (context) => {
+    const scan = await scanProject(options.projectRoot);
+    const command = await resolvePackageInstallCommand({
+      cwd: options.projectRoot,
+      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,
+      script: "install",
+      command: command.command,
+      args: command.args,
+      displayCommand: command.displayCommand
+    });
+    return context.json(processInfo);
+  });
+  app.post("/api/commands/:name", async (context) => {
+    const name = decodeURIComponent(context.req.param("name"));
+    const scan = await scanProject(options.projectRoot);
+    const configuredCommand = scan.config?.config.commands?.[name] ?? null;
+    if (configuredCommand === null) {
+      return context.json({ error: `Configured command "${name}" was not found.` }, 404);
+    }
+    const processInfo = options.processManager.start({
+      cwd: options.projectRoot,
+      script: name,
+      command: configuredCommand,
+      args: [],
+      displayCommand: configuredCommand,
+      shell: true
+    });
+    return context.json({
+      ...processInfo,
+      configuredCommand
+    });
+  });
+  app.post("/api/open/folder", async (context) => {
+    await open(options.projectRoot);
+    return context.json({ opened: true, target: "folder" });
+  });
+  app.post("/api/open/package", async (context) => {
+    const packagePath = path11.join(options.projectRoot, "package.json");
+    if (!await realPathWithinRoot(options.projectRoot, packagePath)) {
+      return context.json({ error: "package.json was not found inside the project root." }, 404);
+    }
+    await open(packagePath);
+    return context.json({ opened: true, target: "package" });
+  });
+  app.post("/api/open/terminal", (context) => {
+    const opened = openTerminalAt(options.projectRoot);
+    return context.json({ opened, target: "terminal" }, opened ? 200 : 501);
+  });
+  app.post("/api/env/copy", async (context) => {
+    const scan = await scanProject(options.projectRoot);
+    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 ?? path11.join(options.projectRoot, scan.config?.config.env?.local ?? ".env");
+    if (!await realPathWithinRoot(options.projectRoot, examplePath) || !await writableDestinationWithinRoot(options.projectRoot, destination)) {
+      return context.json({ error: "Refusing to copy env files outside the project root." }, 400);
+    }
+    const copyResult = await copyFileExclusive(examplePath, destination);
+    if (copyResult === "exists") {
+      return context.json({ error: ".env already exists." }, 409);
+    }
+    return context.json({ copied: true });
+  });
+  app.delete("/api/run/:pid", (context) => {
+    const pid = decodeURIComponent(context.req.param("pid"));
+    const stopped = options.processManager.stop(pid);
+    return context.json({ stopped });
+  });
+}
+
+// src/server/routes/ws.ts
+import { WebSocket, WebSocketServer } from "ws";
+function isAllowedWebSocketRequest(request) {
+  const origin = request.headers.origin;
+  const host = request.headers.host;
+  const secFetchSite = request.headers["sec-fetch-site"];
+  if (typeof host !== "string" || !isAllowedLocalHostHeader(host)) {
+    return false;
+  }
+  if (secFetchSite === "cross-site") {
+    return false;
+  }
+  if (typeof origin !== "string") {
+    return true;
+  }
+  if (!isAllowedLocalOrigin(origin)) {
+    return false;
+  }
+  try {
+    return new URL(origin).host.toLowerCase() === host.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+function setupWebSocket(server, processManager) {
+  const wss = new WebSocketServer({
+    server,
+    path: "/ws",
+    verifyClient: (info) => isAllowedWebSocketRequest(info.req)
+  });
+  function broadcast(payload) {
+    const serialized = JSON.stringify(payload);
+    for (const client of wss.clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(serialized);
+      }
+    }
+  }
+  processManager.on("log", (event) => {
+    broadcast({ type: "log", event });
+  });
+  processManager.on("process", (processInfo) => {
+    broadcast({ type: "process", process: processInfo });
+  });
+  wss.on("connection", (socket) => {
+    socket.send(
+      JSON.stringify({
+        type: "hello",
+        processes: processManager.list(),
+        logs: processManager.listLogs()
+      })
+    );
+  });
+  return wss;
+}
+
+// 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 fileExists2(filePath) {
+  try {
+    await fs12.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findWebDistDir() {
+  const moduleDir = path12.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path12.join(moduleDir, "..", "web", "dist"),
+    path12.join(moduleDir, "..", "..", "src", "web", "dist"),
+    path12.join(moduleDir, "web", "dist")
+  ];
+  for (const candidate of candidates) {
+    if (await fileExists2(path12.join(candidate, "index.html"))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+async function createApp(options) {
+  const app = new Hono();
+  registerApiRoutes(app, options);
+  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 fs12.readFile(path12.join(webDistDir, "index.html"), "utf8");
+      return context.html(html);
+    });
+  } else {
+    app.get(
+      "*",
+      (context) => context.html(
+        "<!doctype html><title>DevSurface</title><main><h1>DevSurface</h1><p>Run npm run build:web to build the dashboard.</p></main>",
+        503
+      )
+    );
+  }
+  return app;
+}
+async function startDevSurfaceServer(options) {
+  assertLocalHost(HOST);
+  const port = options.port ?? DEFAULT_PORT;
+  const processManager = new ProcessManager();
+  processManager.attachCleanupHandlers();
+  const app = await createApp({
+    projectRoot: options.projectRoot,
+    processManager
+  });
+  const server = serve({
+    fetch: app.fetch,
+    port,
+    hostname: HOST
+  });
+  const wss = setupWebSocket(server, processManager);
+  const url = `http://${HOST}:${port}`;
+  if (options.openBrowser !== false) {
+    await open2(url);
+  }
+  return {
+    url,
+    port,
+    processManager,
+    close: async () => {
+      processManager.killAll();
+      await new Promise((resolve) => {
+        wss.close(() => resolve());
+      });
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+          } else {
+            resolve();
+          }
+        });
+      });
+    }
+  };
+}
+
+// src/cli/commands/start.ts
+async function startCommand(options) {
+  const cwd = options.cwd ?? process.cwd();
+  console.log(pc5.bold(`DevSurface v0.1.0`));
+  console.log("Scanning project...\n");
+  const scan = await scanProject(cwd);
+  printScanResult(scan);
+  const warnings = await runDoctor(cwd, scan);
+  if (warnings.length > 0) {
+    console.log("\nWarnings:");
+    for (const item of warnings) {
+      const marker = item.severity === "error" ? pc5.red("!") : pc5.yellow("!");
+      console.log(`  ${marker} ${item.title}`);
+    }
+  }
+  const server = await startDevSurfaceServer({
+    projectRoot: cwd,
+    port: options.port,
+    openBrowser: options.openBrowser
+  });
+  console.log(`
+Dashboard running at -> ${pc5.cyan(server.url)}`);
+}
+
+// src/cli/index.ts
+var program = new Command();
+function toPort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("Port must be an integer between 1 and 65535.");
+  }
+  return port;
+}
+function handle(command) {
+  command.catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+  });
+}
+program.name("devsurface").description("Turn any Node.js repository into a local developer control panel.").version("0.1.0").option("-p, --port <port>", "dashboard port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
+  handle(
+    startCommand({
+      cwd: process.cwd(),
+      port: options.port,
+      openBrowser: options.open
+    })
+  );
+});
+program.command("scan").description("Print detected project info.").action(() => {
+  handle(scanCommand(process.cwd()));
+});
+program.command("doctor").description("Print setup health warnings.").action(() => {
+  handle(doctorCommand(process.cwd()));
+});
+program.command("init").description("Create a starter devsurface.config.json.").action(() => {
+  handle(initCommand(process.cwd()));
+});
+program.command("run").argument("<script>", "package.json script to run").description("Run a package script and stream logs.").action((script) => {
+  handle(runCommand(script, process.cwd()));
+});
+await program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map