vagejs 0.0.0-stage → 0.2.0

package/dist/core/pages.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseFrontmatter } from "../content/markdown.js";
+import { pageMeta } from "../seo/head.js";
+import { clonePlain } from "./clone.js";
+import { applyLayoutFields } from "./render.js";
+import { VageError } from "./errors.js";
+import { discoverRoutes } from "./routes.js";
+/**
+ * Every published page (drafts and 404.md excluded), sorted by route. Reads frontmatter
+ * and applies each page's layout schema, so list entries get the same defaults as the
+ * page itself. The result is frozen: layouts share it, so none may change it.
+ * `skipInvalid` (dev server, `vage check`) leaves out pages whose frontmatter is invalid;
+ * they report their own error instead of breaking every page that lists others.
+ */
+export async function collectPages(root, site, load, options = {}) {
+    const pagesDir = path.join(root, "src", "pages");
+    const out = [];
+    for (const entry of discoverRoutes(pagesDir)) {
+        let frontmatter;
+        try {
+            ({ frontmatter } = parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file));
+            if (frontmatter.draft)
+                continue;
+            await applyLayoutFields(root, frontmatter, load, entry.file);
+        }
+        catch (err) {
+            // Any failure (bad frontmatter, a layout that throws or doesn't compile) is that page's own error.
+            if (options.skipInvalid)
+                continue;
+            throw err;
+        }
+        out.push({
+            route: entry.route,
+            url: pageMeta(site, entry.route, frontmatter).canonical,
+            title: frontmatter.title,
+            description: frontmatter.description,
+            source: path.relative(root, entry.file),
+            frontmatter,
+        });
+    }
+    // A frozen deep copy: shared by every layout, and never the objects a page renders with.
+    return deepFreeze(clonePlain(out));
+}
+/** Freezes plain data only; URL/Date/class instances from schema transforms stay usable. */
+function deepFreeze(value) {
+    const plain = Array.isArray(value) || (value && typeof value === "object" && [Object.prototype, null].includes(Object.getPrototypeOf(value)));
+    if (plain && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreeze(v);
+    }
+    return value;
+}
+const SORTS = ["date", "title", "route"];
+/**
+ * Picks and orders pages for lists such as a blog index, a sidebar or "latest posts":
+ *   collection(pages, { under: "/blog/", sort: "date", limit: 5 })
+ */
+export function collection(pages, options = {}) {
+    if (!Array.isArray(pages))
+        throw new VageError("collection(): pass the layout's `pages` as the first argument.");
+    const { under, includeIndex = false, sort = "route", limit } = options;
+    if (under !== undefined && !/^\/(?!\/)/.test(under)) {
+        throw new VageError(`collection(): "under" must be a site path starting with "/", like "/blog/" (got ${JSON.stringify(under)}).`);
+    }
+    if (typeof sort !== "function" && !SORTS.includes(sort)) {
+        throw new VageError(`collection(): "sort" must be "date", "title", "route" or a compare function (got ${JSON.stringify(sort)}).`);
+    }
+    if (typeof includeIndex !== "boolean")
+        throw new VageError(`collection(): "includeIndex" must be true or false (got ${JSON.stringify(includeIndex)}).`);
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 0)) {
+        throw new VageError(`collection(): "limit" must be a whole number of 0 or more (got ${JSON.stringify(limit)}).`);
+    }
+    const prefix = under ? (under.endsWith("/") ? under : `${under}/`) : undefined;
+    const picked = pages.filter((p) => !prefix || (p.route.startsWith(prefix) && (includeIndex || p.route !== prefix)));
+    const byTitle = (a, b) => a.title.localeCompare(b.title);
+    const compare = typeof sort === "function"
+        ? sort
+        : sort === "title"
+            ? byTitle
+            : sort === "date"
+                ? (a, b) => {
+                    const da = a.frontmatter.datePublished ?? "";
+                    const db = b.frontmatter.datePublished ?? "";
+                    if (da !== db)
+                        return da && db ? db.localeCompare(da) : da ? -1 : 1;
+                    return byTitle(a, b);
+                }
+                : (a, b) => a.route.localeCompare(b.route);
+    const sorted = [...picked].sort(compare);
+    return limit === undefined ? sorted : sorted.slice(0, limit);
+}

package/dist/core/project-config.d.ts

