@datarecce/ui 0.1.39 → 0.1.41

package/recce-source/js/src/lib/csv/format.ts

@@ -0,0 +1,44 @@
+/**
+ * CSV formatting utilities with Excel-friendly output
+ */
+
+/**
+ * Escape a value for CSV format
+ * - Wrap in quotes if contains comma, quote, or newline
+ * - Escape quotes by doubling them
+ */
+function escapeCSVValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  const stringValue =
+    typeof value === "object" ? JSON.stringify(value) : String(value);
+
+  // Check if escaping is needed
+  if (
+    stringValue.includes(",") ||
+    stringValue.includes('"') ||
+    stringValue.includes("\n") ||
+    stringValue.includes("\r")
+  ) {
+    return `"${stringValue.replace(/"/g, '""')}"`;
+  }
+
+  return stringValue;
+}
+
+/**
+ * Convert tabular data to CSV string
+ * @param columns - Column headers
+ * @param rows - Row data (array of arrays)
+ * @returns CSV string with UTF-8 BOM for Excel compatibility
+ */
+export function toCSV(columns: string[], rows: unknown[][]): string {
+  const BOM = "\uFEFF";
+
+  const headerRow = columns.map(escapeCSVValue).join(",");
+  const dataRows = rows.map((row) => row.map(escapeCSVValue).join(","));
+
+  return BOM + [headerRow, ...dataRows].join("\r\n");
+}

package/recce-source/js/src/lib/csv/index.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for CSV utility functions
+ */
+import { generateCSVFilename, generateTimestamp } from "./index";
+
+describe("generateTimestamp", () => {
+  test("should return timestamp in YYYYMMDD-HHmmss format", () => {
+    const timestamp = generateTimestamp();
+
+    // Should match format like 20240101-123456
+    expect(timestamp).toMatch(/^\d{8}-\d{6}$/);
+  });
+
+  test("should generate consistent length timestamps", () => {
+    const timestamps = Array.from({ length: 5 }, () => generateTimestamp());
+
+    for (const ts of timestamps) {
+      expect(ts.length).toBe(15); // 8 + 1 + 6 = 15 characters
+    }
+  });
+});
+
+describe("generateCSVFilename", () => {
+  describe("basic filename generation", () => {
+    test("should include run type in filename", () => {
+      const filename = generateCSVFilename("query_diff", {});
+
+      expect(filename).toMatch(/^query-diff-.*\.csv$/);
+    });
+
+    test("should replace underscores with hyphens in run type", () => {
+      const filename = generateCSVFilename("row_count_diff", {});
+
+      expect(filename).toContain("row-count-diff");
+      expect(filename).not.toContain("_");
+    });
+
+    test("should end with .csv extension", () => {
+      const filename = generateCSVFilename("query", {});
+
+      expect(filename).toMatch(/\.csv$/);
+    });
+
+    test("should include timestamp", () => {
+      const filename = generateCSVFilename("query", {});
+
+      // Should have timestamp pattern before .csv
+      expect(filename).toMatch(/\d{8}-\d{6}\.csv$/);
+    });
+  });
+
+  describe("node name extraction", () => {
+    test("should include single node name from node_names array", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["my_model"],
+      });
+
+      expect(filename).toContain("my_model");
+    });
+
+    test("should not include node name if multiple in array", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["model1", "model2"],
+      });
+
+      expect(filename).not.toContain("model1");
+      expect(filename).not.toContain("model2");
+      expect(filename).toContain("result");
+    });
+
+    test("should include model name from params", () => {
+      const filename = generateCSVFilename("profile", {
+        model: "customers",
+      });
+
+      expect(filename).toContain("customers");
+    });
+
+    test("should prefer node_names over model", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["from_node"],
+        model: "from_model",
+      });
+
+      expect(filename).toContain("from_node");
+      expect(filename).not.toContain("from_model");
+    });
+  });
+
+  describe("node name sanitization", () => {
+    test("should convert to lowercase", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["MyModel"],
+      });
+
+      expect(filename).toContain("mymodel");
+      expect(filename).not.toContain("MyModel");
+    });
+
+    test("should preserve dots for schema.table patterns", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["schema.table_name"],
+      });
+
+      expect(filename).toContain("schema.table_name");
+    });
+
+    test("should replace special characters with hyphens", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["model/with/slashes"],
+      });
+
+      expect(filename).toContain("model-with-slashes");
+      expect(filename).not.toContain("/");
+    });
+
+    test("should handle spaces", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["model with spaces"],
+      });
+
+      expect(filename).toContain("model-with-spaces");
+    });
+
+    test("should preserve underscores and hyphens", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: ["my_model-name"],
+      });
+
+      expect(filename).toContain("my_model-name");
+    });
+  });
+
+  describe("fallback behavior", () => {
+    test("should use 'result' when no node name available", () => {
+      const filename = generateCSVFilename("query", {});
+
+      expect(filename).toMatch(/^query-result-\d{8}-\d{6}\.csv$/);
+    });
+
+    test("should handle undefined params", () => {
+      const filename = generateCSVFilename("query", undefined);
+
+      expect(filename).toMatch(/^query-result-\d{8}-\d{6}\.csv$/);
+    });
+
+    test("should handle empty node_names array", () => {
+      const filename = generateCSVFilename("query", {
+        node_names: [],
+      });
+
+      expect(filename).toContain("result");
+    });
+  });
+});

package/recce-source/js/src/lib/csv/index.ts

@@ -0,0 +1,109 @@
+/**
+ * CSV export utilities
+ */
+import saveAs from "file-saver";
+
+export { toCSV } from "./format";
+
+/**
+ * Trigger browser download of CSV file
+ */
+export function downloadCSV(content: string, filename: string): void {
+  const blob = new Blob([content], { type: "text/csv;charset=utf-8" });
+  saveAs(blob, filename);
+}
+
+/**
+ * Copy CSV content to clipboard
+ * Uses modern Clipboard API with fallback for older browsers
+ */
+export async function copyCSVToClipboard(content: string): Promise<void> {
+  // Prefer modern async Clipboard API when available in a browser context
+  if (
+    typeof navigator !== "undefined" &&
+    navigator.clipboard &&
+    typeof navigator.clipboard.writeText === "function"
+  ) {
+    await navigator.clipboard.writeText(content);
+    return;
+  }
+
+  // Fallback for older browsers or non-secure contexts using execCommand
+  if (typeof document === "undefined") {
+    // In non-DOM environments (e.g., SSR), throw error
+    throw new Error("Clipboard API not available in this environment");
+  }
+
+  const textarea = document.createElement("textarea");
+  textarea.value = content;
+  textarea.style.position = "fixed"; // avoid scrolling to bottom
+  textarea.style.opacity = "0";
+  textarea.setAttribute("readonly", "");
+  document.body.appendChild(textarea);
+
+  textarea.focus();
+  textarea.select();
+
+  try {
+    const success = document.execCommand("copy");
+    if (!success) {
+      throw new Error("execCommand('copy') failed");
+    }
+  } finally {
+    document.body.removeChild(textarea);
+  }
+}
+
+/**
+ * Generate timestamp string for filenames
+ * Format: YYYYMMDD-HHmmss
+ */
+export function generateTimestamp(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const hours = String(now.getHours()).padStart(2, "0");
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const seconds = String(now.getSeconds()).padStart(2, "0");
+  return `${year}${month}${day}-${hours}${minutes}${seconds}`;
+}
+
+/**
+ * Generate context-aware CSV filename
+ */
+export function generateCSVFilename(
+  runType: string,
+  params?: Record<string, unknown>,
+): string {
+  const timestamp = generateTimestamp();
+  const type = runType.replace(/_/g, "-");
+
+  // Try to extract node name from params
+  let nodeName: string | undefined;
+
+  if (
+    params?.node_names &&
+    Array.isArray(params.node_names) &&
+    params.node_names.length === 1
+  ) {
+    nodeName = String(params.node_names[0]);
+  } else if (params?.model && typeof params.model === "string") {
+    nodeName = params.model;
+  }
+
+  // Sanitize node name for filesystem (preserve dots for schema.table patterns)
+  if (nodeName) {
+    nodeName = nodeName.replace(/[^a-zA-Z0-9_.-]/g, "-").toLowerCase();
+    return `${type}-${nodeName}-${timestamp}.csv`;
+  }
+
+  return `${type}-result-${timestamp}.csv`;
+}
+
+export {
+  type CSVData,
+  type CSVExportOptions,
+  extractCSVData,
+  supportsCSVExport,
+} from "./extractors";

package/recce-source/js/src/lib/hooks/useCSVExport.ts

