fraim-framework 2.0.3 → 2.0.4

package/examples/simple-webapp/TESTING.md

@@ -0,0 +1,62 @@
+# Testing with FRAIM Framework
+
+This directory contains example test cases that demonstrate how to use the FRAIM testing framework with proper tagging and structure.
+
+## Test Structure
+
+The example test file (`example-test.ts`) demonstrates:
+
+- **BaseTestCase Interface**: All test cases extend the `BaseTestCase` interface
+- **Tagging System**: Tests are tagged with categories like `smoke`, `integration`, `performance`, etc.
+- **Test Organization**: Tests are organized by functionality and complexity
+- **Mock Functions**: Example mock functions for common scenarios
+
+## Recommended Test Tags (you can add others to your preference)
+
+- **`smoke`**: Critical tests that must pass for basic functionality
+- **`flaky`**: Tests that may be unreliable or environment-dependent
+- **`failing`**: Tests that are currently failing and need debugging
+
+## Running Tests
+
+### Run All Tests
+```bash
+npx run test example-test.ts
+```
+
+### Run Only Smoke Tests
+```bash
+npx run test-smoke example-test.ts
+```
+
+### Run Only Flaky Tests
+```bash
+npx run test-flkay *test*.ts
+```
+
+## Best Practices
+
+1. **Always use tags**: Tag your tests appropriately for easy filtering
+2. **Include descriptions**: Provide clear descriptions of what each test does
+3. **Use meaningful names**: Test names should clearly indicate what's being tested
+4. **Handle errors gracefully**: Catch and report errors appropriately
+5. **Use mocks for external dependencies**: Don't rely on external services in tests
+6. **Test both success and failure cases**: Ensure your tests cover edge cases
+
+## Integration with FRAIM
+
+This testing framework integrates with FRAIM's agent coordination system:
+
+- **AI Agents**: Use these tests during implementation phase
+- **CI/CD**: Automated test execution with proper tagging
+- **Evidence Collection**: Test results are collected as evidence for reviews
+
+## Customization
+
+To adapt this testing framework for your project:
+
+1. **Update mock functions**: Replace example mocks with your actual functions
+2. **Add project-specific tags**: Define tags relevant to your domain
+3. **Customize test structure**: Modify the test case interface as needed
+4. **Add setup/teardown**: Include any necessary test setup or cleanup
+5. **Configure CI integration**: Set up automated test execution in your CI pipeline