@@ -0,0 +1,3 @@
+import { type SiteConfig } from "./config.js";
+/** Loads vage.config.* outside a build (defaults when there is none). */
+export declare function loadProjectConfig(root: string): Promise<SiteConfig>;

package/dist/core/project-config.js

@@ -0,0 +1,14 @@
+import { findConfigFile, loadConfig, parseConfig } from "./config.js";
+import { createBuildLoader } from "./loader.js";
+/** Loads vage.config.* outside a build (defaults when there is none). */
+export async function loadProjectConfig(root) {
+    if (!findConfigFile(root))
+        return parseConfig({});
+    const loader = await createBuildLoader(root);
+    try {
+        return await loadConfig(root, loader.load);
+    }
+    finally {
+        await loader.close();
+    }
+}

package/dist/core/render.d.ts

@@ -0,0 +1,53 @@
+import { type Frontmatter } from "../content/markdown.js";
+import type { ModuleLoader, SiteConfig } from "./config.js";
+import { type SafeHtml } from "./html.js";
+import { type PageMeta } from "../seo/head.js";
+import type { PageSummary } from "./pages.js";
+export interface LayoutProps {
+    /** Rendered page body HTML. Insert as-is; do not escape. */
+    content: string;
+    page: {
+        route: string;
+        title: string;
+        description?: string;
+        /** Absolute canonical URL, when `site` is set and the page is indexable. */
+        url?: string;
+        frontmatter: Frontmatter;
+    };
+    site: SiteConfig;
+    /**
+     * Every published page (drafts excluded), sorted by route. Use `collection()` to
+     * pick a section and order it, e.g. a blog index or a sidebar.
+     */
+    pages: readonly PageSummary[];
+}
+/** Returns the page's HTML: a string, or `html\`...\`` (escapes values automatically). */
+export type Layout = (props: LayoutProps) => string | SafeHtml | Promise<string | SafeHtml>;
+export interface RenderedPage {
+    html: string;
+    frontmatter: Frontmatter;
+    /** Markdown body without frontmatter. */
+    body: string;
+    meta: PageMeta;
+}
+export declare function renderPage(options: {
+    root: string;
+    file: string;
+    route: string;
+    site: SiteConfig;
+    load: ModuleLoader;
+    /** Renders the 404 page: always noindex, no canonical. */
+    notFound?: boolean;
+    /** Add configured analytics tags. Off in the dev server so development traffic is never measured. */
+    analytics?: boolean;
+    /** Published pages for `props.pages`. */
+    pages?: readonly PageSummary[];
+}): Promise<RenderedPage>;
+/**
+ * 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 declare function applyLayoutFields(root: string, frontmatter: Frontmatter, load: ModuleLoader, file: string): Promise<Layout>;
+/** Used when a project has no src/layouts/default.ts. */
+export declare const defaultLayout: Layout;

package/dist/core/render.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { frontmatterSchema, parseMarkdown } from "../content/markdown.js";
+import { enhanceTrustedHtml, sanitizeHtml } from "../content/sanitize.js";
+import { VageError } from "./errors.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 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 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 or html\`...\`.`, file);
+    }
+    let out = injectHead(html, headTags(site, meta), file);
+    const tags = options.analytics ? analyticsTags(site) : undefined;
+    if (tags)
+        out = injectAnalytics(out, tags, file);
+    return { html: out, frontmatter, body, meta };
+}
+const LAYOUT_EXTENSIONS = [".ts", ".js", ".mjs"];
+async function resolveLayout(root, name, load, pageFile) {
+    const base = path.join(root, "src", "layouts", name ?? "default");
+    const file = LAYOUT_EXTENSIONS.map((ext) => base + ext).find((f) => fs.existsSync(f));
+    if (!file) {
+        if (!name)
+            return { layout: defaultLayout };
+        throw new VageError(`Layout "${name}" not found. Expected src/layouts/${name}.ts`, pageFile);
+    }
+    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;
+    return `<!doctype html>
+<html lang="${escapeHtml(site.lang)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+  </head>
+  <body>
+    <main>
+${content}
+    </main>
+  </body>
+</html>
+`;
+};

package/dist/core/routes.d.ts

