@fission-ai/openspec 0.18.0 → 0.20.0

package/dist/core/templates/slash-command-templates.js

@@ -11,7 +11,7 @@ const proposalSteps = `**Steps**
 4. Capture architectural reasoning in \`design.md\` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
 5. Draft spec deltas in \`changes/<id>/specs/<capability>/spec.md\` (one folder per capability) using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
 6. Draft \`tasks.md\` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
-7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`;
+7. Validate with \`openspec validate <id> --strict --no-interactive\` and resolve every issue before sharing the proposal.`;
 const proposalReferences = `**Reference**
 - Use \`openspec show <id> --json --deltas-only\` or \`openspec show <spec> --type spec\` to inspect details when validation fails.
 - Search existing requirements with \`rg -n "Requirement:|Scenario:" openspec/specs\` before writing new ones.
@@ -34,7 +34,7 @@ const archiveSteps = `**Steps**
 2. Validate the change ID by running \`openspec list\` (or \`openspec show <id>\`) and stop if the change is missing, already archived, or otherwise not ready to archive.
 3. Run \`openspec archive <id> --yes\` so the CLI moves the change and applies spec updates without prompts (use \`--skip-specs\` only for tooling-only work).
 4. Review the command output to confirm the target specs were updated and the change landed in \`changes/archive/\`.
-5. Validate with \`openspec validate --strict\` and inspect with \`openspec show <id>\` if anything looks off.`;
+5. Validate with \`openspec validate --strict --no-interactive\` and inspect with \`openspec show <id>\` if anything looks off.`;
 const archiveReferences = `**Reference**
 - Use \`openspec list\` to confirm change IDs before archiving.
 - Inspect refreshed specs with \`openspec list --specs\` and address any validation issues before handing off.`;

package/dist/telemetry/config.d.ts

@@ -0,0 +1,32 @@
+export interface TelemetryConfig {
+    anonymousId?: string;
+    noticeSeen?: boolean;
+}
+export interface GlobalConfig {
+    telemetry?: TelemetryConfig;
+    [key: string]: unknown;
+}
+/**
+ * Get the path to the global config file.
+ * Uses ~/.config/openspec/config.json on all platforms.
+ */
+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>;
+//# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.js

@@ -0,0 +1,68 @@
+/**
+ * Global configuration for telemetry state.
+ * Stores anonymous ID and notice-seen flag in ~/.config/openspec/config.json
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+/**
+ * Get the path to the global config file.
+ * Uses ~/.config/openspec/config.json on all platforms.
+ */
+export function getConfigPath() {
+    const configDir = path.join(os.homedir(), '.config', 'openspec');
+    return path.join(configDir, 'config.json');
+}
+/**
+ * Read the global config file.
+ * Returns an empty object if the file doesn't exist.
+ */
+export async function readConfig() {
+    const configPath = getConfigPath();
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {};
+        }
+        // If parse fails or other error, return empty config
+        return {};
+    }
+}
+/**
+ * Write to the global config file.
+ * Preserves existing fields and merges in new values.
+ */
+export async function writeConfig(updates) {
+    const configPath = getConfigPath();
+    const configDir = path.dirname(configPath);
+    // Ensure directory exists
+    await fs.mkdir(configDir, { recursive: true });
+    // 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 };
+    }
+    await fs.writeFile(configPath, JSON.stringify(merged, null, 2) + '\n');
+}
+/**
+ * Get the telemetry config section.
+ */
+export async function getTelemetryConfig() {
+    const config = await readConfig();
+    return config.telemetry ?? {};
+}
+/**
+ * Update the telemetry config section.
+ */
+export async function updateTelemetryConfig(updates) {
+    const existing = await getTelemetryConfig();
+    await writeConfig({
+        telemetry: { ...existing, ...updates },
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export declare function shutdown(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -0,0 +1,145 @@
+/**
+ * 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
+ */
+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';
+let posthogClient = null;
+let anonymousId = 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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
+        });
+    }
+    return posthogClient;
+}
+/**
+ * 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;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/file-system.d.ts

@@ -9,6 +9,12 @@ export declare class FileSystemUtils {
     static joinPath(basePath: string, ...segments: string[]): string;
     static createDirectory(dirPath: string): Promise<void>;
     static fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    private static findFirstExistingDirectory;
     static canWriteFile(filePath: string): Promise<boolean>;
     static directoryExists(dirPath: string): Promise<boolean>;
     static writeFile(filePath: string, content: string): Promise<void>;

package/dist/utils/file-system.js

@@ -73,6 +73,41 @@ export class FileSystemUtils {
             return false;
         }
     }
+    /**
+     * Finds the first existing parent directory by walking up the directory tree.
+     * @param dirPath Starting directory path
+     * @returns The first existing directory path, or null if root is reached without finding one
+     */
+    static async findFirstExistingDirectory(dirPath) {
+        let currentDir = dirPath;
+        while (true) {
+            try {
+                const stats = await fs.stat(currentDir);
+                if (stats.isDirectory()) {
+                    return currentDir;
+                }
+                // Path component exists but is not a directory (edge case)
+                console.debug(`Path component ${currentDir} exists but is not a directory`);
+                return null;
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    // Directory doesn't exist, move up one level
+                    const parentDir = path.dirname(currentDir);
+                    if (parentDir === currentDir) {
+                        // Reached filesystem root without finding existing directory
+                        return null;
+                    }
+                    currentDir = parentDir;
+                }
+                else {
+                    // Unexpected error (permissions, I/O error, etc.)
+                    console.debug(`Error checking directory ${currentDir}: ${error.message}`);
+                    return null;
+                }
+            }
+        }
+    }
     static async canWriteFile(filePath) {
         try {
             const stats = await fs.stat(filePath);
@@ -91,10 +126,16 @@ export class FileSystemUtils {
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                // File doesn't exist; check if we can write to the parent directory
+                // File doesn't exist - find first existing parent directory and check its permissions
                 const parentDir = path.dirname(filePath);
+                const existingDir = await this.findFirstExistingDirectory(parentDir);
+                if (existingDir === null) {
+                    // No existing parent directory found (edge case)
+                    return false;
+                }
+                // Check if the existing parent directory is writable
                 try {
-                    await fs.access(parentDir, fsConstants.W_OK);
+                    await fs.access(existingDir, fsConstants.W_OK);
                     return true;
                 }
                 catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -42,6 +42,7 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.27.7",
     "@types/node": "^24.2.0",
     "@vitest/ui": "^3.2.4",
@@ -57,6 +58,7 @@
     "commander": "^14.0.0",
     "fast-glob": "^3.3.3",
     "ora": "^8.2.0",
+    "posthog-node": "^5.20.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
   },
@@ -74,7 +76,6 @@
     "check:pack-version": "node scripts/pack-version-check.mjs",
     "release": "pnpm run release:ci",
     "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
     "changeset": "changeset"
   }
 }