vagejs 0.0.0-stage → 0.2.0

package/dist/integrations/api-keys.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { VageError } from "../core/errors.js";
+import { credentialsPath } from "./google-auth.js";
+/**
+ * The user's own Google Cloud API keys for audits. vagejs never ships or
+ * shares keys: each user brings theirs (env var, or saved with `vage connect`).
+ * Saved keys live next to the Google token, outside any project, mode 0600.
+ */
+export const API_KEYS = {
+    pagespeed: {
+        env: "PAGESPEED_API_KEY",
+        label: "PageSpeed Insights API",
+        howTo: "Google Cloud Console → APIs & Services → enable “PageSpeed Insights API” → Credentials → Create credentials → API key (restrict it to that API).",
+    },
+    crux: {
+        env: "CRUX_API_KEY",
+        label: "Chrome UX Report (CrUX) API",
+        howTo: "Google Cloud Console → APIs & Services → enable “Chrome UX Report API” → Credentials → Create credentials → API key (one key can serve both APIs).",
+    },
+};
+const KEY_FORMAT = /^[A-Za-z0-9_-]{20,200}$/;
+export function apiKeysPath(env) {
+    return path.join(path.dirname(credentialsPath(env)), "api-keys.json");
+}
+function readAll(env) {
+    const file = apiKeysPath(env);
+    if (!fs.existsSync(file))
+        return {};
+    const parsed = z.record(z.string(), z.string()).safeParse(JSON.parse(fs.readFileSync(file, "utf8")));
+    if (!parsed.success)
+        throw new VageError(`Saved API keys are unreadable. Remove the file and save them again.`, file);
+    return parsed.data;
+}
+/** Environment variable first, then the key saved with `vage connect`. */
+export function resolveApiKey(name, env = process.env) {
+    return env[API_KEYS[name].env]?.trim() || readAll(env)[name];
+}
+export function saveApiKey(name, value, env) {
+    const key = value.trim();
+    if (!KEY_FORMAT.test(key))
+        throw new VageError(`That doesn't look like a Google API key (letters, digits, "-" or "_", no spaces).`);
+    const file = apiKeysPath(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, `${JSON.stringify({ ...readAll(env), [name]: key }, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+    return file;
+}
+export function removeApiKey(name, env) {
+    const all = readAll(env);
+    if (!all[name])
+        return false;
+    delete all[name];
+    const file = apiKeysPath(env);
+    if (Object.keys(all).length)
+        fs.writeFileSync(file, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    else
+        fs.rmSync(file, { force: true });
+    return true;
+}
+export function missingKeyMessage(name) {
+    const k = API_KEYS[name];
+    return `${k.label} needs your own API key. Set ${k.env}, or save one with "vage connect ${name}". Get a key: ${k.howTo}`;
+}

package/dist/integrations/ga4-data.d.ts

@@ -0,0 +1,13 @@
+import { type HttpOptions } from "./http.js";
+export interface AnalyticsRow {
+    pagePath: string;
+    screenPageViews: number;
+    activeUsers: number;
+    sessions: number;
+}
+/** Top pages by views for the last `days` days. */
+export declare function analyticsReport(token: string, propertyId: string, days: number, opts?: HttpOptions): Promise<{
+    propertyId: string;
+    days: number;
+    rows: AnalyticsRow[];
+}>;

package/dist/integrations/ga4-data.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { apiError, requestWithRetry } from "./http.js";
+// https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
+const API = "https://analyticsdata.googleapis.com/v1beta";
+const METRICS = ["screenPageViews", "activeUsers", "sessions"];
+const responseSchema = z.object({
+    rows: z
+        .array(z.object({
+        dimensionValues: z.array(z.object({ value: z.string() })),
+        metricValues: z.array(z.object({ value: z.string() })),
+    }))
+        .default([]),
+});
+/** Top pages by views for the last `days` days. */
+export async function analyticsReport(token, propertyId, days, opts) {
+    const res = await requestWithRetry("Google Analytics Data API", `${API}/properties/${encodeURIComponent(propertyId)}:runReport`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({
+            dateRanges: [{ startDate: `${days}daysAgo`, endDate: "today" }],
+            dimensions: [{ name: "pagePath" }],
+            metrics: METRICS.map((name) => ({ name })),
+            orderBys: [{ metric: { metricName: "screenPageViews" }, desc: true }],
+            limit: 25,
+        }),
+    }, [token], opts);
+    if (!res.ok) {
+        throw await apiError("Google Analytics Data API", res, [token], {
+            403: `No access to GA4 property ${propertyId}. Check integrations.ga4.propertyId and that your Google account can view it.`,
+        });
+    }
+    const rows = responseSchema.parse(await res.json()).rows.map((r) => ({
+        pagePath: r.dimensionValues[0]?.value ?? "",
+        screenPageViews: Number(r.metricValues[0]?.value ?? 0),
+        activeUsers: Number(r.metricValues[1]?.value ?? 0),
+        sessions: Number(r.metricValues[2]?.value ?? 0),
+    }));
+    return { propertyId, days, rows };
+}

package/dist/integrations/google-auth.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { type HttpOptions } from "./http.js";
+/** Read-only scopes: least privilege for reports. */
+export declare const SCOPES: {
+    readonly gsc: "https://www.googleapis.com/auth/webmasters.readonly";
+    readonly ga4: "https://www.googleapis.com/auth/analytics.readonly";
+};
+declare const storedSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodOptional<z.ZodString>;
+    refreshToken: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type StoredCredentials = z.infer<typeof storedSchema>;
+/** Outside any project: $VAGE_CONFIG_DIR, else the OS user config dir. Never in the repository. */
+export declare function credentialsPath(env?: Record<string, string | undefined>): string;
+export declare function loadCredentials(env?: Record<string, string | undefined>): StoredCredentials | undefined;
+export interface ConnectOptions {
+    scopes: string[];
+    clientId: string;
+    clientSecret?: string;
+    /** Opens (or prints) the Google consent page URL. */
+    open: (url: string) => void;
+    env?: Record<string, string | undefined>;
+    http?: HttpOptions;
+    timeoutMs?: number;
+}
+/**
+ * Runs the browser consent flow and stores a refresh token. Previously granted
+ * scopes are requested again so connecting GA4 keeps Search Console access.
+ */
+export declare function connectGoogle(options: ConnectOptions): Promise<StoredCredentials>;
+/** Exchanges the stored refresh token for a short-lived access token. */
+export declare function getAccessToken(scope: string, service: "gsc" | "ga4", options?: {
+    env?: Record<string, string | undefined>;
+    http?: HttpOptions;
+}): Promise<string>;
+/** Revokes the refresh token at Google and deletes the local file (even if revocation fails). */
+export declare function disconnectGoogle(options?: {
+    env?: Record<string, string | undefined>;
+    http?: HttpOptions;
+}): Promise<{
+    hadConnection: boolean;
+    revoked: boolean;
+}>;
+export {};

package/dist/integrations/google-auth.js

@@ -0,0 +1,157 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { z } from "zod";
+import { VageError } from "../core/errors.js";
+import { apiError, requestWithRetry } from "./http.js";
+// OAuth 2.0 for desktop apps (loopback redirect + PKCE):
+// https://developers.google.com/identity/protocols/oauth2/native-app
+const AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const REVOKE_ENDPOINT = "https://oauth2.googleapis.com/revoke";
+/** Read-only scopes: least privilege for reports. */
+export const SCOPES = {
+    gsc: "https://www.googleapis.com/auth/webmasters.readonly",
+    ga4: "https://www.googleapis.com/auth/analytics.readonly",
+};
+const storedSchema = z.object({
+    clientId: z.string(),
+    clientSecret: z.string().optional(),
+    refreshToken: z.string(),
+    scopes: z.array(z.string()),
+    createdAt: z.string(),
+});
+/** Outside any project: $VAGE_CONFIG_DIR, else the OS user config dir. Never in the repository. */
+export function credentialsPath(env = process.env) {
+    const base = env.VAGE_CONFIG_DIR ??
+        (process.platform === "win32"
+            ? path.join(env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "vagejs")
+            : path.join(env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "vagejs"));
+    return path.join(base, "google.json");
+}
+export function loadCredentials(env) {
+    const file = credentialsPath(env);
+    if (!fs.existsSync(file))
+        return undefined;
+    const parsed = storedSchema.safeParse(JSON.parse(fs.readFileSync(file, "utf8")));
+    if (!parsed.success)
+        throw new VageError(`Stored Google credentials are unreadable. Run "vage disconnect google", then connect again.`, file);
+    return parsed.data;
+}
+function saveCredentials(creds, env) {
+    const file = credentialsPath(env);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+/**
+ * Runs the browser consent flow and stores a refresh token. Previously granted
+ * scopes are requested again so connecting GA4 keeps Search Console access.
+ */
+export async function connectGoogle(options) {
+    const existing = loadCredentials(options.env);
+    const scopes = [...new Set([...(existing?.clientId === options.clientId ? existing.scopes : []), ...options.scopes])].sort();
+    const verifier = base64url(randomBytes(32));
+    const state = base64url(randomBytes(16));
+    const server = http.createServer();
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const redirectUri = `http://127.0.0.1:${server.address().port}`;
+    try {
+        const url = new URL(AUTH_ENDPOINT);
+        url.search = new URLSearchParams({
+            client_id: options.clientId,
+            redirect_uri: redirectUri,
+            response_type: "code",
+            scope: scopes.join(" "),
+            code_challenge: base64url(createHash("sha256").update(verifier).digest()),
+            code_challenge_method: "S256",
+            state,
+        }).toString();
+        const code = waitForCode(server, state, options.timeoutMs ?? 5 * 60_000);
+        options.open(url.href);
+        const authCode = await code;
+        const secrets = [options.clientSecret, authCode, verifier];
+        const body = new URLSearchParams({ code: authCode, client_id: options.clientId, redirect_uri: redirectUri, grant_type: "authorization_code", code_verifier: verifier });
+        if (options.clientSecret)
+            body.set("client_secret", options.clientSecret);
+        const res = await requestWithRetry("Google OAuth", TOKEN_ENDPOINT, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body }, secrets, options.http);
+        if (!res.ok)
+            throw await apiError("Google OAuth token exchange", res, secrets);
+        const token = z.object({ refresh_token: z.string().optional(), scope: z.string().default("") }).parse(await res.json());
+        if (!token.refresh_token)
+            throw new VageError("Google did not return a refresh token, so the connection could not be saved. Try connecting again.");
+        const granted = token.scope.split(" ");
+        const missing = scopes.filter((s) => !granted.includes(s));
+        if (missing.length)
+            throw new VageError(`Access was not granted for: ${missing.join(", ")}. Connect again and allow all requested permissions.`);
+        const creds = { clientId: options.clientId, clientSecret: options.clientSecret, refreshToken: token.refresh_token, scopes, createdAt: new Date().toISOString() };
+        saveCredentials(creds, options.env);
+        return creds;
+    }
+    finally {
+        server.close();
+    }
+}
+function waitForCode(server, state, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new VageError("Timed out waiting for Google authorization. Run the command again.")), timeoutMs);
+        server.on("request", (req, res) => {
+            const params = new URL(req.url ?? "/", "http://127.0.0.1").searchParams;
+            const finish = (status, text) => {
+                res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+                res.end(text);
+            };
+            if (!params.has("code") && !params.has("error"))
+                return finish(404, "Not found");
+            if (params.get("state") !== state)
+                return finish(400, "State mismatch; ignoring this request.");
+            clearTimeout(timer);
+            if (params.get("error")) {
+                finish(200, "Authorization was not granted. You can close this tab.");
+                return reject(new VageError(`Google authorization was not granted (${params.get("error")}).`));
+            }
+            finish(200, "vagejs is connected. You can close this tab.");
+            resolve(params.get("code"));
+        });
+    });
+}
+/** Exchanges the stored refresh token for a short-lived access token. */
+export async function getAccessToken(scope, service, options = {}) {
+    const creds = loadCredentials(options.env);
+    if (!creds)
+        throw new VageError(`Not connected to Google. Run "vage connect ${service}".`);
+    if (!creds.scopes.includes(scope))
+        throw new VageError(`The Google connection does not include ${service} access. Run "vage connect ${service}".`);
+    const secrets = [creds.refreshToken, creds.clientSecret];
+    const body = new URLSearchParams({ client_id: creds.clientId, refresh_token: creds.refreshToken, grant_type: "refresh_token" });
+    if (creds.clientSecret)
+        body.set("client_secret", creds.clientSecret);
+    const res = await requestWithRetry("Google OAuth", TOKEN_ENDPOINT, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body }, secrets, options.http);
+    if (res.status === 400 || res.status === 401) {
+        throw new VageError(`The Google connection has expired or was revoked. Run "vage connect ${service}" again.`);
+    }
+    if (!res.ok)
+        throw await apiError("Google OAuth token refresh", res, secrets);
+    return z.object({ access_token: z.string() }).parse(await res.json()).access_token;
+}
+/** Revokes the refresh token at Google and deletes the local file (even if revocation fails). */
+export async function disconnectGoogle(options = {}) {
+    const creds = loadCredentials(options.env);
+    if (!creds)
+        return { hadConnection: false, revoked: false };
+    let revoked = false;
+    try {
+        const res = await requestWithRetry("Google OAuth", REVOKE_ENDPOINT, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ token: creds.refreshToken }) }, [creds.refreshToken], options.http);
+        revoked = res.ok;
+    }
+    catch {
+        // Network failure: still remove the local token; the caller reports that revocation did not happen.
+    }
+    fs.rmSync(credentialsPath(options.env), { force: true });
+    return { hadConnection: true, revoked };
+}
+function base64url(buf) {
+    return buf.toString("base64url");
+}

