@thinkai/tai-api-contract 2.28.0 → 3.1.0-pr.731.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.27.0
+  version: 3.1.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -2447,6 +2447,97 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/integrations/github-actions:
+    get:
+      tags: [Integrations]
+      summary: GitHub Actions CI integration status for workspace
+      operationId: getWorkspaceGithubActionsIntegrationStatus
+      description: >
+        Returns whether the workspace has explicitly enabled GitHub Actions CI metrics.
+        Requires GitHub App (source control) to be connected; does not use workspace `sources` PATs.
+        When GitHub is not connected, returns 200 with `githubConnected: false` and `enabled: false`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: GitHub Actions integration status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubActionsIntegrationStatusDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+    delete:
+      tags: [Integrations]
+      summary: Disable GitHub Actions CI integration
+      operationId: deleteWorkspaceGithubActionsIntegration
+      description: >
+        Disables GitHub Actions CI opt-in for the workspace. Does not disconnect GitHub source control.
+        Idempotent: returns 204 when already disabled.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: GitHub Actions integration disabled or was already absent
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github-actions/enable:
+    post:
+      tags: [Integrations]
+      summary: Enable GitHub Actions CI integration
+      operationId: postWorkspaceGithubActionsIntegrationEnable
+      description: >
+        Opts the workspace into GitHub Actions CI metrics using the existing GitHub App installation
+        (no separate OAuth or PAT). Returns `outcome: needs_github` when source control is not connected,
+        or `outcome: permissions_missing` when the installation lacks Actions read permission.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Enable result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubActionsEnableResponseDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: GitHub App not configured or smoke test failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /integrations/github/webhook:
     post:
       tags: [Integrations]
@@ -3122,6 +3213,25 @@ paths:
         - $ref: "#/components/parameters/PaginationLimit"
         - $ref: "#/components/parameters/PaginationOffset"
         - $ref: "#/components/parameters/PaginationOrder"
