@cratis/cast 0.0.1 → 0.2.0

package/integration/resolveData.ts

@@ -0,0 +1,138 @@
+// 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 { existsSync } from 'node:fs';
+import path from 'node:path';
+import { cratisOrganization } from '../badges/constants';
+import { resolveTier } from '../badges/resolveTier';
+import type { RegistryMember } from '../badges/RegistryMember';
+import type { ResolvedTier } from '../badges/ResolvedTier';
+import type { GitHubSnapshot } from '../github/GitHubSnapshot';
+import type { CastConfig } from '../config/CastConfig';
+import { parseCast } from '../config/parseCast';
+import { resolveSections } from '../config/resolveSections';
+import { fetchGitHub, gitHubToken, type FreshEvidence } from '../github/fetchGitHub';
+import { emptySnapshot } from '../github/GitHubSnapshot';
+import { fetchWriting } from '../writing/fetchWriting';
+import type { CastData } from './CastData';
+import { loadRegistry } from './loadRegistry';
+import { readSnapshot, writeSnapshot } from './snapshotFile';
+
+/** Inputs for one resolution. */
+export type ResolveDataOptions = {
+    configFile: string;
+    snapshotFile: string;
+    fetch: boolean;
+    castVersion: string;
+    log: { info(message: string): void; warn(message: string): void };
+};
+
+/** Result of a resolution: the data plus the absolute path of a local portrait, if any. */
+export type ResolvedCast = { data: CastData; photoFile?: string };
+
+/** owner/name of every public Cratis repository the cratis section lists. */
+export const trackedCratisRepositories = (config: CastConfig): string[] =>
+    (config.cratis?.repos ?? [])
+        .filter(repository => repository.url?.toLowerCase().startsWith(`https://github.com/${cratisOrganization.toLowerCase()}/`))
+        .map(repository => `${cratisOrganization}/${repository.name}`);
+
+const sameLogin = (left: string, right: string): boolean => left.toLowerCase() === right.toLowerCase();
+
+/** The snapshot's GitHub data, only when it was captured for this identity. */
+export const usableSnapshot = (github: GitHubSnapshot | undefined, identity: string): GitHubSnapshot | undefined =>
+    github && typeof github.login === 'string' && sameLogin(github.login, identity) ? github : undefined;
+
+/**
+ * The tier a site shows: a claim, linked to the directory, which is the authority. Core and Partner come from
+ * the registry by the GitHub login. Contributor comes only from `freshCratisMergedPullRequests`: the count a
+ * search returned in this build for that login. It is never read from a snapshot and never persisted.
+ */
+export function siteTier(identity: string, registry: readonly RegistryMember[], freshCratisMergedPullRequests: number | undefined): ResolvedTier {
+    return resolveTier(identity, registry, freshCratisMergedPullRequests);
+}
+
+/**
+ * Reads cast.yaml, captures build-time data (never failing the build on network problems) and resolves the
+ * verified tier. Order of truth for live data: a fresh fetch, then `.cast/snapshot.json`, then cast.yaml.
+ */
+export async function resolveData(options: ResolveDataOptions): Promise<ResolvedCast> {
+    const configText = await readFile(options.configFile, 'utf8');
+    const config = parseCast(configText, path.basename(options.configFile));
+    const warn = (message: string) => options.log.warn(`${message}`);
+
+    const identity = config.github.login;
+    const snapshot = await readSnapshot(options.snapshotFile);
+    const snapshotGitHub = usableSnapshot(snapshot.github, identity);
+    if (snapshot.github && !snapshotGitHub) {
+        warn(`.cast/snapshot.json holds GitHub data for '${snapshot.github.login}', not '${identity}'; ignoring it`);
+    }
+    let github = snapshotGitHub;
+    let githubSource: CastData['build']['githubSource'] = github ? 'snapshot' : 'none';
+    let writing = snapshot.writing;
+    let changed = false;
+    let freshEvidence: FreshEvidence = {};
+
+    if (options.fetch) {
+        const token = gitHubToken();
+        if (!token) {
+            warn('no GITHUB_TOKEN or GH_TOKEN in the environment; using the snapshot for GitHub data');
+        } else {
+            const result = await fetchGitHub({
+                login: config.github.login,
+                orgs: config.github.orgs,
+                repositories: trackedCratisRepositories(config),
+                releases: config.github.releases,
+                stars: config.github.stars,
+            }, token, github, warn);
+            const fresh = result?.snapshot;
+            if (fresh && !sameLogin(fresh.login, identity)) {
+                warn(`GitHub answered for '${fresh.login}', not '${identity}'; ignoring it`);
+            } else if (result && fresh) {
+                github = fresh;
+                freshEvidence = result.fresh;
+                githubSource = 'live';
+                changed = true;
+                options.log.info(`GitHub: ${fresh.contributions.total} contributions, ${fresh.mergedPullRequests.total} merged pull requests, ${Object.keys(fresh.repositories).length} repositories`);
+            }
+        }
+        if (config.writing.sources.length > 0) {
+            const freshWriting = await fetchWriting(config.writing.sources, warn);
+            if (freshWriting) {
+                writing = freshWriting;
+                changed = true;
+                options.log.info(`writing: ${freshWriting.posts.length} posts`);
+            } else {
+                warn('no posts captured; using the snapshot for writing');
+            }
+        }
+    }
+
+    if (changed) {
+        await writeSnapshot(options.snapshotFile, { version: 1, github, writing });
+    }
+
+    const registry = await loadRegistry(options.fetch, warn);
+    const githubData = github ?? emptySnapshot(identity, config.github.orgs);
+    const tier = siteTier(identity, registry.members, freshEvidence.cratisMergedPullRequests);
+
+    const photo = config.person.photo;
+    const photoUrl = photo && /^https:\/\//.test(photo) ? photo : undefined;
+    const localPhoto = photo && !photoUrl ? path.resolve(path.dirname(options.configFile), photo) : undefined;
+    if (localPhoto && !existsSync(localPhoto)) {
+        warn(`person.photo: ${localPhoto} does not exist; the portrait is left out`);
+    }
+
+    return {
+        data: {
+            config,
+            sections: resolveSections(config),
+            github: githubData,
+            writing: writing ?? { sources: [], posts: [] },
+            tier,
+            photoUrl: photoUrl ?? (localPhoto ? undefined : githubData.profile?.avatarUrl),
+            build: { builtAt: new Date().toISOString(), castVersion: options.castVersion, githubSource, registrySource: registry.source },
+        },
+        photoFile: localPhoto && existsSync(localPhoto) ? localPhoto : undefined,
+    };
+}

