@puckeditor/cli 0.24.0-canary.6f40e09b → 0.24.0-canary.b7903763

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
@@ -25,10 +25,13 @@ npx @puckeditor/cli status # show what's set up
25
25
  npx @puckeditor/cli doctor # diagnose problems
26
26
  npx @puckeditor/cli frameworks # show supported frameworks and versions
27
27
  npx @puckeditor/cli docs # read the docs for this version
28
+ npx @puckeditor/cli telemetry # show or change anonymous usage data collection
28
29
  ```
29
30
 
30
31
  See the [CLI docs](https://puckeditor.com/docs/cli) for the full JSON contract, actions and exit codes.
31
32
 
33
+ 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
+
32
35
  ## Development
33
36
 
34
37
  The CLI integrates Puck using the [recipes](../../recipes) as templates. Tests read the recipes directly, and `pnpm build` copies them into `dist/templates`.
@@ -40,7 +43,7 @@ pnpm build
40
43
  node dist/bin.mjs status
41
44
  ```
42
45
 
43
- Set `PUCK_CLOUD_URL` to point the CLI at a local Puck Cloud.
46
+ Set `PUCK_CLOUD_URL` to point the CLI at a local Puck Cloud. Telemetry goes there too. Set `PUCK_TELEMETRY_DEBUG=1` to print events to stderr instead of sending them.
44
47
 
45
48
  ## License
46
49
 
package/dist/bin.mjs CHANGED
@@ -2,8 +2,8 @@
2
2
 
3
3
  // src/bin.ts
4
4
  import os from "os";
5
- import path32 from "path";
6
- import fs7 from "fs";
5
+ import path33 from "path";
6
+ import fs8 from "fs";
7
7
  import { fileURLToPath } from "url";
8
8
 
9
9
  // src/errors.ts
@@ -302,21 +302,21 @@ var MIN_VERSIONS = {
302
302
  express: "4.16"
303
303
  };
