@monster-orange/den 0.2.0 → 0.2.1

package/src/ui/cli/mcp-connect.ts

@@ -0,0 +1,350 @@
+/**
+ * `<cli> mcp connect | disconnect | clients | config`: register this
+ * distribution's MCP server with a developer's agents. Planning lives in
+ * ../mcp/connect.ts; this file does the I/O.
+ */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import chalk from "chalk";
+import {
+  MCP_CLIENTS,
+  findClient,
+  genericSnippet,
+  jsonHasEntry,
+  mergeJsonConfig,
+  serverSpec,
+  type ConnectAction,
+  type ConnectEnv,
+  type McpClient,
+  type Scope,
+  type ServerSpec,
+} from "../mcp/connect.js";
+import { product } from "../../shared/product.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { readWebPort } from "../../shared/edge/config.js";
+import { DEFAULT_PORT } from "../../shared/constants.js";
+import { readMcpConfig } from "../../shared/den-config.js";
+
+export const MCP_CONNECT_SUBCOMMANDS = [
+  "connect",
+  "disconnect",
+  "clients",
+  "config",
+] as const;
+
+function onPath(bin: string): boolean {
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".EXE;.CMD").split(";")
+      : [""];
+  for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      try {
+        fs.accessSync(path.join(dir, bin + ext), fs.constants.X_OK);
+        return true;
+      } catch {
+        /* next */
+      }
+    }
+  }
+  return false;
+}
+
+function connectEnv(projectDir: string): ConnectEnv {
+  return {
+    home: os.homedir(),
+    platform: process.platform,
+    appData: process.env.APPDATA,
+    projectDir,
+    which: onPath,
+    exists: (p) => fs.existsSync(p),
+  };
+}
+
+interface Flags {
+  clients: string[];
+  all: boolean;
+  project: string | null;
+  port?: number;
+  dryRun: boolean;
+}
+
+function parseFlags(argv: string[]): Flags {
+  const f: Flags = { clients: [], all: false, project: null, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--all" || a === "-a") f.all = true;
+    else if (a === "--dry-run" || a === "-n") f.dryRun = true;
+    else if (a === "--project" || a === "-p") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-") && !findClient(next)) {
+        f.project = path.resolve(next);
+        i++;
+      } else f.project = process.env.DEN_INVOKE_CWD ?? process.cwd();
+    } else if (a === "--port") {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n < 1 || n > 65535)
+        throw new Error(`--port must be a port number`);
+      f.port = n;
+    } else if (a.startsWith("-")) throw new Error(`unknown flag ${a}`);
+    else f.clients.push(a);
+  }
+  return f;
+}
+
+function spec(port?: number): ServerSpec {
+  const cli = product().cli;
+  const s = serverSpec({
+    cli,
+    distRoot: getDistRoot(),
+    nodeBinDir: path.dirname(process.execPath),
+    platform: process.platform,
+    port,
+  });
+  if (!fs.existsSync(s.command))
+    throw new Error(
+      `${s.command} does not exist: run this from a distribution with a bin/${cli} shim`,
+    );
+  return s;
+}
+
+const show = (argv: string[]): string =>
+  argv.map((a) => (/^[\w./:=@-]+$/.test(a) ? a : `'${a}'`)).join(" ");
+
+function run(argv: string[]): { code: number; out: string } {
+  const r = spawnSync(argv[0], argv.slice(1), { encoding: "utf-8" });
+  return {
+    code: r.status ?? 1,
+    out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim(),
+  };
+}
+
+function readText(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Write `text` to `file` atomically, keeping the previous copy as .bak. */
+function writeConfig(file: string, text: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak`);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, file);
+}
+
+function apply(
+  a: ConnectAction,
+  remove: boolean,
+  dryRun: boolean,
+): { ok: boolean; said: string } {
+  if (a.kind === "json") {
+    const before = readText(a.file);
+    const after = mergeJsonConfig(
+      before,
+      a.key,
+      a.name,
+      remove ? null : a.entry,
+    );
+    if (!dryRun) writeConfig(a.file, after);
+    return {
+      ok: true,
+      said: `${dryRun ? "would write" : remove ? "removed from" : "wrote"} ${a.file}`,
+    };
+  }
+  if (remove) {
+    if (!a.remove)
+      return {
+        ok: false,
+        said: "remove it from the client's own MCP settings",
+      };
+    if (dryRun) return { ok: true, said: `would run ${show(a.remove)}` };
+    const r = run(a.remove);
+    return { ok: r.code === 0, said: r.out || show(a.remove) };
+  }
+  if (dryRun) return { ok: true, said: `would run ${show(a.add)}` };
+  if (a.remove) run(a.remove);
+  const r = run(a.add);
+  return {
+    ok: r.code === 0,
+    said:
+      r.code === 0 ? `ran ${a.add[0]} ${a.add.slice(1, 3).join(" ")}` : r.out,
+  };
+}
+
+function status(
+  c: McpClient,
+  s: ServerSpec,
+  scope: Scope,
+  env: ConnectEnv,
+): string {
+  const a = c.plan(s, scope, env);
+  if (a.kind === "json") {
+    const st = jsonHasEntry(readText(a.file), a.key, a.name, a.entry);
+    return st === "connected"
+      ? chalk.green("connected")
+      : st === "different"
+        ? chalk.yellow("connected (different command: reconnect)")
+        : chalk.gray("not connected");
+  }
+  if (!a.check) return chalk.gray("unknown (check the client's MCP list)");
+  return run(a.check).code === 0
+    ? chalk.green("connected")
+    : chalk.gray("not connected");
+}
+
+async function webServerLine(port?: number): Promise<string> {
+  let p = port;
+  if (p === undefined) {
+    try {
+      p = readWebPort();
+    } catch {
+      p = DEFAULT_PORT;
+    }
+  }
+  const url = `http://localhost:${p}`;
+  try {
+    const r = await fetch(`${url}/api/server-info`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    const info = (await r.json()) as { version?: string };
+    return (
+      chalk.green(`web server up at ${url}`) +
+      (info.version ? chalk.gray(` (Den ${info.version})`) : "")
+    );
+  } catch {
+    return chalk.yellow(
+      `web server not running at ${url}: agents get read errors until \`${product().cli} web up\``,
+    );
+  }
+}
+
+function usage(): string {
+  const cli = product().cli;
+  return [
+    `Usage:`,
+    `  ${cli} mcp clients                       which agents are installed and connected`,
+    `  ${cli} mcp connect [<client>...|--all]   register ${cli}'s MCP server (user scope)`,
+    `        [--project [dir]]                  in a project's config instead (default: here)`,
+    `        [--port <n>] [--dry-run]`,
+    `  ${cli} mcp disconnect <client>... [--project [dir]]`,
+    `  ${cli} mcp config [--port <n>]           JSON for any other MCP client`,
+    ``,
+    `Clients: ${MCP_CLIENTS.map((c) => c.id).join(", ")}`,
+  ].join("\n");
+}
+
+export async function runMcpConnect(argv: string[]): Promise<number> {
+  const [sub, ...rest] = argv;
+  if (rest.includes("-h") || rest.includes("--help")) {
+    console.log(usage());
+    return 0;
+  }
+  let flags: Flags;
+  try {
+    flags = parseFlags(rest);
+  } catch (e) {
+    console.error(chalk.red(`${(e as Error).message}\n`) + usage());
+    return 1;
+  }
+  const s = spec(flags.port);
+  const scope: Scope = flags.project ? "project" : "user";
+  const env = connectEnv(
+    flags.project ?? process.env.DEN_INVOKE_CWD ?? process.cwd(),
+  );
+
+  if (sub === "config") {
+    console.log(genericSnippet(s));
+    return 0;
+  }
+
+  if (sub === "clients") {
+    console.log(
+      chalk.bold(
+        `\n  ${product().title} MCP server: ${s.command} ${s.args.join(" ")}`,
+      ),
+    );
+    console.log(`  ${await webServerLine(flags.port)}`);
+    const actions = readMcpConfig().actions;
+    console.log(
+      chalk.gray(
+        `  tools: read${actions.length ? ` + actions ${actions.join(", ")}` : " only (mcp.actions is empty)"}\n`,
+      ),
+    );
+    for (const c of MCP_CLIENTS) {
+      const here = c.detect(env);
+      const st =
+        here && c.scopes.includes(scope)
+          ? status(c, s, scope, env)
+          : chalk.gray(here ? `no ${scope} scope` : "not installed");
+      console.log(
+        `  ${here ? "●" : "○"} ${c.id.padEnd(15)} ${c.title.padEnd(24)} ${st}`,
+      );
+    }
+    console.log(
+      chalk.gray(
+        `\n  Connect: ${product().cli} mcp connect <client>   (or --all for every installed one)\n`,
+      ),
+    );
+    return 0;
+  }
+
+  if (sub !== "connect" && sub !== "disconnect") {
+    console.log(usage());
+    return 1;
+  }
+  const remove = sub === "disconnect";
+  let targets: McpClient[];
+  if (flags.all)
+    targets = MCP_CLIENTS.filter(
+      (c) => c.detect(env) && c.scopes.includes(scope),
+    );
+  else {
+    const unknown = flags.clients.filter((id) => !findClient(id));
+    if (unknown.length) {
+      console.error(
+        chalk.red(`unknown client: ${unknown.join(", ")}\n`) + usage(),
+      );
+      return 1;
+    }
+    targets = flags.clients.map((id) => findClient(id)!);
+  }
+  if (targets.length === 0) {
+    console.log(usage());
+    return 1;
+  }
+
+  let failed = 0;
+  for (const c of targets) {
+    if (!c.scopes.includes(scope)) {
+      console.log(`  ${chalk.yellow("•")} ${c.title}: no ${scope} scope`);
+      failed++;
+      continue;
+    }
+    try {
+      const r = apply(c.plan(s, scope, env), remove, flags.dryRun);
+      console.log(
+        `  ${r.ok ? chalk.green("✓") : chalk.red("✗")} ${c.title}: ${r.said}`,
+      );
+      if (!r.ok) failed++;
+    } catch (e) {
+      console.log(`  ${chalk.red("✗")} ${c.title}: ${(e as Error).message}`);
+      failed++;
+    }
+  }
+  if (!remove && !flags.dryRun && failed < targets.length) {
+    console.log(
+      chalk.gray(
+        `\n  Restart the agent (or start a new session) to load "${s.name}".`,
+      ),
+    );
+    console.log(`  ${await webServerLine(flags.port)}\n`);
+  }
+  return failed ? 1 : 0;
+}

package/src/ui/cli/named-target.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether `address` ("repo" or "repo/service") is something the user named on
+ * the command line: the address itself, or the repo it belongs to.
+ */
+export function isNamedTarget(
+  address: string,
+  named: readonly string[],
+): boolean {
+  const repo = address.split("/")[0];
+  return named.some((n) => n === address || n === repo);
+}

package/src/ui/mcp/api.ts

@@ -58,6 +58,8 @@ const READ_ROUTES = new Set([
 
 /** 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",

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,
+  );
+}

package/src/ui/mcp/guards.ts

@@ -61,7 +61,10 @@ export function runsLocally(entry: ServiceEntryLike): boolean {
   return entry.commands.includes("up");
 }
 
-export function assertRunsLocally(entry: ServiceEntryLike): void {
+export function assertRunsLocally(
+  entry: ServiceEntryLike,
+  command: string = "up",
+): void {
   const address = `${entry.repo ?? "?"}/${entry.service ?? "?"}`;
   if (entry.runs === "remote")
     throw new Refusal(
@@ -69,7 +72,8 @@ export function assertRunsLocally(entry: ServiceEntryLike): void {
         address,
         { runs: "remote", target: entry.target ?? null },
         (e) => isProductionEnv(e),
-      ) ?? `${address} runs remotely; nothing to start here`,
+        command,
+      ) ?? `${address} runs remotely; nothing to ${command} here`,
     );
   if (!runsLocally(entry))
     throw new Refusal(

package/src/ui/mcp/server.ts

@@ -119,6 +119,8 @@ export const MCP_USAGE = (cli: string): string =>
     `An MCP server over stdio for agents, a client of the running web server`,
     `(\`${cli} web up\`; default port: config web.port). Read tools always;`,
     "actions only as named in the org config's mcp.actions. See docs/distributions.md.",
+    "",
+    `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
 /** Run `<cli> mcp` until stdin closes. */