package/integration/snapshotFile.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Snapshot } from './Snapshot';
+
+/** Reads the snapshot; a missing or unreadable file is an empty snapshot. */
+export async function readSnapshot(file: string): Promise<Snapshot> {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8')) as Snapshot;
+        return parsed && typeof parsed === 'object' ? { ...parsed, version: 1 } : { version: 1 };
+    } catch {
+        return { version: 1 };
+    }
+}
+
+/** Writes the snapshot with per-week count arrays on one line so diffs stay readable. */
+export async function writeSnapshot(file: string, snapshot: Snapshot): Promise<void> {
+    await mkdir(path.dirname(file), { recursive: true });
+    const json = JSON.stringify(snapshot, null, 2).replace(/\[\s*(\d[\d,\s]*?)\s*\]/g, (_, numbers: string) => `[${numbers.split(/[\s,]+/).join(', ')}]`);
+    await writeFile(file, `${json}\n`);
+}

package/integration/virtualModule.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { CastData } from './CastData';
+
+const moduleId = 'virtual:cast';
+const resolvedModuleId = `\0${moduleId}`;
+
+/** A minimal Vite plugin shape, so the engine does not depend on Vite's types directly. */
+export type VirtualModulePlugin = {
+    name: string;
+    resolveId(id: string): string | undefined;
+    load(id: string): string | undefined;
+};
+
+/**
+ * Serves `virtual:cast`: the resolved data as named exports, plus `photo`, which is the imported local
+ * portrait (an Astro image) when cast.yaml points at a file.
+ */
+export function castVirtualModule(data: () => CastData, photoFile: () => string | undefined): VirtualModulePlugin {
+    return {
+        name: 'cratis-cast:virtual',
+        resolveId(id) {
+            return id === moduleId ? resolvedModuleId : undefined;
+        },
+        load(id) {
+            if (id !== resolvedModuleId) return undefined;
+            const current = data();
+            const photo = photoFile();
+            return [
+                photo ? `import photo from ${JSON.stringify(photo)};` : 'const photo = undefined;',
+                `export const config = ${JSON.stringify(current.config)};`,
+                `export const sections = ${JSON.stringify(current.sections)};`,
+                `export const github = ${JSON.stringify(current.github)};`,
+                `export const writing = ${JSON.stringify(current.writing)};`,
+                `export const tier = ${JSON.stringify(current.tier)};`,
+                `export const photoUrl = ${JSON.stringify(current.photoUrl ?? null)} ?? undefined;`,
+                `export const build = ${JSON.stringify(current.build)};`,
+                'export { photo };',
+            ].join('\n');
+        },
+    };
+}

