From 99e77ebabf36a758bdbb179ade247ec6690b3c26 Mon Sep 17 00:00:00 2001 From: lilleman Date: Thu, 20 Aug 2026 23:32:10 +0200 Subject: [PATCH] Release this as v0.2.0, and give the Hub overview its own job, token and template --- .gitea/workflows/release.yml | 47 +++++++++----- .gitea/workflows/renovate.yml | 11 ++-- AGENTS.md | 5 +- README.md | 61 +++++++++++++------ examples/plugins/admin/plugin.ts | 2 +- examples/plugins/scheduling/plugin.ts | 2 +- package.json | 2 +- release-tooling/contract-version.test.ts | 50 +++++++++++---- release-tooling/contract-version.ts | 12 ++-- .../dockerhub-overview.md.tmpl | 2 +- release-tooling/dockerhub-overview.test.ts | 4 +- release-tooling/dockerhub-overview.ts | 20 +++--- .../next-version.test.ts | 0 .../next-version.ts | 2 +- renovate.json | 4 +- src/plugin-host/plugin.test.ts | 2 +- src/plugin-host/plugin.ts | 4 +- src/server.ts | 3 +- tsconfig.json | 2 +- views/index.ejs | 2 +- 20 files changed, 155 insertions(+), 82 deletions(-) rename README-dockerhub.md => release-tooling/dockerhub-overview.md.tmpl (99%) rename {auto-release => release-tooling}/next-version.test.ts (100%) rename {auto-release => release-tooling}/next-version.ts (95%) diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index 39ed22b..9697a85 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -2,9 +2,17 @@ name: Release on: push: tags: ['v[0-9]+.[0-9]+.[0-9]+'] + # The overview has its own door: a stale page is exactly the state you cannot fix by cutting a + # release, so republishing it must not require one. + workflow_dispatch: + inputs: + overview_version: + description: 'Version the overview should tell adopters to pull (e.g. 0.2.0)' + required: true jobs: retag-image: + if: github.event_name == 'push' runs-on: docker-host steps: - uses: actions/checkout@v7.0.1 @@ -34,7 +42,7 @@ jobs: done - name: Sync the release tags to Docker Hub env: - DOCKERHUB_REPO: docker.io/${{ github.repository }} + DOCKERHUB_IMAGE: docker.io/${{ github.repository }} DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} DOCKERHUB_USER: ${{ vars.DOCKERHUB_USER }} GIT_TAG: ${{ github.ref_name }} @@ -46,22 +54,33 @@ jobs: || { echo "Set the DOCKERHUB_USER variable + DOCKERHUB_TOKEN secret (README -> CI/CD)"; exit 1; } printf '%s' "$DOCKERHUB_TOKEN" | docker login docker.io -u "$DOCKERHUB_USER" --password-stdin for TAG in "$VERSION" "${VERSION%.*}" "${VERSION%%.*}" latest; do - docker tag "$REPO:$COMMIT" "$DOCKERHUB_REPO:$TAG" - docker push "$DOCKERHUB_REPO:$TAG" + docker tag "$REPO:$COMMIT" "$DOCKERHUB_IMAGE:$TAG" + docker push "$DOCKERHUB_IMAGE:$TAG" done - - name: Publish the Docker Hub overview - env: - DOCKERHUB_REPO: ${{ github.repository }} - DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }} - DOCKERHUB_USER: ${{ vars.DOCKERHUB_USER }} - GIT_TAG: ${{ github.ref_name }} - run: | - docker run --rm -v "$PWD:/repo" -w /repo \ - -e DOCKERHUB_REPO -e DOCKERHUB_TOKEN -e DOCKERHUB_USER \ - node:24.19.0-alpine3.24 \ - node release-tooling/dockerhub-overview.ts "${GIT_TAG#v}" - name: Log out of the registries if: always() run: | docker logout gitea.larvit.se docker logout docker.io + + # Its own job, not a step: the images are already pushed and irreversible by this point, so a Hub + # API outage or an under-scoped token must not report the release itself as failed. + publish-overview: + if: always() && (github.event_name == 'workflow_dispatch' || needs.retag-image.result == 'success') + needs: [retag-image] + runs-on: docker-host + steps: + - uses: actions/checkout@v7.0.1 + - name: Publish the Docker Hub overview + env: + DOCKERHUB_OVERVIEW_TOKEN: ${{ secrets.DOCKERHUB_OVERVIEW_TOKEN }} + DOCKERHUB_REPO: ${{ github.repository }} + DOCKERHUB_USER: ${{ vars.DOCKERHUB_USER }} + GIT_TAG: ${{ github.ref_name }} + INPUT_VERSION: ${{ inputs.overview_version }} + run: | + VERSION=${INPUT_VERSION:-${GIT_TAG#v}} + docker run --rm -v "$PWD:/repo" -w /repo \ + -e DOCKERHUB_OVERVIEW_TOKEN -e DOCKERHUB_REPO -e DOCKERHUB_USER \ + node:24.19.0-alpine3.24 \ + node release-tooling/dockerhub-overview.ts "$VERSION" diff --git a/.gitea/workflows/renovate.yml b/.gitea/workflows/renovate.yml index c593264..d5124e4 100644 --- a/.gitea/workflows/renovate.yml +++ b/.gitea/workflows/renovate.yml @@ -29,7 +29,7 @@ jobs: # (a human owns that release), nothing new merged, or nothing that merged carried a `Release-Bump:` # trailer — a release nobody can observe is noise. ff-only merges keep the renovate commit's # authorship on the tip, so the author checks are reliable. Level = highest `Release-Bump:` trailer; - # pre-1.0 shifts down (auto-release/next-version.ts). Tag-only — release.yml promotes the + # pre-1.0 shifts down (release-tooling/next-version.ts). Tag-only — release.yml promotes the # already-built image; pushed with renovate-bot's PAT so release.yml fires (the built-in token won't). auto-release: runs-on: docker-host @@ -59,12 +59,11 @@ jobs: echo "Renovate commits since ${LATEST}, but none carry Release-Bump — nothing reached a running Plainpages; skipping"; exit 0 fi NEXT=$(docker run --rm -v "$PWD:/repo" -w /repo node:24.19.0-alpine3.24 \ - node auto-release/next-version.ts "$LATEST" $BUMPS) + node release-tooling/next-version.ts "$LATEST" $BUMPS) # Read the constant off origin/main, not the checkout, which lags the merges this run made. - git show origin/main:src/plugin-host/plugin.ts > plugin-at-main.ts - docker run --rm -v "$PWD:/repo" -w /repo node:24.19.0-alpine3.24 \ - node release-tooling/contract-version.ts "$NEXT" plugin-at-main.ts - rm -f plugin-at-main.ts + git show origin/main:src/plugin-host/plugin.ts \ + | docker run -i --rm -v "$PWD:/repo" -w /repo node:24.19.0-alpine3.24 \ + node release-tooling/contract-version.ts "$NEXT" - echo "Releasing $LATEST -> $NEXT" git tag "$NEXT" origin/main git push "https://renovate-bot:${RENOVATE_TOKEN}@gitea.larvit.se/${REPO}.git" "$NEXT" diff --git a/AGENTS.md b/AGENTS.md index 6abbaf8..de88490 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -291,8 +291,9 @@ Revisit only if the stated reason stops holding. workflow reads a markdown file. Both git channels in `ci.sh`'s `docs_only()` pass `--no-renames`: rename detection names only the destination, so `git mv src/app.ts notes.md` would otherwise read as docs and skip the gate over a source file that was gone. `src/ci-gate.test.ts` locks the flags as a - *text* guard — the test image ships neither `git` nor `bash`. Revisit if a `.md` ever becomes - load-bearing. + *text* guard — the test image ships neither `git` nor `bash`. This is why the Docker Hub overview is + `release-tooling/dockerhub-overview.md.tmpl` and not a `.md`: a release reads it and a unit test + guards it, so renaming it back would let a broken `{{VERSION}}` merge with its own guard skipped. - **CI docker logins share the runner host's Docker config.** The act_runner is host-mode, so `docker login`/`logout` in the workflows mutate one shared `~/.docker/config.json`: concurrent jobs can race (one job's logout can 401 another's push — recover by re-running), and tokens sit in that diff --git a/README.md b/README.md index d61db80..91866b7 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ folder under `plugins/` goes live after a restart. Create `plugins/hello/plugin. import { definePlugin } from "@plainpages/plugin-api"; export default definePlugin({ - apiVersion: "0.1.0", + apiVersion: "0.2.0", nav: [{ href: "/hello", id: "hello", label: "Hello", public: true }], routes: [ { method: "GET", path: "/", public: true, handler: () => ({ html: "

