diff --git a/.github/workflows/scient.yml b/.github/workflows/scient.yml index 9db089d005..1e80b8c50f 100644 --- a/.github/workflows/scient.yml +++ b/.github/workflows/scient.yml @@ -4,20 +4,27 @@ name: Scient Agent # every pull request into it, and checks that each build keeps its state apart # from a stock omp. The macOS builds are signed on Linux by upstream's # scripts/ci-macos-sign.sh, ad hoc on every run so the signing path is always -# exercised, then checked on macOS. A `v*` tag signs them with the Developer ID, -# notarizes them and drafts a GitHub release with every binary and its -# checksum; a person publishes the draft. A manual run can sign and notarize -# without drafting a release, to qualify the signing secrets. Oh My Pi's own -# test suite runs on Linux against Scient's tree, as upstream's CI runs it. +# exercised, then checked on macOS. A manual run on main with `release` set +# builds scient.json's version, signs the macOS builds with the Developer ID, +# notarizes them and, once every job passed, drafts a GitHub release with every +# binary and its checksum; a person publishes the draft, which creates the tag. +# As in Scient Desktop's release, a version is used up only when it is +# published: after a failed or superseded run, run again with the same version. +# A manual run can also sign and notarize without drafting a release, to +# qualify the signing secrets. Oh My Pi's own test suite runs on Linux against +# Scient's tree, as upstream's CI runs it. on: push: branches: ["main", "scient/**"] - tags: ["v*"] pull_request: branches: ["main"] workflow_dispatch: inputs: + release: + description: Release scient.json's version from main (it must come right after the latest published release) + type: boolean + default: false developer-id: description: Sign the macOS builds with the Developer ID and notarize them (no release is drafted) type: boolean @@ -28,13 +35,14 @@ permissions: concurrency: # A manual run never cancels, or is cancelled by, a push to the same branch. - group: scient-${{ github.ref }}-${{ github.event_name == 'workflow_dispatch' && 'manual' || 'auto' }} - cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }} + # A release run is never cancelled: a second one waits for it. + group: scient-${{ (github.event_name == 'workflow_dispatch' && inputs.release) && 'release' || format('{0}-{1}', github.ref, github.event_name == 'workflow_dispatch' && 'manual' || 'auto') }} + cancel-in-progress: ${{ !(github.event_name == 'workflow_dispatch' && inputs.release) }} env: - # A release is a pushed product tag. A manual run never drafts one, even against a tag. - RELEASE: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }} - DEVELOPER_ID: ${{ (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) || inputs.developer-id == true }} + # A release is a manual run with `release` set; the release-version job refuses any branch but main. + RELEASE: ${{ github.event_name == 'workflow_dispatch' && inputs.release == true }} + DEVELOPER_ID: ${{ github.event_name == 'workflow_dispatch' && (inputs.release == true || inputs.developer-id == true) }} defaults: run: @@ -42,6 +50,37 @@ defaults: shell: bash jobs: + # A release builds scient.json's version only if it comes right after the + # latest published release and is not tagged yet (scripts/scient/release-version.ts). + # The release job checks again before it drafts. + release-version: + name: Check the release version + # Job conditions cannot read workflow env, so this repeats RELEASE. + if: github.event_name == 'workflow_dispatch' && inputs.release + runs-on: ubuntu-24.04 + timeout-minutes: 10 + outputs: + version: ${{ steps.check.outputs.version }} + steps: + - name: Release from main only + run: | + if [ "$GITHUB_REF" != refs/heads/main ]; then + echo "::error::A release is built from main, not $GITHUB_REF." + exit 1 + fi + + - uses: actions/checkout@v4 + + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.4.4 + + - id: check + name: Check the version + env: + GH_TOKEN: ${{ github.token }} + run: bun scripts/scient/release-version.ts + build: name: Build and check (${{ matrix.id }}) runs-on: ${{ matrix.runner }} @@ -132,11 +171,11 @@ jobs: echo "BINARY=$binary" >> "$GITHUB_ENV" "$binary" --version < /dev/null - - name: Check the release matches its tag + - name: Check the build reports scient.json's version if: env.RELEASE == 'true' run: | version="$("$BINARY" --version < /dev/null)" - test "$version" = "scient-agent/${GITHUB_REF_NAME#v}" + test "$version" = "scient-agent/$(bun -e 'console.log((await Bun.file("scient.json").json()).version)')" - name: Check state isolation run: bun scripts/scient/isolation-check.ts "$BINARY" @@ -364,11 +403,11 @@ jobs: fi "$binary" --version < /dev/null - - name: Check the release matches its tag + - name: Check the build reports scient.json's version if: env.RELEASE == 'true' run: | version="$("$BINARY" --version < /dev/null)" - test "$version" = "scient-agent/${GITHUB_REF_NAME#v}" + test "$version" = "scient-agent/$(bun -e 'console.log((await Bun.file("scient.json").json()).version)')" - name: Check state isolation run: bun scripts/scient/isolation-check.ts "$BINARY" @@ -418,30 +457,76 @@ jobs: release: name: Draft release # Job conditions cannot read workflow env, so this repeats RELEASE. - if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') - needs: [build, verify-macos, compress, divergence, upstream-tests] + if: github.event_name == 'workflow_dispatch' && inputs.release + needs: [release-version, build, verify-macos, compress, divergence, upstream-tests] runs-on: ubuntu-24.04 permissions: contents: write + env: + VERSION: ${{ needs.release-version.outputs.version }} + TAG: v${{ needs.release-version.outputs.version }} steps: + - uses: actions/checkout@v4 + + - uses: oven-sh/setup-bun@v2 + with: + bun-version: 1.4.4 + + # The run takes an hour or more; a release may have been published meanwhile. + - name: Check the version is still next + env: + GH_TOKEN: ${{ github.token }} + run: bun scripts/scient/release-version.ts + - uses: actions/download-artifact@v4 with: pattern: scient-agent-* path: release merge-multiple: true + + # A draft that was never published holds no tag and does not use its + # version up: this run's draft replaces it. GitHub cannot delete only + # if still a draft, so each one is read again right before; SCIENT.md + # says not to publish a draft while a release run of its version runs. + - name: Replace an unpublished draft of this version + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + drafts="$(gh api --paginate "repos/$GITHUB_REPOSITORY/releases?per_page=100" \ + --jq ".[] | select(.draft and .tag_name == \"$TAG\") | .id")" + for id in $drafts; do + if [ "$(gh api "repos/$GITHUB_REPOSITORY/releases/$id" --jq .draft)" != true ]; then + echo "::error::$TAG's draft $id was published during this run; nothing was replaced." + exit 1 + fi + echo "Deleting the unpublished draft $id of $TAG." + gh api -X DELETE "repos/$GITHUB_REPOSITORY/releases/$id" + done + + # Publishing the draft creates the tag on the commit built here; until + # then no tag exists, so the version is not used up. - name: Create the draft release env: GH_TOKEN: ${{ github.token }} run: | + set -euo pipefail ls -l release - gh release create "$GITHUB_REF_NAME" release/* \ + gh release create "$TAG" release/* \ --repo "$GITHUB_REPOSITORY" \ --draft \ - --title "Scient Agent ${GITHUB_REF_NAME#v}" \ + --target "$GITHUB_SHA" \ + --title "Scient Agent $VERSION" \ --notes "Built from ${GITHUB_SHA}." + if gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$TAG" > /dev/null 2>&1; then + echo "::error::Drafting $TAG created its tag; the version would be used up before it is published." + exit 1 + fi + # Scient Desktop downloads from Scient's own copy first and falls back to # this release, so a GitHub outage doesn't block installs. Its catalog - # publishes a version only after every copy here matches the digest. + # publishes a version only after every copy here matches the digest. A + # run that replaces an unpublished draft overwrites that draft's copy. - name: Copy the release to downloads.scientfactory.com env: AWS_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }} @@ -457,10 +542,10 @@ jobs: for name in R2_ACCOUNT_ID AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY R2_BUCKET; do if [ -z "${!name}" ]; then echo "::error::$name is not set; Scient's copy was not uploaded." >&2; exit 1; fi done - aws s3 cp release/ "s3://$R2_BUCKET/scient-agent/$GITHUB_REF_NAME/" --recursive \ + aws s3 cp release/ "s3://$R2_BUCKET/scient-agent/$TAG/" --recursive \ --endpoint-url "https://$R2_ACCOUNT_ID.r2.cloudflarestorage.com" \ --content-type application/octet-stream \ --cache-control "public, max-age=3600" for file in release/*; do - echo "https://downloads.scientfactory.com/scient-agent/$GITHUB_REF_NAME/$(basename "$file")" + echo "https://downloads.scientfactory.com/scient-agent/$TAG/$(basename "$file")" done diff --git a/SCIENT.md b/SCIENT.md index 2116b3317d..6c314f6a58 100644 --- a/SCIENT.md +++ b/SCIENT.md @@ -90,7 +90,7 @@ The 18.8.4 alignment predates markers; its in-place changes were accepted with i ## Branches, releases and upstream updates -- `main` holds Scient Agent. Changes reach it through pull requests that keep their commits (rebase merge; history stays linear). A release is a `v` tag on `main` that matches `scient.json`: `v0.1.0`, `v0.1.1`, ... +- `main` holds Scient Agent. Changes reach it through pull requests that keep their commits (rebase merge; history stays linear). A release is a published GitHub release of `scient.json`'s version, tagged `v` on the `main` commit it was built from: `v0.1.0`, `v0.1.1`, ... A version is used up only when its release is published, so published versions follow each other with no gaps (see Release). - Scient's commits come in three kinds: the scripts under `scripts/scient/`, generated commits (the output of one generator and nothing else, subject ending in `(generated)`, trailer `Scient-Generator: identity`, `wording` or `rpc`), and hand-written changes (trailer `Scient-Divergence: ` in a replay). A pull request that changes what a script produces carries the output as its own generated commit. - `upstream` is a fetch-only remote for Oh My Pi. `scient/18.4.8` is the branch the work started on, kept as it was. @@ -929,6 +929,14 @@ The Intel macOS job restores Cargo dependency artifacts keyed by the compiler, R The macOS builds are signed by upstream's `scripts/ci-macos-sign.sh`, unchanged, on a Linux runner (it uses a pinned `rcodesign`): ad hoc on every run, so the signing path is exercised by every pull request. A separate job then runs the signed bytes on their own macOS runner: checksum, `codesign --verify --strict`, `--version` and the isolation check. An unsigned macOS build is uploaded under an `unsigned-` name and can never reach a release. -Pushing a `v` tag that matches `scient.json` signs the macOS builds with the Developer ID, notarizes them, refuses an ad-hoc signature, and drafts a GitHub release with every binary, its zstd copy (`.zst`) and the SHA-256 of each. A person publishes the draft. The same job copies them all to `downloads.scientfactory.com/scient-agent/v/` (Cloudflare R2; secrets `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` and variable `R2_DOWNLOADS_BUCKET`). Scient Desktop downloads that copy first and falls back to the GitHub release, and its catalog publishes a version only after every copy matches the digest. Desktop prefers the zstd copy, about 40% of the binary's size, unpacks it and checks the binary's SHA-256; it falls back to the binary itself, and Desktops that predate the copies download only the binary. The `compress` job makes the copies on every run with `zstd -19 --long=27` and checks that each unpacks to its binary: Desktop allows a window of at most 2^27 bytes, and the check unpacks with the same limit. A manual run of the workflow with `developer-id` set signs and notarizes without drafting a release; use it to qualify the signing secrets before tagging. Not built yet: Linux with musl (Alpine). The Windows builds are not code-signed. +A release follows Scient Desktop's order: the version is checked first, the tag comes last. + +1. A pull request sets `scient.json`'s version to the one right after the latest published release (next patch, minor or major), in a commit `release: Scient Agent `. +2. Once it is on `main`, run the workflow manually on `main` with `release` set. Its first job (`scripts/scient/release-version.ts`) refuses a version that does not come right after the latest published release, or that a tag carries already. The run signs the macOS builds with the Developer ID, notarizes them and refuses an ad-hoc signature. Only when every job passed does it check the version again and draft a GitHub release with every binary, its zstd copy (`.zst`) and the SHA-256 of each, targeting the commit it built. +3. A person publishes the draft. Publishing creates the `v` tag on that commit; a draft has no tag. + +A version whose run failed, or whose draft was not published, is not used up. Fix `main` and run the release again with the same version: its draft replaces the unpublished one. Never move `scient.json` to a later version for a retry. A failed job can also be rerun in the same run. Do not publish a draft while a release run of the same version is running: that run deletes the old draft just before it drafts its own, and GitHub cannot limit a deletion to drafts. A `v` tag pushed by hand on a version that was never published blocks it; the release run says so, and the tag is deleted before running again. + +The release job copies the release files to `downloads.scientfactory.com/scient-agent/v/` (Cloudflare R2; secrets `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` and variable `R2_DOWNLOADS_BUCKET`), overwriting the copy of a draft it replaces. Scient Desktop's catalog takes only published releases. Desktop downloads that copy first and falls back to the GitHub release, and its catalog publishes a version only after every copy matches the digest. Desktop prefers the zstd copy, about 40% of the binary's size, unpacks it and checks the binary's SHA-256; it falls back to the binary itself, and Desktops that predate the copies download only the binary. The `compress` job makes the copies on every run with `zstd -19 --long=27` and checks that each unpacks to its binary: Desktop allows a window of at most 2^27 bytes, and the check unpacks with the same limit. A manual run of the workflow with `developer-id` set signs and notarizes without drafting a release; use it to qualify the signing secrets before a release run. Not built yet: Linux with musl (Alpine). The Windows builds are not code-signed. Signing uses the same five repository secrets, in the same form, as Scient Desktop's release: `CSC_LINK` (the Developer ID Application certificate as a base64 `.p12`), `CSC_KEY_PASSWORD`, `APPLE_API_KEY` (the App Store Connect `.p8` key's text), `APPLE_API_KEY_ID` and `APPLE_API_ISSUER`. diff --git a/scripts/scient/divergences.json b/scripts/scient/divergences.json index ac465cceb8..f56b8cec15 100644 --- a/scripts/scient/divergences.json +++ b/scripts/scient/divergences.json @@ -24,7 +24,7 @@ }, "SA-RELEASE": { "status": "active", - "contract": "Only Scient's own workflow builds, signs and drafts releases; Oh My Pi's publishing and repository automation is removed, and so is its Nix packaging, which installs and configures a stock omp.", + "contract": "Only Scient's own workflow builds, signs and drafts releases, and only of the version right after the latest published release, whose tag publishing the draft creates; Oh My Pi's publishing and repository automation is removed, and so is its Nix packaging, which installs and configures a stock omp.", "owned": [ "SCIENT.md", ".github/README.md", @@ -37,6 +37,8 @@ "scripts/scient/lib/ledger.ts", "scripts/scient/lib/markers.ts", "scripts/scient/native-variant.ts", + "scripts/scient/release-version.ts", + "scripts/scient/release-version.test.ts", "scripts/scient/upstream-tests.ts", "scripts/scient/upstream-tests.test.ts" ], @@ -54,7 +56,11 @@ "nix/nixos-module.nix", "nix/package.nix" ], - "verification": ["bun scripts/scient/divergence-check.ts", "bun scripts/scient/isolation-check.ts "] + "verification": [ + "bun scripts/scient/divergence-check.ts", + "bun scripts/scient/isolation-check.ts ", + "bun test scripts/scient/release-version.test.ts" + ] }, "SA-PRODUCT": { "status": "active", diff --git a/scripts/scient/release-version.test.ts b/scripts/scient/release-version.test.ts new file mode 100644 index 0000000000..a5e4064c4e --- /dev/null +++ b/scripts/scient/release-version.test.ts @@ -0,0 +1,31 @@ +import { describe, expect, it } from "bun:test"; +import { nextVersions, releaseRefusal } from "./release-version"; + +describe("release version", () => { + it("follows the latest published release by one patch, minor or major step", () => { + expect(nextVersions("0.1.9")).toEqual(["0.1.10", "0.2.0", "1.0.0"]); + for (const version of ["0.1.9", "0.2.0", "1.0.0"]) { + expect(releaseRefusal(version, { latestPublished: "v0.1.8", tagExists: false })).toBeUndefined(); + } + }); + + it("refuses to skip a number, repeat one or go back", () => { + for (const version of ["0.1.10", "0.3.0", "0.1.8", "0.1.7"]) { + expect(releaseRefusal(version, { latestPublished: "v0.1.8", tagExists: false })).toContain( + "next release is 0.1.9", + ); + } + }); + + it("reuses a version whose earlier run failed or was never published, but never a tagged one", () => { + expect(releaseRefusal("0.1.9", { latestPublished: "v0.1.8", tagExists: false })).toBeUndefined(); + expect(releaseRefusal("0.1.8", { latestPublished: "v0.1.8", tagExists: true })).toContain("tagged already"); + // A tag on the next version with no published release was pushed by hand; the run says to delete it. + expect(releaseRefusal("0.1.9", { latestPublished: "v0.1.8", tagExists: true })).toContain("delete that tag"); + }); + + it("allows any version before the first published release, and refuses one that is not x.y.z", () => { + expect(releaseRefusal("0.1.0", { latestPublished: null, tagExists: false })).toBeUndefined(); + expect(releaseRefusal("0.1.9-beta", { latestPublished: "v0.1.8", tagExists: false })).toContain("not x.y.z"); + }); +}); diff --git a/scripts/scient/release-version.ts b/scripts/scient/release-version.ts new file mode 100755 index 0000000000..3b1af603e0 --- /dev/null +++ b/scripts/scient/release-version.ts @@ -0,0 +1,81 @@ +#!/usr/bin/env bun +/** + * Checks that `scient.json`'s version may be released now. As in Scient + * Desktop's release, a version is used up when its release is published, not + * when a build of it is drafted or fails: the version must come right after the + * latest published release, and no tag may carry it yet (publishing a draft + * creates its tag). An unpublished draft holds no tag, so the next release run + * of the same version replaces it. + * + * GITHUB_REPOSITORY=ScientFactory/scient-agent bun scripts/scient/release-version.ts + * + * Prints the version and writes `version=` to `$GITHUB_OUTPUT` when it + * is set; exits 1 with the reason when the version may not be released. + */ +import { appendFileSync } from "node:fs"; +import * as path from "node:path"; +import { $ } from "bun"; + +const VERSION = /^(\d+)\.(\d+)\.(\d+)$/; + +/** The versions that may follow `latest`: its next patch, minor and major release. */ +export function nextVersions(latest: string): string[] { + const match = VERSION.exec(latest); + if (!match) throw new Error(`${latest} is not a version (x.y.z)`); + const [major, minor, patch] = match.slice(1).map(Number); + return [`${major}.${minor}.${patch + 1}`, `${major}.${minor + 1}.0`, `${major + 1}.0.0`]; +} + +export interface ReleaseState { + /** The latest published release's tag (`v0.1.8`), or null before the first one. */ + latestPublished: string | null; + /** Whether a tag `v` exists already. */ + tagExists: boolean; +} + +/** Why `version` may not be released in `state`, or undefined when it may. */ +export function releaseRefusal(version: string, state: ReleaseState): string | undefined { + if (!VERSION.test(version)) return `scient.json's version ${version} is not x.y.z.`; + const latest = state.latestPublished?.replace(/^v/, "") ?? null; + const next = latest === null ? null : nextVersions(latest); + if (state.tagExists) { + // Only publishing tags a version now, so a tag on the next version with no published + // release was made another way (a pushed tag, as releases were once made). + if (next?.includes(version)) { + return `v${version} is tagged, but no release of it is published. A release run never tags; delete that tag, then run the release again.`; + } + return `v${version} is tagged already, and a tagged version is never released again. Set scient.json to the version after the latest published release.`; + } + if (next === null || next.includes(version)) return undefined; + return `The latest published release is v${latest}, so the next release is ${next.join(", ")} (patch, minor or major), not ${version}.`; +} + +/** `gh` output, or null when GitHub answers 404; any other failure throws, so the check fails closed. */ +async function ghOrNotFound(args: string[]): Promise { + const result = await $`gh ${args}`.nothrow().quiet(); + if (result.exitCode === 0) return result.text().trim(); + const stderr = result.stderr.toString(); + if (stderr.includes("HTTP 404")) return null; + throw new Error(`gh ${args.join(" ")} failed: ${stderr.trim()}`); +} + +if (import.meta.main) { + const repo = process.env.GITHUB_REPOSITORY; + if (!repo) { + console.error("GITHUB_REPOSITORY is not set."); + process.exit(2); + } + const repoRoot = path.resolve(import.meta.dir, "..", ".."); + const { version } = (await Bun.file(path.join(repoRoot, "scient.json")).json()) as { version: string }; + const latestPublished = await ghOrNotFound(["api", `repos/${repo}/releases/latest`, "--jq", ".tag_name"]); + const tagExists = (await ghOrNotFound(["api", `repos/${repo}/git/ref/tags/v${version}`, "--jq", ".ref"])) !== null; + const refusal = releaseRefusal(version, { latestPublished, tagExists }); + if (refusal) { + console.log(`::error::${refusal}`); + process.exitCode = 1; + } else { + console.log(`Releasing ${version}; the latest published release is ${latestPublished ?? "none"}.`); + const output = process.env.GITHUB_OUTPUT; + if (output) appendFileSync(output, `version=${version}\n`); + } +}