vagejs 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,172 @@
 <p align="center">
-  <img src="assets/brand/vagejs-logo.svg" alt="VAGE JS" width="320">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/brand/vagejs-logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/agevenkat/vagejs/main/assets/brand/vagejs-logo.svg" alt="vagejs" width="320">
+  </picture>
 </p>
 
-# VAGE JS
+<p align="center">
+  <a href="https://www.npmjs.com/package/vagejs"><img src="https://img.shields.io/npm/v/vagejs?color=4F46E5&label=npm" alt="npm version"></a>
+  <a href="https://github.com/agevenkat/vagejs/actions/workflows/ci.yml"><img src="https://github.com/agevenkat/vagejs/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/vagejs?color=2E2A8C" alt="MIT license"></a>
+</p>
+
+# vagejs
+
+An AI-native, static-first web framework. Write pages in Markdown, and vagejs builds a fast static site with SEO, `llms.txt`, accessibility and security handled for you. It's built so AI coding agents can use it without guessing. **Pre-release (0.x).**
+
+- **Static by default**: plain HTML, no client JavaScript unless you add analytics.
+- **SEO built in**: `robots.txt`, `sitemap.xml`, `llms.txt`, canonical URLs, Open Graph and JSON-LD, generated from your pages.
+- **Checks before you ship**: `vage check` (links, SEO, structured data, accessibility) and `vage audit` (page-weight budgets, axe, optional Lighthouse and PageSpeed).
+- **Safe by default**: page content is sanitized; secrets, build output and force-pushes are refused; Cloudflare deploys get a computed Content-Security-Policy.
+- **Agent-friendly**: every site ships with `AGENTS.md`, and `vage info --json` describes every command and config option.
+
+## Quick start
+
+Requires **Node.js 22.12 or newer**.
+
+```bash
+npm create vagejs@latest my-site
+cd my-site
+npm install
+npm run dev
+```
+
+Open the URL it prints. Edit `src/pages/index.md` and the browser reloads.
+
+## Using vagejs
+
+### Project layout
+
+```text
+my-site/
+├── src/
+│   ├── pages/          # every .md file is a page
+│   │   ├── index.md    # → /
+│   │   ├── about.md    # → /about/
+│   │   └── blog/
+│   │       └── first-post.md   # → /blog/first-post/
+│   └── layouts/
+│       └── default.ts  # HTML around each page
+├── public/             # copied to the site as-is (favicons, images)
+├── vage.config.ts      # site settings
+└── AGENTS.md           # instructions for AI coding agents
+```
+
+### Write a page
+
+```markdown
+---
+title: Pricing
+description: Plans and prices.
+---
+
+# Pricing
+
+Our plans start at …
+```
+
+Save it as `src/pages/pricing.md` and it's served at `/pricing/`. `title` is required. `description`, `draft`, `noindex`, `canonical`, `image`, `type: article`, `author`, `datePublished` and `dateModified` are optional; see [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md).
+
+Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` and `height` from the file, so the page doesn't jump while loading.
+
+### Write a layout
+
+Layouts are TypeScript functions. The `html` template tag escapes every value for you; `raw()` inserts trusted HTML such as the rendered page. (Escaping doesn't check URLs, so validate link targets that come from frontmatter.) `pages` lists every published page, and `collection()` picks and sorts them:
+
+```ts
+import { collection, html, raw, z, type Layout } from "vagejs";
+
+// Optional: fields this layout accepts. Pages using it are checked strictly, so typos fail the build.
+export const frontmatter = z.object({ intro: z.string().optional() });
+
+const layout: Layout = ({ content, page, site, pages }) => html`<!doctype html>
+<html lang="${site.lang}">
+  <head><title>${page.title}</title></head>
+  <body>
+    <main>${raw(content)}</main>
+    <h2>Latest posts</h2>
+    <ul>${collection(pages, { under: "/blog/", sort: "date", limit: 5 }).map((p) => html`<li><a href="${p.route}">${p.title}</a></li>`)}</ul>
+  </body>
+</html>`;
+
+export default layout;
+```
+
+### Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `npm run dev` | Dev server with live reload |
+| `npm run check` | Links, SEO, structured data and basic accessibility; writes nothing |
+| `npm run build` | Static site in `dist/`, plus `robots.txt`, `sitemap.xml`, `llms.txt` |
+| `npm run audit` | Page-weight budgets and automated accessibility (`-- --lighthouse` adds Lighthouse) |
+| `npm run preview` | Serves `dist/` locally, the way a static host would |
+
+Add `--json` to `npx vage build`, `check` or `audit` for machine-readable output. Failures exit with code 1.
+
+### Configure the site
+
+`vage.config.ts`:
+
+```ts
+import { defineConfig } from "vagejs";
+
+export default defineConfig({
+  site: "https://example.com", // your real domain (used for canonical URLs and the sitemap)
+  title: "My Website",
+  description: "What this site is about.",
+  seo: {
+    robots: { aiTraining: "disallow" }, // optional: block AI training crawlers, keep search
+    llmsTxt: { full: false },
+  },
+  redirects: { "/old-page/": "/new-page/" },
+});
+```
 
-An AI-native, static-first web framework. **Pre-release (0.x).**
+Unknown keys are an error, so typos don't silently do nothing. `npx vage info --json` prints the full schema.
 
-## What works today
+### Deploy
+
+```bash
+npx vage deploy:github --remote https://github.com/you/site.git   # check, build, safe commit + push (asks first)
+npx vage deploy                                                  # GitHub Pages via Actions
+npx vage deploy --target cloudflare-workers --project my-site    # Cloudflare Workers: new version, no downtime
+npx vage deploy --target cloudflare-pages --project my-site      # older Cloudflare Pages projects
+```
+
+Every deploy shows its plan and asks for confirmation (`--dry-run` to preview, `--yes` to skip). It reports success only after the host confirms.
+
+Cloudflare now creates new static sites as Workers, so use `cloudflare-workers` for new projects. For a custom domain, add a `wrangler.jsonc` with your `routes`; vagejs uses it and switches versions without re-attaching domains, so the site stays up during deploys.
+
+### Analytics, Search Console and audits of live pages
+
+Optional, and off until configured: GA4 or Google Tag Manager (consent denied by default), Plausible, Microsoft Clarity, IndexNow. `vage connect gsc|ga4` adds read-only Search Console and GA4 reports, and `vage audit --url https://your-site` runs PageSpeed and CrUX with **your own** Google API key. Details are in the generated `AGENTS.md`.
+
+## Updating
+
+vagejs follows semver. While it's 0.x, a minor version (0.1 → 0.2) may include breaking changes, so read the release notes before moving up a minor version.
+
+```bash
+npm outdated vagejs           # see what's available
+npm update vagejs             # latest patch in your range (with ^0.2.0: any 0.2.x)
+npm install vagejs@latest     # move to the newest version, including a new minor
+npx vage --version            # confirm
+npx vage check && npx vage build
+```
+
+If your config pins the rule pack (`guidelines: { rulePack: "…" }`), a build after an update that ships new provider rules stops with a message. Review them with `npx vage guidelines`, then update the pin. New projects always use the latest version through `npm create vagejs@latest`.
+
+## Use with AI coding agents
+
+Every site includes `AGENTS.md` (conventions, recipes, definition of done) and `CLAUDE.md` (imports `AGENTS.md`). Agents can discover the API instead of guessing:
+
+```bash
+npx vage info --json    # commands, options, config and frontmatter JSON Schemas
+npx vage check --json   # findings with file, rule and fix hints
+```
+
+## Command reference
 
 ```bash
 vage create <dir> [--vage-spec <spec>] [--json]   # scaffold a Markdown site
@@ -16,8 +176,9 @@ vage check    [--root .] [--json] [--strict]      # SEO, links, JSON-LD, basic a
 vage audit    [--root .] [--lighthouse] [--url U] [--strategy mobile|desktop|both] [--strict] [--json]
                                                   # budgets + axe a11y; optional Lighthouse; PageSpeed/CrUX for deployed URLs
 vage preview  [--root .] [--port N] [--host]      # serve dist/ locally
-vage deploy:github [--remote URL] [--dry-run] [--yes] [--json]   # check, build, safe commit + push (asks first)
+vage deploy:github [--remote URL] [--branch B] [-m MSG] [--dry-run] [--yes] [--json]   # check, build, safe commit + push (asks first)
 vage deploy        [--remote URL] [--no-wait] [--dry-run] [--yes] # GitHub Pages via Actions; confirms with GitHub
+vage deploy --target cloudflare-workers [--project NAME]          # new Worker version at 100%; custom domains stay up
 vage deploy --target cloudflare-pages --project NAME [--branch B] # Wrangler upload; preview URL per branch
 vage indexnow --changed-since REF | --urls … | --all              # IndexNow URL notification (asks first)
 vage connect gsc|ga4 / vage disconnect google      # read-only Google OAuth (PKCE, loopback); token outside the repo
@@ -27,45 +188,49 @@ vage guidelines [--json]                          # rule pack: provider facts in
 vage info     [--json]                            # commands + config/frontmatter JSON Schemas for agents
 ```
 