Hello from my plugin

" }) }, @@ -348,7 +348,7 @@ import { definePlugin } from "@plainpages/plugin-api"; import { listThings, createThings } from "./handlers.ts"; export default definePlugin({ - apiVersion: "0.1.0", // semver string of the host contract this plugin was built against (see Versioning) + apiVersion: "0.2.0", // semver string of the host contract this plugin was built against (see Versioning) // Nav fragment, merged into the global menu and permission-filtered per user. // `icon` is a Lucide icon by its sprite id (src/ui/icons.ts). @@ -468,7 +468,7 @@ import { definePlugin } from "@plainpages/plugin-api"; import { landing, board } from "./pages.ts"; export default definePlugin({ - apiVersion: "0.1.0", + apiVersion: "0.2.0", home: landing, // owns "/" — the public front page dashboard: board, // owns "/dashboard" — the post-login app home }); @@ -612,7 +612,10 @@ provider/consumer semantics in `checkApiVersion`: | missing / not a valid semver | `refuse` | **abort boot** — must be declared | The plugin pins one exact version (no ranges, per the project's pinning rules); the *host* supplies -the caret-style compatibility. While Plainpages is `0.x` every release shares major `0`, so a plugin +the caret-style compatibility. Note what a **minor** means now that one digit carries the whole +release: either the plugin contract changed, or a dependency moved far enough to warrant one. A +`warn` therefore says "built against an older release", not "new plugin features exist" — check the +Upgrading section for that release before assuming there is anything to adopt. While Plainpages is `0.x` every release shares major `0`, so a plugin built against `0.1.0` still loads on a `0.9.0` host with a `warn`; reaching `1.0.0` refuses everything built against `0.x`, which is the point of that milestone. @@ -748,7 +751,7 @@ import { definePlugin } from "@plainpages/plugin-api"; let sql: ReturnType; export default definePlugin({ - apiVersion: "0.1.0", + apiVersion: "0.2.0", storage: true, hooks: { onBoot: async (boot) => { @@ -1378,7 +1381,7 @@ Gitea Actions (`.gitea/workflows/`) runs the pipeline; the test job runs | Workflow | Trigger | Does | | --- | --- | --- | | `ci.yml` | push, any branch except `main` | the full gate (`bash ci.sh`, a no-op on a docs-only branch), then build + push the app image | -| `release.yml` | push of a `vX.Y.Z` tag | check the tag against `HOST_API_VERSION`, re-tag that commit's image as `X.Y.Z`, `X.Y`, `X`, `latest`, sync those tags to Docker Hub and publish its overview | +| `release.yml` | push of a `vX.Y.Z` tag, or manual | check the tag against `HOST_API_VERSION`, re-tag that commit's image as `X.Y.Z`, `X.Y`, `X`, `latest`, sync those tags to Docker Hub; a second job publishes the Hub overview, and runs alone on a manual trigger | | `mirror.yml` | push to `main` or any tag, or manual | force-push `main` + tags (pruning deleted ones) to the [GitHub mirror](https://github.com/larvit/plainpages) | | `registry-cleanup.yml` | nightly cron, or manual | delete registry images that are neither release-tagged nor a branch head | | `renovate.yml` | nightly cron, or manual | open dependency-update PRs, automerge them once the gate is green, then cut a release tag for what merged | @@ -1408,13 +1411,17 @@ nothing is rebuilt, so the released image is byte-identical to the gated one. It hash image exists — release tags must point at a commit that went through the gate. The same four tags sync to [Docker Hub](https://hub.docker.com/r/larvit/plainpages), releases only. -Two things guard the tag before anything is published. The -[contract check](#contract-versioning) refuses a tag whose `major.minor` disagrees with -`HOST_API_VERSION`, naming the value to set. And the Docker Hub repository **overview** is published -from [`README-dockerhub.md`](README-dockerhub.md) by the same job, with `{{VERSION}}` rendered to the -release — so the image tags it tells adopters to pull cannot go stale. That needs `DOCKERHUB_TOKEN` -to carry permission to edit repository metadata, not just push images; the step names this if it -403s. +The [contract check](#contract-versioning) guards the tag before anything is published, refusing one +whose `major.minor` disagrees with `HOST_API_VERSION` and naming the value to set. + +**The Docker Hub overview** is published by a separate `publish-overview` job from +[`release-tooling/dockerhub-overview.md.tmpl`](release-tooling/dockerhub-overview.md.tmpl), with +`{{VERSION}}` rendered to the release, so the image tags it tells adopters to pull cannot go stale. +It is its own job for two reasons: the images are already pushed and irreversible by then, so a Hub +outage must not report a good release as failed; and the page has its own door — run the workflow +manually with an `overview_version` input to republish it without cutting a release. It uses +`DOCKERHUB_OVERVIEW_TOKEN`, separate from the image-push token because editing repository metadata is +a different permission and widening the push credential to cover it would widen what a leak costs. **GitHub mirror** — [github.com/larvit/plainpages](https://github.com/larvit/plainpages) is read-only; after every merge `mirror.yml` force-pushes `main` and all tags, overwriting any drift. @@ -1436,8 +1443,11 @@ exact. Each PR runs the normal gate on its `renovate/*` branch and automerges on trailer — a dependency update that cannot reach the app releases nothing. Renovate stamps a `Release-Bump: ` trailer onto the updates that reach a running Plainpages — the root `package.json`'s runtime dependencies, the image base, and `compose.yml`'s services — and -[`auto-release/next-version.ts`](auto-release/next-version.ts) turns the highest one into the next -version; pre-1.0 it never auto-crosses into `1.0.0`. `updateType` rates the *dependency's* own jump, +[`release-tooling/next-version.ts`](release-tooling/next-version.ts) turns the highest one into the next +version; pre-1.0 it never auto-crosses into `1.0.0`. Because the contract version *is* the release +version, an update big enough to reach a **minor** stops the job rather than tagging: bump +`HOST_API_VERSION` in a PR, merge, then tag by hand. Pre-1.0 that covers a dependency *major*, since +`nextVersion` shifts it down to a `0.x` minor. `updateType` rates the *dependency's* own jump, so the trailer is an allowlist in [`renovate.json`](renovate.json): a devDependency, E2E or CI-only bump carries none and rides the next patch release instead of escalating it. It is **tag-only**: the tag hands off to `release.yml`, and is pushed with renovate-bot's PAT so that workflow actually fires (a tag pushed by @@ -1449,6 +1459,7 @@ the built-in Actions token wouldn't trigger it). `HOST_API_VERSION` is never tou | --- | --- | | `DOCKER_REGISTRY_USER` (var) + `DOCKER_REGISTRY_TOKEN` (secret) | A Gitea account with package write in the `larvit` org, and its access token with `read:package` + `write:package`. Reused by `registry-cleanup.yml`. | | `DOCKERHUB_USER` (var) + `DOCKERHUB_TOKEN` (secret) | The public `larvit/plainpages` Docker Hub repo, and a read/write token **scoped to that repository** (an org access token, or one on a dedicated account — an account-wide PAT can push to every repo under it). | +| `DOCKERHUB_OVERVIEW_TOKEN` (secret) | A Docker Hub PAT that may **edit repository metadata**, used only to publish the overview. Separate from `DOCKERHUB_TOKEN` so the image-push credential stays narrow; without it the `publish-overview` job fails and the released images are unaffected. | | `MIRROR_GITHUB_TOKEN` (secret) | A fine-grained PAT (Contents: read & write) for a GitHub machine account with write access to the mirror. Its `main` must not block force-pushes and must carry no tag protection, which would reject the prune. | | `RENOVATE_TOKEN` (secret) | The shared `renovate@larvit.se` bot's Gitea PAT, with write access to this repo. | | `RENOVATE_GITHUB_TOKEN` (secret) | A **scopeless** (read-only) github.com PAT, so Renovate's lookups of github.com-hosted deps run authenticated instead of tripping the anonymous 60-req/hour limit. | @@ -1502,6 +1513,21 @@ box. The web app waits for Kratos + Keto healthy *and* the bootstrap to finish b ## Upgrading +### 0.1.x → 0.2.0: `apiVersion` now names the Plainpages release + +`0.1.0` shipped a host reporting contract version `1.0.0` — a second number that tracked the plugin +contract separately from the release. There is only one number now, and it is the release: a host on +`0.2.0` reports `0.2.0`. Every plugin must say so, or discovery refuses it by version and **aborts +boot**: + +```ts +// plugins//plugin.ts +apiVersion: "0.2.0", // was "1.0.0" +``` + +Re-copy anything taken from `examples/` (below) to pick this up. Nothing else in the contract +changed, so a plugin that boots after the edit needs no further work. + **Re-copy your drop-in plugins.** Anything under `plugins/` is *your* copy — the host never updates it. A plugin copied from `examples/` is still the old one after you pull, and the host may have tightened a manifest rule since. Discovery fails loud at boot rather than running a plugin it can't @@ -1651,12 +1677,11 @@ examples/ Copy-in reference mirroring the mount dirs: plugins/schedul config/menu.ts, and shifts-upstream/ (the dev mock backend) e2e-tests/ Playwright specs + their Dockerfile and compose.{visual,auth,oauth,full,devstack}.yml; proxy.ts (same-origin gateway) and mock-oidc.ts back full-flow -auto-release/ Release-version math for the Renovate auto-release (next-version.ts) -release-tooling/ Run by the release itself: the HOST_API_VERSION↔tag gate, the Docker Hub publisher +release-tooling/ Everything the release runs: next-version (the bump math), contract-version + (the HOST_API_VERSION↔tag gate), dockerhub-overview (+ its .md.tmpl) registry-cleanup/ Nightly image pruning — the Gitea client plus what survives (select-versions.ts) ci.sh The full gate: typecheck → unit tests → every E2E suite on a fresh stack .gitea/workflows/ Gitea Actions — see CI/CD -README-dockerhub.md The Docker Hub repository overview; release.yml renders {{VERSION}} and publishes it ``` ## Extending the core diff --git a/examples/plugins/admin/plugin.ts b/examples/plugins/admin/plugin.ts index ece09d0..ec19a8b 100644 --- a/examples/plugins/admin/plugin.ts +++ b/examples/plugins/admin/plugin.ts @@ -26,7 +26,7 @@ const groups = on("groups"); const clients = on("oauth2-clients"); export default definePlugin({ - apiVersion: "0.1.0", // the host contract this was built against — a literal, never HOST_API_VERSION + apiVersion: "0.2.0", // the host contract this was built against — a literal, never HOST_API_VERSION nav: [ADMIN_NAV], diff --git a/examples/plugins/scheduling/plugin.ts b/examples/plugins/scheduling/plugin.ts index 9b3cb1a..2bf86eb 100644 --- a/examples/plugins/scheduling/plugin.ts +++ b/examples/plugins/scheduling/plugin.ts @@ -11,7 +11,7 @@ const upstreamUrl = process.env["SCHEDULING_UPSTREAM"] ?? "http://shifts-upstrea const upstream = createUpstream(upstreamUrl); export default definePlugin({ - apiVersion: "0.1.0", // the host contract this was built against — a literal, never HOST_API_VERSION + apiVersion: "0.2.0", // the host contract this was built against — a literal, never HOST_API_VERSION // onBoot runs after discovery, before the server listens: validate the plugin's own config so a // typo'd SCHEDULING_UPSTREAM fails the boot loudly instead of degrading every request later. diff --git a/package.json b/package.json index 1a1be55..e0cde0d 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,7 @@ "dev": "node --watch src/server.ts", "gen-jwks": "node src/auth/gen-jwks.ts", "typecheck": "tsc --noEmit", - "test": "node --test \"src/**/*.test.ts\" \"plugins/**/*.test.ts\" \"examples/**/*.test.ts\" \"registry-cleanup/**/*.test.ts\" \"release-tooling/**/*.test.ts\" \"auto-release/**/*.test.ts\"" + "test": "node --test \"src/**/*.test.ts\" \"plugins/**/*.test.ts\" \"examples/**/*.test.ts\" \"registry-cleanup/**/*.test.ts\" \"release-tooling/**/*.test.ts\"" }, "dependencies": { "@larvit/log": "2.3.0", diff --git a/release-tooling/contract-version.test.ts b/release-tooling/contract-version.test.ts index 954ead3..c48a994 100644 --- a/release-tooling/contract-version.test.ts +++ b/release-tooling/contract-version.test.ts @@ -9,27 +9,51 @@ test("readHostApiVersion pulls the constant out of the real source, and returns assert.equal(readHostApiVersion('export const SOMETHING_ELSE = "1.0.0";'), null); }); -test("the shipped tag and the shipped contract agree", () => { - // Guards the pair the release gate checks, so a bump to one fails here before it fails in CI. - assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.1.0"); +test("bumping HOST_API_VERSION is a deliberate act, so pin the shipped value", () => { + // Not a substitute for the release gate — this test cannot see a tag. It is the tripwire that + // makes an accidental edit fail here rather than at release time. + assert.equal(readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")), "0.2.0"); +}); + +test("every author-facing apiVersion sample matches the shipped contract", () => { + // A plugin author copies these; a stale one produces a boot-aborting refuse on first run. The + // examples deliberately write a literal rather than importing the constant (AGENTS.md), so this + // is the only thing keeping the copies honest. + const host = readHostApiVersion(readFileSync("src/plugin-host/plugin.ts", "utf8")) ?? ""; + const [major, minor] = host.split("."); + for (const file of [ + "README.md", + "examples/plugins/admin/plugin.ts", + "examples/plugins/scheduling/plugin.ts", + "release-tooling/dockerhub-overview.md.tmpl", + "views/index.ejs", + ]) { + const found = [...readFileSync(file, "utf8").matchAll(/apiVersion: "(\d+\.\d+\.\d+)"/g)].map((m) => m[1]); + assert.ok(found.length > 0, `${file} should carry at least one apiVersion sample`); + for (const sample of found) { + const [sMajor, sMinor] = (sample ?? "").split("."); + assert.equal(`${sMajor}.${sMinor}`, `${major}.${minor}`, `${file} samples apiVersion ${sample}, host is ${host}`); + } + } }); test("checkTagMatchesContract: major.minor must agree, patch may lag", () => { - assert.equal(checkTagMatchesContract("v0.1.0", "0.1.0").ok, true); - assert.equal(checkTagMatchesContract("v0.1.7", "0.1.0").ok, true); // auto-release cut patches - assert.equal(checkTagMatchesContract("0.1.0", "0.1.0").ok, true); // bare tag, no v - assert.equal(checkTagMatchesContract("v0.2.0", "0.1.0").ok, false); // plugin-visible, needs a bump - assert.equal(checkTagMatchesContract("v1.0.0", "0.1.0").ok, false); + assert.equal(checkTagMatchesContract("v0.2.0", "0.2.0").ok, true); + assert.equal(checkTagMatchesContract("v0.2.7", "0.2.0").ok, true); // auto-release cut patches + assert.equal(checkTagMatchesContract("0.2.0", "0.2.0").ok, true); // bare tag, no v + assert.equal(checkTagMatchesContract("v0.3.0", "0.2.0").ok, false); // plugin-visible, needs a bump + assert.equal(checkTagMatchesContract("v0.1.0", "0.2.0").ok, false); // the previously released line + assert.equal(checkTagMatchesContract("v1.0.0", "0.2.0").ok, false); }); test("checkTagMatchesContract names what to fix rather than just failing", () => { - const res = checkTagMatchesContract("v0.2.0", "0.1.0"); + const res = checkTagMatchesContract("v0.3.0", "0.2.0"); assert.equal(res.ok, false); - assert.match(res.ok === false ? res.error : "", /HOST_API_VERSION to 0\.2\.0/); + assert.match(res.ok === false ? res.error : "", /HOST_API_VERSION to 0\.3\.0/); }); test("checkTagMatchesContract rejects junk on either side without throwing", () => { - assert.equal(checkTagMatchesContract("v0.1.0", null).ok, false); // constant not found - assert.equal(checkTagMatchesContract("nope", "0.1.0").ok, false); - assert.equal(checkTagMatchesContract("v0.1.0", "1.0").ok, false); + assert.equal(checkTagMatchesContract("v0.2.0", null).ok, false); // constant not found + assert.equal(checkTagMatchesContract("nope", "0.2.0").ok, false); + assert.equal(checkTagMatchesContract("v0.2.0", "1.0").ok, false); }); diff --git a/release-tooling/contract-version.ts b/release-tooling/contract-version.ts index 103dd06..96ab281 100644 --- a/release-tooling/contract-version.ts +++ b/release-tooling/contract-version.ts @@ -15,7 +15,7 @@ export function readHostApiVersion(source: string): string | null { // releases with no commit to bump the constant in. export function checkTagMatchesContract(tag: string, hostApiVersion: string | null): ContractCheck { if (hostApiVersion === null) { - return { error: "HOST_API_VERSION not found in src/plugin-host/plugin.ts", ok: false }; + return { error: "HOST_API_VERSION not found", ok: false }; } const t = SEMVER.exec(tag); if (!t) return { error: `tag must be vX.Y.Z, got ${JSON.stringify(tag)}`, ok: false }; @@ -31,14 +31,16 @@ export function checkTagMatchesContract(tag: string, hostApiVersion: string | nu }; } -// CLI: node auto-release/contract-version.ts → exits 1 on mismatch. +// CLI: node release-tooling/contract-version.ts → exits 1 on +// mismatch. `-` reads the source on stdin, so a caller checking a ref other than its checkout +// (`git show origin/main:… | …`) needs no scratch file in the workspace. if (process.argv[1]?.endsWith("/contract-version.ts")) { - const [, , tag, pluginPath] = process.argv; + const [, , tag, pluginPath = "src/plugin-host/plugin.ts"] = process.argv; const { readFileSync } = await import("node:fs"); - const source = readFileSync(pluginPath ?? "src/plugin-host/plugin.ts", "utf8"); + const source = readFileSync(pluginPath === "-" ? 0 : pluginPath, "utf8"); const result = checkTagMatchesContract(tag ?? "", readHostApiVersion(source)); if (!result.ok) { - process.stderr.write(`${result.error}\n`); + process.stderr.write(`${pluginPath}: ${result.error}\n`); process.exit(1); } process.stdout.write(`${tag} matches HOST_API_VERSION\n`); diff --git a/README-dockerhub.md b/release-tooling/dockerhub-overview.md.tmpl similarity index 99% rename from README-dockerhub.md rename to release-tooling/dockerhub-overview.md.tmpl index 6921772..51a9047 100644 --- a/README-dockerhub.md +++ b/release-tooling/dockerhub-overview.md.tmpl @@ -182,7 +182,7 @@ into the app. Create `plugins/hello/plugin.ts`: import { definePlugin } from "@plainpages/plugin-api"; export default definePlugin({ - apiVersion: "0.1.0", + apiVersion: "0.2.0", nav: [{ href: "/hello", id: "hello", label: "Hello", public: true }], routes: [ { method: "GET", path: "/", public: true, handler: () => ({ html: "

