@monster-orange/den 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.2.1] - 2026-11-04
+
+### Fixed
+
+- **MCP `service_restart` on a service with only `up` and `down`.**
+  `/api/service/exec` now runs `up`, `down` and `restart` (env local) through
+  the service runner, as `<cli> up|down|restart` do, instead of looking up
+  and executing the manifest's command itself. So, for the web UI's panel and
+  for MCP alike: `restart` with no declared `restart` is `down` then `up`;
+  `up` on a service that is already healthy starts nothing and says
+  `already up (healthy)`; `up` attaches to a running shared instance; `down`
+  honours workspace ownership. The panel offers Restart whenever a service has
+  `up` and `down`.
+- **A detached start says when it is ready.** `/api/service/exec` sends a
+  `ready` event once a detached `up` or `restart` is up: its health check
+  passes (`checked: true`; for a restart, only after the old instance went
+  down or 5s passed), or, with no health check, its launcher is still running
+  after 5s (`checked: false`). MCP `service_up` and `service_restart` return
+  at `ready` (`"ready": true` in the result) instead of waiting for a
+  launcher that runs in the foreground (a dev server) to exit, which ran
+  into the 180s timeout and reported a false failure. A restart of a running
+  shared instance now says `restarting the running instance`, not
+  `already running`, and the log path is printed once. An MCP action's
+  `ended` reads `ready` or `handed-off` for a detached start, never
+  `stopped`.
+- **MCP actions report failure.** `service_up|down|restart`, `run_tests` and
+  `workspace_sync` return `isError` with `"failed": true` in the result when
+  the command exits non-zero, a detached service's launcher exits non-zero,
+  or the call times out. They used to come back ok with `exitCode: 1` inside.
+- **`<cli> up|down|restart <remote service>` exits 1.** Naming a remote
+  service (or its repo) directly is a refused command. A remote service
+  reached through a workspace, `-a` or `-A <app>` run is still said and
+  skipped, exit 0.
+- **Refusals name the command.** `runs in dev (AWS); nothing to restart here`
+  (and `stop`, `start`, `run "<cmd>" on`), not `start` for everything.
+
+### Added
+
+- **`<cli> mcp connect`: register the MCP server with your agents.**
+  `mcp clients` lists the agents installed here (Claude Code, Codex, Cursor,
+  VS Code, Claude Desktop, Windsurf, Gemini CLI) and whether each is
+  connected. `mcp connect <client>...|--all` registers the distribution's
+  server at user scope through each client's own CLI or config file, and
+  `--project [dir]` writes a project's config instead. `--dry-run` shows the
+  change, `mcp disconnect` removes it, and `mcp config` prints JSON for any
+  other client. The registration pins `PATH` to the running node so GUI
+  agents can launch it. See "Connecting your agents" in
+  `docs/distributions.md`.
+- **Refused attempts are in the activity trail.** `/api/activity` entries may
+  carry `outcome: "refused"` and a `reason`: a refused or unresolvable
+  `/api/service/exec`, and any MCP action a guard refused before it reached
+  the web server. Agents report the latter to `POST /api/activity` (agent
+  audit header required; it appends one sanitised entry and nothing else).
+  The panel's Activity tab shows them as refused. An attempt that named only
+  the repo shows for the repo and for each of its services.
+- **`target.expect` in placement.** `/api/services` and `/api/health` rows'
+  `target` now carry `expect` (as declared) when the manifest's target has its
+  own `url`.
+
+### Migrations
+
+- None required. Two additive API changes a contract probe may see:
+  `target.expect` on `/api/services` and `/api/health` rows, and
+  `outcome`/`reason` on `/api/activity` entries.
+- Scripts that relied on `<cli> restart|down <remote service>` exiting 0
+  should expect 1.
+
 ## [0.2.0] - 2026-11-04
 
 ### Added

package/bin/den

@@ -41,8 +41,9 @@ if [ "${1:-}" = "create" ]; then
   built="dist/src/ui/cli/create-main.js"
 fi
 # `mcp` speaks the MCP protocol on stdout: its own entry point, so nothing
-# the full CLI prints can reach the protocol stream.
-if [ "${1:-}" = "mcp" ]; then
+# the full CLI prints can reach the protocol stream. Its setup subcommands
+# (connect, disconnect, clients, config) are ordinary CLI commands.
+if [ "${1:-}" = "mcp" ] && ! case "${2:-}" in connect|disconnect|clients|config) true ;; *) false ;; esac; then
   shift
   entry="src/ui/cli/mcp-main.ts"
   built="dist/src/ui/cli/mcp-main.js"

package/docs/distributions.md

@@ -367,17 +367,45 @@ answers 404, the MCP server reads the web server's version from
 `web server is Den 0.1.0; stacks needs >= 0.2.0: run acme web restart`. Any
 other 404 is reported as it is.
 
