@pantheon-systems/create-p1-starter-kit 0.1.0

package/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCLI } from './lib/cli.js';
+
+runCLI();

package/lib/cli.js

@@ -0,0 +1,149 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import * as clack from '@clack/prompts';
+import pc from 'picocolors';
+import { copyTemplate } from './copy-template.js';
+import { detectPackageManager, isPackageManagerAvailable, installDependencies } from './install-deps.js';
+import { showWelcome, showSuccess, showInstallHelp, showError } from './messages.js';
+
+export async function runCLI() {
+  showWelcome();
+
+  const args = process.argv.slice(2);
+  const targetDirArg = args[0];
+
+  clack.intro(pc.bgCyan(pc.black(' P1 Starter Kit Setup ')));
+
+  // Get project name
+  const projectName = await clack.text({
+    message: 'What is your project named?',
+    placeholder: 'my-p1-app',
+    initialValue: targetDirArg || 'my-p1-app',
+    validate: (value) => {
+      if (!value) return 'Please enter a project name';
+      if (!/^[a-z0-9-_]+$/.test(value)) {
+        return 'Project name must be lowercase and can only contain letters, numbers, hyphens, and underscores';
+      }
+      return undefined;
+    },
+  });
+
+  if (clack.isCancel(projectName)) {
+    clack.cancel('Operation cancelled');
+    process.exit(0);
+  }
+
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  // Check if directory already exists before prompting further
+  if (fs.existsSync(targetDir)) {
+    showError(`Directory "${projectName}" already exists. Please choose a different name or remove the existing directory.`);
+    process.exit(1);
+  }
+
+  // Detect package manager
+  const detectedPM = detectPackageManager();
+  const packageManager = await clack.select({
+    message: 'Which package manager do you want to use?',
+    options: [
+      { value: 'pnpm', label: 'pnpm', hint: detectedPM === 'pnpm' ? 'detected' : '' },
+      { value: 'npm', label: 'npm', hint: detectedPM === 'npm' ? 'detected' : '' },
+      { value: 'yarn', label: 'yarn', hint: detectedPM === 'yarn' ? 'detected' : '' },
+    ],
+    initialValue: detectedPM,
+  });
+
+  if (clack.isCancel(packageManager)) {
+    clack.cancel('Operation cancelled');
+    process.exit(0);
+  }
+
+  // Check if package manager is available
+  if (!isPackageManagerAvailable(packageManager)) {
+    showError(`${packageManager} is not installed. Please install it first or choose a different package manager.`);
+    process.exit(1);
+  }
+
+  // Git init?
+  const shouldInitGit = await clack.confirm({
+    message: 'Initialize a git repository?',
+    initialValue: true,
+  });
+
+  if (clack.isCancel(shouldInitGit)) {
+    clack.cancel('Operation cancelled');
+    process.exit(0);
+  }
+
+  // Install deps?
+  const shouldInstall = await clack.confirm({
+    message: 'Install dependencies now?',
+    initialValue: true,
+  });
+
+  if (clack.isCancel(shouldInstall)) {
+    clack.cancel('Operation cancelled');
+    process.exit(0);
+  }
+
+  const s = clack.spinner();
+
+  // Create directory and copy template
+  s.start('Copying template files...');
+  try {
+    fs.mkdirSync(targetDir, { recursive: false });
+    copyTemplate(targetDir, projectName);
+    s.stop('Template files copied');
+  } catch (error) {
+    s.stop('Failed to copy template');
+    if (error.code === 'EEXIST') {
+      showError(`Directory "${projectName}" already exists. Please choose a different name or remove the existing directory.`);
+    } else {
+      showError(error.message);
+    }
+    // Clean up on failure (skip if dir already existed)
+    if (error.code !== 'EEXIST') {
+      try {
+        fs.rmSync(targetDir, { recursive: true, force: true });
+      } catch (cleanupError) {
+        // Ignore cleanup errors
+      }
+    }
+    process.exit(1);
+  }
+
+  // Git init
+  if (shouldInitGit) {
+    s.start('Initializing git repository...');
+    try {
+      execSync('git init', { cwd: targetDir, stdio: 'ignore' });
+      execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+      execSync('git commit -m "Initial commit from create-p1-starter-kit"', {
+        cwd: targetDir,
+        stdio: 'ignore',
+      });
+      s.stop('Git repository initialized');
+    } catch (error) {
+      s.stop('Failed to initialize git');
+      showError(`Git initialization failed: ${error.message}`);
+    }
+  }
+
+  // Install dependencies
+  if (shouldInstall) {
+    s.start('Installing dependencies (this may take a while)...');
+    const result = installDependencies(targetDir, packageManager);
+
+    if (result.success) {
+      s.stop('Dependencies installed');
+    } else {
+      s.stop('Dependency installation failed');
+      showInstallHelp(packageManager);
+      // Note: We don't clean up on install failure as user may want to retry manually
+    }
+  }
+
+  clack.outro(pc.green('All done!'));
+  showSuccess(projectName, targetDir, packageManager);
+}

