aios-core 4.2.15 → 4.4.0

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

@@ -0,0 +1,361 @@
+'use strict';
+
+const { CodeIntelSource } = require('./data-sources/code-intel-source');
+const { RegistrySource } = require('./data-sources/registry-source');
+const { MetricsSource } = require('./data-sources/metrics-source');
+const { renderTree } = require('./renderers/tree-renderer');
+const { renderStats } = require('./renderers/stats-renderer');
+const { renderStatus } = require('./renderers/status-renderer');
+const { formatAsJson } = require('./formatters/json-formatter');
+const { formatAsDot } = require('./formatters/dot-formatter');
+const { formatAsMermaid } = require('./formatters/mermaid-formatter');
+const { formatAsHtml } = require('./formatters/html-formatter');
+
+const fs = require('fs');
+const path = require('path');
+const { exec } = require('child_process');
+
+const MAX_SUMMARY_PER_CATEGORY = 5;
+const DEFAULT_WATCH_INTERVAL_MS = 5000;
+const DEBOUNCE_MS = 300;
+
+const FORMAT_MAP = {
+  json: formatAsJson,
+  dot: formatAsDot,
+  mermaid: formatAsMermaid,
+  html: formatAsHtml,
+};
+
+const VALID_FORMATS = ['ascii', ...Object.keys(FORMAT_MAP)];
+
+const WATCH_FORMAT_MAP = {
+  dot: { formatter: formatAsDot, filename: 'graph.dot' },
+  mermaid: { formatter: formatAsMermaid, filename: 'graph.mmd' },
+  html: {
+    formatter: (graphData) => formatAsHtml(graphData, { autoRefresh: true, refreshInterval: 5 }),
+    filename: 'graph.html',
+  },
+};
+
+const COMMANDS = {
+  '--deps': handleDeps,
+  '--stats': handleStats,
+  '--help': handleHelp,
+  '-h': handleHelp,
+};
+
+/**
+ * Parse CLI arguments into structured args object.
+ * @param {string[]} argv - Raw CLI arguments
+ * @returns {Object} Parsed args
+ */
+function parseArgs(argv) {
+  const args = {
+    command: null,
+    format: 'ascii',
+    file: null,
+    interval: 5,
+    watch: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      args.command = '--help';
+    } else if (arg === '--deps') {
+      args.command = '--deps';
+    } else if (arg === '--stats') {
+      args.command = '--stats';
+    } else if (arg === '--watch') {
+      args.watch = true;
+    } else if (arg === '--format' && i + 1 < argv.length) {
+      args.format = argv[++i];
+    } else if (arg.startsWith('--format=')) {
+      args.format = arg.split('=')[1];
+    } else if (arg === '--interval' && i + 1 < argv.length) {
+      args.interval = parseInt(argv[++i], 10);
+    } else if (arg.startsWith('--interval=')) {
+      args.interval = parseInt(arg.split('=')[1], 10);
+    } else if (arg.startsWith('--') && !args.command) {
+      args.command = arg;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Handle --deps command: render dependency tree or formatted output.
+ * If --watch is set, delegates to handleWatch.
+ * @param {Object} args - Parsed CLI args
+ */
+async function handleDeps(args) {
+  const format = args.format || 'ascii';
+
+  if (format !== 'ascii' && !FORMAT_MAP[format]) {
+    console.error(`Unknown format: ${format}. Valid formats: ${VALID_FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (args.watch) {
+    return handleWatch(args);
+  }
+
+  const source = new CodeIntelSource();
+  const graphData = await source.getData();
+
+  if (format === 'html') {
+    return handleHtmlOutput(graphData);
+  }
+
+  if (format !== 'ascii') {
+    const formatter = FORMAT_MAP[format];
+    process.stdout.write(formatter(graphData) + '\n');
+    return;
+  }
+
+  const isTTY = process.stdout.isTTY;
+  const output = renderTree(graphData, { color: isTTY, unicode: isTTY });
+  console.log(output);
+}
+
+/**
+ * Write HTML graph to .aios/graph.html and open in default browser.
+ * @param {Object} graphData - Normalized graph data
+ * @param {Object} [options] - Options passed to formatAsHtml
+ * @returns {string} Output file path
+ */
+function handleHtmlOutput(graphData, options = {}) {
+  const outputDir = path.resolve(process.cwd(), '.aios');
+  const outputPath = path.join(outputDir, 'graph.html');
+
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const html = formatAsHtml(graphData, options);
+  fs.writeFileSync(outputPath, html, 'utf8');
+
+  const nodeCount = (graphData.nodes || []).length;
+  console.log(`HTML graph written to ${outputPath} (${nodeCount} entities)`);
+
+  openInBrowser(outputPath);
+  return outputPath;
+}
+
+/**
+ * Open a file in the default browser (cross-platform).
+ * @param {string} filePath - Absolute path to file
+ */
+function openInBrowser(filePath) {
+  const platform = process.platform;
+  const cmd = platform === 'win32' ? 'start ""' : platform === 'darwin' ? 'open' : 'xdg-open';
+
+  exec(`${cmd} "${filePath}"`, (err) => {
+    if (err) {
+      console.log(`Could not open browser automatically. Open manually: ${filePath}`);
+    }
+  });
+}
+
+/**
+ * Handle --watch mode: regenerate graph file on interval and on file changes.
+ * Writes to .aios/graph.dot, .aios/graph.mmd, or .aios/graph.html.
+ * @param {Object} args - Parsed CLI args
+ * @returns {Object} Watch state for cleanup (used by tests)
+ */
+async function handleWatch(args) {
+  const watchFormat = WATCH_FORMAT_MAP[args.format] ? args.format : 'dot';
+  const { formatter, filename } = WATCH_FORMAT_MAP[watchFormat];
+  const intervalMs = (args.interval || 5) * 1000;
+  const outputDir = path.resolve(process.cwd(), '.aios');
+  const outputPath = path.join(outputDir, filename);
+
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const source = new CodeIntelSource();
+
+  async function regenerate() {
+    try {
+      const graphData = await source.getData();
+      const content = formatter(graphData);
+      fs.writeFileSync(outputPath, content, 'utf8');
+      const nodeCount = (graphData.nodes || []).length;
+      console.log(`[watch] ${filename} updated (${nodeCount} entities)`);
+    } catch (err) {
+      console.error(`[watch] regeneration failed: ${err.message}`);
+    }
+  }
+
+  await regenerate();
+
+  const intervalId = setInterval(regenerate, intervalMs);
+
+  let fileWatcher = null;
+  let debounceTimer = null;
+  const registryPath = path.resolve(process.cwd(), '.aios-core/data/entity-registry.yaml');
+
+  try {
+    if (fs.existsSync(registryPath)) {
+      fileWatcher = fs.watch(registryPath, () => {
+        if (debounceTimer) {
+          clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(regenerate, DEBOUNCE_MS);
+      });
+    }
+  } catch (_err) {
+    // fs.watch not available or path inaccessible; interval-only mode
+  }
+
+  function cleanup() {
+    clearInterval(intervalId);
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    if (fileWatcher) {
+      fileWatcher.close();
+    }
+    console.log('[watch] stopped');
+  }
+
+  process.once('SIGINT', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  return { intervalId, fileWatcher, cleanup, outputPath };
+}
+
+/**
+ * Handle --stats command: render entity statistics and cache metrics.
+ * @param {Object} args - Parsed CLI args
+ */
+async function handleStats(_args) {
+  const registrySource = new RegistrySource();
+  const metricsSource = new MetricsSource();
+  const [registryData, metricsData] = await Promise.all([
+    registrySource.getData(),
+    metricsSource.getData(),
+  ]);
+  const isTTY = process.stdout.isTTY;
+  const output = renderStats(registryData, metricsData, { isTTY: !!isTTY });
+
+  process.stdout.write(output + '\n');
+}
+
+/**
+ * Handle --help command: show usage text.
+ */
+function handleHelp() {
+  const usage = `
+Usage: aios graph [command] [options]
+
+Commands:
+  --deps          Show dependency tree as ASCII text
+  --stats         Show entity statistics and cache metrics
+  --help, -h      Show this help message
+
+Options:
+  --format=FORMAT Output format: ascii (default), json, dot, mermaid, html
+  --watch         Live mode: regenerate graph file on interval
+  --interval=N    Seconds between regeneration in watch mode (default: 5)
+
+Examples:
+  aios graph --deps                        Show dependency tree
+  aios graph --deps --format=json          Output as JSON
+  aios graph --deps --format=html          Interactive HTML graph (opens browser)
+  aios graph --deps --watch                Live DOT file for VS Code preview
+  aios graph --deps --watch --format=html  Live HTML with auto-refresh
+  aios graph --deps --watch --format=mermaid  Live Mermaid file
+  aios graph --deps --watch --interval=10  Refresh every 10 seconds
+  aios graph --stats                       Show entity stats and cache metrics
+`.trim();
+
+  console.log(usage);
+}
+
+/**
+ * Handle default summary view: dependency tree (compact) + stats + provider status.
+ * @param {Object} args - Parsed CLI args
+ */
+async function handleSummary(args) {
+  const codeIntelSource = new CodeIntelSource();
+  const registrySource = new RegistrySource();
+  const metricsSource = new MetricsSource();
+
+  const [graphData, registryData, metricsData] = await Promise.all([
+    codeIntelSource.getData(),
+    registrySource.getData(),
+    metricsSource.getData(),
+  ]);
+
+  const isTTY = !!process.stdout.isTTY;
+  const sections = [];
+
+  sections.push('AIOS Graph Dashboard');
+  sections.push(isTTY ? '\u2550'.repeat(35) : '='.repeat(35));
+  sections.push('');
+
+  const treeOutput = renderTree(graphData, {
+    color: isTTY,
+    unicode: isTTY,
+    maxPerCategory: MAX_SUMMARY_PER_CATEGORY,
+  });
+  sections.push(treeOutput);
+  sections.push('');
+
+  const statsOutput = renderStats(registryData, metricsData, { isTTY });
+  sections.push(statsOutput);
+  sections.push('');
+
+  const statusOutput = renderStatus(metricsData, { isTTY });
+  sections.push(statusOutput);
+
+  process.stdout.write(sections.join('\n') + '\n');
+}
+
+/**
+ * Main CLI entry point.
+ * @param {string[]} argv - Raw CLI arguments
+ */
+async function run(argv) {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    handleHelp();
+    return;
+  }
+
+  if (args.command === null) {
+    return handleSummary(args);
+  }
+
+  const handler = COMMANDS[args.command];
+  if (!handler) {
+    console.error(`Unknown command: ${args.command}`);
+    handleHelp();
+    process.exit(1);
+  }
+
+  return handler(args);
+}
+
+module.exports = {
+  run,
+  parseArgs,
+  handleDeps,
+  handleStats,
+  handleHelp,
+  handleWatch,
+  handleSummary,
+  handleHtmlOutput,
+  openInBrowser,
+  MAX_SUMMARY_PER_CATEGORY,
+  DEFAULT_WATCH_INTERVAL_MS,
+  DEBOUNCE_MS,
+  FORMAT_MAP,
+  VALID_FORMATS,
+  WATCH_FORMAT_MAP,
+};

package/.aios-core/core/graph-dashboard/data-sources/code-intel-source.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const { getClient, isCodeIntelAvailable } = require('../../code-intel');
+const { RegistryLoader } = require('../../ids/registry-loader');
+
+/**
+ * Data source that provides normalized graph data from code-intel
+ * or falls back to entity-registry.yaml when provider is offline.
+ */
+/**
+ * Classify a script entity into subcategory based on its path.
+ * @param {string} filePath - Entity path
+ * @returns {string} 'scripts/task' | 'scripts/engine' | 'scripts/infra'
+ */
+function _classifyScript(filePath) {
+  if (filePath.includes('/development/scripts/')) return 'scripts/task';
+  if (filePath.includes('/core/')) return 'scripts/engine';
+  if (filePath.includes('/infrastructure/')) return 'scripts/infra';
+  return 'scripts/task';
+}
+
+/**
+ * Detect fine-grained category from entity path and base category.
+ * @param {string} baseCategory - Original category from registry/provider
+ * @param {string} filePath - Entity path
+ * @returns {string} Refined category
+ */
+function _detectCategory(baseCategory, filePath) {
+  const path = (filePath || '').toLowerCase();
+
+  if (path.includes('/checklists/')) return 'checklists';
+  if (path.includes('/workflows/')) return 'workflows';
+  if (path.includes('/utils/')) return 'utils';
+  if (path.includes('/data/')) return 'data';
+  if (path.includes('/tools/')) return 'tools';
+
+  if (baseCategory === 'scripts' || path.includes('/scripts/')) {
+    return _classifyScript(path);
+  }
+
+  return baseCategory;
+}
+
+class CodeIntelSource {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.cacheTTL=5000] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this._cache = null;
+    this._cacheTimestamp = 0;
+    this._cacheTTL = options.cacheTTL || 5000;
+  }
+
+  /**
+   * Get normalized graph data.
+   * Primary: code-intel provider (live data).
+   * Fallback: entity-registry.yaml (static data).
+   * @returns {Promise<Object>} { nodes, edges, source, isFallback, timestamp }
+   */
+  async getData() {
+    if (this._cache && !this.isStale()) {
+      return this._cache;
+    }
+
+    let result;
+
+    try {
+      if (isCodeIntelAvailable()) {
+        const client = getClient();
+        const deps = await client.analyzeDependencies('.');
+        result = this._wrap(this._normalizeDeps(deps), 'code-intel', false);
+      } else {
+        result = this._getRegistryFallback();
+      }
+    } catch (_err) {
+      result = this._getRegistryFallback();
+    }
+
+    this._cache = result;
+    this._cacheTimestamp = Date.now();
+    return result;
+  }
+
+  /**
+   * Get timestamp of last successful data fetch.
+   * @returns {number}
+   */
+  getLastUpdate() {
+    return this._cacheTimestamp;
+  }
+
+  /**
+   * Check if cached data is expired.
+   * @returns {boolean}
+   */
+  isStale() {
+    return Date.now() - this._cacheTimestamp > this._cacheTTL;
+  }
+
+  /**
+   * Load graph data from entity-registry.yaml as fallback.
+   * @returns {Object} Wrapped graph data
+   */
+  _getRegistryFallback() {
+    try {
+      const loader = new RegistryLoader();
+      const registry = loader.load();
+      return this._wrap(this._registryToTree(registry), 'registry', true);
+    } catch (_err) {
+      return this._wrap({ nodes: [], edges: [] }, 'registry', true);
+    }
+  }
+
+  /**
+   * Normalize analyzeDependencies output to { nodes, edges }.
+   * Handles various shapes from different providers.
+   * @param {*} deps - Raw output from analyzeDependencies
+   * @returns {Object} { nodes: Array, edges: Array }
+   */
+  _normalizeDeps(deps) {
+    if (!deps) {
+      return { nodes: [], edges: [] };
+    }
+
+    // Already normalized format
+    if (Array.isArray(deps.nodes) && Array.isArray(deps.edges)) {
+      return { nodes: deps.nodes, edges: deps.edges };
+    }
+
+    // Array of dependency objects
+    if (Array.isArray(deps)) {
+      const nodes = [];
+      const edges = [];
+      const seen = new Set();
+
+      for (const dep of deps) {
+        const id = dep.id || dep.name || dep.path;
+        if (!id || seen.has(id)) continue;
+        seen.add(id);
+
+        nodes.push({
+          id,
+          label: dep.label || dep.name || id,
+          type: dep.type || 'unknown',
+          path: dep.path || '',
+          category: _detectCategory(dep.category || dep.type || 'other', dep.path || ''),
+        });
+
+        for (const target of dep.dependencies || dep.deps || []) {
+          edges.push({ from: id, to: target, type: 'depends' });
+        }
+      }
+
+      return { nodes, edges };
+    }
+
+    // Flat object with dependencies property
+    if (deps.dependencies && typeof deps.dependencies === 'object') {
+      return this._normalizeDeps(
+        Object.entries(deps.dependencies).map(([key, val]) => ({
+          id: key,
+          ...((typeof val === 'object' && val) || {}),
+        }))
+      );
+    }
+
+    return { nodes: [], edges: [] };
+  }
+
+  /**
+   * Convert entity-registry to normalized graph format.
+   * Groups entities by category and maps dependencies/usedBy to edges.
+   * @param {Object} registry - Loaded registry data
+   * @returns {Object} { nodes: Array, edges: Array }
+   */
+  _registryToTree(registry) {
+    const nodes = [];
+    const edges = [];
+    const edgeSet = new Set();
+
+    for (const [category, entities] of Object.entries(registry.entities || {})) {
+      if (!entities || typeof entities !== 'object') continue;
+
+      for (const [entityId, entity] of Object.entries(entities)) {
+        nodes.push({
+          id: entityId,
+          label: entityId,
+          type: entity.type || category,
+          path: entity.path || '',
+          category: _detectCategory(category, entity.path || ''),
+          lifecycle: entity.lifecycle || 'production',  // NOG-16C: pass lifecycle for graph filtering
+        });
+
+        for (const dep of entity.dependencies || []) {
+          const edgeKey = `${entityId}->depends->${dep}`;
+          if (!edgeSet.has(edgeKey)) {
+            edgeSet.add(edgeKey);
+            edges.push({ from: entityId, to: dep, type: 'depends' });
+          }
+        }
+
+        for (const consumer of entity.usedBy || []) {
+          const edgeKey = `${consumer}->uses->${entityId}`;
+          if (!edgeSet.has(edgeKey)) {
+            edgeSet.add(edgeKey);
+            edges.push({ from: consumer, to: entityId, type: 'uses' });
+          }
+        }
+      }
+    }
+
+    return { nodes, edges };
+  }
+
+  /**
+   * Wrap data in standard result envelope.
+   * @param {Object} data - { nodes, edges }
+   * @param {string} source - 'code-intel' | 'registry'
+   * @param {boolean} isFallback
+   * @returns {Object}
+   */
+  _wrap(data, source, isFallback) {
+    return {
+      nodes: data.nodes || [],
+      edges: data.edges || [],
+      source,
+      isFallback,
+      timestamp: Date.now(),
+    };
+  }
+}
+
+module.exports = { CodeIntelSource, _classifyScript, _detectCategory };

package/.aios-core/core/graph-dashboard/data-sources/metrics-source.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const { getClient, isCodeIntelAvailable } = require('../../code-intel');
+
+/**
+ * Data source that provides cache and latency metrics from the code-intel client.
+ * Falls back to offline data when Code Graph MCP is unavailable.
+ * Implements the same interface as CodeIntelSource: getData(), getLastUpdate(), isStale().
+ */
+class MetricsSource {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.cacheTTL=5000] - Cache TTL in milliseconds
+   */
+  constructor(options = {}) {
+    this._cache = null;
+    this._cacheTimestamp = 0;
+    this._cacheTTL = options.cacheTTL || 5000;
+  }
+
+  /**
+   * Get metrics from code-intel client.
+   * Primary: live metrics from active provider.
+   * Fallback: offline placeholder with providerAvailable=false.
+   * @returns {Promise<Object>} Metrics object
+   */
+  async getData() {
+    if (this._cache && !this.isStale()) {
+      return this._cache;
+    }
+
+    let result;
+
+    try {
+      if (isCodeIntelAvailable()) {
+        const client = getClient();
+        const metrics = client.getMetrics();
+        result = {
+          cacheHits: metrics.cacheHits || 0,
+          cacheMisses: metrics.cacheMisses || 0,
+          cacheHitRate: metrics.cacheHitRate || 0,
+          circuitBreakerState: metrics.circuitBreakerState || 'CLOSED',
+          latencyLog: metrics.latencyLog || [],
+          providerAvailable: true,
+          activeProvider: metrics.activeProvider || null,
+          timestamp: Date.now(),
+        };
+      } else {
+        result = this._offlineMetrics();
+      }
+    } catch (_err) {
+      result = this._offlineMetrics();
+    }
+
+    this._cache = result;
+    this._cacheTimestamp = Date.now();
+    return result;
+  }
+
+  /**
+   * Get timestamp of last successful data fetch.
+   * @returns {number}
+   */
+  getLastUpdate() {
+    return this._cacheTimestamp;
+  }
+
+  /**
+   * Check if cached data is expired.
+   * @returns {boolean}
+   */
+  isStale() {
+    return Date.now() - this._cacheTimestamp > this._cacheTTL;
+  }
+
+  /**
+   * Return offline placeholder metrics.
+   * @returns {Object}
+   * @private
+   */
+  _offlineMetrics() {
+    return {
+      cacheHits: 0,
+      cacheMisses: 0,
+      cacheHitRate: 0,
+      circuitBreakerState: 'CLOSED',
+      latencyLog: [],
+      providerAvailable: false,
+      activeProvider: null,
+      timestamp: Date.now(),
+    };
+  }
+}
+
+module.exports = { MetricsSource };