wiki-viewer 1.0.0 → 1.0.1

package/.next/standalone/src/lib/proof/activity-shared.ts

@@ -0,0 +1,31 @@
+import type { ProofEvent } from "./types";
+
+export interface ActivityEvent extends ProofEvent {
+	path: string;
+}
+
+export const ACTIVITY_DEFAULT_LIMIT = 50;
+export const ACTIVITY_MAX_LIMIT = 200;
+
+/** Derive active connections from recent events (last 5 minutes). */
+export function deriveConnections(
+	events: ActivityEvent[],
+): { by: string; opCount: number; lastSeen: string }[] {
+	const cutoff = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+	const map = new Map<string, { opCount: number; lastSeen: string }>();
+	for (const ev of events) {
+		if (ev.at < cutoff) continue;
+		const existing = map.get(ev.by);
+		if (!existing) {
+			map.set(ev.by, { opCount: 1, lastSeen: ev.at });
+		} else {
+			map.set(ev.by, {
+				opCount: existing.opCount + 1,
+				lastSeen: ev.at > existing.lastSeen ? ev.at : existing.lastSeen,
+			});
+		}
+	}
+	return Array.from(map.entries())
+		.map(([by, v]) => ({ by, ...v }))
+		.sort((a, b) => (a.lastSeen < b.lastSeen ? 1 : -1));
+}

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

@@ -0,0 +1,74 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import type { Sidecar } from "./types";
+import type { ActivityEvent } from "./activity-shared";
+import {
+	ACTIVITY_DEFAULT_LIMIT,
+	ACTIVITY_MAX_LIMIT,
+	deriveConnections,
+} from "./activity-shared";
+
+export type { ActivityEvent } from "./activity-shared";
+export {
+	ACTIVITY_DEFAULT_LIMIT,
+	ACTIVITY_MAX_LIMIT,
+	deriveConnections,
+};
+
+/** Walk rootDir/.proof/, merge events from all sidecars, sort newest first. */
+export async function aggregateActivity(
+	rootDir: string,
+	options?: { limit?: number; file?: string },
+): Promise<ActivityEvent[]> {
+	const limit = Math.min(
+		options?.limit ?? ACTIVITY_DEFAULT_LIMIT,
+		ACTIVITY_MAX_LIMIT,
+	);
+	const fileFilter = options?.file ?? null;
+
+	const proofDir = path.join(rootDir, ".proof");
+
+	let allEvents: ActivityEvent[] = [];
+
+	async function walk(dir: string): Promise<void> {
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				await walk(fullPath);
+			} else if (entry.isFile() && entry.name.endsWith(".json")) {
+				let sc: Sidecar;
+				try {
+					const raw = await readFile(fullPath, "utf-8");
+					sc = JSON.parse(raw) as Sidecar;
+					if (sc.schemaVersion !== 1) continue;
+				} catch {
+					continue;
+				}
+				if (fileFilter && sc.path !== fileFilter) continue;
+				const events: ActivityEvent[] = (sc.events ?? []).map((ev) => ({
+					...ev,
+					path: sc.path,
+				}));
+				allEvents = allEvents.concat(events);
+			}
+		}
+	}
+
+	await walk(proofDir);
+
+	allEvents.sort((a, b) => {
+		if (a.at < b.at) return 1;
+		if (a.at > b.at) return -1;
+		return 0;
+	});
+
+	return allEvents.slice(0, limit);
+}
+
+

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

