@git.zone/cli 7.2.6 → 7.3.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 (43) hide show
  1. package/assets/templates/npm/.package.json +1 -1
  2. package/assets/templates/service/.package.json +1 -1
  3. package/assets/templates/wcc/.package.json +1 -1
  4. package/assets/templates/website/.package.json +1 -1
  5. package/dist_ts/00_commitinfo_data.js +1 -1
  6. package/dist_ts/helpers.climode.js +2 -1
  7. package/dist_ts/helpers.workflow.d.ts +19 -1
  8. package/dist_ts/helpers.workflow.js +31 -2
  9. package/dist_ts/mod_config/index.js +18 -2
  10. package/dist_ts/mod_release/classes.detachedrelease.d.ts +85 -0
  11. package/dist_ts/mod_release/classes.detachedrelease.js +506 -0
  12. package/dist_ts/mod_release/classes.releasejournal.d.ts +34 -0
  13. package/dist_ts/mod_release/classes.releasejournal.js +134 -2
  14. package/dist_ts/mod_release/helpers.giteaassets.d.ts +19 -0
  15. package/dist_ts/mod_release/helpers.giteaassets.js +53 -4
  16. package/dist_ts/mod_release/helpers.gitremote.d.ts +52 -0
  17. package/dist_ts/mod_release/helpers.gitremote.js +87 -0
  18. package/dist_ts/mod_release/helpers.releasebranch.d.ts +5 -0
  19. package/dist_ts/mod_release/helpers.releasebranch.js +39 -15
  20. package/dist_ts/mod_release/helpers.releasepreparation.js +18 -8
  21. package/dist_ts/mod_release/helpers.releasepublication.d.ts +3 -0
  22. package/dist_ts/mod_release/helpers.releasepublication.js +19 -15
  23. package/dist_ts/mod_release/index.js +303 -66
  24. package/dist_ts/mod_services/classes.interprocesslock.d.ts +12 -0
  25. package/dist_ts/mod_services/classes.interprocesslock.js +35 -12
  26. package/dist_ts/paths.d.ts +6 -0
  27. package/dist_ts/paths.js +7 -1
  28. package/package.json +4 -4
  29. package/readme.md +158 -21
  30. package/ts/00_commitinfo_data.ts +1 -1
  31. package/ts/helpers.climode.ts +1 -0
  32. package/ts/helpers.workflow.ts +50 -0
  33. package/ts/mod_config/index.ts +19 -0
  34. package/ts/mod_release/classes.detachedrelease.ts +655 -0
  35. package/ts/mod_release/classes.releasejournal.ts +181 -1
  36. package/ts/mod_release/helpers.giteaassets.ts +67 -5
  37. package/ts/mod_release/helpers.gitremote.ts +147 -0
  38. package/ts/mod_release/helpers.releasebranch.ts +75 -30
  39. package/ts/mod_release/helpers.releasepreparation.ts +25 -7
  40. package/ts/mod_release/helpers.releasepublication.ts +27 -36
  41. package/ts/mod_release/index.ts +443 -87
  42. package/ts/mod_services/classes.interprocesslock.ts +44 -15
  43. package/ts/paths.ts +10 -0
@@ -45,7 +45,10 @@ import {
45
45
  type TReleaseJournal,
46
46
  type IReleaseJournalV1,
47
47
  type IReleaseJournalV2,
48
+ releaseIntentKind,
49
+ type IReleaseIntent,
48
50
  } from "./classes.releasejournal.js";
