@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/droid/commands/webapp-testing.md

@@ -1,275 +0,0 @@
----
-description: Test local web applications using Playwright - verify functionality, debug UI, capture screenshots
-argument-hint: <webapp-url-or-local-server>
----
-
-Test local web applications using native Python Playwright scripts with bundled helper utilities.
-
-## Available Operations
-
-- `static` - Test static HTML files
-- `dynamic` - Test dynamic web applications  
-- `debug` - Debug UI behavior and capture logs
-- `screenshot` - Capture browser screenshots
-- `server` - Manage server lifecycle for testing
-
-## Decision Tree
-
-```
-Task → Is it static HTML?
-    ├─ Yes → Read HTML file directly to identify selectors
-    │         ├─ Success → Write Playwright script using selectors
-    │         └─ Fails/Incomplete → Treat as dynamic (below)
-    │
-    └─ No (dynamic webapp) → Is the server already running?
-        ├─ No → Run: python scripts/with_server.py --help
-        │        Then use the helper + write simplified Playwright script
-        │
-        └─ Yes → Reconnaissance-then-action:
-            1. Navigate and wait for networkidle
-            2. Take screenshot or inspect DOM
-            3. Identify selectors from rendered state
-            4. Execute actions with discovered selectors
-```
-
-## Basic Playwright Setup
-
-```python
-from playwright.sync_api import sync_playwright
-
-with sync_playwright() as p:
-    browser = p.chromium.launch(headless=True)  # Always chromium in headless
-    page = browser.new_page()
-    page.goto('http://localhost:5173')  # Your local server
-    page.wait_for_load_state('networkidle')  # CRITICAL: Wait for JS execution
-    
-    # Your automation logic here
-    
-    browser.close()
-```
-
-## Server Management with with_server.py
-
-**Single server:**
-```bash
-python scripts/with_server.py \
-  --server "npm run dev" \
-  --port 5173 \
-  -- python your_automation.py
-```
-
-**Multiple servers (backend + frontend):**
-```bash
-python scripts/with_server.py \
-  --server "cd backend && python server.py" --port 3000 \
-  --server "cd frontend && npm run dev" --port 5173 \
-  -- python your_automation.py
-```
-
-**Always run `--help` first:**
-```bash
-python scripts/with_server.py --help
-```
-
-## Reconnaissance-Then-Action Pattern
-
-### 1. Inspect Rendered DOM
-```python
-# Take full page screenshot
-page.screenshot(path='/tmp/inspect.png', full_page=True)
-
-# Get page content
-content = page.content()
-
-# Discover all buttons, links, inputs
-page.locator('button').all()
-page.locator('a').all() 
-page.locator('input').all()
-```
-
-### 2. Identify Selectors
-Common selector strategies:
-- **Text-based**: `page.locator('text=Login')`
-- **Role-based**: `page.locator('role=button')`
-- **CSS selectors**: `page.locator('.button-primary')`
-- **IDs**: `page.locator('#submit-form')`
-
-### 3. Execute Actions
-```python
-# Click elements
-page.click('button:has-text("Submit")')
-
-# Fill forms
-page.fill('input[name="email"]', 'user@example.com')
-page.fill('input[type="password"]', 'password123')
-
-# Select from dropdown
-page.select_option('select[name="country"]', 'US')
-
-# Wait for elements
-page.wait_for_selector('.loading-spinner', state='hidden')
-```
-
-## Common Patterns
-
-### Form Interaction
-```python
-# Complete multi-step form
-page.goto('http://localhost:3000/form')
-page.wait_for_load_state('networkidle')
-
-# Fill form fields
-page.fill('input[name="firstName"]', 'John')
-page.fill('input[name="lastName"]', 'Doe')
-page.fill('input[name="email"]', 'john.doe@example.com')
-
-# Select dropdown
-page.select_option('select[name="country"]', 'United States')
-
-# Submit form
-page.click('button[type="submit"]')
-
-# Verify success
-page.wait_for_selector('.success-message')
-assert page.locator('.success-message').text_content() == 'Form submitted successfully!'
-```
-
-### Navigation Testing
-```python
-# Test navigation between pages
-page.click('a[href="/dashboard"]')
-page.wait_for_load_state('networkidle')
-
-# Verify URL changed
-assert page.url == 'http://localhost:3000/dashboard'
-
-# Check page content
-assert page.locator('h1:has-text("Dashboard")').is_visible()
-```
-
-### Data Loading and Waiting
-```python
-# Wait for data to load
-page.wait_for_selector('.data-table')
-page.wait_for_load_state('networkidle')
-
-# Check table content
-table = page.locator('.data-table')
-rows = table.locator('tbody tr')
-
-# Verify data loaded
-assert rows.count() > 0
-
-# Check specific data
-assert page.locator('text=John Doe').is_visible()
-```
-
-### Error Handling
-```python
-# Test error states
-page.goto('http://localhost:3000/invalid-page')
-page.wait_for_load_state('networkidle')
-
-# Check for error message
-error_message = page.locator('.error-message')
-assert error_message.is_visible()
-assert '404' in error_message.text_content()
-```
-
-## Debugging and Logging
-
-### Console Logs
-```python
-from playwright.sync_api import sync_playwright
-
-with sync_playwright() as p:
-    browser = p.chromium.launch(headless=False)  # Non-headless for debugging
-    page = browser.new_page()
-    
-    # Capture console messages
-    page.on('console', lambda msg: print(f'Browser console: {msg.text}'))
-    
-    # Capture JavaScript errors
-    page.on('pageerror', lambda error: print(f'Page error: {error}'))
-    
-    page.goto('http://localhost:5173')
-    browser.close()
-```
-
-### Screenshot Capture
-```python
-# Capture on failure
-try:
-    page.click('button')
-except Exception as e:
-    page.screenshot(path='/tmp/failure.png', full_page=True)
-    raise e
-
-# Full page screenshot
-page.screenshot(path='/tmp/full-page.png', full_page=True)
-
-# Element screenshot
-element = page.locator('.widget')
-element.screenshot(path='/tmp/widget.png')
-```
-
-## Best Practices
-
-### Critical Rules
-- **Always** wait for `networkidle` on dynamic apps before DOM inspection
-- Use `sync_playwright()` for synchronous scripts
-- Always close the browser when done
-- Use descriptive selectors (text, role, CSS, or IDs)
-- Add appropriate waits: `wait_for_selector()` or `wait_for_timeout()`
-
-### Performance Tips
-- Use headless mode for CI/automation: `headless=True`
-- Close unused pages to free memory
-- Use specific selectors over generic ones
-- Avoid unnecessary waits
-
-### Selector Strategy
-```python
-# Prefer these (most reliable):
-page.locator('text=Submit')           # Text content
-page.locator('role=button')           # ARIA role
-page.locator('#submit-form')          # ID
-page.locator('.button-primary')       # CSS class
-
-# Avoid these (less reliable):
-page.locator('button:nth-child(2)')   # Position-based
-page.locator('a[href*="login"]')      # Partial attribute match
-```
-
-## Reference Examples
-
-**Element Discovery:**
-```python
-# Find all interactive elements
-buttons = page.locator('button').all()
-for button in buttons:
-    print(f"Button: {button.text_content()}")
-```
-
-**Static HTML Testing:**
-```python
-# For local HTML files
-page.goto('file:///path/to/local/file.html')
-page.wait_for_load_state('networkidle')
-```
-
-## Usage Examples
-
-**Test React app:**
-`/webapp-testing "http://localhost:3000"`
-
-**Test with server management:**
-`/webapp-testing "npm run dev --port 3000"`
-
-**Debug UI issues:**
-`/webapp-testing "http://localhost:5173 --debug"`
-
-**Capture screenshots:**
-`/webapp-testing "http://localhost:3000 --screenshot"`
-
-Remember: Use bundled scripts as black boxes for complex workflows - they handle common patterns reliably.

