vagejs 0.0.0-stage → 0.2.0

package/dist/deploy/cloudflare-pages.js

@@ -0,0 +1,42 @@
+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`."
+            : /pages_build_output_dir|project not found|delegat|Workers/i.test(output)
+                ? ' Cloudflare now creates new sites as Workers rather than Pages projects. Set deploy.target to "cloudflare-workers" in vage.config.ts and run vage deploy again.'
+                : "";
+        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/cloudflare-workers.d.ts

@@ -0,0 +1,59 @@
+import type { DeployStatus, Runner } from "./github-pages.js";
+/** In wrangler's own lookup order. */
+export declare const WRANGLER_CONFIGS: string[];
+/** Compatibility date for the generated config; Workers static assets need nothing newer. Checked 2026-10-23. */
+export declare const COMPATIBILITY_DATE = "2026-10-01";
+/** What vagejs needs to know from a project's own wrangler config. */
+export interface WranglerConfig {
+    file: string;
+    name?: string;
+    /** assets.directory, resolved against the project root. */
+    assetsDir?: string;
+    notFoundHandling?: string;
+}
+/**
+ * Reads name and assets settings from the project's wrangler config. Refuses setups where
+ * wrangler could pick a different file or Worker than the one shown: several config files,
+ * a CLOUDFLARE_ENV environment, or a .wrangler/deploy redirect.
+ */
+export declare function readWranglerConfig(root: string, env?: Record<string, string | undefined>): WranglerConfig | undefined;
+export interface WorkersPlan {
+    /** The Worker that will actually be deployed. */
+    worker: string;
+    /** The project's wrangler config, if it has one. */
+    config?: WranglerConfig;
+    warnings: string[];
+}
+/**
+ * Decides which Worker gets deployed, and refuses setups where the plan and what
+ * wrangler would actually do differ (another Worker name, or a folder other than dist/).
+ */
+export declare function planWorkersDeploy(root: string, requested: string | undefined): WorkersPlan;
+export interface WorkersDeployment extends DeployStatus {
+    worker: string;
+    /** How it was deployed: a new version switched to 100% (existing Worker), or a full first deploy. */
+    mode?: "version" | "first-deploy";
+    versionId?: string;
+}
+/**
+ * Deploys dist/ as a Cloudflare Worker with static assets (what Cloudflare now creates
+ * instead of Pages projects; `_headers` and `_redirects` still apply).
+ *
+ * - With a wrangler config in the project (needed for custom domains and routes), that
+ *   file is used as-is; `planWorkersDeploy` has already checked its name and folder.
+ *   Otherwise a temporary config pointing at dist/ is generated, so the project gains no files.
+ * - Existing Workers get `wrangler versions upload` + `versions deploy <id>@100%`: the new
+ *   version takes all traffic without re-applying routes or custom domains, so the site
+ *   stays up. Only Cloudflare's "Worker doesn't exist" error leads to a first `wrangler deploy`.
+ * - Success needs wrangler to succeed AND the live site to answer 200: `siteUrl` when set,
+ *   else the Worker's workers.dev URL (never a version preview URL).
+ */
+export declare function deployCloudflareWorkers(root: string, options: {
+    plan: WorkersPlan;
+    tag?: string;
+    siteUrl?: string;
+    run?: Runner;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    env?: Record<string, string | undefined>;
+}): Promise<WorkersDeployment>;

package/dist/deploy/cloudflare-workers.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { VageError } from "../core/errors.js";
+import { redact } from "../integrations/http.js";
+import { WRANGLER } from "./cloudflare-pages.js";
+import { runCommand } from "./github-pages.js";
+/** In wrangler's own lookup order. */
+export const WRANGLER_CONFIGS = ["wrangler.json", "wrangler.jsonc", "wrangler.toml"];
+/** Compatibility date for the generated config; Workers static assets need nothing newer. Checked 2026-10-23. */
+export const COMPATIBILITY_DATE = "2026-10-01";
+/**
+ * Reads name and assets settings from the project's wrangler config. Refuses setups where
+ * wrangler could pick a different file or Worker than the one shown: several config files,
+ * a CLOUDFLARE_ENV environment, or a .wrangler/deploy redirect.
+ */
+export function readWranglerConfig(root, env = process.env) {
+    const present = WRANGLER_CONFIGS.filter((f) => fs.existsSync(path.join(root, f)));
+    if (present.length > 1)
+        throw new VageError(`Found ${present.join(" and ")}. Keep one wrangler config so it's clear which Worker gets deployed.`);
+    if (fs.existsSync(path.join(root, ".wrangler", "deploy", "config.json"))) {
+        throw new VageError(".wrangler/deploy/config.json redirects wrangler to another config. Remove it, or deploy with wrangler directly.");
+    }
+    const file = present[0];
+    if (!file)
+        return undefined;
+    if (env.CLOUDFLARE_ENV)
+        throw new VageError(`CLOUDFLARE_ENV="${env.CLOUDFLARE_ENV}" makes wrangler deploy that environment's Worker. Unset it to deploy with vagejs.`);
+    const text = fs.readFileSync(path.join(root, file), "utf8").replace(/^\uFEFF/, "");
+    let name, dir, nf;
+    if (file.endsWith(".toml")) {
+        const lines = text.split(/\r?\n/).map((l) => l.replace(/\s+#.*$|^\s*#.*$/, ""));
+        const header = (l) => /^\s*\[/.test(l);
+        const firstHeader = lines.findIndex(header);
+        const top = firstHeader === -1 ? lines : lines.slice(0, firstHeader);
+        const assetsStart = lines.findIndex((l) => /^\s*\[assets\]\s*$/.test(l));
+        const assetsEnd = assetsStart === -1 ? -1 : lines.findIndex((l, i) => i > assetsStart && header(l));
+        const assets = assetsStart === -1 ? [] : lines.slice(assetsStart + 1, assetsEnd === -1 ? undefined : assetsEnd);
+        const value = (block, key) => {
+            for (const l of block) {
+                const m = new RegExp(`^\\s*${key}\\s*=\\s*(?:"([^"]*)"|'([^']*)')\\s*$`).exec(l);
+                if (m)
+                    return m[1] ?? m[2];
+            }
+            return undefined;
+        };
+        name = value(top, "name");
+        dir = value(assets, "directory");
+        nf = value(assets, "not_found_handling");
+        const inline = top.map((l) => /^\s*assets\s*=\s*\{(.*)\}\s*$/.exec(l)?.[1]).find(Boolean);
+        if (inline) {
+            dir ??= /directory\s*=\s*"([^"]*)"/.exec(inline)?.[1];
+            nf ??= /not_found_handling\s*=\s*"([^"]*)"/.exec(inline)?.[1];
+        }
+    }
+    else {
+        let data;
+        try {
+            data = JSON.parse(stripJsonComments(text));
+        }
+        catch (err) {
+            throw new VageError(`Could not read ${file}: ${err.message}`, path.join(root, file));
+        }
+        ({ name } = data);
+        dir = data.assets?.directory;
+        nf = data.assets?.not_found_handling;
+    }
+    return {
+        file,
+        name: typeof name === "string" ? name : undefined,
+        assetsDir: typeof dir === "string" ? path.resolve(root, dir) : undefined,
+        notFoundHandling: typeof nf === "string" ? nf : undefined,
+    };
+}
+/** JSONC to JSON: drops // and /* *\/ comments and trailing commas outside strings. */
+function stripJsonComments(text) {
+    let out = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"') {
+            const end = /"(?:[^"\\]|\\.)*"/y;
+            end.lastIndex = i;
+            const m = end.exec(text);
+            const str = m ? m[0] : text.slice(i);
+            out += str;
+            i += str.length - 1;
+        }
+        else if (c === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (c === "/" && text[i + 1] === "*") {
+            i = text.indexOf("*/", i + 2);
+            if (i === -1)
+                break;
+            i++;
+        }
+        else if (c === "," && /^\s*(\/\/[^\n]*\n\s*|\/\*[\s\S]*?\*\/\s*)*[}\]]/.test(text.slice(i + 1))) {
+            // trailing comma: drop it
+        }
+        else
+            out += c;
+    }
+    return out;
+}
+/**
+ * Decides which Worker gets deployed, and refuses setups where the plan and what
+ * wrangler would actually do differ (another Worker name, or a folder other than dist/).
+ */
+export function planWorkersDeploy(root, requested) {
+    const config = readWranglerConfig(root);
+    const warnings = [];
+    if (!config) {
+        if (!requested)
+            throw new VageError("No Worker name. Pass --project <name>, set deploy.cloudflareWorker, or add a wrangler.jsonc.");
+        return { worker: requested, warnings };
+    }
+    if (!config.name)
+        throw new VageError(`${config.file} has no "name". Add the Worker's name there.`, path.join(root, config.file));
+    if (requested && requested !== config.name) {
+        throw new VageError(`${config.file} deploys the Worker "${config.name}", but this deploy asks for "${requested}". ` +
+            `Make them match (deploy.cloudflareWorker / --project, or "name" in ${config.file}); vagejs won't deploy a different Worker than it shows.`);
+    }
+    const dist = path.join(root, "dist");
+    if (config.assetsDir !== dist) {
+        throw new VageError(`${config.file} must serve the built site: set assets.directory to "dist" (it is ${config.assetsDir ? `"${path.relative(root, config.assetsDir) || "."}"` : "not set"}).`, path.join(root, config.file));
+    }
+    if (config.notFoundHandling !== "404-page" && fs.existsSync(path.join(root, "src", "pages", "404.md"))) {
+        warnings.push(`${config.file}: add "not_found_handling": "404-page" under "assets", or unknown URLs get an empty 404 instead of your 404 page.`);
+    }
+    return { worker: config.name, config, warnings };
+}
+/**
+ * Deploys dist/ as a Cloudflare Worker with static assets (what Cloudflare now creates
+ * instead of Pages projects; `_headers` and `_redirects` still apply).
+ *
+ * - With a wrangler config in the project (needed for custom domains and routes), that
+ *   file is used as-is; `planWorkersDeploy` has already checked its name and folder.
+ *   Otherwise a temporary config pointing at dist/ is generated, so the project gains no files.
+ * - Existing Workers get `wrangler versions upload` + `versions deploy <id>@100%`: the new
+ *   version takes all traffic without re-applying routes or custom domains, so the site
+ *   stays up. Only Cloudflare's "Worker doesn't exist" error leads to a first `wrangler deploy`.
+ * - Success needs wrangler to succeed AND the live site to answer 200: `siteUrl` when set,
+ *   else the Worker's workers.dev URL (never a version preview URL).
+ */
+export async function deployCloudflareWorkers(root, options) {
+    const run = options.run ?? runCommand;
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const secrets = [(options.env ?? process.env).CLOUDFLARE_API_TOKEN];
+    const { worker } = options.plan;
+    let tempDir;
+    // Always name the config file, so wrangler can't pick another one (e.g. in a parent folder).
+    const configArgs = options.plan.config ? ["--config", path.join(root, options.plan.config.file)] : [];
+    if (!options.plan.config) {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "vage-wrangler-"));
+        const config = {
+            name: worker,
+            compatibility_date: COMPATIBILITY_DATE,
+            assets: { directory: path.join(root, "dist"), not_found_handling: "404-page" },
+        };
+        fs.writeFileSync(path.join(tempDir, "wrangler.json"), JSON.stringify(config, null, 2));
+        configArgs.push("--config", path.join(tempDir, "wrangler.json"));
+    }
+    try {
+        const wrangler = (...args) => run("npx", ["--yes", WRANGLER, ...args, ...configArgs], root);
+        const out = (r) => redact(`${r.stdout}\n${r.stderr}`, secrets);
+        const failReason = (code, text) => {
+            const auth = /auth|login|token|unauthori[sz]ed|10000/i.test(text) ? " Set CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, or run `npx wrangler login`." : "";
+            return `wrangler failed (exit ${code}).${auth}\n${tail(text)}`;
+        };
+        let mode = "version";
+        let versionId;
+        let output;
+        const tag = options.tag ?? `vage-${Date.now()}`;
+        const upload = await wrangler("versions", "upload", "--tag", tag);
+        output = out(upload);
+        if (upload.code !== 0) {
+            // Only a Worker that doesn't exist yet gets a full deploy (which also attaches routes).
+            if (!/\b10007\b|worker[^\n]*(?:does not exist|not found)/i.test(output))
+                return { status: "failure", worker, reason: failReason(upload.code, output) };
+            mode = "first-deploy";
+            const first = await wrangler("deploy");
+            output = out(first);
+            if (first.code !== 0)
+                return { status: "failure", worker, mode, reason: failReason(first.code, output) };
+        }
+        else {
+            versionId = /Version ID:\s*([0-9a-f-]{36})/i.exec(output)?.[1];
+            if (!versionId)
+                return { status: "failure", worker, reason: `wrangler uploaded but printed no version ID.\n${tail(output)}` };
+            const switched = await wrangler("versions", "deploy", `${versionId}@100%`, "--yes");
+            if (switched.code !== 0)
+                return { status: "failure", worker, versionId, reason: `Version ${versionId} uploaded but not deployed. ${failReason(switched.code, out(switched))}` };
+            output += `\n${out(switched)}`;
+        }
+        // Lines mentioning "preview" carry version preview URLs, which show the new version even when the live site doesn't.
+        const workersDev = output
+            .split("\n")
+            .filter((line) => !/preview/i.test(line))
+            .join("\n")
+            .match(/https:\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)*\.workers\.dev/gi)
+            ?.at(-1);
+        const pageUrl = options.siteUrl ?? workersDev;
+        if (!pageUrl)
+            return { status: "unconfirmed", worker, mode, versionId, reason: "Deployed, but there is no URL to check: set `site` in vage.config.ts." };
+        for (let i = 0; i < 5; i++) {
+            const page = await doFetch(pageUrl, { signal: AbortSignal.timeout(20_000) }).catch(() => undefined);
+            if (page?.ok)
+                return { status: "success", worker, mode, versionId, pageUrl };
+            await sleep(3000);
+        }
+        return { status: "unconfirmed", worker, mode, versionId, pageUrl, reason: `Deployed, but ${pageUrl} did not respond with 200 yet. Check it in a minute.` };
+    }
+    finally {
+        if (tempDir)
+            fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+function tail(text) {
+    return text.trim().split("\n").slice(-8).join("\n");
+}

package/dist/deploy/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));
+}

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

