vagejs 0.0.0-stage → 0.1.0

package/dist/cli/info.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { frontmatterSchema } from "../content/markdown.js";
+import { CONFIG_FILES, configSchema } from "../core/config.js";
+/**
+ * Machine-readable description of the framework for coding agents. Commands
+ * and schemas are read from the live CLI and Zod definitions, so they cannot
+ * drift from the implementation.
+ */
+export function frameworkInfo(cli, version) {
+    const schema = (s) => z.toJSONSchema(s, { io: "input", unrepresentable: "any" });
+    return {
+        name: "vagejs",
+        version,
+        commands: cli.commands.map((c) => ({
+            usage: `vage ${c.rawName}`,
+            description: c.description,
+            options: c.options
+                .filter((o) => o.name !== "help")
+                .map((o) => ({ flags: o.rawName, description: o.description, default: o.config.default })),
+        })),
+        exitCodes: { 0: "success", 1: "failure (build error, check errors, or check warnings with --strict)" },
+        config: { files: CONFIG_FILES, schema: schema(configSchema) },
+        frontmatter: { schema: schema(frontmatterSchema) },
+        routing: {
+            pagesDir: "src/pages",
+            rules: [
+                "src/pages/index.md -> /",
+                "src/pages/about.md -> /about/",
+                "src/pages/blog/index.md -> /blog/",
+                "src/pages/blog/post.md -> /blog/post/",
+                "src/pages/404.md -> dist/404.html (not a route)",
+                "files or folders starting with _ are ignored",
+                "two files mapping to one route is an error",
+            ],
+            layouts: "src/layouts/<name>.ts default-exports ({ content, page, site }) => string and must contain </head>",
+        },
+        generatedFiles: ["robots.txt", "sitemap.xml", "llms.txt", "llms-full.txt (opt-in)", "404.html", "redirect pages", "<indexnow-key>.txt (opt-in)", "_redirects (cloudflare-pages target)"],
+        environment: {
+            PAGESPEED_API_KEY: "your own key; required for `vage audit --url` (or save it with `vage connect pagespeed`)",
+            CRUX_API_KEY: "your own key; CrUX field data for `vage audit --url` (falls back to the PageSpeed key; or `vage connect crux`)",
+            GOOGLE_OAUTH_CLIENT_ID: "required for `vage connect`; Google Cloud OAuth client of type Desktop app",
+            GOOGLE_OAUTH_CLIENT_SECRET: "optional; the Desktop client's secret",
+            VAGE_CONFIG_DIR: "optional; where the Google token is stored (default: OS user config dir)",
+            CLOUDFLARE_API_TOKEN: "for `vage deploy --target cloudflare-pages` (or run `npx wrangler login`)",
+            CLOUDFLARE_ACCOUNT_ID: "for `vage deploy --target cloudflare-pages`",
+        },
+        notImplemented: [
+            "Bing Webmaster Tools API (use IndexNow for URL submission)",
+            "Netlify and Vercel deploy adapters",
+            "CMS / external content-source adapters",
+            "hreflang / multi-language sites, base paths, sitemap indexes",
+            "MCP server",
+        ],
+    };
+}

package/dist/content/markdown.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const frontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    draft: z.ZodDefault<z.ZodBoolean>;
+    layout: z.ZodOptional<z.ZodString>;
+    noindex: z.ZodDefault<z.ZodBoolean>;
+    canonical: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    type: z.ZodDefault<z.ZodEnum<{
+        article: "article";
+        website: "website";
+    }>>;
+    author: z.ZodOptional<z.ZodString>;
+    datePublished: z.ZodOptional<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>, unknown>>;
+    dateModified: z.ZodOptional<z.ZodPreprocess<z.ZodUnion<readonly [z.ZodISODate, z.ZodISODateTime]>, unknown>>;
+}, z.core.$loose>;
+export type Frontmatter = z.output<typeof frontmatterSchema>;
+export interface MarkdownPage {
+    frontmatter: Frontmatter;
+    /** Markdown body without frontmatter. */
+    body: string;
+    /** Rendered HTML of the Markdown body. */
+    html: string;
+}
+export declare function parseMarkdown(source: string, file: string): MarkdownPage;

package/dist/content/markdown.js

