@git.zone/cli 9.2.2 → 10.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/assets/templates/asset_binary_installer/install.sh +109 -34
  2. package/assets/templates/asset_binary_release_gitea/.gitea/workflows/release.yml +17 -4
  3. package/assets/templates/ci_rust/.gitea/workflows/rust_nottags.yaml +29 -0
  4. package/assets/templates/ci_rust/.gitea/workflows/rust_tags.yaml +32 -0
  5. package/assets/templates/gitignore/_gitignore +1 -1
  6. package/assets/templates/gitignore_rust/_gitignore +31 -0
  7. package/assets/templates/license_mit/license +4 -1
  8. package/assets/templates/rust/.smartscaf.yml +16 -0
  9. package/assets/templates/rust/_Cargo.toml +12 -0
  10. package/assets/templates/rust/_crate_Cargo.toml +10 -0
  11. package/assets/templates/rust/_crate_lib.rs +19 -0
  12. package/assets/templates/rust/_smartconfig.json +27 -0
  13. package/assets/templates/rust/readme.md +23 -0
  14. package/dist_ts/00_commitinfo_data.js +2 -2
  15. package/dist_ts/classes.gitzoneconfig.d.ts +3 -1
  16. package/dist_ts/classes.gitzoneconfig.js +9 -1
  17. package/dist_ts/helpers.managedassets.d.ts +1 -1
  18. package/dist_ts/helpers.managedassets.js +58 -14
  19. package/dist_ts/helpers.releasetargets.d.ts +6 -0
  20. package/dist_ts/helpers.releasetargets.js +13 -0
  21. package/dist_ts/helpers.smartconfigmigrations.js +42 -1
  22. package/dist_ts/helpers.toolconfig.d.ts +50 -0
  23. package/dist_ts/helpers.toolconfig.js +212 -0
  24. package/dist_ts/helpers.tssea.d.ts +9 -2
  25. package/dist_ts/helpers.tssea.js +47 -17
  26. package/dist_ts/helpers.tstest.d.ts +27 -8
  27. package/dist_ts/helpers.tstest.js +64 -26
  28. package/dist_ts/helpers.versionsource.d.ts +37 -0
  29. package/dist_ts/helpers.versionsource.js +112 -0
  30. package/dist_ts/helpers.workflow.d.ts +45 -1
  31. package/dist_ts/helpers.workflow.js +120 -5
  32. package/dist_ts/mod_commit/mod.helpers.d.ts +0 -24
  33. package/dist_ts/mod_commit/mod.helpers.js +1 -94
  34. package/dist_ts/mod_config/index.js +131 -18
  35. package/dist_ts/mod_format/formatters/assets.formatter.js +29 -27
  36. package/dist_ts/mod_format/formatters/gitignore.formatter.d.ts +4 -2
  37. package/dist_ts/mod_format/formatters/gitignore.formatter.js +10 -7
  38. package/dist_ts/mod_format/formatters/license.formatter.d.ts +8 -0
  39. package/dist_ts/mod_format/formatters/license.formatter.js +25 -2
  40. package/dist_ts/mod_format/formatters/packagejson.formatter.js +14 -3
  41. package/dist_ts/mod_format/formatters/rustfmt.formatter.d.ts +19 -0
  42. package/dist_ts/mod_format/formatters/rustfmt.formatter.js +97 -0
  43. package/dist_ts/mod_format/formatters/smartconfig.formatter.js +5 -2
  44. package/dist_ts/mod_format/index.js +3 -1
  45. package/dist_ts/mod_format/interfaces.format.js +2 -1
  46. package/dist_ts/mod_release/classes.releasejournal.d.ts +38 -2
  47. package/dist_ts/mod_release/classes.releasejournal.js +238 -66
  48. package/dist_ts/mod_release/helpers.cargorelease.d.ts +52 -0
  49. package/dist_ts/mod_release/helpers.cargorelease.js +195 -0
  50. package/dist_ts/mod_release/helpers.npmpackages.d.ts +18 -0
  51. package/dist_ts/mod_release/helpers.npmpackages.js +40 -2
  52. package/dist_ts/mod_release/helpers.releasecheck.d.ts +73 -0
  53. package/dist_ts/mod_release/helpers.releasecheck.js +269 -0
  54. package/dist_ts/mod_release/helpers.releasepreparation.d.ts +22 -8
  55. package/dist_ts/mod_release/helpers.releasepreparation.js +74 -26
  56. package/dist_ts/mod_release/helpers.releasepublication.d.ts +21 -1
  57. package/dist_ts/mod_release/helpers.releasepublication.js +249 -4
  58. package/dist_ts/mod_release/helpers.releaseversionsource.d.ts +10 -0
  59. package/dist_ts/mod_release/helpers.releaseversionsource.js +18 -0
  60. package/dist_ts/mod_release/helpers.rsrepoengine.d.ts +192 -0
  61. package/dist_ts/mod_release/helpers.rsrepoengine.js +457 -0
  62. package/dist_ts/mod_release/index.d.ts +3 -0
  63. package/dist_ts/mod_release/index.js +177 -65
  64. package/dist_ts/mod_template/index.js +6 -2
  65. package/package.json +1 -1
  66. package/readme.md +237 -21
  67. package/ts/00_commitinfo_data.ts +1 -1
  68. package/ts/classes.gitzoneconfig.ts +10 -1
  69. package/ts/helpers.managedassets.ts +64 -14
  70. package/ts/helpers.releasetargets.ts +13 -0
  71. package/ts/helpers.smartconfigmigrations.ts +48 -0
  72. package/ts/helpers.toolconfig.ts +280 -0
  73. package/ts/helpers.tssea.ts +59 -16
  74. package/ts/helpers.tstest.ts +105 -35
  75. package/ts/helpers.versionsource.ts +169 -0
  76. package/ts/helpers.workflow.ts +197 -5
  77. package/ts/mod_commit/mod.helpers.ts +0 -119
  78. package/ts/mod_config/index.ts +169 -19
  79. package/ts/mod_format/formatters/assets.formatter.ts +28 -27
  80. package/ts/mod_format/formatters/gitignore.formatter.ts +10 -6
  81. package/ts/mod_format/formatters/license.formatter.ts +26 -1
  82. package/ts/mod_format/formatters/packagejson.formatter.ts +14 -2
  83. package/ts/mod_format/formatters/rustfmt.formatter.ts +107 -0
  84. package/ts/mod_format/formatters/smartconfig.formatter.ts +8 -1
  85. package/ts/mod_format/index.ts +2 -0
  86. package/ts/mod_format/interfaces.format.ts +1 -0
  87. package/ts/mod_release/classes.releasejournal.ts +312 -39
  88. package/ts/mod_release/helpers.cargorelease.ts +289 -0
  89. package/ts/mod_release/helpers.npmpackages.ts +76 -1
  90. package/ts/mod_release/helpers.releasecheck.ts +409 -0
  91. package/ts/mod_release/helpers.releasepreparation.ts +116 -36
  92. package/ts/mod_release/helpers.releasepublication.ts +462 -1
  93. package/ts/mod_release/helpers.releaseversionsource.ts +29 -0
  94. package/ts/mod_release/helpers.rsrepoengine.ts +790 -0
  95. package/ts/mod_release/index.ts +277 -84
  96. package/ts/mod_template/index.ts +5 -1
