@shivaedev/work-board 0.11.0 → 0.12.0

package/src/server/rpc/affected.ts

@@ -0,0 +1,88 @@
+import type { Key } from "@shivaedev/effect-contract/keys.ts";
+import { documents, identities, index, navigation } from "#rpc/keys.ts";
+import { referencesFrom } from "#server/metadata/backlinks.ts";
+import type { MetadataModel } from "#server/metadata/model.ts";
+import { referencesOf } from "#server/metadata/referencesOf.ts";
+import { malformedResponse } from "#server/responses/records.ts";
+
+function uncertain(previous: MetadataModel, current: MetadataModel, paths: readonly string[]) {
+	if (previous.unavailable.length > 0 || current.unavailable.length > 0) {
+		return true;
+	}
+	const before = new Map(previous.documents.map((doc) => [doc.file, doc.parsed]));
+	const after = new Map(current.documents.map((doc) => [doc.file, doc.parsed]));
+	const known = new Set([...before.keys(), ...after.keys()]);
+	if (paths.some((path) => !known.has(path))) {
+		return true;
+	}
+	const announced = new Set(paths);
+	return [...known].some((file) => {
+		const old = before.get(file);
+		const next = after.get(file);
+		return !announced.has(file) && (old?.body !== next?.body || old?.raw !== next?.raw || old?.bodyLine !== next?.bodyLine);
+	});
+}
+function connectIdentities(model: MetadataModel, connect: (from: string, to: string) => void) {
+	for (const duplicates of model.ids.values()) {
+		const first = duplicates[0];
+		if (first === undefined) {
+			continue;
+		}
+		for (const duplicate of duplicates.slice(1)) {
+			connect(first.file, duplicate.file);
+			connect(duplicate.file, first.file);
+		}
+	}
+}
+function linkedFiles(models: readonly MetadataModel[], paths: readonly string[]) {
+	const edges = new Map<string, Set<string>>();
+	function connect(from: string, to: string) {
+		const targets = edges.get(from) ?? new Set();
+		targets.add(to);
+		edges.set(from, targets);
+	}
+	for (const model of models) {
+		connectIdentities(model, connect);
+		const managed = model.documents.filter((document) => document.parsed.fields.attention?.some((request) => request.managed));
+		for (const document of model.documents) {
+			const uncertainReceipt = document.parsed.diagnostics.some(
+				(problem) => problem.field === "request_receipt" || problem.field === "requestReceipt",
+			);
+			const targets = [
+				...referencesFrom(document, model).flatMap((link) => (link.target === undefined ? [] : [link.target])),
+				...referencesOf(document).flatMap((reference) => (model.ids.get(reference.target.split("#")[0] ?? "") ?? []).map((target) => target.file)),
+				...(malformedResponse(document) || uncertainReceipt ? managed.map((source) => source.file) : []),
+			];
+			for (const target of targets) {
+				connect(document.file, target);
+				connect(target, document.file);
+			}
+		}
+	}
+	const files = new Set(paths);
+	for (const file of files) {
+		for (const linked of edges.get(file) ?? []) {
+			files.add(linked);
+		}
+	}
+	return files;
+}
+export function affected(previous: MetadataModel, current: MetadataModel, paths: readonly string[]): readonly Key[] | undefined {
+	if (uncertain(previous, current, paths)) {
+		return undefined;
+	}
+	const models = [previous, current];
+	const files = linkedFiles(models, paths);
+	const keys: Key[] = [index.list, navigation.list, ...[...files].map((file) => documents.item(file))];
+	for (const model of models) {
+		if (model.rootFile && files.has(model.rootFile)) {
+			keys.push(documents.item(""));
+		}
+		for (const document of model.documents) {
+			if (files.has(document.file) && document.parsed.fields.id) {
+				keys.push(identities.item(document.parsed.fields.id));
+			}
+		}
+	}
+	return keys;
+}

package/src/server/rpc/handlers.ts

