aios-core 4.2.14 → 4.3.0

package/.aios-core/core/graph-dashboard/formatters/json-formatter.js

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * Format graph data as JSON string.
+ * Output is pipe-friendly and parseable by jq.
+ * @param {Object} graphData - Normalized graph data { nodes, edges, source, isFallback }
+ * @returns {string} JSON string (indented, no trailing newline)
+ */
+function formatAsJson(graphData) {
+  return JSON.stringify(graphData, null, 2);
+}
+
+module.exports = { formatAsJson };

package/.aios-core/core/graph-dashboard/formatters/mermaid-formatter.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Format graph data as Mermaid diagram string.
+ * Output is valid Mermaid syntax for documentation.
+ * @param {Object} graphData - Normalized graph data { nodes, edges, source, isFallback }
+ * @returns {string} Mermaid format string
+ */
+function formatAsMermaid(graphData) {
+  const nodes = graphData.nodes || [];
+  const edges = graphData.edges || [];
+  const lines = [];
+
+  lines.push('graph TD');
+
+  const connectedNodes = new Set();
+
+  for (const edge of edges) {
+    const fromLabel = _escapeMermaid(edge.from);
+    const toLabel = _escapeMermaid(edge.to);
+    lines.push(`  ${_safeId(edge.from)}["${fromLabel}"] --> ${_safeId(edge.to)}["${toLabel}"]`);
+    connectedNodes.add(edge.from);
+    connectedNodes.add(edge.to);
+  }
+
+  for (const node of nodes) {
+    if (!connectedNodes.has(node.id)) {
+      const label = _escapeMermaid(node.label || node.id);
+      lines.push(`  ${_safeId(node.id)}["${label}"]`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Create a safe Mermaid node ID (alphanumeric + hyphens + underscores).
+ * @param {string} id - Raw node ID
+ * @returns {string} Safe ID
+ * @private
+ */
+function _safeId(id) {
+  return String(id).replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+/**
+ * Escape special characters for Mermaid label strings.
+ * @param {string} str - Raw string
+ * @returns {string} Escaped string
+ * @private
+ */
+function _escapeMermaid(str) {
+  return String(str)
+    .replace(/"/g, '"')
+    .replace(/\[/g, '[')
+    .replace(/\]/g, ']');
+}
+
+module.exports = { formatAsMermaid, _safeId, _escapeMermaid };

package/.aios-core/core/graph-dashboard/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const { CodeIntelSource } = require('./data-sources/code-intel-source');
+const { renderTree } = require('./renderers/tree-renderer');
+const { run } = require('./cli');
+
+/**
+ * Get graph data from code-intel or registry fallback.
+ * @returns {Promise<Object>} Normalized graph data { nodes, edges, source, isFallback, timestamp }
+ */
+async function getGraphData() {
+  const source = new CodeIntelSource();
+  return source.getData();
+}
+
+module.exports = {
+  getGraphData,
+  renderTree,
+  run,
+  CodeIntelSource,
+};

package/.aios-core/core/graph-dashboard/renderers/stats-renderer.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const asciichart = require('asciichart');
+
+const SPARKLINE_CHARS = ['\u2581', '\u2582', '\u2583', '\u2584', '\u2585', '\u2586', '\u2587'];
+const MAX_LATENCY_POINTS = 10;
+
+/**
+ * Render entity statistics and cache metrics as formatted ASCII text.
+ * @param {Object} registryData - From RegistrySource.getData()
+ * @param {Object} metricsData - From MetricsSource.getData()
+ * @param {Object} [options]
+ * @param {boolean} [options.isTTY=true] - Whether output is to a TTY
+ * @returns {string} Formatted multiline string
+ */
+function renderStats(registryData, metricsData, options = {}) {
+  const isTTY = options.isTTY !== false;
+  const lines = [];
+
+  lines.push(..._renderEntityTable(registryData, isTTY));
+  lines.push('');
+  lines.push(..._renderCachePerformance(metricsData, isTTY));
+  lines.push('');
+  lines.push(..._renderLatencyChart(metricsData, isTTY));
+
+  if (registryData.lastUpdated) {
+    lines.push('');
+    lines.push(`Last updated: ${_timeAgo(registryData.lastUpdated)}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render entity statistics table.
+ * @param {Object} data - Registry stats
+ * @param {boolean} isTTY
+ * @returns {string[]}
+ * @private
+ */
+function _renderEntityTable(data, isTTY) {
+  const lines = [];
+  const categories = data.categories || {};
+  const sortedCategories = Object.entries(categories)
+    .sort((a, b) => b[1].count - a[1].count);
+
+  if (isTTY) {
+    lines.push('Entity Statistics');
+    lines.push('\u2500'.repeat(37));
+    lines.push(` ${'Category'.padEnd(13)}\u2502 ${'Count'.padStart(5)} \u2502 ${'%'.padStart(6)}`);
+    lines.push(`${'\u2500'.repeat(14)}\u253C${'\u2500'.repeat(7)}\u253C${'\u2500'.repeat(8)}`);
+
+    for (const [name, stats] of sortedCategories) {
+      const pctStr = `${stats.pct.toFixed(1)}%`;
+      lines.push(` ${name.padEnd(13)}\u2502 ${String(stats.count).padStart(5)} \u2502 ${pctStr.padStart(6)}`);
+    }
+
+    lines.push(`${'\u2500'.repeat(14)}\u253C${'\u2500'.repeat(7)}\u253C${'\u2500'.repeat(8)}`);
+    lines.push(` ${'TOTAL'.padEnd(13)}\u2502 ${String(data.totalEntities).padStart(5)} \u2502 ${'100%'.padStart(6)}`);
+  } else {
+    lines.push('Entity Statistics');
+    lines.push('-'.repeat(37));
+    lines.push(` ${'Category'.padEnd(13)}| ${'Count'.padStart(5)} | ${'%'.padStart(6)}`);
+    lines.push(`${'-'.repeat(14)}+${'-'.repeat(7)}+${'-'.repeat(8)}`);
+
+    for (const [name, stats] of sortedCategories) {
+      const pctStr = `${stats.pct.toFixed(1)}%`;
+      lines.push(` ${name.padEnd(13)}| ${String(stats.count).padStart(5)} | ${pctStr.padStart(6)}`);
+    }
+
+    lines.push(`${'-'.repeat(14)}+${'-'.repeat(7)}+${'-'.repeat(8)}`);
+    lines.push(` ${'TOTAL'.padEnd(13)}| ${String(data.totalEntities).padStart(5)} | ${'100%'.padStart(6)}`);
+  }
+
+  return lines;
+}
+
+/**
+ * Render cache performance with sparkline.
+ * @param {Object} data - Metrics data
+ * @param {boolean} isTTY
+ * @returns {string[]}
+ * @private
+ */
+function _renderCachePerformance(data, isTTY) {
+  const lines = [];
+
+  lines.push('Cache Performance');
+
+  if (!data.providerAvailable) {
+    lines.push(' [OFFLINE] No metrics available');
+    return lines;
+  }
+
+  const hitPct = (data.cacheHitRate * 100).toFixed(1);
+  const missPct = (100 - data.cacheHitRate * 100).toFixed(1);
+
+  if (isTTY) {
+    const hitSparkline = _generateSparkline(data.latencyLog, true);
+    const missSparkline = _generateSparkline(data.latencyLog, false);
+    lines.push(` Hit Rate: ${hitPct.padStart(5)}% ${hitSparkline}`);
+    lines.push(` Misses:  ${missPct.padStart(5)}% ${missSparkline}`);
+  } else {
+    lines.push(` Hit Rate: ${hitPct}%`);
+    lines.push(` Misses:  ${missPct}%`);
+  }
+
+  return lines;
+}
+
+/**
+ * Generate sparkline string from latency log entries.
+ * @param {Array} latencyLog - Array of { isCacheHit, durationMs }
+ * @param {boolean} forHits - true = sparkline for hits, false = for misses
+ * @returns {string}
+ * @private
+ */
+function _generateSparkline(latencyLog, forHits) {
+  if (!latencyLog || latencyLog.length === 0) {
+    return '';
+  }
+
+  const recent = latencyLog.slice(-MAX_LATENCY_POINTS);
+  const values = recent.map((entry) => {
+    if (forHits) {
+      return entry.isCacheHit ? entry.durationMs || 1 : 0;
+    }
+    return entry.isCacheHit ? 0 : entry.durationMs || 1;
+  });
+
+  const max = Math.max(...values, 1);
+
+  return values
+    .map((v) => {
+      const idx = Math.round((v / max) * (SPARKLINE_CHARS.length - 1));
+      return SPARKLINE_CHARS[Math.min(idx, SPARKLINE_CHARS.length - 1)];
+    })
+    .join('');
+}
+
+/**
+ * Render latency chart using asciichart.
+ * @param {Object} data - Metrics data
+ * @param {boolean} isTTY
+ * @returns {string[]}
+ * @private
+ */
+function _renderLatencyChart(data, _isTTY) {
+  const lines = [];
+  const latencyLog = data.latencyLog || [];
+
+  if (!data.providerAvailable) {
+    lines.push('Latency');
+    lines.push(' [OFFLINE] No latency data');
+    return lines;
+  }
+
+  if (latencyLog.length === 0) {
+    lines.push('Latency');
+    lines.push(' No operations recorded');
+    return lines;
+  }
+
+  const recent = latencyLog.slice(-MAX_LATENCY_POINTS);
+  const durations = recent.map((entry) => entry.durationMs || 0);
+
+  lines.push(`Latency (last ${recent.length} operations)`);
+
+  const chart = asciichart.plot(durations, { height: 4, padding: '  ' });
+  lines.push(chart);
+
+  return lines;
+}
+
+/**
+ * Calculate relative time string from ISO date.
+ * @param {string} isoDate - ISO date string
+ * @returns {string} Relative time (e.g., "5 minutes ago")
+ * @private
+ */
+function _timeAgo(isoDate) {
+  const now = Date.now();
+  const then = new Date(isoDate).getTime();
+  const diffMs = now - then;
+
+  if (isNaN(diffMs) || diffMs < 0) {
+    return 'unknown';
+  }
+
+  const seconds = Math.floor(diffMs / 1000);
+
+  if (seconds < 60) {
+    return `${seconds}s ago`;
+  }
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    return `${minutes}m ago`;
+  }
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    return `${hours}h ago`;
+  }
+
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+module.exports = {
+  renderStats,
+  _renderEntityTable,
+  _renderCachePerformance,
+  _renderLatencyChart,
+  _generateSparkline,
+  _timeAgo,
+};

package/.aios-core/core/graph-dashboard/renderers/status-renderer.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const COLORS = {
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m',
+};
+
+const CB_FAILURE_THRESHOLD = 5;
+
+/**
+ * Render provider status as formatted multiline string.
+ * @param {Object} metricsData - From MetricsSource.getData()
+ * @param {Object} [options]
+ * @param {boolean} [options.isTTY=true] - Whether output is to a TTY
+ * @returns {string} Formatted multiline string
+ */
+function renderStatus(metricsData, options = {}) {
+  const isTTY = options.isTTY !== false;
+  const lines = [];
+
+  lines.push(_renderHeader(isTTY));
+  lines.push(_renderProviderLine(metricsData, isTTY));
+  lines.push(_renderCircuitBreaker(metricsData, isTTY));
+  lines.push(_renderFailures(metricsData));
+  lines.push(_renderCacheEntries(metricsData));
+  lines.push(_renderUptime());
+
+  return lines.join('\n');
+}
+
+/**
+ * Render status section header.
+ * @param {boolean} isTTY
+ * @returns {string}
+ * @private
+ */
+function _renderHeader(isTTY) {
+  const separator = isTTY ? '\u2500'.repeat(27) : '-'.repeat(27);
+  return `Provider Status\n${separator}`;
+}
+
+/**
+ * Render provider availability line.
+ * @param {Object} data - Metrics data
+ * @param {boolean} isTTY
+ * @returns {string}
+ * @private
+ */
+function _renderProviderLine(data, isTTY) {
+  const isActive = !!data.providerAvailable;
+
+  if (isTTY) {
+    if (isActive) {
+      return ` Code Graph MCP: ${COLORS.green}\u25CF ACTIVE${COLORS.reset}`;
+    }
+    return ` Code Graph MCP: ${COLORS.red}\u25CB OFFLINE${COLORS.reset}`;
+  }
+
+  if (isActive) {
+    return ' Code Graph MCP: [ACTIVE]';
+  }
+  return ' Code Graph MCP: [OFFLINE]';
+}
+
+/**
+ * Render circuit breaker state line.
+ * @param {Object} data - Metrics data
+ * @param {boolean} isTTY
+ * @returns {string}
+ * @private
+ */
+function _renderCircuitBreaker(data, isTTY) {
+  const state = data.circuitBreakerState || 'CLOSED';
+
+  if (isTTY && state === 'HALF-OPEN') {
+    return ` Circuit Breaker: ${COLORS.yellow}${state}${COLORS.reset}`;
+  }
+
+  return ` Circuit Breaker: ${state}`;
+}
+
+/**
+ * Render failure count line.
+ * @param {Object} data - Metrics data
+ * @returns {string}
+ * @private
+ */
+function _renderFailures(data) {
+  const failures = data.circuitBreakerFailures || 0;
+  return ` Failures: ${failures}/${CB_FAILURE_THRESHOLD}`;
+}
+
+/**
+ * Render cache entries count line.
+ * Uses cacheHits + cacheMisses as proxy for total cache operations.
+ * @param {Object} data - Metrics data
+ * @returns {string}
+ * @private
+ */
+function _renderCacheEntries(data) {
+  const entries = (data.cacheHits || 0) + (data.cacheMisses || 0);
+  return ` Cache Entries: ${entries}`;
+}
+
+/**
+ * Render uptime line (static string, no real tracking).
+ * @returns {string}
+ * @private
+ */
+function _renderUptime() {
+  return ' Uptime: session';
+}
+
+module.exports = {
+  renderStatus,
+  CB_FAILURE_THRESHOLD,
+  _renderHeader,
+  _renderProviderLine,
+  _renderCircuitBreaker,
+  _renderFailures,
+  _renderCacheEntries,
+  _renderUptime,
+};

package/.aios-core/core/graph-dashboard/renderers/tree-renderer.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const MAX_ITEMS_PER_BRANCH = 20;
+
+/**
+ * Box-drawing characters for tree rendering.
+ */
+const UNICODE_CHARS = { branch: '\u251C\u2500', last: '\u2514\u2500', pipe: '\u2502', space: ' ' };
+const ASCII_CHARS = { branch: '+-', last: '\\-', pipe: '|', space: ' ' };
+
+/**
+ * Render graph data as ASCII dependency tree.
+ * @param {Object} graphData - Normalized graph data { nodes, edges, source, isFallback }
+ * @param {Object} [options]
+ * @param {boolean} [options.color=true] - Enable ANSI colors (ignored if not TTY)
+ * @param {boolean} [options.unicode=true] - Use Unicode box-drawing characters
+ * @returns {string} Multiline ASCII tree string
+ */
+function renderTree(graphData, options = {}) {
+  const useUnicode = options.unicode !== false;
+  const chars = useUnicode ? UNICODE_CHARS : ASCII_CHARS;
+
+  const nodes = graphData.nodes || [];
+  const edges = graphData.edges || [];
+
+  if (nodes.length === 0) {
+    const badge = graphData.isFallback ? ' [OFFLINE]' : '';
+    return `Dependency Graph (0 entities)${badge}\n(empty)`;
+  }
+
+  // Build dependency lookup: entityId → [dep1, dep2, ...]
+  const depsMap = _buildDepsMap(edges);
+
+  // Group nodes by category
+  const categories = _groupByCategory(nodes);
+  const categoryNames = Object.keys(categories).sort();
+
+  const lines = [];
+  const badge = graphData.isFallback ? ' [OFFLINE]' : '';
+  lines.push(`Dependency Graph (${nodes.length} entities)${badge}`);
+
+  for (let ci = 0; ci < categoryNames.length; ci++) {
+    const catName = categoryNames[ci];
+    const catNodes = categories[catName];
+    const isLastCategory = ci === categoryNames.length - 1;
+    const catPrefix = isLastCategory ? chars.last : chars.branch;
+    const catContinue = isLastCategory ? chars.space : chars.pipe;
+
+    lines.push(`${catPrefix} ${catName}/ (${catNodes.length})`);
+
+    const sortedNodes = catNodes.sort((a, b) => a.id.localeCompare(b.id));
+    const displayCount = Math.min(sortedNodes.length, MAX_ITEMS_PER_BRANCH);
+    const hasMore = sortedNodes.length > MAX_ITEMS_PER_BRANCH;
+
+    for (let ni = 0; ni < displayCount; ni++) {
+      const node = sortedNodes[ni];
+      const isLastNode = ni === displayCount - 1 && !hasMore;
+      const nodePrefix = isLastNode ? chars.last : chars.branch;
+
+      const deps = depsMap.get(node.id) || [];
+      const depSuffix = deps.length > 0 ? ` ${chars.last} depends: ${deps.join(', ')}` : '';
+
+      lines.push(`${catContinue}  ${nodePrefix} ${node.id}${depSuffix}`);
+    }
+
+    if (hasMore) {
+      const remaining = sortedNodes.length - MAX_ITEMS_PER_BRANCH;
+      lines.push(`${catContinue}  ${chars.last} ... (${remaining} more)`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build map of entityId → array of dependency IDs from edges.
+ * @param {Array} edges - Array of { from, to, type }
+ * @returns {Map<string, string[]>}
+ */
+function _buildDepsMap(edges) {
+  const map = new Map();
+
+  for (const edge of edges) {
+    if (edge.type !== 'depends') continue;
+
+    if (!map.has(edge.from)) {
+      map.set(edge.from, []);
+    }
+    map.get(edge.from).push(edge.to);
+  }
+
+  return map;
+}
+
+/**
+ * Group nodes by their category field.
+ * @param {Array} nodes - Array of { id, label, type, path, category }
+ * @returns {Object} { categoryName: [nodes...] }
+ */
+function _groupByCategory(nodes) {
+  const groups = {};
+
+  for (const node of nodes) {
+    const cat = node.category || 'other';
+    if (!groups[cat]) {
+      groups[cat] = [];
+    }
+    groups[cat].push(node);
+  }
+
+  return groups;
+}
+
+module.exports = {
+  renderTree,
+  MAX_ITEMS_PER_BRANCH,
+  UNICODE_CHARS,
+  ASCII_CHARS,
+};

package/.aios-core/core/health-check/base-check.js

@@ -4,7 +4,7 @@
  * Abstract base class for all health checks. Provides common
  * functionality and enforces the check interface.
  *
- * @module @synkra/aios-core/health-check/base-check
+ * @module aios-core/health-check/base-check
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/check-registry.js

@@ -4,7 +4,7 @@
  * Central registry for all health checks. Manages check registration,
  * lookup, and categorization by domain and severity.
  *
- * @module @synkra/aios-core/health-check/check-registry
+ * @module aios-core/health-check/check-registry
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/build-config.js

@@ -3,7 +3,7 @@
  *
  * Verifies build configuration is valid.
  *
- * @module @synkra/aios-core/health-check/checks/deployment/build-config
+ * @module aios-core/health-check/checks/deployment/build-config
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/ci-config.js

@@ -3,7 +3,7 @@
  *
  * Verifies CI/CD configuration.
  *
- * @module @synkra/aios-core/health-check/checks/deployment/ci-config
+ * @module aios-core/health-check/checks/deployment/ci-config
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/deployment-readiness.js

@@ -3,7 +3,7 @@
  *
  * Verifies project is ready for deployment.
  *
- * @module @synkra/aios-core/health-check/checks/deployment/deployment-readiness
+ * @module aios-core/health-check/checks/deployment/deployment-readiness
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/docker-config.js

@@ -3,7 +3,7 @@
  *
  * Verifies Docker configuration if present.
  *
- * @module @synkra/aios-core/health-check/checks/deployment/docker-config
+ * @module aios-core/health-check/checks/deployment/docker-config
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/env-file.js

@@ -3,7 +3,7 @@
  *
  * Verifies .env files are properly configured.
  *
- * @module @synkra/aios-core/health-check/checks/deployment/env-file
+ * @module aios-core/health-check/checks/deployment/env-file
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/deployment/index.js

@@ -4,7 +4,7 @@
  * Checks for deployment configuration and environment.
  * Domain: deployment
  *
- * @module @synkra/aios-core/health-check/checks/deployment
+ * @module aios-core/health-check/checks/deployment
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/index.js

@@ -3,7 +3,7 @@
  *
  * Aggregates all domain checks for the health check system.
  *
- * @module @synkra/aios-core/health-check/checks
+ * @module aios-core/health-check/checks
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/local/disk-space.js

@@ -3,7 +3,7 @@
  *
  * Verifies sufficient disk space is available.
  *
- * @module @synkra/aios-core/health-check/checks/local/disk-space
+ * @module aios-core/health-check/checks/local/disk-space
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/local/environment-vars.js

@@ -3,7 +3,7 @@
  *
  * Verifies required environment variables are set.
  *
- * @module @synkra/aios-core/health-check/checks/local/environment-vars
+ * @module aios-core/health-check/checks/local/environment-vars
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/local/git-install.js

@@ -3,7 +3,7 @@
  *
  * Verifies Git is installed and configured.
  *
- * @module @synkra/aios-core/health-check/checks/local/git-install
+ * @module aios-core/health-check/checks/local/git-install
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */

package/.aios-core/core/health-check/checks/local/ide-detection.js

@@ -3,7 +3,7 @@
  *
  * Detects and validates IDE/editor configuration.
  *
- * @module @synkra/aios-core/health-check/checks/local/ide-detection
+ * @module aios-core/health-check/checks/local/ide-detection
  * @version 1.0.0
  * @story HCS-2 - Health Check System Implementation
  */