vagejs 0.1.0 → 0.2.0

package/dist/core/render.js

@@ -1,25 +1,30 @@
 import fs from "node:fs";
 import path from "node:path";
-import { parseMarkdown } from "../content/markdown.js";
-import { sanitizeHtml } from "../content/sanitize.js";
+import { z } from "zod";
+import { frontmatterSchema, parseMarkdown } from "../content/markdown.js";
+import { enhanceTrustedHtml, sanitizeHtml } from "../content/sanitize.js";
 import { VageError } from "./errors.js";
-import { escapeHtml } from "./html.js";
+import { clonePlain } from "./clone.js";
+import { escapeHtml, isSafeHtml } from "./html.js";
 import { headTags, injectHead, pageMeta } from "../seo/head.js";
 import { analyticsTags, injectAnalytics } from "../integrations/tags.js";
 export async function renderPage(options) {
     const { root, file, route, site, load } = options;
     const parsed = parseMarkdown(fs.readFileSync(file, "utf8"), file);
     const { frontmatter, body } = parsed;
-    const content = site.markdown.html === "allow" ? parsed.html : await sanitizeHtml(parsed.html);
+    const publicDir = path.join(root, "public");
+    const content = site.markdown.html === "allow" ? await enhanceTrustedHtml(parsed.html, publicDir) : await sanitizeHtml(parsed.html, { publicDir, inlineStyles: site.markdown.inlineStyles });
+    const layout = await applyLayoutFields(root, frontmatter, load, file);
     const meta = pageMeta(site, route, frontmatter, options.notFound);
-    const layout = await resolveLayout(root, frontmatter.layout, load, file);
-    const html = await layout({
+    const result = await layout({
         content,
         page: { route, title: frontmatter.title, description: frontmatter.description, url: meta.canonical, frontmatter },
         site,
+        pages: options.pages ?? [],
     });
+    const html = isSafeHtml(result) ? result.value : result;
     if (typeof html !== "string") {
-        throw new VageError(`Layout "${frontmatter.layout ?? "default"}" must return an HTML string.`, file);
+        throw new VageError(`Layout "${frontmatter.layout ?? "default"}" must return an HTML string or html\`...\`.`, file);
     }
     let out = injectHead(html, headTags(site, meta), file);
     const tags = options.analytics ? analyticsTags(site) : undefined;
@@ -33,15 +38,52 @@ async function resolveLayout(root, name, load, pageFile) {
     const file = LAYOUT_EXTENSIONS.map((ext) => base + ext).find((f) => fs.existsSync(f));
     if (!file) {
         if (!name)
-            return defaultLayout;
+            return { layout: defaultLayout };
         throw new VageError(`Layout "${name}" not found. Expected src/layouts/${name}.ts`, pageFile);
     }
-    const layout = (await load(file)).default;
+    const mod = await load(file);
+    const layout = mod.default;
     if (typeof layout !== "function") {
         throw new VageError("Layout files must default-export a function that returns an HTML string.", file);
     }
+    const schema = mod.frontmatter;
+    if (schema !== undefined && (typeof schema?.safeParse !== "function" || typeof schema.shape !== "object")) {
+        throw new VageError('`export const frontmatter` in a layout must be a Zod object schema: z.object({ ... }) (import { z } from "vagejs").', file);
+    }
+    return { layout: layout, schema };
+}
+const BUILT_IN_FIELDS = new Set(Object.keys(frontmatterSchema.shape));
+/**
+ * Loads the page's layout and, if it exports a `frontmatter` schema, validates the page
+ * against it and fills in defaults (mutating `frontmatter`). Used for rendering and for
+ * `props.pages`, so both see the same values. Returns the layout function.
+ */
+export async function applyLayoutFields(root, frontmatter, load, file) {
+    const { layout, schema } = await resolveLayout(root, frontmatter.layout, load, file);
+    if (schema)
+        Object.assign(frontmatter, validateLayoutFields(frontmatter, schema, frontmatter.layout ?? "default", file));
     return layout;
 }
+/**
+ * Checks the fields a page adds for its layout against the layout's schema. Unknown
+ * fields are errors (a typo would otherwise do nothing); defaults are filled in. A
+ * schema may also declare built-in fields (e.g. make `author` required); those are
+ * validated too. Built-in defaults (type "website", draft/noindex false) are applied
+ * first, so a layout can restrict them but not change their defaults.
+ */
+function validateLayoutFields(frontmatter, schema, layoutName, file) {
+    const declared = new Set(Object.keys(schema.shape ?? {}));
+    const own = Object.fromEntries(Object.entries(frontmatter).filter(([k]) => !BUILT_IN_FIELDS.has(k) || declared.has(k)));
+    // Strict unless the layout chose otherwise (.passthrough() / z.looseObject set a catchall).
+    const loose = schema._zod?.def?.catchall !== undefined;
+    const result = (loose || !schema.strict ? schema : schema.strict()).safeParse(own);
+    if (!result.success) {
+        const detail = result.error instanceof z.ZodError ? z.prettifyError(result.error) : String(result.error);
+        throw new VageError(`Frontmatter doesn't match the "${layoutName}" layout's fields:\n${detail}`, file);
+    }
+    // Zod reuses a default's nested objects across parses; give each page its own copy.
+    return clonePlain(result.data);
+}
 /** Used when a project has no src/layouts/default.ts. */
 export const defaultLayout = ({ content, page, site }) => {
     const title = site.title && site.title !== page.title ? `${page.title} | ${site.title}` : page.title;

package/dist/core/site.d.ts

@@ -12,8 +12,17 @@ export interface SiteRedirect {
     outFile: string;
     html: string;
 }
+export interface PageError {
+    /** Source path relative to the project root. */
+    source: string;
+    /** The route the page would have had (links to it aren't reported again as broken). */
+    route?: string;
+    message: string;
+}
 export interface SiteModel {
     site: SiteConfig;
+    /** Pages that failed to render (only with `collectErrors`; otherwise the first failure throws). */
+    pageErrors: PageError[];
     /** Published pages (drafts excluded). */
     pages: SitePage[];
     skippedDrafts: string[];
@@ -26,6 +35,8 @@ export interface SiteModel {
     warnings: string[];
 }
 /** Renders every page and derives discovery files from the same data, without writing anything. */
-export declare function renderSite(root: string, load: ModuleLoader): Promise<SiteModel>;
+export declare function renderSite(root: string, load: ModuleLoader, options?: {
+    collectErrors?: boolean;
+}): Promise<SiteModel>;
 /** Pages that should appear in sitemap.xml and llms.txt: indexable and canonical to themselves. */
 export declare function listedPages(model: SiteModel): SitePage[];

package/dist/core/site.js

@@ -12,12 +12,14 @@ import { loadConfig } from "./config.js";
 import { VageError } from "./errors.js";
 import { escapeHtml } from "./html.js";
 import { renderPage } from "./render.js";
+import { parseFrontmatter } from "../content/markdown.js";
+import { collectPages } from "./pages.js";
 import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "./routes.js";
 /** Renders every page and derives discovery files from the same data, without writing anything. */
-export async function renderSite(root, load) {
+export async function renderSite(root, load, options = {}) {
     const pagesDir = path.join(root, "src", "pages");
     if (!fs.existsSync(pagesDir)) {
-        throw new VageError(`No src/pages directory found in ${root}. Is this a VAGE JS project?`);
+        throw new VageError(`No src/pages directory found in ${root}. Is this a vagejs project?`);
     }
     const site = await loadConfig(root, load);
     const pinned = site.guidelines.rulePack;
@@ -25,21 +27,40 @@ export async function renderSite(root, load) {
         throw new VageError(`This project pins rule pack ${pinned}, but the installed vagejs ships ${rulePack.version}. ` +
             `Review what changed with "vage guidelines", then update guidelines.rulePack in vage.config.ts.`);
     }
-    const model = { site, pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    const model = { site, pageErrors: [], pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    const collect = options.collectErrors === true;
+    const attempt = async (file, route, work) => {
+        try {
+            await work();
+        }
+        catch (err) {
+            if (!collect)
+                throw err;
+            // Layout code can throw anything (or fail to compile); report it as this page's error.
+            const message = err instanceof VageError ? err.detail : `Layout or render error: ${err?.message ?? String(err)}`;
+            model.pageErrors.push({ source: path.relative(root, file), route, message });
+        }
+    };
+    const pages = await collectPages(root, site, load, { skipInvalid: collect });
     for (const entry of discoverRoutes(pagesDir)) {
-        const page = await renderPage({ root, file: entry.file, route: entry.route, site, load, analytics: true });
         const source = path.relative(root, entry.file);
-        if (page.frontmatter.draft) {
-            model.skippedDrafts.push(source);
-            model.draftRoutes.push(entry.route);
-        }
-        else
+        await attempt(entry.file, entry.route, async () => {
+            // Drafts are skipped before rendering, so their fields can't fail a build.
+            if (parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file).frontmatter.draft) {
+                model.skippedDrafts.push(source);
+                model.draftRoutes.push(entry.route);
+                return;
+            }
+            const page = await renderPage({ root, file: entry.file, route: entry.route, site, load, analytics: true, pages });
             model.pages.push({ ...page, route: entry.route, source, outFile: entry.outFile });
+        });
     }
     const notFound = findNotFoundPage(pagesDir);
     if (notFound) {
-        const page = await renderPage({ root, file: notFound, route: "/404/", site, load, notFound: true, analytics: true });
-        model.notFound = { ...page, route: "/404/", source: path.relative(root, notFound), outFile: "404.html" };
+        await attempt(notFound, undefined, async () => {
+            const page = await renderPage({ root, file: notFound, route: "/404/", site, load, notFound: true, analytics: true, pages });
+            model.notFound = { ...page, route: "/404/", source: path.relative(root, notFound), outFile: "404.html" };
+        });
     }
     checkPublicDir(root, model.warnings);
     model.redirects = buildRedirects(site, new Set(model.pages.map((p) => p.route)));
@@ -78,9 +99,11 @@ function addDiscoveryFiles(root, model) {
     const indexNow = site.integrations.indexNow;
     if (indexNow)
         generate(`${indexNow.key}.txt`, () => `${indexNow.key}\n`);
-    if (site.deploy.target === "cloudflare-pages" && model.redirects.length)
+    // Cloudflare Pages and Workers static assets both read _redirects and _headers.
+    const cloudflare = site.deploy.target === "cloudflare-pages" || site.deploy.target === "cloudflare-workers";
+    if (cloudflare && model.redirects.length)
         generate("_redirects", () => cloudflareRedirects(model.redirects));
-    if (site.deploy.target === "cloudflare-pages" && site.security.headers) {
+    if (cloudflare && site.security.headers) {
         const html = [...model.pages, ...(model.notFound ? [model.notFound] : []), ...model.redirects].map((p) => p.html);
         generate("_headers", () => headersFile(html, site));
     }

package/dist/core/validate.d.ts

@@ -4,6 +4,8 @@
  */
 export declare function assertBranchName(value: string, flag?: string): string;
 export declare function assertCloudflareProject(value: string): string;
+/** Cloudflare Worker names: lowercase letters, digits and "-", up to 63 characters. */
+export declare function assertWorkerName(value: string): string;
 /** https://, ssh://, git@host:path, or a local path. Refuses options and git's command-running transports. */
 export declare function assertGitRemote(value: string): string;
 /** npm dependency spec for new projects: a version/range, "latest", or a local file: tarball. */

package/dist/core/validate.js

@@ -14,6 +14,12 @@ export function assertCloudflareProject(value) {
         throw new VageError(`Invalid --project "${value}". Use lowercase letters, digits and "-".`);
     return value;
 }
+/** Cloudflare Worker names: lowercase letters, digits and "-", up to 63 characters. */
+export function assertWorkerName(value) {
+    if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(value))
+        throw new VageError(`Invalid Worker name "${value}". Use lowercase letters, digits and "-" (up to 63).`);
+    return value;
+}
 /** https://, ssh://, git@host:path, or a local path. Refuses options and git's command-running transports. */
 export function assertGitRemote(value) {
     if (value.startsWith("-") || /^(ext|fd)::/i.test(value) || /[\s\u0000-\u001f]/.test(value)) {

package/dist/deploy/cloudflare-pages.js

@@ -20,7 +20,9 @@ export async function deployCloudflarePages(root, options) {
     if (res.code !== 0) {
         const auth = /auth|login|token|unauthori[sz]ed|10000/i.test(output)
             ? " Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, or run `npx wrangler login`."
-            : "";
+            : /pages_build_output_dir|project not found|delegat|Workers/i.test(output)
+                ? ' Cloudflare now creates new sites as Workers rather than Pages projects. Set deploy.target to "cloudflare-workers" in vage.config.ts and run vage deploy again.'
+                : "";
         return { status: "failure", branch: options.branch, reason: `wrangler failed (exit ${res.code}).${auth}\n${tail(output)}` };
     }
     const deploymentUrl = output.match(/https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.pages\.dev/gi)?.at(-1);

package/dist/deploy/cloudflare-workers.d.ts

@@ -0,0 +1,59 @@
+import type { DeployStatus, Runner } from "./github-pages.js";
+/** In wrangler's own lookup order. */
+export declare const WRANGLER_CONFIGS: string[];
+/** Compatibility date for the generated config; Workers static assets need nothing newer. Checked 2026-10-23. */
+export declare const COMPATIBILITY_DATE = "2026-10-01";
+/** What vagejs needs to know from a project's own wrangler config. */
+export interface WranglerConfig {
+    file: string;
+    name?: string;
+    /** assets.directory, resolved against the project root. */
+    assetsDir?: string;
+    notFoundHandling?: string;
+}
+/**
+ * Reads name and assets settings from the project's wrangler config. Refuses setups where
+ * wrangler could pick a different file or Worker than the one shown: several config files,
+ * a CLOUDFLARE_ENV environment, or a .wrangler/deploy redirect.
+ */
+export declare function readWranglerConfig(root: string, env?: Record<string, string | undefined>): WranglerConfig | undefined;
+export interface WorkersPlan {
+    /** The Worker that will actually be deployed. */
+    worker: string;
+    /** The project's wrangler config, if it has one. */
+    config?: WranglerConfig;
+    warnings: string[];
+}
+/**
+ * Decides which Worker gets deployed, and refuses setups where the plan and what
+ * wrangler would actually do differ (another Worker name, or a folder other than dist/).
+ */
+export declare function planWorkersDeploy(root: string, requested: string | undefined): WorkersPlan;
+export interface WorkersDeployment extends DeployStatus {
+    worker: string;
+    /** How it was deployed: a new version switched to 100% (existing Worker), or a full first deploy. */
+    mode?: "version" | "first-deploy";
+    versionId?: string;
+}
+/**
+ * Deploys dist/ as a Cloudflare Worker with static assets (what Cloudflare now creates
+ * instead of Pages projects; `_headers` and `_redirects` still apply).
+ *
+ * - With a wrangler config in the project (needed for custom domains and routes), that
+ *   file is used as-is; `planWorkersDeploy` has already checked its name and folder.
+ *   Otherwise a temporary config pointing at dist/ is generated, so the project gains no files.
+ * - Existing Workers get `wrangler versions upload` + `versions deploy <id>@100%`: the new
+ *   version takes all traffic without re-applying routes or custom domains, so the site
+ *   stays up. Only Cloudflare's "Worker doesn't exist" error leads to a first `wrangler deploy`.
+ * - Success needs wrangler to succeed AND the live site to answer 200: `siteUrl` when set,
+ *   else the Worker's workers.dev URL (never a version preview URL).
+ */
+export declare function deployCloudflareWorkers(root: string, options: {
+    plan: WorkersPlan;
+    tag?: string;
+    siteUrl?: string;
+    run?: Runner;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    env?: Record<string, string | undefined>;
+}): Promise<WorkersDeployment>;

package/dist/deploy/cloudflare-workers.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { VageError } from "../core/errors.js";
+import { redact } from "../integrations/http.js";
+import { WRANGLER } from "./cloudflare-pages.js";
+import { runCommand } from "./github-pages.js";
+/** In wrangler's own lookup order. */
+export const WRANGLER_CONFIGS = ["wrangler.json", "wrangler.jsonc", "wrangler.toml"];
+/** Compatibility date for the generated config; Workers static assets need nothing newer. Checked 2026-10-23. */
+export const COMPATIBILITY_DATE = "2026-10-01";
+/**
+ * Reads name and assets settings from the project's wrangler config. Refuses setups where
+ * wrangler could pick a different file or Worker than the one shown: several config files,
+ * a CLOUDFLARE_ENV environment, or a .wrangler/deploy redirect.
+ */
+export function readWranglerConfig(root, env = process.env) {
+    const present = WRANGLER_CONFIGS.filter((f) => fs.existsSync(path.join(root, f)));
+    if (present.length > 1)
+        throw new VageError(`Found ${present.join(" and ")}. Keep one wrangler config so it's clear which Worker gets deployed.`);
+    if (fs.existsSync(path.join(root, ".wrangler", "deploy", "config.json"))) {
+        throw new VageError(".wrangler/deploy/config.json redirects wrangler to another config. Remove it, or deploy with wrangler directly.");
+    }
+    const file = present[0];
+    if (!file)
+        return undefined;
+    if (env.CLOUDFLARE_ENV)
+        throw new VageError(`CLOUDFLARE_ENV="${env.CLOUDFLARE_ENV}" makes wrangler deploy that environment's Worker. Unset it to deploy with vagejs.`);
+    const text = fs.readFileSync(path.join(root, file), "utf8").replace(/^\uFEFF/, "");
+    let name, dir, nf;
+    if (file.endsWith(".toml")) {
+        const lines = text.split(/\r?\n/).map((l) => l.replace(/\s+#.*$|^\s*#.*$/, ""));
+        const header = (l) => /^\s*\[/.test(l);
+        const firstHeader = lines.findIndex(header);
+        const top = firstHeader === -1 ? lines : lines.slice(0, firstHeader);
+        const assetsStart = lines.findIndex((l) => /^\s*\[assets\]\s*$/.test(l));
+        const assetsEnd = assetsStart === -1 ? -1 : lines.findIndex((l, i) => i > assetsStart && header(l));
+        const assets = assetsStart === -1 ? [] : lines.slice(assetsStart + 1, assetsEnd === -1 ? undefined : assetsEnd);
+        const value = (block, key) => {
+            for (const l of block) {
+                const m = new RegExp(`^\\s*${key}\\s*=\\s*(?:"([^"]*)"|'([^']*)')\\s*$`).exec(l);
+                if (m)
+                    return m[1] ?? m[2];
+            }
+            return undefined;
+        };
+        name = value(top, "name");
+        dir = value(assets, "directory");
+        nf = value(assets, "not_found_handling");
+        const inline = top.map((l) => /^\s*assets\s*=\s*\{(.*)\}\s*$/.exec(l)?.[1]).find(Boolean);
+        if (inline) {
+            dir ??= /directory\s*=\s*"([^"]*)"/.exec(inline)?.[1];
+            nf ??= /not_found_handling\s*=\s*"([^"]*)"/.exec(inline)?.[1];
+        }
+    }
+    else {
+        let data;
+        try {
+            data = JSON.parse(stripJsonComments(text));
+        }
+        catch (err) {
+            throw new VageError(`Could not read ${file}: ${err.message}`, path.join(root, file));
+        }
+        ({ name } = data);
+        dir = data.assets?.directory;
+        nf = data.assets?.not_found_handling;
+    }
+    return {
+        file,
+        name: typeof name === "string" ? name : undefined,
+        assetsDir: typeof dir === "string" ? path.resolve(root, dir) : undefined,
+        notFoundHandling: typeof nf === "string" ? nf : undefined,
+    };
+}
+/** JSONC to JSON: drops // and /* *\/ comments and trailing commas outside strings. */
+function stripJsonComments(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            const end = /"(?:[^"\\]|\\.)*"/y;
+            end.lastIndex = i;
+            const m = end.exec(text);
+            const str = m ? m[0] : text.slice(i);
+            out += str;
+            i += str.length - 1;
+        }
+        else if (c === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (c === "/" && text[i + 1] === "*") {
+            i = text.indexOf("*/", i + 2);
+            if (i === -1)
+                break;
+            i++;
+        }
+        else if (c === "," && /^\s*(\/\/[^\n]*\n\s*|\/\*[\s\S]*?\*\/\s*)*[}\]]/.test(text.slice(i + 1))) {
+            // trailing comma: drop it
+        }
+        else
+            out += c;
+    }
+    return out;
+}
+/**
+ * Decides which Worker gets deployed, and refuses setups where the plan and what
+ * wrangler would actually do differ (another Worker name, or a folder other than dist/).
+ */
+export function planWorkersDeploy(root, requested) {
+    const config = readWranglerConfig(root);
+    const warnings = [];
+    if (!config) {
+        if (!requested)
+            throw new VageError("No Worker name. Pass --project <name>, set deploy.cloudflareWorker, or add a wrangler.jsonc.");
+        return { worker: requested, warnings };
+    }
+    if (!config.name)
+        throw new VageError(`${config.file} has no "name". Add the Worker's name there.`, path.join(root, config.file));
+    if (requested && requested !== config.name) {
+        throw new VageError(`${config.file} deploys the Worker "${config.name}", but this deploy asks for "${requested}". ` +
+            `Make them match (deploy.cloudflareWorker / --project, or "name" in ${config.file}); vagejs won't deploy a different Worker than it shows.`);
+    }
+    const dist = path.join(root, "dist");
+    if (config.assetsDir !== dist) {
+        throw new VageError(`${config.file} must serve the built site: set assets.directory to "dist" (it is ${config.assetsDir ? `"${path.relative(root, config.assetsDir) || "."}"` : "not set"}).`, path.join(root, config.file));
+    }
+    if (config.notFoundHandling !== "404-page" && fs.existsSync(path.join(root, "src", "pages", "404.md"))) {
+        warnings.push(`${config.file}: add "not_found_handling": "404-page" under "assets", or unknown URLs get an empty 404 instead of your 404 page.`);
+    }
+    return { worker: config.name, config, warnings };
+}
+/**
+ * Deploys dist/ as a Cloudflare Worker with static assets (what Cloudflare now creates
+ * instead of Pages projects; `_headers` and `_redirects` still apply).
+ *
+ * - With a wrangler config in the project (needed for custom domains and routes), that
+ *   file is used as-is; `planWorkersDeploy` has already checked its name and folder.
+ *   Otherwise a temporary config pointing at dist/ is generated, so the project gains no files.
+ * - Existing Workers get `wrangler versions upload` + `versions deploy <id>@100%`: the new
+ *   version takes all traffic without re-applying routes or custom domains, so the site
+ *   stays up. Only Cloudflare's "Worker doesn't exist" error leads to a first `wrangler deploy`.
+ * - Success needs wrangler to succeed AND the live site to answer 200: `siteUrl` when set,
+ *   else the Worker's workers.dev URL (never a version preview URL).
+ */
+export async function deployCloudflareWorkers(root, options) {
+    const run = options.run ?? runCommand;
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const secrets = [(options.env ?? process.env).CLOUDFLARE_API_TOKEN];
+    const { worker } = options.plan;
+    let tempDir;
+    // Always name the config file, so wrangler can't pick another one (e.g. in a parent folder).
+    const configArgs = options.plan.config ? ["--config", path.join(root, options.plan.config.file)] : [];
+    if (!options.plan.config) {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "vage-wrangler-"));
+        const config = {
+            name: worker,
+            compatibility_date: COMPATIBILITY_DATE,
+            assets: { directory: path.join(root, "dist"), not_found_handling: "404-page" },
+        };
+        fs.writeFileSync(path.join(tempDir, "wrangler.json"), JSON.stringify(config, null, 2));
+        configArgs.push("--config", path.join(tempDir, "wrangler.json"));
+    }
+    try {
+        const wrangler = (...args) => run("npx", ["--yes", WRANGLER, ...args, ...configArgs], root);
+        const out = (r) => redact(`${r.stdout}\n${r.stderr}`, secrets);
+        const failReason = (code, text) => {
+            const auth = /auth|login|token|unauthori[sz]ed|10000/i.test(text) ? " Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, or run `npx wrangler login`." : "";
+            return `wrangler failed (exit ${code}).${auth}\n${tail(text)}`;
+        };
+        let mode = "version";
+        let versionId;
+        let output;
+        const tag = options.tag ?? `vage-${Date.now()}`;
+        const upload = await wrangler("versions", "upload", "--tag", tag);
+        output = out(upload);
+        if (upload.code !== 0) {
+            // Only a Worker that doesn't exist yet gets a full deploy (which also attaches routes).
+            if (!/\b10007\b|worker[^\n]*(?:does not exist|not found)/i.test(output))
+                return { status: "failure", worker, reason: failReason(upload.code, output) };
+            mode = "first-deploy";
+            const first = await wrangler("deploy");
+            output = out(first);
+            if (first.code !== 0)
+                return { status: "failure", worker, mode, reason: failReason(first.code, output) };
+        }
+        else {
+            versionId = /Version ID:\s*([0-9a-f-]{36})/i.exec(output)?.[1];
+            if (!versionId)
+                return { status: "failure", worker, reason: `wrangler uploaded but printed no version ID.\n${tail(output)}` };
+            const switched = await wrangler("versions", "deploy", `${versionId}@100%`, "--yes");
+            if (switched.code !== 0)
+                return { status: "failure", worker, versionId, reason: `Version ${versionId} uploaded but not deployed. ${failReason(switched.code, out(switched))}` };
+            output += `\n${out(switched)}`;
+        }
+        // Lines mentioning "preview" carry version preview URLs, which show the new version even when the live site doesn't.
+        const workersDev = output
+            .split("\n")
+            .filter((line) => !/preview/i.test(line))
+            .join("\n")
+            .match(/https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.workers\.dev/gi)
+            ?.at(-1);
+        const pageUrl = options.siteUrl ?? workersDev;
+        if (!pageUrl)
+            return { status: "unconfirmed", worker, mode, versionId, reason: "Deployed, but there is no URL to check: set `site` in vage.config.ts." };
+        for (let i = 0; i < 5; i++) {
+            const page = await doFetch(pageUrl, { signal: AbortSignal.timeout(20_000) }).catch(() => undefined);
+            if (page?.ok)
+                return { status: "success", worker, mode, versionId, pageUrl };
+            await sleep(3000);
+        }
+        return { status: "unconfirmed", worker, mode, versionId, pageUrl, reason: `Deployed, but ${pageUrl} did not respond with 200 yet. Check it in a minute.` };
+    }
+    finally {
+        if (tempDir)
+            fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+function tail(text) {
+    return text.trim().split("\n").slice(-8).join("\n");
+}

package/dist/deploy/headers.js

@@ -89,7 +89,7 @@ export function contentSecurityPolicy(pagesHtml, site) {
 }
 /** Cloudflare Pages / Netlify `_headers` for every path. */
 export function headersFile(pagesHtml, site) {
-    const lines = ["# Generated by VAGE JS (security in vage.config.ts)", "/*", "  X-Content-Type-Options: nosniff", "  Referrer-Policy: strict-origin-when-cross-origin", "  X-Frame-Options: SAMEORIGIN", "  Permissions-Policy: camera=(), microphone=(), geolocation=()"];
+    const lines = ["# Generated by vagejs (security in vage.config.ts)", "/*", "  X-Content-Type-Options: nosniff", "  Referrer-Policy: strict-origin-when-cross-origin", "  X-Frame-Options: SAMEORIGIN", "  Permissions-Policy: camera=(), microphone=(), geolocation=()"];
     if (site.security.csp !== "off") {
         const name = site.security.csp === "report-only" ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
         lines.push(`  ${name}: ${contentSecurityPolicy(pagesHtml, site)}`);

package/dist/deploy/publish.d.ts

@@ -9,7 +9,7 @@ export interface PublishPlan {
     /** True when `--remote` will be added as "origin". */
     addRemote: boolean;
     files: ChangedFile[];
-    /** Files VAGE JS will create (they do not exist yet). */
+    /** Files vagejs will create (they do not exist yet). */
     extraFiles: Record<string, string>;
     message: string;
     /** Local commits not yet on the remote (before this commit). */

package/dist/deploy/publish.js

@@ -51,7 +51,7 @@ export async function publish(root, options) {
         const out = push.stderr + push.stdout;
         if (/rejected|non-fast-forward|fetch first/i.test(out)) {
             throw new VageError(`Push rejected: origin/${plan.branch} has commits you don't have. Your commit is saved locally. ` +
-                `Run "git pull --rebase origin ${plan.branch}", resolve any conflicts, then publish again. VAGE JS never force-pushes.`);
+                `Run "git pull --rebase origin ${plan.branch}", resolve any conflicts, then publish again. vagejs never force-pushes.`);
         }
         throw new VageError(`Push failed (your commit is saved locally): ${out.trim()}`);
     }
@@ -84,7 +84,7 @@ export async function planPublish(root, options) {
         if (!branch)
             throw new VageError("HEAD is detached. Check out a branch before publishing.");
         if (options.branch && options.branch !== branch) {
-            throw new VageError(`You are on "${branch}", not "${options.branch}". Switch branches yourself first; VAGE JS won't do it for you.`);
+            throw new VageError(`You are on "${branch}", not "${options.branch}". Switch branches yourself first; vagejs won't do it for you.`);
         }
     }
     const origin = initRepo ? undefined : await gitRaw(cwd, ["remote", "get-url", "origin"]);
@@ -129,7 +129,7 @@ export async function planPublish(root, options) {
         addRemote: Boolean(options.remote && !existingRemote),
         files,
         extraFiles,
-        message: options.message ?? "Publish site with VAGE JS",
+        message: options.message ?? "Publish site with vagejs",
         unpushedCommits,
         warnings,
     };

package/dist/deploy/redirects.js

@@ -14,5 +14,5 @@ export function cloudflareRedirects(redirects) {
     });
     if (lines.length > maxStaticRules)
         throw new VageError(`_redirects would have ${lines.length} rules; Cloudflare Pages allows ${maxStaticRules}.`);
-    return `# Generated by VAGE JS from redirects in vage.config.ts\n${lines.join("\n")}\n`;
+    return `# Generated by vagejs from redirects in vage.config.ts\n${lines.join("\n")}\n`;
 }

package/dist/deploy/secrets.js

@@ -4,7 +4,7 @@ import path from "node:path";
 const SECRET_FILES = [
     [/(^|\/)\.env(\.(?!example$|sample$|template$)[^/]+)?$/, "environment file"],
     [/(^|\/)\.(dev\.vars|envrc)$/, "environment file"],
-    [/(^|\/)(google|api-keys)\.json$/, "VAGE JS credentials file"],
+    [/(^|\/)(google|api-keys)\.json$/, "vagejs credentials file"],
     [/\.(pem|key|p12|pfx|jks|keystore)$/i, "private key or certificate store"],
     [/(^|\/)id_(rsa|dsa|ecdsa|ed25519)$/, "SSH private key"],
     [/(^|\/)(credentials|client_secrets?|service[-_]?account[^/]*)\.json$/i, "credentials file"],

package/dist/dev/server.js

@@ -6,6 +6,7 @@ import { VageError } from "../core/errors.js";
 import { escapeHtml } from "../core/html.js";
 import { baseViteConfig, viteLoader } from "../core/loader.js";
 import { renderPage } from "../core/render.js";
+import { collectPages } from "../core/pages.js";
 import { renderSite } from "../core/site.js";
 import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "../core/routes.js";
 import { devAccessGuard } from "./guard.js";
@@ -74,7 +75,8 @@ export async function startDevServer(root, options = {}) {
                 return send(res, 404, await server.transformIndexHtml(urlPath, plainPage("404 — Not found", `No page for ${route}`)));
             }
             const file = entry?.file ?? notFound;
-            const page = await renderPage({ root, file, route: entry ? route : "/404/", site, load, notFound: !entry });
+            const pages = await collectPages(root, site, load, { skipInvalid: true });
+            const page = await renderPage({ root, file, route: entry ? route : "/404/", site, load, notFound: !entry, pages });
             send(res, entry ? 200 : 404, await server.transformIndexHtml(urlPath, page.html));
         }
         catch (err) {

package/dist/guidelines/rule-pack.json

@@ -604,7 +604,7 @@
             "version": "2026.10.0",
             "date": "2026-10-23",
             "summary": "Initial rule pack (unreleased; extended during Phase 8 and the security review with IndexNow, Clarity, Plausible, Cloudflare Pages and CSP provider rules). Facts checked against the cited sources on 2026-10-23 during implementation.",
-            "reviewedBy": "A G E Venkatesh",
+            "reviewedBy": "Venkatesh A G E",
             "contentHash": "8c7272511f733c01984ce1d962b39e2d521a88b31a5c958a95307a04b82bb3dd"
         }
     ]

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export { defineConfig, type SiteConfig, type UserConfig } from "./core/config.js";
-export { escapeHtml } from "./core/html.js";
+export { escapeHtml, html, raw, type SafeHtml } from "./core/html.js";
+/** Zod, for layout field schemas: `export const frontmatter = z.object({ ... })`. Same instance vagejs validates with. */
+export { z } from "zod";
 export type { Layout, LayoutProps } from "./core/render.js";
 export type { Frontmatter } from "./content/markdown.js";
+export { collection, type CollectionOptions, type PageSummary } from "./core/pages.js";
 export { build, type BuildResult } from "./core/build.js";
 export { startDevServer } from "./dev/server.js";
 export { startPreviewServer } from "./dev/preview.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 export { defineConfig } from "./core/config.js";
-export { escapeHtml } from "./core/html.js";
+export { escapeHtml, html, raw } from "./core/html.js";
+/** Zod, for layout field schemas: `export const frontmatter = z.object({ ... })`. Same instance vagejs validates with. */
+export { z } from "zod";
+export { collection } from "./core/pages.js";
 export { build } from "./core/build.js";
 export { startDevServer } from "./dev/server.js";
 export { startPreviewServer } from "./dev/preview.js";