@@ -0,0 +1,64 @@
+import { Clock, Effect, Layer, Ref, Stream } from "effect";
+import type { HttpServerResponse } from "effect/unstable/http";
+import { InternalServerError, NotFound } from "@shivaedev/platform/errors/taxonomy.ts";
+import { rpcBoundary } from "@shivaedev/platform/rpc-server/boundary.ts";
+import { requestTracingLayer } from "@shivaedev/platform/rpc-server/tracing.ts";
+import { workRpcs } from "#rpc/contract.ts";
+import { DocumentRejection, ResponseRejection } from "#rpc/rejections.ts";
+import { HandoffsService } from "#server/handoffs/Service.ts";
+import { historyResponse } from "#server/history/response.ts";
+import { navigationData } from "#server/navigation/model.ts";
+import { Responses } from "#server/responses/service.ts";
+import { searchMatch } from "#server/search/match.ts";
+import { hints } from "./hints.ts";
+import type { ServerOptions } from "./transport.ts";
+
+const readBoundary = rpcBoundary(InternalServerError, { unexpected: (message) => new InternalServerError({ message }) });
+const documentBoundary = rpcBoundary(DocumentRejection, { unexpected: (message) => new InternalServerError({ message }) });
+const responseBoundary = rpcBoundary(ResponseRejection, { unexpected: (message) => new InternalServerError({ message }) });
+
+function readablePage(response: HttpServerResponse.HttpServerResponse) {
+	if (response.status >= 500 || response.body._tag !== "Uint8Array") {
+		return Effect.fail(
+			new InternalServerError({
+				message: `Page response is unreadable (status ${response.status}, body ${response.body._tag}). Retry the page; if it still fails, restart Work Board.`,
+			}),
+		);
+	}
+	return Effect.succeed({ html: new TextDecoder().decode(response.body.body), status: response.status });
+}
+
+export const handlers = Effect.fn("WorkBoard.handlers")(function* ({ changes, document, home, index, page }: ServerOptions) {
+	const handoffs = yield* HandoffsService;
+	const responses = yield* Responses;
+	return workRpcs
+		.toLayer({
+			"work-board.awaitResponse": (input) => Effect.suspend(() => responses.awaitResponse(input)).pipe(responseBoundary),
+			"work-board.document": ({ url }) =>
+				Effect.suspend(() => (document ? document(url) : Effect.fail(new NotFound({ message: "The document is missing." })))).pipe(documentBoundary),
+			"work-board.handoffSource": ({ item }) => Effect.suspend(() => handoffs.locate(item)).pipe(responseBoundary),
+			"work-board.handoffs": ({ item }) => Effect.suspend(() => handoffs.read(item)).pipe(responseBoundary),
+			"work-board.history": ({ action, baseline }) =>
+				Effect.gen(function* () {
+					const now = yield* Clock.currentTimeMillis;
+					const snapshot = action === "check" ? undefined : yield* index;
+					return historyResponse(baseline, now, snapshot);
+				}).pipe(readBoundary),
+			"work-board.navigation": ({ current }) =>
+				Effect.gen(function* () {
+					return navigationData(yield* changes.files, current, home, yield* index);
+				}).pipe(readBoundary),
+			"work-board.page": ({ url }) => Effect.suspend(() => page(url)).pipe(Effect.flatMap(readablePage), readBoundary),
+			"work-board.prepareHandoff": (input) => Effect.suspend(() => handoffs.prepare(input)).pipe(responseBoundary),
+			"work-board.question": ({ item, request }) => Effect.suspend(() => responses.locate(item, request)).pipe(responseBoundary),
+			"work-board.recordResponse": (input) => Effect.suspend(() => responses.record(input)).pipe(responseBoundary),
+			"work-board.registerQuestion": (input) => Effect.suspend(() => responses.register(input)).pipe(responseBoundary),
+			"work-board.responses": ({ question }) => Effect.suspend(() => responses.read(question)).pipe(responseBoundary),
+			"work-board.search": ({ query }) =>
+				Effect.map(index, (snapshot) => ({ ...searchMatch(snapshot.entries, query), unavailable: snapshot.unavailable })).pipe(readBoundary),
+			"work-board.subscribe": () =>
+				hints(changes, index).pipe(Stream.catchCause((cause) => Stream.fromEffect(Effect.failCause(cause).pipe(readBoundary)))),
+			"work-board.watcher": () => Effect.map(Ref.get(changes.watching), (watching) => ({ watching })).pipe(readBoundary),
+		})
+		.pipe(Layer.provideMerge(requestTracingLayer()));
+});

