@git.zone/cli 6.0.1 → 6.1.1

package/ts/mod_release/helpers.tsdockerprotocol.ts

@@ -0,0 +1,806 @@
+import * as plugins from "./mod.plugins.js";
+import { getProjectTsdockerBinPath } from "../helpers.tsdocker.js";
+import { supportsTsdockerMinimumVersion } from "../helpers.workflow.js";
+import type {
+  IReleaseCapabilitiesResult,
+  IReleaseCleanupResult,
+  IReleaseDestinationEvidence,
+  IReleaseProbeResult,
+  IReleasePromotionContext,
+  IReleasePromotionResult,
+  IReleaseQualificationRequest,
+  IReleaseQualificationResult,
+  IReleaseValidationResult,
+  TReleasePromotionEvidence,
+  TReleaseProtocolCommand,
+} from "./mod.plugins.js";
+
+export type {
+  IReleaseCapabilitiesResult,
+  IReleaseCleanupResult,
+  IReleaseDestinationEvidence,
+  IReleaseProbeResult,
+  IReleasePromotionContext,
+  IReleasePromotionResult,
+  IReleaseQualificationRequest,
+  IReleaseQualificationResult,
+  IReleaseValidationResult,
+  TReleasePromotionEvidence,
+  TReleaseProtocolCommand,
+} from "./mod.plugins.js";
+
+export const assertReleaseCleanupResult =
+  plugins.tsdockerReleaseProtocol.assertReleaseCleanupResult;
+export const assertReleasePromotionEvidence =
+  plugins.tsdockerReleaseProtocol.assertReleasePromotionEvidence;
+export const assertReleaseProbeResult =
+  plugins.tsdockerReleaseProtocol.assertReleaseProbeResult;
+export const assertReleasePromotionResult =
+  plugins.tsdockerReleaseProtocol.assertReleasePromotionResult;
+export const assertReleaseQualificationRequest =
+  plugins.tsdockerReleaseProtocol.assertReleaseQualificationRequest;
+export const assertReleaseQualificationResult =
+  plugins.tsdockerReleaseProtocol.assertReleaseQualificationResult;
+export const canonicalReleaseJson =
+  plugins.tsdockerReleaseProtocol.canonicalReleaseJson;
+export const canonicalReleaseJsonDocument =
+  plugins.tsdockerReleaseProtocol.canonicalReleaseJsonDocument;
+export const classifyReleasePromotionEvidence =
+  plugins.tsdockerReleaseProtocol.classifyReleasePromotionEvidence;
+export const createReleaseProjectId =
+  plugins.tsdockerReleaseProtocol.createReleaseProjectId;
+export const createReleasePromotionId =
+  plugins.tsdockerReleaseProtocol.createReleasePromotionId;
+export const createReleaseQualificationRequest =
+  plugins.tsdockerReleaseProtocol.createReleaseQualificationRequest;
+export const getReleasePromotionContexts =
+  plugins.tsdockerReleaseProtocol.getReleasePromotionContexts;
+
+const responseByteLimit = 1024 * 1024;
+const requestByteLimit = 64 * 1024;
+const packageJsonByteLimit = 64 * 1024;
+const requestOwnerIdPattern = /^[a-f0-9]{32}$/;
+const requestFilePattern =
+  /^\.tsdocker-request\.([a-f0-9]{32})\.(release-(?:validate|qualify|probe|promote|cleanup))\.([a-f0-9]{24})\.json$/;
+const minimumReleaseVersion = [3, 5, 1] as const;
+
+const commandTimeouts: Record<TReleaseProtocolCommand, number> = {
+  "release-capabilities": 30_000,
+  "release-validate": 2 * 60_000,
+  "release-qualify": 6 * 60 * 60_000,
+  "release-probe": 5 * 60_000,
+  "release-promote": 2 * 60 * 60_000,
+  "release-cleanup": 10 * 60_000,
+};
+
+const isPlainObject = (
+  valueArg: unknown,
+): valueArg is Record<string, unknown> =>
+  typeof valueArg === "object" && valueArg !== null && !Array.isArray(valueArg);
+
+export class TsdockerReleaseCommandError extends Error {
+  constructor(
+    public readonly command: TReleaseProtocolCommand,
+    public readonly code: string,
+    messageArg: string,
+  ) {
+    super(messageArg);
+    this.name = "TsdockerReleaseCommandError";
+  }
+}
+
+export class TsdockerReleaseRequestCleanupError extends Error {
+  public reclamationError: unknown | undefined;
+
+  constructor(
+    public readonly command: TReleaseProtocolCommand,
+    public readonly requestPath: string,
+    public readonly commandError: unknown | undefined,
+    public readonly result: unknown | undefined,
+    public readonly cleanupError: unknown,
+  ) {
+    super(`tSDocker ${command} request cleanup failed.`);
+    this.name = "TsdockerReleaseRequestCleanupError";
+    this.reclamationError = undefined;
+  }
+}
+
+export interface ITsdockerReleaseClient {
+  assertCapabilities: () => Promise<IReleaseCapabilitiesResult>;
+  validate: (
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg?: string,
+  ) => Promise<IReleaseValidationResult>;
+  qualify: (
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ) => Promise<IReleaseQualificationResult>;
+  probe: (
+    requestArg: IReleaseQualificationRequest,
+    contextArg: IReleasePromotionContext,
+    requestDirectoryArg?: string,
+    requestOwnerIdArg?: string,
+  ) => Promise<IReleaseProbeResult>;
+  promote: (
+    requestArg: IReleaseQualificationRequest,
+    contextArg: IReleasePromotionContext,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ) => Promise<IReleasePromotionResult>;
+  cleanup: (
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ) => Promise<IReleaseCleanupResult>;
+  reclaimRequestFiles: (
+    requestDirectoryArg: string,
+    retiredOwnerIdsArg: string[],
+  ) => Promise<void>;
+}
+
+const parseProtocolOutput = (
+  resultArg: plugins.smartshell.IExecResult,
+  commandArg: TReleaseProtocolCommand,
+): unknown => {
+  if (resultArg.timedOut) {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "COMMAND_TIMEOUT",
+      `tSDocker ${commandArg} timed out with an unresolved outcome.`,
+    );
+  }
+  if (resultArg.signal) {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "COMMAND_SIGNALLED",
+      `tSDocker ${commandArg} was terminated with an unresolved outcome.`,
+    );
+  }
+  if (resultArg.stderr !== "") {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "INVALID_PROTOCOL_OUTPUT",
+      `tSDocker ${commandArg} wrote non-protocol stderr output.`,
+    );
+  }
+  if (
+    Buffer.byteLength(resultArg.stdout) > responseByteLimit ||
+    !resultArg.stdout.endsWith("\n")
+  ) {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "INVALID_PROTOCOL_OUTPUT",
+      `tSDocker ${commandArg} returned an invalid response envelope.`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(resultArg.stdout);
+  } catch {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "INVALID_PROTOCOL_OUTPUT",
+      `tSDocker ${commandArg} returned invalid JSON.`,
+    );
+  }
+  if (canonicalReleaseJsonDocument(parsed) !== resultArg.stdout) {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "INVALID_PROTOCOL_OUTPUT",
+      `tSDocker ${commandArg} returned noncanonical JSON.`,
+    );
+  }
+  if (resultArg.exitCode !== 0) {
+    try {
+      const protocolError =
+        plugins.tsdockerReleaseProtocol.assertReleaseErrorResult(
+          parsed,
+          commandArg,
+        );
+      throw new TsdockerReleaseCommandError(
+        commandArg,
+        protocolError.error.code,
+        protocolError.error.message,
+      );
+    } catch (error) {
+      if (error instanceof TsdockerReleaseCommandError) throw error;
+      throw new TsdockerReleaseCommandError(
+        commandArg,
+        "INVALID_PROTOCOL_OUTPUT",
+        `tSDocker ${commandArg} failed without a valid protocol error.`,
+      );
+    }
+  }
+  if (
+    isPlainObject(parsed) &&
+    parsed.kind === "tsdocker-release-error-result"
+  ) {
+    throw new TsdockerReleaseCommandError(
+      commandArg,
+      "INVALID_PROTOCOL_OUTPUT",
+      `tSDocker ${commandArg} returned an error result with exit code 0.`,
+    );
+  }
+  return parsed;
+};
+
+export class TsdockerReleaseClient implements ITsdockerReleaseClient {
+  private readonly binaryPath: string;
+  private readonly cwd: string;
+  private readonly packageJsonPath: string;
+
+  constructor(
+    private readonly smartshell: plugins.smartshell.Smartshell,
+    cwdArg: string,
+  ) {
+    this.cwd = plugins.path.resolve(cwdArg);
+    this.binaryPath = getProjectTsdockerBinPath(this.cwd);
+    this.packageJsonPath = plugins.path.join(
+      this.cwd,
+      "node_modules",
+      "@git.zone",
+      "tsdocker",
+      "package.json",
+    );
+  }
+
+  public async assertCapabilities(): Promise<IReleaseCapabilitiesResult> {
+    const installedVersion = await this.readInstalledVersion();
+    await plugins.fs.access(this.binaryPath);
+    const versionResult = await this.smartshell.execSpawn(
+      this.binaryPath,
+      ["--version"],
+      {
+        cwd: this.cwd,
+        maxBuffer: 4096,
+        silent: true,
+        timeout: 30_000,
+        timeoutKillGraceMs: 5_000,
+      },
+    );
+    if (
+      versionResult.exitCode !== 0 ||
+      versionResult.timedOut ||
+      versionResult.signal ||
+      versionResult.stderr !== "" ||
+      versionResult.stdout.trim() !== installedVersion
+    ) {
+      throw new Error(
+        "Docker release journal schema 2 requires one matching project-local @git.zone/tsdocker package and binary.",
+      );
+    }
+
+    const parsed = await this.run("release-capabilities");
+    return plugins.tsdockerReleaseProtocol.assertReleaseCapabilitiesResult(
+      parsed,
+      this.cwd,
+      {
+        requiredCommands: [
+          ...plugins.tsdockerReleaseProtocol.releaseProtocolCommands,
+        ],
+        requiredFeatures: [
+          ...plugins.tsdockerReleaseProtocol.releaseProtocolFeatures,
+        ],
+      },
+    );
+  }
+
+  public async validate(
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg?: string,
+  ): Promise<IReleaseValidationResult> {
+    const request = this.assertRequestForProject(requestArg);
+    const runValidation = async (
+      requestDirectory: string,
+      requestOwnerId: string,
+    ): Promise<IReleaseValidationResult> => {
+      const parsed = await this.run(
+        "release-validate",
+        request,
+        requestDirectory,
+        requestOwnerId,
+      );
+      return plugins.tsdockerReleaseProtocol.assertReleaseValidationResult(
+        parsed,
+        request,
+      );
+    };
+    if (requestDirectoryArg) {
+      return runValidation(
+        requestDirectoryArg,
+        plugins.crypto.randomBytes(16).toString("hex"),
+      );
+    }
+    return this.runWithTemporaryRequestDirectory(
+      "release-validate",
+      runValidation,
+      (valueArg) =>
+        plugins.tsdockerReleaseProtocol.assertReleaseValidationResult(
+          valueArg,
+          request,
+        ),
+    );
+  }
+
+  public async qualify(
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ): Promise<IReleaseQualificationResult> {
+    const request = this.assertRequestForProject(requestArg);
+    const parsed = await this.run(
+      "release-qualify",
+      request,
+      requestDirectoryArg,
+      requestOwnerIdArg,
+      ["--classified-errors"],
+    );
+    return assertReleaseQualificationResult(parsed, request);
+  }
+
+  public async probe(
+    requestArg: IReleaseQualificationRequest,
+    contextArg: IReleasePromotionContext,
+    requestDirectoryArg?: string,
+    requestOwnerIdArg?: string,
+  ): Promise<IReleaseProbeResult> {
+    const request = this.assertPromotionInvocation(requestArg, contextArg);
+    const runProbe = async (
+      requestDirectory: string,
+      requestOwnerId: string,
+    ): Promise<IReleaseProbeResult> => {
+      const parsed = await this.run(
+        "release-probe",
+        this.createPromotionRequest(
+          "tsdocker-release-probe-request",
+          request,
+          contextArg.promotionId,
+        ),
+        requestDirectory,
+        requestOwnerId,
+      );
+      return plugins.tsdockerReleaseProtocol.assertReleaseProbeResult(
+        parsed,
+        request,
+        contextArg,
+      );
+    };
+    if (
+      (requestDirectoryArg === undefined) !==
+      (requestOwnerIdArg === undefined)
+    ) {
+      throw new Error(
+        "tSDocker release probes require both request storage and owner, or neither.",
+      );
+    }
+    if (requestDirectoryArg && requestOwnerIdArg) {
+      return runProbe(requestDirectoryArg, requestOwnerIdArg);
+    }
+    return this.runWithTemporaryRequestDirectory(
+      "release-probe",
+      runProbe,
+      (valueArg) =>
+        plugins.tsdockerReleaseProtocol.assertReleaseProbeResult(
+          valueArg,
+          request,
+          contextArg,
+        ),
+    );
+  }
+
+  public async promote(
+    requestArg: IReleaseQualificationRequest,
+    contextArg: IReleasePromotionContext,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ): Promise<IReleasePromotionResult> {
+    const request = this.assertPromotionInvocation(requestArg, contextArg);
+    const parsed = await this.run(
+      "release-promote",
+      this.createPromotionRequest(
+        "tsdocker-release-promotion-request",
+        request,
+        contextArg.promotionId,
+      ),
+      requestDirectoryArg,
+      requestOwnerIdArg,
+    );
+    return plugins.tsdockerReleaseProtocol.assertReleasePromotionResult(
+      parsed,
+      request,
+      contextArg,
+    );
+  }
+
+  public async cleanup(
+    requestArg: IReleaseQualificationRequest,
+    requestDirectoryArg: string,
+    requestOwnerIdArg: string,
+  ): Promise<IReleaseCleanupResult> {
+    const request = this.assertRequestForProject(requestArg);
+    const parsed = await this.run(
+      "release-cleanup",
+      {
+        candidateId: request.candidateId,
+        kind: "tsdocker-release-cleanup-request",
+        projectId: request.projectId,
+        protocolVersion: 1,
+        schemaVersion: 1,
+      },
+      requestDirectoryArg,
+      requestOwnerIdArg,
+    );
+    return assertReleaseCleanupResult(parsed, request);
+  }
+
+  public async reclaimRequestFiles(
+    requestDirectoryArg: string,
+    retiredOwnerIdsArg: string[],
+  ): Promise<void> {
+    if (
+      retiredOwnerIdsArg.length === 0 ||
+      new Set(retiredOwnerIdsArg).size !== retiredOwnerIdsArg.length ||
+      retiredOwnerIdsArg.some(
+        (ownerIdArg) => !requestOwnerIdPattern.test(ownerIdArg),
+      )
+    ) {
+      throw new Error(
+        "tSDocker request reclamation requires unique exact retired owner IDs.",
+      );
+    }
+    const requestDirectory =
+      await this.assertRequestDirectory(requestDirectoryArg);
+    const retiredOwnerIds = new Set(retiredOwnerIdsArg);
+    const callerUid = process.getuid?.();
+    const entries = await plugins.fs.readdir(requestDirectory, {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      const match = entry.name.match(requestFilePattern);
+      if (!match || !retiredOwnerIds.has(match[1])) continue;
+      const requestPath = plugins.path.join(requestDirectory, entry.name);
+      let requestStat;
+      try {
+        requestStat = await plugins.fs.lstat(requestPath);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw error;
+      }
+      if (
+        !entry.isFile() ||
+        !requestStat.isFile() ||
+        requestStat.isSymbolicLink() ||
+        (callerUid !== undefined && requestStat.uid !== callerUid) ||
+        (requestStat.mode & 0o077) !== 0 ||
+        requestStat.size > requestByteLimit
+      ) {
+        throw new Error(
+          `Retired tSDocker request file is unsafe: ${requestPath}`,
+        );
+      }
+      await plugins.fs.rm(requestPath);
+    }
+  }
+
+  private async readInstalledVersion(): Promise<string> {
+    const packageHandle = await plugins.fs.open(
+      this.packageJsonPath,
+      plugins.fsConstants.O_RDONLY | plugins.fsConstants.O_NOFOLLOW,
+    );
+    let packageJson: unknown;
+    try {
+      const before = await packageHandle.stat();
+      if (
+        !before.isFile() ||
+        before.size <= 0 ||
+        before.size > packageJsonByteLimit
+      ) {
+        throw new Error(
+          "Project-local @git.zone/tsdocker package metadata is unavailable or unsafe.",
+        );
+      }
+      const bytes = await packageHandle.readFile();
+      const after = await packageHandle.stat();
+      if (
+        before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.size !== after.size ||
+        before.mtimeMs !== after.mtimeMs ||
+        before.ctimeMs !== after.ctimeMs ||
+        bytes.byteLength !== before.size
+      ) {
+        throw new Error(
+          "Project-local @git.zone/tsdocker package metadata changed while being read.",
+        );
+      }
+      packageJson = JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+      );
+    } catch (error) {
+      throw new Error(
+        "Project-local @git.zone/tsdocker package metadata is invalid.",
+        { cause: error },
+      );
+    } finally {
+      await packageHandle.close();
+    }
+    if (
+      !isPlainObject(packageJson) ||
+      packageJson.name !== "@git.zone/tsdocker" ||
+      typeof packageJson.version !== "string" ||
+      !supportsTsdockerMinimumVersion(
+        packageJson.version,
+        minimumReleaseVersion,
+      )
+    ) {
+      throw new Error(
+        "Docker release journal schema 2 requires project-local @git.zone/tsdocker >= 3.5.1.",
+      );
+    }
+    return packageJson.version;
+  }
+
+  private assertRequestForProject(
+    requestArg: IReleaseQualificationRequest,
+  ): IReleaseQualificationRequest {
+    return plugins.tsdockerReleaseProtocol.assertReleaseQualificationRequestForProject(
+      requestArg,
+      this.cwd,
+    );
+  }
+
+  private assertPromotionInvocation(
+    requestArg: IReleaseQualificationRequest,
+    contextArg: IReleasePromotionContext,
+  ): IReleaseQualificationRequest {
+    return plugins.tsdockerReleaseProtocol.assertReleasePromotionInvocation({
+      ...contextArg,
+      request: requestArg,
+    });
+  }
+
+  private createPromotionRequest(
+    kindArg:
+      "tsdocker-release-probe-request" | "tsdocker-release-promotion-request",
+    requestArg: IReleaseQualificationRequest,
+    promotionIdArg: string,
+  ): Record<string, unknown> {
+    return {
+      candidateId: requestArg.candidateId,
+      kind: kindArg,
+      projectId: requestArg.projectId,
+      promotionId: promotionIdArg,
+      protocolVersion: 1,
+      schemaVersion: 1,
+    };
+  }
+
+  private async assertRequestDirectory(
+    requestDirectoryArg: string,
+  ): Promise<string> {
+    const requestDirectory = plugins.path.resolve(requestDirectoryArg);
+    const directoryStat = await plugins.fs.lstat(requestDirectory);
+    const callerUid = process.getuid?.();
+    if (
+      !directoryStat.isDirectory() ||
+      directoryStat.isSymbolicLink() ||
+      (callerUid !== undefined && directoryStat.uid !== callerUid) ||
+      (directoryStat.mode & 0o077) !== 0
+    ) {
+      throw new Error(
+        "tSDocker release request storage must be a private owned directory.",
+      );
+    }
+    return requestDirectory;
+  }
+
+  private async runWithTemporaryRequestDirectory<T>(
+    commandArg: "release-validate" | "release-probe",
+    operationArg: (
+      requestDirectoryArg: string,
+      requestOwnerIdArg: string,
+    ) => Promise<T>,
+    assertResultArg: (valueArg: unknown) => T,
+  ): Promise<T> {
+    const temporaryRoot = await plugins.fs.realpath(plugins.os.tmpdir());
+    const temporaryDirectory = await plugins.fs.mkdtemp(
+      plugins.path.join(temporaryRoot, `gitzone-tsdocker-${commandArg}-`),
+    );
+    let result: T | undefined;
+    let operationError: unknown;
+    try {
+      await plugins.fs.chmod(temporaryDirectory, 0o700);
+      result = await operationArg(
+        temporaryDirectory,
+        plugins.crypto.randomBytes(16).toString("hex"),
+      );
+    } catch (error) {
+      operationError = error;
+    }
+
+    let directoryCleanupError: unknown;
+    try {
+      await plugins.fs.rm(temporaryDirectory, {
+        recursive: true,
+        force: false,
+      });
+    } catch (error) {
+      directoryCleanupError = error;
+    }
+    if (directoryCleanupError) {
+      if (operationError instanceof TsdockerReleaseRequestCleanupError) {
+        operationError.reclamationError = directoryCleanupError;
+        throw operationError;
+      }
+      throw new TsdockerReleaseRequestCleanupError(
+        commandArg,
+        temporaryDirectory,
+        operationError,
+        result,
+        directoryCleanupError,
+      );
+    }
+    if (operationError instanceof TsdockerReleaseRequestCleanupError) {
+      if (operationError.result !== undefined) {
+        return assertResultArg(operationError.result);
+      }
+      if (operationError.commandError !== undefined) {
+        throw operationError.commandError;
+      }
+      throw operationError;
+    }
+    if (operationError) throw operationError;
+    return result!;
+  }
+
+  private async run(
+    commandArg: TReleaseProtocolCommand,
+    requestArg?: unknown,
+    requestDirectoryArg?: string,
+    requestOwnerIdArg?: string,
+    extraArgsArg: string[] = [],
+  ): Promise<unknown> {
+    let requestPath = "";
+    let requestCreated = false;
+    let requestIdentity:
+      { dev: number; ino: number; mode: number; uid: number } | undefined;
+    let commandError: unknown;
+    let result: unknown;
+    let hasResult = false;
+
+    try {
+      const args: string[] = [commandArg];
+      if (requestArg !== undefined) {
+        if (
+          !requestDirectoryArg ||
+          !requestOwnerIdArg ||
+          !requestOwnerIdPattern.test(requestOwnerIdArg)
+        ) {
+          throw new Error(
+            "tSDocker release request storage and exact owner are required.",
+          );
+        }
+        const requestDirectory =
+          await this.assertRequestDirectory(requestDirectoryArg);
+        requestPath = plugins.path.join(
+          requestDirectory,
+          `.tsdocker-request.${requestOwnerIdArg}.${commandArg}.${plugins.crypto
+            .randomBytes(12)
+            .toString("hex")}.json`,
+        );
+        const document = canonicalReleaseJsonDocument(requestArg);
+        if (Buffer.byteLength(document) > requestByteLimit) {
+          throw new Error("tSDocker release request exceeds 64 KiB.");
+        }
+        const callerUid = process.getuid?.();
+        const handle = await plugins.fs.open(
+          requestPath,
+          plugins.fsConstants.O_WRONLY |
+            plugins.fsConstants.O_CREAT |
+            plugins.fsConstants.O_EXCL |
+            plugins.fsConstants.O_NOFOLLOW,
+          0o600,
+        );
+        requestCreated = true;
+        try {
+          const openedStat = await handle.stat();
+          if (
+            !openedStat.isFile() ||
+            (callerUid !== undefined && openedStat.uid !== callerUid) ||
+            (openedStat.mode & 0o077) !== 0
+          ) {
+            throw new Error("tSDocker release request file is unsafe.");
+          }
+          requestIdentity = {
+            dev: openedStat.dev,
+            ino: openedStat.ino,
+            mode: openedStat.mode,
+            uid: openedStat.uid,
+          };
+          await handle.writeFile(document, "utf8");
+          await handle.sync();
+          const requestStat = await handle.stat();
+          if (
+            !requestStat.isFile() ||
+            (callerUid !== undefined && requestStat.uid !== callerUid) ||
+            (requestStat.mode & 0o077) !== 0 ||
+            requestStat.size !== Buffer.byteLength(document)
+          ) {
+            throw new Error("tSDocker release request file is unsafe.");
+          }
+          requestIdentity = {
+            dev: requestStat.dev,
+            ino: requestStat.ino,
+            mode: requestStat.mode,
+            uid: requestStat.uid,
+          };
+        } finally {
+          await handle.close();
+        }
+        args.push(`--request-file=${requestPath}`, ...extraArgsArg);
+      } else if (extraArgsArg.length > 0) {
+        throw new Error("tSDocker request flags require a request payload.");
+      }
+
+      const commandResult = await this.smartshell.execSpawn(
+        this.binaryPath,
+        args,
+        {
+          cwd: this.cwd,
+          maxBuffer: responseByteLimit + 1,
+          silent: true,
+          timeout: commandTimeouts[commandArg],
+          timeoutKillGraceMs:
+            commandArg === "release-qualify" || commandArg === "release-promote"
+              ? 3 * 60_000
+              : 30_000,
+        },
+      );
+      result = parseProtocolOutput(commandResult, commandArg);
+      hasResult = true;
+    } catch (error) {
+      commandError = error;
+    }
+
+    let cleanupError: unknown;
+    if (requestCreated) {
+      try {
+        if (!requestIdentity) {
+          throw new Error(
+            "tSDocker release request was created without a cleanup identity.",
+          );
+        }
+        const currentStat = await plugins.fs.lstat(requestPath);
+        if (
+          !currentStat.isFile() ||
+          currentStat.isSymbolicLink() ||
+          currentStat.dev !== requestIdentity.dev ||
+          currentStat.ino !== requestIdentity.ino ||
+          currentStat.mode !== requestIdentity.mode ||
+          currentStat.uid !== requestIdentity.uid
+        ) {
+          throw new Error(
+            "tSDocker release request changed before caller cleanup.",
+          );
+        }
+        await plugins.fs.rm(requestPath);
+      } catch (error) {
+        cleanupError = error;
+      }
+    }
+
+    if (cleanupError) {
+      throw new TsdockerReleaseRequestCleanupError(
+        commandArg,
+        requestPath,
+        commandError,
+        hasResult ? result : undefined,
+        cleanupError,
+      );
+    }
+    if (commandError) throw commandError;
+    return result;
+  }
+}