Files
pipelines/scripts/resolve-releases.py
T
alan 05ae530442 Make Pipelines Docker-only with OpenCode and Pi
Install current verified harness releases inside Docker, preserve persistent accounts and settings, and provide separate interactive and pipeline model defaults with terminal onboarding and fuzzy pickers.

Add Docker-aware authoring transport, Pi stage execution, bounded workflow controls, reliable final-result readback and usage settlement, and finite short-lived CLI pipe draining. Keep dated installation evidence and packaged authoring guidance consistent.

Verified with a real Docker installation, both harness stages and interactive authors, the built-in plan/implement/review starter, independent host race/vet checks, installer tests, and packaged skill tests. Generated release receipts stay ignored in clean checkouts.
2026-10-11 23:00:25 +01:00

281 lines
12 KiB
Python

#!/usr/bin/env python3
"""Bounded resolution of current harness releases for the Docker image.
Network I/O is isolated behind an injectable ``fetch`` callable so unit tests
never touch the network. The resolver:
* discovers supported V2 releases from one bounded GitHub request to
``git/matching-refs/tags/v2``, which the official REST docs
(https://docs.github.com/en/rest/git/refs#list-matching-references) document
as a complete array with no pagination parameters. There is no page/per_page
query, no ``Link`` cursor and no tags/list cross-check: an explicit
``MAX_REFS`` count and ``MAX_BODY`` byte cap bound the single response;
* treats the official V2 tag metadata (not the registry's insertion order) as
the ordering, ignoring prerelease/build-suffixed tags and rejecting malformed
ones; it never uses the moving ``releases/latest`` anchor;
* resolves the selected tag's immutable ``sha256`` digest from GHCR and fails
closed when it is missing or invalid, never falling back to an older version;
* validates untrusted metadata, versions, digests and fixture values;
* refuses non-registry hosts and unexpected redirects;
* validates the Pi Node engine constraint fail-closed.
The selected versions/digests are data, not evergreen hardcoded answers.
"""
import json
import re
import urllib.error
import urllib.parse
import urllib.request
class ReleaseError(ValueError):
"""Resolution failed; callers must keep the last verified pins."""
GHCR = "https://ghcr.io"
GITHUB = "https://api.github.com"
NPM = "https://registry.npmjs.org"
OPENCODE_REPOSITORY = "anomalyco/opencode"
OPENCODE_IMAGE = "ghcr.io/anomalyco/opencode"
PI_PACKAGE = "@earendil-works/pi-coding-agent"
MAX_REFS = 1000 # Explicit ceiling on the documented complete matching-refs array.
MAX_BODY = 1 << 20 # Generous ceiling for tag lists and manifest metadata.
SUPPORTED_MAJOR = 2
HTTP_TIMEOUT = 5.0
ALLOWED_HOSTS = frozenset({"ghcr.io", "api.github.com", "registry.npmjs.org"})
GITHUB_HEADERS = {"Accept": "application/vnd.github+json", "User-Agent": "pipelines-setup"}
MANIFEST_ACCEPT = ", ".join([
"application/vnd.oci.image.index.v1+json",
"application/vnd.docker.distribution.manifest.list.v2+json",
"application/vnd.oci.image.manifest.v1+json",
"application/vnd.docker.distribution.manifest.v2+json",
])
VERSION = re.compile(r"v?(\d+)\.(\d+)\.(\d+)")
# A version-shaped tag carrying a prerelease/build suffix is ignored, not fatal.
VERSION_SUFFIX = re.compile(r"v?(\d+)\.(\d+)\.(\d+)[-+].*")
DIGEST = re.compile(r"sha256:[0-9a-f]{64}")
TAG = re.compile(r"[A-Za-z0-9][A-Za-z0-9._/-]{0,127}")
ENGINE = re.compile(r"(>=|<=|>|<|=)?\s*v?(\d+\.\d+\.\d+)")
def registry_tag(tag):
"""Normalize an official ``vX.Y.Z`` git tag to its registry tag name."""
return tag[1:] if tag.startswith("v") else tag
def parse_version(text):
if not isinstance(text, str):
return None
match = VERSION.fullmatch(text.strip())
if not match:
return None
return tuple(int(part) for part in match.groups())
class _NoRedirect(urllib.request.HTTPRedirectHandler):
"""Registry metadata lookups must never be silently redirected elsewhere."""
def redirect_request(self, req, fp, code, msg, headers, newurl):
raise ReleaseError(f"refusing unexpected redirect from {req.full_url!r} to {newurl!r}")
_OPENER = urllib.request.build_opener(_NoRedirect)
def _default_fetch(url, headers=None):
parsed = urllib.parse.urlsplit(url)
if parsed.scheme != "https" or parsed.hostname not in ALLOWED_HOSTS:
raise ReleaseError(f"refusing non-registry host {url!r}")
request = urllib.request.Request(url, headers=headers or {})
try:
with _OPENER.open(request, timeout=HTTP_TIMEOUT) as response:
lowered = {key.lower(): value for key, value in response.headers.items()}
return response.status, lowered, response.read(MAX_BODY + 1)
except urllib.error.HTTPError as error:
lowered = {key.lower(): value for key, value in error.headers.items()}
return error.code, lowered, error.read(MAX_BODY + 1)
def _response_json(fetch, url, headers=None):
"""Fetch a bounded JSON body and return it with its lower-cased headers."""
status, response_headers, body = fetch(url, headers or {})
if status != 200:
raise ReleaseError(f"HTTP {status} from {url}")
if not isinstance(body, (bytes, bytearray)):
raise ReleaseError(f"non-bytes response from {url}")
if len(body) > MAX_BODY:
raise ReleaseError(f"response body exceeds {MAX_BODY} bytes from {url}")
try:
data = json.loads(body)
except (TypeError, ValueError):
raise ReleaseError(f"invalid JSON from {url}") from None
lowered = {key.lower(): value for key, value in (response_headers or {}).items()}
return data, lowered
def _json(fetch, url, headers=None):
data, _ = _response_json(fetch, url, headers)
return data
def _github_v2_tags(fetch):
"""One bounded request for the documented complete matching-refs array.
GitHub's "List matching references" endpoint documents a complete array and
no pagination parameters, so a single ``MAX_BODY``/``MAX_REFS``-bounded GET
is sufficient. Exact stable versions become candidates; version-shaped tags
with a prerelease/build suffix are ignored; other malformed tags fail closed.
"""
url = f"{GITHUB}/repos/{OPENCODE_REPOSITORY}/git/matching-refs/tags/v{SUPPORTED_MAJOR}"
data, _ = _response_json(fetch, url, GITHUB_HEADERS)
if not isinstance(data, list):
raise ReleaseError("GitHub matching-refs payload is not a list")
if len(data) > MAX_REFS:
raise ReleaseError(
f"GitHub matching-refs returned {len(data)} refs, exceeding the {MAX_REFS}-ref cap; "
"refusing to select a release without proof the tag list is complete")
candidates = {}
for entry in data:
if not isinstance(entry, dict):
raise ReleaseError("GitHub matching-refs entry is not an object")
ref = entry.get("ref")
if not isinstance(ref, str) or not ref.startswith("refs/tags/"):
raise ReleaseError(f"GitHub matching-refs entry has an unexpected ref {ref!r}")
tag = registry_tag(ref[len("refs/tags/"):])
version = parse_version(tag)
if version is None:
if VERSION_SUFFIX.fullmatch(tag):
# Prerelease/build tags never win; skip them instead of failing.
continue
raise ReleaseError(f"GitHub matching-refs tag {tag!r} is not an exact version")
candidates[tag] = version
return candidates
def _ghcr_token(fetch):
data = _json(fetch, f"{GHCR}/token?scope=repository:{OPENCODE_REPOSITORY}:pull")
if not isinstance(data, dict):
raise ReleaseError("registry token payload is not an object")
token = data.get("token")
if not isinstance(token, str) or not token:
raise ReleaseError("registry did not issue a pull token")
return token
def _manifest_digest(fetch, token, tag):
if not isinstance(tag, str) or not TAG.fullmatch(tag):
raise ReleaseError(f"refusing to resolve an invalid registry tag {tag!r}")
url = f"{GHCR}/v2/{OPENCODE_REPOSITORY}/manifests/{urllib.parse.quote(tag, safe='')}"
status, headers, _ = fetch(url, {"Authorization": "Bearer " + token, "Accept": MANIFEST_ACCEPT})
if status != 200:
raise ReleaseError(f"HTTP {status} resolving digest for {tag}")
digest = headers.get("docker-content-digest", "")
if not DIGEST.fullmatch(digest):
raise ReleaseError(f"registry returned no usable content digest for {tag}")
return digest
def resolve_opencode(fetch=_default_fetch):
candidates = _github_v2_tags(fetch)
supported = {tag: version for tag, version in candidates.items() if version[0] == SUPPORTED_MAJOR}
if not supported:
raise ReleaseError(f"no supported OpenCode V{SUPPORTED_MAJOR} release found in the official tag metadata")
tag = max(supported, key=lambda name: supported[name])
token = _ghcr_token(fetch)
# The highest supported stable tag is authoritative; the manifest lookup
# below proves publication and fails closed if its digest is missing, never
# falling back to an older version.
return {
"image": OPENCODE_IMAGE,
"version": tag,
"digest": _manifest_digest(fetch, token, tag),
"anchor": f"github:repos/{OPENCODE_REPOSITORY}/git/matching-refs/tags/v{SUPPORTED_MAJOR}",
"candidates": sorted(supported),
}
def _validate_engine(engine):
text = (engine or "").strip()
if not text:
return
if not ENGINE.fullmatch(text):
raise ReleaseError(f"unsupported Pi Node engine constraint {engine!r}; refusing to accept an unchecked runtime")
def node_satisfies(engine, node_version):
"""Fail-closed check for the simple constraints Pi publishes."""
node = parse_version(node_version)
if node is None:
raise ReleaseError(f"could not parse Node version {node_version!r}")
text = (engine or "").strip()
if not text:
return True
match = ENGINE.fullmatch(text)
if not match:
raise ReleaseError(f"unsupported Pi Node engine constraint {engine!r}; refusing to accept an unchecked runtime")
operator = match.group(1) or "="
bound = parse_version(match.group(2))
if operator == ">=":
return node >= bound
if operator == "<=":
return node <= bound
if operator == ">":
return node > bound
if operator == "<":
return node < bound
return node == bound
def resolve_pi(fetch=_default_fetch, node_version=None):
url = f"{NPM}/@earendil-works%2fpi-coding-agent/latest"
data = _json(fetch, url)
if not isinstance(data, dict):
raise ReleaseError("npm Pi payload is not an object")
version = data.get("version")
if parse_version(version) is None:
raise ReleaseError(f"npm returned a non-version Pi release {version!r}")
engines = data.get("engines") or {}
if not isinstance(engines, dict):
raise ReleaseError("npm Pi engines metadata is malformed")
engine = engines.get("node", "")
if engine is not None and not isinstance(engine, str):
raise ReleaseError("npm Pi node engine constraint is malformed")
engine = engine or ""
_validate_engine(engine)
if node_version is not None and not node_satisfies(engine, node_version):
raise ReleaseError(f"Pi {version} requires Node {engine} but the image provides {node_version}")
return {"package": PI_PACKAGE, "version": version, "engine": engine}
def resolve(fetch=_default_fetch, node_version=None):
return {"opencode": resolve_opencode(fetch), "pi": resolve_pi(fetch, node_version)}
def load_fixture(path):
"""Test/offline seam: read an explicit resolution instead of the network."""
with open(path, encoding="utf-8") as handle:
data = json.load(handle)
if not isinstance(data, dict):
raise ReleaseError("release fixture must be an object")
opencode, pi = data.get("opencode"), data.get("pi")
if not isinstance(opencode, dict) or not isinstance(pi, dict):
raise ReleaseError("release fixture must contain opencode and pi objects")
if parse_version(opencode.get("version")) is None:
raise ReleaseError("release fixture opencode version is not an exact version")
if not DIGEST.fullmatch(str(opencode.get("digest", ""))):
raise ReleaseError("release fixture opencode digest is not a sha256 digest")
if opencode.get("image", OPENCODE_IMAGE) != OPENCODE_IMAGE:
raise ReleaseError("release fixture opencode image is not the supported registry image")
if parse_version(pi.get("version")) is None:
raise ReleaseError("release fixture pi version is not an exact version")
_validate_engine(pi.get("engine", ""))
return data
if __name__ == "__main__":
import sys
try:
print(json.dumps(resolve(), indent=2))
except ReleaseError as error:
sys.exit(f"Release resolution failed: {error}")