chore: openapi docs for undocumented routes and fix two broken doc blocks

plugins/file-manager/src/backend/index.ts

@@ -2050,6 +2050,30 @@ export async function activate(ctx: PluginContext) {
     closeDedicatedTransferSession,
   };
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferMethodPreview:
+   *   post:
+   *     summary: Preview how a host to host transfer would run
+   *     description: Says whether tar or per-file SFTP would be used, and why, without moving anything.
+   *     tags: [File Manager]
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [sourceSessionId, destSessionId, sourcePaths, destPath]
+   *             properties:
+   *               sourceSessionId: { type: string }
+   *               destSessionId: { type: string }
+   *               sourcePaths: { type: array, items: { type: string } }
+   *               destPath: { type: string }
+   *               methodPreference: { type: string, enum: [auto, tar, item_sftp] }
+   *     responses:
+   *       200: { description: The chosen method and the reason. }
+   *       400: { description: Missing parameters. }
+   */
   app.post("/transferMethodPreview", async (req, res) => {
     const {
       sourceSessionId,
@@ -2095,6 +2119,34 @@ export async function activate(ctx: PluginContext) {
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferToHost:
+   *   post:
+   *     summary: Copy or move files from one host to another
+   *     description: Starts a background transfer between two of the caller's file manager sessions.
+   *     tags: [File Manager]
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [sourceSessionId, destSessionId, sourcePaths, destPath]
+   *             properties:
+   *               sourceSessionId: { type: string }
+   *               destSessionId: { type: string }
+   *               sourcePaths: { type: array, items: { type: string } }
+   *               destPath: { type: string }
+   *               methodPreference: { type: string, enum: [auto, tar, item_sftp] }
+   *               move: { type: boolean, description: Delete the source after a successful copy. }
+   *               parallelSegmentCount: { type: integer }
+   *     responses:
+   *       200: { description: The new transfer id. }
+   *       400: { description: Missing parameters or a session is not connected. }
+   *       403: { description: A session belongs to someone else. }
+   *       500: { description: The transfer could not start. }
+   */
   app.post("/transferToHost", async (req, res) => {
     const {
       sourceSessionId,
@@ -2168,6 +2220,16 @@ export async function activate(ctx: PluginContext) {
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/activeTransfers:
+   *   get:
+   *     summary: List the caller's running host to host transfers
+   *     tags: [File Manager]
+   *     responses:
+   *       200: { description: The active transfers. }
+   *       401: { description: Not signed in. }
+   */
   app.get("/activeTransfers", async (req, res) => {
     const userId = ctx.currentActor();
     if (!userId)
@@ -2176,6 +2238,22 @@ export async function activate(ctx: PluginContext) {
     res.json({ transfers: listActiveTransfers(userId) });
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferStatus/{transferId}:
+   *   get:
+   *     summary: Get a transfer's progress
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: transferId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: The transfer's status and progress. }
+   *       401: { description: Not signed in. }
+   *       404: { description: No such transfer for this user. }
+   */
   app.get("/transferStatus/:transferId", async (req, res) => {
     const userId = ctx.currentActor();
     const transferId = req.params.transferId;
@@ -2187,6 +2265,21 @@ export async function activate(ctx: PluginContext) {
     res.json(status);
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferCancel/{transferId}:
+   *   post:
+   *     summary: Cancel a running transfer
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: transferId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: The transfer was asked to stop. }
+   *       401: { description: Not signed in. }
+   */
   app.post("/transferCancel/:transferId", (req, res) => {
     const userId = ctx.currentActor();
     const transferId = req.params.transferId;
@@ -2200,6 +2293,22 @@ export async function activate(ctx: PluginContext) {
     res.json({ ok: true });
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferCleanup/{transferId}:
+   *   post:
+   *     summary: Remove the partial files a cancelled transfer left
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: transferId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: What was removed. }
+   *       401: { description: Not signed in. }
+   *       404: { description: No such transfer for this user. }
+   */
   app.post("/transferCleanup/:transferId", async (req, res) => {
     const userId = ctx.currentActor();
     const transferId = req.params.transferId;
@@ -2219,6 +2328,22 @@ export async function activate(ctx: PluginContext) {
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/transferRetry/{transferId}:
+   *   post:
+   *     summary: Retry a failed or cancelled transfer
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: transferId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: The transfer started again. }
+   *       401: { description: Not signed in. }
+   *       404: { description: No such transfer for this user. }
+   */
   app.post("/transferRetry/:transferId", (req, res) => {
     const userId = ctx.currentActor();
     const transferId = req.params.transferId;

plugins/file-manager/src/backend/operation-routes.ts

@@ -57,6 +57,22 @@ export function registerFileOperationRoutes(
     return session;
   }
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/trash:
+   *   get:
+   *     summary: List items in the host's Termix trash
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: query
+   *         name: sessionId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: Trashed items, the retention in days and whether the caller may change it. }
+   *       400: { description: The session is not connected. }
+   *       403: { description: The session belongs to someone else. }
+   */
   app.get("/trash", async (req, res) => {
     const session = await ownedSession(req, res);
     if (!session) return;
@@ -73,6 +89,25 @@ export function registerFileOperationRoutes(
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/trash/{id}/restore:
+   *   post:
+   *     summary: Restore a trashed item to where it was
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: string }
+   *       - in: query
+   *         name: sessionId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: The restored path. }
+   *       409: { description: Something already exists at the original path. }
+   */
   app.post("/trash/:id/restore", async (req, res) => {
     const session = await ownedSession(req, res);
     if (!session) return;
@@ -91,6 +126,25 @@ export function registerFileOperationRoutes(
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/trash/{id}:
+   *   delete:
+   *     summary: Delete a trashed item for good
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema: { type: string }
+   *       - in: query
+   *         name: sessionId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: Deleted. }
+   *       500: { description: The delete failed on the host. }
+   */
   app.delete("/trash/:id", async (req, res) => {
     const session = await ownedSession(req, res);
     if (!session) return;
@@ -105,6 +159,21 @@ export function registerFileOperationRoutes(
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/trash:
+   *   delete:
+   *     summary: Empty the host's Termix trash
+   *     tags: [File Manager]
+   *     parameters:
+   *       - in: query
+   *         name: sessionId
+   *         required: true
+   *         schema: { type: string }
+   *     responses:
+   *       200: { description: How many items were deleted. }
+   *       500: { description: The delete failed on the host. }
+   */
   app.delete("/trash", async (req, res) => {
     const session = await ownedSession(req, res);
     if (!session) return;
@@ -115,6 +184,26 @@ export function registerFileOperationRoutes(
     }
   });
 
+  /**
+   * @openapi
+   * /plugin-api/file-manager/trash-retention:
+   *   put:
+   *     summary: Set how long trashed items are kept (admin only)
+   *     tags: [File Manager]
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [retentionDays]
+   *             properties:
+   *               retentionDays: { type: integer, minimum: 1, maximum: 3650 }
+   *     responses:
+   *       200: { description: The new retention. }
+   *       400: { description: Out of range. }
+   *       403: { description: Admin access required. }
+   */
   app.put("/trash-retention", async (req, res) => {
     if (!(await canManageRetention())) {
       return res.status(403).json({ error: "Admin access required" });