@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/GraphWorkspace/useMarkdownEditor.ts

@@ -0,0 +1,177 @@
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  MarkdownClientError,
+  applyMarkdownResource,
+  readMarkdownResource,
+  type MarkdownApplyResult,
+} from "./markdownResourceClient";
+import {
+  cancelEdit,
+  createEditSession,
+  createLoadingSession,
+  isDirty,
+  saveFailed,
+  saveStarted,
+  saveSucceeded,
+  updateDraft,
+  type MarkdownEditorError,
+  type MarkdownEditSession,
+  type MarkdownResourceRef,
+} from "./markdownEditorState";
+
+interface MarkdownEditorOptions {
+  resource?: MarkdownResourceRef;
+  onApplied?: (result: MarkdownApplyResult) => void;
+  onDirtyChange?: (dirty: boolean) => void;
+}
+
+interface KeyedError {
+  resourceKey: string;
+  error: MarkdownEditorError;
+}
+
+function keyOf(resource?: MarkdownResourceRef): string {
+  return resource ? `${resource.kind}:${resource.id}` : "";
+}
+
+function normalizeError(failure: unknown): MarkdownEditorError {
+  if (failure instanceof MarkdownClientError) return failure;
+  return {
+    kind: "network",
+    message: "The Markdown service could not be reached. Your draft was kept.",
+  };
+}
+
+export function useMarkdownEditor({
+  resource,
+  onApplied,
+  onDirtyChange,
+}: MarkdownEditorOptions) {
+  const resourceKey = keyOf(resource);
+  const [session, setSession] = useState<MarkdownEditSession | null>(null);
+  const [viewError, setViewError] = useState<KeyedError | null>(null);
+  const [renderedResourceKey, setRenderedResourceKey] = useState(resourceKey);
+  const loadGenerationRef = useRef(0);
+
+  if (renderedResourceKey !== resourceKey) {
+    setRenderedResourceKey(resourceKey);
+    setSession(null);
+    setViewError(null);
+  }
+
+  useLayoutEffect(() => {
+    loadGenerationRef.current += 1;
+  }, [resourceKey]);
+
+  const activeSession = session && keyOf(session.resource) === resourceKey
+    ? session
+    : null;
+  const dirty = isDirty(activeSession);
+  const editing = activeSession !== null
+    && activeSession.status !== "viewing"
+    && activeSession.status !== "loading-document";
+  const saving = activeSession?.status === "saving";
+  const loading = activeSession?.status === "loading-document";
+  const error = activeSession?.error
+    ?? (viewError?.resourceKey === resourceKey ? viewError.error : null);
+
+  useEffect(() => {
+    onDirtyChange?.(dirty);
+    return () => {
+      if (dirty) onDirtyChange?.(false);
+    };
+  }, [dirty, onDirtyChange]);
+
+  useEffect(() => {
+    if (!dirty) return;
+    const protectDraft = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      event.returnValue = "";
+    };
+    window.addEventListener("beforeunload", protectDraft);
+    return () => window.removeEventListener("beforeunload", protectDraft);
+  }, [dirty]);
+
+  const beginEdit = useCallback(async () => {
+    if (!resource) return false;
+    const loadGeneration = ++loadGenerationRef.current;
+    setViewError(null);
+    setSession(createLoadingSession(resource));
+    try {
+      const document = await readMarkdownResource(resource);
+      if (loadGeneration !== loadGenerationRef.current) return false;
+      setSession(createEditSession(resource, document));
+      return true;
+    } catch (failure) {
+      if (loadGeneration !== loadGenerationRef.current) return false;
+      setSession(null);
+      setViewError({ resourceKey, error: normalizeError(failure) });
+      return false;
+    }
+  }, [resource, resourceKey]);
+
+  const discard = useCallback(() => {
+    if (!activeSession || saving) return;
+    setSession(cancelEdit());
+    setViewError(null);
+  }, [activeSession, saving]);
+
+  const save = useCallback(async () => {
+    if (!activeSession || saving || !dirty) return false;
+    const resourceGeneration = loadGenerationRef.current;
+    const pending = saveStarted(activeSession);
+    setSession(pending);
+    try {
+      const result = await applyMarkdownResource(
+        pending.resource,
+        pending.draft,
+        pending.baseRevision,
+      );
+      if (resourceGeneration !== loadGenerationRef.current) return false;
+      setSession(saveSucceeded(pending, result));
+      onApplied?.(result);
+      return true;
+    } catch (failure) {
+      if (resourceGeneration !== loadGenerationRef.current) return false;
+      setSession(saveFailed(pending, normalizeError(failure)));
+      return false;
+    }
+  }, [activeSession, dirty, onApplied, saving]);
+
+  const reloadLatest = useCallback(async () => {
+    if (!resource || saving) return;
+    if (
+      dirty
+      && !window.confirm("Discard this draft and reload the latest applied version?")
+    ) return;
+    await beginEdit();
+  }, [beginEdit, dirty, resource, saving]);
+
+  const changeDraft = useCallback((draft: string) => {
+    setSession((current) => (
+      current && keyOf(current.resource) === resourceKey
+        ? updateDraft(current, draft)
+        : current
+    ));
+  }, [resourceKey]);
+
+  return {
+    session: activeSession,
+    error,
+    dirty,
+    editing,
+    saving,
+    loading,
+    beginEdit,
+    discard,
+    save,
+    reloadLatest,
+    changeDraft,
+  };
+}

