@monster-orange/den 0.1.0 → 0.2.1

package/src/ui/mcp/api.ts

@@ -0,0 +1,286 @@
+/**
+ * The MCP server's client for the running web server's HTTP API. The MCP
+ * server holds no state of its own: agents and the web UI share the server's
+ * state and its guards. This client can reach only the routes below, and it
+ * sends the agent's audit headers (see shared/agent-actor.ts) on every call.
+ */
+import { product } from "../../shared/product.js";
+import { LIFECYCLE_CMDS, Refusal } from "./guards.js";
+
+export type Query = Record<string, string | string[] | undefined>;
+
+/** The web server isn't answering; the message names the start command. */
+export class DenWebDown extends Error {
+  constructor(baseUrl: string, cli: string) {
+    super(
+      `The ${product().title} web server is not running at ${baseUrl}. ` +
+        `Start it with \`${cli} web up\` (the MCP server never starts it for you).`,
+    );
+    this.name = "DenWebDown";
+  }
+}
+
+/** The web server answered with an error status. */
+export class DenHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    readonly body: string,
+  ) {
+    super(`${method} ${path} → ${status}: ${body}`);
+    this.name = "DenHttpError";
+  }
+}
+
+/** Read routes: GET only. */
+const READ_ROUTES = new Set([
+  "/api/health",
+  "/api/services",
+  "/api/applications",
+  "/api/graph",
+  "/api/workspaces",
+  "/api/environments",
+  "/api/logs/search",
+  "/api/service/taillog",
+  "/api/service/logs",
+  "/api/modules",
+  "/api/test-sources",
+  "/api/security/latest",
+  "/api/security/plan",
+  "/api/release/status",
+  "/api/release/runs",
+  "/api/manifest/validate",
+  "/api/stacks",
+  "/api/edge",
+  "/api/server-info",
+]);
+
+/** Action routes and their method. Anything else is never reached. */
+const ACTION_ROUTES: Record<string, string> = {
+  // A refusal report: appends one entry to the activity trail, nothing more.
+  "/api/activity": "POST",
+  "/api/service/exec": "GET",
+  "/api/run": "GET",
+  "/api/workspace/sync": "POST",
+};
+
+/**
+ * Throws a Refusal unless (method, path) is an allowed route. Never reached:
+ * sudo-password, aws/login, terminal/open, editor/open, workspace/exec,
+ * settings writes, workspace create/rename/mode, server-log, config, deploys.
+ * service/exec is allowed only for up/down/restart with env=local.
+ */
+export function assertAllowedRequest(
+  method: string,
+  path: string,
+  query: Query,
+): void {
+  const ok =
+    (READ_ROUTES.has(path) &&
+      (method === "GET" ||
+        (method === "POST" && path === "/api/manifest/validate"))) ||
+    ACTION_ROUTES[path] === method;
+  if (!ok) throw new Refusal(`${method} ${path} is not exposed to agents.`);
+  if (path === "/api/service/exec") {
+    const cmd = String(query.cmd ?? "");
+    if (!(LIFECYCLE_CMDS as readonly string[]).includes(cmd))
+      throw new Refusal(
+        `service/exec "${cmd}" refused: only ${LIFECYCLE_CMDS.join(", ")}.`,
+      );
+    if (query.env !== "local")
+      throw new Refusal("service/exec refused: env=local only.");
+  }
+}
+
+export interface SseEvent {
+  type?: string;
+  text?: string;
+  exitCode?: number;
+  [k: string]: unknown;
+}
+
+export interface StreamOpts {
+  method?: "GET" | "POST";
+  /** Stop after this many output lines (a follow stream never ends itself). */
+  maxLines: number;
+  /** Stop after this long, whatever is happening. */
+  timeoutMs: number;
+  /** Stop once nothing has arrived for this long (for log tails). */
+  idleMs?: number;
+  /** Stop when this event arrives (e.g. a detached `up` handing off). */
+  stopOn?: (e: SseEvent) => boolean;
+}
+
+export interface StreamResult {
+  events: SseEvent[];
+  lines: string[];
+  ended: "done" | "closed" | "limit" | "timeout" | "idle" | "stopped";
+  exitCode?: number;
+}
+
+export interface DenApi {
+  baseUrl: string;
+  /** A JSON route. */
+  get(
+    path: string,
+    query?: Query,
+    method?: "GET" | "POST",
+    body?: unknown,
+  ): Promise<unknown>;
+  /** An SSE route, read to a bound; the connection is closed after. */
+  stream(path: string, query: Query, opts: StreamOpts): Promise<StreamResult>;
+}
+
+function buildUrl(base: string, path: string, query: Query = {}): string {
+  const u = new URL(path, base);
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined) continue;
+    for (const one of Array.isArray(v) ? v : [v]) u.searchParams.append(k, one);
+  }
+  return u.toString();
+}
+
+function isConnectionError(e: unknown): boolean {
+  const err = e as { name?: string; cause?: { code?: string } };
+  if (err?.name === "AbortError") return false;
+  const code = err?.cause?.code ?? "";
+  return (
+    err?.name === "TypeError" ||
+    ["ECONNREFUSED", "ECONNRESET", "ENOTFOUND", "EHOSTUNREACH"].includes(code)
+  );
+}
+
+const OUTPUT_TYPES = new Set(["line", "cmd", "error"]);
+
+export function createDenApi(opts: {
+  baseUrl: string;
+  cli: string;
+  headers: () => Record<string, string>;
+}): DenApi {
+  const { baseUrl, cli } = opts;
+
+  async function request(
+    method: string,
+    path: string,
+    query: Query,
+    signal?: AbortSignal,
+    body?: unknown,
+  ): Promise<Response> {
+    assertAllowedRequest(method, path, query);
+    try {
+      const res = await fetch(buildUrl(baseUrl, path, query), {
+        method,
+        headers: {
+          ...opts.headers(),
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        signal,
+      });
+      if (!res.ok) {
+        const text = (await res.text()).slice(0, 2000);
+        throw new DenHttpError(method, path, res.status, text);
+      }
+      return res;
+    } catch (e) {
+      if (isConnectionError(e)) throw new DenWebDown(baseUrl, cli);
+      throw e;
+    }
+  }
+
+  return {
+    baseUrl,
+
+    async get(path, query = {}, method = "GET", body) {
+      const res = await request(method, path, query, undefined, body);
+      const text = await res.text();
+      try {
+        return JSON.parse(text) as unknown;
+      } catch {
+        return text;
+      }
+    },
+
+    async stream(path, query, s) {
+      const ac = new AbortController();
+      const res = await request(s.method ?? "GET", path, query, ac.signal);
+      const events: SseEvent[] = [];
+      const lines: string[] = [];
+      let exitCode: number | undefined;
+      let ended: StreamResult["ended"] = "closed";
+      let stop = false;
+
+      const finish = (why: StreamResult["ended"]): void => {
+        if (stop) return;
+        stop = true;
+        ended = why;
+        ac.abort();
+      };
+      const overall = setTimeout(() => finish("timeout"), s.timeoutMs);
+      let idle: ReturnType<typeof setTimeout> | undefined;
+      const bumpIdle = (): void => {
+        if (!s.idleMs) return;
+        if (idle) clearTimeout(idle);
+        idle = setTimeout(() => finish("idle"), s.idleMs);
+      };
+      bumpIdle();
+
+      const onEvent = (e: SseEvent): void => {
+        events.push(e);
+        if (OUTPUT_TYPES.has(String(e.type)) && typeof e.text === "string") {
+          for (const l of e.text.replace(/\n+$/, "").split("\n")) {
+            if (lines.length >= s.maxLines) return finish("limit");
+            lines.push(l);
+          }
+          if (lines.length >= s.maxLines) return finish("limit");
+        }
+        if (e.type === "done") {
+          if (typeof e.exitCode === "number") exitCode = e.exitCode;
+          return finish("done");
+        }
+        if (s.stopOn?.(e)) finish("stopped");
+      };
+
+      try {
+        const reader = res.body?.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        while (reader && !stop) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          bumpIdle();
+          buf += decoder.decode(value, { stream: true });
+          let i: number;
+          while (!stop && (i = buf.indexOf("\n\n")) !== -1) {
+            const chunk = buf.slice(0, i);
+            buf = buf.slice(i + 2);
+            const data = chunk
+              .split("\n")
+              .filter((l) => l.startsWith("data:"))
+              .map((l) => l.slice(5).trimStart())
+              .join("\n");
+            if (!data) continue;
+            try {
+              onEvent(JSON.parse(data) as SseEvent);
+            } catch {
+              onEvent({ type: "line", text: data });
+            }
+          }
+        }
+      } catch (e) {
+        if (!stop) throw e;
+      } finally {
+        clearTimeout(overall);
+        if (idle) clearTimeout(idle);
+        if (!stop) ac.abort();
+      }
+      return {
+        events,
+        lines,
+        ended,
+        ...(exitCode !== undefined ? { exitCode } : {}),
+      };
+    },
+  };
+}

