@monster-orange/den 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,135 @@ 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.3] - 2026-11-04
+
+### Added
+
+- **`secret_env`: secrets resolved by Den into a stack's or a service's env**
+  (R16), so a consumer no longer wraps `<provider> run -- <cli> restart
+  <repo>` by hand, and a plain restart no longer drops a key. In a manifest,
+  `compose.secret_env` (for the docker compose process: the compose file's
+  `${VAR}` or pass-through `environment:` entries) and
+  `services.<svc>.secret_env` (for that service's own up/restart command)
+  map an env var to a fully qualified ref, `<vault>/<item>/<field>`. For
+  Doppler that is `<project>/<config>/<key>`; for 1Password vault / item /
+  field; for `env` the field is the env var to read. Existing refs (the
+  engine's named secrets, test users) are unchanged. Resolved through the
+  configured `secrets.provider` at `up` and `restart` (also the in-place
+  restart of one compose service), all or nothing, before anything stops or
+  starts. A missing key fails that target, exit 1, naming the key, ref and
+  provider. Values go only into the spawned process's env: never into the
+  compose override, logs, activity records, MCP output or messages. A dry
+  run (`-n`) never asks the provider; it lists the key names it would
+  inject. A CLI-tabs start of a service with `secret_env` runs as a daemon,
+  so the values stay out of the tab's shell. `validate` rejects a ref that
+  is not exactly three non-empty parts, and a key that is not an env var
+  name. See "Secrets in a target's env" in `docs/distributions.md`.
+
+### Fixed
+
+- **`<cli> mcp connect` for Claude Code failed whenever the server has env**
+  ("Invalid environment variable format: <name>"): `claude mcp add`'s `-e`
+  takes several values, so the server name after the env pairs was read as
+  one more. The name now comes right after `add`.
+- **The up/restart secrets check said the backend was "not ready" when it
+  was signed in with no default scope.** `secret_env` refs name their own
+  scope, so they still resolve; it now says "signed in, no default scope
+  set" instead of warning.
+
+### Migrations
+
+- None required.
+
+## [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

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/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,
@@ -196,6 +213,57 @@ ones (`⇄ hybrid`).
   production_envs: [prod] # default: [prod, production]
   ```
 
+## Secrets in a target's env
+
+`secret_env` puts secrets from the configured secrets provider
+(`secrets.provider`: `doppler`, `1password` or `env`) into the env of what
+Den starts, instead of wrapping `<provider> run -- <cli> restart <repo>` by
+hand:
+
+```yaml
+# .acme.yml
+compose:
+  secret_env: # the docker compose process's env, at stack up / restart
+    OPENAI_API_KEY: shop/dev_personal/OPENAI_API_KEY
+services:
+  worker:
+    secret_env: # the env of this service's own up / restart command
+      STRIPE_KEY: Engineering/Stripe Test/secret key
+```
+
+Each value is a fully qualified ref, `<vault>/<item>/<field>`:
+
+| Provider    | `a/b/c` means                                                              |
+| ----------- | -------------------------------------------------------------------------- |
+| `doppler`   | `--project a --config b`, key `c` (`secrets.doppler` is not consulted)     |
+| `1password` | vault `a`, item `b`, field `c`                                             |
+| `env`       | the env var `c` of the process running Den (`secrets.keys` is not applied) |
+
+A `compose.secret_env` key reaches a container only through the compose
+file: `${OPENAI_API_KEY}` in it, or a pass-through `environment:
+[OPENAI_API_KEY]`.
+
+- **When.** `up` and `restart`, including `restart <repo>/<service>` of one
+  compose service (`stack up`, `stack restart`, `stack restart --service`),
+  from the CLI, the web UI and MCP. Every key is resolved before anything
+  stops or starts.
+- **Missing.** A key the provider cannot resolve (unset, empty, no access)
+  fails that target, exit 1, naming the key, the ref and the provider. The
+  rest of the set is not used: nothing starts with a partial set, and a
+  restart leaves the old instance running.
+- **Where values go.** Only into the spawned process's env (the docker
+  compose process, or the service's command). Never into the generated
+  compose override, logs, activity records, MCP output, dry runs or
+  messages. A CLI-tabs (`cli_tabs`) start of a service with `secret_env`
+  runs as a daemon, since a tab would put them in its shell history.
+- **Dry run.** `-n`/`--dry-run` never asks the provider. It lists the key
+  names it would inject: `shop: would inject secret_env compose:
+OPENAI_API_KEY (names only; not resolved in a dry run)`.
+- **Validation.** `<cli> validate` rejects a ref that is not exactly three
+  non-empty parts and a key that is not an env var name
+  (`[A-Za-z_][A-Za-z0-9_]*`). A `stacks:` entry in the org config takes
+  `secret_env` too.
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -329,7 +397,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 \
@@ -407,6 +508,20 @@ 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}'
+```
+
+`--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
 
 Without an `mcp:` block in the org config (`config/<name>.yml`) only the read

package/package.json

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

package/scripts/setup-secrets.ts

@@ -72,6 +72,17 @@ async function main(): Promise<number> {
     const r = await provider.preflight();
     if (r.ok) return 0;
     if (gate && !cfg.required) {
+      // Signed in but no default scope: secret_env refs name their own
+      // (<project>/<config>/<key>), so only the engine's own secrets lack one.
+      if (await provider.isReady()) {
+        console.error(
+          chalk.gray(
+            `   ${label}: signed in, no default scope set (secret_env refs still resolve;` +
+              ` test logins and the saved sudo password need one: \`make ${product().cli}-setup-secrets\`).`,
+          ),
+        );
+        return 0;
+      }
       console.error(
         chalk.yellow(
           `⚠️  ${label} is not ready — continuing.\n` +

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) ──────────────────────────────────────────────
 
 /**