issue-core/.capability/integrate.sh

#!/bin/bash
# Integration script for issue-facade capability
# This script helps the main project discover and integrate the capability

set -e

CAPABILITY_NAME="issue-facade"
CAPABILITY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$CAPABILITY_DIR/../.." && pwd)}"

echo "🔧 Issue Facade Capability Integration"
echo "   Capability: $CAPABILITY_DIR"
echo "   Project:    $PROJECT_ROOT"
echo ""

# Function to check if something exists
check_exists() {
    [ -e "$1" ] && echo "✓" || echo "✗"
}

# Show current status
echo "📊 Current Status:"
echo "   Issue command installed: $(check_exists "$(command -v issue)")"
echo "   Backend configured:      $(issue backend list 2>/dev/null | grep -q "default" && echo "✓" || echo "✗")"
echo "   Claude config dir:       $(check_exists "$PROJECT_ROOT/.claude")"
echo ""

# Ask what to do
echo "🎯 Integration Options:"
echo "   1) Install capability (pip install -e)"
echo "   2) Configure backend"
echo "   3) Add to Claude Code context"
echo "   4) Create slash command"
echo "   5) Show integration checklist"
echo "   6) Full setup (all of the above)"
echo "   0) Exit"
echo ""

read -p "Choose option [1-6, 0]: " choice

case $choice in
    1)
        echo ""
        echo "📦 Installing capability..."
        pip install -e "$CAPABILITY_DIR"
        echo "✓ Installed"
        echo ""
        echo "Verify with: issue --version"
        ;;

    2)
        echo ""
        echo "🔑 Configuring backend..."
        echo ""
        echo "You'll need:"
        echo "  - Gitea URL (e.g., https://gitea.example.com)"
        echo "  - Repository owner"
        echo "  - Repository name"
        echo "  - API token (set GITEA_API_TOKEN environment variable)"
        echo ""

        if [ -z "$GITEA_API_TOKEN" ]; then
            echo "⚠️  GITEA_API_TOKEN not set"
            read -p "Enter token (or press Enter to skip): " token
            if [ -n "$token" ]; then
                export GITEA_API_TOKEN="$token"
            fi
        else
            echo "✓ Using GITEA_API_TOKEN from environment"
        fi

        read -p "Backend name (e.g., myproject): " backend_name
        if [ -n "$backend_name" ]; then
            issue backend add "$backend_name" gitea
            echo ""
            read -p "Set as default? [y/N]: " set_default
            if [ "$set_default" = "y" ] || [ "$set_default" = "Y" ]; then
                issue backend set-default "$backend_name"
            fi

            echo ""
            echo "✓ Backend configured"
            echo ""
            echo "Test with: issue list --limit=5"
        fi
        ;;

    3)
        echo ""
        echo "📝 Adding to Claude Code context..."
        mkdir -p "$PROJECT_ROOT/.claude/capabilities"
        cp "$CAPABILITY_DIR/.capability/agent-context.md" \
           "$PROJECT_ROOT/.claude/capabilities/issue-facade.md"

        # Create or update context file
        CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
        mkdir -p "$(dirname "$CONTEXT_FILE")"

        if [ ! -f "$CONTEXT_FILE" ]; then
            cat > "$CONTEXT_FILE" << 'EOF'
# Available Capabilities

This project uses specialized capabilities. Always check for existing capabilities before implementing similar functionality.

## Issue Tracking: issue-facade

**Location:** `capabilities/issue-facade/`
**Documentation:** `.claude/capabilities/issue-facade.md`
**Priority:** CRITICAL (always use for issue operations)

**MUST USE FOR:**
- Creating, reading, updating, searching issues
- Multi-agent coordination via issue tracking
- Querying issue state or assigning issues

**NEVER USE:**
- Direct API calls to Gitea/GitHub/GitLab (`requests.post("/api/v1/repos/...")`)
- Platform CLIs (`gh issue`, `glab issue`)
- Platform libraries (`from github import Github`)

**Quick Start:**
```python
from issue_tracker.backends.gitea import GiteaBackend
backend = GiteaBackend()
backend.connect(config)
issues = backend.list_issues()
```

**Full Documentation:** See `.claude/capabilities/issue-facade.md`
EOF
            echo "✓ Created $CONTEXT_FILE"
        else
            echo "✓ Context file exists: $CONTEXT_FILE"
            echo "   (Review and update manually if needed)"
        fi

        echo ""
        echo "✓ Added to Claude Code context"
        echo ""
        echo "Files created:"
        echo "  - $PROJECT_ROOT/.claude/capabilities/issue-facade.md"
        echo "  - $CONTEXT_FILE"
        ;;

    4)
        echo ""
        echo "⚡ Creating slash command..."
        mkdir -p "$PROJECT_ROOT/.claude/commands"

        cat > "$PROJECT_ROOT/.claude/commands/use-issues.md" << 'EOF'
You are working with issue tracking. Use the **issue-facade capability**:

## Available API

