@git.zone/cli 8.5.1 → 8.7.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 (40) hide show
  1. package/assets/templates/asset_tspack_release_gitea/.gitea/workflows/release.yml +12 -18
  2. package/assets/templates/asset_tspack_release_gitea/scripts/gitzone-gitea-tag.d.mts +22 -0
  3. package/assets/templates/asset_tspack_release_gitea/scripts/gitzone-gitea-tag.mjs +48 -0
  4. package/assets/templates/asset_tspack_release_gitea/scripts/gitzone-release-api.mjs +244 -74
  5. package/assets/templates/asset_tspack_release_gitea/scripts/gitzone-sealed-release.mjs +103 -38
  6. package/assets/templates/vscode/.vscode/settings.json +57 -0
  7. package/dist_ts/00_commitinfo_data.js +1 -1
  8. package/dist_ts/classes.gitzoneconfig.d.ts +3 -0
  9. package/dist_ts/classes.gitzoneconfig.js +1 -1
  10. package/dist_ts/helpers.objects.d.ts +2 -0
  11. package/dist_ts/helpers.objects.js +3 -0
  12. package/dist_ts/helpers.packagefiles.d.ts +74 -0
  13. package/dist_ts/helpers.packagefiles.js +177 -0
  14. package/dist_ts/helpers.workflow.d.ts +18 -0
  15. package/dist_ts/helpers.workflow.js +45 -2
  16. package/dist_ts/mod_config/index.js +69 -2
  17. package/dist_ts/mod_format/formatters/assets.formatter.js +2 -1
  18. package/dist_ts/mod_format/formatters/packagejson.formatter.js +8 -27
  19. package/dist_ts/mod_release/helpers.giteaassets.d.ts +4 -14
  20. package/dist_ts/mod_release/helpers.giteaassets.js +20 -35
  21. package/dist_ts/mod_release/helpers.npmartifactcheck.d.ts +93 -0
  22. package/dist_ts/mod_release/helpers.npmartifactcheck.js +279 -0
  23. package/dist_ts/mod_release/index.d.ts +15 -0
  24. package/dist_ts/mod_release/index.js +82 -17
  25. package/dist_ts/plugins.d.ts +2 -1
  26. package/dist_ts/plugins.js +3 -2
  27. package/package.json +2 -1
  28. package/readme.md +147 -33
  29. package/ts/00_commitinfo_data.ts +1 -1
  30. package/ts/classes.gitzoneconfig.ts +3 -0
  31. package/ts/helpers.objects.ts +5 -0
  32. package/ts/helpers.packagefiles.ts +273 -0
  33. package/ts/helpers.workflow.ts +70 -1
  34. package/ts/mod_config/index.ts +78 -0
  35. package/ts/mod_format/formatters/assets.formatter.ts +1 -0
  36. package/ts/mod_format/formatters/packagejson.formatter.ts +7 -27
  37. package/ts/mod_release/helpers.giteaassets.ts +28 -44
  38. package/ts/mod_release/helpers.npmartifactcheck.ts +397 -0
  39. package/ts/mod_release/index.ts +115 -26
  40. package/ts/plugins.ts +2 -0
@@ -73,6 +73,12 @@ export interface IReleaseNpmTargetConfig {
73
73
  alreadyPublished?: "success" | "error";
74
74
  /** Minutes one accepted upload may stay unreadable before resume takes over. */
75
75
  verificationWindowMinutes?: number;
76
+ /**
77
+ * Largest publish body, in bytes, each named registry accepts. A release
78
+ * whose estimated body exceeds it stops before anything is pushed. A
79
+ * registry without an entry has no limit.
80
+ */
81
+ maxPublishBytes?: Record<string, number>;
76
82
  }
77
83
 