@@ -0,0 +1,33 @@
+export declare const PAGES_WORKFLOW = ".github/workflows/deploy.yml";
+/**
+ * GitHub Actions workflow: check and build on every push to `branch`, then
+ * deploy dist/ to GitHub Pages. Action majors checked 2026-10-23 against
+ * https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
+ * and each action's latest release. Least privilege: only the deploy job can write to Pages.
+ */
+export declare function pagesWorkflow(branch: string): string;
+export type Runner = (cmd: string, args: string[], cwd: string) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const runCommand: Runner;
+export interface DeployStatus {
+    status: "success" | "failure" | "unconfirmed";
+    runUrl?: string;
+    pageUrl?: string;
+    reason?: string;
+}
+/** Turns on Pages with "GitHub Actions" as the source if it is not enabled yet. Uses the gh CLI. */
+export declare function ensurePagesEnabled(cwd: string, run?: Runner): Promise<"enabled" | "already-enabled" | {
+    manual: string;
+}>;
+/**
+ * Waits for the Pages workflow run for `sha` and reports what GitHub says.
+ * Without gh, or if the run never appears, the result is "unconfirmed", never success.
+ */
+export declare function confirmPagesDeployment(cwd: string, sha: string, options?: {
+    run?: Runner;
+    sleep?: (ms: number) => Promise<void>;
+    findRunAttempts?: number;
+}): Promise<DeployStatus>;

