vagejs 0.0.0-stage → 0.2.0

package/dist/deploy/publish.d.ts

@@ -0,0 +1,45 @@
+import { type ChangedFile } from "./git.js";
+export interface PublishPlan {
+    root: string;
+    /** True when `git init` will run (the folder is not a repository yet). */
+    initRepo: boolean;
+    branch: string;
+    /** Remote URL that will be pushed to, if any. */
+    remote?: string;
+    /** True when `--remote` will be added as "origin". */
+    addRemote: boolean;
+    files: ChangedFile[];
+    /** 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). */
+    unpushedCommits: number;
+    warnings: string[];
+}
+export interface PublishResult {
+    plan: PublishPlan;
+    status: "published" | "committed" | "aborted" | "up-to-date";
+    commit?: string;
+    /** Set only after `git ls-remote` shows the remote branch at our commit. */
+    confirmedRemote?: {
+        url: string;
+        branch: string;
+        sha: string;
+    };
+}
+export interface PublishOptions {
+    remote?: string;
+    branch?: string;
+    message?: string;
+    /** Receives the full plan; nothing is changed unless it resolves true. */
+    confirm: (plan: PublishPlan) => Promise<boolean>;
+    /** Files to create if missing, before committing (e.g. a deploy workflow): relative path -> content, given the branch. */
+    extraFiles?: (branch: string) => Record<string, string>;
+}
+/**
+ * Safe commit-and-push: runs check and build, refuses secrets and build
+ * output, shows the plan, asks for confirmation, never force-pushes, and
+ * reports success only after the remote confirms the commit.
+ */
+export declare function publish(root: string, options: PublishOptions): Promise<PublishResult>;
+export declare function planPublish(root: string, options: Omit<PublishOptions, "confirm">): Promise<PublishPlan>;