-Register it with a client as a stdio server, for example:
-
-```json
-{
-  "mcpServers": {
-    "acme": { "command": "/path/to/acme/bin/acme", "args": ["mcp"] }
-  }
-}
+### Connecting your agents
+
+`<cli> mcp connect` registers the server with the agents you use, so nobody
+edits an MCP config by hand:
+
+```sh
+./bin/acme mcp clients                 # which agents are installed, which are connected
+./bin/acme mcp connect --all           # every installed agent, user scope
+./bin/acme mcp connect claude-code     # one (or several) by id
+./bin/acme mcp connect cursor --project ../shop   # a project's config instead
+./bin/acme mcp connect --all --dry-run # show what it would write or run
+./bin/acme mcp disconnect cursor
+./bin/acme mcp config                  # JSON for any other MCP client
 ```
 
-`--port <n>` points it at a web server on another port.
+| Client           | User scope                            | Project scope (`--project [dir]`) |
+| ---------------- | ------------------------------------- | --------------------------------- |
+| `claude-code`    | `claude mcp add --scope user`         | `<dir>/.mcp.json`                 |
+| `codex`          | `codex mcp add`                       | –                                 |
+| `cursor`         | `~/.cursor/mcp.json`                  | `<dir>/.cursor/mcp.json`          |
+| `vscode`         | `code --add-mcp`                      | `<dir>/.vscode/mcp.json`          |
+| `claude-desktop` | its `claude_desktop_config.json`      | –                                 |
+| `windsurf`       | `~/.codeium/windsurf/mcp_config.json` | –                                 |
+| `gemini`         | `~/.gemini/settings.json`             | `<dir>/.gemini/settings.json`     |
+
+The server is registered under the CLI's name (`acme`) as the distribution's
+`bin/<cli>` by absolute path, with `PATH` set to the directory of the `node`
+that ran `connect` plus the system dirs. GUI agents start without your login
+shell's PATH (so without nvm's node) and would otherwise fail to launch it.
+After upgrading or switching node, run `connect` again. For a JSON config,
+`connect` changes only its own entry, keeps the previous file as `.bak`, and
+refuses to rewrite a file it cannot parse. Connecting again replaces the entry.
+Restart the agent, or start a new session, to load it.
+
+Project-scope files hold absolute paths on your machine: commit them only if
+everyone's checkout is in the same place.
+
+`--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
+port.
 
 ### Config
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/environment-manager/service-runner.ts