-Generated sites include `AGENTS.md` (conventions, recipes, definition of done) and `CLAUDE.md` (imports AGENTS.md).
+## Planned, not implemented
+
+Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server, image resizing and WebP/AVIF conversion.
 
-Failures exit with code 1. With `--json`, output is `{ "ok": true, ... }` or `{ "ok": false, "error": "..." }`.
+## Security
+
+Page content is sanitized, dev/preview servers serve only what a site needs, and Cloudflare deploys get security headers with a computed Content-Security-Policy. Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
 
-See [`templates/starter/AGENTS.md`](templates/starter/AGENTS.md) for routing, frontmatter, layouts and config, and [`docs/DECISIONS.md`](docs/DECISIONS.md) for design decisions.
+### Protection against spam injection
 
-## Getting started
+A static site has no admin panel, database or plugins to break into, so attackers go after your content, your repository or your host instead, usually to plant hidden links and spam pages. vagejs checks for that on every build:
+
+| Protection | What it does |
+| --- | --- |
+| Outbound link lock | `links.lock.json` lists the domains your site may link to. A link to any other domain fails `vage check` (and so every deploy) until you approve it with `vage links approve <domain>`. It covers links, SVG links, canonical and `og:url`, meta refresh, iframes and forms. With `security.outboundLinks: "require"` (the default for new sites), deleting the file is an error too. |
+| No hidden links | Inline styles, SVG `xlink:href` and legacy tags like `<font>` and `<marquee>` are stripped from page content, and `vage check` fails on external links hidden with CSS, `aria-hidden`, zero-size SVG or no visible content, in content and layouts. |
+| Spam words | `vage check` warns about common injected-spam terms (casino, pharmacy, payday loans…). |
+| Live-site verification | `vage verify` compares the live site with your files: links and other targets, scripts, event handlers, JSON-LD, text (spam words are errors), `robots.txt` and sitemap pages. It also looks at every page as Googlebot, to catch spam shown only to search engines. New sites include a daily GitHub Actions check (opt in with the `VAGE_VERIFY_URL` variable). |
+| Supply chain | New sites run `npm audit` in CI and get Dependabot updates. |
 
 ```bash
-npm create vagejs@latest my-site
-cd my-site
-npm install
-npm run dev
+npx vage links                    # list external domains: approved or NEW
+npx vage links approve github.com # approve one (asks first)
+npx vage verify                   # compare the live site with your files
 ```
 
