@fragments-sdk/cli 0.10.1 → 0.11.1

package/src/viewer/webmcp/analytics.ts

@@ -1,165 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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();
-    },
-  };
-}

package/src/viewer/webmcp/runtime-tools.ts

@@ -1,152 +0,0 @@
-import type { WebMCPTool, InputSchema } from '@fragments-sdk/webmcp';
-import type { CompiledFragmentsFile } from '@fragments-sdk/context/types';
-import { runAxeScan } from './scan-utils.js';
-import { getViewerState } from './viewer-state.js';
-
-export interface RuntimeToolsOptions {
-  compiledData?: CompiledFragmentsFile | null;
-}
-
-export function createRuntimeWebMCPTools(options: RuntimeToolsOptions = {}): WebMCPTool[] {
-  const tools: WebMCPTool[] = [];
-
-  // --- fragments_a11y ---
-  tools.push({
-    name: 'fragments_a11y',
-    description: 'Run an accessibility audit on the currently previewed component. Returns axe-core violations, a WCAG compliance score, and severity counts. Runs directly on the live DOM for accurate results.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        component: { type: 'string', description: 'Component name to audit' },
-        variant: { type: 'string', description: 'Specific variant to audit' },
-        standard: { type: 'string', enum: ['AA', 'AAA'], default: 'AA', description: 'WCAG compliance level' },
-      },
-      required: ['component'],
-    } as InputSchema,
-    annotations: { readOnlyHint: true },
-    execute: async (input) => {
-      const component = input.component as string;
-      const standard = (input.standard as string) || 'AA';
-
-      const result = await runAxeScan('[data-preview-container="true"]');
-      if (!result) {
-        return { error: true, message: 'No preview container found. Navigate to a component first.' };
-      }
-
-      const total = result.passes + result.violations.length + result.incomplete;
-      const wcagScore = total > 0 ? Math.round((result.passes / total) * 100) : 100;
-
-      return {
-        component,
-        wcagScore,
-        standard,
-        violations: result.violations,
-        passCount: result.passes,
-        incompleteCount: result.incomplete,
-        counts: result.counts,
-      };
-    },
-  });
-
-  // --- fragments_theme ---
-  tools.push({
-    name: 'fragments_theme',
-    description: 'Inspect the current runtime theme state. Returns the resolved theme (light/dark), seed configuration values, and computed CSS token values from the live DOM.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        category: { type: 'string', description: 'Filter tokens by category (e.g., "colors", "spacing")' },
-        search: { type: 'string', description: 'Search token names' },
-        includeComputed: { type: 'boolean', default: true, description: 'Include computed CSS values' },
-      },
-    } as InputSchema,
-    annotations: { readOnlyHint: true },
-    execute: async (input) => {
-      const category = input.category as string | undefined;
-      const search = input.search as string | undefined;
-      const includeComputed = input.includeComputed !== false;
-
-      const root = document.documentElement;
-      const computedStyle = getComputedStyle(root);
-
-      // Detect theme
-      const resolvedTheme = root.classList.contains('dark') ? 'dark' : 'light';
-
-      // Read seed values
-      const seed = {
-        brand: computedStyle.getPropertyValue('--fui-seed-brand').trim() || null,
-        neutral: computedStyle.getPropertyValue('--fui-seed-neutral').trim() || null,
-        radius: computedStyle.getPropertyValue('--fui-seed-radius').trim() || null,
-        density: computedStyle.getPropertyValue('--fui-seed-density').trim() || null,
-      };
-
-      // Get tokens from compiled data
-      const compiledData = options.compiledData;
-      const tokenEntries: Array<{ name: string; value: string; computed?: string; category?: string }> = [];
-
-      if (compiledData?.tokens?.categories) {
-        for (const [cat, entries] of Object.entries(compiledData.tokens.categories)) {
-          if (category && cat.toLowerCase() !== category.toLowerCase()) continue;
-
-          for (const token of entries) {
-            if (search && !token.name.toLowerCase().includes(search.toLowerCase())) continue;
-
-            const entry: { name: string; value: string; computed?: string; category?: string } = {
-              name: token.name,
-              value: token.value,
-              category: cat,
-            };
-
-            if (includeComputed) {
-              entry.computed = computedStyle.getPropertyValue(token.name).trim() || token.value;
-            }
-
-            tokenEntries.push(entry);
-          }
-        }
-      }
-
-      return {
-        resolvedTheme,
-        seed,
-        tokens: tokenEntries,
-        tokenCount: tokenEntries.length,
-      };
-    },
-  });
-
-  // --- fragments_context ---
-  tools.push({
-    name: 'fragments_context',
-    description: 'Get information about what the developer is currently viewing in the Fragments dev viewer. Returns the active component, variant, viewport settings, theme, and panel state.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        fields: {
-          type: 'array',
-          items: { type: 'string' },
-          description: 'Specific fields to return (e.g., ["currentComponent", "theme"]). Returns all fields if omitted.',
-        },
-      },
-    } as InputSchema,
-    annotations: { readOnlyHint: true },
-    execute: async (input) => {
-      const state = getViewerState();
-      const fields = input.fields as string[] | undefined;
-
-      if (fields && fields.length > 0) {
-        const filtered: Record<string, unknown> = {};
-        for (const field of fields) {
-          if (field in state) {
-            filtered[field] = state[field as keyof typeof state];
-          }
-        }
-        return filtered;
-      }
-
-      return state;
-    },
-  });
-
-  return tools;
-}

