@monster-orange/den 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,249 @@ 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.6] - 2026-11-07
+
+Den in five minutes, set up by your own agent (ON-2, with ON-4's dry run).
+A developer pastes one line into their agent, and every command the agent
+runs answers in JSON, never prompts, and is safe to re-run.
+
+### Added
+
+- **Set up by your agent.** `den --help` and the README print the line to
+  paste: "Set up Den for me by following
+  https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md". The install-den skill it points
+  at ships in the package as `skills/install-den/SKILL.md`: plain Markdown
+  with Claude skill front matter, at most three questions, no secrets in
+  chat, no edits to the person's repos, nothing sent off the machine.
+- **`<cli> repo add <path|git-url>`** adds a repo with no prompts and never
+  writes into it. A git URL is cloned where Den keeps managed clones. A repo
+  with no manifest (or `--sidecar`) gets a side-car manifest in the
+  distribution's `manifests/`, detected from its Makefile `up` target, its
+  compose file or its `package.json` `dev`/`start` scripts (and `test`), and
+  validated before it is written. When detection can't decide, nothing is
+  written and the answer asks, with the choices; a re-run passes
+  `--run "<cmd>"`. `--health <url>` adds a health check. The workspace is
+  `-w`, else the focused one, else a new `default`. The same repo again
+  answers `existed: true`.
+- **`--json` for setup.** `create --yes --json` (a directory that already
+  holds the distribution is `existed: true`), `up --json` (each service's
+  result and health), `doctor --json` and `mcp connect --json`. Stdout is
+  one JSON object, the log goes to stderr, and a failure carries a `fix`
+  the agent can run or an `ask` for the person.
+- **`doctor --json`'s onboarding checks:** Node 22.13 or later, git, Docker
+  (only when a registered repo needs it), the web server and its URL, and
+  Den's MCP through it, each `ok`, `warn` or `fail`. The human `doctor` is
+  unchanged.
+- **`mcp connect --runtime claude|codex|gemini|grok`** names the agent by
+  its runtime. Grok CLI is a new client: Den writes its own
+  `[mcp_servers.<cli>]` table in `~/.grok/config.toml` (or the project's
+  `.grok/config.toml`), as xAI documents. A config file that already has the
+  entry is no longer rewritten.
+- **`create` picks a free web port.** When 7777 is in use on this machine,
+  `create` picks the next free port above it (never 7778, 7791 or 7799),
+  writes it to the new distribution's `config/local/user.yml` and says so,
+  in JSON as `port` and `portPicked`. `--port <n>` sets it outright. The
+  check connects and binds only; it sends nothing to the port's holder.
+  `DEN_WEB_PORT_START` moves the starting port.
+- **`web up --json`** answers `{ ok, url, port }` once the server answers,
+  and `doctor --json`'s web check carries the `port`.
+
+### Changed
+
+- `create` into a directory that already holds the same distribution says
+  so and exits 0, instead of refusing a non-empty directory.
+
+### Fixed
+
+- **An opted-in CLI sends its metrics.** The CLI records each run as it
+  exits, and a send started then never ran. With `metrics.share: true`, the
+  CLI now hands the event to a small detached sender that gives up after 2
+  seconds. The web server sends as before. Not opted in, nothing is sent.
+- **Linked devices read plainly.** A device approved with a code says
+  "approved with a code", not "signed in with approved with a code".
+- **An agent's refusal names the admin password.** It said "the lock",
+  which 0.4.4 removed.
+
+### Metric
+
+- Time from the paste to "service running, MCP connected" (R11): not
+  measured before; ON-4's dry run (create, repo add, up, web up, doctor,
+  mcp connect, each run twice) now records it, about 16 s locally. Target:
+  5 minutes or less.
+
+### Migrations
+
+- None.
+
+## [0.4.5] - 2026-11-07
+
+Sign in with GitHub as the owner, from your other devices; approve a
+computer with a code; see that you're signed in (SEC-2a). Save the admin
+password without editing YAML (LK-4). Dev-metrics stay on this machine
+unless you opt in.
+
+### Added
+
+- **Sign in with GitHub.** A Den has one owner, a GitHub account:
+  `<cli> web owner link` runs GitHub's device flow in the terminal (a code
+  to enter at https://github.com/login/device) and stores only
+  `github:<id>` and the login (`web-owner.json`, 0600), never the token.
+  `web owner show` and `web owner unlink` too. The signed-out page then
+  has **Sign in with GitHub**: the server runs the flow, and the owner's
+  approval sets the same never-expiring session a one-time link does;
+  any other account sees "@<login> isn't allowed on this Den". At most
+  three sign-ins wait at once. Before an owner is linked the page says to
+  run `web owner link`. See docs/distributions.md, "Signing in with GitHub".
+- **Settings › Access.** The owner (link and unlink: shell-grade, so a
+  signed-in browser and never an agent's token), the
+  linked devices (browser, how it signed in, the client address the edge
+  vouched for, first and last seen) each with **Revoke**, which ends that
+  session at once, and **Pair a device**: a one-time link and its QR code
+  for an edge hostname you pick.
+- **`web.github_client_id`**: the GitHub App's client id (public). The
+  default is Den's own App, "Monster Orange Den" (`Iv23liKL12gnN6WvRV5b`);
+  a distribution sets its own App's id here, and an empty value turns Sign
+  in with GitHub off (the page then offers only the code and the link).
+  The App needs "Enable Device Flow" ticked and "Expire user authorization
+  tokens" off (docs/distributions.md, "The GitHub App").
+- **Expiring GitHub tokens are noticed.** If the App hands out expiring
+  tokens (`expires_in` or `refresh_token` in the answer), sign-in still
+  completes, and Den says once to switch off token expiry in the App's
+  settings (never with the token). `GET /api/web/owner` reports it as
+  `tokenExpiry`. Den never asks for `offline_access`.
+- **Approve this computer with a code.** The signed-out page shows a
+  six-character code (`XXX-XXX`, about 30 bits; the page polls with its own
+  128-bit id) and the command that approves it on the machine Den runs on:
+  `<cli> web approve <code>` (any case, dash optional; `--list` shows what
+  waits). The page signs itself in when it's approved, onto the page it
+  asked for. From a machine with SSH access the page gives the one-liner
+  (`ssh <host> '<cli> web approve <code>'`) and, for a host name, an Open
+  Terminal link. Codes expire after 10 minutes, are single-use, at most
+  five wait at once (the oldest drops) and are kept in memory only;
+  approvals are rate-limited and audited with who approved. The device is
+  labelled "approved with a code".
+- **Settings › Access › Waiting devices**: the computers waiting with a
+  code (browser and OS, address, when), each with **Approve** and **Deny**.
+- **`web.machine_name`** (Settings › Access › Machine name, in user.yml):
+  the name the signed-out page gives this machine. Default: the short
+  hostname. It's never taken from the browser's Host; the ssh one-liner's
+  target is the Host the browser used (without the port).
+- **The signed-out page says where to act.** "Sign in to <product>", which
+  machine Den runs on and why it asks (once per computer), Sign in with
+  GitHub (only with a client id), Approve this computer, and the one-time
+  link under "Other ways". Every command it prints names the machine it
+  runs on, has a copy button, and is `<cli>` when that's on PATH and this
+  distribution's, else the absolute path of its bin. English, Japanese and
+  Spanish.
+- **See that you're signed in.** A chip at the foot of the rail says
+  "Local", "Signed in · this device" or "@<login>" and opens Settings ›
+  Access. The first page after a sign-in says "This device is signed in
+  to <product> on <machine>", once. Linked devices lists every session
+  (GitHub, a code, a one-time link) with how it signed in, when, from
+  where, last seen and Revoke, and marks the one you're using as "This
+  device".
+- **Save the admin password without editing YAML (LK-4).** When a secrets
+  backend that keeps secrets (1Password, Doppler) is available and no
+  `secrets.refs.sudo` is set, the admin password prompt (shown when a
+  command is about to run sudo, LK-0) still offers "Save to <backend>".
+  Saving creates the item (1Password: "<Product> admin password" in your
+  default vault; Doppler: `<PREFIX>_LOCAL_ADMIN_PWD`) and writes
+  `secrets.refs.sudo` to your `config/local/user.yml`, so the password
+  survives restarts. A ref in the distribution's config still wins. The
+  vault status says so as `canSave`. A save error no longer carries the
+  backend's command line.
+- **`edge.proxy_protocol.trusted_ips`** (empty by default): the front
+  proxies (a TCP passthrough in front of the edge) whose PROXY protocol
+  every entrypoint accepts, so Den sees the real client through them.
+- **`web.edge_unattested: local | signin`** (default `signin`, read only
+  from `config/local/user.yml`): whether an edge client Den can't place
+  signs in. `local` keeps 0.4.4's (and 0.4.3's) behaviour.
+
+### Changed
+
+- **Dev-metrics are local unless you opt in.** Den sent its dev-metrics
+  whenever a DSN was present (in the env or a synced
+  `dev-metrics.config`). Sending now needs `metrics: { share: true }` in
+  `config/local/user.yml` (the boolean only); a DSN alone never sends. The
+  local `events.jsonl` is unchanged, and `CI=true` and
+  `DEV_METRICS_DISABLED=1` still stop sending.
+- **`<cli> web login` waits.** It prints the link and an 8-character code,
+  and blocks until the link is used ("Signed in: <browser> (<address>) at
+  <time>") or expires ("Expired: nobody used the link", exit 1). The link
+  asks for the code before it signs in; a wrong code is refused (five burn
+  the link, and wrong codes are rate-limited) and the link stays
+  single-use. `--no-wait` prints the link alone, as before, and asks for no
+  code; with no server running it behaves like `--no-wait` and says so.
+- **Edge visitors Den can't place sign in.** A client the edge reports
+  with no `X-Forwarded-For`, or with a Docker/VM gateway or bridge address
+  (what a TCP passthrough or Docker Desktop and OrbStack hand it), now sees
+  the signed-out page with Sign in with GitHub, unless
+  `web.edge_unattested: local`. Loopback and this machine's own addresses,
+  as the edge reports them, stay local, and localhost straight to the
+  server's port never signs in.
+- **The client is the right-most `X-Forwarded-For` entry**, the one the
+  edge appended (0.4.4 and earlier read the left-most, which a client could
+  write).
+- **The edge believes forwarded headers only from its own networks.** Den
+  renders `forwardedHeaders.trustedIPs` (loopback and the Docker ranges)
+  on every entrypoint, never `forwardedHeaders.insecure`. An `edge.args`
+  entry that sets `forwardedHeaders` or `proxyProtocol` is dropped with a
+  notice from `edge up`.
+- **"Your edge is reachable from other machines"** now reads "A browser it
+  can't place as this one signs in first (Sign in with GitHub, or a
+  pairing link)." (with `web.edge_unattested: local`, that anyone it can't
+  place can use terminals).
+- **`edge up` says when the running edge's command differs** from the one
+  it renders, and why, before recreating it.
+
+### Fixed
+
+- **The workspace commands run in is named: "CLI default".** Local Dev's
+  workspace list marked it with a bare accent dot and no label, and
+  picking a workspace in the top bar never moved the dot (by design: that
+  picks the view), so it looked broken. It now says "CLI default", with
+  a tooltip: CLI commands run there when you don't name a workspace, and
+  the top bar only changes what pages show. The top bar's Workspace menu
+  tags it "CLI default" (was "focus") and offers "Make <ws> the CLI
+  default"; the Workspaces pane's badge reads "active · CLI default" and
+  its button "Make CLI default". Nothing behaves differently.
+
+- **A browser signs in on a plain-http LAN bind** (`DEN_BIND_HOST` with
+  `web.allow_plain_http_remote`). A `web login --origin http://<LAN IP>:<port>`
+  link got 403 `origin_rejected`: the browser sends a plain-http origin that
+  isn't localhost no `Sec-Fetch-*` headers, and a navigation sends no
+  Origin. The sign-in GETs (`/auth` and the GitHub sign-in poll), which
+  carry their own one-time credential, now pass with neither header. Either
+  header, when present, is still checked, and every other GET that runs
+  something still needs this server's page or a bearer.
+- **`web up` with `DEN_BIND_HOST` on one address is ready when it serves.**
+  Its readiness probe (and `web sessions`/`web logout`'s calls) asked
+  127.0.0.1, so a server bound to a LAN IP or `::1` printed "did not become
+  ready" and exited non-zero. They ask the bound address now (loopback for
+  0.0.0.0 and `::`), with a Host the allowlist accepts and the CLI's
+  bearer: a LAN address answers an unsigned probe 401 `signin_required`.
+  `web up` names the bound address (`http://<LAN IP>:<port>`), not
+  localhost, which a LAN-only bind doesn't answer.
+
+### Migrations
+
+- **One edge recreate.** The edge's command changes (forwarded-header
+  trust), so the first `<cli> edge up` (or `stack up`) after upgrading
+  recreates it once, and says so: "<org>-edge's settings changed
+  (forwarded-header trust): recreating it once." Routes drop only while it
+  restarts.
+- **Edge visitors now see Sign in with GitHub** where 0.4.4 let a client
+  it couldn't place in. Link an owner (`<cli> web owner link`), approve
+  the computer with its code (`<cli> web approve <code>`) or pair with
+  `<cli> web login --host <name>`;
+  or set `web.edge_unattested: local` in `config/local/user.yml` to keep
+  0.4.4's behaviour on that machine.
+- **Scripts that run `<cli> web login` and read its output** should pass
+  `--no-wait`: it now waits for the link to be used.
+- **Remove `forwardedHeaders.*` and `proxyProtocol.*` from `edge.args`.**
+  They are ignored now; use `edge.proxy_protocol.trusted_ips` for a front
+  proxy.
+
 ## [0.4.4] - 2026-11-07
 
 The admin password is for sudo, and nothing else (LK-0). An agent's

