@monster-orange/den 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,162 @@ 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.2] - 2026-11-04
+
+### Added
+
+- **`<cli> service install | status | print | uninstall`**: the web UI's
+  launchd service, over `service/install.sh`, so a distribution no longer
+  wraps the script in its Makefile. The label and log directory are
+  `web.service: { label, logs }` in the org config; the defaults are the
+  script's own (`local.<distribution dir name>.web`,
+  `~/Library/Logs/<distribution dir name>`), so an existing install keeps its
+  label. A bad label, a non-path `logs` or an unknown key under `web.service`
+  is an error. `install` (which also restarts) says `running` only once
+  `/api/server-info` answers with JSON, and after 30s without an answer says
+  `installed but not answering yet: check <logs dir>` and exits 1. `print`
+  writes the plist only, on any OS. See "Running the web UI as a service" in
+  `docs/distributions.md`.
+- **`<cli> mcp --call <tool> ['<json args>']` and `<cli> mcp --list`.** One
+  tool call from a shell, through the same tool layer as the MCP server
+  (registered tools only, so actions only as named in `mcp.actions`; every
+  guard; redaction; audit headers), against the running web server. Prints
+  the tool's text to stdout and exits 1 when the tool reports an error.
+  `--list` prints the tool names.
+- **Service aliases.** `up`, `down`, `restart` and `logs` (and every caller
+  of the service resolver, so `/api/service/exec` too) accept a service's
+  manifest key or a compose stack's name, when it names exactly one service
+  in the workspace: `<cli> restart indexer` restarts the repo whose service
+  or stack is `indexer`. Repo names and listed addresses win over an alias.
+  An ambiguous alias is an error naming the candidates (`"worker" is
+  ambiguous in workspace "default": one/worker, two/worker`). See "Naming a
+  service" in `docs/distributions.md`.
+- **`validate` flags a redundant held manifest.** When a repo carries its own
+  manifest and the distribution still holds `manifests/<repo>.<name>.yml`,
+  `validate` warns (never an error) that the held file is not used and can be
+  deleted, or turned into `manifests/<repo>.override.yml`.
+
+### Fixed
+
+- **`-n`/`--dry-run` and `--plan` run nothing on every path.** Given a
+  `repo/service` address or an alias, `up` and `down` ignored them and
+  really ran the service (and its dependencies); they now print the order
+  they would run and stop. `restart` accepts `-n`/`--dry-run` too. Tested
+  for each way to name a target: the cwd repo, a repo, an address, an alias,
+  a compose stack name and an app.
+- **A dry run says what the real run does**, per target: the same command
+  lookup (own command, restart as down + up, a repo-started service's
+  repo up, nothing to stop, not found), so a dry run fails where the real
+  run would. Every dry run names its targets (`Would down: …`).
+- **`down` and `restart` on named services act on those services only.**
+  They took the services' dependencies down (or restarted them) too, even
+  ones other running services still use. `up` still starts dependencies;
+  `down <repo>` still stops the repo's closure, naming what else depends on
+  it.
+- **`down <repo>` stops that repo only.** It stopped the repo's whole
+  derived closure, so `down api` took down stacks it sits on that other
+  running systems use. `--with-deps` keeps the old behaviour (naming what
+  else uses them); `down -a` still stops everything.
+- **Plans show remote services as skipped, with the reason**
+  (`core (remote, skipped): core runs in dev; …`), and a named remote target
+  fails with the real run's reason.
+- **A compose sub-service restarts on its own**: `restart <repo>/<svc>` runs
+  `docker compose restart <svc>` in its stack (`<cli> stack restart <stack>
+  --service <svc>`): the same container and env, nothing recreated. Up and
+  down stay the stack's.
+- **A service its repo starts**: `down` on it says it is stopped by the
+  repo's down and names the command (exit 0, so a workspace Down that sends
+  every service stays clean); `restart` fails the same way, exit 1.
+- **`down` of a remote repo no longer warns about its dependents**: it stops
+  nothing, so nothing is at risk. Only targets that really stop here count.
+- **A failed or unknown target exits 1.** `up`, `down` and `restart` exited 0
+  when a named service failed or did not exist.
+- **A service with no commands of its own** (its repo's up starts it): `up`
+  runs the repo's up and says so, instead of `command "up" not found`; other
+  commands point at the repo, since they would reach its other services.
+- **`service status`** no longer prints launchctl's errors when the service
+  is not loaded.
+
+### Migrations
+
+- None required.
+- `down <repo/service>` and `restart <repo/service>` no longer touch the
+  service's dependencies; stop or restart those by name.
+- `down <repo>` (and a bare `down` in a repo) stops only that repo; add
+  `--with-deps` for its closure.
+- A Makefile target that runs `service/install.sh` with `DEN_SERVICE_LABEL`
+  and `DEN_SERVICE_LOGS` can become `<cli> service install`; put a non-default
+  label or log directory in `web.service` first, since the CLI reads the
+  config, not those env vars.
+- Delete held manifests `validate` now reports as unused.
+
+## [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/README.md

@@ -133,7 +133,7 @@ provider in `src/shared/auth/token-providers/`.
 
 ```bash
 den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
-den down [repo]        # stop it cleanly
+den down [repo]        # stop it cleanly (--with-deps: and what it sits on)
 den status             # service health for the active workspace
 den apps               # Org > Application > Repo > Services
 den graph [repo]       # the derived dependency graph

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

@@ -109,6 +109,23 @@ The web UI's Services cards show the layers each manifest was built from
 `manifestLayers`, e.g. `["held", "override"]`. `DEN_MANIFESTS_DIR` points the
 held and override lookup at another directory (tests use it).
 
+Once a repo carries its own manifest, a held `manifests/<repo>.acme.yml` is
+never read. `validate` says so, as a warning (not an error), naming the held
+file: delete it, or keep only what this distribution changes as
+`manifests/<repo>.override.yml`.
+
+## Naming a service
+
+`up`, `down`, `restart` and `logs` take a repo name (`shop`) or a
+`repo/service` address (`shop/api`). A service's manifest key (`api`) or a
+compose stack's name (`compose.name`, else the manifest's `name`) works too,
+when it names exactly one service in the workspace: a stack stands for its
+repo, so `<cli> restart search` restarts the repo whose stack is `search`.
+Repo names and listed addresses always win over an alias, so a catalog repo
+is never mistaken for another repo's service. An alias that names more than
+one service is an error that lists them (`"worker" is ambiguous in workspace
+"default": one/worker, two/worker`); name one of them.
+
 ## Placement
 
 Each service says where it runs, per environment: `local` (on this machine,
@@ -329,7 +346,40 @@ are the same directory.
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
-it exits. From the distribution root:
+it exits:
+
+```bash
+./bin/acme service install     # install (or refresh) and start it
+./bin/acme service status      # launchd's view: state, pid, last exit code
+./bin/acme service print       # the LaunchAgent plist it would install; installs nothing
+./bin/acme service uninstall   # stop it and remove the LaunchAgent
+```
+
+The label and log directory come from the org config:
+
+```yaml
+web:
+  port: 7777
+  service:
+    label: local.acme.web # default: local.<distribution dir name>.web
+    logs: ~/Library/Logs/acme # default: ~/Library/Logs/<distribution dir name>
+```
+
+The defaults are the installer's own, so an install made by the script keeps
+its label. `logs` may start with `~/`; a relative path is under the
+distribution root. A label other than letters, digits, `.`, `-` and `_`, a
+`logs` that is not a path, or any other key under `web.service` is an error.
+`print` works on any OS; the rest are macOS only.
+
+`install` also restarts a service that is already installed. It says the
+service is running only once the web server answers
+`http://localhost:<web.port>/api/server-info` with JSON (a fresh server
+answers empty for a few seconds while it starts). If it has not answered
+within 30s, it says `installed but not answering yet: check <logs dir>` and
+exits 1.
+
+`<cli> service` runs the installer script below, which you can also run
+yourself, from the distribution root:
 
 ```bash
 DEN_ROOT="$PWD" DEN_SERVICE_LABEL=local.acme.web \
@@ -367,17 +417,59 @@ 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:
+### 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
+```
 
