@karaoke-cms/module-seo 0.10.3

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@karaoke-cms/module-seo",
+  "type": "module",
+  "version": "0.10.3",
+  "description": "SEO module for karaoke-cms — OG images, JSON-LD, robots.txt",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./pages/robots.txt": "./src/pages/robots.txt.ts"
+  },
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "astro",
+    "cms",
+    "seo",
+    "og-image",
+    "karaoke-cms"
+  ],
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "satori": "^0.10.14"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0",
+    "@karaoke-cms/contracts": "^0.10.3"
+  },
+  "devDependencies": {
+    "astro": "^6.0.8",
+    "vitest": "^4.1.1",
+    "@karaoke-cms/contracts": "0.10.3"
+  },
+  "scripts": {
+    "test": "vitest run test/seo-utils.test.js"
+  }
+}

package/src/css-contract.ts

@@ -0,0 +1,4 @@
+import type { CssContract } from '@karaoke-cms/contracts';
+
+// module-seo has no UI components — no CSS contract needed.
+export const cssContract: CssContract = {};

package/src/generate-og-images.ts

@@ -0,0 +1,265 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import satori from 'satori';
+import { Resvg } from '@resvg/resvg-js';
+import type { AstroIntegrationLogger } from 'astro';
+
+// Load Inter font bundled with the package — resolved relative to this file's location.
+const _fontData = readFileSync(
+  fileURLToPath(new URL('./fonts/inter-latin-400-normal.woff', import.meta.url)),
+);
+
+// ── HTML helpers ──────────────────────────────────────────────────────────────
+
+export function getMeta(html: string, prop: string): string | null {
+  const a = html.match(
+    new RegExp(`<meta[^>]*(?:property|name)=["']${prop}["'][^>]*content=["']([^"']*)["']`, 'i'),
+  );
+  if (a) return a[1];
+  const b = html.match(
+    new RegExp(`<meta[^>]*content=["']([^"']*)["'][^>]*(?:property|name)=["']${prop}["']`, 'i'),
+  );
+  return b ? b[1] : null;
+}
+
+export function hasMeta(html: string, prop: string): boolean {
+  return getMeta(html, prop) !== null;
+}
+
+/**
+ * Derive the OG image path from an og:url value.
+ * https://example.com/blog/my-post/ → /og/blog/my-post.png
+ */
+export function ogImagePath(ogUrl: string): string | null {
+  try {
+    const pathname = new URL(ogUrl).pathname.replace(/\/$/, '');
+    return pathname && pathname !== '/' ? `/og${pathname}.png` : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inject `og:image`, `twitter:image`, `twitter:card`, and JSON-LD into HTML.
+ * Replaces the existing `twitter:card` if already `summary` (upgrades to large image).
+ * Returns the modified HTML string.
+ */
+export function injectSeoTags(
+  html: string,
+  ogImage: string,
+  ogUrl: string,
+  ogType: string | null,
+  title: string | null,
+  description: string | null,
+  siteName: string | null,
+): string {
+  const metaTags = [
+    `<meta property="og:image" content="${ogImage}">`,
+    `<meta name="twitter:image" content="${ogImage}">`,
+  ].join('');
+
+  // Build JSON-LD schema
+  const isArticle = ogType === 'article';
+  const schema: Record<string, unknown> = {
+    '@context': 'https://schema.org',
+    '@type': isArticle ? 'BlogPosting' : 'WebSite',
+    url: ogUrl,
+    ...(title ? { [isArticle ? 'headline' : 'name']: title } : {}),
+    ...(description ? { description } : {}),
+    ...(siteName && !isArticle ? { name: siteName } : {}),
+  };
+  const jsonLd = `<script type="application/ld+json">${JSON.stringify(schema)}</script>`;
+
+  // Upgrade twitter:card from summary → summary_large_image
+  let modified = html.replace(
+    /(<meta[^>]*name=["']twitter:card["'][^>]*content=["'])summary(["'][^>]*>)/gi,
+    '$1summary_large_image$2',
+  ).replace(
+    /(<meta[^>]*content=["'])summary(["'][^>]*name=["']twitter:card["'][^>]*>)/gi,
+    '$1summary_large_image$2',
+  );
+
+  // Inject before </head>
+  modified = modified.replace('</head>', `${metaTags}${jsonLd}</head>`);
+  return modified;
+}
+
+// ── OG image renderer ─────────────────────────────────────────────────────────
+
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function ogTemplate(title: string, description: string | undefined, siteName: string | undefined): object {
+  const safeTitle = escapeHtml(title);
+  const safeDesc = description
+    ? escapeHtml(description.length > 140 ? description.slice(0, 137) + '…' : description)
+    : '';
+  const safeSite = escapeHtml(siteName ?? '');
+  const fontSize = title.length > 60 ? 44 : title.length > 40 ? 52 : 60;
+
+  return {
+    type: 'div',
+    key: null,
+    props: {
+      style: {
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'space-between',
+        width: '100%',
+        height: '100%',
+        padding: '72px 80px',
+        backgroundColor: '#ffffff',
+        fontFamily: 'Inter',
+      },
+      children: [
+        {
+          type: 'div',
+          key: null,
+          props: {
+            style: {
+              display: 'flex',
+              fontSize,
+              fontWeight: 700,
+              color: '#111111',
+              maxWidth: 900,
+              lineHeight: 1.25,
+            },
+            children: safeTitle,
+          },
+        },
+        {
+          type: 'div',
+          key: null,
+          props: {
+            style: {
+              display: 'flex',
+              justifyContent: 'space-between',
+              alignItems: 'flex-end',
+              gap: 40,
+            },
+            children: [
+              safeDesc
+                ? {
+                    type: 'div',
+                    key: null,
+                    props: {
+                      style: {
+                        display: 'flex',
+                        fontSize: 22,
+                        color: '#555555',
+                        maxWidth: 750,
+                        lineHeight: 1.4,
+                        flex: 1,
+                      },
+                      children: safeDesc,
+                    },
+                  }
+                : { type: 'div', key: null, props: { style: { display: 'flex', flex: 1 }, children: '' } },
+              safeSite
+                ? {
+                    type: 'div',
+                    key: null,
+                    props: {
+                      style: { display: 'flex', fontSize: 20, color: '#aaaaaa', flexShrink: 0 },
+                      children: safeSite,
+                    },
+                  }
+                : { type: 'div', key: null, props: { style: { display: 'flex', flexShrink: 0 }, children: '' } },
+            ],
+          },
+        },
+      ],
+    },
+  };
+}
+
+async function renderPng(title: string, description?: string, siteName?: string): Promise<Buffer> {
+  const svg = await satori(ogTemplate(title, description, siteName) as any, {
+    width: 1200,
+    height: 630,
+    fonts: [
+      {
+        name: 'Inter',
+        data: _fontData.buffer as ArrayBuffer,
+        weight: 400,
+        style: 'normal',
+      },
+    ],
+  });
+  return Buffer.from(new Resvg(svg, { fitTo: { mode: 'width', value: 1200 } }).render().asPng());
+}
+
+// ── File walker ───────────────────────────────────────────────────────────────
+
+function* walkHtmlFiles(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) yield* walkHtmlFiles(full);
+    else if (entry.name.endsWith('.html')) yield full;
+  }
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
+/**
+ * Post-build SEO enrichment pass.
+ *
+ * For every HTML page that has `og:url` set (blog posts, docs pages, etc.):
+ * 1. Derives the OG image path from the URL  (e.g. /blog/my-post → /og/blog/my-post.png)
+ * 2. Injects `og:image`, `twitter:image`, `twitter:card` (summary_large_image), and JSON-LD
+ *    into the HTML and writes it back to disk.
+ * 3. Renders a 1200×630 PNG using satori + resvg-js and writes it to `dist/og/…`.
+ *
+ * Runs in the `astro:build:done` hook — plain Node.js, no Vite/Rollup bundling —
+ * so native binaries work without any special configuration.
+ *
+ * Pages that already have `og:image` are skipped (user-provided takes precedence).
+ */
+export async function generateOgImages(dir: URL, logger: AstroIntegrationLogger): Promise<void> {
+  const distPath = fileURLToPath(dir);
+  let generated = 0;
+
+  for (const htmlFile of walkHtmlFiles(distPath)) {
+    let html = readFileSync(htmlFile, 'utf-8');
+
+    // Skip if og:image already set (user-managed)
+    if (hasMeta(html, 'og:image')) continue;
+
+    const ogUrl = getMeta(html, 'og:url');
+    if (!ogUrl) continue;
+
+    const imagePath = ogImagePath(ogUrl);
+    if (!imagePath) continue; // homepage or unparseable URL
+
+    const title       = getMeta(html, 'og:title');
+    const description = getMeta(html, 'og:description') ?? undefined;
+    const ogType      = getMeta(html, 'og:type');
+    const siteName    = getMeta(html, 'og:site_name') ?? undefined;
+
+    if (!title) continue;
+
+    // 1. Inject SEO tags into HTML and write back
+    html = injectSeoTags(html, imagePath, ogUrl, ogType, title, description ?? null, siteName ?? null);
+    writeFileSync(htmlFile, html);
+
+    // 2. Generate PNG (skip if already exists from a previous incremental build)
+    const pngPath = join(distPath, imagePath.slice(1)); // /og/… → dist/og/…
+    if (!existsSync(pngPath)) {
+      const png = await renderPng(title, description, siteName);
+      mkdirSync(dirname(pngPath), { recursive: true });
+      writeFileSync(pngPath, png);
+    }
+
+    generated++;
+  }
+
+  if (generated > 0) {
+    logger.info(`Generated ${generated} OG image${generated === 1 ? '' : 's'}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+import { defineModule } from '@karaoke-cms/contracts';
+import { generateOgImages } from './generate-og-images.js';
+import { cssContract } from './css-contract.js';
+
+export { cssContract } from './css-contract.js';
+
+/**
+ * SEO module — zero-config OG images, JSON-LD structured data, and robots.txt.
+ *
+ * Add to `modules[]` in `karaoke.config.ts` and every published blog post and docs
+ * page will automatically get a social card image, structured data, and a robots.txt.
+ *
+ * @example
+ * // karaoke.config.ts
+ * import { seo } from '@karaoke-cms/module-seo';
+ * export default defineConfig({
+ *   modules: [seo()],
+ * });
+ */
+export const seo = defineModule({
+  id: 'seo',
+  cssContract,
+
+  routes: () => [
+    { pattern: '/robots.txt', entrypoint: '@karaoke-cms/module-seo/pages/robots.txt' },
+  ],
+
+  menuEntries: () => [],
+
+  integration: {
+    name: '@karaoke-cms/module-seo',
+    hooks: {
+      'astro:build:done': async ({ dir, logger }: { dir: URL; logger: any }) => {
+        await generateOgImages(dir, logger);
+      },
+    },
+  },
+});

package/src/pages/robots.txt.ts

@@ -0,0 +1,17 @@
+/**
+ * Robots.txt endpoint.
+ * Disallows the /karaoke-cms/ handbook routes (dev-only, should not be indexed).
+ * Everything else is allowed.
+ */
+export async function GET(): Promise<Response> {
+  const content = [
+    'User-agent: *',
+    'Allow: /',
+    'Disallow: /karaoke-cms/',
+    '',
+  ].join('\n');
+
+  return new Response(content, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}