@eventra_dev/eventra-cli 0.0.1

package/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release CLI
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: npm-publish
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - run: pnpm install --no-frozen-lockfile
+
+      - name: Build CLI
+        run: pnpm build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          EVENTRA_ENDPOINT: ${{ secrets.EVENTRA_ENDPOINT }}

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Eventra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software.

package/README.md

@@ -0,0 +1,310 @@
+# Eventra CLI
+
+Eventra CLI automatically discovers feature usage events in your codebase and syncs them with Eventra.
+
+It helps you:
+
+- Automatically discover events
+- Detect wrapper components
+- Keep events in sync
+- Register features in Eventra
+- Works with any JS framework (React, Vue, Svelte, Node, etc.)
+
+---
+
+# Installation
+
+Using npm
+
+```bash
+npm install -D @eventra_dev/eventra-cli
+```
+
+Using pnpm
+
+```bash
+pnpm add -D @eventra_dev/eventra-cli
+```
+
+Using npx
+
+```bash
+npx eventra init
+```
+
+---
+
+# Quick Start
+
+```bash
+eventra init
+eventra sync
+eventra send
+```
+
+---
+
+# Commands
+
+## eventra init
+
+Creates `eventra.json` config file.
+
+```bash
+eventra init
+```
+
+Example:
+
+```json
+{
+  "apiKey": "",
+  "events": [],
+  "wrappers": [],
+  "sync": {
+    "include": ["**/*.{ts,tsx,js,jsx}"],
+    "exclude": ["node_modules", "dist", ".next", ".git"]
+  }
+}
+```
+
+---
+
+## eventra sync
+
+Scans your project and finds all tracking events automatically.
+
+```bash
+eventra sync
+```
+
+Eventra CLI searches for:
+
+### Direct tracking calls
+
+```ts
+tracker.track("feature_created")
+```
+
+### Wrapper components
+
+```tsx
+<TrackedButton event="feature_created" />
+```
+
+### Custom wrappers
+
+```tsx
+<MyComponent event="user_signup" />
+```
+
+---
+
+# Wrapper detection
+
+If you use wrapper components, Eventra CLI will ask:
+
+```
+Use wrapper components? (Y/n)
+```
+
+Then:
+
+```
+Wrapper component name:
+> TrackedButton
+```
+
+```
+Event prop name:
+> event
+```
+
+You can add multiple wrappers:
+
+```
+Add another wrapper? (y/N)
+```
+
+Example config:
+
+```json
+{
+  "wrappers": [
+    {
+      "name": "TrackedButton",
+      "prop": "event"
+    },
+    {
+      "name": "Feature",
+      "prop": "name"
+    }
+  ]
+}
+```
+
+---
+
+# Example sync output
+
+```bash
+eventra sync
+```
+
+Output:
+
+```
+Scanning project...
+
+Found events:
+
+- landing_login_clicked
+- feature_created
+- user_signup
+```
+
+---
+
+# Diff detection
+
+Eventra CLI automatically detects changes:
+
+```
+Changes:
+
+New events:
++ landing_signup_clicked
+
+Removed events:
+- old_event
+```
+
+---
+
+## eventra send
+
+Send events to Eventra backend.
+
+```bash
+eventra send
+```
+
+If API key is missing:
+
+```
+API key is not configured
+Enter your API key:
+```
+
+Events are registered in Eventra.
+
+Example output:
+
+```
+Events registered successfully
+
+New events:
++ feature_created
+```
+
+---
+
+# Example workflow
+
+```bash
+eventra init
+eventra sync
+eventra send
+```
+
+---
+
+# Configuration
+
+eventra.json
+
+```json
+{
+  "apiKey": "",
+  "events": [],
+  "wrappers": [],
+  "sync": {
+    "include": ["**/*.{ts,tsx,js,jsx}"],
+    "exclude": ["node_modules", "dist", ".next", ".git"]
+  }
+}
+```
+
+---
+
+# Supported patterns
+
+## Direct tracking
+
+```ts
+tracker.track("feature_created")
+```
+
+## Wrapper components
+
+```tsx
+<TrackedButton event="feature_created" />
+```
+
+## Custom wrapper props
+
+```tsx
+<MyComponent eventName="user_signup" />
+```
+
+---
+
+# Supported frameworks
+
+Eventra CLI works with:
+
+- React
+- Next.js
+- Vue
+- Nuxt
+- Svelte
+- Astro
+- Node.js
+- Express
+- NestJS
+- Vanilla JavaScript
+
+---
+
+# Important
+
+Eventra CLI detects only string literals:
+
+Supported:
+
+```ts
+track("event_name")
+```
+
+Not supported:
+
+```ts
+track(eventName)
+track(EVENTS.event)
+track(getEvent())
+```
+
+This ensures reliable and predictable event detection.
+
+---
+
+# Requirements
+
+- Node.js 18+
+- JavaScript / TypeScript project
+
+---
+
+# License
+
+MIT

