@shivaedev/work-board 0.11.0 → 0.13.0

package/src/server/files/list.ts

@@ -0,0 +1,75 @@
+import { Effect, FileSystem, Option, Path, type PlatformError } from "effect";
+import { isMarkdown as markdown } from "#path/isMarkdown.ts";
+
+export interface MarkdownFile {
+	readonly modified: number;
+	readonly path: string;
+}
+
+export function isMarkdown(path: string): boolean {
+	return markdown(path);
+}
+
+export function within(realRoot: string, separator: string, real: string): boolean {
+	return real === realRoot || real.startsWith(`${realRoot}${separator}`);
+}
+
+function folderOf(path: string): string {
+	return path.slice(0, Math.max(0, path.lastIndexOf("/")));
+}
+
+export function byFolder(left: string, right: string): number {
+	return folderOf(left).localeCompare(folderOf(right)) || left.localeCompare(right);
+}
+
+type Listing = Effect.Effect<readonly MarkdownFile[], PlatformError.PlatformError>;
+
+export const scanMarkdown = Effect.fn("WorkBoard.scanMarkdown")(function* (root: string, realRoot: string) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const roots: Array<{ readonly real: string; readonly relative: string }> = [{ real: realRoot, relative: "" }];
+	function entry(relative: string, boundary: string, ancestors: ReadonlySet<string>, parent: string): Listing {
+		return Effect.gen(function* () {
+			const real = yield* Effect.option(fs.realPath(path.join(root, relative)));
+			if (Option.isNone(real)) {
+				return [];
+			}
+			const info = yield* Effect.option(fs.stat(real.value));
+			if (Option.isNone(info)) {
+				return [];
+			}
+			if (info.value.type === "Directory") {
+				return yield* directory(relative, real.value, boundary, ancestors, real.value !== path.join(parent, path.basename(relative)));
+			}
+			const modified = Option.match(info.value.mtime, { onNone: () => 0, onSome: (date) => date.getTime() });
+			return info.value.type === "File" && relative.endsWith(".md") && within(boundary, path.sep, real.value) ? [{ modified, path: relative }] : [];
+		});
+	}
+	function directory(relative: string, real: string, boundary: string, ancestors: ReadonlySet<string>, alias: boolean): Listing {
+		if (ancestors.has(real) || within(real, path.sep, realRoot)) {
+			return Effect.succeed([]);
+		}
+		const linked = !within(boundary, path.sep, real);
+		if (alias) {
+			roots.push({ real, relative });
+		}
+		return Effect.orElseSucceed(folder(relative, real, linked ? real : boundary, ancestors), () => []);
+	}
+	function folder(relative: string, real: string, boundary: string, ancestors: ReadonlySet<string>): Listing {
+		return Effect.gen(function* () {
+			const branch = new Set([...ancestors, real]);
+			const names = yield* fs.readDirectory(real);
+			const found = yield* Effect.forEach(
+				names.filter((name) => !name.startsWith(".") && name !== "node_modules"),
+				(name) => entry(relative === "" ? name : `${relative}/${name}`, boundary, branch, real),
+			);
+			return found.flat();
+		});
+	}
+	const files = yield* folder("", realRoot, realRoot, new Set());
+	return { files: files.toSorted((left, right) => byFolder(left.path, right.path)), roots };
+});
+
+export const listMarkdown = Effect.fn("WorkBoard.listMarkdown")(function* (root: string, realRoot: string) {
+	return (yield* scanMarkdown(root, realRoot)).files;
+});

package/src/server/files/update.ts