package/dist/deploy/publish.js

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { check } from "../checks/check.js";
+import { build } from "../core/build.js";
+import { VageError } from "../core/errors.js";
+import { assertBranchName, assertGitRemote } from "../core/validate.js";
+import { changedFiles, git, gitRaw } from "./git.js";
+import { findSecrets } from "./secrets.js";
+const BLOCKED_DIRS = ["node_modules/", "dist/"];
+/**
+ * Safe commit-and-push: runs check and build, refuses secrets and build
+ * output, shows the plan, asks for confirmation, never force-pushes, and
+ * reports success only after the remote confirms the commit.
+ */
+export async function publish(root, options) {
+    const plan = await planPublish(root, options);
+    const nothingToCommit = plan.files.length === 0;
+    if (nothingToCommit && plan.unpushedCommits === 0 && !plan.initRepo)
+        return { plan, status: "up-to-date" };
+    if (!(await options.confirm(plan)))
+        return { plan, status: "aborted" };
+    const cwd = plan.root;
+    if (plan.initRepo)
+        await git(cwd, ["init", "-b", plan.branch]);
+    if (plan.addRemote)
+        await git(cwd, ["remote", "add", "--", "origin", plan.remote]);
+    for (const [rel, content] of Object.entries(plan.extraFiles)) {
+        fs.mkdirSync(path.dirname(path.join(cwd, rel)), { recursive: true });
+        fs.writeFileSync(path.join(cwd, rel), content);
+    }
+    let commit;
+    if (!nothingToCommit) {
+        await git(cwd, ["add", "-A"]);
+        // Re-check what is actually staged: the tree may have changed since the plan was shown.
+        const staged = (await git(cwd, ["diff", "--cached", "--name-only", "-z"])).split("\0").filter(Boolean);
+        const planned = new Set(plan.files.map((f) => f.path));
+        const unexpected = staged.filter((f) => !planned.has(f));
+        if (unexpected.length) {
+            await git(cwd, ["reset", "-q"]);
+            throw new VageError(`Files changed after the plan was shown and were not committed: ${unexpected.join(", ")}. Re-run to review.`);
+        }
+        await git(cwd, ["commit", "-q", "-m", plan.message]);
+        commit = await git(cwd, ["rev-parse", "HEAD"]);
+    }
+    commit ??= await git(cwd, ["rev-parse", "HEAD"]);
+    if (!plan.remote)
+        return { plan, status: "committed", commit };
+    const push = await gitRaw(cwd, ["push", "-u", "origin", "--", plan.branch]);
+    if (push.code !== 0) {
+        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. vagejs never force-pushes.`);
+        }
+        throw new VageError(`Push failed (your commit is saved locally): ${out.trim()}`);
+    }
+    const remoteSha = (await git(cwd, ["ls-remote", "origin", `refs/heads/${plan.branch}`])).split(/\s/)[0];
+    if (remoteSha !== commit) {
+        throw new VageError(`Push finished but origin/${plan.branch} is at ${remoteSha || "nothing"}, not ${commit}. Check the remote before retrying.`);
+    }
+    return { plan, status: "published", commit, confirmedRemote: { url: plan.remote, branch: plan.branch, sha: remoteSha } };
+}
+export async function planPublish(root, options) {
+    root = path.resolve(root);
+    if (options.branch)
+        assertBranchName(options.branch);
+    if (options.remote)
+        assertGitRemote(options.remote);
+    const checked = await check(root);
+    if (checked.errors > 0)
+        throw new VageError(`vage check found ${checked.errors} error(s). Fix them (run "vage check") before publishing.`);
+    await build(root);
+    const top = await gitRaw(root, ["rev-parse", "--show-toplevel"]);
+    const initRepo = top.code !== 0;
+    const cwd = initRepo ? root : fs.realpathSync(top.stdout.trim());
+    const warnings = [];
+    let branch;
+    if (initRepo) {
+        branch = options.branch ?? "main";
+    }
+    else {
+        branch = await git(cwd, ["branch", "--show-current"]);
+        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; vagejs won't do it for you.`);
+        }
+    }
+    const origin = initRepo ? undefined : await gitRaw(cwd, ["remote", "get-url", "origin"]);
+    const existingRemote = origin?.code === 0 ? origin.stdout.trim() : undefined;
+    if (options.remote && existingRemote && options.remote !== existingRemote) {
+        throw new VageError(`origin is already ${existingRemote}. Change it yourself with "git remote set-url" if that is intended.`);
+    }
+    const remote = existingRemote ?? options.remote;
+    if (!remote)
+        warnings.push('No remote: changes will be committed locally only. Pass --remote <git-url> to push (e.g. a repo created with "gh repo create").');
+    const files = initRepo ? await filesForNewRepo(root) : await changedFiles(cwd);
+    const blocked = files.filter((f) => BLOCKED_DIRS.some((d) => f.path.startsWith(d) || f.path.includes(`/${d}`)));
+    if (blocked.length) {
+        throw new VageError(`Refusing to commit build output or dependencies (${blocked[0].path}, …). Add node_modules/ and dist/ to .gitignore.`);
+    }
+    const secrets = findSecrets(cwd, files.filter((f) => !f.status.includes("D")).map((f) => f.path));
+    if (secrets.length) {
+        throw new VageError(`Refusing to commit possible secrets:\n${secrets.map((s) => `  ${s.path}: ${s.reason}`).join("\n")}\n` +
+            "Add them to .gitignore (and rotate any real credential that was exposed). False positive? Commit manually with git.");
+    }
+    const pkgPath = path.join(root, "package.json");
+    if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        const local = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([, v]) => String(v).startsWith("file:"));
+        if (local.length)
+            warnings.push(`package.json uses local "file:" dependencies (${local.map(([k]) => k).join(", ")}); CI and other machines cannot install them.`);
+    }
+    let unpushedCommits = 0;
+    if (!initRepo && remote && (await gitRaw(cwd, ["rev-parse", "HEAD"])).code === 0) {
+        const tracking = await gitRaw(cwd, ["rev-list", "--count", `origin/${branch}..HEAD`]);
+        unpushedCommits = tracking.code === 0 ? Number(tracking.stdout.trim()) : Number(await git(cwd, ["rev-list", "--count", "HEAD"]));
+    }
+    // Generated files are only created when missing, never overwritten; they are part of the commit.
+    const extraFiles = Object.fromEntries(Object.entries(options.extraFiles?.(branch) ?? {}).filter(([rel]) => !fs.existsSync(path.join(cwd, rel))));
+    for (const rel of Object.keys(extraFiles))
+        files.push({ status: "??", path: rel });
+    return {
+        root: cwd,
+        initRepo,
+        branch,
+        remote,
+        addRemote: Boolean(options.remote && !existingRemote),
+        files,
+        extraFiles,
+        message: options.message ?? "Publish site with vagejs",
+        unpushedCommits,
+        warnings,
+    };
+}
+/** Lists what `git add -A` would stage in a folder that is not a repo yet, honoring .gitignore, without touching it. */
+async function filesForNewRepo(root) {
+    const gitDir = fs.mkdtempSync(path.join(os.tmpdir(), "vage-plan-"));
+    try {
+        await git(root, ["--git-dir", gitDir, "--work-tree", root, "init", "-q"]);
+        const out = await git(root, ["--git-dir", gitDir, "--work-tree", root, "ls-files", "--others", "--exclude-standard", "-z"]);
+        return out.split("\0").filter(Boolean).sort().map((p) => ({ status: "??", path: p }));
+    }
+    finally {
+        fs.rmSync(gitDir, { recursive: true, force: true });
+    }
+}