package/examples/simple-webapp/example-test.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env tsx
+
+/**
+ * Example Test Case for FRAIM Framework
+ * 
+ * This demonstrates how to write test cases using the FRAIM testing framework
+ * with proper tagging and structure.
+ */
+
+import { BaseTestCase, runTests } from '../../test-utils';
+
+// Example test case interface extending BaseTestCase
+interface ExampleTestCase extends BaseTestCase {
+  description: string;
+  testFunction: () => Promise<boolean>;
+}
+
+// Example test cases with different tags
+const EXAMPLE_TEST_CASES: ExampleTestCase[] = [
+  {
+    name: 'test_basic_functionality',
+    tags: ['smoke', 'basic'],
+    description: 'Should verify basic application functionality works',
+    testFunction: async () => {
+      console.log('🧪 Testing basic functionality...');
+      
+      // Example: Test that a basic function works
+      const result = await basicFunction();
+      
+      if (result !== 'success') {
+        console.log(`❌ Expected 'success', got '${result}'`);
+        return false;
+      }
+      
+      console.log('✅ Basic functionality test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_user_authentication',
+    tags: ['smoke', 'auth'],
+    description: 'Should verify user authentication works correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing user authentication...');
+      
+      // Example: Test authentication flow
+      const authResult = await authenticateUser('test@example.com', 'password123');
+      
+      if (!authResult.success) {
+        console.log(`❌ Authentication failed: ${authResult.error}`);
+        return false;
+      }
+      
+      console.log('✅ User authentication test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_api_integration',
+    tags: ['integration', 'api'],
+    description: 'Should verify API integration works correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing API integration...');
+      
+      // Example: Test API call
+      const apiResult = await callExternalAPI('https://api.example.com/data');
+      
+      if (!apiResult || !apiResult.data) {
+        console.log('❌ API integration failed - no data returned');
+        return false;
+      }
+      
+      console.log('✅ API integration test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_database_operations',
+    tags: ['database', 'integration'],
+    description: 'Should verify database operations work correctly',
+    testFunction: async () => {
+      console.log('🧪 Testing database operations...');
+      
+      // Example: Test database operations
+      const dbResult = await performDatabaseOperation();
+      
+      if (!dbResult.success) {
+        console.log(`❌ Database operation failed: ${dbResult.error}`);
+        return false;
+      }
+      
+      console.log('✅ Database operations test passed');
+      return true;
+    }
+  },
+  {
+    name: 'test_performance_benchmark',
+    tags: ['performance', 'flaky'],
+    description: 'Should verify performance meets requirements (may be flaky)',
+    testFunction: async () => {
+      console.log('🧪 Testing performance benchmark...');
+      
+      const startTime = Date.now();
+      await performExpensiveOperation();
+      const endTime = Date.now();
+      
+      const duration = endTime - startTime;
+      const maxDuration = 1000; // 1 second
+      
+      if (duration > maxDuration) {
+        console.log(`❌ Performance test failed: ${duration}ms > ${maxDuration}ms`);
+        return false;
+      }
+      
+      console.log(`✅ Performance test passed: ${duration}ms`);
+      return true;
+    }
+  },
+  {
+    name: 'test_failing_scenario',
+    tags: ['failing', 'debug'],
+    description: 'This test is currently failing and needs debugging',
+    testFunction: async () => {
+      console.log('🧪 Testing failing scenario...');
+      
+      // This test is intentionally failing to demonstrate the failing tag
+      console.log('❌ This test is currently failing for demonstration');
+      return false;
+    }
+  }
+];
+
+// Mock functions for demonstration
+async function basicFunction(): Promise<string> {
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 10));
+  return 'success';
+}
+
+async function authenticateUser(email: string, password: string): Promise<{success: boolean, error?: string}> {
+  // Simulate authentication
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  if (email === 'test@example.com' && password === 'password123') {
+    return { success: true };
+  }
+  
+  return { success: false, error: 'Invalid credentials' };
+}
+
+async function callExternalAPI(url: string): Promise<{data?: any}> {
+  // Simulate API call
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  return {
+    data: {
+      id: 1,
+      name: 'Test Data',
+      timestamp: new Date().toISOString()
+    }
+  };
+}
+
+async function performDatabaseOperation(): Promise<{success: boolean, error?: string}> {
+  // Simulate database operation
+  await new Promise(resolve => setTimeout(resolve, 75));
+  
+  return { success: true };
+}
+
+async function performExpensiveOperation(): Promise<void> {
+  // Simulate expensive operation
+  await new Promise(resolve => setTimeout(resolve, 500));
+}
+
+// Test runner function
+const runExampleTest = async (testCase: ExampleTestCase): Promise<boolean> => {
+  try {
+    return await testCase.testFunction();
+  } catch (error) {
+    console.log(`❌ Test ${testCase.name} threw an error: ${error}`);
+    return false;
+  }
+};
+
+await runTests(EXAMPLE_TEST_CASES, runExampleTest, 'Example Test Suite');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -49,6 +49,15 @@
     "tsx": "^4.0.0",
     "dotenv": "^16.0.0"
   },
+  "files": [
+    ".ai-agents/",
+    "examples/",
+    "bin/",
+    "*.js",
+    "*.ts",
+    "*.md",
+    "*.json"
+  ],
   "publishConfig": {
     "access": "public"
   }

package/.cursor/rules/cursor-rules.mdc

@@ -1,8 +0,0 @@
----
-description: Centralized AI agent rules for Cursor
-alwaysApply: true
----
-
-# Cursor AI Agent Rules
-
-Thoroughly review `.ai-agents/agent-guardrails.md`

package/.cursor/rules/design.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/design.md`

package/.cursor/rules/implement.mdc

@@ -1,6 +0,0 @@
----
-
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/implement.md`

package/.cursor/rules/resolve.mdc

@@ -1,5 +0,0 @@
----
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/resolve.md`

package/.cursor/rules/retrospect.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.cursor/rules/spec.mdc

@@ -1,4 +0,0 @@
----
-alwaysApply: false
----
-Follow instructions in `.ai-agents/workflows/spec.md`

package/.cursor/rules/test.mdc

@@ -1,5 +0,0 @@
----
-alwaysApply: false
----
-
-Follow instructions in `.ai-agents/workflows/test.md`

package/.windsurf/rules/windsurf-rules.md

@@ -1,7 +0,0 @@
----
-trigger: always_on
----
-
-# Windsurf AI Agent Rules
-
-Thoroughly review `.ai-agents/agent-guardrails.md`

package/.windsurf/workflows/resolve-issue.md

@@ -1,6 +0,0 @@
----
-description: Resolve issue (once confirmed complete)
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/resolve.md`

