@codewalla_india/openspec 1.0.6 → 1.2.0

package/dist/telemetry/config.d.ts

@@ -1,38 +1,11 @@
 export declare const CONFIG_DIR_NAME = "openspec";
 export declare const CONFIG_FILE_NAME = "config.json";
-export interface TelemetryConfig {
-    anonymousId?: string;
-    noticeSeen?: boolean;
-}
 export interface GlobalConfig {
-    telemetry?: TelemetryConfig;
     [key: string]: unknown;
 }
-/**
- * Get the path to the global config file.
- * Follows XDG Base Directory Specification and platform conventions.
- *
- * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
- * - Unix/macOS fallback: ~/.config/openspec/
- * - Windows fallback: %APPDATA%/openspec/
- */
 export declare function getConfigPath(): string;
-/**
- * Read the global config file.
- * Returns an empty object if the file doesn't exist.
- */
 export declare function readConfig(): Promise<GlobalConfig>;
-/**
- * Write to the global config file.
- * Preserves existing fields and merges in new values.
- */
 export declare function writeConfig(updates: Partial<GlobalConfig>): Promise<void>;
-/**
- * Get the telemetry config section.
- */
-export declare function getTelemetryConfig(): Promise<TelemetryConfig>;
-/**
- * Update the telemetry config section.
- */
-export declare function updateTelemetryConfig(updates: Partial<TelemetryConfig>): Promise<void>;
+export declare function getTelemetryConfig(): Promise<Record<string, unknown>>;
+export declare function updateTelemetryConfig(updates: Record<string, unknown>): Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.js

@@ -1,20 +1,15 @@
 /**
- * Global configuration for telemetry state.
- * Stores anonymous ID and notice-seen flag in the platform-appropriate config directory.
+ * Global configuration for OpenSpec CLI state.
+ * Stores settings in the platform-appropriate config directory.
  */
 import { promises as fs } from 'fs';
 import path from 'path';
-import os from 'os';
 import { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, getGlobalConfigDir, } from '../core/global-config.js';
-// Constants
 export const CONFIG_DIR_NAME = GLOBAL_CONFIG_DIR_NAME;
 export const CONFIG_FILE_NAME = GLOBAL_CONFIG_FILE_NAME;
 function getConfigDir() {
     return getGlobalConfigDir();
 }
