@noldova/tools.pipelines 0.0.0-stage → 0.0.1

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 (50) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +173 -2
  3. package/api/index.d.ts +1307 -0
  4. package/api/index.js +26 -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-step-output.js +9 -0
  13. package/interfaces/i-step-output.js.map +1 -0
  14. package/interfaces/i-step.js +9 -0
  15. package/interfaces/i-step.js.map +1 -0
  16. package/interfaces/i-tag-host.js +9 -0
  17. package/interfaces/i-tag-host.js.map +1 -0
  18. package/models/archive-check.js +16 -0
  19. package/models/archive-check.js.map +1 -0
  20. package/models/package-archive.js +16 -0
  21. package/models/package-archive.js.map +1 -0
  22. package/models/process-result.js +22 -0
  23. package/models/process-result.js.map +1 -0
  24. package/models/step-result.js +22 -0
  25. package/models/step-result.js.map +1 -0
  26. package/models/version.js +85 -0
  27. package/models/version.js.map +1 -0
  28. package/package.json +24 -4
  29. package/resources.js +258 -0
  30. package/resources.js.map +1 -0
  31. package/services/archive-step.js +114 -0
  32. package/services/archive-step.js.map +1 -0
  33. package/services/command-line.js +34 -0
  34. package/services/command-line.js.map +1 -0
  35. package/services/git.js +60 -0
  36. package/services/git.js.map +1 -0
  37. package/services/nightly-step.js +82 -0
  38. package/services/nightly-step.js.map +1 -0
  39. package/services/npm.js +43 -0
  40. package/services/npm.js.map +1 -0
  41. package/services/process-runner.js +34 -0
  42. package/services/process-runner.js.map +1 -0
  43. package/services/publish-step.js +117 -0
  44. package/services/publish-step.js.map +1 -0
  45. package/services/source-step.js +43 -0
  46. package/services/source-step.js.map +1 -0
  47. package/services/tag-step.js +48 -0
  48. package/services/tag-step.js.map +1 -0
  49. package/services/tar.js +20 -0
  50. package/services/tar.js.map +1 -0
