@mccaskie-labs/workbench-config 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- Capabilities: analytics lists cf_web_analytics_site_delete and the WEB_ANALYTICS_TOKEN config written by cf_worker_secret_put source=web_analytics; manifests may say a tool ships in phase 5.
+
 ## 0.1.11
 
 ### 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/capabilities/analytics.json

@@ -12,21 +12,40 @@
       "eventsMigration"
     ],
     "tools": [
-      "cf_web_analytics_site_create"
+      "cf_web_analytics_site_create",
+      "cf_web_analytics_site_delete",
+      "cf_worker_secret_put"
     ]
   },
+  "config": [
+    {
+      "name": "WEB_ANALYTICS_TOKEN",
+      "required": false,
+      "secret": false,
+      "environments": [
+        "staging",
+        "production"
+      ],
+      "description": "The public beacon token of the Web Analytics site for the Worker's own hostname, for beaconScript(); written by cf_worker_secret_put source=web_analytics (free, new or replacing). Unset in development and CI, where beaconScript returns ''"
+    }
+  ],
   "actions": [
     {
       "tool": "cf_web_analytics_site_create",
       "gate": "free",
       "ships": "4"
+    },
+    {
+      "tool": "cf_web_analytics_site_delete",
+      "gate": "two_step",
+      "ships": "5"
     }
   ],
   "rules": [
     {
       "id": "analytics.beacon-on-pages",
       "kind": "must",
-      "text": "Put beaconScript(token) on every page, with the site's public beacon token from cf_web_analytics_site_create.",
+      "text": "Put beaconScript(env.WEB_ANALYTICS_TOKEN) on every page; Control writes the site's public beacon token onto each Worker with cf_worker_secret_put source=web_analytics.",
       "enforced_by": "review",
       "probe": "analytics.beacon"
     },

package/capabilities/schema.json

@@ -211,6 +211,7 @@
             "enum": [
               "3",
               "4",
+              "5",
               "later"
             ]
           }

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/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "debb0b3db404";
+export declare const MANIFEST_VERSION: "f3d5b55e579d";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -145,18 +145,29 @@ export declare const capabilities: {
         readonly summary: "Cloudflare Web Analytics counts page views through a beacon on every page; product events go into the app's own database through workbench-analytics. Apps hold no Cloudflare token: Claude reads page views through Control.";
         readonly status: "built";
         readonly surfaces: {
-            readonly tools: readonly ["cf_web_analytics_site_create"];
+            readonly tools: readonly ["cf_web_analytics_site_create", "cf_web_analytics_site_delete", "cf_worker_secret_put"];
             readonly package: readonly ["beaconScript", "createEvents", "eventsMigration"];
         };
+        readonly config: readonly [{
+            readonly name: "WEB_ANALYTICS_TOKEN";
+            readonly required: false;
+            readonly secret: false;
+            readonly environments: readonly ["staging", "production"];
+            readonly description: "The public beacon token of the Web Analytics site for the Worker's own hostname, for beaconScript(); written by cf_worker_secret_put source=web_analytics (free, new or replacing). Unset in development and CI, where beaconScript returns ''";
+        }];
         readonly actions: readonly [{
             readonly tool: "cf_web_analytics_site_create";
             readonly gate: "free";
             readonly ships: "4";
+        }, {
+            readonly tool: "cf_web_analytics_site_delete";
+            readonly gate: "two_step";
+            readonly ships: "5";
         }];
         readonly rules: readonly [{
             readonly id: "analytics.beacon-on-pages";
             readonly kind: "must";
-            readonly text: "Put beaconScript(token) on every page, with the site's public beacon token from cf_web_analytics_site_create.";
+            readonly text: "Put beaconScript(env.WEB_ANALYTICS_TOKEN) on every page; Control writes the site's public beacon token onto each Worker with cf_worker_secret_put source=web_analytics.";
             readonly enforced_by: "review";
             readonly probe: "analytics.beacon";
         }, {

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "debb0b3db404";
+export const MANIFEST_VERSION = "f3d5b55e579d";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -203,7 +203,9 @@ export const capabilities = {
         "status": "built",
         "surfaces": {
             "tools": [
-                "cf_web_analytics_site_create"
+                "cf_web_analytics_site_create",
+                "cf_web_analytics_site_delete",
+                "cf_worker_secret_put"
             ],
             "package": [
                 "beaconScript",
@@ -211,18 +213,35 @@ export const capabilities = {
                 "eventsMigration"
             ]
         },
+        "config": [
+            {
+                "name": "WEB_ANALYTICS_TOKEN",
+                "required": false,
+                "secret": false,
+                "environments": [
+                    "staging",
+                    "production"
+                ],
+                "description": "The public beacon token of the Web Analytics site for the Worker's own hostname, for beaconScript(); written by cf_worker_secret_put source=web_analytics (free, new or replacing). Unset in development and CI, where beaconScript returns ''"
+            }
+        ],
         "actions": [
             {
                 "tool": "cf_web_analytics_site_create",
                 "gate": "free",
                 "ships": "4"
+            },
+            {
+                "tool": "cf_web_analytics_site_delete",
+                "gate": "two_step",
+                "ships": "5"
             }
         ],
         "rules": [
             {
                 "id": "analytics.beacon-on-pages",
                 "kind": "must",
-                "text": "Put beaconScript(token) on every page, with the site's public beacon token from cf_web_analytics_site_create.",
+                "text": "Put beaconScript(env.WEB_ANALYTICS_TOKEN) on every page; Control writes the site's public beacon token onto each Worker with cf_worker_secret_put source=web_analytics.",
                 "enforced_by": "review",
                 "probe": "analytics.beacon"
             },

package/dist/capability-schema.d.ts

@@ -146,6 +146,7 @@ export declare const capabilitySchema: z.ZodObject<{
         ships: z.ZodEnum<{
             3: "3";
             4: "4";
+            5: "5";
             later: "later";
         }>;
     }, z.core.$strict>>>;

package/dist/capability-schema.js

@@ -45,7 +45,7 @@ const action = z.strictObject({
     tool: z.string().regex(/^[a-z]+_[a-z0-9_]+$/),
     gate: z.enum(["free", "two_step", "two_step_on_production", "two_step_when"]),
     when: z.string().min(1).optional(),
-    ships: z.enum(["3", "4", "later"]),
+    ships: z.enum(["3", "4", "5", "later"]),
 });
 const errorEntry = z.strictObject({
     code,

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.11",
+  "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",