@cratis/cast 0.1.0 → 0.2.0

package/config/calendar.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+const dayPattern = /^(\d{4})-(\d{2})-(\d{2})/;
+
+/** True when `year`, `month` and `day` name a real day: '2026-02-30' and '2026-99-99' do not. */
+function isRealDay(year: number, month: number, day: number): boolean {
+    if (year < 1000 || month < 1 || month > 12 || day < 1) return false;
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+
+/** True for a real calendar day written as 'YYYY-MM-DD'. */
+export function isCalendarDate(value: string): boolean {
+    const match = dayPattern.exec(value);
+    return match !== null && match[0].length === value.length && isRealDay(Number(match[1]), Number(match[2]), Number(match[3]));
+}
+
+/** True for 'YYYY' or 'YYYY-MM' with a real month. */
+export function isCalendarMonth(value: string): boolean {
+    const match = /^(\d{4})(?:-(\d{2}))?$/.exec(value);
+    return match !== null && isRealDay(Number(match[1]), Number(match[2] ?? 1), 1);
+}
+
+/** True for 'YYYY-MM-DD', 'YYYY-MM' or 'YYYY', each a real day or month. */
+export function isPartialDate(value: string): boolean {
+    return value.length === 10 ? isCalendarDate(value) : isCalendarMonth(value);
+}
+
+/** True for an ISO 8601 date or date and time that starts with a real calendar day and that `Date` can read. */
+export function isInstant(value: string): boolean {
+    const match = dayPattern.exec(value);
+    return match !== null && isRealDay(Number(match[1]), Number(match[2]), Number(match[3])) && Number.isFinite(Date.parse(value));
+}

package/config/castSchema.ts

@@ -2,15 +2,16 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { z } from 'zod';
+import { isCalendarMonth, isPartialDate } from './calendar';
 import { LiveStat } from './LiveStat';
 import { SectionId } from './SectionId';
 import { ThemeMode } from './ThemeMode';
 
 /** 'YYYY-MM' or 'YYYY'. */
-const month = z.string().regex(/^\d{4}(-\d{2})?$/, 'Use YYYY-MM or YYYY');
+const month = z.string().regex(/^\d{4}(-\d{2})?$/, 'Use YYYY-MM or YYYY').refine(isCalendarMonth, 'Use a real month: YYYY-MM or YYYY');
 
 /** 'YYYY-MM-DD', 'YYYY-MM' or 'YYYY'. */
-const date = z.string().regex(/^\d{4}(-\d{2}(-\d{2})?)?$/, 'Use YYYY-MM-DD, YYYY-MM or YYYY');
+const date = z.string().regex(/^\d{4}(-\d{2}(-\d{2})?)?$/, 'Use YYYY-MM-DD, YYYY-MM or YYYY').refine(isPartialDate, 'Use a real date: YYYY-MM-DD, YYYY-MM or YYYY');
 
 const url = z.url({ protocol: /^https?$/ });
 const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'Use a six-digit hex color such as #8b5cf6');

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/machine/castJson.ts

@@ -4,20 +4,28 @@
 import { verificationUrl } from '../badges/constants';
 import type { CastData } from '../integration/CastData';
 import { plainText } from '../site/lib/inline';
+import { castJsonVersion } from './castJsonSchema';
 
