@git.zone/cli 6.7.3 → 6.9.0

package/ts/mod_release/helpers.npmartifact.ts

@@ -9,6 +9,7 @@ const supportedPnpmVersions = [
   "11.25.0",
   "12.1.0",
   "12.2.1",
+  "12.3.0",
   "12.3.4",
 ] as const;
 const pnpmHelpRequirements = {
@@ -49,6 +50,19 @@ const pnpmHelpRequirements = {
       "[possible values: public, restricted]",
     ],
   },
+  "12.3.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.3.4": {
     pack: ["Usage: pnpm pack [OPTIONS]", "--out <OUT>", "--json"],
     publish: [
@@ -70,10 +84,31 @@ 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._-]*)$/;
 
+export function assertNpmPackageName(value: unknown): asserts value is string {
+  if (typeof value !== "string" || !packageNameRegex.test(value)) {
+    throw new Error("Invalid release package name.");
+  }
+}
+
 export interface IPnpmReleaseCapability {
-  version: (typeof supportedPnpmVersions)[number];
+  readonly version: (typeof supportedPnpmVersions)[number];
 }
 
+export const buildQualifiedPnpmArgs = (
+  capabilityArg: IPnpmReleaseCapability | undefined,
+  argsArg: readonly string[],
+): string[] => {
+  if (
+    !capabilityArg ||
+    !supportedPnpmVersions.includes(capabilityArg.version)
+  ) {
+    throw new Error(
+      "npm release commands require a qualified pnpm invocation.",
+    );
+  }
+  return ["with", capabilityArg.version, ...argsArg];
+};
+
 export type TNpmArtifactProbeStatus =
   "absent" | "exact" | "conflict" | "inconclusive";
 
@@ -163,21 +198,28 @@ export const assertPnpmReleaseCapability = async (
     );
   }
   const requirements = pnpmHelpRequirements[supportedVersion];
+  const capability = Object.freeze({ version: supportedVersion });
 