@@ -0,0 +1,51 @@
+import { Marked } from "marked";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { VageError } from "../core/errors.js";
+// YAML may produce Date objects for unquoted timestamps; normalize to ISO strings.
+const isoDate = z.preprocess((v) => (v instanceof Date ? v.toISOString() : v), z.union([z.iso.date(), z.iso.datetime({ offset: true })], { error: "must be an ISO date (2026-01-31) or datetime" }));
+// Single line, no control characters: these values end up in <title>, meta tags and llms.txt lines.
+const singleLine = z.string().regex(/^[^\u0000-\u001f\u007f]*$/, "must be a single line without control characters");
+// A site path ("/x", not "//host") or an absolute http(s) URL.
+const pathOrUrl = /^(\/(?!\/)|https?:\/\/)/;
+export const frontmatterSchema = z.looseObject({
+    title: singleLine.min(1, "title is required").describe("Page title. Required; never invented."),
+    description: singleLine.min(1).optional().describe("Meta description, og:description and llms.txt summary."),
+    draft: z.boolean().default(false).describe("Skipped in builds; still visible in dev."),
+    layout: z
+        .string()
+        .regex(/^[\w-]+$/, "layout must be a file name without extension")
+        .optional()
+        .describe("Loads src/layouts/<layout>.ts. Defaults to 'default'."),
+    noindex: z.boolean().default(false).describe("Adds robots noindex; excludes the page from sitemap.xml and llms.txt."),
+    canonical: z
+        .string()
+        .regex(pathOrUrl, 'must be a site path starting with a single "/" or an http(s) URL')
+        .optional()
+        .describe("Canonical URL override (site path or absolute URL). Defaults to the page's own URL."),
+    image: z.string().regex(pathOrUrl, 'must be a site path starting with a single "/" or an http(s) URL').optional().describe("Social preview image: site path (e.g. /images/og.png) or absolute URL."),
+    type: z.enum(["website", "article"]).default("website").describe('"article" emits og:type=article and Article JSON-LD.'),
+    author: singleLine.min(1).optional().describe("Article author name. Only use a real author."),
+    datePublished: isoDate.optional().describe("ISO date or datetime. Only use a real date."),
+    dateModified: isoDate.optional().describe("ISO date or datetime; also the sitemap <lastmod>."),
+});
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+const marked = new Marked({ gfm: true });
+export function parseMarkdown(source, file) {
+    const match = FRONTMATTER_RE.exec(source);
+    let data = {};
+    if (match) {
+        try {
+            data = parseYaml(match[1] ?? "") ?? {};
+        }
+        catch (err) {
+            throw new VageError(`Invalid YAML frontmatter: ${err.message}`, file);
+        }
+    }
+    const result = frontmatterSchema.safeParse(data);
+    if (!result.success) {
+        throw new VageError(`Invalid frontmatter:\n${z.prettifyError(result.error)}`, file);
+    }
+    const body = match ? source.slice(match[0].length) : source;
+    return { frontmatter: result.data, body, html: marked.parse(body, { async: false }) };
+}

package/dist/content/sanitize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
+ * contributors or (later) CMS sources, so scripts, event handlers, javascript:
+ * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
+ * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ */
+export declare function sanitizeHtml(html: string): Promise<string>;

package/dist/content/sanitize.js

@@ -0,0 +1,17 @@
+let purifier;
+/**
+ * Sanitizes rendered Markdown HTML. Page content may be written by AI agents,
+ * contributors or (later) CMS sources, so scripts, event handlers, javascript:
+ * URLs, iframes, forms and <meta>/<base>/<style> tricks are removed. data-*
+ * attributes (used by analytics events) are kept. Loaded lazily: jsdom is heavy.
+ */
+export async function sanitizeHtml(html) {
+    if (!purifier) {
+        const [{ JSDOM }, { default: createDOMPurify }] = await Promise.all([import("jsdom"), import("dompurify")]);
+        purifier = createDOMPurify(new JSDOM("").window);
+    }
+    return purifier.sanitize(html, {
+        FORBID_TAGS: ["style", "form", "input", "button", "textarea", "select", "option", "base", "link", "meta", "object", "embed"],
+        ALLOW_DATA_ATTR: true,
+    });
+}

package/dist/core/build.d.ts

