import { mkdir, readFile, writeFile } from "node:fs/promises"; import process from "node:process"; import { parseArgs } from "node:util"; import { DEPLOYMENT_TARGETS, findAdmissionViolations, isDeploymentTarget, type AdmissionInput, } from "../src/contracts/deployment-admission.ts"; import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts"; import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts"; import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts"; import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts"; import { changedRuntimeConfigBuildFields, RUNTIME_CONFIG_EMERGENCY_SWITCHES, } from "./lib/runtime-config-switches.ts"; /** * §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not * built for. * * Release coherence already proves the artifacts agree with each other. It * cannot prove they belong in production, because a local build is coherent * with itself: `APP_ENV: local`, `AUTH_MODE: demo` and a loopback API pass * every existing gate. This gate closes that by making the destination an * explicit, declared input and refusing anything that does not match it. * * It fails closed in both directions. An undeclared destination is a refusal, * not a default, so an artifact can never be admitted by omission; and every * rule is stated as a reason to refuse, so an unreadable field cannot pass. */ const RUNTIME_CONFIG_PATH = "dist/config.json"; const RECORD_PATH = "artifacts/release/deployment-admission.json"; const EMERGENCY_SWITCHES = RUNTIME_CONFIG_EMERGENCY_SWITCHES; function refuse(reason: string): void { process.stderr.write(`release admission refused: ${reason}\n`); process.exitCode = 1; } function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error); } async function readRuntimeConfig(file: string): Promise { let document: unknown; try { document = JSON.parse(await readFile(file, "utf8")); } catch (error) { refuse(`${file} is unreadable: ${errorMessage(error)}`); return null; } try { return parseRuntimeConfigArtifact(document) as AdmissionInput; } catch (error) { refuse(`${file} is not a valid runtime config: ${errorMessage(error)}`); return null; } } async function main(): Promise { // `pnpm check:release-admission -- --config …` may pass the separator through. const argv = process.argv.slice(2); if (argv[0] === "--") argv.shift(); const { values: options } = parseArgs({ args: argv, options: { config: { type: "string" }, original: { type: "string" } }, }); const declared = process.env["RELEASE_TARGET"]; if (!isDeploymentTarget(declared)) { process.stderr.write( "release admission refused: RELEASE_TARGET must be declared as one of " + `${DEPLOYMENT_TARGETS.join(", ")}; received ${ declared === undefined ? "nothing" : declared }.\n` + "An artifact is never admitted by default — name the environment it is for.\n", ); process.exitCode = 1; return; } // 13-01: the build profile and the admission target are separate repository // variables; a profile left on staging must not ship to production. const profile = process.env["APP_PROFILE"]; if (profile !== undefined && profile !== declared) { process.stderr.write( `release admission refused: the artifact was built with APP_PROFILE=${profile} ` + `but RELEASE_TARGET=${declared}. Set both to the same environment.\n`, ); process.exitCode = 1; return; } // 1101/13-05. An edited copy of the deployed document is checked against // that document, so a changed build field is refused, not just a bad value. const editedCopy = options.config; if (editedCopy !== undefined && options.original === undefined) { refuse( "--config needs --original ; " + "BUILD_ID, RELEASE_ID and every other build field are compared with it.", ); return; } const configPath = editedCopy ?? RUNTIME_CONFIG_PATH; const config = await readRuntimeConfig(configPath); if (config === null) return; if (options.original !== undefined) { const original = await readRuntimeConfig(options.original); if (original === null) return; const changed = changedRuntimeConfigBuildFields(original, config); if (changed.length > 0) { refuse( `${configPath} changes ${changed.join(", ")}; without a rebuild only ` + `${[...EMERGENCY_SWITCHES].join(" and ")} may change.`, ); return; } } // U7 (decision 2). The packages the build compiled; a placeholder identity // from create:feature is refused for staging and production. An edited copy // is checked without them: packages are a build field it cannot change, and // the build's own admission checked them. const violations = findAdmissionViolations( declared, config, editedCopy === undefined ? EXPECTED_CONTRACT_SET_PACKAGES : [], ); // 09-09. Inert by design (a shared document may name another build's // features), so this warns instead of refusing. const warnings = unknownProductFeatureOverrides( COMPILED_PRODUCT_FEATURE_IDS, "FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined, ).map((featureId) => ({ field: `FEATURE_OVERRIDES.${featureId}`, reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`, })); for (const warning of warnings) { process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`); } if (editedCopy !== undefined) { // The record is the build's admission evidence (a CI artifact); an // operator's edited copy is not the build and does not replace it. if (violations.length > 0) { refuse( `${editedCopy} for ${declared}:\n${violations .map((violation) => ` ${violation.field}: ${violation.reason}`) .join("\n")}`, ); return; } process.stdout.write( `release admission: ${editedCopy} ADMITTED for ${declared}; no field other than ` + `${[...EMERGENCY_SWITCHES].join(" and ")} differs from ${options.original}. ` + "Not recorded: this checks an edited copy, not the build.\n", ); return; } await mkdir("artifacts/release", { recursive: true }); await writeFile( RECORD_PATH, `${JSON.stringify( { schemaVersion: 1, target: declared, appEnv: config.APP_ENV, authMode: config.AUTH_MODE, apiBaseUrl: config.API_BASE_URL, buildId: config.BUILD_ID ?? null, releaseId: config.RELEASE_ID ?? null, status: violations.length === 0 ? "ADMITTED" : "REFUSED", violations, warnings, }, null, 2, )}\n`, "utf8", ); if (violations.length > 0) { process.stderr.write( `release admission refused for ${declared}:\n${violations .map((violation) => ` ${violation.field}: ${violation.reason}`) .join("\n")}\n`, ); process.exitCode = 1; return; } process.stdout.write( `release admission: ${declared} ADMITTED ` + `(APP_ENV=${config.APP_ENV}, AUTH_MODE=${config.AUTH_MODE}, ` + `API=${config.API_BASE_URL}); record at ${RECORD_PATH}\n`, ); } await main();