localhost-cockpit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 localhost contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# localhost
+
+`localhost` is a dependency-free terminal cockpit for the development servers
+running on your computer. It is designed for both humans and AI coding agents.
+
+```text
+NAME          URL                    STACK    PID    BRANCH
+storefront    http://localhost:3000  Next.js  48102  checkout-redesign
+api           http://localhost:8000  FastAPI  48177  main
+```
+
+## Try it
+
+Requires Node.js 20+ and `lsof` (included with macOS and commonly available on
+Linux).
+
+```bash
+npm link
+localhost
+localhost inspect 3000
+localhost watch
+```
+
+No global installation is needed while developing:
+
+```bash
+node ./bin/localhost.js list
+```
+
+## Commands
+
+```bash
+localhost list [--json] [--all]
+localhost inspect <pid|port> [--json]
+localhost open <pid|port>
+localhost stop <pid|port> [--force]
+localhost watch [seconds]
+localhost mcp
+```
+
+The JSON response is versionable, deterministic output for scripts and agents:
+
+```bash
+localhost list --json | jq '.servers[] | {name, port, framework}'
+```
+
+By default, obvious operating-system listeners are hidden and cannot be targeted
+by the inspect or stop commands. Use `localhost list --all` only when diagnosing
+discovery itself.
+
+## MCP integration
+
+Add the server to an MCP-capable coding agent using a stdio configuration:
+
+```json
+{
+  "mcpServers": {
+    "localhost": {
+      "command": "node",
+      "args": ["/absolute/path/to/localhost/bin/localhost.js", "mcp"]
+    }
+  }
+}
+```
+
+Tools exposed:
+
+- `list_servers` — discover listening servers and their project context
+- `inspect_server` — inspect a server by port or PID
+- `stop_server` — terminate a verified listener; requires `confirm: true`
+
+`stop_server` re-runs discovery immediately before signaling the process. This
+prevents an agent from acting on stale process information.
+
+The server supports both the modern MCP `2026-07-28` `server/discover` lifecycle
+and the legacy `initialize` lifecycle. Tool results include both human-readable
+text and schema-declared `structuredContent`.
+
+## Current scope
+
+This first release supports macOS and Linux systems with `lsof`. Stable local
+domains, aggregated logs, Docker metadata, and a full-screen interactive TUI are
+planned next.
+
+## Development
+
+```bash
+npm test
+npm run check
+```
+
+## License
+
+MIT

