@lownoise-studio/rendershield 0.1.4

package/src/core/generateWorker.ts

@@ -0,0 +1,80 @@
+import { RenderShieldConfig } from "../types.js";
+
+function jsStringArray(arr: string[]): string {
+  return `[${arr.map((s) => JSON.stringify(s)).join(", ")}]`;
+}
+
+export function generateWorkerJs(cfg: RenderShieldConfig): string {
+  const patterns = cfg.worker.botUserAgentPatterns.map((p) => p.toLowerCase());
+  const rewriteBases = cfg.worker.rewriteRouteBases;
+
+  return `/**
+ * RenderShield Worker (generated)
+ * Serves prerendered /index.html to bots on selected route bases.
+ */
+
+const BOT_SUBSTRINGS = ${jsStringArray(patterns)};
+const REWRITE_BASES = ${jsStringArray(rewriteBases)};
+
+function isBot(ua) {
+  const s = (ua || "").toLowerCase();
+  return BOT_SUBSTRINGS.some((sub) => s.includes(sub));
+}
+
+function shouldRewrite(pathname) {
+  return REWRITE_BASES.some((base) => pathname.startsWith(base));
+}
+
+function toIndexHtml(pathname) {
+  let p = pathname;
+  if (!p.endsWith("/")) p += "/";
+  return p + "index.html";
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    const ua = request.headers.get("User-Agent") || "";
+    const bot = isBot(ua);
+
+    const isGetLike = request.method === "GET" || request.method === "HEAD";
+    const rewrite = bot && isGetLike && shouldRewrite(url.pathname);
+
+    try {
+      if (!rewrite) return fetch(request);
+
+      const origin = ${JSON.stringify(cfg.worker.lovableOrigin)};
+      const finalPath = toIndexHtml(url.pathname);
+      const originUrl = origin + finalPath + url.search;
+
+      const headers = new Headers();
+      headers.set("Accept", "text/html");
+      headers.set("User-Agent", ua);
+
+      const resp = await fetch(originUrl, { method: "GET", headers });
+
+      if (!resp.ok) {
+        const fallbackUrl = origin + url.pathname + url.search;
+        const fb = await fetch(fallbackUrl, { method: "GET", headers });
+        const out = new Response(fb.body, fb);
+        ${cfg.worker.debugHeaders ? `out.headers.set("X-Bot-Detected", "true");
+        out.headers.set("X-Prerender-Fallback", "true");
+        out.headers.set("X-Requested-Path", url.pathname);` : ""}
+        return out;
+      }
+
+      const out = new Response(resp.body, resp);
+      ${cfg.worker.debugHeaders ? `out.headers.set("X-Bot-Detected", "true");
+      out.headers.set("X-Prerender", "true");
+      out.headers.set("X-Final-Path", finalPath);` : ""}
+      return out;
+    } catch (err) {
+      return new Response("Worker error: " + (err && err.message ? err.message : String(err)), {
+        status: 500,
+        headers: { "Content-Type": "text/plain; charset=utf-8" }
+      });
+    }
+  }
+};
+`;
+}

package/src/core/loadConfig.ts

@@ -0,0 +1,74 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { RenderShieldConfig } from "../types.js";
+
+const CONFIG_NAME = "rendershield.config.json";
+
+type BoolFlag = { enabled: boolean };
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function coerceBoolFlag(
+  parsed: any,
+  key: "sitemap" | "robots" | "worker",
+  defaultEnabled: boolean
+): BoolFlag {
+  // If missing, provide defaults (keeps older configs from exploding)
+  if (parsed?.[key] == null) return { enabled: defaultEnabled };
+
+  // If present, validate shape
+  const v = parsed[key];
+  if (!isObject(v)) {
+    throw new Error(`${key} must be an object like { "enabled": true }`);
+  }
+  if (typeof (v as any).enabled !== "boolean") {
+    throw new Error(`${key}.enabled must be a boolean`);
+  }
+  return { enabled: (v as any).enabled };
+}
+
+export async function loadConfig(
+  cwd = process.cwd()
+): Promise<RenderShieldConfig> {
+  const p = path.join(cwd, CONFIG_NAME);
+  const exists = await fs.pathExists(p);
+  if (!exists) {
+    throw new Error(`Missing ${CONFIG_NAME}. Run: rendershield init`);
+  }
+
+  const raw = await fs.readFile(p, "utf8");
+  let parsed: any;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`${CONFIG_NAME} is not valid JSON`);
+  }
+
+  // Minimal validation (v0)
+  if (parsed?.version !== 1) throw new Error(`Config version must be 1`);
+  if (!parsed?.site?.canonicalBase)
+    throw new Error(`site.canonicalBase is required`);
+  if (!parsed?.site?.siteName) throw new Error(`site.siteName is required`);
+  if (!parsed?.site?.defaultOgImage)
+    throw new Error(`site.defaultOgImage is required`);
+  if (!parsed?.site?.authorName)
+    throw new Error(`site.authorName is required`);
+  if (!parsed?.content?.markdown?.baseDir)
+    throw new Error(`content.markdown.baseDir is required`);
+  if (
+    !Array.isArray(parsed?.content?.markdown?.collections) ||
+    parsed.content.markdown.collections.length === 0
+  ) {
+    throw new Error(`content.markdown.collections must be a non-empty array`);
+  }
+  if (!parsed?.output?.outDir) throw new Error(`output.outDir is required`);
+
+  // Validate + default these optional sections to prevent TypeErrors later
+  parsed.sitemap = coerceBoolFlag(parsed, "sitemap", true);
+  parsed.robots = coerceBoolFlag(parsed, "robots", true);
+  parsed.worker = coerceBoolFlag(parsed, "worker", true);
+
+  return parsed as RenderShieldConfig;
+}

