fix(app): address OpenAPI review follow-ups

Author: skulidropek

bun.lock

@@ -1,10 +1,23 @@
 import { describe, expect, it } from "@effect/vitest"
 import { Effect } from "effect"
+import * as fc from "fast-check"
 
 import { buildDockerGitOpenApi } from "../src/api/openapi.js"
 
 const documentedMethods = ["delete", "get", "post", "put"] as const
 const commonErrorStatuses = ["400", "401", "404", "409", "500"]
+const okOnlyOperations = [
+  { method: "post", path: "/projects/apply-all" },
+  { method: "post", path: "/projects/down-all" },
+  { method: "delete", path: "/projects/{projectId}" },
+  { method: "post", path: "/projects/{projectId}/down" },
+  { method: "delete", path: "/projects/{projectId}/ports/{targetPort}" },
+  { method: "delete", path: "/projects/{projectId}/databases/profiles/{profileId}" },
+  { method: "delete", path: "/projects/{projectId}/databases/profiles/{profileId}/expose" },
+  { method: "delete", path: "/projects/by-key/{projectKey}/terminal-sessions/{sessionId}" },
+  { method: "delete", path: "/auth/terminal-sessions/{sessionId}" },
+  { method: "post", path: "/projects/{projectId}/tasks/{pid}/stop" }
+] as const
 
 describe("openapi contract", () => {
   it.effect("documents generated REST paths from the Effect HttpApi contract", () =>
@@ -86,22 +99,38 @@ describe("openapi contract", () => {
       }
     }))
 
+  it.effect("preserves common error status invariant for arbitrary documented operations", () =>
+    Effect.sync(() => {
+      const spec = buildDockerGitOpenApi()
+      const paths = spec.paths ?? {}
+      const operations = Object.entries(paths).flatMap(([path, item]) =>
+        documentedMethods.flatMap((method) => {
+          const responses = item[method]?.responses
+          return responses === undefined ? [] : [{ method, path, responses }]
+        })
+      )
+
+      expect(operations.length).toBeGreaterThan(0)
+
+      fc.assert(
+        fc.property(fc.integer({ min: 0, max: operations.length - 1 }), (index) => {
+          const operation = operations[index]
+          if (operation === undefined) {
+            return false
+          }
+          expect(Object.keys(operation.responses), `${operation.method.toUpperCase()} ${operation.path}`).toEqual(
+            expect.arrayContaining(commonErrorStatuses)
+          )
+          return true
+        }),
+        { numRuns: Math.max(operations.length * 2, 50) }
+      )
+    }))
+
   it.effect("documents ok-only HTTP handlers as 200 JSON responses", () =>
     Effect.sync(() => {
       const spec = buildDockerGitOpenApi()
       const paths = spec.paths ?? {}
-      const okOnlyOperations = [
-        { method: "post", path: "/projects/apply-all" },
-        { method: "post", path: "/projects/down-all" },
-        { method: "delete", path: "/projects/{projectId}" },
-        { method: "post", path: "/projects/{projectId}/down" },
-        { method: "delete", path: "/projects/{projectId}/ports/{targetPort}" },
-        { method: "delete", path: "/projects/{projectId}/databases/profiles/{profileId}" },
-        { method: "delete", path: "/projects/{projectId}/databases/profiles/{profileId}/expose" },
-        { method: "delete", path: "/projects/by-key/{projectKey}/terminal-sessions/{sessionId}" },
-        { method: "delete", path: "/auth/terminal-sessions/{sessionId}" },
-        { method: "post", path: "/projects/{projectId}/tasks/{pid}/stop" }
-      ] as const
 
       for (const operation of okOnlyOperations) {
         const responses = paths[operation.path]?.[operation.method]?.responses ?? {}
@@ -114,6 +143,25 @@ describe("openapi contract", () => {
       }
     }))
 
+  it.effect("preserves ok-only handler response invariant for arbitrary ok-only operations", () =>
+    Effect.sync(() => {
+      const spec = buildDockerGitOpenApi()
+      const paths = spec.paths ?? {}
+
+      fc.assert(
+        fc.property(fc.constantFrom(...okOnlyOperations), (operation) => {
+          const responses = paths[operation.path]?.[operation.method]?.responses ?? {}
+          const serializedSuccessSchema = JSON.stringify(responses["200"] ?? {})
+
+          expect(responses["200"], `${operation.method.toUpperCase()} ${operation.path}`).toBeDefined()
+          expect(responses["204"], `${operation.method.toUpperCase()} ${operation.path}`).toBeUndefined()
+          expect(serializedSuccessSchema).toContain("\"required\":[\"ok\"]")
+          expect(serializedSuccessSchema).toContain("\"ok\":{\"type\":\"boolean\",\"enum\":[true]}")
+        }),
+        { numRuns: okOnlyOperations.length * 2 }
+      )
+    }))
+
   it.effect("documents project auth snapshots without nonexistent totalEntries", () =>
     Effect.sync(() => {
       const spec = buildDockerGitOpenApi()

packages/api/tests/openapi.test.ts

@@ -79,6 +79,7 @@
     "@effect/workflow": "^0.18.2",
     "@gridland/bun": "0.4.3",
     "@gridland/web": "0.4.3",
+    "@prover-coder-ai/docker-git-openapi": "workspace:*",
     "@prover-coder-ai/docker-git-session-sync": "workspace:*",
     "effect": "^3.21.3",
     "react": "19.2.4",
@@ -95,7 +96,6 @@
     "@eslint/compat": "2.1.0",
     "@eslint/eslintrc": "3.3.5",
     "@eslint/js": "10.0.1",
-    "@prover-coder-ai/docker-git-openapi": "workspace:*",
     "@prover-coder-ai/docker-git-terminal": "workspace:*",
     "@prover-coder-ai/eslint-plugin-suggest-members": "^0.0.26",
     "@ton-ai-core/vibecode-linter": "^1.0.11",

packages/app/package.json

@@ -1,14 +1,24 @@
 import type { Effect } from "effect"
 
 import {
+  type BaseCreateProjectBody,
   baseCreateProjectBody,
   type CreateProjectRequestDraft,
-  optionalProjectResourceFields
+  optionalProjectResourceFields,
+  type OptionalProjectResourceFieldsBody
 } from "./api-project-create-body.js"
 import { CreateProjectAcceptedResponseSchema } from "./api-schema.js"
 import type { CreateProjectAcceptedResponse } from "./api-schema.js"
 import { openApiJsonSchema } from "./openapi-client.js"
 
+type CreateProjectAcceptedBody = Readonly<
+  & BaseCreateProjectBody
+  & OptionalProjectResourceFieldsBody
+  & {
+    readonly async: true
+  }
+>
+
 /**
  * Builds the async POST /projects request body.
  *
@@ -23,7 +33,7 @@ import { openApiJsonSchema } from "./openapi-client.js"
  * @complexity O(1).
  * @throws Never.
  */
-export const createProjectAcceptedBody = (draft: CreateProjectRequestDraft) => ({
+export const createProjectAcceptedBody = (draft: CreateProjectRequestDraft): CreateProjectAcceptedBody => ({
   ...baseCreateProjectBody(draft),
   async: true,
   ...optionalProjectResourceFields(draft)

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

@@ -14,6 +14,48 @@ import type { CreateProjectDraft } from "./api-schema.js"
  */
 export type CreateProjectRequestDraft = CreateProjectDraft & ProjectResourceLimitRequest
 
+/**
+ * Optional resource-limit fragment serialized into POST /projects request bodies.
+ *
+ * @pure true - structural type contract only.
+ * @effect none
+ * @invariant present fields are defined strings; undefined inputs are omitted by optionalProjectResourceFields.
+ * @precondition callers construct this value through optionalProjectResourceFields.
+ * @postcondition spreading this fragment cannot add undefined Playwright limit fields.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export type OptionalProjectResourceFieldsBody = Readonly<{
+  readonly playwrightCpuLimit?: Exclude<ProjectResourceLimitRequest["playwrightCpuLimit"], undefined>
+  readonly playwrightRamLimit?: Exclude<ProjectResourceLimitRequest["playwrightRamLimit"], undefined>
+}>
+
+/**
+ * Common POST /projects request body shared by synchronous and asynchronous create flows.
+ *
+ * @pure true - structural type contract only.
+ * @effect none
+ * @invariant sync and async create flows share identical non-async fields.
+ * @precondition callers construct this value through baseCreateProjectBody.
+ * @postcondition openSsh is false and managed authorized keys are enabled for web-created projects.
+ * @complexity O(1).
+ * @throws Never.
+ */
+export type BaseCreateProjectBody = Readonly<{
+  readonly cpuLimit: CreateProjectDraft["cpuLimit"]
+  readonly enableMcpPlaywright: CreateProjectDraft["enableMcpPlaywright"]
+  readonly force: CreateProjectDraft["force"]
+  readonly forceEnv: CreateProjectDraft["forceEnv"]
+  readonly gpu: CreateProjectDraft["gpu"]
+  readonly openSsh: false
+  readonly outDir: CreateProjectDraft["outDir"]
+  readonly ramLimit: CreateProjectDraft["ramLimit"]
+  readonly repoRef: CreateProjectDraft["repoRef"]
+  readonly repoUrl: CreateProjectDraft["repoUrl"]
+  readonly up: CreateProjectDraft["up"]
+  readonly useManagedAuthorizedKeys: true
+}>
+
 /**
  * Serializes optional Playwright resource limits for project creation requests.
  *
@@ -28,7 +70,9 @@ export type CreateProjectRequestDraft = CreateProjectDraft & ProjectResourceLimi
  * @complexity O(1).
  * @throws Never.
  */
-export const optionalProjectResourceFields = (request: ProjectResourceLimitRequest) => ({
+export const optionalProjectResourceFields = (
+  request: ProjectResourceLimitRequest
+): OptionalProjectResourceFieldsBody => ({
   ...(request.playwrightCpuLimit !== undefined && { playwrightCpuLimit: request.playwrightCpuLimit }),
   ...(request.playwrightRamLimit !== undefined && { playwrightRamLimit: request.playwrightRamLimit })
 })
@@ -47,7 +91,7 @@ export const optionalProjectResourceFields = (request: ProjectResourceLimitReque
  * @complexity O(1).
  * @throws Never.
  */
-export const baseCreateProjectBody = (draft: CreateProjectDraft) => ({
+export const baseCreateProjectBody = (draft: CreateProjectDraft): BaseCreateProjectBody => ({
   cpuLimit: draft.cpuLimit,
   enableMcpPlaywright: draft.enableMcpPlaywright,
   force: draft.force,

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

@@ -17,7 +17,7 @@ const openApiRuntime = makeDockerGitOpenApiRuntime({
  * @complexity O(n)/O(n) for error rendering, O(1)/O(1) on local success handling.
  * @throws Never; failures are returned in the Effect error channel.
  */
-export const openApiJson = openApiRuntime.openApiJson
+export const openApiJson: typeof openApiRuntime.openApiJson = openApiRuntime.openApiJson
 
 /**
  * Executes a docker-git OpenAPI request and decodes the response with an Effect Schema.
@@ -30,7 +30,7 @@ export const openApiJson = openApiRuntime.openApiJson
  * @complexity O(n)/O(n) where n is the decoded response size.
  * @throws Never; failures are returned in the Effect error channel.
  */
-export const openApiJsonSchema = openApiRuntime.openApiJsonSchema
+export const openApiJsonSchema: typeof openApiRuntime.openApiJsonSchema = openApiRuntime.openApiJsonSchema
 
 /**
  * Executes a docker-git OpenAPI request whose success response has no body.
@@ -43,4 +43,4 @@ export const openApiJsonSchema = openApiRuntime.openApiJsonSchema
  * @complexity O(n)/O(n) for error rendering, O(1)/O(1) on local success handling.
  * @throws Never; failures are returned in the Effect error channel.
  */
-export const openApiVoid = openApiRuntime.openApiVoid
+export const openApiVoid: typeof openApiRuntime.openApiVoid = openApiRuntime.openApiVoid

packages/app/src/web/openapi-client.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "@effect/vitest"
 import { Effect } from "effect"
+import * as fc from "fast-check"
 
 import { createProjectAcceptedBody } from "../../src/web/api-create-project.js"
 import type { CreateProjectRequestDraft } from "../../src/web/api-project-create-body.js"
@@ -19,7 +20,41 @@ const projectDraft = {
   up: true
 } satisfies CreateProjectRequestDraft
 
+const hasOwnField = (value: object, key: string): boolean => Object.prototype.hasOwnProperty.call(value, key)
+const optionalPlaywrightLimitArbitrary = fc.option(fc.string(), { nil: undefined })
+
 describe("api create project request body", () => {
+  it.effect("preserves async create invariants for arbitrary Playwright resource limits", () =>
+    Effect.sync(() => {
+      fc.assert(
+        fc.property(
+          optionalPlaywrightLimitArbitrary,
+          optionalPlaywrightLimitArbitrary,
+          (playwrightCpuLimit, playwrightRamLimit) => {
+            const draft: CreateProjectRequestDraft = {
+              ...projectDraft,
+              playwrightCpuLimit,
+              playwrightRamLimit
+            }
+            const body = createProjectAcceptedBody(draft)
+
+            expect(body.async).toBe(true)
+            expect(body.openSsh).toBe(false)
+            expect(body.useManagedAuthorizedKeys).toBe(true)
+            expect(hasOwnField(body, "playwrightCpuLimit")).toBe(playwrightCpuLimit !== undefined)
+            expect(hasOwnField(body, "playwrightRamLimit")).toBe(playwrightRamLimit !== undefined)
+            if (playwrightCpuLimit !== undefined) {
+              expect(body.playwrightCpuLimit).toBe(playwrightCpuLimit)
+            }
+            if (playwrightRamLimit !== undefined) {
+              expect(body.playwrightRamLimit).toBe(playwrightRamLimit)
+            }
+          }
+        ),
+        { numRuns: 50 }
+      )
+    }))
+
   it.effect("serializes async create requests with Playwright resource limits", () =>
     Effect.sync(() => {
       expect(createProjectAcceptedBody(projectDraft)).toEqual({

packages/app/tests/docker-git/api-create-project.test.ts

@@ -79,6 +79,9 @@ describe("api terminal helpers", () => {
       const result = yield* _(Effect.either(deleteTerminalSessionByPath("/terminal-sessions/session-1")))
 
       expect(result._tag).toBe("Left")
+      if (result._tag === "Left") {
+        expect(result.left).toBe("Invalid terminal close path: /terminal-sessions/session-1")
+      }
       expect(capturedDeleteRequests).toEqual([])
     }))
 })