sdlc-agent-4-enterprise-server 1.0.0

package/src/viewer/modules/empty-states.js

@@ -0,0 +1,123 @@
+/**
+ * Empty state detector and renderer.
+ * KSA-93 Phase 4: Shows helpful UI when sections have no data.
+ */
+
+import { on } from './event-bus.js';
+
+const EMPTY_CONFIGS = {
+  graph: {
+    selector: '#graph-recent',
+    checkEmpty: (el) => el.textContent.includes('No entries'),
+    icon: '🧠',
+    title: 'Knowledge Graph trống',
+    desc: 'Chưa có entries nào trong KB. Hãy ingest tài liệu hoặc tạo entries mới qua MCP tools.',
+    action: { label: 'Xem hướng dẫn', event: 'help:open', detail: 'graph' }
+  },
+  sessions: {
+    selector: '#sess-list',
+    checkEmpty: (el) => el.children.length === 0,
+    icon: '📋',
+    title: 'Chưa có sessions',
+    desc: 'Sessions được tạo tự động khi agent thực hiện thao tác trên KB. Hãy chạy agent để bắt đầu.',
+    action: null
+  },
+  browser: {
+    selector: '#br-list',
+    checkEmpty: (el) => el.children.length === 0,
+    icon: '🔍',
+    title: 'Không tìm thấy entries',
+    desc: 'Thử thay đổi bộ lọc hoặc tìm kiếm với từ khóa khác.',
+    action: { label: 'Xóa bộ lọc', event: 'browser:clearFilters' }
+  },
+  stream: {
+    selector: '#stream-list',
+    checkEmpty: (el) => el.children.length === 0,
+    icon: '⚡',
+    title: 'Chưa có events',
+    desc: 'Live stream hiển thị events real-time. Events sẽ xuất hiện khi có thao tác trên KB.',
+    action: null
+  }
+};
+
+/** Initialize empty state detection for a page. */
+export function initEmptyStates(page) {
+  const config = EMPTY_CONFIGS[page];
+  if (!config) return;
+  checkAndRender(config);
+  observeChanges(config);
+}
+
+/** Check if section is empty and render empty state. */
+function checkAndRender(config) {
+  const el = document.querySelector(config.selector);
+  if (!el) return;
+  setTimeout(() => {
+    if (config.checkEmpty(el)) renderEmptyState(el, config);
+  }, 1500);
+}
+
+/** Render empty state UI inside the target element. */
+function renderEmptyState(container, config) {
+  if (container.querySelector('.ux-empty-state')) return;
+  const emptyEl = document.createElement('div');
+  emptyEl.className = 'ux-empty-state';
+  emptyEl.innerHTML = buildEmptyHTML(config);
+  container.appendChild(emptyEl);
+  if (config.action) bindAction(emptyEl, config.action);
+}
+
+/** Build empty state HTML. */
+function buildEmptyHTML(config) {
+  let html = `
+    <div class="ux-empty-state-icon">${config.icon}</div>
+    <div class="ux-empty-state-title">${escText(config.title)}</div>
+    <div class="ux-empty-state-desc">${escText(config.desc)}</div>`;
+  if (config.action) {
+    html += `<div class="ux-empty-state-action">
+      <button class="ux-btn ux-btn-primary empty-action">${escText(config.action.label)}</button>
+    </div>`;
+  }
+  return html;
+}
+
+/** Bind action button click to event bus. */
+function bindAction(el, action) {
+  const btn = el.querySelector('.empty-action');
+  if (!btn) return;
+  const { emit } = await_import_event_bus();
+  btn.addEventListener('click', () => {
+    import('./event-bus.js').then(bus => {
+      bus.emit(action.event, action.detail);
+    });
+  });
+}
+
+/** Use MutationObserver to remove empty state when content appears. */
+function observeChanges(config) {
+  const el = document.querySelector(config.selector);
+  if (!el) return;
+  const observer = new MutationObserver(() => {
+    const emptyState = el.querySelector('.ux-empty-state');
+    if (!emptyState) return;
+    const hasRealContent = Array.from(el.children).some(
+      child => !child.classList.contains('ux-empty-state')
+    );
+    if (hasRealContent) emptyState.remove();
+  });
+  observer.observe(el, { childList: true });
+}
+
+/** Lazy import helper (avoids circular deps). */
+function await_import_event_bus() {
+  return { emit: (e, d) => document.dispatchEvent(new CustomEvent('ux:' + e, { detail: d })) };
+}
+
+/** Escape text for safe display. */
+function escText(str) {
+  const div = document.createElement('div');
+  div.textContent = str || '';
+  return div.innerHTML;
+}
+
+export default { initEmptyStates };

