s9n-devops-agent 2.0.18-dev.0 → 2.0.18-dev.2

package/README.md

@@ -1,201 +1,151 @@
 # DevOps Agent - AI-Powered Git Workflow Automation
 
-> Let AI assistants work safely on your codebase with automatic commits, branch management, and multi-agent conflict prevention.
+> **Now with Kora 🤖 - Your Smart DevOps Assistant**
+
+DevOps Agent acts as a bridge between human developers and AI coding assistants. It manages git operations, prevents multi-agent conflicts, ensures architectural compliance, and now talks to you to streamline your workflow.
 
 [![npm version](https://badge.fury.io/js/s9n-devops-agent.svg)](https://www.npmjs.com/package/s9n-devops-agent)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What It Does
-
-🤖 **Works with Any AI Assistant** - Claude, Cursor, GitHub Copilot, Cline  
-🔄 **Automatic Git Operations** - Watches changes, commits with proper messages, pushes automatically  
-🛡️ **Multi-Agent Coordination** - Prevents multiple AIs from editing the same files simultaneously  
-🌲 **Smart Branch Management** - Hierarchical structure: session → daily → weekly → main  
-📋 **House Rules System** - Teaches AI agents your project conventions and testing requirements
-
-## Quick Start (2 Minutes)
-
-```bash
-# Install
-npm install -g s9n-devops-agent
-
-# Learn (recommended for first-time users)
-s9n-devops-agent tutorial
-
-# Setup
-s9n-devops-agent setup
-
-# Start working
-s9n-devops-agent start
-```
+---
 
-## How It Works
+## 🚀 New in v2.0: Smart Features
 
-**The Concept:** Give each AI assistant its own private workspace (called a "session")
+### 🤖 Meet Kora
+Kora is a conversational AI assistant built into the DevOps Agent. She knows your project's **House Rules**, understands your **Architecture Contracts**, and can manage your development sessions.
 
-1. **You start a session** → Creates isolated workspace (git worktree)
-2. **AI assistant works there** → Following house rules you define
-3. **DevOps Agent watches** → Auto-commits and pushes changes
-4. **Session closes** → Merges to daily branch, then to main
+- **Ask Questions:** "What are the rules for API endpoints?"
+- **Start Work:** "Start a new session to fix the login bug."
+- **Check Status:** "Are there any open sessions?"
 
-### What's a Session?
+### 📜 Contract Automation
+Ensure your code matches your architecture. The agent now includes tools to:
+- **Validate Compliance:** Checks if your code implements the defined contracts (API, DB, Features).
+- **Auto-Generate Contracts:** Reverse-engineer documentation from existing code.
+- **Test:** Run `npm run test:contracts` to verify compliance in CI/CD.
 
-Think of it like giving each AI assistant their own office:
-- **Separate directory** with full git history
-- **Own branch** auto-named based on task
-- **File locks** prevent conflicts with other agents
-- **Auto-monitoring** commits and pushes automatically
+### 🧠 AI-Powered Commits
+The agent analyzes your staged changes and generates semantic, conventional commit messages that adhere to your specific House Rules.
 
-## Core Features
+---
 
-### 🔄 Auto-Commit System
-**What:** Watches your workspace and commits changes automatically  
-**Why:** AI can't run git commands, so we do it for them  
-**How:** AI writes commit message to special file, agent reads and commits
+## 📦 Installation
 
-### 🛡️ File Coordination
-**What:** Prevents multiple AI agents from editing same files  
-**Why:** Avoids merge conflicts when working with multiple agents  
-**How:** Agents "declare" files before editing, system checks for conflicts
+### Stable Version
+```bash
+npm install -g s9n-devops-agent
+```
 
-### 🌲 Branch Hierarchy
-**What:** Organized structure: session/* → daily/* → weekly/* → main  
-**Why:** Easy rollbacks, clear progress tracking, organized history  
-**How:** Auto-merges happen at session close and nightly rollover
+### Development Version (Latest Features)
+To access Kora and the latest smart features:
+```bash
+npm install -g s9n-devops-agent@dev
+```
 
-### 📋 House Rules
-**What:** Instructions for AI assistants in `docs/houserules.md`  
-**Why:** Consistent behavior across agents, follows your conventions  
-**How:** Markdown file that AI reads first, auto-updated by agent
+---
 
-## Commands
+## ⚡ Quick Start
 
+### 1. Setup
+Run the setup wizard to configure your environment and API keys.
 ```bash
-# New User Commands
-s9n-devops-agent tutorial          # Interactive learning (start here!)
-s9n-devops-agent setup              # First-time configuration
-s9n-devops-agent help-topics        # Browse comprehensive help
-
-# Session Management
-s9n-devops-agent start              # Create/resume session
-s9n-devops-agent list               # Show all sessions
-s9n-devops-agent close              # Close active session
-
-# Advanced
-s9n-devops-agent create --task api --agent claude  # Create specific session
-s9n-devops-agent cleanup                           # Clean up stale sessions
+s9n-devops-agent setup
 ```
+> **Note:** You will be prompted for a `GROQ_API_KEY` to enable Kora and AI features.
 
-## Common Workflows
-
-### Single AI Agent
+### 2. Talk to Kora
+Start the conversational interface to manage your work.
 ```bash
-s9n-devops-agent start        # Create session
-# Copy instructions to Claude/Cursor
-# AI works, agent commits automatically
-s9n-devops-agent close        # Merge and cleanup
+s9n-devops-agent chat
 ```
 
-### Multiple AI Agents (Parallel Work)
+### 3. Start a Session (Classic Mode)
+If you prefer the CLI menu:
 ```bash
-# Terminal 1: Claude on backend
-s9n-devops-agent create --task api --agent claude
+s9n-devops-agent start
+```
 
-# Terminal 2: Cursor on frontend  
-s9n-devops-agent create --task ui --agent cursor
+---
 
-# They work independently, no conflicts!
-```
+## 🛠️ Core Features
 
-## What Makes It Special?
+### 🔄 Auto-Commit System
+- **Watches** your workspace in real-time.
+- **Commits** changes automatically when your AI assistant saves files.
+- **Pushes** to the remote repository.
 
-✅ **Zero Manual Git Commands** - AI can't run git, we handle it all  
-✅ **Conflict-Free Multi-Agent** - File coordination prevents chaos  
-✅ **Production-Ready** - Used in real projects with multiple developers  
-✅ **Framework Agnostic** - Works with any codebase, any language  
-✅ **Git Platform Agnostic** - GitHub, GitLab, Bitbucket, self-hosted
+### 🛡️ Multi-Agent Coordination
+- **File Locking:** Prevents multiple agents (or humans) from editing the same files simultaneously.
+- **Worktrees:** Each session gets an isolated git worktree, keeping your main branch clean.
 
-## Requirements
+### 🌲 Smart Branch Management
+- **Hierarchy:** `session/task` → `daily/date` → `main`.
+- **Auto-Merge:** Sessions automatically merge into daily branches, which roll over to main.
 
-- Node.js 16.0.0 or higher
-- Git repository
-- Any AI assistant (Claude, Cursor, Copilot, Cline, etc.)
+### 📋 House Rules System
+- **Context Injection:** AI agents read `docs/houserules.md` to understand your coding conventions.
+- **Enforcement:** The agent checks commits against these rules.
 
-## Documentation
+---
 
-📖 **Getting Started**
-- [Interactive Tutorial](docs/V2_IMPLEMENTATION_GUIDE.md) - Learn by doing
-- [Installation Guide](docs/INSTALLATION_GUIDE.md) - Detailed setup
+## 📖 Usage Guide
 
-📚 **Feature Guides**
-- [Version Strategies](docs/version-strategies.md) - Daily version incrementing
-- [File Coordination](docs/file-coordination-guide.md) - Multi-agent prevention
-- [Multi-Agent Setup](docs/multi-agent-guide.md) - Working with multiple AIs
-- [House Rules](docs/houserules-guide.md) - Teaching AI your conventions
+### Using Kora (Chat)
+```bash
+$ s9n-devops-agent chat
 
-🔧 **Advanced Topics**
-- [Branch Management](docs/branch-management.md) - Hierarchical structure
-- [Docker Integration](docs/V2_IMPLEMENTATION_GUIDE.md) - Auto-restart containers
-- [Session Management](docs/SESSION_MANAGEMENT.md) - Advanced workflows
+🤖 Kora - Smart DevOps Assistant
+Powered by Groq (llama-3.3-70b-versatile)
+============================================================
 
-## Troubleshooting
+Kora > Hi! I'm Kora. How can I help you today?
 
-**Session not found?**
-```bash
-s9n-devops-agent list --all    # Check closed sessions
-```
+You > Start a session for user auth
 
-**Agent not detecting changes?**
-```bash
-# Check commit message file exists and has content
-ls -la .devops-commit-*.msg
-# Enable debug mode
-AC_DEBUG=true s9n-devops-agent start
+Kora > Starting new session for: user-auth...
 ```
 
-**Need help?**
+### Managing Sessions
 ```bash
-s9n-devops-agent help-topics   # Browse all help topics
-s9n-devops-agent tutorial      # Re-run tutorial
-```
+# List all active sessions
+s9n-devops-agent list
 
-## Configuration
-
-Configure via environment variables or project settings:
+# Close the current session (merge and cleanup)
+s9n-devops-agent close
+```
 
+### Contract Testing
+Run these tests to ensure your code complies with `House_Rules_Contracts/`:
 ```bash
-# Branch naming
-export AC_BRANCH_PREFIX="dev_initials_"
-
-# Auto-push (default: true)
-export AC_PUSH=true
+npm run test:contracts
+```
 
-# Debug logging
-export AC_DEBUG=true
+---
 
-# Timezone for daily rollover
-export AC_TZ="America/New_York"
-```
+## ⚙️ Configuration
 
-See [Configuration Guide](docs/INSTALLATION_GUIDE.md#configuration-files) for details.
+The setup wizard (`s9n-devops-agent setup`) creates a `.env` file in your project root.
 
-## Contributing
+| Variable | Description |
+|----------|-------------|
+| `GROQ_API_KEY` | **Required** for Kora and AI commits. Get one at [console.groq.com](https://console.groq.com). |
+| `AC_BRANCH_PREFIX` | Prefix for branch names (e.g., `dev_abc_`). |
+| `AC_PUSH` | `true` to auto-push commits, `false` for local only. |
+| `AC_DEBUG` | `true` for verbose logging. |
 
-Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+---
 
-## License
+## 📚 Documentation
+- [Installation Guide](docs/INSTALLATION_GUIDE.md)
+- [Testing Guide](TESTING_GUIDE.md)
+- [House Rules Guide](docs/houserules-guide.md)
+- [Contract Automation](scripts/contract-automation/README.md)
 
-MIT License - see [LICENSE](LICENSE) file for details.
+---
 
 ## Support
-
 - 🐛 [Report Issues](https://github.com/SecondBrainAICo/CS_DevOpsAgent/issues)
-- 💬 [Discussions](https://github.com/SecondBrainAICo/CS_DevOpsAgent/discussions)
 - 📦 [npm Package](https://www.npmjs.com/package/s9n-devops-agent)
-- 📖 [Documentation](https://github.com/SecondBrainAICo/CS_DevOpsAgent/wiki)
 
 ---
-
 **Built with ❤️ by [SecondBrain Labs](https://secondbrain.ai)**
-
-*Making AI-powered development safe, efficient, and conflict-free.*

package/package.json

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

package/src/setup-cs-devops-agent.js

@@ -150,19 +150,51 @@ This structure is compatible with the DevOps Agent's automation tools.
 }
 
 function checkContractsExist(projectRoot) {
-  const contractsDir = path.join(projectRoot, 'House_Rules_Contracts');
-  if (!fs.existsSync(contractsDir)) return false;
-  
-  const requiredContracts = [
-    'FEATURES_CONTRACT.md',
-    'API_CONTRACT.md',
-    'DATABASE_SCHEMA_CONTRACT.md',
-    'SQL_CONTRACT.json',
-    'THIRD_PARTY_INTEGRATIONS.md',
-    'INFRA_CONTRACT.md'
-  ];
-  
-  return requiredContracts.every(file => fs.existsSync(path.join(contractsDir, file)));
+  // Search recursively for contract folders
+  try {
+    // Find all directories named 'House_Rules_Contracts' or 'contracts'
+    // Ignoring node_modules and .git
+    const findCommand = `find "${projectRoot}" -type d \\( -name "House_Rules_Contracts" -o -name "contracts" \\) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/local_deploy/*"`;
+    
+    const output = execSync(findCommand, { encoding: 'utf8' }).trim();
+    const locations = output.split('\n').filter(Boolean);
+
+    let contractsDir = null;
+    if (locations.length > 0) {
+      // Prefer House_Rules_Contracts if available
+      contractsDir = locations.find(l => l.endsWith('House_Rules_Contracts')) || locations[0];
+      log.info(`Found contracts directory at: ${contractsDir}`);
+    }
+
+    if (!contractsDir) return false;
+    
+    const requiredContracts = [
+      'FEATURES_CONTRACT.md',
+      'API_CONTRACT.md',
+      'DATABASE_SCHEMA_CONTRACT.md',
+      'SQL_CONTRACT.json',
+      'THIRD_PARTY_INTEGRATIONS.md',
+      'INFRA_CONTRACT.md'
+    ];
+    
+    // Check if we have multiple similar contracts that might need merging
+    const files = fs.readdirSync(contractsDir);
+    const potentialDuplicates = files.filter(f => 
+      (f.includes('FEATURE') && f !== 'FEATURES_CONTRACT.md') ||
+      (f.includes('API') && f !== 'API_CONTRACT.md')
+    );
+
+    if (potentialDuplicates.length > 0) {
+      log.info(`Found potential split contract files in ${contractsDir}:`);
+      potentialDuplicates.forEach(f => console.log(` - ${f}`));
+      console.log('You may want to merge these into single contract files per type.');
+    }
+    
+    return requiredContracts.every(file => fs.existsSync(path.join(contractsDir, file)));
+  } catch (error) {
+    log.warn(`Error searching for contracts: ${error.message}`);
+    return false;
+  }
 }
 
 async function generateContracts(projectRoot) {
@@ -951,12 +983,10 @@ ${colors.dim}This takes about 2 minutes.${colors.reset}
   log.info(`Project root: ${projectRoot}`);
   
   // Ensure ScriptCS_DevOpsAgent directory exists
-  const scriptsDir = path.join(projectRoot, 'ScriptCS_DevOpsAgent');
-  if (!fs.existsSync(scriptsDir)) {
-    log.error('ScriptCS_DevOpsAgent folder not found! Please copy the folder to your project root.');
-    log.info('Run: cp -r ScriptCS_DevOpsAgent /path/to/your/project/');
-    process.exit(1);
-  }
+  // const scriptsDir = path.join(projectRoot, 'ScriptCS_DevOpsAgent');
+  // if (!fs.existsSync(scriptsDir)) {
+  //   log.warn('ScriptCS_DevOpsAgent folder not found. Assuming global install or custom setup.');
+  // }
   
   // Get developer initials
   console.log();