vagejs 0.0.0-stage → 0.1.0

package/dist/audit/remote.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { VageError } from "../core/errors.js";
+import { apiError, redact, requestWithRetry } from "../integrations/http.js";
+import { rate } from "./vitals.js";
+const PSI_ENDPOINT = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
+const CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+const KEY_HINTS = {
+    400: "Check the URL is public and the API key has this API enabled.",
+    403: "Check the URL is public and the API key has this API enabled.",
+    429: "Rate limited: wait and retry, or use an API key with quota.",
+};
+/** The API key goes in the x-goog-api-key header, never in the URL. */
+function withKey(init, key) {
+    return { ...init, headers: { ...init.headers, ...(key ? { "x-goog-api-key": key } : {}) } };
+}
+export { redact };
+// ---------------------------------------------------------------- PageSpeed Insights (lab)
+const CATEGORY_IDS = ["performance", "accessibility", "seo", "best-practices"];
+const psiSchema = z.object({
+    lighthouseResult: z.object({
+        lighthouseVersion: z.string(),
+        fetchTime: z.string(),
+        finalDisplayedUrl: z.string().optional(),
+        categories: z.record(z.string(), z.object({ score: z.number().nullable() })),
+        audits: z.record(z.string(), z.object({ title: z.string(), score: z.number().nullable().optional(), numericValue: z.number().optional(), displayValue: z.string().optional() })),
+    }),
+});
+/** Normalizes a Lighthouse result (from PSI or a local run). */
+export function labReport(lhr, source, url, strategy) {
+    const score = (id) => {
+        const s = lhr.categories[id]?.score;
+        return s === null || s === undefined ? null : Math.round(s * 100);
+    };
+    const num = (id) => lhr.audits[id]?.numericValue;
+    const opportunities = Object.entries(lhr.audits)
+        .filter(([, a]) => typeof a.score === "number" && a.score < 0.9 && a.displayValue)
+        .sort(([, a], [, b]) => (a.score ?? 1) - (b.score ?? 1))
+        .slice(0, 8)
+        .map(([id, a]) => ({ id, title: a.title, displayValue: a.displayValue }));
+    return {
+        source,
+        url,
+        strategy,
+        fetchTime: lhr.fetchTime,
+        toolVersion: `lighthouse ${lhr.lighthouseVersion}`,
+        scores: {
+            performance: score("performance"),
+            accessibility: score("accessibility"),
+            seo: score("seo"),
+            "best-practices": score("best-practices"),
+        },
+        metrics: {
+            lcpMs: num("largest-contentful-paint"),
+            cls: num("cumulative-layout-shift"),
+            tbtMs: num("total-blocking-time"),
+            fcpMs: num("first-contentful-paint"),
+            speedIndexMs: num("speed-index"),
+        },
+        opportunities,
+    };
+}
+export async function pageSpeed(url, strategy, key, opts = {}) {
+    const params = new URLSearchParams({ url, strategy: strategy.toUpperCase() });
+    for (const c of CATEGORY_IDS)
+        params.append("category", c.toUpperCase().replace("-", "_"));
+    const res = await requestWithRetry("PageSpeed Insights", `${PSI_ENDPOINT}?${params}`, withKey({ method: "GET" }, key), [key], opts);
+    if (!res.ok)
+        throw await apiError("PageSpeed Insights", res, [key], KEY_HINTS);
+    const parsed = psiSchema.safeParse(await res.json().catch(() => undefined));
+    if (!parsed.success)
+        throw new VageError("PageSpeed Insights returned an unexpected response (no lighthouseResult).");
+    return labReport(parsed.data.lighthouseResult, "pagespeed-insights", url, strategy);
+}
+// ---------------------------------------------------------------- CrUX (field)
+const cruxSchema = z.object({
+    record: z.object({
+        metrics: z.record(z.string(), z.object({ percentiles: z.object({ p75: z.union([z.number(), z.string()]) }) })),
+        collectionPeriod: z
+            .object({
+            firstDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+            lastDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+        })
+            .optional(),
+    }),
+});
+const CRUX_METRICS = {
+    largest_contentful_paint: "lcp",
+    interaction_to_next_paint: "inp",
+    cumulative_layout_shift: "cls",
+};
+/**
+ * Queries the CrUX API for the page, falling back to the origin. Returns
+ * undefined when neither has data. A 404 is treated as "no data"; the API
+ * docs do not specify this response, so it is an observed-behavior assumption.
+ */
+export async function cruxField(url, strategy, key, opts = {}) {
+    const formFactor = strategy === "mobile" ? "PHONE" : "DESKTOP";
+    for (const scope of ["url", "origin"]) {
+        const body = { [scope]: scope === "url" ? url : new URL(url).origin, formFactor, metrics: Object.keys(CRUX_METRICS) };
+        const init = withKey({ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, key);
+        const res = await requestWithRetry("CrUX API", CRUX_ENDPOINT, init, [key], opts);
+        if (res.status === 404)
+            continue;
+        if (!res.ok)
+            throw await apiError("CrUX API", res, [key], KEY_HINTS);
+        const parsed = cruxSchema.safeParse(await res.json().catch(() => undefined));
+        if (!parsed.success)
+            throw new VageError("CrUX API returned an unexpected response (no record.metrics).");
+        const metrics = {};
+        for (const [apiName, name] of Object.entries(CRUX_METRICS)) {
+            const raw = parsed.data.record.metrics[apiName]?.percentiles.p75;
+            if (raw === undefined)
+                continue;
+            const p75 = Number(raw); // CLS is a string-encoded double
+            if (Number.isFinite(p75))
+                metrics[name] = { p75, rating: rate(name, p75) };
+        }
+        const period = parsed.data.record.collectionPeriod;
+        const date = (d) => `${d.year}-${String(d.month).padStart(2, "0")}-${String(d.day).padStart(2, "0")}`;
+        return { source: "crux", scope, formFactor, metrics, collectionPeriod: period && `${date(period.firstDate)} to ${date(period.lastDate)}` };
+    }
+    return undefined;
+}

package/dist/audit/vitals.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Core Web Vitals thresholds, assessed at the 75th percentile of real-user
+ * page loads (rule pack "vitals.thresholds", source: https://web.dev/articles/vitals).
+ */
+export declare const VITALS: {
+    readonly lcp: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "LCP";
+        readonly unit: "ms";
+    };
+    readonly inp: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "INP";
+        readonly unit: "ms";
+    };
+    readonly cls: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "CLS";
+        readonly unit: "";
+    };
+};
+export type VitalName = keyof typeof VITALS;
+export type Rating = "good" | "needs-improvement" | "poor";
+export declare function rate(metric: VitalName, p75: number): Rating;
+export declare const LAB_VS_FIELD: string;

