@monster-orange/den 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,103 @@ 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.5] - 2026-11-04
+
+### Fixed
+
+- **`<cli> web down` (any SIGTERM) shuts the web server down cleanly
+  under load.** `<cli> web up` ran the server under the `tsx` CLI, a
+  parent process that relays a signal to the server and, if the server has
+  not acknowledged it within about 60ms, SIGKILLs it and exits 143. On a
+  loaded machine the server missed that window, so it was killed without
+  its shutdown. The server now runs as `node --import <tsx loader>`, one
+  process that gets the signal itself, as the launchd service already did.
+- **Compose-stack health no longer starts a CLI per check.** Den's own
+  check for a compose repo was a `<cli> stack health <stack> --service X`
+  process per manifest service, each a full CLI start running its own
+  `docker ps`: 17-19 processes per health cycle for three stacks. On a
+  loaded machine (load 35-55) they ran past their budget, and two such
+  cycles in a row read every stack down. These checks are now answered
+  in the web server and in `<cli> status` from one `docker ps` per cycle,
+  shared by every check in it (17 checks: 17 CLI starts and 17 docker
+  calls per cycle before, 0 and 1 now). The verdict is the one `stack
+  health` gives. A distribution's own shell checks still run as shell
+  commands, at most max(2, cpus/2) at a time; a queued check's budget
+  starts when it starts.
+- **The health row no longer shows healthy repos down on a cold poll.** A
+  check that got no answer within its budget was sent as a finished
+  `ok: false`: a compose stack's check (`<cli> stack health`, a full CLI
+  start per service, 15-20 of them at once) past its 5s budget on a loaded
+  machine, or an HTTP check past its 3s timeout. The row painted it red
+  and the 8s health cache replayed that to the next page load, until the
+  next poll corrected it. Now a check that has not answered is **pending**
+  (`ok: null`, `pending: true`, the reason in `error`), never down. Only a
+  check that completed and failed is `ok: false`. A timeout is down only
+  when it repeats on the next cycle (`timeout (twice in a row)`), so a hung
+  service still shows. `<cli> status` agrees: on a timeout it probes once
+  more, and is down only when both probes time out. Health results have a
+  new `pending` state (`health: "pending"`), which readiness waits on
+  rather than skipping.
+- **"Docker state unknown" is not "not running".** When docker does not
+  answer, the health row and `<cli> status` report a compose stack as
+  unknown (`ok: null`), not down, and so does `/api/stacks`. `<cli> stack
+  health` exits 3 when it could not tell (docker did not answer, the stack
+  config could not be read), 1 only when a stack is not healthy.
+- **A health stream and a poll at once run each check once.** A stream
+  started its own full run next to an in-flight `/api/health` (or another
+  stream), doubling the shell checks' processes. It now joins the run in
+  flight, replaying what has landed and then following it.
+- The web header's dot for a multi-service repo without an entrypoint
+  turned red when none of its checks were up yet, even with none down. It
+  is red now only when a check completed and failed.
+
+- **The default workspace is seeded only on a genuine fresh setup.** Any
+  command that reads workspaces (`status`, `up`, `graph`, `logs`, …) seeded
+  `default` from `defaults.workspace.repos` whenever `default` was empty,
+  so moving every repo into per-project workspaces and deactivating
+  `default` got it refilled with managed entries on the next command, ready
+  to clone duplicates of repos you work on locally. Seeding now requires
+  that no workspace but `default` exists and that `default` was never
+  seeded (no `seeded_repos`). Declining the offer records that too, so it
+  is no longer asked again.
+- **No silent seeding without a TTY.** On a fresh setup a command without
+  a TTY now prints a one-line hint to run `<cli> workspace seed` and
+  changes nothing; on a TTY the offer stays. New: `<cli>
+  workspace seed` seeds explicitly (as `<cli> init` in the root does).
+- **Top-up no longer re-adds repos you moved or removed.** Top-up (adding
+  repos that joined the blueprint after seeding) never runs once you have
+  other workspaces, and skips a repo any workspace holds. Removing a
+  blueprint repo from `default` in the web UI records it, so a `default`
+  from before `seeded_repos` no longer gets it back on its one-time
+  migration.
+
+### Added
+
+- **The "What's new" pop-up shows the newest release only** (from
+  0.3.0-dev.16). A "Show all versions (N earlier)" button in its footer
+  lists every earlier version in the same pop-up, and "Show latest only"
+  collapses it again. It always opens collapsed, at the top: the scroll is
+  reset once the pop-up is shown (a reset made while it was hidden did not
+  stick, so a reopened pop-up kept its old scroll position). It is an
+  accessible modal dialog (`role="dialog"`, `aria-modal`, labelled by its
+  title). Opening moves focus to its heading, so a screen reader starts at
+  the latest notes. Tab stays inside, and closing returns focus to what had
+  it, which is the version pill after the first-visit auto-open. Each
+  version is a heading (h4) for heading navigation, and the icon buttons
+  have spoken names ("Close", "Copy v0.2.5 as Markdown").
+- **The version pill names the running build** (`v0.2.5-dev.2`), not the
+  newest changelog heading, so a prerelease under test says what it is.
+- **Multi-workspace blueprint: `defaults.workspaces`.** `{ <name>: {
+  repos, branch?, autostart_off?, focus? } }` in the org config. A fresh
+  setup creates each workspace with its repos (managed), activates them
+  all and focuses the one with `focus: true` (else the first). Setting
+  both `defaults.workspace` and `defaults.workspaces` is an error, as is a
+  malformed entry. See docs/distributions.md, "Workspace blueprint".
+
+### Migrations
+
+- None required.
+
 ## [0.2.4] - 2026-11-04
 
 ### Fixed