package/bin/localhost.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import { discoverServers, findServer } from "../src/discovery.js";
+import { formatDetails, formatTable } from "../src/format.js";
+import { runMcpServer } from "../src/mcp.js";
+import { openServer, stopServer } from "../src/actions.js";
+
+const VERSION = "0.1.0";
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = new Set();
+  for (const arg of argv) {
+    if (arg.startsWith("--")) flags.add(arg);
+    else positional.push(arg);
+  }
+  return { positional, flags };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function help() {
+  return `localhost ${VERSION} — your local development cockpit
+
+Usage:
+  localhost                         List listening development servers
+  localhost list [--json] [--all]   List servers as a table or stable JSON
+  localhost inspect <pid|port>      Show one server in detail
+  localhost open <pid|port>         Open a server in the default browser
+  localhost stop <pid|port>         Gracefully stop a server
+  localhost stop <pid|port> --force Send SIGKILL instead of SIGTERM
+  localhost watch [seconds]         Refresh the terminal dashboard
+  localhost mcp                     Run the MCP server over stdio
+
+Agent usage:
+  localhost list --json
+  localhost inspect 3000 --json
+  localhost mcp
+
+Targets can be a PID, a port, or :port. Destructive actions only operate on
+processes that are still listening when the action is performed.`;
+}
+
+async function list(json = false, includeSystem = false) {
+  const servers = await discoverServers({ includeSystem });
+  if (json) printJson({ servers, count: servers.length });
+  else process.stdout.write(`${formatTable(servers)}\n`);
+}
+
+async function inspect(target, json = false) {
+  const servers = await discoverServers();
+  const server = findServer(servers, target);
+  if (json) printJson(server);
+  else process.stdout.write(`${formatDetails(server)}\n`);
+}
+
+async function watch(secondsArg) {
+  const seconds = Number(secondsArg ?? 2);
+  if (!Number.isFinite(seconds) || seconds < 0.25) {
+    throw new Error("Refresh interval must be at least 0.25 seconds");
+  }
+  const render = async () => {
+    const servers = await discoverServers();
+    process.stdout.write("\u001b[2J\u001b[H");
+    process.stdout.write(`localhost — ${new Date().toLocaleTimeString()} — Ctrl+C to exit\n\n`);
+    process.stdout.write(`${formatTable(servers)}\n`);
+  };
+  await render();
+  setInterval(() => void render(), seconds * 1000);
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const [command = "list", target] = positional;
+  const json = flags.has("--json");
+
+  if (flags.has("--help") || command === "help") {
+    process.stdout.write(`${help()}\n`);
+    return;
+  }
+  if (flags.has("--version") || command === "version") {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  switch (command) {
+    case "list":
+      await list(json, flags.has("--all"));
+      break;
+    case "inspect": {
+      if (!target) throw new Error("inspect requires a PID or port");
+      await inspect(target, json);
+      break;
+    }
+    case "open": {
+      if (!target) throw new Error("open requires a PID or port");
+      const result = await openServer(target);
+      if (json) printJson(result);
+      else process.stdout.write(`Opened ${result.url}\n`);
+      break;
+    }
+    case "stop": {
+      if (!target) throw new Error("stop requires a PID or port");
+      const result = await stopServer(target, { force: flags.has("--force") });
+      if (json) printJson(result);
+      else process.stdout.write(`Sent ${result.signal} to ${result.name} (PID ${result.pid})\n`);
+      break;
+    }
+    case "watch":
+      await watch(target);
+      break;
+    case "mcp":
+      await runMcpServer();
+      break;
+    default:
+      throw new Error(`Unknown command: ${command}\n\n${help()}`);
+  }
+}
+
+main().catch((error) => {
+  const jsonRequested = process.argv.includes("--json");
+  if (jsonRequested) printJson({ error: error.message, code: error.code ?? "LOCALHOST_ERROR" });
+  else process.stderr.write(`localhost: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "localhost-cockpit",
+  "version": "0.1.0",
+  "description": "See and control every development server running on your machine.",
+  "keywords": [
+    "localhost",
+    "developer-tools",
+    "cli",
+    "mcp",
+    "dev-server"
+  ],
+  "author": "Danilo Lekovic",
+  "homepage": "https://github.com/danilolekovic/localhost#readme",
+  "bugs": {
+    "url": "https://github.com/danilolekovic/localhost/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danilolekovic/localhost.git"
+  },
+  "type": "module",
+  "bin": {
+    "localhost": "bin/localhost.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ./bin/localhost.js",
+    "test": "node --test",
+    "check": "node --check ./bin/localhost.js && node --check ./src/discovery.js && node --check ./src/mcp.js",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/actions.js

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import { discoverServers, findServer } from "./discovery.js";
+
+export async function resolveLiveServer(target) {
+  return findServer(await discoverServers(), target);
+}
+
+export async function stopServer(target, { force = false } = {}) {
+  const server = await resolveLiveServer(target);
+  const signal = force ? "SIGKILL" : "SIGTERM";
+  process.kill(server.pid, signal);
+  return { ok: true, action: "stop", signal, pid: server.pid, port: server.port, name: server.name };
+}
+
+export async function openServer(target) {
+  const server = await resolveLiveServer(target);
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", server.url] : [server.url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.unref();
+  return { ok: true, action: "open", pid: server.pid, port: server.port, url: server.url };
+}

package/src/discovery.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { run, tryRun } from "./system.js";
+
+export function parseLsofFieldOutput(output) {
+  const listeners = [];
+  let process = null;
+  let file = null;
+
+  const flushFile = () => {
+    if (!process || !file?.name) return;
+    const match = file.name.match(/(?:\]|:)(\d+)(?:\s+\(LISTEN\))?$/);
+    if (!match) return;
+    listeners.push({
+      pid: Number(process.pid),
+      commandName: process.commandName,
+      address: file.name.replace(/\s+\(LISTEN\)$/, ""),
+      port: Number(match[1]),
+    });
+  };
+
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    const field = line[0];
+    const value = line.slice(1);
+    if (field === "p") {
+      flushFile();
+      process = { pid: value, commandName: "unknown" };
+      file = null;
+    } else if (field === "c" && process) {
+      process.commandName = value;
+    } else if (field === "f") {
+      flushFile();
+      file = { fd: value, name: "" };
+    } else if (field === "n" && file) {
+      file.name = value;
+    }
+  }
+  flushFile();
+  return listeners;
+}
+
+function frameworkFrom(pkg, command) {
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const candidates = [
+    ["next", "Next.js"], ["vite", "Vite"], ["astro", "Astro"],
+    ["nuxt", "Nuxt"], ["@remix-run/dev", "Remix"], ["gatsby", "Gatsby"],
+    ["react-scripts", "Create React App"], ["fastify", "Fastify"],
+    ["express", "Express"], ["@nestjs/core", "NestJS"],
+  ];
+  for (const [dependency, label] of candidates) {
+    if (deps?.[dependency]) return label;
+  }
+  if (/rails/i.test(command)) return "Rails";
+  if (/django|manage\.py/i.test(command)) return "Django";
+  if (/uvicorn|fastapi/i.test(command)) return "FastAPI";
+  if (/python/i.test(command)) return "Python";
+  if (/node|bun|deno/i.test(command)) return "Node.js";
+  return null;
+}
+
+function isLikelyDevelopmentServer({ cwd, command, framework }) {
+  if (framework) return true;
+  if (/\b(node|npm|npx|pnpm|yarn|bun|deno|python|ruby|rails|php|java|cargo|go run|dotnet)\b/i.test(command)) {
+    return true;
+  }
+  if (!cwd || cwd === "/") return false;
+  return !/^\/(System|Library|usr|bin|sbin|private\/var)(?:\/|$)/.test(cwd);
+}
+
+async function packageInfo(cwd) {
+  if (!cwd) return { pkg: null, packageName: null };
+  try {
+    const pkg = JSON.parse(await readFile(path.join(cwd, "package.json"), "utf8"));
+    return { pkg, packageName: pkg.name ?? null };
+  } catch {
+    return { pkg: null, packageName: null };
+  }
+}
+
+async function enrich(listener) {
+  const pid = String(listener.pid);
+  const cwdRaw = await tryRun("lsof", ["-a", "-p", pid, "-d", "cwd", "-Fn"]);
+  const cwd = cwdRaw.split("\n").find((line) => line.startsWith("n"))?.slice(1) ?? null;
+  const command = await tryRun("ps", ["-p", pid, "-o", "command="], listener.commandName);
+  const { pkg, packageName } = await packageInfo(cwd);
+  const gitBranch = cwd
+    ? await tryRun("git", ["-C", cwd, "branch", "--show-current"], "")
+    : "";
+  const host = /(?:127\.0\.0\.1|\[::1\]|localhost)/.test(listener.address)
+    ? "localhost"
+    : "localhost";
+  const protocol = [443, 8443].includes(listener.port) ? "https" : "http";
+  const framework = frameworkFrom(pkg, command);
+  const name = packageName || (cwd && cwd !== "/" ? path.basename(cwd) : null) || listener.commandName;
+  const server = {
+    id: `${listener.pid}:${listener.port}`,
+    pid: listener.pid,
+    port: listener.port,
+    address: listener.address,
+    url: `${protocol}://${host}:${listener.port}`,
+    name,
+    process: listener.commandName,
+    command,
+    cwd,
+    framework,
+    gitBranch: gitBranch || null,
+  };
+  return { ...server, development: isLikelyDevelopmentServer(server) };
+}
+
+export async function discoverServers({ includeSystem = false } = {}) {
+  let output;
+  try {
+    output = await run("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-Fpcfn"]);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      const wrapped = new Error("lsof is required for process discovery");
+      wrapped.code = "MISSING_LSOF";
+      throw wrapped;
+    }
+    return [];
+  }
+
+  const parsed = parseLsofFieldOutput(output);
+  const unique = [...new Map(parsed.map((item) => [`${item.pid}:${item.port}`, item])).values()];
+  const servers = await Promise.all(unique.map(enrich));
+  return servers
+    .filter((server) => includeSystem || server.development)
+    .sort((a, b) => a.port - b.port || a.pid - b.pid);
+}
+
+export function findServer(servers, target) {
+  const normalized = String(target).replace(/^:/, "");
+  const number = Number(normalized);
+  if (!Number.isInteger(number) || number <= 0) {
+    const error = new Error(`Invalid target: ${target}. Use a PID, port, or :port.`);
+    error.code = "INVALID_TARGET";
+    throw error;
+  }
+  const byPort = servers.filter((server) => server.port === number);
+  const byPid = servers.filter((server) => server.pid === number);
+  const matches = [...new Map([...byPort, ...byPid].map((server) => [server.id ?? `${server.pid}:${server.port}`, server])).values()];
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    const error = new Error(`Target ${target} is ambiguous; use the server's port instead.`);
+    error.code = "AMBIGUOUS_TARGET";
+    throw error;
+  }
+  const error = new Error(`No listening server found for ${target}`);
+  error.code = "SERVER_NOT_FOUND";
+  throw error;
+}