@@ -0,0 +1,52 @@
+import { Effect, FileSystem, Option } from "effect";
+import { attachmentType } from "#path/attachment.ts";
+import { byFolder, isMarkdown, listMarkdown, type MarkdownFile } from "./list.ts";
+import { markdownPath } from "./markdownPath.ts";
+
+export const updateFiles = Effect.fn("WorkBoard.updateFiles")(function* (
+	root: string,
+	realRoot: string,
+	previous: readonly MarkdownFile[],
+	paths: ReadonlySet<string> | undefined,
+) {
+	const fs = yield* FileSystem.FileSystem;
+	// Root disappearance must reach callers as a filesystem failure.
+	yield* fs.stat(realRoot);
+	if (
+		paths === undefined
+		|| [...paths].some(
+			(path) => (!isMarkdown(path) && attachmentType(path) === undefined) || previous.some((file) => file.path.startsWith(`${path}/`)),
+		)
+	) {
+		return yield* listMarkdown(root, realRoot);
+	}
+	const files = new Map(previous.map((file) => [file.path, file]));
+	for (const file of paths) {
+		if (!isMarkdown(file)) {
+			continue;
+		}
+		const found = yield* Effect.option(
+			Effect.gen(function* () {
+				const real = yield* markdownPath(root, realRoot, file);
+				if (!real) {
+					return undefined;
+				}
+				const info = yield* fs.stat(real);
+				if (info.type === "Directory") {
+					return "directory";
+				}
+				return info.type === "File"
+					? { modified: Option.match(info.mtime, { onNone: () => 0, onSome: (date) => date.getTime() }), path: file }
+					: undefined;
+			}),
+		);
+		files.delete(file);
+		if (Option.isSome(found) && found.value === "directory") {
+			return yield* listMarkdown(root, realRoot);
+		}
+		if (Option.isSome(found) && found.value && typeof found.value !== "string") {
+			files.set(file, found.value);
+		}
+	}
+	return [...files.values()].toSorted((left, right) => byFolder(left.path, right.path));
+});

package/src/server/files/watchDirectories.ts

@@ -0,0 +1,79 @@
+import { Deferred, Effect, FileSystem, Option, Path, Stream } from "effect";
+import { ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { attachmentType } from "#path/attachment.ts";
+import { isMarkdown, scanMarkdown } from "./list.ts";
+
+const SETTLE = "100 millis";
+
+export const watchDirectories = Effect.fn("WorkBoard.watchDirectories")(function* (
+	root: string,
+	realRoot: string,
+	stale: Effect.Effect<void>,
+	setWatching: (watching: boolean) => Effect.Effect<unknown>,
+	publish: (paths: readonly string[]) => Effect.Effect<unknown>,
+	observed: Effect.Effect<void> = Effect.void,
+) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const cycle = Effect.scoped(
+		Effect.gen(function* () {
+			const { roots } = yield* scanMarkdown(root, realRoot);
+			const topology = yield* Deferred.make<void>();
+			// Node's recursive watcher can miss replacement of directory symlinks.
+			const parents = yield* Effect.forEach(
+				roots.filter((folder) => folder.relative !== ""),
+				(folder) =>
+					Effect.map(fs.realPath(path.dirname(path.join(root, folder.relative))), (real) => ({ real, relative: path.dirname(folder.relative) })),
+			);
+			const watched = [...roots.map((folder) => ({ ...folder, recursive: true })), ...parents.map((folder) => ({ ...folder, recursive: false }))];
+			const streams = watched.map((folder) =>
+				fs.watch(folder.real, { recursive: folder.recursive }).pipe(
+					Stream.map((event) => {
+						const local = path.isAbsolute(event.path) ? path.relative(folder.real, event.path) : event.path;
+						return path.join(folder.relative, local).split(path.sep).join("/");
+					}),
+				),
+			);
+			const pending = new Set<string>();
+			const watch = Stream.mergeAll(streams, { concurrency: "unbounded" }).pipe(
+				Stream.tap((relative) => (isMarkdown(relative) || attachmentType(relative) !== undefined ? observed : Effect.void)),
+				Stream.tap((relative) =>
+					Effect.gen(function* () {
+						const info = yield* Effect.option(fs.stat(path.join(root, relative)));
+						const removedLink = roots.some((folder) => folder.relative === relative || folder.relative.startsWith(`${relative}/`));
+						if (Option.match(info, { onNone: () => removedLink, onSome: (value) => value.type === "Directory" })) {
+							yield* stale;
+							yield* Effect.forkScoped(Effect.delay(Deferred.succeed(topology, undefined), SETTLE));
+						}
+					}),
+				),
+				Stream.filter((relative) => isMarkdown(relative) || attachmentType(relative) !== undefined),
+				Stream.tap((relative) =>
+					Effect.sync(() => {
+						pending.add(relative);
+					}),
+				),
+				Stream.interruptWhen(Deferred.await(topology)),
+				Stream.debounce(SETTLE),
+				Stream.runForEach(() =>
+					Effect.suspend(() => {
+						const paths = [...pending];
+						pending.clear();
+						return publish(paths);
+					}),
+				),
+				Effect.andThen(
+					Effect.flatMap(Deferred.isDone(topology), (changed) =>
+						changed
+							? Effect.void
+							: Effect.fail(new ServiceUnavailable({ message: "The workspace watcher ended. Retrying the watch automatically." })),
+					),
+				),
+			);
+			yield* Effect.forkScoped(Effect.delay(setWatching(true), SETTLE));
+			yield* watch;
+			yield* setWatching(false);
+		}),
+	);
+	yield* Effect.forever(cycle);
+});

