@monster-orange/den 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -4,6 +4,221 @@ 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.7] - 2026-11-05
+
+### Added
+
+- **A workspace belongs to an org** (0.2.7-dev.2, ORG-1a). Its org is
+  `org:` on the workspace in workspaces.yml, else `org:` on the blueprint
+  workspace (`defaults.workspaces.<n>.org`, the one new blueprint key), else
+  the one catalog owner of its repos (case-insensitive; `gh: ""` ignored),
+  else `github_org`, the default org. It is computed on read, never written
+  to workspaces.yml. A config with no `org:` resolves to `github_org` as
+  before, unless all of a workspace's repos have one other owner in the
+  catalog.
+- **`<cli> org list`** (0.2.7-dev.2, ORG-1a): each org's label, its
+  workspaces on this machine, which is the default, and the org warnings.
+  `<cli> workspace list` gains an Org column; `--org <id>` filters it.
+- **Org warnings, never errors** (0.2.7-dev.2, ORG-1a, C1): a workspace
+  whose repos span several owners, an `org:` naming an owner Den does not
+  know, a repo in another owner than its workspace's org, a workspaces.yml
+  `org:` that overrides the blueprint's. Shown by `org list` and
+  `workspace list`.
+- **`<cli> setup --plan`** (0.2.7-dev.2, ORG-1a): each repo's org and clone
+  URL, and whether it is cloned, then stop. On a fresh machine it plans the
+  blueprint's workspaces; once seeded, the focused workspace. `<cli> up
+  --plan` prints the same lines for its repos. Nothing is cloned, seeded or
+  written.
+- **`GET /api/orgs` entries gain `default` and `workspaces`**, and
+  `/api/<cli>/config` gains `default_org` (0.2.7-dev.2, ORG-1a). Every
+  existing field, entry and order is unchanged; `?repos=1` still maps each
+  repo to its owner string.
+- **`<cli> register --org <id>`** (0.2.7-dev.2, ORG-1a) lists another org's
+  repos for a managed clone.
+
+- **Bare `<cli> validate` checks every manifest** (0.2.7-dev.1, from a
+  consumer). In the distribution root, with no argument: each workspace repo
+  once per checkout (own or held, plus any override, then the merge), the
+  held manifest when there is no checkout, and held manifests no workspace
+  uses. One line per repo, details on failure, exit 1 if any fails, nothing
+  cloned. `--held` checks `manifests/` alone, independent of the machine. A
+  path argument works as before.
+
+### Changed
+
+- **A repo is released from its own org** (0.2.7-dev.2, REL-1). With no
+  `release.org`, a repo with no `gh:` in `release.repos` released from
+  `github_org`, so a client org's repo targeted the wrong owner. Its owner
+  is now an explicit `release.org` (unchanged: it still wins for every
+  repo), else the repo's non-empty catalog owner, else `github_org`.
+- **`register` lists the focused workspace's org** (0.2.7-dev.2, ORG-1a),
+  not `github_org` alone, and no longer falls back to the owner of Den's own
+  git remote (SEC-0): with no org it says how to set one.
+
+### Fixed
+
+- **A second root's server leaves the first root's services alone**
+  (0.2.7-dev.3, dev.4). Every root of a product shares one daemons file.
+  A server's two startup sweeps (the stale-daemon prune and the health
+  reaper) dropped any record whose address did not resolve in its own
+  workspaces, so starting a scratch root's server silently forgot another
+  root's running dev server; an interactive Ctrl-C stopped every service in
+  the file, and deactivating a workspace released any record with the same
+  workspace name. Records are now stamped with the root that started them
+  and a server lists, stops, releases and sweeps only its own (other roots'
+  records stay in the file untouched). An older unstamped record is never
+  dropped just for not resolving; it still goes when its containers are
+  verifiably gone or two health checks fail. The reaper now logs what it
+  removes.
+- **A service the edge has no route for is no longer healthy** (0.2.7-dev.2).
+  A health URL served through the edge answered the edge's own
+  `404 page not found` when the service had no route, and Den counted any
+  404 as up. That exact 404 is now down with "no route (edge 404)", over
+  HTTP and HTTPS; a 404 from the service itself is still up.
+- **A client workspace no longer clones from the default org** (0.2.7-dev.2,
+  ORG-1a). Seeding, `up` and the web sync gave a repo with no clone URL
+  `<github_org>/<repo>`; it is now `<org>/<repo>` with its workspace's org.
+- **`<cli> setup` clones a catalog entry with `gh: ""`** from its
+  workspace's org (0.2.7-dev.2), as `up` does, instead of failing on an
+  empty slug.
+- **A seed without a terminal no longer resets a workspace that has
+  entries** (SEED-0). `<cli> init` and `<cli> workspace seed` from a script
+  or `make` replaced every entry of the default (or blueprint) workspaces with
+  managed clones, your own dev-managed checkouts included, without asking.
+  Without a TTY they now refuse (exit 1, nothing written) and name
+  `--reset`; on a TTY they still ask, default No. `init --reset` and
+  `workspace seed --reset` reset as before.
+- **A failed seed leaves the workspaces as they were** (0.2.7-dev.1, from a
+  consumer). Seeding wrote workspaces.yml, then filled the catalog, which
+  fails with no `github_org`: the workspace was reset and nothing could be
+  cloned. The catalog comes first now, and the org is needed only for a repo
+  with no clone URL in the catalog.
+- **A seed refusal names the command that was run** (`init --reset` or
+  `workspace seed --reset`).
+- **A `DEN_ROOT` with no den.yml is a one-line error** (exit 2), not a stack
+  trace from deep in module loading.
+- **Piped output carries no ANSI from tables** (`status`, `services`, test
+  results). cli-table3 coloured borders and head cells itself, ignoring
+  NO_COLOR and a pipe.
+- **`<cli> mcp --call` validates its arguments** against the tool's schema,
+  strictly: an unknown or misspelt key, or a bad value, exits 2 with the
+  problem and the keys the tool takes, and calls nothing.
+- **The web UI service survives a removed nvm version.** Install prefers a
+  stable node of the same major version over a version manager's (or uses
+  `DEN_SERVICE_NODE`), and warns when it must keep one. `service status`
+  exits 1, naming it, when the installed node no longer exists.
+
+- **`<cli> init` in the distribution root seeds even through a symlinked
+  path** (`/var` → `/private/var`, a symlinked home). It compared paths
+  without resolving links and ran the manifest scaffolder instead.
+
+### Migrations
+
+- A script that relied on a non-interactive seed resetting a changed
+  workspace must pass `--reset`.
+- Optional (ORG-1a): to put a blueprint workspace in an org other than the
+  one its catalog owners give, add `org: <id>` to it under
+  `defaults.workspaces`. Pin Den 0.2.7 or later first: an older Den rejects
+  the key. Nothing else needs changing.
+
+## [0.2.6] - 2026-11-04
+
+### Fixed
+
+- **`<cli> web restart` and `web down` act on our server from an older
+  Den.** A server from before 0.2.6 (no `root` in `/api/server-info`) run
+  from our root is ours, and 0.2.6-dev.0 classified it so, but stopping it
+  then looked for our pids by command line only: the entry point of this
+  engine, or one under the root. An older Den installed elsewhere, or a
+  hand-started server, matched neither, so `web restart` printed "OK ... web
+  is already running" and restarted nothing, and `web down` printed "OK ...
+  web is not running" while the server stayed up and bound. A server the
+  identity check finds ours is now stopped by the pid it reports, when that
+  pid listens on the port: `restart` replaces it and `down` frees the port,
+  with or without a `web.json` for it. web.json's root is compared after
+  resolving symlinks (`/var` and `/private/var` are one root).
+- **The MCP server serves nothing from another distribution's server.**
+  It read from whatever answered on its port. Before a tool reads, it now
+  checks `/api/server-info` as `web up` does; on another distribution's
+  server every tool answers `port <N> is in use by <product> at <root>; not
+  this distribution's server` and returns none of its data. A positive
+  check is trusted for 30s and made again after a connection error, so a
+  server that took over the port is noticed. A server that does not say
+  whose it is within 5s is not read from either.
+- **A mistyped `service` flag no longer installs.** `<cli> service install
+  --anything` ignored the flag and installed; a `service` subcommand now
+  refuses an argument it does not take, before running anything.
+- **`<cli> web up` no longer trusts whatever answers on its port.** With
+  `web.port` set to a port where another distribution's Den server ran
+  (another root, an older Den), `web up` printed "OK ... web is already
+  running" and stopped, and `web down` or `web restart` could SIGTERM that
+  server: with a linked engine its command line looks like ours.
+  `/api/server-info` now also returns `root` (the distribution root the
+  server serves) and `product`. `web up`, `web down` and `web restart`
+  compare both with their own, and on another distribution's server exit 1
+  with `port <N> is in use by <product> at <root>` and a hint to pick
+  another port (`--port`, or `web.port`). A server from before 0.2.6 has
+  no `root`: it is ours when it runs from our root (its working
+  directory), otherwise `port <N> is in use by another server (Den
+  <version>)`; anything else is "a non-Den server". `web down` also no
+  longer signals a process running from another root, even when the
+  server does not answer. `<cli> mcp connect` refuses to point an agent at
+  another distribution's server (and `mcp clients` names it), and `<cli>
+  service install` no longer reports "running" when another
+  distribution's server answers on the port.
+- **A repeat `<cli> workspace seed` says "already seeded".** Seeding a
+  workspace that already holds exactly the blueprint printed "Default
+  workspace ready" as if it had seeded again; it now prints `✓ Default
+  workspace already seeded — N repos (managed): nothing changed.` and
+  writes nothing (multi blueprint: `✓ N workspaces already seeded (a, b)`).
+  A seed over a workspace the user changed says it was "reset to the
+  blueprint".
+- **Counts read "1 repo", not "1 repos".** CLI output that counts repos,
+  workspaces, systems, files, profiles and tools uses one plural helper
+  (`src/shared/plural.ts`), also in place of "repo(s)".
+- **Spinners no longer loop forever on a 0-column terminal.** On a pty that
+  reports 0 columns (one nobody sized, as agent shells give), ora computed
+  an infinite number of lines to clear and never finished. A spinner now
+  animates only on a TTY with a known, non-zero width; otherwise it prints
+  plain lines (its text on start, then the result).
+
+### Added
+
+- **Health type `container`.** `health: { type: container, project: <compose
+  project>, service: <compose service> }` checks a compose container by its
+  `com.docker.compose.project` / `com.docker.compose.service` labels, or
+  `{ type: container, container_name: <name> }` any container by name. It
+  is answered from the one `docker ps` per health cycle the compose checks
+  already share (its format gains `{{.Names}}`, and it no longer filters to
+  compose containers), so N container checks add no docker call, in the
+  web health row and in `<cli> status` (22 checks, 17 compose and 5
+  container: 1 docker call per cycle). A running container with a
+  healthcheck is its health (healthy up, unhealthy down, starting
+  pending), one without is up, and no matching container is down. When
+  docker gives no listing it says what a compose check says, through the
+  same code: a failed `docker ps` is unknown (`ok: null`, the reason in
+  `error`) on every cycle, never down; a listing past its budget is
+  pending (`pending: true`), down only when that repeats. Of several matches the best counts:
+  healthy, then running. `/api/health` rows show it as `check: "container
+  <project>/<service>"`. `<cli> validate` requires `project` + `service` or
+  `container_name` (not both, not one of the pair alone, no other type's
+  keys) and says which. See docs/distributions.md, "Health checks".
+- **`<cli> service install --plan`.** Read-only: prints the label, the
+  plist path, the log file, the roots, whose server answers on `web.port`
+  (ours, free, or `port <N> is in use by <product> at <root>`) and the
+  plist install would write; writes nothing and never calls launchctl.
+  Exits 1 when the port is another distribution's. `<cli> service status`
+  also names another distribution's server on the port.
+
+### Migrations
+
+- None required. Optional: a `type: shell` check that runs `docker ps` to
+  find a container (`test -n "$(docker ps -q --filter
+  label=com.docker.compose.project=X --filter
+  label=com.docker.compose.service=Y)"`) can become `{ type: container,
+  project: X, service: Y }`: no process or docker call of its own, and it
+  reads the container's healthcheck.
+
 ## [0.2.5] - 2026-11-04
 
 ### Fixed

