@lownoise-studio/rendershield 0.3.1 → 1.0.0

package/docs/deploy-cloudflare.md

@@ -37,6 +37,12 @@ At a high level:
 - Known crawlers are routed to prerendered HTML files
 - All other traffic passes through to your SPA unchanged
 
+Every response from the Worker includes an **x-rendershield** header so routing is observable:
+
+- **pass-through** — request was not rewritten (human or path not in rewrite bases)
+- **bot-hit** — bot request was rewritten and prerendered HTML was served
+- **bot-fallback** — bot request was rewritten but the origin returned non-200; Worker fell back to the SPA
+
 If prerendered output is missing or incomplete, RenderShield fails the build.
 
 ---
@@ -104,7 +110,7 @@ The Worker must be able to fetch prerendered files.
 
 You need a static origin that serves paths like:
 
-- /content/example/index.html
+- /blog/example/index.html (or your configured route base)
 - /sitemap.xml
 - /robots.txt
 
@@ -132,36 +138,56 @@ Submit the sitemap URL in Google Search Console.
 
 ## Verification
 
-RenderShield includes a verify command to guide testing.
+### Production verification (recommended)
+
+After deploying the Worker and hosting prerendered output, run:
+
+```bash
+rendershield verify --prod https://yourdomain.com
+```
+
+This command:
 
-### Worker execution test
+- Fetches the URL as Googlebot
+- Asserts the response has **x-rendershield: bot-hit** (proving the Worker served prerendered HTML)
+- Validates metadata, JSON-LD, and article content
+- Exits with code 1 if the header is missing, is `bot-fallback`, or the contract fails
 
-Run:
+If it passes, crawlers are receiving the prerendered HTML.
 
-curl -I -H "User-Agent: GPTBot" https://yourdomain.com/content/example
+### Manual checks (optional)
 
-If debug headers are enabled, you should see headers similar to:
+Check the response header:
+
+```bash
+curl -I -H "User-Agent: Googlebot" https://yourdomain.com/blog/example
+```
+
+You should see **x-rendershield: bot-hit**. If debug headers are enabled in config, you may also see:
 
 - X-Bot-Detected: true
 - X-Prerender: true
-- X-Final-Path: /content/example/index.html
+- X-Final-Path: /blog/example/index.html
+
+If **x-rendershield** is missing or **bot-fallback**:
 
-If these headers are missing:
 - The Worker route may not be attached
 - The Cloudflare proxy may be disabled
-- DNS may still point to a different origin
-
----
+- The prerendered origin may be returning non-200 for that path
 
-## Content comparison
+### Content comparison
 
 Human request (SPA response):
 
-curl -s https://yourdomain.com/content/example | grep -i "<title>"
+```bash
+curl -s https://yourdomain.com/blog/example | grep -i "<title>"
+```
 
 Crawler request (prerendered HTML):
 
-curl -s -H "User-Agent: Googlebot" https://yourdomain.com/content/example | grep -i "<title>"
+```bash
+curl -s -H "User-Agent: Googlebot" https://yourdomain.com/blog/example | grep -i "<title>"
+```
 
 The crawler response should contain the prerendered, route-specific title.
 

package/package.json

@@ -1,12 +1,33 @@
 {
   "name": "@lownoise-studio/rendershield",
-  "version": "0.3.1",
+  "version": "1.0.0",
   "description": "Boring bot-aware prerendering: real HTML for bots, SPA for humans.",
   "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "prerender",
+    "seo",
+    "bots",
+    "spa",
+    "static-site",
+    "cloudflare-workers",
+    "markdown"
+  ],
   "bin": {
     "rendershield": "dist/cli.js"
   },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "node --enable-source-maps dist/cli.js",
@@ -19,10 +40,11 @@
     "dist/**",
     "src/**",
     "docs/**",
-    "content/**",
     "DEPLOY.md",
     "README.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "repository": {

package/src/cli.ts

