@shivaedev/work-board 0.10.0 → 0.12.0

package/src/server/http/changesPage.ts

@@ -0,0 +1,15 @@
+import { Effect } from "effect";
+import type { Changes } from "#server/files/changes.ts";
+import { changesHtml } from "#server/history/html.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function changesPage(changes: Changes, home: string | undefined, index?: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.changesPage")(function* () {
+		const snapshot = index ? yield* index : undefined;
+		const nav = navHtml(yield* changes.files, "", home, snapshot);
+		return respond(shell("Changes", nav, changesHtml(), changes.realRoot, true, undefined, "changes", snapshot), "text/html");
+	});
+}

package/src/server/http/identity.ts

@@ -0,0 +1,71 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { fileUrl } from "#files/url.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import type { page } from "./page.ts";
+import { respond } from "./respond.ts";
+
+function requestedIdentity(pathname: string): string {
+	try {
+		return decodeURIComponent(pathname.slice("/_board/item/".length).replace(/\/$/u, ""));
+	} catch {
+		return "";
+	}
+}
+
+export function identity(
+	index: Effect.Success<ReturnType<typeof searchSnapshot>>,
+	pages: ReturnType<typeof page>,
+	changes: Changes,
+	home: string | undefined,
+) {
+	return Effect.fn("WorkBoard.identity")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const pathname = new URL(request.url, "http://127.0.0.1").pathname;
+		const id = requestedIdentity(pathname);
+		if (!pathname.endsWith("/") && /\.md$/iu.exec(id) !== null) {
+			return yield* pages(request);
+		}
+		const snapshot = yield* index;
+		const matches = snapshot.model.ids.get(id) ?? [];
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					`Item ${id}`,
+					"",
+					`<p class="empty">The workspace index is incomplete. Could not read ${escapeHtml(snapshot.unavailable.join(", "))}; item identity could not be validated. Retry when the files are readable.</p>`,
+					changes.realRoot,
+					false,
+				),
+				"text/html",
+				503,
+			);
+		}
+		if (matches.length === 1 && matches[0]) {
+			return yield* pages(request, matches[0].file, id);
+		}
+		const text =
+			matches.length > 0
+				? `The ID ${id} is duplicated. No document was selected.`
+				: `No item with ID ${id} is available. It may be missing, renamed, or invalid.`;
+		const choices = matches.map((document) => `<li><a href="${escapeHtml(fileUrl(document.file))}">${escapeHtml(document.file)}</a></li>`).join("");
+		const nav = navHtml(yield* changes.files, "", home, snapshot);
+		return respond(
+			shell(
+				`Item ${id}`,
+				nav,
+				`<p class="empty">${escapeHtml(text)}</p>${choices ? `<ul>${choices}</ul>` : ""}`,
+				changes.realRoot,
+				false,
+				undefined,
+				false,
+				snapshot,
+			),
+			"text/html",
+			matches.length > 0 ? 409 : 404,
+		);
+	});
+}

package/src/server/http/inbox.ts

@@ -0,0 +1,27 @@
+import { Clock, Effect } from "effect";
+import { inboxHtml } from "#server/attention/inboxHtml.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function inbox(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.inbox")(function* () {
+		const snapshot = yield* index;
+		return respond(
+			shell(
+				"Inbox",
+				navHtml(yield* changes.files, "", home, snapshot),
+				inboxHtml(snapshot, false, yield* Clock.currentTimeMillis),
+				changes.realRoot,
+				true,
+				undefined,
+				"inbox",
+				snapshot,
+			),
+			"text/html",
+			snapshot.unavailable.length > 0 ? 503 : 200,
+		);
+	});
+}

package/src/server/http/overview.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import { overviewHtml } from "#server/attention/overviewHtml.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function overview(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.overview")(function* () {
+		const snapshot = yield* index;
+		const nav = navHtml(yield* changes.files, "", home, snapshot);
+		return respond(
+			shell("Overview", nav, overviewHtml(snapshot), changes.realRoot, true, undefined, "overview", snapshot),
+			"text/html",
+			snapshot.unavailable.length > 0 ? 503 : 200,
+		);
+	});
+}

package/src/server/http/page.ts