@@ -0,0 +1,132 @@
+/**
+ * Agent authentication.
+ *
+ * Accepts one of:
+ *  1. Better Auth session cookie (browser UI) — treated as a synthetic user agent
+ *  2. Bearer token + X-Agent-Id header (registered external agents)
+ *
+ * AGENT_BEARER_TOKEN env var is not used.
+ */
+import type { Agent } from "./registry";
+import { lookupAgentByToken, updateLastSeen } from "./registry";
+import { matchGlob } from "./glob";
+import { getSessionFromRequest } from "@/lib/auth/server";
+
+// One-time warning if legacy env var is set
+if (process.env.AGENT_BEARER_TOKEN) {
+	console.warn(
+		"[wiki-viewer] AGENT_BEARER_TOKEN is no longer used; manage agents via the AI Panel.",
+	);
+}
+
+export type CheckAuthResult =
+	| { ok: true; agent: Agent }
+	| { ok: false; code: string; message?: string };
+
+export async function checkAuth(req: Request): Promise<CheckAuthResult> {
+	// 1. Try Better Auth session (browser same-origin requests)
+	const session = await getSessionFromRequest(req);
+	if (session?.user) {
+		const u = session.user;
+		return {
+			ok: true,
+			agent: {
+				id: `user:${u.id}`,
+				displayName: u.name,
+				tokenHash: "",
+				scope: { paths: ["**/*"], ops: ["read", "mutate"] },
+				createdAt: "",
+				lastSeen: "",
+			},
+		};
+	}
+
+	// 2. Try Bearer token (external agents)
+	const authHeader = req.headers.get("authorization") ?? "";
+	const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7).trim() : "";
+	if (!token) {
+		return { ok: false, code: "UNAUTHORIZED", message: "No credentials" };
+	}
+
+	const agent = await lookupAgentByToken(token);
+	if (!agent) {
+		return { ok: false, code: "UNAUTHORIZED", message: "Unknown or invalid token" };
+	}
+
+	// X-Agent-Id MUST be present and MUST equal the agent id bound to this token.
+	const presentedId = req.headers.get("x-agent-id") ?? "";
+	if (!presentedId) {
+		return { ok: false, code: "UNAUTHORIZED", message: "X-Agent-Id header required" };
+	}
+	if (presentedId !== agent.id) {
+		return { ok: false, code: "UNAUTHORIZED", message: "X-Agent-Id does not match token owner" };
+	}
+
+	void updateLastSeen(agent.id);
+
+	return { ok: true, agent };
+}
+
+// ── Scope enforcement ─────────────────────────────────────────────────────────
+
+export interface ScopeParams {
+	filePath?: string;
+	op: "read" | "mutate";
+}
+
+export function enforceScope(
+	agent: Agent,
+	params: ScopeParams,
+): { ok: true } | { ok: false; code: "FORBIDDEN"; message: string } {
+	const { scope } = agent;
+
+	if (!scope.ops.includes(params.op)) {
+		return { ok: false, code: "FORBIDDEN", message: `Agent scope does not allow "${params.op}"` };
+	}
+
+	if (params.filePath) {
+		const matched = scope.paths.some((pattern) => matchGlob(pattern, params.filePath!));
+		if (!matched) {
+			return {
+				ok: false,
+				code: "FORBIDDEN",
+				message: `Agent scope does not cover path "${params.filePath}"`,
+			};
+		}
+	}
+
+	return { ok: true };
+}
+
+/** Verify the `by` field on a mutation matches the authenticated agent id. */
+export function verifyBy(
+	agent: Agent,
+	by: string | undefined | null,
+): { ok: true } | { ok: false; code: "FORBIDDEN"; message: string } {
+	// Browser/session users: accept user:*, "human", "owner" (back-compat)
+	if (agent.id.startsWith("user:")) {
+		if (!by || by === "owner" || by === "human" || by.startsWith("human:") || by === agent.id) {
+			return { ok: true };
+		}
+		return {
+			ok: false,
+			code: "FORBIDDEN",
+			message: `User agent must use "human", "owner", or own id in "by" field`,
+		};
+	}
+
+	// AI agents must match their registered id exactly
+	if (by !== agent.id) {
+		return {
+			ok: false,
+			code: "FORBIDDEN",
+			message: `"by" field must equal agent id "${agent.id}"`,
+		};
+	}
+	return { ok: true };
+}
+
+/** @deprecated No longer relevant — always returns false */
+export function hasTokenConfigured(): boolean {
+	return false;
+}