-## Releasing
-
-See [docs/RELEASING.md](docs/RELEASING.md).
+Also protect the accounts around the site: two-factor authentication on GitHub, npm, your host and your domain registrar; branch protection on `main`; and Google Search Console alerts for security issues.
 
-## Development
+## Contributing
 
 ```bash
+npm install
 npm run typecheck
 npm test            # unit + integration (dev server, preview, build)
 npm run test:e2e    # pack -> create -> npm install/ci -> build (needs npm registry or cache)
 ```
 
-## Planned, not implemented
-
-Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, sitemap indexes, MCP server. See `VAGE_JS_BUILD_SPEC.md`.
-
-## Security
-
-Page content is sanitized, dev/preview servers serve only what a site needs, and Cloudflare deploys get security headers with a computed Content-Security-Policy. Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
+Design decisions: [docs/DECISIONS.md](docs/DECISIONS.md). Provider rules and how they're monitored: [docs/GUIDELINES.md](docs/GUIDELINES.md). Releasing: [docs/RELEASING.md](docs/RELEASING.md).
 
 ## Brand assets
 
 - `assets/brand/vagejs-icon.svg`: the icon, as received (with C2PA content credentials).
-- `assets/brand/vagejs-logo.svg`: the wordmark with **Space Grotesk Bold embedded** (a 1.6 KB WOFF2 subset of the glyphs used), so it renders the same without the font installed. Space Grotesk is © 2020 The Space Grotesk Project Authors, under the SIL Open Font License 1.1 (`assets/brand/fonts/OFL.txt`). Editing the file invalidated its C2PA signature, so that block was removed.
+- `assets/brand/vagejs-logo.svg` and `vagejs-logo-dark.svg`: the wordmark for light and dark backgrounds, with **Space Grotesk Bold embedded** (a 1.6 KB WOFF2 subset of the glyphs used), so it renders the same without the font installed. Space Grotesk is © 2020 The Space Grotesk Project Authors, under the SIL Open Font License 1.1 (`assets/brand/fonts/OFL.txt`). Editing the file invalidated its C2PA signature, so that block was removed. The dark variant only changes the text colors (`#F4F5FA` and `#A5B4FC`).
 - New sites get `favicon.svg`, `favicon.ico` (16/32/48) and `apple-touch-icon.png` (180) in `public/`.
 
 Regenerate (maintainer tools; need Chrome, and Python with `fonttools` and `brotli`):

