@codewalla_india/openspec 1.0.6 → 1.2.0

package/dist/telemetry/index.js

@@ -1,164 +1,45 @@
 /**
- * Telemetry module for anonymous usage analytics.
- *
- * Privacy-first design:
- * - Only tracks command name and version
- * - No arguments, file paths, or content
- * - Opt-out via OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1
- * - Auto-disabled in CI environments
- * - Anonymous ID is a random UUID with no relation to the user
+ * Codewalla PostHog telemetry — mandatory when identity is available.
  */
-import { PostHog } from 'posthog-node';
-import { randomUUID } from 'crypto';
-import { getTelemetryConfig, updateTelemetryConfig } from './config.js';
-// PostHog API key - public key for client-side analytics
-// This is safe to embed as it only allows sending events, not reading data
-const POSTHOG_API_KEY = 'phc_Hthu8YvaIJ9QaFKyTG4TbVwkbd5ktcAFzVTKeMmoW2g';
-// Using reverse proxy to avoid ad blockers and keep traffic on our domain
-const POSTHOG_HOST = 'https://edge.openspec.dev';
-const TELEMETRY_REQUEST_TIMEOUT_MS = 1000;
-let posthogClient = null;
-let anonymousId = null;
-async function safeTelemetryFetch(url, options) {
-    try {
-        const response = await fetch(url, options);
-        if (response.ok) {
-            return response;
-        }
-    }
-    catch {
-        // Silent failure - telemetry should never surface network noise
-    }
-    return new Response(null, { status: 204 });
+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;
 }
-/**
- * Check if telemetry is enabled.
- *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
- */
-export function isTelemetryEnabled() {
-    // Check explicit opt-out
-    if (process.env.OPENSPEC_TELEMETRY === '0') {
-        return false;
-    }
-    // Respect DO_NOT_TRACK standard
-    if (process.env.DO_NOT_TRACK === '1') {
-        return false;
-    }
-    // Auto-disable in CI environments
-    if (process.env.CI === 'true') {
-        return false;
-    }
-    return true;
+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 } : {}),
+    });
 }
-/**
- * Get or create the anonymous user ID.
- * Lazily generates a UUID on first call and persists it.
- */
-export async function getOrCreateAnonymousId() {
-    // Return cached value if available
-    if (anonymousId) {
-        return anonymousId;
-    }
-    // Try to load from config
-    const config = await getTelemetryConfig();
-    if (config.anonymousId) {
-        anonymousId = config.anonymousId;
-        return anonymousId;
-    }
-    // Generate new UUID and persist
-    anonymousId = randomUUID();
-    await updateTelemetryConfig({ anonymousId });
-    return anonymousId;
+export async function trackEvent(event, properties = {}) {
+    await captureEvent(event, properties);
 }
-/**
- * Get the PostHog client instance.
- * Creates it on first call with CLI-optimized settings.
- */
-function getClient() {
-    if (!posthogClient) {
-        posthogClient = new PostHog(POSTHOG_API_KEY, {
-            host: POSTHOG_HOST,
-            flushAt: 1, // Send immediately, don't batch
-            flushInterval: 0, // No timer-based flushing
-            fetchRetryCount: 0,
-            requestTimeout: TELEMETRY_REQUEST_TIMEOUT_MS,
-            preloadFeatureFlags: false,
-            disableRemoteConfig: true,
-            disableSurveys: true,
-            fetch: safeTelemetryFetch,
-        });
-    }
-    return posthogClient;
+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,
+    });
 }
-/**
- * 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 userId = await getOrCreateAnonymousId();
-        const client = getClient();
-        client.capture({
-            distinctId: userId,
-            event: 'command_executed',
-            properties: {
-                command: commandName,
-                version: version,
-                surface: 'cli',
-                $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 collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0');
-        // Mark as seen
-        await updateTelemetryConfig({ noticeSeen: true });
-    }
-    catch {
-        // Silent failure - telemetry should never break CLI
-    }
-}
-/**
- * Shutdown the PostHog client and flush pending events.
- * Call this before CLI exit.
- */
 export async function shutdown() {
-    if (!posthogClient) {
-        return;
-    }
-    try {
-        await posthogClient.shutdown();
-    }
-    catch {
-        // Silent failure - telemetry should never break CLI exit
-    }
-    finally {
-        posthogClient = null;
-    }
+    await shutdownClient();
+}
+/** @internal Test helper */
+export function resetTelemetryForTests() {
+    resetTelemetryClientForTests();
 }
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 //# sourceMappingURL=index.js.map

package/dist/telemetry/input.d.ts