@@ -0,0 +1,24 @@
+export interface RouteEntry {
+    /** URL path, always with a trailing slash, e.g. "/blog/first-post/". */
+    route: string;
+    /** Absolute path of the source file. */
+    file: string;
+    /** Output path relative to the build directory, e.g. "blog/first-post/index.html". */
+    outFile: string;
+}
+export declare const NOT_FOUND_PAGE = "404.md";
+/**
+ * Maps src/pages/**\/*.md to routes:
+ *   index.md       -> /
+ *   about.md       -> /about/
+ *   blog/index.md  -> /blog/
+ *   blog/post.md   -> /blog/post/
+ * Files and directories starting with "_" are ignored. The top-level 404.md is
+ * not a route; use findNotFoundPage() for it.
+ */
+export declare function discoverRoutes(pagesDir: string): RouteEntry[];
+/** Route for a page path relative to src/pages (works for deleted files too). */
+export declare function routeForPage(rel: string): string | undefined;
+export declare function findNotFoundPage(pagesDir: string): string | undefined;
+/** Normalizes a request path ("/about", "/about/index.html") to a route key ("/about/"). */
+export declare function normalizeRequestPath(urlPath: string): string;

package/dist/core/routes.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+import { VageError } from "./errors.js";
+export const NOT_FOUND_PAGE = "404.md";
+/**
+ * Maps src/pages/**\/*.md to routes:
+ *   index.md       -> /
+ *   about.md       -> /about/
+ *   blog/index.md  -> /blog/
+ *   blog/post.md   -> /blog/post/
+ * Files and directories starting with "_" are ignored. The top-level 404.md is
+ * not a route; use findNotFoundPage() for it.
+ */
+export function discoverRoutes(pagesDir) {
+    if (!fs.existsSync(pagesDir))
+        return [];
+    const routes = new Map();
+    for (const rel of walk(pagesDir)) {
+        if (rel === NOT_FOUND_PAGE)
+            continue;
+        const segments = routeSegments(rel);
+        const route = segments.length ? `/${segments.join("/")}/` : "/";
+        const file = path.join(pagesDir, rel);
+        const existing = routes.get(route);
+        if (existing) {
+            throw new VageError(`Two pages map to the route "${route}": ${path.relative(pagesDir, existing.file)} and ${rel}. Remove or rename one of them.`, file);
+        }
+        routes.set(route, { route, file, outFile: path.posix.join(...segments, "index.html") });
+    }
+    return [...routes.values()].sort((a, b) => a.route.localeCompare(b.route));
+}
+function routeSegments(rel) {
+    const segments = rel.slice(0, -".md".length).split("/");
+    if (segments.at(-1) === "index")
+        segments.pop();
+    return segments;
+}
+/** Route for a page path relative to src/pages (works for deleted files too). */
+export function routeForPage(rel) {
+    if (!rel.endsWith(".md") || rel === NOT_FOUND_PAGE || rel.split("/").some((s) => s.startsWith("_") || s.startsWith(".")))
+        return undefined;
+    const segments = routeSegments(rel);
+    return segments.length ? `/${segments.join("/")}/` : "/";
+}
+export function findNotFoundPage(pagesDir) {
+    const file = path.join(pagesDir, NOT_FOUND_PAGE);
+    return fs.existsSync(file) ? file : undefined;
+}
+/** Normalizes a request path ("/about", "/about/index.html") to a route key ("/about/"). */
+export function normalizeRequestPath(urlPath) {
+    let p = decodeURIComponent(urlPath.split(/[?#]/)[0] ?? "/");
+    if (p.endsWith("/index.html"))
+        p = p.slice(0, -"index.html".length);
+    else if (p.endsWith(".html"))
+        p = p.slice(0, -".html".length);
+    return p.endsWith("/") ? p : `${p}/`;
+}
+function walk(dir, prefix = "") {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name.startsWith("_") || entry.name.startsWith("."))
+            continue;
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...walk(path.join(dir, entry.name), rel));
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            out.push(rel);
+    }
+    return out;
+}

package/dist/core/site.d.ts

