create-windy 0.6.6 → 0.6.8

package/template/packages/delivery/src/delivery.test.ts

@@ -0,0 +1,332 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDeterministicTarGz, listTarGzEntries } from "./archive.js";
+import {
+  ingestArchiveFiles,
+  inventoryBlobs,
+  partialBlobSize,
+  receiveBlobChunk,
+} from "./blob-store.js";
+import { sha256Bytes } from "./digest.js";
+import { manifestDigest, readManifest } from "./manifest.js";
+import { negotiateDelivery } from "./negotiation.js";
+import {
+  acquireDeliveryLock,
+  cleanupStaging,
+  releaseDeliveryLock,
+  stageRelease,
+} from "./staging.js";
+import { planBlobTransfer } from "./transfer.js";
+import type {
+  ContentBlob,
+  DeliveryCapabilities,
+  DeliveryManifestV2,
+} from "./types.js";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    roots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe("内容寻址增量交付", () => {
+  test("首次全量传输，第二次仅 Web 变化", () => {
+    const base = blob("base", 100);
+    const server = blob("server-v1", 200);
+    const webV1 = blob("web-v1", 300);
+    const first = planBlobTransfer([base, server, webV1], new Set());
+    expect(first.statistics).toEqual({
+      totalBytes: 600,
+      reusedBytes: 0,
+      uploadedBytes: 600,
+      totalBlobs: 3,
+      reusedBlobs: 0,
+      uploadedBlobs: 3,
+    });
+    const webV2 = blob("web-v2", 320);
+    const second = planBlobTransfer(
+      [base, server, webV2],
+      new Set([base.digest, server.digest, webV1.digest]),
+    );
+    expect(second.missing).toEqual([webV2]);
+    expect(second.statistics.reusedBytes).toBe(300);
+    expect(second.statistics.uploadedBytes).toBe(320);
+  });
+
+  test("Server 与 Web 同时变化只上传两个新 blob", () => {
+    const base = blob("base", 100);
+    const oldServer = blob("server-v1", 200);
+    const oldWeb = blob("web-v1", 300);
+    const server = blob("server-v2", 210);
+    const web = blob("web-v2", 320);
+    const result = planBlobTransfer(
+      [base, server, web],
+      new Set([base.digest, oldServer.digest, oldWeb.digest]),
+    );
+    expect(result.missing).toEqual([server, web].sort(byDigest));
+    expect(result.statistics.uploadedBlobs).toBe(2);
+    expect(result.statistics.reusedBytes).toBe(100);
+  });
+
+  test("远端损坏 blob 不计入复用且 stage fail closed", async () => {
+    const root = await temporaryRoot();
+    const store = join(root, "store");
+    const archive = join(root, "archive");
+    await mkdir(archive);
+    await writeFile(join(archive, "manifest.json"), "valid");
+    const graph = await ingestArchiveFiles(archive, ["manifest.json"], store);
+    await writeFile(
+      join(store, "blobs/sha256", graph.blobs[0]!.digest.slice(7)),
+      "broken",
+    );
+    expect((await inventoryBlobs(store, graph.blobs)).size).toBe(0);
+    const install = join(root, "install");
+    await mkdir(install);
+    const lock = await acquireDeliveryLock(install);
+    const manifest = releaseManifest(graph.entries, graph.blobs);
+    await expect(
+      stageRelease({
+        installRoot: install,
+        storeRoot: store,
+        manifest,
+        expectedManifestDigest: manifestDigest(manifest),
+        lock,
+        reserveBytes: 0,
+      }),
+    ).rejects.toThrow("blob 不完整或损坏");
+    await releaseDeliveryLock(lock);
+  });
+
+  test("传输中断后从已验明 offset 恢复", async () => {
+    const root = await temporaryRoot();
+    const bytes = new TextEncoder().encode("resumable-content");
+    const target = { digest: sha256Bytes(bytes), size: bytes.byteLength };
+    const first = await receiveBlobChunk({
+      storeRoot: root,
+      blob: target,
+      offset: 0,
+      bytes: bytes.slice(0, 8),
+    });
+    expect(first.complete).toBeFalse();
+    expect(await partialBlobSize(root, target)).toBe(8);
+    await expect(
+      receiveBlobChunk({
+        storeRoot: root,
+        blob: target,
+        offset: 7,
+        bytes: bytes.slice(8),
+      }),
+    ).rejects.toThrow("offset 不匹配");
+    const resumed = await receiveBlobChunk({
+      storeRoot: root,
+      blob: target,
+      offset: 8,
+      bytes: bytes.slice(8),
+    });
+    expect(resumed.complete).toBeTrue();
+    expect(
+      (await inventoryBlobs(root, [target])).has(target.digest),
+    ).toBeTrue();
+  });
+
+  test("越界传输回退 partial 到调用前 offset", async () => {
+    const root = await temporaryRoot();
+    const target = { digest: sha256Bytes("1234"), size: 4 };
+    await expect(
+      receiveBlobChunk({
+        storeRoot: root,
+        blob: target,
+        offset: 0,
+        bytes: new TextEncoder().encode("12345"),
+      }),
+    ).rejects.toThrow("超出声明尺寸");
+    expect(await partialBlobSize(root, target)).toBe(0);
+  });
+
+  test("相同 manifest 的 stage 幂等且落盘字节绑定同一 digest", async () => {
+    const root = await temporaryRoot();
+    const archive = join(root, "archive");
+    const store = join(root, "store");
+    const install = join(root, "install");
+    await mkdir(archive);
+    await mkdir(install);
+    await writeFile(join(archive, "manifest.json"), "{}\n");
+    const graph = await ingestArchiveFiles(archive, ["manifest.json"], store);
+    const manifest = releaseManifest(graph.entries, graph.blobs);
+    const digest = manifestDigest(manifest);
+    const lock = await acquireDeliveryLock(install);
+    const input = {
+      installRoot: install,
+      storeRoot: store,
+      manifest,
+      expectedManifestDigest: digest,
+      lock,
+      reserveBytes: 0,
+    };
+    const first = await stageRelease(input);
+    expect(await stageRelease(input)).toBe(first);
+    expect(
+      (
+        await readFile(join(first, "..", "DELIVERY-MANIFEST.sha256"), "utf8")
+      ).trim(),
+    ).toBe(digest);
+    await releaseDeliveryLock(lock);
+  });
+
+  test("manifest 与 digest 篡改均被拒绝", async () => {
+    const root = await temporaryRoot();
+    const path = join(root, "manifest.json");
+    const manifest = releaseManifest(
+      [{ path: "manifest.json", ...blob("archive", 10), mode: 0o644 }],
+      [blob("archive", 10)],
+    );
+    const expected = manifestDigest(manifest);
+    await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+    await expect(readManifest(path, expected)).resolves.toEqual(manifest);
+    const tampered = { ...manifest, releaseId: "tampered" };
+    await writeFile(path, `${JSON.stringify(tampered, null, 2)}\n`);
+    await expect(readManifest(path, expected)).rejects.toThrow("digest 不匹配");
+  });
+
+  test("并发部署只能有一个 owner，失败清理不越过锁", async () => {
+    const root = await temporaryRoot();
+    const first = await acquireDeliveryLock(root);
+    await expect(acquireDeliveryLock(root)).rejects.toThrow("并发交付");
+    await cleanupStaging(root, first);
+    await releaseDeliveryLock(first);
+    const second = await acquireDeliveryLock(root);
+    await releaseDeliveryLock(second);
+  });
+
+  test("schema negotiation 优先 registry digest，旧端显式回退 V1", () => {
+    const content = blob("archive", 10);
+    const manifest = releaseManifest(
+      [{ path: "manifest.json", ...content, mode: 0o644 }],
+      [content],
+      true,
+    );
+    const modern = capabilities({ registryByDigest: true });
+    expect(negotiateDelivery(manifest, modern)).toEqual({
+      mode: "registry",
+      images: [
+        {
+          role: "server",
+          reference: `registry.example.com/windy/server@${manifest.images[0]!.registry!.digest}`,
+        },
+      ],
+    });
+    const legacy = capabilities({
+      schemaVersions: [1],
+      registryByDigest: false,
+      blobDelta: false,
+      resumableBlobTransfer: false,
+    });
+    expect(negotiateDelivery(manifest, legacy)).toMatchObject({
+      mode: "full-bundle",
+      schemaVersion: 1,
+      file: "windy-full.tar.gz",
+    });
+  });
+});
+
+describe("macOS 到 Linux 的确定性归档", () => {
+  test("显式文件集合不携带 AppleDouble，重复归档字节一致", async () => {
+    const root = await temporaryRoot();
+    const input = join(root, "input");
+    await mkdir(input);
+    await writeFile(join(input, "manifest.json"), "{}\n");
+    await writeFile(join(input, "._manifest.json"), "simulated xattr sidecar");
+    const first = join(root, "first.tar.gz");
+    const second = join(root, "second.tar.gz");
+    const entries = [
+      { source: join(input, "manifest.json"), path: "manifest.json" },
+    ];
+    await createDeterministicTarGz(first, entries);
+    await createDeterministicTarGz(second, entries);
+    expect(await listTarGzEntries(first)).toEqual(["manifest.json"]);
+    expect(await readFile(first)).toEqual(await readFile(second));
+    const extracted = join(root, "linux-extracted");
+    await mkdir(extracted);
+    const process = Bun.spawn(["tar", "-xzf", first, "-C", extracted], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...globalThis.process.env, COPYFILE_DISABLE: "1" },
+    });
+    expect(await process.exited).toBe(0);
+    expect(await readFile(join(extracted, "manifest.json"), "utf8")).toBe(
+      "{}\n",
+    );
+  });
+});
+
+function blob(seed: string, size: number): ContentBlob {
+  return { digest: sha256Bytes(seed), size };
+}
+
+function releaseManifest(
+  entries: DeliveryManifestV2["dockerArchive"]["entries"],
+  blobs: ContentBlob[],
+  withFallback = false,
+): DeliveryManifestV2 {
+  const imageDigest = blobs[0]!.digest;
+  return {
+    schemaVersion: 2,
+    minimumReaderVersion: 2,
+    product: "windy",
+    releaseId: "release-1",
+    gitSha: "a".repeat(40),
+    platform: "linux/amd64",
+    createdAt: "2026-08-07T00:00:00.000Z",
+    images: [
+      {
+        role: "server",
+        platform: "linux/amd64",
+        configDigest: imageDigest,
+        registry: {
+          repository: "registry.example.com/windy/server",
+          digest: imageDigest,
+          layers: [blobs[0]!],
+        },
+      },
+    ],
+    dockerArchive: { format: "oci-image-layout-v1", entries },
+    releaseFiles: [],
+    blobs,
+    compatibility: withFallback
+      ? {
+          fullBundle: {
+            schemaVersion: 1,
+            file: "windy-full.tar.gz",
+            digest: sha256Bytes("fallback"),
+            size: 1000,
+          },
+        }
+      : {},
+  };
+}
+
+function capabilities(
+  overrides: Partial<DeliveryCapabilities> = {},
+): DeliveryCapabilities {
+  return {
+    schemaVersions: [1, 2],
+    registryByDigest: false,
+    blobDelta: true,
+    resumableBlobTransfer: true,
+    ...overrides,
+  };
+}
+
+async function temporaryRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "windy-delivery-test-"));
+  roots.push(root);
+  return root;
+}
+
+function byDigest(left: ContentBlob, right: ContentBlob): number {
+  return left.digest.localeCompare(right.digest);
+}

