vagejs 0.0.0-stage → 0.1.0

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 VAGE JS (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`;
+}

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 VAGE JS 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. VAGE JS 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; VAGE JS 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 VAGE JS",
+        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 VAGE JS 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$/, "VAGE JS 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;