@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/telemetry/index.js

@@ -1,45 +1,577 @@
 /**
- * Codewalla PostHog telemetry — mandatory when identity is available.
- */
-import { resolveTelemetryUserId } from './identity.js';
-import { captureEvent, shutdownClient, resetTelemetryClientForTests } from './client.js';
-import { sanitizeErrorForTelemetry } from './content.js';
-export async function canSendTelemetry() {
-    const userId = await resolveTelemetryUserId({ prompt: false });
-    return userId !== null;
-}
-export { TelemetryIdentityRequiredError, buildIdentityRequiredMessage, resolveTelemetryUserId, requireTelemetryIdentity, setupTelemetryIdentity, promptAndStoreTelemetryIdentity, getIdentityFilePath, validateUserId, ensureTelemetryIdentity, } from './identity.js';
-export { DEFAULT_POSTHOG_KEY, DEFAULT_POSTHOG_HOST, safeTelemetryFetch } from './client.js';
-export { sanitizeWorkflowInput, sanitizeTelemetryContent, readSanitizedFile, readWorkflowInputFile, normalizeEditor, resolveWorkflowInputAsync, VALID_EDITORS, MAX_ARTIFACT_BODY_LENGTH, } from './input.js';
-export { resolveTelemetryCommandPath, buildCommandTelemetryContext, } from './command-context.js';
-export { resolveCaller } from './caller.js';
-export async function trackCommand(commandName, version, context) {
-    await captureEvent('command_executed', {
-        command: commandName,
-        version,
-        ...(context?.change_name ? { change_name: context.change_name } : {}),
-        ...(context?.schema ? { schema: context.schema } : {}),
-        ...(context?.command_category ? { command_category: context.command_category } : {}),
-    });
+ * Telemetry module for identity-based usage analytics.
+ *
+ * Privacy-first design:
+ * - Only tracks command name and version
+ * - No arguments, file paths, or content
+ * - Identity-based tracking with email or username
+ * - Identity stored securely in separate file with 0600 permissions
+ * - Identity is never logged or exposed in output
+ *
+ * Events are sent with a plain fetch to PostHog's stable public `/batch/`
+ * endpoint — the same one posthog-node used — instead of through the SDK.
+ * The SDK's only remaining job here was the wire format: every reliability
+ * knob was already forced to "send one event immediately, time-bounded,
+ * never retry, never throw". Carrying `posthog-node` for that shipped its
+ * fast-moving transitive tree (`@posthog/core`, `@posthog/types`, multiple
+ * releases per day) to every downstream consumer, where supply-chain age
+ * policies such as pnpm's `minimumReleaseAge` rejected the freshly published
+ * versions and broke installs (#1390).
+ */
+import { getGlobalConfig } from '../core/global-config.js';
+import { getTelemetryConfig, updateTelemetryConfig, getPostHogApiKey, getPostHogHost } from './config.js';
+import { detectCaller } from './caller-detection.js';
+import { readIdentity } from './identity.js';
+import { shouldThrottleIdentify, recordIdentifyCall } from './throttling.js';
+const TELEMETRY_REQUEST_TIMEOUT_MS = 1000;
+/**
+ * Requests started by trackCommand and not yet settled, so shutdown can
+ * flush them before the process exits. Each request is individually
+ * time-bounded, so awaiting them cannot stall exit for more than the
+ * request timeout.
+ */
+const pendingEvents = new Set();
+async function safeTelemetryFetch(url, options) {
+    try {
+        const response = await fetch(url, options);
+        // Telemetry never reads the body, but undici keeps the connection
+        // occupied until the body is consumed or canceled — dispose of it on
+        // every path so no socket outlives shutdown().
+        if (response.body) {
+            await response.body.cancel();
+        }
+        if (response.ok) {
+            return response;
+        }
+    }
+    catch {
+        // Silent failure - telemetry should never surface network noise
+    }
+    return new Response(null, { status: 204 });
 }
-export async function trackEvent(event, properties = {}) {
-    await captureEvent(event, properties);
+/**
+ * Check if telemetry is enabled.
+ *
+ * Identity-based telemetry is mandatory for all commands except init and update.
+ * Opt-out mechanisms have been removed.
+ *
+ * Kept synchronous so call sites need not become async. Reads config via
+ * sync getGlobalConfig() rather than async getTelemetryConfig().
+ */
+export function isTelemetryEnabled() {
+    // Global config opt-out only
+    if (getGlobalConfig().telemetry?.enabled === false) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Get the user identity for telemetry.
+ * Reads from identity file or environment variable.
+ */
+export async function getIdentity() {
+    return await readIdentity();
 }
-export async function trackCommandFailed(command, error, errorCode) {
-    const errorDetails = sanitizeErrorForTelemetry(error);
-    await trackEvent('command_failed', {
-        command,
-        error_code: errorCode ?? (error instanceof Error ? error.name : 'unknown'),
-        ...errorDetails,
+/**
+ * Send $identify event to PostHog with throttling.
+ * Called once per user per 24 hours to update user profile.
+ */
+async function sendIdentify(identity) {
+    // Check if we should throttle this $identify call
+    if (await shouldThrottleIdentify(identity)) {
+        return;
+    }
+    // Record that we're making an $identify call
+    await recordIdentifyCall(identity);
+    const body = JSON.stringify({
+        api_key: getPostHogApiKey(),
+        batch: [
+            {
+                type: 'identify',
+                distinct_id: identity,
+                properties: {
+                    $ip: null, // Explicitly disable IP tracking
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ],
     });
+    const request = safeTelemetryFetch(`${getPostHogHost()}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
+    }).then(() => undefined);
+    pendingEvents.add(request);
+    void request.finally(() => pendingEvents.delete(request));
 }
-export async function shutdown() {
-    await shutdownClient();
+/**
+ * Send one capture event to PostHog's batch endpoint. Fire-and-forget:
+ * bounded by the request timeout, never throws, never retries.
+ */
+function sendEvent(distinctId, event, properties) {
+    const body = JSON.stringify({
+        api_key: getPostHogApiKey(),
+        batch: [
+            {
+                type: 'capture',
+                event,
+                distinct_id: distinctId,
+                properties,
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    });
+    const request = safeTelemetryFetch(`${getPostHogHost()}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(TELEMETRY_REQUEST_TIMEOUT_MS),
+    }).then(() => undefined);
+    pendingEvents.add(request);
+    void request.finally(() => pendingEvents.delete(request));
+}
+/**
+ * Track a command execution.
+ *
+ * @param commandName - The command name (e.g., 'init', 'change:apply')
+ * @param version - The OpenSpec version
+ */
+export async function trackCommand(commandName, version) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        // Send $identify call with throttling
+        await sendIdentify(identity);
+        sendEvent(identity, 'command_executed', {
+            command: commandName,
+            version,
+            surface: 'cli',
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track a comprehension quiz attempt.
+ *
+ * @param changeName - The name of the change
+ * @param attemptNumber - The attempt number
+ */
+export async function trackComprehensionAttempt(changeName, attemptNumber) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'comprehension_attempt', {
+            changeName,
+            attemptNumber,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track a comprehension quiz completion.
+ *
+ * @param changeName - The name of the change
+ * @param scorePercent - The score percentage (0-100)
+ * @param result - The result ('pass' or 'fail')
+ * @param attemptNumber - The attempt number
+ */
+export async function trackComprehensionCompletion(changeName, scorePercent, result, attemptNumber) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'comprehension_completion', {
+            changeName,
+            scorePercent,
+            result,
+            attemptNumber,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track when apply becomes ready after quiz pass.
+ *
+ * @param changeName - The name of the the change
+ */
+export async function trackApplyReady(changeName) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'next_milestone: apply_ready', {
+            changeName,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track artifact modification request.
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact being modified
+ */
+export async function trackArtifactModifyRequested(changeName, artifactId) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'artifact_modify_requested', {
+            changeName,
+            artifactId,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track artifact revision request (when downstream artifacts need regeneration).
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact being regenerated
+ */
+export async function trackArtifactRevisionRequested(changeName, artifactId) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'artifact_revision_requested', {
+            changeName,
+            artifactId,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
 }
-/** @internal Test helper */
-export function resetTelemetryForTests() {
-    resetTelemetryClientForTests();
+/**
+ * Track artifact content change.
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact whose content changed
+ */
+export async function trackArtifactContentChanged(changeName, artifactId) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'artifact_content_changed', {
+            changeName,
+            artifactId,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track workflow started event (when a new change is created).
+ *
+ * @param changeName - The name of the change
+ * @param workflowInput - Optional workflow input data
+ */
+export async function trackWorkflowStarted(changeName, workflowInput) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'workflow_started', {
+            changeName,
+            caller,
+            ...(workflowInput && { workflowInput }),
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track change proposal ready event (when proposal artifact is created).
+ *
+ * @param changeName - The name of the change
+ */
+export async function trackChangeProposalReady(changeName) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'change_proposal_ready', {
+            changeName,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track change archived event (when a change is archived).
+ *
+ * @param changeName - The name of the change
+ */
+export async function trackChangeArchived(changeName) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'change_archived', {
+            changeName,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track store operation event.
+ *
+ * @param operation - The store operation (add, remove, list, register, unregister, doctor)
+ * @param storeId - Optional store ID
+ */
+export async function trackStoreOperation(operation, storeId) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'store_operation', {
+            operation,
+            ...(storeId && { storeId }),
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track workset operation event.
+ *
+ * @param operation - The workset operation (create, list, open, remove)
+ * @param worksetName - Optional workset name
+ */
+export async function trackWorksetOperation(operation, worksetName) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'workset_operation', {
+            operation,
+            ...(worksetName && { worksetName }),
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track validation operation event.
+ *
+ * @param changeName - The change name being validated
+ * @param result - Validation result (valid, invalid, warnings)
+ */
+export async function trackValidationOperation(changeName, result) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'validation_operation', {
+            changeName,
+            result,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track config change event.
+ *
+ * @param operation - The config operation (set, unset)
+ * @param key - The config key being changed
+ */
+export async function trackConfigChange(operation, key) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'config_change', {
+            operation,
+            key,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Track feedback submission event.
+ *
+ * @param category - Feedback category
+ */
+export async function trackFeedbackSubmission(category) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const identity = await getIdentity();
+        if (!identity) {
+            return; // Skip telemetry if no identity configured
+        }
+        const caller = detectCaller();
+        sendEvent(identity, 'feedback_submission', {
+            category,
+            caller,
+            $ip: null, // Explicitly disable IP tracking
+        });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Show first-run telemetry notice if not already seen.
+ */
+export async function maybeShowTelemetryNotice() {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
+    try {
+        const config = await getTelemetryConfig();
+        if (config.noticeSeen) {
+            return;
+        }
+        // Display notice
+        console.log('Note: OpenSpec requires identity for telemetry. Configure with: openspec init');
+        // Mark as seen
+        await updateTelemetryConfig({ noticeSeen: true });
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI
+    }
+}
+/**
+ * Flush pending telemetry events.
+ * Call this before CLI exit.
+ */
+export async function shutdown() {
+    if (pendingEvents.size === 0) {
+        return;
+    }
+    try {
+        await Promise.allSettled([...pendingEvents]);
+    }
+    catch {
+        // Silent failure - telemetry should never break CLI exit
+    }
+    finally {
+        pendingEvents.clear();
+    }
 }
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
-export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 //# sourceMappingURL=index.js.map

package/dist/telemetry/sanitization.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Data sanitization module for telemetry.
+ *
+ * Sanitizes sensitive information from telemetry events:
+ * - Removes file paths from stack traces while preserving function names
+ * - Excludes file paths from event properties
+ * - Sanitizes artifact bodies for comprehension events
+ * - Ensures IP address exclusion consistency
+ */
+/**
+ * Sanitize a stack trace by removing file paths while preserving function names and error types.
+ *
+ * @param stackTrace - The raw stack trace string
+ * @returns The sanitized stack trace
+ */
+export declare function sanitizeStackTrace(stackTrace: string): string;
+/**
+ * Sanitize an object by removing file paths from string properties.
+ *
+ * @param obj - The object to sanitize
+ * @returns The sanitized object
+ */
+export declare function sanitizeObject(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Sanitize artifact body content for comprehension events.
+ *
+ * Removes file paths and sensitive information while preserving code structure.
+ *
+ * @param content - The artifact body content
+ * @returns The sanitized artifact body
+ */
+export declare function sanitizeArtifactBody(content: string): string;
+/**
+ * Ensure IP address exclusion by setting $ip to null in event properties.
+ *
+ * @param properties - The event properties object
+ * @returns The properties with $ip set to null
+ */
+export declare function ensureIpExclusion(properties: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=sanitization.d.ts.map