package/template/packages/delivery/src/digest.ts

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import type { Sha256Digest } from "./types.js";
+
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+
+export function sha256Bytes(value: Uint8Array | string): Sha256Digest {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+export async function sha256File(path: string): Promise<Sha256Digest> {
+  const hash = createHash("sha256");
+  await new Promise<void>((resolve, reject) => {
+    const stream = createReadStream(path);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", resolve);
+  });
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function assertSha256Digest(value: unknown): Sha256Digest {
+  if (typeof value !== "string" || !digestPattern.test(value)) {
+    throw new Error("无效的 sha256 digest");
+  }
+  return value as Sha256Digest;
+}
+
+export function digestHex(digest: Sha256Digest): string {
+  return digest.slice("sha256:".length);
+}

package/template/packages/delivery/src/manifest.ts

@@ -0,0 +1,255 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { assertSha256Digest, sha256Bytes } from "./digest.js";
+import { assertRelativePortablePath, assertSafeName } from "./paths.js";
+import type {
+  ArchiveEntry,
+  ContentBlob,
+  DeliveryManifestV2,
+  ReleaseImageV2,
+  ReleasePlatform,
+  Sha256Digest,
+} from "./types.js";
+
+export function canonicalManifestJson(manifest: DeliveryManifestV2): string {
+  const normalized = validateManifest(manifest);
+  return `${JSON.stringify(normalized, null, 2)}\n`;
+}
+
+export function manifestDigest(manifest: DeliveryManifestV2): Sha256Digest {
+  return sha256Bytes(canonicalManifestJson(manifest));
+}
+
+export async function writeManifest(
+  path: string,
+  manifest: DeliveryManifestV2,
+): Promise<Sha256Digest> {
+  const json = canonicalManifestJson(manifest);
+  await writeFile(path, json, { flag: "wx" });
+  return sha256Bytes(json);
+}
+
+export async function readManifest(
+  path: string,
+  expectedDigest?: Sha256Digest,
+): Promise<DeliveryManifestV2> {
+  const json = await readFile(path, "utf8");
+  if (expectedDigest && sha256Bytes(json) !== expectedDigest) {
+    throw new Error("release manifest digest 不匹配");
+  }
+  return validateManifest(JSON.parse(json));
+}
+
+export function validateManifest(value: unknown): DeliveryManifestV2 {
+  const root = record(value, "manifest");
+  if (root.schemaVersion !== 2 || root.minimumReaderVersion !== 2) {
+    throw new Error("不支持的 delivery manifest schema");
+  }
+  const product = assertSafeName(string(root.product, "product"), "product");
+  const releaseId = assertSafeName(
+    string(root.releaseId, "releaseId"),
+    "releaseId",
+  );
+  const gitSha = string(root.gitSha, "gitSha");
+  if (!/^[a-f0-9]{40}$/.test(gitSha)) throw new Error("gitSha 无效");
+  const platform = parsePlatform(root.platform);
+  const createdAt = string(root.createdAt, "createdAt");
+  if (Number.isNaN(Date.parse(createdAt))) throw new Error("createdAt 无效");
+  if (!Array.isArray(root.images) || root.images.length === 0) {
+    throw new Error("manifest images 不能为空");
+  }
+  const images = root.images.map((image) => parseImage(image, platform));
+  assertUnique(
+    images.map(({ role }) => role),
+    "镜像 role",
+  );
+  const archive = record(root.dockerArchive, "dockerArchive");
+  if (archive.format !== "oci-image-layout-v1") {
+    throw new Error("dockerArchive format 不受支持");
+  }
+  if (!Array.isArray(archive.entries) || archive.entries.length === 0) {
+    throw new Error("dockerArchive entries 不能为空");
+  }
+  const entries = archive.entries.map(parseEntry).sort(byPath);
+  assertUnique(
+    entries.map(({ path }) => path),
+    "archive path",
+  );
+  if (!Array.isArray(root.releaseFiles)) {
+    throw new Error("releaseFiles 必须是数组");
+  }
+  const releaseFiles = root.releaseFiles.map(parseEntry).sort(byPath);
+  assertUnique(
+    releaseFiles.map(({ path }) => path),
+    "release file path",
+  );
+  if (releaseFiles.some(({ path }) => path === "images.tar")) {
+    throw new Error("releaseFiles 不得重复声明 images.tar");
+  }
+  if (!Array.isArray(root.blobs) || root.blobs.length === 0) {
+    throw new Error("manifest blobs 不能为空");
+  }
+  const blobs = root.blobs.map(parseBlob).sort(byDigest);
+  assertUnique(
+    blobs.map(({ digest }) => digest),
+    "blob digest",
+  );
+  const blobSizes = new Map(blobs.map((blob) => [blob.digest, blob.size]));
+  for (const entry of [...entries, ...releaseFiles]) {
+    if (blobSizes.get(entry.digest) !== entry.size) {
+      throw new Error(`archive entry 未绑定同尺寸 blob：${entry.path}`);
+    }
+  }
+  const imageBlobSizes = new Map(
+    entries.map(({ digest, size }) => [digest, size]),
+  );
+  for (const image of images) {
+    if (!imageBlobSizes.has(image.configDigest)) {
+      throw new Error(`镜像 config digest 未绑定 OCI blob：${image.role}`);
+    }
+    if (!image.registry) continue;
+    if (!imageBlobSizes.has(image.registry.digest)) {
+      throw new Error(`镜像 manifest digest 未绑定 OCI blob：${image.role}`);
+    }
+    for (const layer of image.registry.layers) {
+      if (imageBlobSizes.get(layer.digest) !== layer.size) {
+        throw new Error(`镜像 layer 未绑定同尺寸 OCI blob：${image.role}`);
+      }
+    }
+  }
+  const compatibility = record(root.compatibility, "compatibility");
+  const fullBundle = compatibility.fullBundle
+    ? parseFallback(compatibility.fullBundle)
+    : undefined;
+  return {
+    schemaVersion: 2,
+    minimumReaderVersion: 2,
+    product,
+    releaseId,
+    gitSha,
+    platform,
+    createdAt,
+    images,
+    dockerArchive: { format: "oci-image-layout-v1", entries },
+    releaseFiles,
+    blobs,
+    compatibility: { ...(fullBundle ? { fullBundle } : {}) },
+  };
+}
+
+function parseImage(value: unknown, platform: ReleasePlatform): ReleaseImageV2 {
+  const item = record(value, "images[]");
+  const imagePlatform = parsePlatform(item.platform);
+  if (imagePlatform !== platform) throw new Error("镜像平台与 release 不一致");
+  const registry = item.registry
+    ? (() => {
+        const value = record(item.registry, "image.registry");
+        const repository = string(value.repository, "repository");
+        if (!validRegistryRepository(repository)) {
+          throw new Error(
+            "registry repository 必须是不含 tag、digest、凭据的 OCI repository",
+          );
+        }
+        if (!Array.isArray(value.layers) || value.layers.length === 0) {
+          throw new Error("registry layers 不能为空");
+        }
+        const layers = value.layers.map(parseBlob).sort(byDigest);
+        assertUnique(
+          layers.map(({ digest }) => digest),
+          "registry layer digest",
+        );
+        return {
+          repository,
+          digest: assertSha256Digest(value.digest),
+          layers,
+        };
+      })()
+    : undefined;
+  return {
+    role: assertSafeName(string(item.role, "image.role"), "image.role"),
+    platform: imagePlatform,
+    configDigest: assertSha256Digest(item.configDigest),
+    ...(registry ? { registry } : {}),
+  };
+}
+
+function validRegistryRepository(value: string): boolean {
+  const match =
+    /^([a-z0-9]+(?:[._-][a-z0-9]+)*)(?::([0-9]{1,5}))?(\/[a-z0-9]+(?:[._-][a-z0-9]+)*)+$/.exec(
+      value,
+    );
+  if (!match || value.includes("@") || value.includes("://")) return false;
+  const port = match[2] ? Number(match[2]) : undefined;
+  return port === undefined || (port > 0 && port <= 65_535);
+}
+
+function parseEntry(value: unknown): ArchiveEntry {
+  const entry = record(value, "dockerArchive.entries[]");
+  const mode = number(entry.mode, "entry.mode");
+  if (!Number.isInteger(mode) || mode < 0 || mode > 0o777) {
+    throw new Error("archive entry mode 无效");
+  }
+  return {
+    path: assertRelativePortablePath(string(entry.path, "entry.path")),
+    digest: assertSha256Digest(entry.digest),
+    size: safeSize(entry.size),
+    mode,
+  };
+}
+
+function parseBlob(value: unknown): ContentBlob {
+  const blob = record(value, "blobs[]");
+  return { digest: assertSha256Digest(blob.digest), size: safeSize(blob.size) };
+}
+
+function parseFallback(value: unknown) {
+  const fallback = record(value, "compatibility.fullBundle");
+  if (fallback.schemaVersion !== 1) throw new Error("fallback schema 必须为 1");
+  return {
+    schemaVersion: 1 as const,
+    file: assertRelativePortablePath(string(fallback.file, "fallback.file")),
+    digest: assertSha256Digest(fallback.digest),
+    size: safeSize(fallback.size),
+  };
+}
+
+function parsePlatform(value: unknown): ReleasePlatform {
+  if (value !== "linux/amd64" && value !== "linux/arm64") {
+    throw new Error("release platform 不受支持");
+  }
+  return value;
+}
+
+function safeSize(value: unknown): number {
+  const result = number(value, "size");
+  if (!Number.isSafeInteger(result) || result < 0) throw new Error("size 无效");
+  return result;
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} 必须是对象`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function string(value: unknown, label: string): string {
+  if (typeof value !== "string") throw new Error(`${label} 必须是字符串`);
+  return value;
+}
+
+function number(value: unknown, label: string): number {
+  if (typeof value !== "number") throw new Error(`${label} 必须是数字`);
+  return value;
+}
+
+function assertUnique(values: readonly string[], label: string): void {
+  if (new Set(values).size !== values.length) throw new Error(`${label} 重复`);
+}
+
+function byPath(left: ArchiveEntry, right: ArchiveEntry): number {
+  return left.path.localeCompare(right.path);
+}
+
+function byDigest(left: ContentBlob, right: ContentBlob): number {
+  return left.digest.localeCompare(right.digest);
+}

package/template/packages/delivery/src/negotiation.ts

@@ -0,0 +1,68 @@
+import type {
+  DeliveryCapabilities,
+  DeliveryManifestV2,
+  Sha256Digest,
+} from "./types.js";
+
+export type DeliverySelection =
+  | { mode: "registry"; images: { role: string; reference: string }[] }
+  | { mode: "blob-delta"; schemaVersion: 2 }
+  | {
+      mode: "full-bundle";
+      schemaVersion: 1;
+      file: string;
+      digest: Sha256Digest;
+    };
+
+export function negotiateDelivery(
+  manifest: DeliveryManifestV2,
+  capabilities: DeliveryCapabilities,
+  preference: "auto" | "registry" | "blob-delta" | "full-bundle" = "auto",
+): DeliverySelection {
+  const registry = registrySelection(manifest, capabilities);
+  const delta =
+    capabilities.schemaVersions.includes(2) &&
+    capabilities.blobDelta &&
+    capabilities.resumableBlobTransfer
+      ? ({ mode: "blob-delta", schemaVersion: 2 } as const)
+      : undefined;
+  const fallback = manifest.compatibility.fullBundle
+    ? {
+        mode: "full-bundle" as const,
+        schemaVersion: 1 as const,
+        file: manifest.compatibility.fullBundle.file,
+        digest: manifest.compatibility.fullBundle.digest,
+      }
+    : undefined;
+  if (preference === "registry") return required(registry, "registry digest");
+  if (preference === "blob-delta") return required(delta, "OCI blob 差量");
+  if (preference === "full-bundle")
+    return required(fallback, "完整 bundle fallback");
+  const selected = registry ?? delta ?? fallback;
+  if (!selected) throw new Error("客户端与安装端没有共同支持的交付 schema");
+  return selected;
+}
+
+function registrySelection(
+  manifest: DeliveryManifestV2,
+  capabilities: DeliveryCapabilities,
+): DeliverySelection | undefined {
+  if (!capabilities.registryByDigest) return undefined;
+  const images = manifest.images.map((image) => {
+    if (!image.registry) return undefined;
+    return {
+      role: image.role,
+      reference: `${image.registry.repository}@${image.registry.digest}`,
+    };
+  });
+  if (images.some((image) => !image)) return undefined;
+  return {
+    mode: "registry",
+    images: images as { role: string; reference: string }[],
+  };
+}
+
+function required<T>(value: T | undefined, label: string): T {
+  if (!value) throw new Error(`目标不支持请求的${label}交付模式`);
+  return value;
+}