@grafema/cli 0.2.11 → 0.3.0-beta

package/src/commands/query.ts

@@ -13,10 +13,12 @@ import { Command } from 'commander';
 import { resolve, join, basename } from 'path';
 import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/util';
 import { formatNodeDisplay, formatNodeInline, formatLocation } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 import { Spinner } from '../utils/spinner.js';
+import { extractQueriedTypes, findSimilarTypes } from '../utils/queryHints.js';
+import type { DatalogExplainResult, CypherResult } from '@grafema/types';
 
 // Node type constants to avoid magic string duplication
 const HTTP_ROUTE_TYPE = 'http:route';
@@ -32,6 +34,8 @@ interface QueryOptions {
   json?: boolean;
   limit: string;
   raw?: boolean;
+  cypher?: boolean;
+  explain?: boolean;
   type?: string;  // Explicit node type (bypasses type aliases)
 }
 
@@ -106,6 +110,26 @@ Rules (must define violation/1):
   grafema query --raw 'violation(X) :- node(X, "FUNCTION").'
   grafema query --raw 'violation(X) :- node(X, "http:route"), attr(X, "method", "POST").'`
   )
+  .option(
+    '--cypher',
+    `Execute a Cypher query instead of Datalog
+
+Cypher is a graph query language with pattern-matching syntax.
+
+Examples:
+  grafema query --cypher 'MATCH (n:FUNCTION) RETURN n.name LIMIT 10'
+  grafema query --cypher 'MATCH (a)-[:CALLS]->(b) RETURN a.name, b.name'`
+  )
+  .option(
+    '--explain',
+    `Show step-by-step query execution (use with --raw)
+
+Displays each predicate evaluation, result counts, and timing.
+Useful when a query returns no results — shows where the funnel drops to zero.
+
+Example:
+  grafema query --raw 'type(X, "FUNCTION"), attr(X, "name", "main")' --explain`
+  )
   .option(
     '-t, --type <nodeType>',
     `Filter by exact node type (bypasses type aliases)
@@ -135,6 +159,7 @@ Examples:
   grafema query --type FUNCTION "auth"         Explicit type (no alias resolution)
   grafema query -t http:request "/api"         Search custom node types
   grafema query --raw 'type(X, "FUNCTION")'    Raw Datalog query
