wiki-viewer 1.5.2 → 1.7.0

package/.next/standalone/packages/wiki-viewer-mcp/src/index.ts

@@ -27,8 +27,35 @@ import {
 import * as z from "zod";
 
 import { parseArgs } from "node:util";
-import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError } from "./http-client.js";
+import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError, PatchUnsupportedError, MatchCountError } from "./http-client.js";
 import * as stateCache from "./state-cache.js";
+
+/**
+ * Enable pooled HTTP keep-alive for the global fetch the client uses.
+ *
+ * Without this, every tool call opens a fresh connection and pays a full
+ * TCP + TLS handshake (~3 RTT) before the request even goes out. Over a WAN
+ * link that turns a sub-100ms write into 300ms-1s+, and multiplies across the
+ * GET+PUT an edit performs. Reusing connections removes that per-call penalty.
+ *
+ * Wrapped in try/catch + dynamic import so a missing/edge undici never breaks
+ * startup; it just falls back to default (non-pooled) fetch.
+ */
+async function enableKeepAlive(): Promise<void> {
+  try {
+    const { Agent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(
+      new Agent({
+        keepAliveTimeout: 30_000,
+        keepAliveMaxTimeout: 60_000,
+        connections: 16,
+        pipelining: 1,
+      }),
+    );
+  } catch {
+    // undici unavailable — default fetch still works, just without pooling.
+  }
+}
 import {
   register,
   RegisterScope,
@@ -287,17 +314,47 @@ export function createServer(client: WikiViewerClient): Server {
           const block = checkCollabBlock(path);
           if (block) return err(block);
 
-          // Read → transform → PUT with If-Match
+          // Best path: server-side PATCH str-replace — sends only {find,replace}
+          // (~hundreds of bytes) instead of the whole file. One small request.
+          // Requires a known sha (If-Match); use cached sha if present, else the
+          // server's 412-recover path handles it. Falls back to read+PUT if the
+          // server has no PATCH route (older version).
+          const cachedForPatch = stateCache.get(path);
+          if (cachedForPatch?.collabState !== "active") {
+            try {
+              const r = await client.patchFile(path, find, replace, {
+                ifMatch: cachedForPatch?.sha256,
+              });
+              return ok(
+                `Edited: ${path}\nReplaced ${JSON.stringify(find)} → ${JSON.stringify(replace)}\nNew sha256: ${r.sha256}`,
+              );
+            } catch (e) {
+              if (e instanceof MatchCountError) {
+                return err(
+                  `edit_file: expected to replace exactly 1 occurrence of ${JSON.stringify(find)} in "${path}", ` +
+                  `but found ${e.found}. Re-read the file or make the search string unique.`,
+                );
+              }
+              if (e instanceof CollabActiveError) {
+                return err(collabActiveMessage(path, e.snapshotUrl));
+              }
+              if (e instanceof IfMatchError) {
+                // sha was stale — fall through to read+retry below.
+              } else if (!(e instanceof PatchUnsupportedError)) {
+                throw e;
+              }
+              // PatchUnsupportedError or stale If-Match → fall back to read+PUT.
+            }
+          }
+
+          // Fallback path: read → transform → PUT with If-Match.
           const readResult = await client.readFile(path);
           if (readResult.text === null) {
             return err(`edit_file: "${path}" appears to be binary — cannot do text replacement.`);
           }
-
-          // Check collab state from fresh read
           if (readResult.collabState === "active") {
             return err(collabActiveMessage(path, readResult.collabSnapshot));
           }
-
           if (!readResult.text.includes(find)) {
             return err(
               `edit_file: string not found in "${path}".\n` +
@@ -433,6 +490,7 @@ function buildJsonSchema(val: AnyZodVal): Record<string, unknown> {
 // ─── Entrypoints ─────────────────────────────────────────────────────────────
 
 async function main() {
+  await enableKeepAlive();
   const client = createClient();
   const server = createServer(client);
   const transport = new StdioServerTransport();

package/.next/standalone/packages/wiki-viewer-mcp/src/state-cache.ts

@@ -15,8 +15,18 @@ export interface PathState {
   collabSnapshot: string | null;
   /** When this cache entry was last updated (ms) */
   fetchedAt: number;
+  /**
+   * Last-known text body, paired with `sha256`. Only set for text files from a
+   * read. Lets edit_file skip the GET round-trip: it transforms this cached
+   * text and PUTs with If-Match=sha256; if the file changed server-side the
+   * PUT 412s and the caller re-reads. Capped by MAX_CACHED_BODY_BYTES.
+   */
+  body?: string;
 }
 
+/** Don't cache bodies larger than this (avoid unbounded memory). */
+export const MAX_CACHED_BODY_BYTES = 256 * 1024;
+
 const cache = new Map<string, PathState>();
 
 export function set(path: string, state: PathState): void {

package/.next/standalone/pnpm-lock.yaml

@@ -20,6 +20,9 @@ importers:
       chokidar:
         specifier: ^5.0.0
         version: 5.0.0
+      jszip:
+        specifier: ^3.10.1
+        version: 3.10.1
       kysely:
         specifier: 0.28.5
         version: 0.28.5
@@ -204,9 +207,6 @@ importers:
       highlight.js:
         specifier: ^11.11.1
         version: 11.11.1
-      jszip:
-        specifier: ^3.10.1
-        version: 3.10.1
       lowlight:
         specifier: ^3.3.0
         version: 3.3.0

package/.next/standalone/src/app/api/agent/fs/file/[...path]/route.ts

@@ -24,6 +24,7 @@ import {
 	isMarkdown,
 	atomicWrite,
 	ensureParentDir,
+	looksLikeBinary,
 } from "@/lib/proof/raw-fs";
 import { computeCollabState } from "@/lib/proof/collab-state";
 
@@ -125,16 +126,28 @@ export async function GET(
 	});
 }
 
-// ── PUT ──────────────────────────────────────────────────────────────────────
+// ── Shared mutation path (PUT + PATCH) ────────────────────────────────────────
 
-export async function PUT(
+/**
+ * Single code path for all Tier-1 byte mutations so PUT and PATCH cannot drift
+ * on auth/scope/If-Match/R6/atomicWrite/reconcile/audit.
+ *
+ * `computeNewBody` receives the existing file buffer (or null if absent) and
+ * returns the new bytes, or an error response to short-circuit (e.g. PATCH
+ * match-count mismatch). `op` is the audit verb ("put" | "patch").
+ */
+async function applyMutation(
 	req: Request,
-	{ params }: { params: Promise<{ path: string[] }> },
+	segments: string[],
+	opts: {
+		op: "put" | "patch";
+		allowCreate: boolean;
+		computeNewBody: (existing: Buffer | null) => Buffer | NextResponse;
+	},
 ): Promise<NextResponse> {
 	const auth = await checkAuth(req);
 	if (!auth.ok) return errJson("UNAUTHORIZED", auth.message ?? "Unauthorized", 401);
 
-	const { path: segments } = await params;
 	const relPath = rel(segments);
 	const url = new URL(req.url);
 	const mkdirs = url.searchParams.get("mkdirs") === "true";
@@ -150,56 +163,52 @@ export async function PUT(
 	if (!scope.ok) return errJson(scope.code, scope.message, 403);
 
 	const ifMatch = req.headers.get("if-match");
-	const bodyBuf = Buffer.from(await req.arrayBuffer());
-	const newSha = sha256ofBuf(bodyBuf);
-
-	// Check existing file
-	let existingSha: string | undefined;
-	let existed = false;
-	try {
-		const existing = await readFile(absPath);
-		existingSha = sha256ofBuf(existing);
-		existed = true;
-	} catch (e) {
-		if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
-	}
+	const ifCollabMatch = req.headers.get("if-collab-match");
+	const rootDir = getRootDir();
 
-	if (existed) {
-		// Overwrite: If-Match required by default (unless ?force=true)
-		if (!force && !ifMatch) {
-			return errJson(
-				"PRECONDITION_REQUIRED",
-				"If-Match header required for overwrites (use ?force=true to bypass with audit)",
-				412,
-			);
+	// The whole read-existing → precondition → compute → write → reconcile → audit
+	// sequence runs inside the mutex for .md (so R6 and reconcile are atomic with
+	// the write); non-.md runs it without the mutex.
+	const doMutation = async (): Promise<NextResponse> => {
+		// Read existing
+		let existingBuf: Buffer | null = null;
+		let existingSha: string | undefined;
+		try {
+			existingBuf = await readFile(absPath);
+			existingSha = sha256ofBuf(existingBuf);
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
 		}
-		if (ifMatch) {
-			const provided = extractShaHex(ifMatch);
-			const current = extractShaHex(existingSha!);
-			if (provided !== current) {
+		const existed = existingBuf !== null;
+
+		if (existed) {
+			// Overwrite: If-Match required by default (unless ?force=true)
+			if (!force && !ifMatch) {
+				return errJson(
+					"PRECONDITION_REQUIRED",
+					"If-Match header required for overwrites (use ?force=true to bypass with audit)",
+					412,
+				);
+			}
+			if (ifMatch && extractShaHex(ifMatch) !== extractShaHex(existingSha!)) {
 				return errJson("PRECONDITION_FAILED", "If-Match sha256 mismatch", 412);
 			}
+		} else {
+			if (!opts.allowCreate) {
+				return errJson("NOT_FOUND", "File not found", 404);
+			}
+			const parentOk = await ensureParentDir(absPath, mkdirs);
+			if (!parentOk) {
+				return errJson(
+					"PARENT_NOT_FOUND",
+					"Parent directory does not exist (use ?mkdirs=true to create)",
+					400,
+				);
+			}
 		}
-	} else {
-		// Create: ensure parent dir exists
-		const parentOk = await ensureParentDir(absPath, mkdirs);
-		if (!parentOk) {
-			return errJson(
-				"PARENT_NOT_FOUND",
-				"Parent directory does not exist (use ?mkdirs=true to create)",
-				400,
-			);
-		}
-	}
 
-	const rootDir = getRootDir();
-	// R6: for .md, re-check collab state atomically inside write mutex
-	const ifCollabMatch = req.headers.get("if-collab-match");
-
-	if (isMarkdown(relPath)) {
-		// R1: acquire shared mutex; R2: reconcile eagerly inside it
-		return await withFileMutex(relPath, async () => {
-			// R6: atomic collab-state check (closes TOCTOU race)
+		// R6: for .md, re-check collab state atomically (inside mutex)
+		if (isMarkdown(relPath)) {
 			const { state, revision, snapshotUrl } = await computeCollabState(rootDir, relPath);
 			if (state === "active") {
 				const matchVal = ifCollabMatch?.trim();
@@ -216,9 +225,17 @@ export async function PUT(
 					);
 				}
 			}
+		}
+
+		// Compute new bytes (PUT: request body; PATCH: str-replace on existing)
+		const computed = opts.computeNewBody(existingBuf);
+		if (computed instanceof NextResponse) return computed;
+		const bodyBuf = computed;
+		const newSha = sha256ofBuf(bodyBuf);
 
-			await atomicWrite(absPath, bodyBuf);
+		await atomicWrite(absPath, bodyBuf);
 
+		if (isMarkdown(relPath)) {
 			const content = bodyBuf.toString("utf-8");
 			const sidecar = (await readSidecar(rootDir, relPath)) ?? emptySidecar(relPath);
 			await reconcileSidecar({
@@ -230,44 +247,119 @@ export async function PUT(
 				eventType: "file.rawWritten",
 				fingerprint: newSha,
 			});
+		}
 
-			writeAuditRow({
-				agentId: auth.agent.id,
-				op: "put",
-				path: relPath,
-				oldSha: existingSha,
-				newSha,
-				forced: force,
-			});
+		writeAuditRow({
+			agentId: auth.agent.id,
+			op: opts.op,
+			path: relPath,
+			oldSha: existingSha,
+			newSha,
+			forced: force,
+		});
 
-			const st = await stat(absPath);
-			return NextResponse.json({
-				path: relPath,
-				sha256: newSha,
-				size: st.size,
-				mtime: st.mtime.toISOString(),
-				created: !existed,
-			});
+		const st = await stat(absPath);
+		return NextResponse.json({
+			path: relPath,
+			sha256: newSha,
+			size: st.size,
+			mtime: st.mtime.toISOString(),
+			created: !existed,
 		});
-	}
+	};
 
-	// Non-.md: atomic write + audit (no mutex, no sidecar)
-	await atomicWrite(absPath, bodyBuf);
-	writeAuditRow({
-		agentId: auth.agent.id,
+	return isMarkdown(relPath) ? withFileMutex(relPath, doMutation) : doMutation();
+}
+
+// ── PUT ──────────────────────────────────────────────────────────────────────
+
+export async function PUT(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): Promise<NextResponse> {
+	const { path: segments } = await params;
+	const bodyBuf = Buffer.from(await req.arrayBuffer());
+	return applyMutation(req, segments, {
 		op: "put",
-		path: relPath,
-		oldSha: existingSha,
-		newSha,
-		forced: force,
+		allowCreate: true,
+		computeNewBody: () => bodyBuf,
 	});
-	const st = await stat(absPath);
-	return NextResponse.json({
-		path: relPath,
-		sha256: newSha,
-		size: st.size,
-		mtime: st.mtime.toISOString(),
-		created: !existed,
+}
+
+// ── PATCH ─────────────────────────────────────────────────────────────────────
+// Server-side str-replace so agents send only the change, not the whole file.
+// Strict: exact substring (no regex), text/UTF-8 only, If-Match required,
+// expectedOccurrences must match exactly (default 1). Shares applyMutation, so
+// lock / R6 / reconcile / audit behave identically to PUT.
+
+const MAX_PATCH_STRING = 1_000_000; // 1MB cap on find/replace strings
+
+export async function PATCH(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): Promise<NextResponse> {
+	const { path: segments } = await params;
+
+	let body: { find?: unknown; replace?: unknown; expectedOccurrences?: unknown };
+	try {
+		body = (await req.json()) as typeof body;
+	} catch {
+		return errJson("INVALID_PAYLOAD", "Body must be JSON {find, replace, expectedOccurrences?}", 400);
+	}
+	const find = body.find;
+	const replace = body.replace;
+	if (typeof find !== "string" || typeof replace !== "string") {
+		return errJson("INVALID_PAYLOAD", "find and replace must be strings", 400);
+	}
+	if (find.length === 0) {
+		return errJson("INVALID_PAYLOAD", "find must not be empty", 400);
+	}
+	if (find.length > MAX_PATCH_STRING || replace.length > MAX_PATCH_STRING) {
+		return errJson("PAYLOAD_TOO_LARGE", "find/replace exceeds 1MB limit", 413);
+	}
+	let expected = 1;
+	if (body.expectedOccurrences !== undefined) {
+		if (typeof body.expectedOccurrences !== "number" || !Number.isInteger(body.expectedOccurrences) || body.expectedOccurrences < 1) {
+			return errJson("INVALID_PAYLOAD", "expectedOccurrences must be a positive integer", 400);
+		}
+		expected = body.expectedOccurrences;
+	}
+
+	return applyMutation(req, segments, {
+		op: "patch",
+		allowCreate: false, // patch only edits existing files
+		computeNewBody: (existing) => {
+			if (existing === null) return errJson("NOT_FOUND", "File not found", 404);
+			if (looksLikeBinary(existing)) {
+				return errJson("UNSUPPORTED", "Cannot patch binary / non-text file", 415);
+			}
+			let text: string;
+			try {
+				text = new TextDecoder("utf-8", { fatal: true }).decode(existing);
+			} catch {
+				return errJson("UNSUPPORTED", "File is not valid UTF-8", 415);
+			}
+			// Count exact occurrences (no regex).
+			let count = 0;
+			let idx = text.indexOf(find);
+			while (idx !== -1) {
+				count++;
+				idx = text.indexOf(find, idx + find.length);
+			}
+			if (count !== expected) {
+				return NextResponse.json(
+					{
+						error: "MATCH_COUNT_MISMATCH",
+						message: `Expected ${expected} occurrence(s) of find, found ${count}. Re-read the file or adjust expectedOccurrences.`,
+						found: count,
+						expected,
+					},
+					{ status: 422 },
+				);
+			}
+			// Replace all (count == expected) occurrences, literally.
+			return Buffer.from(text.split(find).join(replace), "utf-8");
+		},
 	});
 }
 

package/.next/standalone/src/app/api/wiki/download/route.ts

@@ -0,0 +1,99 @@
+import { createReadStream } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import JSZip from "jszip";
+import { NextResponse } from "next/server";
+import { requireUser } from "@/lib/auth/server";
+import { safeRootPath } from "@/lib/root-dir";
+
+// Skip noise that should never end up in a downloaded archive.
+const SKIP_DIRS = new Set([".git", "node_modules", ".next", ".proof"]);
+
+function contentDisposition(filename: string): string {
+	// RFC 5987: ASCII fallback + UTF-8 encoded form for non-ASCII names.
+	const ascii = filename.replace(/[^\x20-\x7e]/g, "_").replace(/"/g, "'");
+	const encoded = encodeURIComponent(filename);
+	return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+
+async function addDirToZip(
+	zip: JSZip,
+	absDir: string,
+	zipPrefix: string,
+): Promise<void> {
+	const names = await readdir(absDir);
+	for (const name of names) {
+		if (SKIP_DIRS.has(name)) continue;
+		const abs = path.join(absDir, name);
+		const info = await stat(abs);
+		const zipPath = zipPrefix ? `${zipPrefix}/${name}` : name;
+		if (info.isDirectory()) {
+			await addDirToZip(zip, abs, zipPath);
+		} else if (info.isFile()) {
+			zip.file(zipPath, await readFile(abs));
+		}
+	}
+}
+
+export async function GET(request: Request) {
+	const auth = await requireUser(request);
+	if (!auth.ok)
+		return NextResponse.json({ error: "UNAUTHORIZED" }, { status: 401 });
+
+	const { searchParams } = new URL(request.url);
+	const rel = searchParams.get("path") ?? "";
+	const target = safeRootPath(rel);
+	if (!target)
+		return NextResponse.json({ error: "Invalid path" }, { status: 400 });
+
+	let info: Awaited<ReturnType<typeof stat>>;
+	try {
+		info = await stat(target);
+	} catch {
+		return NextResponse.json({ error: "Not found" }, { status: 404 });
+	}
+
+	const baseName = path.basename(target) || "download";
+
+	if (info.isFile()) {
+		const webStream = Readable.toWeb(
+			createReadStream(target),
+		) as ReadableStream;
+		return new Response(webStream, {
+			headers: {
+				"Content-Type": "application/octet-stream",
+				"Content-Length": String(info.size),
+				"Content-Disposition": contentDisposition(baseName),
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+
+	if (info.isDirectory()) {
+		const zip = new JSZip();
+		try {
+			await addDirToZip(zip, target, "");
+		} catch {
+			return NextResponse.json(
+				{ error: "Failed to read folder" },
+				{ status: 500 },
+			);
+		}
+		const buffer = await zip.generateAsync({
+			type: "nodebuffer",
+			compression: "DEFLATE",
+			compressionOptions: { level: 6 },
+		});
+		return new Response(new Uint8Array(buffer), {
+			headers: {
+				"Content-Type": "application/zip",
+				"Content-Length": String(buffer.length),
+				"Content-Disposition": contentDisposition(`${baseName}.zip`),
+				"Cache-Control": "private, no-store",
+			},
+		});
+	}
+
+	return NextResponse.json({ error: "Unsupported path" }, { status: 400 });
+}

package/.next/standalone/src/app/page.tsx

@@ -6,6 +6,7 @@ import {
 	Check,
 	ChevronDown,
 	ChevronRight,
+	Download,
 	File,
 	FilePlus,
 	FileText,
@@ -272,6 +273,7 @@ export default function Page() {
 	const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
 	const [settingsOpen, setSettingsOpen] = useState(false);
 	const [fileContent, setFileContent] = useState<string | null>(null);
+	const [fileRevision, setFileRevision] = useState(0);
 	const [fileLoading, setFileLoading] = useState(false);
 	const [editing, setEditing] = useState(false);
 	const [editContent, setEditContent] = useState("");
@@ -411,6 +413,7 @@ export default function Page() {
 			if (res.ok) {
 				const d: { content: string } = await res.json();
 				setFileContent(d.content);
+				setFileRevision(Number(res.headers.get("X-Wiki-Revision") ?? 0));
 			}
 		} catch {
 			/* ignore */
@@ -536,6 +539,7 @@ export default function Page() {
 		setEditing(false);
 		setSaveError(null);
 		setFileContent(null);
+		setFileRevision(0);
 		const kind = viewerKindFor(node.name, node.type);
 		if (!["editor", "text"].includes(kind) && !isText(node.name)) return;
 		setFileLoading(true);
@@ -546,6 +550,7 @@ export default function Page() {
 			if (res.ok) {
 				const d: { content: string } = await res.json();
 				setFileContent(d.content);
+				setFileRevision(Number(res.headers.get("X-Wiki-Revision") ?? 0));
 			}
 		} catch {
 			/* ignore */
@@ -624,9 +629,15 @@ export default function Page() {
 		const res = await fetch("/api/wiki/content", {
 			method: "PUT",
 			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({ path: openFile.path, content: editContent }),
+			body: JSON.stringify({
+				path: openFile.path,
+				content: editContent,
+				baseRevision: fileRevision,
+			}),
 		});
 		if (res.ok) {
+			const d: { revision?: number } = await res.json();
+			if (typeof d.revision === "number") setFileRevision(d.revision);
 			setFileContent(editContent);
 			setEditing(false);
 		} else {
@@ -732,6 +743,16 @@ export default function Page() {
 		}
 	}
 
+	function handleDownload(node: TreeNode) {
+		const url = `/api/wiki/download?path=${encodeURIComponent(node.path)}`;
+		const a = document.createElement("a");
+		a.href = url;
+		a.download = node.type === "file" ? node.name : `${node.name}.zip`;
+		document.body.appendChild(a);
+		a.click();
+		a.remove();
+	}
+
 	async function handleDelete() {
 		if (!deletingPath) return;
 		await fetch("/api/wiki", {
@@ -946,6 +967,15 @@ export default function Page() {
 								</Button>
 							</>
 						)}
+						<Button
+							size="sm"
+							variant="ghost"
+							className="h-6 w-6 p-0 text-muted-foreground hover:text-foreground"
+							title={node.type === "file" ? "Download" : "Download as zip"}
+							onClick={() => handleDownload(node)}
+						>
+							<Download className="h-3 w-3" />
+						</Button>
 						<Button
 							size="sm"
 							variant="ghost"