-function getLegacyConfigPath() {
-    return path.join(os.homedir(), '.config', CONFIG_DIR_NAME, CONFIG_FILE_NAME);
-}
 async function readConfigFile(configPath) {
     try {
         const content = await fs.readFile(configPath, 'utf-8');
@@ -24,7 +19,6 @@ async function readConfigFile(configPath) {
         if (error.code === 'ENOENT') {
             return { status: 'missing' };
         }
-        // If parse fails or another read error occurs, ignore the file.
         return { status: 'invalid', config: {} };
     }
 }
@@ -32,101 +26,31 @@ async function writeConfigFile(configPath, config) {
     await fs.mkdir(path.dirname(configPath), { recursive: true });
     await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
 }
-function hasMissingTelemetryFields(config) {
-    const telemetry = config.telemetry;
-    return (!telemetry ||
-        telemetry.anonymousId === undefined ||
-        telemetry.noticeSeen === undefined);
-}
-function mergeLegacyTelemetry(config, legacyConfig) {
-    const legacyTelemetry = legacyConfig.telemetry;
-    if (!legacyTelemetry) {
-        return undefined;
-    }
-    const currentTelemetry = config.telemetry ?? {};
-    const shouldMigrate = (currentTelemetry.anonymousId === undefined && legacyTelemetry.anonymousId !== undefined) ||
-        (currentTelemetry.noticeSeen === undefined && legacyTelemetry.noticeSeen !== undefined);
-    if (!shouldMigrate) {
-        return undefined;
-    }
-    return {
-        ...config,
-        telemetry: {
-            ...legacyTelemetry,
-            ...currentTelemetry,
-        },
-    };
-}
-async function migrateLegacyTelemetryConfig(configPath, config, persist) {
-    const legacyConfigPath = getLegacyConfigPath();
-    if (path.resolve(configPath) === path.resolve(legacyConfigPath) || !hasMissingTelemetryFields(config)) {
-        return config;
-    }
-    const legacyRead = await readConfigFile(legacyConfigPath);
-    if (legacyRead.status !== 'ok') {
-        return config;
-    }
-    const migrated = mergeLegacyTelemetry(config, legacyRead.config);
-    if (!migrated) {
-        return config;
-    }
-    if (persist) {
-        try {
-            await writeConfigFile(configPath, migrated);
-        }
-        catch {
-            // Preserve telemetry for this run even if the one-time migration cannot be persisted.
-        }
-    }
-    return migrated;
-}
-/**
- * Get the path to the global config file.
- * Follows XDG Base Directory Specification and platform conventions.
- *
- * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
- * - Unix/macOS fallback: ~/.config/openspec/
- * - Windows fallback: %APPDATA%/openspec/
- */
 export function getConfigPath() {
-    const configDir = getConfigDir();
-    return path.join(configDir, CONFIG_FILE_NAME);
+    return path.join(getConfigDir(), CONFIG_FILE_NAME);
 }
-/**
- * Read the global config file.
- * Returns an empty object if the file doesn't exist.
- */
 export async function readConfig() {
     const configPath = getConfigPath();
     const read = await readConfigFile(configPath);
-    const config = read.status === 'ok' ? read.config : {};
-    return migrateLegacyTelemetryConfig(configPath, config, read.status !== 'invalid');
+    return read.status === 'ok' ? read.config : {};
 }
-/**
- * Write to the global config file.
- * Preserves existing fields and merges in new values.
- */
 export async function writeConfig(updates) {
     const configPath = getConfigPath();
-    // Read existing config and merge
     const existing = await readConfig();
     const merged = { ...existing, ...updates };
-    // Deep merge for telemetry object
-    if (updates.telemetry && existing.telemetry) {
-        merged.telemetry = { ...existing.telemetry, ...updates.telemetry };
+    if (updates.telemetry && existing.telemetry && typeof existing.telemetry === 'object') {
+        merged.telemetry = {
+            ...existing.telemetry,
+            ...updates.telemetry,
+        };
     }
     await writeConfigFile(configPath, merged);
 }
-/**
- * Get the telemetry config section.
- */
 export async function getTelemetryConfig() {
     const config = await readConfig();
-    return config.telemetry ?? {};
+    const telemetry = config.telemetry;
+    return telemetry && typeof telemetry === 'object' ? telemetry : {};
 }
-/**
- * Update the telemetry config section.
- */
 export async function updateTelemetryConfig(updates) {
     const existing = await getTelemetryConfig();
     await writeConfig({

package/dist/telemetry/content.d.ts

@@ -0,0 +1,10 @@
+export declare function toChangeRelativePaths(changeDir: string, absolutePaths: string[]): string[];
+export declare function readPrimaryArtifactBody(changeDir: string, absolutePaths: string[]): Promise<string | undefined>;
+export declare function collectArtifactPathsMap(changeDir: string, contextFiles: Record<string, string[]>): Promise<Record<string, string[]>>;
+export declare function collectArtifactBodiesMap(changeDir: string, contextFiles: Record<string, string[]>): Promise<Record<string, string>>;
+export declare function readSanitizedFileAt(filePath: string, maxLength?: number): Promise<string | undefined>;
+export declare function sanitizeErrorForTelemetry(error: unknown): {
+    error_message: string;
+    stack_trace?: string;
+};
+//# sourceMappingURL=content.d.ts.map

package/dist/telemetry/content.js

@@ -0,0 +1,56 @@
+import path from 'path';
+import { MAX_ARTIFACT_BODY_LENGTH, readSanitizedFile, sanitizeTelemetryContent, } from './input.js';
+export function toChangeRelativePaths(changeDir, absolutePaths) {
+    return absolutePaths.map((filePath) => {
+        const relative = path.relative(changeDir, filePath);
+        return relative.split(path.sep).join('/');
+    });
+}
+export async function readPrimaryArtifactBody(changeDir, absolutePaths) {
+    const primary = absolutePaths[0];
+    if (!primary) {
+        return undefined;
+    }
+    try {
+        return await readSanitizedFile(primary, MAX_ARTIFACT_BODY_LENGTH);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function collectArtifactPathsMap(changeDir, contextFiles) {
+    const result = {};
+    for (const [artifactId, paths] of Object.entries(contextFiles)) {
+        if (paths.length > 0) {
+            result[artifactId] = toChangeRelativePaths(changeDir, paths);
+        }
+    }
+    return result;
+}
+export async function collectArtifactBodiesMap(changeDir, contextFiles) {
+    const bodies = {};
+    for (const [artifactId, paths] of Object.entries(contextFiles)) {
+        const body = await readPrimaryArtifactBody(changeDir, paths);
+        if (body) {
+            bodies[artifactId] = body;
+        }
+    }
+    return bodies;
+}
+export async function readSanitizedFileAt(filePath, maxLength = MAX_ARTIFACT_BODY_LENGTH) {
+    try {
+        return await readSanitizedFile(filePath, maxLength);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function sanitizeErrorForTelemetry(error) {
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'unknown error';
+    const stack = error instanceof Error ? error.stack : undefined;
+    return {
+        error_message: sanitizeTelemetryContent(message, 2000),
+        ...(stack ? { stack_trace: sanitizeTelemetryContent(stack, 8000) } : {}),
+    };
+}
+//# sourceMappingURL=content.js.map

package/dist/telemetry/git-stats.d.ts

@@ -0,0 +1,12 @@
+export interface GitDiffStats {
+    files_changed: number;
+    lines_added: number;
+    lines_removed: number;
+    lines_changed: number;
+}
+export declare function captureGitHead(cwd: string): Promise<string | null>;
+/**
+ * Diff working tree (including staged/unstaged) against ref.
+ */
+export declare function diffStatsSince(ref: string, cwd: string, excludeOpenspec?: boolean): Promise<GitDiffStats | null>;
+//# sourceMappingURL=git-stats.d.ts.map

package/dist/telemetry/git-stats.js

@@ -0,0 +1,69 @@
+/**
+ * Best-effort git stats for implementation_changed telemetry.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+export async function captureGitHead(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            timeout: 2000,
+        });
+        const head = stdout.trim();
+        return head || null;
+    }
+    catch {
+        return null;
+    }
+}
+function shouldExcludePath(filePath, excludeOpenspec) {
+    if (!excludeOpenspec) {
+        return false;
+    }
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized.startsWith('openspec/') || normalized.includes('/openspec/');
+}
+/**
+ * Diff working tree (including staged/unstaged) against ref.
+ */
+export async function diffStatsSince(ref, cwd, excludeOpenspec = true) {
+    try {
+        const { stdout } = await execFileAsync('git', ['diff', '--numstat', ref], {
+            cwd,
+            timeout: 5000,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        let filesChanged = 0;
+        let linesAdded = 0;
+        let linesRemoved = 0;
+        for (const line of stdout.split('\n')) {
+            if (!line.trim()) {
+                continue;
+            }
+            const parts = line.split('\t');
+            if (parts.length < 3) {
+                continue;
+            }
+            const filePath = parts[2];
+            if (shouldExcludePath(filePath, excludeOpenspec)) {
+                continue;
+            }
+            filesChanged++;
+            const added = parts[0] === '-' ? 0 : parseInt(parts[0], 10);
+            const removed = parts[1] === '-' ? 0 : parseInt(parts[1], 10);
+            linesAdded += Number.isNaN(added) ? 0 : added;
+            linesRemoved += Number.isNaN(removed) ? 0 : removed;
+        }
+        return {
+            files_changed: filesChanged,
+            lines_added: linesAdded,
+            lines_removed: linesRemoved,
+            lines_changed: linesAdded + linesRemoved,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=git-stats.js.map

package/dist/telemetry/identify-cache.d.ts

@@ -0,0 +1,7 @@
+export declare const IDENTIFY_STATE_FILENAME = "telemetry-identify-state.json";
+export declare function getIdentifyStatePath(): string;
+export declare function shouldIdentifyUser(userId: string): Promise<boolean>;
+export declare function markUserIdentified(userId: string): Promise<void>;
+/** @internal Test helper */
+export declare function clearIdentifyStateForTests(): Promise<void>;
+//# sourceMappingURL=identify-cache.d.ts.map

package/dist/telemetry/identify-cache.js

@@ -0,0 +1,47 @@
+/**
+ * Cross-process throttle for PostHog identify() calls.
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { getGlobalConfigDir } from '../core/global-config.js';
+export const IDENTIFY_STATE_FILENAME = 'telemetry-identify-state.json';
+const IDENTIFY_TTL_MS = 24 * 60 * 60 * 1000;
+export function getIdentifyStatePath() {
+    return path.join(getGlobalConfigDir(), IDENTIFY_STATE_FILENAME);
+}
+export async function shouldIdentifyUser(userId) {
+    try {
+        const content = await fs.readFile(getIdentifyStatePath(), 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed.userId !== userId || !parsed.identifiedAt) {
+            return true;
+        }
+        const identifiedAt = Date.parse(parsed.identifiedAt);
+        if (Number.isNaN(identifiedAt)) {
+            return true;
+        }
+        return Date.now() - identifiedAt >= IDENTIFY_TTL_MS;
+    }
+    catch {
+        return true;
+    }
+}
+export async function markUserIdentified(userId) {
+    const dir = getGlobalConfigDir();
+    await fs.mkdir(dir, { recursive: true });
+    const state = {
+        userId,
+        identifiedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(getIdentifyStatePath(), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+/** @internal Test helper */
+export async function clearIdentifyStateForTests() {
+    try {
+        await fs.unlink(getIdentifyStatePath());
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=identify-cache.js.map

package/dist/telemetry/identity.d.ts

@@ -0,0 +1,23 @@
+export declare const IDENTITY_FILENAME = "telemetry-identity.json";
+export declare class TelemetryIdentityRequiredError extends Error {
+    readonly code = "telemetry_identity_required";
+    constructor(message?: string);
+}
+export declare function buildIdentityRequiredMessage(): string;
+export declare function validateUserId(value: string): true | string;
+export declare function getIdentityFilePath(): string;
+export declare function readStoredUserId(): Promise<string | null>;
+export declare function writeStoredUserId(userId: string): Promise<void>;
+export declare function resolveTelemetryUserId(options?: {
+    prompt?: boolean;
+}): Promise<string | null>;
+export declare function promptAndStoreTelemetryIdentity(): Promise<string>;
+export declare function requireTelemetryIdentity(): Promise<string>;
+export declare function setupTelemetryIdentity(options: {
+    interactive: boolean;
+}): Promise<string>;
+/** @deprecated Use setupTelemetryIdentity or requireTelemetryIdentity */
+export declare function ensureTelemetryIdentity(): Promise<string | null>;
+/** @internal Test helper */
+export declare function resetIdentityCacheForTests(): void;
+//# sourceMappingURL=identity.d.ts.map

package/dist/telemetry/identity.js

@@ -0,0 +1,125 @@
+/**
+ * Codewalla telemetry identity — human-readable userId (email or username).
+ * Stored globally at ~/.config/openspec/telemetry-identity.json (mode 0600).
+ */
+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()}.`);
+}
+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;
+    }
+    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() {
+    try {
+        const content = await fs.readFile(getIdentityFilePath(), 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed.userId && validateUserId(parsed.userId) === true) {
+            return parsed.userId.trim();
+        }
+    }
+    catch {
+        // Missing or invalid file — treat as no identity
+    }
+    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();
+}
+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;
+}
+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();
+}
+export async function requireTelemetryIdentity() {
+    const userId = await resolveTelemetryUserId({ prompt: false });
+    if (!userId) {
+        throw new TelemetryIdentityRequiredError();
+    }
+    return userId;
+}
+export async function setupTelemetryIdentity(options) {
+    const existing = await resolveTelemetryUserId({ prompt: false });
+    if (existing) {
+        return existing;
+    }
+    if (options.interactive) {
+        return promptAndStoreTelemetryIdentity();
+    }
+    throw new TelemetryIdentityRequiredError();
+}
+/** @deprecated Use setupTelemetryIdentity or requireTelemetryIdentity */
+export async function ensureTelemetryIdentity() {
+    return resolveTelemetryUserId({ prompt: true });
+}
+/** @internal Test helper */
+export function resetIdentityCacheForTests() {
+    cachedUserId = null;
+}
+//# sourceMappingURL=identity.js.map

package/dist/telemetry/index.d.ts

@@ -1,31 +1,17 @@
-/**
- * Check if telemetry is enabled.
- *
- * Disabled when:
- * - OPENSPEC_TELEMETRY=0
- * - DO_NOT_TRACK=1
- * - CI=true (any CI environment)
- */
-export declare function isTelemetryEnabled(): boolean;
-/**
- * Get or create the anonymous user ID.
- * Lazily generates a UUID on first call and persists it.
- */
-export declare function getOrCreateAnonymousId(): Promise<string>;
-/**
- * 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>;
-/**
- * Show first-run telemetry notice if not already seen.
- */
-export declare function maybeShowTelemetryNotice(): Promise<void>;
-/**
- * Shutdown the PostHog client and flush pending events.
- * Call this before CLI exit.
- */
+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>;
 export declare function shutdown(): Promise<void>;
+/** @internal Test helper */
+export declare function resetTelemetryForTests(): void;
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, 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