@lownoise-studio/rendershield 0.3.1 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * RenderShield programmatic API.
+ *
+ * CLI usage: `npx rendershield <command>`
+ * Library usage: import commands and core helpers from `@lownoise-studio/rendershield`.
+ */
+export { cmdInit } from "./commands/init.js";
+export { cmdBuild } from "./commands/build.js";
+export { cmdVerify, type VerifyOptions, type VerifyLocalResult, type VerifyProdResult, type VerifyResult, type VerifyPageResult, } from "./commands/verify.js";
+export { loadConfig } from "./core/loadConfig.js";
+export { loadAllMarkdownDocs } from "./core/loadMarkdown.js";
+export { renderPageHtml } from "./core/renderHtml.js";
+export { validatePrerenderHtml, checkPrerenderContract, type ValidateParams, type ContractCheckResult, } from "./core/validateOutput.js";
+export { generateSitemapXml } from "./core/generateSitemap.js";
+export { generateRobotsTxt } from "./core/generateRobots.js";
+export { generateWorkerJs } from "./core/generateWorker.js";
+export type { CommandOptions } from "./configPath.js";
+export { DEFAULT_CONFIG_NAME, resolveConfigFile } from "./configPath.js";
+export type { RenderShieldConfig, MarkdownDoc, SchemaType } from "./types.js";
+export { SCHEMA_TYPES } from "./types.js";
+export { RenderShieldError, isRenderShieldError, renderShieldError, formatCliError, type RenderShieldErrorCode, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * RenderShield programmatic API.
+ *
+ * CLI usage: `npx rendershield <command>`
+ * Library usage: import commands and core helpers from `@lownoise-studio/rendershield`.
+ */
+export { cmdInit } from "./commands/init.js";
+export { cmdBuild } from "./commands/build.js";
+export { cmdVerify, } from "./commands/verify.js";
+export { loadConfig } from "./core/loadConfig.js";
+export { loadAllMarkdownDocs } from "./core/loadMarkdown.js";
+export { renderPageHtml } from "./core/renderHtml.js";
+export { validatePrerenderHtml, checkPrerenderContract, } from "./core/validateOutput.js";
+export { generateSitemapXml } from "./core/generateSitemap.js";
+export { generateRobotsTxt } from "./core/generateRobots.js";
+export { generateWorkerJs } from "./core/generateWorker.js";
+export { DEFAULT_CONFIG_NAME, resolveConfigFile } from "./configPath.js";
+export { SCHEMA_TYPES } from "./types.js";
+export { RenderShieldError, isRenderShieldError, renderShieldError, formatCliError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,SAAS,GAMV,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GAEf,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export declare const SCHEMA_TYPES: readonly ["Article", "BlogPosting", "WebPage"];
+export type SchemaType = (typeof SCHEMA_TYPES)[number];
+export type RenderShieldConfig = {
+    version: 1;
+    site: {
+        canonicalBase: string;
+        siteName: string;
+        defaultOgImage: string;
+        authorName: string;
+    };
+    content: {
+        markdown: {
+            baseDir: string;
+            collections: Array<{
+                name: string;
+                pattern: string;
+                routeBase: string;
+                schemaType: SchemaType;
+            }>;
+        };
+    };
+    output: {
+        outDir: string;
+        prettyHtml: boolean;
+    };
+    sitemap: {
+        enabled: boolean;
+        path: string;
+    };
+    robots: {
+        enabled: boolean;
+        path: string;
+    };
+    worker: {
+        enabled: boolean;
+        spaOrigin: string;
+        rewriteRouteBases: string[];
+        botUserAgentPatterns: string[];
+        debugHeaders: boolean;
+    };
+};
+export type MarkdownDoc = {
+    sourcePath: string;
+    collection: string;
+    routePath: string;
+    title: string;
+    excerpt: string;
+    datePublished: string;
+    coverImage: string;
+    slug: string;
+    htmlContent: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,gDAAiD,CAAC;AAC3E,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE;QACJ,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,OAAO,EAAE;QACP,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,CAAC;YAChB,WAAW,EAAE,KAAK,CAAC;gBACjB,IAAI,EAAE,MAAM,CAAC;gBACb,OAAO,EAAE,MAAM,CAAC;gBAChB,SAAS,EAAE,MAAM,CAAC;gBAClB,UAAU,EAAE,UAAU,CAAC;aACxB,CAAC,CAAC;SACJ,CAAC;KACH,CAAC;IACF,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC"}

package/dist/types.js

@@ -1,2 +1,2 @@
-export {};
+export const SCHEMA_TYPES = ["Article", "BlogPosting", "WebPage"];
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,CAAU,CAAC"}

package/docs/CONFIG.md

@@ -0,0 +1,70 @@
+# Config reference
+
+Default file: `rendershield.config.json` (override with `--config <path>`).
+
+JSON Schema: [`rendershield.config.schema.json`](../rendershield.config.schema.json) (editor autocomplete).
+
+## Top level
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `version` | yes | Must be `1`. |
+| `site` | yes | Site metadata for URLs and JSON-LD. |
+| `content` | yes | Markdown content sources. |
+| `output` | yes | Build output directory. |
+| `sitemap` | no | Defaults: `enabled: true`, `path: "/sitemap.xml"`. |
+| `robots` | no | Defaults: `enabled: true`, `path: "/robots.txt"`. |
+| `worker` | no | Defaults: `enabled: true` in `init` sample. |
+
+## `site`
+
+| Field | Description |
+|-------|-------------|
+| `canonicalBase` | Public site origin, e.g. `https://example.com` (no trailing slash). |
+| `siteName` | Appended to page titles. |
+| `defaultOgImage` | Fallback OG image URL. |
+| `authorName` | JSON-LD author for article types. |
+
+## `content.markdown.collections[]`
+
+| Field | Description |
+|-------|-------------|
+| `name` | Collection id (used internally). |
+| `pattern` | Glob under `baseDir`, e.g. `blog/**/*.md`. |
+| `routeBase` | URL prefix, e.g. `/blog`. |
+| `schemaType` | JSON-LD `@type`: `Article` (default), `BlogPosting`, or `WebPage`. |
+
+### Markdown frontmatter (per file)
+
+Required: `title`, `excerpt`, `datePublished` (`YYYY-MM-DD`), `coverImage`, `slug`.
+
+Route: `{routeBase}/{slug}` → `dist-prerender/.../index.html`.
+
+## `output`
+
+| Field | Description |
+|-------|-------------|
+| `outDir` | Relative path inside project, e.g. `dist-prerender`. |
+| `prettyHtml` | Pretty-print HTML (default `true`). |
+
+## `worker`
+
+When `enabled: true`:
+
+| Field | Description |
+|-------|-------------|
+| `spaOrigin` | Origin that serves prerendered + SPA assets, e.g. `https://app.example.com`. |
+| `lovableOrigin` | **Deprecated** — same as `spaOrigin` (still accepted). |
+| `rewriteRouteBases` | Bot rewrite prefixes, e.g. `["/blog/"]`. |
+| `botUserAgentPatterns` | Case-insensitive substring match list. |
+| `debugHeaders` | Extra `X-*` headers on Worker responses. |
+
+## CLI flags
+
+```bash
+rendershield --config ./config/prerender.json build
+rendershield verify --check              # contract-check first built page
+rendershield verify --all --check        # contract-check every built page
+rendershield verify --prod --all         # prod-check every route from build output
+rendershield verify --prod https://example.com/blog/post
+```

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.1.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,12 @@
     "dist/**",
     "src/**",
     "docs/**",
-    "content/**",
+    "rendershield.config.schema.json",
     "DEPLOY.md",
     "README.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "repository": {

package/rendershield.config.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Lownoise-Studio/rendershield/rendershield.config.schema.json",
+  "title": "RenderShield config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "site", "content", "output"],
+  "properties": {
+    "version": { "const": 1 },
+    "site": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["canonicalBase", "siteName", "defaultOgImage", "authorName"],
+      "properties": {
+        "canonicalBase": { "type": "string", "format": "uri" },
+        "siteName": { "type": "string", "minLength": 1 },
+        "defaultOgImage": { "type": "string", "minLength": 1 },
+        "authorName": { "type": "string", "minLength": 1 }
+      }
+    },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["markdown"],
+      "properties": {
+        "markdown": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["baseDir", "collections"],
+          "properties": {
+            "baseDir": { "type": "string", "minLength": 1 },
+            "collections": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name", "pattern", "routeBase"],
+                "properties": {
+                  "name": { "type": "string", "minLength": 1 },
+                  "pattern": { "type": "string", "minLength": 1 },
+                  "routeBase": { "type": "string", "minLength": 1 },
+                  "schemaType": {
+                    "type": "string",
+                    "enum": ["Article", "BlogPosting", "WebPage"],
+                    "default": "Article"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outDir"],
+      "properties": {
+        "outDir": { "type": "string", "minLength": 1 },
+        "prettyHtml": { "type": "boolean", "default": true }
+      }
+    },
+    "sitemap": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "path": { "type": "string", "pattern": "^/" }
+      }
+    },
+    "robots": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "path": { "type": "string", "pattern": "^/" }
+      }
+    },
+    "worker": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "spaOrigin": { "type": "string", "format": "uri" },
+        "lovableOrigin": {
+          "type": "string",
+          "format": "uri",
+          "description": "Deprecated alias for spaOrigin."
+        },
+        "rewriteRouteBases": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "botUserAgentPatterns": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "debugHeaders": { "type": "boolean" }
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -1,75 +1,96 @@
-#!/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";
+import { extractGlobalOptions, parseVerifyArgs } from "./cliArgs.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 [--config <path>] init
+  rendershield [--config <path>] build
+  rendershield [--config <path>] verify [options]
+
+Global:
+  --config <path>   Config file (default: rendershield.config.json)
+
+Verify:
+  verify              Print curl smoke-test commands for first built page
+  verify --check      Validate built HTML contract (first page)
+  verify --all --check   Validate contract for every built page
+  verify --prod <url> Fetch URL as bot; require x-rendershield: bot-hit + contract
+  verify --prod --all Check every route from build output in production
+
+Notes:
+  - Content: content/<collection>/**/*.md (frontmatter required)
+  - Output: dist-prerender/ (see config)
+  - Config reference: docs/CONFIG.md
+`);
+}
+
+async function main() {
+  const { options: globalOptions, rest } = extractGlobalOptions(
+    process.argv.slice(2)
+  );
+  const cmd = rest[0]?.trim();
+  const cmdArgs = rest.slice(1);
+
+  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(undefined, globalOptions);
+      return;
+    }
+    if (cmd === "build") {
+      await cmdBuild(undefined, globalOptions);
+      return;
+    }
+    if (cmd === "verify") {
+      if (cmdArgs.includes("-h") || cmdArgs.includes("--help")) {
+        printHelp();
+        process.exit(0);
+      }
+      const verifyOptions = parseVerifyArgs(cmdArgs, globalOptions);
+      if (verifyOptions.prod && !verifyOptions.prodUrl && !verifyOptions.all) {
+        throw renderShieldError(
+          "CLI_INVALID_ARGS",
+          "verify --prod requires a URL, or use --prod --all. Example: rendershield verify --prod https://example.com/blog/hello-world"
+        );
+      }
+      if (verifyOptions.all && !verifyOptions.check && !verifyOptions.prod) {
+        throw renderShieldError(
+          "CLI_INVALID_ARGS",
+          "verify --all requires --check (local) or --prod (production). Example: rendershield verify --all --check"
+        );
+      }
+      await cmdVerify(undefined, verifyOptions);
+      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();