@debugkit/cli 0.4.0 → 0.6.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.
- package/README.md +47 -5
- package/dist/cli.js +1966 -1392
- package/dist/lambda/index.mjs +3 -2
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -16,15 +16,53 @@ Run it from your app's folder. It walks you through these steps:
|
|
|
16
16
|
- **AWS:** a Lambda with a public URL and DynamoDB.
|
|
17
17
|
- **Just this machine:** no cloud, for a first look.
|
|
18
18
|
3. **Signs you in and sets everything up in your own account.**
|
|
19
|
-
- **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
|
|
19
|
+
- **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
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. **
|
|
22
|
-
5. **
|
|
23
|
-
6. **
|
|
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:**
|
|
24
25
|
- what each part of the dashboard will show;
|
|
25
26
|
- a test event, sent through the real ingest so you watch it arrive;
|
|
26
27
|
- what the SDK records on its own;
|
|
27
28
|
- 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
|
+
|
|
31
|
+
## Hosting the dashboard for your team
|
|
32
|
+
|
|
33
|
+
`npx debugkit deploy-dashboard` puts the dashboard online, next to your data, and prints the link.
|
|
34
|
+
It uses the same login as your local dashboard, and you can keep running it locally too.
|
|
35
|
+
|
|
36
|
+
| | Firebase | AWS |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| Address | `https://<project>-debug.web.app`, a Hosting site of its own (your app's site is untouched) | the Lambda's Function URL |
|
|
39
|
+
| Runs as | a 2nd-gen Cloud Function `debugkitDashboard`, behind Firebase Hosting | a Lambda `debugkit-dashboard-<table>` |
|
|
40
|
+
| Reads data as | a service account `debugkit-dashboard` with Cloud Datastore Viewer only (needs `gcloud`; without it, the project's default account) | an IAM role with the read-only policy `init` created |
|
|
41
|
+
| Secrets | `.debugkit/firebase/dashboard/.env.<project>`, gitignored | the Lambda's environment |
|
|
42
|
+
|
|
43
|
+
- Run it again after upgrading deBug, or after `npx debugkit password`, to update the hosted copy.
|
|
44
|
+
- Slack alerts link to the hosted dashboard once it exists.
|
|
45
|
+
- Anyone with the link sees the sign-in page; only people with a login get in.
|
|
46
|
+
- If Firebase Hosting can't reach a function in your database's region, the CLI offers to retry with the function in `us-central1`.
|
|
47
|
+
|
|
48
|
+
### Inviting your team
|
|
49
|
+
|
|
50
|
+
Open **Team** on the dashboard and create an invite link. Nothing is emailed: copy the link and
|
|
51
|
+
send it however you like. The person opens it, picks a password, and is signed in.
|
|
52
|
+
|
|
53
|
+
| Role | Can |
|
|
54
|
+
|---|---|
|
|
55
|
+
| owner | everything, including adding and removing owners |
|
|
56
|
+
| admin | change settings and manage the team, except owners |
|
|
57
|
+
| member | see everything and change issue status |
|
|
58
|
+
|
|
59
|
+
- Links work once and expire after 7 days. Add an email to lock a link to one person.
|
|
60
|
+
- Removing someone signs them out within 10 seconds, and their password stops working.
|
|
61
|
+
- The login `init` created stays an owner. It lives in `.debugkit/dashboard.env`, not the team list.
|
|
62
|
+
- Team logins are stored in your database (`debug_apps_members` in Firestore, `TEAM` items in
|
|
63
|
+
DynamoDB) as scrypt hashes. Invite links are stored only as SHA-256 hashes.
|
|
64
|
+
- Changes go through your ingest function, like settings. Redeploy ingest (`npx debugkit init`)
|
|
65
|
+
if the Team page says it's too old.
|
|
28
66
|
|
|
29
67
|
## Several environments (preview, production…)
|
|
30
68
|
|
|
@@ -57,7 +95,8 @@ Every command below also works as `npx @debugkit/cli <command>`.
|
|
|
57
95
|
| Command | What it does |
|
|
58
96
|
|---|---|
|
|
59
97
|
| `npx debugkit init` | The full setup above |
|
|
60
|
-
| `npx debugkit dashboard` | Runs the dashboard against your data. On "just this machine", it also receives your app's events |
|
|
98
|
+
| `npx debugkit dashboard` | Runs the dashboard on this machine against your data. On "just this machine", it also receives your app's events |
|
|
99
|
+
| `npx debugkit deploy-dashboard` | Hosts the dashboard in your Firebase project or AWS account, at a link to share |
|
|
61
100
|
| `npx debugkit test` | Sends test events and checks they're accepted |
|
|
62
101
|
| `npx debugkit guide` | Replays the walkthrough |
|
|
63
102
|
|
|
@@ -69,7 +108,9 @@ Options: `--provider firebase|aws|local` skips the provider question, `--cwd <di
|
|
|
69
108
|
|---|---|
|
|
70
109
|
| Just this machine | Run end to end: the empty dashboard, then test events arriving |
|
|
71
110
|
| Firebase | Run end to end against a real project: function deployed, indexes added without touching existing ones, test events read back on the dashboard |
|
|
111
|
+
| Hosting the dashboard | Firebase: deployed to a real project (us-central1), reading live data as the read-only service account, redeployed on top of itself. AWS: the Lambda package runs locally; not yet deployed to a real account |
|
|
72
112
|
| AWS | Unit-tested (profile parsing, the "not found" handling, key merging) and the bundled Lambda run locally. Not yet run against a real account |
|
|
113
|
+
| Environments (`--env`) | Run end to end with "just this machine" in an Expo-style app: separate config and login, `.env` untouched, `debug.ts` with the on/off switch. `eas env:set` is checked against EAS's help but not yet run against a real EAS project |
|
|
73
114
|
| Platforms | Vite and React run for real. The Expo, React Native, Next.js, TanStack Start and Node templates are unit-tested |
|
|
74
115
|
|
|
75
116
|
## What it needs
|
|
@@ -86,6 +127,7 @@ Options: `--provider firebase|aws|local` skips the provider question, `--cwd <di
|
|
|
86
127
|
|---|---|---|
|
|
87
128
|
| `.debugkit/config.json` | provider, endpoint, ingest key, resource names | yes |
|
|
88
129
|
| `.debugkit/firebase/` | the ingest function source (Firebase), so you can redeploy it | yes |
|
|
130
|
+
| `.debugkit/firebase/dashboard/` | the hosted dashboard's function source (Firebase). Its `.env.<project>` holds secrets and is gitignored | yes, except `.env.*` |
|
|
89
131
|
| `.debugkit/dashboard.env` | the dashboard login (a password hash), session secret, API token | no, it's gitignored |
|
|
90
132
|
| `debug.ts` (or `src/debug.ts`) | `init()` for your platform | yes |
|
|
91
133
|
| `.env` | the endpoint and ingest key | added to `.gitignore` |
|