wiki-viewer 1.0.0 → 1.0.1

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

@@ -0,0 +1,170 @@
+export type BlockType =
+	| "heading"
+	| "paragraph"
+	| "bulletList"
+	| "orderedList"
+	| "taskList"
+	| "blockquote"
+	| "codeBlock"
+	| "table"
+	| "hr"
+	| "html";
+
+export interface Block {
+	ref: string; // "b" + 6-hex
+	type: BlockType;
+	level?: number; // headings only
+	lang?: string; // codeBlock only
+	markdown: string; // canonical markdown for this block, trailing \n stripped
+}
+
+export interface ProvenanceMeta {
+	origin: "human" | "ai";
+	basis?: "described" | "inferred" | "suggested";
+	basisDetail?: string;
+	by?: string; // "ai:claude" or "human"
+	at?: string; // ISO 8601
+	spanId: string; // "p" + 4-hex
+	inResponseTo?: string; // comment id
+}
+
+export interface CommentTurn {
+	by: string; // "human" | "ai:claude"
+	text: string;
+	at: string;
+}
+
+export interface Comment {
+	id: string; // "c" + 4-hex
+	ref: string; // block ref it's attached to
+	resolved: boolean;
+	createdAt: string;
+	turns: CommentTurn[];
+}
+
+export type SuggestionKind =
+	| "replace"
+	| "insertAfter"
+	| "insertBefore"
+	| "delete";
+export type SuggestionStatus = "pending" | "accepted" | "rejected";
+
+export interface Suggestion {
+	id: string; // "s" + 4-hex
+	ref: string;
+	kind: SuggestionKind;
+	status: SuggestionStatus;
+	by: string;
+	markdown?: string; // omitted for kind=delete
+	basis?: ProvenanceMeta["basis"];
+	basisDetail?: string;
+	createdAt: string;
+	resolvedAt?: string; // when accepted/rejected
+	resolvedBy?: string;
+}
+
+export interface ProofEvent {
+	id: number;
+	type: string; // see §4.6 list
+	at: string;
+	by: string;
+	[k: string]: unknown;
+}
+
+export interface SpanAttrs {
+	spanId: string;
+	origin: "ai" | "human";
+	basis?: string;
+	basisDetail?: string;
+	by: string;
+	at: string;
+	inResponseTo?: string;
+}
+
+export interface Sidecar {
+	schemaVersion: 1;
+	path: string;
+	revision: number;
+	createdAt: string;
+	updatedAt: string;
+	// Map of block.ref -> current text fingerprint (sha256 of block markdown, first 12 hex).
+	refMap: Record<string, { textHash: string; lastSeenAt: string }>;
+	// History of ref renames. Old ref -> new ref, kept for ONE generation.
+	refAliases: Record<string, string>;
+	comments: Comment[];
+	suggestions: Suggestion[];
+	archivedSuggestions: Suggestion[];
+	events: ProofEvent[];
+	nextEventId: number;
+	lastAck: Record<string, number>; // by -> eventId
+	fingerprint: string; // last-known sha256 of the .md file
+	blockProvenance?: Record<string, SpanAttrs>; // for blocks we can't wrap inline
+}
+
+export type Op =
+	| {
+			type: "block.replace";
+			ref: string;
+			markdown: string;
+			basis?: string;
+			basisDetail?: string;
+			inResponseTo?: string;
+	  }
+	| {
+			type: "block.insertAfter";
+			ref: string;
+			markdown: string;
+			basis?: string;
+			basisDetail?: string;
+			inResponseTo?: string;
+	  }
+	| {
+			type: "block.insertBefore";
+			ref: string;
+			markdown: string;
+			basis?: string;
+			basisDetail?: string;
+			inResponseTo?: string;
+	  }
+	| { type: "block.delete"; ref: string }
+	| {
+			type: "block.append";
+			markdown: string;
+			basis?: string;
+			basisDetail?: string;
+			inResponseTo?: string;
+	  }
+	| {
+			type: "block.prepend";
+			markdown: string;
+			basis?: string;
+			basisDetail?: string;
+			inResponseTo?: string;
+	  }
+	| { type: "comment.add"; ref: string; text: string }
+	| { type: "comment.reply"; commentId: string; text: string }
+	| { type: "comment.resolve"; commentId: string }
+	| { type: "comment.reopen"; commentId: string }
+	| {
+			type: "suggestion.add";
+			ref: string;
+			kind: SuggestionKind;
+			markdown?: string;
+			basis?: string;
+			basisDetail?: string;
+			status?: SuggestionStatus;
+	  }
+	| { type: "suggestion.accept"; suggestionId: string }
+	| { type: "suggestion.reject"; suggestionId: string };
+
+export interface Snapshot {
+	path: string;
+	revision: number;
+	createdAt: string;
+	updatedAt: string;
+	fingerprint: string;
+	blocks: Block[];
+	comments: Comment[]; // unresolved + resolved (separately by client)
+	suggestions: Suggestion[]; // pending only by default
+	lastEventId: number;
+}

