@git.zone/cli 5.0.0 → 6.0.0

package/ts/mod_release/helpers.npmartifact.ts

@@ -0,0 +1,553 @@
+import * as plugins from "./mod.plugins.js";
+import {
+  releaseArtifactFileName,
+  type IReleaseArtifact,
+} from "./classes.releasejournal.js";
+import { assertCredentialFreeGitPushDestination } from "./helpers.releasebranch.js";
+
+const supportedPnpmVersion = "11.21.0";
+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._-]*)$/;
+
+export interface IPnpmReleaseCapability {
+  version: typeof supportedPnpmVersion;
+}
+
+export type TNpmArtifactProbeStatus =
+  | "absent"
+  | "exact"
+  | "conflict"
+  | "inconclusive";
+
+export interface INpmArtifactProbeResult {
+  status: TNpmArtifactProbeStatus;
+  code:
+    | "absent"
+    | "exact"
+    | "metadata-conflict"
+    | "tarball-conflict"
+    | "tag-conflict"
+    | "registry-response"
+    | "network-error";
+}
+
+export interface INpmArtifactProbeOptions {
+  fetchImplementation?: typeof fetch;
+  timeoutMs?: number;
+  attempts?: number;
+  delayMs?: number;
+}
+
+const readPackageIdentity = async (
+  cwdArg: string,
+): Promise<{ packageName: string; version: string }> => {
+  let packageJson: unknown;
+  try {
+    packageJson = JSON.parse(
+      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.", {
+      cause: error,
+    });
+  }
+  if (
+    typeof packageJson !== "object" ||
+    packageJson === null ||
+    Array.isArray(packageJson) ||
+    typeof (packageJson as { name?: unknown }).name !== "string" ||
+    !packageNameRegex.test((packageJson as { name: string }).name) ||
+    typeof (packageJson as { version?: unknown }).version !== "string"
+  ) {
+    throw new Error("package.json requires a canonical npm name and version.");
+  }
+  return {
+    packageName: (packageJson as { name: string }).name,
+    version: (packageJson as { version: string }).version,
+  };
+};
+
+const requireHelpFragments = (
+  outputArg: string,
+  fragmentsArg: string[],
+  commandArg: string,
+): void => {
+  const missing = fragmentsArg.filter((fragmentArg) => !outputArg.includes(fragmentArg));
+  if (missing.length > 0) {
+    throw new Error(
+      `pnpm ${commandArg} is missing required exact-release capabilities: ${missing.join(", ")}.`,
+    );
+  }
+};
+
+export const assertPnpmReleaseCapability = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+): Promise<IPnpmReleaseCapability> => {
+  const versionResult = await smartshellArg.execSpawn("pnpm", ["--version"], {
+    cwd: cwdArg,
+    silent: true,
+    timeout: capabilityCommandTimeoutMs,
+    timeoutKillGraceMs: 5_000,
+  });
+  const version = versionResult.stdout.trim();
+  if (versionResult.exitCode !== 0 || version !== supportedPnpmVersion) {
+    throw new Error(
+      `Exact release packaging requires the verified pnpm ${supportedPnpmVersion}; resolved ${version || "unknown"}.`,
+    );
+  }
+
+  const packHelp = await smartshellArg.execSpawn("pnpm", ["pack", "--help"], {
+    cwd: cwdArg,
+    silent: true,
+    timeout: capabilityCommandTimeoutMs,
+    timeoutKillGraceMs: 5_000,
+  });
+  if (packHelp.exitCode !== 0) {
+    throw new Error("Unable to inspect pnpm pack capabilities.");
+  }
+  requireHelpFragments(packHelp.combinedOutput, ["--out <path>", "--json"], "pack");
+
+  const publishHelp = await smartshellArg.execSpawn(
+    "pnpm",
+    ["publish", "--help"],
+    {
+      cwd: cwdArg,
+      silent: true,
+      timeout: capabilityCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  if (publishHelp.exitCode !== 0) {
+    throw new Error("Unable to inspect pnpm publish capabilities.");
+  }
+  requireHelpFragments(
+    publishHelp.combinedOutput,
+    [
+      "publish [<tarball>|<dir>]",
+      "--no-git-checks",
+      "--ignore-scripts",
+      "--json",
+      "--tag <tag>",
+      "--access <public|restricted>",
+    ],
+    "publish",
+  );
+  return { version: supportedPnpmVersion };
+};
+
+const legacyPublishWorkflowPaths = [
+  ".gitea/workflows/default_tags.yaml",
+  ".gitlab-ci.yml",
+] as const;
+
+export const assertNoLegacyNpmPublisher = async (cwdArg: string): Promise<void> => {
+  for (const relativePath of legacyPublishWorkflowPaths) {
+    const filePath = plugins.path.join(cwdArg, relativePath);
+    let content: string;
+    try {
+      content = await plugins.fs.readFile(filePath, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        continue;
+      }
+      throw new Error(`Unable to inspect ${relativePath} for legacy npm publication.`, {
+        cause: error,
+      });
+    }
+    const activeContent = content
+      .split("\n")
+      .filter((lineArg) => !/^\s*#/.test(lineArg))
+      .join("\n");
+    if (/\bnpmci\s+npm\s+publish\b/.test(activeContent)) {
+      throw new Error(
+        `${relativePath} still contains the legacy independent npm publisher. ` +
+          "Remove it or apply the Gitzone v6 Gitea workflow template, then commit the workflow change before releasing.",
+      );
+    }
+  }
+};
+
+export const normalizeNpmRegistryUrl = (valueArg: string): string => {
+  if (typeof valueArg !== "string" || !valueArg.trim()) {
+    throw new Error("npm registry URLs must be non-empty strings.");
+  }
+  let url: URL;
+  try {
+    url = new URL(valueArg.trim());
+  } catch (error) {
+    throw new Error("Invalid npm registry URL.", { cause: error });
+  }
+  if (
+    (url.protocol !== "https:" && url.protocol !== "http:") ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error(
+      "npm registry URLs must use credential-free http(s) without query strings or fragments.",
+    );
+  }
+  const pathname = url.pathname.replace(/\/+$/, "");
+  return `${url.origin}${pathname}`;
+};
+
+export const hashReleaseDestination = (valueArg: string): string => {
+  assertCredentialFreeGitPushDestination(valueArg);
+  return plugins.crypto.createHash("sha256").update(valueArg).digest("hex");
+};
+
+export const calculateNpmArtifact = async (
+  artifactPathArg: string,
+  packageNameArg: string,
+  versionArg: string,
+): Promise<IReleaseArtifact> => {
+  const stat = await plugins.fs.lstat(artifactPathArg);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0) {
+    throw new Error("Release npm artifact must be a non-empty regular file.");
+  }
+  const bytes = await plugins.fs.readFile(artifactPathArg);
+  return {
+    kind: "npm-tarball",
+    file: releaseArtifactFileName,
+    packageName: packageNameArg,
+    version: versionArg,
+    size: bytes.byteLength,
+    sha1: plugins.crypto.createHash("sha1").update(bytes).digest("hex"),
+    sha256: plugins.crypto.createHash("sha256").update(bytes).digest("hex"),
+    integrity: `sha512-${plugins.crypto.createHash("sha512").update(bytes).digest("base64")}`,
+  };
+};
+
+const syncFile = async (filePathArg: string): Promise<void> => {
+  const handle = await plugins.fs.open(filePathArg, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+
+export const packNpmArtifact = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  destinationDirectoryArg: string,
+  expectedVersionArg: string,
+): Promise<IReleaseArtifact> => {
+  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 result = await smartshellArg.execSpawn(
+    "pnpm",
+    ["pack", "--out", artifactPath, "--json"],
+    {
+      cwd: cwdArg,
+      timeout: packCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  if (result.exitCode !== 0) {
+    throw new Error("pnpm pack failed while creating the exact release artifact.");
+  }
+  let report: unknown;
+  try {
+    report = JSON.parse(result.stdout.trim());
+  } catch (error) {
+    throw new Error("pnpm pack did not return its required JSON report.", {
+      cause: error,
+    });
+  }
+  if (
+    typeof report !== "object" ||
+    report === null ||
+    Array.isArray(report) ||
+    (report as { name?: unknown }).name !== identity.packageName ||
+    (report as { version?: unknown }).version !== identity.version
+  ) {
+    throw new Error("pnpm pack reported a different package identity.");
+  }
+  await syncFile(artifactPath);
+  return calculateNpmArtifact(
+    artifactPath,
+    identity.packageName,
+    identity.version,
+  );
+};
+
+export const verifyStoredNpmArtifact = async (
+  artifactPathArg: string,
+  expectedArtifactArg: IReleaseArtifact,
+): Promise<void> => {
+  const actual = await calculateNpmArtifact(
+    artifactPathArg,
+    expectedArtifactArg.packageName,
+    expectedArtifactArg.version,
+  );
+  if (
+    actual.size !== expectedArtifactArg.size ||
+    actual.sha1 !== expectedArtifactArg.sha1 ||
+    actual.sha256 !== expectedArtifactArg.sha256 ||
+    actual.integrity !== expectedArtifactArg.integrity
+  ) {
+    throw new Error("Stored npm artifact no longer matches its release journal identity.");
+  }
+};
+
+export const buildPnpmPublishArgs = (
+  artifactPathArg: string,
+  registryArg: string,
+): string[] => [
+  "publish",
+  artifactPathArg,
+  `--registry=${normalizeNpmRegistryUrl(registryArg)}`,
+  "--access=public",
+  "--tag=latest",
+  "--no-git-checks",
+  "--ignore-scripts",
+  "--json",
+];
+
+export const publishNpmArtifact = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  cwdArg: string,
+  artifactPathArg: string,
+  registryArg: string,
+): Promise<{ exitCode: number; output: string }> => {
+  const result = await smartshellArg.execSpawn(
+    "pnpm",
+    buildPnpmPublishArgs(artifactPathArg, registryArg),
+    {
+      cwd: cwdArg,
+      timeout: publishCommandTimeoutMs,
+      timeoutKillGraceMs: 5_000,
+    },
+  );
+  return { exitCode: result.exitCode, output: result.combinedOutput };
+};
+
+const getFetch = (optionsArg: INpmArtifactProbeOptions): typeof fetch =>
+  optionsArg.fetchImplementation || globalThis.fetch;
+
+const fetchWithoutRedirects = async (
+  urlArg: URL,
+  acceptArg: string,
+  optionsArg: INpmArtifactProbeOptions,
+): Promise<Response> => {
+  const timeoutMs = optionsArg.timeoutMs ?? 10_000;
+  return getFetch(optionsArg)(urlArg, {
+    method: "GET",
+    headers: { accept: acceptArg },
+    redirect: "manual",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+};
+
+const cancelResponseBody = (responseArg: Response): void => {
+  if (responseArg.body && !responseArg.body.locked) {
+    void responseArg.body.cancel().catch(() => {});
+  }
+};
+
+const readBoundedResponse = async (
+  responseArg: Response,
+  maximumSizeArg: number,
+  contextArg: string,
+): Promise<Buffer> => {
+  const contentLength = responseArg.headers.get("content-length");
+  if (
+    contentLength &&
+    (!/^\d+$/.test(contentLength) || Number(contentLength) > maximumSizeArg)
+  ) {
+    cancelResponseBody(responseArg);
+    throw new Error(`${contextArg} exceeds its maximum response size.`);
+  }
+  if (!responseArg.body) {
+    throw new Error(`${contextArg} response has no body.`);
+  }
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  const reader = responseArg.body.getReader();
+  let complete = false;
+  try {
+    while (true) {
+      const item = await reader.read();
+      if (item.done) {
+        complete = true;
+        break;
+      }
+      size += item.value.byteLength;
+      if (size > maximumSizeArg) {
+        throw new Error(`${contextArg} exceeds its maximum response size.`);
+      }
+      chunks.push(item.value);
+    }
+  } finally {
+    if (!complete) {
+      void reader.cancel().catch(() => {});
+    }
+    reader.releaseLock();
+  }
+  return Buffer.concat(chunks.map((chunkArg) => Buffer.from(chunkArg)), size);
+};
+
+const readBoundedJsonResponse = async (responseArg: Response): Promise<unknown> =>
+  JSON.parse(
+    (
+      await readBoundedResponse(
+        responseArg,
+        maximumMetadataResponseBytes,
+        "Registry metadata",
+      )
+    ).toString("utf8"),
+  );
+
+const getMetadataUrl = (
+  registryArg: string,
+  packageNameArg: string,
+  versionArg?: string,
+): URL => {
+  const encodedPackage = encodeURIComponent(packageNameArg);
+  return new URL(
+    versionArg
+      ? `${normalizeNpmRegistryUrl(registryArg)}/${encodedPackage}/${encodeURIComponent(versionArg)}`
+      : `${normalizeNpmRegistryUrl(registryArg)}/${encodedPackage}`,
+  );
+};
+
+export const probeAnonymousNpmArtifact = async (
+  registryArg: string,
+  artifactArg: IReleaseArtifact,
+  tagArg = "latest",
+  optionsArg: INpmArtifactProbeOptions = {},
+): Promise<INpmArtifactProbeResult> => {
+  const registry = normalizeNpmRegistryUrl(registryArg);
+  try {
+    const versionResponse = await fetchWithoutRedirects(
+      getMetadataUrl(registry, artifactArg.packageName, artifactArg.version),
+      "application/json",
+      optionsArg,
+    );
+    if (versionResponse.status === 404) {
+      cancelResponseBody(versionResponse);
+      return { status: "absent", code: "absent" };
+    }
+    if (versionResponse.status !== 200) {
+      cancelResponseBody(versionResponse);
+      return { status: "inconclusive", code: "registry-response" };
+    }
+    const metadata = (await readBoundedJsonResponse(versionResponse)) as {
+      name?: unknown;
+      version?: unknown;
+      dist?: { integrity?: unknown; shasum?: unknown; tarball?: unknown };
+    };
+    if (
+      metadata.name !== artifactArg.packageName ||
+      metadata.version !== artifactArg.version ||
+      metadata.dist?.integrity !== artifactArg.integrity ||
+      metadata.dist?.shasum !== artifactArg.sha1 ||
+      typeof metadata.dist?.tarball !== "string"
+    ) {
+      return { status: "conflict", code: "metadata-conflict" };
+    }
+
+    const tarballUrl = new URL(metadata.dist.tarball);
+    const registryUrl = new URL(registry);
+    if (
+      tarballUrl.origin !== registryUrl.origin ||
+      (tarballUrl.protocol !== "https:" && tarballUrl.protocol !== "http:") ||
+      tarballUrl.username ||
+      tarballUrl.password ||
+      tarballUrl.search ||
+      tarballUrl.hash
+    ) {
+      return { status: "conflict", code: "metadata-conflict" };
+    }
+    const tarballResponse = await fetchWithoutRedirects(
+      tarballUrl,
+      "application/octet-stream",
+      optionsArg,
+    );
+    if (tarballResponse.status !== 200) {
+      cancelResponseBody(tarballResponse);
+      return { status: "inconclusive", code: "registry-response" };
+    }
+    const bytes = await readBoundedResponse(
+      tarballResponse,
+      artifactArg.size,
+      "Registry tarball",
+    );
+    if (
+      bytes.byteLength !== artifactArg.size ||
+      plugins.crypto.createHash("sha1").update(bytes).digest("hex") !==
+        artifactArg.sha1 ||
+      plugins.crypto.createHash("sha256").update(bytes).digest("hex") !==
+        artifactArg.sha256 ||
+      `sha512-${plugins.crypto.createHash("sha512").update(bytes).digest("base64")}` !==
+        artifactArg.integrity
+    ) {
+      return { status: "conflict", code: "tarball-conflict" };
+    }
+
+    const packageResponse = await fetchWithoutRedirects(
+      getMetadataUrl(registry, artifactArg.packageName),
+      "application/json",
+      optionsArg,
+    );
+    if (packageResponse.status !== 200) {
+      cancelResponseBody(packageResponse);
+      return { status: "inconclusive", code: "registry-response" };
+    }
+    const packageMetadata = (await readBoundedJsonResponse(packageResponse)) as {
+      ["dist-tags"]?: Record<string, unknown>;
+    };
+    if (packageMetadata["dist-tags"]?.[tagArg] !== artifactArg.version) {
+      return { status: "inconclusive", code: "tag-conflict" };
+    }
+    return { status: "exact", code: "exact" };
+  } catch {
+    return { status: "inconclusive", code: "network-error" };
+  }
+};
+
+export const waitForAnonymousNpmArtifact = async (
+  registryArg: string,
+  artifactArg: IReleaseArtifact,
+  tagArg = "latest",
+  optionsArg: INpmArtifactProbeOptions = {},
+): Promise<INpmArtifactProbeResult> => {
+  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.");
+  }
+  let lastResult: INpmArtifactProbeResult = {
+    status: "inconclusive",
+    code: "network-error",
+  };
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    lastResult = await probeAnonymousNpmArtifact(
+      registryArg,
+      artifactArg,
+      tagArg,
+      optionsArg,
+    );
+    if (lastResult.status === "exact" || lastResult.status === "conflict") {
+      return lastResult;
+    }
+    if (attempt + 1 < attempts) {
+      await plugins.smartdelay.delayFor(delayMs);
+    }
+  }
+  return lastResult;
+};

package/ts/mod_release/helpers.releasebranch.ts

@@ -49,6 +49,65 @@ export const releaseGitEnv: NodeJS.ProcessEnv = {
   GIT_NO_REPLACE_OBJECTS: "1",
 };
 
+export const assertCredentialFreeGitPushDestination = (
+  valueArg: string,
+): void => {
+  if (
+    !valueArg ||
+    valueArg.trim() !== valueArg ||
+    /[\u0000-\u001f\u007f]/.test(valueArg)
+  ) {
+    throw new Error("Git push destinations must be non-empty canonical strings.");
+  }
+  if (
+    plugins.path.isAbsolute(valueArg) ||
+    /^[A-Za-z]:[\\/]/.test(valueArg) ||
+    valueArg.startsWith("./") ||
+    valueArg.startsWith("../") ||
+    valueArg.startsWith("~/")
+  ) {
+    return;
+  }
+  if (/^[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:.+$/.test(valueArg)) {
+    return;
+  }
+
+  let url: URL;
+  try {
+    url = new URL(valueArg);
+  } catch (error) {
+    if (/^[A-Za-z0-9._/-]+$/.test(valueArg)) {
+      return;
+    }
+    throw new Error("Git push destination syntax is unsupported.", {
+      cause: error,
+    });
+  }
+  const sshProtocol =
+    url.protocol === "ssh:" ||
+    url.protocol === "git+ssh:" ||
+    url.protocol === "ssh+git:";
+  if (
+    !sshProtocol &&
+    url.protocol !== "https:" &&
+    url.protocol !== "http:" &&
+    url.protocol !== "git:" &&
+    url.protocol !== "file:"
+  ) {
+    throw new Error("Git push destination protocol is unsupported.");
+  }
+  if (
+    url.password ||
+    url.search ||
+    url.hash ||
+    (!sshProtocol && url.username)
+  ) {
+    throw new Error(
+      "Git push destinations must not contain embedded credentials or parameters.",
+    );
+  }
+};
+
 const readOnlyGitEnv: NodeJS.ProcessEnv = {
   ...releaseGitEnv,
   GIT_NO_LAZY_FETCH: "1",
@@ -116,6 +175,9 @@ const runGit = async (
     cwd: cwdArg,
     env: readOnlyArg ? readOnlyGitEnv : releaseGitEnv,
     silent: true,
+    timeout:
+      argsArg[0] === "fetch" || argsArg[0] === "push" ? 5 * 60_000 : 60_000,
+    timeoutKillGraceMs: 5_000,
   });
 
 const requireGitSuccess = (
@@ -365,15 +427,15 @@ const resolvePushUrl = async (
   const hasUrlScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(pushUrl);
   const isScpStyle = /^(?:[^@/\\:]+@)?[^/\\:]+:.+/.test(pushUrl);
   const isWindowsAbsolutePath = /^[a-z]:[\\/]/i.test(pushUrl);
-  if (
+  const resolvedPushUrl =
     !hasUrlScheme &&
     !isScpStyle &&
     !plugins.path.isAbsolute(pushUrl) &&
     !isWindowsAbsolutePath
-  ) {
-    return plugins.path.resolve(cwdArg, pushUrl);
-  }
-  return pushUrl;
+      ? plugins.path.resolve(cwdArg, pushUrl)
+      : pushUrl;
+  assertCredentialFreeGitPushDestination(resolvedPushUrl);
+  return resolvedPushUrl;
 };
 
 const resolveRemoteMainOid = async (