@git.zone/cli 6.0.1 → 6.1.0

package/ts/mod_release/index.ts

@@ -9,6 +9,7 @@ import {
   readPendingChangelog,
 } from "../helpers.changelog.js";
 import {
+  resolveReleaseDockerConfiguration,
   resolveReleaseWorkflow,
   resolveReleaseResumeConfiguration,
   type IResolvedReleaseResumeConfiguration,
@@ -27,13 +28,16 @@ import {
 } from "./helpers.releasebranch.js";
 import {
   ReleaseJournalStore,
+  createInitialReleaseDockerJournal,
   createInitialTargetStatus,
   finalizeJournalCompletion,
   normalizeReleaseGitRemoteName,
   normalizeReleaseVersion,
   resolveGitCommonDirectory,
   type IReleaseArtifact,
-  type IReleaseJournal,
+  type TReleaseJournal,
+  type IReleaseJournalV1,
+  type IReleaseJournalV2,
 } from "./classes.releasejournal.js";
 import {
   assertNoLegacyNpmPublisher,
@@ -44,6 +48,13 @@ import {
   verifyStoredNpmArtifact,
 } from "./helpers.npmartifact.js";
 import { executeReleasePublication } from "./helpers.releasepublication.js";
+import {
+  TsdockerReleaseClient,
+  canonicalReleaseJson,
+  createReleaseQualificationRequest,
+  type ITsdockerReleaseClient,
+  type IReleaseQualificationRequest,
+} from "./helpers.tsdockerprotocol.js";
 
 export { buildReleaseGitPushArgs } from "./helpers.releasepublication.js";
 
@@ -92,7 +103,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
   });
   const mergeRequested = resolveReleaseMergeFlag(argvArg);
   const workflow = await resolveReleaseWorkflow(argvArg);
