@codewalla_india/openspec 1.3.1 → 1.3.2

package/dist/telemetry/identity.js

@@ -1,125 +1,170 @@
 /**
- * Codewalla telemetry identity — human-readable userId (email or username).
- * Stored globally at ~/.config/openspec/telemetry-identity.json (mode 0600).
+ * Identity management for telemetry.
+ *
+ * Handles identity collection, storage, validation, and retrieval.
+ * Identity is stored securely in a separate file with restricted permissions.
  */
-import { input } from '@inquirer/prompts';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { getGlobalConfigDir } from '../core/global-config.js';
-export const IDENTITY_FILENAME = 'telemetry-identity.json';
-const USERNAME_REGEX = /^[a-zA-Z0-9._-]{2,64}$/;
-const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-let cachedUserId = null;
-export class TelemetryIdentityRequiredError extends Error {
-    code = 'telemetry_identity_required';
-    constructor(message) {
-        super(message ?? buildIdentityRequiredMessage());
-        this.name = 'TelemetryIdentityRequiredError';
-    }
-}
-export function buildIdentityRequiredMessage() {
-    return (`Telemetry identity required. Run \`openspec init\` or \`openspec update\` interactively, ` +
-        `or create ${getIdentityFilePath()}.`);
+// Constants
+export const IDENTITY_FILE_NAME = 'telemetry-identity.json';
+/**
+ * Get the path to the identity file.
+ * Follows platform-specific config directory conventions.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+export function getIdentityPath() {
+    const configDir = getGlobalConfigDir();
+    return path.join(configDir, IDENTITY_FILE_NAME);
 }
-export function validateUserId(value) {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return 'Email or username is required';
-    }
-    if (EMAIL_REGEX.test(trimmed) || USERNAME_REGEX.test(trimmed)) {
-        return true;
+/**
+ * Read identity from file or environment variable.
+ * Environment variable takes precedence over file.
+ *
+ * @returns The identity string, or null if not configured
+ */
+export async function readIdentity() {
+    // Check environment variable first (highest priority)
+    const envIdentity = process.env.OPENSPEC_TELEMETRY_USER;
+    if (envIdentity) {
+        return envIdentity.trim();
     }
-    return 'Enter a valid email (user@example.com) or username (2–64 chars: letters, numbers, . _ -)';
-}
-export function getIdentityFilePath() {
-    return path.join(getGlobalConfigDir(), IDENTITY_FILENAME);
-}
-export async function readStoredUserId() {
+    // Fall back to file
+    const identityPath = getIdentityPath();
     try {
-        const content = await fs.readFile(getIdentityFilePath(), 'utf-8');
+        const content = await fs.readFile(identityPath, 'utf-8');
         const parsed = JSON.parse(content);
-        if (parsed.userId && validateUserId(parsed.userId) === true) {
-            return parsed.userId.trim();
+        return parsed.identity || null;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
         }
+        // If parse fails or another read error occurs, return null
+        return null;
+    }
+}
+/**
+ * Write identity to file with restricted permissions.
+ *
+ * @param identity - The identity string to write
+ */
+export async function writeIdentity(identity) {
+    const identityPath = getIdentityPath();
+    const identityDir = path.dirname(identityPath);
+    // Create directory if it doesn't exist
+    await fs.mkdir(identityDir, { recursive: true });
+    // Write identity file
+    await fs.writeFile(identityPath, JSON.stringify({ identity }, null, 2) + '\n');
+    // Set file permissions to 0600 (owner read/write only)
+    // This works on Unix-like systems; on Windows it's a no-op
+    try {
+        await fs.chmod(identityPath, 0o600);
     }
     catch {
-        // Missing or invalid file — treat as no identity
+        // Windows doesn't support chmod in the same way, but that's okay
+        // The file is still protected by OS-level permissions
     }
-    return null;
 }
-export async function writeStoredUserId(userId) {
-    const filePath = getIdentityFilePath();
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    const payload = { userId: userId.trim() };
-    await fs.writeFile(filePath, JSON.stringify(payload, null, 2) + '\n', { mode: 0o600 });
-    cachedUserId = userId.trim();
+/**
+ * Validate email format using RFC 5322 compliant pattern.
+ *
+ * @param email - The email string to validate
+ * @returns True if valid, false otherwise
+ */
+export function validateEmail(email) {
+    // Structural checks first
+    if (!email.includes('@'))
+        return false;
+    const parts = email.split('@');
+    if (parts.length !== 2)
+        return false;
+    if (parts[0].length === 0 || parts[1].length === 0)
+        return false;
+    // Domain must have at least one dot for a valid email format
+    if (!parts[1].includes('.'))
+        return false;
+    // RFC 5322 compliant email regex pattern
+    const emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+    return emailRegex.test(email);
 }
-export async function resolveTelemetryUserId(options) {
-    if (cachedUserId) {
-        return cachedUserId;
-    }
-    const envUser = process.env.OPENSPEC_TELEMETRY_USER?.trim();
-    if (envUser && validateUserId(envUser) === true) {
-        cachedUserId = envUser;
-        return envUser;
-    }
-    const stored = await readStoredUserId();
-    if (stored) {
-        cachedUserId = stored;
-        return stored;
-    }
-    if (options?.prompt === true) {
-        try {
-            return await promptAndStoreTelemetryIdentity();
-        }
-        catch (error) {
-            if (error instanceof TelemetryIdentityRequiredError) {
-                return null;
-            }
-            throw error;
-        }
-    }
-    return null;
+/**
+ * Validate username format.
+ * Username must be 3-32 characters, alphanumeric + underscores + hyphens.
+ *
+ * @param username - The username string to validate
+ * @returns True if valid, false otherwise
+ */
+export function validateUsername(username) {
+    const usernameRegex = /^[a-zA-Z0-9_-]{3,32}$/;
+    // Ensure @ is not allowed in usernames
+    if (username.includes('@'))
+        return false;
+    return usernameRegex.test(username);
 }
-export async function promptAndStoreTelemetryIdentity() {
-    const existing = await resolveTelemetryUserId({ prompt: false });
-    if (existing) {
-        return existing;
-    }
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw new TelemetryIdentityRequiredError();
-    }
-    console.log('Codewalla OpenSpec collects usage analytics tied to your email/username.');
-    const answer = await input({
-        message: 'Enter your Codewalla email or username:',
-        validate: validateUserId,
-    });
-    await writeStoredUserId(answer);
-    return answer.trim();
+/**
+ * Normalize identity input by trimming whitespace and converting to lowercase.
+ *
+ * @param identity - The identity string to normalize
+ * @returns The normalized identity string
+ */
+export function normalizeIdentity(identity) {
+    return identity.trim().toLowerCase();
 }
-export async function requireTelemetryIdentity() {
-    const userId = await resolveTelemetryUserId({ prompt: false });
-    if (!userId) {
-        throw new TelemetryIdentityRequiredError();
+/**
+ * Validate identity format (email or username).
+ *
+ * @param identity - The identity string to validate
+ * @returns Object with valid flag and error messages if invalid
+ */
+export function validateIdentity(identity) {
+    const errors = [];
+    if (!identity || identity.trim().length === 0) {
+        errors.push('Identity cannot be empty');
+        return { valid: false, errors };
     }
-    return userId;
-}
-export async function setupTelemetryIdentity(options) {
-    const existing = await resolveTelemetryUserId({ prompt: false });
-    if (existing) {
-        return existing;
+    const isEmail = validateEmail(identity);
+    const isUsername = validateUsername(identity);
+    // Must be either a valid email OR a valid username, not both
+    if (!isEmail && !isUsername) {
+        errors.push('Identity must be a valid email address or username (3-32 alphanumeric characters, underscores, or hyphens)');
     }
-    if (options.interactive) {
-        return promptAndStoreTelemetryIdentity();
+    // If it looks like an email (has @), ensure it's actually a valid email
+    if (identity.includes('@') && !isEmail) {
+        errors.push('Invalid email format');
     }
-    throw new TelemetryIdentityRequiredError();
-}
-/** @deprecated Use setupTelemetryIdentity or requireTelemetryIdentity */
-export async function ensureTelemetryIdentity() {
-    return resolveTelemetryUserId({ prompt: true });
+    // If it doesn't have @ and is not a valid username, reject
+    if (!identity.includes('@') && !isUsername) {
+        errors.push('Invalid username format');
+    }
+    return { valid: errors.length === 0, errors };
 }
-/** @internal Test helper */
-export function resetIdentityCacheForTests() {
-    cachedUserId = null;
+/**
+ * Interactive prompt for identity collection.
+ * Uses inquirer for consistent prompting with other OpenSpec commands.
+ *
+ * @returns The user's identity input
+ */
+export async function promptForIdentity() {
+    const { input } = await import('@inquirer/prompts');
+    const identity = await input({
+        message: 'Enter your identity for telemetry (email or username):',
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return 'Identity cannot be empty';
+            }
+            const normalized = normalizeIdentity(value);
+            const validation = validateIdentity(normalized);
+            if (!validation.valid) {
+                return validation.errors[0];
+            }
+            return true;
+        },
+    });
+    return normalizeIdentity(identity);
 }
 //# sourceMappingURL=identity.js.map

package/dist/telemetry/index.d.ts

@@ -1,17 +1,128 @@
-import type { CommandTelemetryContext } from './command-context.js';
-export declare function canSendTelemetry(): Promise<boolean>;
-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, type WorkflowEditor, } from './input.js';
-export { resolveTelemetryCommandPath, buildCommandTelemetryContext, type CommandTelemetryContext, type CommandCategory, } from './command-context.js';
-export { resolveCaller } from './caller.js';
-export declare function trackCommand(commandName: string, version: string, context?: CommandTelemetryContext): Promise<void>;
-export declare function trackEvent(event: string, properties?: Record<string, unknown>): Promise<void>;
-export declare function trackCommandFailed(command: string, error: unknown, errorCode?: string): Promise<void>;
+/**
+ * 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 declare function isTelemetryEnabled(): boolean;
+/**
+ * Get the user identity for telemetry.
+ * Reads from identity file or environment variable.
+ */
+export declare function getIdentity(): Promise<string | null>;
+/**
+ * Track a command execution.
+ *
+ * @param commandName - The command name (e.g., 'init', 'change:apply')
+ * @param version - The OpenSpec version
+ */
+export declare function trackCommand(commandName: string, version: string): Promise<void>;
+/**
+ * Track a comprehension quiz attempt.
+ *
+ * @param changeName - The name of the change
+ * @param attemptNumber - The attempt number
+ */
+export declare function trackComprehensionAttempt(changeName: string, attemptNumber: number): Promise<void>;
+/**
+ * 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 declare function trackComprehensionCompletion(changeName: string, scorePercent: number, result: 'pass' | 'fail', attemptNumber: number): Promise<void>;
+/**
+ * Track when apply becomes ready after quiz pass.
+ *
+ * @param changeName - The name of the the change
+ */
+export declare function trackApplyReady(changeName: string): Promise<void>;
+/**
+ * Track artifact modification request.
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact being modified
+ */
+export declare function trackArtifactModifyRequested(changeName: string, artifactId: string): Promise<void>;
+/**
+ * Track artifact revision request (when downstream artifacts need regeneration).
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact being regenerated
+ */
+export declare function trackArtifactRevisionRequested(changeName: string, artifactId: string): Promise<void>;
+/**
+ * Track artifact content change.
+ *
+ * @param changeName - The name of the change
+ * @param artifactId - The artifact whose content changed
+ */
+export declare function trackArtifactContentChanged(changeName: string, artifactId: string): Promise<void>;
+/**
+ * Track workflow started event (when a new change is created).
+ *
+ * @param changeName - The name of the change
+ * @param workflowInput - Optional workflow input data
+ */
+export declare function trackWorkflowStarted(changeName: string, workflowInput?: Record<string, unknown>): Promise<void>;
+/**
+ * Track change proposal ready event (when proposal artifact is created).
+ *
+ * @param changeName - The name of the change
+ */
+export declare function trackChangeProposalReady(changeName: string): Promise<void>;
+/**
+ * Track change archived event (when a change is archived).
+ *
+ * @param changeName - The name of the change
+ */
+export declare function trackChangeArchived(changeName: string): Promise<void>;
+/**
+ * Track store operation event.
+ *
+ * @param operation - The store operation (add, remove, list, register, unregister, doctor)
+ * @param storeId - Optional store ID
+ */
+export declare function trackStoreOperation(operation: 'add' | 'remove' | 'list' | 'register' | 'unregister' | 'doctor', storeId?: string): Promise<void>;
+/**
+ * Track workset operation event.
+ *
+ * @param operation - The workset operation (create, list, open, remove)
+ * @param worksetName - Optional workset name
+ */
+export declare function trackWorksetOperation(operation: 'create' | 'list' | 'open' | 'remove', worksetName?: string): Promise<void>;
+/**
+ * Track validation operation event.
+ *
+ * @param changeName - The change name being validated
+ * @param result - Validation result (valid, invalid, warnings)
+ */
+export declare function trackValidationOperation(changeName: string, result: 'valid' | 'invalid' | 'warnings'): Promise<void>;
+/**
+ * Track config change event.
+ *
+ * @param operation - The config operation (set, unset)
+ * @param key - The config key being changed
+ */
+export declare function trackConfigChange(operation: 'set' | 'unset', key: string): Promise<void>;
+/**
+ * Track feedback submission event.
+ *
+ * @param category - Feedback category
+ */
+export declare function trackFeedbackSubmission(category: string): Promise<void>;
+/**
+ * Show first-run telemetry notice if not already seen.
+ */
+export declare function maybeShowTelemetryNotice(): Promise<void>;
+/**
+ * Flush pending telemetry events.
+ * Call this before CLI exit.
+ */
 export declare function shutdown(): Promise<void>;
-/** @internal Test helper */
-export declare function resetTelemetryForTests(): void;
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
-export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
-export type { EntryPoint } from './marker.js';
 //# sourceMappingURL=index.d.ts.map