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

package/README.md

@@ -1,201 +1,152 @@
 # 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.
+- **Base Branch Selection:** Choose any branch (main, develop, etc.) as the starting point for your session worktree.
 
-- 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/bin/cs-devops-agent

@@ -54,21 +54,11 @@ function runShellScript(scriptPath, scriptArgs = []) {
 switch(command) {
   case 'start':
   case 'session':
-    // Start interactive session manager
-    // On Windows, always use Node.js coordinator (bash may not be available)
-    if (process.platform === 'win32') {
-      console.log('Starting DevOps Agent session manager...\n');
-      runScript(join(rootDir, 'src', 'session-coordinator.js'), ['start', ...args.slice(1)]);
-    } else {
-      // Unix/Mac: use bash script
-      const sessionScript = join(rootDir, 'start-devops-session.sh');
-      if (fs.existsSync(sessionScript)) {
-        runShellScript(sessionScript, args.slice(1));
-      } else {
-        console.error('Session script not found. Please ensure the package is properly installed.');
-        process.exit(1);
-      }
-    }
+  case 'chat':
+    // Unified entry point: Run Kora (Smart Assistant)
+    // Kora handles session creation and management conversationally
+    console.log('Starting Kora (Smart DevOps Assistant)...');
+    runScript(join(rootDir, 'src', 'agent-chat.js'), args.slice(1));
     break;
     
   case 'worker':
@@ -101,6 +91,11 @@ switch(command) {
     runScript(join(rootDir, 'src', 'session-coordinator.js'), ['create', ...args.slice(1)]);
     break;
     
+  case 'resume':
+    // Resume existing session
+    runScript(join(rootDir, 'src', 'session-coordinator.js'), ['resume', ...args.slice(1)]);
+    break;
+    
   case 'close':
     // Close session
     runScript(join(rootDir, 'src', 'close-session.js'), args.slice(1));
@@ -118,7 +113,7 @@ switch(command) {
     break;
     
   case 'chat':
-    // Run the chat agent
+    // Run the chat agent (kept for backward compatibility, now same as start)
     runScript(join(rootDir, 'src', 'agent-chat.js'), args.slice(1));
     break;
 
@@ -207,11 +202,12 @@ For more information, visit: https://github.com/SecondBrainAICo/CS_DevOpsAgent
     break;
 
   default:
-    // Default to chat if no command provided, or if unknown command
-    // This replaces the prior UX where help was default
+    // Default to Kora (Smart Assistant) if no command provided
+    // This provides the unified experience
     if (!command || !command.startsWith('-')) {
-      console.log('Starting Kora Smart Assistant...');
-      runScript(join(rootDir, 'src', 'agent-chat.js'), args.slice(1));
+      console.log('Starting Kora (Smart DevOps Assistant)...');
+      // Pass all args to agent-chat
+      runScript(join(rootDir, 'src', 'agent-chat.js'), args);
     } else {
       // Show help for flags like -h, --help, or unknown flags
       console.log(`\nCS_DevOpsAgent - Intelligent Git Automation System`);

package/docs/RELEASE_NOTES.md

@@ -1,3 +1,18 @@
+# Release Notes - s9n-devops-agent v2.0.18-dev.3
+
+## 🚀 Enhancements
+- **Base Branch Selection**: You can now select a base branch (e.g., main, develop) when starting a session, allowing for cleaner feature branching from stable points.
+- **Enhanced Setup Wizard**: 
+  - Finds and merges contract files from subdirectories.
+  - Ensures versioning strategy is configured.
+  - Persists credentials in user home directory to survive package updates.
+
+## 🐛 Fixes
+- **Update Logic**: Fixed update checker to respect dev versions.
+- **Credentials**: Fixed issue where API keys were lost during updates.
+
+---
+
 # Release Notes - s9n-devops-agent v2.0.11-dev.0
 
 ## 🐛 Fixed

package/package.json

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

package/scripts/deploy-local.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+
+# Deploy DevOpsAgent locally to a target directory
+# Usage: ./scripts/deploy-local.sh <target_directory>
+
+TARGET_DIR="$1"
+
+if [ -z "$TARGET_DIR" ]; then
+  echo "Usage: $0 <target_directory>"
+  exit 1
+fi
+
+if [ ! -d "$TARGET_DIR" ]; then
+  echo "Error: Target directory $TARGET_DIR does not exist"
+  exit 1
+fi
+
+SOURCE_DIR="$(pwd)"
+DEST_DIR="$TARGET_DIR/DevOpsAgent"
+
+echo "Deploying DevOpsAgent to $DEST_DIR..."
+
+# Create destination directory
+mkdir -p "$DEST_DIR"
+
+# Copy files
+echo "Copying files..."
+rsync -av --exclude 'node_modules' \
+          --exclude '.git' \
+          --exclude '.DS_Store' \
+          --exclude 'local_deploy' \
+          --exclude 'coverage' \
+          --exclude 'test_cases' \
+          "$SOURCE_DIR/" "$DEST_DIR/"
+
+# Install dependencies in the target
+echo "Installing dependencies in $DEST_DIR..."
+cd "$DEST_DIR"
+npm install --production --silent
+cd "$SOURCE_DIR"
+
+# Create universal runner script
+RUNNER="$TARGET_DIR/devops"
+LOG_FILE="$TARGET_DIR/devops-agent.log"
+
+echo "Creating 'devops' CLI wrapper..."
+
+cat > "$RUNNER" << EOF
+#!/bin/bash
+
+# DevOps Agent CLI Wrapper
+# Supports all standard commands: start, chat, setup, worker, etc.
+
+DIR="\$(cd "\$(dirname "\$0")" && pwd)"
+AGENT_DIR="\$DIR/DevOpsAgent"
+LOG_FILE="\$DIR/devops-agent.log"
+
+# Ensure executable permissions
+chmod +x "\$AGENT_DIR/bin/cs-devops-agent"
+
+# If first arg is 'worker' or 'background', run in background
+if [ "\$1" == "background" ]; then
+  echo "Starting worker in background..."
+  echo "--- Worker Start: \$(date) ---" >> "\$LOG_FILE"
+  export AC_DEBUG="true"
+  node "\$AGENT_DIR/src/cs-devops-agent-worker.js" >> "\$LOG_FILE" 2>&1 &
+  echo "Worker PID: \$!"
+  echo "Logs: \$LOG_FILE"
+  exit 0
+fi
+
+# Otherwise run interactive CLI
+node "\$AGENT_DIR/bin/cs-devops-agent" "\$@"
+EOF
+
+chmod +x "$RUNNER"
+
+# Add to gitignore in target
+GITIGNORE="$TARGET_DIR/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+  if ! grep -q "DevOpsAgent/" "$GITIGNORE"; then
+    echo "" >> "$GITIGNORE"
+    echo "# DevOps Agent" >> "$GITIGNORE"
+    echo "DevOpsAgent/" >> "$GITIGNORE"
+    echo "devops-agent.log" >> "$GITIGNORE"
+    echo "devops" >> "$GITIGNORE"
+    echo "Added DevOpsAgent files to .gitignore"
+  fi
+fi
+
+echo "Deployment complete!"
+echo "Use the './devops' script to interact with the agent:"
+echo ""
+echo "  ./devops setup        # Run first-time setup"
+echo "  ./devops chat         # Chat with Kora"
+echo "  ./devops start        # Start session manager (Interactive)"
+echo "  ./devops background   # Run worker silently"
+echo "  ./devops --help       # See all commands"
+echo ""
+echo "Logs location: '$LOG_FILE'"