diff --git a/.gitignore b/.gitignore
index 200960d..edc16d3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@ scripts/deploy_config.json
Serverdaten.txt
*.local.php
.env
+client-dotnet/Deploymentcenter.Packager/packager.config.json
diff --git a/client-dotnet/Deploymentcenter.Client/UpdateClient.cs b/client-dotnet/Deploymentcenter.Client/UpdateClient.cs
index 5d54fd8..a224d51 100644
--- a/client-dotnet/Deploymentcenter.Client/UpdateClient.cs
+++ b/client-dotnet/Deploymentcenter.Client/UpdateClient.cs
@@ -59,22 +59,39 @@ namespace Deploymentcenter.Client
// Path pattern: https://domain/releases/{ProjectId}/{channel}/latest.json
string staticUrl = $"{cleanBaseUrl}/releases/{projectId}/{channel}/latest.json";
- HttpResponseMessage response;
+ // Zuerst die statische latest.json, danach die API.
+ //
+ // Der Rueckfall auf die API war zuvor unerreichbar: er lag in
+ // einem catch, aber GetAsync wirft bei einem 404 keine Exception,
+ // sondern liefert eine Antwort mit Statuscode. Fehlte die
+ // latest.json, brach die Pruefung mit "HTTP Error NotFound" ab,
+ // statt die API zu befragen.
+ HttpResponseMessage? response = null;
+
try
{
response = await _httpClient.GetAsync(staticUrl, cancellationToken).ConfigureAwait(false);
}
catch
{
- // Fallback check: Deploymentcenter API endpoint
- // Path pattern: https://domain/api/updateservice/v1/check?product={projectId}&version={currentVersion}
- string apiUrl = $"{cleanBaseUrl}/api/updateservice/v1/check?product={Uri.EscapeDataString(projectId)}&version={Uri.EscapeDataString(currentVersion)}";
+ response = null;
+ }
+
+ if (response == null || !response.IsSuccessStatusCode)
+ {
+ response?.Dispose();
+
+ string apiUrl = $"{cleanBaseUrl}/api/updateservice/v1/check"
+ + $"?product={Uri.EscapeDataString(projectId)}"
+ + $"&version={Uri.EscapeDataString(currentVersion)}"
+ + $"&channel={Uri.EscapeDataString(channel)}";
+
response = await _httpClient.GetAsync(apiUrl, cancellationToken).ConfigureAwait(false);
}
if (!response.IsSuccessStatusCode)
{
- result.Message = $"HTTP Error {response.StatusCode} during update check";
+ result.Message = $"Update-Pruefung fehlgeschlagen: HTTP {(int)response.StatusCode}";
return result;
}
@@ -214,24 +231,107 @@ namespace Deploymentcenter.Client
return BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
}
+ ///
+ /// Prueft, ob neuer ist als .
+ ///
+ /// Die vorherige Fassung entfernte zwar die Vorabkennung, nicht aber ein
+ /// fuehrendes "v". Damit scheiterte Version.TryParse bei Angaben wie
+ /// "v1.4.2" und es wurde auf einen alphabetischen Vergleich
+ /// zurueckgefallen - dort gilt "v1.9.0" faelschlich als neuer als
+ /// "v1.10.0". Das entspricht dem Fehler, der serverseitig in der
+ /// SQL-Abfrage steckte.
+ ///
public static bool IsVersionNewer(string currentVer, string remoteVer)
{
- if (string.IsNullOrEmpty(remoteVer)) return false;
- if (string.IsNullOrEmpty(currentVer)) return true;
+ if (string.IsNullOrWhiteSpace(remoteVer)) return false;
+ if (string.IsNullOrWhiteSpace(currentVer)) return true;
- string CleanVer(string v)
+ return CompareVersions(remoteVer, currentVer) > 0;
+ }
+
+ ///
+ /// Vergleicht zwei Versionsangaben nach semantischer Ordnung.
+ /// Rueckgabe: negativ wenn a < b, 0 bei Gleichstand, positiv wenn a > b.
+ ///
+ public static int CompareVersions(string a, string b)
+ {
+ var (coreA, preA) = ParseVersion(a);
+ var (coreB, preB) = ParseVersion(b);
+
+ int length = Math.Max(coreA.Count, coreB.Count);
+ for (int i = 0; i < length; i++)
{
- int dash = v.IndexOf('-');
- return dash > 0 ? v.Substring(0, dash) : v;
+ int partA = i < coreA.Count ? coreA[i] : 0;
+ int partB = i < coreB.Count ? coreB[i] : 0;
+ if (partA != partB)
+ {
+ return partA.CompareTo(partB);
+ }
}
- if (Version.TryParse(CleanVer(currentVer), out var cVer) &&
- Version.TryParse(CleanVer(remoteVer), out var rVer))
+ // Eine Version ohne Vorabkennung rangiert ueber derselben mit:
+ // 1.0.0 ist neuer als 1.0.0-rc.1
+ bool emptyA = preA.Count == 0;
+ bool emptyB = preB.Count == 0;
+ if (emptyA && emptyB) return 0;
+ if (emptyA) return 1;
+ if (emptyB) return -1;
+
+ int preLength = Math.Max(preA.Count, preB.Count);
+ for (int i = 0; i < preLength; i++)
{
- return rVer > cVer;
+ if (i >= preA.Count) return -1;
+ if (i >= preB.Count) return 1;
+
+ bool numericA = int.TryParse(preA[i], out int numA);
+ bool numericB = int.TryParse(preB[i], out int numB);
+
+ if (numericA && numericB)
+ {
+ if (numA != numB) return numA.CompareTo(numB);
+ continue;
+ }
+
+ // Rein numerische Bestandteile rangieren unter alphanumerischen.
+ if (numericA != numericB) return numericA ? -1 : 1;
+
+ int cmp = string.CompareOrdinal(preA[i], preB[i]);
+ if (cmp != 0) return cmp > 0 ? 1 : -1;
}
- return string.Compare(remoteVer, currentVer, StringComparison.OrdinalIgnoreCase) > 0;
+ return 0;
+ }
+
+ private static (List Core, List Prerelease) ParseVersion(string version)
+ {
+ string value = (version ?? string.Empty).Trim().TrimStart('v', 'V');
+
+ // Build-Metadaten sind fuer die Rangfolge ohne Bedeutung.
+ int plus = value.IndexOf('+');
+ if (plus >= 0) value = value.Substring(0, plus);
+
+ var prerelease = new List();
+ int dash = value.IndexOf('-');
+ if (dash >= 0)
+ {
+ string preString = value.Substring(dash + 1);
+ value = value.Substring(0, dash);
+ if (preString.Length > 0)
+ {
+ prerelease.AddRange(preString.Split('.'));
+ }
+ }
+
+ var core = new List();
+ foreach (string part in value.Split('.'))
+ {
+ string digits = new string(part.Where(char.IsDigit).ToArray());
+ core.Add(digits.Length > 0 ? int.Parse(digits) : 0);
+ }
+
+ if (core.Count == 0) core.Add(0);
+
+ return (core, prerelease);
}
}
}
diff --git a/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj b/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj
index 1fb5fbf..7a6e193 100644
--- a/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj
+++ b/client-dotnet/Deploymentcenter.Packager/Deploymentcenter.Packager.csproj
@@ -18,4 +18,19 @@
+
+
+
+ PreserveNewest
+
+
+ PreserveNewest
+
+
+
diff --git a/client-dotnet/Deploymentcenter.Packager/Program.cs b/client-dotnet/Deploymentcenter.Packager/Program.cs
index 5b9c20f..3af3a51 100644
--- a/client-dotnet/Deploymentcenter.Packager/Program.cs
+++ b/client-dotnet/Deploymentcenter.Packager/Program.cs
@@ -15,18 +15,56 @@ using FluentFTP;
namespace Deploymentcenter.Packager
{
+ ///
+ /// Konfiguration des Packagers.
+ ///
+ /// Die Zugangsdaten standen zuvor als Standardwerte direkt im Quelltext und
+ /// lagen damit im Repository. Sie kommen jetzt ausschliesslich aus
+ /// packager.config.json (nicht versioniert) oder aus Umgebungsvariablen.
+ /// Fehlen sie, bricht das Programm mit einer klaren Meldung ab, statt sich
+ /// mit veralteten Werten zu verbinden.
+ ///
public class PackagerConfig
{
- public string FtpHost { get; set; } = "www531.your-server.de";
+ public string FtpHost { get; set; } = "";
public int FtpPort { get; set; } = 21;
- public string FtpUser { get; set; } = "bergisnu_4";
- public string FtpPass { get; set; } = "o2#M*NN^5EsT";
+ public string FtpUser { get; set; } = "";
+ public string FtpPass { get; set; } = "";
public string FtpRemoteBaseDir { get; set; } = "/public_html/releases";
public string ApiBaseUrl { get; set; } = "https://dc.mhdf.de";
+
+ ///
+ /// Token mit dem Recht updateservice:publish. Das Veroeffentlichen eines
+ /// Releases ist nicht mehr unauthentifiziert moeglich.
+ ///
+ public string ApiToken { get; set; } = "";
+
public List ExcludePatterns { get; set; } = new List
{
"*.pdb", "*.xml", "appsettings.Development.json", "appsettings.Staging.json", "*.log", "logs/*"
};
+
+ /// Umgebungsvariablen haben Vorrang vor der Konfigurationsdatei.
+ public void ApplyEnvironmentOverrides()
+ {
+ FtpHost = Env("DC_FTP_HOST", FtpHost);
+ FtpUser = Env("DC_FTP_USER", FtpUser);
+ FtpPass = Env("DC_FTP_PASS", FtpPass);
+ ApiBaseUrl = Env("DC_API_URL", ApiBaseUrl);
+ ApiToken = Env("DC_TOKEN", ApiToken);
+
+ string port = Env("DC_FTP_PORT", "");
+ if (int.TryParse(port, out int parsedPort) && parsedPort > 0)
+ {
+ FtpPort = parsedPort;
+ }
+ }
+
+ private static string Env(string name, string fallback)
+ {
+ string? value = Environment.GetEnvironmentVariable(name);
+ return string.IsNullOrWhiteSpace(value) ? fallback : value;
+ }
}
class Program
@@ -46,12 +84,43 @@ namespace Deploymentcenter.Packager
string configFile = GetArg(args, "--config") ?? Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "packager.config.json");
PackagerConfig config = LoadConfig(configFile);
+ config.ApplyEnvironmentOverrides();
- // Override config with explicit CLI args if provided
+ // Reihenfolge: CLI-Argument, dann Umgebungsvariable, dann Datei.
string ftpHost = GetArg(args, "--ftp-host") ?? config.FtpHost;
string ftpUser = GetArg(args, "--ftp-user") ?? config.FtpUser;
string ftpPass = GetArg(args, "--ftp-pass") ?? config.FtpPass;
string remoteBase = GetArg(args, "--remote-dir") ?? config.FtpRemoteBaseDir;
+ string apiToken = GetArg(args, "--token") ?? config.ApiToken;
+
+ var missing = new List();
+ if (string.IsNullOrWhiteSpace(ftpHost)) missing.Add("FTP-Host (--ftp-host / DC_FTP_HOST / ftpHost)");
+ if (string.IsNullOrWhiteSpace(ftpUser)) missing.Add("FTP-Benutzer (--ftp-user / DC_FTP_USER / ftpUser)");
+ if (string.IsNullOrWhiteSpace(ftpPass)) missing.Add("FTP-Passwort (--ftp-pass / DC_FTP_PASS / ftpPass)");
+
+ if (missing.Count > 0)
+ {
+ Console.ForegroundColor = ConsoleColor.Red;
+ Console.WriteLine("[FEHLER] Konfiguration unvollstaendig:");
+ foreach (var item in missing)
+ {
+ Console.WriteLine($" - {item}");
+ }
+ Console.ResetColor();
+ Console.WriteLine();
+ Console.WriteLine($"Vorlage kopieren: {Path.GetFileName(configFile)}.example -> {Path.GetFileName(configFile)}");
+ return 1;
+ }
+
+ if (string.IsNullOrWhiteSpace(apiToken))
+ {
+ Console.ForegroundColor = ConsoleColor.Yellow;
+ Console.WriteLine("[WARNUNG] Kein API-Token gesetzt (--token / DC_TOKEN / apiToken).");
+ Console.WriteLine(" Das Paket wird gebaut und hochgeladen, aber das Deploymentcenter");
+ Console.WriteLine(" erfaehrt nichts davon - Veroeffentlichen erfordert seit Version 2.0");
+ Console.WriteLine(" ein Token mit dem Recht updateservice:publish.");
+ Console.ResetColor();
+ }
publishDir = Path.GetFullPath(publishDir);
if (!Directory.Exists(publishDir))
@@ -162,6 +231,8 @@ namespace Deploymentcenter.Packager
Console.WriteLine($"[INFO] Uploading via FTP to {ftpHost}:{config.FtpPort} ({remoteVersionPath})...");
+ bool ftpSucceeded = false;
+
try
{
using var ftp = new AsyncFtpClient(ftpHost, ftpUser, ftpPass, config.FtpPort);
@@ -241,50 +312,153 @@ namespace Deploymentcenter.Packager
Console.WriteLine("[SUCCESS] Updated latest.json on FTP server!");
await ftp.Disconnect();
+ ftpSucceeded = true;
}
catch (Exception ex)
{
- Console.ForegroundColor = ConsoleColor.Yellow;
- Console.WriteLine($"[WARNING] FTP upload encountered error: {ex.Message}");
+ Console.ForegroundColor = ConsoleColor.Red;
+ Console.WriteLine($"[FEHLER] FTP-Upload fehlgeschlagen: {ex.Message}");
+ Console.WriteLine(" Das Paket wurde NICHT ausgeliefert.");
Console.ResetColor();
}
- // 6. Notify Deploymentcenter Web API
- try
- {
- using var http = new HttpClient();
- string apiPublishUrl = $"{config.ApiBaseUrl.TrimEnd('/')}/api/updateservice/v1/index.php";
- var payload = new
- {
- action = "publish_release",
- product_slug = project,
- version = version,
- channel = channel,
- release_notes = changelog,
- download_url = $"{config.ApiBaseUrl.TrimEnd('/')}/releases/{project}/{channel}/{version}/package.tar.gz",
- sha256_hash = packageSha256,
- git_commit = gitCommitShort,
- size_bytes = packageSizeBytes,
- is_critical = isCritical ? 1 : 0
- };
+ // 6. Deploymentcenter benachrichtigen
+ //
+ // Zuvor stand hier ein leeres catch, und ohne Erfolgsfall wurde gar
+ // nichts ausgegeben. Ein fehlgeschlagener Aufruf blieb damit
+ // unsichtbar, waehrend das Programm am Ende Erfolg meldete.
+ bool apiNotified = false;
+ string apiMessage = "uebersprungen (kein Token gesetzt)";
- string jsonContent = JsonSerializer.Serialize(payload);
- var content = new StringContent(jsonContent, Encoding.UTF8, "application/json");
- var response = await http.PostAsync(apiPublishUrl, content);
- if (response.IsSuccessStatusCode)
+ if (!string.IsNullOrWhiteSpace(apiToken))
+ {
+ try
{
- Console.WriteLine("[SUCCESS] Notified Deploymentcenter Web API of new release.");
+ using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
+ string apiPublishUrl = $"{config.ApiBaseUrl.TrimEnd('/')}/api/updateservice/v1/publish";
+
+ var payload = new
+ {
+ product_slug = project,
+ version = version,
+ channel = channel,
+ release_notes = changelog,
+ download_url = $"{config.ApiBaseUrl.TrimEnd('/')}/releases/{project}/{channel}/{version}/package.tar.gz",
+ sha256_hash = packageSha256,
+ git_commit = gitCommitShort,
+ size_bytes = packageSizeBytes,
+ is_critical = isCritical
+ };
+
+ var request = new HttpRequestMessage(HttpMethod.Post, apiPublishUrl)
+ {
+ Content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
+ };
+ request.Headers.Add("Authorization", $"Bearer {apiToken}");
+
+ var response = await http.SendAsync(request);
+ string body = await response.Content.ReadAsStringAsync();
+
+ if (response.IsSuccessStatusCode)
+ {
+ apiNotified = true;
+ apiMessage = ExtractJsonString(body, "message") ?? "Release im Deploymentcenter eingetragen.";
+
+ string? autoResolved = ExtractJsonString(body, "auto_resolved");
+ if (!string.IsNullOrEmpty(autoResolved) && autoResolved != "0")
+ {
+ apiMessage += $" ({autoResolved} Bugtracker-Item(s) automatisch geschlossen)";
+ }
+ }
+ else
+ {
+ apiMessage = $"HTTP {(int)response.StatusCode}: "
+ + (ExtractJsonString(body, "message") ?? body.Trim());
+ }
+ }
+ catch (Exception ex)
+ {
+ apiMessage = $"Aufruf fehlgeschlagen: {ex.Message}";
}
}
- catch { }
+
+ if (apiNotified)
+ {
+ Console.ForegroundColor = ConsoleColor.Green;
+ Console.WriteLine($"[SUCCESS] {apiMessage}");
+ }
+ else
+ {
+ Console.ForegroundColor = ConsoleColor.Yellow;
+ Console.WriteLine($"[WARNUNG] Deploymentcenter nicht benachrichtigt - {apiMessage}");
+ }
+ Console.ResetColor();
// Cleanup temp
try { Directory.Delete(outputTempDir, true); } catch { }
- Console.ForegroundColor = ConsoleColor.Green;
- Console.WriteLine($"\n[FINISHED] Release v{version} for {project} ({channel}) successfully published!");
+ // Der Rueckgabewert bildet jetzt ab, was tatsaechlich passiert ist.
+ // Zuvor wurde immer 0 und "successfully published" gemeldet, selbst
+ // wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren.
+ bool fullySucceeded = ftpSucceeded && apiNotified;
+
+ Console.WriteLine();
+ Console.ForegroundColor = fullySucceeded ? ConsoleColor.Green : ConsoleColor.Yellow;
+ Console.WriteLine(fullySucceeded
+ ? $"[FERTIG] Release {version} fuer {project} ({channel}) vollstaendig veroeffentlicht."
+ : $"[UNVOLLSTAENDIG] Release {version} fuer {project} ({channel}): "
+ + $"Upload {(ftpSucceeded ? "ok" : "FEHLGESCHLAGEN")}, "
+ + $"Registrierung {(apiNotified ? "ok" : "FEHLGESCHLAGEN")}.");
Console.ResetColor();
- return 0;
+
+ return fullySucceeded ? 0 : 2;
+ }
+
+ ///
+ /// Liest einen einzelnen Wert aus einer JSON-Antwort, ohne ein
+ /// vollstaendiges Modell dafuer zu benoetigen.
+ ///
+ static string? ExtractJsonString(string json, string propertyName)
+ {
+ try
+ {
+ using var doc = JsonDocument.Parse(json);
+ return FindProperty(doc.RootElement, propertyName);
+ }
+ catch
+ {
+ return null;
+ }
+ }
+
+ static string? FindProperty(JsonElement element, string propertyName)
+ {
+ if (element.ValueKind != JsonValueKind.Object)
+ {
+ return null;
+ }
+
+ if (element.TryGetProperty(propertyName, out var direct))
+ {
+ return direct.ValueKind == JsonValueKind.String
+ ? direct.GetString()
+ : direct.ToString();
+ }
+
+ // Fehlerantworten verpacken die Nachricht in einem "error"-Objekt.
+ foreach (var child in element.EnumerateObject())
+ {
+ if (child.Value.ValueKind == JsonValueKind.Object)
+ {
+ string? nested = FindProperty(child.Value, propertyName);
+ if (nested != null)
+ {
+ return nested;
+ }
+ }
+ }
+
+ return null;
}
static PackagerConfig LoadConfig(string path)
diff --git a/client-dotnet/Deploymentcenter.Packager/packager.config.example.json b/client-dotnet/Deploymentcenter.Packager/packager.config.example.json
new file mode 100644
index 0000000..3245a8d
--- /dev/null
+++ b/client-dotnet/Deploymentcenter.Packager/packager.config.example.json
@@ -0,0 +1,24 @@
+{
+ "_comment": "Kopie als packager.config.json anlegen und ausfuellen. packager.config.json ist per .gitignore ausgeschlossen. Alternativ ueber Umgebungsvariablen: DC_FTP_HOST, DC_FTP_PORT, DC_FTP_USER, DC_FTP_PASS, DC_API_URL, DC_TOKEN.",
+
+ "ftpHost": "ftp.example.com",
+ "ftpPort": 21,
+ "ftpUser": "ftp-user",
+ "ftpPass": "ftp-password",
+ "ftpRemoteBaseDir": "/public_html/releases",
+
+ "apiBaseUrl": "https://dc.example.com",
+ "_apiToken_comment": "Token mit dem Recht updateservice:publish. Im WebUI unter Token-Verwaltung erzeugen.",
+ "apiToken": "",
+
+ "excludePatterns": [
+ "*.pdb",
+ "*.xml",
+ "appsettings.Development.json",
+ "appsettings.Staging.json",
+ "*.log",
+ "logs/**",
+ "scratch/**",
+ "*.tmp"
+ ]
+}
diff --git a/client-dotnet/Deploymentcenter.Packager/packager.config.json b/client-dotnet/Deploymentcenter.Packager/packager.config.json
deleted file mode 100644
index ef89c76..0000000
--- a/client-dotnet/Deploymentcenter.Packager/packager.config.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
- "ftpHost": "www531.your-server.de",
- "ftpPort": 21,
- "ftpUser": "bergisnu_4",
- "ftpPass": "o2#M*NN^5EsT",
- "ftpRemoteBaseDir": "/public_html/releases",
- "apiBaseUrl": "https://dc.mhdf.de",
- "excludePatterns": [
- "*.pdb",
- "*.xml",
- "appsettings.Development.json",
- "appsettings.Staging.json",
- "*.log",
- "logs/**",
- "scratch/**",
- "*.tmp"
- ]
-}
diff --git a/docs/BUGTRACKER_INTEGRATION_GUIDE.md b/docs/BUGTRACKER_INTEGRATION_GUIDE.md
index df55f64..e565a56 100644
--- a/docs/BUGTRACKER_INTEGRATION_GUIDE.md
+++ b/docs/BUGTRACKER_INTEGRATION_GUIDE.md
@@ -1,266 +1,56 @@
-# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API
+# Bugtracker-Integration
-> **⚠️ Geändert in Version 2.0** — `POST /api/bugtracker/v1/report` und
-> `GET /api/bugtracker/v1/projects` verlangen jetzt zwingend ein Token mit dem
-> passenden Scope; Aufrufe ohne Token liefern `401 unauthorized`. Das
-> Antwortformat wurde vereinheitlicht. Die aktuelle, vollständige Beschreibung
-> steht im **[Agenten-Handbuch](../public/docs/bugtracker.md)** und unter
-> `/api/openapi.json`. Umstellungsschritte: **[UPGRADE.md](./UPGRADE.md)**.
-
-
-This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.
+> **Dieser Leitfaden wurde zusammengeführt.**
+>
+> Die vollständige, gepflegte Beschreibung steht im
+> **[Agenten-Handbuch](../public/docs/bugtracker.md)** — öffentlich erreichbar
+> unter `https://dc.mhdf.de/docs/` und maschinenlesbar unter
+> `https://dc.mhdf.de/api/openapi.json`.
+>
+> Zuvor existierten zwei Beschreibungen desselben Workflows nebeneinander. Sie
+> waren bereits auseinandergelaufen: die hier stehenden Beispiele riefen die
+> Endpunkte ohne Token auf, benutzten `report.php` und `manage/index.php` als
+> Pfade und kannten weder Claim/Lease noch Idempotenz. Ein Agent, der diesem
+> Dokument folgte, wäre seit Version 2.0 an `401 unauthorized` gescheitert.
---
-## 📌 Executive Overview for AI Agents
+## Was sich gegenüber der alten Fassung geändert hat
-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.
+| Alt | Neu |
+|---|---|
+| `POST /api/bugtracker/v1/report.php` ohne Token | `POST /api/bugtracker/v1/report` **mit** Token (`bugtracker:report`) |
+| `GET /api/bugtracker/v1/projects.php` ohne Token | `GET /api/bugtracker/v1/projects` **mit** Token (`bugtracker:read`) |
+| `GET .../manage/index.php?project_slug=…` | `GET .../manage?action=list&project_slug=…` |
+| `created_by` frei wählbar | Wird aus dem Token abgeleitet |
+| Keine Reservierung — zwei Agenten konnten dasselbe Item bearbeiten | `?action=next` holt und reserviert exklusiv (Claim/Lease) |
+| Wiederholte Sendung erzeugte Duplikate | `client_ref` bzw. Header `Idempotency-Key` |
+| Fehler nur als Freitext | Stabiler `error.code` zum Auswerten |
-### 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.
+## Kürzestmögliche Fassung
----
-
-## 🔑 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" \
+# 1. Arbeit holen und übernehmen
+curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=next" \
+ -H "Authorization: Bearer $DC_TOKEN" \
-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"
- }'
+ -d '{"project_slug": "myapp", "limit": 1}'
+
+# 2. Zwischenstand festhalten
+curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=comment&id=42" \
+ -H "Authorization: Bearer $DC_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"comment": "Ursache gefunden.", "action_taken": "investigated"}'
+
+# 3. Abschließen
+curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/manage?action=resolve&id=42" \
+ -H "Authorization: Bearer $DC_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"resolved_in_build": "v1.4.3", "resolution_notes": "Fix in AuthController."}'
```
----
+## Weiterführend
-## 🎯 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.
+- **[Agenten-Handbuch](../public/docs/bugtracker.md)** — vollständige Referenz mit allen Feldern, Filtern, Fehlercodes und einem Python-Beispiel
+- **[Agent-Prompt-Vorlage](./AGENT_PROMPT_TEMPLATE.md)** — Textbaustein für `CLAUDE.md` / `AGENTS.md`
+- **[UPGRADE.md](./UPGRADE.md)** — Umstellungsschritte für bestehende Integrationen
diff --git a/docs/UPDATESERVICE_INTEGRATION_GUIDE.md b/docs/UPDATESERVICE_INTEGRATION_GUIDE.md
index 5c9b27a..bedf1c8 100644
--- a/docs/UPDATESERVICE_INTEGRATION_GUIDE.md
+++ b/docs/UPDATESERVICE_INTEGRATION_GUIDE.md
@@ -76,26 +76,62 @@ Das Packaging-Tool verpackt den `dotnet publish`-Output, berechnet Hashes, erzeu
pack-and-deploy --project myapp --version 1.4.0 --channel prod --publish-dir ./bin/Release/net8.0/publish --changelog "Fehlerbehebungen und Performance-Optimierung"
```
-### Konfiguration (`packager.config.json`):
+### Konfiguration (`packager.config.json`)
+
+> Diese Datei enthält Zugangsdaten und ist per `.gitignore` von der
+> Versionskontrolle ausgeschlossen. Vorlage: `packager.config.example.json`.
+> In der vorherigen Fassung standen die echten FTP-Zugangsdaten sowohl hier in
+> der Anleitung als auch als Standardwerte im Quelltext von `Program.cs`.
```json
{
- "ftpHost": "www531.your-server.de",
+ "ftpHost": "ftp.example.com",
"ftpPort": 21,
- "ftpUser": "bergisnu_4",
- "ftpPass": "o2#M*NN^5EsT",
+ "ftpUser": "ftp-user",
+ "ftpPass": "ftp-password",
"ftpRemoteBaseDir": "/public_html/releases",
"apiBaseUrl": "https://dc.mhdf.de",
+ "apiToken": "dc_sub_...",
"excludePatterns": [
"*.pdb",
"*.xml",
"appsettings.Development.json",
"*.log",
- "logs/*"
+ "logs/**"
]
}
```
+`apiToken` braucht das Recht `updateservice:publish`. Ohne Token baut und lädt
+der Packager das Paket zwar hoch, meldet es aber nicht beim Deploymentcenter an
+und beendet sich mit Rückgabewert 2.
+
+### Alternative: Umgebungsvariablen
+
+Für CI-Läufe, in denen keine Datei abgelegt werden soll — sie haben Vorrang vor
+der Konfigurationsdatei:
+
+```bash
+export DC_FTP_HOST=ftp.example.com
+export DC_FTP_USER=ftp-user
+export DC_FTP_PASS='...'
+export DC_TOKEN='dc_sub_...'
+
+pack-and-deploy --project myapp --version 1.4.0 --channel prod \
+ --publish-dir ./bin/Release/net8.0/publish
+```
+
+### Rückgabewerte
+
+| Wert | Bedeutung |
+|---|---|
+| `0` | Paket gebaut, hochgeladen und im Deploymentcenter registriert |
+| `1` | Konfiguration unvollständig oder Publish-Verzeichnis fehlt — nichts wurde ausgeführt |
+| `2` | Teilweise fehlgeschlagen: FTP-Upload oder Registrierung ging schief |
+
+Zuvor lieferte das Werkzeug in allen Fällen `0` und meldete „successfully
+published", selbst wenn FTP-Upload und API-Aufruf beide fehlgeschlagen waren.
+
---
## 4. Standalone UpdateAgent (`update-agent`)
diff --git a/public/api/license/v1/index.php b/public/api/license/v1/index.php
index 2051b3c..87c2efd 100644
--- a/public/api/license/v1/index.php
+++ b/public/api/license/v1/index.php
@@ -33,23 +33,30 @@ $action = resolveLicenseAction();
switch ($action) {
+ // WICHTIG: Die Lizenz-Endpunkte antworten bewusst OHNE den
+ // status/error-Umschlag der uebrigen API. Ihr Format ist ein bereits
+ // ausgerollter Vertrag: das Feld "status" auf oberster Ebene traegt den
+ // Lizenzzustand (valid, revoked, expired, not_found, activation_limit).
+ // Ein Umschlag mit status=success wuerde von jedem bestehenden Client als
+ // "nicht valid" interpretiert - saemtliche Lizenzen gaelten als ungueltig.
+
case 'validate':
if (Http::method() !== 'POST') {
Http::fail(405, 'method_not_allowed', 'Diese Aktion erwartet POST.');
}
// Bewusst oeffentlich: Client-Anwendungen pruefen hier ihre Lizenz.
// Die Antwort verraet nichts ueber fremde Lizenzen.
- Http::ok(['result' => $service->validate(Http::body(), $ip)]);
+ Http::raw($service->validate(Http::body(), $ip));
case 'deactivate':
if (Http::method() !== 'POST') {
Http::fail(405, 'method_not_allowed', 'Diese Aktion erwartet POST.');
}
ApiAuth::requireScope($db, 'license:deactivate');
- Http::ok(['result' => $service->deactivate(Http::body(), $ip)]);
+ Http::raw($service->deactivate(Http::body(), $ip));
case 'status':
- Http::ok(['module' => 'license', 'version' => '2.0']);
+ Http::raw(['status' => 'ok', 'module' => 'license', 'version' => '2.0']);
default:
Http::fail(404, 'unknown_action', 'Endpunkt nicht gefunden.', null, [
diff --git a/src/Core/Http.php b/src/Core/Http.php
index 3716bb3..22c238b 100644
--- a/src/Core/Http.php
+++ b/src/Core/Http.php
@@ -101,6 +101,31 @@ final class Http
self::send(['status' => 'error', 'error' => $error], $status);
}
+ /**
+ * Sendet eine Antwort ohne den status/error-Umschlag.
+ *
+ * Fuer Schnittstellen mit bereits ausgerollten Konsumenten, deren Format
+ * feststeht. Konkret die Lizenzpruefung: dort liegt das Feld "status" auf
+ * oberster Ebene und traegt den Lizenzzustand (valid, revoked, expired ...).
+ * Ein Umschlag mit status=success wuerde von jedem bestehenden Client als
+ * "nicht valid" gelesen - die Lizenz gaelte damit ueberall als ungueltig.
+ */
+ public static function raw(array $payload, int $status = 200): void
+ {
+ if (!headers_sent()) {
+ http_response_code($status);
+ header('Content-Type: application/json; charset=utf-8');
+ }
+
+ $json = json_encode(
+ $payload,
+ JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT | JSON_INVALID_UTF8_SUBSTITUTE
+ );
+
+ echo $json === false ? '{"status":"error","message":"Antwort nicht kodierbar."}' : $json;
+ exit;
+ }
+
private static function send(array $payload, int $status): void
{
if (!headers_sent()) {