@grafema/cli 0.2.11 → 0.3.0-beta

package/src/commands/describe.ts

@@ -0,0 +1,160 @@
+/**
+ * Describe command — Render compact DSL notation for a graph node
+ *
+ * Resolves target by: semantic ID → file path (MODULE) → node name.
+ * Calls extractSubgraph() + renderNotation() from @grafema/util.
+ *
+ * Output is DSL notation using archetype-grouped operators:
+ *   o- dependency, > call/flow, < read/input, => write,
+ *   >x exception, ~>> event, ?| guard, |= governance
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import {
+  RFDBServerBackend,
+  renderNotation,
+  extractSubgraph,
+  PERSPECTIVES,
+} from '@grafema/util';
+import type { DescribeOptions } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { Spinner } from '../utils/spinner.js';
+
+interface DescribeCommandOptions {
+  project: string;
+  depth: string;
+  perspective?: string;
+  budget?: string;
+  json?: boolean;
+  locations?: boolean;
+}
+
+export const describeCommand = new Command('describe')
+  .description('Render compact DSL notation for a graph node')
+  .argument('<target>', 'Semantic ID, file path, or node name')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-d, --depth <level>', 'LOD: 0=names, 1=edges, 2=nested+fold, 3=nested (exact)', '1')
+  .option(
+    '--perspective <name>',
+    `Perspective preset: ${Object.keys(PERSPECTIVES).join(', ')}`,
+  )
+  .option('-b, --budget <n>', 'Max items before summarization (default 7)')
+  .option('-j, --json', 'Output as JSON for scripting')
+  .option('-l, --locations', 'Include file:line locations')
+  .addHelpText('after', `
+Perspectives:
+  security   writes + exceptions
+  data       flow out/in + writes
+  errors     exceptions only
+  api        flow out + publishes + depends
+  events     publishes only
+
+LOD levels:
+  0  Node names only (minimal)
+  1  Node + edges (default)
+  2  Node + edges + nested children (folded)
+  3  Node + edges + nested children (exact, no folding)
+
+Examples:
+  grafema describe "src/app.ts->FUNCTION->main"
+  grafema describe src/app.ts
+  grafema describe handleRequest
+  grafema describe handleRequest --perspective security
+  grafema describe MyClass -d 2 --locations
+  grafema describe handleRequest --json
+`)
+  .action(async (target: string, options: DescribeCommandOptions) => {
+    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 depth = parseInt(options.depth, 10);
+    if (isNaN(depth) || depth < 0 || depth > 3) {
+      exitWithError('Invalid depth', ['Use 0, 1, 2, or 3']);
+    }
+
+    if (options.perspective && !PERSPECTIVES[options.perspective]) {
+      exitWithError(`Unknown perspective: "${options.perspective}"`, [
+        `Available: ${Object.keys(PERSPECTIVES).join(', ')}`,
+      ]);
+    }
+
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
+    await backend.connect();
+
+    const spinner = new Spinner('Resolving target...');
+    spinner.start();
+
+    try {
+      // Step 1: Resolve target → node
+      let node = await backend.getNode(target);
+
+      if (!node) {
+        for await (const n of backend.queryNodes({ file: target, type: 'MODULE' })) {
+          node = n;
+          break;
+        }
+      }
+      if (!node) {
+        for await (const n of backend.queryNodes({ name: target })) {
+          node = n;
+          break;
+        }
+      }
+
+      if (!node) {
+        spinner.stop();
+        exitWithError(`Target not found: "${target}"`, [
+          'Use: grafema query "<name>" to find available nodes',
+          'Try: semantic ID, file path, or node name',
+        ]);
+        return;
+      }
+
+      // Step 2: Extract subgraph
+      const subgraph = await extractSubgraph(backend, node.id, depth);
+
+      // Step 3: Build options
+      const describeOptions: DescribeOptions = {
+        depth,
+        includeLocations: options.locations ?? depth >= 2,
+      };
+      if (options.perspective && PERSPECTIVES[options.perspective]) {
+        describeOptions.archetypeFilter = PERSPECTIVES[options.perspective];
+      }
+      if (options.budget) {
+        describeOptions.budget = parseInt(options.budget, 10);
+      }
+
+      // Step 4: Render
+      const notation = renderNotation(subgraph, describeOptions);
+
+      spinner.stop();
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          target: node.id,
+          dsl: notation || `[${node.type}] ${node.name ?? node.id}\nNo relationships found at depth=${depth}.`,
+          subgraph: {
+            rootNodes: subgraph.rootNodes.length,
+            edges: subgraph.edges.length,
+            nodes: subgraph.nodeMap.size,
+          },
+        }, null, 2));
+      } else if (notation.trim()) {
+        console.log(notation);
+      } else {
+        console.log(`[${node.type}] ${node.name ?? node.id}`);
+        console.log(`No relationships found at depth=${depth}.`);
+      }
+    } finally {
+      spinner.stop();
+      await backend.close();
+    }
+  });

package/src/commands/doctor/checks.ts

@@ -2,14 +2,14 @@
  * Diagnostic check functions for `grafema doctor` command - REG-214
  *
  * Checks are organized in levels:
- * - Level 1: Prerequisites (fail-fast) - checkGrafemaInitialized, checkServerStatus
+ * - Level 1: Prerequisites (fail-fast) - checkBinaries, checkGrafemaInitialized, checkServerStatus
  * - Level 2: Configuration - checkConfigValidity, checkEntrypoints
  * - Level 3: Graph Health - checkDatabaseExists, checkGraphStats, checkConnectivity, checkFreshness
  * - Level 4: Informational - checkVersions
  */
 
 import { existsSync, readFileSync, statSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, delimiter } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import {
@@ -17,7 +17,7 @@ import {
   RFDBClient,
   loadConfig,
   GraphFreshnessChecker,
-} from '@grafema/core';
+} from '@grafema/util';
 import type { DoctorCheckResult } from './types.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -38,13 +38,156 @@ const VALID_PLUGIN_NAMES = new Set([
   'RustFFIEnricher',
   // Validation
   'CallResolverValidator', 'EvalBanValidator', 'SQLInjectionValidator', 'ShadowingDetector',