package/.windsurf/workflows/retrospect.md

@@ -1,6 +0,0 @@
----
-description: Resolve issue (once confirmed complete)
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/retrospect.md`

package/.windsurf/workflows/start-design.md

@@ -1,6 +0,0 @@
----
-description: Start working on the issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/design.md`

package/.windsurf/workflows/start-impl.md

@@ -1,6 +0,0 @@
----
-description: Implement issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/implement.md`

package/.windsurf/workflows/start-spec.md

@@ -1,6 +0,0 @@
----
-description: Spec Issue
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/spec.md`

package/.windsurf/workflows/start-tests.md

@@ -1,6 +0,0 @@
----
-description: Start writing tests
-auto_execution_mode: 3
----
-
-Follow instructions in `.ai-agents/workflows/test.md`

package/CODEOWNERS

@@ -1,24 +0,0 @@
-# This file defines the code owners for the FRAIM repository
-# Code owners are automatically requested for review when someone opens a PR that modifies code they own
-# See: https://docs.github.com/en/repositories/managing-your-codebase-in-github/about-code-owners
-
-# Default owners for everything in the repo
-*       @mathursrus
-
-# Specific ownership for different parts of the codebase
-/agents/         @mathursrus
-/rules/          @mathursrus
-/workflows/      @mathursrus
-/templates/      @mathursrus
-/scripts/        @mathursrus
-/.github/        @mathursrus
-
-# Documentation
-/docs/           @mathursrus
-*.md             @mathursrus
-
-# Configuration files
-*.json           @mathursrus
-*.jsonc          @mathursrus
-*.yml            @mathursrus
-*.yaml           @mathursrus

package/install.sh

@@ -1,58 +0,0 @@
-#!/bin/bash
-
-# FRAIM One-Line Installer
-# Framework for Rigor-based AI Management
-# Where humans become AI managers through rigorous methodology
-
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-# Banner
-echo -e "${BLUE}"
-cat << 'EOF'
-╔══════════════════════════════════════════════════════════════╗
-║  🚀 FRAIM                                                  ║
-║  Framework for Rigor-based AI Management                    ║
-║  Where humans become AI managers                            ║
-╚══════════════════════════════════════════════════════════════╝
-EOF
-echo -e "${NC}"
-
-echo -e "${GREEN}🤖 Welcome to FRAIM!${NC}"
-echo -e "${GREEN}Where humans become AI managers through rigorous methodology${NC}\n"
-
-# Check if we're in a git repository
-if [ ! -d ".git" ]; then
-    echo -e "${RED}❌ Error: Not in a git repository${NC}"
-    echo "Please run this script from within a git repository."
-    exit 1
-fi
-
-# Check if FRAIM is already installed
-if [ -d "FRAIM" ]; then
-    echo -e "${YELLOW}⚠️  FRAIM appears to already be installed in this repository${NC}"
-    echo "If you want to reinstall, please remove the existing FRAIM folder first."
-    exit 1
-fi
-
-echo -e "${BLUE}📥 Installing FRAIM framework...${NC}"
-
-# Download FRAIM from GitHub
-echo "Downloading FRAIM framework..."
-curl -sSL https://raw.githubusercontent.com/mathursrus/FRAIM/master/install.sh | bash -s -- --repo $(git remote get-url origin | sed 's/.*github.com[:/]\([^/]*\/[^/]*\).*/\1/' | sed 's/\.git$//')
-
-echo -e "\n${GREEN}✅ FRAIM installation complete!${NC}"
-echo -e "\n${BLUE}🚀 Next steps:${NC}"
-echo "1. Review the FRAIM folder that was created"
-echo "2. Run: npx @fraim/framework init"
-echo "3. Start managing your AI agents with RIGOR methodology!"
-echo -e "\n${BLUE}📚 Learn more:${NC}"
-echo "Documentation: https://github.com/mathursrus/FRAIM"
-echo -e "\n${GREEN}🎯 Ready to become an AI manager?${NC}"
-echo "The FRAIM framework is now installed and ready to use!"