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

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

@@ -5,6 +5,13 @@
  *
  * 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 =
@@ -12,6 +19,23 @@ const ASSET_EXTENSION_PATTERN =
 
 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 {
@@ -26,7 +50,7 @@ export async function load(url, context, nextLoad) {
   if (url.startsWith(ASSET_STUB_PROTOCOL)) {
     return {
       format: 'module',
-      source: 'export default {};',
+      source: ASSET_STUB_SOURCE,
       shortCircuit: true,
     };
   }

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

@@ -8,6 +8,11 @@
  *
  * 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
@@ -22,12 +27,14 @@ 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;
 }
 
@@ -36,6 +43,11 @@ export function validateEnv(env: Record<string, string | undefined>): ValidatedE
   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[] = [];
@@ -65,6 +77,7 @@ export function validateEnv(env: Record<string, string | undefined>): ValidatedE
     siteId: siteId as string,
     apiKey: apiKey as string,
     branchOverride,
+    defaultBranchName,
     puckConfigPath,
   };
 }
@@ -82,8 +95,60 @@ export function resolveConfigModule(mod: unknown): unknown {
  */
 export class NoBranchMatchError extends Error {}
 
-export function resolveBranchId(branches: Branch[], siteId: string, override?: string): string {
-  if (override !== undefined && override !== "") {
+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}`);
@@ -104,29 +169,41 @@ async function main(): Promise<void> {
   // never installs a process-wide loader hook.
   register("./asset-stub-hooks.mjs", import.meta.url);
 
-  const { baseUrl, siteId, apiKey, branchOverride, puckConfigPath } = validateEnv(process.env);
+  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);
+  const branchId = resolveBranchId(branches, siteId, branchOverride, defaultBranchName);
 
   if (dryRun) {
     console.log(
-      `[sync-puck-registry] Dry run: ${String(descriptors.length)} component descriptor(s) found for site ${siteId}, branch ${branchId}. No writes performed.`,
+      `[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, descriptors);
+  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`,
+      `wrote ${String(result.total)} component descriptor(s) + registry index` +
+      (skipped.length > 0 ? ` (${String(skipped.length)} asset-bearing component(s) left to the editor)` : ""),
   );
 }
 

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",
+    },
   },
 });