@mccaskie-labs/workbench-config 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.13
+
+### Patch Changes
+
+- The brand file: `brand.json` at the root of an app's repo (`BRAND_FILE`), checked by `defineBrand` (or `brandSchema`) and filled with the default colours (`BRAND_DEFAULTS`, `resolveBrand`). Name, site address, logo (https PNG, JPEG or SVG), colours, optional fonts, support address and footer line. workbench-email's account emails, workbench-pdf and Supabase's sign-in emails all read it, so an app is branded once.
+
 ## 0.1.12
 
 ### Patch Changes

package/README.md

@@ -27,6 +27,7 @@ const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
 | `sharedSecret(binding, name?)` | Reads a Secrets Store binding; throws if it is empty |
 | `redact(value)`, `redactAll(text, secrets)` | `[redacted]` in place of a secret, for logs |
 | `capabilities`, `MANIFEST_VERSION`, `capabilitySchema` | The Workbench capabilities manifests and their schema. The JSON files are also at `@mccaskie-labs/workbench-config/capabilities/<component>.json` |
+| `defineBrand(json)`, `brandSchema`, `resolveBrand`, `BRAND_DEFAULTS`, `BRAND_FILE` | The app's brand file, `brand.json` at the repo root: `name`, `siteUrl` (https), `logo.url` (https PNG, JPEG or SVG; optional `alt`, `width`, `height`), `colours.primary` (`#rrggbb`; `text`, `background`, `muted` default), optional `fonts.heading`/`fonts.body` (`{ family, url? }`, `url` an https stylesheet), `supportEmail` and `footer`. Unknown keys fail. Account emails, PDFs and Supabase's sign-in emails all read it |
 | `DEFAULT_GATEWAY_URL` | `https://gateway.mccaskielabs.dev` |
 
 `npx workbench-config check [dir]` compares the variable names in `.dev.vars` with `.dev.vars.example` and prints names only.