package/bin/den

@@ -49,6 +49,15 @@ if [ "${1:-}" = "mcp" ] && ! case "${2:-}" in connect|disconnect|clients|config)
   built="dist/src/ui/cli/mcp-main.js"
 fi
 
+# A DEN_ROOT that names no distribution is a usage error, not a crash: say
+# so here, before any module resolves paths from it at import time.
+# (`create` needs no distribution.)
+if [ -n "${DEN_ROOT:-}" ] && [ "$entry" != "src/ui/cli/create-main.ts" ] && [ ! -f "$DEN_ROOT/den.yml" ]; then
+  echo "den: DEN_ROOT is set to \"$DEN_ROOT\" but that directory has no den.yml." >&2
+  echo "     Point it at your distribution's checkout, or unset it." >&2
+  exit 2
+fi
+
 # Escape hatch: force the compiled build (e.g. to test the prod artifact).
 if [ "${DEN_USE_DIST:-}" = "1" ] && [ -f "$DEN_ENGINE_ROOT/$built" ]; then
   exec node "$DEN_ENGINE_ROOT/$built" "$@"

package/docs/distributions.md

@@ -104,6 +104,23 @@ naming the file each error is in, then checks the merged result:
   ERROR   services.api.commands.local.down  unknown key "down": not in the base manifest
 ```
 
+Run with no argument in the distribution root, `<cli> validate` checks every
+manifest the distribution uses, and never clones:
+
+- each repo of every workspace, once per checkout path, with the
+  workspaces that use it and where its base comes from (`own`, `held`,
+  `+ override`);
+- a repo with no checkout on disk falls back to its held manifest, marked
+  `held only, no checkout`. With no held manifest either it is a warning, not
+  a failure;
+- each held manifest in `manifests/` that no workspace uses.
+
+It prints one line per repo, details only for a layer with errors or
+warnings, and exits 1 if any fails. `<cli> validate --held` checks only
+`manifests/`, as if nothing were checked out, so the result does not depend on
+the machine (use it in a CI or upgrade gate). An override whose base is the
+repo's own manifest is noted there, not checked.
+
 The web UI's Services cards show the layers each manifest was built from
 (`manifest: repo + override`), and `/api/services` returns them per service as
 `manifestLayers`, e.g. `["held", "override"]`. `DEN_MANIFESTS_DIR` points the
@@ -126,6 +143,83 @@ 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.
 
+## Health checks
+
+A service declares its health per environment under `health`, in one of
+three types:
+
+```yaml
+services:
+  api:
+    health:
+      local: { url: http://shop-api/healthz } # http (the default type)
+  db:
+    health:
+      local: { type: shell, cmd: pg_isready -h localhost } # exit 0 is up
+  cache:
+    health:
+      local: { type: container, project: shop-main, service: cache }
+```
+
+`label` (optional, any type) is shown in the UI instead of the URL or the
+command. A compose repo with no declared check gets Den's own stack check
+(`<cli> stack health`), answered in-process.
+
+**`type: container`** asks whether a container is up, from the one
+`docker ps` listing a health cycle already makes for the compose checks: it
+adds no docker call however many container checks there are, in the web
+health row and in `<cli> status`. It matches a compose container by its
+`com.docker.compose.project` and `com.docker.compose.service` labels
+(`project` + `service`), or any container by name (`container_name`, for one
+compose does not run). One or the other, never both:
+
+| What the listing shows                    | Verdict                                                 |
+| ----------------------------------------- | ------------------------------------------------------- |
+| running, healthcheck `healthy`            | up                                                      |
+| running, healthcheck `unhealthy`          | down                                                    |
+| running, healthcheck `starting`           | pending                                                 |
+| running, no healthcheck                   | up                                                      |
+| not running (exited, created, restarting) | down                                                    |
+| no matching container                     | down (`<project>/<service>: no container`)              |
+| `docker ps` fails (daemon down)           | unknown (`ok: null`, the reason in `error`), never down |
+| `docker ps` past its 5s budget            | pending (`ok: null`, `pending: true`)                   |
+| more than one match                       | the best one: healthy, then running                     |
+
+When docker gives no listing, a container check says what a compose check
+says, through the same code: docker state unknown is not "not running", so
+a failed `docker ps` is `ok: null` however many cycles it lasts, in the
+health row and in `<cli> status`. Only a listing that runs past its budget
+is `pending`, and like any check with no answer it is down when that
+repeats on the next cycle. A container whose healthcheck is still starting
+stays pending. In
+`/api/health` the row's `check` reads `container <project>/<service>` (or
+`container <name>`).
+
+Before, a container check was a shell check that ran docker itself, one
+process and one docker call per check per cycle:
+
+```yaml
+health:
+  local:
+    type: shell
+    cmd: test -n "$(docker ps -q --filter label=com.docker.compose.project=shop-main --filter label=com.docker.compose.service=cache)"
+```
+
+After:
+
+```yaml
+health:
+  local: { type: container, project: shop-main, service: cache }
+```
+
+which also reads the container's own healthcheck (the shell form only saw
+that a container existed, running or not).
+
+**Validation.** `<cli> validate` rejects a container check with neither
+`project` + `service` nor `container_name`, with only one of `project` and
+`service`, with both forms at once, or with a key of another type (`cmd`,
+`url`), and says which.
+
 ## Placement
 
 Each service says where it runs, per environment: `local` (on this machine,
@@ -358,8 +452,8 @@ defaults:
       focus: true
 ```
 
-Each entry takes `repos`, `branch` and `autostart_off`, the same fields as
-`defaults.workspace`, plus `focus`. Seeding creates every named workspace
+Each entry takes `repos`, `branch`, `autostart_off` and `org`, the same
+fields as `defaults.workspace`, plus `focus`. Seeding creates every named workspace
 with its repos, activates them all, and focuses the one with `focus: true`
 (else the first). Set `defaults.workspace` or `defaults.workspaces`, not both:
 both at once is an error, as is more than one `focus: true`.
@@ -375,6 +469,68 @@ Once seeded, a repo that later joins `defaults.workspace.repos` is added to
 you removed from it or that another workspace holds. With
 `defaults.workspaces` nothing is topped up.
 
+To see what a setup would clone before it clones anything, run
+`acme setup --plan`: each repo with its org and clone URL, and whether it
+is cloned yet. On a fresh machine it plans the blueprint (every workspace
+`acme workspace seed` would create); once seeded, the focused workspace.
+`acme up --plan` lists the same lines for the repos it would start. Both
+are read-only: nothing is cloned, seeded or written.
+
+## Orgs
+
+A distribution can hold work for more than one org: each workspace belongs
+to one. An org's id is a key of `orgs:` or a GitHub owner, and today an org
+is the GitHub owner of the same name. `github_org` is the default org. A
+distribution that never mentions orgs has one org, the default, and every
+workspace is in it.
+
+```yaml
+github_org: acme
+orgs:
+  acme: { label: Acme }
+  globex: { label: Globex, color: "#0af" }
+defaults:
+  workspaces:
+    storefront:
+      repos: [shop-web, shop]
+    client:
+      org: globex # optional: the workspace's org
+      repos: [globex-web, globex-api]
+```
+
+A workspace's org is the first of:
+
+1. `org:` on the workspace in `config/local/workspaces.yml` (this machine)
+2. `org:` on the blueprint workspace of the same name (committed)
+3. the one owner of its repos in the catalog (`gh: <owner>/<repo>`; owners
+   compare case-insensitively, and a `gh: ""` counts as unknown)
+4. `github_org`
+
+It is worked out each time it is read and never written back. A repo with
+no clone URL is cloned from `<org>/<repo>` with its workspace's org: seeding
+the blueprint above gives `globex-web` `gh: globex/globex-web`, not
+`acme/...`. `acme register` picks a managed clone from the focused
+workspace's org, or from `--org <id>`.
+
+`acme org list` shows each org's label, its workspaces and which is the
+default. `acme workspace list` has an Org column, and `--org <id>` lists one
+org's workspaces. A workspace whose repos belong to several owners, an
+`org:` naming an owner Den does not know, or a repo in another owner than
+its workspace's org is a warning in both lists, never an error.
+`GET /api/orgs` adds `default` and `workspaces` to each entry, and
+`/api/<cli>/config` adds `default_org`.
+
+`org:` in the blueprint needs Den 0.2.7 or later: an older Den rejects the
+unknown key. Pin 0.2.7 before you commit it.
+
+## Releases
+
+The Release page dispatches each repo's CD workflow on GitHub. A repo's
+owner there is its own `gh: owner/repo` in `release.repos`, else
+`release.org` when it is set, else the repo's owner in the catalog, else
+`github_org`. Leave `release.org` unset when the repos belong to different
+orgs: each then releases from its own.
+
 ## The bin shim
 
 `bin/<cli>` is three lines of sh: it names the distribution root and runs
@@ -449,6 +605,7 @@ it exits:
 
 ```bash
 ./bin/acme service install     # install (or refresh) and start it
+./bin/acme service install --plan  # what install would do; writes and loads nothing
 ./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
@@ -477,6 +634,15 @@ 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.
 
+`install --plan` is read-only: it prints the label, the plist path
+(`~/Library/LaunchAgents/<label>.plist`), the log file, the distribution and
+engine roots, whose server answers on `web.port` (this distribution's, free,
+or `port <N> is in use by <product> at <root>; not this distribution's
+server`), and the plist install would write. It writes nothing, never calls
+launchctl, and exits 1 when the port is another distribution's. Any other
+argument to a `service` subcommand is an error, so a mistyped `--plan` never
+installs. `status` also names another distribution's server on the port.
+
 `<cli> service` runs the installer script below, which you can also run
 yourself, from the distribution root:
 
@@ -493,10 +659,17 @@ node_modules/@monster-orange/den/service/install.sh print       # the plist only
 | `DEN_ROOT`          | required in a distribution               |
 | `DEN_SERVICE_LABEL` | `local.<distribution dir name>.web`      |
 | `DEN_SERVICE_LOGS`  | `~/Library/Logs/<distribution dir name>` |
-
-The service runs the engine's server with the `node` on your `PATH` at install
-time, from the distribution root; re-run `install` after changing node versions
-or upgrading Den. Keep the label stable: it is how launchd knows the service.
+| `DEN_SERVICE_NODE`  | see below                                |
+
+The service runs the engine's server, from the distribution root, with the
+`node` on your `PATH` at install time. A version manager's node (nvm, fnm,
+volta, asdf, mise) lives under a versioned path that disappears when that
+version is removed, so install prefers `/opt/homebrew/bin/node` or
+`/usr/local/bin/node` when one has the same major version, and otherwise
+keeps the version manager's and warns. `DEN_SERVICE_NODE` names the node
+outright. `service status` exits 1 when the installed node no longer exists.
+Re-run `install` after changing node versions or upgrading Den. Keep the
+label stable: it is how launchd knows the service.
 
 ## MCP server
 
@@ -509,6 +682,13 @@ set of guards. It never starts the web server; if it is not running, every
 tool answers with the command that starts it (`./bin/acme web up`). stdout
 carries only the protocol; diagnostics go to stderr.
 
+It reads only from this distribution's server. Before serving a tool it
+checks `/api/server-info` (root and product, or for a server from before
+0.2.6 its working directory), trusts a positive answer for 30s, and checks
+again after a connection error. When another distribution's server answers
+on the port, every tool says `port <N> is in use by <product> at <root>; not
+this distribution's server` and returns none of its data.
+
 The web server keeps running the Den it started with until it is restarted,
 so after an upgrade it can be older than the MCP server. When a tool's route
 answers 404, the MCP server reads the web server's version from
@@ -592,22 +772,22 @@ guard off.
 
 Read tools (always registered):
 
-| Tool                | Web API                                    | What                                                                                                                                            |
-| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell); `ok` true up, false down, null not known (`pending: true` when a check has not answered) |
-| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                      |
-| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                             |
-| `graph`             | `/api/graph`                               | The derived dependency graph and startup order                                                                                                  |
-| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                  |
-| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                              |
-| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                               |
-| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                          |
-| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                 |
-| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                               |
-| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                             |
-| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                          |
-| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health                                                                                         |
-| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names                                                                                                 |
+| Tool                | Web API                                    | What                                                                                                                                                                                |
+| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell, or `container <project>/<service>`); `ok` true up, false down, null not known (`pending: true` when a check has not answered) |
+| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                                                          |
+| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                                                                 |
+| `graph`             | `/api/graph`                               | The derived dependency graph and startup order                                                                                                                                      |
+| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                                                      |
+| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                                                                  |
+| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                                                                   |
+| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                                                              |
+| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                                                     |
+| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                                                                   |
+| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                                                                 |
+| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                                                              |
+| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health                                                                                                                             |
+| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names                                                                                                                                     |
 
 Action tools (only those named in `mcp.actions`): `service_up`,
 `service_down`, `service_restart` (through `/api/service/exec`),

