wiki-viewer 1.4.2 → 1.5.0

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,
 			};
 		}
 

package/.next/standalone/src/lib/proof/raw-fs.ts

@@ -0,0 +1,198 @@
+/**
+ * Shared utilities for Tier-1 raw-fs routes.
+ *
+ * - Path safety (symlink escape guard, hard-denied paths)
+ * - SHA-256 of Buffer
+ * - Best-effort MIME by extension
+ * - Atomic write (tmp → rename, preserves mode)
+ */
+import { createHash } from "node:crypto";
+import { open, stat, rename, realpath, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { getRootDir } from "@/lib/root-dir";
+
+// ── Denied path checks ──────────────────────────────────────────────────────
+
+/**
+ * True if the root-relative path is hard-denied regardless of scope.
+ * - .proof/ — sidecar storage (Tier-2 internal)
+ * - .git/   — git objects (sensitive)
+ */
+export function isDeniedRelPath(rel: string): boolean {
+	const norm = rel.replace(/\\/g, "/");
+	return (
+		norm === ".proof" ||
+		norm.startsWith(".proof/") ||
+		norm === ".git" ||
+		norm.startsWith(".git/")
+	);
+}
+
+export function isMarkdown(filePath: string): boolean {
+	return filePath.endsWith(".md") || filePath.endsWith(".markdown");
+}
+
+// ── Path safety ──────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the absolute path for `rel`, checking:
+ *  1. basic traversal (path.join containment)
+ *  2. hard-denied prefixes (.proof/, .git/)
+ *  3. symlink escape: if file exists, realpath must still be under root
+ *
+ * For non-existent targets (creates), resolves parent dir instead.
+ *
+ * Returns absolute path on success, null on rejection.
+ */
+export async function safeAbsPath(rel: string): Promise<string | null> {
+	const root = getRootDir();
+	if (!root) return null;
+
+	// Normalise and basic traversal guard
+	const normalised = path.normalize(rel);
+	if (normalised.startsWith("..") || path.isAbsolute(normalised)) return null;
+
+	if (isDeniedRelPath(normalised)) return null;
+
+	const abs = path.join(root, normalised);
+	// Re-check containment after normalize
+	if (abs !== root && !abs.startsWith(root + path.sep)) return null;
+
+	// Symlink-escape check: resolve realpath of the nearest existing ancestor
+	try {
+		const real = await realpath(abs);
+		if (real !== root && !real.startsWith(root + path.sep)) return null;
+	} catch {
+		// Target doesn't exist — check parent
+		const parent = path.dirname(abs);
+		if (parent !== abs) {
+			try {
+				const parentReal = await realpath(parent);
+				if (parentReal !== root && !parentReal.startsWith(root + path.sep)) {
+					return null;
+				}
+			} catch {
+				// Parent doesn't exist either — containment already checked above
+			}
+		}
+	}
+
+	return abs;
+}
+
+// ── Hashing ──────────────────────────────────────────────────────────────────
+
+/** Returns "sha256:<hex>" — the canonical sha format used in ETag / audit. */
+export function sha256ofBuf(buf: Buffer): string {
+	return "sha256:" + createHash("sha256").update(buf).digest("hex");
+}
+
+/**
+ * Normalise an If-Match / ETag header value to bare hex.
+ * Strips outer double-quotes and "sha256:" prefix.
+ */
+export function extractShaHex(header: string): string {
+	return header
+		.replace(/^"/, "")
+		.replace(/"$/, "")
+		.replace(/^sha256:/, "");
+}
+
+// ── MIME ──────────────────────────────────────────────────────────────────────
+
+const MIME_MAP: Record<string, string> = {
+	".md":       "text/markdown; charset=utf-8",
+	".markdown": "text/markdown; charset=utf-8",
+	".txt":      "text/plain; charset=utf-8",
+	".json":     "application/json; charset=utf-8",
+	".jsonc":    "application/json; charset=utf-8",
+	".ts":       "text/typescript; charset=utf-8",
+	".tsx":      "text/typescript; charset=utf-8",
+	".mts":      "text/typescript; charset=utf-8",
+	".js":       "text/javascript; charset=utf-8",
+	".jsx":      "text/javascript; charset=utf-8",
+	".mjs":      "text/javascript; charset=utf-8",
+	".html":     "text/html; charset=utf-8",
+	".htm":      "text/html; charset=utf-8",
+	".css":      "text/css; charset=utf-8",
+	".yaml":     "text/yaml; charset=utf-8",
+	".yml":      "text/yaml; charset=utf-8",
+	".toml":     "text/toml; charset=utf-8",
+	".xml":      "application/xml; charset=utf-8",
+	".svg":      "image/svg+xml",
+	".png":      "image/png",
+	".jpg":      "image/jpeg",
+	".jpeg":     "image/jpeg",
+	".gif":      "image/gif",
+	".webp":     "image/webp",
+	".pdf":      "application/pdf",
+	".zip":      "application/zip",
+	".tar":      "application/x-tar",
+	".gz":       "application/gzip",
+	".py":       "text/x-python; charset=utf-8",
+	".rs":       "text/x-rustsrc; charset=utf-8",
+	".go":       "text/x-go; charset=utf-8",
+	".sh":       "text/x-shellscript; charset=utf-8",
+	".csv":      "text/csv; charset=utf-8",
+	".env":      "text/plain; charset=utf-8",
+};
+
+export function mimeByExt(filePath: string): string {
+	const ext = path.extname(filePath).toLowerCase();
+	return MIME_MAP[ext] ?? "application/octet-stream";
+}
+
+// ── Binary detection ──────────────────────────────────────────────────────────
+
+/** Heuristic: buffer contains a null byte in first 8 KB → treat as binary. */
+export function looksLikeBinary(buf: Buffer): boolean {
+	const sample = buf.slice(0, Math.min(buf.length, 8192));
+	return sample.includes(0);
+}
+
+// ── Atomic write ──────────────────────────────────────────────────────────────
+
+/**
+ * Write `data` to `absPath` atomically:
+ *   1. Write to a sibling .tmp file
+ *   2. datasync the tmp file
+ *   3. rename tmp → target
+ *
+ * Preserves the unix mode of the existing file.
+ * Caller is responsible for creating parent dirs.
+ */
+export async function atomicWrite(absPath: string, data: Buffer): Promise<void> {
+	// Preserve mode of existing file
+	let mode = 0o644;
+	try {
+		const st = await stat(absPath);
+		mode = st.mode & 0o777;
+	} catch {
+		// New file — use 0o644 default
+	}
+
+	const tmp = absPath + ".~" + process.pid + "." + Date.now() + ".tmp";
+	const fh = await open(tmp, "w", mode);
+	try {
+		await fh.write(data);
+		await fh.datasync();
+	} finally {
+		await fh.close();
+	}
+	await rename(tmp, absPath);
+}
+
+/** Ensure parent directory exists; creates intermediate dirs if mkdirs=true. */
+export async function ensureParentDir(absPath: string, mkdirs: boolean): Promise<boolean> {
+	const dir = path.dirname(absPath);
+	if (mkdirs) {
+		await mkdir(dir, { recursive: true });
+		return true;
+	}
+	try {
+		await stat(dir);
+		return true;
+	} catch {
+		return false;
+	}
+}

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

@@ -19,7 +19,7 @@ const LAST_SEEN_THROTTLE_MS = 30_000;
 
 export interface AgentScope {
 	paths: string[]; // glob patterns
-	ops: Array<"read" | "mutate">;
+	ops: Array<"read" | "mutate" | "delete">;
 }
 
 export interface Agent {

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

@@ -1,4 +1,4 @@
-import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { readFile, writeFile, mkdir, rename, unlink } from "node:fs/promises";
 import path from "node:path";
 import type { Sidecar } from "./types";
 
@@ -44,6 +44,43 @@ export async function writeSidecar(
 	await rename(tmp, dest);
 }
 
+/**
+ * Move a sidecar file alongside a renamed .md file.
+ * No-op if the sidecar does not exist.
+ */
+export async function moveSidecar(
+	rootDir: string,
+	fromMdPath: string,
+	toMdPath: string,
+): Promise<void> {
+	const src = sidecarPath(rootDir, fromMdPath);
+	const dest = sidecarPath(rootDir, toMdPath);
+	try {
+		await mkdir(path.dirname(dest), { recursive: true });
+		await rename(src, dest);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // no sidecar — ok
+		throw err;
+	}
+}
+
+/**
+ * Delete a sidecar file for a removed .md file.
+ * No-op if the sidecar does not exist.
+ */
+export async function deleteSidecar(
+	rootDir: string,
+	mdPath: string,
+): Promise<void> {
+	const filePath = sidecarPath(rootDir, mdPath);
+	try {
+		await unlink(filePath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return; // already gone — ok
+		throw err;
+	}
+}
+
 export function emptySidecar(mdPath: string): Sidecar {
 	const now = new Date().toISOString();
 	return {

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

@@ -40,6 +40,8 @@ export interface Comment {
 	resolved: boolean;
 	createdAt: string;
 	turns: CommentTurn[];
+	/** Set true when a raw .md overwrite orphans the anchor ref (R2 collab-anchor safety). */
+	stale?: boolean;
 }
 
 export type SuggestionKind =
@@ -61,11 +63,21 @@ export interface Suggestion {
 	createdAt: string;
 	resolvedAt?: string; // when accepted/rejected
 	resolvedBy?: string;
+	/** Set true when a raw .md overwrite orphans the anchor ref (R2 collab-anchor safety). */
+	stale?: boolean;
 }
 
 export interface ProofEvent {
 	id: number;
-	type: string; // see §4.6 list
+	/**
+	 * Known event types:
+	 *   block.replaced | block.inserted | block.deleted
+	 *   comment.added | comment.replied | comment.resolved | comment.reopened
+	 *   suggestion.added | suggestion.accepted | suggestion.rejected
+	 *   file.externallyEdited  — writer unknown (chokidar / external tool)
+	 *   file.rawWritten        — writer known (by: "ai:<id>"), emitted by Tier-1 raw-fs write
+	 */
+	type: string;
 	at: string;
 	by: string;
 	[k: string]: unknown;