@@ -0,0 +1,109 @@
+import { Effect, FileSystem, Option } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { authoredQuestion } from "#server/attention/inbox.ts";
+import { documentBody } from "#server/document/body.ts";
+import type { Changes } from "#server/files/changes.ts";
+import type { MarkdownFile } from "#server/files/list.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { metadataModel } from "#server/metadata/model.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { boardHtml } from "#server/page/boardHtml.ts";
+import { documentHtml } from "#server/page/documentHtml.ts";
+import { itemIntroduction } from "#server/page/itemIntroduction.ts";
+import { metadataHtml } from "#server/page/metadata.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import { startHtml } from "#server/page/startHtml.ts";
+import { boardOf } from "#server/render/board.ts";
+import { authoredQuestionHtml } from "#server/responses/authoredQuestionHtml.ts";
+import { readingActions } from "#server/responses/readingActions.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export interface PageOptions {
+	readonly home: string | undefined;
+	readonly root: string;
+	readonly writable?: boolean;
+}
+
+function requestedPath(url: string): string {
+	const pathname = new URL(url, "http://127.0.0.1").pathname.replace(/^\/+/u, "");
+	try {
+		return decodeURIComponent(pathname);
+	} catch {
+		return pathname;
+	}
+}
+
+function message(text: string): string {
+	return `<p class="empty">${escapeHtml(text)}</p>`;
+}
+
+export function page(options: PageOptions, changes: Changes, index: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	const body = Effect.fn("WorkBoard.body")(function* (file: MarkdownFile, expectedIdentity?: string) {
+		const fs = yield* FileSystem.FileSystem;
+		const real = yield* markdownPath(options.root, changes.realRoot, file.path);
+		if (real === undefined) {
+			return Option.none();
+		}
+		const source = yield* fs.readFileString(real);
+		const parsed = metadataParse(source);
+		let identity: string | undefined;
+		const snapshot = yield* index;
+		const model = metadataModel(
+			[...snapshot.documents.filter((document) => document.file !== file.path), { file: file.path, parsed }],
+			snapshot.unavailable,
+			options.home ?? (yield* changes.files)[0]?.path,
+		);
+		const metadata = metadataHtml(parsed, file.path, model, file.path === options.home);
+		if (snapshot.unavailable.length === 0 && parsed.fields.id && model.ids.get(parsed.fields.id)?.length === 1) {
+			identity = parsed.fields.id;
+		}
+		if (expectedIdentity && identity !== expectedIdentity) {
+			return Option.none();
+		}
+		const actions = yield* readingActions({ file: file.path, parsed }, source, options.writable === true, identity);
+		const prose = documentBody({ file: file.path, parsed });
+		const html =
+			file.path === options.home
+				? yield* boardHtml(boardOf(prose), file.path, file.modified, metadata, actions)
+				: yield* documentHtml(prose, file, metadata, itemIntroduction(parsed), actions);
+		const question = identity && authoredQuestion({ file: file.path, parsed });
+		const answer = question ? yield* authoredQuestionHtml({ file: file.path, parsed }, source, options.writable === true) : "";
+		return Option.some({ html: html + answer, identity });
+	});
+	return Effect.fn("WorkBoard.page")(function* (request: HttpServerRequest.HttpServerRequest, resolved?: string, expectedIdentity?: string) {
+		const files = yield* changes.files;
+		const requested = resolved ?? (requestedPath(request.url) || options.home || files[0]?.path || "");
+		const file = files.find((candidate) => candidate.path === requested);
+		const snapshot = yield* index;
+		const nav = navHtml(files, requested, options.home, snapshot);
+		function layout(content: string, identity?: string) {
+			return shell(requested, nav, content, changes.realRoot, requested === options.home, identity, false, snapshot);
+		}
+		function missing() {
+			return respond(
+				layout(
+					message(
+						expectedIdentity
+							? `No item with ID ${expectedIdentity} at ${requested}; its source identity changed or is invalid.`
+							: `No markdown file at ${requested || options.root}.`,
+					),
+				),
+				"text/html",
+				404,
+			);
+		}
+		if (files.length === 0 && requestedPath(request.url) === "" && resolved === undefined && expectedIdentity === undefined) {
+			return respond(layout(startHtml(true)), "text/html");
+		}
+		if (file === undefined) {
+			return missing();
+		}
+		return yield* body(file, expectedIdentity).pipe(
+			Effect.map(Option.match({ onNone: missing, onSome: (main) => respond(layout(main.html, main.identity), "text/html") })),
+			Effect.catch(() => Effect.succeed(respond(layout(message(`${file.path} could not be read.`)), "text/html", 500))),
+		);
+	});
+}

