@git.zone/cli 8.3.2 → 8.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 (29) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/helpers.workflow.d.ts +14 -0
  3. package/dist_ts/helpers.workflow.js +29 -1
  4. package/dist_ts/mod_config/index.js +42 -1
  5. package/dist_ts/mod_release/classes.releasejournal.d.ts +19 -3
  6. package/dist_ts/mod_release/classes.releasejournal.js +95 -9
  7. package/dist_ts/mod_release/helpers.npmartifact.d.ts +68 -7
  8. package/dist_ts/mod_release/helpers.npmartifact.js +192 -26
  9. package/dist_ts/mod_release/helpers.releasebranch.d.ts +11 -0
  10. package/dist_ts/mod_release/helpers.releasebranch.js +88 -61
  11. package/dist_ts/mod_release/helpers.releaseline.d.ts +60 -0
  12. package/dist_ts/mod_release/helpers.releaseline.js +129 -0
  13. package/dist_ts/mod_release/helpers.releasepublication.d.ts +2 -0
  14. package/dist_ts/mod_release/helpers.releasepublication.js +86 -19
  15. package/dist_ts/mod_release/helpers.releaseversion.d.ts +2 -0
  16. package/dist_ts/mod_release/helpers.releaseversion.js +4 -2
  17. package/dist_ts/mod_release/index.js +130 -40
  18. package/package.json +3 -3
  19. package/readme.md +123 -7
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/helpers.workflow.ts +54 -0
  22. package/ts/mod_config/index.ts +47 -0
  23. package/ts/mod_release/classes.releasejournal.ts +149 -10
  24. package/ts/mod_release/helpers.npmartifact.ts +302 -22
  25. package/ts/mod_release/helpers.releasebranch.ts +120 -45
  26. package/ts/mod_release/helpers.releaseline.ts +214 -0
  27. package/ts/mod_release/helpers.releasepublication.ts +168 -16
  28. package/ts/mod_release/helpers.releaseversion.ts +5 -1
  29. package/ts/mod_release/index.ts +177 -26
