@proletariat/cli 0.3.51 → 0.3.53

package/dist/lib/telemetry/analytics.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Product Analytics (Statsig) & Event Tracking
+ *
+ * Provides anonymous usage analytics for the CLI using Statsig client SDK.
+ * All data is anonymous — identified by a machine UUID only, no PII is ever sent.
+ *
+ * Telemetry can be disabled via:
+ * - `prlt telemetry disable`
+ * - `DO_NOT_TRACK=1` environment variable
+ * - `PRLT_TELEMETRY_DISABLED=1` environment variable
+ *
+ * Privacy:
+ * - Anonymous machine ID (UUID) stored in ~/.proletariat/telemetry.json
+ * - No file paths, usernames, or ticket content ever sent
+ * - Events are fired async and never block command execution
+ */
+/**
+ * Check if telemetry is disabled by environment variables or config.
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Enable telemetry.
+ */
+export declare function enableTelemetry(): void;
+/**
+ * Disable telemetry.
+ */
+export declare function disableTelemetry(): void;
+/**
+ * Get current telemetry status for display.
+ */
+export declare function getTelemetryStatus(): {
+    enabled: boolean;
+    machineId: string;
+    envOverride: boolean;
+    envVar?: string;
+};
+/**
+ * Get the anonymous machine ID for this installation.
+ */
+export declare function getMachineId(): string;
+/**
+ * Initialize the Statsig SDK. Called from the init hook.
+ * No-op if telemetry is disabled.
+ */
+export declare function initAnalytics(version: string): Promise<void>;
+/**
+ * Track an analytics event. Fire-and-forget — never blocks.
+ *
+ * @param eventName - Event name (e.g., 'command_run')
+ * @param value - Optional numeric or string value
+ * @param metadata - Event-specific metadata
+ */
+export declare function trackEvent(eventName: string, value?: string | number | null, metadata?: Record<string, unknown> | null): void;
+/**
+ * Track a command execution.
+ */
+export declare function trackCommandRun(options: {
+    command: string;
+    durationMs: number;
+    success: boolean;
+    flags?: string[];
+}): void;
+/**
+ * Track an agent being spawned.
+ */
+export declare function trackAgentSpawned(options: {
+    executor: string;
+    environment: string;
+    action: string;
+    ephemeral: boolean;
+}): void;
+/**
+ * Track an orchestrator being started.
+ */
+export declare function trackOrchestratorStarted(options: {
+    executor: string;
+    name: string;
+    displayMode: string;
+}): void;
+/**
+ * Track work being completed.
+ */
+export declare function trackWorkCompleted(options: {
+    durationMs: number;
+    prCreated: boolean;
+}): void;
+/**
+ * Track a PR being created.
+ */
+export declare function trackPRCreated(options: {
+    source: 'prlt' | 'manual';
+}): void;
+/**
+ * Track an MCP tool call.
+ */
+export declare function trackMCPToolCalled(options: {
+    toolName: string;
+    success: boolean;
+}): void;
+/**
+ * Flush pending events and shut down the Statsig client.
+ * Called from the postrun hook. Times out to avoid blocking CLI exit.
+ */
+export declare function shutdownAnalytics(): Promise<void>;

package/dist/lib/telemetry/analytics.js

