@grafema/cli 0.2.5-beta → 0.2.6-beta

package/dist/plugins/pluginLoader.js

@@ -0,0 +1,101 @@
+/**
+ * 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 { 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() {
+    if (pluginResolverRegistered)
+        return;
+    pluginResolverRegistered = true;
+    const grafemaPackages = {};
+    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, log) {
+    const pluginsDir = join(projectPath, '.grafema', 'plugins');
+    if (!existsSync(pluginsDir)) {
+        return {};
+    }
+    // Ensure @grafema/* imports resolve for custom plugins (REG-380)
+    registerPluginResolver();
+    const customPlugins = {};
+    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();
+                        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, customPlugins = {}, verbose = false) {
+    const plugins = [];
+    const phases = ['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;
+}
+//# sourceMappingURL=pluginLoader.js.map

package/dist/plugins/pluginLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pluginLoader.js","sourceRoot":"","sources":["../../src/plugins/pluginLoader.ts"],"names":[],"mappings":"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"}

package/dist/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);
+}

package/dist/utils/codePreview.d.ts

@@ -9,6 +9,7 @@ export interface CodePreviewOptions {
     line: number;
     contextBefore?: number;
     contextAfter?: number;
+    projectPath?: string;
 }
 export interface CodePreviewResult {
     lines: string[];

package/dist/utils/codePreview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codePreview.d.ts","sourceRoot":"","sources":["../../src/utils/codePreview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,IAAI,CA0BpF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,EAAE,CAeV"}
+{"version":3,"file":"codePreview.d.ts","sourceRoot":"","sources":["../../src/utils/codePreview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,IAAI,CA4BpF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,EAAE,CAeV"}

package/dist/utils/codePreview.js

@@ -5,17 +5,19 @@
  * for displaying in the explorer UI.
  */
 import { readFileSync, existsSync } from 'fs';
