@shivaedev/work-board 0.7.2 → 0.9.0

package/src/responses/templateNodes.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import type { RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import { Identity } from "#path/Identity.ts";
+
+const Id = Identity.check(Schema.isMaxLength(128));
+const PromptFields = Schema.Struct({ id: Id, request: Schema.optional(Identity), select: Schema.optional(Schema.Literals(["one", "many", "text"])) });
+const OptionFields = Schema.Struct({ id: Id });
+
+export function sliceNode(source: string, node: RootContent) {
+	return source.slice(node.position?.start.offset, node.position?.end.offset);
+}
+export function isContainer(node: RootContent): node is ContainerDirective {
+	return node.type === "containerDirective";
+}
+function hasControl(node: RootContent): boolean {
+	return (
+		((node.type === "containerDirective" || node.type === "leafDirective" || node.type === "textDirective")
+			&& ["question", "option"].includes(node.name))
+		|| ("children" in node && node.children.some(hasControl))
+	);
+}
+export function promptFrom(node: ContainerDirective, source: string) {
+	const attrs = Schema.decodeUnknownSync(PromptFields, { onExcessProperty: "error" })(node.attributes ?? {});
+	const options = node.children.filter((child) => isContainer(child) && child.name === "option");
+	const description = node.children.filter((child) => !(isContainer(child) && child.name === "option"));
+	if (
+		description.some(hasControl)
+		|| description.length === 0
+		|| options.length > 32
+		|| (attrs.select === "text" ? options.length > 0 : options.length === 0)
+	) {
+		throw new Error("A question needs Markdown context and 1–32 direct options (or select=text without options), without nested questions.");
+	}
+	const choices = options.map((option) => {
+		if (!isContainer(option) || option.children.some(hasControl) || option.children.length === 0) {
+			throw new Error("Options need Markdown descriptions and cannot nest response controls.");
+		}
+		const fields = Schema.decodeUnknownSync(OptionFields, { onExcessProperty: "error" })(option.attributes ?? {});
+		return { id: fields.id, source: option.children.map((child) => sliceNode(source, child)).join("\n\n") };
+	});
+	if (new Set(choices.map((option) => option.id)).size !== choices.length) {
+		throw new Error("Option IDs must be unique within each question.");
+	}
+	return {
+		prompt: {
+			id: attrs.id,
+			mode: attrs.select ?? "one",
+			options: choices,
+			source: description.map((child) => sliceNode(source, child)).join("\n\n"),
+		} satisfies Prompt,
+		request: attrs.request,
+	};
+}

package/src/responses/validateSupersedes.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { type DraftInput, type Question, ResponseFailed } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { questionFrom, responseFrom } from "./records.ts";
+
+export function validateSupersedes(input: DraftInput, question: Question, data: Snapshot) {
+	if (input.supersedes === undefined) {
+		return Effect.void;
+	}
+	const matches = data.model.ids.get(input.supersedes);
+	const previous = matches?.length === 1 && matches[0] ? responseFrom(matches[0]) : undefined;
+	const context = previous && data.model.ids.get(previous.response.question);
+	const old = context?.length === 1 && context[0] ? questionFrom(context[0]) : undefined;
+	return old
+		&& previous
+		&& previous.response.reviewedRevision === old.question.reviewedRevision
+		&& old.question.item === question.question.item
+		&& old.question.request === question.question.request
+		&& input.supersedes !== input.id
+		? Effect.void
+		: Effect.fail(
+				new ResponseFailed({ code: "Conflict", message: "Supersedes must identify one recorded response to this item's attention request." }),
+			);
+}

package/src/responses/validatedInput.ts

@@ -0,0 +1,45 @@
+import { answerBody } from "#browser/responses/answerBody.ts";
+import type { Prompt } from "#browser/responses/Prompt.ts";
+import type { DraftInput, PromptAnswer } from "#browser/responses/schema.ts";
+import { questionTemplate } from "./template.ts";
+
+function answerFor(prompt: Prompt, answer: PromptAnswer | undefined, required: boolean) {
+	if (!answer || answer.prompt !== prompt.id) {
+		throw new Error("Submit one answer per question, in template order.");
+	}
+	if (new Set(answer.selected).size !== answer.selected.length || (prompt.mode === "one" && answer.selected.length > 1)) {
+		throw new Error("The selected options do not match the question's selection mode.");
+	}
+	if (answer.selected.some((id) => !prompt.options.some((option) => option.id === id))) {
+		throw new Error("A selected option is not in the reviewed template.");
+	}
+	if (required && answer.selected.length === 0 && !answer.text.trim()) {
+		throw new Error("Answer every question with a selection or additional text, or use Clarify / Not now.");
+	}
+}
+export function validatedInput(input: DraftInput, context: string, request: string, file?: string): DraftInput {
+	const template = questionTemplate(context, request, file);
+	if (input.answers === undefined) {
+		if (template.prompts.length > 0 && input.type === "answer") {
+			throw new Error("This question packet requires answers for all prompts.");
+		}
+		if (!input.body.trim()) {
+			throw new Error("A response needs text or answers to the question packet.");
+		}
+		return input;
+	}
+	if (input.answers.length !== template.prompts.length || template.prompts.length === 0) {
+		throw new Error("The answer packet does not match the reviewed questions.");
+	}
+	template.prompts.forEach((prompt, index) => {
+		answerFor(prompt, input.answers?.[index], input.type === "answer");
+	});
+	if (input.type !== "answer" && !input.body.trim() && !input.answers.some((answer) => answer.text.trim())) {
+		throw new Error("Clarify / Not now needs explanatory text.");
+	}
+	const body = answerBody(template.prompts, input.answers, input.body);
+	if (body.length > 32_768) {
+		throw new Error("The complete recorded response exceeds 32768 characters. Shorten the response or split the source request.");
+	}
+	return { ...input, body };
+}

package/src/responses/waitFor.ts

@@ -0,0 +1,58 @@
+import * as Clock from "effect/Clock";
+import * as Effect from "effect/Effect";
+import type { RpcClientError } from "effect/unstable/rpc/RpcClientError";
+import { ResponseFailed, type WaitReading } from "#browser/responses/schema.ts";
+
+function resultFor(reading: WaitReading) {
+	if (reading.response) {
+		return Effect.succeed({ kind: "response", question: reading.question, response: reading.response } as const);
+	}
+	if (reading.expired) {
+		return Effect.fail(
+			new ResponseFailed({
+				code: "Unanswered",
+				message:
+					"The human left this unanswered for 48 hours. Check in with them; they may have forgotten or want to postpone. The request and late replies remain available.",
+			}),
+		);
+	}
+	return Effect.succeed(undefined);
+}
+
+function retryable(error: ResponseFailed | RpcClientError) {
+	return error._tag !== "ResponseFailed" || error.code === "Unavailable";
+}
+
+export const waitForResponse = Effect.fn("WorkBoard.waitForResponse")(function* (
+	read: () => Effect.Effect<WaitReading, ResponseFailed | RpcClientError>,
+	diagnostic: (text: string) => void,
+) {
+	let known: WaitReading | undefined;
+	const leaseEnd = (yield* Clock.currentTimeMillis) + 48 * 60 * 60 * 1000;
+	let unavailable = false;
+	while (true) {
+		const result = yield* read().pipe(Effect.result);
+		if (result._tag === "Failure") {
+			if (!retryable(result.failure)) {
+				return yield* Effect.fail(result.failure);
+			}
+			if ((yield* Clock.currentTimeMillis) >= (known?.question.question.deadline ?? leaseEnd)) {
+				return yield* Effect.fail(
+					new Error("The service is unavailable at the deadline; unanswered status could not be verified. Re-read this question when it returns."),
+				);
+			}
+			if (!unavailable) {
+				diagnostic("Local service unavailable; reconnecting to the same question.");
+			}
+			unavailable = true;
+			yield* Effect.sleep("2 seconds");
+			continue;
+		}
+		known = result.success;
+		unavailable = false;
+		const complete = yield* resultFor(known);
+		if (complete) {
+			return complete;
+		}
+	}
+});

package/src/rpc/contract.ts

@@ -4,6 +4,7 @@ import { contract } from "@shivaedev/effect-contract/contract.ts";
 import { LiveHint } from "@shivaedev/effect-contract/live.ts";
 import { query } from "@shivaedev/effect-contract/operation.ts";
 import { HistoryInput, HistoryOutput } from "#history/schema.ts";
+import { responseContract } from "#rpc/responseContract.ts";
 import { index, navigation, watcher, workspace } from "./keys.ts";
 import { pageKeys } from "./pageKeys.ts";
 
@@ -18,7 +19,7 @@ const PageUrl = Schema.String.check(
 			const path = new URL(value, "http://127.0.0.1").pathname;
 			return (
 				path === "/"
-				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start"].includes(path)
+				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start", "/_board/respond"].includes(path)
 				|| /^\/_board\/item\/[^/]+\/$/u.exec(path) !== null
 				|| /\.md$/iu.exec(path) !== null
 				|| "Expected a local reading URL"
@@ -59,4 +60,4 @@ const ReadWatcher = query("watcher", {
 });
 export const workContract = contract("work-board", { queries: [ReadPage, ReadNavigation, ReadSearch, ReadHistory, ReadWatcher] });
 export const Subscribe = Rpc.make("work-board.subscribe", { error: ReadFailed, stream: true, success: LiveHint });
-export const workRpcs = workContract.add(Subscribe);
+export const workRpcs = workContract.add(Subscribe).merge(responseContract);

package/src/rpc/responseContract.ts

@@ -0,0 +1,46 @@
+import { Schema } from "effect";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { command, query } from "@shivaedev/effect-contract/operation.ts";
+import {
+	DraftInput,
+	Question,
+	QuestionPreview,
+	Reading,
+	RecordedResponse,
+	ResponseFailed,
+	Revision,
+	WaitReading,
+} from "#browser/responses/schema.ts";
+import { index, workspace } from "#rpc/keys.ts";
+
+const locate = query("question", {
+	payload: { item: Schema.String, request: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: QuestionPreview,
+});
+const awaitResponse = query("awaitResponse", {
+	payload: { after: Schema.optional(Schema.String), question: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: WaitReading,
+});
+const read = query("responses", {
+	payload: { question: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: Reading,
+});
+const register = command("registerQuestion", {
+	invalidates: () => [workspace.list, index.list],
+	payload: { item: Schema.String, request: Schema.String, revision: Revision },
+	rejections: { ResponseFailed },
+	success: Question,
+});
+const respond = command("recordResponse", {
+	invalidates: () => [workspace.list, index.list],
+	payload: DraftInput,
+	rejections: { ResponseFailed },
+	success: RecordedResponse,
+});
+export const responseContract = contract("work-board", { commands: [register, respond], queries: [locate, read, awaitResponse] });

package/src/rpc/server.ts

@@ -6,6 +6,7 @@ import { MAX_BYTES } from "#history/limits.ts";
 import { historyResponse } from "#history/response.ts";
 import { HEADERS } from "#http/respond.ts";
 import { navHtml } from "#page/nav.ts";
+import type { responseService } from "#responses/service.ts";
 import { searchMatch } from "#search/match.ts";
 import type { Snapshot } from "#search/snapshot.ts";
 import { ReadFailed, workRpcs } from "./contract.ts";
@@ -16,10 +17,12 @@ export interface ServerOptions {
 	readonly home: string | undefined;
 	readonly index: Effect.Effect<Snapshot, unknown>;
 	readonly page: (url: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
+	readonly responses: Effect.Success<ReturnType<typeof responseService>>;
 }
 
-export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home, index, page }: ServerOptions) {
+export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home, index, page, responses }: ServerOptions) {
 	const handlers = workRpcs.toLayer({
+		"work-board.awaitResponse": responses.awaitResponse,
 		"work-board.history": ({ action, baseline }) =>
 			Effect.gen(function* () {
 				const now = yield* Clock.currentTimeMillis;
@@ -40,6 +43,10 @@ export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home,
 				}),
 				Effect.catch((error) => Effect.fail(error instanceof ReadFailed ? error : new ReadFailed({ operation: "page", status: 500 }))),
 			),
+		"work-board.question": ({ item, request }) => responses.locate(item, request),
+		"work-board.recordResponse": responses.record,
+		"work-board.registerQuestion": responses.register,
+		"work-board.responses": ({ question }) => responses.read(question),
 		"work-board.search": ({ query }) =>
 			Effect.map(index, (snapshot) => ({ ...searchMatch(snapshot.entries, query), unavailable: snapshot.unavailable })).pipe(
 				Effect.catch(() => Effect.fail(new ReadFailed({ operation: "search", status: 500 }))),

package/src/serve-cli.ts

@@ -0,0 +1,37 @@
+#!/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 { HOST, serveBoard } from "./serve.ts";
+
+const VERSION = "0.9.0";
+
+const serve = Effect.fn("WorkBoard.serve")(function* (input: {
+	readonly dir: string;
+	readonly port: number;
+	readonly responses: boolean;
+	readonly home: Option.Option<string>;
+}) {
+	const path = yield* Path.Path;
+	return yield* Layer.launch(
+		serveBoard({ home: Option.getOrUndefined(input.home), 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")),
+		home: Flag.string("home").pipe(Flag.optional, Flag.withDescription("The file shown as a board at /, relative to the folder")),
+		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 and response 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);
+}