diff --git a/.htaccess b/.htaccess index d660b99..03f79f1 100644 --- a/.htaccess +++ b/.htaccess @@ -10,8 +10,13 @@ RewriteRule ^api/updateservice/v1(?:/(.*))?$ public/api/updateservice/v1/index.php [L,QSA] RewriteRule ^api/tokens/v1/provision public/api/tokens/v1/provision.php [L,QSA] RewriteRule ^api/bugtracker/v1/report public/api/bugtracker/v1/report.php [L,QSA] + RewriteRule ^api/bugtracker/v1/projects public/api/bugtracker/v1/projects.php [L,QSA] RewriteRule ^api/bugtracker/v1/manage(?:/(.*))?$ public/api/bugtracker/v1/manage/index.php [L,QSA] + # Documentation routing + RewriteRule ^docs/(.*)$ public/docs/$1 [L,QSA] + RewriteRule ^docs/?$ public/docs/index.php [L,QSA] + # Fallback for static assets in /api/ RewriteRule ^api/(.*)$ public/api/$1 [L,QSA] diff --git a/docs/AGENT_PROMPT_TEMPLATE.md b/docs/AGENT_PROMPT_TEMPLATE.md new file mode 100644 index 0000000..ea703d7 --- /dev/null +++ b/docs/AGENT_PROMPT_TEMPLATE.md @@ -0,0 +1,42 @@ +# 📋 Minimal Agent Prompt Template (For CLAUDE.md / AGENTS.md / CursorRules) + +Copy & paste the following snippet into your agent system prompts or repository `CLAUDE.md` / `.cursorrules`: + +```markdown +## 🐛 Central Bugtracker & Feature Logging Directive + +As an AI developer agent, you MUST track all unhandled errors, stack traces, planned features, and refactoring ideas in the central **Deployment Center Bugtracker**. + +### 1. Monitored Projects & Discovery +Before reporting, check monitored projects via API or use the known project slug: +- **Projects Discovery API**: `GET https://dc.mhdf.de/api/bugtracker/v1/projects.php` +- **Known Slugs**: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`. +*Note: If you discover a bug or issue in the Deployment Center code itself while working elsewhere, report it under `project_slug: "deploymentcenter"`.* + +### 2. Reporting Bugs & Ideas +Submit reports via HTTP POST to: `https://dc.mhdf.de/api/bugtracker/v1/report.php` +Header: `Authorization: Bearer ` (or `X-Agent-Token: `) + +```json +{ + "project_slug": "deploymentcenter", + "type": "bug", + "title": "Short descriptive title of the error or feature", + "description": "Condition or context under which it occurred", + "error_message": "Exact exception message", + "stack_trace": "Complete stack trace snippet", + "severity": "high", + "push_id": "push_wf_8912", + "created_by": "agent:your-name" +} +``` + +- **Severities**: + - `idea`: 💡 Quick reminder / thought for later + - `wishlist`: ⭐ Backlog feature request + - `low` / `medium` / `high` / `critical`: Standard bug severities + +### 3. Full API Documentation On-Demand +If you need complete API details, token provisioning instructions, or cURL/Python examples, read: +📄 **Documentation URL**: `https://dc.mhdf.de/docs/bugtracker.md` +``` diff --git a/docs/BUGTRACKER_INTEGRATION_GUIDE.md b/docs/BUGTRACKER_INTEGRATION_GUIDE.md index c016152..939e7b6 100644 --- a/docs/BUGTRACKER_INTEGRATION_GUIDE.md +++ b/docs/BUGTRACKER_INTEGRATION_GUIDE.md @@ -49,6 +49,50 @@ Header: `Authorization: Bearer ` --- +## 📂 1.5. Discovering Monitored Projects API + +Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center. + +### Endpoint: `GET /api/bugtracker/v1/projects.php` + +#### Response: +```json +{ + "status": "success", + "count": 4, + "projects": [ + { + "id": 1, + "slug": "myapp", + "name": "My Application Deluxe", + "notes": "Hauptanwendung für Desktop und Server" + }, + { + "id": 2, + "slug": "polytrader", + "name": "PolyTrader Suite Pro", + "notes": "Trading- und Handelssystem Client" + }, + { + "id": 3, + "slug": "predictalytics", + "name": "Predictalytics Engine", + "notes": "Datenanalyse und Vorhersage Dienst" + }, + { + "id": 4, + "slug": "deploymentcenter", + "name": "Deployment Center", + "notes": "Zentrale Verwaltungs- & Update-Plattform" + } + ] +} +``` + +If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`. + +--- + ## 🐛 2. Reporting Bugs, Features & Ideas ### Endpoint: `POST /api/bugtracker/v1/report.php` diff --git a/public/api/bugtracker/v1/manage/index.php b/public/api/bugtracker/v1/manage/index.php index a2016d0..75e0378 100644 --- a/public/api/bugtracker/v1/manage/index.php +++ b/public/api/bugtracker/v1/manage/index.php @@ -69,6 +69,11 @@ try { } // Sub-actions + if ($action === 'projects' || str_contains($path, '/projects')) { + echo json_encode(['status' => 'success', 'projects' => $repo->getProjects()], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES); + exit; + } + if ($action === 'stats' || str_ends_with($path, '/stats')) { echo json_encode(['status' => 'success', 'stats' => $repo->getStats()], JSON_PRETTY_PRINT); exit; diff --git a/public/api/bugtracker/v1/projects.php b/public/api/bugtracker/v1/projects.php new file mode 100644 index 0000000..a5c3a10 --- /dev/null +++ b/public/api/bugtracker/v1/projects.php @@ -0,0 +1,44 @@ +getProjects(); + + echo json_encode([ + 'status' => 'success', + 'count' => count($projects), + 'projects' => array_map(function($p) { + return [ + 'id' => (int)$p['id'], + 'slug' => $p['slug'], + 'name' => $p['name'], + 'notes' => $p['notes'] ?? null, + ]; + }, $projects), + ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES); + +} catch (Throwable $t) { + http_response_code(500); + echo json_encode(['status' => 'error', 'message' => 'Failed to fetch projects: ' . $t->getMessage()]); +} diff --git a/public/docs/.htaccess b/public/docs/.htaccess new file mode 100644 index 0000000..13fe496 --- /dev/null +++ b/public/docs/.htaccess @@ -0,0 +1,8 @@ +# Documentation Public Access +Satisfy Any +Allow from all + +# Apache 2.4+ compatibility + + Require all granted + diff --git a/public/docs/bugtracker.md b/public/docs/bugtracker.md new file mode 100644 index 0000000..939e7b6 --- /dev/null +++ b/public/docs/bugtracker.md @@ -0,0 +1,258 @@ +# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API + +This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**. + +--- + +## 📌 Executive Overview for AI Agents + +As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center. + +### Core Capabilities: +1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks. +2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication. +3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`). +4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments. + +--- + +## 🔑 1. Token Provisioning API + +Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**. + +### Endpoint: `POST /api/tokens/v1/provision` + +Header: `Authorization: Bearer ` + +#### Request Payload: +```json +{ + "parent_token": "dc_master_myapp_dev_agent_001", + "name": "Codebase Refactoring Agent Token", + "environment": "development", + "scopes": ["bugtracker:report", "bugtracker:manage"], + "expires_in_hours": 24 +} +``` + +#### Response: +```json +{ + "status": "success", + "token_id": "tok_s_8912ab", + "raw_token": "dc_sub_myapp_refactor_agent_991", + "scopes": ["bugtracker:report", "bugtracker:manage"], + "environment": "development", + "expires_at": "2026-08-07 21:00:00" +} +``` + +--- + +## 📂 1.5. Discovering Monitored Projects API + +Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center. + +### Endpoint: `GET /api/bugtracker/v1/projects.php` + +#### Response: +```json +{ + "status": "success", + "count": 4, + "projects": [ + { + "id": 1, + "slug": "myapp", + "name": "My Application Deluxe", + "notes": "Hauptanwendung für Desktop und Server" + }, + { + "id": 2, + "slug": "polytrader", + "name": "PolyTrader Suite Pro", + "notes": "Trading- und Handelssystem Client" + }, + { + "id": 3, + "slug": "predictalytics", + "name": "Predictalytics Engine", + "notes": "Datenanalyse und Vorhersage Dienst" + }, + { + "id": 4, + "slug": "deploymentcenter", + "name": "Deployment Center", + "notes": "Zentrale Verwaltungs- & Update-Plattform" + } + ] +} +``` + +If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`. + +--- + +## 🐛 2. Reporting Bugs, Features & Ideas + +### Endpoint: `POST /api/bugtracker/v1/report.php` + +Header: `Authorization: Bearer ` + +### A. Reporting an Unhandled Exception / Bug +```json +{ + "project_slug": "myapp", + "type": "bug", + "title": "NullReferenceException in UserAuthService.cs line 42", + "description": "Triggered when user logs in without an active session object.", + "error_message": "NullReferenceException: Object reference not set to an instance of an object.", + "stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18", + "build_version": "v1.4.2-dev", + "environment": "development", + "severity": "high", + "push_id": "push_wf_8912", + "target_agent": "agent:code-fixer-01", + "tags": "auth, security, csharp", + "created_by": "agent:watchdog-monitor" +} +``` + +### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`) +```json +{ + "project_slug": "myapp", + "type": "feature_request", + "title": "Automatische Datenbank-Backups vor FTP Deployments", + "description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.", + "build_version": "v1.6.0-roadmap", + "environment": "development", + "severity": "idea", + "push_id": "push_wf_9910", + "target_agent": "agent:db-optimizer", + "tags": "database, automation, backup", + "created_by": "agent:planner" +} +``` + +#### Response: +```json +{ + "status": "success", + "item_id": 4, + "is_new": true, + "occurrence_count": 1, + "error_hash": "e2c918a514d89a42f", + "type": "bug", + "environment": "development", + "push_id": "push_wf_8912", + "message": "New bug reported successfully." +} +``` + +--- + +## 📌 3. Managing Items (Fetching, Updating & Commenting) + +### Base Endpoint: `/api/bugtracker/v1/manage/index.php` + +Header: `Authorization: Bearer ` + +### A. Fetching Open Items Assigned to an Agent +```http +GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01 +``` + +### B. Updating Status & Details (`POST ?action=update`) +```json +{ + "id": 4, + "status": "in_progress", + "severity": "high", + "push_id": "push_wf_8912", + "target_agent": "agent:code-fixer-01", + "tags": "auth, fixed_pending_test", + "author": "agent:code-fixer-01" +} +``` + +### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`) +```json +{ + "id": 4, + "comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.", + "action_taken": "code_patched", + "author": "agent:code-fixer-01" +} +``` + +### D. Marking as Resolved (`POST ?action=resolve`) +```json +{ + "id": 4, + "resolved_in_build": "v1.4.3-dev", + "resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.", + "author": "agent:code-fixer-01" +} +``` + +--- + +## 💻 4. Code Implementation Examples for Agents + +### Python Example: Automatic Error Reporter Decorator +```python +import requests +import traceback +import sys + +DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php" +AGENT_TOKEN = "dc_sub_myapp_agent_live_001" + +def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None): + payload = { + "project_slug": project_slug, + "type": "bug", + "title": f"{type(exc).__name__}: {str(exc)}", + "error_message": str(exc), + "stack_trace": traceback.format_exc(), + "build_version": "v1.4.2", + "environment": env, + "severity": "high", + "push_id": push_id, + "created_by": "agent:python-runner" + } + headers = { + "Content-Type": "application/json", + "Authorization": f"Bearer {AGENT_TOKEN}" + } + try: + r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5) + return r.json() + except Exception as e: + print(f"Failed to report to Deployment Center: {e}", file=sys.stderr) +``` + +### cURL Example: Submit Feature Request / Idea +```bash +curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \ + -H "Authorization: Bearer dc_sub_myapp_agent_live_001" \ + -H "Content-Type: application/json" \ + -d '{ + "project_slug": "myapp", + "type": "feature_request", + "title": "Erweiterte Filterung im WebUI Dashboard", + "severity": "idea", + "push_id": "push_task_1029", + "tags": "ui, dashboard", + "created_by": "agent:dev-assistant" + }' +``` + +--- + +## 🎯 Best Practices for Developer Agents + +1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run. +2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas. +3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed. diff --git a/public/docs/index.php b/public/docs/index.php new file mode 100644 index 0000000..3aa9491 --- /dev/null +++ b/public/docs/index.php @@ -0,0 +1,156 @@ + + + + + + + Deployment Center - Developer & Agent Documentation + + + + + +
+
+

