@cloudhal/mcp-server 0.0.0-stage → 0.1.0

package/dist/src/analytics-reports.js

@@ -0,0 +1,632 @@
+/**
+ * Analytics reports shared by the REST routes (`packages/api/src/routes/analytics.ts`) and the MCP
+ * tools (`analytics-tools.ts`), RFC-0006 §9: queries of the model through `AnalyticsService`, joined
+ * to the **current** graph by node id (a renamed article shows its new title and path; a deleted
+ * one reads as gone). Every string returned is graph data, an enum, a hostname, a UTM token or —
+ * for render reports only — a percent-encoded requested path (§5.5, invariant A9).
+ */
+             
+                  
+                  
+                   
+                   
+            
+         
+        
+                 
+                    
+              
+         
+             
+                             
+import { ID_RE, parseRange, privacySignalShare } from "@cloudhal/analytics";
+import {                        previousRange } from "@cloudhal/analytics/service";
+import { entryPath } from "@cloudhal/astro-renderer/routing";
+import { archivePath } from "@cloudhal/astro-renderer/taxonomy";
+                                                                                         
+import {                      termName } from "@cloudhal/core-ts";
+
+                                                             
+
+/** A node of analytics rows as the current graph knows it. */
+                                
+                          
+                                                                
+                                          
+                                                                             
+                           
+                                
+                                                              
+                               
+                                                        
+                                 
+ 
+
+/** Where a combined answer came from (the REST envelope's `source`, `estimated`, `partial`). */
+                                
+                                   
+                              
+                             
+ 
+
+export function combineMeta(results                            )                {
+  const sources = new Set(results.map((r) => r.source));
+  const source                  =
+    sources.size === 1
+      ? ([...sources][0]                   )
+      : sources.size === 0
+        ? "live"
+        : "mixed";
+  const partial = results.some((r) => r.partial === true);
+  return {
+    source,
+    estimated: results.some((r) => r.estimated),
+    ...(partial ? { partial: true } : {}),
+  };
+}
+
+const KIND_BY_PREFIX                                              = {
+  page: "page",
+  entry: "entry",
+  term: "archive",
+};
+
+export function nodeKindOf(id        )                           {
+  return KIND_BY_PREFIX[id.slice(0, id.indexOf("_"))] ?? null;
+}
+
+/** Individual reads up to this many entries; beyond it one list read (D1 caps queries per call). */
+const ENTRY_GETS = 20;
+
+/** The current graph's view of analytics node ids, in a bounded number of reads. */
+export async function analyticsNodes(
+  store                ,
+  site      ,
+  ids                   ,
+)                                      {
+  const unique = [...new Set(ids)].filter((id) => ID_RE.test(id));
+  const byKind = (k                   ) => unique.filter((id) => nodeKindOf(id) === k);
+  const out = new Map                       ();
+  const gone = (nodeId        )                => ({
+    nodeId,
+    kind: nodeKindOf(nodeId),
+    exists: false,
+    title: null,
+    path: null,
+    status: null,
+  });
+
+  const pageIds = byKind("page");
+  if (pageIds.length > 0) {
+    const pages = new Map              ((await store.listPages(site.id)).map((p) => [p.id, p]));
+    for (const id of pageIds) {
+      const p = pages.get(id);
+      out.set(
+        id,
+        p
+          ? {
+              nodeId: id,
+              kind: "page",
+              exists: true,
+              title: p.title,
+              path: p.path,
+              status: p.status,
+            }
+          : gone(id),
+      );
+    }
+  }
+
+  const entryIds = byKind("entry");
+  if (entryIds.length > 0) {
+    let entries                           ;
+    if (entryIds.length <= ENTRY_GETS) {
+      const found = await Promise.all(entryIds.map((id) => store.getContentEntry(id)));
+      entries = new Map(
+        found.filter((e)                    => e?.siteId === site.id).map((e) => [e.id, e]),
+      );
+    } else {
+      const wanted = new Set(entryIds);
+      entries = new Map(
+        (await store.listContentEntries(site.id))
+          .filter((e) => wanted.has(e.id))
+          .map((e) => [e.id, e]),
+      );
+    }
+    for (const id of entryIds) {
+      const e = entries.get(id);
+      out.set(
+        id,
+        e
+          ? {
+              nodeId: id,
+              kind: "entry",
+              exists: true,
+              title: e.title,
+              path: entryPath(e),
+              status: e.status,
+            }
+          : gone(id),
+      );
+    }
+  }
+
+  const termIds = byKind("archive");
+  if (termIds.length > 0) {
+    const [terms, taxonomies] = await Promise.all([
+      store.listTerms(site.id),
+      store.listTaxonomies(site.id),
+    ]);
+    const termById = new Map              (terms.map((t) => [t.id, t]));
+    const taxById = new Map                  (taxonomies.map((t) => [t.id, t]));
+    for (const id of termIds) {
+      const t = termById.get(id);
+      const tax = t ? taxById.get(t.taxonomyId) : undefined;
+      out.set(
+        id,
+        t
+          ? {
+              nodeId: id,
+              kind: "archive",
+              exists: true,
+              title: termName(t, site.defaultLocale),
+              path: tax?.archive.enabled ? archivePath(tax, t.slug) : null,
+              status: t.status,
+            }
+          : gone(id),
+      );
+    }
+  }
+
+  for (const id of ids) if (!out.has(id)) out.set(id, gone(id));
+  return out;
+}
+
+// ───────────────────────────── summary ─────────────────────────────
+
+                                                    
+                                                     
+                                        
+     
+                                                                                            
+                                                                                                   
+                                                                                       
+     
+                                        
+     
+                                                                                             
+                                                                                  
+     
+                                             
+                                                                   
+                                                              
+                                                                                                  
+                     
+                                      
+                                   
+                                     
+    
+ 
+
+const ratio = (cur               , prev               )                =>
+  cur === null || prev === null || prev === 0
+    ? null
+    : Math.round(((cur - prev) / prev) * 1000) / 1000;
+
+export async function summaryReport(
+  analytics                  ,
+  siteId        ,
+  range       ,
+  options                                                                 = {},
+)                                                               {
+  const filter = options.filter ? { filter: options.filter } : {};
+  const current = await analytics.query({ kind: "summary", siteId, range, ...filter });
+  const cur = current.data;
+  const base                = {
+    ...cur,
+    viewsPerVisit: cur.visits > 0 ? Math.round((cur.pageviews / cur.visits) * 100) / 100 : null,
+    cacheHitRatio: analytics.cacheHitRatio(cur),
+    privacySignalShare: privacySignalShare(cur),
+  };
+  if (!options.compare) return { data: base, results: [current] };
+  const prevRange = previousRange(range);
+  const previous = await analytics.query({ kind: "summary", siteId, range: prevRange, ...filter });
+  const prev = previous.data;
+  return {
+    data: {
+      ...base,
+      previous: { ...prev, range: prevRange },
+      change: {
+        pageviews: ratio(cur.pageviews, prev.pageviews),
+        visits: ratio(cur.visits, prev.visits),
+        visitors: ratio(cur.visitors, prev.visitors),
+      },
+    },
+    results: [current, previous],
+  };
+}
+
+// ───────────────────────────── possible bot traffic ─────────────────────────────
+
+/** A reason of the signal; `single_page` carries the page as the current graph knows it. */
+                                                                                          
+
+                                                                             
+                                                      
+ 
+
+/**
+ * The "possible bot traffic" signal (RFC-0006 §5.5) for REST `…/analytics/bots` and
+ * `get_analytics`: the period's last 7 days by the hour; a `single_page` reason is joined to the
+ * graph (title and current path), so people and agents see which page drew the burst.
+ */
+export async function botTrafficReport(
+  analytics                  ,
+  store                ,
+  site      ,
+  range       ,
+)                                                                  {
+  const { signal, results } = await analytics.botTraffic(site.id, range);
+  const page = signal.reasons.find((r) => r.code === "single_page")?.key;
+  if (!page) return { data: signal, results };
+  const nodes = await analyticsNodes(store, site, [page]);
+  return {
+    data: {
+      ...signal,
+      reasons: signal.reasons.map((r) =>
+        r.code === "single_page" && r.key ? { ...r, node: nodes.get(r.key)                  } : r,
+      ),
+    },
+    results,
+  };
+}
+
+// ───────────────────────────── top lists ─────────────────────────────
+
+                                                      
+                             
+                          
+                                                                                   
+                                  
+ 
+
+/** Top content joined to the graph. `kind` and `channel` narrow it; `compare` adds the change. */
+export async function topContentReport(
+  analytics                  ,
+  store                ,
+  site      ,
+  range       ,
+  options   
+                  
+                                         
+                                
+                                  
+   ,
+)                                                                 {
+  // A kind filter is applied after the join, so ask for more rows than shown.
+  const ask = options.kind ? Math.min(100, options.limit * 4) : options.limit;
+  const filter = options.filter ? { filter: options.filter } : {};
+  const top = await analytics.query({
+    kind: "top",
+    siteId: site.id,
+    range,
+    dimension: "node",
+    limit: ask,
+    ...filter,
+  });
+  const results                    = [top];
+  let rows = top.data.rows.filter((r) => !options.kind || nodeKindOf(r.key) === options.kind);
+  rows = rows.slice(0, options.limit);
+  let before                                 ;
+  if (options.compare && rows.length > 0) {
+    const prev = await analytics.query({
+      kind: "top",
+      siteId: site.id,
+      range: previousRange(range),
+      dimension: "node",
+      limit: Math.min(1000, ask * 4),
+      ...filter,
+    });
+    results.push(prev);
+    before = new Map(prev.data.rows.map((r) => [r.key, r.pageviews]));
+  }
+  const nodes = await analyticsNodes(
+    store,
+    site,
+    rows.map((r) => r.key),
+  );
+  return {
+    rows: rows.map((r) => ({
+      ...(nodes.get(r.key)                 ),
+      pageviews: r.pageviews,
+      visits: r.visits,
+      ...(before ? { change: ratio(r.pageviews, before.get(r.key) ?? 0) } : {}),
+    })),
+    results,
+  };
+}
+
+/** A plain top list (no join): channels, referrers, countries, devices, … */
+export async function topList(
+  analytics                  ,
+  siteId        ,
+  range       ,
+  dimension           ,
+  limit        ,
+  filter         ,
+)                                                                   {
+  return analytics.query({
+    kind: "top",
+    siteId,
+    range,
+    dimension,
+    limit,
+    ...(filter ? { filter } : {}),
+  });
+}
+
+// ───────────────────────────── one node ─────────────────────────────
+
+                          
+                                                                           
+                        
+                      
+                          
+                          
+                                          
+                        
+ 
+
+                             
+                               
+                                  
+                    
+                             
+                                                                        
+    
+                                                      
+                                       
+                                        
+                                        
+                                      
+                              
+                                                                                         
+                                        
+                                                                                                    
+                                
+ 
+
+/** Hourly buckets for ranges of at most two days, daily otherwise (§10.1). */
+export function seriesInterval(range       )                 {
+  const r = parseRange(range, 731);
+  return r.to.getTime() - r.from.getTime() <= 2 * 86_400_000 ? "hour" : "day";
+}
+
+export async function nodeReport(
+  analytics                  ,
+  store                ,
+  site      ,
+  nodeId        ,
+  range       ,
+  options                                    = {},
+)                                                     {
+  const filter         = { node: nodeId };
+  const interval = seriesInterval(range);
+  const [nodes, summary, series, channels, referrers, countries, devices, vitals, redirects] =
+    await Promise.all([
+      analyticsNodes(store, site, [nodeId]),
+      summaryReport(analytics, site.id, range, { filter, compare: options.compare }),
+      analytics.query({ kind: "series", siteId: site.id, range, interval, filter }),
+      topList(analytics, site.id, range, "channel", 10, filter),
+      topList(analytics, site.id, range, "refHost", 10, filter),
+      topList(analytics, site.id, range, "country", 10, filter),
+      topList(analytics, site.id, range, "device", 10, filter),
+      analytics.query({ kind: "vitals", siteId: site.id, range, filter }),
+      analytics.query({
+        kind: "renders",
+        siteId: site.id,
+        range,
+        statuses: "redirects",
+        limit: 1000,
+      }),
+    ]);
+  const redirectRows = redirects.data.rows                                ;
+  const history = (await store.listRedirects(site.id)).filter((r) => r.source?.id === nodeId);
+  const hitsFrom = (path        ) =>
+    redirectRows.filter((r) => r.path === path).reduce((n, r) => n + r.hits, 0);
+  const oldPaths = history.map((r) => ({
+    from: r.from,
+    to: r.to,
+    status: r.status,
+    reason: r.reason,
+    hits: hitsFrom(r.from),
+  }));
+  const froms = new Set(history.map((r) => r.from));
+  const redirectHits = redirectRows
+    .filter((r) => r.nodeId === nodeId || froms.has(r.path))
+    .reduce((n, r) => n + r.hits, 0);
+  return {
+    data: {
+      node: nodes.get(nodeId)                 ,
+      summary: summary.data,
+      series: series.data,
+      channels: channels.data.rows,
+      referrers: referrers.data.rows,
+      countries: countries.data.rows,
+      devices: devices.data.rows,
+      vitals: vitals.data,
+      oldPaths,
+      redirectHits,
+    },
+    meta: combineMeta([
+      ...summary.results,
+      series,
+      channels,
+      referrers,
+      countries,
+      devices,
+      vitals,
+      redirects,
+    ]),
+  };
+}
+
+// ───────────────────────────── broken links ─────────────────────────────
+
+                             
+                                                                                                
+                        
+                          
+                        
+                                                            
+                                         
+                                   
+                                                                                        
+                             
+                 
+                    
+                                   
+           
+ 
+
+function lastSegment(path        )         {
+  let p = path;
+  try {
+    p = decodeURIComponent(path);
+  } catch {
+    // keep it encoded
+  }
+  const parts = p
+    .toLowerCase()
+    .replace(/[?#].*$/, "")
+    .split("/")
+    .filter(Boolean);
+  return parts.at(-1) ?? "";
+}
+
+function editDistance(a        , b        , max        )         {
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    let best = i;
+    for (let j = 1; j <= b.length; j++) {
+      const v = Math.min(
+        (prev[j]          ) + 1,
+        (cur[j - 1]          ) + 1,
+        (prev[j - 1]          ) + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      cur.push(v);
+      best = Math.min(best, v);
+    }
+    if (best > max) return max + 1;
+    prev = cur;
+  }
+  return prev[b.length]          ;
+}
+
+/** 404 and 410 paths with hits, the pages linking to them, and a suggested target. */
+export async function brokenLinksReport(
+  analytics                  ,
+  store                ,
+  site      ,
+  range       ,
+  limit        ,
+)                                                       {
+  const errors = await analytics.query({
+    kind: "renders",
+    siteId: site.id,
+    range,
+    statuses: "errors",
+    limit: 1000,
+  });
+  const groups = new Map 
+           
+     
+                   
+                     
+                   
+                                
+                              
+     
+   ();
+  for (const r of errors.data.rows                             ) {
+    if (r.status !== 404 && r.status !== 410) continue;
+    const key = `${r.status} ${r.path}`;
+    const g = groups.get(key) ?? {
+      path: r.path,
+      status: r.status,
+      hits: 0,
+      refs: new Map                (),
+      lastSeen: null,
+    };
+    g.hits += r.hits;
+    if (r.refPath) g.refs.set(r.refPath, (g.refs.get(r.refPath) ?? 0) + r.hits);
+    if (r.lastSeen && (!g.lastSeen || r.lastSeen > g.lastSeen)) g.lastSeen = r.lastSeen;
+    groups.set(key, g);
+  }
+  const top = [...groups.values()]
+    .sort((a, b) => b.hits - a.hits || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .slice(0, limit);
+
+  // Candidates for "similar slug": published pages and entries (two reads).
+  let candidates                                                                 ;
+  const loadCandidates = async () => {
+    if (candidates) return candidates;
+    const [pages, entries] = await Promise.all([
+      store.listPages(site.id),
+      store.listContentEntries(site.id, { status: ["published"] }),
+    ]);
+    candidates = [
+      ...pages
+        .filter((p) => p.status === "published")
+        .map((p) => ({ path: p.path, nodeId: p.id, segment: lastSegment(p.path) })),
+      ...entries.map((e) => ({ path: entryPath(e), nodeId: e.id, segment: e.slug })),
+    ];
+    return candidates;
+  };
+
+  const rows               = [];
+  for (const g of top) {
+    let suggestedTarget                                = null;
+    let decoded                    ;
+    try {
+      decoded = decodeURIComponent(g.path).toLowerCase();
+    } catch {
+      decoded = undefined;
+    }
+    const match = decoded
+      ? await store.redirectFor(site.id, decoded).catch(() => undefined)
+      : undefined;
+    if (match) suggestedTarget = { path: match.location, reason: "redirect" };
+    else {
+      const seg = lastSegment(g.path);
+      if (seg.length >= 3) {
+        let best                                                         ;
+        for (const c of await loadCandidates()) {
+          if (!c.segment) continue;
+          const d =
+            c.segment === seg
+              ? 0
+              : c.segment.includes(seg) || seg.includes(c.segment)
+                ? 1
+                : editDistance(seg, c.segment, 3);
+          if (d <= 3 && (!best || d < best.d)) best = { path: c.path, nodeId: c.nodeId, d };
+        }
+        if (best) suggestedTarget = { path: best.path, nodeId: best.nodeId, reason: "similar" };
+      }
+    }
+    rows.push({
+      path: g.path,
+      status: g.status,
+      hits: g.hits,
+      linkedFrom: [...g.refs.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([p]) => p),
+      lastSeen: g.lastSeen,
+      suggestedTarget,
+    });
+  }
+  return { rows, meta: combineMeta([errors]) };
+}

package/dist/src/analytics-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "./common.js";
+/** Analytics errors as tool errors with stable codes. */
+export declare function toAnalyticsToolError(e: unknown): unknown;
+export declare function analyticsTools(): ToolDefinition[];