package/dist/audit/vitals.js

@@ -0,0 +1,18 @@
+import { ruleData } from "../guidelines/pack.js";
+const T = ruleData("vitals.thresholds");
+/**
+ * Core Web Vitals thresholds, assessed at the 75th percentile of real-user
+ * page loads (rule pack "vitals.thresholds", source: https://web.dev/articles/vitals).
+ */
+export const VITALS = {
+    lcp: { label: "LCP", unit: "ms", ...T.lcp },
+    inp: { label: "INP", unit: "ms", ...T.inp },
+    cls: { label: "CLS", unit: "", ...T.cls },
+};
+export function rate(metric, p75) {
+    const t = VITALS[metric];
+    return p75 <= t.good ? "good" : p75 <= t.poor ? "needs-improvement" : "poor";
+}
+export const LAB_VS_FIELD = "Lab results (Lighthouse/PageSpeed) are a single simulated load and vary between runs. " +
+    "Field data (CrUX) reflects real Chrome users at the 75th percentile over 28 days and is " +
+    "unavailable for pages or sites without enough traffic. Google's Core Web Vitals assessment uses field data.";

package/dist/checks/check.d.ts

@@ -0,0 +1,29 @@
+import { type SiteModel } from "../core/site.js";
+export type Severity = "error" | "warning";
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** Route of the page the finding is about, if any. */
+    page?: string;
+    /** Source file relative to the project root, if any. */
+    source?: string;
+    /** Official documentation backing the rule, where one exists. */
+    docs?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    errors: number;
+    warnings: number;
+    pagesChecked: number;
+    findings: Finding[];
+}
+/**
+ * Static checks on the rendered site (nothing is written to disk).
+ * Passing checks mean the output is technically sound; they do not guarantee
+ * indexing, rankings, rich results or AI citations.
+ */
+export declare function check(root: string, options?: {
+    strict?: boolean;
+}): Promise<CheckResult>;
+export declare function checkSite(root: string, model: SiteModel): Finding[];