package/src/server/rpc/hints.ts

@@ -0,0 +1,34 @@
+import { Effect, PubSub, Stream } from "effect";
+import type { LiveHint } from "@shivaedev/effect-contract/live.ts";
+import type { Change, Changes } from "#server/files/changes.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { affected } from "./affected.ts";
+
+export function hints(changes: Changes, index: Effect.Effect<Snapshot, unknown>) {
+	return Stream.unwrap(
+		Effect.gen(function* () {
+			const subscription = yield* PubSub.subscribe(changes.events);
+			let sequence = changes.sequence ? yield* changes.sequence : undefined;
+			let previous = yield* Effect.option(index);
+			function nextHint(change: Change) {
+				return Effect.gen(function* () {
+					const current = yield* Effect.option(index);
+					const contiguous = sequence !== undefined && change.sequence === sequence + 1;
+					sequence = change.sequence;
+					let hint: LiveHint = { _tag: "Resync" };
+					if (contiguous && change._tag === "Changed" && previous._tag === "Some" && current._tag === "Some") {
+						const keys = affected(previous.value.model, current.value.model, change.paths);
+						if (keys !== undefined) {
+							hint = { _tag: "Changed", keys };
+						}
+					}
+					previous = current;
+					return hint;
+				});
+			}
+
+			const changesStream = Stream.fromSubscription(subscription).pipe(Stream.mapEffect(nextHint));
+			return Stream.concat(Stream.succeed<LiveHint>({ _tag: "Resync" }), changesStream);
+		}),
+	);
+}

package/src/server/rpc/transport.ts

