@malloy-publisher/server 0.0.219 → 0.0.220

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.219",
+   "version": "0.0.220",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -36,17 +36,17 @@
       "@azure/storage-blob": "^12.26.0",
       "@duckdb/node-api": "1.5.3-r.2",
       "@google-cloud/storage": "^7.16.0",
-      "@malloydata/db-bigquery": "^0.0.415",
-      "@malloydata/db-databricks": "^0.0.415",
-      "@malloydata/db-duckdb": "^0.0.415",
-      "@malloydata/db-mysql": "^0.0.415",
-      "@malloydata/db-postgres": "^0.0.415",
-      "@malloydata/db-publisher": "^0.0.415",
-      "@malloydata/db-snowflake": "^0.0.415",
-      "@malloydata/db-trino": "^0.0.415",
-      "@malloydata/malloy": "^0.0.415",
-      "@malloydata/malloy-sql": "^0.0.415",
-      "@malloydata/render-validator": "^0.0.415",
+      "@malloydata/db-bigquery": "^0.0.421",
+      "@malloydata/db-databricks": "^0.0.421",
+      "@malloydata/db-duckdb": "^0.0.421",
+      "@malloydata/db-mysql": "^0.0.421",
+      "@malloydata/db-postgres": "^0.0.421",
+      "@malloydata/db-publisher": "^0.0.421",
+      "@malloydata/db-snowflake": "^0.0.421",
+      "@malloydata/db-trino": "^0.0.421",
+      "@malloydata/malloy": "^0.0.421",
+      "@malloydata/malloy-sql": "^0.0.421",
+      "@malloydata/render-validator": "^0.0.421",
       "@modelcontextprotocol/sdk": "^1.13.2",
       "@opentelemetry/api": "^1.9.0",
       "@opentelemetry/auto-instrumentations-node": "^0.57.0",

package/src/config.theme.spec.ts

