@git.zone/cli 7.2.7 → 7.4.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 (32) 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/mod_release/classes.detachedrelease.d.ts +85 -0
  8. package/dist_ts/mod_release/classes.detachedrelease.js +506 -0
  9. package/dist_ts/mod_release/classes.releasejournal.d.ts +8 -2
  10. package/dist_ts/mod_release/classes.releasejournal.js +2 -2
  11. package/dist_ts/mod_release/helpers.npmartifact.d.ts +57 -4
  12. package/dist_ts/mod_release/helpers.npmartifact.js +228 -9
  13. package/dist_ts/mod_release/helpers.releasepreparation.d.ts +7 -2
  14. package/dist_ts/mod_release/helpers.releasepreparation.js +20 -6
  15. package/dist_ts/mod_release/helpers.releasepublication.js +38 -8
  16. package/dist_ts/mod_release/index.js +118 -13
  17. package/dist_ts/mod_services/classes.interprocesslock.d.ts +12 -0
  18. package/dist_ts/mod_services/classes.interprocesslock.js +35 -12
  19. package/dist_ts/paths.d.ts +6 -0
  20. package/dist_ts/paths.js +7 -1
  21. package/package.json +4 -4
  22. package/readme.md +126 -5
  23. package/ts/00_commitinfo_data.ts +1 -1
  24. package/ts/helpers.climode.ts +1 -0
  25. package/ts/mod_release/classes.detachedrelease.ts +655 -0
  26. package/ts/mod_release/classes.releasejournal.ts +10 -3
  27. package/ts/mod_release/helpers.npmartifact.ts +379 -16
  28. package/ts/mod_release/helpers.releasepreparation.ts +25 -3
  29. package/ts/mod_release/helpers.releasepublication.ts +60 -0
  30. package/ts/mod_release/index.ts +168 -10
  31. package/ts/mod_services/classes.interprocesslock.ts +44 -15
  32. package/ts/paths.ts +10 -0
