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

package/README.md

@@ -0,0 +1,114 @@
+# @pantheon-systems/create-p1-starter-kit
+
+Scaffold a new P1 project — a Next.js app with the Puck visual editor and Pantheon Content
+Publisher integration wired up and ready to run.
+
+## Usage
+
+```bash
+# pnpm
+pnpm create @pantheon-systems/p1-starter-kit my-app
+
+# npm
+npm create @pantheon-systems/p1-starter-kit my-app
+
+# yarn
+yarn create @pantheon-systems/p1-starter-kit my-app
+```
+
+The CLI prompts for:
+
+- **Project name** — defaults to the directory name argument
+- **Package manager** — auto-detects pnpm/npm/yarn, allows override
+- **Git initialization** — creates a repo with an initial commit
+- **Dependency installation** — runs install immediately
+
+## What's included
+
+- **Next.js 16 App Router** — server components and modern routing
+- **Puck editor** — visual drag-and-drop page building at `/p1/<path>`
+- **Content Publisher integration** — CMS with datasource bindings
+- **Pre-built blocks** — typography, media, layout, and action components
+- **Tailwind CSS v4**, **TypeScript**, **Vitest**, **ESLint**
+
+## Getting started
+
+After scaffolding:
+
+1. **Configure environment variables:**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Fill in:
+
+   | Variable | Purpose |
+   | --- | --- |
+   | `PCC_SITE_ID` | Content Cloud site ID |
+   | `PCC_TOKEN` | API token for your site |
+   | `NEXT_PUBLIC_CSS_BASE_URL` | CSS API base URL |
+   | `NEXT_PUBLIC_CSS_SITE_ID` | Site identifier (UUID) |
+   | `CSS_API_KEY` | Server-side API key |
+
+2. **Start the dev server:**
+
+   ```bash
+   pnpm dev
+   ```
+
+3. **Open:**
+   - Site — http://localhost:3000
+   - Dashboard — http://localhost:3000/p1
+   - Editor — http://localhost:3000/p1/your-page-path
+
+## Project structure
+
+```
+my-app/
+├── app/
+│   ├── page.tsx                  # Site root
+│   ├── [...puckPath]/            # Published pages
+│   └── p1/
+│       ├── page.tsx              # Dashboard
+│       ├── [[...p1]]/            # Editor & renderer
+│       ├── api/[...p1]/          # API routes
+│       └── auth/[...action]/     # Auth routes
+├── components/puck/              # Block definitions
+├── lib/                          # Datasources and utilities
+├── puck.config.tsx               # Puck configuration
+└── .env.example                  # Environment template
+```
+
+## Customization
+
+- **Add blocks** — create components in `components/puck/`, register them in `puck.config.tsx`
+- **Add datasources** — define in `lib/` and register for use in blocks
+- **Styling** — edit the Tailwind config or component styles
+
+Your scaffolded project also includes an optional `scripts/sync-puck-registry.ts` for syncing
+the component registry from CI, with a sample workflow in `ci-examples/`. It is inert until you
+wire it up; see the comments in those files for setup.
+
+## Troubleshooting
+
+**Module resolution errors.** Next.js needs the P1 packages transpiled. Verify
+`next.config.mjs` includes:
+
+```js
+transpilePackages: [
+  "@pantheon-systems/css-client",
+  "@pantheon-systems/puck-css",
+  "@pantheon-systems/p1-next-sdk",
+],
+```
+
+## Resources
+
+- [Pantheon documentation](https://docs.pantheon.io)
+- [Puck editor docs](https://puckeditor.com)
+- [Next.js docs](https://nextjs.org/docs)
+
+## License
+
+MIT

package/lib/cli.js

@@ -106,7 +106,7 @@ export async function runCLI() {
     if (error.code !== 'EEXIST') {
       try {
         fs.rmSync(targetDir, { recursive: true, force: true });
-      } catch (cleanupError) {
+      } catch {
         // Ignore cleanup errors
       }
     }

package/lib/messages.js

@@ -6,7 +6,7 @@ export function showWelcome() {
   console.log(pc.bold(pc.cyan('└─────────────────────────────────────────┘\n')));
 }
 
-export function showSuccess(projectName, projectPath, packageManager) {
+export function showSuccess(projectName, _projectPath, packageManager) {
   console.log(pc.green('\n✔ Project created successfully!\n'));
   console.log(`${pc.bold('Next steps:')}\n`);
   console.log(`  ${pc.cyan('cd')} ${projectName}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/create-p1-starter-kit",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Scaffold a new P1 starter project",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pantheon-systems/puck-css-integration.git",
+    "url": "git+https://github.com/pantheon-systems/p1-platform.git",
     "directory": "packages/create-p1-starter-kit"
   },
   "keywords": [
@@ -30,20 +30,29 @@
     "template"
   ],
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=24.0.0"
   },
   "devDependencies": {
+    "@vitejs/plugin-react": "^6.0.5",
+    "eslint": "^9.27.0",
+    "isomorphic-dompurify": "^3.18.0",
+    "react": "^19.2.5",
     "vitest": "^4.1.5",
-    "@pantheon-systems/css-client": "0.7.0",
-    "@pantheon-systems/puck-css": "0.7.0"
+    "@pantheon-systems/css-client": "0.10.0",
+    "@pantheon-systems/eslint-config": "0.1.0",
+    "@pantheon-systems/puck-css": "0.10.0"
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
     "picocolors": "^1.1.1"
   },
   "license": "MIT",
+  "homepage": "https://github.com/pantheon-systems/p1-platform/tree/main/packages/create-p1-starter-kit",
   "scripts": {
     "build": "node scripts/build-template.js",
+    "clean": "rm -rf template node_modules/.vite",
+    "lint": "eslint index.js lib scripts",
+    "lint:fix": "eslint index.js lib scripts --fix",
     "test": "vitest run"
   }
 }

package/template/.env.example

@@ -1,13 +1,28 @@
-PCC_SITE_ID=your-site-id
-PCC_TOKEN=your-token
-
 # --- P1 backend ---
-# NEXT_PUBLIC_CSS_BASE_URL defaults to https://ccr.p1.pantheon for production.
-# Override for staging, local, or sandbox deployments:
-# NEXT_PUBLIC_CSS_BASE_URL=https://staging.example.com
 NEXT_PUBLIC_CSS_SITE_ID=site-123
 CSS_API_KEY=your-api-key
 
+# Public URL of THIS environment, used to build the post-login redirect.
+# Read at runtime (not a NEXT_PUBLIC_ build-time var), so redeploy after setting it.
+#
+# Set it per environment — each of dev/test/live/multidev needs its own value
+# matching its own public URL. A site-level value that every environment inherits
+# sends logins to the wrong origin, silently.
+#   terminus secret:site:set <site>.live P1_SITE_URL "https://www.yoursite.com" \
+#     --type=env --scope=web
+#
+# Can be left unset once this site's origins are registered in the P1 dashboard:
+# the browser then states its origin and the backend verifies it against that
+# list, which one wildcard entry covers for every environment. Unset and
+# unregistered falls back to the request origin, which is an internal hostname on
+# Pantheon — that is the cause of post-login redirects to localhost.
+# P1_SITE_URL=https://www.yoursite.com
+
+# --- P1 backend URL (optional) ---
+# P1 backend defaults to https://ccr.p1.pantheon.io for production.
+# Override for staging, local, or sandbox deployments:
+# NEXT_PUBLIC_CSS_BASE_URL=https://staging.ccr.p1.pantheon.io
+
 # --- P1 Admin Dashboard (optional) ---
 # Override the default dashboard URL (https://content.pantheon.io)
 # NEXT_PUBLIC_P1_ADMIN_DASHBOARD_URL=https://staging.content.pantheon.io
@@ -25,3 +40,15 @@ CSS_API_KEY=your-api-key
 # public by design (safe to expose in the browser). When unset, the chatbot
 # stays hidden.
 # NEXT_PUBLIC_LD_CLIENT_ID=your-launchdarkly-client-side-id
+
+# --- Media library (on by default) ---
+# CDN image origin used to validate media URLs — NOT the Worker API URL.
+# Defaults to the production origin (https://media.p1.pantheon.io). Override
+# for staging, sandbox, or local dev.
+# NEXT_PUBLIC_MEDIA_BASE_URL=https://staging.media.p1.pantheon.io
+
+# --- Content Publisher (optional) ---
+# Add your secrets to connect to Content Publisher collections and
+# automatically pull documents from there into your P1 site.
+# PCC_SITE_ID=your-content-publisher-collection-id
+# PCC_TOKEN=your-content-publisher-access-token

package/template/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @pantheon-systems/p1-starter
 
+## 1.0.7
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies [3ed945e]
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @pantheon-systems/puck-css@0.8.0
+  - @pantheon-systems/p1-next-sdk@0.8.0
+  - @pantheon-systems/css-client@0.8.0
+
 ## 1.0.6
 
 ### Patch Changes

package/template/__tests__/ai-generate.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import type { DraftRequest, DraftRequestChannel } from "@pantheon-systems/p1-ai-chat";
+import { createGenerateWithAIHandler } from "../lib/chatbot-flag/ai-generate";
+
+/**
+ * A recording stand-in for the request channel. The real channel is unit-tested in
+ * `p1-ai-chat`; here we only assert what the handler publishes. Using a fake also
+ * keeps this test from importing the package's runtime (which pulls in CSS).
+ */
+function fakeChannel(): { channel: DraftRequestChannel; published: DraftRequest[] } {
+  const published: DraftRequest[] = [];
+  const channel: DraftRequestChannel = {
+    publish: (request) => {
+      published.push(request);
+    },
+    subscribe: () => () => {},
+    getLatest: () => published[published.length - 1] ?? null,
+    clearLatest: () => {},
+  };
+  return { channel, published };
+}
+
+describe("createGenerateWithAIHandler", () => {
+  it("returns undefined when the chatbot is disabled (leaves the modal tile a placeholder)", () => {
+    const { channel } = fakeChannel();
+    expect(createGenerateWithAIHandler(channel, false)).toBeUndefined();
+  });
+
+  it("asks for the page to be created, with the title and path the dialog collected", () => {
+    const { channel, published } = fakeChannel();
+
+    const handler = createGenerateWithAIHandler(channel, true);
+    // Narrowed with a throw rather than a `!`: the return type is optional because the
+    // handler is undefined when the chatbot is disabled, and the lint rule forbids
+    // asserting that away. This keeps the "must be defined when enabled" claim asserted.
+    if (!handler) throw new Error("handler must be defined when the chatbot is enabled");
+    handler("a launch page", { path: "launch", title: "Launch" });
+
+    // `create-page`, not `fill-page`: nothing exists yet, because the template the page starts
+    // from is settled in the chat first and can only be applied as the page is created.
+    expect(published).toEqual([
+      { kind: "create-page", brief: "a launch page", page: { path: "launch", title: "Launch" } },
+    ]);
+  });
+
+  it("keeps the nested path the dialog built from a template's route", () => {
+    const { channel, published } = fakeChannel();
+    const handler = createGenerateWithAIHandler(channel, true);
+    if (!handler) throw new Error("handler must be defined when the chatbot is enabled");
+
+    handler("draft", { path: "resources/guide", title: "Guide" });
+
+    expect(published[0]).toEqual({
+      kind: "create-page",
+      brief: "draft",
+      page: { path: "resources/guide", title: "Guide" },
+    });
+  });
+
+  // The dialog's title field can be left empty; the agent draws one from the brief instead.
+  it("sends an empty title rather than omitting it", () => {
+    const { channel, published } = fakeChannel();
+    const handler = createGenerateWithAIHandler(channel, true);
+    if (!handler) throw new Error("handler must be defined when the chatbot is enabled");
+
+    handler("draft", { path: "launch" });
+
+    expect(published[0]).toEqual({
+      kind: "create-page",
+      brief: "draft",
+      page: { path: "launch", title: "" },
+    });
+  });
+});

package/template/__tests__/auth-route.test.ts

@@ -1,7 +1,7 @@
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const appDir = resolve(__dirname, "..");

package/template/__tests__/chatbot-flag-wiring.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const appDir = resolve(__dirname, "..");
 
 describe("editor-client gates the chatbot behind the p1-chatbot flag", () => {
   const content = readFileSync(
-    resolve(appDir, "app/p1/[[...p1]]/editor-client.tsx"),
+    resolve(appDir, "app/p1/(editor)/[[...p1]]/editor-client.tsx"),
     "utf-8",
   );
 
@@ -29,6 +29,26 @@ describe("editor-client gates the chatbot behind the p1-chatbot flag", () => {
   });
 });
 
+describe("editor-client wires Generate with AI to the chat sidebar", () => {
+  const content = readFileSync(
+    resolve(appDir, "app/p1/(editor)/[[...p1]]/editor-client.tsx"),
+    "utf-8",
+  );
+
+  it("uses the shared (singleton) agent request channel", () => {
+    expect(content).toContain("getDraftRequestChannel");
+  });
+
+  it("passes the request channel to the chat plugin", () => {
+    expect(content).toMatch(/createAIChatPlugin\(\{[^}]*draftRequests/);
+  });
+
+  it("wires onGenerateWithAI to publish onto the channel via the handler", () => {
+    expect(content).toContain("onGenerateWithAI");
+    expect(content).toContain("createGenerateWithAIHandler");
+  });
+});
+
 describe("chatbot flag provider is a client-side LaunchDarkly gate", () => {
   const content = readFileSync(
     resolve(appDir, "components/ChatbotFlagProvider.tsx"),

package/template/__tests__/editor-integration.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, it } from "vitest";
 import { readFileSync } from "fs";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const appDir = resolve(__dirname, "..");
 
 describe("editor-client uses P1 plugins", () => {
   const content = readFileSync(
-    resolve(appDir, "app/p1/[[...p1]]/editor-client.tsx"),
+    resolve(appDir, "app/p1/(editor)/[[...p1]]/editor-client.tsx"),
     "utf-8",
   );
 

package/template/__tests__/editor-route-group.test.ts

@@ -0,0 +1,44 @@
+/**
+ * The persistent editor is scoped to the `(editor)` route group so it wraps
+ * only the catch-all editor page — not sibling routes like /p1/merge (or a
+ * future /p1/settings). This structure replaces the old NON_EDITOR_ROUTES
+ * opt-out list: siblings stay editor-free by construction, not by enumeration.
+ */
+import { existsSync, readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const appDir = resolve(__dirname, "..");
+const p1 = resolve(appDir, "app/p1");
+
+describe("editor is scoped to the (editor) route group", () => {
+  it("mounts the persistent editor layout inside the group", () => {
+    const layout = resolve(p1, "(editor)/layout.tsx");
+    expect(existsSync(layout)).toBe(true);
+    expect(readFileSync(layout, "utf-8")).toContain("pages.Layout");
+  });
+
+  it("keeps the catch-all editor page inside the group", () => {
+    expect(existsSync(resolve(p1, "(editor)/[[...p1]]/page.tsx"))).toBe(true);
+    expect(existsSync(resolve(p1, "(editor)/[[...p1]]/editor-client.tsx"))).toBe(true);
+  });
+
+  it("does not mount a layout at /p1 that would wrap every sibling", () => {
+    expect(existsSync(resolve(p1, "layout.tsx"))).toBe(false);
+  });
+
+  it("keeps /p1/merge a sibling outside the group so the editor never wraps it", () => {
+    expect(existsSync(resolve(p1, "merge/page.tsx"))).toBe(true);
+    expect(existsSync(resolve(p1, "(editor)/merge/page.tsx"))).toBe(false);
+  });
+
+  it("no longer guards routes with a NON_EDITOR_ROUTES opt-out list", () => {
+    const editorClient = readFileSync(
+      resolve(p1, "(editor)/[[...p1]]/editor-client.tsx"),
+      "utf-8",
+    );
+    expect(editorClient).not.toContain("NON_EDITOR_ROUTES");
+  });
+});

package/template/__tests__/page-seo-meta-templates.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("../lib/remote-datasource-fetchers", () => ({
+  REMOTE_DATASOURCE_FETCHERS: {},
+}));
+
+vi.mock("@pantheon-systems/puck-css/server", () => ({
+  listRouteTemplateKeysFromDatabase: vi.fn().mockResolvedValue([]),
+  extractReferencedDatasourceIds: vi.fn().mockReturnValue([]),
+  loadRemoteDatasourceContext: vi.fn().mockResolvedValue({}),
+  resolveStringTemplates: vi.fn(async (input: string) =>
+    input
+      .replace(/\{\{\s*name\s*\}\}/g, "World")
+      .replace(/\{\{\s*slug\s*\}\}/g, "widgets"),
+  ),
+}));
+
+import * as puckServer from "@pantheon-systems/puck-css/server";
+import { resolvePageMetadata } from "../lib/page-seo";
+
+/**
+ * `{{ }}` interpolation on the metadata fields.
+ *
+ * Loading the datasource context is a network round trip, so it happens only
+ * when something on the page actually carries a template — and once, however
+ * many fields do.
+ *
+ * The two fixed-vocabulary fields are deliberately excluded: their values are
+ * validated against a union, so a template could only ever produce a value the
+ * renderer rejects.
+ */
+
+type PageData = Parameters<typeof resolvePageMetadata>[0]["pageData"];
+
+function pageWithRootProps(props: Record<string, unknown>): PageData {
+  return { root: { props }, content: [] } as unknown as PageData;
+}
+
+const resolve = (props: Record<string, unknown>) =>
+  resolvePageMetadata({
+    pageData: pageWithRootProps(props),
+    path: "/q3",
+    searchParams: {},
+  });
+
+const og = (m: Awaited<ReturnType<typeof resolvePageMetadata>>) =>
+  (m.openGraph ?? {}) as Record<string, unknown>;
+const tw = (m: Awaited<ReturnType<typeof resolvePageMetadata>>) =>
+  (m.twitter ?? {}) as Record<string, unknown>;
+
+describe("resolvePageMetadata — {{ }} in _meta", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("resolves templates in the free-text metadata fields", async () => {
+    const meta = await resolve({
+      title: "Q3",
+      _meta: {
+        ogTitle: "Hello {{ name }}",
+        ogDescription: "All about {{ name }}",
+        twitterTitle: "{{ name }} on X",
+        ogLocale: "{{ name }}",
+      },
+    });
+
+    expect(og(meta).title).toBe("Hello World");
+    expect(og(meta).description).toBe("All about World");
+    expect(tw(meta).title).toBe("World on X");
+    expect(og(meta).locale).toBe("World");
+  });
+
+  it("resolves templates in the image URLs", async () => {
+    const meta = await resolve({
+      title: "Q3",
+      _meta: {
+        ogImage: "https://cdn.example/{{ slug }}.png",
+        twitterImage: "https://cdn.example/{{ slug }}-x.png",
+      },
+    });
+
+    expect(og(meta).images).toBe("https://cdn.example/widgets.png");
+    expect(tw(meta).images).toBe("https://cdn.example/widgets-x.png");
+  });
+
+  it("leaves the fixed-vocabulary fields alone", async () => {
+    const meta = await resolve({
+      title: "Q3",
+      _meta: { ogType: "{{ name }}", twitterCard: "{{ name }}", ogTitle: "Set" },
+    });
+
+    // Unresolved and unrecognised, so the union check falls back.
+    expect(og(meta).type).toBe("website");
+    expect(tw(meta).card).toBe("summary");
+    for (const call of vi.mocked(puckServer.resolveStringTemplates).mock.calls) {
+      expect(call[0]).not.toBe("{{ name }}");
+    }
+  });
+
+  it("loads the datasource context once, however many fields template", async () => {
+    await resolve({
+      title: "Hello {{ name }}",
+      description: "About {{ name }}",
+      _meta: { ogTitle: "{{ name }}", twitterTitle: "{{ name }}" },
+    });
+
+    expect(puckServer.loadRemoteDatasourceContext).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not touch the network when nothing carries a template", async () => {
+    const meta = await resolve({
+      title: "Q3 Launch Recap",
+      _meta: { ogTitle: "The launch, in numbers" },
+    });
+
+    expect(puckServer.loadRemoteDatasourceContext).not.toHaveBeenCalled();
+    expect(puckServer.resolveStringTemplates).not.toHaveBeenCalled();
+    expect(og(meta).title).toBe("The launch, in numbers");
+  });
+
+  it("resolves only the fields that carry a template", async () => {
+    await resolve({
+      title: "Q3",
+      _meta: { ogTitle: "Hello {{ name }}", ogDescription: "Static" },
+    });
+
+    expect(puckServer.resolveStringTemplates).toHaveBeenCalledTimes(1);
+    expect(puckServer.resolveStringTemplates).toHaveBeenCalledWith("Hello {{ name }}", {});
+  });
+
+  it("resolves a metadata field when the title carries no template", async () => {
+    // The context load used to be gated on title/description alone, so a
+    // template that appeared only in _meta would never have been resolved.
+    const meta = await resolve({ title: "Q3", _meta: { ogTitle: "Hello {{ name }}" } });
+
+    expect(og(meta).title).toBe("Hello World");
+  });
+
+  it("still derives an unset field from the resolved title", async () => {
+    const meta = await resolve({ title: "Hello {{ name }}", _meta: { ogTitle: "" } });
+
+    expect(og(meta).title).toBe("Hello World");
+    expect(tw(meta).title).toBe("Hello World");
+  });
+});