package/src/server/handoffs/Service.ts

@@ -0,0 +1,111 @@
+import { join } from "node:path";
+import { Clock, Effect, FileSystem, Path, Semaphore } from "effect";
+import { defineService } from "@shivaedev/effect-service/define-service.ts";
+import { Conflict, Forbidden, NotFound, PreconditionFailed, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import type { Handoff, HandoffInput } from "#browser/handoffs/schema.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { handoffFrom, handoffMarkdown, handoffPrompt, matchesHandoff } from "#server/handoffs/records.ts";
+import { handoffSource } from "#server/handoffs/source.ts";
+import { publish } from "#server/responses/publish.ts";
+import { revisionOf } from "#server/responses/records.ts";
+import { ResponseConfig } from "#server/responses/service.ts";
+
+export const HandoffsService = defineService({
+	id: "WorkBoard/HandoffsService",
+	initialize: Effect.gen(function* () {
+		return { fs: yield* FileSystem.FileSystem, lock: yield* Semaphore.make(1), options: yield* ResponseConfig };
+	}),
+	methods: ({ options, fs, lock }) => {
+		const snapshot = options.index.pipe(
+			rpcBoundary(ServiceUnavailable, {
+				message: "The workspace could not be indexed.",
+				unexpected: (message) => new ServiceUnavailable({ message }),
+			}),
+		);
+		const locate = handoffSource(options.root, options.changes.realRoot, snapshot, fs);
+		const read = Effect.fn("WorkBoard.read")(function* (item: string) {
+			const data = yield* snapshot;
+			const unknown = [...data.unavailable];
+			const records = data.documents.flatMap((document) => {
+				const record = handoffFrom(document, options.changes.realRoot);
+				if (
+					(record && data.model.ids.get(record.id)?.length !== 1)
+					|| (document.parsed.fields.kind === "handoff" && !record)
+					|| (document.file.startsWith("handoffs/") && document.parsed.diagnostics.some((problem) => problem.field === undefined))
+				) {
+					unknown.push(document.file);
+					return [];
+				}
+				return record?.handoff.item === item ? [record] : [];
+			});
+			return { records: records.sort((a, b) => b.handoff.preparedAt - a.handoff.preparedAt || a.id.localeCompare(b.id)), unknown };
+		});
+		const reconcile = Effect.fn("WorkBoard.reconcile")(function* (record: Handoff | undefined, input: HandoffInput) {
+			if (!record || record.file !== `handoffs/${input.id}.md` || !matchesHandoff(record, input) || revisionOf(record.context) !== input.revision) {
+				return yield* Effect.fail(new Conflict({ message: "This handoff identity moved, is duplicated or records different direction." }));
+			}
+			const path = yield* markdownPath(options.root, options.changes.realRoot, record.file);
+			if (!path) {
+				return yield* Effect.fail(new NotFound({ message: "The prepared handoff moved or disappeared." }));
+			}
+			const raw = yield* fs.readFileString(path).pipe(
+				rpcBoundary(ServiceUnavailable, {
+					message: "The handoff could not be reconciled.",
+					unexpected: (message) => new ServiceUnavailable({ message }),
+				}),
+			);
+			yield* publish(options.root, options.changes.realRoot, record.id, raw, "handoffs");
+			return record;
+		});
+
+		function prepare(input: HandoffInput) {
+			return lock.withPermit(
+				Effect.gen(function* () {
+					if (!options.enabled) {
+						return yield* Effect.fail(new Forbidden({ message: "Restart with --responses to enable local response/handoff writes." }));
+					}
+					const data = yield* snapshot;
+					const existing = data.model.ids.get(input.id);
+					if (existing?.length) {
+						const record = existing.length === 1 ? handoffFrom(existing[0], options.changes.realRoot) : undefined;
+						return yield* reconcile(record, input);
+					}
+					const current = yield* locate(input.item);
+					if (current.reviewedRevision !== input.revision || current.source !== input.source) {
+						return yield* Effect.fail(new PreconditionFailed({ message: "The source changed or moved. Keep your draft and review it again." }));
+					}
+					const file = `handoffs/${input.id}.md`;
+					const record: Handoff = {
+						context: current.context,
+						file,
+						handoff: {
+							constraints: input.constraints,
+							goal: input.goal,
+							item: input.item,
+							nextAction: input.nextAction,
+							preparedAt: yield* Clock.currentTimeMillis,
+							recipient: input.recipient,
+							reviewedRevision: input.revision,
+							source: input.source,
+							state: "requested",
+						},
+						id: input.id,
+						prompt: handoffPrompt(join(options.changes.realRoot, file)),
+					};
+					yield* publish(
+						options.root,
+						options.changes.realRoot,
+						record.id,
+						handoffMarkdown(record.id, record.handoff, record.context),
+						"handoffs",
+					).pipe(Effect.ensuring(options.changes.refresh ?? Effect.void));
+					return record;
+				}),
+			);
+		}
+		return { locate, prepare, read };
+	},
+	requires: [ResponseConfig, FileSystem.FileSystem, Path.Path],
+});
+export type HandoffsService = typeof HandoffsService.Identifier;

package/src/server/handoffs/records.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { Schema } from "effect";
+import { stringify } from "yaml";
+import type { Handoff, HandoffInput, HandoffRecord } from "#browser/handoffs/schema.ts";
+import { HandoffRecord as RecordSchema } from "#browser/handoffs/schema.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+
+export function handoffFrom(document: MetadataDocument | undefined, root: string): Handoff | undefined {
+	if (!document) {
+		return undefined;
+	}
+	const { id, kind, handoff } = document.parsed.fields;
+	return id && kind === "handoff" && handoff
+		? { context: document.parsed.body, file: document.file, handoff, id, prompt: handoffPrompt(join(root, document.file)) }
+		: undefined;
+}
+export function handoffPrompt(path: string): string {
+	return `Read the handoff at ${JSON.stringify(path)}. Record receipt by editing its handoff.state and add handoff.by/note; then follow its instructions.`;
+}
+export function handoffMarkdown(id: string, handoff: HandoffRecord, context: string): string {
+	return `---\n${stringify({ handoff: Schema.encodeSync(RecordSchema)(handoff), id, kind: "handoff" })}---\n${context}`;
+}
+export function matchesHandoff(record: Handoff, input: HandoffInput) {
+	const saved = record.handoff;
+	return (
+		saved.item === input.item
+		&& saved.source === input.source
+		&& saved.reviewedRevision === input.revision
+		&& saved.recipient === input.recipient
+		&& saved.goal === input.goal
+		&& saved.constraints === input.constraints
+		&& saved.nextAction === input.nextAction
+	);
+}

package/src/server/handoffs/source.ts

@@ -0,0 +1,40 @@
+import { Effect, type FileSystem } from "effect";
+import { BadRequest, NotFound, PreconditionFailed, ServiceUnavailable } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import type { HandoffPreview } from "#browser/handoffs/schema.ts";
+import type { ResponseRejection } from "#rpc/rejections.ts";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { questionId, revisionOf } from "#server/responses/records.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+
+export function handoffSource(root: string, realRoot: string, snapshot: Effect.Effect<Snapshot, ResponseRejection>, fs: FileSystem.FileSystem) {
+	return Effect.fn("WorkBoard.handoffSource")(function* (item: string) {
+		const data = yield* snapshot;
+		const matches = data.model.ids.get(item);
+		if (data.unavailable.length > 0 || matches?.length !== 1 || !matches[0]) {
+			return yield* Effect.fail(new NotFound({ message: "The item is missing, ambiguous or unavailable." }));
+		}
+		const file = matches[0].file;
+		const real = yield* markdownPath(root, realRoot, file);
+		if (!real) {
+			return yield* Effect.fail(new ServiceUnavailable({ message: "The handoff source could not be read." }));
+		}
+		const context = yield* fs.readFileString(real).pipe(
+			rpcBoundary(ServiceUnavailable, {
+				message: "The handoff source could not be read.",
+				unexpected: (message) => new ServiceUnavailable({ message }),
+			}),
+		);
+		const fields = metadataParse(context).fields;
+		if (fields.id !== item || fields.kind === "question" || fields.kind === "response" || fields.kind === "handoff") {
+			return yield* Effect.fail(new PreconditionFailed({ message: "Choose a current project item for this handoff." }));
+		}
+		if (new TextEncoder().encode(context).length > 256 * 1024) {
+			return yield* Effect.fail(new BadRequest({ message: "Handoff context is limited to 256 KiB. Choose a focused item." }));
+		}
+		const reviewedRevision = revisionOf(context);
+		const preview: HandoffPreview = { context, id: questionId(item, "handoff", reviewedRevision, file), item, reviewedRevision, source: file };
+		return preview;
+	});
+}

package/src/server/history/baseline.ts

@@ -0,0 +1,43 @@
+import { Option, Schema } from "effect";
+import { Baseline } from "#history/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { MAX_AGE, MAX_BYTES } from "./limits.ts";
+
+const JsonBaseline = Schema.fromJsonString(Baseline);
+function byteLength(text: string): number {
+	return new TextEncoder().encode(text).length;
+}
+
+export function readBaseline(raw: string | null, now: number) {
+	if (raw === null) {
+		return { baseline: undefined, discard: false, reason: "No previous snapshot. Start remembering changes to compare future source observations." };
+	}
+	if (byteLength(raw) > MAX_BYTES) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot exceeds 2 MiB; history is unavailable." };
+	}
+	const decoded = Schema.decodeUnknownOption(JsonBaseline, { onExcessProperty: "error" })(raw);
+	if (Option.isNone(decoded)) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot is invalid or unsupported; history is unavailable." };
+	}
+	const elapsed = now - Date.parse(decoded.value.recordedAt);
+	if (elapsed < 0) {
+		return { baseline: undefined, discard: true, reason: "Remembered observation is in the future; history is unavailable." };
+	}
+	if (elapsed >= MAX_AGE) {
+		return { baseline: undefined, discard: true, reason: "Remembered snapshot expired after 30 days; start again to establish a new baseline." };
+	}
+	return { baseline: decoded.value, discard: false, reason: "" };
+}
+
+export function observeBaseline(snapshot: Snapshot, now: number): string | undefined {
+	if (snapshot.unavailable.length > 0) {
+		return undefined;
+	}
+	const baseline: Baseline = {
+		documents: snapshot.documents.map((document) => ({ file: document.file, source: (document.parsed.raw ?? "") + document.parsed.body })),
+		recordedAt: new Date(now).toISOString(),
+		version: 1,
+	};
+	const raw = Schema.encodeSync(JsonBaseline)(baseline);
+	return byteLength(raw) <= MAX_BYTES ? raw : undefined;
+}

