konpeki 0.1.0 → 0.2.0

package/runtime/konpeki.mjs

@@ -1,33 +1,14 @@
 #!/usr/bin/env node
-import { createHash, randomBytes } from "node:crypto";
-import { access, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createServer } from "vite";
-import { tmpdir } from "node:os";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import "@xmldom/xmldom";
+import lockfile from "proper-lockfile";
 //#region composition/types.ts
-var compositionSchema = "konpeki-composition/v18";
-var legacyCompositionSchemas = [
-	"konpeki-composition/v1",
-	"konpeki-composition/v2",
-	"konpeki-composition/v3",
-	"konpeki-composition/v4",
-	"konpeki-composition/v5",
-	"konpeki-composition/v6",
-	"konpeki-composition/v7",
-	"konpeki-composition/v8",
-	"konpeki-composition/v9",
-	"konpeki-composition/v10",
-	"konpeki-composition/v11",
-	"konpeki-composition/v12",
-	"konpeki-composition/v13",
-	"konpeki-composition/v14",
-	"konpeki-composition/v15",
-	"konpeki-composition/v16",
-	"konpeki-composition/v17"
-];
+var compositionSchema = "konpeki-composition/v1";
 var canvasSize = {
 	width: 1920,
 	height: 1080
@@ -341,17 +322,6 @@ var chartTemplates = Object.keys({
 	}
 });
 Array.from(new Set(Object.values(diagramDefinitions).map((definition) => definition.category)));
-function migrateLegacyDiagramType(type, layout) {
-	if (typeof type !== "string" || typeof layout !== "string") return void 0;
-	return {
-		"process/linear": "process",
-		"process/branching": "flowchart",
-		"process/cyclical": "loop-flywheel",
-		"system/layered": "layer-stack",
-		"system/request-flow": "sequence",
-		"system/hub-and-spoke": "architecture"
-	}[`${type}/${layout}`];
-}
 //#endregion
 //#region composition/theme-tokens.ts
 /** Explicit opt-in bindings. Literal SVG attributes always remain fixed. */