package/src/server/http/readPage.ts

@@ -0,0 +1,13 @@
+import type { Effect } from "effect";
+import { HttpServerRequest, type HttpServerResponse } from "effect/unstable/http";
+
+export function readPage<E, R>(
+	routes: Readonly<Record<string, (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>>>,
+	fallback: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>,
+) {
+	return (url: string) => {
+		const request = HttpServerRequest.fromWeb(new Request(`http://127.0.0.1${url}`));
+		const path = new URL(url, "http://127.0.0.1").pathname;
+		return (routes[path] ?? fallback)(request);
+	};
+}

package/src/server/http/respond.ts

@@ -0,0 +1,21 @@
+import { HttpServerResponse } from "effect/unstable/http";
+
+const POLICY = [
+	"default-src 'self'",
+	"script-src 'self' 'wasm-unsafe-eval'",
+	"style-src 'self' 'unsafe-inline'",
+	"img-src 'self' data: https:",
+	"object-src 'none'",
+	"form-action 'none'",
+	"frame-src 'none'",
+	"base-uri 'none'",
+	"frame-ancestors 'none'",
+].join("; ");
+
+export const HEADERS = { "cache-control": "no-store", "content-security-policy": POLICY, "x-content-type-options": "nosniff" };
+
+export function respond(body: string | Uint8Array, contentType: string, status = 200): HttpServerResponse.HttpServerResponse {
+	return typeof body === "string"
+		? HttpServerResponse.text(body, { contentType: `${contentType}; charset=utf-8`, headers: HEADERS, status })
+		: HttpServerResponse.uint8Array(body, { contentType, headers: HEADERS, status });
+}

package/src/server/http/start.ts

@@ -0,0 +1,27 @@
+import { Effect } from "effect";
+import type { Changes } from "#server/files/changes.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import { startHtml } from "#server/page/startHtml.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { respond } from "./respond.ts";
+
+export function start(changes: Changes, home: string | undefined, index?: Effect.Success<ReturnType<typeof searchSnapshot>>) {
+	return Effect.fn("WorkBoard.start")(function* () {
+		const files = yield* changes.files;
+		const snapshot = index ? yield* index : undefined;
+		return respond(
+			shell(
+				"Getting started",
+				navHtml(files, "", home, snapshot),
+				startHtml(files.length === 0),
+				changes.realRoot,
+				false,
+				undefined,
+				"start",
+				snapshot,
+			),
+			"text/html",
+		);
+	});
+}

package/src/server/http/work.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { navHtml } from "#server/page/nav.ts";
+import { shell } from "#server/page/shell.ts";
+import type { searchSnapshot } from "#server/search/snapshot.ts";
+import { stateOf } from "#server/views/state.ts";
+import { workHtml } from "#server/views/workHtml.ts";
+import { respond } from "./respond.ts";
+
+export function work(index: Effect.Success<ReturnType<typeof searchSnapshot>>, changes: Changes, home: string | undefined) {
+	return Effect.fn("WorkBoard.work")(function* (request: HttpServerRequest.HttpServerRequest) {
+		const snapshot = yield* index;
+		const nav = navHtml(yield* changes.files, "", home, snapshot);
+		if (snapshot.unavailable.length > 0) {
+			return respond(
+				shell(
+					"Work",
+					nav,
+					`<h1>Workspace incomplete</h1><p class="empty">Could not read ${escapeHtml(snapshot.unavailable.join(", "))}. Work identity and view counts cannot be validated. Read available source files or retry when the workspace is readable.</p>`,
+					changes.realRoot,
+					true,
+					undefined,
+					true,
+					snapshot,
+				),
+				"text/html",
+				503,
+			);
+		}
+		const result = yield* workHtml(snapshot, stateOf(request.url)).pipe(
+			Effect.catch(() =>
+				Effect.succeed({
+					html: '<h1>Work unavailable</h1><p class="empty">The selected source could not be rendered. Read its Markdown file or retry.</p>',
+					status: 500,
+				}),
+			),
+		);
+		return respond(shell("Work", nav, result.html, changes.realRoot, true, undefined, true, snapshot), "text/html", result.status);
+	});
+}

package/src/server/integration/attention.ts

@@ -0,0 +1,9 @@
+import { RequestReceipt as RequestReceiptSchema } from "#attention/RequestReceipt.ts";
+import { managedRequestReceipt } from "#server/attention/managedRequestReceipt.ts";
+
+export type RequestReceipt = typeof RequestReceiptSchema.Type;
+
+export const attention = {
+	managedRequestReceipt,
+	RequestReceipt: RequestReceiptSchema,
+} as const;

package/src/server/integration/board.ts

@@ -0,0 +1,36 @@
+import { type Changes as InternalChanges, watchChanges } from "#server/files/changes.ts";
+import { type MarkdownFile as InternalMarkdownFile, listMarkdown } from "#server/files/list.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import {
+	type MetadataDocument as InternalMetadataDocument,
+	type MetadataModel as InternalMetadataModel,
+	metadataModel,
+} from "#server/metadata/model.ts";
+import { type Diagnostic as InternalDiagnostic, type ParsedMetadata as InternalParsedMetadata, metadataParse } from "#server/metadata/parse.ts";
+import { type Snapshot as InternalSnapshot, searchSnapshot } from "#server/search/snapshot.ts";
+
+export type Changes = InternalChanges;
+export type MarkdownFile = InternalMarkdownFile;
+export type MetadataDocument = InternalMetadataDocument;
+export type MetadataModel = InternalMetadataModel;
+export type Diagnostic = InternalDiagnostic;
+export type ParsedMetadata = InternalParsedMetadata;
+export type Snapshot = InternalSnapshot;
+
+const snapshot: (
+	root: string,
+	home: string | undefined,
+	changes: Changes,
+	maintainer?: string,
+) => Effect.Effect<Effect.Effect<Snapshot, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>> = searchSnapshot;
+
+export const board = {
+	listMarkdown,
+	markdownPath,
+	metadataModel,
+	metadataParse,
+	searchSnapshot: snapshot,
+	watchChanges,
+} as const;
+
+import type { Effect, FileSystem, Path, PlatformError } from "effect";

