@zharp/cli 0.0.0-stage → 0.1.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 +21 -0
- package/README.md +94 -3
- package/dist/cli.js +770 -0
- package/dist/cli.js.map +1 -0
- package/dist/index.d.mts +292 -0
- package/dist/index.d.ts +292 -0
- package/dist/index.js +786 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +727 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +60 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
declare const DEFAULT_URL = "https://api.zharp.io";
|
|
2
|
+
type ArtifactKind = 'sourcemap' | 'minified-source' | 'proguard' | 'dart-symbols' | 'dart-obfuscation-map' | 'dsym';
|
|
3
|
+
interface Connection {
|
|
4
|
+
/** The Zharp API's base URL, e.g. https://api.zharp.io. */
|
|
5
|
+
url: string;
|
|
6
|
+
/** A workspace API key with the `artifacts:write` scope. */
|
|
7
|
+
authToken: string;
|
|
8
|
+
/** The application's ID, as in the dashboard URL. */
|
|
9
|
+
app: string | number;
|
|
10
|
+
}
|
|
11
|
+
interface Artifact {
|
|
12
|
+
kind: ArtifactKind;
|
|
13
|
+
debugId: string;
|
|
14
|
+
/** The file's path or URL (JS), or file name. */
|
|
15
|
+
name: string;
|
|
16
|
+
release?: string;
|
|
17
|
+
arch?: string;
|
|
18
|
+
data: Uint8Array;
|
|
19
|
+
/** Send gzipped (large native symbol files). */
|
|
20
|
+
gzip?: boolean;
|
|
21
|
+
}
|
|
22
|
+
declare class UploadError extends Error {
|
|
23
|
+
readonly status?: number | undefined;
|
|
24
|
+
/** Retrying will not help: a rejected key, a missing app, a bad request. */
|
|
25
|
+
readonly permanent: boolean;
|
|
26
|
+
constructor(message: string, status?: number | undefined,
|
|
27
|
+
/** Retrying will not help: a rejected key, a missing app, a bad request. */
|
|
28
|
+
permanent?: boolean);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* The connection from options and the environment (`ZHARP_AUTH_TOKEN`, `ZHARP_URL`,
|
|
32
|
+
* `ZHARP_APP`). Throws with what is missing.
|
|
33
|
+
*/
|
|
34
|
+
declare function resolveConnection(options: {
|
|
35
|
+
url?: string;
|
|
36
|
+
authToken?: string;
|
|
37
|
+
app?: string | number;
|
|
38
|
+
}): Connection;
|
|
39
|
+
declare function artifactsUrl(connection: Connection): string;
|
|
40
|
+
/** Upload one artifact, retrying network failures, 408, 429 and 5xx with backoff. */
|
|
41
|
+
declare function uploadArtifact(connection: Connection, artifact: Artifact, options?: {
|
|
42
|
+
retries?: number;
|
|
43
|
+
fetch?: typeof fetch;
|
|
44
|
+
backoffMs?: number;
|
|
45
|
+
}): Promise<unknown>;
|
|
46
|
+
|
|
47
|
+
declare const DEBUG_ID_COMMENT = "//# debugId=";
|
|
48
|
+
/**
|
|
49
|
+
* The UUID for a file's content: the first 16 bytes of its SHA-256, with the version and variant
|
|
50
|
+
* bits of a v4 UUID. The same output always gets the same ID, so a rebuild of unchanged code
|
|
51
|
+
* does not need a new upload.
|
|
52
|
+
*/
|
|
53
|
+
declare function debugIdFromContent(content: string | Uint8Array): string;
|
|
54
|
+
/**
|
|
55
|
+
* The runtime registration: ES5, so it is safe in any bundle whatever its target, and wrapped in
|
|
56
|
+
* a try so it can never break the file it is in. The key is a stack taken inside the file — its
|
|
57
|
+
* top frame is the file's own URL or path, as the runtime names it.
|
|
58
|
+
*/
|
|
59
|
+
declare function registrationSnippet(debugId: string): string;
|
|
60
|
+
/** The debug ID already in a file, if it has one. */
|
|
61
|
+
declare function existingDebugId(code: string): string | undefined;
|
|
62
|
+
interface InjectedCode {
|
|
63
|
+
code: string;
|
|
64
|
+
debugId: string;
|
|
65
|
+
/** False when the file already had a debug ID: nothing was changed. */
|
|
66
|
+
changed: boolean;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The file with its debug ID: the registration line and the comment, appended after the code —
|
|
70
|
+
* before a trailing `sourceMappingURL` comment, if there is one. Appending leaves every existing
|
|
71
|
+
* line and column where it was, so the source map stays valid without being rewritten.
|
|
72
|
+
*
|
|
73
|
+
* A file that already has a debug ID is returned as it is, with that ID.
|
|
74
|
+
*/
|
|
75
|
+
declare function injectCode(code: string, options?: {
|
|
76
|
+
stripSourceMappingUrl?: boolean;
|
|
77
|
+
}): InjectedCode;
|
|
78
|
+
/** The code without its trailing `sourceMappingURL` comment — for maps that are not shipped. */
|
|
79
|
+
declare function withoutSourceMappingUrl(code: string): string;
|
|
80
|
+
/**
|
|
81
|
+
* The source map with the debug ID in it, under both spellings in use (`debugId` from the TC39
|
|
82
|
+
* proposal, `debug_id` from earlier tooling). Returns the text unchanged when it already matches.
|
|
83
|
+
*/
|
|
84
|
+
declare function injectMap(mapText: string, debugId: string): {
|
|
85
|
+
text: string;
|
|
86
|
+
changed: boolean;
|
|
87
|
+
hasSourcesContent: boolean;
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* The GNU build ID of an ELF file — what a Dart AOT snapshot prints as `build_id: '…'` in an
|
|
92
|
+
* obfuscated stack, and what its `--split-debug-info` symbol file carries too.
|
|
93
|
+
*/
|
|
94
|
+
interface ElfInfo {
|
|
95
|
+
/** Lowercase hex, as Dart prints it. */
|
|
96
|
+
buildId?: string;
|
|
97
|
+
bits: 32 | 64;
|
|
98
|
+
littleEndian: boolean;
|
|
99
|
+
/** e_machine, as an architecture name where known. */
|
|
100
|
+
arch?: string;
|
|
101
|
+
}
|
|
102
|
+
/** Parse just enough of an ELF file to find its GNU build ID. Throws on a file that is not ELF. */
|
|
103
|
+
declare function readElf(data: Uint8Array): ElfInfo;
|
|
104
|
+
|
|
105
|
+
/** A glob (`**`, `*`, `?`), a regular expression, or a list of them. */
|
|
106
|
+
type Pattern = string | RegExp | Array<string | RegExp>;
|
|
107
|
+
/** A glob as a regular expression over a relative path with forward slashes. */
|
|
108
|
+
declare function globToRegExp(glob: string): RegExp;
|
|
109
|
+
/** A filter over relative paths: in `include` (when given) and not in `exclude`. */
|
|
110
|
+
declare function pathFilter(include?: Pattern, exclude?: Pattern): (relativePath: string) => boolean;
|
|
111
|
+
|
|
112
|
+
/** Where progress goes. The CLI prints it; the bundler plugins prefix it with their name. */
|
|
113
|
+
interface Logger {
|
|
114
|
+
info(message: string): void;
|
|
115
|
+
warn(message: string): void;
|
|
116
|
+
}
|
|
117
|
+
declare const consoleLogger: (prefix?: string) => Logger;
|
|
118
|
+
declare const silentLogger: Logger;
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The LC_UUID of each architecture in a Mach-O file (thin or universal) — the UUID an iOS crash
|
|
122
|
+
* report lists for each binary image, and the key its dSYM is found by.
|
|
123
|
+
*/
|
|
124
|
+
interface MachOImage {
|
|
125
|
+
/** Uppercase with dashes, as the iOS SDK (`UUID.uuidString`) and Apple's tools print it. */
|
|
126
|
+
uuid: string;
|
|
127
|
+
arch: string;
|
|
128
|
+
/** Where the image is in the file: the whole file, or its slice of a universal one. */
|
|
129
|
+
offset: number;
|
|
130
|
+
size: number;
|
|
131
|
+
}
|
|
132
|
+
/** The images in a Mach-O file: one for a thin file, one per slice for a universal one. */
|
|
133
|
+
declare function readMachO(data: Uint8Array): MachOImage[];
|
|
134
|
+
|
|
135
|
+
interface NativeUploadOptions {
|
|
136
|
+
release?: string;
|
|
137
|
+
dryRun?: boolean;
|
|
138
|
+
logger?: Logger;
|
|
139
|
+
fetch?: typeof fetch;
|
|
140
|
+
retries?: number;
|
|
141
|
+
}
|
|
142
|
+
/** Upload an R8/ProGuard `mapping.txt` under the build's UUID (the one the Gradle plugin put in the app). */
|
|
143
|
+
declare function uploadProguard(mappingFile: string, uuid: string, connection: Connection | null, options?: NativeUploadOptions): Promise<Artifact[]>;
|
|
144
|
+
interface DartSymbolFile {
|
|
145
|
+
path: string;
|
|
146
|
+
buildId: string;
|
|
147
|
+
os?: string;
|
|
148
|
+
arch?: string;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* The Dart symbol files in a `--split-debug-info` directory (`app.android-arm64.symbols`, …), or
|
|
152
|
+
* the one file given. The debug ID is the ELF GNU build ID — the `build_id` an obfuscated
|
|
153
|
+
* stack prints.
|
|
154
|
+
*/
|
|
155
|
+
declare function findDartSymbols(path: string, logger?: Logger): DartSymbolFile[];
|
|
156
|
+
/**
|
|
157
|
+
* The obfuscation map Flutter writes with
|
|
158
|
+
* `--extra-gen-snapshot-options=--save-obfuscation-map=<file>`: `obfuscation.json` or
|
|
159
|
+
* `*.obfuscation.json`, in the symbols directory or the directory next to it.
|
|
160
|
+
*/
|
|
161
|
+
declare function findObfuscationMap(symbolsPath: string): string | undefined;
|
|
162
|
+
interface DartSymbolsUploadOptions extends NativeUploadOptions {
|
|
163
|
+
/** The obfuscation map to upload with the symbols. Default: found next to them (see findObfuscationMap). */
|
|
164
|
+
obfuscationMap?: string;
|
|
165
|
+
}
|
|
166
|
+
declare function uploadDartSymbols(path: string, connection: Connection | null, options?: DartSymbolsUploadOptions): Promise<Artifact[]>;
|
|
167
|
+
interface DsymImage {
|
|
168
|
+
/** The DWARF file inside the .dSYM bundle. */
|
|
169
|
+
path: string;
|
|
170
|
+
uuid: string;
|
|
171
|
+
arch: string;
|
|
172
|
+
offset: number;
|
|
173
|
+
size: number;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* The binary images in a .dSYM bundle, a folder of them (Xcode's `$DWARF_DSYM_FOLDER_PATH`), or
|
|
177
|
+
* a DWARF file itself. Universal files give one image per architecture.
|
|
178
|
+
*/
|
|
179
|
+
declare function findDsymImages(path: string): DsymImage[];
|
|
180
|
+
declare function uploadDsyms(path: string, connection: Connection | null, options?: NativeUploadOptions): Promise<Artifact[]>;
|
|
181
|
+
|
|
182
|
+
interface SourceFile {
|
|
183
|
+
/** Absolute path of the JavaScript file. */
|
|
184
|
+
file: string;
|
|
185
|
+
/** Absolute path of its source map. */
|
|
186
|
+
map: string;
|
|
187
|
+
/** Path of the file relative to the directory, with forward slashes. */
|
|
188
|
+
name: string;
|
|
189
|
+
mapName: string;
|
|
190
|
+
}
|
|
191
|
+
interface FindOptions {
|
|
192
|
+
include?: Pattern;
|
|
193
|
+
exclude?: Pattern;
|
|
194
|
+
/** Only these files (absolute paths) — the bundler plugins pass what the build wrote. */
|
|
195
|
+
files?: string[];
|
|
196
|
+
}
|
|
197
|
+
/** The source map a JS file has: `<file>.map` next to it, or the file its `sourceMappingURL` names. */
|
|
198
|
+
declare function mapFor(file: string, code?: string): string | undefined;
|
|
199
|
+
/** Every JS file under `dir` that has a source map. */
|
|
200
|
+
declare function findSourceFiles(dir: string, options?: FindOptions): SourceFile[];
|
|
201
|
+
interface InjectOptions extends FindOptions {
|
|
202
|
+
/** Remove the `sourceMappingURL` comment too — for maps that are deleted after upload. */
|
|
203
|
+
stripSourceMappingUrl?: boolean;
|
|
204
|
+
dryRun?: boolean;
|
|
205
|
+
logger?: Logger;
|
|
206
|
+
}
|
|
207
|
+
interface InjectedFile extends SourceFile {
|
|
208
|
+
debugId: string;
|
|
209
|
+
/** False when the file already had this debug ID. */
|
|
210
|
+
changed: boolean;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Add a debug ID to every JS file under `dir` that has a source map, and to the map. Running it
|
|
214
|
+
* again changes nothing: a file that has a debug ID keeps it.
|
|
215
|
+
*/
|
|
216
|
+
declare function injectDirectory(dir: string, options?: InjectOptions): InjectedFile[];
|
|
217
|
+
interface UploadOptions extends FindOptions {
|
|
218
|
+
release?: string;
|
|
219
|
+
/** Delete the .map files once they are uploaded. */
|
|
220
|
+
deleteAfter?: boolean;
|
|
221
|
+
/** Also strip the `sourceMappingURL` comments that pointed at deleted maps. */
|
|
222
|
+
stripSourceMappingUrl?: boolean;
|
|
223
|
+
dryRun?: boolean;
|
|
224
|
+
concurrency?: number;
|
|
225
|
+
logger?: Logger;
|
|
226
|
+
fetch?: typeof fetch;
|
|
227
|
+
retries?: number;
|
|
228
|
+
}
|
|
229
|
+
interface UploadResult {
|
|
230
|
+
files: number;
|
|
231
|
+
artifacts: number;
|
|
232
|
+
bytes: number;
|
|
233
|
+
deleted: string[];
|
|
234
|
+
/** Files with a map but no debug ID: run inject first. */
|
|
235
|
+
skipped: string[];
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* Upload every JS file under `dir` that has a debug ID, with its source map, keyed by that ID.
|
|
239
|
+
* `connection` may be null in a dry run.
|
|
240
|
+
*/
|
|
241
|
+
declare function uploadSourcemaps(dir: string, connection: Connection | null, options?: UploadOptions): Promise<UploadResult>;
|
|
242
|
+
/** Delete these files' source maps (and, if asked, the comments pointing at them). */
|
|
243
|
+
declare function deleteSourcemaps(files: SourceFile[], options?: {
|
|
244
|
+
stripSourceMappingUrl?: boolean;
|
|
245
|
+
}): string[];
|
|
246
|
+
|
|
247
|
+
declare const VERSION = "0.1.0";
|
|
248
|
+
|
|
249
|
+
interface ZharpPluginOptions {
|
|
250
|
+
/** The application's ID (the number in its dashboard URL). Default `ZHARP_APP`. */
|
|
251
|
+
app?: string | number;
|
|
252
|
+
/** File the upload under this release. Default `ZHARP_RELEASE`, or the commit SHA CI provides. */
|
|
253
|
+
release?: string;
|
|
254
|
+
/** A workspace API key with the `artifacts:write` scope. Default `ZHARP_AUTH_TOKEN`. */
|
|
255
|
+
authToken?: string;
|
|
256
|
+
/** The Zharp API. Default `ZHARP_URL`, or https://api.zharp.io. */
|
|
257
|
+
url?: string;
|
|
258
|
+
/** Only these output files (globs relative to the output directory, or regular expressions). */
|
|
259
|
+
include?: Pattern;
|
|
260
|
+
/** Not these output files. */
|
|
261
|
+
exclude?: Pattern;
|
|
262
|
+
/** Delete the .map files from the output once uploaded, so they are not deployed. Default true. */
|
|
263
|
+
deleteSourcemapsAfterUpload?: boolean;
|
|
264
|
+
/** Inject debug IDs and report what would be uploaded; upload and delete nothing. */
|
|
265
|
+
dryRun?: boolean;
|
|
266
|
+
/** Run on every build, not only production ones. */
|
|
267
|
+
force?: boolean;
|
|
268
|
+
/** Do nothing at all. */
|
|
269
|
+
disabled?: boolean;
|
|
270
|
+
/** Fail the build when the upload fails. Default false: a warning, and the build goes on. */
|
|
271
|
+
failOnError?: boolean;
|
|
272
|
+
/** No progress output (warnings still print). */
|
|
273
|
+
silent?: boolean;
|
|
274
|
+
}
|
|
275
|
+
/** A release name from the options, the environment, or the commit SHA a CI system provides. */
|
|
276
|
+
declare function defaultRelease(options: ZharpPluginOptions): string | undefined;
|
|
277
|
+
declare function pluginLogger(name: string, options: ZharpPluginOptions): Logger;
|
|
278
|
+
interface ProcessBuildResult {
|
|
279
|
+
injected: InjectedFile[];
|
|
280
|
+
uploaded: boolean;
|
|
281
|
+
deleted: string[];
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Inject, upload, delete — for the files a build just wrote to `dir` (or every file there when
|
|
285
|
+
* `files` is not given).
|
|
286
|
+
*/
|
|
287
|
+
declare function processBuildOutput(dir: string, options: ZharpPluginOptions, context?: {
|
|
288
|
+
files?: string[];
|
|
289
|
+
logger?: Logger;
|
|
290
|
+
}): Promise<ProcessBuildResult>;
|
|
291
|
+
|
|
292
|
+
export { type Artifact, type ArtifactKind, type Connection, DEBUG_ID_COMMENT, DEFAULT_URL, type DartSymbolsUploadOptions, type ElfInfo, type InjectOptions, type InjectedFile, type Logger, type MachOImage, type NativeUploadOptions, type Pattern, type ProcessBuildResult, type SourceFile, UploadError, type UploadOptions, type UploadResult, VERSION, type ZharpPluginOptions, artifactsUrl, consoleLogger, debugIdFromContent, defaultRelease, deleteSourcemaps, existingDebugId, findDartSymbols, findDsymImages, findObfuscationMap, findSourceFiles, globToRegExp, injectCode, injectDirectory, injectMap, mapFor, pathFilter, pluginLogger, processBuildOutput, readElf, readMachO, registrationSnippet, resolveConnection, silentLogger, uploadArtifact, uploadDartSymbols, uploadDsyms, uploadProguard, uploadSourcemaps, withoutSourceMappingUrl };
|