@zharp/cli 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zharp
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,94 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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)