304
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
- var unsupportedVersion = (id, version, range) => {
305
+ var unsupportedVersion = (id2, version, range) => {
306
306
  const found = versionOf(version) ?? versionOf(range);
307
- const [major, minor] = versionOf(MIN_VERSIONS[id]);
308
- if (!found || found[0] > major || found[0] === major && found[1] >= minor)
307
+ const [major2, minor] = versionOf(MIN_VERSIONS[id2]);
308
+ if (!found || found[0] > major2 || found[0] === major2 && found[1] >= minor)
309
309
  return null;
310
- const label2 = FRAMEWORK_LABELS[id];
310
+ const label2 = FRAMEWORK_LABELS[id2];
311
311
  return {
312
312
  status: "unsupported",
313
313
  error: {
314
314
  code: "PUCK-CLI-UNSUPPORTED-FRAMEWORK-VERSION",
315
- message: `${label2} ${version ?? range} is not supported. Upgrade to ${label2} ${MIN_VERSIONS[id]} or later, or integrate Puck manually.`,
315
+ message: `${label2} ${version ?? range} is not supported. Upgrade to ${label2} ${MIN_VERSIONS[id2]} or later, or integrate Puck manually.`,
316
316
  details: {
317
317
  docs: MANUAL_INTEGRATION_DOCS_URL,
318
318
  version: version ?? range,
319
- minVersion: MIN_VERSIONS[id]
319
+ minVersion: MIN_VERSIONS[id2]
320
320
  }
321
321
  }
322
322
  };
@@ -372,7 +372,7 @@ var detectAppRouter = (vfs, root, label2) => {
372
372
  };
373
373
  var detectNext = (vfs, root, range) => {
374
374
  const version = resolveInstalledVersion(vfs, root, "next");
375
- const major = majorOf(version) ?? majorOf(range) ?? 16;
375
+ const major2 = majorOf(version) ?? majorOf(range) ?? 16;
376
376
  const layout = detectAppRouter(vfs, root, "Next.js");
377
377
  if ("status" in layout) return layout;
378
378
  const tooOld = unsupportedVersion("next", version, range);
@@ -382,9 +382,9 @@ var detectNext = (vfs, root, range) => {
382
382
  info: {
383
383
  id: "next",
384
384
  version,
385
- major,
385
+ major: major2,
386
386
  ...layout,
387
- proxyKind: major >= 16 ? "proxy" : "middleware"
387
+ proxyKind: major2 >= 16 ? "proxy" : "middleware"
388
388
  }
389
389
  };
390
390
  };
@@ -412,7 +412,7 @@ var detectVinext = (vfs, root, range) => {
412
412
  };
413
413
  var detectReactRouter = (vfs, root, range) => {
414
414
  const version = resolveInstalledVersion(vfs, root, "@react-router/dev") ?? resolveInstalledVersion(vfs, root, "react-router");
415
- const major = majorOf(version) ?? majorOf(range);
415
+ const major2 = majorOf(version) ?? majorOf(range);
416
416
  const tooOld = unsupportedVersion("react-router", version, range);
417
417
  if (tooOld) return tooOld;
418
418
  const configFile = firstExisting(
@@ -465,7 +465,7 @@ var detectReactRouter = (vfs, root, range) => {
465
465
  info: {
466
466
  id: "react-router",
467
467
  version,
468
- major,
468
+ major: major2,
469
469
  appDir,
470
470
  routesFile,
471
471
  configFile,
@@ -574,14 +574,14 @@ var detectAstro = (vfs, root, range, deps) => {
574
574
  }
575
575
  };
576
576
  };
577
- var detectServer = (id) => (vfs, root, range, deps) => {
578
- const version = resolveInstalledVersion(vfs, root, id);
579
- const tooOld = unsupportedVersion(id, version, range);
577
+ var detectServer = (id2) => (vfs, root, range, deps) => {
578
+ const version = resolveInstalledVersion(vfs, root, id2);
579
+ const tooOld = unsupportedVersion(id2, version, range);
580
580
  if (tooOld) return tooOld;
581
581
  return {
582
582
  status: "detected",
583
583
  info: {
584
- id,
584
+ id: id2,
585
585
  version,
586
586
  major: majorOf(version) ?? majorOf(range),
587
587
  entry: findServerEntry(vfs, root),
@@ -805,6 +805,7 @@ var COMMAND_OPTIONS = {
805
805
  doctor: ["json", "help", "version", "cwd", "workspace", "config", "offline"],
806
806
  docs: ["json", "help", "version"],
807
807
  frameworks: ["json", "help", "version"],
808
+ telemetry: ["json", "help", "version"],
808
809
  help: GLOBAL
809
810
  };
810
811
  var COMMANDS = [
@@ -815,6 +816,7 @@ var COMMANDS = [
815
816
  "doctor",
816
817
  "docs",
817
818
  "frameworks",
819
+ "telemetry",
818
820
  "help"
819
821
  ];
820
822
  var FRAMEWORKS = FRAMEWORK_IDS;
@@ -1093,15 +1095,16 @@ var createCloudApi = (baseUrl, fetchImpl) => {
1093
1095
  };
1094
1096
  };
1095
1097
 
1098
+ // src/env/truthy.ts
1099
+ var isTruthyEnv = (value) => value !== void 0 && value !== "" && value !== "0" && value.toLowerCase() !== "false";
1100
+
1096
1101
  // src/context.ts
1097
- var isCI = (env2) => {
1098
- const ci = env2.CI;
1099
- return ci !== void 0 && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
1100
- };
1101
- var createRunContext = (deps, flags, argv) => {
1102
+ var isCI = (env2) => isTruthyEnv(env2.CI);
1103
+ var cloudBaseUrl = (env2) => env2.PUCK_CLOUD_URL || DEFAULT_CLOUD_URL;
1104
+ var createRunContext = (deps, flags, argv, telemetry) => {
1102
1105
  const interactive = !flags.yes && !flags.json && deps.stdinIsTTY && Boolean(deps.stdout.isTTY) && !isCI(deps.env);
1103
1106
  const secrets = new SecretRegistry();
1104
- const baseUrl = deps.env.PUCK_CLOUD_URL || DEFAULT_CLOUD_URL;
1107
+ const baseUrl = cloudBaseUrl(deps.env);
1105
1108
  return {
1106
1109
  deps,
1107
1110
  flags,
@@ -1110,6 +1113,7 @@ var createRunContext = (deps, flags, argv) => {
1110
1113
  prompter: interactive ? deps.createPrompter() : nonInteractivePrompter,
1111
1114
  secrets,
1112
1115
  cloud: createCloudApi(baseUrl, deps.fetch),
1116
+ telemetry,
1113
1117
  log: (line) => {
1114
1118
  if (!flags.json) deps.stderr.write(secrets.scrub(line) + "\n");
1115
1119
  }
@@ -1175,6 +1179,10 @@ var COMMANDS2 = [
1175
1179
  {
1176
1180
  name: "docs <command>",
1177
1181
  description: "Read the docs for this version: ls, cat <page>, find <query>, grep <text>"
1182
+ },
1183
+ {
1184
+ name: "telemetry [status|enable|disable]",
1185
+ description: "Show or change anonymous usage data collection"
1178
1186
  }
1179
1187
  ];
1180
1188
  var HELP_TEXT = `Puck CLI: set up Puck and Puck Cloud.
@@ -2558,10 +2566,10 @@ var analyzeRoutes = (code, filename) => {
2558
2566
  const topLevel = new Set(exported.elements.filter(Boolean));
2559
2567
  walk(exported, (node) => {
2560
2568
  if (!isRouteCall(node, routeLocal)) return;
2561
- const path33 = stringArg(node, 0);
2569
+ const path34 = stringArg(node, 0);
2562
2570
  const isTop = topLevel.has(node);
2563
- calls.push({ path: path33, file: stringArg(node, 1), topLevel: isTop });
2564
- if (path33 === "*") {
2571
+ calls.push({ path: path34, file: stringArg(node, 1), topLevel: isTop });
2572
+ if (path34 === "*") {
2565
2573
  if (isTop) splat = node;
2566
2574
  else nestedSplat = true;
2567
2575
  }
@@ -3058,7 +3066,7 @@ var locate = (info) => (from) => {
3058
3066
  };
3059
3067
  var tanstackRelocation = (p, info) => {
3060
3068
  const to = locate(info);
3061
- const moduleId = (id) => to(`${id}.ts`).replace(/\.ts$/, "");
3069
+ const moduleId = (id2) => to(`${id2}.ts`).replace(/\.ts$/, "");
3062
3070
  return {
3063
3071
  moduleMap: {
3064
3072
  "src/lib/pages": moduleId("src/lib/pages"),
@@ -3485,9 +3493,9 @@ var planEnvLoading = (p, info) => {
3485
3493
  }
3486
3494
  );
3487
3495
  };
3488
- var serverPlanner = (id) => {
3489
- const recipe = id;
3490
- const aiRecipe = `${id}-ai`;
3496
+ var serverPlanner = (id2) => {
3497
+ const recipe = id2;
3498
+ const aiRecipe = `${id2}-ai`;
3491
3499
  const planEditor = (p, info) => {
3492
3500
  const dir = puckDir(p.vfs, p.ctx.root, info);
3493
3501
  const file = `${dir}/pages.ts`;
@@ -3738,7 +3746,7 @@ var SERVER_DEV_PACKAGES = [
3738
3746
  var locate2 = (info) => (from) => from.startsWith("src/") ? path12.posix.join(info.srcDir || ".", from.slice(4)) : from;
3739
3747
  var viteRelocation = (p, info) => {
3740
3748
  const to = locate2(info);
3741
- const moduleId = (id) => to(`${id}.ts`).replace(/\.ts$/, "");
3749
+ const moduleId = (id2) => to(`${id2}.ts`).replace(/\.ts$/, "");
3742
3750
  return {
3743
3751
  moduleMap: {
3744
3752
  "src/puck/pages": moduleId("src/puck/pages"),
@@ -5100,14 +5108,23 @@ var WORKSPACE_PROTOCOL = /^workspace:/;
5100
5108
  var transformPackageJson = (text, { appName, cliVersion }) => {
5101
5109
  const pkg = JSON.parse(text);
5102
5110
  pkg.name = appName;
5111
+ const pinned = [];
5103
5112
  for (const field of ["dependencies", "devDependencies"]) {
5104
5113
  const deps = pkg[field];
5105
5114
  if (!deps) continue;
5106
5115
  delete deps["eslint-config-custom"];
5107
5116
  for (const [name, range] of Object.entries(deps)) {
5108
- if (WORKSPACE_PROTOCOL.test(range)) deps[name] = `^${cliVersion}`;
5117
+ if (!WORKSPACE_PROTOCOL.test(range)) continue;
5118
+ deps[name] = `^${cliVersion}`;
5119
+ pinned.push(name);
5109
5120
  }
5110
5121
  }
5122
+ if (cliVersion.includes("-") && pinned.length > 0) {
5123
+ pkg.overrides = {
5124
+ ...pkg.overrides,
5125
+ ...Object.fromEntries(pinned.map((name) => [name, `$${name}`]))
5126
+ };
5127
+ }
5111
5128
  if (pkg.scripts?.lint === "eslint") delete pkg.scripts.lint;
5112
5129
  return JSON.stringify(pkg, null, 2) + "\n";
5113
5130
  };
@@ -5378,18 +5395,18 @@ var Planner = class {
5378
5395
  modifyFile(rel, content, opts) {
5379
5396
  const abs = this.abs(rel);
5380
5397
  this.vfs.write(abs, content);
5381
- const id = `${opts.capability}:modify:${rel}`;
5398
+ const id2 = `${opts.capability}:modify:${rel}`;
5382
5399
  const edits = (opts.inserted ?? []).map((e) => ({
5383
5400
  line: lineOf(content, e.at),
5384
5401
  insert: e.text
5385
5402
  }));
5386
- const existing = this.steps.find((s) => s.id === id);
5403
+ const existing = this.steps.find((s) => s.id === id2);
5387
5404
  if (existing && existing.kind === "modify_file") {
5388
5405
  existing.edits.push(...edits);
5389
5406
  return;
5390
5407
  }
5391
5408
  this.steps.push({
5392
- id,
5409
+ id: id2,
5393
5410
  kind: "modify_file",
5394
5411
  capability: opts.capability,
5395
5412
  summary: opts.summary,
@@ -5470,10 +5487,10 @@ var DEPENDS_ON = {
5470
5487
  };
5471
5488
  var resolveCapabilities = (requested) => {
5472
5489
  const ordered = [];
5473
- const visit = (id) => {
5474
- if (ordered.includes(id)) return;
5475
- DEPENDS_ON[id].forEach(visit);
5476
- ordered.push(id);
5490
+ const visit = (id2) => {
5491
+ if (ordered.includes(id2)) return;
5492
+ DEPENDS_ON[id2].forEach(visit);
5493
+ ordered.push(id2);
5477
5494
  };
5478
5495
  requested.forEach(visit);
5479
5496
  return ordered;
@@ -5484,13 +5501,13 @@ var planCapabilities = (p, capabilities) => {
5484
5501
  const status = capabilityStatus(p.state);
5485
5502
  const withAi = capabilities.includes("ai");
5486
5503
  let editorPlanned = false;
5487
- for (const id of capabilities) {
5488
- if (id === "editor") {
5504
+ for (const id2 of capabilities) {
5505
+ if (id2 === "editor") {
5489
5506
  if (status.editor.satisfied) continue;
5490
5507
  editorPlanned = true;
5491
5508
  adapter.planEditor(p, framework, withAi);
5492
5509
  }
5493
- if (id === "cloud") {
5510
+ if (id2 === "cloud") {
5494
5511
  if (p.backend?.mode === "external") {
5495
5512
  p.warn(
5496
5513
  "PUCK-CLI-W-EXTERNAL-BACKEND",
@@ -5512,7 +5529,7 @@ var planCapabilities = (p, capabilities) => {
5512
5529
  "The /api/puck route forwards requests to Puck Cloud using your API key. Add authentication before deploying."
5513
5530
  );
5514
5531
  }
5515
- if (id === "ai") {
5532
+ if (id2 === "ai") {
5516
5533
  if (adapter.kind === "server") continue;
5517
5534
  if (!p.state.ai.installed) {
5518
5535
  p.addDependency(
@@ -5769,7 +5786,8 @@ var clientPayload = (rc, info) => ({
5769
5786
  cliVersion: rc.deps.cliVersion,
5770
5787
  hostname: rc.deps.hostname.slice(0, 100),
5771
5788
  projectName: info.projectName?.slice(0, 100),
5772
- framework: info.framework
5789
+ framework: info.framework,
5790
+ anonymousId: rc.telemetry?.anonymousId ?? void 0
5773
5791
  });
5774
5792
  var onApproved = (rc, approved) => {
5775
5793
  const secret = secretFrom(rc, approved.apiKey, "Puck Cloud");
@@ -7378,15 +7396,15 @@ var NOTES = {
7378
7396
  hono: "Serves the APIs for an editor in another app",
7379
7397
  express: "Serves the APIs for an editor in another app"
7380
7398
  };
7381
- var frameworkSupport = () => FRAMEWORK_IDS.map((id) => {
7382
- const adapter = ADAPTERS[id];
7399
+ var frameworkSupport = () => FRAMEWORK_IDS.map((id2) => {
7400
+ const adapter = ADAPTERS[id2];
7383
7401
  return {
7384
- id,
7385
- name: FRAMEWORK_LABELS[id],
7386
- minVersion: MIN_VERSIONS[id],
7402
+ id: id2,
7403
+ name: FRAMEWORK_LABELS[id2],
7404
+ minVersion: MIN_VERSIONS[id2],
7387
7405
  kind: adapter.kind ?? "app",
7388
7406
  needsServer: Boolean(adapter.backend),
7389
- notes: NOTES[id]
7407
+ notes: NOTES[id2]
7390
7408
  };
7391
7409
  });
7392
7410
  var runFrameworks = async (_rc, positionals) => {
@@ -7402,6 +7420,214 @@ var runFrameworks = async (_rc, positionals) => {
7402
7420
  return result;
7403
7421
  };
7404
7422
 
7423
+ // src/telemetry/consent.ts
7424
+ import { randomUUID } from "crypto";
7425
+
7426
+ // src/telemetry/config.ts
7427
+ import fs6 from "fs";
7428
+ import path31 from "path";
7429
+ var TelemetryConfigStore = class {
7430
+ #file;
7431
+ constructor(configDir) {
7432
+ this.#file = path31.join(configDir, "puck", "telemetry.json");
7433
+ }
7434
+ get path() {
7435
+ return this.#file;
7436
+ }
7437
+ load() {
7438
+ try {
7439
+ const data = JSON.parse(fs6.readFileSync(this.#file, "utf8"));
7440
+ return data && typeof data === "object" ? data : {};
7441
+ } catch {
7442
+ return {};
7443
+ }
7444
+ }
7445
+ /** Throws if the config directory isn't writable */
7446
+ save(config) {
7447
+ fs6.mkdirSync(path31.dirname(this.#file), { recursive: true, mode: 448 });
7448
+ fs6.writeFileSync(this.#file, JSON.stringify(config, null, 2) + "\n", {
7449
+ mode: 384
7450
+ });
7451
+ }
7452
+ };
7453
+ var configDirFor = (env2, homedir) => env2.XDG_CONFIG_HOME || path31.join(homedir, ".config");
7454
+
7455
+ // src/telemetry/consent.ts
7456
+ var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
7457
+ var telemetryConsent = (env2, config) => {
7458
+ if (isTruthyEnv(env2.PUCK_TELEMETRY_DISABLED))
7459
+ return { enabled: false, reason: "PUCK_TELEMETRY_DISABLED" };
7460
+ if (isTruthyEnv(env2.DO_NOT_TRACK))
7461
+ return { enabled: false, reason: "DO_NOT_TRACK" };
7462
+ if (config.enabled === false) return { enabled: false, reason: "disabled" };
7463
+ return { enabled: true, reason: config.enabled ? "enabled" : "default" };
7464
+ };
7465
+ var loadTelemetry = (deps) => {
7466
+ const store = new TelemetryConfigStore(configDirFor(deps.env, deps.homedir));
7467
+ const debug = isTruthyEnv(deps.env.PUCK_TELEMETRY_DEBUG);
7468
+ const envOnly = telemetryConsent(deps.env, {});
7469
+ const config = envOnly.reason === "PUCK_TELEMETRY_DISABLED" || envOnly.reason === "DO_NOT_TRACK" ? {} : store.load();
7470
+ const consent = telemetryConsent(deps.env, config);
7471
+ const off = (reason) => ({
7472
+ enabled: false,
7473
+ reason,
7474
+ anonymousId: null,
7475
+ debug,
7476
+ store,
7477
+ config
7478
+ });
7479
+ if (!consent.enabled) return off(consent.reason);
7480
+ if (typeof config.anonymousId !== "string" || !UUID.test(config.anonymousId)) {
7481
+ config.anonymousId = randomUUID();
7482
+ try {
7483
+ store.save(config);
7484
+ } catch {
7485
+ return off("unwritable");
7486
+ }
7487
+ }
7488
+ return { ...consent, anonymousId: config.anonymousId, debug, store, config };
7489
+ };
7490
+
7491
+ // src/commands/telemetry.ts
7492
+ var SUBCOMMANDS2 = ["status", "enable", "disable"];
7493
+ var DISABLE = `\`${CANONICAL_INVOCATION} telemetry disable\``;
7494
+ var MESSAGES = {
7495
+ default: `Telemetry is on. Turn it off with ${DISABLE}.`,
7496
+ enabled: `Telemetry is on. Turn it off with ${DISABLE}.`,
7497
+ disabled: "Telemetry is off.",
7498
+ PUCK_TELEMETRY_DISABLED: "Telemetry is off because PUCK_TELEMETRY_DISABLED is set.",
7499
+ DO_NOT_TRACK: "Telemetry is off because DO_NOT_TRACK is set.",
7500
+ unwritable: "Telemetry is off because its config file can't be written."
7501
+ };
7502
+ var runTelemetry = async (rc, positionals) => {
7503
+ const [sub = "status", ...rest] = positionals;
7504
+ if (rest.length > 0 || !SUBCOMMANDS2.includes(sub)) {
7505
+ throw new CliError(
7506
+ "PUCK-CLI-INVALID-ARGS",
7507
+ `Usage: \`${CANONICAL_INVOCATION} telemetry [status|enable|disable]\`.`
7508
+ );
7509
+ }
7510
+ const { env: env2, homedir } = rc.deps;
7511
+ const store = new TelemetryConfigStore(configDirFor(env2, homedir));
7512
+ const config = store.load();
7513
+ const result = emptyResult("telemetry");
7514
+ if (sub !== "status") {
7515
+ const enabled = sub === "enable";
7516
+ result.changed = config.enabled !== enabled;
7517
+ config.enabled = enabled;
7518
+ if (!enabled) delete config.anonymousId;
7519
+ try {
7520
+ store.save(config);
7521
+ } catch (err) {
7522
+ throw new CliError(
7523
+ "PUCK-CLI-WRITE-FAILED",
7524
+ `Couldn't save ${store.path}: ${err.message}`
7525
+ );
7526
+ }
7527
+ }
7528
+ const consent = telemetryConsent(env2, config);
7529
+ result.telemetry = {
7530
+ ...consent,
7531
+ anonymousId: consent.enabled ? config.anonymousId ?? null : null
7532
+ };
7533
+ result.message = sub === "enable" && !consent.enabled ? `Telemetry is enabled in ${store.path}, but stays off: ${MESSAGES[consent.reason].replace("Telemetry is off because ", "")}` : MESSAGES[consent.reason];
7534
+ return result;
7535
+ };
7536
+
7537
+ // src/telemetry/event.ts
7538
+ var AGENTS = [
7539
+ ["CLAUDECODE", "claude-code"],
7540
+ ["CURSOR_AGENT", "cursor"],
7541
+ ["CODEX_SANDBOX", "codex"],
7542
+ ["CODEX_SANDBOX_NETWORK_DISABLED", "codex"],
7543
+ ["GEMINI_CLI", "gemini-cli"],
7544
+ ["OPENCODE", "opencode"]
7545
+ ];
7546
+ var detectAgent = (env2) => AGENTS.find(([key]) => env2[key] !== void 0 && env2[key] !== "")?.[1] ?? null;
7547
+ var id = (value) => value && /^[A-Za-z0-9._@:-]{1,64}$/.test(value) ? value : null;
7548
+ var ids = (values) => values.map(id).filter((v) => v !== null);
7549
+ var major = (version) => {
7550
+ const match = version?.match(/\d+/);
7551
+ return match ? Number(match[0]) : null;
7552
+ };
7553
+ var buildEvent = (input) => {
7554
+ const { result, flags } = input;
7555
+ const project = result.project;
7556
+ return {
7557
+ event: "cli_command",
7558
+ timestamp: new Date(input.now).toISOString(),
7559
+ command: input.command,
7560
+ capabilities: input.command === "add" ? CAPABILITY_IDS.filter((c) => input.positionals.includes(c)) : [],
7561
+ status: result.status,
7562
+ errorCode: id(result.error?.code),
7563
+ exitCode: input.exitCode,
7564
+ durationMs: Math.max(0, Math.round(input.durationMs)),
7565
+ dryRun: Boolean(flags.dryRun),
7566
+ changed: result.changed,
7567
+ actions: ids(result.actions.map((a) => a.type)),
7568
+ warnings: ids(result.warnings.map((w) => w.code)),
7569
+ cliVersion: id(input.cliVersion) ?? "unknown",
7570
+ os: id(input.platform) ?? "unknown",
7571
+ arch: id(input.arch) ?? "unknown",
7572
+ nodeVersion: id(input.nodeVersion) ?? "unknown",
7573
+ packageManager: project?.packageManager ?? flags.packageManager ?? null,
7574
+ ci: isCI(input.env),
7575
+ interactive: input.interactive,
7576
+ json: Boolean(flags.json),
7577
+ agent: detectAgent(input.env),
7578
+ framework: project?.framework ?? flags.framework ?? null,
7579
+ frameworkMajor: major(project?.frameworkVersion),
7580
+ monorepo: Boolean(project?.workspace),
7581
+ puck: Boolean(result.puck?.installed),
7582
+ cloud: Boolean(result.cloud?.installed),
7583
+ ai: Boolean(result.ai?.installed),
7584
+ backend: flags.backend ?? null
7585
+ };
7586
+ };
7587
+
7588
+ // src/telemetry/client.ts
7589
+ var TIMEOUT_MS2 = 1e3;
7590
+ var sendTelemetry = async (deps, baseUrl, telemetry, events) => {
7591
+ if (!telemetry.enabled || !telemetry.anonymousId) return;
7592
+ const body = JSON.stringify({ anonymousId: telemetry.anonymousId, events });
7593
+ if (telemetry.debug) {
7594
+ deps.stderr.write(`[telemetry] ${body}
7595
+ `);
7596
+ return;
7597
+ }
7598
+ try {
7599
+ await deps.fetch(
7600
+ new URL(
7601
+ "api/cli/telemetry",
7602
+ baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`
7603
+ ),
7604
+ {
7605
+ method: "POST",
7606
+ headers: { "content-type": "application/json" },
7607
+ body,
7608
+ signal: AbortSignal.timeout(TIMEOUT_MS2)
7609
+ }
7610
+ );
7611
+ } catch {
7612
+ }
7613
+ };
7614
+
7615
+ // src/telemetry/notice.ts
7616
+ var TELEMETRY_NOTICE = `Puck CLI collects anonymous usage data, like which commands run and whether they succeed. It never includes code, file paths, project names or API keys.
7617
+ To opt out, run \`${CANONICAL_INVOCATION} telemetry disable\` or set PUCK_TELEMETRY_DISABLED=1.
7618
+ Learn more: ${DOCS_URL}#telemetry
7619
+ `;
7620
+ var showTelemetryNotice = (deps, telemetry) => {
7621
+ if (!telemetry.enabled || telemetry.config.notifiedAt) return;
7622
+ deps.stderr.write(`${TELEMETRY_NOTICE}
7623
+ `);
7624
+ telemetry.config.notifiedAt = new Date(deps.now()).toISOString();
7625
+ try {
7626
+ telemetry.store.save(telemetry.config);
7627
+ } catch {
7628
+ }
7629
+ };
7630
+
7405
7631
  // src/cli.ts
7406
7632
  var exitCodeFor = (result) => {
7407
7633
  if (result.status === "error")
@@ -7426,15 +7652,42 @@ var errorResult = (command, err, dryRun = false) => {
7426
7652
  result.message = cliError.message;
7427
7653
  return result;
7428
7654
  };
7655
+ var recordRun = (deps, telemetry, startedAt, input) => {
7656
+ const now = deps.now();
7657
+ const event = buildEvent({
7658
+ ...input,
7659
+ durationMs: now - startedAt,
7660
+ env: deps.env,
7661
+ cliVersion: deps.cliVersion,
7662
+ platform: deps.platform,
7663
+ arch: deps.arch,
7664
+ nodeVersion: deps.nodeVersion,
7665
+ now
7666
+ });
7667
+ return sendTelemetry(deps, cloudBaseUrl(deps.env), telemetry, [event]);
7668
+ };
7429
7669
  var runCli = async (argv, deps) => {
7670
+ const startedAt = deps.now();
7430
7671
  let parsed;
7431
7672
  try {
7432
7673
  parsed = parseCliArgs(argv);
7433
7674
  } catch (err) {
7434
7675
  const result2 = errorResult("help", err);
7435
- if (wantsJson(argv)) presentJson(deps.stdout, result2, new SecretRegistry());
7676
+ const json = wantsJson(argv);
7677
+ if (json) presentJson(deps.stdout, result2, new SecretRegistry());
7436
7678
  else presentHuman(deps.stderr, result2, new SecretRegistry());
7437
- return exitCodeFor(result2);
7679
+ const exitCode2 = exitCodeFor(result2);
7680
+ if (argv[0] !== "telemetry") {
7681
+ await recordRun(deps, loadTelemetry(deps), startedAt, {
7682
+ command: null,
7683
+ positionals: [],
7684
+ flags: { json },
7685
+ result: result2,
7686
+ exitCode: exitCode2,
7687
+ interactive: false
7688
+ });
7689
+ }
7690
+ return exitCode2;
7438
7691
  }
7439
7692
  const { command, flags, positionals } = parsed;
7440
7693
  if (flags.version) {
@@ -7450,7 +7703,9 @@ var runCli = async (argv, deps) => {
7450
7703
  else deps.stdout.write(HELP_TEXT);
7451
7704
  return EXIT_CODES.success;
7452
7705
  }
7453
- const rc = createRunContext(deps, flags, argv);
7706
+ const telemetry = command === "telemetry" ? null : loadTelemetry(deps);
7707
+ const rc = createRunContext(deps, flags, argv, telemetry);
7708
+ if (telemetry && !flags.json) showTelemetryNotice(deps, telemetry);
7454
7709
  let result;
7455
7710
  try {
7456
7711
  if (command === "init") result = await runInit(rc);
@@ -7460,6 +7715,8 @@ var runCli = async (argv, deps) => {
7460
7715
  else if (command === "docs") result = await runDocs(rc, positionals);
7461
7716
  else if (command === "frameworks")
7462
7717
  result = await runFrameworks(rc, positionals);
7718
+ else if (command === "telemetry")
7719
+ result = await runTelemetry(rc, positionals);
7463
7720
  else result = await runDoctor(rc);
7464
7721
  } catch (err) {
7465
7722
  result = errorResult(command, err, flags.dryRun);
@@ -7471,8 +7728,19 @@ var runCli = async (argv, deps) => {
7471
7728
  result,
7472
7729
  rc.secrets
7473
7730
  );
7731
+ const exitCode = exitCodeFor(result);
7732
+ if (telemetry) {
7733
+ await recordRun(deps, telemetry, startedAt, {
7734
+ command,
7735
+ positionals,
7736
+ flags,
7737
+ result,
7738
+ exitCode,
7739
+ interactive: rc.interactive
7740
+ });
7741
+ }
7474
7742
  if (result.status === "success" && rc.afterOutput) await rc.afterOutput();
7475
- return exitCodeFor(result);
7743
+ return exitCode;
7476
7744
  };
7477
7745
 
7478
7746
  // src/io/runner.ts
@@ -7562,8 +7830,8 @@ var runDevServer = (spec, onReady) => new Promise((resolve) => {
7562
7830
  });
7563
7831
 
7564
7832
  // src/docs/source.ts
7565
- import fs6 from "fs";
7566
- import path31 from "path";
7833
+ import fs7 from "fs";
7834
+ import path32 from "path";
7567
7835
  var DirDocsSource = class {
7568
7836
  #dir;
7569
7837
  constructor(dir) {
@@ -7571,21 +7839,21 @@ var DirDocsSource = class {
7571
7839
  }
7572
7840
  list() {
7573
7841
  return JSON.parse(
7574
- fs6.readFileSync(path31.join(this.#dir, "index.json"), "utf8")
7842
+ fs7.readFileSync(path32.join(this.#dir, "index.json"), "utf8")
7575
7843
  );
7576
7844
  }
7577
7845
  read(page) {
7578
- return fs6.readFileSync(path31.join(this.#dir, `${page}.md`), "utf8");
7846
+ return fs7.readFileSync(path32.join(this.#dir, `${page}.md`), "utf8");
7579
7847
  }
7580
7848
  };
7581
7849
 
7582
7850
  // src/bin.ts
7583
- var distDir = path32.dirname(fileURLToPath(import.meta.url));
7584
- var templatesDir = path32.join(distDir, "templates");
7851
+ var distDir = path33.dirname(fileURLToPath(import.meta.url));
7852
+ var templatesDir = path33.join(distDir, "templates");
7585
7853
  var templates = new DirTemplateSource(templatesDir, {
7586
7854
  gitignoreName: "_gitignore",
7587
7855
  manifest: () => JSON.parse(
7588
- fs7.readFileSync(path32.join(templatesDir, "manifest.json"), "utf8")
7856
+ fs8.readFileSync(path33.join(templatesDir, "manifest.json"), "utf8")
7589
7857
  )
7590
7858
  });
7591
7859
  var env = { ...process.env };
@@ -7595,16 +7863,19 @@ runCli(process.argv.slice(2), {
7595
7863
  stdout: process.stdout,
7596
7864
  stderr: process.stderr,
7597
7865
  stdinIsTTY: Boolean(process.stdin.isTTY),
7598
- cliVersion: "0.24.0-canary.6f40e09b",
7866
+ cliVersion: "0.24.0-canary.b7903763",
7599
7867
  runner: createRunner(env),
7600
7868
  fetch: globalThis.fetch,
7601
7869
  openUrl,
7602
7870
  runDevServer,
7603
7871
  createPrompter: () => createInquirerPrompter(process.stderr),
7604
7872
  templates,
7605
- docs: new DirDocsSource(path32.join(distDir, "docs")),
7873
+ docs: new DirDocsSource(path33.join(distDir, "docs")),
7606
7874
  homedir: os.homedir(),
7607
7875
  hostname: os.hostname(),
7876
+ platform: process.platform,
7877
+ arch: process.arch,
7878
+ nodeVersion: process.versions.node,
7608
7879
  now: () => Date.now(),
7609
7880
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
7610
7881
  }).then(
package/dist/docs/cli.md CHANGED
@@ -164,6 +164,7 @@ npx skills add puckeditor/skills --skill puck
164
164
  | `doctor` | Diagnose problems and suggest fixes. Never makes changes |
165
165
  | `frameworks` | Show the supported frameworks and versions |
166
166
  | `docs` | Read these docs: `ls`, `cat <page>`, `find <query>`, `grep <text>` |
167
+ | `telemetry` | Show or change anonymous usage data collection |
167
168
 
168
169
  ## Flags
169
170
 
@@ -209,3 +210,26 @@ The `/api/puck` route and the editor are public by default. Add authentication b
209
210
  ## Puck AI
210
211
 
211
212
  `init` and `add ai` add the Puck AI plugin to the editor, allow design mode in the `/api/puck` route, and wrap your config with `withDynamicConfig` so components designed by Puck AI render on your pages. If your editor has been customised, the CLI leaves it alone and prints the code to add.
213
+
214
+ ## Telemetry
215
+
216
+ The CLI collects anonymous usage data to help us improve it. The first time it runs without `--json`, it prints a notice.
217
+
218
+ Each command sends one event to Puck Cloud with:
219
+
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
+ - Whether it was a dry run, made changes, ran interactively, used `--json` or ran in CI
222
+ - The CLI version, operating system, CPU architecture and Node.js version
223
+ - The name of the coding agent running it, if it's a known one, such as `claude-code`
224
+ - 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
+ - A random ID, stored in `~/.config/puck/telemetry.json`
226
+
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
+
229
+ To turn telemetry off, run:
230
+
231
+ ```sh
232
+ npx @puckeditor/cli telemetry disable
233
+ ```
234
+
235
+ 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@puckeditor/cli",
3
- "version": "0.24.0-canary.6f40e09b",
3
+ "version": "0.24.0-canary.b7903763",
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": {