project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/src/__tests__/unit/analytics/analytics.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+
+/**
+ * Analytics Module Tests
+ *
+ * Tests for the analytics tracker including:
+ * - Machine ID generation (consistent hash)
+ * - Session ID generation (unique per run)
+ * - Shell detection (platform-aware)
+ * - Telemetry opt-out detection
+ * - Tracker initialization and event methods
+ */
+
+describe('Analytics Module', () => {
+    // Store original env vars
+    const originalEnv = { ...process.env };
+
+    beforeEach(() => {
+        // Reset environment before each test
+        process.env = { ...originalEnv };
+        // Clear module cache to get fresh instances
+        vi.resetModules();
+    });
+
+    afterEach(() => {
+        // Restore original env
+        process.env = originalEnv;
+    });
+
+    describe('machine-id', () => {
+        it('should generate a 64-character hex string', async () => {
+            const { getMachineId } = await import('../../../lib/analytics/machine-id');
+            const id = getMachineId();
+
+            expect(id).toMatch(/^[a-f0-9]{64}$/);
+        });
+
+        it('should generate consistent ID across calls', async () => {
+            const { getMachineId } = await import('../../../lib/analytics/machine-id');
+            const id1 = getMachineId();
+            const id2 = getMachineId();
+
+            expect(id1).toBe(id2);
+        });
+
+        it('should generate different IDs for different hostnames', async () => {
+            // This is tested implicitly - the salt ensures different machines
+            // have different IDs even if they have similar hostnames
+            const { getMachineId } = await import('../../../lib/analytics/machine-id');
+            const id = getMachineId();
+
+            // Just verify it's a valid hash
+            expect(id.length).toBe(64);
+        });
+    });
+
+    describe('env-detector', () => {
+        describe('detectShell', () => {
+            it('should detect shell from SHELL env var on Unix', async () => {
+                process.env.SHELL = '/bin/zsh';
+                const { detectShell } = await import('../../../lib/analytics/env-detector');
+
+                // Only test on non-Windows
+                if (process.platform !== 'win32') {
+                    expect(detectShell()).toBe('zsh');
+                }
+            });
+
+            it('should return "unknown" when SHELL is not set', async () => {
+                delete process.env.SHELL;
+                vi.resetModules();
+                const { detectShell } = await import('../../../lib/analytics/env-detector');
+
+                if (process.platform !== 'win32') {
+                    expect(detectShell()).toBe('unknown');
+                }
+            });
+
+            it('should extract basename from full path', async () => {
+                process.env.SHELL = '/usr/local/bin/fish';
+                vi.resetModules();
+                const { detectShell } = await import('../../../lib/analytics/env-detector');
+
+                if (process.platform !== 'win32') {
+                    expect(detectShell()).toBe('fish');
+                }
+            });
+        });
+
+        describe('isTelemetryDisabled', () => {
+            it('should return false by default', async () => {
+                // Clear all telemetry-related env vars
+                delete process.env.SPECSMD_TELEMETRY_DISABLED;
+                delete process.env.DO_NOT_TRACK;
+                delete process.env.CI;
+                delete process.env.GITHUB_ACTIONS;
+                delete process.env.GITLAB_CI;
+                delete process.env.CIRCLECI;
+                delete process.env.JENKINS_URL;
+
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(false);
+            });
+
+            it('should return true when SPECSMD_TELEMETRY_DISABLED=1', async () => {
+                process.env.SPECSMD_TELEMETRY_DISABLED = '1';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when DO_NOT_TRACK=1', async () => {
+                process.env.DO_NOT_TRACK = '1';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when CI=true', async () => {
+                process.env.CI = 'true';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when GITHUB_ACTIONS=true', async () => {
+                process.env.GITHUB_ACTIONS = 'true';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when GITLAB_CI=true', async () => {
+                process.env.GITLAB_CI = 'true';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when CIRCLECI=true', async () => {
+                process.env.CIRCLECI = 'true';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when JENKINS_URL is set', async () => {
+                process.env.JENKINS_URL = 'http://jenkins.example.com';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(true);
+            });
+
+            it('should return true when noTelemetryFlag option is true', async () => {
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled({ noTelemetryFlag: true })).toBe(true);
+            });
+
+            it('should NOT disable when SPECSMD_TELEMETRY_DISABLED=0', async () => {
+                // Clear all CI env vars first (these are set in GitHub Actions)
+                delete process.env.CI;
+                delete process.env.GITHUB_ACTIONS;
+                delete process.env.GITLAB_CI;
+                delete process.env.CIRCLECI;
+                delete process.env.JENKINS_URL;
+                delete process.env.DO_NOT_TRACK;
+
+                process.env.SPECSMD_TELEMETRY_DISABLED = '0';
+                vi.resetModules();
+                const { isTelemetryDisabled } = await import('../../../lib/analytics/env-detector');
+
+                expect(isTelemetryDisabled()).toBe(false);
+            });
+        });
+    });
+
+    describe('tracker', () => {
+        it('should export all required methods', async () => {
+            const tracker = await import('../../../lib/analytics/tracker');
+
+            expect(typeof tracker.default.init).toBe('function');
+            expect(typeof tracker.default.trackInstallerStarted).toBe('function');
+            expect(typeof tracker.default.trackIdesConfirmed).toBe('function');
+            expect(typeof tracker.default.trackFlowSelected).toBe('function');
+            expect(typeof tracker.default.trackInstallationCompleted).toBe('function');
+            expect(typeof tracker.default.trackInstallationFailed).toBe('function');
+            expect(typeof tracker.default.isEnabled).toBe('function');
+        });
+
+        it('should return false from isEnabled before init', async () => {
+            vi.resetModules();
+            const tracker = await import('../../../lib/analytics/tracker');
+
+            expect(tracker.default.isEnabled()).toBe(false);
+        });
+
+        it('should not throw when tracking methods called before init', async () => {
+            vi.resetModules();
+            const tracker = await import('../../../lib/analytics/tracker');
+
+            // These should be silent no-ops
+            expect(() => tracker.default.trackInstallerStarted()).not.toThrow();
+            expect(() => tracker.default.trackIdesConfirmed(['test'])).not.toThrow();
+            expect(() => tracker.default.trackFlowSelected('test')).not.toThrow();
+            expect(() => tracker.default.trackInstallationCompleted('ide', 'flow', 1000, 5)).not.toThrow();
+            expect(() => tracker.default.trackInstallationFailed('ide', 'error')).not.toThrow();
+        });
+
+        it('should return false from init when telemetry is disabled', async () => {
+            process.env.SPECSMD_TELEMETRY_DISABLED = '1';
+            vi.resetModules();
+            const tracker = await import('../../../lib/analytics/tracker');
+
+            const result = tracker.default.init();
+
+            expect(result).toBe(false);
+            expect(tracker.default.isEnabled()).toBe(false);
+        });
+    });
+
+    describe('index', () => {
+        it('should export the tracker singleton', async () => {
+            const analytics = await import('../../../lib/analytics/index');
+
+            expect(analytics.default).toBeDefined();
+            expect(typeof analytics.default.init).toBe('function');
+        });
+    });
+});