package/dist/checks/check.js

@@ -0,0 +1,330 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "node-html-parser";
+import { createBuildLoader } from "../core/loader.js";
+import { listedPages, renderSite } from "../core/site.js";
+const DOCS = {
+    title: "https://developers.google.com/search/docs/appearance/title-link",
+    description: "https://developers.google.com/search/docs/appearance/snippet",
+    canonical: "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls",
+    structuredData: "https://developers.google.com/search/docs/appearance/structured-data/sd-policies",
+    article: "https://developers.google.com/search/docs/appearance/structured-data/article",
+    imgAlt: "https://www.w3.org/WAI/tutorials/images/",
+    lang: "https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html",
+    linkPurpose: "https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html",
+    robots: "https://developers.google.com/search/docs/crawling-indexing/robots/intro",
+};
+/**
+ * Static checks on the rendered site (nothing is written to disk).
+ * Passing checks mean the output is technically sound; they do not guarantee
+ * indexing, rankings, rich results or AI citations.
+ */
+export async function check(root, options = {}) {
+    root = path.resolve(root);
+    const loader = await createBuildLoader(root);
+    try {
+        const model = await renderSite(root, loader.load);
+        const findings = checkSite(root, model);
+        const errors = findings.filter((f) => f.severity === "error").length;
+        const warnings = findings.length - errors;
+        return {
+            ok: errors === 0 && (!options.strict || warnings === 0),
+            errors,
+            warnings,
+            pagesChecked: model.pages.length + (model.notFound ? 1 : 0),
+            findings,
+        };
+    }
+    finally {
+        await loader.close();
+    }
+}
+export function checkSite(root, model) {
+    const findings = model.warnings.map((message) => ({ rule: "config", severity: "warning", message }));
+    const outputs = outputPaths(root, model);
+    const drafts = new Set(model.draftRoutes);
+    const pages = model.notFound ? [...model.pages, model.notFound] : model.pages;
+    for (const page of pages) {
+        const add = (f) => findings.push({ ...f, page: page.route, source: page.source });
+        checkPage(page, parse(page.html), model, outputs, drafts, add);
+    }
+    findings.push(...checkDuplicates(listedPages(model)));
+    findings.push(...checkRobots(model));
+    return findings;
+}
+function checkPage(page, doc, model, outputs, drafts, add) {
+    const indexable = !page.meta.noindex;
+    if (!doc.querySelector("html")?.getAttribute("lang")) {
+        add({ rule: "html-lang", severity: "error", message: "<html> has no lang attribute.", docs: DOCS.lang });
+    }
+    const titles = doc.querySelectorAll("title");
+    if (titles.length !== 1 || !titles[0].text.trim()) {
+        add({ rule: "title", severity: "error", message: `Expected exactly one non-empty <title>, found ${titles.length}.`, docs: DOCS.title });
+    }
+    if (indexable && !doc.querySelector('meta[name="description"]')?.getAttribute("content")) {
+        add({
+            rule: "meta-description",
+            severity: "warning",
+            message: "No meta description. Add `description` to the frontmatter or site config.",
+            docs: DOCS.description,
+        });
+    }
+    if (!doc.querySelector("h1")) {
+        add({ rule: "h1", severity: "warning", message: "Page has no <h1> heading." });
+    }
+    for (const img of doc.querySelectorAll("img")) {
+        const src = img.getAttribute("src") ?? "";
+        if (img.getAttribute("alt") === undefined) {
+            add({ rule: "img-alt", severity: "error", message: `<img src="${src}"> has no alt attribute (use alt="" for decorative images).`, docs: DOCS.imgAlt });
+        }
+        if (!img.getAttribute("width") || !img.getAttribute("height")) {
+            add({ rule: "img-dimensions", severity: "warning", message: `<img src="${src}"> has no width/height; this can cause layout shift.` });
+        }
+    }
+    for (const el of doc.querySelectorAll("[href], [src], [action], [formaction]")) {
+        for (const attr of ["href", "src", "action", "formaction"]) {
+            const value = el.getAttribute(attr);
+            if (value && /^\s*(javascript|vbscript|data:text\/html)/i.test(value.replace(/[\u0000-\u0020]/g, ""))) {
+                add({ rule: "unsafe-url", severity: "error", message: `<${el.tagName.toLowerCase()} ${attr}="${value.slice(0, 60)}"> uses a script URL; this runs code on your site.` });
+            }
+        }
+    }
+    const site = model.site;
+    if (site.deploy.target === "cloudflare-pages" && site.security.headers && site.security.csp === "enforce") {
+        for (const el of doc.querySelectorAll("*")) {
+            const handler = Object.keys(el.attributes).find((a) => /^on[a-z]+$/i.test(a));
+            if (handler) {
+                add({
+                    rule: "csp-inline-handler",
+                    severity: "warning",
+                    message: `<${el.tagName.toLowerCase()} ${handler}="…"> is an inline event handler; the Content Security Policy blocks it. Use addEventListener in a script file.`,
+                });
+            }
+        }
+    }
+    for (const a of doc.querySelectorAll("a[href]")) {
+        const href = a.getAttribute("href");
+        if (!a.text.trim() && !a.getAttribute("aria-label") && !a.querySelector("img[alt]:not([alt=''])")) {
+            add({ rule: "link-text", severity: "warning", message: `Link to "${href}" has no accessible text.`, docs: DOCS.linkPurpose });
+        }
+        const target = internalPath(href, page.route, model.site.site);
+        if (target === undefined)
+            continue;
+        if (target === MALFORMED) {
+            add({ rule: "link-broken", severity: "error", message: `Link to "${href}" is a malformed URL.` });
+            continue;
+        }
+        const resolved = resolveOutput(target, outputs);
+        if (resolved === "missing") {
+            const draft = drafts.has(target.endsWith("/") ? target : `${target}/`);
+            add({
+                rule: "link-broken",
+                severity: "error",
+                message: draft ? `Link to "${href}" points to a draft page, which is not published.` : `Link to "${href}" does not match any page or file.`,
+            });
+        }
+        else if (resolved === "needs-slash") {
+            add({ rule: "link-trailing-slash", severity: "warning", message: `Link to "${href}" redirects; use "${target}/".` });
+        }
+    }
+    for (const [selector, attr] of [
+        ["img[src]", "src"],
+        ["script[src]", "src"],
+        ["link[href]:not([rel=canonical]):not([rel=alternate])", "href"],
+    ]) {
+        for (const el of doc.querySelectorAll(selector)) {
+            const value = el.getAttribute(attr);
+            const target = internalPath(value, page.route, model.site.site);
+            if (target !== undefined && (target === MALFORMED || resolveOutput(target, outputs) === "missing")) {
+                add({ rule: "asset-missing", severity: "error", message: `<${el.tagName.toLowerCase()} ${attr}="${value}"> does not exist in the build output.` });
+            }
+        }
+    }
+    const canonicals = doc.querySelectorAll('link[rel="canonical"]');
+    if (canonicals.length > 1) {
+        add({ rule: "canonical", severity: "error", message: `Found ${canonicals.length} canonical links; use one.`, docs: DOCS.canonical });
+    }
+    for (const link of canonicals) {
+        const href = link.getAttribute("href") ?? "";
+        if (!/^https?:\/\//.test(href)) {
+            add({ rule: "canonical", severity: "error", message: `Canonical "${href}" is not an absolute URL.`, docs: DOCS.canonical });
+            continue;
+        }
+        const target = internalPath(href, page.route, model.site.site);
+        if (target === undefined) {
+            add({ rule: "canonical", severity: "warning", message: `Canonical "${href}" points to another site; search engines may credit that site instead of yours.`, docs: DOCS.canonical });
+        }
+        else if (target === MALFORMED || resolveOutput(target, outputs) !== "ok") {
+            add({ rule: "canonical", severity: "error", message: `Canonical "${href}" does not point to a published page.`, docs: DOCS.canonical });
+        }
+    }
+    for (const script of doc.querySelectorAll('script[type="application/ld+json"]')) {
+        checkJsonLd(script.rawText, add);
+    }
+    checkAnalytics(page.html, doc, model, add);
+}
+function checkAnalytics(html, doc, model, add) {
+    const loaders = html.match(/googletagmanager\.com\/(gtag\/js|gtm\.js)/g) ?? [];
+    if (loaders.length > 1) {
+        add({
+            rule: "analytics-duplicate",
+            severity: "error",
+            message: `Page loads Google tags ${loaders.length} times (${loaders.join(", ")}); this double-counts. Remove the layout's tag or the integrations config.`,
+        });
+    }
+    const { ga4, gtm, plausible } = model.site.integrations;
+    // Each provider that receives events must declare them.
+    const receivers = [
+        ga4?.measurementId && { name: "ga4", events: ga4.events },
+        gtm?.containerId && { name: "gtm", events: gtm.events },
+        plausible && { name: "plausible", events: plausible.events },
+    ].filter((r) => Boolean(r));
+    for (const el of doc.querySelectorAll("[data-vage-event]")) {
+        const name = el.getAttribute("data-vage-event");
+        if (!receivers.length) {
+            add({ rule: "analytics-event", severity: "warning", message: `data-vage-event="${name}" is used but no analytics integration is configured.` });
+            continue;
+        }
+        const missing = receivers.filter((r) => !r.events[name]);
+        if (missing.length) {
+            add({
+                rule: "analytics-event",
+                severity: "error",
+                message: `Event "${name}" is not declared. Add it to ${missing.map((r) => `integrations.${r.name}.events`).join(" and ")} in vage.config.ts.`,
+            });
+            continue;
+        }
+        const params = Object.keys(el.attributes)
+            .filter((a) => a.startsWith("data-vage-param-"))
+            .map((a) => a.slice("data-vage-param-".length).replace(/-/g, "_"));
+        for (const param of params.filter((p) => receivers.some((r) => !r.events[name].params.includes(p)))) {
+            add({ rule: "analytics-event", severity: "error", message: `Event "${name}" has undeclared parameter "${param}". Declare it in its params list.` });
+        }
+    }
+}
+function checkJsonLd(raw, add) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        add({ rule: "jsonld", severity: "error", message: `JSON-LD is not valid JSON: ${err.message}`, docs: DOCS.structuredData });
+        return;
+    }
+    const root = data;
+    if (typeof root["@context"] !== "string" || !/^https?:\/\/schema\.org\/?$/.test(root["@context"])) {
+        add({ rule: "jsonld", severity: "error", message: 'JSON-LD needs "@context": "https://schema.org".', docs: DOCS.structuredData });
+    }
+    const items = (Array.isArray(root["@graph"]) ? root["@graph"] : [root]);
+    for (const item of items) {
+        if (typeof item["@type"] !== "string") {
+            add({ rule: "jsonld", severity: "error", message: 'A JSON-LD item has no "@type".', docs: DOCS.structuredData });
+        }
+        else if (item["@type"] === "Article") {
+            const missing = ["author", "datePublished", "image"].filter((k) => item[k] === undefined);
+            if (missing.length) {
+                add({
+                    rule: "jsonld-article",
+                    severity: "warning",
+                    message: `Article JSON-LD lacks properties Google recommends: ${missing.join(", ")}. Add them to the frontmatter only if they are true.`,
+                    docs: DOCS.article,
+                });
+            }
+        }
+    }
+}
+function checkDuplicates(pages) {
+    const findings = [];
+    for (const [rule, get] of [
+        ["title-duplicate", (p) => p.frontmatter.title],
+        ["description-duplicate", (p) => p.frontmatter.description],
+    ]) {
+        const seen = new Map();
+        for (const p of pages) {
+            const value = get(p);
+            if (value)
+                seen.set(value, [...(seen.get(value) ?? []), p.route]);
+        }
+        for (const [value, routes] of seen) {
+            if (routes.length > 1) {
+                findings.push({ rule, severity: "warning", message: `"${value}" is used by ${routes.join(", ")}. Make each page's ${rule.split("-")[0]} unique.` });
+            }
+        }
+    }
+    return findings;
+}
+function checkRobots(model) {
+    const robots = model.files.get("robots.txt");
+    if (!robots)
+        return [];
+    // Find the "*" group and look for a blanket Disallow.
+    const groups = robots.split(/\n\s*\n/);
+    const star = groups.find((g) => /^User-agent:\s*\*\s*$/im.test(g));
+    if (star && /^Disallow:\s*\/\s*$/im.test(star) && model.pages.some((p) => !p.meta.noindex)) {
+        return [
+            {
+                rule: "robots-blocks-all",
+                severity: "warning",
+                message: "robots.txt disallows all crawlers (User-agent: * / Disallow: /) while pages are indexable.",
+                source: "robots.txt",
+                docs: DOCS.robots,
+            },
+        ];
+    }
+    return [];
+}
+/** Every path the build would write, as "/path" strings. */
+function outputPaths(root, model) {
+    const out = new Set();
+    for (const p of model.pages)
+        out.add(`/${p.outFile}`);
+    if (model.notFound)
+        out.add("/404.html");
+    for (const r of model.redirects)
+        out.add(`/${r.outFile}`);
+    for (const name of model.files.keys())
+        out.add(`/${name}`);
+    const walk = (dir, prefix) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), `${prefix}/${e.name}`);
+            else
+                out.add(`${prefix}/${e.name}`);
+        }
+    };
+    const publicDir = path.join(root, "public");
+    if (fs.existsSync(publicDir))
+        walk(publicDir, "");
+    return out;
+}
+const MALFORMED = "\u0000malformed";
+/** Returns the site-relative path for internal URLs, undefined for external ones, MALFORMED when undecodable. */
+function internalPath(href, base, site) {
+    if (/^(mailto:|tel:|javascript:|vbscript:|data:|#)/i.test(href.trim()) || href === "")
+        return undefined;
+    let url;
+    try {
+        url = new URL(href, `http://internal.invalid${base}`);
+    }
+    catch {
+        return MALFORMED;
+    }
+    const isInternal = url.host === "internal.invalid" || (site !== undefined && url.origin === site);
+    if (!isInternal)
+        return undefined;
+    try {
+        return decodeURIComponent(url.pathname);
+    }
+    catch {
+        return MALFORMED;
+    }
+}
+function resolveOutput(target, outputs) {
+    if (target.endsWith("/"))
+        return outputs.has(`${target}index.html`) ? "ok" : "missing";
+    if (outputs.has(target))
+        return "ok";
+    if (!path.posix.extname(target) && outputs.has(`${target}/index.html`))
+        return "needs-slash";
+    return "missing";
+}

package/dist/cli/create.d.ts

@@ -0,0 +1,10 @@
+export interface CreateResult {
+    dir: string;
+    files: string[];
+}
+/**
+ * Copies the starter template into `dir`. Refuses to write into a non-empty
+ * directory. `vageSpec` is the dependency spec written to package.json
+ * (a version range, or e.g. "file:../vagejs-0.1.0.tgz" while unpublished).
+ */
+export declare function createProject(dir: string, vageSpec: string): CreateResult;

package/dist/cli/create.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { VageError } from "../core/errors.js";
+const TEMPLATE_DIR = fileURLToPath(new URL("../../templates/starter", import.meta.url));
+/** npm strips .gitignore from published packages, so templates store it under this name. */
+const RENAMES = { _gitignore: ".gitignore" };
+/**
+ * Copies the starter template into `dir`. Refuses to write into a non-empty
+ * directory. `vageSpec` is the dependency spec written to package.json
+ * (a version range, or e.g. "file:../vagejs-0.1.0.tgz" while unpublished).
+ */
+export function createProject(dir, vageSpec) {
+    dir = path.resolve(dir);
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length > 0) {
+        throw new VageError(`${dir} already exists and is not empty. Choose a new directory name.`);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.cpSync(TEMPLATE_DIR, dir, { recursive: true });
+    for (const [from, to] of Object.entries(RENAMES)) {
+        if (fs.existsSync(path.join(dir, from)))
+            fs.renameSync(path.join(dir, from), path.join(dir, to));
+    }
+    const pkgPath = path.join(dir, "package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    pkg.name = toPackageName(path.basename(dir));
+    pkg.devDependencies.vagejs = vageSpec;
+    fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return { dir, files: listFiles(dir) };
+}
+function toPackageName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9-~._]+/g, "-").replace(/^[-._]+/, "") || "my-website";
+}
+function listFiles(dir, prefix = "") {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .flatMap((e) => (e.isDirectory() ? listFiles(path.join(dir, e.name), `${prefix}${e.name}/`) : [`${prefix}${e.name}`]))
+        .sort();
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};