diff --git a/README.md b/README.md index e251b7d1..086066cd 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,51 @@ corepack pnpm install --frozen-lockfile corepack pnpm dev ``` -Runtime-public settings live in `public/config.json` and are validated before -the product tree mounts. Client secrets are forbidden. +## Runtime configuration + +Runtime-public settings are validated against one schema before the product +tree mounts (`runtimeConfigV2ArtifactSchema` in +`src/contracts/release-artifacts.ts`). Client secrets are forbidden. + +The source of truth is `config/runtime/.json`, one file per +environment: `local`, `development`, `staging`, `production`. `corepack pnpm +build` writes `dist/config.json` from the selected profile +(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local +profile for `corepack pnpm dev`; the build replaces it, so settings put there +never reach a deployment. Keep it equal to `config/runtime/local.json` plus +`BUILD_ID: local-build` and `RELEASE_ID: local-release`; nothing checks that +yet. + +Build and deploy variables, lowest precedence first: + +| Variable | Sets | Default | +| --- | --- | --- | +| `APP_PROFILE` | which `config/runtime/.json` is used | `local`; an empty value fails the build | +| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value | +| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value | +| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` | +| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` | +| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it | + +Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything +else changes by editing the profile file. Staging and production reject demo +auth and non-HTTPS endpoints. + +A production build and its admission check: + +```bash +APP_PROFILE=production \ +RUNTIME_API_BASE_URL=https://api.example.com/ \ +RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \ +VITE_BUILD_ID= RELEASE_ID= \ +corepack pnpm build +APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission +``` + +With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires +`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a +gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable +list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md). ## Included starter experience diff --git a/scripts/build-frontend.ts b/scripts/build-frontend.ts index 4c891059..8158b9e8 100644 --- a/scripts/build-frontend.ts +++ b/scripts/build-frontend.ts @@ -23,11 +23,11 @@ import { makeDistFilesPublic } from "./lib/dist-permissions.ts"; * Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES` * and `null`: those modes never run an active worker build. * - * Step 4 has to follow the Vite build and precede the asset scan. Vite copies - * `public/` verbatim, so without it every build — including a production one — - * ships the local runtime document; and the Service Worker hashes the emitted - * `config.json`, so the profile must be in place before that inventory is - * taken. + * Step 4 has to follow the Vite build. Vite copies `public/` verbatim, so + * without it every build — including a production one — ships the local + * runtime document. The Service Worker asset scan excludes `config.json` + * (`scripts/generate-service-worker-assets.ts`), so the order against step 5 + * is not what keeps the profile out of the worker cache (13-15). */ const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker; diff --git a/scripts/generate-runtime-config.ts b/scripts/generate-runtime-config.ts index 9ca4ed2b..dc3bd44e 100644 --- a/scripts/generate-runtime-config.ts +++ b/scripts/generate-runtime-config.ts @@ -29,7 +29,7 @@ const OUTPUT_PATH = "dist/config.json"; * Deployment-supplied values. Everything else is fixed by the profile so a * deployment cannot quietly widen what was reviewed. */ -const OVERRIDES = Object.freeze({ +export const RUNTIME_OVERRIDES = Object.freeze({ API_BASE_URL: "RUNTIME_API_BASE_URL", TELEMETRY_ENDPOINT: "RUNTIME_TELEMETRY_ENDPOINT", } as const); @@ -49,7 +49,7 @@ export async function generateRuntimeConfig( `${profilePath}: declares APP_ENV ${String(draft["APP_ENV"])}, expected ${target}`, ); } - for (const [field, variable] of Object.entries(OVERRIDES)) { + for (const [field, variable] of Object.entries(RUNTIME_OVERRIDES)) { const supplied = environment[variable]; if (supplied !== undefined && supplied !== "") draft[field] = supplied; } diff --git a/tests/unit/runtime-config-docs.test.ts b/tests/unit/runtime-config-docs.test.ts new file mode 100644 index 00000000..318d84b1 --- /dev/null +++ b/tests/unit/runtime-config-docs.test.ts @@ -0,0 +1,24 @@ +import { readFileSync } from "node:fs"; + +import { describe, expect, it } from "vitest"; + +import { RUNTIME_OVERRIDES } from "../../scripts/generate-runtime-config.ts"; + +// 13-15. README said runtime settings live in public/config.json, which the +// build replaces with config/runtime/.json, and named none of the +// variables a production build needs. +describe("runtime configuration documentation", () => { + it("names every build and deploy variable in the README", () => { + const readme = readFileSync("README.md", "utf8"); + for (const variable of [ + "APP_PROFILE", + "RELEASE_TARGET", + "VITE_BUILD_ID", + "RELEASE_ID", + ...Object.values(RUNTIME_OVERRIDES), + ]) { + expect(readme, variable).toContain(`\`${variable}\``); + } + expect(readme).toContain("config/runtime/.json"); + }); +});