Return 409 Conflict for duplicate skill version uploads (#41)

Previously, uploading a skill version that already existed returned 400 Bad
Request, making it hard for clients to distinguish between validation errors
and benign duplicate uploads without parsing the response body.

- Add IsDuplicateVersion flag and DuplicateVersion() factory to SkillUploadResult
- Return 409 Conflict with error code 'duplicate_version' for duplicates
- Add integration tests for 409 duplicate and multi-version success

Author: Aaronontheweb

src/SkillServer/Endpoints.cs

@@ -1,4 +1,4 @@
-// -----------------------------------------------------------------------
+// -----------------------------------------------------------------------
 // <copyright file="Endpoints.cs" company="Petabridge, LLC">
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
@@ -232,6 +232,15 @@ private static async Task<IResult> UploadSkill(
 
         if (!result.Success)
         {
+            if (result.IsDuplicateVersion)
+            {
+                return Results.Conflict(new ErrorResponse
+                {
+                    Error = "duplicate_version",
+                    Message = result.Error ?? "Version already exists."
+                });
+            }
+
             return Results.BadRequest(new ErrorResponse
             {
                 Error = "upload_failed",

src/SkillServer/Services/SkillUploadService.cs

@@ -1,4 +1,4 @@
-// -----------------------------------------------------------------------
+// -----------------------------------------------------------------------
 // <copyright file="SkillUploadService.cs" company="Petabridge, LLC">
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
@@ -91,7 +91,7 @@ public async Task<SkillUploadResult> UploadSkillMdAsync(
             var existingVersion = await _repository.GetVersionAsync(skillId, version.Value, ct);
             if (existingVersion is not null)
             {
-                return SkillUploadResult.Failed($"Version {version.Value} already exists for skill {name.Value}.");
+                return SkillUploadResult.DuplicateVersion($"Version {version.Value} already exists for skill {name.Value}.");
             }
         }
 
@@ -181,12 +181,16 @@ public sealed record SkillUploadResult
     public SkillVersionString? Version { get; init; }
     public Sha256Digest? Digest { get; init; }
     public string? Error { get; init; }
+    public bool IsDuplicateVersion { get; init; }
 
     public static SkillUploadResult Succeeded(SkillName name, SkillVersionString version, Sha256Digest digest) =>
         new() { Success = true, Name = name, Version = version, Digest = digest };
 
     public static SkillUploadResult Failed(string error) =>
         new() { Success = false, Error = error };
+
+    public static SkillUploadResult DuplicateVersion(string error) =>
+        new() { Success = false, Error = error, IsDuplicateVersion = true };
 }
 
 /// <summary>

tests/SkillServer.Integration.Tests/SkillServerIntegrationTests.cs

@@ -1,4 +1,4 @@
-// -----------------------------------------------------------------------
+// -----------------------------------------------------------------------
 // <copyright file="SkillServerIntegrationTests.cs" company="Petabridge, LLC">
 //      Copyright (C) 2026 - 2026 Petabridge, LLC <https://petabridge.com>
 // </copyright>
@@ -481,4 +481,94 @@ public async Task ApiKeyManagement_WithoutAuth_Returns401()
         var response = await _fixture.HttpClient.GetAsync("/api-keys", ct);
         Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
     }
+
+    [Fact]
+    public async Task UploadSkill_DuplicateVersion_Returns409()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"dup-test-{Guid.NewGuid():N}"[..20];
+
+        var skillContent = $"""
+            ---
+            name: {skillName}
+            description: Testing duplicate version
+            ---
+
+            # Duplicate Test
+            """;
+
+        // Upload the first version
+        using var content1 = new MultipartFormDataContent();
+        content1.Add(new StringContent(skillName), "name");
+        content1.Add(new StringContent("1.0.0"), "version");
+
+        var fileContent1 = new ByteArrayContent(Encoding.UTF8.GetBytes(skillContent));
+        fileContent1.Headers.ContentType = new MediaTypeHeaderValue("text/markdown");
+        content1.Add(fileContent1, "file", "SKILL.md");
+
+        var uploadResponse1 = await _fixture.AuthenticatedHttpClient.PostAsync("/skills", content1, ct);
+        Assert.Equal(HttpStatusCode.Created, uploadResponse1.StatusCode);
+
+        // Upload the same version again - should return 409 Conflict
+        using var content2 = new MultipartFormDataContent();
+        content2.Add(new StringContent(skillName), "name");
+        content2.Add(new StringContent("1.0.0"), "version");
+
+        var fileContent2 = new ByteArrayContent(Encoding.UTF8.GetBytes(skillContent));
+        fileContent2.Headers.ContentType = new MediaTypeHeaderValue("text/markdown");
+        content2.Add(fileContent2, "file", "SKILL.md");
+
+        var uploadResponse2 = await _fixture.AuthenticatedHttpClient.PostAsync("/skills", content2, ct);
+        Assert.Equal(HttpStatusCode.Conflict, uploadResponse2.StatusCode);
+
+        // Verify the response body contains the duplicate_version error
+        var errorBody = await uploadResponse2.Content.ReadFromJsonAsync<SkillServer.Models.ErrorResponse>(ct);
+        Assert.NotNull(errorBody);
+        Assert.Equal("duplicate_version", errorBody.Error);
+        Assert.Contains(errorBody.Message!, "already exists");
+    }
+
+    [Fact]
+    public async Task UploadSkill_DifferentVersions_AreAllowed()
+    {
+        var ct = TestContext.Current.CancellationToken;
+        var skillName = $"ver-test-{Guid.NewGuid():N}"[..20];
+
+        var skillContent = $"""
+            ---
+            name: {skillName}
+            description: Testing different versions
+            ---
+
+            # Version Test
+            """;
+
+        // Upload v1.0.0
+        using var content1 = new MultipartFormDataContent();
+        content1.Add(new StringContent(skillName), "name");
+        content1.Add(new StringContent("1.0.0"), "version");
+
+        var fileContent1 = new ByteArrayContent(Encoding.UTF8.GetBytes(skillContent));
+        fileContent1.Headers.ContentType = new MediaTypeHeaderValue("text/markdown");
+        content1.Add(fileContent1, "file", "SKILL.md");
+
+        var uploadResponse1 = await _fixture.AuthenticatedHttpClient.PostAsync("/skills", content1, ct);
+        Assert.Equal(HttpStatusCode.Created, uploadResponse1.StatusCode);
+
+        // Upload v2.0.0 - should succeed
+        using var content2 = new MultipartFormDataContent();
+        content2.Add(new StringContent(skillName), "name");
+        content2.Add(new StringContent("2.0.0"), "version");
+
+        var fileContent2 = new ByteArrayContent(Encoding.UTF8.GetBytes(skillContent));
+        fileContent2.Headers.ContentType = new MediaTypeHeaderValue("text/markdown");
+        content2.Add(fileContent2, "file", "SKILL.md");
+
+        var uploadResponse2 = await _fixture.AuthenticatedHttpClient.PostAsync("/skills", content2, ct);
+        Assert.Equal(HttpStatusCode.Created, uploadResponse2.StatusCode);
+
+        // Verify both versions exist
+        var versions = await _fixture.Client.GetSkillVersionsAsync(skillName, ct);
+        Assert.Equal(2, versions.Count);
+    }
 }