@@ -0,0 +1,289 @@
+/**
+ * Product Analytics (Statsig) & Event Tracking
+ *
+ * Provides anonymous usage analytics for the CLI using Statsig client SDK.
+ * All data is anonymous — identified by a machine UUID only, no PII is ever sent.
+ *
+ * Telemetry can be disabled via:
+ * - `prlt telemetry disable`
+ * - `DO_NOT_TRACK=1` environment variable
+ * - `PRLT_TELEMETRY_DISABLED=1` environment variable
+ *
+ * Privacy:
+ * - Anonymous machine ID (UUID) stored in ~/.proletariat/telemetry.json
+ * - No file paths, usernames, or ticket content ever sent
+ * - Events are fired async and never block command execution
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { getMachineConfigDir, ensureMachineConfigDir } from '../machine-config.js';
+// Statsig client SDK key (public — safe to embed in open source repos)
+const STATSIG_CLIENT_KEY = 'client-kvxMxRhn9NFSmH8orl7e2W9nYTfWVS7Kjf7yRTdIecc';
+// Flush timeout — don't let analytics delay CLI exit
+const FLUSH_TIMEOUT_MS = 2000;
+// Module-level state
+let statsigClient = null;
+let telemetryConfig = null;
+let cliVersion = null;
+// ─── Telemetry Config ────────────────────────────────────────────────────────
+function getTelemetryConfigPath() {
+    return path.join(getMachineConfigDir(), 'telemetry.json');
+}
+function readTelemetryConfig() {
+    if (telemetryConfig)
+        return telemetryConfig;
+    const configPath = getTelemetryConfigPath();
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            telemetryConfig = JSON.parse(content);
+            return telemetryConfig;
+        }
+        catch {
+            // Fall through to create new config
+        }
+    }
+    // Create new config with generated machine ID
+    telemetryConfig = {
+        enabled: true,
+        noticeShown: false,
+        machineId: crypto.randomUUID(),
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    writeTelemetryConfig(telemetryConfig);
+    return telemetryConfig;
+}
+function writeTelemetryConfig(config) {
+    ensureMachineConfigDir();
+    const configPath = getTelemetryConfigPath();
+    const tempPath = `${configPath}.tmp.${process.pid}`;
+    try {
+        fs.writeFileSync(tempPath, JSON.stringify(config, null, 2), 'utf-8');
+        fs.renameSync(tempPath, configPath);
+    }
+    catch {
+        try {
+            if (fs.existsSync(tempPath))
+                fs.unlinkSync(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+// ─── Opt-out Detection ───────────────────────────────────────────────────────
+/**
+ * Check if telemetry is disabled by environment variables or config.
+ */
+export function isTelemetryEnabled() {
+    // Environment variable opt-outs (standard + prlt-specific)
+    if (process.env.DO_NOT_TRACK === '1' || process.env.DO_NOT_TRACK === 'true')
+        return false;
+    if (process.env.PRLT_TELEMETRY_DISABLED === '1' || process.env.PRLT_TELEMETRY_DISABLED === 'true')
+        return false;
+    // Config-based opt-out
+    const config = readTelemetryConfig();
+    return config.enabled;
+}
+/**
+ * Enable telemetry.
+ */
+export function enableTelemetry() {
+    const config = readTelemetryConfig();
+    config.enabled = true;
+    config.updatedAt = new Date().toISOString();
+    telemetryConfig = config;
+    writeTelemetryConfig(config);
+}
+/**
+ * Disable telemetry.
+ */
+export function disableTelemetry() {
+    const config = readTelemetryConfig();
+    config.enabled = false;
+    config.updatedAt = new Date().toISOString();
+    telemetryConfig = config;
+    writeTelemetryConfig(config);
+}
+/**
+ * Get current telemetry status for display.
+ */
+export function getTelemetryStatus() {
+    const config = readTelemetryConfig();
+    // Check for env var overrides
+    if (process.env.DO_NOT_TRACK === '1' || process.env.DO_NOT_TRACK === 'true') {
+        return { enabled: false, machineId: config.machineId, envOverride: true, envVar: 'DO_NOT_TRACK' };
+    }
+    if (process.env.PRLT_TELEMETRY_DISABLED === '1' || process.env.PRLT_TELEMETRY_DISABLED === 'true') {
+        return { enabled: false, machineId: config.machineId, envOverride: true, envVar: 'PRLT_TELEMETRY_DISABLED' };
+    }
+    return { enabled: config.enabled, machineId: config.machineId, envOverride: false };
+}
+// ─── First-Run Notice ────────────────────────────────────────────────────────
+/**
+ * Show a one-time notice that telemetry is active.
+ * Only shown in interactive TTY sessions.
+ */
+function showTelemetryNotice() {
+    const config = readTelemetryConfig();
+    if (config.noticeShown)
+        return;
+    if (!process.stdout.isTTY) {
+        // Mark as shown so we don't try again, but don't print in non-TTY
+        config.noticeShown = true;
+        writeTelemetryConfig(config);
+        return;
+    }
+    console.log('');
+    console.log('Proletariat collects anonymous usage analytics to improve the CLI.');
+    console.log('Only command names and durations are tracked — no values, arguments, or personal data.');
+    console.log('You can opt out at any time:');
+    console.log('');
+    console.log('  prlt telemetry disable');
+    console.log('');
+    config.noticeShown = true;
+    telemetryConfig = config;
+    writeTelemetryConfig(config);
+}
+// ─── Machine ID ──────────────────────────────────────────────────────────────
+/**
+ * Get the anonymous machine ID for this installation.
+ */
+export function getMachineId() {
+    return readTelemetryConfig().machineId;
+}
+// ─── Statsig Client ──────────────────────────────────────────────────────────
+/**
+ * Initialize the Statsig SDK. Called from the init hook.
+ * No-op if telemetry is disabled.
+ */
+export async function initAnalytics(version) {
+    cliVersion = version;
+    if (!isTelemetryEnabled())
+        return;
+    showTelemetryNotice();
+    try {
+        const { StatsigClient: StatsigClientClass } = await import('@statsig/js-client');
+        const client = new StatsigClientClass(STATSIG_CLIENT_KEY, { userID: getMachineId(), custom: { cli_version: version } });
+        await client.initializeAsync();
+        statsigClient = client;
+        // Share Statsig client with feature-flags for synchronous gate checks
+        const { setStatsigClient } = await import('./feature-flags.js');
+        setStatsigClient(client);
+    }
+    catch {
+        // If Statsig can't initialize, fail silently — analytics should never break the CLI
+        statsigClient = null;
+    }
+}
+// ─── Event Tracking ──────────────────────────────────────────────────────────
+/**
+ * Track an analytics event. Fire-and-forget — never blocks.
+ *
+ * @param eventName - Event name (e.g., 'command_run')
+ * @param value - Optional numeric or string value
+ * @param metadata - Event-specific metadata
+ */
+export function trackEvent(eventName, value, metadata) {
+    if (!statsigClient || !isTelemetryEnabled())
+        return;
+    try {
+        // Convert metadata values to strings as required by the client SDK
+        const stringMetadata = metadata
+            ? Object.fromEntries(Object.entries({ ...metadata, cli_version: cliVersion }).map(([k, v]) => [k, String(v)]))
+            : cliVersion
+                ? { cli_version: cliVersion }
+                : null;
+        statsigClient.logEvent(eventName, value, stringMetadata);
+    }
+    catch {
+        // Never let analytics errors affect the CLI
+    }
+}
+/**
+ * Track a command execution.
+ */
+export function trackCommandRun(options) {
+    trackEvent('command_run', options.durationMs, {
+        command: options.command,
+        success: options.success,
+        flags_used: (options.flags ?? []).join(','),
+    });
+}
+/**
+ * Track an agent being spawned.
+ */
+export function trackAgentSpawned(options) {
+    trackEvent('agent_spawned', null, {
+        executor: options.executor,
+        environment: options.environment,
+        action: options.action,
+        ephemeral: String(options.ephemeral),
+    });
+}
+/**
+ * Track an orchestrator being started.
+ */
+export function trackOrchestratorStarted(options) {
+    trackEvent('orchestrator_started', null, {
+        executor: options.executor,
+        name: options.name,
+        display_mode: options.displayMode,
+    });
+}
+/**
+ * Track work being completed.
+ */
+export function trackWorkCompleted(options) {
+    trackEvent('work_completed', options.durationMs, {
+        pr_created: String(options.prCreated),
+    });
+}
+/**
+ * Track a PR being created.
+ */
+export function trackPRCreated(options) {
+    trackEvent('pr_created', null, {
+        source: options.source,
+    });
+}
+/**
+ * Track an MCP tool call.
+ */
+export function trackMCPToolCalled(options) {
+    trackEvent('mcp_tool_called', null, {
+        tool_name: options.toolName,
+        success: String(options.success),
+    });
+}
+// ─── Shutdown ────────────────────────────────────────────────────────────────
+/**
+ * Flush pending events and shut down the Statsig client.
+ * Called from the postrun hook. Times out to avoid blocking CLI exit.
+ */
+export async function shutdownAnalytics() {
+    if (!statsigClient)
+        return;
+    try {
+        // Give the client a moment to flush, but don't block the CLI
+        await new Promise((resolve) => setTimeout(resolve, FLUSH_TIMEOUT_MS));
+        statsigClient.shutdown();
+    }
+    catch {
+        // Never let shutdown errors affect the CLI
+    }
+    finally {
+        statsigClient = null;
+        // Clear feature-flags module reference
+        try {
+            const { setStatsigClient } = await import('./feature-flags.js');
+            setStatsigClient(null);
+        }
+        catch {
+            // Ignore
+        }
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/lib/telemetry/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../../src/lib/telemetry/analytics.ts"],"names":[],"mappings":"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"}

package/dist/lib/telemetry/feature-flags.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Feature Flags (Statsig Feature Gates)
+ *
+ * Wraps Statsig feature gate checks with a simple API for the CLI.
+ * Feature flags are evaluated locally after SDK initialization,
+ * so checks are near-instant after the initial fetch.
+ *
+ * Usage:
+ *   import { isEnabled } from '../lib/telemetry/feature-flags.js'
+ *   if (isEnabled('new_board_view')) { ... }
+ *
+ * Feature flags require Statsig to be initialized (via initAnalytics).
+ * If Statsig is unavailable or telemetry is disabled, all flags return false.
+ */
+interface StatsigClientRef {
+    checkGate(gateName: string): boolean;
+    getDynamicConfig(configName: string): {
+        get(key: string, defaultValue: unknown): unknown;
+    };
+}
+/**
+ * Set the Statsig client reference (called from analytics.ts after init).
+ * @internal
+ */
+export declare function setStatsigClient(client: StatsigClientRef | null): void;
+/**
+ * Check if a feature gate is enabled for the current machine.
+ *
+ * Uses Statsig's local evaluation (near-zero latency after init).
+ * Returns false if Statsig is not initialized or telemetry is disabled.
+ *
+ * @param gateName - The feature gate name (e.g., 'new_board_view')
+ * @returns Whether the gate is enabled
+ */
+export declare function isEnabled(gateName: string): boolean;
+/**
+ * Get a dynamic config value from Statsig.
+ *
+ * Useful for remote configuration (not just boolean flags).
+ * Returns the default value if Statsig is unavailable.
+ *
+ * @param configName - The dynamic config name
+ * @param key - The key within the config
+ * @param defaultValue - Default value if unavailable
+ * @returns The config value, or the default
+ */
+export declare function getConfigValue<T>(configName: string, key: string, defaultValue: T): T;
+/**
+ * Clear the local flag cache.
+ * Useful for testing or when you want to force re-evaluation.
+ */
+export declare function clearFlagCache(): void;
+export {};

package/dist/lib/telemetry/feature-flags.js

@@ -0,0 +1,83 @@
+/**
+ * Feature Flags (Statsig Feature Gates)
+ *
+ * Wraps Statsig feature gate checks with a simple API for the CLI.
+ * Feature flags are evaluated locally after SDK initialization,
+ * so checks are near-instant after the initial fetch.
+ *
+ * Usage:
+ *   import { isEnabled } from '../lib/telemetry/feature-flags.js'
+ *   if (isEnabled('new_board_view')) { ... }
+ *
+ * Feature flags require Statsig to be initialized (via initAnalytics).
+ * If Statsig is unavailable or telemetry is disabled, all flags return false.
+ */
+import { isTelemetryEnabled } from './analytics.js';
+// Cache for flag values — populated on check, persists for the process lifetime
+const flagCache = new Map();
+// Statsig client instance reference — set after initialization in initAnalytics
+let statsigClient = null;
+/**
+ * Set the Statsig client reference (called from analytics.ts after init).
+ * @internal
+ */
+export function setStatsigClient(client) {
+    statsigClient = client;
+}
+/**
+ * Check if a feature gate is enabled for the current machine.
+ *
+ * Uses Statsig's local evaluation (near-zero latency after init).
+ * Returns false if Statsig is not initialized or telemetry is disabled.
+ *
+ * @param gateName - The feature gate name (e.g., 'new_board_view')
+ * @returns Whether the gate is enabled
+ */
+export function isEnabled(gateName) {
+    if (!isTelemetryEnabled() || !statsigClient)
+        return false;
+    // Return cached value if available
+    if (flagCache.has(gateName)) {
+        return flagCache.get(gateName);
+    }
+    try {
+        const result = statsigClient.checkGate(gateName);
+        flagCache.set(gateName, result);
+        return result;
+    }
+    catch {
+        // Statsig not initialized or gate check failed — default to false
+        flagCache.set(gateName, false);
+        return false;
+    }
+}
+/**
+ * Get a dynamic config value from Statsig.
+ *
+ * Useful for remote configuration (not just boolean flags).
+ * Returns the default value if Statsig is unavailable.
+ *
+ * @param configName - The dynamic config name
+ * @param key - The key within the config
+ * @param defaultValue - Default value if unavailable
+ * @returns The config value, or the default
+ */
+export function getConfigValue(configName, key, defaultValue) {
+    if (!isTelemetryEnabled() || !statsigClient)
+        return defaultValue;
+    try {
+        const config = statsigClient.getDynamicConfig(configName);
+        return config.get(key, defaultValue);
+    }
+    catch {
+        return defaultValue;
+    }
+}
+/**
+ * Clear the local flag cache.
+ * Useful for testing or when you want to force re-evaluation.
+ */
+export function clearFlagCache() {
+    flagCache.clear();
+}
+//# sourceMappingURL=feature-flags.js.map

package/dist/lib/telemetry/feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags.js","sourceRoot":"","sources":["../../../src/lib/telemetry/feature-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,gFAAgF;AAChF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAA;AAE5C,gFAAgF;AAChF,IAAI,aAAa,GAA4B,IAAI,CAAA;AAOjD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA+B;IAC9D,aAAa,GAAG,MAAM,CAAA;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAA;IAEzD,mCAAmC;IACnC,IAAI,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAA;IACjC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QAChD,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QAC/B,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC9B,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAI,UAAkB,EAAE,GAAW,EAAE,YAAe;IAChF,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,aAAa;QAAE,OAAO,YAAY,CAAA;IAEhE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAA;QACzD,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,YAAY,CAAM,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAA;IACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,SAAS,CAAC,KAAK,EAAE,CAAA;AACnB,CAAC"}

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Telemetry and error tracking via Sentry.
+ *
+ * Implements opt-out crash reporting with:
+ * - First-run notice shown once
+ * - `prlt telemetry disable/enable/status` commands
+ * - Respects DO_NOT_TRACK=1 and PRLT_TELEMETRY_DISABLED=1 env vars
+ * - Consent stored in ~/.proletariat/config.json
+ * - Path scrubbing to remove usernames from stack traces
+ */
+interface TelemetryConfig {
+    enabled?: boolean;
+    noticeShown?: boolean;
+}
+/**
+ * Read the telemetry section from machine config.
+ */
+export declare function readTelemetryConfig(): TelemetryConfig;
+/**
+ * Write telemetry preferences to machine config.
+ */
+export declare function writeTelemetryConfig(telemetry: TelemetryConfig): void;
+/**
+ * Check if telemetry is enabled.
+ *
+ * Disabled when any of:
+ * - DO_NOT_TRACK=1 (consoledonottrack.com standard)
+ * - PRLT_TELEMETRY_DISABLED=1
+ * - User ran `prlt telemetry disable` (config.telemetry === false)
+ *
+ * Enabled by default (opt-out model).
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Check if the first-run telemetry notice has been shown.
+ */
+export declare function hasShownTelemetryNotice(): boolean;
+/**
+ * Mark the telemetry notice as shown.
+ */
+export declare function markTelemetryNoticeShown(): void;
+/**
+ * Show the first-run telemetry notice.
+ * Returns true if the notice was shown (first time), false if already shown.
+ */
+export declare function showTelemetryNotice(): boolean;
+/**
+ * Get the Sentry DSN. Exposed for testing.
+ */
+export declare function getSentryDSN(): string;
+/**
+ * Initialize Sentry error tracking.
+ * Should be called as early as possible in the CLI lifecycle.
+ *
+ * @param cliVersion - The CLI version string from oclif config
+ */
+export declare function initSentry(cliVersion: string): Promise<void>;
+/**
+ * Flush pending Sentry events with a timeout.
+ * Should be called in the postrun hook.
+ */
+export declare function flushSentry(): Promise<void>;
+export {};