import { readFile } from "node:fs/promises"; import path from "node:path"; import { z } from "zod"; /** * 1103/12-07. The product's own part of CI, kept out of the template-owned * config/ci/gates.json so a template sync never meets it. The template ships * this file empty and does not change it. It may hold only: * * - `deployment`: the package script that deploys the promoted release, and * its `vars.*` / `secrets.*` bindings. The template renders the rest of the * slot (download the promoted-release transfer, extract it against the * candidate digest, then run the script); secrets reach the deploy step only * (1103/13-05). * - `mergeGates`: product checks that run on every merge-stage run, in a job * of their own (`product_merge_gate`). Their ids are `PRODUCT-GATE-NNN`, so * they never take or change a template gate (`FE-GATE-NNN`), its commands, * artifacts or readiness formula. The template contract baseline counts * only the template contract. */ export const PRODUCT_CI_OVERLAY_PATH = "config/ci/product-gates.json"; const scriptName = z .string() .max(128) .regex(/^[A-Za-z0-9:_-]+$/u, "a product script is a package script name ([A-Za-z0-9:_-])"); const binding = z .object({ name: z.string().regex(/^[A-Z][A-Z0-9_]*$/u), value: z .string() .regex( /^\$\{\{ (?:vars|secrets)\.[A-Za-z_][A-Za-z0-9_]* \}\}$/u, "a product binding must be a vars.* or secrets.* value", ), }) .strict(); const productGate = z .object({ id: z .string() .regex(/^PRODUCT-GATE-\d{3}$/u, "product gate ids are PRODUCT-GATE-NNN; FE-GATE-NNN ids belong to the template"), name: z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/u), script: scriptName, }) .strict(); const productCiOverlaySchema = z .object({ schemaVersion: z.literal(1), deployment: z .object({ script: scriptName, environment: z.array(binding).max(32) }) .strict() .nullable(), mergeGates: z.array(productGate).max(32), }) .strict() .superRefine((overlay, context) => { const issue = (message: string) => context.addIssue({ code: "custom", message }); const names = overlay.deployment?.environment.map(({ name }) => name) ?? []; if (new Set(names).size !== names.length) issue("duplicate deployment binding name"); if (names.includes("CANDIDATE_ARCHIVE_SHA256")) { issue("CANDIDATE_ARCHIVE_SHA256 is bound by the template to the immutable_build digest"); } for (const field of ["id", "name"] as const) { const values = overlay.mergeGates.map((gate) => gate[field]); if (new Set(values).size !== values.length) issue(`duplicate product gate ${field}`); } }); export type ProductCiOverlay = z.infer; export type ProductDeployment = NonNullable; export type ProductGate = ProductCiOverlay["mergeGates"][number]; const EMPTY_PRODUCT_CI_OVERLAY: ProductCiOverlay = Object.freeze({ schemaVersion: 1, deployment: null, mergeGates: [], }); export function parseProductCiOverlay(value: unknown): ProductCiOverlay { const result = productCiOverlaySchema.safeParse(value); if (!result.success) { throw new TypeError( `${PRODUCT_CI_OVERLAY_PATH} invalid:\n${result.error.issues .map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`) .join("\n")}`, ); } return result.data; } /** The overlay of `root`; a checkout without the file (synced before it existed) has none. */ export async function loadProductCiOverlay(root: string): Promise { let text: string; try { text = await readFile(path.join(root, PRODUCT_CI_OVERLAY_PATH), "utf8"); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return EMPTY_PRODUCT_CI_OVERLAY; throw error; } return parseProductCiOverlay(JSON.parse(text)); } const PROMOTED_DOWNLOAD_PATH = ".release/deployment"; /** Where the slot extracts the promoted archive; the deploy script uploads `/dist`. */ export const PROMOTED_RELEASE_ROOT = ".release/promoted-release"; /** * The template contract document with its empty deployment slot filled from * the overlay. The caller parses the result, so the slot rules of the * template contract still apply. A slot the template contract already * filled is refused: the slot has one owner. */ export function withProductDeployment(contract: unknown, deployment: ProductDeployment): unknown { const document = structuredClone(contract) as { jobs?: { id?: unknown; steps?: unknown; environment?: unknown }[] }; const slot = document.jobs?.find(({ id }) => id === "deployment"); if ( !slot || JSON.stringify(slot.steps) !== JSON.stringify([{ kind: "deploy" }]) || JSON.stringify(slot.environment) !== "[]" ) { throw new TypeError( `the deployment slot is filled in config/ci/gates.json and in ${PRODUCT_CI_OVERLAY_PATH}; ` + `keep the template slot empty and fill ${PRODUCT_CI_OVERLAY_PATH}`, ); } slot.environment = [ { name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" }, ...deployment.environment, ]; slot.steps = [ { kind: "checkout" }, { kind: "setup-node" }, { kind: "frozen-install" }, { kind: "download", transferId: "promoted-release", path: PROMOTED_DOWNLOAD_PATH }, { kind: "extract", archivePath: `${PROMOTED_DOWNLOAD_PATH}/release-candidate.tar.gz`, targetRoot: PROMOTED_RELEASE_ROOT, }, { kind: "deploy", script: deployment.script }, ]; return document; }