feat: add telemetry-core package for privacy-focused plugin analytics

- Create @voitanos/heft-plugins-telemetry-core package with:
  - TelemetryClient using Azure Application Insights
  - Privacy-safe context collection (OS, Node version, CI detection)
  - Message sanitization to remove PII (paths, emails, IPs, URLs)
  - Multiple opt-out mechanisms (HEFT_TELEMETRY_DISABLED, DO_NOT_TRACK, etc.)
  - Connection string injection script for CI/CD builds

- Integrate telemetry into heft-stylelint-plugin:
  - Track plugin started, completed, errors, and warnings
  - Record execution duration and outcome metrics
  - Flush telemetry with timeout to avoid blocking builds

- Add PRIVACY.md documenting data collection practices

- feat(heft-stylelint-plugin): add postinstall script for installation tracking

  Tracks when the plugin is installed via npm/pnpm/yarn. The script:
    - Sends a single telemetry event on installation
    - Respects all telemetry opt-out environment variables
    - Can be skipped in CI with SKIP_INSTALL_TELEMETRY=1
    - Never fails installation even if telemetry errors occur

- build(telemetry-core): 🏗️ npm scripts to inject connection string
  - add two scripts to create & inject variables on local builds
  - to build local, run:

      ```console
      npm run [`build` | `build:prod']
      npm run set-azappinsights-connection-string
      npm run inject-azappinsights-connection-string
      ````

- chore(telemetry-core): add conventional commit scope for telemetry-core
- feat(telemetry-core): 🍱 update env var for connection string
- docs(telemetry-core): 📝 add privcy statement
- ci(publish): 👷 update publish to be dynamic
  - previously only supported heft-*-plugins
  - now also supports telemetry-code package

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: andrewconnell

.github/workflows/plugin-publish.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - 'heft-*-plugin@v*.*.*'
+      - 'telemetry-core@v*.*.*'
 
 permissions:
   contents: write
@@ -67,15 +68,31 @@ jobs:
       - name: Extract package name, version, and determine dist-tag
         id: version
         run: |
-          # Extract from tag format: heft-stylelint-plugin@v0.1.0
+          # Extract from tag format: heft-stylelint-plugin@v0.1.0 or telemetry-core@v0.1.0
           FULL_TAG=${GITHUB_REF#refs/tags/}
           PACKAGE_SHORT_NAME=${FULL_TAG%@v*}
           VERSION=${FULL_TAG#*@v}
 
           echo "package_short_name=$PACKAGE_SHORT_NAME" >> $GITHUB_OUTPUT
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
-          echo "Publishing package from directory: heft-plugins/${PACKAGE_SHORT_NAME}"
+          # Map package short name to folder path
+          # Plugins live in heft-plugins/, libraries live in packages/
+          case $PACKAGE_SHORT_NAME in
+            heft-*-plugin)
+              PACKAGE_PATH="heft-plugins/${PACKAGE_SHORT_NAME}"
+              ;;
+            telemetry-core)
+              PACKAGE_PATH="packages/${PACKAGE_SHORT_NAME}"
+              ;;
+            *)
+              echo "Error: Unknown package '${PACKAGE_SHORT_NAME}'"
+              exit 1
+              ;;
+          esac
+
+          echo "package_path=$PACKAGE_PATH" >> $GITHUB_OUTPUT
+          echo "Publishing package from directory: $PACKAGE_PATH"
           echo "Version: $VERSION"
 
           # Determine NPM dist-tag based on version format
@@ -96,11 +113,16 @@ jobs:
       - name: Get package full name from package.json
         id: package
         run: |
-          cd heft-plugins/${{ steps.version.outputs.package_short_name }}
+          cd ${{ steps.version.outputs.package_path }}
           PACKAGE_NAME=$(node -p "require('./package.json').name")
           echo "name=$PACKAGE_NAME" >> $GITHUB_OUTPUT
           echo "Full package name: $PACKAGE_NAME"
 
+      - name: Inject AppInsights connection string into @voitanos/heft-plugins-telemetry-core
+        run: node packages/telemetry-core/scripts/inject-connection-string.js
+        env:
+          HEFT_PLUGINS_APP_INSIGHTS_CONNECTION_STRING: ${{ vars.HEFT_PLUGINS_APP_INSIGHTS_CONNECTION_STRING }}
+
       - name: Configure npm for OIDC authentication
         run: |
           npm config delete //registry.npmjs.org/:_authToken 2>/dev/null || true
@@ -109,7 +131,7 @@ jobs:
 
       - name: Publish specific package to NPM with provenance
         run: |
-          cd heft-plugins/${{ steps.version.outputs.package_short_name }}
+          cd ${{ steps.version.outputs.package_path }}
           npm publish --access public --tag ${{ steps.version.outputs.dist_tag }} --provenance
 
       - name: Create GitHub Release

.vscode/settings.json

@@ -2,5 +2,6 @@
   "conventionalCommits.scopes": [
     "publish",
     "heft-stylelint-plugin",
+    "telemetry-core"
   ]
 }

