@git.zone/cli 5.0.0 → 6.0.0

package/ts/mod_release/index.ts

@@ -9,15 +9,12 @@ import {
   readPendingChangelog,
 } from "../helpers.changelog.js";
 import {
-  formatTsdockerMinimumVersion,
-  getDeclaredTsdockerRange,
-  getTsdockerMinimumVersion,
   resolveReleaseWorkflow,
-  supportsTsdockerMinimumVersion,
+  resolveReleaseResumeConfiguration,
+  type IResolvedReleaseResumeConfiguration,
   type IResolvedReleaseWorkflow,
 } from "../helpers.workflow.js";
 import * as commitHelpers from "../mod_commit/mod.helpers.js";
-import { hasInstalledProjectTsdockerBinary } from "../helpers.tsdocker.js";
 import {
   inspectReleaseBranch,
   integrateReleaseBranch,
@@ -28,16 +25,38 @@ import {
   resolveReleaseMergeFlag,
   type IReleaseBranchContext,
 } from "./helpers.releasebranch.js";
+import {
+  ReleaseJournalStore,
+  createInitialTargetStatus,
+  finalizeJournalCompletion,
+  normalizeReleaseGitRemoteName,
+  normalizeReleaseVersion,
+  resolveGitCommonDirectory,
+  type IReleaseArtifact,
+  type IReleaseJournal,
+} from "./classes.releasejournal.js";
+import {
+  assertNoLegacyNpmPublisher,
+  assertPnpmReleaseCapability,
+  hashReleaseDestination,
+  normalizeNpmRegistryUrl,
+  packNpmArtifact,
+  verifyStoredNpmArtifact,
+} from "./helpers.npmartifact.js";
+import { executeReleasePublication } from "./helpers.releasepublication.js";
 
-type TTargetStatus = "success" | "already-published" | "skipped" | "failed";
+export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
 
-interface ITargetResult {
-  target: string;
-  status: TTargetStatus;
-  message?: string;
-}
+export const run = async (argvArg: any): Promise<void> => {
+  try {
+    await runInternal(argvArg);
+  } catch (error) {
+    logger.log("error", error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+};
 
-export const run = async (argvArg: any) => {
+const runInternal = async (argvArg: any): Promise<void> => {
   const mode = await getCliMode(argvArg);
   const subcommand = argvArg._?.[1];
 
@@ -46,6 +65,18 @@ export const run = async (argvArg: any) => {
     return;
   }
 
+  if (subcommand === "inspect") {
+    await runReleaseInspect(argvArg, mode);
+    return;
+  }
+  if (subcommand === "resume") {
+    await runReleaseResume(argvArg, mode);
+    return;
+  }
+  if (subcommand !== undefined) {
+    throw new Error(`Unknown release subcommand: ${subcommand}`);
+  }
+
   if (mode.json) {
     printJson({
       ok: false,
@@ -59,44 +90,37 @@ export const run = async (argvArg: any) => {
     executor: "bash",
     sourceFilePaths: [],
   });
-  let mergeRequested: boolean;
-  try {
-    mergeRequested = resolveReleaseMergeFlag(argvArg);
-  } catch (error) {
-    logger.log("error", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-    return;
-  }
+  const mergeRequested = resolveReleaseMergeFlag(argvArg);
   const workflow = await resolveReleaseWorkflow(argvArg);
-  let branchContext: IReleaseBranchContext;
-  try {
-    branchContext = await inspectReleaseBranch({
-      smartshell: smartshellInstance,
-      cwd: paths.cwd,
-      gitRemote: workflow.gitRemote,
-      gitTargetActive: workflow.targets.includes("git"),
-      pushBranch: workflow.pushBranch,
-      pushTags: workflow.pushTags,
-      mergeRequested,
-      planMode: workflow.confirmation === "plan",
-    });
-  } catch (error) {
-    logger.log("error", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-    return;
-  }
+  assertReleaseConfiguration(workflow);
+  let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    gitRemote: workflow.gitRemote,
+    gitTargetActive: workflow.targets.includes("git"),
+    pushBranch: workflow.pushBranch,
+    pushTags: workflow.pushTags,
+    mergeRequested,
+    planMode: workflow.confirmation === "plan",
+  });
   printReleasePlan(workflow, branchContext);
   if (workflow.confirmation === "plan") {
     return;
   }
 
+  await assertFreshReleaseCapabilities(
+    smartshellInstance,
+    workflow,
+    branchContext.sourceCwd,
+    branchContext.pushUrl,
+  );
+
   const pending = await readPendingChangelog(
     plugins.path.join(branchContext.sourceCwd, workflow.changelogFile),
     workflow.changelogPendingSection,
   );
   if (pending.isEmpty && !argvArg["allow-empty"] && !argvArg.allowEmpty) {
-    logger.log("error", "No pending changelog entries. Nothing to release.");
-    process.exit(1);
+    throw new Error("No pending changelog entries. Nothing to release.");
   }
 
   const versionType = resolveVersionType(argvArg, pending.block);
@@ -130,20 +154,10 @@ export const run = async (argvArg: any) => {
   }
 
   let newVersion = plannedVersion;
-  const gitResults: ITargetResult[] = [];
-  const npmResults: ITargetResult[] = [];
-  const dockerResults: ITargetResult[] = [];
-
-  try {
-    branchContext = await prepareReleaseIntegration(
-      smartshellInstance,
-      branchContext,
-    );
-  } catch (error) {
-    logger.log("error", error instanceof Error ? error.message : String(error));
-    process.exit(1);
-    return;
-  }
+  branchContext = await prepareReleaseIntegration(
+    smartshellInstance,
+    branchContext,
+  );
   if (workflow.runTests) {
     await runCommandStep(
       smartshellInstance,
@@ -157,33 +171,15 @@ export const run = async (argvArg: any) => {
   let releasePushUrl = branchContext.pushUrl;
   let expectedRemoteMainOid = branchContext.remoteMainOid;
   if (branchContext.sourceBranch === "main") {
-    try {
-      await revalidatePreparedReleaseBranch(smartshellInstance, branchContext);
-    } catch (error) {
-      logger.log(
-        "error",
-        error instanceof Error ? error.message : String(error),
-      );
-      process.exit(1);
-      return;
-    }
+    await revalidatePreparedReleaseBranch(smartshellInstance, branchContext);
   } else {
-    try {
-      const integration = await integrateReleaseBranch(
-        smartshellInstance,
-        branchContext,
-      );
-      releaseCwd = integration.releaseCwd;
-      releasePushUrl = integration.pushUrl;
-      expectedRemoteMainOid = integration.expectedRemoteMainOid;
-    } catch (error) {
-      logger.log(
-        "error",
-        error instanceof Error ? error.message : String(error),
-      );
-      process.exit(1);
-      return;
-    }
+    const integration = await integrateReleaseBranch(
+      smartshellInstance,
+      branchContext,
+    );
+    releaseCwd = integration.releaseCwd;
+    releasePushUrl = integration.pushUrl;
+    expectedRemoteMainOid = integration.expectedRemoteMainOid;
   }
 
   newVersion = await runVersionStep(projectType, versionType, releaseCwd);
@@ -220,81 +216,447 @@ export const run = async (argvArg: any) => {
     );
   }
 
-  const ensurePublicationState = async (): Promise<boolean> => {
-    try {
-      await verifyReleaseRefs(
-        smartshellInstance,
-        releaseCwd,
-        newVersion,
-        releaseRefs,
-      );
-      await revalidateReleasePublicationState(
-        smartshellInstance,
-        branchContext,
-        releaseRefs.mainOid,
-        expectedRemoteMainOid,
+  const ensurePublicationState = async (
+    expectedRemoteMainOidArg = expectedRemoteMainOid,
+  ): Promise<void> => {
+    await verifyReleaseRefs(
+      smartshellInstance,
+      releaseCwd,
+      newVersion,
+      releaseRefs,
+    );
+    await revalidateReleasePublicationState(
+      smartshellInstance,
+      branchContext,
+      releaseRefs.mainOid,
+      expectedRemoteMainOidArg,
+    );
+  };
+
+  await ensurePublicationState();
+  const journalContext = await createReleaseJournal({
+    smartshell: smartshellInstance,
+    workflow,
+    releaseCwd,
+    releasePushUrl,
+    expectedRemoteMainOid,
+    version: newVersion,
+    refs: releaseRefs,
+    ensurePublicationState,
+  });
+  const finalJournal = await executeReleasePublication({
+    smartshell: smartshellInstance,
+    cwd: releaseCwd,
+    store: journalContext.store,
+    journal: journalContext.journal,
+    pushUrl: releasePushUrl,
+    ensurePublicationState,
+  });
+  printReleaseJournalSummary(finalJournal);
+};
+
+const assertFreshReleaseCapabilities = async (
+  smartshellArg: plugins.smartshell.Smartshell,
+  workflowArg: IResolvedReleaseWorkflow,
+  cwdArg: string,
+  pushUrlArg?: string,
+): Promise<void> => {
+  if (workflowArg.targets.includes("docker")) {
+    throw new Error(
+      "Journaled Docker publication requires the planned structured tSDocker digest capability. Disable the Docker target until that upstream release is installed.",
+    );
+  }
+  if (workflowArg.targets.includes("git") && !pushUrlArg) {
+    throw new Error("The Git release target requires one resolved push destination.");
+  }
+  if (
+    workflowArg.targets.includes("git") ||
+    workflowArg.targets.includes("npm")
+  ) {
+    await assertNoLegacyNpmPublisher(cwdArg);
+  }
+  if (workflowArg.targets.includes("npm")) {
+    await assertPnpmReleaseCapability(smartshellArg, cwdArg);
+  }
+};
+
+const assertReleaseConfiguration = (
+  workflowArg: IResolvedReleaseWorkflow,
+): void => {
+  if (workflowArg.targets.includes("git")) {
+    normalizeReleaseGitRemoteName(workflowArg.gitRemote);
+  }
+  if (!workflowArg.targets.includes("npm")) {
+    return;
+  }
+  if (workflowArg.npmRegistries.length === 0) {
+    throw new Error("The npm release target requires at least one registry.");
+  }
+  if (workflowArg.npmAccessLevel !== "public") {
+    throw new Error(
+      "Journaled npm publication currently requires public access so every destination can be verified anonymously.",
+    );
+  }
+  if (
+    workflowArg.npmAlreadyPublished !== "success" &&
+    workflowArg.npmAlreadyPublished !== "error"
+  ) {
+    throw new Error(
+      "release.targets.npm.alreadyPublished must be success or error.",
+    );
+  }
+  const canonicalRegistries = workflowArg.npmRegistries.map(
+    normalizeNpmRegistryUrl,
+  );
+  if (
+    new Set(canonicalRegistries).size !== canonicalRegistries.length ||
+    canonicalRegistries.some(
+      (registryArg, indexArg) => registryArg !== workflowArg.npmRegistries[indexArg],
+    )
+  ) {
+    throw new Error(
+      "npm release registries must be unique canonical credential-free http(s) URLs.",
+    );
+  }
+};
+
+interface ICreateReleaseJournalOptions {
+  smartshell: plugins.smartshell.Smartshell;
+  workflow: IResolvedReleaseWorkflow;
+  releaseCwd: string;
+  releasePushUrl?: string;
+  expectedRemoteMainOid?: string;
+  version: string;
+  refs: IReleaseRefs;
+  ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
+}
+
+const createReleaseJournal = async (
+  optionsArg: ICreateReleaseJournalOptions,
+): Promise<{ store: ReleaseJournalStore; journal: IReleaseJournal }> => {
+  const gitCommonDirectory = await resolveGitCommonDirectory(
+    optionsArg.smartshell,
+    optionsArg.releaseCwd,
+  );
+  const store = new ReleaseJournalStore(gitCommonDirectory);
+  const releaseDirectory = store.getReleaseDirectory(optionsArg.version);
+  const releaseDirectoryExists = await plugins.fs
+    .lstat(releaseDirectory)
+    .then(() => true)
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ENOENT") return false;
+      throw error;
+    });
+  if (releaseDirectoryExists) {
+    throw new Error(
+      `Release journal v${optionsArg.version} already exists. Inspect or resume it instead of regenerating artifacts.`,
+    );
+  }
+
+  let temporaryDirectory = await store.createTemporaryDirectory(optionsArg.version);
+  try {
+    let artifact: IReleaseArtifact | null = null;
+    if (optionsArg.workflow.targets.includes("npm")) {
+      artifact = await packNpmArtifact(
+        optionsArg.smartshell,
+        optionsArg.releaseCwd,
+        temporaryDirectory,
+        optionsArg.version,
       );
-      return true;
-    } catch (error) {
-      logger.log(
-        "error",
-        error instanceof Error ? error.message : String(error),
+      await verifyCleanTree(
+        optionsArg.smartshell,
+        optionsArg.releaseCwd,
+        "npm pack lifecycle scripts changed the release worktree. Aborting release.",
       );
-      process.exit(1);
-      return false;
+      await optionsArg.ensurePublicationState();
     }
-  };
 
-  if (!(await ensurePublicationState())) {
+    const gitEnabled = optionsArg.workflow.targets.includes("git");
+    if (
+      gitEnabled &&
+      (!optionsArg.releasePushUrl || !optionsArg.expectedRemoteMainOid)
+    ) {
+      throw new Error("Git release destination state is incomplete.");
+    }
+    const now = new Date().toISOString();
+    const gitStatus = createInitialTargetStatus(gitEnabled);
+    const journal = finalizeJournalCompletion({
+      kind: "gitzone-release-journal",
+      schemaVersion: 1,
+      revision: 1,
+      release: {
+        version: optionsArg.version,
+        tag: `v${optionsArg.version}`,
+        mainOid: optionsArg.refs.mainOid,
+        tagOid: optionsArg.refs.tagOid,
+      },
+      artifact,
+      git: {
+        state: gitStatus.state,
+        attempts: gitStatus.attempts,
+        attempt: gitStatus.attempt,
+        error: gitStatus.error,
+        remote: gitEnabled ? optionsArg.workflow.gitRemote : null,
+        destinationHash: gitEnabled
+          ? hashReleaseDestination(optionsArg.releasePushUrl as string)
+          : null,
+        expectedRemoteMainOid: gitEnabled
+          ? (optionsArg.expectedRemoteMainOid as string)
+          : null,
+      },
+      npm: {
+        access: "public",
+        tag: "latest",
+        alreadyPublished: optionsArg.workflow.targets.includes("npm")
+          ? optionsArg.workflow.npmAlreadyPublished
+          : "success",
+        registries: optionsArg.workflow.targets.includes("npm")
+          ? optionsArg.workflow.npmRegistries.map((registryArg) => {
+              const status = createInitialTargetStatus(true);
+              return {
+                state: status.state,
+                attempts: status.attempts,
+                attempt: status.attempt,
+                error: status.error,
+                registry: registryArg,
+              };
+            })
+          : [],
+      },
+      createdAt: now,
+      updatedAt: now,
+      completedAt: null,
+    }, now);
+    const installed = await store.installPrepared(temporaryDirectory, journal);
+    temporaryDirectory = "";
+    return { store, journal: installed };
+  } finally {
+    if (temporaryDirectory) {
+      await plugins.fs.rm(temporaryDirectory, { recursive: true, force: true });
+    }
+  }
+};
+
+const runReleaseInspect = async (
+  argvArg: any,
+  modeArg: ICliMode,
+): Promise<void> => {
+  if (argvArg._?.length > 3) {
+    throw new Error("Usage: gitzone release inspect [version] [--json]");
+  }
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const store = new ReleaseJournalStore(
+    await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
+  );
+  const requestedVersion = argvArg._?.[2];
+  const journals = requestedVersion
+    ? [await store.read(normalizeReleaseVersion(requestedVersion))]
+    : await store.list();
+  if (modeArg.json) {
+    printJson({ ok: true, journals });
     return;
   }
+  if (journals.length === 0) {
+    console.log("No release journals found.");
+    return;
+  }
+  for (const journal of journals) {
+    printReleaseJournalSummary(journal);
+  }
+};
 
-  if (workflow.targets.includes("git")) {
-    gitResults.push(
-      ...(await runGitTarget(
-        smartshellInstance,
-        workflow,
-        releaseCwd,
-        newVersion,
-        releaseRefs,
-        releasePushUrl,
-        expectedRemoteMainOid,
-      )),
+const assertResumeArguments = (argvArg: any): void => {
+  const forbiddenKeys = [
+    "allow-empty",
+    "allowEmpty",
+    "b",
+    "build",
+    "docker",
+    "git",
+    "major",
+    "merge",
+    "minor",
+    "npm",
+    "p",
+    "patch",
+    "plan",
+    "publish",
+    "push",
+    "t",
+    "target",
+    "targets",
+    "test",
+  ];
+  if (
+    forbiddenKeys.some((keyArg) =>
+      Object.prototype.hasOwnProperty.call(argvArg, keyArg),
+    )
+  ) {
+    throw new Error(
+      "release resume rejects fresh-release target, integration, build, test, and version overrides.",
     );
-    if (gitResults.some((result) => result.status === "failed")) {
-      printReleaseSummary(newVersion, gitResults, npmResults, dockerResults);
-      process.exit(1);
-      return;
-    }
-    expectedRemoteMainOid = releaseRefs.mainOid;
   }
-  if (workflow.targets.includes("npm")) {
-    if (!(await ensurePublicationState())) {
-      return;
-    }
-    npmResults.push(
-      ...(await runNpmTarget(smartshellInstance, workflow, releaseCwd)),
+  if (argvArg._?.length !== 3) {
+    throw new Error(
+      "Usage: gitzone release resume <version> [-y] [--recover-attempt=<id>]",
     );
   }
-  if (workflow.targets.includes("docker")) {
-    if (!(await ensurePublicationState())) {
+};
+
+const runReleaseResume = async (
+  argvArg: any,
+  modeArg: ICliMode,
+): Promise<void> => {
+  assertResumeArguments(argvArg);
+  if (modeArg.json) {
+    throw new Error("JSON output is read-only. Use release inspect --json.");
+  }
+  const recoveryAttemptId =
+    argvArg["recover-attempt"] || argvArg.recoverAttempt;
+  if (
+    recoveryAttemptId !== undefined &&
+    (typeof recoveryAttemptId !== "string" ||
+      !/^[0-9a-f]{32}$/.test(recoveryAttemptId))
+  ) {
+    throw new Error("--recover-attempt requires one exact 32-character owner ID.");
+  }
+  const version = normalizeReleaseVersion(argvArg._[2]);
+  const smartshellInstance = new plugins.smartshell.Smartshell({
+    executor: "bash",
+    sourceFilePaths: [],
+  });
+  const store = new ReleaseJournalStore(
+    await resolveGitCommonDirectory(smartshellInstance, paths.cwd),
+  );
+  const journal = await store.read(version);
+  const gitEnabled = journal.git.state !== "skipped";
+  const resumeConfiguration = await resolveReleaseResumeConfiguration({
+    git: gitEnabled,
+    npm: journal.npm.registries.length > 0,
+  });
+  await assertResumeConfiguration(resumeConfiguration, journal, paths.cwd);
+  if (journal.artifact) {
+    await assertPnpmReleaseCapability(smartshellInstance, paths.cwd);
+    await assertNoLegacyNpmPublisher(paths.cwd);
+    await verifyStoredNpmArtifact(store.getArtifactPath(version), journal.artifact);
+  }
+
+  const branchContext = await inspectReleaseBranch({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    gitRemote: journal.git.remote || resumeConfiguration.gitRemote,
+    gitTargetActive: gitEnabled,
+    pushBranch: true,
+    pushTags: true,
+    mergeRequested: false,
+    planMode: false,
+  });
+  if (branchContext.sourceOid !== journal.release.mainOid) {
+    throw new Error("Resume must run from the journaled release commit on main.");
+  }
+  const refs = await captureReleaseRefs(
+    smartshellInstance,
+    paths.cwd,
+    version,
+    journal.release.mainOid,
+  );
+  if (refs.tagOid !== journal.release.tagOid) {
+    throw new Error("The local release tag no longer matches the journal.");
+  }
+  const pushUrl = gitEnabled ? branchContext.pushUrl : undefined;
+  if (
+    gitEnabled &&
+    (!pushUrl || hashReleaseDestination(pushUrl) !== journal.git.destinationHash)
+  ) {
+    throw new Error("The Git push destination changed after journal creation.");
+  }
+
+  if (!modeArg.yes) {
+    if (!modeArg.interactive) {
+      throw new Error("Release resume requires an interactive terminal or -y.");
+    }
+    const confirmed =
+      await plugins.smartinteract.SmartInteract.getCliConfirmation(
+        `Resume release v${version} now?`,
+        true,
+      );
+    if (!confirmed) {
+      logger.log("info", "Release resume cancelled.");
       return;
     }
-    dockerResults.push(
-      ...(await runDockerTarget(smartshellInstance, workflow, releaseCwd)),
-    );
   }
 
-  printReleaseSummary(newVersion, gitResults, npmResults, dockerResults);
+  const ensurePublicationState = async (
+    expectedRemoteMainOidArg?: string,
+  ): Promise<void> => {
+    await verifyReleaseRefs(smartshellInstance, paths.cwd, version, refs);
+    await revalidateReleasePublicationState(
+      smartshellInstance,
+      branchContext,
+      journal.release.mainOid,
+      expectedRemoteMainOidArg,
+    );
+  };
+  const finalJournal = await executeReleasePublication({
+    smartshell: smartshellInstance,
+    cwd: paths.cwd,
+    store,
+    journal,
+    pushUrl,
+    recoveryAttemptId,
+    ensurePublicationState,
+  });
+  printReleaseJournalSummary(finalJournal);
+};
+
+const assertResumeConfiguration = async (
+  workflowArg: IResolvedReleaseResumeConfiguration,
+  journalArg: IReleaseJournal,
+  cwdArg: string,
+): Promise<void> => {
   if (
-    [...gitResults, ...npmResults, ...dockerResults].some(
-      (result) => result.status === "failed",
-    )
+    journalArg.git.state !== "skipped" &&
+    workflowArg.gitRemote !== journalArg.git.remote
   ) {
-    process.exit(1);
+    throw new Error("Current Git release remote does not match the journal.");
+  }
+  const currentRegistries = workflowArg.npmRegistries.map(
+    normalizeNpmRegistryUrl,
+  );
+  if (
+    journalArg.npm.registries.length > 0 &&
+    (JSON.stringify(currentRegistries) !==
+      JSON.stringify(
+        journalArg.npm.registries.map((registryArg) => registryArg.registry),
+      ) ||
+      workflowArg.npmAccessLevel !== journalArg.npm.access ||
+      workflowArg.npmAlreadyPublished !== journalArg.npm.alreadyPublished)
+  ) {
+    throw new Error("Current npm release configuration does not match the journal.");
+  }
+  if (journalArg.git.state !== "skipped" || journalArg.artifact) {
+    await assertNoLegacyNpmPublisher(cwdArg);
   }
 };
 
+const printReleaseJournalSummary = (journalArg: IReleaseJournal): void => {
+  console.log("");
+  console.log(`Release v${journalArg.release.version}`);
+  console.log(`journal revision: ${journalArg.revision}`);
+  console.log(
+    `artifact: ${journalArg.artifact ? `${journalArg.artifact.integrity} (${journalArg.artifact.sha256})` : "none"}`,
+  );
+  console.log(`git: ${journalArg.git.state}`);
+  for (const registry of journalArg.npm.registries) {
+    console.log(`npm ${registry.registry}: ${registry.state}`);
+  }
+  console.log(`completed: ${journalArg.completedAt || "no"}`);
+  console.log("");
+};
+
 function resolveVersionType(
   argvArg: any,
   pendingBlock: string,
@@ -314,8 +676,7 @@ async function runCommandStep(
   console.log(`\n${label}`);
   const result = await smartshellInstance.exec(command, { cwd: cwdArg });
   if (result.exitCode !== 0) {
-    logger.log("error", `${label} failed. Aborting release.`);
-    process.exit(1);
+    throw new Error(`${label} failed. Aborting release.`);
   }
   logger.log("success", `${label} passed.`);
 }
@@ -328,12 +689,15 @@ async function verifyCleanTree(
   const statusResult = await smartshellInstance.execSpawn(
     "git",
     ["status", "--porcelain"],
-    { cwd: cwdArg, env: releaseGitEnv },
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
   );
   if (statusResult.stdout.trim() !== "") {
-    logger.log("error", errorMessage);
-    console.log(statusResult.stdout);
-    process.exit(1);
+    throw new Error(errorMessage);
   }
 }
 
@@ -385,6 +749,8 @@ async function runReleaseCommitStep(
   const addResult = await smartshellInstance.execSpawn("git", ["add", "-A"], {
     cwd: cwdArg,
     env: releaseGitEnv,
+    timeout: 60_000,
+    timeoutKillGraceMs: 5_000,
   });
   if (addResult.exitCode !== 0) {
     throw new Error("Staging release metadata failed.");
@@ -392,7 +758,12 @@ async function runReleaseCommitStep(
   const result = await smartshellInstance.execSpawn(
     "git",
     ["commit", "-m", `v${newVersion}`],
-    { cwd: cwdArg, env: releaseGitEnv },
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
   );
   if (result.exitCode !== 0) {
     throw new Error("Release commit failed.");
@@ -400,7 +771,13 @@ async function runReleaseCommitStep(
   const branchResult = await smartshellInstance.execSpawn(
     "git",
     ["symbolic-ref", "--quiet", "HEAD"],
-    { cwd: cwdArg, env: releaseGitEnv, silent: true },
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      silent: true,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
   );
   if (
     branchResult.exitCode !== 0 ||
@@ -440,7 +817,12 @@ async function runTagStep(
       `v${newVersion}`,
       releaseCommitOidArg,
     ],
-    { cwd: cwdArg, env: releaseGitEnv },
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
   );
   if (result.exitCode !== 0) {
     throw new Error("Release tag failed.");
@@ -460,7 +842,13 @@ const resolveGitObjectOid = async (
   const result = await smartshellInstanceArg.execSpawn(
     "git",
     ["rev-parse", "--verify", revisionArg],
-    { cwd: cwdArg, env: releaseGitEnv, silent: true },
+    {
+      cwd: cwdArg,
+      env: releaseGitEnv,
+      silent: true,
+      timeout: 60_000,
+      timeoutKillGraceMs: 5_000,
+    },
   );
   const oid = result.stdout.trim();
   if (result.exitCode !== 0 || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(oid)) {
@@ -523,208 +911,6 @@ const verifyReleaseRefs = async (
   }
 };
 
-async function runGitTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-  cwdArg: string,
-  newVersionArg: string,
-  releaseRefsArg: IReleaseRefs,
-  pushUrlArg?: string,
-  expectedRemoteMainOidArg?: string,
-): Promise<ITargetResult[]> {
-  const destination = pushUrlArg || workflow.gitRemote;
-  const targets: string[] = [];
-  const refspecs: string[] = [];
-  if (workflow.pushBranch) {
-    targets.push(`${workflow.gitRemote}/main`);
-    refspecs.push("refs/heads/main:refs/heads/main");
-  }
-  if (workflow.pushTags) {
-    targets.push(`${workflow.gitRemote}/v${newVersionArg}`);
-    refspecs.push(`refs/tags/v${newVersionArg}:refs/tags/v${newVersionArg}`);
-  }
-  if (refspecs.length === 0) {
-    return [];
-  }
-
-  const args = buildReleaseGitPushArgs({
-    destination,
-    newVersion: newVersionArg,
-    pushBranch: workflow.pushBranch,
-    pushTags: workflow.pushTags,
-    mainOid: releaseRefsArg.mainOid,
-    tagOid: releaseRefsArg.tagOid,
-    expectedRemoteMainOid: expectedRemoteMainOidArg,
-  });
-  const result = await smartshellInstance.execSpawn("git", args, {
-    cwd: cwdArg,
-    env: releaseGitEnv,
-  });
-  return targets.map((target) => ({
-    target,
-    status: result.exitCode === 0 ? "success" : "failed",
-    message:
-      result.exitCode === 0
-        ? undefined
-        : firstMeaningfulLine(result.combinedOutput),
-  }));
-}
-
-export interface IBuildReleaseGitPushArgsOptions {
-  destination: string;
-  newVersion: string;
-  pushBranch: boolean;
-  pushTags: boolean;
-  mainOid: string;
-  tagOid: string;
-  expectedRemoteMainOid?: string;
-}
-
-export function buildReleaseGitPushArgs(
-  optionsArg: IBuildReleaseGitPushArgsOptions,
-): string[] {
-  const refspecs: string[] = [];
-  if (optionsArg.pushBranch) {
-    refspecs.push(`${optionsArg.mainOid}:refs/heads/main`);
-  }
-  if (optionsArg.pushTags) {
-    refspecs.push(`${optionsArg.tagOid}:refs/tags/v${optionsArg.newVersion}`);
-  }
-  const args = ["push", "--no-follow-tags"];
-  if (refspecs.length > 1) {
-    args.push("--atomic");
-  }
-  if (optionsArg.pushBranch && optionsArg.expectedRemoteMainOid) {
-    args.push(
-      `--force-with-lease=refs/heads/main:${optionsArg.expectedRemoteMainOid}`,
-    );
-  }
-  args.push(optionsArg.destination, ...refspecs);
-  return args;
-}
-
-async function runNpmTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-  cwdArg: string,
-): Promise<ITargetResult[]> {
-  if (!workflow.npmEnabled) {
-    return [{ target: "npm", status: "skipped", message: "disabled" }];
-  }
-  if (workflow.npmRegistries.length === 0) {
-    return [
-      { target: "npm", status: "failed", message: "no registries configured" },
-    ];
-  }
-
-  const results: ITargetResult[] = [];
-  for (const registry of workflow.npmRegistries) {
-    const command = `pnpm publish --registry=${registry} --access=${workflow.npmAccessLevel}`;
-    const result = await smartshellInstance.exec(command, { cwd: cwdArg });
-    const output = result.combinedOutput;
-    if (result.exitCode === 0) {
-      results.push({ target: registry, status: "success" });
-    } else if (
-      isAlreadyPublishedOutput(output) &&
-      workflow.npmAlreadyPublished === "success"
-    ) {
-      results.push({ target: registry, status: "already-published" });
-    } else {
-      results.push({
-        target: registry,
-        status: "failed",
-        message: firstMeaningfulLine(output),
-      });
-    }
-  }
-  return results;
-}
-
-async function runDockerTarget(
-  smartshellInstance: plugins.smartshell.Smartshell,
-  workflow: IResolvedReleaseWorkflow,
-  cwdArg: string,
-): Promise<ITargetResult[]> {
-  if (!workflow.dockerEnabled) {
-    return [{ target: "docker", status: "skipped", message: "disabled" }];
-  }
-
-  let packageJson: unknown;
-  try {
-    packageJson = JSON.parse(
-      await plugins.fs.readFile(
-        plugins.path.join(cwdArg, "package.json"),
-        "utf8",
-      ),
-    );
-  } catch {
-    packageJson = undefined;
-  }
-  if (!getDeclaredTsdockerRange(packageJson)) {
-    return [
-      {
-        target: "tsdocker",
-        status: "failed",
-        message:
-          "Docker releases require @git.zone/tsdocker as a project dependency",
-      },
-    ];
-  }
-  if (!(await hasInstalledProjectTsdockerBinary(cwdArg))) {
-    return [
-      {
-        target: "tsdocker",
-        status: "failed",
-        message:
-          "Docker releases require the installed project-local tSDocker binary",
-      },
-    ];
-  }
-
-  const minimumTsdockerVersion = getTsdockerMinimumVersion(
-    workflow.dockerBuildRegistries.length > 0,
-    workflow.dockerTest,
-  );
-  if (minimumTsdockerVersion) {
-    const versionResult = await smartshellInstance.exec(
-      "pnpm exec tsdocker --version",
-      { cwd: cwdArg },
-    );
-    if (
-      versionResult.exitCode !== 0 ||
-      !supportsTsdockerMinimumVersion(
-        versionResult.combinedOutput,
-        minimumTsdockerVersion,
-      )
-    ) {
-      const minimumVersion = formatTsdockerMinimumVersion(
-        minimumTsdockerVersion,
-      );
-      return [
-        {
-          target: "tsdocker",
-          status: "failed",
-          message: `Docker release options require project-local @git.zone/tsdocker >= ${minimumVersion}`,
-        },
-      ];
-    }
-  }
-
-  const command = buildTsdockerPushCommand(workflow);
-  const result = await smartshellInstance.exec(command, { cwd: cwdArg });
-  const output = result.combinedOutput;
-  return [
-    {
-      target:
-        workflow.dockerPatterns.length > 0
-          ? `tsdocker:${workflow.dockerPatterns.join(",")}`
-          : "tsdocker",
-      status: result.exitCode === 0 ? "success" : "failed",
-      message: result.exitCode === 0 ? undefined : firstMeaningfulLine(output),
-    },
-  ];
-}
-
 type TDockerCommandWorkflow = Pick<
   IResolvedReleaseWorkflow,
   | "dockerRegistry"
@@ -776,21 +962,6 @@ export function buildTsdockerPushCommand(
   return commandParts.join(" ");
 }
 
-function isAlreadyPublishedOutput(output: string): boolean {
-  return /previously published versions|cannot publish over|already exists/i.test(
-    output,
-  );
-}
-
-function firstMeaningfulLine(output: string): string {
-  return (
-    output
-      .split("\n")
-      .map((line) => line.trim())
-      .find((line) => line.length > 0) || "command failed"
-  );
-}
-
 function shellQuote(value: string): string {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
@@ -858,49 +1029,11 @@ function formatDockerOptions(workflow: IResolvedReleaseWorkflow): string {
   return options.length > 0 ? options.join(", ") : "default";
 }
 
-function printReleaseSummary(
-  newVersion: string,
-  gitResults: ITargetResult[],
-  npmResults: ITargetResult[],
-  dockerResults: ITargetResult[],
-): void {
-  console.log("");
-  console.log(`Release v${newVersion}`);
-  console.log("");
-
-  if (gitResults.length > 0) {
-    console.log("git:");
-    for (const result of gitResults) {
-      console.log(
-        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
-      );
-    }
-  }
-
-  if (npmResults.length > 0) {
-    console.log("npm:");
-    for (const result of npmResults) {
-      console.log(
-        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
-      );
-    }
-  }
-
-  if (dockerResults.length > 0) {
-    console.log("docker:");
-    for (const result of dockerResults) {
-      console.log(
-        `  ${result.target}  ${result.status}${result.message ? ` (${result.message})` : ""}`,
-      );
-    }
-  }
-}
-
 export function showHelp(mode?: ICliMode): void {
   if (mode?.json) {
     printJson({
       command: "release",
-      usage: "gitzone release [options]",
+      usage: "gitzone release [inspect [version]|resume <version>] [options]",
       description:
         "Creates a versioned release from pending changelog entries and publishes configured artifacts.",
       flags: [
@@ -918,16 +1051,20 @@ export function showHelp(mode?: ICliMode): void {
           flag: "--no-build",
           description: "Disable the post-metadata release build",
         },
-        { flag: "-p, --push", description: "Enable the git release target" },
+        { flag: "-p, --push", description: "Explicitly select the git target" },
         {
           flag: "--target <names>",
-          description: "Release only selected targets: git,npm,docker",
+          description:
+            "Replace configured targets with a non-empty subset of git,npm,docker",
+        },
+        { flag: "--npm", description: "Explicitly select the npm target" },
+        {
+          flag: "--docker",
+          description: "Select Docker and fail closed under journal schema v1",
         },
-        { flag: "--npm", description: "Enable the npm release target" },
-        { flag: "--docker", description: "Enable the tsdocker release target" },
         {
           flag: "--no-publish",
-          description: "Run release core and git target only",
+          description: "Remove npm and Docker without implicitly enabling Git",
         },
         {
           flag: "--merge",
@@ -939,13 +1076,28 @@ export function showHelp(mode?: ICliMode): void {
           description:
             "Show the workflow without fetching or mutating refs, files, the index, or worktrees",
         },
+        {
+          flag: "inspect [version]",
+          description: "Read one or all durable release journals without mutation",
+        },
+        {
+          flag: "resume <version>",
+          description: "Resume exact Git/npm publication without rebuilding or repacking",
+        },
+        {
+          flag: "--recover-attempt <id>",
+          description:
+            "Recover one exact 32-character hexadecimal attempt ID after proving it stopped",
+        },
       ],
     });
     return;
   }
 
   console.log("");
-  console.log("Usage: gitzone release [options]");
+  console.log(
+    "Usage: gitzone release [inspect [version]|resume <version>] [options]",
+  );
   console.log("");
   console.log("Creates a versioned release from changelog Pending entries.");
   console.log("");
@@ -956,13 +1108,17 @@ export function showHelp(mode?: ICliMode): void {
     "  -b, --build         Build after creating local release metadata",
   );
   console.log("  --no-build          Disable the post-metadata release build");
-  console.log("  -p, --push          Enable the git release target");
+  console.log("  -p, --push          Explicitly select the git target");
   console.log(
-    "  --target <names>    Release only selected targets: git,npm,docker",
+    "  --target <names>    Replace configured targets with a non-empty subset of git,npm,docker",
+  );
+  console.log("  --npm               Explicitly select the npm target");
+  console.log(
+    "  --docker            Select Docker (fails closed under journal schema v1)",
+  );
+  console.log(
+    "  --no-publish        Remove npm and Docker without implicitly enabling Git",
   );
-  console.log("  --npm               Enable the npm release target");
-  console.log("  --docker            Enable the tsdocker release target");
-  console.log("  --no-publish        Run release core and git target only");
   console.log(
     "  --merge             Fast-forward and lease-push a cleanly rebased feature branch before release metadata",
   );
@@ -970,5 +1126,14 @@ export function showHelp(mode?: ICliMode): void {
   console.log(
     "  --plan              Show workflow without fetching or mutating refs, files, index, or worktrees",
   );
+  console.log(
+    "  inspect [version]   Read one or all durable release journals without mutation",
+  );
+  console.log(
+    "  resume <version>    Resume exact Git/npm publication without rebuilding or repacking",
+  );
+  console.log(
+    "  --recover-attempt   Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",
+  );
   console.log("");
 }