package/.next/standalone/src/lib/proof/block-refs.ts

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import type { RootContent } from "mdast";
+import type { Block, Sidecar } from "./types";
+import { blockToMarkdown, blockType } from "./blocks";
+
+function sha256hex(input: string): string {
+	return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+function textHash(markdown: string): string {
+	return sha256hex(markdown).slice(0, 12);
+}
+
+function mintRef(markdown: string, usedRefs: Set<string>, position: number): string {
+	const base = "b" + sha256hex(markdown).slice(0, 6);
+	if (!usedRefs.has(base)) return base;
+	// Collision: try position suffix
+	const withPos = `${base}_${position}`;
+	if (!usedRefs.has(withPos)) return withPos;
+	// Fallback: increment counter
+	let i = 0;
+	while (usedRefs.has(`${base}_${i}`)) i++;
+	return `${base}_${i}`;
+}
+
+/**
+ * Assign Block refs to a list of parsed mdast nodes.
+ * If a sidecar is provided, reuse existing refs for matching content hashes.
+ * Returns Block[] with stable refs and a new refMap.
+ */
+export function assignRefs(
+	nodes: RootContent[],
+	sidecar: Sidecar | null,
+): { blocks: Block[]; newRefMap: Record<string, { textHash: string; lastSeenAt: string }> } {
+	const now = new Date().toISOString();
+	const usedRefs = new Set<string>();
+	const newRefMap: Record<string, { textHash: string; lastSeenAt: string }> = {};
+
+	// Build a reverse map: textHash -> ref from existing sidecar
+	const hashToRef = new Map<string, string>();
+	if (sidecar) {
+		for (const [ref, entry] of Object.entries(sidecar.refMap)) {
+			// Only map each hash once (first wins, since refs may have been aliased)
+			if (!hashToRef.has(entry.textHash)) {
+				hashToRef.set(entry.textHash, ref);
+			}
+		}
+	}
+
+	const blocks: Block[] = nodes.map((node, i) => {
+		const md = blockToMarkdown(node);
+		const hash = textHash(md);
+		const { type, level, lang } = blockType(node);
+
+		let ref: string;
+		const existingRef = hashToRef.get(hash);
+		if (existingRef && !usedRefs.has(existingRef)) {
+			ref = existingRef;
+		} else {
+			ref = mintRef(md, usedRefs, i);
+		}
+
+		usedRefs.add(ref);
+		newRefMap[ref] = { textHash: hash, lastSeenAt: now };
+
+		const block: Block = { ref, type, markdown: md };
+		if (level !== undefined) block.level = level;
+		if (lang !== undefined) block.lang = lang;
+		return block;
+	});
+
+	return { blocks, newRefMap };
+}
+
+/**
+ * Resolve a ref against current block refs, falling back to aliases.
+ */
+export function resolveRef(
+	sidecar: Sidecar,
+	ref: string,
+	currentRefs: Set<string>,
+): string | null {
+	if (currentRefs.has(ref)) return ref;
+	const aliased = sidecar.refAliases[ref];
+	if (aliased && currentRefs.has(aliased)) return aliased;
+	return null;
+}
+
+/**
+ * After applying ops: compute new refMap and collect aliases for changed blocks.
+ * oldRefMap: refMap before ops. newBlocks: blocks after ops.
+ * Returns { newRefMap, refAliases } — aliases map old ref -> new ref for any block
+ * that changed identity this mutation. Aliases are ONE-generation only.
+ */
+export function computeRefDelta(
+	oldRefMap: Record<string, { textHash: string; lastSeenAt: string }>,
+	oldHashToRef: Map<string, string>,
+	newBlocks: Block[],
+): {
+	newRefMap: Record<string, { textHash: string; lastSeenAt: string }>;
+	refAliases: Record<string, string>;
+} {
+	const now = new Date().toISOString();
+	const newRefMap: Record<string, { textHash: string; lastSeenAt: string }> = {};
+	const refAliases: Record<string, string> = {};
+
+	for (const block of newBlocks) {
+		const hash = textHash(block.markdown);
+		newRefMap[block.ref] = { textHash: hash, lastSeenAt: now };
+
+		// If this block's hash previously mapped to a different ref, record alias
+		const oldRef = oldHashToRef.get(hash);
+		if (oldRef && oldRef !== block.ref) {
+			refAliases[oldRef] = block.ref;
+		}
+	}
+
+	// For any old ref that's no longer present (was replaced/deleted), try to alias
+	// it if we can identify which new block replaced it by position or hash.
+	for (const [oldRef, entry] of Object.entries(oldRefMap)) {
+		if (!newRefMap[oldRef] && !refAliases[oldRef]) {
+			// Old ref gone, no content match found. Check if new block with same hash exists
+			const match = newBlocks.find((b) => b.ref !== oldRef && textHash(b.markdown) === entry.textHash);
+			if (match) {
+				refAliases[oldRef] = match.ref;
+			}
+		}
+	}
+
+	return { newRefMap, refAliases };
+}
+
+export { textHash };

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

@@ -0,0 +1,73 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkStringify from "remark-stringify";
+import type { Root, RootContent } from "mdast";
+import type { BlockType } from "./types";
+
+const PARSER = unified().use(remarkParse).use(remarkGfm);
+const STRINGIFY = unified()
+	.use(remarkStringify, {
+		bullet: "-",
+		fence: "`",
+		fences: true,
+		listItemIndent: "one",
+		rule: "-",
+		emphasis: "*",
+		strong: "*",
+	})
+	.use(remarkGfm);
+
+export function parseBlocks(markdown: string): RootContent[] {
+	const tree = PARSER.parse(markdown) as Root;
+	return tree.children;
+}
+
+export function blockToMarkdown(node: RootContent): string {
+	const tree: Root = { type: "root", children: [node] };
+	return (STRINGIFY.stringify(tree) as string).replace(/\n+$/, "");
+}
+
+export function blocksToMarkdown(nodes: RootContent[]): string {
+	if (nodes.length === 0) return "";
+	const tree: Root = { type: "root", children: nodes };
+	return (STRINGIFY.stringify(tree) as string).replace(/\n+$/, "") + "\n";
+}
+
+export function blockType(node: RootContent): {
+	type: BlockType;
+	level?: number;
+	lang?: string;
+} {
+	switch (node.type) {
+		case "heading":
+			return { type: "heading", level: (node as unknown as { depth: number }).depth };
+		case "paragraph":
+			return { type: "paragraph" };
+		case "list": {
+			const n = node as unknown as { ordered: boolean; children: Array<{ checked: boolean | null | undefined }> };
+			if (
+				n.children?.some(
+					(li) => li.checked !== null && li.checked !== undefined,
+				)
+			)
+				return { type: "taskList" };
+			return { type: n.ordered ? "orderedList" : "bulletList" };
+		}
+		case "blockquote":
+			return { type: "blockquote" };
+		case "code":
+			return {
+				type: "codeBlock",
+				lang: (node as unknown as { lang: string | null }).lang ?? undefined,
+			};
+		case "table":
+			return { type: "table" };
+		case "thematicBreak":
+			return { type: "hr" };
+		case "html":
+			return { type: "html" };
+		default:
+			return { type: "paragraph" }; // fallback
+	}
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Browser-side auth for same-origin UI requests.
+ *
+ * Authentication is now handled by the owner cookie (wv_owner) set via
+ * /api/owner/init. Same-origin fetch automatically attaches cookies, so no
+ * explicit Authorization header is needed from the browser UI.
+ *
+ * All fetch calls from the browser must use credentials: "same-origin" (the
+ * default) or credentials: "include".
+ */
+
+/** @deprecated No longer returns a token. Owner cookie is used instead. */
+export function getAgentToken(): string | null {
+	return null;
+}
+
+/**
+ * Returns empty object — authentication is via owner cookie automatically.
+ * Kept for backwards-compat with call sites.
+ */
+export function authHeaders(): HeadersInit {
+	return {};
+}

package/.next/standalone/src/lib/proof/event-bus.ts

@@ -0,0 +1,47 @@
+import type { ProofEvent, Sidecar } from "./types";
+
+/**
+ * Append one or more events to a working sidecar (in-memory mutation).
+ * Assigns monotonic IDs from sidecar.nextEventId.
+ */
+export function emitEvents(
+	sidecar: Sidecar,
+	partials: Array<Omit<ProofEvent, "id">>,
+): ProofEvent[] {
+	const emitted: ProofEvent[] = [];
+	for (const partial of partials) {
+		const ev = { ...partial, id: sidecar.nextEventId++ } as ProofEvent;
+		sidecar.events.push(ev);
+		emitted.push(ev);
+	}
+	return emitted;
+}
+
+/**
+ * Poll events after a given ID, up to limit.
+ */
+export function pollEvents(
+	sidecar: Sidecar,
+	afterId: number,
+	limit: number,
+): ProofEvent[] {
+	return sidecar.events.filter((e) => e.id > afterId).slice(0, limit);
+}
+
+/**
+ * Trim sidecar events to stay under TRIM_SIZE, preserving events newer than
+ * the oldest lastAck cursor to avoid stranding agents.
+ */
+export function trimEvents(sidecar: Sidecar, trimSize: number): void {
+	if (sidecar.events.length <= trimSize) return;
+
+	const ackValues = Object.values(sidecar.lastAck);
+	const oldestAck = ackValues.length > 0 ? Math.min(...ackValues) : Infinity;
+
+	// Events to keep: either within trimSize from the end, OR above the oldest ack
+	const keepFrom = sidecar.events.length - trimSize;
+	const trimmedEvents = sidecar.events.filter(
+		(e, i) => i >= keepFrom || e.id > oldestAck,
+	);
+	sidecar.events = trimmedEvents;
+}

package/.next/standalone/src/lib/proof/file-lock.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-process file locking via proper-lockfile.
+ *
+ * Uses a sentinel file in ~/.wiki-viewer/.locks/ keyed by a hash of the lock
+ * key so the actual data file need not exist before locking.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+
+function locksDir(): string {
+	const home = process.env.HOME ?? os.homedir();
+	return path.join(home, ".wiki-viewer", ".locks");
+}
+
+function sentinelPath(lockKey: string): string {
+	const hash = createHash("sha256").update(lockKey, "utf8").digest("hex").slice(0, 32);
+	return path.join(locksDir(), hash);
+}
+
+export async function withFileLock<T>(lockKey: string, fn: () => Promise<T>): Promise<T> {
+	const dir = locksDir();
+	await mkdir(dir, { recursive: true });
+	const sentinel = sentinelPath(lockKey);
+	// Create sentinel if absent (flag "a" = append/create, never truncate)
+	await writeFile(sentinel, "", { flag: "a" });
+
+	const release = await lockfile.lock(sentinel, {
+		retries: { retries: 10, factor: 1.5, minTimeout: 50, maxTimeout: 2_000 },
+	});
+	try {
+		return await fn();
+	} finally {
+		await release();
+	}
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Minimal glob matcher.
+ *
+ * Supported patterns:
+ *   **   — any sequence of characters including path separators
+ *   *    — any sequence of characters except path separators (/)
+ *   ?    — single character that is not /
+ *   Literal characters — matched verbatim (case-sensitive)
+ *
+ * Patterns are anchored to the full string (implicit ^ and $).
+ */
+export function matchGlob(pattern: string, filePath: string): boolean {
+	const regex = globToRegex(pattern);
+	return regex.test(filePath);
+}
+
+function globToRegex(pattern: string): RegExp {
+	let regStr = "^";
+	let i = 0;
+	while (i < pattern.length) {
+		if (pattern[i] === "*" && pattern[i + 1] === "*") {
+			// ** — match anything including slashes
+			regStr += ".*";
+			i += 2;
+			// Skip a trailing slash after ** to avoid double-matching: **/foo matches foo too
+			if (pattern[i] === "/") {
+				regStr += "(?:.+/)?";
+				i++;
+				// roll back the .* so we match just /**/ properly
+				// Actually: keep simple — .* already handles it
+			}
+		} else if (pattern[i] === "*") {
+			// * — match non-slash characters
+			regStr += "[^/]*";
+			i++;
+		} else if (pattern[i] === "?") {
+			regStr += "[^/]";
+			i++;
+		} else {
+			// Escape regex special chars
+			regStr += escapeRegex(pattern[i]!);
+			i++;
+		}
+	}
+	regStr += "$";
+	return new RegExp(regStr);
+}
+
+function escapeRegex(c: string): string {
+	return c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,32 @@
+// Tiny in-memory LRU. Lives for process lifetime. Acceptable: idempotency
+// guards retries within seconds, not days.
+const MAX = 1000;
+const TTL_MS = 5 * 60 * 1000;
+
+interface Entry {
+	payloadHash: string;
+	status: number;
+	body: string;
+	expiresAt: number;
+}
+
+const store = new Map<string, Entry>();
+
+export const idempotency = {
+	get(key: string): Entry | null {
+		const e = store.get(key);
+		if (!e) return null;
+		if (e.expiresAt < Date.now()) {
+			store.delete(key);
+			return null;
+		}
+		return e;
+	},
+	set(key: string, value: Omit<Entry, "expiresAt">): void {
+		if (store.size >= MAX) {
+			const first = store.keys().next().value;
+			if (first !== undefined) store.delete(first);
+		}
+		store.set(key, { ...value, expiresAt: Date.now() + TTL_MS });
+	},
+};

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

@@ -0,0 +1,32 @@
+import { withFileLock } from "./file-lock";
+
+const locks = new Map<string, Promise<void>>();
+
+/**
+ * Acquire an in-process mutex (for same-process serialisation) and then a
+ * cross-process file lock (for multi-replica safety).
+ *
+ * The in-process mutex is held for the outer scope so that same-process
+ * callers never race for the file lock. The file lock is acquired inside so
+ * that different processes can safely share the same data files.
+ */
+export async function withFileMutex<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+): Promise<T> {
+	while (locks.has(filePath)) {
+		await locks.get(filePath);
+	}
+	let release!: () => void;
+	const p = new Promise<void>((r) => {
+		release = r;
+	});
+	locks.set(filePath, p);
+	try {
+		// Cross-process file lock wraps the inner fn.
+		return await withFileLock(filePath, fn);
+	} finally {
+		locks.delete(filePath);
+		release();
+	}
+}