@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import fs from "fs";
+import path from "path";
+import {
+   getInstanceTheme,
+   getProcessedPublisherConfig,
+   mergeThemes,
+   type Theme,
+} from "./config";
+import { PUBLISHER_CONFIG_NAME } from "./constants";
+
+const TEST_ROOT = path.join(process.cwd(), "test-temp-theme-config");
+const CONFIG_PATH = path.join(TEST_ROOT, PUBLISHER_CONFIG_NAME);
+
+function writeConfig(json: object) {
+   if (!fs.existsSync(TEST_ROOT)) {
+      fs.mkdirSync(TEST_ROOT, { recursive: true });
+   }
+   fs.writeFileSync(CONFIG_PATH, JSON.stringify(json));
+}
+
+describe("Theme cascade in publisher.config.json", () => {
+   beforeEach(() => {
+      if (fs.existsSync(CONFIG_PATH)) fs.unlinkSync(CONFIG_PATH);
+   });
+
+   afterEach(() => {
+      if (fs.existsSync(CONFIG_PATH)) fs.unlinkSync(CONFIG_PATH);
+      if (fs.existsSync(TEST_ROOT)) {
+         fs.rmdirSync(TEST_ROOT, { recursive: true });
+      }
+   });
+
+   it("returns no theme when none is set", () => {
+      writeConfig({
+         frozenConfig: false,
+         environments: [
+            {
+               name: "default",
+               packages: [{ name: "pkg", location: "/tmp/pkg" }],
+            },
+         ],
+      });
+      const cfg = getProcessedPublisherConfig(TEST_ROOT);
+      expect(cfg.theme).toBeUndefined();
+      expect(cfg.environments[0].theme).toBeUndefined();
+   });
+
+   it("exposes the instance theme on the top-level config", () => {
+      writeConfig({
+         frozenConfig: false,
+         theme: {
+            defaultMode: "dark",
+            palette: { series: ["#ff0080"] },
+         },
+         environments: [
+            {
+               name: "default",
+               packages: [{ name: "pkg", location: "/tmp/pkg" }],
+            },
+         ],
+      });
+      const cfg = getProcessedPublisherConfig(TEST_ROOT);
+      expect(cfg.theme?.defaultMode).toBe("dark");
+      expect(cfg.theme?.palette?.series).toEqual(["#ff0080"]);
+      expect(cfg.environments[0].theme?.palette?.series).toEqual(["#ff0080"]);
+   });
+
+   it("environment theme overrides instance per key", () => {
+      writeConfig({
+         frozenConfig: false,
+         theme: {
+            defaultMode: "light",
+            palette: {
+               series: ["#aaa"],
+               background: { light: "#fff" },
+            },
+            font: { family: "Inter" },
+         },
+         environments: [
+            {
+               name: "marketing",
+               packages: [{ name: "pkg", location: "/tmp/pkg" }],
+               theme: {
+                  palette: { series: ["#cc0000"] },
+               },
+            },
+         ],
+      });
+      const cfg = getProcessedPublisherConfig(TEST_ROOT);
+      expect(cfg.environments[0].theme?.palette?.series).toEqual(["#cc0000"]);
+      // Font and background fall through from instance default.
+      expect(cfg.environments[0].theme?.font?.family).toBe("Inter");
+      expect(cfg.environments[0].theme?.palette?.background?.light).toBe(
+         "#fff",
+      );
+   });
+
+   it("drops invalid defaultMode values without losing the rest", () => {
+      writeConfig({
+         frozenConfig: false,
+         theme: {
+            defaultMode: "nonsense",
+            palette: { series: ["#a"] },
+         },
+         environments: [
+            {
+               name: "default",
+               packages: [{ name: "pkg", location: "/tmp/pkg" }],
+            },
+         ],
+      });
+      const cfg = getProcessedPublisherConfig(TEST_ROOT);
+      expect(cfg.theme?.defaultMode).toBeUndefined();
+      expect(cfg.theme?.palette?.series).toEqual(["#a"]);
+   });
+
+   it("getInstanceTheme returns the same instance theme", () => {
+      writeConfig({
+         frozenConfig: false,
+         theme: { palette: { series: ["#abc"] } },
+         environments: [],
+      });
+      const t = getInstanceTheme(TEST_ROOT);
+      expect(t?.palette?.series).toEqual(["#abc"]);
+   });
+});
+
+describe("mergeThemes", () => {
+   it("returns undefined when both sides are missing", () => {
+      expect(mergeThemes(undefined, undefined)).toBeUndefined();
+   });
+
+   it("returns the override when base is missing", () => {
+      const o: Theme = { palette: { series: ["#x"] } };
+      expect(mergeThemes(undefined, o)).toEqual(o);
+   });
+
+   it("merges background sub-object per mode", () => {
+      const base: Theme = {
+         palette: { background: { light: "#fff", dark: "#000" } },
+      };
+      const o: Theme = {
+         palette: { background: { dark: "#111" } },
+      };
+      const merged = mergeThemes(base, o);
+      expect(merged?.palette?.background?.light).toBe("#fff");
+      expect(merged?.palette?.background?.dark).toBe("#111");
+   });
+
+   it("merges all per-mode color keys, not just background and tableHeader", () => {
+      // Regression: mergeThemes used to ignore tableBody / tile /
+      // tileTitle, so an environment that overrode one of those keys
+      // dropped the instance-level default for the same key.
+      const base: Theme = {
+         palette: {
+            tableBody: { light: "#727883" },
+            tile: { light: "#f5fafc", dark: "#0f172a" },
+            tileTitle: { light: "#5d626b" },
+         },
+      };
+      const o: Theme = {
+         palette: { tile: { dark: "#000000" } },
+      };
+      const merged = mergeThemes(base, o);
+      expect(merged?.palette?.tableBody?.light).toBe("#727883");
+      expect(merged?.palette?.tile?.light).toBe("#f5fafc");
+      expect(merged?.palette?.tile?.dark).toBe("#000000");
+      expect(merged?.palette?.tileTitle?.light).toBe("#5d626b");
+   });
+
+   it("override series replaces the array wholesale", () => {
+      const base: Theme = { palette: { series: ["#1", "#2", "#3"] } };
+      const o: Theme = { palette: { series: ["#a"] } };
+      const merged = mergeThemes(base, o);
+      expect(merged?.palette?.series).toEqual(["#a"]);
+   });
+});

