s9n-devops-agent 1.6.2 → 1.7.0

package/docs/AUTOMATED_TESTING_STRATEGY.md

@@ -0,0 +1,316 @@
+# Automated Testing Strategy for Branch Management System
+
+**Date:** October 10, 2025
+
+This document outlines the comprehensive automated testing strategy for the DevOps Agent's branch management system. The strategy addresses the unique challenges of testing git operations, multi-session scenarios, and complex branching workflows.
+
+## 1. Testing Challenges
+
+Testing a branch management system presents several unique challenges that our framework addresses:
+
+### 1.1 Git State Management
+- **Challenge**: Each test needs a clean git repository state
+- **Solution**: Isolated test repositories created in temporary directories for each test case
+
+### 1.2 Multi-Session Simulation
+- **Challenge**: Testing scenarios with multiple concurrent sessions
+- **Solution**: Mock session creation with realistic branch structures and commit histories
+
+### 1.3 Time-Based Logic
+- **Challenge**: Testing orphaned session detection and day rollovers
+- **Solution**: Controlled date manipulation and mock session aging
+
+### 1.4 File System Operations
+- **Challenge**: Testing worktree creation, cleanup, and file coordination
+- **Solution**: Temporary directories with full cleanup after each test
+
+## 2. Testing Framework Architecture
+
+### 2.1 Core Components
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| **BranchManagementTestFramework** | Base testing infrastructure | Isolated repos, git operations, assertions |
+| **Test Suites** | Specific functionality testing | Session closure, weekly consolidation, orphan cleanup |
+| **Test Runner** | Orchestration and reporting | Parallel execution, comprehensive reporting |
+| **Mock Utilities** | Simulation helpers | Session creation, branch aging, configuration |
+
+### 2.2 Test Isolation Strategy
+
+Each test runs in complete isolation:
+
+```javascript
+// Test lifecycle
+1. Create temporary git repository
+2. Copy source files to test repo
+3. Initialize git with test configuration
+4. Execute test logic
+5. Validate results with assertions
+6. Clean up temporary repository
+```
+
+This ensures no test can affect another and provides a clean slate for each scenario.
+
+## 3. Test Categories
+
+### 3.1 Unit Tests
+Focus on individual functions and methods within each script.
+
+**Coverage Areas:**
+- Branch name generation and validation
+- Configuration parsing and validation
+- Date calculations and formatting
+- Git command execution and error handling
+
+**Example:**
+```javascript
+// Test branch name generation
+const consolidator = new WeeklyConsolidator();
+const dailyBranches = ['daily/2025-10-01', 'daily/2025-10-02'];
+const weeklyName = consolidator.generateWeeklyBranchName(dailyBranches);
+expect(weeklyName).toBe('weekly/2025-10-01_to_2025-10-02');
+```
+
+### 3.2 Integration Tests
+Test interactions between different components of the system.
+
+**Key Scenarios:**
+- Session closure triggering branch merges
+- Configuration changes affecting behavior
+- Error propagation and recovery
+- File coordination between components
+
+### 3.3 End-to-End Tests
+Simulate complete user workflows from start to finish.
+
+**Comprehensive Scenarios:**
+- Full week of development with multiple sessions
+- Day rollover with active sessions
+- Weekly consolidation with dual merge
+- Orphaned session cleanup after threshold period
+
+## 4. Test Data Management
+
+### 4.1 Mock Session Creation
+The framework provides utilities to create realistic test sessions:
+
+```javascript
+// Create a session with commits and branch structure
+const session = framework.createMockSession('test-session', 'feature-work');
+
+// Create an aged session for orphan testing
+const oldSession = framework.createOldSession('old-session', 10); // 10 days old
+```
+
+### 4.2 Configuration Testing
+Multiple configuration scenarios are tested:
+
+```javascript
+// Test with dual merge enabled
+framework.createProjectSettings({
+  branchManagement: {
+    enableDualMerge: true,
+    defaultMergeTarget: 'main',
+    mergeStrategy: 'hierarchical-first'
+  }
+});
+```
+
+### 4.3 Branch Structure Simulation
+The framework can create complex branch structures:
+
+```javascript
+// Create daily branches for testing weekly consolidation
+const dates = ['2025-10-01', '2025-10-02', '2025-10-03'];
+const dailyBranches = framework.createDailyBranches(dates);
+```
+
+## 5. Assertion Framework
+
+### 5.1 Git-Specific Assertions
+Custom assertions for git operations:
+
+```javascript
+// Branch existence checks
+framework.assertBranchExists('weekly/2025-10-01_to_2025-10-07');
+framework.assertBranchNotExists('session/agent/old-task');
+
+// File system checks
+framework.assertFileExists('local_deploy/session-locks/session-id.lock');
+framework.assertFileNotExists('.devops-commit-session-id.msg');
+```
+
+### 5.2 State Validation
+Comprehensive state validation after operations:
+
+```javascript
+// Verify complete session cleanup
+const verifySessionCleanup = (sessionData) => {
+  framework.assertBranchNotExists(sessionData.branchName);
+  framework.assertFileNotExists(`local_deploy/session-locks/${sessionData.sessionId}.lock`);
+  framework.assertFileNotExists(`.devops-commit-${sessionData.sessionId}.msg`);
+};
+```
+
+## 6. Error Handling and Recovery Testing
+
+### 6.1 Merge Conflict Simulation
+Tests include scenarios with merge conflicts:
+
+```javascript
+// Create conflicting content in different branches
+execSync(`git checkout ${sessionBranch}`, { stdio: 'ignore' });
+fs.writeFileSync('conflict.txt', 'Session content\n');
+execSync('git add conflict.txt && git commit -m "Session changes"', { stdio: 'ignore' });
+
+execSync('git checkout main', { stdio: 'ignore' });
+fs.writeFileSync('conflict.txt', 'Main content\n');
+execSync('git add conflict.txt && git commit -m "Main changes"', { stdio: 'ignore' });
+```
+
+### 6.2 Partial Failure Scenarios
+Tests verify graceful handling of partial failures:
+
+- One merge succeeds, another fails in dual merge
+- Some daily branches merge successfully, others conflict
+- Network failures during remote operations
+
+## 7. Performance and Scalability Testing
+
+### 7.1 Large Repository Simulation
+Tests with many branches and sessions:
+
+```javascript
+// Create 50 daily branches for stress testing
+const manyDates = Array.from({length: 50}, (_, i) => {
+  const date = new Date();
+  date.setDate(date.getDate() - i);
+  return date.toISOString().split('T')[0];
+});
+framework.createDailyBranches(manyDates);
+```
+
+### 7.2 Concurrent Operation Testing
+Simulate multiple agents working simultaneously:
+
+```javascript
+// Create multiple sessions with overlapping timeframes
+const sessions = [
+  framework.createMockSession('agent1-session', 'feature-a', 'agent1'),
+  framework.createMockSession('agent2-session', 'feature-b', 'agent2'),
+  framework.createMockSession('agent3-session', 'feature-c', 'agent3')
+];
+```
+
+## 8. Continuous Integration Integration
+
+### 8.1 GitHub Actions Workflow
+The test suite integrates with CI/CD:
+
+```yaml
+name: Branch Management Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install
+      - run: node test_cases/branch-management/run-all-tests.js
+```
+
+### 8.2 Test Reporting
+Comprehensive test reports are generated:
+
+- **Summary**: Pass/fail counts and duration
+- **Details**: Individual test results with error messages
+- **Coverage**: Code coverage metrics for each component
+- **Performance**: Execution time trends over commits
+
+## 9. Running the Tests
+
+### 9.1 Command Line Interface
+
+```bash
+# Run all test suites
+node test_cases/branch-management/run-all-tests.js
+
+# Run specific test suite
+node test_cases/branch-management/run-all-tests.js --suite=session-closure
+
+# Run with verbose output
+node test_cases/branch-management/run-all-tests.js --verbose
+
+# Run suites in parallel (experimental)
+node test_cases/branch-management/run-all-tests.js --parallel
+```
+
+### 9.2 Individual Test Suites
+
+```bash
+# Session closure tests
+node test_cases/branch-management/session-closure.test.js
+
+# Weekly consolidation tests
+node test_cases/branch-management/weekly-consolidation.test.js
+
+# Orphan cleanup tests
+node test_cases/branch-management/orphan-cleanup.test.js
+```
+
+## 10. Test Maintenance
+
+### 10.1 Adding New Tests
+When adding new functionality:
+
+1. **Create test cases** in the appropriate test suite
+2. **Add mock data** generation if needed
+3. **Update assertions** for new validation requirements
+4. **Document test scenarios** in this strategy document
+
+### 10.2 Test Data Evolution
+As the system evolves:
+
+- **Update mock session structures** to match new session data formats
+- **Extend configuration options** in test settings
+- **Add new assertion methods** for new validation needs
+- **Maintain backward compatibility** in test data formats
+
+## 11. Benefits of This Testing Strategy
+
+### 11.1 Comprehensive Coverage
+- **All major workflows** are tested end-to-end
+- **Edge cases and error conditions** are thoroughly covered
+- **Configuration variations** are tested systematically
+- **Performance characteristics** are validated
+
+### 11.2 Reliable and Repeatable
+- **Isolated test environments** prevent interference
+- **Deterministic test data** ensures consistent results
+- **Comprehensive cleanup** prevents test pollution
+- **Parallel execution** reduces testing time
+
+### 11.3 Developer Friendly
+- **Clear test organization** makes it easy to find relevant tests
+- **Detailed error reporting** helps with debugging
+- **Fast feedback loops** enable rapid development
+- **Easy test addition** supports continuous improvement
+
+## 12. Future Enhancements
+
+### 12.1 Advanced Scenarios
+- **Multi-repository testing** for distributed teams
+- **Network partition simulation** for remote operation testing
+- **Large-scale performance testing** with thousands of branches
+- **Real-time collaboration testing** with multiple concurrent agents
+
+### 12.2 Enhanced Tooling
+- **Visual test reporting** with branch diagrams
+- **Interactive test debugging** with step-through capabilities
+- **Automated test generation** from user scenarios
+- **Performance regression detection** with historical baselines
+
+This comprehensive testing strategy ensures the branch management system is robust, reliable, and ready for production use across diverse development environments and workflows.

