@eventra_dev/eventra-cli 1.0.1 → 1.0.3

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm version" src="https://img.shields.io/npm/v/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://github.com/and-1991/eventra-cli/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/and-1991/eventra-cli/test.yml?branch=main&label=tests&style=flat-square&logo=vitest&logoColor=white"></a>
-  <img alt="unit tests" src="https://img.shields.io/badge/unit-52%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
+  <img alt="unit tests" src="https://img.shields.io/badge/unit-59%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="e2e fixtures" src="https://img.shields.io/badge/e2e-12%20fixtures-brightgreen?style=flat-square">
   <img alt="node" src="https://img.shields.io/node/v/@eventra_dev/eventra-cli?style=flat-square&color=darkgreen&logo=node.js&logoColor=white">
   <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square&logo=typescript&logoColor=white"></a>
@@ -23,7 +23,7 @@ Eventra CLI statically discovers analytics events from [**@eventra_dev/eventra-s
 
 The CLI scans TypeScript and JavaScript with the TypeScript compiler API and extracts **only** calls to `Eventra.prototype.track()` on instances of `Eventra` imported from `@eventra_dev/eventra-sdk`.
 
-It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries.
+It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries out of the box. Framework files (e.g. `.vue`) require an optional [plugin](#plugins).
 
 ---
 
@@ -166,6 +166,66 @@ Network resilience:
 
 ---
 
+## Plugins
+
+The CLI core is framework-agnostic. Extensions are **separate npm packages** with their own types — the CLI loads them from `eventra.json` and adapts their output internally.
+
+### Vue (`.vue` SFC)
+
+Install the official Vue plugin and enable it in config:
+
+```bash
+pnpm add -D @eventra_dev/cli-plugin-vue
+```
+
+```json
+{
+  "plugins": ["@eventra_dev/cli-plugin-vue"],
+  "sync": {
+    "include": ["**/*.{ts,tsx,js,jsx}"],
+    "exclude": ["node_modules", "dist", ".next", ".git"]
+  }
+}
+```
+
+The plugin:
+
+- splits each `.vue` file into virtual TypeScript modules (`App.vue.ts`, `App.vue.template.ts`)
+- extracts `track()` calls from `<script>` blocks
+- detects static `event="feature_name"` attributes in `<template>` (literals only)
+
+`sync.include` does **not** need `**/*.vue` manually — the plugin registers `**/*.vue` via `includeGlobs`.
+
+### Before publishing / local development
+
+Plugins are resolved from your project's `node_modules` (same as any dependency):
+
+```json
+{
+  "devDependencies": {
+    "@eventra_dev/cli-plugin-vue": "file:../cli-plugin-vue"
+  }
+}
+```
+
+The plugin package must be built (`dist/`) before use. Unpublished plugins work the same way — only the install source differs.
+
+### Plugin contract (for authors)
+
+External plugins export an object (or factory) with:
+
+| Field | Purpose |
+|-------|---------|
+| `id` | Unique preprocessor name |
+| `includeGlobs` | Extra glob patterns merged into the scan |
+| `match(path)` | Whether this plugin handles a file |
+| `transform({ path, source })` | Returns `{ modules: [{ path, content }] }` |
+| `staticSinks?` | Declarative callee-based sink rules (CLI converts to internal detectors) |
+
+No dependency on `@eventra_dev/eventra-cli` is required. See [`ARCHITECTURE.md`](./ARCHITECTURE.md#plugin-kernel-phase-15--foundation-shipped) for details.
+
+---
+
 ## Configuration
 
 ```json
@@ -174,6 +234,7 @@ Network resilience:
   "endpoint": "",
   "events": [],
   "functionWrappers": [],
+  "plugins": [],
   "sync": {
     "include": ["**/*.{ts,tsx,js,jsx}"],
     "exclude": ["node_modules", "dist", ".next", ".git"]
@@ -181,14 +242,25 @@ Network resilience:
 }
 ```
 
+| Field | Description |
+|-------|-------------|
+| `plugins` | Module specifiers to `import()` at startup (e.g. `@eventra_dev/cli-plugin-vue`) |
+| `sync.include` | Base glob patterns; plugin `includeGlobs` are merged automatically |
+| `sync.exclude` | Paths skipped during scan |
+
 ---
 
 ## How it works
 
-1. Load project files into an incremental TypeScript program (with SDK type shim).
-2. **Phase 1** — find `Eventra` instances from `@eventra_dev/eventra-sdk` and register function wrappers that call `.track()`.
-3. **Phase 2** — resolve static event names and wrapper propagation chains.
-4. Write results to `eventra.json`.
+1. Load built-in plugins (`eventra-sdk` sink detector) and any packages listed in `plugins`.
+2. Glob project files (`sync.include` + plugin `includeGlobs`).
+3. Run file preprocessors (e.g. `.vue` → virtual `.ts` modules).
+4. Load sources into an incremental TypeScript program (with SDK type shim).
+5. **Phase 1** — find `Eventra` instances from `@eventra_dev/eventra-sdk` and register function wrappers that call `.track()`.
+6. **Phase 2** — resolve static event names and wrapper propagation chains (sink detector chain includes plugin sinks).
+7. Write results to `eventra.json`.
+
+`watch` tracks **disk source files** (including `.vue`), re-runs preprocessors on change, and incrementally updates the engine.
 
 No runtime execution. No monkey-patching.
 
@@ -203,9 +275,9 @@ No runtime execution. No monkey-patching.
 
 ## Test Coverage
 
-Two test layers, **52 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios**.
+Two test layers, **59 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios**.
 
-**Unit tests (vitest)** — 10 suites covering core modules:
+**Unit tests (vitest)** — 13 suites covering core modules:
 
 | Module | Covers |
 |---|---|
@@ -214,9 +286,12 @@ Two test layers, **52 unit tests + 12 e2e fixtures + 3 `check` exit-code scenari
 | `DocumentRegistry` | Path normalization, version bumping, no-op on identical content, `ensure()` from disk |
 | `CompilerContext` | Stage/update/remove files, `resolveModule` with `tsconfig.json` `paths`, source-file enumeration |
 | `EventraEngine` | Direct calls, SDK isolation, cross-file wrappers, file updates, file removal, wrapper filtering |
+| `PluginRegistry` | Built-in SDK sink, preprocessors, virtual-path mapping, include-pattern dedup |
+| `external plugin adapter` | Transform output mapping, static sink registration, invalid result rejection |
+| `vue-shaped external plugin` | Adapter path for script + template virtual modules and `staticSinks` |
 | `processFile` | Script-kind detection, import/export specifier extraction |
 | `extractTemplateExpressions` | Vue/Svelte/Astro attribute patterns |
-| `normalizeConfig` | Sort events, dedupe wrappers, defaults, preserve `apiKey` / `endpoint` / `sync` |
+| `normalizeConfig` | Sort events, dedupe wrappers, defaults, preserve `apiKey` / `endpoint` / `sync` / `plugins` |
 | `buildConfigFromScan` | Replace events + wrappers, preserve everything else |
 | `hash` | Stability and uniqueness |
 

package/dist/analysis/engine/analyzeFile.js

@@ -4,8 +4,8 @@ exports.indexSourceFile = indexSourceFile;
 exports.extractFromIndex = extractFromIndex;
 const scanner_1 = require("../scanner/scanner");
 const extractor_1 = require("../extractor/extractor");
-function indexSourceFile(source, checker, wrapperRegistry) {
-    return (0, scanner_1.scanSource)(source, checker, wrapperRegistry);
+function indexSourceFile(source, checker, wrapperRegistry, plugins) {
+    return (0, scanner_1.scanSource)(source, checker, wrapperRegistry, plugins);
 }
 function extractFromIndex(index, config, checker, wrapperRegistry, evaluationCache, resolvedCallCache, returnPropagationCache, resolvedExportCache) {
     return (0, extractor_1.extractEvents)(index, checker, config, evaluationCache, resolvedExportCache, resolvedCallCache, returnPropagationCache, wrapperRegistry);

package/dist/analysis/scanner/scanner.js

@@ -7,7 +7,7 @@ exports.scanSource = scanSource;
 const typescript_1 = __importDefault(require("typescript"));
 const sinkDetector_1 = require("./sinkDetector");
 const propagationAnalyzer_1 = require("./analyzer/propagationAnalyzer");
-function scanSource(source, checker, wrapperRegistry) {
+function scanSource(source, checker, wrapperRegistry, plugins) {
     const sinks = [];
     const wrappers = [];
     const trackCalls = [];
@@ -23,7 +23,7 @@ function scanSource(source, checker, wrapperRegistry) {
         }
         // sink detection
         if (typescript_1.default.isCallExpression(node)) {
-            const sink = (0, sinkDetector_1.detectTrackSink)(node, checker);
+            const sink = (0, sinkDetector_1.detectTrackSink)(node, checker, plugins);
             if (sink) {
                 sinks.push(sink);
                 const trackedArguments = sink.trackedArguments.map(tracked => {

package/dist/analysis/scanner/sinkDetector.js

@@ -1,37 +1,6 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectTrackSink = detectTrackSink;
-const typescript_1 = __importDefault(require("typescript"));
-const isEventraTrackCall_1 = require("../sdk/isEventraTrackCall");
-/** SDK: track(name: string, options?) — event name is always the first argument. */
-function extractTrackedArguments(call) {
-    if (call.arguments.length === 0) {
-        return [];
-    }
-    const first = call.arguments[0];
-    if (typescript_1.default.isObjectLiteralExpression(first)) {
-        return [];
-    }
-    return [
-        {
-            index: 0,
-            propertyPath: [],
-        },
-    ];
-}
-function detectTrackSink(call, checker) {
-    if (!(0, isEventraTrackCall_1.isEventraSdkTrackCall)(call, checker)) {
-        return null;
-    }
-    const trackedArguments = extractTrackedArguments(call);
-    if (trackedArguments.length === 0) {
-        return null;
-    }
-    return {
-        call,
-        trackedArguments,
-    };
+function detectTrackSink(call, checker, plugins) {
+    return plugins.detectSink({ call, checker });
 }

package/dist/cli/watch.js

@@ -13,6 +13,7 @@ const config_1 = require("../config/config");
 const eventraSdk_1 = require("../analysis/sdk/eventraSdk");
 const EventraEngine_1 = require("../core/EventraEngine");
 const scanResults_1 = require("../core/scanResults");
+const loadPlugins_1 = require("../plugin/loadPlugins");
 const SDK_TYPES_FILE = "__eventra_sdk_types__.d.ts";
 const processFile_1 = require("../filesystem/processFile");
 const getVirtualFile_1 = require("../filesystem/getVirtualFile");
@@ -23,15 +24,18 @@ async function watch() {
         return;
     }
     console.log(chalk_1.default.blue("Watching...\n"));
-    const engine = new EventraEngine_1.EventraEngine(process.cwd());
+    const plugins = await (0, loadPlugins_1.createPluginRegistry)(config);
+    const include = [...config.sync.include, ...plugins.getIncludePatterns()];
+    const engine = new EventraEngine_1.EventraEngine(process.cwd(), plugins);
     const fileDeps = new Map();
     const cache = new Map();
     const watchedDeps = new Set();
     const trackedFiles = new Set();
+    const sourceFiles = new Set();
     const normalize = (file) => {
         return path_1.default.resolve(file).replace(/\\/g, "/");
     };
-    const files = await (0, fast_glob_1.default)(config.sync.include, {
+    const files = await (0, fast_glob_1.default)(include, {
         ignore: config.sync.exclude,
         absolute: true,
     });
@@ -40,16 +44,19 @@ async function watch() {
     for (const file of files) {
         try {
             const abs = normalize(file);
+            sourceFiles.add(abs);
             const raw = await promises_1.default.readFile(abs, "utf-8");
-            // processFile extracts import specifiers for chokidar tracking;
-            // the engine itself receives raw file content.
-            const parsed = await (0, processFile_1.processFile)(abs, raw);
-            cache.set(abs, parsed);
-            trackedFiles.add(abs);
-            await engine.preloadFile((0, getVirtualFile_1.getVirtualFile)(abs), raw);
-            fileDeps.set(abs, new Set(parsed.dependencies
-                .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
-                .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(abs), dep)))));
+            const virtualFiles = await plugins.preprocessFile({ fileName: abs, content: raw });
+            for (const virtualFile of virtualFiles) {
+                const scanPath = normalize(virtualFile.fileName);
+                const parsed = await (0, processFile_1.processFile)(scanPath, virtualFile.content);
+                cache.set(scanPath, parsed);
+                trackedFiles.add(scanPath);
+                await engine.preloadFile((0, getVirtualFile_1.getVirtualFile)(scanPath), virtualFile.content);
+                fileDeps.set(scanPath, new Set(parsed.dependencies
+                    .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
+                    .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(scanPath), dep)))));
+            }
         }
         catch {
             // ignore invalid files
@@ -61,7 +68,7 @@ async function watch() {
     const initialEvents = engine.getAllEvents();
     const initialWrappers = engine.getAllFunctionWrappers();
     console.log(chalk_1.default.gray(`Initial: ${initialEvents.length} events, ${initialWrappers.length} wrappers\n`));
-    const watcher = chokidar_1.default.watch([...trackedFiles, ...watchedDeps], { ignoreInitial: true });
+    const watcher = chokidar_1.default.watch([...sourceFiles, ...watchedDeps], { ignoreInitial: true });
     const queue = new Map();
     let timer = null;
     const run = async () => {
@@ -70,31 +77,31 @@ async function watch() {
         for (const file of batch) {
             try {
                 const raw = await promises_1.default.readFile(file, "utf-8");
-                // processFile here is used ONLY to extract import specifiers for
-                // chokidar's dependency tracking. The engine receives raw content
-                // and parses it itself.
-                const parsed = await (0, processFile_1.processFile)(file, raw);
-                cache.set(file, parsed);
-                trackedFiles.add(file);
-                await engine.updateFile((0, getVirtualFile_1.getVirtualFile)(file), raw, config);
-                const abs = normalize(file);
-                const prevDeps = fileDeps.get(abs) ?? new Set();
-                const nextDeps = new Set(parsed.dependencies
-                    .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
-                    .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(abs), dep))));
-                for (const dep of nextDeps) {
-                    if (prevDeps.has(dep))
-                        continue;
-                    watcher.add(dep);
-                    watchedDeps.add(dep);
+                const virtualFiles = await plugins.preprocessFile({ fileName: file, content: raw });
+                for (const virtualFile of virtualFiles) {
+                    const scanPath = normalize(virtualFile.fileName);
+                    const parsed = await (0, processFile_1.processFile)(scanPath, virtualFile.content);
+                    cache.set(scanPath, parsed);
+                    trackedFiles.add(scanPath);
+                    await engine.updateFile((0, getVirtualFile_1.getVirtualFile)(scanPath), virtualFile.content, config);
+                    const prevDeps = fileDeps.get(scanPath) ?? new Set();
+                    const nextDeps = new Set(parsed.dependencies
+                        .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
+                        .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(scanPath), dep))));
+                    for (const dep of nextDeps) {
+                        if (prevDeps.has(dep))
+                            continue;
+                        watcher.add(dep);
+                        watchedDeps.add(dep);
+                    }
+                    for (const dep of prevDeps) {
+                        if (nextDeps.has(dep))
+                            continue;
+                        watcher.unwatch(dep);
+                        watchedDeps.delete(dep);
+                    }
+                    fileDeps.set(scanPath, nextDeps);
                 }
-                for (const dep of prevDeps) {
-                    if (nextDeps.has(dep))
-                        continue;
-                    watcher.unwatch(dep);
-                    watchedDeps.delete(dep);
-                }
-                fileDeps.set(abs, nextDeps);
             }
             catch {
                 console.log(chalk_1.default.gray(`skip: ${file}`));
@@ -115,8 +122,12 @@ async function watch() {
         .on("add", schedule)
         .on("unlink", async (file) => {
         const abs = normalize(file);
-        trackedFiles.delete(abs);
-        await engine.removeFile((0, getVirtualFile_1.getVirtualFile)(abs), config);
+        sourceFiles.delete(abs);
+        const virtualPaths = plugins.getVirtualPathsForSource(abs);
+        for (const virtualPath of virtualPaths) {
+            trackedFiles.delete(virtualPath);
+            await engine.removeFile((0, getVirtualFile_1.getVirtualFile)(virtualPath), config);
+        }
         await (0, scanResults_1.persistScanResults)(config, engine);
         console.log(chalk_1.default.red(`Removed → ${engine.getAllEvents().length} events, ${engine.getAllFunctionWrappers().length} wrappers`));
     });

package/dist/config/config.js

@@ -28,6 +28,7 @@ function normalizeConfig(config) {
         endpoint: config.endpoint ?? "",
         events: [...(config.events ?? [])].sort(),
         functionWrappers: uniqueWrappers.sort((a, b) => a.name.localeCompare(b.name)),
+        plugins: [...(config.plugins ?? [])],
         sync: {
             include: config.sync?.include ?? DEFAULT_INCLUDE,
             exclude: config.sync?.exclude ?? DEFAULT_EXCLUDE,

package/dist/core/EventraEngine.js

@@ -16,6 +16,7 @@ const returnPropagationCache_1 = require("../analysis/cache/returnPropagationCac
 const analyzeFile_1 = require("../analysis/engine/analyzeFile");
 const wrapperRegistry_1 = require("../analysis/symbols/wrapperRegistry");
 const processFile_1 = require("../filesystem/processFile");
+const loadPlugins_1 = require("../plugin/loadPlugins");
 const EMPTY_RESULT = () => ({
     events: new Set(),
     detectedFunctionWrappers: new Set(),
@@ -32,6 +33,7 @@ class EventraEngine {
     fileIndices = new Map();
     fileResults = new Map();
     normalizedPathCache = new Map();
+    plugins;
     isPreloading = false;
     lastConfig = {
         events: [],
@@ -41,7 +43,8 @@ class EventraEngine {
             exclude: [],
         },
     };
-    constructor(rootDir) {
+    constructor(rootDir, plugins = (0, loadPlugins_1.createBuiltinPluginRegistry)()) {
+        this.plugins = plugins;
         this.compiler = new compilerContext_1.CompilerContext(rootDir);
         this.wrapperRegistry = new wrapperRegistry_1.WrapperRegistry(this.compiler.getChecker(), this.resolvedExportCache);
         this.scheduler = new scheduler_1.Scheduler(async (updates) => {
@@ -184,7 +187,7 @@ class EventraEngine {
             this.fileIndices.delete(normalized);
             return;
         }
-        const index = (0, analyzeFile_1.indexSourceFile)(source, this.compiler.getChecker(), this.wrapperRegistry);
+        const index = (0, analyzeFile_1.indexSourceFile)(source, this.compiler.getChecker(), this.wrapperRegistry, this.plugins);
         this.fileIndices.set(normalized, index);
     }
     extractFile(fileName, config) {

package/dist/core/projectScanner.js

@@ -11,6 +11,7 @@ const eventraSdk_1 = require("../analysis/sdk/eventraSdk");
 const EventraEngine_1 = require("./EventraEngine");
 const processFile_1 = require("../filesystem/processFile");
 const getVirtualFile_1 = require("../filesystem/getVirtualFile");
+const loadPlugins_1 = require("../plugin/loadPlugins");
 const SDK_TYPES_FILE = "__eventra_sdk_types__.d.ts";
 async function getParsedFile(file, cache) {
     const existing = cache.get(file);
@@ -22,11 +23,13 @@ async function getParsedFile(file, cache) {
     return parsed;
 }
 async function scanProject(config) {
-    const files = await (0, fast_glob_1.default)(config.sync.include, {
+    const plugins = await (0, loadPlugins_1.createPluginRegistry)(config);
+    const include = [...config.sync.include, ...plugins.getIncludePatterns()];
+    const files = await (0, fast_glob_1.default)(include, {
         ignore: config.sync.exclude,
         absolute: true,
     });
-    const engine = new EventraEngine_1.EventraEngine(process.cwd());
+    const engine = new EventraEngine_1.EventraEngine(process.cwd(), plugins);
     const cache = new Map();
     const toScan = new Set();
     for (const file of files) {
@@ -34,12 +37,16 @@ async function scanProject(config) {
             const raw = await promises_1.default.readFile(file, "utf8");
             if (raw.length > 2_000_000)
                 continue;
-            const parsed = await (0, processFile_1.processFile)(file, raw);
-            cache.set(file, parsed);
-            toScan.add(file);
-            for (const dep of parsed.dependencies) {
-                if (dep.startsWith(".") || dep.startsWith("/")) {
-                    toScan.add(path_1.default.resolve(path_1.default.dirname(file), dep));
+            const virtualFiles = await plugins.preprocessFile({ fileName: file, content: raw });
+            for (const virtualFile of virtualFiles) {
+                const parsed = await (0, processFile_1.processFile)(virtualFile.fileName, virtualFile.content);
+                const scanPath = path_1.default.resolve(virtualFile.fileName);
+                cache.set(scanPath, parsed);
+                toScan.add(scanPath);
+                for (const dep of parsed.dependencies) {
+                    if (dep.startsWith(".") || dep.startsWith("/")) {
+                        toScan.add(path_1.default.resolve(path_1.default.dirname(scanPath), dep));
+                    }
                 }
             }
         }

package/dist/plugin/adapters/external.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExternalCliPlugin = isExternalCliPlugin;
+exports.registerExternalCliPlugin = registerExternalCliPlugin;
+const typescript_1 = __importDefault(require("typescript"));
+function isStaticSink(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const sink = value;
+    return (typeof sink.id === "string" &&
+        sink.id.trim().length > 0 &&
+        typeof sink.callee === "string" &&
+        sink.callee.trim().length > 0 &&
+        Number.isInteger(sink.eventNameArgumentIndex) &&
+        sink.eventNameArgumentIndex >= 0);
+}
+function isExternalCliPlugin(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const plugin = value;
+    if (typeof plugin.id !== "string" || plugin.id.trim().length === 0) {
+        return false;
+    }
+    if (!Array.isArray(plugin.includeGlobs) || plugin.includeGlobs.some((g) => typeof g !== "string")) {
+        return false;
+    }
+    if (plugin.staticSinks !== undefined) {
+        if (!Array.isArray(plugin.staticSinks) || plugin.staticSinks.some((s) => !isStaticSink(s))) {
+            return false;
+        }
+    }
+    return typeof plugin.match === "function" && typeof plugin.transform === "function";
+}
+function createStaticCalleeSinkDetector(sink) {
+    return {
+        name: sink.id,
+        detect({ call }) {
+            const expr = call.expression;
+            if (!typescript_1.default.isIdentifier(expr) || expr.text !== sink.callee) {
+                return null;
+            }
+            const argIndex = sink.eventNameArgumentIndex;
+            if (call.arguments.length <= argIndex) {
+                return null;
+            }
+            const arg = call.arguments[argIndex];
+            if (!typescript_1.default.isStringLiteral(arg)) {
+                return null;
+            }
+            return {
+                call,
+                trackedArguments: [{ index: argIndex, propertyPath: [] }],
+            };
+        },
+    };
+}
+function mapTransformModules(plugin, fileName, modules) {
+    if (!Array.isArray(modules)) {
+        throw new Error(`Plugin "${plugin.id}" returned invalid transform result for ${fileName}`);
+    }
+    return modules.map((module, index) => {
+        if (!module || typeof module !== "object") {
+            throw new Error(`Plugin "${plugin.id}" module at index ${index} is invalid`);
+        }
+        const { path: modulePath, content } = module;
+        if (typeof modulePath !== "string" || typeof content !== "string") {
+            throw new Error(`Plugin "${plugin.id}" module at index ${index} must have string path and content`);
+        }
+        return { fileName: modulePath, content };
+    });
+}
+/** Maps an external plugin contract into the internal PluginRegistry hooks. */
+function registerExternalCliPlugin(plugin, registry) {
+    for (const glob of plugin.includeGlobs) {
+        registry.registerIncludePattern(glob);
+    }
+    registry.registerFilePreprocessor({
+        name: plugin.id,
+        test: (fileName) => plugin.match(fileName),
+        process: async ({ fileName, content }) => {
+            let result;
+            try {
+                result = await plugin.transform({ path: fileName, source: content });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`Plugin "${plugin.id}" failed to transform ${fileName}: ${message}`);
+            }
+            return mapTransformModules(plugin, fileName, result?.modules);
+        },
+    });
+    for (const sink of plugin.staticSinks ?? []) {
+        if (!isStaticSink(sink)) {
+            throw new Error(`Plugin "${plugin.id}" has invalid staticSink (id, callee, eventNameArgumentIndex)`);
+        }
+        registry.registerSinkDetector(createStaticCalleeSinkDetector(sink));
+    }
+}

package/dist/plugin/builtins/eventra-sdk.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEventraSdkPlugin = registerEventraSdkPlugin;
+const typescript_1 = __importDefault(require("typescript"));
+const isEventraTrackCall_1 = require("../../analysis/sdk/isEventraTrackCall");
+/** SDK: track(name: string, options?) — event name is always the first argument. */
+function extractTrackedArguments(call) {
+    if (call.arguments.length === 0) {
+        return [];
+    }
+    const first = call.arguments[0];
+    if (typescript_1.default.isObjectLiteralExpression(first)) {
+        return [];
+    }
+    return [{ index: 0, propertyPath: [] }];
+}
+const eventraSdkSinkDetector = {
+    name: "eventra-sdk",
+    detect({ call, checker }) {
+        if (!(0, isEventraTrackCall_1.isEventraSdkTrackCall)(call, checker)) {
+            return null;
+        }
+        const trackedArguments = extractTrackedArguments(call);
+        if (trackedArguments.length === 0) {
+            return null;
+        }
+        return { call, trackedArguments };
+    },
+};
+/** Built-in sink detection for @eventra_dev/eventra-sdk (always enabled). */
+function registerEventraSdkPlugin(registry) {
+    registry.registerSinkDetector(eventraSdkSinkDetector);
+}

package/dist/plugin/loadPlugins.js

@@ -0,0 +1,88 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBuiltinPluginRegistry = createBuiltinPluginRegistry;
+exports.createPluginRegistry = createPluginRegistry;
+const external_1 = require("./adapters/external");
+const eventra_sdk_1 = require("./builtins/eventra-sdk");
+const registry_1 = require("./registry");
+async function resolvePluginExport(mod) {
+    let candidate = mod.default ?? mod;
+    if (typeof candidate === "function") {
+        candidate = candidate();
+    }
+    if (candidate && typeof candidate.then === "function") {
+        candidate = await candidate;
+    }
+    return candidate;
+}
+function pluginLoadHint(spec) {
+    if (spec.includes("plugin-vue") && !spec.includes("cli-plugin-vue")) {
+        return " Did you mean @eventra_dev/cli-plugin-vue?";
+    }
+    return "";
+}
+async function loadExternalPlugin(registry, spec) {
+    const trimmed = spec.trim();
+    if (!trimmed)
+        return;
+    let mod;
+    try {
+        mod = await Promise.resolve(`${trimmed}`).then(s => __importStar(require(s)));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to load plugin "${trimmed}": ${message}.${pluginLoadHint(trimmed)}`);
+    }
+    const candidate = await resolvePluginExport(mod);
+    if (!(0, external_1.isExternalCliPlugin)(candidate)) {
+        throw new Error(`Plugin "${trimmed}" must export a CLI plugin ({ id, includeGlobs, match, transform }).${pluginLoadHint(trimmed)}`);
+    }
+    (0, external_1.registerExternalCliPlugin)(candidate, registry);
+}
+/** Built-in plugins only (sync). Used in tests and as engine default. */
+function createBuiltinPluginRegistry() {
+    const registry = new registry_1.PluginRegistry();
+    (0, eventra_sdk_1.registerEventraSdkPlugin)(registry);
+    return registry;
+}
+/** Built-ins + plugins listed in eventra.json `plugins` array. */
+async function createPluginRegistry(config) {
+    const registry = createBuiltinPluginRegistry();
+    for (const spec of config.plugins ?? []) {
+        await loadExternalPlugin(registry, spec);
+    }
+    return registry;
+}

package/dist/plugin/registry.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginRegistry = void 0;
+const path_1 = __importDefault(require("path"));
+class PluginRegistry {
+    preprocessors = [];
+    sinkDetectors = [];
+    includePatterns = [];
+    sourceToVirtuals = new Map();
+    registerFilePreprocessor(preprocessor) {
+        if (this.preprocessors.some((p) => p.name === preprocessor.name)) {
+            throw new Error(`File preprocessor already registered: ${preprocessor.name}`);
+        }
+        this.preprocessors.push(preprocessor);
+    }
+    registerSinkDetector(detector) {
+        if (this.sinkDetectors.some((d) => d.name === detector.name)) {
+            throw new Error(`Sink detector already registered: ${detector.name}`);
+        }
+        this.sinkDetectors.push(detector);
+    }
+    registerIncludePattern(pattern) {
+        const trimmed = pattern.trim();
+        if (!trimmed)
+            return;
+        if (this.includePatterns.includes(trimmed))
+            return;
+        this.includePatterns.push(trimmed);
+    }
+    getIncludePatterns() {
+        return this.includePatterns;
+    }
+    getSinkDetectors() {
+        return this.sinkDetectors;
+    }
+    getFilePreprocessors() {
+        return this.preprocessors;
+    }
+    /** Disk paths produced by the last preprocess run for a source file (for watch unlink). */
+    getVirtualPathsForSource(fileName) {
+        const mapped = this.sourceToVirtuals.get(this.normalizePath(fileName));
+        if (mapped && mapped.length > 0) {
+            return mapped;
+        }
+        return [this.normalizePath(fileName)];
+    }
+    async preprocessFile(input) {
+        const sourceKey = this.normalizePath(input.fileName);
+        for (const preprocessor of this.preprocessors) {
+            if (!preprocessor.test(input.fileName)) {
+                continue;
+            }
+            const files = await preprocessor.process(input);
+            if (files.length > 0) {
+                this.sourceToVirtuals.set(sourceKey, files.map((file) => this.normalizePath(file.fileName)));
+                return files;
+            }
+        }
+        this.sourceToVirtuals.delete(sourceKey);
+        return [{ fileName: input.fileName, content: input.content }];
+    }
+    detectSink(context) {
+        for (const detector of this.sinkDetectors) {
+            const sink = detector.detect(context);
+            if (sink) {
+                return sink;
+            }
+        }
+        return null;
+    }
+    normalizePath(fileName) {
+        return path_1.default.resolve(fileName).replace(/\\/g, "/");
+    }
+}
+exports.PluginRegistry = PluginRegistry;

package/dist/plugin/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventra_dev/eventra-cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Static analytics event extraction CLI powered by the TypeScript compiler API",
   "license": "MIT",
   "type": "commonjs",
@@ -8,6 +8,9 @@
     "eventra": "./dist/index.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
   "files": [
     "dist",
     "README.md",