package/dist/deploy/redirects.d.ts

@@ -0,0 +1,7 @@
+import type { SiteRedirect } from "../core/site.js";
+/**
+ * Cloudflare Pages `_redirects`: real 301s for configured redirects. The
+ * meta-refresh pages stay as a fallback for hosts without redirect support.
+ * Both "/old" and "/old/" are listed so either form redirects.
+ */
+export declare function cloudflareRedirects(redirects: SiteRedirect[]): string;

package/dist/deploy/redirects.js

@@ -0,0 +1,18 @@
+import { VageError } from "../core/errors.js";
+import { ruleData } from "../guidelines/pack.js";
+// https://developers.cloudflare.com/pages/configuration/redirects/ (rule pack "cloudflare.redirects")
+const { maxStaticRules } = ruleData("cloudflare.redirects");
+/**
+ * Cloudflare Pages `_redirects`: real 301s for configured redirects. The
+ * meta-refresh pages stay as a fallback for hosts without redirect support.
+ * Both "/old" and "/old/" are listed so either form redirects.
+ */
+export function cloudflareRedirects(redirects) {
+    const lines = redirects.flatMap((r) => {
+        const sources = r.from === "/" ? ["/"] : [r.from, r.from.replace(/\/$/, "")];
+        return sources.map((from) => `${from} ${r.to} 301`);
+    });
+    if (lines.length > maxStaticRules)
+        throw new VageError(`_redirects would have ${lines.length} rules; Cloudflare Pages allows ${maxStaticRules}.`);
+    return `# Generated by vagejs from redirects in vage.config.ts\n${lines.join("\n")}\n`;
+}

package/dist/deploy/secrets.d.ts

@@ -0,0 +1,6 @@
+export interface SecretHit {
+    path: string;
+    reason: string;
+}
+/** Scans files about to be committed. Never returns the secret value itself. */
+export declare function findSecrets(root: string, files: string[]): SecretHit[];

