@cratis/cast 0.0.1 → 0.2.0

package/README.md

@@ -1,3 +1,15 @@
 # @cratis/cast
 
-Placeholder that reserves the package name for [Cratis Cast](https://github.com/Cratis/Cast). The first release is coming; do not install this version.
+The engine behind [Cratis Cast](https://cast.cratis.io) sites: an Astro integration that turns one `cast.yaml` into a verified, event-sourced personal site.
+
+```js
+// astro.config.mjs
+import cast from '@cratis/cast';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({ integrations: [cast()] });
+```
+
+The quickest start is `npm create @cratis/cast@latest`. Documentation: [getting started](https://github.com/Cratis/Cast/blob/main/Documentation/getting-started.md), [cast.yaml reference](https://github.com/Cratis/Cast/blob/main/Documentation/cast-yaml.md), [cast.json reference](https://github.com/Cratis/Cast/blob/main/Documentation/cast-json.md), [badges and the registry](https://github.com/Cratis/Cast/blob/main/Documentation/badges-and-registry.md).
+
+Besides the integration, the package exports what other Astro projects need to render a Cast profile: `@cratis/cast/profile` (`castView`, the hosts, the browser data), `@cratis/cast/machine` (`castJson`, `profileFromCastJson`, the cast.json schema) and the page components `@cratis/cast/site/pages/ProfilePage.astro` and `CvPage.astro`. The JSON Schemas are `@cratis/cast/cast.schema.json` (cast.yaml) and `@cratis/cast/cast-json.schema.json` (cast.json, version 2).

package/badges/RegistryMember.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Tier } from './Tier';
+
+/** One reviewed line in Registry/members.yaml. */
+export type RegistryMember = {
+    github: string;
+    tier: Tier.Core | Tier.Partner;
+    since?: string;
+    role?: string;
+    site?: string;
+    /** URL of the member's /cast.json, for sites that publish it elsewhere. Defaults to `<site>/cast.json`. */
+    profile?: string;
+    company?: string;
+    /** 1-based line in members.yaml where this entry starts, for "verified from" links. */
+    line?: number;
+};

package/badges/ResolvedTier.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.
+
+import type { RegistryMember } from './RegistryMember';
+import type { Tier } from './Tier';
+import type { TierSource } from './TierSource';
+
+/** The tier a handle holds, as verified at build time. */
+export type ResolvedTier = {
+    handle: string;
+    tier?: Tier;
+    source: TierSource;
+    /** The registry entry, when the tier came from the registry. */
+    member?: RegistryMember;
+    /** Merged public pull requests in the Cratis organization, when known. */
+    mergedPullRequests?: number;
+};

package/badges/Tier.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Cast membership tiers. Core and Partner come only from the reviewed registry; Contributor is earned. */
+export enum Tier {
+    /** Founders and maintainers of Cratis. */
+    Core = 'core',
+
+    /** Consultants and companies Cratis vouches for. */
+    Partner = 'partner',
+
+    /** Anyone with at least one merged public pull request in the Cratis organization. */
+    Contributor = 'contributor',
+}

package/badges/TierSource.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Where a resolved tier came from. */
+export enum TierSource {
+    /** A reviewed line in Registry/members.yaml. */
+    Registry = 'registry',
+
+    /** Merged public pull requests in the Cratis organization, counted at build time. */
+    Contributions = 'contributions',
+
+    /** Neither: the person is not (yet) part of the Cast. */
+    None = 'none',
+}

package/badges/badgeSvg.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { castDirectoryUrl } from './constants';
+import { cratisMarkPaths } from './cratisMark';
+import { Tier } from './Tier';
+
+/** How a tier looks on a badge. */
+export type TierStyle = {
+    label: string;
+    description: string;
+    /** Gradient stops, left to right. */
+    from: string;
+    to: string;
+    /** Text on the tier segment. */
+    ink: string;
+};
+
+export const tierStyles: Record<Tier, TierStyle> = {
+    [Tier.Core]: { label: 'Core', description: 'Founder or maintainer of Cratis', from: '#a78bfa', to: '#5eead4', ink: '#140b2e' },
+    [Tier.Partner]: { label: 'Partner', description: 'Vouched for by Cratis', from: '#2dd4bf', to: '#99f6e4', ink: '#042f2b' },
+    [Tier.Contributor]: { label: 'Contributor', description: 'Merged work in the Cratis organization', from: '#f2994a', to: '#fcd34d', ink: '#2d1503' },
+};
+
+const unverified: TierStyle = { label: 'not verified', description: 'Not in the Cast registry and no merged Cratis pull requests yet', from: '#3a3a4a', to: '#4a4a5c', ink: '#e8e6f0' };
+
+const fontStack = "Inter, 'Inter Variable', -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif";
+const serifStack = "Fraunces, 'Fraunces Variable', Georgia, 'Times New Roman', serif";
+const monoStack = "'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace";
+
+const narrow = new Set('fijlrtI.,:;\'!|() '.split(''));
+const wide = new Set('mwMWO@%'.split(''));
+
+/** Approximate rendered width of a string at a font size. `textLength` makes the final rendering exact. */
+export function measureText(text: string, fontSize: number): number {
+    let units = 0;
+    for (const character of text) {
+        if (narrow.has(character)) units += 0.32;
+        else if (wide.has(character)) units += 0.86;
+        else if (character >= 'A' && character <= 'Z') units += 0.66;
+        else units += 0.56;
+    }
+    return Math.ceil(units * fontSize);
+}
+
+const escapeXml = (value: string): string =>
+    value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+
+const mark = (x: number, y: number, size: number, fill: string): string =>
+    `<g transform="translate(${x} ${y}) scale(${(size / 328).toFixed(5)})"><g transform="translate(0 328) scale(.1 -.1)" fill="${fill}">${cratisMarkPaths.map(path => `<path d="${path}"/>`).join('')}</g></g>`;
+
+/**
+ * The inline badge: 20px high, shields-like, with the Cratis mark. Works on light and dark backgrounds
+ * because it carries its own ground.
+ */
+export function badgeSvg(tier: Tier | undefined): string {
+    const style = tier ? tierStyles[tier] : unverified;
+    const height = 20;
+    const leftText = 'Cast';
+    const leftTextWidth = measureText(leftText, 11);
+    const leftWidth = 6 + 12 + 5 + leftTextWidth + 7;
+    const rightTextWidth = measureText(style.label, 11);
+    const rightWidth = rightTextWidth + 16;
+    const width = leftWidth + rightWidth;
+    const title = tier ? `Cratis Cast: ${style.label}` : 'Cratis Cast: not verified';
+    const id = `cast-${tier ?? 'none'}`;
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(title)}">
+<title>${escapeXml(title)}</title>
+<defs>
+<linearGradient id="${id}-tier" x1="0" x2="1" y1="0" y2="0"><stop offset="0" stop-color="${style.from}"/><stop offset="1" stop-color="${style.to}"/></linearGradient>
+<linearGradient id="${id}-gloss" x1="0" x2="0" y1="0" y2="1"><stop offset="0" stop-color="#fff" stop-opacity=".18"/><stop offset=".5" stop-color="#fff" stop-opacity="0"/></linearGradient>
+<clipPath id="${id}-round"><rect width="${width}" height="${height}" rx="5"/></clipPath>
+</defs>
+<g clip-path="url(#${id}-round)">
+<rect width="${leftWidth}" height="${height}" fill="#0c0c15"/>
+<rect x="${leftWidth}" width="${rightWidth}" height="${height}" fill="url(#${id}-tier)"/>
+<rect width="${width}" height="${height}" fill="url(#${id}-gloss)"/>
+<rect x=".5" y=".5" width="${width - 1}" height="${height - 1}" rx="4.5" fill="none" stroke="#fff" stroke-opacity=".12"/>
+</g>
+${mark(4, 4, 12, '#f5f3f0')}
+<g font-family="${fontStack}" font-size="11" font-weight="600" text-rendering="geometricPrecision">
+<text x="${6 + 12 + 5}" y="14" fill="#f5f3f0" textLength="${leftTextWidth}" lengthAdjust="spacingAndGlyphs">${leftText}</text>
+<text x="${leftWidth + 8}" y="14" fill="${style.ink}" textLength="${rightTextWidth}" lengthAdjust="spacingAndGlyphs">${escapeXml(style.label)}</text>
+</g>
+</svg>
+`;
+}
+
+/** Options for the large badge card. */
+export type BadgeCardOptions = {
+    handle: string;
+    name?: string;
+    since?: string;
+};
+
+/**
+ * The large badge card (480 × 168): a dark card with a tier-colored edge, the Cratis mark, the tier in
+ * the italic serif and the verification address. Meant for READMEs, slides and profile pages.
+ */
+export function badgeCardSvg(tier: Tier | undefined, options: BadgeCardOptions): string {
+    const style = tier ? tierStyles[tier] : unverified;
+    const width = 480;
+    const height = 168;
+    const id = `cast-card-${tier ?? 'none'}`;
+    const handle = options.handle.toLowerCase();
+    const address = `${castDirectoryUrl.replace(/^https:\/\//, '')}/${handle}`;
+    const who = options.name ? `${options.name} · @${options.handle}` : `@${options.handle}`;
+    const sinceText = options.since ? ` · since ${options.since}` : '';
+    const title = tier ? `${who}: Cratis Cast ${style.label}` : `${who}: not verified in the Cratis Cast`;
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escapeXml(title)}">
+<title>${escapeXml(title)}</title>
+<defs>
+<linearGradient id="${id}-edge" x1="0" x2="1" y1="0" y2="1"><stop offset="0" stop-color="${style.from}"/><stop offset="1" stop-color="${style.to}"/></linearGradient>
+<radialGradient id="${id}-glow" cx="1" cy="0" r="1"><stop offset="0" stop-color="${style.from}" stop-opacity=".28"/><stop offset=".6" stop-color="${style.from}" stop-opacity="0"/></radialGradient>
+<linearGradient id="${id}-ground" x1="0" x2="0" y1="0" y2="1"><stop offset="0" stop-color="#12121d"/><stop offset="1" stop-color="#08080e"/></linearGradient>
+<pattern id="${id}-grid" width="16" height="16" patternUnits="userSpaceOnUse"><path d="M16 0H0V16" fill="none" stroke="#fff" stroke-opacity=".035"/></pattern>
+</defs>
+<rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="17" fill="url(#${id}-ground)"/>
+<rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="17" fill="url(#${id}-grid)"/>
+<rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="17" fill="url(#${id}-glow)"/>
+<rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="17" fill="none" stroke="url(#${id}-edge)" stroke-width="2"/>
+<rect x="24" y="24" width="56" height="56" rx="14" fill="url(#${id}-edge)"/>
+${mark(30, 30, 44, style.ink)}
+<g font-family="${monoStack}" font-size="11" letter-spacing="1.4" fill="#9b9aa8">
+<text x="98" y="38">CRATIS CAST${tier ? ' · VERIFIED' : ''}</text>
+</g>
+<text x="96" y="78" font-family="${serifStack}" font-style="italic" font-weight="600" font-size="38" fill="${style.from}">${escapeXml(style.label)}</text>
+<g font-family="${fontStack}" fill="#f5f3f0">
+<text x="24" y="118" font-size="16" font-weight="600">${escapeXml(who)}</text>
+<text x="24" y="140" font-size="12.5" fill="#9b9aa8">${escapeXml(style.description + sinceText)}</text>
+</g>
+<text x="${width - 24}" y="140" text-anchor="end" font-family="${monoStack}" font-size="11" fill="#6c6b7a">${escapeXml(address)}</text>
+</svg>
+`;
+}

package/badges/constants.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.
+
+/** The Cast directory. Every verification page lives at `${castDirectoryUrl}/<handle>`. */
+export const castDirectoryUrl = 'https://cast.cratis.io';
+
+/** The organization whose merged public pull requests make someone a Contributor. */
+export const cratisOrganization = 'Cratis';
+
+/** The reviewed registry, read at build time. A copy ships in the package as a fallback. */
+export const registryUrl = 'https://raw.githubusercontent.com/Cratis/Cast/main/Registry/members.yaml';
+
+/** Human-readable location of the registry, for "verified from" links. */
+export const registryBlobUrl = 'https://github.com/Cratis/Cast/blob/main/Registry/members.yaml';
+
+/** The verification page for a handle. */
+export const verificationUrl = (handle: string): string => `${castDirectoryUrl}/${handle.toLowerCase()}`;

package/badges/cratisMark.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The Cratis mark (bracket and hexagon), in a 328 × 328 box drawn with `translate(0 328) scale(.1 -.1)`.
+ * Taken from the cratis.no favicon.
+ */
+export const cratisMarkPaths: readonly string[] = [
+    'M1444 2779c-319-182-592-343-607-358-16-14-34-35-40-46-8-14-10-229-9-735l3-715 23-35c18-26 74-64 222-151 110-64 374-219 589-344 214-126 400-231 413-233 13-3 31 3 42 13 19 17 20 33 20 307 0 233-3 294-15 317-10 21-93 74-327 211-172 101-324 194-338 207l-25 23v802l27 23c14 12 161 100 327 194 177 101 310 184 325 202l26 31v293c0 318-1 325-55 325-12 0-283-149-601-331z',
+    'M1965 2009c-178-98-219-126-237-157-15-26-18-57-18-215 0-175 1-186 23-218 30-45 326-219 372-219 34 0 319 157 361 199 24 23 24 26 24 230v207l-27 31c-39 44-319 203-358 203-19 0-73-24-140-61z',
+];
+
+/** The mark as a standalone SVG element, colored with `currentColor`. */
+export const cratisMarkSvg = (className = ''): string =>
+    `<svg viewBox="0 0 328 328" class="${className}" aria-hidden="true" focusable="false"><g transform="translate(0 328) scale(.1 -.1)" fill="currentColor">${cratisMarkPaths.map(path => `<path d="${path}"/>`).join('')}</g></svg>`;

package/badges/index.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.
+
+export * from './badgeSvg';
+export * from './constants';
+export * from './cratisMark';
+export * from './registry';
+export * from './RegistryMember';
+export * from './ResolvedTier';
+export * from './resolveTier';
+export * from './Tier';
+export * from './TierSource';

package/badges/registry.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { parseDocument, isSeq, isMap } from 'yaml';
+import { z } from 'zod';
+import type { RegistryMember } from './RegistryMember';
+import { Tier } from './Tier';
+
+export const registryMemberSchema = z.object({
+    github: z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/, 'Must be a GitHub login'),
+    tier: z.enum([Tier.Core, Tier.Partner]),
+    since: z.string().regex(/^\d{4}-\d{2}$/, 'Use YYYY-MM').optional(),
+    role: z.string().min(1).optional(),
+    site: z.url({ protocol: /^https$/ }).optional(),
+    profile: z.url({ protocol: /^https$/ }).optional(),
+    company: z.string().min(1).optional(),
+}).strict();
+
+export const registrySchema = z.array(registryMemberSchema);
+
+/** Thrown when members.yaml does not validate. */
+export class RegistryError extends Error {
+    constructor(readonly problems: string[]) {
+        super(`Registry/members.yaml is not valid:\n${problems.map(problem => `  - ${problem}`).join('\n')}`);
+        this.name = 'RegistryError';
+    }
+}
+
+/** Parses and validates the registry. Handles are unique, compared case-insensitively. */
+export function parseRegistry(yamlText: string): RegistryMember[] {
+    const document = parseDocument(yamlText);
+    if (document.errors.length > 0) {
+        throw new RegistryError(document.errors.map(error => error.message));
+    }
+
+    const result = registrySchema.safeParse(document.toJS() ?? []);
+    if (!result.success) {
+        throw new RegistryError(result.error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`));
+    }
+
+    const lines = entryLines(document, yamlText);
+    const seen = new Set<string>();
+    const problems: string[] = [];
+    const members = result.data.map((member, index) => {
+        const key = member.github.toLowerCase();
+        if (seen.has(key)) problems.push(`${index}.github: '${member.github}' is listed more than once`);
+        seen.add(key);
+        return { ...member, line: lines[index] } as RegistryMember;
+    });
+    if (problems.length > 0) throw new RegistryError(problems);
+    return members;
+}
+
+function entryLines(document: ReturnType<typeof parseDocument>, yamlText: string): (number | undefined)[] {
+    if (!isSeq(document.contents)) return [];
+    return document.contents.items.map(item => {
+        const offset = isMap(item) ? item.range?.[0] : undefined;
+        return offset === undefined ? undefined : yamlText.slice(0, offset).split('\n').length;
+    });
+}
+
+/** Where the directory reads a member's profile: `profile`, else `<site>/cast.json`, else nowhere. */
+export const profileUrlOf = (member: Pick<RegistryMember, 'site' | 'profile'>): string | undefined =>
+    member.profile ?? (member.site ? new URL('/cast.json', member.site).toString() : undefined);
+
+/** Finds a member by GitHub login, case-insensitively. */
+export const findMember = (members: readonly RegistryMember[], handle: string): RegistryMember | undefined =>
+    members.find(member => member.github.toLowerCase() === handle.toLowerCase());

package/badges/resolveTier.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { findMember } from './registry';
+import type { RegistryMember } from './RegistryMember';
+import type { ResolvedTier } from './ResolvedTier';
+import { Tier } from './Tier';
+import { TierSource } from './TierSource';
+
+/**
+ * Resolves a handle's tier. The registry decides Core and Partner. Without a registry entry, one or more
+ * merged public pull requests in the Cratis organization make a Contributor. There is no other input:
+ * nothing a site writes about itself can change the result.
+ */
+export function resolveTier(handle: string, registry: readonly RegistryMember[], mergedPullRequests?: number): ResolvedTier {
+    const member = findMember(registry, handle);
+    if (member) {
+        return { handle: member.github, tier: member.tier, source: TierSource.Registry, member, mergedPullRequests };
+    }
+    if (mergedPullRequests !== undefined && mergedPullRequests >= 1) {
+        return { handle, tier: Tier.Contributor, source: TierSource.Contributions, mergedPullRequests };
+    }
+    return { handle, source: TierSource.None, mergedPullRequests };
+}