package/src/server/history/compare.ts

@@ -0,0 +1,54 @@
+import type { Baseline } from "#history/schema.ts";
+import { type HistoryDocument, historyDocuments, historyIdentities } from "./documents.ts";
+import { historyFields } from "./fields.ts";
+
+export interface SourceChange {
+	readonly after?: HistoryDocument;
+	readonly before?: HistoryDocument;
+	readonly kind: "added" | "removed" | "changed";
+	readonly reasons: readonly string[];
+}
+
+export function compareHistory(baseline: Baseline, current: Baseline) {
+	const before = historyDocuments(baseline);
+	const after = historyDocuments(current);
+	const oldIds = historyIdentities(before);
+	const newIds = historyIdentities(after);
+	const paired = new Set<HistoryDocument>();
+	const remaining = new Set(after);
+	const changes: SourceChange[] = [];
+	function pair(old: HistoryDocument, next: HistoryDocument) {
+		paired.add(old);
+		remaining.delete(next);
+		if (old.source !== next.source || old.file !== next.file) {
+			changes.push({ after: next, before: old, kind: "changed", reasons: historyFields(old, next) });
+		}
+	}
+	for (const [id, old] of oldIds) {
+		const next = newIds.get(id);
+		if (old && next) {
+			pair(old, next);
+		}
+	}
+	const byFile = new Map([...remaining].map((document) => [document.file, document]));
+	for (const old of before) {
+		if (paired.has(old)) {
+			continue;
+		}
+		const next = byFile.get(old.file);
+		if (next) {
+			pair(old, next);
+		} else {
+			changes.push({ before: old, kind: "removed", reasons: ["Source absent from the complete current observation"] });
+		}
+	}
+	for (const next of remaining) {
+		changes.push({ after: next, kind: "added", reasons: ["Source added since the remembered observation"] });
+	}
+	const issues = [
+		...[...oldIds].filter(([, document]) => !document).map(([id]) => `Duplicate ID ${id} in remembered sources; no identity winner selected.`),
+		...[...newIds].filter(([, document]) => !document).map(([id]) => `Duplicate ID ${id} in current sources; no identity winner selected.`),
+	];
+	changes.sort((a, b) => (a.after?.file ?? a.before?.file ?? "").localeCompare(b.after?.file ?? b.before?.file ?? "", "en"));
+	return { changes, issues, newIds };
+}

