emdash-plugin-sitegraph 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,957 @@
+import { PluginRouteError, definePlugin } from "emdash";
+import { z } from "astro/zod";
+
+//#region src/domain/graph.ts
+const NODE_TYPES = [
+	"CONTENT",
+	"URL",
+	"FORM",
+	"SERVICE",
+	"WORKFLOW",
+	"TEAM_MEMBER"
+];
+/** Node types a person can create; CONTENT and URL only come from scans. */
+const DOCUMENTED_NODE_TYPES = [
+	"FORM",
+	"SERVICE",
+	"WORKFLOW",
+	"TEAM_MEMBER"
+];
+/** Relations a person can document; PUBLISHES_AS and LINKS_TO only come from scans. */
+const DOCUMENTED_RELATION_TYPES = [
+	"SUBMITS_TO",
+	"DEPENDS_ON",
+	"PART_OF",
+	"OWNED_BY",
+	"RELATED_TO"
+];
+const CRITICALITIES = [
+	"LOW",
+	"MEDIUM",
+	"HIGH",
+	"CRITICAL"
+];
+const SCHEMA_VERSION = 1;
+const contentNodeId = (collection, entryId) => `content:${collection}:${entryId}`;
+const urlNodeId = (path) => `url:${path}`;
+const edgeId = (source, relation, target, fieldPath = "") => `${source}|${relation}|${target}|${fieldPath}`;
+
+//#endregion
+//#region src/domain/impact.ts
+const MAX_DEPTH$1 = 3;
+const MAX_NODES = 500;
+const MAX_EDGES = 1e3;
+/**
+* Most relations read "source depends on target" (a page links to a URL, a form submits to a
+* CRM). PART_OF reads the other way: the workflow depends on its parts. RELATED_TO has no
+* direction. So "inbound" (what depends on this) walks edges backwards, except PART_OF.
+*/
+function follows(relation, dir, direction) {
+	if (relation === "RELATED_TO") return true;
+	return (relation === "PART_OF" ? dir === "inbound" ? "outbound" : "inbound" : dir) === direction;
+}
+/**
+* Bounded breadth-first search. "inbound" finds what depends on the start node (what could
+* break if it changes); "outbound" finds what it depends on. Each node is
+* reached once, by its shortest path, so cycles end the walk. Reachability is potential
+* impact, never proof of it.
+*/
+async function impact(start, direction, depth, fetchEdges) {
+	const maxDepth = Math.max(1, Math.min(MAX_DEPTH$1, Math.floor(depth)));
+	const reached = new Map([[start, {
+		nodeId: start,
+		depth: 0,
+		path: [],
+		confirmed: true
+	}]]);
+	const edges = /* @__PURE__ */ new Map();
+	let frontier = [start];
+	let truncated = false;
+	for (let level = 1; level <= maxDepth && frontier.length > 0 && !truncated; level++) {
+		const next = [];
+		let batch = frontier;
+		while (batch.length > 0 && !truncated) {
+			const samePage = [];
+			for (const dir of ["outbound", "inbound"]) for (const edge of await fetchEdges(batch, dir)) {
+				const free = edge.relation === "PUBLISHES_AS";
+				if (direction !== "both" && !free && !follows(edge.relation, dir, direction)) continue;
+				const from = dir === "outbound" ? edge.sourceNodeId : edge.targetNodeId;
+				const to = dir === "outbound" ? edge.targetNodeId : edge.sourceNodeId;
+				const parent = reached.get(from);
+				if (!parent) continue;
+				if (edges.size >= MAX_EDGES) {
+					truncated = true;
+					break;
+				}
+				edges.set(edge.id, edge);
+				if (reached.has(to)) continue;
+				if (reached.size >= MAX_NODES) {
+					truncated = true;
+					break;
+				}
+				reached.set(to, {
+					nodeId: to,
+					depth: free ? parent.depth : level,
+					path: [...parent.path, edge],
+					confirmed: parent.confirmed && edge.provenance !== "INFERRED"
+				});
+				(free ? samePage : next).push(to);
+			}
+			batch = samePage;
+		}
+		frontier = next;
+	}
+	reached.delete(start);
+	return {
+		start,
+		hits: [...reached.values()],
+		edges: [...edges.values()],
+		truncated
+	};
+}
+
+//#endregion
+//#region src/domain/links.ts
+const MAX_DEPTH = 32;
+const UNSAFE_SCHEME = /^\s*(javascript|data|vbscript|file|mailto|tel):/i;
+/**
+* Find links in an entry's data: Portable Text link marks (`{_type: "link", href}`)
+* anywhere in the tree, plus the values of the given `url`-type fields.
+* Plain strings that merely look like URLs are ignored on purpose.
+*/
+function extractLinks(data, urlFields = []) {
+	const found = [];
+	for (const field of urlFields) {
+		const value = data[field];
+		if (typeof value === "string" && value.trim()) found.push({
+			href: value.trim(),
+			field,
+			path: field
+		});
+	}
+	const walk = (value, field, path, depth) => {
+		if (depth > MAX_DEPTH || value === null || typeof value !== "object") return;
+		if (Array.isArray(value)) {
+			value.forEach((item, i) => walk(item, field, `${path}[${i}]`, depth + 1));
+			return;
+		}
+		const obj = value;
+		if (obj._type === "link" && typeof obj.href === "string" && obj.href.trim()) found.push({
+			href: obj.href.trim(),
+			field,
+			path
+		});
+		for (const [key, child] of Object.entries(obj)) walk(child, field, `${path}.${key}`, depth + 1);
+	};
+	for (const [field, value] of Object.entries(data)) walk(value, field, field, 0);
+	return found;
+}
+/**
+* Turn an href into the site-relative path that identifies a page, or null when the
+* link is external, unsafe or not a page link. Fragments and query strings are dropped
+* (`/pricing?plan=pro` is the pricing page; the raw href stays in the edge evidence) and
+* trailing slashes are ignored so "/a/" and "/a" are the same page.
+*/
+function internalPath(href, sourcePath, siteUrl) {
+	if (UNSAFE_SCHEME.test(href) || href.trim().startsWith("#")) return null;
+	const origin = siteUrl ? new URL(siteUrl).origin : "http://sitegraph.invalid";
+	let url;
+	try {
+		url = new URL(href, new URL(sourcePath || "/", origin));
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	if (url.origin !== origin) return null;
+	let path = url.pathname.replace(/\/{2,}/g, "/");
+	if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+	return path;
+}
+/**
+* The public path of an entry from its collection's URL pattern, mirroring EmDash's
+* `interpolateUrlPattern` for `{slug}` and `{id}`. Returns null for patterns using
+* tokens we don't resolve (dates, locales), so we never invent a wrong URL.
+*/
+function entryPath(pattern, collection, slug, id) {
+	let path = (pattern ?? `/${encodeURIComponent(collection)}/{slug}`).replaceAll("{slug}", encodeURIComponent(slug)).replaceAll("{id}", encodeURIComponent(id));
+	if (path.includes("{")) return null;
+	path = path.replace(/\/{2,}/g, "/");
+	if (!path.startsWith("/")) path = `/${path}`;
+	if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+	return path;
+}
+/**
+* A matcher for paths an entry of this collection could live at, or null when the pattern
+* uses tokens we don't resolve. Used to tell a broken link (looks like an entry, none is
+* there) from a link to some other page of the site (home, listings, feeds).
+*/
+function entryPathMatcher(pattern, collection) {
+	let base = pattern ?? `/${encodeURIComponent(collection)}/{slug}`;
+	if (/\{(?!slug\}|id\})[^}]*\}/.test(base)) return null;
+	base = base.replace(/\/{2,}/g, "/");
+	if (!base.startsWith("/")) base = `/${base}`;
+	if (base.length > 1 && base.endsWith("/")) base = base.slice(0, -1);
+	const source = base.split(/(\{slug\}|\{id\})/).map((part) => part === "{slug}" || part === "{id}" ? "[^/]+" : part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("");
+	return new RegExp(`^${source}$`);
+}
+
+//#endregion
+//#region src/store.ts
+const STORAGE = {
+	nodes: { indexes: [
+		"type",
+		"active",
+		"search",
+		"provenance",
+		"resolved"
+	] },
+	edges: { indexes: [
+		"sourceNodeId",
+		"targetNodeId",
+		"provenance",
+		"active"
+	] }
+};
+const nodesOf = (ctx) => ctx.storage.nodes;
+const edgesOf = (ctx) => ctx.storage.edges;
+const PAGE = 100;
+/** Documents matching `where`, page by page, stopping once `max` are read. */
+async function queryAll(collection, where, max = Infinity) {
+	const out = [];
+	let cursor;
+	do {
+		const page = await collection.query({
+			where,
+			limit: PAGE,
+			cursor
+		});
+		out.push(...page.items);
+		cursor = page.hasMore && out.length < max ? page.cursor : void 0;
+	} while (cursor);
+	return out.slice(0, max);
+}
+/**
+* Active edges touching any of `nodeIds`, used by impact and neighbourhood views. Stops reading
+* at `max`, so a hub page linked from every footer can't make a request read the whole table.
+*/
+async function activeEdges(ctx, nodeIds, direction, max = Infinity) {
+	const field = direction === "outbound" ? "sourceNodeId" : "targetNodeId";
+	const out = [];
+	for (let i = 0; i < nodeIds.length && out.length < max; i += PAGE) {
+		const rows = await queryAll(edgesOf(ctx), {
+			[field]: { in: nodeIds.slice(i, i + PAGE) },
+			active: true
+		}, max - out.length);
+		for (const row of rows) out.push({
+			id: row.id,
+			...row.data
+		});
+	}
+	return out;
+}
+
+//#endregion
+//#region src/scan.ts
+const SCAN_KEY = "scan";
+const LAST_SCAN_KEY = "lastScan";
+const BATCH = 25;
+const STALE_AFTER_MS = 120 * 1e3;
+const MAX_ERRORS = 20;
+const errorText = (error) => error instanceof Error ? error.message : String(error);
+async function collectionPlans(ctx) {
+	return (await ctx.schema?.listCollections() ?? []).map((c) => ({
+		slug: c.slug,
+		label: c.labelSingular ?? c.label,
+		pattern: c.urlPattern,
+		routable: c.routable,
+		titleField: c.titleField,
+		urlFields: c.fields.filter((f) => f.type === "url").map((f) => f.slug)
+	}));
+}
+/**
+* Could an entry live at this path? Yes when it fits a routable collection's URL pattern and
+* doesn't look like a file. A link to such a path with no entry behind it is broken; a link
+* to anything else (home page, listings, feeds) points at a page we simply don't map.
+*/
+function looksLikeEntryPath(path, plans) {
+	if (path.slice(path.lastIndexOf("/") + 1).includes(".")) return false;
+	return plans.some((p) => p.routable && entryPathMatcher(p.pattern, p.slug)?.test(path));
+}
+function entryLabel(item, plan) {
+	const title = plan.titleField ? item.data[plan.titleField] : item.data.title;
+	if (typeof title === "string" && title.trim()) return title.trim().slice(0, 200);
+	return item.slug ?? item.id;
+}
+/** A discovered node merged over what's stored, so human annotations and firstSeenAt survive. */
+function discoveredNode(existing, fresh, now, scanId) {
+	return {
+		...existing,
+		...fresh,
+		search: fresh.label.toLowerCase(),
+		provenance: "DISCOVERED",
+		active: true,
+		firstSeenAt: existing?.firstSeenAt ?? now,
+		lastSeenAt: now,
+		schemaVersion: SCHEMA_VERSION,
+		scanId
+	};
+}
+/**
+* Recompute a URL node's status from the edges that point at it, the single source of truth:
+* a published entry there → resolved; otherwise broken if it looks like an entry path, or
+* unknown if not; and with nothing pointing at it at all, it leaves the map.
+*/
+async function settleUrl(ctx, plans, nodeId) {
+	const nodes = nodesOf(ctx);
+	const node = await nodes.get(nodeId);
+	if (!node || node.type !== "URL" || node.provenance !== "DISCOVERED") return false;
+	const inbound = await activeEdges(ctx, [nodeId], "inbound", 50);
+	const hasPage = inbound.some((e) => e.relation === "PUBLISHES_AS");
+	const next = { ...node };
+	if (!hasPage && inbound.length === 0) next.active = false;
+	else if (hasPage) next.resolved = true;
+	else if (looksLikeEntryPath(node.ref, plans)) next.resolved = false;
+	else delete next.resolved;
+	if (next.active === node.active && next.resolved === node.resolved) return false;
+	await nodes.put(nodeId, next);
+	return true;
+}
+/**
+* Re-read one entry's graph: its CONTENT node, its URL, and its outgoing links. Outgoing
+* discovered edges it no longer has are retired; that's safe because the entry was read whole.
+* `settle` recomputes the touched URLs right away (hooks); a full scan settles them at the end.
+*/
+async function refreshEntry(ctx, plans, plan, item, scanId, settle) {
+	if (item.status !== "published") return retireEntry(ctx, plans, plan.slug, item.id);
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const nodes = nodesOf(ctx);
+	const edges = edgesOf(ctx);
+	const contentId = contentNodeId(plan.slug, item.id);
+	const isDefaultLocale = !item.locale || item.locale === ctx.site.locale;
+	const path = plan.routable && item.slug && isDefaultLocale ? entryPath(plan.pattern, plan.slug, item.slug, item.id) : null;
+	const links = extractLinks(item.data, plan.urlFields).flatMap((link) => {
+		const target = internalPath(link.href, path ?? "/", ctx.site.url);
+		return target && target !== path ? [{
+			...link,
+			target
+		}] : [];
+	});
+	const nodeIds = [
+		contentId,
+		...path ? [urlNodeId(path)] : [],
+		...links.map((l) => urlNodeId(l.target))
+	];
+	const existing = await nodes.getMany([...new Set(nodeIds)]);
+	const nodeDocs = /* @__PURE__ */ new Map();
+	nodeDocs.set(contentId, discoveredNode(existing.get(contentId), {
+		type: "CONTENT",
+		label: entryLabel(item, plan),
+		ref: `${plan.slug}/${item.id}`
+	}, now, scanId));
+	if (path) nodeDocs.set(urlNodeId(path), discoveredNode(existing.get(urlNodeId(path)), {
+		type: "URL",
+		label: path,
+		ref: path,
+		resolved: true
+	}, now, scanId));
+	for (const link of links) {
+		const id = urlNodeId(link.target);
+		if (nodeDocs.has(id)) continue;
+		const prior = existing.get(id);
+		const resolved = prior?.active ? prior.resolved : looksLikeEntryPath(link.target, plans) ? false : void 0;
+		const doc = discoveredNode(prior, {
+			type: "URL",
+			label: link.target,
+			ref: link.target
+		}, now, scanId);
+		if (resolved === void 0) delete doc.resolved;
+		else doc.resolved = resolved;
+		nodeDocs.set(id, doc);
+	}
+	const edgeDocs = /* @__PURE__ */ new Map();
+	const edge = (source, relation, target, field, evidence) => {
+		edgeDocs.set(edgeId(source, relation, target, field), {
+			sourceNodeId: source,
+			targetNodeId: target,
+			relation,
+			provenance: "DISCOVERED",
+			evidence: {
+				sourceId: `${plan.slug}/${item.id}`,
+				observedAt: now,
+				...evidence
+			},
+			active: true,
+			scanId,
+			firstSeenAt: now,
+			lastSeenAt: now,
+			schemaVersion: SCHEMA_VERSION
+		});
+	};
+	if (path) edge(contentId, "PUBLISHES_AS", urlNodeId(path), "", { href: path });
+	for (const link of links) edge(contentId, "LINKS_TO", urlNodeId(link.target), link.field, {
+		fieldPath: link.path,
+		href: link.href
+	});
+	const previous = await queryAll(edges, {
+		sourceNodeId: contentId,
+		provenance: "DISCOVERED"
+	});
+	const prevById = new Map(previous.map((p) => [p.id, p.data]));
+	for (const [id, doc] of edgeDocs) {
+		const first = prevById.get(id)?.firstSeenAt;
+		if (first) doc.firstSeenAt = first;
+	}
+	const stale = previous.filter((p) => p.data.active && !edgeDocs.has(p.id));
+	await nodes.putMany([...nodeDocs].map(([id, data]) => ({
+		id,
+		data
+	})));
+	await edges.putMany([...[...edgeDocs].map(([id, data]) => ({
+		id,
+		data
+	})), ...stale.map((p) => ({
+		id: p.id,
+		data: {
+			...p.data,
+			active: false
+		}
+	}))]);
+	if (settle) {
+		const touched = new Set([...stale.map((e) => e.data.targetNodeId), ...links.map((l) => urlNodeId(l.target))]);
+		for (const id of touched) await settleUrl(ctx, plans, id);
+	}
+}
+/** An entry left the published site: hide its node and links, then re-settle the URLs it touched. */
+async function retireEntry(ctx, plans, collection, entryId) {
+	const nodes = nodesOf(ctx);
+	const edges = edgesOf(ctx);
+	const contentId = contentNodeId(collection, entryId);
+	const outgoing = (await queryAll(edges, {
+		sourceNodeId: contentId,
+		provenance: "DISCOVERED"
+	})).filter((e) => e.data.active);
+	await edges.putMany(outgoing.map((e) => ({
+		id: e.id,
+		data: {
+			...e.data,
+			active: false
+		}
+	})));
+	const content = await nodes.get(contentId);
+	if (content?.active) await nodes.put(contentId, {
+		...content,
+		active: false
+	});
+	for (const id of new Set(outgoing.map((e) => e.data.targetNodeId))) await settleUrl(ctx, plans, id);
+}
+/** Refresh one entry from a content hook. Never scans the site (SPEC D8). */
+async function refreshFromHook(ctx, collection, entryId) {
+	const plans = await collectionPlans(ctx);
+	const plan = plans.find((p) => p.slug === collection);
+	if (!plan) return;
+	const item = await ctx.content?.get(collection, entryId);
+	if (!item) return retireEntry(ctx, plans, collection, entryId);
+	await refreshEntry(ctx, plans, plan, item, (await ctx.kv.get(SCAN_KEY))?.id ?? "hook", true);
+}
+async function retireFromHook(ctx, collection, entryId) {
+	await retireEntry(ctx, await collectionPlans(ctx), collection, entryId);
+}
+async function getScanStatus(ctx) {
+	return {
+		running: await ctx.kv.get(SCAN_KEY),
+		last: await ctx.kv.get(LAST_SCAN_KEY)
+	};
+}
+/** Start a scan, or join the one in progress (two admins clicking at once share it). */
+async function startScan(ctx) {
+	const running = await ctx.kv.get(SCAN_KEY);
+	if (running && Date.now() - Date.parse(running.updatedAt ?? running.startedAt) < STALE_AFTER_MS) return running;
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const state = {
+		id: `scan_${crypto.randomUUID()}`,
+		startedAt: now,
+		updatedAt: now,
+		phase: "collect",
+		collections: await collectionPlans(ctx),
+		index: 0,
+		processed: 0,
+		retired: 0,
+		errors: []
+	};
+	await ctx.kv.set(SCAN_KEY, state);
+	return state;
+}
+/**
+* Advance scan `scanId` by one bounded batch. The admin calls this until `done`, so no single
+* request runs long. Reconciliation runs only after every collection was read cleanly, so a
+* failed or abandoned scan never retires anything (SPEC D7). Writes are compare-and-set: if
+* another tab advanced the scan meanwhile, this step's state is dropped instead of rolling
+* theirs back (the work it did is idempotent).
+*/
+async function scanStep(ctx, scanId) {
+	const versioned = await ctx.kv.getVersioned(SCAN_KEY);
+	const state = versioned?.value;
+	if (!state) return {
+		state: null,
+		last: await ctx.kv.get(LAST_SCAN_KEY),
+		done: true
+	};
+	if (state.id !== scanId) throw PluginRouteError.conflict("A newer scan replaced this one. Reload to follow it.");
+	const plans = state.collections;
+	if (state.phase === "collect") {
+		const plan = plans[state.index];
+		if (!plan) {
+			state.phase = "reconcile-edges";
+			state.cursor = void 0;
+		} else try {
+			const page = await ctx.content.list(plan.slug, {
+				limit: BATCH,
+				cursor: state.cursor,
+				where: { status: "published" }
+			});
+			for (const item of page.items) try {
+				await refreshEntry(ctx, plans, plan, item, state.id, false);
+				state.processed++;
+			} catch (error) {
+				if (state.errors.length < MAX_ERRORS) state.errors.push(`${plan.slug}/${item.id}: ${errorText(error)}`);
+			}
+			if (page.hasMore && page.cursor) state.cursor = page.cursor;
+			else {
+				state.index++;
+				state.cursor = void 0;
+			}
+		} catch (error) {
+			if (state.errors.length < MAX_ERRORS) state.errors.push(`${plan.slug}: ${errorText(error)}`);
+			state.index++;
+			state.cursor = void 0;
+		}
+	} else if (state.errors.length) return finish(ctx, state);
+	else if (state.phase === "reconcile-edges") {
+		const page = await edgesOf(ctx).query({
+			where: { provenance: "DISCOVERED" },
+			limit: 100,
+			cursor: state.cursor
+		});
+		const stale = page.items.filter((row) => row.data.active && row.data.scanId !== state.id);
+		if (stale.length) {
+			await edgesOf(ctx).putMany(stale.map((row) => ({
+				id: row.id,
+				data: {
+					...row.data,
+					active: false
+				}
+			})));
+			state.retired += stale.length;
+		}
+		if (page.hasMore && page.cursor) state.cursor = page.cursor;
+		else {
+			state.phase = "reconcile-nodes";
+			state.cursor = void 0;
+		}
+	} else {
+		const page = await nodesOf(ctx).query({
+			where: { provenance: "DISCOVERED" },
+			limit: 50,
+			cursor: state.cursor
+		});
+		for (const row of page.items) {
+			if (!row.data.active) continue;
+			if (row.data.type === "URL") {
+				if (await settleUrl(ctx, plans, row.id) && !(await nodesOf(ctx).get(row.id))?.active) state.retired++;
+			} else if (row.data.scanId !== state.id) {
+				await nodesOf(ctx).put(row.id, {
+					...row.data,
+					active: false
+				});
+				state.retired++;
+			}
+		}
+		if (page.hasMore && page.cursor) state.cursor = page.cursor;
+		else return finish(ctx, state);
+	}
+	state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const current = (await ctx.kv.compareAndSet(SCAN_KEY, versioned.revision, state)).applied ? state : await ctx.kv.get(SCAN_KEY);
+	return {
+		state: current,
+		last: await ctx.kv.get(LAST_SCAN_KEY),
+		done: !current
+	};
+}
+async function finish(ctx, state) {
+	const last = {
+		id: state.id,
+		startedAt: state.startedAt,
+		finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		status: state.errors.length ? "PARTIAL" : "SUCCEEDED",
+		processed: state.processed,
+		retired: state.retired,
+		errors: state.errors
+	};
+	await ctx.kv.set(LAST_SCAN_KEY, last);
+	await ctx.kv.delete(SCAN_KEY);
+	return {
+		state: null,
+		last,
+		done: true
+	};
+}
+
+//#endregion
+//#region src/routes.ts
+const READ = "plugins:read";
+const MANAGE = "plugins:manage";
+const id = z.string().min(1).max(600);
+const text = (max) => z.string().trim().max(max);
+const safeUrl = z.string().trim().max(2e3).refine((v) => v === "" || /^https?:\/\//i.test(v), "Only http(s) links are allowed");
+const annotation = {
+	description: text(2e3).optional(),
+	criticality: z.enum(CRITICALITIES).nullable().optional(),
+	notes: text(5e3).optional(),
+	docUrl: safeUrl.optional(),
+	lastVerifiedAt: z.iso.datetime().nullable().optional()
+};
+const nodeSaveInput = z.object({
+	id: id.optional(),
+	type: z.enum(DOCUMENTED_NODE_TYPES).optional(),
+	label: text(200).min(1).optional(),
+	...annotation
+});
+const NEIGHBOUR_CAP = 200;
+async function nodesById(ctx, ids) {
+	return [...await nodesOf(ctx).getMany([...new Set(ids)])].map(([nodeId, data]) => ({
+		id: nodeId,
+		...data
+	}));
+}
+async function requireNode(ctx, nodeId) {
+	const node = await nodesOf(ctx).get(nodeId);
+	if (!node || !node.active) throw PluginRouteError.notFound("That node doesn't exist (or a scan retired it).");
+	return node;
+}
+function applyAnnotation(target, input) {
+	const out = { ...target };
+	for (const key of Object.keys(annotation)) {
+		const value = input[key];
+		if (value === void 0) continue;
+		if (value === "" || value === null) delete out[key];
+		else out[key] = value;
+	}
+	return out;
+}
+const routes = {
+	health: {
+		permission: READ,
+		handler: async (ctx) => ({
+			plugin: ctx.plugin.id,
+			version: ctx.plugin.version,
+			siteUrl: ctx.site.url || null
+		})
+	},
+	overview: {
+		permission: READ,
+		handler: async (ctx) => {
+			const nodes = nodesOf(ctx);
+			const counts = Object.fromEntries(await Promise.all(NODE_TYPES.map(async (type) => [type, await nodes.count({
+				type,
+				active: true
+			})])));
+			return {
+				siteUrl: ctx.site.url || null,
+				counts,
+				edges: await edgesOf(ctx).count({ active: true }),
+				brokenLinks: await nodes.count({
+					type: "URL",
+					active: true,
+					resolved: false
+				}),
+				scan: await getScanStatus(ctx)
+			};
+		}
+	},
+	"scan/start": {
+		permission: MANAGE,
+		handler: async (ctx) => ({ state: await startScan(ctx) })
+	},
+	"scan/step": {
+		permission: MANAGE,
+		input: z.object({ scanId: z.string().min(1).max(100) }),
+		handler: async (ctx) => scanStep(ctx, ctx.input.scanId)
+	},
+	"nodes/search": {
+		permission: READ,
+		input: z.object({
+			q: text(200).default(""),
+			type: z.enum(NODE_TYPES).optional(),
+			broken: z.boolean().optional(),
+			cursor: z.string().optional()
+		}),
+		handler: async (ctx) => {
+			const { q, type, broken, cursor } = ctx.input;
+			const where = { active: true };
+			if (q) where.search = { startsWith: q.toLowerCase() };
+			if (type) where.type = type;
+			if (broken) Object.assign(where, {
+				type: "URL",
+				resolved: false
+			});
+			const page = await nodesOf(ctx).query({
+				where,
+				limit: 50,
+				cursor
+			});
+			return {
+				items: page.items.map((row) => ({
+					id: row.id,
+					...row.data
+				})),
+				cursor: page.hasMore ? page.cursor : null
+			};
+		}
+	},
+	"graph/neighborhood": {
+		permission: READ,
+		input: z.object({ nodeId: id }),
+		handler: async (ctx) => {
+			const center = await requireNode(ctx, ctx.input.nodeId);
+			const cap = NEIGHBOUR_CAP + 1;
+			const [outbound, inbound] = await Promise.all([activeEdges(ctx, [ctx.input.nodeId], "outbound", cap), activeEdges(ctx, [ctx.input.nodeId], "inbound", cap)]);
+			const ownUrls = outbound.filter((e) => e.relation === "PUBLISHES_AS").map((e) => e.targetNodeId);
+			const linkers = ownUrls.length ? await activeEdges(ctx, ownUrls, "inbound", cap) : [];
+			const all = [...new Map([
+				...outbound,
+				...inbound,
+				...linkers
+			].map((e) => [e.id, e])).values()];
+			const edges = all.slice(0, NEIGHBOUR_CAP);
+			const nodes = await nodesById(ctx, edges.flatMap((e) => [e.sourceNodeId, e.targetNodeId]));
+			return {
+				center: {
+					id: ctx.input.nodeId,
+					...center
+				},
+				nodes,
+				edges,
+				truncated: all.length > edges.length,
+				total: all.length
+			};
+		}
+	},
+	"graph/impact": {
+		permission: READ,
+		input: z.object({
+			nodeId: id,
+			direction: z.enum([
+				"inbound",
+				"outbound",
+				"both"
+			]).default("inbound"),
+			depth: z.number().int().min(1).max(MAX_DEPTH$1).default(2)
+		}),
+		handler: async (ctx) => {
+			await requireNode(ctx, ctx.input.nodeId);
+			const result = await impact(ctx.input.nodeId, ctx.input.direction, ctx.input.depth, (ids, dir) => activeEdges(ctx, ids, dir, MAX_EDGES));
+			const nodes = await nodesById(ctx, [result.start, ...result.hits.map((h) => h.nodeId)]);
+			return {
+				...result,
+				nodes
+			};
+		}
+	},
+	"nodes/save": {
+		permission: MANAGE,
+		input: nodeSaveInput,
+		handler: async (ctx) => {
+			const nodes = nodesOf(ctx);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const { id: nodeId, type, label } = ctx.input;
+			if (nodeId) {
+				const existing = await requireNode(ctx, nodeId);
+				const renamed = existing.provenance === "DOCUMENTED" && label ? {
+					label,
+					search: label.toLowerCase()
+				} : {};
+				const updated = applyAnnotation({
+					...existing,
+					...renamed
+				}, ctx.input);
+				await nodes.put(nodeId, updated);
+				return {
+					id: nodeId,
+					...updated
+				};
+			}
+			if (!type || !label) throw PluginRouteError.badRequest("A new node needs a type and a label.");
+			const created = applyAnnotation({
+				type,
+				label,
+				search: label.toLowerCase(),
+				ref: label,
+				provenance: "DOCUMENTED",
+				active: true,
+				firstSeenAt: now,
+				lastSeenAt: now,
+				schemaVersion: SCHEMA_VERSION
+			}, ctx.input);
+			const newId = `doc:${crypto.randomUUID()}`;
+			await nodes.put(newId, created);
+			return {
+				id: newId,
+				...created
+			};
+		}
+	},
+	"nodes/delete": {
+		permission: MANAGE,
+		input: z.object({ id }),
+		handler: async (ctx) => {
+			if ((await requireNode(ctx, ctx.input.id)).provenance !== "DOCUMENTED") throw PluginRouteError.badRequest("Discovered nodes come from your content. Change the content instead.");
+			const touching = [...await queryAll(edgesOf(ctx), { sourceNodeId: ctx.input.id }), ...await queryAll(edgesOf(ctx), { targetNodeId: ctx.input.id })];
+			await edgesOf(ctx).deleteMany(touching.map((e) => e.id));
+			await nodesOf(ctx).delete(ctx.input.id);
+			return {
+				deleted: ctx.input.id,
+				edgesDeleted: touching.length
+			};
+		}
+	},
+	"edges/save": {
+		permission: MANAGE,
+		input: z.object({
+			sourceNodeId: id,
+			targetNodeId: id,
+			relation: z.enum(DOCUMENTED_RELATION_TYPES),
+			label: text(200).optional()
+		}),
+		handler: async (ctx) => {
+			const { sourceNodeId, targetNodeId, relation, label } = ctx.input;
+			if (sourceNodeId === targetNodeId) throw PluginRouteError.badRequest("A node can't depend on itself.");
+			if (relation === "RELATED_TO" && !label) throw PluginRouteError.badRequest("Say how they're related: RELATED_TO needs a label.");
+			await requireNode(ctx, sourceNodeId);
+			await requireNode(ctx, targetNodeId);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const edgeKey = edgeId(sourceNodeId, relation, targetNodeId, "doc");
+			const existing = await edgesOf(ctx).get(edgeKey);
+			const edge = {
+				sourceNodeId,
+				targetNodeId,
+				relation,
+				...label ? { label } : {},
+				provenance: "DOCUMENTED",
+				evidence: {
+					observedAt: now,
+					...ctx.user?.id ? { sourceId: `user:${ctx.user.id}` } : {}
+				},
+				active: true,
+				firstSeenAt: existing?.firstSeenAt ?? now,
+				lastSeenAt: now,
+				schemaVersion: SCHEMA_VERSION
+			};
+			await edgesOf(ctx).put(edgeKey, edge);
+			return {
+				id: edgeKey,
+				...edge
+			};
+		}
+	},
+	"edges/delete": {
+		permission: MANAGE,
+		input: z.object({ id }),
+		handler: async (ctx) => {
+			const edge = await edgesOf(ctx).get(ctx.input.id);
+			if (!edge) throw PluginRouteError.notFound("That relationship doesn't exist.");
+			if (edge.provenance !== "DOCUMENTED") throw PluginRouteError.badRequest("Discovered links come from your content. Edit the content instead.");
+			await edgesOf(ctx).delete(ctx.input.id);
+			return { deleted: ctx.input.id };
+		}
+	},
+	export: {
+		permission: READ,
+		handler: async (ctx) => ({
+			format: "sitegraph",
+			schemaVersion: SCHEMA_VERSION,
+			plugin: {
+				id: ctx.plugin.id,
+				version: ctx.plugin.version
+			},
+			site: ctx.site.url || null,
+			exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			nodes: (await queryAll(nodesOf(ctx), { active: true })).map((r) => ({
+				id: r.id,
+				...r.data
+			})),
+			edges: (await queryAll(edgesOf(ctx), { active: true })).map((r) => ({
+				id: r.id,
+				...r.data
+			}))
+		})
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const ID = "sitegraph";
+const VERSION = "0.1.0";
+const PACKAGE = "emdash-plugin-sitegraph";
+const ADMIN_ENTRY = `${PACKAGE}/admin`;
+const PAGES = [{
+	path: "/",
+	label: "SiteGraph",
+	icon: "graph"
+}];
+const WIDGETS = [{
+	id: "overview",
+	title: "SiteGraph",
+	size: "half"
+}];
+/** Build-time descriptor: register with `emdash({ plugins: [siteGraph()] })`. */
+function siteGraph() {
+	return {
+		id: ID,
+		version: VERSION,
+		format: "native",
+		entrypoint: PACKAGE,
+		adminEntry: ADMIN_ENTRY,
+		adminPages: PAGES,
+		adminWidgets: WIDGETS
+	};
+}
+const entryId = (content) => typeof content.id === "string" ? content.id : null;
+/** Runtime entry. EmDash imports this by name. */
+function createPlugin() {
+	return definePlugin({
+		id: ID,
+		version: VERSION,
+		capabilities: ["content:read", "schema:read"],
+		storage: STORAGE,
+		admin: {
+			entry: ADMIN_ENTRY,
+			pages: PAGES,
+			widgets: WIDGETS
+		},
+		hooks: {
+			"content:afterSave": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterPublish": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterRestore": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await refreshFromHook(ctx, event.collection, id);
+			},
+			"content:afterUnpublish": async (event, ctx) => {
+				const id = entryId(event.content);
+				if (id) await retireFromHook(ctx, event.collection, id);
+			},
+			"content:afterDelete": async (event, ctx) => {
+				await retireFromHook(ctx, event.collection, event.id);
+			}
+		},
+		routes
+	});
+}
+
+//#endregion
+export { createPlugin, siteGraph as default, siteGraph };