@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.
Files changed (54) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +202 -2
  3. package/api/index.d.ts +1490 -0
  4. package/api/index.js +27 -0
  5. package/api/index.js.map +1 -0
  6. package/exceptions/pipeline.exception.js +14 -0
  7. package/exceptions/pipeline.exception.js.map +1 -0
  8. package/exceptions/process.exception.js +17 -0
  9. package/exceptions/process.exception.js.map +1 -0
  10. package/exceptions/version.exception.js +15 -0
  11. package/exceptions/version.exception.js.map +1 -0
  12. package/interfaces/i-registry-host.js +9 -0
  13. package/interfaces/i-registry-host.js.map +1 -0
  14. package/interfaces/i-step-output.js +9 -0
  15. package/interfaces/i-step-output.js.map +1 -0
  16. package/interfaces/i-step.js +9 -0
  17. package/interfaces/i-step.js.map +1 -0
  18. package/interfaces/i-tag-host.js +9 -0
  19. package/interfaces/i-tag-host.js.map +1 -0
  20. package/models/archive-check.js +16 -0
  21. package/models/archive-check.js.map +1 -0
  22. package/models/package-archive.js +16 -0
  23. package/models/package-archive.js.map +1 -0
  24. package/models/process-result.js +22 -0
  25. package/models/process-result.js.map +1 -0
  26. package/models/step-result.js +22 -0
  27. package/models/step-result.js.map +1 -0
  28. package/models/version.js +85 -0
  29. package/models/version.js.map +1 -0
  30. package/package.json +24 -4
  31. package/resources.js +310 -0
  32. package/resources.js.map +1 -0
  33. package/services/archive-step.js +130 -0
  34. package/services/archive-step.js.map +1 -0
  35. package/services/command-line.js +34 -0
  36. package/services/command-line.js.map +1 -0
  37. package/services/git.js +60 -0
  38. package/services/git.js.map +1 -0
  39. package/services/nightly-step.js +82 -0
  40. package/services/nightly-step.js.map +1 -0
  41. package/services/npm.js +43 -0
  42. package/services/npm.js.map +1 -0
  43. package/services/process-runner.js +34 -0
  44. package/services/process-runner.js.map +1 -0
  45. package/services/prune-step.js +102 -0
  46. package/services/prune-step.js.map +1 -0
  47. package/services/publish-step.js +117 -0
  48. package/services/publish-step.js.map +1 -0
  49. package/services/source-step.js +43 -0
  50. package/services/source-step.js.map +1 -0
  51. package/services/tag-step.js +48 -0
  52. package/services/tag-step.js.map +1 -0
  53. package/services/tar.js +23 -0
  54. 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
+ }