@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/core/view.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import chalk from 'chalk';
 import { getTaskProgressForChange } from '../utils/task-progress.js';
 import { MarkdownParser } from './parsers/markdown-parser.js';
+import { discoverSpecFiles } from '../utils/spec-discovery.js';
 export class ViewCommand {
     async execute(targetPath = '.') {
         const openspecDir = path.join(targetPath, 'openspec');
@@ -70,7 +71,7 @@ export class ViewCommand {
         const entries = fs.readdirSync(changesDir, { withFileTypes: true });
         for (const entry of entries) {
             if (entry.isDirectory() && entry.name !== 'archive') {
-                const progress = await getTaskProgressForChange(changesDir, entry.name);
+                const progress = await getTaskProgressForChange(changesDir, entry.name, path.dirname(openspecDir));
                 if (progress.total === 0) {
                     // No tasks defined yet - still in planning/draft phase
                     draft.push({ name: entry.name });
@@ -106,23 +107,17 @@ export class ViewCommand {
             return [];
         }
         const specs = [];
-        const entries = fs.readdirSync(specsDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                const specFile = path.join(specsDir, entry.name, 'spec.md');
-                if (fs.existsSync(specFile)) {
-                    try {
-                        const content = fs.readFileSync(specFile, 'utf-8');
-                        const parser = new MarkdownParser(content);
-                        const spec = parser.parseSpec(entry.name);
-                        const requirementCount = spec.requirements.length;
-                        specs.push({ name: entry.name, requirementCount });
-                    }
-                    catch (error) {
-                        // If spec cannot be parsed, include with 0 count
-                        specs.push({ name: entry.name, requirementCount: 0 });
-                    }
-                }
+        for (const { id, specFile } of await discoverSpecFiles(specsDir)) {
+            try {
+                const content = fs.readFileSync(specFile, 'utf-8');
+                const parser = new MarkdownParser(content);
+                const spec = parser.parseSpec(id);
+                const requirementCount = spec.requirements.length;
+                specs.push({ name: id, requirementCount });
+            }
+            catch (error) {
+                // If spec cannot be parsed, include with 0 count
+                specs.push({ name: id, requirementCount: 0 });
             }
         }
         return specs;

package/dist/prompts/searchable-multi-select.js

@@ -113,7 +113,7 @@ async function createSearchableMultiSelect() {
                 const actualIndex = startIndex + i;
                 const isActive = actualIndex === cursor;
                 const selected = selectedSet.has(item.value);
-                const icon = selected ? chalk.green('◉') : chalk.dim('○');
+                const icon = selected ? chalk.green('[x]') : chalk.dim('[ ]');
                 const arrow = isActive ? chalk.cyan('›') : ' ';
                 const name = isActive ? chalk.cyan(item.name) : item.name;
                 const isRefresh = selected && item.configured;

package/dist/telemetry/caller-detection.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Caller detection module for telemetry.
+ *
+ * Detects the caller type (human, automation, ci, devin, cursor-agent, windsurf)
+ * from environment fingerprints and includes this information in all telemetry events.
+ */
+/**
+ * Detect the caller type from environment fingerprints.
+ *
+ * Priority order:
+ * 1. Manual override via OPENSPEC_CALLER environment variable
+ * 2. Agent-specific detection (Devin, Cursor, Windsurf)
+ * 3. CI environment detection
+ * 4. TTY detection (interactive terminal)
+ * 5. Default to human if TTY present, else automation
+ *
+ * @returns The detected caller type
+ */
+export declare function detectCaller(): string;
+/**
+ * Validate a caller type against the allowed set.
+ *
+ * @param callerType - The caller type to validate
+ * @returns True if valid, false otherwise
+ */
+export declare function isValidCallerType(callerType: string): boolean;
+//# sourceMappingURL=caller-detection.d.ts.map

package/dist/telemetry/caller-detection.js

@@ -0,0 +1,85 @@
+/**
+ * Caller detection module for telemetry.
+ *
+ * Detects the caller type (human, automation, ci, devin, cursor-agent, windsurf)
+ * from environment fingerprints and includes this information in all telemetry events.
+ */
+import { isCiEnvironment } from '../utils/ci.js';
+// Allowed caller types
+const ALLOWED_CALLER_TYPES = new Set([
+    'human',
+    'automation',
+    'ci',
+    'devin',
+    'cursor-agent',
+    'windsurf',
+]);
+/**
+ * Detect the caller type from environment fingerprints.
+ *
+ * Priority order:
+ * 1. Manual override via OPENSPEC_CALLER environment variable
+ * 2. Agent-specific detection (Devin, Cursor, Windsurf)
+ * 3. CI environment detection
+ * 4. TTY detection (interactive terminal)
+ * 5. Default to human if TTY present, else automation
+ *
+ * @returns The detected caller type
+ */
+export function detectCaller() {
+    // 1. Manual override (highest priority)
+    const manualOverride = process.env.OPENSPEC_CALLER;
+    if (manualOverride) {
+        const normalized = manualOverride.trim().toLowerCase();
+        if (ALLOWED_CALLER_TYPES.has(normalized)) {
+            return normalized;
+        }
+        // Invalid override, fall through to auto-detection
+    }
+    // 2. Agent-specific detection (placeholders for research)
+    // TODO: Research actual environment variable fingerprints for Devin, Cursor, Windsurf
+    const agentType = detectAgent();
+    if (agentType) {
+        return agentType;
+    }
+    // 3. CI environment detection
+    if (isCiEnvironment()) {
+        return 'ci';
+    }
+    // 4. TTY detection
+    if (process.stdout.isTTY) {
+        return 'human';
+    }
+    // 5. Default to automation
+    return 'automation';
+}
+/**
+ * Detect AI coding agent from environment variables.
+ *
+ * @returns The agent type if detected, null otherwise
+ */
+function detectAgent() {
+    // TODO: Research and implement actual environment variable fingerprints
+    // for Devin, Cursor, and Windsurf agents
+    // Placeholder implementations (to be replaced with actual detection logic)
+    if (process.env.DEVIN_AGENT === 'true') {
+        return 'devin';
+    }
+    if (process.env.CURSOR_AGENT === 'true') {
+        return 'cursor-agent';
+    }
+    if (process.env.WINDSURF_AGENT === 'true') {
+        return 'windsurf';
+    }
+    return null;
+}
+/**
+ * Validate a caller type against the allowed set.
+ *
+ * @param callerType - The caller type to validate
+ * @returns True if valid, false otherwise
+ */
+export function isValidCallerType(callerType) {
+    return ALLOWED_CALLER_TYPES.has(callerType.trim().toLowerCase());
+}
+//# sourceMappingURL=caller-detection.js.map

package/dist/telemetry/caller-detection.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for caller detection module.
+ */
+export {};
+//# sourceMappingURL=caller-detection.test.d.ts.map

package/dist/telemetry/config.d.ts

@@ -1,11 +1,57 @@
+import { type TelemetryConfig } from '../core/global-config.js';
 export declare const CONFIG_DIR_NAME = "openspec";
 export declare const CONFIG_FILE_NAME = "config.json";
+export declare const IDENTITY_FILE_NAME = "telemetry-identity.json";
+export declare const DEFAULT_POSTHOG_API_KEY = "phc_s56WNC4SgBSQBqa5jgZ22MpCmxv5rUsAy4g6MikQaZtD";
+export declare const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
+/** Re-export shared telemetry section type (single source of truth in global-config). */
+export type { TelemetryConfig };
 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;
+/**
+ * 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 declare function getIdentityFilePath(): 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>;
-export declare function getTelemetryConfig(): Promise<Record<string, unknown>>;
-export declare function updateTelemetryConfig(updates: Record<string, unknown>): Promise<void>;
+/**
+ * Get the telemetry config section.
+ */
+export declare function getTelemetryConfig(): Promise<TelemetryConfig>;
+/**
+ * Get the PostHog API key from environment variable or default.
+ */
+export declare function getPostHogApiKey(): string;
+/**
+ * Get the PostHog host from environment variable or default.
+ */
+export declare function getPostHogHost(): string;
+/**
+ * Update the telemetry config section.
+ */
+export declare function updateTelemetryConfig(updates: Partial<TelemetryConfig>): Promise<void>;
 //# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.js

@@ -1,15 +1,24 @@
 /**
- * Global configuration for OpenSpec CLI state.
- * Stores settings in the platform-appropriate config directory.
+ * Global configuration for telemetry state.
+ * Stores anonymous ID and notice-seen flag 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;
+export const IDENTITY_FILE_NAME = 'telemetry-identity.json';
+// PostHog configuration defaults
+export const DEFAULT_POSTHOG_API_KEY = 'phc_s56WNC4SgBSQBqa5jgZ22MpCmxv5rUsAy4g6MikQaZtD';
+export const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
 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');
@@ -19,6 +28,7 @@ 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: {} };
     }
 }
@@ -26,31 +36,123 @@ 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.noticeSeen === undefined);
+}
+function mergeLegacyTelemetry(config, legacyConfig) {
+    const legacyTelemetry = legacyConfig.telemetry;
+    if (!legacyTelemetry) {
+        return undefined;
+    }
+    const currentTelemetry = config.telemetry ?? {};
+    const shouldMigrate = (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() {
-    return path.join(getConfigDir(), CONFIG_FILE_NAME);
+    const configDir = getConfigDir();
+    return path.join(configDir, CONFIG_FILE_NAME);
 }
+/**
+ * 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 getIdentityFilePath() {
+    const configDir = getConfigDir();
+    return path.join(configDir, IDENTITY_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);
-    return read.status === 'ok' ? read.config : {};
+    const config = read.status === 'ok' ? read.config : {};
+    return migrateLegacyTelemetryConfig(configPath, config, read.status !== 'invalid');
 }
+/**
+ * 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 };
-    if (updates.telemetry && existing.telemetry && typeof existing.telemetry === 'object') {
-        merged.telemetry = {
-            ...existing.telemetry,
-            ...updates.telemetry,
-        };
+    // Deep merge for telemetry object
+    if (updates.telemetry && existing.telemetry) {
+        merged.telemetry = { ...existing.telemetry, ...updates.telemetry };
     }
     await writeConfigFile(configPath, merged);
 }
+/**
+ * Get the telemetry config section.
+ */
 export async function getTelemetryConfig() {
     const config = await readConfig();
-    const telemetry = config.telemetry;
-    return telemetry && typeof telemetry === 'object' ? telemetry : {};
+    return config.telemetry ?? {};
 }
+/**
+ * Get the PostHog API key from environment variable or default.
+ */
+export function getPostHogApiKey() {
+    return process.env.POSTHOG_API_KEY || DEFAULT_POSTHOG_API_KEY;
+}
+/**
+ * Get the PostHog host from environment variable or default.
+ */
+export function getPostHogHost() {
+    return process.env.POSTHOG_HOST || DEFAULT_POSTHOG_HOST;
+}
+/**
+ * Update the telemetry config section.
+ */
 export async function updateTelemetryConfig(updates) {
     const existing = await getTelemetryConfig();
     await writeConfig({

package/dist/telemetry/config.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for PostHog configuration.
+ */
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/telemetry/deduplication.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Event deduplication module for telemetry.
+ *
+ * Prevents duplicate event emission through:
+ * - Time-based throttling for $identify calls (24h window)
+ * - State-based deduplication for gate events
+ * - Rapid duplicate prevention for general events
+ */
+/**
+ * Check if an $identify call should be throttled for a given user.
+ *
+ * @param userId - The anonymous user ID
+ * @returns True if the call should be throttled (not sent), false otherwise
+ */
+export declare function shouldThrottleIdentify(userId: string): boolean;
+/**
+ * Check if a gate event should be deduplicated based on state comparison.
+ *
+ * @param eventKey - Unique key for the gate event (e.g., "comprehension_gate_checked:change-name")
+ * @param currentState - The current state of the gate
+ * @returns True if the event should be deduplicated (not sent), false otherwise
+ */
+export declare function shouldDeduplicateGateEvent(eventKey: string, currentState: string): boolean;
+/**
+ * Check if a general event should be deduplicated due to rapid succession.
+ *
+ * @param eventKey - Unique key for the event (e.g., "command_executed:init")
+ * @returns True if the event should be deduplicated (not sent), false otherwise
+ */
+export declare function shouldDeduplicateRapidEvent(eventKey: string): boolean;
+/**
+ * Clear deduplication state (useful for testing or session reset).
+ */
+export declare function clearDeduplicationState(): void;
+//# sourceMappingURL=deduplication.d.ts.map

package/dist/telemetry/deduplication.js

@@ -0,0 +1,82 @@
+/**
+ * Event deduplication module for telemetry.
+ *
+ * Prevents duplicate event emission through:
+ * - Time-based throttling for $identify calls (24h window)
+ * - State-based deduplication for gate events
+ * - Rapid duplicate prevention for general events
+ */
+// In-memory state for session-level deduplication
+const identifyThrottleState = new Map();
+const gateEventState = new Map();
+const recentEvents = new Map();
+const IDENTIFY_THROTTLE_MS = 24 * 60 * 60 * 1000; // 24 hours
+const RAPID_DUPLICATE_WINDOW_MS = 1000; // 1 second
+/**
+ * Check if an $identify call should be throttled for a given user.
+ *
+ * @param userId - The anonymous user ID
+ * @returns True if the call should be throttled (not sent), false otherwise
+ */
+export function shouldThrottleIdentify(userId) {
+    const now = Date.now();
+    const lastIdentify = identifyThrottleState.get(userId);
+    if (lastIdentify === undefined) {
+        identifyThrottleState.set(userId, now);
+        return false;
+    }
+    const timeSinceLastIdentify = now - lastIdentify;
+    if (timeSinceLastIdentify < IDENTIFY_THROTTLE_MS) {
+        return true; // Throttle
+    }
+    identifyThrottleState.set(userId, now);
+    return false;
+}
+/**
+ * Check if a gate event should be deduplicated based on state comparison.
+ *
+ * @param eventKey - Unique key for the gate event (e.g., "comprehension_gate_checked:change-name")
+ * @param currentState - The current state of the gate
+ * @returns True if the event should be deduplicated (not sent), false otherwise
+ */
+export function shouldDeduplicateGateEvent(eventKey, currentState) {
+    const previousState = gateEventState.get(eventKey);
+    if (previousState === undefined) {
+        gateEventState.set(eventKey, currentState);
+        return false;
+    }
+    if (previousState === currentState) {
+        return true; // Deduplicate - state unchanged
+    }
+    gateEventState.set(eventKey, currentState);
+    return false;
+}
+/**
+ * Check if a general event should be deduplicated due to rapid succession.
+ *
+ * @param eventKey - Unique key for the event (e.g., "command_executed:init")
+ * @returns True if the event should be deduplicated (not sent), false otherwise
+ */
+export function shouldDeduplicateRapidEvent(eventKey) {
+    const now = Date.now();
+    const lastEventTime = recentEvents.get(eventKey);
+    if (lastEventTime === undefined) {
+        recentEvents.set(eventKey, now);
+        return false;
+    }
+    const timeSinceLastEvent = now - lastEventTime;
+    if (timeSinceLastEvent < RAPID_DUPLICATE_WINDOW_MS) {
+        return true; // Deduplicate - too rapid
+    }
+    recentEvents.set(eventKey, now);
+    return false;
+}
+/**
+ * Clear deduplication state (useful for testing or session reset).
+ */
+export function clearDeduplicationState() {
+    identifyThrottleState.clear();
+    gateEventState.clear();
+    recentEvents.clear();
+}
+//# sourceMappingURL=deduplication.js.map

package/dist/telemetry/deduplication.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for deduplication module.
+ */
+export {};
+//# sourceMappingURL=deduplication.test.d.ts.map

package/dist/telemetry/identity.d.ts

@@ -1,23 +1,63 @@
-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;
+export declare 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 declare function getIdentityPath(): string;
+/**
+ * Read identity from file or environment variable.
+ * Environment variable takes precedence over file.
+ *
+ * @returns The identity string, or null if not configured
+ */
+export declare function readIdentity(): Promise<string | null>;
+/**
+ * Write identity to file with restricted permissions.
+ *
+ * @param identity - The identity string to write
+ */
+export declare function writeIdentity(identity: string): Promise<void>;
+/**
+ * Validate email format using RFC 5322 compliant pattern.
+ *
+ * @param email - The email string to validate
+ * @returns True if valid, false otherwise
+ */
+export declare function validateEmail(email: string): boolean;
+/**
+ * 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 declare function validateUsername(username: string): boolean;
+/**
+ * Normalize identity input by trimming whitespace and converting to lowercase.
+ *
+ * @param identity - The identity string to normalize
+ * @returns The normalized identity string
+ */
+export declare function normalizeIdentity(identity: string): string;
+/**
+ * Validate identity format (email or username).
+ *
+ * @param identity - The identity string to validate
+ * @returns Object with valid flag and error messages if invalid
+ */
+export declare function validateIdentity(identity: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Interactive prompt for identity collection.
+ * Uses inquirer for consistent prompting with other OpenSpec commands.
+ *
+ * @returns The user's identity input
+ */
+export declare function promptForIdentity(): Promise<string>;
 //# sourceMappingURL=identity.d.ts.map