@lownoise-studio/rendershield 0.3.1 → 1.1.0

package/src/core/loadConfig.ts

@@ -1,173 +1,282 @@
-import fs from "fs-extra";
-import path from "node:path";
-import { RenderShieldConfig } from "../types.js";
-
-const CONFIG_NAME = "rendershield.config.json";
-
-const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
-const DEFAULT_ROBOTS_PATH = "/robots.txt";
-
-type BoolFlag = { enabled: boolean };
-
-/** Shape of config as read from JSON (before normalization). Used for validation only. */
-interface ParsedInput {
-  version?: unknown;
-  site?: { canonicalBase?: unknown; siteName?: unknown; defaultOgImage?: unknown; authorName?: unknown };
-  content?: { markdown?: { baseDir?: unknown; collections?: unknown[] } };
-  output?: { outDir?: unknown };
-  sitemap?: Record<string, unknown>;
-  robots?: Record<string, unknown>;
-  worker?: Record<string, unknown>;
-}
-
-function isObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-function coerceBoolFlag(
-  parsed: Record<string, unknown>,
-  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 }`);
-  }
-  const enabled = (v as Record<string, unknown>).enabled;
-  if (typeof enabled !== "boolean") {
-    throw new Error(`${key}.enabled must be a boolean`);
-  }
-  return { enabled };
-}
-
-/**
- * Worker config policy: strict mode.
- * When worker.enabled is true, all of lovableOrigin, rewriteRouteBases, and
- * botUserAgentPatterns are required and must be non-empty. No defaults are
- * supplied — build fails with a crisp error.
- * lovableOrigin: must be http: or https: only (no file:, javascript:, protocol-relative).
- * botUserAgentPatterns: substring match only (not regex); empty strings rejected to avoid overmatching.
- */
-function validateWorkerWhenEnabled(parsed: Record<string, unknown>): void {
-  const worker = parsed.worker as Record<string, unknown> | undefined;
-  if (!worker?.lovableOrigin || typeof worker.lovableOrigin !== "string") {
-    throw new Error(
-      `worker.lovableOrigin is required when worker.enabled is true. Example: "https://your-site.lovable.app"`
-    );
-  }
-  let url: URL;
-  try {
-    url = new URL(worker.lovableOrigin);
-  } catch {
-    throw new Error(
-      `worker.lovableOrigin must be a valid URL. Got: "${worker.lovableOrigin}"`
-    );
-  }
-  const scheme = url.protocol.toLowerCase();
-  if (scheme !== "http:" && scheme !== "https:") {
-    throw new Error(
-      `worker.lovableOrigin must use http or https. Got: "${url.protocol}"`
-    );
-  }
-  if (
-    !Array.isArray(worker.rewriteRouteBases) ||
-    worker.rewriteRouteBases.length === 0
-  ) {
-    throw new Error(
-      `worker.rewriteRouteBases must be a non-empty array when worker.enabled is true. Example: ["/blog/"]`
-    );
-  }
-  if (
-    !Array.isArray(worker.botUserAgentPatterns) ||
-    worker.botUserAgentPatterns.length === 0
-  ) {
-    throw new Error(
-      `worker.botUserAgentPatterns must be a non-empty array when worker.enabled is true. Example: ["googlebot", "bingbot"]`
-    );
-  }
-  // Substring match only; empty string would match every User-Agent
-  for (let i = 0; i < worker.botUserAgentPatterns.length; i++) {
-    const p = worker.botUserAgentPatterns[i];
-    if (typeof p !== "string" || p.trim() === "") {
-      throw new Error(
-        `worker.botUserAgentPatterns[${i}] must be a non-empty string (substring match). Empty or invalid entry would overmatch.`
-      );
-    }
-  }
-}
-
-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: ParsedInput & Record<string, unknown>;
-  try {
-    parsed = JSON.parse(raw) as ParsedInput & Record<string, unknown>;
-  } 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 (preserve path so it is not lost)
-  const sitemapFlag = coerceBoolFlag(parsed, "sitemap", true);
-  const sitemapObj = parsed.sitemap as Record<string, unknown> | undefined;
-  const sitemapPathVal = sitemapObj?.path;
-  const sitemapPath =
-    typeof sitemapPathVal === "string" && sitemapPathVal.trim().startsWith("/")
-      ? sitemapPathVal.trim()
-      : DEFAULT_SITEMAP_PATH;
-  parsed.sitemap = { enabled: sitemapFlag.enabled, path: sitemapPath };
-
-  const robotsFlag = coerceBoolFlag(parsed, "robots", true);
-  const robotsObj = parsed.robots as Record<string, unknown> | undefined;
-  const robotsPathVal = robotsObj?.path;
-  const robotsPath =
-    typeof robotsPathVal === "string" && robotsPathVal.trim().startsWith("/")
-      ? robotsPathVal.trim()
-      : DEFAULT_ROBOTS_PATH;
-  parsed.robots = { enabled: robotsFlag.enabled, path: robotsPath };
-
-  const workerFlag = coerceBoolFlag(parsed, "worker", true);
-  if (workerFlag.enabled) {
-    validateWorkerWhenEnabled(parsed);
-    // Keep parsed.worker as the full object from JSON (already validated)
-  } else {
-    parsed.worker = {
-      enabled: false,
-      lovableOrigin: "",
-      rewriteRouteBases: [],
-      botUserAgentPatterns: [],
-      debugHeaders: false,
-    };
-  }
-
-  return parsed as RenderShieldConfig;
-}
+import fs from "fs-extra";
+import path from "node:path";
+import { RenderShieldConfig, SCHEMA_TYPES, type SchemaType } from "../types.js";
+import { renderShieldError } from "../errors.js";
+import {
+  resolveConfigFile,
+  DEFAULT_CONFIG_NAME,
+  type CommandOptions,
+} from "../configPath.js";
+
+const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
+const DEFAULT_ROBOTS_PATH = "/robots.txt";
+
+type BoolFlag = { enabled: boolean };
+
+/** Shape of config as read from JSON (before normalization). Used for validation only. */
+interface ParsedInput {
+  version?: unknown;
+  site?: { canonicalBase?: unknown; siteName?: unknown; defaultOgImage?: unknown; authorName?: unknown };
+  content?: { markdown?: { baseDir?: unknown; collections?: unknown[] } };
+  output?: { outDir?: unknown };
+  sitemap?: Record<string, unknown>;
+  robots?: Record<string, unknown>;
+  worker?: Record<string, unknown>;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function coerceBoolFlag(
+  parsed: Record<string, unknown>,
+  key: "sitemap" | "robots" | "worker",
+  defaultEnabled: boolean
+): BoolFlag {
+  if (parsed?.[key] == null) return { enabled: defaultEnabled };
+
+  const v = parsed[key];
+  if (!isObject(v)) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `${key} must be an object like { "enabled": true }`
+    );
+  }
+  const enabled = (v as Record<string, unknown>).enabled;
+  if (typeof enabled !== "boolean") {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `${key}.enabled must be a boolean`
+    );
+  }
+  return { enabled };
+}
+
+function readSpaOrigin(worker: Record<string, unknown>): string | undefined {
+  const spa = worker.spaOrigin ?? worker.lovableOrigin;
+  return typeof spa === "string" && spa.trim() !== "" ? spa.trim() : undefined;
+}
+
+/**
+ * Worker config policy: strict mode when enabled.
+ * spaOrigin (or deprecated lovableOrigin) must be http(s).
+ */
+function validateWorkerWhenEnabled(parsed: Record<string, unknown>): void {
+  const worker = parsed.worker as Record<string, unknown> | undefined;
+  const spaOrigin = worker ? readSpaOrigin(worker) : undefined;
+
+  if (!spaOrigin) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `worker.spaOrigin is required when worker.enabled is true. Example: "https://app.example.com" (lovableOrigin is accepted as a deprecated alias).`
+    );
+  }
+
+  let url: URL;
+  try {
+    url = new URL(spaOrigin);
+  } catch {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `worker.spaOrigin must be a valid URL. Got: "${spaOrigin}"`
+    );
+  }
+  const scheme = url.protocol.toLowerCase();
+  if (scheme !== "http:" && scheme !== "https:") {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `worker.spaOrigin must use http or https. Got: "${url.protocol}"`
+    );
+  }
+  if (
+    !Array.isArray(worker?.rewriteRouteBases) ||
+    worker.rewriteRouteBases.length === 0
+  ) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `worker.rewriteRouteBases must be a non-empty array when worker.enabled is true. Example: ["/blog/"]`
+    );
+  }
+  if (
+    !Array.isArray(worker?.botUserAgentPatterns) ||
+    worker.botUserAgentPatterns.length === 0
+  ) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `worker.botUserAgentPatterns must be a non-empty array when worker.enabled is true. Example: ["googlebot", "bingbot"]`
+    );
+  }
+  for (let i = 0; i < worker.botUserAgentPatterns.length; i++) {
+    const p = worker.botUserAgentPatterns[i];
+    if (typeof p !== "string" || p.trim() === "") {
+      throw renderShieldError(
+        "CONFIG_INVALID",
+        `worker.botUserAgentPatterns[${i}] must be a non-empty string (substring match). Empty or invalid entry would overmatch.`
+      );
+    }
+  }
+}
+
+function normalizeWorker(
+  parsed: Record<string, unknown>,
+  enabled: boolean
+): void {
+  if (!enabled) {
+    parsed.worker = {
+      enabled: false,
+      spaOrigin: "",
+      rewriteRouteBases: [],
+      botUserAgentPatterns: [],
+      debugHeaders: false,
+    };
+    return;
+  }
+
+  validateWorkerWhenEnabled(parsed);
+  const worker = parsed.worker as Record<string, unknown>;
+  parsed.worker = {
+    enabled: true,
+    spaOrigin: readSpaOrigin(worker) as string,
+    rewriteRouteBases: worker.rewriteRouteBases,
+    botUserAgentPatterns: worker.botUserAgentPatterns,
+    debugHeaders: worker.debugHeaders === true,
+  };
+}
+
+export async function loadConfig(
+  cwd = process.cwd(),
+  options?: CommandOptions
+): Promise<RenderShieldConfig> {
+  const configFile = resolveConfigFile(cwd, options?.configPath);
+  const configName = path.basename(configFile);
+  const exists = await fs.pathExists(configFile);
+  if (!exists) {
+    throw renderShieldError(
+      "CONFIG_MISSING",
+      `Missing ${configName}. Run: rendershield init`
+    );
+  }
+
+  const raw = await fs.readFile(configFile, "utf8");
+  let parsed: ParsedInput & Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as ParsedInput & Record<string, unknown>;
+  } catch {
+    throw renderShieldError("CONFIG_INVALID", `${configName} is not valid JSON`);
+  }
+
+  if (parsed?.version !== 1) {
+    throw renderShieldError("CONFIG_INVALID", "Config version must be 1");
+  }
+  if (!parsed?.site?.canonicalBase) {
+    throw renderShieldError("CONFIG_INVALID", "site.canonicalBase is required");
+  }
+  if (!parsed?.site?.siteName) {
+    throw renderShieldError("CONFIG_INVALID", "site.siteName is required");
+  }
+  if (!parsed?.site?.defaultOgImage) {
+    throw renderShieldError("CONFIG_INVALID", "site.defaultOgImage is required");
+  }
+  if (!parsed?.site?.authorName) {
+    throw renderShieldError("CONFIG_INVALID", "site.authorName is required");
+  }
+  if (!parsed?.content?.markdown?.baseDir) {
+    throw renderShieldError("CONFIG_INVALID", "content.markdown.baseDir is required");
+  }
+  if (
+    !Array.isArray(parsed?.content?.markdown?.collections) ||
+    parsed.content.markdown.collections.length === 0
+  ) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      "content.markdown.collections must be a non-empty array"
+    );
+  }
+  if (!parsed?.output?.outDir) {
+    throw renderShieldError("CONFIG_INVALID", "output.outDir is required");
+  }
+
+  parsed.content.markdown.collections = normalizeCollections(
+    parsed.content.markdown.collections
+  );
+
+  const sitemapFlag = coerceBoolFlag(parsed, "sitemap", true);
+  const sitemapObj = parsed.sitemap as Record<string, unknown> | undefined;
+  const sitemapPathVal = sitemapObj?.path;
+  const sitemapPath =
+    typeof sitemapPathVal === "string" && sitemapPathVal.trim().startsWith("/")
+      ? sitemapPathVal.trim()
+      : DEFAULT_SITEMAP_PATH;
+  parsed.sitemap = { enabled: sitemapFlag.enabled, path: sitemapPath };
+
+  const robotsFlag = coerceBoolFlag(parsed, "robots", true);
+  const robotsObj = parsed.robots as Record<string, unknown> | undefined;
+  const robotsPathVal = robotsObj?.path;
+  const robotsPath =
+    typeof robotsPathVal === "string" && robotsPathVal.trim().startsWith("/")
+      ? robotsPathVal.trim()
+      : DEFAULT_ROBOTS_PATH;
+  parsed.robots = { enabled: robotsFlag.enabled, path: robotsPath };
+
+  const workerFlag = coerceBoolFlag(parsed, "worker", true);
+  normalizeWorker(parsed, workerFlag.enabled);
+
+  return parsed as RenderShieldConfig;
+}
+
+export { DEFAULT_CONFIG_NAME };
+
+function normalizeCollections(collections: unknown[]): RenderShieldConfig["content"]["markdown"]["collections"] {
+  return collections.map((raw, index) => {
+    if (!isObject(raw)) {
+      throw renderShieldError(
+        "CONFIG_INVALID",
+        `content.markdown.collections[${index}] must be an object`
+      );
+    }
+
+    const name = raw.name;
+    const pattern = raw.pattern;
+    const routeBase = raw.routeBase;
+    const schemaTypeRaw = raw.schemaType;
+
+    if (typeof name !== "string" || name.trim() === "") {
+      throw renderShieldError(
+        "CONFIG_INVALID",
+        `content.markdown.collections[${index}].name must be a non-empty string`
+      );
+    }
+    if (typeof pattern !== "string" || pattern.trim() === "") {
+      throw renderShieldError(
+        "CONFIG_INVALID",
+        `content.markdown.collections[${index}].pattern must be a non-empty string`
+      );
+    }
+    if (typeof routeBase !== "string" || routeBase.trim() === "") {
+      throw renderShieldError(
+        "CONFIG_INVALID",
+        `content.markdown.collections[${index}].routeBase must be a non-empty string`
+      );
+    }
+
+    const schemaType: SchemaType =
+      schemaTypeRaw === undefined ? "Article" : parseSchemaType(schemaTypeRaw, index);
+
+    return {
+      name: name.trim(),
+      pattern: pattern.trim(),
+      routeBase: routeBase.trim(),
+      schemaType,
+    };
+  });
+}
+
+function parseSchemaType(value: unknown, index: number): SchemaType {
+  if (typeof value !== "string" || !SCHEMA_TYPES.includes(value as SchemaType)) {
+    throw renderShieldError(
+      "CONFIG_INVALID",
+      `content.markdown.collections[${index}].schemaType must be one of: ${SCHEMA_TYPES.join(", ")}`
+    );
+  }
+  return value as SchemaType;
+}

package/src/core/loadMarkdown.ts

@@ -4,6 +4,7 @@ import fs from "fs-extra";
 import matter from "gray-matter";
 import MarkdownIt from "markdown-it";
 import { MarkdownDoc, RenderShieldConfig } from "../types.js";
+import { renderShieldError } from "../errors.js";
 
 const md = new MarkdownIt({ html: false, linkify: true, typographer: true });
 
@@ -11,7 +12,8 @@ const REQUIRED_FIELDS = "title, excerpt, datePublished, coverImage, slug";
 
 function requireString(value: unknown, field: string, file: string): string {
   if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(
+    throw renderShieldError(
+      "CONTENT_INVALID",
       `Missing required frontmatter field "${field}" in ${file}. Required fields: ${REQUIRED_FIELDS}`
     );
   }
@@ -25,7 +27,10 @@ function normalizeDate(value: unknown, file: string): string {
   if (value instanceof Date) {
     return value.toISOString().slice(0, 10);
   }
-  throw new Error(`Invalid datePublished in ${file}. Use format YYYY-MM-DD.`);
+  throw renderShieldError(
+    "CONTENT_INVALID",
+    `Invalid datePublished in ${file}. Use format YYYY-MM-DD.`
+  );
 }
 
 export async function loadAllMarkdownDocs(cfg: RenderShieldConfig, cwd = process.cwd()): Promise<MarkdownDoc[]> {
@@ -47,7 +52,8 @@ export async function loadAllMarkdownDocs(cfg: RenderShieldConfig, cwd = process
 
       const datePublishedRaw = parsed.data?.datePublished;
       if (datePublishedRaw === undefined || datePublishedRaw === null) {
-        throw new Error(
+        throw renderShieldError(
+          "CONTENT_INVALID",
           `Missing required frontmatter field "datePublished" in ${abs}. Required fields: ${REQUIRED_FIELDS}`
         );
       }

package/src/core/renderHtml.ts

@@ -1,4 +1,4 @@
-import { MarkdownDoc, RenderShieldConfig } from "../types.js";
+import { MarkdownDoc, RenderShieldConfig, SchemaType } from "../types.js";
 
 function escapeHtml(s: string): string {
   return s
@@ -15,6 +15,37 @@ function joinUrl(base: string, pathname: string): string {
   return b + p;
 }
 
+function resolveSchemaType(cfg: RenderShieldConfig, doc: MarkdownDoc): SchemaType {
+  const collection = cfg.content.markdown.collections.find((c) => c.name === doc.collection);
+  return collection?.schemaType ?? "Article";
+}
+
+function buildJsonLd(
+  schemaType: SchemaType,
+  cfg: RenderShieldConfig,
+  doc: MarkdownDoc,
+  canonicalUrl: string,
+  ogImageUrl: string
+): Record<string, unknown> {
+  const base = {
+    "@context": "https://schema.org",
+    "@type": schemaType,
+    mainEntityOfPage: canonicalUrl,
+    image: ogImageUrl,
+  };
+
+  if (schemaType === "WebPage") {
+    return { ...base, name: doc.title };
+  }
+
+  return {
+    ...base,
+    headline: doc.title,
+    author: { "@type": "Person", name: cfg.site.authorName },
+    datePublished: doc.datePublished,
+  };
+}
+
 export function renderPageHtml(cfg: RenderShieldConfig, doc: MarkdownDoc): string {
   const canonicalUrl = joinUrl(cfg.site.canonicalBase, doc.routePath);
   const ogImageUrl = doc.coverImage.startsWith("http")
@@ -23,16 +54,9 @@ export function renderPageHtml(cfg: RenderShieldConfig, doc: MarkdownDoc): strin
 
   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,
-  };
+  const schemaType = resolveSchemaType(cfg, doc);
+  const ogType = schemaType === "WebPage" ? "website" : "article";
+  const jsonLd = buildJsonLd(schemaType, cfg, doc, canonicalUrl, ogImageUrl);
 
   // NOTE: doc.htmlContent is already HTML from markdown-it.
   // We trust it as generated output, not user-injected raw HTML (markdown-it html:false).
@@ -46,7 +70,7 @@ export function renderPageHtml(cfg: RenderShieldConfig, doc: MarkdownDoc): strin
   <meta name="description" content="${escapeHtml(description)}">
   <link rel="canonical" href="${escapeHtml(canonicalUrl)}">
 
-  <meta property="og:type" content="article">
+  <meta property="og:type" content="${ogType}">
   <meta property="og:title" content="${escapeHtml(doc.title)}">
   <meta property="og:description" content="${escapeHtml(description)}">
   <meta property="og:image" content="${escapeHtml(ogImageUrl)}">