merge: v1.8.0 — Telemetry (PostHog)

Author: SoftDryzz

README.md

@@ -273,6 +273,7 @@ chmod +x scripts/install.sh && ./scripts/install.sh
 | `pm export` | Export all projects to a portable JSON file |
 | `pm export <names...> [--file <path>]` | Export selected projects to a custom file |
 | `pm import <file>` | Import projects from an exported JSON file |
+| `pm config telemetry [on\|off]` | Enable or disable anonymous telemetry |
 | `pm help` | Show help |
 | `pm version` | Show version |
 
@@ -476,6 +477,32 @@ Projects are saved in:
 
 ---
 
+## 📊 Telemetry
+
+ProjectManager collects **anonymous** usage statistics to improve the tool. Telemetry is **opt-in** — disabled by default.
+
+### What is collected
+- PM version, OS name/version, Java version
+- Command name (e.g., `build`, `test`) — **no arguments**
+- Number of registered projects — **no project names or paths**
+
+### What is NOT collected
+- Project names, file paths, source code
+- Environment variables, secrets, credentials
+- Personal information, IP addresses, usernames
+
+### Control
+```bash
+pm config telemetry on       # Enable
+pm config telemetry off      # Disable
+pm config telemetry          # Check status
+```
+
+On first run, PM asks: `Enable telemetry? (y/n)` — default is **no**.
+Delete `~/.projectmanager/config.json` to reset all preferences.
+
+---
+
 ## 🚧 Roadmap
 
 ### ✅ Completed
@@ -490,9 +517,10 @@ Projects are saved in:
 - **Lint & Format** — `pm lint` / `pm fmt` auto-detect and run linters/formatters (ESLint, Prettier, Clippy, gofmt, Ruff, Black, Checkstyle, Spotless, and more)
 - **Workspaces** — `pm modules` detects monorepo structures (Cargo, npm/pnpm/yarn, Gradle, Go), multi-language detection, `pm build --all` / `pm test --all`
 - **Environments** — `pm env files/show/switch` for .env file discovery, secret scanning (AWS, GitHub, Slack tokens), `pm migrate` for database migration tools (Prisma, Alembic, Diesel, Flyway, Liquibase, SQLx)
-- **Reliability** — Atomic writes, backup/recovery, directory validation, download integrity, 748 tests
+- **Telemetry** — Opt-in anonymous usage analytics via PostHog, `pm config telemetry on/off`, privacy-first design
+- **Reliability** — Atomic writes, backup/recovery, directory validation, download integrity, 763 tests
 
-> Latest release: **v1.7.1** (Environments, Secrets & Databases) — Full version history in [ROADMAP.md](ROADMAP.md)
+> Latest release: **v1.8.0** (Telemetry) — Full version history in [ROADMAP.md](ROADMAP.md)
 
 ### 💡 Future Ideas
 - [ ] Project groups (`pm group create backend api-users product-service`, `pm run-group backend`)

ROADMAP.md

@@ -355,12 +355,16 @@ Export all or selected projects to a portable JSON file and import them back on
 ## v1.8.0 — Telemetry
 
 ### Anonymous usage analytics (opt-in)
-- First-run prompt: "Allow anonymous usage statistics? (y/n)"
-- Tracks: version, OS, command frequency, project count
-- `pm config telemetry on/off` to toggle at any time
-- Privacy-first: no personal data, no project names, no paths
-- Transparent: documented in README and `pm help`
-- Backend: PostHog Cloud (free tier)
+
+| Feature | Status |
+|---------|--------|
+| First-run consent prompt (opt-in, default disabled) | ✅ Done |
+| Track: version, OS, command name, project count | ✅ Done |
+| `pm config telemetry on/off` to toggle at any time | ✅ Done |
+| Privacy-first: no personal data, no project names, no paths | ✅ Done |
+| Transparent: documented in README, User-Guide, and `pm help` | ✅ Done |
+| Backend: PostHog Cloud (free tier) | ✅ Done |
+| Shell completions for config command | ✅ Done |
 
 ---
 