package/src/viewer/modules/event-bus.js

@@ -0,0 +1,37 @@
+/**
+ * Lightweight event bus for cross-module communication.
+ * Uses native CustomEvent API with 'ux:' namespace prefix.
+ * KSA-93: Foundation module for UX enhancements.
+ */
+
+const PREFIX = 'ux:';
+
+/** Emit an event with optional detail payload. */
+export function emit(event, detail = null) {
+  document.dispatchEvent(new CustomEvent(PREFIX + event, { detail }));
+}
+
+/** Subscribe to an event. Returns unsubscribe function. */
+export function on(event, handler) {
+  const wrapped = (e) => handler(e.detail);
+  document.addEventListener(PREFIX + event, wrapped);
+  return () => document.removeEventListener(PREFIX + event, wrapped);
+}
+
+/** Subscribe to an event once, auto-removes after first call. */
+export function once(event, handler) {
+  const wrapped = (e) => {
+    handler(e.detail);
+    document.removeEventListener(PREFIX + event, wrapped);
+  };
+  document.addEventListener(PREFIX + event, wrapped);
+}
+
+/** Remove a specific handler (must pass same function reference). */
+export function off(event, handler) {
+  document.removeEventListener(PREFIX + event, handler);
+}
+
+/** Convenience: EventBus object for import * style usage. */
+export const EventBus = { emit, on, once, off };
+export default EventBus;

package/src/viewer/modules/graph-analysis.js

