@foundation0/git 1.3.0 → 1.3.1

package/src/ci-api.ts

@@ -1,544 +1,544 @@
-import type { GitApiFeatureMapping } from './platform/gitea-adapter'
-import type { GitPlatformConfig } from './platform/config'
-import type { GitServiceApi, GitServiceApiExecutionResult } from './git-service-api'
-
-type CiApiDefaults = {
-  defaultOwner?: string
-  defaultRepo?: string
-}
-
-export type GitCiApiContext = {
-  config: GitPlatformConfig
-  defaults: CiApiDefaults
-  requestTimeoutMs: number
-  log?: (message: string) => void
-}
-
-type NormalizedCall = {
-  args: string[]
-  options: Record<string, unknown>
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
-const toTrimmedString = (value: unknown): string =>
-  value === null || value === undefined ? '' : String(value).trim()
-
-const toPositiveInteger = (value: unknown): number | null => {
-  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
-    return Math.floor(value)
-  }
-
-  if (typeof value !== 'string') return null
-  const trimmed = value.trim()
-  if (!trimmed) return null
-  const parsed = Number(trimmed)
-  if (!Number.isFinite(parsed) || parsed <= 0) return null
-  return Math.floor(parsed)
-}
-
-const splitArgsAndOptions = (rawArgs: unknown[]): NormalizedCall => {
-  if (rawArgs.length === 0 || !isRecord(rawArgs[rawArgs.length - 1])) {
-    return {
-      args: rawArgs.map((value) => String(value)),
-      options: {},
-    }
-  }
-
-  const last = rawArgs[rawArgs.length - 1] as Record<string, unknown>
-  return {
-    args: rawArgs.slice(0, -1).map((value) => String(value)),
-    options: last,
-  }
-}
-
-const buildApiBase = (host: string): string => {
-  const sanitizedHost = host.replace(/\/$/, '')
-  if (sanitizedHost.endsWith('/api/v1')) {
-    return sanitizedHost
-  }
-  return `${sanitizedHost}/api/v1`
-}
-
-const toQueryArray = (query: Record<string, string | number | boolean>): string[] =>
-  Object.entries(query).map(([key, value]) => `${key}=${value}`)
-
-const toHeaderRecord = (headers: string[]): Record<string, string> =>
-  Object.fromEntries(
-    headers
-      .map((entry) => {
-        const separatorIndex = entry.indexOf(':')
-        if (separatorIndex < 0) return null
-        const name = entry.slice(0, separatorIndex).trim()
-        const value = entry.slice(separatorIndex + 1).trim()
-        return [name, value]
-      })
-      .filter((entry): entry is [string, string] => Boolean(entry)),
-  )
-
-const fetchJson = async (
-  ctx: GitCiApiContext,
-  path: string[],
-  query: Record<string, string | number | boolean> = {},
-): Promise<{ status: number; ok: boolean; headers: Record<string, string>; body: unknown; url: string }> => {
-  const apiBase = buildApiBase(ctx.config.giteaHost)
-  const url = new URL(`${apiBase}/${path.join('/')}`)
-  for (const [key, value] of Object.entries(query)) {
-    url.searchParams.set(key, String(value))
-  }
-
-  const headersList: string[] = []
-  headersList.push('Accept: application/json')
-  if (ctx.config.giteaToken) {
-    headersList.push(`Authorization: token ${ctx.config.giteaToken}`)
-  }
-
-  ctx.log?.(`ci:http:request GET ${url.toString()}`)
-  const response = await fetch(url.toString(), { headers: toHeaderRecord(headersList) })
-  const responseHeaders: Record<string, string> = {}
-  try {
-    response.headers.forEach((value, key) => {
-      responseHeaders[key.toLowerCase()] = value
-    })
-  } catch {
-    // best effort
-  }
-
-  const contentType = response.headers.get('content-type') ?? ''
-  const text = await response.text().catch(() => '')
-  let parsed: unknown = text
-  if (contentType.toLowerCase().includes('application/json')) {
-    try {
-      parsed = JSON.parse(text)
-    } catch {
-      parsed = text
-    }
-  }
-
-  ctx.log?.(`ci:http:response GET ${url.toString()} -> ${response.status}`)
-  return {
-    status: response.status,
-    ok: response.ok,
-    headers: responseHeaders,
-    body: parsed,
-    url: url.toString(),
-  }
-}
-
-const resolveOwnerRepo = (
-  scope: { owner?: string; repo?: string },
-  defaults: CiApiDefaults,
-): { owner: string; repo: string } => {
-  const owner = scope.owner ?? defaults.defaultOwner
-  const repo = scope.repo ?? defaults.defaultRepo
-
-  if (!owner || !repo) {
-    throw new Error(
-      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
-    )
-  }
-
-  return { owner, repo }
-}
-
-type NormalizedCheckState = 'success' | 'failure' | 'pending'
-
-const normalizeGiteaStatusState = (raw: unknown): NormalizedCheckState => {
-  const value = toTrimmedString(raw).toLowerCase()
-  if (value === 'success') return 'success'
-  if (value === 'pending') return 'pending'
-  if (value === 'failure') return 'failure'
-  if (value === 'failed') return 'failure'
-  if (value === 'error') return 'failure'
-  if (value === 'cancelled' || value === 'canceled') return 'failure'
-  if (value === 'skipped') return 'success'
-  if (value === 'running' || value === 'in_progress' || value === 'queued' || value === 'waiting') return 'pending'
-  return 'pending'
-}
-
-const summarizeOverall = (states: NormalizedCheckState[]) => {
-  const total = states.length
-  const failed = states.filter((state) => state === 'failure').length
-  const pending = states.filter((state) => state === 'pending').length
-  const successful = states.filter((state) => state === 'success').length
-
-  const state: NormalizedCheckState =
-    failed > 0 ? 'failure' : pending > 0 ? 'pending' : total > 0 ? 'success' : 'success'
-
-  return { state, total, failed, pending, successful }
-}
-
-const listWorkflowFiles = async (
-  ctx: GitCiApiContext,
-  owner: string,
-  repo: string,
-): Promise<Array<{ id: string; name: string; path: string; state: string; url?: string; html_url?: string }>> => {
-  const directories = ['.gitea/workflows', '.github/workflows']
-  const workflows: Array<{ id: string; name: string; path: string; state: string; url?: string; html_url?: string }> = []
-
-  for (const directory of directories) {
-    const response = await fetchJson(ctx, ['repos', owner, repo, 'contents', directory])
-    if (!response.ok) {
-      continue
-    }
-
-    if (!Array.isArray(response.body)) {
-      continue
-    }
-
-    for (const entry of response.body) {
-      if (!isRecord(entry)) continue
-      const type = toTrimmedString(entry.type).toLowerCase()
-      if (type !== 'file') continue
-      const name = toTrimmedString(entry.name)
-      if (!name.toLowerCase().endsWith('.yml') && !name.toLowerCase().endsWith('.yaml')) continue
-      const path = toTrimmedString(entry.path) || `${directory}/${name}`
-
-      workflows.push({
-        id: path,
-        name,
-        path,
-        state: 'active',
-        ...(typeof entry.url === 'string' ? { url: entry.url } : {}),
-        ...(typeof entry.html_url === 'string' ? { html_url: entry.html_url } : {}),
-      })
-    }
-  }
-
-  const unique = new Map<string, { id: string; name: string; path: string; state: string; url?: string; html_url?: string }>()
-  for (const workflow of workflows) {
-    unique.set(workflow.id, workflow)
-  }
-  return [...unique.values()]
-}
-
-export const attachGitCiApi = (api: GitServiceApi, ctx: GitCiApiContext): void => {
-  const prChecks = async (...rawArgs: unknown[]): Promise<GitServiceApiExecutionResult> => {
-    if (ctx.config.platform !== 'GITEA') {
-      throw new Error(`pr.checks only supports GITEA platform, got ${ctx.config.platform}`)
-    }
-
-    const parsed = splitArgsAndOptions(rawArgs)
-    const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
-    const options = parsed.options
-
-    let owner: string | undefined
-    let repo: string | undefined
-    let prNumber: number | null = null
-
-    if (args.length >= 3) {
-      owner = args[0]
-      repo = args[1]
-      prNumber = toPositiveInteger(args[2])
-    } else if (args.length === 2) {
-      if (args[0].includes('/')) {
-        const split = args[0].split('/')
-        if (split.length === 2 && split[0] && split[1]) {
-          owner = split[0]
-          repo = split[1]
-          prNumber = toPositiveInteger(args[1])
-        }
-      }
-    } else if (args.length === 1) {
-      prNumber = toPositiveInteger(args[0])
-    }
-
-    if (!prNumber) {
-      prNumber = toPositiveInteger(
-        (options.prNumber ?? options.pr_number ?? options.number ?? options.pull ?? options.pull_number) as unknown,
-      )
-    }
-
-    if (!owner) {
-      owner = typeof options.owner === 'string' ? options.owner : undefined
-    }
-
-    if (!repo) {
-      repo = typeof options.repo === 'string' ? options.repo : undefined
-    }
-
-    const scope = resolveOwnerRepo({ owner, repo }, ctx.defaults)
-
-    if (!prNumber) {
-      throw new Error('PR number is required.')
-    }
-
-    const prResponse = await fetchJson(ctx, ['repos', scope.owner, scope.repo, 'pulls', String(prNumber)])
-    if (!prResponse.ok) {
-      return {
-        mapping: {
-          platform: 'GITEA',
-          featurePath: ['pr', 'checks'],
-          mappedPath: ['repos', scope.owner, scope.repo, 'pulls', String(prNumber)],
-          method: 'GET',
-          query: [],
-          headers: [],
-          apiBase: buildApiBase(ctx.config.giteaHost),
-          swaggerPath: '/repos/{owner}/{repo}/pulls/{index}',
-          mapped: true,
-          reason: 'Fetch PR for checks computation',
-        },
-        request: {
-          url: prResponse.url,
-          method: 'GET',
-          headers: {},
-          query: [],
-        },
-        response: {
-          headers: prResponse.headers,
-        },
-        status: prResponse.status,
-        ok: prResponse.ok,
-        body: prResponse.body,
-      }
-    }
-
-    const prBody = prResponse.body
-    const head = isRecord(prBody) ? prBody.head : null
-    const headSha =
-      toTrimmedString(isRecord(head) ? head.sha : null) ||
-      toTrimmedString(isRecord(prBody) ? prBody.head_sha : null) ||
-      toTrimmedString(isRecord(prBody) ? prBody.headSha : null)
-    const headBranch =
-      toTrimmedString(isRecord(head) ? head.ref : null) ||
-      toTrimmedString(isRecord(prBody) ? prBody.head_branch : null) ||
-      toTrimmedString(isRecord(prBody) ? prBody.headBranch : null)
-
-    if (!headSha) {
-      throw new Error('Unable to determine PR head SHA from pull request response.')
-    }
-
-    const [tasksResponse, statusesResponse] = await Promise.all([
-      fetchJson(ctx, ['repos', scope.owner, scope.repo, 'actions', 'tasks'], { limit: 50 }),
-      fetchJson(ctx, ['repos', scope.owner, scope.repo, 'statuses', headSha]),
-    ])
-
-    const actionRuns =
-      isRecord(tasksResponse.body) && Array.isArray(tasksResponse.body.workflow_runs)
-        ? (tasksResponse.body.workflow_runs as unknown[])
-        : []
-
-    const actionChecks = actionRuns
-      .filter((entry) => isRecord(entry))
-      .filter((entry) => toTrimmedString((entry as Record<string, unknown>).head_sha) === headSha)
-      .map((entry) => {
-        const record = entry as Record<string, unknown>
-        const state = normalizeGiteaStatusState(record.status)
-        const name =
-          toTrimmedString(record.name) ||
-          toTrimmedString(record.display_title) ||
-          toTrimmedString(record.workflow_id) ||
-          `run:${toTrimmedString(record.id)}`
-        const detailsUrl = toTrimmedString(record.url)
-        const runNumber = toPositiveInteger(record.run_number)
-        const jobId = toTrimmedString(record.id)
-        return {
-          source: 'actions' as const,
-          name,
-          state,
-          ...(detailsUrl ? { details_url: detailsUrl } : {}),
-          ...(runNumber ? { run_number: runNumber } : {}),
-          ...(jobId ? { job_id: jobId } : {}),
-          ...(typeof record.updated_at === 'string' ? { updated_at: record.updated_at } : {}),
-        }
-      })
-
-    const combinedState = isRecord(statusesResponse.body) ? normalizeGiteaStatusState(statusesResponse.body.state) : null
-    const commitStatuses =
-      isRecord(statusesResponse.body) && Array.isArray(statusesResponse.body.statuses)
-        ? (statusesResponse.body.statuses as unknown[])
-        : []
-
-    const statusChecks = commitStatuses
-      .filter((entry) => isRecord(entry))
-      .map((entry) => {
-        const record = entry as Record<string, unknown>
-        const name =
-          toTrimmedString(record.context) ||
-          toTrimmedString(record.name) ||
-          toTrimmedString(record.id) ||
-          'status'
-        const state = normalizeGiteaStatusState(record.status ?? record.state)
-        const detailsUrl = toTrimmedString(record.target_url ?? record.targetUrl)
-        return {
-          source: 'status' as const,
-          name,
-          state,
-          ...(detailsUrl ? { details_url: detailsUrl } : {}),
-          ...(typeof record.description === 'string' ? { description: record.description } : {}),
-          ...(typeof record.updated_at === 'string' ? { updated_at: record.updated_at } : {}),
-          ...(typeof record.created_at === 'string' ? { created_at: record.created_at } : {}),
-        }
-      })
-
-    const checks = [...actionChecks, ...statusChecks]
-    const states = checks.map((check) => check.state)
-    const overallBase = summarizeOverall(states)
-    const overall =
-      checks.length === 0 && (!tasksResponse.ok || !statusesResponse.ok)
-        ? { ...overallBase, state: 'pending' as const }
-        : overallBase
-
-    const body = {
-      pr: {
-        number: prNumber,
-        headSha,
-        ...(headBranch ? { headBranch } : {}),
-        ...(isRecord(prBody) && typeof prBody.html_url === 'string' ? { url: prBody.html_url } : {}),
-        ...(isRecord(prBody) && typeof prBody.title === 'string' ? { title: prBody.title } : {}),
-      },
-      overall: {
-        ...overall,
-        ...(combinedState ? { combined_state: combinedState } : {}),
-        ...(tasksResponse.ok ? {} : { actions_error: tasksResponse.body }),
-        ...(statusesResponse.ok ? {} : { statuses_error: statusesResponse.body }),
-      },
-      checks,
-      meta: {
-        actions_total_count: isRecord(tasksResponse.body) ? tasksResponse.body.total_count : undefined,
-      },
-    }
-
-    const mapping: GitApiFeatureMapping = {
-      platform: 'GITEA',
-      featurePath: ['pr', 'checks'],
-      mappedPath: ['repos', scope.owner, scope.repo, 'pulls', String(prNumber), 'checks'],
-      method: 'GET',
-      query: [],
-      headers: [],
-      apiBase: buildApiBase(ctx.config.giteaHost),
-      swaggerPath: '/repos/{owner}/{repo}/pulls/{index} + /actions/tasks + /statuses/{sha}',
-      mapped: true,
-      reason: 'Computed PR checks from actions tasks and commit statuses',
-    }
-
-    return {
-      mapping,
-      request: {
-        url: 'computed://repo/pr/checks',
-        method: 'GET',
-        headers: {},
-        query: [],
-      },
-      response: { headers: {} },
-      status: 200,
-      ok: true,
-      body,
-    }
-  }
-
-  const workflowList = async (...rawArgs: unknown[]): Promise<GitServiceApiExecutionResult> => {
-    if (ctx.config.platform !== 'GITEA') {
-      throw new Error(`workflow.list only supports GITEA platform, got ${ctx.config.platform}`)
-    }
-
-    const parsed = splitArgsAndOptions(rawArgs)
-    const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
-    const options = parsed.options
-
-    let owner: string | undefined
-    let repo: string | undefined
-
-    if (args.length >= 2) {
-      owner = args[0]
-      repo = args[1]
-    } else if (args.length === 1 && args[0].includes('/')) {
-      const split = args[0].split('/')
-      if (split.length === 2 && split[0] && split[1]) {
-        owner = split[0]
-        repo = split[1]
-      }
-    }
-
-    if (!owner) {
-      owner = typeof options.owner === 'string' ? options.owner : undefined
-    }
-    if (!repo) {
-      repo = typeof options.repo === 'string' ? options.repo : undefined
-    }
-
-    const scope = resolveOwnerRepo({ owner, repo }, ctx.defaults)
-
-    const apiResponse = await fetchJson(ctx, ['repos', scope.owner, scope.repo, 'actions', 'workflows'])
-
-    const workflowsFromApi =
-      isRecord(apiResponse.body) && Array.isArray(apiResponse.body.workflows)
-        ? (apiResponse.body.workflows as unknown[])
-        : []
-
-    if (apiResponse.ok && workflowsFromApi.length > 0) {
-      return {
-        mapping: {
-          platform: 'GITEA',
-          featurePath: ['workflow', 'list'],
-          mappedPath: ['repos', scope.owner, scope.repo, 'actions', 'workflows'],
-          method: 'GET',
-          query: [],
-          headers: [],
-          apiBase: buildApiBase(ctx.config.giteaHost),
-          swaggerPath: '/repos/{owner}/{repo}/actions/workflows',
-          mapped: true,
-          reason: 'Gitea actions workflows API',
-        },
-        request: {
-          url: apiResponse.url,
-          method: 'GET',
-          headers: {},
-          query: [],
-        },
-        response: { headers: apiResponse.headers },
-        status: apiResponse.status,
-        ok: apiResponse.ok,
-        body: apiResponse.body,
-      }
-    }
-
-    const fallbackWorkflows = await listWorkflowFiles(ctx, scope.owner, scope.repo)
-    const fallbackBody = {
-      total_count: fallbackWorkflows.length,
-      workflows: fallbackWorkflows,
-      ...(apiResponse.ok ? {} : { api_error: apiResponse.body }),
-    }
-
-    return {
-      mapping: {
-        platform: 'GITEA',
-        featurePath: ['workflow', 'list'],
-        mappedPath: ['repos', scope.owner, scope.repo, 'actions', 'workflows'],
-        method: 'GET',
-        query: [],
-        headers: [],
-        apiBase: buildApiBase(ctx.config.giteaHost),
-        swaggerPath: '/repos/{owner}/{repo}/actions/workflows',
-        mapped: true,
-        reason: 'Fallback to repository workflow files when API returns empty',
-      },
-      request: {
-        url: apiResponse.url,
-        method: 'GET',
-        headers: {},
-        query: [],
-      },
-      response: { headers: apiResponse.headers },
-      status: apiResponse.ok ? 200 : apiResponse.status,
-      ok: true,
-      body: fallbackBody,
-    }
-  }
-
-  const root = api as Record<string, any>
-
-  // Override "workflow.list" if the platform adapter returns an empty list in Gitea environments.
-  root.workflow ??= {}
-  root.workflow.list = workflowList
-  root.repo ??= {}
-  root.repo.workflow ??= {}
-  root.repo.workflow.list = workflowList
-
-  // Override "pr.checks" to return a CI-friendly summary with per-check states.
-  root.pr ??= {}
-  root.pr.checks = prChecks
-  root.repo.pr ??= {}
-  root.repo.pr.checks = prChecks
-}
+import type { GitApiFeatureMapping } from './platform/gitea-adapter'
+import type { GitPlatformConfig } from './platform/config'
+import type { GitServiceApi, GitServiceApiExecutionResult } from './git-service-api'
+
+type CiApiDefaults = {
+  defaultOwner?: string
+  defaultRepo?: string
+}
+
+export type GitCiApiContext = {
+  config: GitPlatformConfig
+  defaults: CiApiDefaults
+  requestTimeoutMs: number
+  log?: (message: string) => void
+}
+
+type NormalizedCall = {
+  args: string[]
+  options: Record<string, unknown>
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const toTrimmedString = (value: unknown): string =>
+  value === null || value === undefined ? '' : String(value).trim()
+
+const toPositiveInteger = (value: unknown): number | null => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return Math.floor(value)
+  }
+
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  const parsed = Number(trimmed)
+  if (!Number.isFinite(parsed) || parsed <= 0) return null
+  return Math.floor(parsed)
+}
+
+const splitArgsAndOptions = (rawArgs: unknown[]): NormalizedCall => {
+  if (rawArgs.length === 0 || !isRecord(rawArgs[rawArgs.length - 1])) {
+    return {
+      args: rawArgs.map((value) => String(value)),
+      options: {},
+    }
+  }
+
+  const last = rawArgs[rawArgs.length - 1] as Record<string, unknown>
+  return {
+    args: rawArgs.slice(0, -1).map((value) => String(value)),
+    options: last,
+  }
+}
+
+const buildApiBase = (host: string): string => {
+  const sanitizedHost = host.replace(/\/$/, '')
+  if (sanitizedHost.endsWith('/api/v1')) {
+    return sanitizedHost
+  }
+  return `${sanitizedHost}/api/v1`
+}
+
+const toQueryArray = (query: Record<string, string | number | boolean>): string[] =>
+  Object.entries(query).map(([key, value]) => `${key}=${value}`)
+
+const toHeaderRecord = (headers: string[]): Record<string, string> =>
+  Object.fromEntries(
+    headers
+      .map((entry) => {
+        const separatorIndex = entry.indexOf(':')
+        if (separatorIndex < 0) return null
+        const name = entry.slice(0, separatorIndex).trim()
+        const value = entry.slice(separatorIndex + 1).trim()
+        return [name, value]
+      })
+      .filter((entry): entry is [string, string] => Boolean(entry)),
+  )
+
+const fetchJson = async (
+  ctx: GitCiApiContext,
+  path: string[],
+  query: Record<string, string | number | boolean> = {},
+): Promise<{ status: number; ok: boolean; headers: Record<string, string>; body: unknown; url: string }> => {
+  const apiBase = buildApiBase(ctx.config.giteaHost)
+  const url = new URL(`${apiBase}/${path.join('/')}`)
+  for (const [key, value] of Object.entries(query)) {
+    url.searchParams.set(key, String(value))
+  }
+
+  const headersList: string[] = []
+  headersList.push('Accept: application/json')
+  if (ctx.config.giteaToken) {
+    headersList.push(`Authorization: token ${ctx.config.giteaToken}`)
+  }
+
+  ctx.log?.(`ci:http:request GET ${url.toString()}`)
+  const response = await fetch(url.toString(), { headers: toHeaderRecord(headersList) })
+  const responseHeaders: Record<string, string> = {}
+  try {
+    response.headers.forEach((value, key) => {
+      responseHeaders[key.toLowerCase()] = value
+    })
+  } catch {
+    // best effort
+  }
+
+  const contentType = response.headers.get('content-type') ?? ''
+  const text = await response.text().catch(() => '')
+  let parsed: unknown = text
+  if (contentType.toLowerCase().includes('application/json')) {
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      parsed = text
+    }
+  }
+
+  ctx.log?.(`ci:http:response GET ${url.toString()} -> ${response.status}`)
+  return {
+    status: response.status,
+    ok: response.ok,
+    headers: responseHeaders,
+    body: parsed,
+    url: url.toString(),
+  }
+}
+
+const resolveOwnerRepo = (
+  scope: { owner?: string; repo?: string },
+  defaults: CiApiDefaults,
+): { owner: string; repo: string } => {
+  const owner = scope.owner ?? defaults.defaultOwner
+  const repo = scope.repo ?? defaults.defaultRepo
+
+  if (!owner || !repo) {
+    throw new Error(
+      'Owner/repo is required. Pass owner and repo args or set defaultOwner/defaultRepo when creating the API.',
+    )
+  }
+
+  return { owner, repo }
+}
+
+type NormalizedCheckState = 'success' | 'failure' | 'pending'
+
+const normalizeGiteaStatusState = (raw: unknown): NormalizedCheckState => {
+  const value = toTrimmedString(raw).toLowerCase()
+  if (value === 'success') return 'success'
+  if (value === 'pending') return 'pending'
+  if (value === 'failure') return 'failure'
+  if (value === 'failed') return 'failure'
+  if (value === 'error') return 'failure'
+  if (value === 'cancelled' || value === 'canceled') return 'failure'
+  if (value === 'skipped') return 'success'
+  if (value === 'running' || value === 'in_progress' || value === 'queued' || value === 'waiting') return 'pending'
+  return 'pending'
+}
+
+const summarizeOverall = (states: NormalizedCheckState[]) => {
+  const total = states.length
+  const failed = states.filter((state) => state === 'failure').length
+  const pending = states.filter((state) => state === 'pending').length
+  const successful = states.filter((state) => state === 'success').length
+
+  const state: NormalizedCheckState =
+    failed > 0 ? 'failure' : pending > 0 ? 'pending' : total > 0 ? 'success' : 'success'
+
+  return { state, total, failed, pending, successful }
+}
+
+const listWorkflowFiles = async (
+  ctx: GitCiApiContext,
+  owner: string,
+  repo: string,
+): Promise<Array<{ id: string; name: string; path: string; state: string; url?: string; html_url?: string }>> => {
+  const directories = ['.gitea/workflows', '.github/workflows']
+  const workflows: Array<{ id: string; name: string; path: string; state: string; url?: string; html_url?: string }> = []
+
+  for (const directory of directories) {
+    const response = await fetchJson(ctx, ['repos', owner, repo, 'contents', directory])
+    if (!response.ok) {
+      continue
+    }
+
+    if (!Array.isArray(response.body)) {
+      continue
+    }
+
+    for (const entry of response.body) {
+      if (!isRecord(entry)) continue
+      const type = toTrimmedString(entry.type).toLowerCase()
+      if (type !== 'file') continue
+      const name = toTrimmedString(entry.name)
+      if (!name.toLowerCase().endsWith('.yml') && !name.toLowerCase().endsWith('.yaml')) continue
+      const path = toTrimmedString(entry.path) || `${directory}/${name}`
+
+      workflows.push({
+        id: path,
+        name,
+        path,
+        state: 'active',
+        ...(typeof entry.url === 'string' ? { url: entry.url } : {}),
+        ...(typeof entry.html_url === 'string' ? { html_url: entry.html_url } : {}),
+      })
+    }
+  }
+
+  const unique = new Map<string, { id: string; name: string; path: string; state: string; url?: string; html_url?: string }>()
+  for (const workflow of workflows) {
+    unique.set(workflow.id, workflow)
+  }
+  return [...unique.values()]
+}
+
+export const attachGitCiApi = (api: GitServiceApi, ctx: GitCiApiContext): void => {
+  const prChecks = async (...rawArgs: unknown[]): Promise<GitServiceApiExecutionResult> => {
+    if (ctx.config.platform !== 'GITEA') {
+      throw new Error(`pr.checks only supports GITEA platform, got ${ctx.config.platform}`)
+    }
+
+    const parsed = splitArgsAndOptions(rawArgs)
+    const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
+    const options = parsed.options
+
+    let owner: string | undefined
+    let repo: string | undefined
+    let prNumber: number | null = null
+
+    if (args.length >= 3) {
+      owner = args[0]
+      repo = args[1]
+      prNumber = toPositiveInteger(args[2])
+    } else if (args.length === 2) {
+      if (args[0].includes('/')) {
+        const split = args[0].split('/')
+        if (split.length === 2 && split[0] && split[1]) {
+          owner = split[0]
+          repo = split[1]
+          prNumber = toPositiveInteger(args[1])
+        }
+      }
+    } else if (args.length === 1) {
+      prNumber = toPositiveInteger(args[0])
+    }
+
+    if (!prNumber) {
+      prNumber = toPositiveInteger(
+        (options.prNumber ?? options.pr_number ?? options.number ?? options.pull ?? options.pull_number) as unknown,
+      )
+    }
+
+    if (!owner) {
+      owner = typeof options.owner === 'string' ? options.owner : undefined
+    }
+
+    if (!repo) {
+      repo = typeof options.repo === 'string' ? options.repo : undefined
+    }
+
+    const scope = resolveOwnerRepo({ owner, repo }, ctx.defaults)
+
+    if (!prNumber) {
+      throw new Error('PR number is required.')
+    }
+
+    const prResponse = await fetchJson(ctx, ['repos', scope.owner, scope.repo, 'pulls', String(prNumber)])
+    if (!prResponse.ok) {
+      return {
+        mapping: {
+          platform: 'GITEA',
+          featurePath: ['pr', 'checks'],
+          mappedPath: ['repos', scope.owner, scope.repo, 'pulls', String(prNumber)],
+          method: 'GET',
+          query: [],
+          headers: [],
+          apiBase: buildApiBase(ctx.config.giteaHost),
+          swaggerPath: '/repos/{owner}/{repo}/pulls/{index}',
+          mapped: true,
+          reason: 'Fetch PR for checks computation',
+        },
+        request: {
+          url: prResponse.url,
+          method: 'GET',
+          headers: {},
+          query: [],
+        },
+        response: {
+          headers: prResponse.headers,
+        },
+        status: prResponse.status,
+        ok: prResponse.ok,
+        body: prResponse.body,
+      }
+    }
+
+    const prBody = prResponse.body
+    const head = isRecord(prBody) ? prBody.head : null
+    const headSha =
+      toTrimmedString(isRecord(head) ? head.sha : null) ||
+      toTrimmedString(isRecord(prBody) ? prBody.head_sha : null) ||
+      toTrimmedString(isRecord(prBody) ? prBody.headSha : null)
+    const headBranch =
+      toTrimmedString(isRecord(head) ? head.ref : null) ||
+      toTrimmedString(isRecord(prBody) ? prBody.head_branch : null) ||
+      toTrimmedString(isRecord(prBody) ? prBody.headBranch : null)
+
+    if (!headSha) {
+      throw new Error('Unable to determine PR head SHA from pull request response.')
+    }
+
+    const [tasksResponse, statusesResponse] = await Promise.all([
+      fetchJson(ctx, ['repos', scope.owner, scope.repo, 'actions', 'tasks'], { limit: 50 }),
+      fetchJson(ctx, ['repos', scope.owner, scope.repo, 'statuses', headSha]),
+    ])
+
+    const actionRuns =
+      isRecord(tasksResponse.body) && Array.isArray(tasksResponse.body.workflow_runs)
+        ? (tasksResponse.body.workflow_runs as unknown[])
+        : []
+
+    const actionChecks = actionRuns
+      .filter((entry) => isRecord(entry))
+      .filter((entry) => toTrimmedString((entry as Record<string, unknown>).head_sha) === headSha)
+      .map((entry) => {
+        const record = entry as Record<string, unknown>
+        const state = normalizeGiteaStatusState(record.status)
+        const name =
+          toTrimmedString(record.name) ||
+          toTrimmedString(record.display_title) ||
+          toTrimmedString(record.workflow_id) ||
+          `run:${toTrimmedString(record.id)}`
+        const detailsUrl = toTrimmedString(record.url)
+        const runNumber = toPositiveInteger(record.run_number)
+        const jobId = toTrimmedString(record.id)
+        return {
+          source: 'actions' as const,
+          name,
+          state,
+          ...(detailsUrl ? { details_url: detailsUrl } : {}),
+          ...(runNumber ? { run_number: runNumber } : {}),
+          ...(jobId ? { job_id: jobId } : {}),
+          ...(typeof record.updated_at === 'string' ? { updated_at: record.updated_at } : {}),
+        }
+      })
+
+    const combinedState = isRecord(statusesResponse.body) ? normalizeGiteaStatusState(statusesResponse.body.state) : null
+    const commitStatuses =
+      isRecord(statusesResponse.body) && Array.isArray(statusesResponse.body.statuses)
+        ? (statusesResponse.body.statuses as unknown[])
+        : []
+
+    const statusChecks = commitStatuses
+      .filter((entry) => isRecord(entry))
+      .map((entry) => {
+        const record = entry as Record<string, unknown>
+        const name =
+          toTrimmedString(record.context) ||
+          toTrimmedString(record.name) ||
+          toTrimmedString(record.id) ||
+          'status'
+        const state = normalizeGiteaStatusState(record.status ?? record.state)
+        const detailsUrl = toTrimmedString(record.target_url ?? record.targetUrl)
+        return {
+          source: 'status' as const,
+          name,
+          state,
+          ...(detailsUrl ? { details_url: detailsUrl } : {}),
+          ...(typeof record.description === 'string' ? { description: record.description } : {}),
+          ...(typeof record.updated_at === 'string' ? { updated_at: record.updated_at } : {}),
+          ...(typeof record.created_at === 'string' ? { created_at: record.created_at } : {}),
+        }
+      })
+
+    const checks = [...actionChecks, ...statusChecks]
+    const states = checks.map((check) => check.state)
+    const overallBase = summarizeOverall(states)
+    const overall =
+      checks.length === 0 && (!tasksResponse.ok || !statusesResponse.ok)
+        ? { ...overallBase, state: 'pending' as const }
+        : overallBase
+
+    const body = {
+      pr: {
+        number: prNumber,
+        headSha,
+        ...(headBranch ? { headBranch } : {}),
+        ...(isRecord(prBody) && typeof prBody.html_url === 'string' ? { url: prBody.html_url } : {}),
+        ...(isRecord(prBody) && typeof prBody.title === 'string' ? { title: prBody.title } : {}),
+      },
+      overall: {
+        ...overall,
+        ...(combinedState ? { combined_state: combinedState } : {}),
+        ...(tasksResponse.ok ? {} : { actions_error: tasksResponse.body }),
+        ...(statusesResponse.ok ? {} : { statuses_error: statusesResponse.body }),
+      },
+      checks,
+      meta: {
+        actions_total_count: isRecord(tasksResponse.body) ? tasksResponse.body.total_count : undefined,
+      },
+    }
+
+    const mapping: GitApiFeatureMapping = {
+      platform: 'GITEA',
+      featurePath: ['pr', 'checks'],
+      mappedPath: ['repos', scope.owner, scope.repo, 'pulls', String(prNumber), 'checks'],
+      method: 'GET',
+      query: [],
+      headers: [],
+      apiBase: buildApiBase(ctx.config.giteaHost),
+      swaggerPath: '/repos/{owner}/{repo}/pulls/{index} + /actions/tasks + /statuses/{sha}',
+      mapped: true,
+      reason: 'Computed PR checks from actions tasks and commit statuses',
+    }
+
+    return {
+      mapping,
+      request: {
+        url: 'computed://repo/pr/checks',
+        method: 'GET',
+        headers: {},
+        query: [],
+      },
+      response: { headers: {} },
+      status: 200,
+      ok: true,
+      body,
+    }
+  }
+
+  const workflowList = async (...rawArgs: unknown[]): Promise<GitServiceApiExecutionResult> => {
+    if (ctx.config.platform !== 'GITEA') {
+      throw new Error(`workflow.list only supports GITEA platform, got ${ctx.config.platform}`)
+    }
+
+    const parsed = splitArgsAndOptions(rawArgs)
+    const args = parsed.args.map((value) => value.trim()).filter((value) => value.length > 0)
+    const options = parsed.options
+
+    let owner: string | undefined
+    let repo: string | undefined
+
+    if (args.length >= 2) {
+      owner = args[0]
+      repo = args[1]
+    } else if (args.length === 1 && args[0].includes('/')) {
+      const split = args[0].split('/')
+      if (split.length === 2 && split[0] && split[1]) {
+        owner = split[0]
+        repo = split[1]
+      }
+    }
+
+    if (!owner) {
+      owner = typeof options.owner === 'string' ? options.owner : undefined
+    }
+    if (!repo) {
+      repo = typeof options.repo === 'string' ? options.repo : undefined
+    }
+
+    const scope = resolveOwnerRepo({ owner, repo }, ctx.defaults)
+
+    const apiResponse = await fetchJson(ctx, ['repos', scope.owner, scope.repo, 'actions', 'workflows'])
+
+    const workflowsFromApi =
+      isRecord(apiResponse.body) && Array.isArray(apiResponse.body.workflows)
+        ? (apiResponse.body.workflows as unknown[])
+        : []
+
+    if (apiResponse.ok && workflowsFromApi.length > 0) {
+      return {
+        mapping: {
+          platform: 'GITEA',
+          featurePath: ['workflow', 'list'],
+          mappedPath: ['repos', scope.owner, scope.repo, 'actions', 'workflows'],
+          method: 'GET',
+          query: [],
+          headers: [],
+          apiBase: buildApiBase(ctx.config.giteaHost),
+          swaggerPath: '/repos/{owner}/{repo}/actions/workflows',
+          mapped: true,
+          reason: 'Gitea actions workflows API',
+        },
+        request: {
+          url: apiResponse.url,
+          method: 'GET',
+          headers: {},
+          query: [],
+        },
+        response: { headers: apiResponse.headers },
+        status: apiResponse.status,
+        ok: apiResponse.ok,
+        body: apiResponse.body,
+      }
+    }
+
+    const fallbackWorkflows = await listWorkflowFiles(ctx, scope.owner, scope.repo)
+    const fallbackBody = {
+      total_count: fallbackWorkflows.length,
+      workflows: fallbackWorkflows,
+      ...(apiResponse.ok ? {} : { api_error: apiResponse.body }),
+    }
+
+    return {
+      mapping: {
+        platform: 'GITEA',
+        featurePath: ['workflow', 'list'],
+        mappedPath: ['repos', scope.owner, scope.repo, 'actions', 'workflows'],
+        method: 'GET',
+        query: [],
+        headers: [],
+        apiBase: buildApiBase(ctx.config.giteaHost),
+        swaggerPath: '/repos/{owner}/{repo}/actions/workflows',
+        mapped: true,
+        reason: 'Fallback to repository workflow files when API returns empty',
+      },
+      request: {
+        url: apiResponse.url,
+        method: 'GET',
+        headers: {},
+        query: [],
+      },
+      response: { headers: apiResponse.headers },
+      status: apiResponse.ok ? 200 : apiResponse.status,
+      ok: true,
+      body: fallbackBody,
+    }
+  }
+
+  const root = api as Record<string, any>
+
+  // Override "workflow.list" if the platform adapter returns an empty list in Gitea environments.
+  root.workflow ??= {}
+  root.workflow.list = workflowList
+  root.repo ??= {}
+  root.repo.workflow ??= {}
+  root.repo.workflow.list = workflowList
+
+  // Override "pr.checks" to return a CI-friendly summary with per-check states.
+  root.pr ??= {}
+  root.pr.checks = prChecks
+  root.repo.pr ??= {}
+  root.repo.pr.checks = prChecks
+}