@@ -43,6 +43,7 @@ import {
43
43
  type IReleasePackage,
44
44
  type IReleaseArtifact,
45
45
  type TReleaseJournal,
46
+ type TReleaseNpmAccess,
46
47
  type IReleaseJournalV1,
47
48
  type IReleaseJournalV2,
48
49
  releaseIntentKind,
@@ -56,6 +57,7 @@ import {
56
57
  import {
57
58
  assertNoLegacyNpmPublisher,
58
59
  assertNoStandaloneTspublishPublisher,
60
+ assertNpmRegistryAuthentication,
59
61
  assertPnpmReleaseCapability,
60
62
  hashReleaseDestination,
61
63
  normalizeNpmRegistryUrl,
@@ -94,10 +96,25 @@ import {
94
96
  type IReleaseVersionResolution,
95
97
  } from "./helpers.releaseversion.js";
96
98
 
99
+ import {
100
+ describeDetachedReleaseLaunch,
101
+ type DetachedReleaseRuns,
102
+ getDetachedWorkerArguments,
103
+ isDetachedReleaseSupervisor,
104
+ launchDetachedRelease,
105
+ openDetachedReleaseRuns,
106
+ superviseDetachedRelease,
107
+ type IDetachedReleaseRun,
108
+ } from "./classes.detachedrelease.js";
109
+
97
110
  export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
98
111
 
99
112
  export const run = async (argvArg: any): Promise<void> => {
100
113
  try {
114
+ if (isDetachedReleaseSupervisor()) {
115
+ await superviseDetachedRelease();
116
+ return;
117
+ }
101
118
  await runInternal(argvArg);
102
119
  } catch (error) {
103
120
  logger.log("error", error instanceof Error ? error.message : String(error));
@@ -139,6 +156,12 @@ const runInternal = async (argvArg: any): Promise<void> => {
139
156
  return;
140
157
  }
141
158
 
159
+ const detach = readDetachFlag(argvArg);
160
+ if (detach && argvArg.plan) {
161
+ throw new Error(
162
+ "--detach cannot be combined with --plan: a plan runs in the foreground.",
163
+ );
164
+ }
142
165
  const smartshellInstance = new plugins.smartshell.Smartshell({
143
166
  executor: "bash",
144
167
  sourceFilePaths: [],
@@ -146,6 +169,16 @@ const runInternal = async (argvArg: any): Promise<void> => {
146
169
  const mergeRequested = resolveReleaseMergeFlag(argvArg);
147
170
  const workflow = await resolveReleaseWorkflow(argvArg);
148
171
  assertReleaseConfiguration(workflow, mergeRequested);
172
+ if (detach && workflow.confirmation !== "auto") {
173
+ throw new Error(
174
+ '--detach requires -y or release.confirmation "auto": a detached release cannot ask for confirmation.',
175
+ );
176
+ }
177
+ const detachedRuns =
178
+ workflow.confirmation === "plan"
179
+ ? undefined
180
+ : await openDetachedReleaseRuns(paths.cwd);
181
+ await detachedRuns?.assertNoForeignRun();
149
182
  let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
150
183
  smartshell: smartshellInstance,
151
184
  cwd: paths.cwd,
@@ -154,7 +187,9 @@ const runInternal = async (argvArg: any): Promise<void> => {
154
187
  pushBranch: workflow.pushBranch,
155
188
  pushTags: workflow.pushTags,
156
189
  mergeRequested,
157
- planMode: workflow.confirmation === "plan",
190
+ // A detached launch checks in the foreground what the plan checks, and
191
+ // leaves every mutation to the release it starts.
192
+ planMode: workflow.confirmation === "plan" || detach,
158
193
  gitRemotePolicy: createReleaseGitRemotePolicy(
159
194
  workflow.gitRemoteTimeoutSeconds,
160
195
  ),
@@ -181,6 +216,13 @@ const runInternal = async (argvArg: any): Promise<void> => {
181
216
  if (workflow.confirmation === "plan") {
182
217
  return;
183
218
  }
219
+ if (detachedRuns && detach) {
220
+ if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
221
+ throw new Error("No pending changelog entries. Nothing to release.");
222
+ }
223
+ await startDetachedRelease(detachedRuns, versionResolution.version);
224
+ return;
225
+ }
184
226
 
185
227
  const preflightTsdocker = workflow.targets.includes("docker")
186
228
  ? new TsdockerReleaseClient(smartshellInstance, branchContext.sourceCwd)
@@ -391,6 +433,7 @@ const assertFreshReleaseCapabilities = async (
391
433
  cwdArg: string,
392
434
  pushUrlArg?: string,
393
435
  tsdockerArg?: ITsdockerReleaseClient,
436
+ authenticationNextStepArg = "release again",
394
437
  ): Promise<IPnpmReleaseCapability | undefined> => {
395
438
  if (workflowArg.targets.includes("docker")) {
396
439
  if (!tsdockerArg) {
@@ -411,7 +454,39 @@ const assertFreshReleaseCapabilities = async (
411
454
  }
412
455
  if (workflowArg.targets.includes("npm")) {
413
456
  await assertNoStandaloneTspublishPublisher(cwdArg);
414
- return assertPnpmReleaseCapability(smartshellArg, cwdArg);
457
+ const capability = await assertPnpmReleaseCapability(smartshellArg, cwdArg);
458
+ await assertPrivateNpmAuthentication(
459
+ smartshellArg,
460
+ cwdArg,
461
+ capability,
462
+ workflowArg.npmAccessLevel,
463
+ workflowArg.npmRegistries,
464
+ authenticationNextStepArg,
465
+ );
466
+ return capability;
467
+ }
468
+ };
469
+
470
+ /**
471
+ * A private package is verified with the registry's configured
472
+ * authentication, so every destination must confirm that authentication
473
+ * before anything is committed, tagged or published.
474
+ */
475
+ const assertPrivateNpmAuthentication = async (
476
+ smartshellArg: plugins.smartshell.Smartshell,
477
+ cwdArg: string,
478
+ capabilityArg: IPnpmReleaseCapability,
479
+ accessArg: TReleaseNpmAccess,
480
+ registriesArg: readonly string[],
481
+ nextStepArg: string,
482
+ ): Promise<void> => {
483
+ if (accessArg !== "private") return;
484
+ for (const registry of registriesArg) {
485
+ await assertNpmRegistryAuthentication(
486
+ { smartshell: smartshellArg, cwd: cwdArg, capability: capabilityArg },
487
+ registry,
488
+ nextStepArg,
489
+ );
415
490
  }
416
491
  };
417
492
 
@@ -452,11 +527,6 @@ const assertReleaseConfiguration = (
452
527
  if (workflowArg.npmRegistries.length === 0) {
453
528
  throw new Error("The npm release target requires at least one registry.");
454
529
  }
455
- if (workflowArg.npmAccessLevel !== "public") {
456
- throw new Error(
457
- "Journaled npm publication currently requires public access so every destination can be verified anonymously.",
458
- );
459
- }
460
530
  if (
461
531
  workflowArg.npmAlreadyPublished !== "success" &&
462
532
  workflowArg.npmAlreadyPublished !== "error"
@@ -727,6 +797,7 @@ const prepareRecordedRelease = async (
727
797
  workflow.targets.includes("docker")
728
798
  ? new TsdockerReleaseClient(smartshellArg, paths.cwd)
729
799
  : undefined,
800
+ `run \`gitzone release resume ${version} -y\``,
730
801
  );
731
802
  console.log(
732
803
  `\nPreparing the journal of recorded release v${version} from ${refs.mainOid}`,
@@ -957,7 +1028,9 @@ export const createReleaseJournal = async (
957
1028
  : null,
958
1029
  },
959
1030
  npm: {
960
- access: "public",
1031
+ access: optionsArg.workflow.targets.includes("npm")
1032
+ ? optionsArg.workflow.npmAccessLevel
1033
+ : "public",
961
1034
  tag: "latest",
962
1035
  alreadyPublished: optionsArg.workflow.targets.includes("npm")
963
1036
  ? optionsArg.workflow.npmAlreadyPublished
@@ -1022,6 +1095,31 @@ export const createReleaseJournal = async (
1022
1095
  }
1023
1096
  };
1024
1097
 
1098
+ /** `--detach` is a bare flag; `--no-detach` runs in the foreground. */
1099
+ const readDetachFlag = (argvArg: any): boolean => {
1100
+ const value = argvArg.detach;
1101
+ if (value === undefined || value === false) return false;
1102
+ if (value === true) return true;
1103
+ throw new Error("--detach takes no value.");
1104
+ };
1105
+
1106
+ /**
1107
+ * Starts the release this command describes, without `--detach`, in a
1108
+ * session of its own and reports where it runs.
1109
+ */
1110
+ const startDetachedRelease = async (
1111
+ runsArg: DetachedReleaseRuns,
1112
+ versionArg: string,
1113
+ ): Promise<void> => {
1114
+ const run = await launchDetachedRelease({
1115
+ runs: runsArg,
1116
+ cwd: paths.cwd,
1117
+ workerArguments: getDetachedWorkerArguments(process.argv.slice(2)),
1118
+ version: versionArg,
1119
+ });
1120
+ console.log(describeDetachedReleaseLaunch(run));
1121
+ };
1122
+
1025
1123
  const runReleaseInspect = async (
1026
1124
  argvArg: any,
1027
1125
  modeArg: ICliMode,
@@ -1040,10 +1138,20 @@ const runReleaseInspect = async (
1040
1138
  const journals = requestedVersion
1041
1139
  ? [await store.read(normalizeReleaseVersion(requestedVersion))]
1042
1140
  : await store.list();
1141
+ // Detached runs are listed with all journals; a run that failed before its
1142
+ // tag has no journal to be found by version.
1143
+ const runs = requestedVersion
1144
+ ? undefined
1145
+ : await (await openDetachedReleaseRuns(paths.cwd)).list();
1043
1146
  if (modeArg.json) {
1044
- printJson({ ok: true, journals });
1147
+ printJson({ ok: true, journals, ...(runs ? { runs } : {}) });
1045
1148
  return;
1046
1149
  }
1150
+ if (runs?.length) {
1151
+ console.log("");
1152
+ console.log("Detached release runs");
1153
+ for (const run of runs) console.log(describeDetachedReleaseRun(run));
1154
+ }
1047
1155
  if (journals.length === 0) {
1048
1156
  console.log("No release journals found.");
1049
1157
  return;
@@ -1053,6 +1161,15 @@ const runReleaseInspect = async (
1053
1161
  }
1054
1162
  };
1055
1163
 
1164
+ const describeDetachedReleaseRun = (runArg: IDetachedReleaseRun): string => {
1165
+ const release = `gitzone ${runArg.command.join(" ")} (v${runArg.version})`;
1166
+ const outcome =
1167
+ runArg.state === "running"
1168
+ ? `running since ${runArg.startedAt} in process group ${runArg.supervisorPid}`
1169
+ : `${runArg.state} (${runArg.exitCode !== null ? `exit code ${runArg.exitCode}` : `signal ${runArg.signal}`}) at ${runArg.finishedAt}`;
1170
+ return `run ${runArg.id}: ${outcome}; ${release}; log ${runArg.logPath}`;
1171
+ };
1172
+
1056
1173
  const runReleaseRecover = async (
1057
1174
  argvArg: any,
1058
1175
  mode: ICliMode,
@@ -1082,6 +1199,9 @@ const runReleaseRecover = async (
1082
1199
  );
1083
1200
  }
1084
1201
  const version = normalizeReleaseVersion(argvArg._[2]);
1202
+ if (!argvArg.plan) {
1203
+ await (await openDetachedReleaseRuns(paths.cwd)).assertNoForeignRun();
1204
+ }
1085
1205
  const shell = new plugins.smartshell.Smartshell({
1086
1206
  executor: "bash",
1087
1207
  sourceFilePaths: [],
@@ -1176,6 +1296,7 @@ const runReleaseRecover = async (
1176
1296
  paths.cwd,
1177
1297
  branch.pushUrl,
1178
1298
  tsdocker,
1299
+ `run \`gitzone release recover ${version} -y\``,
1179
1300
  );
1180
1301
  if (tsdocker && dockerRequest) await tsdocker.validate(dockerRequest);
1181
1302
  if (!mode.yes) {
@@ -1204,7 +1325,7 @@ const runReleaseRecover = async (
1204
1325
  };
1205
1326
  const ensureUnpublished = async () => {
1206
1327
  await ensureState();
1207
- await assertRecoveryUnpublished(options);
1328
+ await assertRecoveryUnpublished(options, pnpmCapability);
1208
1329
  };
1209
1330
  const context = await withReleasePreparationRecovery(
1210
1331
  options,
@@ -1306,6 +1427,12 @@ const runReleaseResume = async (
1306
1427
  );
1307
1428
  }
1308
1429
  const version = normalizeReleaseVersion(argvArg._[2]);
1430
+ const detach = readDetachFlag(argvArg);
1431
+ if (detach && !modeArg.yes) {
1432
+ throw new Error(
1433
+ "--detach requires -y: a detached resume cannot ask for confirmation.",
1434
+ );
1435
+ }
1309
1436
  const smartshellInstance = new plugins.smartshell.Smartshell({
1310
1437
  executor: "bash",
1311
1438
  sourceFilePaths: [],
@@ -1313,6 +1440,17 @@ const runReleaseResume = async (
1313
1440
  const store = new ReleaseJournalStore(
1314
1441
  await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
1315
1442
  );
1443
+ const detachedRuns = await openDetachedReleaseRuns(paths.cwd);
1444
+ await detachedRuns.assertNoForeignRun();
1445
+ if (detach) {
1446
+ if (await store.hasJournal(version)) {
1447
+ await store.read(version);
1448
+ } else if (!(await store.readIntent(version))) {
1449
+ throw new Error(`Release journal v${version} does not exist.`);
1450
+ }
1451
+ await startDetachedRelease(detachedRuns, version);
1452
+ return;
1453
+ }
1316
1454
  // A release that failed between its tag and its journal left only its
1317
1455
  // intent; preparing the journal from it is part of this resume.
1318
1456
  const preparesRecordedRelease = !(await store.hasJournal(version));
@@ -1379,6 +1517,18 @@ const runReleaseResume = async (
1379
1517
  );
1380
1518
  await assertNoLegacyNpmPublisher(paths.cwd);
1381
1519
  await assertNoStandaloneTspublishPublisher(paths.cwd);
1520
+ await assertPrivateNpmAuthentication(
1521
+ smartshellInstance,
1522
+ paths.cwd,
1523
+ pnpmCapability,
1524
+ journal.npm.access,
1525
+ [
1526
+ ...new Set(
1527
+ journal.npm.registries.map((registryArg) => registryArg.registry),
1528
+ ),
1529
+ ],
1530
+ `run \`gitzone release resume ${version} -y\``,
1531
+ );
1382
1532
  for (const artifact of getReleaseArtifacts(journal)) {
1383
1533
  await verifyStoredNpmArtifact(
1384
1534
  store.getArtifactPath(version, artifact.file),
@@ -2131,6 +2281,11 @@ export function showHelp(mode?: ICliMode): void {
2131
2281
  description:
2132
2282
  "Recover one exact 32-character hexadecimal attempt ID after proving it stopped",
2133
2283
  },
2284
+ {
2285
+ flag: "--detach",
2286
+ description:
2287
+ "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",
2288
+ },
2134
2289
  ],
2135
2290
  });
2136
2291
  return;
@@ -2182,5 +2337,8 @@ export function showHelp(mode?: ICliMode): void {
2182
2337
  console.log(
2183
2338
  " --recover-attempt Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
2184
2339
  );
2340
+ console.log(
2341
+ " --detach With -y, run a release or resume in its own session; see `gitzone release inspect`",
2342
+ );
2185
2343
  console.log("");
2186
2344
  }
@@ -7,6 +7,12 @@ interface ILockOwner {
7
7
  createdAt: string;
8
8
  }
9
9
 
10
+ /** The process a held lock names, as far as its owner metadata tells. */
11
+ export interface IInterProcessLockHolder {
12
+ pid: number | null;
13
+ createdAt: string | null;
14
+ }
15
+
10
16
  export interface IInterProcessLockOptions {
11
17
  lockPath: string;
12
18
  description: string;
@@ -102,21 +108,11 @@ export class InterProcessLock {
102
108
  }
103
109
  const remaining = deadlineAt - Date.now();
104
110
  if (remaining <= 0) {
105
- let ownerDescription = 'owner metadata unavailable';
106
- try {
107
- const existingOwner = JSON.parse(await plugins.fs.readFile(ownerPath, 'utf8')) as {
108
- pid?: unknown;
109
- createdAt?: unknown;
110
- };
111
- if (
112
- typeof existingOwner.pid === 'number' &&
113
- typeof existingOwner.createdAt === 'string'
114
- ) {
115
- ownerDescription = `pid ${existingOwner.pid}, created ${existingOwner.createdAt}`;
116
- }
117
- } catch {
118
- // Incomplete stale locks remain fail-closed and require operator review.
119
- }
111
+ const holder = await this.readOwnerMetadata();
112
+ const ownerDescription =
113
+ holder.pid !== null && holder.createdAt !== null
114
+ ? `pid ${holder.pid}, created ${holder.createdAt}`
115
+ : 'owner metadata unavailable';
120
116
  throw new Error(
121
117
  `${this.description} is locked (${ownerDescription}). ` +
122
118
  `If that process no longer exists, inspect and remove ${this.lockPath}.`,
@@ -127,6 +123,39 @@ export class InterProcessLock {
127
123
  }
128
124
  }
129
125
 
126
+ /**
127
+ * The holder of the lock, or null while it is free. A lock whose owner
128
+ * metadata is missing or incomplete is still held; its holder is then
129
+ * unknown, and stale-lock recovery stays manual.
130
+ */
131
+ public async readHolder(): Promise<IInterProcessLockHolder | null> {
132
+ try {
133
+ await plugins.fs.lstat(this.lockPath);
134
+ } catch (error) {
135
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
136
+ throw new Error(`${this.description} lock could not be inspected.`, { cause: error });
137
+ }
138
+ return this.readOwnerMetadata();
139
+ }
140
+
141
+ private async readOwnerMetadata(): Promise<IInterProcessLockHolder> {
142
+ try {
143
+ const owner: unknown = JSON.parse(
144
+ await plugins.fs.readFile(plugins.path.join(this.lockPath, 'owner.json'), 'utf8'),
145
+ );
146
+ if (
147
+ isPlainObject(owner) &&
148
+ typeof owner.pid === 'number' &&
149
+ typeof owner.createdAt === 'string'
150
+ ) {
151
+ return { pid: owner.pid, createdAt: owner.createdAt };
152
+ }
153
+ } catch {
154
+ // Incomplete stale locks remain fail-closed and require operator review.
155
+ }
156
+ return { pid: null, createdAt: null };
157
+ }
158
+
130
159
  private async release(tokenArg: string, requireOwnerArg: boolean): Promise<void> {
131
160
  const ownerPath = plugins.path.join(this.lockPath, 'owner.json');
132
161
  if (requireOwnerArg) {
package/ts/paths.ts CHANGED
@@ -7,3 +7,13 @@ export let packageDir = plugins.path.join(
7
7
  export let assetsDir = plugins.path.join(packageDir, './assets');
8
8
  export let templatesDir = plugins.path.join(assetsDir, 'templates');
9
9
  export let cwd = process.cwd();
10
+
11
+ /**
12
+ * The executable that runs this build of gitzone: `cli.js` loads `dist_ts`, and
13
+ * `cli.ts.js` runs the TypeScript sources through tsrun. A process that starts
14
+ * another gitzone process uses it, so both run the same code.
15
+ */
16
+ export let cliEntryPath = plugins.path.join(
17
+ packageDir,
18
+ import.meta.url.endsWith('.ts') ? 'cli.ts.js' : 'cli.js',
19
+ );