@puckeditor/cli 0.24.0-canary.3e19956e → 0.24.0-canary.5eddccac

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,9 +11,11 @@ npx @puckeditor/cli init
11
11
  For coding agents:
12
12
 
13
13
  ```sh
14
- npx @puckeditor/cli init --yes --json --ai # or --no-ai for the editor only
14
+ npx @puckeditor/cli init --yes --json
15
15
  ```
16
16
 
17
+ `init` returns a `choose_ai` action. Ask the developer rather than choosing for them.
18
+
17
19
  Other commands:
18
20
 
19
21
  ```sh
@@ -32,6 +34,8 @@ See the [CLI docs](https://puckeditor.com/docs/cli) for the full JSON contract,
32
34
 
33
35
  The CLI collects anonymous usage data. See [Telemetry](https://puckeditor.com/docs/cli#telemetry) for what's sent and how to turn it off.
34
36
 
37
+ Coding agents: leave this to the developer. Don't turn telemetry off unless they ask.
38
+
35
39
  ## Development
36
40
 
37
41
  The CLI integrates Puck using the [recipes](../../recipes) as templates. Tests read the recipes directly, and `pnpm build` copies them into `dist/templates`.
package/dist/bin.mjs CHANGED
@@ -301,7 +301,7 @@ var MIN_VERSIONS = {
301
301
  // express.json() arrived in 4.16
302
302
  express: "4.16"
303
303
  };
304
- 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";
304
+ 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";
305
305
  var unsupportedVersion = (id2, version, range) => {
306
306
  const found = versionOf(version) ?? versionOf(range);
307
307
  const [major2, minor] = versionOf(MIN_VERSIONS[id2]);
@@ -452,7 +452,7 @@ var detectReactRouter = (vfs, root, range) => {
452
452
  status: "unsupported",
453
453
  error: {
454
454
  code: "PUCK-CLI-UNSUPPORTED-FRAMEWORK",
455
- message: "Found @react-router/dev but no react-router.config or app/routes file. The CLI supports React Router 7 framework mode.",
455
+ message: "Found @react-router/dev but no react-router.config or app/routes file. The CLI supports React Router 7+ framework mode.",
456
456
  details: { docs: MANUAL_INTEGRATION_DOCS_URL }
457
457
  }
458
458
  };
@@ -820,6 +820,8 @@ var COMMANDS = [
820
820
  "help"
821
821
  ];
822
822
  var FRAMEWORKS = FRAMEWORK_IDS;
823
+ var NO_POSITIONALS = ["init", "status", "doctor"];
824
+ var PLACEHOLDER = /^(<.*>|\[.*\])$/;
823
825
  var parseCliArgs = (argv) => {
824
826
  let parsed;
825
827
  try {
@@ -841,11 +843,19 @@ var parseCliArgs = (argv) => {
841
843
  if (!COMMANDS.includes(first)) {
842
844
  throw new CliError(
843
845
  "PUCK-CLI-UNKNOWN-COMMAND",
844
- `Unknown command "${first}". Run \`${CANONICAL_INVOCATION} --help\` to see available commands.`
846
+ `Unknown command "${first}". Run \`${CANONICAL_INVOCATION} --help\` to see available commands.`,
847
+ { command: first }
845
848
  );
846
849
  }
847
850
  command = first;
848
851
  }
852
+ const placeholder = positionals.find((p) => PLACEHOLDER.test(p));
853
+ if (command && NO_POSITIONALS.includes(command) && placeholder) {
854
+ throw new CliError(
855
+ "PUCK-CLI-INVALID-ARGS",
856
+ `"${placeholder}" is a placeholder. Ask the developer to pick one of the action's choices, then pass that flag instead.`
857
+ );
858
+ }
849
859
  const values = parsed.values;
850
860
  const allowed = COMMAND_OPTIONS[command ?? "help"];
851
861
  for (const key of Object.keys(values)) {
@@ -3012,8 +3022,35 @@ var planReactRouterAi = (p, info) => {
3012
3022
  snippet: AI_SNIPPET
3013
3023
  });
