@monster-orange/den 0.2.8 → 0.3.0

package/src/ui/cli/stack-command.ts

@@ -1,5 +1,5 @@
 /**
- * `stack ls | up <name…> [--build] | down <name…> | restart <name…> | health <name…> | ps <name> | logs <name> [args]`
+ * `stack ls | up <name…> [--build] | down <name…> [--force] | restart <name…> | health <name…> | ps <name> | logs <name> [args]`
  *
  * Runs repos' Docker Compose projects with no host ports, each as its own
  * project (`<stack>-<workspace>`), served by the edge at
@@ -20,7 +20,19 @@ import {
   stackRestartService,
   stackUp,
 } from "../../shared/stacks/runtime.js";
-import { loadStackContext, stackStatuses } from "../../shared/stacks/status.js";
+import {
+  loadStackContext,
+  rejoinRunningStacks,
+  stackStatuses,
+} from "../../shared/stacks/status.js";
+import {
+  assertStackClaim,
+  forgetStackOwners,
+  recordStackOwner,
+  releaseStackOwner,
+  stackRefcounted,
+} from "../../shared/stacks/owners.js";
+import { resolveStackNamespace } from "../../shared/stacks/namespace.js";
 import type { StackConfig } from "../../shared/stacks/types.js";
 import { STACK_HEALTH_UNKNOWN_EXIT } from "../../shared/constants.js";
 
@@ -104,6 +116,19 @@ export async function cmdStack(argv: string[]): Promise<void> {
   const ctx = loadStackContext();
   const { edge, stacks } = ctx;
   const names = args.filter((a) => !a.startsWith("-"));
+  // workspaces.yml overriding a different blueprint stack_namespace.
+  if (ctx.denWorkspace && ctx.namespaceSource === "workspace")
+    for (const w of resolveStackNamespace(ctx.denWorkspace).warnings)
+      console.error(chalk.yellow(`⚠ ${w}`));
+  /** Each stack's other live owners; throws on a checkout mismatch. */
+  const claims = (targets: string[]): Map<string, string[]> => {
+    const out = new Map<string, string[]>();
+    if (!stackRefcounted(ctx)) return out;
+    for (const n of targets)
+      if (stacks[n])
+        out.set(n, assertStackClaim(ctx, stacks[n], ctx.denWorkspace));
+    return out;
+  };
   const pick = () => {
     if (!names.length)
       throw new Error(
@@ -131,13 +156,25 @@ export async function cmdStack(argv: string[]): Promise<void> {
       // Re-render the edge so its cert covers every stack, then start the stacks.
       const order = startOrder(pick(), stacks);
       const secrets = await resolveStacksSecretEnv(order.map((n) => stacks[n]));
+      // A shared namespace: refused before anything starts when another
+      // workspace runs one of these projects from a different checkout.
+      const shared = claims(order);
       await edgeUp(edge);
+      rejoinRunningStacks();
       for (const n of order) {
         console.log(chalk.cyan(`\n▶ ${n} (${projectName(n, ctx.workspace)})`));
+        if (shared.get(n)?.length)
+          console.log(
+            chalk.gray(
+              `  shared with [${shared.get(n)!.join(", ")}] (stack namespace ${ctx.workspace})`,
+            ),
+          );
         stackUp(ctx, stacks[n], {
           build: args.includes("--build"),
           secretEnv: secrets.get(n),
         });
+        if (stackRefcounted(ctx))
+          recordStackOwner(ctx, stacks[n], ctx.denWorkspace);
         for (const route of Object.keys(stacks[n].routes))
           console.log(chalk.green(`  ✓ ${routeUrl(`${route}.${n}`, edge)}`));
       }
@@ -158,14 +195,24 @@ export async function cmdStack(argv: string[]): Promise<void> {
         }
         return;
       }
+      const shared = claims(pick());
       await edgeUp(edge);
+      rejoinRunningStacks();
       for (const n of pick()) {
         console.log(chalk.cyan(`↻ ${n}`));
+        if (shared.get(n)?.length)
+          console.log(
+            chalk.yellow(
+              `  Warning: restarting a shared stack — this interrupts [${shared.get(n)!.join(", ")}]`,
+            ),
+          );
         stackDown(ctx, stacks[n]);
         stackUp(ctx, stacks[n], {
           build: args.includes("--build"),
           secretEnv: secrets.get(n),
         });
+        if (stackRefcounted(ctx))
+          recordStackOwner(ctx, stacks[n], ctx.denWorkspace);
       }
       return;
     }
@@ -173,8 +220,22 @@ export async function cmdStack(argv: string[]): Promise<void> {
       for (const n of startOrder(pick(), stacks)
         .reverse()
         .filter((n) => names.includes(n))) {
+        // A shared namespace: the last live owner stops it; any other
+        // detaches. `--force` stops it whoever else holds it.
+        if (stackRefcounted(ctx) && !args.includes("--force")) {
+          const r = releaseStackOwner(ctx, stacks[n], ctx.denWorkspace);
+          if (!r.stop) {
+            console.log(
+              chalk.cyan(
+                `▼ ${n}: detached workspace "${ctx.denWorkspace}" — ${projectName(n, ctx.workspace)} still running for [${r.remaining.join(", ")}]`,
+              ),
+            );
+            continue;
+          }
+        }
         console.log(chalk.cyan(`▼ ${n}`));
         stackDown(ctx, stacks[n]);
+        forgetStackOwners(ctx, stacks[n]);
       }
       return;
     case "ps":

package/src/ui/cli/test-runner.ts

@@ -24,6 +24,12 @@ import {
   tsxCommand,
   type EngineCommand,
 } from "../../shared/engine.js";
+import { product } from "../../shared/product.js";
+
+/** Remediation when test sessions cannot be created (no vendor assumed). */
+const SETUP_SECRETS_HINT = `  make ${product().cli}-setup-secrets  - Set up the selected secrets.provider`;
+const CI_CREDENTIALS_HINT =
+  "  CI: E2E_<ROLE>_EMAIL / E2E_<ROLE>_PASSWORD env vars";
 
 /** After Playwright smoke runs: fail if storage fixture handoff was left behind. */
 function smokePostRunTeardownVerifyStep(env: NodeJS.ProcessEnv): CommandStep {
@@ -913,13 +919,11 @@ export class TestRunner {
       if (shouldSetup) {
         console.log(
           chalk.cyan(
-            "\n📝 Sessions are created automatically — ensure 1Password is signed in:\n",
+            "\n📝 Sessions are created automatically — ensure the secrets backend is ready:\n",
           ),
         );
-        console.log(chalk.cyan("  eval $(op signin)   - Sign in to 1Password"));
-        console.log(
-          chalk.cyan("  make auth-configure  - One-time admin setup\n"),
-        );
+        console.log(chalk.cyan(SETUP_SECRETS_HINT));
+        console.log(chalk.cyan(`${CI_CREDENTIALS_HINT}\n`));
         return false;
       } else {
         console.log(chalk.red("Cannot run tests without authentication\n"));
@@ -934,10 +938,8 @@ export class TestRunner {
           "\n⚠️  Authentication failed — sessions are created fresh each run\n",
         ),
       );
-      console.log(chalk.cyan("  eval $(op signin)   - Sign in to 1Password"));
-      console.log(
-        chalk.cyan("  make auth-configure  - One-time admin setup\n"),
-      );
+      console.log(chalk.cyan(SETUP_SECRETS_HINT));
+      console.log(chalk.cyan(`${CI_CREDENTIALS_HINT}\n`));
       return false;
     }
 

package/src/ui/cli/theme-command.ts

@@ -0,0 +1,136 @@
+/**
+ * `theme validate | add | list | remove | new`
+ *
+ * Sugar over `plugin *` (PL-2a): the same commands, filtered to kind theme,
+ * with the same output and exit codes. Only `new` is theme-specific.
+ *
+ * A theme is a den-theme.json (den.theme/v1) with its files, in any git repo.
+ * `add` fetches one at an exact ref, validates it, and vendors it into the
+ * distribution (`plugins/<id>/`) with a lock entry (`plugins.lock.json`: kinds,
+ * source, ref, commit, content hash), so it is pinned the way Den is, works offline,
+ * and the whole team gets the same files from the distribution's own repo.
+ * Den's default theme ships inside Den (themes/den in the package).
+ */
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import { getDistRoot, getEngineRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import { readBrand } from "../../shared/brand.js";
+import { THEME_FILE } from "../../shared/theme/contract.js";
+import { PLUGIN_ID, PLUGIN_ID_RULE } from "../../shared/plugins/manifest.js";
+import {
+  PLUGINS_DIR,
+  hashFiles,
+  parsePluginSource,
+  pluginDirFor,
+  type LockEntry,
+  type PluginSource,
+} from "../../shared/plugins/store.js";
+import { runPluginCommand, type PluginDeps } from "./plugin-command.js";
+
+// The plugin store is where themes live (PL-2a); these names stay for
+// theme-runtime and older callers.
+export {
+  LOCK_FILE,
+  PLUGINS_DIR,
+  installedThemeIds,
+  readLock,
+  refKind,
+  type GitRunner,
+  type LockEntry,
+} from "../../shared/plugins/store.js";
+export { validationSummary } from "./plugin-command.js";
+
+export type ThemeSource = PluginSource;
+export const parseThemeSource = parsePluginSource;
+export const hashTheme = hashFiles;
+export const themeDirFor = pluginDirFor;
+
+/** The lock's theme entries (the lock is shared with other plugin kinds). */
+export function themesIn(lock: Record<string, LockEntry>): LockEntry[] {
+  return Object.values(lock).filter((e) => e.kinds?.includes("theme"));
+}
+
+export type ThemeDeps = PluginDeps;
+
+/**
+ * Run `theme <sub>`; returns the exit code. add, list, validate and remove
+ * are `plugin <sub>` filtered to kind theme; new is the theme scaffold.
+ */
+export async function cmdTheme(
+  args: string[],
+  deps: ThemeDeps = {},
+): Promise<number> {
+  const log = deps.log ?? ((l: string) => console.log(l));
+  const distRoot = deps.distRoot ?? getDistRoot();
+  const [sub, ...rest] = args;
+  const cli = product().cli;
+
+  switch (sub) {
+    case "validate":
+    case "add":
+    case "list":
+    case "remove":
+    case undefined:
+      return runPluginCommand(args, "theme", deps);
+
+    case "new": {
+      // A local theme to edit: a copy of the built-in one, in plugins/<id>/,
+      // committed with the distribution so the whole team gets it.
+      const id = rest[0];
+      if (!id || !PLUGIN_ID.test(id) || id === "den") {
+        log(
+          chalk.red(
+            `Usage: ${cli} theme new <id>  (${PLUGIN_ID_RULE}; not "den")`,
+          ),
+        );
+        return 1;
+      }
+      const dest = themeDirFor(distRoot, id);
+      if (fs.existsSync(dest)) {
+        log(
+          chalk.red(`✗ ${PLUGINS_DIR}/${id}/ already exists; nothing changed`),
+        );
+        return 1;
+      }
+      const from = path.join(
+        deps.engineRoot ?? getEngineRoot(),
+        "themes",
+        "den",
+      );
+      // Not Den's tab icon: a new theme's tab shows its own mark.
+      const denIcon = path.join(from, "favicon.ico");
+      fs.cpSync(from, dest, {
+        recursive: true,
+        filter: (src) => src !== denIcon,
+      });
+      const file = path.join(dest, THEME_FILE);
+      const m = JSON.parse(fs.readFileSync(file, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+      delete m.favicon;
+      const name = id
+        .split("-")
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join(" ");
+      Object.assign(m, { id, name, version: "0.1.0" });
+      delete m.homepage;
+      // The author is the theme's maintainer (plugin rule 1): the team.
+      m.author = readBrand().name;
+      fs.writeFileSync(file, `${JSON.stringify(m, null, 2)}\n`);
+      log(
+        `  ${id} → ${PLUGINS_DIR}/${id}/ (a copy of den: edit ${THEME_FILE} and mark.svg)`,
+      );
+      log(`  ${cli} theme validate checks it; commit it and your team has it.`);
+      return 0;
+    }
+
+    default:
+      log(
+        `Usage: ${cli} theme [list] | validate [dir] | new <id> | add <repo>[/<subpath>]@<ref> | remove <id>`,
+      );
+      return 1;
+  }
+}

package/src/ui/cli/web-command.ts

@@ -4,11 +4,12 @@ import * as fs from "fs";
 import * as http from "http";
 import * as path from "path";
 import { pathToFileURL } from "url";
+import { CLI_SPAWN_TIMEOUT_MS, DEFAULT_PORT } from "../../shared/constants.js";
 import {
-  CLI_SPAWN_TIMEOUT_MS,
-  DEFAULT_PORT,
-  OP_ACCOUNT_DEFAULT,
-} from "../../shared/constants.js";
+  readSecretsConfig,
+  secretsProcessEnv,
+  type SecretsConfig,
+} from "../../shared/secrets/index.js";
 import { getDistRoot, getEngineRoot, getStateDir } from "../../shared/paths.js";
 import { hasDenUiMarker } from "../../shared/ui-marker.js";
 import { engineBin, engineModuleFile } from "../../shared/engine.js";
@@ -269,26 +270,43 @@ async function getHttpText(
   });
 }
 
+/**
+ * The API is up: /api/server-info answers whatever the config holds
+ * (0.3.0-dev.42: /api/health answers 422 under an invalid config, so
+ * `web up` reported a running server as not ready). A server too old for
+ * server-info is asked /api/health, as before.
+ */
 async function isDenWebApiRunning(port: number): Promise<boolean> {
-  const response = await getHttpText(port, "/api/health");
-  if (!response || response.statusCode !== 200) return false;
-  try {
-    return Array.isArray(JSON.parse(response.body));
-  } catch {
-    return false;
-  }
+  const json = async (p: string): Promise<unknown> => {
+    const response = await getHttpText(port, p);
+    if (!response || response.statusCode !== 200) return undefined;
+    try {
+      return JSON.parse(response.body) as unknown;
+    } catch {
+      return undefined;
+    }
+  };
+  const info = await json("/api/server-info");
+  if (
+    info &&
+    typeof info === "object" &&
+    typeof (info as { pid?: unknown }).pid === "number"
+  )
+    return true;
+  return Array.isArray(await json("/api/health"));
 }
 
 async function isDenWebUiReady(port: number): Promise<boolean> {
   const response = await getHttpText(port, "/index.html");
   return (
-    response?.statusCode === 200 &&
+    // 422: the "Config is invalid" page, the shell serving as it should.
+    (response?.statusCode === 200 || response?.statusCode === 422) &&
     /<html[\s>]/i.test(response.body) &&
     hasDenUiMarker(response.body)
   );
 }
 
-async function isDenWebRunning(port: number): Promise<boolean> {
+export async function isDenWebRunning(port: number): Promise<boolean> {
   return (await isDenWebApiRunning(port)) && (await isDenWebUiReady(port));
 }
 
@@ -350,6 +368,20 @@ export function resolveServerEntrypoint(engine: string = getEngineRoot()): {
   };
 }
 
+/**
+ * The env the web server daemon starts with: the caller's, its port, and
+ * whatever the selected secrets strategy gives (only 1password gives one,
+ * OP_ACCOUNT, from the distribution's `secrets.onepassword.account` or the
+ * caller's own OP_ACCOUNT). Den adds no account of its own.
+ */
+export function webServerEnv(
+  port: number,
+  base: NodeJS.ProcessEnv = process.env,
+  cfg: SecretsConfig = readSecretsConfig(),
+): NodeJS.ProcessEnv {
+  return { ...base, PORT: String(port), ...secretsProcessEnv(cfg, base) };
+}
+
 function startDenWebServer(options: WebCommandOptions): StartedServer {
   const root = getDistRoot();
   const entrypoint = resolveServerEntrypoint();
@@ -369,11 +401,7 @@ function startDenWebServer(options: WebCommandOptions): StartedServer {
       {
         cwd: root,
         detached: true,
-        env: {
-          ...process.env,
-          PORT: String(options.port),
-          OP_ACCOUNT: process.env.OP_ACCOUNT ?? OP_ACCOUNT_DEFAULT,
-        },
+        env: webServerEnv(options.port),
         stdio: ["ignore", logFd, logFd],
       },
     );
@@ -435,11 +463,7 @@ export function spawnDetachedWebRestart(port: number): number | undefined {
       {
         cwd: root,
         detached: true,
-        env: {
-          ...process.env,
-          PORT: String(port),
-          OP_ACCOUNT: process.env.OP_ACCOUNT ?? OP_ACCOUNT_DEFAULT,
-        },
+        env: webServerEnv(port),
         stdio: ["ignore", logFd, logFd],
       },
     );

package/src/ui/mcp/api.ts

@@ -85,6 +85,28 @@ export class DenHttpError extends Error {
   }
 }
 
+/**
+ * An error body as a line: the server's R26b JSON ({ ok: false, error,
+ * code, requestId }) as its message and request id, anything else as is.
+ */
+export function errorText(body: string): string {
+  try {
+    const j = JSON.parse(body) as {
+      error?: unknown;
+      code?: unknown;
+      requestId?: unknown;
+    };
+    if (j && typeof j.error === "string")
+      return (
+        j.error +
+        (typeof j.requestId === "string" ? ` (request ${j.requestId})` : "")
+      );
+  } catch {
+    /* not JSON */
+  }
+  return body;
+}
+
 /** Read routes: GET only. */
 const READ_ROUTES = new Set([
   "/api/health",
@@ -268,8 +290,12 @@ export function createDenApi(opts: {
         signal,
       });
       if (!res.ok) {
-        const text = (await res.text()).slice(0, 2000);
-        throw new DenHttpError(method, path, res.status, text);
+        throw new DenHttpError(
+          method,
+          path,
+          res.status,
+          errorText((await res.text()).slice(0, 2000)),
+        );
       }
       return res;
     } catch (e) {

package/src/ui/mcp/scope.ts

@@ -103,6 +103,27 @@ function printable(v: string): string {
   return v.replace(/[^\x20-\x7e]/g, "?").slice(0, 80);
 }
 
+/**
+ * A path echoed back in an error: one printable line, never cut mid-name
+ * (0.3.0-dev.40, a consumer's 0.2.8 nit: printable's 80-character cap cut
+ * the filename). Up to `max` characters it is whole; a longer one keeps its
+ * start and its last segment whole, eliding the middle with "…".
+ */
+export function printablePath(v: string, max = 160): string {
+  const s = v.replace(/[^\x20-\x7e]/g, "?");
+  if (s.length <= max) return s;
+  const cut = s.lastIndexOf("/");
+  const tail = cut >= 0 ? s.slice(cut) : s;
+  // The last segment is kept whole whatever its length; the room left is
+  // shared between the path's start and the directories just before it.
+  const room = max - tail.length - 1;
+  if (room <= 0) return `…${tail}`;
+  const head = s.slice(0, Math.ceil(room / 2));
+  const end = s.length - tail.length;
+  const more = s.slice(end - (room - head.length), end);
+  return `${head}…${more}${tail}`;
+}
+
 /** The refusal for a call that names `other`. */
 export function otherWorkspace(
   tool: string,
@@ -272,6 +293,6 @@ export async function assertPathInScope(
     .map((r) => path.resolve(r));
   if (!roots.some((r) => target === r || target.startsWith(r + path.sep)))
     throw new ScopeRefusal(
-      `${tool}: ${printable(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+      `${tool}: ${printablePath(p)} is not inside a repo of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
     );
 }

package/src/ui/mcp/tools.ts

@@ -601,13 +601,17 @@ export function versionBefore(a: string, b: string): boolean {
   return false;
 }
 
-/** The running web server's version, or undefined when it reports none. */
-async function webServerVersion(api: DenApi): Promise<string | undefined> {
+/** The running web server's /api/server-info, or null when it has none. */
+async function readServerInfo(
+  api: DenApi,
+): Promise<Record<string, unknown> | null> {
   try {
-    const info = (await api.get("/api/server-info")) as { version?: unknown };
-    return typeof info?.version === "string" ? info.version : undefined;
+    const info = (await api.get("/api/server-info")) as unknown;
+    return info && typeof info === "object"
+      ? (info as Record<string, unknown>)
+      : null;
   } catch (e) {
-    if (e instanceof DenHttpError) return undefined;
+    if (e instanceof DenHttpError) return null;
     throw e;
   }
 }
@@ -621,11 +625,13 @@ async function notFoundMessage(
   e: DenHttpError,
   tool: string,
   ctx: ToolContext,
+  info: () => Promise<Record<string, unknown> | null>,
 ): Promise<string> {
   const plain = `Error: ${tool}: the web server answered 404 for ${e.method} ${e.path}: ${e.body}`;
   const since = ROUTE_SINCE[e.path];
   if (!since) return plain;
-  const version = await webServerVersion(ctx.api);
+  const v = (await info())?.version;
+  const version = typeof v === "string" ? v : undefined;
   if (version !== undefined && !versionBefore(version, since)) return plain;
   return (
     `web server is Den ${version ?? `< ${since}`}; ` +
@@ -664,6 +670,30 @@ async function reportRefusal(
   }
 }
 
+/**
+ * MD-2: when the web server runs an older engine than the one on disk (a
+ * pin upgraded Den under it), every failed call says so, naming both
+ * versions and the restart. Null when the engines agree or it can't tell.
+ */
+function staleEngineMessage(
+  tool: string,
+  ctx: ToolContext,
+  info: Record<string, unknown> | null,
+): string | null {
+  if (info?.engineStale !== true) return null;
+  const ver = (x: unknown) =>
+    x &&
+    typeof x === "object" &&
+    typeof (x as { version?: unknown }).version === "string"
+      ? (x as { version: string }).version
+      : "unknown";
+  return (
+    `Error: ${tool}: Den was updated to ${ver(info.onDisk)}, but the web server ` +
+    `is still running ${ver(info.loaded)}. Restart it: ${ctx.cli} web restart ` +
+    `(or your service restart).`
+  );
+}
+
 /**
  * A scoped server's arguments: the workspace exists (checked once per
  * server), and a tool that takes a workspace gets the scoped one; naming
@@ -709,8 +739,21 @@ export async function callTool(
         text: redactSecrets(JSON.stringify(e.out, null, 2)),
         isError: true,
       };
+    // server-info is read lazily, once, and only after a call failed.
+    let infoRead: Promise<Record<string, unknown> | null> | null = null;
+    const info = () => (infoRead ??= readServerInfo(ctx.api).catch(() => null));
+    if (e instanceof DenHttpError) {
+      const stale = staleEngineMessage(name, ctx, await info());
+      if (stale)
+        return {
+          text: redactSecrets(
+            `${stale} (${e.method} ${e.path} answered ${e.status}: ${e.body})`,
+          ),
+          isError: true,
+        };
+    }
     if (e instanceof DenHttpError && e.status === 404) {
-      const text = await notFoundMessage(e, name, ctx).catch(
+      const text = await notFoundMessage(e, name, ctx, info).catch(
         (inner: Error) => `Error: ${inner.message}`,
       );
       return { text: redactSecrets(text), isError: true };

package/src/ui/server/appearance-prefs.ts

@@ -0,0 +1,95 @@
+/**
+ * Appearance preferences: the theme and mode this engineer chose. Stored in
+ * the user config as `appearance:` and served by /api/settings, like the
+ * graph prefs. A pure UI preference: changing it writes this block of
+ * config/local/user.yml and nothing else (no edge, services or restart).
+ */
+
+export type ModePref = "system" | "dark" | "light";
+
+export interface AppearancePrefs {
+  /**
+   * A theme id, or null to follow the org default (the org config's
+   * `brand.theme`, else den). A named theme is pinned even when it is the
+   * org default today: you keep it when the org changes `brand.theme`.
+   */
+  theme: string | null;
+  /** system follows prefers-color-scheme. */
+  mode: ModePref;
+}
+
+export const APPEARANCE_DEFAULTS: AppearancePrefs = {
+  theme: null,
+  mode: "system",
+};
+
+export const MODES: readonly ModePref[] = ["system", "dark", "light"];
+const THEME_ID = /^[a-z][a-z0-9-]{1,39}$/;
+
+const isObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * The stored block, normalised. A stored theme id is kept even when that
+ * theme is not installed now (resolution warns and falls back), so a theme
+ * that is briefly missing does not lose the preference.
+ */
+export function appearancePrefs(stored: unknown): AppearancePrefs {
+  const out: AppearancePrefs = { ...APPEARANCE_DEFAULTS };
+  if (!isObject(stored)) return out;
+  if (typeof stored.theme === "string" && THEME_ID.test(stored.theme))
+    out.theme = stored.theme;
+  if (MODES.includes(stored.mode as ModePref))
+    out.mode = stored.mode as ModePref;
+  return out;
+}
+
+/**
+ * Merge a POSTed (partial) block. `theme` must name an installed theme that
+ * validates; null or "" clears it ("Org default": follow the org); any bad
+ * field fails the whole patch.
+ *
+ * A theme picked by name is stored by name, even one that is the org
+ * default now (0.3.0-dev.11): that is a pin, and the menu shows it as one.
+ * Only "Org default" follows the org when it changes `brand.theme`.
+ */
+export function mergeAppearancePrefs(
+  current: AppearancePrefs,
+  patch: unknown,
+  isUsableTheme: (id: string) => boolean,
+): { ok: true; value: AppearancePrefs } | { ok: false; error: string } {
+  if (!isObject(patch))
+    return { ok: false, error: "appearance must be an object" };
+  const out: AppearancePrefs = { ...current };
+  for (const [key, v] of Object.entries(patch)) {
+    if (key === "mode") {
+      // null clears it to the default (0.3.0-dev.32), as theme's does.
+      if (v === null) out.mode = APPEARANCE_DEFAULTS.mode;
+      else if (!MODES.includes(v as ModePref))
+        return {
+          ok: false,
+          error: `appearance.mode must be one of ${MODES.map((m) => `"${m}"`).join(", ")}`,
+        };
+      else out.mode = v as ModePref;
+    } else if (key === "theme") {
+      if (v === null || v === "") out.theme = null;
+      else if (typeof v !== "string" || !THEME_ID.test(v) || !isUsableTheme(v))
+        return {
+          ok: false,
+          error: `appearance.theme: no valid installed theme "${String(v)}"`,
+        };
+      else out.theme = v;
+    } else return { ok: false, error: `unknown appearance setting "${key}"` };
+  }
+  return { ok: true, value: out };
+}
+
+/** What user.yml stores: only what differs from the defaults. */
+export function storedAppearance(
+  p: AppearancePrefs,
+): { theme?: string; mode?: ModePref } | undefined {
+  const out: { theme?: string; mode?: ModePref } = {};
+  if (p.theme) out.theme = p.theme;
+  if (p.mode !== APPEARANCE_DEFAULTS.mode) out.mode = p.mode;
+  return Object.keys(out).length ? out : undefined;
+}