@git.zone/cli 6.16.1 → 6.16.3

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.
@@ -4,6 +4,10 @@ import {
4
4
  type IReleaseArtifact,
5
5
  } from "./classes.releasejournal.js";
6
6
  import { assertCredentialFreeGitPushDestination } from "./helpers.releasebranch.js";
7
+ import {
8
+ compareReleaseVersions,
9
+ isCanonicalReleaseVersion,
10
+ } from "./helpers.releaseversion.js";
7
11
  import {
8
12
  getDefaultMinimumReleaseAgeMinutes,
9
13
  packageSelectorMatches,
@@ -75,6 +79,7 @@ export interface INpmArtifactProbeResult {
75
79
  | "absent"
76
80
  | "exact"
77
81
  | "metadata-conflict"
82
+ | "superseded-tag"
78
83
  | "tarball-conflict"
79
84
  | "tag-conflict"
80
85
  | "registry-response"
@@ -795,6 +800,22 @@ const getMetadataUrl = (
795
800
  );
796
801
  };
797
802
 
803
+ /**
804
+ * The tarball bytes prove the release; the dist-tag only proves provenance.
805
+ * A later release moving the tag on is history, exactly as a `main` that moved
806
+ * past the release tag is history for Git, so a tag pointing at a canonical
807
+ * version above this one still reads as proof. An older version, a prerelease
808
+ * of this one, a non-semver value or an absent tag leave provenance unproven.
809
+ */
810
+ const tagSupersedesVersion = (
811
+ taggedVersionArg: unknown,
812
+ versionArg: string,
813
+ ): boolean =>
814
+ typeof taggedVersionArg === "string" &&
815
+ isCanonicalReleaseVersion(taggedVersionArg) &&
816
+ isCanonicalReleaseVersion(versionArg) &&
817
+ compareReleaseVersions(taggedVersionArg, versionArg) > 0;
818
+
798
819
  export const probeAnonymousNpmArtifact = async (
799
820
  registryArg: string,
800
821
  artifactArg: IReleaseArtifact,
@@ -883,10 +904,14 @@ export const probeAnonymousNpmArtifact = async (
883
904
  )) as {
884
905
  ["dist-tags"]?: Record<string, unknown>;
885
906
  };
886
- if (packageMetadata["dist-tags"]?.[tagArg] !== artifactArg.version) {
887
- return { status: "inconclusive", code: "tag-conflict" };
907
+ const taggedVersion = packageMetadata["dist-tags"]?.[tagArg];
908
+ if (taggedVersion === artifactArg.version) {
909
+ return { status: "exact", code: "exact" };
910
+ }
911
+ if (tagSupersedesVersion(taggedVersion, artifactArg.version)) {
912
+ return { status: "exact", code: "superseded-tag" };
888
913
  }
889
- return { status: "exact", code: "exact" };
914
+ return { status: "inconclusive", code: "tag-conflict" };
890
915
  } catch {
891
916
  return { status: "inconclusive", code: "network-error" };
892
917
  }
@@ -208,6 +208,20 @@ export class DockerArgvExecutionError extends Error {
208
208
  }
209
209
  }
210
210
 
211
+ /** One mount as Docker reports it, with the facts an ownership fence needs. */
212
+ export interface IContainerMountInfo {
213
+ /** Docker's mount type, for example `bind` or `volume`. */
214
+ type: string;
215
+ /** Volume name; empty for bind mounts. */
216
+ name: string;
217
+ /** Volume driver; empty for bind mounts. */
218
+ driver: string;
219
+ /** Resolved host-side source. */
220
+ source: string;
221
+ destination: string;
222
+ readWrite: boolean;
223
+ }
224
+
211
225
  /** Container facts needed to decide, safely, whether a container may be removed. */