package/src/core/loadMarkdown.ts

@@ -0,0 +1,82 @@
+import path from "node:path";
+import fg from "fast-glob";
+import fs from "fs-extra";
+import matter from "gray-matter";
+import MarkdownIt from "markdown-it";
+import { MarkdownDoc, RenderShieldConfig } from "../types.js";
+
+const md = new MarkdownIt({ html: false, linkify: true, typographer: true });
+
+const REQUIRED_FIELDS = "title, excerpt, datePublished, coverImage, slug";
+
+function requireString(value: any, field: string, file: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(
+      `Missing required frontmatter field "${field}" in ${file}. Required fields: ${REQUIRED_FIELDS}`
+    );
+  }
+  return value.trim();
+}
+
+function normalizeDate(value: any, file: string): string {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+  if (value instanceof Date) {
+    return value.toISOString().slice(0, 10);
+  }
+  throw new Error(`Invalid datePublished in ${file}. Use format YYYY-MM-DD.`);
+}
+
+export async function loadAllMarkdownDocs(cfg: RenderShieldConfig, cwd = process.cwd()): Promise<MarkdownDoc[]> {
+  const baseDirAbs = path.join(cwd, cfg.content.markdown.baseDir);
+
+  const out: MarkdownDoc[] = [];
+
+  for (const col of cfg.content.markdown.collections) {
+    const pattern = col.pattern;
+    const matches = await fg(pattern, { cwd: baseDirAbs, onlyFiles: true });
+
+    for (const rel of matches) {
+      const abs = path.join(baseDirAbs, rel);
+      const raw = await fs.readFile(abs, "utf8");
+      const parsed = matter(raw);
+
+      const title = requireString(parsed.data?.title, "title", abs);
+      const excerpt = requireString(parsed.data?.excerpt, "excerpt", abs);
+
+      const datePublishedRaw = parsed.data?.datePublished;
+      if (datePublishedRaw === undefined || datePublishedRaw === null) {
+        throw new Error(
+          `Missing required frontmatter field "datePublished" in ${abs}. Required fields: ${REQUIRED_FIELDS}`
+        );
+      }
+      const datePublished = normalizeDate(datePublishedRaw, abs);
+
+      const coverImage = requireString(parsed.data?.coverImage, "coverImage", abs);
+      const slug = requireString(parsed.data?.slug, "slug", abs);
+
+      // Route: /blog/<slug>
+      const routeBase = col.routeBase.endsWith("/") ? col.routeBase.slice(0, -1) : col.routeBase;
+      const routePath = `${routeBase}/${slug}`;
+
+      const htmlContent = md.render(parsed.content ?? "");
+
+      out.push({
+        sourcePath: abs,
+        collection: col.name,
+        routePath,
+        title,
+        excerpt,
+        datePublished,
+        coverImage,
+        slug,
+        htmlContent,
+      });
+    }
+  }
+
+  // Deterministic order
+  out.sort((a, b) => a.routePath.localeCompare(b.routePath));
+  return out;
+}

package/src/core/renderHtml.ts

