@grafema/cli 0.2.12-beta → 0.3.1-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

@@ -12,7 +12,7 @@ import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync, unlinkSync, readFileSync } from 'fs';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary, startRfdbServer } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary, startRfdbServer } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 // Extend config type for server settings
@@ -40,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', () => {});
 
@@ -92,7 +92,7 @@ function resolveBinaryPath(projectPath: string, explicitBinary?: string): string
  * 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);
+  const client = new RFDBClient(socketPath, 'cli');
   client.on('error', () => {});
 
   try {
@@ -186,6 +186,12 @@ serverCommand
       waitTimeoutMs: 10000,
     });
 
+    if (serverProcess === null) {
+      // Existing server detected via PID file
+      console.log('Server already running (detected via PID file)');
+      return;
+    }
+
     // Verify server is responsive
     const verifyStatus = await isServerRunning(socketPath);
     if (!verifyStatus.running) {
@@ -262,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 {
@@ -382,7 +388,7 @@ serverCommand
     if (verifyStatus.version) {
       console.log(`  Version: ${verifyStatus.version}`);
     }
-    if (serverProcess.pid) {
+    if (serverProcess?.pid) {
       console.log(`  PID: ${serverProcess.pid}`);
     }
   });
@@ -408,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 {

package/src/commands/tldr.ts

@@ -0,0 +1,103 @@
+/**
+ * tldr command — "What's in this file?"
+ *
+ * Human-first alias for `describe`. Shows notation DSL for a file.
+ *
+ * Usage:
+ *   grafema tldr src/auth.ts          # File overview in DSL
+ *   grafema tldr src/auth.ts --save   # Save as src/auth.ts.tldr
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import {
+  RFDBServerBackend,
+  renderNotation,
+  extractSubgraph,
+} from '@grafema/util';
+import type { DescribeOptions } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface TldrCommandOptions {
+  project: string;
+  save?: boolean;
+  ext: string;
+}
+
+export const tldrCommand = new Command('tldr')
+  .description("What's in this file? — compact DSL overview")
+  .argument('<file>', 'File path to describe')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-s, --save', 'Save output to <file>.<ext>')
+  .option('--ext <ext>', 'File extension for --save', '.tldr')
+  .addHelpText('after', `
+Examples:
+  grafema tldr src/auth.ts          File overview in DSL notation
+  grafema tldr src/auth.ts --save   Save as src/auth.ts.tldr
+  grafema tldr src/app.ts --save --ext .md   Save as src/app.ts.md
+`)
+  .action(async (file: string, options: TldrCommandOptions) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+
+    if (!existsSync(dbPath)) {
+      exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
+    await backend.connect();
+
+    const spinner = new Spinner('Loading file overview...');
+    spinner.start();
+
+    try {
+      // Find MODULE node for the file
+      let node = null;
+      for await (const n of backend.queryNodes({ file, type: 'MODULE' })) {
+        node = n;
+        break;
+      }
+
+      if (!node) {
+        spinner.stop();
+        exitWithError(`File not found in graph: "${file}"`, [
+          'Check that the file was included in analysis',
+          'Run: grafema analyze',
+        ]);
+        return;
+      }
+
+      // Extract subgraph at depth 2 (nested + fold)
+      const subgraph = await extractSubgraph(backend, node.id, 2);
+
+      // Render notation
+      const describeOptions: DescribeOptions = {
+        depth: 2,
+        includeLocations: true,
+      };
+      const notation = renderNotation(subgraph, describeOptions);
+
+      spinner.stop();
+
+      const output = notation.trim()
+        ? notation
+        : `[${node.type}] ${node.name ?? node.id}\nNo relationships found.`;
+
+      console.log(output);
+
+      // Save to file if --save flag
+      if (options.save) {
+        const ext = options.ext.startsWith('.') ? options.ext : `.${options.ext}`;
+        const outputPath = `${file}${ext}`;
+        writeFileSync(outputPath, output + '\n', 'utf-8');
+        console.log('');
+        console.log(`Saved to ${outputPath}`);
+      }
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });