@grafema/cli 0.2.4-beta → 0.2.6-beta

package/src/commands/schema.ts

@@ -10,7 +10,8 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative } from 'path';
+import { resolve, join } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync, writeFileSync } from 'fs';
 import {
   RFDBServerBackend,
@@ -82,7 +83,7 @@ function formatInterfaceYaml(schema: InterfaceSchema): string {
 
 function formatInterfaceMarkdown(schema: InterfaceSchema, projectPath: string): string {
   const lines: string[] = [];
-  const relPath = relative(projectPath, schema.source.file);
+  const relPath = toRelativeDisplay(schema.source.file, projectPath);
 
   lines.push(`# Interface: ${schema.name}`);
   lines.push('');

package/src/commands/server.ts

@@ -1,10 +1,11 @@
 /**
- * Server command - Manage RFDB server lifecycle
+ * Server command - Manage RFDB (Rega Flow Database) server lifecycle
  *
  * Provides explicit control over the RFDB server process:
  *   grafema server start   - Start detached server
  *   grafema server stop    - Stop server gracefully
  *   grafema server status  - Check if server is running
+ *   grafema server graphql - Start GraphQL API server
  */
 
 import { Command } from 'commander';
@@ -12,7 +13,7 @@ import { resolve, join } from 'path';
 import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient, loadConfig, findRfdbBinary, getBinaryNotFoundMessage } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
 // Extend config type for server settings
@@ -20,6 +21,18 @@ interface ServerConfig {
   binaryPath?: string;
 }
 
+/**
+ * Find RFDB server binary using shared utility.
+ * Wraps findRfdbBinary() with CLI-specific error logging.
+ */
+function findServerBinary(explicitPath?: string): string | null {
+  const binaryPath = findRfdbBinary({ explicitPath });
+  if (!binaryPath && explicitPath) {
+    console.error(`Specified binary not found: ${explicitPath}`);
+  }
+  return binaryPath;
+}
+
 /**
  * Check if server is running by attempting to ping it
  */
@@ -56,7 +69,7 @@ function getProjectPaths(projectPath: string) {
 
 // Create main server command with subcommands
 export const serverCommand = new Command('server')
-  .description('Manage RFDB server lifecycle')
+  .description('Manage RFDB (Rega Flow Database) server lifecycle')
   .addHelpText('after', `
 Examples:
   grafema server start                       Start the RFDB server
@@ -104,34 +117,38 @@ serverCommand
     }
 
     // Determine binary path: CLI flag > config > auto-detect
-    let explicitPath: string | undefined;
+    let binaryPath: string | null = null;
 
     if (options.binary) {
       // Explicit --binary flag
-      explicitPath = options.binary;
+      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) {
-          explicitPath = serverConfig.binaryPath;
+          binaryPath = findServerBinary(serverConfig.binaryPath);
         }
       } catch {
         // Config not found or invalid - continue with auto-detect
       }
-    }
 
-    const binaryPath = findRfdbBinary({ explicitPath });
+      // Auto-detect if not specified
+      if (!binaryPath) {
+        binaryPath = findServerBinary();
+      }
+    }
 
     if (!binaryPath) {
-      // If explicit path was given but not found, show specific error
-      if (explicitPath) {
-        exitWithError(`Specified binary not found: ${resolve(explicitPath)}`, [
-          'Check the path and try again'
-        ]);
-      }
-      exitWithError('RFDB server binary not found', getBinaryNotFoundMessage().split('\n').slice(2));
+      exitWithError('RFDB server binary not found', [
+        'Specify path: grafema server start --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...`);
@@ -323,3 +340,56 @@ serverCommand
       }
     }
   });