package/dist/integrations/http.d.ts

@@ -0,0 +1,15 @@
+import { VageError } from "../core/errors.js";
+export interface HttpOptions {
+    fetch?: typeof fetch;
+    /** Waits between retries; injectable for tests. */
+    sleep?: (ms: number) => Promise<void>;
+    attempts?: number;
+}
+/**
+ * Fetch with retries for rate limits and transient errors (exponential
+ * backoff: 1 s, 2 s, ...). Every value in `secrets` is scrubbed from error text.
+ */
+export declare function requestWithRetry(service: string, url: string, init: RequestInit, secrets: (string | undefined)[], opts?: HttpOptions): Promise<Response>;
+/** Builds an actionable error from a non-OK Google API response. */
+export declare function apiError(service: string, res: Response, secrets: (string | undefined)[], hints?: Partial<Record<number, string>>): Promise<VageError>;
+export declare function redact(text: string, secrets: (string | undefined)[]): string;

package/dist/integrations/http.js

@@ -0,0 +1,40 @@
+import { VageError } from "../core/errors.js";
+const RETRY_STATUS = new Set([429, 500, 502, 503, 504]);
+/**
+ * Fetch with retries for rate limits and transient errors (exponential
+ * backoff: 1 s, 2 s, ...). Every value in `secrets` is scrubbed from error text.
+ */
+export async function requestWithRetry(service, url, init, secrets, opts = {}) {
+    const doFetch = opts.fetch ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const attempts = opts.attempts ?? 3;
+    for (let i = 1;; i++) {
+        try {
+            const res = await doFetch(url, { ...init, signal: AbortSignal.timeout(120_000) });
+            if (res.ok || !RETRY_STATUS.has(res.status) || i === attempts)
+                return res;
+        }
+        catch (err) {
+            if (i === attempts)
+                throw new VageError(redact(`${service} request failed after ${attempts} attempts: ${err.message}`, secrets));
+        }
+        await sleep(1000 * 2 ** (i - 1));
+    }
+}
+/** Builds an actionable error from a non-OK Google API response. */
+export async function apiError(service, res, secrets, hints = {}) {
+    let detail = "";
+    try {
+        // Google APIs use { error: { message } }; the OAuth endpoints use { error, error_description }.
+        const body = (await res.json());
+        detail = body.error_description ?? (typeof body.error === "string" ? body.error : (body.error?.message ?? ""));
+    }
+    catch {
+        // Non-JSON error body; the status is enough.
+    }
+    const hint = hints[res.status] ?? (res.status === 429 ? "Rate limited: wait and retry." : "");
+    return new VageError(redact(`${service} returned HTTP ${res.status}${detail ? `: ${detail.replace(/\.+$/, "")}` : ""}.${hint ? ` ${hint}` : ""}`, secrets));
+}
+export function redact(text, secrets) {
+    return secrets.filter((s) => Boolean(s && s.length >= 4)).reduce((t, s) => t.split(s).join("[redacted]"), text);
+}