package/src/iris_bundle/frameworks/iris-core/src/__tests__/unit/architecture/bolt-type-agnostic.test.ts

@@ -0,0 +1,282 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const FLOWS_PATH = path.resolve(__dirname, '../../../flows/aidlc');
+
+/**
+ * Bolt-Type Agnostic Architecture Test
+ *
+ * Purpose: Ensure that bolt-start.md, construction-agent.md, and other generic
+ * construction skills do NOT contain bolt-type-specific terminology.
+ *
+ * The Construction Agent should be bolt-type agnostic - it reads stages from
+ * the bolt type definition file and executes them without hardcoded knowledge
+ * of specific bolt types like DDD, BDD, or TDD.
+ *
+ * Violations:
+ * - construction-agent.md knowing about "domain model" or "technical design"
+ * - bolt-start.md referencing DDD-specific stages or artifacts
+ * - Any generic construction skill mentioning bolt-type-specific concepts
+ */
+
+// Terms that indicate DDD-specific knowledge (should NOT appear in generic files)
+const DDD_SPECIFIC_TERMS = [
+  // DDD Stages and Artifacts (specific names)
+  /domain\s+model/i,
+  /technical\s+design/i,
+  /ddd-01/i,
+  /ddd-02/i,
+  /ddd-03/i,
+
+  // DDD-specific stage references (numbered stages with DDD names)
+  /stage\s*[12].*domain/i,
+  /stage\s*[12].*model/i,
+  /stage\s*2.*design/i,
+  /after.*domain.*model/i,
+  /after.*technical.*design/i,
+  /completing.*domain.*model/i,
+  /completing.*technical.*design/i,
+
+  // DDD-specific artifact patterns in generic context
+  /entity:\s*\{.*name.*\}/i,
+  /value\s+objects:\s*\{.*list.*\}/i,
+];
+
+// Terms that indicate BDD-specific knowledge
+const BDD_SPECIFIC_TERMS = [
+  /feature\s+file/i,
+  /gherkin/i,
+  /cucumber/i,
+  /step\s+definition/i,
+];
+
+// Terms that indicate TDD-specific knowledge
+const TDD_SPECIFIC_TERMS = [
+  /red.*green.*refactor/i,
+  /test.*first/i,
+];
+
+// Terms that assume a specific workflow (e.g., design→code→tests)
+// These should NOT appear in generic construction skills
+const WORKFLOW_SPECIFIC_TERMS = [
+  // Hardcoded checkpoint names
+  /design\s+review/i,
+  /code\s+review/i,
+
+  // Hardcoded stage workflow
+  /code\s*\+\s*tests/i,
+  /generate.*code/i,
+  /generate.*tests/i,
+  /implementation\s+code/i,
+
+  // Test-specific outcomes (not all bolts produce tests)
+  /unit\s+tests?\s+(pass|fail)/i,
+  /tests?\s+pass/i,
+  /test\s+results/i,
+  /test\s+validation/i,
+  /all\s+tests/i,
+
+  // Auto-validation assumptions
+  /auto-validation/i,
+  /skip.*code\s+review/i,
+];
+
+// Files that MUST be bolt-type agnostic
+const AGNOSTIC_FILES = [
+  'skills/construction/bolt-start.md',
+  'skills/construction/bolt-list.md',
+  'skills/construction/bolt-status.md',
+  'skills/construction/bolt-replan.md',
+  'agents/construction-agent.md',
+];
+
+describe('Bolt-Type Agnostic Architecture', () => {
+  describe('Generic Construction Files', () => {
+    AGNOSTIC_FILES.forEach((relativePath) => {
+      const filePath = path.join(FLOWS_PATH, relativePath);
+
+      describe(relativePath, () => {
+        let content: string;
+        let fileExists: boolean;
+
+        beforeAll(() => {
+          fileExists = fs.existsSync(filePath);
+          if (fileExists) {
+            content = fs.readFileSync(filePath, 'utf-8');
+          }
+        });
+
+        it('should exist', () => {
+          expect(fileExists).toBe(true);
+        });
+
+        it('should NOT contain DDD-specific terminology', () => {
+          if (!fileExists) return;
+
+          const violations: string[] = [];
+
+          DDD_SPECIFIC_TERMS.forEach((pattern) => {
+            const matches = content.match(new RegExp(pattern, 'gi'));
+            if (matches) {
+              matches.forEach((match) => {
+                // Find line number for better error messages
+                const lines = content.split('\n');
+                const lineNum = lines.findIndex((line) =>
+                  new RegExp(pattern, 'i').test(line)
+                );
+                violations.push(
+                  `Line ${lineNum + 1}: Found DDD-specific term "${match}" (pattern: ${pattern})`
+                );
+              });
+            }
+          });
+
+          if (violations.length > 0) {
+            throw new Error(
+              `${relativePath} contains DDD-specific terminology:\n${violations.join('\n')}\n\n` +
+                'Construction skills must be bolt-type agnostic. ' +
+                'Move bolt-type-specific logic to the bolt type definition file.'
+            );
+          }
+        });
+
+        it('should NOT contain BDD-specific terminology', () => {
+          if (!fileExists) return;
+
+          const violations: string[] = [];
+
+          BDD_SPECIFIC_TERMS.forEach((pattern) => {
+            const matches = content.match(new RegExp(pattern, 'gi'));
+            if (matches) {
+              violations.push(`Found BDD-specific term: ${matches.join(', ')}`);
+            }
+          });
+
+          expect(violations).toEqual([]);
+        });
+
+        it('should NOT contain TDD-specific terminology', () => {
+          if (!fileExists) return;
+
+          const violations: string[] = [];
+
+          TDD_SPECIFIC_TERMS.forEach((pattern) => {
+            const matches = content.match(new RegExp(pattern, 'gi'));
+            if (matches) {
+              violations.push(`Found TDD-specific term: ${matches.join(', ')}`);
+            }
+          });
+
+          expect(violations).toEqual([]);
+        });
+
+        it('should NOT contain hardcoded workflow assumptions', () => {
+          if (!fileExists) return;
+
+          const violations: string[] = [];
+
+          WORKFLOW_SPECIFIC_TERMS.forEach((pattern) => {
+            const matches = content.match(new RegExp(pattern, 'gi'));
+            if (matches) {
+              matches.forEach((match) => {
+                const lines = content.split('\n');
+                const lineNum = lines.findIndex((line) =>
+                  new RegExp(pattern, 'i').test(line)
+                );
+                violations.push(
+                  `Line ${lineNum + 1}: Found workflow assumption "${match}" (pattern: ${pattern})`
+                );
+              });
+            }
+          });
+
+          if (violations.length > 0) {
+            throw new Error(
+              `${relativePath} contains hardcoded workflow assumptions:\n${violations.join('\n')}\n\n` +
+                'Generic construction skills must not assume a specific workflow. ' +
+                'A marketing research bolt has no "design review" or "code + tests" stages.'
+            );
+          }
+        });
+
+        it('should reference bolt type definition for stages', () => {
+          if (!fileExists) return;
+
+          // Generic construction files should reference loading bolt type
+          const referencessBoltType =
+            content.includes('bolt_type') ||
+            content.includes('bolt type') ||
+            content.includes('bolt-type');
+
+          expect(referencessBoltType).toBe(true);
+        });
+      });
+    });
+  });
+
+  describe('Bolt Type Definition Files', () => {
+    describe('DDD Construction Bolt', () => {
+      const filePath = path.join(
+        FLOWS_PATH,
+        'templates/construction/bolt-types/ddd-construction-bolt.md'
+      );
+      let content: string;
+      let fileExists: boolean;
+
+      beforeAll(() => {
+        fileExists = fs.existsSync(filePath);
+        if (fileExists) {
+          content = fs.readFileSync(filePath, 'utf-8');
+        }
+      });
+
+      it('should exist', () => {
+        expect(fileExists).toBe(true);
+      });
+
+      it('SHOULD contain DDD-specific terminology (it defines them)', () => {
+        if (!fileExists) return;
+
+        // DDD bolt type definition SHOULD contain these terms
+        expect(content).toMatch(/domain\s+model/i);
+        expect(content).toMatch(/technical\s+design/i);
+        expect(content).toMatch(/ddd-01/i);
+        expect(content).toMatch(/ddd-02/i);
+      });
+
+      it('should define stages that construction-agent will read', () => {
+        if (!fileExists) return;
+
+        expect(content).toMatch(/stages/i);
+        expect(content).toMatch(/stage\s*1/i);
+        expect(content).toMatch(/stage\s*2/i);
+      });
+    });
+  });
+
+  describe('Architecture Principle', () => {
+    it('documents the bolt-type agnostic principle', () => {
+      // This test documents the architectural principle
+      const principle = `
+        ARCHITECTURAL PRINCIPLE: Bolt-Type Agnosticism
+
+        The Construction Agent and its skills (bolt-start, bolt-list, etc.)
+        MUST NOT contain hardcoded knowledge of specific bolt types.
+
+        Flow:
+        1. bolt-start reads bolt.md to get bolt_type field
+        2. bolt-start loads the bolt type definition from templates/construction/bolt-types/
+        3. The bolt type definition specifies stages, artifacts, and constraints
+        4. bolt-start executes stages as defined, without knowing their names
+
+        This allows:
+        - Adding new bolt types (BDD, TDD) without modifying construction skills
+        - Each bolt type to define its own workflow
+        - Clean separation of concerns
+      `;
+
+      expect(principle).toBeTruthy();
+    });
+  });
+});