package/src/format.js

@@ -0,0 +1,46 @@
+const color = {
+  dim: (value) => `\u001b[2m${value}\u001b[22m`,
+  cyan: (value) => `\u001b[36m${value}\u001b[39m`,
+  green: (value) => `\u001b[32m${value}\u001b[39m`,
+  bold: (value) => `\u001b[1m${value}\u001b[22m`,
+};
+
+function plainLength(value) {
+  return String(value).replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+
+function pad(value, width) {
+  return `${value}${" ".repeat(Math.max(0, width - plainLength(value)))}`;
+}
+
+export function formatTable(servers) {
+  if (servers.length === 0) return "No listening TCP servers found.";
+  const rows = servers.map((server) => [
+    server.name,
+    server.url,
+    server.framework ?? server.process,
+    String(server.pid),
+    server.gitBranch ?? "—",
+  ]);
+  const headers = ["NAME", "URL", "STACK", "PID", "BRANCH"];
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => plainLength(row[index])))
+  );
+  const header = headers.map((cell, index) => pad(color.dim(cell), widths[index])).join("  ");
+  const body = rows.map((row) => row.map((cell, index) => {
+    const styled = index === 0 ? color.bold(cell) : index === 1 ? color.cyan(cell) : index === 3 ? color.green(cell) : cell;
+    return pad(styled, widths[index]);
+  }).join("  "));
+  return [header, ...body].join("\n");
+}
+
+export function formatDetails(server) {
+  const entries = [
+    ["Name", server.name], ["URL", server.url], ["PID", server.pid],
+    ["Process", server.process], ["Framework", server.framework],
+    ["Branch", server.gitBranch], ["Directory", server.cwd],
+    ["Command", server.command], ["Address", server.address],
+  ].filter(([, value]) => value !== null && value !== "");
+  const width = Math.max(...entries.map(([key]) => key.length));
+  return entries.map(([key, value]) => `${color.dim(pad(key, width))}  ${value}`).join("\n");
+}