User-Guide.md

@@ -1109,6 +1109,27 @@ Migration tools are also shown in `pm info`:
 
 ---
 
+### 🔹 Configuration
+
+#### Check telemetry status
+```bash
+pm config telemetry
+```
+
+#### Enable telemetry
+```bash
+pm config telemetry on
+```
+
+#### Disable telemetry
+```bash
+pm config telemetry off
+```
+
+> **Privacy**: Telemetry is opt-in (disabled by default). Only anonymous data is collected: PM version, OS, command name, and project count. No project names, file paths, secrets, or personal information is ever sent.
+
+---
+
 ### 🔹 Help and Version
 
 #### View help
@@ -2094,6 +2115,11 @@ pm migrate                                     # List migration tools per projec
 pm migrate <name>                              # Run migration (with confirmation)
 pm migrate <name> status                       # Check migration status
 
+# === CONFIGURATION ===
+pm config telemetry                            # Check telemetry status
+pm config telemetry on                         # Enable anonymous telemetry
+pm config telemetry off                        # Disable telemetry
+
 # === UPDATES ===
 pm update                                      # Update to latest version
 

docs/es/README.md

@@ -273,6 +273,7 @@ chmod +x scripts/install.sh && ./scripts/install.sh
 | `pm export` | Exportar todos los proyectos a un archivo JSON portátil |
 | `pm export <nombres...> [--file <ruta>]` | Exportar proyectos seleccionados a un archivo personalizado |
 | `pm import <archivo>` | Importar proyectos desde un archivo JSON exportado |
+| `pm config telemetry [on\|off]` | Habilitar o deshabilitar telemetría anónima |
 | `pm help` | Mostrar ayuda |
 | `pm version` | Mostrar versión |
 
@@ -476,6 +477,32 @@ Los proyectos se guardan en:
 
 ---
 
+## 📊 Telemetría
+
+ProjectManager recopila estadísticas de uso **anónimas** para mejorar la herramienta. La telemetría es **opt-in** — desactivada por defecto.
+
+### Qué se recopila
+- Versión de PM, nombre/versión del SO, versión de Java
+- Nombre del comando (ej: `build`, `test`) — **sin argumentos**
+- Número de proyectos registrados — **sin nombres ni rutas**
+
+### Qué NO se recopila
+- Nombres de proyectos, rutas de archivos, código fuente
+- Variables de entorno, secretos, credenciales
+- Información personal, direcciones IP, nombres de usuario
+
+### Control
+```bash
+pm config telemetry on       # Activar
+pm config telemetry off      # Desactivar
+pm config telemetry          # Comprobar estado
+```
+
+En la primera ejecución, PM pregunta: `Enable telemetry? (y/n)` — por defecto es **no**.
+Elimina `~/.projectmanager/config.json` para resetear todas las preferencias.
+
+---
+
 ## 🚧 Roadmap
 
 ### ✅ Completado
@@ -490,9 +517,10 @@ Los proyectos se guardan en:
 - **Lint y Formato** — `pm lint` / `pm fmt` auto-detectan y ejecutan linters/formateadores (ESLint, Prettier, Clippy, gofmt, Ruff, Black, Checkstyle, Spotless y más)
 - **Workspaces** — `pm modules` detecta monorepos (Cargo, npm, Gradle, Go), detección multi-lenguaje, `pm build --all` y `pm test --all`
 - **Entornos** — `pm env files/show/switch` para descubrir archivos .env, escaneo de secretos (tokens AWS, GitHub, Slack), `pm migrate` para herramientas de migración (Prisma, Alembic, Diesel, Flyway, Liquibase, SQLx)