package/src/iris_bundle/frameworks/iris-core/src/__tests__/unit/flow-consistency/code-examples.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Code Examples Validity Tests
+ *
+ * Tests that code examples in templates are syntactically valid:
+ * - YAML code blocks parse correctly
+ * - Bash command examples are syntactically plausible
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import * as path from 'path';
+import { glob } from 'glob';
+import * as fs from 'fs-extra';
+import * as yaml from 'js-yaml';
+import { ValidationIssues, hasPlaceholders, readFlowFile } from './helpers';
+
+const FLOWS_PATH = path.resolve(__dirname, '../../../../../flows/aidlc');
+
+let templateFiles: string[] = [];
+
+beforeAll(async () => {
+  templateFiles = await glob(path.join(FLOWS_PATH, 'templates/**/*.md'));
+});
+
+describe('Flow Files - Code Example Validity', () => {
+
+  describe('YAML code blocks should be valid', () => {
+    it('should parse all YAML blocks in templates', async () => {
+      const issues = new ValidationIssues('YAML validation errors');
+      const yamlRegex = /```yaml\n([\s\S]*?)```/g;
+
+      for (const file of templateFiles) {
+        const content = await fs.readFile(file, 'utf8');
+        let match;
+
+        while ((match = yamlRegex.exec(content)) !== null) {
+          const yamlContent = match[1];
+
+          // Skip teaching examples with placeholders
+          if (hasPlaceholders(yamlContent)) continue;
+
+          // Skip bolt-type files (valid multi-document YAML examples)
+          if (file.includes('/bolt-types/')) continue;
+
+          try {
+            yaml.load(yamlContent);
+          } catch (error) {
+            issues.add(file, `invalid YAML - ${(error as Error).message}`);
+          }
+        }
+      }
+
+      issues.log();
+      issues.assertNone(expect);
+    });
+
+    it('should parse YAML frontmatter examples in templates', async () => {
+      const issues = new ValidationIssues('YAML frontmatter errors');
+
+      for (const file of templateFiles) {
+        // Skip teaching examples and special formatting files
+        if (file.includes('-template.md') || file.includes('.guide.md') || file.includes('/bolt-types/')) {
+          continue;
+        }
+
+        const content = await fs.readFile(file, 'utf8');
+        const frontmatterRegex = /---\n([\s\S]*?)---/g;
+        let match;
+
+        while ((match = frontmatterRegex.exec(content)) !== null) {
+          const yamlContent = match[1];
+
+          if (hasPlaceholders(yamlContent)) continue;
+
+          try {
+            yaml.load(yamlContent);
+          } catch (error) {
+            issues.add(file, `invalid YAML frontmatter - ${(error as Error).message}`);
+          }
+        }
+      }
+
+      issues.log();
+      issues.assertNone(expect);
+    });
+  });
+
+  describe('Bash command examples should be syntactically plausible', () => {
+    it('should have valid node command syntax', async () => {
+      const content = await readFlowFile('skills/construction/bolt-start.md');
+      expect(content).toMatch(/node\s+\.irismd\/scripts\/bolt-complete\.js/);
+    });
+  });
+});