package/src/mcp.js

@@ -0,0 +1,170 @@
+import { discoverServers, findServer } from "./discovery.js";
+import { stopServer } from "./actions.js";
+
+const tools = [
+  {
+    name: "list_servers",
+    description: "List TCP servers currently listening on the developer's machine, including ports, projects, frameworks, and git branches.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    outputSchema: { type: "object" },
+  },
+  {
+    name: "inspect_server",
+    description: "Inspect a listening server by TCP port or process ID.",
+    inputSchema: {
+      type: "object",
+      properties: { target: { type: ["string", "number"], description: "A TCP port or process ID" } },
+      required: ["target"], additionalProperties: false,
+    },
+    outputSchema: { type: "object" },
+  },
+  {
+    name: "stop_server",
+    description: "Stop a verified listening server. Requires confirm=true because this terminates a local process.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: { type: ["string", "number"], description: "A TCP port or process ID" },
+        confirm: { type: "boolean", description: "Must be true to confirm process termination" },
+        force: { type: "boolean", default: false, description: "Use SIGKILL instead of SIGTERM" },
+      },
+      required: ["target", "confirm"], additionalProperties: false,
+    },
+    outputSchema: { type: "object" },
+  },
+];
+
+const MODERN_VERSION = "2026-07-28";
+const LEGACY_VERSION = "2025-11-25";
+const SERVER_INFO = { name: "localhost", version: "0.1.0" };
+
+function response(id, result) {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function errorResponse(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+function textResult(value, isError = false) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    ...(isError ? {} : { structuredContent: value }),
+    isError,
+  };
+}
+
+function modernResponse(message, result) {
+  const modern = message.method === "server/discover"
+    || message.params?._meta?.["io.modelcontextprotocol/protocolVersion"] === MODERN_VERSION;
+  if (!modern) return response(message.id, result);
+  return response(message.id, {
+    ...result,
+    _meta: {
+      ...result?._meta,
+      "io.modelcontextprotocol/serverInfo": SERVER_INFO,
+    },
+  });
+}
+
+export async function handleMcpMessage(message) {
+  const { id, method, params = {} } = message;
+  if (method === "server/discover") {
+    return modernResponse(message, {
+      supportedVersions: [MODERN_VERSION, LEGACY_VERSION],
+      capabilities: { tools: {} },
+      instructions: "Discover and inspect local development servers. Stop a process only after explicit user confirmation.",
+      ttlMs: 60_000,
+      cacheScope: "private",
+    });
+  }
+  if (method === "initialize") {
+    const requested = params.protocolVersion;
+    const protocolVersion = requested && requested !== MODERN_VERSION ? requested : LEGACY_VERSION;
+    return response(id, {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo: SERVER_INFO,
+    });
+  }
+  if (method === "notifications/initialized") return null;
+  if (method === "ping") return modernResponse(message, {});
+  if (method === "tools/list") return modernResponse(message, { tools });
+  if (method === "tools/call") {
+    const args = params.arguments ?? {};
+    try {
+      if (params.name === "list_servers") {
+        const servers = await discoverServers();
+        return modernResponse(message, textResult({ servers, count: servers.length }));
+      }
+      if (params.name === "inspect_server") {
+        const server = findServer(await discoverServers(), args.target);
+        return modernResponse(message, textResult(server));
+      }
+      if (params.name === "stop_server") {
+        if (args.confirm !== true) {
+          return modernResponse(message, textResult({ error: "Set confirm=true to stop the process." }, true));
+        }
+        return modernResponse(message, textResult(await stopServer(args.target, { force: args.force === true })));
+      }
+      return errorResponse(id, -32601, `Unknown tool: ${params.name}`);
+    } catch (error) {
+      return modernResponse(message, textResult({ error: error.message, code: error.code ?? "LOCALHOST_ERROR" }, true));
+    }
+  }
+  return errorResponse(id, -32601, `Method not found: ${method}`);
+}
+
+function writeMessage(message, framing = "newline") {
+  const body = JSON.stringify(message);
+  if (framing === "content-length") {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+  } else {
+    process.stdout.write(`${body}\n`);
+  }
+}
+
+export async function runMcpServer() {
+  let buffer = Buffer.alloc(0);
+  process.stdin.on("data", async (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (true) {
+      // Modern MCP stdio uses one JSON-RPC message per line. Content-Length
+      // framing is also accepted for compatibility with older clients.
+      if (!buffer.toString("utf8", 0, Math.min(buffer.length, 15)).startsWith("Content-Length:")) {
+        const newline = buffer.indexOf("\n");
+        if (newline === -1) break;
+        const body = buffer.subarray(0, newline).toString("utf8").trim();
+        buffer = buffer.subarray(newline + 1);
+        if (!body) continue;
+        try {
+          const result = await handleMcpMessage(JSON.parse(body));
+          if (result) writeMessage(result, "newline");
+        } catch (error) {
+          writeMessage(errorResponse(null, -32700, error.message), "newline");
+        }
+        continue;
+      }
+      const separator = buffer.indexOf("\r\n\r\n");
+      if (separator === -1) break;
+      const header = buffer.subarray(0, separator).toString("utf8");
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) {
+        buffer = buffer.subarray(separator + 4);
+        continue;
+      }
+      const length = Number(match[1]);
+      const bodyStart = separator + 4;
+      if (buffer.length < bodyStart + length) break;
+      const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf8");
+      buffer = buffer.subarray(bodyStart + length);
+      try {
+        const result = await handleMcpMessage(JSON.parse(body));
+        if (result) writeMessage(result, "content-length");
+      } catch (error) {
+        writeMessage(errorResponse(null, -32700, error.message), "content-length");
+      }
+    }
+  });
+  process.stdin.resume();
+}

package/src/system.js

@@ -0,0 +1,21 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function run(command, args = [], options = {}) {
+  const { stdout } = await execFileAsync(command, args, {
+    encoding: "utf8",
+    maxBuffer: 4 * 1024 * 1024,
+    ...options,
+  });
+  return stdout.trim();
+}
+
+export async function tryRun(command, args = [], fallback = "") {
+  try {
+    return await run(command, args);
+  } catch {
+    return fallback;
+  }
+}