-- **Fiabilidad** — Escritura atómica, backup/recuperación, validación de directorio, integridad de descarga, 748 tests
+- **Telemetría** — Analíticas de uso anónimas opt-in vía PostHog, `pm config telemetry on/off`, diseño privacy-first
+- **Fiabilidad** — Escritura atómica, backup/recuperación, validación de directorio, integridad de descarga, 763 tests
 
-> Última release: **v1.7.1** (Entornos, Secretos y Bases de Datos) — Historial completo en [ROADMAP.md](ROADMAP.md)
+> Última release: **v1.8.0** (Telemetría) — Historial completo en [ROADMAP.md](ROADMAP.md)
 
 ### 💡 Ideas Futuras
 - [ ] Grupos de proyectos (`pm group create backend api-users product-service`, `pm run-group backend`)

docs/es/ROADMAP.md

@@ -355,12 +355,16 @@ Exporta todos o proyectos seleccionados a un archivo JSON portable e impórtalos
 ## v1.8.0 — Telemetría
 
 ### Analíticas de uso anónimas (opt-in)
-- Pregunta en primera ejecución: "¿Permitir estadísticas anónimas? (y/n)"
-- Rastrea: versión, SO, frecuencia de comandos, número de proyectos
-- `pm config telemetry on/off` para activar/desactivar en cualquier momento
-- Privacidad primero: sin datos personales, sin nombres de proyecto, sin rutas
-- Transparente: documentado en README y `pm help`
-- Backend: PostHog Cloud (tier gratuito)
+
+| Funcionalidad | Estado |
+|---------------|--------|
+| Prompt de consentimiento en primera ejecución (opt-in, desactivado por defecto) | ✅ Hecho |
+| Rastrea: versión, SO, nombre del comando, número de proyectos | ✅ Hecho |
+| `pm config telemetry on/off` para activar/desactivar en cualquier momento | ✅ Hecho |
+| Privacidad primero: sin datos personales, sin nombres de proyecto, sin rutas | ✅ Hecho |
+| Transparente: documentado en README, User-Guide y `pm help` | ✅ Hecho |
+| Backend: PostHog Cloud (tier gratuito) | ✅ Hecho |
+| Autocompletado en shell para comando config | ✅ Hecho |
 
 ---
 

docs/es/User-Guide.md

@@ -1109,6 +1109,27 @@ Las herramientas de migración también se muestran en `pm info`:
 
 ---
 
+### 🔹 Configuración
+
+#### Comprobar estado de telemetría
+```bash
+pm config telemetry
+```
+
+#### Activar telemetría
+```bash
+pm config telemetry on
+```
+
+#### Desactivar telemetría
+```bash
+pm config telemetry off
+```
+
+> **Privacidad**: La telemetría es opt-in (desactivada por defecto). Solo se recopilan datos anónimos: versión de PM, SO, nombre del comando y número de proyectos. Nunca se envían nombres de proyectos, rutas, secretos ni información personal.
+
+---
+
 ### 🔹 Ayuda y Versión
 
 #### Ver ayuda
@@ -2094,6 +2115,11 @@ pm migrate                                         # Listar herramientas de migr
 pm migrate <nombre>                                # Ejecutar migración (con confirmación)
 pm migrate <nombre> status                         # Comprobar estado de migración
 
+# === CONFIGURACIÓN ===
+pm config telemetry                                # Comprobar estado de telemetría
+pm config telemetry on                             # Activar telemetría anónima
+pm config telemetry off                            # Desactivar telemetría
+
 # === ACTUALIZACIONES ===
 pm update                                          # Actualizar a última versión
 

pom.xml

@@ -8,7 +8,7 @@
     <!-- Identificación del proyecto -->
     <groupId>pm</groupId>
     <artifactId>projectmanager</artifactId>
-    <version>1.7.1</version>
+    <version>1.8.0</version>
     <packaging>jar</packaging>
 
     <name>ProjectManager</name>

scripts/install.ps1