@@ -0,0 +1,131 @@
+/**
+ * Graph analysis — fetches server-side analysis and renders insights panel.
+ * KSA-93 Phase 6: Graph structure insights.
+ */
+
+import { emit, on } from './event-bus.js';
+
+const API_URL = 'api/kb/graph/analysis';
+const CACHE_KEY = 'kb-viewer-graph-analysis';
+const CACHE_TTL = 300000; // 5 minutes
+let insightsData = null;
+
+/** Initialize graph analysis (only on graph page). */
+export async function initGraphAnalysis() {
+  const graphDetail = document.getElementById('graph-detail');
+  if (!graphDetail) return;
+  insightsData = loadCache();
+  if (!insightsData) {
+    insightsData = await fetchAnalysis();
+    saveCache(insightsData);
+  }
+  if (insightsData) renderInsights(graphDetail, insightsData);
+}
+
+/** Fetch graph analysis from server API. */
+async function fetchAnalysis() {
+  try {
+    const resp = await fetch(API_URL);
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch (e) {
+    console.debug('[graph-analysis] Fetch failed:', e.message);
+    return null;
+  }
+}
+
+/** Render insights panel into the graph detail sidebar. */
+function renderInsights(container, data) {
+  if (!data || !data.insights || data.insights.length === 0) return;
+  let panel = container.querySelector('.ux-insights-section');
+  if (!panel) {
+    panel = document.createElement('div');
+    panel.className = 'ux-insights-section';
+    panel.style.marginTop = '12px';
+    container.appendChild(panel);
+  }
+  const header = `<h3 style="font-size:.75rem;margin-bottom:6px;opacity:.7">
+    🔬 Graph Insights</h3>`;
+  const statsHtml = renderStats(data.stats);
+  const insightsHtml = data.insights.map(renderInsight).join('');
+  panel.innerHTML = header + statsHtml + insightsHtml;
+}
+
+/** Render graph stats summary. */
+function renderStats(stats) {
+  if (!stats) return '';
+  return `<div style="font-size:.6rem;opacity:.6;margin-bottom:8px">
+    Nodes: ${stats.node_count} | Edges: ${stats.edge_count} | 
+    Density: ${(stats.density * 100).toFixed(1)}%
+  </div>`;
+}
+
+/** Render a single insight item. */
+function renderInsight(insight) {
+  const icon = getInsightIcon(insight.type);
+  const severityColor = getSeverityColor(insight.severity);
+  const nodeCount = insight.node_ids ? insight.node_ids.length : 0;
+  return `<div class="ux-insight-item">
+    <span style="font-size:1rem">${icon}</span>
+    <div style="flex:1">
+      <div style="font-size:.7rem;font-weight:600;color:${severityColor}">
+        ${escText(insight.title)}
+      </div>
+      <div style="font-size:.6rem;opacity:.7">${escText(insight.description)}</div>
+      ${nodeCount > 0 ? `<div style="font-size:.55rem;opacity:.5;margin-top:2px">
+        IDs: ${insight.node_ids.slice(0, 5).join(', ')}${nodeCount > 5 ? '...' : ''}
+      </div>` : ''}
+    </div>
+  </div>`;
+}
+
+/** Get icon for insight type. */
+function getInsightIcon(type) {
+  const icons = {
+    orphans: '🏝️',
+    hubs: '🌟',
+    clusters: '🧩',
+    stale: '⏰',
+  };
+  return icons[type] || '📊';
+}
+
+/** Get color for severity level. */
+function getSeverityColor(severity) {
+  const colors = {
+    warning: 'var(--color-warning)',
+    info: 'var(--color-info)',
+    error: 'var(--color-error)',
+  };
+  return colors[severity] || 'var(--color-text-primary)';
+}
+
+/** Load cached analysis from localStorage. */
+function loadCache() {
+  try {
+    const raw = localStorage.getItem(CACHE_KEY);
+    if (!raw) return null;
+    const cached = JSON.parse(raw);
+    if (Date.now() - cached.timestamp > CACHE_TTL) return null;
+    return cached.data;
+  } catch { return null; }
+}
+
+/** Save analysis to localStorage cache. */
+function saveCache(data) {
+  if (!data) return;
+  try {
+    localStorage.setItem(CACHE_KEY, JSON.stringify({
+      data, timestamp: Date.now()
+    }));
+  } catch { /* quota exceeded */ }
+}
+
+/** Escape text for safe display. */
+function escText(str) {
+  const div = document.createElement('div');
+  div.textContent = str || '';
+  return div.innerHTML;
+}
+
+export default { initGraphAnalysis };

package/src/viewer/modules/help-panel.js

@@ -0,0 +1,104 @@
+/**
+ * Help panel — slide-in panel with contextual help content.
+ * KSA-93 Phase 7: Contextual help system.
+ */
+
+import { on, emit } from './event-bus.js';
+import { renderMarkdown } from './markdown-renderer.js';
+import { restartTour } from './tour.js';
+
+let panelEl = null;
+let currentPage = null;
+const CACHE = {};
+
+/** Initialize help panel for the current page. */
+export function initHelpPanel(page) {
+  currentPage = page;
+  createPanel();
+  createHelpButton();
+  on('help:open', (detail) => openHelp(detail || page));
+}
+
+/** Create the slide-in panel element. */
+function createPanel() {
+  if (document.querySelector('.ux-help-panel')) return;
+  panelEl = document.createElement('div');
+  panelEl.className = 'ux-help-panel';
+  panelEl.innerHTML = `
+    <div class="ux-help-header">
+      <h3 style="font-size:.8rem;color:var(--color-text-accent)">❓ Trợ giúp</h3>
+      <button class="ux-btn help-close" aria-label="Đóng">✕</button>
+    </div>
+    <div class="ux-help-content">
+      <div style="opacity:.5;font-size:.7rem">Đang tải...</div>
+    </div>
+    <div class="ux-help-footer" style="padding:12px 16px;border-top:1px solid var(--color-border-subtle)">
+      <button class="ux-btn help-restart-tour" style="width:100%">🔄 Xem lại Tour hướng dẫn</button>
+    </div>`;
+  document.body.appendChild(panelEl);
+  panelEl.querySelector('.help-close').addEventListener('click', closeHelp);
+  panelEl.querySelector('.help-restart-tour').addEventListener('click', () => {
+    closeHelp();
+    restartTour(currentPage);
+  });
+}
+
+/** Create floating help button (bottom-right). */
+function createHelpButton() {
+  if (document.querySelector('.ux-help-btn')) return;
+  const btn = document.createElement('button');
+  btn.className = 'ux-help-btn';
+  btn.innerHTML = '❓';
+  btn.setAttribute('aria-label', 'Mở trợ giúp');
+  btn.style.cssText = `
+    position:fixed;bottom:16px;right:16px;width:40px;height:40px;
+    border-radius:50%;border:1px solid var(--color-border);
+    background:var(--color-bg-secondary);color:var(--color-text-accent);
+    font-size:1.1rem;cursor:pointer;z-index:var(--z-dropdown);
+    box-shadow:var(--shadow-md);transition:all var(--transition-fast);
+  `;
+  btn.addEventListener('click', () => openHelp(currentPage));
+  btn.addEventListener('mouseenter', () => { btn.style.transform = 'scale(1.1)'; });
+  btn.addEventListener('mouseleave', () => { btn.style.transform = 'scale(1)'; });
+  document.body.appendChild(btn);
+}
+
+/** Open help panel and load content for section. */
+async function openHelp(section) {
+  if (!panelEl) return;
+  panelEl.classList.add('open');
+  const contentEl = panelEl.querySelector('.ux-help-content');
+  if (CACHE[section]) {
+    contentEl.innerHTML = CACHE[section];
+    return;
+  }
+  contentEl.innerHTML = '<div style="opacity:.5;font-size:.7rem">Đang tải...</div>';
+  try {
+    const resp = await fetch(`api/kb/help/${section}`);
+    if (!resp.ok) {
+      contentEl.innerHTML = '<div style="color:var(--color-error)">Không tìm thấy nội dung</div>';
+      return;
+    }
+    const data = await resp.json();
+    const html = `<h2 style="font-size:.85rem;margin-bottom:8px;color:var(--color-text-accent)">
+      ${escText(data.title)}</h2>${renderMarkdown(data.content)}`;
+    CACHE[section] = html;
+    contentEl.innerHTML = html;
+  } catch (e) {
+    contentEl.innerHTML = '<div style="color:var(--color-error)">Lỗi kết nối</div>';
+  }
+}
+
+/** Close help panel. */
+function closeHelp() {
+  if (panelEl) panelEl.classList.remove('open');
+}
+
+/** Escape text for safe display. */
+function escText(str) {
+  const div = document.createElement('div');
+  div.textContent = str || '';
+  return div.innerHTML;
+}
+
+export default { initHelpPanel };

package/src/viewer/modules/markdown-renderer.js

@@ -0,0 +1,70 @@
+/**
+ * Simple markdown to HTML renderer — no external dependencies.
+ * KSA-93 Phase 7: Renders help content markdown.
+ * Supports: headings, bold, italic, lists, code, links, paragraphs.
+ */
+
+/** Render markdown string to sanitized HTML. */
+export function renderMarkdown(md) {
+  if (!md) return '';
+  const lines = md.split('\n');
+  let html = '';
+  let inList = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === '') {
+      if (inList) { html += '</ul>'; inList = false; }
+      continue;
+    }
+
+    if (trimmed.startsWith('## ')) {
+      if (inList) { html += '</ul>'; inList = false; }
+      html += `<h3 style="font-size:.75rem;margin:12px 0 6px;color:var(--color-text-accent)">${inline(trimmed.slice(3))}</h3>`;
+    } else if (trimmed.startsWith('# ')) {
+      if (inList) { html += '</ul>'; inList = false; }
+      html += `<h2 style="font-size:.8rem;margin:12px 0 6px;color:var(--color-text-accent)">${inline(trimmed.slice(2))}</h2>`;
+    } else if (trimmed.startsWith('- ') || trimmed.startsWith('* ')) {
+      if (!inList) { html += '<ul style="padding-left:16px;margin:4px 0">'; inList = true; }
+      html += `<li style="font-size:.7rem;margin:2px 0;color:var(--color-text-secondary)">${inline(trimmed.slice(2))}</li>`;
+    } else if (trimmed.startsWith('```')) {
+      // Skip code fences (simplified)
+      continue;
+    } else {
+      if (inList) { html += '</ul>'; inList = false; }
+      html += `<p style="font-size:.7rem;margin:4px 0;color:var(--color-text-secondary);line-height:1.5">${inline(trimmed)}</p>`;
+    }
+  }
+  if (inList) html += '</ul>';
+  return html;
+}
+
+/** Process inline markdown: bold, italic, code, links. */
+function inline(text) {
+  let result = escText(text);
+  // Bold: **text**
+  result = result.replace(/\*\*(.+?)\*\*/g, '<strong style="color:var(--color-text-primary)">$1</strong>');
+  // Italic: *text*
+  result = result.replace(/\*(.+?)\*/g, '<em>$1</em>');
+  // Inline code: `text`
+  result = result.replace(/`(.+?)`/g,
+    '<code style="background:var(--color-bg-primary);padding:1px 4px;border-radius:3px;font-size:.65rem">$1</code>');
+  // Links: [text](url) — sanitize href
+  result = result.replace(/\[(.+?)\]\((.+?)\)/g, (_, text, url) => {
+    if (url.startsWith('javascript:')) return text;
+    return `<a href="${url}" style="color:var(--color-text-accent)" target="_blank" rel="noopener">${text}</a>`;
+  });
+  return result;
+}
+
+/** Escape text to prevent XSS. */
+function escText(str) {
+  return (str || '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export default { renderMarkdown };

package/src/viewer/modules/recommendations.js

@@ -0,0 +1,116 @@
+/**
+ * Recommendation panel — fetches and displays KB improvement suggestions.
+ * KSA-93 Phase 5: Actionable recommendations with Fix Now buttons.
+ */
+
+import { emit, on } from './event-bus.js';
+
+const API_URL = 'api/kb/recommendations';
+const CACHE_TTL = 30000; // 30 seconds
+let lastFetch = 0;
+let cachedData = null;
+let containerEl = null;
+
+/** Initialize recommendations (only on pages with graph-detail panel). */
+export async function initRecommendations() {
+  containerEl = document.getElementById('graph-detail');
+  if (!containerEl) return;
+  await loadAndRender();
+  on('recommendation:refresh', loadAndRender);
+}
+
+/** Fetch recommendations from API and render. */
+async function loadAndRender() {
+  const now = Date.now();
+  if (cachedData && (now - lastFetch) < CACHE_TTL) {
+    render(cachedData);
+    return;
+  }
+  try {
+    const resp = await fetch(API_URL + '?limit=5');
+    if (!resp.ok) return;
+    cachedData = await resp.json();
+    lastFetch = now;
+    render(cachedData);
+  } catch (e) {
+    console.debug('[recommendations] Fetch failed:', e.message);
+  }
+}
+
+/** Render recommendation cards into the container. */
+function render(data) {
+  if (!containerEl || !data.recommendations) return;
+  let section = containerEl.querySelector('.ux-rec-section');
+  if (!section) {
+    section = document.createElement('div');
+    section.className = 'ux-rec-section';
+    section.style.marginTop = '12px';
+    containerEl.appendChild(section);
+  }
+  if (data.recommendations.length === 0) {
+    section.innerHTML = '<div style="font-size:.65rem;opacity:.5">✅ Không có recommendations</div>';
+    return;
+  }
+  const header = `<h3 style="font-size:.75rem;margin-bottom:6px;opacity:.7">
+    💡 Recommendations (${data.total})</h3>`;
+  const cards = data.recommendations.map(buildCard).join('');
+  section.innerHTML = header + cards;
+  bindActions(section);
+}
+
+/** Build HTML for a single recommendation card. */
+function buildCard(rec) {
+  const severityClass = `severity-${rec.severity}`;
+  const actionBtn = rec.action
+    ? `<button class="ux-btn rec-action" data-endpoint="${rec.action.endpoint}" 
+         data-method="${rec.action.method}">${escText(rec.action.label)}</button>`
+    : '';
+  return `<div class="ux-rec-card ${severityClass}" data-id="${rec.id}">
+    <div style="font-size:.7rem;font-weight:600;margin-bottom:2px">${escText(rec.title)}</div>
+    <div style="font-size:.6rem;opacity:.7;margin-bottom:4px">${escText(rec.description)}</div>
+    ${actionBtn}
+  </div>`;
+}
+
+/** Bind click handlers to Fix Now action buttons. */
+function bindActions(section) {
+  section.querySelectorAll('.rec-action').forEach(btn => {
+    btn.addEventListener('click', async (e) => {
+      e.stopPropagation();
+      const endpoint = btn.dataset.endpoint;
+      const method = btn.dataset.method || 'POST';
+      await executeAction(endpoint, method, btn);
+    });
+  });
+}
+
+/** Execute a recommendation action (POST to endpoint). */
+async function executeAction(endpoint, method, btn) {
+  btn.disabled = true;
+  btn.textContent = '⏳...';
+  try {
+    const resp = await fetch(endpoint, { method });
+    if (resp.ok) {
+      btn.textContent = '✓ Done';
+      btn.style.background = 'var(--color-success)';
+      btn.style.color = '#000';
+      cachedData = null;
+      setTimeout(() => emit('recommendation:refresh'), 1500);
+    } else {
+      btn.textContent = '✗ Error';
+      btn.disabled = false;
+    }
+  } catch {
+    btn.textContent = '✗ Network error';
+    btn.disabled = false;
+  }
+}
+
+/** Escape text for safe display. */
+function escText(str) {
+  const div = document.createElement('div');
+  div.textContent = str || '';
+  return div.innerHTML;
+}
+
+export default { initRecommendations };