From 7a372b64802173e721b4fdcff0e8637135723529 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Thu, 11 Jun 2026 16:44:11 +0300 Subject: [PATCH] fix: document and publish live registry endpoint --- .github/workflows/publish-registry.yml | 15 +++++++++++---- README.md | 2 +- docs/DISTRIBUTION.md | 16 ++++++++++++---- scripts/build-registry.mjs | 6 +++--- tests/registry.test.mjs | 7 ++++++- 5 files changed, 33 insertions(+), 13 deletions(-) diff --git a/.github/workflows/publish-registry.yml b/.github/workflows/publish-registry.yml index a03e47f..aeaaff7 100644 --- a/.github/workflows/publish-registry.yml +++ b/.github/workflows/publish-registry.yml @@ -32,6 +32,8 @@ jobs: - run: npm test - name: Build every released schema version shell: bash + env: + SCHEMA_DOMAIN: ${{ vars.SCHEMA_DOMAIN }} run: | set -euo pipefail rm -rf registry release-source @@ -40,11 +42,16 @@ jobs: line="v${version%.*}" mkdir -p "release-source/$version" git archive "$tag" "schemas/$line" | tar -x -C "release-source/$version" - node scripts/build-registry.mjs \ - --version "$version" \ - --source "release-source/$version/schemas/$line" \ - --output registry \ + args=( + --version "$version" + --source "release-source/$version/schemas/$line" + --output registry --append + ) + if [[ -n "${SCHEMA_DOMAIN:-}" ]]; then + args+=(--domain "$SCHEMA_DOMAIN") + fi + node scripts/build-registry.mjs "${args[@]}" done < <(git tag --list "v[0-9]*.[0-9]*.[0-9]*" --sort=version:refname) - run: npm run validate:registry -- --registry registry - uses: actions/configure-pages@v5 diff --git a/README.md b/README.md index 14e7881..1d053a0 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Producers should emit records that validate against the declared version. Consum The schemas are public APIs. Review [versioning and compatibility](docs/VERSIONING.md), [contributing](CONTRIBUTING.md), and [security](SECURITY.md) before proposing changes. -Released schemas are discoverable from `https://schemas.coding-autopilot.dev/index.json`. Use stable `vMAJOR.MINOR` URLs for compatible updates or immutable `releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md). +Released schemas are discoverable from `https://coding-autopilot-system.github.io/cas-contracts/index.json`. Use stable `vMAJOR.MINOR` URLs for compatible updates or immutable `releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md). ## Status diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md index 435ad0f..e167944 100644 --- a/docs/DISTRIBUTION.md +++ b/docs/DISTRIBUTION.md @@ -1,19 +1,25 @@ # Schema Distribution -Released CAS schemas are distributed as a static registry from `https://schemas.coding-autopilot.dev`. +Released CAS schemas are distributed from: + +```text +https://coding-autopilot-system.github.io/cas-contracts/ +``` + +Schema `$id` values use the reserved canonical namespace `https://schemas.coding-autopilot.dev/`. Until DNS is configured for that domain, consumers must resolve schemas from the live GitHub Pages distribution URL. ## URL Contract Use a stable major/minor URL when a consumer should automatically receive compatible patch releases: ```text -https://schemas.coding-autopilot.dev/v0.1/prompt-envelope.schema.json +https://coding-autopilot-system.github.io/cas-contracts/v0.1/prompt-envelope.schema.json ``` Use an immutable release URL when builds or evidence must remain reproducible: ```text -https://schemas.coding-autopilot.dev/releases/v0.1.0/prompt-envelope.schema.json +https://coding-autopilot-system.github.io/cas-contracts/releases/v0.1.0/prompt-envelope.schema.json ``` Discovery and integrity metadata are available from: @@ -35,4 +41,6 @@ The command writes `registry/`, validates the version, preserves relative schema Pushing a semantic version tag such as `v0.1.1` runs `.github/workflows/publish-registry.yml`. The workflow rebuilds every tagged release, preserves immutable release paths, advances stable major/minor paths, validates the repository, and deploys the result to GitHub Pages. -Repository administrators must configure GitHub Pages to use **GitHub Actions** as its source and configure DNS for the `schemas.coding-autopilot.dev` custom domain. Publication uses GitHub's OIDC token and does not require stored deployment credentials. +Repository administrators must configure GitHub Pages to use **GitHub Actions** as its source. Publication uses GitHub's OIDC token and does not require stored deployment credentials. + +To activate a verified custom domain, configure its DNS records and set the repository Actions variable `SCHEMA_DOMAIN`. The publication workflow emits `CNAME` only when that variable is explicitly configured. diff --git a/scripts/build-registry.mjs b/scripts/build-registry.mjs index 77e3760..bca2cbb 100644 --- a/scripts/build-registry.mjs +++ b/scripts/build-registry.mjs @@ -8,7 +8,7 @@ const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/; function parseArguments(args) { if (args.includes("--help")) return { help: true }; - const result = { output: path.join(root, "registry"), append: false, domain: "schemas.coding-autopilot.dev" }; + const result = { output: path.join(root, "registry"), append: false }; for (let index = 0; index < args.length; index += 1) { if (args[index] === "--append") result.append = true; else { @@ -51,7 +51,7 @@ async function packageSchemas(source, destination, version) { return manifest; } -export async function buildRegistry({ version, source, output, append = false, domain = "schemas.coding-autopilot.dev" }) { +export async function buildRegistry({ version, source, output, append = false, domain }) { if (!versionPattern.test(version ?? "")) throw new Error("version must be a semantic version such as 0.1.0"); const [, major, minor] = version.match(versionPattern); const line = `v${major}.${minor}`; @@ -81,7 +81,7 @@ export async function buildRegistry({ version, source, output, append = false, d lines: { ...existing.lines, [line]: version } }; await writeJson(indexPath, index); - await writeFile(path.join(outputRoot, "CNAME"), `${domain}\n`); + if (domain) await writeFile(path.join(outputRoot, "CNAME"), `${domain}\n`); return { index, immutable, stable, output: outputRoot }; } diff --git a/tests/registry.test.mjs b/tests/registry.test.mjs index e89063f..f53b17f 100644 --- a/tests/registry.test.mjs +++ b/tests/registry.test.mjs @@ -28,7 +28,6 @@ test("registry packages immutable and stable schema paths with verified digests" const content = await readFile(path.join(output, "v0.1", schema.path)); assert.equal(createHash("sha256").update(content).digest("hex"), schema.sha256); } - assert.equal(await readFile(path.join(output, "CNAME"), "utf8"), "schemas.coding-autopilot.dev\n"); }); test("distributed stable schemas compile and retain authoritative ids", async () => { @@ -58,3 +57,9 @@ test("registry builds are deterministic and append preserves immutable releases" test("registry rejects invalid release versions", async () => { await assert.rejects(() => buildRegistry({ version: "latest", source: schemaDirectory, output: "ignored" }), /semantic version/); }); + +test("registry emits a custom-domain CNAME only when explicitly configured", async () => { + const output = await mkdtemp(path.join(os.tmpdir(), "cas-registry-domain-")); + await buildRegistry({ version: "0.1.0", source: schemaDirectory, output, domain: "schemas.example.com" }); + assert.equal(await readFile(path.join(output, "CNAME"), "utf8"), "schemas.example.com\n"); +});