@debugkit/cli 0.0.0-stage → 0.4.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 +92 -2
- package/dist/cli.js +2203 -0
- package/dist/lambda/index.mjs +2 -0
- package/package.json +44 -3
package/README.md
CHANGED
|
@@ -1,3 +1,93 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @debugkit/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Set up [deBug](https://github.com/Abantu-Digital/deBug) in your app with one command:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx @debugkit/cli init
|
|
7
|
+
```
|
|
8
|
+
|
|
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
|
+
|
|
11
|
+
Run it from your app's folder. It walks you through these steps:
|
|
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.
|
|
14
|
+
2. **Asks where your data should live:**
|
|
15
|
+
- **Firebase:** a Cloud Function and Firestore.
|
|
16
|
+
- **AWS:** a Lambda with a public URL and DynamoDB.
|
|
17
|
+
- **Just this machine:** no cloud, for a first look.
|
|
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 30-day 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. **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.
|
|
22
|
+
5. **Opens your dashboard,** connected to your data and still empty, behind a login you choose.
|
|
23
|
+
6. **Walks you through it:**
|
|
24
|
+
- what each part of the dashboard will show;
|
|
25
|
+
- a test event, sent through the real ingest so you watch it arrive;
|
|
26
|
+
- what the SDK records on its own;
|
|
27
|
+
- what you add in your own try/catches.
|
|
28
|
+
|
|
29
|
+
## Several environments (preview, production…)
|
|
30
|
+
|
|
31
|
+
When each environment has its own backend, such as separate Firebase projects or AWS accounts, set
|
|
32
|
+
deBug up once per environment:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npx debugkit init --env preview # e.g. into your staging Firebase project
|
|
36
|
+
npx debugkit init --env production # into the production one
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Each environment gets its own provider, project, endpoint, ingest key and dashboard login. They're
|
|
40
|
+
saved under `environments` in `.debugkit/config.json`, with `.debugkit/dashboard.<env>.env`.
|
|
41
|
+
|
|
42
|
+
- **Expo apps with EAS:** for `development`, `preview` and `production`, the CLI offers to put
|
|
43
|
+
`EXPO_PUBLIC_DEBUG_ENDPOINT`, `EXPO_PUBLIC_DEBUG_KEY` and `EXPO_PUBLIC_DEBUG_ENVIRONMENT` into
|
|
44
|
+
that EAS environment (`eas env:set`). `eas build` and `eas env:pull` then pick them up.
|
|
45
|
+
- **Other apps:** it prints the three values to set wherever that environment's builds get their
|
|
46
|
+
config. With `--env` it never writes `.env`, which would point every build at one environment.
|
|
47
|
+
- **`debug.ts` is the same for every environment:** it's on in release builds that have an
|
|
48
|
+
endpoint, and off in development builds and local runs (`enabled: !__DEV__ && !!endpoint`). To
|
|
49
|
+
leave an environment out, such as development, don't set it up.
|
|
50
|
+
- **Later commands take `--env` too:** `npx debugkit dashboard --env production`, `test`, `guide`
|
|
51
|
+
and `password`.
|
|
52
|
+
|
|
53
|
+
## Commands
|
|
54
|
+
|
|
55
|
+
Every command below also works as `npx @debugkit/cli <command>`.
|
|
56
|
+
|
|
57
|
+
| Command | What it does |
|
|
58
|
+
|---|---|
|
|
59
|
+
| `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 |
|
|
61
|
+
| `npx debugkit test` | Sends test events and checks they're accepted |
|
|
62
|
+
| `npx debugkit guide` | Replays the walkthrough |
|
|
63
|
+
|
|
64
|
+
Options: `--provider firebase|aws|local` skips the provider question, `--cwd <dir>` points at another folder, and `--yes` accepts the defaults (for scripts; set `DEBUGKIT_DASHBOARD_PASSWORD`).
|
|
65
|
+
|
|
66
|
+
## What's been verified
|
|
67
|
+
|
|
68
|
+
| Path | Status |
|
|
69
|
+
|---|---|
|
|
70
|
+
| Just this machine | Run end to end: the empty dashboard, then test events arriving |
|
|
71
|
+
| Firebase | Run end to end against a real project: function deployed, indexes added without touching existing ones, test events read back on the dashboard |
|
|
72
|
+
| AWS | Unit-tested (profile parsing, the "not found" handling, key merging) and the bundled Lambda run locally. Not yet run against a real account |
|
|
73
|
+
| Platforms | Vite and React run for real. The Expo, React Native, Next.js, TanStack Start and Node templates are unit-tested |
|
|
74
|
+
|
|
75
|
+
## What it needs
|
|
76
|
+
|
|
77
|
+
- Node 20.12 or later.
|
|
78
|
+
- **Firebase:**
|
|
79
|
+
- the Firebase CLI, which is used automatically through `npx firebase-tools` if it isn't installed;
|
|
80
|
+
- `gcloud`, so the dashboard can read Firestore with your Google credentials. Without it, you create a read-only service account yourself.
|
|
81
|
+
- **AWS:** an AWS profile, or the AWS CLI for SSO sign-in.
|
|
82
|
+
|
|
83
|
+
## What it writes in your repo
|
|
84
|
+
|
|
85
|
+
| Path | What it is | Commit it? |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| `.debugkit/config.json` | provider, endpoint, ingest key, resource names | yes |
|
|
88
|
+
| `.debugkit/firebase/` | the ingest function source (Firebase), so you can redeploy it | yes |
|
|
89
|
+
| `.debugkit/dashboard.env` | the dashboard login (a password hash), session secret, API token | no, it's gitignored |
|
|
90
|
+
| `debug.ts` (or `src/debug.ts`) | `init()` for your platform | yes |
|
|
91
|
+
| `.env` | the endpoint and ingest key | added to `.gitignore` |
|
|
92
|
+
|
|
93
|
+
The ingest key is public and write-only, the same kind of key that ships inside your app. Your cloud credentials stay with the Firebase, gcloud and AWS tools on your machine. deBug never receives them.
|