@malloy-publisher/server 0.0.219 → 0.0.221

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.219",
+   "version": "0.0.221",
    "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/package.controller.spec.ts

@@ -18,6 +18,7 @@ describe("PackageController.addPackage explores validation", () => {
          "Invalid explores entry 'missing.malloy' in publisher.json: file not found";
       const mockPackage = {
          formatInvalidExplores: () => invalidMsg,
+         formatInvalidSchedule: () => "",
       };
       const unloadPackage = sinon.stub().resolves(undefined);
       const deletePackage = sinon.stub().resolves(undefined);
@@ -52,7 +53,10 @@ describe("PackageController.addPackage explores validation", () => {
       // controller passes a validator and does NOT call delete/unload itself.
       const invalidMsg =
          "Invalid explores entry 'missing.malloy' in publisher.json: file not found";
-      const mockPackage = { formatInvalidExplores: () => invalidMsg };
+      const mockPackage = {
+         formatInvalidExplores: () => invalidMsg,
+         formatInvalidSchedule: () => "",
+      };
       // installPackage mimics the real contract: invoke the validator and, if it
       // returns a message, throw BadRequestError (after its internal rollback).
       const installPackage = sinon
@@ -100,6 +104,7 @@ describe("PackageController.addPackage explores validation", () => {
    it("persists when explores are valid (no-location)", async () => {
       const mockPackage = {
          formatInvalidExplores: () => "",
+         formatInvalidSchedule: () => "",
       };
       const addPackage = sinon.stub().resolves(mockPackage);
       const getEnvironment = sinon.stub().resolves({ addPackage });
@@ -122,6 +127,88 @@ describe("PackageController.addPackage explores validation", () => {
    });
 });
 
+describe("PackageController.addPackage cron schedule validation", () => {
+   afterEach(() => {
+      sinon.restore();
+   });
+
+   it("rejects a publish whose cron fails the private-only gate (no-location path)", async () => {
+      // Valid explores but an invalid materialization cron: the publish must
+      // still 400 (strict-at-publish, same split as explores — load merely
+      // warns) and roll back via unloadPackage.
+      const cronMsg =
+         "materialization.schedule (cron) in publisher.json requires every " +
+         "persist source to declare '#@ persist ... sharing=private'; source " +
+         "'orders' resolves to unset.";
+      const mockPackage = {
+         formatInvalidExplores: () => "",
+         formatInvalidSchedule: () => cronMsg,
+      };
+      const unloadPackage = sinon.stub().resolves(undefined);
+      const addPackage = sinon.stub().resolves(mockPackage);
+      const environment = { addPackage, unloadPackage };
+      const getEnvironment = sinon.stub().resolves(environment);
+      const addPackageToDatabase = sinon.stub().resolves(undefined);
+      const environmentStore = {
+         publisherConfigIsFrozen: false,
+         getEnvironment,
+         addPackageToDatabase,
+      } as unknown as EnvironmentStore;
+
+      const controller = new PackageController(environmentStore);
+
+      await expect(
+         controller.addPackage("env", { name: "pkg", description: "test" }),
+      ).rejects.toThrow(cronMsg);
+
+      expect(unloadPackage.calledOnceWith("pkg")).toBe(true);
+      expect(addPackageToDatabase.called).toBe(false);
+   });
+
+   it("location path: the cron gate runs inside installPackage's rollback window", async () => {
+      const cronMsg =
+         "materialization.schedule (cron) in publisher.json requires every " +
+         "persist source to declare '#@ persist ... sharing=private'.";
+      const mockPackage = {
+         formatInvalidExplores: () => "",
+         formatInvalidSchedule: () => cronMsg,
+      };
+      const installPackage = sinon
+         .stub()
+         .callsFake(
+            async (
+               _name: string,
+               _downloader: unknown,
+               validate?: (pkg: unknown) => string | undefined,
+            ) => {
+               const msg = validate?.(mockPackage);
+               if (msg) throw new BadRequestError(msg);
+               return mockPackage;
+            },
+         );
+      const environment = { installPackage };
+      const getEnvironment = sinon.stub().resolves(environment);
+      const addPackageToDatabase = sinon.stub().resolves(undefined);
+      const environmentStore = {
+         publisherConfigIsFrozen: false,
+         getEnvironment,
+         addPackageToDatabase,
+      } as unknown as EnvironmentStore;
+
+      const controller = new PackageController(environmentStore);
+
+      await expect(
+         controller.addPackage("env", {
+            name: "pkg",
+            description: "test",
+            location: "gs://bucket/pkg.zip",
+         }),
+      ).rejects.toThrow(cronMsg);
+
+      expect(addPackageToDatabase.called).toBe(false);
+   });
+});
+
 describe("PackageController.updatePackage explores validation", () => {
    afterEach(() => {
       sinon.restore();
@@ -138,6 +225,7 @@ describe("PackageController.updatePackage explores validation", () => {
       const mockPackage = {
          formatInvalidExplores: (override?: string[]) =>
             override?.includes("nope.malloy") ? invalidMsg : "",
+         formatInvalidSchedule: () => "",
       };
       const installPackage = sinon
          .stub()