@puckeditor/cli 0.24.0-canary.301a0304 → 0.24.0-canary.6f40e09b

package/README.md

@@ -20,8 +20,10 @@ Other commands:
 npx @puckeditor/cli add editor   # add the Puck editor
 npx @puckeditor/cli add cloud    # connect Puck Cloud
 npx @puckeditor/cli add ai       # add the Puck AI plugin
+npx @puckeditor/cli connect      # log in to Puck Cloud again for a new API key
 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

@@ -2,7 +2,7 @@
 
 // src/bin.ts
 import os from "os";
-import path30 from "path";
+import path32 from "path";
 import fs7 from "fs";
 import { fileURLToPath } from "url";
 
@@ -38,6 +38,7 @@ var exitCodeByError = {
   "PUCK-CLI-FRAMEWORK-MISMATCH": EXIT_CODES.unsupported,
   "PUCK-CLI-BACKEND-REQUIRED": EXIT_CODES.usage,
   "PUCK-CLI-BACKEND-URL-REQUIRED": EXIT_CODES.usage,
+  "PUCK-CLI-EXTERNAL-BACKEND": EXIT_CODES.unsupported,
   "PUCK-CLI-WORKSPACE-TARGET-NOT-FOUND": EXIT_CODES.unsupported,
   "PUCK-CLI-TYPESCRIPT-REQUIRED": EXIT_CODES.unsupported,
   "PUCK-CLI-TARGET-DIR-NOT-EMPTY": EXIT_CODES.filesystem,
@@ -67,9 +68,6 @@ var CliError = class extends Error {
 // src/args.ts
 import { parseArgs } from "util";
 
-// src/detect/framework.ts
-import path3 from "path";
-
 // src/constants.ts
 var ENV_KEY = "PUCK_API_KEY";
 var DEFAULT_CLOUD_URL = "https://cloud.puckeditor.com";
@@ -82,6 +80,9 @@ var CLOUD_CLIENT_PACKAGE = "@puckeditor/cloud-client";
 var PLUGIN_AI_PACKAGE = "@puckeditor/plugin-ai";
 var CANONICAL_INVOCATION = "npx @puckeditor/cli";
 
+// src/detect/framework.ts
+import path3 from "path";
+
 // src/ast/parse.ts
 import { parse } from "@babel/parser";
 var isTsx = (filename) => /\.(tsx|jsx|js|mjs|cjs)$/.test(filename);
@@ -190,12 +191,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 +285,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 +375,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 +390,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 +413,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 +476,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 +525,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 +551,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 +576,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: {
@@ -772,17 +800,21 @@ var MUTATING = [
 var COMMAND_OPTIONS = {
   init: [...GLOBAL, ...MUTATING, "framework", "name", "ai", "no-ai"],
   add: [...GLOBAL, ...MUTATING],
+  connect: [...GLOBAL, "api-key", "config", "wait"],
   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 = [
   "init",
   "add",
+  "connect",
   "status",
   "doctor",
   "docs",
+  "frameworks",
   "help"
 ];
 var FRAMEWORKS = FRAMEWORK_IDS;
@@ -807,7 +839,7 @@ var parseCliArgs = (argv) => {
     if (!COMMANDS.includes(first)) {
       throw new CliError(
         "PUCK-CLI-UNKNOWN-COMMAND",
-        `Unknown command "${first}". Run \`puck --help\` to see available commands.`
+        `Unknown command "${first}". Run \`${CANONICAL_INVOCATION} --help\` to see available commands.`
       );
     }
     command = first;
@@ -818,7 +850,7 @@ var parseCliArgs = (argv) => {
     if (!allowed.includes(key)) {
       throw new CliError(
         "PUCK-CLI-INVALID-ARGS",
-        `--${key} can't be used with \`${command ?? "puck"}\`.`
+        `--${key} can't be used with \`${command ?? CANONICAL_INVOCATION}\`.`
       );
     }
   }
@@ -1127,11 +1159,19 @@ var COMMANDS2 = [
     name: "add <editor|cloud|ai>",
     description: "Add one capability (ai includes cloud, cloud includes editor)"
   },
+  {
+    name: "connect",
+    description: "Log in to Puck Cloud again and replace PUCK_API_KEY"
+  },
   { name: "status", description: "Show what's installed and configured" },
   {
     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>"
@@ -1471,7 +1511,8 @@ var templates_default = {
     "*.tsbuildinfo",
     "eslint.config.mjs",
     ".env*"
-  ]
+  ],
+  allowBuilds: ["esbuild"]
 };
 
 // src/templates/source.ts
@@ -2517,10 +2558,10 @@ var analyzeRoutes = (code, filename) => {
   const topLevel = new Set(exported.elements.filter(Boolean));
   walk(exported, (node) => {
     if (!isRouteCall(node, routeLocal)) return;
-    const path31 = stringArg(node, 0);
+    const path33 = stringArg(node, 0);
     const isTop = topLevel.has(node);
-    calls.push({ path: path31, file: stringArg(node, 1), topLevel: isTop });
-    if (path31 === "*") {
+    calls.push({ path: path33, file: stringArg(node, 1), topLevel: isTop });
+    if (path33 === "*") {
       if (isTop) splat = node;
       else nestedSplat = true;
     }
@@ -4671,6 +4712,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 +4765,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 +4838,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:"),
@@ -4778,7 +4851,7 @@ var presentHuman = (out, result, secrets) => {
 };
 
 // src/commands/init.ts
-import path27 from "path";
+import path28 from "path";
 
 // src/io/vfs.ts
 import fs2 from "fs";
@@ -5248,7 +5321,7 @@ var resolveTarget = async (rc, opts = {}) => {
 };
 
 // src/commands/mutate.ts
-import path26 from "path";
+import path27 from "path";
 
 // src/plan/planner.ts
 import path22 from "path";
@@ -5506,6 +5579,66 @@ var planEnvWrite = (p, secret) => {
   planGitignore(p, target);
 };
 
+// src/plan/pnpm-builds.ts
+import path24 from "path";
+import { Document, isMap, isSeq, parseDocument } from "yaml";
+var LEGACY_LISTS = [
+  "onlyBuiltDependencies",
+  "neverBuiltDependencies",
+  "ignoredBuiltDependencies"
+];
+var allowAll = (names) => Object.fromEntries(names.map((name) => [name, true]));
+var withAllowedBuilds = (text, names) => {
+  const doc = parseDocument(text ?? "");
+  if (doc.errors.length > 0) return null;
+  if (doc.get("dangerouslyAllowAllBuilds") === true) return null;
+  const allowBuilds = doc.get("allowBuilds");
+  const covered = /* @__PURE__ */ new Set();
+  if (isMap(allowBuilds)) {
+    for (const item of allowBuilds.items) covered.add(String(item.key));
+  }
+  for (const list of LEGACY_LISTS) {
+    const seq = doc.get(list);
+    if (isSeq(seq)) for (const item of seq.toJSON()) covered.add(String(item));
+  }
+  const missing = names.filter((name) => !covered.has(name));
+  if (missing.length === 0) return null;
+  const legacy = doc.get("onlyBuiltDependencies");
+  if (isMap(allowBuilds)) {
+    for (const name of missing) allowBuilds.set(name, true);
+  } else if (isSeq(legacy)) {
+    for (const name of missing) legacy.add(name);
+  } else if (doc.contents === null) {
+    const created = new Document({ allowBuilds: allowAll(missing) });
+    created.commentBefore = " Dependencies allowed to run install scripts (required by pnpm 11+)";
+    return created.toString();
+  } else {
+    doc.set("allowBuilds", allowAll(missing));
+  }
+  return doc.toString();
+};
+var planAllowedBuilds = (planner) => {
+  const { ctx, vfs } = planner;
+  if (ctx.packageManager.name !== "pnpm") return;
+  const ws = ctx.workspace;
+  if (ws && ws.source !== "pnpm-workspace.yaml") return;
+  const file = path24.join(ws?.root ?? ctx.root, "pnpm-workspace.yaml");
+  const names = templates_default.allowBuilds;
+  const list = names.join(", ");
+  const next = withAllowedBuilds(vfs.readText(file), names);
+  if (next === null) return;
+  vfs.write(file, next);
+  if (!ws) return;
+  planner.steps.push({
+    id: "bootstrap:allow-builds",
+    kind: "modify_file",
+    capability: "bootstrap",
+    summary: `Allow ${list} build scripts in the workspace's pnpm-workspace.yaml`,
+    path: file,
+    edits: []
+  });
+};
+
 // src/plan/backend.ts
 var choicesFor = (options, wantsCloud) => [
   { value: "add", label: options.addLabel },
@@ -5575,14 +5708,14 @@ var resolveBackend = async (rc, options, capabilities, planned) => {
 
 // src/auth/session-store.ts
 import fs4 from "fs";
-import path24 from "path";
+import path25 from "path";
 import { createHash as createHash2 } from "crypto";
 var SessionStore = class {
   #file;
   constructor(cacheDir, projectRoot, baseUrl) {
     const key = createHash2("sha256").update(`${projectRoot}
 ${baseUrl}`).digest("hex").slice(0, 32);
-    this.#file = path24.join(cacheDir, "puck", "connect", `${key}.json`);
+    this.#file = path25.join(cacheDir, "puck", "connect", `${key}.json`);
   }
   get path() {
     return this.#file;
@@ -5596,14 +5729,14 @@ ${baseUrl}`).digest("hex").slice(0, 32);
     }
   }
   save(session) {
-    fs4.mkdirSync(path24.dirname(this.#file), { recursive: true, mode: 448 });
+    fs4.mkdirSync(path25.dirname(this.#file), { recursive: true, mode: 448 });
     fs4.writeFileSync(this.#file, JSON.stringify(session), { mode: 384 });
   }
   clear() {
     fs4.rmSync(this.#file, { force: true });
   }
 };
-var cacheDirFor = (env2, homedir) => env2.XDG_CACHE_HOME || path24.join(homedir, ".cache");
+var cacheDirFor = (env2, homedir) => env2.XDG_CACHE_HOME || path25.join(homedir, ".cache");
 
 // src/auth/credentials.ts
 var apiKeysUrl = (rc) => new URL(API_KEYS_PATH, rc.cloud.baseUrl).toString();
@@ -5826,7 +5959,7 @@ var promptForKey = async (rc) => {
     warnings: []
   };
 };
-var resolveCredential = async (rc, state, info) => {
+var resolveCredential = async (rc, state, info, { fresh = false } = {}) => {
   const warnings = [];
   const fromExplicit = async (value, source) => {
     const secret = secretFrom(
@@ -5852,10 +5985,15 @@ var resolveCredential = async (rc, state, info) => {
   };
   if (rc.flags.apiKey !== void 0)
     return fromExplicit(rc.flags.apiKey, "flag");
-  if (rc.deps.env[ENV_KEY])
+  if (fresh && rc.deps.env[ENV_KEY]) {
+    warnings.push({
+      code: "PUCK-CLI-W-KEY-IN-PROCESS-ENV",
+      message: `${ENV_KEY} is set in your environment and overrides the new key in the env file. Unset it to use the new key.`
+    });
+  } else if (rc.deps.env[ENV_KEY])
     return fromExplicit(rc.deps.env[ENV_KEY], "process.env");
   const existing = state.cloud.apiKey;
-  if (existing.present && existing.value) {
+  if (!fresh && existing.present && existing.value) {
     const secret = secretFrom(
       rc,
       existing.value,
@@ -5916,7 +6054,7 @@ var resolveCredential = async (rc, state, info) => {
 
 // src/apply/applier.ts
 import fs5 from "fs";
-import path25 from "path";
+import path26 from "path";
 var tail = (text, lines = 20) => text.trim().split("\n").slice(-lines).join("\n");
 var run = async (rc, spec) => {
   rc.log(`$ ${formatCommand(spec)}`);
@@ -5946,14 +6084,14 @@ ${result.stderr}`))
   }
 };
 var writeFile = (file, content, mode) => {
-  fs5.mkdirSync(path25.dirname(file), { recursive: true });
+  fs5.mkdirSync(path26.dirname(file), { recursive: true });
   if (mode === void 0) {
     fs5.writeFileSync(file, content);
     return;
   }
-  const temp = path25.join(
-    path25.dirname(file),
-    `.${path25.basename(file)}.${process.pid}.tmp`
+  const temp = path26.join(
+    path26.dirname(file),
+    `.${path26.basename(file)}.${process.pid}.tmp`
   );
   fs5.writeFileSync(temp, content, { mode });
   fs5.chmodSync(temp, mode);
@@ -6154,6 +6292,7 @@ var runMutation = async (rc, input) => {
   }
   planCapabilities(planner, capabilities);
   planner.finalize();
+  if (bootstrap) planAllowedBuilds(planner);
   if (scaffoldStep) planner.steps.unshift(scaffoldStep);
   const wantsCloud = capabilities.includes("cloud") && planner.backend?.mode !== "external" && !state.cloud.external;
   const needsConsent = planner.steps.length > 0 || wantsCloud && !state.cloud.apiKey.present;
@@ -6192,7 +6331,7 @@ var runMutation = async (rc, input) => {
   if (wantsCloud) {
     credential = await resolveCredential(rc, state, {
       projectRoot: root,
-      projectName: bootstrap?.appName ?? ctx.packageJson?.name ?? path26.basename(root),
+      projectName: bootstrap?.appName ?? ctx.packageJson?.name ?? path27.basename(root),
       framework: ctx.framework.id
     });
     for (const w of credential.warnings) planner.warn(w.code, w.message);
@@ -6383,14 +6522,14 @@ var runInit = async (rc) => {
         { globs: target.workspace.globs }
       );
     }
-    parentDir = path27.join(target.workspace.root, appsDir);
+    parentDir = path28.join(target.workspace.root, appsDir);
     workspaceRoot = target.workspace.root;
     for (const pkg of target.workspace.packages) {
       if (pkg.name) existingNames.add(pkg.name);
-      existingNames.add(path27.basename(pkg.dir));
+      existingNames.add(path28.basename(pkg.dir));
     }
   } else {
-    if (vfs.exists(path27.join(target.root, "package.json"))) {
+    if (vfs.exists(path28.join(target.root, "package.json"))) {
       const read = readPackageJson(vfs, target.root);
       const deps = depsOf(read.status === "ok" ? read.pkg : null);
       const detection = detectFramework(vfs, target.root, deps);
@@ -6480,7 +6619,7 @@ var runInit = async (rc) => {
       `A workspace package named "${name}" already exists.`
     );
   }
-  const dir = inPlace ? parentDir : path27.join(parentDir, name);
+  const dir = inPlace ? parentDir : path28.join(parentDir, name);
   if (!inPlace && vfs.exists(dir) && !isEmptyDir(vfs, dir)) {
     throw new CliError(
       "PUCK-CLI-TARGET-DIR-NOT-EMPTY",
@@ -6499,7 +6638,7 @@ var runInit = async (rc) => {
     bootstrap: {
       framework,
       dir,
-      appName: name ?? sanitizeAppName(path27.basename(dir)),
+      appName: name ?? sanitizeAppName(path28.basename(dir)),
       workspaceRoot
     },
     workspace: target.kind === "workspace-empty" ? target.summary : null
@@ -6513,7 +6652,7 @@ var runAdd = async (rc, positionals) => {
       "PUCK-CLI-INVALID-ARGS",
       `Specify what to add: ${CAPABILITY_IDS.join(
         ", "
-      )}. For example \`puck add cloud\`.`
+      )}. For example \`${CANONICAL_INVOCATION} add cloud\`.`
     );
   }
   const unknown = positionals.filter(
@@ -6551,6 +6690,144 @@ var runAdd = async (rc, positionals) => {
   });
 };
 
+// src/commands/connect.ts
+import path29 from "path";
+var runConnect = async (rc) => {
+  const { deps, flags } = rc;
+  const result = emptyResult("connect", flags.dryRun);
+  const target = await resolveTarget(rc);
+  if (target.kind === "action") {
+    result.status = "action_required";
+    result.message = target.action.message;
+    result.actions = [target.action];
+    return result;
+  }
+  if (target.kind === "workspace-empty") {
+    throw new CliError(
+      "PUCK-CLI-UNSUPPORTED-FRAMEWORK",
+      `No supported app was found in this workspace. Run \`${CANONICAL_INVOCATION} init\` to create one.`,
+      { fix: `${CANONICAL_INVOCATION} init --name <name>` }
+    );
+  }
+  const base = baseDir(rc);
+  const root = target.root;
+  const vfs = new Vfs();
+  const ctx = detectProject({
+    vfs,
+    root,
+    cwd: base,
+    packageManagerFlag: flags.packageManager,
+    env: deps.env
+  });
+  assertSupported(rc, ctx);
+  const state = detectState(vfs, ctx, deps.env, { configFlag: flags.config });
+  if (state.cloud.external) {
+    throw new CliError(
+      "PUCK-CLI-EXTERNAL-BACKEND",
+      "This app sends Puck Cloud requests to a server elsewhere, and the key lives there. Run connect against that server instead.",
+      { fix: `${CANONICAL_INVOCATION} connect --cwd <server dir>` }
+    );
+  }
+  const planner = new Planner(vfs, ctx, state, deps.templates, deps.cliVersion);
+  for (const warning of ctx.warnings)
+    planner.warn("PUCK-CLI-W-DETECTION", warning);
+  const cloudReady = state.cloud.clientInstalled && Boolean(state.cloud.routeFile) && state.cloud.routeRegistered !== false;
+  const where = root === base ? "" : ` --cwd ${displayPath(base, root)}`;
+  if (!cloudReady) {
+    planner.warn(
+      "PUCK-CLI-W-CLOUD-NOT-SET-UP",
+      `Puck Cloud isn't set up in this app yet, so nothing uses ${ENV_KEY}. Run \`${CANONICAL_INVOCATION} add cloud\` to set it up.`
+    );
+  }
+  const finish = (status, message) => {
+    result.status = status;
+    result.message = message;
+    result.project = projectSummary(ctx, target.workspace);
+    result.cloud = cloudSummary(state, "none");
+    result.warnings = planner.warnings;
+    return result;
+  };
+  if (!flags.dryRun && !rc.interactive && !flags.yes) {
+    result.actions = [
+      {
+        id: "confirm",
+        type: "confirm_plan",
+        required: true,
+        flag: "--yes",
+        message: `Re-run with --yes to log in to Puck Cloud and replace ${ENV_KEY}.`,
+        rerun: `${rerunCommand(rc)} --yes`
+      }
+    ];
+    return finish(
+      "action_required",
+      `Re-run with --yes to log in to Puck Cloud and replace ${ENV_KEY}.`
+    );
+  }
+  const credential = await resolveCredential(
+    rc,
+    state,
+    {
+      projectRoot: root,
+      projectName: ctx.packageJson?.name ?? path29.basename(root),
+      framework: ctx.framework.id
+    },
+    { fresh: true }
+  );
+  for (const w of credential.warnings) planner.warn(w.code, w.message);
+  if (credential.kind === "action") {
+    result.actions = [credential.action];
+    return finish(
+      "action_required",
+      credential.action.type === "browser_login" ? "Puck Cloud login required. No changes have been made yet." : "A Puck API key is required. No changes have been made yet."
+    );
+  }
+  if (credential.kind === "none") {
+    planner.warn(
+      "PUCK-CLI-W-KEY-NEEDED",
+      "You'll be asked to log in to Puck Cloud when you run this without --dry-run."
+    );
+    return finish("success", "Dry run: no changes were made.");
+  }
+  planEnvWrite(planner, credential.secret);
+  result.plan = { steps: serializeSteps(base, planner.steps) };
+  if (flags.dryRun) return finish("success", "Dry run: no changes were made.");
+  const outcome = await applyPlan(rc, vfs, planner.steps);
+  const after = new Vfs();
+  const verifiedCtx = detectProject({
+    vfs: after,
+    root,
+    cwd: base,
+    packageManagerFlag: flags.packageManager,
+    env: deps.env
+  });
+  const verifiedState = detectState(after, verifiedCtx, deps.env, {
+    configFlag: flags.config
+  });
+  const check = credential.verified;
+  finish(
+    "success",
+    `Connected to Puck Cloud. ${planner.steps.length ? `Saved ${ENV_KEY} to ${displayPath(
+      base,
+      verifiedState.cloud.apiKey.file ?? root
+    )}.` : `${ENV_KEY} was already set to this key.`}`
+  );
+  result.project = projectSummary(verifiedCtx, target.workspace);
+  result.cloud = cloudSummary(
+    verifiedState,
+    check === "valid" ? "remote" : check === "invalid" ? "failed" : "local"
+  );
+  result.changed = planner.steps.length > 0;
+  result.filesCreated = outcome.created.map((f) => displayPath(base, f)).sort();
+  result.filesModified = [...outcome.created, ...outcome.modified].map((f) => displayPath(base, f)).sort();
+  const pm = verifiedCtx.packageManager.name;
+  const cdPrefix = root === base ? "" : `cd ${displayPath(base, root)} && `;
+  result.nextSteps = cloudReady ? [
+    "# Restart the dev server so it picks up the new key",
+    `${cdPrefix}${pm} ${pm === "npm" ? "run " : ""}dev`
+  ] : [`${CANONICAL_INVOCATION} add cloud${where}`];
+  return result;
+};
+
 // src/commands/status.ts
 var runStatus = async (rc) => {
   const base = baseDir(rc);
@@ -6624,7 +6901,7 @@ var runStatus = async (rc) => {
 };
 
 // src/commands/doctor.ts
-import path28 from "path";
+import path30 from "path";
 var finding = (check, status, evidence, fix = null) => ({ check, status, evidence, fix });
 var runDoctor = async (rc) => {
   const base = baseDir(rc);
@@ -6709,7 +6986,7 @@ var runDoctor = async (rc) => {
     finding(
       "project.package_json",
       "ok",
-      displayPath(base, path28.join(ctx.root, "package.json"))
+      displayPath(base, path30.join(ctx.root, "package.json"))
     )
   );
   result.project = projectSummary(ctx, target.workspace);
@@ -6951,7 +7228,7 @@ var runDoctor = async (rc) => {
           "cloud.connection",
           "fail",
           "Puck Cloud rejected the API key",
-          `${CANONICAL_INVOCATION} add cloud${where}`
+          `${CANONICAL_INVOCATION} connect${where}`
         )
       );
     } else {
@@ -7090,6 +7367,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")
@@ -7143,8 +7455,11 @@ var runCli = async (argv, deps) => {
   try {
     if (command === "init") result = await runInit(rc);
     else if (command === "add") result = await runAdd(rc, positionals);
+    else if (command === "connect") result = await runConnect(rc);
     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);
@@ -7248,7 +7563,7 @@ var runDevServer = (spec, onReady) => new Promise((resolve) => {
 
 // src/docs/source.ts
 import fs6 from "fs";
-import path29 from "path";
+import path31 from "path";
 var DirDocsSource = class {
   #dir;
   constructor(dir) {
@@ -7256,21 +7571,21 @@ var DirDocsSource = class {
   }
   list() {
     return JSON.parse(
-      fs6.readFileSync(path29.join(this.#dir, "index.json"), "utf8")
+      fs6.readFileSync(path31.join(this.#dir, "index.json"), "utf8")
     );
   }
   read(page) {
-    return fs6.readFileSync(path29.join(this.#dir, `${page}.md`), "utf8");
+    return fs6.readFileSync(path31.join(this.#dir, `${page}.md`), "utf8");
   }
 };
 
 // src/bin.ts
-var distDir = path30.dirname(fileURLToPath(import.meta.url));
-var templatesDir = path30.join(distDir, "templates");
+var distDir = path32.dirname(fileURLToPath(import.meta.url));
+var templatesDir = path32.join(distDir, "templates");
 var templates = new DirTemplateSource(templatesDir, {
   gitignoreName: "_gitignore",
   manifest: () => JSON.parse(
-    fs7.readFileSync(path30.join(templatesDir, "manifest.json"), "utf8")
+    fs7.readFileSync(path32.join(templatesDir, "manifest.json"), "utf8")
   )
 });
 var env = { ...process.env };
@@ -7280,14 +7595,14 @@ 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.6f40e09b",
   runner: createRunner(env),
   fetch: globalThis.fetch,
   openUrl,
   runDevServer,
   createPrompter: () => createInquirerPrompter(process.stderr),
   templates,
-  docs: new DirDocsSource(path30.join(distDir, "docs")),
+  docs: new DirDocsSource(path32.join(distDir, "docs")),
   homedir: os.homedir(),
   hostname: os.hostname(),
   now: () => Date.now(),

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
@@ -157,8 +159,10 @@ npx skills add puckeditor/skills --skill puck
 | `add editor` | Add the Puck editor                                                |
 | `add cloud`  | Connect Puck Cloud (adds the editor first if needed)               |
 | `add ai`     | Add the Puck AI plugin (adds Puck Cloud first if needed)           |
+| `connect`    | Log in to Puck Cloud again and replace `PUCK_API_KEY`              |
 | `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
@@ -192,6 +196,12 @@ To use an existing key, prefer the environment over `--api-key`, which is visibl
 PUCK_API_KEY=your-key npx @puckeditor/cli add cloud --yes
 ```
 
+To log in again, for example to replace a revoked key, run `connect`. It always starts a new login and replaces the existing key, without changing any code:
+
+```sh
+npx @puckeditor/cli connect
+```
+
 Remember to set `PUCK_API_KEY` in your production environment too. `react-router-serve` and Cloudflare Workers don't load `.env` files; on Workers, use `wrangler secret put PUCK_API_KEY`.
 
 The `/api/puck` route and the editor are public by default. Add authentication before deploying.

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.6f40e09b",
   "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": {