Close the HTTP contract loop

apps/server/package.json

@@ -12,7 +12,7 @@
 		"start": "bun run src/index.ts",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit",
-		"gen:openapi": "bun run scripts/emit-openapi.ts"
+		"gen:openapi": "bun run scripts/emit-openapi.ts && biome format --write openapi.json"
 	},
 	"dependencies": {
 		"@hono/zod-openapi": "^1.4.0",

apps/server/scripts/emit-openapi.ts

@@ -6,7 +6,7 @@ if (!res.ok) {
 }
 
 const doc = await res.json();
-const output = `${JSON.stringify(doc, null, 2)}\n`;
+const output = `${JSON.stringify(doc, null, "\t")}\n`;
 await Bun.write(new URL("../openapi.json", import.meta.url), output);
 
 console.log("Wrote apps/server/openapi.json");

apps/server/src/routes/files.ts

@@ -1,5 +1,14 @@
-import { OpenAPIHono } from "@hono/zod-openapi";
-import { jsonError } from "@/lib/http-error";
+import { createRoute, OpenAPIHono } from "@hono/zod-openapi";
+import { ErrorResponseSchema, errorResponses } from "@/schemas/common";
+import {
+	FileDownloadResponseSchema,
+	FileParamsSchema,
+	FileStatusesBodySchema,
+	FileStatusesResponseSchema,
+	FilesResponseSchema,
+	ProviderFileInfoSchema,
+	UploadFileFormSchema,
+} from "@/schemas/files";
 import {
 	deleteUserFile,
 	getUserFileDownloadUrl,
@@ -13,109 +22,135 @@ export const filesRoute = new OpenAPIHono();
 // Max upload size enforced at the edge (the provider also caps via nacos cmaMaxFileSize).
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 
-/**
- * POST /api/files — multipart/form-data with field `file`. Streams the bytes to the provider's
- * Files API via the SDK and returns the file metadata ({ id, filename, mime_type, size_bytes, created_at }).
- * Plain handler (not zod-openapi) so multipart parsing stays under our control.
- */
-filesRoute.post("/files", async (c) => {
-	let body: Record<string, unknown>;
-	try {
-		body = await c.req.parseBody();
-	} catch (error) {
-		return jsonError(error, 400);
-	}
-	const file = body.file;
-	if (!(file instanceof File) || file.size === 0) {
-		return c.json({ error: { message: "file is required" } }, 400);
-	}
-	if (file.size > MAX_UPLOAD_BYTES) {
-		return c.json({ error: { message: "file too large" } }, 413);
-	}
+const uploadFileRoute = createRoute({
+	method: "post",
+	path: "/files",
+	operationId: "uploadFile",
+	request: {
+		body: {
+			required: true,
+			content: { "multipart/form-data": { schema: UploadFileFormSchema } },
+		},
+	},
+	responses: {
+		201: {
+			description: "Upload a workspace file",
+			content: { "application/json": { schema: ProviderFileInfoSchema } },
+		},
+		413: {
+			description: "File exceeds the upload size limit",
+			content: { "application/json": { schema: ErrorResponseSchema } },
+		},
+		...errorResponses,
+	},
+});
+
+filesRoute.openapi(
+	uploadFileRoute,
+	async (c) => {
+		const { file } = c.req.valid("form");
+		if (file.size === 0) {
+			return c.json({ error: { message: "file is required" } }, 400);
+		}
+		if (file.size > MAX_UPLOAD_BYTES) {
+			return c.json({ error: { message: "file too large" } }, 413);
+		}
 
-	try {
 		const content = new Uint8Array(await file.arrayBuffer());
 		const info = await uploadUserFile({
 			content,
 			filename: file.name || "upload",
 			mimeType: file.type || undefined,
 		});
 		return c.json(info, 201);
-	} catch (error) {
-		return jsonError(error);
-	}
+	},
+	(result, c) => {
+		if (!result.success) return c.json({ error: { message: "file is required" } }, 400);
+	},
+);
+
+const listFilesRoute = createRoute({
+	method: "get",
+	path: "/files",
+	operationId: "listFiles",
+	responses: {
+		200: {
+			description: "List workspace files",
+			content: { "application/json": { schema: FilesResponseSchema } },
+		},
+		...errorResponses,
+	},
 });
 
-/**
- * GET /api/files — list workspace user-uploaded files (newest first), as
- * `{ files: [{ id, filename, mime_type, size_bytes, created_at, downloadable, status?, available }] }`.
- * The OpenAPI list omits `status` (@JsonIgnore) but carries `downloadable`; the server enriches
- * `status` + `available` via @openagentpack/sdk/file-lifecycle before responding.
- */
-filesRoute.get("/files", async (c) => {
-	try {
-		const files = await listUserFiles();
-		return c.json({ files });
-	} catch (error) {
-		return jsonError(error);
-	}
+filesRoute.openapi(listFilesRoute, async (c) => {
+	const files = await listUserFiles();
+	return c.json({ files }, 200);
+});
+
+const getFileStatusesRoute = createRoute({
+	method: "post",
+	path: "/files/status",
+	operationId: "getFileStatuses",
+	request: {
+		body: {
+			required: true,
+			content: { "application/json": { schema: FileStatusesBodySchema } },
+		},
+	},
+	responses: {
+		200: {
+			description: "Get file scan statuses",
+			content: { "application/json": { schema: FileStatusesResponseSchema } },
+		},
+		...errorResponses,
+	},
+});
+
+filesRoute.openapi(
+	getFileStatusesRoute,
+	async (c) => {
+		const { fileIds } = c.req.valid("json");
+		const files = await getUserFileStatuses(fileIds);
+		return c.json({ files }, 200);
+	},
+	(result, c) => {
+		if (!result.success) return c.json({ error: { message: "fileIds (string[]) is required" } }, 400);
+	},
+);
+
+const downloadFileRoute = createRoute({
+	method: "get",
+	path: "/files/{id}/download",
+	operationId: "downloadFile",
+	request: { params: FileParamsSchema },
+	responses: {
+		200: {
+			description: "Resolve a short-lived file download URL",
+			content: { "application/json": { schema: FileDownloadResponseSchema } },
+		},
+		...errorResponses,
+	},
 });
 
-/**
- * POST /api/files/status — body `{ fileIds: string[] }`. Returns each file's normalized scan
- * `status` and bindability (`{ files: [{ id, status, available }] }`).
- */
-filesRoute.post("/files/status", async (c) => {
-	let body: { fileIds?: unknown };
-	try {
-		body = await c.req.json();
-	} catch (error) {
-		return jsonError(error, 400);
-	}
-	const fileIds = body.fileIds;
-	if (!Array.isArray(fileIds) || fileIds.some((id) => typeof id !== "string")) {
-		return c.json({ error: { message: "fileIds (string[]) is required" } }, 400);
-	}
-	try {
-		const files = await getUserFileStatuses(fileIds as string[]);
-		return c.json({ files });
-	} catch (error) {
-		return jsonError(error);
-	}
+filesRoute.openapi(downloadFileRoute, async (c) => {
+	const { id } = c.req.valid("param");
+	const result = await getUserFileDownloadUrl(id);
+	return c.json(result, 200);
 });
 
-/**
- * GET /api/files/:id/download — resolves a short-lived presigned download URL for a file
- * (typically an agent-delivered artifact), as `{ url, expires_at }`. The webui fetches this on
- * demand (each click), so the URL never goes stale in the UI. Errors if the provider has no
- * download endpoint (bailian/claude).
- */
-filesRoute.get("/files/:id/download", async (c) => {
-	const id = c.req.param("id");
-	if (!id) {
-		return c.json({ error: { message: "file id is required" } }, 400);
-	}
-	try {
-		const result = await getUserFileDownloadUrl(id);
-		return c.json(result);
-	} catch (error) {
-		return jsonError(error);
-	}
+const deleteFileRoute = createRoute({
+	method: "delete",
+	path: "/files/{id}",
+	operationId: "deleteFile",
+	request: { params: FileParamsSchema },
+	responses: {
+		204: { description: "File deleted" },
+		...errorResponses,
+	},
 });
 
-/**
- * DELETE /api/files/:id — removes a previously uploaded file from the provider's Files API.
- * Used when the composer's upload chip is dismissed so the backend doesn't accumulate orphans.
- */
-filesRoute.delete("/files/:id", async (c) => {
-	const id = c.req.param("id");
-	if (!id) {
-		return c.json({ error: { message: "file id is required" } }, 400);
-	}
-	try {
-		await deleteUserFile(id);
-		return c.body(null, 204);
-	} catch (error) {
-		return jsonError(error);
-	}
+filesRoute.openapi(deleteFileRoute, async (c) => {
+	const { id } = c.req.valid("param");
+	await deleteUserFile(id);
+	return c.body(null, 204);
 });