3014
3024
  };
3025
+ var REACT_ROUTER_7 = "^7.18.0";
3026
+ var V8_FUTURE_FLAGS = ` future: {
3027
+ v8_middleware: true,
3028
+ v8_splitRouteModules: true,
3029
+ v8_viteEnvironmentApi: true,
3030
+ v8_passThroughRequests: true,
3031
+ v8_trailingSlashAwareDataRequests: true,
3032
+ },
3033
+ `;
3034
+ var reactRouterLegacyScaffold = (nodeVersion) => {
3035
+ const [major2, minor] = versionOf(nodeVersion) ?? [0, 0];
3036
+ if (major2 > 22 || major2 === 22 && minor >= 22) return null;
3037
+ return {
3038
+ dependencies: {
3039
+ "react-router": REACT_ROUTER_7,
3040
+ "@react-router/node": REACT_ROUTER_7,
3041
+ "@react-router/serve": REACT_ROUTER_7,
3042
+ "@react-router/dev": REACT_ROUTER_7
3043
+ },
3044
+ node: ">=20.0.0",
3045
+ files: {
3046
+ "react-router.config.ts": (text) => text.replace(/^} satisfies Config;/m, `${V8_FUTURE_FLAGS}$&`)
3047
+ },
3048
+ warning: `React Router 8 needs Node 22.22 or later, and this is Node ${nodeVersion}, so the app uses React Router 7. To move to React Router 8, upgrade Node and update react-router, @react-router/node, @react-router/serve and @react-router/dev to ^8.`
3049
+ };
3050
+ };
3015
3051
  var reactRouterAdapter = {
3016
3052
  recipe: (withAi) => withAi ? "react-router-ai" : "react-router",
3053
+ legacyScaffold: reactRouterLegacyScaffold,
3017
3054
  recipeCloudRoute: REACT_ROUTER_CLOUD_ROUTE_FILE("app"),
3018
3055
  appDir: (info) => info.appDir,
3019
3056
  configDirs: (info) => ["", "src", info.appDir],
@@ -5105,17 +5142,32 @@ import path20 from "path";
5105
5142
 
5106
5143
  // src/templates/transform.ts
5107
5144
  var WORKSPACE_PROTOCOL = /^workspace:/;
5108
- var transformPackageJson = (text, { appName, cliVersion }) => {
5145
+ var transformPackageJson = (text, {
5146
+ appName,
5147
+ cliVersion,
5148
+ legacy
5149
+ }) => {
5109
5150
  const pkg = JSON.parse(text);
5110
5151
  pkg.name = appName;
5152
+ const pinned = [];
5111
5153
  for (const field of ["dependencies", "devDependencies"]) {
5112
5154
  const deps = pkg[field];
5113
5155
  if (!deps) continue;
5114
5156
  delete deps["eslint-config-custom"];
5115
5157
  for (const [name, range] of Object.entries(deps)) {
5116
- if (WORKSPACE_PROTOCOL.test(range)) deps[name] = `^${cliVersion}`;
5158
+ if (legacy?.dependencies[name]) deps[name] = legacy.dependencies[name];
5159
+ if (!WORKSPACE_PROTOCOL.test(range)) continue;
5160
+ deps[name] = `^${cliVersion}`;
5161
+ pinned.push(name);
5117
5162
  }
5118
5163
  }
5164
+ if (cliVersion.includes("-") && pinned.length > 0) {
5165
+ pkg.overrides = {
5166
+ ...pkg.overrides,
5167
+ ...Object.fromEntries(pinned.map((name) => [name, `$${name}`]))
5168
+ };
5169
+ }
5170
+ if (legacy) pkg.engines = { ...pkg.engines, node: legacy.node };
5119
5171
  if (pkg.scripts?.lint === "eslint") delete pkg.scripts.lint;
5120
5172
  return JSON.stringify(pkg, null, 2) + "\n";
5121
5173
  };
@@ -5158,16 +5210,24 @@ var scaffoldApp = (vfs, templates2, {
5158
5210
  dir,
5159
5211
  appName,
5160
5212
  cliVersion,
5161
- cloudHost
5213
+ cloudHost,
5214
+ legacy
5162
5215
  }) => {
5163
5216
  const files = templates2.list(recipe);
5164
5217
  for (const rel of files) {
5165
5218
  const target = path20.join(dir, ...rel.split("/"));
5166
5219
  const raw = templates2.read(recipe, rel);
5167
- if (rel === "package.json") {
5220
+ const legacyFile = legacy?.files[rel];
5221
+ if (legacyFile) {
5222
+ vfs.write(target, legacyFile(raw.toString("utf8")));
5223
+ } else if (rel === "package.json") {
5168
5224
  vfs.write(
5169
5225
  target,
5170
- transformPackageJson(raw.toString("utf8"), { appName, cliVersion })
5226
+ transformPackageJson(raw.toString("utf8"), {
5227
+ appName,
5228
+ cliVersion,
5229
+ legacy
5230
+ })
5171
5231
  );
5172
5232
  } else if (rel === "tsconfig.json") {
5173
5233
  vfs.write(target, transformTsconfig(raw.toString("utf8")));
@@ -6228,16 +6288,18 @@ var runMutation = async (rc, input) => {
6228
6288
  const root = bootstrap?.dir ?? input.root;
6229
6289
  const cloudHost = deps.env.PUCK_CLOUD_URL ? `${deps.env.PUCK_CLOUD_URL.replace(/\/+$/, "")}/api` : void 0;
6230
6290
  let scaffoldStep = null;
6291
+ let legacy = null;
6231
6292
  if (bootstrap) {
6232
- const recipe = ADAPTERS[bootstrap.framework].recipe(
6233
- input.requested.includes("ai")
6234
- );
6293
+ const adapter2 = ADAPTERS[bootstrap.framework];
6294
+ const recipe = adapter2.recipe(input.requested.includes("ai"));
6295
+ legacy = adapter2.legacyScaffold?.(deps.nodeVersion) ?? null;
6235
6296
  const { files } = scaffoldApp(vfs, deps.templates, {
6236
6297
  recipe,
6237
6298
  dir: bootstrap.dir,
6238
6299
  appName: bootstrap.appName,
6239
6300
  cliVersion: deps.cliVersion,
6240
- cloudHost
6301
+ cloudHost,
6302
+ legacy
6241
6303
  });
6242
6304
  scaffoldStep = {
6243
6305
  id: "bootstrap:scaffold",
@@ -6263,6 +6325,7 @@ var runMutation = async (rc, input) => {
6263
6325
  const planner = new Planner(vfs, ctx, state, deps.templates, deps.cliVersion);
6264
6326
  planner.scaffolded = Boolean(bootstrap);
6265
6327
  planner.cloudHost = cloudHost;
6328
+ if (legacy) planner.warn("PUCK-CLI-W-NODE-VERSION", legacy.warning);
6266
6329
  for (const warning of ctx.warnings)
6267
6330
  planner.warn("PUCK-CLI-W-DETECTION", warning);
6268
6331
  const summaries = () => {
@@ -6431,10 +6494,14 @@ var runMutation = async (rc, input) => {
6431
6494
  );
6432
6495
  result.message = blocked ? `Partially set up. ${unsatisfied.length ? `Still missing: ${unsatisfied.flatMap((c) => status[c].missing).join("; ")}.` : "Complete the required actions below."}` : result.changed ? `Set up ${done.map((c) => capabilityLabels(state.target === "server")[c]).join(", ").replace(/, ([^,]*)$/, " and $1")}.` : "Already set up. Nothing changed.";
6433
6496
  const devCommand = `${verifiedCtx.packageManager.name} ${verifiedCtx.packageManager.name === "npm" ? "run " : ""}dev`;
6434
- const cdPrefix = root === base ? "" : `cd ${displayPath(base, root)} && `;
6497
+ const devSteps = [
6498
+ ...root === base ? [] : [`cd ${displayPath(base, root)}`],
6499
+ devCommand
6500
+ ];
6435
6501
  result.nextSteps = [
6436
6502
  ...(input.notes ?? []).map((n) => `# ${n}`),
6437
- `${cdPrefix}${devCommand}`,
6503
+ // Windows PowerShell 5.1 has no `&&`
6504
+ ...rc.deps.platform === "win32" ? devSteps : [devSteps.join(" && ")],
6438
6505
  `# then open ${adapterFor(verifiedCtx.framework ?? ctx.framework).devUrl}`
6439
6506
  ];
6440
6507
  if (wantsCloud && !capabilities.includes("ai") && !status.ai.satisfied) {
@@ -6829,10 +6896,14 @@ var runConnect = async (rc) => {
6829
6896
  result.filesCreated = outcome.created.map((f) => displayPath(base, f)).sort();
6830
6897
  result.filesModified = [...outcome.created, ...outcome.modified].map((f) => displayPath(base, f)).sort();
6831
6898
  const pm = verifiedCtx.packageManager.name;
6832
- const cdPrefix = root === base ? "" : `cd ${displayPath(base, root)} && `;
6899
+ const devSteps = [
6900
+ ...root === base ? [] : [`cd ${displayPath(base, root)}`],
6901
+ `${pm} ${pm === "npm" ? "run " : ""}dev`
6902
+ ];
6833
6903
  result.nextSteps = cloudReady ? [
6834
6904
  "# Restart the dev server so it picks up the new key",
6835
- `${cdPrefix}${pm} ${pm === "npm" ? "run " : ""}dev`
6905
+ // Windows PowerShell 5.1 has no `&&`
6906
+ ...rc.deps.platform === "win32" ? devSteps : [devSteps.join(" && ")]
6836
6907
  ] : [`${CANONICAL_INVOCATION} add cloud${where}`];
6837
6908
  return result;
6838
6909
  };
@@ -7537,6 +7608,7 @@ var AGENTS = [
7537
7608
  var detectAgent = (env2) => AGENTS.find(([key]) => env2[key] !== void 0 && env2[key] !== "")?.[1] ?? null;
7538
7609
  var id = (value) => value && /^[A-Za-z0-9._@:-]{1,64}$/.test(value) ? value : null;
7539
7610
  var ids = (values) => values.map(id).filter((v) => v !== null);
7611
+ var word = (value) => typeof value === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(value) ? value : null;
7540
7612
  var major = (version) => {
7541
7613
  const match = version?.match(/\d+/);
7542
7614
  return match ? Number(match[0]) : null;
@@ -7551,6 +7623,7 @@ var buildEvent = (input) => {
7551
7623
  capabilities: input.command === "add" ? CAPABILITY_IDS.filter((c) => input.positionals.includes(c)) : [],
7552
7624
  status: result.status,
7553
7625
  errorCode: id(result.error?.code),
7626
+ unknownCommand: result.error?.code === "PUCK-CLI-UNKNOWN-COMMAND" ? word(result.error.details?.command) : null,
7554
7627
  exitCode: input.exitCode,
7555
7628
  durationMs: Math.max(0, Math.round(input.durationMs)),
7556
7629
  dryRun: Boolean(flags.dryRun),
@@ -7737,6 +7810,10 @@ var runCli = async (argv, deps) => {
7737
7810
  // src/io/runner.ts
7738
7811
  import { spawn } from "child_process";
7739
7812
  var MAX_CAPTURE = 64 * 1024;
7813
+ var CMD_SPECIAL = /[\s^&|<>()]/;
7814
+ var quoteForShell = (args, platform) => platform === "win32" ? args.map(
7815
+ (arg) => CMD_SPECIAL.test(arg) && !arg.includes('"') ? `"${arg}"` : arg
7816
+ ) : args;
7740
7817
  var append = (current, chunk) => {
7741
7818
  const next = current + chunk.toString("utf8");
7742
7819
  return next.length > MAX_CAPTURE ? next.slice(-MAX_CAPTURE) : next;
@@ -7746,7 +7823,7 @@ var createRunner = (baseEnv) => ({
7746
7823
  return new Promise((resolve) => {
7747
7824
  let stdout = "";
7748
7825
  let stderr = "";
7749
- const child = spawn(command, args, {
7826
+ const child = spawn(command, quoteForShell(args, process.platform), {
7750
7827
  cwd,
7751
7828
  stdio: ["ignore", "pipe", "pipe"],
7752
7829
  // Package managers ship as .cmd shims on Windows
@@ -7854,7 +7931,7 @@ runCli(process.argv.slice(2), {
7854
7931
  stdout: process.stdout,
7855
7932
  stderr: process.stderr,
7856
7933
  stdinIsTTY: Boolean(process.stdin.isTTY),
7857
- cliVersion: "0.24.0-canary.3e19956e",
7934
+ cliVersion: "0.24.0-canary.5eddccac",
7858
7935
  runner: createRunner(env),
7859
7936
  fetch: globalThis.fetch,
7860
7937
  openUrl,
package/dist/docs/cli.md CHANGED
@@ -15,12 +15,12 @@ npx @puckeditor/cli init
15
15
 
16
16
  With Puck AI, the only manual step is logging in to Puck Cloud and approving the connection in your browser. When it's done, the CLI starts your dev server and opens the editor.
17
17
 
18
- Puck AI is optional. It's the editor plugin that uses Puck Cloud as its backend, so choosing it sets up Puck Cloud too. `init` asks whether to add it; pass `--ai` or `--no-ai` to choose up front.
18
+ Puck AI is optional. It's the editor plugin that uses Puck Cloud as its backend, so choosing it sets up Puck Cloud too. `init` asks whether to add it, and gives coding agents a `choose_ai` action to ask the developer. Pass `--ai` or `--no-ai` when the developer has already chosen, such as in the command from the Puck Cloud setup page.
19
19
 
20
20
  ## Supported projects
21
21
 
22
22
  - Next.js 15+ using the App Router (`app/` or `src/app/`)
23
- - React Router 7+ in framework mode
23
+ - React Router 7+ in framework mode. New apps use React Router 8, or React Router 7 on Node.js older than 22.22, which React Router 8 requires
24
24
  - [TanStack Start](https://tanstack.com/start) 1.132+
25
25
  - [vinext](https://github.com/cloudflare/vinext) 1+ using the App Router
26
26
  - [Vite](https://vite.dev) 6+ React apps (see [Vite and Astro](#vite-and-astro))
@@ -218,13 +218,14 @@ The CLI collects anonymous usage data to help us improve it. The first time it r
218
218
  Each command sends one event to Puck Cloud with:
219
219
 
220
220
  - The command, what `add` was asked for, the result status, error and warning codes, the actions it returned, the exit code and how long it took
221
+ - The word given in place of a command, when it isn't one and is a plain lowercase word, such as `create`
221
222
  - Whether it was a dry run, made changes, ran interactively, used `--json` or ran in CI
222
223
  - The CLI version, operating system, CPU architecture and Node.js version
223
224
  - The name of the coding agent running it, if it's a known one, such as `claude-code`
224
225
  - The framework and its major version, the package manager, the `--backend` choice, whether the project is in a monorepo, and whether the Puck editor, Puck Cloud and Puck AI are set up
225
226
  - A random ID, stored in `~/.config/puck/telemetry.json`
226
227
 
227
- It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys. When you log in to Puck Cloud with `connect`, the random ID is linked to your account.
228
+ It never sends code, file paths, project or package names, hostnames, error messages, flag values or API keys, other than a word typed in place of a command. When you log in to Puck Cloud with `connect`, the random ID is linked to your account. Logging in isn't telemetry: `connect` also sends your project's name and your computer's hostname, so the approval page can show what's connecting and name a new Puck Cloud project after your app.
228
229
 
229
230
  To turn telemetry off, run:
230
231
 
@@ -233,3 +234,5 @@ npx @puckeditor/cli telemetry disable
233
234
  ```
234
235
 
235
236
  Or set `PUCK_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1` in your environment. `telemetry status` shows whether it's on, and `PUCK_TELEMETRY_DEBUG=1` prints each event instead of sending it.
237
+
238
+ Coding agents: leave this to the developer. Don't turn telemetry off unless they ask.
@@ -1 +1 @@
1
- {"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props":{"title":"Puck + React Router 7 demo"}},"zones":{}}}
1
+ {"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props":{"title":"Puck + React Router demo"}},"zones":{}}}
@@ -11,16 +11,16 @@
11
11
  },
12
12
  "dependencies": {
13
13
  "@puckeditor/core": "workspace:*",
14
- "@react-router/node": "^7.18.0",
15
- "@react-router/serve": "^7.18.0",
14
+ "@react-router/node": "^8.4.0",
15
+ "@react-router/serve": "^8.4.0",
16
16
  "isbot": "^5",
17
- "react": "^19.0.0",
18
- "react-dom": "^19.0.0",
19
- "react-router": "^7.18.0"
17
+ "react": "^19.2.7",
18
+ "react-dom": "^19.2.7",
19
+ "react-router": "^8.4.0"
20
20
  },
21
21
  "devDependencies": {
22
- "@react-router/dev": "^7.18.0",
23
- "@types/node": "^20",
22
+ "@react-router/dev": "^8.4.0",
23
+ "@types/node": "^22",
24
24
  "@types/react": "^19.0.1",
25
25
  "@types/react-dom": "^19.0.2",
26
26
  "typescript": "^5.8.3",
@@ -28,6 +28,6 @@
28
28
  "vite-tsconfig-paths": "^5.1.4"
29
29
  },
30
30
  "engines": {
31
- "node": ">=20.0.0"
31
+ "node": ">=22.22.0"
32
32
  }
33
33
  }
@@ -1 +1 @@
1
- {"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props":{"title":"Puck + React Router 7 demo"}},"zones":{}}}
1
+ {"/":{"content":[{"type":"HeadingBlock","props":{"title":"Edit this page by adding /edit to the end of the URL","id":"HeadingBlock-1694032984497"}}],"root":{"props":{"title":"Puck + React Router demo"}},"zones":{}}}
@@ -13,16 +13,16 @@
13
13
  "@puckeditor/cloud-client": "^0",
14
14
  "@puckeditor/core": "workspace:*",
15
15
  "@puckeditor/plugin-ai": "^0",
16
- "@react-router/node": "^7.18.0",
17
- "@react-router/serve": "^7.18.0",
16
+ "@react-router/node": "^8.4.0",
17
+ "@react-router/serve": "^8.4.0",
18
18
  "isbot": "^5",
19
- "react": "^19.0.0",
20
- "react-dom": "^19.0.0",
21
- "react-router": "^7.18.0"
19
+ "react": "^19.2.7",
20
+ "react-dom": "^19.2.7",
21
+ "react-router": "^8.4.0"
22
22
  },
23
23
  "devDependencies": {
24
- "@react-router/dev": "^7.18.0",
25
- "@types/node": "^20",
24
+ "@react-router/dev": "^8.4.0",
25
+ "@types/node": "^22",
26
26
  "@types/react": "^19.0.1",
27
27
  "@types/react-dom": "^19.0.2",
28
28
  "typescript": "^5.8.3",
@@ -30,6 +30,6 @@
30
30
  "vite-tsconfig-paths": "^5.1.4"
31
31
  },
32
32
  "engines": {
33
- "node": ">=20.0.0"
33
+ "node": ">=22.22.0"
34
34
  }
35
35
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@puckeditor/cli",
3
- "version": "0.24.0-canary.3e19956e",
3
+ "version": "0.24.0-canary.5eddccac",
4
4
  "description": "Set up Puck and Puck Cloud from the command line. Built for coding agents, friendly for humans.",
5
5
  "author": "Chris Villa <chris@puckeditor.com>",
6
6
  "repository": {