package/packages/droid/commands/xlsx/recalc.py

@@ -1,178 +0,0 @@
-#!/usr/bin/env python3
-"""
-Excel Formula Recalculation Script
-Recalculates all formulas in an Excel file using LibreOffice
-"""
-
-import json
-import sys
-import subprocess
-import os
-import platform
-from pathlib import Path
-from openpyxl import load_workbook
-
-
-def setup_libreoffice_macro():
-    """Setup LibreOffice macro for recalculation if not already configured"""
-    if platform.system() == 'Darwin':
-        macro_dir = os.path.expanduser('~/Library/Application Support/LibreOffice/4/user/basic/Standard')
-    else:
-        macro_dir = os.path.expanduser('~/.config/libreoffice/4/user/basic/Standard')
-    
-    macro_file = os.path.join(macro_dir, 'Module1.xba')
-    
-    if os.path.exists(macro_file):
-        with open(macro_file, 'r') as f:
-            if 'RecalculateAndSave' in f.read():
-                return True
-    
-    if not os.path.exists(macro_dir):
-        subprocess.run(['soffice', '--headless', '--terminate_after_init'], 
-                      capture_output=True, timeout=10)
-        os.makedirs(macro_dir, exist_ok=True)
-    
-    macro_content = '''<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE script:module PUBLIC "-//OpenOffice.org//DTD OfficeDocument 1.0//EN" "module.dtd">
-<script:module xmlns:script="http://openoffice.org/2000/script" script:name="Module1" script:language="StarBasic">
-    Sub RecalculateAndSave()
-      ThisComponent.calculateAll()
-      ThisComponent.store()
-      ThisComponent.close(True)
-    End Sub
-</script:module>'''
-    
-    try:
-        with open(macro_file, 'w') as f:
-            f.write(macro_content)
-        return True
-    except Exception:
-        return False
-
-
-def recalc(filename, timeout=30):
-    """
-    Recalculate formulas in Excel file and report any errors
-    
-    Args:
-        filename: Path to Excel file
-        timeout: Maximum time to wait for recalculation (seconds)
-    
-    Returns:
-        dict with error locations and counts
-    """
-    if not Path(filename).exists():
-        return {'error': f'File {filename} does not exist'}
-    
-    abs_path = str(Path(filename).absolute())
-    
-    if not setup_libreoffice_macro():
-        return {'error': 'Failed to setup LibreOffice macro'}
-    
-    cmd = [
-        'soffice', '--headless', '--norestore',
-        'vnd.sun.star.script:Standard.Module1.RecalculateAndSave?language=Basic&location=application',
-        abs_path
-    ]
-    
-    # Handle timeout command differences between Linux and macOS
-    if platform.system() != 'Windows':
-        timeout_cmd = 'timeout' if platform.system() == 'Linux' else None
-        if platform.system() == 'Darwin':
-            # Check if gtimeout is available on macOS
-            try:
-                subprocess.run(['gtimeout', '--version'], capture_output=True, timeout=1, check=False)
-                timeout_cmd = 'gtimeout'
-            except (FileNotFoundError, subprocess.TimeoutExpired):
-                pass
-        
-        if timeout_cmd:
-            cmd = [timeout_cmd, str(timeout)] + cmd
-    
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    
-    if result.returncode != 0 and result.returncode != 124:  # 124 is timeout exit code
-        error_msg = result.stderr or 'Unknown error during recalculation'
-        if 'Module1' in error_msg or 'RecalculateAndSave' not in error_msg:
-            return {'error': 'LibreOffice macro not configured properly'}
-        else:
-            return {'error': error_msg}
-    
-    # Check for Excel errors in the recalculated file - scan ALL cells
-    try:
-        wb = load_workbook(filename, data_only=True)
-        
-        excel_errors = ['#VALUE!', '#DIV/0!', '#REF!', '#NAME?', '#NULL!', '#NUM!', '#N/A']
-        error_details = {err: [] for err in excel_errors}
-        total_errors = 0
-        
-        for sheet_name in wb.sheetnames:
-            ws = wb[sheet_name]
-            # Check ALL rows and columns - no limits
-            for row in ws.iter_rows():
-                for cell in row:
-                    if cell.value is not None and isinstance(cell.value, str):
-                        for err in excel_errors:
-                            if err in cell.value:
-                                location = f"{sheet_name}!{cell.coordinate}"
-                                error_details[err].append(location)
-                                total_errors += 1
-                                break
-        
-        wb.close()
-        
-        # Build result summary
-        result = {
-            'status': 'success' if total_errors == 0 else 'errors_found',
-            'total_errors': total_errors,
-            'error_summary': {}
-        }
-        
-        # Add non-empty error categories
-        for err_type, locations in error_details.items():
-            if locations:
-                result['error_summary'][err_type] = {
-                    'count': len(locations),
-                    'locations': locations[:20]  # Show up to 20 locations
-                }
-        
-        # Add formula count for context - also check ALL cells
-        wb_formulas = load_workbook(filename, data_only=False)
-        formula_count = 0
-        for sheet_name in wb_formulas.sheetnames:
-            ws = wb_formulas[sheet_name]
-            for row in ws.iter_rows():
-                for cell in row:
-                    if cell.value and isinstance(cell.value, str) and cell.value.startswith('='):
-                        formula_count += 1
-        wb_formulas.close()
-        
-        result['total_formulas'] = formula_count
-        
-        return result
-        
-    except Exception as e:
-        return {'error': str(e)}
-
-
-def main():
-    if len(sys.argv) < 2:
-        print("Usage: python recalc.py <excel_file> [timeout_seconds]")
-        print("\nRecalculates all formulas in an Excel file using LibreOffice")
-        print("\nReturns JSON with error details:")
-        print("  - status: 'success' or 'errors_found'")
-        print("  - total_errors: Total number of Excel errors found")
-        print("  - total_formulas: Number of formulas in the file")
-        print("  - error_summary: Breakdown by error type with locations")
-        print("    - #VALUE!, #DIV/0!, #REF!, #NAME?, #NULL!, #NUM!, #N/A")
-        sys.exit(1)
-    
-    filename = sys.argv[1]
-    timeout = int(sys.argv[2]) if len(sys.argv) > 2 else 30
-    
-    result = recalc(filename, timeout)
-    print(json.dumps(result, indent=2))
-
-
-if __name__ == '__main__':
-    main()

