@noldova/tools.pipelines 0.0.0-stage → 0.0.2
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 +202 -2
- package/api/index.d.ts +1490 -0
- package/api/index.js +27 -0
- package/api/index.js.map +1 -0
- package/exceptions/pipeline.exception.js +14 -0
- package/exceptions/pipeline.exception.js.map +1 -0
- package/exceptions/process.exception.js +17 -0
- package/exceptions/process.exception.js.map +1 -0
- package/exceptions/version.exception.js +15 -0
- package/exceptions/version.exception.js.map +1 -0
- package/interfaces/i-registry-host.js +9 -0
- package/interfaces/i-registry-host.js.map +1 -0
- package/interfaces/i-step-output.js +9 -0
- package/interfaces/i-step-output.js.map +1 -0
- package/interfaces/i-step.js +9 -0
- package/interfaces/i-step.js.map +1 -0
- package/interfaces/i-tag-host.js +9 -0
- package/interfaces/i-tag-host.js.map +1 -0
- package/models/archive-check.js +16 -0
- package/models/archive-check.js.map +1 -0
- package/models/package-archive.js +16 -0
- package/models/package-archive.js.map +1 -0
- package/models/process-result.js +22 -0
- package/models/process-result.js.map +1 -0
- package/models/step-result.js +22 -0
- package/models/step-result.js.map +1 -0
- package/models/version.js +85 -0
- package/models/version.js.map +1 -0
- package/package.json +24 -4
- package/resources.js +310 -0
- package/resources.js.map +1 -0
- package/services/archive-step.js +130 -0
- package/services/archive-step.js.map +1 -0
- package/services/command-line.js +34 -0
- package/services/command-line.js.map +1 -0
- package/services/git.js +60 -0
- package/services/git.js.map +1 -0
- package/services/nightly-step.js +82 -0
- package/services/nightly-step.js.map +1 -0
- package/services/npm.js +43 -0
- package/services/npm.js.map +1 -0
- package/services/process-runner.js +34 -0
- package/services/process-runner.js.map +1 -0
- package/services/prune-step.js +102 -0
- package/services/prune-step.js.map +1 -0
- package/services/publish-step.js +117 -0
- package/services/publish-step.js.map +1 -0
- package/services/source-step.js +43 -0
- package/services/source-step.js.map +1 -0
- package/services/tag-step.js +48 -0
- package/services/tag-step.js.map +1 -0
- package/services/tar.js +23 -0
- package/services/tar.js.map +1 -0
package/api/index.d.ts
ADDED
|
@@ -0,0 +1,1490 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Copyright (c) Noldova.
|
|
4
|
+
*
|
|
5
|
+
* This source code is licensed under the license found in the
|
|
6
|
+
* LICENSE file in the root directory of this source tree.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { Exception, type ExceptionOptions } from "@noldova/context.exceptions";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* The abstract base of this package's exceptions; catch it to handle any of
|
|
13
|
+
* them. A check that finds something wrong returns a failed
|
|
14
|
+
* {@link StepResult} instead.
|
|
15
|
+
*/
|
|
16
|
+
export declare abstract class PipelineException extends Exception {
|
|
17
|
+
/**
|
|
18
|
+
* Initializes the message and the cause for a derived exception.
|
|
19
|
+
*
|
|
20
|
+
* @param message The complete explanation, kept as given.
|
|
21
|
+
* @param options The failure that caused this one, as its `cause`.
|
|
22
|
+
* Omitted, the exception has no cause.
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* import type { ExceptionOptions } from "@noldova/context.exceptions";
|
|
26
|
+
* import { PipelineException } from "@noldova/tools.pipelines";
|
|
27
|
+
*
|
|
28
|
+
* class StepException extends PipelineException {
|
|
29
|
+
* public constructor(message: string, options?: ExceptionOptions) {
|
|
30
|
+
* super(message, options);
|
|
31
|
+
* }
|
|
32
|
+
* }
|
|
33
|
+
* const exception = new StepException("The step could not run.");
|
|
34
|
+
* exception.name; // "StepException"
|
|
35
|
+
* exception instanceof PipelineException; // true
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
protected constructor(message: string, options?: ExceptionOptions);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The exception that is thrown when a program cannot start, or when it ends
|
|
43
|
+
* in a way that no check expects, such as git failing to read a file it
|
|
44
|
+
* reported as present.
|
|
45
|
+
*/
|
|
46
|
+
export declare class ProcessException extends PipelineException {
|
|
47
|
+
/**
|
|
48
|
+
* The program that could not start or that failed, such as `"git"`.
|
|
49
|
+
*/
|
|
50
|
+
public readonly program: string;
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Creates the exception for a program.
|
|
54
|
+
*
|
|
55
|
+
* @param program The program that could not start or that failed.
|
|
56
|
+
* @param message The complete explanation, kept as given, such as the
|
|
57
|
+
* command that failed and what it wrote to its error output. Omitted, it is
|
|
58
|
+
* `The program "<program>" failed.`
|
|
59
|
+
* @param options The failure that caused this one, such as the error a
|
|
60
|
+
* program that cannot start reports. Omitted, the exception has no cause.
|
|
61
|
+
* @example
|
|
62
|
+
* ```ts
|
|
63
|
+
* import { ExceptionOptions } from "@noldova/context.exceptions";
|
|
64
|
+
* import { PipelineException, ProcessException } from "@noldova/tools.pipelines";
|
|
65
|
+
*
|
|
66
|
+
* const exception = new ProcessException("git", "\"git\" could not start: spawn git ENOENT", new ExceptionOptions(new Error("spawn git ENOENT")));
|
|
67
|
+
* exception.program; // "git"
|
|
68
|
+
* exception.name; // "ProcessException"
|
|
69
|
+
* exception instanceof PipelineException; // true
|
|
70
|
+
* new ProcessException("git").message; // "The program \"git\" failed."
|
|
71
|
+
* ```
|
|
72
|
+
*/
|
|
73
|
+
public constructor(program: string, message?: string, options?: ExceptionOptions);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The exception that is thrown when a text is not a version, when a
|
|
78
|
+
* version's part is not a whole number from 0 to `Number.MAX_SAFE_INTEGER`,
|
|
79
|
+
* or when a nightly version's date is not a calendar date.
|
|
80
|
+
*/
|
|
81
|
+
export declare class VersionException extends PipelineException {
|
|
82
|
+
/**
|
|
83
|
+
* Creates the exception with the explanation it reports.
|
|
84
|
+
*
|
|
85
|
+
* @param message The complete explanation, kept as given, such as which
|
|
86
|
+
* text was not a version and the form a version takes. Omitted, it is
|
|
87
|
+
* `The text is not a version.`
|
|
88
|
+
* @param options The failure that caused this one, as its `cause`.
|
|
89
|
+
* Omitted, the exception has no cause.
|
|
90
|
+
* @example
|
|
91
|
+
* ```ts
|
|
92
|
+
* import { PipelineException, VersionException } from "@noldova/tools.pipelines";
|
|
93
|
+
*
|
|
94
|
+
* const exception = new VersionException("\"1.4\" is not a version.");
|
|
95
|
+
* exception.name; // "VersionException"
|
|
96
|
+
* exception instanceof PipelineException; // true
|
|
97
|
+
* new VersionException().message; // "The text is not a version."
|
|
98
|
+
* ```
|
|
99
|
+
*/
|
|
100
|
+
public constructor(message?: string, options?: ExceptionOptions);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* A version of the form `major.minor.patch`, each part a whole number from 0
|
|
105
|
+
* to `Number.MAX_SAFE_INTEGER`, or a nightly version of the form
|
|
106
|
+
* `major.minor.patch-nightly.YYYYMMDD`, which adds the date it was built. A
|
|
107
|
+
* version never changes after it is created; versions compare part by part,
|
|
108
|
+
* major first, and a nightly version comes before the release with the same
|
|
109
|
+
* three parts.
|
|
110
|
+
*/
|
|
111
|
+
export declare class Version {
|
|
112
|
+
/**
|
|
113
|
+
* The major part, the first of the three.
|
|
114
|
+
*/
|
|
115
|
+
public readonly major: number;
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* The minor part, the second of the three.
|
|
119
|
+
*/
|
|
120
|
+
public readonly minor: number;
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The patch part, the last of the three.
|
|
124
|
+
*/
|
|
125
|
+
public readonly patch: number;
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* A nightly version's date, written `YYYYMMDD`, such as `20261101`; `null`
|
|
129
|
+
* for a release.
|
|
130
|
+
*/
|
|
131
|
+
public readonly nightlyDate: string | null;
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Creates a version from its three parts and, for a nightly version, its
|
|
135
|
+
* date.
|
|
136
|
+
*
|
|
137
|
+
* @param major The major part: a whole number from 0 to
|
|
138
|
+
* `Number.MAX_SAFE_INTEGER`.
|
|
139
|
+
* @param minor The minor part, in the same range.
|
|
140
|
+
* @param patch The patch part, in the same range.
|
|
141
|
+
* @param nightlyDate A nightly version's date: a calendar date written
|
|
142
|
+
* `YYYYMMDD`, from year 1000, such as `20261101`. Omitted or `null`, the
|
|
143
|
+
* version is a release.
|
|
144
|
+
* @throws VersionException, synchronously, if a part is negative, not a
|
|
145
|
+
* whole number, or greater than `Number.MAX_SAFE_INTEGER`, or if the date
|
|
146
|
+
* is not a calendar date written that way.
|
|
147
|
+
* @example
|
|
148
|
+
* ```ts
|
|
149
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
150
|
+
*
|
|
151
|
+
* new Version(1, 4, 0).toString(); // "1.4.0"
|
|
152
|
+
* new Version(1, 4, 1, "20261101").toString(); // "1.4.1-nightly.20261101"
|
|
153
|
+
* // new Version(1, -1, 0) and new Version(1, 4, 1, "20261131") throw VersionException.
|
|
154
|
+
* ```
|
|
155
|
+
*/
|
|
156
|
+
public constructor(major: number, minor: number, patch: number, nightlyDate?: string | null);
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Reads a version from its text.
|
|
160
|
+
*
|
|
161
|
+
* @param text The version's text: exactly three whole numbers joined by
|
|
162
|
+
* dots, each without a sign or a leading zero, such as `1.4.0`, optionally
|
|
163
|
+
* followed by `-nightly.` and a calendar date written `YYYYMMDD`, such as
|
|
164
|
+
* `1.4.1-nightly.20261101`, with nothing before or after them.
|
|
165
|
+
* @returns A new version with the text's parts and, for a nightly version,
|
|
166
|
+
* its date.
|
|
167
|
+
* @throws VersionException, synchronously, if the text is not of that form,
|
|
168
|
+
* if a part is greater than `Number.MAX_SAFE_INTEGER`, or if the date is
|
|
169
|
+
* not a calendar date.
|
|
170
|
+
* @example
|
|
171
|
+
* ```ts
|
|
172
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
173
|
+
*
|
|
174
|
+
* Version.parse("1.4.0").minor; // 4
|
|
175
|
+
* Version.parse("1.4.1-nightly.20261101").nightlyDate; // "20261101"
|
|
176
|
+
* // Version.parse("1.04.0"), Version.parse("v1.4.0") and
|
|
177
|
+
* // Version.parse("1.4.0-beta.1") throw VersionException.
|
|
178
|
+
* ```
|
|
179
|
+
*/
|
|
180
|
+
public static parse(text: string): Version;
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Tells why a text is not a version, without throwing, for a text that
|
|
184
|
+
* comes from outside the program, such as a command-line value.
|
|
185
|
+
*
|
|
186
|
+
* @param text The text to check, of the form {@link Version.parse} reads.
|
|
187
|
+
* @returns `null` if {@link Version.parse} reads the text, otherwise the
|
|
188
|
+
* message its `VersionException` would carry: that the text is not of the
|
|
189
|
+
* form, that a part is greater than `Number.MAX_SAFE_INTEGER`, or that the
|
|
190
|
+
* date is not a calendar date.
|
|
191
|
+
* @example
|
|
192
|
+
* ```ts
|
|
193
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
194
|
+
*
|
|
195
|
+
* Version.validate("1.4.0"); // null
|
|
196
|
+
* Version.validate("1.4"); // "\"1.4\" is not a version: a version is major.minor.patch, …"
|
|
197
|
+
* Version.validate("1.4.1-nightly.20261131"); // "A nightly version's date must be a calendar date …"
|
|
198
|
+
* ```
|
|
199
|
+
*/
|
|
200
|
+
public static validate(text: string): string | null;
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Compares this version with another, major part first, then minor, then
|
|
204
|
+
* patch; with the same three parts, a nightly version comes before the
|
|
205
|
+
* release, and nightly versions come in the order of their dates.
|
|
206
|
+
*
|
|
207
|
+
* @param other The version to compare with.
|
|
208
|
+
* @returns -1 if this version comes before the other, 0 if both are the
|
|
209
|
+
* same version, and 1 if this version comes after it.
|
|
210
|
+
* @example
|
|
211
|
+
* ```ts
|
|
212
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
213
|
+
*
|
|
214
|
+
* Version.parse("1.4.0").compareTo(Version.parse("1.10.0")); // -1
|
|
215
|
+
* Version.parse("2.0.0").compareTo(Version.parse("1.99.99")); // 1
|
|
216
|
+
* Version.parse("1.4.1-nightly.20261101").compareTo(Version.parse("1.4.1")); // -1
|
|
217
|
+
* Version.parse("1.4.1-nightly.20261102").compareTo(Version.parse("1.4.1-nightly.20261101")); // 1
|
|
218
|
+
* ```
|
|
219
|
+
*/
|
|
220
|
+
public compareTo(other: Version): number;
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Tells whether another version has the same three parts and the same
|
|
224
|
+
* nightly date, or is a release as this one is.
|
|
225
|
+
*
|
|
226
|
+
* @param other The version to compare with.
|
|
227
|
+
* @returns `true` if both are the same version, otherwise `false`.
|
|
228
|
+
* @example
|
|
229
|
+
* ```ts
|
|
230
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
231
|
+
*
|
|
232
|
+
* Version.parse("1.4.0").equals(new Version(1, 4, 0)); // true
|
|
233
|
+
* Version.parse("1.4.1").equals(Version.parse("1.4.1-nightly.20261101")); // false
|
|
234
|
+
* ```
|
|
235
|
+
*/
|
|
236
|
+
public equals(other: Version): boolean;
|
|
237
|
+
|
|
238
|
+
/**
|
|
239
|
+
* Writes the version as its text.
|
|
240
|
+
*
|
|
241
|
+
* @returns The three parts joined by dots, such as `1.4.0`, followed for a
|
|
242
|
+
* nightly version by `-nightly.` and its date, such as
|
|
243
|
+
* `1.4.1-nightly.20261101`; reading it with {@link Version.parse} gives an
|
|
244
|
+
* equal version.
|
|
245
|
+
* @example
|
|
246
|
+
* ```ts
|
|
247
|
+
* import { Version } from "@noldova/tools.pipelines";
|
|
248
|
+
*
|
|
249
|
+
* new Version(1, 4, 0).toString(); // "1.4.0"
|
|
250
|
+
* `${new Version(0, 0, 4, "20261101")}`; // "0.0.4-nightly.20261101"
|
|
251
|
+
* ```
|
|
252
|
+
*/
|
|
253
|
+
public toString(): string;
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* What a program wrote and how it ended.
|
|
258
|
+
*/
|
|
259
|
+
export declare class ProcessResult {
|
|
260
|
+
/**
|
|
261
|
+
* The program's exit code, `0` when it succeeded; `null` when it ended
|
|
262
|
+
* through a signal instead.
|
|
263
|
+
*/
|
|
264
|
+
public readonly exitCode: number | null;
|
|
265
|
+
|
|
266
|
+
/**
|
|
267
|
+
* Everything the program wrote to its standard output, as UTF-8 text.
|
|
268
|
+
*/
|
|
269
|
+
public readonly output: string;
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* Everything the program wrote to its error output, as UTF-8 text.
|
|
273
|
+
*/
|
|
274
|
+
public readonly errorOutput: string;
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Creates the result of a program's run.
|
|
278
|
+
*
|
|
279
|
+
* @param exitCode The exit code, or `null` when the program ended through
|
|
280
|
+
* a signal.
|
|
281
|
+
* @param output What the program wrote to its standard output.
|
|
282
|
+
* @param errorOutput What the program wrote to its error output.
|
|
283
|
+
* @example
|
|
284
|
+
* ```ts
|
|
285
|
+
* import { ProcessResult } from "@noldova/tools.pipelines";
|
|
286
|
+
*
|
|
287
|
+
* const result = new ProcessResult(0, "git version 2.55.0\n", "");
|
|
288
|
+
* result.isSuccessful; // true
|
|
289
|
+
* ```
|
|
290
|
+
*/
|
|
291
|
+
public constructor(exitCode: number | null, output: string, errorOutput: string);
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Whether the program succeeded, its exit code `0`.
|
|
295
|
+
*
|
|
296
|
+
* @example
|
|
297
|
+
* ```ts
|
|
298
|
+
* import { ProcessResult } from "@noldova/tools.pipelines";
|
|
299
|
+
*
|
|
300
|
+
* new ProcessResult(1, "", "").isSuccessful; // false
|
|
301
|
+
* new ProcessResult(null, "", "").isSuccessful; // false, the program ended through a signal
|
|
302
|
+
* ```
|
|
303
|
+
*/
|
|
304
|
+
public get isSuccessful(): boolean;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* What a step found: that it succeeded, or that it failed, each with the
|
|
309
|
+
* message a pipeline's log shows. A failed check is a result, not an
|
|
310
|
+
* exception; a result never changes after it is created.
|
|
311
|
+
*/
|
|
312
|
+
export declare class StepResult {
|
|
313
|
+
/**
|
|
314
|
+
* Whether the step succeeded.
|
|
315
|
+
*/
|
|
316
|
+
public readonly isSuccessful: boolean;
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* The message for the log: what the step did, or what is wrong.
|
|
320
|
+
*/
|
|
321
|
+
public readonly message: string;
|
|
322
|
+
|
|
323
|
+
private constructor();
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Creates the result of a step that succeeded.
|
|
327
|
+
*
|
|
328
|
+
* @param message What the step did, such as what it checked.
|
|
329
|
+
* @returns A result whose `isSuccessful` is `true`.
|
|
330
|
+
* @example
|
|
331
|
+
* ```ts
|
|
332
|
+
* import { StepResult } from "@noldova/tools.pipelines";
|
|
333
|
+
*
|
|
334
|
+
* StepResult.succeeded("The archives hold 0.0.4.").isSuccessful; // true
|
|
335
|
+
* ```
|
|
336
|
+
*/
|
|
337
|
+
public static succeeded(message: string): StepResult;
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* Creates the result of a step that failed.
|
|
341
|
+
*
|
|
342
|
+
* @param message What is wrong, written so the reader can fix it.
|
|
343
|
+
* @returns A result whose `isSuccessful` is `false`.
|
|
344
|
+
* @example
|
|
345
|
+
* ```ts
|
|
346
|
+
* import { StepResult } from "@noldova/tools.pipelines";
|
|
347
|
+
*
|
|
348
|
+
* StepResult.failed("Commit 225059f… is not on origin/main.").isSuccessful; // false
|
|
349
|
+
* ```
|
|
350
|
+
*/
|
|
351
|
+
public static failed(message: string): StepResult;
|
|
352
|
+
}
|
|
353
|
+
|
|
354
|
+
/**
|
|
355
|
+
* A package and the path of its archive, as {@link ArchiveStep} checked it.
|
|
356
|
+
*/
|
|
357
|
+
export declare class PackageArchive {
|
|
358
|
+
/**
|
|
359
|
+
* The package's name, such as `@noldova/tools.pipelines`.
|
|
360
|
+
*/
|
|
361
|
+
public readonly packageName: string;
|
|
362
|
+
|
|
363
|
+
/**
|
|
364
|
+
* The archive's path, such as
|
|
365
|
+
* `archives/noldova-tools.pipelines-0.0.4.tgz`.
|
|
366
|
+
*/
|
|
367
|
+
public readonly filePath: string;
|
|
368
|
+
|
|
369
|
+
/**
|
|
370
|
+
* Creates the pair.
|
|
371
|
+
*
|
|
372
|
+
* @param packageName The package's name.
|
|
373
|
+
* @param filePath The archive's path.
|
|
374
|
+
* @example
|
|
375
|
+
* ```ts
|
|
376
|
+
* import { PackageArchive } from "@noldova/tools.pipelines";
|
|
377
|
+
*
|
|
378
|
+
* const archive = new PackageArchive("@noldova/tools.pipelines", "archives/noldova-tools.pipelines-0.0.4.tgz");
|
|
379
|
+
* ```
|
|
380
|
+
*/
|
|
381
|
+
public constructor(packageName: string, filePath: string);
|
|
382
|
+
}
|
|
383
|
+
|
|
384
|
+
/**
|
|
385
|
+
* What {@link ArchiveStep.checkAsync} found: its result, and the archives it
|
|
386
|
+
* checked when it succeeded.
|
|
387
|
+
*/
|
|
388
|
+
export declare class ArchiveCheck {
|
|
389
|
+
/**
|
|
390
|
+
* The archive step's result.
|
|
391
|
+
*/
|
|
392
|
+
public readonly result: StepResult;
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* Each expected package with its archive, by package name, when the result
|
|
396
|
+
* succeeded; none when it failed.
|
|
397
|
+
*/
|
|
398
|
+
public readonly archives: readonly PackageArchive[];
|
|
399
|
+
|
|
400
|
+
/**
|
|
401
|
+
* Creates the check.
|
|
402
|
+
*
|
|
403
|
+
* @param result The archive step's result.
|
|
404
|
+
* @param archives The archives it checked.
|
|
405
|
+
* @example
|
|
406
|
+
* ```ts
|
|
407
|
+
* import { ArchiveCheck, StepResult } from "@noldova/tools.pipelines";
|
|
408
|
+
*
|
|
409
|
+
* const check = new ArchiveCheck(StepResult.failed("There is no folder archives."), []);
|
|
410
|
+
* ```
|
|
411
|
+
*/
|
|
412
|
+
public constructor(result: StepResult, archives: readonly PackageArchive[]);
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
/**
|
|
416
|
+
* A step of a pipeline that a {@link CommandLine} runs by its name, such as
|
|
417
|
+
* {@link SourceStep}.
|
|
418
|
+
*/
|
|
419
|
+
export declare interface IStep {
|
|
420
|
+
/**
|
|
421
|
+
* The name a command line gives to run the step, such as `"source"`.
|
|
422
|
+
*/
|
|
423
|
+
readonly name: string;
|
|
424
|
+
|
|
425
|
+
/**
|
|
426
|
+
* The values the step takes, as a usage line shows them, such as
|
|
427
|
+
* `"<version> <commit>"`.
|
|
428
|
+
*/
|
|
429
|
+
readonly usage: string;
|
|
430
|
+
|
|
431
|
+
/**
|
|
432
|
+
* Runs the step.
|
|
433
|
+
*
|
|
434
|
+
* @param values The values given after the step's name, in order. The step
|
|
435
|
+
* checks them itself, so a wrong number or form fails the step instead of
|
|
436
|
+
* throwing.
|
|
437
|
+
* @returns A promise of what the step found. It never rejects for a failed
|
|
438
|
+
* check, only when something else goes wrong, such as with a
|
|
439
|
+
* {@link PipelineException}.
|
|
440
|
+
* @example
|
|
441
|
+
* ```ts
|
|
442
|
+
* import { type IStep, StepResult } from "@noldova/tools.pipelines";
|
|
443
|
+
*
|
|
444
|
+
* const step: IStep = {
|
|
445
|
+
* name: "greet",
|
|
446
|
+
* usage: "<name>",
|
|
447
|
+
* runAsync: async values => StepResult.succeeded(`Hello, ${values.join(" ")}.`)
|
|
448
|
+
* };
|
|
449
|
+
* (await step.runAsync(["world"])).message; // "Hello, world."
|
|
450
|
+
* ```
|
|
451
|
+
*/
|
|
452
|
+
runAsync(values: readonly string[]): Promise<StepResult>;
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/**
|
|
456
|
+
* Where a {@link CommandLine} writes a step's message; each pipeline host
|
|
457
|
+
* implements it, such as by writing a failure as the host's error annotation.
|
|
458
|
+
*/
|
|
459
|
+
export declare interface IStepOutput {
|
|
460
|
+
/**
|
|
461
|
+
* Writes the message of a step that succeeded.
|
|
462
|
+
*
|
|
463
|
+
* @param message The step's message.
|
|
464
|
+
* @example
|
|
465
|
+
* ```ts
|
|
466
|
+
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
467
|
+
*
|
|
468
|
+
* const output: IStepOutput = {
|
|
469
|
+
* writeSuccess: message => console.log(message),
|
|
470
|
+
* writeFailure: message => console.error(message)
|
|
471
|
+
* };
|
|
472
|
+
* output.writeSuccess("Commit 225059f… is on origin/main, and its version.json holds 0.0.4.");
|
|
473
|
+
* ```
|
|
474
|
+
*/
|
|
475
|
+
writeSuccess(message: string): void;
|
|
476
|
+
|
|
477
|
+
/**
|
|
478
|
+
* Writes the message of a step that failed, or the usage line when the
|
|
479
|
+
* command line names no step it has.
|
|
480
|
+
*
|
|
481
|
+
* @param message What is wrong.
|
|
482
|
+
* @example
|
|
483
|
+
* ```ts
|
|
484
|
+
* import type { IStepOutput } from "@noldova/tools.pipelines";
|
|
485
|
+
*
|
|
486
|
+
* const output: IStepOutput = {
|
|
487
|
+
* writeSuccess: message => console.log(message),
|
|
488
|
+
* writeFailure: message => console.error(message)
|
|
489
|
+
* };
|
|
490
|
+
* output.writeFailure("Commit 225059f… is not on origin/main.");
|
|
491
|
+
* ```
|
|
492
|
+
*/
|
|
493
|
+
writeFailure(message: string): void;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* How the {@link TagStep} reads and creates a tag on the pipeline's host,
|
|
498
|
+
* which implements it, such as through the host's API.
|
|
499
|
+
*/
|
|
500
|
+
export declare interface ITagHost {
|
|
501
|
+
/**
|
|
502
|
+
* Reads the commit a tag points to, following an annotated tag to its
|
|
503
|
+
* commit.
|
|
504
|
+
*
|
|
505
|
+
* @param tag The tag's name, such as `v0.0.4`.
|
|
506
|
+
* @returns A promise of the commit's full id, `""` when the host has no
|
|
507
|
+
* such tag, or a failed {@link StepResult} that says why the host could not
|
|
508
|
+
* answer.
|
|
509
|
+
* @example
|
|
510
|
+
* ```ts
|
|
511
|
+
* import type { ITagHost } from "@noldova/tools.pipelines";
|
|
512
|
+
*
|
|
513
|
+
* const tags = new Map<string, string>();
|
|
514
|
+
* const host: ITagHost = {
|
|
515
|
+
* readTagAsync: async tag => tags.get(tag) ?? "",
|
|
516
|
+
* createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
|
|
517
|
+
* };
|
|
518
|
+
* await host.readTagAsync("v0.0.4"); // ""
|
|
519
|
+
* ```
|
|
520
|
+
*/
|
|
521
|
+
readTagAsync(tag: string): Promise<string | StepResult>;
|
|
522
|
+
|
|
523
|
+
/**
|
|
524
|
+
* Creates a tag at a commit, unless the host already has a tag of that
|
|
525
|
+
* name; it never moves a tag.
|
|
526
|
+
*
|
|
527
|
+
* @param tag The tag's name, such as `v0.0.4`.
|
|
528
|
+
* @param commit The commit's full id.
|
|
529
|
+
* @returns A promise of `true` when it created the tag, `false` when the
|
|
530
|
+
* host already has a tag of that name, such as one another run made, or a
|
|
531
|
+
* failed {@link StepResult} that says why the host could not create it.
|
|
532
|
+
* @example
|
|
533
|
+
* ```ts
|
|
534
|
+
* import type { ITagHost } from "@noldova/tools.pipelines";
|
|
535
|
+
*
|
|
536
|
+
* const tags = new Map<string, string>();
|
|
537
|
+
* const host: ITagHost = {
|
|
538
|
+
* readTagAsync: async tag => tags.get(tag) ?? "",
|
|
539
|
+
* createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
|
|
540
|
+
* };
|
|
541
|
+
* await host.createTagAsync("v0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"); // true
|
|
542
|
+
* await host.createTagAsync("v0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"); // false
|
|
543
|
+
* ```
|
|
544
|
+
*/
|
|
545
|
+
createTagAsync(tag: string, commit: string): Promise<boolean | StepResult>;
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
/**
|
|
549
|
+
* How the {@link PruneStep} lists and deletes a package's versions on a
|
|
550
|
+
* registry, which the registry's host implements, such as through the
|
|
551
|
+
* host's API.
|
|
552
|
+
*/
|
|
553
|
+
export declare interface IRegistryHost {
|
|
554
|
+
/**
|
|
555
|
+
* The registry the host lists and deletes versions on, an `https` URL such
|
|
556
|
+
* as `https://npm.pkg.github.com/`; the prune step runs only for it, and
|
|
557
|
+
* never for npm's registry, `https://registry.npmjs.org/`.
|
|
558
|
+
*/
|
|
559
|
+
readonly registry: string;
|
|
560
|
+
|
|
561
|
+
/**
|
|
562
|
+
* Lists every version of a package the registry has.
|
|
563
|
+
*
|
|
564
|
+
* @param packageName The package's name, inside its scope, such as
|
|
565
|
+
* `@noldova/tools.pipelines`.
|
|
566
|
+
* @returns A promise of the versions' texts, in any order, including any
|
|
567
|
+
* that are not release versions, or a failed {@link StepResult} that says
|
|
568
|
+
* why the host could not list them.
|
|
569
|
+
* @example
|
|
570
|
+
* ```ts
|
|
571
|
+
* import type { IRegistryHost } from "@noldova/tools.pipelines";
|
|
572
|
+
*
|
|
573
|
+
* const versions = new Map([["@noldova/a", ["0.0.3", "0.0.4"]]]);
|
|
574
|
+
* const host: IRegistryHost = {
|
|
575
|
+
* registry: "https://npm.pkg.github.com/",
|
|
576
|
+
* readVersionsAsync: async packageName => versions.get(packageName) ?? [],
|
|
577
|
+
* deleteVersionAsync: async () => true
|
|
578
|
+
* };
|
|
579
|
+
* await host.readVersionsAsync("@noldova/a"); // ["0.0.3", "0.0.4"]
|
|
580
|
+
* ```
|
|
581
|
+
*/
|
|
582
|
+
readVersionsAsync(packageName: string): Promise<readonly string[] | StepResult>;
|
|
583
|
+
|
|
584
|
+
/**
|
|
585
|
+
* Deletes one version of a package from the registry.
|
|
586
|
+
*
|
|
587
|
+
* @param packageName The package's name, inside its scope.
|
|
588
|
+
* @param version The version's text, as {@link IRegistryHost.readVersionsAsync}
|
|
589
|
+
* listed it.
|
|
590
|
+
* @returns A promise of `true` when it deleted the version, `false` when
|
|
591
|
+
* the registry no longer has it, such as after another run deleted it, or
|
|
592
|
+
* a failed {@link StepResult} that says why the host could not delete it.
|
|
593
|
+
* @example
|
|
594
|
+
* ```ts
|
|
595
|
+
* import type { IRegistryHost } from "@noldova/tools.pipelines";
|
|
596
|
+
*
|
|
597
|
+
* const versions = new Set(["0.0.3", "0.0.4"]);
|
|
598
|
+
* const host: IRegistryHost = {
|
|
599
|
+
* registry: "https://npm.pkg.github.com/",
|
|
600
|
+
* readVersionsAsync: async () => [...versions],
|
|
601
|
+
* deleteVersionAsync: async (packageName, version) => versions.delete(version)
|
|
602
|
+
* };
|
|
603
|
+
* await host.deleteVersionAsync("@noldova/a", "0.0.3"); // true
|
|
604
|
+
* await host.deleteVersionAsync("@noldova/a", "0.0.3"); // false
|
|
605
|
+
* ```
|
|
606
|
+
*/
|
|
607
|
+
deleteVersionAsync(packageName: string, version: string): Promise<boolean | StepResult>;
|
|
608
|
+
}
|
|
609
|
+
|
|
610
|
+
/**
|
|
611
|
+
* The command-line base a pipeline host builds its command line on: it runs
|
|
612
|
+
* the step its first value names with the values after it, writes the step's
|
|
613
|
+
* message, and gives the exit code.
|
|
614
|
+
*/
|
|
615
|
+
export declare class CommandLine {
|
|
616
|
+
/**
|
|
617
|
+
* Creates a command line over its steps.
|
|
618
|
+
*
|
|
619
|
+
* @param programName The name the usage line shows, such as the command a
|
|
620
|
+
* workflow calls.
|
|
621
|
+
* @param steps The steps it can run, each with its own name; the usage
|
|
622
|
+
* line lists them in this order.
|
|
623
|
+
* @param output Where it writes each message.
|
|
624
|
+
* @example
|
|
625
|
+
* ```ts
|
|
626
|
+
* import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
|
|
627
|
+
*
|
|
628
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
629
|
+
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
630
|
+
* writeSuccess: message => console.log(message),
|
|
631
|
+
* writeFailure: message => console.error(message)
|
|
632
|
+
* });
|
|
633
|
+
* ```
|
|
634
|
+
*/
|
|
635
|
+
public constructor(programName: string, steps: readonly IStep[], output: IStepOutput);
|
|
636
|
+
|
|
637
|
+
/**
|
|
638
|
+
* Runs the step the first value names.
|
|
639
|
+
*
|
|
640
|
+
* @param values The command line's values after the program, such as
|
|
641
|
+
* `["source", "0.0.4", "<commit>"]`.
|
|
642
|
+
* @returns A promise of the exit code: `0` after a step that succeeded,
|
|
643
|
+
* whose message it wrote with {@link IStepOutput.writeSuccess}; `1` after a
|
|
644
|
+
* step that failed, whose message it wrote with
|
|
645
|
+
* {@link IStepOutput.writeFailure}, or when no step has the first value's
|
|
646
|
+
* name, after writing the usage line, such as
|
|
647
|
+
* `Usage: pipelines source <version> <commit>`. It rejects with what the
|
|
648
|
+
* step rejects with, such as a {@link PipelineException}.
|
|
649
|
+
* @example
|
|
650
|
+
* ```ts
|
|
651
|
+
* import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
|
|
652
|
+
*
|
|
653
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
654
|
+
* const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
|
|
655
|
+
* writeSuccess: message => console.log(message),
|
|
656
|
+
* writeFailure: message => console.error(message)
|
|
657
|
+
* });
|
|
658
|
+
* process.exitCode = await commandLine.runAsync(process.argv.slice(2));
|
|
659
|
+
* ```
|
|
660
|
+
*/
|
|
661
|
+
public runAsync(values: readonly string[]): Promise<number>;
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
/**
|
|
665
|
+
* Runs a program without a shell and collects what it writes.
|
|
666
|
+
*/
|
|
667
|
+
export declare class ProcessRunner {
|
|
668
|
+
/**
|
|
669
|
+
* Runs a program to its end.
|
|
670
|
+
*
|
|
671
|
+
* @param program The program, found on the `PATH` as the operating system
|
|
672
|
+
* finds it, or a path to it.
|
|
673
|
+
* @param values The values passed to the program, each as one argument,
|
|
674
|
+
* never read by a shell.
|
|
675
|
+
* @param workingDirectory The directory the program runs in.
|
|
676
|
+
* @returns A promise of the program's exit code and of what it wrote. A
|
|
677
|
+
* program that fails still resolves, with its exit code; the promise
|
|
678
|
+
* rejects with {@link ProcessException} only when the program cannot
|
|
679
|
+
* start, such as when it is not installed or the directory does not exist.
|
|
680
|
+
* @example
|
|
681
|
+
* ```ts
|
|
682
|
+
* import { ProcessRunner } from "@noldova/tools.pipelines";
|
|
683
|
+
*
|
|
684
|
+
* const result = await new ProcessRunner().runAsync("git", ["--version"], process.cwd());
|
|
685
|
+
* result.isSuccessful; // true where git is installed
|
|
686
|
+
* ```
|
|
687
|
+
*/
|
|
688
|
+
public runAsync(program: string, values: readonly string[], workingDirectory: string): Promise<ProcessResult>;
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
/**
|
|
692
|
+
* Reads what a step needs from a clone of a git repository, through the
|
|
693
|
+
* `git` program.
|
|
694
|
+
*/
|
|
695
|
+
export declare class Git {
|
|
696
|
+
/**
|
|
697
|
+
* Creates a reader of one clone.
|
|
698
|
+
*
|
|
699
|
+
* @param processRunner What runs `git`.
|
|
700
|
+
* @param workingDirectory The clone's directory, or any directory inside
|
|
701
|
+
* it.
|
|
702
|
+
* @example
|
|
703
|
+
* ```ts
|
|
704
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
705
|
+
*
|
|
706
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
707
|
+
* ```
|
|
708
|
+
*/
|
|
709
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
710
|
+
|
|
711
|
+
/**
|
|
712
|
+
* Tells whether a revision names a commit in the clone.
|
|
713
|
+
*
|
|
714
|
+
* @param revision A commit id, or a reference such as
|
|
715
|
+
* `refs/remotes/origin/main`.
|
|
716
|
+
* @returns A promise of `true` if the revision names a commit, otherwise
|
|
717
|
+
* `false`. It rejects with {@link ProcessException} if git cannot start or
|
|
718
|
+
* fails otherwise, such as outside a clone.
|
|
719
|
+
* @example
|
|
720
|
+
* ```ts
|
|
721
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
722
|
+
*
|
|
723
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
724
|
+
* await git.hasCommitAsync("refs/remotes/origin/main"); // true in a clone that fetched main
|
|
725
|
+
* ```
|
|
726
|
+
*/
|
|
727
|
+
public hasCommitAsync(revision: string): Promise<boolean>;
|
|
728
|
+
|
|
729
|
+
/**
|
|
730
|
+
* Tells whether a commit holds a file.
|
|
731
|
+
*
|
|
732
|
+
* @param commit The commit, which the clone holds.
|
|
733
|
+
* @param filePath The file's path from the repository's root, with `/`
|
|
734
|
+
* between folders, such as `version.json`.
|
|
735
|
+
* @returns A promise of `true` if the commit holds a file at the path,
|
|
736
|
+
* otherwise `false`, also when the path is a folder. It rejects with {@link ProcessException} if git cannot start or
|
|
737
|
+
* fails otherwise.
|
|
738
|
+
* @example
|
|
739
|
+
* ```ts
|
|
740
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
741
|
+
*
|
|
742
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
743
|
+
* await git.hasFileAsync("refs/remotes/origin/main", "version.json"); // true where main holds the file
|
|
744
|
+
* ```
|
|
745
|
+
*/
|
|
746
|
+
public hasFileAsync(commit: string, filePath: string): Promise<boolean>;
|
|
747
|
+
|
|
748
|
+
/**
|
|
749
|
+
* Tells whether a commit is in another commit's history, such as on a
|
|
750
|
+
* branch.
|
|
751
|
+
*
|
|
752
|
+
* @param commit The commit to look for, which the clone holds.
|
|
753
|
+
* @param descendant The commit or reference whose history is searched; a
|
|
754
|
+
* commit is in its own history.
|
|
755
|
+
* @returns A promise of `true` if the commit is in the descendant's
|
|
756
|
+
* history, otherwise `false`. It rejects with {@link ProcessException} if
|
|
757
|
+
* git cannot start or fails otherwise, such as when the clone holds
|
|
758
|
+
* neither commit.
|
|
759
|
+
* @example
|
|
760
|
+
* ```ts
|
|
761
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
762
|
+
*
|
|
763
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
764
|
+
* await git.isAncestorAsync("HEAD", "refs/remotes/origin/main"); // true when HEAD is on main
|
|
765
|
+
* ```
|
|
766
|
+
*/
|
|
767
|
+
public isAncestorAsync(commit: string, descendant: string): Promise<boolean>;
|
|
768
|
+
|
|
769
|
+
/**
|
|
770
|
+
* Lists the files a commit holds in a folder and the folders inside it.
|
|
771
|
+
*
|
|
772
|
+
* @param commit The commit, which the clone holds.
|
|
773
|
+
* @param folderPath The folder's path from the repository's root, with `/`
|
|
774
|
+
* between folders, such as `src`.
|
|
775
|
+
* @returns A promise of each file's path from the repository's root, with
|
|
776
|
+
* `/` between folders, in git's order; none when the commit has no such
|
|
777
|
+
* folder. It rejects with {@link ProcessException} if git cannot start or
|
|
778
|
+
* fails otherwise, such as when the clone does not hold the commit.
|
|
779
|
+
* @example
|
|
780
|
+
* ```ts
|
|
781
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
782
|
+
*
|
|
783
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
784
|
+
* await git.listFilesAsync("refs/remotes/origin/main", "src"); // ["src/noldova.tools.pipelines/package.json", …]
|
|
785
|
+
* ```
|
|
786
|
+
*/
|
|
787
|
+
public listFilesAsync(commit: string, folderPath: string): Promise<readonly string[]>;
|
|
788
|
+
|
|
789
|
+
/**
|
|
790
|
+
* Reads a file as a commit holds it.
|
|
791
|
+
*
|
|
792
|
+
* @param commit The commit, which holds the file.
|
|
793
|
+
* @param filePath The file's path from the repository's root, with `/`
|
|
794
|
+
* between folders.
|
|
795
|
+
* @returns A promise of the file's content as UTF-8 text. It rejects with
|
|
796
|
+
* {@link ProcessException} if git cannot start or cannot read the file,
|
|
797
|
+
* such as when the commit does not hold it.
|
|
798
|
+
* @example
|
|
799
|
+
* ```ts
|
|
800
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
801
|
+
*
|
|
802
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
803
|
+
* await git.readFileAsync("refs/remotes/origin/main", "version.json"); // "{\n \"version\": \"0.0.4\"\n}\n"
|
|
804
|
+
* ```
|
|
805
|
+
*/
|
|
806
|
+
public readFileAsync(commit: string, filePath: string): Promise<string>;
|
|
807
|
+
|
|
808
|
+
/**
|
|
809
|
+
* Reads the commit the checkout is at.
|
|
810
|
+
*
|
|
811
|
+
* @returns A promise of the commit's full id. It rejects with
|
|
812
|
+
* {@link ProcessException} if git cannot start or fails otherwise, such as
|
|
813
|
+
* in a clone without commits.
|
|
814
|
+
* @example
|
|
815
|
+
* ```ts
|
|
816
|
+
* import { Git, ProcessRunner } from "@noldova/tools.pipelines";
|
|
817
|
+
*
|
|
818
|
+
* const git = new Git(new ProcessRunner(), process.cwd());
|
|
819
|
+
* await git.readHeadAsync(); // "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"
|
|
820
|
+
* ```
|
|
821
|
+
*/
|
|
822
|
+
public readHeadAsync(): Promise<string>;
|
|
823
|
+
}
|
|
824
|
+
|
|
825
|
+
/**
|
|
826
|
+
* Reads and lists files in `.tgz` archives through the `tar` program.
|
|
827
|
+
*/
|
|
828
|
+
export declare class Tar {
|
|
829
|
+
/**
|
|
830
|
+
* Creates the reader.
|
|
831
|
+
*
|
|
832
|
+
* @param processRunner The runner that starts `tar`.
|
|
833
|
+
* @example
|
|
834
|
+
* ```ts
|
|
835
|
+
* import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
836
|
+
*
|
|
837
|
+
* const tar = new Tar(new ProcessRunner());
|
|
838
|
+
* ```
|
|
839
|
+
*/
|
|
840
|
+
public constructor(processRunner: ProcessRunner);
|
|
841
|
+
|
|
842
|
+
/**
|
|
843
|
+
* Reads one file from an archive.
|
|
844
|
+
*
|
|
845
|
+
* @param archivePath The archive's path, such as
|
|
846
|
+
* `archives/noldova-tools.pipelines-0.0.4.tgz`.
|
|
847
|
+
* @param filePath The file's path inside the archive, such as
|
|
848
|
+
* `package/package.json`.
|
|
849
|
+
* @returns A promise of how `tar` ended: on success, its output is the
|
|
850
|
+
* file's content as UTF-8 text; when the archive is not a `.tgz` or lacks
|
|
851
|
+
* the file, it failed, with `tar`'s message. It rejects with
|
|
852
|
+
* {@link ProcessException} if `tar` cannot start, such as when it is not
|
|
853
|
+
* installed or the archive's folder does not exist.
|
|
854
|
+
* @example
|
|
855
|
+
* ```ts
|
|
856
|
+
* import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
857
|
+
*
|
|
858
|
+
* const result = await new Tar(new ProcessRunner()).readFileAsync("archives/noldova-tools.pipelines-0.0.4.tgz", "package/package.json");
|
|
859
|
+
* result.isSuccessful; // true when the archive holds the file
|
|
860
|
+
* ```
|
|
861
|
+
*/
|
|
862
|
+
public readFileAsync(archivePath: string, filePath: string): Promise<ProcessResult>;
|
|
863
|
+
|
|
864
|
+
/**
|
|
865
|
+
* Lists the paths an archive holds.
|
|
866
|
+
*
|
|
867
|
+
* @param archivePath The archive's path, such as
|
|
868
|
+
* `archives/noldova-tools.pipelines-0.0.4.tgz`.
|
|
869
|
+
* @returns A promise of how `tar` ended: on success, its output has one
|
|
870
|
+
* path inside the archive on each line, such as `package/package.json`,
|
|
871
|
+
* with a folder's path ending in `/` when the archive lists it; when the
|
|
872
|
+
* archive is not a `.tgz`, it failed, with `tar`'s message. It rejects with
|
|
873
|
+
* {@link ProcessException} if `tar` cannot start, such as when it is not
|
|
874
|
+
* installed or the archive's folder does not exist.
|
|
875
|
+
* @example
|
|
876
|
+
* ```ts
|
|
877
|
+
* import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
878
|
+
*
|
|
879
|
+
* const result = await new Tar(new ProcessRunner()).listFilesAsync("archives/noldova-tools.pipelines-0.0.4.tgz");
|
|
880
|
+
* result.output.split(/\r?\n/).includes("package/LICENSE"); // true when the archive holds its license
|
|
881
|
+
* ```
|
|
882
|
+
*/
|
|
883
|
+
public listFilesAsync(archivePath: string): Promise<ProcessResult>;
|
|
884
|
+
}
|
|
885
|
+
|
|
886
|
+
/**
|
|
887
|
+
* Runs the `npm` program's registry commands. It passes no credentials;
|
|
888
|
+
* `npm` takes them from its own configuration, such as the environment a
|
|
889
|
+
* pipeline sets up.
|
|
890
|
+
*/
|
|
891
|
+
export declare class Npm {
|
|
892
|
+
/**
|
|
893
|
+
* Creates the runner.
|
|
894
|
+
*
|
|
895
|
+
* @param processRunner The runner that starts `npm`.
|
|
896
|
+
* @param workingDirectory The directory `npm` runs in, whose configuration
|
|
897
|
+
* it reads.
|
|
898
|
+
* @example
|
|
899
|
+
* ```ts
|
|
900
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
901
|
+
*
|
|
902
|
+
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
903
|
+
* ```
|
|
904
|
+
*/
|
|
905
|
+
public constructor(processRunner: ProcessRunner, workingDirectory: string);
|
|
906
|
+
|
|
907
|
+
/**
|
|
908
|
+
* Reads a field of a package or a version from the registry, asking the
|
|
909
|
+
* registry rather than `npm`'s cache.
|
|
910
|
+
*
|
|
911
|
+
* @param specifier The package, such as `@noldova/tools.pipelines`, or one
|
|
912
|
+
* of its versions, such as `@noldova/tools.pipelines@0.0.4`.
|
|
913
|
+
* @param field The field, such as `dist.integrity` or `dist-tags.latest`.
|
|
914
|
+
* @param registry The registry's URL.
|
|
915
|
+
* @returns A promise of how `npm view` ended: on success, its output is the
|
|
916
|
+
* field's value, empty when the version or the field doesn't exist. It
|
|
917
|
+
* rejects with {@link ProcessException} if `npm` cannot start.
|
|
918
|
+
* @example
|
|
919
|
+
* ```ts
|
|
920
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
921
|
+
*
|
|
922
|
+
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
923
|
+
* const result = await npm.viewAsync("@noldova/tools.pipelines", "dist-tags.latest", "https://registry.npmjs.org/");
|
|
924
|
+
* result.output; // "0.0.4\n" once 0.0.4 is the latest version
|
|
925
|
+
* ```
|
|
926
|
+
*/
|
|
927
|
+
public viewAsync(specifier: string, field: string, registry: string): Promise<ProcessResult>;
|
|
928
|
+
|
|
929
|
+
/**
|
|
930
|
+
* Reads a field of a package or a version from the registry, as
|
|
931
|
+
* {@link Npm.viewAsync} does, and gives its value.
|
|
932
|
+
*
|
|
933
|
+
* @param specifier The package, such as `@noldova/tools.pipelines`, or one
|
|
934
|
+
* of its versions, such as `@noldova/tools.pipelines@0.0.4`.
|
|
935
|
+
* @param field The field, such as `gitHead` or `dist-tags.nightly`.
|
|
936
|
+
* @param registry The registry's URL.
|
|
937
|
+
* @returns A promise of the field's value without surrounding white space,
|
|
938
|
+
* empty when the registry has no such package, version or field, or of a
|
|
939
|
+
* failed {@link StepResult} with one line, such as
|
|
940
|
+
* `@noldova/tools.pipelines: npm view exited with code 1: …`, when `npm`
|
|
941
|
+
* fails otherwise. It rejects with {@link ProcessException} if `npm`
|
|
942
|
+
* cannot start.
|
|
943
|
+
* @example
|
|
944
|
+
* ```ts
|
|
945
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
946
|
+
*
|
|
947
|
+
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
948
|
+
* const latest = await npm.readFieldOrEmptyAsync("@noldova/tools.pipelines", "dist-tags.latest", "https://registry.npmjs.org/");
|
|
949
|
+
* latest; // "0.0.4" once 0.0.4 is the latest version
|
|
950
|
+
* ```
|
|
951
|
+
*/
|
|
952
|
+
public readFieldOrEmptyAsync(specifier: string, field: string, registry: string): Promise<string | StepResult>;
|
|
953
|
+
|
|
954
|
+
/**
|
|
955
|
+
* Publishes an archive to the registry under a dist-tag.
|
|
956
|
+
*
|
|
957
|
+
* @param archivePath The archive's path, relative to the current folder or
|
|
958
|
+
* full.
|
|
959
|
+
* @param tag The dist-tag the version gets, such as `latest` or `nightly`.
|
|
960
|
+
* @param access `public` or `restricted`.
|
|
961
|
+
* @param registry The registry's URL.
|
|
962
|
+
* @returns A promise of how `npm publish` ended. It rejects with
|
|
963
|
+
* {@link ProcessException} if `npm` cannot start.
|
|
964
|
+
* @example
|
|
965
|
+
* ```ts
|
|
966
|
+
* import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
|
|
967
|
+
*
|
|
968
|
+
* const npm = new Npm(new ProcessRunner(), process.cwd());
|
|
969
|
+
* const result = await npm.publishAsync("archives/noldova-tools.pipelines-0.0.4.tgz", "latest", "public", "https://registry.npmjs.org/");
|
|
970
|
+
* result.isSuccessful; // true when the registry took the archive
|
|
971
|
+
* ```
|
|
972
|
+
*/
|
|
973
|
+
public publishAsync(archivePath: string, tag: string, access: string, registry: string): Promise<ProcessResult>;
|
|
974
|
+
|
|
975
|
+
/**
|
|
976
|
+
* Tells whether a text is a registry the steps take: an `https` URL
|
|
977
|
+
* without credentials, a query or a fragment.
|
|
978
|
+
*
|
|
979
|
+
* @param text The text, such as a step's value.
|
|
980
|
+
* @returns `true` when the text is such a URL.
|
|
981
|
+
* @example
|
|
982
|
+
* ```ts
|
|
983
|
+
* import { Npm } from "@noldova/tools.pipelines";
|
|
984
|
+
*
|
|
985
|
+
* Npm.isRegistry("https://registry.npmjs.org/"); // true
|
|
986
|
+
* Npm.isRegistry("https://registry.npmjs.org/?token=x"); // false
|
|
987
|
+
* ```
|
|
988
|
+
*/
|
|
989
|
+
public static isRegistry(text: string): boolean;
|
|
990
|
+
}
|
|
991
|
+
|
|
992
|
+
/**
|
|
993
|
+
* The step that checks a release's source before anything is built or
|
|
994
|
+
* published: `source <version> <commit>`. It succeeds only when the version
|
|
995
|
+
* is a version, the commit is a full commit id that the clone holds, the
|
|
996
|
+
* commit is on `origin/main`, and the `version.json` at the commit's root is
|
|
997
|
+
* a JSON object whose `version` is that version.
|
|
998
|
+
*/
|
|
999
|
+
export declare class SourceStep implements IStep {
|
|
1000
|
+
/**
|
|
1001
|
+
* The step's name, `"source"`.
|
|
1002
|
+
*/
|
|
1003
|
+
public readonly name: string;
|
|
1004
|
+
|
|
1005
|
+
/**
|
|
1006
|
+
* The values the step takes, `"<version> <commit>"`.
|
|
1007
|
+
*/
|
|
1008
|
+
public readonly usage: string;
|
|
1009
|
+
|
|
1010
|
+
/**
|
|
1011
|
+
* Creates the step over a clone.
|
|
1012
|
+
*
|
|
1013
|
+
* @param git The reader of the clone, which has fetched `origin/main` with
|
|
1014
|
+
* its history.
|
|
1015
|
+
* @example
|
|
1016
|
+
* ```ts
|
|
1017
|
+
* import { Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
|
|
1018
|
+
*
|
|
1019
|
+
* const step = new SourceStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1020
|
+
* step.name; // "source"
|
|
1021
|
+
* ```
|
|
1022
|
+
*/
|
|
1023
|
+
public constructor(git: Git);
|
|
1024
|
+
|
|
1025
|
+
/**
|
|
1026
|
+
* Checks the release's source.
|
|
1027
|
+
*
|
|
1028
|
+
* @param values The version, such as `0.0.4`, and the commit's full id,
|
|
1029
|
+
* 40 lowercase hexadecimal digits.
|
|
1030
|
+
* @returns A promise of the result: succeeded, such as
|
|
1031
|
+
* `Commit 225059f… is on origin/main, and its version.json holds 0.0.4.`,
|
|
1032
|
+
* or failed with the first thing that is wrong, checked in this order: not
|
|
1033
|
+
* two values, a version that is not a version, a commit that is not a full
|
|
1034
|
+
* id, a commit the clone does not hold, a clone without `origin/main`, a
|
|
1035
|
+
* commit not on it, a commit without `version.json`, and a `version` other
|
|
1036
|
+
* than the one given. It rejects with `JsonException`, from
|
|
1037
|
+
* `@noldova/context.json`, if `version.json` is not a JSON object with a
|
|
1038
|
+
* `version` text, and with {@link ProcessException} if git cannot start or
|
|
1039
|
+
* fails otherwise.
|
|
1040
|
+
* @example
|
|
1041
|
+
* ```ts
|
|
1042
|
+
* import { Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
|
|
1043
|
+
*
|
|
1044
|
+
* const step = new SourceStep(new Git(new ProcessRunner(), process.cwd()));
|
|
1045
|
+
* const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
|
|
1046
|
+
* result.isSuccessful; // true when that commit is on main and holds 0.0.4
|
|
1047
|
+
* (await step.runAsync(["0.0.4"])).message; // "The source step takes <version> <commit>."
|
|
1048
|
+
* ```
|
|
1049
|
+
*/
|
|
1050
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1051
|
+
}
|
|
1052
|
+
|
|
1053
|
+
/**
|
|
1054
|
+
* The step that checks a release's archives before anything is published:
|
|
1055
|
+
* `archive <folder> <version> <commit> <scope>`. The packages it expects are
|
|
1056
|
+
* the commit's `package.json` files under `src/`, outside `tests/` folders,
|
|
1057
|
+
* that are not `"private": true`. It succeeds only when the checkout is at
|
|
1058
|
+
* the commit, and the folder holds exactly one archive for each package at
|
|
1059
|
+
* the version, named as `npm pack` names it, whose `package/package.json`
|
|
1060
|
+
* has the package's name, inside the scope, the version, and the commit as
|
|
1061
|
+
* its `gitHead`, is not `"private": true`, has a `license`, and lists any expected package under `dependencies` at
|
|
1062
|
+
* exactly the version. Each archive must also hold `package/LICENSE`, and no
|
|
1063
|
+
* file of a kind that holds credentials: `.npmrc`, `.netrc`, `.env` or
|
|
1064
|
+
* `.env.<name>`, `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`, or a name
|
|
1065
|
+
* ending in `.pem`, `.key`, `.p12` or `.pfx`, such as `.key` itself, in any
|
|
1066
|
+
* folder and whatever its case.
|
|
1067
|
+
*/
|
|
1068
|
+
export declare class ArchiveStep implements IStep {
|
|
1069
|
+
/**
|
|
1070
|
+
* The step's name, `"archive"`.
|
|
1071
|
+
*/
|
|
1072
|
+
public readonly name: string;
|
|
1073
|
+
|
|
1074
|
+
/**
|
|
1075
|
+
* The values the step takes, `"<folder> <version> <commit> <scope>"`.
|
|
1076
|
+
*/
|
|
1077
|
+
public readonly usage: string;
|
|
1078
|
+
|
|
1079
|
+
/**
|
|
1080
|
+
* Creates the step over a clone and an archive reader.
|
|
1081
|
+
*
|
|
1082
|
+
* @param git The reader of the clone whose checkout the archives were
|
|
1083
|
+
* packed from.
|
|
1084
|
+
* @param tar The reader of the archives.
|
|
1085
|
+
* @example
|
|
1086
|
+
* ```ts
|
|
1087
|
+
* import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1088
|
+
*
|
|
1089
|
+
* const processRunner = new ProcessRunner();
|
|
1090
|
+
* const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1091
|
+
* step.name; // "archive"
|
|
1092
|
+
* ```
|
|
1093
|
+
*/
|
|
1094
|
+
public constructor(git: Git, tar: Tar);
|
|
1095
|
+
|
|
1096
|
+
/**
|
|
1097
|
+
* Checks the release's archives.
|
|
1098
|
+
*
|
|
1099
|
+
* @param values The folder of archives, such as `archives`; the version,
|
|
1100
|
+
* such as `0.0.4`; the commit's full id, 40 lowercase hexadecimal digits;
|
|
1101
|
+
* and the scope, such as `@noldova`.
|
|
1102
|
+
* @returns A promise of the result. It succeeds with one line for each
|
|
1103
|
+
* archive, such as
|
|
1104
|
+
* `noldova-tools.pipelines-0.0.4.tgz: @noldova/tools.pipelines@0.0.4 from commit 225059f…`.
|
|
1105
|
+
* It fails with the first of these that is wrong: not four values, a
|
|
1106
|
+
* version that is not a version, a commit that is not a full id, a scope
|
|
1107
|
+
* that is not `@` and a lowercase name, a checkout at another commit, a
|
|
1108
|
+
* folder that does not exist, and a commit without a package to publish.
|
|
1109
|
+
* Otherwise it fails with one line for each problem with the archives: an
|
|
1110
|
+
* archive missing, a file that is not an expected archive, an archive
|
|
1111
|
+
* `tar` cannot read the manifest of, with `tar`'s exit code and message,
|
|
1112
|
+
* and a manifest with another name, a name outside the scope, another
|
|
1113
|
+
* version, no `gitHead` or another one, `"private": true`, no `license`
|
|
1114
|
+
* or an empty one, or an expected package under `dependencies`
|
|
1115
|
+
* at anything but exactly the version, an archive `tar` cannot list the
|
|
1116
|
+
* files of, with `tar`'s exit code and message, a file of a kind that holds
|
|
1117
|
+
* credentials, and no `package/LICENSE`. It rejects with `JsonException`,
|
|
1118
|
+
* from `@noldova/context.json`, if a `package.json` the step reads is not
|
|
1119
|
+
* a JSON object, lacks a `name` or `version` text where it needs one, has
|
|
1120
|
+
* a `gitHead` or a `license` that is not a text, or
|
|
1121
|
+
* has a `private` that is not `true` or `false` or `dependencies` that are
|
|
1122
|
+
* not an object of texts, and with {@link ProcessException} if git or
|
|
1123
|
+
* `tar` cannot start or git fails otherwise.
|
|
1124
|
+
* @example
|
|
1125
|
+
* ```ts
|
|
1126
|
+
* import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1127
|
+
*
|
|
1128
|
+
* const processRunner = new ProcessRunner();
|
|
1129
|
+
* const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1130
|
+
* const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
|
|
1131
|
+
* result.isSuccessful; // true when the folder holds exactly the packages at 0.0.4
|
|
1132
|
+
* (await step.runAsync(["archives"])).message; // "The archive step takes <folder> <version> <commit> <scope>."
|
|
1133
|
+
* ```
|
|
1134
|
+
*/
|
|
1135
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1136
|
+
|
|
1137
|
+
/**
|
|
1138
|
+
* Checks the release's archives as {@link ArchiveStep.runAsync} does, and
|
|
1139
|
+
* gives the archives it checked with the result, for a step that goes on
|
|
1140
|
+
* to use them.
|
|
1141
|
+
*
|
|
1142
|
+
* @param values The same values as {@link ArchiveStep.runAsync}.
|
|
1143
|
+
* @returns A promise of the check: the result, and when it succeeded, each
|
|
1144
|
+
* expected package with its archive, by package name. It rejects as
|
|
1145
|
+
* {@link ArchiveStep.runAsync} does.
|
|
1146
|
+
* @example
|
|
1147
|
+
* ```ts
|
|
1148
|
+
* import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1149
|
+
*
|
|
1150
|
+
* const processRunner = new ProcessRunner();
|
|
1151
|
+
* const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1152
|
+
* const check = await step.checkAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
|
|
1153
|
+
* check.archives.map(t => t.packageName); // ["@noldova/tools.pipelines"] when the check succeeded
|
|
1154
|
+
* ```
|
|
1155
|
+
*/
|
|
1156
|
+
public checkAsync(values: readonly string[]): Promise<ArchiveCheck>;
|
|
1157
|
+
|
|
1158
|
+
/**
|
|
1159
|
+
* Reads the names of the packages the step expects at a commit: those of
|
|
1160
|
+
* its `package.json` files under `src/`, outside `tests/` folders, that are
|
|
1161
|
+
* not `"private": true`.
|
|
1162
|
+
*
|
|
1163
|
+
* @param commit The commit's full id.
|
|
1164
|
+
* @returns A promise of the names, sorted, and empty when there is none. It
|
|
1165
|
+
* rejects with `JsonException` and {@link ProcessException} as
|
|
1166
|
+
* {@link ArchiveStep.runAsync} does.
|
|
1167
|
+
* @example
|
|
1168
|
+
* ```ts
|
|
1169
|
+
* import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1170
|
+
*
|
|
1171
|
+
* const processRunner = new ProcessRunner();
|
|
1172
|
+
* const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1173
|
+
* const names = await step.readPackageNamesAsync("225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8");
|
|
1174
|
+
* names; // ["@noldova/tools.pipelines"]
|
|
1175
|
+
* ```
|
|
1176
|
+
*/
|
|
1177
|
+
public readPackageNamesAsync(commit: string): Promise<readonly string[]>;
|
|
1178
|
+
}
|
|
1179
|
+
|
|
1180
|
+
/**
|
|
1181
|
+
* The step that publishes a release's archives:
|
|
1182
|
+
* `publish <folder> <version> <commit> <scope> <registry> <access>`. It runs
|
|
1183
|
+
* {@link ArchiveStep}'s checks first, then publishes each package whose
|
|
1184
|
+
* version the registry doesn't have and waits until the registry serves each
|
|
1185
|
+
* version it published with the same archive.
|
|
1186
|
+
*/
|
|
1187
|
+
export declare class PublishStep implements IStep {
|
|
1188
|
+
/**
|
|
1189
|
+
* The step's name, `"publish"`.
|
|
1190
|
+
*/
|
|
1191
|
+
public readonly name: string;
|
|
1192
|
+
|
|
1193
|
+
/**
|
|
1194
|
+
* The values the step takes,
|
|
1195
|
+
* `"<folder> <version> <commit> <scope> <registry> <access>"`.
|
|
1196
|
+
*/
|
|
1197
|
+
public readonly usage: string;
|
|
1198
|
+
|
|
1199
|
+
/**
|
|
1200
|
+
* Creates the step.
|
|
1201
|
+
*
|
|
1202
|
+
* @param archiveStep The step that checks the archives first.
|
|
1203
|
+
* @param npm The runner of `npm`, which publishes and reads the registry.
|
|
1204
|
+
* @param waitMilliseconds How long the step waits, after its last publish,
|
|
1205
|
+
* for the registry to serve every version it published; 10 minutes by
|
|
1206
|
+
* default.
|
|
1207
|
+
* @param retryMilliseconds How long the step waits between two reads of
|
|
1208
|
+
* the registry while it waits; 10 seconds by default.
|
|
1209
|
+
* @example
|
|
1210
|
+
* ```ts
|
|
1211
|
+
* import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
|
|
1212
|
+
*
|
|
1213
|
+
* const processRunner = new ProcessRunner();
|
|
1214
|
+
* const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1215
|
+
* const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
|
|
1216
|
+
* step.name; // "publish"
|
|
1217
|
+
* ```
|
|
1218
|
+
*/
|
|
1219
|
+
public constructor(archiveStep: ArchiveStep, npm: Npm, waitMilliseconds?: number, retryMilliseconds?: number);
|
|
1220
|
+
|
|
1221
|
+
/**
|
|
1222
|
+
* Publishes the release's archives.
|
|
1223
|
+
*
|
|
1224
|
+
* @param values The archive step's four values, then the registry, an
|
|
1225
|
+
* `https` URL without credentials, a query or a fragment, such as
|
|
1226
|
+
* `https://registry.npmjs.org/`, and the access, `public` or `restricted`.
|
|
1227
|
+
* A release is published under the `latest` dist-tag, and a nightly
|
|
1228
|
+
* version under `nightly`; a nightly version must be newer than both.
|
|
1229
|
+
* @returns A promise of the result. It succeeds with one line for each
|
|
1230
|
+
* package, such as `@noldova/tools.pipelines@0.0.4 published.` or
|
|
1231
|
+
* `@noldova/tools.pipelines@0.0.4 is already published from this archive.`
|
|
1232
|
+
* It fails with the first of these that is wrong, publishing nothing: not
|
|
1233
|
+
* six values, a registry or an access that is not one, or the archive
|
|
1234
|
+
* step's failure. Otherwise, before it publishes anything, it fails with
|
|
1235
|
+
* one line for each version the registry already has from another
|
|
1236
|
+
* archive, each version not newer than the version a tag it must pass
|
|
1237
|
+
* points to, and each
|
|
1238
|
+
* read of the registry that fails, with `npm`'s exit code and message.
|
|
1239
|
+
* After that, it publishes the archives in turn and stops at the first
|
|
1240
|
+
* publish that fails; it still waits for the versions it published before
|
|
1241
|
+
* it, and fails with a line for that publish, with `npm`'s exit code and
|
|
1242
|
+
* message, and for each version the registry does not serve in time or
|
|
1243
|
+
* serves from another archive. A URL's credentials, query and fragment in
|
|
1244
|
+
* `npm`'s message are left out of the line. It rejects as {@link ArchiveStep.runAsync} does,
|
|
1245
|
+
* and with {@link ProcessException} if `npm` cannot start.
|
|
1246
|
+
* @example
|
|
1247
|
+
* ```ts
|
|
1248
|
+
* import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
|
|
1249
|
+
*
|
|
1250
|
+
* const processRunner = new ProcessRunner();
|
|
1251
|
+
* const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
|
|
1252
|
+
* const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
|
|
1253
|
+
* const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://registry.npmjs.org/", "public"]);
|
|
1254
|
+
* result.isSuccessful; // true when every package's 0.0.4 is published and served
|
|
1255
|
+
* ```
|
|
1256
|
+
*/
|
|
1257
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1258
|
+
}
|
|
1259
|
+
|
|
1260
|
+
/**
|
|
1261
|
+
* The step that works out a nightly build's version: `nightly <commit> <registry>`.
|
|
1262
|
+
* It prints the version when `main` has changed since the packages' last
|
|
1263
|
+
* nightly versions, and nothing otherwise, so a pipeline publishes a nightly
|
|
1264
|
+
* build only when there is something new.
|
|
1265
|
+
*/
|
|
1266
|
+
export declare class NightlyStep implements IStep {
|
|
1267
|
+
/**
|
|
1268
|
+
* The step's name, `"nightly"`.
|
|
1269
|
+
*/
|
|
1270
|
+
public readonly name: string;
|
|
1271
|
+
|
|
1272
|
+
/**
|
|
1273
|
+
* The values the step takes, `"<commit> <registry>"`.
|
|
1274
|
+
*/
|
|
1275
|
+
public readonly usage: string;
|
|
1276
|
+
|
|
1277
|
+
/**
|
|
1278
|
+
* Creates the step.
|
|
1279
|
+
*
|
|
1280
|
+
* @param git The reader of the clone that holds the commit.
|
|
1281
|
+
* @param archiveStep The step whose expected packages the step looks up.
|
|
1282
|
+
* @param npm The runner of `npm`, which reads the registry.
|
|
1283
|
+
* @param readNow The clock the step takes the date from; the current time
|
|
1284
|
+
* by default.
|
|
1285
|
+
* @example
|
|
1286
|
+
* ```ts
|
|
1287
|
+
* import { ArchiveStep, Git, NightlyStep, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1288
|
+
*
|
|
1289
|
+
* const processRunner = new ProcessRunner();
|
|
1290
|
+
* const git = new Git(processRunner, process.cwd());
|
|
1291
|
+
* const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
|
|
1292
|
+
* step.name; // "nightly"
|
|
1293
|
+
* ```
|
|
1294
|
+
*/
|
|
1295
|
+
public constructor(git: Git, archiveStep: ArchiveStep, npm: Npm, readNow?: () => Date);
|
|
1296
|
+
|
|
1297
|
+
/**
|
|
1298
|
+
* Works out the nightly version.
|
|
1299
|
+
*
|
|
1300
|
+
* @param values The commit's full id, 40 lowercase hexadecimal digits, and
|
|
1301
|
+
* the registry, an `https` URL without credentials, a query or a fragment,
|
|
1302
|
+
* such as `https://registry.npmjs.org/`.
|
|
1303
|
+
* @returns A promise of the result. It succeeds with the version alone,
|
|
1304
|
+
* the release in `version.json` at the commit with one more patch and the
|
|
1305
|
+
* UTC date, such as `0.0.5-nightly.20261102` for `0.0.4` on November 2,
|
|
1306
|
+
* 2026. It succeeds with an empty message when the last nightly version of
|
|
1307
|
+
* every package the archive step expects has the commit as its `gitHead`,
|
|
1308
|
+
* or is from the same UTC date. It fails with the first of these that is
|
|
1309
|
+
* wrong: not two values, a commit that is not a full id, a registry that is
|
|
1310
|
+
* not one, a commit the clone does not hold, a clone without `origin/main`,
|
|
1311
|
+
* a commit not on it, a commit without `version.json`, a `version` that is
|
|
1312
|
+
* not a release version, and a commit without a package to publish.
|
|
1313
|
+
* Otherwise it fails with one line for each read of the registry that
|
|
1314
|
+
* fails, with `npm`'s exit code and message, and for each `nightly`
|
|
1315
|
+
* dist-tag that is not a version, or with one line naming the packages
|
|
1316
|
+
* whose last nightly version is from the same UTC date when only some are.
|
|
1317
|
+
* It rejects with `JsonException`, from `@noldova/context.json`, if
|
|
1318
|
+
* `version.json` is not a JSON object with a `version` text, and as
|
|
1319
|
+
* {@link ArchiveStep.readPackageNamesAsync} does.
|
|
1320
|
+
* @example
|
|
1321
|
+
* ```ts
|
|
1322
|
+
* import { ArchiveStep, Git, NightlyStep, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
|
|
1323
|
+
*
|
|
1324
|
+
* const processRunner = new ProcessRunner();
|
|
1325
|
+
* const git = new Git(processRunner, process.cwd());
|
|
1326
|
+
* const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
|
|
1327
|
+
* const result = await step.runAsync(["225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "https://registry.npmjs.org/"]);
|
|
1328
|
+
* result.message; // "0.0.5-nightly.20261102", or "" when nothing changed
|
|
1329
|
+
* ```
|
|
1330
|
+
*/
|
|
1331
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1332
|
+
}
|
|
1333
|
+
|
|
1334
|
+
/**
|
|
1335
|
+
* The step that keeps a registry's newest versions after a release:
|
|
1336
|
+
* `prune <version> <commit> <scope> <registry> <keep-versions>`. Through
|
|
1337
|
+
* the host's {@link IRegistryHost}, it deletes each package's older release
|
|
1338
|
+
* versions, keeping the newest; it runs only on the host's registry, never
|
|
1339
|
+
* on npm's, and deletes nothing unless the release is every package's
|
|
1340
|
+
* newest.
|
|
1341
|
+
*/
|
|
1342
|
+
export declare class PruneStep implements IStep {
|
|
1343
|
+
/**
|
|
1344
|
+
* The step's name, `"prune"`.
|
|
1345
|
+
*/
|
|
1346
|
+
public readonly name: string;
|
|
1347
|
+
|
|
1348
|
+
/**
|
|
1349
|
+
* The values the step takes,
|
|
1350
|
+
* `"<version> <commit> <scope> <registry> <keep-versions>"`.
|
|
1351
|
+
*/
|
|
1352
|
+
public readonly usage: string;
|
|
1353
|
+
|
|
1354
|
+
/**
|
|
1355
|
+
* Creates the step.
|
|
1356
|
+
*
|
|
1357
|
+
* @param git The reader of the clone that holds the commit.
|
|
1358
|
+
* @param archiveStep The step whose expected packages the step prunes.
|
|
1359
|
+
* @param registryHost How the step lists and deletes versions on the
|
|
1360
|
+
* registry.
|
|
1361
|
+
* @example
|
|
1362
|
+
* ```ts
|
|
1363
|
+
* import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
|
|
1364
|
+
*
|
|
1365
|
+
* const processRunner = new ProcessRunner();
|
|
1366
|
+
* const git = new Git(processRunner, process.cwd());
|
|
1367
|
+
* const host: IRegistryHost = {
|
|
1368
|
+
* registry: "https://npm.pkg.github.com/",
|
|
1369
|
+
* readVersionsAsync: async () => [],
|
|
1370
|
+
* deleteVersionAsync: async () => true
|
|
1371
|
+
* };
|
|
1372
|
+
* const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
|
|
1373
|
+
* step.name; // "prune"
|
|
1374
|
+
* ```
|
|
1375
|
+
*/
|
|
1376
|
+
public constructor(git: Git, archiveStep: ArchiveStep, registryHost: IRegistryHost);
|
|
1377
|
+
|
|
1378
|
+
/**
|
|
1379
|
+
* Deletes the older release versions of the packages a commit holds.
|
|
1380
|
+
*
|
|
1381
|
+
* @param values The release version just published, such as `0.0.4`; the
|
|
1382
|
+
* commit's full id, 40 lowercase hexadecimal digits; the scope, such as
|
|
1383
|
+
* `@noldova`; the registry, an `https` URL without credentials, a query or
|
|
1384
|
+
* a fragment, which must be the host's and not npm's; and how many release
|
|
1385
|
+
* versions to keep, a whole number above 0 without a leading zero, such as
|
|
1386
|
+
* `5`.
|
|
1387
|
+
* @returns A promise of the result. It fails with the first of these that
|
|
1388
|
+
* is wrong, asking the registry nothing: not five values, a version that
|
|
1389
|
+
* is not a version, a nightly version, a commit that is not a full id, a
|
|
1390
|
+
* scope that is not `@` and a lowercase name, a registry that is not one,
|
|
1391
|
+
* is npm's or is not the host's, a number to keep that is not one, a commit
|
|
1392
|
+
* the clone does not hold, a commit without a package to publish, and a
|
|
1393
|
+
* package outside the scope. Otherwise it lists every package's versions
|
|
1394
|
+
* first, and fails, deleting nothing, with one line for each package whose
|
|
1395
|
+
* versions the host could not list and each whose newest release version
|
|
1396
|
+
* is not the version. Then it deletes each package's release versions
|
|
1397
|
+
* after the newest it keeps, and succeeds with one line for each, such as
|
|
1398
|
+
* `@noldova/tools.pipelines@0.0.1 deleted.` or
|
|
1399
|
+
* `@noldova/tools.pipelines@0.0.1 was already deleted.`, or with one line
|
|
1400
|
+
* saying nothing is deleted when no package has more. It stops at the
|
|
1401
|
+
* first delete that fails, with the lines before it and the host's
|
|
1402
|
+
* answer, or, when the delete rejects with an `Error`, a line naming the
|
|
1403
|
+
* version with the error's message. Versions that are not release
|
|
1404
|
+
* versions, such as nightly ones, are neither counted nor deleted. It
|
|
1405
|
+
* rejects as {@link ArchiveStep.readPackageNamesAsync} and the host's
|
|
1406
|
+
* list do, and as a delete does that rejects with anything but an `Error`.
|
|
1407
|
+
* @example
|
|
1408
|
+
* ```ts
|
|
1409
|
+
* import { ArchiveStep, Git, type IRegistryHost, ProcessRunner, PruneStep, Tar } from "@noldova/tools.pipelines";
|
|
1410
|
+
*
|
|
1411
|
+
* const processRunner = new ProcessRunner();
|
|
1412
|
+
* const git = new Git(processRunner, process.cwd());
|
|
1413
|
+
* const versions = new Set(["0.0.1", "0.0.2", "0.0.3"]);
|
|
1414
|
+
* const host: IRegistryHost = {
|
|
1415
|
+
* registry: "https://npm.pkg.github.com/",
|
|
1416
|
+
* readVersionsAsync: async () => [...versions],
|
|
1417
|
+
* deleteVersionAsync: async (packageName, version) => versions.delete(version)
|
|
1418
|
+
* };
|
|
1419
|
+
* const step = new PruneStep(git, new ArchiveStep(git, new Tar(processRunner)), host);
|
|
1420
|
+
* const result = await step.runAsync(["0.0.3", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://npm.pkg.github.com/", "2"]);
|
|
1421
|
+
* result.message; // "@noldova/a@0.0.1 deleted." when the commit holds only @noldova/a
|
|
1422
|
+
* ```
|
|
1423
|
+
*/
|
|
1424
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1425
|
+
}
|
|
1426
|
+
|
|
1427
|
+
/**
|
|
1428
|
+
* The step a release ends with: it tags the released commit `v<version>`,
|
|
1429
|
+
* through the host's {@link ITagHost}, and never moves a tag.
|
|
1430
|
+
*/
|
|
1431
|
+
export declare class TagStep implements IStep {
|
|
1432
|
+
/**
|
|
1433
|
+
* The step's name, `"tag"`.
|
|
1434
|
+
*/
|
|
1435
|
+
public readonly name: string;
|
|
1436
|
+
|
|
1437
|
+
/**
|
|
1438
|
+
* The values the step takes, `"<version> <commit>"`.
|
|
1439
|
+
*/
|
|
1440
|
+
public readonly usage: string;
|
|
1441
|
+
|
|
1442
|
+
/**
|
|
1443
|
+
* Creates the step over a host's tags.
|
|
1444
|
+
*
|
|
1445
|
+
* @param tagHost How the step reads and creates a tag on the host.
|
|
1446
|
+
* @example
|
|
1447
|
+
* ```ts
|
|
1448
|
+
* import { type ITagHost, TagStep } from "@noldova/tools.pipelines";
|
|
1449
|
+
*
|
|
1450
|
+
* const tags = new Map<string, string>();
|
|
1451
|
+
* const host: ITagHost = {
|
|
1452
|
+
* readTagAsync: async tag => tags.get(tag) ?? "",
|
|
1453
|
+
* createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
|
|
1454
|
+
* };
|
|
1455
|
+
* const step = new TagStep(host);
|
|
1456
|
+
* step.name; // "tag"
|
|
1457
|
+
* ```
|
|
1458
|
+
*/
|
|
1459
|
+
public constructor(tagHost: ITagHost);
|
|
1460
|
+
|
|
1461
|
+
/**
|
|
1462
|
+
* Tags a release's commit with its version.
|
|
1463
|
+
*
|
|
1464
|
+
* @param values The release version, such as `0.0.4`, and the commit's
|
|
1465
|
+
* full id, 40 lowercase hexadecimal digits.
|
|
1466
|
+
* @returns A promise of the result. It fails, before asking the host, for
|
|
1467
|
+
* values other than two, a version that is not a version, a nightly
|
|
1468
|
+
* version, which gets no tag, or a commit that is not a full id. When the
|
|
1469
|
+
* host has no `v<version>`, it creates it and succeeds, such as
|
|
1470
|
+
* `Tagged commit 225059f… as v0.0.4.`; when the host already has it, such
|
|
1471
|
+
* as from another run that made it first, it succeeds if the tag points to
|
|
1472
|
+
* the commit, `v0.0.4 already points to commit 225059f….`, and fails,
|
|
1473
|
+
* naming both commits, if it points to another. A failed answer of the host
|
|
1474
|
+
* is the result as the host gives it.
|
|
1475
|
+
* @example
|
|
1476
|
+
* ```ts
|
|
1477
|
+
* import { type ITagHost, TagStep } from "@noldova/tools.pipelines";
|
|
1478
|
+
*
|
|
1479
|
+
* const tags = new Map<string, string>();
|
|
1480
|
+
* const host: ITagHost = {
|
|
1481
|
+
* readTagAsync: async tag => tags.get(tag) ?? "",
|
|
1482
|
+
* createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
|
|
1483
|
+
* };
|
|
1484
|
+
* const step = new TagStep(host);
|
|
1485
|
+
* (await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message; // "Tagged commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8 as v0.0.4."
|
|
1486
|
+
* (await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message; // "v0.0.4 already points to commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8."
|
|
1487
|
+
* ```
|
|
1488
|
+
*/
|
|
1489
|
+
public runAsync(values: readonly string[]): Promise<StepResult>;
|
|
1490
|
+
}
|