package/src/iris_bundle/frameworks/iris-core/src/__tests__/unit/flow-consistency/helpers.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared utilities for flow consistency tests
+ */
+
+import * as path from 'path';
+import * as fs from 'fs-extra';
+
+export const ROOT_DIR = path.resolve(__dirname, '../../..');
+export const FLOWS_PATH = path.join(ROOT_DIR, 'flows/aidlc');
+
+/**
+ * Find all lines matching a pattern in a file, excluding certain sections
+ */
+export function findLinesExcluding(
+  content: string,
+  pattern: RegExp,
+  excludeSectionHeading: string
+): number[] {
+  const lines = content.split('\n');
+  const matches: number[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (pattern.test(lines[i])) {
+      // Check if we're in an excluded section
+      const beforeLines = lines.slice(Math.max(0, i - 20), i).join('\n');
+      if (!beforeLines.includes(excludeSectionHeading)) {
+        matches.push(i);
+      }
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Check if YAML content contains placeholders (not meant to be parsed)
+ */
+export function hasPlaceholders(yamlContent: string): boolean {
+  return /\{[A-Z]+\}|must|should|could|null|\*{2}/.test(yamlContent);
+}
+
+/**
+ * Collect validation issues across multiple files
+ */
+export class ValidationIssues {
+  private issues: string[] = [];
+  private _type: string;
+
+  constructor(type: string) {
+    this._type = type;
+  }
+
+  add(file: string, message: string): void {
+    const relPath = path.relative(ROOT_DIR, file);
+    this.issues.push(`${relPath}: ${message}`);
+  }
+
+  addWithLine(file: string, lineNumber: number, message: string): void {
+    const relPath = path.relative(ROOT_DIR, file);
+    this.issues.push(`${relPath}:${lineNumber + 1}: ${message}`);
+  }
+
+  log(): void {
+    if (this.issues.length > 0) {
+      console.error(`\n${this._type}:\n${this.issues.join('\n')}`);
+    }
+  }
+
+  assertNone(expect: jest.Expect): void {
+    expect(this.issues).toHaveLength(0);
+  }
+}
+
+/**
+ * Read file content relative to FLOWS_PATH
+ */
+export async function readFlowFile(relativePath: string): Promise<string> {
+  return fs.readFile(path.join(FLOWS_PATH, relativePath), 'utf8');
+}