package/lib/copy-template.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function getTemplatePath() {
+  return path.join(__dirname, '..', 'template');
+}
+
+export function copyTemplate(targetDir, projectName) {
+  const templatePath = getTemplatePath();
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template directory not found at ${templatePath}`);
+  }
+
+  copyRecursive(templatePath, targetDir);
+
+  // Update package.json with project name
+  const packageJsonPath = path.join(targetDir, 'package.json');
+  let packageJson;
+  try {
+    packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  } catch (error) {
+    throw new Error(`Failed to parse package.json: ${error.message}`);
+  }
+  packageJson.name = projectName;
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+}
+
+export function copyRecursive(src, dest, rootDest) {
+  // On first call, rootDest is the original destination directory
+  if (!rootDest) {
+    rootDest = path.resolve(dest);
+  }
+
+  // Validate that dest is within rootDest to prevent path traversal
+  const resolvedDest = path.resolve(dest);
+  if (!resolvedDest.startsWith(rootDest)) {
+    throw new Error(`Path traversal detected: ${dest} is outside target directory`);
+  }
+
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    // Validate each destPath to prevent traversal attacks via entry.name
+    const resolvedDestPath = path.resolve(destPath);
+    if (!resolvedDestPath.startsWith(rootDest)) {
+      throw new Error(`Path traversal detected: ${entry.name} attempts to escape target directory`);
+    }
+
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath, rootDest);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}

package/lib/install-deps.js

@@ -0,0 +1,68 @@
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const ALLOWED_PACKAGE_MANAGERS = new Set(['pnpm', 'npm', 'yarn']);
+
+function assertAllowedPM(pm) {
+  if (!ALLOWED_PACKAGE_MANAGERS.has(pm)) {
+    throw new Error(`Unknown package manager: ${pm}`);
+  }
+}
+
+export function detectPackageManager() {
+  // Check if pnpm-lock.yaml exists in parent directories
+  if (findFileInParents('pnpm-lock.yaml')) {
+    return 'pnpm';
+  }
+
+  // Check if yarn.lock exists
+  if (findFileInParents('yarn.lock')) {
+    return 'yarn';
+  }
+
+  // Default to npm
+  return 'npm';
+}
+
+function findFileInParents(filename) {
+  let currentDir = process.cwd();
+  const root = path.parse(currentDir).root;
+
+  while (currentDir !== root) {
+    if (fs.existsSync(path.join(currentDir, filename))) {
+      return true;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+
+  return false;
+}
+
+export function isPackageManagerAvailable(pm) {
+  assertAllowedPM(pm);
+  try {
+    execSync(`${pm} --version`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function installDependencies(targetDir, packageManager) {
+  assertAllowedPM(packageManager);
+  const installCmd = packageManager === 'yarn' ? 'yarn' : `${packageManager} install`;
+
+  try {
+    execSync(installCmd, {
+      cwd: targetDir,
+      stdio: 'inherit',
+    });
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}

package/lib/messages.js

@@ -0,0 +1,28 @@
+import pc from 'picocolors';
+
+export function showWelcome() {
+  console.log(pc.bold(pc.cyan('\n┌─────────────────────────────────────────┐')));
+  console.log(pc.bold(pc.cyan('│  Create P1 Starter Kit                  │')));
+  console.log(pc.bold(pc.cyan('└─────────────────────────────────────────┘\n')));
+}
+
+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}`);
+  console.log(`  ${pc.dim('# Copy .env.example to .env and fill in your credentials:')}`);
+  console.log(`  ${pc.cyan('cp')} .env.example .env`);
+  console.log(`  ${pc.dim('# Edit .env with your PCC_SITE_ID and PCC_TOKEN')}\n`);
+  console.log(`  ${pc.dim('# Start the dev server:')}`);
+  console.log(`  ${pc.cyan(`${packageManager} dev`)}\n`);
+  console.log(pc.bold('Happy building! 🚀\n'));
+}
+
+export function showInstallHelp(packageManager) {
+  console.log(pc.yellow('\n⚠️  Dependency installation failed.\n'));
+  console.log(`Try running ${pc.cyan(`${packageManager} install`)} manually.\n`);
+}
+
+export function showError(message) {
+  console.error(pc.red(`\n✖ Error: ${message}\n`));
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pantheon-systems/create-p1-starter-kit",
+  "version": "0.1.0",
+  "description": "Scaffold a new P1 starter project",
+  "type": "module",
+  "bin": {
+    "create-p1-starter-kit": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "template/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pantheon-systems/puck-css-integration.git",
+    "directory": "packages/create-p1-starter-kit"
+  },
+  "keywords": [
+    "p1",
+    "puck",
+    "cms",
+    "content-publisher",
+    "starter",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "picocolors": "^1.1.1"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "node scripts/build-template.js"
+  }
+}