package/.next/standalone/src/lib/proof-config.ts

@@ -0,0 +1,14 @@
+// Rate limiting: token bucket per "by" agent identity.
+// Bucket size = OPS_PER_MINUTE, refill 1 op/sec.
+export const OPS_PER_MINUTE = (() => {
+	const v = parseInt(process.env.AGENT_RATE_LIMIT ?? "", 10);
+	return Number.isFinite(v) && v > 0 ? v : 60;
+})();
+
+// Max events to return from a single poll.
+export const EVENTS_MAX_LIMIT = 1000;
+export const EVENTS_DEFAULT_LIMIT = 100;
+
+// Sidecar event trimming: keep last N events (but never below oldest ack cursor).
+export const SIDECAR_EVENT_TRIM_SIZE = 1000;
+export const SIDECAR_TRIM_EVERY_N_MUTATIONS = 100;

package/.next/standalone/src/middleware.ts

@@ -0,0 +1,38 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+// Prefixes the middleware never intercepts. Either they're public, or the route
+// handler itself runs Better Auth / agent bearer auth and returns a proper
+// status (401/403/200) instead of a redirect to /signin.
+const PASSTHROUGH_PREFIXES = [
+	"/signin",
+	"/api/",            // ALL API routes self-gate; middleware never redirects API
+	"/_next",
+	"/icon.svg",
+	"/favicon.ico",
+];
+
+export function middleware(req: NextRequest): NextResponse {
+	const { pathname } = req.nextUrl;
+
+	if (PASSTHROUGH_PREFIXES.some((p) => pathname.startsWith(p))) {
+		return NextResponse.next();
+	}
+
+	// Cheap presence check; real session validation happens in individual routes.
+	// Cookie name from better-auth default: "better-auth.session_token"
+	const sessionCookie =
+		req.cookies.get("better-auth.session_token") ??
+		req.cookies.get("__Secure-better-auth.session_token");
+
+	if (!sessionCookie) {
+		const url = new URL("/signin", req.url);
+		url.searchParams.set("next", pathname);
+		return NextResponse.redirect(url);
+	}
+
+	return NextResponse.next();
+}
+
+export const config = {
+	matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};

package/.next/standalone/src/stores/ai-panel-store.ts

@@ -1,8 +1,14 @@
 "use client";
 import { create } from "zustand";
+import type { ActivityEvent } from "@/lib/proof/activity-shared";
+import { deriveConnections } from "@/lib/proof/activity-shared";
+import { authHeaders } from "@/lib/proof/client-auth";
 