@@ -1,7 +1,7 @@
 # ProjectManager - Installation Script for Windows
 # Works both from source (mvn clean package) and from GitHub Release download
 
-$jarName = "projectmanager-1.7.1.jar"
+$jarName = "projectmanager-1.8.0.jar"
 
 Write-Host "=== ProjectManager Installer ===" -ForegroundColor Cyan
 Write-Host ""

scripts/install.sh

@@ -2,7 +2,7 @@
 # ProjectManager - Installation Script for Linux/Mac
 # Works both from source (mvn clean package) and from GitHub Release download
 
-JAR_NAME="projectmanager-1.7.1.jar"
+JAR_NAME="projectmanager-1.8.0.jar"
 
 echo "=== ProjectManager Installer ==="
 echo ""

src/main/java/pm/ProjectManager.java

@@ -34,6 +34,7 @@
 import pm.util.Constants;
 import pm.util.GitIntegration;
 import pm.util.RuntimeChecker;
+import pm.telemetry.Telemetry;
 import pm.util.UpdateChecker;
 
 import java.io.IOException;
@@ -103,6 +104,9 @@ public static void main(String[] args) {
         // Check for updates in the background (non-blocking, 2s timeout)
         UpdateChecker.checkForUpdates();
 
+        // Initialize telemetry (first-run consent prompt if needed)
+        Telemetry.init();
+
         if (args.length == 0) {
             printHelp();
             return;
@@ -137,10 +141,12 @@ public static void main(String[] args) {
                 case "migrate" -> handleMigrate(args);
                 case "export" -> handleExport(args);
                 case "import" -> handleImport(args);
+                case "config" -> handleConfig(args);
                 case "help", "-h", "--help" -> printHelp();
                 case "version", "-v", "--version" -> printVersion();
                 default -> handleGenericCommand(command, args);
             }
+            Telemetry.trackCommand(command);
         } catch (Exception e) {
             handleFatalError(e);
         }
@@ -3220,6 +3226,55 @@ private static void printBanner() {
             """.formatted(Constants.VERSION));
     }
 
+    // ============================================================
+    // COMMAND: CONFIG (User preferences)
+    // ============================================================
+
+    private static void handleConfig(String[] args) {
+        if (args.length < 2) {
+            printConfigHelp();
+            return;
+        }
+
+        String key = args[1].toLowerCase();
+        switch (key) {
+            case "telemetry" -> {
+                if (args.length < 3) {
+                    System.out.println("  Telemetry: " + (Telemetry.isEnabled() ? "on" : "off"));
+                    return;
+                }
+                String value = args[2].toLowerCase();
+                switch (value) {
+                    case "on" -> {
+                        Telemetry.setEnabled(true);
+                        OutputFormatter.success("Telemetry enabled.");
+                    }
+                    case "off" -> {
+                        Telemetry.setEnabled(false);
+                        OutputFormatter.success("Telemetry disabled.");
+                    }
+                    default -> {
+                        OutputFormatter.error("Invalid value: " + args[2]);
+                        System.out.println("Usage: pm config telemetry [on|off]");
+                    }
+                }
+            }
+            default -> {
+                OutputFormatter.error("Unknown config key: " + key);
+                printConfigHelp();
+            }
+        }
+    }
+
+    private static void printConfigHelp() {
+        System.out.println("""
+        Usage: pm config <key> [value]
+
+        Keys:
+          telemetry [on|off]     Enable/disable anonymous usage statistics
+        """);
+    }
+
     private static void printHelp() {
         System.out.println("""
         Usage: pm <command> [options]
@@ -3260,6 +3315,7 @@ migrate <name>                              Run database migration (with confirm
           migrate <name> status                       Check migration status
           export [names...] [--file <path>]           Export projects to JSON file
           import <file>                               Import projects from JSON file
+          config telemetry [on|off]                    Manage telemetry settings
           help                                      Show this help
           version                                   Show version