@dbx-tools/shared-core 0.1.22 → 0.1.23

package/.projen/deps.json

@@ -23,6 +23,11 @@
       "name": "consola",
       "version": "catalog:",
       "type": "peer"
+    },
+    {
+      "name": "zod",
+      "version": "catalog:",
+      "type": "runtime"
     }
   ],
   "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\"."

package/README.md

@@ -15,6 +15,7 @@ import {
   log,
   net,
   object,
+  brand,
   string,
 } from "@dbx-tools/shared-core";
 ```
@@ -36,6 +37,24 @@ Key features:
   logging helpers that avoid Node-only dependencies.
 - Namespace exports that make utility call sites explicit without creating a
   grab-bag default import.
+- A Zod-backed `BrandContext` contract with dbx tools defaults, JSON Schema
+  output, and prompt serialization for browser, library, and LLM consumers.
+
+## Brand Context
+
+```ts
+import { brand } from "@dbx-tools/shared-core";
+
+const context = brand.parseBrandContext({ name: "Acme Data" });
+const jsonSchema = brand.brandContextJsonSchema();
+const instructions = brand.brandContextPrompt(context);
+```
+
+`BrandContextSchema` validates identity, theme-aware assets, colors,
+typography, links, audience, and voice. Every field has a dbx tools default, so
+an empty object is a complete context. Use [`@dbx-tools/core`](../../node/core)
+to discover and read YAML/JSON files, and
+[`@dbx-tools/ui-branding`](../../ui/branding) to apply the same context to a UI.
 
 ## Async Control
 
@@ -217,3 +236,4 @@ without paying formatting cost when disabled.
 - `token` - JWT payload and scope readers.
 - `functionModule` - memoization.
 - `log` - tagged leveled logging.
+- `brand` - Zod schema, defaults, JSON Schema, and LLM prompt serialization.

package/index.ts

@@ -3,6 +3,7 @@
 // Hand edits are overwritten on the next watch; this file is read-only.
 
 export * as async from "./src/async";
+export * as brand from "./src/brand";
 export * as error from "./src/error";
 export * as functionModule from "./src/function";
 export * as hash from "./src/hash";
@@ -14,6 +15,7 @@ export * as predicate from "./src/predicate";
 export * as string from "./src/string";
 export * as token from "./src/token";
 export type { PollContext, PollProducer, PollOptions } from "./src/async";
+export type { BrandContext, BrandContextInput, BrandAssetSet } from "./src/brand";
 export type { ErrorContext } from "./src/error";
 export type { MemoizeOptions } from "./src/function";
 export type { HeaderLike } from "./src/http";

package/package.json

@@ -14,12 +14,15 @@
   "peerDependencies": {
     "consola": "^3.4.2"
   },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.1.22",
+  "version": "0.1.23",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/brand.ts

@@ -0,0 +1,136 @@
+/**
+ * Browser-safe brand contract, defaults, and LLM serialization helpers.
+ *
+ * Asset values are intentionally strings: they may be relative file paths,
+ * package exports, data URLs, or network URLs depending on the consumer.
+ */
+import { z } from "zod";
+
+const nonBlankString = z.string().trim().min(1);
+const color = z.string().regex(/^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i, "Expected a hex color.");
+
+export const DEFAULT_BRAND_ASSETS = {
+  icon: {
+    light: "@dbx-tools/ui-branding/assets/icon-light.svg",
+    dark: "@dbx-tools/ui-branding/assets/icon-dark.svg",
+  },
+  logo: {
+    light: "@dbx-tools/ui-branding/assets/logo-light.svg",
+    dark: "@dbx-tools/ui-branding/assets/logo-dark.svg",
+  },
+  favicon: "@dbx-tools/ui-branding/assets/icon-light.svg",
+} as const;
+
+export const BrandAssetSetSchema = z
+  .object({
+    light: nonBlankString.describe("Asset for light surfaces."),
+    dark: nonBlankString.optional().describe("Asset for dark surfaces; light is the fallback."),
+  })
+  .strict()
+  .describe("Theme-aware references to one visual asset.");
+
+export const BrandColorsSchema = z
+  .object({
+    primary: color.default("#FF3621").describe("Primary action and identity color."),
+    primaryHover: color.default("#D92D18").describe("Primary hover or pressed color."),
+    accent: color.default("#00A972").describe("Secondary accent color."),
+    foreground: color.default("#0B2026").describe("Default text and mark color."),
+    background: color.default("#FFFFFF").describe("Default page background."),
+    surface: color.default("#F6F7F8").describe("Secondary surface background."),
+    muted: color.default("#5F6B70").describe("Muted text color."),
+    border: color.default("#DCE2E5").describe("Default border color."),
+  })
+  .strict()
+  .prefault({});
+
+export const BrandVoiceSchema = z
+  .object({
+    audience: z
+      .array(nonBlankString)
+      .default(["Databricks developers", "application engineers", "AI agents"]),
+    tone: z.array(nonBlankString).default(["direct", "practical", "technical", "approachable"]),
+    principles: z
+      .array(nonBlankString)
+      .default([
+        "Lead with the useful outcome.",
+        "Prefer concrete examples and accurate technical language.",
+        "Keep product claims specific and defensible.",
+      ]),
+    avoid: z
+      .array(nonBlankString)
+      .default(["unsupported superlatives", "vague AI claims", "unnecessary jargon"]),
+  })
+  .strict()
+  .prefault({});
+
+export const BrandContextSchema = z
+  .object({
+    schemaVersion: z.literal("1").default("1"),
+    name: nonBlankString.default("dbx tools").describe("Canonical display name."),
+    shortName: nonBlankString.default("dbx").describe("Compact name for constrained UI."),
+    tagline: nonBlankString
+      .default("Practical tools for Databricks builders.")
+      .describe("Short product line suitable for a header or metadata."),
+    description: nonBlankString
+      .default(
+        "Companion packages for Databricks developers building apps, agents, data workflows, and reusable UI.",
+      )
+      .describe("Plain-language product description."),
+    assets: z
+      .object({
+        icon: BrandAssetSetSchema.default(DEFAULT_BRAND_ASSETS.icon),
+        logo: BrandAssetSetSchema.default(DEFAULT_BRAND_ASSETS.logo),
+        favicon: nonBlankString.default(DEFAULT_BRAND_ASSETS.favicon),
+      })
+      .strict()
+      .default(DEFAULT_BRAND_ASSETS),
+    colors: BrandColorsSchema,
+    typography: z
+      .object({
+        sans: nonBlankString.default("Inter, ui-sans-serif, system-ui, sans-serif"),
+        mono: nonBlankString.default("ui-monospace, SFMono-Regular, Menlo, monospace"),
+      })
+      .strict()
+      .prefault({}),
+    voice: BrandVoiceSchema,
+    links: z
+      .object({
+        website: z.string().url().optional(),
+        repository: z.string().url().optional(),
+        documentation: z.string().url().optional(),
+      })
+      .strict()
+      .default({}),
+    extensions: z
+      .record(nonBlankString, z.unknown())
+      .default({})
+      .describe("Namespaced consumer-specific values that do not belong in the portable core."),
+  })
+  .strict()
+  .describe("Portable identity, visual, and voice context for UI, libraries, and LLMs.");
+
+export type BrandContext = z.output<typeof BrandContextSchema>;
+export type BrandContextInput = z.input<typeof BrandContextSchema>;
+export type BrandAssetSet = z.output<typeof BrandAssetSetSchema>;
+
+/** Validate input and fill every dbx tools default. */
+export function parseBrandContext(input: unknown = {}): BrandContext {
+  return BrandContextSchema.parse(input);
+}
+
+export const defaultBrandContext: BrandContext = parseBrandContext();
+
+/** JSON Schema representation suitable for structured-output and tool definitions. */
+export function brandContextJsonSchema(): Record<string, unknown> {
+  return z.toJSONSchema(BrandContextSchema) as Record<string, unknown>;
+}
+
+/** Stable prompt block for an LLM that needs to write or design in this brand. */
+export function brandContextPrompt(context: BrandContext = defaultBrandContext): string {
+  return [
+    `Use the following ${context.name} brand context for names, visual choices, and writing voice.`,
+    "Treat explicit task instructions as higher priority than this context.",
+    "",
+    JSON.stringify(context, null, 2),
+  ].join("\n");
+}

package/test/brand.test.ts

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { brand } from "../index";
+
+describe("brand context", () => {
+  it("fills dbx tools defaults", () => {
+    const context = brand.parseBrandContext();
+
+    assert.equal(context.name, "dbx tools");
+    assert.equal(context.assets.icon.light, brand.DEFAULT_BRAND_ASSETS.icon.light);
+    assert.equal(context.colors.primary, "#FF3621");
+  });
+
+  it("validates nested overrides and preserves defaults", () => {
+    const context = brand.parseBrandContext({
+      name: "Example",
+      colors: { primary: "#123456" },
+    });
+
+    assert.equal(context.name, "Example");
+    assert.equal(context.colors.primary, "#123456");
+    assert.equal(context.colors.background, "#FFFFFF");
+  });
+
+  it("exports schema and prompt forms for LLM consumers", () => {
+    const schema = brand.brandContextJsonSchema();
+    const prompt = brand.brandContextPrompt();
+
+    assert.equal(schema.type, "object");
+    assert.match(prompt, /dbx tools brand context/);
+    assert.match(prompt, /"schemaVersion": "1"/);
+  });
+});