@@ -737,7 +707,7 @@ var components = componentKinds.map((kind) => {
 });
 var schema = {
 	$schema: "https://json-schema.org/draft/2020-12/schema",
-	$id: "https://vcfgdev.github.io/konpeki/composition/v18/schema.json",
+	$id: "https://vcfgdev.github.io/konpeki/composition/v1/schema.json",
 	title: compositionSchema,
 	...object({
 		schema: { const: compositionSchema },
@@ -928,388 +898,15 @@ var structural = new Ajv2020({
 	allErrors: true,
 	strict: false
 }).compile(schema);
-function migratePreV5Document(input) {
-	const slide = input.slide;
-	const components = Array.isArray(slide?.components) ? slide.components.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const component = value;
-		if (component.kind !== "callout" && component.kind !== "comparison" && component.kind !== "text-block") return component;
-		const previous = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-		const common = Object.fromEntries([
-			"alignment",
-			"border",
-			"titleStyle",
-			"rule"
-		].flatMap((key) => key in previous ? [[key, previous[key]]] : []));
-		const appearance = component.kind === "callout" ? {
-			...common,
-			layout: "single",
-			orientation: "horizontal",
-			purpose: "emphasis",
-			treatment: "strong"
-		} : component.kind === "comparison" ? {
-			...common,
-			layout: "two-column",
-			orientation: "horizontal",
-			purpose: "comparison",
-			treatment: "plain"
-		} : {
-			...previous,
-			purpose: previous.purpose ?? "narrative",
-			treatment: previous.treatment ?? "plain"
-		};
-		return {
-			...component,
-			kind: "text-block",
-			appearance
-		};
-	}) : slide?.components;
-	return {
-		...Object.fromEntries(Object.entries(input).filter(([key]) => key !== "target" && key !== "slide")),
-		schema: "konpeki-composition/v5",
-		...slide ? { slides: [{
-			...slide,
-			name: "Slide 01",
-			components
-		}] } : {}
-	};
-}
-function migrateV5Document(input) {
-	const slides = Array.isArray(input.slides) ? input.slides.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const slide = value;
-		const previousComponents = Array.isArray(slide.components) ? slide.components : [];
-		const pageNumber = previousComponents.find((component) => component.kind === "page-number");
-		const pageAppearance = pageNumber?.appearance && typeof pageNumber.appearance === "object" ? pageNumber.appearance : {};
-		const removedIds = new Set(previousComponents.filter((component) => component.kind === "page-number").map((component) => String(component.id)));
-		const removedSlots = new Set(previousComponents.filter((component) => component.kind === "page-number").flatMap((component) => Array.isArray(component.slotIds) ? component.slotIds.map(String) : []));
-		const components = previousComponents.flatMap((component) => {
-			const appearance = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-			if (component.kind === "page-number") return [];
-			if (component.kind === "evidence") return [{
-				...component,
-				kind: "visual"
-			}];
-			if (component.kind === "process") return [{
-				...component,
-				kind: "diagram",
-				appearance: {
-					...appearance,
-					type: "process"
-				}
-			}];
-			if (component.kind === "system-map") return [{
-				...component,
-				kind: "diagram",
-				appearance: {
-					...appearance,
-					type: "system"
-				}
-			}];
-			return [component];
-		});
-		const componentIds = new Set(components.map((component) => String(component.id)));
-		const groups = Array.isArray(slide.groups) ? slide.groups.map((group) => ({
-			...group,
-			childIds: Array.isArray(group.childIds) ? group.childIds.filter((id) => !removedIds.has(String(id))) : group.childIds
-		})).filter((group) => !Array.isArray(group.childIds) || group.childIds.length > 0) : slide.groups;
-		const groupIds = new Set(Array.isArray(groups) ? groups.map((group) => String(group.id)) : []);
-		const contentSlots = Array.isArray(slide.contentSlots) ? slide.contentSlots.filter((slot) => !removedSlots.has(String(slot.id))).map((slot) => {
-			if (!Array.isArray(slot.targets)) return slot;
-			const targets = slot.targets.filter((target) => !removedIds.has(String(target)) && !removedSlots.has(String(target)));
-			return {
-				...slot,
-				targets: targets.length ? targets : [String(components[0]?.id ?? "")]
-			};
-		}) : slide.contentSlots;
-		return {
-			...slide,
-			pageNumber: {
-				style: pageNumber ? pageAppearance.style ?? "01" : "none",
-				color: pageAppearance.color ?? "muted"
-			},
-			components,
-			contentSlots,
-			groups,
-			readingOrder: Array.isArray(slide.readingOrder) ? slide.readingOrder.filter((entry) => entry.kind === "group" ? groupIds.has(String(entry.id)) : componentIds.has(String(entry.id))) : slide.readingOrder,
-			paintOrder: Array.isArray(slide.paintOrder) ? slide.paintOrder.filter((id) => !removedIds.has(String(id))) : slide.paintOrder,
-			relationships: Array.isArray(slide.relationships) ? slide.relationships.filter((relationship) => {
-				const from = relationship.from;
-				const to = relationship.to;
-				return !removedIds.has(String(from?.nodeId)) && !removedIds.has(String(to?.nodeId));
-			}) : slide.relationships
-		};
-	}) : input.slides;
-	return {
-		...input,
-		schema: compositionSchema,
-		slides
-	};
-}
-function migrateV7Document(input) {
-	const slides = Array.isArray(input.slides) ? input.slides.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const slide = value;
-		const components = Array.isArray(slide.components) ? slide.components.map((value) => {
-			if (!value || typeof value !== "object") return value;
-			const component = value;
-			const appearance = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-			if (component.kind !== "visual" || appearance.template !== "image") return component;
-			return {
-				...component,
-				kind: "image",
-				appearance: {
-					...appearance.border ? { border: appearance.border } : {},
-					fit: "contain"
-				}
-			};
-		}) : slide.components;
-		return {
-			...slide,
-			components
-		};
-	}) : input.slides;
-	return {
-		...input,
-		schema: compositionSchema,
-		slides
-	};
-}
-function migrateV10Document(input) {
-	const slides = Array.isArray(input.slides) ? input.slides.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const slide = value;
-		const components = Array.isArray(slide.components) ? slide.components.map((value) => {
-			if (!value || typeof value !== "object") return value;
-			const component = value;
-			const appearance = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-			if (component.kind === "headline") return {
-				...component,
-				kind: "text-block",
-				appearance: {
-					...appearance,
-					role: "title",
-					layout: "single",
-					orientation: "horizontal",
-					purpose: "narrative",
-					treatment: "plain",
-					logicalOrder: "none"
-				}
-			};
-			if (component.kind === "footnote") return {
-				...component,
-				kind: "text-block",
-				appearance: {
-					...appearance,
-					role: "footnote",
-					layout: "single",
-					orientation: "horizontal",
-					purpose: "narrative",
-					treatment: "plain",
-					logicalOrder: "none",
-					titleStyle: "plain"
-				}
-			};
-			if (component.kind === "text-block") return {
-				...component,
-				appearance: {
-					role: "body",
-					...appearance
-				}
-			};
-			if (component.kind === "visual") return {
-				...component,
-				kind: "chart"
-			};
-			if (component.kind === "diagram") {
-				const { template, ...rest } = appearance;
-				return {
-					...component,
-					appearance: {
-						...rest,
-						layout: template ?? appearance.layout ?? "linear"
-					}
-				};
-			}
-			if (component.kind === "icon" || component.kind === "shape") {
-				const slotIds = Array.isArray(component.slotIds) ? component.slotIds.map(String) : [];
-				const slotId = slotIds[0] ?? `${String(component.id)}-content`;
-				const primitive = component.kind === "icon" ? {
-					kind: "icon",
-					...typeof component.intent === "string" && component.intent.trim() ? { name: component.intent.trim() } : {},
-					...appearance.style ? { style: appearance.style } : {},
-					...appearance.color ? { color: appearance.color } : {}
-				} : {
-					kind: "shape",
-					shape: appearance.shape ?? "rectangle",
-					...appearance.color ? { color: appearance.color } : {},
-					...appearance.fill ? { fill: appearance.fill } : {}
-				};
-				return {
-					...component,
-					kind: "diagram",
-					slotIds: slotIds.length ? slotIds : [slotId],
-					appearance: {
-						type: "system",
-						layout: "hub-and-spoke",
-						border: appearance.border ?? "none",
-						colorScheme: "accent-with-muted-context",
-						emphasis: "primary",
-						density: "sparse"
-					},
-					topology: {
-						kind: "explicit",
-						nodes: (slotIds.length ? slotIds : [slotId]).map((currentSlotId, index) => ({
-							id: index ? `${String(component.id)}-slot-${index + 1}` : String(component.id),
-							slotId: currentSlotId,
-							...index ? { visible: false } : { primitive },
-							...component.preferredRect && typeof component.preferredRect === "object" ? { preferredRect: component.preferredRect } : {}
-						})),
-						edges: []
-					}
-				};
-			}
-			return component;
-		}) : slide.components;
-		const contentSlots = Array.isArray(slide.contentSlots) ? slide.contentSlots.map((value) => {
-			if (!value || typeof value !== "object") return value;
-			const slot = value;
-			return slot.role === "icon" || slot.role === "shape" ? {
-				...slot,
-				role: "entity"
-			} : slot;
-		}) : slide.contentSlots;
-		return {
-			...slide,
-			components,
-			contentSlots
-		};
-	}) : input.slides;
-	return {
-		...input,
-		schema: "konpeki-composition/v11",
-		slides
-	};
-}
-function migrateV11Document(input) {
-	const slides = Array.isArray(input.slides) ? input.slides.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const slide = value;
-		const components = Array.isArray(slide.components) ? slide.components.map((value) => {
-			if (!value || typeof value !== "object") return value;
-			const component = value;
-			if (component.kind !== "diagram") return component;
-			const appearance = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-			const migratedType = migrateLegacyDiagramType(appearance.type, appearance.layout);
-			const { layout, ...rest } = appearance;
-			return {
-				...component,
-				appearance: {
-					...rest,
-					type: migratedType ?? null
-				}
-			};
-		}) : slide.components;
-		return {
-			...slide,
-			components
-		};
-	}) : input.slides;
-	return {
-		...input,
-		schema: compositionSchema,
-		slides
-	};
-}
-function migrateInterimV12Sankey(input) {
-	if (!input || typeof input !== "object") return input;
-	const document = input;
-	if (document.schema !== "konpeki-composition/v18" || !Array.isArray(document.slides)) return input;
-	const slides = document.slides.map((value) => {
-		if (!value || typeof value !== "object") return value;
-		const slide = value;
-		if (!Array.isArray(slide.components)) return value;
-		const components = slide.components.map((componentValue) => {
-			if (!componentValue || typeof componentValue !== "object") return componentValue;
-			const component = componentValue;
-			const appearance = component.appearance && typeof component.appearance === "object" ? component.appearance : {};
-			if (component.kind !== "diagram" || appearance.type !== "sankey") return componentValue;
-			const { type: _type, ...sharedAppearance } = appearance;
-			return {
-				...component,
-				kind: "chart",
-				appearance: {
-					...sharedAppearance,
-					template: "sankey"
-				}
-			};
-		});
-		return {
-			...slide,
-			components
-		};
-	});
-	return {
-		...document,
-		slides
-	};
-}
-function preserveLegacyVisualizationChoices(input) {
-	if (!input || typeof input !== "object") return input;
-	const document = input;
-	if (!Array.isArray(document.slides)) return input;
-	return {
-		...document,
-		slides: document.slides.map((value) => {
-			if (!value || typeof value !== "object") return value;
-			const slide = value;
-			if (!Array.isArray(slide.components)) return value;
-			return {
-				...slide,
-				components: slide.components.map((value) => {
-					if (!value || typeof value !== "object") return value;
-					const component = value;
-					if (component.kind !== "diagram" && component.kind !== "chart" || !component.appearance || typeof component.appearance !== "object") return value;
-					return {
-						...component,
-						appearance: {
-							...component.appearance,
-							selection: "explicit"
-						}
-					};
-				})
-			};
-		})
-	};
-}
 function validateComposition(input) {
-	const legacy = Boolean(input && typeof input === "object" && "schema" in input && legacyCompositionSchemas.includes(input.schema));
-	const legacyInput = input;
-	const normalized = migrateInterimV12Sankey(legacy ? [
-		"konpeki-composition/v12",
-		"konpeki-composition/v13",
-		"konpeki-composition/v14",
-		"konpeki-composition/v15",
-		"konpeki-composition/v16",
-		"konpeki-composition/v17"
-	].includes(String(legacyInput.schema)) ? {
-		...legacyInput,
-		schema: compositionSchema
-	} : migrateV11Document(legacyInput.schema === "konpeki-composition/v11" ? legacyInput : migrateV10Document([
-		"konpeki-composition/v6",
-		"konpeki-composition/v7",
-		"konpeki-composition/v8",
-		"konpeki-composition/v9",
-		"konpeki-composition/v10"
-	].includes(String(legacyInput.schema)) ? migrateV7Document(legacyInput) : migrateV7Document(migrateV5Document(legacyInput.schema === "konpeki-composition/v5" ? legacyInput : migratePreV5Document(legacyInput))))) : input);
-	const candidate = legacy ? preserveLegacyVisualizationChoices(normalized) : normalized;
-	if (!structural(candidate)) return {
+	if (!structural(input)) return {
 		ok: false,
 		issues: (structural.errors ?? []).map((error) => ({
 			path: error.instancePath,
 			message: error.message ?? "Invalid value"
 		}))
 	};
+	const candidate = input;
 	const issues = [];
 	const fail = (path, message) => issues.push({
 		path,
@@ -1418,16 +1015,7 @@ function validateComposition(input) {
 		issues
 	} : {
 		ok: true,
-		document: legacy ? {
-			...candidate,
-			slides: candidate.slides.map((slide) => ({
-				...slide,
-				components: slide.components.map((component) => component.kind === "text-block" && !component.customVisual && component.content === void 0 ? {
-					...component,
-					content: component.intent ?? ""
-				} : component)
-			}))
-		} : candidate
+		document: input
 	};
 }
 //#endregion
@@ -1461,10 +1049,6 @@ function parseCompositionJSON(raw) {
 function revisionFor(value) {
 	return createHash("sha256").update(value).digest("hex");
 }
-function requestFileFor(compositionPath) {
-	const key = revisionFor(resolve(compositionPath));
-	return join(tmpdir(), "konpeki", `${key}.request.json`);
-}
 async function readCompositionFile(compositionPath) {
 	const raw = await readFile(compositionPath, "utf8");
 	const parsed = parseCompositionJSON(raw);
@@ -1500,28 +1084,134 @@ async function saveCompositionFile(compositionPath, expectedRevision, document)
 	}
 	return { revision: revisionFor(value) };
 }
-async function writeBuildRequest(compositionPath, request) {
-	const current = await readCompositionFile(compositionPath);
-	if (current.revision !== request.revision) throw Object.assign(/* @__PURE__ */ new Error("Save the latest composition before requesting a build."), {
-		code: "REVISION_CONFLICT",
-		revision: current.revision
+//#endregion
+//#region src/lib/review.ts
+var emptyReview = () => ({
+	schema: "konpeki-review/v1",
+	version: 0,
+	notes: []
+});
+var activeRequest = (request) => request?.status === "submitted" || request?.status === "working";
+//#endregion
+//#region bin/review-store.ts
+var reviewFileFor = (path) => `${resolve(path)}.review.json`;
+var conflict = (message) => Object.assign(new Error(message), { code: "REVISION_CONFLICT" });
+var invalid = (message) => Object.assign(new Error(message), { code: "INVALID_REVIEW" });
+async function readReview(path) {
+	try {
+		const state = JSON.parse(await readFile(reviewFileFor(path), "utf8"));
+		if (state.schema !== "konpeki-review/v1") throw invalid("Unsupported revision-note format.");
+		return state;
+	} catch (error) {
+		if (error.code === "ENOENT") return emptyReview();
+		throw error;
+	}
+}
+async function mutate(path, change) {
+	const file = reviewFileFor(path);
+	const release = await lockfile.lock(file, {
+		realpath: false,
+		retries: {
+			retries: 60,
+			minTimeout: 100,
+			maxTimeout: 250
+		}
+	});
+	const temporary = `${file}.${randomUUID()}.tmp`;
+	try {
+		const state = await readReview(path);
+		await change(state);
+		state.version++;
+		await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`);
+		await rename(temporary, file);
+		return state;
+	} finally {
+		await rm(temporary, { force: true });
+		await release();
+	}
+}
+function validateTarget(document, target) {
+	const slide = document.slides.find((s) => s.id === target.slideId);
+	if (!slide) throw invalid("The note's page no longer exists. Remove the note and select a new target.");
+	const component = slide.components.find((c) => c.id === target.componentId);
+	if (target.componentId !== void 0 && !component) throw invalid("The note's component no longer exists. Remove the note and select a new target.");
+	if (target.elementId !== void 0 && !(component?.customVisual?.format === "vector" && component.customVisual.elements.some((e) => e.id === target.elementId))) throw invalid("The note's vector element no longer exists. Remove the note and select a new target.");
+}
+async function addRevisionNote(path, target, text) {
+	if (typeof text !== "string" || !text.trim() || text.length > 4e3) throw invalid("Write a revision note of 1–4000 characters.");
+	return mutate(path, async (state) => {
+		if (activeRequest(state.request)) throw conflict("Wait for the current request before adding notes.");
+		validateTarget((await readCompositionFile(path)).document, target);
+		state.notes.push({
+			id: randomUUID(),
+			slideId: target.slideId,
+			...target.componentId ? { componentId: target.componentId } : {},
+			...target.elementId ? { elementId: target.elementId } : {},
+			text: text.trim(),
+			resolved: false
+		});
+	});
+}
+async function removeRevisionNote(path, id) {
+	return mutate(path, (state) => {
+		if (activeRequest(state.request)) throw conflict("Wait for the current request before removing notes.");
+		state.notes = state.notes.filter((note) => note.id !== id);
+	});
+}
+async function writeBuildRequest(path, request) {
+	return mutate(path, async (state) => {
+		if (activeRequest(state.request)) throw conflict("A build request is already waiting or working.");
+		const current = await readCompositionFile(path);
+		if (current.revision !== request.revision) throw conflict("Save the latest composition before requesting a build.");
+		validateTarget(current.document, request);
+		const notes = state.notes.filter((note) => !note.resolved);
+		for (const note of notes) validateTarget(current.document, note);
+		if (typeof request.instruction !== "string" || !request.instruction.trim()) throw invalid("Describe what the agent should build.");
+		state.request = {
+			schema: "konpeki-build-request/v2",
+			id: randomUUID(),
+			compositionPath: resolve(path),
+			revision: current.revision,
+			instruction: request.instruction.trim(),
+			slideId: request.slideId,
+			...request.componentId ? { componentId: request.componentId } : {},
+			...request.elementId ? { elementId: request.elementId } : {},
+			notes,
+			status: "submitted"
+		};
+	});
+}
+async function claimBuildRequest(path) {
+	if ((await readReview(path)).request?.status !== "submitted") return;
+	let claimed;
+	await mutate(path, (state) => {
+		if (state.request?.status !== "submitted") return;
+		state.request.status = "working";
+		claimed = state.request;
+	});
+	return claimed;
+}
+async function finishBuildRequest(path, id, status, message) {
+	if (![
+		"done",
+		"needs-clarification",
+		"failed"
+	].includes(status)) throw invalid("Status must be done, needs-clarification or failed.");
+	if (status !== "done" && !message?.trim()) throw invalid("Explain what failed or needs clarification.");
+	return mutate(path, async (state) => {
+		if (state.request?.id !== id || !activeRequest(state.request)) throw conflict("This request is no longer active.");
+		if (status === "done" && state.request.status !== "working") throw conflict("Claim the request with konpeki wait before completing it.");
+		if (status === "done") {
+			state.request.resultRevision = (await readCompositionFile(path)).revision;
+			const completed = new Set(state.request.notes.map((note) => note.id));
+			state.notes = state.notes.map((note) => completed.has(note.id) ? {
+				...note,
+				resolved: true
+			} : note);
+		}
+		state.request.status = status;
+		state.request.message = message?.trim();
 	});
-	const output = requestFileFor(compositionPath);
-	await mkdir(dirname(output), { recursive: true });
-	const value = {
-		schema: "konpeki-build-request/v1",
-		compositionPath: resolve(compositionPath),
-		revision: request.revision,
-		instruction: request.instruction.trim(),
-		slideId: request.slideId,
-		...request.componentId ? { componentId: request.componentId } : {},
-		createdAt: (/* @__PURE__ */ new Date()).toISOString()
-	};
-	await writeFile(output, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-	return {
-		output,
-		request: value
-	};
 }
 //#endregion
 //#region bin/session-plugin.ts
@@ -1547,7 +1237,7 @@ async function readJSON(request) {
 function errorResponse(error) {
 	const code = error instanceof Error && "code" in error ? error.code : void 0;
 	return {
-		status: code === "REVISION_CONFLICT" ? 409 : code === "INVALID_COMPOSITION" ? 422 : code === "BODY_TOO_LARGE" ? 413 : error instanceof SyntaxError ? 400 : 500,
+		status: code === "REVISION_CONFLICT" ? 409 : code === "INVALID_COMPOSITION" || code === "INVALID_REVIEW" ? 422 : code === "BODY_TOO_LARGE" ? 413 : error instanceof SyntaxError ? 400 : 500,
 		body: {
 			error: error instanceof Error ? error.message : "File-session request failed.",
 			...error && typeof error === "object" && "revision" in error ? { revision: error.revision } : {}
@@ -1558,6 +1248,19 @@ function fileSessionPlugin({ compositionPath, token, onBuildRequest }) {
 	return {
 		name: "konpeki-file-session",
 		enforce: "pre",
+		config(config) {
+			return { server: { fs: { deny: [
+				".env",
+				".env.*",
+				"*.{crt,pem,key,p12,pfx,cer,der}",
+				".npmrc",
+				".yarnrc.yml",
+				"**/.git/**",
+				...config.server?.fs?.deny ?? [],
+				"**/*.review.json",
+				"**/*.review.json.*"
+			] } } };
+		},
 		configureServer(server) {
 			server.middlewares.use(async (request, response, next) => {
 				const url = new URL(request.url || "/", "http://localhost");
@@ -1568,7 +1271,11 @@ function fileSessionPlugin({ compositionPath, token, onBuildRequest }) {
 				}
 				try {
 					if (url.pathname === route && request.method === "GET") {
-						sendJSON(response, 200, await readCompositionFile(compositionPath));
+						const review = await readReview(compositionPath);
+						sendJSON(response, 200, {
+							...await readCompositionFile(compositionPath),
+							review
+						});
 						return;
 					}
 					if (url.pathname === route && request.method === "PUT") {
@@ -1584,7 +1291,20 @@ function fileSessionPlugin({ compositionPath, token, onBuildRequest }) {
 						}
 						const result = await writeBuildRequest(compositionPath, body);
 						onBuildRequest?.(result);
-						sendJSON(response, 201, { ok: true });
+						sendJSON(response, 201, result);
+						return;
+					}
+					if (url.pathname === `${route}/notes` && request.method === "POST") {
+						const body = await readJSON(request);
+						sendJSON(response, 201, await addRevisionNote(compositionPath, body, body.text));
+						return;
+					}
+					if (url.pathname === `${route}/notes` && request.method === "DELETE") {
+						sendJSON(response, 200, await removeRevisionNote(compositionPath, (await readJSON(request)).id));
+						return;
+					}
+					if (url.pathname === `${route}/cancel` && request.method === "POST") {
+						sendJSON(response, 200, await finishBuildRequest(compositionPath, (await readJSON(request)).id, "failed", "Cancelled by user. Stop the agent before starting another request."));
 						return;
 					}
 					sendJSON(response, 404, { error: "Unknown file-session endpoint." });
@@ -1603,7 +1323,9 @@ function usage() {
 	console.error(`Usage:
   konpeki preview <composition.json> [--host <host>] [--port <port>]
   konpeki validate <composition.json>
-  konpeki wait <composition.json>`);
+  konpeki wait <composition.json>
+  konpeki request <composition.json>
+  konpeki finish <composition.json> <request-id> [--status done|needs-clarification|failed] [--message <text>]`);
 }
 function option(name, fallback) {
 	const index = process.argv.indexOf(name);
@@ -1616,7 +1338,6 @@ async function preview(input) {
 	const host = option("--host", "127.0.0.1");
 	const port = Number(option("--port", "4318"));
 	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error("Port must be an integer from 1 to 65535.");
-	await rm(requestFileFor(compositionPath), { force: true });
 	const server = await createServer({
 		root,
 		configFile: resolve(root, "vite.config.ts"),
@@ -1629,6 +1350,7 @@ async function preview(input) {
 			compositionPath,
 			token,
 			onBuildRequest: ({ request }) => {
+				if (!request) return;
 				console.log(`\nBuild requested for ${request.compositionPath}`);
 				console.log(`Revision: ${request.revision}`);
 				console.log(`Instruction: ${request.instruction}`);
@@ -1649,17 +1371,12 @@ async function validate(input) {
 	console.log(`${result.name}: valid (${result.revision})`);
 }
 async function waitForRequest(input) {
-	const requestPath = requestFileFor(resolve(input));
-	console.log(`Waiting for a Build it request for ${resolve(input)}…`);
+	console.error(`Waiting for a Build it request for ${resolve(input)}…`);
 	for (;;) {
-		try {
-			await access(requestPath);
-			const value = await readFile(requestPath, "utf8");
-			await rm(requestPath, { force: true });
-			process.stdout.write(value);
+		const request = await claimBuildRequest(resolve(input));
+		if (request) {
+			console.log(JSON.stringify(request, null, 2));
 			return;
-		} catch (error) {
-			if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
 		}
 		await new Promise((resolveWait) => setTimeout(resolveWait, 250));
 	}
@@ -1673,7 +1390,12 @@ if (!command || !input) {
 	if (command === "preview") await preview(input);
 	else if (command === "validate") await validate(input);
 	else if (command === "wait") await waitForRequest(input);
-	else {
+	else if (command === "request") console.log(JSON.stringify((await readReview(input)).request ?? null, null, 2));
+	else if (command === "finish") {
+		if (!process.argv[4]) throw new Error("Provide the request ID returned by konpeki wait.");
+		const result = await finishBuildRequest(input, process.argv[4], option("--status", "done"), option("--message"));
+		console.log(JSON.stringify(result.request, null, 2));
+	} else {
 		usage();
 		process.exitCode = 1;
 	}