package/machine/castJson.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { verificationUrl } from '../badges/constants';
+import type { CastData } from '../integration/CastData';
+import { plainText } from '../site/lib/inline';
+import { castJsonVersion } from './castJsonSchema';
+
+export { castJsonVersion };
+
+/** Where the published JSON Schema of cast.json lives. */
+export const castJsonSchemaUrl = 'https://unpkg.com/@cratis/cast/cast-json.schema.json';
+
+/**
+ * The machine-readable profile at /cast.json, format version 2. `profile` is the complete, render-ready
+ * profile: cast.yaml as JSON plus the build-time GitHub and writing captures. The directory renders a member's
+ * full profile from it; agents can read it. The fields before `profile` are the version 1 summary, kept.
+ * `verification.claimedTier` is what this site's build resolved. A site is static and controlled by its owner,
+ * so it is a claim: the directory page at `verification.url` is the source of truth, and the directory never
+ * reads tiers from here.
+ */
+export function castJson(data: CastData, photoUrl?: string) {
+    const { config, tier, github, build } = data;
+    const person = config.person;
+    const { $schema: _schema, ...cast } = config;
+    const { photo: _photo, ...personWithoutPhoto } = person;
+    return {
+        $schema: castJsonSchemaUrl,
+        castJsonVersion,
+        generator: `@cratis/cast ${build.castVersion}`,
+        builtAt: build.builtAt,
+        handle: config.github.login,
+        name: person.name,
+        ...(person.fullName ? { fullName: person.fullName } : {}),
+        title: person.title,
+        ...(person.location ? { location: person.location } : {}),
+        tagline: plainText(person.tagline),
+        intro: plainText(person.intro),
+        site: config.site.url,
+        verification: {
+            url: verificationUrl(config.github.login),
+            claimedTier: tier.tier ?? null,
+            source: tier.source,
+            ...(tier.member?.since ? { since: tier.member.since } : {}),
+            ...(tier.member?.role ? { role: tier.member.role } : {}),
+            claimedAt: build.builtAt,
+            registry: build.registrySource,
+            note: 'Claimed by this site when it was built. The directory page at url is the source of truth.',
+        },
+        links: { github: `https://github.com/${config.github.login}`, ...person.links },
+        career: config.career.events.map(event => ({
+            seq: event.seq,
+            date: event.date,
+            ...(event.endDate ? { endDate: event.endDate } : {}),
+            type: event.type,
+            title: event.title,
+            ...(event.org ? { org: event.org } : {}),
+            ...(event.role ? { role: event.role } : {}),
+            ...(event.endsRole ? { endsRole: event.endsRole } : {}),
+            summary: plainText(event.summary),
+            ...(event.skills?.length ? { skills: event.skills } : {}),
+        })),
+        projects: config.projects.map(project => ({ name: project.name, url: project.url, pitch: plainText(project.pitch), stack: project.stack })),
+        stats: {
+            capturedAt: github.fetchedAt ?? null,
+            source: build.githubSource,
+            contributionsLastYear: github.contributions.total,
+            mergedPullRequests: github.mergedPullRequests.total,
+            mergedPullRequestsByOrg: github.mergedPullRequests.byOrg,
+        },
+        profile: {
+            cast: { ...cast, person: { ...personWithoutPhoto, ...(photoUrl ? { photo: photoUrl } : {}) } },
+            github,
+            writing: data.writing,
+        },
+    };
+}

package/machine/castJsonSchema.ts

@@ -0,0 +1,35 @@
+// 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 { isInstant } from '../config/calendar';
+import { castSchema } from '../config/castSchema';
+import { gitHubSnapshotSchema } from '../github/gitHubSnapshotSchema';
+import { writingSnapshotSchema } from '../writing/writingSnapshotSchema';
+
+/** The cast.json format version this engine writes and the directory renders. */
+export const castJsonVersion = 2;
+
+const login = z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/, 'Must be a GitHub login');
+
+/**
+ * cast.json, format version 2: the complete, render-ready profile. `profile.cast` is cast.yaml as JSON
+ * (validated against cast.schema.json; `person.photo` must be an https URL). `profile.github` and
+ * `profile.writing` are optional build-time captures. Everything outside `profile` is a summary for agents
+ * and earlier readers; `verification` is the site's own claim, which the directory never reads.
+ */
+export const castJsonSchema = z.object({
+    $schema: z.string().optional(),
+    castJsonVersion: z.literal(castJsonVersion),
+    handle: login.describe('The GitHub login: the profile identity. Must equal profile.cast.person.handle.'),
+    generator: z.string().max(200).optional().describe('What wrote the file, for example "@cratis/cast 1.2.0".'),
+    builtAt: z.string().max(64).refine(isInstant, 'Use an ISO 8601 date and time on a real day').optional().describe('When the file was written, ISO 8601.'),
+    profile: z.object({
+        cast: castSchema.describe('cast.yaml as JSON. See https://github.com/Cratis/Cast/blob/main/Documentation/cast-yaml.md'),
+        github: gitHubSnapshotSchema.optional().describe('Public GitHub data captured at build time. Without it the directory uses its own.'),
+        writing: writingSnapshotSchema.optional().describe('Posts captured from the writing sources.'),
+    }),
+}).loose();
+
+/** A cast.json document as written. */
+export type CastJsonInput = z.input<typeof castJsonSchema>;