-  'GraphConnectivityValidator', 'DataFlowValidator', 'TypeScriptDeadCodeValidator',
+  'GraphConnectivityValidator', 'DataFlowValidator',
 ]);
 
 // =============================================================================
 // Level 1: Prerequisites (fail-fast)
 // =============================================================================
 
+/**
+ * Binary lookup config — mirrors packages/grafema/src/binaries.ts but inlined
+ * to avoid cross-package dependency (CLI does not depend on the `grafema` pkg).
+ */
+type BinaryName = 'rfdb-server' | 'grafema-orchestrator';
+
+interface BinaryLookupResult {
+  name: BinaryName;
+  path: string | null;
+  source: string | null;
+}
+
+function findBinaryForDoctor(binaryName: BinaryName): BinaryLookupResult {
+  const envVars: Record<BinaryName, string> = {
+    'rfdb-server': 'GRAFEMA_RFDB_SERVER',
+    'grafema-orchestrator': 'GRAFEMA_ORCHESTRATOR',
+  };
+  const monorepoPackages: Record<BinaryName, string> = {
+    'rfdb-server': 'rfdb-server',
+    'grafema-orchestrator': 'grafema-orchestrator',
+  };
+
+  const envVar = envVars[binaryName];
+  const monorepoPkg = monorepoPackages[binaryName];
+
+  // 1. Environment variable
+  const envPath = process.env[envVar];
+  if (envPath && existsSync(envPath)) {
+    return { name: binaryName, path: envPath, source: `$${envVar}` };
+  }
+
+  // 2. Monorepo development builds (release, then debug)
+  // Walk up from this file to find monorepo root
+  let dir = __dirname;
+  let monorepoRoot: string | null = null;
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, 'packages', 'util')) && existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+      monorepoRoot = dir;
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (!monorepoRoot) {
+    const envRoot = process.env.GRAFEMA_ROOT;
+    if (envRoot && existsSync(join(envRoot, 'packages', 'util'))) {
+      monorepoRoot = envRoot;
+    }
+  }
+
+  if (monorepoRoot) {
+    for (const profile of ['release', 'debug'] as const) {
+      const p = join(monorepoRoot, 'packages', monorepoPkg, 'target', profile, binaryName);
+      if (existsSync(p)) {
+        return { name: binaryName, path: p, source: `monorepo (${profile})` };
+      }
+    }
+  }
+
+  // 3. System PATH
+  const pathDirs = (process.env.PATH || '').split(delimiter);
+  for (const pathDir of pathDirs) {
+    if (!pathDir) continue;
+    const p = join(pathDir, binaryName);
+    if (existsSync(p)) {
+      return { name: binaryName, path: p, source: 'PATH' };
+    }
+  }
+
+  // 4. ~/.local/bin
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home) {
+    const p = join(home, '.local', 'bin', binaryName);
+    if (existsSync(p)) {
+      return { name: binaryName, path: p, source: '~/.local/bin' };
+    }
+  }
+
+  return { name: binaryName, path: null, source: null };
+}
+
+/**
+ * Check if native binaries (rfdb-server, grafema-orchestrator) are findable.
+ * FAIL if both missing, WARN if one missing, PASS if both found.
+ */
+export async function checkBinaries(): Promise<DoctorCheckResult> {
+  const rfdb = findBinaryForDoctor('rfdb-server');
+  const orchestrator = findBinaryForDoctor('grafema-orchestrator');
+
+  const found: string[] = [];
+  const missing: string[] = [];
+
+  if (rfdb.path) {
+    found.push(`rfdb-server (${rfdb.source})`);
+  } else {
+    missing.push('rfdb-server');
+  }
+
+  if (orchestrator.path) {
+    found.push(`grafema-orchestrator (${orchestrator.source})`);
+  } else {
+    missing.push('grafema-orchestrator');
+  }
+
+  if (missing.length === 0) {
+    return {
+      name: 'binaries',
+      status: 'pass',
+      message: `Binaries: ${found.join(', ')}`,
+      details: {
+        rfdbServer: rfdb.path,
+        orchestrator: orchestrator.path,
+      },
+    };
+  }
+
+  if (missing.length === 2) {
+    return {
+      name: 'binaries',
+      status: 'fail',
+      message: 'Native binaries not found: rfdb-server, grafema-orchestrator',
+      recommendation:
+        'Install: npm install grafema, or build from source: cd packages/<name> && cargo build --release, or set GRAFEMA_RFDB_SERVER / GRAFEMA_ORCHESTRATOR env vars',
+    };
+  }
+
+  // One found, one missing
+  return {
+    name: 'binaries',
+    status: 'warn',
+    message: `Missing binary: ${missing[0]} (found: ${found[0]})`,
+    recommendation:
+      missing[0] === 'rfdb-server'
+        ? 'Set GRAFEMA_RFDB_SERVER env var or build: cd packages/rfdb-server && cargo build --release'
+        : 'Set GRAFEMA_ORCHESTRATOR env var or build: cd packages/grafema-orchestrator && cargo build --release',
+    details: {
+      rfdbServer: rfdb.path,
+      orchestrator: orchestrator.path,
+    },
+  };
+}
+
 /**
  * Check if .grafema directory exists with config file.
  * FAIL if not initialized.
@@ -103,7 +246,7 @@ export async function checkServerStatus(
     };
   }
 
-  const client = new RFDBClient(socketPath);
+  const client = new RFDBClient(socketPath, 'cli');
   client.on('error', () => {}); // Suppress error events
 
   try {
@@ -330,7 +473,7 @@ export async function checkGraphStats(
     };
   }
 
-  const backend = new RFDBServerBackend({ dbPath });
+  const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
   try {
     await backend.connect();
     const stats = await backend.getStats();
@@ -387,7 +530,7 @@ export async function checkConnectivity(
     };
   }
 
-  const backend = new RFDBServerBackend({ dbPath });
+  const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
   try {
     await backend.connect();
 
@@ -523,7 +666,7 @@ export async function checkFreshness(
     };
   }
 
-  const backend = new RFDBServerBackend({ dbPath });
+  const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
   try {
     await backend.connect();
     const freshnessChecker = new GraphFreshnessChecker();
@@ -584,7 +727,7 @@ export async function checkVersions(
   // Read core version
   try {
     const require = createRequire(import.meta.url);
-    const corePkgPath = require.resolve('@grafema/core/package.json');
+    const corePkgPath = require.resolve('@grafema/util/package.json');
     const corePkg = JSON.parse(readFileSync(corePkgPath, 'utf-8'));
     coreVersion = corePkg.version;
   } catch {
@@ -594,7 +737,7 @@ export async function checkVersions(
   // Get RFDB version from server if running
   const socketPath = join(projectPath, '.grafema', 'rfdb.sock');
   if (existsSync(socketPath)) {
-    const client = new RFDBClient(socketPath);
+    const client = new RFDBClient(socketPath, 'cli');
     client.on('error', () => {});
     try {
       await client.connect();

package/src/commands/doctor.ts

@@ -2,20 +2,22 @@
  * Doctor command - Diagnose Grafema setup issues
  *
  * Checks (in order):
- * 1. Initialization (.grafema directory, config file)
- * 2. Config validity (syntax, plugin names)
- * 3. Entrypoints (service paths exist)
- * 4. Server status (RFDB server running)
- * 5. Database exists and has data
- * 6. Graph statistics
- * 7. Graph connectivity
- * 8. Graph freshness
- * 9. Version information
+ * 1. Binaries (rfdb-server, grafema-orchestrator)
+ * 2. Initialization (.grafema directory, config file)
+ * 3. Config validity (syntax, plugin names)
+ * 4. Entrypoints (service paths exist)
+ * 5. Server status (RFDB server running)
+ * 6. Database exists and has data
+ * 7. Graph statistics
+ * 8. Graph connectivity
+ * 9. Graph freshness
+ * 10. Version information
  */
 
 import { Command } from 'commander';
 import { resolve } from 'path';
 import {
+  checkBinaries,
   checkGrafemaInitialized,
   checkServerStatus,
   checkConfigValidity,
@@ -47,6 +49,8 @@ Examples:
     const checks: DoctorCheckResult[] = [];
 
     // Level 1: Prerequisites (fail-fast)
+    checks.push(await checkBinaries());
+
     const initCheck = await checkGrafemaInitialized(projectPath);
     checks.push(initCheck);
 

package/src/commands/explain.ts

@@ -16,7 +16,7 @@ import { Command } from 'commander';
 import { resolve, join, relative, normalize } from 'path';
 import { existsSync, realpathSync } from 'fs';
 import { toRelativeDisplay } from '../utils/pathUtils.js';
-import { RFDBServerBackend, FileExplainer, type EnhancedNode } from '@grafema/core';
+import { RFDBServerBackend, FileExplainer, type EnhancedNode } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 interface ExplainOptions {
@@ -81,7 +81,7 @@ If a file shows NOT_ANALYZED:
     // Keep relative path for display
     const relativeFilePath = relative(projectPath, absoluteFilePath);
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     try {

package/src/commands/explore.tsx

@@ -15,7 +15,7 @@ import { existsSync } from 'fs';
 import { execSync } from 'child_process';
 import React, { useState, useEffect } from 'react';
 import { render, Box, Text, useInput, useApp } from 'ink';
-import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore, findCallsInFunction as findCallsInFunctionCore } from '@grafema/core';
+import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore, findCallsInFunction as findCallsInFunctionCore } from '@grafema/util';
 import { getCodePreview, formatCodePreview } from '../utils/codePreview.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
@@ -816,7 +816,7 @@ async function getCallees(backend: RFDBServerBackend, nodeId: string, limit: num
   const seen = new Set<string>();
 
   try {
-    // Use shared utility from @grafema/core
+    // Use shared utility from @grafema/util
     const calls = await findCallsInFunctionCore(backend, nodeId);
 
     for (const call of calls) {

package/src/commands/file.ts

@@ -14,8 +14,8 @@
 import { Command } from 'commander';
 import { resolve, join, relative, normalize } from 'path';
 import { existsSync, realpathSync } from 'fs';
-import { RFDBServerBackend, FileOverview } from '@grafema/core';
-import type { FileOverviewResult, FunctionOverview } from '@grafema/core';
+import { RFDBServerBackend, FileOverview } from '@grafema/util';
+import type { FileOverviewResult, FunctionOverview } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 import { Spinner } from '../utils/spinner.js';
 
@@ -79,7 +79,7 @@ Use 'grafema context <id>' to dive deeper into any specific entity.
     const absoluteFilePath = realpathSync(resolvedPath);
     const relativeFilePath = relative(projectPath, absoluteFilePath);
 
-    const backend = new RFDBServerBackend({ dbPath });
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
     await backend.connect();
 
     const spinner = new Spinner('Loading file overview...');

package/src/commands/get.ts

@@ -9,7 +9,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 { formatNodeDisplay } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 import { Spinner } from '../utils/spinner.js';
@@ -64,7 +64,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...');

package/src/commands/git-ingest.ts

@@ -0,0 +1,49 @@
+/**
+ * Git Ingest command - ingest git history into knowledge layer
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { GitIngest } from '@grafema/util';
+
+export const gitIngestCommand = new Command('git-ingest')
+  .description('Ingest git history into the knowledge layer')
+  .argument('[path]', 'Repository path', '.')
+  .option('--full', 'Full re-ingest (rebuilds derived/)')
+  .option('--since <date>', 'Ingest from date (ISO format)')
+  .option('--branch <branch>', 'Ingest specific branch')
+  .addHelpText('after', `
+Examples:
+  grafema git-ingest                    Incremental ingest from last cursor
+  grafema git-ingest --full             Full re-ingest of all history
+  grafema git-ingest --full ./my-repo   Full ingest of specific repo
+  grafema git-ingest --branch develop   Ingest specific branch
+  grafema git-ingest --since 2025-01-01 Ingest from specific date
+`)
+  .action(async (path: string, options: { full?: boolean; since?: string; branch?: string }) => {
+    const repoPath = resolve(path);
+    const knowledgeDir = join(repoPath, '.grafema', 'knowledge');
+
+    const ingest = new GitIngest(knowledgeDir);
+
+    console.log(`Ingesting git history from ${repoPath}...`);
+
+    try {
+      let result;
+      if (options.full || options.since) {
+        result = await ingest.ingestFull(repoPath, options.branch, options.since);
+      } else {
+        result = await ingest.ingestIncremental(repoPath, options.branch);
+      }
+
+      console.log('Git ingest complete:');
+      console.log(`  Commits: ${result.commits}`);
+      console.log(`  Authors: ${result.authors}`);
+      console.log(`  Files changed: ${result.filesChanged}`);
+      console.log(`\nData written to ${knowledgeDir}/derived/`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Error: ${message}`);
+      process.exit(1);
+    }
+  });