@git.zone/cli 7.2.7 → 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.
@@ -94,10 +94,25 @@ import {
94
94
  type IReleaseVersionResolution,
95
95
  } from "./helpers.releaseversion.js";
96
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
+
97
108
  export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
98
109
 
99
110
  export const run = async (argvArg: any): Promise<void> => {
100
111
  try {
112
+ if (isDetachedReleaseSupervisor()) {
113
+ await superviseDetachedRelease();
114
+ return;
115
+ }
101
116
  await runInternal(argvArg);
102
117
  } catch (error) {
103
118
  logger.log("error", error instanceof Error ? error.message : String(error));
@@ -139,6 +154,12 @@ const runInternal = async (argvArg: any): Promise<void> => {
139
154
  return;
140
155
  }
141
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
+ }
142
163
  const smartshellInstance = new plugins.smartshell.Smartshell({
143
164
  executor: "bash",
144
165
  sourceFilePaths: [],
@@ -146,6 +167,16 @@ const runInternal = async (argvArg: any): Promise<void> => {
146
167
  const mergeRequested = resolveReleaseMergeFlag(argvArg);
147
168
  const workflow = await resolveReleaseWorkflow(argvArg);
148
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();
149
180
  let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
150
181
  smartshell: smartshellInstance,
151
182
  cwd: paths.cwd,
@@ -154,7 +185,9 @@ const runInternal = async (argvArg: any): Promise<void> => {
154
185
  pushBranch: workflow.pushBranch,
155
186
  pushTags: workflow.pushTags,
156
187
  mergeRequested,
157
- 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,
158
191
  gitRemotePolicy: createReleaseGitRemotePolicy(
159
192
  workflow.gitRemoteTimeoutSeconds,
160
193
  ),
@@ -181,6 +214,13 @@ const runInternal = async (argvArg: any): Promise<void> => {
181
214
  if (workflow.confirmation === "plan") {
182
215
  return;
183
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
+ }
184
224
 
185
225
  const preflightTsdocker = workflow.targets.includes("docker")
186
226
  ? new TsdockerReleaseClient(smartshellInstance, branchContext.sourceCwd)
@@ -1022,6 +1062,31 @@ export const createReleaseJournal = async (
1022
1062
  }
1023
1063
  };
1024
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
+
1025
1090
  const runReleaseInspect = async (
1026
1091
  argvArg: any,
1027
1092
  modeArg: ICliMode,
@@ -1040,10 +1105,20 @@ const runReleaseInspect = async (
1040
1105
  const journals = requestedVersion
1041
1106
  ? [await store.read(normalizeReleaseVersion(requestedVersion))]
1042
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();
1043
1113
  if (modeArg.json) {
1044
- printJson({ ok: true, journals });
1114
+ printJson({ ok: true, journals, ...(runs ? { runs } : {}) });
1045
1115
  return;
1046
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
+ }
1047
1122
  if (journals.length === 0) {
1048
1123
  console.log("No release journals found.");
1049
1124
  return;
@@ -1053,6 +1128,15 @@ const runReleaseInspect = async (
1053
1128
  }
1054
1129
  };
1055
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
+
1056
1140
  const runReleaseRecover = async (
1057
1141
  argvArg: any,
1058
1142
  mode: ICliMode,
@@ -1082,6 +1166,9 @@ const runReleaseRecover = async (
1082
1166
  );
1083
1167
  }
1084
1168
  const version = normalizeReleaseVersion(argvArg._[2]);
1169
+ if (!argvArg.plan) {
1170
+ await (await openDetachedReleaseRuns(paths.cwd)).assertNoForeignRun();
1171
+ }
1085
1172
  const shell = new plugins.smartshell.Smartshell({
1086
1173
  executor: "bash",
1087
1174
  sourceFilePaths: [],
@@ -1306,6 +1393,12 @@ const runReleaseResume = async (
1306
1393
  );
1307
1394
  }
1308
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
+ }
1309
1402
  const smartshellInstance = new plugins.smartshell.Smartshell({
1310
1403
  executor: "bash",
1311
1404
  sourceFilePaths: [],
@@ -1313,6 +1406,17 @@ const runReleaseResume = async (
1313
1406
  const store = new ReleaseJournalStore(
1314
1407
  await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
1315
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
+ }
1316
1420
  // A release that failed between its tag and its journal left only its
1317
1421
  // intent; preparing the journal from it is part of this resume.
1318
1422
  const preparesRecordedRelease = !(await store.hasJournal(version));
@@ -2131,6 +2235,11 @@ export function showHelp(mode?: ICliMode): void {
2131
2235
  description:
2132
2236
  "Recover one exact 32-character hexadecimal attempt ID after proving it stopped",
2133
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
+ },
2134
2243
  ],
2135
2244
  });
2136
2245
  return;
@@ -2182,5 +2291,8 @@ export function showHelp(mode?: ICliMode): void {
2182
2291
  console.log(
2183
2292
  " --recover-attempt Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
2184
2293
  );
2294
+ console.log(
2295
+ " --detach With -y, run a release or resume in its own session; see `gitzone release inspect`",
2296
+ );
2185
2297
  console.log("");
2186
2298
  }
@@ -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
+ );