212
226
  export interface IContainerInspectInfo {
213
227
  id: string;
@@ -215,10 +229,143 @@ export interface IContainerInspectInfo {
215
229
  state: string;
216
230
  running: boolean;
217
231
  labels: { [key: string]: string };
218
- /** Resolved host-side sources of every bind mount. */
232
+ /** Resolved host-side sources of every mount. */
219
233
  mountSources: string[];
234
+ /** Every mount Docker reported, in order. */
235
+ mounts: IContainerMountInfo[];
236
+ /** False when any mount entry could not be read exactly; fences must refuse. */
237
+ mountsProven: boolean;
238
+ /** Volume destinations the container's own image configuration declares. */
239
+ declaredVolumes: string[];
220
240
  }
221
241
 
242
+ /** Docker names an anonymous volume with a random 64-character hex id. */
243
+ const anonymousVolumeNamePattern = /^[a-f0-9]{64}$/u;
244
+
245
+ /**
246
+ * A container path in the exact form Docker reports mount destinations in, or
247
+ * undefined when the input is not an absolute POSIX path.
248
+ *
249
+ * Docker cleans every destination it mounts at (moby `daemon/create_unix.go`,
250
+ * `createContainerVolumesOS`: `destination := filepath.Clean(spec)`), while the
251
+ * image configuration keeps the raw `VOLUME` spec as its key (moby
252
+ * `daemon/builder/dockerfile/dispatchers.go`, `dispatchVolume`). So `VOLUME
253
+ * /data/db/` produces the declaration key `/data/db/` and the destination
254
+ * `/data/db`, and the two sides can only be compared in this cleaned form.
255
+ * `path.posix.normalize` keeps a trailing separator where Go's `filepath.Clean`
256
+ * drops it, so it is removed here.
257
+ */
258
+ const cleanedContainerDestination = (pathArg: string): string | undefined => {
259
+ if (!plugins.path.posix.isAbsolute(pathArg)) {
260
+ return undefined;
261
+ }
262
+ const normalized = plugins.path.posix.normalize(pathArg);
263
+ return normalized.length > 1 ? normalized.replace(/\/+$/u, '') : normalized;
264
+ };
265
+
266
+ /**
267
+ * True when a path is already exactly what Docker would report as a mount
268
+ * destination.
269
+ *
270
+ * Containment is decided by comparing two destinations, and
271
+ * `path.posix.relative` resolves a relative path against the process working
272
+ * directory, so a destination that is not absolute and clean would be judged
273
+ * against something that is not this operation's bind target at all. Such a
274
+ * destination is refused instead of interpreted.
275
+ */
276
+ const isCleanedContainerDestination = (pathArg: string): boolean =>
277
+ cleanedContainerDestination(pathArg) === pathArg;
278
+
279
+ /**
280
+ * True when a mount is one of the anonymous volumes Docker materialises for the
281
+ * image's own `VOLUME` declarations.
282
+ *
283
+ * Images such as `mongo:7.0` declare `/data/db` and `/data/configdb`. Docker
284
+ * creates a fresh anonymous volume for every declared destination the container
285
+ * does not already cover with an explicit mount, so a helper created from such
286
+ * an image always carries mounts GitZone never asked for. They are accepted
287
+ * only where Docker itself proves them image-declared and anonymous: the local
288
+ * volume driver, a random 64-hex volume name (a named volume is user data), and
289
+ * a destination the container's image configuration declares. A destination at
290
+ * or below the bind destination is refused as well, because the operation runs
291
+ * there and must only ever reach the bound host directory.
292
+ */
293
+ const isImageDeclaredAnonymousVolumeMount = (
294
+ mountArg: IContainerMountInfo,
295
+ declaredVolumesArg: readonly string[],
296
+ bindDestinationArg: string,
297
+ ): boolean => {
298
+ if (
299
+ !isCleanedContainerDestination(mountArg.destination) ||
300
+ !isCleanedContainerDestination(bindDestinationArg)
301
+ ) {
302
+ return false;
303
+ }
304
+ if (
305
+ mountArg.type !== 'volume' ||
306
+ mountArg.driver !== 'local' ||
307
+ !anonymousVolumeNamePattern.test(mountArg.name) ||
308
+ !declaredVolumesArg.some(
309
+ (declaredVolumeArg) =>
310
+ cleanedContainerDestination(declaredVolumeArg) === mountArg.destination,
311
+ )
312
+ ) {
313
+ return false;
314
+ }
315
+ const relativeToBind = plugins.path.posix.relative(bindDestinationArg, mountArg.destination);
316
+ // Only a path that actually walks out of the bind destination is outside it.
317
+ // A sibling whose first segment merely begins with dots — `/gitzone-target`
318
+ // against `/gitzone-target/..data` — relativises to `..data` and is *inside*:
319
+ // the cleanup command's own `rm -rf /gitzone-target/..?*` glob would delete
320
+ // exactly that name, so it must stay refused.
321
+ return relativeToBind === '..' || relativeToBind.startsWith('../');
322
+ };
323
+
324
+ /**
325
+ * True when a container's mount set is exactly one read-write bind of the
326
+ * target host path plus, at most, image-declared anonymous volumes.
327
+ *
328
+ * This is the one place that decides which mounts a proven GitZone bind helper
329
+ * may carry. A named volume, a second bind, a read-only target bind, a volume
330
+ * at an undeclared destination, a destination not in the cleaned absolute form
331
+ * Docker reports, or an unreadable mount entry all leave the container
332
+ * unproven.
333
+ */
334
+ const provesExactBindHelperMounts = (optionsArg: {
335
+ mounts: readonly IContainerMountInfo[];
336
+ mountsProven: boolean;
337
+ declaredVolumes: readonly string[];
338
+ hostPath: string;
339
+ containerPath?: string;
340
+ }): boolean => {
341
+ if (!optionsArg.mountsProven || !Array.isArray(optionsArg.mounts)) {
342
+ return false;
343
+ }
344
+ const bindMounts = optionsArg.mounts.filter((mountArg) => mountArg.type === 'bind');
345
+ if (bindMounts.length !== 1) {
346
+ return false;
347
+ }
348
+ const [bindMount] = bindMounts;
349
+ if (
350
+ !bindMount.readWrite ||
351
+ !isCleanedContainerDestination(bindMount.destination) ||
352
+ plugins.path.resolve(bindMount.source) !== plugins.path.resolve(optionsArg.hostPath) ||
353
+ (optionsArg.containerPath !== undefined &&
354
+ bindMount.destination !== optionsArg.containerPath)
355
+ ) {
356
+ return false;
357
+ }
358
+ return optionsArg.mounts.every(
359
+ (mountArg) =>
360
+ mountArg === bindMount ||
361
+ isImageDeclaredAnonymousVolumeMount(
362
+ mountArg,
363
+ optionsArg.declaredVolumes ?? [],
364
+ bindMount.destination,
365
+ ),
366
+ );
367
+ };
368
+
222
369
  const isExactStoppedBindHelperForTarget = (
223
370
  containerArg: IContainerInspectInfo,
224
371
  hostPathArg: string,
@@ -246,8 +393,12 @@ const isExactStoppedBindHelperForTarget = (
246
393
  Object.entries(expectedLabels).every(
247
394
  ([keyArg, valueArg]) => containerArg.labels[keyArg] === valueArg,
248
395
  ) &&
249
- containerArg.mountSources.length === 1 &&
250
- plugins.path.resolve(containerArg.mountSources[0]) === plugins.path.resolve(hostPathArg)
396
+ provesExactBindHelperMounts({
397
+ mounts: containerArg.mounts,
398
+ mountsProven: containerArg.mountsProven === true,
399
+ declaredVolumes: containerArg.declaredVolumes,
400
+ hostPath: hostPathArg,
401
+ })
251
402
  );
252
403
  };
253
404
 
@@ -330,9 +481,50 @@ interface IFencedBindInspection {
330
481
  entrypoint: string[];
331
482
  command: string[];
332
483
  labels: Record<string, string>;
333
- mounts: Array<{ source: string; destination: string; readWrite: boolean }>;
484
+ mounts: IContainerMountInfo[];
485
+ declaredVolumes: string[];
334
486
  }
335
487
 
488
+ /**
489
+ * Read one Docker mount entry exactly, or return undefined.
490
+ *
491
+ * Bind entries carry neither `Name` nor `Driver`, so both are optional and
492
+ * normalise to an empty string; every other field must be present and typed.
493
+ */
494
+ const parseContainerMount = (mountArg: unknown): IContainerMountInfo | undefined => {
495
+ if (
496
+ !isUnknownRecord(mountArg) ||
497
+ typeof mountArg.Type !== 'string' ||
498
+ typeof mountArg.Source !== 'string' ||
499
+ typeof mountArg.Destination !== 'string' ||
500
+ typeof mountArg.RW !== 'boolean' ||
501
+ (mountArg.Name !== undefined && typeof mountArg.Name !== 'string') ||
502
+ (mountArg.Driver !== undefined && typeof mountArg.Driver !== 'string')
503
+ ) {
504
+ return undefined;
505
+ }
506
+ return {
507
+ type: mountArg.Type,
508
+ name: typeof mountArg.Name === 'string' ? mountArg.Name : '',
509
+ driver: typeof mountArg.Driver === 'string' ? mountArg.Driver : '',
510
+ source: plugins.path.resolve(mountArg.Source),
511
+ destination: mountArg.Destination,
512
+ readWrite: mountArg.RW,
513
+ };
514
+ };
515
+
516
+ /**
517
+ * Volume destinations declared by the image a container was created from.
518
+ * Docker copies them into the container's own `Config.Volumes`, which is what
519
+ * produced the container's anonymous volumes in the first place.
520
+ */
521
+ const parseDeclaredVolumes = (configArg: unknown): string[] => {
522
+ if (!isUnknownRecord(configArg) || !isUnknownRecord(configArg.Volumes)) {
523
+ return [];
524
+ }
525
+ return Object.keys(configArg.Volumes);
526
+ };
527
+
336
528
  const parseFencedBindInspection = (
337
529
  stdoutArg: string,
338
530
  expectedNameArg?: string,
@@ -380,21 +572,15 @@ const parseFencedBindInspection = (
380
572
  }
381
573
  labels[key] = value;
382
574
  }
575
+ // Mount *shape* is validated here; which mounts are acceptable is decided by
576
+ // the ownership fence, because that depends on the operation's bind target
577
+ // and on the image's own volume declarations.
383
578
  const mounts = inspected.Mounts.map((mountArg: unknown) => {
384
- if (
385
- !isUnknownRecord(mountArg) ||
386
- mountArg.Type !== 'bind' ||
387
- typeof mountArg.Source !== 'string' ||
388
- typeof mountArg.Destination !== 'string' ||
389
- typeof mountArg.RW !== 'boolean'
390
- ) {
579
+ const mount = parseContainerMount(mountArg);
580
+ if (!mount) {
391
581
  throw new Error(`Docker returned an invalid bind-operation inspection for ${expectedNameArg}.`);
392
582
  }
393
- return {
394
- source: plugins.path.resolve(mountArg.Source),
395
- destination: mountArg.Destination,
396
- readWrite: mountArg.RW,
397
- };
583
+ return mount;
398
584
  });
399
585
  return {
400
586
  id: inspected.Id,
@@ -409,6 +595,7 @@ const parseFencedBindInspection = (
409
595
  command: [...config.Cmd],
410
596
  labels,
411
597
  mounts,
598
+ declaredVolumes: parseDeclaredVolumes(config),
412
599
  };
413
600
  };
414
601
 
@@ -562,11 +749,13 @@ export class DockerContainer {
562
749
  expectedGitZoneLabels.every(
563
750
  ([key, value]) => inspectionArg.labels[key] === value,
564
751
  );
565
- const mountsMatch =
566
- inspectionArg.mounts.length === 1 &&
567
- inspectionArg.mounts[0].source === plugins.path.resolve(optionsArg.hostPath) &&
568
- inspectionArg.mounts[0].destination === optionsArg.containerPath &&
569
- inspectionArg.mounts[0].readWrite;
752
+ const mountsMatch = provesExactBindHelperMounts({
753
+ mounts: inspectionArg.mounts,
754
+ mountsProven: true,
755
+ declaredVolumes: inspectionArg.declaredVolumes,
756
+ hostPath: optionsArg.hostPath,
757
+ containerPath: optionsArg.containerPath,
758
+ });
570
759
  if (
571
760
  inspectionArg.name !== optionsArg.name ||
572
761
  inspectionArg.image !== optionsArg.image ||
@@ -607,10 +796,13 @@ export class DockerContainer {
607
796
  ) &&
608
797
  typeof invocationId === 'string' &&
609
798
  /^[a-f0-9]{32}$/u.test(invocationId);
610
- const mountMatches =
611
- inspectionArg.mounts.length === 1 &&
612
- inspectionArg.mounts[0].source === plugins.path.resolve(optionsArg.hostPath) &&
613
- inspectionArg.mounts[0].readWrite;
799
+ const mountMatches = provesExactBindHelperMounts({
800
+ mounts: inspectionArg.mounts,
801
+ mountsProven: true,
802
+ declaredVolumes: inspectionArg.declaredVolumes,
803
+ hostPath: optionsArg.hostPath,
804
+ containerPath: optionsArg.containerPath,
805
+ });
614
806
  const operationMatches = [
615
807
  { entrypoint: optionsArg.entrypoint, command: optionsArg.command },
616
808
  ...(optionsArg.recoverablePredecessors ?? []),
@@ -629,8 +821,7 @@ export class DockerContainer {
629
821
  inspectionArg.user !== '0' ||
630
822
  !operationMatches ||
631
823
  !labelsMatch ||
632
- !mountMatches ||
633
- inspectionArg.mounts[0].destination !== optionsArg.containerPath
824
+ !mountMatches
634
825
  ) {
635
826
  throw new Error(
636
827
  `Refusing bind-operation container ${expectedNameArg}: canonical helper ownership is not proven.`,
@@ -729,7 +920,10 @@ export class DockerContainer {
729
920
  }
730
921
  // Non-forced removal is the atomic handoff: if another process starts the
731
922
  // helper after inspection, Docker refuses removal instead of killing it.
732
- await this.execArgv(['rm', inspection.id], optionsArg.executionOptions());
923
+ // `-v` takes the helper's own anonymous volumes with it; Docker never
924
+ // removes a named volume this way, and the fence proved every extra mount
925
+ // is an anonymous image-declared volume of exactly this helper.
926
+ await this.execArgv(['rm', '-v', inspection.id], optionsArg.executionOptions());
733
927
  }
734
928
 
735
929
  /**
@@ -811,7 +1005,7 @@ export class DockerContainer {
811
1005
  if (completed.running || completed.status !== 'exited' || completed.exitCode !== 0) {
812
1006
  throw new Error(`Bind-operation container ${operationName} did not exit successfully.`);
813
1007
  }
814
- await this.execArgv(['rm', containerId], runtimeOptions.executionOptions());
1008
+ await this.execArgv(['rm', '-v', containerId], runtimeOptions.executionOptions());
815
1009
  return;
816
1010
  } catch (error) {
817
1011
  operationError = normalizeError(error);
@@ -855,7 +1049,7 @@ export class DockerContainer {
855
1049
  await this.inspectFencedBindOperation(containerId, runtimeOptions, {
856
1050
  timeoutMs: runtimeOptions.rollbackTimeoutMs ?? 5_000,
857
1051
  });
858
- await this.execArgv(['rm', '-f', containerId], {
1052
+ await this.execArgv(['rm', '-f', '-v', containerId], {
859
1053
  timeoutMs: runtimeOptions.rollbackTimeoutMs ?? 5_000,
860
1054
  });
861
1055
  } catch (error) {
@@ -1520,10 +1714,23 @@ export class DockerContainer {
1520
1714
  return parsed.map((container: any) => {
1521
1715
  const labels = (container?.Config?.Labels || {}) as { [key: string]: string };
1522
1716
  const mountSources: string[] = [];
1523
- for (const mount of container?.Mounts || []) {
1717
+ const mounts: IContainerMountInfo[] = [];
1718
+ const rawMounts = container?.Mounts;
1719
+ // Every container on the daemon passes through here, so an unreadable
1720
+ // mount entry must not fail the whole query. It is recorded as unproven
1721
+ // instead, which keeps ownership fences refusing while the conflict scan
1722
+ // still sees every source it could read.
1723
+ let mountsProven = Array.isArray(rawMounts);
1724
+ for (const mount of Array.isArray(rawMounts) ? rawMounts : []) {
1524
1725
  if (mount?.Source) {
1525
1726
  mountSources.push(plugins.path.resolve(mount.Source));
1526
1727
  }
1728
+ const parsedMount = parseContainerMount(mount);
1729
+ if (!parsedMount) {
1730
+ mountsProven = false;
1731
+ continue;
1732
+ }
1733
+ mounts.push(parsedMount);
1527
1734
  }
1528
1735
  return {
1529
1736
  id: String(container?.Id || ''),
@@ -1532,6 +1739,9 @@ export class DockerContainer {
1532
1739
  running: container?.State?.Running === true,
1533
1740
  labels,
1534
1741
  mountSources,
1742
+ mounts,
1743
+ mountsProven,
1744
+ declaredVolumes: parseDeclaredVolumes(container?.Config),
1535
1745
  };
1536
1746
  });
1537
1747
  }