@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/versions/github/src/fetch-http-client.js

@@ -0,0 +1,23 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class FetchHttpClient {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async get(url, options = {}) {
+        const timeout = AbortSignal.timeout(options.timeoutMs ?? this.options.timeoutMs ?? 30_000);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        const response = await fetch(url, {
+            method: "GET",
+            redirect: "follow",
+            signal,
+            headers: { "user-agent": this.options.userAgent ?? "product-lab", ...options.headers },
+        });
+        const headers = {};
+        response.headers.forEach((value, name) => {
+            headers[name.toLowerCase()] = value;
+        });
+        return { status: response.status, url: response.url || url, headers, body: await response.text() };
+    }
+}

package/adapters/versions/github/src/github-release-artifacts.d.ts

@@ -0,0 +1,36 @@
+import { type LockedComponent } from "@parity/product-lab/domain/versions";
+import type { ArtifactStore, FetchedArtifact, LocatedArtifact, MissingArtifact } from "@parity/product-lab/ports/versions";
+/** This machine's target triple, or undefined for a platform no release names. */
+export declare function machineTarget(platform?: string, arch?: string): string | undefined;
+/**
+ * product-lab's shared cache directory: `PRODUCT_LAB_CACHE_DIR` (absolute), else
+ * `$XDG_CACHE_HOME/product-lab`, else `~/.cache/product-lab`. The truAPI CLI
+ * host adapter keeps its hosts in the same directory (its `cacheRoot`).
+ */
+export declare function productLabCacheDir(env?: Readonly<Record<string, string | undefined>>): string;
+export interface GitHubReleaseArtifactsOptions {
+    /** The cache directory (default `productLabCacheDir()`). */
+    readonly cacheDir?: string;
+    /** This machine's target triple (default `machineTarget()`). */
+    readonly target?: string;
+    /** Tests: serve releases from this loopback base instead of https://github.com. */
+    readonly releaseBase?: string;
+    readonly fetch?: typeof fetch;
+}
+/** `ArtifactStore` over GitHub release downloads and a content-addressed directory. */
+export declare class GitHubReleaseArtifacts implements ArtifactStore {
+    private readonly options;
+    readonly location: string;
+    readonly target: string | undefined;
+    constructor(options?: GitHubReleaseArtifactsOptions);
+    handles(component: LockedComponent): boolean;
+    private artifact;
+    private directory;
+    private url;
+    private located;
+    locate(component: LockedComponent): LocatedArtifact | MissingArtifact;
+    acquire(component: LockedComponent, options?: {
+        signal?: AbortSignal;
+        log?: (line: string) => void;
+    }): Promise<FetchedArtifact>;
+}

package/adapters/versions/github/src/github-release-artifacts.js

@@ -0,0 +1,166 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { ReleaseArtifact } from "@parity/product-lab/domain/versions";
+const TARGETS = {
+    "darwin arm64": "aarch64-apple-darwin",
+    "darwin x64": "x86_64-apple-darwin",
+    "linux x64": "x86_64-unknown-linux-gnu",
+    "linux arm64": "aarch64-unknown-linux-gnu",
+};
+export function machineTarget(platform = process.platform, arch = process.arch) {
+    return TARGETS[`${platform} ${arch}`];
+}
+export function productLabCacheDir(env = process.env) {
+    const configured = env.PRODUCT_LAB_CACHE_DIR;
+    if (configured) {
+        if (!isAbsolute(configured))
+            throw new Error(`PRODUCT_LAB_CACHE_DIR must be an absolute path, not ${configured}`);
+        return configured;
+    }
+    const xdg = env.XDG_CACHE_HOME;
+    return join(xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".cache"), "product-lab");
+}
+const MAX_BYTES = 512 * 1024 * 1024;
+const DOWNLOAD_HOST = (hostname) => hostname === "github.com" || hostname.endsWith(".githubusercontent.com");
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|localhost|\[::1\])$/;
+const sha256Of = async (file) => {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(file), hash);
+    return hash.digest("hex");
+};
+const sha256OfSync = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
+const megabytes = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+export class GitHubReleaseArtifacts {
+    options;
+    location;
+    target;
+    constructor(options = {}) {
+        this.options = options;
+        this.location = options.cacheDir ?? productLabCacheDir();
+        if (!isAbsolute(this.location))
+            throw new Error(`The artifact cache must be an absolute path, not ${this.location}`);
+        this.target = options.target ?? machineTarget();
+        if (options.releaseBase !== undefined && !LOOPBACK.test(new URL(options.releaseBase).hostname))
+            throw new Error("releaseBase is for tests: it must be a loopback URL");
+    }
+    handles(component) {
+        return ReleaseArtifact.isArtifact(component);
+    }
+    artifact(component) {
+        if (!this.target)
+            throw new Error(`${component.id} has no release file for ${process.platform} ${process.arch}: no known target triple`);
+        return ReleaseArtifact.forTarget(component, this.target);
+    }
+    directory(artifact) {
+        return join(this.location, "artifacts", "sha256", artifact.sha256);
+    }
+    url(artifact) {
+        if (!this.options.releaseBase)
+            return artifact.url;
+        return `${this.options.releaseBase.replace(/\/$/, "")}/${artifact.repository}/releases/download/${encodeURIComponent(artifact.tag)}/${encodeURIComponent(artifact.asset)}`;
+    }
+    located(artifact, path, bytes) {
+        return { component: artifact.component, path, asset: artifact.asset, url: artifact.url, sha256: `sha256:${artifact.sha256}`, bytes };
+    }
+    locate(component) {
+        const id = component.id.toString();
+        let artifact;
+        try {
+            artifact = this.artifact(component);
+        }
+        catch (error) {
+            return { component: id, reason: error.message };
+        }
+        const directory = this.directory(artifact);
+        const path = join(directory, artifact.asset);
+        const recordFile = join(directory, "verified.json");
+        if (!existsSync(path) || !existsSync(recordFile))
+            return { component: id, reason: `${artifact} is not in the cache (${this.location})` };
+        const stats = statSync(path);
+        let record;
+        try {
+            record = JSON.parse(readFileSync(recordFile, "utf8"));
+            if (!record || record.schemaVersion !== 1 || record.sha256 !== artifact.sha256)
+                return { component: id, reason: `the verification record for ${artifact} is invalid; run product-lab fetch` };
+        }
+        catch {
+            return { component: id, reason: `the verification record for ${artifact} is unreadable; run product-lab fetch` };
+        }
+        if (sha256OfSync(path) !== artifact.sha256)
+            return { component: id, reason: `the cached copy of ${artifact} at ${path} does not match the lock's sha256 (delete ${directory} and fetch again)` };
+        if (record.bytes !== stats.size || record.mtimeMs !== stats.mtimeMs) {
+            writeFileSync(recordFile, JSON.stringify({ ...record, bytes: stats.size, mtimeMs: stats.mtimeMs, verifiedAt: new Date().toISOString() }, null, 2) + "\n");
+        }
+        if (component.id.kind === "binary" && (stats.mode & 0o111) === 0)
+            chmodSync(path, 0o755);
+        return this.located(artifact, path, stats.size);
+    }
+    async acquire(component, options = {}) {
+        const started = performance.now();
+        const cached = this.locate(component);
+        if ("path" in cached)
+            return { ...cached, downloaded: false, ms: Math.round(performance.now() - started) };
+        const artifact = this.artifact(component);
+        const log = options.log ?? (() => { });
+        const directory = this.directory(artifact);
+        const url = this.url(artifact);
+        mkdirSync(join(this.location, "artifacts", "sha256"), { recursive: true, mode: 0o755 });
+        const partial = join(this.location, "artifacts", `.download-${artifact.sha256.slice(0, 12)}-${randomBytes(4).toString("hex")}`);
+        try {
+            const response = await (this.options.fetch ?? fetch)(url, { redirect: "follow", ...(options.signal ? { signal: options.signal } : {}) });
+            const final = new URL(response.url || url);
+            const allowed = this.options.releaseBase ? LOOPBACK.test(final.hostname) : final.protocol === "https:" && DOWNLOAD_HOST(final.hostname);
+            if (!allowed)
+                throw new Error(`Refusing ${final.origin}: release files come only from GitHub's download hosts over https`);
+            if (!response.ok || !response.body)
+                throw new Error(`Downloading ${url} failed: HTTP ${response.status}`);
+            const length = Number(response.headers.get("content-length") ?? 0);
+            if (length > MAX_BYTES)
+                throw new Error(`${url} is larger than ${megabytes(MAX_BYTES)}`);
+            log(`downloading ${artifact}${length ? `, ${megabytes(length)}` : ""} from ${url}`);
+            const hash = createHash("sha256");
+            let bytes = 0;
+            const body = Readable.fromWeb(response.body);
+            body.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > MAX_BYTES)
+                    body.destroy(new Error(`${url} is larger than ${megabytes(MAX_BYTES)}`));
+                hash.update(chunk);
+            });
+            await pipeline(body, createWriteStream(partial, { mode: 0o600 }));
+            const actual = hash.digest("hex");
+            if (actual !== artifact.sha256)
+                throw new Error(`Checksum mismatch for ${artifact}: the lock says sha256 ${artifact.sha256}, the download is ${actual}`);
+            if ((await sha256Of(partial)) !== artifact.sha256)
+                throw new Error(`${artifact} changed on disk while it was downloaded`);
+            chmodSync(partial, component.id.kind === "binary" ? 0o755 : 0o644);
+            mkdirSync(directory, { recursive: true, mode: 0o755 });
+            const path = join(directory, artifact.asset);
+            renameSync(partial, path);
+            const stats = statSync(path);
+            const record = {
+                schemaVersion: 1,
+                component: artifact.component,
+                asset: artifact.asset,
+                url: artifact.url,
+                sha256: artifact.sha256,
+                bytes: stats.size,
+                mtimeMs: stats.mtimeMs,
+                verifiedAt: new Date().toISOString(),
+            };
+            writeFileSync(join(directory, "verified.json"), JSON.stringify(record, null, 2) + "\n", { mode: 0o644 });
+            const ms = Math.round(performance.now() - started);
+            log(`verified ${artifact}: ${megabytes(stats.size)} in ${(ms / 1000).toFixed(1)} s, sha256 ${actual}`);
+            return { ...this.located(artifact, path, stats.size), downloaded: true, ms };
+        }
+        finally {
+            rmSync(partial, { force: true });
+        }
+    }
+}

