@pantheon-systems/p1-next-sdk 0.7.0 → 0.10.0

package/README.md

@@ -0,0 +1,87 @@
+# @pantheon-systems/p1-next-sdk
+
+Next.js SDK for the P1 editor. Mounts the editor, its API routes, auth, and published-page
+rendering into a Next.js App Router application with a handful of factories.
+
+> Part of Pantheon's **P1** platform. It is published publicly so P1 applications can install
+> it, but it talks to Pantheon-hosted services and is not a general-purpose Next.js library.
+> Pre-1.0: minor versions may carry breaking changes.
+
+## Install
+
+```bash
+npm install @pantheon-systems/p1-next-sdk
+```
+
+Peer dependencies:
+
+```bash
+npm install @puckeditor/core next react react-dom
+```
+
+The fastest way to get a working application is to scaffold one:
+
+```bash
+npm create @pantheon-systems/p1-starter-kit my-app
+```
+
+## Usage
+
+Mount the API routes in `app/p1/api/[...p1]/route.ts`:
+
+```ts
+import { createP1Handler } from "@pantheon-systems/p1-next-sdk/server";
+import config from "../../../../puck.config";
+
+const handler = createP1Handler({
+  config,
+  p1BaseUrl: process.env.NEXT_PUBLIC_CSS_BASE_URL,
+  p1ApiKey: process.env.CSS_API_KEY,
+  p1SiteId: process.env.NEXT_PUBLIC_CSS_SITE_ID,
+});
+
+export const { GET, POST } = handler;
+```
+
+And the editor and dashboard pages:
+
+```ts
+import { createP1Pages } from "@pantheon-systems/p1-next-sdk/server";
+import config from "../../../../puck.config";
+
+export const pages = createP1Pages({
+  config,
+  p1BaseUrl: process.env.NEXT_PUBLIC_CSS_BASE_URL,
+  p1ApiKey: process.env.CSS_API_KEY,
+  p1SiteId: process.env.NEXT_PUBLIC_CSS_SITE_ID,
+});
+```
+
+Client components render inside `P1NextRouterProvider`, which bridges P1 navigation to the
+Next.js router.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@pantheon-systems/p1-next-sdk` | `P1NextRouterProvider` and client-side helpers |
+| `.../server` | `createP1Handler`, `createP1AuthHandler`, `createP1Pages`, `createP1Middleware`, `createCssQueryFetchers` |
+
+Transpilation is required, since the P1 packages ship untranspiled ESM:
+
+```js
+// next.config.mjs
+transpilePackages: [
+  "@pantheon-systems/css-client",
+  "@pantheon-systems/puck-css",
+  "@pantheon-systems/p1-next-sdk",
+],
+```
+
+## CLI
+
+The package ships a `p1-migrate` binary for applying P1 migrations:
+
+```bash
+npx p1-migrate
+```

package/bin/lib/cli.js

@@ -0,0 +1,171 @@
+/**
+ * Codemod orchestration.
+ *
+ * `migrate()` is pure-ish and testable (takes a dir, returns a result, throws
+ * BailError on unrecognized input). `runCLI()` wraps it with argv parsing and
+ * process exit codes for the bin entrypoint.
+ *
+ * All transforms run before any write, so a bail leaves the tree untouched —
+ * the app is never left half-migrated.
+ */
+
+import { join, relative } from "node:path";
+import { detectApp, assertSuiteVersions, isRouteSpecial } from "./detect.js";
+import { assertCleanTree } from "./git.js";
+import * as fsops from "./fs-ops.js";
+import * as msg from "./messages.js";
+import {
+  BailError,
+  rewriteEditorClient,
+  splitPageFile,
+  buildLayoutFile,
+} from "./transform.js";
+
+const show = (dir, target) => relative(dir, target) || target;
+
+/**
+ * The codemod's only irreversible act is removing the old catch-all, so when it
+ * holds anything else the bail has to be worth reading: name every file, and
+ * separate the ones that just need moving from the ones whose destination is a
+ * real decision.
+ */
+function extraFilesMessage({ catchAll, extras, p1Dir }, dir) {
+  const special = extras.filter(isRouteSpecial);
+  const plain = extras.filter((entry) => !isRouteSpecial(entry));
+  const group = show(dir, join(p1Dir, "(editor)"));
+  const lines = [
+    `${show(dir, catchAll)} contains files this codemod does not know how to move:`,
+  ];
+  if (plain.length > 0) {
+    lines.push(
+      "",
+      ...plain.map((entry) => `  ${entry}`),
+      `Move these into ${join(group, "[[...p1]]")}/ and add one ../ to each parent-relative import.`,
+    );
+  }
+  if (special.length > 0) {
+    lines.push(
+      "",
+      ...special.map((entry) => `  ${entry}`),
+      "These wrap the route segment. The editor now renders from " +
+        `${join(group, "layout.tsx")}, one level up, so they likely belong beside it in ${group}/.`,
+    );
+  }
+  lines.push(
+    "",
+    "Move them, then re-run — the page split, import depth, and layout are still handled for you.",
+  );
+  return lines.join("\n");
+}
+
+function partialMessage({ catchAll, p1Dir }, dir) {
+  return (
+    `Both ${show(dir, join(p1Dir, "(editor)"))} and ${show(dir, catchAll)} exist, so an ` +
+    "earlier run was interrupted before it removed the old route. Check which files you " +
+    `want to keep, delete ${show(dir, catchAll)}, then re-run.`
+  );
+}
+
+export async function migrate(opts = {}) {
+  const dir = opts.dir ?? process.cwd();
+  const force = opts.force ?? false;
+  const dryRun = opts.dryRun ?? false;
+
+  const app = detectApp(dir);
+  if (app.status === "already-migrated") {
+    msg.alreadyMigrated();
+    return { changed: false };
+  }
+  if (app.status === "not-found") {
+    throw new BailError(
+      `Could not find app/p1/[[...p1]]/page.tsx under ${dir}. Run this from your project root.`,
+    );
+  }
+  if (app.status === "partial") {
+    throw new BailError(partialMessage(app, dir));
+  }
+  if (app.status === "extra-files") {
+    throw new BailError(extraFilesMessage(app, dir));
+  }
+
+  // Runs on --dry-run too: a plan the installed suite cannot render is not a
+  // plan worth previewing.
+  if (assertSuiteVersions(dir).status === "unverified") msg.versionsUnverified();
+
+  if (!force && !dryRun && assertCleanTree(dir).status === "no-repo") msg.noGitRepo();
+
+  const { catchAll, p1Dir } = app;
+  const editorGroup = join(p1Dir, "(editor)");
+  const newCatchAll = join(editorGroup, "[[...p1]]");
+
+  // Transform everything up front — any bail happens before we touch disk.
+  const newEditorClient = rewriteEditorClient(fsops.read(join(catchAll, "editor-client.tsx")));
+  const { p1Pages, page } = splitPageFile(fsops.read(join(catchAll, "page.tsx")));
+  const layout = buildLayoutFile();
+
+  const writes = [
+    [join(newCatchAll, "editor-client.tsx"), newEditorClient],
+    [join(newCatchAll, "p1-pages.tsx"), p1Pages],
+    [join(newCatchAll, "page.tsx"), page],
+    [join(editorGroup, "layout.tsx"), layout],
+  ];
+
+  for (const [path] of writes) fsops.assertWithin(dir, path);
+  fsops.assertWithin(dir, catchAll);
+
+  if (dryRun) {
+    msg.dryRunPlan(writes.map(([path]) => path), catchAll);
+    return { changed: false, dryRun: true };
+  }
+
+  fsops.ensureDir(newCatchAll);
+  for (const [path, content] of writes) fsops.write(path, content);
+  fsops.removeDir(catchAll);
+
+  msg.success(writes.map(([path]) => path), catchAll);
+  return { changed: true };
+}
+
+/**
+ * Strict on purpose: a silently-ignored `--dryrun` would run the real migration,
+ * and a `--dir` given with a space would migrate the current directory instead
+ * of the one the user named.
+ */
+export function parseArgs(argv) {
+  const opts = { dir: process.cwd(), force: false, dryRun: false, help: false };
+  for (const arg of argv) {
+    if (arg === "--force" || arg === "-f") opts.force = true;
+    else if (arg === "--dry-run") opts.dryRun = true;
+    else if (arg === "--help" || arg === "-h") opts.help = true;
+    else if (arg.startsWith("--dir=")) opts.dir = arg.slice("--dir=".length);
+    else {
+      throw new BailError(
+        `Unrecognized argument: ${arg}. Run with --help to see the supported options.`,
+      );
+    }
+  }
+  return opts;
+}
+
+export async function runCLI(argv = process.argv.slice(2)) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof BailError) msg.bail(err.message);
+    else msg.unexpected(err);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.help) {
+    msg.help();
+    return;
+  }
+  try {
+    await migrate(opts);
+  } catch (err) {
+    if (err instanceof BailError) msg.bail(err.message);
+    else msg.unexpected(err);
+    process.exitCode = 1;
+  }
+}

package/bin/lib/detect.js

@@ -0,0 +1,179 @@
+/**
+ * Classify a consumer project's editor route so the codemod knows whether to
+ * run, skip (already migrated), or bail (unrecognized), and verify the installed
+ * package suite is new enough for the shape this codemod writes.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { BailError } from "./transform.js";
+
+/** The only two files the codemod knows how to transform and carry across. */
+const MOVABLE = ["page.tsx", "editor-client.tsx"];
+
+/**
+ * App Router files whose behavior depends on where they sit. The editor moves
+ * up into `(editor)/layout.tsx`, so these stop wrapping it even when relocated
+ * faithfully — the destination is a judgment call the codemod should not make.
+ */
+const ROUTE_SPECIAL = new Set([
+  "layout",
+  "template",
+  "error",
+  "global-error",
+  "loading",
+  "not-found",
+  "default",
+  "route",
+]);
+
+export function isRouteSpecial(entry) {
+  return ROUTE_SPECIAL.has(entry.replace(/\.(tsx|ts|jsx|js)$/, ""));
+}
+
+function extraEntries(catchAll) {
+  return readdirSync(catchAll, { withFileTypes: true })
+    .filter((entry) => !MOVABLE.includes(entry.name))
+    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+    .sort();
+}
+
+export function detectApp(dir) {
+  const p1Dir = [join(dir, "app", "p1"), join(dir, "src", "app", "p1")].find((p) =>
+    existsSync(p),
+  );
+  if (!p1Dir) return { status: "not-found" };
+
+  const catchAll = join(p1Dir, "[[...p1]]");
+
+  if (existsSync(join(p1Dir, "(editor)"))) {
+    // Both trees present means a previous run died between the writes and the
+    // cleanup; calling that "already migrated" would strand the old route.
+    if (existsSync(catchAll)) return { status: "partial", p1Dir, catchAll };
+    return { status: "already-migrated", p1Dir };
+  }
+
+  if (
+    existsSync(join(catchAll, "page.tsx")) &&
+    existsSync(join(catchAll, "editor-client.tsx"))
+  ) {
+    const extras = extraEntries(catchAll);
+    if (extras.length > 0) return { status: "extra-files", p1Dir, catchAll, extras };
+    return { status: "legacy", p1Dir, catchAll };
+  }
+
+  return { status: "not-found" };
+}
+
+/**
+ * The release that moved the editor from `pages.Page` to `pages.Layout`. The
+ * codemod writes routes that call `Layout`, so anything older would be
+ * restructured to import an export that does not exist yet.
+ */
+export const MIN_SUITE_VERSION = "0.8.0";
+
+/**
+ * The lockstep-versioned packages a consumer app actually installs.
+ * `create-p1-starter-kit` is in the same `fixed` group but only ever scaffolds,
+ * so it is never present in the tree being migrated.
+ */
+const SUITE = [
+  "@pantheon-systems/p1-next-sdk",
+  "@pantheon-systems/puck-css",
+  "@pantheon-systems/css-client",
+];
+
+function readVersion(packageJsonPath) {
+  if (!existsSync(packageJsonPath)) return null;
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf-8")).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestPath(...segments) {
+  return join(...segments, "package.json");
+}
+
+/** Numeric release triple, ignoring any prerelease tag. Null when unparseable. */
+function parseVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(version));
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+function isOlderThan(version, floor) {
+  for (let i = 0; i < 3; i++) {
+    if (version[i] !== floor[i]) return version[i] < floor[i];
+  }
+  return false;
+}
+
+/**
+ * Verify the installed suite is consistent and new enough.
+ *
+ * Reads the installed tree rather than the consumer's declared ranges: a
+ * pre-1.0 caret is pinned to its minor, and an exact-pinned internal dep is
+ * satisfied by a nested private copy, so ranges cannot reveal either a stale
+ * install or a duplicated package. When nothing is resolvable we cannot verify
+ * anything — proceed rather than block, matching the clean-tree check.
+ *
+ * Only root-level packages are checked. Under pnpm's isolated node_modules just
+ * the app's direct dependencies are linked at the root, so a suite package
+ * missing from there is transitive, not broken — and a genuinely absent one
+ * fails loudly at build time anyway.
+ */
+export function assertSuiteVersions(dir) {
+  const modules = join(dir, "node_modules");
+  const resolved = SUITE.map((pkg) => ({
+    pkg,
+    version: readVersion(manifestPath(modules, pkg)),
+  })).filter((entry) => entry.version !== null);
+
+  if (resolved.length === 0) return { status: "unverified" };
+
+  const duplicates = [];
+  for (const { pkg: owner } of resolved) {
+    for (const { pkg: nested, version: root } of resolved) {
+      if (owner === nested) continue;
+      const version = readVersion(manifestPath(modules, owner, "node_modules", nested));
+      if (version !== null && version !== root) {
+        duplicates.push(`${nested}@${version} nested under ${owner}, and ${nested}@${root} at the root`);
+      }
+    }
+  }
+  if (duplicates.length > 0) {
+    throw new BailError(
+      `Your install has more than one copy of a P1 package: ${duplicates.join("; ")}. ` +
+        "Two copies mean two React contexts and the editor will misbehave at runtime. " +
+        "Upgrade every @pantheon-systems/* dependency in your package.json to the same " +
+        "version, reinstall, then re-run.",
+    );
+  }
+
+  const versions = [...new Set(resolved.map((entry) => entry.version))];
+  if (versions.length > 1) {
+    throw new BailError(
+      "Installed P1 packages are on different versions " +
+        `(${resolved.map((e) => `${e.pkg}@${e.version}`).join(", ")}). ` +
+        "They are released in lockstep and must match. Upgrade them together, then re-run.",
+    );
+  }
+
+  const [version] = versions;
+  const parsed = parseVersion(version);
+  if (parsed === null) return { status: "unverified" };
+
+  if (isOlderThan(parsed, parseVersion(MIN_SUITE_VERSION))) {
+    throw new BailError(
+      `Installed P1 packages are at ${version}, but the persistent (editor) layout ` +
+        `needs ${MIN_SUITE_VERSION} or newer. This codemod runs at the latest published ` +
+        "version because npx fetches it from the registry, so it can restructure routes " +
+        `your installed version cannot render. Note a "^${version}" range will not resolve ` +
+        `${MIN_SUITE_VERSION} — pre-1.0 carets are pinned to their minor — so upgrade ` +
+        "explicitly, reinstall, then re-run.",
+    );
+  }
+
+  return { status: "ok", version };
+}

package/bin/lib/fs-ops.js

@@ -0,0 +1,32 @@
+/**
+ * Filesystem helpers for the codemod, with a path-traversal guard so a write
+ * can never land outside the project being migrated.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { BailError } from "./transform.js";
+
+export function read(path) {
+  return readFileSync(path, "utf-8");
+}
+
+export function assertWithin(root, target) {
+  const r = resolve(root);
+  const t = resolve(target);
+  if (t !== r && !t.startsWith(r + sep)) {
+    throw new BailError(`Refusing to touch a path outside the project: ${target}`);
+  }
+}
+
+export function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+
+export function write(path, content) {
+  writeFileSync(path, content);
+}
+
+export function removeDir(path) {
+  rmSync(path, { recursive: true, force: true });
+}

package/bin/lib/git.js

@@ -0,0 +1,60 @@
+/**
+ * A file-moving codemod needs a clean tree so the user can review its diff and
+ * roll back. Not being a git repo is a state we can report and proceed from;
+ * git being present but unable to answer is not — that is an unverified tree
+ * wearing the same mask, and the caller would delete files on the strength of
+ * a check that never ran.
+ */
+
+import { execFileSync } from "node:child_process";
+import { BailError } from "./transform.js";
+
+function runGit(args, dir) {
+  return execFileSync("git", args, {
+    cwd: dir,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function describeFailure(err) {
+  const stderr = typeof err?.stderr === "string" ? err.stderr.trim() : "";
+  return stderr || (err instanceof Error ? err.message : String(err));
+}
+
+function unverified(err) {
+  return new BailError(
+    `git could not verify the working tree (${describeFailure(err)}). ` +
+      "Fix that, or re-run with --force to migrate without a clean-tree check.",
+  );
+}
+
+/**
+ * @returns `{ status: "clean" }` when the target subtree has no pending changes,
+ * or `{ status: "no-repo" }` when there is no repository to check. Throws
+ * BailError when the tree is dirty or git could not answer.
+ */
+export function assertCleanTree(dir, run = runGit) {
+  try {
+    run(["rev-parse", "--git-dir"], dir);
+  } catch (err) {
+    if (/not a git repository/i.test(describeFailure(err))) return { status: "no-repo" };
+    throw unverified(err);
+  }
+
+  let out;
+  try {
+    // Scoped to the target: `git status` is repo-wide by default, so an
+    // unrelated dirty file elsewhere in a monorepo would block a clean subtree.
+    out = run(["status", "--porcelain", "--", "."], dir);
+  } catch (err) {
+    throw unverified(err);
+  }
+
+  if (out.trim()) {
+    throw new BailError(
+      "Working tree is not clean. Commit or stash your changes first, or re-run with --force.",
+    );
+  }
+  return { status: "clean" };
+}

package/bin/lib/messages.js

@@ -0,0 +1,65 @@
+/**
+ * All console output for the codemod, kept in one place. Plain text — no color
+ * dependency — so the SDK's runtime deps stay unchanged.
+ */
+
+import { MIN_SUITE_VERSION } from "./detect.js";
+
+const TAG = "[p1-migrate]";
+
+export function help() {
+  console.log(
+    [
+      "p1-migrate — migrate a P1 app to the persistent (editor) layout",
+      "",
+      "Usage: npx @pantheon-systems/p1-next-sdk p1-migrate [options]",
+      "",
+      "Options:",
+      "  --dir=<path>   Project directory to migrate (default: current directory)",
+      "  --dry-run      Show what would change without writing anything",
+      "  --force, -f    Skip the clean-git-tree check",
+      "  --help, -h     Show this help",
+    ].join("\n"),
+  );
+}
+
+export function alreadyMigrated() {
+  console.log(`${TAG} Already on the (editor) layout — nothing to do.`);
+}
+
+export function noGitRepo() {
+  console.log(
+    `${TAG} Not a git repository — skipping the clean-tree check. This rewrites and ` +
+      "removes files with no way to roll them back.",
+  );
+}
+
+export function versionsUnverified() {
+  console.log(
+    `${TAG} Could not read installed @pantheon-systems/* versions — skipping the version check.`,
+  );
+  console.log(
+    `${TAG} Make sure your dependencies are installed and on ${MIN_SUITE_VERSION} or newer.`,
+  );
+}
+
+export function dryRunPlan(writePaths, oldDir) {
+  console.log(`${TAG} Dry run — no files written. Planned changes:`);
+  for (const p of writePaths) console.log(`  write   ${p}`);
+  console.log(`  remove  ${oldDir}`);
+}
+
+export function success(writePaths, oldDir) {
+  console.log(`${TAG} Migrated to the persistent (editor) layout:`);
+  for (const p of writePaths) console.log(`  wrote   ${p}`);
+  console.log(`  removed ${oldDir}`);
+  console.log(`${TAG} Review the diff and commit when it looks right.`);
+}
+
+export function bail(message) {
+  console.error(`${TAG} Could not migrate automatically: ${message}`);
+}
+
+export function unexpected(err) {
+  console.error(`${TAG} Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+}