wiki-viewer 1.4.3 → 1.5.0

package/.next/standalone/src/components/ai-panel/ai-panel.tsx

@@ -68,8 +68,36 @@ export function AIPanel({ currentPath }: { currentPath?: string | null }) {
 		() => bootstrapPrompt.replace(/\$WIKI_URL/g, origin),
 		[bootstrapPrompt, origin]
 	);
+	const getMcpRegister = useCallback(
+		() =>
+			`npx wiki-viewer-mcp register --url ${origin} --id ai:myagent --name "My Agent"`,
+		[origin]
+	);
+	const getMcpJson = useCallback(
+		() =>
+			JSON.stringify(
+				{
+					servers: {
+						"wiki-viewer": {
+							command: "npx",
+							args: ["wiki-viewer-mcp"],
+							env: {
+								WIKI_VIEWER_URL: origin,
+								WIKI_VIEWER_TOKEN: "<token from register>",
+								WIKI_VIEWER_AGENT_ID: "ai:myagent",
+							},
+						},
+					},
+				},
+				null,
+				2
+			),
+		[origin]
+	);
 	const skillCli = useCopyButton(getSkillCli);
 	const bootstrapCopy = useCopyButton(getBootstrapPrompt);
+	const mcpRegister = useCopyButton(getMcpRegister);
+	const mcpJson = useCopyButton(getMcpJson);
 
 	// Keyboard: Esc closes
 	useEffect(() => {
@@ -182,6 +210,27 @@ export function AIPanel({ currentPath }: { currentPath?: string | null }) {
 							Install for AI Agents
 						</h3>
 						<div className="rounded-md border border-border bg-muted/40 p-3 space-y-3">
+							<div className="space-y-1">
+								<p className="text-[10px] text-muted-foreground/70">
+									MCP server <span className="text-muted-foreground/50">(Claude Code, Cursor, Codex):</span>
+								</p>
+								<p className="text-[10px] text-muted-foreground/50">1. Register &amp; get a token:</p>
+								<div className="flex items-center gap-2">
+									<code className="flex-1 text-[10px] font-mono text-foreground/80 truncate bg-muted rounded px-1 py-0.5">
+										{getMcpRegister()}
+									</code>
+									<Button size="sm" variant="ghost" className="h-6 w-6 p-0 shrink-0" title="Copy register command" onClick={() => void mcpRegister.copy()}>
+										{mcpRegister.copied ? <Check className="h-3.5 w-3.5 text-green-500" /> : <Copy className="h-3.5 w-3.5" />}
+									</Button>
+								</div>
+								<p className="text-[10px] text-muted-foreground/50 pt-1">2. Approve below, then add to your <code className="bg-muted px-0.5 rounded">mcp.json</code>:</p>
+								<Button size="sm" variant="outline" className="h-7 w-full text-xs gap-1.5" onClick={() => void mcpJson.copy()}>
+									{mcpJson.copied
+										? <><Check className="h-3.5 w-3.5 text-green-500" /> Copied!</>
+										: <><Copy className="h-3.5 w-3.5" /> Copy mcp.json</>}
+								</Button>
+							</div>
+							<div className="h-px bg-border/60" />
 							<div className="space-y-1">
 								<p className="text-[10px] text-muted-foreground/70">Agent Skills standard:</p>
 								<div className="flex items-center gap-2">

package/.next/standalone/src/components/editor/editor.tsx

@@ -184,6 +184,44 @@ export function KBEditor() {
 		void useProofStore.getState().loadSidecar(currentPath);
 	}, [currentPath]);
 
+	// Human edit-lease heartbeat: tell the server a human has this markdown doc
+	// open so computeCollabState() reports "active" even before the first
+	// suggestion/comment. This is what makes raw-fs writes from agents defer to
+	// the collaborative (Tier-2) path while a human is editing. Only markdown
+	// files participate in the collab-state machine.
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		if (!currentPath) return;
+		if (!/\.(md|markdown)$/i.test(currentPath)) return;
+
+		const path = currentPath;
+		const ping = (action: "open" | "heartbeat" | "close") => {
+			// keepalive lets the "close" beacon survive page unload.
+			void fetch("/api/wiki/presence", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ path, action }),
+				keepalive: action === "close",
+			}).catch(() => {
+				/* presence is best-effort; ignore failures */
+			});
+		};
+
+		ping("open");
+		// Refresh well within the 90s server lease TTL.
+		const id = setInterval(() => ping("heartbeat"), 30_000);
+		const onHidden = () => {
+			if (document.visibilityState === "hidden") ping("heartbeat");
+		};
+		document.addEventListener("visibilitychange", onHidden);
+
+		return () => {
+			clearInterval(id);
+			document.removeEventListener("visibilitychange", onHidden);
+			ping("close");
+		};
+	}, [currentPath]);
+
 	// Subscribe to chokidar SSE: when current file changes on disk, reload sidecar.
 	useEffect(() => {
 		if (typeof window === "undefined") return;

package/.next/standalone/src/lib/proof/audit.ts

@@ -0,0 +1,79 @@
+/**
+ * Minimal durable audit log for raw-fs mutations (Tier 1).
+ *
+ * Uses the same ~/.wiki-viewer/auth.db already opened by better-auth.
+ * Table: agent_fs_audit
+ *
+ * For .md files the sidecar event covers provenance; this covers ALL types.
+ */
+import Database from "better-sqlite3";
+import path from "node:path";
+import os from "node:os";
+import { mkdirSync } from "node:fs";
+
+function dataDir(): string {
+	return path.join(process.env.HOME ?? os.homedir(), ".wiki-viewer");
+}
+
+// Lazily initialised so tests can set HOME before first import.
+let _db: InstanceType<typeof Database> | null = null;
+
+function getDb(): InstanceType<typeof Database> {
+	if (_db) return _db;
+	const dir = dataDir();
+	mkdirSync(dir, { recursive: true });
+	const dbPath = path.join(dir, "auth.db");
+	_db = new Database(dbPath);
+	_db.pragma("journal_mode = WAL");
+	_db.exec(`
+		CREATE TABLE IF NOT EXISTS agent_fs_audit (
+			id      INTEGER PRIMARY KEY AUTOINCREMENT,
+			agent_id TEXT NOT NULL,
+			op      TEXT NOT NULL,
+			path    TEXT NOT NULL,
+			old_sha TEXT,
+			new_sha TEXT,
+			forced  INTEGER NOT NULL DEFAULT 0,
+			at      TEXT NOT NULL
+		)
+	`);
+	return _db;
+}
+
+export interface AuditRow {
+	agentId: string;
+	op: string;
+	path: string;
+	oldSha?: string;
+	newSha?: string;
+	forced?: boolean;
+}
+
+/**
+ * Write one audit row synchronously (SQLite sync is fine here — it's a WAL journal append).
+ * Fire-and-forget: never throws; logs to stderr on error.
+ */
+export function writeAuditRow(row: AuditRow): void {
+	try {
+		const db = getDb();
+		db.prepare(
+			`INSERT INTO agent_fs_audit (agent_id, op, path, old_sha, new_sha, forced, at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		).run(
+			row.agentId,
+			row.op,
+			row.path,
+			row.oldSha ?? null,
+			row.newSha ?? null,
+			row.forced ? 1 : 0,
+			new Date().toISOString(),
+		);
+	} catch (e) {
+		console.error("[agent-fs audit] write failed:", e);
+	}
+}
+
+/** Reset cached DB handle (used by tests to pick up new HOME). */
+export function _resetAuditDb(): void {
+	_db = null;
+}

package/.next/standalone/src/lib/proof/auth.ts

@@ -34,7 +34,7 @@ export async function checkAuth(req: Request): Promise<CheckAuthResult> {
 				id: `user:${u.id}`,
 				displayName: u.name,
 				tokenHash: "",
-				scope: { paths: ["**/*"], ops: ["read", "mutate"] },
+				scope: { paths: ["**/*"], ops: ["read", "mutate", "delete"] },
 				createdAt: "",
 				lastSeen: "",
 			},
@@ -71,7 +71,7 @@ export async function checkAuth(req: Request): Promise<CheckAuthResult> {
 
 export interface ScopeParams {
 	filePath?: string;
-	op: "read" | "mutate";
+	op: "read" | "mutate" | "delete";
 }
 
 export function enforceScope(

package/.next/standalone/src/lib/proof/collab-state.ts

@@ -0,0 +1,79 @@
+/**
+ * Collab-state computation for §3.5 Working mode vs Collaborating mode.
+ *
+ * Returns:
+ *   state     — "active" | "tracked" | "untracked" | "not-markdown"
+ *   revision  — X-Collab-Revision (sidecar.revision + leaseGeneration(path))
+ *   snapshotUrl — Tier-2 snapshot URL (null for non-markdown)
+ *
+ * Revision formula:
+ *   revision = (sidecar?.revision ?? 0) + leaseGeneration(relPath)
+ *
+ *   sidecar.revision bumps on every collab write (block-ops, comment, suggestion).
+ *   leaseGeneration bumps on every lease open/close.
+ *   Together they form a monotonically-non-decreasing integer that changes
+ *   whenever collab state could change.  A raw PUT that supplies
+ *   If-Collab-Match: <n> is only safe when n equals the revision computed
+ *   atomically inside the write mutex — otherwise 409 COLLAB_ACTIVE.
+ *
+ * active = has artifacts (pendingSuggestions > 0 OR unresolvedComments > 0
+ *          OR blockProvenance entries > 0) OR has a current human edit lease.
+ */
+
+import { readSidecar } from "./sidecar";
+import { hasActiveLease, leaseGeneration } from "./lease";
+
+function isMarkdownPath(p: string): boolean {
+	return p.endsWith(".md") || p.endsWith(".markdown");
+}
+
+export type CollabState = "active" | "tracked" | "untracked" | "not-markdown";
+
+export interface CollabStateResult {
+	state: CollabState;
+	/** sidecar.revision + leaseGeneration(relPath) */
+	revision: number;
+	/** /api/agent/files/<relPath> — null for not-markdown */
+	snapshotUrl: string | null;
+}
+
+export async function computeCollabState(
+	rootDir: string,
+	relPath: string,
+): Promise<CollabStateResult> {
+	if (!isMarkdownPath(relPath)) {
+		return { state: "not-markdown", revision: 0, snapshotUrl: null };
+	}
+
+	const snapshotUrl = `/api/agent/files/${relPath}`;
+
+	// Compute revision components
+	const sidecar = await readSidecar(rootDir, relPath);
+	const gen = leaseGeneration(relPath);
+	const sidecarRevision = sidecar?.revision ?? 0;
+	const revision = sidecarRevision + gen;
+
+	// Lease check — do after reading sidecar to keep gen stable within this call
+	const leaseActive = hasActiveLease(relPath);
+
+	if (!sidecar && !leaseActive) {
+		return { state: "untracked", revision, snapshotUrl };
+	}
+
+	if (leaseActive) {
+		return { state: "active", revision, snapshotUrl };
+	}
+
+	// Has sidecar, no lease — inspect artifacts
+	const pendingSuggestions = sidecar!.suggestions.filter(
+		(s) => s.status === "pending" && !s.stale,
+	).length;
+	const unresolvedComments = sidecar!.comments.filter((c) => !c.resolved).length;
+	const proofSpanCount = Object.keys(sidecar!.blockProvenance ?? {}).length;
+
+	if (pendingSuggestions > 0 || unresolvedComments > 0 || proofSpanCount > 0) {
+		return { state: "active", revision, snapshotUrl };
+	}
+
+	return { state: "tracked", revision, snapshotUrl };
+}

package/.next/standalone/src/lib/proof/lease.ts

@@ -0,0 +1,104 @@
+/**
+ * Human edit-lease store (in-memory, globalThis for hot-reload survival).
+ *
+ * A lease is set when a human opens a .md doc in the editor and refreshed
+ * via heartbeat while the doc stays open.  Its presence makes collab-state
+ * "active" even before the human has typed a single suggestion (closes the
+ * false-negative GPT-5.5 caught in the design review).
+ *
+ * TTL: LEASE_TTL_MS (default 90 s). Editor should heartbeat every ~30 s.
+ *
+ * Collab-generation counter:
+ *   - Starts at 0 per path.
+ *   - Increments on EVERY 0→1 transition (first setLease, or setLease after
+ *     all prior leases expired) AND on every 1→0 transition (clearLease or
+ *     expiry-on-read).
+ *   - X-Collab-Revision = sidecar.revision + leaseGeneration(path).
+ *     Any lease or sidecar state change therefore bumps the combined revision.
+ */
+
+export const LEASE_TTL_MS = 90_000;
+
+interface LeaseEntry {
+	userId: string;
+	expiresAt: number;
+}
+
+interface LeaseStore {
+	leases: Map<string, LeaseEntry>;
+	generations: Map<string, number>;
+}
+
+const g = globalThis as typeof globalThis & { __wikiLeaseStore?: LeaseStore };
+if (!g.__wikiLeaseStore) {
+	g.__wikiLeaseStore = { leases: new Map(), generations: new Map() };
+}
+
+function store(): LeaseStore {
+	return g.__wikiLeaseStore!;
+}
+
+/** True if relPath has a non-expired lease RIGHT NOW (lazy-sweeps on check). */
+function isLeaseActiveInternal(relPath: string): boolean {
+	const s = store();
+	const entry = s.leases.get(relPath);
+	if (!entry) return false;
+	if (Date.now() >= entry.expiresAt) {
+		s.leases.delete(relPath);
+		// 1→0 transition: bump generation
+		s.generations.set(relPath, (s.generations.get(relPath) ?? 0) + 1);
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Set (or refresh) a lease for relPath by userId.
+ * Bumps the generation counter on a 0→1 transition.
+ */
+export function setLease(relPath: string, userId: string, ttlMs = LEASE_TTL_MS): void {
+	const s = store();
+	const wasActive = isLeaseActiveInternal(relPath);
+	s.leases.set(relPath, { userId, expiresAt: Date.now() + ttlMs });
+	if (!wasActive) {
+		// 0→1 transition: bump generation
+		s.generations.set(relPath, (s.generations.get(relPath) ?? 0) + 1);
+	}
+}
+
+/** True if relPath has a current non-expired lease. */
+export function hasActiveLease(relPath: string): boolean {
+	return isLeaseActiveInternal(relPath);
+}
+
+/**
+ * Clear the lease for relPath (on doc close).
+ * Only clears if the existing lease belongs to userId.
+ * Bumps generation on removal.
+ */
+export function clearLease(relPath: string, userId: string): void {
+	const s = store();
+	const entry = s.leases.get(relPath);
+	if (!entry) return;
+	// Still clear expired leases owned by the same user
+	if (entry.userId === userId) {
+		s.leases.delete(relPath);
+		// 1→0 transition: bump generation
+		s.generations.set(relPath, (s.generations.get(relPath) ?? 0) + 1);
+	}
+}
+
+/**
+ * Returns the monotonic-ish collab generation for relPath.
+ * Increments on every 0→1 and 1→0 lease transition.
+ */
+export function leaseGeneration(relPath: string): number {
+	return store().generations.get(relPath) ?? 0;
+}
+
+/** Reset store — for tests only. */
+export function _resetLeaseStore(): void {
+	const s = store();
+	s.leases.clear();
+	s.generations.clear();
+}

package/.next/standalone/src/lib/proof/ops-applier.ts

@@ -103,6 +103,20 @@ function opMarkdownToBlocks(
 	return { nodes, refs };
 }
 
+function markOrphanedRefsStale(sidecar: Sidecar, newRefMap: Record<string, unknown>): void {
+	const validRefs = new Set(Object.keys(newRefMap));
+	for (const s of sidecar.suggestions) {
+		if (s.status === "pending" && !validRefs.has(s.ref)) {
+			s.stale = true;
+		}
+	}
+	for (const c of sidecar.comments) {
+		if (!c.resolved && !validRefs.has(c.ref)) {
+			c.stale = true;
+		}
+	}
+}
+
 function buildSnapshot(
 	mdPath: string,
 	blocks: Block[],
@@ -121,6 +135,49 @@ function buildSnapshot(
 	};
 }
 
+/**
+ * Reconcile a sidecar after a file was modified outside of block-ops.
+ * Rebuilds refMap, bumps revision, marks orphaned anchors stale, emits event, writes sidecar.
+ *
+ * Callers MUST hold `withFileMutex(mdPath, ...)` before calling.
+ *
+ * Used by:
+ *   - readSnapshot: eventType="file.externallyEdited", by="system"
+ *   - raw-fs PUT (Phase 2): eventType="file.rawWritten", by="ai:<id>"
+ */
+export async function reconcileSidecar(args: {
+	rootDir: string;
+	mdPath: string;
+	content: string;
+	sidecar: Sidecar; // mutated in place
+	by: string;
+	eventType: string;
+	fingerprint: string; // pre-computed sha256 of content
+}): Promise<{ snapshot: Snapshot; blocks: Block[] }> {
+	const { rootDir, mdPath, content, sidecar, by, eventType, fingerprint } = args;
+	const nodes = parseBlocks(content);
+	const { blocks, newRefMap } = assignRefs(nodes, sidecar);
+	const oldFingerprint = sidecar.fingerprint;
+	sidecar.refMap = newRefMap;
+	sidecar.revision += 1;
+	sidecar.updatedAt = nowIso();
+	sidecar.fingerprint = fingerprint;
+	markOrphanedRefsStale(sidecar, newRefMap);
+	const eventPayload: Omit<ProofEvent, "id"> & Record<string, unknown> = {
+		type: eventType,
+		at: nowIso(),
+		by,
+		fingerprint,
+	};
+	if (eventType === "file.rawWritten") {
+		eventPayload.oldSha = oldFingerprint;
+		eventPayload.newSha = fingerprint;
+	}
+	emitEvents(sidecar, [eventPayload as Omit<ProofEvent, "id">]);
+	await writeSidecar(rootDir, mdPath, sidecar);
+	return { snapshot: buildSnapshot(mdPath, blocks, sidecar), blocks };
+}
+
 /**
  * Pure read: load file, parse blocks, assign refs, return snapshot.
  * Detects external edits (fingerprint mismatch) and records them in the sidecar.
@@ -156,20 +213,16 @@ export async function readSnapshot(
 			const freshFingerprint = sha256file(freshContent);
 
 			if (freshSidecar.fingerprint && freshSidecar.fingerprint !== freshFingerprint) {
-				const freshNodes = parseBlocks(freshContent);
-				const { blocks: freshBlocks, newRefMap } = assignRefs(freshNodes, freshSidecar);
-				freshSidecar.refMap = newRefMap;
-				freshSidecar.revision += 1;
-				freshSidecar.updatedAt = nowIso();
-				freshSidecar.fingerprint = freshFingerprint;
-				emitEvents(freshSidecar, [{
-					type: "file.externallyEdited",
-					at: nowIso(),
+				const { snapshot } = await reconcileSidecar({
+					rootDir,
+					mdPath,
+					content: freshContent,
+					sidecar: freshSidecar,
 					by: "system",
+					eventType: "file.externallyEdited",
 					fingerprint: freshFingerprint,
-				}]);
-				await writeSidecar(rootDir, mdPath, freshSidecar);
-				return buildSnapshot(mdPath, freshBlocks, freshSidecar);
+				});
+				return snapshot;
 			}
 
 			// Another writer already updated — just build snapshot from current state
@@ -233,28 +286,24 @@ export async function applyOps(args: {
 
 		const isAi = by.startsWith("ai:");
 
-		// Detect external edits
+		// Detect external edits — reconcile eagerly inside the mutex (R2: do not let lazy reconcile miss)
 		if (sidecar.fingerprint && sidecar.fingerprint !== fingerprint) {
-			const nodes = parseBlocks(content);
-			const { blocks: freshBlocks, newRefMap } = assignRefs(nodes, sidecar);
-			sidecar.refMap = newRefMap;
-			sidecar.revision += 1;
-			sidecar.updatedAt = nowIso();
-			sidecar.fingerprint = fingerprint;
-			emitEvents(sidecar, [{
-				type: "file.externallyEdited",
-				at: nowIso(),
+			const { snapshot: freshSnapshot } = await reconcileSidecar({
+				rootDir,
+				mdPath,
+				content,
+				sidecar,
 				by: "system",
+				eventType: "file.externallyEdited",
 				fingerprint,
-			}]);
-			await writeSidecar(rootDir, mdPath, sidecar);
+			});
 			// Return STALE_REVISION so caller knows to re-fetch
 			return {
 				ok: false,
 				status: 409,
 				code: "STALE_REVISION",
 				message: "File was externally edited. Fetch the new snapshot and retry.",
-				snapshot: buildSnapshot(mdPath, freshBlocks, sidecar),
+				snapshot: freshSnapshot,
 			};
 		}