package/dist/deploy/github-pages.js

@@ -0,0 +1,99 @@
+import { execFile } from "node:child_process";
+export const PAGES_WORKFLOW = ".github/workflows/deploy.yml";
+/**
+ * GitHub Actions workflow: check and build on every push to `branch`, then
+ * deploy dist/ to GitHub Pages. Action majors checked 2026-10-23 against
+ * https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
+ * and each action's latest release. Least privilege: only the deploy job can write to Pages.
+ */
+export function pagesWorkflow(branch) {
+    return `name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [${JSON.stringify(branch)}]
+  workflow_dispatch:
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npx vage check
+      - run: npx vage build
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5
+`;
+}
+export const runCommand = (cmd, args, cwd) => new Promise((resolve) => {
+    execFile(cmd, args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err?.code;
+        resolve({ code: !err ? 0 : code === "ENOENT" ? 127 : typeof code === "number" ? code : 1, stdout, stderr });
+    });
+});
+/** Turns on Pages with "GitHub Actions" as the source if it is not enabled yet. Uses the gh CLI. */
+export async function ensurePagesEnabled(cwd, run = runCommand) {
+    const manual = 'Enable it in the repository: Settings → Pages → Build and deployment → Source: "GitHub Actions".';
+    if ((await run("gh", ["auth", "status"], cwd)).code !== 0)
+        return { manual: `GitHub CLI (gh) is not available or not logged in. ${manual}` };
+    if ((await run("gh", ["api", "repos/{owner}/{repo}/pages"], cwd)).code === 0)
+        return "already-enabled";
+    const created = await run("gh", ["api", "-X", "POST", "repos/{owner}/{repo}/pages", "-f", "build_type=workflow"], cwd);
+    return created.code === 0 ? "enabled" : { manual: `Could not enable Pages automatically (${created.stderr.trim()}). ${manual}` };
+}
+/**
+ * Waits for the Pages workflow run for `sha` and reports what GitHub says.
+ * Without gh, or if the run never appears, the result is "unconfirmed", never success.
+ */
+export async function confirmPagesDeployment(cwd, sha, options = {}) {
+    const run = options.run ?? runCommand;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    if ((await run("gh", ["auth", "status"], cwd)).code !== 0) {
+        return { status: "unconfirmed", reason: "GitHub CLI (gh) is not available or not logged in; check the Actions tab for the deploy run." };
+    }
+    let runId;
+    let runUrl;
+    for (let i = 0; i < (options.findRunAttempts ?? 20) && runId === undefined; i++) {
+        const list = await run("gh", ["run", "list", "--workflow", "deploy.yml", "--commit", sha, "--json", "databaseId,url", "--limit", "1"], cwd);
+        const [found] = list.code === 0 ? JSON.parse(list.stdout || "[]") : [];
+        if (found)
+            ({ databaseId: runId, url: runUrl } = found);
+        else
+            await sleep(3000);
+    }
+    if (runId === undefined)
+        return { status: "unconfirmed", reason: `No deploy.yml run found for ${sha.slice(0, 7)}. Is the workflow on the pushed branch?` };
+    await run("gh", ["run", "watch", String(runId), "--exit-status", "--interval", "5"], cwd);
+    const view = await run("gh", ["run", "view", String(runId), "--json", "conclusion,url"], cwd);
+    const conclusion = view.code === 0 ? JSON.parse(view.stdout).conclusion : "unknown";
+    if (conclusion !== "success")
+        return { status: "failure", runUrl, reason: `Deploy run finished with "${conclusion}". See the run for logs.` };
+    const pages = await run("gh", ["api", "repos/{owner}/{repo}/pages", "--jq", ".html_url"], cwd);
+    return { status: "success", runUrl, pageUrl: pages.code === 0 ? pages.stdout.trim() || undefined : undefined };
+}

