@git.zone/cli 7.2.6 → 7.2.7

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.
@@ -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,
@@ -152,6 +155,9 @@ const runInternal = async (argvArg: any): Promise<void> => {
152
155
  pushTags: workflow.pushTags,
153
156
  mergeRequested,
154
157
  planMode: workflow.confirmation === "plan",
158
+ gitRemotePolicy: createReleaseGitRemotePolicy(
159
+ workflow.gitRemoteTimeoutSeconds,
160
+ ),
155
161
  });
156
162
  if (workflow.giteaAssets)
157
163
  assertGiteaAssetsGitDestination(
@@ -294,24 +300,6 @@ const runInternal = async (argvArg: any): Promise<void> => {
294
300
  releaseCommitOid,
295
301
  );
296
302
 
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
303
  const ensurePublicationState = async (
316
304
  expectedRemoteMainOidArg = expectedRemoteMainOid,
317
305
  ): Promise<void> => {
@@ -329,53 +317,36 @@ const runInternal = async (argvArg: any): Promise<void> => {
329
317
  );
330
318
  };
331
319
 
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,
320
+ const versionFloor = toReleaseVersionFloorRecord(versionResolution);
321
+ await recordReleaseIntent(smartshellInstance, {
348
322
  workflow,
349
323
  releaseCwd,
350
324
  releasePushUrl,
351
325
  expectedRemoteMainOid,
352
326
  version: newVersion,
353
- versionFloor: toReleaseVersionFloorRecord(versionResolution),
327
+ versionFloor,
354
328
  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 });
329
+ });
330
+ let journalContext: IPreparedTaggedRelease;
331
+ try {
332
+ journalContext = await prepareTaggedRelease({
333
+ pnpmCapability,
334
+ smartshell: smartshellInstance,
335
+ workflow,
336
+ releaseCwd,
337
+ releasePushUrl,
338
+ expectedRemoteMainOid,
339
+ version: newVersion,
340
+ versionFloor,
341
+ refs: releaseRefs,
342
+ ensurePublicationState,
343
+ });
344
+ } catch (error) {
345
+ throw new Error(
346
+ `${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.`,
347
+ { cause: error },
348
+ );
349
+ }
379
350
  const finalJournal = await executeReleasePublication({
380
351
  pnpmCapability,
381
352
  smartshell: smartshellInstance,
@@ -385,7 +356,8 @@ const runInternal = async (argvArg: any): Promise<void> => {
385
356
  pushUrl: releasePushUrl,
386
357
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
387
358
  giteaAssetTransfer: workflow.giteaAssetTransfer,
388
- tsdocker,
359
+ gitRemotePolicy: branchContext.gitRemotePolicy,
360
+ tsdocker: journalContext.tsdocker,
389
361
  ensurePublicationState,
390
362
  });
391
363
  await cleanTestArtifactsForCompletedRelease(
@@ -553,6 +525,234 @@ const createDockerQualificationRequest = (
553
525
  version: versionArg,
554
526
  });
555
527
 
528
+ interface IRecordReleaseIntentOptions {
529
+ workflow: IResolvedReleaseWorkflow;
530
+ releaseCwd: string;
531
+ releasePushUrl?: string;
532
+ expectedRemoteMainOid?: string;
533
+ version: string;
534
+ versionFloor?: IReleaseVersionFloorRecord;
535
+ refs: IReleaseRefs;
536
+ }
537
+
538
+ /** Records the tagged release before anything can fail on its way to a journal. */
539
+ const recordReleaseIntent = async (
540
+ smartshellArg: plugins.smartshell.Smartshell,
541
+ optionsArg: IRecordReleaseIntentOptions,
542
+ ): Promise<void> => {
543
+ const gitEnabled = optionsArg.workflow.targets.includes("git");
544
+ if (
545
+ gitEnabled &&
546
+ (!optionsArg.releasePushUrl || !optionsArg.expectedRemoteMainOid)
547
+ ) {
548
+ throw new Error("Git release destination state is incomplete.");
549
+ }
550
+ const store = new ReleaseJournalStore(
551
+ await resolveGitCommonDirectory(smartshellArg, optionsArg.releaseCwd),
552
+ );
553
+ await store.recordIntent({
554
+ kind: releaseIntentKind,
555
+ release: {
556
+ version: optionsArg.version,
557
+ tag: `v${optionsArg.version}`,
558
+ mainOid: optionsArg.refs.mainOid,
559
+ tagOid: optionsArg.refs.tagOid,
560
+ ...(optionsArg.versionFloor
561
+ ? { versionFloor: optionsArg.versionFloor }
562
+ : {}),
563
+ },
564
+ plan: {
565
+ targets: optionsArg.workflow.targets,
566
+ runBuild: optionsArg.workflow.runBuild,
567
+ },
568
+ git: gitEnabled
569
+ ? {
570
+ remote: optionsArg.workflow.gitRemote,
571
+ destinationHash: hashReleaseDestination(optionsArg.releasePushUrl!),
572
+ expectedRemoteMainOid: optionsArg.expectedRemoteMainOid!,
573
+ }
574
+ : null,
575
+ createdAt: new Date().toISOString(),
576
+ });
577
+ };
578
+
579
+ type TPrepareTaggedReleaseOptions = Omit<
580
+ ICreateReleaseJournalOptions,
581
+ | "npmSourceCwd"
582
+ | "npmPreparationDirectory"
583
+ | "dockerRequest"
584
+ | "tsdocker"
585
+ | "ensurePublicationState"
586
+ > & {
587
+ ensurePublicationState: () => Promise<void>;
588
+ };
589
+
590
+ interface IPreparedTaggedRelease {
591
+ store: ReleaseJournalStore;
592
+ journal: TReleaseJournal;
593
+ tsdocker?: ITsdockerReleaseClient;
594
+ }
595
+
596
+ /**
597
+ * Everything between the release tag and the installed journal: the Docker
598
+ * worktree build, the isolated build and pack, and the journal itself. A fresh
599
+ * release and the resume of its recorded intent run exactly this.
600
+ */
601
+ const prepareTaggedRelease = async (
602
+ optionsArg: TPrepareTaggedReleaseOptions,
603
+ ): Promise<IPreparedTaggedRelease> => {
604
+ const { workflow, smartshell, releaseCwd } = optionsArg;
605
+ // tSDocker keys qualification to the project directory, so an active Docker
606
+ // target additionally builds the release worktree that qualification reads.
607
+ if (workflow.runBuild && workflow.targets.includes("docker")) {
608
+ await runCommandStep(
609
+ smartshell,
610
+ releaseCwd,
611
+ "Running release build",
612
+ workflow.buildCommand,
613
+ );
614
+ await verifyCleanTree(
615
+ smartshell,
616
+ releaseCwd,
617
+ "Build produced uncommitted changes. Aborting release.",
618
+ );
619
+ }
620
+ await optionsArg.ensurePublicationState();
621
+ const tsdocker = workflow.targets.includes("docker")
622
+ ? new TsdockerReleaseClient(smartshell, releaseCwd)
623
+ : undefined;
624
+ await tsdocker?.assertCapabilities();
625
+ const journalOptions: ICreateReleaseJournalOptions = {
626
+ ...optionsArg,
627
+ dockerRequest: tsdocker
628
+ ? createDockerQualificationRequest(
629
+ workflow,
630
+ releaseCwd,
631
+ optionsArg.version,
632
+ optionsArg.refs.mainOid,
633
+ )
634
+ : undefined,
635
+ tsdocker,
636
+ };
637
+ // The release build belongs to the release commit and runs in its isolated
638
+ // checkout.
639
+ const prepared = releaseNeedsIsolatedCheckout(workflow)
640
+ ? await withIsolatedReleaseCheckout(
641
+ {
642
+ smartshell,
643
+ repositoryCwd: releaseCwd,
644
+ mainOid: optionsArg.refs.mainOid,
645
+ // Preflight already ran the configured tests on this exact source.
646
+ ...(workflow.runBuild ? { buildCommand: workflow.buildCommand } : {}),
647
+ },
648
+ async (checkout) =>
649
+ createReleaseJournal({
650
+ ...journalOptions,
651
+ npmSourceCwd: checkout.path,
652
+ npmPreparationDirectory: checkout.preparationPath,
653
+ ensurePublicationState: async () => {
654
+ await checkout.assertExact();
655
+ await optionsArg.ensurePublicationState();
656
+ },
657
+ }),
658
+ )
659
+ : await createReleaseJournal(journalOptions);
660
+ return { ...prepared, tsdocker };
661
+ };
662
+
663
+ /**
664
+ * A release whose journal was never installed resumes from its recorded
665
+ * intent. It re-resolves the release from the configuration its commit
666
+ * carries and the recorded command-line choices, proves the local refs and
667
+ * the Git destination unchanged, and then prepares the journal exactly as the
668
+ * release would have. Publication continues from that journal.
669
+ */
670
+ const prepareRecordedRelease = async (
671
+ smartshellArg: plugins.smartshell.Smartshell,
672
+ intentArg: IReleaseIntent,
673
+ ): Promise<void> => {
674
+ const { version } = intentArg.release;
675
+ const workflow = await resolveReleaseWorkflow({ yes: true }, intentArg.plan);
676
+ assertReleaseConfiguration(workflow, false);
677
+ const gitEnabled = workflow.targets.includes("git");
678
+ if (gitEnabled && intentArg.git?.remote !== workflow.gitRemote) {
679
+ throw new Error(
680
+ "Current Git release remote does not match the recorded release.",
681
+ );
682
+ }
683
+ const branch = await inspectReleaseBranch({
684
+ smartshell: smartshellArg,
685
+ cwd: paths.cwd,
686
+ gitRemote: workflow.gitRemote,
687
+ gitTargetActive: gitEnabled,
688
+ pushBranch: workflow.pushBranch,
689
+ pushTags: workflow.pushTags,
690
+ mergeRequested: false,
691
+ planMode: false,
692
+ gitRemotePolicy: createReleaseGitRemotePolicy(
693
+ workflow.gitRemoteTimeoutSeconds,
694
+ ),
695
+ });
696
+ if (branch.sourceOid !== intentArg.release.mainOid) {
697
+ throw new Error(
698
+ "Resume must run from the recorded release commit on main.",
699
+ );
700
+ }
701
+ const refs = await captureReleaseRefs(
702
+ smartshellArg,
703
+ paths.cwd,
704
+ version,
705
+ intentArg.release.mainOid,
706
+ );
707
+ if (refs.tagOid !== intentArg.release.tagOid) {
708
+ throw new Error(
709
+ "The local release tag no longer matches the recorded release.",
710
+ );
711
+ }
712
+ if (
713
+ intentArg.git &&
714
+ (!branch.pushUrl ||
715
+ hashReleaseDestination(branch.pushUrl) !== intentArg.git.destinationHash)
716
+ ) {
717
+ throw new Error(
718
+ "The Git push destination changed after the release was recorded.",
719
+ );
720
+ }
721
+ const expectedRemoteMainOid = intentArg.git?.expectedRemoteMainOid;
722
+ const pnpmCapability = await assertFreshReleaseCapabilities(
723
+ smartshellArg,
724
+ workflow,
725
+ paths.cwd,
726
+ branch.pushUrl,
727
+ workflow.targets.includes("docker")
728
+ ? new TsdockerReleaseClient(smartshellArg, paths.cwd)
729
+ : undefined,
730
+ );
731
+ console.log(
732
+ `\nPreparing the journal of recorded release v${version} from ${refs.mainOid}`,
733
+ );
734
+ await prepareTaggedRelease({
735
+ pnpmCapability,
736
+ smartshell: smartshellArg,
737
+ workflow,
738
+ releaseCwd: paths.cwd,
739
+ releasePushUrl: branch.pushUrl,
740
+ expectedRemoteMainOid,
741
+ version,
742
+ versionFloor: intentArg.release.versionFloor,
743
+ refs,
744
+ ensurePublicationState: async () => {
745
+ await verifyReleaseRefs(smartshellArg, paths.cwd, version, refs);
746
+ await revalidateReleasePublicationState(
747
+ smartshellArg,
748
+ branch,
749
+ refs.mainOid,
750
+ expectedRemoteMainOid,
751
+ );
752
+ },
753
+ });
754
+ };
755
+
556
756
  /**
557
757
  * tspublish materializes the already built modules outside every repository,
558
758
  * so each package is packed from its own generated manifest and nothing else.
@@ -889,14 +1089,7 @@ const runReleaseRecover = async (
889
1089
  const store = new ReleaseJournalStore(
890
1090
  await resolveGitCommonDirectory(shell, paths.cwd),
891
1091
  );
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) {
1092
+ if (await store.hasJournal(version)) {
900
1093
  if (argvArg.plan) {
901
1094
  printReleaseJournalSummary(await store.read(version));
902
1095
  return;
@@ -907,6 +1100,21 @@ const runReleaseRecover = async (
907
1100
  );
908
1101
  return;
909
1102
  }
1103
+ // A release that recorded its intent resumes from it; recovery is for tags
1104
+ // created without one.
1105
+ if (await store.readIntent(version)) {
1106
+ if (argvArg.plan) {
1107
+ console.log(
1108
+ `Release v${version} is recorded locally without a journal. \`gitzone release resume ${version} -y\` prepares and publishes it.`,
1109
+ );
1110
+ return;
1111
+ }
1112
+ await runReleaseResume(
1113
+ { _: ["release", "resume", version], yes: mode.yes },
1114
+ mode,
1115
+ );
1116
+ return;
1117
+ }
910
1118
  const workflow = await resolveReleaseWorkflow({ yes: true });
911
1119
  assertReleaseConfiguration(workflow, false);
912
1120
  let branch = await inspectReleaseBranch({
@@ -918,6 +1126,9 @@ const runReleaseRecover = async (
918
1126
  pushTags: workflow.pushTags,
919
1127
  mergeRequested: false,
920
1128
  planMode: argvArg.plan === true,
1129
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1130
+ workflow.gitRemoteTimeoutSeconds,
1131
+ ),
921
1132
  });
922
1133
  const refs = await captureReleaseRefs(
923
1134
  shell,
@@ -1030,6 +1241,7 @@ const runReleaseRecover = async (
1030
1241
  pushUrl: branch.pushUrl,
1031
1242
  npmVerificationWindowMs: workflow.npmVerificationWindowMinutes * 60_000,
1032
1243
  giteaAssetTransfer: workflow.giteaAssetTransfer,
1244
+ gitRemotePolicy: branch.gitRemotePolicy,
1033
1245
  tsdocker,
1034
1246
  ensurePublicationState: ensureState,
1035
1247
  });
@@ -1101,6 +1313,24 @@ const runReleaseResume = async (
1101
1313
  const store = new ReleaseJournalStore(
1102
1314
  await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
1103
1315
  );
1316
+ // A release that failed between its tag and its journal left only its
1317
+ // intent; preparing the journal from it is part of this resume.
1318
+ const preparesRecordedRelease = !(await store.hasJournal(version));
1319
+ if (preparesRecordedRelease) {
1320
+ const intent = await store.readIntent(version);
1321
+ if (!intent) {
1322
+ throw new Error(`Release journal v${version} does not exist.`);
1323
+ }
1324
+ if (
1325
+ !(await confirmReleaseResume(
1326
+ modeArg,
1327
+ `Prepare and publish recorded release v${version} now?`,
1328
+ ))
1329
+ ) {
1330
+ return;
1331
+ }
1332
+ await prepareRecordedRelease(smartshellInstance, intent);
1333
+ }
1104
1334
  const journal = await store.read(version);
1105
1335
  const gitEnabled = journal.git.state !== "skipped";
1106
1336
  const resumeConfiguration = await resolveReleaseResumeConfiguration({
@@ -1166,6 +1396,9 @@ const runReleaseResume = async (
1166
1396
  pushTags: true,
1167
1397
  mergeRequested: false,
1168
1398
  planMode: false,
1399
+ gitRemotePolicy: createReleaseGitRemotePolicy(
1400
+ resumeConfiguration.gitRemoteTimeoutSeconds,
1401
+ ),
1169
1402
  });
1170
1403
  const { refs, verificationOnly } = await resolveResumeReleaseRefs(
1171
1404
  smartshellInstance,
@@ -1182,19 +1415,11 @@ const runReleaseResume = async (
1182
1415
  throw new Error("The Git push destination changed after journal creation.");
1183
1416
  }
1184
1417
 
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
- }
1418
+ if (
1419
+ !preparesRecordedRelease &&
1420
+ !(await confirmReleaseResume(modeArg, `Resume release v${version} now?`))
1421
+ ) {
1422
+ return;
1198
1423
  }
1199
1424
 
1200
1425
  const ensurePublicationState = async (
@@ -1234,6 +1459,7 @@ const runReleaseResume = async (
1234
1459
  npmVerificationWindowMs:
1235
1460
  resumeConfiguration.npmVerificationWindowMinutes * 60_000,
1236
1461
  giteaAssetTransfer: resumeConfiguration.giteaAssetTransfer,
1462
+ gitRemotePolicy: branchContext.gitRemotePolicy,
1237
1463
  tsdocker,
1238
1464
  ensurePublicationState,
1239
1465
  });
@@ -1246,6 +1472,24 @@ const runReleaseResume = async (
1246
1472
  printReleaseJournalSummary(finalJournal);
1247
1473
  };
1248
1474
 
1475
+ /** True when the operator runs with -y or confirms interactively. */
1476
+ const confirmReleaseResume = async (
1477
+ modeArg: ICliMode,
1478
+ questionArg: string,
1479
+ ): Promise<boolean> => {
1480
+ if (modeArg.yes) return true;
1481
+ if (!modeArg.interactive) {
1482
+ throw new Error("Release resume requires an interactive terminal or -y.");
1483
+ }
1484
+ const confirmed =
1485
+ await plugins.smartinteract.SmartInteract.getCliConfirmation(
1486
+ questionArg,
1487
+ true,
1488
+ );
1489
+ if (!confirmed) logger.log("info", "Release resume cancelled.");
1490
+ return confirmed;
1491
+ };
1492
+
1249
1493
  const assertResumeConfiguration = async (
1250
1494
  workflowArg: IResolvedReleaseResumeConfiguration,
1251
1495
  journalArg: TReleaseJournal,
@@ -1875,12 +2119,12 @@ export function showHelp(mode?: ICliMode): void {
1875
2119
  {
1876
2120
  flag: "resume <version>",
1877
2121
  description:
1878
- "Resume exact journaled publication without rebuilding or repacking npm artifacts",
2122
+ "Resume exact journaled publication without rebuilding or repacking npm artifacts, or prepare the journal of a recorded release that failed before it",
1879
2123
  },
1880
2124
  {
1881
2125
  flag: "recover <version>",
1882
2126
  description:
1883
- "Recover a local npm and/or Docker release tag after build or pack failure before journal creation",
2127
+ "Recover a local npm and/or Docker release tag created without a recorded intent after build or pack failure before journal creation",
1884
2128
  },
1885
2129
  {
1886
2130
  flag: "--recover-attempt <id>",
@@ -1930,10 +2174,10 @@ export function showHelp(mode?: ICliMode): void {
1930
2174
  " inspect [version] Read one or all durable release journals without mutation",
1931
2175
  );
1932
2176
  console.log(
1933
- " resume <version> Resume exact journaled publication without rebuilding or repacking npm artifacts",
2177
+ " resume <version> Resume exact journaled publication, or prepare the journal of a recorded release that failed before it",
1934
2178
  );
1935
2179
  console.log(
1936
- " recover <version> Recover an unpublished npm and/or Docker release from its existing local tag",
2180
+ " recover <version> Recover an unpublished npm and/or Docker release tag created without a recorded intent",
1937
2181
  );
1938
2182
  console.log(
1939
2183
  " --recover-attempt Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",