package/package.json

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

package/service/install.sh

@@ -15,6 +15,7 @@
 #
 #   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
 #   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_NODE   the node the agent runs (default: see pick_node)
 #   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
 #                      caller (`<cli> service install`) checks the server
 #                      answers first.
@@ -47,8 +48,36 @@ find_tsx() {
   done
 }
 
+# A version manager's node (nvm, fnm, volta, asdf, mise) lives under a
+# versioned path that disappears when that version is removed, and the agent
+# then fails to start with no clear reason. Prefer a stable install of the
+# same major version; otherwise keep it and say so.
+STABLE_NODES="${DEN_SERVICE_STABLE_NODES:-/opt/homebrew/bin/node /usr/local/bin/node}"
+node_major() { "$1" -p "process.versions.node.split('.')[0]" 2>/dev/null; }
+pick_node() {
+  if [ -n "${DEN_SERVICE_NODE:-}" ]; then
+    [ -x "$DEN_SERVICE_NODE" ] || { echo "✗ DEN_SERVICE_NODE ($DEN_SERVICE_NODE) is not executable" >&2; exit 1; }
+    echo "$DEN_SERVICE_NODE"; return
+  fi
+  local node; node="$(command -v node)" || { echo "✗ node is not on PATH" >&2; exit 1; }
+  case "$node" in
+    */.nvm/*|*/fnm/*|*/.fnm/*|*/.volta/*|*/.asdf/*|*/mise/*) ;;
+    *) echo "$node"; return ;;
+  esac
+  local want c; want="$(node_major "$node")"
+  for c in $STABLE_NODES; do
+    if [ -x "$c" ] && [ "$(node_major "$c")" = "$want" ]; then echo "$c"; return; fi
+  done
+  # Warn when installing; `print` writes the plist and nothing else.
+  if [ "${1:-}" = install ]; then
+    echo "⚠ the service will run $node, a version manager's node: it stops starting" >&2
+    echo "  when that version is removed. Re-run install after switching, or set DEN_SERVICE_NODE." >&2
+  fi
+  echo "$node"
+}
+
 write_plist() { # $1 = output file
-  NODE="$(command -v node)" || { echo "✗ node is not on PATH" >&2; exit 1; }
+  NODE="$(pick_node "$MODE")"
   TSX="$(find_tsx)" || { echo "✗ tsx not installed: run npm ci in $DIST" >&2; exit 1; }
   DOCKER_DIR="$(dirname "$(command -v docker || echo /usr/local/bin/docker)")"
   SVC_PATH="$(dirname "$NODE"):$DOCKER_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
@@ -79,7 +108,8 @@ else:
 PY
 }
 
-case "${1:-install}" in
+MODE="${1:-install}"
+case "$MODE" in
   install)
     mkdir -p "$LOGS" "$(dirname "$PLIST")"
     write_plist "$PLIST.new"
@@ -115,6 +145,15 @@ case "${1:-install}" in
     write_plist -
     ;;
   status)
+    # The node the agent was installed with may be gone (a removed nvm
+    # version): launchd then restarts it forever with no useful message.
+    if [ -f "$PLIST" ] && command -v plutil >/dev/null 2>&1; then
+      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$PLIST" 2>/dev/null || true)"
+      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
+        echo "✗ $LABEL runs $svc_node, which no longer exists: re-run service install" >&2
+        exit 1
+      fi
+    fi
     # 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|spawn type)'

package/src/pillars/security/discover.ts

@@ -107,7 +107,7 @@ export function autoSecurityTargets(
     if (!runsLocally) continue;
     const hosts: SecurityServiceConfig["hosts"] = {};
     for (const [env, h] of Object.entries(s.config?.health ?? {})) {
-      if (!h || h.type === "shell" || !/^https?:\/\//.test(h.url)) continue;
+      if (!h || !("url" in h) || !/^https?:\/\//.test(h.url)) continue;
       hosts[env as keyof typeof hosts] = [new URL(h.url).origin + "/"];
     }
     if (Object.keys(hosts).length === 0) continue;

package/src/pillars/smoke/setup-global.ts

@@ -11,6 +11,7 @@ import { discoverRepos, resolveRepoPath, resolveService } from "./discover.js";
 import { stageSmokeTree } from "./staging.js";
 import type { Environment } from "../../shared/types/index.js";
 import { getDistRoot } from "../../shared/paths.js";
+import { plural } from "../../shared/plural.js";
 
 // Den-root anchored, NOT process.cwd() — bulk writer of .smoke-run (see setup.ts).
 const PROJECT_ROOT = getDistRoot();
@@ -116,7 +117,7 @@ async function main() {
   );
 
   console.log(
-    `\n  Total: ${total} smoke test file(s) staged across ${repos.length} repo(s)\n`,
+    `\n  Total: ${plural(total, "smoke test file")} staged across ${plural(repos.length, "repo")}\n`,
   );
 }
 

package/src/scripts/configure-aws-profiles.ts

@@ -17,6 +17,7 @@ import type { Environment } from "../shared/types/index.js";
 import { getDistRoot } from "../shared/paths.js";
 
 import { product } from "../shared/product.js";
+import { plural } from "../shared/plural.js";
 // Den-root anchored: WRITES config/local/aws-profiles.json, and the reader
 // (shared/environment/aws-profiles.ts) already anchors at getDistRoot().
 const ROOT = getDistRoot();
@@ -54,7 +55,7 @@ async function main() {
     );
   } else {
     console.log(
-      `  Found ${profiles.length} profile(s): ${profiles.join(", ")}\n`,
+      `  Found ${plural(profiles.length, "profile")}: ${profiles.join(", ")}\n`,
     );
   }