feat(docs): add analytics and mcp version widget

.github/workflows/pages.yml

@@ -43,6 +43,9 @@ jobs:
         env:
           GITTENSORY_SITE_URL: https://gittensory.aethereal.dev/
           GITTENSORY_SITE_BASE: /
+          GITTENSORY_UMAMI_SCRIPT_URL: ${{ vars.GITTENSORY_UMAMI_SCRIPT_URL }}
+          GITTENSORY_UMAMI_WEBSITE_ID: ${{ vars.GITTENSORY_UMAMI_WEBSITE_ID }}
+          GITTENSORY_UMAMI_DOMAINS: ${{ vars.GITTENSORY_UMAMI_DOMAINS }}
         run: npm run docs:build
 
       - name: Upload Pages artifact

CHANGELOG.md

@@ -45,5 +45,7 @@
 
 - Add public registration polish gates
 
+- Add analytics and mcp version widget
+
 
 

package.json

@@ -22,6 +22,7 @@
     "docs:build": "vitepress build site",
     "docs:preview": "vitepress preview site --host 127.0.0.1",
     "docs:check": "node scripts/check-docs.mjs",
+    "docs:smoke": "node scripts/check-docs-build.mjs",
     "changelog": "npm run changelog:root && npm run changelog:mcp",
     "changelog:root": "git-cliff --config cliff.toml --output CHANGELOG.md",
     "changelog:mcp": "git-cliff --config cliff.mcp.toml --include-path 'packages/gittensory-mcp/**' --include-path '.github/workflows/npm-publish.yml' --output packages/gittensory-mcp/CHANGELOG.md",
@@ -32,7 +33,7 @@
     "test:integration": "vitest run test/integration",
     "test:workers": "vitest run --config vitest.workers.config.ts",
     "test:coverage": "vitest run --coverage",
-    "test:ci": "git diff --check && npm run actionlint && npm run typecheck && npm run test:coverage && npm run test:workers && npm run build:mcp && npm run test:mcp-pack && npm run docs:check && npm run docs:build && npm run changelog:check && npm audit --audit-level=moderate",
+    "test:ci": "git diff --check && npm run actionlint && npm run typecheck && npm run test:coverage && npm run test:workers && npm run build:mcp && npm run test:mcp-pack && npm run docs:check && npm run docs:build && npm run docs:smoke && npm run changelog:check && npm audit --audit-level=moderate",
     "test:watch": "vitest",
     "validate": "npm run typecheck && npm run test:coverage"
   },

scripts/check-docs-build.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.cwd();
+const dist = join(root, "site/.vitepress/dist");
+const indexPath = join(dist, "index.html");
+const expectUmami = process.env.GITTENSORY_EXPECT_UMAMI === "1";
+const expectedScriptUrl = process.env.GITTENSORY_UMAMI_SCRIPT_URL;
+const expectedWebsiteId = process.env.GITTENSORY_UMAMI_WEBSITE_ID;
+const expectedDomains = process.env.GITTENSORY_UMAMI_DOMAINS ?? "gittensory.aethereal.dev";
+const failures = [];
+
+if (!existsSync(indexPath)) {
+  failures.push("site/.vitepress/dist/index.html is missing; run npm run docs:build first.");
+} else {
+  const html = readFileSync(indexPath, "utf8");
+  if (!html.includes("gtn-version-pill")) failures.push("built docs are missing the MCP version pill markup.");
+  if (!html.includes("MCP")) failures.push("built docs are missing MCP version text.");
+}
+
+const builtFiles = existsSync(dist) ? collect(dist).filter((file) => /\.(html|js)$/.test(file)) : [];
+const builtText = builtFiles.map((file) => readFileSync(file, "utf8")).join("\n");
+
+if (!builtText.includes("registry.npmjs.org") || !builtText.includes("@jsonbored%2fgittensory-mcp")) {
+  failures.push("built docs are missing the npm registry fetch for the MCP version widget.");
+}
+
+if (expectUmami) {
+  if (!expectedScriptUrl || !expectedWebsiteId) {
+    failures.push("GITTENSORY_EXPECT_UMAMI=1 requires GITTENSORY_UMAMI_SCRIPT_URL and GITTENSORY_UMAMI_WEBSITE_ID.");
+  } else {
+    if (!builtText.includes(expectedScriptUrl)) failures.push("built docs are missing the configured Umami script URL.");
+    if (!builtText.includes(`data-website-id="${expectedWebsiteId}"`)) failures.push("built docs are missing the configured Umami website ID.");
+    if (!builtText.includes(`data-domains="${expectedDomains}"`)) failures.push("built docs are missing the configured Umami domain list.");
+    if (!builtText.includes('data-do-not-track="true"')) failures.push("built docs are missing the Umami do-not-track attribute.");
+    if (!builtText.includes('data-exclude-search="true"')) failures.push("built docs are missing the Umami search exclusion attribute.");
+    if (!builtText.includes('data-exclude-hash="true"')) failures.push("built docs are missing the Umami hash exclusion attribute.");
+  }
+} else if (builtText.includes("data-website-id=")) {
+  failures.push("built docs include analytics without GITTENSORY_EXPECT_UMAMI=1.");
+}
+
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+
+console.log(`checked built docs (${builtFiles.length} file(s))`);
+
+function collect(path) {
+  const stat = statSync(path);
+  if (stat.isFile()) return [path];
+  return readdirSync(path).flatMap((entry) => collect(join(path, entry)));
+}

