@git.zone/cli 6.7.2 → 6.8.0

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/index.ts

@@ -51,6 +51,11 @@ import {
   verifyStoredNpmArtifact,
 } from "./helpers.npmartifact.js";
 import { executeReleasePublication } from "./helpers.releasepublication.js";
+import {
+  assertPackageReleaseRecovery,
+  assertRecoveryUnpublished,
+  withReleasePreparationRecovery,
+} from "./helpers.releasepreparation.js";
 import {
   TsdockerReleaseClient,
   canonicalReleaseJson,
@@ -87,6 +92,10 @@ const runInternal = async (argvArg: any): Promise<void> => {
     await runReleaseResume(argvArg, mode);
     return;
   }
+  if (subcommand === "recover") {
+    await runReleaseRecover(argvArg, mode);
+    return;
+  }
   if (subcommand !== undefined) {
     throw new Error(`Unknown release subcommand: ${subcommand}`);
   }
@@ -402,6 +411,8 @@ interface ICreateReleaseJournalOptions {
   smartshell: plugins.smartshell.Smartshell;
   workflow: IResolvedReleaseWorkflow;
   releaseCwd: string;
+  /** Exact detached checkout used only while recovering pre-journal packaging. */
+  npmSourceCwd?: string;
   releasePushUrl?: string;
   expectedRemoteMainOid?: string;
   version: string;
@@ -447,6 +458,7 @@ export const planReleasePackages = async (
 export const createReleaseJournal = async (
   optionsArg: ICreateReleaseJournalOptions,
 ): Promise<{ store: ReleaseJournalStore; journal: TReleaseJournal }> => {
+  const npmSourceCwd = optionsArg.npmSourceCwd ?? optionsArg.releaseCwd;
   const gitCommonDirectory = await resolveGitCommonDirectory(
     optionsArg.smartshell,
     optionsArg.releaseCwd,
@@ -474,7 +486,7 @@ export const createReleaseJournal = async (
     const packages: IReleasePackage[] = [];
     if (optionsArg.workflow.targets.includes("npm")) {
       if (optionsArg.workflow.npmPackageSource === "tspublish") {
-        const plan = await planReleasePackages(optionsArg.releaseCwd);
+        const plan = await planReleasePackages(npmSourceCwd);
         if (plan.version !== optionsArg.version)
           throw new Error("tspublish plan version differs from the release.");
         const outputDirectory = plugins.path.join(
@@ -482,7 +494,7 @@ export const createReleaseJournal = async (
           "prepared",
         );
         const prepared = await new plugins.tspublish.TsPublish().prepare(
-          optionsArg.releaseCwd,
+          npmSourceCwd,
           outputDirectory,
         );
         if (
@@ -509,14 +521,14 @@ export const createReleaseJournal = async (
       } else {
         artifact = await packNpmArtifact(
           optionsArg.smartshell,
-          optionsArg.releaseCwd,
+          npmSourceCwd,
           temporaryDirectory,
           optionsArg.version,
         );
       }
       await verifyCleanTree(
         optionsArg.smartshell,
-        optionsArg.releaseCwd,
+        npmSourceCwd,
         "npm pack lifecycle scripts changed the release worktree. Aborting release.",
       );
       await optionsArg.ensurePublicationState();
@@ -650,6 +662,153 @@ const runReleaseInspect = async (
   }
 };
 
+const runReleaseRecover = async (
+  argvArg: any,
+  mode: ICliMode,
+): Promise<void> => {
+  const allowed = new Set([
+    "_",
+    "$0",
+    "y",
+    "yes",
+    "plan",
+    "h",
+    "help",
+    "plain",
+    "quiet",
+    "agent",
+    "interactive",
+    "check-updates",
+    "checkUpdates",
+  ]);
+  if (
+    argvArg._?.length !== 3 ||
+    Object.keys(argvArg).some((key) => !allowed.has(key)) ||
+    (argvArg.plan !== undefined && typeof argvArg.plan !== "boolean")
+  ) {
+    throw new Error(
+      "Usage: gitzone release recover <version> [-y|--plan]. Target, version, build and test overrides are not allowed.",
+    );
+  }
+  const version = normalizeReleaseVersion(argvArg._[2]);
+  const shell = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const store = new ReleaseJournalStore(
+    await resolveGitCommonDirectory(shell, paths.cwd),
+  );
+  const existing = await plugins.fs
+    .lstat(store.getReleaseDirectory(version))
+    .then(() => true)
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    });
+  if (existing) {
+    if (argvArg.plan) {
+      printReleaseJournalSummary(await store.read(version));
+      return;
+    }
+    await runReleaseResume(
+      { _: ["release", "resume", version], yes: mode.yes },
+      mode,
+    );
+    return;
+  }
+  const workflow = await resolveReleaseWorkflow({ yes: true });
+  assertReleaseConfiguration(workflow, false);
+  let branch = await inspectReleaseBranch({
+    smartshell: shell,
+    cwd: paths.cwd,
+    gitRemote: workflow.gitRemote,
+    gitTargetActive: true,
+    pushBranch: workflow.pushBranch,
+    pushTags: workflow.pushTags,
+    mergeRequested: false,
+    planMode: argvArg.plan === true,
+  });
+  const refs = await captureReleaseRefs(
+    shell,
+    paths.cwd,
+    version,
+    branch.sourceOid,
+  );
+  const options = { smartshell: shell, workflow, branch, refs, version, store };
+  const packageName = await assertPackageReleaseRecovery(options);
+  if (!branch.planAncestryVerified) {
+    console.log(
+      "Remote ancestry is deferred until execution fetches the missing commit.",
+    );
+  }
+  console.log(
+    `Recover existing ${packageName}@${version}\ncommit: ${refs.mainOid}\ntag object: ${refs.tagOid}\nGit destination: ${branch.gitRemote}\nnpm registries: ${workflow.npmRegistries.join(", ")}\nBuild and pack an isolated checkout, install its journal, then publish configured targets.`,
+  );
+  if (argvArg.plan) return;
+  await assertFreshReleaseCapabilities(
+    shell,
+    workflow,
+    paths.cwd,
+    branch.pushUrl,
+  );
+  if (!mode.yes) {
+    if (!mode.interactive)
+      throw new Error(
+        "Release recovery requires an interactive terminal or -y.",
+      );
+    if (
+      !(await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        `Recover and publish existing v${version}?`,
+        false,
+      ))
+    )
+      return;
+  }
+  branch = await prepareReleaseIntegration(shell, branch);
+  options.branch = branch;
+  const ensureState = async (remote = branch.remoteMainOid) => {
+    await verifyReleaseRefs(shell, paths.cwd, version, refs);
+    await revalidateReleasePublicationState(
+      shell,
+      branch,
+      refs.mainOid,
+      remote,
+    );
+  };
+  const ensureUnpublished = async () => {
+    await ensureState();
+    await assertRecoveryUnpublished(options, packageName);
+  };
+  const context = await withReleasePreparationRecovery(
+    options,
+    ensureUnpublished,
+    async (checkout, ensureCheckout) =>
+      createReleaseJournal({
+        smartshell: shell,
+        workflow,
+        releaseCwd: paths.cwd,
+        npmSourceCwd: checkout,
+        releasePushUrl: branch.pushUrl,
+        expectedRemoteMainOid: branch.remoteMainOid,
+        version,
+        refs,
+        ensurePublicationState: async () => {
+          await ensureCheckout();
+          await ensureUnpublished();
+        },
+      }),
+  );
+  const result = await executeReleasePublication({
+    smartshell: shell,
+    cwd: paths.cwd,
+    store: context.store,
+    journal: context.journal,
+    pushUrl: branch.pushUrl,
+    ensurePublicationState: ensureState,
+  });
+  printReleaseJournalSummary(result);
+};
+
 const assertResumeArguments = (argvArg: any): void => {
   const forbiddenKeys = [
     "allow-empty",
@@ -1284,7 +1443,8 @@ export function showHelp(mode?: ICliMode): void {
   if (mode?.json) {
     printJson({
       command: "release",
-      usage: "gitzone release [inspect [version]|resume <version>] [options]",
+      usage:
+        "gitzone release [inspect [version]|resume <version>|recover <version>] [options]",
       description:
         "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
       flags: [
@@ -1338,6 +1498,11 @@ export function showHelp(mode?: ICliMode): void {
           description:
             "Resume exact journaled publication without rebuilding or repacking npm artifacts",
         },
+        {
+          flag: "recover <version>",
+          description:
+            "Recover a local root npm release tag after build or pack failure before journal creation",
+        },
         {
           flag: "--recover-attempt <id>",
           description:
@@ -1350,7 +1515,7 @@ export function showHelp(mode?: ICliMode): void {
 
   console.log("");
   console.log(
-    "Usage: gitzone release [inspect [version]|resume <version>] [options]",
+    "Usage: gitzone release [inspect [version]|resume <version>|recover <version>] [options]",
   );
   console.log("");
   console.log("Creates a versioned release from changelog Pending entries.");
@@ -1386,6 +1551,9 @@ export function showHelp(mode?: ICliMode): void {
   console.log(
     "  resume <version>    Resume exact journaled publication without rebuilding or repacking npm artifacts",
   );
+  console.log(
+    "  recover <version>   Recover an unpublished root npm release from its existing local tag",
+  );
   console.log(
     "  --recover-attempt   Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
   );