-  assertReleaseConfiguration(workflow);
+  assertReleaseConfiguration(workflow, mergeRequested);
   let branchContext: IReleaseBranchContext = await inspectReleaseBranch({
     smartshell: smartshellInstance,
     cwd: paths.cwd,
@@ -108,11 +119,15 @@ const runInternal = async (argvArg: any): Promise<void> => {
     return;
   }
 
+  const preflightTsdocker = workflow.targets.includes("docker")
+    ? new TsdockerReleaseClient(smartshellInstance, branchContext.sourceCwd)
+    : undefined;
   await assertFreshReleaseCapabilities(
     smartshellInstance,
     workflow,
     branchContext.sourceCwd,
     branchContext.pushUrl,
+    preflightTsdocker,
   );
 
   const pending = await readPendingChangelog(
@@ -135,6 +150,16 @@ const runInternal = async (argvArg: any): Promise<void> => {
     currentVersion,
     versionType,
   );
+  if (preflightTsdocker) {
+    await preflightTsdocker.validate(
+      createDockerQualificationRequest(
+        workflow,
+        branchContext.sourceCwd,
+        plannedVersion,
+        branchContext.sourceOid,
+      ),
+    );
+  }
 
   if (workflow.confirmation === "prompt") {
     if (!mode.interactive) {
@@ -234,6 +259,18 @@ const runInternal = async (argvArg: any): Promise<void> => {
   };
 
   await ensurePublicationState();
+  const tsdocker = workflow.targets.includes("docker")
+    ? new TsdockerReleaseClient(smartshellInstance, releaseCwd)
+    : undefined;
+  await tsdocker?.assertCapabilities();
+  const dockerRequest = tsdocker
+    ? createDockerQualificationRequest(
+        workflow,
+        releaseCwd,
+        newVersion,
+        releaseRefs.mainOid,
+      )
+    : undefined;
   const journalContext = await createReleaseJournal({
     smartshell: smartshellInstance,
     workflow,
@@ -242,6 +279,8 @@ const runInternal = async (argvArg: any): Promise<void> => {
     expectedRemoteMainOid,
     version: newVersion,
     refs: releaseRefs,
+    dockerRequest,
+    tsdocker,
     ensurePublicationState,
   });
   const finalJournal = await executeReleasePublication({
@@ -250,6 +289,7 @@ const runInternal = async (argvArg: any): Promise<void> => {
     store: journalContext.store,
     journal: journalContext.journal,
     pushUrl: releasePushUrl,
+    tsdocker,
     ensurePublicationState,
   });
   printReleaseJournalSummary(finalJournal);
@@ -260,14 +300,18 @@ const assertFreshReleaseCapabilities = async (
   workflowArg: IResolvedReleaseWorkflow,
   cwdArg: string,
   pushUrlArg?: string,
+  tsdockerArg?: ITsdockerReleaseClient,
 ): 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 (!tsdockerArg) {
+      throw new Error("Docker release target requires project-local tSDocker.");
+    }
+    await tsdockerArg.assertCapabilities();
   }
   if (workflowArg.targets.includes("git") && !pushUrlArg) {
-    throw new Error("The Git release target requires one resolved push destination.");
+    throw new Error(
+      "The Git release target requires one resolved push destination.",
+    );
   }
   if (
     workflowArg.targets.includes("git") ||
@@ -282,7 +326,20 @@ const assertFreshReleaseCapabilities = async (
 
 const assertReleaseConfiguration = (
   workflowArg: IResolvedReleaseWorkflow,
+  mergeRequestedArg: boolean,
 ): void => {
+  if (workflowArg.targets.includes("docker")) {
+    if (mergeRequestedArg) {
+      throw new Error(
+        "Docker releases cannot use --merge because qualification must precede every remote publication.",
+      );
+    }
+    if (workflowArg.dockerNoBuild) {
+      throw new Error(
+        "Journaled Docker qualification always builds; release.targets.docker.noBuild must be false or absent.",
+      );
+    }
+  }
   if (workflowArg.targets.includes("git")) {
     normalizeReleaseGitRemoteName(workflowArg.gitRemote);
   }
@@ -311,7 +368,8 @@ const assertReleaseConfiguration = (
   if (
     new Set(canonicalRegistries).size !== canonicalRegistries.length ||
     canonicalRegistries.some(
-      (registryArg, indexArg) => registryArg !== workflowArg.npmRegistries[indexArg],
+      (registryArg, indexArg) =>
+        registryArg !== workflowArg.npmRegistries[indexArg],
     )
   ) {
     throw new Error(
@@ -328,12 +386,33 @@ interface ICreateReleaseJournalOptions {
   expectedRemoteMainOid?: string;
   version: string;
   refs: IReleaseRefs;
+  dockerRequest?: IReleaseQualificationRequest;
+  tsdocker?: ITsdockerReleaseClient;
   ensurePublicationState: (expectedRemoteMainOidArg?: string) => Promise<void>;
 }
 
+const createDockerQualificationRequest = (
+  workflowArg: IResolvedReleaseWorkflow,
+  cwdArg: string,
+  versionArg: string,
+  revisionArg: string,
+): IReleaseQualificationRequest =>
+  createReleaseQualificationRequest({
+    buildRegistries: workflowArg.dockerBuildRegistries,
+    cached: workflowArg.dockerCached,
+    context: workflowArg.dockerContext,
+    cwd: cwdArg,
+    parallel: workflowArg.dockerParallel,
+    patterns: workflowArg.dockerPatterns,
+    registry: workflowArg.dockerRegistry,
+    revision: revisionArg,
+    test: workflowArg.dockerTest,
+    version: versionArg,
+  });
+
 const createReleaseJournal = async (
   optionsArg: ICreateReleaseJournalOptions,
-): Promise<{ store: ReleaseJournalStore; journal: IReleaseJournal }> => {
+): Promise<{ store: ReleaseJournalStore; journal: TReleaseJournal }> => {
   const gitCommonDirectory = await resolveGitCommonDirectory(
     optionsArg.smartshell,
     optionsArg.releaseCwd,
@@ -353,7 +432,9 @@ const createReleaseJournal = async (
     );
   }
 
-  let temporaryDirectory = await store.createTemporaryDirectory(optionsArg.version);
+  let temporaryDirectory = await store.createTemporaryDirectory(
+    optionsArg.version,
+  );
   try {
     let artifact: IReleaseArtifact | null = null;
     if (optionsArg.workflow.targets.includes("npm")) {
@@ -380,53 +461,75 @@ const createReleaseJournal = async (
     }
     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 journal = finalizeJournalCompletion(
+      {
+        kind: "gitzone-release-journal",
+        schemaVersion: optionsArg.dockerRequest ? 2 : 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,
+                };
+              })
+            : [],
+        },
+        ...(optionsArg.dockerRequest
+          ? {
+              docker: createInitialReleaseDockerJournal(
+                optionsArg.dockerRequest,
+              ),
+            }
+          : {}),
+        createdAt: now,
+        updatedAt: now,
+        completedAt: null,
+      } as TReleaseJournal,
+      now,
+    );
+    await optionsArg.ensurePublicationState();
+    if (optionsArg.dockerRequest) {
+      if (!optionsArg.tsdocker) {
+        throw new Error(
+          "Docker release journal installation requires the verified tSDocker protocol client.",
+        );
+      }
+      await optionsArg.tsdocker.validate(
+        optionsArg.dockerRequest,
+        temporaryDirectory,
+      );
+    }
     const installed = await store.installPrepared(temporaryDirectory, journal);
     temporaryDirectory = "";
     return { store, journal: installed };
@@ -521,7 +624,9 @@ const runReleaseResume = async (
     (typeof recoveryAttemptId !== "string" ||
       !/^[0-9a-f]{32}$/.test(recoveryAttemptId))
   ) {
-    throw new Error("--recover-attempt requires one exact 32-character owner ID.");
+    throw new Error(
+      "--recover-attempt requires one exact 32-character owner ID.",
+    );
   }
   const version = normalizeReleaseVersion(argvArg._[2]);
   const smartshellInstance = new plugins.smartshell.Smartshell({
@@ -538,10 +643,45 @@ const runReleaseResume = async (
     npm: journal.npm.registries.length > 0,
   });
   await assertResumeConfiguration(resumeConfiguration, journal, paths.cwd);
+  let tsdocker: ITsdockerReleaseClient | undefined;
+  if (journal.schemaVersion === 2 && !journal.completedAt) {
+    const dockerConfiguration = await resolveReleaseDockerConfiguration();
+    if (dockerConfiguration.dockerNoBuild) {
+      throw new Error(
+        "Journaled Docker qualification always builds; release.targets.docker.noBuild must be false or absent.",
+      );
+    }
+    const currentRequest = createReleaseQualificationRequest({
+      buildRegistries: dockerConfiguration.dockerBuildRegistries,
+      cached: dockerConfiguration.dockerCached,
+      context: dockerConfiguration.dockerContext,
+      cwd: paths.cwd,
+      parallel: dockerConfiguration.dockerParallel,
+      patterns: dockerConfiguration.dockerPatterns,
+      registry: dockerConfiguration.dockerRegistry,
+      revision: journal.release.mainOid,
+      test: dockerConfiguration.dockerTest,
+      version: journal.release.version,
+    });
+    if (
+      canonicalReleaseJson(currentRequest) !==
+      canonicalReleaseJson(journal.docker.request)
+    ) {
+      throw new Error(
+        "Current Docker release configuration does not match the journal.",
+      );
+    }
+    tsdocker = new TsdockerReleaseClient(smartshellInstance, paths.cwd);
+    await tsdocker.assertCapabilities();
+    await tsdocker.validate(journal.docker.request);
+  }
   if (journal.artifact) {
     await assertPnpmReleaseCapability(smartshellInstance, paths.cwd);
     await assertNoLegacyNpmPublisher(paths.cwd);
-    await verifyStoredNpmArtifact(store.getArtifactPath(version), journal.artifact);
+    await verifyStoredNpmArtifact(
+      store.getArtifactPath(version),
+      journal.artifact,
+    );
   }
 
   const branchContext = await inspectReleaseBranch({
@@ -555,7 +695,9 @@ const runReleaseResume = async (
     planMode: false,
   });
   if (branchContext.sourceOid !== journal.release.mainOid) {
-    throw new Error("Resume must run from the journaled release commit on main.");
+    throw new Error(
+      "Resume must run from the journaled release commit on main.",
+    );
   }
   const refs = await captureReleaseRefs(
     smartshellInstance,
@@ -569,7 +711,8 @@ const runReleaseResume = async (
   const pushUrl = gitEnabled ? branchContext.pushUrl : undefined;
   if (
     gitEnabled &&
-    (!pushUrl || hashReleaseDestination(pushUrl) !== journal.git.destinationHash)
+    (!pushUrl ||
+      hashReleaseDestination(pushUrl) !== journal.git.destinationHash)
   ) {
     throw new Error("The Git push destination changed after journal creation.");
   }
@@ -607,6 +750,7 @@ const runReleaseResume = async (
     journal,
     pushUrl,
     recoveryAttemptId,
+    tsdocker,
     ensurePublicationState,
   });
   printReleaseJournalSummary(finalJournal);
@@ -614,7 +758,7 @@ const runReleaseResume = async (
 
 const assertResumeConfiguration = async (
   workflowArg: IResolvedReleaseResumeConfiguration,
-  journalArg: IReleaseJournal,
+  journalArg: TReleaseJournal,
   cwdArg: string,
 ): Promise<void> => {
   if (
@@ -635,14 +779,16 @@ const assertResumeConfiguration = async (
       workflowArg.npmAccessLevel !== journalArg.npm.access ||
       workflowArg.npmAlreadyPublished !== journalArg.npm.alreadyPublished)
   ) {
-    throw new Error("Current npm release configuration does not match the journal.");
+    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 => {
+const printReleaseJournalSummary = (journalArg: TReleaseJournal): void => {
   console.log("");
   console.log(`Release v${journalArg.release.version}`);
   console.log(`journal revision: ${journalArg.revision}`);
@@ -653,6 +799,17 @@ const printReleaseJournalSummary = (journalArg: IReleaseJournal): void => {
   for (const registry of journalArg.npm.registries) {
     console.log(`npm ${registry.registry}: ${registry.state}`);
   }
+  if (journalArg.schemaVersion === 2) {
+    console.log(
+      `docker qualification ${journalArg.docker.request.candidateId}: ${journalArg.docker.qualification.state}`,
+    );
+    for (const promotion of journalArg.docker.promotions) {
+      console.log(
+        `docker promotion ${promotion.promotionId}: ${promotion.state}`,
+      );
+    }
+    console.log(`docker cleanup: ${journalArg.docker.cleanup.state}`);
+  }
   console.log(`completed: ${journalArg.completedAt || "no"}`);
   console.log("");
 };
@@ -796,7 +953,9 @@ async function runReleaseCommitStep(
     "refs/heads/main^{commit}",
   );
   if (headOid !== mainOid) {
-    throw new Error("HEAD and main diverged after creating the release commit.");
+    throw new Error(
+      "HEAD and main diverged after creating the release commit.",
+    );
   }
   return mainOid;
 }
@@ -916,7 +1075,6 @@ type TDockerCommandWorkflow = Pick<
   | "dockerRegistry"
   | "dockerBuildRegistries"
   | "dockerTest"
-  | "dockerNoBuild"
   | "dockerCached"
   | "dockerParallel"
   | "dockerContext"
@@ -941,9 +1099,6 @@ export function buildTsdockerPushCommand(
   if (workflow.dockerTest) {
     commandParts.push("--test");
   }
-  if (workflow.dockerNoBuild) {
-    commandParts.push("--no-build");
-  }
   if (workflow.dockerCached) {
     commandParts.push("--cached");
   }
@@ -1024,7 +1179,6 @@ function formatDockerOptions(workflow: IResolvedReleaseWorkflow): string {
     options.push(
       `parallel=${workflow.dockerParallel === true ? "true" : workflow.dockerParallel}`,
     );
-  if (workflow.dockerNoBuild) options.push("no-build");
   if (workflow.dockerContext) options.push(`context=${workflow.dockerContext}`);
   return options.length > 0 ? options.join(", ") : "default";
 }
@@ -1060,7 +1214,8 @@ export function showHelp(mode?: ICliMode): void {
         { flag: "--npm", description: "Explicitly select the npm target" },
         {
           flag: "--docker",
-          description: "Select Docker and fail closed under journal schema v1",
+          description:
+            "Select digest-qualified Docker publication through project-local tSDocker >= 3.5.1",
         },
         {
           flag: "--no-publish",
@@ -1078,11 +1233,13 @@ export function showHelp(mode?: ICliMode): void {
         },
         {
           flag: "inspect [version]",
-          description: "Read one or all durable release journals without mutation",
+          description:
+            "Read one or all durable release journals without mutation",
         },
         {
           flag: "resume <version>",
-          description: "Resume exact Git/npm publication without rebuilding or repacking",
+          description:
+            "Resume exact journaled publication without rebuilding or repacking npm artifacts",
         },
         {
           flag: "--recover-attempt <id>",
@@ -1114,7 +1271,7 @@ export function showHelp(mode?: ICliMode): void {
   );
   console.log("  --npm               Explicitly select the npm target");
   console.log(
-    "  --docker            Select Docker (fails closed under journal schema v1)",
+    "  --docker            Select digest-qualified Docker publication through project-local tSDocker >= 3.5.1",
   );
   console.log(
     "  --no-publish        Remove npm and Docker without implicitly enabling Git",
@@ -1130,7 +1287,7 @@ export function showHelp(mode?: ICliMode): void {
     "  inspect [version]   Read one or all durable release journals without mutation",
   );
   console.log(
-    "  resume <version>    Resume exact Git/npm publication without rebuilding or repacking",
+    "  resume <version>    Resume exact journaled publication without rebuilding or repacking npm artifacts",
   );
   console.log(
     "  --recover-attempt   Recover one exact 32-character hexadecimal attempt ID after proving its publisher stopped",

package/ts/plugins.ts

@@ -2,7 +2,9 @@ import * as smartlog from '@push.rocks/smartlog';
 import * as smartlogDestinationLocal from '@push.rocks/smartlog-destination-local';
 import * as smartconfig from '@push.rocks/smartconfig';
 import * as path from 'path';
+import * as os from 'node:os';
 import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import * as crypto from 'node:crypto';
 import * as projectinfo from '@push.rocks/projectinfo';
 import * as smartcli from '@push.rocks/smartcli';
@@ -17,6 +19,21 @@ import * as smartinteract from '@push.rocks/smartinteract';
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartbucket from '@push.rocks/smartbucket';
 import * as s3 from '@aws-sdk/client-s3';
+import * as tsdockerReleaseProtocol from '@git.zone/tsdocker/dist_ts/classes.releaseprotocol.js';
+
+export type {
+  IReleaseCapabilitiesResult,
+  IReleaseCleanupResult,
+  IReleaseDestinationEvidence,
+  IReleaseProbeResult,
+  IReleasePromotionContext,
+  IReleasePromotionResult,
+  IReleaseQualificationRequest,
+  IReleaseQualificationResult,
+  IReleaseValidationResult,
+  TReleasePromotionEvidence,
+  TReleaseProtocolCommand,
+} from '@git.zone/tsdocker/dist_ts/interfaces/index.js';
 
 // Create smartfs instance for filesystem operations
 export const smartfs = new SmartFs(new SmartFsProviderNode());
@@ -26,7 +43,9 @@ export {
   smartlogDestinationLocal,
   smartconfig,
   path,
+  os,
   fs,
+  fsConstants,
   crypto,
   projectinfo,
   smartcli,
@@ -40,4 +59,5 @@ export {
   smartdelay,
   smartbucket,
   s3,
+  tsdockerReleaseProtocol,
 };