specsmd 0.0.34 → 0.1.1

package/flows/aidlc/templates/inception/story-template.md

@@ -13,7 +13,7 @@ unit: {unit-name}
 intent: {intent-name}
 status: draft
 priority: must|should|could
-created: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
 assigned_bolt: null
 implemented: false
 ---
@@ -96,7 +96,7 @@ unit: auth-service
 intent: user-authentication
 status: ready
 priority: must
-created: 2024-12-05
+created: 2024-12-05T10:00:00Z
 assigned_bolt: bolt-auth-service-1
 implemented: false
 ---

package/flows/aidlc/templates/inception/system-context-template.md

@@ -2,7 +2,7 @@
 intent: {intent-name}
 phase: inception
 status: context-defined
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # {Intent Name} - System Context

package/flows/aidlc/templates/inception/unit-brief-template.md

@@ -12,8 +12,8 @@ unit: {unit-name}
 intent: {intent-name}
 phase: inception
 status: draft|ready
-created: {YYYY-MM-DD}
-updated: {YYYY-MM-DD}
+created: {YYYY-MM-DDTHH:MM:SSZ}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 ```
 

package/flows/aidlc/templates/inception/units-template.md

@@ -2,7 +2,7 @@
 intent: {intent-name}
 phase: inception
 status: units-decomposed
-updated: {date}
+updated: {YYYY-MM-DDTHH:MM:SSZ}
 ---
 
 # {Intent Name} - Unit Decomposition

package/lib/analytics/env-detector.js

@@ -0,0 +1,92 @@
+/**
+ * Environment Detection
+ *
+ * Detects shell environment and telemetry opt-out settings.
+ * Used to enrich analytics events and respect user privacy preferences.
+ */
+
+/**
+ * Detect the user's shell/terminal environment
+ *
+ * @returns {string} Shell name (zsh, bash, powershell, cmd, fish, etc.) or 'unknown'
+ */
+function detectShell() {
+    if (process.platform === 'win32') {
+        const comspec = (process.env.ComSpec || '').toLowerCase();
+        if (comspec.includes('powershell') || comspec.includes('pwsh')) {
+            return 'powershell';
+        }
+        if (comspec.includes('cmd')) {
+            return 'cmd';
+        }
+        return 'unknown';
+    }
+
+    // Unix-like systems (macOS, Linux)
+    const shell = process.env.SHELL || '';
+    const basename = shell.split('/').pop() || 'unknown';
+    return basename;
+}
+
+/**
+ * Check if telemetry is disabled via environment variables or CLI flag
+ *
+ * Respects:
+ * - SPECSMD_TELEMETRY_DISABLED=1
+ * - DO_NOT_TRACK=1
+ * - CI environments (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, JENKINS_URL)
+ * - --no-telemetry CLI flag
+ *
+ * @param {Object} options - Optional overrides
+ * @param {boolean} options.noTelemetryFlag - CLI flag state
+ * @returns {boolean} True if telemetry should be disabled
+ */
+function isTelemetryDisabled(options = {}) {
+    // Check CLI flag first (highest priority)
+    if (options.noTelemetryFlag === true) {
+        return true;
+    }
+
+    // Check process.argv for --no-telemetry flag
+    if (process.argv.includes('--no-telemetry')) {
+        return true;
+    }
+
+    // Check explicit opt-out environment variables
+    if (process.env.SPECSMD_TELEMETRY_DISABLED === '1') {
+        return true;
+    }
+
+    // Respect DO_NOT_TRACK standard (https://consoledonottrack.com/)
+    if (process.env.DO_NOT_TRACK === '1') {
+        return true;
+    }
+
+    // Auto-disable in CI environments
+    if (process.env.CI === 'true') {
+        return true;
+    }
+
+    if (process.env.GITHUB_ACTIONS === 'true') {
+        return true;
+    }
+
+    if (process.env.GITLAB_CI === 'true') {
+        return true;
+    }
+
+    if (process.env.CIRCLECI === 'true') {
+        return true;
+    }
+
+    if (process.env.JENKINS_URL !== undefined) {
+        return true;
+    }
+
+    return false;
+}
+
+module.exports = {
+    detectShell,
+    isTelemetryDisabled
+};

package/lib/analytics/index.js

@@ -0,0 +1,22 @@
+/**
+ * Analytics Module
+ *
+ * Exports the analytics tracker singleton for use throughout the installer.
+ *
+ * Usage:
+ *   const analytics = require('./analytics');
+ *
+ *   // Initialize at startup
+ *   analytics.init();
+ *
+ *   // Track events
+ *   analytics.trackInstallerStarted();
+ *   analytics.trackIdesConfirmed(['claude-code', 'cursor']);
+ *   analytics.trackFlowSelected('aidlc');
+ *   analytics.trackInstallationCompleted('claude-code', 'aidlc', 1500, 12);
+ *   analytics.trackInstallationFailed('cursor', 'file_permission', 'aidlc');
+ */
+
+const tracker = require('./tracker');
+
+module.exports = tracker;

package/lib/analytics/machine-id.js

@@ -0,0 +1,33 @@
+/**
+ * Machine ID Generation
+ *
+ * Generates a stable, anonymous machine identifier using a salted SHA-256 hash
+ * of the hostname. This ensures:
+ * - Same machine always produces same ID
+ * - Cannot reverse-lookup the hostname from the hash
+ * - No PII is stored or transmitted
+ */
+
+const crypto = require('crypto');
+const os = require('os');
+
+// Constant salt prevents rainbow table attacks
+// Do not change this value - it would break ID consistency
+const SALT = 'specsmd-analytics-v1';
+
+/**
+ * Generate a stable machine identifier
+ *
+ * @returns {string} SHA-256 hash of salted hostname (64 hex characters)
+ */
+function getMachineId() {
+    const hostname = os.hostname();
+    return crypto
+        .createHash('sha256')
+        .update(SALT + hostname)
+        .digest('hex');
+}
+
+module.exports = {
+    getMachineId
+};

package/lib/analytics/tracker.js

@@ -0,0 +1,205 @@
+/**
+ * Analytics Tracker
+ *
+ * Mixpanel-based analytics for the specsmd installer.
+ * Tracks anonymous usage patterns while respecting privacy.
+ *
+ * Features:
+ * - Fire-and-forget event delivery (non-blocking)
+ * - Silent failures (never breaks installation)
+ * - Privacy-first (no PII, respects opt-out)
+ */
+
+const crypto = require('crypto');
+const { getMachineId } = require('./machine-id');
+const { detectShell, isTelemetryDisabled } = require('./env-detector');
+
+// Mixpanel project token
+// This is safe to embed - analytics tokens are public by design
+const MIXPANEL_TOKEN = 'f405d1fa631f91137f9bb8e0a0277653';
+
+/**
+ * AnalyticsTracker - Singleton class for event tracking
+ */
+class AnalyticsTracker {
+    constructor() {
+        this.mixpanel = null;
+        this.enabled = false;
+        this.machineId = null;
+        this.sessionId = null;
+        this.baseProperties = null;
+        this.initialized = false;
+    }
+
+    /**
+     * Initialize the analytics tracker
+     *
+     * @param {Object} options - Initialization options
+     * @param {boolean} options.noTelemetry - CLI flag to disable telemetry
+     * @returns {boolean} True if analytics is enabled
+     */
+    init(options = {}) {
+        if (this.initialized) {
+            return this.enabled;
+        }
+
+        this.initialized = true;
+
+        // Check if telemetry is disabled
+        if (isTelemetryDisabled({ noTelemetryFlag: options.noTelemetry })) {
+            this.enabled = false;
+            return false;
+        }
+
+        try {
+            // Lazy-load Mixpanel to avoid blocking if not needed
+            const Mixpanel = require('mixpanel');
+            this.mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
+                protocol: 'https',
+                host: 'api-eu.mixpanel.com'  // EU endpoint for GDPR compliance
+            });
+
+            // Generate IDs
+            this.machineId = getMachineId();
+            this.sessionId = crypto.randomUUID();
+
+            // Build base properties included with every event
+            this.baseProperties = {
+                distinct_id: this.machineId,
+                session_id: this.sessionId,
+                $os: process.platform,
+                shell: detectShell(),
+                node_version: process.version,
+                specsmd_version: this._getVersion()
+            };
+
+            this.enabled = true;
+            return true;
+        } catch (error) {
+            // Silent failure - analytics should never break installation
+            this.enabled = false;
+            return false;
+        }
+    }
+
+    /**
+     * Get specsmd version from package.json
+     * @private
+     */
+    _getVersion() {
+        try {
+            const pkg = require('../../package.json');
+            return pkg.version || 'unknown';
+        } catch {
+            return 'unknown';
+        }
+    }
+
+    /**
+     * Track an event (fire-and-forget)
+     * @private
+     *
+     * @param {string} eventName - Name of the event
+     * @param {Object} properties - Additional event properties
+     */
+    track(eventName, properties = {}) {
+        if (!this.enabled || !this.mixpanel) {
+            return;
+        }
+
+        try {
+            this.mixpanel.track(eventName, {
+                ...this.baseProperties,
+                ...properties
+            });
+            // No await - fire and forget
+        } catch {
+            // Silent failure
+        }
+    }
+
+    /**
+     * Track installer_started event
+     * Called when the installer begins
+     */
+    trackInstallerStarted() {
+        this.track('installer_started');
+    }
+
+    /**
+     * Track ides_confirmed event
+     * Called after user confirms IDE/tool selection
+     *
+     * @param {string[]} ides - Array of selected IDE keys (e.g., ['claude-code', 'cursor'])
+     */
+    trackIdesConfirmed(ides) {
+        this.track('ides_confirmed', {
+            ide_count: ides.length,
+            ides: ides
+        });
+    }
+
+    /**
+     * Track flow_selected event
+     * Called after user selects an SDLC flow
+     *
+     * @param {string} flow - Flow key (e.g., 'aidlc', 'agile')
+     */
+    trackFlowSelected(flow) {
+        this.track('flow_selected', {
+            flow: flow
+        });
+    }
+
+    /**
+     * Track installation_completed event
+     * Called after successful installation for an IDE
+     *
+     * @param {string} ide - IDE key (e.g., 'claude-code')
+     * @param {string} flow - Flow key (e.g., 'aidlc')
+     * @param {number} durationMs - Installation duration in milliseconds
+     * @param {number} filesCreated - Number of files created
+     */
+    trackInstallationCompleted(ide, flow, durationMs, filesCreated) {
+        this.track('installation_completed', {
+            ide: ide,
+            flow: flow,
+            duration_ms: durationMs,
+            files_created: filesCreated
+        });
+    }
+
+    /**
+     * Track installation_failed event
+     * Called after failed installation for an IDE
+     *
+     * @param {string} ide - IDE key (e.g., 'claude-code')
+     * @param {string} errorCategory - Error category (e.g., 'file_permission', 'network', 'unknown')
+     * @param {string} [flow] - Flow key (optional, may not be selected yet)
+     */
+    trackInstallationFailed(ide, errorCategory, flow) {
+        const properties = {
+            ide: ide,
+            error_category: errorCategory
+        };
+
+        if (flow) {
+            properties.flow = flow;
+        }
+
+        this.track('installation_failed', properties);
+    }
+
+    /**
+     * Check if analytics is enabled
+     * @returns {boolean}
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+}
+
+// Export singleton instance
+const tracker = new AnalyticsTracker();
+
+module.exports = tracker;

package/lib/installer.js

@@ -5,10 +5,56 @@ const yaml = require('js-yaml');
 const CLIUtils = require('./cli-utils');
 const InstallerFactory = require('./InstallerFactory');
 const { FLOWS } = require('./constants');
+const analytics = require('./analytics');
 
 // Use theme from CLIUtils for consistent styling
 const { theme } = CLIUtils;
 
+/**
+ * Categorize an error for analytics tracking
+ * @param {Error} error - The error to categorize
+ * @returns {string} Error category
+ */
+function categorizeError(error) {
+    const message = (error.message || '').toLowerCase();
+
+    if (message.includes('permission') || message.includes('eacces')) {
+        return 'file_permission';
+    }
+    if (message.includes('enoent') || message.includes('not found')) {
+        return 'file_not_found';
+    }
+    if (message.includes('network') || message.includes('enotfound') || message.includes('timeout')) {
+        return 'network';
+    }
+    if (message.includes('enospc') || message.includes('disk')) {
+        return 'disk_space';
+    }
+    return 'unknown';
+}
+
+/**
+ * Count files in a directory recursively
+ * @param {string} dir - Directory path
+ * @returns {Promise<number>} File count
+ */
+async function countFiles(dir) {
+    let count = 0;
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += await countFiles(path.join(dir, entry.name));
+            } else {
+                count++;
+            }
+        }
+    } catch {
+        // Ignore errors (directory might not exist)
+    }
+    return count;
+}
+
 async function detectTools() {
   const detected = [];
   const installers = InstallerFactory.getInstallers();
@@ -22,6 +68,12 @@ async function detectTools() {
 }
 
 async function install() {
+  // Initialize analytics (respects opt-out env vars)
+  analytics.init();
+  analytics.trackInstallerStarted();
+
+  const installStartTime = Date.now();
+
   await CLIUtils.displayLogo();
   CLIUtils.displayHeader('Installation', '');
 
@@ -67,6 +119,9 @@ async function install() {
     process.exit(1);
   }
 
+  // Track IDE selection
+  analytics.trackIdesConfirmed(selectedToolKeys);
+
   // Step 3: Select Flow
   console.log('');
   CLIUtils.displayStep(3, 4, 'Select SDLC flow');
@@ -88,12 +143,21 @@ async function install() {
     process.exit(1);
   }
 
+  // Track flow selection
+  analytics.trackFlowSelected(selectedFlow);
+
   // Step 4: Install flow files
   console.log('');
   CLIUtils.displayStep(4, 4, `Installing ${FLOWS[selectedFlow].name} flow...`);
 
   try {
-    await installFlow(selectedFlow, selectedToolKeys);
+    const filesCreated = await installFlow(selectedFlow, selectedToolKeys);
+
+    // Track successful installation for each tool
+    const durationMs = Date.now() - installStartTime;
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationCompleted(toolKey, selectedFlow, durationMs, filesCreated);
+    }
 
     CLIUtils.displaySuccess(`${FLOWS[selectedFlow].name} flow installed successfully!`, 'Installation Complete');
 
@@ -108,6 +172,12 @@ async function install() {
     ];
     CLIUtils.displayNextSteps(nextSteps);
   } catch (error) {
+    // Track installation failure
+    const errorCategory = categorizeError(error);
+    for (const toolKey of selectedToolKeys) {
+      analytics.trackInstallationFailed(toolKey, errorCategory, selectedFlow);
+    }
+
     CLIUtils.displayError(`Installation failed: ${error.message}`);
     console.log(theme.dim('\nRolling back changes...'));
     await rollback(selectedFlow, selectedToolKeys);
@@ -199,6 +269,10 @@ async function installFlow(flowKey, toolKeys) {
   );
 
   CLIUtils.displayStatus('', 'Created installation manifest', 'success');
+
+  // Count files created for analytics
+  const filesCreated = await countFiles(specsmdDir);
+  return filesCreated;
 }
 
 async function rollback(flowKey, toolKeys) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specsmd",
-  "version": "0.0.34",
+  "version": "0.1.1",
   "description": "Multi-agent orchestration system for AI-native software development. Delivers AI-DLC, Agile, and custom SDLC flows as markdown-based agent systems.",
   "main": "lib/installer.js",
   "bin": {
@@ -10,8 +10,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:schema": "vitest run __tests__/unit/schema-validation/",
-    "lint:md": "markdownlint '../memory-bank/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml",
-    "lint:md:fix": "markdownlint '../memory-bank/**/*.md' 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
+    "lint:md": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml",
+    "lint:md:fix": "markdownlint 'flows/**/*.md' --config ../.markdownlint.yaml --fix",
     "validate:all": "npm run test && npm run lint:md"
   },
   "keywords": [
@@ -45,6 +45,7 @@
     "fs-extra": "^11.1.1",
     "gradient-string": "^2.0.2",
     "js-yaml": "^4.1.0",
+    "mixpanel": "^0.18.0",
     "oh-my-logo": "^0.4.0",
     "prompts": "^2.4.2"
   },