@@ -0,0 +1,25 @@
+import { type SiteModel } from "./site.js";
+export declare const OUT_DIR = "dist";
+export interface BuildResult {
+    outDir: string;
+    pages: {
+        route: string;
+        source: string;
+        output: string;
+    }[];
+    redirects: {
+        from: string;
+        to: string;
+        output: string;
+    }[];
+    files: string[];
+    skippedDrafts: string[];
+    warnings: string[];
+    durationMs: number;
+}
+export declare function build(root: string): Promise<BuildResult>;
+/** Builds and also returns the rendered site model (for audits). */
+export declare function buildSite(root: string): Promise<{
+    result: BuildResult;
+    model: SiteModel;
+}>;

package/dist/core/build.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { VageError } from "./errors.js";
+import { createBuildLoader } from "./loader.js";
+import { renderSite } from "./site.js";
+export const OUT_DIR = "dist";
+export async function build(root) {
+    return (await buildSite(root)).result;
+}
+/** Builds and also returns the rendered site model (for audits). */
+export async function buildSite(root) {
+    const start = performance.now();
+    root = path.resolve(root);
+    const outDir = path.join(root, OUT_DIR);
+    const loader = await createBuildLoader(root);
+    try {
+        // Render everything before touching dist/ so a failed build leaves the previous output intact.
+        const model = await renderSite(root, loader.load);
+        const outputs = new Map();
+        for (const page of model.pages)
+            outputs.set(page.outFile, page.html);
+        if (model.notFound)
+            outputs.set(model.notFound.outFile, model.notFound.html);
+        for (const r of model.redirects)
+            outputs.set(r.outFile, r.html);
+        for (const [name, content] of model.files)
+            outputs.set(name, content);
+        fs.rmSync(outDir, { recursive: true, force: true });
+        const publicDir = path.join(root, "public");
+        if (fs.existsSync(publicDir))
+            fs.cpSync(publicDir, outDir, { recursive: true });
+        for (const [output, content] of outputs) {
+            const target = path.resolve(outDir, output);
+            // Defense in depth: config is validated, but never write outside dist/.
+            if (!target.startsWith(outDir + path.sep))
+                throw new VageError(`Refusing to write outside ${OUT_DIR}/: ${output}`);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, content);
+        }
+        const result = {
+            outDir,
+            pages: model.pages.map((p) => ({ route: p.route, source: p.source, output: p.outFile })),
+            redirects: model.redirects.map((r) => ({ from: r.from, to: r.to, output: r.outFile })),
+            files: [...model.files.keys()],
+            skippedDrafts: model.skippedDrafts,
+            warnings: model.warnings,
+            durationMs: Math.round(performance.now() - start),
+        };
+        return { result, model };
+    }
+    finally {
+        await loader.close();
+    }
+}