package/dist/brand.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * One brand file per app, read by workbench-email (account emails) and
+ * workbench-pdf (branded PDFs), so an app is branded once. Agreed between the
+ * sign-in kit and branded PDFs work on 11 November 2026.
+ *
+ * Lives in the app's repo as `brand.json` at the root, so Control can read it
+ * at a ref (as it reads migration files) without running the app's code. The
+ * app imports and checks it once:
+ *
+ *   import brandFile from '../brand.json'
+ *   export const brand = defineBrand(brandFile)
+ */
+/** Where the brand file sits in an app's repo. */
+export declare const BRAND_FILE = "brand.json";
+export declare const brandSchema: z.ZodObject<{
+    name: z.ZodString;
+    siteUrl: z.ZodURL;
+    logo: z.ZodObject<{
+        url: z.ZodURL;
+        alt: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    colours: z.ZodObject<{
+        primary: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        muted: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    fonts: z.ZodOptional<z.ZodObject<{
+        heading: z.ZodOptional<z.ZodObject<{
+            family: z.ZodString;
+            url: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strict>>;
+        body: z.ZodOptional<z.ZodObject<{
+            family: z.ZodString;
+            url: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    supportEmail: z.ZodOptional<z.ZodEmail>;
+    footer: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Brand = z.infer<typeof brandSchema>;
+/** The colours a brand leaves out. */
+export declare const BRAND_DEFAULTS: {
+    readonly text: "#1a1a1a";
+    readonly background: "#ffffff";
+    readonly muted: "#6b6b6b";
+};
+/** A brand with every colour filled, so emails and PDFs fill the same values. */
+export type ResolvedBrand = Brand & {
+    colours: Required<Brand["colours"]>;
+};
+/**
+ * Validates a brand and fills its default colours. Throws a plain Error
+ * naming every bad field (the brand holds nothing secret, so values may show).
+ */
+export declare function defineBrand(input: unknown): ResolvedBrand;
+/** Fills the default colours of an already valid brand. */
+export declare function resolveBrand(brand: Brand): ResolvedBrand;

package/dist/brand.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+/**
+ * One brand file per app, read by workbench-email (account emails) and
+ * workbench-pdf (branded PDFs), so an app is branded once. Agreed between the
+ * sign-in kit and branded PDFs work on 11 November 2026.
+ *
+ * Lives in the app's repo as `brand.json` at the root, so Control can read it
+ * at a ref (as it reads migration files) without running the app's code. The
+ * app imports and checks it once:
+ *
+ *   import brandFile from '../brand.json'
+ *   export const brand = defineBrand(brandFile)
+ */
+/** Where the brand file sits in an app's repo. */
+export const BRAND_FILE = "brand.json";
+const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/, "expected a colour like #1f6feb");
+const https = z.url({ protocol: /^https$/ });
+// A PNG, JPEG or SVG by its path: the PDF inlines the logo and refuses
+// anything else, and email clients show only these reliably.
+const logoUrl = https.refine((u) => /\.(png|jpe?g|svg)$/i.test(new URL(u).pathname), "expected a .png, .jpg, .jpeg or .svg URL");
+const font = z.strictObject({
+    /** The CSS family name. Without `url` it is used as a local font, with a system fallback. */
+    family: z.string().min(1).max(100),
+    /** An https stylesheet, such as a Google Fonts css2 link. */
+    url: https.optional(),
+});
+export const brandSchema = z.strictObject({
+    /** The app's name as people see it: "Sent by <name>", the PDF header. */
+    name: z.string().min(1).max(60),
+    /** The app's home page, https. Email links and the PDF footer. */
+    siteUrl: https,
+    logo: z.strictObject({
+        url: logoUrl,
+        alt: z.string().min(1).max(100).optional(),
+        /** Display width in CSS pixels; emails default to 120. */
+        width: z.number().int().min(16).max(600).optional(),
+        height: z.number().int().min(16).max(600).optional(),
+    }),
+    colours: z.strictObject({
+        /** Buttons, links and headings. */
+        primary: hex,
+        text: hex.optional(),
+        background: hex.optional(),
+        /** Small print and rules. */
+        muted: hex.optional(),
+    }),
+    fonts: z.strictObject({ heading: font.optional(), body: font.optional() }).optional(),
+    /** Shown as "Questions? Write to …" in account emails. */
+    supportEmail: z.email().optional(),
+    /** One line of small print under every email and PDF page. */
+    footer: z.string().min(1).max(200).optional(),
+});
+/** The colours a brand leaves out. */
+export const BRAND_DEFAULTS = {
+    text: "#1a1a1a",
+    background: "#ffffff",
+    muted: "#6b6b6b",
+};
+/**
+ * Validates a brand and fills its default colours. Throws a plain Error
+ * naming every bad field (the brand holds nothing secret, so values may show).
+ */
+export function defineBrand(input) {
+    const result = brandSchema.safeParse(input);
+    if (!result.success) {
+        const lines = result.error.issues.map((i) => `${i.path.join(".") || "(brand)"}: ${i.message}`);
+        throw new Error(`Invalid brand:\n${lines.join("\n")}`);
+    }
+    return resolveBrand(result.data);
+}
+/** Fills the default colours of an already valid brand. */
+export function resolveBrand(brand) {
+    const c = brand.colours;
+    return {
+        ...brand,
+        colours: {
+            primary: c.primary,
+            text: c.text ?? BRAND_DEFAULTS.text,
+            background: c.background ?? BRAND_DEFAULTS.background,
+            muted: c.muted ?? BRAND_DEFAULTS.muted,
+        },
+    };
+}

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export { WorkbenchConfigError, type ConfigErrorCode, type ConfigProblem } from "
 export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capability, type Component, type ManifestProblem, } from "./capability-schema.ts";
 export { capabilities, MANIFEST_VERSION, type Alias, type GatewayScope } from "./capabilities.gen.ts";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.ts";
+export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS, type Brand, type ResolvedBrand } from "./brand.ts";

package/dist/index.js

@@ -5,3 +5,4 @@ export { WorkbenchConfigError } from "./errors.js";
 export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, } from "./capability-schema.js";
 export { capabilities, MANIFEST_VERSION } from "./capabilities.gen.js";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.js";
+export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS } from "./brand.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",