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: { /* … */ } }),
});