@@ -0,0 +1,34 @@
+import { Effect } from "effect";
+import { HttpIncomingMessage, HttpServerResponse } from "effect/unstable/http";
+import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
+import { localRpcGuard } from "@shivaedev/platform/rpc-server/local.ts";
+import type { Document } from "#browser/document/schema.ts";
+import { workRpcs } from "#rpc/contract.ts";
+import type { Changes } from "#server/files/changes.ts";
+import { MAX_BYTES } from "#server/history/limits.ts";
+import { HEADERS } from "#server/http/respond.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { handlers } from "./handlers.ts";
+
+export interface ServerOptions {
+	readonly changes: Changes;
+	readonly document?: (url: string) => Effect.Effect<Document, unknown>;
+	readonly home: string | undefined;
+	readonly index: Effect.Effect<Snapshot, unknown>;
+	readonly page: (url: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
+}
+
+export const server = Effect.fn("WorkBoard.server")(function* (options: ServerOptions) {
+	const rpcHandlers = yield* handlers(options);
+	const wire = RpcSerialization.ndjson;
+	const handler = yield* RpcServer.toHttpEffect(workRpcs).pipe(
+		Effect.provide(rpcHandlers),
+		Effect.provideService(RpcSerialization.RpcSerialization, wire),
+	);
+	return handler.pipe(
+		localRpcGuard,
+		Effect.provideService(RpcSerialization.RpcSerialization, wire),
+		Effect.provideService(HttpIncomingMessage.MaxBodySize, BigInt(4 * MAX_BYTES + 4096)),
+		Effect.map((response) => HttpServerResponse.setHeaders(response, HEADERS)),
+	);
+});

package/src/server/search/attentionEntries.ts

@@ -0,0 +1,22 @@
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import type { Entry } from "./entries.ts";
+
+export function attentionEntries(document: MetadataDocument, href: string): readonly Entry[] {
+	const requests = document.parsed.fields.attention ?? [];
+	return requests.flatMap((request, index) => {
+		if (requests.filter((other) => other.id === request.id).length !== 1) {
+			return [];
+		}
+		const line = document.parsed.lines[`attention.${index}`] ?? document.parsed.lines.attention;
+		return [
+			{
+				file: document.file,
+				href: `${href}#attention-request-${encodeURIComponent(request.id)}`,
+				kind: "passage",
+				...(line === undefined ? {} : { line }),
+				text: [request.reason, request.id, request.kind, request.state, ...request.responseFrom, ...request.unblocks].join(" "),
+				title: request.reason,
+			},
+		];
+	});
+}

package/src/server/search/entries.ts

@@ -0,0 +1,58 @@
+import { MarkdownAsync } from "react-markdown";
+import rehypeRaw from "rehype-raw";
+import remarkDirective from "remark-directive";
+import remarkGfm from "remark-gfm";
+import { fileUrl } from "#files/url.ts";
+import { callouts } from "#render/callouts.ts";
+import { documentHeadings } from "#render/documentHeadings.ts";
+import { visualDocuments } from "#render/visualDocuments.ts";
+import { boardOf } from "#server/render/board.ts";
+import { searchCollector } from "./collector.ts";
+import { linkCollector } from "./linkCollector.ts";
+
+export interface Entry {
+	readonly file: string;
+	readonly href: string;
+	readonly kind: "document" | "heading" | "passage";
+	readonly line?: number;
+	readonly text: string;
+	readonly title: string;
+}
+
+function fragmentLocation(source: string, fragment: string, bodyLine: number, seen: Map<string, number>): number | undefined {
+	const start = source.indexOf(fragment, seen.get(fragment) ?? 0);
+	if (start < 0) {
+		return undefined;
+	}
+	seen.set(fragment, start + fragment.length);
+	return bodyLine + source.slice(0, start).split("\n").length - 1;
+}
+
+export async function entriesOf(source: string, file: string, home: boolean, bodyLine = 1, links = new Set<string>()): Promise<readonly Entry[]> {
+	const headings = documentHeadings();
+	let fragmentLine: number | undefined = bodyLine;
+	let fragmentLength = 0;
+	const seenFragments = new Map<string, number>();
+	const { entries, plugin } = searchCollector(
+		file,
+		() => fragmentLine,
+		() => fragmentLength,
+	);
+	const board = home ? boardOf(source) : undefined;
+	const fragments = board
+		? [board.title, board.intro, ...board.sections.flatMap((section) => [section.heading, section.notes, ...section.items]), board.footer]
+		: [source];
+	for (const fragment of fragments) {
+		if (fragment) {
+			fragmentLength = fragment.split("\n").length;
+			fragmentLine = board ? fragmentLocation(source, fragment, bodyLine, seenFragments) : bodyLine;
+			await MarkdownAsync({
+				children: board?.definitions ? `${fragment}\n\n${board.definitions}` : fragment,
+				rehypePlugins: [rehypeRaw, headings.plugin, plugin, linkCollector(links)],
+				remarkPlugins: [remarkGfm, remarkDirective, visualDocuments, callouts],
+			});
+		}
+	}
+	const title = headings.entries.find((heading) => heading.depth === 1)?.title || file;
+	return [{ file, href: fileUrl(file), kind: "document", line: bodyLine, text: `${file} ${title}`, title }, ...entries];
+}

package/src/server/search/metadataEntries.ts

@@ -0,0 +1,44 @@
+import { fileUrl } from "#files/url.ts";
+import { identityUrl } from "#server/metadata/links.ts";
+import type { MetadataDocument, MetadataModel } from "#server/metadata/model.ts";
+import { attentionEntries } from "./attentionEntries.ts";
+import type { Entry } from "./entries.ts";
+
+function itemUrl(document: MetadataDocument, model: MetadataModel): string {
+	const id = document.parsed.fields.id;
+	return model.unavailable.length === 0 && id && model.ids.get(id)?.length === 1 ? identityUrl(id) : fileUrl(document.file);
+}
+export function metadataEntries(entries: readonly Entry[], documents: readonly MetadataDocument[], model: MetadataModel): readonly Entry[] {
+	const sources = new Map(documents.map((document) => [document.file, document]));
+	const enriched = entries.map((entry) => {
+		const document = sources.get(entry.file);
+		if (entry.kind !== "document" || !document) {
+			return entry;
+		}
+		const fields = document.parsed.fields;
+		return {
+			...entry,
+			href: itemUrl(document, model),
+			text: [entry.text, fields.id, fields.kind, fields.status, fields.owner, fields.nextAction].filter(Boolean).join(" "),
+		};
+	});
+	for (const document of documents) {
+		enriched.push(...attentionEntries(document, itemUrl(document, model)));
+		const criteria = document.parsed.fields.criteria ?? [];
+		for (const [index, criterion] of criteria.entries()) {
+			if (criteria.filter((item) => item.id === criterion.id).length !== 1) {
+				continue;
+			}
+			const line = document.parsed.lines[`criteria.${index}`] ?? document.parsed.lines.criteria;
+			enriched.push({
+				file: document.file,
+				href: `${itemUrl(document, model)}#criterion-${encodeURIComponent(criterion.id)}`,
+				kind: "passage",
+				...(line === undefined ? {} : { line }),
+				text: criterion.text,
+				title: criterion.text,
+			});
+		}
+	}
+	return enriched;
+}

package/src/server/search/readDocument.ts

@@ -0,0 +1,34 @@
+import { Effect, FileSystem } from "effect";
+import { markdownPath } from "#server/files/markdownPath.ts";
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import { metadataParse } from "#server/metadata/parse.ts";
+import { type Entry, entriesOf } from "./entries.ts";
+
+export interface IndexedDocument {
+	readonly document: MetadataDocument;
+	readonly entries: readonly Entry[];
+	readonly source: string;
+}
+
+export const readDocument = Effect.fn("WorkBoard.readDocument")(function* (
+	root: string,
+	realRoot: string,
+	file: string,
+	home: string | undefined,
+	modified: number,
+	previous?: IndexedDocument,
+) {
+	const fs = yield* FileSystem.FileSystem;
+	const real = yield* markdownPath(root, realRoot, file);
+	if (real === undefined) {
+		return undefined;
+	}
+	const source = yield* fs.readFileString(real);
+	if (previous?.source === source) {
+		return previous;
+	}
+	const parsed = metadataParse(source);
+	const links = new Set<string>();
+	const entries = yield* Effect.tryPromise(() => entriesOf(parsed.body, file, file === home, parsed.bodyLine, links));
+	return { document: { file, links: [...links], modified, parsed }, entries, source };
+});

package/src/server/search/snapshot.ts

@@ -0,0 +1,87 @@
+import { Effect, Option, Ref, Semaphore } from "effect";
+import type { Changes } from "#server/files/changes.ts";
+import { invalidationsSince } from "#server/files/invalidations.ts";
+import type { MarkdownFile } from "#server/files/list.ts";
+import type { MetadataDocument, metadataModel } from "#server/metadata/model.ts";
+import { updateModel } from "#server/metadata/updateModel.ts";
+import type { Entry } from "./entries.ts";
+import { type IndexedDocument, readDocument } from "./readDocument.ts";
+import { updateEntries } from "./updateEntries.ts";
+
+export interface Snapshot {
+	readonly documents: readonly MetadataDocument[];
+	readonly entries: readonly Entry[];
+	readonly maintainer?: string;
+	readonly model: ReturnType<typeof metadataModel>;
+	readonly modified: ReadonlyMap<string, number>;
+	readonly revision: number;
+	readonly unavailable: readonly string[];
+}
+
+function shouldRead(
+	file: MarkdownFile,
+	previous: IndexedDocument | undefined,
+	listed: ReadonlyMap<string, MarkdownFile>,
+	dirty: ReadonlySet<string> | undefined,
+) {
+	return (
+		!previous
+		|| dirty === undefined
+		|| listed.get(file.path)?.modified !== file.modified
+		|| [...dirty].some((path) => path === file.path || file.path.startsWith(`${path}/`))
+	);
+}
+
+export const searchSnapshot = Effect.fn("WorkBoard.searchSnapshot")(function* (
+	root: string,
+	home: string | undefined,
+	changes: Changes,
+	maintainer = "maintainer",
+) {
+	const cached = yield* Ref.make<Snapshot | undefined>(undefined);
+	const semaphore = yield* Semaphore.make(1);
+	let records = new Map<string, IndexedDocument>();
+	let listed = new Map<string, MarkdownFile>();
+	const enrich = updateEntries();
+	function find(file: MarkdownFile, dirty: ReadonlySet<string> | undefined) {
+		const previous = records.get(file.path);
+		return shouldRead(file, previous, listed, dirty)
+			? Effect.map(Effect.option(readDocument(root, changes.realRoot, file.path, home, file.modified, previous)), Option.getOrUndefined)
+			: Effect.succeed(previous);
+	}
+	const read = Effect.gen(function* () {
+		let revision = yield* changes.revision;
+		let files = yield* changes.files;
+		while ((yield* changes.revision) !== revision) {
+			revision = yield* changes.revision;
+			files = yield* changes.files;
+		}
+		const hit = yield* Ref.get(cached);
+		const watching = yield* Ref.get(changes.watching);
+		if (hit?.revision === revision && hit.unavailable.length === 0 && watching) {
+			return hit;
+		}
+		const dirty = hit && watching ? invalidationsSince(changes, hit.revision) : undefined;
+		const next = new Map<string, IndexedDocument>();
+		const documents: MetadataDocument[] = [];
+		const unavailable: string[] = [];
+		for (const file of files) {
+			const found = yield* find(file, dirty);
+			if (found) {
+				documents.push(found.document);
+				next.set(file.path, found);
+			} else {
+				unavailable.push(file.path);
+			}
+		}
+		const model = updateModel(hit?.model, documents, unavailable, home ?? files[0]?.path);
+		const enriched = enrich(next, model);
+		const modified = new Map(files.map((file) => [file.path, file.modified]));
+		const snapshot = { documents, entries: enriched, maintainer, model, modified, revision, unavailable };
+		records = next;
+		listed = new Map(files.map((file) => [file.path, file]));
+		yield* Ref.set(cached, snapshot);
+		return snapshot;
+	});
+	return semaphore.withPermit(read);
+});

package/src/server/search/updateEntries.ts

@@ -0,0 +1,34 @@
+import type { MetadataModel } from "#server/metadata/model.ts";
+import type { Entry } from "./entries.ts";
+import { metadataEntries } from "./metadataEntries.ts";
+import type { IndexedDocument } from "./readDocument.ts";
+
+export function updateEntries() {
+	let previous: MetadataModel | undefined;
+	let sources = new Map<string, IndexedDocument>();
+	let enriched = new Map<string, readonly Entry[]>();
+	return (records: ReadonlyMap<string, IndexedDocument>, model: MetadataModel): readonly Entry[] => {
+		const next = new Map<string, readonly Entry[]>();
+		for (const [file, record] of records) {
+			const id = record.document.parsed.fields.id;
+			const unique = id && model.ids.get(id)?.length === 1;
+			const wasUnique = id && previous?.ids.get(id)?.length === 1;
+			const complete = model.unavailable.length === 0;
+			const wasComplete = previous?.unavailable.length === 0;
+			const hit = enriched.get(file);
+			next.set(
+				file,
+				hit && sources.get(file) === record && unique === wasUnique && complete === wasComplete
+					? hit
+					: metadataEntries(record.entries, [record.document], model),
+			);
+		}
+		previous = model;
+		sources = new Map(records);
+		enriched = next;
+		return [
+			...[...records].flatMap(([file, record]) => next.get(file)?.slice(0, record.entries.length) ?? []),
+			...[...records].flatMap(([file, record]) => next.get(file)?.slice(record.entries.length) ?? []),
+		];
+	};
+}

package/src/server/serve-cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect, Layer, Option, Path } from "effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+import { DAEMON_PORT } from "#diagnostics/daemonContract.ts";
+import { HOST, serveBoard } from "./serve.ts";
+
+const VERSION = "0.12.0";
+
+const serve = Effect.fn("WorkBoard.serve")(function* (input: {
+	readonly dir: string;
+	readonly fleetPort: number;
+	readonly maintainer: string;
+	readonly port: number;
+	readonly responses: boolean;
+	readonly home: Option.Option<string>;
+}) {
+	const path = yield* Path.Path;
+	return yield* Layer.launch(
+		serveBoard({
+			fleetPort: input.fleetPort,
+			home: Option.getOrUndefined(input.home),
+			maintainer: input.maintainer,
+			port: input.port,
+			responses: input.responses,
+			root: path.resolve(input.dir),
+		}),
+	);
+});
+
+const workBoard = Command.make(
+	"work-board",
+	{
+		dir: Argument.directory("dir", { mustExist: true }).pipe(Argument.withDescription("The folder of markdown files to serve")),
+		fleetPort: Flag.integer("fleet-port").pipe(Flag.withDefault(DAEMON_PORT), Flag.withDescription("Fleet daemon port for Diagnostics at 127.0.0.1")),
+		home: Flag.string("home").pipe(Flag.optional, Flag.withDescription("The file shown as a board at /, relative to the folder")),
+		maintainer: Flag.string("maintainer").pipe(
+			Flag.withDefault("maintainer"),
+			Flag.withDescription("The response_from label whose questions appear in the Inbox"),
+		),
+		port: Flag.integer("port").pipe(Flag.withDefault(4747), Flag.withDescription(`The port to listen on at ${HOST}`)),
+		responses: Flag.boolean("responses").pipe(
+			Flag.withDefault(false),
+			Flag.withDescription("Explicitly enable local durable question, response and handoff writes (Linux)"),
+		),
+	},
+	serve,
+).pipe(Command.withDescription("Serve a folder of markdown files as a live page that updates in place when a file changes."));
+
+export function runServe() {
+	Command.run(workBoard, { version: VERSION }).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain);
+}

