@monster-orange/den 0.2.7 → 0.3.0

package/src/shared/auth/sudo-vault.ts

@@ -1,51 +1,56 @@
 /**
  * Secrets-backed persistence for the local-dev sudo password.
  *
- * Goes through the configured secrets strategy (Doppler, 1Password or env —
- * see src/shared/secrets), addressing the named ref `sudo` (default
- * OP_API_KEYS_VAULT / OP_DEV_KEYS_ITEM / OP_DEN_SUDO_FIELD; an org
- * moves it with `secrets.refs.sudo` in its config) — flat key
- * DEN_LOCAL_ADMIN_PWD for key/value backends.
+ * Goes through the configured secrets strategy (see src/shared/secrets),
+ * addressing the named ref `sudo`. There is no built-in location: a
+ * distribution that wants the saved password sets `secrets.refs.sudo` in its
+ * config. Without it, the vault path is "not configured" and only the
+ * interactive unlock is offered; nothing is spawned.
  *
  * All read helpers fail *soft*: if the backend isn't installed, the user isn't
- * signed in, or the value is missing, they return null/false so the server can
- * fall back to the manual unlock banner without surfacing CLI noise.
+ * signed in, the ref is not configured or the value is missing, they return
+ * null/false so the server can fall back to the manual unlock without
+ * surfacing CLI noise.
  */
 
-import {
-  OP_API_KEYS_VAULT,
-  OP_DEV_KEYS_ITEM,
-  OP_DEN_SUDO_FIELD,
-} from "../constants.js";
 import {
   getSecretsProvider,
   namedSecretRef,
+  notConfiguredMessage,
+  readSecretsConfig,
+  secretsStatus,
+  SecretsNotConfiguredError,
   type SecretRef,
+  type SecretsProviderName,
 } from "../secrets/index.js";
+import { product } from "../product.js";
 
-/** The built-in default for the `sudo` named ref. */
-export const SUDO_SECRET_REF: SecretRef = {
-  vault: OP_API_KEYS_VAULT,
-  item: OP_DEV_KEYS_ITEM,
-  field: OP_DEN_SUDO_FIELD,
-};
+/** Name of the sudo ref under `secrets.refs`. */
+export const SUDO_REF_NAME = "sudo";
 
