@thinkai/tai-api-contract 2.3.1 → 2.4.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.3.0
+  version: 2.4.1
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -48,6 +48,8 @@ tags:
     description: Per-user per-workspace preferences (§12)
   - name: OrgChartImport
     description: Org chart import via storage path (§14)
+  - name: AgenticFoundation
+    description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
 
 paths:
   /me:
@@ -1308,10 +1310,98 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/readiness/analyze:
+    post:
+      tags: [RepositoryReadiness]
+      summary: Enqueue AI readiness analysis for one repository
+      description: >
+        User-triggered "Run now" path. Requires workspace editor/admin access and an active GitHub App
+        connection. Prefer `repoId`; `providerSlug` is accepted for compatibility only when it resolves
+        to a repository in the workspace.
+      operationId: postReadinessAnalyze
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReadinessAnalyzeBodyDto"
+            examples:
+              byRepoId:
+                value:
+                  repoId: "11111111-1111-4111-8111-111111111111"
+              byProviderSlug:
+                value:
+                  providerSlug: "thinkai-llc/thinkai-platform-backend"
+      responses:
+        "202":
+          description: Run queued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReadinessAnalyzeResponseDto"
+        "400":
+          description: Invalid body, missing GitHub connection, unsupported provider, or active run conflict inputs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: A queued/running readiness analysis already exists for this repository slug
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/runs/{runId}:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Get readiness analysis run status
+      operationId: getReadinessRun
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: runId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Run status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReadinessRunSummaryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or run not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/repos/{repoId}:
     get:
       tags: [RepositoryReadiness]
       summary: Single repo readiness
