@cratis/cast 0.0.1 → 0.2.0

package/github/fetchGitHub.ts

@@ -0,0 +1,235 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { cratisOrganization } from '../badges/constants';
+import type { GitHubSnapshot, Release } from './GitHubSnapshot';
+import { mergedPullRequestQuery, parseCalendar, parseMergedPullRequests, standingAmongHumans, type CalendarWeekNode, type ContributorEntry, type PullRequestNode } from './parse';
+
+/** What to capture. */
+export type GitHubRequest = {
+    login: string;
+    orgs: string[];
+    /** owner/name repositories to compute commit rank and merged pull requests for. */
+    repositories: string[];
+    releases: string[];
+    stars: string[];
+    feedLimit?: number;
+    /** Spacing between search requests (search has its own 30-per-minute limit). Default 2100 ms. */
+    searchDelayMilliseconds?: number;
+};
+
+/**
+ * Evidence fetched in this call only, for granting tiers. Never persisted: a snapshot is owner-editable, so
+ * nothing read from one may grant a tier.
+ */
+export type FreshEvidence = {
+    /** Merged public pull requests in the Cratis organization, when the search succeeded in this call. */
+    cratisMergedPullRequests?: number;
+};
+
+/** A fetch result: the snapshot to render and persist, and the evidence that is used for tiers and then dropped. */
+export type GitHubFetchResult = { snapshot: GitHubSnapshot; fresh: FreshEvidence };
+
+/** Receives warnings; the fetch itself never throws. */
+export type Warn = (message: string) => void;
+
+const userAgent = 'cratis-cast-build';
+const sleep = (milliseconds: number) => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/** Reads the token the build should use, if any. */
+export const gitHubToken = (): string | undefined => process.env.GITHUB_TOKEN || process.env.GH_TOKEN || undefined;
+
+async function rest(path: string, token: string): Promise<Response> {
+    const response = await fetch(`https://api.github.com${path}`, {
+        headers: { authorization: `bearer ${token}`, accept: 'application/vnd.github+json', 'user-agent': userAgent },
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (response.status !== 200) throw new Error(`${path}: GitHub answered ${response.status}`);
+    return response;
+}
+
+/**
+ * Runs a GraphQL query; throws on transport errors and on GraphQL errors. With `allowPartial`, GraphQL errors
+ * (such as one unknown login in a batch) are reported through `onErrors` and whatever data came back is returned.
+ */
+export async function graphql<T>(query: string, variables: Record<string, unknown>, token: string, partial?: { allowPartial: true; onErrors: (messages: string[]) => void }): Promise<T> {
+    const response = await fetch('https://api.github.com/graphql', {
+        method: 'POST',
+        headers: { authorization: `bearer ${token}`, 'content-type': 'application/json', 'user-agent': userAgent },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(25_000),
+    });
+    if (!response.ok) throw new Error(`GitHub GraphQL answered ${response.status} ${response.statusText}`);
+    const body = await response.json() as { data?: T; errors?: { message: string }[] };
+    if (body.errors?.length) {
+        const messages = body.errors.map(error => error.message);
+        if (!partial || !body.data) throw new Error(`GraphQL errors: ${messages.join('; ')}`);
+        partial.onErrors(messages);
+    }
+    if (!body.data) throw new Error('GraphQL returned no data');
+    return body.data;
+}
+
+/** Counts search results. Search has its own 30-per-minute limit, so calls are spaced out. */
+export async function searchCount(query: string, token: string, delayMilliseconds = 2100): Promise<number> {
+    await sleep(delayMilliseconds);
+    const body = await (await rest(`/search/issues?q=${encodeURIComponent(query)}&per_page=1`, token)).json() as { total_count?: number; incomplete_results?: boolean };
+    if (!Number.isInteger(body.total_count) || body.incomplete_results) throw new Error('incomplete search response');
+    return body.total_count!;
+}
+
+async function contributors(repository: string, token: string): Promise<ContributorEntry[]> {
+    const all: ContributorEntry[] = [];
+    for (let page = 1; page <= 10; page++) {
+        const path = `/repos/${repository}/contributors?per_page=100&page=${page}`;
+        let response: Response;
+        try {
+            response = await rest(path, token);
+        } catch (error) {
+            // 202 means GitHub is still computing the statistics; one retry is enough for a build.
+            if (!String(error).includes('answered 202')) throw error;
+            await sleep(1000);
+            response = await rest(path, token);
+        }
+        const items = await response.json() as ContributorEntry[];
+        all.push(...items);
+        if (!response.headers.get('link')?.includes('rel="next"')) break;
+    }
+    if (all.length === 0) throw new Error(`${repository}: no contributors returned`);
+    return all;
+}
+
+const alias = (index: number) => `r${index}`;
+const split = (repository: string): [string, string] => {
+    const [owner, name] = repository.split('/');
+    return [owner ?? '', name ?? ''];
+};
+
+/**
+ * Captures public GitHub data. Returns undefined when nothing could be captured; per-repository failures keep
+ * that repository's previous values. Never throws.
+ */
+export async function fetchGitHub(request: GitHubRequest, token: string, previous: GitHubSnapshot | undefined, warn: Warn): Promise<GitHubFetchResult | undefined> {
+    const delay = request.searchDelayMilliseconds ?? 2100;
+    const tracked = [...new Set([...request.releases, ...request.stars, ...request.repositories])];
+    const repositoryFields = tracked.map((repository, index) => {
+        const [owner, name] = split(repository);
+        return `${alias(index)}: repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { nameWithOwner isPrivate stargazerCount latestRelease { tagName publishedAt url } }`;
+    }).join('\n  ');
+
+    const query = `query($login: String!, $prs: String!) {
+  user(login: $login) {
+    login name bio location websiteUrl avatarUrl
+    followers { totalCount }
+    repositories(privacy: PUBLIC) { totalCount }
+    contributionsCollection {
+      totalCommitContributions
+      contributionCalendar { totalContributions weeks { contributionDays { date contributionCount } } }
+    }
+  }
+  ${repositoryFields}
+  merged: search(query: $prs, type: ISSUE, first: 60) {
+    issueCount
+    nodes { ... on PullRequest { title number url mergedAt repository { nameWithOwner isPrivate } } }
+  }
+}`;
+
+    type RepositoryNode = { nameWithOwner: string; isPrivate: boolean; stargazerCount: number; latestRelease: { tagName: string; publishedAt: string; url: string } | null } | null;
+    type Data = {
+        user: {
+            login: string; name: string | null; bio: string | null; location: string | null; websiteUrl: string | null; avatarUrl: string | null;
+            followers: { totalCount: number }; repositories: { totalCount: number };
+            contributionsCollection: { totalCommitContributions: number; contributionCalendar: { totalContributions: number; weeks: CalendarWeekNode[] } };
+        } | null;
+        merged: { issueCount: number; nodes: PullRequestNode[] };
+    } & Record<string, RepositoryNode>;
+
+    let data: Data;
+    try {
+        data = await graphql<Data>(query, { login: request.login, prs: `${mergedPullRequestQuery(request.login, request.orgs)} sort:updated-desc` }, token);
+    } catch (error) {
+        warn(error instanceof Error ? error.message : String(error));
+        return undefined;
+    }
+    if (!data.user) {
+        warn(`GitHub has no user '${request.login}'`);
+        return undefined;
+    }
+
+    const publicRepository = (repository: string): RepositoryNode | undefined => {
+        const node = data[alias(tracked.indexOf(repository))];
+        return node && node.isPrivate === false ? node : undefined;
+    };
+
+    const releases: Record<string, Release> = {};
+    for (const repository of request.releases) {
+        const release = publicRepository(repository)?.latestRelease;
+        if (release) releases[repository] = { tag: release.tagName, publishedAt: release.publishedAt, url: release.url };
+    }
+    const stars: Record<string, number> = {};
+    for (const repository of request.stars) {
+        const node = publicRepository(repository);
+        if (node) stars[repository] = node.stargazerCount;
+    }
+
+    const repositories: GitHubSnapshot['repositories'] = {};
+    for (const repository of request.repositories) {
+        // Never keep even an older snapshot for a repository that is not public now.
+        if (!publicRepository(repository)) continue;
+        const kept = previous?.repositories[repository];
+        if (kept) repositories[repository] = kept;
+        try {
+            const standing = standingAmongHumans(await contributors(repository, token), request.login);
+            const prs = await searchCount(`author:${request.login} repo:${repository} is:public is:pr is:merged`, token, delay);
+            repositories[repository] = { ...standing, prs };
+        } catch (error) {
+            warn(`${repository}: ${error instanceof Error ? error.message : String(error)} (keeping previous values)`);
+        }
+    }
+
+    const byOrg: Record<string, number> = {};
+    const fresh: FreshEvidence = {};
+    for (const org of new Set([...request.orgs, cratisOrganization])) {
+        try {
+            byOrg[org] = await searchCount(mergedPullRequestQuery(request.login, [org]), token, delay);
+            if (org === cratisOrganization && data.user.login.toLowerCase() === request.login.toLowerCase()) fresh.cratisMergedPullRequests = byOrg[org];
+        } catch (error) {
+            // The previous count is kept for display only; it never becomes evidence.
+            const kept = previous?.mergedPullRequests.byOrg[org];
+            if (kept !== undefined) byOrg[org] = kept;
+            warn(`${org} merged pull requests: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    const user = data.user;
+    const calendar = user.contributionsCollection.contributionCalendar;
+    const snapshot: GitHubSnapshot = {
+        fetchedAt: new Date().toISOString(),
+        login: user.login,
+        orgs: request.orgs,
+        profile: {
+            login: user.login,
+            name: user.name ?? undefined,
+            bio: user.bio ?? undefined,
+            location: user.location ?? undefined,
+            blog: user.websiteUrl ?? undefined,
+            avatarUrl: user.avatarUrl ?? undefined,
+            followers: user.followers.totalCount,
+            publicRepositories: user.repositories.totalCount,
+        },
+        contributions: {
+            total: calendar.totalContributions,
+            commits: user.contributionsCollection.totalCommitContributions,
+            weeks: parseCalendar(calendar.weeks),
+        },
+        mergedPullRequests: {
+            total: data.merged.issueCount,
+            byOrg,
+            latest: parseMergedPullRequests(data.merged.nodes, request.feedLimit ?? 12),
+        },
+        repositories,
+        releases,
+        stars,
+    };
+    return { snapshot, fresh };
+}

package/github/gitHubSnapshotSchema.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { z } from 'zod';
+import { isCalendarDate, isInstant } from '../config/calendar';
+
+/** A whole, finite, non-negative number. */
+const count = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const repository = z.string().max(200).regex(/^[\w.-]+\/[\w.-]+$/, 'Use owner/name');
+const maximumEntries = 500;
+const fewEntries = (value: object) => Object.keys(value).length <= maximumEntries;
+const tooMany = `At most ${maximumEntries} entries`;
+const instant = z.string().max(40).refine(isInstant, 'Use an ISO 8601 date and time on a real day');
+const https = z.url({ protocol: /^https$/ });
+
+/** A merged pull request; the URL must be the pull request on github.com. */
+export const pullRequestSchema = z.object({
+    title: z.string().min(1).max(300),
+    repository,
+    number: z.number().int().positive(),
+    url: z.url({ protocol: /^https$/, hostname: /^github\.com$/ }),
+    mergedAt: instant,
+});
+
+export const contributionWeekSchema = z.object({
+    start: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD').refine(isCalendarDate, 'Use a real day: YYYY-MM-DD'),
+    counts: z.array(count).max(7),
+});
+
+/** Public GitHub data a profile renders: the build-time snapshot a Cast site captures, as it appears in cast.json. */
+export const gitHubSnapshotSchema = z.object({
+    fetchedAt: instant.optional(),
+    login: z.string().min(1).max(39).describe('GitHub login the data was captured for. Must be the profile handle.'),
+    orgs: z.array(z.string().min(1).max(100)).max(20).default([]),
+    profile: z.object({
+        login: z.string().min(1).max(39),
+        name: z.string().max(200).optional(),
+        bio: z.string().max(500).optional(),
+        location: z.string().max(200).optional(),
+        blog: z.string().max(500).optional(),
+        avatarUrl: https.optional(),
+        followers: count.optional(),
+        publicRepositories: count.optional(),
+    }).optional(),
+    contributions: z.object({
+        total: count,
+        commits: count.optional(),
+        weeks: z.array(contributionWeekSchema).max(60).default([]),
+    }).default({ total: 0, weeks: [] }).describe('The contribution calendar of the last year, one entry per week starting on Sunday.'),
+    mergedPullRequests: z.object({
+        total: count,
+        byOrg: z.record(z.string().max(100), count).refine(fewEntries, tooMany).default({}),
+        latest: z.array(pullRequestSchema).max(30).default([]),
+    }).default({ total: 0, byOrg: {}, latest: [] }),
+    repositories: z.record(repository, z.object({ commits: count, rank: count, prs: count })).refine(fewEntries, tooMany).default({}).describe('Standing in each tracked repository, by owner/name.'),
+    releases: z.record(repository, z.object({ tag: z.string().min(1).max(100), publishedAt: instant, url: https })).refine(fewEntries, tooMany).default({}),
+    stars: z.record(repository, count).refine(fewEntries, tooMany).default({}),
+});

package/github/parse.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ContributionWeek, PullRequest } from './GitHubSnapshot';
+
+/** A contributor as the REST contributors endpoint returns it. */
+export type ContributorEntry = { login: string; type?: string; contributions: number };
+
+/** A pull request node as the GraphQL search returns it. */
+export type PullRequestNode = {
+    title?: string;
+    number?: number;
+    url?: string;
+    mergedAt?: string | null;
+    repository?: { nameWithOwner?: string; name?: string; owner?: { login?: string }; isPrivate?: boolean };
+} | null;
+
+const botLogins = new Set(['cratis-bot', 'dependabot', 'github-actions', 'renovate', 'copilot', 'copilot-swe-agent']);
+
+/** True for bots: GitHub's Bot type, `[bot]` and `-bot` logins, and well-known automation accounts. */
+export function isBot(entry: { login: string; type?: string }): boolean {
+    const login = entry.login.toLowerCase();
+    return entry.type === 'Bot' || login.endsWith('[bot]') || login.endsWith('-bot') || botLogins.has(login);
+}
+
+/** Commits and 1-based rank of `login` among human contributors; rank 0 when absent. */
+export function standingAmongHumans(contributors: readonly ContributorEntry[], login: string): { commits: number; rank: number } {
+    const humans = contributors.filter(contributor => !isBot(contributor)).sort((left, right) => right.contributions - left.contributions);
+    const index = humans.findIndex(contributor => contributor.login.toLowerCase() === login.toLowerCase());
+    return index < 0 ? { commits: 0, rank: 0 } : { commits: humans[index]!.contributions, rank: index + 1 };
+}
+
+/**
+ * Turns search nodes into the feed: merged, public only (the token may see private work, the site never
+ * shows it), newest first, capped at `limit`.
+ */
+export function parseMergedPullRequests(nodes: readonly PullRequestNode[], limit: number): PullRequest[] {
+    return nodes
+        .filter((node): node is NonNullable<PullRequestNode> => !!node?.mergedAt && node.repository?.isPrivate === false && !!node.url && node.number !== undefined)
+        .sort((left, right) => right.mergedAt!.localeCompare(left.mergedAt!))
+        .slice(0, limit)
+        .map(node => ({
+            title: node.title ?? '',
+            repository: node.repository!.nameWithOwner ?? `${node.repository!.owner?.login ?? ''}/${node.repository!.name ?? ''}`,
+            number: node.number!,
+            url: node.url!,
+            mergedAt: node.mergedAt!,
+        }));
+}
+
+/** A contribution calendar as the GraphQL API returns it. */
+export type CalendarWeekNode = { contributionDays: { date: string; contributionCount: number }[] };
+
+/** Compacts the calendar into week starts and daily counts. */
+export const parseCalendar = (weeks: readonly CalendarWeekNode[]): ContributionWeek[] =>
+    weeks.filter(week => week.contributionDays.length > 0).map(week => ({
+        start: week.contributionDays[0]!.date,
+        counts: week.contributionDays.map(day => day.contributionCount),
+    }));
+
+/** The search query for merged public pull requests by `login` in any of `orgs`. */
+export const mergedPullRequestQuery = (login: string, orgs: readonly string[]): string =>
+    `author:${login} ${orgs.map(org => `org:${org}`).join(' ')} is:public is:pr is:merged`;

package/index.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sitemap from '@astrojs/sitemap';
+import tailwindcss from '@tailwindcss/vite';
+import type { AstroIntegration } from 'astro';
+import type { CastData } from './integration/CastData';
+import type { CastOptions } from './integration/CastOptions';
+import { resolveData } from './integration/resolveData';
+import { castVirtualModule } from './integration/virtualModule';
+
+export type { CastOptions } from './integration/CastOptions';
+export type { CastData } from './integration/CastData';
+export * from './config/index';
+export * from './badges/index';
+
+const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL('./package.json', import.meta.url)), 'utf8')) as { version: string };
+
+/** The pages and files every Cast site serves. */
+const routes: [pattern: string, entrypoint: string][] = [
+    ['/', 'index.astro'],
+    ['/cv', 'cv.astro'],
+    ['/404', '404.astro'],
+    ['/cast.json', 'cast.json.ts'],
+    ['/resume.json', 'resume.json.ts'],
+    ['/llms.txt', 'llms.txt.ts'],
+    ['/badge.svg', 'badge.svg.ts'],
+    ['/badge-card.svg', 'badge-card.svg.ts'],
+    ['/og.png', 'og.png.ts'],
+    ['/favicon.svg', 'favicon.svg.ts'],
+    ['/apple-touch-icon.png', 'apple-touch-icon.png.ts'],
+    ['/robots.txt', 'robots.txt.ts'],
+];
+
+/**
+ * The Cast integration. Reads cast.yaml, captures public GitHub and writing data at build time, verifies the
+ * tier against the Cast registry and injects every page. Tailwind, fonts and the sitemap are configured here,
+ * so a site needs nothing but `integrations: [cast()]`.
+ */
+export default function cast(options: CastOptions = {}): AstroIntegration {
+    let data: CastData | undefined;
+    let photoFile: string | undefined;
+
+    return {
+        name: '@cratis/cast',
+        hooks: {
+            'astro:config:setup': async ({ config, command, updateConfig, injectRoute, addWatchFile, logger }) => {
+                const root = fileURLToPath(config.root);
+                const configFile = path.resolve(root, options.config ?? 'cast.yaml');
+                const snapshotFile = path.resolve(root, options.snapshot ?? '.cast/snapshot.json');
+                const fetchMode = options.fetch ?? 'build';
+                addWatchFile(configFile);
+
+                const resolved = await resolveData({
+                    configFile,
+                    snapshotFile,
+                    fetch: fetchMode === 'always' || (fetchMode === 'build' && command === 'build'),
+                    castVersion: packageJson.version,
+                    log: logger,
+                });
+                data = resolved.data;
+                photoFile = resolved.photoFile;
+                const site = data.config.site.url;
+                logger.info(`${data.config.person.name} (@${data.config.person.handle}): tier ${data.tier.tier ?? 'none'} from ${data.tier.source}`);
+
+                for (const [pattern, entrypoint] of routes) {
+                    injectRoute({ pattern, entrypoint: `@cratis/cast/routes/${entrypoint}`, prerender: true });
+                }
+
+                updateConfig({
+                    site: config.site ?? site,
+                    trailingSlash: 'ignore',
+                    redirects: { '/resume': '/cv', ...config.redirects },
+                    integrations: [sitemap({ filter: page => !page.endsWith('/404/') && !page.endsWith('/404') })],
+                    vite: {
+                        plugins: [
+                            tailwindcss(),
+                            castVirtualModule(() => data!, () => photoFile),
+                        ],
+                    },
+                } as Parameters<typeof updateConfig>[0]);
+            },
+        },
+    };
+}

package/integration/CastData.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ResolvedTier } from '../badges/ResolvedTier';
+import type { CastConfig } from '../config/CastConfig';
+import type { ResolvedSection } from '../config/ResolvedSection';
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { WritingSnapshot } from '../writing/WritingSnapshot';
+
+/** Everything the site renders from, resolved once per build and served through `virtual:cast`. */
+export type CastData = {
+    config: CastConfig;
+    sections: ResolvedSection[];
+    github: GitHubSnapshot;
+    writing: WritingSnapshot;
+    tier: ResolvedTier;
+    /** Remote portrait URL, when `person.photo` is an https URL. */
+    photoUrl?: string;
+    build: { builtAt: string; castVersion: string; githubSource: 'live' | 'snapshot' | 'none'; registrySource: 'live' | 'bundled' };
+};

package/integration/CastOptions.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Options for the `cast()` integration. */
+export type CastOptions = {
+    /** Path to cast.yaml, relative to the project root. Defaults to `./cast.yaml`. */
+    config?: string;
+
+    /** Where the last good build-time data is kept, relative to the project root. Defaults to `./.cast/snapshot.json`. */
+    snapshot?: string;
+
+    /**
+     * When to fetch GitHub, writing and registry data. `build` (the default) fetches on `astro build` only;
+     * `always` also fetches when the dev server starts; `never` uses the snapshot only.
+     */
+    fetch?: 'build' | 'always' | 'never';
+};

package/integration/Snapshot.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { WritingSnapshot } from '../writing/WritingSnapshot';
+
+/** The file at `.cast/snapshot.json`: the last data that was captured successfully. */
+export type Snapshot = {
+    version: 1;
+    github?: GitHubSnapshot;
+    writing?: WritingSnapshot;
+};

package/integration/loadRegistry.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { registryUrl } from '../badges/constants';
+import { parseRegistry } from '../badges/registry';
+import type { RegistryMember } from '../badges/RegistryMember';
+
+/** The registry copy bundled into the package when it is published. */
+export const bundledRegistryFile = fileURLToPath(new URL('../registry/members.yaml', import.meta.url));
+
+/** Reads the bundled registry; an absent copy is an empty registry. */
+export async function readBundledRegistry(): Promise<RegistryMember[]> {
+    try {
+        return parseRegistry(await readFile(bundledRegistryFile, 'utf8'));
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Reads the reviewed registry from the Cast repository, falling back to the bundled copy. A registry that
+ * fails validation is never used.
+ */
+export async function loadRegistry(fetchLive: boolean, warn: (message: string) => void): Promise<{ members: RegistryMember[]; source: 'live' | 'bundled' }> {
+    if (fetchLive) {
+        try {
+            const response = await fetch(registryUrl, { headers: { 'user-agent': 'cratis-cast-build' }, signal: AbortSignal.timeout(15_000) });
+            if (!response.ok) throw new Error(`answered ${response.status}`);
+            return { members: parseRegistry(await response.text()), source: 'live' };
+        } catch (error) {
+            warn(`registry: ${error instanceof Error ? error.message : String(error)}; using the bundled copy`);
+        }
+    }
+    return { members: await readBundledRegistry(), source: 'bundled' };
+}