package/src/server/integration/diagnostics.ts

@@ -0,0 +1,28 @@
+import { DAEMON_PORT, DAEMON_RPC_PATH, DiagnosticsContract } from "#diagnostics/daemonContract.ts";
+import { CapacityRejection as CapacityRejectionSchema, FLEET_HEALTH_NAME, FleetHealth as FleetHealthSchema } from "#diagnostics/health.ts";
+import type { SourceFailure as SourceFailureType } from "#diagnostics/source.ts";
+import { DiagnosticsSources, diagnostics as readDiagnostics, SourceFailure as SourceFailureClass } from "#diagnostics/source.ts";
+import { codexLimits } from "#server/diagnostics/codexLimits.ts";
+import { codexRateLimits } from "#server/diagnostics/codexRateLimits.ts";
+import { fleetHealth } from "#server/diagnostics/fleetHealth.ts";
+import { githubLimits } from "#server/diagnostics/githubLimits.ts";
+
+export type CapacityRejection = typeof CapacityRejectionSchema.Type;
+export type FleetHealth = typeof FleetHealthSchema.Type;
+export type SourceFailure = SourceFailureType;
+
+export const diagnostics = {
+	CapacityRejection: CapacityRejectionSchema,
+	codexLimits,
+	codexRateLimits,
+	DAEMON_PORT,
+	DAEMON_RPC_PATH,
+	DiagnosticsContract,
+	DiagnosticsSources,
+	diagnostics: readDiagnostics,
+	FLEET_HEALTH_NAME,
+	FleetHealth: FleetHealthSchema,
+	fleetHealth,
+	githubLimits,
+	SourceFailure: SourceFailureClass,
+} as const;

package/src/server/integration/publication.ts

@@ -0,0 +1,6 @@
+import { directoryPath, validateDirectory } from "#server/responses/publicationDirectory.ts";
+
+export const publication = {
+	directoryPath,
+	validateDirectory,
+} as const;

package/src/server/integration/responses.ts