site/.vitepress/config.mts

@@ -1,7 +1,27 @@
-import { defineConfig } from "vitepress";
+import { defineConfig, type HeadConfig } from "vitepress";
 
 const siteUrl = process.env.GITTENSORY_SITE_URL ?? "https://gittensory.aethereal.dev/";
 const siteBase = process.env.GITTENSORY_SITE_BASE ?? "/";
+const umamiScriptUrl = process.env.GITTENSORY_UMAMI_SCRIPT_URL;
+const umamiWebsiteId = process.env.GITTENSORY_UMAMI_WEBSITE_ID;
+const umamiDomains = process.env.GITTENSORY_UMAMI_DOMAINS ?? "gittensory.aethereal.dev";
+
+const analyticsHead: HeadConfig[] = umamiScriptUrl && umamiWebsiteId
+  ? [
+      [
+        "script",
+        {
+          defer: "",
+          src: umamiScriptUrl,
+          "data-website-id": umamiWebsiteId,
+          "data-domains": umamiDomains,
+          "data-do-not-track": "true",
+          "data-exclude-search": "true",
+          "data-exclude-hash": "true",
+        },
+      ],
+    ]
+  : [];
 
 export default defineConfig({
   title: "Gittensory",
@@ -18,6 +38,7 @@ export default defineConfig({
     ["meta", { property: "og:description", content: "Private decision intelligence for healthier Gittensor repo participation." }],
     ["meta", { property: "og:url", content: siteUrl }],
     ["meta", { name: "theme-color", content: "#050608" }],
+    ...analyticsHead,
   ],
   themeConfig: {
     logo: "/logo.svg",

site/.vitepress/theme/components/McpVersionPill.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+import mcpPackage from "../../../../packages/gittensory-mcp/package.json";
+
+const props = defineProps<{
+  placement?: "nav" | "footer";
+}>();
+
+type NpmRegistryPackage = {
+  "dist-tags"?: Record<string, string>;
+  time?: Record<string, string>;
+  versions?: Record<string, unknown>;
+};
+
+type VersionEntry = {
+  version: string;
+  publishedAt?: string;
+  npmUrl: string;
+};
+
+const packageName = "@jsonbored/gittensory-mcp";
+const encodedPackageName = "@jsonbored%2fgittensory-mcp";
+const fallbackVersion = mcpPackage.version;
+const registryUrl = `https://registry.npmjs.org/${encodedPackageName}`;
+const packageUrl = `https://www.npmjs.com/package/${packageName}`;
+const changelogUrl = "https://github.com/JSONbored/gittensory/blob/main/packages/gittensory-mcp/CHANGELOG.md";
+const storageKey = "gittensory:mcp-version:seen";
+const recentWindowMs = 7 * 24 * 60 * 60 * 1000;
+
+const root = ref<HTMLElement | null>(null);
+const open = ref(false);
+const failed = ref(false);
+const seenVersion = ref("");
+const latestVersion = ref(fallbackVersion);
+const versions = ref<VersionEntry[]>([
+  {
+    version: fallbackVersion,
+    npmUrl: `${packageUrl}/v/${fallbackVersion}`,
+  },
+]);
+
+const latestEntry = computed(() => versions.value.find((entry) => entry.version === latestVersion.value) ?? versions.value[0]);
+const latestPublishedAt = computed(() => latestEntry.value?.publishedAt);
+const latestNpmUrl = computed(() => `${packageUrl}/v/${latestVersion.value}`);
+const showNewBadge = computed(() => {
+  if (seenVersion.value && seenVersion.value !== latestVersion.value) return true;
+  if (latestVersion.value !== fallbackVersion) return true;
+  if (!latestPublishedAt.value) return false;
+  const publishedAt = Date.parse(latestPublishedAt.value);
+  return Number.isFinite(publishedAt) && Date.now() - publishedAt < recentWindowMs;
+});
+
+onMounted(async () => {
+  seenVersion.value = readSeenVersion();
+  document.addEventListener("click", closeFromDocument);
+  document.addEventListener("keydown", closeFromEscape);
+
+  try {
+    const response = await fetch(registryUrl, { headers: { accept: "application/json" } });
+    if (!response.ok) throw new Error(`npm registry returned ${response.status}`);
+    const payload = (await response.json()) as NpmRegistryPackage;
+    const latest = payload["dist-tags"]?.latest;
+    const nextVersions = Object.keys(payload.versions ?? {})
+      .filter(isStableVersion)
+      .sort(compareVersionsDesc)
+      .slice(0, 5);
+
+    if (latest && isStableVersion(latest)) latestVersion.value = latest;
+    if (nextVersions.length > 0) {
+      versions.value = nextVersions.map((version) => ({
+        version,
+        publishedAt: payload.time?.[version],
+        npmUrl: `${packageUrl}/v/${version}`,
+      }));
+    }
+  } catch {
+    failed.value = true;
+  }
+});
+
+onBeforeUnmount(() => {
+  document.removeEventListener("click", closeFromDocument);
+  document.removeEventListener("keydown", closeFromEscape);
+});
+
+function toggleOpen() {
+  open.value = !open.value;
+  if (open.value) markSeen();
+}
+
+function markSeen() {
+  seenVersion.value = latestVersion.value;
+  try {
+    localStorage.setItem(storageKey, latestVersion.value);
+  } catch {
+    // Ignore storage failures; the badge is only a convenience hint.
+  }
+}
+
+function readSeenVersion(): string {
+  try {
+    return localStorage.getItem(storageKey) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function closeFromDocument(event: MouseEvent) {
+  if (!open.value || root.value?.contains(event.target as Node)) return;
+  open.value = false;
+}
+
+function closeFromEscape(event: KeyboardEvent) {
+  if (event.key === "Escape") open.value = false;
+}
+
+function isStableVersion(version: string): boolean {
+  return /^\d+\.\d+\.\d+$/.test(version);
+}
+
+function compareVersionsDesc(left: string, right: string): number {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const delta = (rightParts[index] ?? 0) - (leftParts[index] ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+function formatDate(value?: string): string {
+  if (!value) return "date unknown";
+  return new Intl.DateTimeFormat("en", { month: "short", day: "numeric", year: "numeric" }).format(new Date(value));
+}
+</script>
+
+<template>
+  <div
+    ref="root"
+    class="gtn-version-pill"
+    :class="{
+      'gtn-version-pill--footer': props.placement === 'footer',
+      'gtn-version-pill--fallback': failed,
+    }"
+  >
+    <button
+      type="button"
+      class="gtn-version-pill__button"
+      aria-haspopup="menu"
+      :aria-expanded="open"
+      @click="toggleOpen"
+    >
+      <span>MCP</span>
+      <strong>v{{ latestVersion }}</strong>
+      <em v-if="showNewBadge">new</em>
+    </button>
+
+    <div v-if="open" class="gtn-version-pill__menu" role="menu">
+      <div class="gtn-version-pill__menu-head">
+        <span>Package releases</span>
+        <a :href="latestNpmUrl">npm</a>
+        <a :href="changelogUrl">changelog</a>
+      </div>
+
+      <a
+        v-for="entry in versions"
+        :key="entry.version"
+        class="gtn-version-pill__version"
+        :href="entry.npmUrl"
+        role="menuitem"
+      >
+        <strong>v{{ entry.version }}</strong>
+        <time>{{ formatDate(entry.publishedAt) }}</time>
+        <span v-if="entry.version === latestVersion">latest</span>
+      </a>
+
+      <p v-if="failed" class="gtn-version-pill__note">
+        Showing the docs build version because npm release metadata could not be loaded.
+      </p>
+    </div>
+  </div>
+</template>