package/dist/deploy/secrets.js

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+/** File names that commonly hold credentials. */
+const SECRET_FILES = [
+    [/(^|\/)\.env(\.(?!example$|sample$|template$)[^/]+)?$/, "environment file"],
+    [/(^|\/)\.(dev\.vars|envrc)$/, "environment 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"],
+    [/(^|\/)\.(netrc|pgpass)$/, "credentials file"],
+];
+/** Well-known token formats. Matching is a strong hint, not proof; false positives are possible. */
+const SECRET_CONTENT = [
+    [/-----BEGIN (?:[A-Z]+ )?PRIVATE KEY(?: BLOCK)?-----/, "private key"],
+    [/\bAKIA[0-9A-Z]{16}\b/, "AWS access key ID"],
+    [/\bgh[pousr]_[A-Za-z0-9]{36,}\b/, "GitHub token"],
+    [/\bgithub_pat_[A-Za-z0-9_]{22,}\b/, "GitHub fine-grained token"],
+    [/\bAIza[0-9A-Za-z_-]{35}\b/, "Google API key"],
+    [/\bGOCSPX-[A-Za-z0-9_-]{20,}/, "Google OAuth client secret"],
+    [/\b1\/\/0[A-Za-z0-9_-]{20,}/, "Google OAuth refresh token"],
+    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, "Slack token"],
+    [/\bsk_live_[A-Za-z0-9]{16,}\b/, "Stripe live key"],
+    [/\bsk-ant-[A-Za-z0-9_-]{20,}\b/, "Anthropic API key"],
+    [/\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/, "OpenAI-style API key"],
+    [/_authToken\s*=\s*\S+/, "npm auth token"],
+];
+/** Text files above this are flagged for manual review instead of being skipped silently. */
+const MAX_SCAN_BYTES = 20 * 1024 * 1024;
+/** Scans files about to be committed. Never returns the secret value itself. */
+export function findSecrets(root, files) {
+    const hits = [];
+    for (const rel of files) {
+        const name = SECRET_FILES.find(([re]) => re.test(rel));
+        if (name) {
+            hits.push({ path: rel, reason: name[1] });
+            continue;
+        }
+        const file = path.join(root, rel);
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            continue;
+        if (isBinary(file))
+            continue;
+        if (fs.statSync(file).size > MAX_SCAN_BYTES) {
+            hits.push({ path: rel, reason: "text file too large to scan for secrets; review it manually" });
+            continue;
+        }
+        const buf = fs.readFileSync(file);
+        const text = buf.toString("utf8");
+        const content = SECRET_CONTENT.find(([re]) => re.test(text));
+        if (content)
+            hits.push({ path: rel, reason: `looks like a ${content[1]}` });
+    }
+    return hits;
+}
+function isBinary(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const head = Buffer.alloc(8000);
+        const n = fs.readSync(fd, head, 0, head.length, 0);
+        return head.subarray(0, n).includes(0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

package/dist/dev/guard.d.ts

@@ -0,0 +1,9 @@
+import type { Plugin } from "vite";
+/**
+ * Runs before Vite's own middleware. The dev server only needs to serve
+ * rendered pages, discovery files, public/ files and Vite's live-reload
+ * client, so everything else (package.json, vage.config.ts, page sources,
+ * layouts, /@fs/ paths, ?raw/?import) is a 404. This matters with --host.
+ */
+export declare function devAccessGuard(root: string, allowedFiles: Set<string>): Plugin;
+export declare function allowed(url: string, publicDir: string, allowedFiles: Set<string>): boolean;

package/dist/dev/guard.js

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+/** Vite's source-transform endpoints: they would expose project files as text or modules. */
+const SOURCE_QUERY = /[?&](raw|import|url|inline|worker|sharedworker|direct|html-proxy)\b/;
+const VITE_CLIENT = "/node_modules/vite/dist/client/";
+/**
+ * Runs before Vite's own middleware. The dev server only needs to serve
+ * rendered pages, discovery files, public/ files and Vite's live-reload
+ * client, so everything else (package.json, vage.config.ts, page sources,
+ * layouts, /@fs/ paths, ?raw/?import) is a 404. This matters with --host.
+ */
+export function devAccessGuard(root, allowedFiles) {
+    const publicDir = path.join(root, "public");
+    return {
+        name: "vage:dev-access-guard",
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (allowed(req.url ?? "/", publicDir, allowedFiles))
+                    return next();
+                res.statusCode = 404;
+                res.end("Not found");
+            });
+        },
+    };
+}
+export function allowed(url, publicDir, allowedFiles) {
+    const [rawPath = "/", query = ""] = url.split("?");
+    let pathname;
+    try {
+        pathname = decodeURIComponent(rawPath);
+    }
+    catch {
+        return false;
+    }
+    if (pathname === "/@vite/client" || pathname === "/@vite/env" || pathname.startsWith("/__vite"))
+        return true;
+    if (pathname.startsWith(VITE_CLIENT) || (pathname.startsWith("/@fs/") && pathname.includes(VITE_CLIENT)))
+        return !pathname.includes("..");
+    if (SOURCE_QUERY.test(`?${query}`))
+        return false;
+    if (pathname.startsWith("/@"))
+        return false; // /@fs/, /@id/ and other internals
+    const ext = path.posix.extname(pathname);
+    if (!ext || ext === ".html")
+        return true; // rendered pages (our middleware decides 200/404)
+    if (allowedFiles.has(pathname))
+        return true;
+    const file = path.resolve(publicDir, `.${pathname}`);
+    if (!file.startsWith(publicDir + path.sep))
+        return false;
+    try {
+        return fs.lstatSync(file).isFile(); // lstat: symlinks are not served
+    }
+    catch {
+        return false;
+    }
+}