@@ -0,0 +1,36 @@
+import {
+	DraftInput as DraftInputSchema,
+	Question as QuestionSchema,
+	Reading as ReadingSchema,
+	RecordedResponse as RecordedResponseSchema,
+} from "#browser/responses/schema.ts";
+import { currentResponses } from "#responses/current.ts";
+import { makeResponse } from "#server/responses/make.ts";
+import { publish } from "#server/responses/publish.ts";
+import { readResponses } from "#server/responses/read.ts";
+import { questionFrom, questionId, questionMarkdown, responseMarkdown, revisionOf } from "#server/responses/records.ts";
+import { type ResponseOptions as InternalResponseOptions, ResponseConfig, Responses } from "#server/responses/service.ts";
+
+export type ResponseOptions = InternalResponseOptions;
+export type DraftInput = typeof DraftInputSchema.Type;
+export type Question = typeof QuestionSchema.Type;
+export type Reading = typeof ReadingSchema.Type;
+export type RecordedResponse = typeof RecordedResponseSchema.Type;
+
+export const responses = {
+	currentResponses,
+	DraftInput: DraftInputSchema,
+	makeResponse,
+	publish,
+	Question: QuestionSchema,
+	questionFrom,
+	questionId,
+	questionMarkdown,
+	Reading: ReadingSchema,
+	RecordedResponse: RecordedResponseSchema,
+	ResponseConfig,
+	Responses,
+	readResponses,
+	responseMarkdown,
+	revisionOf,
+} as const;

package/src/server/metadata/backlinks.ts

@@ -0,0 +1,52 @@
+import type { MetadataDocument, MetadataModel } from "./model.ts";
+import { referenceFile, sourceFile } from "./sourceLinks.ts";
+
+export interface Backlink {
+	readonly file: string;
+	readonly kind: string;
+	readonly line?: number;
+}
+
+export function referencesFrom(document: MetadataDocument, model: MetadataModel) {
+	const { fields, lines } = document.parsed;
+	return [
+		...(fields.handoff ? [{ kind: "agent handoff", line: lines.handoff, target: referenceFile(fields.handoff.item, model) }] : []),
+		...(fields.question ? [{ kind: "reviewed question", line: lines.question, target: referenceFile(fields.question.item, model) }] : []),
+		...(fields.response ? [{ kind: "recorded response", line: lines.response, target: referenceFile(fields.response.question, model) }] : []),
+		...(fields.response?.supersedes
+			? [{ kind: "superseding response", line: lines.response, target: referenceFile(fields.response.supersedes, model) }]
+			: []),
+		...(fields.attention?.flatMap((request, index) =>
+			request.unblocks.map((target, targetIndex) => ({
+				kind: "attention target",
+				line: lines[`attention.${index}.unblocks.${targetIndex}`],
+				target: referenceFile(target, model),
+			})),
+		) ?? []),
+		...(fields.relationships?.map((link, index) => ({
+			kind: link.kind,
+			line: lines[`relationships.${index}.target`],
+			target: referenceFile(link.target, model),
+		})) ?? []),
+		...(fields.items?.map((item, index) => ({ kind: "board member", line: lines[`items.${index}`], target: referenceFile(item, model) })) ?? []),
+		...(fields.evidence?.flatMap((evidence, index) => [
+			{ kind: "evidence source", line: lines[`evidence.${index}.source`], target: sourceFile(evidence.source, document.file, model) },
+			{
+				kind: "criterion evidence",
+				line: lines[`evidence.${index}.criterion`],
+				target: evidence.criterion ? referenceFile(evidence.criterion, model) : undefined,
+			},
+		]) ?? []),
+		...(document.links?.map((link) => ({ kind: "Markdown link", line: undefined, target: sourceFile(link, document.file, model) })) ?? []),
+	];
+}
+
+export function backlinksOf(file: string, model: MetadataModel): readonly Backlink[] {
+	return model.documents.flatMap((document) =>
+		document.file === file
+			? []
+			: referencesFrom(document, model)
+					.filter((reference) => reference.target === file)
+					.map((reference) => ({ file: document.file, kind: reference.kind, ...(reference.line === undefined ? {} : { line: reference.line }) })),
+	);
+}

package/src/server/metadata/fields.ts