package/dist/commands/init.js

@@ -0,0 +1,42 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const config_1 = require("../utils/config");
+async function init() {
+    console.log(chalk_1.default.blue("Initializing Eventra..."));
+    const configPath = path_1.default.join(process.cwd(), config_1.CONFIG_NAME);
+    if (await fs_extra_1.default.pathExists(configPath)) {
+        console.log(chalk_1.default.yellow("eventra.json already exists"));
+        return;
+    }
+    const answers = await inquirer_1.default.prompt([
+        {
+            type: "input",
+            name: "apiKey",
+            message: "API Key (optional):"
+        }
+    ]);
+    const config = {
+        apiKey: answers.apiKey || "",
+        events: [],
+        wrappers: [],
+        sync: {
+            include: ["**/*.{ts,tsx,js,jsx}"],
+            exclude: [
+                "node_modules",
+                "dist",
+                ".next",
+                ".git"
+            ]
+        }
+    };
+    await (0, config_1.saveConfig)(config);
+    console.log(chalk_1.default.green("eventra.json created"));
+}

package/dist/commands/send.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.send = send;
+const chalk_1 = __importDefault(require("chalk"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const config_1 = require("../utils/config");
+const EVENTRA_ENDPOINT = process.env.EVENTRA_ENDPOINT ?? "";
+const CLI_VERSION = "0.0.1";
+async function send() {
+    let config = await (0, config_1.loadConfig)();
+    if (!config) {
+        console.log(chalk_1.default.red("eventra.json not found. Run 'eventra init'"));
+        return;
+    }
+    let apiKey = config.apiKey;
+    if (!apiKey) {
+        const answers = await inquirer_1.default.prompt([
+            {
+                type: "input",
+                name: "apiKey",
+                message: "Enter your API key:"
+            }
+        ]);
+        apiKey = answers.apiKey;
+        config.apiKey = apiKey;
+        await (0, config_1.saveConfig)(config);
+        console.log(chalk_1.default.green("API key saved"));
+    }
+    if (!config.events.length) {
+        console.log(chalk_1.default.yellow("No events found. Run 'eventra sync'"));
+        return;
+    }
+    console.log(chalk_1.default.blue("Sending events..."));
+    try {
+        const res = await fetch(EVENTRA_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": apiKey
+            },
+            body: JSON.stringify({
+                events: config.events,
+                cli: {
+                    name: "@eventra_dev/eventra-cli",
+                    version: CLI_VERSION,
+                    runtime: "node"
+                }
+            })
+        });
+        if (res.status >= 400) {
+            console.log(chalk_1.default.red(`Failed (${res.status})`));
+            return;
+        }
+        const data = await res.json();
+        console.log(chalk_1.default.green("Events registered successfully"));
+        if (data.created?.length) {
+            console.log(chalk_1.default.green("\nNew events:"));
+            data.created.forEach((e) => console.log(chalk_1.default.green(`+ ${e}`)));
+        }
+    }
+    catch {
+        console.log(chalk_1.default.red("Network error"));
+    }
+}

package/dist/commands/sync.js

