generated from coulomb/repo-seed
tegwick
b605d970e3
Renames the package, distribution, CLI alias, Makefile targets, and working directory from issue-facade to issue-core, signalling its role as the authoritative task lifecycle manager for the Coulomb org (peer to activity-core, rules-core, project-core). Adds POST /issues/ ingestion endpoint for activity-core's IssueSink, under a new optional [api] extra. The endpoint is served by `issue serve`, authenticates via the ISSUE_CORE_API_KEY env var (Bearer or X-API-Key header), and routes the TaskSpec payload to the configured default backend with full traceability metadata embedded in sync_metadata. - T01: Python package issue_tracker -> issue_core, dir rename - T02: registered in state hub under custodian domain - T03: INTENT.md (what it is, what it isn't, how it fits) - T04: SCOPE.md (in/out-of-scope, integration boundaries) - T05: POST /issues/ via FastAPI + Uvicorn, 9 unit tests - T06: docs/nats-task-ingestion.md design stub Closes ISSC-WP-0001. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
317 lines
9.5 KiB
Bash
Executable File
317 lines
9.5 KiB
Bash
Executable File
#!/bin/bash
|
|
# Integration script for issue-core capability
|
|
# This script helps the main project discover and integrate the capability
|
|
|
|
set -e
|
|
|
|
CAPABILITY_NAME="issue-core"
|
|
CAPABILITY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$CAPABILITY_DIR/../.." && pwd)}"
|
|
|
|
echo "🔧 Issue Core 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-core.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-core
|
|
|
|
**Location:** `capabilities/issue-core/`
|
|
**Documentation:** `.claude/capabilities/issue-core.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_core.backends.gitea import GiteaBackend
|
|
backend = GiteaBackend()
|
|
backend.connect(config)
|
|
issues = backend.list_issues()
|
|
```
|
|
|
|
**Full Documentation:** See `.claude/capabilities/issue-core.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-core.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-core capability**:
|
|
|
|
## Available API
|
|
|
|
**Python (Recommended):**
|
|
```python
|
|
from issue_core.backends.gitea import GiteaBackend
|
|
from issue_core.core.models import Issue, Label, IssueState
|
|
from issue_core.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-core/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-core 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-core.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-core
|
|
|
|
**CRITICAL:** Always use this for issue operations. Never bypass with direct API calls.
|
|
|
|
**Docs:** `.claude/capabilities/issue-core.md`
|
|
**Usage:** `/use-issues`
|
|
EOF
|
|
fi
|
|
|
|
# Create slash command
|
|
cat > "$PROJECT_ROOT/.claude/commands/use-issues.md" << 'EOF'
|
|
Use the issue-core capability for all issue tracking operations.
|
|
|
|
**Quick reference:** See `.claude/capabilities/issue-core.md`
|
|
**Examples:** See `capabilities/issue-core/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-core.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-core/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 ""
|