+  grafema query --cypher 'MATCH (n:FUNCTION) RETURN n.name'  Cypher query
 `)
   .action(async (pattern: string, options: QueryOptions) => {
     const projectPath = resolve(options.project);
@@ -145,7 +170,7 @@ Examples:
       exitWithError('No graph database found', ['Run: grafema analyze']);
     }
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     const spinner = new Spinner('Querying graph...');
@@ -158,10 +183,23 @@ Examples:
         exitWithError('Invalid limit', ['Use a positive number, e.g.: --limit 10']);
       }
 
+      // --explain only works with --raw
+      if (options.explain && !options.raw) {
+        spinner.stop();
+        console.error('Note: --explain requires --raw. Ignoring --explain.');
+      }
+
+      // Cypher mode
+      if (options.cypher) {
+        spinner.stop();
+        await executeCypherQuery(backend, pattern, limit, options.json);
+        return;
+      }
+
       // Raw Datalog mode
       if (options.raw) {
         spinner.stop();
-        await executeRawQuery(backend, pattern, limit, options.json);
+        await executeRawQuery(backend, pattern, limit, options.json, options.explain);
         return;
       }
 
@@ -373,7 +411,7 @@ export function isFileScope(scope: string): boolean {
 /**
  * Check if a semantic ID matches the given scope constraints.
  *
- * Uses parseSemanticId from @grafema/core for robust ID parsing.
+ * Uses parseSemanticId from @grafema/util for robust ID parsing.
  *
  * Scope matching rules:
  * - File scope: semantic ID must match the file path (full or basename)
@@ -737,7 +775,7 @@ async function getCallers(
       const callNode = await backend.getNode(edge.src);
       if (!callNode) continue;
 
-      // Find the FUNCTION that contains this CALL (use shared utility from @grafema/core)
+      // Find the FUNCTION that contains this CALL (use shared utility from @grafema/util)
       const containingFunc = await findContainingFunctionCore(backend, callNode.id);
 
       if (containingFunc && !seen.has(containingFunc.id)) {
@@ -763,7 +801,7 @@ async function getCallers(
 /**
  * Get functions that this node calls
  *
- * Uses shared utility from @grafema/core which:
+ * Uses shared utility from @grafema/util which:
  * - Follows HAS_SCOPE -> SCOPE -> CONTAINS pattern correctly
  * - Finds both CALL and METHOD_CALL nodes
  * - Only returns resolved calls (those with CALLS edges to targets)
@@ -1070,6 +1108,58 @@ export function getUnknownPredicates(query: string): string[] {
   return predicates.filter(p => !BUILTIN_PREDICATES.has(p) && !ruleHeads.has(p));
 }
 
+/**
+ * Execute Cypher query and display results in tabular format.
+ */
+async function executeCypherQuery(
+  backend: RFDBServerBackend,
+  query: string,
+  limit: number,
+  json?: boolean,
+): Promise<void> {
+  const result: CypherResult = await backend.cypherQuery(query);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.rowCount === 0) {
+    console.log('No results.');
+    return;
+  }
+
+  const limited = result.rows.slice(0, limit);
+
+  // Calculate column widths for tabular display
+  const colWidths = result.columns.map((col, i) => {
+    let maxWidth = col.length;
+    for (const row of limited) {
+      const cellLen = String(row[i] ?? '').length;
+      if (cellLen > maxWidth) maxWidth = cellLen;
+    }
+    return Math.min(maxWidth, 60); // cap at 60 chars
+  });
+
+  // Header
+  const header = result.columns.map((col, i) => col.padEnd(colWidths[i])).join('  ');
+  const separator = colWidths.map(w => '-'.repeat(w)).join('  ');
+  console.log(header);
+  console.log(separator);
+
+  // Rows
+  for (const row of limited) {
+    const line = row.map((cell, i) => {
+      const s = String(cell ?? '');
+      return s.length > colWidths[i] ? s.slice(0, colWidths[i] - 1) + '\u2026' : s.padEnd(colWidths[i]);
+    }).join('  ');
+    console.log(line);
+  }
+
+  console.log('');
+  console.log(`${limited.length}${result.rowCount > limit ? ` of ${result.rowCount}` : ''} row(s)`);
+}
+
 /**
  * Execute raw Datalog query.
  * Uses unified executeDatalog endpoint which auto-detects rules vs direct queries.
@@ -1078,8 +1168,19 @@ async function executeRawQuery(
   backend: RFDBServerBackend,
   query: string,
   limit: number,
-  json?: boolean
+  json?: boolean,
+  explain?: boolean,
 ): Promise<void> {
+  if (explain) {
+    const result = await backend.executeDatalog(query, true);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    renderExplainOutput(result, limit);
+    return;
+  }
+
   const results = await backend.executeDatalog(query);
   const limited = results.slice(0, limit);
 
@@ -1106,5 +1207,94 @@ async function executeRawQuery(
       const builtinList = [...BUILTIN_PREDICATES].join(', ');
       console.error(`Note: unknown predicate ${unknownList}. Built-in predicates: ${builtinList}`);
     }
+
+    // Type suggestions: only if there are type literals in the query
+    const { nodeTypes, edgeTypes } = extractQueriedTypes(query);
+    if (nodeTypes.length > 0 || edgeTypes.length > 0) {
+      const nodeCounts = nodeTypes.length > 0 ? await backend.countNodesByType() : {};
+      const edgeCounts = edgeTypes.length > 0 ? await backend.countEdgesByType() : {};
+      const availableNodeTypes = Object.keys(nodeCounts);
+      const availableEdgeTypes = Object.keys(edgeCounts);
+
+      if (nodeTypes.length > 0 && availableNodeTypes.length === 0) {
+        console.error('Note: graph has no nodes');
+      } else {
+        for (const queriedType of nodeTypes) {
+          if (!nodeCounts[queriedType]) {
+            const similar = findSimilarTypes(queriedType, availableNodeTypes);
+            if (similar.length > 0) {
+              console.error(`Note: unknown node type "${queriedType}". Did you mean: ${similar.join(', ')}?`);
+            } else {
+              const typeList = availableNodeTypes.slice(0, 10).join(', ');
+              const more = availableNodeTypes.length > 10 ? '...' : '';
+              console.error(`Note: unknown node type "${queriedType}". Available: ${typeList}${more}`);
+            }
+          }
+        }
+      }
+
+      if (edgeTypes.length > 0 && availableEdgeTypes.length === 0) {
+        console.error('Note: graph has no edges');
+      } else {
+        for (const queriedType of edgeTypes) {
+          if (!edgeCounts[queriedType]) {
+            const similar = findSimilarTypes(queriedType, availableEdgeTypes);
+            if (similar.length > 0) {
+              console.error(`Note: unknown edge type "${queriedType}". Did you mean: ${similar.join(', ')}?`);
+            } else {
+              const typeList = availableEdgeTypes.slice(0, 10).join(', ');
+              const more = availableEdgeTypes.length > 10 ? '...' : '';
+              console.error(`Note: unknown edge type "${queriedType}". Available: ${typeList}${more}`);
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+function renderExplainOutput(result: DatalogExplainResult, limit: number): void {
+  // Print warnings to stderr first so they're immediately visible
+  if (result.warnings && result.warnings.length > 0) {
+    console.error('Warnings:');
+    for (const warning of result.warnings) {
+      console.error(`  ${warning}`);
+    }
+    console.error('');
+  }
+
+  console.log('Explain mode \u2014 step-by-step execution:\n');
+
+  for (const step of result.explainSteps) {
+    const args = step.args.join(', ');
+    console.log(`  Step ${step.step}: [${step.operation}] ${step.predicate}(${args})`);
+    console.log(`          \u2192 ${step.resultCount} result(s) in ${step.durationUs} \u00b5s`);
+    if (step.details) {
+      console.log(`          ${step.details}`);
+    }
+    console.log('');
+  }
+
+  console.log('Query statistics:');
+  console.log(`  Nodes visited:    ${result.stats.nodesVisited}`);
+  console.log(`  Edges traversed:  ${result.stats.edgesTraversed}`);
+  console.log(`  Rule evaluations: ${result.stats.ruleEvaluations}`);
+  console.log(`  Total results:    ${result.stats.totalResults}`);
+  console.log(`  Total duration:   ${result.profile.totalDurationUs} \u00b5s`);
+  if (result.profile.ruleEvalTimeUs === 0 && result.profile.projectionTimeUs === 0) {
+    console.log('  (rule_eval_time and projection_time: not yet tracked)');
+  }
+  console.log('');
+
+  const bindingsToShow = result.bindings.slice(0, limit);
+  if (bindingsToShow.length === 0) {
+    console.log('No results.');
+  } else {
+    console.log(`Results (${bindingsToShow.length}${result.bindings.length > limit ? ` of ${result.bindings.length}` : ''}):`);
+    console.log('');
+    for (const row of bindingsToShow) {
+      const pairs = Object.entries(row).map(([k, v]) => `${k}=${v}`).join(', ');
+      console.log(`  { ${pairs} }`);
+    }
   }
 }

package/src/commands/schema.ts

@@ -21,7 +21,7 @@ import {
   type GraphSchema,
   type NodeTypeSchema,
   type EdgeTypeSchema,
-} from '@grafema/core';
+} from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 interface ExportOptions {
@@ -262,7 +262,7 @@ const exportSubcommand = new Command('export')
       exitWithError('No graph database found', ['Run: grafema analyze']);
     }
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     try {

package/src/commands/server.ts

@@ -10,10 +10,9 @@
 
 import { Command } from 'commander';
 import { resolve, join } from 'path';
-import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
-import { spawn } from 'child_process';
+import { existsSync, unlinkSync, readFileSync } from 'fs';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary, startRfdbServer } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 // Extend config type for server settings
@@ -41,7 +40,7 @@ async function isServerRunning(socketPath: string): Promise<{ running: boolean;
     return { running: false };
   }
 
-  const client = new RFDBClient(socketPath);
+  const client = new RFDBClient(socketPath, 'cli');
   // Suppress error events (we handle via try/catch)
   client.on('error', () => {});
 
@@ -67,6 +66,55 @@ function getProjectPaths(projectPath: string) {
   return { grafemaDir, socketPath, dbPath, pidPath };
 }
 
+/**
+ * Resolve RFDB binary path: CLI flag > config > auto-detect
+ */
+function resolveBinaryPath(projectPath: string, explicitBinary?: string): string | null {
+  if (explicitBinary) {
+    return findServerBinary(explicitBinary);
+  }
+
+  // Try config
+  try {
+    const config = loadConfig(projectPath);
+    const serverConfig = (config as unknown as { server?: ServerConfig }).server;
+    if (serverConfig?.binaryPath) {
+      return findServerBinary(serverConfig.binaryPath);
+    }
+  } catch {
+    // Config not found or invalid - continue with auto-detect
+  }
+
+  return findServerBinary();
+}
+
+/**
+ * Stop a running RFDB server: send shutdown, wait for socket removal, clean PID
+ */
+async function stopRunningServer(socketPath: string, pidPath: string): Promise<void> {
+  const client = new RFDBClient(socketPath, 'cli');
+  client.on('error', () => {});
+
+  try {
+    await client.connect();
+    await client.shutdown();
+  } catch {
+    // Expected - server closes connection
+  }
+
+  // Wait for socket to disappear
+  let attempts = 0;
+  while (existsSync(socketPath) && attempts < 30) {
+    await sleep(100);
+    attempts++;
+  }
+
+  // Clean up PID file
+  if (existsSync(pidPath)) {
+    unlinkSync(pidPath);
+  }
+}
+
 // Create main server command with subcommands
 export const serverCommand = new Command('server')
   .description('Manage RFDB (Rega Flow Database) server lifecycle')
@@ -111,34 +159,7 @@ serverCommand
       return;
     }
 
-    // Remove stale socket if exists
-    if (existsSync(socketPath)) {
-      unlinkSync(socketPath);
-    }
-
-    // Determine binary path: CLI flag > config > auto-detect
-    let binaryPath: string | null = null;
-
-    if (options.binary) {
-      // Explicit --binary flag
-      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) {
-          binaryPath = findServerBinary(serverConfig.binaryPath);
-        }
-      } catch {
-        // Config not found or invalid - continue with auto-detect
-      }
-
-      // Auto-detect if not specified
-      if (!binaryPath) {
-        binaryPath = findServerBinary();
-      }
-    }
+    const binaryPath = resolveBinaryPath(projectPath, options.binary);
 
     if (!binaryPath) {
       exitWithError('RFDB server binary not found', [
@@ -156,33 +177,19 @@ serverCommand
     console.log(`  Database: ${dbPath}`);
     console.log(`  Socket: ${socketPath}`);
 
-    // Start server
-    const serverProcess = spawn(binaryPath, [dbPath, '--socket', socketPath], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      detached: true,
+    // Start server using shared utility
+    const serverProcess = await startRfdbServer({
+      dbPath,
+      socketPath,
+      binaryPath,
+      pidPath,
+      waitTimeoutMs: 10000,
     });
 
-    // Don't let server process prevent parent from exiting
-    serverProcess.unref();
-
-    // Write PID file
-    if (serverProcess.pid) {
-      writeFileSync(pidPath, String(serverProcess.pid));
-    }
-
-    // Wait for socket to appear (increased timeout for slow systems)
-    let attempts = 0;
-    while (!existsSync(socketPath) && attempts < 100) {
-      await sleep(100);
-      attempts++;
-    }
-
-    if (!existsSync(socketPath)) {
-      exitWithError('Server failed to start', [
-        'Check if database path is valid',
-        'Check server logs for errors',
-        `Binary used: ${binaryPath}`
-      ]);
+    if (serverProcess === null) {
+      // Existing server detected via PID file
+      console.log('Server already running (detected via PID file)');
+      return;
     }
 
     // Verify server is responsive
@@ -227,31 +234,7 @@ serverCommand
     }
 
     console.log('Stopping RFDB server...');
-
-    // Send shutdown command
-    const client = new RFDBClient(socketPath);
-    // Suppress error events (server closes connection on shutdown)
-    client.on('error', () => {});
-
-    try {
-      await client.connect();
-      await client.shutdown();
-    } catch {
-      // Expected - server closes connection
-    }
-
-    // Wait for socket to disappear
-    let attempts = 0;
-    while (existsSync(socketPath) && attempts < 30) {
-      await sleep(100);
-      attempts++;
-    }
-
-    // Clean up PID file
-    if (existsSync(pidPath)) {
-      unlinkSync(pidPath);
-    }
-
+    await stopRunningServer(socketPath, pidPath);
     console.log('Server stopped');
   });
 
@@ -285,7 +268,7 @@ serverCommand
     let nodeCount: number | undefined;
     let edgeCount: number | undefined;
     if (status.running) {
-      const client = new RFDBClient(socketPath);
+      const client = new RFDBClient(socketPath, 'cli');
       client.on('error', () => {}); // Suppress error events
 
       try {
@@ -341,6 +324,75 @@ serverCommand
     }
   });
 
+// grafema server restart
+serverCommand
+  .command('restart')
+  .description('Restart the RFDB server (stop if running, then start)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-b, --binary <path>', 'Path to rfdb-server binary')
+  .action(async (options: { project: string; binary?: string }) => {
+    const projectPath = resolve(options.project);
+    const { grafemaDir, socketPath, dbPath, pidPath } = getProjectPaths(projectPath);
+
+    // Check if grafema is initialized
+    if (!existsSync(grafemaDir)) {
+      exitWithError('Grafema not initialized', [
+        'Run: grafema init',
+        'Or: grafema analyze (initializes automatically)'
+      ]);
+    }
+
+    // Stop server if running
+    const status = await isServerRunning(socketPath);
+    if (status.running) {
+      console.log('Stopping RFDB server...');
+      await stopRunningServer(socketPath, pidPath);
+      console.log('Server stopped');
+    }
+
+    const binaryPath = resolveBinaryPath(projectPath, options.binary);
+
+    if (!binaryPath) {
+      exitWithError('RFDB server binary not found', [
+        'Specify path: grafema server restart --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...');
+    console.log(`  Binary: ${binaryPath}`);
+    console.log(`  Database: ${dbPath}`);
+    console.log(`  Socket: ${socketPath}`);
+
+    const serverProcess = await startRfdbServer({
+      dbPath,
+      socketPath,
+      binaryPath,
+      pidPath,
+      waitTimeoutMs: 10000,
+    });
+
+    const verifyStatus = await isServerRunning(socketPath);
+    if (!verifyStatus.running) {
+      exitWithError('Server started but not responding', [
+        'Check server logs for errors'
+      ]);
+    }
+
+    console.log('');
+    console.log(`Server restarted successfully`);
+    if (verifyStatus.version) {
+      console.log(`  Version: ${verifyStatus.version}`);
+    }
+    if (serverProcess?.pid) {
+      console.log(`  PID: ${serverProcess.pid}`);
+    }
+  });
+
 // grafema server graphql
 serverCommand
   .command('graphql')
@@ -362,7 +414,7 @@ serverCommand
     }
 
     // Create backend connection
-    const backend = new RFDBServerBackend({ socketPath });
+    const backend = new RFDBServerBackend({ socketPath, clientName: 'cli' });
     await backend.connect();
 
     // Import and start GraphQL server

package/src/commands/stats.ts

@@ -5,7 +5,7 @@
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend } from '@grafema/core';
+import { RFDBServerBackend } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 export const statsCommand = new Command('stats')
@@ -29,7 +29,7 @@ Examples:
       exitWithError('No graph database found', ['Run: grafema analyze']);
     }
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     try {