@pennyfarthing/core 11.3.8 → 11.4.0

package/packages/core/src/public/hooks/useGitStatus.ts

@@ -0,0 +1,233 @@
+/**
+ * useGitStatus Hook
+ *
+ * React hook for subscribing to git status data.
+ * Story MSSCI-12717 - React Migration
+ * Story MSSCI-12781 - Fixed to handle multi-repo response format
+ * Story MSSCI-12798 - Expose full repo array for stacked display
+ * Story MSSCI-12860 - IPC to WebSocket Migration (Phase 1)
+ *
+ * Uses WebSocket /ws/git for real-time updates (no polling).
+ */
+
+import { useState, useEffect, useRef } from 'react';
+
+export interface GitStatusData {
+  branch: string;
+  ahead?: number;
+  behind?: number;
+  staged?: number;
+  modified?: number;
+  untracked?: number;
+  isDirty?: boolean;
+}
+
+/** Per-repo status data for stacked display */
+export interface RepoStatusData {
+  name: string;
+  path: string;
+  branch: string;
+  ahead?: number;
+  behind?: number;
+  /** Commits origin/develop has that this branch doesn't (needs pull/rebase) */
+  developBehind?: number;
+  staged: number;
+  modified: number;
+  untracked: number;
+  isDirty: boolean;
+  files: DirtyFile[];
+}
+
+/** Dirty file from git status --porcelain */
+export interface DirtyFile {
+  status: string;  // M, A, D, ?, etc.
+  path: string;
+}
+
+/** Raw repo git info from server */
+interface RepoGitInfo {
+  name: string;
+  path: string;
+  branch: string;
+  clean: boolean;
+  ahead: number | null;
+  behind: number | null;
+  developBehind: number | null;
+  dirtyFiles: DirtyFile[];
+}
+
+/** WebSocket message format from /ws/git */
+interface GitMessage {
+  type: 'init' | 'update';
+  repos: RepoGitInfo[];
+}
+
+/**
+ * Count files by type from dirty files array
+ */
+function countFilesByType(dirtyFiles: DirtyFile[]): { staged: number; modified: number; untracked: number } {
+  let staged = 0;
+  let modified = 0;
+  let untracked = 0;
+
+  for (const file of dirtyFiles) {
+    // Git status codes:
+    // First char = staging area, Second char = working tree
+    // M = modified, A = added (staged), D = deleted, ? = untracked
+    const indexStatus = file.status[0] || ' ';
+    const workTreeStatus = file.status[1] || ' ';
+
+    // Staged files (anything in the index that's not space or ?)
+    if (indexStatus !== ' ' && indexStatus !== '?') {
+      staged++;
+    }
+
+    // Modified in working tree (not staged)
+    if (workTreeStatus === 'M' || workTreeStatus === 'D') {
+      modified++;
+    }
+
+    // Untracked files
+    if (indexStatus === '?' && workTreeStatus === '?') {
+      untracked++;
+    }
+  }
+
+  return { staged, modified, untracked };
+}
+
+/**
+ * Transform raw git response to per-repo status array for stacked display
+ */
+function transformToRepoArray(repos: RepoGitInfo[]): RepoStatusData[] {
+  if (!repos?.length) {
+    return [];
+  }
+
+  return repos.map(repo => {
+    const counts = countFilesByType(repo.dirtyFiles);
+    return {
+      name: repo.name,
+      path: repo.path,
+      branch: repo.branch,
+      ahead: repo.ahead ?? undefined,
+      behind: repo.behind ?? undefined,
+      developBehind: repo.developBehind ?? undefined,
+      staged: counts.staged,
+      modified: counts.modified,
+      untracked: counts.untracked,
+      isDirty: !repo.clean,
+      files: repo.dirtyFiles,
+    };
+  });
+}
+
+/**
+ * Transform raw git response to GitStatusData for display (legacy aggregated view)
+ * Uses first repo for branch info, aggregates file counts across all repos
+ */
+function transformGitResponse(repos: RepoGitInfo[]): GitStatusData | null {
+  if (!repos?.length) {
+    return null;
+  }
+
+  // Use first repo as primary (usually the orchestrator or main repo)
+  const primaryRepo = repos[0];
+
+  // Count file types across all repos
+  let staged = 0;
+  let modified = 0;
+  let untracked = 0;
+
+  for (const repo of repos) {
+    const counts = countFilesByType(repo.dirtyFiles);
+    staged += counts.staged;
+    modified += counts.modified;
+    untracked += counts.untracked;
+  }
+
+  // Check if any repo is dirty
+  const isDirty = repos.some(repo => !repo.clean);
+
+  return {
+    branch: primaryRepo.branch,
+    ahead: primaryRepo.ahead ?? undefined,
+    behind: primaryRepo.behind ?? undefined,
+    staged: staged > 0 ? staged : undefined,
+    modified: modified > 0 ? modified : undefined,
+    untracked: untracked > 0 ? untracked : undefined,
+    isDirty,
+  };
+}
+
+interface UseGitStatusResult {
+  gitStatus: GitStatusData | null;
+  repos: RepoStatusData[];
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export function useGitStatus(): UseGitStatusResult {
+  const [gitStatus, setGitStatus] = useState<GitStatusData | null>(null);
+  const [repos, setRepos] = useState<RepoStatusData[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => {
+    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const wsUrl = `${protocol}//${window.location.host}/ws/git`;
+
+    const connect = () => {
+      try {
+        wsRef.current = new WebSocket(wsUrl);
+
+        wsRef.current.onopen = () => {
+          console.debug('[useGitStatus] WebSocket connected');
+        };
+
+        wsRef.current.onmessage = (event) => {
+          try {
+            const msg = JSON.parse(event.data) as GitMessage;
+            if (msg.type === 'init' || msg.type === 'update') {
+              setGitStatus(transformGitResponse(msg.repos));
+              setRepos(transformToRepoArray(msg.repos));
+              setIsLoading(false);
+              setError(null);
+            }
+          } catch (err) {
+            console.error('[useGitStatus] Failed to parse message:', err);
+          }
+        };
+
+        wsRef.current.onclose = () => {
+          console.debug('[useGitStatus] WebSocket closed, reconnecting...');
+          reconnectTimeoutRef.current = setTimeout(connect, 2000);
+        };
+
+        wsRef.current.onerror = (err) => {
+          console.error('[useGitStatus] WebSocket error:', err);
+          setError(new Error('WebSocket connection failed'));
+        };
+      } catch (err) {
+        console.error('[useGitStatus] WebSocket init failed:', err);
+        setError(err instanceof Error ? err : new Error('Failed to connect'));
+        setIsLoading(false);
+      }
+    };
+
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+    };
+  }, []);
+
+  return { gitStatus, repos, isLoading, error };
+}

