05ae530442
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.
281 lines
12 KiB
Python
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}")
|