fraim-framework 1.0.12 → 2.0.2

package/.ai-agents/rules/successful-debugging-patterns.md

@@ -0,0 +1,313 @@
+# Successful Debugging Patterns
+
+## INTENT
+Establish systematic debugging approaches that convert challenges into learning opportunities and prevent recurring issues through comprehensive testing and documentation.
+
+## PRINCIPLES
+- **Systematic Approach**: Follow structured debugging methodology
+- **Evidence-Based**: Document findings with concrete evidence
+- **Learning Focus**: Convert every debug session into reusable knowledge
+- **Test-Driven**: Create tests that prevent regression
+- **Pattern Recognition**: Identify and document common failure modes
+
+## SYSTEMATIC DEBUGGING METHODOLOGY
+
+### 1. Issue Reproduction
+**Goal**: Create reliable, repeatable failure conditions
+
+**Steps**:
+1. Document exact steps to reproduce
+2. Identify minimum conditions for failure
+3. Create automated reproduction script
+4. Verify reproduction works consistently
+5. Document environment and dependencies
+
+### 2. Evidence Collection
+**Goal**: Gather comprehensive data about the failure
+
+**Steps**:
+1. Collect error messages and stack traces
+2. Review relevant logs with timestamps
+3. Document system state at failure time
+4. Capture network requests/responses
+5. Record configuration and environment details
+
+### 3. Root Cause Analysis
+**Goal**: Identify the underlying cause, not just symptoms
+
+**Steps**:
+1. Trace execution flow to failure point
+2. Examine code logic and data flow
+3. Identify assumptions that may be incorrect
+4. Check for race conditions or timing issues
+5. Validate external dependencies
+
+### 4. Solution Development
+**Goal**: Create targeted fix that addresses root cause
+
+**Steps**:
+1. Design minimal fix for root cause
+2. Consider impact on other system components
+3. Plan rollback strategy if needed
+4. Implement fix with proper error handling
+5. Add monitoring/logging for future detection
+
+### 5. Validation and Testing
+**Goal**: Ensure fix works and doesn't break anything else
+
+**Steps**:
+1. Verify original issue is resolved
+2. Run comprehensive test suite
+3. Test edge cases and error conditions
+4. Validate performance impact
+5. Confirm no new issues introduced
+
+## SPECIFIC DEBUGGING TECHNIQUES
+
+### Code Analysis and Understanding
+
+**CRITICAL: Always Analyze Before Implementing**
+Before making any changes, use tools to understand the current codebase:
+
+```bash
+# Find all files that import a specific module
+grep_search --SearchPath src --Query \"import.*ApiService\" --IsRegex true --MatchPerLine true
+
+# Find files by pattern
+find_by_name --SearchDirectory src --Pattern \"*service*\" --Type file
+
+# Read specific files to understand implementation
+Read --file_path src/services/api-service.ts
+```
+
+**Pattern Analysis Requirements:**
+1. **Examine existing patterns** in the codebase (e.g., ServiceBase pattern)
+2. **Use grep_search** to find all dependencies and usage
+3. **Read actual implementations** to understand current architecture
+4. **Document findings** with real code examples and line numbers
+
+### Database Validation Scripts
+
+**Database State Validation:**
+```typescript
+const { DatabaseService } = require('./src/services/database-service');
+
+async function checkDatabaseState() {
+  console.log('🔍 Checking database state...');
+  const dbService = new DatabaseService();
+  await dbService.initialize();
+
+  try {
+    // Check for tokens
+    const tokens = await dbService.getTokens('primary');
+    console.log('📋 Tokens found:', !!tokens);
+    
+    // Check for data
+    const records = await dbService.getAllRecords();
+    console.log('📊 Records found:', records.length);
+    
+    // Check for specific data
+    const config = await dbService.getConfig('APP_CLIENT_ID');
+    console.log('🔑 Config found:', !!config);
+    
+  } catch (error) {
+    console.error('❌ Database check failed:', error);
+  } finally {
+    await dbService.close();
+  }
+}
+```
+
+**API Endpoint Testing:**
+```typescript
+async function testAPIEndpoints() {
+  const baseUrl = 'http://localhost:3000';
+  
+  // Test main API
+  try {
+    const response = await fetch(`${baseUrl}/api/data?start=2024-01-01&end=2024-01-02`);
+    const data = await response.json();
+    console.log('📊 Data API:', response.status, data);
+  } catch (error) {
+    console.error('❌ Data API failed:', error);
+  }
+  
+  // Test status API
+  try {
+    const response = await fetch(`${baseUrl}/api/status`);
+    const data = await response.json();
+    console.log('💬 Status API:', response.status, data);
+  } catch (error) {
+    console.error('❌ Status API failed:', error);
+  }
+}
+```
+
+## COMMON DEBUGGING SCENARIOS
+
+### Authentication Issues
+**Symptoms**: 401 errors, token validation failures
+**Common Causes**:
+- Expired tokens not being refreshed
+- Missing authentication headers
+- Incorrect token format or encoding
+- Clock skew between systems
+
+**Debugging Steps**:
+1. Verify token expiration times
+2. Check token refresh logic
+3. Validate authentication headers
+4. Test with known-good tokens
+
+### API Integration Issues
+**Symptoms**: Network errors, unexpected responses
+**Common Causes**:
+- Rate limiting
+- API version mismatches
+- Incorrect request formatting
+- Network connectivity issues
+
+**Debugging Steps**:
+1. Check API documentation for changes
+2. Verify request format and headers
+3. Test with API debugging tools
+4. Monitor rate limits and quotas
+
+### Database Connection Issues
+**Symptoms**: Connection timeouts, query failures
+**Common Causes**:
+- Connection pool exhaustion
+- Database server issues
+- Network connectivity problems
+- Query performance issues
+
+**Debugging Steps**:
+1. Check connection pool status
+2. Verify database server health
+3. Analyze slow query logs
+4. Test connection from different environments
+
+## LEARNING AND DOCUMENTATION
+
+### Issue Documentation Template
+```markdown
+# Debug Session: [Issue Title]
+
+## Problem Description
+[Clear description of the issue]
+
+## Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. [Expected vs Actual behavior]
+
+## Investigation Process
+- **Hypothesis 1**: [What you thought might be wrong]
+  - **Test**: [How you tested it]
+  - **Result**: [What you found]
+- **Hypothesis 2**: [Next theory]
+  - **Test**: [How you tested it]
+  - **Result**: [What you found]
+
+## Root Cause
+[The actual underlying cause]
+
+## Solution
+[What you changed to fix it]
+
+## Prevention
+- **Tests Added**: [New tests to prevent regression]
+- **Monitoring Added**: [New alerts or logging]
+- **Documentation Updated**: [What docs were improved]
+
+## Lessons Learned
+[Key insights for future debugging]
+```
+
+### Creating Regression Tests
+**Always create tests that would have caught the bug:**
+
+```typescript
+describe('Bug Fix: [Issue Description]', () => {
+  it('should handle [specific failure condition]', async () => {
+    // Arrange: Set up the exact conditions that caused the bug
+    const testData = createTestConditions();
+    
+    // Act: Perform the action that previously failed
+    const result = await performAction(testData);
+    
+    // Assert: Verify the fix works
+    expect(result).toBeDefined();
+    expect(result.status).toBe('success');
+  });
+  
+  it('should not break existing functionality', async () => {
+    // Regression test to ensure fix doesn't break other features
+    const existingFlow = await testExistingWorkflow();
+    expect(existingFlow).toMatchSnapshot();
+  });
+});
+```
+
+## ESCALATION PATTERNS
+
+### When to Escalate
+- Issue persists after 2+ hours of systematic debugging
+- Root cause requires architectural changes
+- Issue affects production systems
+- Solution requires expertise outside your domain
+
+### How to Escalate
+1. **Document everything**: Provide complete investigation history
+2. **Be specific**: Include exact error messages and reproduction steps
+3. **Show your work**: Explain what you've tried and why
+4. **Suggest options**: Propose potential solutions if you have ideas
+5. **Set context**: Explain business impact and urgency
+
+### Escalation Template
+```markdown
+# Escalation: [Issue Title]
+
+## Summary
+[Brief description of the problem]
+
+## Business Impact
+- **Affected Users**: [Who is impacted]
+- **Severity**: [Critical/High/Medium/Low]
+- **Timeline**: [When this needs to be resolved]
+
+## Investigation Summary
+- **Time Spent**: [Hours invested]
+- **Approaches Tried**: [List of debugging attempts]
+- **Current Status**: [Where you're stuck]
+
+## Technical Details
+- **Error Messages**: [Exact error text]
+- **Reproduction Steps**: [How to reproduce]
+- **Environment**: [System details]
+
+## Requested Help
+- **Specific Question**: [What you need help with]
+- **Suggested Approach**: [Your ideas, if any]
+- **Resources Needed**: [Additional access, tools, etc.]
+```
+
+## CONTINUOUS IMPROVEMENT
+
+### Post-Debug Review
+After resolving any significant issue:
+1. **Document the solution** in team knowledge base
+2. **Update debugging runbooks** with new patterns
+3. **Improve monitoring** to catch similar issues earlier
+4. **Share learnings** with team in retrospectives
+5. **Update automated tests** to prevent regression
+
+### Pattern Recognition
+Keep track of:
+- **Common failure modes** in your system
+- **Effective debugging techniques** for different issue types
+- **Tools and commands** that consistently help
+- **Environmental factors** that contribute to issues
+- **Time patterns** when issues typically occur
+
+This systematic approach ensures that every debugging session contributes to the overall system reliability and team knowledge.

