@octaviaflow/telemetry 1.0.0

package/README.md

@@ -0,0 +1,260 @@
+# Octaviaflow Telemetry Collector
+
+> JavaScript telemetry collection tooling for octaviaflow projects
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NPM version](https://img.shields.io/npm/v/%40octaviaflow/telemetry-collector.svg)](https://npmjs.org/package/@octaviaflow/telemetry-collector)
+
+## Overview
+
+Octaviaflow Telemetry Collector is a powerful analytics tool that captures anonymized usage data from JavaScript/TypeScript projects. It supports multiple data collection scopes including NPM dependencies, JSX components, JavaScript functions, and Web Components.
+
+### Key Features
+
+- **File-based Storage**: Store telemetry data in JSON files ready for MongoDB Atlas import
+- **Multiple Collection Scopes**: NPM, JSX, JavaScript, and Web Components
+- **Privacy-First**: Anonymized data collection with configurable allowlists
+- **MongoDB Ready**: Generated files are formatted for direct MongoDB import
+- **CLI Tool**: Easy-to-use command-line interface
+
+## Installation
+
+```bash
+npm install @octaviaflow/telemetry-collector
+```
+
+## Quick Start
+
+### 1. Create Configuration File
+
+Create a `telemetry.yml` file in your project root:
+
+```yaml
+# yaml-language-server: $schema=https://unpkg.com/@octaviaflow/telemetry-config-schema@1/dist/config.schema.json
+version: 1
+projectId: 'my-awesome-project'
+name: 'my-awesome-project'
+storage:
+  type: 'file'
+  file:
+    directory: './telemetry-logs'
+    fileNamePattern: 'octaviaflow-telemetry-{timestamp}.json'
+    maxFileSizeMB: 10
+collect:
+  npm:
+    dependencies:
+  jsx:
+    elements:
+      allowedAttributeNames: ['size', 'variant']
+      allowedAttributeStringValues: ['small', 'medium', 'large']
+```
+
+### 2. Run Collection
+
+```bash
+# Basic usage
+npx octaviaflow-telemetry --config ./telemetry.yml
+
+# With verbose output
+npx octaviaflow-telemetry --config ./telemetry.yml --verbose
+
+# Dry run (no data stored)
+npx octaviaflow-telemetry --config ./telemetry.yml --dry-run
+```
+
+### 3. Import to MongoDB Atlas
+
+After collection, import the generated JSON files to MongoDB Atlas:
+
+```bash
+mongoimport --uri "mongodb+srv://user:pass@cluster.mongodb.net/database" \
+  --collection telemetry \
+  --file ./telemetry-logs/octaviaflow-telemetry-2025-01-01T10-00-00-000Z.json
+```
+
+## Configuration
+
+### Storage Options
+
+#### File Storage (Current)
+
+```yaml
+storage:
+  type: 'file'
+  file:
+    directory: './telemetry-logs'           # Directory to store files
+    fileNamePattern: 'octaviaflow-telemetry-{timestamp}.json'  # File naming pattern
+    maxFileSizeMB: 10                       # Max file size before rotation
+    compress: false                         # Enable compression (future)
+```
+
+#### MongoDB Storage (Future)
+
+```yaml
+storage:
+  type: 'mongodb'
+  mongodb:
+    connectionString: 'mongodb+srv://user:pass@cluster.mongodb.net'
+    database: 'telemetry'
+    collection: 'metrics'
+```
+
+### Collection Scopes
+
+#### NPM Dependencies
+
+Captures package dependency information:
+
+```yaml
+collect:
+  npm:
+    dependencies:  # Captures all dependencies and versions
+```
+
+#### JSX Components
+
+Captures React component usage:
+
+```yaml
+collect:
+  jsx:
+    elements:
+      allowedAttributeNames:
+        - 'size'
+        - 'variant'
+        - 'color'
+      allowedAttributeStringValues:
+        - 'small'
+        - 'medium'
+        - 'large'
+```
+
+#### JavaScript Functions
+
+Captures function calls and arguments:
+
+```yaml
+collect:
+  js:
+    tokens:  # Captures imported tokens
+    functions:
+      allowedArgumentStringValues:
+        - 'debug'
+        - 'info'
+        - 'error'
+```
+
+#### Web Components
+
+Captures Web Component usage:
+
+```yaml
+collect:
+  wc:
+    elements:
+      allowedAttributeNames:
+        - 'type'
+        - 'disabled'
+      allowedAttributeStringValues:
+        - 'button'
+        - 'submit'
+```
+
+## CLI Options
+
+```bash
+octaviaflow-telemetry [options]
+
+Options:
+  -c, --config <path>  Path to telemetry configuration file (default: "./telemetry.yml")
+  -v, --verbose        Enable verbose logging
+  --dry-run           Perform a dry run without storing data
+  -h, --help          Display help for command
+  --version           Display version number
+```
+
+## Data Format
+
+Generated JSON files contain telemetry data in MongoDB-ready format:
+
+```json
+{
+  "_id": "507f1f77bcf86cd799439011",
+  "timestamp": "2025-01-01T10:00:00.000Z",
+  "projectId": "my-awesome-project",
+  "scope": "jsx",
+  "metric": "jsx.element",
+  "data": {
+    "elements": [
+      {
+        "name": "Button",
+        "attributes": { "size": "large", "variant": "primary" },
+        "moduleSpecifier": "@octaviaflow/ui"
+      }
+    ]
+  },
+  "metadata": {
+    "collectionTimestamp": "2025-01-01T10:00:00.000Z",
+    "storageType": "file",
+    "collectionMethod": "jsx-analysis"
+  }
+}
+```
+
+## Integration with Package
+
+Add telemetry collection to your package's `postinstall` script:
+
+```json
+{
+  "scripts": {
+    "postinstall": "octaviaflow-telemetry --config ./telemetry.yml"
+  }
+}
+```
+
+## Privacy and Data Collection
+
+- **Anonymized by Default**: All sensitive data is anonymized unless specifically allowlisted
+- **Configurable Collection**: Only collect data you explicitly configure
+- **Local Storage**: Data is stored locally in files, giving you full control
+- **No External Calls**: No data is sent to external servers automatically
+
+## MongoDB Atlas Import
+
+### Prepare Data for Import
+
+The collector can prepare all collected data for MongoDB import:
+
+```javascript
+import { FileStorage } from '@octaviaflow/telemetry-collector';
+
+const storage = new FileStorage({ directory: './telemetry-logs' });
+const importFile = await storage.prepareForMongoImport('./mongodb-ready.json');
+console.log('Ready for import:', importFile);
+```
+
+### Import Commands
+
+```bash
+# Import single file
+mongoimport --uri "your-connection-string" \
+  --collection telemetry \
+  --file ./telemetry-logs/octaviaflow-telemetry-2025-01-01T10-00-00-000Z.json
+
+# Import all files
+for file in ./telemetry-logs/*.json; do
+  mongoimport --uri "your-connection-string" \
+    --collection telemetry \
+    --file "$file"
+done
+```
+
+## Related Packages
+
+- [`@octaviaflow/telemetry-config-schema`](../octaviaflow-telemetry-config-schema) - Configuration schema and validation
+- [`@octaviaflow/telemetry-attributes`](../octaviaflow-telemetry-attributes) - Telemetry attribute definitions
+
+## License
+
+MIT © octaviaflow

package/dist/collect.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/*
+ * Copyright OctaviaFlow 2025
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Command } from 'commander';
+import { TelemetryCollector } from './core/telemetry-collector.js';
+import { loadConfig } from './config/config-loader.js';
+const program = new Command();
+program
+    .name('octaviaflow-telemetry')
+    .description('OctaviaFlow Telemetry Collection Tool')
+    .version('1.0.0')
+    .option('-c, --config <path>', 'path to telemetry configuration file', './telemetry.yml')
+    .option('-v, --verbose', 'enable verbose logging')
+    .option('--dry-run', 'perform a dry run without storing data')
+    .parse();
+const options = program.opts();
+async function main() {
+    try {
+        console.log('🚀 Starting OctaviaFlow Telemetry Collection...');
+        // Load configuration
+        const config = await loadConfig(options.config);
+        if (options.verbose) {
+            console.log('📋 Configuration loaded:', JSON.stringify(config, null, 2));
+        }
+        // Create collector instance
+        const collector = new TelemetryCollector(config, {
+            verbose: options.verbose,
+            dryRun: options.dryRun
+        });
+        // Run collection
+        await collector.collect();
+        console.log('✅ Telemetry collection completed successfully');
+    }
+    catch (error) {
+        console.error('❌ Telemetry collection failed:', error);
+        process.exit(1);
+    }
+}
+main().catch(console.error);
+//# sourceMappingURL=collect.js.map

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@octaviaflow/telemetry",
+  "description": "JavaScript telemetry collection tooling for OctaviaFlow projects",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "author": "OctaviaFlow",
+  "keywords": [
+    "octaviaflow",
+    "telemetry",
+    "metrics",
+    "analytics",
+    "javascript",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/OctaviaFlow/OctaviaFlow-Design-System#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OctaviaFlow/OctaviaFlow-Design-System.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OctaviaFlow/OctaviaFlow-Design-System/issues"
+  },
+  "type": "module",
+  "bin": {
+    "octaviaflow-telemetry": "dist/collect.js"
+  },
+  "files": [
+    "dist/background-process.js",
+    "dist/collect.js",
+    "dist/spawn-background-process.js",
+    "dist/notify.js"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run compile && npm run compile:collect && npm run bundle",
+    "bundle": "node esbuild.js",
+    "clean": "rimraf dist .test-coverage",
+    "compile": "tsc",
+    "compile:collect": "tsc --project ./tsconfig.collect.json",
+    "compile:watch": "tsc --watch",
+    "lint": "scripts/lint",
+    "lint:fix": "scripts/lint_and_fix",
+    "prepare": "husky",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest --coverage"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.4.1",
+    "@commitlint/config-conventional": "^19.4.1",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.4.0",
+    "@octaviaflow/telemetry-attributes": "workspace:*",
+    "@octaviaflow/telemetry-config-schema": "workspace:*",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.53.0",
+    "@opentelemetry/otlp-exporter-base": "^0.53.0",
+    "@opentelemetry/resources": "^1.26.0",
+    "@opentelemetry/sdk-metrics": "^1.26.0",
+    "@opentelemetry/semantic-conventions": "^1.27.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/lodash": "^4.17.7",
+    "@types/mock-fs": "^4.13.4",
+    "@types/node": "^20.16.5",
+    "@types/semver": "^7.5.8",
+    "@vitest/coverage-v8": "^1.6.0",
+    "@vitest/eslint-plugin": "^1.0.1",
+    "ajv": "^8.17.1",
+    "ci-info": "^4.0.0",
+    "commander": "^12.1.0",
+    "domhandler": "^5.0.3",
+    "domutils": "^3.2.2",
+    "esbuild": "^0.25.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-import": "^2.30.0",
+    "eslint-plugin-jsdoc": "^48.11.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-notice": "^0.9.10",
+    "eslint-plugin-promise": "^6.6.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "globals": "^15.9.0",
+    "htmlparser2": "^10.0.0",
+    "husky": "^9.1.5",
+    "js-yaml": "^4.1.0",
+    "lint-staged": "^15.2.10",
+    "lodash": "^4.17.21",
+    "mock-fs": "^5.4.0",
+    "object-scan": "^19.0.5",
+    "prettier": "^3.3.3",
+    "reflect-metadata": "^0.2.1",
+    "rimraf": "^5.0.10",
+    "semver": "^7.6.3",
+    "ts-json-schema-generator": "^1.5.1",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^7.18.0",
+    "vite": "^5.4.3",
+    "vitest": "^1.6.0"
+  }
+}