project-iris 0.0.12 → 0.0.14

package/flows/aidlc/templates/standards/tech-stack.guide.md

@@ -0,0 +1,280 @@
+# Tech Stack Facilitation Guide
+
+## Purpose
+
+Define the technology choices that will guide code generation, architecture decisions, and ensure consistency across all AI agents working on the project.
+
+---
+
+## Facilitation Approach
+
+You are collaborating with a peer to discover their tech stack preferences. This is a conversation, not a form to fill out.
+
+**Adapt your style:**
+
+- If they mention specific technologies confidently → treat them as experienced, be concise
+- If they seem uncertain → provide more context, examples, and recommendations
+- If they have strong preferences → respect them, ask about tradeoffs they've considered
+
+**Your role:**
+
+- Guide discovery, don't dictate choices
+- Surface tradeoffs they may not have considered
+- Ensure choices are coherent (no conflicting technologies)
+- Capture rationale, not just the choice
+
+---
+
+## Discovery Areas
+
+### 1. Languages
+
+**Goal**: Understand what programming language(s) they'll use.
+
+**Open with context:**
+> "Let's start with languages. This affects everything else - framework options, available libraries, team hiring, and performance characteristics."
+
+**Explore:**
+
+- What languages is the team already comfortable with?
+- Are there languages they want to learn vs. use productively?
+- Is type safety important? (catches bugs early vs. development speed)
+- What's the runtime environment? (Browser, Node.js, Edge functions, Native)
+- Any organizational standards or constraints?
+
+**If they're unsure, guide by use case:**
+
+| Use Case | Recommendation | Why |
+|----------|----------------|-----|
+| Web app (full-stack) | TypeScript | Type safety, React/Next.js ecosystem, great tooling |
+| API service | TypeScript or Go | TS for ecosystem, Go for performance |
+| ML/AI/Data | Python | Libraries (PyTorch, pandas), community |
+| High-performance systems | Go or Rust | Go for simplicity, Rust for safety |
+| Scripts/automation | Python or TypeScript | Readability, quick iteration |
+
+**Common signals to listen for:**
+
+- "We're a React shop" → TypeScript
+- "We do ML/AI" → Python, possibly with TypeScript frontend
+- "Performance is critical" → Go, Rust, or optimized Node.js
+- "Small team, move fast" → TypeScript or Python
+- "Enterprise environment" → Java/Kotlin or TypeScript
+
+**Validate before moving on:**
+> "So we're going with {language}. This means {implication}. Sound right?"
+
+---
+
+### 2. Framework
+
+**Goal**: Understand their application framework choice.
+
+**Context to share:**
+> "Your framework shapes project structure, available patterns, and deployment options. It's one of the hardest things to change later."
+
+**Explore:**
+
+- What type of application? (Web app, API only, CLI, Mobile)
+- Do they need server-side rendering (SSR) or static generation (SSG)?
+- Is this a new project or adding to existing code?
+- Where will it be deployed? (This affects framework choice)
+- Any real-time requirements? (WebSockets, subscriptions)
+
+**Guide by language and use case:**
+
+**TypeScript - Web Applications:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Next.js | Full-stack, SSR/SSG, Vercel deployment | Opinionated, tied to React |
+| Remix | Web standards, nested routing, great DX | Smaller ecosystem |
+| Astro | Content-heavy sites, partial hydration | Less suited for highly interactive apps |
+| SvelteKit | Performance, smaller bundle, great DX | Smaller ecosystem than React |
+
+**TypeScript - API Only:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Fastify | Performance, low overhead | Less opinionated |
+| NestJS | Enterprise, structured, dependency injection | More boilerplate |
+| Hono | Edge functions, ultra-lightweight | Newer, smaller ecosystem |
+| Express | Simple, huge middleware ecosystem | Older patterns, callback-heavy |
+
+**Python - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| FastAPI | Modern async, auto-docs, type hints | Async complexity |
+| Django | Batteries-included, ORM, admin | Heavier, monolithic |
+| Flask | Minimal, flexible | Need to add everything yourself |
+
+**Go - APIs:**
+
+| Framework | Best For | Tradeoffs |
+|-----------|----------|-----------|
+| Gin | Fast, popular, good docs | |
+| Echo | Similar to Gin, slightly different API | |
+| Chi | Lightweight, idiomatic Go | Less batteries included |
+| Standard library | Maximum control | More code to write |
+
+**Questions to surface tradeoffs:**
+
+- "Next.js is great but ties you to React. Is that okay?"
+- "FastAPI requires understanding async Python. Is the team comfortable with that?"
+- "NestJS has more structure but also more boilerplate. Do you prefer convention or flexibility?"
+
+---
+
+### 3. Authentication
+
+**Goal**: Understand authentication needs.
+
+**Optional - some projects don't need auth initially.**
+
+**Explore:**
+
+- Do they need user authentication?
+- What methods? (Email/password, social login, magic links, SSO)
+- Is this B2C (end users) or B2B (enterprise SSO)?
+- Any compliance requirements? (MFA, audit logs)
+
+**Options:**
+
+| Solution | Best For | Tradeoffs |
+|----------|----------|-----------|
+| Supabase Auth | Supabase users, quick setup | Tied to Supabase |
+| NextAuth.js | Next.js apps, flexible | Configuration complexity |
+| Clerk | Quick setup, beautiful UI | Cost at scale |
+| Auth0 | Enterprise, SSO | Cost, complexity |
+| Lucia | Lightweight, self-hosted | More DIY |
+| Custom | Full control | Security responsibility |
+
+**If using Supabase for database:**
+> "Since you're using Supabase for the database, Supabase Auth integrates seamlessly. It handles email/password, social providers, and row-level security. Worth considering unless you have specific needs."
+
+---
+
+### 4. Infrastructure & Deployment
+
+**Goal**: Understand how they'll deploy and operate.
+
+**Explore:**
+
+- Where do they want to deploy? (Cloud provider preference?)
+- Serverless vs. containers vs. VMs?
+- Who manages infrastructure? (Solo dev, dedicated DevOps, managed service)
+- Budget constraints?
+- Any existing infrastructure to integrate with?
+
+**Guide by context:**
+
+| Context | Recommendation | Why |
+|---------|----------------|-----|
+| Solo dev, startup | Vercel, Railway, Render | Minimal ops, fast deployment |
+| Next.js app | Vercel | Optimized for Next.js |
+| Need containers | Fly.io, Railway, Render | Simple container hosting |
+| Enterprise/compliance | AWS, GCP, Azure | Full control, compliance certifications |
+| Cost-sensitive at scale | Fly.io, self-managed k8s | Lower costs, more ops |
+| Already in AWS | AWS ecosystem | Consistency, existing knowledge |
+
+**Serverless vs. Containers:**
+
+- **Serverless** (Vercel, Lambda): Pay-per-use, auto-scaling, cold starts
+- **Containers** (Fly.io, ECS): Predictable performance, more control
+- **VMs** (EC2): Full control, predictable costs at scale
+
+---
+
+### 5. Package Manager
+
+**Goal**: Quick decision on package management.
+
+**For JavaScript/TypeScript:**
+
+| Manager | Best For |
+|---------|----------|
+| pnpm | Monorepos, disk efficiency, speed |
+| npm | Default, widest compatibility |
+| yarn | Existing yarn projects |
+| bun | Experimental, very fast |
+
+**Default recommendation:** pnpm (fast, efficient, great monorepo support)
+
+---
+
+## Completing the Discovery
+
+Once you've explored all relevant areas, summarize:
+
+```markdown
+## Tech Stack Summary
+
+Based on our conversation, here's what I understand:
+
+**Languages**: {choice}
+{brief rationale}
+
+**Framework**: {choice}
+{brief rationale}
+
+**Authentication**: {choice or "TBD"}
+{brief rationale if applicable}
+
+**Infrastructure**: {choice}
+{brief rationale}
+
+**Package Manager**: {choice}
+
+---
+
+Does this capture your tech stack accurately? Any adjustments needed?
+```
+
+---
+
+## Output Generation
+
+After confirmation, create `standards/tech-stack.md`:
+
+```markdown
+# Tech Stack
+
+## Overview
+{1-2 sentence summary of the stack and why it fits the project}
+
+## Languages
+{language(s)}
+
+{Rationale - why this choice, what it enables}
+
+## Framework
+{framework}
+
+{Rationale - why this choice, deployment implications}
+
+## Authentication
+{auth solution or "TBD"}
+
+{Rationale if selected}
+
+## Infrastructure & Deployment
+{infrastructure choice}
+
+{Rationale - deployment strategy, scaling approach}
+
+## Package Manager
+{package manager}
+
+## Decision Relationships
+{Note any important connections between choices}
+```
+
+---
+
+## Notes for Agent
+
+- **Don't ask all questions linearly** - adapt based on what they've already told you
+- **Skip irrelevant decisions** - CLI tools don't need authentication discussion
+- **Capture rationale** - "why" is as important as "what"
+- **Respect existing choices** - if they say "we're using X", don't try to change their mind unless there's a real issue
+- **It's okay to leave things TBD** - not every decision needs to be made upfront