package/src/config.ts

@@ -74,6 +74,25 @@ function resolvePublisherConfigPath(serverRoot: string): {
 type FilesystemPath = `./${string}` | `../${string}` | `/${string}`;
 type GcsPath = `gs://${string}`;
 type ApiConnection = components["schemas"]["Connection"];
+export type Theme = components["schemas"]["Theme"];
+
+/**
+ * Palette colour keys that have separate light/dark variants. Hand-copied
+ * from `packages/sdk/src/theme/keys.ts`: the server and the SDK are
+ * intentionally decoupled (neither imports the other; their only shared
+ * contract is api-doc.yaml), so the list lives in both. The parity test
+ * `theme_key_parity.spec.ts` fails if the two copies or the api-doc
+ * Theme.palette schema drift apart. Exported so that test can import it.
+ */
+export const PER_MODE_COLOR_KEYS = [
+   "background",
+   "tableHeader",
+   "tableHeaderBackground",
+   "tableBody",
+   "tile",
+   "tileTitle",
+   "mapColor",
+] as const;
 
 export type Package = {
    name: string;
@@ -87,23 +106,27 @@ export type Connection = {
 
 export type Environment = {
    name: string;
+   theme?: Theme;
    packages: Package[];
    connections?: Connection[];
 };
 
 export type PublisherConfig = {
    frozenConfig: boolean;
+   theme?: Theme;
    environments: Environment[];
 };
 
 export type ProcessedEnvironment = {
    name: string;
+   theme?: Theme;
    packages: Package[];
    connections: ApiConnection[];
 };
 
 export type ProcessedPublisherConfig = {
    frozenConfig: boolean;
+   theme?: Theme;
    environments: ProcessedEnvironment[];
 };
 
@@ -488,12 +511,138 @@ export const getPublisherConfig = (serverRoot: string): PublisherConfig => {
       );
    }
 
+   const instanceTheme = sanitizeTheme(
+      processedConfig &&
+         typeof processedConfig === "object" &&
+         "theme" in processedConfig
+         ? (processedConfig as { theme: unknown }).theme
+         : undefined,
+      "publisher.config.json",
+   );
+
    return {
       frozenConfig,
+      ...(instanceTheme ? { theme: instanceTheme } : {}),
       environments,
    } as PublisherConfig;
 };
 
+/**
+ * Sanitize a raw theme value pulled from JSON. Returns a Theme on success
+ * or `undefined` if the input is missing/invalid. Bad shapes log a warning
+ * and are dropped rather than failing the whole config; an unthemed config
+ * still boots fine.
+ */
+export function sanitizeTheme(
+   raw: unknown,
+   context: string,
+): Theme | undefined {
+   if (raw === undefined || raw === null) return undefined;
+   if (typeof raw !== "object" || Array.isArray(raw)) {
+      logger.warn(
+         `Invalid "theme" in ${context}: expected an object. Ignoring.`,
+      );
+      return undefined;
+   }
+   const obj = raw as Record<string, unknown>;
+   const theme: Theme = {};
+
+   if ("defaultMode" in obj) {
+      const mode = obj.defaultMode;
+      if (mode === "light" || mode === "dark" || mode === "auto") {
+         theme.defaultMode = mode;
+      } else {
+         logger.warn(
+            `Invalid "theme.defaultMode" in ${context}: expected "light" | "dark" | "auto" (got ${JSON.stringify(mode)}). Ignoring field.`,
+         );
+      }
+   }
+   if ("allowUserToggle" in obj) {
+      const value = obj.allowUserToggle;
+      if (typeof value === "boolean") {
+         theme.allowUserToggle = value;
+      } else {
+         // Don't coerce: Boolean("false") is true, so a stray string would
+         // silently invert the operator's intent. Match defaultMode above
+         // and warn + ignore instead.
+         logger.warn(
+            `Invalid "theme.allowUserToggle" in ${context}: expected a boolean (got ${JSON.stringify(value)}). Ignoring field.`,
+         );
+      }
+   }
+   if ("palette" in obj && obj.palette && typeof obj.palette === "object") {
+      const palette = obj.palette as Record<string, unknown>;
+      const sanitized: NonNullable<Theme["palette"]> = {};
+      if (Array.isArray(palette.series)) {
+         // Preserve an explicit empty array as a clear-the-palette
+         // signal; resolveTheme treats [] as a real override.
+         sanitized.series = palette.series.filter(
+            (c): c is string => typeof c === "string",
+         );
+      }
+      // Per-mode colour keys share the same shape: { light?: string, dark?: string }.
+      // Sanitize uniformly so adding a new key only touches PER_MODE_COLOR_KEYS.
+      for (const key of PER_MODE_COLOR_KEYS) {
+         const raw = palette[key];
+         if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+         const r = raw as Record<string, unknown>;
+         const out: { light?: string; dark?: string } = {};
+         if (typeof r.light === "string") out.light = r.light;
+         if (typeof r.dark === "string") out.dark = r.dark;
+         if (Object.keys(out).length > 0) {
+            (sanitized as Record<string, unknown>)[key] = out;
+         }
+      }
+      if (Object.keys(sanitized).length > 0) theme.palette = sanitized;
+   }
+   if ("font" in obj && obj.font && typeof obj.font === "object") {
+      const font = obj.font as Record<string, unknown>;
+      const sanitized: NonNullable<Theme["font"]> = {};
+      if (typeof font.family === "string") sanitized.family = font.family;
+      if (typeof font.size === "number" && Number.isFinite(font.size)) {
+         sanitized.size = font.size;
+      }
+      if (Object.keys(sanitized).length > 0) theme.font = sanitized;
+   }
+
+   return Object.keys(theme).length > 0 ? theme : undefined;
+}
+
+/**
+ * Merge an environment-level theme on top of the instance default. Both
+ * inputs are already sanitized. The override wins per key at every level;
+ * absent keys fall through to the base. Returns `undefined` only when both
+ * sides are absent.
+ *
+ * Per-mode colour objects merge per-mode so an environment that sets
+ * only `palette.tile.dark` keeps the instance's `palette.tile.light`.
+ */
+export function mergeThemes(
+   base: Theme | undefined,
+   override: Theme | undefined,
+): Theme | undefined {
+   if (!base) return override;
+   if (!override) return base;
+   const merged: Theme = { ...base, ...override };
+   if (base.palette || override.palette) {
+      merged.palette = {
+         ...(base.palette ?? {}),
+         ...(override.palette ?? {}),
+      };
+      for (const key of PER_MODE_COLOR_KEYS) {
+         const b = base.palette?.[key];
+         const o = override.palette?.[key];
+         if (b || o) {
+            merged.palette[key] = { ...(b ?? {}), ...(o ?? {}) };
+         }
+      }
+   }
+   if (base.font || override.font) {
+      merged.font = { ...(base.font ?? {}), ...(override.font ?? {}) };
+   }
+   return merged;
+}
+
 export const isPublisherConfigFrozen = (serverRoot: string) => {
    try {
       const publisherConfig = getPublisherConfig(serverRoot);
@@ -637,17 +786,47 @@ export const getProcessedPublisherConfig = (
          continue;
       }
 
+      // Per-environment theme override: computed here (the instance default
+      // merged with this environment's theme) but NOT yet wired through.
+      // addEnvironment() drops this field, so the live Environment never
+      // carries it and no viewer applies it today; only the instance-level
+      // theme is applied. Kept for the planned per-environment follow-up.
+      const envTheme = sanitizeTheme(
+         (environment as { theme?: unknown }).theme,
+         `environment "${environment.name}"`,
+      );
+      const resolvedTheme = mergeThemes(rawConfig.theme, envTheme);
+
       validEnvironments.push({
          name: environment.name,
          packages: validPackages,
          connections: convertConnectionsToApiConnections(
             environment.connections || [],
          ),
+         ...(resolvedTheme ? { theme: resolvedTheme } : {}),
       });
    }
 
    return {
       frozenConfig: rawConfig.frozenConfig ?? false,
+      ...(rawConfig.theme ? { theme: rawConfig.theme } : {}),
       environments: validEnvironments,
    };
 };
+
+/**
+ * Convenience accessor for the instance-wide default theme. Used by
+ * ServerStatus so the app shell can apply the operator's chosen theme
+ * before the viewer has navigated into any specific environment.
+ */
+export const getInstanceTheme = (serverRoot: string): Theme | undefined => {
+   try {
+      return getPublisherConfig(serverRoot).theme;
+   } catch (error) {
+      logger.error(
+         `Error reading instance theme from ${PUBLISHER_CONFIG_NAME}`,
+         { error },
+      );
+      return undefined;
+   }
+};

package/src/controller/materialization.controller.spec.ts

@@ -59,7 +59,7 @@ describe("MaterializationController.createMaterialization validation", () => {
          buildInstructions: {
             sources: [
                {
-                  buildId: "b1",
+                  sourceEntityId: "b1",
                   sourceID: "orders@m",
                   materializedTableId: "mt-1",
                   physicalTableName: "orders_v1",
@@ -71,7 +71,7 @@ describe("MaterializationController.createMaterialization validation", () => {
       expect(parsed).toEqual({
          buildInstructions: [
             {
-               buildId: "b1",
+               sourceEntityId: "b1",
                sourceID: "orders@m",
                materializedTableId: "mt-1",
                physicalTableName: "orders_v1",
@@ -99,7 +99,7 @@ describe("MaterializationController.createMaterialization validation", () => {
       await expect(
          controller.createMaterialization("env", "pkg", {
             buildInstructions: {
-               sources: [{ buildId: "b1", materializedTableId: "mt-1" }],
+               sources: [{ sourceEntityId: "b1", materializedTableId: "mt-1" }],
             },
          }),
       ).rejects.toThrow(BadRequestError);
@@ -112,7 +112,7 @@ describe("MaterializationController.createMaterialization validation", () => {
             buildInstructions: {
                sources: [
                   {
-                     buildId: "b1",
+                     sourceEntityId: "b1",
                      materializedTableId: "mt-1",
                      physicalTableName: "orders_v1",
                      realization: "MERGE",

package/src/controller/materialization.controller.ts

@@ -81,7 +81,7 @@ export class MaterializationController {
       }
       const instruction = raw as Record<string, unknown>;
       const required = [
-         "buildId",
+         "sourceEntityId",
          "materializedTableId",
          "physicalTableName",
          "realization",
@@ -102,7 +102,7 @@ export class MaterializationController {
          );
       }
       return {
-         buildId: instruction.buildId as string,
+         sourceEntityId: instruction.sourceEntityId as string,
          sourceID:
             typeof instruction.sourceID === "string"
                ? instruction.sourceID

package/src/controller/theme.controller.ts

@@ -0,0 +1,83 @@
+import { components } from "../api";
+import { sanitizeTheme, Theme } from "../config";
+import { BadRequestError, FrozenConfigError } from "../errors";
+import { isPublisherConfigFrozen } from "../config";
+import { ThemeStore } from "../service/theme_store";
+
+type ApiTheme = components["schemas"]["Theme"];
+
+/**
+ * Handlers for the in-app Theme Editor.
+ *
+ *   GET  /api/v0/theme  → current saved theme (or built-in default)
+ *   PUT  /api/v0/theme  → save the supplied theme
+ *   DELETE /api/v0/theme → reset to boot seed / built-in default
+ */
+export class ThemeController {
+   constructor(
+      private themeStore: ThemeStore,
+      private serverRoot: string,
+   ) {}
+
+   getTheme = async (): Promise<ApiTheme> => {
+      const theme = await this.themeStore.get();
+      // Always return an object so the client never has to deal with the
+      // null/undefined ambiguity. An empty object means "no overrides yet,
+      // use SDK defaults."
+      return theme ?? {};
+   };
+
+   /**
+    * PUT persists the supplied theme verbatim, including a literal `{}`.
+    * An empty `{}` is an intentional "clear all overrides" save: it writes
+    * an (empty) row so the boot seed from publisher.config.json's `theme`
+    * block is suppressed on subsequent loads. This deliberately differs
+    * from DELETE (resetTheme), which drops the row and lets that config
+    * seed re-apply. Note the persisted `"{}"` sanitizes back to `undefined`
+    * on reload (sanitizeTheme returns undefined for `{}`), but the row
+    * still exists, so the seed stays suppressed. This PUT-`{}` path is not
+    * reachable from the Theme Editor UI today (its clear affordance is the
+    * Reset button, which calls DELETE); it exists only via the API.
+    */
+   putTheme = async (body: unknown): Promise<ApiTheme> => {
+      if (isPublisherConfigFrozen(this.serverRoot)) {
+         throw new FrozenConfigError(
+            'Cannot edit theme: publisher.config.json has "frozenConfig": true.',
+         );
+      }
+      // Treat a literal `{}` as an intentional "clear all overrides" PUT
+      // (the only other clear path is DELETE, which re-seeds from the
+      // config file). sanitizeTheme returns undefined for both `{}` and
+      // garbage, so we have to disambiguate here.
+      const isEmptyObject =
+         typeof body === "object" &&
+         body !== null &&
+         !Array.isArray(body) &&
+         Object.keys(body as Record<string, unknown>).length === 0;
+      const sanitized = sanitizeTheme(body, "PUT /api/v0/theme");
+      if (!sanitized && !isEmptyObject) {
+         throw new BadRequestError(
+            "Theme payload was malformed (expected an object).",
+         );
+      }
+      const saved: Theme = await this.themeStore.set(sanitized ?? {});
+      return saved;
+   };
+
+   /**
+    * DELETE drops the persisted row so the next load re-seeds from
+    * publisher.config.json's `theme` block (or ends up unthemed if the
+    * config defines none). Contrast with PUT `{}`, which persists an empty
+    * row and thereby suppresses that seed instead of restoring it. See
+    * putTheme for the full divergence.
+    */
+   resetTheme = async (): Promise<ApiTheme> => {
+      if (isPublisherConfigFrozen(this.serverRoot)) {
+         throw new FrozenConfigError(
+            'Cannot reset theme: publisher.config.json has "frozenConfig": true.',
+         );
+      }
+      const reseeded = await this.themeStore.reset();
+      return reseeded ?? {};
+   };
+}

package/src/dto/connection.dto.ts

@@ -265,6 +265,12 @@ export class ConnectionDto implements ApiConnection {
       | "motherduck"
       | "ducklake";
 
+   // Opaque, secret-free data-identity token; carried verbatim (never parsed
+   // or re-hashed) into content-addressed source ids. See api-doc.yaml.
+   @IsOptional()
+   @IsString()
+   fingerprint?: string;
+
    @IsOptional()
    @ValidateNested()
    @Type(() => PostgresConnectionDto)

package/src/materialization_metrics.ts

@@ -131,7 +131,7 @@ export function recordAutoLoadOutcome(outcome: "success" | "failure"): void {
 
 /**
  * Record that a connection digest could not be computed during build-plan
- * compilation because the connection failed to resolve. The resulting buildIds
+ * compilation because the connection failed to resolve. The resulting sourceEntityIds
  * are computed without a digest, so this is a correctness signal, not just noise.
  */
 export function recordConnectionDigestSkipped(): void {

package/src/runtime/publisher.js

@@ -79,7 +79,12 @@
          "/packages/" +
          encodeURIComponent(target.pkg) +
          "/models/" +
-         modelPath.split("/").map(encodeURIComponent).join("/") +
+         // Encode the whole model path as ONE path segment (slashes -> %2F). A model
+         // in a subfolder ("model/x.malloy") must not become two URL segments: some
+         // servers only match a single-segment {path} and would 405 a multi-segment
+         // path. This matches the typed SDK (encodeURIComponent) and the server's
+         // encoded-slash handling.
+         encodeURIComponent(modelPath) +
          "/query";
       var body = { compactJson: compactJson };
       if (malloyQuery) body.query = malloyQuery;