devsurface 0.2.0 → 0.3.0

package/dist/cli/index.js

@@ -10,6 +10,27 @@ import pc from "picocolors";
 import { promises as fs9 } from "fs";
 import path9 from "path";
 
+// src/core/documentation.ts
+function extractScriptReferences(content) {
+  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 content.matchAll(regex)) {
+      references.add(match[1]);
+    }
+  }
+  return Array.from(references);
+}
+
 // src/core/scanner/index.ts
 import { promises as fs8 } from "fs";
 import path8 from "path";
@@ -18,6 +39,16 @@ import path8 from "path";
 import { promises as fs } from "fs";
 import path from "path";
 
+// src/core/security/url.ts
+function isSafeHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 // src/core/config/defaults.ts
 var CONFIG_FILE_NAME = "devsurface.config.json";
 var defaultConfig = {
@@ -49,6 +80,10 @@ var defaultConfig = {
 
 // src/core/config/load.ts
 var MAX_CONFIGURED_PORTS = 32;
+function isWithinRoot(root, target) {
+  const relative = path.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -125,6 +160,14 @@ function validateConfig(raw) {
   if (raw.services !== void 0 && !isRecord(raw.services)) {
     warnings.push("services must be an object.");
   }
+  let docs;
+  if (typeof raw.docs === "string" && raw.docs.length > 0) {
+    if (isSafeHttpUrl(raw.docs)) {
+      docs = raw.docs;
+    } else {
+      warnings.push("docs must be an http or https URL.");
+    }
+  }
   return {
     config: {
       name: typeof raw.name === "string" ? raw.name : void 0,
@@ -134,7 +177,7 @@ function validateConfig(raw) {
       ports: toPorts(raw.ports, warnings),
       env,
       services,
-      docs: typeof raw.docs === "string" ? raw.docs : void 0
+      docs
     },
     warnings
   };
@@ -142,10 +185,17 @@ function validateConfig(raw) {
 async function loadConfig(root) {
   const configPath = path.join(root, CONFIG_FILE_NAME);
   try {
-    const content = await fs.readFile(configPath, "utf8");
+    const [realRoot, realConfigPath] = await Promise.all([
+      fs.realpath(root),
+      fs.realpath(configPath)
+    ]);
+    if (!isWithinRoot(realRoot, realConfigPath)) {
+      return null;
+    }
+    const content = await fs.readFile(realConfigPath, "utf8");
     const parsed = JSON.parse(content);
     const { config, warnings } = validateConfig(parsed);
-    return { path: configPath, config, warnings };
+    return { path: realConfigPath, config, warnings };
   } catch (error) {
     const code = typeof error === "object" && error !== null && "code" in error ? error.code : void 0;
     if (code === "ENOENT") {
@@ -162,7 +212,7 @@ async function loadConfig(root) {
   }
 }
 
-// src/core/scanner/docker.ts
+// src/core/docker/compose.ts
 import { promises as fs3 } from "fs";
 import os from "os";
 import path3 from "path";
@@ -173,7 +223,7 @@ import { parse as parseYaml } from "yaml";
 import { constants } from "fs";
 import { promises as fs2 } from "fs";
 import path2 from "path";
-function isWithinRoot(root, target) {
+function isWithinRoot2(root, target) {
   const resolvedRoot = path2.resolve(root);
   const resolvedTarget = path2.resolve(target);
   const relative = path2.relative(resolvedRoot, resolvedTarget);
@@ -193,7 +243,7 @@ function executableNames(command) {
   return extensions.map((extension) => `${command}${extension}`);
 }
 async function executableOutsideRoot(root, candidate) {
-  if (isWithinRoot(root, candidate)) {
+  if (isWithinRoot2(root, candidate)) {
     return null;
   }
   try {
@@ -201,7 +251,7 @@ async function executableOutsideRoot(root, candidate) {
       fs2.realpath(root),
       fs2.realpath(candidate)
     ]);
-    if (isWithinRoot(realRoot, realCandidate)) {
+    if (isWithinRoot2(realRoot, realCandidate)) {
       return null;
     }
     await fs2.access(realCandidate, constants.X_OK);
@@ -216,7 +266,7 @@ async function resolveExecutableOutsideRoot(root, command) {
   }
   for (const entry of pathEntries(process.env.PATH ?? "")) {
     const directory = path2.resolve(entry);
-    if (isWithinRoot(root, directory)) {
+    if (isWithinRoot2(root, directory)) {
       continue;
     }
     for (const executableName of executableNames(command)) {
@@ -229,50 +279,38 @@ async function resolveExecutableOutsideRoot(root, command) {
   return null;
 }
 
-// src/core/scanner/docker.ts
+// src/core/docker/compose.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) {
+var COMMAND_OUTPUT_LIMIT = 2e5;
+var ESC = String.fromCharCode(27);
+var ANSI_CSI_SEQUENCE = new RegExp(`${ESC}\\[[0-?]*[ -/]*[@-~]`, "g");
+var DockerOperationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DockerOperationError";
+  }
+  code;
+};
+function isWithinRoot3(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();
+  return candidates.find((candidate) => !isWithinRoot3(root, candidate)) ?? os.homedir();
+}
+function appendBounded(current, chunk, limit) {
+  const combined = current + chunk;
+  return combined.length <= limit ? combined : combined.slice(-limit);
 }
-async function runDockerCommand(root, args, timeoutMs = 2500) {
+var runDockerCommand = async (root, args, options = {}) => {
   const dockerExecutable = await resolveExecutableOutsideRoot(root, "docker");
   if (dockerExecutable === null) {
-    return { code: null, stdout: "", stderr: "" };
+    return { code: null, stdout: "", stderr: "", error: "not-found" };
   }
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const outputLimit = options.outputLimit ?? COMMAND_OUTPUT_LIMIT;
   return await new Promise((resolve) => {
     const child = spawn(dockerExecutable, args, {
       cwd: dockerCommandCwd(root),
@@ -281,36 +319,152 @@ async function runDockerCommand(root, args, timeoutMs = 2500) {
     let settled = false;
     let stdout = "";
     let stderr = "";
-    const timeout = setTimeout(() => {
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
       settled = true;
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    const timeout = setTimeout(() => {
       child.kill();
-      resolve({ code: null, stdout, stderr });
+      finish({ code: null, stdout, stderr, error: "timeout" });
     }, timeoutMs);
     child.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString();
+      stdout = appendBounded(stdout, chunk.toString(), outputLimit);
     });
     child.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString();
+      stderr = appendBounded(stderr, chunk.toString(), outputLimit);
     });
     child.on("error", () => {
-      clearTimeout(timeout);
-      if (!settled) {
-        settled = true;
-        resolve({ code: null, stdout, stderr });
-      }
+      finish({ code: null, stdout, stderr, error: "spawn" });
     });
     child.on("close", (code) => {
-      clearTimeout(timeout);
-      if (!settled) {
-        settled = true;
-        resolve({ code, stdout, stderr });
-      }
+      finish({ code, stdout, stderr, error: null });
     });
   });
+};
+async function findComposeFiles(root) {
+  const resolvedRoot = await fs3.realpath(root).catch(() => path3.resolve(root));
+  const matches = [];
+  for (const file of COMPOSE_FILES) {
+    const candidate = path3.join(root, file);
+    try {
+      const [stat, realCandidate] = await Promise.all([fs3.stat(candidate), fs3.realpath(candidate)]);
+      if (stat.isFile() && isWithinRoot3(resolvedRoot, realCandidate)) {
+        matches.push(realCandidate);
+      }
+    } catch {
+    }
+  }
+  return matches;
 }
-async function isDockerRunning(root) {
-  const result = await runDockerCommand(root, ["info"]);
-  return result.code === 0;
+async function serviceNamesFromFiles(composeFiles) {
+  const names = /* @__PURE__ */ new Set();
+  for (const composeFile of composeFiles) {
+    try {
+      const parsed = parseYaml(await fs3.readFile(composeFile, "utf8"));
+      if (typeof parsed !== "object" || parsed === null || !("services" in parsed) || typeof parsed.services !== "object" || parsed.services === null || Array.isArray(parsed.services)) {
+        continue;
+      }
+      for (const name of Object.keys(parsed.services)) {
+        if (name.length > 0) {
+          names.add(name);
+        }
+      }
+    } catch {
+    }
+  }
+  return Array.from(names);
+}
+function composeArgs(root, composeFiles, args) {
+  return [
+    "compose",
+    ...composeFiles.flatMap((composeFile) => ["-f", composeFile]),
+    "--project-directory",
+    root,
+    ...args
+  ];
+}
+function cleanMessage(value) {
+  return value.replace(ANSI_CSI_SEQUENCE, "").trim().slice(-1e3);
+}
+function resultMessage(result) {
+  return cleanMessage(result.stderr || result.stdout);
+}
+function daemonStatus(result, platform2) {
+  if (result.error === "not-found") {
+    return {
+      status: "not-installed",
+      running: false,
+      message: "Docker CLI was not found. Install Docker and refresh this page."
+    };
+  }
+  if (result.code === 0) {
+    return { status: "running", running: true, message: null };
+  }
+  if (platform2 === "win32" || platform2 === "darwin") {
+    return {
+      status: "stopped",
+      running: false,
+      message: "Docker is installed, but its engine is not responding. Start Docker Desktop and refresh."
+    };
+  }
+  const detail = resultMessage(result);
+  return {
+    status: result.error === "timeout" ? "unknown" : "stopped",
+    running: false,
+    message: detail ? `Docker is installed, but its daemon is not responding: ${detail}` : "Docker is installed, but its daemon is not responding. Start Docker and refresh."
+  };
+}
+function exitCodeFromRow(record) {
+  if (typeof record.ExitCode === "number") {
+    return record.ExitCode;
+  }
+  if (typeof record.ExitCode === "string" && /^\d+$/.test(record.ExitCode)) {
+    return Number(record.ExitCode);
+  }
+  if (typeof record.Status === "string") {
+    const match = /\bExited\s+\((\d+)\)/i.exec(record.Status);
+    if (match?.[1]) {
+      return Number(match[1]);
+    }
+  }
+  return null;
+}
+function serviceStatusFromRow(record) {
+  const state = typeof record.State === "string" ? record.State.toLowerCase() : "";
+  const exitCode = exitCodeFromRow(record);
+  if (state === "running") {
+    return "running";
+  }
+  if (exitCode !== null && exitCode > 0) {
+    return "error";
+  }
+  if (state === "created" || state === "exited" || state === "stopped") {
+    return "stopped";
+  }
+  if (state === "dead" || state === "restarting" || state === "paused") {
+    return "error";
+  }
+  return "unknown";
+}
+function addComposeStatusRow(statuses, row) {
+  if (typeof row !== "object" || row === null) {
+    return;
+  }
+  const record = row;
+  if (typeof record.Service !== "string") {
+    return;
+  }
+  const detail = typeof record.Status === "string" && record.Status.trim() ? record.Status.trim() : typeof record.State === "string" && record.State.trim() ? record.State.trim() : null;
+  statuses.set(record.Service, {
+    name: record.Service,
+    status: serviceStatusFromRow(record),
+    statusDetail: detail,
+    containerId: typeof record.ID === "string" && record.ID.length > 0 ? record.ID : null
+  });
 }
 function parseComposePs(output) {
   const statuses = /* @__PURE__ */ new Map();
@@ -320,82 +474,181 @@ function parseComposePs(output) {
   }
   try {
     const parsed = JSON.parse(compactOutput);
-    const rows2 = Array.isArray(parsed) ? parsed : [parsed];
-    for (const row of rows2) {
+    for (const row of Array.isArray(parsed) ? parsed : [parsed]) {
       addComposeStatusRow(statuses, row);
     }
     return statuses;
   } catch {
   }
-  const rows = compactOutput.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-  for (const row of rows) {
+  for (const line of compactOutput.split(/\r?\n/)) {
     try {
-      const parsed = JSON.parse(row);
-      addComposeStatusRow(statuses, parsed);
+      addComposeStatusRow(statuses, JSON.parse(line));
     } catch {
-      return statuses;
+      return /* @__PURE__ */ new Map();
     }
   }
   return statuses;
 }
-function addComposeStatusRow(statuses, row) {
-  if (typeof row !== "object" || row === null) {
-    return;
+function unknownServices(serviceNames) {
+  return serviceNames.map((name) => ({
+    name,
+    status: "unknown",
+    statusDetail: null,
+    containerId: null
+  }));
+}
+function commandFailureMessage(action, result) {
+  const detail = resultMessage(result);
+  return detail ? `Docker Compose ${action} failed: ${detail}` : `Docker Compose ${action} failed.`;
+}
+var DockerComposeController = class {
+  constructor(root, options = {}) {
+    this.root = root;
+    this.runner = options.runner ?? runDockerCommand;
+    this.platform = options.platform ?? process.platform;
+  }
+  root;
+  runner;
+  platform;
+  async definition() {
+    const composeFiles = await findComposeFiles(this.root);
+    if (composeFiles.length === 0) {
+      return null;
+    }
+    return {
+      composeFiles,
+      serviceNames: await serviceNamesFromFiles(composeFiles)
+    };
   }
-  const record = row;
-  if (typeof record.Service !== "string") {
-    return;
+  async requireService(service) {
+    const definition = await this.definition();
+    if (definition === null) {
+      throw new DockerOperationError("compose-not-found", "No Docker Compose file was found.");
+    }
+    if (!definition.serviceNames.includes(service)) {
+      throw new DockerOperationError(
+        "service-not-found",
+        `Docker Compose service "${service}" was not found.`
+      );
+    }
+    return definition;
   }
-  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 [];
+  async requireDaemon() {
+    const result = await this.runner(this.root, ["info"], { timeoutMs: 5e3 });
+    const daemon = daemonStatus(result, this.platform);
+    if (daemon.status === "not-installed") {
+      throw new DockerOperationError("docker-not-installed", daemon.message ?? "Docker not found.");
+    }
+    if (!daemon.running) {
+      throw new DockerOperationError(
+        "docker-not-running",
+        daemon.message ?? "Docker is not running."
+      );
+    }
   }
-  if (!dockerRunning) {
-    return serviceNames.map((service) => ({
-      name: service,
-      status: "unknown",
-      containerId: null
-    }));
+  async inspect() {
+    const definition = await this.definition();
+    if (definition === null) {
+      return null;
+    }
+    const infoResult = await this.runner(this.root, ["info"], { timeoutMs: 5e3 });
+    const daemon = daemonStatus(infoResult, this.platform);
+    if (!daemon.running) {
+      return {
+        composeFiles: definition.composeFiles,
+        services: unknownServices(definition.serviceNames),
+        dockerRunning: false,
+        daemonStatus: daemon.status,
+        message: daemon.message
+      };
+    }
+    const ps = await this.runner(
+      this.root,
+      composeArgs(this.root, definition.composeFiles, ["ps", "--all", "--format", "json"]),
+      { timeoutMs: 8e3 }
+    );
+    if (ps.code !== 0 || ps.error !== null) {
+      return {
+        composeFiles: definition.composeFiles,
+        services: definition.serviceNames.map((name) => ({
+          name,
+          status: "error",
+          statusDetail: null,
+          containerId: null
+        })),
+        dockerRunning: true,
+        daemonStatus: "running",
+        message: commandFailureMessage("status check", ps)
+      };
+    }
+    const statuses = parseComposePs(ps.stdout);
+    return {
+      composeFiles: definition.composeFiles,
+      services: definition.serviceNames.map(
+        (name) => statuses.get(name) ?? {
+          name,
+          status: "stopped",
+          statusDetail: null,
+          containerId: null
+        }
+      ),
+      dockerRunning: true,
+      daemonStatus: "running",
+      message: 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 action(service, action) {
+    const definition = await this.requireService(service);
+    await this.requireDaemon();
+    const composeCommand = action === "start" ? ["up", "-d", "--", service] : ["stop", "--", service];
+    const result = await this.runner(
+      this.root,
+      composeArgs(this.root, definition.composeFiles, composeCommand),
+      { timeoutMs: 6e4 }
+    );
+    if (result.code !== 0 || result.error !== null) {
+      throw new DockerOperationError("command-failed", commandFailureMessage(action, result));
     }
-  );
-}
-async function detectDocker(root) {
-  const composeFiles = await getComposeFiles(root);
-  if (composeFiles.length === 0) {
-    return null;
+    return {
+      service,
+      action,
+      output: cleanMessage(result.stdout || result.stderr)
+    };
   }
-  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
-  };
+  async start(service) {
+    return await this.action(service, "start");
+  }
+  async stop(service) {
+    return await this.action(service, "stop");
+  }
+  async logs(service) {
+    const definition = await this.requireService(service);
+    await this.requireDaemon();
+    const result = await this.runner(
+      this.root,
+      composeArgs(this.root, definition.composeFiles, [
+        "logs",
+        "--no-color",
+        "--tail",
+        "200",
+        "--",
+        service
+      ]),
+      { timeoutMs: 15e3, outputLimit: COMMAND_OUTPUT_LIMIT }
+    );
+    if (result.code !== 0 || result.error !== null) {
+      throw new DockerOperationError("command-failed", commandFailureMessage("logs", result));
+    }
+    return {
+      service,
+      logs: appendBounded("", `${result.stdout}${result.stderr}`, COMMAND_OUTPUT_LIMIT)
+    };
+  }
+};
+
+// src/core/scanner/docker.ts
+async function detectDocker(root) {
+  return await new DockerComposeController(root).inspect();
 }
 
 // src/core/scanner/env.ts
@@ -529,7 +782,7 @@ function detectFramework(packageJson) {
 // src/core/scanner/git.ts
 import { promises as fs5 } from "fs";
 import path5 from "path";
-function isWithinRoot3(root, target) {
+function isWithinRoot4(root, target) {
   const resolvedRoot = path5.resolve(root);
   const resolvedTarget = path5.resolve(target);
   const relative = path5.relative(resolvedRoot, resolvedTarget);
@@ -548,14 +801,14 @@ async function resolveGitDirectory(root) {
       if (match) {
         const gitDir = match[1].trim();
         const resolvedGitDir = path5.isAbsolute(gitDir) ? path5.resolve(gitDir) : path5.resolve(root, gitDir);
-        if (!isWithinRoot3(root, resolvedGitDir)) {
+        if (!isWithinRoot4(root, resolvedGitDir)) {
           return null;
         }
         const [realRoot, realGitDir] = await Promise.all([
           fs5.realpath(root),
           fs5.realpath(resolvedGitDir)
         ]);
-        return isWithinRoot3(realRoot, realGitDir) ? resolvedGitDir : null;
+        return isWithinRoot4(realRoot, realGitDir) ? resolvedGitDir : null;
       }
     }
   } catch {
@@ -613,7 +866,7 @@ async function detectPackageManager(root) {
 // src/core/scanner/packageJson.ts
 import { promises as fs7 } from "fs";
 import path7 from "path";
-function isWithinRoot4(root, target) {
+function isWithinRoot5(root, target) {
   const relative = path7.relative(root, target);
   return relative === "" || !relative.startsWith("..") && !path7.isAbsolute(relative);
 }
@@ -624,7 +877,7 @@ async function readPackageJson(root) {
       fs7.realpath(root),
       fs7.realpath(packageJsonPath)
     ]);
-    if (!isWithinRoot4(realRoot, realPackageJsonPath)) {
+    if (!isWithinRoot5(realRoot, realPackageJsonPath)) {
       return null;
     }
     const content = await fs7.readFile(realPackageJsonPath, "utf8");
@@ -727,13 +980,18 @@ function extractScripts(packageJson) {
 }
 
 // src/core/scanner/index.ts
+function isWithinRoot6(root, target) {
+  const relative = path8.relative(path8.resolve(root), path8.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path8.isAbsolute(relative);
+}
 async function findFirstFile(root, candidates) {
+  const resolvedRoot = await fs8.realpath(root).catch(() => path8.resolve(root));
   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 };
+      const [stat, realPath] = await Promise.all([fs8.stat(filePath), fs8.realpath(filePath)]);
+      if (stat.isFile() && isWithinRoot6(resolvedRoot, realPath)) {
+        return { path: realPath, exists: true };
       }
     } catch {
     }
@@ -744,8 +1002,9 @@ 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 resolvedRoot = await fs8.realpath(root).catch(() => path8.resolve(root));
+  const config = await loadConfig(resolvedRoot);
+  const packageJson = await readPackageJson(resolvedRoot);
   const scripts = extractScripts(packageJson) ?? {};
   const framework = detectFramework(packageJson);
   const portsToProbe = [
@@ -754,17 +1013,17 @@ async function scanProject(root = process.cwd()) {
     ...defaultPortsForFramework(framework)
   ];
   const [packageManager, env, docker, git, ports, readme, license] = await Promise.all([
-    detectPackageManager(root),
-    detectEnv(root, config?.config),
-    detectDocker(root),
-    detectGit(root),
+    detectPackageManager(resolvedRoot),
+    detectEnv(resolvedRoot, config?.config),
+    detectDocker(resolvedRoot),
+    detectGit(resolvedRoot),
     detectPorts(portsToProbe),
-    findFirstFile(root, ["README.md", "README"]),
-    findFirstFile(root, ["LICENSE", "LICENSE.md", "COPYING"])
+    findFirstFile(resolvedRoot, ["README.md", "README"]),
+    findFirstFile(resolvedRoot, ["LICENSE", "LICENSE.md", "COPYING"])
   ]);
   return {
-    root,
-    projectName: config?.config.name ?? packageJson?.data.name ?? path8.basename(root),
+    root: resolvedRoot,
+    projectName: config?.config.name ?? packageJson?.data.name ?? path8.basename(resolvedRoot),
     packageJson,
     packageManager: packageManager ?? (packageJson ? "npm" : null),
     scripts,
@@ -798,25 +1057,6 @@ async function readIfPresent2(filePath) {
     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 };
 }
@@ -888,7 +1128,7 @@ async function runDoctor(root = process.cwd(), scan) {
   } else {
     const readme = await readIfPresent2(result.readme.path);
     if (readme !== null) {
-      const references = extractReadmeScriptReferences(readme);
+      const references = extractScriptReferences(readme);
       const missingScripts = references.filter((script) => result.scripts[script] === void 0);
       if (missingScripts.length > 0) {
         warnings.push(
@@ -918,7 +1158,7 @@ async function runDoctor(root = process.cwd(), scan) {
         "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."
+        result.docker.message ?? "A compose file exists, but Docker is not available."
       )
     );
   }
@@ -942,18 +1182,15 @@ async function runDoctor(root = process.cwd(), scan) {
       )
     );
   }
-  if (!result.license.exists) {
-    warnings.push(warning("missing-license", "info", "No LICENSE", "No LICENSE file was found."));
-  }
   return warnings;
 }
 
-// src/cli/terminal.ts
-var ESC = String.fromCharCode(27);
+// src/core/security/text.ts
+var ESC2 = String.fromCharCode(27);
 var BEL = String.fromCharCode(7);
-var OSC_SEQUENCE = new RegExp(`${ESC}\\][\\s\\S]*?(?:${BEL}|${ESC}\\\\)`, "g");
-var CSI_SEQUENCE = new RegExp(`${ESC}\\[[0-?]*[ -/]*[@-~]`, "g");
-var ESCAPE_SEQUENCE = new RegExp(`${ESC}[@-Z\\\\-_]`, "g");
+var OSC_SEQUENCE = new RegExp(`${ESC2}\\][\\s\\S]*?(?:${BEL}|${ESC2}\\\\)`, "g");
+var CSI_SEQUENCE = new RegExp(`${ESC2}\\[[0-?]*[ -/]*[@-~]`, "g");
+var ESCAPE_SEQUENCE = new RegExp(`${ESC2}[@-Z\\\\-_]`, "g");
 function stripControlCharacters(value) {
   let result = "";
   for (const character of value) {
@@ -964,13 +1201,13 @@ function stripControlCharacters(value) {
   }
   return result;
 }
-function safeTerminalText(value) {
+function safeDisplayText(value) {
   return stripControlCharacters(
     String(value).replace(OSC_SEQUENCE, "").replace(CSI_SEQUENCE, "").replace(ESCAPE_SEQUENCE, "")
   );
 }
-function safeTerminalList(values) {
-  return values.length > 0 ? values.map((value) => safeTerminalText(value)).join(", ") : "none";
+function safeDisplayList(values) {
+  return values.length > 0 ? values.map((value) => safeDisplayText(value)).join(", ") : "none";
 }
 
 // src/cli/commands/doctor.ts
@@ -990,8 +1227,8 @@ async function doctorCommand(cwd = process.cwd()) {
     return;
   }
   for (const item of warnings) {
-    console.log(`${colorSeverity(item.severity)} ${pc.bold(safeTerminalText(item.title))}`);
-    console.log(`  ${safeTerminalText(item.message)}`);
+    console.log(`${colorSeverity(item.severity)} ${pc.bold(safeDisplayText(item.title))}`);
+    console.log(`  ${safeDisplayText(item.message)}`);
   }
 }
 
@@ -1017,6 +1254,14 @@ import pc3 from "picocolors";
 
 // src/core/process/runner.ts
 import spawn2 from "cross-spawn";
+
+// src/core/security/dangerousCommand.ts
+var DANGEROUS_COMMAND = /\b(rm\s+-rf|docker\s+volume\s+rm|drop\s+database|prisma\s+migrate\s+reset|git\s+clean\s+-fdx?)\b/i;
+function isDangerousCommand(command) {
+  return DANGEROUS_COMMAND.test(command);
+}
+
+// src/core/process/runner.ts
 function getPackageRunCommand(packageManager, script) {
   const manager = packageManager ?? "npm";
   const args = ["run", script];
@@ -1077,6 +1322,95 @@ async function resolvePackageInstallCommand(options) {
     command: executable
   };
 }
+function splitCommandLine(command) {
+  const tokens = [];
+  let current = "";
+  let quote = null;
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index] ?? "";
+    if (quote !== null) {
+      if (character === quote) {
+        quote = null;
+      } else if (character === "\\" && quote === '"') {
+        const next = command[index + 1];
+        if (next === '"' || next === "\\") {
+          index += 1;
+          current += next ?? "";
+        } else {
+          current += character;
+        }
+      } else {
+        current += character;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += character;
+  }
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+function containsShellMetacharacters(command) {
+  let quote = null;
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index] ?? "";
+    if (quote !== null) {
+      if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      continue;
+    }
+    if (character === "\n" || character === "\r") {
+      return true;
+    }
+    if (";|&<>".includes(character)) {
+      return true;
+    }
+    if (character === "`") {
+      return true;
+    }
+    if (character === "$" && (command[index + 1] === "(" || command[index + 1] === "{")) {
+      return true;
+    }
+  }
+  return false;
+}
+async function resolveConfiguredCommand(cwd, command) {
+  const trimmed = command.trim();
+  if (trimmed.length === 0 || containsShellMetacharacters(trimmed)) {
+    return null;
+  }
+  const tokens = splitCommandLine(trimmed);
+  if (tokens.length === 0) {
+    return null;
+  }
+  const [executableName, ...args] = tokens;
+  const executable = await resolveExecutableOutsideRoot(cwd, executableName);
+  if (executable === null) {
+    return null;
+  }
+  return {
+    command: executable,
+    args,
+    displayCommand: trimmed
+  };
+}
 async function runPackageScriptToTerminal(options) {
   const runCommand2 = await resolvePackageRunCommand(options);
   if (runCommand2 === null) {
@@ -1121,14 +1455,14 @@ async function runCommand(script, cwd = process.cwd()) {
 // src/cli/commands/scan.ts
 import pc4 from "picocolors";
 function formatList(values) {
-  return safeTerminalList(values);
+  return safeDisplayList(values);
 }
 function printScanResult(scan) {
-  console.log(pc4.bold(`Project:   ${safeTerminalText(scan.projectName)}`));
-  console.log(`Type:      ${safeTerminalText(scan.framework?.type ?? "Unknown")}`);
-  console.log(`Manager:   ${safeTerminalText(scan.packageManager ?? "unknown")}`);
+  console.log(pc4.bold(`Project:   ${safeDisplayText(scan.projectName)}`));
+  console.log(`Type:      ${safeDisplayText(scan.framework?.type ?? "Unknown")}`);
+  console.log(`Manager:   ${safeDisplayText(scan.packageManager ?? "unknown")}`);
   console.log(`Scripts:   ${formatList(Object.keys(scan.scripts))}`);
-  console.log(`Git:       ${safeTerminalText(scan.git?.branch ?? "not detected")}`);
+  console.log(`Git:       ${safeDisplayText(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) {
@@ -1152,17 +1486,532 @@ async function scanCommand(cwd = process.cwd()) {
 import pc5 from "picocolors";
 
 // src/server/index.ts
-import { promises as fs12 } from "fs";
-import path12 from "path";
-import { fileURLToPath } from "url";
+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";
-import open2 from "open";
+
+// node_modules/open/index.js
+import process7 from "process";
+import { Buffer as Buffer2 } from "buffer";
+import path11 from "path";
+import { fileURLToPath } from "url";
+import { promisify as promisify5 } from "util";
+import childProcess from "child_process";
+import fs15, { constants as fsConstants2 } from "fs/promises";
+
+// node_modules/wsl-utils/index.js
+import process3 from "process";
+import fs14, { constants as fsConstants } from "fs/promises";
+
+// node_modules/is-wsl/index.js
+import process2 from "process";
+import os2 from "os";
+import fs13 from "fs";
+
+// node_modules/is-inside-container/index.js
+import fs12 from "fs";
+
+// node_modules/is-docker/index.js
+import fs11 from "fs";
+var isDockerCached;
+function hasDockerEnv() {
+  try {
+    fs11.statSync("/.dockerenv");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function hasDockerCGroup() {
+  try {
+    return fs11.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+  } catch {
+    return false;
+  }
+}
+function isDocker() {
+  if (isDockerCached === void 0) {
+    isDockerCached = hasDockerEnv() || hasDockerCGroup();
+  }
+  return isDockerCached;
+}
+
+// node_modules/is-inside-container/index.js
+var cachedResult;
+var hasContainerEnv = () => {
+  try {
+    fs12.statSync("/run/.containerenv");
+    return true;
+  } catch {
+    return false;
+  }
+};
+function isInsideContainer() {
+  if (cachedResult === void 0) {
+    cachedResult = hasContainerEnv() || isDocker();
+  }
+  return cachedResult;
+}
+
+// node_modules/is-wsl/index.js
+var isWsl = () => {
+  if (process2.platform !== "linux") {
+    return false;
+  }
+  if (os2.release().toLowerCase().includes("microsoft")) {
+    if (isInsideContainer()) {
+      return false;
+    }
+    return true;
+  }
+  try {
+    if (fs13.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft")) {
+      return !isInsideContainer();
+    }
+  } catch {
+  }
+  if (fs13.existsSync("/proc/sys/fs/binfmt_misc/WSLInterop") || fs13.existsSync("/run/WSL")) {
+    return !isInsideContainer();
+  }
+  return false;
+};
+var is_wsl_default = process2.env.__IS_WSL_TEST__ ? isWsl : isWsl();
+
+// node_modules/wsl-utils/index.js
+var wslDrivesMountPoint = /* @__PURE__ */ (() => {
+  const defaultMountPoint = "/mnt/";
+  let mountPoint;
+  return async function() {
+    if (mountPoint) {
+      return mountPoint;
+    }
+    const configFilePath = "/etc/wsl.conf";
+    let isConfigFileExists = false;
+    try {
+      await fs14.access(configFilePath, fsConstants.F_OK);
+      isConfigFileExists = true;
+    } catch {
+    }
+    if (!isConfigFileExists) {
+      return defaultMountPoint;
+    }
+    const configContent = await fs14.readFile(configFilePath, { encoding: "utf8" });
+    const configMountPoint = /(?<!#.*)root\s*=\s*(?<mountPoint>.*)/g.exec(configContent);
+    if (!configMountPoint) {
+      return defaultMountPoint;
+    }
+    mountPoint = configMountPoint.groups.mountPoint.trim();
+    mountPoint = mountPoint.endsWith("/") ? mountPoint : `${mountPoint}/`;
+    return mountPoint;
+  };
+})();
+var powerShellPathFromWsl = async () => {
+  const mountPoint = await wslDrivesMountPoint();
+  return `${mountPoint}c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe`;
+};
+var powerShellPath = async () => {
+  if (is_wsl_default) {
+    return powerShellPathFromWsl();
+  }
+  return `${process3.env.SYSTEMROOT || process3.env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+};
+
+// node_modules/define-lazy-prop/index.js
+function defineLazyProperty(object, propertyName, valueGetter) {
+  const define = (value) => Object.defineProperty(object, propertyName, { value, enumerable: true, writable: true });
+  Object.defineProperty(object, propertyName, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      const result = valueGetter();
+      define(result);
+      return result;
+    },
+    set(value) {
+      define(value);
+    }
+  });
+  return object;
+}
+
+// node_modules/default-browser/index.js
+import { promisify as promisify4 } from "util";
+import process6 from "process";
+import { execFile as execFile4 } from "child_process";
+
+// node_modules/default-browser-id/index.js
+import { promisify } from "util";
+import process4 from "process";
+import { execFile } from "child_process";
+var execFileAsync = promisify(execFile);
+async function defaultBrowserId() {
+  if (process4.platform !== "darwin") {
+    throw new Error("macOS only");
+  }
+  const { stdout } = await execFileAsync("defaults", ["read", "com.apple.LaunchServices/com.apple.launchservices.secure", "LSHandlers"]);
+  const match = /LSHandlerRoleAll = "(?!-)(?<id>[^"]+?)";\s+?LSHandlerURLScheme = (?:http|https);/.exec(stdout);
+  const browserId = match?.groups.id ?? "com.apple.Safari";
+  if (browserId === "com.apple.safari") {
+    return "com.apple.Safari";
+  }
+  return browserId;
+}
+
+// node_modules/run-applescript/index.js
+import process5 from "process";
+import { promisify as promisify2 } from "util";
+import { execFile as execFile2, execFileSync } from "child_process";
+var execFileAsync2 = promisify2(execFile2);
+async function runAppleScript(script, { humanReadableOutput = true, signal } = {}) {
+  if (process5.platform !== "darwin") {
+    throw new Error("macOS only");
+  }
+  const outputArguments = humanReadableOutput ? [] : ["-ss"];
+  const execOptions = {};
+  if (signal) {
+    execOptions.signal = signal;
+  }
+  const { stdout } = await execFileAsync2("osascript", ["-e", script, outputArguments], execOptions);
+  return stdout.trim();
+}
+
+// node_modules/bundle-name/index.js
+async function bundleName(bundleId) {
+  return runAppleScript(`tell application "Finder" to set app_path to application file id "${bundleId}" as string
+tell application "System Events" to get value of property list item "CFBundleName" of property list file (app_path & ":Contents:Info.plist")`);
+}
+
+// node_modules/default-browser/windows.js
+import { promisify as promisify3 } from "util";
+import { execFile as execFile3 } from "child_process";
+var execFileAsync3 = promisify3(execFile3);
+var windowsBrowserProgIds = {
+  MSEdgeHTM: { name: "Edge", id: "com.microsoft.edge" },
+  // The missing `L` is correct.
+  MSEdgeBHTML: { name: "Edge Beta", id: "com.microsoft.edge.beta" },
+  MSEdgeDHTML: { name: "Edge Dev", id: "com.microsoft.edge.dev" },
+  AppXq0fevzme2pys62n3e0fbqa7peapykr8v: { name: "Edge", id: "com.microsoft.edge.old" },
+  ChromeHTML: { name: "Chrome", id: "com.google.chrome" },
+  ChromeBHTML: { name: "Chrome Beta", id: "com.google.chrome.beta" },
+  ChromeDHTML: { name: "Chrome Dev", id: "com.google.chrome.dev" },
+  ChromiumHTM: { name: "Chromium", id: "org.chromium.Chromium" },
+  BraveHTML: { name: "Brave", id: "com.brave.Browser" },
+  BraveBHTML: { name: "Brave Beta", id: "com.brave.Browser.beta" },
+  BraveDHTML: { name: "Brave Dev", id: "com.brave.Browser.dev" },
+  BraveSSHTM: { name: "Brave Nightly", id: "com.brave.Browser.nightly" },
+  FirefoxURL: { name: "Firefox", id: "org.mozilla.firefox" },
+  OperaStable: { name: "Opera", id: "com.operasoftware.Opera" },
+  VivaldiHTM: { name: "Vivaldi", id: "com.vivaldi.Vivaldi" },
+  "IE.HTTP": { name: "Internet Explorer", id: "com.microsoft.ie" }
+};
+var _windowsBrowserProgIdMap = new Map(Object.entries(windowsBrowserProgIds));
+var UnknownBrowserError = class extends Error {
+};
+async function defaultBrowser(_execFileAsync = execFileAsync3) {
+  const { stdout } = await _execFileAsync("reg", [
+    "QUERY",
+    " HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\Shell\\Associations\\UrlAssociations\\http\\UserChoice",
+    "/v",
+    "ProgId"
+  ]);
+  const match = /ProgId\s*REG_SZ\s*(?<id>\S+)/.exec(stdout);
+  if (!match) {
+    throw new UnknownBrowserError(`Cannot find Windows browser in stdout: ${JSON.stringify(stdout)}`);
+  }
+  const { id } = match.groups;
+  const dotIndex = id.lastIndexOf(".");
+  const hyphenIndex = id.lastIndexOf("-");
+  const baseIdByDot = dotIndex === -1 ? void 0 : id.slice(0, dotIndex);
+  const baseIdByHyphen = hyphenIndex === -1 ? void 0 : id.slice(0, hyphenIndex);
+  return windowsBrowserProgIds[id] ?? windowsBrowserProgIds[baseIdByDot] ?? windowsBrowserProgIds[baseIdByHyphen] ?? { name: id, id };
+}
+
+// node_modules/default-browser/index.js
+var execFileAsync4 = promisify4(execFile4);
+var titleize = (string) => string.toLowerCase().replaceAll(/(?:^|\s|-)\S/g, (x) => x.toUpperCase());
+async function defaultBrowser2() {
+  if (process6.platform === "darwin") {
+    const id = await defaultBrowserId();
+    const name = await bundleName(id);
+    return { name, id };
+  }
+  if (process6.platform === "linux") {
+    const { stdout } = await execFileAsync4("xdg-mime", ["query", "default", "x-scheme-handler/http"]);
+    const id = stdout.trim();
+    const name = titleize(id.replace(/.desktop$/, "").replace("-", " "));
+    return { name, id };
+  }
+  if (process6.platform === "win32") {
+    return defaultBrowser();
+  }
+  throw new Error("Only macOS, Linux, and Windows are supported");
+}
+
+// node_modules/open/index.js
+var execFile5 = promisify5(childProcess.execFile);
+var __dirname = path11.dirname(fileURLToPath(import.meta.url));
+var localXdgOpenPath = path11.join(__dirname, "xdg-open");
+var { platform, arch } = process7;
+async function getWindowsDefaultBrowserFromWsl() {
+  const powershellPath = await powerShellPath();
+  const rawCommand = String.raw`(Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\http\UserChoice").ProgId`;
+  const encodedCommand = Buffer2.from(rawCommand, "utf16le").toString("base64");
+  const { stdout } = await execFile5(
+    powershellPath,
+    [
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-EncodedCommand",
+      encodedCommand
+    ],
+    { encoding: "utf8" }
+  );
+  const progId = stdout.trim();
+  const browserMap = {
+    ChromeHTML: "com.google.chrome",
+    BraveHTML: "com.brave.Browser",
+    MSEdgeHTM: "com.microsoft.edge",
+    FirefoxURL: "org.mozilla.firefox"
+  };
+  return browserMap[progId] ? { id: browserMap[progId] } : {};
+}
+var pTryEach = async (array, mapper) => {
+  let latestError;
+  for (const item of array) {
+    try {
+      return await mapper(item);
+    } catch (error) {
+      latestError = error;
+    }
+  }
+  throw latestError;
+};
+var baseOpen = async (options) => {
+  options = {
+    wait: false,
+    background: false,
+    newInstance: false,
+    allowNonzeroExitCode: false,
+    ...options
+  };
+  if (Array.isArray(options.app)) {
+    return pTryEach(options.app, (singleApp) => baseOpen({
+      ...options,
+      app: singleApp
+    }));
+  }
+  let { name: app, arguments: appArguments = [] } = options.app ?? {};
+  appArguments = [...appArguments];
+  if (Array.isArray(app)) {
+    return pTryEach(app, (appName) => baseOpen({
+      ...options,
+      app: {
+        name: appName,
+        arguments: appArguments
+      }
+    }));
+  }
+  if (app === "browser" || app === "browserPrivate") {
+    const ids = {
+      "com.google.chrome": "chrome",
+      "google-chrome.desktop": "chrome",
+      "com.brave.Browser": "brave",
+      "org.mozilla.firefox": "firefox",
+      "firefox.desktop": "firefox",
+      "com.microsoft.msedge": "edge",
+      "com.microsoft.edge": "edge",
+      "com.microsoft.edgemac": "edge",
+      "microsoft-edge.desktop": "edge"
+    };
+    const flags = {
+      chrome: "--incognito",
+      brave: "--incognito",
+      firefox: "--private-window",
+      edge: "--inPrivate"
+    };
+    const browser = is_wsl_default ? await getWindowsDefaultBrowserFromWsl() : await defaultBrowser2();
+    if (browser.id in ids) {
+      const browserName = ids[browser.id];
+      if (app === "browserPrivate") {
+        appArguments.push(flags[browserName]);
+      }
+      return baseOpen({
+        ...options,
+        app: {
+          name: apps[browserName],
+          arguments: appArguments
+        }
+      });
+    }
+    throw new Error(`${browser.name} is not supported as a default browser`);
+  }
+  let command;
+  const cliArguments = [];
+  const childProcessOptions = {};
+  if (platform === "darwin") {
+    command = "open";
+    if (options.wait) {
+      cliArguments.push("--wait-apps");
+    }
+    if (options.background) {
+      cliArguments.push("--background");
+    }
+    if (options.newInstance) {
+      cliArguments.push("--new");
+    }
+    if (app) {
+      cliArguments.push("-a", app);
+    }
+  } else if (platform === "win32" || is_wsl_default && !isInsideContainer() && !app) {
+    command = await powerShellPath();
+    cliArguments.push(
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-EncodedCommand"
+    );
+    if (!is_wsl_default) {
+      childProcessOptions.windowsVerbatimArguments = true;
+    }
+    const encodedArguments = ["Start"];
+    if (options.wait) {
+      encodedArguments.push("-Wait");
+    }
+    if (app) {
+      encodedArguments.push(`"\`"${app}\`""`);
+      if (options.target) {
+        appArguments.push(options.target);
+      }
+    } else if (options.target) {
+      encodedArguments.push(`"${options.target}"`);
+    }
+    if (appArguments.length > 0) {
+      appArguments = appArguments.map((argument) => `"\`"${argument}\`""`);
+      encodedArguments.push("-ArgumentList", appArguments.join(","));
+    }
+    options.target = Buffer2.from(encodedArguments.join(" "), "utf16le").toString("base64");
+  } else {
+    if (app) {
+      command = app;
+    } else {
+      const isBundled = !__dirname || __dirname === "/";
+      let exeLocalXdgOpen = false;
+      try {
+        await fs15.access(localXdgOpenPath, fsConstants2.X_OK);
+        exeLocalXdgOpen = true;
+      } catch {
+      }
+      const useSystemXdgOpen = process7.versions.electron ?? (platform === "android" || isBundled || !exeLocalXdgOpen);
+      command = useSystemXdgOpen ? "xdg-open" : localXdgOpenPath;
+    }
+    if (appArguments.length > 0) {
+      cliArguments.push(...appArguments);
+    }
+    if (!options.wait) {
+      childProcessOptions.stdio = "ignore";
+      childProcessOptions.detached = true;
+    }
+  }
+  if (platform === "darwin" && appArguments.length > 0) {
+    cliArguments.push("--args", ...appArguments);
+  }
+  if (options.target) {
+    cliArguments.push(options.target);
+  }
+  const subprocess = childProcess.spawn(command, cliArguments, childProcessOptions);
+  if (options.wait) {
+    return new Promise((resolve, reject) => {
+      subprocess.once("error", reject);
+      subprocess.once("close", (exitCode) => {
+        if (!options.allowNonzeroExitCode && exitCode > 0) {
+          reject(new Error(`Exited with code ${exitCode}`));
+          return;
+        }
+        resolve(subprocess);
+      });
+    });
+  }
+  subprocess.unref();
+  return subprocess;
+};
+var open = (target, options) => {
+  if (typeof target !== "string") {
+    throw new TypeError("Expected a `target`");
+  }
+  return baseOpen({
+    ...options,
+    target
+  });
+};
+function detectArchBinary(binary) {
+  if (typeof binary === "string" || Array.isArray(binary)) {
+    return binary;
+  }
+  const { [arch]: archBinary } = binary;
+  if (!archBinary) {
+    throw new Error(`${arch} is not supported`);
+  }
+  return archBinary;
+}
+function detectPlatformBinary({ [platform]: platformBinary }, { wsl }) {
+  if (wsl && is_wsl_default) {
+    return detectArchBinary(wsl);
+  }
+  if (!platformBinary) {
+    throw new Error(`${platform} is not supported`);
+  }
+  return detectArchBinary(platformBinary);
+}
+var apps = {};
+defineLazyProperty(apps, "chrome", () => detectPlatformBinary({
+  darwin: "google chrome",
+  win32: "chrome",
+  linux: ["google-chrome", "google-chrome-stable", "chromium"]
+}, {
+  wsl: {
+    ia32: "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+    x64: ["/mnt/c/Program Files/Google/Chrome/Application/chrome.exe", "/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe"]
+  }
+}));
+defineLazyProperty(apps, "brave", () => detectPlatformBinary({
+  darwin: "brave browser",
+  win32: "brave",
+  linux: ["brave-browser", "brave"]
+}, {
+  wsl: {
+    ia32: "/mnt/c/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe",
+    x64: ["/mnt/c/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe", "/mnt/c/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe"]
+  }
+}));
+defineLazyProperty(apps, "firefox", () => detectPlatformBinary({
+  darwin: "firefox",
+  win32: String.raw`C:\Program Files\Mozilla Firefox\firefox.exe`,
+  linux: "firefox"
+}, {
+  wsl: "/mnt/c/Program Files/Mozilla Firefox/firefox.exe"
+}));
+defineLazyProperty(apps, "edge", () => detectPlatformBinary({
+  darwin: "microsoft edge",
+  win32: "msedge",
+  linux: ["microsoft-edge", "microsoft-edge-dev"]
+}, {
+  wsl: "/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
+}));
+defineLazyProperty(apps, "browser", () => "browser");
+defineLazyProperty(apps, "browserPrivate", () => "browserPrivate");
+var open_default = open;
 
 // src/core/process/manager.ts
 import { EventEmitter } from "events";
 import spawn3 from "cross-spawn";
+var LOG_MESSAGE_LIMIT = 16384;
+var LOG_ENTRY_LIMIT = 1e3;
 function killChildProcessTree(child) {
   if (child.pid === void 0) {
     child.kill();
@@ -1187,7 +2036,7 @@ var ProcessManager = class extends EventEmitter {
   start(options) {
     const child = spawn3(options.command, options.args, {
       cwd: options.cwd,
-      shell: options.shell ?? false,
+      shell: false,
       windowsHide: true
     });
     const pid = String(child.pid ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`);
@@ -1270,16 +2119,17 @@ var ProcessManager = class extends EventEmitter {
     });
   }
   emitLog(record, stream, message) {
+    const boundedMessage = message.length <= LOG_MESSAGE_LIMIT ? message : message.slice(-LOG_MESSAGE_LIMIT);
     const event = {
       pid: record.pid,
       script: record.script,
       stream,
-      message,
+      message: boundedMessage,
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
     };
     this.logs.push(event);
-    if (this.logs.length > 1e3) {
-      this.logs.splice(0, this.logs.length - 1e3);
+    if (this.logs.length > LOG_ENTRY_LIMIT) {
+      this.logs.splice(0, this.logs.length - LOG_ENTRY_LIMIT);
     }
     this.emit("log", event);
   }
@@ -1301,10 +2151,9 @@ var ProcessManager = class extends EventEmitter {
 
 // src/server/routes/api.ts
 import { constants as constants2, existsSync } from "fs";
-import { promises as fs11 } from "fs";
-import path11 from "path";
+import { promises as fs16 } from "fs";
+import path12 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"]);
@@ -1345,10 +2194,30 @@ function isSameOrigin(requestUrl, origin) {
   }
 }
 
+// src/server/mutationToken.ts
+import { randomBytes, timingSafeEqual } from "crypto";
+function createMutationToken() {
+  return randomBytes(32).toString("hex");
+}
+function hasValidMutationToken(provided, expected) {
+  if (typeof provided !== "string" || provided.length === 0) {
+    return false;
+  }
+  if (provided.length !== expected.length) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(provided, "utf8"), Buffer.from(expected, "utf8"));
+}
+
+// src/server/terminal.ts
+function isAllowedTerminalCommand(command) {
+  return /^[A-Za-z0-9._+-]+$/.test(command);
+}
+
 // src/server/routes/api.ts
-function isWithinRoot5(root, target) {
-  const relative = path11.relative(path11.resolve(root), path11.resolve(target));
-  return relative === "" || !relative.startsWith("..") && !path11.isAbsolute(relative);
+function isWithinRoot7(root, target) {
+  const relative = path12.relative(path12.resolve(root), path12.resolve(target));
+  return relative === "" || !relative.startsWith("..") && !path12.isAbsolute(relative);
 }
 function isAllowedMutationOrigin(requestUrl, origin) {
   if (origin === null) {
@@ -1363,35 +2232,35 @@ function hasMutationIntent(intent) {
   return intent === "dashboard";
 }
 async function realPathWithinRoot(root, target) {
-  if (!isWithinRoot5(root, target)) {
+  if (!isWithinRoot7(root, target)) {
     return false;
   }
   try {
-    const [realRoot, realTarget] = await Promise.all([fs11.realpath(root), fs11.realpath(target)]);
-    return isWithinRoot5(realRoot, realTarget);
+    const [realRoot, realTarget] = await Promise.all([fs16.realpath(root), fs16.realpath(target)]);
+    return isWithinRoot7(realRoot, realTarget);
   } catch {
     return false;
   }
 }
 async function writableDestinationWithinRoot(root, destination) {
-  if (!isWithinRoot5(root, destination)) {
+  if (!isWithinRoot7(root, destination)) {
     return false;
   }
   try {
     const [realRoot, realParent] = await Promise.all([
-      fs11.realpath(root),
-      fs11.realpath(path11.dirname(destination))
+      fs16.realpath(root),
+      fs16.realpath(path12.dirname(destination))
     ]);
-    return isWithinRoot5(realRoot, realParent);
+    return isWithinRoot7(realRoot, realParent);
   } catch {
     return false;
   }
 }
 async function copyFileExclusive(source, destination) {
-  const content = await fs11.readFile(source);
+  const content = await fs16.readFile(source);
   let handle2 = null;
   try {
-    handle2 = await fs11.open(
+    handle2 = await fs16.open(
       destination,
       constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY,
       384
@@ -1418,15 +2287,15 @@ function resolveCommandPromptExecutable() {
   return process.env.ComSpec ?? "cmd.exe";
 }
 function findExecutable(command) {
-  if (path11.isAbsolute(command)) {
+  if (path12.isAbsolute(command)) {
     return existsSync(command) ? command : null;
   }
   const pathValue = process.env.PATH ?? "";
-  for (const directory of pathValue.split(path11.delimiter)) {
+  for (const directory of pathValue.split(path12.delimiter)) {
     if (directory.length === 0) {
       continue;
     }
-    const candidate = path11.join(directory, command);
+    const candidate = path12.join(directory, command);
     if (existsSync(candidate)) {
       return candidate;
     }
@@ -1467,8 +2336,8 @@ function openTerminalAt(root) {
   if (process.platform === "darwin") {
     return launchDetached("open", ["-a", "Terminal", root], root);
   }
-  const configuredTerminal = process.env.TERMINAL;
-  if (configuredTerminal !== void 0 && findExecutable(configuredTerminal) !== null) {
+  const configuredTerminal = process.env.TERMINAL?.trim();
+  if (configuredTerminal !== void 0 && configuredTerminal.length > 0 && isAllowedTerminalCommand(configuredTerminal) && findExecutable(configuredTerminal) !== null) {
     return launchDetached(configuredTerminal, [], root);
   }
   const linuxTerminals = [
@@ -1493,6 +2362,10 @@ 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)) {
@@ -1502,7 +2375,8 @@ function registerApiRoutes(app, options) {
       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)) {
+      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);
       }
     }
@@ -1520,6 +2394,57 @@ function registerApiRoutes(app, options) {
   app.get("/api/logs", (context) => {
     return context.json(options.processManager.listLogs());
   });
+  app.get("/api/docker/:service/logs", async (context) => {
+    const service = decodeURIComponent(context.req.param("service"));
+    try {
+      return context.json(await 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;
+    }
+  });
+  app.post("/api/docker/:service/start", async (context) => {
+    const service = decodeURIComponent(context.req.param("service"));
+    try {
+      return context.json(await 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;
+    }
+  });
+  app.post("/api/docker/:service/stop", async (context) => {
+    const service = decodeURIComponent(context.req.param("service"));
+    try {
+      return context.json(await 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;
+    }
+  });
   app.post("/api/run/:script", async (context) => {
     const script = decodeURIComponent(context.req.param("script"));
     const scan = await scanProject(options.projectRoot);
@@ -1527,6 +2452,9 @@ function registerApiRoutes(app, options) {
     if (packageScript === void 0) {
       return context.json({ error: `Script "${script}" was not found.` }, 404);
     }
+    if (isDangerousCommand(packageScript)) {
+      return context.json({ error: "Refusing to run dangerous script." }, 403);
+    }
     const command = await resolvePackageRunCommand({
       cwd: options.projectRoot,
       packageManager: scan.packageManager,
@@ -1572,13 +2500,24 @@ function registerApiRoutes(app, options) {
     if (configuredCommand === null) {
       return context.json({ error: `Configured command "${name}" was not found.` }, 404);
     }
+    if (isDangerousCommand(configuredCommand)) {
+      return context.json({ error: "Refusing to run dangerous command." }, 403);
+    }
+    const resolvedCommand = await resolveConfiguredCommand(options.projectRoot, configuredCommand);
+    if (resolvedCommand === null) {
+      return context.json(
+        {
+          error: "Configured command uses unsupported shell syntax. Use a simple executable with arguments, or move complex logic into a package.json script."
+        },
+        400
+      );
+    }
     const processInfo = options.processManager.start({
       cwd: options.projectRoot,
       script: name,
-      command: configuredCommand,
-      args: [],
-      displayCommand: configuredCommand,
-      shell: true
+      command: resolvedCommand.command,
+      args: resolvedCommand.args,
+      displayCommand: resolvedCommand.displayCommand
     });
     return context.json({
       ...processInfo,
@@ -1586,15 +2525,15 @@ function registerApiRoutes(app, options) {
     });
   });
   app.post("/api/open/folder", async (context) => {
-    await open(options.projectRoot);
+    await open_default(options.projectRoot);
     return context.json({ opened: true, target: "folder" });
   });
   app.post("/api/open/package", async (context) => {
-    const packagePath = path11.join(options.projectRoot, "package.json");
+    const packagePath = path12.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);
+    await open_default(packagePath);
     return context.json({ opened: true, target: "package" });
   });
   app.post("/api/open/terminal", (context) => {
@@ -1608,7 +2547,7 @@ function registerApiRoutes(app, options) {
     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");
+    const destination = localPath ?? path12.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);
     }
@@ -1689,23 +2628,23 @@ function assertLocalHost(host) {
     throw new Error("DevSurface must bind only to 127.0.0.1.");
   }
 }
-async function fileExists2(filePath) {
+async function fileExists(filePath) {
   try {
-    await fs12.access(filePath);
+    await fs17.access(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function findWebDistDir() {
-  const moduleDir = path12.dirname(fileURLToPath(import.meta.url));
+  const moduleDir = path13.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    path12.join(moduleDir, "..", "web", "dist"),
-    path12.join(moduleDir, "..", "..", "src", "web", "dist"),
-    path12.join(moduleDir, "web", "dist")
+    path13.join(moduleDir, "..", "web", "dist"),
+    path13.join(moduleDir, "..", "..", "src", "web", "dist"),
+    path13.join(moduleDir, "web", "dist")
   ];
   for (const candidate of candidates) {
-    if (await fileExists2(path12.join(candidate, "index.html"))) {
+    if (await fileExists(path13.join(candidate, "index.html"))) {
       return candidate;
     }
   }
@@ -1777,13 +2716,16 @@ async function closeHttpServer(server) {
 }
 async function createApp(options) {
   const app = new Hono();
-  registerApiRoutes(app, options);
+  registerApiRoutes(app, {
+    ...options,
+    mutationToken: options.mutationToken ?? createMutationToken()
+  });
   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");
+      const html = await fs17.readFile(path13.join(webDistDir, "index.html"), "utf8");
       return context.html(html);
     });
   } else {
@@ -1815,7 +2757,7 @@ async function startDevSurfaceServer(options) {
   processManager.attachCleanupHandlers();
   const url = `http://${HOST}:${port}`;
   if (options.openBrowser !== false) {
-    await open2(url);
+    await open_default(url);
   }
   return {
     url,
@@ -1829,10 +2771,13 @@ async function startDevSurfaceServer(options) {
   };
 }
 
+// src/version.ts
+var DEV_SURFACE_VERSION = "0.3.0";
+
 // src/cli/commands/start.ts
 async function startCommand(options) {
   const cwd = options.cwd ?? process.cwd();
-  console.log(pc5.bold(`DevSurface v0.2.0`));
+  console.log(pc5.bold(`DevSurface v${DEV_SURFACE_VERSION}`));
   console.log("Scanning project...\n");
   const scan = await scanProject(cwd);
   printScanResult(scan);
@@ -1869,7 +2814,7 @@ function handle(command) {
     process.exitCode = 1;
   });
 }
-program.name("devsurface").description("Turn any Node.js repository into a local developer control panel.").version("0.2.0").option("-p, --port <port>", "dashboard port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
+program.name("devsurface").description("Turn any Node.js repository into a local developer control panel.").version(DEV_SURFACE_VERSION).option("-p, --port <port>", "dashboard port", toPort, 4567).option("--no-open", "do not open the browser automatically").action((options) => {
   handle(
     startCommand({
       cwd: process.cwd(),