package/src/viewer/webmcp/scan-utils.ts

@@ -1,135 +0,0 @@
-import type { Result } from 'axe-core';
-import type { SerializedViolation } from '../types/a11y.js';
-
-// 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
- */
-export 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
- */
-export 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,
-  };
-}

package/src/viewer/webmcp/use-tool-analytics.ts

@@ -1,69 +0,0 @@
-import { useEffect, useRef, useState, useCallback } from 'react';
-import { useWebMCPContext } from '@fragments-sdk/webmcp/react';
-import type { ToolCallEvent } from '@fragments-sdk/webmcp';
-import { ToolAnalyticsCollector } from './analytics.js';
-import { createPostHogBridge } from './posthog-bridge.js';
-
-interface UseToolAnalyticsResult {
-  collector: ToolAnalyticsCollector;
-  summary: ReturnType<ToolAnalyticsCollector['toSummary']> | null;
-  refreshSummary: () => void;
-}
-
-export function useToolAnalytics(): UseToolAnalyticsResult {
-  const { shimRegistry } = useWebMCPContext();
-  const collectorRef = useRef(new ToolAnalyticsCollector());
-  const [summary, setSummary] = useState<ReturnType<ToolAnalyticsCollector['toSummary']> | null>(null);
-
-  const refreshSummary = useCallback(() => {
-    setSummary(collectorRef.current.toSummary());
-  }, []);
-
-  useEffect(() => {
-    if (!shimRegistry) return;
-
-    const posthog = (window as any).posthog as { capture(event: string, properties?: Record<string, unknown>): void } | undefined;
-    const bridge = posthog
-      ? createPostHogBridge(posthog, collectorRef.current)
-      : null;
-
-    const onToolCall = (event: ToolCallEvent) => {
-      collectorRef.current.record(event);
-      bridge?.onToolCall(event);
-      // Auto-refresh summary every 5 calls
-      const total = collectorRef.current.toSummary().totalCalls;
-      if (total % 5 === 0) {
-        setSummary(collectorRef.current.toSummary());
-      }
-    };
-
-    shimRegistry.addEventListener('toolcall', onToolCall);
-
-    // Fire session summary on page unload
-    const handleVisibilityChange = () => {
-      if (document.visibilityState === 'hidden') {
-        bridge?.onSessionEnd();
-      }
-    };
-
-    const handleBeforeUnload = () => {
-      bridge?.flush();
-    };
-
-    document.addEventListener('visibilitychange', handleVisibilityChange);
-    window.addEventListener('beforeunload', handleBeforeUnload);
-
-    return () => {
-      shimRegistry.removeEventListener('toolcall', onToolCall);
-      document.removeEventListener('visibilitychange', handleVisibilityChange);
-      window.removeEventListener('beforeunload', handleBeforeUnload);
-      bridge?.onSessionEnd();
-    };
-  }, [shimRegistry]);
-
-  return {
-    collector: collectorRef.current,
-    summary,
-    refreshSummary,
-  };
-}

package/src/viewer/webmcp/viewer-state.ts

@@ -1,45 +0,0 @@
-export interface ViewerState {
-  currentComponent: string | null;
-  currentVariant: string | null;
-  variantIndex: number;
-  totalVariants: number;
-  viewport: string;
-  zoom: number;
-  theme: string;
-  panels: {
-    activePanel: string;
-    panelOpen: boolean;
-  };
-  viewMode: {
-    matrixView: boolean;
-    multiViewport: boolean;
-    comparison: boolean;
-  };
-  designSystem: {
-    name: string;
-    componentCount: number;
-  };
-}
-
-const DEFAULT_STATE: ViewerState = {
-  currentComponent: null,
-  currentVariant: null,
-  variantIndex: 0,
-  totalVariants: 0,
-  viewport: 'responsive',
-  zoom: 100,
-  theme: 'light',
-  panels: { activePanel: 'code', panelOpen: true },
-  viewMode: { matrixView: false, multiViewport: false, comparison: false },
-  designSystem: { name: 'Fragments', componentCount: 0 },
-};
-
-let currentState: ViewerState = { ...DEFAULT_STATE };
-
-export function setViewerState(state: Partial<ViewerState>): void {
-  currentState = { ...currentState, ...state };
-}
-
-export function getViewerState(): ViewerState {
-  return currentState;
-}