🚀 Deployment Center API & Agent Documentation

+ +
+
Loading documentation...
+
+ + + + diff --git a/sql/migrations/005_bugtracker_push_id_and_severities.sql b/sql/migrations/005_bugtracker_push_id_and_severities.sql index 2e67d97..5a03110 100644 --- a/sql/migrations/005_bugtracker_push_id_and_severities.sql +++ b/sql/migrations/005_bugtracker_push_id_and_severities.sql @@ -48,6 +48,11 @@ DEALLOCATE PREPARE stmt; SET FOREIGN_KEY_CHECKS = 1; +-- Seed Deployment Center Project +INSERT INTO dc_projects (id, slug, name, notes, default_cache_ttl_hours) VALUES +(4, 'deploymentcenter', 'Deployment Center', 'Zentrale Verwaltungs- & Update-Plattform', 168) +ON DUPLICATE KEY UPDATE name = VALUES(name); + -- Seed Sample Feature Idea INSERT IGNORE INTO bugtracker_items ( id, project_slug, type, title, description, error_message, stack_trace, error_hash, build_version, environment, severity, status, occurrence_count, push_id, target_agent, tags, created_by diff --git a/sql/schema.sql b/sql/schema.sql index b05c5c5..af4fc1d 100644 --- a/sql/schema.sql +++ b/sql/schema.sql @@ -259,7 +259,8 @@ ON DUPLICATE KEY UPDATE interval_sec = VALUES(interval_sec); INSERT INTO dc_projects (id, slug, name, notes, default_cache_ttl_hours) VALUES (1, 'myapp', 'My Application Deluxe', 'Hauptanwendung für Desktop und Server', 168), (2, 'polytrader', 'PolyTrader Suite Pro', 'Trading- und Handelssystem Client', 72), -(3, 'predictalytics', 'Predictalytics Engine', 'Datenanalyse und Vorhersage Dienst', 168) +(3, 'predictalytics', 'Predictalytics Engine', 'Datenanalyse und Vorhersage Dienst', 168), +(4, 'deploymentcenter', 'Deployment Center', 'Zentrale Verwaltungs- & Update-Plattform', 168) ON DUPLICATE KEY UPDATE id = id; -- Seed Initial Licenses (Non-destructive) diff --git a/src/Modules/Bugtracker/BugRepo.php b/src/Modules/Bugtracker/BugRepo.php index fcaa3e6..f6b9b95 100644 --- a/src/Modules/Bugtracker/BugRepo.php +++ b/src/Modules/Bugtracker/BugRepo.php @@ -417,4 +417,13 @@ class BugRepo return $stats; } + + /** + * Get list of all monitored projects. + */ + public function getProjects(): array + { + $stmt = $this->db->query('SELECT id, slug, name, notes, default_cache_ttl_hours FROM dc_projects ORDER BY name ASC'); + return $stmt->fetchAll() ?: []; + } }