@monster-orange/den 0.2.8 → 0.4.0

package/src/shared/den-config.ts

@@ -243,6 +243,11 @@ export interface DenConfig {
    * only; `actions` opts in to named actions. See readMcpConfig.
    */
   mcp?: McpConfig;
+  /**
+   * Agents: `max_concurrent` caps the sessions running at once in this
+   * distribution (default 4). See readAgentsConfig.
+   */
+  agents?: AgentsConfig;
   /**
    * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
    * the launchd service `<cli> service` installs. See readWebServiceConfig.
@@ -341,6 +346,33 @@ export interface UserConfig {
     density?: string;
     panelWidth?: number;
   };
+  /**
+   * Web UI appearance: theme id and mode (system | dark | light), set from
+   * the header. See src/ui/server/appearance-prefs.ts.
+   */
+  appearance?: { theme?: string; mode?: string };
+  /**
+   * The web UI's language (R19): en (the default, never stored), ja or es.
+   * See src/ui/server/ui-language.ts.
+   */
+  language?: string;
+  /**
+   * The rail's pins and collapse, and (R21 Navigation) the pages it hides
+   * and their order (src/ui/server/shell-prefs.ts).
+   */
+  shell?: {
+    pins?: string[];
+    collapsed?: boolean;
+    hidden?: string[];
+    order?: string[];
+  };
+  /**
+   * What the web UI and `<cli> status` show: `scope` is "all" (every active
+   * workspace, the default) or one active workspace's name. A view filter
+   * only: the focused workspace stays the default target for commands. See
+   * src/shared/environment-manager/scope.ts.
+   */
+  view?: { scope?: string };
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [
@@ -403,12 +435,34 @@ export function mergeUserConfig(patch: Partial<UserConfig>): UserConfig {
   return next;
 }
 
+/**
+ * A scaffold or docs placeholder rather than a real org: `your-github-org`,
+ * `your-org`, `<your-org>`, `<slug>`, `example-org`. Den treats it as unset.
+ */
+export function isPlaceholderGithubOrg(org: string): boolean {
+  return /^(your[-_]?(github[-_]?)?org|<.*>|example[-_]?org)$/i.test(
+    org.trim(),
+  );
+}
+
+/**
+ * The configured `github_org`, or null when it is unset or still a
+ * placeholder ("not configured": Den runs no gh for it).
+ */
+export function configuredGithubOrg(
+  config: DenConfig = readDenConfig(),
+): string | null {
+  const org =
+    typeof config.github_org === "string" ? config.github_org.trim() : "";
+  return org && !isPlaceholderGithubOrg(org) ? org : null;
+}
+
 /**
  * The GitHub org managed repos clone from. Den has no default: an org that
  * needs one sets `github_org` in its config.
  */
 export function requireGithubOrg(config: DenConfig = readDenConfig()): string {
-  const org = config.github_org?.trim();
+  const org = configuredGithubOrg(config);
   if (!org)
     throw new Error(
       `github_org is not set: add \`github_org: <your-org>\` to ${DEN_CONFIG_PATH}`,
@@ -448,7 +502,19 @@ export function assertDenConfigValid(): void {
     }
     checked = { key, error };
   }
-  if (checked.error) throw new ConfigError(checked.error.message);
+  if (checked.error) throw new ConfigError(checked.error.issues);
+}
+
+let orgsWaived = false;
+
+/**
+ * For `down` only (0.3.0-dev.40): from now on in this process, a config
+ * whose `orgs:` fails validation reads as one with no org data instead of
+ * throwing, so stopping is never stranded by it. Every other key is read as
+ * usual; a file that does not parse still throws.
+ */
+export function waiveInvalidOrgs(): void {
+  orgsWaived = true;
 }
 
 /**
@@ -463,7 +529,13 @@ export function readDenConfig(): DenConfig {
     const parsed = yaml.parse(raw) as Partial<DenConfig> | null;
     // ORG-1d keys (orgs.<id>.sources / .repos) are checked here, where a bad
     // value throws naming its key; configs without them are not touched.
-    validateOrgSources(parsed?.orgs, product().configFile);
+    let orgs = parsed?.orgs;
+    try {
+      validateOrgSources(orgs, product().configFile);
+    } catch (e) {
+      if (!orgsWaived || !isConfigError(e)) throw e;
+      orgs = undefined;
+    }
     // `environments` may be malformed (scalar/object) in a hand-edited file —
     // fall back to the default set rather than throwing on .filter below.
     const envs = Array.isArray(parsed?.environments)
@@ -476,7 +548,7 @@ export function readDenConfig(): DenConfig {
       production_envs: parsed?.production_envs,
       repos_root: parsed?.repos_root,
       github_org: parsed?.github_org,
-      orgs: parsed?.orgs,
+      orgs,
       graph: parsed?.graph,
       org: parsed?.org,
       applications: parsed?.applications,
@@ -485,6 +557,7 @@ export function readDenConfig(): DenConfig {
       env_health_urls: parsed?.env_health_urls,
       security: parsed?.security,
       mcp: parsed?.mcp,
+      agents: parsed?.agents,
       web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
@@ -662,6 +735,116 @@ export function readMcpConfig(
   };
 }
 
+// ── Agents (`<cli> sessions`, `<cli> agents`) ─────────────────────────────────
+
+/** `agents:` in the org config. */
+export interface AgentsConfig {
+  /** Sessions that may run at once (default 4). */
+  max_concurrent?: number;
+  /**
+   * Persona packs (AG-2a): directories of persona files, relative to the
+   * distribution root. Den's default pack is always read first; a pack's
+   * persona replaces one of the same id.
+   */
+  persona_packs?: string[];
+  /**
+   * Any other key is an agent id: `agents.<id>.grants` widens that agent's
+   * MCP scope to other workspaces (AG spec §5b). Config only: an agent
+   * never grants itself one.
+   */
+  [agentId: string]: unknown;
+}
+
+export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
+
+/** The keys of `agents:` that are not an agent id. */
+export const AGENTS_RESERVED_KEYS = ["max_concurrent", "persona_packs"];
+
+/** One agent's own block, `agents.<id>`. */
+export interface AgentGrantsConfig {
+  /** Workspaces beyond its own that its MCP serves. */
+  grants: string[];
+}
+
+/** `agents:` with its defaults applied. */
+export interface ResolvedAgentsConfig {
+  maxConcurrent: number;
+  /** As configured (relative to the distribution root). */
+  personaPacks: string[];
+  /** `agents.<id>` blocks, by agent id. */
+  agents: Record<string, AgentGrantsConfig>;
+}
+
+/** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
+const AGENT_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+const isMapping = (v: unknown): v is Record<string, unknown> =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * The effective agents config. Anything malformed throws, naming the key:
+ * a typo must not lift the cap, drop a pack or widen a grant.
+ */
+export function readAgentsConfig(
+  config: DenConfig = readDenConfig(),
+): ResolvedAgentsConfig {
+  const raw = (config.agents ?? {}) as unknown;
+  if (!isMapping(raw))
+    throw new Error(`agents: must be a mapping (got ${JSON.stringify(raw)})`);
+  const out: ResolvedAgentsConfig = {
+    maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
+    personaPacks: [],
+    agents: {},
+  };
+  const max = raw.max_concurrent;
+  if (max !== undefined) {
+    if (typeof max !== "number" || !Number.isInteger(max) || max < 1)
+      throw new Error(
+        `agents.max_concurrent: must be a whole number of at least 1 (got ${JSON.stringify(max)})`,
+      );
+    out.maxConcurrent = max;
+  }
+  const packs = raw.persona_packs;
+  if (packs !== undefined && packs !== null) {
+    if (!Array.isArray(packs))
+      throw new Error(
+        `agents.persona_packs: must be a list of paths (got ${JSON.stringify(packs)})`,
+      );
+    packs.forEach((p, i) => {
+      if (typeof p !== "string" || !p.trim())
+        throw new Error(
+          `agents.persona_packs[${i}]: must be a non-empty path (got ${JSON.stringify(p)})`,
+        );
+    });
+    out.personaPacks = packs as string[];
+  }
+  for (const [id, block] of Object.entries(raw)) {
+    if (AGENTS_RESERVED_KEYS.includes(id)) continue;
+    const where = `agents.${id}`;
+    if (!AGENT_KEY_RE.test(id) || !isMapping(block))
+      throw new Error(
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, ` +
+          `or an agent id mapping to { grants: [...] })`,
+      );
+    for (const k of Object.keys(block))
+      if (k !== "grants")
+        throw new Error(`${where}.${k}: unknown key (an agent takes grants)`);
+    const grants = block.grants ?? [];
+    if (!Array.isArray(grants))
+      throw new Error(
+        `${where}.grants: must be a list of workspace names (got ${JSON.stringify(grants)})`,
+      );
+    grants.forEach((g, i) => {
+      if (typeof g !== "string" || !AGENT_KEY_RE.test(g))
+        throw new Error(
+          `${where}.grants[${i}]: ${JSON.stringify(g)} is not a workspace name`,
+        );
+    });
+    out.agents[id] = { grants: [...new Set(grants as string[])] };
+  }
+  return out;
+}
+
 // ── Web UI service (`<cli> service`) ──────────────────────────────────────────
 
 /** `web:` in the org config. */
@@ -680,6 +863,11 @@ export interface ResolvedWorkspaceBlueprint {
   focus: boolean;
   /** `org:` (ORG-1a): the org this workspace belongs to, when the blueprint names one. */
   org?: string;
+  /**
+   * `stack_namespace:`: the Compose project suffix this workspace's stacks
+   * run under, in place of its own name (see stacks/namespace.ts).
+   */
+  stackNamespace?: string;
 }
 
 /** Which blueprint shape the distribution uses, and its workspaces. */
@@ -688,7 +876,32 @@ export interface WorkspaceBlueprints {
   workspaces: ResolvedWorkspaceBlueprint[];
 }
 
-const BLUEPRINT_KEYS = ["branch", "repos", "autostart_off", "org"];
+const BLUEPRINT_KEYS = [
+  "branch",
+  "repos",
+  "autostart_off",
+  "org",
+  "stack_namespace",
+];
+
+/**
+ * A stack namespace (and a Compose project suffix): lowercase letters,
+ * digits and dashes, not starting or ending with a dash.
+ */
+export const STACK_NAMESPACE_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+/** `v` as a stack namespace, or undefined when unset; throws naming `key`. */
+export function checkStackNamespace(
+  key: string,
+  v: unknown,
+): string | undefined {
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string" || !STACK_NAMESPACE_RE.test(v))
+    throw new Error(
+      `${key} must be lowercase letters, digits and dashes (got ${JSON.stringify(v)})`,
+    );
+  return v;
+}
 
 function blueprintStrings(where: string, key: string, v: unknown): string[] {
   if (v === undefined) return [];
@@ -720,6 +933,10 @@ function resolveBlueprint(
     throw new Error(`${where}.focus must be true or false`);
   if (bp.org !== undefined && (typeof bp.org !== "string" || !bp.org.trim()))
     throw new Error(`${where}.org must be an org id (a key of orgs:)`);
+  const stackNamespace = checkStackNamespace(
+    `${where}.stack_namespace`,
+    bp.stack_namespace,
+  );
   return {
     name,
     repos: blueprintStrings(where, "repos", bp.repos),
@@ -727,9 +944,44 @@ function resolveBlueprint(
     autostartOff: blueprintStrings(where, "autostart_off", bp.autostart_off),
     focus: bp.focus === true,
     ...(typeof bp.org === "string" ? { org: bp.org.trim() } : {}),
+    ...(stackNamespace ? { stackNamespace } : {}),
   };
 }
 
+/**
+ * Each blueprint workspace's `stack_namespace`, by workspace name (the
+ * single `defaults.workspace` is `default`). Reads only that key, so a
+ * blueprint malformed elsewhere still gives its namespaces: the stacks'
+ * Compose projects never fall back to another name because of an unrelated
+ * error. A bad `stack_namespace` itself throws, naming the key.
+ */
+export function readBlueprintStackNamespaces(
+  config: DenConfig = readDenConfig(),
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const defaults: unknown = config.defaults;
+  if (!defaults || typeof defaults !== "object" || Array.isArray(defaults))
+    return out;
+  const { workspace, workspaces } = defaults as Record<string, unknown>;
+  const take = (where: string, name: string, raw: unknown) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+    const ns = checkStackNamespace(
+      `${where}.stack_namespace`,
+      (raw as Record<string, unknown>).stack_namespace,
+    );
+    if (ns) out[name] = ns;
+  };
+  if (
+    workspaces &&
+    typeof workspaces === "object" &&
+    !Array.isArray(workspaces)
+  )
+    for (const [name, raw] of Object.entries(workspaces))
+      take(`defaults.workspaces.${name}`, name, raw);
+  else if (workspace != null) take("defaults.workspace", "default", workspace);
+  return out;
+}
+
 /**
  * The distribution's workspace blueprint, validated: `defaults.workspace`
  * (one workspace, `default`) or `defaults.workspaces` (named workspaces).

package/src/shared/edge/config.ts

@@ -12,9 +12,17 @@
  *     publish: true          # false: another proxy fronts the edge
  *     http_port: 80
  *     https_port: 443
+ *     tls: none              # http only; or (see tls.ts):
+ *     #   tls: { strategy: mkcert }                   # own local CA, per machine
+ *     #   tls: { strategy: mkcert, ca: ~/path/to/ca } # an existing CA; never minted
+ *     #   tls: { strategy: files, include: edge/dynamic, mounts: {...} }
+ *     #        # included config holds the certs; optional ca: the CA that
+ *     #        # signed them, trusted by health checks
+ *     # legacy (still read, mapped to tls, deprecated):
+ *     #   caroot: <ca>       → tls: { strategy: mkcert, ca: <ca> }
+ *     #   issue_cert: false  → tls: { strategy: files }
+ *     #   neither, no tls    → mkcert with a local CA, and a warning
  *     # opt-ins (all off by default):
- *     caroot: ~/path/to/mkcert-ca   # use an existing CA; never mint one
- *     issue_cert: false             # included config holds the certs
  *     https_redirect: false         # included config redirects per name
  *     docker_labels: { network: apps-network }
  *     include: edge/dynamic         # dynamic-config files, repo-relative
@@ -35,7 +43,8 @@ import { cachedRead } from "../read-cache.js";
 import { readManifestStacks } from "../stacks/config.js";
 import { getActiveWorkspaces } from "../environment-manager/workspaces.js";
 import { assertDomain } from "./render.js";
-import type { EdgeConfig } from "./types.js";
+import { tlsStrategyIds } from "./tls.js";
+import type { EdgeConfig, EdgeTls } from "./types.js";
 
 import { product } from "../product.js";
 export const DEFAULT_TRAEFIK_IMAGE = "traefik:v3.7.17";
@@ -51,6 +60,7 @@ interface RawEdge {
   publish?: boolean;
   http_port?: number;
   https_port?: number;
+  tls?: unknown;
   caroot?: string;
   issue_cert?: boolean;
   https_redirect?: boolean;
@@ -120,6 +130,108 @@ function mounts(v: RawEdge["mounts"], root: string): Record<string, string> {
   return out;
 }
 
+const TLS_KEYS: Record<string, string[]> = {
+  none: ["strategy"],
+  mkcert: ["strategy", "ca"],
+  files: ["strategy", "ca", "include", "mounts"],
+};
+
+interface ResolvedTls {
+  tls: EdgeTls;
+  from: EdgeConfig["tlsFrom"];
+  /** `files`' own include and mounts (raw, resolved by the caller). */
+  include?: string;
+  mounts?: Record<string, string>;
+}
+
+/**
+ * `edge.tls` (user.yml's replaces the team's), or the legacy keys mapped to
+ * it (EXT-1 rule 6): `issue_cert: false` → files, `caroot` → mkcert with
+ * `ca`, neither → mkcert with a local CA (implicit, warned).
+ */
+function readTls(team: RawEdge, user: RawEdge, root: string): ResolvedTls {
+  const raw = user.tls ?? team.tls;
+  const caroot = user.caroot ?? team.caroot;
+  const issue = user.issue_cert ?? team.issue_cert;
+  const ids = tlsStrategyIds();
+  const builtIns = ids.join(", ");
+  if (raw === undefined) {
+    const ca = caroot ? resolvePath(caroot, root) : null;
+    return {
+      tls:
+        issue === false
+          ? { strategy: "files", ca }
+          : { strategy: "mkcert", ca },
+      from: caroot === undefined && issue === undefined ? "implicit" : "legacy",
+    };
+  }
+  const legacy = [
+    ...(caroot !== undefined ? ["caroot"] : []),
+    ...(issue !== undefined ? ["issue_cert"] : []),
+  ];
+  if (legacy.length)
+    throw new Error(
+      `edge.tls replaces edge.${legacy.join(" and edge.")}; remove ${legacy.length > 1 ? "them" : "it"} ` +
+        "(caroot is tls.ca, issue_cert: false is tls.strategy: files).",
+    );
+  const obj: Record<string, unknown> =
+    typeof raw === "string"
+      ? { strategy: raw }
+      : raw && typeof raw === "object" && !Array.isArray(raw)
+        ? (raw as Record<string, unknown>)
+        : {};
+  const id = obj.strategy;
+  if (typeof id !== "string" || !id)
+    throw new Error(
+      `edge.tls must be a strategy id or { strategy: <id>, ... }; the built-ins are ${builtIns}`,
+    );
+  if (!ids.includes(id))
+    throw new Error(
+      `edge.tls.strategy "${id}" is not a known TLS strategy; the built-ins are ${builtIns}`,
+    );
+  const allowed = TLS_KEYS[id] ?? ["strategy"];
+  for (const k of Object.keys(obj))
+    if (!allowed.includes(k))
+      throw new Error(
+        `edge.tls.${k} does not apply to strategy ${id} (it takes ${allowed.join(", ")})`,
+      );
+  let ca: string | null = null;
+  if (obj.ca !== undefined) {
+    if (typeof obj.ca !== "string" || !obj.ca.trim())
+      throw new Error(
+        "edge.tls.ca must be the path to an existing CA directory",
+      );
+    ca = resolvePath(obj.ca, root);
+  }
+  if (
+    obj.include !== undefined &&
+    (typeof obj.include !== "string" || !obj.include)
+  )
+    throw new Error(
+      "edge.tls.include must be a directory of dynamic-config files",
+    );
+  if (
+    obj.mounts !== undefined &&
+    (!obj.mounts || typeof obj.mounts !== "object" || Array.isArray(obj.mounts))
+  )
+    throw new Error("edge.tls.mounts must map host paths to container paths");
+  const tls: EdgeTls =
+    id === "none"
+      ? { strategy: "none" }
+      : { strategy: id as "mkcert" | "files", ca };
+  return {
+    tls,
+    from: "explicit",
+    include: obj.include as string | undefined,
+    mounts: obj.mounts as Record<string, string> | undefined,
+  };
+}
+
+/** True when the org config has an `edge:` block (an edge is configured). */
+export function hasEdgeBlock(root: string = getDistRoot()): boolean {
+  return layers(root).team.edge !== undefined;
+}
+
 /** The web UI's route name: the brand name as a slug ("Den" → "den"). */
 function webRouteName(team: Record<string, unknown>): string {
   const name = (team.brand as { name?: string } | undefined)?.name?.trim();
@@ -188,6 +300,22 @@ function computeEdgeConfig(root: string): EdgeConfig {
     throw new Error("edge.aliases must be a list of domains");
   aliases.forEach(assertDomain);
   const publish = user.publish ?? team.publish ?? true;
+  const tls = readTls(team, user, root);
+  if (tls.include !== undefined && team.include !== undefined)
+    throw new Error(
+      "edge.include and edge.tls.include are both set; keep one (tls.include for files' certs)",
+    );
+  const include = tls.include ?? team.include;
+  // The state dir the config names (or the XDG default), DEN_EDGE_DIR aside.
+  const configuredStateDir = expandHome(
+    user.state_dir ??
+      team.state_dir ??
+      path.join(
+        process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"),
+        team.org,
+        "edge",
+      ),
+  );
   return {
     org: team.org,
     domain: team.domain,
@@ -214,26 +342,24 @@ function computeEdgeConfig(root: string): EdgeConfig {
           ),
         }
       : null,
-    stateDir: expandHome(
-      process.env.DEN_EDGE_DIR ??
-        user.state_dir ??
-        team.state_dir ??
-        path.join(
-          process.env.XDG_DATA_HOME ||
-            path.join(os.homedir(), ".local", "share"),
-          team.org,
-          "edge",
-        ),
-    ),
-    caroot:
-      (user.caroot ?? team.caroot)
-        ? resolvePath((user.caroot ?? team.caroot)!, root)
-        : null,
-    issueCert: (user.issue_cert ?? team.issue_cert) !== false,
+    stateDir:
+      process.env.DEN_EDGE_DIR !== undefined
+        ? expandHome(process.env.DEN_EDGE_DIR)
+        : configuredStateDir,
+    // Set only when DEN_EDGE_DIR overrides it: the dir the config names.
+    ...(process.env.DEN_EDGE_DIR !== undefined &&
+    expandHome(process.env.DEN_EDGE_DIR) !== configuredStateDir
+      ? { defaultStateDir: configuredStateDir }
+      : {}),
+    tls: tls.tls,
+    tlsFrom: tls.from,
     httpsRedirect: (user.https_redirect ?? team.https_redirect) !== false,
     dockerLabels: dockerLabels(user.docker_labels ?? team.docker_labels),
-    include: team.include ? resolvePath(team.include, root) : null,
-    mounts: mounts({ ...(team.mounts ?? {}), ...(user.mounts ?? {}) }, root),
+    include: include ? resolvePath(include, root) : null,
+    mounts: mounts(
+      { ...(team.mounts ?? {}), ...(user.mounts ?? {}), ...(tls.mounts ?? {}) },
+      root,
+    ),
     networks: [
       ...new Set([
         ...list(team.networks, "networks"),

package/src/shared/edge/exec.ts

@@ -0,0 +1,31 @@
+/** Running the edge's CLIs (docker, mkcert): one place, one error shape. */
+import { spawnSync } from "child_process";
+
+export function sh(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv; inherit?: boolean } = {},
+) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf-8",
+    env: { ...process.env, ...opts.env },
+    stdio: opts.inherit ? "inherit" : "pipe",
+  });
+  if (r.error) throw new Error(`${cmd} is not installed (${r.error.message})`);
+  return {
+    code: r.status ?? 1,
+    out: (r.stdout ?? "").trim(),
+    err: (r.stderr ?? "").trim(),
+  };
+}
+
+export function must(
+  cmd: string,
+  args: string[],
+  opts: { env?: NodeJS.ProcessEnv } = {},
+): string {
+  const r = sh(cmd, args, opts);
+  if (r.code !== 0)
+    throw new Error(`${cmd} ${args.join(" ")} failed:\n${r.err || r.out}`);
+  return r.out;
+}