package/docs/branch-management.md

@@ -0,0 +1,101 @@
+# DevOps Agent: Branch Management System
+
+**Author:** Manus AI  
+**Date:** October 10, 2025
+
+This document provides comprehensive documentation for the enhanced branch management system in the DevOps Agent. It covers the architecture, configuration, and usage of the new features.
+
+## 1. Introduction
+
+The branch management system is designed to automate the lifecycle of branches, from individual work sessions to weekly consolidations. It prevents the proliferation of branches, ensures a clean and organized repository, and provides a clear history of all work done.
+
+## 2. Branching Architecture
+
+The system uses a hierarchical branching model:
+
+- **Session Branches:** `session/<agent-name>/<task-id>`
+  - Created for each work session.
+  - Short-lived and merged upon session closure.
+- **Daily Branches:** `daily/<YYYY-MM-DD>`
+  - Consolidate work from multiple sessions for a single day.
+  - Act as the default merge target if no other is specified.
+- **Weekly Branches:** `weekly/<YYYY-MM-DD_to_YYYY-MM-DD>`
+  - Consolidate daily branches from the past week.
+  - Provide a stable weekly snapshot of work.
+- **Target Branch:** (e.g., `main`, `develop`)
+  - The primary line of development, configured by the user.
+
+## 3. Configuration
+
+All branch management settings are stored in `local_deploy/project-settings.json`. You can manage these settings using the `branch-config-manager.js` script.
+
+### 3.1 Configuration Options
+
+| Setting                               | Description                                                                 |
+| ------------------------------------- | --------------------------------------------------------------------------- |
+| `defaultMergeTarget`                  | The primary branch for merges (e.g., `main`).                               |
+| `enableDualMerge`                     | If `true`, merges to both the daily and target branches.                    |
+| `enableWeeklyConsolidation`           | If `true`, enables automated weekly rollup of daily branches.               |
+| `orphanSessionThresholdDays`          | The number of days of inactivity before a session is considered orphaned.   |
+| `mergeStrategy`                       | The order for dual merges (`hierarchical-first`, `target-first`, `parallel`). |
+| `autoCleanupOrphans`                  | If `true`, automatically cleans up orphaned sessions without prompting.     |
+| `weeklyCleanupDay`                    | The day of the week to run the weekly consolidation (`sunday`, `monday`, etc.). |
+| `retainWeeklyBranches`                | The number of weekly branches to keep before cleaning up old ones.          |
+
+### 3.2 Managing Configuration
+
+You can use the `branch-config-manager.js` script to manage these settings:
+
+```bash
+# Display current settings
+node src/branch-config-manager.js show
+
+# Run the interactive configuration wizard
+node src/branch-config-manager.js wizard
+
+# Get a specific setting
+node src/branch-config-manager.js get branchManagement.defaultMergeTarget
+
+# Set a specific setting
+node src/branch-config-manager.js set branchManagement.enableDualMerge true
+```
+
+## 4. Workflows
+
+### 4.1 Closing a Session
+
+When you close a session using `enhanced-close-session.js`, you will be prompted for an action:
+
+- **Merge changes and cleanup:** Merges the session branch and cleans up all related files.
+- **Keep session active, just cleanup worktree:** Removes the worktree but keeps the session branch and lock file.
+- **Delete session and all changes:** Permanently deletes the session branch and all work.
+
+If you choose to merge, the system will perform a single or dual merge based on your configuration.
+
+### 4.2 Weekly Consolidation
+
+This process runs automatically on the configured `weeklyCleanupDay`. It identifies all daily branches from the past week, merges them into a new weekly branch, and then deletes the daily branches.
+
+You can also run this process manually:
+
+```bash
+node src/weekly-consolidator.js consolidate
+```
+
+### 4.3 Orphaned Session Cleanup
+
+This process runs daily and identifies sessions that have been inactive for longer than the `orphanSessionThresholdDays`. It will then prompt you to clean them up.
+
+You can also run this process manually:
+
+```bash
+node src/orphan-cleaner.js cleanup
+```
+
+## 5. Command-Line Interface (CLI)
+
+- **`enhanced-close-session.js`**: Close and manage active sessions.
+- **`weekly-consolidator.js`**: Consolidate daily branches into weekly branches.
+- **`orphan-cleaner.js`**: Detect and clean up orphaned sessions.
+- **`branch-config-manager.js`**: Manage all branch management settings.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s9n-devops-agent",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "CS_DevOpsAgent - Intelligent Git Automation System with multi-agent support and session management",
   "type": "module",
   "main": "src/cs-devops-agent-worker.js",