package/src/server/history/documents.ts

@@ -0,0 +1,21 @@
+import type { Baseline } from "#history/schema.ts";
+import { metadataParse, type ParsedMetadata } from "#server/metadata/parse.ts";
+
+export interface HistoryDocument {
+	readonly file: string;
+	readonly parsed: ParsedMetadata;
+	readonly source: string;
+}
+export function historyDocuments(baseline: Baseline): readonly HistoryDocument[] {
+	return baseline.documents.map((document) => ({ ...document, parsed: metadataParse(document.source) }));
+}
+export function historyIdentities(documents: readonly HistoryDocument[]): ReadonlyMap<string, HistoryDocument | undefined> {
+	const ids = new Map<string, HistoryDocument | undefined>();
+	for (const document of documents) {
+		const id = document.parsed.fields.id;
+		if (id) {
+			ids.set(id, ids.has(id) ? undefined : document);
+		}
+	}
+	return ids;
+}

package/src/server/history/html.ts

@@ -0,0 +1,20 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import { fileUrl } from "#files/url.ts";
+import type { Baseline } from "#history/schema.ts";
+import { compareHistory, type SourceChange } from "./compare.ts";
+
+function source(label: string, text: string, key: string): string {
+	return `<details data-key="${escapeHtml(key)}:${label}" data-history-source="${label.toLowerCase()}"><summary>${label} source (plain text)</summary><pre class="history-source">${escapeHtml(text)}</pre></details>`;
+}
+function changeHtml(change: SourceChange): string {
+	const file = change.after?.file ?? change.before?.file ?? "";
+	const key = change.before ? `before:${change.before.file}` : `added:${file}`;
+	return `<article class="history-change" data-key="${escapeHtml(key)}"><h2>${change.kind}: ${escapeHtml(file)}</h2>${change.before && change.after && change.before.file !== file ? `<p>Previously ${escapeHtml(change.before.file)}</p>` : ""}<ul>${change.reasons.map((reason) => `<li>${escapeHtml(reason)}</li>`).join("")}</ul>${change.after ? `<a href="${escapeHtml(fileUrl(change.after.file))}">Read current source</a>` : "<p>Removed source; no current document link.</p>"}${change.before ? source("Remembered", change.before.source, key) : ""}${change.after ? source("Current", change.after.source, key) : ""}</article>`;
+}
+export function historyHtml(before: Baseline, current: Baseline): string {
+	const result = compareHistory(before, current);
+	const counts = ["added", "removed", "changed"]
+		.map((kind) => `${result.changes.filter((change) => change.kind === kind).length} ${kind}`)
+		.join(" · ");
+	return `<p>Compared with your observation at <time>${escapeHtml(before.recordedAt)}</time>.</p><p role="status">${counts}</p>${result.changes.length === 0 ? "<p>No source changes since that observation.</p>" : ""}${result.issues.length > 0 ? `<aside aria-label="Identity limitations"><ul>${result.issues.map((issue) => `<li>${escapeHtml(issue)}</li>`).join("")}</ul><p>Ambiguous identities are compared by source path only.</p></aside>` : ""}${result.changes.map(changeHtml).join("")}`;
+}

