@ydtb/specsmd 0.1.22

package/lib/analytics/tracker.js

@@ -0,0 +1,232 @@
+/**
+ * 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
+                // Note: geolocate: true enables IP-based geolocation for analytics.
+                // This data is used solely for aggregate usage insights (e.g., country-level
+                // adoption patterns). No personal identifiers are collected. Users can
+                // opt out via the --no-telemetry flag or SPECSMD_NO_TELEMETRY env var.
+                geolocate: true
+            });
+
+            // 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
+     * @param {boolean} waitForDelivery - Wait for event to be sent
+     * @returns {Promise<void>} Resolves when event is sent (if waitForDelivery is true)
+     */
+    track(eventName, properties = {}, waitForDelivery = false) {
+        if (!this.enabled || !this.mixpanel) {
+            return waitForDelivery ? Promise.resolve() : undefined;
+        }
+
+        const eventData = {
+            ...this.baseProperties,
+            ...properties
+        };
+
+        if (waitForDelivery) {
+            return new Promise((resolve) => {
+                try {
+                    this.mixpanel.track(eventName, eventData, () => {
+                        // Resolve regardless of error - silent failure
+                        resolve();
+                    });
+                } catch {
+                    resolve();
+                }
+            });
+        }
+
+        try {
+            this.mixpanel.track(eventName, eventData);
+        } catch {
+            // Silent failure
+        }
+    }
+
+    /**
+     * Track installer_started event
+     * Called when the installer begins
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackInstallerStarted() {
+        // Wait for delivery - critical funnel event
+        return this.track('installer_started', {}, true);
+    }
+
+    /**
+     * Track ides_confirmed event
+     * Called after user confirms IDE/tool selection
+     *
+     * @param {string[]} ides - Array of selected IDE keys (e.g., ['claude-code', 'cursor'])
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackIdesConfirmed(ides) {
+        // Wait for delivery - critical funnel event
+        return this.track('ides_confirmed', {
+            ide_count: ides.length,
+            ides: ides
+        }, true);
+    }
+
+    /**
+     * Track flow_selected event
+     * Called after user selects an SDLC flow
+     *
+     * @param {string} flow - Flow key (e.g., 'aidlc', 'agile')
+     * @returns {Promise<void>} Resolves when event is sent
+     */
+    trackFlowSelected(flow) {
+        // Wait for delivery - critical funnel event
+        return this.track('flow_selected', {
+            flow: flow
+        }, true);
+    }
+
+    /**
+     * 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/cli-utils.js

@@ -0,0 +1,342 @@
+/**
+ * CLI Utilities for specsmd
+ */
+
+const chalk = require('chalk');
+const gradient = require('gradient-string');
+const path = require('path');
+
+const { THEME_COLORS } = require('./constants');
+
+const THEME = THEME_COLORS;
+
+// Create gradient for logo
+const logoGradient = gradient([THEME.primary, THEME.secondary]);
+
+// Pixel-art style logo (brick blocks with 3D effect)
+const PIXEL_LOGO = `
+ ███████╗ ██████╗  ███████╗  ██████╗ ███████╗     ███╗   ███╗ ██████╗
+ ██╔════╝ ██╔══██╗ ██╔════╝ ██╔════╝ ██╔════╝     ████╗ ████║ ██╔══██╗
+ ███████╗ ██████╔╝ █████╗   ██║      ███████╗     ██╔████╔██║ ██║  ██║
+ ╚════██║ ██╔═══╝  ██╔══╝   ██║      ╚════██║     ██║╚██╔╝██║ ██║  ██║
+ ███████║ ██║      ███████╗ ╚██████╗ ███████║ ██╗ ██║ ╚═╝ ██║ ██████╔╝
+ ╚══════╝ ╚═╝      ╚══════╝  ╚═════╝ ╚══════╝ ╚═╝ ╚═╝     ╚═╝ ╚═════╝
+`;
+
+// Theme chalk instances
+const theme = {
+  primary: chalk.hex(THEME.primary),
+  secondary: chalk.hex(THEME.secondary),
+  success: chalk.hex(THEME.success),
+  error: chalk.hex(THEME.error),
+  warning: chalk.hex(THEME.warning),
+  info: chalk.hex(THEME.info),
+  dim: chalk.hex(THEME.dim)
+};
+
+// Box drawing characters (Unicode)
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+  heavyHorizontal: '═',
+  heavyVertical: '║',
+  heavyTopLeft: '╔',
+  heavyTopRight: '╗',
+  heavyBottomLeft: '╚',
+  heavyBottomRight: '╝'
+};
+
+/**
+ * CLIUtils -
+ */
+const CLIUtils = {
+  /**
+   * Get package version
+   */
+  getVersion() {
+    try {
+      const packageJson = require(path.join(__dirname, '..', 'package.json'));
+      return packageJson.version || 'Unknown';
+    } catch {
+      return 'Unknown';
+    }
+  },
+
+  /**
+   * Get terminal width (capped at 80)
+   */
+  getWidth() {
+    return Math.min(process.stdout.columns || 80, 80);
+  },
+
+  /**
+   * Display the specs.md logo with ASCII art
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  async displayLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    console.log('');
+    console.log(logoGradient(PIXEL_LOGO));
+
+    // Tagline with version
+    console.log(theme.primary(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + theme.dim('  https://specs.md') + '\n');
+  },
+
+  /**
+   * Display the specsmd logo synchronously with ASCII art
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  displayLogoSync(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    console.log('');
+    console.log(logoGradient(PIXEL_LOGO));
+
+    // Tagline with version
+    console.log(theme.primary(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + theme.dim('  https://specs.md') + '\n');
+  },
+
+  /**
+   * Display the logo using pixel-art style (alternative/legacy method name)
+   * @param {boolean} clearScreen - Whether to clear screen first
+   */
+  displayFigletLogo(clearScreen = true) {
+    if (clearScreen) {
+      console.clear();
+    }
+
+    const version = this.getVersion();
+
+    console.log(logoGradient(PIXEL_LOGO));
+    console.log(theme.dim(' AI-native development orchestration') + theme.primary.bold(` v${version}`) + theme.dim('  https://specs.md') + '\n');
+  },
+
+  /**
+   * Display a section header with separator lines
+   * @param {string} title - Section title
+   * @param {string} subtitle - Optional subtitle
+   */
+  displaySection(title, subtitle = null) {
+    const width = this.getWidth();
+    const line = BOX.heavyHorizontal.repeat(width);
+
+    console.log('\n' + theme.primary(line));
+    console.log(theme.primary.bold(` ${title}`));
+    if (subtitle) {
+      console.log(theme.dim(` ${subtitle}`));
+    }
+    console.log(theme.primary(line) + '\n');
+  },
+
+  /**
+   * Display a header (lighter than section)
+   * @param {string} title - Header title
+   * @param {string} icon - Optional icon prefix
+   */
+  displayHeader(title, icon = '') {
+    const prefix = icon ? `${icon}  ` : '';
+    console.log('\n' + theme.primary.bold(`${prefix}${title}`));
+    console.log(theme.dim(BOX.horizontal.repeat(title.length + prefix.length)) + '\n');
+  },
+
+  /**
+   * Display a boxed message
+   * @param {string} content - Box content
+   * @param {object} options - Box options
+   */
+  displayBox(content, options = {}) {
+    const {
+      title = null,
+      borderColor = 'primary',
+      padding = 1,
+      width = null
+    } = options;
+
+    const boxWidth = width || Math.min(this.getWidth() - 4, 76);
+    const innerWidth = boxWidth - 2;
+    const colorFn = theme[borderColor] || theme.primary;
+
+    // Top border
+    let topBorder;
+    if (title) {
+      const titleStr = ` ${title} `;
+      const remainingWidth = boxWidth - titleStr.length - 2;
+      const leftPad = Math.floor(remainingWidth / 2);
+      const rightPad = remainingWidth - leftPad;
+      topBorder = colorFn(BOX.topLeft + BOX.horizontal.repeat(leftPad) + titleStr + BOX.horizontal.repeat(rightPad) + BOX.topRight);
+    } else {
+      topBorder = colorFn(BOX.topLeft + BOX.horizontal.repeat(boxWidth - 2) + BOX.topRight);
+    }
+    console.log(topBorder);
+
+    // Padding top
+    for (let i = 0; i < padding; i++) {
+      console.log(colorFn(BOX.vertical) + ' '.repeat(innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Content lines
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const stripped = line.replace(/\u001b\[[0-9;]*m/g, ''); // Strip ANSI codes for length calculation
+      const paddedLine = line + ' '.repeat(Math.max(0, innerWidth - stripped.length));
+      console.log(colorFn(BOX.vertical) + paddedLine.slice(0, innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Padding bottom
+    for (let i = 0; i < padding; i++) {
+      console.log(colorFn(BOX.vertical) + ' '.repeat(innerWidth) + colorFn(BOX.vertical));
+    }
+
+    // Bottom border
+    console.log(colorFn(BOX.bottomLeft + BOX.horizontal.repeat(boxWidth - 2) + BOX.bottomRight));
+  },
+
+  /**
+   * Display a success message in a green box
+   * @param {string} message - Success message
+   * @param {string} title - Optional title
+   */
+  displaySuccess(message, title = 'Success') {
+    console.log('');
+    this.displayBox(theme.success(message), {
+      title,
+      borderColor: 'success',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display an error message in a red box
+   * @param {string} message - Error message
+   * @param {string} title - Optional title
+   */
+  displayError(message, title = 'Error') {
+    console.log('');
+    this.displayBox(theme.error(message), {
+      title,
+      borderColor: 'error',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display a warning message in an amber box
+   * @param {string} message - Warning message
+   * @param {string} title - Optional title
+   */
+  displayWarning(message, title = 'Warning') {
+    console.log('');
+    this.displayBox(theme.warning(message), {
+      title,
+      borderColor: 'warning',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display an info message in a blue box
+   * @param {string} message - Info message
+   * @param {string} title - Optional title
+   */
+  displayInfo(message, title = 'Info') {
+    console.log('');
+    this.displayBox(theme.info(message), {
+      title,
+      borderColor: 'info',
+      padding: 0
+    });
+  },
+
+  /**
+   * Display current step progress
+   * @param {number} current - Current step
+   * @param {number} total - Total steps
+   * @param {string} description - Step description
+   */
+  displayStep(current, total, description) {
+    const progress = theme.primary.bold(`[${current}/${total}]`);
+    console.log(`${progress} ${description}`);
+  },
+
+  /**
+   * Display a completion message
+   * @param {string} message - Completion message
+   */
+  displayComplete(message) {
+    this.displaySuccess(message, 'Complete');
+  },
+
+  /**
+   * Display a simple status line
+   * @param {string} icon - Status icon
+   * @param {string} message - Status message
+   * @param {string} color - Color name
+   */
+  displayStatus(icon, message, color = 'primary') {
+    const colorFn = theme[color] || theme.primary;
+    console.log(`${colorFn(icon)} ${message}`);
+  },
+
+  /**
+   * Display a list of items
+   * @param {string[]} items - List items
+   * @param {string} bullet - Bullet character
+   */
+  displayList(items, bullet = '  -') {
+    for (const item of items) {
+      console.log(theme.dim(bullet) + ' ' + item);
+    }
+  },
+
+  /**
+   * Display next steps
+   * @param {string[]} steps - Array of step descriptions
+   */
+  displayNextSteps(steps) {
+    console.log(theme.dim('\nNext steps:'));
+    steps.forEach((step, index) => {
+      console.log(theme.dim(`  ${index + 1}. ${step}`));
+    });
+    console.log('');
+  },
+
+  /**
+   * Display a separator line
+   * @param {string} style - 'light' or 'heavy'
+   */
+  displaySeparator(style = 'light') {
+    const width = this.getWidth();
+    const char = style === 'heavy' ? BOX.heavyHorizontal : BOX.horizontal;
+    console.log(theme.dim(char.repeat(width)));
+  },
+
+  /**
+   * Theme colors for external use
+   */
+  theme,
+
+  /**
+   * Logo gradient for external use
+   */
+  logoGradient,
+
+  /**
+   * Box characters for external use
+   */
+  BOX
+};
+
+module.exports = CLIUtils;

package/lib/constants.js

@@ -0,0 +1,44 @@
+
+// Theme Colors (dark red)
+const THEME_COLORS = {
+    primary: '#A83232',      // Dark brick red
+    secondary: '#C04545',    // Medium red
+    accent: '#D85858',       // Coral red
+    success: '#22c55e',      // Green
+    error: '#ef4444',        // Red
+    warning: '#f59e0b',      // Amber
+    info: '#3b82f6',         // Blue
+    dim: '#666666'           // Gray shadow (visible on dark/light terminals)
+};
+
+const FLOWS = {
+    fire: {
+        name: 'FIRE',
+        description: 'Adaptive execution - Brownfield/monorepo ready, right-sizes rigor to complexity',
+        path: 'fire'
+    },
+    aidlc: {
+        name: 'AI-DLC',
+        description: 'Full methodology - Comprehensive traceability, DDD or Simple bolt types',
+        path: 'aidlc'
+    },
+    simple: {
+        name: 'Simple',
+        description: 'Spec generation only (Kiro style) - Creates requirement/design/task docs, no execution tracking',
+        path: 'simple'
+    }
+};
+
+const LINKS = {
+    website: 'https://specs.md',
+    flows: 'https://specs.md/architecture/flows',
+    ideExtension: 'https://specs.md/getting-started/ide-extension',
+    vscodeMarketplace: 'https://marketplace.visualstudio.com/items?itemName=fabriqaai.specsmd',
+    openVsx: 'https://open-vsx.org/extension/fabriqaai/specsmd'
+};
+
+module.exports = {
+    THEME_COLORS,
+    FLOWS,
+    LINKS
+};