@git.zone/cli 6.10.0 → 6.12.0

package/ts/mod_release/helpers.npmartifact.ts

@@ -4,16 +4,15 @@ import {
   type IReleaseArtifact,
 } from "./classes.releasejournal.js";
 import { assertCredentialFreeGitPushDestination } from "./helpers.releasebranch.js";
-
-const supportedPnpmVersions = [
-  "11.25.0",
-  "12.1.0",
-  "12.2.1",
-  "12.3.0",
-  "12.3.4",
-] as const;
-const pnpmHelpRequirements = {
-  "11.25.0": {
+import {
+  getDefaultMinimumReleaseAgeMinutes,
+  packageSelectorMatches,
+} from "../mod_tools/classes.packagemanager.js";
+
+const stablePnpmVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+// Qualify the command contract, independently of the executable's version.
+const pnpmHelpRequirements = [
+  {
     pack: ["--out <path>", "--json"],
     publish: [
       "publish [<tarball>|<dir>]",
@@ -24,33 +23,7 @@ const pnpmHelpRequirements = {
       "--access <public|restricted>",
     ],
   },
-  "12.1.0": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-  "12.2.1": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-  "12.3.0": {
+  {
     pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
     publish: [
       "Usage: pnpm publish [OPTIONS] [PACKAGE]",
@@ -63,20 +36,7 @@ const pnpmHelpRequirements = {
       "[possible values: public, restricted]",
     ],
   },
-  "12.3.4": {
-    pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
-    publish: [
-      "Usage: pnpm publish [OPTIONS] [PACKAGE]",
-      "Tarball or directory to publish",
-      "--no-git-checks",
-      "--ignore-scripts",
-      "--json",
-      "--tag <TAG>",
-      "--access <ACCESS>",
-      "[possible values: public, restricted]",
-    ],
-  },
-} as const;
+] as const;
 const maximumMetadataResponseBytes = 8 * 1024 * 1024;
 const capabilityCommandTimeoutMs = 30_000;
 const packCommandTimeoutMs = 10 * 60_000;
@@ -91,17 +51,14 @@ export function assertNpmPackageName(value: unknown): asserts value is string {
 }
 
 export interface IPnpmReleaseCapability {
-  readonly version: (typeof supportedPnpmVersions)[number];
+  readonly version: string;
 }
 
 export const buildQualifiedPnpmArgs = (
   capabilityArg: IPnpmReleaseCapability | undefined,
   argsArg: readonly string[],
 ): string[] => {
-  if (
-    !capabilityArg ||
-    !supportedPnpmVersions.includes(capabilityArg.version)
-  ) {
+  if (!capabilityArg || !stablePnpmVersion.test(capabilityArg.version)) {
     throw new Error(
       "npm release commands require a qualified pnpm invocation.",
     );
@@ -165,15 +122,140 @@ const readPackageIdentity = async (
 
 const requireHelpFragments = (
   outputArg: string,
-  fragmentsArg: readonly string[],
-  commandArg: string,
+  commandArg: "pack" | "publish",
 ): void => {
-  const missing = fragmentsArg.filter(
-    (fragmentArg) => !outputArg.includes(fragmentArg),
+  const missing = pnpmHelpRequirements.map((requirements) =>
+    requirements[commandArg].filter(
+      (fragment) => !outputArg.includes(fragment),
+    ),
+  );
+  if (missing.every((fragments) => fragments.length > 0)) {
+    throw new Error(
+      `pnpm ${commandArg} is missing required exact-release capabilities: ${missing.map((fragments) => fragments.join(", ")).join("; or ")}.`,
+    );
+  }
+};
+
+const readPnpmJson = async (
+  shellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  capabilityArg: IPnpmReleaseCapability,
+  argsArg: string[],
+  labelArg: string,
+): Promise<unknown> => {
+  const result = await shellArg.execSpawn(
+    "pnpm",
+    buildQualifiedPnpmArgs(capabilityArg, [...argsArg, "--json"]),
+    {
+      cwd: cwdArg,
+      silent: true,
+      timeout: capabilityCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+      maxBuffer: maximumMetadataResponseBytes,
+    },
+  );
+  if (result.exitCode !== 0 || result.timedOut) {
+    throw new Error(`Unable to inspect pnpm ${labelArg}.`);
+  }
+  if (result.stdout.trim() === "undefined") return undefined;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Invalid pnpm ${labelArg} response.`);
+  }
+};
+
+const assertPnpmReleaseAge = async (
+  shellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  capabilityArg: IPnpmReleaseCapability,
+): Promise<void> => {
+  const configuredAge = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["config", "get", "minimum-release-age"],
+    "minimum release age",
+  );
+  const age =
+    configuredAge === undefined || configuredAge === null
+      ? getDefaultMinimumReleaseAgeMinutes(capabilityArg.version)
+      : configuredAge;
+  if (
+    typeof age !== "number" ||
+    !Number.isSafeInteger(age) ||
+    age < 0 ||
+    age > Number.MAX_SAFE_INTEGER / 60_000
+  ) {
+    throw new Error(
+      "pnpm minimum-release-age must be a nonnegative integer number of minutes.",
+    );
+  }
+  if (age === 0) return;
+  const configuredExclusions = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["config", "get", "minimum-release-age-exclude"],
+    "release-age exclusions",
   );
-  if (missing.length > 0) {
+  const exclusions =
+    configuredExclusions === undefined || configuredExclusions === null
+      ? []
+      : configuredExclusions;
+  if (
+    !Array.isArray(exclusions) ||
+    exclusions.some((value) => typeof value !== "string" || !value.trim())
+  ) {
     throw new Error(
-      `pnpm ${commandArg} is missing required exact-release capabilities: ${missing.join(", ")}.`,
+      "pnpm minimum-release-age-exclude must be an array of package selectors.",
+    );
+  }
+  if (
+    exclusions.some((selector) =>
+      packageSelectorMatches("pnpm", capabilityArg.version, selector),
+    )
+  )
+    return;
+
+  const times = await readPnpmJson(
+    shellArg,
+    cwdArg,
+    capabilityArg,
+    ["view", `pnpm@${capabilityArg.version}`, "time"],
+    "publication times",
+  );
+  if (!times || typeof times !== "object" || Array.isArray(times)) {
+    throw new Error("pnpm publication times must be an object.");
+  }
+  const publishedAt = Object.hasOwn(times, capabilityArg.version)
+    ? (times as Record<string, unknown>)[capabilityArg.version]
+    : undefined;
+  if (publishedAt === undefined) {
+    const ignoreMissingTime = await readPnpmJson(
+      shellArg,
+      cwdArg,
+      capabilityArg,
+      ["config", "get", "minimum-release-age-ignore-missing-time"],
+      "missing publication time policy",
+    );
+    if (
+      ignoreMissingTime === true ||
+      ignoreMissingTime === undefined ||
+      ignoreMissingTime === null
+    )
+      return;
+    throw new Error(
+      `The registry has no publication time for pnpm ${capabilityArg.version}; its minimum release age cannot be verified.`,
+    );
+  }
+  const timestamp =
+    typeof publishedAt === "string" ? Date.parse(publishedAt) : NaN;
+  if (!Number.isFinite(timestamp))
+    throw new Error("Invalid pnpm publication timestamp.");
+  if (timestamp > Date.now() - age * 60_000) {
+    throw new Error(
+      `pnpm ${capabilityArg.version} does not yet satisfy minimum-release-age (${age} minutes).`,
     );
   }
 };
@@ -189,16 +271,17 @@ export const assertPnpmReleaseCapability = async (
     timeoutKillGraceMs: 5_000,
   });
   const version = versionResult.stdout.trim();
-  const supportedVersion = supportedPnpmVersions.find(
-    (candidateArg) => candidateArg === version,
-  );
-  if (versionResult.exitCode !== 0 || !supportedVersion) {
+  if (
+    versionResult.exitCode !== 0 ||
+    versionResult.timedOut ||
+    !stablePnpmVersion.test(version)
+  ) {
     throw new Error(
-      `Exact release packaging requires a verified pnpm version (${supportedPnpmVersions.join(", ")}); resolved ${version || "unknown"}.`,
+      "Exact release packaging requires a canonical stable pnpm version.",
     );
   }
-  const requirements = pnpmHelpRequirements[supportedVersion];
-  const capability = Object.freeze({ version: supportedVersion });
+  const capability = Object.freeze({ version });
+  await assertPnpmReleaseAge(smartshellArg, cwdArg, capability);
 
   const packHelp = await smartshellArg.execSpawn(
     "pnpm",
@@ -210,12 +293,12 @@ export const assertPnpmReleaseCapability = async (
       timeoutKillGraceMs: 5_000,
     },
   );
-  if (packHelp.exitCode !== 0) {
+  if (packHelp.exitCode !== 0 || packHelp.timedOut) {
     throw new Error(
       "Unable to inspect the selected pnpm pack capabilities. Exact release commands require standalone pnpm with support; Corepack launchers are unsupported.",
     );
   }
-  requireHelpFragments(packHelp.combinedOutput, requirements.pack, "pack");
+  requireHelpFragments(packHelp.combinedOutput, "pack");
 
   const publishHelp = await smartshellArg.execSpawn(
     "pnpm",
@@ -227,14 +310,10 @@ export const assertPnpmReleaseCapability = async (
       timeoutKillGraceMs: 5_000,
     },
   );
-  if (publishHelp.exitCode !== 0) {
+  if (publishHelp.exitCode !== 0 || publishHelp.timedOut) {
     throw new Error("Unable to inspect pnpm publish capabilities.");
   }
-  requireHelpFragments(
-    publishHelp.combinedOutput,
-    requirements.publish,
-    "publish",
-  );
+  requireHelpFragments(publishHelp.combinedOutput, "publish");
   return capability;
 };
 

package/ts/mod_standard/index.ts

@@ -17,7 +17,7 @@ const commandSummaries: ICommandHelpSummary[] = [
   {
     name: "commit",
     description:
-      "Analyze changes and create semantic source commits",
+      "Create semantic source commits from AI or manual input",
   },
   { name: "release", description: "Create versioned releases from pending changelog entries" },
   { name: "format", description: "Plan or apply project formatting changes" },

package/ts/mod_tools/classes.packagemanager.ts

@@ -992,7 +992,7 @@ function getLatestVersionFromMetadata(metadata: any): string | null {
   return typeof latest === "string" && latest.length > 0 ? latest : null;
 }
 
-function getDefaultMinimumReleaseAgeMinutes(currentPnpmVersion: string): number {
+export function getDefaultMinimumReleaseAgeMinutes(currentPnpmVersion: string): number {
   const majorVersion = normalizeSemver(currentPnpmVersion)[0] || 0;
   return majorVersion >= 11 ? 1440 : 0;
 }
@@ -1086,7 +1086,7 @@ function normalizePnpmConfigListItem(rawItem: string): string {
     .trim();
 }
 
-function packageSelectorMatches(
+export function packageSelectorMatches(
   packageName: string,
   version: string,
   pattern: string,