@shivaedev/work-board 0.7.1 → 0.8.0

package/src/responses/service.ts

@@ -0,0 +1,106 @@
+import { Clock, Effect, FileSystem, Semaphore } from "effect";
+import { type DraftInput, type Question, type RecordedResponse, ResponseFailed } from "#browser/responses/schema.ts";
+import type { Changes } from "#files/changes.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { awaitResponse } from "./await.ts";
+import { locate as locateQuestion } from "./locate.ts";
+import { publish } from "./publish.ts";
+import { readResponses } from "./read.ts";
+import { questionMarkdown, responseMarkdown } from "./records.ts";
+import { retryResponse } from "./retry.ts";
+
+export interface ResponseOptions {
+	readonly changes: Changes;
+	readonly enabled: boolean;
+	readonly index: Effect.Effect<Snapshot, unknown>;
+	readonly root: string;
+}
+function reject(code: ResponseFailed["code"], message: string) {
+	return Effect.fail(new ResponseFailed({ code, message }));
+}
+const HOURS_48 = 48 * 60 * 60 * 1000;
+export const responseService = Effect.fn("WorkBoard.responseService")(function* (options: ResponseOptions) {
+	const fs = yield* FileSystem.FileSystem;
+	const lock = yield* Semaphore.make(1);
+	const snapshot = options.index.pipe(Effect.catch(() => reject("Unavailable", "The workspace could not be indexed.")));
+	const enabled = options.enabled ? Effect.void : reject("Disabled", "Start with --responses to explicitly enable local question/response writes.");
+	const locate = locateQuestion(options.root, options.changes.realRoot, snapshot, fs);
+	const read = readResponses(snapshot);
+	function register(input: { readonly item: string; readonly request: string; readonly revision: string }) {
+		return lock.withPermit(
+			Effect.gen(function* () {
+				yield* enabled;
+				const preview = yield* locate(input.item, input.request);
+				if (preview.reviewedRevision !== input.revision) {
+					return yield* reject("Stale", "Source changed since review. Read it again before registering this question.");
+				}
+				const data = yield* snapshot;
+				const matches = data.model.ids.get(preview.id);
+				if (matches?.length) {
+					if (matches.length !== 1 || matches[0]?.file !== `responses/${preview.id}.md`) {
+						return yield* reject("Conflict", "The registered identity moved or is duplicated. Read the existing record instead of retrying a write.");
+					}
+					const saved = (yield* read(preview.id)).question;
+					yield* publish(options.root, options.changes.realRoot, saved.id, questionMarkdown(saved));
+					return saved;
+				}
+				const now = yield* Clock.currentTimeMillis;
+				const question: Question = {
+					context: preview.context,
+					id: preview.id,
+					question: {
+						deadline: now + HOURS_48,
+						item: preview.item,
+						reason: preview.reason,
+						registeredAt: now,
+						request: preview.request,
+						reviewedRevision: preview.reviewedRevision,
+						source: preview.source,
+					},
+				};
+				yield* publish(options.root, options.changes.realRoot, question.id, questionMarkdown(question)).pipe(
+					Effect.ensuring(options.changes.refresh ?? Effect.void),
+				);
+				return question;
+			}),
+		);
+	}
+	function record(input: DraftInput) {
+		return lock.withPermit(
+			Effect.gen(function* () {
+				yield* enabled;
+				const result = yield* read(input.question);
+				const existing = result.responses.find((candidate) => candidate.id === input.id);
+				if (existing) {
+					yield* retryResponse(existing, input, snapshot, options);
+					return existing;
+				}
+				const { question } = result;
+				const current = yield* locate(question.question.item, question.question.request);
+				if (current.reviewedRevision !== question.question.reviewedRevision || current.source !== question.question.source) {
+					return yield* reject("Stale", "Source changed or moved. Keep the draft and review the new revision before responding.");
+				}
+				const data = yield* snapshot;
+				if (data.model.ids.has(input.id)) {
+					return yield* reject("Conflict", "This response identity is already used.");
+				}
+				const response: RecordedResponse = {
+					body: input.body,
+					id: input.id,
+					response: {
+						author: input.author,
+						question: input.question,
+						recordedAt: result.responses.reduce((time, saved) => Math.max(time, saved.response.recordedAt + 1), yield* Clock.currentTimeMillis),
+						reviewedRevision: question.question.reviewedRevision,
+						type: input.type,
+					},
+				};
+				yield* publish(options.root, options.changes.realRoot, response.id, responseMarkdown(response)).pipe(
+					Effect.ensuring(options.changes.refresh ?? Effect.void),
+				);
+				return response;
+			}),
+		);
+	}
+	return { awaitResponse: awaitResponse(read), locate, read, record, register };
+});

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.8.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);
+}