-  const packHelp = await smartshellArg.execSpawn("pnpm", ["pack", "--help"], {
-    cwd: cwdArg,
-    silent: true,
-    timeout: capabilityCommandTimeoutMs,
-    timeoutKillGraceMs: 5_000,
-  });
+  const packHelp = await smartshellArg.execSpawn(
+    "pnpm",
+    buildQualifiedPnpmArgs(capability, ["pack", "--help"]),
+    {
+      cwd: cwdArg,
+      silent: true,
+      timeout: capabilityCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
   if (packHelp.exitCode !== 0) {
-    throw new Error("Unable to inspect pnpm pack capabilities.");
+    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");
 
   const publishHelp = await smartshellArg.execSpawn(
     "pnpm",
-    ["publish", "--help"],
+    buildQualifiedPnpmArgs(capability, ["publish", "--help"]),
     {
       cwd: cwdArg,
       silent: true,
@@ -193,7 +235,7 @@ export const assertPnpmReleaseCapability = async (
     requirements.publish,
     "publish",
   );
-  return { version: supportedVersion };
+  return capability;
 };
 
 /**
@@ -352,6 +394,7 @@ export const packNpmArtifact = async (
   cwdArg: string,
   destinationDirectoryArg: string,
   expectedVersionArg: string,
+  capabilityArg: IPnpmReleaseCapability | undefined,
   fileArg: string = releaseArtifactFileName,
 ): Promise<IReleaseArtifact> => {
   if (
@@ -369,7 +412,12 @@ export const packNpmArtifact = async (
   const artifactPath = plugins.path.join(destinationDirectoryArg, fileArg);
   const result = await smartshellArg.execSpawn(
     "pnpm",
-    ["pack", "--out", artifactPath, "--json"],
+    buildQualifiedPnpmArgs(capabilityArg, [
+      "pack",
+      "--out",
+      artifactPath,
+      "--json",
+    ]),
     {
       cwd: cwdArg,
       timeout: packCommandTimeoutMs,
@@ -464,10 +512,14 @@ export const publishNpmArtifact = async (
   cwdArg: string,
   artifactPathArg: string,
   registryArg: string,
+  capabilityArg: IPnpmReleaseCapability | undefined,
 ): Promise<{ exitCode: number; output: string }> => {
   const result = await smartshellArg.execSpawn(
     "pnpm",
-    buildPnpmPublishArgs(artifactPathArg, registryArg),
+    buildQualifiedPnpmArgs(
+      capabilityArg,
+      buildPnpmPublishArgs(artifactPathArg, registryArg),
+    ),
     {
       cwd: cwdArg,
       timeout: publishCommandTimeoutMs,
@@ -500,6 +552,30 @@ const cancelResponseBody = (responseArg: Response): void => {
   }
 };
 
+/** Recovery without an original artifact must never adopt a published version. */
+export const assertNpmVersionAbsent = async (
+  registryArg: string,
+  packageNameArg: string,
+  versionArg: string,
+  optionsArg: INpmArtifactProbeOptions = {},
+): Promise<void> => {
+  const registry = normalizeNpmRegistryUrl(registryArg);
+  assertNpmPackageName(packageNameArg);
+  const response = await fetchWithoutRedirects(
+    new URL(
+      `${registry}/${encodeURIComponent(packageNameArg)}/${encodeURIComponent(versionArg)}`,
+    ),
+    "application/json",
+    optionsArg,
+  );
+  cancelResponseBody(response);
+  if (response.status !== 404) {
+    throw new Error(
+      `Cannot prove ${packageNameArg}@${versionArg} is unpublished at ${registry} (HTTP ${response.status}).`,
+    );
+  }
+};
+
 const readBoundedResponse = async (
   responseArg: Response,
   maximumSizeArg: number,

package/ts/mod_release/helpers.releasepreparation.ts

@@ -0,0 +1,308 @@
+import * as plugins from "./mod.plugins.js";
+import type { IResolvedReleaseWorkflow } from "../helpers.workflow.js";
+import { readPendingChangelog } from "../helpers.changelog.js";
+import { InterProcessLock } from "../mod_services/classes.interprocesslock.js";
+import { ReleaseJournalStore } from "./classes.releasejournal.js";
+import {
+  releaseGitEnv,
+  type IReleaseBranchContext,
+} from "./helpers.releasebranch.js";
+import {
+  assertNpmVersionAbsent,
+  assertNpmPackageName,
+  hashReleaseDestination,
+} from "./helpers.npmartifact.js";
+import { canonicalReleaseJson } from "./helpers.tsdockerprotocol.js";
+
+interface IRecoveryRefs {
+  mainOid: string;
+  tagOid: string;
+}
+
+export interface IReleasePreparationRecovery {
+  smartshell: plugins.smartshell.Smartshell;
+  workflow: IResolvedReleaseWorkflow;
+  branch: IReleaseBranchContext;
+  refs: IRecoveryRefs;
+  version: string;
+  store: ReleaseJournalStore;
+}
+
+const git = async (
+  options: IReleasePreparationRecovery,
+  args: string[],
+  cwd = options.branch.sourceCwd,
+) => {
+  const result = await options.smartshell.execSpawn("git", args, {
+    cwd,
+    env: releaseGitEnv,
+    silent: true,
+    timeout: 60_000,
+    timeoutKillGraceMs: 5_000,
+  });
+  if (result.exitCode !== 0)
+    throw new Error(`Release recovery Git validation failed: ${args[0]}.`);
+  return result.stdout.trim();
+};
+
+export const assertPackageReleaseRecovery = async (
+  options: IReleasePreparationRecovery,
+): Promise<string> => {
+  const { workflow, branch, version } = options;
+  if (
+    workflow.targets.length !== 2 ||
+    !workflow.targets.includes("git") ||
+    !workflow.targets.includes("npm") ||
+    workflow.npmPackageSource !== "root" ||
+    !workflow.pushBranch ||
+    !workflow.pushTags ||
+    branch.sourceBranch !== "main" ||
+    !branch.pushUrl ||
+    !branch.remoteMainOid
+  ) {
+    throw new Error(
+      "Release recover requires configured Git and root npm targets from clean main.",
+    );
+  }
+  const manifest = JSON.parse(
+    await plugins.fs.readFile(
+      plugins.path.join(branch.sourceCwd, "package.json"),
+      "utf8",
+    ),
+  );
+  if (manifest.version !== version || typeof manifest.name !== "string") {
+    throw new Error(
+      "Recovery package identity does not match the existing release version.",
+    );
+  }
+  assertNpmPackageName(manifest.name);
+  const pending = await readPendingChangelog(
+    plugins.path.join(branch.sourceCwd, workflow.changelogFile),
+    workflow.changelogPendingSection,
+  );
+  const changelog = await plugins.fs.readFile(
+    plugins.path.join(branch.sourceCwd, workflow.changelogFile),
+    "utf8",
+  );
+  const headings = changelog
+    .split(/\r?\n/)
+    .filter(
+      (line) =>
+        /^##\s/.test(line) && line !== `## ${workflow.changelogPendingSection}`,
+    );
+  if (
+    !pending.isEmpty ||
+    !new RegExp(
+      `^## \\d{4}-\\d{2}-\\d{2} - ${version.replace(/\./g, "\\.")}\\s*$`,
+    ).test(headings[0] ?? "")
+  ) {
+    throw new Error(
+      "Recovery requires the completed changelog section for this version and no Pending changes.",
+    );
+  }
+  if (
+    (await git(options, [
+      "show",
+      "-s",
+      "--format=%s",
+      options.refs.mainOid,
+    ])) !== `v${version}` ||
+    (
+      await git(options, [
+        "rev-list",
+        "--parents",
+        "-n",
+        "1",
+        options.refs.mainOid,
+      ])
+    ).split(" ").length !== 2
+  ) {
+    throw new Error("Recovery requires an existing non-merge release commit.");
+  }
+  if (
+    await git(options, [
+      "diff",
+      `${options.refs.mainOid}^`,
+      options.refs.mainOid,
+      "--",
+      ".smartconfig.json",
+    ])
+  ) {
+    throw new Error(
+      "Release configuration changed inside the release metadata commit.",
+    );
+  }
+  return manifest.name;
+};
+
+export const assertRecoveryUnpublished = async (
+  options: IReleasePreparationRecovery,
+  packageName: string,
+): Promise<void> => {
+  const output = await git(options, [
+    "ls-remote",
+    options.branch.pushUrl!,
+    `refs/tags/v${options.version}`,
+    `refs/tags/v${options.version}^{}`,
+  ]);
+  if (output)
+    throw new Error(
+      "Recovery cannot adopt an existing remote release tag. Use its original journal.",
+    );
+  for (const registry of options.workflow.npmRegistries)
+    await assertNpmVersionAbsent(registry, packageName, options.version);
+};
+
+const preparationBinding = (options: IReleasePreparationRecovery) => ({
+  kind: "gitzone-package-release-preparation",
+  schemaVersion: 1,
+  version: options.version,
+  ...options.refs,
+  destinationHash: hashReleaseDestination(options.branch.pushUrl!),
+  expectedRemoteMainOid: options.branch.remoteMainOid,
+  // Capture resolved configuration, including build/test commands, so retries
+  // cannot silently prepare a different release.
+  workflow: JSON.parse(
+    JSON.stringify({ ...options.workflow, confirmation: "auto" }),
+  ),
+});
+
+const bindPreparation = async (
+  path: string,
+  expected: string,
+): Promise<void> => {
+  try {
+    const stat = await plugins.fs.lstat(path);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.size > 128 * 1024 ||
+      (await plugins.fs.readFile(path, "utf8")) !== expected
+    ) {
+      throw new Error(
+        "Release recovery identity or configuration differs from its original preparation.",
+      );
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const handle = await plugins.fs.open(path, "wx", 0o600);
+    try {
+      await handle.writeFile(expected, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    const directory = await plugins.fs.open(plugins.path.dirname(path), "r");
+    try {
+      await directory.sync();
+    } finally {
+      await directory.close();
+    }
+  }
+};
+
+/** Build and seal one unpublished, already tagged package without changing refs. */
+export const withReleasePreparationRecovery = async <T>(
+  options: IReleasePreparationRecovery,
+  ensureState: () => Promise<void>,
+  prepare: (
+    checkout: string,
+    ensureCheckout: () => Promise<void>,
+  ) => Promise<T>,
+): Promise<T> => {
+  if (!options.branch.planAncestryVerified) {
+    throw new Error(
+      "Release recovery requires verified remote ancestry before preparation.",
+    );
+  }
+  const directory = options.store.getReleaseDirectory(options.version);
+  return new InterProcessLock({
+    lockPath: `${directory}.prepare.lock`,
+    description: `Release v${options.version} preparation`,
+  }).runExclusive(async () => {
+    await ensureState();
+    try {
+      await plugins.fs.lstat(directory);
+      throw new Error(
+        "Release journal already exists. Use release resume; do not rebuild its artifact.",
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    await bindPreparation(
+      `${directory}.preparation.json`,
+      `${canonicalReleaseJson(preparationBinding(options))}\n`,
+    );
+    const root = await plugins.fs.mkdtemp(
+      plugins.path.join(plugins.os.tmpdir(), "gitzone-release-prepare-"),
+    );
+    const checkout = plugins.path.join(root, "source");
+    let added = false;
+    try {
+      await git(options, [
+        "worktree",
+        "add",
+        "--detach",
+        checkout,
+        options.refs.mainOid,
+      ]);
+      added = true;
+      const install = await options.smartshell.execSpawn(
+        "pnpm",
+        ["install", "--frozen-lockfile"],
+        {
+          cwd: checkout,
+          timeout: 10 * 60_000,
+          timeoutKillGraceMs: 5_000,
+        },
+      );
+      if (install.exitCode !== 0)
+        throw new Error("Release recovery dependency installation failed.");
+      if (options.workflow.runTests)
+        await run(options, checkout, options.workflow.testCommand, "tests");
+      if (options.workflow.runBuild)
+        await run(options, checkout, options.workflow.buildCommand, "build");
+      await assertCheckout(options, checkout);
+      await ensureState();
+      const result = await prepare(checkout, () =>
+        assertCheckout(options, checkout),
+      );
+      await assertCheckout(options, checkout);
+      return result;
+    } finally {
+      // This path is a uniquely owned disposable checkout, never the user's
+      // source tree or runtime data. Keep registration evidence if cleanup fails.
+      if (added)
+        await git(options, ["worktree", "remove", "--force", checkout]);
+      await plugins.fs.rm(root, { recursive: true, force: true });
+    }
+  });
+};
+
+const run = async (
+  options: IReleasePreparationRecovery,
+  cwd: string,
+  command: string,
+  phase: string,
+) => {
+  const result = await options.smartshell.exec(command, { cwd });
+  if (result.exitCode !== 0)
+    throw new Error(`Release recovery ${phase} failed.`);
+};
+
+const assertCheckout = async (
+  options: IReleasePreparationRecovery,
+  checkout: string,
+) => {
+  if (
+    (await git(options, ["rev-parse", "HEAD"], checkout)) !==
+      options.refs.mainOid ||
+    (await git(
+      options,
+      ["status", "--porcelain", "--untracked-files=all"],
+      checkout,
+    ))
+  ) {
+    throw new Error("Release recovery build changed its exact tracked source.");
+  }
+};

package/ts/mod_release/helpers.releasepublication.ts

@@ -18,6 +18,8 @@ import {
   publishNpmArtifact,
   verifyStoredNpmArtifact,
   waitForAnonymousNpmArtifact,
+  buildQualifiedPnpmArgs,
+  type IPnpmReleaseCapability,
   type INpmArtifactProbeOptions,
   type INpmArtifactProbeResult,
 } from "./helpers.npmartifact.js";
@@ -85,6 +87,7 @@ interface IGitProbeResult {
 }
 
 export interface IReleasePublicationOptions {
+  pnpmCapability?: IPnpmReleaseCapability;
   smartshell: plugins.smartshell.Smartshell;
   cwd: string;
   store: ReleaseJournalStore;
@@ -713,12 +716,15 @@ const executeNpmRegistry = async (
     artifact.file,
   );
   await verifyStoredNpmArtifact(artifactPath, artifact);
+  // Reject a missing invocation before claiming a potentially publishing target.
+  buildQualifiedPnpmArgs(optionsArg.pnpmCapability, []);
   journal = await claimTarget(optionsArg.store, journal, selector);
   const publishResult = await publishNpmArtifact(
     optionsArg.smartshell,
     optionsArg.cwd,
     artifactPath,
     registryArg,
+    optionsArg.pnpmCapability,
   );
   probe = await probeNpm(
     journal,