common/config/rush/pnpm-lock.yaml

@@ -1,4 +1,9 @@
 [
+  {
+    "definitionName": "individualVersion",
+    "policyName": "telemetry-core-policy",
+    "lockedMajor": 0
+  },
   {
     "definitionName": "individualVersion",
     "policyName": "heft-stylelint-plugin-policy",

common/config/rush/version-policies.json

@@ -1,7 +1,8 @@
 {
   "testMatch": ["<rootDir>/src/**/*.test.ts"],
   "moduleNameMapper": {
-    "^(\\.{1,2}/.*)\\.js$": "$1"
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+    "^@voitanos/heft-plugins-telemetry-core$": "<rootDir>/../../packages/telemetry-core/src/index.ts"
   },
   "extensionsToTreatAsEsm": [".ts"],
   "transform": {

heft-plugins/heft-stylelint-plugin/config/jest.config.json

@@ -17,6 +17,7 @@
   "typings": "lib/index.d.ts",
   "files": [
     "lib/",
+    "scripts/",
     "heft-plugin.json"
   ],
   "exports": {
@@ -28,9 +29,11 @@
   "scripts": {
     "build": "heft build --clean",
     "test": "heft test --clean",
-    "start": "heft build-watch"
+    "start": "heft build-watch",
+    "postinstall": "node scripts/postinstall.js"
   },
   "dependencies": {
+    "@voitanos/heft-plugins-telemetry-core": "0.1.0",
     "stylelint": "16.25.0",
     "stylelint-config-standard-scss": "16.0.0"
   },

heft-plugins/heft-stylelint-plugin/package.json

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script to track plugin installations.
+ *
+ * This script runs automatically after the package is installed via npm/pnpm/yarn.
+ * It sends a single telemetry event to track that the plugin was installed.
+ *
+ * Telemetry can be disabled by setting any of these environment variables:
+ *   - HEFT_TELEMETRY_DISABLED=1
+ *   - DISABLE_TELEMETRY=1
+ *   - DO_NOT_TRACK=1
+ *   - TELEMETRY_DISABLED=1
+ *
+ * In CI environments, you can also set SKIP_INSTALL_TELEMETRY=1 to skip this script.
+ */
+
+import { TelemetryClient, isTelemetryDisabled } from '@voitanos/heft-plugins-telemetry-core';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+
+// Get package info
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJsonPath = path.resolve(__dirname, '../package.json');
+
+async function trackInstallation() {
+  // Skip if telemetry is disabled
+  if (isTelemetryDisabled()) {
+    return;
+  }
+
+  // Skip if explicitly disabled for installs (useful in CI during development)
+  if (process.env.SKIP_INSTALL_TELEMETRY === '1') {
+    return;
+  }
+
+  try {
+    // Read package info
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    const pluginName = packageJson.name;
+    const pluginVersion = packageJson.version;
+
+    // Create telemetry client
+    const telemetry = new TelemetryClient({
+      pluginName,
+      pluginVersion,
+    });
+
+    // Track installation
+    telemetry.trackPluginInstalled();
+
+    // Flush with a short timeout (don't delay install too long)
+    await Promise.race([
+      telemetry.flush(),
+      new Promise(resolve => setTimeout(resolve, 3000)),
+    ]);
+  } catch {
+    // Silently ignore any errors - telemetry should never break installation
+  }
+}
+
+// Run the tracking
+trackInstallation().catch(() => {
+  // Silently ignore - telemetry errors should never break installation
+});

heft-plugins/heft-stylelint-plugin/scripts/postinstall.js

@@ -4,55 +4,116 @@ import type {
   HeftConfiguration,
   IHeftTaskSession,
   IHeftTaskPlugin,
-  IHeftTaskRunHookOptions,
-  IScopedLogger
 } from '@rushstack/heft';
 import stylelint from 'stylelint';
+import { TelemetryClient, PluginOutcome } from '@voitanos/heft-plugins-telemetry-core';
 
 export const PLUGIN_NAME: 'stylelint-plugin' = 'stylelint-plugin';
+const PACKAGE_NAME = '@voitanos/heft-stylelint-plugin';
+
+/**
+ * Get the package version for telemetry.
+ * Note: This reads from package.json at runtime to get the actual deployed version.
+ */
+function getPackageVersion(buildFolderPath: string): string {
+  try {
+    // When installed as a dependency, the package.json will be in the package root
+    const packageJsonPath = path.resolve(buildFolderPath, 'node_modules', PACKAGE_NAME, 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return packageJson.version;
+  } catch {
+    // Fallback: return a default version if package.json can't be read
+    return '0.0.0-unknown';
+  }
+}
 
 export interface IStylelintPluginOptions { }
 
 export default class StylelintPlugin implements IHeftTaskPlugin<IStylelintPluginOptions> {
+  private _telemetry: TelemetryClient | undefined;
 
   public apply(taskSession: IHeftTaskSession, heftConfiguration: HeftConfiguration, options: IStylelintPluginOptions): void {
     taskSession.hooks.run.tapPromise({
       name: PLUGIN_NAME,
       stage: Number.MIN_SAFE_INTEGER
     }, async () => {
-      // output version of stylelint
-      const stylelintPkgPath = path.join(heftConfiguration.buildFolderPath, 'node_modules/stylelint/package.json');
-      const stylelintPkg = JSON.parse(readFileSync(stylelintPkgPath, 'utf-8'));
-      taskSession.logger.terminal.writeLine(`Using Stylelint version ${stylelintPkg.version}`)
-      if (taskSession.parameters.verbose) {
-        taskSession.logger.terminal.writeVerboseLine(`path ${heftConfiguration.buildFolderPath}`)
-      }
+      const startTime = Date.now();
+      let warningCount = 0;
 
-      // run stylelint on SCSS & CSS files using Node.js API
-      if (taskSession.parameters.verbose) {
-        taskSession.logger.terminal.writeVerboseLine('linting...');
-      }
-      const result = await stylelint.lint({
-        files: 'src/**/*.scss',
-        configFile: path.join(heftConfiguration.buildFolderPath, '.stylelintrc'),
-        cwd: heftConfiguration.buildFolderPath
-      });
-
-      if (taskSession.parameters.verbose) {
-        taskSession.logger.terminal.writeVerboseLine(`results: ${JSON.stringify(result)}`);
+      // Initialize telemetry lazily (needs buildFolderPath for version detection)
+      if (!this._telemetry) {
+        this._telemetry = new TelemetryClient({
+          pluginName: PACKAGE_NAME,
+          pluginVersion: getPackageVersion(heftConfiguration.buildFolderPath),
+        });
       }
 
-      // process results
-      if (result.errored || result.results.some(r => r.warnings.length > 0)) {
-        for (const fileResult of result.results) {
-          if (fileResult.warnings.length > 0 && fileResult.source) {
-            for (const warning of fileResult.warnings) {
-              const relativePath = path.relative(heftConfiguration.buildFolderPath, fileResult.source);
-              const formattedWarning = `${relativePath}:${warning.line}:${warning.column} - (${warning.rule}) ${warning.text}`;
-              taskSession.logger.terminal.writeWarningLine(formattedWarning);
+      // Track plugin start
+      this._telemetry.trackPluginStarted();
+
+      try {
+        // output version of stylelint
+        const stylelintPkgPath = path.join(heftConfiguration.buildFolderPath, 'node_modules/stylelint/package.json');
+        const stylelintPkg = JSON.parse(readFileSync(stylelintPkgPath, 'utf-8'));
+        taskSession.logger.terminal.writeLine(`Using Stylelint version ${stylelintPkg.version}`)
+        if (taskSession.parameters.verbose) {
+          taskSession.logger.terminal.writeVerboseLine(`path ${heftConfiguration.buildFolderPath}`)
+        }
+
+        // run stylelint on SCSS & CSS files using Node.js API
+        if (taskSession.parameters.verbose) {
+          taskSession.logger.terminal.writeVerboseLine('linting...');
+        }
+        const result = await stylelint.lint({
+          files: 'src/**/*.scss',
+          configFile: path.join(heftConfiguration.buildFolderPath, '.stylelintrc'),
+          cwd: heftConfiguration.buildFolderPath
+        });
+
+        if (taskSession.parameters.verbose) {
+          taskSession.logger.terminal.writeVerboseLine(`results: ${JSON.stringify(result)}`);
+        }
+
+        // process results
+        if (result.errored || result.results.some(r => r.warnings.length > 0)) {
+          for (const fileResult of result.results) {
+            if (fileResult.warnings.length > 0 && fileResult.source) {
+              for (const warning of fileResult.warnings) {
+                warningCount++;
+                const relativePath = path.relative(heftConfiguration.buildFolderPath, fileResult.source);
+                const formattedWarning = `${relativePath}:${warning.line}:${warning.column} - (${warning.rule}) ${warning.text}`;
+                taskSession.logger.terminal.writeWarningLine(formattedWarning);
+
+                // Track warning (category is the stylelint rule)
+                this._telemetry.trackPluginWarning(
+                  warning.rule || 'unknown',
+                  `Stylelint warning: ${warning.text}`
+                );
+              }
             }
           }
         }
+
+        // Track successful completion
+        const duration = Date.now() - startTime;
+        const outcome = warningCount > 0 ? PluginOutcome.Warning : PluginOutcome.Success;
+        this._telemetry.trackPluginCompleted(duration, outcome, warningCount);
+
+      } catch (error) {
+        // Track error
+        const duration = Date.now() - startTime;
+        this._telemetry.trackPluginError(error, duration);
+        this._telemetry.trackPluginCompleted(duration, PluginOutcome.Error, warningCount);
+        throw error;
+
+      } finally {
+        // Flush telemetry with timeout to avoid blocking
+        await Promise.race([
+          this._telemetry.flush(),
+          new Promise(resolve => setTimeout(resolve, 2000))
+        ]).catch(() => {
+          // Silently ignore flush errors
+        });
       }
     });
   }