package/dist/integrations/indexnow.d.ts

@@ -0,0 +1,18 @@
+import { type HttpOptions } from "./http.js";
+export interface IndexNowResult {
+    endpoint: string;
+    submitted: number;
+    /** 200 = accepted; 202 = received, key validation pending. */
+    status: number;
+}
+/**
+ * Notifies IndexNow-participating search engines that URLs changed. A hint,
+ * not a guarantee of crawling or indexing. The key file must already be live.
+ */
+export declare function submitIndexNow(options: {
+    site: string;
+    key: string;
+    endpoint: string;
+    urls: string[];
+    http?: HttpOptions;
+}): Promise<IndexNowResult>;

package/dist/integrations/indexnow.js

@@ -0,0 +1,38 @@
+import { VageError } from "../core/errors.js";
+import { ruleData } from "../guidelines/pack.js";
+import { apiError, requestWithRetry } from "./http.js";
+// https://www.indexnow.org/documentation (rule pack "indexnow.protocol")
+const { maxUrls } = ruleData("indexnow.protocol");
+/**
+ * Notifies IndexNow-participating search engines that URLs changed. A hint,
+ * not a guarantee of crawling or indexing. The key file must already be live.
+ */
+export async function submitIndexNow(options) {
+    const { site, key, endpoint, http } = options;
+    const host = new URL(site).host;
+    const urls = [...new Set(options.urls)];
+    if (!urls.length)
+        throw new VageError("No URLs to submit.");
+    const foreign = urls.filter((u) => new URL(u).host !== host);
+    if (foreign.length)
+        throw new VageError(`IndexNow only accepts URLs on ${host}: ${foreign.slice(0, 3).join(", ")}`);
+    if (urls.length > maxUrls)
+        throw new VageError(`IndexNow accepts at most ${maxUrls} URLs per request; got ${urls.length}.`);
+    // Without a live key file the endpoint answers 403; check first for a clearer message.
+    const keyLocation = `${new URL(site).origin}/${key}.txt`;
+    const doFetch = http?.fetch ?? fetch;
+    const live = await doFetch(keyLocation, { signal: AbortSignal.timeout(30_000) }).catch(() => undefined);
+    if (!live?.ok || (await live.text()).trim() !== key) {
+        throw new VageError(`The key file ${keyLocation} is not live yet. Deploy the site (it is generated by vage build), then submit.`);
+    }
+    const res = await requestWithRetry("IndexNow", endpoint, { method: "POST", headers: { "content-type": "application/json; charset=utf-8" }, body: JSON.stringify({ host, key, keyLocation, urlList: urls }) }, [], { ...http, attempts: 1 });
+    if (res.status !== 200 && res.status !== 202) {
+        throw await apiError("IndexNow", res, [], {
+            400: "The request was malformed.",
+            403: "The key is not valid: the key file was not found or doesn't contain the key.",
+            422: "The URLs don't belong to the host, or the key doesn't match.",
+            429: "Too many requests; IndexNow may treat this as spam. Submit only changed URLs, less often.",
+        });
+    }
+    return { endpoint, submitted: urls.length, status: res.status };
+}