**Python (Recommended):**
```python
from issue_tracker.backends.gitea import GiteaBackend
from issue_tracker.core.models import Issue, Label, IssueState
from issue_tracker.core.interfaces import IssueFilter

backend = GiteaBackend()
backend.connect(config)

# Query issues
issues = backend.list_issues(IssueFilter(state='open', labels=['bug']))

# Create issue
issue = Issue(...)
backend.create_issue(issue)

# Update
issue.state = IssueState.CLOSED
backend.update_issue(issue)
```

**CLI:**
```bash
issue list --state=open --label=bug --format=json
issue create "Title" --label=bug --description="Details"
issue edit 42 --state=in_progress
issue close 42 --comment="Fixed"
```

## Critical Reminders

**DO NOT:**
- ❌ Make direct API calls to Gitea/GitHub/GitLab
- ❌ Use `gh` or `glab` CLI tools
- ❌ Import PyGithub, python-gitlab, or similar libraries
- ❌ Parse HTML or scrape web UIs

**WHY:** Bypassing the capability causes credential sprawl, token waste, and race conditions.

## Full Documentation

See `capabilities/issue-facade/AGENT_INTEGRATION.md` for:
- Complete API reference
- Coordination patterns
- Error handling
- Performance tips
- Working examples

EOF
        echo "✓ Created slash command: /use-issues"
        echo ""
        echo "Usage in Claude Code:"
        echo "  /use-issues"
        echo ""
        echo "This will inject issue-facade context into the conversation."
        ;;

    5)
        echo ""
        cat "$CAPABILITY_DIR/.capability/integration-checklist.md"
        ;;

    6)
        echo ""
        echo "🚀 Full Setup"
        echo "=============="
        echo ""

        # Step 1: Install
        echo "Step 1/4: Installing capability..."
        pip install -e "$CAPABILITY_DIR" || { echo "❌ Installation failed"; exit 1; }
        echo "✓ Installed"
        echo ""

        # Step 2: Configure
        echo "Step 2/4: Configuring backend..."
        echo ""
        if [ -z "$GITEA_API_TOKEN" ]; then
            echo "⚠️  GITEA_API_TOKEN not set"
            echo "   Please set it and run this script again,"
            echo "   or configure manually with: issue backend add <name> gitea"
            echo ""
        else
            read -p "Backend name [myproject]: " backend_name
            backend_name="${backend_name:-myproject}"
            issue backend add "$backend_name" gitea || true
            issue backend set-default "$backend_name" || true
            echo "✓ Backend configured"
            echo ""
        fi

        # Step 3: Claude context
        echo "Step 3/4: Adding to Claude Code..."
        mkdir -p "$PROJECT_ROOT/.claude/capabilities"
        mkdir -p "$PROJECT_ROOT/.claude/commands"
        mkdir -p "$PROJECT_ROOT/.claude/context"

        cp "$CAPABILITY_DIR/.capability/agent-context.md" \
           "$PROJECT_ROOT/.claude/capabilities/issue-facade.md"

        # Create context file if not exists
        CONTEXT_FILE="$PROJECT_ROOT/.claude/context/capabilities.md"
        if [ ! -f "$CONTEXT_FILE" ]; then
            cat > "$CONTEXT_FILE" << 'EOF'
# Available Capabilities

## Issue Tracking: issue-facade

**CRITICAL:** Always use this for issue operations. Never bypass with direct API calls.

**Docs:** `.claude/capabilities/issue-facade.md`
**Usage:** `/use-issues`
EOF
        fi

        # Create slash command
        cat > "$PROJECT_ROOT/.claude/commands/use-issues.md" << 'EOF'
Use the issue-facade capability for all issue tracking operations.

**Quick reference:** See `.claude/capabilities/issue-facade.md`
**Examples:** See `capabilities/issue-facade/examples/agents/`

**DO NOT use direct API calls or platform CLIs!**
EOF

        echo "✓ Claude Code configured"
        echo ""

        # Step 4: Verify
        echo "Step 4/4: Verifying setup..."
        echo ""
        issue --version && echo "✓ CLI works" || echo "❌ CLI not working"
        issue backend list | grep -q "default" && echo "✓ Backend configured" || echo "⚠️  Backend not configured"
        [ -f "$PROJECT_ROOT/.claude/capabilities/issue-facade.md" ] && echo "✓ Claude context exists" || echo "❌ Claude context missing"
        [ -f "$PROJECT_ROOT/.claude/commands/use-issues.md" ] && echo "✓ Slash command exists" || echo "❌ Slash command missing"

        echo ""
        echo "✅ Setup complete!"
        echo ""
        echo "Next steps:"
        echo "  1. Test: issue list --limit=5"
        echo "  2. In Claude Code: /use-issues"
        echo "  3. See examples: capabilities/issue-facade/examples/agents/"
        ;;

    0)
        echo "Exiting."
        exit 0
        ;;

    *)
        echo "Invalid option"
        exit 1
        ;;
esac

echo ""
echo "📚 Additional Resources:"
echo "   - Integration guide: $CAPABILITY_DIR/AGENT_INTEGRATION.md"
echo "   - Checklist:        $CAPABILITY_DIR/.capability/integration-checklist.md"
echo "   - Examples:         $CAPABILITY_DIR/examples/agents/"
echo ""