package/machine/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './castJson';
+export * from './castJsonSchema';
+export * from './profileFromCastJson';

package/machine/llmsText.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { tierStyles } from '../badges/badgeSvg';
+import { verificationUrl } from '../badges/constants';
+import type { CastData } from '../integration/CastData';
+import { formatMonth, project } from '../site/lib/career';
+import { plainText } from '../site/lib/inline';
+
+/** A short, factual Markdown summary for AI agents, following the llms.txt convention. */
+export function llmsText(data: CastData): string {
+    const { config, tier, github } = data;
+    const person = config.person;
+    const site = config.site.url.replace(/\/$/, '');
+    const projection = project(config.career.events);
+    const lines: string[] = [];
+
+    lines.push(`# ${person.name}`, '');
+    lines.push(`> ${person.title}${person.location ? `, ${person.location}` : ''}. ${plainText(person.intro)}`, '');
+
+    if (tier.tier) {
+        const style = tierStyles[tier.tier];
+        lines.push(`Cratis Cast: ${style.label} (${style.description.toLowerCase()}), as claimed by this site's build from ${tier.source === 'registry' ? 'the Cast registry' : 'merged public pull requests in the Cratis organization'}. The authoritative check is ${verificationUrl(config.github.login)}`, '');
+    }
+
+    if (projection.currentRoles.length > 0) {
+        lines.push('## Now', '');
+        for (const role of projection.currentRoles) lines.push(`- ${role.title}, ${role.org} (since ${formatMonth(role.from)})`);
+        lines.push('');
+    }
+
+    if (person.about.length > 0) {
+        lines.push('## About', '', ...person.about.map(paragraph => plainText(paragraph)), '');
+    }
+
+    const roles = [...projection.roles].reverse();
+    if (roles.length > 0) {
+        lines.push('## Experience', '');
+        for (const role of roles) lines.push(`- ${formatMonth(role.from)} – ${role.to ? formatMonth(role.to) : 'present'}: ${role.title}, ${role.org}`);
+        lines.push('');
+    }
+
+    if (config.projects.length > 0) {
+        lines.push('## Projects', '');
+        for (const entry of config.projects) lines.push(`- [${entry.name}](${entry.url}): ${plainText(entry.pitch)}`);
+        lines.push('');
+    }
+
+    const skills = Object.entries(config.skills);
+    if (skills.length > 0) {
+        lines.push('## Skills', '');
+        for (const [group, list] of skills) lines.push(`- ${group}: ${list.join(', ')}`);
+        lines.push('');
+    }
+
+    if (github.fetchedAt) {
+        lines.push('## Public GitHub activity', '');
+        lines.push(`- ${github.contributions.total.toLocaleString('en-US')} contributions in the last year (captured ${github.fetchedAt.slice(0, 10)})`);
+        for (const [org, count] of Object.entries(github.mergedPullRequests.byOrg)) lines.push(`- ${count.toLocaleString('en-US')} merged public pull requests in ${org}`);
+        lines.push('');
+    }
+
+    lines.push('## Machine-readable', '');
+    lines.push(`- [Cast profile](${site}/cast.json): identity, verified tier, career events, projects`);
+    lines.push(`- [JSON Resume](${site}/resume.json)`);
+    lines.push(`- [CV](${site}/cv)`);
+    lines.push('');
+    return lines.join('\n');
+}

