initial ai implementation

SPEC.md

@@ -0,0 +1,119 @@
+# LinearGiteaIntegration Specification
+
+## Project Overview
+
+- **Project Name**: LinearGiteaIntegration
+- **Type**: Web service / Integration middleware
+- **Core Functionality**: Integrate Linear issue tracking with Gitea, enabling PR/commit linking, workflow automation, and bidirectional issue sync
+- **Target Users**: Development teams using Linear for issue tracking and Gitea for Git hosting
+
+## Architecture
+
+### Components
+1. **Webhook Server**: Receives events from Gitea (push, pull request, issues)
+2. **Linear API Client**: Communicates with Linear API to create/update issues
+3. **Gitea API Client**: Communicates with Gitea API to create branches, PRs, update issues
+4. **Configuration Manager**: Handles API keys, webhooks, and settings
+
+### Technology Stack
+- **Language**: Python
+- **Web Framework**: FastAPI (modern, async Python web framework)
+- **Configuration**: YAML-based config file + environment variables
+
+## Functionality Specification
+
+### 1. PR Linking
+- Detect Linear issue ID (e.g., `LIN-123`) in:
+  - Branch name
+  - PR title
+  - PR description
+- When PR is opened/linked, add PR link to Linear issue
+- Support magic words: "closes", "fixes", "resolves" + issue ID
+
+### 2. Workflow Automation
+- Map Gitea PR states to Linear issue statuses:
+  - PR created → Move issue to "In Progress"
+  - PR merged → Move issue to "Done"
+  - PR closed (not merged) → Move issue back to "Todo"
+- Configurable status mappings per team
+
+### 3. Issues Sync
+- One-way sync: Gitea issues → Linear issues
+- Two-way sync: Changes sync both ways
+- Sync properties: title, description, status, assignee, labels, comments
+- Configurable per-repository settings
+
+### 4. Commit Linking
+- Detect Linear issue ID in commit messages
+- Add commit reference to Linear issue
+- Support multiple issues per commit
+
+### 5. Branch Suggestions
+- API endpoint to get suggested branch name for a Linear issue
+- Format: `{issue-id}-{slugified-title}` (e.g., `LIN-123-add-login-feature`)
+
+## Configuration
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 8080
+
+linear:
+  api_key: "${LINEAR_API_KEY}"
+  webhook_secret: "${LINEAR_WEBHOOK_SECRET}"
+
+gitea:
+  url: "https://gitea.example.com"
+  token: "${GITEA_TOKEN}"
+  webhook_secret: "${GITEA_WEBHOOK_SECRET}"
+
+sync:
+  enabled_repos:
+    - "my-org/my-repo"
+  default_team_id: "team_xxx"
+  status_mappings:
+    pr_created: "In Progress"
+    pr_merged: "Done"
+    pr_closed: "Todo"
+  sync_direction: "one-way"  # or "two-way"
+
+features:
+  pr_linking: true
+  workflow_automation: true
+  issues_sync: true
+  commit_linking: true
+  branch_suggestions: true
+```
+
+## API Endpoints
+
+### Webhooks
+- `POST /webhooks/gitea` - Receive Gitea events
+- `POST /webhooks/linear` - Receive Linear events
+
+### REST API
+- `GET /api/health` - Health check
+- `GET /api/issues/:id/branch` - Get suggested branch name for issue
+- `POST /api/sync/issue` - Manually trigger issue sync
+
+## Webhook Events to Handle
+
+### Gitea Events
+- `push` - Parse commit messages for issue IDs
+- `pull_request` - Link PRs, update status
+- `issues` - Sync issues to Linear
+
+### Linear Events
+- `Issue` - Sync issue changes to Gitea (for two-way sync)
+
+## Acceptance Criteria
+
+1. Server starts and listens on configured port
+2. Gitea webhook endpoint accepts and processes events
+3. PR linking works when issue ID found in branch/PR title
+4. Issue status updates based on PR state changes
+5. Issues created in Gitea appear in Linear (when sync enabled)
+6. Branch suggestion endpoint returns proper format
+7. Configuration loads from YAML file and environment variables
+8. Unit tests cover core functionality