package/adapters/versions/github/src/github-release-fixture-source.d.ts

@@ -0,0 +1,51 @@
+import type { FixtureDownload, FixtureSource, FixtureSourceFiles } from "@parity/product-lab/ports/storage";
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+export type AttestationPolicy = "required" | "when-available" | "skip";
+export interface GithubReleaseFixtureSourceOptions {
+    readonly id: string;
+    /** `owner/name`. */
+    readonly repository: string;
+    readonly tag: string;
+    /** Default `when-available`. */
+    readonly attestation?: AttestationPolicy;
+    /** The workflow that must have signed (`owner/repo/.github/workflows/<file>`), passed to `gh attestation verify`. */
+    readonly signerWorkflow?: string;
+    /** A token for a private release (sent to `apiBase` only). */
+    readonly token?: string;
+    /** The fetch to use: the GitHub API is a public endpoint, so the caller passes it explicitly (the opt-in). */
+    readonly fetch: typeof fetch;
+    /** Default `https://api.github.com` (tests point it at a local server). */
+    readonly apiBase?: string;
+    /** Runs `gh attestation verify`; absent: attestations cannot be verified here. */
+    readonly commands?: CommandRunner;
+    /** Bound of each request (default 60 s for metadata; downloads are bounded by the caller's signal). */
+    readonly timeoutMs?: number;
+}
+/** A published file whose content is not what the catalog says; refused as it is. */
+export declare class ReleaseAssetError extends Error {
+    constructor(message: string);
+}
+export declare class GithubReleaseFixtureSource implements FixtureSource {
+    #private;
+    private readonly options;
+    readonly kind: "github-release";
+    readonly id: string;
+    constructor(options: GithubReleaseFixtureSourceOptions);
+    get location(): string;
+    private get api();
+    private headers;
+    private signal;
+    /** The release's assets (read once per source), or undefined when the release does not exist. */
+    private assets;
+    private asset;
+    private fetchAsset;
+    catalog(signal?: AbortSignal): Promise<unknown>;
+    download(files: FixtureSourceFiles, directory: string, options?: {
+        signal?: AbortSignal;
+        progress?: (bytes: number) => void;
+    }): Promise<FixtureDownload>;
+    /** Check each file's build attestation as the policy asks. */
+    private attest;
+    /** What a person runs to publish a bundle and its catalog to the release (product-lab never uploads). */
+    publishCommand(index: string, files: FixtureSourceFiles, catalogFile: string): readonly string[];
+}

