@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 +4 -1
- package/dist/bin.mjs +334 -63
- package/dist/docs/cli.md +24 -0
- package/package.json +1 -1
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
|
|
6
|
-
import
|
|
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 = (
|
|
305
|
+
var unsupportedVersion = (id2, version, range) => {
|
|
306
306
|
const found = versionOf(version) ?? versionOf(range);
|
|
307
|
-
const [
|
|
308
|
-
if (!found || found[0] >
|
|
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[
|
|
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[
|
|
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[
|
|
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
|
|
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:
|
|
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
|
|
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 = (
|
|
578
|
-
const version = resolveInstalledVersion(vfs, root,
|
|
579
|
-
const tooOld = unsupportedVersion(
|
|
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
|
-
|
|
1099
|
-
|
|
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
|
|
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
|
|
2569
|
+
const path34 = stringArg(node, 0);
|
|
2562
2570
|
const isTop = topLevel.has(node);
|
|
2563
|
-
calls.push({ path:
|
|
2564
|
-
if (
|
|
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 = (
|
|
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 = (
|
|
3489
|
-
const recipe =
|
|
3490
|
-
const aiRecipe = `${
|
|
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 = (
|
|
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))
|
|
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
|
|
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 ===
|
|
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 = (
|
|
5474
|
-
if (ordered.includes(
|
|
5475
|
-
DEPENDS_ON[
|
|
5476
|
-
ordered.push(
|
|
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
|
|
5488
|
-
if (
|
|
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 (
|
|
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 (
|
|
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((
|
|
7382
|
-
const adapter = ADAPTERS[
|
|
7399
|
+
var frameworkSupport = () => FRAMEWORK_IDS.map((id2) => {
|
|
7400
|
+
const adapter = ADAPTERS[id2];
|
|
7383
7401
|
return {
|
|
7384
|
-
id,
|
|
7385
|
-
name: FRAMEWORK_LABELS[
|
|
7386
|
-
minVersion: MIN_VERSIONS[
|
|
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[
|
|
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
|
-
|
|
7676
|
+
const json = wantsJson(argv);
|
|
7677
|
+
if (json) presentJson(deps.stdout, result2, new SecretRegistry());
|
|
7436
7678
|
else presentHuman(deps.stderr, result2, new SecretRegistry());
|
|
7437
|
-
|
|
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
|
|
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
|
|
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
|
|
7566
|
-
import
|
|
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
|
-
|
|
7842
|
+
fs7.readFileSync(path32.join(this.#dir, "index.json"), "utf8")
|
|
7575
7843
|
);
|
|
7576
7844
|
}
|
|
7577
7845
|
read(page) {
|
|
7578
|
-
return
|
|
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 =
|
|
7584
|
-
var templatesDir =
|
|
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
|
-
|
|
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.
|
|
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(
|
|
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.
|
|
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": {
|