feat: migrate to OpenAPI 3.0 with oneOf unions

- Add swagger2openapi conversion step to generate OpenAPI 3.0
- Add patch-openapi.ts script to inject oneOf discriminated unions
- Update docs server to embed static openapi.json
- Update moveItemsToDirectory response to use oneOf for items
- Add docs/README.md documenting the pipeline
- Use bun instead of node for scripts

apps/backend/docs/swagger.json

@@ -441,10 +441,13 @@
                         "BearerAuth": []
                     }
                 ],
-                "description": "Move one or more files or directories into this directory. All items must currently be in the same source directory.",
+                "description": "Move one or more files or directories into this directory. Returns detailed status for each item including which were successfully moved, which had conflicts, and which encountered errors.",
                 "consumes": [
                     "application/json"
                 ],
+                "produces": [
+                    "application/json"
+                ],
                 "tags": [
                     "directories"
                 ],
@@ -476,10 +479,10 @@
                     }
                 ],
                 "responses": {
-                    "204": {
-                        "description": "Items moved successfully",
+                    "200": {
+                        "description": "Move operation results with moved, conflict, and error states",
                         "schema": {
-                            "type": "string"
+                            "$ref": "#/definitions/internal_catalog.moveItemsToDirectoryResponse"
                         }
                     },
                     "400": {
@@ -505,15 +508,6 @@
                                 "type": "string"
                             }
                         }
-                    },
-                    "409": {
-                        "description": "Name conflict in target directory",
-                        "schema": {
-                            "type": "object",
-                            "additionalProperties": {
-                                "type": "string"
-                            }
-                        }
                     }
                 }
             }
@@ -1427,6 +1421,61 @@
                 }
             }
         },
+        "internal_catalog.moveItemError": {
+            "description": "Error details for a failed item move",
+            "type": "object",
+            "properties": {
+                "error": {
+                    "description": "Error message describing what went wrong",
+                    "type": "string",
+                    "example": "permission denied"
+                },
+                "id": {
+                    "description": "ID of the item that failed to move",
+                    "type": "string",
+                    "example": "mElnUNCm8F22"
+                }
+            }
+        },
+        "internal_catalog.moveItemsToDirectoryResponse": {
+            "description": "Response from moving items to a directory with status for each item",
+            "type": "object",
+            "properties": {
+                "conflicts": {
+                    "description": "Array of IDs of items that conflicted with existing items in the target directory",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "xYz123AbC456"
+                    ]
+                },
+                "errors": {
+                    "description": "Array of errors that occurred during the move operation",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/internal_catalog.moveItemError"
+                    }
+                },
+                "items": {
+                    "description": "Array of items included in the request (FileInfo or DirectoryInfo objects)",
+                    "type": "array",
+                    "items": {}
+                },
+                "moved": {
+                    "description": "Array of IDs of successfully moved items",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "example": [
+                        "mElnUNCm8F22",
+                        "kRp2XYTq9A55"
+                    ]
+                }
+            }
+        },
         "internal_catalog.patchDirectoryRequest": {
             "description": "Request to update directory properties",
             "type": "object",