@grafema/cli 0.2.4-beta → 0.2.6-beta

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

@@ -7,10 +7,9 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, dirname } from 'path';
-import { relative } from 'path';
+import { isAbsolute, resolve, join, dirname, 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';
 
@@ -313,7 +312,7 @@ async function findCallsToNode(
  */
 function getModulePath(file: string, projectPath: string): string {
   if (!file) return '<unknown>';
-  const relPath = relative(projectPath, file);
+  const relPath = isAbsolute(file) ? relative(projectPath, file) : file;
   const dir = dirname(relPath);
   return dir === '.' ? relPath : `${dir}/*`;
 }

package/src/commands/init.ts

@@ -8,9 +8,9 @@ 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';
+import { DEFAULT_CONFIG, GRAFEMA_VERSION, getSchemaVersion } from '@grafema/core';
+import { installSkill } from './setup-skill.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
@@ -21,6 +21,7 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url));
 function generateConfigYAML(): string {
   // Start with working default config
   const config = {
+    version: getSchemaVersion(GRAFEMA_VERSION),
     // Plugin list (fully implemented)
     plugins: DEFAULT_CONFIG.plugins,
   };
@@ -75,7 +76,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 +95,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.');
 }
 
 /**
@@ -180,6 +186,16 @@ Examples:
       }
     }
 
+    // Auto-install Agent Skill for AI-assisted development
+    try {
+      const installed = installSkill(projectPath);
+      if (installed) {
+        console.log('✓ Installed Agent Skill (.claude/skills/grafema-codebase-analysis/)');
+      }
+    } catch {
+      // Non-critical — don't fail init if skill install fails
+    }
+
     printNextSteps();
 
     // Prompt to run analyze in interactive mode

package/src/commands/ls.ts

@@ -11,10 +11,12 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative } from 'path';
+import { resolve, join } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 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 +68,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 +78,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 +109,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 +133,7 @@ Discover available types:
         }
       }
     } finally {
+      spinner.stop();
       await backend.close();
     }
   });
@@ -134,7 +143,7 @@ Discover available types:
  * Different types show different fields.
  */
 function formatNodeForList(node: NodeInfo, nodeType: string, projectPath: string): string {
-  const relFile = node.file ? relative(projectPath, node.file) : '';
+  const relFile = node.file ? toRelativeDisplay(node.file, projectPath) : '';
   const loc = node.line ? `${relFile}:${node.line}` : relFile;
 
   // HTTP routes: METHOD PATH (location)

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

@@ -10,11 +10,22 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative, basename } from 'path';
+import { resolve, join, basename } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, 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';
+
+// Node type constants to avoid magic string duplication
+const HTTP_ROUTE_TYPE = 'http:route';
+const HTTP_REQUEST_TYPE = 'http:request';
+const SOCKETIO_EVENT_TYPE = 'socketio:event';
+const SOCKETIO_EMIT_TYPE = 'socketio:emit';
+const SOCKETIO_ON_TYPE = 'socketio:on';
+const GRAFEMA_PLUGIN_TYPE = 'grafema:plugin';
+const PROPERTY_ACCESS_TYPE = 'PROPERTY_ACCESS';
 
 interface QueryOptions {
   project: string;
@@ -75,6 +86,9 @@ export const queryCommand = new Command('query')
     '--raw',
     `Execute raw Datalog query
 
+Supports both direct queries and Datalog rules.
+Rules (containing ":-") define a violation predicate and return matching nodes.
+
 Predicates:
   type(Id, Type)        Find nodes by type or get type of node
   node(Id, Type)        Alias for type
@@ -83,10 +97,14 @@ Predicates:
   path(Src, Dst)        Check reachability between nodes
   incoming(Dst, Src, T) Find incoming edges
 
-Examples:
+Direct queries:
   grafema query --raw 'type(X, "FUNCTION")'
   grafema query --raw 'type(X, "FUNCTION"), attr(X, "name", "main")'
-  grafema query --raw 'edge(X, Y, "CALLS")'`
+  grafema query --raw 'edge(X, Y, "CALLS")'
+
+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(
     '-t, --type <nodeType>',
@@ -130,15 +148,23 @@ Examples:
     const backend = new RFDBServerBackend({ dbPath });
     await backend.connect();
 
+    const spinner = new Spinner('Querying graph...');
+    spinner.start();
+
     try {
+      const limit = parseInt(options.limit, 10);
+      if (isNaN(limit) || limit < 1) {
+        spinner.stop();
+        exitWithError('Invalid limit', ['Use a positive number, e.g.: --limit 10']);
+      }
+
       // Raw Datalog mode
       if (options.raw) {
-        await executeRawQuery(backend, pattern, options);
+        spinner.stop();
+        await executeRawQuery(backend, pattern, limit, options.json);
         return;
       }
 
-      const limit = parseInt(options.limit, 10);
-
       // Parse query with scope support
       let query: ParsedQuery;
 
@@ -159,6 +185,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 +246,7 @@ Examples:
       }
 
     } finally {
+      spinner.stop();
       await backend.close();
     }
   });
