@lownoise-studio/rendershield 0.3.1 → 1.1.0

package/CHANGELOG.md

@@ -1,32 +1,73 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-
-- `verify --prod <url>`: production check that asserts `x-rendershield: bot-hit` and runs the same HTML contract validation as build.
-- Worker response header `x-rendershield`: `bot-hit` | `bot-fallback` | `pass-through` so routing is observable without inferring from HTML.
-- CLI `--version` / `-V`: prints version from package.json.
-- Vitest test suite: contract validation, loadConfig (including sitemap/robots path preservation and worker validation), path safety, and integration build.
-
-### Fixed
-
-- Config: sitemap and robots `path` are preserved and defaulted when only `enabled` is set; no longer lost when using boolean flags.
-- Config: when `worker.enabled` is true, full worker object is kept (lovableOrigin, rewriteRouteBases, etc.) instead of being replaced by the flag.
-- Worker: 500 error response body is generic ("Service temporarily unavailable.") to avoid leaking internals.
-- JSON-LD in generated HTML: script body is no longer HTML-escaped so contract validation and crawlers can parse it.
-
-### Changed
-
-- Help text shows version and documents that `verify --prod` requires `x-rendershield: bot-hit`.
-- TypeScript: reduced `any`; use `unknown` and typed interfaces in CLI, loadConfig, validateOutput, loadMarkdown.
-- README: added "Production check" for `verify --prod`.
-
-## [0.3.0] - 2025-02-18
-
-- Initial npm release with init, build, verify, optional Cloudflare Worker, and HTML contract validation.
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2026-08-23
+
+### Added
+
+- `verify --check` and `verify --all --check`: validate built HTML locally against the bot contract (no network).
+- `verify --prod --all`: production-check every route discovered from build output.
+- Global `--config <path>` for `init`, `build`, and `verify`.
+- `worker.spaOrigin` (replaces `lovableOrigin`; old name still accepted on read).
+- Config reference ([docs/CONFIG.md](docs/CONFIG.md)) and `rendershield.config.schema.json`.
+
+### Changed
+
+- `VerifyLocalResult` / `VerifyProdResult` return a `pages` array (multi-route aware).
+- `init` default Worker origin field is `spaOrigin`.
+
+## [1.0.0] - 2026-08-23
+
+### Added
+
+- **Programmatic API**: import `@lownoise-studio/rendershield` for `cmdInit`, `cmdBuild`, `cmdVerify`, config loading, HTML rendering, contract validation, and artifact generators.
+- **`RenderShieldError`**: stable error codes (`CONFIG_MISSING`, `CONFIG_INVALID`, `OUTPUT_PATH_UNSAFE`, `CONTENT_INVALID`, `BUILD_FAILED`, `VALIDATION_FAILED`, `VERIFY_FAILED`, `CLI_INVALID_ARGS`) with optional `details` for library consumers.
+- **TypeScript declarations**: published `.d.ts` via `package.json` `types` and `exports` map.
+- **CI**: GitHub Actions workflow runs build and tests on Node 18, 20, and 22.
+- **Docs**: `CONTRIBUTING.md` and `SECURITY.md`.
+- Tests for `cmdInit`, local and `--prod` `cmdVerify`, public API exports, and `schemaType` rendering.
+- `schemaType` config field now drives JSON-LD `@type` (`Article`, `BlogPosting`, `WebPage`).
+
+### Fixed
+
+- `verify` without build output now exits with failure (`VERIFY_FAILED`) instead of succeeding silently.
+- `verify --prod` without a URL is rejected with `CLI_INVALID_ARGS` instead of falling back to local verify.
+
+### Changed
+
+- `cmdVerify` returns structured `VerifyResult` on success for programmatic use.
+- CLI errors include error codes when thrown as `RenderShieldError`.
+- `package.json`: `engines.node >= 18`, `exports`, `keywords`; sample `content/**` no longer published to npm.
+- README: npm install / `npx` quickstart and programmatic API section.
+
+## [0.3.1] - 2025-02-18
+
+### Added
+
+- `verify --prod <url>`: production check that asserts `x-rendershield: bot-hit` and runs the same HTML contract validation as build.
+- Worker response header `x-rendershield`: `bot-hit` | `bot-fallback` | `pass-through` so routing is observable without inferring from HTML.
+- CLI `--version` / `-V`: prints version from package.json.
+- Vitest test suite: contract validation, loadConfig (including sitemap/robots path preservation and worker validation), path safety, and integration build.
+
+### Fixed
+
+- Config: sitemap and robots `path` are preserved and defaulted when only `enabled` is set; no longer lost when using boolean flags.
+- Config: when `worker.enabled` is true, full worker object is kept (lovableOrigin, rewriteRouteBases, etc.) instead of being replaced by the flag.
+- Worker: 500 error response body is generic ("Service temporarily unavailable.") to avoid leaking internals.
+- JSON-LD in generated HTML: script body is no longer HTML-escaped so contract validation and crawlers can parse it.
+
+### Changed
+
+- Help text shows version and documents that `verify --prod` requires `x-rendershield: bot-hit`.
+- TypeScript: reduced `any`; use `unknown` and typed interfaces in CLI, loadConfig, validateOutput, loadMarkdown.
+- README: added "Production check" for `verify --prod`.
+
+## [0.3.0] - 2025-02-18
+
+- Initial npm release with init, build, verify, optional Cloudflare Worker, and HTML contract validation.

