fix(api): align OpenAPI contract with handlers

Author: skulidropek

packages/api/openapi.json

@@ -465,9 +465,16 @@ const QueryLinesSchema = Schema.Struct({
   lines: Schema.optional(Schema.String)
 })
 
+const ApiErrorEnvelopeSchema = Schema.Struct({
+  command: Schema.optional(Schema.String),
+  details: Schema.optional(Schema.Unknown),
+  message: Schema.String,
+  provider: Schema.optional(Schema.String),
+  type: Schema.String
+})
+
 const ApiErrorResponseSchema = Schema.Struct({
-  error: Schema.String,
-  message: Schema.String
+  error: ApiErrorEnvelopeSchema
 })
 
 const endpoint = {
@@ -486,7 +493,7 @@ const ProjectsGroup = HttpApiGroup.make("projects")
   .add(
     endpoint.post("createProject", "/projects")
       .setPayload(CreateProjectRequestSchema)
-      .addSuccess(ProjectResponseSchema)
+      .addSuccess(ProjectResponseSchema, { status: 201 })
       .addSuccess(CreateProjectAcceptedResponseSchema, { status: 202 })
   )
   .add(
@@ -518,7 +525,7 @@ const ProjectPortsGroup = HttpApiGroup.make("projectPorts")
   .add(
     endpoint.post("createProjectPort")`/projects/${ProjectIdParam}/ports`
       .setPayload(ProjectPortForwardRequestSchema)
-      .addSuccess(ProjectPortForwardResponseSchema)
+      .addSuccess(ProjectPortForwardResponseSchema, { status: 201 })
   )
   .add(
     endpoint.del("deleteProjectPort")`/projects/${ProjectIdParam}/ports/${TargetPortParam}`
@@ -540,15 +547,15 @@ const ProjectDatabasesGroup = HttpApiGroup.make("projectDatabases")
   .add(
     endpoint.post("saveDatabaseProfile")`/projects/${ProjectIdParam}/databases/profiles`
       .setPayload(ProjectDatabaseProfileRequestSchema)
-      .addSuccess(ProjectDatabaseProfileResponseSchema)
+      .addSuccess(ProjectDatabaseProfileResponseSchema, { status: 201 })
   )
   .add(
     endpoint.del("deleteDatabaseProfile")`/projects/${ProjectIdParam}/databases/profiles/${ProfileIdParam}`
       .addSuccess(EmptyResponseSchema)
   )
   .add(
     endpoint.post("exposeDatabaseProfile")`/projects/${ProjectIdParam}/databases/profiles/${ProfileIdParam}/expose`
-      .addSuccess(ProjectDatabaseForwardResponseSchema)
+      .addSuccess(ProjectDatabaseForwardResponseSchema, { status: 201 })
   )
   .add(
     endpoint.del("deleteDatabaseForward")`/projects/${ProjectIdParam}/databases/profiles/${ProfileIdParam}/expose`
@@ -624,7 +631,7 @@ const AuthGroup = HttpApiGroup.make("auth")
   .add(
     endpoint.post("authTerminalSession", "/auth/terminal-sessions")
       .setPayload(AuthTerminalSessionRequestSchema)
-      .addSuccess(AuthTerminalSessionResponseSchema)
+      .addSuccess(AuthTerminalSessionResponseSchema, { status: 201 })
   )
   .add(
     endpoint.post("codexImport", "/auth/codex/import")
@@ -653,7 +660,7 @@ const ProjectAuthGroup = HttpApiGroup.make("projectAuth")
 const TerminalGroup = HttpApiGroup.make("terminal")
   .add(
     endpoint.post("createTerminalByKey")`/projects/by-key/${ProjectKeyParam}/terminal-sessions`
-      .addSuccess(TerminalSessionResponseSchema)
+      .addSuccess(TerminalSessionResponseSchema, { status: 201 })
   )
   .add(
     endpoint.post("startTerminalByKey")`/projects/by-key/${ProjectKeyParam}/terminal-sessions/start`

packages/api/src/api/openapi.ts

@@ -22,4 +22,45 @@ describe("openapi contract", () => {
       expect(paths["/projects/{projectId}/auth"]).toBeUndefined()
       expect(Object.keys(paths)).toHaveLength(54)
     }))
+
+  it.effect("documents real HTTP success status codes for create and async endpoints", () =>
+    Effect.sync(() => {
+      const spec = buildDockerGitOpenApi()
+      const paths = spec.paths ?? {}
+
+      const postResponseStatuses = (path: string): ReadonlyArray<string> =>
+        Object.keys(paths[path]?.post?.responses ?? {})
+
+      expect(postResponseStatuses("/projects")).toEqual(expect.arrayContaining(["201", "202", "400"]))
+      expect(postResponseStatuses("/projects/{projectId}/ports")).toEqual(expect.arrayContaining(["201", "400"]))
+      expect(postResponseStatuses("/projects/{projectId}/databases/profiles")).toEqual(
+        expect.arrayContaining(["201", "400"])
+      )
+      expect(postResponseStatuses("/projects/{projectId}/databases/profiles/{profileId}/expose")).toEqual(
+        expect.arrayContaining(["201", "400"])
+      )
+      expect(postResponseStatuses("/auth/terminal-sessions")).toEqual(expect.arrayContaining(["201", "400"]))
+      expect(postResponseStatuses("/projects/by-key/{projectKey}/terminal-sessions")).toEqual(
+        expect.arrayContaining(["201", "400"])
+      )
+      expect(postResponseStatuses("/projects/by-key/{projectKey}/terminal-sessions/start")).toEqual(
+        expect.arrayContaining(["202", "400"])
+      )
+    }))
+
+  it.effect("documents the nested API error envelope used by HTTP handlers", () =>
+    Effect.sync(() => {
+      const spec = buildDockerGitOpenApi()
+      const serializedBadRequestSchema = JSON.stringify(
+        spec.paths?.["/projects"]?.post?.responses?.["400"] ?? {}
+      )
+
+      expect(serializedBadRequestSchema).toContain("\"required\":[\"error\"]")
+      expect(serializedBadRequestSchema).toContain("\"error\":{\"type\":\"object\"")
+      expect(serializedBadRequestSchema).toContain("\"type\":{\"type\":\"string\"")
+      expect(serializedBadRequestSchema).toContain("\"message\":{\"type\":\"string\"")
+      expect(serializedBadRequestSchema).toContain("\"provider\":{\"type\":\"string\"")
+      expect(serializedBadRequestSchema).toContain("\"command\":{\"type\":\"string\"")
+      expect(serializedBadRequestSchema).not.toContain("\"required\":[\"error\",\"message\"]")
+    }))
 })

packages/api/tests/openapi.test.ts

@@ -23,6 +23,17 @@ export const GithubStatusResponseSchema = Schema.Struct({
   status: GithubAuthStatusSchema
 })
 
+/**
+ * Boundary schema for the controller Codex authentication status.
+ *
+ * @pure true - describes immutable response data only.
+ * @effect none
+ * @invariant account may be null, while authPath, label, message, and present are always typed.
+ * @precondition input is an unknown JSON value received from the API boundary.
+ * @postcondition successful decoding yields the UI-safe Codex auth status shape.
+ * @complexity O(1) schema construction; O(n) decode where n is the response size.
+ * @throws Never.
+ */
 export const CodexAuthStatusSchema = Schema.Struct({
   account: NullableString,
   authPath: Schema.String,
@@ -31,6 +42,17 @@ export const CodexAuthStatusSchema = Schema.Struct({
   present: Schema.Boolean
 })
 
+/**
+ * Boundary schema for the Codex status API response envelope.
+ *
+ * @pure true - describes immutable response data only.
+ * @effect none
+ * @invariant status is always present; ok is an optional compatibility flag.
+ * @precondition input is an unknown JSON value received from the API boundary.
+ * @postcondition successful decoding yields a response with a validated CodexAuthStatusSchema status.
+ * @complexity O(1) schema construction; O(n) decode where n is the response size.
+ * @throws Never.
+ */
 export const CodexStatusResponseSchema = Schema.Struct({
   ok: Schema.optional(Schema.Boolean),
   status: CodexAuthStatusSchema

packages/app/src/web/api-auth-schema.ts

@@ -1,26 +1,37 @@
 import type { Effect } from "effect"
 
+import {
+  baseCreateProjectBody,
+  type CreateProjectRequestDraft,
+  optionalProjectResourceFields
+} from "./api-project-create-body.js"
 import { CreateProjectAcceptedResponseSchema } from "./api-schema.js"
-import type { CreateProjectAcceptedResponse, CreateProjectDraft } from "./api-schema.js"
+import type { CreateProjectAcceptedResponse } from "./api-schema.js"
 import { openApiJsonSchema } from "./openapi-client.js"
 
-const createProjectAcceptedBody = (draft: CreateProjectDraft) => ({
+/**
+ * Builds the async POST /projects request body.
+ *
+ * @param draft - Validated project creation draft plus optional resource limits.
+ * @returns Request body for an accepted asynchronous create request.
+ *
+ * @pure true - deterministic serialization of immutable input.
+ * @effect none
+ * @invariant async create uses the same common fields and optional resource fields as sync create.
+ * @precondition draft fields were validated by the UI create flow.
+ * @postcondition output includes async = true and preserves defined Playwright resource limits.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export const createProjectAcceptedBody = (draft: CreateProjectRequestDraft) => ({
+  ...baseCreateProjectBody(draft),
   async: true,
-  cpuLimit: draft.cpuLimit,
-  enableMcpPlaywright: draft.enableMcpPlaywright,
-  force: draft.force,
-  forceEnv: draft.forceEnv,
-  gpu: draft.gpu,
-  openSsh: false,
-  outDir: draft.outDir,
-  ramLimit: draft.ramLimit,
-  repoRef: draft.repoRef,
-  repoUrl: draft.repoUrl,
-  up: draft.up,
-  useManagedAuthorizedKeys: true
+  ...optionalProjectResourceFields(draft)
 })
 
-export const startCreateProject = (draft: CreateProjectDraft): Effect.Effect<CreateProjectAcceptedResponse, string> =>
+export const startCreateProject = (
+  draft: CreateProjectRequestDraft
+): Effect.Effect<CreateProjectAcceptedResponse, string> =>
   openApiJsonSchema(CreateProjectAcceptedResponseSchema, (client) =>
     client.POST("/projects", {
       body: createProjectAcceptedBody(draft)

packages/app/src/web/api-create-project.ts

@@ -1,18 +1,16 @@
 import { Effect } from "effect"
 
-import type { ApplyProjectRequest, ProjectResourceLimitRequest } from "../shared/project-resource-request.js"
-import type { CreateProjectDraft } from "./api-schema.js"
+import type { ApplyProjectRequest } from "../shared/project-resource-request.js"
+import {
+  baseCreateProjectBody,
+  type CreateProjectRequestDraft,
+  optionalProjectResourceFields
+} from "./api-project-create-body.js"
 import { OutputResponseSchema, ProjectResponseSchema } from "./api-schema.js"
 import { openApiJsonSchema } from "./openapi-client.js"
 
 export type { ApplyProjectRequest, ProjectResourceLimitRequest } from "../shared/project-resource-request.js"
-
-type CreateProjectRequestDraft = CreateProjectDraft & ProjectResourceLimitRequest
-
-const optionalProjectResourceFields = (request: ProjectResourceLimitRequest) => ({
-  ...(request.playwrightCpuLimit !== undefined && { playwrightCpuLimit: request.playwrightCpuLimit }),
-  ...(request.playwrightRamLimit !== undefined && { playwrightRamLimit: request.playwrightRamLimit })
-})
+export type { CreateProjectRequestDraft } from "./api-project-create-body.js"
 
 const applyProjectBody = (request: ApplyProjectRequest | undefined) => ({
   ...(request?.cpuLimit !== undefined && { cpuLimit: request.cpuLimit }),
@@ -22,18 +20,7 @@ const applyProjectBody = (request: ApplyProjectRequest | undefined) => ({
 })
 
 const createProjectBody = (draft: CreateProjectRequestDraft) => ({
-  cpuLimit: draft.cpuLimit,
-  enableMcpPlaywright: draft.enableMcpPlaywright,
-  force: draft.force,
-  forceEnv: draft.forceEnv,
-  gpu: draft.gpu,
-  openSsh: false,
-  outDir: draft.outDir,
-  ramLimit: draft.ramLimit,
-  repoRef: draft.repoRef,
-  repoUrl: draft.repoUrl,
-  up: draft.up,
-  useManagedAuthorizedKeys: true,
+  ...baseCreateProjectBody(draft),
   ...optionalProjectResourceFields(draft)
 })
 

packages/app/src/web/api-project-core.ts

@@ -0,0 +1,63 @@
+import type { ProjectResourceLimitRequest } from "../shared/project-resource-request.js"
+import type { CreateProjectDraft } from "./api-schema.js"
+
+/**
+ * Draft accepted by POST /projects helpers.
+ *
+ * @pure true - type-only boundary contract.
+ * @effect none
+ * @invariant includes the base project draft plus optional resource limit fields shared by sync and async create flows.
+ * @precondition callers already validated UI input into CreateProjectDraft fields.
+ * @postcondition request builders can serialize the same resource fields for both create variants.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export type CreateProjectRequestDraft = CreateProjectDraft & ProjectResourceLimitRequest
+
+/**
+ * Serializes optional Playwright resource limits for project creation requests.
+ *
+ * @param request - Shared resource limit fields from the validated create draft.
+ * @returns Object containing only defined Playwright limit fields.
+ *
+ * @pure true - deterministic projection from immutable input.
+ * @effect none
+ * @invariant undefined optional fields are omitted from the request body.
+ * @precondition request is a validated web create/apply resource limit request.
+ * @postcondition output is safe to spread into a JSON request body.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export const optionalProjectResourceFields = (request: ProjectResourceLimitRequest) => ({
+  ...(request.playwrightCpuLimit !== undefined && { playwrightCpuLimit: request.playwrightCpuLimit }),
+  ...(request.playwrightRamLimit !== undefined && { playwrightRamLimit: request.playwrightRamLimit })
+})
+
+/**
+ * Builds the common POST /projects request body used by sync and async flows.
+ *
+ * @param draft - Validated project creation draft.
+ * @returns Shared request body fields without the flow-specific async flag.
+ *
+ * @pure true - deterministic serialization of create draft fields.
+ * @effect none
+ * @invariant sync and async create requests share one definition of common fields.
+ * @precondition draft fields were validated by the UI create flow.
+ * @postcondition output preserves all non-optional project creation fields.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export const baseCreateProjectBody = (draft: CreateProjectDraft) => ({
+  cpuLimit: draft.cpuLimit,
+  enableMcpPlaywright: draft.enableMcpPlaywright,
+  force: draft.force,
+  forceEnv: draft.forceEnv,
+  gpu: draft.gpu,
+  openSsh: false,
+  outDir: draft.outDir,
+  ramLimit: draft.ramLimit,
+  repoRef: draft.repoRef,
+  repoUrl: draft.repoUrl,
+  up: draft.up,
+  useManagedAuthorizedKeys: true
+})