@@ -237,23 +266,31 @@ function parsePattern(pattern: string): { type: string | null; name: string } {
       fn: 'FUNCTION',
       func: 'FUNCTION',
       class: 'CLASS',
+      interface: 'INTERFACE',
+      type: 'TYPE',
+      enum: 'ENUM',
       module: 'MODULE',
       variable: 'VARIABLE',
       var: 'VARIABLE',
       const: 'CONSTANT',
       constant: 'CONSTANT',
       // HTTP route aliases
-      route: 'http:route',
-      endpoint: 'http:route',
+      route: HTTP_ROUTE_TYPE,
+      endpoint: HTTP_ROUTE_TYPE,
       // HTTP request aliases
-      request: 'http:request',
-      fetch: 'http:request',
-      api: 'http:request',
+      request: HTTP_REQUEST_TYPE,
+      fetch: HTTP_REQUEST_TYPE,
+      api: HTTP_REQUEST_TYPE,
       // Socket.IO aliases
-      event: 'socketio:event',
-      emit: 'socketio:emit',
-      on: 'socketio:on',
-      listener: 'socketio:on',
+      event: SOCKETIO_EVENT_TYPE,
+      emit: SOCKETIO_EMIT_TYPE,
+      on: SOCKETIO_ON_TYPE,
+      listener: SOCKETIO_ON_TYPE,
+      // Grafema internal
+      plugin: GRAFEMA_PLUGIN_TYPE,
+      // Property access aliases (REG-395)
+      property: PROPERTY_ACCESS_TYPE,
+      prop: PROPERTY_ACCESS_TYPE,
     };
 
     if (typeMap[typeWord]) {
@@ -357,6 +394,36 @@ export function isFileScope(scope: string): boolean {
  * @returns true if ID matches all constraints
  */
 export function matchesScope(semanticId: string, file: string | null, scopes: string[]): boolean {
+  // No constraints = everything matches (regardless of ID format)
+  if (file === null && scopes.length === 0) return true;
+
+  // Try v2 parsing first
+  const parsedV2 = parseSemanticIdV2(semanticId);
+  if (parsedV2) {
+    // File scope check (v2)
+    if (file !== null) {
+      if (parsedV2.file === file) {
+        // Exact match - OK
+      } else if (parsedV2.file.endsWith('/' + file)) {
+        // Partial path match - OK
+      } else if (basename(parsedV2.file) === file) {
+        // Basename exact match - OK
+      } else {
+        return false;
+      }
+    }
+
+    // Function/class scope check (v2): check namedParent
+    for (const scope of scopes) {
+      if (!parsedV2.namedParent || parsedV2.namedParent.toLowerCase() !== scope.toLowerCase()) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  // Fallback to v1 parsing
   const parsed = parseSemanticId(semanticId);
   if (!parsed) return false;
 
@@ -411,6 +478,17 @@ export function matchesScope(semanticId: string, file: string | null, scopes: st
  * @returns Human-readable scope context or null
  */
 export function extractScopeContext(semanticId: string): string | null {
+  // Try v2 parsing first
+  const parsedV2 = parseSemanticIdV2(semanticId);
+  if (parsedV2) {
+    if (parsedV2.namedParent) {
+      return `inside ${parsedV2.namedParent}`;
+    }
+    // v2 with no parent = top-level
+    return null;
+  }
+
+  // Fallback to v1 parsing
   const parsed = parseSemanticId(semanticId);
   if (!parsed) return null;
 
@@ -462,7 +540,7 @@ function matchesSearchPattern(
   const lowerPattern = pattern.toLowerCase();
 
   // HTTP routes: search method and path
-  if (nodeType === 'http:route') {
+  if (nodeType === HTTP_ROUTE_TYPE) {
     const method = (node.method || '').toLowerCase();
     const path = (node.path || '').toLowerCase();
 
@@ -488,7 +566,7 @@ function matchesSearchPattern(
   }
 
   // HTTP requests: search method and url
-  if (nodeType === 'http:request') {
+  if (nodeType === HTTP_REQUEST_TYPE) {
     const method = (node.method || '').toLowerCase();
     const url = (node.url || '').toLowerCase();
 
@@ -514,13 +592,13 @@ function matchesSearchPattern(
   }
 
   // Socket.IO event channels: search name field (standard)
-  if (nodeType === 'socketio:event') {
+  if (nodeType === SOCKETIO_EVENT_TYPE) {
     const nodeName = (node.name || '').toLowerCase();
     return nodeName.includes(lowerPattern);
   }
 
   // Socket.IO emit/on: search event field
-  if (nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+  if (nodeType === SOCKETIO_EMIT_TYPE || nodeType === SOCKETIO_ON_TYPE) {
     const eventName = (node.event || '').toLowerCase();
     return eventName.includes(lowerPattern);
   }
@@ -544,18 +622,22 @@ async function findNodes(
     : [
         'FUNCTION',
         'CLASS',
+        'INTERFACE',
+        'TYPE',
+        'ENUM',
         'MODULE',
         'VARIABLE',
         'CONSTANT',
-        'http:route',
-        'http:request',
-        'socketio:event',
-        'socketio:emit',
-        'socketio:on'
+        HTTP_ROUTE_TYPE,
+        HTTP_REQUEST_TYPE,
+        SOCKETIO_EVENT_TYPE,
+        SOCKETIO_EMIT_TYPE,
+        SOCKETIO_ON_TYPE,
+        PROPERTY_ACCESS_TYPE,
       ];
 
   for (const nodeType of searchTypes) {
-    for await (const node of backend.queryNodes({ nodeType: nodeType as any })) {
+    for await (const node of backend.queryNodes({ nodeType })) {
       // Type-aware field matching (name)
       const nameMatches = matchesSearchPattern(node, nodeType, query.name);
       if (!nameMatches) continue;
@@ -576,24 +658,24 @@ async function findNodes(
       nodeInfo.scopeContext = extractScopeContext(node.id);
 
       // Include method and path for http:route nodes
-      if (nodeType === 'http:route') {
+      if (nodeType === HTTP_ROUTE_TYPE) {
         nodeInfo.method = node.method as string | undefined;
         nodeInfo.path = node.path as string | undefined;
       }
 
       // Include method and url for http:request nodes
-      if (nodeType === 'http:request') {
+      if (nodeType === HTTP_REQUEST_TYPE) {
         nodeInfo.method = node.method as string | undefined;
         nodeInfo.url = node.url as string | undefined;
       }
 
       // Include event field for Socket.IO nodes
-      if (nodeType === 'socketio:event' || nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+      if (nodeType === SOCKETIO_EVENT_TYPE || nodeType === SOCKETIO_EMIT_TYPE || nodeType === SOCKETIO_ON_TYPE) {
         nodeInfo.event = node.event as string | undefined;
       }
 
       // Include emit-specific fields
-      if (nodeType === 'socketio:emit') {
+      if (nodeType === SOCKETIO_EMIT_TYPE) {
         nodeInfo.room = node.room as string | undefined;
         nodeInfo.namespace = node.namespace as string | undefined;
         nodeInfo.broadcast = node.broadcast as boolean | undefined;
@@ -601,11 +683,26 @@ async function findNodes(
       }
 
       // Include listener-specific fields
-      if (nodeType === 'socketio:on') {
+      if (nodeType === SOCKETIO_ON_TYPE) {
         nodeInfo.objectName = node.objectName as string | undefined;
         nodeInfo.handlerName = node.handlerName as string | undefined;
       }
 
+      // Include plugin-specific fields
+      if (nodeType === GRAFEMA_PLUGIN_TYPE) {
+        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_TYPE) {
+        nodeInfo.objectName = node.objectName as string | undefined;
+      }
+
       results.push(nodeInfo);
       if (results.length >= limit) break;
     }
@@ -712,29 +809,35 @@ async function getCallees(
  */
 async function displayNode(node: NodeInfo, projectPath: string, backend: RFDBServerBackend): Promise<void> {
   // Special formatting for HTTP routes
-  if (node.type === 'http:route' && node.method && node.path) {
+  if (node.type === HTTP_ROUTE_TYPE && node.method && node.path) {
     console.log(formatHttpRouteDisplay(node, projectPath));
     return;
   }
 
   // Special formatting for HTTP requests
-  if (node.type === 'http:request') {
+  if (node.type === HTTP_REQUEST_TYPE) {
     console.log(formatHttpRequestDisplay(node, projectPath));
     return;
   }
 
   // Special formatting for Socket.IO event channels
-  if (node.type === 'socketio:event') {
+  if (node.type === SOCKETIO_EVENT_TYPE) {
     console.log(await formatSocketEventDisplay(node, projectPath, backend));
     return;
   }
 
   // Special formatting for Socket.IO emit/on
-  if (node.type === 'socketio:emit' || node.type === 'socketio:on') {
+  if (node.type === SOCKETIO_EMIT_TYPE || node.type === SOCKETIO_ON_TYPE) {
     console.log(formatSocketIONodeDisplay(node, projectPath));
     return;
   }
 
+  // Special formatting for Grafema plugin nodes
+  if (node.type === GRAFEMA_PLUGIN_TYPE) {
+    console.log(formatPluginDisplay(node, projectPath));
+    return;
+  }
+
   console.log(formatNodeDisplay(node, { projectPath }));
 
   // Add scope context if present
@@ -758,7 +861,7 @@ function formatHttpRouteDisplay(node: NodeInfo, projectPath: string): string {
 
   // Line 2: Location
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     const loc = node.line ? `${relPath}:${node.line}` : relPath;
     lines.push(`  Location: ${loc}`);
   }
@@ -783,7 +886,7 @@ function formatHttpRequestDisplay(node: NodeInfo, projectPath: string): string {
 
   // Line 2: Location
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     const loc = node.line ? `${relPath}:${node.line}` : relPath;
     lines.push(`  Location: ${loc}`);
   }
@@ -870,7 +973,7 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
   }
 
   // Emit-specific fields
-  if (node.type === 'socketio:emit') {
+  if (node.type === SOCKETIO_EMIT_TYPE) {
     if (node.room) {
       lines.push(`  Room: ${node.room}`);
     }
@@ -883,7 +986,7 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
   }
 
   // Listener-specific fields
-  if (node.type === 'socketio:on' && node.handlerName) {
+  if (node.type === SOCKETIO_ON_TYPE && node.handlerName) {
     lines.push(`  Handler: ${node.handlerName}`);
   }
 
@@ -891,18 +994,96 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
 }
 
 /**
- * Execute raw Datalog query (backwards compat)
+ * 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 = toRelativeDisplay(node.file, projectPath);
+    lines.push(`  Source: ${relPath}`);
+  }
+
+  return lines.join('\n');
+}
+
+/** Built-in Datalog predicates supported by RFDB server */
+export const BUILTIN_PREDICATES = new Set([
+  'node', 'type', 'edge', 'incoming', 'path',
+  'attr', 'attr_edge',
+  'neq', 'starts_with', 'not_starts_with',
+]);
+
+/** Extract predicate names from a Datalog query string */
+export function extractPredicates(query: string): string[] {
+  const regex = /\b([a-z_][a-z0-9_]*)\s*\(/g;
+  const predicates = new Set<string>();
+  let match;
+  while ((match = regex.exec(query)) !== null) {
+    predicates.add(match[1]);
+  }
+  return [...predicates];
+}
+
+/** Extract predicate names defined as rule heads (word(...) :-) */
+export function extractRuleHeads(query: string): Set<string> {
+  const regex = /\b([a-z_][a-z0-9_]*)\s*\([^)]*\)\s*:-/g;
+  const heads = new Set<string>();
+  let match;
+  while ((match = regex.exec(query)) !== null) {
+    heads.add(match[1]);
+  }
+  return heads;
+}
+
+/** Find predicates in a query that are not built-in and not user-defined rule heads */
+export function getUnknownPredicates(query: string): string[] {
+  const predicates = extractPredicates(query);
+  const ruleHeads = extractRuleHeads(query);
+  return predicates.filter(p => !BUILTIN_PREDICATES.has(p) && !ruleHeads.has(p));
+}
+
+/**
+ * Execute raw Datalog query.
+ * Uses unified executeDatalog endpoint which auto-detects rules vs direct queries.
  */
 async function executeRawQuery(
   backend: RFDBServerBackend,
   query: string,
-  options: QueryOptions
+  limit: number,
+  json?: boolean
 ): Promise<void> {
-  const results = await backend.datalogQuery(query);
-  const limit = parseInt(options.limit, 10);
+  const results = await backend.executeDatalog(query);
   const limited = results.slice(0, limit);
 
-  if (options.json) {
+  if (json) {
     console.log(JSON.stringify(limited, null, 2));
   } else {
     if (limited.length === 0) {
@@ -916,4 +1097,14 @@ async function executeRawQuery(
       }
     }
   }
+
+  // Show warning for unknown predicates (on stderr, works in both text and JSON mode)
+  if (limited.length === 0) {
+    const unknown = getUnknownPredicates(query);
+    if (unknown.length > 0) {
+      const unknownList = unknown.map(p => `'${p}'`).join(', ');
+      const builtinList = [...BUILTIN_PREDICATES].join(', ');
+      console.error(`Note: unknown predicate ${unknownList}. Built-in predicates: ${builtinList}`);
+    }
+  }
 }