@debugkit/cli 0.6.1 → 0.7.0

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.
Files changed (3) hide show
  1. package/README.md +10 -10
  2. package/dist/cli.js +220 -81
  3. package/package.json +4 -4
package/README.md CHANGED
@@ -8,25 +8,25 @@ npx @debugkit/cli init
8
8
 
9
9
  Once `@debugkit/sdk` is installed in the app, the shorter `npx debugkit init` works too: the SDK includes a `debugkit` command that runs this CLI at the same version.
10
10
 
11
- Run it from your app's folder. It walks you through these steps:
11
+ Run it from your app's folder. It runs these steps in order, start to finish. Nothing asks you to stop part-way:
12
12
 
13
- 1. **Detects your app:** Expo, React Native, Next.js, TanStack Start, React (Vite) or Node. It installs `@debugkit/sdk` if it's missing.
13
+ 1. **Detects your app:** Expo, React Native, Next.js, TanStack Start, React (Vite) or Node. It installs `@debugkit/sdk` if it's missing, and on React Native and Expo the native modules it reads device details with (`react-native-device-info`; `expo-device` and `expo-application` on Expo).
14
14
  2. **Asks where your data should live:**
15
15
  - **Firebase:** a Cloud Function and Firestore.
16
16
  - **AWS:** a Lambda with a public URL and DynamoDB.
17
17
  - **Just this machine:** no cloud, for a first look.
18
- 3. **Signs you in and sets everything up in your own account.**
18
+ 3. **Asks how long to keep raw events:** 30, 60 (default), 90, 180 or 365 days, or any number, with a rough storage cost. Counts, issues and release health are kept forever. You can change it later on the dashboard's Settings page.
19
+ 4. **Signs you in and sets up ingest in your own account.**
19
20
  - **Firebase:** you sign in with Google in your browser, then pick or create a project. The CLI creates the Firestore database, deploys the indexes and the expiry on raw events, and deploys the ingest function. Cloud Functions need the Blaze plan, so it opens the billing page if you need to upgrade.
20
- - **AWS:** you use an existing profile or sign in with AWS SSO in your browser, so you don't paste any access keys. The CLI creates the DynamoDB table, a Lambda with a public URL, an IAM role that can only write to the table, and a read-only policy for hosting the dashboard later.
21
- 4. **Asks how long to keep raw events:** 30, 60 (default), 90, 180 or 365 days, or any number, with a rough storage cost. Counts, issues and release health are kept forever. You can change it later on the dashboard's Settings page.
22
- 5. **Wires up your app.** It writes the endpoint and ingest key to `.env` (or into the code for bare React Native), creates `debug.ts`, and tells you the one or two lines left to add.
23
- 6. **Opens your dashboard,** connected to your data and still empty, behind a login you choose.
24
- 7. **Walks you through it:**
21
+ - **AWS:** you use an existing profile or sign in with AWS SSO in your browser, so you don't paste any access keys. The CLI creates the DynamoDB table, a Lambda with a public URL, an IAM role that can only write to the table, and a read-only policy for the dashboard.
22
+ 5. **Asks for the dashboard login** you'll sign in with.
23
+ 6. **Offers to host the dashboard** in the same Firebase project or AWS account, straight after ingest, at a link you can share with your team. "Skip for now" carries on with the setup; host it later with `npx debugkit deploy-dashboard`. If the deploy fails, you can retry or skip, and setup still finishes.
24
+ 7. **Wires up your app.** It writes the endpoint and ingest key to `.env` (or into the code for bare React Native), creates `debug.ts`, and tells you the one or two lines left to add.
25
+ 8. **Walks you through the dashboard,** on the hosted one when it's up, or locally otherwise:
25
26
  - what each part of the dashboard will show;
26
27
  - a test event, sent through the real ingest so you watch it arrive;
27
28
  - what the SDK records on its own;
28
29
  - what you add in your own try/catches.
29
- 8. **Offers to host the dashboard** in the same Firebase project or AWS account, at a link you can share with your team. Say no and do it later with `npx debugkit deploy-dashboard`.
30
30
 
31
31
  ## Hosting the dashboard for your team
32
32
 
@@ -74,7 +74,7 @@ npx debugkit init --env preview # e.g. into your staging Firebase project
74
74
  npx debugkit init --env production # into the production one
75
75
  ```
76
76
 
77
- Each environment gets its own provider, project, endpoint, ingest key and dashboard login. They're
77
+ Each environment gets its own provider, project, endpoint, ingest key and dashboard login. `init` enforces it: picking a Firebase project (or a DynamoDB table in the same account and region) that another environment already uses is refused, and you pick again, so preview data never mixes with production. They're
78
78
  saved under `environments` in `.debugkit/config.json`, with `.debugkit/dashboard.<env>.env`.
79
79
 
80
80
  - **Expo apps with EAS:** for `development`, `preview` and `production`, the CLI offers to put
package/dist/cli.js CHANGED
@@ -173,6 +173,15 @@ function readConfig(cwd) {
173
173
  if (current) return f.environments?.[current];
174
174
  return f.provider ? f : void 0;
175
175
  }
176
+ function usedByAnotherEnvironment(cwd, uses) {
177
+ const f = readFile(cwd);
178
+ if (!f) return void 0;
179
+ if (current !== void 0 && f.provider && uses(f)) return "the default setup";
180
+ for (const [name, cfg] of Object.entries(f.environments ?? {})) if (name !== current && uses(cfg)) return `the ${name} environment`;
181
+ return void 0;
182
+ }
183
+ var firebaseProjectUsedBy = (cwd, projectId) => usedByAnotherEnvironment(cwd, (c) => c.provider === "firebase" && c.firebase?.projectId === projectId);
184
+ var dynamoTableUsedBy = (cwd, table, region, account) => usedByAnotherEnvironment(cwd, (c) => c.provider === "aws" && c.aws?.table === table && c.aws.region === region && (!c.aws.account || c.aws.account === account));
176
185
  function listEnvironments(cwd) {
177
186
  return Object.keys(readFile(cwd)?.environments ?? {});
178
187
  }
@@ -230,7 +239,7 @@ function ensureGitignored(cwd, entry) {
230
239
  import * as p from "@clack/prompts";
231
240
  import pc from "picocolors";
232
241
  var flags = { yes: false, command: "init" };
233
- function bail(message = flags.command === "init" ? "Setup cancelled. Run npx debugkit init again whenever you're ready." : "Stopped.") {
242
+ function bail(message = flags.command === "init" ? `Setup cancelled. Run ${cmdFor("init")} again whenever you're ready.` : "Stopped.") {
234
243
  p.cancel(message);