package/dist/integrations/search-console.d.ts

@@ -0,0 +1,25 @@
+import { type HttpOptions } from "./http.js";
+export interface SearchRow {
+    key: string;
+    clicks: number;
+    impressions: number;
+    ctr: number;
+    position: number;
+}
+export interface SearchReport {
+    property: string;
+    startDate: string;
+    endDate: string;
+    queries: SearchRow[];
+    pages: SearchRow[];
+}
+export declare function listSites(token: string, opts?: HttpOptions): Promise<{
+    siteUrl: string;
+    permissionLevel: string;
+}[]>;
+/** Top queries and pages for the last `days` days (Pacific Time dates, finalized data only). */
+export declare function searchReport(token: string, property: string, days: number, opts?: HttpOptions & {
+    now?: Date;
+}): Promise<SearchReport>;
+/** YYYY-MM-DD in America/Los_Angeles, `daysBack` days before `now`. Search Console dates are Pacific Time. */
+export declare function pacificDate(now: Date, daysBack: number): string;

package/dist/integrations/search-console.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { apiError, requestWithRetry } from "./http.js";
+// https://developers.google.com/webmaster-tools/v1/searchanalytics/query
+const API = "https://www.googleapis.com/webmasters/v3";
+const auth = (token) => ({ authorization: `Bearer ${token}` });
+export async function listSites(token, opts) {
+    const res = await requestWithRetry("Search Console API", `${API}/sites`, { headers: auth(token) }, [token], opts);
+    if (!res.ok)
+        throw await apiError("Search Console API", res, [token]);
+    const body = z.object({ siteEntry: z.array(z.object({ siteUrl: z.string(), permissionLevel: z.string() })).default([]) }).parse(await res.json());
+    return body.siteEntry;
+}
+const rowsSchema = z.object({
+    rows: z
+        .array(z.object({ keys: z.array(z.string()), clicks: z.number(), impressions: z.number(), ctr: z.number(), position: z.number() }))
+        .default([]),
+});
+/** Top queries and pages for the last `days` days (Pacific Time dates, finalized data only). */
+export async function searchReport(token, property, days, opts = {}) {
+    const endDate = pacificDate(opts.now ?? new Date(), 0);
+    const startDate = pacificDate(opts.now ?? new Date(), days - 1);
+    const query = async (dimension) => {
+        const res = await requestWithRetry("Search Console API", `${API}/sites/${encodeURIComponent(property)}/searchAnalytics/query`, { method: "POST", headers: { ...auth(token), "content-type": "application/json" }, body: JSON.stringify({ startDate, endDate, dimensions: [dimension], rowLimit: 25 }) }, [token], opts);
+        if (!res.ok) {
+            throw await apiError("Search Console API", res, [token], {
+                403: `No access to ${property}. Check the property name with "vage connect gsc" and that your Google account can view it.`,
+            });
+        }
+        return rowsSchema.parse(await res.json()).rows.map(({ keys, ...m }) => ({ key: keys[0] ?? "", ...m }));
+    };
+    return { property, startDate, endDate, queries: await query("query"), pages: await query("page") };
+}
+/** YYYY-MM-DD in America/Los_Angeles, `daysBack` days before `now`. Search Console dates are Pacific Time. */
+export function pacificDate(now, daysBack) {
+    const today = new Intl.DateTimeFormat("en-CA", { timeZone: "America/Los_Angeles" }).format(now);
+    const d = new Date(`${today}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() - daysBack);
+    return d.toISOString().slice(0, 10);
+}

package/dist/integrations/tags.d.ts

@@ -0,0 +1,22 @@
+import type { SiteConfig } from "../core/config.js";
+/**
+ * Analytics tags for production builds.
+ *
+ * - Google (GA4 or GTM): consent defaults are set before any measurement command
+ *   (https://developers.google.com/tag-platform/security/guides/consent), and nothing
+ *   loads on localhost, so `vage preview` sends no hits.
+ * - Plausible / Clarity: the owner's dashboard snippet, inserted verbatim (vagejs
+ *   can't suppress those on localhost).
+ * - window.vageConsent.update({ analytics_storage, ad_storage }) forwards consent to
+ *   Google (consent update) and Clarity (consentv2). Sites provide their own consent UI.
+ * - One click listener sends data-vage-event / data-vage-param-* to every configured provider.
+ */
+export declare function analyticsTags(site: SiteConfig): {
+    head: string;
+    bodyStart?: string;
+} | undefined;
+/** Puts the tags first in <head> (before other scripts) and the GTM noscript right after <body>. */
+export declare function injectAnalytics(html: string, tags: {
+    head: string;
+    bodyStart?: string;
+}, file: string): string;

package/dist/integrations/tags.js

@@ -0,0 +1,67 @@
+import { VageError } from "../core/errors.js";
+import { ruleData } from "../guidelines/pack.js";
+const CONSENT_TYPES = ruleData("consent.default-order").types;
+const LOCAL_HOST = String.raw `/^(localhost|127\.0\.0\.1|\[::1\])$/`;
+/**
+ * Analytics tags for production builds.
+ *
+ * - Google (GA4 or GTM): consent defaults are set before any measurement command
+ *   (https://developers.google.com/tag-platform/security/guides/consent), and nothing
+ *   loads on localhost, so `vage preview` sends no hits.
+ * - Plausible / Clarity: the owner's dashboard snippet, inserted verbatim (vagejs
+ *   can't suppress those on localhost).
+ * - window.vageConsent.update({ analytics_storage, ad_storage }) forwards consent to
+ *   Google (consent update) and Clarity (consentv2). Sites provide their own consent UI.
+ * - One click listener sends data-vage-event / data-vage-param-* to every configured provider.
+ */
+export function analyticsTags(site) {
+    const { ga4, gtm, plausible, clarity } = site.integrations;
+    const google = ga4?.measurementId ? { kind: "ga4", id: ga4.measurementId, consent: ga4.consentDefault } : gtm?.containerId ? { kind: "gtm", id: gtm.containerId, consent: gtm.consentDefault } : undefined;
+    if (!google && !plausible && !clarity)
+        return undefined;
+    const parts = [];
+    let bodyStart;
+    const send = [];
+    if (google) {
+        const id = JSON.stringify(google.id);
+        let body = `window.dataLayer=window.dataLayer||[];window.gtag=function(){dataLayer.push(arguments)};` +
+            `gtag("consent","default",${JSON.stringify(Object.fromEntries(CONSENT_TYPES.map((t) => [t, google.consent])))});`;
+        if (google.kind === "ga4") {
+            body += `gtag("js",new Date());gtag("config",${id});` + loadScript(`"https://www.googletagmanager.com/gtag/js?id="+${id}`);
+            send.push(`if(window.gtag)gtag("event",n,p);`);
+        }
+        else {
+            body += `dataLayer.push({"gtm.start":new Date().getTime(),event:"gtm.js"});` + loadScript(`"https://www.googletagmanager.com/gtm.js?id="+${id}`);
+            send.push(`if(window.dataLayer){var d={event:n};for(var k in p)d[k]=p[k];dataLayer.push(d)}`);
+            bodyStart = `<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(google.id)}" height="0" width="0" style="display:none;visibility:hidden" title="Google Tag Manager"></iframe></noscript>`;
+        }
+        parts.push(`<script>if(!${LOCAL_HOST}.test(location.hostname)){${body}}</script>`);
+    }
+    if (plausible) {
+        parts.push(plausible.snippet.trim());
+        send.push(`if(window.plausible)plausible(n,{props:p});`);
+    }
+    if (clarity)
+        parts.push(clarity.snippet.trim());
+    // Consent bridge and event listener; safe when a provider failed to load.
+    parts.push(`<script>(function(){var s={};window.vageConsent={update:function(c){for(var k in c)s[k]=c[k];` +
+        `if(window.gtag)gtag("consent","update",c);` +
+        `if(window.clarity)clarity("consentv2",{ad_Storage:s.ad_storage||"denied",analytics_Storage:s.analytics_storage||"denied"})}};` +
+        `document.addEventListener("click",function(e){var el=e.target&&e.target.closest&&e.target.closest("[data-vage-event]");if(!el)return;` +
+        `var n=el.getAttribute("data-vage-event"),p={};for(var i=0;i<el.attributes.length;i++){var a=el.attributes[i];` +
+        `if(a.name.indexOf("data-vage-param-")===0)p[a.name.slice(16).replace(/-/g,"_")]=a.value}${send.join("")}})})();</script>`);
+    return { head: parts.join("\n    "), bodyStart };
+}
+function loadScript(src) {
+    return `var s=document.createElement("script");s.async=true;s.src=${src};document.head.appendChild(s);`;
+}
+/** Puts the tags first in <head> (before other scripts) and the GTM noscript right after <body>. */
+export function injectAnalytics(html, tags, file) {
+    const head = /<head[^>]*>/i.exec(html);
+    if (!head)
+        throw new VageError("Layout output has no <head>; it is needed for analytics tags.", file);
+    let out = html.slice(0, head.index + head[0].length) + `\n    ${tags.head}` + html.slice(head.index + head[0].length);
+    if (tags.bodyStart)
+        out = out.replace(/<body[^>]*>/i, (m) => `${m}\n    ${tags.bodyStart}`);
+    return out;
+}

package/dist/seo/head.d.ts

@@ -0,0 +1,20 @@
+import type { Frontmatter } from "../content/markdown.js";
+import type { SiteConfig } from "../core/config.js";
+export interface PageMeta {
+    route: string;
+    frontmatter: Frontmatter;
+    /** Absolute canonical URL, when `site` is configured and the page is indexable. */
+    canonical?: string;
+    noindex: boolean;
+}
+export declare function pageMeta(site: SiteConfig, route: string, frontmatter: Frontmatter, notFound?: boolean): PageMeta;
+interface Tag {
+    /** Matches an equivalent tag the layout already wrote; if found, ours is skipped. */
+    exists: RegExp;
+    html: string;
+}
+/** Builds the SEO tags for a page. Tags are omitted when their data is unknown; nothing is invented. */
+export declare function headTags(site: SiteConfig, m: PageMeta): Tag[];
+/** Inserts tags before </head>, skipping any the layout already provides. */
+export declare function injectHead(html: string, tags: Tag[], file: string): string;
+export {};