@grafema/cli 0.2.12-beta → 0.3.1-beta

package/src/commands/analyzeAction.ts

@@ -1,24 +1,24 @@
 /**
- * Analyze command action — connects to RFDB, loads plugins, runs Orchestrator.
+ * Analyze command action — spawns grafema-orchestrator for project analysis.
  *
- * Extracted from analyze.ts (REG-435) to keep command definition separate
- * from execution logic.
+ * The Rust grafema-orchestrator binary handles the full analysis pipeline:
+ * discovery, parsing (OXC), analysis (grafema-analyzer), resolution,
+ * and RFDB ingestion. This action finds the binary, spawns it with
+ * the correct args, streams output, and prints a summary.
  */
 
 import { resolve, join } from 'path';
 import { existsSync, mkdirSync } from 'fs';
+import { spawn } from 'child_process';
 import {
-  Orchestrator,
   RFDBServerBackend,
-  DiagnosticReporter,
-  DiagnosticWriter,
   createLogger,
-  loadConfig,
-  StrictModeFailure,
-} from '@grafema/core';
-import type { LogLevel, GraphBackend } from '@grafema/types';
-import { ProgressRenderer } from '../utils/progressRenderer.js';
-import { loadCustomPlugins, createPlugins } from '../plugins/pluginLoader.js';
+  findOrchestratorBinary,
+  getBinaryNotFoundMessage,
+  findAnalyzerBinary,
+  ensureBinary,
+} from '@grafema/util';
+import type { LogLevel } from '@grafema/util';
 
 export interface NodeEdgeCountBackend {
   nodeCount: () => Promise<number>;
@@ -53,6 +53,28 @@ function getLogLevel(options: { quiet?: boolean; verbose?: boolean; logLevel?: s
   return 'silent';  // Default: silent logs, clean progress UI
 }
 
+/**
+ * Find the grafema.config.yaml config file for the orchestrator.
+ *
+ * Search order:
+ * 1. <projectPath>/grafema.config.yaml
+ * 2. <projectPath>/.grafema/config.yaml (legacy location)
+ */
+function findConfigFile(projectPath: string): string | null {
+  const candidates = [
+    join(projectPath, 'grafema.config.yaml'),
+    join(projectPath, '.grafema', 'config.yaml'),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
 export async function analyzeAction(path: string, options: { service?: string; entrypoint?: string; clear?: boolean; quiet?: boolean; verbose?: boolean; debug?: boolean; logLevel?: string; logFile?: string; strict?: boolean; autoStart?: boolean }): Promise<void> {
   const projectPath = resolve(path);
   const grafemaDir = join(projectPath, '.grafema');
@@ -71,35 +93,74 @@ export async function analyzeAction(path: string, options: { service?: string; e
   // Create logger based on CLI flags
   const logLevel = getLogLevel(options);
   const logFile = options.logFile ? resolve(options.logFile) : undefined;
-  const logger = createLogger(logLevel, logFile ? { logFile } : undefined);
+  const _logger = createLogger(logLevel, logFile ? { logFile } : undefined);
 
   if (logFile) {
     debug(`Log file: ${logFile}`);
   }
   debug(`Analyzing project: ${projectPath}`);
 
-  // Connect to RFDB server
-  // Default: require explicit `grafema server start`
-  // Use --auto-start for CI or backwards compatibility
-  // In normal mode (not verbose), suppress backend logs for clean progress UI
+  // Find grafema-orchestrator binary
+  const orchestratorBinary = findOrchestratorBinary();
+  if (!orchestratorBinary) {
+    console.error('');
+    console.error(getBinaryNotFoundMessage('grafema-orchestrator'));
+    process.exit(1);
+  }
+
+  debug(`Using orchestrator: ${orchestratorBinary}`);
+
+  // Ensure JS/TS analyzer binaries exist (lazy download if missing)
+  for (const binName of ['grafema-analyzer', 'grafema-resolve']) {
+    const existing = findAnalyzerBinary(binName);
+    if (!existing) {
+      const downloaded = await ensureBinary(binName, null, info);
+      if (downloaded) {
+        debug(`Downloaded ${binName} → ${downloaded}`);
+      }
+    }
+  }
+
+  // Find config file for the orchestrator
+  const configPath = findConfigFile(projectPath);
+  if (!configPath) {
+    console.error('');
+    console.error('No grafema config file found.');
+    console.error('');
+    console.error('Expected one of:');
+    console.error(`  ${join(projectPath, 'grafema.config.yaml')}`);
+    console.error(`  ${join(projectPath, '.grafema', 'config.yaml')}`);
+    console.error('');
+    console.error('Create a config file with at least:');
+    console.error('  root: "."');
+    console.error('  include:');
+    console.error('    - "src/**/*.js"');
+    console.error('');
+    process.exit(1);
+  }
+
+  debug(`Using config: ${configPath}`);
+
+  // Connect to RFDB server — auto-start by default (zero-config UX)
   const backend = new RFDBServerBackend({
     dbPath,
-    autoStart: options.autoStart ?? false,
-    silent: !options.verbose  // Silent in normal mode (show progress), verbose shows logs
+    autoStart: options.autoStart ?? true,
+    silent: !options.verbose,
+    clientName: 'cli'
   });
 
   try {
     await backend.connect();
   } catch (err) {
-    if (!options.autoStart && err instanceof Error && err.message.includes('not running')) {
+    if (err instanceof Error && err.message.includes('not running')) {
       console.error('');
-      console.error('RFDB server is not running.');
+      console.error('RFDB server failed to start.');
       console.error('');
-      console.error('Start the server first:');
+      console.error('Try starting manually:');
       console.error('  grafema server start');
       console.error('');
-      console.error('Or use --auto-start flag:');
-      console.error('  grafema analyze --auto-start');
+      console.error('Or run diagnostics:');
+      console.error('  grafema doctor');
       console.error('');
       process.exit(1);
     }
@@ -111,174 +172,67 @@ export async function analyzeAction(path: string, options: { service?: string; e
     await backend.clear();
   }
 
-  const config = loadConfig(projectPath, logger);
-
-  // Extract services from config (REG-174)
-  if (config.services.length > 0) {
-    debug(`Loaded ${config.services.length} service(s) from config`);
-    for (const svc of config.services) {
-      const entry = svc.entryPoint ? ` (entry: ${svc.entryPoint})` : '';
-      debug(`  - ${svc.name}: ${svc.path}${entry}`);
-    }
-  }
-
-  // Load custom plugins from .grafema/plugins/
-  const customPlugins = await loadCustomPlugins(projectPath, debug);
-  const plugins = createPlugins(config.plugins, customPlugins, options.verbose);
-
-  debug(`Loaded ${plugins.length} plugins`);
-
-  // Resolve strict mode: CLI flag overrides config
-  const strictMode = options.strict ?? config.strict ?? false;
-  if (strictMode) {
-    debug('Strict mode enabled - analysis will fail on unresolved references');
-  }
-
   const startTime = Date.now();
 
-  // Create progress renderer for CLI output
-  // In quiet mode, use a no-op renderer (skip rendering)
-  // In verbose mode, use non-interactive (newlines per update)
-  // In normal mode, use interactive (spinner with line overwrite)
-  const renderer = options.quiet
-    ? null
-    : new ProgressRenderer({
-        isInteractive: !options.verbose && process.stdout.isTTY,
-      });
+  // Build orchestrator args
+  const args: string[] = ['analyze', '--config', configPath, '--socket', backend.socketPath];
 
-  // Poll graph stats periodically to show node/edge counts in progress
-  let statsInterval: NodeJS.Timeout | null = null;
-  if (renderer && !options.quiet) {
-    statsInterval = setInterval(async () => {
-      try {
-        const stats = await fetchNodeEdgeCounts(backend);
-        renderer.setStats(stats.nodeCount, stats.edgeCount);
-      } catch {
-        // Ignore stats errors during analysis
-      }
-    }, 500); // Poll every 500ms
-    statsInterval.unref?.();
+  if (options.clear) {
+    args.push('--force');
   }
 
-  const orchestrator = new Orchestrator({
-    graph: backend as unknown as GraphBackend,
-    plugins,
-    serviceFilter: options.service || null,
-    entrypoint: options.entrypoint,
-    forceAnalysis: options.clear || false,
-    logger,
-    services: config.services.length > 0 ? config.services : undefined,  // Pass config services (REG-174)
-    strictMode, // REG-330: Pass strict mode flag
-    onProgress: (progress) => {
-      renderer?.update(progress);
-    },
-  });
+  debug(`Spawning: ${orchestratorBinary} ${args.join(' ')}`);
 
   let exitCode = 0;
 
   try {
-    await orchestrator.run(projectPath);
-    await backend.flush();
+    // Spawn grafema-orchestrator
+    exitCode = await new Promise<number>((resolvePromise, reject) => {
+      const child = spawn(orchestratorBinary, args, {
+        stdio: [
+          'ignore',
+          options.quiet ? 'ignore' : 'inherit',
+          options.quiet ? 'ignore' : 'inherit',
+        ],
+        env: {
+          ...process.env,
+          // Pass RUST_LOG for tracing verbosity
+          RUST_LOG: options.verbose ? 'info' : (options.debug ? 'debug' : 'warn'),
+        },
+      });
 
-    const elapsedSeconds = (Date.now() - startTime) / 1000;
-    const stats = await fetchNodeEdgeCounts(backend);
+      child.on('error', (err) => {
+        reject(new Error(`Failed to spawn grafema-orchestrator: ${err.message}`));
+      });
 
-    // Clear progress line in interactive mode, then show results
-    if (renderer && process.stdout.isTTY) {
-      process.stdout.write('\r\x1b[K'); // Clear line
-    }
-    info('');
-    info(renderer ? renderer.finish(elapsedSeconds) : `Analysis complete in ${elapsedSeconds.toFixed(2)}s`);
-    info(`  Nodes: ${stats.nodeCount}`);
-    info(`  Edges: ${stats.edgeCount}`);
+      child.on('close', (code) => {
+        resolvePromise(code ?? 1);
+      });
+    });
 
-    // Get diagnostics and report summary
-    const diagnostics = orchestrator.getDiagnostics();
-    const reporter = new DiagnosticReporter(diagnostics);
+    if (exitCode === 0) {
+      const elapsedSeconds = (Date.now() - startTime) / 1000;
+      const stats = await fetchNodeEdgeCounts(backend);
 
-    // Print summary if there are any issues
-    if (diagnostics.count() > 0) {
       info('');
-      info(reporter.categorizedSummary());
-
-      // In verbose mode, print full report
-      if (options.verbose) {
-        debug('');
-        debug(reporter.report({ format: 'text', includeSummary: false }));
-      }
-    }
-
-    // Always write diagnostics.log (required for `grafema check` command)
-    const writer = new DiagnosticWriter();
-    await writer.write(diagnostics, grafemaDir);
-    if (options.debug) {
-      debug(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
-    }
-
-    // Determine exit code based on severity
-    if (diagnostics.hasFatal()) {
-      exitCode = 1;
-    } else if (diagnostics.hasErrors()) {
-      exitCode = 2; // Completed with errors
+      info(`Analysis complete in ${elapsedSeconds.toFixed(2)}s`);
+      info(`  Nodes: ${stats.nodeCount}`);
+      info(`  Edges: ${stats.edgeCount}`);
     } else {
-      exitCode = 0; // Success (maybe warnings)
-    }
-  } catch (e) {
-    const diagnostics = orchestrator.getDiagnostics();
-    const reporter = new DiagnosticReporter(diagnostics);
-
-    // Clear progress line in interactive mode
-    if (renderer && process.stdout.isTTY) {
-      process.stdout.write('\r\x1b[K');
-    }
-
-    // Check if this is a strict mode failure (REG-332: structured output)
-    if (e instanceof StrictModeFailure) {
-      // Format ONLY from diagnostics, not from error.message
-      console.error('');
-      console.error(`✗ Strict mode: ${e.count} unresolved reference(s) found during ENRICHMENT.`);
       console.error('');
-      console.error(reporter.formatStrict(e.diagnostics, {
-        verbose: options.verbose,
-        suppressedCount: e.suppressedCount,  // REG-332
-      }));
-      console.error('');
-      console.error('Run without --strict for graceful degradation, or fix the underlying issues.');
-    } else {
-      // Generic error handling (non-strict)
-      const error = e instanceof Error ? e : new Error(String(e));
-      console.error('');
-      console.error(`✗ Analysis failed: ${error.message}`);
-      console.error('');
-      console.error('→ Run with --debug for detailed diagnostics');
-
-      if (diagnostics.count() > 0) {
-        console.error('');
-        console.error(reporter.report({ format: 'text', includeSummary: true }));
-      }
-    }
-
-    // Write diagnostics.log in debug mode even on failure
-    if (options.debug) {
-      const writer = new DiagnosticWriter();
-      await writer.write(diagnostics, grafemaDir);
-      console.error(`Diagnostics written to ${writer.getLogPath(grafemaDir)}`);
+      console.error(`Analysis failed with exit code ${exitCode}`);
     }
-
+  } catch (e) {
+    const error = e instanceof Error ? e : new Error(String(e));
+    console.error('');
+    console.error(`Analysis failed: ${error.message}`);
     exitCode = 1;
   } finally {
-    // Stop stats polling
-    if (statsInterval) {
-      clearInterval(statsInterval);
-      statsInterval = null;
-    }
-
     if (backend.connected) {
       await backend.close();
     }
 
     // Exit with appropriate code
-    // 0 = success, 1 = fatal, 2 = errors
     exitWithCode(exitCode);
   }
 }

package/src/commands/check.ts

@@ -15,8 +15,8 @@ import {
   GraphFreshnessChecker,
   IncrementalReanalyzer,
   DIAGNOSTIC_CATEGORIES,
-} from '@grafema/core';
-import type { GuaranteeGraph, DiagnosticCategoryKey } from '@grafema/core';
+} from '@grafema/util';
+import type { GuaranteeGraph, DiagnosticCategoryKey } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 
@@ -31,7 +31,7 @@ const BUILT_IN_VALIDATORS: Record<string, { name: string; description: string; c
   // }
 };
 
-// Re-export for backward compatibility (deprecated - import from @grafema/core instead)
+// Re-export for backward compatibility (deprecated - import from @grafema/util instead)
 export { DIAGNOSTIC_CATEGORIES as CHECK_CATEGORIES };
 
 export const checkCommand = new Command('check')
@@ -132,7 +132,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();
 
       // Check graph freshness
@@ -287,7 +287,7 @@ async function runBuiltInValidator(
     exitWithError('No graph database found', ['Run: grafema analyze']);
   }
 
-  const backend = new RFDBServerBackend({ dbPath });
+  const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
   await backend.connect();
 
   // Check graph freshness

package/src/commands/context.ts

@@ -21,8 +21,8 @@ import {
   getNodeDisplayName,
   formatEdgeMetadata,
   STRUCTURAL_EDGE_TYPES,
-} from '@grafema/core';
-import type { NodeContext, EdgeGroup } from '@grafema/core';
+} from '@grafema/util';
+import type { NodeContext, EdgeGroup } from '@grafema/util';
 import type { BaseNodeRecord } from '@grafema/types';
 import { getCodePreview, formatCodePreview } from '../utils/codePreview.js';
 import { formatLocation } from '../utils/formatNode.js';
@@ -79,7 +79,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('Loading context...');

package/src/commands/coverage.ts

@@ -10,7 +10,7 @@
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, CoverageAnalyzer, type CoverageResult } from '@grafema/core';
+import { RFDBServerBackend, CoverageAnalyzer, type CoverageResult } from '@grafema/util';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 export const coverageCommand = new Command('coverage')
@@ -34,7 +34,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/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();
+    }
+  });