@grafema/cli 0.2.4-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,25 +1,94 @@
 /**
- * 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';
-import { resolve, join } from 'path';
+import { resolve, join, dirname } from 'path';
 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, findRfdbBinary, getBinaryNotFoundMessage } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
 // Extend config type for server settings
 interface ServerConfig {
   binaryPath?: string;
 }
 
+/**
+ * Find RFDB server binary in order of preference:
+ * 1. Explicit path (from --binary flag or config)
+ * 2. Monorepo development (target/release, target/debug)
+ * 3. @grafema/rfdb npm package (prebuilt binaries)
+ * 4. ~/.local/bin/rfdb-server (user-installed)
+ */
+function findServerBinary(explicitPath?: string): string | null {
+  // 1. Explicit path from --binary flag or config
+  if (explicitPath) {
+    const resolved = resolve(explicitPath);
+    if (existsSync(resolved)) {
+      return resolved;
+    }
+    // Explicit path specified but not found - this is an error
+    console.error(`Specified binary not found: ${resolved}`);
+    return null;
+  }
+
+  // 2. Check packages/rfdb-server in monorepo (for development)
+  const projectRoot = join(__dirname, '../../../..');
+  const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
+  if (existsSync(releaseBinary)) {
+    return releaseBinary;
+  }
+
+  const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
+  if (existsSync(debugBinary)) {
+    return debugBinary;
+  }
+
+  // 3. Check @grafema/rfdb npm package
+  try {
+    const rfdbPkg = require.resolve('@grafema/rfdb');
+    const rfdbDir = dirname(rfdbPkg);
+    const platform = process.platform;
+    const arch = process.arch;
+
+    let platformDir: string;
+    if (platform === 'darwin') {
+      platformDir = arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+    } else if (platform === 'linux') {
+      platformDir = arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+    } else {
+      platformDir = `${platform}-${arch}`;
+    }
+
+    const npmBinary = join(rfdbDir, 'prebuilt', platformDir, 'rfdb-server');
+    if (existsSync(npmBinary)) {
+      return npmBinary;
+    }
+  } catch {
+    // @grafema/rfdb not installed
+  }
+
+  // 4. Check ~/.local/bin (user-installed binary for unsupported platforms)
+  const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
+  if (existsSync(homeBinary)) {
+    return homeBinary;
+  }
+
+  return null;
+}
+
 /**
  * Check if server is running by attempting to ping it
  */
@@ -56,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
@@ -104,34 +173,38 @@ serverCommand
     }
 
     // Determine binary path: CLI flag > config > auto-detect
-    let explicitPath: string | undefined;
+    let binaryPath: string | null = null;
 
     if (options.binary) {
       // Explicit --binary flag
-      explicitPath = options.binary;
+      binaryPath = findServerBinary(options.binary);
     } else {
       // Try to read from config
       try {
         const config = loadConfig(projectPath);
         const serverConfig = (config as unknown as { server?: ServerConfig }).server;
         if (serverConfig?.binaryPath) {
-          explicitPath = serverConfig.binaryPath;
+          binaryPath = findServerBinary(serverConfig.binaryPath);
         }
       } catch {
         // Config not found or invalid - continue with auto-detect
       }
-    }
 
-    const binaryPath = findRfdbBinary({ explicitPath });
+      // Auto-detect if not specified
+      if (!binaryPath) {
+        binaryPath = findServerBinary();
+      }
+    }
 
     if (!binaryPath) {
-      // If explicit path was given but not found, show specific error
-      if (explicitPath) {
-        exitWithError(`Specified binary not found: ${resolve(explicitPath)}`, [
-          'Check the path and try again'
-        ]);
-      }
-      exitWithError('RFDB server binary not found', getBinaryNotFoundMessage().split('\n').slice(2));
+      exitWithError('RFDB server binary not found', [
+        'Specify path: grafema server start --binary /path/to/rfdb-server',
+        'Or add to config.yaml:',
+        '  server:',
+        '    binaryPath: /path/to/rfdb-server',
+        'Or install: npm install @grafema/rfdb',
+        'Or build: cargo build --release && cp target/release/rfdb-server ~/.local/bin/'
+      ]);
     }
 
     console.log(`Starting RFDB server...`);
@@ -323,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);
+  });