package/lib/InstallerFactory.js

@@ -0,0 +1,36 @@
+const ClaudeInstaller = require('./installers/ClaudeInstaller');
+const CursorInstaller = require('./installers/CursorInstaller');
+const CopilotInstaller = require('./installers/CopilotInstaller');
+const AntigravityInstaller = require('./installers/AntigravityInstaller');
+const WindsurfInstaller = require('./installers/WindsurfInstaller');
+const ClineInstaller = require('./installers/ClineInstaller');
+const RooInstaller = require('./installers/RooInstaller');
+const KiroInstaller = require('./installers/KiroInstaller');
+const GeminiInstaller = require('./installers/GeminiInstaller');
+const CodexInstaller = require('./installers/CodexInstaller');
+const OpenCodeInstaller = require('./installers/OpenCodeInstaller');
+
+class InstallerFactory {
+    static getInstallers() {
+        return [
+            new ClaudeInstaller(),
+            new CursorInstaller(),
+            new CopilotInstaller(),
+            new AntigravityInstaller(),
+            new WindsurfInstaller(),
+            new ClineInstaller(),
+            new RooInstaller(),
+            new KiroInstaller(),
+            new GeminiInstaller(),
+            new CodexInstaller(),
+            new OpenCodeInstaller()
+        ];
+    }
+
+    static getInstaller(key) {
+        const installers = this.getInstallers();
+        return installers.find(i => i.key === key);
+    }
+}
+
+module.exports = InstallerFactory;

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:
+ * - IRIS_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.IRIS_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 = 'iris-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,232 @@
+/**
+ * Analytics Tracker
+ *
+ * Mixpanel-based analytics for the iris 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 = 'aca20c9ced2bd92e83660b9ebe33ded6';
+
+/**
+ * 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 IRIS_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,
+                iris_version: this._getVersion()
+            };
+
+            this.enabled = true;
+            return true;
+        } catch (error) {
+            // Silent failure - analytics should never break installation
+            this.enabled = false;
+            return false;
+        }
+    }
+
+    /**
+     * Get iris 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;