+      description: >
+        Returns one stored repository scorecard with all eight dimensions and nested issues.
+        Unknown `repoId` or a repo that belongs to another workspace returns `404` (no cross-tenant leakage).
       operationId: getReadinessRepo
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1323,8 +1413,343 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "400":
+          description: Malformed `repoId` (not a UUID)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/dashboard:
+    get:
+      tags: [AgenticFoundation]
+      summary: Agentic Foundation dashboard
+      description: >
+        Returns stored repository readiness scorecards plus a flattened issue queue for the
+        Agentic Foundation dashboard surfaces. This is read-only and does not run scoring on
+        the request path (issue #279). Field `generatedAt` is the server timestamp when this JSON
+        payload was assembled; it is not the same as per-repo `lastAnalyzed` on `RepoReadinessScoreDto`.
+      operationId: getAgenticFoundationDashboard
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Dashboard scorecards and issue queue
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
+              examples:
+                emptyWorkspace:
+                  summary: No repos analyzed yet
+                  value:
+                    workspaceId: 00000000-0000-0000-0000-000000000001
+                    generatedAt: "2026-05-12T12:00:00.000Z"
+                    summary:
+                      repoCount: 0
+                      averageOverallScore: 0
+                      issueCount: 0
+                      criticalIssueCount: 0
+                    repos: []
+                    issueQueue: []
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/agentic-readiness:
+    get:
+      tags: [AgenticFoundation]
+      summary: Agentic readiness pillar (stored dimension slice)
+      description: >
+        Returns `RepoReadinessScoreDto` rows with only the `ai-agent-readiness` dimension populated
+        per repo. Same auth and persistence source as `GET .../readiness/repos` (issue #280).
+      operationId: getAgenticFoundationAgenticReadiness
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with ai-agent-readiness slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+              examples:
+                singleRepoSlice:
+                  summary: One repo, single pillar dimension
+                  value:
+                    - repoId: 00000000-0000-0000-0000-000000000002
+                      repoName: api-gateway
+                      language: typescript
+                      overallScore: 67
+                      dimensions:
+                        - dimensionId: ai-agent-readiness
+                          score: 2
+                          maxScore: 3
+                          issues: []
+                      lastAnalyzed: "2026-05-12T12:00:00.000Z"
+                      teamId: null
+                      provider:
+                        kind: github
+                        slug: acme/api-gateway
+                        webUrl: https://github.com/acme/api-gateway
+                        defaultBranch: main
+                        externalId: null
+                        hostBaseUrl: null
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/repository-health:
+    get:
+      tags: [AgenticFoundation]
+      summary: Repository health pillar (repo-hygiene slice)
+      description: Returns per-repo `repo-hygiene` dimension only (issue #281).
+      operationId: getAgenticFoundationRepositoryHealth
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with repo-hygiene slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/codebase-quality:
+    get:
+      tags: [AgenticFoundation]
+      summary: Codebase quality pillar (stack-quality slice)
+      description: Returns per-repo `stack-quality` dimension only (issue #282).
+      operationId: getAgenticFoundationCodebaseQuality
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with stack-quality slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/test-qa:
+    get:
+      tags: [AgenticFoundation]
+      summary: Test and QA pillar (tests-qa slice)
+      description: Returns per-repo `tests-qa` dimension only (issue #283).
+      operationId: getAgenticFoundationTestQa
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with tests-qa slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/observability:
+    get:
+      tags: [AgenticFoundation]
+      summary: Observability pillar (observability slice)
+      description: Returns per-repo `observability` dimension only (issue #284).
+      operationId: getAgenticFoundationObservability
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with observability slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/api-contract:
+    get:
+      tags: [AgenticFoundation]
+      summary: API contract pillar (api-contracts slice)
+      description: Returns per-repo `api-contracts` dimension only (issue #285).
+      operationId: getAgenticFoundationApiContract
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with api-contracts slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/platform-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Platform governance pillar (platform-governance slice)
+      description: Returns per-repo `platform-governance` dimension only (issue #286).
+      operationId: getAgenticFoundationPlatformGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with platform-governance slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/delivery-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Delivery governance pillar (delivery slice)
+      description: Returns per-repo `delivery` dimension only (issue #287).
+      operationId: getAgenticFoundationDeliveryGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with delivery slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/ai-resolution-hub:
+    get:
+      tags: [AgenticFoundation]
+      summary: AI resolution hub (full readiness scorecards)
+      description: >
+        Returns the same payload as `GET .../readiness/repos` (all dimensions per repo) for
+        cross-pillar hub views (issue #288).
+      operationId: getAgenticFoundationAiResolutionHub
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Full repository readiness scorecards
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/readiness/dimensions:
     get:
@@ -1710,6 +2135,7 @@ components:
       required: true
       schema:
         type: string
+        format: uuid
     ProjectId:
       name: projectId
       in: path
@@ -2482,6 +2908,67 @@ components:
           nullable: true
           description: Required for bitbucket_server (self-hosted); null for cloud providers
 
+    ReadinessAnalyzeBodyDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Prefer `repoId`; `providerSlug` exists for backwards-compatible callers and must resolve
+        to a repository in the workspace. Send exactly one of the two fields.
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        providerSlug:
+          type: string
+          minLength: 1
+          maxLength: 512
+          description: GitHub owner/repo slug; compatibility path only
+      oneOf:
+        - required: [repoId]
+        - required: [providerSlug]
+
+    ReadinessAnalyzeResponseDto:
+      type: object
+      required: [runId]
+      properties:
+        runId:
+          type: string
+          format: uuid
+
+    ReadinessRunStatusDto:
+      type: string
+      enum: [queued, running, succeeded, failed, partial_failed]
+
+    ReadinessRunSummaryDto:
+      type: object
+      required: [runId, status, providerSlug, errorCode, errorDetail, repoId, createdAt, finishedAt]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          $ref: "#/components/schemas/ReadinessRunStatusDto"
+        providerSlug:
+          type: string
+          maxLength: 512
+        errorCode:
+          type: string
+          nullable: true
+        errorDetail:
+          type: string
+          nullable: true
+        repoId:
+          type: string
+          format: uuid
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+
     ReadinessIssueDto:
       type: object
       required: [id, dimensionId, severity, title, description, fixStatus]
@@ -2557,6 +3044,80 @@ components:
         provider:
           $ref: "#/components/schemas/RepoProviderDto"
 
+    AgenticFoundationDashboardSummaryDto:
+      type: object
+      required: [repoCount, averageOverallScore, issueCount, criticalIssueCount]
+      properties:
+        repoCount:
+          type: integer
+          minimum: 0
+        averageOverallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+        issueCount:
+          type: integer
+          minimum: 0
+        criticalIssueCount:
+          type: integer
+          minimum: 0
+
+    AgenticFoundationDashboardIssueDto:
+      type: object
+      required:
+        [id, repoId, repoName, provider, dimensionId, severity, title, description, filePath, fixStatus]
+      properties:
+        id:
+          type: string
+          format: uuid
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+          maxLength: 256
+        provider:
+          $ref: "#/components/schemas/RepoProviderDto"
+        dimensionId:
+          $ref: "#/components/schemas/ReadinessDimensionId"
+        severity:
+          type: string
+          enum: [critical, high, medium, low]
+        title:
+          type: string
+          maxLength: 256
+        description:
+          type: string
+          maxLength: 2048
+        filePath:
+          type: string
+          maxLength: 512
+          nullable: true
+        fixStatus:
+          type: string
+          enum: [open, pr-pending, fixed]
+
+    AgenticFoundationDashboardDto:
+      type: object
+      required: [workspaceId, generatedAt, summary, repos, issueQueue]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        summary:
+          $ref: "#/components/schemas/AgenticFoundationDashboardSummaryDto"
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/RepoReadinessScoreDto"
+        issueQueue:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgenticFoundationDashboardIssueDto"
+
     FixRequestDto:
       type: object
       required: [id, issueId, repoId, repoName, issueTitle, dimensionId, severity, status, createdAt]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.3.1",
+  "version": "2.4.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",