package/dist/deploy/headers.d.ts

@@ -0,0 +1,11 @@
+import type { SiteConfig } from "../core/config.js";
+/**
+ * Content Security Policy derived from the built HTML: sha256 hashes of every
+ * inline script and <style>, the external origins layouts load, and the
+ * documented domains of configured analytics. Scripts are locked down (that
+ * is where XSS protection comes from); images, fonts and media may come from
+ * any https origin so ordinary sites don't break.
+ */
+export declare function contentSecurityPolicy(pagesHtml: string[], site: SiteConfig): string;
+/** Cloudflare Pages / Netlify `_headers` for every path. */
+export declare function headersFile(pagesHtml: string[], site: SiteConfig): string;

package/dist/deploy/headers.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { parse } from "node-html-parser";
+import { VageError } from "../core/errors.js";
+import { ruleData } from "../guidelines/pack.js";
+// https://developers.cloudflare.com/pages/configuration/headers/ (rule pack "cloudflare.headers", "csp.providers")
+const { maxLineLength } = ruleData("cloudflare.headers");
+const PROVIDERS = ruleData("csp.providers");
+const EXECUTABLE = /^(|module|text\/javascript|application\/javascript)$/i;
+/**
+ * Content Security Policy derived from the built HTML: sha256 hashes of every
+ * inline script and <style>, the external origins layouts load, and the
+ * documented domains of configured analytics. Scripts are locked down (that
+ * is where XSS protection comes from); images, fonts and media may come from
+ * any https origin so ordinary sites don't break.
+ */
+export function contentSecurityPolicy(pagesHtml, site) {
+    const sources = {
+        "script-src": new Set(["'self'"]),
+        "style-src": new Set(["'self'"]),
+        "img-src": new Set(["'self'", "data:", "https:"]),
+        "font-src": new Set(["'self'", "data:", "https:"]),
+        "connect-src": new Set(["'self'"]),
+        "frame-src": new Set(),
+        "media-src": new Set(["'self'", "https:"]),
+    };
+    const hash = (text) => `'sha256-${createHash("sha256").update(text, "utf8").digest("base64")}'`;
+    const origin = (url) => {
+        if (!url || !/^https?:\/\//i.test(url))
+            return undefined;
+        const o = new URL(url).origin;
+        return site.site && o === site.site ? undefined : o;
+    };
+    for (const html of pagesHtml) {
+        const doc = parse(html);
+        for (const s of doc.querySelectorAll("script")) {
+            if (!EXECUTABLE.test(s.getAttribute("type") ?? ""))
+                continue; // e.g. JSON-LD is data, not code
+            const src = s.getAttribute("src");
+            if (src) {
+                const o = origin(src);
+                if (o)
+                    sources["script-src"].add(o);
+            }
+            else if (s.rawText.trim())
+                sources["script-src"].add(hash(s.rawText));
+        }
+        for (const s of doc.querySelectorAll("style"))
+            sources["style-src"].add(hash(s.rawText));
+        for (const l of doc.querySelectorAll('link[rel="stylesheet"]')) {
+            const o = origin(l.getAttribute("href"));
+            if (o)
+                sources["style-src"].add(o);
+        }
+        for (const f of doc.querySelectorAll("iframe[src]")) {
+            const o = origin(f.getAttribute("src"));
+            if (o)
+                sources["frame-src"].add(o);
+        }
+    }
+    const { ga4, gtm, plausible, clarity } = site.integrations;
+    const add = (extra) => {
+        for (const [d, list] of Object.entries(extra))
+            list.forEach((v) => sources[d].add(v));
+    };
+    if (ga4?.measurementId || gtm?.containerId)
+        add(PROVIDERS.google);
+    if (clarity)
+        add(PROVIDERS.clarity);
+    if (plausible) {
+        // Plausible's snippet loads its script from, and reports to, the same origin.
+        for (const m of plausible.snippet.matchAll(/src=["']([^"']+)["']/g)) {
+            const o = origin(m[1]);
+            if (o)
+                add({ "script-src": [o], "connect-src": [o] });
+        }
+    }
+    add(site.security.cspSources);
+    const directives = [
+        "default-src 'self'",
+        ...Object.entries(sources).filter(([, v]) => v.size).map(([d, v]) => `${d} ${[...v].join(" ")}`),
+        "style-src-attr 'unsafe-inline'", // style="" attributes in content; CSS can't run script
+        "object-src 'none'",
+        "base-uri 'self'",
+        "form-action 'self'",
+        "frame-ancestors 'self'",
+        "upgrade-insecure-requests",
+    ];
+    return directives.join("; ");
+}
+/** Cloudflare Pages / Netlify `_headers` for every path. */
+export function headersFile(pagesHtml, site) {
+    const lines = ["# Generated by vagejs (security in vage.config.ts)", "/*", "  X-Content-Type-Options: nosniff", "  Referrer-Policy: strict-origin-when-cross-origin", "  X-Frame-Options: SAMEORIGIN", "  Permissions-Policy: camera=(), microphone=(), geolocation=()"];
+    if (site.security.csp !== "off") {
+        const name = site.security.csp === "report-only" ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
+        lines.push(`  ${name}: ${contentSecurityPolicy(pagesHtml, site)}`);
+    }
+    const tooLong = lines.find((l) => l.length > maxLineLength);
+    if (tooLong) {
+        throw new VageError(`The generated Content-Security-Policy is ${tooLong.length} characters; _headers lines are limited to ${maxLineLength}. ` +
+            "Reduce distinct inline scripts/styles (move them to files in public/), or set security.csp to \"off\".");
+    }
+    return `${lines.join("\n")}\n`;
+}