@@ -0,0 +1,42 @@
+import { type ModuleLoader, type SiteConfig } from "./config.js";
+import { type RenderedPage } from "./render.js";
+export interface SitePage extends RenderedPage {
+    route: string;
+    /** Source path relative to the project root. */
+    source: string;
+    outFile: string;
+}
+export interface SiteRedirect {
+    from: string;
+    to: string;
+    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[];
+    /** Routes of draft pages; links to them are broken in production. */
+    draftRoutes: string[];
+    notFound?: SitePage;
+    redirects: SiteRedirect[];
+    /** Generated discovery files: output path -> content. */
+    files: Map<string, string>;
+    warnings: string[];
+}
+/** Renders every page and derives discovery files from the same data, without writing anything. */
+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

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { llmsFullTxt, llmsTxt } from "../discovery/llms.js";
+import { robotsTxt } from "../discovery/robots.js";
+import { SITEMAP_URL_LIMIT, sitemapXml } from "../discovery/sitemap.js";
+import { headersFile } from "../deploy/headers.js";
+import { cloudflareRedirects } from "../deploy/redirects.js";
+import { findSecrets } from "../deploy/secrets.js";
+import { rulePack } from "../guidelines/pack.js";
+import { absoluteUrl } from "../seo/urls.js";
+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, 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 vagejs project?`);
+    }
+    const site = await loadConfig(root, load);
+    const pinned = site.guidelines.rulePack;
+    if (pinned && pinned !== rulePack.version) {
+        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, 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 source = path.relative(root, entry.file);
+        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) {
+        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)));
+    addDiscoveryFiles(root, model);
+    return model;
+}
+/** Pages that should appear in sitemap.xml and llms.txt: indexable and canonical to themselves. */
+export function listedPages(model) {
+    return model.pages.filter((p) => !p.meta.noindex && p.meta.canonical === absoluteUrl(model.site.site, p.route));
+}
+function addDiscoveryFiles(root, model) {
+    const { site, files, warnings } = model;
+    const listed = listedPages(model);
+    const generate = (name, content) => {
+        if (fs.existsSync(path.join(root, "public", name))) {
+            throw new VageError(`public/${name} conflicts with the generated ${name}. Delete it, or turn generation off in vage.config.ts (seo).`);
+        }
+        files.set(name, content());
+    };
+    if (site.site && /^https?:\/\/(www\.)?example\.(com|org|net)$/.test(site.site)) {
+        warnings.push(`"site" is still the placeholder ${site.site}; canonical URLs and sitemap.xml will point there. Set your real origin.`);
+    }
+    if (!site.site) {
+        warnings.push('"site" is not set in vage.config.ts: canonical URLs, og:url, sitemap.xml and absolute image URLs are skipped.');
+    }
+    if (site.seo.robots) {
+        const robots = site.seo.robots;
+        generate("robots.txt", () => robotsTxt(site, robots));
+    }
+    if (site.seo.sitemap && site.site) {
+        if (listed.length > SITEMAP_URL_LIMIT) {
+            throw new VageError(`sitemap.xml would list ${listed.length} URLs; sitemap indexes (over ${SITEMAP_URL_LIMIT}) are not supported yet.`);
+        }
+        generate("sitemap.xml", () => sitemapXml(listed.map((p) => ({ url: p.meta.canonical, lastmod: p.frontmatter.dateModified ?? p.frontmatter.datePublished }))));
+    }
+    const indexNow = site.integrations.indexNow;
+    if (indexNow)
+        generate(`${indexNow.key}.txt`, () => `${indexNow.key}\n`);
+    // 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 (cloudflare && site.security.headers) {
+        const html = [...model.pages, ...(model.notFound ? [model.notFound] : []), ...model.redirects].map((p) => p.html);
+        generate("_headers", () => headersFile(html, site));
+    }
+    if (site.seo.llmsTxt) {
+        if (!site.title) {
+            warnings.push('"title" is not set in vage.config.ts: llms.txt needs a site title and was skipped.');
+        }
+        else {
+            const pages = listed.map((p) => ({
+                title: p.frontmatter.title,
+                url: absoluteUrl(site.site, p.route) ?? p.route,
+                description: p.frontmatter.description,
+                body: p.body,
+            }));
+            generate("llms.txt", () => llmsTxt(site.title, site.description, pages));
+            if (site.seo.llmsTxt.full)
+                generate("llms-full.txt", () => llmsFullTxt(site.title, site.description, pages));
+        }
+    }
+}
+/**
+ * Everything in public/ is published. Refuses symlinks (they can point at files
+ * outside the project) and files that look like secrets. Google browser API keys
+ * are meant to be public when referrer-restricted, so they only warn.
+ */
+function checkPublicDir(root, warnings) {
+    const publicDir = path.join(root, "public");
+    if (!fs.existsSync(publicDir))
+        return;
+    const files = [];
+    const walk = (dir, prefix) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const rel = `${prefix}${e.name}`;
+            if (e.isSymbolicLink()) {
+                throw new VageError(`public/${rel} is a symlink. Copy the real file into public/ instead; links can expose files outside the project.`);
+            }
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), `${rel}/`);
+            else
+                files.push(rel);
+        }
+    };
+    walk(publicDir, "");
+    const hits = findSecrets(publicDir, files);
+    const blocking = hits.filter((h) => h.reason !== "looks like a Google API key");
+    for (const h of hits.filter((h) => !blocking.includes(h))) {
+        warnings.push(`public/${h.path} contains a Google API key and will be public. Fine for a referrer-restricted browser key; otherwise remove it.`);
+    }
+    if (blocking.length) {
+        throw new VageError(`Refusing to publish possible secrets from public/:\n${blocking.map((h) => `  public/${h.path}: ${h.reason}`).join("\n")}\nEverything in public/ is served to the world. Move these files out (and rotate exposed credentials).`);
+    }
+}
+function buildRedirects(site, routes) {
+    return Object.entries(site.redirects).map(([fromPath, to]) => {
+        const from = normalizeRequestPath(fromPath);
+        if (routes.has(from)) {
+            throw new VageError(`Redirect source "${fromPath}" is also a page route. Remove the page or the redirect.`);
+        }
+        const target = absoluteUrl(site.site, to) ?? to;
+        const html = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Redirecting…</title>
+    <meta name="robots" content="noindex" />
+    <link rel="canonical" href="${escapeHtml(target)}" />
+    <meta http-equiv="refresh" content="0; url=${escapeHtml(to)}" />
+  </head>
+  <body>
+    <p>This page has moved to <a href="${escapeHtml(to)}">${escapeHtml(to)}</a>.</p>
+  </body>
+</html>
+`;
+        return { from, to, outFile: path.posix.join(from.slice(1), "index.html"), html };
+    });
+}

