devsurface 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+- Added retained process logs through `GET /api/logs` so the dashboard can recover session output without relying only on WebSocket state.
+- Added dashboard keyboard shortcuts for refresh, section navigation, settings, sidebar collapse, and drawer close.
+- Added exit-code-aware process status labels in the dashboard.
+- Kept dashboard settings in memory to avoid browser storage.
+- Documented `bunx devsurface` as a no-install launch command.
+
 ## 0.1.0
 
 - Initial DevSurface MVP scaffold.

package/README.md

@@ -1,8 +1,34 @@
-# DevSurface
+<!-- markdownlint-disable MD033 MD041 -->
 
-[![DevSurface ready](docs/devsurface-badge.svg)](https://github.com/mrfandu1/devsurface)
+<a id="readme-top"></a>
 
-Turn any Node.js repository into a local developer control panel.
+<div align="center">
+
+<h1>DevSurface</h1>
+
+<p><strong>Turn any Node.js repository into a local developer control panel.</strong></p>
+
+<p>
+  <a href="#quick-start">Quick Start</a>
+  &nbsp;&middot;&nbsp;
+  <a href="#commands">Commands</a>
+  &nbsp;&middot;&nbsp;
+  <a href="#dashboard">Dashboard</a>
+  &nbsp;&middot;&nbsp;
+  <a href="https://github.com/mrfandu1/devsurface/issues">Report an issue</a>
+</p>
+
+<p>
+  <a href="https://github.com/mrfandu1/devsurface">
+    <img alt="DevSurface ready" src="docs/devsurface-badge.svg">
+  </a>
+  <a href="LICENSE">
+    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-informational">
+  </a>
+  <img alt="Built with TypeScript" src="https://img.shields.io/badge/Built%20with-TypeScript-3178c6">
+</p>
+
+</div>
 
 DevSurface scans a project, starts a local dashboard, and shows the things contributors
 usually need before a project will run: package scripts, environment files, ports,
@@ -14,6 +40,12 @@ No config file is required.
 npx devsurface
 ```
 
+With Bun:
+
+```bash
+bunx devsurface
+```
+
 ![DevSurface demo](docs/devsurface-demo.gif)
 
 ## Why DevSurface
@@ -52,6 +84,13 @@ cd my-node-project
 npx devsurface
 ```
 
+Or, if you use Bun:
+
+```bash
+cd my-node-project
+bunx devsurface
+```
+
 The dashboard opens at:
 
 ```text
@@ -63,6 +102,13 @@ terminal.
 
 ## Commands
 
+Run DevSurface without installing it globally:
+
+| Runtime | Command           |
+| ------- | ----------------- |
+| npm     | `npx devsurface`  |
+| Bun     | `bunx devsurface` |
+
 | Command                   | Description                                                          |
 | ------------------------- | -------------------------------------------------------------------- |
 | `devsurface`              | Scan the current project, start the dashboard, and open the browser. |
@@ -205,18 +251,21 @@ npm test
 npm run build
 ```
 
-## Publishing
+## Contributing
 
-The npm package is allowlisted through `package.json#files`. The package includes the
-built CLI, built web UI, README, demo GIF, license, and changelog. Private notes,
-tests, examples, and development-only files are excluded from npm publishes.
+Contributions of every kind are welcome: code, documentation, bug reports,
+examples, and reviews. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development workflow.
 
-Check package contents before publishing:
+## License
 
-```bash
-npm pack --dry-run
-```
+DevSurface is released under the MIT License. See [LICENSE](LICENSE) for the full
+text. Copyright (c) 2026 DevSurface contributors.
 
-## License
+## Contact and community
+
+- GitHub Issues: report bugs and request features through
+  [GitHub Issues](https://github.com/mrfandu1/devsurface/issues).
+- Security: report vulnerabilities through [SECURITY.md](SECURITY.md).
 
-MIT. See [LICENSE](LICENSE).
+[(back to top)](#readme-top)

package/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security issues privately by opening a GitHub security advisory or by
+emailing the maintainer listed in the repository profile.
+
+DevSurface runs local commands from the project it scans. It never binds outside
+`127.0.0.1`, never sends telemetry, and never exposes `.env` values.

package/dist/cli/index.js

@@ -48,6 +48,7 @@ var defaultConfig = {
 };
 
 // src/core/config/load.ts
+var MAX_CONFIGURED_PORTS = 32;
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -101,7 +102,10 @@ function toPorts(value, warnings) {
   if (ports.length !== value.length) {
     warnings.push("ports may only contain integers between 1 and 65535.");
   }
-  return ports;
+  if (ports.length > MAX_CONFIGURED_PORTS) {
+    warnings.push(`ports may contain at most ${MAX_CONFIGURED_PORTS} entries.`);
+  }
+  return ports.slice(0, MAX_CONFIGURED_PORTS);
 }
 function validateConfig(raw) {
   const warnings = [];
@@ -609,12 +613,23 @@ async function detectPackageManager(root) {
 // src/core/scanner/packageJson.ts
 import { promises as fs7 } from "fs";
 import path7 from "path";
+function isWithinRoot4(root, target) {
+  const relative = path7.relative(root, target);
+  return relative === "" || !relative.startsWith("..") && !path7.isAbsolute(relative);
+}
 async function readPackageJson(root) {
   const packageJsonPath = path7.join(root, "package.json");
   try {
-    const content = await fs7.readFile(packageJsonPath, "utf8");
+    const [realRoot, realPackageJsonPath] = await Promise.all([
+      fs7.realpath(root),
+      fs7.realpath(packageJsonPath)
+    ]);
+    if (!isWithinRoot4(realRoot, realPackageJsonPath)) {
+      return null;
+    }
+    const content = await fs7.readFile(realPackageJsonPath, "utf8");
     const data = JSON.parse(content);
-    return { path: packageJsonPath, data };
+    return { path: realPackageJsonPath, data };
   } catch {
     return null;
   }
@@ -622,6 +637,8 @@ async function readPackageJson(root) {
 
 // src/core/scanner/ports.ts
 import net from "net";
+var MAX_PORT_PROBES = 64;
+var PORT_PROBE_CONCURRENCY = 16;
 function uniquePorts(ports) {
   return Array.from(
     new Set(ports.filter((port) => Number.isInteger(port) && port > 0 && port < 65536))
@@ -675,11 +692,25 @@ async function probePort(port) {
   });
 }
 async function detectPorts(ports) {
-  const normalized = uniquePorts(ports);
+  const normalized = uniquePorts(ports).slice(0, MAX_PORT_PROBES);
   if (normalized.length === 0) {
     return null;
   }
-  return await Promise.all(normalized.map((port) => probePort(port)));
+  const results = [];
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < normalized.length) {
+      const port = normalized[nextIndex];
+      nextIndex += 1;
+      results.push(await probePort(port));
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(PORT_PROBE_CONCURRENCY, normalized.length) }, () => worker())
+  );
+  return results.sort(
+    (left, right) => normalized.indexOf(left.port) - normalized.indexOf(right.port)
+  );
 }
 
 // src/core/scanner/scripts.ts
@@ -917,6 +948,31 @@ async function runDoctor(root = process.cwd(), scan) {
   return warnings;
 }
 
+// src/cli/terminal.ts
+var ESC = 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");
+function stripControlCharacters(value) {
+  let result = "";
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code > 31 && code < 127 || code > 159) {
+      result += character;
+    }
+  }
+  return result;
+}
+function safeTerminalText(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";
+}
+
 // src/cli/commands/doctor.ts
 function colorSeverity(severity) {
   if (severity === "error") {
@@ -934,8 +990,8 @@ async function doctorCommand(cwd = process.cwd()) {
     return;
   }
   for (const item of warnings) {
-    console.log(`${colorSeverity(item.severity)} ${pc.bold(item.title)}`);
-    console.log(`  ${item.message}`);
+    console.log(`${colorSeverity(item.severity)} ${pc.bold(safeTerminalText(item.title))}`);
+    console.log(`  ${safeTerminalText(item.message)}`);
   }
 }
 
@@ -1065,14 +1121,14 @@ async function runCommand(script, cwd = process.cwd()) {
 // src/cli/commands/scan.ts
 import pc4 from "picocolors";
 function formatList(values) {
-  return values.length > 0 ? values.join(", ") : "none";
+  return safeTerminalList(values);
 }
 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(pc4.bold(`Project:   ${safeTerminalText(scan.projectName)}`));
+  console.log(`Type:      ${safeTerminalText(scan.framework?.type ?? "Unknown")}`);
+  console.log(`Manager:   ${safeTerminalText(scan.packageManager ?? "unknown")}`);
   console.log(`Scripts:   ${formatList(Object.keys(scan.scripts))}`);
-  console.log(`Git:       ${scan.git?.branch ?? "not detected"}`);
+  console.log(`Git:       ${safeTerminalText(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) {
@@ -1099,7 +1155,7 @@ import pc5 from "picocolors";
 import { promises as fs12 } from "fs";
 import path12 from "path";
 import { fileURLToPath } from "url";
-import { serve } from "@hono/node-server";
+import { createAdaptorServer } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import open2 from "open";
@@ -1107,6 +1163,23 @@ import open2 from "open";
 // src/core/process/manager.ts
 import { EventEmitter } from "events";
 import spawn3 from "cross-spawn";
+function killChildProcessTree(child) {
+  if (child.pid === void 0) {
+    child.kill();
+    return;
+  }
+  if (process.platform === "win32") {
+    const result = spawn3.sync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+      stdio: "ignore",
+      windowsHide: true
+    });
+    if (result.error) {
+      child.kill();
+    }
+    return;
+  }
+  child.kill();
+}
 var ProcessManager = class extends EventEmitter {
   processes = /* @__PURE__ */ new Map();
   logs = [];
@@ -1163,7 +1236,7 @@ var ProcessManager = class extends EventEmitter {
     }
     record.status = "stopped";
     record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
-    record.child.kill();
+    killChildProcessTree(record.child);
     this.emitSystem(record, "Stopped by DevSurface");
     this.emit("process", this.snapshot(record));
     return true;
@@ -1179,7 +1252,7 @@ var ProcessManager = class extends EventEmitter {
       if (record.status === "running") {
         record.status = "stopped";
         record.endedAt = (/* @__PURE__ */ new Date()).toISOString();
-        record.child.kill();
+        killChildProcessTree(record.child);
       }
     }
   }
@@ -1273,7 +1346,7 @@ function isSameOrigin(requestUrl, origin) {
 }
 
 // src/server/routes/api.ts
-function isWithinRoot4(root, target) {
+function isWithinRoot5(root, target) {
   const relative = path11.relative(path11.resolve(root), path11.resolve(target));
   return relative === "" || !relative.startsWith("..") && !path11.isAbsolute(relative);
 }
@@ -1290,18 +1363,18 @@ function hasMutationIntent(intent) {
   return intent === "dashboard";
 }
 async function realPathWithinRoot(root, target) {
-  if (!isWithinRoot4(root, target)) {
+  if (!isWithinRoot5(root, target)) {
     return false;
   }
   try {
     const [realRoot, realTarget] = await Promise.all([fs11.realpath(root), fs11.realpath(target)]);
-    return isWithinRoot4(realRoot, realTarget);
+    return isWithinRoot5(realRoot, realTarget);
   } catch {
     return false;
   }
 }
 async function writableDestinationWithinRoot(root, destination) {
-  if (!isWithinRoot4(root, destination)) {
+  if (!isWithinRoot5(root, destination)) {
     return false;
   }
   try {
@@ -1309,7 +1382,7 @@ async function writableDestinationWithinRoot(root, destination) {
       fs11.realpath(root),
       fs11.realpath(path11.dirname(destination))
     ]);
-    return isWithinRoot4(realRoot, realParent);
+    return isWithinRoot5(realRoot, realParent);
   } catch {
     return false;
   }
@@ -1444,6 +1517,9 @@ function registerApiRoutes(app, options) {
   app.get("/api/processes", (context) => {
     return context.json(options.processManager.list());
   });
+  app.get("/api/logs", (context) => {
+    return context.json(options.processManager.listLogs());
+  });
   app.post("/api/run/:script", async (context) => {
     const script = decodeURIComponent(context.req.param("script"));
     const scan = await scanProject(options.projectRoot);
@@ -1635,6 +1711,70 @@ async function findWebDistDir() {
   }
   return null;
 }
+function toListenError(error, port) {
+  const code = error instanceof Error ? error.code : void 0;
+  if (code === "EADDRINUSE") {
+    return new Error(
+      `Port ${port} is already in use on ${HOST}. Stop the other process or run DevSurface with --port ${port + 1}.`,
+      { cause: error }
+    );
+  }
+  if (code === "EACCES") {
+    return new Error(`DevSurface does not have permission to bind to ${HOST}:${port}.`, {
+      cause: error
+    });
+  }
+  return error instanceof Error ? error : new Error(String(error));
+}
+async function listenOnLocalHost(server, wss, port) {
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      server.off("error", onError);
+      server.off("listening", onListening);
+      wss.off("error", onError);
+    };
+    const onError = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(toListenError(error, port));
+    };
+    const onListening = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    wss.once("error", onError);
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, HOST);
+  });
+}
+async function closeWebSocketServer(wss) {
+  await new Promise((resolve) => {
+    wss.close(() => resolve());
+  });
+}
+async function closeHttpServer(server) {
+  if (!server.listening) {
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}
 async function createApp(options) {
   const app = new Hono();
   registerApiRoutes(app, options);
@@ -1666,12 +1806,13 @@ async function startDevSurfaceServer(options) {
     projectRoot: options.projectRoot,
     processManager
   });
-  const server = serve({
+  const server = createAdaptorServer({
     fetch: app.fetch,
-    port,
     hostname: HOST
   });
   const wss = setupWebSocket(server, processManager);
+  await listenOnLocalHost(server, wss, port);
+  processManager.attachCleanupHandlers();
   const url = `http://${HOST}:${port}`;
   if (options.openBrowser !== false) {
     await open2(url);
@@ -1682,18 +1823,8 @@ async function startDevSurfaceServer(options) {
     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();
-          }
-        });
-      });
+      await closeWebSocketServer(wss);
+      await closeHttpServer(server);
     }
   };
 }
@@ -1701,7 +1832,7 @@ async function startDevSurfaceServer(options) {
 // 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(pc5.bold(`DevSurface v0.2.0`));
   console.log("Scanning project...\n");
   const scan = await scanProject(cwd);
   printScanResult(scan);
@@ -1738,7 +1869,7 @@ function handle(command) {
     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) => {
+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) => {
   handle(
     startCommand({
       cwd: process.cwd(),