@@ -0,0 +1,17 @@
+export declare const VALID_EDITORS: readonly ["cursor", "windsurf", "claude"];
+export type WorkflowEditor = (typeof VALID_EDITORS)[number];
+export declare const MAX_ARTIFACT_BODY_LENGTH = 8000;
+export declare function sanitizeTelemetryContent(text: string, maxLength?: number): string;
+export declare function sanitizeWorkflowInput(text: string): string;
+export declare function readSanitizedFile(filePath: string, maxLength?: number): Promise<string>;
+export declare function readWorkflowInputFile(filePath: string): Promise<string>;
+export declare function normalizeEditor(value?: string): WorkflowEditor | undefined;
+export declare function resolveWorkflowInput(options: {
+    workflowInput?: string;
+    workflowInputFile?: string;
+}): string | undefined;
+export declare function resolveWorkflowInputAsync(options: {
+    workflowInput?: string;
+    workflowInputFile?: string;
+}): Promise<string | undefined>;
+//# sourceMappingURL=input.d.ts.map

package/dist/telemetry/input.js

@@ -0,0 +1,68 @@
+/**
+ * Workflow input normalization for Codewalla telemetry.
+ */
+import { promises as fs } from 'fs';
+export const VALID_EDITORS = ['cursor', 'windsurf', 'claude'];
+const MAX_WORKFLOW_INPUT_LENGTH = 2000;
+export const MAX_ARTIFACT_BODY_LENGTH = 8000;
+const SECRET_PATTERNS = [
+    /\bsk-[a-zA-Z0-9_-]{8,}\b/g,
+    /\bghp_[a-zA-Z0-9]{20,}\b/g,
+    /Bearer\s+[a-zA-Z0-9._-]+/gi,
+];
+function redactSecrets(text) {
+    let sanitized = text.trim();
+    for (const pattern of SECRET_PATTERNS) {
+        sanitized = sanitized.replace(pattern, '[redacted]');
+    }
+    return sanitized;
+}
+export function sanitizeTelemetryContent(text, maxLength = MAX_WORKFLOW_INPUT_LENGTH) {
+    const sanitized = redactSecrets(text);
+    if (sanitized.length > maxLength) {
+        return sanitized.slice(0, maxLength);
+    }
+    return sanitized;
+}
+export function sanitizeWorkflowInput(text) {
+    return sanitizeTelemetryContent(text, MAX_WORKFLOW_INPUT_LENGTH);
+}
+export async function readSanitizedFile(filePath, maxLength = MAX_ARTIFACT_BODY_LENGTH) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return sanitizeTelemetryContent(content, maxLength);
+}
+export async function readWorkflowInputFile(filePath) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return sanitizeWorkflowInput(content);
+}
+export function normalizeEditor(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (VALID_EDITORS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Invalid --editor "${value}". Use: ${VALID_EDITORS.join(', ')}.`);
+}
+export function resolveWorkflowInput(options) {
+    if (options.workflowInput !== undefined && options.workflowInputFile !== undefined) {
+        throw new Error('Pass only one of --workflow-input or --workflow-input-file.');
+    }
+    if (options.workflowInput !== undefined) {
+        const sanitized = sanitizeWorkflowInput(options.workflowInput);
+        return sanitized.length > 0 ? sanitized : undefined;
+    }
+    return undefined;
+}
+export async function resolveWorkflowInputAsync(options) {
+    if (options.workflowInput !== undefined && options.workflowInputFile !== undefined) {
+        throw new Error('Pass only one of --workflow-input or --workflow-input-file.');
+    }
+    if (options.workflowInputFile !== undefined) {
+        const sanitized = await readWorkflowInputFile(options.workflowInputFile);
+        return sanitized.length > 0 ? sanitized : undefined;
+    }
+    return resolveWorkflowInput(options);
+}
+//# sourceMappingURL=input.js.map

package/dist/telemetry/marker.d.ts

@@ -0,0 +1,31 @@
+export declare const CHANGE_TELEMETRY_FILENAME = ".openspec-telemetry.yaml";
+export type EntryPoint = 'propose' | 'new' | 'ff' | 'manual';
+export interface ChangeTelemetryMarker {
+    started_at?: string;
+    entry_point?: EntryPoint;
+    workflow_input?: string;
+    editor?: string;
+    git_head_at_start?: string;
+    proposal_ready_at?: string;
+    proposal_ready_emitted?: boolean;
+    apply_ready_emitted?: boolean;
+    artifact_hashes?: Record<string, string>;
+    artifact_body_cache?: Record<string, string>;
+    revision_counts?: Record<string, number>;
+    comprehension_attempt_count?: number;
+    comprehension_failure_count?: number;
+    comprehension_gate_last_emitted?: {
+        passed: boolean;
+        best_score_percent?: number;
+    };
+}
+export declare function markerPath(changeDir: string): string;
+export declare function readMarker(changeDir: string): Promise<ChangeTelemetryMarker>;
+export declare function writeMarker(changeDir: string, marker: ChangeTelemetryMarker): Promise<void>;
+export declare function updateMarker(changeDir: string, update: (current: ChangeTelemetryMarker) => ChangeTelemetryMarker): Promise<ChangeTelemetryMarker>;
+export declare function hashFileContent(content: string): string;
+export declare function hashFileAt(filePath: string): Promise<string | null>;
+export declare function durationSince(isoStart: string | undefined): number | undefined;
+export declare function durationBetween(isoStart: string | undefined, isoEnd: string | undefined): number | undefined;
+export declare function totalRevisions(marker: ChangeTelemetryMarker): number;
+//# sourceMappingURL=marker.d.ts.map

package/dist/telemetry/marker.js

@@ -0,0 +1,67 @@
+/**
+ * Change-local telemetry marker (.openspec-telemetry.yaml) for dedupe and durations.
+ */
+import { createHash } from 'crypto';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { parse, stringify } from 'yaml';
+export const CHANGE_TELEMETRY_FILENAME = '.openspec-telemetry.yaml';
+export function markerPath(changeDir) {
+    return path.join(changeDir, CHANGE_TELEMETRY_FILENAME);
+}
+export async function readMarker(changeDir) {
+    try {
+        const content = await fs.readFile(markerPath(changeDir), 'utf-8');
+        return parse(content) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeMarker(changeDir, marker) {
+    await fs.writeFile(markerPath(changeDir), stringify(marker), 'utf-8');
+}
+export async function updateMarker(changeDir, update) {
+    const current = await readMarker(changeDir);
+    const next = update(current);
+    await writeMarker(changeDir, next);
+    return next;
+}
+export function hashFileContent(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+export async function hashFileAt(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return hashFileContent(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function durationSince(isoStart) {
+    if (!isoStart) {
+        return undefined;
+    }
+    const start = Date.parse(isoStart);
+    if (Number.isNaN(start)) {
+        return undefined;
+    }
+    return Date.now() - start;
+}
+export function durationBetween(isoStart, isoEnd) {
+    if (!isoStart || !isoEnd) {
+        return undefined;
+    }
+    const start = Date.parse(isoStart);
+    const end = Date.parse(isoEnd);
+    if (Number.isNaN(start) || Number.isNaN(end)) {
+        return undefined;
+    }
+    return end - start;
+}
+export function totalRevisions(marker) {
+    const counts = marker.revision_counts ?? {};
+    return Object.values(counts).reduce((sum, n) => sum + (n ?? 0), 0);
+}
+//# sourceMappingURL=marker.js.map

package/dist/telemetry/workflow.d.ts

@@ -0,0 +1,75 @@
+import { type ChangeTelemetryMarker, type EntryPoint } from './marker.js';
+export declare function trackWorkflowStarted(params: {
+    changeDir: string;
+    changeName: string;
+    schema: string;
+    entryPoint: EntryPoint;
+    storeSelected: boolean;
+    projectRoot: string;
+    workflowInput?: string;
+    description?: string;
+    goal?: string;
+    editor?: string;
+}): Promise<void>;
+export declare function maybeEmitProposalReady(params: {
+    changeDir: string;
+    changeName: string;
+    schema: string;
+    missingArtifacts: string[];
+    artifactCount: number;
+    contextFiles?: Record<string, string[]>;
+}): Promise<void>;
+export declare function maybeEmitApplyReady(params: {
+    changeDir: string;
+    changeName: string;
+    state: string;
+    contextFiles?: Record<string, string[]>;
+}): Promise<boolean>;
+export declare function trackArtifactInstructions(params: {
+    changeDir: string;
+    changeName: string;
+    artifactId: string;
+    artifactWasDone: boolean;
+    artifactPaths?: string[];
+}): Promise<void>;
+export declare function trackArtifactContentChanges(params: {
+    changeDir: string;
+    changeName: string;
+    contextFiles: Record<string, string[]>;
+}): Promise<void>;
+interface SpecDeltaInfo {
+    capability: string;
+    counts: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+    deltaSpecLinesChanged?: number;
+}
+export declare function trackChangeArchived(params: {
+    changeDir: string;
+    changeName: string;
+    schema: string;
+    specsUpdated: boolean;
+    totals?: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+    tasksComplete: boolean;
+    specDeltas: SpecDeltaInfo[];
+    projectRoot: string;
+}): Promise<void>;
+export declare function buildSpecDeltasFromUpdates(specUpdates: Array<{
+    source: string;
+    counts: {
+        added: number;
+        modified: number;
+        removed: number;
+        renamed: number;
+    };
+}>): Promise<SpecDeltaInfo[]>;
+export type { ChangeTelemetryMarker, EntryPoint };
+//# sourceMappingURL=workflow.d.ts.map