@dineway-ai/plugin-seo-graph 0.1.7

package/README.md

@@ -0,0 +1,227 @@
+# Dineway SEO Graph Plugin
+
+An SEO Graph plugin for [Dineway Agentic Web](https://github.com/foodism-dev/foodism-dineway) that generates meta tags, Open Graph, Twitter Cards, canonical URLs, robots directives, and JSON-LD schema markup via the `page:metadata` hook.
+
+## Features
+
+- **Meta descriptions** with configurable fallback chain
+- **Meta robots** with `max-snippet`, `max-image-preview`, and `max-video-preview` directives; `noindex` for search/utility pages; omitted on 404
+- **Canonical URLs** — absolute, normalized, with trailing slash and pagination support
+- **Open Graph** — `og:title` without site name suffix, `og:type: article` for content pages, full set of OG tags
+- **Twitter Cards** — `summary_large_image` when image present, site handle from settings
+- **JSON-LD schema graph** with linked nodes:
+  - `Person` or `Organization` (configurable), with `publishingPrinciples`
+  - `WebSite` with `SearchAction` and optional `SiteNavigationElement`
+  - `Blog` entity (when blog URL is configured)
+  - `WebPage` (`CollectionPage` for archives, `ProfilePage` for `/about`), with `about`, copyright, and license fields
+  - `BlogPosting` with author `Person` (for content pages), linked to `Blog` when configured, with taxonomy-derived `keywords` and `articleSection`
+  - `ImageObject` for primary page images
+  - `BreadcrumbList` with a back-reference from `WebPage`
+- **Breadcrumbs** — derived from the URL path by default, with segment label overrides (`/blog/` → "Blog") and per-`pageType` rule overrides both editable in the admin UI. `@id` scheme matches [joost.blog](https://joost.blog) via `@jdevalk/seo-graph-core`
+- **hreflang alternates** — for multilingual Dineway sites (Astro `i18n` + `translation_group`), one `<link rel="alternate" hreflang="…">` per published sibling plus an automatic `x-default`, with BCP 47 tag normalization (`fr-ca` → `fr-CA`). Zero cost on single-locale sites
+- **llms.txt** — exposes a small-form [llms.txt](https://llmstxt.org) index of published content at the plugin's `llms/txt` route. Enabled by default; flip the setting to disable
+- **Schema map** — exposes every published URL backed by schema markup at the public `schema/map` plugin route for agent/crawler discovery
+- **Fuzzy Redirects** — admin tool that mines the core 404 log, ranks live URLs by path similarity, and lets editors create 301 redirects for moved slugs, typos, and punctuation drift
+- **NLWeb `<link>` tag** — when the **NLWeb endpoint URL** setting is set, every rendered page carries `<link rel="nlweb" href="…">` for conversational agent discovery
+- **IndexNow** — on publish/unpublish transitions, submits the affected URL to [IndexNow](https://www.indexnow.org) so Bing, Yandex, Seznam, Naver, and Yep recrawl immediately. Opt-in via a single toggle in the settings UI; the key is generated and persisted automatically on first use
+- **Admin settings UI** — auto-generated from `settingsSchema` for configuring Person/Organization identity, social profiles, title separator, and default description
+
+## Installation
+
+Copy the `src/` directory into your Dineway theme's `plugins/seo-graph/` directory, or install from this repo:
+
+```bash
+# In your dineway theme directory
+cp -r path/to/dineway-plugin-seo-graph/src plugins/seo-graph/src
+cp path/to/dineway-plugin-seo-graph/package.json plugins/seo-graph/package.json
+```
+
+## Usage
+
+Register the plugin in your `astro.config.mjs`:
+
+```typescript
+import { seoGraphPlugin } from "./plugins/seo-graph/src/index.ts";
+
+export default defineConfig({
+	integrations: [
+		dineway({
+			plugins: [seoGraphPlugin()],
+		}),
+	],
+});
+```
+
+Then configure your site identity and social profiles in the Dineway admin under **Plugins > SEO Graph > Settings**.
+
+## Settings
+
+| Setting                                     | Description                                                                                         |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Site represents                             | Person or Organization                                                                              |
+| Title separator                             | Character between page title and site name (em dash, pipe, hyphen, dot)                             |
+| Default meta description                    | Fallback for pages without their own                                                                |
+| Person name / bio / image / job title / URL | Person schema fields                                                                                |
+| Organization name / logo URL                | Organization schema fields                                                                          |
+| Social URLs                                 | Twitter/X, Facebook, LinkedIn, Instagram, YouTube, GitHub, Bluesky, Mastodon, Wikipedia             |
+| Publishing principles URL                   | Link to editorial policy page                                                                       |
+| Copyright year                              | Year copyright was first asserted                                                                   |
+| License URL                                 | Content license (e.g. Creative Commons)                                                             |
+| Blog URL / name                             | Enables `Blog` schema entity linked to `BlogPosting` nodes                                          |
+| Navigation items                            | JSON array of `{name, url}` for `SiteNavigationElement` schema                                      |
+| Breadcrumb segment labels                   | `segment → display label` overrides (e.g. `blog → Blog`)                                            |
+| Breadcrumb page type rules                  | Per-`pageType` ordered crumb lists, JSON-edited, for themes that need full control over trail shape |
+| IndexNow submission                         | Submit published/unpublished URLs to IndexNow. Disabled by default                                  |
+| llms.txt                                    | Expose an `llms.txt` index of published content. Enabled by default                                 |
+| llms.txt site description                   | Optional blockquote text at the top of `llms.txt`. Falls back to the default meta description       |
+| NLWeb endpoint URL                          | Absolute URL of the site's conversational endpoint, emitted as `<link rel="nlweb">`                 |
+
+## Multilingual sites (hreflang)
+
+When your site has more than one locale configured in Astro's `i18n` block and content entries are linked via `translation_group`, the plugin automatically emits hreflang annotations for each content page. No configuration required — it activates as soon as `isI18nEnabled()` returns true.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+	i18n: {
+		defaultLocale: "en",
+		locales: ["en", "fr", "nl"],
+		routing: { prefixDefaultLocale: false },
+	},
+	integrations: [dineway({ plugins: [seoGraphPlugin()] })],
+});
+```
+
+A 3-locale post at `/hello/`, with published French (`/fr/bonjour/`) and Dutch (`/nl/hallo/`) translations in the same `translation_group`, renders:
+
+```html
+<link rel="alternate" hreflang="en" href="https://example.com/hello/" />
+<link rel="alternate" hreflang="fr" href="https://example.com/fr/bonjour/" />
+<link rel="alternate" hreflang="nl" href="https://example.com/nl/hallo/" />
+<link rel="alternate" hreflang="x-default" href="https://example.com/hello/" />
+```
+
+Only published siblings are included. Drafts, scheduled entries, and siblings whose locale is no longer in your Astro config are dropped. If the page has fewer than two published locales, no hreflang tags are emitted (a single-locale page has no meaningful alternates).
+
+### Region-specific locales (`fr-CA` vs `fr-FR`)
+
+If you need region-specific hreflang, use the BCP 47 code as the locale path directly:
+
+```js
+i18n: {
+  defaultLocale: "en",
+  locales: ["en", "fr-ca", "fr-fr"],
+}
+```
+
+URLs become `/fr-ca/…` and `/fr-fr/…`, and the emitted `hreflang` attributes are normalized to conventional casing (`fr-CA`, `fr-FR`). Dineway core currently drops Astro's object-form `{ path, codes }` shape at the integration boundary, so the code-as-path workaround is the supported path for region tags in this plugin version.
+
+## IndexNow
+
+When enabled via the **IndexNow submission** setting, the plugin submits
+the canonical URL of any content item that transitions to or from
+published. A 32-character hex key is minted on first use and persisted in
+plugin KV.
+
+The front-end Astro site must serve the key-verification file at
+`/<key>.txt`. Fetch the key from the plugin's `indexnow/key` route and
+wire a route on the Astro side using
+[`createIndexNowKeyRoute`](https://www.npmjs.com/package/@jdevalk/astro-seo-graph):
+
+```ts
+// src/pages/[your-key-here].txt.ts
+import { createIndexNowKeyRoute } from "@jdevalk/astro-seo-graph";
+
+export const GET = createIndexNowKeyRoute({ key: "your-key-here" });
+```
+
+> **Deploy the key file before enabling the toggle.** IndexNow verifies
+> host ownership on every submission by fetching
+> `https://<host>/<key>.txt`. Submissions sent before the key file is
+> reachable in production are rejected (HTTP 403) and the key gets
+> marked invalid — you'll have to delete the stored key from plugin KV
+> and mint a new one. Ship the Astro route, deploy, confirm the `.txt`
+> loads over HTTPS, _then_ flip the **IndexNow submission** toggle.
+
+When rejections occur, the plugin logs on `ctx.log.warn` but does not
+throw — transitions still succeed locally.
+
+## llms.txt
+
+The plugin generates a small-form [`llms.txt`](https://llmstxt.org) index of all published content, grouped by collection label, and exposes it on the plugin route `llms/txt`. Only collections with a `urlPattern` are included. The `llms-full.txt` variant is out of scope.
+
+Serve it from your Astro site by creating an endpoint that proxies the plugin route:
+
+```ts
+// src/pages/llms.txt.ts
+import type { APIRoute } from "astro";
+
+export const GET: APIRoute = async ({ request }) => {
+	const origin = new URL(request.url).origin;
+	const res = await fetch(`${origin}/_dineway/api/plugins/seo-graph/llms/txt`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: "{}",
+	});
+	const { data } = (await res.json()) as { data: { enabled: boolean; body: string } };
+	if (!data.enabled) return new Response("Not found", { status: 404 });
+	return new Response(data.body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+};
+```
+
+## Fuzzy Redirects
+
+The admin page at **Plugins > SEO Graph > Fuzzy Redirects** turns Dineway's core 404 log into a redirect work queue. It fetches published URLs from `schema/map`, scores them against each missing path with Levenshtein distance, token overlap, and last-segment matching, then lets an editor create a 301 redirect. Created redirects are grouped under `seo-graph-fuzzy-suggester` for later auditing.
+
+## Schema Map
+
+The public `schema/map` plugin route returns JSON shaped for a `schemamap.xml` endpoint:
+
+```json
+{
+	"data": {
+		"items": [
+			{
+				"url": "https://example.com/journal/spring-menu/",
+				"collection": "posts",
+				"updatedAt": "2026-02-01T00:00:00Z"
+			}
+		]
+	}
+}
+```
+
+Wire it to `/schemamap.xml` at your site root with a small Astro endpoint:
+
+```ts
+// src/pages/schemamap.xml.ts
+import type { APIRoute } from "astro";
+
+interface SchemaMapEntry {
+	url: string;
+	collection: string;
+	updatedAt: string;
+}
+
+export const GET: APIRoute = async ({ request }) => {
+	const origin = new URL(request.url).origin;
+	const res = await fetch(`${origin}/_dineway/api/plugins/seo-graph/schema/map`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: "{}",
+	});
+	const { data } = (await res.json()) as { data: { items: SchemaMapEntry[] } };
+
+	const urls = data.items
+		.map(({ url, updatedAt }) => `  <url><loc>${url}</loc><lastmod>${updatedAt}</lastmod></url>`)
+		.join("\n");
+
+	return new Response(
+		`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`,
+		{ headers: { "Content-Type": "application/xml; charset=utf-8" } },
+	);
+};
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dineway-ai/plugin-seo-graph",
+  "version": "0.1.7",
+  "description": "SEO Graph plugin for the Dineway Agentic Website builder — meta tags, Open Graph, canonical URLs, robots directives, and JSON-LD schema markup",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "dineway",
+    "seo",
+    "schema",
+    "json-ld",
+    "open-graph",
+    "meta-tags",
+    "canonical",
+    "robots",
+    "llms.txt",
+    "schema-map",
+    "indexnow"
+  ],
+  "author": "Dineway",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "dineway": "workspace:*"
+  },
+  "dependencies": {
+    "@jdevalk/astro-seo-graph": "^0.7.0",
+    "@jdevalk/seo-graph-core": "^0.6.0",
+    "schema-dts": "^2.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "catalog:",
+    "dineway": "workspace:*",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/admin-redirects.tsx

@@ -0,0 +1,317 @@
+import { apiFetch as baseFetch, getErrorMessage, parseApiResponse } from "dineway/plugin-utils";
+import * as React from "react";
+
+import { rankCandidates, type RankedMatch } from "./fuzzy.js";
+
+const PLUGIN_API = "/_dineway/api/plugins/seo-graph";
+const CORE_API = "/_dineway/api";
+
+interface NotFoundSummary {
+	path: string;
+	count: number;
+	lastSeen: string;
+	topReferrer: string | null;
+}
+
+interface SchemaMapEntry {
+	url: string;
+	collection: string;
+	updatedAt: string;
+}
+
+interface Suggestion {
+	entry: NotFoundSummary;
+	matches: RankedMatch[];
+	chosen: string;
+	created: boolean;
+	error: string | null;
+	saving: boolean;
+}
+
+async function fetchNotFoundSummary(): Promise<NotFoundSummary[]> {
+	const res = await baseFetch(`${CORE_API}/redirects/404s/summary?limit=100`, {
+		method: "GET",
+	});
+	const data = await parseApiResponse<{ items: NotFoundSummary[] }>(
+		res,
+		"Failed to load 404 summary",
+	);
+	return data.items ?? [];
+}
+
+async function fetchSchemaMap(): Promise<SchemaMapEntry[]> {
+	const res = await baseFetch(`${PLUGIN_API}/schema/map`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: "{}",
+	});
+	const data = await parseApiResponse<{ items: SchemaMapEntry[] }>(
+		res,
+		"Failed to load schema map",
+	);
+	return data.items ?? [];
+}
+
+async function createRedirect(source: string, destination: string): Promise<void> {
+	const res = await baseFetch(`${CORE_API}/redirects`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			source,
+			destination,
+			type: 301,
+			enabled: true,
+			groupName: "seo-graph-fuzzy-suggester",
+		}),
+	});
+	if (!res.ok) {
+		throw new Error(await getErrorMessage(res, "Failed to create redirect"));
+	}
+}
+
+function urlToPath(url: string): string {
+	try {
+		return new URL(url).pathname;
+	} catch {
+		return url;
+	}
+}
+
+const rowStyle: React.CSSProperties = {
+	border: "1px solid #e5e7eb",
+	borderRadius: 8,
+	padding: "1rem",
+	marginBottom: "0.75rem",
+	background: "#fff",
+};
+
+const codeStyle: React.CSSProperties = {
+	fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+	fontSize: "0.8125rem",
+	background: "#f3f4f6",
+	padding: "2px 6px",
+	borderRadius: 4,
+};
+
+const inputStyle: React.CSSProperties = {
+	width: "100%",
+	padding: "0.375rem 0.5rem",
+	borderRadius: 6,
+	border: "1px solid #d1d5db",
+	fontSize: "0.8125rem",
+	fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+};
+
+const primaryButtonStyle: React.CSSProperties = {
+	padding: "0.375rem 0.875rem",
+	borderRadius: 6,
+	background: "#4a1525",
+	color: "white",
+	border: "none",
+	cursor: "pointer",
+	fontSize: "0.8125rem",
+	fontWeight: 500,
+};
+
+export function FuzzyRedirectsPage() {
+	const [loading, setLoading] = React.useState(true);
+	const [loadError, setLoadError] = React.useState<string | null>(null);
+	const [suggestions, setSuggestions] = React.useState<Suggestion[]>([]);
+	const [minScore, setMinScore] = React.useState(0.5);
+
+	const load = React.useCallback(async () => {
+		setLoading(true);
+		setLoadError(null);
+		try {
+			const [log, map] = await Promise.all([fetchNotFoundSummary(), fetchSchemaMap()]);
+			const candidatePaths = map.map((entry) => urlToPath(entry.url));
+			const next: Suggestion[] = log.map((entry) => {
+				const matches = rankCandidates(entry.path, candidatePaths, { limit: 3, minScore });
+				return {
+					entry,
+					matches,
+					chosen: matches[0]?.candidate ?? "",
+					created: false,
+					error: null,
+					saving: false,
+				};
+			});
+			setSuggestions(next);
+		} catch (err) {
+			setLoadError(err instanceof Error ? err.message : String(err));
+		} finally {
+			setLoading(false);
+		}
+	}, [minScore]);
+
+	React.useEffect(() => {
+		void load();
+	}, [load]);
+
+	const updateRow = (index: number, patch: Partial<Suggestion>) => {
+		setSuggestions((prev) => prev.map((s, i) => (i === index ? { ...s, ...patch } : s)));
+	};
+
+	const handleCreate = async (index: number) => {
+		const row = suggestions[index];
+		if (!row?.chosen) return;
+		updateRow(index, { saving: true, error: null });
+		try {
+			await createRedirect(row.entry.path, row.chosen);
+			updateRow(index, { saving: false, created: true });
+		} catch (err) {
+			updateRow(index, {
+				saving: false,
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	};
+
+	const visible = suggestions.filter((suggestion) => !suggestion.created);
+
+	return (
+		<div style={{ maxWidth: 820, padding: "1.5rem 0" }}>
+			<h1 style={{ fontSize: "1.5rem", fontWeight: 700, marginBottom: "0.5rem" }}>
+				Fuzzy Redirects
+			</h1>
+			<p style={{ fontSize: "0.875rem", color: "#4b5563", marginBottom: "1.5rem" }}>
+				Reviews the 404 log, pairs each missing path with the closest matching published URLs, and
+				lets you create a 301 redirect. Matches are scored by path similarity, and the slider tunes
+				how aggressive suggestions are.
+			</p>
+
+			<div style={{ display: "flex", alignItems: "center", gap: 16, marginBottom: "1rem" }}>
+				<label style={{ fontSize: "0.8125rem", color: "#4b5563" }}>
+					Minimum match score: <strong>{minScore.toFixed(2)}</strong>
+					<input
+						type="range"
+						min="0"
+						max="1"
+						step="0.05"
+						value={minScore}
+						onChange={(event) => setMinScore(parseFloat(event.target.value))}
+						style={{ marginLeft: 8, verticalAlign: "middle" }}
+					/>
+				</label>
+				<button
+					onClick={() => void load()}
+					disabled={loading}
+					style={{
+						padding: "0.375rem 0.75rem",
+						borderRadius: 6,
+						background: "#f3f4f6",
+						color: "#374151",
+						border: "1px solid #d1d5db",
+						cursor: loading ? "wait" : "pointer",
+						fontSize: "0.8125rem",
+					}}
+				>
+					{loading ? "Loading..." : "Refresh"}
+				</button>
+			</div>
+
+			{loadError && (
+				<div
+					style={{
+						padding: "0.75rem",
+						background: "#fef2f2",
+						color: "#991b1b",
+						borderRadius: 6,
+						marginBottom: "1rem",
+						fontSize: "0.875rem",
+					}}
+				>
+					Failed to load: {loadError}
+				</div>
+			)}
+
+			{!loading && !loadError && suggestions.length === 0 && (
+				<div
+					style={{ padding: "2rem", textAlign: "center", color: "#6b7280", fontSize: "0.875rem" }}
+				>
+					No 404s logged. Hit a dead link on the live site to populate the log.
+				</div>
+			)}
+
+			{!loading && !loadError && suggestions.length > 0 && visible.length === 0 && (
+				<div
+					style={{ padding: "2rem", textAlign: "center", color: "#16a34a", fontSize: "0.875rem" }}
+				>
+					All suggestions handled.
+				</div>
+			)}
+
+			{visible.map((row) => {
+				const index = suggestions.indexOf(row);
+				return (
+					<div key={row.entry.path} style={rowStyle}>
+						<div style={{ marginBottom: "0.5rem" }}>
+							<span style={codeStyle}>{row.entry.path}</span>
+							<span style={{ marginLeft: 12, fontSize: "0.75rem", color: "#6b7280" }}>
+								{row.entry.count} hit{row.entry.count === 1 ? "" : "s"}
+								{row.entry.topReferrer ? ` from ${row.entry.topReferrer}` : ""}
+							</span>
+						</div>
+
+						{row.matches.length === 0 ? (
+							<div style={{ fontSize: "0.8125rem", color: "#9ca3af", fontStyle: "italic" }}>
+								No matches above the score threshold. Enter a destination manually if you know one.
+							</div>
+						) : (
+							<div style={{ marginBottom: "0.5rem" }}>
+								{row.matches.map((match) => (
+									<label
+										key={match.candidate}
+										style={{
+											display: "flex",
+											alignItems: "center",
+											gap: 8,
+											marginBottom: 4,
+											fontSize: "0.8125rem",
+										}}
+									>
+										<input
+											type="radio"
+											name={`dest-${index}`}
+											checked={row.chosen === match.candidate}
+											onChange={() => updateRow(index, { chosen: match.candidate })}
+										/>
+										<span style={codeStyle}>{match.candidate}</span>
+										<span style={{ color: "#6b7280", fontSize: "0.75rem" }}>
+											score {match.score.toFixed(2)}
+										</span>
+									</label>
+								))}
+							</div>
+						)}
+
+						<div style={{ display: "flex", gap: 8, alignItems: "center", marginTop: "0.5rem" }}>
+							<input
+								type="text"
+								value={row.chosen}
+								onChange={(event) => updateRow(index, { chosen: event.target.value })}
+								placeholder="/destination/path"
+								style={{ ...inputStyle, flex: 1 }}
+							/>
+							<button
+								onClick={() => void handleCreate(index)}
+								disabled={row.saving || !row.chosen}
+								style={{
+									...primaryButtonStyle,
+									cursor: row.saving ? "wait" : row.chosen ? "pointer" : "not-allowed",
+									opacity: row.chosen ? 1 : 0.5,
+								}}
+							>
+								{row.saving ? "Creating..." : "Create redirect"}
+							</button>
+						</div>
+
+						{row.error && (
+							<div style={{ marginTop: 6, fontSize: "0.75rem", color: "#dc2626" }}>{row.error}</div>
+						)}
+					</div>
+				);
+			})}
+		</div>
+	);
+}