package/packages/core/src/public/hooks/useHealthScore.ts

@@ -0,0 +1,71 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+export interface HealthScoreDimension {
+  name: string;
+  score: number | null;
+  weight: number;
+}
+
+export interface HealthScoreData {
+  success: boolean;
+  composite_score: number;
+  dimensions: HealthScoreDimension[];
+  cached: boolean;
+  error?: string;
+}
+
+export interface UseHealthScoreReturn {
+  data: HealthScoreData | null;
+  isLoading: boolean;
+  error: Error | null;
+  lastFetchedAt: number | null;
+  refresh: () => void;
+}
+
+export function useHealthScore(): UseHealthScoreReturn {
+  const [data, setData] = useState<HealthScoreData | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [lastFetchedAt, setLastFetchedAt] = useState<number | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const refresh = useCallback(() => {
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsLoading(true);
+    setError(null);
+
+    fetch('/api/health-score', { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+      })
+      .then((json: HealthScoreData) => {
+        setData(json);
+        setLastFetchedAt(Date.now());
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+  }, []);
+
+  // Auto-fetch on mount
+  useEffect(() => {
+    refresh();
+    return () => {
+      abortRef.current?.abort();
+    };
+  }, [refresh]);
+
+  return { data, isLoading, error, lastFetchedAt, refresh };
+}

package/packages/core/src/public/hooks/useHotspots.ts

@@ -0,0 +1,123 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+// Types matching Python HotspotResult / MultiRepoHotspotResult
+export interface FileHotspot {
+  path: string;
+  change_count: number;
+  bug_fix_count: number;
+  author_count: number;
+  lines_added: number;
+  lines_deleted: number;
+  churn: number;
+  last_changed: string;
+  hotspot_score: number;
+}
+
+export interface DirectoryHotspot {
+  path: string;
+  file_count: number;
+  total_changes: number;
+  total_bug_fixes: number;
+  avg_author_count: number;
+  hotspot_score: number;
+}
+
+export interface HotspotRepoResult {
+  success: boolean;
+  repo_name: string;
+  repo_path: string;
+  time_window_days: number;
+  commit_count: number;
+  file_hotspots: FileHotspot[];
+  directory_hotspots: DirectoryHotspot[];
+  error?: string;
+}
+
+export interface HotspotData {
+  success: boolean;
+  // Single-repo result fields (when --path is used)
+  repo_name?: string;
+  repo_path?: string;
+  time_window_days?: number;
+  commit_count?: number;
+  file_hotspots?: FileHotspot[];
+  directory_hotspots?: DirectoryHotspot[];
+  // Multi-repo result fields
+  repo_results?: HotspotRepoResult[];
+  error?: string;
+}
+
+export interface UseHotspotsOptions {
+  days: number;
+  repo?: string;
+  skipTypes?: string[];
+  includeOrchestrator?: boolean;
+}
+
+export interface UseHotspotsReturn {
+  data: HotspotData | null;
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => void;
+}
+
+export function useHotspots(options: UseHotspotsOptions): UseHotspotsReturn {
+  const [data, setData] = useState<HotspotData | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const fetchHotspots = useCallback(() => {
+    // Cancel any in-flight request
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+
+    const controller = new AbortController();
+    abortRef.current = controller;
+
+    setIsLoading(true);
+    setError(null);
+
+    const params = new URLSearchParams({ days: String(options.days) });
+    if (options.repo) {
+      params.set('repo', options.repo);
+    }
+
+    // Determine skip_type values: use explicit skipTypes, or default to ['orchestrator']
+    // unless includeOrchestrator is true
+    const skipTypes = options.skipTypes ??
+      (options.includeOrchestrator ? [] : ['orchestrator']);
+    for (const st of skipTypes) {
+      params.append('skip_type', st);
+    }
+
+    fetch(`/api/hotspots?${params}`, { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        return res.json();
+      })
+      .then((json: HotspotData) => {
+        setData(json);
+        setIsLoading(false);
+      })
+      .catch((err) => {
+        if (err.name === 'AbortError') return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setIsLoading(false);
+      });
+  }, [options.days, options.repo, options.skipTypes, options.includeOrchestrator]);
+
+  // Cleanup abort controller on unmount
+  useEffect(() => {
+    return () => {
+      if (abortRef.current) {
+        abortRef.current.abort();
+      }
+    };
+  }, []);
+
+  return { data, isLoading, error, refresh: fetchHotspots };
+}

package/packages/core/src/public/hooks/useLayoutPersistence.ts

@@ -0,0 +1,141 @@
+/**
+ * useLayoutPersistence Hook
+ *
+ * React hook for saving and restoring layout state to config.local.yaml.
+ * Story MSSCI-12706 - Layout Persistence
+ *
+ * Uses native Dockview SerializedDockview format for complete layout fidelity.
+ *
+ * REST API:
+ * - GET /api/settings/layout - Load layout
+ * - PATCH /api/settings/layout - Save layout
+ *
+ * Features:
+ * - Load layout from config on mount
+ * - Save layout on changes (debounced)
+ * - Per-project independent layouts
+ * - Graceful handling of corrupted/missing config
+ * - Native Dockview serialization for perfect restore
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { SerializedDockview } from 'dockview-react';
+
+const DEBOUNCE_DELAY = 300;
+
+interface UseLayoutPersistenceResult {
+  layout: SerializedDockview | null;
+  isLoading: boolean;
+  isSaving: boolean;
+  error: Error | null;
+  saveLayout: (layout: SerializedDockview) => void;
+}
+
+/**
+ * Validate that the layout has the native Dockview structure
+ */
+function isValidDockviewLayout(layout: unknown): layout is SerializedDockview {
+  if (!layout || typeof layout !== 'object') return false;
+  const layoutObj = layout as Record<string, unknown>;
+
+  // Check for native Dockview structure: grid and panels are required
+  if (!layoutObj.grid || typeof layoutObj.grid !== 'object') return false;
+  if (!layoutObj.panels || typeof layoutObj.panels !== 'object') return false;
+
+  // A layout with zero panels is empty — treat as invalid so default panels get created
+  if (Object.keys(layoutObj.panels as Record<string, unknown>).length === 0) return false;
+
+  const grid = layoutObj.grid as Record<string, unknown>;
+  // Grid should have root, width, height, orientation
+  if (!grid.root || typeof grid.width !== 'number' || typeof grid.height !== 'number') return false;
+
+  return true;
+}
+
+export function useLayoutPersistence(endpoint: string = '/api/settings/layout'): UseLayoutPersistenceResult {
+  const [layout, setLayout] = useState<SerializedDockview | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isSaving, setIsSaving] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pendingLayoutRef = useRef<SerializedDockview | null>(null);
+
+  // Load layout on mount via REST API
+  useEffect(() => {
+    const loadLayout = async () => {
+      try {
+        const response = await fetch(endpoint);
+        if (response.ok) {
+          const data = await response.json();
+          if (data.layout && isValidDockviewLayout(data.layout)) {
+            // Use native Dockview layout directly
+            setLayout(data.layout as SerializedDockview);
+          } else {
+            // No saved layout or invalid format - let DockviewWorkspace build default
+            setLayout(null);
+          }
+        } else {
+          // API error - let DockviewWorkspace build default
+          setLayout(null);
+        }
+      } catch (err) {
+        // On error, let DockviewWorkspace build default
+        console.error('[useLayoutPersistence] Failed to load layout:', err);
+        setLayout(null);
+        setError(err instanceof Error ? err : new Error('Failed to load layout'));
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    loadLayout();
+  }, [endpoint]);
+
+  // Debounced save function via REST API - saves native Dockview format directly
+  const saveLayout = useCallback((newLayout: SerializedDockview) => {
+    pendingLayoutRef.current = newLayout;
+
+    // Clear existing debounce timer
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Set new debounce timer
+    debounceRef.current = setTimeout(async () => {
+      const layoutToSave = pendingLayoutRef.current;
+      if (!layoutToSave) return;
+
+      setIsSaving(true);
+      try {
+        // Save native Dockview format directly - no conversion needed
+        const response = await fetch(endpoint, {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(layoutToSave),
+        });
+
+        if (!response.ok) {
+          throw new Error('Failed to save layout');
+        }
+        setError(null);
+      } catch (err) {
+        console.error('[useLayoutPersistence] Failed to save layout:', err);
+        setError(err instanceof Error ? err : new Error('Failed to save layout'));
+      } finally {
+        setIsSaving(false);
+      }
+    }, DEBOUNCE_DELAY);
+  }, [endpoint]);
+
+  // Cleanup debounce timer on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, []);
+
+  return { layout, isLoading, isSaving, error, saveLayout };
+}

package/packages/core/src/public/hooks/useMarkdownParser.ts

@@ -0,0 +1,36 @@
+/**
+ * useMarkdownParser Hook
+ *
+ * Story MSSCI-13969: React hook for parsing markdown to HTML with security.
+ * Extracted from js/components/message-view/markdown-parser.js
+ *
+ * Features:
+ * - XSS prevention via HTML escaping
+ * - CYCLIST marker stripping
+ * - Memoization for performance
+ */
+
+import { useMemo } from 'react';
+import { parseMarkdown } from '../utils/markdown.js';
+
+export interface UseMarkdownParserResult {
+  html: string;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+/**
+ * React hook for parsing markdown to HTML with security and memoization.
+ * @param markdown - Raw markdown text (or null)
+ * @returns Object with html string, loading state, and error
+ */
+export function useMarkdownParser(
+  markdown: string | null
+): UseMarkdownParserResult {
+  const html = useMemo(() => {
+    if (!markdown) return '';
+    return parseMarkdown(markdown);
+  }, [markdown]);
+
+  return { html, isLoading: false, error: null };
+}