@dineway-ai/plugin-seo-graph 0.1.7

package/src/hreflang.ts

@@ -0,0 +1,103 @@
+import { buildAlternateLinks } from "@jdevalk/astro-seo-graph";
+import type {
+	I18nConfig,
+	PageMetadataContribution,
+	PluginContext,
+	PublicPageContext,
+} from "dineway";
+
+import { buildPageUrl } from "./urls.js";
+
+/**
+ * Thin Dineway adapter around `@jdevalk/astro-seo-graph`'s
+ * `buildAlternateLinks`.
+ *
+ * Sources translation data via Dineway's public API
+ * (`getTranslations`, `getI18nConfig`, `getCollectionInfo`), constructs
+ * per-locale absolute URLs with the shared `buildPageUrl` helper, and
+ * hands off to `buildAlternateLinks` for normalization, dedup, and
+ * x-default resolution.
+ *
+ * Returns `[]` under any of these conditions:
+ * - i18n is not enabled (single-locale site)
+ * - the current page is not a content entry
+ * - fewer than 2 published siblings exist (no alternates to link)
+ * - the current entry is not in its own translation group (data bug)
+ * - the collection has no `urlPattern` (cannot build URLs)
+ * - any transient failure (e.g. `getTranslations` throws)
+ */
+export async function generateHreflang(
+	page: PublicPageContext,
+	ctx: PluginContext,
+	siteUrl: string,
+): Promise<PageMetadataContribution[]> {
+	// Dynamically import dineway to keep this module testable via
+	// `vi.mock("dineway", ...)` — the alternative is top-level imports
+	// that vitest then has to intercept, which works but makes mocks
+	// brittle. Dynamic import lets each test replace the module cleanly.
+	const { isI18nEnabled, getI18nConfig, getTranslations, getCollectionInfo } =
+		await import("dineway");
+
+	if (!isI18nEnabled()) return [];
+	if (page.kind !== "content" || !page.content) return [];
+
+	const cfg: I18nConfig | null = getI18nConfig();
+	if (!cfg) return [];
+
+	let result;
+	try {
+		result = await getTranslations(page.content.collection, page.content.id);
+	} catch (error) {
+		ctx.log.warn("hreflang: getTranslations failed", { error });
+		return [];
+	}
+	if (result.error !== undefined) return [];
+	if (result.translations.length < 2) return [];
+
+	// Data-integrity guard: the current entry must appear in its own
+	// translation group. If not, something is wrong upstream — don't
+	// emit partial or incorrect annotations.
+	const currentInGroup = result.translations.some((t) => t.id === page.content!.id);
+	if (!currentInGroup) return [];
+
+	let collection;
+	try {
+		collection = await getCollectionInfo(page.content.collection);
+	} catch (error) {
+		ctx.log.warn("hreflang: getCollectionInfo failed", { error });
+		return [];
+	}
+	if (!collection?.urlPattern) return [];
+	const urlPattern = collection.urlPattern;
+
+	const entries: Array<{ hreflang: string; href: string }> = [];
+	for (const t of result.translations) {
+		if (t.status !== "published") continue;
+		if (!t.slug) continue;
+		if (!cfg.locales.includes(t.locale)) continue;
+
+		const href = buildPageUrl({
+			locale: t.locale,
+			slug: t.slug,
+			siteUrl,
+			cfg,
+			urlPattern,
+		});
+		if (href === null) continue;
+
+		entries.push({ hreflang: t.locale, href });
+	}
+
+	const alternates = buildAlternateLinks({
+		entries,
+		defaultLocale: cfg.defaultLocale,
+	});
+
+	return alternates.map((a) => ({
+		kind: "link" as const,
+		rel: "alternate" as const,
+		href: a.href,
+		hreflang: a.hreflang,
+		key: `hreflang:${a.hreflang}`,
+	}));
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+import { definePlugin } from "dineway";
+import type { PluginDescriptor, RouteContext } from "dineway";
+
+import { getKeyFileBody, getOrCreateIndexNowKey, handleIndexNowTransition } from "./indexnow.js";
+import { generateLlmsTxt } from "./llms.js";
+import { metadataHandler } from "./metadata.js";
+import { listSchemaEntries } from "./schema/endpoints.js";
+
+export function seoGraphPlugin(): PluginDescriptor {
+	return {
+		id: "seo-graph",
+		version: "0.5.0",
+		format: "native",
+		entrypoint: new URL("./index.ts", import.meta.url).pathname,
+		adminEntry: new URL("./admin.tsx", import.meta.url).pathname,
+		adminPages: [
+			{ path: "/settings", label: "SEO Graph", icon: "settings" },
+			{ path: "/fuzzy-redirects", label: "Fuzzy Redirects", icon: "arrow-right" },
+		],
+		options: {},
+	};
+}
+
+export function createPlugin() {
+	return definePlugin({
+		id: "seo-graph",
+		version: "0.5.0",
+		capabilities: ["content:read", "hooks.page-fragments:register", "network:request"],
+		allowedHosts: ["api.indexnow.org"],
+
+		hooks: {
+			"page:metadata": {
+				handler: metadataHandler,
+				priority: 10,
+			},
+			"content:afterPublish": {
+				handler: handleIndexNowTransition,
+				priority: 50,
+			},
+			"content:afterUnpublish": {
+				handler: handleIndexNowTransition,
+				priority: 50,
+			},
+		},
+
+		routes: {
+			settings: {
+				handler: async (ctx: RouteContext) => {
+					const entries = await ctx.kv.list("settings:");
+					const settings: Record<string, string> = {};
+					for (const { key, value } of entries) {
+						const k = key.replace("settings:", "");
+						settings[k] = typeof value === "string" ? value : String(value);
+					}
+					return { settings };
+				},
+			},
+			"settings/save": {
+				handler: async (ctx: RouteContext) => {
+					const { settings } = ctx.input as { settings: Record<string, string> };
+					for (const [key, value] of Object.entries(settings)) {
+						await ctx.kv.set(`settings:${key}`, value);
+					}
+					return { ok: true };
+				},
+			},
+			"indexnow/key": {
+				handler: async (ctx: RouteContext) => {
+					const key = await getOrCreateIndexNowKey(ctx);
+					return { key, keyFile: await getKeyFileBody(ctx) };
+				},
+			},
+			"llms/txt": {
+				public: true,
+				handler: async (ctx: RouteContext) => {
+					const body = await generateLlmsTxt(ctx);
+					return { enabled: body !== null, body: body ?? "" };
+				},
+			},
+			"schema/map": {
+				public: true,
+				handler: async (ctx: RouteContext) => {
+					const items = await listSchemaEntries(ctx);
+					return { items };
+				},
+			},
+		},
+
+		admin: {
+			pages: [
+				{ path: "/settings", label: "SEO Graph", icon: "settings" },
+				{ path: "/fuzzy-redirects", label: "Fuzzy Redirects", icon: "arrow-right" },
+			],
+		},
+	});
+}
+
+export default createPlugin;

package/src/indexnow.ts

@@ -0,0 +1,139 @@
+import {
+	generateIndexNowKey,
+	getIndexNowKeyFileContent,
+	submitToIndexNow,
+	validateIndexNowKey,
+} from "@jdevalk/seo-graph-core";
+import type { PluginContext } from "dineway";
+
+import { buildPageUrl } from "./urls.js";
+
+const KEY_KV = "indexnow:key";
+const ENABLED_KV = "settings:indexnowEnabled";
+
+/**
+ * Read or lazily generate the IndexNow key. The key is persisted in plugin
+ * KV so subsequent submissions (and the key-file route exposed on the
+ * Astro front-end) use the same value. Key rotation is a manual action:
+ * delete the KV entry and the next call will mint a new one.
+ */
+export async function getOrCreateIndexNowKey(ctx: PluginContext): Promise<string> {
+	const existing = await ctx.kv.get(KEY_KV);
+	if (typeof existing === "string" && validateIndexNowKey(existing)) {
+		return existing;
+	}
+	const key = generateIndexNowKey(32);
+	await ctx.kv.set(KEY_KV, key);
+	return key;
+}
+
+/** True when the admin has opted in via the settings toggle. */
+export async function isIndexNowEnabled(ctx: PluginContext): Promise<boolean> {
+	const raw = await ctx.kv.get(ENABLED_KV);
+	if (raw === true) return true;
+	if (typeof raw === "string") return raw === "true" || raw === "1";
+	return false;
+}
+
+/**
+ * Build the canonical URL for a published content item using the
+ * collection's `urlPattern`. Returns `null` when the collection has no
+ * pattern or the content lacks a slug (e.g. unpublished draft without a
+ * resolvable URL).
+ */
+async function urlForContent(
+	content: Record<string, unknown>,
+	collection: string,
+	siteUrl: string,
+): Promise<string | null> {
+	const slug = typeof content.slug === "string" ? content.slug : null;
+	if (!slug) return null;
+
+	const { getCollectionInfo, getI18nConfig, isI18nEnabled } = await import("dineway");
+
+	let info;
+	try {
+		info = await getCollectionInfo(collection);
+	} catch {
+		return null;
+	}
+	if (!info?.urlPattern) return null;
+
+	const locale = typeof content.locale === "string" && content.locale ? content.locale : null;
+
+	// Non-i18n sites: fall back to a minimal pattern substitution that
+	// doesn't require an I18nConfig. buildPageUrl demands a cfg, so fake a
+	// single-locale config when i18n is disabled.
+	const cfg =
+		isI18nEnabled() && getI18nConfig()
+			? getI18nConfig()!
+			: {
+					locales: [locale ?? "en"],
+					defaultLocale: locale ?? "en",
+					prefixDefaultLocale: false,
+				};
+
+	return buildPageUrl({
+		locale: locale ?? cfg.defaultLocale,
+		slug,
+		siteUrl,
+		cfg,
+		urlPattern: info.urlPattern,
+	});
+}
+
+/**
+ * Handler for `content:afterPublish` and `content:afterUnpublish`.
+ * Submits the transitioned URL to IndexNow so participating engines
+ * recrawl and pick up the new state (including 410/404 for unpublished
+ * content). Fire-and-forget: never throws, logs errors on ctx.log.
+ */
+export async function handleIndexNowTransition(
+	event: { content: Record<string, unknown>; collection: string },
+	ctx: PluginContext,
+): Promise<void> {
+	try {
+		if (!(await isIndexNowEnabled(ctx))) return;
+
+		const siteUrl = ctx.site.url;
+		if (!siteUrl) return;
+
+		const url = await urlForContent(event.content, event.collection, siteUrl);
+		if (!url) return;
+
+		let host: string;
+		try {
+			host = new URL(siteUrl).hostname;
+		} catch {
+			return;
+		}
+
+		const key = await getOrCreateIndexNowKey(ctx);
+
+		const results = await submitToIndexNow({
+			host,
+			key,
+			urls: [url],
+		});
+
+		for (const r of results) {
+			if (r.ok) {
+				ctx.log.info("IndexNow: submitted", { url, status: r.status });
+			} else {
+				ctx.log.warn("IndexNow: submission failed", {
+					url,
+					status: r.status,
+					message: r.message,
+				});
+			}
+		}
+	} catch (error) {
+		ctx.log.warn("IndexNow: transition handler error", { error });
+	}
+}
+
+/** Returns the plain-text body to serve at `/<key>.txt`. */
+export async function getKeyFileBody(ctx: PluginContext): Promise<string> {
+	const key = await getOrCreateIndexNowKey(ctx);
+	return getIndexNowKeyFileContent(key);
+}

package/src/llms.ts

@@ -0,0 +1,151 @@
+import type { PluginContext } from "dineway";
+
+import { buildPageUrl } from "./urls.js";
+
+const ENABLED_KV = "settings:llmsTxtEnabled";
+const TRAILING_NEWLINES_RE = /\n+$/;
+const HUMANIZE_SEPARATOR_RE = /[-_]+/g;
+const WORD_START_RE = /\b\w/g;
+
+/**
+ * A single link entry in an `llms.txt` section.
+ *
+ * Spec: https://llmstxt.org/ uses a list item of form
+ * `- [name](url): optional description`.
+ */
+export interface LlmsTxtEntry {
+	title: string;
+	url: string;
+	description?: string;
+}
+
+export interface LlmsTxtBuildOptions {
+	/** Heading at the top of the file. */
+	siteName: string;
+	/** Optional blockquote blurb immediately below the heading. */
+	siteDescription?: string;
+	/** Ordered map of section heading to entries. Empty sections are skipped. */
+	sections: Record<string, LlmsTxtEntry[]>;
+}
+
+/**
+ * Render a small-form `llms.txt` body from structured input.
+ *
+ * The `llms-full.txt` variant is intentionally out of scope for this plugin.
+ */
+export function buildLlmsTxt(opts: LlmsTxtBuildOptions): string {
+	const lines: string[] = [];
+	lines.push(`# ${opts.siteName}`, "");
+	if (opts.siteDescription) {
+		lines.push(`> ${opts.siteDescription}`, "");
+	}
+	for (const [heading, entries] of Object.entries(opts.sections)) {
+		if (!entries.length) continue;
+		lines.push(`## ${heading}`, "");
+		for (const entry of entries) {
+			const desc = entry.description ? `: ${entry.description}` : "";
+			lines.push(`- [${entry.title}](${entry.url})${desc}`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n").replace(TRAILING_NEWLINES_RE, "\n");
+}
+
+/**
+ * True when llms.txt generation is active. Enabled by default; flip
+ * `settings:llmsTxtEnabled` to `"false"` in the admin to turn it off.
+ */
+export async function isLlmsTxtEnabled(ctx: PluginContext): Promise<boolean> {
+	const raw = await ctx.kv.get(ENABLED_KV);
+	if (raw === false) return false;
+	if (typeof raw === "string") return !(raw === "false" || raw === "0");
+	return true;
+}
+
+function humanize(slug: string): string {
+	return slug
+		.replace(HUMANIZE_SEPARATOR_RE, " ")
+		.replace(WORD_START_RE, (char) => char.toUpperCase());
+}
+
+/**
+ * Pull published entries across every collection with a `urlPattern`
+ * and assemble an `llms.txt` body.
+ *
+ * Returns `null` when the feature is disabled or content/site URL access is
+ * unavailable. Collections without a public URL pattern are skipped.
+ */
+export async function generateLlmsTxt(ctx: PluginContext): Promise<string | null> {
+	if (!(await isLlmsTxtEnabled(ctx))) return null;
+	if (!ctx.content) return null;
+
+	const siteUrl = ctx.site.url;
+	if (!siteUrl) return null;
+
+	const { SchemaRegistry, isI18nEnabled, getI18nConfig } = await import("dineway");
+	const { getDb } = await import("dineway/runtime");
+	const db = await getDb();
+	const registry = new SchemaRegistry(db);
+	const collections = await registry.listCollections();
+
+	const cfg =
+		isI18nEnabled() && getI18nConfig()
+			? getI18nConfig()!
+			: { locales: ["en"], defaultLocale: "en", prefixDefaultLocale: false };
+
+	const settings = await ctx.kv.list("settings:");
+	const get = (key: string): string => {
+		const hit = settings.find((entry) => entry.key === `settings:${key}`);
+		return typeof hit?.value === "string" ? hit.value : "";
+	};
+
+	const siteName = ctx.site.name || get("personName") || get("orgName") || "Site";
+	const siteDescription = get("llmsTxtDescription") || get("defaultDescription") || undefined;
+
+	const sections: Record<string, LlmsTxtEntry[]> = {};
+
+	for (const collection of collections) {
+		if (!collection.urlPattern) continue;
+
+		const entries: LlmsTxtEntry[] = [];
+		let cursor: string | undefined;
+		do {
+			const page = await ctx.content.list(collection.slug, {
+				limit: 100,
+				cursor,
+				where: { status: "published" },
+			});
+			for (const item of page.items) {
+				if (!item.slug) continue;
+				const locale = item.locale || cfg.defaultLocale;
+
+				const url = buildPageUrl({
+					locale,
+					slug: item.slug,
+					siteUrl,
+					cfg,
+					urlPattern: collection.urlPattern,
+				});
+				if (!url) continue;
+
+				const title =
+					(typeof item.data.title === "string" && item.data.title) ||
+					(typeof item.data.name === "string" && item.data.name) ||
+					item.slug;
+				const description =
+					(typeof item.data.description === "string" && item.data.description) ||
+					(typeof item.data.excerpt === "string" && item.data.excerpt) ||
+					undefined;
+
+				entries.push({ title, url, description });
+			}
+			cursor = page.cursor;
+		} while (cursor);
+
+		if (entries.length) {
+			sections[collection.label || humanize(collection.slug)] = entries;
+		}
+	}
+
+	return buildLlmsTxt({ siteName, siteDescription, sections });
+}

package/src/metadata.ts

@@ -0,0 +1,93 @@
+import type { PageMetadataEvent, PageMetadataContribution, PluginContext } from "dineway";
+
+import { generateCanonical } from "./canonical.js";
+import { generateDescription } from "./descriptions.js";
+import { generateHreflang } from "./hreflang.js";
+import { generateOpengraph } from "./opengraph.js";
+import { generateRobots } from "./robots.js";
+import { buildSchemaGraph } from "./schema/index.js";
+import { loadSettings } from "./settings.js";
+import { fetchPageTerms } from "./terms.js";
+import { generateOgTitle } from "./titles.js";
+
+/**
+ * Main page:metadata hook handler.
+ * Orchestrates all SEO contribution modules.
+ */
+export async function metadataHandler(
+	event: PageMetadataEvent,
+	ctx: PluginContext,
+): Promise<PageMetadataContribution[]> {
+	const { page } = event;
+	const settings = await loadSettings(ctx.kv);
+	const siteUrl = ctx.site.url;
+	const siteName = page.siteName || ctx.site.name;
+	const locale = page.locale || ctx.site.locale || "en";
+
+	const contributions: PageMetadataContribution[] = [];
+
+	// 1. OG title (page title without site name)
+	const ogTitle = generateOgTitle(page, settings);
+
+	// 2. Description
+	const description = generateDescription(page, settings);
+
+	// 3. Meta description
+	if (description) {
+		contributions.push({ kind: "meta", name: "description", content: description });
+	}
+
+	// 4. Robots
+	const robots = generateRobots(page);
+	if (robots) {
+		contributions.push({ kind: "meta", name: "robots", content: robots });
+	}
+
+	// 5. Canonical
+	const canonical = generateCanonical(page, siteUrl);
+	if (canonical) {
+		contributions.push({ kind: "link", rel: "canonical", href: canonical });
+	}
+
+	// 5b. hreflang alternates (multilingual content sites only)
+	// Short-circuits internally when i18n is disabled — zero cost on
+	// single-locale sites.
+	const hreflangContributions = await generateHreflang(page, ctx, siteUrl);
+	contributions.push(...hreflangContributions);
+
+	// 6. Open Graph + Twitter
+	const ogContributions = generateOpengraph(
+		page,
+		settings,
+		ogTitle,
+		description,
+		canonical,
+		locale,
+	);
+	contributions.push(...ogContributions);
+
+	// 7. JSON-LD Schema graph (replaces base "primary" JSON-LD)
+	const { keywords, articleSection } = await fetchPageTerms(page);
+	const schema = buildSchemaGraph(
+		page,
+		settings,
+		siteUrl,
+		siteName,
+		canonical,
+		ogTitle,
+		description,
+		locale,
+		keywords,
+		articleSection,
+	);
+	if (schema) {
+		contributions.push({ kind: "jsonld", id: "primary", graph: schema });
+	}
+
+	// 8. NLWeb discovery link
+	if (settings.nlwebEndpoint) {
+		contributions.push({ kind: "link", rel: "nlweb", href: settings.nlwebEndpoint });
+	}
+
+	return contributions;
+}