-/** Version of the /cast.json document. Bumped on breaking changes; additions keep the version. */
-export const castJsonVersion = 1;
+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. Agents can read it; the directory shows its title and tagline.
+ * 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) {
+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,
@@ -60,5 +68,10 @@ export function castJson(data: CastData) {
             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/profileFromCastJson.ts

@@ -0,0 +1,214 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { z } from 'zod';
+import { TierSource } from '../badges/TierSource';
+import type { CastConfig } from '../config/CastConfig';
+import { CastConfigError } from '../config/CastConfigError';
+import { parseCastObject } from '../config/parseCast';
+import { resolveSections } from '../config/resolveSections';
+import { emptySnapshot, type GitHubSnapshot } from '../github/GitHubSnapshot';
+import { assertRenderable } from '../site/profile/assertRenderable';
+import { directoryHost } from '../site/profile/CastHost';
+import { castView } from '../site/profile/CastView';
+import type { WritingSnapshot } from '../writing/WritingSnapshot';
+import { castJsonSchema, castJsonVersion } from './castJsonSchema';
+
+/** The largest cast.json the directory reads, in bytes. */
+export const maximumCastJsonBytes = 1_000_000;
+
+/** A profile read from a cast.json, ready to render. It never carries a tier: tiers come from the directory. */
+export type CastJsonProfile = {
+    handle: string;
+    generator?: string;
+    builtAt?: string;
+    config: CastConfig;
+    /** Present only when it was captured for the profile handle. */
+    github?: GitHubSnapshot;
+    writing?: WritingSnapshot;
+    /** The portrait, when `person.photo` is an https URL. */
+    photoUrl?: string;
+};
+
+/** The outcome of reading a cast.json: the profile and what was dropped from it, or why it was refused. */
+export type CastJsonResult =
+    | { profile: CastJsonProfile; dropped: string[] }
+    | { problems: string[] };
+
+type Path = PropertyKey[];
+type Container = Record<PropertyKey, unknown> | unknown[];
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value);
+const sameLogin = (left: string, right: string) => left.toLowerCase() === right.toLowerCase();
+const describe = (path: Path) => path.map(String).join('.');
+
+function at(root: unknown, path: Path): unknown {
+    return path.reduce<unknown>((value, key) => (value && typeof value === 'object' ? (value as Record<PropertyKey, unknown>)[key] : undefined), root);
+}
+
+function remove(root: unknown, path: Path): void {
+    const parent = at(root, path.slice(0, -1)) as Container | undefined;
+    const key = path[path.length - 1]!;
+    if (Array.isArray(parent) && typeof key === 'number') parent.splice(key, 1);
+    else if (parent && typeof parent === 'object') delete (parent as Record<PropertyKey, unknown>)[key];
+}
+
+/** A link or address that failed validation (javascript:, data:, relative and so on): dropped, not fatal. */
+const isBadLink = (issue: z.core.$ZodIssue): boolean =>
+    issue.code === 'invalid_format' && (issue.format === 'url' || issue.format === 'email');
+
+/** How large any one part of a cast.json may be. The file itself is at most {@link maximumCastJsonBytes}. */
+const limits = { depth: 24, string: 20_000, items: 2_000 };
+
+/** Where the document exceeds {@link limits}, if anywhere. */
+function oversized(value: unknown, path: Path = []): string | undefined {
+    if (path.length > limits.depth) return `${describe(path)}: nested deeper than ${limits.depth} levels`;
+    if (typeof value === 'string') return value.length > limits.string ? `${describe(path)}: longer than ${limits.string} characters` : undefined;
+    if (!value || typeof value !== 'object') return undefined;
+    const entries = Array.isArray(value) ? value.map((item, index) => [index, item] as const) : Object.entries(value);
+    if (entries.length > limits.items) return `${describe(path) || '(root)'}: more than ${limits.items} entries`;
+    for (const [key, item] of entries) {
+        const problem = (typeof key === 'string' && key.length > limits.string ? `${describe(path)}: a key longer than ${limits.string} characters` : undefined) ?? oversized(item, [...path, key]);
+        if (problem) return problem;
+    }
+    return undefined;
+}
+
+/** A portrait the directory can show: an absolute https URL that parses. */
+function isHttpsUrl(value: unknown): value is string {
+    if (typeof value !== 'string' || value.length > 2_000 || !URL.canParse(value)) return false;
+    return new URL(value).protocol === 'https:';
+}
+
+/** The optional build-time captures: when one does not validate, it is dropped and the directory uses its own data. */
+const captures: Path[] = [['profile', 'github'], ['profile', 'writing']];
+const captureOf = (path: Path): Path | undefined => captures.find(capture => capture.every((key, index) => path[index] === key));
+
+/** The path of the array element closest to `path`, when there is one. */
+function enclosingElement(path: Path): Path | undefined {
+    for (let index = path.length - 1; index > 0; index--) {
+        if (typeof path[index] === 'number') return path.slice(0, index + 1);
+    }
+    return undefined;
+}
+
+/**
+ * Validates a cast.json document (format version 2) for rendering by someone other than its owner. Every
+ * link must be http(s) and every address an email: other links are dropped, and an array item whose
+ * required link was dropped goes with it. The identity must equal `expectedLogin` when given, case-insensitively.
+ * A tier anywhere in the file is ignored. A GitHub or writing capture that does not validate, or that the profile
+ * pages cannot render, is dropped. The rest is checked the way the profile pages use it (real dates, URLs that
+ * parse, a career that replays); unknown versions, oversized parts and anything else that does not validate or
+ * render are refused, so one member's file can never stop the directory build.
+ */
+export function profileFromCastJson(json: unknown, expectedLogin?: string): CastJsonResult {
+    if (!isObject(json)) return { problems: ['cast.json is not a JSON object'] };
+    if (json['castJsonVersion'] !== castJsonVersion) return { problems: [`castJsonVersion ${JSON.stringify(json['castJsonVersion'])} is not supported; expected ${castJsonVersion}`] };
+
+    const tooLarge = oversized(json);
+    if (tooLarge) return { problems: [tooLarge] };
+
+    const document = JSON.parse(JSON.stringify(json)) as Record<string, unknown>;
+    const dropped: string[] = [];
+    const cast = at(document, ['profile', 'cast']);
+    if (isObject(cast)) {
+        // A tier is never read from a profile; the directory decides it.
+        if ('tier' in cast) {
+            delete cast['tier'];
+            dropped.push('profile.cast.tier');
+        }
+        const person = cast['person'];
+        if (isObject(person) && person['photo'] !== undefined && !isHttpsUrl(person['photo'])) {
+            delete person['photo'];
+            dropped.push('profile.cast.person.photo');
+        }
+    }
+
+    const removed = new Set<string>();
+    for (let attempt = 0; attempt < 200; attempt++) {
+        const result = castJsonSchema.safeParse(document);
+        if (result.success) return finish(result.data, document, expectedLogin, dropped);
+
+        const issue = result.error.issues.find(candidate => isBadLink(candidate) || removed.has(describe(candidate.path)));
+        if (!issue) {
+            const capture = result.error.issues.map(candidate => captureOf(candidate.path)).find(Boolean);
+            if (!capture) return { problems: result.error.issues.map(problem => `${describe(problem.path) || '(root)'}: ${problem.message}`) };
+            remove(document, capture);
+            dropped.push(describe(capture));
+            removed.clear();
+            continue;
+        }
+        const path = issue.path;
+        if (isBadLink(issue) && !removed.has(describe(path))) {
+            remove(document, path);
+            removed.add(describe(path));
+            dropped.push(describe(path));
+            continue;
+        }
+        // A required link was dropped: drop the item that needs it.
+        const element = enclosingElement(path);
+        if (!element) return { problems: [`${describe(path)}: required, and its value was not a valid link`] };
+        remove(document, element);
+        dropped.push(describe(element));
+        removed.clear();
+    }
+    return { problems: ['cast.json has too many invalid links'] };
+}
+
+function finish(data: z.output<typeof castJsonSchema>, document: Record<string, unknown>, expectedLogin: string | undefined, dropped: string[]): CastJsonResult {
+    if (expectedLogin && !sameLogin(data.handle, expectedLogin)) return { problems: [`handle '${data.handle}' is not '${expectedLogin}'`] };
+
+    let config: CastConfig;
+    try {
+        // Parsed from the document as written, so defaults apply the same way as for cast.yaml.
+        config = parseCastObject(at(document, ['profile', 'cast']), 'cast.json profile.cast');
+    } catch (error) {
+        return { problems: error instanceof CastConfigError ? error.problems : [String(error)] };
+    }
+    if (!sameLogin(config.person.handle, data.handle)) return { problems: [`profile.cast.person.handle '${config.person.handle}' is not the handle '${data.handle}'`] };
+
+    let github: GitHubSnapshot | undefined = data.profile.github as GitHubSnapshot | undefined;
+    if (github && !sameLogin(github.login, data.handle)) {
+        dropped.push('profile.github');
+        github = undefined;
+    }
+    const photo = config.person.photo;
+    const profile: CastJsonProfile = {
+        handle: data.handle,
+        ...(data.generator ? { generator: data.generator } : {}),
+        ...(data.builtAt ? { builtAt: data.builtAt } : {}),
+        config,
+        ...(github ? { github } : {}),
+        ...(data.profile.writing ? { writing: data.profile.writing as WritingSnapshot } : {}),
+        ...(photo ? { photoUrl: photo } : {}),
+    };
+
+    // Rendered without the captures when only they cannot be: the directory then uses its own GitHub data.
+    const problem = renderProblem(profile);
+    if (!problem) return { dropped, profile };
+    const { github: _github, writing: _writing, ...withoutCaptures } = profile;
+    if ((profile.github || profile.writing) && !renderProblem(withoutCaptures)) {
+        dropped.push(...(profile.github ? ['profile.github'] : []), ...(profile.writing ? ['profile.writing'] : []));
+        return { dropped, profile: withoutCaptures };
+    }
+    return { problems: [problem] };
+}
+
+/** Why the profile pages could not render this profile, when they could not. */
+function renderProblem(profile: CastJsonProfile): string | undefined {
+    const { config, handle } = profile;
+    try {
+        assertRenderable(castView({
+            config,
+            sections: resolveSections(config),
+            github: profile.github ?? emptySnapshot(handle, config.github.orgs),
+            writing: profile.writing ?? { sources: [], posts: [] },
+            tier: { handle, source: TierSource.None },
+            ...(profile.photoUrl ? { photoUrl: profile.photoUrl } : {}),
+            build: { builtAt: profile.builtAt ?? new Date(0).toISOString(), castVersion: profile.generator ?? 'cast.json', githubSource: 'none', registrySource: 'live' },
+        }, directoryHost(handle, config.site.url)));
+        return undefined;
+    } catch (error) {
+        return `does not render: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/cast",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Cast: the Cratis profile-site engine. One cast.yaml becomes a verified, event-sourced personal site with a printable CV, live GitHub numbers and a Cast badge.",
     "keywords": [
         "cratis",
@@ -33,6 +33,7 @@
         "**/*.css",
         "**/*.svg",
         "cast.schema.json",
+        "cast-json.schema.json",
         "registry/members.yaml",
         "!**/for_*/**",
         "!vitest.config.ts",
@@ -46,6 +47,9 @@
         "./badges": "./badges/index.ts",
         "./github/*": "./github/*.ts",
         "./cast.schema.json": "./cast.schema.json",
+        "./cast-json.schema.json": "./cast-json.schema.json",
+        "./machine": "./machine/index.ts",
+        "./profile": "./site/profile/index.ts",
         "./package.json": "./package.json",
         "./*": "./*"
     },

package/routes/404.astro

@@ -5,11 +5,13 @@
 import Base from '../site/layouts/Base.astro';
 import Nav from '../site/components/Nav.astro';
 import Footer from '../site/components/Footer.astro';
-import { person } from '../site/data';
+import { cast } from '../site/data';
+
+const { person } = cast;
 ---
 
-<Base title={`EventNotFound · ${person.name}`} description="This page is not in the event stream." noindex>
-  <Nav slot="nav" home={false} />
+<Base cast={cast} title={`EventNotFound · ${person.name}`} description="This page is not in the event stream." noindex>
+  <Nav slot="nav" cast={cast} home={false} />
   <section class="relative isolate flex min-h-[100svh] items-center overflow-hidden pt-[var(--nav-h)]">
     <div class="pointer-events-none absolute inset-0 -z-10" aria-hidden="true">
       <div class="absolute top-1/2 left-1/2 size-[40rem] -translate-x-1/2 -translate-y-1/2 rounded-full bg-accent/10 blur-[120px]"></div>
@@ -36,5 +38,5 @@ import { person } from '../site/data';
       </div>
     </div>
   </section>
-  <Footer slot="footer" />
+  <Footer slot="footer" cast={cast} />
 </Base>

package/routes/cast.json.ts

@@ -7,5 +7,11 @@ import { castJson } from '../machine/castJson';
 
 export const prerender = true;
 
+/** The portrait as an absolute https URL: the built local image, else the remote one. */
+const portrait = (): string | undefined => {
+    if (data.photo) return new URL(data.photo.src, data.config.site.url).toString();
+    return data.photoUrl;
+};
+
 export const GET: APIRoute = () =>
-    new Response(JSON.stringify(castJson(data), null, 2), { headers: { 'content-type': 'application/json; charset=utf-8' } });
+    new Response(JSON.stringify(castJson(data, portrait()), null, 2), { headers: { 'content-type': 'application/json; charset=utf-8' } });