78
84
  export interface IReleaseGiteaAssetsTargetConfig {
@@ -334,6 +340,10 @@ export interface IResolvedReleaseWorkflow {
334
340
  npmAccessLevel: "public" | "private";
335
341
  npmAlreadyPublished: "success" | "error";
336
342
  npmVerificationWindowMinutes: number;
343
+ /** Publish body limits by normalized registry URL; empty without limits. */
344
+ npmMaxPublishBytes: Record<string, number>;
345
+ /** `@git.zone/cli.packageFiles` is configured, so preflight checks package.json files. */
346
+ packageFilesConfigured: boolean;
337
347
  giteaAssets?: IResolvedReleaseGiteaAssetsConfiguration;
338
348
  giteaAssetTransfer?: IGiteaAssetTransferLimits;
339
349
  /** Attachments of a draft in progress at the same time. */
@@ -389,6 +399,7 @@ export type TResolvedReleaseDockerConfiguration = Pick<
389
399
  interface ICliWorkflowConfig {
390
400
  commit?: ICommitWorkflowConfig;
391
401
  release?: IReleaseWorkflowConfig;
402
+ packageFiles?: unknown;
392
403
  }
393
404
 
394
405
  const commitFlagToStep: Record<string, TCommitStep | undefined> = {
@@ -788,8 +799,12 @@ const buildReleasePlan = (options: {
788
799
  targets: TReleaseTarget[];
789
800
  npmModules: boolean;
790
801
  cleanTestArtifacts: boolean;
802
+ packageFiles: boolean;
803
+ npmPublishSizeLimit: boolean;
791
804
  }): string[] => {
792
805
  const plan: string[] = ["preflight.branch", "preflight.cleanTree"];
806
+ // package.json files must be what `.smartconfig.json` packageFiles generates.
807
+ if (options.packageFiles) plan.push("preflight.packageFiles");
793
808
  // Only a checkout with a package.json installs from a committed pnpm
794
809
  // lockfile, so only such a release proves that install before it creates its
795
810
  // commit and tag. A Deno-only project has no pnpm lockfile to prove.
@@ -815,7 +830,14 @@ const buildReleasePlan = (options: {
815
830
  if (options.runBuild) plan.push("core.releaseCheckout.build");
816
831
  }
817
832
  if (options.npmModules) plan.push("core.prepareNpmModules");
818
- if (options.targets.includes("npm")) plan.push("core.packNpmArtifact");
833
+ if (options.targets.includes("npm")) {
834
+ plan.push("core.packNpmArtifact");
835
+ // Each packed tarball must carry the files its manifest names, and fit
836
+ // the publish body limit of every registry that configures one.
837
+ plan.push("core.packNpmArtifact.entryPoints");
838
+ if (options.npmPublishSizeLimit)
839
+ plan.push("core.packNpmArtifact.publishSize");
840
+ }
819
841
  if (options.targets.includes("giteaAssets"))
820
842
  plan.push("core.freezeGiteaAssets");
821
843
  plan.push("core.writeReleaseJournal");
@@ -952,6 +974,44 @@ export const resolveNpmVerificationWindowMinutes = (
952
974
  return valueArg;
953
975
  };
954
976
 
977
+ /**
978
+ * `release.targets.npm.maxPublishBytes`: whole byte limits keyed by registry
979
+ * URL. Every key must be one of the configured registries, so a typo cannot
980
+ * silently leave a registry without its limit.
981
+ */
982
+ export const resolveNpmMaxPublishBytes = (
983
+ valueArg: unknown,
984
+ registriesArg: string[],
985
+ ): Record<string, number> => {
986
+ if (valueArg === undefined) return {};
987
+ if (typeof valueArg !== "object" || valueArg === null || Array.isArray(valueArg))
988
+ throw new Error(
989
+ "release.targets.npm.maxPublishBytes must map registry URLs to byte limits.",
990
+ );
991
+ const limits: Record<string, number> = {};
992
+ for (const [registry, limit] of Object.entries(valueArg)) {
993
+ const normalized = normalizeRegistryUrl(registry);
994
+ if (!registriesArg.includes(normalized))
995
+ throw new Error(
996
+ `release.targets.npm.maxPublishBytes names ${registry}, which is not one of release.targets.npm.registries (${registriesArg.join(", ") || "none"}).`,
997
+ );
998
+ if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1)
999
+ throw new Error(
1000
+ `release.targets.npm.maxPublishBytes for ${registry} must be a whole number of bytes greater than 0.`,
1001
+ );
1002
+ if (Object.hasOwn(limits, normalized))
1003
+ throw new Error(
1004
+ `release.targets.npm.maxPublishBytes names ${normalized} more than once.`,
1005
+ );
1006
+ limits[normalized] = limit;
1007
+ }
1008
+ return limits;
1009
+ };
1010
+
1011
+ /** The registry URL form `release.targets.npm.registries` resolves to. */
1012
+ export const normalizeReleaseRegistryUrl = (urlArg: string): string =>
1013
+ normalizeRegistryUrl(urlArg);
1014
+
955
1015
  /**
956
1016
  * The npm target reads its package set from the project, so the setting that
957
1017
  * used to choose between the root package and the tspublish modules is gone.
@@ -1147,6 +1207,11 @@ export const resolveReleaseWorkflow = async (
1147
1207
  const npmPackages = targets.includes("npm")
1148
1208
  ? (await planReleaseNpmPackages(process.cwd())).packageSet
1149
1209
  : undefined;
1210
+ // Dormant settings of an inactive target are not validated.
1211
+ const npmMaxPublishBytes = targets.includes("npm")
1212
+ ? resolveNpmMaxPublishBytes(npmConfig.maxPublishBytes, npmRegistries)
1213
+ : {};
1214
+ const packageFilesConfigured = cliConfig.packageFiles !== undefined;
1150
1215
 
1151
1216
  return {
1152
1217
  confirmation,
@@ -1158,6 +1223,8 @@ export const resolveReleaseWorkflow = async (
1158
1223
  targets,
1159
1224
  npmModules: (npmPackages?.modules.length ?? 0) > 0,
1160
1225
  cleanTestArtifacts,
1226
+ packageFiles: packageFilesConfigured,
1227
+ npmPublishSizeLimit: Object.keys(npmMaxPublishBytes).length > 0,
1161
1228
  }),
1162
1229
  projectType,
1163
1230
  targets,
@@ -1188,6 +1255,8 @@ export const resolveReleaseWorkflow = async (
1188
1255
  npmVerificationWindowMinutes: resolveNpmVerificationWindowMinutes(
1189
1256
  npmConfig.verificationWindowMinutes,
1190
1257
  ),
1258
+ npmMaxPublishBytes,
1259
+ packageFilesConfigured,
1191
1260
  ...(giteaAssets
1192
1261
  ? {
1193
1262
  giteaAssets,
@@ -28,7 +28,10 @@ import {
28
28
  resolveGiteaAssetTransferLimits,
29
29
  resolveGitRemoteTimeoutSeconds,
30
30
  resolveNpmVerificationWindowMinutes,
31
+ resolveNpmMaxPublishBytes,
32
+ normalizeReleaseRegistryUrl,
31
33
  } from "../helpers.workflow.js";
34
+ import { resolvePackageFiles } from "../helpers.packagefiles.js";
32
35
  import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
33
36
  import { TsdockerReleaseClient } from "../mod_release/helpers.tsdockerprotocol.js";
34
37
  import {
@@ -1221,10 +1224,60 @@ async function collectDoctorFindings(): Promise<IDoctorFinding[]> {
1221
1224
  validateCommitConfig(cliConfig.commit || {}, findings);
1222
1225
  await validateReleaseConfig(cliConfig.release, smartconfigData, findings);
1223
1226
  await validateAssetsConfig(cliConfig.assets, smartconfigData, findings);
1227
+ await validatePackageFilesConfig(cliConfig, findings);
1224
1228
 
1225
1229
  return findings;
1226
1230
  }
1227
1231
 
1232
+ /** `packageFiles` must resolve, and package.json must carry what it generates. */
1233
+ async function validatePackageFilesConfig(
1234
+ cliConfig: Record<string, any>,
1235
+ findings: IDoctorFinding[],
1236
+ ): Promise<void> {
1237
+ if (cliConfig.packageFiles === undefined) {
1238
+ findings.push({
1239
+ level: "ok",
1240
+ message: "Package files use every default set",
1241
+ });
1242
+ return;
1243
+ }
1244
+ let packageJson: Record<string, any>;
1245
+ try {
1246
+ packageJson = await readPackageJson();
1247
+ } catch (error) {
1248
+ findings.push({
1249
+ level: "error",
1250
+ message: "package.json is not valid JSON",
1251
+ fix: error instanceof Error ? error.message : String(error),
1252
+ });
1253
+ return;
1254
+ }
1255
+ let files: string[];
1256
+ try {
1257
+ files = resolvePackageFiles({
1258
+ packageFiles: cliConfig.packageFiles,
1259
+ assets: isPlainObject(cliConfig.assets) ? cliConfig.assets : undefined,
1260
+ manifest: packageJson,
1261
+ });
1262
+ } catch (error) {
1263
+ findings.push({
1264
+ level: "error",
1265
+ message: error instanceof Error ? error.message : String(error),
1266
+ fix: "Correct @git.zone/cli.packageFiles as the readme's Package contents section describes.",
1267
+ });
1268
+ return;
1269
+ }
1270
+ findings.push(
1271
+ JSON.stringify(packageJson.files) === JSON.stringify(files)
1272
+ ? { level: "ok", message: "package.json files matches packageFiles" }
1273
+ : {
1274
+ level: "warn",
1275
+ message: "package.json files differs from what packageFiles generates",
1276
+ fix: "Run `gitzone format`; a release refuses the difference.",
1277
+ },
1278
+ );
1279
+ }
1280
+
1228
1281
  /**
1229
1282
  * Where each key gitzone once read from `@ship.zone/szci` lives now.
1230
1283
  */
@@ -2304,6 +2357,31 @@ async function validateNpmTarget(
2304
2357
  });
2305
2358
  }
2306
2359
 
2360
+ try {
2361
+ const limits = resolveNpmMaxPublishBytes(
2362
+ npmTarget.maxPublishBytes,
2363
+ registries
2364
+ .filter((registryArg): registryArg is string => typeof registryArg === "string")
2365
+ .map(normalizeReleaseRegistryUrl),
2366
+ );
2367
+ findings.push({
2368
+ level: "ok",
2369
+ message:
2370
+ Object.keys(limits).length > 0
2371
+ ? `npm publish body limits: ${Object.entries(limits)
2372
+ .map(([registry, limit]) => `${registry} ${limit} bytes`)
2373
+ .join(", ")}`
2374
+ : "npm publish body limits: none configured",
2375
+ });
2376
+ } catch (error) {
2377
+ findings.push({
2378
+ level: "error",
2379
+ message:
2380
+ error instanceof Error ? error.message : "Invalid npm publish body limits",
2381
+ fix: "Set release.targets.npm.maxPublishBytes to an object of configured registry URLs and whole byte limits, or remove it.",
2382
+ });
2383
+ }
2384
+
2307
2385
  const smartNetwork = new plugins.smartnetwork.SmartNetwork();
2308
2386
  await Promise.all(
2309
2387
  registries.map(async (registry) => {
@@ -140,6 +140,7 @@ const buildDefaultEntries = (assetsConfig: Record<string, any>, cliName: string)
140
140
  { from: '.gitea/workflows/release.yml', to: '.gitea/workflows/release.yml' },
141
141
  { from: 'scripts/gitzone-sealed-release.mjs', to: 'scripts/gitzone-sealed-release.mjs' },
142
142
  { from: 'scripts/gitzone-release-api.mjs', to: 'scripts/gitzone-release-api.mjs' },
143
+ { from: 'scripts/gitzone-gitea-tag.mjs', to: 'scripts/gitzone-gitea-tag.mjs' },
143
144
  ],
144
145
  }];
145
146
  }
@@ -3,6 +3,7 @@ import type { IPlannedChange } from '../interfaces.format.js';
3
3
  import * as plugins from '../mod.plugins.js';
4
4
  import * as paths from '../../paths.js';
5
5
  import { logger, logVerbose } from '../../gitzone.logging.js';
6
+ import { resolvePackageFiles } from '../../helpers.packagefiles.js';
6
7
 
7
8
  export class PackageJsonFormatter extends BaseFormatter {
8
9
  get name(): string {
@@ -103,33 +104,12 @@ export class PackageJsonFormatter extends BaseFormatter {
103
104
  }
104
105
  }
105
106
 
106
- // Set files array
107
- const sourceFolders = ['ts', 'ts_web'];
108
- const files = [
109
- ...sourceFolders.map((folderArg) => `${folderArg}/**/*`),
110
- 'dist/**/*',
111
- 'dist_*/**/*',
112
- 'dist_ts/**/*',
113
- 'dist_ts_web/**/*',
114
- 'assets/**/*',
115
- 'cli.js',
116
- '.smartconfig.json',
117
- 'readme.md',
118
- ];
119
-
120
- if (assetsConfig?.kind === 'denoBinaryCli' && assetsConfig.installer?.enabled !== false) {
121
- files.push(assetsConfig.installer?.file || 'install.sh');
122
- }
123
- if (assetsConfig?.kind === 'denoBinaryCli' && assetsConfig.npmWrapper?.enabled) {
124
- files.push('bin/');
125
- files.push(assetsConfig.npmWrapper.postinstallFile || 'scripts/install-binary.js');
126
- }
127
- // @git.zone/tsbuild reads a folder's compiler options from <folder>/tsconfig.json,
128
- // which extends the root tsconfig.json. The package does not ship the root file,
129
- // so a shipped folder file would extend a file that is not there. pnpm 10 and 12
130
- // apply an exclusion only after the entries that include the file, so it comes last.
131
- files.push(...sourceFolders.map((folderArg) => `!${folderArg}/tsconfig.json`));
132
- packageJson.files = [...new Set(files)];
107
+ // gitzone format is the one writer of `files`; see helpers.packagefiles.ts.
108
+ packageJson.files = resolvePackageFiles({
109
+ packageFiles: gitzoneData.packageFiles,
110
+ assets: rawAssetsConfig,
111
+ manifest: packageJson,
112
+ });
133
113
 
134
114
  // Set pnpm overrides from assets
135
115
  try {
@@ -11,6 +11,13 @@ import type {
11
11
  IGiteaAssetTransferLimits,
12
12
  } from "./interfaces.giteaassets.js";
13
13
  export type * from "./interfaces.giteaassets.js";
14
+ // The tag-processing wait is shared with the sealed release workflow, which runs a rendered copy.
15
+ import {
16
+ awaitGiteaTagProcessed,
17
+ giteaReleasePagePath,
18
+ giteaTagProcessingPollIntervalMs,
19
+ giteaTagProcessingTimeoutMs,
20
+ } from "../../assets/templates/asset_tspack_release_gitea/scripts/gitzone-gitea-tag.mjs";
14
21
 
15
22
  const maximumManifestBytes = 4 * 1024 * 1024;
16
23
  const maximumMetadataBytes = 8 * 1024 * 1024;
@@ -127,12 +134,9 @@ export const defaultGiteaAssetConcurrency = 1;
127
134
  */
128
135
  export const maximumGiteaAssetConcurrency = 2;
129
136
 
130
- /**
131
- * Gitea processes a pushed tag in its push queue, after the push returned;
132
- * a busy queue has been seen to take more than 90 s.
133
- */
134
- export const defaultGiteaTagProcessingTimeoutMs = 15 * 60_000;
135
- export const defaultGiteaTagProcessingPollIntervalMs = 5_000;
137
+ export const defaultGiteaTagProcessingTimeoutMs = giteaTagProcessingTimeoutMs;
138
+ export const defaultGiteaTagProcessingPollIntervalMs =
139
+ giteaTagProcessingPollIntervalMs;
136
140
  const maximumTagProcessingTimeoutMs = 6 * 60 * 60_000;
137
141
  const maximumTransferTimeoutMs = 60 * 60_000;
138
142
  const maximumBytesPerSecond = 1024 * 1024 * 1024;
@@ -1053,7 +1057,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1053
1057
  private release(value: unknown): IGiteaRelease {
1054
1058
  const release = record(value);
1055
1059
  const id = positiveId(release.id);
1056
- const publicUrl = `${this.destination.apiOrigin}/${this.destination.owner}/${this.destination.repository}/releases/tag/${encodeURIComponent(this.tag)}`;
1060
+ const publicUrl = `${this.destination.apiOrigin}${giteaReleasePagePath(this.destination.owner, this.destination.repository, this.tag)}`;
1057
1061
  if (
1058
1062
  release.tag_name !== this.tag ||
1059
1063
  typeof release.draft !== "boolean" ||
@@ -1117,7 +1121,7 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1117
1121
  try {
1118
1122
  watchdog.awaitResponse();
1119
1123
  response = await this.fetchImplementation(
1120
- `${this.destination.apiOrigin}/${this.destination.owner}/${this.destination.repository}/releases/tag/${encodeURIComponent(this.tag)}`,
1124
+ `${this.destination.apiOrigin}${giteaReleasePagePath(this.destination.owner, this.destination.repository, this.tag)}`,
1121
1125
  {
1122
1126
  redirect: "manual",
1123
1127
  signal: watchdog.signal,
@@ -1141,47 +1145,27 @@ export class GiteaAssetsClient implements IGiteaAssetsClient {
1141
1145
  }
1142
1146
 
1143
1147
  /**
1144
- * Waits until Gitea has processed the pushed tag. Gitea handles a tag push
1145
- * in its push queue after the push returned: it writes a tag-only release
1146
- * row for the tag, or, when a release for the tag already exists, sets
1147
- * `draft: false` on it (services/repository/push.go, pushUpdateAddTags). A
1148
- * draft created before that runs is published by Gitea with whatever
1149
- * attachments it has. Once the tag-only row exists, creating the release
1150
- * converts that row into the draft in place, and the processed push never
1151
- * touches it again. The caller has seen no release for the tag through the
1152
- * API, which hides tag-only rows, so a public page proves the tag-only row.
1148
+ * Waits until Gitea has processed the pushed tag; `awaitGiteaTagProcessed`
1149
+ * (shared with the sealed release workflow) documents why a draft must not
1150
+ * exist before that.
1153
1151
  */
1154
1152
  private async awaitTagProcessed(
1155
1153
  onWaiting?: (elapsedMs: number) => void,
1156
1154
  ): Promise<void> {
1157
- const started = Date.now();
1158
- let reportedAt: number | undefined;
1159
- while (true) {
1160
- const status = await this.publicReleasePageStatus();
1161
- if (status === 200) return;
1162
- if (status !== 404)
1163
- throw new GiteaAssetInconclusiveError(
1164
- `Gitea release page check is inconclusive (HTTP ${status}); no release was created.`,
1165
- );
1166
- const elapsed = Date.now() - started;
1167
- if (elapsed >= this.tagProcessingTimeoutMs)
1168
- throw new GiteaTagProcessingTimeoutError(
1169
- `Gitea has not processed the pushed tag ${this.tag} within ${formatSeconds(elapsed)}; the draft release was not created, because Gitea publishes a draft it finds for the tag once it processes the push. Resume once Gitea shows the tag.`,
1170
- );
1171
- if (reportedAt === undefined || elapsed - reportedAt >= 60_000) {
1172
- reportedAt = elapsed;
1173
- onWaiting?.(elapsed);
1174
- }
1175
- await new Promise<void>((resolve) =>
1176
- setTimeout(
1177
- resolve,
1178
- Math.min(
1179
- this.tagProcessingPollIntervalMs,
1180
- this.tagProcessingTimeoutMs - elapsed,
1181
- ),
1182
- ),
1155
+ const result = await awaitGiteaTagProcessed({
1156
+ pageStatus: () => this.publicReleasePageStatus(),
1157
+ timeoutMs: this.tagProcessingTimeoutMs,
1158
+ pollIntervalMs: this.tagProcessingPollIntervalMs,
1159
+ onWaiting,
1160
+ });
1161
+ if (result.outcome === "unexpected")
1162
+ throw new GiteaAssetInconclusiveError(
1163
+ `Gitea release page check is inconclusive (HTTP ${result.status}); no release was created.`,
1164
+ );
1165
+ if (result.outcome === "timeout")
1166
+ throw new GiteaTagProcessingTimeoutError(
1167
+ `Gitea has not processed the pushed tag ${this.tag} within ${formatSeconds(result.elapsedMs)}; the draft release was not created, because Gitea publishes a draft it finds for the tag once it processes the push. Resume once Gitea shows the tag.`,
1183
1168
  );
1184
- }
1185
1169
  }
1186
1170
 
1187
1171
  public async createRelease(