package/src/server/history/response.ts

@@ -0,0 +1,37 @@
+import { escapeHtml } from "#browser/escapeHtml.ts";
+import type { HistoryOutput } from "#history/schema.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { observeBaseline, readBaseline } from "./baseline.ts";
+import { compareHistory } from "./compare.ts";
+import { historyHtml } from "./html.ts";
+
+export function historyResponse(raw: string | null, now: number, snapshot?: Snapshot): HistoryOutput {
+	const prior = readBaseline(raw, now);
+	const output: HistoryOutput = { discardBaseline: prior.discard, html: `<p>${escapeHtml(prior.reason)}</p>`, reason: prior.reason, snapshot: null };
+	if (snapshot === undefined) {
+		return output;
+	}
+	const currentRaw = observeBaseline(snapshot, now);
+	if (currentRaw === undefined) {
+		const reason =
+			snapshot.unavailable.length > 0
+				? "Current workspace observation is incomplete; no comparison or removals are inferred. Your valid remembered snapshot is preserved."
+				: "Complete current snapshot exceeds 2 MiB; no comparison or partial history is retained.";
+		return { ...output, html: `<p role="status">${escapeHtml(reason)}</p>`, reason };
+	}
+	const current = readBaseline(currentRaw, now).baseline;
+	const compared = prior.baseline && current ? compareHistory(prior.baseline, current) : undefined;
+	const comparison =
+		compared && prior.baseline
+			? {
+					changes: compared.changes.map(({ before, after, ...change }) => ({
+						...change,
+						after: after ? { file: after.file, source: after.source } : undefined,
+						before: before ? { file: before.file, source: before.source } : undefined,
+					})),
+					issues: compared.issues,
+					recordedAt: prior.baseline.recordedAt,
+				}
+			: undefined;
+	return { ...output, comparison, html: prior.baseline && current ? historyHtml(prior.baseline, current) : output.html, snapshot: currentRaw };
+}