@monster-orange/den 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -4,6 +4,148 @@ 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.4.3] - 2026-11-06
+
+Agents start, and the edge counts as local.
+
+### Fixed
+
+- **The Start agent dialog can be submitted (AG-10.0).** A persona's whole
+  role sentence was in its option, so the select grew past the dialog and
+  pushed Cancel and Start out of sight. A persona option now shows its id,
+  with its role on a help line under the select that follows the pick. The
+  runtime's first option names what it resolves to ("Claude Code (persona
+  default)"), a runtime that can't run here says why, and Enter starts
+  from any field. The Workspaces page's agents form gets the same choices.
+
+- **Agents start on a Den run as a service (AG-0.1).** Starting any agent
+  failed with "den-claude is unavailable: claude is not on PATH" when the
+  web server ran under launchd: its PATH leaves out `~/.local/bin`, where
+  Claude Code's native installer puts `claude`, and Den searched only that
+  PATH. Den now finds a runtime's CLI as your terminal would:
+  `agents.runtimes.<id>.bin` in `config/local/user.yml` wins (an absolute
+  path, checked; a bad one is refused with its reason), then the login
+  shell's PATH (`$SHELL -lc`, asked once at server start in the
+  background, 3-second timeout, falling back to the current PATH), the
+  server's PATH, and the runtime's install directories (`~/.local/bin`,
+  `~/.claude/local`, `/opt/homebrew/bin`, `/usr/local/bin`, npm's global
+  bin). Agents and plain sessions get the same directories on their PATH.
+- **The lock is always reachable (LK-1 to LK-3).** Start agent opened its
+  dialog and only then asked for the lock, whose popover sat under the
+  dialog where nothing could reach it. The lock is now checked before the
+  dialog opens, and the dialog asks for the admin password at its top:
+  Start unlocks, then starts. The lock popover is in the top layer, so no
+  dialog covers it. A page that thinks it's locked asks the server before
+  asking you (another tab or device may have unlocked it), and, when a
+  password is stored in the vault, the first action that needs the lock
+  loads it from there on every page, not only Local Dev. A page view still
+  never wakes the vault.
+
+### Changed
+
+- **The edge from this machine needs no sign-in.** A request for the edge
+  hostname from an edge peer is treated as loopback: no sign-in on any
+  route, agents and the terminal included (0.4.2 asked for one on every
+  route). Host, Origin, CSRF and the agent-token rules stay. The client is
+  the left-most `X-Forwarded-For` entry: loopback or one of this machine's
+  own interface addresses (a Tailscale `100.x` included) is local; missing,
+  or a Docker/VM network's address (what Docker Desktop and OrbStack hand
+  the edge; the subnets of the edge's own Docker networks, `<org>-edge`
+  and those it joins, read once at start with `docker network inspect`;
+  OrbStack's host address `0.250.250.254`), is "can't tell", also local, so
+  a TCP-passthrough proxy container on the edge's network is no other
+  machine; any other address is another
+  machine and needs a sign-in. A non-loopback `DEN_BIND_HOST` bind (other
+  than the Linux edge's Docker bridge) and `web.allow_plain_http_remote`'s
+  LAN names still need one. See docs/distributions.md, "Signing in".
+
+### Added
+
+- **The Start dialog says before Start whether the agent can run
+  (AG-0.2).** Under the runtime a line names what Start will run, with its
+  version and path ("Starts Claude Code 2.1.0 from …"); the runtime's
+  option shows its version. When the runtime can't run here, Start is
+  disabled and the line says why and how to fix it: where Den looked, then
+  install it, or set `agents.runtimes.<id>.bin` in the user.yml it names,
+  or run `<cli> agents doctor`. The Workspaces page's agents form does the
+  same. `GET /api/personas` gives each runtime `version` (its version
+  command, run once under a timeout and kept), `path`, `source`
+  (`setting`, `login-shell`, `well-known` or `PATH`), `searched` and
+  `setting`, and the response a `userConfig` path.
+- **`<cli> agents doctor [--json]` (AG-0.3)**: each runtime's status, the
+  CLI it runs and where it came from, its version, the directories
+  searched (names only, never an environment value), and the fix when it
+  is missing. It exits 1 when the default runtime is unavailable.
+
+- **"Your edge is reachable from other machines".** When an edge hostname
+  resolves to an address that isn't loopback, or the edge container
+  publishes a port on every interface (`docker inspect`), Den says so once
+  in `web.log` at start and in a banner on every page (dismissed per
+  browser): "Your edge is reachable from other machines; anyone who can
+  reach it can use terminals. Auth is coming."
+- **`<cli> web login --host <name>`** mints the one-time link for an edge
+  hostname (an edge domain or alias, a VPN name among them) at its edge
+  URL, instead of localhost. A name the edge doesn't route to this server
+  is refused, naming the hostnames it does and what to add. `--origin`
+  stays.
+
+### Migrations
+
+- **A Den run as a service whose agents' CLI is somewhere unusual**: set
+  `agents.runtimes.<id>.bin` (an absolute path) in `config/local/user.yml`.
+  Nothing else changes: a runtime on the server's PATH is found as before.
+- **A page script that called `requireUnlock()`** (header.js): it now
+  returns a promise of the answer; `await` it.
+
+## [0.4.2] - 2026-11-06
+
+The 0.4.1 carry-overs.
+
+### Added
+
+- **`sessions.max_concurrent`** (default 8): the cap on plain sessions
+  (`sessions start`) running at once. Past it, `sessions start` is refused
+  as the agents' cap is: "2 sessions are running and
+  sessions.max_concurrent is 2", then "Stop one first (`<cli> sessions
+  kill <name>`), or raise sessions.max_concurrent." `<cli> validate` names
+  a wrong value of it or of `agents.max_concurrent`.
+
+### Changed
+
+- **`agents.max_concurrent` counts agents only.** Plain sessions count
+  against `sessions.max_concurrent` instead, so a few plain shells never
+  stop an agent from starting (from the CLI, the Workspaces page, the
+  Agents tab or MCP). Its refusal says "1 agent is running and
+  agents.max_concurrent is 1".
+- **The Agents tab's pane title and Close** name the agent by its id
+  (its display name once AG-10 adds one), never its persona; the list row
+  still shows the persona, with the id beside it.
+- **den-claude's deny list, in the docs**: it is a convenience, not the
+  boundary. It binds cooperating agents only and does not catch every
+  spelling (a path relative to the agent's cwd, another program); the
+  server's token rules are the boundary.
+
+### Fixed
+
+- **A distribution config's `web.allow_plain_http_remote`** (ignored: it is
+  read only from `config/local/user.yml`) was warned about only in the
+  in-app server log. It is now in `web.log` too (before a bind refusal it
+  often explains), in the `web up` and `web restart` output, and in
+  `<cli> validate`.
+- **`up --help`**: `-w, --workspace <ws>` ran into its text ("<ws>act in
+  that…"); there are two spaces now. `down`, `restart` and `setup --help`
+  were already spaced.
+
+
+### Migrations
+
+- **More than 4 plain sessions at once**, or a script that relied on
+  `agents.max_concurrent` to cap plain sessions: set
+  `sessions.max_concurrent` (default 8). `agents.max_concurrent` no longer
+  counts them. A session host already running from 0.4.1 keeps counting
+  every session until it restarts (`sessions host --stop`, which ends its
+  sessions, or a reboot).
+
 ## [0.4.1] - 2026-11-06
 
 ### Added

package/README.md

@@ -1,169 +1,99 @@
-# Den
-
-Den is a config-driven local development appliance. It starts the repos you
-work on in dependency order, puts them behind a local HTTPS edge, gives you a
-web UI and a CLI over all of it, and runs smoke, browser, API, journey,
-security and performance suites against the environments you declare.
-
-Den knows nothing about any particular organisation. Everything specific to
-yours — product name, repos, environments, hosts, secrets backend, test
-accounts — lives in **your distribution**, not in Den.
-
-> **Status: 0.2.0**: `npm install @monster-orange/den`. Den is pre-1.0; each release lists the changes a distribution makes under **Migrations** in [CHANGELOG.md](CHANGELOG.md).
-
-## Make it your own
-
-1. **Create** a distribution named after your product:
-
-   ```sh
-   npx @monster-orange/den create acme      # → ./acme
-   cd acme && npm install
-   ```
-
-2. **Name** it: `den.yml` holds `product: { name: acme }`, so the CLI is
-   `./bin/acme`, env vars are `ACME_*`, state lives in `~/.acme`. Pass
-   `--cli`, `--env-prefix` or `--title` to `create`, or edit `den.yml`.
-3. **Brand** it: `brand:` in `config/acme.yml` sets the name, tagline and
-   banner people see in the CLI and web UI.
-4. **Point it at your repos**: set `github_org` in `config/acme.yml`, then
-   `./bin/acme register ../shop-api` (or add a manifest per repo under
-   `manifests/`).
-5. **Run** it: `./bin/acme up`, `./bin/acme web`, `make test`.
-
-Every field, the bin shim, the make fragment and upgrading are in
-[docs/distributions.md](docs/distributions.md);
-[examples/distribution/](examples/distribution) is what `create acme` writes.
-
-## Distributions
-
-You run Den through a small repo of your own (a _distribution_):
-
-```
-my-dev/
-├── den.yml               # who this distribution is (below)
-├── package.json          # pins an exact @monster-orange/den version
-├── config/<name>.yml     # your org config
-├── config/environments/  # one <env>.json per environment
-├── manifests/            # manifests for repos that don't carry their own
-├── tests/pillars/<pillar>/   # your own suites (e.g. tests/pillars/perf/<module>/test.js)
-├── bin/<cli>             # shim: DEN_ROOT=<this dir> exec node_modules/@monster-orange/den/bin/den
-└── Makefile              # include node_modules/@monster-orange/den/make/den.mk
+<p align="center">
+  <img src="docs/images/preview/mark.svg" width="72" alt="Den">
+</p>
+<h1 align="center">Den</h1>
+<p align="center"><b>Your whole stack, up and green, in one place. Built so you and your agents work by the same rules.</b></p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@monster-orange/den"><img src="https://img.shields.io/npm/v/@monster-orange/den" alt="npm"></a>
+  <img src="https://img.shields.io/npm/l/@monster-orange/den" alt="licence">
+  <a href="https://github.com/Monster-Orange/den/actions/workflows/ci.yml"><img src="https://github.com/Monster-Orange/den/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.3/hero-dark.png">
+  <img src="docs/images/0.4.3/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+</picture>
+
+## What Den is
+
+Den is an opinionated local development framework for solo developers and small teams. You point it at the
+repos you work on. Den starts them in the right order, puts them behind a local edge, and shows you the
+whole thing in one web shell and one CLI: what's up, what's down, why, and the fix.
+
+It doesn't replace your tools. Your repos, Docker, your test runners, your secrets store and your agents stay
+yours. Den connects them and turns on good practice from the start.
+
+<p align="center">
+  <img src="docs/images/0.4.3/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+</p>
+
+## How it helps
+
+- **"How do I run this?" goes away.** Each repo declares how it starts, what it needs and how to check it's
+  healthy. Den works out the order and brings everything up, the same way on every machine.
+- **One place to look.** Health, logs, runs, routes and certificates for every service, in one shell, instead
+  of eight terminals and a wiki page.
+- **Real hostnames locally.** Every service gets a proper hostname behind a local edge, over HTTPS when you
+  turn it on (a local CA with mkcert, or certificates you bring). Cookies, OAuth redirects and CORS behave as
+  they do in production.
+- **Several workspaces at once.** Keep feature branches side by side as workspaces. Health covers every active
+  one, and `up`, `down`, `restart` and `setup` take `-w <workspace>`, or find the service you name across them.
+- **Tests are part of the loop.** Smoke, browser, API, user journeys, security and performance suites run against
+  the environments you declare.
+- **Agents work by the same rules as you.** Start an agent from a persona (planner, orchestrator, developers,
+  devops, reviewer, UX designer, or your own) in a workspace. Its terminal opens in the Agents tab and keeps
+  running when you close the page or restart the web server. Over MCP it sees your stack with the same guards
+  and audit trail as a person, under a token of its own. Agents can read and investigate. Acting is opt-in,
+  and the lock still guards starting and stopping things.
+- **Safe on localhost, signed in beyond it.** On localhost there is nothing to sign in to. Reached through the
+  edge or your network, every page and call needs a sign-in, and there is no password: `acme web login` prints a
+  one-time link.
+- **Opinionated, not locked in.** Good defaults are switched on, and almost everything can be switched off. The
+  safety guards stay on. Den never needs our accounts, secrets or certificates. Everything specific to you
+  lives in your own repo.
+
+<p align="center">
+  <img src="docs/images/0.4.3/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.3/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.3/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.3/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+</p>
+
+## Get started
+
+You need Node 22.13 or later, and Docker for anything that runs in containers. mkcert is only needed if you want Den to issue local HTTPS certificates.
+
+```sh
+npx @monster-orange/den create acme     # your own Den, named after your product
+cd acme && npm install
+./bin/acme register ../shop-api          # add a repo (repeat for each one)
+./bin/acme up                            # start everything, in order
+./bin/acme web                           # open the shell
 ```
 
-`den.yml` names the product. Every runtime name derives from it:
+That's it: `acme` is now your tool, with your name, your CLI and your config, in a repo you own.
+[Step by step →](docs/reference.md#make-it-your-own)
 
-```yaml
-product:
-  name:
-    acme # CLI "acme", env vars ACME_*, config/acme.yml,
-    # manifests .acme.yml, state ~/.acme,
-    # managed clones .acme-services/, workspaces acme-workspaces/
-  # Override any of them: cli, env_prefix, config, manifest, state_dir,
-  # services_dir, workspaces_dir
-```
+## How it fits together
 
-Den's own checkout is a distribution named `den`, so in this repo the CLI is
-`./bin/den`, the config is `config/den.yml`, and env vars are `DEN_*`.
-
-## Repos opt in with a manifest
-
-A repo joins by carrying a manifest at its root (`.<name>.yml`, e.g.
-`.den.yml`) whose commands delegate to the repo's own targets. Den never
-reaches inside a repo beyond that. When a repo has no manifest, the
-distribution can hold one for it in `manifests/<repo>.<name>.yml`; the repo's
-own manifest always wins.
-
-```yaml
-# demo-api: a self-contained service. Nothing it calls, so it starts alone.
-version: 1
-name: demo-api
-application: shop # the application this repo belongs to (den apps)
-compose:
-  files: [docker-compose.yml]
-  routes:
-    api: api:8080 # https://api.demo-api.<edge domain>
-services:
-  demo-api:
-    commands:
-      local:
-        setup: make setup
-        preflight: make test
-# OWASP ZAP target for the security pillar (`make test-sec-api env=local`).
-security:
-  api:
-    hosts:
-      local: ["https://api.demo-api.globex.localhost"]
-```
+<p align="center"><img src="docs/images/preview/how-it-fits.svg" width="100%" alt="Den, the engine, runs your distribution, which holds your config; the distribution groups repos into workspaces, and each repo declares its services"></p>
 
-That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
-[`examples/demo/`](examples/demo/).
-
-## What it does
-
-- **Workspaces.** A workspace is a set of repos. Each is either
-  _dev-managed_ (your checkout, your branch) or _managed_ (cloned by Den and
-  kept on a tracking branch).
-- **Derived dependency graph.** Start and stop order comes from real signals in
-  each repo — SDK imports, `*_URL` env vars, IaC references, event rules,
-  readiness probes — tuned in config with `graph.aliases`, `graph.edges` and
-  an optional shared local-infra repo (`graph.infra`).
-- **Local HTTPS edge.** One local proxy routes `https://<route>.<domain>` to
-  each service, with an optional project CA.
-- **Test pillars.** `smoke`, `browser` (synthetic Playwright), `api`,
-  `journeys` (agent-driven), `perf` (k6), `security` (OWASP ZAP against hosts
-  you own) and `suites` (a repo's own commands).
-- **Releases.** A release view over the repos and deploy workflows your config
-  lists.
-- **Web UI and CLI** over the same state.
-
-## Strategies
-
-Concerns that vary by org are strategies selected in config, never hard-wired:
-
-| Concern          | Built-in choices                        | Chosen in                                                                                                            |
-| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| Secrets backend  | `none`, `env`, `doppler`, `1password`   | `secrets.provider` in the org config; per engineer in `config/local/user.yml`; per shell `<PREFIX>_SECRETS_PROVIDER` |
-| Test-user tokens | `local-jwt`, `cognito`, `auth0`, `none` | `auth.provider` in `config/environments/<env>.json`                                                                  |
-
-A new secrets backend implements `SecretsProvider`
-(`src/shared/secrets/types.ts`) and registers as a strategy
-(`src/shared/secrets/strategies.ts`); a distribution needs no store at all
-(`none`, see "Secrets" in `docs/distributions.md`). A new identity provider implements a token
-provider in `src/shared/auth/token-providers/`.
-
-## CLI
-
-```bash
-den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
-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
-den logs [repo]        # tail a repo's local logs
-den use-local [repo]   # use your checkout · use-managed [repo] to switch back
-den workspace list     # workspaces (activate · deactivate · use · create · delete)
-den run                # run test suites (interactive, or with options)
-den web                # the web UI
-den --help             # everything else
-```
+- **Den** is the engine, from npm. It knows nothing about your company.
+- **Your distribution** (`acme`) is a small repo you own. It holds your product name, brand, environments,
+  hosts and secrets setup.
+- **Workspaces** group the repos you work on together. **Manifests** in each repo say how its services start,
+  connect and get checked.
 
-In a distribution the command is that distribution's `cli` name.
+## Coming next
 
-## Developing Den
+One workspace focus with Switch, agent pane layouts, and a Start dialog with personas, roles and a choice of
+runtime and model.
 
-```bash
-npm ci
-npm run typecheck
-npm run lint
-npm test
-DEN_ORG_NAMES_FILE=<patterns file> node scripts/org-name-gate.mjs
-```
+## Docs
 
-CI runs the same gates. The org-name gate fails the build when any file names
-an organisation, product, host or account; its patterns are kept out of this
-repo (a CI secret) so the list itself is never published. See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+[Reference](docs/reference.md) (configuration, manifests, strategies, CLI) · [Distributions](docs/distributions.md) ·
+[Changelog](CHANGELOG.md)
 
-## License
+Found a bug or have an idea? [Open an issue](https://github.com/Monster-Orange/den/issues/new).
 
-[MIT](LICENSE)
+MIT licence.