@@ -0,0 +1,29 @@
+import { Option, Schema } from "effect";
+import { Metadata } from "#metadata/schema.ts";
+import type { Diagnostic } from "./parse.ts";
+
+const schemas: ReadonlyMap<string, Schema.ConstraintDecoder<unknown, never>> = new Map(Object.entries(Metadata.to.fields));
+const sourceKeys = new Map([
+	["next_action", "nextAction"],
+	["request_receipt", "requestReceipt"],
+]);
+
+export function metadataFields(data: object, lines: Readonly<Record<string, number>>) {
+	const fields: Record<string, unknown> = {};
+	const diagnostics: Diagnostic[] = [];
+	for (const [field, value] of Object.entries(data)) {
+		const key = sourceKeys.get(field) ?? field;
+		const schema = field === "nextAction" || field === "requestReceipt" ? undefined : schemas.get(key);
+		if (!schema) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Unknown field ${field}; kept in the original frontmatter.` });
+			continue;
+		}
+		const decoded = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(value);
+		if (Option.isNone(decoded)) {
+			diagnostics.push({ field, line: lines[field] ?? 2, message: `Invalid ${field}; kept in the original frontmatter and not interpreted.` });
+		} else {
+			fields[key] = decoded.value;
+		}
+	}
+	return { diagnostics, fields: Schema.decodeUnknownSync(Schema.toType(Metadata))(fields) };
+}

package/src/server/metadata/model.ts

@@ -0,0 +1,17 @@
+import type { MetadataDocument as PublicMetadataDocument, MetadataModel as PublicMetadataModel } from "#integration/metadata.ts";
+import { metadataProblems } from "./problems.ts";
+
+export type MetadataDocument = PublicMetadataDocument;
+export type MetadataModel = PublicMetadataModel;
+
+export function metadataModel(documents: readonly MetadataDocument[], unavailable: readonly string[] = [], rootFile?: string): MetadataModel {
+	const ids = new Map<string, MetadataDocument[]>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, [...(ids.get(id) ?? []), document]);
+		}
+	}
+	const diagnostics = new Map(documents.map((document) => [document.file, metadataProblems(document, ids, unavailable)]));
+	return { diagnostics, documents, ids, rootFile, unavailable };
+}

package/src/server/metadata/parse.ts

@@ -0,0 +1,51 @@
+import { LineCounter, parseDocument } from "yaml";
+import type { Diagnostic as PublicDiagnostic, ParsedMetadata as PublicParsedMetadata } from "#integration/metadata.ts";
+import { metadataFields } from "./fields.ts";
+import { metadataLocations } from "./locations.ts";
+
+export type Diagnostic = PublicDiagnostic;
+export type ParsedMetadata = PublicParsedMetadata;
+
+export function metadataParse(source: string): ParsedMetadata {
+	const plain: ParsedMetadata = { body: source, bodyLine: 1, diagnostics: [], fields: {}, lines: {} };
+	const opening = /^\uFEFF?---[ \t]*\r?\n/u.exec(source);
+	if (!opening) {
+		return plain;
+	}
+	const remainder = source.slice(opening[0].length);
+	const closing = /^---[ \t]*\r?$/mu.exec(remainder);
+	if (!closing) {
+		return { ...plain, diagnostics: [{ line: 1, message: "Unterminated frontmatter; the original Markdown is shown." }] };
+	}
+	let end = opening[0].length + closing.index + closing[0].length;
+	if (source[end] === "\n") {
+		end += 1;
+	}
+	const raw = source.slice(0, end);
+	const body = source.slice(end);
+	const bodyLine = raw.split("\n").length;
+	const counter = new LineCounter();
+	const doc = parseDocument(remainder.slice(0, closing.index), { lineCounter: counter });
+	const lines = metadataLocations(doc.contents, counter);
+	const diagnostics: Diagnostic[] = [...doc.errors, ...doc.warnings].map((error) => ({
+		line: (error.linePos?.[0].line ?? 1) + 1,
+		message: error.message,
+	}));
+	const result = { body, bodyLine, diagnostics, fields: {}, lines, raw };
+	if (doc.errors.length > 0 || doc.warnings.length > 0) {
+		return result;
+	}
+	let data: unknown;
+	try {
+		data = doc.toJS({ maxAliasCount: 50 });
+	} catch {
+		return { ...result, diagnostics: [...diagnostics, { line: 2, message: "Frontmatter aliases could not be expanded safely." }] };
+	}
+	if (data === null) {
+		return result;
+	}
+	if (typeof data !== "object" || Array.isArray(data)) {
+		return { ...plain, diagnostics: [{ line: 2, message: "Frontmatter must be a mapping; the original Markdown is shown." }] };
+	}
+	return { ...result, ...metadataFields(data, lines) };
+}