@fragments-sdk/cli 0.7.15 → 0.7.17

package/src/viewer/hooks/useA11yService.ts

@@ -8,10 +8,8 @@
  */
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { Result } from 'axe-core';
 import type {
   A11yServiceConfig,
-  SerializedViolation,
   ComponentScanState,
   ScanStatus,
 } from '../types/a11y.js';
@@ -22,6 +20,7 @@ import {
   isComponentStale,
   getA11ySummary,
 } from './useA11yCache.js';
+import { runAxeScan, type ScanResult } from '../webmcp/scan-utils.js';
 
 // Default configuration
 const DEFAULT_CONFIG: A11yServiceConfig = {
@@ -54,139 +53,6 @@ const serviceState: A11yServiceState = {
   componentStates: new Map(),
 };
 
-// Cache the axe-core module
-let axeModule: typeof import('axe-core') | null = null;
-
-export interface ScanResult {
-  violations: SerializedViolation[];
-  passes: number;
-  incomplete: number;
-  counts: {
-    critical: number;
-    serious: number;
-    moderate: number;
-    minor: number;
-  };
-}
-
-/**
- * Convert axe-core Result to SerializedViolation
- */
-function serializeViolation(result: Result): SerializedViolation {
-  return {
-    id: result.id,
-    impact: result.impact || null,
-    description: result.description,
-    help: result.help,
-    helpUrl: result.helpUrl,
-    tags: result.tags,
-    nodes: result.nodes.map(node => ({
-      html: node.html,
-      target: node.target as string[],
-      failureSummary: node.failureSummary,
-      any: node.any?.map(check => ({
-        id: check.id,
-        data: check.data,
-        relatedNodes: check.relatedNodes?.map(rn => ({
-          html: rn.html,
-          target: rn.target as string[],
-        })),
-        impact: check.impact,
-        message: check.message,
-      })),
-      all: node.all?.map(check => ({
-        id: check.id,
-        data: check.data,
-        relatedNodes: check.relatedNodes?.map(rn => ({
-          html: rn.html,
-          target: rn.target as string[],
-        })),
-        impact: check.impact,
-        message: check.message,
-      })),
-      none: node.none?.map(check => ({
-        id: check.id,
-        data: check.data,
-        relatedNodes: check.relatedNodes?.map(rn => ({
-          html: rn.html,
-          target: rn.target as string[],
-        })),
-        impact: check.impact,
-        message: check.message,
-      })),
-    })),
-  };
-}
-
-/**
- * Run axe-core scan on a target element
- */
-async function runAxeScan(targetSelector: string): Promise<ScanResult | null> {
-  // Load axe-core if not cached
-  if (!axeModule) {
-    axeModule = await import('axe-core');
-  }
-  // Handle both ESM default export and CommonJS module
-  const axe = (axeModule as { default?: typeof import('axe-core') }).default || axeModule;
-
-  const target = document.querySelector(targetSelector);
-  if (!target) {
-    console.warn(`[A11y] Target element not found: ${targetSelector}`);
-    return null;
-  }
-
-  // Configure axe-core
-  axe.configure({
-    rules: [
-      { id: 'color-contrast', enabled: true },
-      { id: 'image-alt', enabled: true },
-      { id: 'button-name', enabled: true },
-      { id: 'link-name', enabled: true },
-      { id: 'label', enabled: true },
-      { id: 'aria-valid-attr', enabled: true },
-      { id: 'aria-valid-attr-value', enabled: true },
-    ],
-  });
-
-  // Run the scan
-  const results = await axe.run(target as HTMLElement, {
-    resultTypes: ['violations', 'passes', 'incomplete', 'inapplicable'],
-  });
-
-  // Count violations by severity
-  const counts = {
-    critical: 0,
-    serious: 0,
-    moderate: 0,
-    minor: 0,
-  };
-
-  for (const violation of results.violations) {
-    switch (violation.impact) {
-      case 'critical':
-        counts.critical++;
-        break;
-      case 'serious':
-        counts.serious++;
-        break;
-      case 'moderate':
-        counts.moderate++;
-        break;
-      case 'minor':
-      default:
-        counts.minor++;
-        break;
-    }
-  }
-
-  return {
-    violations: results.violations.map(serializeViolation),
-    passes: results.passes.length,
-    incomplete: results.incomplete.length,
-    counts,
-  };
-}
-
 /**
  * Process the scan queue
  */

package/src/viewer/hooks/useCompiledFragments.ts

@@ -0,0 +1,42 @@
+import { useState, useEffect } from "react";
+import type { CompiledFragmentsFile } from "@fragments-sdk/context/types";
+
+interface UseCompiledFragmentsResult {
+  data: CompiledFragmentsFile | null;
+  loading: boolean;
+  error: string | null;
+}
+
+export function useCompiledFragments(): UseCompiledFragmentsResult {
+  const [data, setData] = useState<CompiledFragmentsFile | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    fetch("/fragments/compiled.json")
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((json) => {
+        if (!cancelled) {
+          setData(json as CompiledFragmentsFile);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return { data, loading, error };
+}

package/src/viewer/server.ts

@@ -32,6 +32,8 @@ const packagesRoot = resolve(cliPackageRoot, "..");
 const localUiLibRoot = resolve(packagesRoot, "../libs/ui/src");
 const localSharedLibRoot = resolve(packagesRoot, "../libs/shared/src");
 const vendoredSharedLibRoot = resolve(viewerRoot, "vendor/shared/src");
+const localWebMCPRoot = resolve(packagesRoot, "webmcp/src");
+const localContextRoot = resolve(packagesRoot, "context/src");
 
 /**
  * Resolve the @fragments/ui alias to the correct path.
@@ -57,6 +59,44 @@ function resolveUiLib(nodeModulesDir: string): string {
   return localUiLibRoot;
 }
 
+/**
+ * Resolve @fragments-sdk/webmcp to monorepo source or installed package.
+ */
+function resolveWebMCPLib(nodeModulesDir: string): string {
+  const localIndex = join(localWebMCPRoot, "index.ts");
+  if (existsSync(localIndex)) {
+    return localWebMCPRoot;
+  }
+  const installedSrc = join(nodeModulesDir, "@fragments-sdk/webmcp/src/index.ts");
+  if (existsSync(installedSrc)) {
+    return resolve(dirname(installedSrc));
+  }
+  const installedDist = join(nodeModulesDir, "@fragments-sdk/webmcp");
+  if (existsSync(installedDist)) {
+    return installedDist;
+  }
+  return localWebMCPRoot;
+}
+
+/**
+ * Resolve @fragments-sdk/context to monorepo source or installed package.
+ */
+function resolveContextLib(nodeModulesDir: string): string {
+  const localIndex = join(localContextRoot, "index.ts");
+  if (existsSync(localIndex)) {
+    return localContextRoot;
+  }
+  const installedSrc = join(nodeModulesDir, "@fragments-sdk/context/src/index.ts");
+  if (existsSync(installedSrc)) {
+    return resolve(dirname(installedSrc));
+  }
+  const installedDist = join(nodeModulesDir, "@fragments-sdk/context");
+  if (existsSync(installedDist)) {
+    return installedDist;
+  }
+  return localContextRoot;
+}
+
 /**
  * Resolve the @fragments-sdk/shared alias to either monorepo source
  * or vendored viewer fallback for npm installs.
@@ -211,6 +251,8 @@ export async function createDevServer(
   const nodeModulesPath = findNodeModules(projectRoot);
   const uiLibRoot = resolveUiLib(nodeModulesPath);
   const sharedLibRoot = resolveSharedLib();
+  const webmcpLibRoot = resolveWebMCPLib(nodeModulesPath);
+  const contextLibRoot = resolveContextLib(nodeModulesPath);
   console.log(`📁 Using node_modules: ${nodeModulesPath}`);
 
   // Collect installed package roots so Vite can serve files from node_modules
@@ -238,7 +280,7 @@ export async function createDevServer(
       open: open ? "/fragments/" : false,
       fs: {
         // Allow serving files from viewer package, project, shared libs, and node_modules root
-        allow: [viewerRoot, uiLibRoot, sharedLibRoot, projectRoot, configDir, dirname(nodeModulesPath), ...installedPkgRoots],
+        allow: [viewerRoot, uiLibRoot, sharedLibRoot, webmcpLibRoot, contextLibRoot, projectRoot, configDir, dirname(nodeModulesPath), ...installedPkgRoots],
       },
     },
 
@@ -257,8 +299,13 @@ export async function createDevServer(
       }),
     ],
 
-    // CSS configuration
-    css: {},
+    // CSS configuration — preserve original hyphenated class names in CSS modules
+    // Vite 6 defaults to camelCaseOnly, but our components use styles['gap-sm'] etc.
+    css: {
+      modules: {
+        localsConvention: 'camelCase',
+      },
+    },
 
     optimizeDeps: {
       // Include common dependencies for faster startup
@@ -274,6 +321,14 @@ export async function createDevServer(
         "@fragments-sdk/ui": uiLibRoot,
         // Resolve @fragments-sdk/shared to monorepo source or vendored fallback
         "@fragments-sdk/shared": sharedLibRoot,
+        // Resolve @fragments-sdk/webmcp subpaths to monorepo source or installed package
+        "@fragments-sdk/webmcp/react": join(webmcpLibRoot, "react/index.ts"),
+        "@fragments-sdk/webmcp/fragments": join(webmcpLibRoot, "fragments/index.ts"),
+        "@fragments-sdk/webmcp": webmcpLibRoot,
+        // Resolve @fragments-sdk/context subpaths to monorepo source or installed package
+        "@fragments-sdk/context/types": join(contextLibRoot, "types/index.ts"),
+        "@fragments-sdk/context/mcp-tools": join(contextLibRoot, "mcp-tools/index.ts"),
+        "@fragments-sdk/context": contextLibRoot,
         // Resolve @fragments-sdk/cli/core to the CLI's own core source
         "@fragments-sdk/cli/core": resolve(cliPackageRoot, "src/core/index.ts"),
         // Ensure ALL react imports resolve to project's node_modules

package/src/viewer/vite-plugin.ts

@@ -928,6 +928,24 @@ export function fragmentsPlugin(options: FragmentsPluginOptions): Plugin[] {
           return;
         }
 
+        // Handle /fragments/compiled.json endpoint for WebMCP integration
+        if (req.url === "/fragments/compiled.json") {
+          try {
+            const { join } = await import("node:path");
+            const fragmentsJsonPath = join(projectRoot, BRAND.outFile);
+            const content = await readFile(fragmentsJsonPath, "utf-8");
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(content);
+          } catch (error) {
+            console.warn(`[${BRAND.name}] Failed to serve compiled.json:`, error);
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+              error: `${BRAND.outFile} not found. Run '${BRAND.cliCommand} build' first.`,
+            }));
+          }
+          return;
+        }
+
         // Handle /fragments/context endpoint for AI context generation
         if (req.url?.startsWith("/fragments/context")) {
           try {

package/src/viewer/webmcp/__tests__/analytics.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { ToolAnalyticsCollector } from '../analytics.js';
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+
+function createEvent(overrides: Partial<ToolCallEvent> = {}): ToolCallEvent {
+  return {
+    toolName: 'fragments_discover',
+    input: {},
+    output: {},
+    error: null,
+    durationMs: 50,
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+describe('ToolAnalyticsCollector', () => {
+  it('records events and computes summary', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent({ toolName: 'fragments_discover', durationMs: 10 }));
+    collector.record(createEvent({ toolName: 'fragments_discover', durationMs: 20 }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', durationMs: 30 }));
+
+    const summary = collector.toSummary();
+    expect(summary.totalCalls).toBe(3);
+    expect(summary.uniqueTools).toBe(2);
+    expect(summary.toolStats.fragments_discover.callCount).toBe(2);
+    expect(summary.toolStats.fragments_discover.avgDuration).toBe(15);
+    expect(summary.toolStats.fragments_inspect.callCount).toBe(1);
+  });
+
+  it('tracks error rate', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent({ error: null }));
+    collector.record(createEvent({ error: 'fail' }));
+
+    const summary = collector.toSummary();
+    expect(summary.errorRate).toBe(0.5);
+  });
+
+  it('detects common flows', () => {
+    const collector = new ToolAnalyticsCollector();
+    const base = Date.now();
+
+    // Create a repeated flow: discover -> inspect -> discover -> inspect
+    collector.record(createEvent({ toolName: 'fragments_discover', timestamp: base }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', timestamp: base + 100 }));
+    collector.record(createEvent({ toolName: 'fragments_discover', timestamp: base + 200 }));
+    collector.record(createEvent({ toolName: 'fragments_inspect', timestamp: base + 300 }));
+
+    const summary = collector.toSummary();
+    expect(summary.commonFlows.length).toBeGreaterThan(0);
+    expect(summary.commonFlows[0].sequence).toEqual(['fragments_discover', 'fragments_inspect']);
+    expect(summary.commonFlows[0].count).toBe(2);
+  });
+
+  it('splits sessions on 30s gap', () => {
+    const collector = new ToolAnalyticsCollector();
+    const base = Date.now();
+
+    collector.record(createEvent({ toolName: 'a', timestamp: base }));
+    collector.record(createEvent({ toolName: 'b', timestamp: base + 100 }));
+    // 31s gap
+    collector.record(createEvent({ toolName: 'a', timestamp: base + 31_100 }));
+    collector.record(createEvent({ toolName: 'b', timestamp: base + 31_200 }));
+
+    const summary = collector.toSummary();
+    // "a -> b" appears in both sessions
+    const abFlow = summary.commonFlows.find(f =>
+      f.sequence[0] === 'a' && f.sequence[1] === 'b'
+    );
+    expect(abFlow).toBeDefined();
+    expect(abFlow!.count).toBe(2);
+  });
+
+  it('computes percentiles', () => {
+    const collector = new ToolAnalyticsCollector();
+    for (let i = 1; i <= 100; i++) {
+      collector.record(createEvent({ durationMs: i }));
+    }
+
+    const summary = collector.toSummary();
+    const stat = summary.toolStats.fragments_discover;
+    expect(stat.p50).toBeGreaterThanOrEqual(49);
+    expect(stat.p50).toBeLessThanOrEqual(51);
+    expect(stat.p95).toBeGreaterThanOrEqual(94);
+    expect(stat.p95).toBeLessThanOrEqual(96);
+  });
+
+  it('produces PostHog properties', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent());
+
+    const props = collector.toPostHogProperties();
+    expect(props.webmcp_total_calls).toBe(1);
+    expect(props.webmcp_unique_tools).toBe(1);
+    expect(typeof props.webmcp_tool_breakdown).toBe('string');
+  });
+
+  it('resets state', () => {
+    const collector = new ToolAnalyticsCollector();
+    collector.record(createEvent());
+    collector.reset();
+
+    const summary = collector.toSummary();
+    expect(summary.totalCalls).toBe(0);
+  });
+});

package/src/viewer/webmcp/analytics.ts

@@ -0,0 +1,165 @@
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+
+interface ToolStats {
+  callCount: number;
+  totalDuration: number;
+  durations: number[];
+  errorCount: number;
+}
+
+interface ToolFlow {
+  sequence: string[];
+  count: number;
+}
+
+interface AnalyticsSummary {
+  totalCalls: number;
+  uniqueTools: number;
+  sessionDurationMs: number;
+  errorRate: number;
+  toolStats: Record<string, {
+    callCount: number;
+    avgDuration: number;
+    p50: number;
+    p95: number;
+    errorCount: number;
+  }>;
+  commonFlows: ToolFlow[];
+}
+
+const SESSION_GAP_MS = 30_000;
+
+export class ToolAnalyticsCollector {
+  private stats = new Map<string, ToolStats>();
+  private events: ToolCallEvent[] = [];
+  private sessionStart: number | null = null;
+
+  record(event: ToolCallEvent): void {
+    this.events.push(event);
+
+    if (this.sessionStart === null) {
+      this.sessionStart = event.timestamp;
+    }
+
+    const existing = this.stats.get(event.toolName);
+    if (existing) {
+      existing.callCount++;
+      existing.totalDuration += event.durationMs;
+      existing.durations.push(event.durationMs);
+      if (event.error) existing.errorCount++;
+    } else {
+      this.stats.set(event.toolName, {
+        callCount: 1,
+        totalDuration: event.durationMs,
+        durations: [event.durationMs],
+        errorCount: event.error ? 1 : 0,
+      });
+    }
+  }
+
+  toSummary(): AnalyticsSummary {
+    let totalCalls = 0;
+    let totalErrors = 0;
+    const toolStats: AnalyticsSummary['toolStats'] = {};
+
+    for (const [name, stat] of this.stats) {
+      totalCalls += stat.callCount;
+      totalErrors += stat.errorCount;
+
+      const sorted = [...stat.durations].sort((a, b) => a - b);
+      toolStats[name] = {
+        callCount: stat.callCount,
+        avgDuration: Math.round(stat.totalDuration / stat.callCount),
+        p50: percentile(sorted, 50),
+        p95: percentile(sorted, 95),
+        errorCount: stat.errorCount,
+      };
+    }
+
+    const sessionDurationMs = this.sessionStart !== null && this.events.length > 0
+      ? this.events[this.events.length - 1].timestamp - this.sessionStart
+      : 0;
+
+    return {
+      totalCalls,
+      uniqueTools: this.stats.size,
+      sessionDurationMs,
+      errorRate: totalCalls > 0 ? Math.round((totalErrors / totalCalls) * 100) / 100 : 0,
+      toolStats,
+      commonFlows: this.detectFlows(),
+    };
+  }
+
+  toPostHogProperties(): Record<string, unknown> {
+    const summary = this.toSummary();
+    return {
+      webmcp_total_calls: summary.totalCalls,
+      webmcp_unique_tools: summary.uniqueTools,
+      webmcp_session_duration_ms: summary.sessionDurationMs,
+      webmcp_error_rate: summary.errorRate,
+      webmcp_tool_breakdown: JSON.stringify(summary.toolStats),
+      webmcp_common_flows: JSON.stringify(summary.commonFlows),
+    };
+  }
+
+  private detectFlows(): ToolFlow[] {
+    if (this.events.length < 2) return [];
+
+    // Split into sessions (30s gap)
+    const sessions: ToolCallEvent[][] = [];
+    let currentSession: ToolCallEvent[] = [this.events[0]];
+
+    for (let i = 1; i < this.events.length; i++) {
+      if (this.events[i].timestamp - this.events[i - 1].timestamp > SESSION_GAP_MS) {
+        sessions.push(currentSession);
+        currentSession = [];
+      }
+      currentSession.push(this.events[i]);
+    }
+    sessions.push(currentSession);
+
+    // Count 2-grams and 3-grams
+    const flowCounts = new Map<string, number>();
+
+    for (const session of sessions) {
+      const names = session.map(e => e.toolName);
+
+      // 2-grams
+      for (let i = 0; i < names.length - 1; i++) {
+        const key = `${names[i]} → ${names[i + 1]}`;
+        flowCounts.set(key, (flowCounts.get(key) ?? 0) + 1);
+      }
+
+      // 3-grams
+      for (let i = 0; i < names.length - 2; i++) {
+        const key = `${names[i]} → ${names[i + 1]} → ${names[i + 2]}`;
+        flowCounts.set(key, (flowCounts.get(key) ?? 0) + 1);
+      }
+    }
+
+    // Return top flows (count >= 2)
+    return [...flowCounts.entries()]
+      .filter(([, count]) => count >= 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([key, count]) => ({
+        sequence: key.split(' → '),
+        count,
+      }));
+  }
+
+  reset(): void {
+    this.stats.clear();
+    this.events = [];
+    this.sessionStart = null;
+  }
+}
+
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const index = (p / 100) * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  if (lower === upper) return sorted[lower];
+  return Math.round(sorted[lower] + (sorted[upper] - sorted[lower]) * (index - lower));
+}

package/src/viewer/webmcp/index.ts

@@ -0,0 +1,3 @@
+export { runAxeScan, serializeViolation, type ScanResult } from './scan-utils.js';
+export { createRuntimeWebMCPTools, type RuntimeToolsOptions } from './runtime-tools.js';
+export { getViewerState, setViewerState, type ViewerState } from './viewer-state.js';

package/src/viewer/webmcp/posthog-bridge.ts

@@ -0,0 +1,39 @@
+import type { ToolCallEvent } from '@fragments-sdk/webmcp';
+import type { ToolAnalyticsCollector } from './analytics.js';
+
+interface PostHogLike {
+  capture(event: string, properties?: Record<string, unknown>): void;
+}
+
+interface PostHogBridge {
+  onToolCall(event: ToolCallEvent): void;
+  onSessionEnd(): void;
+  flush(): void;
+}
+
+export function createPostHogBridge(
+  posthog: PostHogLike,
+  collector: ToolAnalyticsCollector
+): PostHogBridge {
+  return {
+    onToolCall(event: ToolCallEvent): void {
+      posthog.capture('webmcp_tool_call', {
+        tool_name: event.toolName,
+        duration_ms: event.durationMs,
+        success: event.error === null,
+        error: event.error,
+      });
+    },
+
+    onSessionEnd(): void {
+      const props = collector.toPostHogProperties();
+      if ((props.webmcp_total_calls as number) > 0) {
+        posthog.capture('webmcp_session_summary', props);
+      }
+    },
+
+    flush(): void {
+      this.onSessionEnd();
+    },
+  };
+}