package/src/server/serve.ts

@@ -0,0 +1,19 @@
+import { createServer } from "node:http";
+import { NodeHttpServer } from "@effect/platform-node";
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type BoardOptions, boardLayer } from "./board.ts";
+
+export const HOST = "127.0.0.1";
+
+export interface ServeOptions extends BoardOptions {
+	readonly port: number;
+}
+
+export function listenOn(port: number) {
+	return NodeHttpServer.layer(createServer, { disablePreemptiveShutdown: true, host: HOST, port });
+}
+
+export function serveBoard(options: ServeOptions) {
+	return HttpRouter.serve(boardLayer(options), { disableLogger: true }).pipe(Layer.provideMerge(listenOn(options.port)));
+}

package/src/server/views/items.ts

@@ -0,0 +1,55 @@
+import type { MetadataDocument } from "#server/metadata/model.ts";
+import type { Snapshot } from "#server/search/snapshot.ts";
+import { fieldFilter, type State } from "./state.ts";
+
+export interface Item {
+	readonly document: MetadataDocument;
+	readonly id: string;
+	readonly title: string;
+}
+export function itemsOf(snapshot: Snapshot): readonly Item[] {
+	const titles = new Map(snapshot.entries.filter((entry) => entry.kind === "document").map((entry) => [entry.file, entry.title]));
+	return [...snapshot.model.ids].flatMap(([id, documents]) => {
+		const document = documents.length === 1 ? documents[0] : undefined;
+		return document ? [{ document, id, title: titles.get(document.file) ?? document.file }] : [];
+	});
+}
+function matches(item: Item, state: State): boolean {
+	const fields = item.document.parsed.fields;
+	if (state.owner && fieldFilter(fields.owner) !== state.owner) {
+		return false;
+	}
+	if (state.status && fieldFilter(fields.status) !== state.status) {
+		return false;
+	}
+	const text = [item.id, item.title, fields.kind, fields.status, fields.owner, fields.nextAction]
+		.filter(Boolean)
+		.join(" ")
+		.normalize("NFKC")
+		.toLowerCase();
+	return state.query
+		.normalize("NFKC")
+		.toLowerCase()
+		.split(/\s+/u)
+		.filter(Boolean)
+		.every((term) => text.includes(term));
+}
+function order(item: Item, sort: State["sort"]): string | undefined {
+	return sort === "title" ? item.title : item.document.parsed.fields[sort];
+}
+const collator = new Intl.Collator("en", { numeric: true, sensitivity: "base" });
+export function filterItems(items: readonly Item[], state: State): readonly Item[] {
+	return items
+		.filter((item) => matches(item, state))
+		.sort((a, b) => {
+			const left = order(a, state.sort);
+			const right = order(b, state.sort);
+			if (left === undefined) {
+				return right === undefined ? a.id.localeCompare(b.id) : 1;
+			}
+			if (right === undefined) {
+				return -1;
+			}
+			return collator.compare(left, right) || a.id.localeCompare(b.id);
+		});
+}