-// Minimal stub. The editor reads open/clearMessages/open from this store.
-// Extend as needed when an AI panel is added to ccmc.
+export interface Connection {
+	by: string;
+	opCount: number;
+	lastSeen: string;
+}
 
 interface AIPanelState {
 	isOpen: boolean;
@@ -10,6 +16,14 @@ interface AIPanelState {
 	close: () => void;
 	toggle: () => void;
 	clearMessages: () => void;
+
+	activity: ActivityEvent[];
+	connections: Connection[];
+	hasToken: boolean;
+	pollIntervalMs: number;
+	rateLimit: number | null;
+
+	loadActivity: () => Promise<void>;
 }
 
 export const useAIPanelStore = create<AIPanelState>((set) => ({
@@ -18,6 +32,47 @@ export const useAIPanelStore = create<AIPanelState>((set) => ({
 	close: () => set({ isOpen: false }),
 	toggle: () => set((s) => ({ isOpen: !s.isOpen })),
 	clearMessages: () => {
-		/* no-op: no messages in stub */
+		/* no-op */
+	},
+
+	activity: [],
+	connections: [],
+	hasToken: false,
+	pollIntervalMs: 10_000,
+	rateLimit: null,
+
+	loadActivity: async () => {
+		const token =
+			typeof window !== "undefined"
+				? (localStorage.getItem("wiki-agent-token") ?? null)
+				: null;
+		const hasToken = !!(token && token.trim());
+
+		try {
+			const res = await fetch("/api/agent/activity?limit=50", {
+				headers: authHeaders(),
+			});
+			if (!res.ok) {
+				set({ hasToken });
+				return;
+			}
+			const data = (await res.json()) as { events: ActivityEvent[] };
+			const activity = data.events ?? [];
+			const connections = deriveConnections(activity);
+
+			// Also fetch rate-limit setting
+			let rateLimit: number | null = null;
+			try {
+				const sr = await fetch("/api/agent/settings", { headers: authHeaders() });
+				if (sr.ok) {
+					const sd = (await sr.json()) as { rateLimit: number };
+					rateLimit = sd.rateLimit ?? null;
+				}
+			} catch { /* ignore */ }
+
+			set({ activity, connections, hasToken, rateLimit });
+		} catch {
+			set({ hasToken });
+		}
 	},
 }));

package/.next/standalone/src/stores/editor-store.ts

@@ -19,6 +19,7 @@ interface PageData {
 	path: string;
 	content: string;
 	frontmatter: FrontMatter | null;
+	revision: number | null;
 }
 
 async function fetchPageFromApi(path: string): Promise<PageData> {
@@ -27,23 +28,57 @@ async function fetchPageFromApi(path: string): Promise<PageData> {
 		throw new FetchPageError(`Failed to fetch page: ${path}`, res.status);
 	}
 	const data: { content: string } = await res.json();
-	return { path, content: data.content, frontmatter: null };
+	const revHeader = res.headers.get("X-Wiki-Revision");
+	const revision = revHeader !== null ? Number(revHeader) : null;
+	return { path, content: data.content, frontmatter: null, revision };
 }
 
-async function savePageToApi(path: string, content: string): Promise<void> {
+interface SaveResult {
+	revision: number | null;
+}
+
+/** Error thrown when the server reports a stale revision (409). */
+export class StaleRevisionError extends Error {
+	constructor(
+		public readonly currentRevision: number,
+		public readonly serverContent: string,
+	) {
+		super("File was modified externally. Reloaded with latest content.");
+		this.name = "StaleRevisionError";
+	}
+}
+
+async function savePageToApi(
+	path: string,
+	content: string,
+	baseRevision: number | null,
+): Promise<SaveResult> {
+	const body: Record<string, unknown> = { path, content };
+	if (baseRevision !== null) body.baseRevision = baseRevision;
 	const res = await fetch("/api/wiki/content", {
 		method: "PUT",
 		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({ path, content }),
+		body: JSON.stringify(body),
 	});
+	if (res.status === 409) {
+		// Server has a newer revision. Fetch current content and surface the conflict.
+		const conflictData = (await res.json()) as { currentRevision?: number };
+		const freshRes = await fetch(`/api/wiki/content?path=${encodeURIComponent(path)}`);
+		const freshContent = freshRes.ok
+			? ((await freshRes.json()) as { content: string }).content
+			: content;
+		throw new StaleRevisionError(conflictData.currentRevision ?? 0, freshContent);
+	}
 	if (!res.ok) {
 		throw new Error("Failed to save page");
 	}
+	const data = (await res.json()) as { revision?: number };
+	return { revision: data.revision ?? null };
 }
 
 async function createPageInApi(path: string, content = ""): Promise<void> {
 	// ccmc has no dedicated create endpoint; saving empty content creates the file.
-	await savePageToApi(path, content);
+	await savePageToApi(path, content, null);
 }
 
 const PAGE_CACHE_KEY = "kb-page-cache";
@@ -78,6 +113,15 @@ function saveCachedPage(page: CachedPage) {
 
 export type LoadStatus = "idle" | "loading" | "ok" | "missing" | "error";
 
+/**
+ * Editor interaction mode.
+ * - "editing": human edits write directly to the file (full-file PUT).
+ * - "suggesting": human block edits are captured as suggestions (block ops,
+ *   by: "human") and the editor block reverts to the snapshot. The file is
+ *   not changed until a suggestion is accepted.
+ */
+export type EditMode = "editing" | "suggesting";
+
 interface EditorState {
 	currentPath: string | null;
 	content: string;
@@ -87,6 +131,10 @@ interface EditorState {
 	isDirty: boolean;
 	isLoading: boolean;
 	lastSavedAt: number | null;
+	/** Last confirmed revision from the server. null until first save/sync. */
+	currentRevision: number | null;
+	/** Current interaction mode. Persisted in localStorage. */
+	editMode: EditMode;
 
 	loadPage: (path: string) => Promise<void>;
 	updateContent: (content: string) => void;
@@ -94,6 +142,19 @@ interface EditorState {
 	save: () => Promise<void>;
 	createMissingPage: (title: string) => Promise<void>;
 	clear: () => void;
+	/** Sync the known revision from an external source (e.g. proof-store snapshot). */
+	syncRevision: (revision: number) => void;
+	/** Switch interaction mode (editing | suggesting). */
+	setEditMode: (mode: EditMode) => void;
+}
+
+const EDIT_MODE_KEY = "kb-edit-mode";
+
+function loadEditMode(): EditMode {
+	if (typeof window === "undefined") return "editing";
+	return localStorage.getItem(EDIT_MODE_KEY) === "suggesting"
+		? "suggesting"
+		: "editing";
 }
 
 let saveTimer: ReturnType<typeof setTimeout> | null = null;
@@ -108,6 +169,15 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 	isDirty: false,
 	isLoading: false,
 	lastSavedAt: null,
+	currentRevision: null,
+	editMode: loadEditMode(),
+
+	setEditMode: (mode: EditMode) => {
+		if (typeof window !== "undefined") {
+			localStorage.setItem(EDIT_MODE_KEY, mode);
+		}
+		set({ editMode: mode });
+	},
 
 	loadPage: async (path: string) => {
 		const currentState = get();
@@ -126,6 +196,7 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 			loadStatus: "loading",
 			isDirty: false,
 			content: "",
+			currentRevision: null,
 		});
 
 		// Paint from cache immediately so the editor feels instant.
@@ -148,6 +219,7 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 				frontmatter: page.frontmatter,
 				isLoading: false,
 				loadStatus: "ok",
+				currentRevision: page.revision,
 			});
 			saveCachedPage({
 				path,
@@ -166,6 +238,13 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 	},
 
 	updateContent: (content: string) => {
+		// In suggesting mode, human edits never write the file directly. They are
+		// captured as suggestions (block ops) and the editor reverts. Skip the
+		// dirty flag + autosave entirely so no full-file PUT is scheduled.
+		if (get().editMode === "suggesting") {
+			set({ content });
+			return;
+		}
 		set({ content, isDirty: true });
 
 		// Auto-save after 500 ms of inactivity.
@@ -188,13 +267,20 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 	},
 
 	save: async () => {
-		const { currentPath, content, isDirty } = get();
+		const { currentPath, content, isDirty, currentRevision, editMode } = get();
 		if (!currentPath || !isDirty) return;
+		// Suggesting mode must never write the file via full-file PUT.
+		if (editMode === "suggesting") return;
 
 		set({ saveStatus: "saving" });
 		try {
-			await savePageToApi(currentPath, content);
-			set({ saveStatus: "saved", isDirty: false, lastSavedAt: Date.now() });
+			const result = await savePageToApi(currentPath, content, currentRevision);
+			set({
+				saveStatus: "saved",
+				isDirty: false,
+				lastSavedAt: Date.now(),
+				currentRevision: result.revision ?? currentRevision,
+			});
 			saveCachedPage({
 				path: currentPath,
 				content,
@@ -205,8 +291,23 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 			statusTimer = setTimeout(() => {
 				if (get().saveStatus === "saved") set({ saveStatus: "idle" });
 			}, 2000);
-		} catch {
-			set({ saveStatus: "error" });
+		} catch (err) {
+			if (err instanceof StaleRevisionError) {
+				// Server has a newer revision: reload editor with fresh content.
+				set({
+					content: err.serverContent,
+					isDirty: false,
+					saveStatus: "error",
+					currentRevision: err.currentRevision,
+				});
+				saveCachedPage({
+					path: currentPath,
+					content: err.serverContent,
+					frontmatter: get().frontmatter,
+				});
+			} else {
+				set({ saveStatus: "error" });
+			}
 		}
 	},
 
@@ -239,6 +340,11 @@ export const useEditorStore = create<EditorState>((set, get) => ({
 			isDirty: false,
 			isLoading: false,
 			lastSavedAt: null,
+			currentRevision: null,
 		});
 	},
+
+	syncRevision: (revision: number) => {
+		set({ currentRevision: revision });
+	},
 }));

package/.next/standalone/src/stores/proof-store.ts

@@ -0,0 +1,123 @@
+import { create } from "zustand";
+import { authHeaders } from "@/lib/proof/client-auth";
+import { useEditorStore } from "@/stores/editor-store";
+import type { Sidecar, ProofEvent, Block, Snapshot } from "@/lib/proof/types";
+
+interface PathEntry {
+	sidecar: Sidecar | null;
+	snapshotRevision: number;
+	lastEventId: number;
+	/** Ordered block list from latest GET snapshot. Used to resolve ref→position in editor. */
+	snapshotBlocks: Block[];
+}
+
+interface ProofState {
+	byPath: Record<string, PathEntry>;
+	loadSidecar(path: string): Promise<void>;
+	/** Fetch GET /api/agent/files/<path> to get ordered block list for ref positioning. */
+	loadSnapshot(path: string): Promise<void>;
+	pollEvents(path: string): Promise<void>;
+	applyEvent(path: string, e: ProofEvent): void;
+	reset(path: string): void;
+}
+
+function defaultEntry(): PathEntry {
+	return { sidecar: null, snapshotRevision: 0, lastEventId: 0, snapshotBlocks: [] };
+}
+
+export const useProofStore = create<ProofState>((set, get) => ({
+	byPath: {},
+
+	loadSidecar: async (path: string) => {
+		const encoded = encodeURIComponent(path).replace(/%2F/g, "/");
+		try {
+			const res = await fetch(`/api/agent/sidecar/${encoded}`, {
+				headers: authHeaders(),
+			});
+			if (!res.ok) return;
+			const sidecar = (await res.json()) as Sidecar;
+			set((s) => ({
+				byPath: {
+					...s.byPath,
+					[path]: {
+						...(s.byPath[path] ?? defaultEntry()),
+						sidecar,
+						snapshotRevision: sidecar.revision,
+						lastEventId: sidecar.nextEventId - 1,
+					},
+				},
+			}));
+		} catch {
+			// network error — leave stale
+		}
+	},
+
+	loadSnapshot: async (path: string) => {
+		const encoded = encodeURIComponent(path).replace(/%2F/g, "/");
+		try {
+			const res = await fetch(`/api/agent/files/${encoded}`, {
+				headers: authHeaders(),
+			});
+			if (!res.ok) return;
+			const snap = (await res.json()) as Snapshot;
+			set((s) => ({
+				byPath: {
+					...s.byPath,
+					[path]: {
+						...(s.byPath[path] ?? defaultEntry()),
+						snapshotBlocks: snap.blocks,
+						snapshotRevision: snap.revision,
+					},
+				},
+			}));
+			// Sync revision into editor-store so saves send correct baseRevision.
+			const editorState = useEditorStore.getState();
+			if (editorState.currentPath === path) {
+				editorState.syncRevision(snap.revision);
+			}
+		} catch {
+			// network error — leave stale
+		}
+	},
+
+	pollEvents: async (path: string) => {
+		const entry = get().byPath[path] ?? defaultEntry();
+		const encoded = encodeURIComponent(path).replace(/%2F/g, "/");
+		try {
+			const res = await fetch(
+				`/api/agent/events/${encoded}?after=${entry.lastEventId}`,
+				{ headers: authHeaders() },
+			);
+			if (!res.ok) return;
+			const data = (await res.json()) as { events: ProofEvent[]; lastEventId: number };
+			for (const e of data.events) {
+				get().applyEvent(path, e);
+			}
+		} catch {
+			// network error — leave stale
+		}
+	},
+
+	applyEvent: (path: string, e: ProofEvent) => {
+		set((s) => {
+			const prev = s.byPath[path] ?? defaultEntry();
+			return {
+				byPath: {
+					...s.byPath,
+					[path]: {
+						...prev,
+						lastEventId: Math.max(prev.lastEventId, e.id),
+					},
+				},
+			};
+		});
+	},
+
+	reset: (path: string) => {
+		set((s) => {
+			const next = { ...s.byPath };
+			delete next[path];
+			return { byPath: next };
+		});
+	},
+}));