-/** The effective sudo ref (`secrets.refs.sudo` over the default). */
-function sudoRef(): SecretRef {
-  return namedSecretRef("sudo", SUDO_SECRET_REF);
+/** The configured sudo ref, or null when `secrets.refs.sudo` is not set. */
+export function sudoRef(): SecretRef | null {
+  try {
+    return namedSecretRef(SUDO_REF_NAME, readSecretsConfig());
+  } catch {
+    return null;
+  }
 }
 
-/** True when the secrets backend is installed AND authenticated. */
+/** True when the sudo ref is configured AND its backend is ready. */
 export async function isSecretsBackendReady(): Promise<boolean> {
+  if (!sudoRef()) return false;
   return getSecretsProvider().isReady();
 }
 
 /** @deprecated use isSecretsBackendReady */
 export const isOpSignedIn = isSecretsBackendReady;
 
-/** Read the stored sudo password. Null when unavailable or empty. */
+/** Read the stored sudo password. Null when unavailable, unconfigured or empty. */
 export async function readSudoFromVault(): Promise<string | null> {
-  return getSecretsProvider().tryGet(sudoRef());
+  const ref = sudoRef();
+  if (!ref) return null;
+  return getSecretsProvider().tryGet(ref);
 }
 
 /** Whether a non-empty sudo password is stored (without returning it). */
@@ -55,15 +60,72 @@ export async function hasSudoInVault(): Promise<boolean> {
 
 /** Save (or overwrite) the sudo password. Throws on backend errors. */
 export async function saveSudoToVault(password: string): Promise<void> {
-  await getSecretsProvider().set(sudoRef(), password);
+  const ref = sudoRef();
+  if (!ref)
+    throw new SecretsNotConfiguredError(notConfiguredMessage(SUDO_REF_NAME));
+  await getSecretsProvider().set(ref, password);
+}
+
+/** What the UI's unlock form may offer: `/api/sudo-password/vault-status`. */
+export interface SudoVaultStatus {
+  /** The selected strategy id. */
+  backend: SecretsProviderName;
+  /** Name people see ("1Password"), for "Save to <label>". */
+  label: string;
+  /** `secrets.refs.sudo` is set for this backend. */
+  configured: boolean;
+  /**
+   * The backend can work here, whether or not a sudo ref is configured
+   * (`configured` says that). With no ref: detect() only (a PATH check,
+   * nothing spawned), and only for an explicitly chosen provider; an unset
+   * provider is never probed (it is not needed). With a ref: detect() and
+   * signed in.
+   */
+  backendAvailable: boolean;
+  /** Why it is not available (not configured, CLI not on PATH, signed out). */
+  reason?: string;
+  /** The distribution's org config file (e.g. config/acme.yml), for UI copy. */
+  configFile: string;
+  hasStored: boolean;
+  /** @deprecated alias of backendAvailable; removed in a later minor. */
+  opAvailable: boolean;
+}
+
+export async function sudoVaultStatus(): Promise<SudoVaultStatus> {
+  const cfg = readSecretsConfig();
+  const ref = sudoRef();
+  const pre = secretsStatus(cfg, process.env, { detect: false });
+  // Probe only what is needed or was chosen: a ref, or an explicit backend.
+  const probe = !!ref || (!pre.implicit && pre.backend !== "none");
+  const st = probe ? secretsStatus(cfg, process.env) : pre;
+  const out = (
+    backendAvailable: boolean,
+    hasStored: boolean,
+    reason?: string,
+  ): SudoVaultStatus => ({
+    backend: st.backend,
+    label: st.label,
+    configured: !!ref,
+    backendAvailable,
+    ...(reason ? { reason } : {}),
+    configFile: product().configFile,
+    hasStored,
+    opAvailable: backendAvailable,
+  });
+  if (!ref)
+    return out(
+      probe && st.detect.available,
+      false,
+      notConfiguredMessage(SUDO_REF_NAME),
+    );
+  if (!st.detect.available)
+    return out(false, false, `not available: ${st.detect.reason ?? ""}`.trim());
+  if (!(await getSecretsProvider().isReady()))
+    return out(false, false, `${st.label} is not signed in`);
+  return out(true, await hasSudoInVault());
 }
 
 /** Name of the active backend, for UI copy ("Save to Doppler"). */
 export function secretsBackendLabel(): string {
-  const n = getSecretsProvider().name;
-  return n === "1password"
-    ? "1Password"
-    : n === "doppler"
-      ? "Doppler"
-      : "environment";
+  return secretsStatus().label;
 }

package/src/shared/auth/token-providers/index.ts

@@ -115,9 +115,13 @@ const localJwtProvider: TokenProvider = {
     const l = cfg.auth?.localJwt;
     if (!l) throw new Error(`auth.localJwt is not set for ${cfg.name}`);
     const env = o.env ?? process.env;
+    // An explicit key the environment file names: not a default ref, so it
+    // resolves as it always has (env first, then the selected backend).
+    const fromEnv = env[l.secretKey];
+    const backend = fromEnv ? null : getSecretsProvider();
     const secret =
-      env[l.secretKey] ??
-      (await getSecretsProvider().tryGet({
+      fromEnv ??
+      (await backend!.tryGet({
         vault: "",
         item: "",
         field: l.secretKey,
@@ -125,7 +129,7 @@ const localJwtProvider: TokenProvider = {
       }));
     if (!secret) {
       throw new Error(
-        `local-jwt signing secret ${l.secretKey} not found in env or the secrets backend`,
+        `local-jwt signing secret ${l.secretKey} not found in env or the ${backend?.name ?? "configured"} secrets backend (secrets.provider)`,
       );
     }
     const ttl = l.ttlSeconds ?? 3600;

package/src/shared/brand.ts

@@ -8,6 +8,8 @@
  *     name: Acme Dev                 # shown in titles and the banner
  *     tagline: Acme local dev and E2E harness
  *     banner: [ "...", "..." ]       # optional ASCII art lines
+ *     theme: acme                    # the web UI's default theme (an id in
+ *                                    # plugins/<id>/, or den)
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -19,6 +21,8 @@ export interface BrandConfig {
   name: string;
   tagline: string;
   banner?: string[];
+  /** The web UI's default theme id; the user's appearance.theme wins. */
+  theme?: string;
 }
 
 export function defaultBrand(): BrandConfig {
@@ -43,6 +47,9 @@ export function readBrand(root: string = getDistRoot()): BrandConfig {
     name: raw.name?.trim() || fallback.name,
     tagline: raw.tagline?.trim() || fallback.tagline,
     banner: Array.isArray(raw.banner) ? raw.banner.map(String) : undefined,
+    ...(typeof raw.theme === "string" && raw.theme.trim()
+      ? { theme: raw.theme.trim() }
+      : {}),
   };
   return cached;
 }

package/src/shared/config-error.ts

@@ -0,0 +1,63 @@
+/**
+ * A distribution config that fails validation (ORG-1d's `orgs:` checks, for
+ * now). It is the user's to fix, not a crash: the CLI prints it and exits 1
+ * before doing anything, and the web server answers it as
+ * `{ ok: false, error, code: "config_invalid" }` with status 422.
+ *
+ * The message names config keys (`orgs.initech.repos`), never values a
+ * secret could hide in.
+ */
+/**
+ * One validation problem: the config file (as the distribution names it),
+ * the key path (`orgs.acme.sources[0].owner`) and what is wrong with it.
+ * `text` is the whole line after "<file>: ".
+ */
+export interface ConfigIssue {
+  file: string;
+  key: string;
+  message: string;
+  text: string;
+}
+
+export class ConfigError extends Error {
+  readonly code = "config_invalid";
+  /** Every problem found (0.3.0-dev.40), in config order. */
+  readonly issues: ConfigIssue[];
+
+  /**
+   * The message is one line per issue, "<file>: <text>". A plain string is
+   * one issue-less message.
+   */
+  constructor(issues: ConfigIssue[] | string) {
+    const list = typeof issues === "string" ? [] : issues;
+    super(
+      typeof issues === "string"
+        ? issues
+        : list.map((i) => `${i.file}: ${i.text}`).join("\n"),
+    );
+    this.name = "ConfigError";
+    this.issues = list;
+  }
+}
+
+export function isConfigError(e: unknown): e is ConfigError {
+  return e instanceof ConfigError;
+}
+
+/** The web server's status for a ConfigError: the request was fine, the config is not. */
+export const CONFIG_ERROR_STATUS = 422;
+
+/** The JSON body for a ConfigError (the `{ok, error, code}` frame R26 extends). */
+export function configErrorBody(e: ConfigError): {
+  ok: false;
+  error: string;
+  code: "config_invalid";
+  issues: Array<{ file: string; key: string; message: string }>;
+} {
+  return {
+    ok: false,
+    error: e.message,
+    code: e.code,
+    issues: e.issues.map(({ file, key, message }) => ({ file, key, message })),
+  };
+}

package/src/shared/constants.ts

@@ -5,17 +5,7 @@
  * If it's specific to one module (e.g. a Playwright config timeout), keep it local.
  */
 
-import { envKey } from "./product.js";
-// ── 1Password strategy (only used when secrets.provider: 1password) ──────────────────────────────────────────────────────────────
-
-/**
- * Default 1Password account domain used by every `op` invocation across den.
- * Kept in sync with the `OP_ACCOUNT ?= …` default in the Makefile. Scripts that
- * may run outside `make` (setup-1password, auth-configure)
- * set `process.env.OP_ACCOUNT ||= OP_ACCOUNT_DEFAULT` at entry so op picks up
- * the right account even when invoked directly via `npx tsx`.
- */
-export const OP_ACCOUNT_DEFAULT = "example.1password.com";
+// ── Test accounts ─────────────────────────────────────────────────────────────
 
 /**
  * Default vault for shared test accounts. Deprecated: the vault is org data —
@@ -24,19 +14,8 @@ export const OP_ACCOUNT_DEFAULT = "example.1password.com";
  */
 export const OP_TEST_VAULT = "test-accounts";
 
-/** Vault containing per-engineer API keys (1Password's built-in personal vault). */
-export const OP_API_KEYS_VAULT = "Employee";
-
-/** Item within OP_API_KEYS_VAULT holding the developer's API keys. */
-export const OP_DEV_KEYS_ITEM = "Developer API Keys";
-
-/**
- * Field within OP_DEV_KEYS_ITEM where the user's local admin (sudo) password
- * is optionally stored. Populated when the user checks "Save to 1Password" on
- * the den local-dev unlock banner; read on server startup so subsequent
- * sessions unlock without prompting.
- */
-export const OP_DEN_SUDO_FIELD = `${envKey("LOCAL_ADMIN_PWD")}`;
+// No 1Password account, vault, item or field is built in: a distribution
+// names its own in `secrets` (src/shared/secrets).
 
 // ── Timeouts ─────────────────────────────────────────────────────────────────
 

package/src/shared/den-config.ts

@@ -16,6 +16,8 @@ import type { Environment, ReleaseSourceConfig } from "./types/index.js";
 import { getDistRoot } from "./paths.js";
 import type { SecretsConfig } from "./secrets/index.js";
 import type { OrgConfig } from "./org.js";
+import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
+import { ConfigError, isConfigError } from "./config-error.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -194,11 +196,13 @@ export interface DenConfig {
   /** GitHub org slug used to list org repos in the web UI (e.g. "Globex-Corp"). */
   github_org?: string;
   /**
-   * Display names (and an optional colour) for the GitHub orgs repos belong
-   * to, keyed by GitHub owner. Orgs are worked out from the catalog; this
-   * only names them.
+   * Work orgs, keyed by org id: a display name and an optional colour. An
+   * entry with neither `sources` nor `repos` is the GitHub owner of its own
+   * name (ORG-1a). ORG-1d: `sources: [{host, owner|group}]` binds the org to
+   * git-host owners, and `repos: [...]` lists repos outright. See
+   * src/shared/org-sources.ts.
    */
-  orgs?: Record<string, { label?: string; color?: string }>;
+  orgs?: WorkOrgsConfig;
   /** Derived-dependency-graph tuning (aliases + edge overrides). */
   graph?: GraphConfig;
   /**
@@ -337,6 +341,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[] = [
@@ -399,12 +430,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}`,
@@ -412,6 +465,53 @@ export function requireGithubOrg(config: DenConfig = readDenConfig()): string {
   return org;
 }
 
+let checked: { key: string; error: ConfigError | null } | null = null;
+
+/**
+ * Throw the config's validation error (a ConfigError naming its keys), if it
+ * has one, without reading anything else. The CLI runs this before any
+ * command that touches orgs, the catalog, clones or releases, and the web
+ * server before every config-reading route, so a config that fails
+ * validation stops them all, not only those that happen to read `orgs:`.
+ * A missing file, or one that does not parse, is left to readDenConfig.
+ * Memoised on the file's mtime and size: the server checks per request.
+ */
+export function assertDenConfigValid(): void {
+  let key: string;
+  try {
+    const st = fs.statSync(DEN_CONFIG_PATH);
+    key = `${st.mtimeMs}:${st.size}`;
+  } catch {
+    return;
+  }
+  if (checked?.key !== key) {
+    let error: ConfigError | null = null;
+    try {
+      const parsed = yaml.parse(fs.readFileSync(DEN_CONFIG_PATH, "utf-8")) as {
+        orgs?: unknown;
+      } | null;
+      validateOrgSources(parsed?.orgs, product().configFile);
+    } catch (e) {
+      if (!isConfigError(e)) return;
+      error = e;
+    }
+    checked = { key, error };
+  }
+  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;
+}
+
 /**
  * Read the effective den config, merging the shared deployment config with
  * per-engineer overrides from config/local/user.yml.
@@ -422,6 +522,15 @@ export function readDenConfig(): DenConfig {
   try {
     const raw = fs.readFileSync(DEN_CONFIG_PATH, "utf-8");
     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.
+    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)
@@ -434,7 +543,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,
@@ -638,6 +747,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. */
@@ -646,7 +760,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 [];
@@ -678,6 +817,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),
@@ -685,7 +828,42 @@ 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;
 }
 
 /**