@zharp/cli 0.2.0 → 0.3.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 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)