package/dist/dev/listen.d.ts

@@ -0,0 +1,6 @@
+export interface ServeOptions {
+    port?: number;
+    host?: string | boolean;
+}
+/** Runs a Vite listen() call and turns a port conflict into an actionable message. */
+export declare function listenOrExplain<T>(listen: () => Promise<T>, port: number | undefined): Promise<T>;

package/dist/dev/listen.js

@@ -0,0 +1,13 @@
+import { VageError } from "../core/errors.js";
+/** Runs a Vite listen() call and turns a port conflict into an actionable message. */
+export async function listenOrExplain(listen, port) {
+    try {
+        return await listen();
+    }
+    catch (err) {
+        if (/already in use|EADDRINUSE/i.test(err.message)) {
+            throw new VageError(`Port ${port} is already in use. Stop the process using it, or choose another port with --port <number>.`);
+        }
+        throw err;
+    }
+}

package/dist/dev/preview.d.ts

@@ -0,0 +1,6 @@
+import type { ServerResponse } from "node:http";
+import { type PreviewServer } from "vite";
+import { type ServeOptions } from "./listen.js";
+/** Serves the production build output from dist/. */
+export declare function startPreviewServer(root: string, options?: ServeOptions): Promise<PreviewServer>;
+export declare function redirect(res: ServerResponse, location: string): void;

package/dist/dev/preview.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+import { preview } from "vite";
+import { OUT_DIR } from "../core/build.js";
+import { VageError } from "../core/errors.js";
+import { listenOrExplain } from "./listen.js";
+/** Serves the production build output from dist/. */
+export async function startPreviewServer(root, options = {}) {
+    root = path.resolve(root);
+    if (!fs.existsSync(path.join(root, OUT_DIR))) {
+        throw new VageError(`No build output found in ${OUT_DIR}/. Run "vage build" first.`);
+    }
+    return listenOrExplain(() => preview({
+        root,
+        configFile: false,
+        logLevel: "warn",
+        appType: "mpa",
+        build: { outDir: OUT_DIR },
+        plugins: [staticHostBehavior(path.join(root, OUT_DIR))],
+        preview: { port: options.port, strictPort: options.port !== undefined, host: options.host },
+    }), options.port);
+}
+/**
+ * Mimics common static hosts: "/about" redirects to "/about/" when
+ * about/index.html exists, and unknown paths get 404.html with a 404 status.
+ */
+function staticHostBehavior(outDir) {
+    const notFound = (res) => {
+        const page = path.join(outDir, "404.html");
+        res.statusCode = 404;
+        if (!fs.existsSync(page))
+            return res.end("Not found");
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(fs.readFileSync(page));
+    };
+    return {
+        name: "vage:static-host",
+        configurePreviewServer(server) {
+            server.middlewares.use((req, res, next) => {
+                const [rawPath = "/", query] = (req.url ?? "/").split("?");
+                let decoded;
+                try {
+                    decoded = decodeURIComponent(rawPath);
+                }
+                catch {
+                    res.statusCode = 400;
+                    return res.end("Bad request");
+                }
+                // Resolve inside dist/ only: no traversal, no probing for files elsewhere.
+                const file = path.resolve(outDir, `.${decoded}`);
+                if (file !== outDir && !file.startsWith(outDir + path.sep))
+                    return notFound(res);
+                const rel = path.relative(outDir, file).split(path.sep).join("/");
+                if (!decoded.endsWith("/") && !path.extname(decoded) && isFile(path.join(file, "index.html"))) {
+                    // Built from the normalized path, so "//evil.example" can't become a protocol-relative redirect.
+                    return redirect(res, `/${rel ? `${encodeURI(rel)}/` : ""}${query ? `?${query}` : ""}`);
+                }
+                if (isFile(decoded.endsWith("/") ? path.join(file, "index.html") : file))
+                    return next();
+                notFound(res);
+            });
+        },
+    };
+}
+function isFile(file) {
+    return fs.existsSync(file) && fs.statSync(file).isFile();
+}
+export function redirect(res, location) {
+    res.statusCode = 301;
+    res.setHeader("Location", location);
+    res.end();
+}

