wiki-viewer 1.4.3 → 1.5.0

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

@@ -0,0 +1,144 @@
+/**
+ * TOFU registration flow for wiki-viewer.
+ *
+ * Pure function `register()` is testable with a mock fetch.
+ * The CLI wrapper lives in index.ts.
+ *
+ * Flow:
+ *   POST /api/agent/register  → {registrationId, pollUrl, status:"pending"}
+ *   human approves in AI Panel
+ *   GET <pollUrl>             → 202 pending | 200 approved | 410 denied | 404 expired
+ *   returns {token, agentId}
+ */
+
+export interface RegisterScope {
+  paths: string[];
+  ops: Array<"read" | "mutate" | "delete">;
+}
+
+export interface RegisterOptions {
+  baseUrl: string;
+  id: string;           // must match ^ai:[a-z][a-z0-9-]{0,30}$
+  displayName: string;
+  scope: RegisterScope;
+  /** Override fetch for testing */
+  fetch?: typeof globalThis.fetch;
+  /** How long to wait between polls (ms, default 3000) */
+  pollIntervalMs?: number;
+  /** Total time to wait before giving up (ms, default 300_000) */
+  timeoutMs?: number;
+  /** Called each time we get a "pending" poll response */
+  onPending?: (registrationId: string, attempt: number) => void;
+}
+
+export interface RegisterResult {
+  token: string;
+  agentId: string;
+}
+
+export async function register(opts: RegisterOptions): Promise<RegisterResult> {
+  const _fetch = opts.fetch ?? globalThis.fetch;
+  const pollIntervalMs = opts.pollIntervalMs ?? 3_000;
+  const timeoutMs = opts.timeoutMs ?? 300_000;
+  const base = opts.baseUrl.replace(/\/$/, "");
+
+  // ── Step 1: POST registration ──────────────────────────────────────────────
+  const postRes = await _fetch(`${base}/api/agent/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      id: opts.id,
+      displayName: opts.displayName,
+      scope: opts.scope,
+    }),
+  });
+
+  if (!postRes.ok) {
+    const body = await postRes.text().catch(() => "");
+    throw new Error(`Registration request failed (${postRes.status}): ${body}`);
+  }
+
+  const { registrationId, pollUrl } = await postRes.json() as {
+    registrationId: string;
+    pollUrl: string;
+    status: string;
+  };
+
+  // Resolve pollUrl — may be absolute or relative
+  const resolvedPollUrl = pollUrl.startsWith("http")
+    ? pollUrl
+    : `${base}${pollUrl.startsWith("/") ? "" : "/"}${pollUrl}`;
+
+  // ── Step 2: Poll until approved / denied / timeout ─────────────────────────
+  const deadline = Date.now() + timeoutMs;
+  let attempt = 0;
+
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+    attempt++;
+
+    const pollRes = await _fetch(resolvedPollUrl);
+
+    if (pollRes.status === 200) {
+      const body = await pollRes.json() as {
+        status: string;
+        agentId?: string;
+        token?: string;
+      };
+      if (body.status === "approved" && body.agentId && body.token) {
+        return { token: body.token, agentId: body.agentId };
+      }
+      if (body.status === "denied") {
+        throw new RegistrationDeniedError("Registration denied by the operator.");
+      }
+    } else if (pollRes.status === 202) {
+      // Still pending — fire callback and loop
+      opts.onPending?.(registrationId, attempt);
+    } else if (pollRes.status === 410) {
+      const body = await pollRes.json().catch(() => ({}) as Record<string, unknown>) as { status?: string };
+      throw new RegistrationDeniedError(
+        `Registration ${body.status ?? "denied/consumed"} — it can no longer be approved.`,
+      );
+    } else if (pollRes.status === 404) {
+      throw new RegistrationExpiredError(
+        "Registration expired (404). Try registering again.",
+      );
+    } else {
+      throw new Error(`Unexpected poll status ${pollRes.status}.`);
+    }
+  }
+
+  throw new RegistrationTimeoutError(
+    `Timed out after ${Math.round(timeoutMs / 1000)}s. ` +
+    `The request may still be pending in the wiki-viewer AI Panel (id: ${registrationId}).`,
+  );
+}
+
+// ── Typed errors ──────────────────────────────────────────────────────────────
+
+export class RegistrationDeniedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistrationDeniedError";
+  }
+}
+
+export class RegistrationExpiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistrationExpiredError";
+  }
+}
+
+export class RegistrationTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistrationTimeoutError";
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,45 @@
+/**
+ * Per-path cache for last-known file metadata from GET responses.
+ * Drives If-Match and collab-state checks on subsequent writes.
+ */
+
+export type CollabState = "active" | "tracked" | "untracked" | "not-markdown";
+
+export interface PathState {
+  /** sha256 from ETag header (without quotes) */
+  sha256: string;
+  collabState: CollabState;
+  /** X-Collab-Revision value, null for non-markdown */
+  collabRevision: number | null;
+  /** X-Collab-Snapshot URL, null for non-markdown */
+  collabSnapshot: string | null;
+  /** When this cache entry was last updated (ms) */
+  fetchedAt: number;
+}
+
+const cache = new Map<string, PathState>();
+
+export function set(path: string, state: PathState): void {
+  cache.set(normalisePath(path), state);
+}
+
+export function get(path: string): PathState | undefined {
+  return cache.get(normalisePath(path));
+}
+
+export function del(path: string): void {
+  cache.delete(normalisePath(path));
+}
+
+export function rename(from: string, to: string): void {
+  const s = cache.get(normalisePath(from));
+  if (s) {
+    cache.delete(normalisePath(from));
+    cache.set(normalisePath(to), s);
+  }
+}
+
+/** Normalise leading slash away so 'foo/bar' and '/foo/bar' are the same key */
+function normalisePath(p: string): string {
+  return p.replace(/^\/+/, "");
+}

package/.next/standalone/packages/wiki-viewer-mcp/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__", "dist", "node_modules"]
+}

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

@@ -23,9 +23,18 @@ importers:
       kysely:
         specifier: 0.28.5
         version: 0.28.5
+      next:
+        specifier: 16.2.4
+        version: 16.2.4(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       proper-lockfile:
         specifier: ^4.1.2
         version: 4.1.2
+      react:
+        specifier: 19.2.5
+        version: 19.2.5
+      react-dom:
+        specifier: 19.2.5
+        version: 19.2.5(react@19.2.5)
       rehype-parse:
         specifier: ^9.0.1
         version: 9.0.1
@@ -210,9 +219,6 @@ importers:
       mermaid:
         specifier: ^11.14.0
         version: 11.15.0
-      next:
-        specifier: 16.2.4
-        version: 16.2.4(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
       next-themes:
         specifier: ^0.4.6
         version: 0.4.6(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
@@ -225,12 +231,6 @@ importers:
       pptx-preview:
         specifier: ^1.0.7
         version: 1.0.7
-      react:
-        specifier: 19.2.5
-        version: 19.2.5
-      react-dom:
-        specifier: 19.2.5
-        version: 19.2.5(react@19.2.5)
       react-markdown:
         specifier: ^10.1.0
         version: 10.1.0(@types/react@19.2.14)(react@19.2.5)

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

@@ -21,6 +21,7 @@ import { idempotency } from "@/lib/proof/idempotency";
 import { getRootDir, safeRootPath } from "@/lib/root-dir";
 import type { Op } from "@/lib/proof/types";
 import { checkAndConsume } from "@/lib/proof/rate-limit";
+import { computeCollabState } from "@/lib/proof/collab-state";
 
 export const runtime = "nodejs";
 
@@ -67,7 +68,16 @@ export async function GET(
 		return NextResponse.json({ error: "NOT_FOUND", message: "File not found" }, { status: 404 });
 	}
 
-	return NextResponse.json(snapshot);
+	const collab = await computeCollabState(rootDir, rel);
+	const collabHeaders: Record<string, string> = {
+		"X-Collab-State": collab.state,
+		"X-Collab-Revision": String(collab.revision),
+	};
+	if (collab.snapshotUrl) {
+		collabHeaders["X-Collab-Snapshot"] = collab.snapshotUrl;
+	}
+
+	return NextResponse.json(snapshot, { headers: collabHeaders });
 }
 
 export async function POST(

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

@@ -0,0 +1,344 @@
+/**
+ * Tier-1 Raw FS — file read/write/delete.
+ *
+ * GET    /api/agent/fs/file/<path>          Read raw bytes (Range supported).
+ * PUT    /api/agent/fs/file/<path>          Atomic whole-file write.
+ * DELETE /api/agent/fs/file/<path>          Delete file (+ sidecar for .md).
+ */
+export const runtime = "nodejs";
+
+import { readFile, stat, unlink, rm } from "node:fs/promises";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { checkAuth, enforceScope } from "@/lib/proof/auth";
+import { getRootDir, safeRootPath } from "@/lib/root-dir";
+import { withFileMutex } from "@/lib/proof/mutex";
+import { readSidecar, emptySidecar, deleteSidecar } from "@/lib/proof/sidecar";
+import { reconcileSidecar } from "@/lib/proof/ops-applier";
+import { writeAuditRow } from "@/lib/proof/audit";
+import {
+	safeAbsPath,
+	sha256ofBuf,
+	extractShaHex,
+	mimeByExt,
+	isMarkdown,
+	atomicWrite,
+	ensureParentDir,
+} from "@/lib/proof/raw-fs";
+import { computeCollabState } from "@/lib/proof/collab-state";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function rel(segments: string[]): string {
+	return segments.join("/");
+}
+
+function errJson(code: string, message: string, status: number): NextResponse {
+	return NextResponse.json({ error: code, message }, { status });
+}
+
+// ── GET ──────────────────────────────────────────────────────────────────────
+
+export async function GET(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): 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 basic = safeRootPath(relPath);
+	if (!basic) return errJson("INVALID_PATH", "Path traversal rejected", 400);
+
+	const absPath = await safeAbsPath(relPath);
+	if (!absPath) return errJson("INVALID_PATH", "Path rejected (symlink escape or denied)", 400);
+
+	const scope = enforceScope(auth.agent, { filePath: relPath, op: "read" });
+	if (!scope.ok) return errJson(scope.code, scope.message, 403);
+
+	let data: Buffer;
+	let fileStat: Awaited<ReturnType<typeof stat>>;
+	try {
+		[data, fileStat] = await Promise.all([readFile(absPath), stat(absPath)]);
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+			return errJson("NOT_FOUND", "File not found", 404);
+		}
+		throw e;
+	}
+
+	if (fileStat.isDirectory()) {
+		return errJson("IS_DIRECTORY", "Path is a directory; use /api/agent/fs/ls/", 400);
+	}
+
+	const sha = sha256ofBuf(data);
+	const baseHeaders: Record<string, string> = {
+		"ETag": `"${sha}"`,
+		"X-File-Size": String(fileStat.size),
+		"X-File-Mtime": fileStat.mtime.toISOString(),
+		"Content-Type": mimeByExt(relPath),
+		"Accept-Ranges": "bytes",
+	};
+
+	// X-Collab-* headers (§3.5 mode signal)
+	const rootDir = getRootDir();
+	const collab = await computeCollabState(rootDir, relPath);
+	if (collab.state !== "not-markdown") {
+		baseHeaders["X-Collab-State"] = collab.state;
+		baseHeaders["X-Collab-Revision"] = String(collab.revision);
+		baseHeaders["X-Collab-Snapshot"] = collab.snapshotUrl!;
+	} else {
+		baseHeaders["X-Collab-State"] = collab.state;
+	}
+
+	const rangeHeader = req.headers.get("range");
+	if (rangeHeader) {
+		const match = /^bytes=(\d+)-(\d*)$/.exec(rangeHeader);
+		if (!match) {
+			return new NextResponse("Invalid Range header", { status: 416 });
+		}
+		const start = parseInt(match[1]!, 10);
+		const endRaw = match[2] ? parseInt(match[2], 10) : data.length - 1;
+		if (start > endRaw || start >= data.length) {
+			return new NextResponse(null, {
+				status: 416,
+				headers: { "Content-Range": `bytes */${data.length}` },
+			});
+		}
+		const end = Math.min(endRaw, data.length - 1);
+		const slice = data.slice(start, end + 1);
+		return new NextResponse(slice as unknown as BodyInit, {
+			status: 206,
+			headers: {
+				...baseHeaders,
+				"Content-Range": `bytes ${start}-${end}/${data.length}`,
+				"Content-Length": String(slice.length),
+			},
+		});
+	}
+
+	return new NextResponse(data as unknown as BodyInit, {
+		status: 200,
+		headers: { ...baseHeaders, "Content-Length": String(data.length) },
+	});
+}
+
+// ── PUT ──────────────────────────────────────────────────────────────────────
+
+export async function PUT(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): 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";
+	const force = url.searchParams.get("force") === "true";
+
+	const basic = safeRootPath(relPath);
+	if (!basic) return errJson("INVALID_PATH", "Path traversal rejected", 400);
+
+	const absPath = await safeAbsPath(relPath);
+	if (!absPath) return errJson("INVALID_PATH", "Path rejected (symlink escape or denied)", 400);
+
+	const scope = enforceScope(auth.agent, { filePath: relPath, op: "mutate" });
+	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;
+	}
+
+	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) {
+			const provided = extractShaHex(ifMatch);
+			const current = extractShaHex(existingSha!);
+			if (provided !== current) {
+				return errJson("PRECONDITION_FAILED", "If-Match sha256 mismatch", 412);
+			}
+		}
+	} 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)
+			const { state, revision, snapshotUrl } = await computeCollabState(rootDir, relPath);
+			if (state === "active") {
+				const matchVal = ifCollabMatch?.trim();
+				if (!force && (!matchVal || matchVal !== String(revision))) {
+					return NextResponse.json(
+						{
+							error: "COLLAB_ACTIVE",
+							message:
+								"File is in active collaborative session. Use block-ops (Tier-2) or supply a matching If-Collab-Match header. Use ?force=true to override (audited).",
+							snapshotUrl,
+							revision,
+						},
+						{ status: 409 },
+					);
+				}
+			}
+
+			await atomicWrite(absPath, bodyBuf);
+
+			const content = bodyBuf.toString("utf-8");
+			const sidecar = (await readSidecar(rootDir, relPath)) ?? emptySidecar(relPath);
+			await reconcileSidecar({
+				rootDir,
+				mdPath: relPath,
+				content,
+				sidecar,
+				by: auth.agent.id,
+				eventType: "file.rawWritten",
+				fingerprint: newSha,
+			});
+
+			writeAuditRow({
+				agentId: auth.agent.id,
+				op: "put",
+				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,
+			});
+		});
+	}
+
+	// Non-.md: atomic write + audit (no mutex, no sidecar)
+	await atomicWrite(absPath, bodyBuf);
+	writeAuditRow({
+		agentId: auth.agent.id,
+		op: "put",
+		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,
+	});
+}
+
+// ── DELETE ───────────────────────────────────────────────────────────────────
+
+export async function DELETE(
+	req: Request,
+	{ params }: { params: Promise<{ path: string[] }> },
+): 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 recursive = url.searchParams.get("recursive") === "true";
+
+	const basic = safeRootPath(relPath);
+	if (!basic) return errJson("INVALID_PATH", "Path traversal rejected", 400);
+
+	const absPath = await safeAbsPath(relPath);
+	if (!absPath) return errJson("INVALID_PATH", "Path rejected (symlink escape or denied)", 400);
+
+	// Requires "delete" scope op
+	const scope = enforceScope(auth.agent, { filePath: relPath, op: "delete" });
+	if (!scope.ok) return errJson(scope.code, scope.message, 403);
+
+	const ifMatch = req.headers.get("if-match");
+
+	let fileStat: Awaited<ReturnType<typeof stat>>;
+	try {
+		fileStat = await stat(absPath);
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+			return errJson("NOT_FOUND", "File not found", 404);
+		}
+		throw e;
+	}
+
+	if (fileStat.isDirectory()) {
+		if (!recursive) {
+			return errJson("IS_DIRECTORY", "Use ?recursive=true to delete a directory", 400);
+		}
+		// Directory delete — no single sha, skip If-Match; require recursive flag as confirmation
+		await rm(absPath, { recursive: true, force: true });
+		writeAuditRow({ agentId: auth.agent.id, op: "delete", path: relPath, forced: false });
+		return NextResponse.json({ deleted: relPath });
+	}
+
+	// File: If-Match required as confirmation
+	if (!ifMatch) {
+		return errJson("PRECONDITION_REQUIRED", "If-Match header required for delete", 412);
+	}
+
+	const existing = await readFile(absPath);
+	const existingSha = sha256ofBuf(existing);
+	if (extractShaHex(ifMatch) !== extractShaHex(existingSha)) {
+		return errJson("PRECONDITION_FAILED", "If-Match sha256 mismatch", 412);
+	}
+
+	const rootDir = getRootDir();
+
+	if (isMarkdown(relPath)) {
+		await withFileMutex(relPath, async () => {
+			await unlink(absPath);
+			await deleteSidecar(rootDir, relPath);
+		});
+	} else {
+		await unlink(absPath);
+	}
+
+	writeAuditRow({ agentId: auth.agent.id, op: "delete", path: relPath, oldSha: existingSha, forced: false });
+	return NextResponse.json({ deleted: relPath });
+}