-```json
-{
-  "mcpServers": {
-    "acme": { "command": "/path/to/acme/bin/acme", "args": ["mcp"] }
-  }
-}
+| 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.
+
+### One call from a shell
+
+```sh
+./bin/acme mcp --list                                  # the tool names this org registers
+./bin/acme mcp --call status                           # one tool; prints its text result
+./bin/acme mcp --call logs_tail '{"service":"shop/api","lines":50}'
 ```
 
-`--port <n>` points it at a web server on another port.
+`--call <tool> ['<json args>']` runs one tool through the same tool layer as
+the server: only registered tools (so actions only as named in
+`mcp.actions`), every guard, the same redaction and audit headers. It prints
+the tool's text to stdout and exits 1 when the tool reports an error (a
+refusal, a failed action, the web server down).
 
 ### Config
 

package/package.json

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

package/service/install.sh

@@ -15,6 +15,9 @@
 #
 #   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
 #   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
+#                      caller (`<cli> service install`) checks the server
+#                      answers first.
 set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
@@ -95,7 +98,11 @@ case "${1:-install}" in
     done
     [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $LABEL (plist: $PLIST)" >&2; exit 1; }
     launchctl kickstart -k "$DOMAIN/$LABEL"
-    echo "✓ $LABEL running (logs: $LOGS/web.log)"
+    if [ "${DEN_SERVICE_READY_CHECK:-}" = external ]; then
+      echo "… $LABEL started; waiting for it to answer"
+    else
+      echo "✓ $LABEL running (logs: $LOGS/web.log)"
+    fi
     ;;
   uninstall)
     launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
@@ -106,7 +113,12 @@ case "${1:-install}" in
     write_plist -
     ;;
   status)
-    launchctl print "$DOMAIN/$LABEL" | grep -E '^\s*(state|pid|last exit code|runs)' || echo "$LABEL is not loaded"
+    # launchctl's own "Could not find service" is noise when it isn't loaded.
+    if out="$(launchctl print "$DOMAIN/$LABEL" 2>/dev/null)"; then
+      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs)'
+    else
+      echo "$LABEL is not loaded"
+    fi
     ;;
   *) echo "usage: $0 [install|uninstall|status|print]" >&2; exit 2 ;;
 esac

package/src/shared/den-config.ts

@@ -9,6 +9,7 @@
  */
 
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import * as yaml from "yaml";
 import type { Environment, ReleaseSourceConfig } from "./types/index.js";
@@ -238,6 +239,11 @@ export interface DenConfig {
    * only; `actions` opts in to named actions. See readMcpConfig.
    */
   mcp?: McpConfig;
+  /**
+   * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
+   * the launchd service `<cli> service` installs. See readWebServiceConfig.
+   */
+  web?: WebConfig;
   /**
    * Shared test accounts (email + secrets-backend item per role) the test
    * pillars log in as — see src/shared/auth/test-accounts.ts.
@@ -426,6 +432,7 @@ export function readDenConfig(): DenConfig {
       env_health_urls: parsed?.env_health_urls,
       security: parsed?.security,
       mcp: parsed?.mcp,
+      web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
       secrets: parsed?.secrets,
@@ -602,6 +609,68 @@ export function readMcpConfig(
   };
 }
 
+// ── Web UI service (`<cli> service`) ──────────────────────────────────────────
+
+/** `web:` in the org config. */
+export interface WebConfig {
+  port?: number;
+  /** The launchd service that runs the web UI (`<cli> service install`). */
+  service?: { label?: string; logs?: string };
+}
+
+/** `web.service` with its defaults applied. */
+export interface ResolvedWebService {
+  /** launchd label; also the plist's name in ~/Library/LaunchAgents. */
+  label: string;
+  /** Directory the service's web.log goes to. */
+  logs: string;
+}
+
+const WEB_SERVICE_KEYS = ["label", "logs"];
+
+/**
+ * The web UI's launchd service. The defaults are service/install.sh's own
+ * (`local.<distribution dir name>.web`, `~/Library/Logs/<dir name>`), so an
+ * install made with the script keeps its label. `logs` may start with `~/`;
+ * a relative path is under the distribution root. A bad value throws.
+ */
+export function readWebServiceConfig(
+  config: DenConfig = readDenConfig(),
+  distRoot: string = ROOT,
+  home: string = os.homedir(),
+): ResolvedWebService {
+  const name = path.basename(distRoot);
+  const raw: unknown = config.web?.service;
+  if (
+    raw !== undefined &&
+    (raw === null || typeof raw !== "object" || Array.isArray(raw))
+  )
+    throw new Error("web.service must be a map: { label, logs }");
+  const svc = (raw ?? {}) as Record<string, unknown>;
+  for (const key of Object.keys(svc))
+    if (!WEB_SERVICE_KEYS.includes(key))
+      throw new Error(
+        `web.service: unknown key "${key}" (known: ${WEB_SERVICE_KEYS.join(", ")})`,
+      );
+  const label = svc.label ?? `local.${name}.web`;
+  if (typeof label !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(label))
+    throw new Error(
+      `web.service.label must be letters, digits, dots, dashes and underscores, got "${String(label)}"`,
+    );
+  const logs = svc.logs ?? path.join(home, "Library", "Logs", name);
+  if (typeof logs !== "string" || !logs.trim())
+    throw new Error(
+      `web.service.logs must be a directory path, got "${String(logs)}"`,
+    );
+  const expanded = logs.startsWith("~/")
+    ? path.join(home, logs.slice(2))
+    : logs;
+  return {
+    label,
+    logs: path.isAbsolute(expanded) ? expanded : path.join(distRoot, expanded),
+  };
+}
+
 // ── Release config (Release tab) ──────────────────────────────────────────────
 
 /**