51
+ import { createReleaseGitRemotePolicy } from "./helpers.gitremote.js";
49
52
  import {
50
53
  GiteaAssetsClient,
51
54
  prepareGiteaAssets,
@@ -91,10 +94,25 @@ import {
91
94
  type IReleaseVersionResolution,
92
95
  } from "./helpers.releaseversion.js";
93
96
 
97
+ import {
98
+ describeDetachedReleaseLaunch,
99
+ type DetachedReleaseRuns,
100
+ getDetachedWorkerArguments,
101
+ isDetachedReleaseSupervisor,
102
+ launchDetachedRelease,
103
+ openDetachedReleaseRuns,
104
+ superviseDetachedRelease,
105
+ type IDetachedReleaseRun,
106
+ } from "./classes.detachedrelease.js";
107
+
94
108
  export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
95
109
 
96
110
  export const run = async (argvArg: any): Promise<void> => {
97
111
  try {
112
+ if (isDetachedReleaseSupervisor()) {
113
+ await superviseDetachedRelease();
114
+ return;
115
+ }
98
116
  await runInternal(argvArg);
99
117
  } catch (error) {
100
118
  logger.log("error", error instanceof Error ? error.message : String(error));
@@ -136,6 +154,12 @@ const runInternal = async (argvArg: any): Promise<void> => {
136
154
  return;
137
155
  }
138
156
 
157
+ const detach = readDetachFlag(argvArg);
158
+ if (detach && argvArg.plan) {
159
+ throw new Error(
160
+ "--detach cannot be combined with --plan: a plan runs in the foreground.",
161
+ );
162
+ }
139
163
  const smartshellInstance = new plugins.smartshell.Smartshell({
140
164
  executor: "bash",
141
165
  sourceFilePaths: [],
@@ -143,6 +167,16 @@ const runInternal = async (argvArg: any): Promise<void> => {
143
167
  const mergeRequested = resolveReleaseMergeFlag(argvArg);
144
168
  const workflow = await resolveReleaseWorkflow(argvArg);
145
169
  assertReleaseConfiguration(workflow, mergeRequested);
170
+ if (detach && workflow.confirmation !== "auto") {
171
+ throw new Error(
172
+ '--detach requires -y or release.confirmation "auto": a detached release cannot ask for confirmation.',
173
+ );
174
+ }
175
+ const detachedRuns =
176
+ workflow.confirmation === "plan"
177
+ ? undefined
178
+ : await openDetachedReleaseRuns(paths.cwd);
179
+ await detachedRuns?.assertNoForeignRun();
146
180
  let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
147
181
  smartshell: smartshellInstance,
148
182
  cwd: paths.cwd,
@@ -151,7 +185,12 @@ const runInternal = async (argvArg: any): Promise<void> => {
151
185
  pushBranch: workflow.pushBranch,
152
186
  pushTags: workflow.pushTags,
153
187
  mergeRequested,
154
- planMode: workflow.confirmation === "plan",
188
+ // A detached launch checks in the foreground what the plan checks, and
189
+ // leaves every mutation to the release it starts.
190
+ planMode: workflow.confirmation === "plan" || detach,
191
+ gitRemotePolicy: createReleaseGitRemotePolicy(
192
+ workflow.gitRemoteTimeoutSeconds,
193
+ ),
155
194
  });
156
195
  if (workflow.giteaAssets)
157
196
  assertGiteaAssetsGitDestination(
@@ -175,6 +214,13 @@ const runInternal = async (argvArg: any): Promise<void> => {
175
214
  if (workflow.confirmation === "plan") {
176
215
  return;
177
216
  }
217
+ if (detachedRuns && detach) {
218
+ if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
219
+ throw new Error("No pending changelog entries. Nothing to release.");
220
+ }
221
+ await startDetachedRelease(detachedRuns, versionResolution.version);
222
+ return;
223
+ }
178
224
 
179
225
  const preflightTsdocker = workflow.targets.includes("docker")
180
226
  ? new TsdockerReleaseClient(smartshellInstance, branchContext.sourceCwd)
@@ -294,24 +340,6 @@ const runInternal = async (argvArg: any): Promise<void> => {
294
340
  releaseCommitOid,
295
341
  );
296
342
 
297
- // The release build belongs to the release commit and runs in its isolated
298
- // checkout. Docker qualification is bound to the project directory by the
299
- // tSDocker protocol, so an active Docker target additionally builds the
300
- // release worktree that qualification reads.
301
- if (workflow.runBuild && workflow.targets.includes("docker")) {
302
- await runCommandStep(
303
- smartshellInstance,
304
- releaseCwd,
305
- "Running release build",
306
- workflow.buildCommand,
307
- );
308
- await verifyCleanTree(
309
- smartshellInstance,
310
- releaseCwd,
311
- "Build produced uncommitted changes. Aborting release.",
312
- );
313
- }
314
-
315
343
  const ensurePublicationState = async (
316
344
  expectedRemoteMainOidArg = expectedRemoteMainOid,
317
345
  ): Promise<void> => {
@@ -329,53 +357,36 @@ const runInternal = async (argvArg: any): Promise<void> => {
329
357
  );
330
358
  };
331
359
 
332
- await ensurePublicationState();
333
- const tsdocker = workflow.targets.includes("docker")
334
- ? new TsdockerReleaseClient(smartshellInstance, releaseCwd)
335
- : undefined;
336
- await tsdocker?.assertCapabilities();
337
- const dockerRequest = tsdocker
338
- ? createDockerQualificationRequest(
339
- workflow,
340
- releaseCwd,
341
- newVersion,
342
- releaseRefs.mainOid,
343
- )
344
- : undefined;
345
- const journalOptions = {
346
- pnpmCapability,
347
- smartshell: smartshellInstance,
360
+ const versionFloor = toReleaseVersionFloorRecord(versionResolution);
361
+ await recordReleaseIntent(smartshellInstance, {
348
362
  workflow,
349
363
  releaseCwd,
350
364
  releasePushUrl,
351
365
  expectedRemoteMainOid,
352
366
  version: newVersion,
353
- versionFloor: toReleaseVersionFloorRecord(versionResolution),
367
+ versionFloor,
354
368
  refs: releaseRefs,
355
- dockerRequest,
356
- tsdocker,
357
- };
358
- const journalContext = releaseNeedsIsolatedCheckout(workflow)
359
- ? await withIsolatedReleaseCheckout(
360
- {
361
- smartshell: smartshellInstance,
362
- repositoryCwd: releaseCwd,
363
- mainOid: releaseRefs.mainOid,
364
- // Preflight already ran the configured tests on this exact source.
365
- ...(workflow.runBuild ? { buildCommand: workflow.buildCommand } : {}),
366
- },
367
- async (checkout) =>
368
- createReleaseJournal({
369
- ...journalOptions,
370
- npmSourceCwd: checkout.path,
371
- npmPreparationDirectory: checkout.preparationPath,
372
- ensurePublicationState: async () => {
373
- await checkout.assertExact();
374
- await ensurePublicationState();
375
- },
376
- }),
377
- )
378
- : await createReleaseJournal({ ...journalOptions, ensurePublicationState });
369
+ });
370
+ let journalContext: IPreparedTaggedRelease;
371
+ try {
372
+ journalContext = await prepareTaggedRelease({
373
+ pnpmCapability,
374
+ smartshell: smartshellInstance,
375
+ workflow,
376
+ releaseCwd,
377
+ releasePushUrl,
378
+ expectedRemoteMainOid,
379
+ version: newVersion,
380
+ versionFloor,
381
+ refs: releaseRefs,
382
+ ensurePublicationState,
383
+ });
384
+ } catch (error) {
385
+ throw new Error(
386
+ `${error instanceof Error ? error.message : String(error)} The release commit and tag v${newVersion} are recorded locally; \`gitzone release resume ${newVersion} -y\` prepares and publishes them.`,
387
+ { cause: error },
388
+ );
389
+ }
379
390
  const finalJournal = await executeReleasePublication({
380
391
  pnpmCapability,
381
392
  smartshell: smartshellInstance,
@@ -385,7 +396,8 @@ const runInternal = async (argvArg: any): Promise<void> => {
385
396
  pushUrl: releasePushUrl,
386
397
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
387
398
  giteaAssetTransfer: workflow.giteaAssetTransfer,
388
- tsdocker,
399
+ gitRemotePolicy: branchContext.gitRemotePolicy,
400
+ tsdocker: journalContext.tsdocker,
389
401
  ensurePublicationState,
390
402
  });
391
403
  await cleanTestArtifactsForCompletedRelease(
@@ -553,6 +565,234 @@ const createDockerQualificationRequest = (
553
565
  version: versionArg,
554
566
  });
555
567
 
568
+ interface IRecordReleaseIntentOptions {
569
+ workflow: IResolvedReleaseWorkflow;
570
+ releaseCwd: string;
571
+ releasePushUrl?: string;
572
+ expectedRemoteMainOid?: string;
573
+ version: string;
574
+ versionFloor?: IReleaseVersionFloorRecord;
575
+ refs: IReleaseRefs;
576
+ }
577
+
578
+ /** Records the tagged release before anything can fail on its way to a journal. */
579
+ const recordReleaseIntent = async (
580
+ smartshellArg: plugins.smartshell.Smartshell,
581
+ optionsArg: IRecordReleaseIntentOptions,
582
+ ): Promise<void> => {
583
+ const gitEnabled = optionsArg.workflow.targets.includes("git");
584
+ if (
585
+ gitEnabled &&
586
+ (!optionsArg.releasePushUrl || !optionsArg.expectedRemoteMainOid)
587
+ ) {
588
+ throw new Error("Git release destination state is incomplete.");
589
+ }
590
+ const store = new ReleaseJournalStore(
591
+ await resolveGitCommonDirectory(smartshellArg, optionsArg.releaseCwd),
592
+ );
593
+ await store.recordIntent({
594
+ kind: releaseIntentKind,
595
+ release: {
596
+ version: optionsArg.version,
597
+ tag: `v${optionsArg.version}`,
598
+ mainOid: optionsArg.refs.mainOid,
599
+ tagOid: optionsArg.refs.tagOid,
600
+ ...(optionsArg.versionFloor
601
+ ? { versionFloor: optionsArg.versionFloor }
602
+ : {}),
603
+ },
604
+ plan: {
605
+ targets: optionsArg.workflow.targets,
606
+ runBuild: optionsArg.workflow.runBuild,
607
+ },
608
+ git: gitEnabled
609
+ ? {
610
+ remote: optionsArg.workflow.gitRemote,
611
+ destinationHash: hashReleaseDestination(optionsArg.releasePushUrl!),
612
+ expectedRemoteMainOid: optionsArg.expectedRemoteMainOid!,
613
+ }
614
+ : null,
615
+ createdAt: new Date().toISOString(),
616
+ });
617
+ };
618
+
619
+ type TPrepareTaggedReleaseOptions = Omit<
620
+ ICreateReleaseJournalOptions,
621
+ | "npmSourceCwd"
622
+ | "npmPreparationDirectory"
623
+ | "dockerRequest"
624
+ | "tsdocker"
625
+ | "ensurePublicationState"
626
+ > & {
627
+ ensurePublicationState: () => Promise<void>;
628
+ };
629
+
630
+ interface IPreparedTaggedRelease {
631
+ store: ReleaseJournalStore;
632
+ journal: TReleaseJournal;
633
+ tsdocker?: ITsdockerReleaseClient;
634
+ }
635
+
636
+ /**
637
+ * Everything between the release tag and the installed journal: the Docker
638
+ * worktree build, the isolated build and pack, and the journal itself. A fresh
639
+ * release and the resume of its recorded intent run exactly this.
640
+ */
641
+ const prepareTaggedRelease = async (
642
+ optionsArg: TPrepareTaggedReleaseOptions,
643
+ ): Promise<IPreparedTaggedRelease> => {
644
+ const { workflow, smartshell, releaseCwd } = optionsArg;
645
+ // tSDocker keys qualification to the project directory, so an active Docker
646
+ // target additionally builds the release worktree that qualification reads.
647
+ if (workflow.runBuild && workflow.targets.includes("docker")) {
648
+ await runCommandStep(
649
+ smartshell,
650
+ releaseCwd,
651
+ "Running release build",
652
+ workflow.buildCommand,
653
+ );
654
+ await verifyCleanTree(
655
+ smartshell,
656
+ releaseCwd,
657
+ "Build produced uncommitted changes. Aborting release.",
658
+ );
659
+ }
660
+ await optionsArg.ensurePublicationState();
661
+ const tsdocker = workflow.targets.includes("docker")
662
+ ? new TsdockerReleaseClient(smartshell, releaseCwd)
663
+ : undefined;
664
+ await tsdocker?.assertCapabilities();
665
+ const journalOptions: ICreateReleaseJournalOptions = {
666
+ ...optionsArg,
667
+ dockerRequest: tsdocker
668
+ ? createDockerQualificationRequest(
669
+ workflow,
670
+ releaseCwd,
671
+ optionsArg.version,
672
+ optionsArg.refs.mainOid,
673
+ )
674
+ : undefined,
675
+ tsdocker,
676
+ };
677
+ // The release build belongs to the release commit and runs in its isolated
678
+ // checkout.
679
+ const prepared = releaseNeedsIsolatedCheckout(workflow)
680
+ ? await withIsolatedReleaseCheckout(
681
+ {
682
+ smartshell,
683
+ repositoryCwd: releaseCwd,
684
+ mainOid: optionsArg.refs.mainOid,
685
+ // Preflight already ran the configured tests on this exact source.
686
+ ...(workflow.runBuild ? { buildCommand: workflow.buildCommand } : {}),
687
+ },
688
+ async (checkout) =>
689
+ createReleaseJournal({
690
+ ...journalOptions,
691
+ npmSourceCwd: checkout.path,
692
+ npmPreparationDirectory: checkout.preparationPath,
693
+ ensurePublicationState: async () => {
694
+ await checkout.assertExact();
695
+ await optionsArg.ensurePublicationState();
696
+ },
697
+ }),
698
+ )
699
+ : await createReleaseJournal(journalOptions);
700
+ return { ...prepared, tsdocker };
701
+ };
702
+
703
+ /**
704
+ * A release whose journal was never installed resumes from its recorded
705
+ * intent. It re-resolves the release from the configuration its commit
706
+ * carries and the recorded command-line choices, proves the local refs and
707
+ * the Git destination unchanged, and then prepares the journal exactly as the
708
+ * release would have. Publication continues from that journal.
709
+ */
710
+ const prepareRecordedRelease = async (
711
+ smartshellArg: plugins.smartshell.Smartshell,
712
+ intentArg: IReleaseIntent,
713
+ ): Promise<void> => {
714
+ const { version } = intentArg.release;
715
+ const workflow = await resolveReleaseWorkflow({ yes: true }, intentArg.plan);
716
+ assertReleaseConfiguration(workflow, false);
717
+ const gitEnabled = workflow.targets.includes("git");
718
+ if (gitEnabled && intentArg.git?.remote !== workflow.gitRemote) {
719
+ throw new Error(
720
+ "Current Git release remote does not match the recorded release.",
721
+ );
722
+ }
723
+ const branch = await inspectReleaseBranch({
724
+ smartshell: smartshellArg,
725
+ cwd: paths.cwd,
726
+ gitRemote: workflow.gitRemote,
727
+ gitTargetActive: gitEnabled,
728
+ pushBranch: workflow.pushBranch,
729
+ pushTags: workflow.pushTags,
730
+ mergeRequested: false,
731
+ planMode: false,
732
+ gitRemotePolicy: createReleaseGitRemotePolicy(
733
+ workflow.gitRemoteTimeoutSeconds,
734
+ ),
735
+ });
736
+ if (branch.sourceOid !== intentArg.release.mainOid) {
737
+ throw new Error(
738
+ "Resume must run from the recorded release commit on main.",
739
+ );
740
+ }
741
+ const refs = await captureReleaseRefs(
742
+ smartshellArg,
743
+ paths.cwd,
744
+ version,
745
+ intentArg.release.mainOid,
746
+ );
747
+ if (refs.tagOid !== intentArg.release.tagOid) {
748
+ throw new Error(
749
+ "The local release tag no longer matches the recorded release.",
750
+ );
751
+ }
752
+ if (
753
+ intentArg.git &&
754
+ (!branch.pushUrl ||
755
+ hashReleaseDestination(branch.pushUrl) !== intentArg.git.destinationHash)
756
+ ) {
757
+ throw new Error(
758
+ "The Git push destination changed after the release was recorded.",
759
+ );
760
+ }
761
+ const expectedRemoteMainOid = intentArg.git?.expectedRemoteMainOid;
762
+ const pnpmCapability = await assertFreshReleaseCapabilities(
763
+ smartshellArg,
764
+ workflow,
765
+ paths.cwd,
766
+ branch.pushUrl,
767
+ workflow.targets.includes("docker")
768
+ ? new TsdockerReleaseClient(smartshellArg, paths.cwd)
769
+ : undefined,
770
+ );
771
+ console.log(
772
+ `\nPreparing the journal of recorded release v${version} from ${refs.mainOid}`,
773
+ );
774
+ await prepareTaggedRelease({
775
+ pnpmCapability,
776
+ smartshell: smartshellArg,
777
+ workflow,
778
+ releaseCwd: paths.cwd,
779
+ releasePushUrl: branch.pushUrl,
780
+ expectedRemoteMainOid,
781
+ version,
782
+ versionFloor: intentArg.release.versionFloor,
783
+ refs,
784
+ ensurePublicationState: async () => {
785
+ await verifyReleaseRefs(smartshellArg, paths.cwd, version, refs);
786
+ await revalidateReleasePublicationState(
787
+ smartshellArg,
788
+ branch,
789
+ refs.mainOid,
790
+ expectedRemoteMainOid,
791
+ );
792
+ },
793
+ });
794
+ };
795
+
556
796
  /**
557
797
  * tspublish materializes the already built modules outside every repository,
558
798
  * so each package is packed from its own generated manifest and nothing else.
@@ -822,6 +1062,31 @@ export const createReleaseJournal = async (
822
1062
  }
823
1063
  };
824
1064
 
1065
+ /** `--detach` is a bare flag; `--no-detach` runs in the foreground. */
1066
+ const readDetachFlag = (argvArg: any): boolean => {
1067
+ const value = argvArg.detach;
1068
+ if (value === undefined || value === false) return false;
1069
+ if (value === true) return true;
1070
+ throw new Error("--detach takes no value.");
1071
+ };
1072
+
1073
+ /**
1074
+ * Starts the release this command describes, without `--detach`, in a
1075
+ * session of its own and reports where it runs.
1076
+ */
1077
+ const startDetachedRelease = async (
1078
+ runsArg: DetachedReleaseRuns,
1079
+ versionArg: string,
1080
+ ): Promise<void> => {
1081
+ const run = await launchDetachedRelease({
1082
+ runs: runsArg,
1083
+ cwd: paths.cwd,
1084
+ workerArguments: getDetachedWorkerArguments(process.argv.slice(2)),
1085
+ version: versionArg,
1086
+ });
1087
+ console.log(describeDetachedReleaseLaunch(run));
1088
+ };
1089
+
825
1090
  const runReleaseInspect = async (
826
1091
  argvArg: any,
827
1092
  modeArg: ICliMode,
@@ -840,10 +1105,20 @@ const runReleaseInspect = async (
840
1105
  const journals = requestedVersion
841
1106
  ? [await store.read(normalizeReleaseVersion(requestedVersion))]
842
1107
  : await store.list();
1108
+ // Detached runs are listed with all journals; a run that failed before its
1109
+ // tag has no journal to be found by version.
1110
+ const runs = requestedVersion
1111
+ ? undefined
1112
+ : await (await openDetachedReleaseRuns(paths.cwd)).list();
843
1113
  if (modeArg.json) {
844
- printJson({ ok: true, journals });
1114
+ printJson({ ok: true, journals, ...(runs ? { runs } : {}) });
845
1115
  return;
846
1116
  }
1117
+ if (runs?.length) {
1118
+ console.log("");
1119
+ console.log("Detached release runs");
1120
+ for (const run of runs) console.log(describeDetachedReleaseRun(run));
1121
+ }
847
1122
  if (journals.length === 0) {
848
1123
  console.log("No release journals found.");
849
1124
  return;
@@ -853,6 +1128,15 @@ const runReleaseInspect = async (
853
1128
  }
854
1129
  };
855
1130
 
1131
+ const describeDetachedReleaseRun = (runArg: IDetachedReleaseRun): string => {
1132
+ const release = `gitzone ${runArg.command.join(" ")} (v${runArg.version})`;
1133
+ const outcome =
1134
+ runArg.state === "running"
1135
+ ? `running since ${runArg.startedAt} in process group ${runArg.supervisorPid}`
1136
+ : `${runArg.state} (${runArg.exitCode !== null ? `exit code ${runArg.exitCode}` : `signal ${runArg.signal}`}) at ${runArg.finishedAt}`;
1137
+ return `run ${runArg.id}: ${outcome}; ${release}; log ${runArg.logPath}`;
1138
+ };
1139
+
856
1140
  const runReleaseRecover = async (
857
1141
  argvArg: any,
858
1142
  mode: ICliMode,
@@ -882,6 +1166,9 @@ const runReleaseRecover = async (
882
1166
  );
883
1167
  }
884
1168
  const version = normalizeReleaseVersion(argvArg._[2]);
1169
+ if (!argvArg.plan) {
1170
+ await (await openDetachedReleaseRuns(paths.cwd)).assertNoForeignRun();
1171
+ }
885
1172
  const shell = new plugins.smartshell.Smartshell({
886
1173
  executor: "bash",
887
1174
  sourceFilePaths: [],
@@ -889,14 +1176,7 @@ const runReleaseRecover = async (
889
1176
  const store = new ReleaseJournalStore(
890
1177
  await resolveGitCommonDirectory(shell, paths.cwd),
891
1178
  );
892
- const existing = await plugins.fs
893
- .lstat(store.getReleaseDirectory(version))
894
- .then(() => true)
895
- .catch((error: NodeJS.ErrnoException) => {
896
- if (error.code === "ENOENT") return false;
897
- throw error;
898
- });
899
- if (existing) {
1179
+ if (await store.hasJournal(version)) {
900
1180
  if (argvArg.plan) {
901
1181
  printReleaseJournalSummary(await store.read(version));
902
1182
  return;
@@ -907,6 +1187,21 @@ const runReleaseRecover = async (
907
1187
  );
908
1188
  return;
909
1189
  }
1190
+ // A release that recorded its intent resumes from it; recovery is for tags
1191
+ // created without one.
1192
+ if (await store.readIntent(version)) {
1193
+ if (argvArg.plan) {
1194
+ console.log(
1195
+ `Release v${version} is recorded locally without a journal. \`gitzone release resume ${version} -y\` prepares and publishes it.`,
1196
+ );
1197
+ return;
1198
+ }
1199
+ await runReleaseResume(
1200
+ { _: ["release", "resume", version], yes: mode.yes },
1201
+ mode,
1202
+ );
1203
+ return;
1204
+ }
910
1205
  const workflow = await resolveReleaseWorkflow({ yes: true });
911
1206
  assertReleaseConfiguration(workflow, false);
912
1207
  let branch = await inspectReleaseBranch({
@@ -918,6 +1213,9 @@ const runReleaseRecover = async (
918
1213
  pushTags: workflow.pushTags,
919
1214
  mergeRequested: false,
920
1215
  planMode: argvArg.plan === true,
1216
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1217
+ workflow.gitRemoteTimeoutSeconds,
1218
+ ),
921
1219
  });
922
1220
  const refs = await captureReleaseRefs(
923
1221
  shell,
@@ -1030,6 +1328,7 @@ const runReleaseRecover = async (
1030
1328
  pushUrl: branch.pushUrl,
1031
1329
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
1032
1330
  giteaAssetTransfer: workflow.giteaAssetTransfer,
1331
+ gitRemotePolicy: branch.gitRemotePolicy,
1033
1332
  tsdocker,
1034
1333
  ensurePublicationState: ensureState,
1035
1334
  });
@@ -1094,6 +1393,12 @@ const runReleaseResume = async (
1094
1393
  );
1095
1394
  }
1096
1395
  const version = normalizeReleaseVersion(argvArg._[2]);
1396
+ const detach = readDetachFlag(argvArg);
1397
+ if (detach && !modeArg.yes) {
1398
+ throw new Error(
1399
+ "--detach requires -y: a detached resume cannot ask for confirmation.",
1400
+ );
1401
+ }
1097
1402
  const smartshellInstance = new plugins.smartshell.Smartshell({
1098
1403
  executor: "bash",
1099
1404
  sourceFilePaths: [],
@@ -1101,6 +1406,35 @@ const runReleaseResume = async (
1101
1406
  const store = new ReleaseJournalStore(
1102
1407
  await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
1103
1408
  );
1409
+ const detachedRuns = await openDetachedReleaseRuns(paths.cwd);
1410
+ await detachedRuns.assertNoForeignRun();
1411
+ if (detach) {
1412
+ if (await store.hasJournal(version)) {
1413
+ await store.read(version);
1414
+ } else if (!(await store.readIntent(version))) {
1415
+ throw new Error(`Release journal v${version} does not exist.`);
1416
+ }
1417
+ await startDetachedRelease(detachedRuns, version);
1418
+ return;
1419
+ }
1420
+ // A release that failed between its tag and its journal left only its
1421
+ // intent; preparing the journal from it is part of this resume.
1422
+ const preparesRecordedRelease = !(await store.hasJournal(version));
1423
+ if (preparesRecordedRelease) {
1424
+ const intent = await store.readIntent(version);
1425
+ if (!intent) {
1426
+ throw new Error(`Release journal v${version} does not exist.`);
1427
+ }
1428
+ if (
1429
+ !(await confirmReleaseResume(
1430
+ modeArg,
1431
+ `Prepare and publish recorded release v${version} now?`,
1432
+ ))
1433
+ ) {
1434
+ return;
1435
+ }
1436
+ await prepareRecordedRelease(smartshellInstance, intent);
1437
+ }
1104
1438
  const journal = await store.read(version);
1105
1439
  const gitEnabled = journal.git.state !== "skipped";
1106
1440
  const resumeConfiguration = await resolveReleaseResumeConfiguration({
@@ -1166,6 +1500,9 @@ const runReleaseResume = async (
1166
1500
  pushTags: true,
1167
1501
  mergeRequested: false,
1168
1502
  planMode: false,
1503
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1504
+ resumeConfiguration.gitRemoteTimeoutSeconds,
1505
+ ),
1169
1506
  });
1170
1507
  const { refs, verificationOnly } = await resolveResumeReleaseRefs(
1171
1508
  smartshellInstance,
@@ -1182,19 +1519,11 @@ const runReleaseResume = async (
1182
1519
  throw new Error("The Git push destination changed after journal creation.");
1183
1520
  }
1184
1521
 
1185
- if (!modeArg.yes) {
1186
- if (!modeArg.interactive) {
1187
- throw new Error("Release resume requires an interactive terminal or -y.");
1188
- }
1189
- const confirmed =
1190
- await plugins.smartinteract.SmartInteract.getCliConfirmation(
1191
- `Resume release v${version} now?`,
1192
- true,
1193
- );
1194
- if (!confirmed) {
1195
- logger.log("info", "Release resume cancelled.");
1196
- return;
1197
- }
1522
+ if (
1523
+ !preparesRecordedRelease &&
1524
+ !(await confirmReleaseResume(modeArg, `Resume release v${version} now?`))
1525
+ ) {
1526
+ return;
1198
1527
  }
1199
1528
 
1200
1529
  const ensurePublicationState = async (
@@ -1234,6 +1563,7 @@ const runReleaseResume = async (
1234
1563
  npmVerificationWindowMs:
1235
1564
  resumeConfiguration.npmVerificationWindowMinutes * 60_000,
1236
1565
  giteaAssetTransfer: resumeConfiguration.giteaAssetTransfer,
1566
+ gitRemotePolicy: branchContext.gitRemotePolicy,
1237
1567
  tsdocker,
1238
1568
  ensurePublicationState,
1239
1569
  });
@@ -1246,6 +1576,24 @@ const runReleaseResume = async (
1246
1576
  printReleaseJournalSummary(finalJournal);
1247
1577
  };
1248
1578
 
1579
+ /** True when the operator runs with -y or confirms interactively. */
1580
+ const confirmReleaseResume = async (
1581
+ modeArg: ICliMode,
1582
+ questionArg: string,
1583
+ ): Promise<boolean> => {
1584
+ if (modeArg.yes) return true;
1585
+ if (!modeArg.interactive) {
1586
+ throw new Error("Release resume requires an interactive terminal or -y.");
1587
+ }
1588
+ const confirmed =
1589
+ await plugins.smartinteract.SmartInteract.getCliConfirmation(
1590
+ questionArg,
1591
+ true,
1592
+ );
1593
+ if (!confirmed) logger.log("info", "Release resume cancelled.");
1594
+ return confirmed;
1595
+ };
1596
+
1249
1597
  const assertResumeConfiguration = async (
1250
1598
  workflowArg: IResolvedReleaseResumeConfiguration,
1251
1599
  journalArg: TReleaseJournal,
@@ -1875,18 +2223,23 @@ export function showHelp(mode?: ICliMode): void {
1875
2223
  {
1876
2224
  flag: "resume <version>",
1877
2225
  description:
1878
- "Resume exact journaled publication without rebuilding or repacking npm artifacts",
2226
+ "Resume exact journaled publication without rebuilding or repacking npm artifacts, or prepare the journal of a recorded release that failed before it",
1879
2227
  },
1880
2228
  {
1881
2229
  flag: "recover <version>",
1882
2230
  description:
1883
- "Recover a local npm and/or Docker release tag after build or pack failure before journal creation",
2231
+ "Recover a local npm and/or Docker release tag created without a recorded intent after build or pack failure before journal creation",
1884
2232
  },
1885
2233
  {
1886
2234
  flag: "--recover-attempt <id>",
1887
2235
  description:
1888
2236
  "Recover one exact 32-character hexadecimal attempt ID after proving it stopped",
1889
2237
  },
2238
+ {
2239
+ flag: "--detach",
2240
+ description:
2241
+ "With -y, run a release or resume in its own session after the foreground checks; its log and outcome are recorded beside the release journals",
2242
+ },
1890
2243
  ],
1891
2244
  });
1892
2245
  return;
@@ -1930,13 +2283,16 @@ export function showHelp(mode?: ICliMode): void {
1930
2283
  " inspect [version] Read one or all durable release journals without mutation",
1931
2284
  );
1932
2285
  console.log(
1933
- " resume <version> Resume exact journaled publication without rebuilding or repacking npm artifacts",
2286
+ " resume <version> Resume exact journaled publication, or prepare the journal of a recorded release that failed before it",
1934
2287
  );
1935
2288
  console.log(
1936
- " recover <version> Recover an unpublished npm and/or Docker release from its existing local tag",
2289
+ " recover <version> Recover an unpublished npm and/or Docker release tag created without a recorded intent",
1937
2290
  );
1938
2291
  console.log(
1939
2292
  " --recover-attempt Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
1940
2293
  );
2294
+ console.log(
2295
+ " --detach With -y, run a release or resume in its own session; see `gitzone release inspect`",
2296
+ );
1941
2297
  console.log("");
1942
2298
  }