codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/whatsapp-cloud-api/scripts/send_test_message.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Send a test message via WhatsApp Cloud API.
+
+Quick way to validate your setup by sending a text message.
+
+Usage:
+    python send_test_message.py --to 5511999999999 --message "Hello from WhatsApp API!"
+    python send_test_message.py --to 5511999999999  # Uses default test message
+"""
+
+import argparse
+import json
+import os
+import sys
+
+try:
+    import httpx
+except ImportError:
+    print("Error: httpx not installed. Run: pip install httpx")
+    sys.exit(1)
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    load_dotenv = None
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+
+def _mask_secret(value: str) -> str:
+    """Return a masked version of a secret for safe logging."""
+    if not value or len(value) < 8:
+        return "***masked***"
+    return f"{value[:6]}...masked"
+
+
+def send_test(to: str, message: str) -> None:
+    """Send a test text message."""
+    token = os.environ.get("WHATSAPP_TOKEN")
+    phone_id = os.environ.get("PHONE_NUMBER_ID")
+
+    if not token or not phone_id:
+        print("Error: WHATSAPP_TOKEN and PHONE_NUMBER_ID must be set.")
+        print("Configure your .env file or set environment variables.")
+        sys.exit(1)
+
+    payload = {
+        "messaging_product": "whatsapp",
+        "to": to,
+        "type": "text",
+        "text": {"body": message},
+    }
+
+    print(f"Sending message to: {to}")
+    print(f"Message: {message}")
+    print()
+
+    try:
+        response = httpx.post(
+            f"{GRAPH_API}/{phone_id}/messages",
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+
+        data = response.json()
+
+        if response.status_code == 200:
+            msg_id = data.get("messages", [{}])[0].get("id", "N/A")
+            print("Message sent successfully!")
+            print(f"  Message ID: {msg_id}")
+            print(f"  Status: 200 OK")
+        else:
+            error = data.get("error", {})
+            print(f"Error sending message:")
+            print(f"  Code: {error.get('code', '?')}")
+            print(f"  Message: {error.get('message', 'Unknown error')}")
+            if error.get("error_data"):
+                print(f"  Details: {error['error_data'].get('details', '')}")
+
+        print()
+        print("Full response:")
+        # Mask token in response output to prevent credential leakage
+        response_str = json.dumps(data, indent=2)
+        if token and token in response_str:
+            response_str = response_str.replace(token, _mask_secret(token))
+        print(response_str)
+
+    except httpx.ConnectError:
+        print("Error: Connection failed. Check your internet connection.")
+        sys.exit(1)
+    except httpx.TimeoutException:
+        print("Error: Request timed out.")
+        sys.exit(1)
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        print(f"Error: {safe_err}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Send a test WhatsApp message")
+    parser.add_argument(
+        "--to",
+        required=True,
+        help="Recipient phone number with country code (e.g., 5511999999999)",
+    )
+    parser.add_argument(
+        "--message",
+        default="Teste de integracao WhatsApp Cloud API - Mensagem enviada com sucesso!",
+        help="Message text to send",
+    )
+    parser.add_argument(
+        "--env-file",
+        default=".env",
+        help="Path to .env file (default: .env)",
+    )
+
+    args = parser.parse_args()
+
+    # Load environment
+    if load_dotenv:
+        for env_path in [args.env_file, os.path.join(os.getcwd(), ".env")]:
+            if os.path.exists(env_path):
+                load_dotenv(env_path)
+                break
+
+    send_test(args.to, args.message)
+
+
+if __name__ == "__main__":
+    main()

package/templates/.agent/skills/whatsapp-cloud-api/scripts/setup_project.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+Setup a new WhatsApp Cloud API project with boilerplate code.
+
+Usage:
+    python setup_project.py --language nodejs --path ./my-whatsapp-project
+    python setup_project.py --language python --path ./my-whatsapp-project
+"""
+
+import argparse
+import os
+import shutil
+import sys
+
+
+def get_skill_dir() -> str:
+    """Get the skill directory (parent of scripts/)."""
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def setup_project(language: str, path: str, name: str | None = None) -> None:
+    """Copy boilerplate and configure a new WhatsApp project."""
+    skill_dir = get_skill_dir()
+    boilerplate_dir = os.path.join(skill_dir, "assets", "boilerplate", language)
+
+    if not os.path.exists(boilerplate_dir):
+        print(f"Error: Boilerplate not found for language '{language}'")
+        print(f"Available: nodejs, python")
+        sys.exit(1)
+
+    target_path = os.path.abspath(path)
+
+    if os.path.exists(target_path) and os.listdir(target_path):
+        print(f"Warning: Directory '{target_path}' already exists and is not empty.")
+        response = input("Continue and overwrite? (y/N): ").strip().lower()
+        if response != "y":
+            print("Aborted.")
+            sys.exit(0)
+
+    # Copy boilerplate
+    print(f"Creating {language} project at: {target_path}")
+    shutil.copytree(boilerplate_dir, target_path, dirs_exist_ok=True)
+
+    # Rename .env.example to .env
+    env_example = os.path.join(target_path, ".env.example")
+    env_file = os.path.join(target_path, ".env")
+    if os.path.exists(env_example) and not os.path.exists(env_file):
+        shutil.copy2(env_example, env_file)
+        print("Created .env from .env.example")
+
+    # Update project name if provided
+    if name and language == "nodejs":
+        package_json = os.path.join(target_path, "package.json")
+        if os.path.exists(package_json):
+            with open(package_json, "r") as f:
+                content = f.read()
+            content = content.replace('"whatsapp-cloud-api"', f'"{name}"')
+            with open(package_json, "w") as f:
+                f.write(content)
+
+    print()
+    print("=" * 50)
+    print("Project created successfully!")
+    print("=" * 50)
+    print()
+    print("Next steps:")
+    print()
+
+    if language == "nodejs":
+        print(f"  1. cd {target_path}")
+        print("  2. npm install")
+        print("  3. Edit .env with your WhatsApp API credentials")
+        print("  4. npm run dev")
+        print()
+        print("For production:")
+        print("  npm run build && npm start")
+    else:
+        print(f"  1. cd {target_path}")
+        print("  2. pip install -r requirements.txt")
+        print("  3. Edit .env with your WhatsApp API credentials")
+        print("  4. python app.py")
+        print()
+        print("For production:")
+        print("  gunicorn -w 4 -b 0.0.0.0:3000 app:app")
+
+    print()
+    print("For local development with webhooks:")
+    print("  ngrok http 3000")
+    print("  Then configure the ngrok URL in Meta Developers > WhatsApp > Configuration")
+    print()
+    print("Need help with setup? Read: references/setup-guide.md")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Setup a new WhatsApp Cloud API project")
+    parser.add_argument(
+        "--language",
+        choices=["nodejs", "python"],
+        required=True,
+        help="Project language (nodejs or python)",
+    )
+    parser.add_argument(
+        "--path",
+        required=True,
+        help="Path where the project will be created",
+    )
+    parser.add_argument(
+        "--name",
+        default=None,
+        help="Project name (optional, used in package.json for nodejs)",
+    )
+
+    args = parser.parse_args()
+    setup_project(args.language, args.path, args.name)
+
+
+if __name__ == "__main__":
+    main()