Hello from my plugin

" }) }, diff --git a/release-tooling/dockerhub-overview.test.ts b/release-tooling/dockerhub-overview.test.ts index 95e8564..1b6c15b 100644 --- a/release-tooling/dockerhub-overview.test.ts +++ b/release-tooling/dockerhub-overview.test.ts @@ -13,8 +13,8 @@ test("leftoverPlaceholders catches a typo'd placeholder, deduped, and passes cle assert.deepEqual(leftoverPlaceholders(renderOverview("x {{VERSION}}", "0.1.0")), []); }); -test("the real README-dockerhub.md renders clean and pins no literal image tag", () => { - const rendered = renderOverview(readFileSync("README-dockerhub.md", "utf8"), "9.9.9"); +test("the real template renders clean and pins no literal image tag", () => { + const rendered = renderOverview(readFileSync("release-tooling/dockerhub-overview.md.tmpl", "utf8"), "9.9.9"); assert.deepEqual(leftoverPlaceholders(rendered), []); assert.match(rendered, /larvit\/plainpages:9\.9\.9/); // the placeholder actually reaches the examples // A hardcoded version here is what went stale on the live page; the release must own every one. diff --git a/release-tooling/dockerhub-overview.ts b/release-tooling/dockerhub-overview.ts index 9d2b4d5..8d124f7 100644 --- a/release-tooling/dockerhub-overview.ts +++ b/release-tooling/dockerhub-overview.ts @@ -1,6 +1,6 @@ -// Publishes README-dockerhub.md as the Docker Hub repository overview. The page is the first thing -// an adopter copies, and its image tags were maintained by hand — they pointed at a version that no -// longer existed. `{{VERSION}}` is rendered from the tag being promoted, so they cannot go stale. +// Publishes the Docker Hub repository overview from dockerhub-overview.md.tmpl. The page is the +// first thing an adopter copies, and its image tags were maintained by hand — they pointed at a +// version that no longer existed. `{{VERSION}}` is rendered from the release, so they cannot. const HUB = "https://hub.docker.com/v2"; @@ -18,16 +18,18 @@ async function main(): Promise { const { readFileSync } = await import("node:fs"); const repo = process.env["DOCKERHUB_REPO"]; const user = process.env["DOCKERHUB_USER"]; - const token = process.env["DOCKERHUB_TOKEN"]; + const token = process.env["DOCKERHUB_OVERVIEW_TOKEN"]; if (!version || !repo || !user || !token) { - process.stderr.write("usage: dockerhub-overview.ts ; needs DOCKERHUB_REPO/USER/TOKEN\n"); + process.stderr.write( + "usage: dockerhub-overview.ts ; needs DOCKERHUB_REPO, DOCKERHUB_USER, DOCKERHUB_OVERVIEW_TOKEN\n", + ); return 1; } - const body = renderOverview(readFileSync("README-dockerhub.md", "utf8"), version); + const body = renderOverview(readFileSync("release-tooling/dockerhub-overview.md.tmpl", "utf8"), version); const leftover = leftoverPlaceholders(body); if (leftover.length > 0) { - process.stderr.write(`README-dockerhub.md has unrendered placeholders: ${leftover.join(", ")}\n`); + process.stderr.write(`release-tooling/dockerhub-overview.md.tmpl has unrendered placeholders: ${leftover.join(", ")}\n`); return 1; } @@ -56,8 +58,8 @@ async function main(): Promise { process.stderr.write( `Docker Hub overview PATCH failed: ${res.status} ${detail}\n` + (res.status === 403 - ? "403 usually means the token is scoped to the repository's images only — publishing the " + - "overview edits repository metadata and needs a token with that permission (README -> CI/CD).\n" + ? "403 means DOCKERHUB_OVERVIEW_TOKEN cannot edit repository metadata — that is a separate " + + "permission from pushing images, which is why it is its own secret (README -> CI/CD).\n" : ""), ); return 1; diff --git a/auto-release/next-version.test.ts b/release-tooling/next-version.test.ts similarity index 100% rename from auto-release/next-version.test.ts rename to release-tooling/next-version.test.ts diff --git a/auto-release/next-version.ts b/release-tooling/next-version.ts similarity index 95% rename from auto-release/next-version.ts rename to release-tooling/next-version.ts index ecc6ad6..2f8fb7f 100644 --- a/auto-release/next-version.ts +++ b/release-tooling/next-version.ts @@ -36,7 +36,7 @@ export function nextVersion(latestTag: string, level: Bump): string { return `v${major}.${minor}.${patch + 1}`; } -// CLI: node auto-release/next-version.ts [updateType...] → prints the next tag. +// CLI: node release-tooling/next-version.ts [updateType...] → prints the next tag. if (process.argv[1]?.endsWith("/next-version.ts")) { const [, , latestTag, ...updateTypes] = process.argv; process.stdout.write(nextVersion(latestTag ?? "", maxLevel(updateTypes))); diff --git a/renovate.json b/renovate.json index 3494f80..1563568 100644 --- a/renovate.json +++ b/renovate.json @@ -53,8 +53,8 @@ }, { "customType": "regex", - "description": "Pin the node image workflow run-steps invoke (registry-cleanup, auto-release)", - "managerFilePatterns": [".gitea/workflows/registry-cleanup.yml", ".gitea/workflows/renovate.yml"], + "description": "Pin the node image workflow run-steps invoke (registry-cleanup, renovate auto-release, release)", + "managerFilePatterns": [".gitea/workflows/registry-cleanup.yml", ".gitea/workflows/release.yml", ".gitea/workflows/renovate.yml"], "matchStrings": ["\\snode:(?[0-9][^\\s\"']*)"], "depNameTemplate": "node", "datasourceTemplate": "docker" diff --git a/src/plugin-host/plugin.test.ts b/src/plugin-host/plugin.test.ts index 6fde120..9ddc473 100644 --- a/src/plugin-host/plugin.test.ts +++ b/src/plugin-host/plugin.test.ts @@ -20,7 +20,7 @@ import { AUTH_FLOWS } from "../auth/flow-view.ts"; // HOST_API_VERSION would always equal the host and defeat the check. No `id`/`basePath` — the // host derives both from the plugin's folder name. const scheduling: PluginManifest = definePlugin({ - apiVersion: "0.1.0", + apiVersion: "0.2.0", hooks: { onBoot: () => {} }, nav: [{ children: [{ href: "/scheduling/shifts", id: "scheduling:shifts", label: "Shifts", permission: "scheduling:read" }], diff --git a/src/plugin-host/plugin.ts b/src/plugin-host/plugin.ts index 00dbe97..7f94d16 100644 --- a/src/plugin-host/plugin.ts +++ b/src/plugin-host/plugin.ts @@ -11,7 +11,7 @@ import type { StorageCredentials } from "./storage.ts"; // The Plainpages release this contract ships in — one version, not a second one to track. Its // major.minor must equal the release tag's; `release.yml` refuses to promote a tag that disagrees. // The patch digit may lag, since checkApiVersion ignores patch and auto-release cuts patches itself. -export const HOST_API_VERSION = "0.1.0"; +export const HOST_API_VERSION = "0.2.0"; export type HttpMethod = "DELETE" | "GET" | "HEAD" | "PATCH" | "POST" | "PUT"; @@ -160,7 +160,7 @@ export function checkApiVersion(pluginVersion: unknown, hostVersion: string = HO return { level: "refuse", message: `plugin targets apiVersion ${pluginVersion} but host is ${hostVersion}; upgrade the host` }; } if (plugin.minor < host.minor) { - return { level: "warn", message: `plugin targets apiVersion ${pluginVersion}; host is ${hostVersion} — newer features available` }; + return { level: "warn", message: `plugin targets apiVersion ${pluginVersion}; host is ${hostVersion} — built against an older release` }; } return { level: "ok", message: `apiVersion ${pluginVersion}` }; } diff --git a/src/server.ts b/src/server.ts index b489926..1443f46 100644 --- a/src/server.ts +++ b/src/server.ts @@ -2,6 +2,7 @@ import { createApp } from "./http/app.ts"; import { loadConfig } from "./config.ts"; import { createDenylist } from "./auth/denylist.ts"; import { discoverPlugins } from "./plugin-host/discovery.ts"; +import { HOST_API_VERSION } from "./plugin-host/plugin.ts"; import { withTimeout } from "./auth/fetch-timeout.ts"; import { runBootHooks } from "./plugin-host/hooks.ts"; import { createHydraAdmin } from "./auth/hydra-admin.ts"; @@ -91,7 +92,7 @@ const server = createApp({ plugins, secureCookies: config.secureCookies, }).listen(config.port, () => { - log.info("listening", { port: config.port, url: config.appUrl ?? `http://localhost:${config.port}` }); + log.info("listening", { apiVersion: HOST_API_VERSION, port: config.port, url: config.appUrl ?? `http://localhost:${config.port}` }); }); // Drain in-flight requests on container stop instead of cutting them mid-response, then flush any diff --git a/tsconfig.json b/tsconfig.json index b903c3e..c5569e0 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -24,5 +24,5 @@ "forceConsistentCasingInFileNames": true, "skipLibCheck": true }, - "include": ["auto-release", "config", "examples/config", "examples/plugins", "plugin-api", "plugins", "registry-cleanup", "release-tooling", "src"] + "include": ["config", "examples/config", "examples/plugins", "plugin-api", "plugins", "registry-cleanup", "release-tooling", "src"] } diff --git a/views/index.ejs b/views/index.ejs index 118c8e2..12ed83a 100644 --- a/views/index.ejs +++ b/views/index.ejs @@ -14,7 +14,7 @@

${t("dashboard.starter.intro")}

${t("dashboard.starter.replace")}

export default definePlugin({
-  apiVersion: "0.1.0",
+  apiVersion: "0.2.0",
   // view names plugins/<id>/views/<view>.ejs, rendered in this same shell
   dashboard: (ctx) => ({ view: "dashboard", data: { /* … */ } }),
 });