diff --git a/README.md b/README.md index f2827d0..9edbf93 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,8 @@ inference have not been tested. [Docker quickstart](docs/local/quickstart.md) · [Codex CLI](docs/local/codex.md) · [Claude Code](docs/local/claude-code.md) · [OpenCode](docs/local/opencode.md) · [Ollama](docs/local/ollama.md) · [Integration matrix](docs/local/integrations.md) · -[Verification and limits](docs/local/compatibility.md) +[Verification and limits](docs/local/compatibility.md) · +[Release history](https://plompy.dev/docs/releases/) ```sh mkdir -m 700 plompy-local diff --git a/docs/index.md b/docs/index.md index b64db73..6c6fae8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ # Documentation +- **[Release history](https://plompy.dev/docs/releases/)**: published versions, changes, downloads and upgrade boundaries. + - **[Upgrade to Plompy 0.12](migration-plompy.md)**: retain existing sessions, private state, browser identity and Docker volumes. plompy-engine connects a private Discord forum to persistent coding CLI sessions on diff --git a/docs/local/introduction.md b/docs/local/introduction.md index 348e5e9..baa1fc7 100644 --- a/docs/local/introduction.md +++ b/docs/local/introduction.md @@ -4,6 +4,8 @@ Plompy Local connects an agent on your computer to selected tools running behind Plompy Local 0.13.0 ships as ready-made Docker images and a small starter kit. Download it, connect your preferred agent, and choose its tools. The Local images are separate from the Discord engine image. Check [Compatibility and verification](compatibility.md) for what has actually been tested. +See [what shipped in each release](releases.md), including the current 0.13.0 Local images. + ## Pick your starting point - [Run locally with Docker](quickstart.md): start the tools gateway, connect a client, and try a small task. diff --git a/docs/local/navigation.json b/docs/local/navigation.json index 75c2ade..f625fb1 100644 --- a/docs/local/navigation.json +++ b/docs/local/navigation.json @@ -16,6 +16,14 @@ "description": "Pull the ready-made local gateway image and connect your chosen host MCP client.", "group": "Start here" }, + { + "slug": "releases", + "source": "releases.md", + "title": "Release history", + "description": "Every published Plompy release, with changes, downloads and historical boundaries.", + "group": "Start here", + "kind": "release-index" + }, { "slug": "architecture", "source": "architecture.md", @@ -219,5 +227,6 @@ "description": "Keep autonomous remote browser actions outside the first research profile.", "group": "Integrations" } - ] + ], + "releaseHistory": true } diff --git a/docs/local/releases.md b/docs/local/releases.md new file mode 100644 index 0000000..664be16 --- /dev/null +++ b/docs/local/releases.md @@ -0,0 +1,5 @@ +# Every release.
A little more possibility. + +What shipped, when it shipped, and what changed. Follow Plompy from its first published engine to local tools for your own agent. + +Published versions are listed below. Development changes on `main` are not a release, and older notes describe the capabilities and limits of their own version. diff --git a/docs/releases.md b/docs/releases.md index 37f4a29..da9c70e 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,5 +1,7 @@ # Releases and container images +Browse the [public release history](https://plompy.dev/docs/releases/) for a page per published version. This guide covers distribution, upgrades and the maintainer workflow. + A release is a versioned public source snapshot and a set of container images. It does not update an existing private deployment automatically. The [changelog](../CHANGELOG.md) records user-visible changes; the [Docker guide](docker.md) explains initial setup and private volumes. ## Choose an image @@ -57,7 +59,7 @@ The [release workflow](../.github/workflows/release.yml) runs only on `v*` tag p The workflow also builds the allowlisted Local starter kit and its SHA-256 checksum, without including source state or credentials. The original tested OCI archives and their digest reports are retained as workflow artifacts for one day. A separate publishing job receives `packages: write` after all checks succeed. It revalidates the archive hashes, labels, runtime and attestation subjects, copies every manifest with `skopeo --preserve-digests`, and combines the unchanged amd64/arm64 runtime and attestation manifests into the release index. It does not rebuild the application or reinstall its dependencies. The final index is checked against the complete tested manifest set before its digest is recorded. Publishing uses the job's short-lived GitHub token; no personal registry token is needed. If retained artifacts have expired, rerun the complete workflow so both architectures are rebuilt and retested. -After the workflow succeeds, inspect the published manifest and digest, pull the exact images without authentication to confirm public availability, and create the GitHub release with the relevant changelog entry and immutable image references. Attach the generated Local starter kit and its checksum. The workflow deliberately does not create a release announcement before the image has been verified. GitHub may initially create a GHCR package as private; check its package visibility for the first publication before documenting anonymous installation. +After the workflow succeeds, inspect the published manifest and digest, pull the exact images without authentication to confirm public availability, and create the GitHub release with the relevant changelog entry and immutable image references. Attach the generated Local starter kit and its checksum. Then refresh the [release-history catalog](releases/README.md) and rebuild the website documentation from the canonical changelog. The workflow deliberately does not create a release announcement before the image has been verified. GitHub may initially create a GHCR package as private; check its package visibility for the first publication before documenting anonymous installation. The tag validator accepts SemVer versions with an optional prerelease, without build metadata (`+...`, which is not a Docker tag character). Release metadata and tag-selection behavior have their own offline test: diff --git a/docs/releases/README.md b/docs/releases/README.md new file mode 100644 index 0000000..054aa9a --- /dev/null +++ b/docs/releases/README.md @@ -0,0 +1,38 @@ +# Maintaining the public release history + +`CHANGELOG.md` is the source of release changes. `catalog.json` records which +versions actually have a published GitHub release, their publication dates, +latest-stable designation and downloadable assets. A changelog entry alone does +not make a release public. + +After publishing a release and its final assets, refresh the catalog from the +public GitHub API: + +```sh +node docs/releases/sync.mjs +node --test docs/releases/sync.test.mjs +``` + +Review and commit the catalog. The sync reads public metadata only; it does not +publish, edit releases, download artifacts or need account credentials. Drafts +and unpublished entries are excluded. Prereleases are retained and labelled. + +The website builder reads `docs/local/navigation.json`, `docs/local/releases.md`, +`CHANGELOG.md` and this catalog when `releaseHistory` is enabled. It generates the +release index and individual version pages at `/docs/releases/`. Notes are not +copied into separate hand-maintained pages. Builds fail when a published version +has no matching changelog entry. Source-relative links point to the corresponding +Git tag so historical pages do not silently become current instructions. + +From a sibling `plompy-site` checkout, rebuild and verify: + +```sh +npm run build -- --docs-source ../plompy-engine/docs/local +npm run check +npm run test:docs +``` + +Normal site builds use the committed generated pages without fetching GitHub. +The generated manifest records hashes for both release sources. Development-only +changelog entries stay out of the public history until a release is published and +the catalog is refreshed. diff --git a/docs/releases/catalog.json b/docs/releases/catalog.json new file mode 100644 index 0000000..a3a60c1 --- /dev/null +++ b/docs/releases/catalog.json @@ -0,0 +1,192 @@ +{ + "schema": 1, + "repository": "dalkedev/plompy-engine", + "checkedAt": "2026-11-12T16:54:05.526Z", + "latestStableTag": "v0.13.0", + "releases": [ + { + "tag": "v0.13.0", + "title": "Local MCP, ready-made Docker images", + "publishedAt": "2026-11-12T16:45:24Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.13.0", + "assets": [ + { + "name": "plompy-local-0.13.0.tar.gz", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz", + "size": 11923 + }, + { + "name": "plompy-local-0.13.0.tar.gz.sha256", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.13.0/plompy-local-0.13.0.tar.gz.sha256", + "size": 93 + } + ] + }, + { + "tag": "v0.12.0", + "title": "small fish, your whole machine", + "publishedAt": "2026-11-11T22:43:20Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.12.0", + "assets": [ + { + "name": "plompy-engine-brand-kit.zip", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.12.0/plompy-engine-brand-kit.zip", + "size": 3568562 + } + ] + }, + { + "tag": "v0.11.1", + "title": "unattended Playwright", + "publishedAt": "2026-11-10T17:44:33Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.11.1", + "assets": [] + }, + { + "tag": "v0.11.0", + "title": "browser, research and analytics tools", + "publishedAt": "2026-11-10T16:08:54Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.11.0", + "assets": [] + }, + { + "tag": "v0.10.0", + "title": "Node 26 LTS", + "publishedAt": "2026-11-10T14:05:58Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.10.0", + "assets": [ + { + "name": "image-verification.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.10.0/image-verification.json", + "size": 1080 + }, + { + "name": "published-index.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.10.0/published-index.json", + "size": 1611 + } + ] + }, + { + "tag": "v0.9.0", + "title": "install, inspect, verify", + "publishedAt": "2026-11-10T11:24:06Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.9.0", + "assets": [ + { + "name": "image-verification.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.9.0/image-verification.json", + "size": 1078 + }, + { + "name": "published-index.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.9.0/published-index.json", + "size": 1611 + } + ] + }, + { + "tag": "v0.8.1", + "title": "safe goal recovery under queue pressure", + "publishedAt": "2026-11-09T21:36:45Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.8.1", + "assets": [] + }, + { + "tag": "v0.8.0", + "title": "evidence for every reviewed step", + "publishedAt": "2026-11-09T17:25:59Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.8.0", + "assets": [] + }, + { + "tag": "v0.7.0", + "title": "supervised goals", + "publishedAt": "2026-11-07T21:29:16Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.7.0", + "assets": [] + }, + { + "tag": "v0.6.1", + "title": "Release 0.6.1", + "publishedAt": "2026-11-06T19:40:59Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.6.1", + "assets": [] + }, + { + "tag": "v0.6.0", + "title": "integrations and recovery without losing the thread", + "publishedAt": "2026-11-06T16:49:02Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.6.0", + "assets": [] + }, + { + "tag": "v0.5.0", + "title": "Private Discord image input", + "publishedAt": "2026-11-05T18:37:57Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.5.0", + "assets": [] + }, + { + "tag": "v0.4.0", + "title": "Provider-bound runners and offline demos", + "publishedAt": "2026-11-05T16:14:11Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.4.0", + "assets": [] + }, + { + "tag": "v0.3.1", + "title": "Recovery and clock-safe workflows", + "publishedAt": "2026-11-05T14:37:45Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.3.1", + "assets": [] + }, + { + "tag": "v0.3.0", + "title": "Durable bounded work sessions", + "publishedAt": "2026-11-04T19:55:02Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.3.0", + "assets": [ + { + "name": "release-manifest-0.3.0.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.3.0/release-manifest-0.3.0.json", + "size": 1245 + } + ] + }, + { + "tag": "v0.2.0", + "title": "Release 0.2.0", + "publishedAt": "2026-11-04T19:20:04Z", + "prerelease": false, + "url": "https://github.com/dalkedev/plompy-engine/releases/tag/v0.2.0", + "assets": [ + { + "name": "release-manifest.json", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.2.0/release-manifest.json", + "size": 774 + }, + { + "name": "szpont-engine-brand-kit.zip", + "url": "https://github.com/dalkedev/plompy-engine/releases/download/v0.2.0/szpont-engine-brand-kit.zip", + "size": 1647770 + } + ] + } + ] +} diff --git a/docs/releases/sync.mjs b/docs/releases/sync.mjs new file mode 100644 index 0000000..955c99c --- /dev/null +++ b/docs/releases/sync.mjs @@ -0,0 +1,60 @@ +import assert from 'node:assert/strict'; +import { writeFile } from 'node:fs/promises'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { resolve } from 'node:path'; + +const repository = 'dalkedev/plompy-engine'; +const tagPattern = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/; + +// Publication metadata only. Changes remain authored once in CHANGELOG.md. +export function releaseCatalog(releases, latestTag, checkedAt) { + const published = releases.filter(release => !release.draft && release.published_at); + const tags = new Set(); + const entries = published.map(release => { + assert(tagPattern.test(release.tag_name), 'Unsupported release tag.'); + assert(!tags.has(release.tag_name), 'Duplicate release tag.'); + tags.add(release.tag_name); + const url = `https://github.com/${repository}/releases/tag/${release.tag_name}`; + assert.equal(release.html_url, url, 'Unexpected release URL.'); + assert(Number.isFinite(Date.parse(release.published_at)), 'Invalid publication date.'); + const rawTitle = (release.name || '').replace(/^(?:Plompy|Szpont)(?: Engine)?\s+v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\s*(?:[\u2014\u2013:-]\s*)?/i, '').trim(); + return { + tag: release.tag_name, + title: (rawTitle || `Release ${release.tag_name.slice(1)}`).replaceAll('\u2014', ':'), + publishedAt: release.published_at, + prerelease: Boolean(release.prerelease), + url, + assets: release.assets.map(asset => { + const expected = `https://github.com/${repository}/releases/download/${release.tag_name}/`; + assert(asset.browser_download_url.startsWith(expected), 'Unexpected asset URL.'); + assert(Number.isSafeInteger(asset.size) && asset.size >= 0, 'Invalid asset size.'); + return { name: asset.name, url: asset.browser_download_url, size: asset.size }; + }), + }; + }).sort((a, b) => b.publishedAt.localeCompare(a.publishedAt)); + assert(entries.some(entry => entry.tag === latestTag && !entry.prerelease), 'Latest stable release is not published.'); + return { schema: 1, repository, checkedAt, latestStableTag: latestTag, releases: entries }; +} + +async function github(path) { + const response = await fetch(`https://api.github.com/repos/${repository}/${path}`, { + headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'plompy-release-docs' }, + signal: AbortSignal.timeout(20_000), + }); + if (!response.ok) throw new Error(`GitHub publication lookup failed: HTTP ${response.status}`); + return response.json(); +} + +if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) { + const releases = []; + for (let page = 1; page <= 20; page++) { + const batch = await github(`releases?per_page=100&page=${page}`); + releases.push(...batch); + if (batch.length < 100) break; + if (page === 20) throw new Error('Release pagination limit reached; catalog not written.'); + } + const latest = await github('releases/latest'); + const catalog = releaseCatalog(releases, latest.tag_name, new Date().toISOString()); + await writeFile(fileURLToPath(new URL('./catalog.json', import.meta.url)), JSON.stringify(catalog, null, 2) + '\n'); + console.log(`Recorded ${catalog.releases.length} published releases; latest stable ${catalog.latestStableTag}.`); +} diff --git a/docs/releases/sync.test.mjs b/docs/releases/sync.test.mjs new file mode 100644 index 0000000..1d05c9c --- /dev/null +++ b/docs/releases/sync.test.mjs @@ -0,0 +1,18 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { releaseCatalog } from './sync.mjs'; + +const release = (tag, extra = {}) => ({ tag_name: tag, name: `Plompy ${tag}`, html_url: `https://github.com/dalkedev/plompy-engine/releases/tag/${tag}`, published_at: '2026-11-12T12:00:00Z', prerelease: false, draft: false, assets: [], ...extra }); + +test('catalog includes published versions only and retains explicit stable status', () => { + const catalog = releaseCatalog([release('v0.13.0'), release('v0.14.0-rc.1', { prerelease: true }), release('v0.15.0', { draft: true }), release('v0.16.0', { published_at: null })], 'v0.13.0', '2026-11-12T13:00:00Z'); + assert.equal(catalog.releases.length, 2); + assert.equal(catalog.latestStableTag, 'v0.13.0'); + assert.equal(catalog.releases[1].prerelease, true); +}); + +test('rejects inconsistent latest release, duplicate tags and unexpected download origins', () => { + assert.throws(() => releaseCatalog([release('v0.13.0')], 'v0.14.0', ''), /not published/); + assert.throws(() => releaseCatalog([release('v0.13.0'), release('v0.13.0')], 'v0.13.0', ''), /Duplicate/); + assert.throws(() => releaseCatalog([release('v0.13.0', { assets: [{ name: 'kit.zip', size: 1, browser_download_url: 'https://example.com/kit.zip' }] })], 'v0.13.0', ''), /asset URL/); +});