vagejs 0.1.0 → 0.3.0

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/github-pages.js

@@ -25,6 +25,8 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # full history, so seo.lastmod: "git" can date pages
       - uses: actions/setup-node@v7
         with:
           node-version: 22

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/guard.d.ts

@@ -7,3 +7,5 @@ import type { Plugin } from "vite";
  */
 export declare function devAccessGuard(root: string, allowedFiles: Set<string>): Plugin;
 export declare function allowed(url: string, publicDir: string, allowedFiles: Set<string>): boolean;
+/** A regular file whose real path (every folder resolved) is inside public/: no symlinked files or folders. */
+export declare function insidePublic(file: string, publicDir: string): boolean;

package/dist/dev/guard.js

@@ -45,11 +45,40 @@ export function allowed(url, publicDir, allowedFiles) {
         return true; // rendered pages (our middleware decides 200/404)
     if (allowedFiles.has(pathname))
         return true;
+    // Optimized images (images.optimize), served from the cache by the dev server.
+    if (/^\/_vage\/img\/[\w-]+\.webp$/.test(pathname))
+        return true;
+    // Generated files (seo.feeds, seo.markdownCopies) never exist on disk in dev. If a real file
+    // sits at that path, it's a project source (e.g. /src/pages/about.md): Vite would serve it, so refuse.
+    if (/^\/(?:[\w-]+\/)*(?:feed\.xml|[\w-]+\.md)$/.test(pathname)) {
+        if (fs.existsSync(path.join(path.dirname(publicDir), pathname)))
+            return false;
+        // A public/ file with that name is served by Vite, so apply the same rules as below.
+        const candidate = path.join(publicDir, pathname);
+        if (!fs.existsSync(candidate) && !isSymlink(candidate))
+            return true; // not in public/: generated by vagejs
+        return insidePublic(candidate, publicDir);
+    }
     const file = path.resolve(publicDir, `.${pathname}`);
     if (!file.startsWith(publicDir + path.sep))
         return false;
+    return insidePublic(file, publicDir);
+}
+function isSymlink(file) {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** A regular file whose real path (every folder resolved) is inside public/: no symlinked files or folders. */
+export function insidePublic(file, publicDir) {
     try {
-        return fs.lstatSync(file).isFile(); // lstat: symlinks are not served
+        if (!fs.lstatSync(file).isFile())
+            return false;
+        const realPublic = fs.realpathSync(publicDir);
+        return fs.realpathSync(file).startsWith(realPublic + path.sep);
     }
     catch {
         return false;

package/dist/dev/server.js

@@ -6,6 +6,8 @@ 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 { cacheDir } from "../content/optimize.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";
@@ -41,12 +43,27 @@ export async function startDevServer(root, options = {}) {
         const urlPath = req.url ?? "/";
         const pathname = urlPath.split(/[?#]/)[0];
         try {
-            if (DISCOVERY_FILES[pathname]) {
+            const optimized = /^\/_vage\/img\/([\w-]+\.webp)$/.exec(pathname);
+            if (optimized) {
+                const file = path.join(cacheDir(root), optimized[1]);
+                if (!fs.existsSync(file))
+                    return send(res, 404, plainPage("404 — Not found", `No optimized image at ${pathname}`));
+                res.setHeader("Content-Type", "image/webp");
+                return res.end(fs.readFileSync(file));
+            }
+            const isFeed = /^\/(?:[\w.-]+\/)*feed\.xml$/.test(pathname) && !pathname.includes("..");
+            const isCopy = /^\/(?:[\w-]+\/)*[\w-]+\.md$/.test(pathname);
+            if (DISCOVERY_FILES[pathname] || isFeed || isCopy) {
                 // Built from the whole site (drafts excluded), exactly as `vage build` would write it.
                 const content = (await renderSite(root, load)).files.get(pathname.slice(1));
-                if (content === undefined)
+                if (content === undefined) {
+                    // Feeds and Markdown copies exist only as generated files; never fall through to Vite,
+                    // which would serve project sources (e.g. /src/pages/about.md).
+                    if (isFeed || isCopy)
+                        return send(res, 404, plainPage("404 — Not found", `No generated file at ${pathname}`));
                     return next();
-                res.setHeader("Content-Type", DISCOVERY_FILES[pathname]);
+                }
+                res.setHeader("Content-Type", DISCOVERY_FILES[pathname] ?? (isCopy ? "text/markdown; charset=utf-8" : "application/rss+xml; charset=utf-8"));
                 return res.end(content);
             }
             // Leave asset requests (any extension other than .html) to Vite.
@@ -74,7 +91,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/discovery/feed.d.ts

@@ -0,0 +1,21 @@
+import type { SiteConfig } from "../core/config.js";
+import type { SitePage } from "../core/site.js";
+export interface FeedConfig {
+    under: string;
+    title?: string;
+    description?: string;
+    limit: number;
+}
+/** The feed's title: configured, else the site title. Used for the channel and the page links. */
+export declare function feedTitle(site: SiteConfig, feed: {
+    title?: string;
+    under: string;
+}): string;
+/** Where a section's feed is published: "/blog/" -> "blog/feed.xml". */
+export declare function feedPath(under: string): string;
+/**
+ * RSS 2.0 for one section: its listed pages, newest datePublished first (undated last).
+ * Item descriptions are the page descriptions; dates come only from frontmatter, so the
+ * feed is the same on every build.
+ */
+export declare function rssFeed(site: SiteConfig, feed: FeedConfig, pages: SitePage[], origin: string): string;

package/dist/discovery/feed.js

@@ -0,0 +1,68 @@
+import { instant } from "../core/dates.js";
+const XML_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
+const xml = (s) => s.replace(/[&<>"']/g, (c) => XML_ESCAPES[c]);
+/** The feed's title: configured, else the site title. Used for the channel and the page links. */
+export function feedTitle(site, feed) {
+    return feed.title ?? site.title ?? feed.under;
+}
+/** Where a section's feed is published: "/blog/" -> "blog/feed.xml". */
+export function feedPath(under) {
+    return `${under.replace(/^\/+/, "")}feed.xml`;
+}
+/** RFC 822 date, as RSS requires: "Thu, 23 Oct 2026 00:00:00 GMT". */
+function rfc822(iso) {
+    return new Date(iso.length === 10 ? `${iso}T00:00:00Z` : iso).toUTCString();
+}
+/**
+ * RSS 2.0 for one section: its listed pages, newest datePublished first (undated last).
+ * Item descriptions are the page descriptions; dates come only from frontmatter, so the
+ * feed is the same on every build.
+ */
+export function rssFeed(site, feed, pages, origin) {
+    const items = pages
+        .filter((p) => p.route.startsWith(feed.under) && p.route !== feed.under)
+        .sort((a, b) => {
+        // Compare as instants: "2026-10-23T23:00:00-05:00" is after "2026-10-24".
+        const ta = instant(a.frontmatter.datePublished);
+        const tb = instant(b.frontmatter.datePublished);
+        if (ta === tb || (Number.isNaN(ta) && Number.isNaN(tb)))
+            return a.frontmatter.title.localeCompare(b.frontmatter.title);
+        return Number.isNaN(ta) ? 1 : Number.isNaN(tb) ? -1 : tb - ta;
+    })
+        .slice(0, feed.limit);
+    const section = pages.find((p) => p.route === feed.under);
+    // Same default as the <link rel="alternate"> title on the pages.
+    const title = feedTitle(site, feed);
+    const description = feed.description ?? section?.frontmatter.description ?? site.description ?? title;
+    const self = `${origin}/${feedPath(feed.under)}`;
+    const newest = items.find((p) => p.frontmatter.datePublished)?.frontmatter.datePublished; // items are sorted newest first
+    const body = items
+        .map((p) => {
+        const link = p.meta.canonical ?? `${origin}${p.route}`;
+        const date = p.frontmatter.datePublished;
+        return [
+            "    <item>",
+            `      <title>${xml(p.frontmatter.title)}</title>`,
+            `      <link>${xml(link)}</link>`,
+            `      <guid isPermaLink="true">${xml(link)}</guid>`,
+            p.frontmatter.description ? `      <description>${xml(p.frontmatter.description)}</description>` : "",
+            date ? `      <pubDate>${rfc822(date)}</pubDate>` : "",
+            "    </item>",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    })
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${xml(title)}</title>
+    <link>${xml(`${origin}${feed.under}`)}</link>
+    <description>${xml(description)}</description>
+    <language>${xml(site.lang)}</language>
+    <atom:link href="${xml(self)}" rel="self" type="application/rss+xml" />${newest ? `\n    <lastBuildDate>${rfc822(newest)}</lastBuildDate>` : ""}
+${body}
+  </channel>
+</rss>
+`;
+}

package/dist/discovery/git-dates.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Last commit date (ISO) of every file under src/pages, from one `git log` call.
+ * Returns undefined with a reason when dates would be wrong or unavailable: not a git
+ * repository, or a shallow clone (CI's default), where every file seems to change in
+ * the latest commit.
+ */
+export declare function gitPageDates(root: string): {
+    dates?: Map<string, string>;
+    problem?: string;
+};

package/dist/discovery/git-dates.js

@@ -0,0 +1,57 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Last commit date (ISO) of every file under src/pages, from one `git log` call.
+ * Returns undefined with a reason when dates would be wrong or unavailable: not a git
+ * repository, or a shallow clone (CI's default), where every file seems to change in
+ * the latest commit.
+ */
+export function gitPageDates(root) {
+    // core.quotepath=off: print non-ASCII file names as-is (default would quote "caf\303\251.md").
+    const git = (args) => execFileSync("git", ["-c", "core.quotepath=off", ...args], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+    try {
+        git(["--version"]);
+    }
+    catch {
+        return { problem: "git isn't available" };
+    }
+    try {
+        if (git(["rev-parse", "--is-inside-work-tree"]).trim() !== "true")
+            return { problem: "the project isn't a git repository" };
+    }
+    catch {
+        return { problem: "the project isn't a git repository" };
+    }
+    try {
+        if (git(["rev-parse", "--is-shallow-repository"]).trim() === "true") {
+            return { problem: "this is a shallow git clone, so every page would get the latest commit's date (in GitHub Actions, use actions/checkout with fetch-depth: 0)" };
+        }
+        const top = git(["rev-parse", "--show-toplevel"]).trim();
+        // git prints real paths; compare against the project's real path (e.g. /var -> /private/var on macOS).
+        const real = fs.realpathSync(root);
+        // -z: NUL-separated, so file names with quotes, spaces or newlines come through exactly.
+        const out = git(["log", "-z", "--format=@@%cI", "--name-only", "--no-renames", "--", path.join(root, "src", "pages")]);
+        const dates = new Map();
+        let current = "";
+        for (const raw of out.split("\0")) {
+            const field = raw.replace(/^\n+/, "");
+            if (!field)
+                continue;
+            const header = /^@@(\S+)\n?([\s\S]*)$/.exec(field);
+            const name = header ? header[2] : field;
+            if (header)
+                current = header[1];
+            if (name && current) {
+                const rel = path.relative(real, path.join(top, name));
+                if (!dates.has(rel))
+                    dates.set(rel, current); // newest first: keep the first date seen
+            }
+        }
+        return { dates };
+    }
+    catch (err) {
+        const stderr = String(err.stderr ?? "").trim().split("\n")[0];
+        return { problem: `reading the git history failed (${stderr || err.message.split("\n")[0]})` };
+    }
+}

package/dist/discovery/markdown-copy.d.ts

@@ -0,0 +1,13 @@
+/** "/" -> "index.md", "/docs/cli/" -> "docs/cli.md". */
+export declare function markdownCopyPath(route: string): string;
+/**
+ * The page as Markdown, converted from its rendered, sanitized HTML: the copy contains
+ * exactly what the page shows (no comments, no raw HTML the sanitizer removed, the same
+ * links the link lock checked), with links and images made absolute.
+ */
+export declare function htmlToMarkdown(html: string, options: {
+    route: string;
+    origin?: string;
+}): Promise<string>;
+/** The copy: the page's own H1 (or the title), the summary, then the content. */
+export declare function markdownCopy(title: string, description: string | undefined, markdown: string): string;