package/api/index.d.ts ADDED
@@ -0,0 +1,1307 @@
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
+ * The command-line base a pipeline host builds its command line on: it runs
550
+ * the step its first value names with the values after it, writes the step's
551
+ * message, and gives the exit code.
552
+ */
553
+ export declare class CommandLine {
554
+ /**
555
+ * Creates a command line over its steps.
556
+ *
557
+ * @param programName The name the usage line shows, such as the command a
558
+ * workflow calls.
559
+ * @param steps The steps it can run, each with its own name; the usage
560
+ * line lists them in this order.
561
+ * @param output Where it writes each message.
562
+ * @example
563
+ * ```ts
564
+ * import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
565
+ *
566
+ * const git = new Git(new ProcessRunner(), process.cwd());
567
+ * const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
568
+ * writeSuccess: message => console.log(message),
569
+ * writeFailure: message => console.error(message)
570
+ * });
571
+ * ```
572
+ */
573
+ public constructor(programName: string, steps: readonly IStep[], output: IStepOutput);
574
+
575
+ /**
576
+ * Runs the step the first value names.
577
+ *
578
+ * @param values The command line's values after the program, such as
579
+ * `["source", "0.0.4", "<commit>"]`.
580
+ * @returns A promise of the exit code: `0` after a step that succeeded,
581
+ * whose message it wrote with {@link IStepOutput.writeSuccess}; `1` after a
582
+ * step that failed, whose message it wrote with
583
+ * {@link IStepOutput.writeFailure}, or when no step has the first value's
584
+ * name, after writing the usage line, such as
585
+ * `Usage: pipelines source <version> <commit>`. It rejects with what the
586
+ * step rejects with, such as a {@link PipelineException}.
587
+ * @example
588
+ * ```ts
589
+ * import { CommandLine, Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
590
+ *
591
+ * const git = new Git(new ProcessRunner(), process.cwd());
592
+ * const commandLine = new CommandLine("pipelines", [new SourceStep(git)], {
593
+ * writeSuccess: message => console.log(message),
594
+ * writeFailure: message => console.error(message)
595
+ * });
596
+ * process.exitCode = await commandLine.runAsync(process.argv.slice(2));
597
+ * ```
598
+ */
599
+ public runAsync(values: readonly string[]): Promise<number>;
600
+ }
601
+
602
+ /**
603
+ * Runs a program without a shell and collects what it writes.
604
+ */
605
+ export declare class ProcessRunner {
606
+ /**
607
+ * Runs a program to its end.
608
+ *
609
+ * @param program The program, found on the `PATH` as the operating system
610
+ * finds it, or a path to it.
611
+ * @param values The values passed to the program, each as one argument,
612
+ * never read by a shell.
613
+ * @param workingDirectory The directory the program runs in.
614
+ * @returns A promise of the program's exit code and of what it wrote. A
615
+ * program that fails still resolves, with its exit code; the promise
616
+ * rejects with {@link ProcessException} only when the program cannot
617
+ * start, such as when it is not installed or the directory does not exist.
618
+ * @example
619
+ * ```ts
620
+ * import { ProcessRunner } from "@noldova/tools.pipelines";
621
+ *
622
+ * const result = await new ProcessRunner().runAsync("git", ["--version"], process.cwd());
623
+ * result.isSuccessful; // true where git is installed
624
+ * ```
625
+ */
626
+ public runAsync(program: string, values: readonly string[], workingDirectory: string): Promise<ProcessResult>;
627
+ }
628
+
629
+ /**
630
+ * Reads what a step needs from a clone of a git repository, through the
631
+ * `git` program.
632
+ */
633
+ export declare class Git {
634
+ /**
635
+ * Creates a reader of one clone.
636
+ *
637
+ * @param processRunner What runs `git`.
638
+ * @param workingDirectory The clone's directory, or any directory inside
639
+ * it.
640
+ * @example
641
+ * ```ts
642
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
643
+ *
644
+ * const git = new Git(new ProcessRunner(), process.cwd());
645
+ * ```
646
+ */
647
+ public constructor(processRunner: ProcessRunner, workingDirectory: string);
648
+
649
+ /**
650
+ * Tells whether a revision names a commit in the clone.
651
+ *
652
+ * @param revision A commit id, or a reference such as
653
+ * `refs/remotes/origin/main`.
654
+ * @returns A promise of `true` if the revision names a commit, otherwise
655
+ * `false`. It rejects with {@link ProcessException} if git cannot start or
656
+ * fails otherwise, such as outside a clone.
657
+ * @example
658
+ * ```ts
659
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
660
+ *
661
+ * const git = new Git(new ProcessRunner(), process.cwd());
662
+ * await git.hasCommitAsync("refs/remotes/origin/main"); // true in a clone that fetched main
663
+ * ```
664
+ */
665
+ public hasCommitAsync(revision: string): Promise<boolean>;
666
+
667
+ /**
668
+ * Tells whether a commit holds a file.
669
+ *
670
+ * @param commit The commit, which the clone holds.
671
+ * @param filePath The file's path from the repository's root, with `/`
672
+ * between folders, such as `version.json`.
673
+ * @returns A promise of `true` if the commit holds a file at the path,
674
+ * otherwise `false`, also when the path is a folder. It rejects with {@link ProcessException} if git cannot start or
675
+ * fails otherwise.
676
+ * @example
677
+ * ```ts
678
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
679
+ *
680
+ * const git = new Git(new ProcessRunner(), process.cwd());
681
+ * await git.hasFileAsync("refs/remotes/origin/main", "version.json"); // true where main holds the file
682
+ * ```
683
+ */
684
+ public hasFileAsync(commit: string, filePath: string): Promise<boolean>;
685
+
686
+ /**
687
+ * Tells whether a commit is in another commit's history, such as on a
688
+ * branch.
689
+ *
690
+ * @param commit The commit to look for, which the clone holds.
691
+ * @param descendant The commit or reference whose history is searched; a
692
+ * commit is in its own history.
693
+ * @returns A promise of `true` if the commit is in the descendant's
694
+ * history, otherwise `false`. It rejects with {@link ProcessException} if
695
+ * git cannot start or fails otherwise, such as when the clone holds
696
+ * neither commit.
697
+ * @example
698
+ * ```ts
699
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
700
+ *
701
+ * const git = new Git(new ProcessRunner(), process.cwd());
702
+ * await git.isAncestorAsync("HEAD", "refs/remotes/origin/main"); // true when HEAD is on main
703
+ * ```
704
+ */
705
+ public isAncestorAsync(commit: string, descendant: string): Promise<boolean>;
706
+
707
+ /**
708
+ * Lists the files a commit holds in a folder and the folders inside it.
709
+ *
710
+ * @param commit The commit, which the clone holds.
711
+ * @param folderPath The folder's path from the repository's root, with `/`
712
+ * between folders, such as `src`.
713
+ * @returns A promise of each file's path from the repository's root, with
714
+ * `/` between folders, in git's order; none when the commit has no such
715
+ * folder. It rejects with {@link ProcessException} if git cannot start or
716
+ * fails otherwise, such as when the clone does not hold the commit.
717
+ * @example
718
+ * ```ts
719
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
720
+ *
721
+ * const git = new Git(new ProcessRunner(), process.cwd());
722
+ * await git.listFilesAsync("refs/remotes/origin/main", "src"); // ["src/noldova.tools.pipelines/package.json", …]
723
+ * ```
724
+ */
725
+ public listFilesAsync(commit: string, folderPath: string): Promise<readonly string[]>;
726
+
727
+ /**
728
+ * Reads a file as a commit holds it.
729
+ *
730
+ * @param commit The commit, which holds the file.
731
+ * @param filePath The file's path from the repository's root, with `/`
732
+ * between folders.
733
+ * @returns A promise of the file's content as UTF-8 text. It rejects with
734
+ * {@link ProcessException} if git cannot start or cannot read the file,
735
+ * such as when the commit does not hold it.
736
+ * @example
737
+ * ```ts
738
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
739
+ *
740
+ * const git = new Git(new ProcessRunner(), process.cwd());
741
+ * await git.readFileAsync("refs/remotes/origin/main", "version.json"); // "{\n \"version\": \"0.0.4\"\n}\n"
742
+ * ```
743
+ */
744
+ public readFileAsync(commit: string, filePath: string): Promise<string>;
745
+
746
+ /**
747
+ * Reads the commit the checkout is at.
748
+ *
749
+ * @returns A promise of the commit's full id. It rejects with
750
+ * {@link ProcessException} if git cannot start or fails otherwise, such as
751
+ * in a clone without commits.
752
+ * @example
753
+ * ```ts
754
+ * import { Git, ProcessRunner } from "@noldova/tools.pipelines";
755
+ *
756
+ * const git = new Git(new ProcessRunner(), process.cwd());
757
+ * await git.readHeadAsync(); // "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"
758
+ * ```
759
+ */
760
+ public readHeadAsync(): Promise<string>;
761
+ }
762
+
763
+ /**
764
+ * Reads files from `.tgz` archives through the `tar` program.
765
+ */
766
+ export declare class Tar {
767
+ /**
768
+ * Creates the reader.
769
+ *
770
+ * @param processRunner The runner that starts `tar`.
771
+ * @example
772
+ * ```ts
773
+ * import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
774
+ *
775
+ * const tar = new Tar(new ProcessRunner());
776
+ * ```
777
+ */
778
+ public constructor(processRunner: ProcessRunner);
779
+
780
+ /**
781
+ * Reads one file from an archive.
782
+ *
783
+ * @param archivePath The archive's path, such as
784
+ * `archives/noldova-tools.pipelines-0.0.4.tgz`.
785
+ * @param filePath The file's path inside the archive, such as
786
+ * `package/package.json`.
787
+ * @returns A promise of how `tar` ended: on success, its output is the
788
+ * file's content as UTF-8 text; when the archive is not a `.tgz` or lacks
789
+ * the file, it failed, with `tar`'s message. It rejects with
790
+ * {@link ProcessException} if `tar` cannot start, such as when it is not
791
+ * installed or the archive's folder does not exist.
792
+ * @example
793
+ * ```ts
794
+ * import { ProcessRunner, Tar } from "@noldova/tools.pipelines";
795
+ *
796
+ * const result = await new Tar(new ProcessRunner()).readFileAsync("archives/noldova-tools.pipelines-0.0.4.tgz", "package/package.json");
797
+ * result.isSuccessful; // true when the archive holds the file
798
+ * ```
799
+ */
800
+ public readFileAsync(archivePath: string, filePath: string): Promise<ProcessResult>;
801
+ }
802
+
803
+ /**
804
+ * Runs the `npm` program's registry commands. It passes no credentials;
805
+ * `npm` takes them from its own configuration, such as the environment a
806
+ * pipeline sets up.
807
+ */
808
+ export declare class Npm {
809
+ /**
810
+ * Creates the runner.
811
+ *
812
+ * @param processRunner The runner that starts `npm`.
813
+ * @param workingDirectory The directory `npm` runs in, whose configuration
814
+ * it reads.
815
+ * @example
816
+ * ```ts
817
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
818
+ *
819
+ * const npm = new Npm(new ProcessRunner(), process.cwd());
820
+ * ```
821
+ */
822
+ public constructor(processRunner: ProcessRunner, workingDirectory: string);
823
+
824
+ /**
825
+ * Reads a field of a package or a version from the registry, asking the
826
+ * registry rather than `npm`'s cache.
827
+ *
828
+ * @param specifier The package, such as `@noldova/tools.pipelines`, or one
829
+ * of its versions, such as `@noldova/tools.pipelines@0.0.4`.
830
+ * @param field The field, such as `dist.integrity` or `dist-tags.latest`.
831
+ * @param registry The registry's URL.
832
+ * @returns A promise of how `npm view` ended: on success, its output is the
833
+ * field's value, empty when the version or the field doesn't exist. It
834
+ * rejects with {@link ProcessException} if `npm` cannot start.
835
+ * @example
836
+ * ```ts
837
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
838
+ *
839
+ * const npm = new Npm(new ProcessRunner(), process.cwd());
840
+ * const result = await npm.viewAsync("@noldova/tools.pipelines", "dist-tags.latest", "https://registry.npmjs.org/");
841
+ * result.output; // "0.0.4\n" once 0.0.4 is the latest version
842
+ * ```
843
+ */
844
+ public viewAsync(specifier: string, field: string, registry: string): Promise<ProcessResult>;
845
+
846
+ /**
847
+ * Reads a field of a package or a version from the registry, as
848
+ * {@link Npm.viewAsync} does, and gives its value.
849
+ *
850
+ * @param specifier The package, such as `@noldova/tools.pipelines`, or one
851
+ * of its versions, such as `@noldova/tools.pipelines@0.0.4`.
852
+ * @param field The field, such as `gitHead` or `dist-tags.nightly`.
853
+ * @param registry The registry's URL.
854
+ * @returns A promise of the field's value without surrounding white space,
855
+ * empty when the registry has no such package, version or field, or of a
856
+ * failed {@link StepResult} with one line, such as
857
+ * `@noldova/tools.pipelines: npm view exited with code 1: …`, when `npm`
858
+ * fails otherwise. It rejects with {@link ProcessException} if `npm`
859
+ * cannot start.
860
+ * @example
861
+ * ```ts
862
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
863
+ *
864
+ * const npm = new Npm(new ProcessRunner(), process.cwd());
865
+ * const latest = await npm.readFieldOrEmptyAsync("@noldova/tools.pipelines", "dist-tags.latest", "https://registry.npmjs.org/");
866
+ * latest; // "0.0.4" once 0.0.4 is the latest version
867
+ * ```
868
+ */
869
+ public readFieldOrEmptyAsync(specifier: string, field: string, registry: string): Promise<string | StepResult>;
870
+
871
+ /**
872
+ * Publishes an archive to the registry under a dist-tag.
873
+ *
874
+ * @param archivePath The archive's path, relative to the current folder or
875
+ * full.
876
+ * @param tag The dist-tag the version gets, such as `latest` or `nightly`.
877
+ * @param access `public` or `restricted`.
878
+ * @param registry The registry's URL.
879
+ * @returns A promise of how `npm publish` ended. It rejects with
880
+ * {@link ProcessException} if `npm` cannot start.
881
+ * @example
882
+ * ```ts
883
+ * import { Npm, ProcessRunner } from "@noldova/tools.pipelines";
884
+ *
885
+ * const npm = new Npm(new ProcessRunner(), process.cwd());
886
+ * const result = await npm.publishAsync("archives/noldova-tools.pipelines-0.0.4.tgz", "latest", "public", "https://registry.npmjs.org/");
887
+ * result.isSuccessful; // true when the registry took the archive
888
+ * ```
889
+ */
890
+ public publishAsync(archivePath: string, tag: string, access: string, registry: string): Promise<ProcessResult>;
891
+
892
+ /**
893
+ * Tells whether a text is a registry the steps take: an `https` URL
894
+ * without credentials, a query or a fragment.
895
+ *
896
+ * @param text The text, such as a step's value.
897
+ * @returns `true` when the text is such a URL.
898
+ * @example
899
+ * ```ts
900
+ * import { Npm } from "@noldova/tools.pipelines";
901
+ *
902
+ * Npm.isRegistry("https://registry.npmjs.org/"); // true
903
+ * Npm.isRegistry("https://registry.npmjs.org/?token=x"); // false
904
+ * ```
905
+ */
906
+ public static isRegistry(text: string): boolean;
907
+ }
908
+
909
+ /**
910
+ * The step that checks a release's source before anything is built or
911
+ * published: `source <version> <commit>`. It succeeds only when the version
912
+ * is a version, the commit is a full commit id that the clone holds, the
913
+ * commit is on `origin/main`, and the `version.json` at the commit's root is
914
+ * a JSON object whose `version` is that version.
915
+ */
916
+ export declare class SourceStep implements IStep {
917
+ /**
918
+ * The step's name, `"source"`.
919
+ */
920
+ public readonly name: string;
921
+
922
+ /**
923
+ * The values the step takes, `"<version> <commit>"`.
924
+ */
925
+ public readonly usage: string;
926
+
927
+ /**
928
+ * Creates the step over a clone.
929
+ *
930
+ * @param git The reader of the clone, which has fetched `origin/main` with
931
+ * its history.
932
+ * @example
933
+ * ```ts
934
+ * import { Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
935
+ *
936
+ * const step = new SourceStep(new Git(new ProcessRunner(), process.cwd()));
937
+ * step.name; // "source"
938
+ * ```
939
+ */
940
+ public constructor(git: Git);
941
+
942
+ /**
943
+ * Checks the release's source.
944
+ *
945
+ * @param values The version, such as `0.0.4`, and the commit's full id,
946
+ * 40 lowercase hexadecimal digits.
947
+ * @returns A promise of the result: succeeded, such as
948
+ * `Commit 225059f… is on origin/main, and its version.json holds 0.0.4.`,
949
+ * or failed with the first thing that is wrong, checked in this order: not
950
+ * two values, a version that is not a version, a commit that is not a full
951
+ * id, a commit the clone does not hold, a clone without `origin/main`, a
952
+ * commit not on it, a commit without `version.json`, and a `version` other
953
+ * than the one given. It rejects with `JsonException`, from
954
+ * `@noldova/context.json`, if `version.json` is not a JSON object with a
955
+ * `version` text, and with {@link ProcessException} if git cannot start or
956
+ * fails otherwise.
957
+ * @example
958
+ * ```ts
959
+ * import { Git, ProcessRunner, SourceStep } from "@noldova/tools.pipelines";
960
+ *
961
+ * const step = new SourceStep(new Git(new ProcessRunner(), process.cwd()));
962
+ * const result = await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"]);
963
+ * result.isSuccessful; // true when that commit is on main and holds 0.0.4
964
+ * (await step.runAsync(["0.0.4"])).message; // "The source step takes <version> <commit>."
965
+ * ```
966
+ */
967
+ public runAsync(values: readonly string[]): Promise<StepResult>;
968
+ }
969
+
970
+ /**
971
+ * The step that checks a release's archives before anything is published:
972
+ * `archive <folder> <version> <commit> <scope>`. The packages it expects are
973
+ * the commit's `package.json` files under `src/`, outside `tests/` folders,
974
+ * that are not `"private": true`. It succeeds only when the checkout is at
975
+ * the commit, and the folder holds exactly one archive for each package at
976
+ * the version, named as `npm pack` names it, whose `package/package.json`
977
+ * has the package's name, inside the scope, the version, and the commit as
978
+ * its `gitHead`, is not `"private": true`, and lists any expected package under `dependencies` at
979
+ * exactly the version.
980
+ */
981
+ export declare class ArchiveStep implements IStep {
982
+ /**
983
+ * The step's name, `"archive"`.
984
+ */
985
+ public readonly name: string;
986
+
987
+ /**
988
+ * The values the step takes, `"<folder> <version> <commit> <scope>"`.
989
+ */
990
+ public readonly usage: string;
991
+
992
+ /**
993
+ * Creates the step over a clone and an archive reader.
994
+ *
995
+ * @param git The reader of the clone whose checkout the archives were
996
+ * packed from.
997
+ * @param tar The reader of the archives.
998
+ * @example
999
+ * ```ts
1000
+ * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1001
+ *
1002
+ * const processRunner = new ProcessRunner();
1003
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1004
+ * step.name; // "archive"
1005
+ * ```
1006
+ */
1007
+ public constructor(git: Git, tar: Tar);
1008
+
1009
+ /**
1010
+ * Checks the release's archives.
1011
+ *
1012
+ * @param values The folder of archives, such as `archives`; the version,
1013
+ * such as `0.0.4`; the commit's full id, 40 lowercase hexadecimal digits;
1014
+ * and the scope, such as `@noldova`.
1015
+ * @returns A promise of the result. It succeeds with one line for each
1016
+ * archive, such as
1017
+ * `noldova-tools.pipelines-0.0.4.tgz: @noldova/tools.pipelines@0.0.4 from commit 225059f…`.
1018
+ * It fails with the first of these that is wrong: not four values, a
1019
+ * version that is not a version, a commit that is not a full id, a scope
1020
+ * that is not `@` and a lowercase name, a checkout at another commit, a
1021
+ * folder that does not exist, and a commit without a package to publish.
1022
+ * Otherwise it fails with one line for each problem with the archives: an
1023
+ * archive missing, a file that is not an expected archive, an archive
1024
+ * `tar` cannot read the manifest of, with `tar`'s exit code and message,
1025
+ * and a manifest with another name, a name outside the scope, another
1026
+ * version, no `gitHead` or another one, `"private": true`, or an expected package under `dependencies`
1027
+ * at anything but exactly the version. It rejects with `JsonException`,
1028
+ * from `@noldova/context.json`, if a `package.json` the step reads is not
1029
+ * a JSON object, lacks a `name` or `version` text where it needs one, has
1030
+ * a `gitHead` that is not a text, or
1031
+ * has a `private` that is not `true` or `false` or `dependencies` that are
1032
+ * not an object of texts, and with {@link ProcessException} if git or
1033
+ * `tar` cannot start or git fails otherwise.
1034
+ * @example
1035
+ * ```ts
1036
+ * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1037
+ *
1038
+ * const processRunner = new ProcessRunner();
1039
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1040
+ * const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
1041
+ * result.isSuccessful; // true when the folder holds exactly the packages at 0.0.4
1042
+ * (await step.runAsync(["archives"])).message; // "The archive step takes <folder> <version> <commit> <scope>."
1043
+ * ```
1044
+ */
1045
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1046
+
1047
+ /**
1048
+ * Checks the release's archives as {@link ArchiveStep.runAsync} does, and
1049
+ * gives the archives it checked with the result, for a step that goes on
1050
+ * to use them.
1051
+ *
1052
+ * @param values The same values as {@link ArchiveStep.runAsync}.
1053
+ * @returns A promise of the check: the result, and when it succeeded, each
1054
+ * expected package with its archive, by package name. It rejects as
1055
+ * {@link ArchiveStep.runAsync} does.
1056
+ * @example
1057
+ * ```ts
1058
+ * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1059
+ *
1060
+ * const processRunner = new ProcessRunner();
1061
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1062
+ * const check = await step.checkAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova"]);
1063
+ * check.archives.map(t => t.packageName); // ["@noldova/tools.pipelines"] when the check succeeded
1064
+ * ```
1065
+ */
1066
+ public checkAsync(values: readonly string[]): Promise<ArchiveCheck>;
1067
+
1068
+ /**
1069
+ * Reads the names of the packages the step expects at a commit: those of
1070
+ * its `package.json` files under `src/`, outside `tests/` folders, that are
1071
+ * not `"private": true`.
1072
+ *
1073
+ * @param commit The commit's full id.
1074
+ * @returns A promise of the names, sorted, and empty when there is none. It
1075
+ * rejects with `JsonException` and {@link ProcessException} as
1076
+ * {@link ArchiveStep.runAsync} does.
1077
+ * @example
1078
+ * ```ts
1079
+ * import { ArchiveStep, Git, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1080
+ *
1081
+ * const processRunner = new ProcessRunner();
1082
+ * const step = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1083
+ * const names = await step.readPackageNamesAsync("225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8");
1084
+ * names; // ["@noldova/tools.pipelines"]
1085
+ * ```
1086
+ */
1087
+ public readPackageNamesAsync(commit: string): Promise<readonly string[]>;
1088
+ }
1089
+
1090
+ /**
1091
+ * The step that publishes a release's archives:
1092
+ * `publish <folder> <version> <commit> <scope> <registry> <access>`. It runs
1093
+ * {@link ArchiveStep}'s checks first, then publishes each package whose
1094
+ * version the registry doesn't have and waits until the registry serves each
1095
+ * version it published with the same archive.
1096
+ */
1097
+ export declare class PublishStep implements IStep {
1098
+ /**
1099
+ * The step's name, `"publish"`.
1100
+ */
1101
+ public readonly name: string;
1102
+
1103
+ /**
1104
+ * The values the step takes,
1105
+ * `"<folder> <version> <commit> <scope> <registry> <access>"`.
1106
+ */
1107
+ public readonly usage: string;
1108
+
1109
+ /**
1110
+ * Creates the step.
1111
+ *
1112
+ * @param archiveStep The step that checks the archives first.
1113
+ * @param npm The runner of `npm`, which publishes and reads the registry.
1114
+ * @param waitMilliseconds How long the step waits, after its last publish,
1115
+ * for the registry to serve every version it published; 10 minutes by
1116
+ * default.
1117
+ * @param retryMilliseconds How long the step waits between two reads of
1118
+ * the registry while it waits; 10 seconds by default.
1119
+ * @example
1120
+ * ```ts
1121
+ * import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
1122
+ *
1123
+ * const processRunner = new ProcessRunner();
1124
+ * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1125
+ * const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
1126
+ * step.name; // "publish"
1127
+ * ```
1128
+ */
1129
+ public constructor(archiveStep: ArchiveStep, npm: Npm, waitMilliseconds?: number, retryMilliseconds?: number);
1130
+
1131
+ /**
1132
+ * Publishes the release's archives.
1133
+ *
1134
+ * @param values The archive step's four values, then the registry, an
1135
+ * `https` URL without credentials, a query or a fragment, such as
1136
+ * `https://registry.npmjs.org/`, and the access, `public` or `restricted`.
1137
+ * A release is published under the `latest` dist-tag, and a nightly
1138
+ * version under `nightly`; a nightly version must be newer than both.
1139
+ * @returns A promise of the result. It succeeds with one line for each
1140
+ * package, such as `@noldova/tools.pipelines@0.0.4 published.` or
1141
+ * `@noldova/tools.pipelines@0.0.4 is already published from this archive.`
1142
+ * It fails with the first of these that is wrong, publishing nothing: not
1143
+ * six values, a registry or an access that is not one, or the archive
1144
+ * step's failure. Otherwise, before it publishes anything, it fails with
1145
+ * one line for each version the registry already has from another
1146
+ * archive, each version not newer than the version a tag it must pass
1147
+ * points to, and each
1148
+ * read of the registry that fails, with `npm`'s exit code and message.
1149
+ * After that, it publishes the archives in turn and stops at the first
1150
+ * publish that fails; it still waits for the versions it published before
1151
+ * it, and fails with a line for that publish, with `npm`'s exit code and
1152
+ * message, and for each version the registry does not serve in time or
1153
+ * serves from another archive. A URL's credentials, query and fragment in
1154
+ * `npm`'s message are left out of the line. It rejects as {@link ArchiveStep.runAsync} does,
1155
+ * and with {@link ProcessException} if `npm` cannot start.
1156
+ * @example
1157
+ * ```ts
1158
+ * import { ArchiveStep, Git, Npm, ProcessRunner, PublishStep, Tar } from "@noldova/tools.pipelines";
1159
+ *
1160
+ * const processRunner = new ProcessRunner();
1161
+ * const archiveStep = new ArchiveStep(new Git(processRunner, process.cwd()), new Tar(processRunner));
1162
+ * const step = new PublishStep(archiveStep, new Npm(processRunner, process.cwd()));
1163
+ * const result = await step.runAsync(["archives", "0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "@noldova", "https://registry.npmjs.org/", "public"]);
1164
+ * result.isSuccessful; // true when every package's 0.0.4 is published and served
1165
+ * ```
1166
+ */
1167
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1168
+ }
1169
+
1170
+ /**
1171
+ * The step that works out a nightly build's version: `nightly <commit> <registry>`.
1172
+ * It prints the version when `main` has changed since the packages' last
1173
+ * nightly versions, and nothing otherwise, so a pipeline publishes a nightly
1174
+ * build only when there is something new.
1175
+ */
1176
+ export declare class NightlyStep implements IStep {
1177
+ /**
1178
+ * The step's name, `"nightly"`.
1179
+ */
1180
+ public readonly name: string;
1181
+
1182
+ /**
1183
+ * The values the step takes, `"<commit> <registry>"`.
1184
+ */
1185
+ public readonly usage: string;
1186
+
1187
+ /**
1188
+ * Creates the step.
1189
+ *
1190
+ * @param git The reader of the clone that holds the commit.
1191
+ * @param archiveStep The step whose expected packages the step looks up.
1192
+ * @param npm The runner of `npm`, which reads the registry.
1193
+ * @param readNow The clock the step takes the date from; the current time
1194
+ * by default.
1195
+ * @example
1196
+ * ```ts
1197
+ * import { ArchiveStep, Git, NightlyStep, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1198
+ *
1199
+ * const processRunner = new ProcessRunner();
1200
+ * const git = new Git(processRunner, process.cwd());
1201
+ * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
1202
+ * step.name; // "nightly"
1203
+ * ```
1204
+ */
1205
+ public constructor(git: Git, archiveStep: ArchiveStep, npm: Npm, readNow?: () => Date);
1206
+
1207
+ /**
1208
+ * Works out the nightly version.
1209
+ *
1210
+ * @param values The commit's full id, 40 lowercase hexadecimal digits, and
1211
+ * the registry, an `https` URL without credentials, a query or a fragment,
1212
+ * such as `https://registry.npmjs.org/`.
1213
+ * @returns A promise of the result. It succeeds with the version alone,
1214
+ * the release in `version.json` at the commit with one more patch and the
1215
+ * UTC date, such as `0.0.5-nightly.20261102` for `0.0.4` on November 2,
1216
+ * 2026. It succeeds with an empty message when the last nightly version of
1217
+ * every package the archive step expects has the commit as its `gitHead`,
1218
+ * or is from the same UTC date. It fails with the first of these that is
1219
+ * wrong: not two values, a commit that is not a full id, a registry that is
1220
+ * not one, a commit the clone does not hold, a clone without `origin/main`,
1221
+ * a commit not on it, a commit without `version.json`, a `version` that is
1222
+ * not a release version, and a commit without a package to publish.
1223
+ * Otherwise it fails with one line for each read of the registry that
1224
+ * fails, with `npm`'s exit code and message, and for each `nightly`
1225
+ * dist-tag that is not a version, or with one line naming the packages
1226
+ * whose last nightly version is from the same UTC date when only some are.
1227
+ * It rejects with `JsonException`, from `@noldova/context.json`, if
1228
+ * `version.json` is not a JSON object with a `version` text, and as
1229
+ * {@link ArchiveStep.readPackageNamesAsync} does.
1230
+ * @example
1231
+ * ```ts
1232
+ * import { ArchiveStep, Git, NightlyStep, Npm, ProcessRunner, Tar } from "@noldova/tools.pipelines";
1233
+ *
1234
+ * const processRunner = new ProcessRunner();
1235
+ * const git = new Git(processRunner, process.cwd());
1236
+ * const step = new NightlyStep(git, new ArchiveStep(git, new Tar(processRunner)), new Npm(processRunner, process.cwd()));
1237
+ * const result = await step.runAsync(["225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8", "https://registry.npmjs.org/"]);
1238
+ * result.message; // "0.0.5-nightly.20261102", or "" when nothing changed
1239
+ * ```
1240
+ */
1241
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1242
+ }
1243
+
1244
+ /**
1245
+ * The step a release ends with: it tags the released commit `v<version>`,
1246
+ * through the host's {@link ITagHost}, and never moves a tag.
1247
+ */
1248
+ export declare class TagStep implements IStep {
1249
+ /**
1250
+ * The step's name, `"tag"`.
1251
+ */
1252
+ public readonly name: string;
1253
+
1254
+ /**
1255
+ * The values the step takes, `"<version> <commit>"`.
1256
+ */
1257
+ public readonly usage: string;
1258
+
1259
+ /**
1260
+ * Creates the step over a host's tags.
1261
+ *
1262
+ * @param tagHost How the step reads and creates a tag on the host.
1263
+ * @example
1264
+ * ```ts
1265
+ * import { type ITagHost, TagStep } from "@noldova/tools.pipelines";
1266
+ *
1267
+ * const tags = new Map<string, string>();
1268
+ * const host: ITagHost = {
1269
+ * readTagAsync: async tag => tags.get(tag) ?? "",
1270
+ * createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
1271
+ * };
1272
+ * const step = new TagStep(host);
1273
+ * step.name; // "tag"
1274
+ * ```
1275
+ */
1276
+ public constructor(tagHost: ITagHost);
1277
+
1278
+ /**
1279
+ * Tags a release's commit with its version.
1280
+ *
1281
+ * @param values The release version, such as `0.0.4`, and the commit's
1282
+ * full id, 40 lowercase hexadecimal digits.
1283
+ * @returns A promise of the result. It fails, before asking the host, for
1284
+ * values other than two, a version that is not a version, a nightly
1285
+ * version, which gets no tag, or a commit that is not a full id. When the
1286
+ * host has no `v<version>`, it creates it and succeeds, such as
1287
+ * `Tagged commit 225059f… as v0.0.4.`; when the host already has it, such
1288
+ * as from another run that made it first, it succeeds if the tag points to
1289
+ * the commit, `v0.0.4 already points to commit 225059f….`, and fails,
1290
+ * naming both commits, if it points to another. A failed answer of the host
1291
+ * is the result as the host gives it.
1292
+ * @example
1293
+ * ```ts
1294
+ * import { type ITagHost, TagStep } from "@noldova/tools.pipelines";
1295
+ *
1296
+ * const tags = new Map<string, string>();
1297
+ * const host: ITagHost = {
1298
+ * readTagAsync: async tag => tags.get(tag) ?? "",
1299
+ * createTagAsync: async (tag, commit) => tags.has(tag) ? false : (tags.set(tag, commit), true)
1300
+ * };
1301
+ * const step = new TagStep(host);
1302
+ * (await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message; // "Tagged commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8 as v0.0.4."
1303
+ * (await step.runAsync(["0.0.4", "225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8"])).message; // "v0.0.4 already points to commit 225059f4c1e6a3b2d8f7e9a0b1c2d3e4f5a6b7c8."
1304
+ * ```
1305
+ */
1306
+ public runAsync(values: readonly string[]): Promise<StepResult>;
1307
+ }