@@ -0,0 +1,76 @@
+import { MarkdownDoc, RenderShieldConfig } from "../types.js";
+
+function escapeHtml(s: string): string {
+  return s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}
+
+function joinUrl(base: string, pathname: string): string {
+  const b = base.endsWith("/") ? base.slice(0, -1) : base;
+  const p = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return b + p;
+}
+
+export function renderPageHtml(cfg: RenderShieldConfig, doc: MarkdownDoc): string {
+  const canonicalUrl = joinUrl(cfg.site.canonicalBase, doc.routePath);
+  const ogImageUrl = doc.coverImage.startsWith("http")
+    ? doc.coverImage
+    : joinUrl(cfg.site.canonicalBase, doc.coverImage);
+
+  const title = `${doc.title} - ${cfg.site.siteName}`;
+  const description = doc.excerpt;
+
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@type": "Article",
+    headline: doc.title,
+    author: { "@type": "Person", name: cfg.site.authorName },
+    datePublished: doc.datePublished,
+    image: ogImageUrl,
+    mainEntityOfPage: canonicalUrl,
+  };
+
+  // NOTE: doc.htmlContent is already HTML from markdown-it.
+  // We trust it as generated output, not user-injected raw HTML (markdown-it html:false).
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+
+  <title>${escapeHtml(title)}</title>
+  <meta name="description" content="${escapeHtml(description)}">
+  <link rel="canonical" href="${escapeHtml(canonicalUrl)}">
+
+  <meta property="og:type" content="article">
+  <meta property="og:title" content="${escapeHtml(doc.title)}">
+  <meta property="og:description" content="${escapeHtml(description)}">
+  <meta property="og:image" content="${escapeHtml(ogImageUrl)}">
+  <meta property="og:url" content="${escapeHtml(canonicalUrl)}">
+
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="${escapeHtml(doc.title)}">
+  <meta name="twitter:description" content="${escapeHtml(description)}">
+  <meta name="twitter:image" content="${escapeHtml(ogImageUrl)}">
+
+  <script type="application/ld+json">${escapeHtml(JSON.stringify(jsonLd))}</script>
+</head>
+<body>
+  <main>
+    <article>
+      <header>
+        <h1>${escapeHtml(doc.title)}</h1>
+        <p><time datetime="${escapeHtml(doc.datePublished)}">${escapeHtml(doc.datePublished)}</time></p>
+      </header>
+      ${doc.htmlContent}
+    </article>
+  </main>
+</body>
+</html>`;
+
+  return cfg.output.prettyHtml ? html : html.replace(/\s+/g, " ");
+}

package/src/core/validateOutput.ts

@@ -0,0 +1,148 @@
+type ValidateParams = {
+  html: string;
+  outFile: string;
+  routePath: string;
+};
+
+function hasNonEmptyTitle(html: string): boolean {
+  const m = html.match(/<title>([\s\S]*?)<\/title>/i);
+  if (!m) return false;
+  const text = (m[1] ?? "").trim();
+  return text.length > 0;
+}
+
+function getMetaContent(html: string, name: string): string | null {
+  // matches: <meta name="description" content="...">
+  const re = new RegExp(
+    `<meta\\s+[^>]*name=["']${escapeRegExp(name)}["'][^>]*>`,
+    "i"
+  );
+  const tag = html.match(re)?.[0];
+  if (!tag) return null;
+
+  const contentMatch = tag.match(/content=["']([^"']+)["']/i);
+  return contentMatch?.[1]?.trim() ?? null;
+}
+
+function getLinkHref(html: string, rel: string): string | null {
+  const re = new RegExp(
+    `<link\\s+[^>]*rel=["']${escapeRegExp(rel)}["'][^>]*>`,
+    "i"
+  );
+  const tag = html.match(re)?.[0];
+  if (!tag) return null;
+
+  const hrefMatch = tag.match(/href=["']([^"']+)["']/i);
+  return hrefMatch?.[1]?.trim() ?? null;
+}
+
+function getOgContent(html: string, property: string): string | null {
+  const re = new RegExp(
+    `<meta\\s+[^>]*property=["']${escapeRegExp(property)}["'][^>]*>`,
+    "i"
+  );
+  const tag = html.match(re)?.[0];
+  if (!tag) return null;
+
+  const contentMatch = tag.match(/content=["']([^"']+)["']/i);
+  return contentMatch?.[1]?.trim() ?? null;
+}
+
+function getJsonLd(html: string): string | null {
+  const m = html.match(
+    /<script\s+[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/i
+  );
+  if (!m) return null;
+  return (m[1] ?? "").trim();
+}
+
+function getArticleInnerHtml(html: string): string | null {
+  const m = html.match(/<article\b[^>]*>([\s\S]*?)<\/article>/i);
+  if (!m) return null;
+  return (m[1] ?? "").trim();
+}
+
+function stripTags(s: string): string {
+  return s
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<\/?[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function wordCount(s: string): number {
+  if (!s.trim()) return 0;
+  return s.trim().split(/\s+/).filter(Boolean).length;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function validatePrerenderHtml(params: ValidateParams): void {
+  const { html, outFile, routePath } = params;
+
+  const missing: string[] = [];
+
+  // 1) Title
+  if (!hasNonEmptyTitle(html)) missing.push("Missing or empty <title>");
+
+  // 2) Meta description
+  const desc = getMetaContent(html, "description");
+  if (!desc) missing.push('Missing <meta name="description" content="...">');
+
+  // 3) Canonical
+  const canonical = getLinkHref(html, "canonical");
+  if (!canonical) missing.push('Missing <link rel="canonical" href="...">');
+
+  // 4) Open Graph tags
+  const ogTitle = getOgContent(html, "og:title");
+  const ogDesc = getOgContent(html, "og:description");
+  const ogImg = getOgContent(html, "og:image");
+  const ogUrl = getOgContent(html, "og:url");
+
+  if (!ogTitle) missing.push("Missing Open Graph tag: og:title");
+  if (!ogDesc) missing.push("Missing Open Graph tag: og:description");
+  if (!ogImg) missing.push("Missing Open Graph tag: og:image");
+  if (!ogUrl) missing.push("Missing Open Graph tag: og:url");
+
+  // 5) JSON-LD
+  const jsonLd = getJsonLd(html);
+  if (!jsonLd) {
+    missing.push('Missing JSON-LD: <script type="application/ld+json">...</script>');
+  } else if (jsonLd.length <= 20) {
+    missing.push("JSON-LD script present but too short/empty");
+  }
+
+  // 6) Article content
+  const articleInner = getArticleInnerHtml(html);
+  if (!articleInner) {
+    missing.push("Missing <article>...</article>");
+  } else {
+    const text = stripTags(articleInner);
+    const words = wordCount(text);
+
+    // Require either enough characters or enough words
+    const okByChars = text.length >= 80;
+    const okByWords = words >= 20;
+
+    if (!okByChars && !okByWords) {
+      missing.push(
+        `Article content too short (got ${words} words, ${text.length} chars). Require >= 20 words or >= 80 chars.`
+      );
+    }
+  }
+
+  if (missing.length > 0) {
+    const msg =
+      `RenderShield validation failed for prerendered page:\n` +
+      `- routePath: ${routePath}\n` +
+      `- outFile: ${outFile}\n` +
+      `Missing/invalid requirements:\n` +
+      missing.map((m) => `- ${m}`).join("\n") +
+      `\n\nFix the source content or renderer so bots receive complete HTML.`;
+
+    throw new Error(msg);
+  }
+}

package/src/types/markdown-it.d.ts

@@ -0,0 +1,20 @@
+declare module "markdown-it" {
+    type MarkdownItOptions = {
+      html?: boolean;
+      xhtmlOut?: boolean;
+      breaks?: boolean;
+      langPrefix?: string;
+      linkify?: boolean;
+      typographer?: boolean;
+      quotes?: string | string[];
+      highlight?: (str: string, lang: string) => string;
+    };
+  
+    class MarkdownIt {
+      constructor(options?: MarkdownItOptions);
+      render(markdown: string): string;
+    }
+  
+    export default MarkdownIt;
+  }
+  

package/src/types.ts

@@ -0,0 +1,52 @@
+export type RenderShieldConfig = {
+    version: 1;
+    site: {
+      canonicalBase: string; // https://example.com
+      siteName: string;
+      defaultOgImage: string;
+      authorName: string;
+    };
+    content: {
+      markdown: {
+        baseDir: string; // content
+        collections: Array<{
+          name: string; // blog
+          pattern: string; // blog/**/*.md
+          routeBase: string; // /blog
+          schemaType: "Article"; // v0 only supports Article
+        }>;
+      };
+    };
+    output: {
+      outDir: string; // dist-prerender
+      prettyHtml: boolean;
+    };
+    sitemap: {
+      enabled: boolean;
+      path: string; // /sitemap.xml
+    };
+    robots: {
+      enabled: boolean;
+      path: string; // /robots.txt
+    };
+    worker: {
+      enabled: boolean;
+      lovableOrigin: string; // https://YOUR_SITE.lovable.app
+      rewriteRouteBases: string[]; // ["/blog/"]
+      botUserAgentPatterns: string[];
+      debugHeaders: boolean;
+    };
+  };
+  
+  export type MarkdownDoc = {
+    sourcePath: string;
+    collection: string;
+    routePath: string; // /blog/slug
+    title: string;
+    excerpt: string;
+    datePublished: string; // YYYY-MM-DD
+    coverImage: string; // /images/...
+    slug: string;
+    htmlContent: string; // rendered <p>...
+  };
+