package/explorer/src/workspaces/ImportExportWorkspace/ImportExportWorkspace.tsx

@@ -0,0 +1,196 @@
+import { useState, useCallback } from "react";
+import { useDropzone } from "react-dropzone";
+import { UploadCloud, Download, FileJson, FileText, CheckCircle2, AlertCircle, Loader2 } from "lucide-react";
+import { logEvent } from "../../store/registryStore";
+
+interface Toast { id: number; type: "success" | "error"; text: string }
+
+export function ImportExportWorkspace() {
+  const [file, setFile] = useState<File | null>(null);
+  const [isUploading, setIsUploading] = useState(false);
+  const [exportFormat, setExportFormat] = useState<"json" | "csv">("json");
+  const [isExporting, setIsExporting] = useState(false);
+  const [toasts, setToasts] = useState<Toast[]>([]);
+
+  function showToast(type: Toast["type"], text: string) {
+    const id = Date.now();
+    setToasts((p) => [...p, { id, type, text }]);
+    setTimeout(() => setToasts((p) => p.filter((t) => t.id !== id)), 5000);
+  }
+
+  const onDrop = useCallback((accepted: File[]) => {
+    if (accepted.length > 0) setFile(accepted[0]);
+  }, []);
+
+  const { getRootProps, getInputProps, isDragActive } = useDropzone({
+    onDrop,
+    accept: { "application/json": [".json"], "text/csv": [".csv"] },
+    maxFiles: 1,
+  });
+
+  async function handleImport() {
+    if (!file) return;
+    setIsUploading(true);
+    try {
+      const fd = new FormData();
+      fd.append("file", file);
+      const res = await fetch("/api/import", { method: "POST", body: fd });
+      if (!res.ok) { const e = await res.json(); throw new Error(e.detail || "Import failed"); }
+      const data = await res.json();
+      showToast("success", `Imported ${data.nodes_imported} nodes · ${data.edges_imported} edges`);
+      logEvent("import", `Imported ${data.nodes_imported} nodes · ${data.edges_imported} edges from ${file.name}`, { file: file.name });
+      setFile(null);
+    } catch (e: unknown) {
+      showToast("error", e instanceof Error ? e.message : "Import failed");
+    } finally { setIsUploading(false); }
+  }
+
+  async function handleExport() {
+    setIsExporting(true);
+    try {
+      const res = await fetch("/api/export", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ format: exportFormat }),
+      });
+      if (!res.ok) { const e = await res.json(); throw new Error(e.detail || "Export failed"); }
+      const blob = await res.blob();
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = `alphasemantichub_export.${exportFormat}`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+      showToast("success", `Export ready — alphasemantichub_export.${exportFormat}`);
+      logEvent("export", `Exported graph as ${exportFormat.toUpperCase()}`, { format: exportFormat });
+    } catch (e: unknown) {
+      showToast("error", e instanceof Error ? e.message : "Export failed");
+    } finally { setIsExporting(false); }
+  }
+
+  return (
+    <div className="ws-page ws-scroll">
+      <div className="ws-padded" style={{ display: "flex", flexDirection: "column", gap: 24, maxWidth: 980, margin: "0 auto", width: "100%" }}>
+        {/* Page header */}
+        <div style={{ display: "flex", alignItems: "center", gap: 14 }}>
+          <div style={{ width: 42, height: 42, borderRadius: 13, background: "var(--ws-accent-soft)", border: "1px solid var(--ws-border-strong)", display: "grid", placeItems: "center", color: "var(--ws-accent)", flexShrink: 0 }}>
+            <UploadCloud size={20} />
+          </div>
+          <div>
+            <h2 className="ws-title" style={{ fontSize: 18 }}>Import &amp; Export</h2>
+            <div className="ws-body" style={{ marginTop: 2 }}>Ingest new graph datasets or extract the current knowledge base.</div>
+          </div>
+        </div>
+
+        <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 18 }}>
+          {/* ── Import card ── */}
+          <div className="ws-card" style={{ padding: 24, display: "flex", flexDirection: "column", gap: 18 }}>
+            <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+              <UploadCloud size={16} color="var(--ws-accent)" />
+              <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Import Entities &amp; Relations</div>
+            </div>
+
+            {/* Dropzone */}
+            <div
+              {...getRootProps()}
+              style={{
+                border: `2px dashed ${isDragActive ? "var(--ws-accent)" : "var(--ws-border)"}`,
+                borderRadius: "var(--ws-radius)",
+                background: isDragActive ? "var(--ws-accent-soft)" : "rgba(0,0,0,0.18)",
+                padding: 32,
+                textAlign: "center",
+                cursor: "pointer",
+                transition: "all 200ms ease",
+                display: "flex",
+                flexDirection: "column",
+                alignItems: "center",
+                gap: 10,
+              }}
+            >
+              <input {...getInputProps()} />
+              {file ? (
+                <>
+                  {file.name.endsWith(".json") ? <FileJson size={40} color="#4cc38a" /> : <FileText size={40} color="#4cc38a" />}
+                  <div style={{ color: "var(--ws-text)", fontWeight: 700 }}>{file.name}</div>
+                  <div className="ws-body" style={{ fontSize: 11 }}>{(file.size / 1024).toFixed(1)} KB — click to replace</div>
+                </>
+              ) : (
+                <>
+                  <UploadCloud size={36} color="var(--ws-accent)" style={{ opacity: 0.7 }} />
+                  <div style={{ color: "var(--ws-text)", fontWeight: 600 }}>Drag &amp; drop or click to browse</div>
+                  <div className="ws-pill ws-pill--mono">.json</div>
+                  <span style={{ color: "var(--ws-text-dim)", fontSize: 11 }}>or</span>
+                  <div className="ws-pill ws-pill--mono">.csv</div>
+                </>
+              )}
+            </div>
+
+            <button
+              className="ws-btn ws-btn--primary"
+              onClick={handleImport}
+              disabled={!file || isUploading}
+              style={{ width: "100%", justifyContent: "center" }}
+            >
+              {isUploading ? <><Loader2 size={15} className="ws-spin" />Uploading…</> : <><UploadCloud size={15} />Upload to Graph</>}
+            </button>
+          </div>
+
+          {/* ── Export card ── */}
+          <div className="ws-card" style={{ padding: 24, display: "flex", flexDirection: "column", gap: 18 }}>
+            <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+              <Download size={16} color="var(--ws-purple)" />
+              <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Export Graph Snapshot</div>
+            </div>
+
+            <div>
+              <label className="ws-label">Format</label>
+              <div style={{ display: "flex", gap: 8 }}>
+                {(["json", "csv"] as const).map((fmt) => (
+                  <button
+                    key={fmt}
+                    className={`ws-btn ${exportFormat === fmt ? "ws-btn--primary" : "ws-btn--ghost"}`}
+                    style={{ flex: 1, justifyContent: "center", textTransform: "uppercase", fontSize: 12 }}
+                    onClick={() => setExportFormat(fmt)}
+                  >
+                    {fmt === "json" ? <FileJson size={14} /> : <FileText size={14} />}
+                    {fmt}
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            <div style={{ flex: 1, padding: "14px 16px", borderRadius: "var(--ws-radius-sm)", background: "rgba(0,0,0,0.22)", border: "1px solid var(--ws-border)" }}>
+              <div style={{ color: "var(--ws-text-muted)", fontWeight: 700, fontSize: 12, marginBottom: 6 }}>What's included</div>
+              <div className="ws-body" style={{ fontSize: 12 }}>
+                {exportFormat === "json"
+                  ? "Full graph snapshot: all node properties, edge weights, entity metadata and semantic groups in a standardized JSON payload."
+                  : "Flattened CSV: nodes and edges as rows. Complex nested properties are stringified. Best for spreadsheet analysis."}
+              </div>
+            </div>
+
+            <button
+              className="ws-btn"
+              onClick={handleExport}
+              disabled={isExporting}
+              style={{ width: "100%", justifyContent: "center", background: "var(--ws-purple-soft)", borderColor: "rgba(192,132,252,0.3)", color: "#d8b4fe" }}
+            >
+              {isExporting ? <><Loader2 size={15} className="ws-spin" />Preparing…</> : <><Download size={15} />Download Export</>}
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {/* Toasts */}
+      <div style={{ position: "fixed", bottom: 28, right: 28, display: "flex", flexDirection: "column", gap: 10, zIndex: 1000 }}>
+        {toasts.map((t) => (
+          <div key={t.id} className="ws-animate-in" style={{ display: "flex", alignItems: "center", gap: 10, padding: "13px 18px", borderRadius: "var(--ws-radius-sm)", background: t.type === "success" ? "rgba(16,36,22,0.96)" : "rgba(40,10,10,0.96)", border: `1px solid ${t.type === "success" ? "rgba(76,195,138,0.4)" : "rgba(255,123,114,0.4)"}`, boxShadow: "0 8px 24px rgba(0,0,0,0.5)", backdropFilter: "blur(12px)" }}>
+            {t.type === "success" ? <CheckCircle2 size={16} color="#4cc38a" /> : <AlertCircle size={16} color="#ff7b72" />}
+            <span style={{ color: "var(--ws-text)", fontSize: 13, fontWeight: 500 }}>{t.text}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/explorer/src/workspaces/LineageWorkspace/LineageDiagram.tsx

@@ -0,0 +1,177 @@
+/**
+ * src/workspaces/LineageWorkspace/LineageDiagram.tsx
+ */
+import { useEffect, useState } from "react";
+import { Link2 } from "lucide-react";
+import { ReactFlow, Background, Controls } from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+
+const THEME_CSS = `
+  .react-flow { background: var(--ws-bg, #080407); }
+  .react-flow__node-group {
+    background: rgba(255,45,75,0.04);
+    border: 1px dashed rgba(255,45,75,0.18);
+    border-radius: 10px;
+  }
+  .react-flow__node-default {
+    background: rgba(6,13,26,0.92);
+    color: var(--ws-text, #ffe9ec);
+    border: 1px solid rgba(255,45,75,0.22);
+    border-radius: 8px;
+    padding: 10px 12px;
+    white-space: pre-wrap;
+    font-size: 12px;
+    box-shadow: 0 4px 16px rgba(0,0,0,0.4);
+  }
+  .react-flow__controls { background: rgba(6,13,26,0.9); border: 1px solid rgba(255,45,75,0.18); border-radius: 10px; }
+  .react-flow__controls-button { background: transparent; border-color: rgba(255,45,75,0.15); color: var(--ws-text-muted, #8f6d75); }
+  .react-flow__controls-button:hover { background: rgba(255,45,75,0.1); color: var(--ws-text, #ffe9ec); }
+`;
+
+export function LineageDiagram() {
+  const [nodes, setNodes] = useState<any[]>([]);
+  const [edges, setEdges] = useState<any[]>([]);
+  const [searchId, setSearchId] = useState("");
+  const [activeId, setActiveId] = useState("");
+  const [error, setError] = useState("");
+
+  const downloadReport = async (format: "json" | "markdown") => {
+    if (!activeId) return;
+    const response = await fetch(`/api/provenance/report?node_id=${encodeURIComponent(activeId)}&format=${format}`);
+    if (!response.ok) {
+      return;
+    }
+    const blob = await response.blob();
+    const url = window.URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = `${activeId}_provenance.${format === "markdown" ? "md" : "json"}`;
+    document.body.appendChild(anchor);
+    anchor.click();
+    window.URL.revokeObjectURL(url);
+    document.body.removeChild(anchor);
+  };
+
+  const [prevActiveId, setPrevActiveId] = useState(activeId);
+  if (activeId !== prevActiveId) {
+    setPrevActiveId(activeId);
+    setError("");
+    setNodes([]);
+    setEdges([]);
+  }
+
+  useEffect(() => {
+    let ignore = false;
+    if (!activeId) return;
+
+    const xLanes = [
+      { id: "group_agent", type: "group", position: { x: 50, y: 50 }, style: { width: 800, height: 120 } },
+      { id: "group_activity", type: "group", position: { x: 50, y: 200 }, style: { width: 800, height: 120 } },
+      { id: "group_entity", type: "group", position: { x: 50, y: 350 }, style: { width: 800, height: 120 } }
+    ];
+
+    const fetchLineage = async () => {
+      setError("");
+      try {
+        const res = await fetch("/api/provenance?node_id=" + encodeURIComponent(activeId));
+
+        if (!res.ok) {
+          const text = await res.text();
+          throw new Error(`HTTP ${res.status}: API Route missing or failed. ${text.substring(0, 100)}`);
+        }
+
+        const contentType = res.headers.get("content-type");
+        if (!contentType || !contentType.includes("application/json")) {
+          throw new Error("Backend returned non-JSON response (likely an HTML fallback).");
+        }
+
+        const data = await res.json();
+        if (res.status === 207) {
+          setError(data.message || "Warning: Partial success loading lineage.");
+        }
+
+        const counters: Record<string, number> = { "group_agent": 0, "group_activity": 0, "group_entity": 0 };
+
+        const mappedNodes = data.nodes.map((n: any) => {
+          const c = counters[n.parent_id] || 0;
+          counters[n.parent_id] = c + 1;
+          return {
+            id: n.id,
+            data: { label: n.label + "\n(" + n.prov_type + ")" },
+            position: { x: 50 + c * 180, y: 30 },
+            parentId: n.parent_id,
+            extent: "parent",
+            type: "default"
+          };
+        });
+
+        const mappedEdges = data.edges.map((e: any) => ({
+          id: e.id,
+          source: e.source,
+          target: e.target,
+          label: e.label,
+          animated: true,
+          style: { stroke: "#ff2d4b" }
+        }));
+
+        if (!ignore) {
+          setNodes([...xLanes, ...mappedNodes]);
+          setEdges(mappedEdges);
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to load lineage.");
+      }
+    };
+    void fetchLineage();
+    return () => { ignore = true; };
+  }, [activeId]);
+
+  return (
+    <div style={{ width: "100%", height: "100%", position: "relative", background: "var(--ws-bg, #080407)" }}>
+      <style>{THEME_CSS}</style>
+
+      {/* Toolbar */}
+      <div style={{ position: "absolute", top: 14, left: 14, right: 14, zIndex: 10, display: "flex", gap: 8, alignItems: "center", background: "rgba(4,10,18,0.88)", backdropFilter: "blur(14px)", padding: "8px 12px", borderRadius: 12, border: "1px solid rgba(255,45,75,0.16)", boxShadow: "0 4px 20px rgba(0,0,0,0.4)" }}>
+        <span className="ws-eyebrow" style={{ color: "var(--ws-accent, #ff2d4b)", marginRight: 4 }}>PROV-O Lineage</span>
+        <input
+          className="ws-input"
+          type="text"
+          placeholder="Enter Node ID…"
+          value={searchId}
+          onChange={(e) => setSearchId(e.target.value)}
+          onKeyDown={(e) => { if (e.key === "Enter") setActiveId(searchId); }}
+          style={{ width: 200, padding: "6px 10px", fontSize: 12 }}
+        />
+        <button className="ws-btn ws-btn--primary" style={{ padding: "6px 12px" }} onClick={() => setActiveId(searchId)}>
+          Trace
+        </button>
+        <div style={{ flex: 1 }} />
+        <button className="ws-btn ws-btn--ghost" style={{ padding: "6px 12px", fontSize: 11 }} disabled={!activeId} onClick={() => void downloadReport("json")}>
+          Export JSON
+        </button>
+        <button className="ws-btn ws-btn--ghost" style={{ padding: "6px 12px", fontSize: 11 }} disabled={!activeId} onClick={() => void downloadReport("markdown")}>
+          Export MD
+        </button>
+      </div>
+
+      {error ? (
+        <div style={{ position: "absolute", top: 60, left: 14, right: 14, zIndex: 10, padding: 12, borderRadius: 14, color: "#ffb4c2", background: "rgba(255,157,175,0.1)", border: "1px solid rgba(255,157,175,0.18)" }}>
+          {error}
+        </div>
+      ) : null}
+
+      {activeId ? (
+        <ReactFlow nodes={nodes} edges={edges} fitView>
+          <Background color="rgba(255,45,75,0.08)" gap={24} />
+          <Controls />
+        </ReactFlow>
+      ) : (
+        <div className="ws-empty" style={{ height: "100%", paddingTop: 72 }}>
+          <div className="ws-empty-icon"><Link2 size={36} color="var(--ws-accent)" /></div>
+          <div className="ws-empty-title">PROV-O Lineage Viewer</div>
+          <div className="ws-empty-body">Enter a Node ID in the toolbar above and click Trace to view its W3C PROV-O lineage diagram.</div>
+        </div>
+      )}
+    </div>
+  );
+}