235
244
  process.exit(0);
236
245
  }
@@ -253,14 +262,18 @@ async function yes(message, initial = true) {
253
262
  }
254
263
  async function next(message = "Continue") {
255
264
  if (flags.yes) return;
256
- must(await p.confirm({ message, active: "Next", inactive: "Stop here", initialValue: true })) || bail("Stopped the walkthrough. Run npx debugkit guide to pick it up again.");
265
+ if (flags.command === "init") {
266
+ must(await p.select({ message, options: [{ value: "next", label: "Next" }] }));
267
+ return;
268
+ }
269
+ must(await p.confirm({ message, active: "Next", inactive: "Stop here", initialValue: true })) || bail(`Stopped the walkthrough. Run ${cmdFor("guide")} to pick it up again.`);
257
270
  }
258
271
  var code = (s) => pc.cyan(s);
259
272
  var dim = (s) => pc.dim(s);
260
273
  var bold = (s) => pc.bold(s);
261
274
 
262
275
  // src/dashboard.ts
263
- var VERSION = true ? "0.6.1" : "0.0.0-dev";
276
+ var VERSION = true ? "0.7.0" : "0.0.0-dev";
264
277
  var DASHBOARD_VERSION = VERSION;
265
278
  function hashPassword(password2) {
266
279
  const salt = randomBytes(16);
@@ -491,10 +504,17 @@ async function setupAws(ctx) {
491
504
  p.log.success(`Signed in to AWS account ${code(identity.Account ?? "?")} ${dim(identity.Arn ?? "")}`);
492
505
  if (!identity.Account) bail("AWS didn't say which account these credentials belong to.");
493
506
  const account = identity.Account;
507
+ const takenBy = (t) => dynamoTableUsedBy(ctx.app.cwd, t, region, account);
494
508
  const table = await ask("DynamoDB table name", {
495
509
  initial: environment.get() ? `debugkit-${environment.get()}` : "debugkit",
496
- validate: (v) => /^[A-Za-z0-9_.-]{3,40}$/.test(v) ? void 0 : "3\u201340 characters: letters, digits, _ . -"
510
+ validate: (v) => {
511
+ if (!/^[A-Za-z0-9_.-]{3,40}$/.test(v)) return "3\u201340 characters: letters, digits, _ . -";
512
+ const owner = takenBy(v);
513
+ return owner ? `${owner} already uses ${v} in ${region}. Each environment needs its own table.` : void 0;
514
+ }
497
515
  });
516
+ const tableOwner = takenBy(table);
517
+ if (tableOwner) bail(`${table} in ${region} is already ${tableOwner}'s table. Each environment needs its own table: run again without --yes and pick another name.`);
498
518
  const functionName = `debugkit-ingest-${table}`.slice(0, 64);
499
519
  const roleName = `debugkit-ingest-${table}-${region}`.slice(0, 64);
500
520
  await next(`Create the table, role and function in ${region}`);
@@ -542,7 +562,7 @@ async function setupAws(ctx) {
542
562
  active = (await ddb.send(new ddbMod.DescribeTableCommand({ TableName: table }))).Table?.TableStatus === "ACTIVE";
543
563
  if (!active) await sleep(2e3);
544
564
  }
545
- if (!active) throw new Error(`Table ${table} didn't become active within 3 minutes. Check it in the AWS console, then run npx debugkit init again.`);
565
+ if (!active) throw new Error(`Table ${table} didn't become active within 3 minutes. Check it in the AWS console, then run ${cmdFor("init")} again.`);
546
566
  }
547
567
  if (!tableArn) throw new Error(`AWS didn't return the ARN for table ${table}.`);
548
568
  const ttl = (await ddb.send(new ddbMod.DescribeTimeToLiveCommand({ TableName: table }))).TimeToLiveDescription;
@@ -673,7 +693,7 @@ async function setupAws(ctx) {
673
693
  readOnlyPolicyArn = void 0;
674
694
  }
675
695
  return {
676
- config: { provider: "aws", endpoint: url.replace(/\/$/, ""), ingestKey: ctx.ingestKey, aws: { region, profile, table, functionName, roleName, readOnlyPolicyArn } },
696
+ config: { provider: "aws", endpoint: url.replace(/\/$/, ""), ingestKey: ctx.ingestKey, aws: { region, profile, table, functionName, roleName, readOnlyPolicyArn, account } },
677
697
  dashboardEnv: { DEBUG_STORE: "dynamodb", AWS_REGION: region, DEBUG_DYNAMO_TABLE: table, ...profile ? { AWS_PROFILE: profile } : {}, ...adminEnv(url, ctx) },
678
698
  created: [
679
699
  `DynamoDB table ${code(table)} in ${region}${ownTable ? " (on-demand)" : " (your existing table)"}`,
@@ -742,7 +762,7 @@ async function setupFirebase(ctx) {
742
762
  let account;
743
763
  if (!accounts.length) {
744
764
  await next("Open the Google sign-in page");
745
- if (await fbLive(["login"]) !== 0) bail("Firebase sign-in didn't finish. Run npx debugkit init to try again.");
765
+ if (await fbLive(["login"]) !== 0) bail(`Firebase sign-in didn't finish. Run ${cmdFor("init")} to try again.`);
746
766
  accounts = emailsIn((await fb(["login:list"])).stdout);
747
767
  }
748
768
  const ADD = "__add__";
@@ -768,19 +788,33 @@ async function setupFirebase(ctx) {
768
788
  p.log.warn(`Couldn't read the project list: ${dim(list.stderr.slice(-300))}`);
769
789
  }
770
790
  const NEW = "__new__";
771
- let projectId = await choose(
772
- "Which Firebase project should deBug use?",
773
- [
774
- { value: NEW, label: "Create a new project", hint: "recommended: keeps deBug's data and bill separate" },
775
- ...projects.map((x) => ({ value: x.projectId, label: x.displayName ? `${x.displayName}` : x.projectId, hint: x.projectId }))
776
- ],
777
- NEW
778
- );
791
+ const takenBy = (id) => firebaseProjectUsedBy(ctx.app.cwd, id);
792
+ let projectId;
793
+ for (; ; ) {
794
+ projectId = await choose(
795
+ "Which Firebase project should deBug use?",
796
+ [
797
+ { value: NEW, label: "Create a new project", hint: "recommended: keeps deBug's data and bill separate" },
798
+ ...projects.map((x) => {
799
+ const owner2 = takenBy(x.projectId);
800
+ return { value: x.projectId, label: x.displayName ? `${x.displayName}` : x.projectId, hint: owner2 ? `${x.projectId}, used by ${owner2}` : x.projectId };
801
+ })
802
+ ],
803
+ NEW
804
+ );
805
+ const owner = projectId === NEW ? void 0 : takenBy(projectId);
806
+ if (!owner) break;
807
+ p.log.warn(`${bold(projectId)} is already ${owner}'s project. Each environment needs its own Firebase project, so their data never mixes. Pick another project, or create one.`);
808
+ }
779
809
  if (projectId === NEW) {
780
810
  const suggested = `${ctx.app.appId}-debug`.slice(0, 26).replace(/-+$/, "") + `-${Math.random().toString(36).slice(2, 6)}`;
781
811
  projectId = await ask("Project id (lowercase, globally unique)", {
782
812
  initial: suggested,
783
- validate: (v) => /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/.test(v) ? void 0 : "6\u201330 characters: lowercase letters, digits and dashes"
813
+ validate: (v) => {
814
+ if (!/^[a-z][a-z0-9-]{4,28}[a-z0-9]$/.test(v)) return "6\u201330 characters: lowercase letters, digits and dashes";
815
+ const owner = takenBy(v);
816
+ return owner ? `${owner} already uses ${v}. Each environment needs its own Firebase project.` : void 0;
817
+ }
784
818
  });
785
819
  if (await fbLive(["projects:create", projectId, "--display-name", `${ctx.app.name} deBug`.slice(0, 30), ...acct]) !== 0)
786
820
  bail(`Couldn't create ${projectId}. Pick an existing project or another id.`);
@@ -810,7 +844,7 @@ async function setupFirebase(ctx) {
810
844
  if (r.code !== 0 && !/already exists/i.test(r.stderr + r.stdout)) {
811
845
  s.error("Couldn't create the database");
812
846
  p.log.error((r.stderr || r.stdout).slice(-600));
813
- bail("Fix the error above (often: the Firestore API needs enabling, or billing), then run npx debugkit init again.");
847
+ bail(`Fix the error above (often: the Firestore API needs enabling, or billing), then run ${cmdFor("init")} again.`);
814
848
  }
815
849
  s.stop(`Created the Firestore database (${location2})`);
816
850
  }
@@ -853,7 +887,7 @@ async function setupFirebase(ctx) {
853
887
  ],
854
888
  "retry"
855
889
  );
856
- if (again === "stop") bail(`Fix the error above, then run npx debugkit init again (it reuses what's already set up), or deploy by hand: cd ${paths(ctx.app.cwd).firebase} && npx firebase-tools@latest deploy --only functions:${CODEBASE} --project ${projectId}`);
890
+ if (again === "stop") bail(`Fix the error above, then run ${cmdFor("init")} again (it reuses what's already set up), or deploy by hand: cd ${paths(ctx.app.cwd).firebase} && npx firebase-tools@latest deploy --only functions:${CODEBASE} --project ${projectId}`);
857
891
  if (again === "billing") {
858
892
  openUrl(`https://console.firebase.google.com/project/${projectId}/usage/details`);
859
893
  await next("Upgraded: retry the deploy");
@@ -995,7 +1029,7 @@ function hostedEnv(local, url, extra = {}) {
995
1029
  const plain = { DEBUG_DASHBOARD_URL: url, ...extra };
996
1030
  const secret = {};
997
1031
  for (const k of SHARED) if (local[k]) (SECRET.has(k) ? secret : plain)[k] = local[k];
998
- if (!secret.DEBUG_SESSION_SECRET || !secret.DEBUG_DASHBOARD_USERS) throw new Error("The dashboard login isn't set up yet. Run npx debugkit init (or npx debugkit password) first.");
1032
+ if (!secret.DEBUG_SESSION_SECRET || !secret.DEBUG_DASHBOARD_USERS) throw new Error(`The dashboard login isn't set up yet. Run ${cmdFor("init")} (or ${cmdFor("password")}) first.`);
999
1033
  return { plain, secret };
1000
1034
  }
1001
1035
  var dotenv = (values) => Object.entries(values).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("\n") + "\n";
@@ -1043,9 +1077,21 @@ async function waitLive(url, ms = 12e4) {
1043
1077
  }
1044
1078
  return false;
1045
1079
  }
1046
- async function hostDashboard(cwd, cfg) {
1080
+ function skipOrStop(opts, message) {
1081
+ if (opts.onProblem === "skip") {
1082
+ p.log.info(`${message} Host it any time with ${code(cmdFor("deploy-dashboard"))}.`);
1083
+ return void 0;
1084
+ }
1085
+ bail(message);
1086
+ }
1087
+ function fail(opts, message) {
1088
+ if (opts.onProblem === "skip") throw new Error(message);
1089
+ bail(message);
1090
+ }
1091
+ async function hostDashboard(cwd, cfg, opts = {}) {
1047
1092
  const local = readEnv(paths(cwd).dashboardEnv);
1048
- const out = cfg.provider === "firebase" ? await hostFirebase(cwd, cfg, local) : cfg.provider === "aws" ? await hostAws(cfg, local) : bail("The dashboard can only be hosted on Firebase or AWS. On this setup, run it locally.");
1093
+ const out = cfg.provider === "firebase" ? await hostFirebase(cwd, cfg, local, opts) : cfg.provider === "aws" ? await hostAws(cfg, local, opts) : bail("The dashboard can only be hosted on Firebase or AWS. On this setup, run it locally.");
1094
+ if (!out) return void 0;
1049
1095
  if (cfg.firebase?.account) {
1050
1096
  if (!local.DEBUGKIT_FIREBASE_ACCOUNT) upsertEnv(paths(cwd).dashboardEnv, { DEBUGKIT_FIREBASE_ACCOUNT: cfg.firebase.account });
1051
1097
  const { account: _a, ...firebase } = cfg.firebase;
@@ -1055,9 +1101,10 @@ async function hostDashboard(cwd, cfg) {
1055
1101
  await linkAlerts(local, cfg.appId, out.hosted.url);
1056
1102
  const s = p.spinner();
1057
1103
  s.start(`Checking ${out.hosted.url}`);
1058
- if (await waitLive(out.hosted.url)) s.stop(`The dashboard is live at ${code(out.hosted.url)}`);
1104
+ const live = await waitLive(out.hosted.url);
1105
+ if (live) s.stop(`The dashboard is live at ${code(out.hosted.url)}`);
1059
1106
  else s.error(`${out.hosted.url} didn't answer yet. New deploys can take a minute; open it again shortly.`);
1060
- return { url: out.hosted.url, created: out.created };
1107
+ return { url: out.hosted.url, created: out.created, live };
1061
1108
  }
1062
1109
  var SITE_ID = /^[a-z0-9](?:[a-z0-9-]{2,61}[a-z0-9])$/;
1063
1110
  async function listSites(fb, proj) {
@@ -1067,7 +1114,7 @@ async function listSites(fb, proj) {
1067
1114
  async function readOnlyServiceAccount(projectId) {
1068
1115
  const email = `${SA_NAME}@${projectId}.iam.gserviceaccount.com`;
1069
1116
  if (!which("gcloud")) {
1070
- p.log.warn(`gcloud isn't installed, so the dashboard runs as the project's default service account (which can write). Install gcloud and run ${code("npx debugkit deploy-dashboard")} again to lock it to read-only.`);
1117
+ p.log.warn(`gcloud isn't installed, so the dashboard runs as the project's default service account (which can write). Install gcloud and run ${code(cmdFor("deploy-dashboard"))} again to lock it to read-only.`);
1071
1118
  return void 0;
1072
1119
  }
1073
1120
  const g2 = (args) => capture("gcloud", [...args, "--project", projectId, "--quiet"]);
@@ -1135,8 +1182,8 @@ function writeHostingConfig(dir, site, region) {
1135
1182
  ]
1136
1183
  }));
1137
1184
  }
1138
- async function hostFirebase(cwd, cfg, local) {
1139
- const fbc = cfg.firebase ?? bail("This setup has no Firebase project saved. Run npx debugkit init again.");
1185
+ async function hostFirebase(cwd, cfg, local, opts) {
1186
+ const fbc = cfg.firebase ?? fail(opts, `This setup has no Firebase project saved. Run ${cmdFor("init")} again.`);
1140
1187
  const [fbCmd, fbPre] = await firebaseCli();
1141
1188
  const account = local.DEBUGKIT_FIREBASE_ACCOUNT || fbc.account;
1142
1189
  const acct = account ? ["--account", account] : [];
@@ -1144,7 +1191,7 @@ async function hostFirebase(cwd, cfg, local) {
1144
1191
  const fb = (args, o = {}) => capture(fbCmd, [...fbPre, ...args], o);
1145
1192
  const fbLive = (args, o = {}) => interactive(fbCmd, [...fbPre, ...args], o);
1146
1193
  const dir = paths(cwd).firebase;
1147
- if (!existsSync5(join5(dir, "firebase.json"))) bail(`${dir} is missing. Run ${code("npx debugkit init")} again to recreate it.`);
1194
+ if (!existsSync5(join5(dir, "firebase.json"))) fail(opts, `${dir} is missing. Run ${cmdFor("init")} again to recreate it.`);
1148
1195
  const s = p.spinner();
1149
1196
  s.start("Finding a Hosting site for the dashboard");
1150
1197
  const sites = await listSites(fb, proj);
@@ -1166,7 +1213,7 @@ async function hostFirebase(cwd, cfg, local) {
1166
1213
  }
1167
1214
  if (!site) {
1168
1215
  s.error("Couldn't find a free Hosting site name");
1169
- bail(`Create one in the Firebase console (Hosting \u2192 Add another site), then run ${code("npx debugkit deploy-dashboard")}.`);
1216
+ return skipOrStop(opts, "Create a site in the Firebase console (Hosting \u2192 Add another site).");
1170
1217
  }
1171
1218
  const url = `https://${site}.web.app`;
1172
1219
  s.stop(`Hosting site ${code(site)}: ${url}`);
@@ -1199,7 +1246,7 @@ async function hostFirebase(cwd, cfg, local) {
1199
1246
  ].join("\n"),
1200
1247
  "About to host the dashboard"
1201
1248
  );
1202
- if (!await yes(`Host the dashboard in ${fbc.projectId}?`)) bail("Nothing was deployed. The dashboard still runs locally with npx debugkit dashboard.");
1249
+ if (!opts.confirmed && !await yes(`Host the dashboard in ${fbc.projectId}?`)) return skipOrStop(opts, `Skipped hosting: the dashboard still runs locally with ${cmdFor("dashboard")}.`);
1203
1250
  writeFileSync3(join5(dir, "firestore.indexes.json"), JSON.stringify(firestore_indexes_default, null, 2) + "\n");
1204
1251
  p.log.step("Adding any Firestore indexes this version of deBug needs (existing ones are left alone)");
1205
1252
  if (await fbLive(["deploy", "--only", "firestore:indexes", "--non-interactive", ...proj], { cwd: dir }) !== 0)
@@ -1214,11 +1261,11 @@ async function hostFirebase(cwd, cfg, local) {
1214
1261
  // Hosting can't reach functions in some regions (africa-south1, for one): a plain retry fails the same way.
1215
1262
  ...region !== "us-central1" ? [{ value: "us", label: "Retry with the function in us-central1", hint: "the usual fix when Hosting can't reach the function's region" }] : [],
1216
1263
  { value: "retry", label: "Retry as it is" },
1217
- { value: "stop", label: "Stop here" }
1264
+ { value: "giveUp", label: opts.onProblem === "skip" ? "Skip hosting for now" : "Stop here" }
1218
1265
  ],
1219
1266
  region !== "us-central1" ? "us" : "retry"
1220
1267
  );
1221
- if (choice === "stop") bail(`Fix the error above, then run ${code("npx debugkit deploy-dashboard")}.`);
1268
+ if (choice === "giveUp") return skipOrStop(opts, "The dashboard isn't hosted yet: fix the error above.");
1222
1269
  if (choice === "us") {
1223
1270
  region = "us-central1";
1224
1271
  write();
@@ -1258,9 +1305,9 @@ async function dashboardZip() {
1258
1305
  rmSync(dir, { recursive: true, force: true });
1259
1306
  }
1260
1307
  }
1261
- async function hostAws(cfg, local) {
1262
- const aws = cfg.aws ?? bail("This setup has no AWS details saved. Run npx debugkit init again.");
1263
- if (!aws.readOnlyPolicyArn) bail("The read-only policy for the dashboard is missing. Run npx debugkit init again (it adds it), then npx debugkit deploy-dashboard.");
1308
+ async function hostAws(cfg, local, opts) {
1309
+ const aws = cfg.aws ?? fail(opts, `This setup has no AWS details saved. Run ${cmdFor("init")} again.`);
1310
+ if (!aws.readOnlyPolicyArn) fail(opts, `The read-only policy for the dashboard is missing. Run ${cmdFor("init")} again (it adds it), then ${cmdFor("deploy-dashboard")}.`);
1264
1311
  const { fromNodeProviderChain } = await import("@aws-sdk/credential-providers");
1265
1312
  const [iamMod, lambdaMod] = await Promise.all([import("@aws-sdk/client-iam"), import("@aws-sdk/client-lambda")]);
1266
1313
  const base = { region: aws.region, credentials: fromNodeProviderChain(aws.profile ? { profile: aws.profile } : {}) };
@@ -1279,7 +1326,7 @@ async function hostAws(cfg, local) {
1279
1326
  ].join("\n"),
1280
1327
  "About to host the dashboard"
1281
1328
  );
1282
- if (!await yes("Host the dashboard in AWS?")) bail("Nothing was deployed. The dashboard still runs locally with npx debugkit dashboard.");
1329
+ if (!opts.confirmed && !await yes("Host the dashboard in AWS?")) return skipOrStop(opts, `Skipped hosting: the dashboard still runs locally with ${cmdFor("dashboard")}.`);
1283
1330
  const s = p.spinner();
1284
1331
  s.start("Packaging the dashboard");
1285
1332
  const zip = await dashboardZip();
@@ -1288,7 +1335,7 @@ async function hostAws(cfg, local) {
1288
1335
  let newRole = false;
1289
1336
  const role = await lookup(() => iam.send(new iamMod.GetRoleCommand({ RoleName: roleName })));
1290
1337
  if (role) {
1291
- if (!role.Role?.Tags?.some((t) => t.Key === CREATED_BY2 && t.Value === "debugkit")) bail(`Role ${roleName} exists and wasn't created by deBug. deBug won't change it.`);
1338
+ if (!role.Role?.Tags?.some((t) => t.Key === CREATED_BY2 && t.Value === "debugkit")) fail(opts, `Role ${roleName} exists and wasn't created by deBug. deBug won't change it.`);
1292
1339
  roleArn = role.Role.Arn;
1293
1340
  } else {
1294
1341
  roleArn = (await iam.send(
@@ -1314,7 +1361,7 @@ async function hostAws(cfg, local) {
1314
1361
  const fn = await lookup(() => lambda.send(new lambdaMod.GetFunctionCommand({ FunctionName: functionName })));
1315
1362
  const fnConfig = { FunctionName: functionName, Role: roleArn, Handler: "index.handler", Runtime: "nodejs22.x", MemorySize: 1024, Timeout: 30 };
1316
1363
  if (fn) {
1317
- if (fn.Tags?.[CREATED_BY2] !== "debugkit") bail(`Function ${functionName} exists and wasn't created by deBug. deBug won't overwrite it.`);
1364
+ if (fn.Tags?.[CREATED_BY2] !== "debugkit") fail(opts, `Function ${functionName} exists and wasn't created by deBug. deBug won't overwrite it.`);
1318
1365
  await lambda.send(new lambdaMod.UpdateFunctionCodeCommand({ FunctionName: functionName, ZipFile: zip }));
1319
1366
  await waitUpdated2(lambda, lambdaMod, functionName);
1320
1367
  } else {
@@ -1387,7 +1434,7 @@ function detectApp(cwd) {
1387
1434
  try {
1388
1435
  pkg = JSON.parse(readFileSync5(join6(cwd, "package.json"), "utf8"));
1389
1436
  } catch {
1390
- throw new Error(`No package.json in ${cwd}. Run npx debugkit init from your app's folder.`);
1437
+ throw new Error(`No package.json in ${cwd}. Run ${cmdFor("init")} from your app's folder.`);
1391
1438
  }
1392
1439
  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
1393
1440
  const has = (d) => d in deps;
@@ -1404,7 +1451,7 @@ function detectApp(cwd) {
1404
1451
  reactNavigation: has("@react-navigation/native"),
1405
1452
  packageManager: existsSync6(join6(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync6(join6(cwd, "yarn.lock")) ? "yarn" : existsSync6(join6(cwd, "bun.lockb")) || existsSync6(join6(cwd, "bun.lock")) ? "bun" : "npm",
1406
1453
  hasSdk: has("@debugkit/sdk"),
1407
- missingExpoModules: platform === "expo" ? ["expo-device", "expo-application"].filter((m) => !has(m)) : [],
1454
+ missingNativeModules: (platform === "expo" ? ["expo-device", "expo-application", "react-native-device-info"] : platform === "react-native" ? ["react-native-device-info"] : []).filter((m) => !has(m)),
1408
1455
  sourceDir: existsSync6(join6(cwd, "src")) ? "src" : ".",
1409
1456
  envPrefix,
1410
1457
  typescript: existsSync6(join6(cwd, "tsconfig.json")) || has("typescript")
@@ -1464,10 +1511,11 @@ function mergeContext(a, b) {
1464
1511
  const out = { ...a };
1465
1512
  for (const [k, v] of Object.entries(b)) {
1466
1513
  const prev = out[k];
1467
- out[k] = v && typeof v === "object" && prev && typeof prev === "object" ? { ...prev, ...v } : v ?? prev;
1514
+ out[k] = v && typeof v === "object" && prev && typeof prev === "object" ? { ...prev, ...defined(v) } : v ?? prev;
1468
1515
  }
1469
1516
  return out;
1470
1517
  }
1518
+ var defined = (o) => Object.fromEntries(Object.entries(o).filter(([, x]) => x !== void 0));
1471
1519
  function safe(fn) {
1472
1520
  try {
1473
1521
  return fn();
@@ -1705,6 +1753,9 @@ var DebugClient = class {
1705
1753
  user = { anonymousId: uid() };
1706
1754
  timer;
1707
1755
  flushing;
1756
+ /** Tags on every error and event: deBug's own sources (device facts), then the app's. */
1757
+ tagSources = [];
1758
+ globalTags = {};
1708
1759
  /** The batch being uploaded: still saved, so a crash mid-upload doesn't lose it. */
1709
1760
  inflight = [];
1710
1761
  /** Saved events from the last run, read once; saves wait for it so they don't overwrite them. */
@@ -1724,6 +1775,7 @@ var DebugClient = class {
1724
1775
  if (this.timer) clearInterval(this.timer);
1725
1776
  this.uninstrument();
1726
1777
  this.opts = { flushIntervalMs: 5e3, maxBatch: 50, maxBreadcrumbs: 30, ...options };
1778
+ this.globalTags = { ...options.tags };
1727
1779
  if (options.enabled === false) {
1728
1780
  this.ready = false;
1729
1781
  this.queue = [];
@@ -1781,6 +1833,23 @@ var DebugClient = class {
1781
1833
  setContext(patch) {
1782
1834
  if (this.opts) this.opts.context = mergeContext(this.opts.context ?? {}, patch);
1783
1835
  }
1836
+ /** Add or change tags on every later error and event. A value of undefined removes the tag. */
1837
+ setTags(tags) {
1838
+ for (const [k, v] of Object.entries(tags)) {
1839
+ if (v === void 0) delete this.globalTags[k];
1840
+ else this.globalTags[k] = String(v);
1841
+ }
1842
+ }
1843
+ /**
1844
+ * A function whose tags go on every error and event (the React Native entry adds device
1845
+ * facts this way). Read when each event happens; a source that throws is skipped.
1846
+ */
1847
+ addTagSource(source) {
1848
+ this.tagSources.push(source);
1849
+ return () => {
1850
+ this.tagSources = this.tagSources.filter((s) => s !== source);
1851
+ };
1852
+ }
1784
1853
  setUser(id) {
1785
1854
  this.user = { ...this.user, id };
1786
1855
  }
@@ -1930,10 +1999,10 @@ var DebugClient = class {
1930
1999
  /** Queue without sampling (sessions must be complete for crash-free rates to be right). */
1931
2000
  push(e) {
1932
2001
  if (!this.ready) return;
1933
- let out = e;
2002
+ let out = e.type === "error" || e.type === "event" ? this.withTags(e) : e;
1934
2003
  if (this.opts.beforeSend) {
1935
2004
  try {
1936
- out = this.opts.beforeSend(e);
2005
+ out = this.opts.beforeSend(out);
1937
2006
  } catch (err) {
1938
2007
  this.log("beforeSend threw; sending the event unchanged", err);
1939
2008
  }
@@ -1944,6 +2013,30 @@ var DebugClient = class {
1944
2013
  if (out.type === "error" || this.queue.length >= this.opts.maxBatch) void this.flush();
1945
2014
  else void this.persist();
1946
2015
  }
2016
+ /** deBug's tag sources, then the app's global tags, then enrich(), then the event's own tags. */
2017
+ withTags(e) {
2018
+ const tags = {};
2019
+ const add = (t) => {
2020
+ if (!t) return;
2021
+ for (const [k, v] of Object.entries(t)) if (v !== void 0 && v !== null) tags[k.slice(0, 100)] = String(v).slice(0, 200);
2022
+ };
2023
+ for (const source of this.tagSources) {
2024
+ try {
2025
+ add(source());
2026
+ } catch {
2027
+ }
2028
+ }
2029
+ add(this.globalTags);
2030
+ if (this.opts.enrich) {
2031
+ try {
2032
+ add(this.opts.enrich(e));
2033
+ } catch (err) {
2034
+ this.log("enrich threw; skipped", err);
2035
+ }
2036
+ }
2037
+ add(e.tags);
2038
+ return Object.keys(tags).length ? { ...e, tags } : e;
2039
+ }
1947
2040
  buildContext() {
1948
2041
  const c = this.opts.context ?? {};
1949
2042
  return {
@@ -2317,7 +2410,7 @@ async function walkthrough(opts) {
2317
2410
  const sent = await sendTestEvents(cfg, app);
2318
2411
  if (sent.error) {
2319
2412
  s.error(`The ingest didn't accept them: ${sent.error}`);
2320
- p.log.warn(cfg.provider === "firebase" ? "A brand-new Cloud Function can take a minute to answer. Try again with npx debugkit test." : "Check the endpoint and key in .debugkit/config.json, then run npx debugkit test.");
2413
+ p.log.warn(cfg.provider === "firebase" ? `A brand-new Cloud Function can take a minute to answer. Try again with ${cmdFor("test")}.` : `Check the endpoint and key in .debugkit/config.json, then run ${cmdFor("test")}.`);
2321
2414
  } else {
2322
2415
  s.message("Sent. Waiting for the dashboard to show them");
2323
2416
  const after = await waitForArrival(cwd, dashboardUrl, cfg.appId);
@@ -2338,7 +2431,7 @@ async function walkthrough(opts) {
2338
2431
  );
2339
2432
  } else {
2340
2433
  s.error("Sent, but the dashboard doesn't show them yet");
2341
- p.log.warn(`The dashboard said: ${after?.status ?? "?"} ${after?.error ?? ""}. Refresh it in a minute, or run npx debugkit test again.`);
2434
+ p.log.warn(`The dashboard said: ${after?.status ?? "?"} ${after?.error ?? ""}. Refresh it in a minute, or run ${cmdFor("test")} again.`);
2342
2435
  }
2343
2436
  }
2344
2437
  await next("What does the SDK do on its own?");
@@ -2405,23 +2498,43 @@ var ENV_ENDPOINT = "DEBUG_ENDPOINT";
2405
2498
  var ENV_KEY = "DEBUG_KEY";
2406
2499
  async function installSdk(app) {
2407
2500
  if (!app.hasSdk) {
2408
- const [cmd, args] = installCommand(app.packageManager, ["@debugkit/sdk"]);
2501
+ const [cmd2, args2] = installCommand(app.packageManager, ["@debugkit/sdk"]);
2409
2502
  if (await yes(`Install ${code("@debugkit/sdk")} with ${app.packageManager}?`)) {
2410
2503
  const s = p.spinner();
2411
- s.start(`${cmd} ${args.join(" ")}`);
2412
- const r = await capture(cmd, args, { cwd: app.cwd });
2504
+ s.start(`${cmd2} ${args2.join(" ")}`);
2505
+ const r = await capture(cmd2, args2, { cwd: app.cwd });
2413
2506
  if (r.code !== 0) {
2414
2507
  s.error("Install failed");
2415
2508
  p.log.error(r.stderr.slice(-800));
2416
- throw new Error("Couldn't install @debugkit/sdk. Install it yourself and run npx debugkit init again.");
2509
+ throw new Error(`Couldn't install @debugkit/sdk. Install it yourself and run ${cmdFor("init")} again.`);
2417
2510
  }
2418
2511
  s.stop(`Installed @debugkit/sdk`);
2419
2512
  app.hasSdk = true;
2420
2513
  }
2421
2514
  }
2422
- if (app.platform === "expo" && app.missingExpoModules.length) {
2423
- const exit = await interactive("npx", ["expo", "install", ...app.missingExpoModules], { cwd: app.cwd });
2424
- if (exit !== 0) p.log.warn("Couldn't install expo-device and expo-application. Run: npx expo install expo-device expo-application");
2515
+ const missing = app.missingNativeModules;
2516
+ if (!missing.length) return;
2517
+ p.note(
2518
+ [
2519
+ `deBug reads the device's model, memory, screen, network and storage with ${missing.map(code).join(", ")}.`,
2520
+ "They're native modules, so they go in your app's own dependencies (React Native only links those),",
2521
+ `and the app needs a ${bold("new native build")} before they work: an over-the-air update can't add them.`,
2522
+ "Until then deBug still works, with fewer device details."
2523
+ ].join("\n"),
2524
+ "Device details"
2525
+ );
2526
+ const [cmd, args] = app.platform === "expo" ? ["npx", ["expo", "install", ...missing]] : installCommand(app.packageManager, missing);
2527
+ const command = `${cmd} ${args.join(" ")}`;
2528
+ const names = missing.join(", ");
2529
+ if (!await yes(`Install ${names}?`)) {
2530
+ p.log.info(dim(`Later: ${command}`));
2531
+ return;
2532
+ }
2533
+ const exit = await interactive(cmd, args, { cwd: app.cwd });
2534
+ if (exit !== 0) p.log.warn(`Couldn't install ${names}. Run: ${command}`);
2535
+ else {
2536
+ app.missingNativeModules = [];
2537
+ p.log.success(`Installed ${names}. Rebuild the app${app.platform === "react-native" ? " (cd ios && pod install first)" : " (eas build, or npx expo run:android / run:ios)"} to link them.`);
2425
2538
  }
2426
2539
  }
2427
2540
  function writeAppEnv(app, conn) {
@@ -2471,7 +2584,8 @@ export const deBug = initExpo({
2471
2584
  return {
2472
2585
  path: path2,
2473
2586
  contents: `${header}import { initReactNative } from "@debugkit/sdk/react-native";
2474
- // Optional, for model and app version: npm install react-native-device-info, then pass deviceInfo: DeviceInfo.
2587
+ // Device details (model, memory, screen, network, storage) are read automatically with
2588
+ // react-native-device-info. Add your own with tags: { \u2026 } or deBug.setTags({ \u2026 }).
2475
2589
 
2476
2590
  export const deBug = initReactNative({
2477
2591
  enabled: ${multiEnv ? "!__DEV__ // release builds only" : "true"},
@@ -2701,46 +2815,69 @@ async function init(cwd, preset) {
2701
2815
  result = provider === "firebase" ? await setupFirebase(ctx) : provider === "aws" ? await setupAws(ctx) : await setupLocal(ctx);
2702
2816
  } catch (err) {
2703
2817
  p.log.error(err.message);
2704
- bail("Setup stopped. Nothing else was changed in your app. Fix the error above and run npx debugkit init again.");
2818
+ bail(`Setup stopped. Nothing else was changed in your app. Fix the error above and run ${cmdFor("init")} again.`);
2705
2819
  }
2706
2820
  const cfg = { ...result.config, ...existing?.provider === provider && existing.hosted ? { hosted: existing.hosted } : {}, appId: app.appId, dashboardPort, retentionDays, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
2707
2821
  writeConfig(cwd, cfg);
2708
2822
  p.note(result.created.map((l) => `\u2022 ${l}`).join("\n"), "Created");
2709
2823
  printValues("Your ingest endpoint and key (the key is public: it ships in your app):", { endpoint: cfg.endpoint, key: cfg.ingestKey });
2710
- const remaining = await wireApp(app, cfg);
2711
2824
  await prepareDashboardEnv(cwd, result.dashboardEnv, dashboardPort);
2825
+ let hostedUrl = cfg.hosted?.url;
2826
+ let hostedLive = false;
2827
+ if (provider !== "local") {
2828
+ p.note(
2829
+ [
2830
+ `deBug can host the dashboard in your ${provider === "aws" ? "AWS account" : "Firebase project"} too, reading the same data,`,
2831
+ "at a link you can share with your team. It signs in with the same login, and you can still run it locally.",
2832
+ `Skip it and setup carries on; host it later with ${cmdFor("deploy-dashboard")}.`
2833
+ ].join("\n"),
2834
+ "Host the dashboard"
2835
+ );
2836
+ const choice = await choose(
2837
+ hostedUrl ? `The dashboard is hosted at ${hostedUrl}. Update it?` : "Host the dashboard online?",
2838
+ [
2839
+ { value: "host", label: hostedUrl ? "Update it" : "Host it", hint: "a few minutes" },
2840
+ { value: "skip", label: "Skip for now" }
2841
+ ],
2842
+ "host"
2843
+ );
2844
+ for (let attempt = choice === "host"; attempt; ) {
2845
+ try {
2846
+ const out = await hostDashboard(cwd, readConfig(cwd) ?? cfg, { onProblem: "skip", confirmed: true });
2847
+ if (out) [hostedUrl, hostedLive] = [out.url, out.live];
2848
+ attempt = false;
2849
+ } catch (err) {
2850
+ p.log.error(err.message);
2851
+ attempt = await choose("Hosting didn't finish. What now?", [
2852
+ { value: "retry", label: "Retry" },
2853
+ { value: "skip", label: "Skip hosting for now", hint: "setup carries on" }
2854
+ ], "retry") === "retry";
2855
+ if (!attempt) p.log.info(`Setup carries on. Host it later with ${code(cmdFor("deploy-dashboard"))}.`);
2856
+ }
2857
+ }
2858
+ if (choice === "skip") p.log.info(dim(`Skipped. Any time later: ${cmdFor("deploy-dashboard")}`));
2859
+ }
2860
+ const setup = readConfig(cwd) ?? cfg;
2861
+ const remaining = await wireApp(app, setup);
2712
2862
  let dash;
2713
- try {
2714
- dash = await startDashboard(cwd);
2715
- } catch (err) {
2716
- p.log.error(err.message);
2717
- p.outro(`deBug is set up, but the dashboard didn't start. Try ${code(cmdFor("dashboard"))}.`);
2718
- return;
2863
+ if (!(hostedUrl && hostedLive)) {
2864
+ try {
2865
+ dash = await startDashboard(cwd);
2866
+ } catch (err) {
2867
+ p.log.error(err.message);
2868
+ p.outro(`deBug is set up, but the dashboard didn't start. Try ${code(cmdFor("dashboard"))}.`);
2869
+ return;
2870
+ }
2719
2871
  }
2720
- await walkthrough({ cwd, app, cfg, dashboardUrl: dash.url, remaining });
2721
- if (provider === "local") {
2872
+ await walkthrough({ cwd, app, cfg: setup, dashboardUrl: dash?.url ?? hostedUrl, remaining });
2873
+ if (provider === "local" && dash) {
2874
+ const running = dash;
2722
2875
  p.log.info(`The dashboard is your ingest on this setup, so keep it running while you try the app. Stop it with ${code("Ctrl-C")}.`);
2723
2876
  p.outro("deBug is set up.");
2724
- await new Promise((r) => dash.child.once("exit", () => r()));
2877
+ await new Promise((r) => running.child.once("exit", () => r()));
2725
2878
  return;
2726
2879
  }
2727
- dash.stop();
2728
- let hostedUrl = cfg.hosted?.url;
2729
- p.note(
2730
- [
2731
- `The dashboard ran on this machine. deBug can also host it in your ${provider === "aws" ? "AWS account" : "Firebase project"}, reading the same data,`,
2732
- "at a link you can share with your team. It signs in with the same login. You can still run it locally."
2733
- ].join("\n"),
2734
- "Host the dashboard?"
2735
- );
2736
- if (await yes(hostedUrl ? `Update the hosted dashboard at ${hostedUrl}?` : "Host the dashboard online too?", !hostedUrl)) {
2737
- try {
2738
- hostedUrl = (await hostDashboard(cwd, readConfig(cwd) ?? cfg)).url;
2739
- } catch (err) {
2740
- p.log.error(err.message);
2741
- p.log.info(`deBug itself is set up. Try hosting again with ${code(cmdFor("deploy-dashboard"))}.`);
2742
- }
2743
- } else p.log.info(dim(`Any time later: ${cmdFor("deploy-dashboard")}`));
2880
+ dash?.stop();
2744
2881
  const others = listEnvironments(cwd).filter((e) => e !== environment.get());
2745
2882
  p.outro(
2746
2883
  `deBug is set up${envLabel()}. ${hostedUrl ? `Share the dashboard: ${code(hostedUrl)}. ` : ""}Open it locally any time with ${code(cmdFor("dashboard"))}.` + (environment.get() && !others.length ? `
@@ -2751,7 +2888,9 @@ async function deployDashboard(cwd) {
2751
2888
  const cfg = requireConfig(cwd);
2752
2889
  p.intro(`${pc.bgRed(pc.white(" deBug "))} host the dashboard${envLabel()}`);
2753
2890
  if (cfg.provider === "local") bail(`This setup keeps data on this machine, so there's nothing to host. Run ${code(cmdFor("init"))} with Firebase or AWS first.`);
2754
- const { url } = await hostDashboard(cwd, cfg);
2891
+ const out = await hostDashboard(cwd, cfg);
2892
+ if (!out) return;
2893
+ const { url } = out;
2755
2894
  const { openUrl: openUrl2 } = await Promise.resolve().then(() => (init_exec(), exec_exports));
2756
2895
  openUrl2(url);
2757
2896
  p.outro(`Share ${code(url)} with your team. ${loginHint(cwd)}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@debugkit/cli",
3
- "version": "0.6.1",
3
+ "version": "0.7.0",
4
4
  "description": "Set up deBug in your app: npx @debugkit/cli init (or npx debugkit init once @debugkit/sdk is installed). Deploys ingest to your own cloud, wires the SDK and walks you through the dashboard.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -20,9 +20,9 @@
20
20
  },
21
21
  "devDependencies": {
22
22
  "@aws-sdk/lib-dynamodb": "^3.700.0",
23
- "@debugkit/adapters": "^0.6.1",
24
- "@debugkit/ingest": "^0.6.1",
25
- "@debugkit/sdk": "^0.6.1"
23
+ "@debugkit/adapters": "^0.7.0",
24
+ "@debugkit/sdk": "^0.7.0",
25
+ "@debugkit/ingest": "^0.7.0"
26
26
  },
27
27
  "engines": {
28
28
  "node": ">=20.12"