@@ -0,0 +1,136 @@
+/**
+ * Hook for CSV export functionality
+ */
+import { useCallback, useMemo } from "react";
+import { toaster } from "@/components/ui/toaster";
+import type { Run } from "@/lib/api/types";
+import {
+  type CSVExportOptions,
+  copyCSVToClipboard,
+  downloadCSV,
+  extractCSVData,
+  generateCSVFilename,
+  supportsCSVExport,
+  toCSV,
+} from "@/lib/csv";
+
+interface UseCSVExportOptions {
+  run?: Run;
+  /** View options - displayMode is extracted if present (for query_diff views) */
+  viewOptions?: Record<string, unknown>;
+}
+
+interface UseCSVExportResult {
+  /** Whether CSV export is available for this run type */
+  canExportCSV: boolean;
+  /** Copy result data as CSV to clipboard */
+  copyAsCSV: () => Promise<void>;
+  /** Download result data as CSV file */
+  downloadAsCSV: () => void;
+}
+
+export function useCSVExport({
+  run,
+  viewOptions,
+}: UseCSVExportOptions): UseCSVExportResult {
+  const canExportCSV = useMemo(() => {
+    if (!run?.type || !run?.result) return false;
+    return supportsCSVExport(run.type);
+  }, [run?.type, run?.result]);
+
+  const getCSVContent = useCallback((): string | null => {
+    if (!run?.type || !run?.result) return null;
+
+    // Extract display_mode from viewOptions if it exists (for query_diff)
+    const displayMode = viewOptions?.display_mode as
+      | "inline"
+      | "side_by_side"
+      | undefined;
+
+    // Extract primary_keys from run params (for query_diff with primary keys)
+    const primaryKeys = (run?.params as { primary_keys?: string[] })
+      ?.primary_keys;
+
+    const exportOptions: CSVExportOptions = {
+      displayMode,
+      primaryKeys,
+    };
+
+    const csvData = extractCSVData(run.type, run.result, exportOptions);
+    if (!csvData) return null;
+
+    return toCSV(csvData.columns, csvData.rows);
+  }, [run?.type, run?.result, run?.params, viewOptions]);
+
+  const copyAsCSV = useCallback(async () => {
+    const content = getCSVContent();
+    if (!content) {
+      toaster.create({
+        title: "Export failed",
+        description: "Unable to extract data for CSV export",
+        type: "error",
+        duration: 3000,
+      });
+      return;
+    }
+
+    try {
+      await copyCSVToClipboard(content);
+      toaster.create({
+        title: "Copied to clipboard",
+        description: "CSV data copied successfully",
+        type: "success",
+        duration: 2000,
+      });
+    } catch (error) {
+      console.error("Failed to copy CSV to clipboard:", error);
+      toaster.create({
+        title: "Copy failed",
+        description: "Failed to copy to clipboard",
+        type: "error",
+        duration: 3000,
+      });
+    }
+  }, [getCSVContent]);
+
+  const downloadAsCSV = useCallback(() => {
+    const content = getCSVContent();
+    if (!content) {
+      toaster.create({
+        title: "Export failed",
+        description: "Unable to extract data for CSV export",
+        type: "error",
+        duration: 3000,
+      });
+      return;
+    }
+
+    try {
+      const filename = generateCSVFilename(
+        run?.type ?? "",
+        run?.params as Record<string, unknown>,
+      );
+      downloadCSV(content, filename);
+      toaster.create({
+        title: "Downloaded",
+        description: filename,
+        type: "success",
+        duration: 3000,
+      });
+    } catch (error) {
+      console.error("Failed to download CSV file:", error);
+      toaster.create({
+        title: "Download failed",
+        description: "Failed to download CSV file",
+        type: "error",
+        duration: 3000,
+      });
+    }
+  }, [getCSVContent, run]);
+
+  return {
+    canExportCSV,
+    copyAsCSV,
+    downloadAsCSV,
+  };
+}

package/recce-source/recce/mcp_server.py

@@ -115,8 +115,10 @@ class RecceMCPServer:
         mode: Optional[RecceServerMode] = None,
         debug: bool = False,
         log_file: str = "logs/recce-mcp.json",
+        state_loader=None,
     ):
         self.context = context
+        self.state_loader = state_loader
         self.mode = mode or RecceServerMode.server
         self.server = Server("recce")
         self.mcp_logger = MCPLogger(debug=debug, log_file=log_file)
@@ -733,8 +735,30 @@ class RecceMCPServer:
 
     async def run(self):
         """Run the MCP server in stdio mode"""
-        async with stdio_server() as (read_stream, write_stream):
-            await self.server.run(read_stream, write_stream, self.server.create_initialization_options())
+        try:
+            async with stdio_server() as (read_stream, write_stream):
+                await self.server.run(read_stream, write_stream, self.server.create_initialization_options())
+        finally:
+            # Export state on shutdown if state_loader is available
+            if self.state_loader and self.context:
+                try:
+                    from rich.console import Console
+
+                    console = Console()
+
+                    # Export the state
+                    msg = self.state_loader.export(self.context.export_state())
+                    if msg is not None:
+                        console.print(f"[yellow]On shutdown:[/yellow] {msg}")
+                    else:
+                        if hasattr(self.state_loader, "state_file") and self.state_loader.state_file:
+                            console.print(
+                                f"[yellow]On shutdown:[/yellow] State exported to '{self.state_loader.state_file}'"
+                            )
+                        else:
+                            console.print("[yellow]On shutdown:[/yellow] State exported successfully")
+                except Exception as e:
+                    logger.exception(f"Failed to export state on shutdown: {e}")
 
     async def run_sse(self, host: str = "localhost", port: int = 8000):
         """Run the MCP server in HTTP mode using Server-Sent Events (SSE)
@@ -743,6 +767,8 @@ class RecceMCPServer:
             host: Host to bind to (default: localhost)
             port: Port to bind to (default: 8000)
         """
+        from contextlib import asynccontextmanager
+
         import uvicorn
         from mcp.server.sse import SseServerTransport
         from starlette.applications import Starlette
@@ -775,7 +801,22 @@ class RecceMCPServer:
             """Handle health check endpoint (GET /health)"""
             return Response(content='{"status":"ok"}', media_type="application/json")
 
-        # Create Starlette app
+        @asynccontextmanager
+        async def lifespan(app):
+            """Handle startup and shutdown events"""
+            # Startup
+            yield
+            # Shutdown - this runs when server exits (SIGINT, SIGTERM, etc.)
+            if self.state_loader and self.context:
+                try:
+                    logger.info("Exporting state on shutdown...")
+                    msg = self.state_loader.export(self.context.export_state())
+                    if msg:
+                        logger.info(f"State export: {msg}")
+                except Exception as e:
+                    logger.exception(f"Failed to export state on shutdown: {e}")
+
+        # Create Starlette app with lifespan
         app = Starlette(
             debug=self.mcp_logger.debug,
             routes=[
@@ -783,6 +824,7 @@ class RecceMCPServer:
                 Route("/sse", endpoint=handle_sse_request, methods=["GET"]),
                 Mount("/", app=handle_post_message),
             ],
+            lifespan=lifespan,
         )
 
         # Run with uvicorn
@@ -831,31 +873,13 @@ async def run_mcp_server(
     # Extract debug flag from kwargs
     debug = kwargs.get("debug", False)
 
-    # Create MCP server
-    server = RecceMCPServer(context, mode=mode, debug=debug)
-
-    try:
-        # Run in either stdio or SSE mode
-        if sse:
-            await server.run_sse(host=host, port=port)
-        else:
-            await server.run()
-    finally:
-        # Export state on shutdown if state_loader is available
-        if state_loader:
-            try:
-                from rich.console import Console
-
-                console = Console()
+    # Create MCP server with state_loader for graceful shutdown
+    server = RecceMCPServer(context, mode=mode, debug=debug, state_loader=state_loader)
 
-                # Export the state
-                msg = state_loader.export(context.export_state())
-                if msg is not None:
-                    console.print(f"[yellow]On shutdown:[/yellow] {msg}")
-                else:
-                    if hasattr(state_loader, "state_file") and state_loader.state_file:
-                        console.print(f"[yellow]On shutdown:[/yellow] State exported to '{state_loader.state_file}'")
-                    else:
-                        console.print("[yellow]On shutdown:[/yellow] State exported successfully")
-            except Exception as e:
-                logger.exception(f"Failed to export state on shutdown: {e}")
+    # Run in either stdio or SSE mode
+    if sse:
+        # SSE mode: lifespan handler in Starlette manages shutdown and state export
+        await server.run_sse(host=host, port=port)
+    else:
+        # Stdio mode: run() method handles shutdown and state export via try-finally
+        await server.run()

package/recce-source/recce/models/check.py

@@ -183,6 +183,14 @@ class CheckDAO:
         # Parse the type
         check_type = RunType(cloud_data.get("type"))
 
+        def parse_iso_datetime(iso_string: str):
+            """Parse ISO format datetime string, handling 'Z' suffix for UTC"""
+            if not iso_string:
+                return None
+            # Replace 'Z' with '+00:00' for Python's fromisoformat compatibility
+            iso_string = iso_string.replace("Z", "+00:00")
+            return datetime.fromisoformat(iso_string)
+
         return Check(
             check_id=UUID(cloud_data.get("id")),
             session_id=UUID(cloud_data.get("session_id")),
@@ -195,8 +203,8 @@ class CheckDAO:
             is_preset=cloud_data.get("is_preset", False),
             created_by=(cloud_data.get("created_by") or {}).get("email", ""),
             updated_by=(cloud_data.get("updated_by") or {}).get("email", ""),
-            created_at=datetime.fromisoformat(cloud_data["created_at"]) if cloud_data.get("created_at") else None,
-            updated_at=datetime.fromisoformat(cloud_data["updated_at"]) if cloud_data.get("updated_at") else None,
+            created_at=parse_iso_datetime(cloud_data.get("created_at")),
+            updated_at=parse_iso_datetime(cloud_data.get("updated_at")),
         )
 
     def create(self, check: Check) -> Check: