@pantheon-systems/create-p1-starter-kit 0.6.0 → 0.8.0

package/template/scripts/__tests__/sync-puck-registry.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "vitest";
+import {
+  validateEnv,
+  resolveConfigModule,
+  resolveBranchId,
+  filterAssetStubbedDescriptors,
+  NoBranchMatchError,
+} from "../sync-puck-registry.js";
+import { ASSET_STUB_MARKER } from "../asset-stub-hooks.mjs";
+
+function baseEnv(overrides: Record<string, string | undefined> = {}): Record<string, string | undefined> {
+  return {
+    CSS_BASE_URL: "https://css.example.com",
+    CSS_SITE_ID: "site-123",
+    CSS_REGISTRY_API_KEY: "sat_registrytoken",
+    ...overrides,
+  };
+}
+
+describe("validateEnv", () => {
+  it("accepts CSS_BASE_URL/CSS_SITE_ID/CSS_REGISTRY_API_KEY directly", () => {
+    const result = validateEnv(baseEnv());
+    expect(result.baseUrl).toBe("https://css.example.com");
+    expect(result.siteId).toBe("site-123");
+    expect(result.apiKey).toBe("sat_registrytoken");
+    expect(result.branchOverride).toBeUndefined();
+    expect(result.puckConfigPath).toBe("puck.config.tsx");
+  });
+
+  it("falls back to NEXT_PUBLIC_CSS_BASE_URL and NEXT_PUBLIC_CSS_SITE_ID", () => {
+    const result = validateEnv(
+      baseEnv({
+        CSS_BASE_URL: undefined,
+        CSS_SITE_ID: undefined,
+        NEXT_PUBLIC_CSS_BASE_URL: "https://fallback.example.com",
+        NEXT_PUBLIC_CSS_SITE_ID: "site-fallback",
+      }),
+    );
+    expect(result.baseUrl).toBe("https://fallback.example.com");
+    expect(result.siteId).toBe("site-fallback");
+  });
+
+  it("falls back to NEXT_PUBLIC_CSS_BRANCH_ID for the branch override", () => {
+    const result = validateEnv(baseEnv({ NEXT_PUBLIC_CSS_BRANCH_ID: "staging" }));
+    expect(result.branchOverride).toBe("staging");
+  });
+
+  it("prefers CSS_BRANCH_ID over the NEXT_PUBLIC_ fallback when both are set", () => {
+    const result = validateEnv(baseEnv({ CSS_BRANCH_ID: "explicit", NEXT_PUBLIC_CSS_BRANCH_ID: "staging" }));
+    expect(result.branchOverride).toBe("explicit");
+  });
+
+  it("reads CSS_DEFAULT_BRANCH into defaultBranchName, overriding the default", () => {
+    const result = validateEnv(baseEnv({ CSS_DEFAULT_BRANCH: "master" }));
+    expect(result.defaultBranchName).toBe("master");
+  });
+
+  it("defaults defaultBranchName to 'main' when CSS_DEFAULT_BRANCH is not set", () => {
+    // Safe because the CSS main content branch is always literally named
+    // "main": a push override of "main" resolves to the same branch either
+    // by name match or by isMain, so the default only adds semantics.
+    const result = validateEnv(baseEnv());
+    expect(result.defaultBranchName).toBe("main");
+  });
+
+  it("defaults PUCK_CONFIG_PATH to puck.config.tsx", () => {
+    const result = validateEnv(baseEnv());
+    expect(result.puckConfigPath).toBe("puck.config.tsx");
+  });
+
+  it("honors an explicit PUCK_CONFIG_PATH", () => {
+    const result = validateEnv(baseEnv({ PUCK_CONFIG_PATH: "config/puck.config.tsx" }));
+    expect(result.puckConfigPath).toBe("config/puck.config.tsx");
+  });
+
+  it("reports all missing required vars together, not just the first", () => {
+    expect(() => validateEnv({})).toThrowError(/CSS_BASE_URL[\s\S]*CSS_SITE_ID[\s\S]*CSS_REGISTRY_API_KEY/);
+  });
+
+  it("gives an explicit, actionable message when only P1_CSS_API_KEY is set (do not reuse the read-only token)", () => {
+    expect(() =>
+      validateEnv(baseEnv({ CSS_REGISTRY_API_KEY: undefined, P1_CSS_API_KEY: "sat_readonlytoken" })),
+    ).toThrowError(/write:registry/);
+  });
+
+  it("does not accidentally accept P1_CSS_API_KEY as a substitute for CSS_REGISTRY_API_KEY", () => {
+    const result = () =>
+      validateEnv(baseEnv({ CSS_REGISTRY_API_KEY: undefined, P1_CSS_API_KEY: "sat_readonlytoken" }));
+    expect(result).toThrow();
+  });
+});
+
+describe("resolveConfigModule", () => {
+  it("prefers a default export", () => {
+    const mod = { default: { components: {} }, config: { wrong: true } };
+    expect(resolveConfigModule(mod)).toBe(mod.default);
+  });
+
+  it("falls back to a named config export when there is no default", () => {
+    const mod = { config: { components: {} } };
+    expect(resolveConfigModule(mod)).toBe(mod.config);
+  });
+
+  it("falls back to the module itself when neither default nor config is present", () => {
+    const mod = { components: {} };
+    expect(resolveConfigModule(mod)).toBe(mod);
+  });
+});
+
+describe("resolveBranchId", () => {
+  const branches = [
+    { id: "b-1", siteId: "site-123", name: "main", isMain: true },
+    { id: "b-2", siteId: "site-123", name: "staging", isMain: false },
+  ];
+
+  it("resolves to the main branch when no override is given", () => {
+    expect(resolveBranchId(branches as never, "site-123")).toBe("b-1");
+  });
+
+  it("resolves an override by branch id", () => {
+    expect(resolveBranchId(branches as never, "site-123", "b-2")).toBe("b-2");
+  });
+
+  it("resolves an override by branch name", () => {
+    expect(resolveBranchId(branches as never, "site-123", "staging")).toBe("b-2");
+  });
+
+  it("throws NoBranchMatchError ('No main branch found') when there is no override and no isMain branch", () => {
+    const noMain = [{ id: "b-2", siteId: "site-123", name: "staging", isMain: false }];
+    expect(() => resolveBranchId(noMain as never, "site-123")).toThrowError(
+      "No main branch found for site site-123",
+    );
+    try {
+      resolveBranchId(noMain as never, "site-123");
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(NoBranchMatchError);
+    }
+  });
+
+  it("throws NoBranchMatchError when an explicit override matches no branch by id or name", () => {
+    expect(() => resolveBranchId(branches as never, "site-123", "nonexistent")).toThrow(NoBranchMatchError);
+  });
+});
+
+describe("resolveBranchId default-branch semantics", () => {
+  // In CI the override is always the pushed git ref's name, so a repo whose
+  // default branch is not literally named "main" would never match the CSS
+  // main branch (whose name is always "main") — the sync silently skips on
+  // every default-branch push. When the caller also supplies the repo's
+  // default branch name, an override equal to it must resolve via isMain.
+  const branches = [
+    { id: "b-1", siteId: "site-123", name: "main", isMain: true },
+    { id: "b-2", siteId: "site-123", name: "staging", isMain: false },
+  ];
+
+  it("resolves the isMain branch when the override is the repo's default branch name", () => {
+    expect(resolveBranchId(branches as never, "site-123", "master", "master")).toBe("b-1");
+  });
+
+  it("prefers isMain over a coincidental name match for the default branch", () => {
+    const withDecoy = [...branches, { id: "b-3", siteId: "site-123", name: "master", isMain: false }];
+    expect(resolveBranchId(withDecoy as never, "site-123", "master", "master")).toBe("b-1");
+  });
+
+  it("throws NoBranchMatchError for a default-branch override when no isMain branch exists", () => {
+    const noMain = [{ id: "b-2", siteId: "site-123", name: "staging", isMain: false }];
+    expect(() => resolveBranchId(noMain as never, "site-123", "master", "master")).toThrow(NoBranchMatchError);
+  });
+
+  it("keeps plain name matching for overrides that are not the default branch", () => {
+    expect(resolveBranchId(branches as never, "site-123", "staging", "master")).toBe("b-2");
+  });
+
+  it("keeps the silent-skip path for non-default refs that match nothing", () => {
+    expect(() => resolveBranchId(branches as never, "site-123", "feature-x", "master")).toThrow(NoBranchMatchError);
+  });
+});
+
+describe("filterAssetStubbedDescriptors", () => {
+  // CI loads puck.config.tsx under the asset-stub loader, so any defaultProps
+  // value derived from an asset import is a branded sentinel, not the real
+  // bundler-resolved value. CI cannot faithfully describe those components —
+  // it skips them (loudly) and leaves them to the editor path.
+
+  const descriptor = (name: string, defaultProps: Record<string, unknown>) =>
+    ({ name, label: name, fields: [], defaultProps, descriptorHash: "h" }) as never;
+
+  it("keeps descriptors whose defaults are plain values", () => {
+    const clean = descriptor("heroBlock", { title: "Hello", count: 3, nested: { a: [1, "x"] } });
+    const { writable, skipped } = filterAssetStubbedDescriptors([clean]);
+    expect(writable).toEqual([clean]);
+    expect(skipped).toEqual([]);
+  });
+
+  it("skips a descriptor whose default carries the asset-stub marker string (placeholder.src pattern)", () => {
+    const stubbed = descriptor("imageBlock", { src: ASSET_STUB_MARKER, alt: "Mountain" });
+    const { writable, skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(writable).toEqual([]);
+    expect(skipped.map((d: { name: string }) => d.name)).toEqual(["imageBlock"]);
+  });
+
+  it("skips a descriptor whose default is a branded stub object (whole-import pattern)", () => {
+    const stubbed = descriptor("imageBlock", { src: { __p1AssetStub: true } });
+    const { skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(skipped).toHaveLength(1);
+  });
+
+  it("detects the marker arbitrarily deep in defaultProps", () => {
+    const stubbed = descriptor("gallery", { items: [{ media: { src: `prefix ${ASSET_STUB_MARKER}` } }] });
+    const { skipped } = filterAssetStubbedDescriptors([stubbed]);
+    expect(skipped).toHaveLength(1);
+  });
+
+  it("partitions a mixed list preserving order of writable descriptors", () => {
+    const a = descriptor("a", { t: "1" });
+    const b = descriptor("b", { src: ASSET_STUB_MARKER });
+    const c = descriptor("c", { t: "2" });
+    const { writable, skipped } = filterAssetStubbedDescriptors([a, b, c]);
+    expect(writable.map((d: { name: string }) => d.name)).toEqual(["a", "c"]);
+    expect(skipped.map((d: { name: string }) => d.name)).toEqual(["b"]);
+  });
+
+  it("does not hang on circular defaultProps", () => {
+    const circular: Record<string, unknown> = { title: "ok" };
+    circular.self = circular;
+    const { skipped } = filterAssetStubbedDescriptors([descriptor("looper", circular)]);
+    expect(skipped).toEqual([]);
+  });
+});

package/template/scripts/asset-stub-hooks.mjs

@@ -0,0 +1,58 @@
+/**
+ * Node module customization hooks that stub out non-JS asset imports
+ * (CSS, images, fonts, video) so a plain Node script can `import()` a
+ * Next.js app's puck.config.tsx without a bundler. Zero dependencies.
+ *
+ * Wire in with node:module's register() — not the --import flag, which
+ * does not auto-install a resolve/load-only hooks file.
+ *
+ * The stub is a *branded* sentinel, not a bare {}: the browser bundler
+ * resolves these same imports to real URLs/StaticImageData that this script
+ * cannot compute. The brand (`__p1AssetStub`) and the marker string (returned
+ * for every property read, so `placeholder.src` stays detectable) let the
+ * sync filter recognize and skip such components instead of writing wrong
+ * descriptor content and a hash the editor will forever disagree with.
+ */
+
+const ASSET_EXTENSION_PATTERN =
+  /\.(css|scss|sass|less|png|jpe?g|gif|svg|webp|ico|bmp|avif|woff2?|ttf|eot|otf|mp4|webm|mov|mp3|wav)$/i;
+
+const ASSET_STUB_PROTOCOL = 'asset-stub:';
+
+export const ASSET_STUB_MARKER = '__p1_asset_stub__';
+
+// The get trap resolves every unknown property (including well-known symbols)
+// to the marker string, so exotic usage of a stub (spread, iteration) throws
+// during extraction — deliberately loud, rather than silently producing
+// garbage.
+const ASSET_STUB_SOURCE = `
+const target = {
+  __p1AssetStub: true,
+  toString: () => '${ASSET_STUB_MARKER}',
+  [Symbol.toPrimitive]: () => '${ASSET_STUB_MARKER}',
+};
+export default new Proxy(target, {
+  get: (t, prop) => (prop in t ? t[prop] : '${ASSET_STUB_MARKER}'),
+});
+`;
+
+export async function resolve(specifier, context, nextResolve) {
+  if (ASSET_EXTENSION_PATTERN.test(specifier)) {
+    return {
+      url: `${ASSET_STUB_PROTOCOL}${encodeURIComponent(specifier)}`,
+      shortCircuit: true,
+    };
+  }
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.startsWith(ASSET_STUB_PROTOCOL)) {
+    return {
+      format: 'module',
+      source: ASSET_STUB_SOURCE,
+      shortCircuit: true,
+    };
+  }
+  return nextLoad(url, context);
+}

package/template/scripts/sync-puck-registry.ts

@@ -0,0 +1,225 @@
+/**
+ * Syncs this site's Puck component registry (_registry/components/* and the
+ * registry index) headlessly, without opening the editor in a browser.
+ * Intended to run from CI on push to main or a branch whose name matches a
+ * CSS branch, whenever puck.config.tsx or components/puck/** change.
+ *
+ * Usage: tsx scripts/sync-puck-registry.ts [--dry-run]
+ *
+ * Required env vars (see validateEnv below for the full fallback contract):
+ *   CSS_BASE_URL, CSS_SITE_ID, CSS_REGISTRY_API_KEY
+ * Optional:
+ *   CSS_BRANCH_ID — CSS branch to target (in CI: the pushed git ref's name)
+ *   CSS_DEFAULT_BRANCH — the repo's default branch name (defaults to "main");
+ *   when CSS_BRANCH_ID equals it, the site's isMain branch is targeted
+ *   regardless of naming (see resolveBranchId for the resolution contract)
+ *
+ * CSS_REGISTRY_API_KEY must be a sat_ site token scoped to write:registry
+ * only — do not reuse a read-scoped token (P1_CSS_API_KEY). Because that
+ * token has no read access at all, every run rewrites every component
+ * descriptor + the registry index unconditionally (no skip-if-unchanged) —
+ * see syncComponentRegistryWriteOnly.
+ */
+
+import { register } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { P1Client } from "@pantheon-systems/css-client";
+import type { Branch } from "@pantheon-systems/css-client";
+import { extractDescriptors, syncComponentRegistryWriteOnly } from "@pantheon-systems/puck-css/registry-sync";
+import { ASSET_STUB_MARKER } from "./asset-stub-hooks.mjs";
+
+export interface ValidatedEnv {
+  baseUrl: string;
+  siteId: string;
+  apiKey: string;
+  branchOverride?: string;
+  defaultBranchName?: string;
+  puckConfigPath: string;
+}
+
+export function validateEnv(env: Record<string, string | undefined>): ValidatedEnv {
+  const baseUrl = env.CSS_BASE_URL ?? env.NEXT_PUBLIC_CSS_BASE_URL;
+  const siteId = env.CSS_SITE_ID ?? env.NEXT_PUBLIC_CSS_SITE_ID;
+  const apiKey = env.CSS_REGISTRY_API_KEY;
+  const branchOverride = env.CSS_BRANCH_ID ?? env.NEXT_PUBLIC_CSS_BRANCH_ID;
+  // Defaults to "main": the CSS main content branch is always literally
+  // named "main", so for repos whose default git branch is also "main" this
+  // resolves to the same branch it would have matched by name. Repos with a
+  // differently-named default branch (master, trunk) must set it explicitly.
+  const defaultBranchName = env.CSS_DEFAULT_BRANCH ?? "main";
+  const puckConfigPath = env.PUCK_CONFIG_PATH ?? "puck.config.tsx";
+
+  const missing: string[] = [];
+  if (baseUrl === undefined || baseUrl === "") {
+    missing.push("CSS_BASE_URL (or NEXT_PUBLIC_CSS_BASE_URL)");
+  }
+  if (siteId === undefined || siteId === "") {
+    missing.push("CSS_SITE_ID (or NEXT_PUBLIC_CSS_SITE_ID)");
+  }
+  if (apiKey === undefined || apiKey === "") {
+    if (env.P1_CSS_API_KEY !== undefined && env.P1_CSS_API_KEY !== "") {
+      missing.push(
+        "CSS_REGISTRY_API_KEY — do not reuse P1_CSS_API_KEY (your read-scoped site token); " +
+          "create a separate sat_ token scoped to write:registry",
+      );
+    } else {
+      missing.push("CSS_REGISTRY_API_KEY");
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variable(s):\n  - ${missing.join("\n  - ")}`);
+  }
+
+  return {
+    baseUrl: baseUrl as string,
+    siteId: siteId as string,
+    apiKey: apiKey as string,
+    branchOverride,
+    defaultBranchName,
+    puckConfigPath,
+  };
+}
+
+export function resolveConfigModule(mod: unknown): unknown {
+  const record = mod as Record<string, unknown>;
+  return record.default ?? record.config ?? mod;
+}
+
+/**
+ * Thrown by resolveBranchId when no CSS branch matches. Distinguished from
+ * other errors so callers (main(), a CI trigger firing on every git branch)
+ * can treat "this branch has no CSS counterpart" as a benign no-op rather
+ * than a real sync failure.
+ */
+export class NoBranchMatchError extends Error {}
+
+type Descriptor = ReturnType<typeof extractDescriptors>[number];
+
+function containsAssetStubValue(value: unknown, seen = new Set<object>()): boolean {
+  if (typeof value === "string") return value.includes(ASSET_STUB_MARKER);
+  if (typeof value !== "object" || value === null) return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if ((value as Record<string, unknown>).__p1AssetStub === true) return true;
+  return Object.values(value).some((nested) => containsAssetStubValue(nested, seen));
+}
+
+/**
+ * Partitions descriptors into those this script can faithfully write and
+ * those it must skip. Under the asset-stub loader, any config
+ * value derived from an asset import is a branded sentinel — the browser
+ * bundler resolves the same import to a real URL this script cannot know.
+ * Writing such a descriptor stores wrong default values and an index hash
+ * the editor will disagree with on every load (a perpetual re-register
+ * flip-flop between CI and editor). Skipped components stay editor-owned:
+ * one writer per component, no disagreement.
+ *
+ * Scans the whole descriptor, not just defaultProps, so a stub value that
+ * reaches any future descriptor field is still caught.
+ */
+export function filterAssetStubbedDescriptors(descriptors: Descriptor[]): {
+  writable: Descriptor[];
+  skipped: Descriptor[];
+} {
+  const writable: Descriptor[] = [];
+  const skipped: Descriptor[] = [];
+  for (const descriptor of descriptors) {
+    (containsAssetStubValue(descriptor) ? skipped : writable).push(descriptor);
+  }
+  return { writable, skipped };
+}
+
+/**
+ * Resolution contract: an override (in CI, always the pushed git ref's name)
+ * matches a CSS branch by id or name — EXCEPT when it equals the repo's
+ * default branch name, which always resolves the site's isMain branch. CSS
+ * main is always literally named "main", so without that rule a repo whose
+ * default branch is "master"/"trunk" would silently skip on every push. The
+ * default branch means the main registry, even over a coincidental CSS
+ * branch named e.g. "master".
+ */
+export function resolveBranchId(
+  branches: Branch[],
+  siteId: string,
+  override?: string,
+  defaultBranchName?: string,
+): string {
+  const isDefaultBranch =
+    override !== undefined && override !== "" && override === defaultBranchName;
+  if (override !== undefined && override !== "" && !isDefaultBranch) {
+    const match = branches.find((b) => b.id === override || b.name === override);
+    if (match === undefined) {
+      throw new NoBranchMatchError(`No branch matching "${override}" found for site ${siteId}`);
+    }
+    return match.id;
+  }
+  const mainBranch = branches.find((b) => b.isMain);
+  if (mainBranch === undefined) {
+    throw new NoBranchMatchError("No main branch found for site " + siteId);
+  }
+  return mainBranch.id;
+}
+
+async function main(): Promise<void> {
+  const dryRun = process.argv.includes("--dry-run");
+
+  // Registered here (not at module scope) so importing this file for tests
+  // never installs a process-wide loader hook.
+  register("./asset-stub-hooks.mjs", import.meta.url);
+
+  const { baseUrl, siteId, apiKey, branchOverride, defaultBranchName, puckConfigPath } =
+    validateEnv(process.env);
+
+  const configUrl = pathToFileURL(path.resolve(process.cwd(), puckConfigPath)).href;
+  const mod: unknown = await import(configUrl);
+  const puckConfig = resolveConfigModule(mod);
+
+  const descriptors = extractDescriptors(puckConfig);
+  const { writable, skipped } = filterAssetStubbedDescriptors(descriptors);
+
+  for (const descriptor of skipped) {
+    console.warn(
+      `[sync-puck-registry] SKIPPED ${descriptor.name}: its defaults use bundler-resolved asset imports ` +
+        `this script cannot faithfully compute — it will register from the editor instead. ` +
+        `To include it in CI sync, replace imported assets in defaultProps with plain string paths.`,
+    );
+  }
+
+  const client = new P1Client({ baseUrl, apiKey });
+  const branches = await client.branches.list(siteId);
+  const branchId = resolveBranchId(branches, siteId, branchOverride, defaultBranchName);
+
+  if (dryRun) {
+    console.log(
+      `[sync-puck-registry] Dry run: ${String(writable.length)} component descriptor(s) to write ` +
+        `(${String(skipped.length)} skipped) for site ${siteId}, branch ${branchId}. No writes performed.`,
+    );
+    return;
+  }
+
+  const result = await syncComponentRegistryWriteOnly(client, siteId, branchId, writable);
+  console.log(
+    `[sync-puck-registry] Synced site ${siteId}, branch ${branchId}: ` +
+      `wrote ${String(result.total)} component descriptor(s) + registry index` +
+      (skipped.length > 0 ? ` (${String(skipped.length)} asset-bearing component(s) left to the editor)` : ""),
+  );
+}
+
+const isMainModule = import.meta.url === pathToFileURL(process.argv[1] ?? "").href;
+if (isMainModule) {
+  main().catch((err: unknown) => {
+    // A CI trigger firing on every git branch push has no way to know ahead
+    // of time which branches have a matching CSS branch — that has to be
+    // discovered at runtime. Treat "no match" as a benign no-op, not a
+    // failure, so unrelated feature-branch pushes don't turn CI red.
+    if (err instanceof NoBranchMatchError) {
+      console.log(`[sync-puck-registry] Skipping: ${err.message}`);
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[sync-puck-registry] FAILED:", message);
+    process.exitCode = 1;
+  });
+}

package/template/tsconfig.test.json

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}

package/template/vitest.config.ts

@@ -1,7 +1,12 @@
 import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
 
 export default defineConfig({
+  plugins: [react()],
   test: {
     environment: "node",
+    typecheck: {
+      tsconfig: "./tsconfig.test.json",
+    },
   },
 });