package/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to RenderShield
+
+Thank you for your interest in contributing.
+
+## Development setup
+
+Requirements: **Node.js 18+**
+
+```bash
+git clone https://github.com/Lownoise-Studio/rendershield.git
+cd rendershield
+npm install
+npm test
+```
+
+`npm test` runs `tsc` then Vitest. Tests import from `dist/`, so always build before running tests manually.
+
+## Making changes
+
+1. Create a branch from `main`.
+2. Keep changes focused — RenderShield is intentionally narrow in scope.
+3. Add or update tests for behavior changes.
+4. Run `npm test` before opening a pull request.
+5. Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.
+
+## Pull requests
+
+- Describe the problem and the approach.
+- Link related issues when applicable.
+- Ensure CI passes (build + tests on Node 18, 20, 22).
+
+## Code style
+
+- TypeScript strict mode; prefer `unknown` over `any`.
+- Match existing module layout (`src/commands`, `src/core`).
+- Throw `RenderShieldError` with a stable code for user-facing failures.
+- Avoid drive-by refactors unrelated to the change.
+
+## Reporting issues
+
+Use [GitHub Issues](https://github.com/Lownoise-Studio/rendershield/issues). Include Node version, command run, and full error output.

package/README.md

@@ -1,144 +1,227 @@
-# RenderShield
-
-RenderShield ensures crawlers receive complete, static HTML instead of an empty
-JavaScript shell — without changing how humans experience your app.
-
-It prerenders content ahead of time and can route crawler requests to that output
-at the edge, while normal users continue to receive the SPA.
-
-No frameworks required.  
-No vendor lock-in.  
-No guessing what bots see.
-
-If a page builds, the HTML is complete. If it isn’t, the build fails.
-
----
-
-## What problem this solves
-
-Many modern apps technically work but are invisible to:
-
-- search engines
-- social preview scrapers
-- AI crawlers
-
-The content exists only after JavaScript executes.
-Crawlers do not wait.
-
-RenderShield fixes this by generating static, bot-readable HTML and refusing
-to ship incomplete output.
-
----
-
-## What RenderShield does
-
-- Converts structured content into full static HTML pages
-- Injects:
-  - title
-  - meta description
-  - canonical link
-  - Open Graph tags
-  - Twitter tags
-  - JSON-LD (Article)
-- Generates:
-  - index.html per route
-  - sitemap.xml
-  - robots.txt
-  - optional Cloudflare Worker
-- Validates output
-  - missing title, metadata, or content causes the build to fail
-
-If it builds, crawlers will see real content.
-
----
-
-## What it does not do
-
-- It does not run your application
-- It does not execute JavaScript for bots
-- It does not guess content
-- It does not promise rankings, traffic, or citations
-- It does not replace your SPA
-
-It guarantees one thing only:
-that crawlers receive complete HTML.
-
----
-
-## Quickstart
-
-1) Install dependencies
-
-Run:
-
-npm install
-
-2) Initialize RenderShield
-
-Run:
-
-npm run build
-
-This creates:
-- rendershield.config.json
-- sample content
-- a prerender output directory
-
-3) Add content
-
-Place structured content under:
-
-content/
-
-4) Build prerendered output
-
-Run:
-
-node dist/cli.js build
-
-Output is written to:
-
-dist-prerender/
-
-5) Verify output
-
-Run:
-
-node dist/cli.js verify
-
-This prints curl commands you can use to confirm crawler behavior.
-
-**Production check:** After deploying the Worker, run:
-
-`rendershield verify --prod https://your-domain.com`
-
-This fetches the URL as a bot and asserts the response has `x-rendershield: bot-hit` (proving the Worker served prerendered HTML). If the header is missing or `bot-fallback`, the command fails.
-
----
-
-## Deployment
-
-RenderShield is designed to run behind Cloudflare.
-
-A Worker routes crawler requests to prerendered HTML while passing all other
-traffic through unchanged.
-
-See:
-docs/deploy-cloudflare.md
-
----
-
-## Philosophy
-
-RenderShield is intentionally boring.
-
-It does not attempt to outsmart crawlers or simulate browsers.
-It produces correct HTML and refuses to ship broken output.
-
-If crawlers cannot read it, the build fails.
-
----
-
-## License
-
-MIT License
+# RenderShield
+
+RenderShield produces complete, static HTML for crawlers — and can prove
+that bots receive it in production.
+
+It prerenders structured content ahead of time and optionally routes crawler
+requests to that output at the edge, while normal users continue to receive
+your SPA.
+
+No frameworks required.
+No browser rendering.
+No guessing what bots see.
+
+If a page builds, the HTML contract is satisfied.
+If `verify --prod` passes for a URL, that URL is receiving prerendered HTML to bots in production.
+
+---
+
+## What problem this solves
+
+Modern SPAs often render content only after JavaScript executes.
+
+Search engines, social scrapers, and AI crawlers may:
+
+- see an empty shell
+- see partial metadata
+- receive inconsistent output
+
+RenderShield enforces two guarantees:
+
+- **Build-time contract** — Generated HTML must contain required metadata and content.
+- **Production routing proof** — Bots must receive prerendered HTML (verified via header).
+
+---
+
+## What RenderShield does
+
+- Converts structured content (Markdown) into full static HTML pages
+- Injects:
+  - `<title>`
+  - meta description
+  - canonical link
+  - Open Graph tags
+  - Twitter tags
+  - JSON-LD (Article, BlogPosting, WebPage)
+- Generates:
+  - index.html per route
+  - sitemap.xml
+  - robots.txt
+  - optional Cloudflare Worker
+- Validates output:
+  - missing title, metadata, or article body causes the build to fail
+- Verifies behavior:
+  - `verify` (local) — prints curl smoke-test commands for built output; fails if output is missing (does not fetch URLs or validate HTML)
+  - `verify --prod <url>` — fetches production as Googlebot, asserts `x-rendershield: bot-hit`, and validates the HTML contract; fails if the Worker is missing or falling back
+
+---
+
+## What it does not do
+
+- It does not execute your application
+- It does not render JavaScript for bots
+- It does not guess content
+- It does not guarantee rankings or traffic
+- It does not replace your SPA
+
+It guarantees one thing only:
+that bot-facing HTML meets a defined contract —
+and (optionally) that production routing serves it.
+
+---
+
+## Quickstart
+
+Requires **Node.js 18+**.
+
+### From npm
+
+```bash
+npm install -D @lownoise-studio/rendershield
+```
+
+```bash
+npx rendershield init
+npx rendershield build
+npx rendershield verify
+```
+
+Add a script to `package.json` if you prefer:
+
+```json
+{
+  "scripts": {
+    "prerender": "rendershield build",
+    "prerender:verify": "rendershield verify"
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/Lownoise-Studio/rendershield.git
+cd rendershield
+npm install
+npm run build
+```
+
+**Initialize**
+
+```bash
+npx rendershield init
+```
+
+Or:
+
+```bash
+npm run start -- init
+```
+
+**Add content**
+
+```
+content/blog/
+```
+
+**Build**
+
+```bash
+rendershield build
+```
+
+Or with npx:
+
+```bash
+npx rendershield build
+```
+
+**Output**
+
+```
+dist-prerender/
+```
+
+**Local verify**
+
+```bash
+rendershield verify
+```
+
+Prints curl commands for a built page (from `dist-prerender/`). Use this after `build` to get smoke-test commands for your Worker setup. Exits with code 1 if output is missing; it does **not** fetch URLs or validate HTML.
+
+**Local contract check (CI-friendly)**
+
+```bash
+rendershield verify --check
+rendershield verify --all --check
+```
+
+Validates built HTML against the same bot contract as `build`, without network access.
+
+**Production verify (after deploying Worker)**
+
+Pass a **prerendered route URL** (not just the domain root):
+
+```bash
+rendershield verify --prod https://your-domain.com/blog/hello-world
+```
+
+This command:
+
+- Fetches the URL as Googlebot (and as a human browser for comparison)
+- Requires `x-rendershield: bot-hit` on the bot response
+- Validates metadata + JSON-LD + article content on the bot response
+- Exits with code 1 if anything fails
+
+Proves routing for **that URL** only. Use `rendershield verify --prod --all` to check every route from build output.
+
+Config reference: [docs/CONFIG.md](docs/CONFIG.md) · JSON Schema: `rendershield.config.schema.json`
+
+---
+
+## Programmatic API
+
+RenderShield can be used as a library:
+
+```ts
+import { cmdBuild, loadConfig, checkPrerenderContract, RenderShieldError } from "@lownoise-studio/rendershield";
+
+await cmdBuild(process.cwd());
+```
+
+Exported commands, config loaders, HTML renderer, contract validators, and artifact generators are available from the package root. Errors throw `RenderShieldError` with stable `code` values for CI and tooling. ESM `import` only (no CommonJS `require`).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
+
+---
+
+## Deployment
+
+Designed for Cloudflare Workers.
+
+The generated Worker (enabled by default in `init`; set `worker.enabled: false` to skip):
+
+- Rewrites bot requests on configured route bases (e.g. `/blog/`)
+- Sets `x-rendershield` on all responses
+- Makes routing observable and testable
+
+See: [docs/deploy-cloudflare.md](docs/deploy-cloudflare.md)
+
+---
+
+## Philosophy
+
+RenderShield is intentionally narrow.
+
+It does not attempt to simulate browsers.
+It does not promise SEO outcomes.
+It enforces a deterministic HTML contract and observable crawler routing.
+
+Boring on purpose.
+
+---
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 1.0.x   | Yes       |
+| < 1.0   | No        |
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Email security reports to the maintainers via the contact listed on the [GitHub repository](https://github.com/Lownoise-Studio/rendershield). Include:
+
+- A description of the issue and potential impact
+- Steps to reproduce
+- Affected versions
+- Any suggested fix, if you have one
+
+We aim to acknowledge reports within **5 business days** and will coordinate disclosure and a fix before publishing details.
+
+## Scope notes
+
+RenderShield generates static HTML and an optional Cloudflare Worker template. Deployment, DNS, TLS, and Worker binding configuration are the operator's responsibility. Security issues in generated Worker routing logic or path-safety checks in the build command are in scope for this project.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -3,31 +3,40 @@ 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");
 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/
+    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 args = process.argv.slice(2);
-    const cmd = args[0]?.trim();
+    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);
@@ -38,22 +47,26 @@ async function main() {
     }
     try {
         if (cmd === "init") {
-            await cmdInit();
+            await cmdInit(undefined, globalOptions);
             return;
         }
         if (cmd === "build") {
-            await cmdBuild();
+            await cmdBuild(undefined, globalOptions);
             return;
         }
         if (cmd === "verify") {
-            const verifyArgs = args.slice(1);
-            if (verifyArgs.includes("-h") || verifyArgs.includes("--help")) {
+            if (cmdArgs.includes("-h") || cmdArgs.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);
+            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`);
@@ -61,7 +74,7 @@ async function main() {
         process.exit(1);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = formatCliError(err);
         console.error(`\nRenderShield error: ${msg}\n`);
         process.exit(1);
     }