package/templates/.agent/skills/whatsapp-cloud-api/scripts/validate_config.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Validate WhatsApp Cloud API configuration.
+
+Checks environment variables and tests API connectivity.
+
+Usage:
+    python validate_config.py
+    python validate_config.py --env-file /path/to/.env
+"""
+
+import argparse
+import os
+import sys
+
+try:
+    import httpx
+except ImportError:
+    print("Error: httpx not installed. Run: pip install httpx")
+    sys.exit(1)
+
+try:
+    from dotenv import load_dotenv
+except ImportError:
+    print("Warning: python-dotenv not installed. Using system environment only.")
+    load_dotenv = None
+
+GRAPH_API = "https://graph.facebook.com/v21.0"
+
+REQUIRED_VARS = [
+    ("WHATSAPP_TOKEN", "Access token for WhatsApp Cloud API"),
+    ("PHONE_NUMBER_ID", "Phone Number ID from API Setup"),
+    ("WABA_ID", "WhatsApp Business Account ID"),
+    ("APP_SECRET", "App Secret from App Settings > Basic"),
+    ("VERIFY_TOKEN", "Custom token for webhook verification"),
+]
+
+
+def check_env_vars() -> tuple[bool, list[str]]:
+    """Check if all required environment variables are set."""
+    missing = []
+    for var_name, description in REQUIRED_VARS:
+        value = os.environ.get(var_name)
+        if not value or value.startswith("your_"):
+            missing.append(f"  {var_name} - {description}")
+
+    return len(missing) == 0, missing
+
+
+def _mask_secret(value: str) -> str:
+    """Return a masked version of a secret for safe logging."""
+    if not value or len(value) < 8:
+        return "***masked***"
+    return f"{value[:6]}...masked"
+
+
+def test_api_connection() -> tuple[bool, str]:
+    """Test connection to WhatsApp Cloud API."""
+    token = os.environ.get("WHATSAPP_TOKEN", "")
+    phone_id = os.environ.get("PHONE_NUMBER_ID", "")
+
+    try:
+        response = httpx.get(
+            f"{GRAPH_API}/{phone_id}",
+            params={"fields": "verified_name,code_verification_status,display_phone_number,quality_rating"},
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            return True, (
+                f"Phone: {data.get('display_phone_number', 'N/A')}\n"
+                f"  Name: {data.get('verified_name', 'N/A')}\n"
+                f"  Status: {data.get('code_verification_status', 'N/A')}\n"
+                f"  Quality: {data.get('quality_rating', 'N/A')}"
+            )
+        else:
+            error = response.json().get("error", {})
+            return False, f"API Error {error.get('code', '?')}: {error.get('message', 'Unknown')}"
+
+    except httpx.ConnectError:
+        return False, "Connection failed. Check your internet connection."
+    except httpx.TimeoutException:
+        return False, "Request timed out after 10 seconds."
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        return False, f"Unexpected error: {safe_err}"
+
+
+def test_waba_access() -> tuple[bool, str]:
+    """Test access to WhatsApp Business Account."""
+    token = os.environ.get("WHATSAPP_TOKEN", "")
+    waba_id = os.environ.get("WABA_ID", "")
+
+    try:
+        response = httpx.get(
+            f"{GRAPH_API}/{waba_id}/phone_numbers",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=10.0,
+        )
+
+        if response.status_code == 200:
+            data = response.json()
+            count = len(data.get("data", []))
+            return True, f"WABA accessible. {count} phone number(s) found."
+        else:
+            error = response.json().get("error", {})
+            return False, f"API Error {error.get('code', '?')}: {error.get('message', 'Unknown')}"
+
+    except Exception as e:
+        # Mask token in error output to prevent credential leakage
+        safe_err = str(e).replace(token, _mask_secret(token)) if token else str(e)
+        return False, f"Error: {safe_err}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate WhatsApp Cloud API configuration")
+    parser.add_argument("--env-file", default=".env", help="Path to .env file (default: .env)")
+    args = parser.parse_args()
+
+    # Load environment
+    if load_dotenv and os.path.exists(args.env_file):
+        load_dotenv(args.env_file)
+        print(f"Loaded: {args.env_file}")
+    elif not os.path.exists(args.env_file):
+        print(f"Warning: {args.env_file} not found. Using system environment.")
+
+    print()
+    print("=" * 50)
+    print("WhatsApp Cloud API - Configuration Validator")
+    print("=" * 50)
+    print()
+
+    all_ok = True
+
+    # Check 1: Environment variables
+    print("[1/3] Checking environment variables...")
+    env_ok, missing = check_env_vars()
+    if env_ok:
+        print("  OK - All required variables are set")
+    else:
+        print("  FAIL - Missing variables:")
+        for m in missing:
+            print(f"    {m}")
+        all_ok = False
+
+    print()
+
+    if not env_ok:
+        print("Cannot test API without required variables. Fix the above and retry.")
+        sys.exit(1)
+
+    # Check 2: API connection
+    print("[2/3] Testing API connection (Phone Number)...")
+    api_ok, api_msg = test_api_connection()
+    if api_ok:
+        print(f"  OK - Connected successfully")
+        print(f"  {api_msg}")
+    else:
+        print(f"  FAIL - {api_msg}")
+        all_ok = False
+
+    print()
+
+    # Check 3: WABA access
+    print("[3/3] Testing WABA access...")
+    waba_ok, waba_msg = test_waba_access()
+    if waba_ok:
+        print(f"  OK - {waba_msg}")
+    else:
+        print(f"  FAIL - {waba_msg}")
+        all_ok = False
+
+    print()
+    print("=" * 50)
+    if all_ok:
+        print("All checks passed! Your configuration is valid.")
+        print("You can start sending messages.")
+    else:
+        print("Some checks failed. Please fix the issues above.")
+        print("Need help? Read: references/setup-guide.md")
+    print("=" * 50)
+
+    sys.exit(0 if all_ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/templates/.agent/skills/wiki-architect/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: wiki-architect
+description: "You are a documentation architect that produces structured wiki catalogues and onboarding guides from codebases."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Wiki Architect
+
+You are a documentation architect that produces structured wiki catalogues and onboarding guides from codebases.
+
+## When to Use
+- User asks to "create a wiki", "document this repo", "generate docs"
+- User wants to understand project structure or architecture
+- User asks for a table of contents or documentation plan
+- User asks for an onboarding guide or "zero to hero" path
+
+## Procedure
+
+1. **Scan** the repository file tree and README
+2. **Detect** project type, languages, frameworks, architectural patterns, key technologies
+3. **Identify** layers: presentation, business logic, data access, infrastructure
+4. **Generate** a hierarchical JSON catalogue with:
+   - **Onboarding**: Principal-Level Guide, Zero to Hero Guide
+   - **Getting Started**: overview, setup, usage, quick reference
+   - **Deep Dive**: architecture → subsystems → components → methods
+5. **Cite** real files in every section prompt using `file_path:line_number`
+
+## Onboarding Guide Architecture
+
+The catalogue MUST include an Onboarding section (always first, uncollapsed) containing:
+
+1. **Principal-Level Guide** — For senior/principal ICs. Dense, opinionated. Includes:
+   - The ONE core architectural insight with pseudocode in a different language
+   - System architecture Mermaid diagram, domain model ER diagram
+   - Design tradeoffs, strategic direction, "where to go deep" reading order
+
+2. **Zero-to-Hero Learning Path** — For newcomers. Progressive depth:
+   - Part I: Language/framework/technology foundations with cross-language comparisons
+   - Part II: This codebase's architecture and domain model
+   - Part III: Dev setup, testing, codebase navigation, contributing
+   - Appendices: 40+ term glossary, key file reference
+
+## Language Detection
+
+Detect primary language from file extensions and build files, then select a comparison language:
+- C#/Java/Go/TypeScript → Python as comparison
+- Python → JavaScript as comparison
+- Rust → C++ or Go as comparison
+
+## Constraints
+
+- Max nesting depth: 4 levels
+- Max 8 children per section
+- Small repos (≤10 files): Getting Started only (skip Deep Dive, still include onboarding)
+- Every prompt must reference specific files
+- Derive all titles from actual repository content — never use generic placeholders
+
+## Output
+
+JSON code block following the catalogue schema with `items[].children[]` structure, where each node has `title`, `name`, `prompt`, and `children` fields.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.