@@ -1063,7 +1063,7 @@ export function runServiceCommand(
     resolved.address,
     servicePlacement(readManifest(repoPath), subsystem, "local"),
     (e) => isProductionEnv(e) === true,
-    command === "down" ? "stop" : "start",
+    command,
   );
   if (refusal) {
     onLine(refusal);
@@ -1094,7 +1094,9 @@ export function runServiceCommand(
         workspace,
       ];
       onLine(
-        `already running (shared) — owners: [${owners.join(", ")}] at ${resolved.repoPath}`,
+        command === "restart"
+          ? `restarting the running instance (shared) — owners: [${owners.join(", ")}] at ${resolved.repoPath}`
+          : `already running (shared) — owners: [${owners.join(", ")}] at ${resolved.repoPath}`,
       );
       // restart still needs to bounce; only short-circuit pure `up`.
       if (command === "up") {

package/src/shared/manifest/placement.ts

@@ -34,6 +34,8 @@ export interface PlacementTarget {
   env: string;
   account?: string;
   url?: string;
+  /** The status codes that count as up for `url`, as declared. */
+  expect?: number | number[];
 }
 
 export interface Placement {
@@ -84,6 +86,7 @@ function targetFor(svc: ServiceManagementConfig, env: string): PlacementTarget {
     env: tEnv,
     ...(own?.account ? { account: own.account } : {}),
     ...(url ? { url } : {}),
+    ...(own?.url && own.expect !== undefined ? { expect: own.expect } : {}),
   };
 }
 
@@ -186,16 +189,25 @@ export function isProtectedRemote(p: Placement, isProduction: IsProduction) {
   return p.runs === "remote" && !!p.target && isProduction(p.target.env);
 }
 
+/** How a refusal names the command: up → "start", exec → `run "exec" on`. */
+function refusedVerb(command: string): string {
+  if (command === "up" || command === "start") return "start";
+  if (command === "down" || command === "stop") return "stop";
+  if (command === "restart") return "restart";
+  return `run "${command}" on`;
+}
+
 /**
- * Why Den must not run a command on `address`, or null. Every command on a
- * remote service is refused ("runs in dev (AWS); nothing to start here").
+ * Why Den must not run `command` on `address`, or null. Every command on a
+ * remote service is refused ("runs in dev (AWS); nothing to restart here").
  */
 export function placementRefusal(
   address: string,
   p: Placement,
   isProduction: IsProduction,
-  verb: "start" | "stop" = "start",
+  command = "up",
 ): string | null {
+  const verb = refusedVerb(command);
   if (p.runs !== "remote") return null;
   const where = p.target
     ? `${p.target.env}${p.target.account ? ` (${p.target.account})` : ""}`

package/src/ui/cli/index.ts

@@ -5,6 +5,7 @@
  * Main entry point for the interactive CLI
  */
 
+import { isNamedTarget } from "./named-target.js";
 import chalk from "chalk";
 import oraSpinner from "ora";
 
@@ -695,6 +696,17 @@ class DenCLI {
           break;
 
         case "mcp": {
+          // Setup subcommands: register the server with agents.
+          const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
+            await import("./mcp-connect.js");
+          if (
+            (MCP_CONNECT_SUBCOMMANDS as readonly string[]).includes(
+              args[1] ?? "",
+            )
+          ) {
+            process.exitCode = await runMcpConnect(args.slice(1));
+            break;
+          }
           // bin/den routes `mcp` to its own entry (stdout is the protocol);
           // this covers the CLI run directly from a checkout.
           await import("./mcp-stdout-guard.js");
@@ -1298,7 +1310,15 @@ class DenCLI {
       /** Skip ANY already-healthy node (derived `up` starts only what's down). */
       skipHealthyAll?: boolean;
     },
-    opts?: { force?: boolean },
+    opts?: {
+      force?: boolean;
+      /**
+       * What the user named on the command line (repo or address). A remote
+       * service among them is refused with a non-zero exit; one reached only
+       * as part of a workspace or app run is said and skipped.
+       */
+      named?: readonly string[];
+    },
   ): Promise<void> {
     // How long to show startup output before handing control back to the menu
     // for detachable (long-running) commands like `up`.
@@ -1388,11 +1408,16 @@ class DenCLI {
               "local",
             ),
             (e) => isProductionEnv(e),
-            command === "down" ? "stop" : "start",
+            command,
           )
         : null;
       if (remote) {
-        console.log(chalk.gray(`  • ${remote}`));
+        if (isNamedTarget(address, opts?.named ?? [])) {
+          console.log(chalk.red(`  ✗ ${remote}`));
+          process.exitCode = 1;
+        } else {
+          console.log(chalk.gray(`  • ${remote}`));
+        }
         continue;
       }
       if (command === "up" && !seedAddresses.has(address)) {
@@ -1732,6 +1757,7 @@ class DenCLI {
     plan = false,
     pull = false,
   ): Promise<void> {
+    const named = [seed];
     const full = deriveGraph({ scope: "all" });
     // Same positional closure the web "up with deps" uses: everything the seed
     // sits ON TOP OF, never anything above it. Keeps the two entry points from
@@ -1813,12 +1839,17 @@ class DenCLI {
       );
       return;
     }
-    await this.runServicesCommand(order, "up", {
+    await this.runServicesCommand(
       order,
-      waitDepsFor: (address) => hardDepsOf(graph, address),
-      failFast: true,
-      skipHealthyAll: true,
-    });
+      "up",
+      {
+        order,
+        waitDepsFor: (address) => hardDepsOf(graph, address),
+        failFast: true,
+        skipHealthyAll: true,
+      },
+      { named },
+    );
   }
 
   /**
@@ -1874,7 +1905,12 @@ class DenCLI {
       console.log(chalk.gray("  (--dry-run: not stopping anything)\n"));
       return;
     }
-    await this.runServicesCommand(order, "down", { order }, { force });
+    await this.runServicesCommand(
+      order,
+      "down",
+      { order },
+      { force, named: [seed] },
+    );
   }
 
   /** Workspace repos with no runtime (modules, libraries) → their kind. */
@@ -2392,7 +2428,9 @@ class DenCLI {
       return;
     }
     preflightSecrets();
-    await this.runServicesCommand(targets, "up");
+    await this.runServicesCommand(targets, "up", undefined, {
+      named: addresses,
+    });
   }
 
   private async cmdServiceDown(args: string[]): Promise<void> {
@@ -2452,7 +2490,10 @@ class DenCLI {
       addresses.length > 0
         ? addresses
         : this.resolveNoArgServiceTargets("down");
-    await this.runServicesCommand(targets, "down", undefined, { force });
+    await this.runServicesCommand(targets, "down", undefined, {
+      force,
+      named: addresses,
+    });
   }
 
   private async cmdServiceRestart(argv: string[]): Promise<void> {
@@ -2471,7 +2512,9 @@ class DenCLI {
       filtered.length > 0
         ? filtered
         : this.resolveNoArgServiceTargets("restart");
-    await this.runServicesCommand(addresses, "restart");
+    await this.runServicesCommand(addresses, "restart", undefined, {
+      named: filtered,
+    });
   }
 
   /** Service address with a ⏸ marker when the repo is auto-start off. */