package/docs/distributions.md

@@ -327,6 +327,54 @@ brand:
 Runtime names (env vars, files, directories) always come from `den.yml`,
 never from the brand.
 
+## Workspace blueprint
+
+The workspaces a new machine starts with. Read from `defaults:` in the org
+config. Every repo is seeded as a managed clone (`mode: managed`) on the
+blueprint's branch; nothing is cloned until a command needs it. Switch a repo
+to a local checkout afterwards with `acme use-local <repo>`.
+
+One workspace, `default`:
+
+```yaml
+defaults:
+  workspace:
+    branch: main # default: main
+    repos: [shop-web, shop, infra-stack]
+    autostart_off: [shop] # seeded with autostart: false
+    entry: shop-web # where the setup script's dependency walk starts
+```
+
+Several named workspaces:
+
+```yaml
+defaults:
+  workspaces:
+    storefront:
+      repos: [shop-web, shop]
+    data:
+      repos: [warehouse, infra-stack]
+      branch: develop
+      focus: true
+```
+
+Each entry takes `repos`, `branch` and `autostart_off`, 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`.
+
+The blueprint applies only to a genuine fresh setup: no workspace except an
+empty `default` that was never seeded. On a TTY the first command that needs
+workspaces offers to seed. Without a TTY it prints a one-line hint and changes
+nothing. `acme workspace seed` (or `acme init` in the distribution root) seeds
+explicitly, and resets the blueprint's workspaces if they already hold repos.
+
+Once seeded, a repo that later joins `defaults.workspace.repos` is added to
+`default`, but only while `default` is your only workspace, and never a repo
+you removed from it or that another workspace holds. With
+`defaults.workspaces` nothing is topped up.
+
 ## The bin shim
 
 `bin/<cli>` is three lines of sh: it names the distribution root and runs
@@ -544,22 +592,22 @@ guard off.
 
 Read tools (always registered):
 
-| Tool                | Web API                                    | What                                                       |
-| ------------------- | ------------------------------------------ | ---------------------------------------------------------- |
-| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell)      |
-| `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); `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.4",
+  "version": "0.2.5",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/constants.ts

@@ -48,6 +48,13 @@ export const HOSTED_HEALTH_CHECK_TIMEOUT_MS = 10_000;
 /** Timeout for spawning short-lived CLI subprocesses (open, sudo, git). */
 export const CLI_SPAWN_TIMEOUT_MS = 5_000;
 
+/**
+ * Exit code of `<cli> stack health` when it could not tell (docker did not
+ * answer, the stack config could not be read): the check is unknown, not
+ * down. Any other non-zero exit means the containers are not healthy.
+ */
+export const STACK_HEALTH_UNKNOWN_EXIT = 3;
+
 /** Timeout for `gh api` calls (branch listing, repo search). */
 export const GH_API_TIMEOUT_MS = 15_000;
 

package/src/shared/den-config.ts

@@ -255,24 +255,35 @@ export interface DenConfig {
    * `default-workspace.ts`.
    */
   defaults?: {
-    workspace?: {
-      /** Branch managed clones track (default "main"). */
-      branch?: string;
-      /** Repo-system names to seed, all as managed clones. */
-      repos?: string[];
+    workspace?: WorkspaceBlueprint & {
       /** The entry repo the seed's dependency walk starts from (listed first). */
       entry?: string;
-      /**
-       * Seeded repos that get `autostart: false` stamped on their workspace
-       * entry — the team default for systems a fresh clone should not start
-       * with workspace up (e.g. billing-api's `make up` opens an interactive
-       * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
-       */
-      autostart_off?: string[];
     };
+    /**
+     * Multi-workspace blueprint: `{ <name>: { repos, focus?, branch?,
+     * autostart_off? } }`. On a genuine fresh setup each workspace is created
+     * with its repos (managed), all are activated, and the one marked
+     * `focus: true` (else the first) is focused. Exclusive with `workspace`.
+     */
+    workspaces?: Record<string, WorkspaceBlueprint & { focus?: boolean }>;
   };
 }
 
+/** One workspace's blueprint: the repo entries a fresh setup seeds it with. */
+export interface WorkspaceBlueprint {
+  /** Branch managed clones track (default "main"). */
+  branch?: string;
+  /** Repo-system names to seed, all as managed clones. */
+  repos?: string[];
+  /**
+   * Seeded repos that get `autostart: false` stamped on their workspace
+   * entry — the team default for systems a fresh clone should not start
+   * with workspace up (e.g. billing-api's `make up` opens an interactive
+   * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
+   */
+  autostart_off?: string[];
+}
+
 /**
  * Per-engineer preferences stored in config/local/user.yml (gitignored).
  * Only affects settings that should differ between engineers on the same team.
@@ -618,6 +629,113 @@ export interface WebConfig {
   service?: { label?: string; logs?: string };
 }
 
+/** A validated workspace blueprint with its defaults applied. */
+export interface ResolvedWorkspaceBlueprint {
+  name: string;
+  repos: string[];
+  branch: string;
+  autostartOff: string[];
+  focus: boolean;
+}
+
+/** Which blueprint shape the distribution uses, and its workspaces. */
+export interface WorkspaceBlueprints {
+  shape: "none" | "single" | "multi";
+  workspaces: ResolvedWorkspaceBlueprint[];
+}
+
+const BLUEPRINT_KEYS = ["branch", "repos", "autostart_off"];
+
+function blueprintStrings(where: string, key: string, v: unknown): string[] {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((r) => typeof r !== "string" || !r.trim()))
+    throw new Error(`${where}.${key} must be a list of repo names`);
+  return v as string[];
+}
+
+function resolveBlueprint(
+  where: string,
+  name: string,
+  raw: unknown,
+  /** Extra keys allowed; null skips the unknown-key check (legacy shape). */
+  extraKeys: string[] | null,
+): ResolvedWorkspaceBlueprint {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error(`${where} must be a map: { repos: [...] }`);
+  const bp = raw as Record<string, unknown>;
+  const known = [...BLUEPRINT_KEYS, ...(extraKeys ?? [])];
+  for (const key of Object.keys(bp))
+    if (extraKeys && !known.includes(key))
+      throw new Error(
+        `${where}: unknown key "${key}" (known: ${known.join(", ")})`,
+      );
+  const branch = bp.branch ?? "main";
+  if (typeof branch !== "string" || !branch.trim())
+    throw new Error(`${where}.branch must be a branch name`);
+  if (bp.focus !== undefined && typeof bp.focus !== "boolean")
+    throw new Error(`${where}.focus must be true or false`);
+  return {
+    name,
+    repos: blueprintStrings(where, "repos", bp.repos),
+    branch,
+    autostartOff: blueprintStrings(where, "autostart_off", bp.autostart_off),
+    focus: bp.focus === true,
+  };
+}
+
+/**
+ * The distribution's workspace blueprint, validated: `defaults.workspace`
+ * (one workspace, `default`) or `defaults.workspaces` (named workspaces).
+ * Empty when neither is set. Both at once, or a malformed value, throws.
+ */
+export function readWorkspaceBlueprints(
+  config: DenConfig = readDenConfig(),
+): WorkspaceBlueprints {
+  const none: WorkspaceBlueprints = { shape: "none", workspaces: [] };
+  const defaults: unknown = config.defaults;
+  if (defaults === undefined || defaults === null) return none;
+  if (typeof defaults !== "object" || Array.isArray(defaults))
+    throw new Error(`defaults in ${DEN_CONFIG_PATH} must be a map`);
+  const { workspace, workspaces } = defaults as Record<string, unknown>;
+  if (workspace != null && workspaces != null)
+    throw new Error(
+      `${DEN_CONFIG_PATH} sets both defaults.workspace and defaults.workspaces: ` +
+        "use defaults.workspaces alone (name the default workspace `default` in it), " +
+        "or defaults.workspace alone for a single default workspace",
+    );
+  if (workspaces != null) {
+    if (typeof workspaces !== "object" || Array.isArray(workspaces))
+      throw new Error(
+        "defaults.workspaces must be a map: { <name>: { repos: [...], focus?: true } }",
+      );
+    const resolved = Object.entries(workspaces as Record<string, unknown>).map(
+      ([name, raw]) => {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+          throw new Error(
+            `defaults.workspaces: "${name}" is not a valid workspace name (letters, digits, dots, dashes, underscores)`,
+          );
+        return resolveBlueprint(`defaults.workspaces.${name}`, name, raw, [
+          "focus",
+        ]);
+      },
+    );
+    const focused = resolved.filter((b) => b.focus);
+    if (focused.length > 1)
+      throw new Error(
+        `defaults.workspaces: only one workspace may set focus: true (got ${focused.map((b) => b.name).join(", ")})`,
+      );
+    return { shape: "multi", workspaces: resolved };
+  }
+  if (workspace != null)
+    return {
+      shape: "single",
+      workspaces: [
+        resolveBlueprint("defaults.workspace", "default", workspace, null),
+      ],
+    };
+  return none;
+}
+
 /** `web.service` with its defaults applied. */
 export interface ResolvedWebService {
   /** launchd label; also the plist's name in ~/Library/LaunchAgents. */

package/src/shared/engine.ts

@@ -37,6 +37,24 @@ export function engineBin(name: string, engineRoot = getEngineRoot()): string {
   }
 }
 
+/**
+ * A file inside a package Den depends on (e.g. "tsx/dist/loader.mjs"): the
+ * nearest node_modules/<rel> at or above the engine root, or null.
+ */
+export function engineModuleFile(
+  rel: string,
+  engineRoot = getEngineRoot(),
+): string | null {
+  let dir = path.resolve(engineRoot);
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", rel);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /** The tsx binary that runs Den's TypeScript sources. */
 export function tsxBin(): string {
   return engineBin("tsx");