@zharp/cli 0.2.0 → 0.2.1
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 +94 -94
- package/dist/cli.js +6 -5
- package/dist/cli.js.map +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,94 +1,94 @@
|
|
|
1
|
-
# @zharp/cli
|
|
2
|
-
|
|
3
|
-
The `zharp` command: upload what [Zharp](https://zharp.io) needs to turn minified and obfuscated stack traces back into your source — JavaScript source maps, Android R8/ProGuard mappings, Flutter Dart symbols and iOS dSYMs.
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npm install --save-dev @zharp/cli # or run it with npx zharp …
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
Requires Node 18.18 or later. No dependencies.
|
|
10
|
-
|
|
11
|
-
## Authentication
|
|
12
|
-
|
|
13
|
-
Uploads need a **workspace API key with the `artifacts:write` scope** (Integrations & API → Main API keys, "Build uploads"). It is a secret for your CI, not the app key your SDK sends data with.
|
|
14
|
-
|
|
15
|
-
| Variable | |
|
|
16
|
-
|---|---|
|
|
17
|
-
| `ZHARP_AUTH_TOKEN` | The API key. Required to upload. |
|
|
18
|
-
| `ZHARP_URL` | The Zharp API. Default `https://api.zharp.io`. |
|
|
19
|
-
| `ZHARP_APP` | The application ID, instead of `--app`. |
|
|
20
|
-
| `ZHARP_RELEASE` | A release name, instead of `--release`. |
|
|
21
|
-
|
|
22
|
-
The application ID is the number in the app's dashboard URL.
|
|
23
|
-
|
|
24
|
-
## JavaScript source maps
|
|
25
|
-
|
|
26
|
-
If you use Vite, webpack, Next.js, Rollup or esbuild, the [bundler plugins](../bundler-plugins/README.md) do all of this during the build. Otherwise, after your build:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
zharp sourcemaps inject dist
|
|
30
|
-
zharp sourcemaps upload dist --app 42 --release "$GIT_SHA" --delete-after
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
**`zharp sourcemaps inject <dir>`** gives every `.js`/`.mjs`/`.cjs` file that has a source map (`file.js.map` next to it, or the file its `sourceMappingURL` names) a *debug ID*:
|
|
34
|
-
|
|
35
|
-
- appended to the file: one line that registers the file at runtime for the Zharp SDKs, and `//# debugId=<uuid>`. Lines are only added after the code, so the map stays valid;
|
|
36
|
-
- written into the map as `"debugId"` (and `"debug_id"`).
|
|
37
|
-
|
|
38
|
-
The ID is derived from the file's content, so rebuilding identical output gives the same ID, and running `inject` twice changes nothing. A file a bundler already gave a `//# debugId=` comment keeps that ID.
|
|
39
|
-
|
|
40
|
-
`@zharp/browser` and `@zharp/node` send the IDs of the files in each error's stack, and Zharp finds the matching map by ID — whatever URL, CDN or path the file was served from.
|
|
41
|
-
|
|
42
|
-
**`zharp sourcemaps upload <dir> --app <id>`** uploads each injected file and its map. Options: `--release <name>`, `--delete-after` (delete the `.map` files once uploaded, so they are not deployed), `--include <glob>` / `--exclude <glob>` (repeatable, relative to `<dir>`), `--dry-run`.
|
|
43
|
-
|
|
44
|
-
Keep `sourcesContent` in your maps (most bundlers do by default) and Zharp shows the code around each frame, not only the file and line.
|
|
45
|
-
|
|
46
|
-
## Android (R8 / ProGuard)
|
|
47
|
-
|
|
48
|
-
```bash
|
|
49
|
-
zharp proguard upload app/build/outputs/mapping/release/mapping.txt --app 42 --uuid <build-uuid>
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
`--uuid` is the build's UUID that the Zharp Gradle plugin writes into the app (and that the SDK reports as `zharp.proguard_uuid`). The Gradle plugin runs this for you after `assembleRelease`/`bundleRelease`.
|
|
53
|
-
|
|
54
|
-
## Flutter
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
flutter build apk --obfuscate --split-debug-info=build/symbols \
|
|
58
|
-
--extra-gen-snapshot-options=--save-obfuscation-map=build/obfuscation.json
|
|
59
|
-
zharp dart-symbols upload build/symbols --app 42
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Each `*.symbols` file is uploaded under its ELF GNU build ID — the `build_id` an obfuscated Dart stack trace prints — with its architecture.
|
|
63
|
-
|
|
64
|
-
The obfuscation map (the JSON array of `[obfuscated, original]` names that `--save-obfuscation-map` writes) lets Zharp restore class and method names in error types and messages too. `obfuscation.json` or `*.obfuscation.json` in the symbols directory or the directory next to it is found and uploaded automatically; pass `--obfuscation-map <file>` for another location. One map covers every architecture of a build, so it is uploaded once per build ID.
|
|
65
|
-
|
|
66
|
-
## iOS
|
|
67
|
-
|
|
68
|
-
Add a Run Script build phase as the last phase of the app target (and set *Debug Information Format* to *DWARF with dSYM File* for Release):
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
export ZHARP_AUTH_TOKEN=… # better: from your CI's secrets
|
|
72
|
-
npx zharp dsym upload "$DWARF_DSYM_FOLDER_PATH" --app 42
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
Every `.dSYM` in the folder is read; each architecture is uploaded under its Mach-O UUID (the UUID a crash report lists for the binary image).
|
|
76
|
-
|
|
77
|
-
## Behaviour
|
|
78
|
-
|
|
79
|
-
- Native symbol files are uploaded gzipped.
|
|
80
|
-
- Failed uploads are retried three times with backoff (network errors, 408, 429, 5xx); a rejected key, a missing scope or an unknown app fails at once with what to fix.
|
|
81
|
-
- Exit code 1 on any error.
|
|
82
|
-
|
|
83
|
-
## As a library
|
|
84
|
-
|
|
85
|
-
```js
|
|
86
|
-
import { injectDirectory, uploadSourcemaps, resolveConnection } from '@zharp/cli';
|
|
87
|
-
|
|
88
|
-
injectDirectory('dist');
|
|
89
|
-
await uploadSourcemaps('dist', resolveConnection({ app: 42 }), { release: 'web@1.4.0', deleteAfter: true });
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
## License
|
|
93
|
-
|
|
94
|
-
MIT © [Zharp](https://zharp.io)
|
|
1
|
+
# @zharp/cli
|
|
2
|
+
|
|
3
|
+
The `zharp` command: upload what [Zharp](https://zharp.io) needs to turn minified and obfuscated stack traces back into your source — JavaScript source maps, Android R8/ProGuard mappings, Flutter Dart symbols and iOS dSYMs.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install --save-dev @zharp/cli # or run it with npx zharp …
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Requires Node 18.18 or later. No dependencies.
|
|
10
|
+
|
|
11
|
+
## Authentication
|
|
12
|
+
|
|
13
|
+
Uploads need a **workspace API key with the `artifacts:write` scope** (Integrations & API → Main API keys, "Build uploads"). It is a secret for your CI, not the app key your SDK sends data with.
|
|
14
|
+
|
|
15
|
+
| Variable | |
|
|
16
|
+
|---|---|
|
|
17
|
+
| `ZHARP_AUTH_TOKEN` | The API key. Required to upload. |
|
|
18
|
+
| `ZHARP_URL` | The Zharp API. Default `https://api.zharp.io`. |
|
|
19
|
+
| `ZHARP_APP` | The application ID, instead of `--app`. |
|
|
20
|
+
| `ZHARP_RELEASE` | A release name, instead of `--release`. |
|
|
21
|
+
|
|
22
|
+
The application ID is the number in the app's dashboard URL.
|
|
23
|
+
|
|
24
|
+
## JavaScript source maps
|
|
25
|
+
|
|
26
|
+
If you use Vite, webpack, Next.js, Rollup or esbuild, the [bundler plugins](../bundler-plugins/README.md) do all of this during the build. Otherwise, after your build:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
zharp sourcemaps inject dist
|
|
30
|
+
zharp sourcemaps upload dist --app 42 --release "$GIT_SHA" --delete-after
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**`zharp sourcemaps inject <dir>`** gives every `.js`/`.mjs`/`.cjs` file that has a source map (`file.js.map` next to it, or the file its `sourceMappingURL` names) a *debug ID*:
|
|
34
|
+
|
|
35
|
+
- appended to the file: one line that registers the file at runtime for the Zharp SDKs, and `//# debugId=<uuid>`. Lines are only added after the code, so the map stays valid;
|
|
36
|
+
- written into the map as `"debugId"` (and `"debug_id"`).
|
|
37
|
+
|
|
38
|
+
The ID is derived from the file's content, so rebuilding identical output gives the same ID, and running `inject` twice changes nothing. A file a bundler already gave a `//# debugId=` comment keeps that ID.
|
|
39
|
+
|
|
40
|
+
`@zharp/browser` and `@zharp/node` send the IDs of the files in each error's stack, and Zharp finds the matching map by ID — whatever URL, CDN or path the file was served from.
|
|
41
|
+
|
|
42
|
+
**`zharp sourcemaps upload <dir> --app <id>`** uploads each injected file and its map. Options: `--release <name>`, `--delete-after` (delete the `.map` files once uploaded, so they are not deployed), `--include <glob>` / `--exclude <glob>` (repeatable, relative to `<dir>`), `--dry-run`.
|
|
43
|
+
|
|
44
|
+
Keep `sourcesContent` in your maps (most bundlers do by default) and Zharp shows the code around each frame, not only the file and line.
|
|
45
|
+
|
|
46
|
+
## Android (R8 / ProGuard)
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
zharp proguard upload app/build/outputs/mapping/release/mapping.txt --app 42 --uuid <build-uuid>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`--uuid` is the build's UUID that the Zharp Gradle plugin writes into the app (and that the SDK reports as `zharp.proguard_uuid`). The Gradle plugin runs this for you after `assembleRelease`/`bundleRelease`.
|
|
53
|
+
|
|
54
|
+
## Flutter
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
flutter build apk --obfuscate --split-debug-info=build/symbols \
|
|
58
|
+
--extra-gen-snapshot-options=--save-obfuscation-map=build/obfuscation.json
|
|
59
|
+
zharp dart-symbols upload build/symbols --app 42
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Each `*.symbols` file is uploaded under its ELF GNU build ID — the `build_id` an obfuscated Dart stack trace prints — with its architecture.
|
|
63
|
+
|
|
64
|
+
The obfuscation map (the JSON array of `[obfuscated, original]` names that `--save-obfuscation-map` writes) lets Zharp restore class and method names in error types and messages too. `obfuscation.json` or `*.obfuscation.json` in the symbols directory or the directory next to it is found and uploaded automatically; pass `--obfuscation-map <file>` for another location. One map covers every architecture of a build, so it is uploaded once per build ID.
|
|
65
|
+
|
|
66
|
+
## iOS
|
|
67
|
+
|
|
68
|
+
Add a Run Script build phase as the last phase of the app target (and set *Debug Information Format* to *DWARF with dSYM File* for Release):
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
export ZHARP_AUTH_TOKEN=… # better: from your CI's secrets
|
|
72
|
+
npx zharp dsym upload "$DWARF_DSYM_FOLDER_PATH" --app 42
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Every `.dSYM` in the folder is read; each architecture is uploaded under its Mach-O UUID (the UUID a crash report lists for the binary image).
|
|
76
|
+
|
|
77
|
+
## Behaviour
|
|
78
|
+
|
|
79
|
+
- Native symbol files are uploaded gzipped.
|
|
80
|
+
- Failed uploads are retried three times with backoff (network errors, 408, 429, 5xx); a rejected key, a missing scope or an unknown app fails at once with what to fix.
|
|
81
|
+
- Exit code 1 on any error.
|
|
82
|
+
|
|
83
|
+
## As a library
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
import { injectDirectory, uploadSourcemaps, resolveConnection } from '@zharp/cli';
|
|
87
|
+
|
|
88
|
+
injectDirectory('dist');
|
|
89
|
+
await uploadSourcemaps('dist', resolveConnection({ app: 42 }), { release: 'web@1.4.0', deleteAfter: true });
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## License
|
|
93
|
+
|
|
94
|
+
MIT © [Zharp](https://zharp.io)
|
package/dist/cli.js
CHANGED
|
@@ -719,7 +719,7 @@ function deleteSourcemaps(files, options = {}) {
|
|
|
719
719
|
}
|
|
720
720
|
|
|
721
721
|
// src/version.ts
|
|
722
|
-
var VERSION = "0.2.
|
|
722
|
+
var VERSION = "0.2.1";
|
|
723
723
|
|
|
724
724
|
// src/init/index.ts
|
|
725
725
|
var import_node_child_process2 = require("child_process");
|
|
@@ -1149,7 +1149,7 @@ function mergeEnv(existing, vars) {
|
|
|
1149
1149
|
const added = Object.entries(vars).filter(([k]) => !seen.has(k));
|
|
1150
1150
|
if (added.length) {
|
|
1151
1151
|
if (out.length) out.push("");
|
|
1152
|
-
out.push("# Zharp (
|
|
1152
|
+
out.push("# Zharp (npm init zharp@latest)");
|
|
1153
1153
|
for (const [k, v] of added) out.push(`${k}=${v}`);
|
|
1154
1154
|
}
|
|
1155
1155
|
return `${out.join("\n")}
|
|
@@ -1190,11 +1190,11 @@ async function sendTestError(api, c) {
|
|
|
1190
1190
|
timeUnixNano: now,
|
|
1191
1191
|
severityNumber: 17,
|
|
1192
1192
|
severityText: "ERROR",
|
|
1193
|
-
body: { stringValue: "ZharpSetupTest: Zharp is connected \u2014 this is the test error
|
|
1193
|
+
body: { stringValue: "ZharpSetupTest: Zharp is connected \u2014 this is the test error npm init zharp@latest sent" },
|
|
1194
1194
|
attributes: [
|
|
1195
1195
|
attr("exception.type", "ZharpSetupTest"),
|
|
1196
|
-
attr("exception.message", "Zharp is connected \u2014 this is the test error
|
|
1197
|
-
attr("exception.stacktrace", "ZharpSetupTest: Zharp is connected \u2014 this is the test error
|
|
1196
|
+
attr("exception.message", "Zharp is connected \u2014 this is the test error npm init zharp@latest sent"),
|
|
1197
|
+
attr("exception.stacktrace", "ZharpSetupTest: Zharp is connected \u2014 this is the test error npm init zharp@latest sent\n at zharp init"),
|
|
1198
1198
|
attr("zharp.handled", "true")
|
|
1199
1199
|
]
|
|
1200
1200
|
}]
|
|
@@ -1321,6 +1321,7 @@ var HELP = `zharp ${VERSION} \u2014 readable stack traces for Zharp
|
|
|
1321
1321
|
|
|
1322
1322
|
Usage:
|
|
1323
1323
|
zharp init Connect this project to Zharp and set it up
|
|
1324
|
+
(also: npm init zharp@latest)
|
|
1324
1325
|
[--yes] [--dry-run] (signs in through the browser)
|
|
1325
1326
|
zharp sourcemaps inject <dir> Add debug IDs to JS files and their maps
|
|
1326
1327
|
zharp sourcemaps upload <dir> --app <id> Upload JS files and their maps
|