@grafema/cli 0.2.3-beta → 0.2.5-beta

package/src/commands/explore.tsx

@@ -160,9 +160,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
           }));
         }
       } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
         setState(s => ({
           ...s,
-          error: (err as Error).message,
+          error: message,
           loading: false,
         }));
       }
@@ -387,9 +388,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
         error: results.length === 0 ? `No results for "${query}"` : null,
       }));
     } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
       setState(s => ({
         ...s,
-        error: (err as Error).message,
+        error: message,
         loading: false,
       }));
     }
@@ -408,9 +410,10 @@ function Explorer({ backend, startNode, projectPath }: ExplorerProps) {
         loading: false,
       }));
     } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
       setState(s => ({
         ...s,
-        error: (err as Error).message,
+        error: message,
         loading: false,
       }));
     }
@@ -1010,7 +1013,8 @@ async function runBatchExplore(
       outputResults(callees, 'callees', useJson, projectPath, target);
     }
   } catch (err) {
-    exitWithError(`Explore failed: ${(err as Error).message}`);
+    const message = err instanceof Error ? err.message : String(err);
+    exitWithError(`Explore failed: ${message}`);
   }
 }
 

package/src/commands/get.ts

@@ -12,6 +12,7 @@ import { existsSync } from 'fs';
 import { RFDBServerBackend } from '@grafema/core';
 import { formatNodeDisplay } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
 
 interface GetOptions {
   project: string;
@@ -66,11 +67,15 @@ Examples:
     const backend = new RFDBServerBackend({ dbPath });
     await backend.connect();
 
+    const spinner = new Spinner('Querying graph...');
+    spinner.start();
+
     try {
       // Retrieve node by semantic ID
       const node = await backend.getNode(semanticId);
 
       if (!node) {
+        spinner.stop();
         exitWithError('Node not found', [
           `ID: ${semanticId}`,
           'Try: grafema query "<name>" to search for nodes',
@@ -81,6 +86,8 @@ Examples:
       const incomingEdges = await backend.getIncomingEdges(semanticId, null);
       const outgoingEdges = await backend.getOutgoingEdges(semanticId, null);
 
+      spinner.stop();
+
       if (options.json) {
         await outputJSON(backend, node, incomingEdges, outgoingEdges);
       } else {
@@ -88,6 +95,7 @@ Examples:
       }
 
     } finally {
+      spinner.stop();
       await backend.close();
     }
   });

package/src/commands/impact.ts

@@ -10,7 +10,7 @@ import { Command } from 'commander';
 import { resolve, join, dirname } from 'path';
 import { relative } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore, type CallerInfo } from '@grafema/core';
+import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 

package/src/commands/init.ts

@@ -8,7 +8,6 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { createInterface } from 'readline';
 import { fileURLToPath } from 'url';
-import { exitWithError } from '../utils/errorFormatter.js';
 import { stringify as stringifyYAML } from 'yaml';
 import { DEFAULT_CONFIG } from '@grafema/core';
 
@@ -75,7 +74,9 @@ function askYesNo(question: string): Promise<boolean> {
 function runAnalyze(projectPath: string): Promise<number> {
   return new Promise((resolve) => {
     const cliPath = join(__dirname, '..', 'cli.js');
-    const child = spawn('node', [cliPath, 'analyze', projectPath], {
+    // Use process.execPath (absolute path to current Node binary) instead of
+    // 'node' to avoid PATH lookup failures when nvm isn't loaded in the shell.
+    const child = spawn(process.execPath, [cliPath, 'analyze', projectPath], {
       stdio: 'inherit', // Pass through all I/O for user to see progress
     });
     child.on('close', (code) => resolve(code ?? 1));
@@ -92,6 +93,9 @@ function printNextSteps(): void {
   console.log('  1. Review config:  code .grafema/config.yaml');
   console.log('  2. Build graph:    grafema analyze');
   console.log('  3. Explore:        grafema overview');
+  console.log('');
+  console.log('For AI-assisted setup, use the Grafema MCP server');
+  console.log('with the "onboard_project" prompt.');
 }
 
 /**

package/src/commands/ls.ts

@@ -15,6 +15,7 @@ import { resolve, join, relative } from 'path';
 import { existsSync } from 'fs';
 import { RFDBServerBackend } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
 
 interface LsOptions {
   project: string;
@@ -66,6 +67,9 @@ Discover available types:
     const backend = new RFDBServerBackend({ dbPath });
     await backend.connect();
 
+    const spinner = new Spinner('Querying graph...');
+    spinner.start();
+
     try {
       const limit = parseInt(options.limit, 10);
       const nodeType = options.type;
@@ -73,6 +77,7 @@ Discover available types:
       // Check if type exists in graph
       const typeCounts = await backend.countNodesByType();
       if (!typeCounts[nodeType]) {
+        spinner.stop();
         const availableTypes = Object.keys(typeCounts).sort();
         exitWithError(`No nodes of type "${nodeType}" found`, [
           'Available types:',
@@ -103,6 +108,8 @@ Discover available types:
       const totalCount = typeCounts[nodeType];
       const showing = nodes.length;
 
+      spinner.stop();
+
       if (options.json) {
         console.log(JSON.stringify({
           type: nodeType,
@@ -125,6 +132,7 @@ Discover available types:
         }
       }
     } finally {
+      spinner.stop();
       await backend.close();
     }
   });

package/src/commands/overview.ts

@@ -8,10 +8,6 @@ import { existsSync } from 'fs';
 import { RFDBServerBackend } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
-interface NodeStats {
-  type: string;
-  count: number;
-}
 
 export const overviewCommand = new Command('overview')
   .description('Show project overview and statistics')

package/src/commands/query.ts

@@ -15,6 +15,7 @@ import { existsSync } from 'fs';
 import { RFDBServerBackend, parseSemanticId, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline, formatLocation } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
 
 interface QueryOptions {
   project: string;
@@ -130,9 +131,13 @@ Examples:
     const backend = new RFDBServerBackend({ dbPath });
     await backend.connect();
 
+    const spinner = new Spinner('Querying graph...');
+    spinner.start();
+
     try {
       // Raw Datalog mode
       if (options.raw) {
+        spinner.stop();
         await executeRawQuery(backend, pattern, options);
         return;
       }
@@ -159,6 +164,8 @@ Examples:
       // Find matching nodes
       const nodes = await findNodes(backend, query, limit);
 
+      spinner.stop();
+
       // Check if query has scope constraints for suggestion
       const hasScope = query.file !== null || query.scopes.length > 0;
 
@@ -218,6 +225,7 @@ Examples:
       }
 
     } finally {
+      spinner.stop();
       await backend.close();
     }
   });
@@ -254,6 +262,11 @@ function parsePattern(pattern: string): { type: string | null; name: string } {
       emit: 'socketio:emit',
       on: 'socketio:on',
       listener: 'socketio:on',
+      // Grafema internal
+      plugin: 'grafema:plugin',
+      // Property access aliases (REG-395)
+      property: 'PROPERTY_ACCESS',
+      prop: 'PROPERTY_ACCESS',
     };
 
     if (typeMap[typeWord]) {
@@ -551,7 +564,8 @@ async function findNodes(
         'http:request',
         'socketio:event',
         'socketio:emit',
-        'socketio:on'
+        'socketio:on',
+        'PROPERTY_ACCESS'
       ];
 
   for (const nodeType of searchTypes) {
@@ -606,6 +620,21 @@ async function findNodes(
         nodeInfo.handlerName = node.handlerName as string | undefined;
       }
 
+      // Include plugin-specific fields
+      if (nodeType === 'grafema:plugin') {
+        nodeInfo.phase = node.phase as string | undefined;
+        nodeInfo.priority = node.priority as number | undefined;
+        nodeInfo.builtin = node.builtin as boolean | undefined;
+        nodeInfo.createsNodes = node.createsNodes as string[] | undefined;
+        nodeInfo.createsEdges = node.createsEdges as string[] | undefined;
+        nodeInfo.dependencies = node.dependencies as string[] | undefined;
+      }
+
+      // Include objectName for PROPERTY_ACCESS nodes (REG-395)
+      if (nodeType === 'PROPERTY_ACCESS') {
+        nodeInfo.objectName = node.objectName as string | undefined;
+      }
+
       results.push(nodeInfo);
       if (results.length >= limit) break;
     }
@@ -735,6 +764,12 @@ async function displayNode(node: NodeInfo, projectPath: string, backend: RFDBSer
     return;
   }
 
+  // Special formatting for Grafema plugin nodes
+  if (node.type === 'grafema:plugin') {
+    console.log(formatPluginDisplay(node, projectPath));
+    return;
+  }
+
   console.log(formatNodeDisplay(node, { projectPath }));
 
   // Add scope context if present
@@ -890,6 +925,47 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
   return lines.join('\n');
 }
 
+/**
+ * Format Grafema plugin node for display.
+ *
+ * Output:
+ *   [grafema:plugin] HTTPConnectionEnricher
+ *     Phase: ENRICHMENT (priority: 50)
+ *     Creates: edges: INTERACTS_WITH, HTTP_RECEIVES
+ *     Dependencies: ExpressRouteAnalyzer, FetchAnalyzer, ExpressResponseAnalyzer
+ *     Source: packages/core/src/plugins/enrichment/HTTPConnectionEnricher.ts
+ */
+function formatPluginDisplay(node: NodeInfo, projectPath: string): string {
+  const lines: string[] = [];
+
+  lines.push(`[${node.type}] ${node.name}`);
+
+  const phase = (node.phase as string) || 'unknown';
+  const priority = (node.priority as number) ?? 0;
+  lines.push(`  Phase: ${phase} (priority: ${priority})`);
+
+  const createsNodes = (node.createsNodes as string[]) || [];
+  const createsEdges = (node.createsEdges as string[]) || [];
+  const createsParts: string[] = [];
+  if (createsNodes.length > 0) createsParts.push(`nodes: ${createsNodes.join(', ')}`);
+  if (createsEdges.length > 0) createsParts.push(`edges: ${createsEdges.join(', ')}`);
+  if (createsParts.length > 0) {
+    lines.push(`  Creates: ${createsParts.join('; ')}`);
+  }
+
+  const deps = (node.dependencies as string[]) || [];
+  if (deps.length > 0) {
+    lines.push(`  Dependencies: ${deps.join(', ')}`);
+  }
+
+  if (node.file) {
+    const relPath = relative(projectPath, node.file);
+    lines.push(`  Source: ${relPath}`);
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Execute raw Datalog query (backwards compat)
  */

package/src/commands/server.ts

@@ -1,10 +1,11 @@
 /**
- * Server command - Manage RFDB server lifecycle
+ * Server command - Manage RFDB (Rega Flow Database) server lifecycle
  *
  * Provides explicit control over the RFDB server process:
  *   grafema server start   - Start detached server
  *   grafema server stop    - Stop server gracefully
  *   grafema server status  - Check if server is running
+ *   grafema server graphql - Start GraphQL API server
  */
 
 import { Command } from 'commander';
@@ -13,7 +14,7 @@ import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient, loadConfig } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -124,7 +125,7 @@ function getProjectPaths(projectPath: string) {
 
 // Create main server command with subcommands
 export const serverCommand = new Command('server')
-  .description('Manage RFDB server lifecycle')
+  .description('Manage RFDB (Rega Flow Database) server lifecycle')
   .addHelpText('after', `
 Examples:
   grafema server start                       Start the RFDB server
@@ -395,3 +396,56 @@ serverCommand
       }
     }
   });
+
+// grafema server graphql
+serverCommand
+  .command('graphql')
+  .description('Start GraphQL API server (requires RFDB server running)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('--port <number>', 'Port to listen on', '4000')
+  .option('--host <string>', 'Hostname to bind to', 'localhost')
+  .action(async (options: { project: string; port: string; host: string }) => {
+    const projectPath = resolve(options.project);
+    const { socketPath } = getProjectPaths(projectPath);
+
+    // Check if RFDB server is running
+    const status = await isServerRunning(socketPath);
+    if (!status.running) {
+      exitWithError('RFDB server not running', [
+        'Start the server first: grafema server start',
+        'Or run: grafema analyze (starts server automatically)'
+      ]);
+    }
+
+    // Create backend connection
+    const backend = new RFDBServerBackend({ socketPath });
+    await backend.connect();
+
+    // Import and start GraphQL server
+    const { startServer } = await import('@grafema/api');
+    const port = parseInt(options.port, 10);
+
+    console.log('Starting Grafema GraphQL API...');
+    console.log(`  RFDB Socket: ${socketPath}`);
+    if (status.version) {
+      console.log(`  RFDB Version: ${status.version}`);
+    }
+    console.log('');
+
+    const server = startServer({
+      backend,
+      port,
+      hostname: options.host,
+    });
+
+    // Handle shutdown
+    const shutdown = async () => {
+      console.log('\nShutting down GraphQL server...');
+      server.close();
+      await backend.close();
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });

package/src/utils/progressRenderer.ts

@@ -0,0 +1,288 @@
+/**
+ * ProgressRenderer - Formats and displays analysis progress for CLI.
+ *
+ * Consumes ProgressInfo events from Orchestrator and renders them as
+ * user-friendly progress output with phase tracking, elapsed time,
+ * and spinner animation.
+ *
+ * @example
+ * ```typescript
+ * const renderer = new ProgressRenderer({ isInteractive: true });
+ * orchestrator.run({
+ *   onProgress: (info) => renderer.update(info),
+ * });
+ * console.log(renderer.finish(elapsed));
+ * ```
+ */
+
+import type { ProgressInfo } from '@grafema/core';
+
+/**
+ * Options for creating a ProgressRenderer instance.
+ */
+export interface ProgressRendererOptions {
+  /** Whether output is to a TTY (enables spinner and line overwriting) */
+  isInteractive?: boolean;
+  /** Minimum milliseconds between display updates (default: 100) */
+  throttle?: number;
+  /** Custom write function for output (default: process.stdout.write) */
+  write?: (text: string) => void;
+}
+
+/**
+ * ProgressRenderer - Formats and displays analysis progress for CLI.
+ *
+ * Consumes ProgressInfo events from Orchestrator and renders them as
+ * user-friendly progress output with phase tracking, elapsed time,
+ * and spinner animation.
+ */
+export class ProgressRenderer {
+  private phases: string[] = ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'];
+  private currentPhaseIndex: number = -1;
+  private currentPhase: string = '';
+  private currentPlugin: string = '';
+  private message: string = '';
+  private totalFiles: number = 0;
+  private processedFiles: number = 0;
+  private servicesAnalyzed: number = 0;
+  private spinnerIndex: number = 0;
+  private isInteractive: boolean;
+  private startTime: number;
+  private lastDisplayTime: number = 0;
+  private displayThrottle: number;
+  private write: (text: string) => void;
+  private spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  private activePlugins: string[] = [];
+  private nodeCount: number = 0;
+  private edgeCount: number = 0;
+
+  constructor(options?: ProgressRendererOptions) {
+    this.isInteractive = options?.isInteractive ?? process.stdout.isTTY ?? false;
+    this.displayThrottle = options?.throttle ?? 100;
+    this.startTime = Date.now();
+    this.write = options?.write ?? ((text: string) => process.stdout.write(text));
+  }
+
+  /**
+   * Process a progress event from Orchestrator.
+   * Updates internal state and displays formatted output if throttle allows.
+   */
+  update(info: ProgressInfo): void {
+    // Update phase tracking
+    if (info.phase && info.phase !== this.currentPhase) {
+      this.currentPhase = info.phase;
+      const idx = this.phases.indexOf(info.phase);
+      if (idx !== -1) {
+        this.currentPhaseIndex = idx;
+      }
+      // Reset phase-specific state
+      this.activePlugins = [];
+    }
+
+    // Update state from progress info
+    if (info.currentPlugin !== undefined) {
+      this.currentPlugin = info.currentPlugin;
+      // Track active plugins for enrichment/validation display
+      if ((this.currentPhase === 'enrichment' || this.currentPhase === 'validation') &&
+          info.currentPlugin && !this.activePlugins.includes(info.currentPlugin)) {
+        this.activePlugins.push(info.currentPlugin);
+      }
+    }
+    if (info.message !== undefined) {
+      this.message = info.message;
+    }
+    if (info.totalFiles !== undefined) {
+      this.totalFiles = info.totalFiles;
+    }
+    if (info.processedFiles !== undefined) {
+      this.processedFiles = info.processedFiles;
+    }
+    if (info.servicesAnalyzed !== undefined) {
+      this.servicesAnalyzed = info.servicesAnalyzed;
+    }
+
+    // Update spinner
+    this.spinnerIndex = (this.spinnerIndex + 1) % this.spinnerFrames.length;
+
+    // Check throttling
+    const now = Date.now();
+    if (now - this.lastDisplayTime < this.displayThrottle) {
+      return;
+    }
+    this.lastDisplayTime = now;
+
+    this.display();
+  }
+
+  /**
+   * Update graph statistics (called separately from progress events).
+   * This allows real-time node/edge count updates.
+   */
+  setStats(nodeCount: number, edgeCount: number): void {
+    this.nodeCount = nodeCount;
+    this.edgeCount = edgeCount;
+  }
+
+  /**
+   * Format and display current state to console.
+   */
+  private display(): void {
+    const output = this.formatOutput();
+
+    if (this.isInteractive) {
+      // TTY mode: overwrite previous line, pad with spaces to clear old content
+      const padded = output.padEnd(80, ' ');
+      this.write(`\r${padded}`);
+    } else {
+      // Non-TTY mode: append newline
+      this.write(`${output}\n`);
+    }
+  }
+
+  private formatOutput(): string {
+    if (this.isInteractive) {
+      return this.formatInteractive();
+    } else {
+      return this.formatNonInteractive();
+    }
+  }
+
+  /**
+   * Format elapsed time as human-readable string.
+   */
+  private formatElapsed(): string {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    if (elapsed < 60) {
+      return `${elapsed.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(elapsed / 60);
+    const seconds = Math.floor(elapsed % 60);
+    return `${minutes}m${seconds}s`;
+  }
+
+  private formatInteractive(): string {
+    const spinner = this.spinnerFrames[this.spinnerIndex];
+    const elapsed = this.formatElapsed();
+    const phaseLabel = this.getPhaseLabel();
+    const progress = this.formatPhaseProgress();
+    const stats = this.formatStats();
+
+    // Format: ⠋ [3/5] Analysis... 150/4047 modules | 12.5s | 1.2M nodes
+    return `${spinner} ${phaseLabel}${progress} | ${elapsed}${stats}`;
+  }
+
+  private formatNonInteractive(): string {
+    const elapsed = this.formatElapsed();
+    return `[${this.currentPhase}] ${this.message || this.formatPhaseProgress()} (${elapsed})`;
+  }
+
+  /**
+   * Format node/edge counts if available.
+   */
+  private formatStats(): string {
+    if (this.nodeCount === 0 && this.edgeCount === 0) {
+      return '';
+    }
+    const nodes = this.formatNumber(this.nodeCount);
+    const edges = this.formatNumber(this.edgeCount);
+    return ` | ${nodes} nodes, ${edges} edges`;
+  }
+
+  /**
+   * Format large numbers with K/M suffix.
+   */
+  private formatNumber(n: number): string {
+    if (n >= 1_000_000) {
+      return `${(n / 1_000_000).toFixed(1)}M`;
+    }
+    if (n >= 1_000) {
+      return `${(n / 1_000).toFixed(1)}K`;
+    }
+    return String(n);
+  }
+
+  /**
+   * Get formatted phase label with number, e.g., "[3/5] Analysis..."
+   */
+  private getPhaseLabel(): string {
+    const phaseNum = this.currentPhaseIndex + 1;
+    const totalPhases = this.phases.length;
+    const phaseName = this.currentPhase.charAt(0).toUpperCase() + this.currentPhase.slice(1);
+    return `[${phaseNum}/${totalPhases}] ${phaseName}...`;
+  }
+
+  /**
+   * Format progress details based on current phase.
+   */
+  private formatPhaseProgress(): string {
+    switch (this.currentPhase) {
+      case 'discovery':
+        if (this.servicesAnalyzed > 0) {
+          return ` ${this.servicesAnalyzed} services found`;
+        }
+        return '';
+      case 'indexing':
+      case 'analysis':
+        if (this.totalFiles > 0) {
+          return ` ${this.processedFiles}/${this.totalFiles} modules`;
+        }
+        return '';
+      case 'enrichment':
+      case 'validation':
+        if (this.activePlugins.length > 0) {
+          return ` (${this.formatPluginList(this.activePlugins)})`;
+        }
+        return '';
+      default:
+        return '';
+    }
+  }
+
+  /**
+   * Format plugin list, truncating if more than 3 plugins.
+   */
+  private formatPluginList(plugins: string[]): string {
+    if (plugins.length <= 3) {
+      return plugins.join(', ');
+    }
+    // Truncate to 3 plugins + "..."
+    return plugins.slice(0, 3).join(', ') + ', ...';
+  }
+
+  /**
+   * Get final summary message after analysis complete.
+   * @param durationSeconds - Total duration of analysis
+   * @returns Formatted completion message
+   */
+  finish(durationSeconds: number): string {
+    return `Analysis complete in ${durationSeconds.toFixed(2)}s`;
+  }
+
+  /**
+   * Expose internal state for testing.
+   * @internal
+   */
+  getState(): {
+    phaseIndex: number;
+    phase: string;
+    processedFiles: number;
+    totalFiles: number;
+    servicesAnalyzed: number;
+    spinnerIndex: number;
+    activePlugins: string[];
+    nodeCount: number;
+    edgeCount: number;
+  } {
+    return {
+      phaseIndex: this.currentPhaseIndex,
+      phase: this.currentPhase,
+      processedFiles: this.processedFiles,
+      totalFiles: this.totalFiles,
+      servicesAnalyzed: this.servicesAnalyzed,
+      spinnerIndex: this.spinnerIndex,
+      activePlugins: [...this.activePlugins],
+      nodeCount: this.nodeCount,
+      edgeCount: this.edgeCount,
+    };
+  }
+}