package/dist/core/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Validators for values that reach other programs (git, wrangler, npm) as
+ * arguments. A leading "-" would be read as an option, so it is always refused.
+ */
+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. */
+export declare function assertVageSpec(value: string): string;

package/dist/core/validate.js

@@ -0,0 +1,36 @@
+import { VageError } from "./errors.js";
+/**
+ * Validators for values that reach other programs (git, wrangler, npm) as
+ * arguments. A leading "-" would be read as an option, so it is always refused.
+ */
+export function assertBranchName(value, flag = "--branch") {
+    if (!/^(?!-)(?!.*\.\.)(?!.*\/\/)[A-Za-z0-9._/-]{1,200}$/.test(value) || value.endsWith("/") || value.endsWith(".lock")) {
+        throw new VageError(`Invalid ${flag} "${value}". Use letters, digits, ".", "_", "-" and "/" (not starting with "-").`);
+    }
+    return value;
+}
+export function assertCloudflareProject(value) {
+    if (!/^[a-z0-9][a-z0-9-]{0,57}$/.test(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)) {
+        throw new VageError(`Invalid --remote "${value}". Use an https://, ssh:// or git@host:owner/repo.git URL.`);
+    }
+    return value;
+}
+/** npm dependency spec for new projects: a version/range, "latest", or a local file: tarball. */
+export function assertVageSpec(value) {
+    if (!/^(latest|[~^]?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?|file:[^\s]+)$/.test(value)) {
+        throw new VageError(`Invalid --vage-spec "${value}". Use a version like ^0.1.0, "latest", or file:<path-to-tarball>.`);
+    }
+    return value;
+}

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

@@ -0,0 +1,20 @@
+import type { DeployStatus, Runner } from "./github-pages.js";
+/** Pinned so deploys are reproducible; checked 2026-10-23. */
+export declare const WRANGLER = "wrangler@4.152.0";
+/**
+ * Uploads dist/ with `wrangler pages deploy`. Auth comes from the environment
+ * (CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID) or a prior `wrangler login`.
+ * Reports success only when wrangler succeeds AND the deployment URL serves the site.
+ */
+export declare function deployCloudflarePages(root: string, options: {
+    project: string;
+    branch: string;
+    commit?: string;
+    run?: Runner;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    env?: Record<string, string | undefined>;
+}): Promise<DeployStatus & {
+    deploymentUrl?: string;
+    branch: string;
+}>;