@@ -8,12 +8,14 @@ export declare const buildQualifiedPnpmArgs: (capabilityArg: IPnpmReleaseCapabil
8
8
  export type TNpmArtifactProbeStatus = "absent" | "exact" | "conflict" | "inconclusive";
9
9
  export interface INpmArtifactProbeResult {
10
10
  status: TNpmArtifactProbeStatus;
11
- code: "absent" | "exact" | "metadata-conflict" | "superseded-tag" | "tarball-conflict" | "tag-conflict" | "registry-response" | "network-error" | "authentication-required";
11
+ code: "absent" | "exact" | "metadata-conflict" | "superseded-tag" | "tarball-conflict" | "tag-conflict" | "dist-tag-conflict" | "registry-response" | "network-error" | "authentication-required";
12
12
  /**
13
13
  * Why the registry did not confirm the configured authentication, as a
14
14
  * redacted command diagnostic. Only authenticated probes set it.
15
15
  */
16
16
  failure?: string;
17
+ /** The `latest` value a `dist-tag-conflict` observed. */
18
+ observedLatest?: unknown;
17
19
  }
18
20
  export interface INpmArtifactProbeOptions {
19
21
  fetchImplementation?: typeof fetch;
@@ -47,6 +49,12 @@ export declare const probeDelayForAttempt: (attemptArg: number, delayMsArg: numb
47
49
  */
48
50
  export declare const planNpmAvailabilityProbes: (windowMsArg: number, delayMsArg: number, maxDelayMsArg: number) => Required<Pick<INpmArtifactProbeOptions, "attempts" | "delayMs" | "maxDelayMs">>;
49
51
  export declare const assertPnpmReleaseCapability: (smartshellArg: plugins.smartshell.Smartshell, cwdArg: string) => Promise<IPnpmReleaseCapability>;
52
+ /**
53
+ * A private package's dist-tags are read through `pnpm view <name> dist-tags
54
+ * --json` before it is published, so that command form joins the qualified
55
+ * contract wherever such a read happens.
56
+ */
57
+ export declare const assertPnpmDistTagReadCapability: (smartshellArg: plugins.smartshell.Smartshell, cwdArg: string, capabilityArg: IPnpmReleaseCapability) => Promise<void>;
50
58
  export declare const findDevelopmentDocumentsInPackage: (filePathsArg: readonly string[]) => string[];
51
59
  export declare const assertNoDevelopmentDocumentsInPackage: (filePathsArg: readonly string[]) => void;
52
60
  export declare const assertNoLegacyNpmPublisher: (cwdArg: string) => Promise<void>;
@@ -75,8 +83,8 @@ export declare const buildNpmDestinationArgs: (registryArg: string, packageNameA
75
83
  * publish with restricted access, bound to the destination for their scope as
76
84
  * well, because their verification reads through the same binding.
77
85
  */
78
- export declare const buildPnpmPublishArgs: (artifactPathArg: string, registryArg: string, accessArg?: TReleaseNpmAccess, packageNameArg?: string) => string[];
79
- export declare const publishNpmArtifact: (smartshellArg: plugins.smartshell.Smartshell, cwdArg: string, artifactPathArg: string, registryArg: string, capabilityArg: IPnpmReleaseCapability | undefined, accessArg?: TReleaseNpmAccess, packageNameArg?: string) => Promise<{
86
+ export declare const buildPnpmPublishArgs: (artifactPathArg: string, registryArg: string, distTagArg: string, accessArg?: TReleaseNpmAccess, packageNameArg?: string) => string[];
87
+ export declare const publishNpmArtifact: (smartshellArg: plugins.smartshell.Smartshell, cwdArg: string, artifactPathArg: string, registryArg: string, capabilityArg: IPnpmReleaseCapability | undefined, distTagArg: string, accessArg?: TReleaseNpmAccess, packageNameArg?: string) => Promise<{
80
88
  exitCode: number;
81
89
  output: string;
82
90
  failure?: string;
@@ -92,8 +100,32 @@ export declare const npmPublishWasAccepted: (resultArg: {
92
100
  }) => boolean;
93
101
  /** Recovery without an original artifact must never adopt a published version. */
94
102
  export declare const assertNpmVersionAbsent: (registryArg: string, packageNameArg: string, versionArg: string, optionsArg?: INpmArtifactProbeOptions) => Promise<void>;
95
- export declare const probeAnonymousNpmArtifact: (registryArg: string, artifactArg: IReleaseArtifact, tagArg?: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
96
- export declare const waitForAnonymousNpmArtifact: (registryArg: string, artifactArg: IReleaseArtifact, tagArg?: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
103
+ /**
104
+ * A package's dist-tags before a version is published: `absent` when the
105
+ * registry does not know the package, which is how a first publication looks.
106
+ */
107
+ export type TNpmDistTagsRead = {
108
+ status: "present";
109
+ distTags: Record<string, unknown>;
110
+ } | {
111
+ status: "absent";
112
+ } | {
113
+ status: "inconclusive";
114
+ code: "registry-response" | "network-error" | "authentication-required";
115
+ failure?: string;
116
+ };
117
+ /** Reads a public package's dist-tags anonymously, as its probe does. */
118
+ export declare const readAnonymousNpmDistTags: (registryArg: string, packageNameArg: string, optionsArg?: INpmArtifactProbeOptions) => Promise<TNpmDistTagsRead>;
119
+ /**
120
+ * Reads the dist-tags of a published version. `latest` follows the rule
121
+ * above. A maintenance line's tag is superseded only by a later version of
122
+ * its own major, and a line release additionally requires `latest` to still
123
+ * carry a higher major: a line whose version took `latest` is a terminal
124
+ * conflict, because the registry now serves it as the newest release.
125
+ */
126
+ export declare const assessPublishedDistTags: (distTagsArg: Record<string, unknown> | undefined, versionArg: string, distTagArg: string) => INpmArtifactProbeResult;
127
+ export declare const probeAnonymousNpmArtifact: (registryArg: string, artifactArg: IReleaseArtifact, tagArg: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
128
+ export declare const waitForAnonymousNpmArtifact: (registryArg: string, artifactArg: IReleaseArtifact, tagArg: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
97
129
  /**
98
130
  * The package manager an authenticated registry read runs through. GitZone
99
131
  * never reads, parses, logs or journals a credential: the qualified pnpm reads
@@ -114,6 +146,13 @@ export declare class NpmRegistryAuthenticationError extends Error {
114
146
  * registry does not confirm, before anything is published.
115
147
  */
116
148
  export declare const assertNpmRegistryAuthentication: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, nextStepArg: string) => Promise<void>;
149
+ /**
150
+ * Reads a private package's dist-tags with the registry's configured
151
+ * authentication through `pnpm view <name> dist-tags --json`, which
152
+ * {@link assertPnpmDistTagReadCapability} qualifies. A not-found answer proves
153
+ * absence only when the registry also confirms that authentication.
154
+ */
155
+ export declare const readAuthenticatedNpmDistTags: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, packageNameArg: string) => Promise<TNpmDistTagsRead>;
117
156
  /**
118
157
  * Verifies a private destination through an authenticated metadata read: the
119
158
  * version must exist with the packed artifact's integrity and SHA-1, a
@@ -122,10 +161,32 @@ export declare const assertNpmRegistryAuthentication: (readerArg: IAuthenticated
122
161
  * registry's authentication, so the bytes are proven by the registry's
123
162
  * integrity record rather than downloaded.
124
163
  */
125
- export declare const probeAuthenticatedNpmArtifact: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, artifactArg: IReleaseArtifact, tagArg?: string) => Promise<INpmArtifactProbeResult>;
126
- export declare const waitForAuthenticatedNpmArtifact: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, artifactArg: IReleaseArtifact, tagArg?: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
164
+ export declare const probeAuthenticatedNpmArtifact: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, artifactArg: IReleaseArtifact, tagArg: string) => Promise<INpmArtifactProbeResult>;
165
+ export declare const waitForAuthenticatedNpmArtifact: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, artifactArg: IReleaseArtifact, tagArg: string, optionsArg?: INpmArtifactProbeOptions) => Promise<INpmArtifactProbeResult>;
127
166
  /**
128
167
  * Recovery without an original artifact must never adopt a published
129
168
  * version; a private version's absence needs a confirmed authentication.
130
169
  */
131
170
  export declare const assertAuthenticatedNpmVersionAbsent: (readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, packageNameArg: string, versionArg: string, nextStepArg: string) => Promise<void>;
171
+ /** Reads one package's dist-tags the way its verification reads the package. */
172
+ export declare const readNpmDistTags: (accessArg: TReleaseNpmAccess, readerArg: IAuthenticatedNpmRegistryReader, registryArg: string, packageNameArg: string, probeOptionsArg?: INpmArtifactProbeOptions) => Promise<TNpmDistTagsRead>;
173
+ export interface INpmDistTagPreflightOptions {
174
+ reader: IAuthenticatedNpmRegistryReader;
175
+ access: TReleaseNpmAccess;
176
+ registries: readonly string[];
177
+ packageNames: readonly string[];
178
+ version: string;
179
+ distTag: string;
180
+ /** What the operator runs once an authentication failure is fixed. */
181
+ nextStep: string;
182
+ probeOptions?: INpmArtifactProbeOptions;
183
+ }
184
+ /**
185
+ * Before anything is committed or tagged, every package at every registry
186
+ * must allow `version` under `distTag`: a `main` release never moves `latest`
187
+ * downwards, and a line never takes `latest` or moves its own tag backwards.
188
+ * A registry that cannot be read stops the release as well, because nothing
189
+ * else proves the dist-tags it would change. A private read needs the
190
+ * capability the release qualified with {@link assertPnpmDistTagReadCapability}.
191
+ */
192
+ export declare const assertNpmDistTagsAllowPublication: (optionsArg: INpmDistTagPreflightOptions) => Promise<void>;