vagejs 0.0.0-stage → 0.1.0

package/dist/guidelines/rule-pack.json

@@ -0,0 +1,611 @@
+{
+    "version": "2026.10.0",
+    "released": "2026-10-23",
+    "sources": [
+        {
+            "id": "google-search-essentials",
+            "provider": "Google",
+            "title": "Google Search Essentials",
+            "url": "https://developers.google.com/search/docs/essentials",
+            "category": "search",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-robots",
+            "provider": "Google",
+            "title": "Introduction to robots.txt",
+            "url": "https://developers.google.com/search/docs/crawling-indexing/robots/intro",
+            "category": "crawling",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-crawlers",
+            "provider": "Google",
+            "title": "Google's common crawlers (incl. Google-Extended)",
+            "url": "https://developers.google.com/crawling/docs/crawlers-fetchers/google-common-crawlers",
+            "category": "ai-crawlers",
+            "cadence": "daily"
+        },
+        {
+            "id": "google-sitemaps",
+            "provider": "Google",
+            "title": "Build and submit a sitemap",
+            "url": "https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap",
+            "category": "crawling",
+            "cadence": "weekly"
+        },
+        {
+            "id": "sitemaps-protocol",
+            "provider": "sitemaps.org",
+            "title": "Sitemaps XML format",
+            "url": "https://www.sitemaps.org/protocol.html",
+            "category": "crawling",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-canonical",
+            "provider": "Google",
+            "title": "Consolidate duplicate URLs",
+            "url": "https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls",
+            "category": "search",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-sd-policies",
+            "provider": "Google",
+            "title": "Structured data general guidelines",
+            "url": "https://developers.google.com/search/docs/appearance/structured-data/sd-policies",
+            "category": "structured-data",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-article",
+            "provider": "Google",
+            "title": "Article structured data",
+            "url": "https://developers.google.com/search/docs/appearance/structured-data/article",
+            "category": "structured-data",
+            "cadence": "weekly"
+        },
+        {
+            "id": "schema-org",
+            "provider": "Schema.org",
+            "title": "Schema.org documents",
+            "url": "https://schema.org/docs/documents.html",
+            "category": "structured-data",
+            "cadence": "weekly"
+        },
+        {
+            "id": "openai-bots",
+            "provider": "OpenAI",
+            "title": "Overview of OpenAI crawlers",
+            "url": "https://developers.openai.com/api/docs/bots",
+            "category": "ai-crawlers",
+            "cadence": "daily"
+        },
+        {
+            "id": "anthropic-crawlers",
+            "provider": "Anthropic",
+            "title": "Does Anthropic crawl data from the web?",
+            "url": "https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler",
+            "category": "ai-crawlers",
+            "cadence": "daily"
+        },
+        {
+            "id": "llms-txt",
+            "provider": "llmstxt.org",
+            "title": "The /llms.txt file (proposal)",
+            "url": "https://llmstxt.org/",
+            "category": "ai-discovery",
+            "cadence": "weekly"
+        },
+        {
+            "id": "web-vitals",
+            "provider": "Google (web.dev)",
+            "title": "Web Vitals",
+            "url": "https://web.dev/articles/vitals",
+            "category": "performance",
+            "cadence": "weekly"
+        },
+        {
+            "id": "psi-api",
+            "provider": "Google",
+            "title": "PageSpeed Insights API: get started",
+            "url": "https://developers.google.com/speed/docs/insights/v5/get-started",
+            "category": "performance",
+            "cadence": "weekly"
+        },
+        {
+            "id": "crux-api",
+            "provider": "Google (Chrome)",
+            "title": "CrUX API",
+            "url": "https://developer.chrome.com/docs/crux/api",
+            "category": "performance",
+            "cadence": "weekly"
+        },
+        {
+            "id": "w3c-wai",
+            "provider": "W3C",
+            "title": "W3C Accessibility Standards Overview",
+            "url": "https://www.w3.org/WAI/standards-guidelines/",
+            "category": "accessibility",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-consent",
+            "provider": "Google",
+            "title": "Set up consent mode on websites",
+            "url": "https://developers.google.com/tag-platform/security/guides/consent",
+            "category": "privacy",
+            "cadence": "weekly"
+        },
+        {
+            "id": "ga4-event-naming",
+            "provider": "Google",
+            "title": "[GA4] Event naming rules",
+            "url": "https://support.google.com/analytics/answer/13316687",
+            "category": "analytics",
+            "cadence": "weekly"
+        },
+        {
+            "id": "ga4-limits",
+            "provider": "Google",
+            "title": "[GA4] Event collection limits",
+            "url": "https://support.google.com/analytics/answer/9267744",
+            "category": "analytics",
+            "cadence": "weekly"
+        },
+        {
+            "id": "ga4-runreport",
+            "provider": "Google",
+            "title": "GA4 Data API: properties.runReport",
+            "url": "https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport",
+            "category": "analytics",
+            "cadence": "weekly"
+        },
+        {
+            "id": "gsc-searchanalytics",
+            "provider": "Google",
+            "title": "Search Console API: searchanalytics.query",
+            "url": "https://developers.google.com/webmaster-tools/v1/searchanalytics/query",
+            "category": "search-console",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-oauth-native",
+            "provider": "Google",
+            "title": "OAuth 2.0 for iOS & desktop apps",
+            "url": "https://developers.google.com/identity/protocols/oauth2/native-app",
+            "category": "auth",
+            "cadence": "weekly"
+        },
+        {
+            "id": "gh-pages-workflows",
+            "provider": "GitHub",
+            "title": "Using custom workflows with GitHub Pages",
+            "url": "https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages",
+            "category": "hosting",
+            "cadence": "weekly"
+        },
+        {
+            "id": "gh-pages-custom-domain",
+            "provider": "GitHub",
+            "title": "Managing a custom domain for your GitHub Pages site",
+            "url": "https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site",
+            "category": "hosting",
+            "cadence": "weekly"
+        },
+        {
+            "id": "bing-guidelines",
+            "provider": "Microsoft",
+            "title": "Bing Webmaster Guidelines",
+            "url": "https://www.bing.com/webmasters/help/webmaster-guidelines-30fba23a",
+            "category": "search",
+            "cadence": "weekly",
+            "monitor": "manual"
+        },
+        {
+            "id": "indexnow",
+            "provider": "IndexNow",
+            "title": "IndexNow documentation",
+            "url": "https://www.indexnow.org/documentation",
+            "category": "search",
+            "cadence": "weekly"
+        },
+        {
+            "id": "indexnow-faq",
+            "provider": "IndexNow",
+            "title": "IndexNow FAQ",
+            "url": "https://www.indexnow.org/faq",
+            "category": "search",
+            "cadence": "weekly"
+        },
+        {
+            "id": "clarity-consent",
+            "provider": "Microsoft",
+            "title": "Clarity Cookie Consent API - ConsentV2",
+            "url": "https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-consent-api-v2",
+            "category": "privacy",
+            "cadence": "weekly"
+        },
+        {
+            "id": "plausible-events",
+            "provider": "Plausible",
+            "title": "Custom event goals",
+            "url": "https://plausible.io/docs/custom-event-goals",
+            "category": "analytics",
+            "cadence": "weekly"
+        },
+        {
+            "id": "cloudflare-redirects",
+            "provider": "Cloudflare",
+            "title": "Pages: redirects (_redirects)",
+            "url": "https://developers.cloudflare.com/pages/configuration/redirects/",
+            "category": "hosting",
+            "cadence": "weekly"
+        },
+        {
+            "id": "google-csp",
+            "provider": "Google",
+            "title": "Use a Content Security Policy with Google tags",
+            "url": "https://developers.google.com/tag-platform/security/guides/csp",
+            "category": "security",
+            "cadence": "weekly"
+        },
+        {
+            "id": "clarity-csp",
+            "provider": "Microsoft",
+            "title": "Clarity Content Security Policy",
+            "url": "https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-csp",
+            "category": "security",
+            "cadence": "weekly"
+        },
+        {
+            "id": "cloudflare-headers",
+            "provider": "Cloudflare",
+            "title": "Pages: headers (_headers)",
+            "url": "https://developers.cloudflare.com/pages/configuration/headers/",
+            "category": "hosting",
+            "cadence": "weekly"
+        }
+    ],
+    "rules": [
+        {
+            "id": "robots.ai-crawlers",
+            "summary": "robots.txt tokens for AI crawlers, split into training vs search. Only documented robots.txt-honoring tokens; user-initiated fetchers excluded.",
+            "behaviorChanging": true,
+            "sources": [
+                "openai-bots",
+                "anthropic-crawlers",
+                "google-crawlers"
+            ],
+            "implementedIn": [
+                "src/discovery/crawlers.ts",
+                "src/discovery/robots.ts"
+            ],
+            "data": {
+                "crawlers": [
+                    {
+                        "token": "GPTBot",
+                        "provider": "OpenAI",
+                        "purpose": "training",
+                        "source": "openai-bots"
+                    },
+                    {
+                        "token": "OAI-SearchBot",
+                        "provider": "OpenAI",
+                        "purpose": "search",
+                        "source": "openai-bots"
+                    },
+                    {
+                        "token": "ClaudeBot",
+                        "provider": "Anthropic",
+                        "purpose": "training",
+                        "source": "anthropic-crawlers"
+                    },
+                    {
+                        "token": "Claude-SearchBot",
+                        "provider": "Anthropic",
+                        "purpose": "search",
+                        "source": "anthropic-crawlers"
+                    },
+                    {
+                        "token": "Google-Extended",
+                        "provider": "Google",
+                        "purpose": "training",
+                        "source": "google-crawlers"
+                    }
+                ]
+            }
+        },
+        {
+            "id": "sitemap.limits",
+            "summary": "Maximum URLs per sitemap file.",
+            "behaviorChanging": true,
+            "sources": [
+                "google-sitemaps",
+                "sitemaps-protocol"
+            ],
+            "implementedIn": [
+                "src/discovery/sitemap.ts"
+            ],
+            "data": {
+                "maxUrls": 50000
+            }
+        },
+        {
+            "id": "vitals.thresholds",
+            "summary": "Core Web Vitals good / poor thresholds at the 75th percentile.",
+            "behaviorChanging": true,
+            "sources": [
+                "web-vitals"
+            ],
+            "implementedIn": [
+                "src/audit/vitals.ts"
+            ],
+            "data": {
+                "lcp": {
+                    "good": 2500,
+                    "poor": 4000
+                },
+                "inp": {
+                    "good": 200,
+                    "poor": 500
+                },
+                "cls": {
+                    "good": 0.1,
+                    "poor": 0.25
+                }
+            }
+        },
+        {
+            "id": "ga4.naming",
+            "summary": "GA4 event and parameter naming rules and length limits.",
+            "behaviorChanging": true,
+            "sources": [
+                "ga4-event-naming",
+                "ga4-limits"
+            ],
+            "implementedIn": [
+                "src/core/config.ts"
+            ],
+            "data": {
+                "maxNameLength": 40,
+                "reservedParamPrefixes": [
+                    "_",
+                    "firebase_",
+                    "ga_",
+                    "google_",
+                    "gtag."
+                ]
+            }
+        },
+        {
+            "id": "consent.default-order",
+            "summary": "Consent defaults are set before any measurement command; four consent types.",
+            "behaviorChanging": true,
+            "sources": [
+                "google-consent"
+            ],
+            "implementedIn": [
+                "src/integrations/tags.ts"
+            ],
+            "data": {
+                "types": [
+                    "ad_storage",
+                    "ad_user_data",
+                    "ad_personalization",
+                    "analytics_storage"
+                ]
+            }
+        },
+        {
+            "id": "seo.canonical-and-structured-data",
+            "summary": "Absolute canonical URLs; structured data must match visible content; Article recommended properties.",
+            "behaviorChanging": false,
+            "sources": [
+                "google-canonical",
+                "google-sd-policies",
+                "google-article",
+                "schema-org"
+            ],
+            "implementedIn": [
+                "src/seo/head.ts",
+                "src/checks/check.ts"
+            ]
+        },
+        {
+            "id": "llms-txt.format",
+            "summary": "llms.txt layout (H1 title, blockquote summary, link sections). An emerging convention.",
+            "behaviorChanging": false,
+            "sources": [
+                "llms-txt"
+            ],
+            "implementedIn": [
+                "src/discovery/llms.ts"
+            ]
+        },
+        {
+            "id": "audit.field-data-source",
+            "summary": "Field data from the CrUX API (PSI field data is planned for discontinuation); lab data from PageSpeed Insights.",
+            "behaviorChanging": false,
+            "sources": [
+                "psi-api",
+                "crux-api"
+            ],
+            "implementedIn": [
+                "src/audit/remote.ts"
+            ]
+        },
+        {
+            "id": "accessibility.baseline",
+            "summary": "Automated accessibility rules (axe-core) as a baseline, not WCAG conformance.",
+            "behaviorChanging": false,
+            "sources": [
+                "w3c-wai"
+            ],
+            "implementedIn": [
+                "src/audit/a11y.ts",
+                "src/checks/check.ts"
+            ]
+        },
+        {
+            "id": "google-apis.reporting",
+            "summary": "Desktop OAuth (loopback + PKCE) with read-only scopes; Search Analytics and GA4 runReport request shapes.",
+            "behaviorChanging": false,
+            "sources": [
+                "google-oauth-native",
+                "gsc-searchanalytics",
+                "ga4-runreport"
+            ],
+            "implementedIn": [
+                "src/integrations/google-auth.ts",
+                "src/integrations/search-console.ts",
+                "src/integrations/ga4-data.ts"
+            ]
+        },
+        {
+            "id": "hosting.github-pages",
+            "summary": "GitHub Pages via Actions: permissions, environment, artifact; CNAME not required.",
+            "behaviorChanging": true,
+            "sources": [
+                "gh-pages-workflows",
+                "gh-pages-custom-domain"
+            ],
+            "implementedIn": [
+                "src/deploy/github-pages.ts"
+            ]
+        },
+        {
+            "id": "search.general",
+            "summary": "General search guidance tracked for future rules.",
+            "behaviorChanging": false,
+            "sources": [
+                "google-search-essentials",
+                "google-robots",
+                "bing-guidelines"
+            ],
+            "implementedIn": []
+        },
+        {
+            "id": "indexnow.protocol",
+            "summary": "IndexNow submission: shared endpoint, up to 10,000 URLs per request, key 8-128 chars served at /<key>.txt; 200/202 accepted.",
+            "behaviorChanging": true,
+            "sources": [
+                "indexnow",
+                "indexnow-faq"
+            ],
+            "implementedIn": [
+                "src/integrations/indexnow.ts"
+            ],
+            "data": {
+                "endpoint": "https://api.indexnow.org/indexnow",
+                "maxUrls": 10000,
+                "keyPattern": "^[A-Za-z0-9-]{8,128}$"
+            }
+        },
+        {
+            "id": "clarity.consent",
+            "summary": "Clarity consent via consentv2 with ad_Storage / analytics_Storage.",
+            "behaviorChanging": true,
+            "sources": [
+                "clarity-consent"
+            ],
+            "implementedIn": [
+                "src/integrations/tags.ts"
+            ]
+        },
+        {
+            "id": "plausible.events",
+            "summary": "Plausible custom events: plausible(name, { props }).",
+            "behaviorChanging": false,
+            "sources": [
+                "plausible-events"
+            ],
+            "implementedIn": [
+                "src/integrations/tags.ts"
+            ]
+        },
+        {
+            "id": "cloudflare.redirects",
+            "summary": "_redirects format 'source destination status', up to 2,000 static rules.",
+            "behaviorChanging": true,
+            "sources": [
+                "cloudflare-redirects"
+            ],
+            "implementedIn": [
+                "src/deploy/cloudflare-pages.ts"
+            ],
+            "data": {
+                "maxStaticRules": 2000
+            }
+        },
+        {
+            "id": "csp.providers",
+            "summary": "CSP sources required by analytics providers (GA4 without Ads features, Tag Manager, Clarity).",
+            "behaviorChanging": true,
+            "sources": [
+                "google-csp",
+                "clarity-csp"
+            ],
+            "implementedIn": [
+                "src/deploy/headers.ts"
+            ],
+            "data": {
+                "google": {
+                    "script-src": [
+                        "https://www.googletagmanager.com"
+                    ],
+                    "connect-src": [
+                        "https://www.googletagmanager.com",
+                        "https://*.google-analytics.com",
+                        "https://*.google.com"
+                    ],
+                    "img-src": [
+                        "https://www.googletagmanager.com",
+                        "https://*.google-analytics.com"
+                    ],
+                    "frame-src": [
+                        "https://www.googletagmanager.com"
+                    ]
+                },
+                "clarity": {
+                    "script-src": [
+                        "https://*.clarity.ms",
+                        "https://c.bing.com"
+                    ],
+                    "connect-src": [
+                        "https://*.clarity.ms",
+                        "https://c.bing.com"
+                    ],
+                    "img-src": [
+                        "https://*.clarity.ms",
+                        "https://c.bing.com"
+                    ]
+                }
+            }
+        },
+        {
+            "id": "cloudflare.headers",
+            "summary": "_headers format; up to 100 rules, 2,000 characters per line.",
+            "behaviorChanging": true,
+            "sources": [
+                "cloudflare-headers"
+            ],
+            "implementedIn": [
+                "src/deploy/headers.ts"
+            ],
+            "data": {
+                "maxLineLength": 2000
+            }
+        }
+    ],
+    "changelog": [
+        {
+            "version": "2026.10.0",
+            "date": "2026-10-23",
+            "summary": "Initial rule pack (unreleased; extended during Phase 8 and the security review with IndexNow, Clarity, Plausible, Cloudflare Pages and CSP provider rules). Facts checked against the cited sources on 2026-10-23 during implementation.",
+            "reviewedBy": "A G E Venkatesh",
+            "contentHash": "8c7272511f733c01984ce1d962b39e2d521a88b31a5c958a95307a04b82bb3dd"
+        }
+    ]
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { defineConfig, type SiteConfig, type UserConfig } from "./core/config.js";
+export { escapeHtml } from "./core/html.js";
+export type { Layout, LayoutProps } from "./core/render.js";
+export type { Frontmatter } from "./content/markdown.js";
+export { build, type BuildResult } from "./core/build.js";
+export { startDevServer } from "./dev/server.js";
+export { startPreviewServer } from "./dev/preview.js";
+export { VageError } from "./core/errors.js";
+export { check, type CheckResult, type Finding } from "./checks/check.js";
+export { article, breadcrumbList, jsonLdScript, organization, website, type Thing } from "./seo/jsonld.js";
+export { AI_CRAWLERS, type CrawlerToken } from "./discovery/crawlers.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { defineConfig } from "./core/config.js";
+export { escapeHtml } from "./core/html.js";
+export { build } from "./core/build.js";
+export { startDevServer } from "./dev/server.js";
+export { startPreviewServer } from "./dev/preview.js";
+export { VageError } from "./core/errors.js";
+export { check } from "./checks/check.js";
+export { article, breadcrumbList, jsonLdScript, organization, website } from "./seo/jsonld.js";
+export { AI_CRAWLERS } from "./discovery/crawlers.js";

package/dist/integrations/api-keys.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The user's own Google Cloud API keys for audits. VAGE JS 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 declare const API_KEYS: {
+    readonly pagespeed: {
+        readonly env: "PAGESPEED_API_KEY";
+        readonly label: "PageSpeed Insights API";
+        readonly howTo: "Google Cloud Console → APIs & Services → enable “PageSpeed Insights API” → Credentials → Create credentials → API key (restrict it to that API).";
+    };
+    readonly crux: {
+        readonly env: "CRUX_API_KEY";
+        readonly label: "Chrome UX Report (CrUX) API";
+        readonly howTo: "Google Cloud Console → APIs & Services → enable “Chrome UX Report API” → Credentials → Create credentials → API key (one key can serve both APIs).";
+    };
+};
+export type ApiKeyName = keyof typeof API_KEYS;
+type Env = Record<string, string | undefined>;
+export declare function apiKeysPath(env?: Env): string;
+/** Environment variable first, then the key saved with `vage connect`. */
+export declare function resolveApiKey(name: ApiKeyName, env?: Env): string | undefined;
+export declare function saveApiKey(name: ApiKeyName, value: string, env?: Env): string;
+export declare function removeApiKey(name: ApiKeyName, env?: Env): boolean;
+export declare function missingKeyMessage(name: ApiKeyName): string;
+export {};