agentic-sdlc 1.0.0 → 1.5.0

package/bin/CROSS-PLATFORM-CLI.md

@@ -0,0 +1,526 @@
+# Cross-Platform Knowledge Base CLI
+
+## Overview
+
+The Knowledge Base CLI has been reorganized to support **Windows, Linux, and macOS** with a unified Python-based implementation.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              CROSS-PLATFORM CLI ARCHITECTURE                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                ┌─────────────┴─────────────┐
+                ▼                           ▼
+    ┌───────────────────┐       ┌───────────────────┐
+    │   ENTRY POINTS    │       │   PYTHON CORE     │
+    │                   │       │                   │
+    │  • kb (bash)      │──────►│  kb_cli.py        │
+    │  • kb.bat (win)   │       │                   │
+    └───────────────────┘       └───────────────────┘
+                                          │
+                                          ▼
+                                ┌───────────────────┐
+                                │   LIB MODULES     │
+                                │                   │
+                                │  • kb_common.py   │
+                                │  • kb_search.py   │
+                                │  • kb_add.py      │
+                                │  • kb_index.py    │
+                                │  • kb_stats.py    │
+                                │  • kb_list.py     │
+                                │  • kb_compound.py │
+                                └───────────────────┘
+```
+
+## Directory Structure
+
+```
+bin/
+├── kb                      # Bash entry point (Linux/macOS/Git Bash)
+├── kb.bat                  # Windows batch entry point
+├── kb_cli.py              # Main Python CLI
+├── lib/                    # Python library modules
+│   ├── __init__.py
+│   ├── kb_common.py       # Common utilities
+│   ├── kb_search.py       # Search functionality
+│   ├── kb_add.py          # Add entries
+│   ├── kb_index.py        # Index generation
+│   ├── kb_stats.py        # Statistics
+│   ├── kb_list.py         # List entries
+│   └── kb_compound.py     # Neo4j integration
+├── kb.ps1                  # Legacy PowerShell (kept for compatibility)
+├── kb-*.ps1               # Legacy PowerShell scripts
+└── README.md              # Documentation
+```
+
+## Installation
+
+### Prerequisites
+
+**All Platforms:**
+- Python 3.7 or higher
+- pip (Python package manager)
+
+**Optional (for Neo4j integration):**
+```bash
+pip install neo4j python-dotenv
+```
+
+### Platform-Specific Setup
+
+#### Windows
+
+**Option 1: Using Command Prompt**
+```cmd
+cd path\to\agentic-sdlc
+bin\kb.bat help
+```
+
+**Option 2: Using PowerShell**
+```powershell
+cd path\to\agentic-sdlc
+.\bin\kb.ps1 help
+```
+
+**Option 3: Using Git Bash**
+```bash
+cd /path/to/agentic-sdlc
+./bin/kb help
+```
+
+**Add to PATH (Optional):**
+```cmd
+setx PATH "%PATH%;C:\path\to\agentic-sdlc\bin"
+```
+
+#### Linux
+
+**Make executable:**
+```bash
+chmod +x bin/kb
+```
+
+**Usage:**
+```bash
+cd /path/to/agentic-sdlc
+./bin/kb help
+```
+
+**Add to PATH (Optional):**
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export PATH="$PATH:/path/to/agentic-sdlc/bin"
+```
+
+#### macOS
+
+**Make executable:**
+```bash
+chmod +x bin/kb
+```
+
+**Usage:**
+```bash
+cd /path/to/agentic-sdlc
+./bin/kb help
+```
+
+**Add to PATH (Optional):**
+```bash
+# Add to ~/.zshrc or ~/.bash_profile
+export PATH="$PATH:/path/to/agentic-sdlc/bin"
+```
+
+## Usage
+
+### Basic Commands
+
+All commands work identically across platforms:
+
+```bash
+# Show help
+kb help
+
+# Search knowledge base
+kb search "react hydration"
+
+# Add new entry
+kb add
+
+# Update index
+kb index
+
+# Show statistics
+kb stats
+
+# List entries
+kb list
+kb list bugs
+
+# Show recent entries
+kb recent
+kb recent 5
+```
+
+### Compound Commands (Neo4j Integration)
+
+```bash
+# Compound search (file + Neo4j)
+kb compound search "authentication"
+
+# Compound add (create + sync)
+kb compound add
+
+# Full sync
+kb compound sync
+
+# Intelligent query
+kb compound query "React"
+
+# System health
+kb compound stats
+```
+
+## Platform-Specific Notes
+
+### Windows
+
+**Command Prompt:**
+```cmd
+bin\kb.bat search "term"
+```
+
+**PowerShell:**
+```powershell
+.\bin\kb.ps1 search "term"
+```
+
+**Git Bash:**
+```bash
+./bin/kb search "term"
+```
+
+**Colors:**
+- ANSI colors are automatically enabled on Windows 10+
+- Older Windows versions may not display colors
+
+### Linux
+
+**Bash/Zsh:**
+```bash
+./bin/kb search "term"
+```
+
+**Colors:**
+- Full ANSI color support
+- Works in all modern terminals
+
+### macOS
+
+**Bash/Zsh:**
+```bash
+./bin/kb search "term"
+```
+
+**Colors:**
+- Full ANSI color support
+- Works in Terminal.app and iTerm2
+
+## Architecture
+
+### Entry Points
+
+**1. Bash Script (`kb`)**
+- Detects OS automatically
+- Finds Python interpreter
+- Executes `kb_cli.py`
+- Works on Linux, macOS, Git Bash
+
+**2. Batch Script (`kb.bat`)**
+- Windows-specific entry point
+- Finds Python interpreter
+- Executes `kb_cli.py`
+- Works on CMD and PowerShell
+
+**3. Python CLI (`kb_cli.py`)**
+- Main command-line interface
+- Parses arguments
+- Routes to appropriate modules
+- Cross-platform color support
+
+### Library Modules
+
+**`kb_common.py`**
+- Common utilities
+- Configuration management
+- Color handling
+- YAML frontmatter parsing
+- Platform detection
+
+**`kb_search.py`**
+- Search INDEX.md
+- Search all KB files
+- Display results with context
+
+**`kb_add.py`**
+- Interactive entry creation
+- YAML frontmatter generation
+- Auto-open in editor
+
+**`kb_index.py`**
+- Scan all entries
+- Generate INDEX.md
+- Group by category/priority/date
+
+**`kb_stats.py`**
+- Calculate statistics
+- Display metrics
+- Show growth trends
+
+**`kb_list.py`**
+- List all entries
+- Filter by category
+- Show recent entries
+
+**`kb_compound.py`**
+- Neo4j integration
+- Compound operations
+- Cross-platform subprocess handling
+
+## Features
+
+### ✅ Cross-Platform
+
+- **Windows** - CMD, PowerShell, Git Bash
+- **Linux** - Bash, Zsh, Fish
+- **macOS** - Bash, Zsh
+
+### ✅ Color Support
+
+- ANSI colors on all platforms
+- Automatic Windows 10+ color enabling
+- Graceful fallback for older systems
+
+### ✅ Python-Based
+
+- Single codebase for all platforms
+- Easy to maintain and extend
+- No platform-specific logic in core
+
+### ✅ Neo4j Integration
+
+- Optional Neo4j brain integration
+- Graceful fallback if not available
+- Cross-platform subprocess handling
+
+### ✅ Interactive
+
+- Interactive entry creation
+- Auto-open in default editor
+- Platform-specific editor detection
+
+## Migration from PowerShell
+
+### Old PowerShell Commands
+
+```powershell
+.\bin\kb.ps1 search "term"
+.\bin\kb.ps1 add
+.\bin\kb.ps1 compound search "term"
+```
+
+### New Cross-Platform Commands
+
+**Windows (any shell):**
+```bash
+kb search "term"
+kb add
+kb compound search "term"
+```
+
+**Linux/macOS:**
+```bash
+./bin/kb search "term"
+./bin/kb add
+./bin/kb compound search "term"
+```
+
+### Compatibility
+
+The old PowerShell scripts (`kb.ps1`, `kb-*.ps1`) are kept for backward compatibility but are deprecated. Please migrate to the new cross-platform CLI.
+
+## Troubleshooting
+
+### Python Not Found
+
+**Windows:**
+```cmd
+where python
+where python3
+```
+
+Install from: https://www.python.org/downloads/
+
+**Linux:**
+```bash
+sudo apt install python3 python3-pip  # Debian/Ubuntu
+sudo yum install python3 python3-pip  # RHEL/CentOS
+```
+
+**macOS:**
+```bash
+brew install python3
+```
+
+### Permission Denied (Linux/macOS)
+
+```bash
+chmod +x bin/kb
+```
+
+### Colors Not Working (Windows)
+
+- Requires Windows 10 or later
+- Use Windows Terminal for best experience
+- Git Bash has full color support
+
+### Neo4j Not Available
+
+The CLI works without Neo4j. Compound commands will fall back to file-only mode.
+
+To enable Neo4j:
+1. Install dependencies: `pip install neo4j python-dotenv`
+2. Configure `.env` with Neo4j credentials
+3. Ensure `tools/neo4j/` scripts exist
+
+## Development
+
+### Adding New Commands
+
+1. Create module in `bin/lib/kb_newcommand.py`
+2. Import in `kb_cli.py`
+3. Add command handler in `main()`
+4. Update help text
+
+### Testing
+
+**Test on all platforms:**
+
+```bash
+# Windows
+bin\kb.bat help
+
+# Linux/macOS
+./bin/kb help
+
+# Test all commands
+kb search test
+kb add
+kb index
+kb stats
+kb list
+kb recent
+kb compound stats
+```
+
+## Examples
+
+### Example 1: Search Across Platforms
+
+**Windows CMD:**
+```cmd
+C:\project> bin\kb.bat search "authentication"
+```
+
+**Linux:**
+```bash
+$ ./bin/kb search "authentication"
+```
+
+**macOS:**
+```bash
+$ ./bin/kb search "authentication"
+```
+
+### Example 2: Add Entry
+
+**All platforms:**
+```bash
+kb add
+```
+
+Interactive prompts:
+```
+Title: OAuth 2.0 Implementation
+Category (1-6): 2
+Priority (1-4): 2
+Tags: oauth, authentication, security
+Attempts: 3
+Time saved: 2 hours
+```
+
+### Example 3: Compound Workflow
+
+**All platforms:**
+```bash
+# Search first
+kb compound search "react hooks"
+
+# Add solution
+kb compound add
+
+# Sync to Neo4j
+kb compound sync
+```
+
+## Performance
+
+### Startup Time
+
+- **Python CLI:** ~100-200ms
+- **PowerShell:** ~500-1000ms
+- **Improvement:** 5-10x faster
+
+### Cross-Platform
+
+- Same performance on all platforms
+- No platform-specific overhead
+- Efficient file operations
+
+## Future Enhancements
+
+### Planned
+
+- [ ] Shell completion (bash, zsh, fish)
+- [ ] Config file support (~/.kbrc)
+- [ ] Plugin system
+- [ ] Web UI
+- [ ] REST API
+
+### Experimental
+
+- [ ] Real-time sync
+- [ ] Collaborative editing
+- [ ] AI-powered suggestions
+- [ ] Mobile app
+
+## Summary
+
+The cross-platform CLI provides:
+
+✅ **Unified Experience** - Same commands on all platforms  
+✅ **Python-Based** - Single codebase, easy maintenance  
+✅ **Fast** - 5-10x faster than PowerShell  
+✅ **Color Support** - ANSI colors everywhere  
+✅ **Neo4j Integration** - Optional brain integration  
+✅ **Interactive** - User-friendly prompts  
+✅ **Backward Compatible** - Old scripts still work  
+
+---
+
+**Version:** 2.0.0  
+**Created:** 2026-01-02  
+**Platform:** Windows, Linux, macOS  
+**Language:** Python 3.7+
+
+#cross-platform #cli #python #knowledge-base