package/.ai-agents/scripts/cleanup-branch.ts

@@ -0,0 +1,278 @@
+#!/usr/bin/env npx tsx
+
+import { execSync } from 'child_process';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config({ override: true });
+
+interface CleanupOptions {
+  branchName?: string;
+  force?: boolean;
+  skipProjectCleanup?: boolean;
+  skipGit?: boolean;
+}
+
+class BranchCleanup {
+  private options: CleanupOptions;
+
+  constructor(options: CleanupOptions = {}) {
+    this.options = {
+      branchName: options.branchName,
+      force: options.force || false,
+      skipProjectCleanup: options.skipProjectCleanup || false,
+      skipGit: options.skipGit || false,
+    };
+  }
+
+  private async insertYourCodeHere(branchName: string): Promise<void> {
+    // add project specific cleanup code here   
+  }
+
+
+  private log(message: string, level: 'info' | 'warn' | 'error' | 'success' = 'info') {
+    const timestamp = new Date().toISOString();
+    const prefix = {
+      info: 'ℹ️ ',
+      warn: '⚠️ ',
+      error: '❌',
+      success: '✅'
+    }[level];
+    
+    console.log(`${prefix} [${timestamp}] ${message}`);
+  }
+
+  private async executeCommand(command: string, description: string): Promise<string> {
+    this.log(`Executing: ${description}`);
+
+    try {
+      const result = execSync(command, { 
+        encoding: 'utf8',
+        stdio: 'pipe',
+        cwd: process.cwd()
+      });
+      this.log(`Success: ${description}`, 'success');
+      return result;
+    } catch (error: any) {
+      this.log(`Failed: ${description} - ${error.message}`, 'error');
+      throw error;
+    }
+  }
+
+  private async getCurrentBranch(): Promise<string> {
+    try {
+      const result = await this.executeCommand('git branch --show-current', 'Get current branch');
+      return result.trim();
+    } catch (error) {
+      this.log('Could not determine current branch', 'warn');
+      return 'unknown';
+    }
+  }
+
+  private async getBranchName(): Promise<string> {
+    if (this.options.branchName) {
+      return this.options.branchName;
+    }
+
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === 'master' || currentBranch === 'main') {
+      throw new Error('Cannot cleanup master/main branch. Please specify a feature branch name.');
+    }
+
+    return currentBranch;
+  }
+
+  private async checkBranchExists(branchName: string, remote: boolean = false): Promise<boolean> {
+    try {
+      const command = remote 
+        ? `git ls-remote --heads origin ${branchName}`
+        : `git branch --list ${branchName}`;
+      
+      const result = await this.executeCommand(command, `Check if ${remote ? 'remote' : 'local'} branch exists`);
+      return result.trim().length > 0;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  private async doProjectSpecificCleanup(branchName: string): Promise<void> {
+    try {  
+        if (this.options.skipProjectCleanup) {
+        this.log('Skipping project-specific cleanup', 'warn');
+        return;
+        }
+
+        this.log('Starting project-specific cleanup...');
+
+        await this.insertYourCodeHere(branchName);
+
+        this.log('Project-specific cleanup completed successfully', 'success');
+    } catch (error: any) {
+      this.log(`Project-specific cleanup failed: ${error.message}`, 'error');
+      if (!this.options.force) {
+        throw error;
+      }
+    }
+  }
+
+  private async cleanupGitBranches(branchName: string): Promise<void> {
+    if (this.options.skipGit) {
+      this.log('Skipping Git cleanup', 'warn');
+      return;
+    }
+
+    this.log(`Starting Git branch cleanup for: ${branchName}`);
+
+    // Check if we're on the branch we want to delete
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === branchName) {
+      this.log(`Currently on branch ${branchName}, switching to master first`, 'warn');
+      await this.executeCommand('git checkout master', 'Switch to master branch');
+    }
+
+    // Delete remote branch
+    const remoteExists = await this.checkBranchExists(branchName, true);
+    if (remoteExists) {
+      this.log(`Deleting remote branch: origin/${branchName}`);
+      await this.executeCommand(`git push origin --delete ${branchName}`, `Delete remote branch ${branchName}`);
+    } else {
+      this.log(`Remote branch origin/${branchName} does not exist`, 'info');
+    }
+
+    // Delete local branch
+    const localExists = await this.checkBranchExists(branchName, false);
+    if (localExists) {
+      this.log(`Deleting local branch: ${branchName}`);
+      await this.executeCommand(`git branch -D ${branchName}`, `Delete local branch ${branchName}`);
+    } else {
+      this.log(`Local branch ${branchName} does not exist`, 'info');
+    }
+
+    // Clean up any untracked files
+    this.log('Cleaning up untracked files...');
+    await this.executeCommand('git clean -fd', 'Remove untracked files and directories');
+
+    // Reset any uncommitted changes
+    this.log('Resetting uncommitted changes...');
+    await this.executeCommand('git reset --hard HEAD', 'Reset to HEAD');
+
+    this.log('Git branch cleanup completed', 'success');
+  }
+
+
+  private async verifyCleanup(branchName: string): Promise<void> {
+    this.log('Verifying cleanup...');
+
+    // Verify branch deletion
+    const remoteExists = await this.checkBranchExists(branchName, true);
+    const localExists = await this.checkBranchExists(branchName, false);
+
+    if (remoteExists || localExists) {
+      this.log(`Warning: Branch ${branchName} still exists (remote: ${remoteExists}, local: ${localExists})`, 'warn');
+    } else {
+      this.log(`Branch ${branchName} successfully deleted`, 'success');
+    }
+
+    // Verify we're on master
+    const currentBranch = await this.getCurrentBranch();
+    if (currentBranch === 'master' || currentBranch === 'main') {
+      this.log('Currently on master/main branch', 'success');
+    } else {
+      this.log(`Warning: Not on master branch, currently on ${currentBranch}`, 'warn');
+    }
+
+    this.log('Cleanup verification completed', 'success');
+  }
+
+  async cleanup(): Promise<void> {
+    try {
+      this.log('🚀 Starting branch cleanup process...');
+
+      const branchName = await this.getBranchName();
+      this.log(`Target branch: ${branchName}`);
+
+      // Step 1: Project-specific cleanup
+      await this.doProjectSpecificCleanup(branchName);
+
+      // Step 2: Git branch cleanup
+      await this.cleanupGitBranches(branchName);
+
+      // Step 3: Verification
+      await this.verifyCleanup(branchName);
+
+      this.log('🎉 Branch cleanup completed successfully!', 'success');
+
+    } catch (error: any) {
+      this.log(`Cleanup failed: ${error.message}`, 'error');
+      if (!this.options.force) {
+        process.exit(1);
+      }
+    }
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options: CleanupOptions = {};
+
+// Parse arguments
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  
+  switch (arg) {
+    case '--branch':
+    case '-b':
+      options.branchName = args[++i];
+      break;
+    case '--force':
+    case '-f':
+      options.force = true;
+      break;
+    case '--skip-project-cleanup':
+      options.skipProjectCleanup = true;
+      break;
+    case '--skip-git':
+      options.skipGit = true;
+      break;
+    case '--help':
+    case '-h':
+      console.log(`
+🧹 Branch Cleanup Script
+
+Usage:
+  npx tsx .ai-agents/scripts/cleanup-branch.ts [options]
+
+Options:
+  --branch, -b <name>              Specific branch name to cleanup (default: current branch)
+  --force, -f                      Continue even if some operations fail
+  --skip-project-cleanup           Skip project-specific cleanup
+  --skip-git                       Skip Git branch deletion
+  --help, -h                       Show this help message
+
+Examples:
+  # Cleanup current branch with default settings
+  npx tsx .ai-agents/scripts/cleanup-branch.ts
+
+  # Cleanup specific branch
+  npx tsx .ai-agents/scripts/cleanup-branch.ts --branch feature/123
+
+  # Force cleanup even if some operations fail
+  npx tsx .ai-agents/scripts/cleanup-branch.ts --force
+
+  # Skip project-specific cleanup (only do Git cleanup)
+  npx tsx .ai-agents/scripts/cleanup-branch.ts --skip-project-cleanup
+
+This script performs the following cleanup operations:
+1. 🗄️  Project-specific cleanup (calls existing cleanup-mongo-schemas.ts with branch-based pattern)
+2. 🌿 Git branch deletion (remote and local)
+3. ✅ Verification of cleanup completion
+
+⚠️  WARNING: This script will permanently delete branches and data!
+      `);
+      process.exit(0);
+  }
+}
+
+// Run the cleanup
+const cleanup = new BranchCleanup(options);
+cleanup.cleanup();

package/.ai-agents/scripts/exec-with-timeout.ts

@@ -0,0 +1,122 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import fg from "fast-glob";
+import kill from "tree-kill";
+import os from "os";
+
+function parseArgs(argv: string[]) {
+  const out: any = { cmd: [], timeout: 120, logfile: "run.log" };
+  let parsingCmd = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+
+    if (!parsingCmd) {
+      if (a === "--timeout" && argv[i + 1]) {
+        out.timeout = parseInt(argv[++i], 10);
+      } else if (a.startsWith("--timeout=")) {
+        out.timeout = parseInt(a.split("=")[1], 10);
+      } else if (a === "--logfile" && argv[i + 1]) {
+        out.logfile = argv[++i];
+      } else if (a.startsWith("--logfile=")) {
+        out.logfile = a.split("=")[1];
+      } else if (a === "--") {
+        parsingCmd = true; // everything after this is command
+      } else {
+        parsingCmd = true;
+        out.cmd.push(a);
+      }
+    } else {
+      out.cmd.push(a);
+    }
+  }
+
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.cmd.length) {
+    console.error(
+      "Usage: exec-with-timeout <cmd> [args...] [--timeout 120] [--logfile run.log]"
+    );
+    process.exit(2);
+  }
+
+  const logPath = path.resolve(process.cwd(), args.logfile);
+  const out = fs.createWriteStream(logPath, { flags: "a" });
+  out.write(
+    `\n--- RUN: ${args.cmd.join(" ")} @ ${new Date().toISOString()} (timeout ${
+      args.timeout
+    }s) ---\n`
+  );
+
+  // Expand globs (e.g. test*.ts)
+  let [cmd, ...argv] = args.cmd;
+  let expanded: string[] = [];
+  for (const a of argv) {
+    if (a.includes("*")) {
+      const matches = await fg(a);
+      expanded.push(...matches);
+    } else {
+      expanded.push(a);
+    }
+  }
+
+  let child;
+  if (os.platform() === "win32" && (cmd === "npm" || cmd === "npx")) {
+    // On Windows, run the full command line with shell
+    const fullCommand = [cmd, ...expanded].join(" ");
+    child = spawn(fullCommand, { stdio: ["ignore", "pipe", "pipe"], shell: true });
+  } else {
+    // On Linux/Mac, do it the normal way
+    child = spawn(cmd, expanded, { stdio: ["ignore", "pipe", "pipe"] });
+  }
+
+
+
+  child.stdout.on("data", (d) => {
+    process.stdout.write(d);
+    out.write(d);
+  });
+
+  child.stderr.on("data", (d) => {
+    process.stderr.write(d);
+    out.write(d);
+  });
+
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    out.write(
+      `\n[exec-with-timeout] TIMEOUT after ${args.timeout}s → killing process tree\n`
+    );
+    kill(child.pid!, "SIGTERM");
+
+    setTimeout(() => {
+      try {
+        kill(child.pid!, "SIGKILL");
+      } catch {}
+    }, 2000);
+  }, args.timeout * 1000);
+
+  child.on("exit", (code, signal) => {
+    clearTimeout(timer);
+    out.write(
+      `\n--- EXIT: code=${code} signal=${signal} timedOut=${timedOut} ---\n`
+    );
+    out.end();
+
+    if (timedOut) {
+      console.error(`[guard] Command timed out: ${args.cmd.join(" ")}`);
+      process.exit(124);
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});