@git.zone/cli 6.6.2 → 6.7.2

package/ts/mod_release/helpers.npmartifact.ts

@@ -5,7 +5,12 @@ import {
 } from "./classes.releasejournal.js";
 import { assertCredentialFreeGitPushDestination } from "./helpers.releasebranch.js";
 
-const supportedPnpmVersions = ["11.25.0", "12.1.0", "12.2.1", "12.3.4"] as const;
+const supportedPnpmVersions = [
+  "11.25.0",
+  "12.1.0",
+  "12.2.1",
+  "12.3.4",
+] as const;
 const pnpmHelpRequirements = {
   "11.25.0": {
     pack: ["--out <path>", "--json"],
@@ -62,17 +67,15 @@ const maximumMetadataResponseBytes = 8 * 1024 * 1024;
 const capabilityCommandTimeoutMs = 30_000;
 const packCommandTimeoutMs = 10 * 60_000;
 const publishCommandTimeoutMs = 5 * 60_000;
-const packageNameRegex = /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+const packageNameRegex =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
 
 export interface IPnpmReleaseCapability {
   version: (typeof supportedPnpmVersions)[number];
 }
 
 export type TNpmArtifactProbeStatus =
-  | "absent"
-  | "exact"
-  | "conflict"
-  | "inconclusive";
+  "absent" | "exact" | "conflict" | "inconclusive";
 
 export interface INpmArtifactProbeResult {
   status: TNpmArtifactProbeStatus;
@@ -99,7 +102,10 @@ const readPackageIdentity = async (
   let packageJson: unknown;
   try {
     packageJson = JSON.parse(
-      await plugins.fs.readFile(plugins.path.join(cwdArg, "package.json"), "utf8"),
+      await plugins.fs.readFile(
+        plugins.path.join(cwdArg, "package.json"),
+        "utf8",
+      ),
     );
   } catch (error) {
     throw new Error("Unable to read package.json for npm release packaging.", {
@@ -190,12 +196,67 @@ export const assertPnpmReleaseCapability = async (
   return { version: supportedVersion };
 };
 
+/**
+ * Development documents must never reach a published tarball.
+ *
+ * npm-packlist force-includes every root level file whose name starts with
+ * "readme" (case insensitive), so neither the package.json files array nor
+ * .npmignore can keep readme.plan.md or readme.hints.md out of the package.
+ * plan.md and hints.md are not force-included but a broad files array can still
+ * capture them, so both spellings are refused here.
+ */
+const developmentDocumentPatterns = [
+  /^readme\.plan(?:\..+)?$/i,
+  /^readme\.hints(?:\..+)?$/i,
+  /^plan\.md$/i,
+  /^hints\.md$/i,
+  /^readme\..+\.md$/i,
+] as const;
+
+export const findDevelopmentDocumentsInPackage = (
+  filePathsArg: readonly string[],
+): string[] => {
+  const offenders = new Set<string>();
+  for (const filePath of filePathsArg) {
+    if (typeof filePath !== "string" || !filePath) continue;
+    const normalized = filePath.replace(/\\/g, "/").replace(/^\.\//, "");
+    // Only root level files matter, npm force-inclusion is a root level rule.
+    if (normalized.includes("/")) continue;
+    if (
+      developmentDocumentPatterns.some((patternArg) =>
+        patternArg.test(normalized),
+      )
+    ) {
+      offenders.add(normalized);
+    }
+  }
+  return [...offenders].sort();
+};
+
+export const assertNoDevelopmentDocumentsInPackage = (
+  filePathsArg: readonly string[],
+): void => {
+  const offenders = findDevelopmentDocumentsInPackage(filePathsArg);
+  if (offenders.length === 0) {
+    return;
+  }
+  throw new Error(
+    `The npm package would publish development documents: ${offenders.join(", ")}. ` +
+      'npm force-includes every root file whose name starts with "readme", so neither the ' +
+      "package.json files array nor .npmignore can exclude them. Rename them to names that are " +
+      "not published (readme.plan.md -> plan.md, readme.hints.md -> hints.md; `gitzone format` " +
+      "performs this rename), or drop them from the files array, then release again.",
+  );
+};
+
 const legacyPublishWorkflowPaths = [
   ".gitea/workflows/default_tags.yaml",
   ".gitlab-ci.yml",
 ] as const;
 
-export const assertNoLegacyNpmPublisher = async (cwdArg: string): Promise<void> => {
+export const assertNoLegacyNpmPublisher = async (
+  cwdArg: string,
+): Promise<void> => {
   for (const relativePath of legacyPublishWorkflowPaths) {
     const filePath = plugins.path.join(cwdArg, relativePath);
     let content: string;
@@ -205,9 +266,12 @@ export const assertNoLegacyNpmPublisher = async (cwdArg: string): Promise<void>
       if ((error as NodeJS.ErrnoException).code === "ENOENT") {
         continue;
       }
-      throw new Error(`Unable to inspect ${relativePath} for legacy npm publication.`, {
-        cause: error,
-      });
+      throw new Error(
+        `Unable to inspect ${relativePath} for legacy npm publication.`,
+        {
+          cause: error,
+        },
+      );
     }
     const activeContent = content
       .split("\n")
@@ -288,17 +352,21 @@ export const packNpmArtifact = async (
   cwdArg: string,
   destinationDirectoryArg: string,
   expectedVersionArg: string,
+  fileArg: string = releaseArtifactFileName,
 ): Promise<IReleaseArtifact> => {
+  if (
+    fileArg !== releaseArtifactFileName &&
+    !/^package\.[0-9a-f]{64}\.tgz$/.test(fileArg)
+  ) {
+    throw new Error("Invalid release artifact filename.");
+  }
   const identity = await readPackageIdentity(cwdArg);
   if (identity.version !== expectedVersionArg) {
     throw new Error(
       `package.json version ${identity.version} does not match release ${expectedVersionArg}.`,
     );
   }
-  const artifactPath = plugins.path.join(
-    destinationDirectoryArg,
-    releaseArtifactFileName,
-  );
+  const artifactPath = plugins.path.join(destinationDirectoryArg, fileArg);
   const result = await smartshellArg.execSpawn(
     "pnpm",
     ["pack", "--out", artifactPath, "--json"],
@@ -309,13 +377,17 @@ export const packNpmArtifact = async (
     },
   );
   if (result.exitCode !== 0) {
-    throw new Error("pnpm pack failed while creating the exact release artifact.");
+    throw new Error(
+      "pnpm pack failed while creating the exact release artifact.",
+    );
   }
   let report: unknown;
   try {
     const stdout = result.stdout.trim();
     const reportStart = stdout.lastIndexOf("\n{");
-    report = JSON.parse(reportStart === -1 ? stdout : stdout.slice(reportStart + 1));
+    report = JSON.parse(
+      reportStart === -1 ? stdout : stdout.slice(reportStart + 1),
+    );
   } catch (error) {
     throw new Error("pnpm pack did not return its required JSON report.", {
       cause: error,
@@ -330,12 +402,26 @@ export const packNpmArtifact = async (
   ) {
     throw new Error("pnpm pack reported a different package identity.");
   }
+  const reportedFiles = (report as { files?: unknown }).files;
+  if (!Array.isArray(reportedFiles)) {
+    throw new Error(
+      "pnpm pack did not report the packed file list, so the package contents cannot be verified.",
+    );
+  }
+  assertNoDevelopmentDocumentsInPackage(
+    reportedFiles.map((entryArg) =>
+      typeof entryArg === "string"
+        ? entryArg
+        : String((entryArg as { path?: unknown })?.path ?? ""),
+    ),
+  );
   await syncFile(artifactPath);
-  return calculateNpmArtifact(
+  const artifact = await calculateNpmArtifact(
     artifactPath,
     identity.packageName,
     identity.version,
   );
+  return { ...artifact, file: fileArg };
 };
 
 export const verifyStoredNpmArtifact = async (
@@ -353,7 +439,9 @@ export const verifyStoredNpmArtifact = async (
     actual.sha256 !== expectedArtifactArg.sha256 ||
     actual.integrity !== expectedArtifactArg.integrity
   ) {
-    throw new Error("Stored npm artifact no longer matches its release journal identity.");
+    throw new Error(
+      "Stored npm artifact no longer matches its release journal identity.",
+    );
   }
 };
 
@@ -451,10 +539,15 @@ const readBoundedResponse = async (
     }
     reader.releaseLock();
   }
-  return Buffer.concat(chunks.map((chunkArg) => Buffer.from(chunkArg)), size);
+  return Buffer.concat(
+    chunks.map((chunkArg) => Buffer.from(chunkArg)),
+    size,
+  );
 };
 
-const readBoundedJsonResponse = async (responseArg: Response): Promise<unknown> =>
+const readBoundedJsonResponse = async (
+  responseArg: Response,
+): Promise<unknown> =>
   JSON.parse(
     (
       await readBoundedResponse(
@@ -561,7 +654,9 @@ export const probeAnonymousNpmArtifact = async (
       cancelResponseBody(packageResponse);
       return { status: "inconclusive", code: "registry-response" };
     }
-    const packageMetadata = (await readBoundedJsonResponse(packageResponse)) as {
+    const packageMetadata = (await readBoundedJsonResponse(
+      packageResponse,
+    )) as {
       ["dist-tags"]?: Record<string, unknown>;
     };
     if (packageMetadata["dist-tags"]?.[tagArg] !== artifactArg.version) {
@@ -582,7 +677,9 @@ export const waitForAnonymousNpmArtifact = async (
   const attempts = optionsArg.attempts ?? 10;
   const delayMs = optionsArg.delayMs ?? 1_000;
   if (!Number.isSafeInteger(attempts) || attempts < 1) {
-    throw new Error("npm verification attempts must be a positive safe integer.");
+    throw new Error(
+      "npm verification attempts must be a positive safe integer.",
+    );
   }
   let lastResult: INpmArtifactProbeResult = {
     status: "inconclusive",

package/ts/mod_release/helpers.releasepublication.ts

@@ -5,6 +5,8 @@ import {
   createReleaseDockerPromotions,
   finalizeJournalCompletion,
   getReleaseDockerPromotionContext,
+  getReleaseArtifacts,
+  getReleaseNpmArtifact,
   type TReleaseJournal,
   type IReleaseJournalV2,
   type IReleaseTargetStatus,
@@ -71,7 +73,7 @@ export function buildReleaseGitPushArgs(
 
 type TReleaseTargetSelector =
   | { kind: "git" }
-  | { kind: "npm"; registry: string }
+  | { kind: "npm"; registry: string; packageName?: string }
   | { kind: "docker-qualification" }
   | { kind: "docker-promotion"; promotionId: string }
   | { kind: "docker-cleanup" };
@@ -128,7 +130,9 @@ const getTargetStatus = (
     return promotion;
   }
   const registry = journalArg.npm.registries.find(
-    (registryArg) => registryArg.registry === selectorArg.registry,
+    (registryArg) =>
+      registryArg.registry === selectorArg.registry &&
+      registryArg.packageName === selectorArg.packageName,
   );
   if (!registry) {
     throw new Error(
@@ -486,20 +490,19 @@ const probeNpm = async (
   registryArg: string,
   optionsArg: IReleasePublicationOptions,
   waitArg = false,
+  packageNameArg?: string,
 ): Promise<INpmArtifactProbeResult> => {
-  if (!journalArg.artifact) {
-    throw new Error("npm release target has no exact artifact.");
-  }
+  const artifact = getReleaseNpmArtifact(journalArg, packageNameArg);
   return waitArg
     ? waitForAnonymousNpmArtifact(
         registryArg,
-        journalArg.artifact,
+        artifact,
         journalArg.npm.tag,
         optionsArg.npmProbeOptions,
       )
     : probeAnonymousNpmArtifact(
         registryArg,
-        journalArg.artifact,
+        artifact,
         journalArg.npm.tag,
         optionsArg.npmProbeOptions,
       );
@@ -527,14 +530,23 @@ const executeNpmRegistry = async (
   optionsArg: IReleasePublicationOptions,
   journalArg: TReleaseJournal,
   registryArg: string,
+  packageNameArg?: string,
+  deferVerificationArg = false,
 ): Promise<TReleaseJournal> => {
   const selector: TReleaseTargetSelector = {
     kind: "npm",
     registry: registryArg,
+    packageName: packageNameArg,
   };
   let journal = journalArg;
   let status = getTargetStatus(journal, selector);
-  let probe = await probeNpm(journal, registryArg, optionsArg);
+  let probe = await probeNpm(
+    journal,
+    registryArg,
+    optionsArg,
+    false,
+    packageNameArg,
+  );
 
   if (status.state === "verified") {
     if (probe.status === "exact") {
@@ -596,7 +608,64 @@ const executeNpmRegistry = async (
     throw new Error(`npm registry target is in conflict: ${registryArg}`);
   }
 
-  probe = await probeNpm(journal, registryArg, optionsArg);
+  // A component submission can succeed before npm makes it installable. Keep
+  // that uncertainty durable without retaining a live publisher or resending
+  // the accepted artifact on resume. Older root/Docker journal behavior stays
+  // unchanged.
+  if (
+    journal.schemaVersion === 3 &&
+    status.state === "failed" &&
+    status.attempts > 0 &&
+    status.error === "verification-inconclusive" &&
+    probe.status !== "exact" &&
+    probe.status !== "conflict"
+  ) {
+    if (deferVerificationArg) return journal;
+    console.log(
+      `Waiting for npm availability: ${packageNameArg} on ${registryArg}`,
+    );
+    probe = await probeNpm(
+      journal,
+      registryArg,
+      {
+        ...optionsArg,
+        npmProbeOptions: {
+          attempts: 91,
+          delayMs: 10_000,
+          ...optionsArg.npmProbeOptions,
+        },
+      },
+      true,
+      packageNameArg,
+    );
+    await optionsArg.ensurePublicationState(
+      journal.git.state === "verified"
+        ? journal.release.mainOid
+        : journal.git.expectedRemoteMainOid || undefined,
+    );
+    if (probe.status === "exact") {
+      return markUnclaimedTarget(
+        optionsArg.store,
+        journal,
+        selector,
+        ["failed"],
+        "verified",
+        null,
+      );
+    }
+    await markNpmProbeFailure(optionsArg, journal, selector, ["failed"], probe);
+    throw new Error(
+      `npm availability could not be verified: ${packageNameArg} on ${registryArg}`,
+    );
+  }
+
+  probe = await probeNpm(
+    journal,
+    registryArg,
+    optionsArg,
+    false,
+    packageNameArg,
+  );
   if (probe.status === "exact") {
     if (status.attempts === 0 && journal.npm.alreadyPublished === "error") {
       await markUnclaimedTarget(
@@ -619,6 +688,15 @@ const executeNpmRegistry = async (
     );
   }
   if (probe.status !== "absent") {
+    if (
+      journal.schemaVersion === 3 &&
+      status.state === "failed" &&
+      probe.status === "inconclusive"
+    ) {
+      // Preserve a prior command failure: a later network failure must not
+      // turn it into evidence that the registry accepted the submission.
+      throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
+    }
     await markNpmProbeFailure(
       optionsArg,
       journal,
@@ -629,13 +707,12 @@ const executeNpmRegistry = async (
     throw new Error(`npm registry cannot be verified safely: ${registryArg}`);
   }
 
+  const artifact = getReleaseNpmArtifact(journal, packageNameArg);
   const artifactPath = optionsArg.store.getArtifactPath(
     journal.release.version,
+    artifact.file,
   );
-  if (!journal.artifact) {
-    throw new Error("npm release journal has no artifact.");
-  }
-  await verifyStoredNpmArtifact(artifactPath, journal.artifact);
+  await verifyStoredNpmArtifact(artifactPath, artifact);
   journal = await claimTarget(optionsArg.store, journal, selector);
   const publishResult = await publishNpmArtifact(
     optionsArg.smartshell,
@@ -643,7 +720,13 @@ const executeNpmRegistry = async (
     artifactPath,
     registryArg,
   );
-  probe = await probeNpm(journal, registryArg, optionsArg, true);
+  probe = await probeNpm(
+    journal,
+    registryArg,
+    optionsArg,
+    !deferVerificationArg,
+    packageNameArg,
+  );
   if (probe.status === "exact") {
     return finishPublishingTarget(
       optionsArg.store,
@@ -663,7 +746,7 @@ const executeNpmRegistry = async (
     );
     throw new Error(`npm registry published conflicting bytes: ${registryArg}`);
   }
-  await finishPublishingTarget(
+  journal = await finishPublishingTarget(
     optionsArg.store,
     journal,
     selector,
@@ -672,6 +755,7 @@ const executeNpmRegistry = async (
       ? "verification-inconclusive"
       : "command-failed",
   );
+  if (deferVerificationArg && publishResult.exitCode === 0) return journal;
   throw new Error(`npm publication could not be verified: ${registryArg}`);
 };
 
@@ -1346,6 +1430,13 @@ export const executeReleasePublication = async (
   optionsArg: IReleasePublicationOptions,
 ): Promise<TReleaseJournal> => {
   let journal = optionsArg.journal;
+  // Validate the whole stored set before Git or any registry can change.
+  for (const artifact of getReleaseArtifacts(journal)) {
+    await verifyStoredNpmArtifact(
+      optionsArg.store.getArtifactPath(journal.release.version, artifact.file),
+      artifact,
+    );
+  }
   if (journal.schemaVersion === 2) {
     journal = await executeDockerQualification(optionsArg, journal);
     if (
@@ -1362,7 +1453,31 @@ export const executeReleasePublication = async (
       : journal.git.expectedRemoteMainOid || undefined;
   for (const registry of journal.npm.registries) {
     await optionsArg.ensurePublicationState(expectedRemoteMainOid);
-    journal = await executeNpmRegistry(optionsArg, journal, registry.registry);
+    journal = await executeNpmRegistry(
+      optionsArg,
+      journal,
+      registry.registry,
+      registry.packageName,
+      journal.schemaVersion === 3,
+    );
+  }
+  // Submit in dependency order before waiting for npm's publish-time scans.
+  // Success still requires every package/registry cell to verify exactly.
+  if (journal.schemaVersion === 3) {
+    for (const registry of journal.npm.registries) {
+      if (
+        registry.state !== "failed" ||
+        registry.error !== "verification-inconclusive"
+      )
+        continue;
+      await optionsArg.ensurePublicationState(expectedRemoteMainOid);
+      journal = await executeNpmRegistry(
+        optionsArg,
+        journal,
+        registry.registry,
+        registry.packageName,
+      );
+    }
   }
   if (
     journal.schemaVersion === 2 &&