package/adapters/versions/github/src/github-release-fixture-source.js

@@ -0,0 +1,193 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+const CATALOG = "manifest.json";
+export class ReleaseAssetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReleaseAssetError";
+    }
+}
+async function sha256Of(file) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+export class GithubReleaseFixtureSource {
+    options;
+    kind = "github-release";
+    id;
+    #assets;
+    constructor(options) {
+        this.options = options;
+        this.id = options.id;
+    }
+    get location() {
+        return `${this.options.repository}@${this.options.tag}`;
+    }
+    get api() {
+        return (this.options.apiBase ?? "https://api.github.com").replace(/\/+$/, "");
+    }
+    headers(accept) {
+        return { accept, "user-agent": "product-lab", "x-github-api-version": "2022-11-28", ...(this.options.token ? { authorization: `Bearer ${this.options.token}` } : {}) };
+    }
+    signal(signal) {
+        const bound = AbortSignal.timeout(this.options.timeoutMs ?? 60_000);
+        return signal ? AbortSignal.any([signal, bound]) : bound;
+    }
+    assets(signal) {
+        this.#assets ??= (async () => {
+            const response = await this.options.fetch(`${this.api}/repos/${this.options.repository}/releases/tags/${encodeURIComponent(this.options.tag)}`, {
+                headers: this.headers("application/vnd.github+json"),
+                signal: this.signal(signal),
+            });
+            if (response.status === 404)
+                return undefined;
+            if (!response.ok)
+                throw new Error(`GitHub answered ${response.status} for the release ${this.location}${response.status === 401 || response.status === 403 ? " (a private release needs GITHUB_TOKEN)" : ""}`);
+            const release = (await response.json());
+            return release.assets ?? [];
+        })();
+        const pending = this.#assets;
+        pending.catch(() => {
+            if (this.#assets === pending)
+                this.#assets = undefined;
+        });
+        return pending;
+    }
+    async asset(name, signal) {
+        const assets = await this.assets(signal);
+        if (!assets)
+            throw new ReleaseAssetError(`the release ${this.location} does not exist`);
+        const found = assets.find((asset) => asset.name === name);
+        if (!found)
+            throw new ReleaseAssetError(`the release ${this.location} has no asset ${name}`);
+        return found;
+    }
+    async fetchAsset(asset, signal) {
+        const response = await this.options.fetch(asset.url, { headers: this.headers("application/octet-stream"), redirect: "follow", ...(signal ? { signal } : {}) });
+        if (!response.ok || !response.body)
+            throw new Error(`GitHub answered ${response.status} for ${asset.name} of ${this.location}`);
+        return response;
+    }
+    async catalog(signal) {
+        const assets = await this.assets(signal);
+        const found = assets?.find((asset) => asset.name === CATALOG);
+        if (!found)
+            return undefined;
+        const response = await this.fetchAsset(found, this.signal(signal));
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`${CATALOG} of ${this.location} is not a fixture catalog (not JSON)`, { cause: error });
+        }
+    }
+    async download(files, directory, options = {}) {
+        mkdirSync(directory, { recursive: true });
+        const entries = [{ file: files.index, sha256: files.indexSha256 }, ...files.parts.map((part) => ({ ...part }))];
+        let fetchedBytes = 0;
+        for (const entry of entries) {
+            const target = join(directory, entry.file);
+            if (existsSync(target) && (entry.bytes === undefined || statSync(target).size === entry.bytes) && (await sha256Of(target)) === entry.sha256)
+                continue;
+            const asset = await this.asset(entry.file, options.signal);
+            if (entry.bytes !== undefined && asset.size !== entry.bytes)
+                throw new ReleaseAssetError(`${entry.file} is ${asset.size} bytes in ${this.location}; its catalog says ${entry.bytes}`);
+            if (asset.digest && asset.digest !== `sha256:${entry.sha256}`)
+                throw new ReleaseAssetError(`${entry.file} in ${this.location} has digest ${asset.digest}; its catalog says sha256:${entry.sha256}; nothing was downloaded`);
+            const response = await this.fetchAsset(asset, options.signal);
+            const partial = `${target}.partial`;
+            const hash = createHash("sha256");
+            let bytes = 0;
+            const body = Readable.fromWeb(response.body);
+            body.on("data", (chunk) => {
+                hash.update(chunk);
+                bytes += chunk.length;
+                options.progress?.(fetchedBytes + bytes);
+            });
+            try {
+                await pipeline(body, createWriteStream(partial, { mode: 0o644 }), ...(options.signal ? [{ signal: options.signal }] : []));
+            }
+            catch (error) {
+                rmSync(partial, { force: true });
+                throw error;
+            }
+            const sha256 = hash.digest("hex");
+            if (sha256 !== entry.sha256 || (entry.bytes !== undefined && bytes !== entry.bytes)) {
+                rmSync(partial, { force: true });
+                throw new ReleaseAssetError(`${entry.file} from ${this.location} does not match its checksum (sha256 ${sha256.slice(0, 12)}…, ${bytes} bytes; the catalog says ${entry.sha256.slice(0, 12)}…)`);
+            }
+            renameSync(partial, target);
+            fetchedBytes += bytes;
+        }
+        const attestation = await this.attest(entries.map((entry) => ({ file: join(directory, entry.file), sha256: entry.sha256 })), options.signal);
+        return { index: join(directory, files.index), fetchedBytes, attestation };
+    }
+    async attest(files, signal) {
+        const policy = this.options.attestation ?? "when-available";
+        if (policy === "skip")
+            return { status: "skipped", reason: "attestation check disabled for this source" };
+        const unavailable = (reason) => {
+            if (policy === "required")
+                throw new ReleaseAssetError(`Attestation required but not verifiable for ${this.location}: ${reason}`);
+            return { status: "unavailable", reason };
+        };
+        const published = [];
+        for (const entry of files) {
+            const response = await this.options.fetch(`${this.api}/repos/${this.options.repository}/attestations/sha256:${entry.sha256}`, { headers: this.headers("application/vnd.github+json"), signal: this.signal(signal) });
+            if (response.status === 404)
+                continue;
+            if (!response.ok)
+                return unavailable(`the attestation API answered ${response.status}`);
+            const body = (await response.json());
+            if (body.attestations?.length)
+                published.push(entry);
+        }
+        if (!published.length)
+            return unavailable("no build attestation is published for these files");
+        if (published.length < files.length)
+            return unavailable(`only ${published.length} of ${files.length} files have a published attestation`);
+        const commands = this.options.commands;
+        if (!commands)
+            return unavailable("the GitHub CLI (gh) is not available here to verify the published attestations");
+        let certificate;
+        for (const entry of published) {
+            let result;
+            try {
+                result = await commands.run({
+                    command: "gh",
+                    args: ["attestation", "verify", entry.file, "--repo", this.options.repository, ...(this.options.signerWorkflow ? ["--signer-workflow", this.options.signerWorkflow] : []), "--format", "json"],
+                    timeoutMs: 120_000,
+                    maxOutputBytes: 32 * 1024 * 1024,
+                    ...(signal ? { signal } : {}),
+                    ...(this.options.token ? { env: { GH_TOKEN: this.options.token } } : {}),
+                });
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return unavailable("the GitHub CLI (gh) is not installed");
+                throw error;
+            }
+            if (result.code !== 0)
+                throw new ReleaseAssetError(`The build attestation of ${entry.file} does not verify (${result.stderr.trim().split("\n").slice(-2).join(" ")}); refusing it`);
+            const [first] = JSON.parse(result.stdout);
+            if (!first?.verificationResult?.statement?.subject?.some((subject) => subject.digest?.sha256 === entry.sha256))
+                throw new ReleaseAssetError(`The build attestation gh verified does not name ${entry.file}'s digest; refusing it`);
+            certificate = first.verificationResult.signature?.certificate;
+        }
+        return { status: "verified", ...(certificate?.buildSignerURI ? { signerWorkflow: certificate.buildSignerURI } : {}), ...(certificate?.sourceRepositoryDigest ? { sourceCommit: certificate.sourceRepositoryDigest } : {}) };
+    }
+    publishCommand(index, files, catalogFile) {
+        const directory = index.slice(0, index.lastIndexOf("/"));
+        const quote = (path) => (/^[A-Za-z0-9_./:@-]+$/.test(path) ? path : `'${path.replaceAll("'", "'\\''")}'`);
+        const paths = [index, ...files.parts.map((part) => join(directory, part.file)), catalogFile].map(quote);
+        return [`gh release upload ${quote(this.options.tag)} ${paths.join(" ")} --repo ${this.options.repository} --clobber`];
+    }
+}