package/README.md

@@ -10,10 +10,24 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.4/hero-dark.png">
-  <img src="docs/images/0.4.4/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">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.6/hero-dark.png">
+  <img src="docs/images/0.4.6/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>
 
+## Set up by your agent
+
+Paste this line into your coding agent (Claude Code, Codex, Gemini, Grok, …):
+
+```text
+Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md
+```
+
+The agent follows the [install-den skill](skills/install-den/SKILL.md). It asks you at most three questions,
+creates your Den, adds one of your repos without changing it, starts it, checks it, and connects itself to Den's
+MCP server. Then it tells you what's running and the URL to open. It never asks for a password in chat, never
+edits your repos and sends nothing off your machine. Every step it runs answers in JSON and is safe to re-run:
+see [Set up by your agent](docs/distributions.md#set-up-by-your-agent).
+
 ## What Den is
 
 Den is an opinionated local development framework for solo developers and small teams. You point it at the
@@ -24,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.4/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">
+  <img src="docs/images/0.4.6/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
@@ -46,17 +60,18 @@ yours. Den connects them and turns on good practice from the start.
   and audit trail as a person, under a token of its own. Agents can read and investigate, and acting is opt-in.
   Starting an agent never asks for your admin password: Den asks for it only when a command it runs needs sudo.
 - **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.
+  edge from another machine, or over your network, every page and call needs a sign-in, and there is no password:
+  Sign in with GitHub as the Den's owner, approve the computer with a code (`acme web approve <code>`), or open a
+  one-time link from `acme web login`.
 - **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.4/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.4/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.4/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.4/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">
+  <img src="docs/images/0.4.6/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.6/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.6/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.6/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