vagejs 0.0.0-stage → 0.1.0

package/dist/core/errors.js

@@ -0,0 +1,9 @@
+/** An expected, user-facing error. The CLI prints its message without a stack trace. */
+export class VageError extends Error {
+    file;
+    constructor(message, file) {
+        super(file ? `${message}\n  at ${file}` : message);
+        this.file = file;
+        this.name = "VageError";
+    }
+}

package/dist/core/html.d.ts

@@ -0,0 +1,2 @@
+/** Escapes text for safe use in HTML content and attribute values. */
+export declare function escapeHtml(value: unknown): string;

package/dist/core/html.js

@@ -0,0 +1,11 @@
+const ESCAPES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** Escapes text for safe use in HTML content and attribute values. */
+export function escapeHtml(value) {
+    return String(value ?? "").replace(/[&<>"']/g, (c) => ESCAPES[c]);
+}

package/dist/core/loader.d.ts

@@ -0,0 +1,10 @@
+import { type InlineConfig, type ViteDevServer } from "vite";
+import type { ModuleLoader } from "./config.js";
+/** Shared Vite options. configFile: false keeps a project's own vite.config out of the picture. */
+export declare function baseViteConfig(root: string): InlineConfig;
+export declare function viteLoader(server: ViteDevServer): ModuleLoader;
+/** A headless Vite server used only to import TypeScript config and layout files during a build. */
+export declare function createBuildLoader(root: string): Promise<{
+    load: ModuleLoader;
+    close: () => Promise<void>;
+}>;

package/dist/core/loader.js

@@ -0,0 +1,16 @@
+import { createServer } from "vite";
+/** Shared Vite options. configFile: false keeps a project's own vite.config out of the picture. */
+export function baseViteConfig(root) {
+    return { root, configFile: false, logLevel: "warn", appType: "custom" };
+}
+export function viteLoader(server) {
+    return (file) => server.ssrLoadModule(file);
+}
+/** A headless Vite server used only to import TypeScript config and layout files during a build. */
+export async function createBuildLoader(root) {
+    const server = await createServer({
+        ...baseViteConfig(root),
+        server: { middlewareMode: true, hmr: false, ws: false, watch: null },
+    });
+    return { load: viteLoader(server), close: () => server.close() };
+}

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,37 @@
+import { type Frontmatter } from "../content/markdown.js";
+import type { ModuleLoader, SiteConfig } from "./config.js";
+import { type PageMeta } from "../seo/head.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;
+}
+export type Layout = (props: LayoutProps) => string | Promise<string>;
+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;
+}): Promise<RenderedPage>;
+/** Used when a project has no src/layouts/default.ts. */
+export declare const defaultLayout: Layout;