package/adapters/versions/github/src/github-version-source.d.ts

@@ -0,0 +1,78 @@
+import { ComponentId, LockedComponent, VersionSelector, type FetchRecord } from "@parity/product-lab/domain/versions";
+import type { Clock } from "@parity/product-lab/ports/system";
+import type { HttpClient, ObservedComponent, ResolveRequest, SourceResolution, VersionSource } from "@parity/product-lab/ports/versions";
+/** How one component is published on GitHub. */
+export interface GitHubComponent {
+    /** `owner/repo`. */
+    readonly repository: string;
+    /** The tag of a version, `{version}` replaced: `@parity/truapi@{version}`, `v{version}` (default `{version}`). */
+    readonly tag?: string;
+    /**
+     * Digest name → release asset name (`{version}` replaced), for example
+     * `{ "archive:aarch64-apple-darwin": "truapi-host-{version}-aarch64-apple-darwin.tar.gz" }`.
+     * Each asset's sha256 comes from GitHub's asset digest or a `<asset>.sha256` file.
+     */
+    readonly assets?: Readonly<Record<string, string>>;
+    /** Let `latest-release` pick pre-releases (default false). Drafts never. */
+    readonly prereleases?: boolean;
+    /**
+     * How `latest-release` and `publishedVersions` rank versions that are not dotted: a regular expression a version must
+     * match, its groups read as numbers in order, an absent group as 0. polkadot-sdk's `^polkadot-stable(\d+)(?:-(\d+))?$`
+     * puts `polkadot-stable2606-2` (2606.2) after `polkadot-stable2603-7` (2603.7) and skips `polkadot-stable2609-rc2`.
+     * Absent: a dotted version (`0.20.0`, `v1.2.3-rc.1`).
+     */
+    readonly order?: string;
+}
+export interface GitHubVersionSourceOptions {
+    readonly http: HttpClient;
+    readonly clock: Clock;
+    /** Keyed by component id (`host:truapi-cli`). */
+    readonly components: Readonly<Record<string, GitHubComponent>>;
+    /** Aliases for git selectors, `{ "host-rust-core": "paritytech/host-rust-core" }`. */
+    readonly repositories?: Readonly<Record<string, string>>;
+    /** Default `https://api.github.com`. */
+    readonly apiBase?: string;
+    /** A GitHub token (for rate limits), sent to the API host only and never recorded. */
+    readonly token?: string;
+    readonly timeoutMs?: number;
+    /** Release pages (100 each) `latest-release` scans (default 3). */
+    readonly maxPages?: number;
+}
+export declare class GitHubVersionSource implements VersionSource {
+    private readonly options;
+    readonly id = "github";
+    private readonly api;
+    private readonly components;
+    constructor(options: GitHubVersionSourceOptions);
+    supports(component: ComponentId, selector: VersionSelector): boolean;
+    canObserve(component: LockedComponent): boolean;
+    resolve(request: ResolveRequest): Promise<SourceResolution>;
+    /**
+     * Backlog 37: the published releases of a declared component from `from` to `to` (versions or tags), both included,
+     * oldest first; drafts never, pre-releases only when the component declares them or an end is one.
+     */
+    publishedVersions(request: {
+        component: ComponentId;
+        from: string;
+        to: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        versions: string[];
+        fetches: FetchRecord[];
+    }>;
+    observe(component: LockedComponent, options?: {
+        signal?: AbortSignal;
+    }): Promise<ObservedComponent>;
+    private repository;
+    private tagFor;
+    /** The version inside a tag, when the tag has the component's form. */
+    private versionOf;
+    private latest;
+    private release;
+    private commit;
+    private assetDigests;
+    /** A JSON API read; undefined on 404. */
+    private json;
+    /** Every fetch goes through here: host rules, the token for the API host only, and a record. */
+    private get;
+}