@@ -0,0 +1,790 @@
1
+ import * as plugins from "./mod.plugins.js";
2
+ import { formatCommandFailure } from "./helpers.commandfailure.js";
3
+
4
+ /**
5
+ * The rsrepo release engine protocol, version 1. gitzone delegates every Cargo
6
+ * operation of a release (workspace plan, version edit, packaging, publication
7
+ * and registry probes) to `rsrepo engine <command> --request <file>`, the way
8
+ * Docker releases delegate to project-local tSDocker. The types are duplicated
9
+ * here on purpose: the CLI never depends on `@git.zone/rsrepo`, so it resolves
10
+ * the engine at run time and checks the protocol version instead.
11
+ */
12
+ export const rsrepoEngineProtocol = "gitzone-rsrepo-engine" as const;
13
+ export const rsrepoEngineProtocolVersion = 1 as const;
14
+
15
+ export type TRsrepoEngineCommand =
16
+ | "capabilities"
17
+ | "plan"
18
+ | "set-version"
19
+ | "package"
20
+ | "publish"
21
+ | "probe";
22
+
23
+ export const rsrepoEngineCommands: readonly TRsrepoEngineCommand[] = [
24
+ "capabilities",
25
+ "plan",
26
+ "set-version",
27
+ "package",
28
+ "publish",
29
+ "probe",
30
+ ];
31
+
32
+ export type TRsrepoEngineErrorCode =
33
+ | "bad-request"
34
+ | "unsupported-command"
35
+ | "no-workspace"
36
+ | "cargo-failed"
37
+ | "layout-unsupported"
38
+ | "independent-versions"
39
+ | "already-published"
40
+ | "publish-rejected"
41
+ | "registry-unreachable"
42
+ | "not-found";
43
+
44
+ const rsrepoEngineErrorCodes: readonly TRsrepoEngineErrorCode[] = [
45
+ "bad-request",
46
+ "unsupported-command",
47
+ "no-workspace",
48
+ "cargo-failed",
49
+ "layout-unsupported",
50
+ "independent-versions",
51
+ "already-published",
52
+ "publish-rejected",
53
+ "registry-unreachable",
54
+ "not-found",
55
+ ];
56
+
57
+ export interface IRsrepoEngineError {
58
+ code: TRsrepoEngineErrorCode;
59
+ message: string;
60
+ details?: unknown;
61
+ }
62
+
63
+ export interface IRsrepoEngineEnvelope<T> {
64
+ protocol: typeof rsrepoEngineProtocol;
65
+ protocolVersion: typeof rsrepoEngineProtocolVersion;
66
+ ok: boolean;
67
+ result?: T;
68
+ error?: IRsrepoEngineError;
69
+ }
70
+
71
+ export interface IRsrepoCapabilitiesResult {
72
+ rsrepoVersion: string;
73
+ cargoVersion: string;
74
+ commands: string[];
75
+ }
76
+
77
+ export interface IRsrepoPlanRequest {
78
+ cwd: string;
79
+ registries: string[];
80
+ members?: string[];
81
+ }
82
+
83
+ export type TRsrepoWorkspaceLayout = "root" | "rust" | "ts_rust";
84
+ export type TRsrepoVersionMode = "workspace" | "single" | "independent";
85
+ export type TRsrepoDependencyKind = "normal" | "build" | "dev";
86
+
87
+ export interface IRsrepoPlanDependency {
88
+ name: string;
89
+ requirement: string | null;
90
+ kind: TRsrepoDependencyKind;
91
+ }
92
+
93
+ export interface IRsrepoPlanProblem {
94
+ code: string;
95
+ message: string;
96
+ blocking: boolean;
97
+ }
98
+
99
+ /**
100
+ * Problem codes whose class the protocol fixes (Appendix P, R2 gate): a
101
+ * dependency that cannot be published blocks its dependent; a dependency the
102
+ * release does not select and a member with `publish = false` are notes. Any
103
+ * other code is classified by the engine's own `blocking` flag.
104
+ */
105
+ export const rsrepoPlanProblemBlocking: Readonly<Record<string, boolean>> = {
106
+ "dependency-unpublishable": true,
107
+ "dependency-not-selected": false,
108
+ "publish-disabled": false,
109
+ };
110
+
111
+ export interface IRsrepoPlanMember {
112
+ name: string;
113
+ version: string;
114
+ manifestPath: string;
115
+ /** Cargo `publish`: null admits any registry, an empty list none. */
116
+ publish: string[] | null;
117
+ license: string | null;
118
+ licenseFile: string | null;
119
+ description: string | null;
120
+ internalDependencies: IRsrepoPlanDependency[];
121
+ /** Publishable to every requested registry and named in `members`, if given. */
122
+ selected: boolean;
123
+ problems: IRsrepoPlanProblem[];
124
+ }
125
+
126
+ export interface IRsrepoPlanResult {
127
+ workspaceRoot: string;
128
+ layout: TRsrepoWorkspaceLayout;
129
+ versionMode: TRsrepoVersionMode;
130
+ /** The shared version of a workspace or single package; null when independent. */
131
+ version: string | null;
132
+ /** A tracked Cargo.lock exists. */
133
+ lockfile: boolean;
134
+ members: IRsrepoPlanMember[];
135
+ /** Selected members, dependencies first. */
136
+ order: string[];
137
+ }
138
+
139
+ export interface IRsrepoSetVersionRequest {
140
+ cwd: string;
141
+ version: string;
142
+ }
143
+
144
+ export interface IRsrepoSetVersionResult {
145
+ previousVersion: string;
146
+ version: string;
147
+ /** Paths relative to the workspace root. */
148
+ changedFiles: string[];
149
+ }
150
+
151
+ export interface IRsrepoPackageRequest {
152
+ cwd: string;
153
+ outDir: string;
154
+ members: string[];
155
+ }
156
+
157
+ export interface IRsrepoPackedCrate {
158
+ name: string;
159
+ version: string;
160
+ file: string;
161
+ sha256: string;
162
+ files: string[];
163
+ }
164
+
165
+ export interface IRsrepoPackageResult {
166
+ crates: IRsrepoPackedCrate[];
167
+ }
168
+
169
+ export interface IRsrepoPublishRequest {
170
+ cwd: string;
171
+ registry: string;
172
+ member: string;
173
+ }
174
+
175
+ export interface IRsrepoPublishResult {
176
+ name: string;
177
+ version: string;
178
+ registry: string;
179
+ state: "accepted";
180
+ }
181
+
182
+ export interface IRsrepoProbeRequest {
183
+ registry: string;
184
+ name: string;
185
+ version: string;
186
+ /** Where the engine starts its cargo config lookup for registry names. */
187
+ cwd?: string;
188
+ }
189
+
190
+ export interface IRsrepoProbeResult {
191
+ present: boolean;
192
+ cksum: string | null;
193
+ yanked: boolean | null;
194
+ }
195
+
196
+ /** Every Cargo operation of a release, behind one replaceable seam. */
197
+ export interface IRsrepoEngineClient {
198
+ /** The engine binary this client runs. */
199
+ readonly binaryPath: string;
200
+ capabilities: () => Promise<IRsrepoCapabilitiesResult>;
201
+ /** Capabilities, refused unless every named command is supported. */
202
+ assertCapabilities: (
203
+ commandsArg: readonly TRsrepoEngineCommand[],
204
+ ) => Promise<IRsrepoCapabilitiesResult>;
205
+ plan: (requestArg: IRsrepoPlanRequest) => Promise<IRsrepoPlanResult>;
206
+ setVersion: (
207
+ requestArg: IRsrepoSetVersionRequest,
208
+ ) => Promise<IRsrepoSetVersionResult>;
209
+ package: (requestArg: IRsrepoPackageRequest) => Promise<IRsrepoPackageResult>;
210
+ publish: (requestArg: IRsrepoPublishRequest) => Promise<IRsrepoPublishResult>;
211
+ probe: (requestArg: IRsrepoProbeRequest) => Promise<IRsrepoProbeResult>;
212
+ }
213
+
214
+ /**
215
+ * A command that ran and answered with a protocol error, or whose outcome is
216
+ * not a valid protocol answer (`protocol-failure`). A publish that ends in a
217
+ * protocol failure has an unknown outcome; only a probe can settle it.
218
+ */
219
+ export class RsrepoEngineCommandError extends Error {
220
+ constructor(
221
+ public readonly command: TRsrepoEngineCommand,
222
+ public readonly code: TRsrepoEngineErrorCode | "protocol-failure",
223
+ messageArg: string,
224
+ ) {
225
+ super(messageArg);
226
+ this.name = "RsrepoEngineCommandError";
227
+ }
228
+ }
229
+
230
+ const commandTimeouts: Record<TRsrepoEngineCommand, number> = {
231
+ capabilities: 30_000,
232
+ plan: 5 * 60_000,
233
+ "set-version": 10 * 60_000,
234
+ package: 60 * 60_000,
235
+ publish: 30 * 60_000,
236
+ probe: 2 * 60_000,
237
+ };
238
+
239
+ /** stdout and stderr together; cargo's progress output goes to stderr. */
240
+ const outputByteLimit = 16 * 1024 * 1024;
241
+
242
+ const isPlainObject = (
243
+ valueArg: unknown,
244
+ ): valueArg is Record<string, unknown> =>
245
+ typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
246
+
247
+ const assertKeys = (
248
+ valueArg: Record<string, unknown>,
249
+ requiredArg: readonly string[],
250
+ optionalArg: readonly string[],
251
+ contextArg: string,
252
+ ): void => {
253
+ for (const key of requiredArg) {
254
+ if (!Object.hasOwn(valueArg, key)) {
255
+ throw new Error(`${contextArg} lacks ${key}.`);
256
+ }
257
+ }
258
+ const unknownKey = Object.keys(valueArg).find(
259
+ (keyArg) => !requiredArg.includes(keyArg) && !optionalArg.includes(keyArg),
260
+ );
261
+ if (unknownKey !== undefined) {
262
+ throw new Error(`${contextArg} carries the unknown key ${unknownKey}.`);
263
+ }
264
+ };
265
+
266
+ const isString = (valueArg: unknown): valueArg is string =>
267
+ typeof valueArg === "string";
268
+
269
+ const isNonEmptyString = (valueArg: unknown): valueArg is string =>
270
+ typeof valueArg === "string" && valueArg.length > 0;
271
+
272
+ const isStringOrNull = (valueArg: unknown): valueArg is string | null =>
273
+ valueArg === null || typeof valueArg === "string";
274
+
275
+ const isStringArray = (valueArg: unknown): valueArg is string[] =>
276
+ Array.isArray(valueArg) && valueArg.every(isString);
277
+
278
+ const sha256Pattern = /^[0-9a-f]{64}$/;
279
+
280
+ /** A crate name as crates.io accepts it. */
281
+ export const isCargoCrateName = (valueArg: unknown): valueArg is string =>
282
+ typeof valueArg === "string" &&
283
+ /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(valueArg);
284
+
285
+ /** `crates-io` or a registry name defined in cargo config. */
286
+ export const isCargoRegistryName = (valueArg: unknown): valueArg is string =>
287
+ typeof valueArg === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(valueArg);
288
+
289
+ export const assertRsrepoCapabilitiesResult = (
290
+ valueArg: unknown,
291
+ ): IRsrepoCapabilitiesResult => {
292
+ const context = "rsrepo engine capabilities";
293
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
294
+ assertKeys(valueArg, ["rsrepoVersion", "cargoVersion", "commands"], [], context);
295
+ if (
296
+ !isNonEmptyString(valueArg.rsrepoVersion) ||
297
+ !isNonEmptyString(valueArg.cargoVersion) ||
298
+ !isStringArray(valueArg.commands)
299
+ ) {
300
+ throw new Error(`${context} is invalid.`);
301
+ }
302
+ return valueArg as unknown as IRsrepoCapabilitiesResult;
303
+ };
304
+
305
+ const assertPlanMember = (
306
+ valueArg: unknown,
307
+ contextArg: string,
308
+ ): IRsrepoPlanMember => {
309
+ if (!isPlainObject(valueArg)) throw new Error(`${contextArg} must be an object.`);
310
+ assertKeys(
311
+ valueArg,
312
+ [
313
+ "name",
314
+ "version",
315
+ "manifestPath",
316
+ "publish",
317
+ "license",
318
+ "licenseFile",
319
+ "description",
320
+ "internalDependencies",
321
+ "selected",
322
+ "problems",
323
+ ],
324
+ [],
325
+ contextArg,
326
+ );
327
+ if (
328
+ !isCargoCrateName(valueArg.name) ||
329
+ !isNonEmptyString(valueArg.version) ||
330
+ !isNonEmptyString(valueArg.manifestPath) ||
331
+ !(valueArg.publish === null || isStringArray(valueArg.publish)) ||
332
+ !isStringOrNull(valueArg.license) ||
333
+ !isStringOrNull(valueArg.licenseFile) ||
334
+ !isStringOrNull(valueArg.description) ||
335
+ typeof valueArg.selected !== "boolean" ||
336
+ !Array.isArray(valueArg.internalDependencies) ||
337
+ !Array.isArray(valueArg.problems)
338
+ ) {
339
+ throw new Error(`${contextArg} is invalid.`);
340
+ }
341
+ for (const [index, dependency] of valueArg.internalDependencies.entries()) {
342
+ const dependencyContext = `${contextArg} internal dependency ${index}`;
343
+ if (!isPlainObject(dependency))
344
+ throw new Error(`${dependencyContext} must be an object.`);
345
+ assertKeys(dependency, ["name", "requirement", "kind"], [], dependencyContext);
346
+ if (
347
+ !isCargoCrateName(dependency.name) ||
348
+ !isStringOrNull(dependency.requirement) ||
349
+ !["normal", "build", "dev"].includes(dependency.kind as string)
350
+ ) {
351
+ throw new Error(`${dependencyContext} is invalid.`);
352
+ }
353
+ }
354
+ for (const [index, problem] of valueArg.problems.entries()) {
355
+ const problemContext = `${contextArg} problem ${index}`;
356
+ if (!isPlainObject(problem))
357
+ throw new Error(`${problemContext} must be an object.`);
358
+ assertKeys(problem, ["code", "message", "blocking"], [], problemContext);
359
+ if (
360
+ !isNonEmptyString(problem.code) ||
361
+ !isNonEmptyString(problem.message) ||
362
+ typeof problem.blocking !== "boolean"
363
+ ) {
364
+ throw new Error(`${problemContext} is invalid.`);
365
+ }
366
+ const expectedBlocking = Object.hasOwn(rsrepoPlanProblemBlocking, problem.code)
367
+ ? rsrepoPlanProblemBlocking[problem.code]
368
+ : undefined;
369
+ if (expectedBlocking !== undefined && problem.blocking !== expectedBlocking) {
370
+ throw new Error(
371
+ `${problemContext} classifies ${problem.code} as ${problem.blocking ? "blocking" : "non-blocking"}; protocol v1 makes it ${expectedBlocking ? "blocking" : "non-blocking"}.`,
372
+ );
373
+ }
374
+ }
375
+ return valueArg as unknown as IRsrepoPlanMember;
376
+ };
377
+
378
+ export const assertRsrepoPlanResult = (valueArg: unknown): IRsrepoPlanResult => {
379
+ const context = "rsrepo engine plan";
380
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
381
+ assertKeys(
382
+ valueArg,
383
+ [
384
+ "workspaceRoot",
385
+ "layout",
386
+ "versionMode",
387
+ "version",
388
+ "lockfile",
389
+ "members",
390
+ "order",
391
+ ],
392
+ [],
393
+ context,
394
+ );
395
+ if (
396
+ !isNonEmptyString(valueArg.workspaceRoot) ||
397
+ !plugins.path.isAbsolute(valueArg.workspaceRoot) ||
398
+ !["root", "rust", "ts_rust"].includes(valueArg.layout as string) ||
399
+ !["workspace", "single", "independent"].includes(
400
+ valueArg.versionMode as string,
401
+ ) ||
402
+ !isStringOrNull(valueArg.version) ||
403
+ (valueArg.versionMode === "independent") !== (valueArg.version === null) ||
404
+ typeof valueArg.lockfile !== "boolean" ||
405
+ !Array.isArray(valueArg.members) ||
406
+ !isStringArray(valueArg.order)
407
+ ) {
408
+ throw new Error(`${context} is invalid.`);
409
+ }
410
+ const members = valueArg.members.map((member, index) =>
411
+ assertPlanMember(member, `${context} member ${index}`),
412
+ );
413
+ const names = members.map((member) => member.name);
414
+ if (new Set(names).size !== names.length) {
415
+ throw new Error(`${context} names a member more than once.`);
416
+ }
417
+ const selected = members
418
+ .filter((member) => member.selected)
419
+ .map((member) => member.name);
420
+ const order = valueArg.order;
421
+ if (
422
+ new Set(order).size !== order.length ||
423
+ order.length !== selected.length ||
424
+ order.some((name) => !selected.includes(name))
425
+ ) {
426
+ throw new Error(`${context} order must list every selected member once.`);
427
+ }
428
+ // Dependencies first: a selected member's normal and build dependencies on
429
+ // other selected members come earlier in the order.
430
+ for (const [index, name] of order.entries()) {
431
+ const member = members.find((entry) => entry.name === name)!;
432
+ for (const dependency of member.internalDependencies) {
433
+ if (dependency.kind === "dev") continue;
434
+ const dependencyIndex = order.indexOf(dependency.name);
435
+ if (dependencyIndex > index) {
436
+ throw new Error(
437
+ `${context} order publishes ${name} before its dependency ${dependency.name}.`,
438
+ );
439
+ }
440
+ }
441
+ }
442
+ return valueArg as unknown as IRsrepoPlanResult;
443
+ };
444
+
445
+ export const assertRsrepoSetVersionResult = (
446
+ valueArg: unknown,
447
+ versionArg: string,
448
+ ): IRsrepoSetVersionResult => {
449
+ const context = "rsrepo engine set-version";
450
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
451
+ assertKeys(valueArg, ["previousVersion", "version", "changedFiles"], [], context);
452
+ if (
453
+ !isNonEmptyString(valueArg.previousVersion) ||
454
+ valueArg.version !== versionArg ||
455
+ !isStringArray(valueArg.changedFiles) ||
456
+ valueArg.changedFiles.some(
457
+ (fileArg) =>
458
+ plugins.path.isAbsolute(fileArg) ||
459
+ fileArg.split(/[\\/]/).includes(".."),
460
+ )
461
+ ) {
462
+ throw new Error(`${context} is invalid.`);
463
+ }
464
+ return valueArg as unknown as IRsrepoSetVersionResult;
465
+ };
466
+
467
+ export const assertRsrepoPackageResult = (
468
+ valueArg: unknown,
469
+ requestArg: IRsrepoPackageRequest,
470
+ ): IRsrepoPackageResult => {
471
+ const context = "rsrepo engine package";
472
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
473
+ assertKeys(valueArg, ["crates"], [], context);
474
+ if (!Array.isArray(valueArg.crates)) throw new Error(`${context} is invalid.`);
475
+ const outDir = plugins.path.resolve(requestArg.outDir);
476
+ for (const [index, crate] of valueArg.crates.entries()) {
477
+ const crateContext = `${context} crate ${index}`;
478
+ if (!isPlainObject(crate)) throw new Error(`${crateContext} must be an object.`);
479
+ assertKeys(crate, ["name", "version", "file", "sha256", "files"], [], crateContext);
480
+ if (
481
+ !isCargoCrateName(crate.name) ||
482
+ !isNonEmptyString(crate.version) ||
483
+ !isNonEmptyString(crate.file) ||
484
+ !plugins.path.isAbsolute(crate.file) ||
485
+ plugins.path.dirname(plugins.path.resolve(crate.file)) !== outDir ||
486
+ !isString(crate.sha256) ||
487
+ !sha256Pattern.test(crate.sha256) ||
488
+ !isStringArray(crate.files)
489
+ ) {
490
+ throw new Error(`${crateContext} is invalid.`);
491
+ }
492
+ }
493
+ const names = valueArg.crates.map((crate) => (crate as IRsrepoPackedCrate).name);
494
+ if (
495
+ names.length !== requestArg.members.length ||
496
+ names.some((name, index) => name !== requestArg.members[index])
497
+ ) {
498
+ throw new Error(`${context} must answer every requested member in order.`);
499
+ }
500
+ return valueArg as unknown as IRsrepoPackageResult;
501
+ };
502
+
503
+ export const assertRsrepoPublishResult = (
504
+ valueArg: unknown,
505
+ requestArg: IRsrepoPublishRequest,
506
+ ): IRsrepoPublishResult => {
507
+ const context = "rsrepo engine publish";
508
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
509
+ assertKeys(valueArg, ["name", "version", "registry", "state"], [], context);
510
+ if (
511
+ valueArg.name !== requestArg.member ||
512
+ !isNonEmptyString(valueArg.version) ||
513
+ valueArg.registry !== requestArg.registry ||
514
+ valueArg.state !== "accepted"
515
+ ) {
516
+ throw new Error(`${context} does not answer the request.`);
517
+ }
518
+ return valueArg as unknown as IRsrepoPublishResult;
519
+ };
520
+
521
+ export const assertRsrepoProbeResult = (valueArg: unknown): IRsrepoProbeResult => {
522
+ const context = "rsrepo engine probe";
523
+ if (!isPlainObject(valueArg)) throw new Error(`${context} must be an object.`);
524
+ assertKeys(valueArg, ["present", "cksum", "yanked"], [], context);
525
+ if (
526
+ typeof valueArg.present !== "boolean" ||
527
+ !(valueArg.cksum === null || (isString(valueArg.cksum) && sha256Pattern.test(valueArg.cksum))) ||
528
+ !(valueArg.yanked === null || typeof valueArg.yanked === "boolean") ||
529
+ (valueArg.present && (valueArg.cksum === null || valueArg.yanked === null)) ||
530
+ (!valueArg.present && (valueArg.cksum !== null || valueArg.yanked !== null))
531
+ ) {
532
+ throw new Error(`${context} is invalid.`);
533
+ }
534
+ return valueArg as unknown as IRsrepoProbeResult;
535
+ };
536
+
537
+ /** The parsed answer of one engine invocation: its result, or its protocol error. */
538
+ export const parseRsrepoEngineOutput = (
539
+ commandArg: TRsrepoEngineCommand,
540
+ resultArg: plugins.smartshell.IExecResult,
541
+ ): unknown => {
542
+ const withFailure = (messageArg: string): string =>
543
+ formatCommandFailure(messageArg, resultArg, {
544
+ command: `rsrepo engine ${commandArg}`,
545
+ timeoutMs: commandTimeouts[commandArg],
546
+ });
547
+ const protocolFailure = (messageArg: string): RsrepoEngineCommandError =>
548
+ new RsrepoEngineCommandError(commandArg, "protocol-failure", withFailure(messageArg));
549
+ if (resultArg.timedOut) {
550
+ throw protocolFailure(`rsrepo engine ${commandArg} timed out with an unresolved outcome.`);
551
+ }
552
+ if (resultArg.signal) {
553
+ throw protocolFailure(`rsrepo engine ${commandArg} was terminated with an unresolved outcome.`);
554
+ }
555
+ if (resultArg.exitCode !== 0 && resultArg.exitCode !== 1) {
556
+ throw protocolFailure(`rsrepo engine ${commandArg} exited outside the protocol.`);
557
+ }
558
+ let parsed: unknown;
559
+ try {
560
+ parsed = JSON.parse(resultArg.stdout);
561
+ } catch {
562
+ throw protocolFailure(
563
+ `rsrepo engine ${commandArg} did not print exactly one JSON document on stdout.`,
564
+ );
565
+ }
566
+ if (
567
+ !isPlainObject(parsed) ||
568
+ parsed.protocol !== rsrepoEngineProtocol ||
569
+ typeof parsed.ok !== "boolean"
570
+ ) {
571
+ throw protocolFailure(`rsrepo engine ${commandArg} returned no protocol envelope.`);
572
+ }
573
+ if (parsed.protocolVersion !== rsrepoEngineProtocolVersion) {
574
+ throw new RsrepoEngineCommandError(
575
+ commandArg,
576
+ "protocol-failure",
577
+ `rsrepo engine ${commandArg} speaks protocol version ${String(parsed.protocolVersion)}; this gitzone speaks version ${rsrepoEngineProtocolVersion}. Install an @git.zone/rsrepo that speaks version ${rsrepoEngineProtocolVersion}.`,
578
+ );
579
+ }
580
+ try {
581
+ assertKeys(
582
+ parsed,
583
+ ["protocol", "protocolVersion", "ok", parsed.ok ? "result" : "error"],
584
+ [],
585
+ `rsrepo engine ${commandArg} envelope`,
586
+ );
587
+ } catch (error) {
588
+ throw protocolFailure(error instanceof Error ? error.message : String(error));
589
+ }
590
+ if (parsed.ok !== (resultArg.exitCode === 0)) {
591
+ throw protocolFailure(
592
+ `rsrepo engine ${commandArg} answered ok: ${String(parsed.ok)} with exit code ${resultArg.exitCode}.`,
593
+ );
594
+ }
595
+ if (parsed.ok) return parsed.result;
596
+ const error = parsed.error;
597
+ if (
598
+ !isPlainObject(error) ||
599
+ !rsrepoEngineErrorCodes.includes(error.code as TRsrepoEngineErrorCode) ||
600
+ !isNonEmptyString(error.message) ||
601
+ Object.keys(error).some((keyArg) => !["code", "message", "details"].includes(keyArg))
602
+ ) {
603
+ throw protocolFailure(`rsrepo engine ${commandArg} returned an invalid protocol error.`);
604
+ }
605
+ throw new RsrepoEngineCommandError(
606
+ commandArg,
607
+ error.code as TRsrepoEngineErrorCode,
608
+ `rsrepo engine ${commandArg} failed (${String(error.code)}): ${error.message}`,
609
+ );
610
+ };
611
+
612
+ const declaresRsrepo = (packageJsonArg: unknown): boolean => {
613
+ if (!isPlainObject(packageJsonArg)) return false;
614
+ return (["dependencies", "devDependencies"] as const).some((fieldArg) => {
615
+ const dependencies = packageJsonArg[fieldArg];
616
+ return (
617
+ isPlainObject(dependencies) &&
618
+ Object.hasOwn(dependencies, "@git.zone/rsrepo")
619
+ );
620
+ });
621
+ };
622
+
623
+ /**
624
+ * The engine a project uses: its own `node_modules/.bin/rsrepo` when its
625
+ * package.json declares `@git.zone/rsrepo`, otherwise `rsrepo` on PATH (a
626
+ * global install, like gitzone itself). A declared but missing install is an
627
+ * error, never a reason to run another rsrepo.
628
+ */
629
+ export const resolveRsrepoEngineBinary = async (
630
+ projectRootArg: string,
631
+ platformArg: NodeJS.Platform = process.platform,
632
+ ): Promise<string> => {
633
+ const projectRoot = plugins.path.resolve(projectRootArg);
634
+ const packageJsonPath = plugins.path.join(projectRoot, "package.json");
635
+ let packageJson: unknown;
636
+ try {
637
+ packageJson = JSON.parse(await plugins.fs.readFile(packageJsonPath, "utf8"));
638
+ } catch (error) {
639
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
640
+ throw new Error(`${packageJsonPath} could not be read.`, { cause: error });
641
+ }
642
+ }
643
+ if (declaresRsrepo(packageJson)) {
644
+ const binaryPath = plugins.path.join(
645
+ projectRoot,
646
+ "node_modules",
647
+ ".bin",
648
+ platformArg === "win32" ? "rsrepo.CMD" : "rsrepo",
649
+ );
650
+ try {
651
+ await plugins.fs.access(binaryPath);
652
+ } catch {
653
+ throw new Error(
654
+ `package.json declares @git.zone/rsrepo, but ${binaryPath} is missing. Run \`pnpm install\`.`,
655
+ );
656
+ }
657
+ return binaryPath;
658
+ }
659
+ const found = await plugins.smartshell.which("rsrepo", { nothrow: true });
660
+ if (!found) {
661
+ throw new Error(
662
+ "Cargo release steps need the rsrepo engine: install @git.zone/rsrepo globally (`pnpm add -g @git.zone/rsrepo`) or declare it in the project's package.json.",
663
+ );
664
+ }
665
+ return found;
666
+ };
667
+
668
+ export class RsrepoEngineClient implements IRsrepoEngineClient {
669
+ constructor(
670
+ private readonly smartshell: plugins.smartshell.Smartshell,
671
+ public readonly binaryPath: string,
672
+ private readonly cwd: string,
673
+ ) {}
674
+
675
+ /** The client of the project's resolved engine. */
676
+ public static async forProject(
677
+ smartshellArg: plugins.smartshell.Smartshell,
678
+ projectRootArg: string,
679
+ ): Promise<RsrepoEngineClient> {
680
+ return new RsrepoEngineClient(
681
+ smartshellArg,
682
+ await resolveRsrepoEngineBinary(projectRootArg),
683
+ plugins.path.resolve(projectRootArg),
684
+ );
685
+ }
686
+
687
+ public async capabilities(): Promise<IRsrepoCapabilitiesResult> {
688
+ return assertRsrepoCapabilitiesResult(await this.run("capabilities", {}));
689
+ }
690
+
691
+ public async assertCapabilities(
692
+ commandsArg: readonly TRsrepoEngineCommand[],
693
+ ): Promise<IRsrepoCapabilitiesResult> {
694
+ const capabilities = await this.capabilities();
695
+ const missing = commandsArg.filter(
696
+ (commandArg) => !capabilities.commands.includes(commandArg),
697
+ );
698
+ if (missing.length > 0) {
699
+ throw new Error(
700
+ `rsrepo ${capabilities.rsrepoVersion} (${this.binaryPath}) does not support the engine commands ${missing.join(", ")}.`,
701
+ );
702
+ }
703
+ return capabilities;
704
+ }
705
+
706
+ public async plan(requestArg: IRsrepoPlanRequest): Promise<IRsrepoPlanResult> {
707
+ return assertRsrepoPlanResult(await this.run("plan", requestArg));
708
+ }
709
+
710
+ public async setVersion(
711
+ requestArg: IRsrepoSetVersionRequest,
712
+ ): Promise<IRsrepoSetVersionResult> {
713
+ return assertRsrepoSetVersionResult(
714
+ await this.run("set-version", requestArg),
715
+ requestArg.version,
716
+ );
717
+ }
718
+
719
+ public async package(
720
+ requestArg: IRsrepoPackageRequest,
721
+ ): Promise<IRsrepoPackageResult> {
722
+ return assertRsrepoPackageResult(
723
+ await this.run("package", requestArg),
724
+ requestArg,
725
+ );
726
+ }
727
+
728
+ public async publish(
729
+ requestArg: IRsrepoPublishRequest,
730
+ ): Promise<IRsrepoPublishResult> {
731
+ return assertRsrepoPublishResult(
732
+ await this.run("publish", requestArg),
733
+ requestArg,
734
+ );
735
+ }
736
+
737
+ public async probe(requestArg: IRsrepoProbeRequest): Promise<IRsrepoProbeResult> {
738
+ return assertRsrepoProbeResult(await this.run("probe", requestArg));
739
+ }
740
+
741
+ /**
742
+ * Writes the request into a private directory of its own, runs the engine
743
+ * and removes the directory again, whatever the outcome.
744
+ */
745
+ private async run(
746
+ commandArg: TRsrepoEngineCommand,
747
+ requestArg: object,
748
+ ): Promise<unknown> {
749
+ // The engine resolves no relative request path (protocol v1, R2 gate).
750
+ for (const [key, value] of Object.entries(requestArg)) {
751
+ if (
752
+ (key === "cwd" || key === "outDir") &&
753
+ !(isNonEmptyString(value) && plugins.path.isAbsolute(value))
754
+ ) {
755
+ throw new Error(
756
+ `rsrepo engine ${commandArg} needs an absolute ${key}, not ${JSON.stringify(value)}.`,
757
+ );
758
+ }
759
+ }
760
+ const temporaryRoot = await plugins.fs.realpath(plugins.os.tmpdir());
761
+ const requestDirectory = await plugins.fs.mkdtemp(
762
+ plugins.path.join(temporaryRoot, `gitzone-rsrepo-${commandArg}-`),
763
+ );
764
+ try {
765
+ await plugins.fs.chmod(requestDirectory, 0o700);
766
+ const requestPath = plugins.path.join(requestDirectory, "request.json");
767
+ const handle = await plugins.fs.open(requestPath, "wx", 0o600);
768
+ try {
769
+ await handle.writeFile(`${JSON.stringify(requestArg)}\n`, "utf8");
770
+ await handle.sync();
771
+ } finally {
772
+ await handle.close();
773
+ }
774
+ const result = await this.smartshell.execSpawn(
775
+ this.binaryPath,
776
+ ["engine", commandArg, "--request", requestPath],
777
+ {
778
+ cwd: this.cwd,
779
+ maxBuffer: outputByteLimit,
780
+ silent: true,
781
+ timeout: commandTimeouts[commandArg],
782
+ timeoutKillGraceMs: 30_000,
783
+ },
784
+ );
785
+ return parseRsrepoEngineOutput(commandArg, result);
786
+ } finally {
787
+ await plugins.fs.rm(requestDirectory, { recursive: true, force: true });
788
+ }
789
+ }
790
+ }