@@ -1,75 +1,86 @@
-#!/usr/bin/env node
-import { createRequire } from "node:module";
-import { cmdInit } from "./commands/init.js";
-import { cmdBuild } from "./commands/build.js";
-import { cmdVerify } from "./commands/verify.js";
-
-const require = createRequire(import.meta.url);
-const pkg = require("../package.json") as { version?: string };
-const VERSION = pkg.version ?? "0.0.0";
-
-function printHelp() {
-  console.log(`
-RenderShield v${VERSION} — boring bot-aware prerendering.
-
-Usage:
-  rendershield init
-  rendershield build
-  rendershield verify [--prod <url>]
-
-  verify         Print curl commands for local/build output.
-  verify --prod  Fetch URL as bot and human; verify bot sees full HTML and contract fields.
-                 Requires x-rendershield: bot-hit from the Worker.
-
-Notes:
-  - Config file: rendershield.config.json
-  - Content: content/<collection>/**/*.md (frontmatter required)
-  - Output: dist-prerender/
-`);
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const cmd = args[0]?.trim();
-
-  if (!cmd || cmd === "-h" || cmd === "--help") {
-    printHelp();
-    process.exit(0);
-  }
-  if (cmd === "-V" || cmd === "--version") {
-    console.log(VERSION);
-    process.exit(0);
-  }
-
-  try {
-    if (cmd === "init") {
-      await cmdInit();
-      return;
-    }
-    if (cmd === "build") {
-      await cmdBuild();
-      return;
-    }
-    if (cmd === "verify") {
-      const verifyArgs = args.slice(1);
-      if (verifyArgs.includes("-h") || verifyArgs.includes("--help")) {
-        printHelp();
-        process.exit(0);
-      }
-      const prodIdx = verifyArgs.indexOf("--prod");
-      const prodUrl = prodIdx >= 0 && verifyArgs[prodIdx + 1] ? verifyArgs[prodIdx + 1].trim() : undefined;
-      await cmdVerify(undefined, prodUrl ? { prodUrl } : undefined);
-      return;
-    }
-
-    console.error(`Unknown command: ${cmd}\n`);
-    printHelp();
-    process.exit(1);
-  } catch (err: unknown) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error(`\nRenderShield error: ${msg}\n`);
-    process.exit(1);
-  }
-}
-
-main();
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { cmdInit } from "./commands/init.js";
+import { cmdBuild } from "./commands/build.js";
+import { cmdVerify } from "./commands/verify.js";
+import { formatCliError, renderShieldError } from "./errors.js";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as { version?: string };
+const VERSION = pkg.version ?? "0.0.0";
+
+function printHelp() {
+  console.log(`
+RenderShield v${VERSION} — boring bot-aware prerendering.
+
+Usage:
+  rendershield init
+  rendershield build
+  rendershield verify [--prod <url>]
+
+  verify         Print curl commands for local/build output.
+  verify --prod  Fetch URL as bot and human; verify bot sees full HTML and contract fields.
+                 Requires x-rendershield: bot-hit from the Worker.
+
+Notes:
+  - Config file: rendershield.config.json
+  - Content: content/<collection>/**/*.md (frontmatter required)
+  - Output: dist-prerender/
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0]?.trim();
+
+  if (!cmd || cmd === "-h" || cmd === "--help") {
+    printHelp();
+    process.exit(0);
+  }
+  if (cmd === "-V" || cmd === "--version") {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  try {
+    if (cmd === "init") {
+      await cmdInit();
+      return;
+    }
+    if (cmd === "build") {
+      await cmdBuild();
+      return;
+    }
+    if (cmd === "verify") {
+      const verifyArgs = args.slice(1);
+      if (verifyArgs.includes("-h") || verifyArgs.includes("--help")) {
+        printHelp();
+        process.exit(0);
+      }
+      const prodIdx = verifyArgs.indexOf("--prod");
+      if (prodIdx >= 0) {
+        const prodUrl = verifyArgs[prodIdx + 1]?.trim();
+        if (!prodUrl || prodUrl.startsWith("-")) {
+          throw renderShieldError(
+            "CLI_INVALID_ARGS",
+            "verify --prod requires a URL. Example: rendershield verify --prod https://example.com/blog/hello-world"
+          );
+        }
+        await cmdVerify(undefined, { prodUrl });
+        return;
+      }
+      await cmdVerify();
+      return;
+    }
+
+    console.error(`Unknown command: ${cmd}\n`);
+    printHelp();
+    process.exit(1);
+  } catch (err: unknown) {
+    const msg = formatCliError(err);
+    console.error(`\nRenderShield error: ${msg}\n`);
+    process.exit(1);
+  }
+}
+
+main();