package/template/.env.example

@@ -0,0 +1,10 @@
+PCC_SITE_ID=your-site-id
+PCC_TOKEN=your-token
+
+# --- P1 backend ---
+NEXT_PUBLIC_CSS_BASE_URL=https://css.example.com
+NEXT_PUBLIC_CSS_SITE_ID=site-123
+P1_CSS_API_KEY=your-api-key
+
+# Branch is auto-detected (defaults to main) unless specified:
+# NEXT_PUBLIC_CSS_BRANCH_ID=branch-456

package/template/README.md

@@ -0,0 +1,53 @@
+# Content Publisher Site Sample
+
+A sample Next.js site demonstrating the Content Publisher CMS — Pantheon's visual page-building and content management system. Content Publisher combines a Puck-based drag-and-drop editor with server-side datasource resolution, enabling authors to build dynamic, data-driven pages without writing code.
+
+## What's included
+
+- **Visual page editor** — Puck-powered drag-and-drop editing at `/p1/<path>` with built-in blocks for typography, media, layout, and actions
+- **Site structure management** — Dashboard at `/p1` for creating and organizing pages and templates
+- **Datasource bindings** — Connect page blocks to live data from Content Publisher articles, external APIs (SWAPI, Pokemon GraphQL), and URL route parameters
+- **Next.js App Router** — Server components, catch-all routing, and API route handlers via `@pantheon-systems/p1-client-sdk`
+
+## Getting started
+
+1. Copy the environment file and fill in your credentials:
+
+   ```
+   cp .env.example .env
+   ```
+
+   | Variable      | Description                |
+   | ------------- | -------------------------- |
+   | `PCC_SITE_ID` | Your Content Cloud site ID |
+   | `PCC_TOKEN`   | API token for your site    |
+
+2. Install dependencies and start the dev server:
+
+   ```
+   npm install
+   npm run dev
+   ```
+
+3. Open http://localhost:3000 to view the site, or http://localhost:3000/p1 for the page management dashboard.
+
+## Project structure
+
+```
+app/
+  page.tsx                    # Site root (renders via Puck)
+  [...puckPath]/              # Catch-all route for published pages
+  p1/
+    page.tsx                  # P1 dashboard — lists pages, links to editor
+    [...p1]/                  # Editor & renderer for any page path
+    api/[...p1]/route.ts      # API handler (GET/POST/DELETE) for page data
+components/puck/              # Block definitions (Heading, Paragraph, Image, etc.)
+lib/builtin-datasources.ts    # Datasource registry (SWAPI, Pokemon, articles, URL params)
+puck.config.tsx               # Puck editor configuration — block registry & categories
+```
+
+## Customization
+
+- **Add blocks** — Create a new component in `components/puck/`, then register it in `puck.config.tsx`
+- **Add datasources** — Define a new `DatasourceDefinition` in `lib/builtin-datasources.ts` to make external data available to block fields via `{{ datasource.field }}` expressions
+- **Change styling** — The project uses Tailwind CSS v4; edit `app/styles.css` or individual block components

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

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+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"),
+    "utf-8",
+  );
+
+  it("imports useP1Plugins", () => {
+    expect(content).toContain("useP1Plugins");
+  });
+
+  it("imports wrapConfigForEditorPreview", () => {
+    expect(content).toContain("wrapConfigForEditorPreview");
+  });
+
+  it("passes additionalPlugins to useP1Editor", () => {
+    expect(content).toContain("additionalPlugins");
+  });
+
+  it("wraps with P1QueryProvider for TanStack React Query", () => {
+    expect(content).toContain("P1QueryProvider");
+  });
+});
+
+describe("API handler passes fetcher config", () => {
+  const content = readFileSync(
+    resolve(appDir, "app/p1/api/[...p1]/route.ts"),
+    "utf-8",
+  );
+
+  it("imports REMOTE_DATASOURCE_FETCHERS", () => {
+    expect(content).toContain("REMOTE_DATASOURCE_FETCHERS");
+  });
+
+  it("imports REMOTE_DATASOURCE_REGISTRY", () => {
+    expect(content).toContain("REMOTE_DATASOURCE_REGISTRY");
+  });
+
+  it("passes builtinFetchers to createP1Handler", () => {
+    expect(content).toContain("builtinFetchers");
+  });
+
+  it("passes builtinDatasourceRegistry to createP1Handler", () => {
+    expect(content).toContain("builtinDatasourceRegistry");
+  });
+});