package/src/ui/mcp/connect.ts

@@ -0,0 +1,304 @@
+/**
+ * `<cli> mcp connect`: register this distribution's MCP server with the
+ * agents a developer uses, so nobody hand-edits an MCP config.
+ *
+ * Each client is a strategy: where its config lives (or which of its own
+ * CLIs registers a server) and in which shape. Planning is pure (tests drive
+ * it with a fake home and PATH); applying it writes one JSON key or runs the
+ * client's own `mcp add`. Nothing else in a client's config is touched.
+ *
+ * The registered command is the distribution's bin shim by absolute path,
+ * with PATH pinned so that GUI clients (which start without the login shell's
+ * PATH, so without nvm's node) can launch it.
+ */
+import * as path from "path";
+
+export type Scope = "user" | "project";
+
+/** What gets registered: one stdio server. */
+export interface ServerSpec {
+  name: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export interface ConnectEnv {
+  home: string;
+  platform: NodeJS.Platform;
+  /** %APPDATA% on Windows. */
+  appData?: string;
+  /** The project directory for project scope (where the agent runs). */
+  projectDir: string;
+  /** Whether an executable is on PATH. */
+  which: (bin: string) => boolean;
+  /** Whether a file or directory exists. */
+  exists: (p: string) => boolean;
+}
+
+/** One change to make. */
+export type ConnectAction =
+  | {
+      kind: "json";
+      file: string;
+      /** Top-level key holding the servers: mcpServers, or servers (VS Code). */
+      key: "mcpServers" | "servers";
+      name: string;
+      entry: Record<string, unknown>;
+    }
+  | {
+      kind: "exec";
+      /** Run first, failure ignored: makes the add idempotent. */
+      remove?: string[];
+      add: string[];
+      /** Exit 0 when the server is registered (for status). */
+      check?: string[];
+    };
+
+export interface McpClient {
+  id: string;
+  title: string;
+  scopes: Scope[];
+  /** Whether the client looks installed here. */
+  detect(env: ConnectEnv): boolean;
+  plan(spec: ServerSpec, scope: Scope, env: ConnectEnv): ConnectAction;
+}
+
+const stdioEntry = (s: ServerSpec): Record<string, unknown> => ({
+  command: s.command,
+  args: s.args,
+  ...(Object.keys(s.env).length ? { env: s.env } : {}),
+});
+
+const envFlags = (flag: string, env: Record<string, string>): string[] =>
+  Object.entries(env).flatMap(([k, v]) => [flag, `${k}=${v}`]);
+
+function appSupport(env: ConnectEnv, app: string): string {
+  if (env.platform === "darwin")
+    return path.join(env.home, "Library", "Application Support", app);
+  if (env.platform === "win32")
+    return path.join(
+      env.appData ?? path.join(env.home, "AppData", "Roaming"),
+      app,
+    );
+  return path.join(env.home, ".config", app);
+}
+
+const json = (
+  file: string,
+  spec: ServerSpec,
+  key: "mcpServers" | "servers" = "mcpServers",
+  entry: Record<string, unknown> = stdioEntry(spec),
+): ConnectAction => ({ kind: "json", file, key, name: spec.name, entry });
+
+export const MCP_CLIENTS: readonly McpClient[] = [
+  {
+    id: "claude-code",
+    title: "Claude Code",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("claude"),
+    plan: (s, scope, e) =>
+      scope === "project"
+        ? json(path.join(e.projectDir, ".mcp.json"), s)
+        : {
+            kind: "exec",
+            remove: ["claude", "mcp", "remove", "--scope", "user", s.name],
+            add: [
+              "claude",
+              "mcp",
+              "add",
+              "--scope",
+              "user",
+              ...envFlags("-e", s.env),
+              s.name,
+              "--",
+              s.command,
+              ...s.args,
+            ],
+            check: ["claude", "mcp", "get", s.name],
+          },
+  },
+  {
+    id: "codex",
+    title: "Codex CLI",
+    scopes: ["user"],
+    detect: (e) => e.which("codex"),
+    plan: (s) => ({
+      kind: "exec",
+      remove: ["codex", "mcp", "remove", s.name],
+      add: [
+        "codex",
+        "mcp",
+        "add",
+        ...envFlags("--env", s.env),
+        s.name,
+        "--",
+        s.command,
+        ...s.args,
+      ],
+      check: ["codex", "mcp", "get", s.name],
+    }),
+  },
+  {
+    id: "cursor",
+    title: "Cursor",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("cursor") || e.exists(path.join(e.home, ".cursor")),
+    plan: (s, scope, e) =>
+      json(
+        path.join(
+          scope === "project" ? e.projectDir : e.home,
+          ".cursor",
+          "mcp.json",
+        ),
+        s,
+      ),
+  },
+  {
+    id: "vscode",
+    title: "VS Code (Copilot agent)",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("code"),
+    plan: (s, scope, e) =>
+      scope === "project"
+        ? json(path.join(e.projectDir, ".vscode", "mcp.json"), s, "servers", {
+            type: "stdio",
+            ...stdioEntry(s),
+          })
+        : {
+            kind: "exec",
+            add: [
+              "code",
+              "--add-mcp",
+              JSON.stringify({ name: s.name, type: "stdio", ...stdioEntry(s) }),
+            ],
+          },
+  },
+  {
+    id: "claude-desktop",
+    title: "Claude Desktop",
+    scopes: ["user"],
+    detect: (e) => e.exists(appSupport(e, "Claude")),
+    plan: (s, _scope, e) =>
+      json(path.join(appSupport(e, "Claude"), "claude_desktop_config.json"), s),
+  },
+  {
+    id: "windsurf",
+    title: "Windsurf",
+    scopes: ["user"],
+    detect: (e) =>
+      e.which("windsurf") ||
+      e.exists(path.join(e.home, ".codeium", "windsurf")),
+    plan: (s, _scope, e) =>
+      json(path.join(e.home, ".codeium", "windsurf", "mcp_config.json"), s),
+  },
+  {
+    id: "gemini",
+    title: "Gemini CLI",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("gemini"),
+    plan: (s, scope, e) =>
+      json(
+        path.join(
+          scope === "project" ? e.projectDir : e.home,
+          ".gemini",
+          "settings.json",
+        ),
+        s,
+      ),
+  },
+];
+
+export function findClient(id: string): McpClient | undefined {
+  return MCP_CLIENTS.find((c) => c.id === id);
+}
+
+/** The PATH a launched server needs: node's own directory first. */
+export function serverPath(nodeBinDir: string, platform: NodeJS.Platform) {
+  const base =
+    platform === "win32"
+      ? []
+      : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+  return [nodeBinDir, ...base.filter((d) => d !== nodeBinDir)].join(
+    platform === "win32" ? ";" : ":",
+  );
+}
+
+/** The server this distribution registers. */
+export function serverSpec(o: {
+  cli: string;
+  distRoot: string;
+  nodeBinDir: string;
+  platform: NodeJS.Platform;
+  port?: number;
+}): ServerSpec {
+  return {
+    name: o.cli,
+    command: path.join(o.distRoot, "bin", o.cli),
+    args: ["mcp", ...(o.port !== undefined ? ["--port", String(o.port)] : [])],
+    env: { PATH: serverPath(o.nodeBinDir, o.platform) },
+  };
+}
+
+// ── JSON configs ────────────────────────────────────────────────────────────
+
+/**
+ * `text` (a client's config file, or null when absent) with `name` set under
+ * `key`. Refuses to rewrite a file it cannot parse: a client's config is the
+ * developer's, and clobbering it loses their other servers.
+ */
+export function mergeJsonConfig(
+  text: string | null,
+  key: string,
+  name: string,
+  entry: Record<string, unknown> | null,
+): string {
+  let doc: Record<string, unknown> = {};
+  if (text !== null && text.trim()) {
+    try {
+      doc = JSON.parse(text) as Record<string, unknown>;
+    } catch (e) {
+      throw new Error(
+        `not valid JSON (${(e as Error).message}); fix it or add the server by hand`,
+      );
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+      throw new Error("not a JSON object; add the server by hand");
+  }
+  const servers =
+    doc[key] && typeof doc[key] === "object" && !Array.isArray(doc[key])
+      ? { ...(doc[key] as Record<string, unknown>) }
+      : {};
+  if (entry === null) delete servers[name];
+  else servers[name] = entry;
+  return `${JSON.stringify({ ...doc, [key]: servers }, null, 2)}\n`;
+}
+
+/** Whether a JSON config already registers `name` with this entry. */
+export function jsonHasEntry(
+  text: string | null,
+  key: string,
+  name: string,
+  entry: Record<string, unknown>,
+): "connected" | "different" | "absent" {
+  if (!text) return "absent";
+  try {
+    const doc = JSON.parse(text) as Record<string, Record<string, unknown>>;
+    const have = doc?.[key]?.[name];
+    if (have === undefined) return "absent";
+    return JSON.stringify(have) === JSON.stringify(entry)
+      ? "connected"
+      : "different";
+  } catch {
+    return "absent";
+  }
+}
+
+/** A generic snippet for any other MCP client. */
+export function genericSnippet(spec: ServerSpec): string {
+  return JSON.stringify(
+    { mcpServers: { [spec.name]: stdioEntry(spec) } },
+    null,
+    2,
+  );
+}