package/packages/droid/commands/xlsx.md

@@ -1,254 +0,0 @@
----
-description: Create, edit, and analyze spreadsheets with formulas, formatting, data analysis, and visualization
-argument-hint: <operation> <spreadsheet-file>
----
-
-**Available Operations:**
-- `create` - Generate new spreadsheet with formulas
-- `read` - Analyze existing data
-- `edit` - Modify while preserving formulas
-- `analyze` - Data analysis and visualization
-- `recalc` - Recalculate all formulas
-
-## Core Requirements
-
-### Zero Formula Errors
-Every Excel file MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
-
-### Always Use Formulas, Not Hardcoded Values
-**❌ WRONG:** Calculate in Python and hardcode results
-```python
-# Bad: Hardcoding calculated values
-total = df['Sales'].sum()
-sheet['B10'] = total  # Hardcodes 5000
-
-# Bad: Computing in Python
-growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']  
-sheet['C5'] = growth  # Hardcodes 0.15
-```
-
-**✅ CORRECT:** Use Excel formulas
-```python
-# Good: Let Excel calculate the sum
-sheet['B10'] = '=SUM(B2:B9)'
-
-# Good: Growth rate as Excel formula
-sheet['C5'] = '=(C4-C2)/C2'
-```
-
-## Library Selection
-
-**pandas:** Best for data analysis, bulk operations, and simple export
-**openpyxl:** Best for complex formatting, formulas, and Excel-specific features
-
-## Reading and Analyzing Data
-
-### Data Analysis with pandas
-```python
-import pandas as pd
-
-# Read Excel
-df = pd.read_excel('file.xlsx')  # Default: first sheet
-all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict
-
-# Analyze
-df.head()      # Preview data
-df.info()      # Column info  
-df.describe()  # Statistics
-df.isnull().sum()  # Missing values
-
-# Write Excel
-df.to_excel('output.xlsx', index=False)
-```
-
-### Advanced Data Operations
-```python
-# Specific columns and data types
-df = pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'], dtype={'id': str})
-
-# Parse dates
-df = pd.read_excel('file.xlsx', parse_dates=['date_column'])
-
-# Handle large files
-df = pd.read_excel('large_file.xlsx', read_only=True)
-```
-
-## Creating New Excel Files
-
-### With openpyxl (Recommended for formulas)
-```python
-from openpyxl import Workbook
-from openpyxl.styles import Font, PatternFill, Alignment
-
-wb = Workbook()
-sheet = wb.active
-
-# Add data
-sheet['A1'] = 'Hello'
-sheet['B1'] = 'World'
-sheet.append(['Row', 'of', 'data'])
-
-# Add formula
-sheet['B2'] = '=SUM(A1:A10)'
-
-# Formatting
-sheet['A1'].font = Font(bold=True, color='FF0000')
-sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
-sheet['A1'].alignment = Alignment(horizontal='center')
-
-# Column width
-sheet.column_dimensions['A'].width = 20
-
-wb.save('output.xlsx')
-```
-
-## Editing Existing Files
-
-### Preserve Formulas and Formatting
-```python
-from openpyxl import load_workbook
-
-# Load existing file
-wb = load_workbook('existing.xlsx')
-sheet = wb.active  # or wb['SheetName']
-
-# Working with multiple sheets
-for sheet_name in wb.sheetnames:
-    sheet = wb[sheet_name]
-    print(f"Sheet: {sheet_name}")
-
-# Modify cells
-sheet['A1'] = 'New Value'
-sheet.insert_rows(2)  # Insert row at position 2
-sheet.delete_cols(3)  # Delete column 3
-
-# Add new sheet
-new_sheet = wb.create_sheet('NewSheet')
-new_sheet['A1'] = 'Data'
-
-wb.save('modified.xlsx')
-```
-
-## Financial Model Standards
-
-### Color Coding (Industry Standard)
-- **Blue text (RGB: 0,0,255)**: Hardcoded inputs
-- **Black text (RGB: 0,0,0)**: All formulas and calculations
-- **Green text (RGB: 0,128,0)**: Links to other worksheets
-- **Red text (RGB: 255,0,0)**: External links to other files
-- **Yellow background (RGB: 255,255,0)**: Key assumptions
-
-### Number Formatting
-- **Years**: Format as text strings ("2024" not "2,024")
-- **Currency**: Use $#,##0 format with units in headers
-- **Zeros**: Use number formatting to display as "-"
-- **Percentages**: Default to 0.0% format
-- **Multiples**: Format as 0.0x for ratios (EV/EBITDA, P/E)
-- **Negative numbers**: Use parentheses (123) not minus -123
-
-### Formula Construction
-```python
-# Place assumptions in separate cells
-sheet['B6'] = 0.05  # Growth rate assumption
-sheet['B5'] = 1000  # Base value
-
-# Use cell references in formulas
-sheet['B7'] = '=B5*(1+$B$6)'  # Calculates with assumption
-
-# Comment hardcoded values
-sheet['B8'] = 5000  # Revenue
-sheet['B8'].comment = 'Source: Company 10-K, FY2024, Page 45'
-```
-
-## Recalculating Formulas
-
-### Using recalc.py Script
-**MANDATORY:** Recalculate formulas after creating/modifying Excel files
-```bash
-python recalc.py output.xlsx
-```
-
-**With timeout:**
-```bash
-python recalc.py output.xlsx 30
-```
-
-### Understanding Output
-```json
-{
-  "status": "success",           // or "errors_found"
-  "total_errors": 0,              // Total error count
-  "total_formulas": 42,           // Number of formulas in file
-  "error_summary": {              // Only if errors found
-    "#REF!": {
-      "count": 2,
-      "locations": ["Sheet1!B5", "Sheet1!C10"]
-    }
-  }
-}
-```
-
-### Common Errors to Fix
-- **#REF!**: Invalid cell references
-- **#DIV/0!**: Division by zero  
-- **#VALUE!**: Wrong data type in formula
-- **#NAME?**: Unrecognized formula name
-
-## Formula Verification Checklist
-
-### Essential Checks
-- [ ] Test 2-3 sample references before building full model
-- [ ] Verify Excel columns match (column 64 = BL, not BK)
-- [ ] Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
-- [ ] Check denominators before division operations
-- [ ] Test formulas with edge cases (zero, negative, large values)
-
-### Formula Testing Strategy
-```python
-# Test on sample data first
-sheet['A1'] = 100
-sheet['A2'] = 50
-sheet['A3'] = '=A1+A2'  # Should equal 150
-
-# Verify formula works before applying broadly
-for row in range(2, 100):
-    sheet[f'C{row}'] = f'=A{row}+B{row}'
-```
-
-## Best Practices
-
-### Library Usage
-**pandas:**
-- Specify data types: `dtype={'id': str}`
-- Read specific columns: `usecols=['A', 'C', 'E']`
-- For large files, use `read_only=True`
-
-**openpyxl:**
-- Use `data_only=True` to read calculated values
-- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values
-- Cell indices are 1-based (row=1, column=1 = cell A1)
-
-### Error Prevention
-- Check for NaN values with `pd.notna()`
-- Verify all cell references exist before using in formulas
-- Use correct cross-sheet reference format (Sheet1!A1)
-- Add comments for complex formulas and assumptions
-
-## Usage Examples
-
-**Create financial model:**
-`/xlsx create financial-model.xlsx`
-
-**Analyze existing data:**
-`/xlsx read sales-data.xlsx`
-
-**Edit while preserving formulas:**
-`/xlsx edit budget-template.xlsx`
-
-**Data analysis and visualization:**
-`/xlsx analyze quarterly-results.xlsx`
-
-**Recalculate formulas:**
-`/xlsx recalc updated-model.xlsx`
-
-Remember: The spreadsheet should be dynamic and recalculable when source data changes.