+        - name: sort
+          in: query
+          required: false
+          description: >
+            Server-side sort column (the activity "5 W's"). Combined with `order` (asc/desc).
+            Defaults to `when` (occurredAt). `occurredAt`/`id` is always the tiebreaker.
+          schema:
+            type: string
+            enum: [when, who, what, why, where]
+        - name: productArea
+          in: query
+          required: false
+          description: >
+            Coarse product-area grouping filter (#156). `integration` = GitHub + AI-tool key events;
+            `agentic_foundation` = repos, readiness scans, fixes; `workspace_team` = members + HRIS.
+            Omit (or pass `all`) for every area.
+          schema:
+            type: string
+            enum: [integration, agentic_foundation, workspace_team, all]
         - name: eventType
           in: query
           description: Filter to a specific event type.
@@ -3916,6 +4026,79 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/repo-eligibility:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Get repo-sync eligibility gate (defaults + per-workspace overrides)
+      description: >
+        Returns the effective repo-sync eligibility gate (archived / fork / size / count) for the
+        workspace: the global `defaults`, any per-workspace `overrides`, the merged `effective`
+        values, and whether the caller can edit without platform-admin (`canEditUnrestricted`).
+        Member-level read access.
+      operationId: getWorkspaceRepoEligibility
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Effective repo-eligibility configuration
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceRepoEligibilityDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    put:
+      tags: [RepositoryReadiness]
+      summary: Set per-workspace repo-sync eligibility overrides
+      description: >
+        Set (or clear, with an empty `overrides`) the per-workspace repo-sync eligibility overrides.
+        **Platform admins** may set any value (raise caps, `0` = unlimited, include archived/forks).
+        **Workspace admins** may only make the gate *more restrictive* than the platform defaults
+        (lower caps, exclude archived/forks) — exceeding a platform limit returns `403`
+        (`repo_eligibility_bound_exceeded`). Requires workspace admin or platform admin.
+      operationId: putWorkspaceRepoEligibility
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [overrides]
+              properties:
+                overrides:
+                  $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+      responses:
+        "200":
+          description: Overrides saved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [overrides, effective]
+                properties:
+                  overrides:
+                    $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+                  effective:
+                    $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Forbidden, or a workspace-admin value exceeds a platform limit (`repo_eligibility_bound_exceeded`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/cursor-key-usage:
     get:
       tags: [RepositoryReadiness]
@@ -4622,7 +4805,7 @@ paths:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Sync completed successfully
+          description: Sync completed successfully for all configured HRIS providers
           content:
             application/json:
               schema:
@@ -4632,6 +4815,12 @@ paths:
                 employeeCount: 42
                 absenceCount: 7
                 durationMs: 1234
+                providers:
+                  - provider: personio
+                    status: ok
+                    employeeCount: 42
+                    absenceCount: 7
+                    durationMs: 1234
         "422":
           description: No HRIS source configured for this workspace
           content:
@@ -4640,10 +4829,10 @@ paths:
                 $ref: "#/components/schemas/HrisTriggerSyncResultDto"
               example:
                 status: skipped
-                code: no_personio_source
-                reason: no_personio_source
+                code: no_hris_source
+                reason: no_hris_source
         "500":
-          description: Sync failed (Personio API error, decryption failure, etc.)
+          description: Sync failed for one or more HRIS providers
           content:
             application/json:
               schema:
@@ -4651,7 +4840,7 @@ paths:
               example:
                 status: error
                 code: hris_sync_failed
-                error: "Personio employees API 401"
+                error: "ZenHR token refresh failed (401)"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -6611,6 +6800,123 @@ components:
           format: date-time
           nullable: true
           description: Last push or metadata update from GitHub when available.
+        archived:
+          type: boolean
+          nullable: true
+          description: True when the repository is archived (read-only on GitHub).
+        fork:
+          type: boolean
+          nullable: true
+          description: True when the repository is a fork of another repository.
+        disabled:
+          type: boolean
+          nullable: true
+          description: True when the repository is disabled on GitHub.
+        size:
+          type: integer
+          nullable: true
+          description: Repository size in KB as reported by GitHub.
+        readOnly:
+          type: boolean
+          nullable: true
+          description: >
+            True when the GitHub App installation lacks push access to this repo
+            (read-only). Read-only repos are rejected during sync because readiness
+            fixes require write access.
+        ineligibleReason:
+          type: string
+          nullable: true
+          description: >
+            Set when this repo was skipped during sync due to an eligibility check.
+            The frontend should display this as an inline explanation (e.g. "This repo is archived").
+        eligibilityStatus:
+          type: string
+          enum: [eligible, ineligible]
+          nullable: true
+          description: >
+            Language-based eligibility for Agentic-Foundation readiness analysis (issue #44).
+            `ineligible` repos (no supported stack) render read-only/orange in the AF list with
+            no analyze/score/fix actions. Mixed monorepos with a supported secondary stack are
+            `eligible`. Distinct from `ineligibleReason`, which reflects the structural sync gate.
+        eligibilityReason:
+          type: string
+          nullable: true
+          description: >
+            Human-readable explanation when `eligibilityStatus` is `ineligible`
+            (e.g. "This repository's primary language (Python) is not supported in v1").
+        primaryStack:
+          type: string
+          nullable: true
+          description: >
+            Dominant supported stack (by GitHub language bytes), one of
+            backend_jvm | ios_app | web_spa | backend_go. Null for ineligible repos.
+        secondaryStack:
+          type: string
+          nullable: true
+          description: Second supported stack for a multi-stack repo, or null.
+        supportedStacks:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: >
+            All supported stacks detected for the repo (ordered, primary first). Empty/null
+            when no supported stack is present. Drives multi-stack scanning and the orange
+            mixed-monorepo box in the AF UI.
+
+    RepoEligibilityConfigDto:
+      type: object
+      description: Resolved repo-sync eligibility gate (defaults or effective). All fields present.
+      required: [excludeArchived, excludeForks, maxRepoSizeKb, maxReposPerWorkspace]
+      properties:
+        excludeArchived:
+          type: boolean
+          description: Skip archived repos during GitHub repo sync.
+        excludeForks:
+          type: boolean
+          description: Skip forked repos. Forks are included by default.
+        maxRepoSizeKb:
+          type: integer
+          description: Max repo size in KB (GitHub-reported). 0 = no limit.
+        maxReposPerWorkspace:
+          type: integer
+          description: Max repos materialized per workspace per sync. 0 = no limit.
+
+    RepoEligibilityOverridesDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Per-workspace overrides for the repo-sync eligibility gate. Any field present wins over the
+        global default; omit a field to inherit the default. An empty object clears all overrides.
+      properties:
+        excludeArchived:
+          type: boolean
+          nullable: true
+        excludeForks:
+          type: boolean
+          nullable: true
+        maxRepoSizeKb:
+          type: integer
+          minimum: 0
+          nullable: true
+        maxReposPerWorkspace:
+          type: integer
+          minimum: 0
+          nullable: true
+
+    WorkspaceRepoEligibilityDto:
+      type: object
+      required: [defaults, overrides, effective, canEditUnrestricted]
+      properties:
+        defaults:
+          $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        overrides:
+          $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+        effective:
+          $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        canEditUnrestricted:
+          type: boolean
+          description: True when the caller is a platform admin (may set any value, incl. raising caps).
 
     GithubMissingPermissionDto:
       type: object
@@ -6682,6 +6988,75 @@ components:
           format: date-time
           description: When the pending install request was recorded.
 
+    GithubActionsWorkflowPreviewDto:
+      type: object
+      additionalProperties: false
+      properties:
+        workflows:
+          type: integer
+          minimum: 0
+          description: Approximate workflow count from recent API sample (best effort).
+        runsThisWeek:
+          type: integer
+          minimum: 0
+          description: Workflow runs in the trailing 7 days from sample repo (best effort).
+
+    GithubActionsIntegrationStatusDto:
+      type: object
+      additionalProperties: false
+      required: [enabled, githubConnected, permissionsOk]
+      properties:
+        enabled:
+          type: boolean
+          description: True when the workspace admin explicitly enabled GitHub Actions CI.
+        githubConnected:
+          type: boolean
+          description: True when at least one GitHub App VCS installation is linked.
+        permissionsOk:
+          type: boolean
+          description: False when GitHub App installation lacks Actions read permission.
+        permissionsUpgradeRequired:
+          type: boolean
+          description: Alias for `!permissionsOk` when GitHub is connected.
+        missingPermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+        manageUrl:
+          type: string
+          format: uri
+          nullable: true
+          description: GitHub installation settings URL for permission approval.
+        lastSyncAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Last productivity ingest timestamp when CI is enabled.
+        workflowPreview:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/GithubActionsWorkflowPreviewDto"
+        error:
+          type: string
+          nullable: true
+          description: Last enable or status error message when applicable.
+
+    GithubActionsEnableResponseDto:
+      type: object
+      additionalProperties: false
+      required: [outcome]
+      properties:
+        outcome:
+          type: string
+          enum: [enabled, needs_github, permissions_missing, error]
+        status:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/GithubActionsIntegrationStatusDto"
+        error:
+          type: string
+          nullable: true
+
     GithubInstallationStatusDto:
       type: object
       required: [installed, installations, permissionsUpgradeRequired]
@@ -7230,6 +7605,11 @@ components:
           type: string
           enum: [high, medium, low]
           description: Rubric-defined severity for this criterion
+        summary:
+          type: string
+          maxLength: 120
+          nullable: true
+          description: Plain-language explanation of what this check means (from rubric, not LLM)
         notes:
           type: string
           maxLength: 2048
@@ -7564,6 +7944,33 @@ components:
           nullable: true
           enum: [github_removed, installation_disconnected, installation_replaced, superseded, null]
           description: Why the repo was archived. Only present when `archivedAt` is set.
+        eligibilityStatus:
+          type: string
+          enum: [eligible, ineligible]
+          nullable: true
+          description: >
+            Language-based eligibility for Agentic-Foundation analysis (#44). `ineligible` repos
+            (no v1-supported stack) render read-only/orange in the AF list with no analyze/score/fix
+            actions; the server also rejects analyze requests for them. Null until the first
+            sync/scan computes it.
+        eligibilityReason:
+          type: string
+          nullable: true
+          description: Human-readable explanation when `eligibilityStatus` is `ineligible`.
+        primaryStack:
+          type: string
+          nullable: true
+          description: Dominant supported stack — backend_jvm | ios_app | web_spa | backend_go. Null when ineligible/uncomputed.
+        secondaryStack:
+          type: string
+          nullable: true
+          description: Second supported stack for a multi-stack repo, or null.
+        supportedStacks:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: All supported stacks detected (ordered, primary first). Empty/null when none.
 
     RepoReadinessScoreDetailDto:
       type: object
@@ -8638,18 +9045,29 @@ components:
         - readiness.scan_completed
         - readiness.scan_failed
         - readiness.scan_partial
-        - config.cursor.added
-        - config.cursor.updated
-        - config.cursor.removed
-        - config.cursor.platform_key_enabled
-        - config.cursor.platform_key_disabled
-        - config.claude.added
-        - config.claude.updated
-        - config.claude.removed
-        - config.agent_execution.provider_changed
+        - integrations.agent_execution.provider_changed
+        - integrations.repo_eligibility.overrides_changed
+        - integrations.cursor.platform_key_enabled
+        - integrations.cursor.platform_key_disabled
         - member.invited
         - member.role_changed
         - member.removed
+        - repo.sync_skipped
+        - integrations.cursor.execution_key.added
+        - integrations.cursor.execution_key.updated
+        - integrations.cursor.execution_key.removed
+        - integrations.cursor.execution_key.check_failed
+        - integrations.cursor.admin_key.added
+        - integrations.cursor.admin_key.updated
+        - integrations.cursor.admin_key.removed
+        - integrations.claude.execution_key.added
+        - integrations.claude.execution_key.updated
+        - integrations.claude.execution_key.removed
+        - integrations.claude.execution_key.check_failed
+        - integrations.claude.admin_key.added
+        - integrations.claude.admin_key.updated
+        - integrations.claude.admin_key.removed
+        - readiness.scan_precheck_failed
 
     ActivityLogActorDto:
       type: object
@@ -8797,25 +9215,49 @@ components:
       properties:
         status:
           type: string
-          enum: [ok, skipped, error]
+          enum: [ok, skipped, error, partial]
         code:
           type: string
-          description: Stable machine-readable code (e.g. 'no_personio_source', 'hris_sync_failed').
+          description: Stable machine-readable code (e.g. 'no_hris_source', 'hris_sync_failed').
         employeeCount:
           type: integer
-          description: Number of employees synced (present when status = 'ok').
+          description: Employees synced across successful providers (when status = ok or partial).
         absenceCount:
           type: integer
-          description: Number of absence records synced (present when status = 'ok').
+          description: Absence rows synced across successful providers.
         durationMs:
           type: integer
-          description: Wall-clock duration of the sync in milliseconds (present when status = 'ok').
+          description: Wall-clock duration of the sync in milliseconds.
         reason:
           type: string
-          description: Machine-readable reason for a skipped sync (e.g. 'no_personio_source').
+          description: Machine-readable reason for a skipped sync (e.g. 'no_hris_source').
+        error:
+          type: string
+          description: Error message when status = error, or first provider failure when partial.
+        providers:
+          type: array
+          description: Per-provider sync outcomes when one or more HRIS sources are configured.
+          items:
+            $ref: "#/components/schemas/HrisProviderSyncResultDto"
+
+    HrisProviderSyncResultDto:
+      type: object
+      required: [provider, status]
+      properties:
+        provider:
+          type: string
+          description: HRIS provider identifier (personio, zenhr, …).
+        status:
+          type: string
+          enum: [ok, error]
+        employeeCount:
+          type: integer
+        absenceCount:
+          type: integer
+        durationMs:
+          type: integer
         error:
           type: string
-          description: Error message when status = 'error'.
 
     ActivityLogPageDto:
       allOf:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.28.0",
+  "version": "3.1.0-pr.731.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -21,9 +21,10 @@
   "dependencies": {},
   "devDependencies": {
     "@stoplight/spectral-cli": "^6.15.1",
+    "@types/node": "^25.9.1",
     "jsonpath-plus": "^10.3.0",
     "openapi-typescript": "^7.13.0",
-    "typescript": "~5.3.0"
+    "typescript": "~6.0.3"
   },
   "files": [
     "dist",