package/dist/checks/check.d.ts

@@ -18,6 +18,8 @@ export interface CheckResult {
     pagesChecked: number;
     findings: Finding[];
 }
+/** Paths of frontmatter values that came out empty (null), e.g. "faq.items[3].Claude and other AI search?". */
+export declare function emptyValues(value: unknown, at?: string): string[];
 /**
  * Static checks on the rendered site (nothing is written to disk).
  * Passing checks mean the output is technically sound; they do not guarantee

package/dist/checks/check.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse } from "node-html-parser";
 import { createBuildLoader } from "../core/loader.js";
 import { listedPages, renderSite } from "../core/site.js";
+import { externalHost, hiddenReason, isEmptyLink, LINK_LOCK, linkTarget, outboundHosts, readLinkLock, spamHits } from "./integrity.js";
 const DOCS = {
     title: "https://developers.google.com/search/docs/appearance/title-link",
     description: "https://developers.google.com/search/docs/appearance/snippet",
@@ -13,7 +14,19 @@ const DOCS = {
     lang: "https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html",
     linkPurpose: "https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html",
     robots: "https://developers.google.com/search/docs/crawling-indexing/robots/intro",
+    yamlFlow: "https://yaml.org/spec/1.2.2/#74-flow-collection-styles",
 };
+/** Paths of frontmatter values that came out empty (null), e.g. "faq.items[3].Claude and other AI search?". */
+export function emptyValues(value, at = "") {
+    if (value === null)
+        return [at || "(frontmatter)"];
+    if (Array.isArray(value))
+        return value.flatMap((v, i) => emptyValues(v, `${at}[${i}]`));
+    if (typeof value === "object" && value !== undefined) {
+        return Object.entries(value).flatMap(([k, v]) => emptyValues(v, at ? `${at}.${k}` : k));
+    }
+    return [];
+}
 /**
  * Static checks on the rendered site (nothing is written to disk).
  * Passing checks mean the output is technically sound; they do not guarantee
@@ -23,7 +36,7 @@ export async function check(root, options = {}) {
     root = path.resolve(root);
     const loader = await createBuildLoader(root);
     try {
-        const model = await renderSite(root, loader.load);
+        const model = await renderSite(root, loader.load, { collectErrors: true });
         const findings = checkSite(root, model);
         const errors = findings.filter((f) => f.severity === "error").length;
         const warnings = findings.length - errors;
@@ -31,7 +44,7 @@ export async function check(root, options = {}) {
             ok: errors === 0 && (!options.strict || warnings === 0),
             errors,
             warnings,
-            pagesChecked: model.pages.length + (model.notFound ? 1 : 0),
+            pagesChecked: model.pages.length + (model.notFound ? 1 : 0) + model.pageErrors.length,
             findings,
         };
     }
@@ -41,7 +54,13 @@ export async function check(root, options = {}) {
 }
 export function checkSite(root, model) {
     const findings = model.warnings.map((message) => ({ rule: "config", severity: "warning", message }));
+    for (const e of model.pageErrors)
+        findings.push({ rule: "page-error", severity: "error", message: e.message, source: e.source });
     const outputs = outputPaths(root, model);
+    // Pages that failed to render are already reported; links to them aren't broken links on top of that.
+    for (const e of model.pageErrors)
+        if (e.route)
+            outputs.add(`${e.route}index.html`);
     const drafts = new Set(model.draftRoutes);
     const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
     for (const page of pages) {
@@ -50,10 +69,31 @@ export function checkSite(root, model) {
     }
     findings.push(...checkDuplicates(listedPages(model)));
     findings.push(...checkRobots(model));
+    findings.push(...checkRedirectTargets(model, outputs));
+    findings.push(...checkOutboundLinks(root, model));
     return findings;
 }
 function checkPage(page, doc, model, outputs, drafts, add) {
     const indexable = !page.meta.noindex;
+    if (model.site.security.spamPatterns) {
+        const text = `${doc.querySelector("body")?.text ?? ""} ${doc.querySelectorAll("a[href]").map((a) => a.getAttribute("href")).join(" ")}`;
+        const hits = spamHits(text);
+        if (hits.length) {
+            add({
+                rule: "spam-pattern",
+                severity: "warning",
+                message: `Page contains words common in injected spam (${hits.join(", ")}). If you didn't write them, check this page's history. Turn off with security.spamPatterns: false.`,
+            });
+        }
+    }
+    for (const key of emptyValues(page.frontmatter)) {
+        add({
+            rule: "frontmatter-empty",
+            severity: "warning",
+            message: `Frontmatter "${key}" has no value. If you meant to write text there, check for a missing value; inside { } a comma or colon splits the text, so wrap it in quotes.`,
+            docs: DOCS.yamlFlow,
+        });
+    }
     if (!doc.querySelector("html")?.getAttribute("lang")) {
         add({ rule: "html-lang", severity: "error", message: "<html> has no lang attribute.", docs: DOCS.lang });
     }
@@ -104,6 +144,7 @@ function checkPage(page, doc, model, outputs, drafts, add) {
     }
     for (const a of doc.querySelectorAll("a[href]")) {
         const href = a.getAttribute("href");
+        checkHiddenLink(a, href, model, add);
         if (!a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])")) {
             add({ rule: "link-text", severity: "warning", message: `Link to "${href}" has no accessible text.`, docs: DOCS.linkPurpose });
         }
@@ -127,6 +168,11 @@ function checkPage(page, doc, model, outputs, drafts, add) {
             add({ rule: "link-trailing-slash", severity: "warning", message: `Link to "${href}" redirects; use "${target}/".` });
         }
     }
+    // SVG links (a xlink:href) aren't in the loop above; they get the hidden-link check too.
+    for (const a of doc.querySelectorAll("a")) {
+        if (!a.hasAttribute("href") && a.getAttribute("xlink:href"))
+            checkHiddenLink(a, linkTarget(a), model, add);
+    }
     for (const [selector, attr] of [
         ["img[src]", "src"],
         ["script[src]", "src"],
@@ -253,6 +299,64 @@ function checkDuplicates(pages) {
     }
     return findings;
 }
+/** Links visitors can't see but search engines can: the signature of injected spam. */
+function checkHiddenLink(a, href, model, add) {
+    const external = externalHost(href, model.site.site) !== undefined;
+    const hidden = hiddenReason(a) ?? (external && isEmptyLink(a) ? { reason: "empty (no text or image)", strength: "strong" } : undefined);
+    if (!hidden)
+        return;
+    add({
+        rule: "link-hidden",
+        severity: external && hidden.strength === "strong" ? "error" : "warning",
+        message: `Link to "${href}" is ${hidden.reason}: visitors can't see it, but search engines can. Hidden links are a common sign of injected spam. Remove it, or show it.`,
+    });
+}
+/**
+ * Outbound link guard: with security.outboundLinks "lock", every external domain must be
+ * listed in links.lock.json. A domain nobody approved is how injected spam usually shows up.
+ */
+function checkOutboundLinks(root, model) {
+    if (model.site.security.outboundLinks === "off")
+        return [];
+    const hosts = outboundHosts(model);
+    const lock = readLinkLock(root);
+    if (!lock && model.site.security.outboundLinks === "require") {
+        return [{ rule: "links-lock-missing", severity: "error", message: `${LINK_LOCK} is missing, but security.outboundLinks is "require". Restore it from git, or have the site owner recreate it with "npx vage links approve --all" after reviewing "npx vage links".` }];
+    }
+    if (!lock) {
+        return hosts.size
+            ? [{ rule: "links-lock-missing", severity: "warning", message: `The site links to ${hosts.size} external domain(s) and has no ${LINK_LOCK}. The site owner should review them with "npx vage links" and approve them with "npx vage links approve --all"; after that, links to any new domain fail the check.` }]
+            : [];
+    }
+    const approved = new Set(lock.domains);
+    const findings = [];
+    for (const [host, pages] of hosts) {
+        if (approved.has(host))
+            continue;
+        const where = pages.map((p) => p.route);
+        findings.push({
+            rule: "link-unapproved",
+            severity: "error",
+            message: `Links to ${host} (on ${where.slice(0, 3).join(", ")}${where.length > 3 ? ` and ${where.length - 3} more` : ""}) aren't approved in ${LINK_LOCK}. If the site owner added them on purpose, they approve with "npx vage links approve ${host}". Otherwise remove them: unapproved links are how injected spam usually shows up.`,
+            page: pages[0].route,
+            source: pages[0].source,
+        });
+    }
+    return findings;
+}
+/** Redirects to a page on this site must land on something that exists. */
+function checkRedirectTargets(model, outputs) {
+    const findings = [];
+    for (const r of model.redirects) {
+        const target = internalPath(r.to, "/", model.site.site);
+        if (target === undefined)
+            continue;
+        if (target === MALFORMED || resolveOutput(target, outputs) === "missing") {
+            findings.push({ rule: "redirect-target", severity: "error", message: `Redirect from "${r.from}" points to "${r.to}", which isn't a page or file on this site.`, source: "vage.config.ts" });
+        }
+    }
+    return findings;
+}
 function checkRobots(model) {
     const robots = model.files.get("robots.txt");
     if (!robots)

package/dist/checks/integrity.d.ts

@@ -0,0 +1,36 @@
+import { type HTMLElement } from "node-html-parser";
+import type { SiteModel } from "../core/site.js";
+/**
+ * Defenses against injected spam (the classic hacked-site problem): links hidden with
+ * CSS, outbound links nobody approved, and common spam vocabulary. These run in
+ * `vage check` on the final HTML, so they cover page content and layouts alike.
+ */
+export declare const LINK_LOCK = "links.lock.json";
+export interface Hidden {
+    reason: string;
+    /** "strong": a CSS/SVG trick with no legitimate use around a link. "soft": hidden by a mechanism sites also use for menus (hidden, closed <details>). */
+    strength: "strong" | "soft";
+}
+/** Why this element (or an ancestor) is hidden from people, if it is. Only inline signals; stylesheets aren't evaluated. */
+export declare function hiddenReason(el: HTMLElement): Hidden | undefined;
+/** A link with nothing a visitor can see or a screen reader can announce. */
+export declare function isEmptyLink(a: HTMLElement): boolean;
+/** href of <a>/<area>, including SVG's xlink:href. */
+export declare function linkTarget(a: HTMLElement): string | undefined;
+/** Normalized host of an external http(s) link ("www." dropped), or undefined for internal/other links. */
+export declare function externalHost(href: string, site: string | undefined): string | undefined;
+/** Lowercase, punycode, no "www.", no trailing dot: one spelling per host. */
+export declare function normalizeHost(host: string): string;
+/** Every external host the built site links to, with the pages that link there. */
+export declare function outboundHosts(model: SiteModel): Map<string, {
+    route: string;
+    source: string;
+}[]>;
+export interface LinkLock {
+    domains: string[];
+}
+export declare function readLinkLock(root: string): LinkLock | undefined;
+export declare function writeLinkLock(root: string, domains: Iterable<string>): void;
+/** Words that rarely appear on legitimate business sites but are staples of injected spam. Warnings only. */
+export declare const SPAM_PATTERNS: [RegExp, string][];
+export declare function spamHits(text: string): string[];

package/dist/checks/integrity.js

@@ -0,0 +1,145 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "node-html-parser";
+import { VageError } from "../core/errors.js";
+/**
+ * Defenses against injected spam (the classic hacked-site problem): links hidden with
+ * CSS, outbound links nobody approved, and common spam vocabulary. These run in
+ * `vage check` on the final HTML, so they cover page content and layouts alike.
+ */
+export const LINK_LOCK = "links.lock.json";
+// ---------------------------------------------------------------- hidden links
+const HIDING_STYLES = [
+    [/display\s*:\s*none/i, "display:none"],
+    [/visibility\s*:\s*(hidden|collapse)/i, "visibility:hidden"],
+    [/opacity\s*:\s*0(\.0+)?\s*(;|$|!)/i, "opacity:0"],
+    [/font-size\s*:\s*0(\.0+)?(px|em|rem|%)?\s*(;|$|!)/i, "font-size:0"],
+    [/(^|;|\s)(width|height|max-width|max-height)\s*:\s*0(px)?\s*(;|$|!)/i, "zero size"],
+    [/(^|;|\s)(left|top|right|bottom|margin-left|margin-top)\s*:\s*-\s*\d{3,}/i, "positioned off-screen"],
+    [/text-indent\s*:\s*-\s*\d{3,}/i, "text pushed off-screen"],
+    [/clip\s*:\s*rect\(\s*0/i, "clipped away"],
+    [/clip-path\s*:\s*inset\(\s*(50%|100%)/i, "clipped away"],
+];
+/** Why this element (or an ancestor) is hidden from people, if it is. Only inline signals; stylesheets aren't evaluated. */
+export function hiddenReason(el) {
+    for (let node = el; node && node.tagName; node = node.parentNode) {
+        const tag = node.tagName.toLowerCase();
+        const where = node === el ? "" : "inside ";
+        const style = node.getAttribute?.("style");
+        if (style) {
+            const hit = HIDING_STYLES.find(([re]) => re.test(style));
+            if (hit)
+                return { reason: `${where ? "inside an element " : ""}hidden with ${hit[1]}`, strength: "strong" };
+        }
+        if (node.getAttribute?.("aria-hidden") === "true")
+            return { reason: `${where}aria-hidden="true"`, strength: "strong" };
+        if (tag === "svg" && (/^0(px)?$/.test(node.getAttribute("width") ?? "") || /^0(px)?$/.test(node.getAttribute("height") ?? ""))) {
+            return { reason: "inside a zero-size <svg>", strength: "strong" };
+        }
+        if (node.hasAttribute?.("hidden"))
+            return { reason: `inside a hidden <${tag}>`, strength: "soft" };
+        if (tag === "details" && node !== el && !node.hasAttribute("open") && !el.closest?.("summary")) {
+            return { reason: "inside a closed <details>", strength: "soft" };
+        }
+    }
+    return undefined;
+}
+/** A link with nothing a visitor can see or a screen reader can announce. */
+export function isEmptyLink(a) {
+    return !a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])");
+}
+/** href of <a>/<area>, including SVG's xlink:href. */
+export function linkTarget(a) {
+    return a.getAttribute("href") ?? a.getAttribute("xlink:href") ?? undefined;
+}
+// ---------------------------------------------------------------- outbound links
+/** Normalized host of an external http(s) link ("www." dropped), or undefined for internal/other links. */
+export function externalHost(href, site) {
+    let url;
+    try {
+        url = new URL(href.trim(), site ?? "https://site.invalid");
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return undefined;
+    const host = normalizeHost(url.hostname);
+    const own = site ? normalizeHost(new URL(site).hostname) : "site.invalid";
+    return host === own ? undefined : host;
+}
+/** Lowercase, punycode, no "www.", no trailing dot: one spelling per host. */
+export function normalizeHost(host) {
+    return host.toLowerCase().replace(/\.$/, "").replace(/^www\./, "");
+}
+/** Places in a page that send visitors or search engines elsewhere, beyond <a>: all go through the link lock. */
+const OTHER_TARGETS = [
+    ['link[rel="canonical"]', (el) => el.getAttribute("href")],
+    ['meta[property="og:url"]', (el) => el.getAttribute("content")],
+    ["meta[http-equiv]", (el) => (/^refresh$/i.test(el.getAttribute("http-equiv") ?? "") ? /url\s*=\s*['"]?([^'";]+)/i.exec(el.getAttribute("content") ?? "")?.[1] : undefined)],
+    ["iframe[src]", (el) => el.getAttribute("src")],
+    ["form[action]", (el) => el.getAttribute("action")],
+];
+/** Every external host the built site links to, with the pages that link there. */
+export function outboundHosts(model) {
+    const hosts = new Map();
+    const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
+    for (const page of pages) {
+        const seen = new Set();
+        const doc = parse(page.html);
+        const targets = [
+            ...doc.querySelectorAll("a, area").map(linkTarget),
+            ...OTHER_TARGETS.flatMap(([selector, read]) => doc.querySelectorAll(selector).map(read)),
+        ];
+        for (const target of targets) {
+            if (!target)
+                continue;
+            const host = externalHost(target, model.site.site);
+            if (!host || seen.has(host))
+                continue;
+            seen.add(host);
+            hosts.set(host, [...(hosts.get(host) ?? []), { route: page.route, source: page.source }]);
+        }
+    }
+    return new Map([...hosts].sort(([a], [b]) => a.localeCompare(b)));
+}
+export function readLinkLock(root) {
+    const file = path.join(root, LINK_LOCK);
+    if (!fs.existsSync(file))
+        return undefined;
+    let data;
+    try {
+        data = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new VageError(`${LINK_LOCK} is not valid JSON: ${err.message}`, file);
+    }
+    const domains = data?.domains;
+    if (!Array.isArray(domains) || !domains.every((d) => typeof d === "string")) {
+        throw new VageError(`${LINK_LOCK} must look like { "domains": ["example.com"] }.`, file);
+    }
+    return { domains: domains.map(normalizeHost) };
+}
+export function writeLinkLock(root, domains) {
+    const sorted = [...new Set(domains)].sort();
+    const body = {
+        $comment: "External domains this site may link to. vage check fails on links to any other domain. Only the site owner approves new ones: npx vage links approve <domain>",
+        domains: sorted,
+    };
+    fs.writeFileSync(path.join(root, LINK_LOCK), `${JSON.stringify(body, null, 2)}\n`);
+}
+// ---------------------------------------------------------------- spam vocabulary
+/** Words that rarely appear on legitimate business sites but are staples of injected spam. Warnings only. */
+export const SPAM_PATTERNS = [
+    [/\b(online|best|free|top)\s+casinos?\b|\bcasino\s+(bonus|online|games?|sites?)\b/i, "casino"],
+    [/\b(viagra|cialis|levitra|kamagra)\b/i, "pharmacy spam"],
+    [/\bpayday\s+loans?\b/i, "payday loans"],
+    [/\breplica\s+(watches|handbags|bags|rolex)\b/i, "replica goods"],
+    [/\bescort\s+(girls|agency|agencies)\b/i, "escort ads"],
+    [/\bporn\b|\bxxx\s+(videos?|porn|sex)\b/i, "adult content"],
+    [/\bbuy\s+(cheap\s+)?(followers|backlinks|likes)\b/i, "bought followers or backlinks"],
+    [/\bonline\s+slots\b|\bslot\s+gacor\b|\bjudi\s+online\b/i, "online gambling"],
+];
+export function spamHits(text) {
+    return [...new Set(SPAM_PATTERNS.filter(([re]) => re.test(text)).map(([, label]) => label))];
+}

package/dist/checks/links.d.ts

@@ -0,0 +1,18 @@
+import { readLinkLock, writeLinkLock } from "./integrity.js";
+export interface LinkStatus {
+    /** External domains the site links to now, with how many pages link there, and whether they're approved. */
+    domains: {
+        domain: string;
+        pages: string[];
+        approved: boolean;
+    }[];
+    /** Approved domains the site no longer links to. */
+    unused: string[];
+    hasLock: boolean;
+}
+export declare function linkStatus(root: string): Promise<LinkStatus>;
+/** "Bücher.DE." -> "xn--bcher-kva.de"; throws for anything that isn't a bare host (or IP). */
+export declare function parseHost(input: string): string;
+/** The lock file's domains after approving `add` (and, with `prune`, dropping unused ones). */
+export declare function nextLock(status: LinkStatus, current: string[], add: string[], prune: boolean): string[];
+export { readLinkLock, writeLinkLock };