+import { isAbsolute, join } from 'path';
 /**
  * Get a code preview snippet from a source file.
  * Returns lines around the specified line number with context.
  */
 export function getCodePreview(options) {
-    const { file, line, contextBefore = 2, contextAfter = 12 } = options;
-    if (!existsSync(file)) {
+    const { file, line, contextBefore = 2, contextAfter = 12, projectPath } = options;
+    const absoluteFile = projectPath && !isAbsolute(file) ? join(projectPath, file) : file;
+    if (!existsSync(absoluteFile)) {
         return null;
     }
     try {
-        const content = readFileSync(file, 'utf-8');
+        const content = readFileSync(absoluteFile, 'utf-8');
         const allLines = content.split('\n');
         // Calculate range (1-indexed)
         const startLine = Math.max(1, line - contextBefore);

package/dist/utils/codePreview.js.map

@@ -1 +1 @@
-{"version":3,"file":"codePreview.js","sourceRoot":"","sources":["../../src/utils/codePreview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAe9C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAA2B;IACxD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,GAAG,CAAC,EAAE,YAAY,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAErE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAErC,8BAA8B;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,aAAa,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,YAAY,CAAC,CAAC;QAE/D,wDAAwD;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAErD,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;SACR,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA0B,EAC1B,aAAsB;IAEtB,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACrC,MAAM,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IAE/C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAErD,2BAA2B;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAExE,OAAO,GAAG,MAAM,GAAG,SAAS,MAAM,WAAW,EAAE,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"codePreview.js","sourceRoot":"","sources":["../../src/utils/codePreview.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAgBxC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAA2B;IACxD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,GAAG,CAAC,EAAE,YAAY,GAAG,EAAE,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAElF,MAAM,YAAY,GAAG,WAAW,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvF,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAErC,8BAA8B;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,aAAa,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,YAAY,CAAC,CAAC;QAE/D,wDAAwD;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAErD,OAAO;YACL,KAAK;YACL,SAAS;YACT,OAAO;SACR,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA0B,EAC1B,aAAsB;IAEtB,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACrC,MAAM,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IAE/C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;QAClC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAErD,2BAA2B;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAExE,OAAO,GAAG,MAAM,GAAG,SAAS,MAAM,WAAW,EAAE,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/formatNode.d.ts

@@ -25,7 +25,7 @@ export interface DisplayableNode {
     type: string;
     /** Human-readable name */
     name: string;
-    /** Absolute file path */
+    /** Source file path (relative to project root, or absolute for legacy) */
     file: string;
     /** Line number (optional) */
     line?: number;

package/dist/utils/formatNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatNode.d.ts","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAyBhE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAoB3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}
+{"version":3,"file":"formatNode.d.ts","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAyBhE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAoB3F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR"}

package/dist/utils/formatNode.js

@@ -4,7 +4,7 @@
  * Provides consistent formatting for node display across all CLI commands.
  * Semantic IDs are shown as the PRIMARY identifier, with location as secondary.
  */
-import { relative } from 'path';
+import { isAbsolute, relative } from 'path';
 /**
  * Get the display name for a node based on its type.
  *
@@ -77,7 +77,7 @@ export function formatNodeInline(node) {
 export function formatLocation(file, line, projectPath) {
     if (!file)
         return '';
-    const relPath = relative(projectPath, file);
+    const relPath = isAbsolute(file) ? relative(projectPath, file) : file;
     return line ? `${relPath}:${line}` : relPath;
 }
 //# sourceMappingURL=formatNode.js.map

package/dist/utils/formatNode.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatNode.js","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAoChC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,YAAY;YACf,+BAA+B;YAC/B,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC7B,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACvC,CAAC;YACD,MAAM;QACR,KAAK,cAAc;YACjB,yCAAyC;YACzC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC5B,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACtC,CAAC;YACD,MAAM;IACV,CAAC;IACD,gEAAgE;IAChE,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IACD,sDAAsD;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sCAAsC;IACzD,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAqB,EAAE,OAA0B;IACjF,MAAM,EAAE,WAAW,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,8CAA8C;IAC9C,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC,CAAC;IAErD,2BAA2B;IAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,SAAS,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAExC,8BAA8B;IAC9B,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC9D,IAAI,GAAG,EAAE,CAAC;YACR,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,eAAe,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAqB;IACpD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,IAAwB,EACxB,WAAmB;IAEnB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"formatNode.js","sourceRoot":"","sources":["../../src/utils/formatNode.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAoC5C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,YAAY;YACf,+BAA+B;YAC/B,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC7B,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACvC,CAAC;YACD,MAAM;QACR,KAAK,cAAc;YACjB,yCAAyC;YACzC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC5B,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACtC,CAAC;YACD,MAAM;IACV,CAAC;IACD,gEAAgE;IAChE,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IACD,sDAAsD;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,sCAAsC;IACzD,CAAC;IACD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAqB,EAAE,OAA0B;IACjF,MAAM,EAAE,WAAW,EAAE,YAAY,GAAG,IAAI,EAAE,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,8CAA8C;IAC9C,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC,CAAC;IAErD,2BAA2B;IAC3B,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,SAAS,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAExC,8BAA8B;IAC9B,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC9D,IAAI,GAAG,EAAE,CAAC;YACR,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,eAAe,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAqB;IACpD,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,IAAwB,EACxB,WAAmB;IAEnB,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC"}

package/dist/utils/pathUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function toRelativeDisplay(file: string, projectPath: string): string;
+//# sourceMappingURL=pathUtils.d.ts.map

package/dist/utils/pathUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.d.ts","sourceRoot":"","sources":["../../src/utils/pathUtils.ts"],"names":[],"mappings":"AAMA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3E"}

package/dist/utils/pathUtils.js

@@ -0,0 +1,9 @@
+/**
+ * Convert a node file path to relative display format.
+ * Handles both legacy absolute paths and new relative paths (REG-408).
+ */
+import { relative, isAbsolute } from 'path';
+export function toRelativeDisplay(file, projectPath) {
+    return isAbsolute(file) ? relative(projectPath, file) : file;
+}
+//# sourceMappingURL=pathUtils.js.map

package/dist/utils/pathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../../src/utils/pathUtils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAE5C,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,WAAmB;IACjE,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/cli",
-  "version": "0.2.5-beta",
+  "version": "0.2.6-beta",
   "description": "CLI for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/cli.js",
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "keywords": [
     "grafema",
@@ -33,21 +34,18 @@
   },
   "dependencies": {
     "commander": "^13.0.0",
-    "ink": "^6.6.0",
-    "ink-text-input": "^6.0.0",
-    "react": "^19.2.3",
     "yaml": "^2.8.2",
-    "@grafema/api": "0.2.5-beta",
-    "@grafema/core": "0.2.5-beta",
-    "@grafema/types": "0.2.5-beta"
+    "@grafema/core": "0.2.6-beta",
+    "@grafema/types": "0.2.6-beta",
+    "@grafema/api": "0.2.6-beta"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",
-    "@types/react": "^19.2.9",
     "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",
+    "postbuild": "mkdir -p dist/plugins && cp src/plugins/pluginResolver.js dist/plugins/",
     "clean": "rm -rf dist",
     "start": "node dist/cli.js",
     "test": "node --import tsx --test test/*.test.ts"

package/skills/grafema-codebase-analysis/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: grafema-codebase-analysis
+description: >
+  Analyze codebases using a graph database instead of reading source files.
+  Use when understanding code architecture, finding functions or call patterns,
+  tracing data flow, checking dependencies, or answering "where is X used?"
+  questions. Grafema builds a queryable code graph from static analysis —
+  prefer querying the graph over reading files manually.
+license: Apache-2.0
+compatibility: Requires Grafema MCP server configured (grafema or @grafema/mcp package)
+metadata:
+  author: Grafema
+  version: "0.2.5"
+---
+
+# Grafema: Graph-Based Codebase Analysis
+
+## Core Principle
+
+**Query the graph, not read code.**
+
+Grafema builds a graph database from your codebase via static analysis.
+Instead of reading dozens of files to understand how code connects,
+query the graph to get structured, complete answers instantly.
+
+```
+BAD:  Read 20 files hoping to find all callers of a function
+GOOD: find_calls({ name: "processPayment" }) -> get all callers in one query
+
+BAD:  Grep for variable name across files, miss aliased references
+GOOD: trace_dataflow({ source: "userInput", direction: "forward" }) -> complete data flow
+
+BAD:  Read file by file to understand module dependencies
+GOOD: get_file_overview({ file: "src/api.ts" }) -> structured imports, exports, classes, functions
+```
+
+### When to Use Grafema
+
+- Finding where functions/methods are called
+- Understanding module dependencies and imports
+- Tracing data flow (forward or backward)
+- Getting function details (signature, callers, callees)
+- Checking code invariants with Datalog rules
+- Exploring file structure and entity relationships
+
+### When NOT to Use Grafema
+
+- Reading a single specific file (use your editor/Read tool — faster)
+- Editing code (Grafema is read-only analysis)
+- Runtime behavior questions (Grafema is static analysis)
+- Files not yet analyzed (run `analyze_project` first)
+
+## Essential Tools (Tier 1)
+
+These 5 tools handle ~80% of queries. Start here.
+
+### find_nodes — Find entities by type, name, or file
+
+```json
+find_nodes({ type: "FUNCTION", name: "validateUser" })
+find_nodes({ type: "CLASS", file: "src/auth.ts" })
+find_nodes({ type: "http:request" })
+find_nodes({ type: "MODULE" })
+```
+
+**Use when:** "Find all X", "What functions are in file Y", "List all routes"
+
+**Node types:** MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER,
+CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE,
+http:route, http:request, db:query, socketio:emit, socketio:on
+
+### find_calls — Find function/method call sites
+
+```json
+find_calls({ name: "processPayment" })
+find_calls({ name: "query", className: "Database" })
+```
+
+**Use when:** "Where is X called?", "Who calls this function?", "Find all usages"
+
+Returns call sites with file locations and whether the target is resolved.
+
+### get_function_details — Complete function info
+
+```json
+get_function_details({ name: "handleRequest" })
+get_function_details({ name: "validate", file: "src/auth.ts" })
+get_function_details({ name: "processOrder", transitive: true })
+```
+
+**Use when:** "What does function X do?", "What does it call?", "Who calls it?"
+
+Returns: signature, parameters, what it calls, who calls it.
+Use `transitive: true` to follow call chains (A calls B calls C, max depth 5).
+
+### get_context — Deep context for any node
+
+```json
+get_context({ semanticId: "src/api.ts:handleRequest#fn" })
+get_context({ semanticId: "src/db.ts:Database#class", edgeType: "CALLS" })
+```
+
+**Use when:** "Tell me everything about this entity", "Show me its relationships"
+
+Returns: node info, source code, ALL incoming/outgoing edges with code context.
+Use after `find_nodes` to deep-dive into a specific result.
+
+### trace_dataflow — Trace data flow
+
+```json
+trace_dataflow({ source: "userInput", file: "src/handler.ts", direction: "forward" })
+trace_dataflow({ source: "dbResult", file: "src/query.ts", direction: "backward" })
+trace_dataflow({ source: "config", direction: "both", max_depth: 5 })
+```
+
+**Use when:** "Where does this value end up?", "Where does this data come from?",
+"Is user input reaching the database unsanitized?"
+
+Directions: `forward` (where does it go?), `backward` (where did it come from?), `both`.
+
+## Decision Tree
+
+```
+START: What do you need?
+|
+|-- "Find entities (functions, classes, routes)"
+|   -> find_nodes({ type, name, file })
+|
+|-- "Find who calls function X"
+|   -> find_calls({ name: "X" })
+|   -> For full details: get_function_details({ name: "X" })
+|
+|-- "Understand a specific entity deeply"
+|   -> First: find_nodes to get its semantic ID
+|   -> Then: get_context({ semanticId: "..." })
+|
+|-- "Trace data flow"
+|   -> trace_dataflow({ source, file, direction })
+|
+|-- "Understand a file's structure"
+|   -> get_file_overview({ file: "path/to/file.ts" })
+|
+|-- "Trace an alias/re-export chain"
+|   -> trace_alias({ variableName: "alias", file: "path.ts" })
+|
+|-- "Check a code rule/invariant"
+|   -> check_invariant({ rule: "violation(X) :- ..." })
+|
+|-- "Custom complex query"
+|   -> query_graph({ query: "violation(X) :- ..." })
+|   -> See references/query-patterns.md for Datalog syntax
+|
+|-- "Explore unknown codebase"
+|   -> get_stats() for high-level overview
+|   -> get_schema() for available node/edge types
+|   -> find_nodes({ type: "MODULE" }) for module list
+|   -> get_file_overview for specific files
+```
+
+## Common Workflows
+
+### 1. Impact Analysis: "What breaks if I change function X?"
+
+```
+get_function_details({ name: "X", transitive: true })
+-> Check calledBy array for all callers (direct + transitive)
+-> For critical callers: get_context({ semanticId }) for full picture
+```
+
+### 2. Security Audit: "Does user input reach the database?"
+
+```
+find_nodes({ type: "http:request" })
+-> For each route, trace_dataflow({ source: requestParam, direction: "forward" })
+-> Check if flow reaches db:query nodes
+-> Use find_guards to check for sanitization
+```
+
+### 3. Onboarding: "How is this codebase structured?"
+
+```
+get_stats()                              -> Node/edge counts by type
+find_nodes({ type: "MODULE" })           -> All modules
+get_file_overview({ file: "src/index.ts" })  -> Entry point structure
+find_nodes({ type: "http:request" })     -> All API endpoints
+```
+
+### 4. Dependency Analysis: "What does module X depend on?"
+
+```
+get_file_overview({ file: "src/service.ts" })
+-> Check imports section for dependencies
+-> For each import: get_context for deeper relationships
+```
+
+### 5. Find Dead Code: "What functions have no callers?"
+
+```
+query_graph({
+  query: 'violation(X) :- node(X, "FUNCTION"), \\+ edge(_, X, "CALLS").'
+})
+```
+
+## Anti-Patterns
+
+**Don't read files to find call sites.** Use `find_calls` — it finds ALL callers across
+the entire codebase, including indirect references you'd miss by grepping.
+
+**Don't use `query_graph` for simple lookups.** `find_nodes`, `find_calls`, and
+`get_function_details` are optimized for common queries. Reserve Datalog for
+complex patterns (joins, transitive closure, invariant checks).
+
+**Don't skip analysis status.** If you just ran `analyze_project`, check
+`get_analysis_status` before querying — partial results are misleading.
+
+**Don't request excessive depth.** `get_context` with no filters returns everything.
+Use `edgeType` filter to focus on specific relationships (e.g., `"CALLS,ASSIGNED_FROM"`).
+
+**Don't use Grafema for single-file questions.** If you only need to read one file,
+use your editor. Grafema shines for cross-file relationships.
+
+## Advanced Tools (Tier 2)
+
+### query_graph — Custom Datalog queries
+
+For complex patterns not covered by high-level tools.
+See [references/query-patterns.md](references/query-patterns.md) for syntax and examples.
+
+```json
+query_graph({
+  query: "violation(X) :- node(X, \"CALL\"), attr(X, \"name\", \"eval\").",
+  explain: true
+})
+```
+
+Available predicates: `node(Id, Type)`, `edge(Src, Dst, Type)`, `attr(Id, Name, Value)`.
+Must define `violation/1` predicate for results. Use `explain: true` to debug empty results.
+
+### get_file_overview — File-level structure
+
+Structured overview of imports, exports, classes, functions, variables with relationships.
+Recommended first step when exploring a specific file before using `get_context`.
+
+### trace_alias — Resolve alias chains
+
+For code like `const alias = obj.method; alias()` — traces "alias" back to "obj.method".
+
+### get_schema — Available types
+
+Returns all node and edge types in the graph. Use when you need exact type names.
+
+### check_invariant — Code rule checking
+
+Check if a Datalog rule has violations. For persistent rules, use `create_guarantee`.
+
+## Specialized Tools (Tier 3)
+
+| Tool | Purpose |
+|------|---------|
+| get_stats | Graph statistics (node/edge counts by type) |
+| get_coverage | Analysis coverage for a path |
+| find_guards | Conditional guards protecting a node |
+| create_guarantee | Create persistent code invariant |
+| list_guarantees | List all guarantees |
+| check_guarantees | Check guarantee violations |
+| delete_guarantee | Remove a guarantee |
+| discover_services | Discover services without full analysis |
+| analyze_project | Run/re-run analysis |
+| get_analysis_status | Check analysis progress |
+| read_project_structure | Directory tree |
+| write_config | Update .grafema/config.yaml |
+| get_documentation | Grafema usage docs |
+| report_issue | Report bugs |
+
+## Troubleshooting
+
+**Query returns nothing?**
+1. Check analysis ran: `get_analysis_status`
+2. Check type names: `get_schema` for available types
+3. Use `explain: true` in `query_graph` to debug
+4. Check file paths match (relative to project root)
+
+**Need help with Datalog syntax?**
+- See [references/query-patterns.md](references/query-patterns.md)
+- Use `get_documentation({ topic: "queries" })` for inline help
+
+**Graph seems incomplete?**
+- Run `get_coverage({ path: "src/" })` to check coverage
+- Re-analyze with `analyze_project({ force: true })`
+- Check `.grafema/config.yaml` for include/exclude patterns
+
+## References
+
+- [Node and Edge Types](references/node-edge-types.md) — Complete graph schema
+- [Query Patterns](references/query-patterns.md) — Datalog cookbook with examples