package/dist/core/render.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseMarkdown } from "../content/markdown.js";
+import { sanitizeHtml } from "../content/sanitize.js";
+import { VageError } from "./errors.js";
+import { escapeHtml } 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 meta = pageMeta(site, route, frontmatter, options.notFound);
+    const layout = await resolveLayout(root, frontmatter.layout, load, file);
+    const html = await layout({
+        content,
+        page: { route, title: frontmatter.title, description: frontmatter.description, url: meta.canonical, frontmatter },
+        site,
+    });
+    if (typeof html !== "string") {
+        throw new VageError(`Layout "${frontmatter.layout ?? "default"}" must return an HTML string.`, 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 defaultLayout;
+        throw new VageError(`Layout "${name}" not found. Expected src/layouts/${name}.ts`, pageFile);
+    }
+    const layout = (await load(file)).default;
+    if (typeof layout !== "function") {
+        throw new VageError("Layout files must default-export a function that returns an HTML string.", file);
+    }
+    return layout;
+}
+/** 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,31 @@
+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 SiteModel {
+    site: SiteConfig;
+    /** 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): 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,159 @@
+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 { 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) {
+    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?`);
+    }
+    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, pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    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
+            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" };
+    }
+    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`);
+    if (site.deploy.target === "cloudflare-pages" && model.redirects.length)
+        generate("_redirects", () => cloudflareRedirects(model.redirects));
+    if (site.deploy.target === "cloudflare-pages" && 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,10 @@
+/**
+ * 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;
+/** 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,30 @@
+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;
+}
+/** 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;
+}>;

package/dist/deploy/cloudflare-pages.js

@@ -0,0 +1,40 @@
+import { redact } from "../integrations/http.js";
+import { runCommand } from "./github-pages.js";
+/** Pinned so deploys are reproducible; checked 2026-10-23. */
+export 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 async function deployCloudflarePages(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 args = ["--yes", WRANGLER, "pages", "deploy", "dist", "--project-name", options.project, "--branch", options.branch];
+    if (options.commit)
+        args.push("--commit-hash", options.commit);
+    const res = await run("npx", args, root);
+    const output = redact(`${res.stdout}\n${res.stderr}`, secrets);
+    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`."
+            : "";
+        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);
+    if (!deploymentUrl)
+        return { status: "unconfirmed", branch: options.branch, reason: `wrangler succeeded but printed no deployment URL.\n${tail(output)}` };
+    // Wrangler's success is the provider's confirmation; also check the deployment actually serves.
+    for (let i = 0; i < 5; i++) {
+        const page = await doFetch(deploymentUrl, { signal: AbortSignal.timeout(20_000) }).catch(() => undefined);
+        if (page?.ok)
+            return { status: "success", branch: options.branch, deploymentUrl, pageUrl: deploymentUrl };
+        await sleep(3000);
+    }
+    return { status: "unconfirmed", branch: options.branch, deploymentUrl, reason: `Uploaded, but ${deploymentUrl} did not respond with 200 yet. Check it in a minute.` };
+}
+function tail(text) {
+    return text.trim().split("\n").slice(-8).join("\n");
+}

package/dist/deploy/git.d.ts

@@ -0,0 +1,20 @@
+export interface GitResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/** Runs git without a shell. Non-zero exits are returned, not thrown, so callers can explain them. */
+export declare function gitRaw(cwd: string, args: string[]): Promise<GitResult>;
+export declare function git(cwd: string, args: string[]): Promise<string>;
+export interface ChangedFile {
+    /** Two-letter porcelain status, e.g. "??", " M", "D ". */
+    status: string;
+    path: string;
+}
+/** Changes git would commit with `git add -A`, honoring .gitignore. */
+export declare function changedFiles(cwd: string): Promise<ChangedFile[]>;
+/**
+ * Routes of pages changed (or deleted) since `ref`. The ref is resolved to a
+ * commit SHA first, so it can never be read as a git option such as --output=<file>.
+ */
+export declare function changedPageRoutes(cwd: string, ref: string): Promise<string[]>;

package/dist/deploy/git.js

@@ -0,0 +1,55 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { VageError } from "../core/errors.js";
+import { routeForPage } from "../core/routes.js";
+const exec = promisify(execFile);
+/** Runs git without a shell. Non-zero exits are returned, not thrown, so callers can explain them. */
+export async function gitRaw(cwd, args) {
+    try {
+        const { stdout, stderr } = await exec("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+        return { stdout, stderr, code: 0 };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT")
+            throw new VageError("git is not installed or not on PATH. Install git and retry.");
+        return { stdout: e.stdout ?? "", stderr: e.stderr ?? "", code: typeof e.code === "number" ? e.code : 1 };
+    }
+}
+export async function git(cwd, args) {
+    const res = await gitRaw(cwd, args);
+    if (res.code !== 0)
+        throw new VageError(`git ${args[0]} failed: ${(res.stderr || res.stdout).trim()}`);
+    return res.stdout.trim();
+}
+/** Changes git would commit with `git add -A`, honoring .gitignore. */
+export async function changedFiles(cwd) {
+    const out = (await gitRaw(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"])).stdout;
+    const entries = out.split("\0").filter(Boolean);
+    const files = [];
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const status = entry.slice(0, 2);
+        files.push({ status, path: entry.slice(3) });
+        if (status.startsWith("R") || status.startsWith("C"))
+            i++; // skip the rename source
+    }
+    return files;
+}
+/**
+ * Routes of pages changed (or deleted) since `ref`. The ref is resolved to a
+ * commit SHA first, so it can never be read as a git option such as --output=<file>.
+ */
+export async function changedPageRoutes(cwd, ref) {
+    if (ref.startsWith("-"))
+        throw new VageError(`Invalid ref "${ref}".`);
+    const resolved = await gitRaw(cwd, ["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`]);
+    if (resolved.code !== 0)
+        throw new VageError(`"${ref}" is not a commit in this repository.`);
+    const changed = await git(cwd, ["diff", "--name-only", "--relative", resolved.stdout.trim(), "--", "src/pages"]);
+    return changed
+        .split("\n")
+        .filter(Boolean)
+        .map((f) => routeForPage(f.replace(/^src\/pages\//, "")))
+        .filter((r) => Boolean(r));
+}