package/dist/core/config.d.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+export declare const CONFIG_FILES: string[];
+export declare const configSchema: z.ZodObject<{
+    site: z.ZodOptional<z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lang: z.ZodDefault<z.ZodString>;
+    markdown: z.ZodDefault<z.ZodObject<{
+        html: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            sanitize: "sanitize";
+        }>>;
+    }, z.core.$strict>>;
+    seo: z.ZodDefault<z.ZodObject<{
+        robots: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                userAgent: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+                allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                disallow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            aiTraining: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                disallow: "disallow";
+            }>>;
+            aiSearch: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                disallow: "disallow";
+            }>>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            rules: {
+                userAgent: string | string[];
+                allow: string[];
+                disallow: string[];
+            }[];
+            aiTraining?: "allow" | "disallow" | undefined;
+            aiSearch?: "allow" | "disallow" | undefined;
+        }, boolean | {
+            rules: {
+                userAgent: string | string[];
+                allow: string[];
+                disallow: string[];
+            }[];
+            aiTraining?: "allow" | "disallow" | undefined;
+            aiSearch?: "allow" | "disallow" | undefined;
+        }>>;
+        sitemap: z.ZodDefault<z.ZodBoolean>;
+        llmsTxt: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            full: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            full: boolean;
+        }, boolean | {
+            full: boolean;
+        }>>;
+        structuredData: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            organization: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                url: z.ZodOptional<z.ZodURL>;
+                logo: z.ZodOptional<z.ZodString>;
+                sameAs: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>]>>, z.ZodTransform<false | {
+            organization?: {
+                name: string;
+                url?: string | undefined;
+                logo?: string | undefined;
+                sameAs?: string[] | undefined;
+            } | undefined;
+        }, boolean | {
+            organization?: {
+                name: string;
+                url?: string | undefined;
+                logo?: string | undefined;
+                sameAs?: string[] | undefined;
+            } | undefined;
+        }>>;
+    }, z.core.$strict>>;
+    performance: z.ZodDefault<z.ZodObject<{
+        budgets: z.ZodDefault<z.ZodObject<{
+            performance: z.ZodDefault<z.ZodNumber>;
+            accessibility: z.ZodDefault<z.ZodNumber>;
+            seo: z.ZodDefault<z.ZodNumber>;
+            bestPractices: z.ZodDefault<z.ZodNumber>;
+            javascriptKb: z.ZodDefault<z.ZodNumber>;
+            cssKb: z.ZodDefault<z.ZodNumber>;
+            imageKb: z.ZodDefault<z.ZodNumber>;
+            fontKb: z.ZodDefault<z.ZodNumber>;
+            totalKb: z.ZodDefault<z.ZodNumber>;
+            requests: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        lighthouse: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            pages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    deploy: z.ZodDefault<z.ZodObject<{
+        target: z.ZodDefault<z.ZodEnum<{
+            "cloudflare-pages": "cloudflare-pages";
+            "github-pages": "github-pages";
+        }>>;
+        cloudflareProject: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    security: z.ZodDefault<z.ZodObject<{
+        headers: z.ZodDefault<z.ZodBoolean>;
+        csp: z.ZodDefault<z.ZodEnum<{
+            enforce: "enforce";
+            off: "off";
+            "report-only": "report-only";
+        }>>;
+        cspSources: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            "connect-src": "connect-src";
+            "font-src": "font-src";
+            "frame-src": "frame-src";
+            "img-src": "img-src";
+            "media-src": "media-src";
+            "script-src": "script-src";
+            "style-src": "style-src";
+        }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+    }, z.core.$strict>>;
+    guidelines: z.ZodDefault<z.ZodObject<{
+        rulePack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    integrations: z.ZodDefault<z.ZodObject<{
+        ga4: z.ZodOptional<z.ZodObject<{
+            measurementId: z.ZodOptional<z.ZodString>;
+            propertyId: z.ZodOptional<z.ZodString>;
+            consentDefault: z.ZodDefault<z.ZodEnum<{
+                denied: "denied";
+                granted: "granted";
+            }>>;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        gtm: z.ZodOptional<z.ZodObject<{
+            containerId: z.ZodOptional<z.ZodString>;
+            consentDefault: z.ZodDefault<z.ZodEnum<{
+                denied: "denied";
+                granted: "granted";
+            }>>;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        plausible: z.ZodOptional<z.ZodObject<{
+            snippet: z.ZodString;
+            events: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                params: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        clarity: z.ZodOptional<z.ZodObject<{
+            snippet: z.ZodString;
+        }, z.core.$strict>>;
+        indexNow: z.ZodOptional<z.ZodObject<{
+            key: z.ZodString;
+            endpoint: z.ZodDefault<z.ZodURL>;
+        }, z.core.$strict>>;
+        searchConsole: z.ZodOptional<z.ZodObject<{
+            property: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    redirects: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type UserConfig = z.input<typeof configSchema>;
+export type SiteConfig = z.output<typeof configSchema>;
+/** Identity helper that gives config files type checking. */
+export declare function defineConfig(config: UserConfig): UserConfig;
+export declare function findConfigFile(root: string): string | undefined;
+export type ModuleLoader = (file: string) => Promise<Record<string, unknown>>;
+export declare function loadConfig(root: string, load: ModuleLoader): Promise<SiteConfig>;
+/** Validates a raw config object and applies defaults. */
+export declare function parseConfig(raw: unknown, file?: string): SiteConfig;

package/dist/core/config.js

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { VageError } from "./errors.js";
+import { ruleData } from "../guidelines/pack.js";
+export const CONFIG_FILES = ["vage.config.ts", "vage.config.js", "vage.config.mjs"];
+/** `true` -> defaults, `false` -> disabled, object -> options. */
+function toggle(options) {
+    return z
+        .union([z.boolean(), options])
+        .default(true)
+        .transform((v) => (v === true ? options.parse({}) : v === false ? false : v));
+}
+// No whitespace or control characters: these values become robots.txt lines and output paths.
+const token = z.string().min(1).regex(/^[^\s\u0000-\u001f\u007f]+$/, "must not contain spaces or line breaks");
+const userAgents = z.union([token, z.array(token).min(1)]);
+const urlPath = token.regex(/^\//, 'must start with "/"');
+/** Redirect source: a site path without ".." segments (it becomes a file path under dist/). */
+const redirectSource = urlPath.refine((p) => !p.split("/").some((seg) => seg === ".." || seg === "."), 'must not contain "." or ".." segments');
+/** Redirect target: a site path ("/x", not "//host") or an absolute http(s) URL. */
+const redirectTarget = token.regex(/^(\/(?!\/)|https?:\/\/)/, 'must be a site path starting with a single "/" or an http(s) URL');
+const robotsSchema = z.strictObject({
+    rules: z
+        .array(z.strictObject({
+        userAgent: userAgents,
+        allow: z.array(urlPath).default([]),
+        disallow: z.array(urlPath).default([]),
+    }))
+        .default([])
+        .describe("Explicit robots.txt groups, written in order."),
+    aiTraining: z
+        .enum(["allow", "disallow"])
+        .optional()
+        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended). Unset: the * group applies."),
+    aiSearch: z
+        .enum(["allow", "disallow"])
+        .optional()
+        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot). Unset: the * group applies."),
+});
+const seoSchema = z.strictObject({
+    robots: toggle(robotsSchema).describe("Generate robots.txt (true/false or options)."),
+    sitemap: z.boolean().default(true).describe("Generate sitemap.xml (needs `site`)."),
+    llmsTxt: toggle(z.strictObject({
+        full: z.boolean().default(false).describe("Also emit llms-full.txt with the Markdown of every listed page."),
+    })).describe("Generate llms.txt (needs `title`)."),
+    structuredData: toggle(z.strictObject({
+        organization: z
+            .strictObject({
+            name: z.string().min(1),
+            url: z.url().optional(),
+            logo: z.string().min(1).optional(),
+            sameAs: z.array(z.url()).optional(),
+        })
+            .optional()
+            .describe("Organization JSON-LD on the home page. Only true, visible facts."),
+    })).describe("Automatic JSON-LD (WebSite, Organization, Article)."),
+});
+const score = z.number().int().min(0).max(100);
+const kb = z.number().positive();
+const budgetsSchema = z.strictObject({
+    performance: score.default(90).describe("Minimum Lighthouse performance score (lab)."),
+    accessibility: score.default(95).describe("Minimum Lighthouse accessibility score (lab)."),
+    seo: score.default(95).describe("Minimum Lighthouse SEO score (lab)."),
+    bestPractices: score.default(90).describe("Minimum Lighthouse best-practices score (lab)."),
+    javascriptKb: kb.default(100).describe("Max uncompressed JavaScript per page, KB."),
+    cssKb: kb.default(50).describe("Max uncompressed CSS per page, KB."),
+    imageKb: kb.default(500).describe("Max image bytes per page, KB."),
+    fontKb: kb.default(150).describe("Max font bytes per page, KB."),
+    totalKb: kb.default(1000).describe("Max total local bytes per page, KB."),
+    requests: z.number().int().positive().default(30).describe("Max resource requests per page (incl. the HTML)."),
+});
+const performanceSchema = z.strictObject({
+    budgets: budgetsSchema.default(() => budgetsSchema.parse({})).describe("Starting points, not universal standards. Adjust per site."),
+    lighthouse: z
+        .strictObject({
+        enabled: z.boolean().default(false).describe("Run Lighthouse in `vage audit` without --lighthouse. Needs the lighthouse package and Chrome."),
+        pages: z.array(z.string().regex(/^\//)).min(1).default(["/"]).describe("Routes to audit with Lighthouse."),
+    })
+        .default({ enabled: false, pages: ["/"] }),
+});
+// GA4 naming rules and limits: rule pack "ga4.naming".
+const GA4 = ruleData("ga4.naming");
+const ga4Name = z
+    .string()
+    .max(GA4.maxNameLength)
+    .regex(/^[A-Za-z][A-Za-z0-9_]*$/, "must start with a letter and use only letters, numbers and underscores");
+const ga4Param = ga4Name.refine((p) => !GA4.reservedParamPrefixes.some((prefix) => p.startsWith(prefix)), "uses a reserved prefix");
+/** Event map whose keys are validated with GA4 naming rules (record keys alone give unhelpful errors). */
+const ga4Events = z.record(z.string(), z.strictObject({ params: z.array(ga4Param).default([]) })).superRefine((events, ctx) => {
+    for (const name of Object.keys(events)) {
+        const result = ga4Name.safeParse(name);
+        if (!result.success)
+            ctx.addIssue({ code: "custom", path: [name], message: `event name "${name}" ${result.error.issues[0].message}` });
+    }
+});
+const consentDefault = z
+    .enum(["denied", "granted"])
+    .default("denied")
+    .describe("Consent mode default for analytics/ads storage before the visitor chooses. Your site provides the consent UI.");
+/** A tracking snippet pasted from the provider's dashboard; inserted verbatim into <head>. */
+const snippet = z
+    .string()
+    .max(5000)
+    .refine((v) => /<script[\s>]/i.test(v), "must be the <script> snippet from the provider's dashboard")
+    .refine((v) => !/googletagmanager\.com/.test(v), "Google tags belong in integrations.ga4 or integrations.gtm");
+const INDEXNOW = ruleData("indexnow.protocol");
+const integrationsSchema = z
+    .strictObject({
+    ga4: z
+        .strictObject({
+        measurementId: z
+            .string()
+            .regex(/^G-[A-Z0-9]+$/, 'must look like "G-XXXXXXX"')
+            .optional()
+            .describe("GA4 web stream measurement ID (public). Tags are added only when set, e.g. process.env.GA4_MEASUREMENT_ID."),
+        propertyId: z.string().regex(/^\d+$/, "must be the numeric GA4 property ID").optional().describe("Numeric property ID for `vage report analytics`."),
+        consentDefault,
+        events: ga4Events
+            .default({})
+            .describe('Allowed custom events for data-vage-event attributes, e.g. { signup_click: { params: ["plan"] } }.'),
+    })
+        .optional(),
+    gtm: z
+        .strictObject({
+        containerId: z.string().regex(/^GTM-[A-Z0-9]+$/, 'must look like "GTM-XXXXXX"').optional().describe("Google Tag Manager container ID."),
+        consentDefault,
+        events: ga4Events.default({}),
+    })
+        .optional(),
+    plausible: z
+        .strictObject({
+        snippet: snippet.describe("Your site's script snippet from Plausible (Site settings → Site installation)."),
+        events: z
+            .record(z.string().min(1).max(120), z.strictObject({ params: z.array(z.string().min(1)).default([]) }))
+            .default({})
+            .describe("Custom events for data-vage-event, sent with plausible(name, { props })."),
+    })
+        .optional(),
+    clarity: z
+        .strictObject({
+        snippet: snippet.describe("Tracking code from Clarity (Settings → Setup → Install manually)."),
+    })
+        .optional()
+        .describe("Microsoft Clarity. window.vageConsent.update() also sends Clarity's consentv2 signal."),
+    indexNow: z
+        .strictObject({
+        key: z.string().regex(new RegExp(INDEXNOW.keyPattern), "must be 8-128 characters: letters, digits or dashes").describe("Public IndexNow key; served as /<key>.txt."),
+        endpoint: z.url().default(INDEXNOW.endpoint).describe("IndexNow endpoint (default: the shared api.indexnow.org)."),
+    })
+        .optional(),
+    searchConsole: z
+        .strictObject({
+        property: z
+            .string()
+            .regex(/^(sc-domain:[^/\s]+|https?:\/\/\S+\/)$/, 'must be "sc-domain:example.com" or a URL prefix ending in "/"')
+            .optional()
+            .describe("Search Console property for `vage report search`."),
+    })
+        .optional(),
+})
+    .refine((i) => !(i.ga4?.measurementId && i.gtm?.containerId), {
+    message: "Configure GA4 directly (ga4.measurementId) or through Tag Manager (gtm.containerId), not both: loading both double-counts.",
+});
+export const configSchema = z.strictObject({
+    site: z
+        .url({ protocol: /^https?$/ })
+        .refine((s) => new URL(s).pathname === "/", "must be an origin without a path (base paths are not supported yet)")
+        .transform((s) => new URL(s).origin)
+        .optional()
+        .describe("Production origin, e.g. https://example.com. Needed for canonical URLs and sitemap.xml."),
+    title: z.string().min(1).optional().describe("Site name: page titles, og:site_name, llms.txt heading."),
+    description: z.string().min(1).optional().describe("Fallback meta description; llms.txt summary."),
+    lang: z.string().min(1).default("en").describe("<html lang> value."),
+    markdown: z
+        .strictObject({
+        html: z
+            .enum(["sanitize", "allow"])
+            .default("sanitize")
+            .describe('"sanitize" removes scripts, event handlers, javascript: URLs, iframes and forms from page content. "allow" trusts all content authors.'),
+    })
+        .default({ html: "sanitize" }),
+    seo: seoSchema.default(() => seoSchema.parse({})),
+    performance: performanceSchema.default(() => performanceSchema.parse({})),
+    deploy: z
+        .strictObject({
+        target: z.enum(["github-pages", "cloudflare-pages"]).default("github-pages").describe("Host used by `vage deploy`."),
+        cloudflareProject: z.string().regex(/^[a-z0-9][a-z0-9-]{0,57}$/).optional().describe("Cloudflare Pages project name."),
+    })
+        .default({ target: "github-pages" }),
+    security: z
+        .strictObject({
+        headers: z.boolean().default(true).describe("Write a _headers file with security headers (Cloudflare Pages target)."),
+        csp: z
+            .enum(["enforce", "report-only", "off"])
+            .default("enforce")
+            .describe("Content Security Policy generated from the built pages: hashes of inline scripts/styles plus the origins your layouts and analytics load."),
+        cspSources: z
+            .partialRecord(z.enum(["script-src", "style-src", "img-src", "font-src", "connect-src", "frame-src", "media-src"]), z.array(z.string().regex(/^('[a-z0-9-]+'|https?:\/\/[^\s;,']+|[a-z]+:)$/, "must be a source like https://cdn.example.com or 'self'")))
+            .default({})
+            .describe("Extra sources per directive, e.g. { \"connect-src\": [\"https://api.example.com\"] }."),
+    })
+        .default({ headers: true, csp: "enforce", cspSources: {} }),
+    guidelines: z
+        .strictObject({
+        rulePack: z
+            .string()
+            .regex(/^\d{4}\.\d{1,2}\.\d+$/)
+            .optional()
+            .describe("Pin the rule-pack version. Builds fail when the installed vagejs ships a different pack, until you review its changelog and update the pin."),
+    })
+        .default({}),
+    integrations: integrationsSchema.default({}).describe("Optional analytics and search integrations. All off unless configured."),
+    redirects: z
+        .record(z.string(), redirectTarget)
+        .superRefine((redirects, ctx) => {
+        for (const from of Object.keys(redirects)) {
+            const result = redirectSource.safeParse(from);
+            if (!result.success)
+                ctx.addIssue({ code: "custom", path: [from], message: `redirect source "${from}" ${result.error.issues[0].message}` });
+        }
+    })
+        .default({})
+        .describe("Old path -> new path or URL. Built as noindex meta-refresh pages; dev answers 301."),
+});
+/** Identity helper that gives config files type checking. */
+export function defineConfig(config) {
+    return config;
+}
+export function findConfigFile(root) {
+    return CONFIG_FILES.map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
+}
+export async function loadConfig(root, load) {
+    const file = findConfigFile(root);
+    return parseConfig(file ? (await load(file)).default : {}, file);
+}
+/** Validates a raw config object and applies defaults. */
+export function parseConfig(raw, file) {
+    const result = configSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        throw new VageError(`Invalid config:\n${z.prettifyError(result.error)}`, file);
+    }
+    return result.data;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,5 @@
+/** An expected, user-facing error. The CLI prints its message without a stack trace. */
+export declare class VageError extends Error {
+    readonly file?: string | undefined;
+    constructor(message: string, file?: string | undefined);
+}