package/machine/ogImageSvg.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { tierStyles } from '../badges/badgeSvg';
+import { cratisMarkPaths } from '../badges/cratisMark';
+import type { Tier } from '../badges/Tier';
+import { plainText } from '../site/lib/inline';
+
+/** Inputs for the social preview card. */
+export type OgImageInput = {
+    name: string;
+    title: string;
+    tagline: string;
+    host: string;
+    accent: string;
+    tier?: Tier;
+};
+
+const escapeXml = (value: string): string =>
+    value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Greedy word wrap by an approximate character budget. */
+export function wrap(text: string, maximumCharacters: number, maximumLines: number): string[] {
+    const lines: string[] = [];
+    let current = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if ((current ? `${current} ${word}` : word).length > maximumCharacters && current) {
+            lines.push(current);
+            current = word;
+        } else {
+            current = current ? `${current} ${word}` : word;
+        }
+    }
+    if (current) lines.push(current);
+    if (lines.length > maximumLines) {
+        const kept = lines.slice(0, maximumLines);
+        kept[maximumLines - 1] = `${kept[maximumLines - 1]!.replace(/[.,;:]?$/, '')}…`;
+        return kept;
+    }
+    return lines;
+}
+
+const sans = "Inter, 'Helvetica Neue', Helvetica, Arial, 'DejaVu Sans', sans-serif";
+const serif = "Fraunces, Georgia, 'DejaVu Serif', serif";
+const mono = "'JetBrains Mono', Menlo, 'DejaVu Sans Mono', monospace";
+
+/** The 1200 × 630 social preview card, rendered to PNG at build time. */
+export function ogImageSvg(input: OgImageInput): string {
+    const style = input.tier ? tierStyles[input.tier] : undefined;
+    const tagline = wrap(plainText(input.tagline), 34, 2);
+    const title = wrap(input.title, 64, 2);
+    const mark = `<g transform="translate(80 72) scale(${(40 / 328).toFixed(5)})"><g transform="translate(0 328) scale(.1 -.1)" fill="#f5f3f0">${cratisMarkPaths.map(path => `<path d="${path}"/>`).join('')}</g></g>`;
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+<defs>
+<radialGradient id="a" cx="0.92" cy="0.05" r="0.75"><stop offset="0" stop-color="${input.accent}" stop-opacity=".42"/><stop offset="1" stop-color="${input.accent}" stop-opacity="0"/></radialGradient>
+<radialGradient id="b" cx="0.1" cy="1.05" r="0.6"><stop offset="0" stop-color="#2dd4bf" stop-opacity=".18"/><stop offset="1" stop-color="#2dd4bf" stop-opacity="0"/></radialGradient>
+<pattern id="g" width="40" height="40" patternUnits="userSpaceOnUse"><path d="M40 0H0V40" fill="none" stroke="#ffffff" stroke-opacity=".04"/></pattern>
+${style ? `<linearGradient id="t" x1="0" x2="1"><stop offset="0" stop-color="${style.from}"/><stop offset="1" stop-color="${style.to}"/></linearGradient>` : ''}
+</defs>
+<rect width="1200" height="630" fill="#08080e"/>
+<rect width="1200" height="630" fill="url(#g)"/>
+<rect width="1200" height="630" fill="url(#a)"/>
+<rect width="1200" height="630" fill="url(#b)"/>
+${mark}
+<text x="136" y="101" font-family="${mono}" font-size="20" letter-spacing="3" fill="#a09fad">CRATIS CAST</text>
+${style ? `<g><rect x="${1120 - 52 - style.label.length * 15}" y="66" width="${52 + style.label.length * 15}" height="44" rx="12" fill="url(#t)"/><text x="${1120 - 26}" y="96" text-anchor="end" font-family="${sans}" font-weight="700" font-size="22" fill="${style.ink}">${escapeXml(style.label)}</text></g>` : ''}
+<text x="80" y="250" font-family="${sans}" font-weight="800" font-size="84" letter-spacing="-3" fill="#f5f3f0">${escapeXml(input.name)}</text>
+${title.map((line, index) => `<text x="82" y="${306 + index * 36}" font-family="${sans}" font-size="28" fill="#a09fad">${escapeXml(line)}</text>`).join('\n')}
+${tagline.map((line, index) => `<text x="80" y="${440 + index * 62}" font-family="${serif}" font-style="italic" font-weight="600" font-size="54" fill="${input.accent}">${escapeXml(line)}</text>`).join('\n')}
+<text x="80" y="582" font-family="${mono}" font-size="22" fill="#7c7b8b">${escapeXml(input.host)}</text>
+<rect x="0" y="626" width="1200" height="4" fill="${input.accent}"/>
+</svg>`;
+}
+
+/** The favicon: the person's initial in the italic serif on their accent. */
+export function faviconSvg(initial: string, accent: string, ink: string): string {
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="${accent}"/><text x="32" y="45" text-anchor="middle" font-family="Georgia, 'Times New Roman', serif" font-style="italic" font-weight="700" font-size="40" fill="${ink}">${escapeXml(initial)}</text></svg>`;
+}