stackdeck 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beingmechon
+
+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,173 @@
+<img src="logo-wordmark.svg" alt="Stackdeck" height="52">
+
+**Your projects folder, as a control panel.**
+
+<img src="docs/screenshot.png" alt="The Stackdeck board: sections of services with live status, a parallel worktree instance of orders-api running a feature branch on its own port" width="100%">
+
+*(Fictional demo data — spin it up yourself with `./scripts/demo.sh`.)*
+
+A browser dashboard for the services you run every day in local development.
+Stackdeck scans your projects folder, figures out how to run each repo, and
+gives you Start / Kill / restart buttons, live logs, and a **git branch
+dropdown** that checks out the branch before launching. Zero dependencies —
+one Node process (>= 18.13), one HTML page, binds to 127.0.0.1.
+
+*Spiritual successor to [hotel](https://github.com/typicode/hotel)
+(unmaintained since 2019), with the git-awareness of
+[portree](https://github.com/fairy-pitta/portree) and the multi-project scope
+neither has.*
+
+## Quick start
+
+```bash
+git clone https://github.com/beingmechon/stackdeck && cd stackdeck
+node bin/stackdeck.js         # starts the daemon, opens http://localhost:8899
+```
+
+Or link it onto your PATH:
+
+```bash
+npm link                     # then: stackdeck | stackdeck status | stackdeck logs api
+```
+
+## What it does
+
+- **Discovers your projects** — scans your project roots (default `~/Projects`),
+  detects git repos + current branch, and infers a run command per repo
+  (pnpm/npm/yarn scripts, Makefile targets, Python entrypoints with uv
+  detection, docker-compose, cargo, go).
+- **Services** — a project you've promoted to a runnable recipe: directory +
+  command + port + env. Start / Kill / restart from the browser or CLI, live
+  ANSI-colored logs (also on disk), status by pid *and* port — services
+  started outside Stackdeck show as `external` and can be killed too.
+  Killing the daemon never kills your services: pids persist to disk and a
+  restarted daemon re-adopts them (still killable, logs resume on restart).
+- **Git-aware** — a branch dropdown per service; picking a branch runs
+  `git checkout` before start, refused while the tree is dirty. Dirty repos
+  are badged.
+- **Organize the board** — drag rows between your own sections, per-section
+  *start all* / *stop all*, collapse/expand, hide/unhide anything, categorize
+  the project list.
+- **Stacks that start in order** — give a service `dependsOn` and it starts
+  after its dependencies are *ready* (a log-line regex via `readyWhen`, an
+  HTTP check, or its port opening). Section **start all** is
+  dependency-ordered; cycles fail loudly.
+- **Crash handling** — `restart: on-failure` restarts with exponential
+  backoff (5 tries, resets after a minute of clean uptime); unexpected exits
+  show a `crashed` badge and fire a browser notification. Manual stops never
+  auto-restart.
+- **Port squatter eviction** — if another process holds a service's port,
+  Start tells you the pid and offers to kill it and take the port.
+- ***.localhost domains** — a built-in reverse proxy maps
+  `<service>.localhost` → its port, and `<branch>.<service>.localhost` →
+  a running worktree instance (whose port you didn't pick — that's when
+  stable names matter most). WebSockets included. Browsers resolve
+  `*.localhost` natively: no /etc/hosts, no PAC files. Port 80 where
+  binding is permitted, `:8880` otherwise.
+- **Multi-process repos** — a Procfile, docker-compose services, or pnpm
+  workspace packages turn one repo into a section of services with one click.
+- **Parallel branches (worktrees)** — pick a branch and hit ⧉: the service
+  runs that branch in its own git worktree with a free port injected as
+  `$PORT`, side by side with the main checkout. Made for the
+  several-agents-on-several-branches workflow. Instances survive daemon
+  restarts (re-adopted like services) and worktrees are reused across runs.
+- **CLI parity** — `stackdeck status|start|stop|restart|logs <name>` talks to
+  the same daemon.
+- **MCP server** — `stackdeck mcp` exposes list/start/stop/restart/logs as
+  MCP tools over stdio, so AI coding agents can manage (and debug against)
+  your dev environment. Zero-dependency, wraps the same authenticated API.
+- **Dev tools** — detects databases and brokers installed on your machine
+  (PostgreSQL, MySQL/MariaDB, MongoDB, Redis/Valkey, Elasticsearch/OpenSearch,
+  RabbitMQ, NATS, MinIO, Temporal, ClickHouse, Mailpit, Memcached) and
+  one-click configures them as ordinary foreground services — managed child,
+  streamed logs, clean kill. Data directories are resolved from standard
+  locations (or self-initialized under `~/.local/share/stackdeck/`); no Docker,
+  no launchd/systemd indirection.
+
+## Configuration
+
+Everything lives in one JSON file — `~/.config/stackdeck/config.json`
+(or `$STACKDECK_HOME/config.json`); logs sit next to it. Every field is
+editable from the UI; the interesting ones:
+
+```jsonc
+{
+  "port": 8899,
+  "projectRoots": ["~/Projects", "~/work"],   // folders to scan
+  "categoryOrder": ["Products", "Tools"],     // display order of project categories
+  "projectCategories": { "my-repo": "Products" },
+  "groups": ["Stack A"],                      // your service sections
+  "services": [
+    {
+      "name": "api",
+      "dir": "~/Projects/my-app",
+      "command": "pnpm run dev",
+      "port": 3001,                            // for status detection + <name>.localhost
+      "env": { "DEBUG": "1" },
+      "group": "Stack A",
+      "dependsOn": ["db"],                     // started (and ready) first
+      "readyWhen": { "log": "Listening on" },  // or { "http": "http://…/health" }; default: port opens
+      "restart": "on-failure"                  // exponential backoff, 5 tries
+    }
+  ]
+}
+```
+
+## Security model
+
+The daemon executes shell commands by design, and **localhost is not a
+security boundary** — so the API is gated by a per-install secret
+(`<state dir>/secret`, mode 0600). The web page receives the token by being
+served from disk by the daemon itself; the CLI reads it as the same user.
+Every `/api/*` call without it gets a 401 (only the bare `/api/ping`
+liveness check is open). State files are 0600 in a 0700 directory.
+
+Layered on top: the daemon binds to 127.0.0.1 only, pins the `Host` header
+(DNS-rebinding defense), accepts only `application/json` POSTs (a cross-origin
+JSON POST forces a CORS preflight, which is never answered; `text/plain`
+sneak-POSTs are rejected), rejects foreign `Origin` headers, validates
+service/section names, ports, dirs, and env server-side, limits request bodies
+to 1MB, and restricts the folder browser to your home directory and configured
+roots. Config writes are atomic; a corrupt config is set aside, never fatal.
+Logs rotate at 5MB per service. Do not port-forward the daemon off your machine.
+
+The `*.localhost` proxy is unauthenticated by design (your browser needs it),
+but it only forwards to the loopback ports of services you configured —
+nothing else is reachable through it. Note that it makes those services
+reachable at *guessable names* from any site you visit (same-origin policy
+still blocks reading responses); that's roughly the exposure a guessable
+port already had, but if a dev service has destructive unauthenticated
+endpoints, don't give it a port in Stackdeck.
+
+Stackdeck is **Unix-only** (macOS/Linux): it relies on bash, process groups,
+and lsof/ss. The `.env` loader is intentionally minimal — flat `KEY=value`
+lines, quotes and `#` comments handled, no interpolation or multiline values.
+
+## Notes that will save you a debugging session
+
+- Services spawn through a **non-login** shell with the PATH of your login
+  shell resolved once at daemon start — so nvm/homebrew/uv tools are found
+  even when the daemon was launched from a GUI, and profile files can't
+  reorder your toolchain per-spawn.
+- The HTTP server accepts headers up to 256KB, because browsers hoard
+  localhost cookies across every dev app you've ever run, and Node's 16KB
+  default silently breaks localhost apps (431s / dropped connections).
+- Kill stops the whole process group; stragglers get SIGKILL after 5s.
+
+## macOS app (optional)
+
+```bash
+./scripts/macos-app.sh    # builds ~/Applications/Stackdeck.app from this checkout
+```
+
+Double-click to start the daemon and open the board. Linux users: `stackdeck`
+in a terminal, or add a systemd user unit for `node server.js`.
+
+## Status
+
+Early. Solid daily driver, small codebase (~1 file each side), no tests yet.
+Issues and PRs welcome.
+
+## License
+
+MIT

package/bin/stackdeck.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * stackdeck CLI — same daemon as the web board.
+ *
+ *   stackdeck                start the daemon (if down) and open the board
+ *   stackdeck daemon         run the daemon in the foreground
+ *   stackdeck status         list services and their state
+ *   stackdeck start <name>   start a service
+ *   stackdeck stop <name>    stop a service
+ *   stackdeck restart <name> restart a service
+ *   stackdeck logs <name>    stream a service's logs (Ctrl-C to quit)
+ *   stackdeck mcp            run an MCP server over stdio (for AI agents)
+ */
+"use strict";
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const { spawn, execFileSync } = require("child_process");
+
+const SERVER = path.join(__dirname, "..", "server.js");
+
+// The API requires the per-install secret; same-user processes read it from disk.
+function stateHome() {
+  if (process.env.STACKDECK_HOME)
+    return process.env.STACKDECK_HOME.replace(/^~(?=\/|$)/, os.homedir());
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(xdg, "stackdeck");
+}
+const token = () => { try { return fs.readFileSync(path.join(stateHome(), "secret"), "utf8").trim(); } catch { return ""; } };
+const authHeaders = () => ({ "X-Stackdeck-Token": token() });
+
+// Same port resolution as the daemon: env override, else config, else default.
+function resolvePort() {
+  const env = Number(process.env.STACKDECK_PORT);
+  if (Number.isInteger(env) && env >= 1 && env <= 65535) return env;
+  try {
+    const p = JSON.parse(fs.readFileSync(path.join(stateHome(), "config.json"), "utf8")).port;
+    if (Number.isInteger(p) && p >= 1 && p <= 65535) return p;
+  } catch {}
+  return 8899;
+}
+const PORT = resolvePort();
+const BASE = `http://127.0.0.1:${PORT}`;
+
+async function up() {
+  try { const r = await fetch(`${BASE}/api/ping`); return r.ok; } catch { return false; }
+}
+
+async function ensureDaemon() {
+  if (await up()) return;
+  // The daemon's own stderr (crash guards, request errors) goes to a log —
+  // safety nets that report to /dev/null are worse than no nets.
+  let out = "ignore";
+  try {
+    fs.mkdirSync(path.join(stateHome(), "logs"), { recursive: true, mode: 0o700 });
+    out = fs.openSync(path.join(stateHome(), "logs", "daemon.log"), "a");
+  } catch {}
+  const child = spawn(process.execPath, [SERVER], { detached: true, stdio: ["ignore", out, out] });
+  child.unref();
+  for (let i = 0; i < 40; i++) {
+    if (await up()) return;
+    await new Promise((ok) => setTimeout(ok, 250));
+  }
+  console.error("daemon did not come up — try: stackdeck daemon");
+  process.exit(1);
+}
+
+async function post(pathname, body) {
+  const r = await fetch(BASE + pathname, {
+    method: "POST", headers: { "Content-Type": "application/json", ...authHeaders() }, body: JSON.stringify(body),
+  });
+  const j = await r.json().catch(() => ({}));
+  if (!r.ok) { console.error("error:", j.error || r.statusText); process.exit(1); }
+  return j;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+  try { execFileSync(cmd, [url], { stdio: "ignore" }); } catch { console.log(url); }
+}
+
+(async () => {
+  const [cmd, name] = process.argv.slice(2);
+
+  if (!cmd || cmd === "up" || cmd === "open") {
+    await ensureDaemon();
+    console.log(`stackdeck · ${BASE}`);
+    openBrowser(BASE);
+    return;
+  }
+  if (cmd === "daemon") {
+    require(SERVER);
+    return;
+  }
+  if (cmd === "status") {
+    await ensureDaemon();
+    const r = await fetch(`${BASE}/api/services`, { headers: authHeaders() });
+    const d = await r.json().catch(() => ({}));
+    if (!r.ok) { console.error("error:", d.error || r.statusText); process.exit(1); }
+    for (const s of d.services) {
+      const state = s.running ? (s.managed ? "up" : "up (external)") : "down";
+      console.log(`${s.running ? "●" : "○"} ${s.name.padEnd(16)} ${state.padEnd(14)} :${s.port ?? "—"}  ${s.branch ?? ""}`);
+    }
+    return;
+  }
+  if (["start", "stop", "restart"].includes(cmd)) {
+    if (!name) { console.error(`usage: stackdeck ${cmd} <service>`); process.exit(1); }
+    await ensureDaemon();
+    await post(`/api/${cmd}`, { name });
+    console.log(`${name}: ${cmd} ok`);
+    return;
+  }
+  if (cmd === "logs") {
+    if (!name) { console.error("usage: stackdeck logs <service>"); process.exit(1); }
+    await ensureDaemon();
+    const res = await fetch(`${BASE}/api/logs?name=${encodeURIComponent(name)}`, { headers: authHeaders() });
+    if (!res.ok) { console.error("error:", (await res.json()).error); process.exit(1); }
+    let buf = "";
+    for await (const chunk of res.body) {
+      buf += chunk.toString();
+      const lines = buf.split("\n");
+      buf = lines.pop(); // keep any partial SSE frame for the next chunk
+      for (const line of lines)
+        if (line.startsWith("data: ")) { try { console.log(JSON.parse(line.slice(6))); } catch {} }
+    }
+    return;
+  }
+  if (cmd === "mcp") {
+    await ensureDaemon();
+    runMcp();
+    return;
+  }
+  console.error("unknown command:", cmd);
+  process.exit(1);
+})();
+
+/* ---------- MCP server (stdio, zero-dep) ----------
+   Exposes the daemon to AI agents: list services, start/stop/restart, read
+   logs. Newline-delimited JSON-RPC 2.0, MCP protocol 2025-03-26. */
+function runMcp() {
+  const TOOLS = [
+    { name: "list_services", description: "List all Stackdeck services with running state, port, pid, git branch, and dirty flag.",
+      inputSchema: { type: "object", properties: {} } },
+    { name: "start_service", description: "Start a service by name (starts its dependencies first). Optional branch to check out.",
+      inputSchema: { type: "object", properties: { name: { type: "string" }, branch: { type: "string" } }, required: ["name"] } },
+    { name: "stop_service", description: "Stop (kill) a service by name.",
+      inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } },
+    { name: "restart_service", description: "Restart a service by name.",
+      inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"] } },
+    { name: "get_logs", description: "Return the most recent log lines for a service (from its on-disk log).",
+      inputSchema: { type: "object", properties: { name: { type: "string" }, lines: { type: "number", description: "default 100" } }, required: ["name"] } },
+  ];
+  async function callTool(name, args) {
+    if (name === "list_services") {
+      const r = await fetch(`${BASE}/api/services`, { headers: authHeaders() });
+      const d = await r.json();
+      if (!r.ok) throw new Error(d.error || r.statusText);
+      return d.services.map((s) => ({
+        name: s.name, running: s.running, managed: s.managed, pid: s.pid, port: s.port ?? null,
+        branch: s.branch, dirty: s.dirty, group: s.group ?? null, command: s.command, dir: s.dir,
+      }));
+    }
+    if (["start_service", "stop_service", "restart_service"].includes(name)) {
+      const ep = { start_service: "start", stop_service: "stop", restart_service: "restart" }[name];
+      const r = await fetch(`${BASE}/api/${ep}`, {
+        method: "POST", headers: { "Content-Type": "application/json", ...authHeaders() },
+        body: JSON.stringify({ name: args.name, branch: args.branch }),
+      });
+      const d = await r.json();
+      if (!r.ok) throw new Error(d.error || r.statusText);
+      return d;
+    }
+    if (name === "get_logs") {
+      const n = Math.min(Math.max(Number(args.lines) || 100, 1), 2000);
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(args.name)) throw new Error("bad service name");
+      const file = path.join(stateHome(), "logs", `${args.name}.log`);
+      let text = "";
+      try { text = fs.readFileSync(file, "utf8"); } catch { throw new Error(`no logs for '${args.name}'`); }
+      return text.split("\n").slice(-n).join("\n");
+    }
+    throw new Error(`unknown tool: ${name}`);
+  }
+  let pending = 0, stdinDone = false;
+  const maybeExit = () => { if (stdinDone && pending === 0) process.exit(0); };
+  const reply = (id, result, error) => {
+    process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, ...(error ? { error: { code: -32000, message: error } } : { result }) }) + "\n");
+  };
+  let buf = "";
+  process.stdin.on("data", (chunk) => {
+    buf += chunk.toString("utf8");
+    const linesIn = buf.split("\n");
+    buf = linesIn.pop();
+    for (const line of linesIn) {
+      if (!line.trim()) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      if (msg.method === "initialize")
+        reply(msg.id, { protocolVersion: "2025-03-26", capabilities: { tools: {} },
+          serverInfo: { name: "stackdeck", version: "0.3.0" } });
+      else if (msg.method === "tools/list") reply(msg.id, { tools: TOOLS });
+      else if (msg.method === "tools/call") {
+        pending++; // dispatched concurrently: a slow call must not delay (or exit before) queued ones
+        callTool(msg.params.name, msg.params.arguments || {})
+          .then((out) => reply(msg.id, { content: [{ type: "text", text: typeof out === "string" ? out : JSON.stringify(out, null, 2) }] }))
+          .catch((e) => reply(msg.id, { content: [{ type: "text", text: `error: ${e.message}` }], isError: true }))
+          .finally(() => { pending--; maybeExit(); });
+      }
+      else if (msg.id !== undefined) reply(msg.id, {}); // politely ack anything else with an id
+    }
+  });
+  // Exit when the host closes the pipe — but only after in-flight calls finish.
+  process.stdin.on("end", () => { stdinDone = true; setImmediate(maybeExit); });
+}