@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/versions/github/src/github-version-source.js

@@ -0,0 +1,281 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ARTIFACT_FILE, ComponentId, Digest, LockedComponent, ReleaseArtifact, ReleaseVersion, VersionError, recordedTarget, } from "@parity/product-lab/domain/versions";
+const REPOSITORY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|localhost|\[::1\])$/;
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function assetAttributes(config, version) {
+    const attributes = {};
+    for (const [name, template] of Object.entries(config.assets ?? {}))
+        if (name === ARTIFACT_FILE || name.startsWith(`${ARTIFACT_FILE}:`))
+            attributes[`asset${name.slice(ARTIFACT_FILE.length)}`] = template.replace("{version}", version);
+    return attributes;
+}
+function artifactConfig(component) {
+    if (component.source.type !== "github-release" || !ReleaseArtifact.isArtifact(component))
+        return undefined;
+    const assets = {};
+    for (const name of Object.keys(component.digests)) {
+        const asset = component.attributes[`asset${name.slice(ARTIFACT_FILE.length)}`];
+        if ((name === ARTIFACT_FILE || name.startsWith(`${ARTIFACT_FILE}:`)) && typeof asset === "string")
+            assets[name] = asset;
+    }
+    return { repository: component.source.repository, tag: component.source.tag, assets };
+}
+function observeConfig(declared, component) {
+    const recorded = artifactConfig(component);
+    if (!recorded)
+        return declared;
+    if (!declared)
+        return recorded;
+    return { ...declared, assets: { ...declared.assets, ...recorded.assets } };
+}
+export class GitHubVersionSource {
+    options;
+    id = "github";
+    api;
+    components;
+    constructor(options) {
+        this.options = options;
+        this.api = new URL(options.apiBase ?? "https://api.github.com");
+        if (this.api.protocol !== "https:" && !(this.api.protocol === "http:" && LOOPBACK.test(this.api.hostname)))
+            throw new Error(`GitHub API base ${this.api.origin} must be https (plain http only on loopback, for tests)`);
+        const components = new Map();
+        for (const [id, component] of Object.entries(options.components)) {
+            if (!REPOSITORY.test(component.repository))
+                throw new Error(`${id}: repository ${JSON.stringify(component.repository)} must be owner/repo`);
+            if (component.tag !== undefined && !component.tag.includes("{version}"))
+                throw new Error(`${id}: tag ${JSON.stringify(component.tag)} must contain {version}`);
+            components.set(ComponentId.parse(id).toString(), component);
+        }
+        for (const [alias, repository] of Object.entries(options.repositories ?? {}))
+            if (!REPOSITORY.test(repository))
+                throw new Error(`Repository alias ${alias} must name owner/repo, not ${JSON.stringify(repository)}`);
+        this.components = components;
+    }
+    supports(component, selector) {
+        return this.components.has(component.toString()) && (selector.kind === "latest-release" || selector.kind === "version" || selector.kind === "git");
+    }
+    canObserve(component) {
+        return (component.source.type === "git" ||
+            (component.source.type === "github-release" && (this.components.has(component.id.toString()) || ReleaseArtifact.isArtifact(component))));
+    }
+    async resolve(request) {
+        const config = this.components.get(request.component.toString());
+        if (!config || !this.supports(request.component, request.selector))
+            throw new VersionError("unresolvable", `${this.id} does not resolve ${request.selector} for ${request.component}`);
+        const fetches = [];
+        const signal = request.signal;
+        if (request.selector.kind === "git") {
+            const repository = this.repository(request.selector.repository);
+            const commit = await this.commit(repository, request.selector.ref, fetches, signal);
+            const component = LockedComponent.create(request.component, {
+                version: request.selector.isCommit ? commit.slice(0, 12) : request.selector.ref,
+                source: { type: "git", repository, ref: request.selector.ref, commit },
+                digests: { commit: `git-sha1:${commit}` },
+                selector: request.selector.toJSON(),
+                resolvedAt: this.options.clock.date().toISOString(),
+            });
+            return { component, fetches };
+        }
+        const repository = request.selector.repository ?? config.repository;
+        const release = request.selector.kind === "latest-release"
+            ? await this.latest(repository, config, fetches, signal)
+            : await this.release(repository, this.tagFor(config, request.selector), fetches, signal);
+        if (!release)
+            throw new VersionError("unresolvable", `${repository} has no published release${config.tag ? ` tagged ${config.tag}` : ""}`);
+        const version = this.versionOf(config, release.tag_name) ?? release.tag_name;
+        const digests = { ...(await this.assetDigests(config, version, release, fetches, signal)), commit: `git-sha1:${await this.commit(repository, release.tag_name, fetches, signal)}` };
+        const component = LockedComponent.create(request.component, {
+            version,
+            source: { type: "github-release", repository, tag: release.tag_name },
+            digests,
+            selector: request.selector.toJSON(),
+            resolvedAt: this.options.clock.date().toISOString(),
+            attributes: { prerelease: release.prerelease, ...(release.published_at ? { publishedAt: release.published_at } : {}), ...assetAttributes(config, version) },
+        });
+        return { component, fetches };
+    }
+    async publishedVersions(request) {
+        const config = this.components.get(request.component.toString());
+        if (!config)
+            throw new VersionError("unresolvable", `${this.id} has no releases declared for ${request.component}`);
+        const fetches = [];
+        const ends = [request.from, request.to].map((end) => ({ text: this.versionOf(config, end) ?? end })).map(({ text }) => ({ text, version: rank(config, text) }));
+        if (ends.some((end) => !end.version))
+            throw new VersionError("unresolvable", `${request.from} and ${request.to} must both be release versions of ${request.component}`);
+        const [low, high] = ends.map((end) => end.version);
+        if (low.compare(high) >= 0)
+            throw new VersionError("unresolvable", `${request.from} is not older than ${request.to}`);
+        const prereleases = config.prereleases || low.isPrerelease || high.isPrerelease;
+        const found = new Map();
+        for (let page = 1; page <= (this.options.maxPages ?? 3); page++) {
+            const releases = (await this.json(`/repos/${config.repository}/releases?per_page=100&page=${page}`, fetches, request.signal, `page ${page}`)) ?? [];
+            for (const release of releases) {
+                if (release.draft || (release.prerelease && !prereleases))
+                    continue;
+                const text = this.versionOf(config, release.tag_name);
+                const version = text === undefined ? undefined : rank(config, text);
+                if (!version || (version.isPrerelease && !prereleases) || version.compare(low) < 0 || version.compare(high) > 0)
+                    continue;
+                found.set(text, version);
+            }
+            if (releases.length < 100)
+                break;
+        }
+        for (const end of ends)
+            if (![...found.values()].some((version) => version.compare(end.version) === 0))
+                throw new VersionError("unresolvable", `${config.repository} has no published release ${end.text} of ${request.component}`);
+        return { versions: [...found].sort(([, a], [, b]) => a.compare(b)).map(([text]) => text), fetches };
+    }
+    async observe(component, options = {}) {
+        const fetches = [];
+        try {
+            if (component.source.type === "git") {
+                const source = component.source;
+                const commit = await this.commit(source.repository, source.commit, fetches, options.signal);
+                const tracked = source.ref !== source.commit && !source.commit.startsWith(source.ref);
+                const moved = tracked
+                    ? await this.commit(source.repository, source.ref, fetches, options.signal).then((at) => (at !== source.commit ? `${source.ref} now points at ${at.slice(0, 12)}; the lock keeps ${source.commit.slice(0, 12)}` : undefined), (error) => `Could not check whether ${source.ref} moved: ${error instanceof Error ? error.message : String(error)}`)
+                    : undefined;
+                return {
+                    observed: true,
+                    digests: { commit: `git-sha1:${commit}` },
+                    fetches,
+                    ...(moved ? { notes: [moved] } : {}),
+                };
+            }
+            if (component.source.type !== "github-release")
+                return { observed: false, reason: `${this.id} does not fetch ${component.source.type} components`, fetches };
+            const config = observeConfig(this.components.get(component.id.toString()), component);
+            if (!config)
+                return { observed: false, reason: `${component.id} is not configured for ${this.id}`, fetches };
+            const release = await this.release(component.source.repository, component.source.tag, fetches, options.signal);
+            if (!release)
+                return { observed: false, reason: `release ${component.source.repository}@${component.source.tag} no longer exists`, fetches };
+            const assets = await this.assetDigests(config, component.version, release, fetches, options.signal, Object.keys(component.digests));
+            return { observed: true, digests: { ...assets, commit: `git-sha1:${await this.commit(component.source.repository, release.tag_name, fetches, options.signal)}` }, fetches };
+        }
+        catch (error) {
+            return { observed: false, reason: error.message, fetches };
+        }
+    }
+    repository(name) {
+        const repository = this.options.repositories?.[name] ?? name;
+        if (!REPOSITORY.test(repository))
+            throw new VersionError("unresolvable", `Unknown repository alias ${name} (configure it in repositories, or write owner/repo)`);
+        return repository;
+    }
+    tagFor(config, selector) {
+        if (selector.repository)
+            return selector.version;
+        return this.versionOf(config, selector.version) !== undefined ? selector.version : (config.tag ?? "{version}").replace("{version}", selector.version);
+    }
+    versionOf(config, tag) {
+        const template = config.tag ?? "{version}";
+        const [before, after] = template.split("{version}");
+        const match = new RegExp(`^${escape(before)}(.+)${escape(after)}$`).exec(tag);
+        return match?.[1];
+    }
+    async latest(repository, config, fetches, signal) {
+        let best;
+        for (let page = 1; page <= (this.options.maxPages ?? 3); page++) {
+            const releases = (await this.json(`/repos/${repository}/releases?per_page=100&page=${page}`, fetches, signal, `page ${page}`)) ?? [];
+            for (const release of releases) {
+                if (release.draft || (release.prerelease && !config.prereleases))
+                    continue;
+                const text = this.versionOf(config, release.tag_name);
+                const version = text === undefined ? undefined : rank(config, text);
+                if (!version || (version.isPrerelease && !config.prereleases))
+                    continue;
+                if (!best || version.compare(best.version) > 0)
+                    best = { release, version };
+            }
+            if (releases.length < 100)
+                break;
+        }
+        return best?.release;
+    }
+    async release(repository, tag, fetches, signal) {
+        const release = await this.json(`/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`, fetches, signal);
+        if (release?.draft)
+            return undefined;
+        return release;
+    }
+    async commit(repository, ref, fetches, signal) {
+        const commit = await this.json(`/repos/${repository}/commits/${encodeURIComponent(ref)}`, fetches, signal);
+        if (!commit?.sha || !/^[0-9a-f]{40}$/.test(commit.sha))
+            throw new VersionError("unresolvable", `${repository} has no commit ${ref}`);
+        return commit.sha;
+    }
+    async assetDigests(config, version, release, fetches, signal, only) {
+        const digests = {};
+        for (const [name, template] of Object.entries(config.assets ?? {})) {
+            if (only && !only.includes(name))
+                continue;
+            const file = template.replace("{version}", version);
+            const asset = release.assets.find((item) => item.name === file);
+            if (!asset)
+                throw new VersionError("unresolvable", `Release ${release.tag_name} has no asset ${file}`);
+            if (asset.digest && /^sha256:[0-9a-f]{64}$/i.test(asset.digest)) {
+                digests[name] = Digest.parse(asset.digest).toString();
+                continue;
+            }
+            const sidecar = release.assets.find((item) => item.name === `${file}.sha256`);
+            if (!sidecar)
+                throw new VersionError("unresolvable", `Release ${release.tag_name} publishes no sha256 for ${file} (no asset digest, no ${file}.sha256)`);
+            const response = await this.get(sidecar.browser_download_url, fetches, signal, `${file}.sha256`);
+            if (response.status !== 200)
+                throw new VersionError("unresolvable", `${file}.sha256 answered HTTP ${response.status}`);
+            const hex = /\b[0-9a-f]{64}\b/i.exec(response.body)?.[0];
+            if (!hex)
+                throw new VersionError("unresolvable", `${file}.sha256 holds no sha256`);
+            digests[name] = Digest.of("sha256", hex).toString();
+        }
+        return digests;
+    }
+    async json(path, fetches, signal, detail) {
+        const response = await this.get(`${this.api.toString().replace(/\/$/, "")}${path}`, fetches, signal, detail);
+        if (response.status === 404)
+            return undefined;
+        if (response.status === 403 || response.status === 429)
+            throw new VersionError("unresolvable", `GitHub refused ${path} (HTTP ${response.status}${response.headers["x-ratelimit-remaining"] === "0" ? ", rate limit reached: give the source a token" : ""})`);
+        if (response.status !== 200)
+            throw new VersionError("unresolvable", `GitHub answered HTTP ${response.status} for ${path}`);
+        try {
+            return JSON.parse(response.body);
+        }
+        catch {
+            throw new VersionError("unresolvable", `GitHub answered ${path} with something other than JSON`);
+        }
+    }
+    async get(url, fetches, signal, detail) {
+        const target = new URL(url);
+        const loopbackApi = this.api.protocol === "http:";
+        const allowed = target.host === this.api.host ||
+            (!loopbackApi && (target.hostname === "github.com" || target.hostname.endsWith(".githubusercontent.com")));
+        if (!allowed || (target.protocol !== "https:" && !(loopbackApi && target.protocol === "http:")))
+            throw new VersionError("unresolvable", `${this.id} does not fetch ${target.origin} (only the GitHub API and GitHub's download hosts, over https)`);
+        const started = this.options.clock.now();
+        const at = this.options.clock.date().toISOString();
+        const headers = target.host === this.api.host ? { accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" } : {};
+        if (this.options.token && target.host === this.api.host)
+            headers.authorization = `Bearer ${this.options.token}`;
+        let response;
+        try {
+            response = await this.options.http.get(target.toString(), { headers, ...(signal ? { signal } : {}), ...(this.options.timeoutMs ? { timeoutMs: this.options.timeoutMs } : {}) });
+        }
+        catch (error) {
+            fetches.push({ source: this.id, target: recordedTarget(target.toString()), at, durationMs: this.options.clock.now() - started, detail: `failed: ${error.message}` });
+            throw new VersionError("unresolvable", `${this.id}: ${target.origin}${target.pathname} failed: ${error.message}`);
+        }
+        fetches.push({ source: this.id, target: recordedTarget(target.toString()), at, status: response.status, durationMs: this.options.clock.now() - started, ...(detail ? { detail } : {}) });
+        return response;
+    }
+}
+function rank(config, text) {
+    if (config.order === undefined)
+        return ReleaseVersion.parse(text);
+    const match = new RegExp(config.order).exec(text);
+    return match && match.length > 1 ? ReleaseVersion.parse(match.slice(1).map((group) => group ?? "0").join(".")) : undefined;
+}

package/adapters/versions/github/src/index.d.ts

@@ -0,0 +1,4 @@
+export { GitHubVersionSource, type GitHubComponent, type GitHubVersionSourceOptions } from "./github-version-source.js";
+export { FetchHttpClient } from "./fetch-http-client.js";
+export { GitHubReleaseArtifacts, machineTarget, productLabCacheDir, type GitHubReleaseArtifactsOptions } from "./github-release-artifacts.js";
+export { GithubReleaseFixtureSource, ReleaseAssetError, type AttestationPolicy, type GithubReleaseFixtureSourceOptions } from "./github-release-fixture-source.js";

package/adapters/versions/github/src/index.js

@@ -0,0 +1,6 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { GitHubVersionSource } from "./github-version-source.js";
+export { FetchHttpClient } from "./fetch-http-client.js";
+export { GitHubReleaseArtifacts, machineTarget, productLabCacheDir } from "./github-release-artifacts.js";
+export { GithubReleaseFixtureSource, ReleaseAssetError } from "./github-release-fixture-source.js";

package/adapters/versions/npm/README.md

@@ -0,0 +1,32 @@
+# @product-lab/versions-npm
+
+A `VersionSource` for npm packages (backlog 27):
+the latest dist-tag or an explicit published version of a package, with the registry's integrity for its tarball.
+
+| Class / function | Implements | What it does |
+| --- | --- | --- |
+| `NpmVersionSource` | `VersionSource` (`@product-lab/ports/versions`) | Resolves `latest-release` (the package's `latest` dist-tag) and a plain version, for the components it is configured with. It refuses a named GitHub release (`release:<owner/repo>@<tag>`) and `deployed`. One GET of `<registry>/<package>/<version or latest>`. The package name and version in the answer must be the ones asked for, and the answer must carry a sha512 integrity. The entry's source is `{ type: "npm", package }`, its digest `tarball` (`sha512:<hex>`, the registry's `dist.integrity`) and its attribute `tarball` (the URL without query or credentials). `observe` fetches the locked version again and reports its digest, so a republished tarball shows as a mismatch, and a version no longer published is reported as not observed. Backlog 37: `publishedVersions` lists the package's versions from one to another, both included, oldest first (pre-releases only when an end is one), from one GET of the package document |
+| `integrityDigest(integrity)` | | A registry integrity (`sha512-<base64>`, the sha512 entry of a list) as a lock digest (`sha512:<hex>`); undefined for anything else |
+| `TARBALL_DIGEST` | | `"tarball"`, the digest's name |
+
+```ts
+const npm = new NpmVersionSource({ http: new FetchHttpClient(), clock, components: { "host:truapi-wasm": { package: "@parity/truapi-host" } } });
+```
+
+The source talks only to the registry (default `https://registry.npmjs.org`; plain http only when the registry itself is
+loopback, for tests) and records every fetch (`FetchRecord`, source `npm`). It reads only: nothing is published. A lab
+declares its npm components as data, `defineLab({ versions: { npm: { "host:truapi-wasm": { package: "@parity/truapi-host" } } } })`.
+The composition root routes a `latest-release` or plain version of such a component here, rather than to GitHub.
+
+| | |
+| --- | --- |
+| Nx project | `versions-npm` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `NpmVersionSource`, `NpmComponent`, `NpmVersionSourceOptions`, `integrityDigest`, `TARBALL_DIGEST` |
+| Depends on | `@product-lab/domain`, `@product-lab/ports` (uses `HttpClient`, `Clock`) |
+| Used by | `composition/` (`src/versions/version-source-catalogue.ts`, for the components a lab declares in `versions.npm`) |
+
+Tests: `bunx nx run versions-npm:test`, against a fake registry (an in-memory `HttpClient`). Covered: the latest dist-tag
+and explicit versions, a real 0.23.0 integrity, answers that are not the package or version asked for or have no
+sha512, observing again (a match, a republished tarball, a version no longer published), and the host rules.
+

package/adapters/versions/npm/src/index.d.ts

@@ -0,0 +1 @@
+export { NpmVersionSource, integrityDigest, TARBALL_DIGEST, type NpmComponent, type NpmVersionSourceOptions } from "./npm-version-source.js";

package/adapters/versions/npm/src/index.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { NpmVersionSource, integrityDigest, TARBALL_DIGEST } from "./npm-version-source.js";

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

@@ -0,0 +1,53 @@
+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 npm. */
+export interface NpmComponent {
+    /** The package (`@parity/truapi-host`). */
+    readonly package: string;
+}
+export interface NpmVersionSourceOptions {
+    readonly http: HttpClient;
+    readonly clock: Clock;
+    /** Keyed by component id (`host:truapi-wasm`). */
+    readonly components: Readonly<Record<string, NpmComponent>>;
+    /** Default `https://registry.npmjs.org`. */
+    readonly registry?: string;
+    readonly timeoutMs?: number;
+}
+/** The digest naming a package version's tarball: its registry integrity. */
+export declare const TARBALL_DIGEST = "tarball";
+/** A registry integrity (`sha512-<base64>`) as a lock digest (`sha512:<hex>`); undefined when it is not a sha512 integrity. */
+export declare function integrityDigest(integrity: unknown): string | undefined;
+export declare class NpmVersionSource implements VersionSource {
+    private readonly options;
+    readonly id = "npm";
+    private readonly registry;
+    private readonly components;
+    constructor(options: NpmVersionSourceOptions);
+    supports(component: ComponentId, selector: VersionSelector): boolean;
+    canObserve(component: LockedComponent): boolean;
+    resolve(request: ResolveRequest): Promise<SourceResolution>;
+    observe(component: LockedComponent, options?: {
+        signal?: AbortSignal;
+    }): Promise<ObservedComponent>;
+    /**
+     * Backlog 37: the published versions of a declared package from `from` to `to`, both included, oldest first;
+     * pre-releases only when an end is one. One GET of the package document (`<registry>/<package>`).
+     */
+    publishedVersions(request: {
+        component: ComponentId;
+        from: string;
+        to: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        versions: string[];
+        fetches: FetchRecord[];
+    }>;
+    /** The document's version, its tarball digest and URL, refused when it is not the package or version asked for. */
+    private checked;
+    /** One published version's document (`<registry>/<package>/<version or dist-tag>`); undefined when there is none. */
+    private version;
+    /** Every fetch goes through here: the registry host only, and a record. */
+    private get;
+}

package/adapters/versions/npm/src/npm-version-source.js

@@ -0,0 +1,151 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ComponentId, Digest, LockedComponent, ReleaseVersion, VersionError, recordedTarget } from "@parity/product-lab/domain/versions";
+export const TARBALL_DIGEST = "tarball";
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const LOOPBACK = /^(127\.\d+\.\d+\.\d+|localhost|\[::1\])$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function integrityDigest(integrity) {
+    if (typeof integrity !== "string")
+        return undefined;
+    const sha512 = integrity.split(/\s+/).find((entry) => entry.startsWith("sha512-"));
+    if (!sha512 || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(sha512))
+        return undefined;
+    return Digest.of("sha512", Buffer.from(sha512.slice("sha512-".length), "base64").toString("hex")).toString();
+}
+export class NpmVersionSource {
+    options;
+    id = "npm";
+    registry;
+    components;
+    constructor(options) {
+        this.options = options;
+        this.registry = new URL(options.registry ?? "https://registry.npmjs.org");
+        if (this.registry.protocol !== "https:" && !(this.registry.protocol === "http:" && LOOPBACK.test(this.registry.hostname)))
+            throw new Error(`npm registry ${this.registry.origin} must be https (plain http only on loopback, for tests)`);
+        const components = new Map();
+        for (const [id, component] of Object.entries(options.components)) {
+            if (!PACKAGE.test(component.package))
+                throw new Error(`${id}: ${JSON.stringify(component.package)} is not an npm package name`);
+            components.set(ComponentId.parse(id).toString(), component);
+        }
+        this.components = components;
+    }
+    supports(component, selector) {
+        return this.components.has(component.toString()) && (selector.kind === "latest-release" || (selector.kind === "version" && !selector.repository));
+    }
+    canObserve(component) {
+        return component.source.type === "npm";
+    }
+    async resolve(request) {
+        const config = this.components.get(request.component.toString());
+        if (!config || !this.supports(request.component, request.selector))
+            throw new VersionError("unresolvable", `${this.id} does not resolve ${request.selector} for ${request.component}`);
+        const fetches = [];
+        const wanted = request.selector.kind === "latest-release" ? "latest" : request.selector.version;
+        const document = await this.version(config.package, wanted, fetches, request.signal);
+        if (!document)
+            throw new VersionError("unresolvable", `${config.package} has no published ${wanted === "latest" ? "latest dist-tag" : `version ${wanted}`}`);
+        const { version, digest, tarball } = this.checked(config.package, wanted, document);
+        const component = LockedComponent.create(request.component, {
+            version,
+            source: { type: "npm", package: config.package },
+            digests: { [TARBALL_DIGEST]: digest },
+            selector: request.selector.toJSON(),
+            resolvedAt: this.options.clock.date().toISOString(),
+            ...(tarball ? { attributes: { tarball } } : {}),
+        });
+        return { component, fetches };
+    }
+    async observe(component, options = {}) {
+        const fetches = [];
+        if (component.source.type !== "npm")
+            return { observed: false, reason: `${this.id} does not fetch ${component.source.type} components`, fetches };
+        try {
+            const document = await this.version(component.source.package, component.version, fetches, options.signal);
+            if (!document)
+                return { observed: false, reason: `${component.source.package}@${component.version} is no longer published`, fetches };
+            return { observed: true, digests: { [TARBALL_DIGEST]: this.checked(component.source.package, component.version, document).digest }, fetches };
+        }
+        catch (error) {
+            return { observed: false, reason: error.message, fetches };
+        }
+    }
+    async publishedVersions(request) {
+        const config = this.components.get(request.component.toString());
+        if (!config)
+            throw new VersionError("unresolvable", `${this.id} has no package declared for ${request.component}`);
+        const [low, high] = [request.from, request.to].map((end) => ReleaseVersion.parse(end));
+        if (!low || !high)
+            throw new VersionError("unresolvable", `${request.from} and ${request.to} must both be versions of ${config.package}`);
+        if (low.compare(high) >= 0)
+            throw new VersionError("unresolvable", `${request.from} is not older than ${request.to}`);
+        const fetches = [];
+        const response = await this.get(`${this.registry.toString().replace(/\/$/, "")}/${config.package.replace("/", "%2f")}`, fetches, request.signal);
+        if (response.status !== 200)
+            throw new VersionError("unresolvable", `The npm registry answered HTTP ${response.status} for ${config.package}`);
+        let document;
+        try {
+            document = JSON.parse(response.body);
+        }
+        catch {
+            throw new VersionError("unresolvable", `The npm registry answered ${config.package} with something other than JSON`);
+        }
+        const prereleases = low.isPrerelease || high.isPrerelease;
+        const versions = Object.keys(document.versions ?? {})
+            .filter((text) => VERSION.test(text))
+            .map((text) => ({ text, version: ReleaseVersion.parse(text) }))
+            .filter(({ version }) => version && (prereleases || !version.isPrerelease) && version.compare(low) >= 0 && version.compare(high) <= 0)
+            .sort((a, b) => a.version.compare(b.version))
+            .map(({ text }) => text);
+        for (const end of [request.from, request.to])
+            if (!versions.includes(end))
+                throw new VersionError("unresolvable", `${config.package} has no published version ${end}`);
+        return { versions, fetches };
+    }
+    checked(name, wanted, document) {
+        if (document.name !== name)
+            throw new VersionError("unresolvable", `The registry answered ${name}@${wanted} with ${String(document.name)}`);
+        const version = document.version;
+        if (typeof version !== "string" || !VERSION.test(version))
+            throw new VersionError("unresolvable", `The registry gave ${name}@${wanted} no valid version (${String(version)})`);
+        if (wanted !== "latest" && version !== wanted)
+            throw new VersionError("unresolvable", `The registry answered ${name}@${wanted} with version ${version}`);
+        const digest = integrityDigest(document.dist?.integrity);
+        if (!digest)
+            throw new VersionError("unresolvable", `The registry gives ${name}@${version} no sha512 integrity`);
+        const tarball = typeof document.dist?.tarball === "string" && document.dist.tarball.length <= 256 ? recordedTarget(document.dist.tarball) : undefined;
+        return { version, digest, ...(tarball ? { tarball } : {}) };
+    }
+    async version(name, wanted, fetches, signal) {
+        const url = `${this.registry.toString().replace(/\/$/, "")}/${name.replace("/", "%2f")}/${encodeURIComponent(wanted)}`;
+        const response = await this.get(url, fetches, signal);
+        if (response.status === 404)
+            return undefined;
+        if (response.status !== 200)
+            throw new VersionError("unresolvable", `The npm registry answered HTTP ${response.status} for ${name}@${wanted}`);
+        try {
+            return JSON.parse(response.body);
+        }
+        catch {
+            throw new VersionError("unresolvable", `The npm registry answered ${name}@${wanted} with something other than JSON`);
+        }
+    }
+    async get(url, fetches, signal) {
+        const target = new URL(url);
+        if (target.host !== this.registry.host || target.protocol !== this.registry.protocol)
+            throw new VersionError("unresolvable", `${this.id} does not fetch ${target.origin} (only the registry, ${this.registry.origin})`);
+        const started = this.options.clock.now();
+        const at = this.options.clock.date().toISOString();
+        let response;
+        try {
+            response = await this.options.http.get(target.toString(), { headers: { accept: "application/json" }, ...(signal ? { signal } : {}), ...(this.options.timeoutMs ? { timeoutMs: this.options.timeoutMs } : {}) });
+        }
+        catch (error) {
+            fetches.push({ source: this.id, target: recordedTarget(target.toString()), at, durationMs: this.options.clock.now() - started, detail: `failed: ${error.message}` });
+            throw new VersionError("unresolvable", `${this.id}: ${target.origin}${target.pathname} failed: ${error.message}`);
+        }
+        fetches.push({ source: this.id, target: recordedTarget(target.toString()), at, status: response.status, durationMs: this.options.clock.now() - started });
+        return response;
+    }
+}

package/adapters/video/ffmpeg/README.md

@@ -0,0 +1,39 @@
+# @product-lab/video-ffmpeg
+
+`VideoEditor` adapter (`@product-lab/ports/recording`, backlog 36): a recorded video cut into a demo by the system's
+`ffmpeg` and `ffprobe`.
+
+- `FfmpegVideoEditor({ commands, ffmpeg?, ffprobe?, timeoutMs? })` runs the tools through the `CommandRunner` port
+  (the system adapter's `NodeCommandRunner`; an adapter never spawns a process itself), `ffmpeg` and `ffprobe` on
+  `PATH` unless paths are given (the composition root reads `PRODUCT_LAB_FFMPEG`, the folder holding both).
+- `probe()`: `ffmpeg -version`, `ffprobe -version` and the encoders; without them it returns why, with how to install
+  them (macOS: `brew install ffmpeg`; Debian/Ubuntu: `apt install ffmpeg`).
+- `render(request)`: one ffmpeg run over a filter graph passed inline (`demoFilterGraph`; `-filter_complex`, since ffmpeg 8
+  removed `-filter_complex_script`): per segment `trim`, `setpts` (its speed),
+  `fps=25`, `scale` and `pad` to the output size on the lab's canvas colour, `tpad` to hold a short step's last frame;
+  `concat`; each overlay laid over its time with `overlay=…:enable='between(t,a,b)'`. H.264 MP4 (`yuv420p`,
+  `+faststart`) or VP9 WebM; written to a temporary name and renamed, so the cut appears only once complete. The
+  source is never changed. No `drawtext`, freetype or libass is needed: captions arrive as images.
+- `durationMs(source)`: the container's duration, or, for a browser's WebM that names none, the last frame's time.
+- `frame(source, atMs)`: a PNG of one frame.
+
+## Licence
+
+ffmpeg is not bundled, installed or downloaded by product-lab: the adapter runs the copy the system has, so its
+licence (LGPL or GPL, depending on how that copy was built) stays with that copy and with whoever installed it, and
+nothing of ffmpeg is in what `@parity/product-lab` ships.
+
+| | |
+| --- | --- |
+| Nx project | `video-ffmpeg` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `FfmpegVideoEditor`, `FfmpegVideoEditorOptions`, `demoFilterGraph` |
+| Implements | `VideoEditor` (`@product-lab/ports/recording`) |
+| Depends on | `@product-lab/ports`, `@product-lab/domain`; at run time the system's `ffmpeg` and `ffprobe` |
+| Used by | the composition root |
+
+Tests: `bunx nx run video-ffmpeg:test` (the filter graph; the probe without ffmpeg; with the system's ffmpeg, a
+generated video cut into an MP4 and a WebM of the planned length with an overlay, and a frame; skipped, saying why,
+where ffmpeg is not installed).
+
+Private, workspace-only package. Consumers will install the single umbrella package `@parity/product-lab` once it is published.

package/adapters/video/ffmpeg/src/ffmpeg-video-editor.d.ts

@@ -0,0 +1,40 @@
+import type { DemoPlan } from "@parity/product-lab/domain/recordings";
+import type { VideoEditor, VideoEditorProbe, VideoEditRequest } from "@parity/product-lab/ports/recording";
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+export interface FfmpegVideoEditorOptions {
+    /** Runs ffmpeg and ffprobe (the system adapter's `NodeCommandRunner`). */
+    commands: CommandRunner;
+    /** Default `ffmpeg` and `ffprobe` on PATH. */
+    ffmpeg?: string;
+    ffprobe?: string;
+    /** The longest one render may take (default 10 minutes). */
+    timeoutMs?: number;
+}
+/** The filter graph that cuts `plan` out of input 0 and lays inputs 1..n over it (exported for its test). */
+export declare function demoFilterGraph(plan: DemoPlan, overlays: readonly {
+    startMs: number;
+    endMs: number;
+}[], size: {
+    width: number;
+    height: number;
+}): {
+    graph: string;
+    output: string;
+};
+export declare class FfmpegVideoEditor implements VideoEditor {
+    private readonly commands;
+    private readonly ffmpeg;
+    private readonly ffprobe;
+    private readonly timeoutMs;
+    constructor(options: FfmpegVideoEditorOptions);
+    /** Run `command`; a non-zero exit is an error naming the last lines it printed. */
+    private run;
+    probe(): Promise<VideoEditorProbe>;
+    durationMs(source: string): Promise<number>;
+    frame(source: string, atMs: number): Promise<Uint8Array>;
+    render(request: VideoEditRequest): Promise<{
+        file: string;
+        bytes: number;
+        durationMs: number;
+    }>;
+}