+
+// grafema server graphql
+serverCommand
+  .command('graphql')
+  .description('Start GraphQL API server (requires RFDB server running)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('--port <number>', 'Port to listen on', '4000')
+  .option('--host <string>', 'Hostname to bind to', 'localhost')
+  .action(async (options: { project: string; port: string; host: string }) => {
+    const projectPath = resolve(options.project);
+    const { socketPath } = getProjectPaths(projectPath);
+
+    // Check if RFDB server is running
+    const status = await isServerRunning(socketPath);
+    if (!status.running) {
+      exitWithError('RFDB server not running', [
+        'Start the server first: grafema server start',
+        'Or run: grafema analyze (starts server automatically)'
+      ]);
+    }
+
+    // Create backend connection
+    const backend = new RFDBServerBackend({ socketPath });
+    await backend.connect();
+
+    // Import and start GraphQL server
+    const { startServer } = await import('@grafema/api');
+    const port = parseInt(options.port, 10);
+
+    console.log('Starting Grafema GraphQL API...');
+    console.log(`  RFDB Socket: ${socketPath}`);
+    if (status.version) {
+      console.log(`  RFDB Version: ${status.version}`);
+    }
+    console.log('');
+
+    const server = startServer({
+      backend,
+      port,
+      hostname: options.host,
+    });
+
+    // Handle shutdown
+    const shutdown = async () => {
+      console.log('\nShutting down GraphQL server...');
+      server.close();
+      await backend.close();
+      process.exit(0);
+    };
+
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });

package/src/commands/setup-skill.ts

@@ -0,0 +1,162 @@
+/**
+ * Setup-skill command - Install Grafema Agent Skill into a project
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync, readFileSync, cpSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+/** Default install paths per platform */
+const PLATFORM_PATHS: Record<string, string> = {
+  claude: '.claude/skills',
+  gemini: '.gemini/skills',
+  cursor: '.cursor/skills',
+};
+
+const SKILL_DIR_NAME = 'grafema-codebase-analysis';
+
+interface SetupSkillOptions {
+  outputDir?: string;
+  platform?: string;
+  force?: boolean;
+}
+
+/**
+ * Get the bundled skill source directory.
+ * In the published package, skills/ is at the package root alongside dist/.
+ */
+function getSkillSourceDir(): string {
+  // __dirname is dist/commands/ -> go up to package root, then into skills/
+  return join(__dirname, '..', '..', 'skills', SKILL_DIR_NAME);
+}
+
+/**
+ * Read version from skill metadata.
+ */
+function getSkillVersion(skillDir: string): string | null {
+  const skillMd = join(skillDir, 'SKILL.md');
+  if (!existsSync(skillMd)) return null;
+
+  const content = readFileSync(skillMd, 'utf-8');
+  const versionMatch = content.match(/version:\s*"?([^"\n]+)"?/);
+  return versionMatch ? versionMatch[1].trim() : null;
+}
+
+/**
+ * Resolve the target directory for skill installation.
+ */
+function resolveTargetDir(projectPath: string, options: SetupSkillOptions): string {
+  if (options.outputDir) {
+    return resolve(options.outputDir, SKILL_DIR_NAME);
+  }
+
+  const platform = options.platform || 'claude';
+  const basePath = PLATFORM_PATHS[platform];
+  if (!basePath) {
+    throw new Error(
+      `Unknown platform: ${platform}. Supported: ${Object.keys(PLATFORM_PATHS).join(', ')}`
+    );
+  }
+
+  return join(projectPath, basePath, SKILL_DIR_NAME);
+}
+
+/**
+ * Copy skill directory recursively.
+ */
+function copySkill(sourceDir: string, targetDir: string): void {
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(sourceDir, targetDir, { recursive: true });
+}
+
+/**
+ * Install the Grafema Agent Skill into a project directory.
+ * Returns true if skill was installed, false if skipped.
+ */
+export function installSkill(projectPath: string, options: SetupSkillOptions = {}): boolean {
+  const sourceDir = getSkillSourceDir();
+
+  if (!existsSync(sourceDir)) {
+    throw new Error(`Skill source not found at ${sourceDir}. Package may be corrupted.`);
+  }
+
+  const targetDir = resolveTargetDir(projectPath, options);
+
+  // Check if already installed
+  if (existsSync(targetDir) && !options.force) {
+    const installedVersion = getSkillVersion(targetDir);
+    const sourceVersion = getSkillVersion(sourceDir);
+
+    if (installedVersion === sourceVersion) {
+      return false; // Same version, skip
+    }
+
+    // Different version — warn but don't overwrite without --force
+    console.log(`  Skill exists (v${installedVersion}), latest is v${sourceVersion}`);
+    console.log('  Use --force to update, or run: grafema setup-skill --force');
+    return false;
+  }
+
+  copySkill(sourceDir, targetDir);
+  return true;
+}
+
+export const setupSkillCommand = new Command('setup-skill')
+  .description('Install Grafema Agent Skill into your project')
+  .argument('[path]', 'Project path', '.')
+  .option('--output-dir <path>', 'Custom output directory (overrides --platform)')
+  .option('--platform <name>', 'Target platform: claude, gemini, cursor', 'claude')
+  .option('-f, --force', 'Overwrite existing skill')
+  .addHelpText('after', `
+Examples:
+  grafema setup-skill                     Install for Claude Code (.claude/skills/)
+  grafema setup-skill --platform gemini   Install for Gemini CLI (.gemini/skills/)
+  grafema setup-skill --force             Update existing skill
+  grafema setup-skill --output-dir ./my-skills/
+`)
+  .action(async (path: string, options: SetupSkillOptions) => {
+    const projectPath = resolve(path);
+    const sourceDir = getSkillSourceDir();
+
+    if (!existsSync(sourceDir)) {
+      console.error('✗ Skill source not found. Package may be corrupted.');
+      process.exit(1);
+    }
+
+    const targetDir = resolveTargetDir(projectPath, options);
+
+    // Check if already installed
+    if (existsSync(targetDir) && !options.force) {
+      const installedVersion = getSkillVersion(targetDir);
+      const sourceVersion = getSkillVersion(sourceDir);
+
+      if (installedVersion === sourceVersion) {
+        console.log(`✓ Grafema skill already installed (v${installedVersion})`);
+        console.log(`  Location: ${targetDir}`);
+        return;
+      }
+
+      console.log(`  Skill exists (v${installedVersion}), latest is v${sourceVersion}`);
+      console.log('  Use --force to update');
+      return;
+    }
+
+    try {
+      copySkill(sourceDir, targetDir);
+    } catch (err) {
+      console.error('✗ Failed to install skill:', (err as Error).message);
+      process.exit(1);
+    }
+
+    const sourceVersion = getSkillVersion(sourceDir);
+    console.log(`✓ Grafema skill installed (v${sourceVersion})`);
+    console.log(`  Location: ${targetDir}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Ensure Grafema MCP server is configured in your AI agent');
+    console.log('  2. Run "grafema analyze" to build the code graph');
+    console.log('  3. Your AI agent will now prefer graph queries over reading files');
+  });

package/src/commands/trace.ts

@@ -8,9 +8,9 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join } from 'path';
+import { isAbsolute, resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, traceValues, type ValueSource } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, traceValues, type ValueSource } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 
@@ -227,12 +227,21 @@ async function findVariables(
       if (name.toLowerCase() === varName.toLowerCase()) {
         // If scope specified, check if variable is in that scope
         if (scopeName) {
-          const parsed = parseSemanticId(node.id);
-          if (!parsed) continue; // Skip nodes with invalid IDs
+          // Try v2 parsing first
+          const parsedV2 = parseSemanticIdV2(node.id);
+          if (parsedV2) {
+            if (!parsedV2.namedParent || parsedV2.namedParent.toLowerCase() !== lowerScopeName) {
+              continue;
+            }
+          } else {
+            // Fallback to v1 parsing
+            const parsed = parseSemanticId(node.id);
+            if (!parsed) continue; // Skip nodes with invalid IDs
 
-          // Check if scopeName appears anywhere in the scope chain
-          if (!parsed.scopePath.some(s => s.toLowerCase() === lowerScopeName)) {
-            continue;
+            // Check if scopeName appears anywhere in the scope chain
+            if (!parsed.scopePath.some(s => s.toLowerCase() === lowerScopeName)) {
+              continue;
+            }
           }
         }
 
@@ -738,7 +747,7 @@ async function handleSinkTrace(
     const sourcesCount = pv.sources.length;
     console.log(`  - ${JSON.stringify(pv.value)} (${sourcesCount} source${sourcesCount === 1 ? '' : 's'})`);
     for (const src of pv.sources.slice(0, 3)) {
-      const relativePath = src.file.startsWith(projectPath)
+      const relativePath = isAbsolute(src.file)
         ? src.file.substring(projectPath.length + 1)
         : src.file;
       console.log(`    <- ${relativePath}:${src.line}`);
@@ -900,7 +909,7 @@ async function handleRouteTrace(
     // Format traced values
     const sources = await Promise.all(
       traced.map(async (t) => {
-        const relativePath = t.source.file.startsWith(projectPath)
+        const relativePath = isAbsolute(t.source.file)
           ? t.source.file.substring(projectPath.length + 1)
           : t.source.file;
 

package/src/plugins/builtinPlugins.ts

@@ -0,0 +1,108 @@
+/**
+ * Built-in plugin registry — maps plugin names to factory functions.
+ *
+ * Each entry creates a fresh plugin instance. Plugin names match the class names
+ * and are referenced by name in .grafema/config.yaml under phases:
+ * discovery, indexing, analysis, enrichment, validation.
+ */
+
+import type { Plugin } from '@grafema/core';
+import {
+  // Discovery
+  SimpleProjectDiscovery,
+  MonorepoServiceDiscovery,
+  WorkspaceDiscovery,
+  // Indexing
+  JSModuleIndexer,
+  RustModuleIndexer,
+  // Analysis
+  JSASTAnalyzer,
+  ExpressRouteAnalyzer,
+  ExpressResponseAnalyzer,
+  NestJSRouteAnalyzer,
+  SocketIOAnalyzer,
+  DatabaseAnalyzer,
+  FetchAnalyzer,
+  ServiceLayerAnalyzer,
+  ReactAnalyzer,
+  RustAnalyzer,
+  // Enrichment
+  MethodCallResolver,
+  ArgumentParameterLinker,
+  AliasTracker,
+  ValueDomainAnalyzer,
+  MountPointResolver,
+  ExpressHandlerLinker,
+  PrefixEvaluator,
+  InstanceOfResolver,
+  ImportExportLinker,
+  FunctionCallResolver,
+  HTTPConnectionEnricher,
+  ConfigRoutingMapBuilder,
+  ServiceConnectionEnricher,
+  RustFFIEnricher,
+  RejectionPropagationEnricher,
+  CallbackCallResolver,
+  // Validation
+  CallResolverValidator,
+  EvalBanValidator,
+  SQLInjectionValidator,
+  AwaitInLoopValidator,
+  ShadowingDetector,
+  GraphConnectivityValidator,
+  DataFlowValidator,
+  TypeScriptDeadCodeValidator,
+  BrokenImportValidator,
+  UnconnectedRouteValidator,
+  PackageCoverageValidator,
+} from '@grafema/core';
+
+export const BUILTIN_PLUGINS: Record<string, () => Plugin> = {
+  // Discovery
+  SimpleProjectDiscovery: () => new SimpleProjectDiscovery() as Plugin,
+  MonorepoServiceDiscovery: () => new MonorepoServiceDiscovery() as Plugin,
+  WorkspaceDiscovery: () => new WorkspaceDiscovery() as Plugin,
+  // Indexing
+  JSModuleIndexer: () => new JSModuleIndexer() as Plugin,
+  RustModuleIndexer: () => new RustModuleIndexer() as Plugin,
+  // Analysis
+  JSASTAnalyzer: () => new JSASTAnalyzer() as Plugin,
+  ExpressRouteAnalyzer: () => new ExpressRouteAnalyzer() as Plugin,
+  ExpressResponseAnalyzer: () => new ExpressResponseAnalyzer() as Plugin,
+  NestJSRouteAnalyzer: () => new NestJSRouteAnalyzer() as Plugin,
+  SocketIOAnalyzer: () => new SocketIOAnalyzer() as Plugin,
+  DatabaseAnalyzer: () => new DatabaseAnalyzer() as Plugin,
+  FetchAnalyzer: () => new FetchAnalyzer() as Plugin,
+  ServiceLayerAnalyzer: () => new ServiceLayerAnalyzer() as Plugin,
+  ReactAnalyzer: () => new ReactAnalyzer() as Plugin,
+  RustAnalyzer: () => new RustAnalyzer() as Plugin,
+  // Enrichment
+  MethodCallResolver: () => new MethodCallResolver() as Plugin,
+  ArgumentParameterLinker: () => new ArgumentParameterLinker() as Plugin,
+  AliasTracker: () => new AliasTracker() as Plugin,
+  ValueDomainAnalyzer: () => new ValueDomainAnalyzer() as Plugin,
+  MountPointResolver: () => new MountPointResolver() as Plugin,
+  ExpressHandlerLinker: () => new ExpressHandlerLinker() as Plugin,
+  PrefixEvaluator: () => new PrefixEvaluator() as Plugin,
+  InstanceOfResolver: () => new InstanceOfResolver() as Plugin,
+  ImportExportLinker: () => new ImportExportLinker() as Plugin,
+  FunctionCallResolver: () => new FunctionCallResolver() as Plugin,
+  HTTPConnectionEnricher: () => new HTTPConnectionEnricher() as Plugin,
+  ConfigRoutingMapBuilder: () => new ConfigRoutingMapBuilder() as Plugin,
+  ServiceConnectionEnricher: () => new ServiceConnectionEnricher() as Plugin,
+  RustFFIEnricher: () => new RustFFIEnricher() as Plugin,
+  RejectionPropagationEnricher: () => new RejectionPropagationEnricher() as Plugin,
+  CallbackCallResolver: () => new CallbackCallResolver() as Plugin,
+  // Validation
+  CallResolverValidator: () => new CallResolverValidator() as Plugin,
+  EvalBanValidator: () => new EvalBanValidator() as Plugin,
+  SQLInjectionValidator: () => new SQLInjectionValidator() as Plugin,
+  AwaitInLoopValidator: () => new AwaitInLoopValidator() as Plugin,
+  ShadowingDetector: () => new ShadowingDetector() as Plugin,
+  GraphConnectivityValidator: () => new GraphConnectivityValidator() as Plugin,
+  DataFlowValidator: () => new DataFlowValidator() as Plugin,
+  TypeScriptDeadCodeValidator: () => new TypeScriptDeadCodeValidator() as Plugin,
+  BrokenImportValidator: () => new BrokenImportValidator() as Plugin,
+  UnconnectedRouteValidator: () => new UnconnectedRouteValidator() as Plugin,
+  PackageCoverageValidator: () => new PackageCoverageValidator() as Plugin,
+};

package/src/plugins/pluginLoader.ts

@@ -0,0 +1,123 @@
+/**
+ * Plugin loading — resolves built-in and custom plugins from config.
+ *
+ * Handles:
+ * - ESM resolve hook for custom plugin @grafema/* imports
+ * - Loading custom plugins from .grafema/plugins/
+ * - Creating plugin instances from config phases
+ */
+
+import { join } from 'path';
+import { existsSync, readdirSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { register } from 'node:module';
+import type { Plugin, GrafemaConfig } from '@grafema/core';
+import { BUILTIN_PLUGINS } from './builtinPlugins.js';
+
+/**
+ * Register ESM resolve hook so custom plugins can import @grafema/* packages.
+ *
+ * Plugins in .grafema/plugins/ do `import { Plugin } from '@grafema/core'`,
+ * but @grafema/core isn't in the target project's node_modules/.
+ * This hook redirects those imports to the CLI's bundled packages.
+ *
+ * Uses module.register() (stable Node.js 20.6+ API).
+ * Safe to call multiple times — subsequent calls add redundant hooks
+ * that short-circuit on the same specifiers.
+ */
+let pluginResolverRegistered = false;
+
+export function registerPluginResolver(): void {
+  if (pluginResolverRegistered) return;
+  pluginResolverRegistered = true;
+
+  const grafemaPackages: Record<string, string> = {};
+  for (const pkg of ['@grafema/core', '@grafema/types']) {
+    try {
+      grafemaPackages[pkg] = import.meta.resolve(pkg);
+    } catch {
+      // Package not available from CLI context — skip
+    }
+  }
+
+  register(
+    new URL('./pluginResolver.js', import.meta.url),
+    { data: { grafemaPackages } },
+  );
+}
+
+/**
+ * Load custom plugins from .grafema/plugins/ directory
+ */
+export async function loadCustomPlugins(
+  projectPath: string,
+  log: (msg: string) => void
+): Promise<Record<string, () => Plugin>> {
+  const pluginsDir = join(projectPath, '.grafema', 'plugins');
+  if (!existsSync(pluginsDir)) {
+    return {};
+  }
+
+  // Ensure @grafema/* imports resolve for custom plugins (REG-380)
+  registerPluginResolver();
+
+  const customPlugins: Record<string, () => Plugin> = {};
+
+  try {
+    const files = readdirSync(pluginsDir).filter(
+      (f) => f.endsWith('.js') || f.endsWith('.mjs') || f.endsWith('.cjs')
+    );
+
+    for (const file of files) {
+      try {
+        const pluginPath = join(pluginsDir, file);
+        const pluginUrl = pathToFileURL(pluginPath).href;
+        const module = await import(pluginUrl);
+
+        const PluginClass = module.default || module[file.replace(/\.[cm]?js$/, '')];
+        if (PluginClass && typeof PluginClass === 'function') {
+          const pluginName = PluginClass.name || file.replace(/\.[cm]?js$/, '');
+          customPlugins[pluginName] = () => {
+            const instance = new PluginClass() as Plugin;
+            instance.config.sourceFile = pluginPath;
+            return instance;
+          };
+          log(`Loaded custom plugin: ${pluginName}`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`Failed to load plugin ${file}: ${message}`);
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`Error loading custom plugins: ${message}`);
+  }
+
+  return customPlugins;
+}
+
+export function createPlugins(
+  config: GrafemaConfig['plugins'],
+  customPlugins: Record<string, () => Plugin> = {},
+  verbose: boolean = false
+): Plugin[] {
+  const plugins: Plugin[] = [];
+  const phases: (keyof GrafemaConfig['plugins'])[] = ['discovery', 'indexing', 'analysis', 'enrichment', 'validation'];
+
+  for (const phase of phases) {
+    const names = config[phase] || [];
+    for (const name of names) {
+      // Check built-in first, then custom
+      const factory = BUILTIN_PLUGINS[name] || customPlugins[name];
+      if (factory) {
+        plugins.push(factory());
+      } else if (verbose) {
+        // Only show plugin warning in verbose mode
+        console.warn(`Plugin not found: ${name} (skipping). Check .grafema/config.yaml or add to .grafema/plugins/`);
+      }
+    }
+  }
+
+  return plugins;
+}

package/src/plugins/pluginResolver.js

@@ -0,0 +1,38 @@
+/**
+ * ESM resolve hook for custom Grafema plugins.
+ *
+ * Allows plugins in .grafema/plugins/ to `import { Plugin } from '@grafema/core'`
+ * without requiring @grafema/core in the target project's node_modules/.
+ *
+ * The hook maps @grafema/* bare specifiers to the actual package URLs
+ * within the CLI's dependency tree.
+ *
+ * Registered via module.register() before loading custom plugins.
+ * Must be plain JS — loader hooks run in a separate thread.
+ */
+
+/** @type {Record<string, string>} package name → resolved file URL */
+let grafemaPackages = {};
+
+/**
+ * Called once when the hook is registered via module.register().
+ * @param {{ grafemaPackages: Record<string, string> }} data
+ */
+export function initialize(data) {
+  grafemaPackages = data.grafemaPackages;
+}
+
+/**
+ * Resolve hook — intercepts bare specifier imports for @grafema/* packages
+ * and redirects them to the CLI's bundled versions.
+ *
+ * Only exact package name matches are handled (e.g. '@grafema/core').
+ * All other specifiers pass through to the default resolver.
+ */
+export function resolve(specifier, context, next) {
+  if (grafemaPackages[specifier]) {
+    return { url: grafemaPackages[specifier], shortCircuit: true };
+  }
+
+  return next(specifier, context);
+}