package/dist/dev/server.d.ts

@@ -0,0 +1,8 @@
+import { type ViteDevServer } from "vite";
+import { type ServeOptions } from "./listen.js";
+/**
+ * Starts the dev server. Pages are rendered on every request, so new and
+ * edited pages show up without a restart; any change under src/ or to the
+ * config triggers a full browser reload.
+ */
+export declare function startDevServer(root: string, options?: ServeOptions): Promise<ViteDevServer>;

package/dist/dev/server.js

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createServer } from "vite";
+import { findConfigFile, loadConfig } from "../core/config.js";
+import { VageError } from "../core/errors.js";
+import { escapeHtml } from "../core/html.js";
+import { baseViteConfig, viteLoader } from "../core/loader.js";
+import { renderPage } from "../core/render.js";
+import { collectPages } from "../core/pages.js";
+import { renderSite } from "../core/site.js";
+import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "../core/routes.js";
+import { devAccessGuard } from "./guard.js";
+import { listenOrExplain } from "./listen.js";
+import { redirect } from "./preview.js";
+/**
+ * Starts the dev server. Pages are rendered on every request, so new and
+ * edited pages show up without a restart; any change under src/ or to the
+ * config triggers a full browser reload.
+ */
+export async function startDevServer(root, options = {}) {
+    // Vite reports watcher paths with symlinks resolved, so compare against the real path.
+    root = path.resolve(root);
+    if (!fs.existsSync(root))
+        throw new VageError(`Project directory not found: ${root}`);
+    root = fs.realpathSync(root);
+    const pagesDir = path.join(root, "src", "pages");
+    const srcDir = path.join(root, "src") + path.sep;
+    const server = await createServer({
+        ...baseViteConfig(root),
+        plugins: [devAccessGuard(root, new Set(Object.keys(DISCOVERY_FILES)))],
+        server: { port: options.port, strictPort: options.port !== undefined, host: options.host },
+    });
+    const load = viteLoader(server);
+    server.watcher.on("all", (_event, file) => {
+        if (file.startsWith(srcDir) || file === findConfigFile(root)) {
+            server.ws.send({ type: "full-reload", path: "*" });
+        }
+    });
+    server.middlewares.use(async (req, res, next) => {
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return next();
+        const urlPath = req.url ?? "/";
+        const pathname = urlPath.split(/[?#]/)[0];
+        try {
+            if (DISCOVERY_FILES[pathname]) {
+                // 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)
+                    return next();
+                res.setHeader("Content-Type", DISCOVERY_FILES[pathname]);
+                return res.end(content);
+            }
+            // Leave asset requests (any extension other than .html) to Vite.
+            if (/\.[a-z0-9]+$/i.test(pathname) && !pathname.endsWith(".html"))
+                return next();
+            const site = await loadConfig(root, load);
+            let route;
+            try {
+                route = normalizeRequestPath(urlPath);
+            }
+            catch {
+                res.statusCode = 400;
+                return res.end("Bad request");
+            }
+            const target = Object.entries(site.redirects).find(([from]) => normalizeRequestPath(from) === route)?.[1];
+            if (target)
+                return redirect(res, target);
+            const entry = discoverRoutes(pagesDir).find((r) => r.route === route);
+            // Match production preview: "/about" -> "/about/".
+            if (entry && !pathname.endsWith("/") && !pathname.endsWith(".html")) {
+                return redirect(res, entry.route + urlPath.slice(pathname.length));
+            }
+            const notFound = findNotFoundPage(pagesDir);
+            if (!entry && !notFound) {
+                return send(res, 404, await server.transformIndexHtml(urlPath, plainPage("404 — Not found", `No page for ${route}`)));
+            }
+            const file = entry?.file ?? notFound;
+            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) {
+            const message = err.message;
+            server.config.logger.error(message);
+            send(res, 500, await server.transformIndexHtml(urlPath, plainPage("Render error", message)));
+        }
+    });
+    await listenOrExplain(() => server.listen(), options.port);
+    return server;
+}
+const DISCOVERY_FILES = {
+    "/robots.txt": "text/plain; charset=utf-8",
+    "/sitemap.xml": "application/xml; charset=utf-8",
+    "/llms.txt": "text/markdown; charset=utf-8",
+    "/llms-full.txt": "text/markdown; charset=utf-8",
+};
+function send(res, status, html) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(html);
+}
+function plainPage(title, message) {
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body><h1>${escapeHtml(title)}</h1><pre>${escapeHtml(message)}</pre></body></html>`;
+}

package/dist/discovery/crawlers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Documented robots.txt tokens for AI crawlers, grouped by purpose. The list
+ * lives in the rule pack (rule "robots.ai-crawlers") with its official sources;
+ * change it only through a reviewed rule-pack release.
+ */
+export interface CrawlerToken {
+    token: string;
+    provider: string;
+    purpose: "training" | "search";
+    /** Official documentation URL. */
+    source: string;
+}
+export declare const AI_CRAWLERS: CrawlerToken[];

package/dist/discovery/crawlers.js

@@ -0,0 +1,2 @@
+import { rulePack, ruleData } from "../guidelines/pack.js";
+export const AI_CRAWLERS = ruleData("robots.ai-crawlers").crawlers.map((c) => ({ ...c, source: rulePack.sources.find((s) => s.id === c.source).url }));

package/dist/discovery/llms.d.ts

@@ -0,0 +1,12 @@
+/**
+ * llms.txt (https://llmstxt.org) is an emerging convention. Publishing it does
+ * not guarantee that any AI system reads, indexes or cites the site.
+ */
+export interface LlmsPage {
+    title: string;
+    url: string;
+    description?: string;
+    body: string;
+}
+export declare function llmsTxt(title: string, description: string | undefined, pages: LlmsPage[]): string;
+export declare function llmsFullTxt(title: string, description: string | undefined, pages: LlmsPage[]): string;

package/dist/discovery/llms.js

@@ -0,0 +1,19 @@
+/** Keeps a value on one line and stops it from forming Markdown links. */
+const inline = (s) => s.replace(/\s+/g, " ").replace(/[[\]()<>]/g, (c) => `\\${c}`).trim();
+export function llmsTxt(title, description, pages) {
+    const lines = [`# ${inline(title)}`, ""];
+    if (description)
+        lines.push(`> ${inline(description)}`, "");
+    lines.push("## Pages", "");
+    for (const p of pages)
+        lines.push(`- [${inline(p.title)}](${p.url.replace(/[()\s<>]/g, encodeURIComponent)})${p.description ? `: ${inline(p.description)}` : ""}`);
+    return `${lines.join("\n")}\n`;
+}
+export function llmsFullTxt(title, description, pages) {
+    const parts = [`# ${inline(title)}`];
+    if (description)
+        parts.push(`> ${inline(description)}`);
+    for (const p of pages)
+        parts.push(`---\n\nSource: ${p.url}\n\n${p.body.trim()}`);
+    return `${parts.join("\n\n")}\n`;
+}

package/dist/discovery/robots.d.ts

@@ -0,0 +1,8 @@
+import type { SiteConfig } from "../core/config.js";
+type RobotsOptions = Exclude<SiteConfig["seo"]["robots"], false>;
+/**
+ * robots.txt from explicit config only. Unset AI options add nothing, so the
+ * owner's `*` policy applies. robots.txt is advisory and is not access control.
+ */
+export declare function robotsTxt(site: SiteConfig, options: RobotsOptions): string;
+export {};