@@ -0,0 +1,216 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sync = sync;
+const ts_morph_1 = require("ts-morph");
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const chalk_1 = __importDefault(require("chalk"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const config_1 = require("../utils/config");
+async function sync() {
+    let config = await (0, config_1.loadConfig)();
+    if (!config) {
+        console.log(chalk_1.default.red("Run 'eventra init' first"));
+        return;
+    }
+    const events = new Set();
+    const project = new ts_morph_1.Project();
+    console.log(chalk_1.default.blue("Scanning project..."));
+    const files = await (0, fast_glob_1.default)(config.sync.include, {
+        ignore: config.sync.exclude
+    });
+    // track()
+    for (const file of files) {
+        const sourceFile = project.addSourceFileAtPath(file);
+        const calls = sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression);
+        for (const call of calls) {
+            const expression = call.getExpression();
+            if (expression.getKind() ===
+                ts_morph_1.SyntaxKind.PropertyAccessExpression) {
+                const prop = expression.asKind(ts_morph_1.SyntaxKind.PropertyAccessExpression);
+                if (!prop)
+                    continue;
+                if (prop.getName() !== "track")
+                    continue;
+                const args = call.getArguments();
+                const eventArg = args[0];
+                if (!eventArg)
+                    continue;
+                let event = null;
+                // "event"
+                if (eventArg.getKind() ===
+                    ts_morph_1.SyntaxKind.StringLiteral) {
+                    event =
+                        eventArg
+                            .asKindOrThrow(ts_morph_1.SyntaxKind.StringLiteral)
+                            .getLiteralText();
+                }
+                // `event`
+                if (eventArg.getKind() ===
+                    ts_morph_1.SyntaxKind.NoSubstitutionTemplateLiteral) {
+                    event =
+                        eventArg
+                            .asKindOrThrow(ts_morph_1.SyntaxKind.NoSubstitutionTemplateLiteral)
+                            .getLiteralText();
+                }
+                if (event) {
+                    events.add(event);
+                }
+            }
+        }
+    }
+    console.log(chalk_1.default.green(`Found ${events.size} track events`));
+    // wrappers setup
+    if (!config.wrappers.length) {
+        const { useWrapper } = await inquirer_1.default.prompt([
+            {
+                type: "confirm",
+                name: "useWrapper",
+                message: "Use wrapper components?",
+                default: true
+            }
+        ]);
+        if (useWrapper) {
+            const wrappers = [];
+            let addMore = true;
+            while (addMore) {
+                const answers = await inquirer_1.default.prompt([
+                    {
+                        type: "input",
+                        name: "name",
+                        message: "Wrapper component name:"
+                    },
+                    {
+                        type: "input",
+                        name: "prop",
+                        message: "Event prop name:"
+                    }
+                ]);
+                wrappers.push({
+                    name: answers.name,
+                    prop: answers.prop
+                });
+                const more = await inquirer_1.default.prompt([
+                    {
+                        type: "confirm",
+                        name: "more",
+                        message: "Add another wrapper?",
+                        default: false
+                    }
+                ]);
+                addMore = more.more;
+            }
+            config.wrappers = wrappers;
+        }
+    }
+    // scan wrappers
+    if (config.wrappers.length) {
+        console.log(chalk_1.default.blue("Scanning wrappers..."));
+        for (const file of files) {
+            const sourceFile = project.addSourceFileAtPath(file);
+            const elements = [
+                ...sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxOpeningElement),
+                ...sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.JsxSelfClosingElement)
+            ];
+            for (const element of elements) {
+                const tagName = element
+                    .getTagNameNode()
+                    .getText()
+                    .toLowerCase();
+                for (const wrapper of config.wrappers) {
+                    if (tagName !==
+                        wrapper.name.toLowerCase())
+                        continue;
+                    const attrs = element.getAttributes();
+                    for (const attr of attrs) {
+                        if (attr.getKind() !==
+                            ts_morph_1.SyntaxKind.JsxAttribute)
+                            continue;
+                        const attrNode = attr.asKind(ts_morph_1.SyntaxKind.JsxAttribute);
+                        if (!attrNode)
+                            continue;
+                        const attrName = attrNode
+                            .getNameNode()
+                            .getText()
+                            .toLowerCase();
+                        if (attrName !==
+                            wrapper.prop.toLowerCase())
+                            continue;
+                        const initializer = attrNode.getInitializer();
+                        if (!initializer)
+                            continue;
+                        let value = null;
+                        // event="signup"
+                        if (initializer.getKind() ===
+                            ts_morph_1.SyntaxKind.StringLiteral) {
+                            value =
+                                initializer
+                                    .asKindOrThrow(ts_morph_1.SyntaxKind.StringLiteral)
+                                    .getLiteralText();
+                        }
+                        // event={"signup"}
+                        if (initializer.getKind() ===
+                            ts_morph_1.SyntaxKind.JsxExpression) {
+                            const expr = initializer
+                                .asKindOrThrow(ts_morph_1.SyntaxKind.JsxExpression)
+                                .getExpression();
+                            if (expr?.getKind() ===
+                                ts_morph_1.SyntaxKind.StringLiteral) {
+                                value =
+                                    expr
+                                        .asKindOrThrow(ts_morph_1.SyntaxKind.StringLiteral)
+                                        .getLiteralText();
+                            }
+                        }
+                        if (value) {
+                            events.add(value);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // results
+    const list = [...events].sort();
+    console.log("");
+    console.log(chalk_1.default.green("Found events:"));
+    list.forEach((e) => console.log(chalk_1.default.gray(`- ${e}`)));
+    console.log("");
+    // diff
+    const previous = config.events ?? [];
+    const added = list.filter((e) => !previous.includes(e));
+    const removed = previous.filter((e) => !list.includes(e));
+    if (added.length || removed.length) {
+        console.log(chalk_1.default.blue("Changes:"));
+        if (added.length) {
+            console.log(chalk_1.default.green("New events:"));
+            added.forEach((e) => console.log(chalk_1.default.green(`+ ${e}`)));
+        }
+        if (removed.length) {
+            console.log(chalk_1.default.red("Removed events:"));
+            removed.forEach((e) => console.log(chalk_1.default.red(`- ${e}`)));
+        }
+        console.log("");
+    }
+    else {
+        console.log(chalk_1.default.gray("No changes detected"));
+    }
+    // confirm
+    const { confirm } = await inquirer_1.default.prompt([
+        {
+            type: "confirm",
+            name: "confirm",
+            message: "Sync these events?",
+            default: true
+        }
+    ]);
+    if (!confirm) {
+        console.log(chalk_1.default.yellow("Sync cancelled"));
+        return;
+    }
+    config.events = list;
+    await (0, config_1.saveConfig)(config);
+    console.log(chalk_1.default.green("eventra.json updated"));
+}