@puckeditor/cli 0.24.0-canary.301a0304 → 0.24.0-canary.55558da4

package/README.md

@@ -22,6 +22,7 @@ npx @puckeditor/cli add cloud    # connect Puck Cloud
 npx @puckeditor/cli add ai       # add the Puck AI plugin
 npx @puckeditor/cli status       # show what's set up
 npx @puckeditor/cli doctor       # diagnose problems
+npx @puckeditor/cli frameworks   # show supported frameworks and versions
 npx @puckeditor/cli docs         # read the docs for this version
 ```
 

package/dist/bin.mjs

@@ -190,12 +190,13 @@ var resolveInstalledVersion = (vfs, fromDir, name) => {
     dir = parent;
   }
 };
-var majorOf = (versionOrRange) => {
+var versionOf = (versionOrRange) => {
   if (!versionOrRange) return null;
   const cleaned = versionOrRange.replace(/^(workspace:|npm:[^@]+@)/, "");
-  const match = /(\d+)(?:\.\d+)?/.exec(cleaned);
-  return match ? Number(match[1]) : null;
+  const match = /(\d+)(?:\.(\d+))?/.exec(cleaned);
+  return match ? [Number(match[1]), Number(match[2] ?? 0)] : null;
 };
+var majorOf = (versionOrRange) => versionOf(versionOrRange)?.[0] ?? null;
 
 // src/detect/server.ts
 import path2 from "path";
@@ -283,7 +284,42 @@ var FRAMEWORK_LABELS = {
   hono: "Hono",
   express: "Express"
 };
+var MIN_VERSIONS = {
+  next: "15",
+  "react-router": "7",
+  // Server route handlers on createFileRoute arrived in the Start RC
+  "tanstack-start": "1.132",
+  // vinext 1.0 moved to Vite 8, which the recipe uses
+  vinext: "1",
+  // @hono/vite-dev-server is built and tested against Vite 6
+  vite: "6",
+  // @astrojs/node 11, which `astro add node` installs, needs Astro 7
+  astro: "7",
+  // @hono/node-server 2 needs Hono 4
+  hono: "4",
+  // express.json() arrived in 4.16
+  express: "4.16"
+};
 var SUPPORTED_FRAMEWORKS = "Next.js (App Router), React Router 7 framework mode, TanStack Start, vinext, Astro and Vite React apps, or a Hono or Express server";
+var unsupportedVersion = (id, version, range) => {
+  const found = versionOf(version) ?? versionOf(range);
+  const [major, minor] = versionOf(MIN_VERSIONS[id]);
+  if (!found || found[0] > major || found[0] === major && found[1] >= minor)
+    return null;
+  const label2 = FRAMEWORK_LABELS[id];
+  return {
+    status: "unsupported",
+    error: {
+      code: "PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION",
+      message: `${label2} ${version ?? range} is not supported. Upgrade to ${label2} ${MIN_VERSIONS[id]} or later, or integrate Puck manually.`,
+      details: {
+        docs: MANUAL_INTEGRATION_DOCS_URL,
+        version: version ?? range,
+        minVersion: MIN_VERSIONS[id]
+      }
+    }
+  };
+};
 var firstExisting = (vfs, root, candidates) => candidates.find((c) => vfs.exists(path3.join(root, c))) ?? null;
 var CONFIG_EXTENSIONS = ["ts", "mts", "js", "mjs", "cts", "cjs"];
 var findViteConfig = (vfs, root) => firstExisting(
@@ -338,19 +374,8 @@ var detectNext = (vfs, root, range) => {
   const major = majorOf(version) ?? majorOf(range) ?? 16;
   const layout = detectAppRouter(vfs, root, "Next.js");
   if ("status" in layout) return layout;
-  if (major < 15) {
-    return {
-      status: "unsupported",
-      error: {
-        code: "PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION",
-        message: `Next.js ${version ?? range} is not supported. Upgrade to Next.js 15 or later, or integrate Puck manually.`,
-        details: {
-          docs: MANUAL_INTEGRATION_DOCS_URL,
-          version: version ?? range
-        }
-      }
-    };
-  }
+  const tooOld = unsupportedVersion("next", version, range);
+  if (tooOld) return tooOld;
   return {
     status: "detected",
     info: {
@@ -364,6 +389,8 @@ var detectNext = (vfs, root, range) => {
 };
 var detectVinext = (vfs, root, range) => {
   const version = resolveInstalledVersion(vfs, root, "vinext");
+  const tooOld = unsupportedVersion("vinext", version, range);
+  if (tooOld) return tooOld;
   const layout = detectAppRouter(vfs, root, "vinext");
   if ("status" in layout) return layout;
   const base = layout.baseDir ? `${layout.baseDir}/` : "";
@@ -385,16 +412,8 @@ var detectVinext = (vfs, root, range) => {
 var detectReactRouter = (vfs, root, range) => {
   const version = resolveInstalledVersion(vfs, root, "@react-router/dev") ?? resolveInstalledVersion(vfs, root, "react-router");
   const major = majorOf(version) ?? majorOf(range);
-  if (major !== null && major < 7) {
-    return {
-      status: "unsupported",
-      error: {
-        code: "PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION",
-        message: `React Router ${version ?? range} is not supported. Upgrade to React Router 7 framework mode.`,
-        details: { docs: MANUAL_INTEGRATION_DOCS_URL }
-      }
-    };
-  }
+  const tooOld = unsupportedVersion("react-router", version, range);
+  if (tooOld) return tooOld;
   const configFile = firstExisting(
     vfs,
     root,
@@ -456,6 +475,8 @@ var detectReactRouter = (vfs, root, range) => {
 };
 var detectTanStackStart = (vfs, root, range) => {
   const version = resolveInstalledVersion(vfs, root, "@tanstack/react-start");
+  const tooOld = unsupportedVersion("tanstack-start", version, range);
+  if (tooOld) return tooOld;
   const viteConfig = findViteConfig(vfs, root);
   const code = viteConfig ? vfs.readText(path3.join(root, viteConfig)) ?? "" : "";
   const dirs = { srcDirectory: "src", routesDirectory: "routes" };
@@ -503,6 +524,8 @@ var detectVite = (vfs, root, range, deps) => {
     (f) => Boolean(f) && vfs.exists(path3.join(root, f))
   ) ?? null;
   const version = resolveInstalledVersion(vfs, root, "vite");
+  const tooOld = unsupportedVersion("vite", version, range);
+  if (tooOld) return tooOld;
   const viteConfig = findViteConfig(vfs, root);
   const code = viteConfig ? vfs.readText(path3.join(root, viteConfig)) ?? "" : "";
   return {
@@ -527,6 +550,8 @@ var ASTRO_ADAPTERS = [
 ];
 var detectAstro = (vfs, root, range, deps) => {
   const version = resolveInstalledVersion(vfs, root, "astro");
+  const tooOld = unsupportedVersion("astro", version, range);
+  if (tooOld) return tooOld;
   const config = firstExisting(
     vfs,
     root,
@@ -550,6 +575,8 @@ var detectAstro = (vfs, root, range, deps) => {
 };
 var detectServer = (id) => (vfs, root, range, deps) => {
   const version = resolveInstalledVersion(vfs, root, id);
+  const tooOld = unsupportedVersion(id, version, range);
+  if (tooOld) return tooOld;
   return {
     status: "detected",
     info: {
@@ -775,6 +802,7 @@ var COMMAND_OPTIONS = {
   status: ["json", "help", "version", "cwd", "workspace", "config"],
   doctor: ["json", "help", "version", "cwd", "workspace", "config", "offline"],
   docs: ["json", "help", "version"],
+  frameworks: ["json", "help", "version"],
   help: GLOBAL
 };
 var COMMANDS = [
@@ -783,6 +811,7 @@ var COMMANDS = [
   "status",
   "doctor",
   "docs",
+  "frameworks",
   "help"
 ];
 var FRAMEWORKS = FRAMEWORK_IDS;
@@ -1132,6 +1161,10 @@ var COMMANDS2 = [
     name: "doctor",
     description: "Diagnose problems and suggest fixes (read-only)"
   },
+  {
+    name: "frameworks",
+    description: "Show the supported frameworks and versions"
+  },
   {
     name: "docs <command>",
     description: "Read the docs for this version: ls, cat <page>, find <query>, grep <text>"
@@ -4671,6 +4704,26 @@ var statusTable = (result) => {
   const width = Math.max(...rows.map(([k]) => k.length), 0) + 2;
   return rows.map(([k, v]) => `${k.padEnd(width)}${v}`);
 };
+var frameworksTable = (frameworks) => {
+  const rows = [
+    ["Framework", "ID", "Versions", "Editor", "Puck Cloud & AI", "Notes"],
+    ...frameworks.map((f) => [
+      f.name,
+      f.id,
+      `${f.minVersion}+`,
+      f.kind === "server" ? "API only" : "\u2713",
+      f.needsServer ? "needs a server*" : "\u2713",
+      f.notes
+    ])
+  ];
+  const widths = rows[0].map(
+    (_, i) => Math.max(...rows.map((row) => row[i].length))
+  );
+  return rows.map((row, r) => {
+    const line = row.map((cell, i) => i === row.length - 1 ? cell : cell.padEnd(widths[i])).join("  ").trimEnd();
+    return r === 0 ? pc.bold(line) : line;
+  });
+};
 var presentHuman = (out, result, secrets) => {
   const lines = [];
   const write = () => out.write(secrets.scrub(lines.join("\n")) + "\n");
@@ -4704,6 +4757,18 @@ var presentHuman = (out, result, secrets) => {
         lines.push(`  ${" ".repeat(24)} ${pc.cyan(f.fix)}`);
     }
     lines.push("", result.message);
+  } else if (result.command === "frameworks" && result.status !== "error") {
+    lines.push(...frameworksTable(result.frameworks ?? []));
+    const needServer = (result.frameworks ?? []).filter((f) => f.needsServer);
+    if (needServer.length) {
+      lines.push(
+        "",
+        `* ${needServer.map((f) => f.name).join(
+          " and "
+        )} need a server for Puck Cloud and Puck AI, unless they already have one. Choose one with --backend.`
+      );
+    }
+    lines.push("", pc.dim(result.message));
   } else if (result.command === "docs" && result.status !== "error") {
     const { page, pages, matches } = result.docs ?? {};
     if (page) lines.push(page.content.trimEnd());
@@ -4765,7 +4830,7 @@ var presentHuman = (out, result, secrets) => {
       ...result.warnings.map((w) => `${pc.yellow("!")} ${w.message}`)
     );
   }
-  if (result.status !== "error" && result.command !== "doctor" && result.command !== "docs" && result.nextSteps.length) {
+  if (result.status !== "error" && result.command !== "doctor" && result.command !== "docs" && result.command !== "frameworks" && result.nextSteps.length) {
     lines.push(
       "",
       pc.bold("Next:"),
@@ -7090,6 +7155,41 @@ var runDocs = async (rc, positionals) => {
   return result;
 };
 
+// src/commands/frameworks.ts
+var NOTES = {
+  next: "App Router, in app/ or src/app/",
+  "react-router": "Framework mode",
+  "tanstack-start": "",
+  vinext: "App Router, in app/ or src/app/",
+  vite: "React apps using @vitejs/plugin-react",
+  astro: "Adds React with astro add react if needed",
+  hono: "Serves the APIs for an editor in another app",
+  express: "Serves the APIs for an editor in another app"
+};
+var frameworkSupport = () => FRAMEWORK_IDS.map((id) => {
+  const adapter = ADAPTERS[id];
+  return {
+    id,
+    name: FRAMEWORK_LABELS[id],
+    minVersion: MIN_VERSIONS[id],
+    kind: adapter.kind ?? "app",
+    needsServer: Boolean(adapter.backend),
+    notes: NOTES[id]
+  };
+});
+var runFrameworks = async (_rc, positionals) => {
+  if (positionals.length > 0) {
+    throw new CliError(
+      "PUCK-CLI-INVALID-ARGS",
+      `\`frameworks\` doesn't take arguments. Run \`${CANONICAL_INVOCATION} frameworks\`.`
+    );
+  }
+  const result = emptyResult("frameworks");
+  result.frameworks = frameworkSupport();
+  result.message = `Create a new app with \`${CANONICAL_INVOCATION} init --framework <id>\`.`;
+  return result;
+};
+
 // src/cli.ts
 var exitCodeFor = (result) => {
   if (result.status === "error")
@@ -7145,6 +7245,8 @@ var runCli = async (argv, deps) => {
     else if (command === "add") result = await runAdd(rc, positionals);
     else if (command === "status") result = await runStatus(rc);
     else if (command === "docs") result = await runDocs(rc, positionals);
+    else if (command === "frameworks")
+      result = await runFrameworks(rc, positionals);
     else result = await runDoctor(rc);
   } catch (err) {
     result = errorResult(command, err, flags.dryRun);
@@ -7280,7 +7382,7 @@ runCli(process.argv.slice(2), {
   stdout: process.stdout,
   stderr: process.stderr,
   stdinIsTTY: Boolean(process.stdin.isTTY),
-  cliVersion: "0.24.0-canary.301a0304",
+  cliVersion: "0.24.0-canary.55558da4",
   runner: createRunner(env),
   fetch: globalThis.fetch,
   openUrl,

package/dist/docs/cli.md

@@ -21,14 +21,16 @@ Puck AI is optional. It's the editor plugin that uses Puck Cloud as its backend,
 
 - Next.js 15+ using the App Router (`app/` or `src/app/`)
 - React Router 7+ in framework mode
-- [TanStack Start](https://tanstack.com/start) 1.x
-- [vinext](https://github.com/cloudflare/vinext) using the App Router
-- [Vite](https://vite.dev) React apps (see [Vite and Astro](#vite-and-astro))
+- [TanStack Start](https://tanstack.com/start) 1.132+
+- [vinext](https://github.com/cloudflare/vinext) 1+ using the App Router
+- [Vite](https://vite.dev) 6+ React apps (see [Vite and Astro](#vite-and-astro))
 - [Astro](https://astro.build) 7+ (see [Vite and Astro](#vite-and-astro))
-- [Hono](https://hono.dev) and [Express](https://expressjs.com) servers (see [Servers](#servers))
+- [Hono](https://hono.dev) 4+ and [Express](https://expressjs.com) 4.16+ servers (see [Servers](#servers))
 - npm, pnpm, Yarn and Bun, including workspaces
 - TypeScript projects
 
+Run `npx @puckeditor/cli frameworks` to see what the CLI sets up for each framework. Older versions fail with `PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION`.
+
 When the CLI can't safely change something, like an existing `middleware.ts`, it leaves the file alone and tells you exactly what to add.
 
 ## Vite and Astro
@@ -159,6 +161,7 @@ npx skills add puckeditor/skills --skill puck
 | `add ai`     | Add the Puck AI plugin (adds Puck Cloud first if needed)           |
 | `status`     | Show what's installed and configured                               |
 | `doctor`     | Diagnose problems and suggest fixes. Never makes changes           |
+| `frameworks` | Show the supported frameworks and versions                         |
 | `docs`       | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
 
 ## Flags

package/dist/templates/express/src/puck/pages.ts

@@ -27,13 +27,18 @@ puckPages.get("/api/pages", async (req, res) => {
 puckPages.post(
   "/api/pages",
   express.json({ limit: "10mb" }),
-  async (req, res) => {
-    const { path, data } = req.body;
-    const pages = await readPages();
-
-    pages[path] = data;
-    await fs.writeFile(databasePath, JSON.stringify(pages));
-
-    res.json({ status: "ok" });
+  async (req, res, next) => {
+    // Express 4 doesn't pass errors from async handlers to next()
+    try {
+      const { path, data } = req.body;
+      const pages = await readPages();
+
+      pages[path] = data;
+      await fs.writeFile(databasePath, JSON.stringify(pages));
+
+      res.json({ status: "ok" });
+    } catch (error) {
+      next(error);
+    }
   }
 );

package/dist/templates/express-ai/src/puck/pages.ts

@@ -27,13 +27,18 @@ puckPages.get("/api/pages", async (req, res) => {
 puckPages.post(
   "/api/pages",
   express.json({ limit: "10mb" }),
-  async (req, res) => {
-    const { path, data } = req.body;
-    const pages = await readPages();
-
-    pages[path] = data;
-    await fs.writeFile(databasePath, JSON.stringify(pages));
-
-    res.json({ status: "ok" });
+  async (req, res, next) => {
+    // Express 4 doesn't pass errors from async handlers to next()
+    try {
+      const { path, data } = req.body;
+      const pages = await readPages();
+
+      pages[path] = data;
+      await fs.writeFile(databasePath, JSON.stringify(pages));
+
+      res.json({ status: "ok" });
+    } catch (error) {
+      next(error);
+    }
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@puckeditor/cli",
-  "version": "0.24.0-canary.301a0304",
+  "version": "0.24.0-canary.55558da4",
   "description": "Set up Puck and Puck Cloud from the command line. Built for coding agents, friendly for humans.",
   "author": "Chris Villa <chris@puckeditor.com>",
   "repository": {